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/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}$/);
+  });
 });