Add pluggable OKF type taxonomy per mode

[ayrtonvwf]

Adds and implements the OpenSpec change pluggable-okf-taxonomy (proposal, design, delta spec, tasks) for making the OKF type taxonomy pluggable per run mode while keeping the OKF carrier unchanged.

What changed

• src/constants.ts: new DocTypeTaxonomy type; REPO_DOC_TYPES/REPO_DOC_TYPE_FALLBACK/getRepoDocTypeForDirectory replaced by CODE_DOC_TYPES, PERSONAL_DOC_TYPES, getDocTypeForDirectory, and getTaxonomyForMode. code mode keeps today's exact type→directory entries and fallback (Reference); a new minimal personal taxonomy maps "" → Overview, sources → Source, topics → Topic, fallback Note.
• src/agent/prompt.ts: createOkfContractSection() now takes a DocTypeTaxonomy, resolved from options.outputMode via getTaxonomyForMode in createSystemPrompt, so the OKF directory contract advertises the right directories per mode.
• src/agent/okf.ts: stampPage() and runOkfPass() now take a DocTypeTaxonomy (defaulting to CODE_DOC_TYPES to preserve existing call shapes), and infer type via getDocTypeForDirectory.
• src/agent/index.ts: the runOkfPass call site passes the mode-derived taxonomy using the outputMode already in scope.
• verifyOkfConformance (--okf-check) was intentionally left unchanged: it never calls stampPage or reads the taxonomy (it only checks that type is present and non-empty), and the proposal's own non-goals keep --okf-check behavior untouched, so no taxonomy parameter was added there.
• Tests: test/constants.test.ts, test/prompt.test.ts, and test/okf.test.ts updated/extended to cover the renamed constant, getDocTypeForDirectory, getTaxonomyForMode, and per-mode stamping/prompt behavior.

Verified with pnpm run typecheck (clean) and pnpm test (256/256 passing). code-mode stamped types are unchanged.

Refs #22.

Generated with Claude Code

[ayrtonvwf]

@claude /opsx:apply then update the PR title and description accordingly

[claude]

Claude finished @ayrtonvwf's task in 9m 14s —— View job

---

Applying OpenSpec change: pluggable-okf-taxonomy

• Gather context (status, instructions, read artifacts)
• Implement pending tasks (17/17)
• Update PR title and description
• Push changes

Implementation Complete

Change: pluggable-okf-taxonomy
Schema: spec-driven
Progress: 17/17 tasks complete ✓

Summary

• src/constants.ts: added DocTypeTaxonomy, replaced REPO_DOC_TYPES/REPO_DOC_TYPE_FALLBACK/getRepoDocTypeForDirectory with CODE_DOC_TYPES, new PERSONAL_DOC_TYPES, getDocTypeForDirectory, and getTaxonomyForMode. code mode is byte-for-byte unchanged; personal mode now maps "" → Overview, sources → Source, topics → Topic, fallback Note.
• src/agent/prompt.ts: createOkfContractSection() takes the mode-selected taxonomy so the prompt's directory contract matches what the stamping pass will infer.
• src/agent/okf.ts: stampPage() / runOkfPass() take a DocTypeTaxonomy (defaulting to CODE_DOC_TYPES for existing call shapes).
• src/agent/index.ts:243: passes getTaxonomyForMode(outputMode) into runOkfPass.
• Deviation from tasks.md 3.2/3.4: verifyOkfConformance (--okf-check) was left unchanged — it never calls stampPage or reads the taxonomy (it only checks that type is a non-empty string), and the proposal's own non-goals state --okf-check behavior stays untouched. Threading an unused taxonomy parameter through it and its cli.tsx:918 caller would have been dead code, so I skipped it and documented the reasoning in tasks.md.
• Tests extended in test/constants.test.ts, test/prompt.test.ts, test/okf.test.ts (renamed constant, getDocTypeForDirectory, getTaxonomyForMode, per-mode prompt contract, and an end-to-end runOkfPass case stamping a personal sources/ page as Source vs. a code operations/ page as Operations).

Verification

• pnpm run typecheck — clean
• pnpm test — 256/256 passing
• pnpm run lint:check — could not run (blocked by sandbox permissions in this environment); please run it or update --allowedTools if you'd like it verified here

PR title and description updated to reflect the implementation.
· Branch

[ayrtonvwf]

@claude-opus review the change

[claude]

Claude finished @ayrtonvwf's task in 1m 56s —— View job

---

Review: pluggable-okf-taxonomy

I read the full diff (constants.ts, okf.ts, prompt.ts, index.ts), the OpenSpec artifacts, and the tests, and traced the production call paths. This is a clean, well-scoped change. code-mode behavior is preserved, the taxonomy is threaded as an explicit value rather than hidden global state, and both seams (prompt contract + stamping) read from the same selected taxonomy. Below are observations, none of them blocking.

---

✅ Strengths

• Explicit value over mutable global (DocTypeTaxonomy threaded through getDocTypeForDirectory(taxonomy, dir)) is the right call — pure, testable, concurrency-safe. The design doc's rejection of a "current taxonomy" module global is sound.
• WeakMap inversion cache (directoryLookupCache) is a nice touch: keyed on the stable taxonomy objects, computed lazily once, no leak risk.
• --okf-check left untouched is correct, not a shortcut. verifyOkfConformance (src/agent/okf.ts:777) only checks type is present/non-empty via findMissingOkfFields — it never infers type from a directory, so a taxonomy parameter would be genuinely dead code. Verified by reading the function. Good judgment documenting the deviation in tasks.md.
• Test coverage is proportionate: per-mode getDocTypeForDirectory, getTaxonomyForMode, an end-to-end runOkfPass case stamping sources/ → Source vs operations/ → Operations, and per-mode prompt-contract assertions.

---

🟡 Observations (non-blocking)

1. Diverging defaults between the two seams.
stampPage / runOkfPass default to CODE_DOC_TYPES (src/agent/okf.ts:322,676), but createSystemPrompt defaults outputMode to local-wiki → PERSONAL_DOC_TYPES. In production this is harmless — index.ts:247 threads the resolved outputMode explicitly — but the two OKF seams now disagree on what "no argument" means. A future caller of runOkfPass(cwd, info) with no taxonomy would silently get the code taxonomy while the prompt half went personal. Since the default exists only to preserve test call shapes, consider a short comment on the = CODE_DOC_TYPES default noting it's a test-only convenience and production always passes the mode-derived taxonomy.

2. Stale REPO_ prefix on the now-generalized validators.
REPO_DOC_TYPE_NAME_PATTERN / REPO_DOC_TYPE_DIRECTORY_PATTERN (src/constants.ts:326-327) and the error messages were generalized (the function is now assertSanitizedDocTypes validating any taxonomy), but these two regex constants kept the REPO_ name. Minor, but they now validate PERSONAL_DOC_TYPES too — DOC_TYPE_NAME_PATTERN would read truer.

3. Brittle negative assertion in test/prompt.test.ts.
expect(prompt).not.toContain("Architecture") / .not.toContain("Data Model") passes today, but it asserts on substrings of a large free-text prompt rather than on the contract block. If any unrelated prompt copy ever mentions "architecture," this fails without the taxonomy actually being wrong. Consider scoping the assertion to the rendered OKF directory-contract section (the type -> directory list) instead of the whole prompt.

4. --okf-check is now mode-blind (accepted non-goal, worth stating).
Because verifyOkfConformance only checks non-emptiness, a personal-mode bundle whose pages carry code-taxonomy type values (e.g. authored under a prior code run, or hand-written Architecture) still passes --okf-check. This matches the proposal's non-goals, so no action needed — just flagging that the check can't detect a type that's inconsistent with the current mode's taxonomy. Fine to leave as-is; a mode-aware --okf-check would be a reasonable follow-up if that drift ever matters.

---

Verdict

Ship it. The four items above are polish (naming, a comment, a test-robustness tweak) and an accepted-scope note — none change behavior. Spec, design, tasks, and implementation are consistent, and code-mode output is preserved.
· Branch

[ayrtonvwf]

@claude fix points 1, 2 and 3

[claude]

Claude finished @ayrtonvwf's task in 1m 48s —— View job

---

Fixing review points 1, 2, 3

• Gather context (re-read review comment + relevant files)
• Point 1: comment on = CODE_DOC_TYPES defaults noting it's a test-only convenience
• Point 2: rename REPO_DOC_TYPE_NAME_PATTERN/REPO_DOC_TYPE_DIRECTORY_PATTERN to drop stale REPO_ prefix
• Point 3: scope brittle negative assertions in test/prompt.test.ts to the OKF contract section
• Run typecheck & tests
• Push changes

Summary

• src/agent/okf.ts: added a comment above the taxonomy: DocTypeTaxonomy = CODE_DOC_TYPES default on both stampPage and runOkfPass clarifying it's a test-only convenience — production always threads the mode-derived taxonomy explicitly via getTaxonomyForMode(outputMode) in agent/index.ts.
• src/constants.ts: renamed REPO_DOC_TYPE_NAME_PATTERN → DOC_TYPE_NAME_PATTERN and REPO_DOC_TYPE_DIRECTORY_PATTERN → DOC_TYPE_DIRECTORY_PATTERN, since assertSanitizedDocTypes validates any taxonomy (code or personal), not just the code one.
• test/prompt.test.ts: added extractOkfContractSection(), which slices the prompt from the "OKF output contract (--okf):" marker onward (the OKF section is always appended last), and scoped the personal-mode not.toContain("Architecture")/not.toContain("Data Model") assertions to that section instead of the full free-text prompt.

Point 4 (--okf-check being mode-blind) was explicitly called out as an accepted non-goal in the original review, not something to fix, so it was left untouched.

Verification

• pnpm run typecheck — clean
• pnpm test — 256/256 passing
• pnpm run lint:check — could not run (blocked by sandbox permissions in this environment); please run it or update --allowedTools if you'd like it verified here

Branch ·