TECH.md — Code-intelligence integration into the SDLC workflow

TECH.md — Code-intelligence integration into the SDLC workflow

§1 Context

Linked spec

This TECH.md implements the 16 numbered Behavior invariants and 21-cell coverage matrix in docs/specs/id-23-code-intelligence-integration/PRODUCT.md. Read PRODUCT.md first — this document does not restate user-facing behaviour; it translates each PRODUCT invariant into a concrete file edit, anchor convention, and freshness-guard assertion.

Tooling already on disk (the integration’s prerequisites)

The three code-intelligence tools are installed and operational:

• gitnexus — MCP server registered in the user’s MCP catalogue (tools surface as mcp__gitnexus__*). KH-corpus index reports 36,955 symbols / 54,750 relationships / 300 execution flows. Project-global directive at .gitnexus/CLAUDE.md (file is on disk in both knowledge-hub/ and knowledge-hub-production-readiness/ worktrees but is untracked / gitignored — see §6 asymmetry note).
• ast-dataflow — TypeScript-corpus CLI at bun scripts/ast-dataflow-cli.ts <query>, 12 queries + 9 cross-tool patterns. Project-global directive at .ast-dataflow/CLAUDE.md (file is tracked: git ls-files .ast-dataflow/CLAUDE.md → present).
• ccc — semantic codebase index CLI (ccc search, ccc describe, ccc guide). Skill body lives in the user’s global skill catalogue at ~/.agents/skills/ccc/SKILL.md; there is no project-local .ccc/ directive (per PRODUCT row-7×ccc N/A justification, P-OQ-3 default).

Both .gitnexus/CLAUDE.md and .ast-dataflow/CLAUDE.md are imported into the root CLAUDE.md via the @./.gitnexus/CLAUDE.md / @./.ast-dataflow/CLAUDE.md directives at lines 9–10. The import mechanism works regardless of git-tracking state (Claude reads referenced files at session bootstrap), so the untracked .gitnexus/ file is functionally live for all main-session orchestration; the tracking gap matters only for the freshness-guard’s regex anchoring (§4).

Current state per surface (S61 WP5 baseline: 0 of 63 cells populated)

The audit context cited in Task ID-23’s priority_note measured 63 of 63 tool-integration cells MISSING. This TECH treats every surface as needing additive edits — no removal of existing content. Per-surface current state, with line references against current HEAD (commit e8213bdb):

#	Surface	Current code-intel references	Lines / sections to amend (additive)
1	.claude/skills/workflow-orchestration/SKILL.md (463 L)	0	Insert new “Code-intelligence baseline” section after ## Skill routing (current line 327)
2a	.claude/agents/task-planner.md (376 L)	0	Insert “Code-intelligence orientation (pre-spec-write)” subsection under “Operating principles” (current line ~94)
2b	.claude/skills/write-product-spec/SKILL.md (~325 L)	0	Add ### Code-intelligence orientation subsection to “Before writing” (current line 69)
3a	.claude/agents/task-executor.md (316 L)	0	Insert “Pre-edit impact + pre-commit detect-changes” bullets in “Operating principles” + amend Step 4 Implement
3b	.claude/skills/implement-subtask/SKILL.md (273 L)	0	Amend Step 1 (Read the brief), Step 4 (Commit), Step 5 (Journal block schema)
4	.claude/agents/task-checker.md (401 L)	0	Add scope-containment and rename-sweep rows to “Standard audit axes” + extend axis_scores enum
5a	.claude/agents/workflow-curator.md (259 L)	0	Add “Code-intelligence pre-grep” bullet in “Operating principles” + amend Step 3 (Run triage-finding) flow
5b	.claude/skills/triage-finding/SKILL.md (306 L)	0	Add “Caller-count pre-grep” sub-step in Step 1
6	.claude/skills/write-tech-spec/SKILL.md (~180 L)	0	Add ### Code-intelligence orientation subsection at top of “Research before writing” (current line 49) + extend “Knowledge Hub conventions” list with “Code intelligence” row
7a	.gitnexus/CLAUDE.md (~55 L, untracked)	Self-contained tool guide	Add ## Propagation discipline section before ## CLI table
7b	.ast-dataflow/CLAUDE.md (44 L, tracked)	Self-contained tool guide	Add ## Propagation discipline section before final “ast-dataflow does not cover Python or SQL files” section
(Inv 12)	docs/reference/skill-routing-map.md (85 L)	Existing 10-row tilt table	Append 11th row: “Refactor / Rename / Type-evolution”
(Inv 15)	.claude/skills/workflow-orchestration/references/lifecycle-detail.md (90 L)	0	Amend {N.2} PRODUCT and {N.3} TECH sub-sections with cite-the-impact-verdict requirement

Eleven surface files in total when counting the auxiliary docs/reference/ and references/ files inside surface boundaries (Task ID-23 description names this count explicitly).

Why the integration matters now

The three tools exist and are already invoked by Liam in interactive sessions. The failure mode the S61 WP5 audit captured is that sub-agents (Planner / Executor / Checker / Curator) never see the tool-discipline instructions because the Orchestrator’s dispatch briefs don’t name them. Adding the project-global directive imports to root CLAUDE.md does not propagate — sub-agents that load skills via fresh contexts inherit .claude/skills/<skill>/SKILL.md and .claude/agents/<agent>.md content, not the orchestrator’s CLAUDE.md gotcha bullets. The integration’s intent is to encode the tool-discipline expectation in skill / agent bodies so it survives context resets.

Mirror to ID-19.4 (hook propagation): same shape, different artefact — there it was a PreToolUse hook in .claude/settings.json that failed to propagate because the file wasn’t on main; here it’s tool-discipline instruction blocks that fail to propagate because no skill body cites them. The freshness guard (§4) is the structural mitigation: on every PR, CI asserts the anchors exist on the surface files. If any anchor goes missing, the build fails with a directive pointing back to this spec.

§2 Proposed changes per invariant (one-to-one with PRODUCT.md)

Every PRODUCT invariant maps to exactly one row. The “Mechanism” column names the file edit; the “Test verification” column names how the freshness guard (§4) or runtime behaviour confirms the edit landed.

PRODUCT inv	Proposed change	Mechanism	Test verification
Inv 1 Orchestrator brief composition	Add “Code-intelligence baseline” section to workflow-orchestration/SKILL.md enumerating the matrix of tools per role + the file-extension allowlist that classifies a dispatch as “code-touching”	update-skill workflow-orchestration — insert section after ## Skill routing, with named anchor <!-- code-intel:baseline-start --> … <!-- code-intel:baseline-end -->	Guard: regex-assert anchor presence + ≥1 mention of each of gitnexus_impact, gitnexus_detect_changes, gitnexus_query, ast-dataflow, ccc inside the anchor block
Inv 2 Planner brief template carries gitnexus orientation verbatim	Add “Planner brief code-intel block” inside <!-- code-intel:planner-block-start --> … <!-- code-intel:planner-block-end --> anchors in workflow-orchestration/SKILL.md AND in task-planner.md “Operating principles”	update-skill workflow-orchestration (block 1) + agent-development task-planner (block 2). Block content per PRODUCT inv 2 paraphrase: invoke gitnexus_query + gitnexus_context, cite findings in spec Context/Problem	Guard: both anchor pairs exist with non-empty content matching /gitnexus_query/ and /gitnexus_context/
Inv 3 Executor brief template carries pre-edit + pre-commit gitnexus discipline	Add “Executor brief code-intel block” inside <!-- code-intel:executor-block-start --> … <!-- code-intel:executor-block-end --> anchors in workflow-orchestration/SKILL.md AND in task-executor.md “Operating principles”	update-skill workflow-orchestration (block 1) + agent-development task-executor (block 2). Content: pre-edit gitnexus_impact per modified symbol + pre-commit gitnexus_detect_changes	Guard: both anchor pairs present, content matches /gitnexus_impact/ AND /gitnexus_detect_changes/
Inv 4 Code-intelligence baseline section in workflow-orchestration	The Inv 1 section is the implementation. Per PRODUCT, the section enumerates: (a) tool-matrix per role, (b) verbatim instruction blocks, (c) freshness-guard expectations, (d) file-extension allowlist	Inv 1 mechanism. Add a “References to” sub-bullet linking out to the per-role anchor blocks (Inv 2/3/7/8)	Guard: section header ## Code-intelligence baseline exists; section contains four sub-headers matching the four PRODUCT inv-4 enumerated items
Inv 5 Planners cite gitnexus orientation in spec artefacts	Add ### Code-intelligence orientation subsection to write-product-spec/SKILL.md “Before writing” AND to write-tech-spec/SKILL.md “Research before writing”, instructing Planners to either cite gitnexus findings or note “gitnexus orientation: no existing symbols match — greenfield surface”	update-skill write-product-spec + update-skill write-tech-spec. Each subsection has anchor <!-- code-intel:planner-citation-start --> … <!-- code-intel:planner-citation-end --> and includes the greenfield-disclaimer wording (per P-OQ-4 default)	Guard: both skill files contain Code-intelligence orientation subsection header AND the greenfield-disclaimer string
Inv 6 Executors run pre-edit gitnexus_impact per modified symbol and record verdicts in the journal	Amend implement-subtask/SKILL.md Step 5 (Journal) block schema to add two lines: **Blast radius:** <verdict> (<caller-count> callers) and **Scope verified:** gitnexus_detect_changes matched expected symbol set	update-skill implement-subtask — amend the journal-block-schema code-fence at current line ~140	Guard: journal-block schema in implement-subtask/SKILL.md contains both literal strings
Inv 7 Checkers run gitnexus_detect_changes + audit scope-containment per commit	Add scope-containment and rename-sweep rows to task-checker.md “Standard audit axes” + extend axis_scores enum in JSON output schema. Add anchor <!-- code-intel:checker-axes-start --> … <!-- code-intel:checker-axes-end --> around the table extension	agent-development task-checker — insert axes rows + amend JSON schema literal at current line ~310	Guard: anchor present; table contains scope-containment row naming gitnexus_detect_changes; table contains rename-sweep row naming ast-dataflow Q1/Q2/Q3; JSON schema literal axis_scores includes "scope-containment" and "rename-sweep" keys
Inv 8 Curators run gitnexus caller counts as deterministic roadmap-vs-backlog signal	Add “Caller-count pre-grep” sub-step to triage-finding/SKILL.md Step 1 + add corresponding “Operating principle” bullet in workflow-curator.md. Anchor <!-- code-intel:curator-pregrep-start --> … <!-- code-intel:curator-pregrep-end --> in triage-finding/SKILL.md	update-skill triage-finding + agent-development workflow-curator. Content per PRODUCT inv 8: gitnexus_context({name: '<symbolName>'}) + ast-dataflow callers <symbolName> + ≥10 callers across ≥3 modules threshold	Guard: anchor present in triage-finding/SKILL.md; literal strings gitnexus_context AND ast-dataflow callers AND "≥ 10" present inside anchor block
Inv 9 write-tech-spec skill body prescribes first-line code-intelligence research pattern	Amend write-tech-spec/SKILL.md “Research before writing” — make ### Code-intelligence orientation the FIRST subsection (before reading product spec); extend “Knowledge Hub conventions” list with a “Code intelligence” row pointing to .gitnexus/CLAUDE.md and .ast-dataflow/CLAUDE.md	update-skill write-tech-spec — insert subsection at top of “Research before writing”; append list row	Guard: write-tech-spec/SKILL.md “Research before writing” first subsection title === Code-intelligence orientation; conventions list contains Code intelligence row referencing both directive files
Inv 10 Project-global directive files carry propagation-discipline bullets	Add ## Propagation discipline section to BOTH .gitnexus/CLAUDE.md AND .ast-dataflow/CLAUDE.md, mirroring ID-19.4 hook propagation rule. Content: sub-agents inherit only when Orchestrator brief names the tools; escalate if dispatched without instructions on code-touching brief	Manual Edit (per Task ID-23 constraint: update-skill / agent-development apply ONLY to .claude/skills/* and .claude/agents/* — NOT to project-global directive files). Anchor <!-- code-intel:propagation-start --> … <!-- code-intel:propagation-end --> in both files	Guard: both files contain ## Propagation discipline header AND anchor pair AND mention Inv 2, Inv 3, Inv 7, Inv 8 in the body
Inv 11 Freshness guard catches integration regressions	Author __tests__/docs/code-intelligence-integration.test.ts Vitest test (per P-OQ-2 default). Test reads each surface file and asserts presence of named anchors + required strings per Invariants 1–10 + 12	Author the test file directly (no skill invocation — test-driven-development skill governs the write, but the file itself is a new Vitest spec). Use parseTaskListWithWarnings pattern? No — this is a docs guard, not task-list. Read files via fs.readFile() + regex-assert anchors	Guard self-tests: the test passes against the post-Task-23-implementation HEAD; the test fails when any anchor pair is removed (run on each CI PR via the existing Vitest matrix in .github/workflows/ci.yml)
Inv 12 skill-routing-map.md gains Refactor / Rename / Type-evolution tilt row	Append 11th row to “Tilt routing table” in docs/reference/skill-routing-map.md. Required: gitnexus-refactoring, gitnexus-impact-analysis, ast-dataflow, ast-dataflow-rename-sweep, ast-dataflow-call-chain-pin. Conditional: code-simplification, test-driven-development. Anti-patterns per PRODUCT inv 12 wording	Manual Edit (this is a reference doc, not a skill body — update-skill does not apply). Bump Last verified header to authoring date (DD/MM/YYYY UK format)	Guard: row 11 of the tilt table contains tilt === "Refactor / Rename / Type-evolution" AND all five named Required skills appear in the row’s “Required skills” cell
Inv 13 Skill-routing-map location ratified — current docs/reference/ retained	No file moves. Validate that docs/reference/skill-routing-map.md still exists AND no .claude/skills/workflow-orchestration/references/skill-routing-map.md exists. Tracked-reference-doc registration: per S249 (commit 4d4524d3), the lib/docs/tracked-reference-docs.ts registry was REMOVED — current freshness posture is “manually-bumped headers”. Inv 13’s “tracked in lib/docs/tracked-reference-docs.ts” line is a PRODUCT-side claim that no longer matches reality (see T-OQ-1)	No file edit required (default branch satisfies). Validation only	Guard: file existence check for both paths (positive assertion on docs/reference/, negative assertion on .claude/skills/workflow-orchestration/references/)
Inv 14 commit-commands integration note in implement-subtask Step 4	Amend implement-subtask/SKILL.md Step 4 (Commit) with paragraph “Pre-commit scope check (manual gate): Before invoking commit-commands, invoke gitnexus_detect_changes() to verify the affected symbol set matches the Subtask’s expected file-ownership boundary. If detect_changes reports symbols outside the boundary, STOP and escalate to the Orchestrator — this is scope creep and the Checker will FAIL the audit otherwise. Until tooling automates this gate, the manual invocation is the canonical guard.”	update-skill implement-subtask — insert paragraph immediately before the commit-message code-fence at current line ~117	Guard: implement-subtask/SKILL.md contains literal string Pre-commit scope check (manual gate) AND gitnexus_detect_changes()
Inv 15 lifecycle-detail.md carries cite-the-impact-verdict requirement for Planner sections	Amend workflow-orchestration/references/lifecycle-detail.md {N.2} PRODUCT and {N.3} TECH sub-sections — each gets a one-paragraph requirement: “The Planner cites the gitnexus_impact verdict for any symbol the spec slice mandates be modified — verdict level (LOW / MEDIUM / HIGH / CRITICAL), caller count, and the names of the top-3 affected execution flows.”	update-skill workflow-orchestration — the references/ subfile is part of the skill bundle, so update-skill covers it. Insert paragraph after PRODUCT and TECH sub-section headers at current lines ~15 and ~19	Guard: lifecycle-detail.md contains literal string cites the gitnexus_impact verdict in both PRODUCT and TECH sub-sections
Inv 16 Tool-discipline scope is bounded by file-extension allowlist	The Inv 4 baseline section (point d) carries the allowlist verbatim. Content: in-scope file extensions (.ts/.tsx/.js/.jsx/.mjs/.cjs) + directories (app/, lib/, components/, hooks/, contexts/, types/, scripts/); out-of-scope (.md/.mdx, ledger .json, .py, .sql); mixed-dispatch rule (TS portion governs)	Same update-skill workflow-orchestration invocation as Inv 4. Anchor <!-- code-intel:allowlist-start --> … <!-- code-intel:allowlist-end --> inside the baseline section	Guard: anchor present; literal strings for each file extension + each directory listed in PRODUCT Inv 16

One-to-one mapping verified. Every PRODUCT invariant (1 through 16) has exactly one Proposed-change row. No invariant maps to multiple rows (single-implementation discipline); no row implements multiple invariants (the apparent exception is Inv 1 + Inv 4 + Inv 16 all landing in the same workflow-orchestration baseline section — but each invariant maps to a distinct anchor block within that section, preserving the 1:1 discipline).

§3 Per-file edit sequence

The implementation Subtasks {23.4+} will dispatch one Executor per logical surface file (per {23.3} PLAN; {23.2} TECH proposes the natural grouping in §7). Sequential dispatch is mandated per Task ID-23 Constraints (update-skill / agent-development stall pattern observed S59 + S60 — three skill body edits in flight at once stalled both dispatch sessions). The order below resolves inter-file dependencies: later edits reference content authored in earlier edits.

Topological dependency order

Why this order: The freshness guard (Inv 11) regex-asserts anchors and content across all 11 surface files. The guard test itself must be authored after all surface files land, otherwise it fails CI on every intermediate commit. Within the surface files, the Inv 4 baseline section in workflow-orchestration/SKILL.md enumerates the matrix that the per-role agent bodies reference — so the baseline section must land before the per-role anchors, or the per-role anchors will reference content that doesn’t exist yet. The freshness guard tolerates the intermediate state because each PR ships one logical surface; the guard fails only when an existing anchor is removed, not when a future anchor is missing.

Order	File	Why this order	Depends on
1	.claude/skills/workflow-orchestration/SKILL.md	Inv 1 + 2 (orch-side) + 3 (orch-side) + 4 + 16 — the canonical baseline section. Authored first so per-role agents reference an existing anchor target	—
2	.claude/skills/workflow-orchestration/references/lifecycle-detail.md	Inv 15 — Planner cite-the-impact-verdict requirement. Part of the workflow-orchestration skill bundle; lands in same Subtask if file ownership permits, or immediately after #1	#1 (same skill bundle)
3	.claude/agents/task-planner.md	Inv 2 (agent-side) — Planner brief code-intel block	#1 (references baseline anchor names)
4	.claude/skills/write-product-spec/SKILL.md	Inv 5 (PRODUCT side) — code-intelligence orientation subsection	#3 (task-planner agent references the skill subsection)
5	.claude/skills/write-tech-spec/SKILL.md	Inv 5 (TECH side) + Inv 9 — code-intelligence orientation as first-line research pattern + conventions list extension	#3 + #4 (same surface, parallel skill files)
6	.claude/agents/task-executor.md	Inv 3 (agent-side) — Executor brief code-intel block	#1 (references baseline anchor names)
7	.claude/skills/implement-subtask/SKILL.md	Inv 6 (journal block schema) + Inv 14 (Step 4 commit gate)	#6 (task-executor agent references the skill steps)
8	.claude/agents/task-checker.md	Inv 7 — scope-containment + rename-sweep audit axes + JSON schema extension	#1 (references baseline anchor) + #6/#7 (Executor journal block schema is the source of the verdicts the Checker audits)
9	.claude/agents/workflow-curator.md	Inv 8 (agent-side) — caller-count pre-grep operating principle	#1 (references baseline anchor)
10	.claude/skills/triage-finding/SKILL.md	Inv 8 (skill-side) — Caller-count pre-grep sub-step in Step 1	#9 (workflow-curator agent references the skill sub-step)
11	.gitnexus/CLAUDE.md	Inv 10 — Propagation discipline section. Manual Edit, not update-skill (project-global directive file, untracked)	#1 (references Inv 2/3/7/8 by number, which must exist in #1’s anchors)
12	.ast-dataflow/CLAUDE.md	Inv 10 — Propagation discipline section. Manual Edit (tracked project-global directive)	#1 (same as #11)
13	docs/reference/skill-routing-map.md	Inv 12 — Refactor / Rename / Type-evolution tilt row. Manual Edit (reference doc, not skill body)	— (independent surface, no dependency on baseline anchors)
14	__tests__/docs/code-intelligence-integration.test.ts	Inv 11 — freshness-guard Vitest test. Authored LAST so all asserted anchors exist	All of #1–#13

Inter-file reference patterns

Two patterns recur:

• Anchor-name reference (no copy): Per-role agent files (task-planner.md, task-executor.md, task-checker.md, workflow-curator.md) reference the workflow-orchestration baseline section by name (e.g. “see Code-intelligence baseline, workflow-orchestration/SKILL.md”) but do not copy the block contents. This avoids the propagation problem (single source of truth). The verbatim instruction blocks (Inv 2/3) are duplicated by design — once in workflow-orchestration/SKILL.md for the Orchestrator’s lookup, once in the per-role agent file for the sub-agent’s lookup.
• Skill-body anchor-block discipline: Each anchor pair (e.g. <!-- code-intel:planner-block-start --> … <!-- code-intel:planner-block-end -->) contains exactly one block of guidance. Anchors are HTML comments (invisible in rendered markdown but regex-anchorable). Anchor naming convention: code-intel:<role>-<purpose>. All 11 anchor pairs enumerated in §4.

§4 Freshness-guard implementation (P-OQ-2 default: Vitest under __tests__/docs/)

Why Vitest over pre-commit hook

P-OQ-2 default is Vitest test under __tests__/docs/code-intelligence-integration.test.ts with CI enforcement. Three reasons (recommended default — explicit in §10 T-OQ-2):

1. Avoids the rejected pattern. The reference-doc-edit-coupled-freshness.test.ts pre-commit-coupled freshness guard was removed S249 (commit 4d4524d3) because the doc maintenance burden outweighed the catch-rate benefit. Re-introducing a pre-commit hook would resurrect the rejected pattern. A Vitest test in the CI matrix carries less friction because it lives alongside other docs guards (backlog-schema-roundtrip.test.ts, roadmap-roundtrip.test.ts) and runs only on PR.
2. --no-verify bypass. Pre-commit hooks can be bypassed with --no-verify. CLAUDE.md forbids this for sub-agents, but the bypass risk is real on direct Liam commits. Vitest in CI cannot be bypassed without merging a red build.
3. Sandbox compatibility. Sub-agent worktrees inherit .claude/settings.json from the PRIMARY tree (per ID-19.4 hook-propagation gotcha). A pre-commit hook would need to land on main first AND be tested against every sub-agent dispatch context — the same complexity that motivated ID-19.4’s Tier 2.2 hook migration. A Vitest test avoids this entirely.

Guard file location and shape

Location: __tests__/docs/code-intelligence-integration.test.ts

Shape (skeleton — Subtask {23.4-final} authors the full body):

import { describe, it, expect } from 'vitest';
import { readFile } from 'node:fs/promises';
import { existsSync } from 'node:fs';

const REQUIRED_ANCHORS: ReadonlyArray<{
  file: string;
  anchorStart: string;
  anchorEnd: string;
  requiredContent: ReadonlyArray<string | RegExp>;
}> = [
  {
    file: '.claude/skills/workflow-orchestration/SKILL.md',
    anchorStart: '<!-- code-intel:baseline-start -->',
    anchorEnd: '<!-- code-intel:baseline-end -->',
    requiredContent: [
      /gitnexus_impact/,
      /gitnexus_detect_changes/,
      /gitnexus_query/,
      /ast-dataflow/,
      /ccc/,
    ],
  },
  {
    file: '.claude/skills/workflow-orchestration/SKILL.md',
    anchorStart: '<!-- code-intel:planner-block-start -->',
    anchorEnd: '<!-- code-intel:planner-block-end -->',
    requiredContent: [/gitnexus_query/, /gitnexus_context/, /spec's Context|Problem/],
  },
  // ... 11 more anchor specs per §4-anchor-inventory below
];

describe('code-intelligence integration anchors', () => {
  for (const spec of REQUIRED_ANCHORS) {
    it(`${spec.file} contains ${spec.anchorStart} … ${spec.anchorEnd}`, async () => {
      expect(existsSync(spec.file)).toBe(true);
      const body = await readFile(spec.file, 'utf8');
      expect(body).toContain(spec.anchorStart);
      expect(body).toContain(spec.anchorEnd);
      const start = body.indexOf(spec.anchorStart) + spec.anchorStart.length;
      const end = body.indexOf(spec.anchorEnd);
      expect(end).toBeGreaterThan(start);
      const block = body.slice(start, end);
      for (const required of spec.requiredContent) {
        if (typeof required === 'string') {
          expect(block).toContain(required);
        } else {
          expect(block).toMatch(required);
        }
      }
    });
  }

  it('skill-routing-map retains canonical location and tilt row 11', async () => {
    expect(existsSync('docs/reference/skill-routing-map.md')).toBe(true);
    expect(existsSync('.claude/skills/workflow-orchestration/references/skill-routing-map.md')).toBe(false);
    const map = await readFile('docs/reference/skill-routing-map.md', 'utf8');
    expect(map).toMatch(/Refactor \/ Rename \/ Type-evolution/);
    expect(map).toMatch(/gitnexus-refactoring/);
    expect(map).toMatch(/ast-dataflow-rename-sweep/);
  });

  it('task-checker JSON schema includes scope-containment and rename-sweep axes', async () => {
    const body = await readFile('.claude/agents/task-checker.md', 'utf8');
    expect(body).toMatch(/"scope-containment":/);
    expect(body).toMatch(/"rename-sweep":/);
  });
});

Anchor inventory (the freshness-guard’s truth table)

#	File	Anchor pair	Required content inside
1	workflow-orchestration/SKILL.md	code-intel:baseline-start/end	/gitnexus_impact/, /gitnexus_detect_changes/, /gitnexus_query/, /ast-dataflow/, /ccc/
2	workflow-orchestration/SKILL.md	code-intel:planner-block-start/end	/gitnexus_query/, /gitnexus_context/, `/spec’s Context
3	workflow-orchestration/SKILL.md	code-intel:executor-block-start/end	/gitnexus_impact/, /gitnexus_detect_changes/, /HIGH or CRITICAL/
4	workflow-orchestration/SKILL.md	code-intel:allowlist-start/end	/\.ts/, /\.tsx/, /app\//, /lib\//, /scripts\//, /\.md/, /\.py/, /\.sql/ (mix of in/out-of-scope listings)
5	task-planner.md	code-intel:planner-block-start/end	(same as #2 — duplicated by design)
6	task-executor.md	code-intel:executor-block-start/end	(same as #3)
7	task-checker.md	code-intel:checker-axes-start/end	/scope-containment/, /rename-sweep/, /gitnexus_detect_changes/, /ast-dataflow.*Q1.*Q2.*Q3/
8	triage-finding/SKILL.md	code-intel:curator-pregrep-start/end	/gitnexus_context/, /ast-dataflow callers/, /≥ 10/, /≥ 3 modules/
9	write-product-spec/SKILL.md	code-intel:planner-citation-start/end	/Code-intelligence orientation/, /greenfield surface/
10	write-tech-spec/SKILL.md	code-intel:planner-citation-start/end	/Code-intelligence orientation/, /greenfield surface/
11	.gitnexus/CLAUDE.md	code-intel:propagation-start/end	/Propagation discipline/, /Inv 2/, /Inv 3/, /Inv 7/, /Inv 8/
12	.ast-dataflow/CLAUDE.md	code-intel:propagation-start/end	(same as #11)

12 anchor pairs (11 unique pairs + 1 duplicate by-design for the role-agent mirroring).

Baseline-acknowledgement strategy

The guard is strict from PR day 1 — no baseline ratchet, no “TODO” tolerance. Every anchor in the inventory must exist or the CI build fails. Two consequences:

• The freshness-guard test (__tests__/docs/code-intelligence-integration.test.ts) is authored in the LAST Subtask of the Task ID-23 chain (after all surface files land). Authoring it earlier would fail every intermediate commit.
• If a future change removes an anchor (e.g. someone runs update-skill and the regeneration drops the anchor block), the next PR fails with a directive pointing back to this spec. The directive in the test failure message: "Anchor <code-intel:X-start>/<code-intel:X-end> missing from <file>. Restore via update-skill / agent-development per docs/specs/id-23-code-intelligence-integration/TECH.md §3."

update-skill / agent-development anchor-preservation discipline

update-skill regenerates SKILL.md bodies from internal LLM reasoning — there is a real risk that anchor pairs get clobbered on regeneration cycles. Mitigation pattern (encoded in the dispatch brief for every Subtask that invokes update-skill):

“The skill file MUST retain all <!-- code-intel:*-start --> … <!-- code-intel:*-end --> anchor pairs verbatim. If update-skill produces output that drops any anchor pair, do NOT commit — re-invoke update-skill with the anchor preservation requirement in the instruction prompt, OR fall back to manual Edit for the anchor-insertion step.”

This shifts the anchor-preservation burden onto the dispatch brief (Planner’s responsibility at {23.4} PLAN-time), not onto the freshness guard. The guard is the backstop, not the primary defense.

§5 Skill / agent body-edit pattern

Which mechanism per surface

Per Task ID-23 Constraints, the body-edit mechanism is gated by surface type:

Surface type	Files	Mechanism	Rationale
Skill body	.claude/skills/<skill>/SKILL.md	update-skill skill	Per Task constraint; ensures frontmatter + structure-validation hooks fire
Skill bundle ref file	.claude/skills/<skill>/references/*.md	update-skill (covers bundle)	Same skill mechanism (bundle is atomic)
Agent body	.claude/agents/<agent>.md	agent-development skill	Per Task constraint; ensures frontmatter + example-block structure preserved
Project-global directive	.gitnexus/CLAUDE.md, .ast-dataflow/CLAUDE.md	Manual Edit	NOT a skill body; the Task constraint applies to .claude/skills/* and .claude/agents/* only
Reference doc	docs/reference/skill-routing-map.md	Manual Edit	Liam-facing lookup table; not a skill body. UK English Last verified header bump expected in same commit
Test spec	__tests__/docs/code-intelligence-integration.test.ts	Manual Write (new file)	New Vitest test file, no skill governs the body

Skill descriptions (from the loaded catalogue)

• update-skill — “Create or update skills by generating, editing, or refining SKILL.md files in this repository. Use when authoring new skills or revising the structure, frontmatter, or guidance for existing ones.”
• agent-development — “Use when the user asks to ‘create an agent’, ‘add an agent’, ‘write a subagent’, ‘agent frontmatter’, ‘when to use description’, ‘agent examples’, ‘agent tools’, ‘agent colors’, ‘autonomous agent’, or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.”

Both skills already exist in the project’s loaded catalogue. No new skill authoring is required for the Task ID-23 implementation Subtasks — update-skill and agent-development are the existing mechanisms.

Sequential-dispatch constraint (S59 + S60 stall pattern)

Per Task ID-23 description: three observed update-skill / agent-development stalls in S59 + S60 with parallel dispatches. The pattern: two or more Executor dispatches running update-skill simultaneously caused both to stall at the LLM-regeneration step. Root cause not fully diagnosed but the empirical workaround is one skill body edit per Executor brief, sequential dispatch only. The {23.4} PLAN’s decomposition (§7 below) respects this — one Subtask = one surface file = one body-edit invocation.

§6 Two CLAUDE.md edit asymmetry — and the third tool’s absence

.gitnexus/CLAUDE.md is untracked; .ast-dataflow/CLAUDE.md is tracked

Verified via git ls-files .gitnexus/ .ast-dataflow/:

.ast-dataflow/CLAUDE.md

.gitnexus/CLAUDE.md is NOT in the git index. The file exists on disk in both the primary knowledge-hub/ worktree and the knowledge-hub-production-readiness/ worktree (both have identical 3,099-byte content, last-modified 19/05/2026 12:04:51), but neither copy is tracked. The import directive in root CLAUDE.md:

**Import GitNexus and AST Dataflow development workflow commands and guidelines, treat as
if import is in the main CLAUDE.md file.** @./.gitnexus/CLAUDE.md
@./.ast-dataflow/CLAUDE.md

works regardless of tracking — Claude resolves the path on each session bootstrap. The asymmetry has three implementation consequences:

1. Inv 10 edits to .gitnexus/CLAUDE.md will NOT appear in git diff until the file is git add-ed. The Subtask {23.4-N} that edits .gitnexus/CLAUDE.md must explicitly git add .gitnexus/CLAUDE.md and commit the file alongside the propagation-discipline insertion (transitioning it from untracked to tracked).
2. The freshness guard (Inv 11) asserts content inside .gitnexus/CLAUDE.md. The guard works fine on untracked files (fs.readFile() doesn’t care about index state) — but if the file is removed from disk (e.g. .gitignore adds .gitnexus/), the guard fails. The implementing Subtask must also confirm .gitnexus/ is NOT in .gitignore. Verified: git check-ignore .gitnexus/CLAUDE.md returns non-zero (file is not ignored).
3. Sub-agent worktrees created via isolation: "worktree" inherit the PRIMARY tree’s .gitnexus/ content (per ID-19.4 hook-propagation gotcha pattern). Once .gitnexus/CLAUDE.md is tracked, sub-agents will read the propagation-discipline section directly. Until tracked, they read it via the orchestrator-inherited CLAUDE.md import which DOES work at agent-bootstrap.

Decision: one-shot edit, not @import or anchor-reference

The two .gitnexus/CLAUDE.md and .ast-dataflow/CLAUDE.md files are the source of truth for their respective tools. The 7 surface skill / agent files reference the tools by name (gitnexus_impact, ast-dataflow callers) but DO NOT copy the tool guide contents — that would duplicate maintenance. The surface files cite the tool guides inline, e.g.:

“Invoke gitnexus_impact({target: '<symbolName>', direction: 'upstream'}) — see .gitnexus/CLAUDE.md ‘Always Do’ for the canonical impact-analysis pattern.”

This is anchor-name reference, the third option from the brief’s enumeration (one-shot copy / @import style / anchor-name reference). Rationale: one-shot copy risks staleness; @import style is not a real Claude Code primitive (only root CLAUDE.md supports it); anchor-name reference is the lightest-touch propagation that still gives the sub-agent the citation it needs to look up the canonical guide.

Why ccc has no .ccc/CLAUDE.md

Per PRODUCT row-7×ccc N/A justification + P-OQ-3 default: ccc is intentionally skill-catalogue-only. The user’s global skill catalogue at ~/.agents/skills/ccc/SKILL.md is the canonical ccc reference. KH does NOT author a .ccc/CLAUDE.md mirror — adding one would create three propagation surfaces (root CLAUDE.md import + the file itself + the skill catalogue) for a single tool, increasing drift risk without changing behaviour. The ccc skill body is auto-discovered by the Skill tool when the trigger phrases match, so sub-agents that need ccc can invoke it without a project-global directive.

P-OQ-3 alternative escalation: if Liam ratifies P-OQ-3 ALT during this Task’s ratification gate, this TECH spec needs an amendment: (a) author .ccc/CLAUDE.md with parallel propagation-discipline section, (b) update root CLAUDE.md to add @./.ccc/CLAUDE.md import, (c) extend Inv 10 to cover the third file, (d) extend the freshness guard’s anchor inventory with anchor pair #13. Captured as T-OQ-5 below in case the TECH-level decision affects scope estimation.

§7 Per-Subtask file ownership for {23.3} PLAN — sibling-only deps

Recommended decomposition (13 Subtasks: 12 surface edits + 1 freshness guard)

This is the recommended grouping for the {23.3} PLAN. Sibling-only dependencies are honoured (every dependency expressed below is ID-23.{N} → ID-23.{M} with both N and M ≤ 17). The PLAN Planner makes the final call; this is the TECH-level proposal:

Proposed Subtask	Title	File ownership	Sibling deps
ID-23.4	workflow-orchestration baseline section + allowlist	.claude/skills/workflow-orchestration/SKILL.md (Inv 1, 4, 16)	—
ID-23.5	workflow-orchestration Planner + Executor brief blocks	.claude/skills/workflow-orchestration/SKILL.md (Inv 2 orch-side + Inv 3 orch-side)	23.4
ID-23.6	workflow-orchestration lifecycle-detail cite-the-impact-verdict	.claude/skills/workflow-orchestration/references/lifecycle-detail.md (Inv 15)	23.4
ID-23.7	task-planner Planner brief block	.claude/agents/task-planner.md (Inv 2 agent-side)	23.5 (anchor names must exist in workflow-orchestration first)
ID-23.8	write-product-spec orientation subsection	.claude/skills/write-product-spec/SKILL.md (Inv 5 PRODUCT-side)	23.7 (task-planner agent references it)
ID-23.9	write-tech-spec orientation subsection + conventions row	.claude/skills/write-tech-spec/SKILL.md (Inv 5 TECH-side + Inv 9)	23.7
ID-23.10	task-executor Executor brief block	.claude/agents/task-executor.md (Inv 3 agent-side)	23.5
ID-23.11	implement-subtask journal schema + commit gate	.claude/skills/implement-subtask/SKILL.md (Inv 6 + Inv 14)	23.10
ID-23.12	task-checker scope-containment + rename-sweep axes	.claude/agents/task-checker.md (Inv 7)	23.11 (journal schema is the source of audited verdicts)
ID-23.13	workflow-curator code-intel pre-grep principle	.claude/agents/workflow-curator.md (Inv 8 agent-side)	23.4
ID-23.14	triage-finding Caller-count pre-grep sub-step	.claude/skills/triage-finding/SKILL.md (Inv 8 skill-side)	23.13
ID-23.15	.gitnexus + .ast-dataflow propagation discipline	.gitnexus/CLAUDE.md + .ast-dataflow/CLAUDE.md (Inv 10 — manual Edit)	23.5 (references Inv 2/3 from the orch-side blocks)
ID-23.16	skill-routing-map tilt row 11	docs/reference/skill-routing-map.md (Inv 12)	—
ID-23.17	freshness-guard Vitest test	__tests__/docs/code-intelligence-integration.test.ts (Inv 11)	All of 23.4 through 23.16

13 implementation Subtasks. Within the 25-Subtask soft ceiling; comfortably below the split signal.

Sibling-only check passed

Every dependency cited is ID-23.{N} → ID-23.{M} (intra-Task). No Subtask requires referencing another Task’s Subtasks. The Task boundary is correct.

Parallelisability assessment

The sequential-dispatch constraint (§5) FORBIDS parallel update-skill / agent-development invocations. So even though the dependency graph above has parallelisable chains (e.g. 23.13/23.14 are independent of 23.7/23.8/23.9), the implementation must serialise. The PLAN Planner should set dependencies[] on every Subtask to enforce this serially, NOT just the logical inter-file deps.

Pure-prose Subtasks (no code change)

ID-23.15 (manual Edit on .gitnexus/ + .ast-dataflow/), ID-23.16 (manual Edit on skill-routing-map), and ID-23.17 (new Vitest test file) bypass the update-skill / agent-development constraint and CAN parallelise with each other IF the PLAN Planner ratifies that. The other 10 Subtasks (23.4–23.14) are strictly sequential.

§8 Testing and validation

PRODUCT inv	Test path	What the test asserts
Inv 1, 4, 16	__tests__/docs/code-intelligence-integration.test.ts (anchor #1 + #4)	Baseline section + allowlist anchors exist in workflow-orchestration/SKILL.md with required tool names
Inv 2	Same test (anchors #2 + #5)	Planner-block anchor present in BOTH workflow-orchestration/SKILL.md AND task-planner.md; content matches
Inv 3	Same test (anchors #3 + #6)	Executor-block anchor present in BOTH workflow-orchestration/SKILL.md AND task-executor.md; content matches
Inv 5	Same test (anchors #9 + #10)	Code-intelligence orientation subsection present in BOTH write-product-spec/SKILL.md AND write-tech-spec/SKILL.md; greenfield-disclaimer string present
Inv 6	Same test (manual literal-string assertion)	implement-subtask/SKILL.md journal-block schema contains “Blast radius” + “Scope verified” literal strings
Inv 7	Same test (anchor #7 + JSON-schema literal assertions)	task-checker.md axes table contains scope-containment + rename-sweep rows; JSON axis_scores literal includes both keys
Inv 8	Same test (anchor #8)	triage-finding/SKILL.md Step 1 caller-count pre-grep sub-step present with threshold
Inv 9	Same test (header-position assertion)	write-tech-spec/SKILL.md “Research before writing” FIRST subsection title === Code-intelligence orientation
Inv 10	Same test (anchors #11 + #12)	Both .gitnexus/CLAUDE.md AND .ast-dataflow/CLAUDE.md contain Propagation discipline section + Inv 2/3/7/8 mentions
Inv 11	Self-asserting	The test itself; passing means it exists. Failure on missing anchor surfaces the violation
Inv 12	Same test (skill-routing-map assertions)	docs/reference/skill-routing-map.md contains row 11 with named Required skills; canonical location retained
Inv 13	Same test (file-existence assertions)	docs/reference/skill-routing-map.md exists; .claude/skills/workflow-orchestration/references/skill-routing-map.md does NOT exist
Inv 14	Same test (literal-string assertion)	implement-subtask/SKILL.md contains “Pre-commit scope check (manual gate)” literal
Inv 15	Same test (literal-string assertion)	lifecycle-detail.md contains “cites the gitnexus_impact verdict” in both PRODUCT and TECH sub-sections

Run mechanism: bun run test __tests__/docs/code-intelligence-integration.test.ts locally; CI runs via the existing Vitest 4-shard matrix in .github/workflows/ci.yml quality-test job.

No runtime behaviour to verify. Inv 1–16 are all skill / agent / docs body assertions — there are no production code paths to test. The freshness guard IS the test. Future enhancement: a bun run test:dispatch-audit script that simulates a dispatch brief composition and asserts the brief contains the code-intel instruction blocks — but that’s a future ID, not in scope here.

§9 Risks and mitigations

#	Risk	Likelihood	Impact	Mitigation
R1	Propagation discipline failure mirroring ID-19.4 — surface skill / agent body edits land on production-readiness branch but not on main, so sub-agent worktrees (which inherit PRIMARY tree’s HEAD) dispatch WITHOUT the code-intel instruction blocks	HIGH	HIGH	(a) Every implementing Subtask’s details field carries a pre-merge check: `git show origin/main:.claude/skills//SKILL.md
R2	Freshness drift if guard is bypassed — someone runs update-skill and the anchor pair is clobbered during regeneration; guard catches it on next PR but the offending PR has already merged	MEDIUM	MEDIUM	(a) Anchor-preservation discipline encoded in every Subtask dispatch brief (per §4 last paragraph). (b) Guard runs on EVERY PR including main-target PRs (not gated to production-readiness). (c) Anchor-removal directive in test failure message points back to this spec for restoration
R3	Multi-tool reference churn — gitnexus / ast-dataflow / ccc tool guides themselves change (e.g. gitnexus_impact parameter shape evolves), invalidating the verbatim instruction blocks across all 7 surfaces	MEDIUM	LOW	(a) The verbatim blocks are paraphrased (Inv 2/3 wording), not literal tool-call signatures. The blocks reference the tool BY NAME and point to .gitnexus/CLAUDE.md for canonical signatures. Tool-signature evolution requires updating .gitnexus/CLAUDE.md only. (b) Freshness guard regex-asserts tool NAMES (e.g. /gitnexus_impact/) not parameter shapes — guard survives signature evolution
R4	update-skill stall pattern recurs — the S59 + S60 sequential-dispatch constraint fails to hold; a future Orchestrator session dispatches 2+ update-skill invocations in parallel and both stall	MEDIUM	MEDIUM	(a) PLAN Planner sets explicit dependencies[] on every update-skill / agent-development Subtask so the Orchestrator’s topological dispatch naturally serialises. (b) Document the constraint in Task ID-23 description (already present in current task-list.json). (c) Future: encode the constraint as an Orchestrator-side check in workflow-orchestration/SKILL.md
R5	.gitnexus/CLAUDE.md tracking transition — the Inv 10 commit adds the file to git tracking; if the surrounding directory .gitnexus/ contains other untracked files (e.g. .gitnexus/cache.db), the commit might accidentally stage them	LOW	LOW	The implementing Subtask’s details field explicitly states git add .gitnexus/CLAUDE.md (specific file, not git add .gitnexus/). Worktree status verification in the brief catches accidental scope expansion
R6	Anchor pair collision — a future skill body edit uses HTML comments for an unrelated purpose, accidentally matching the code-intel:* anchor regex	LOW	LOW	Anchor naming convention namespaces every anchor under code-intel: prefix. The regex is `<!— code-intel:[a-z]+-(start

§10 T-OQs (TECH-level open questions for Liam ratification)

Five T-OQs surfaced during TECH authoring. Each with default + alternative.

T-OQ-1 — Inv 13 references a registry that no longer exists

PRODUCT Inv 13 says: “this invariant is satisfied if docs/reference/skill-routing-map.md remains the canonical location AND no .claude/skills/workflow-orchestration/references/ skill-routing-map.md file exists. Tracked in lib/docs/tracked-reference-docs.ts so the <!-- Last verified --> header maintenance discipline applies.”

But lib/docs/tracked-reference-docs.ts was REMOVED in S249 (commit 4d4524d3 removed the entire edit-coupled freshness guard). The directory lib/docs/ does not exist in the current worktree. The freshness-header discipline is now “manually-bumped on edit”, not “CI-enforced via registry”.

Default: TECH authors Inv 13 as a file-existence-only assertion (positive on docs/reference/, negative on .claude/skills/workflow-orchestration/references/). Drop the “registry-tracked” framing from the implementation. The <!-- Last verified --> header bump becomes a manual discipline (which it already is everywhere else).

Alternative: Re-author lib/docs/tracked-reference-docs.ts as part of Task ID-23 scope — register skill-routing-map.md + the two new directive files. Adds maintenance overhead and re-introduces the rejected pattern.

Recommended: Default. The post-S249 posture is intentional; resurrecting the registry contradicts the same architectural decision.

T-OQ-2 — Freshness guard surface: Vitest under __tests__/docs/ vs pre-commit hook

P-OQ-2 was surfaced in PRODUCT with default Vitest test. TECH ratifies the default per §4 rationale: (a) avoids rejected S249 pattern, (b) --no-verify bypass risk on pre-commit, (c) sandbox compatibility issue with hook propagation.

Default: Vitest at __tests__/docs/code-intelligence-integration.test.ts. Authored as the LAST Subtask of Task ID-23 to avoid intermediate-commit failures.

Alternative: Pre-commit hook in .claude/settings.json that lints the surface files on git commit. Faster local feedback; bypassable.

Recommended: Default Vitest. The cost of bypass-risk + the cost of hook-propagation (per ID-19.4 lessons) outweigh the faster feedback.

T-OQ-3 — Surface-file scope expansion: should agent-creator.md be in scope?

PRODUCT matrix lists 7 surfaces (rows 1–7) and the brief’s dispatch text mentions .claude/agents/agent-creator.md as a “likely surface”. TECH-authoring inspection: the agent-creator.md agent is invoked to AUTHOR new agent files; it doesn’t dispatch code-touching work. Its tool-discipline expectations would be “when an agent file is authored that will dispatch code-touching work, the new agent file should carry the code-intel anchor blocks too” — but that’s a meta-requirement, not a code-intel integration.

Default: Exclude agent-creator.md. The 7 surfaces PRODUCT lists are authoritative; adding agent-creator.md adds maintenance without changing dispatched-agent behaviour.

Alternative: Include agent-creator.md with a “newly-authored agents inherit code-intel anchors” requirement. Captures the meta-rule but increases Subtask count to 14 and freshness-guard anchor count to 13+.

Recommended: Default. If a future agent file is authored that dispatches code-touching work, the freshness guard will fail on the first PR if it lacks the expected anchors — agent-creator.md is upstream of that failure; the guard catches the result.

T-OQ-4 — Inclusion-style for tool references: anchor-name vs @import vs one-shot copy

§6 ratifies anchor-name reference (third option). The 7 surface files reference .gitnexus/CLAUDE.md and .ast-dataflow/CLAUDE.md by path, not by content-copy.

Default: Anchor-name reference. Surface files cite “see .gitnexus/CLAUDE.md ‘Always Do’ for the canonical impact-analysis pattern”. Sub-agents follow the path to read the canonical guide.

Alternative A — one-shot copy: Embed the full “Always Do” / “Never Do” sections from .gitnexus/CLAUDE.md verbatim in each surface file. Risk: staleness on tool guide updates.

Alternative B — @import: Use @./.gitnexus/CLAUDE.md syntax inside surface skill / agent bodies. Risk: NOT a supported Claude Code primitive outside root CLAUDE.md — silent no-op in skill body resolution.

Recommended: Default. Alternative A duplicates maintenance; Alternative B is non-functional.

T-OQ-5 — P-OQ-3 carry-over: should .ccc/CLAUDE.md be authored under Task ID-23?

PRODUCT P-OQ-3 default: do NOT author .ccc/CLAUDE.md. If Liam ratifies P-OQ-3 ALT during this Task’s ratification gate, TECH needs amendment per §6 last paragraph.

Default: Do not author. Preserve the existing matrix (row 7, column 3 = N/A).

Alternative: Author .ccc/CLAUDE.md + extend root CLAUDE.md imports + extend Inv 10 to cover three files + extend freshness guard anchor inventory.

Recommended: Default (deferred to PRODUCT P-OQ-3 ratification). If P-OQ-3 flips ALT, add a follow-up Subtask {23.18} to author the third file.

§11 Estimated effort

Subtask	Effort estimate	Driver
ID-23.4 workflow-orchestration baseline + allowlist	60–90 min	Largest single edit; baseline section is the authoritative source-of-truth, ~80 lines of new content
ID-23.5 workflow-orchestration Planner + Executor brief blocks	30–45 min	Two anchor pairs, content per PRODUCT verbatim
ID-23.6 lifecycle-detail cite-the-impact-verdict	15–20 min	Two paragraph inserts
ID-23.7 task-planner Planner brief block	20–30 min	Mirror block from #5; verify anchor preservation through agent-development
ID-23.8 write-product-spec orientation	20–30 min	One subsection insert
ID-23.9 write-tech-spec orientation + conventions row	25–35 min	One subsection insert + one list row append
ID-23.10 task-executor Executor brief block	20–30 min	Mirror block from #5
ID-23.11 implement-subtask journal + commit gate	25–35 min	Two distinct amendments in different Steps
ID-23.12 task-checker axes + JSON schema	30–45 min	Most error-prone — JSON schema literal extension AND table extension; high anchor-preservation risk
ID-23.13 workflow-curator pre-grep principle	15–25 min	One bullet insert
ID-23.14 triage-finding pre-grep sub-step	20–30 min	One sub-step insert in Step 1
ID-23.15 .gitnexus + .ast-dataflow propagation	25–35 min	Two manual Edits; include git add .gitnexus/CLAUDE.md
ID-23.16 skill-routing-map tilt row 11	15–20 min	One row append + Last verified header bump
ID-23.17 freshness-guard Vitest test	60–90 min	New file; 12-anchor inventory + JSON schema assertions; local test run before commit
Total	6.5–9.5h	13 Subtasks; sequential constraint adds overhead per dispatch boundary

Recommended PLAN approach: Group ID-23.4 + ID-23.5 + ID-23.6 into the same Executor brief (single skill bundle: workflow-orchestration/) to amortise the dispatch overhead. Same for the per-file-pair groupings (ID-23.7 task-planner alone; ID-23.10 task-executor alone — different skill bundles). If grouping is acceptable to the sequential constraint, the wall-clock estimate drops to ~5–7h.

§12 Notes for {23.4} PLAN

• Decomposition strategy: Use the §7 recommended decomposition as the baseline. Group same-skill-bundle edits (Inv 1 + 4 + 16 share workflow-orchestration/SKILL.md).
• Anchor-preservation discipline: Every update-skill / agent-development Subtask’s details field MUST carry the literal instruction: “Retain all <!-- code-intel:*-start --> / <!-- code-intel:*-end --> anchor pairs verbatim. If the skill regenerates and drops an anchor, do not commit — re-invoke with the anchor-preservation requirement in the prompt, or fall back to manual Edit.”
• Pre-merge propagation check: Same Subtask details carries: git show origin/main:.claude/skills/<file>:.md | grep -c "code-intel:" must be ≥1 before sub-agent dispatch on that surface. Mirrors ID-19.4 hook-propagation pattern.
• Sequential dispatch enforcement: PLAN Planner sets explicit dependencies[] to serialise even logically-independent update-skill Subtasks. Manual-Edit Subtasks (23.15, 23.16) and the test-authoring Subtask (23.17) can parallelise with each other.
• Freshness guard last: ID-23.17 MUST be the final Subtask. Authoring it earlier fails every intermediate commit.
• T-OQ-3 confirmation: PLAN Planner confirms agent-creator.md is OUT of scope per TECH T-OQ-3 default before opening Subtasks 23.4–23.17.

References

• Linked PRODUCT spec: docs/specs/id-23-code-intelligence-integration/PRODUCT.md (16 invariants + 21-cell matrix + 5 P-OQs)
• Task ID-23 record: docs/reference/task-list.json → .tasks[] where id === "23"
• Tooling directives (sources of truth):
  • .gitnexus/CLAUDE.md (untracked) — gitnexus tool guide
  • .ast-dataflow/CLAUDE.md (tracked) — ast-dataflow tool guide
  • ~/.agents/skills/ccc/SKILL.md (user-global) — ccc skill body
• Surface files (current state captured §1):
  • .claude/skills/workflow-orchestration/SKILL.md + references/lifecycle-detail.md
  • .claude/skills/write-product-spec/SKILL.md
  • .claude/skills/write-tech-spec/SKILL.md
  • .claude/skills/implement-subtask/SKILL.md
  • .claude/skills/triage-finding/SKILL.md
  • .claude/agents/task-planner.md
  • .claude/agents/task-executor.md
  • .claude/agents/task-checker.md
  • .claude/agents/workflow-curator.md
  • docs/reference/skill-routing-map.md
• KH conventions (apply throughout authoring):
  • .planning/codebase/STRUCTURE.md — directory layout
  • docs/reference/SCHEMA-QUICK-REFERENCE.md — DB schema (N/A for this Task)
  • docs/reference/test-philosophy.md — tests verify behaviour, not implementation
  • docs/design/warm-meridian-implementation-spec.md — semantic tokens (N/A — no UI)
• Prior-art propagation pattern: ID-19.4 hook propagation gotcha in root CLAUDE.md “General” gotchas — directly mirrored by Inv 10’s propagation discipline
• Removed-pattern reference: S249 commit 4d4524d3 removed __tests__/docs/reference-doc-edit-coupled-freshness.test.ts and lib/docs/tracked-reference-docs.ts — informs T-OQ-1 default and T-OQ-2 default