fix(cli): survive ktx.yaml version skew and derive repo ownership from disk (#293)

* fix(cli): survive ktx.yaml version skew and derive repo ownership from disk

Loading ktx.yaml is now tolerant of keys this ktx version does not
recognize: they are stripped from the in-memory config (the file on disk
is never rewritten) and reported by ktx status as non-blocking warnings,
while invalid values on recognized fields still fail hard. Repo
ownership is derived from observed state (a .git directory plus a root
ktx.yaml) instead of a ktx.managed git-config marker, so projects
created by any past or future ktx classify identically. initKtxProject
now runs an explicit foreign-repo pre-check and writes ktx.yaml before
initializing git, so an interrupted init leaves only recoverable
residue instead of a bare .git misread as foreign.

* style(cli): trim comment blocks to constraint-only notes

* docs(agents): require constraint-only code comments

packages/cli/test/context/core/git.service.init-identity.test.ts

@@ -6,10 +6,10 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import type { KtxCoreConfig } from '../../../src/context/core/config.js';
 import { GitService } from '../../../src/context/core/git.service.js';
 
-// Regression for bootstrapping a marked ktx repo on a machine with no configured
+// Regression for bootstrapping a ktx-owned repo on a machine with no configured
 // git identity. A foreign pre-existing repo is rejected by the ownership rule;
-// this test covers the still-valid path where the repo is already ktx-managed
-// but has no HEAD yet.
+// this test covers the still-valid path where the repo is already ktx's own
+// (root ktx.yaml present) but has no HEAD yet.
 describe('GitService.initialize without a configured git identity', () => {
   let repoDir: string;
   let homeDir: string;
@@ -58,11 +58,7 @@ describe('GitService.initialize without a configured git identity', () => {
     }
 
     execFileSync('git', ['init'], { cwd: repoDir, env: process.env, stdio: 'ignore' });
-    execFileSync('git', ['config', '--local', 'ktx.managed', 'true'], {
-      cwd: repoDir,
-      env: process.env,
-      stdio: 'ignore',
-    });
+    await writeFile(join(repoDir, 'ktx.yaml'), 'connections: {}\n', 'utf-8');
   });
 
   afterEach(async () => {

packages/cli/test/context/core/git.service.repo-isolation.test.ts

@@ -56,10 +56,11 @@ describe('GitService repository ownership', () => {
     git(parentDir, ['commit', '-m', 'parent baseline']);
     const parentHeadBefore = git(parentDir, ['rev-parse', 'HEAD']);
 
+    await writeFile(join(projectDir, 'ktx.yaml'), 'connections: {}\n', 'utf-8');
     const service = new GitService(coreConfig(projectDir));
     await service.onModuleInit();
 
-    expect(git(projectDir, ['config', '--local', '--get', 'ktx.managed'])).toBe('true');
+    expect(await classifyKtxRepoOwnership(projectDir)).toBe('ktx-managed');
     expect(git(parentDir, ['rev-parse', 'HEAD'])).toBe(parentHeadBefore);
     expect(await realpath(git(projectDir, ['rev-parse', '--show-toplevel']))).toBe(await realpath(projectDir));
 
@@ -83,18 +84,22 @@ describe('GitService repository ownership', () => {
     expect(await readFile(join(projectDir, '.git', 'config'), 'utf-8')).toBe(configBefore);
   });
 
-  it('rejects a gitfile at the project dir as foreign', async () => {
+  it('rejects a gitfile at the project dir as foreign even when a ktx.yaml sits beside it', async () => {
+    // A linked worktree is never ktx's own repo, whatever files live in it.
     const projectDir = join(tempDir, 'linked-worktree');
     await mkdir(projectDir, { recursive: true });
     await writeFile(join(projectDir, '.git'), 'gitdir: ../actual.git\n', 'utf-8');
+    await writeFile(join(projectDir, 'ktx.yaml'), 'connections: {}\n', 'utf-8');
 
     const service = new GitService(coreConfig(projectDir));
 
     await expect(service.onModuleInit()).rejects.toThrow(/already a git repository that ktx did not create/);
   });
 
-  it('accepts a marked ktx repo and does not create a second bootstrap commit', async () => {
+  it('re-initializes an existing ktx project repo without a second bootstrap commit', async () => {
     const projectDir = join(tempDir, 'owned');
+    await mkdir(projectDir, { recursive: true });
+    await writeFile(join(projectDir, 'ktx.yaml'), 'connections: {}\n', 'utf-8');
     const service = new GitService(coreConfig(projectDir));
     await service.onModuleInit();
     const before = await service.revParseHead();
@@ -103,7 +108,37 @@ describe('GitService repository ownership', () => {
     await second.onModuleInit();
 
     expect(await second.revParseHead()).toBe(before);
-    expect(git(projectDir, ['config', '--local', '--get', 'ktx.managed'])).toBe('true');
+  });
+
+  it('accepts a project created by an older ktx: repo history plus an untracked root ktx.yaml', async () => {
+    // Older projects have ktx commit history and an uncommitted root ktx.yaml
+    // (it holds secret refs); the on-disk file is still the ownership signal.
+    const projectDir = join(tempDir, 'legacy');
+    await mkdir(join(projectDir, '.ktx'), { recursive: true });
+    git(projectDir, ['init']);
+    await writeFile(join(projectDir, '.ktx', '.gitignore'), 'secrets/\n', 'utf-8');
+    git(projectDir, ['add', '.ktx/.gitignore']);
+    git(projectDir, ['commit', '-m', 'Initialize KTX project: legacy']);
+    await writeFile(join(projectDir, 'ktx.yaml'), 'connections: {}\n', 'utf-8');
+    const headBefore = git(projectDir, ['rev-parse', 'HEAD']);
+
+    const service = new GitService(coreConfig(projectDir));
+    await expect(service.onModuleInit()).resolves.toBeUndefined();
+
+    expect(await service.revParseHead()).toBe(headBefore);
+    expect(git(projectDir, ['status', '--short'])).toContain('?? ktx.yaml');
+  });
+
+  it('still rejects a user repo with history but no root ktx.yaml', async () => {
+    const projectDir = join(tempDir, 'app-repo');
+    await mkdir(projectDir, { recursive: true });
+    git(projectDir, ['init']);
+    await writeFile(join(projectDir, 'README.md'), '# App\n', 'utf-8');
+    git(projectDir, ['add', 'README.md']);
+    git(projectDir, ['commit', '-m', 'app baseline']);
+
+    const service = new GitService(coreConfig(projectDir));
+    await expect(service.onModuleInit()).rejects.toThrow(/already a git repository that ktx did not create/);
   });
 });
 
@@ -132,9 +167,11 @@ describe('classifyKtxRepoOwnership', () => {
     expect(await classifyKtxRepoOwnership(nestedDir)).toBe('unowned');
   });
 
-  it('reports ktx-managed for a repo ktx initialized', async () => {
+  it('reports ktx-managed for a repo with a root ktx.yaml (even untracked)', async () => {
     const dir = join(tempDir, 'owned');
-    await new GitService(coreConfig(dir)).onModuleInit();
+    await mkdir(dir, { recursive: true });
+    git(dir, ['init']);
+    await writeFile(join(dir, 'ktx.yaml'), 'connections: {}\n', 'utf-8');
     expect(await classifyKtxRepoOwnership(dir)).toBe('ktx-managed');
   });
 
@@ -145,6 +182,16 @@ describe('classifyKtxRepoOwnership', () => {
     expect(await classifyKtxRepoOwnership(dir)).toBe('foreign');
   });
 
+  it('reports foreign for a non-ktx repo that has commits but no ktx.yaml', async () => {
+    const dir = join(tempDir, 'app');
+    await mkdir(dir, { recursive: true });
+    git(dir, ['init']);
+    await writeFile(join(dir, 'README.md'), '# App\n', 'utf-8');
+    git(dir, ['add', 'README.md']);
+    git(dir, ['commit', '-m', 'baseline']);
+    expect(await classifyKtxRepoOwnership(dir)).toBe('foreign');
+  });
+
   it('reports foreign for a .git file (linked worktree)', async () => {
     const dir = join(tempDir, 'linked');
     await mkdir(dir, { recursive: true });

packages/cli/test/context/core/git.service.test.ts

@@ -1,4 +1,3 @@
-import { execFileSync } from 'node:child_process';
 import { mkdir, mkdtemp, readFile, realpath, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
@@ -27,8 +26,12 @@ describe('GitService', () => {
       },
     };
 
+    // Mirror production: initKtxProject writes ktx.yaml before the git repo is
+    // initialized (the root ktx.yaml is the ownership signal) and commits it.
+    await writeFile(join(tempDir, 'ktx.yaml'), 'connections: {}\n', 'utf-8');
     service = new GitService(coreConfig);
     await service.onModuleInit();
+    await service.commitFile('ktx.yaml', 'Initialize KTX project', 'Test', 'test@example.com');
   });
 
   afterEach(async () => {
@@ -61,14 +64,9 @@ describe('GitService', () => {
 
   describe('cold-start bootstrap commit', () => {
     it('writes an empty commit on init so HEAD always resolves', async () => {
-      // beforeEach already ran onModuleInit() against an empty temp dir.
+      // beforeEach already ran onModuleInit() against a fresh temp dir.
       const head = await service.revParseHead();
       expect(head).toMatch(/^[0-9a-f]{40}$/);
-      const marker = execFileSync('git', ['config', '--local', '--get', 'ktx.managed'], {
-        cwd: tempDir,
-        encoding: 'utf-8',
-      }).trim();
-      expect(marker).toBe('true');
     });
 
     it('does not double-commit when re-initialized', async () => {

packages/cli/test/context/project/config.test.ts

@@ -91,25 +91,61 @@ connections:
     });
   });
 
-  it('rejects removed auto-commit config keys', () => {
-    expect(() =>
-      parseKtxProjectConfig(`
+  it('tolerates unrecognized keys left over from older ktx versions', () => {
+    // A project written by an older ktx still carries fields that newer ktx
+    // removed (storage.git.auto_commit, the top-level memory block). Loading
+    // must not brick every command — the keys are dropped, not rejected.
+    const config = parseKtxProjectConfig(`
 storage:
   git:
     ${removedAutoCommitKey}: false
-`),
-    ).toThrow(new RegExp(`storage\\.git\\.${removedAutoCommitKey}`));
-
-    expect(() =>
-      parseKtxProjectConfig(`
 memory:
   ${removedAutoCommitKey}: false
-`),
-    ).toThrow(/memory/);
+`);
+    expect(config.storage.git).toEqual({ author: 'ktx <ktx@example.com>' });
+    expect(config).not.toHaveProperty('memory');
+  });
 
-    expect(validateKtxProjectConfig(`storage:\n  git:\n    ${removedAutoCommitKey}: false\n`)).toMatchObject({
+  it('reports dropped keys as warnings, not blocking errors', () => {
+    const validation = validateKtxProjectConfig(
+      `storage:\n  git:\n    ${removedAutoCommitKey}: false\nmemory:\n  ${removedAutoCommitKey}: false\n`,
+    );
+    expect(validation.ok).toBe(true);
+    expect(validation.issues).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ path: `storage.git.${removedAutoCommitKey}`, severity: 'warning' }),
+        expect.objectContaining({ path: 'memory', severity: 'warning' }),
+      ]),
+    );
+  });
+
+  it('tolerates llm.models roles this ktx version does not define', () => {
+    // Enum-keyed record entries surface as zod `invalid_key`, not
+    // `unrecognized_keys` — a distinct path from unknown object fields.
+    const config = parseKtxProjectConfig(`
+llm:
+  models:
+    default: claude-sonnet-4-6
+    summarizer_from_the_future: some-model
+`);
+    expect(config.llm.models).toEqual({ default: 'claude-sonnet-4-6' });
+
+    const validation = validateKtxProjectConfig(
+      'llm:\n  models:\n    default: claude-sonnet-4-6\n    summarizer_from_the_future: some-model\n',
+    );
+    expect(validation.ok).toBe(true);
+    expect(validation.issues).toEqual([
+      expect.objectContaining({ path: 'llm.models.summarizer_from_the_future', severity: 'warning' }),
+    ]);
+  });
+
+  it('still rejects malformed values on recognized fields', () => {
+    // Tolerance is only for unknown keys. A bad value on a known field is a
+    // real misconfiguration and must still fail loudly.
+    expect(() => parseKtxProjectConfig('storage:\n  state: mariadb\n')).toThrow(/storage\.state/);
+    expect(validateKtxProjectConfig('storage:\n  state: mariadb\n')).toMatchObject({
       ok: false,
-      issues: [expect.objectContaining({ path: `storage.git.${removedAutoCommitKey}` })],
+      issues: [expect.objectContaining({ path: 'storage.state', severity: 'error' })],
     });
   });
 
@@ -471,41 +507,34 @@ scan:
     expect(() => parseKtxProjectConfig(yaml)).toThrow(/scan\.relationships\.validationBudget/);
   });
 
-  it('rejects unsupported local LLM and embedding fields', () => {
+  it('tolerates unsupported nested fields and surfaces them as warnings', () => {
+    // Unknown nested keys (whether obsolete or a typo) are dropped rather than
+    // bricking the command; ktx status surfaces them via validate warnings.
     expect(() =>
       parseKtxProjectConfig(`
 ingest:
   llm:
     backend: anthropic
 `),
-    ).toThrow('Unsupported ingest.llm: unknown field');
+    ).not.toThrow();
 
-    expect(() =>
-      parseKtxProjectConfig(`
+    const validation = validateKtxProjectConfig(`
+ingest:
+  llm:
+    backend: anthropic
 scan:
   enrichment:
     backend: gateway
-`),
-    ).toThrow('Unsupported scan.enrichment.backend: unknown field');
-
-    expect(() =>
-      parseKtxProjectConfig(`
-scan:
-  enrichment:
-    mode: llm
-    llm:
-      backend: gateway
-`),
-    ).toThrow('Unsupported scan.enrichment.llm: unknown field');
-
-    expect(() =>
-      parseKtxProjectConfig(`
-ingest:
-  embeddings:
-    provider: gateway
-    max_batch_size: 32
-`),
-    ).toThrow('Unsupported ingest.embeddings.provider');
+ingest_embeddings_typo:
+  provider: gateway
+`);
+    expect(validation.ok).toBe(true);
+    expect(validation.issues).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ path: 'ingest.llm', severity: 'warning' }),
+        expect.objectContaining({ path: 'scan.enrichment.backend', severity: 'warning' }),
+      ]),
+    );
   });
 
   it('rejects gateway embedding configs', () => {
@@ -552,13 +581,19 @@ scan:
     });
   });
 
-  it('rejects unknown top-level fields under strict mode', () => {
+  it('tolerates an unknown top-level field but warns about it', () => {
+    // A typo like `storrage` no longer bricks every command; it is dropped and
+    // reported as a warning so the user can notice the setting did not apply.
     expect(() =>
       parseKtxProjectConfig(`
 storrage:
   state: sqlite
 `),
-    ).toThrow(/Unsupported storrage/);
+    ).not.toThrow();
+
+    const validation = validateKtxProjectConfig('storrage:\n  state: sqlite\n');
+    expect(validation.ok).toBe(true);
+    expect(validation.issues).toEqual([expect.objectContaining({ path: 'storrage', severity: 'warning' })]);
   });
 });
 
@@ -598,7 +633,7 @@ scan:
     const result = validateKtxProjectConfig('- nope\n');
     expect(result).toEqual({
       ok: false,
-      issues: [{ path: '', message: 'ktx.yaml must contain a YAML object' }],
+      issues: [{ path: '', message: 'ktx.yaml must contain a YAML object', severity: 'error' }],
     });
   });
 });

packages/cli/test/context/project/project.test.ts

@@ -1,5 +1,5 @@
 import { execFileSync } from 'node:child_process';
-import { mkdir, mkdtemp, readFile, realpath, rm, stat } from 'node:fs/promises';
+import { mkdir, mkdtemp, readFile, realpath, rm, stat, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
@@ -61,6 +61,31 @@ describe('ktx local project runtime', () => {
     });
   });
 
+  it('loads a ktx.yaml carrying fields removed in a newer ktx without mutating it on disk', async () => {
+    const projectDir = join(tempDir, 'warehouse');
+    await initKtxProject({ projectDir });
+
+    // Simulate a project written by a different ktx: inject unknown fields into
+    // the existing storage.git block and as a top-level memory block.
+    const configPath = join(projectDir, 'ktx.yaml');
+    const original = await readFile(configPath, 'utf-8');
+    const withStaleKeys = `${original.replace(
+      'author: ktx <ktx@example.com>',
+      'auto_commit: true\n    author: ktx <ktx@example.com>',
+    )}memory:\n  auto_commit: true\n`;
+    await writeFile(configPath, withStaleKeys, 'utf-8');
+
+    const loaded = await loadKtxProject({ projectDir });
+
+    // Loading tolerates the unknown fields instead of throwing: they are stripped
+    // from the in-memory config so every command still runs.
+    expect(loaded.config).not.toHaveProperty('memory');
+    expect(loaded.config.storage.git).toEqual({ author: 'ktx <ktx@example.com>' });
+
+    // The file on disk stays exactly as the user wrote it.
+    await expect(readFile(configPath, 'utf-8')).resolves.toBe(withStaleKeys);
+  });
+
   it('initializes a dedicated git repo at the project dir even when nested inside an enclosing repo', async () => {
     // A ktx project dir living below an existing git working tree (e.g. an analytics
     // subfolder of an app repo). ktx must own its own repo rooted at the project dir,
@@ -95,4 +120,40 @@ describe('ktx local project runtime', () => {
       configPath: join(projectDir, 'ktx.yaml'),
     });
   });
+
+  it('refuses to initialize inside a foreign git repo and writes nothing into it', async () => {
+    // A user's own repo: has history, no root ktx.yaml. The guard must reject
+    // before writing ktx.yaml — that file would make the repo classify as ktx's.
+    const projectDir = join(tempDir, 'app-repo');
+    await mkdir(projectDir, { recursive: true });
+    execFileSync('git', ['init', '-q'], { cwd: projectDir });
+    await writeFile(join(projectDir, 'README.md'), '# App\n', 'utf-8');
+    execFileSync('git', ['add', 'README.md'], { cwd: projectDir });
+    execFileSync(
+      'git',
+      ['-c', 'user.name=App', '-c', 'user.email=app@example.com', 'commit', '-q', '-m', 'baseline'],
+      { cwd: projectDir },
+    );
+
+    await expect(initKtxProject({ projectDir })).rejects.toThrow(
+      /already a git repository that ktx did not create/,
+    );
+
+    await expect(stat(join(projectDir, 'ktx.yaml'))).rejects.toMatchObject({ code: 'ENOENT' });
+    const tracked = execFileSync('git', ['ls-files'], { cwd: projectDir, encoding: 'utf-8' });
+    expect(tracked).not.toContain('ktx.yaml');
+  });
+
+  it('recovers an init interrupted after ktx.yaml was written but before git finished', async () => {
+    // ktx.yaml is written before git init, so the only crash residue is a valid
+    // ktx.yaml with no `.git` — the next load must re-init, not reject as foreign.
+    const projectDir = join(tempDir, 'half-init');
+    await initKtxProject({ projectDir });
+    await rm(join(projectDir, '.git'), { recursive: true, force: true });
+
+    const loaded = await loadKtxProject({ projectDir });
+
+    await expect(stat(join(projectDir, '.git'))).resolves.toBeDefined();
+    expect(await loaded.git.revParseHead()).toMatch(/^[0-9a-f]{40}$/);
+  });
 });

packages/cli/test/doctor.test.ts

@@ -9,6 +9,8 @@ import {
   type DoctorCheck,
 } from '../src/doctor.js';
 
+const removedAutoCommitKey = ['auto', 'commit'].join('_');
+
 function makeIo() {
   let stdout = '';
   let stderr = '';
@@ -353,17 +355,10 @@ describe('runKtxDoctor', () => {
     expect(parsed.projectDir).toBe(tempDir);
   });
 
-  it('prints schema issues and exits 1 when ktx.yaml fails Zod validation', async () => {
+  it('prints schema issues and exits 1 when ktx.yaml has an invalid value', async () => {
     await writeFile(
       join(tempDir, 'ktx.yaml'),
-      [
-        'storrage:',
-        '  state: sqlite',
-        'ingest:',
-        '  llm:',
-        '    backend: anthropic',
-        '',
-      ].join('\n'),
+      ['storage:', '  state: mariadb', ''].join('\n'),
       'utf-8',
     );
     const testIo = makeIo();
@@ -379,15 +374,14 @@ describe('runKtxDoctor', () => {
     const out = testIo.stdout();
     expect(out).toContain('ktx status');
     expect(out).toContain('Config');
-    expect(out).toContain('Unsupported storrage: unknown field');
-    expect(out).toContain('Unsupported ingest.llm: unknown field');
+    expect(out).toContain('storage.state');
     expect(out).toContain('ktx.yaml');
   });
 
-  it('emits structured JSON when ktx.yaml fails Zod validation', async () => {
+  it('emits structured JSON when ktx.yaml has an invalid value', async () => {
     await writeFile(
       join(tempDir, 'ktx.yaml'),
-      ['storrage: {}', ''].join('\n'),
+      ['storage:', '  state: mariadb', ''].join('\n'),
       'utf-8',
     );
     const testIo = makeIo();
@@ -407,7 +401,7 @@ describe('runKtxDoctor', () => {
     };
     expect(parsed.error).toBe('invalid_config');
     expect(parsed.projectDir).toBe(tempDir);
-    expect(parsed.issues.some((issue) => issue.path === 'storrage')).toBe(true);
+    expect(parsed.issues.some((issue) => issue.path === 'storage.state')).toBe(true);
   });
 
   it('shows a Config row labelled "ktx.yaml schema valid" on the happy path', async () => {
@@ -490,6 +484,49 @@ describe('runKtxDoctor', () => {
     delete process.env.OPENAI_API_KEY;
   });
 
+  it('exits 0 and shows a Config warn row when ktx.yaml carries stale unknown fields', async () => {
+    // The default `ktx status` path (command: 'project') must keep working on a
+    // ktx.yaml written by a different ktx version: unknown fields surface as an
+    // ignored-fields warning on the Config row, never as a failure.
+    process.env.ANTHROPIC_API_KEY = 'test-key'; // pragma: allowlist secret
+    await writeFile(
+      join(tempDir, 'ktx.yaml'),
+      [
+        'connections:',
+        '  warehouse:',
+        '    driver: sqlite',
+        '    path: ./warehouse.db',
+        'llm:',
+        '  provider:',
+        '    backend: anthropic',
+        '  models:',
+        '    default: claude-sonnet-4-5',
+        'storage:',
+        '  git:',
+        `    ${removedAutoCommitKey}: false`,
+        'memory: {}',
+        '',
+      ].join('\n'),
+      'utf-8',
+    );
+    const testIo = makeIo();
+
+    await expect(
+      runKtxDoctor(
+        { command: 'project', projectDir: tempDir, outputMode: 'plain', inputMode: 'disabled' },
+        testIo.io,
+        {},
+      ),
+    ).resolves.toBe(0);
+
+    const out = testIo.stdout();
+    expect(out).toContain('Config');
+    expect(out).toContain('ktx.yaml schema valid · 2 ignored fields');
+    expect(out).toContain(`⚠ Unsupported storage.git.${removedAutoCommitKey}: unknown field (ignored)`);
+    expect(out).toContain('⚠ Unsupported memory: unknown field (ignored)');
+    delete process.env.ANTHROPIC_API_KEY;
+  });
+
   it('reports Claude Code auth failures and ignored prompt-caching fields in project doctor output', async () => {
     await writeFile(
       join(tempDir, 'ktx.yaml'),
@@ -795,17 +832,10 @@ describe('runKtxDoctor', () => {
       expect(JSON.parse(testIo.stdout())).toEqual({ ok: true, projectDir: tempDir });
     });
 
-    it('prints schema issues and exits 1 when ktx.yaml fails Zod validation', async () => {
+    it('prints schema issues and exits 1 when ktx.yaml has an invalid value', async () => {
       await writeFile(
         join(tempDir, 'ktx.yaml'),
-        [
-          'storrage:',
-          '  state: sqlite',
-          'ingest:',
-          '  llm:',
-          '    backend: anthropic',
-          '',
-        ].join('\n'),
+        ['storage:', '  state: mariadb', ''].join('\n'),
         'utf-8',
       );
       const testIo = makeIo();
@@ -819,14 +849,13 @@ describe('runKtxDoctor', () => {
       ).resolves.toBe(1);
 
       const out = testIo.stdout();
-      expect(out).toContain('Unsupported storrage: unknown field');
-      expect(out).toContain('Unsupported ingest.llm: unknown field');
+      expect(out).toContain('storage.state');
     });
 
     it('emits structured JSON issues when validation fails', async () => {
       await writeFile(
         join(tempDir, 'ktx.yaml'),
-        ['storrage: {}', ''].join('\n'),
+        ['storage:', '  state: mariadb', ''].join('\n'),
         'utf-8',
       );
       const testIo = makeIo();
@@ -841,7 +870,75 @@ describe('runKtxDoctor', () => {
 
       const parsed = JSON.parse(testIo.stdout()) as { error: string; issues: Array<{ path: string }> };
       expect(parsed.error).toBe('invalid_config');
-      expect(parsed.issues.some((issue) => issue.path === 'storrage')).toBe(true);
+      expect(parsed.issues.some((issue) => issue.path === 'storage.state')).toBe(true);
+    });
+
+    it('tolerates unknown fields, reporting them as warnings and exiting 0', async () => {
+      await writeFile(
+        join(tempDir, 'ktx.yaml'),
+        ['storrage:', '  state: sqlite', 'ingest:', '  llm:', '    backend: anthropic', ''].join('\n'),
+        'utf-8',
+      );
+      const testIo = makeIo();
+
+      await expect(
+        runKtxDoctor(
+          { command: 'validate', projectDir: tempDir, outputMode: 'plain', inputMode: 'disabled' },
+          testIo.io,
+          {},
+        ),
+      ).resolves.toBe(0);
+
+      const out = testIo.stdout();
+      expect(out).toContain('storrage');
+      expect(out).toContain('ingest.llm');
+      expect(out).toContain('ignored');
+    });
+
+    it('emits structured JSON warnings for unknown fields and exits 0', async () => {
+      await writeFile(
+        join(tempDir, 'ktx.yaml'),
+        ['storrage: {}', ''].join('\n'),
+        'utf-8',
+      );
+      const testIo = makeIo();
+
+      await expect(
+        runKtxDoctor(
+          { command: 'validate', projectDir: tempDir, outputMode: 'json', inputMode: 'disabled' },
+          testIo.io,
+          {},
+        ),
+      ).resolves.toBe(0);
+
+      const parsed = JSON.parse(testIo.stdout()) as { ok: boolean; warnings: Array<{ path: string; severity: string }> };
+      expect(parsed.ok).toBe(true);
+      expect(parsed.warnings.some((warning) => warning.path === 'storrage' && warning.severity === 'warning')).toBe(true);
+    });
+
+    it('renders unknown fields as ignored even when a real error blocks', async () => {
+      // Mixed file: a bad value on a recognized field (blocks) plus a stale
+      // unknown key (ignored). Only the error counts as a schema issue; the
+      // warning keeps the ⚠ ignored-field treatment instead of a misleading ✗.
+      await writeFile(
+        join(tempDir, 'ktx.yaml'),
+        ['storage:', '  state: mariadb', 'memory: {}', ''].join('\n'),
+        'utf-8',
+      );
+      const testIo = makeIo();
+
+      await expect(
+        runKtxDoctor(
+          { command: 'validate', projectDir: tempDir, outputMode: 'plain', inputMode: 'disabled' },
+          testIo.io,
+          {},
+        ),
+      ).resolves.toBe(1);
+
+      const out = testIo.stdout();
+      expect(out).toContain('ktx.yaml has 1 schema issue · 1 ignored field');
+      expect(out).toContain('✗ storage.state');
+      expect(out).toContain('⚠ Unsupported memory: unknown field (ignored)');
     });
 
     it('prints the missing-project message and exits 1 when ktx.yaml is absent', async () => {