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

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

§1 Overview

This PLAN decomposes the ratified PRODUCT.md + TECH.md pair into 13 sibling-only implementation Subtasks (ID-23.4 through ID-23.16), all landing in Wave 5 of the S65 WP0 cross-Task sequencing. Each Subtask owns exactly one surface file (or one logical co-edit pair where the file belongs to a single skill bundle) and carries a load-bearing details brief plus a one-line testStrategy. The decomposition honours TECH §7’s recommended 13-Subtask shape but renumbers, regroups, and reorders against the S65 WP0 cross-Task ratifications (OQ-B1 Wave-5 ordering + OQ-F1 surgical-additions).

1.1 What this PLAN delivers vs the prior TECH §7 proposal

TECH §7 proposed Subtasks ID-23.4 through ID-23.17 (14 Subtasks). This PLAN renumbers to ID-23.4 through ID-23.16 (13 Subtasks) by folding TECH’s §7 ID-23.4 + ID-23.5 + ID-23.6 grouping into a single workflow-orchestration-bundle Subtask (ID-23.4) — TECH’s own §11 effort recommendation already proposed this grouping (“Group ID-23.4 + ID-23.5 + ID-23.6 into the same Executor brief”). The freshness-guard test is the LAST Subtask (ID-23.16) per TECH §3 + §4 baseline-acknowledgement strategy.

1.2 Critical constraints applied

This PLAN is shaped by three load-bearing constraints absorbed at S65 W0:

1. OQ-B1 ordering — ID-23 lands LAST. Per WP0 §6 Wave-5 placement: every Subtask in this PLAN dispatches AFTER both (a) ID-30 PR-A curator-skill rewrite merges (Wave 2) AND (b) ID-31 §6.4 Promote-mode umbrella_id extension merges (Wave 2 / 3). This means EVERY curator-skill-touching Subtask in this PLAN reads the post-Wave-3 form of the skill body and adds surgical inline content — NEVER from scratch.
2. OQ-F1 surgical-additions — encoded in every Subtask details. Per WP0 §7 OQ-F1 (HIGH confidence): Subtasks touching .claude/skills/triage-finding/SKILL.md, .claude/skills/update-roadmap-backlog/SKILL.md, or any skill body Wave-2 rewrote carry the EXPLICIT VERBATIM instruction in their details field: “Read the post-Wave-3 form of {skill} FIRST; this Subtask adds surgical edits only — do NOT re-author from scratch.” This avoids the rebase thrash the CLAUDE.md gotcha “Sub- agents struggle with multi-skill invocations” warns against.
3. Sequential dispatch — no parallel /update-skill invocations. Per Task ID-23 description Constraints + S59 + S60 stall pattern: every Subtask whose mechanism is update-skill or agent-development has its dependencies[] set to enforce strict serialisation, regardless of whether the underlying file-ownership graph permits parallelism. Manual-Edit Subtasks (ID-23.13 + ID-23.14) and the freshness-guard Subtask (ID-23.16) MAY parallelise with each other once their upstream sibling deps close.

1.3 Output shape

13 implementation Subtask records added to Task ID-23’s subtasks[] array. Total Task ID-23 Subtask count after this PLAN lands: 16 (3 spec-chain + 13 implementation), comfortably within the 25-Subtask soft ceiling (§3.4 / A7).

§2 Ratifications absorbed (full traceability)

Five spec-chain ratification packages apply to this PLAN. The table below maps each ratification to its source, its Inv / OQ scope, and the PLAN-side consequence.

#	Ratification	Source	Scope	PLAN-side consequence
1	P-OQ-1 retain docs/reference/skill-routing-map.md location	PRODUCT §P-OQ-1 default	Inv 13	PLAN authors ID-23.14 as a docs/reference/skill-routing-map.md Manual Edit (no file move; no lib/docs/tracked-reference-docs.ts registration — that file was removed S249 per T-OQ-1)
2	P-OQ-2 freshness guard = Vitest at __tests__/docs/code-intelligence-integration.test.ts	PRODUCT §P-OQ-2 default	Inv 11	PLAN’s ID-23.16 (final Subtask) authors the Vitest test; baseline-acknowledgement strategy is strict-from-PR-day-1 per TECH §4
3	P-OQ-3 do NOT author .ccc/CLAUDE.md	PRODUCT §P-OQ-3 default	Inv 10, matrix row 7	PLAN scope EXCLUDES .ccc/CLAUDE.md authoring; Inv 10 covers only .gitnexus/CLAUDE.md + .ast-dataflow/CLAUDE.md. If P-OQ-3 flips ALT later, add a 17th Subtask post-PLAN
4	P-OQ-4 greenfield-disclaimer wording = free text	PRODUCT §P-OQ-4 default	Inv 5, Inv 11	PLAN’s ID-23.6 + ID-23.7 (write-product-spec / write-tech-spec orientation subsections) prescribe the literal text “gitnexus orientation: no existing symbols match — greenfield surface”
5	P-OQ-5 docs-only dispatches skip tool discipline	PRODUCT §P-OQ-5 default	Inv 16	Allowlist scope in ID-23.4 baseline section excludes .md / .mdx from tool-discipline enforcement; no overhead added to documentation-only dispatches
6	T-OQ-1 Inv 13 references removed lib/docs/tracked-reference-docs.ts registry — drop registry framing	TECH §10 T-OQ-1 + S65 W0 ratification	Inv 13	PLAN’s ID-23.14 (skill-routing-map row 11) drops the “tracked in lib/docs/tracked-reference-docs.ts” expectation; Inv 13 satisfied by file-existence assertions only. Per Liam at S65 session-start: registry resurrection contradicts S249 architectural decision; freshness-header maintenance is manual discipline (will be covered by ID-9 Astro + Warp ported doc skills)
7	T-OQ-2 Vitest at __tests__/docs/ (not pre-commit hook)	TECH §10 T-OQ-2 default	Inv 11	PLAN’s ID-23.16 codifies the Vitest path; baseline-ratchet strategy is strict; CI matrix is the canonical surface
8	T-OQ-3 agent-creator.md OUT of scope	TECH §10 T-OQ-3 default + Orchestrator pre-flight verification	Surface scope	PLAN scope EXCLUDES .claude/agents/agent-creator.md. Verified pre-flight by Orchestrator: agent-development skill does NOT reference agent-creator.md (no relationship). 11 surface files only
9	T-OQ-4 anchor-name reference (not @import, not one-shot copy)	TECH §10 T-OQ-4 default	Inv 1-3, 7, 8, 10	PLAN’s curator/agent Subtasks reference .gitnexus/CLAUDE.md and .ast-dataflow/CLAUDE.md BY NAME from inside skill / agent bodies; surface files cite the canonical guides rather than copy them. Per Liam: “Task-dependent and a key reason why we have skill routing… it would be the orchestrator who would deploy a task planner for a research task and at this point it would need to be explicit which supporting tools should be utilised based on what the task requires”
10	T-OQ-5 do NOT author .ccc/CLAUDE.md (TECH-side echo of P-OQ-3)	TECH §10 T-OQ-5 default	Inv 10	Same scope exclusion as ratification #3 above; redundant safeguard

2.1 WP0 cross-Task ratifications applied (CRITICAL)

These three ratifications from docs/research/cross-task-dependency-map-and-sequencing.md (S65 W0) are LOAD-BEARING for this PLAN’s correctness:

WP0 OQ	Recommendation	PLAN consequence
OQ-B1 — curator-skill rewrite ordering (HIGH confidence)	(1) ID-30 PR-A curator rewrite FIRST → (2) ID-31 §6.4 Promote-mode umbrella_id extension SECOND → (3) ID-23 propagation discipline + caller-count amendments LAST	This entire PLAN’s Wave-5 placement. Every Subtask touching triage-finding or update-roadmap-backlog runs AFTER the prior two waves. §5 cross-Task coordination encodes the verification step
OQ-F1 — surgical-additions constraint (HIGH confidence)	ID-23 Subtasks adding to curator skills MUST read post-Wave-3 form first; amendments are surgical inserts, never re-authoring from scratch	Every PLAN Subtask whose mechanism = update-skill on triage-finding or update-roadmap-backlog carries the verbatim “surgical addition only” instruction. Encoded per §6 surgical-additions template
OQ-C — strict-sequence ID-30 PR-A → ID-31 §3 (MEDIUM confidence)	ID-30 PR-A merges first, then ID-31 §3	Not directly a PLAN constraint (ID-23 lands LAST regardless), but informs the prerequisite-merge verification in §5

2.2 Confirmations carried in from the brief

• T-OQ-3 confirmation: Orchestrator pre-flight verified agent-development skill does NOT reference agent-creator.md. 11 surface files only. No 12th surface or 13th anchor pair added to the freshness-guard.
• Liam’s T-OQ-1 ratification on tracked-reference-docs: “Not required — will be covered by ID-9 (Astro + Warp ported doc skills).” PLAN’s ID-23.14 (skill-routing- map.md edit) bumps the <!-- Last verified --> header as manual discipline; no registry registration step.

§3 Sibling-only Subtask DAG

13 implementation Subtasks. Every dependency expressed is intra-Task (ID-23.{N} → ID-23.{M}). NO cross-Task Subtask dependencies surface. Cross-Task dependencies (per WP0 §6 Wave-5 ordering) live at the Task level via prerequisite-merge verification in the Subtask details field, NOT in the dependencies[] array. This is the §3.3 / A6 forcing function applied.

3.1 DAG (Mermaid-style ASCII)

                                         ID-23.4
                            (workflow-orchestration bundle:
                          SKILL.md baseline + Planner + Executor
                              blocks + lifecycle-detail.md)
                                            │
              ┌─────────────────────────────┼─────────────────────────────┐
              ▼                             ▼                             ▼
         ID-23.5                       ID-23.8                       ID-23.10
      (task-planner.md            (task-executor.md             (workflow-curator.md
       Planner block)              Executor block)               pre-grep principle)
              │                             │                             │
              ▼                             ▼                             ▼
         ID-23.6                       ID-23.9                       ID-23.11
    (write-product-spec         (implement-subtask              (triage-finding
     orientation)               journal+commit gate)             caller-count pregrep)
              │                             │
              ▼                             ▼
         ID-23.7                       ID-23.12
    (write-tech-spec            (task-checker.md
     orientation+conventions)    scope-containment + rename-sweep)
                                            │
                                            ▼
                                       ID-23.13
                                 (.gitnexus + .ast-dataflow
                                  propagation discipline —
                                  manual Edit)
                                            │
                                            ▼
                                       ID-23.14
                                  (skill-routing-map row 11
                                   — manual Edit)
                                            │
                                            ▼
                                       ID-23.15
                                  (pre-merge propagation
                                   verification — final
                                   defensive check)
                                            │
                                            ▼
                                       ID-23.16
                                 (freshness-guard Vitest
                                  test — LAST)

3.2 Dependency rationale per edge

• ID-23.4 → ID-23.5 / .8 / .10: the workflow-orchestration baseline section + per- role anchor blocks must land FIRST so per-role agent Subtasks reference an existing anchor target (TECH §3 topological order).
• ID-23.5 → ID-23.6: task-planner.md Operating principles references the new write-product-spec orientation subsection — order matters for cross-doc citation freshness.
• ID-23.6 → ID-23.7: write-product-spec orientation lands before write-tech-spec orientation; the second subsection cites patterns established in the first.
• ID-23.8 → ID-23.9: task-executor.md operating principles references the implement-subtask journal-block schema; sequencing prevents broken back-references.
• ID-23.9 → ID-23.12: task-checker.md scope-containment audit axis verifies Executor journal-block lines (Blast radius + Scope verified) authored in ID-23.9.
• ID-23.10 → ID-23.11: workflow-curator.md operating-principle pre-grep bullet references triage-finding/SKILL.md Step 1 — same pattern.
• ID-23.7 / .11 / .12 → ID-23.13: .gitnexus/CLAUDE.md + .ast-dataflow/CLAUDE.md propagation-discipline sections cite Inv 2/3/7/8 by number; those anchors must exist in the per-role surface files first.
• ID-23.13 → ID-23.14: sequential discipline (no parallel manual-Edits across the same logical area).
• ID-23.14 → ID-23.15: verification step runs AFTER all surface-file edits land.
• ID-23.15 → ID-23.16: the freshness-guard Vitest test asserts EVERY anchor; authoring it before any prior step would fail every intermediate commit (TECH §4 baseline-acknowledgement: strict-from-PR-day-1).

3.3 Cycle check

Acyclic. Every dependency points “down” the DAG (from earlier to later Subtask ID). Sibling-only constraint preserved: every dep is ID-23.{N} → ID-23.{M} with both N, M ∈ {4, 5, …, 16}.

3.4 Sibling-only verification

For each Subtask, the dependencies[] array contains ONLY other Subtask IDs from Task ID-23. If a future need surfaces to express “ID-23.{N} depends on ID-{M}.{P} (cross- Task)”, the Task boundary is wrong — escalate to the Orchestrator to split or merge. No such dependency surfaced during this PLAN authoring.

§4 Wave alignment

Per WP0 §6 sequencing: ALL Subtasks ID-23.4+ land in Wave 5 (~S68, 3 sessions out from S65 dispatch). Wave 5 follows the schema + curator-skill foundation (Wave 2), the retrospective Task population (Wave 3), and the bulk-content migration + roadmap reshape (Wave 4).

4.1 Wave 5 entry preconditions

Before ANY Subtask ID-23.4+ dispatches, the following must be true:

1. ID-30 PR-A merged into main AND production-readiness (curator-skill rewrite landed: triage-finding/SKILL.md Branch B/C rewrite + update-roadmap-backlog/ SKILL.md Create/Update/Delete/Promote under Shape A; both with capability_theme copy-through).
2. ID-31 §6.4 (Subtask 31.9) merged into main AND production-readiness (update-roadmap-backlog/SKILL.md Promote-mode umbrella_id extension landed).
3. Pre-merge propagation check passes (per §5 cross-Task coordination + Inv 10 propagation discipline): git show origin/main:.claude/skills/<surface>/SKILL.md | grep -c "<post-Wave-3 anchor>" must return ≥1 before any ID-23.4+ sub-agent dispatch.

Failure to satisfy any of these preconditions = STOP and escalate to Orchestrator before dispatching ID-23.4+. Per CLAUDE.md “Sub-agents struggle with multi-skill invocations” + WP0 OQ-F1 surgical-additions ratification.

4.2 In-Wave ordering

Within Wave 5, dispatch follows the §3 DAG strictly. Sequential dispatch enforced (one update-skill / agent-development invocation in flight at a time). The final two Subtasks (ID-23.15 pre-merge propagation verification + ID-23.16 freshness-guard Vitest test) may parallelise with each other once their respective upstream deps close, BUT the propagation verification must report PASS before the Vitest test authoring closes (the Vitest test depends on the propagation verification’s discovery of any missing anchors).

4.3 Curator-skill Subtask reading discipline

Per OQ-F1: every Subtask in this PLAN whose details field includes “edit triage-finding/SKILL.md” or “edit update-roadmap-backlog/SKILL.md” prescribes explicitly:

Read the POST-Wave-3 form of {skill} FIRST. Verify the post-Wave-3 anchor exists: grep -E "<expected-Wave-3-marker>" .claude/skills/<skill>/SKILL.md must return a match. This Subtask adds SURGICAL EDITS to the already-rewritten skill — do NOT re-author from scratch. If the post-Wave-3 marker is missing, STOP and escalate (the prerequisite merge has not landed).

This instruction is encoded verbatim in §6 below per applicable Subtask.

§5 Cross-Task coordination (load-bearing)

This section is load-bearing per WP0 + the brief’s explicit emphasis. It encodes the prerequisite-merge verification, the sequential-dispatch discipline, and the propagation-discipline check that protects against ID-19.4-style hook-propagation regressions.

5.1 Prerequisite-merge gates

Each curator-skill-touching Subtask carries an explicit testStrategy verification step naming the prerequisite merge commit. The Executor dispatched on the Subtask verifies the merge BEFORE making any edit:

ID-23 Subtask	Prerequisite merge commit	Verification command
ID-23.11 (triage-finding caller-count pre-grep)	ID-30 PR-A merge (curator-skill rewrite of triage-finding/SKILL.md Branch B/C)	`git log main —oneline — .claude/skills/triage-finding/SKILL.md
ID-23.10 (workflow-curator pre-grep principle)	ID-30 PR-A merge (same as above, on curator-side)	grep "Branch B" .claude/skills/triage-finding/SKILL.md returns ≥1 (transitive via prior Subtask). Direct verification: git log main --grep "PR-A" -- .claude/skills/triage-finding/SKILL.md | head -3
(Indirect — none directly)	ID-31 §6.4 (Subtask 31.9) merge (Promote-mode umbrella_id extension on update-roadmap-backlog/SKILL.md)	NOT a direct prereq for any ID-23 Subtask in this PLAN — ID-23 does NOT edit update-roadmap-backlog/SKILL.md (TECH §1 surface list excludes it; only triage-finding/SKILL.md is in ID-23 scope per Inv 8). Cross-Task informational dep only

Important clarification: Re-reading TECH §1 and Inv 8, the ID-23 PLAN scope edits triage-finding/SKILL.md ONLY (NOT update-roadmap-backlog/SKILL.md). The WP0 row 5 crossover names both files because ID-30 + ID-31 BOTH edit both, while ID-23 edits only triage-finding. This narrows ID-23’s prerequisite-merge surface considerably.

5.2 Sequential dispatch enforcement

Per Task ID-23 description Constraints + S59 + S60 stall pattern: NO parallel update-skill / agent-development invocations. Encoded structurally via dependencies[]:

Subtask	Mechanism	Why sequential
ID-23.4	update-skill workflow-orchestration	First in chain; no deps
ID-23.5	agent-development task-planner	Depends on ID-23.4 (anchor names referenced)
ID-23.6	update-skill write-product-spec	Depends on ID-23.5
ID-23.7	update-skill write-tech-spec	Depends on ID-23.6
ID-23.8	agent-development task-executor	Depends on ID-23.4
ID-23.9	update-skill implement-subtask	Depends on ID-23.8
ID-23.10	agent-development workflow-curator	Depends on ID-23.4
ID-23.11	update-skill triage-finding	Depends on ID-23.10
ID-23.12	agent-development task-checker	Depends on ID-23.9
ID-23.13	Manual Edit	Depends on ID-23.7 + ID-23.11 + ID-23.12 — convergence point
ID-23.14	Manual Edit	Depends on ID-23.13
ID-23.15	Manual Edit (verification only — read-only against origin/main)	Depends on ID-23.14
ID-23.16	Manual Write (new Vitest file)	Depends on ID-23.15

Manual-Edit Subtasks (ID-23.13 + ID-23.14) and the verification + Vitest-test Subtasks (ID-23.15 + ID-23.16) MAY parallelise pairwise once their direct upstream sibling deps close — but the conservative default is strict sequential, per CLAUDE.md “Sub-agents struggle with multi-skill invocations” applied transitively.

5.3 Propagation-discipline check (ID-19.4 mirror)

Per Inv 10 + ID-19.4 hook propagation pattern: hooks live in .claude/settings.json per branch; sub-agent worktrees inherit MAIN branch state at creation.

ID-23 mirror: skill / agent body edits live in .claude/skills/*/SKILL.md and .claude/agents/*.md per branch; sub-agent worktrees inherit MAIN branch state at creation. If a curator-skill edit lands on production-readiness but NOT on main, sub-agents dispatched off MAIN will inherit a skill body LACKING the code-intel anchors — sub-agents dispatch without the tool-discipline instruction blocks.

Mitigation: ID-23.15 (penultimate Subtask) runs the pre-merge propagation check across all 13 surface files:

for surface in \
  .claude/skills/workflow-orchestration/SKILL.md \
  .claude/skills/workflow-orchestration/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 \
  .gitnexus/CLAUDE.md \
  .ast-dataflow/CLAUDE.md \
  docs/reference/skill-routing-map.md; do
  count=$(git show origin/main:"$surface" 2>/dev/null | grep -c "code-intel:")
  echo "$surface: $count"
done

For the 12 surface files with code-intel:* anchors, count MUST be ≥1 on every file on origin/main BEFORE the freshness-guard Vitest test (ID-23.16) authoring closes. (skill-routing-map.md uses no anchor pair; its Inv 12 satisfaction is the row-11 presence — checked separately via grep "Refactor / Rename" docs/reference/skill- routing-map.md on origin/main.)

If any count is 0 on main, STOP and escalate — the propagation gap is the failure mode this Task explicitly mitigates against.

5.4 Brief-authoring discipline applied

Per CLAUDE.md “Brief-authoring discipline — minimise sibling-worktree absolute paths”: every Subtask’s details field uses relative paths only. The sole exception is git show origin/main:<relative-path> strings (a worktree-safe pattern that does NOT trigger Tier 2.2 hooks because it operates on git object database, not on filesystem paths). NO Subtask’s details field mentions absolute sibling-worktree paths like /Users/liamj/Documents/development/knowledge-hub-production-readiness/.

§6 Surgical-additions template (referenced by every curator-skill Subtask)

The following instruction block is referenced verbatim in every Subtask whose mechanism touches .claude/skills/triage-finding/SKILL.md, .claude/skills/update-roadmap-backlog/SKILL.md, or any other skill body Wave-2 rewrote. Each Subtask details field includes this instruction:

SURGICAL-ADDITION CONSTRAINT (OQ-F1 ratification). Before invoking update-skill on <skill-name>, run grep -E "<post-Wave-3-marker>" .claude/skills/<skill-name>/ SKILL.md to confirm the prerequisite ID-30 PR-A (or ID-31 §6.4) merge has landed. If the marker is MISSING, STOP and escalate to the Orchestrator — the Wave-5 prerequisite is not satisfied. If the marker is PRESENT, your task is to ADD the Inv 8 caller-count pre-grep sub-step as a surgical insert AT THE END of Step 1 (or at the documented anchor position) WITHOUT modifying the post-Wave-3 Branch B/C rewrite content. Do NOT re-author the file from scratch; do NOT regenerate the entire skill body. Use the update-skill skill’s “edit existing skill” mode with explicit anchor preservation. If update-skill regeneration clobbers the post- Wave-3 Branch B/C content, fall back to manual Edit for the anchor insertion step only.

This template is invoked in §7 Subtasks ID-23.11 (triage-finding) and partially in ID-23.10 (workflow-curator agent-side reference to the skill).

§7 Subtask records

Each Subtask record below is in TM-shape ready for splicing into Task ID-23’s subtasks[] array. Format: id (integer, local to parent Task 23), title, description, details (load-bearing dispatch brief), status (pending), dependencies (integer array of sibling-only Subtask IDs), testStrategy (one-line acceptance prose), and KH-extension fields priority + effort_h + file_ownership (file-ownership zone label per WP0 §2 convention). Note: priority, effort_h, and file_ownership are PLAN-side-only metadata fields used for human-readable planning context — they are not written to task-list.json (consistent with existing Task subtask records).

ID-23.4 — workflow-orchestration baseline section + role anchor blocks + lifecycle-detail

• id: 4
• title: workflow-orchestration baseline section + Planner/Executor blocks + lifecycle-detail.md cite-the-impact-verdict
• description: Author the canonical “Code-intelligence baseline” section in .claude/skills/workflow-orchestration/SKILL.md covering Inv 1 + Inv 4 + Inv 16, AND the two role-side verbatim instruction blocks (Inv 2 Planner-block + Inv 3 Executor-block) in the same SKILL.md, AND the cite-the-impact-verdict paragraph in .claude/skills/workflow-orchestration/references/lifecycle-detail.md PRODUCT + TECH sub-sections (Inv 15). Single Executor brief; same update-skill invocation covers all three because the workflow-orchestration skill bundle is atomic.
• details: update-skill workflow-orchestration invocation. Files touched (single skill bundle): .claude/skills/workflow-orchestration/SKILL.md (insert “Code-intelligence baseline” section after ## Skill routing, current line ~327; insert per-role anchor blocks within the baseline section); .claude/skills/workflow-orchestration/references/lifecycle-detail.md (amend PRODUCT + TECH sub-sections with cite-the-impact-verdict paragraph). Anchors to author (4 anchor pairs in SKILL.md): <!-- code-intel:baseline-start --> … <!-- code-intel:baseline-end --> (Inv 1, 4); <!-- code-intel:planner-block-start --> … <!-- code-intel:planner-block-end --> (Inv 2 orch-side); <!-- code-intel:executor-block-start --> … <!-- code-intel:executor-block-end --> (Inv 3 orch-side); <!-- code-intel:allowlist-start --> … <!-- code-intel:allowlist-end --> (Inv 16). Required content per TECH §4 anchor inventory: baseline section mentions gitnexus_impact, gitnexus_detect_changes, gitnexus_query, ast-dataflow, ccc; Planner block mentions gitnexus_query + gitnexus_context; Executor block mentions gitnexus_impact + gitnexus_detect_changes + “HIGH or CRITICAL”; allowlist block lists .ts/.tsx/.js/.jsx/.mjs/.cjs + app//lib//components//hooks//contexts//types//scripts/ (in-scope) + .md/.mdx/.py/.sql (out-of-scope). lifecycle-detail.md insert: add one paragraph each to PRODUCT and TECH sub-sections beginning “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” per Inv 15 wording. Anchor preservation: mandate to retain all <!-- code-intel:*-start --> / <!-- code-intel:*-end --> anchor pairs verbatim if update-skill regenerates; fall back to manual Edit for the anchor insertion if regeneration drops anchors. Spec references: PRODUCT §Cluster A (Inv 1-4), §Cluster F (Inv 15), §Cluster G (Inv 16); TECH §2 rows 1+2+3+4+15+16. WP0 Wave 5 prereq check: verify ID-30 PR-A merged on origin/main before dispatch (git log main --grep "PR-A" -- .claude/skills/workflow-orchestration/SKILL.md returns ≥1 commit) — workflow-orchestration is NOT directly rewritten by ID-30 PR-A, but the broader Wave 2 schema + skill foundation must be stable. If unsure, escalate.
• status: pending
• dependencies: []
• testStrategy: update-skill workflow-orchestration invocation lands; .claude/skills/workflow-orchestration/SKILL.md contains all four <!-- code-intel:*-start -->/-end --> anchor pairs with required content; lifecycle-detail.md contains “cites the gitnexus_impact verdict” literal in BOTH PRODUCT and TECH sub-sections. Sanity: grep -c "code-intel:" .claude/skills/workflow-orchestration/SKILL.md returns 8 (4 pairs × 2 markers).
• priority: must
• effort_h: 1.5
• file_ownership: workflow-orchestration-bundle

ID-23.5 — task-planner Planner brief block

• id: 5
• title: task-planner.md Planner brief code-intel block (Inv 2 agent-side)
• description: Mirror the Planner brief code-intel block from workflow-orchestration/SKILL.md (authored in ID-23.4) into .claude/agents/task-planner.md Operating principles section. Sub-agent reads this verbatim at dispatch time per Inv 2 acceptance criterion.
• details: agent-development task-planner invocation. File touched: .claude/agents/task-planner.md (insert “Code-intelligence orientation (pre-spec-write)” subsection under “Operating principles”, current line ~94). Anchor to author: <!-- code-intel:planner-block-start --> … <!-- code-intel:planner-block-end --> (Inv 2 agent-side, duplicate-by-design of ID-23.4’s orch-side anchor). Required content: same paraphrase as TECH §2 Inv 2 row — invoke gitnexus_query on feature concept + gitnexus_context on each named symbol + cite findings in spec Context (TECH) or Problem (PRODUCT) section. Anchor-name reference (T-OQ-4 ratification): the block cites .gitnexus/CLAUDE.md “Always Do” section by name + path; do NOT copy the gitnexus guide contents inline. Anchor preservation: retain anchor pair verbatim if agent-development regenerates the agent body. Spec references: PRODUCT §Cluster A Inv 2, §Cluster B Inv 5; TECH §2 row 2; TECH §3 order #3.
• status: pending
• dependencies: [4]
• testStrategy: agent-development task-planner invocation lands; .claude/agents/task-planner.md contains <!-- code-intel:planner-block-start --> … <!-- code-intel:planner-block-end --> pair with content matching /gitnexus_query/ AND /gitnexus_context/. Sanity: grep -c "code-intel:planner-block" .claude/agents/task-planner.md returns 2.
• priority: must
• effort_h: 0.5
• file_ownership: agent-task-planner

ID-23.6 — write-product-spec orientation subsection

• id: 6
• title: write-product-spec/SKILL.md code-intelligence orientation subsection (Inv 5 PRODUCT-side)
• description: Add ### Code-intelligence orientation subsection to the “Before writing” section of .claude/skills/write-product-spec/SKILL.md. Subsection instructs Planners to cite gitnexus findings (execution-flow name, symbol caller count, cluster ID) in spec Problem section, OR carry the explicit “gitnexus orientation: no existing symbols match — greenfield surface” disclaimer (per P-OQ-4 default).
• details: update-skill write-product-spec invocation. File touched: .claude/skills/write-product-spec/SKILL.md (insert ### Code-intelligence orientation subsection in “Before writing” section). Anchor to author: <!-- code-intel:planner-citation-start --> … <!-- code-intel:planner-citation-end -->. Required content: subsection title Code-intelligence orientation; instruction text covering (a) invoke gitnexus_query on feature concept, (b) invoke gitnexus_context on each named symbol, (c) cite findings (execution-flow ID, caller count, cluster ID) in spec Problem section, (d) greenfield-disclaimer wording literal “gitnexus orientation: no existing symbols match — greenfield surface” available for use when no symbols match. Anchor preservation: retain anchor pair verbatim if update-skill regenerates the SKILL.md. Spec references: PRODUCT §Cluster B Inv 5, §P-OQ-4 default; TECH §2 row 5.
• status: pending
• dependencies: [5]
• testStrategy: update-skill write-product-spec invocation lands; .claude/skills/write-product-spec/SKILL.md contains <!-- code-intel:planner-citation-start --> … <!-- code-intel:planner-citation-end --> pair AND literal strings Code-intelligence orientation AND greenfield surface. Sanity: grep -c "greenfield surface" .claude/skills/write-product-spec/SKILL.md returns ≥1.
• priority: must
• effort_h: 0.5
• file_ownership: skill-write-product-spec

ID-23.7 — write-tech-spec orientation subsection + conventions row

• id: 7
• title: write-tech-spec/SKILL.md code-intelligence orientation subsection (FIRST) + conventions list extension (Inv 5 TECH-side + Inv 9)
• description: Add ### Code-intelligence orientation as the FIRST subsection of “Research before writing” in .claude/skills/write-tech-spec/SKILL.md (per Inv 9 first-line research pattern requirement), AND extend the “Knowledge Hub conventions to ground the plan in” list with a “Code intelligence” row pointing to .gitnexus/CLAUDE.md and .ast-dataflow/CLAUDE.md.
• details: update-skill write-tech-spec invocation. File touched: .claude/skills/write-tech-spec/SKILL.md (insert ### Code-intelligence orientation subsection at TOP of “Research before writing” section, current line ~49; append “Code intelligence” row to “Knowledge Hub conventions to ground the plan in” list). Anchor to author: <!-- code-intel:planner-citation-start --> … <!-- code-intel:planner-citation-end --> (mirrors ID-23.6’s anchor in write-product-spec). Required content: subsection title Code-intelligence orientation; FIRST-position placement within “Research before writing” section (verified by TECH §4 anchor #10 header-position assertion); four-step orientation pattern per Inv 9 — (a) gitnexus_query on feature concept, (b) gitnexus_context on each named symbol from PRODUCT.md, (c) ccc semantic search when surface is unfamiliar, (d) ast-dataflow queries (column-reads / column-writes for schema-touching; callers for refactor). Greenfield-disclaimer wording literal “gitnexus orientation: no existing symbols match — greenfield surface” available. Conventions list extension: add row “Code intelligence — see .gitnexus/CLAUDE.md and .ast-dataflow/CLAUDE.md”. Anchor-name reference (T-OQ-4): subsection cites .gitnexus/CLAUDE.md + .ast-dataflow/CLAUDE.md by name + path; do NOT copy tool guide contents. Spec references: PRODUCT §Cluster B Inv 5, §Cluster C Inv 9; TECH §2 rows 5+9; TECH §3 order #5.
• status: pending
• dependencies: [6]
• testStrategy: update-skill write-tech-spec invocation lands; .claude/skills/write-tech-spec/SKILL.md “Research before writing” FIRST subsection title is Code-intelligence orientation; conventions list contains row referencing both .gitnexus/CLAUDE.md AND .ast-dataflow/CLAUDE.md; literal string greenfield surface present. Sanity: head -100 .claude/skills/write-tech-spec/SKILL.md | grep -A 0 "^### " | head -1 returns the new subsection (verifying first-position).
• priority: must
• effort_h: 0.5
• file_ownership: skill-write-tech-spec

ID-23.8 — task-executor Executor brief block

• id: 8
• title: task-executor.md Executor brief code-intel block (Inv 3 agent-side)
• description: Mirror the Executor brief code-intel block from workflow-orchestration/SKILL.md (authored in ID-23.4) into .claude/agents/task-executor.md Operating principles. Sub-agent reads this verbatim at dispatch time per Inv 3 acceptance criterion — pre-edit gitnexus_impact per modified symbol; pre-commit gitnexus_detect_changes.
• details: agent-development task-executor invocation. File touched: .claude/agents/task-executor.md (insert “Pre-edit impact + pre-commit detect-changes” bullets in “Operating principles” section; amend Step 4 Implement). Anchor to author: <!-- code-intel:executor-block-start --> … <!-- code-intel:executor-block-end --> (Inv 3 agent-side, duplicate-by-design of ID-23.4’s orch-side anchor). Required content: same paraphrase as TECH §2 Inv 3 row — pre-edit gitnexus_impact({target: '<symbolName>', direction: 'upstream'}) per modified function/class/method; HIGH or CRITICAL risk warnings MUST escalate to Orchestrator; pre-commit gitnexus_detect_changes() verifies diff only affects expected symbols. Anchor-name reference (T-OQ-4): block cites .gitnexus/CLAUDE.md “Always Do” by name + path; do NOT copy. Anchor preservation: retain anchor pair verbatim. Spec references: PRODUCT §Cluster A Inv 3, §Cluster B Inv 6; TECH §2 row 3; TECH §3 order #6.
• status: pending
• dependencies: [4]
• testStrategy: agent-development task-executor invocation lands; .claude/agents/task-executor.md contains <!-- code-intel:executor-block-start --> … <!-- code-intel:executor-block-end --> pair with content matching /gitnexus_impact/ AND /gitnexus_detect_changes/ AND /HIGH or CRITICAL/. Sanity: grep -c "code-intel:executor-block" .claude/agents/task-executor.md returns 2.
• priority: must
• effort_h: 0.5
• file_ownership: agent-task-executor

ID-23.9 — implement-subtask journal schema + commit gate

• id: 9
• title: implement-subtask/SKILL.md journal-block schema + pre-commit scope check (Inv 6 + Inv 14)
• description: Amend .claude/skills/implement-subtask/SKILL.md Step 5 (Journal block schema) to add two literal lines — **Blast radius:** <verdict> (<caller-count> callers) and **Scope verified:** gitnexus_detect_changes matched expected symbol set — AND Step 4 (Commit) to add the “Pre-commit scope check (manual gate)” paragraph naming gitnexus_detect_changes() invocation.
• details: update-skill implement-subtask invocation. File touched: .claude/skills/implement-subtask/SKILL.md (amend Step 5 journal-block schema code-fence at current line ~140; insert “Pre-commit scope check (manual gate)” paragraph immediately before the commit-message code-fence in Step 4 at current line ~117). No anchor pair required — the freshness guard (Inv 11) asserts literal strings directly. Required literal strings in Step 5 journal-block code-fence: **Blast radius:** <verdict> (<caller-count> callers) AND **Scope verified:** gitnexus_detect_changes matched expected symbol set. Required literal string in Step 4: paragraph beginning **Pre-commit scope check (manual gate):** followed by the content per TECH §2 Inv 14 row — invoke gitnexus_detect_changes() before commit-commands; STOP and escalate if symbols outside boundary; manual gate canonical until tooling automates. Anchor-name reference (T-OQ-4): paragraph cites .gitnexus/CLAUDE.md for the canonical detect_changes invocation pattern. Spec references: PRODUCT §Cluster B Inv 6, §Cluster F Inv 14; TECH §2 rows 6+14; TECH §3 order #7.
• status: pending
• dependencies: [8]
• testStrategy: update-skill implement-subtask invocation lands; .claude/skills/implement-subtask/SKILL.md contains literal strings Blast radius: AND Scope verified: AND Pre-commit scope check (manual gate): AND gitnexus_detect_changes(). Sanity: grep -c "gitnexus_detect_changes" .claude/skills/implement-subtask/SKILL.md returns ≥2 (one in Step 4 paragraph + one in Step 5 schema reference).
• priority: must
• effort_h: 0.6
• file_ownership: skill-implement-subtask

ID-23.10 — workflow-curator code-intel pre-grep principle

• id: 10
• title: workflow-curator.md code-intelligence pre-grep operating principle (Inv 8 agent-side)
• description: Add a “Code-intelligence pre-grep” bullet to .claude/agents/workflow-curator.md “Operating principles” section, AND amend Step 3 (Run triage-finding) flow with a reference to the caller-count pre-grep sub-step added by ID-23.11 to triage-finding/SKILL.md.
• details: agent-development workflow-curator invocation. File touched: .claude/agents/workflow-curator.md (insert “Code-intelligence pre-grep” bullet in “Operating principles” section; amend Step 3 flow). No anchor pair required at the agent body level (the freshness guard asserts the skill-side anchor in ID-23.11 only). Required content: bullet text per PRODUCT Inv 8 paraphrase — for any finding whose evidence cites a symbol name or column read/write, the Curator first invokes gitnexus_context({name: '<symbolName>'}) and ast-dataflow callers <symbolName> to obtain deterministic caller count; count drives Branch B (roadmap ≥10 callers across ≥3 modules) vs Branch C (backlog <10 callers OR ≤2 modules) classification. Anchor-name reference (T-OQ-4): bullet cites .gitnexus/CLAUDE.md + .ast-dataflow/CLAUDE.md by path. Pre-Wave-5 prerequisite check (WP0 OQ-B1): verify ID-30 PR-A merge landed on origin/main (git log main --grep "PR-A" -- .claude/skills/triage-finding/SKILL.md | head -3 returns ≥1 commit). If missing, STOP and escalate — Wave 2 prerequisite not satisfied. Spec references: PRODUCT §Cluster B Inv 8; TECH §2 row 8.
• status: pending
• dependencies: [4]
• testStrategy: agent-development workflow-curator invocation lands; .claude/agents/workflow-curator.md contains bullet text mentioning gitnexus_context AND ast-dataflow callers. Sanity: grep -c "gitnexus_context" .claude/agents/workflow-curator.md returns ≥1; pre-flight verification confirmed via git log main --grep "PR-A" -- .claude/skills/triage-finding/SKILL.md returning ≥1.
• priority: must
• effort_h: 0.4
• file_ownership: agent-workflow-curator

ID-23.11 — triage-finding caller-count pre-grep sub-step (SURGICAL ADDITION)

• id: 11
• title: triage-finding/SKILL.md Step 1 caller-count pre-grep sub-step (Inv 8 skill-side) — SURGICAL ADDITION post-Wave-3
• description: Add the “Caller-count pre-grep” sub-step to Step 1 of .claude/skills/triage-finding/SKILL.md. CRITICAL: this is a SURGICAL ADDITION to the post-Wave-3 (post-ID-30 PR-A) rewritten skill body. The Wave-2 rewrite changed Branch B/C semantics under Shape A; this Subtask adds an Inv-8 caller-count pre-grep step at the END of Step 1 without modifying the Branch B/C content.
• details: update-skill triage-finding invocation. SURGICAL-ADDITION CONSTRAINT (OQ-F1 ratification — VERBATIM): Before invoking update-skill triage-finding, run grep -E "Branch B|Branch C" .claude/skills/triage-finding/SKILL.md to confirm the prerequisite ID-30 PR-A merge has landed (Branch B/C semantic rewrite landed Wave 2). If the post-Wave-3 marker is MISSING, STOP and escalate to the Orchestrator — the Wave-5 prerequisite is not satisfied. If the marker is PRESENT, your task is to ADD the Inv 8 caller-count pre-grep sub-step as a surgical insert AT THE END of Step 1 (or at the documented anchor position) WITHOUT modifying the post-Wave-3 Branch B/C rewrite content. Do NOT re-author the file from scratch; do NOT regenerate the entire skill body. Use the update-skill skill’s “edit existing skill” mode with explicit anchor preservation. If update-skill regeneration clobbers the post-Wave-3 Branch B/C content, fall back to manual Edit for the anchor insertion step only. File touched: .claude/skills/triage-finding/SKILL.md (insert “Caller-count pre-grep” sub-step in Step 1). Anchor to author: <!-- code-intel:curator-pregrep-start --> … <!-- code-intel:curator-pregrep-end -->. Required content inside anchor block: sub-step name “Caller-count pre-grep”; invocation patterns gitnexus_context({name: '<symbolName>'}) + ast-dataflow callers <symbolName>; threshold ”≥ 10 callers across ≥ 3 modules” drives Branch B (roadmap); ”< 10 callers OR contained to ≤ 2 modules” drives Branch C (backlog); record-the-count requirement “gitnexus caller count at triage: N callers across M modules” in resulting ledger entry’s notes field. Anchor-name reference (T-OQ-4): sub-step cites .gitnexus/CLAUDE.md + .ast-dataflow/CLAUDE.md by path. Spec references: PRODUCT §Cluster B Inv 8 (verbatim); TECH §2 row 8; TECH §3 order #10. Cross-Task coordination: §5.1 prerequisite verification + §5.3 propagation check.
• status: pending
• dependencies: [10]
• testStrategy: update-skill triage-finding invocation lands AND post-Wave-3 Branch B/C content survived unchanged AND .claude/skills/triage-finding/SKILL.md contains <!-- code-intel:curator-pregrep-start --> … <!-- code-intel:curator-pregrep-end --> pair with content matching /gitnexus_context/ AND /ast-dataflow callers/ AND /≥ 10/ AND /≥ 3 modules/. Sanity: grep -c "code-intel:curator-pregrep" .claude/skills/triage-finding/SKILL.md returns 2 AND grep -c "Branch B" .claude/skills/triage-finding/SKILL.md returns ≥1 (pre-existing post-Wave-3 content intact).
• priority: must
• effort_h: 0.7
• file_ownership: skill-triage-finding

ID-23.12 — task-checker scope-containment + rename-sweep axes

• id: 12
• title: task-checker.md scope-containment + rename-sweep audit axes + JSON schema extension (Inv 7)
• description: Add scope-containment and rename-sweep rows to .claude/agents/task-checker.md “Standard audit axes” table AND extend the JSON output schema’s axis_scores enum with "scope-containment" and "rename-sweep". This is the most anchor-sensitive Subtask: it touches both a markdown table AND a JSON-literal block.
• details: agent-development task-checker invocation. File touched: .claude/agents/task-checker.md (insert two table rows in “Standard audit axes” section; extend axis_scores enum in JSON output schema literal at current line ~310). Anchor to author: <!-- code-intel:checker-axes-start --> … <!-- code-intel:checker-axes-end --> around the table-row insertion. Required content in anchor block: scope-containment row naming gitnexus_detect_changes mechanism; rename-sweep row naming ast-dataflow Q1/Q2/Q3 (string-literal-uses + import-path sweep + new-symbol references). Required content in JSON axis_scores enum: literal keys "scope-containment": AND "rename-sweep": appear in the JSON schema literal block (between the existing axis enum entries; do NOT clobber pre-existing axes). Cross-cutting acceptance: the Checker’s scope-containment audit verifies Executor journal-block lines authored by ID-23.9 (Inv 6 — Blast radius: + Scope verified: lines). Anchor preservation: retain anchor pair verbatim if agent-development regenerates. Spec references: PRODUCT §Cluster B Inv 7; TECH §2 row 7; TECH §3 order #8; TECH §9 R6 (anchor pair collision mitigation).
• status: pending
• dependencies: [9]
• testStrategy: agent-development task-checker invocation lands; .claude/agents/task-checker.md contains <!-- code-intel:checker-axes-start --> … <!-- code-intel:checker-axes-end --> pair AND the literal table-row strings scope-containment + rename-sweep + gitnexus_detect_changes + ast-dataflow.*Q1 AND JSON axis_scores literal "scope-containment": AND "rename-sweep":. Sanity: grep -c '"scope-containment":' .claude/agents/task-checker.md returns ≥1 AND grep -c '"rename-sweep":' .claude/agents/task-checker.md returns ≥1.
• priority: must
• effort_h: 0.8
• file_ownership: agent-task-checker

ID-23.13 — .gitnexus + .ast-dataflow propagation discipline (manual Edit)

• id: 13
• title: .gitnexus/CLAUDE.md + .ast-dataflow/CLAUDE.md propagation-discipline sections (Inv 10) — manual Edit + git-add untracked transition
• description: Add “Propagation discipline” sections to BOTH .gitnexus/CLAUDE.md (currently untracked — transition to tracked via git add in same commit) AND .ast-dataflow/CLAUDE.md (already tracked). Mirrors ID-19.4 hook propagation pattern: sub-agents inherit project-global directive only if Orchestrator’s brief names the tools; escalate if dispatched without instructions on code-touching brief.
• details: Manual Edit mechanism (per Task ID-23 constraint: update-skill / agent-development apply ONLY to .claude/skills/* and .claude/agents/* — NOT to project-global directive files). Files touched (2 files, both repo-root): .gitnexus/CLAUDE.md (insert ## Propagation discipline section before ## CLI table — currently at ~line 35; transition file from untracked to tracked); .ast-dataflow/CLAUDE.md (insert ## Propagation discipline section before final “ast-dataflow does not cover Python or SQL files” section). Anchor to author (BOTH files): <!-- code-intel:propagation-start --> … <!-- code-intel:propagation-end -->. Required content in BOTH files: ## Propagation discipline header; sub-agents inherit project-global directive only if Orchestrator’s brief names the tools per Inv 10; verify before dispatch that brief contains tool-discipline instruction blocks (cite Inv 2, Inv 3, Inv 7, Inv 8 by number); escalate if sub-agent reports being dispatched without tool-discipline instructions on a code-touching brief (brief-composition defect, not sub-agent failure). Mirror to ID-19.4: content paraphrase mirrors CLAUDE.md “Hook propagation discipline (ID-19.4)” bullet; pattern is identical (skill / agent / directive on main branch propagates to sub-agent worktrees at creation). Git-add discipline (R5 mitigation): the commit MUST run git add .gitnexus/CLAUDE.md SPECIFICALLY (not git add .gitnexus/) to avoid accidentally staging other untracked files in the .gitnexus/ directory. Worktree status verification: git status .gitnexus/ returns only .gitnexus/CLAUDE.md as modified/new. Spec references: PRODUCT §Cluster C Inv 10; TECH §2 row 10; TECH §6.1 asymmetry note (untracked vs tracked); TECH §9 R5.
• status: pending
• dependencies: [7, 11, 12]
• testStrategy: Both .gitnexus/CLAUDE.md AND .ast-dataflow/CLAUDE.md contain ## Propagation discipline header AND <!-- code-intel:propagation-start --> … <!-- code-intel:propagation-end --> pair AND mention Inv 2, Inv 3, Inv 7, Inv 8 in the body. .gitnexus/CLAUDE.md now appears in git ls-files (transitioned untracked → tracked). Sanity: git ls-files .gitnexus/CLAUDE.md returns the path AND grep -c "Inv 2" .gitnexus/CLAUDE.md returns ≥1 AND same for .ast-dataflow/CLAUDE.md.
• priority: must
• effort_h: 0.6
• file_ownership: directive-gitnexus-and-ast-dataflow

ID-23.14 — skill-routing-map tilt row 11 (manual Edit)

• id: 14
• title: skill-routing-map.md tilt row 11 — Refactor / Rename / Type-evolution (Inv 12) — manual Edit
• description: Append the 11th row to the “Tilt routing table” in docs/reference/skill-routing-map.md. New tilt: “Refactor / Rename / Type-evolution”. Required skills: gitnexus-refactoring, gitnexus-impact-analysis, ast-dataflow, ast-dataflow-rename-sweep, ast-dataflow-call-chain-pin. Conditional skills: code-simplification, test-driven-development. Anti-patterns: find-and-replace renames; skipping gitnexus_impact on HIGH-risk symbol edits. T-OQ-1 ratification applied: drop registry framing — no lib/docs/tracked-reference-docs.ts registration; manual <!-- Last verified --> header bump only.
• details: Manual Edit mechanism (this is a reference doc, not a skill body — update-skill does not apply). File touched: docs/reference/skill-routing-map.md (append row 11 to “Tilt routing table”; bump <!-- Last verified --> header to authoring date 22/05/2026 in DD/MM/YYYY UK format). No anchor pair required — Inv 12 acceptance is row-content-based (verified by literal-string assertions on the row). Required content in row 11: tilt column === Refactor / Rename / Type-evolution; Required skills column lists all five named — gitnexus-refactoring, gitnexus-impact-analysis, ast-dataflow, ast-dataflow-rename-sweep, ast-dataflow-call-chain-pin; Conditional skills column lists code-simplification, test-driven-development; Anti-patterns column includes “Do NOT use find-and-replace for renames — gitnexus_rename understands the call graph” AND “Do NOT skip gitnexus_impact on HIGH-risk symbol edits”; Example Tasks column lists “column rename across consumers, function extraction, type-narrowing refactor, dead-export sweep”. T-OQ-1 ratification (verbatim from Liam at S65 session-start): “Not required — will be covered by ID-9 (Astro + Warp ported doc skills).” Skip any lib/docs/tracked-reference-docs.ts registration step (that file was removed S249 per CLAUDE.md gotcha). Header bump: update <!-- Last verified: ... --> header to <!-- Last verified: 22/05/2026 --> per UK DD/MM/YYYY discipline. Spec references: PRODUCT §Cluster E Inv 12 + Inv 13; TECH §2 rows 12+13; TECH §3 order #13.
• status: pending
• dependencies: [13]
• testStrategy: docs/reference/skill-routing-map.md contains row 11 with all five named Required skills (grep -c "gitnexus-refactoring" docs/reference/skill-routing-map.md returns ≥1; same for ast-dataflow-rename-sweep); tilt column literal string Refactor / Rename / Type-evolution present; <!-- Last verified --> header bumped to 22/05/2026 UK format. Inv 13 file-existence: docs/reference/skill-routing-map.md exists AND .claude/skills/workflow-orchestration/references/skill-routing-map.md does NOT exist.
• priority: must
• effort_h: 0.4
• file_ownership: reference-skill-routing-map

ID-23.15 — pre-merge propagation verification (manual Edit, read-only against origin/main)

• id: 15
• title: Pre-merge propagation verification — Inv 10 ID-19.4-mirror check against origin/main
• description: Run the propagation-discipline pre-merge check (§5.3) across all 13 surface files to verify each contains the expected code-intel:* anchors (or row-11 marker for skill-routing-map.md) on origin/main. Mirrors ID-19.4 hook propagation pattern. This Subtask produces NO code change — its output is the verification log that gates the freshness-guard Vitest authoring (ID-23.16).
• details: Manual Bash mechanism (read-only operations against origin/main; no file edits). No file touched (verification only). Operation: for each surface file, run git show origin/main:<path> | grep -c "code-intel:" (or specific marker for skill-routing-map.md). Tabulate results. Required pass condition: ALL 12 surface files (excluding skill-routing-map.md, which uses no anchor pair) return ≥1 anchor count on origin/main. The skill-routing-map.md check returns ≥1 for grep "Refactor / Rename / Type-evolution". Failure mode: if any count is 0 on origin/main for a file that should have anchors per ID-23.4-23.13 deliverables, STOP and escalate to the Orchestrator — the propagation gap is the failure mode this Task explicitly mitigates against (Inv 10 + ID-19.4 mirror). Surface inventory verified: the 12 files with code-intel:* anchors are workflow-orchestration/SKILL.md + workflow-orchestration/references/lifecycle-detail.md + task-planner.md + write-product-spec/SKILL.md + write-tech-spec/SKILL.md + task-executor.md + implement-subtask/SKILL.md (Inv 6 + Inv 14 use literal strings, no anchor — adjust check to literal-string presence) + workflow-curator.md (literal bullet, no anchor — adjust check accordingly) + triage-finding/SKILL.md + task-checker.md + .gitnexus/CLAUDE.md + .ast-dataflow/CLAUDE.md. Plus the row-11 check on docs/reference/skill-routing-map.md. Output: a verification log (printed to stdout; no file commit) listing each surface file’s anchor / literal-string / row count from origin/main. Brief-authoring discipline: no absolute sibling-worktree paths in this Subtask’s commands. Use git show origin/main:<repo-relative-path> exclusively. Spec references: PRODUCT §Cluster C Inv 10; TECH §9 R1 (propagation discipline failure mirroring ID-19.4); CLAUDE.md “Hook propagation discipline (ID-19.4)” gotcha.
• status: pending
• dependencies: [14]
• testStrategy: Verification log PRINT confirms all 12 anchor-bearing surface files on origin/main return ≥1 anchor count AND skill-routing-map.md on origin/main returns ≥1 match for “Refactor / Rename / Type-evolution”. If ANY check returns 0, the Subtask FAILS and escalates to Orchestrator — the freshness-guard test (ID-23.16) cannot author until this gate passes.
• priority: must
• effort_h: 0.3
• file_ownership: verification-no-files-touched

ID-23.16 — Freshness-guard Vitest test (Inv 11) — final Subtask

• id: 16
• title: Freshness-guard Vitest test at tests/docs/code-intelligence-integration.test.ts (Inv 11)
• description: Author the Vitest test that regex-asserts all 12 anchor pairs + literal strings + row-11 marker enumerated in TECH §4 anchor inventory. LAST Subtask of Task ID-23 chain — authoring earlier would fail every intermediate commit (TECH §4 baseline-acknowledgement strategy: strict-from-PR-day-1).
• details: Manual Write mechanism (new Vitest file, no skill governs the body — test-driven-development skill discipline applies to the test design pattern). File created: __tests__/docs/code-intelligence-integration.test.ts (NEW). Test shape (per TECH §4 skeleton): import describe, it, expect from vitest; import readFile from node:fs/promises; import existsSync from node:fs. Author REQUIRED_ANCHORS array with 12 entries (one per anchor-bearing surface file per TECH §4 anchor inventory table — repeated here for traceability: workflow-orchestration/SKILL.md × 4 anchor pairs + task-planner.md × 1 + task-executor.md × 1 + task-checker.md × 1 + triage-finding/SKILL.md × 1 + write-product-spec/SKILL.md × 1 + write-tech-spec/SKILL.md × 1 + .gitnexus/CLAUDE.md × 1 + .ast-dataflow/CLAUDE.md × 1). Each entry: file, anchorStart, anchorEnd, requiredContent (array of regex patterns). Additional standalone assertions (not anchor-based): (a) implement-subtask/SKILL.md contains literal strings Blast radius:, Scope verified:, Pre-commit scope check (manual gate), gitnexus_detect_changes (Inv 6 + Inv 14); (b) workflow-curator.md contains literal bullet mentioning gitnexus_context AND ast-dataflow callers (Inv 8 agent-side); (c) lifecycle-detail.md contains literal string cites the gitnexus_impact verdict in BOTH PRODUCT and TECH sub-sections (Inv 15); (d) task-checker.md JSON axis_scores literal includes "scope-containment": AND "rename-sweep": (Inv 7 JSON-schema component); (e) docs/reference/skill-routing-map.md contains row-11 marker Refactor / Rename / Type-evolution AND all five named Required skills (Inv 12); (f) docs/reference/skill-routing-map.md exists AND .claude/skills/workflow-orchestration/references/skill-routing-map.md does NOT exist (Inv 13 file-existence pair); (g) write-tech-spec/SKILL.md “Research before writing” FIRST subsection is Code-intelligence orientation (Inv 9 header-position assertion). Failure message format: 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. per TECH §4 baseline-acknowledgement spec. Run command: bun run test -- code-intelligence-integration (Vitest 4-shard matrix in CI per .github/workflows/ci.yml). Local pre-commit verification: the author runs bun run test -- code-intelligence-integration locally before commit — test MUST PASS on the worktree HEAD after all prior 12 Subtasks have landed. Spec references: PRODUCT §Cluster D Inv 11; TECH §4 in full (Vitest at __tests__/docs/; 12-anchor inventory; baseline-acknowledgement: strict); TECH §3 order #14.
• status: pending
• dependencies: [15]
• testStrategy: Vitest test file exists at __tests__/docs/code-intelligence-integration.test.ts; bun run test -- code-intelligence-integration returns 0 exit code (all anchor + literal-string + file-existence assertions PASS) on the post-Task-23 worktree HEAD; in CI the existing Vitest 4-shard matrix in quality-test job covers the new test file automatically (no .github/workflows/ci.yml edit required).
• priority: must
• effort_h: 1.2
• file_ownership: test-freshness-guard

7.1 Summary table

ID	Title	Mechanism	Surface	Effort (h)	Deps
23.4	workflow-orchestration baseline + role blocks + lifecycle-detail	update-skill (bundle)	workflow-orchestration skill bundle	1.5	—
23.5	task-planner Planner block	agent-development	agent task-planner	0.5	[4]
23.6	write-product-spec orientation	update-skill	skill write-product-spec	0.5	[5]
23.7	write-tech-spec orientation + conventions	update-skill	skill write-tech-spec	0.5	[6]
23.8	task-executor Executor block	agent-development	agent task-executor	0.5	[4]
23.9	implement-subtask journal schema + commit gate	update-skill	skill implement-subtask	0.6	[8]
23.10	workflow-curator pre-grep principle	agent-development	agent workflow-curator	0.4	[4]
23.11	triage-finding caller-count pre-grep (SURGICAL)	update-skill (surgical add)	skill triage-finding	0.7	[10]
23.12	task-checker scope-containment + rename-sweep axes	agent-development	agent task-checker	0.8	[9]
23.13	.gitnexus + .ast-dataflow propagation	Manual Edit	directive files (2)	0.6	[7, 11, 12]
23.14	skill-routing-map row 11	Manual Edit	reference doc	0.4	[13]
23.15	Pre-merge propagation verification	Manual Bash (read-only)	none (verification only)	0.3	[14]
23.16	Freshness-guard Vitest test	Manual Write	new test file	1.2	[15]
Total	13 Subtasks			8.5h

Total effort 8.5h is within TECH §11’s grand-total range (6.5-9.5h); slightly above TECH §11’s “grouped” estimate (5-7h) because this PLAN adds an explicit verification Subtask (ID-23.15) the TECH outline did not enumerate — surfaced via WP0 OQ-F1 surgical-additions discipline + ID-19.4 mirror.

§8 Risks

#	Risk	Likelihood	Impact	Mitigation in this PLAN
R1	Propagation discipline failure mirroring ID-19.4 — surface edits land on production-readiness but not on main; sub-agent worktrees dispatch without the code-intel anchors	HIGH	HIGH	(a) ID-23.15 explicit pre-merge verification Subtask runs the §5.3 check across all 13 surfaces; STOPS and escalates on any 0-count. (b) ID-23.16 freshness-guard test runs on EVERY PR base (main and production-readiness) via existing CI matrix. (c) Per-Subtask details field carries the git show origin/main:... pre-check pattern for curator-skill Subtasks (ID-23.10, ID-23.11)
R2	update-skill regeneration clobbers anchors — running update-skill on a SKILL.md regenerates the body from LLM reasoning; anchor pairs may be dropped on regeneration	MEDIUM	MEDIUM	Every update-skill Subtask’s details field carries the verbatim anchor-preservation instruction (TECH §4 last paragraph) + fallback to manual Edit for anchor insertion if regeneration drops pairs. ID-23.16 freshness guard catches subsequent regressions on next PR
R3	OQ-F1 surgical-additions violation — ID-23.11 re-authors triage-finding from scratch	MEDIUM	HIGH	ID-23.11 details field embeds the §6 surgical-additions template verbatim + pre-dispatch grep for the post-Wave-3 Branch B/C marker. STOPS and escalates on missing marker. PLAN’s §6 makes the constraint load-bearing — no Subtask can be dispatched without the template in its brief
R4	Sequential dispatch constraint slips — Orchestrator dispatches 2+ update-skill in parallel	MEDIUM	MEDIUM	Every Subtask’s dependencies[] enforces strict serialisation. The Orchestrator’s topological dispatch respects dependencies[] automatically. Documented in §5.2 sequential-dispatch table
R5	.gitnexus/CLAUDE.md git-add scope creep — git add .gitnexus/CLAUDE.md could be mistyped as git add .gitnexus/ and stage unrelated untracked files	LOW	LOW	ID-23.13 details field names the specific file path verbatim (git add .gitnexus/CLAUDE.md); worktree status verification step confirms only the intended file modified. Mirrors TECH §9 R5 mitigation
R6	Wave-5 entry preconditions slip — ID-30 PR-A or ID-31 §6.4 not merged when ID-23 dispatch attempts	MEDIUM	HIGH	§4.1 entry preconditions enumerated; ID-23.10 + ID-23.11 carry pre-dispatch git log verification commands. STOP and escalate to Orchestrator on missing prereq. Pre-flight check is the Orchestrator’s responsibility before dispatching ID-23.4
R7	JSON-literal regression in task-checker.md (ID-23.12) — agent-development regenerates the agent body and breaks the axis_scores enum’s JSON syntax	MEDIUM	MEDIUM	ID-23.12 is the most anchor-sensitive Subtask; details field calls out the JSON-literal block edit explicitly. Fallback: manual Edit for the JSON enum extension if agent-development cannot preserve syntactic correctness. ID-23.16 freshness guard’s axis_scores assertion catches subsequent regressions
R8	Anchor name collision — future skill body uses HTML comments for unrelated purpose accidentally matching code-intel:* regex	LOW	LOW	Anchor namespace code-intel: is specific enough; freshness guard regex is <!-- code-intel:[a-z]+-(start|end) --> — narrow enough to avoid collision. Documented in TECH §9 R6

§9 Notes for ID-23.4+ Executor dispatches

These notes carry forward into every implementation Subtask’s dispatch brief — the Orchestrator should fold them into the brief composition for ID-23.4 through ID-23.16:

1. Worktree verification gate first. Every Subtask Executor’s first action is the no-cd verification block per CLAUDE.md “Hook propagation discipline (ID-19.4)” + ID-19 worktree-isolation pattern: pwd && git branch --show-current && git fetch origin production-readiness && git reset --hard origin/production-readiness && git branch --show-current (no cd prefix). The branch must equal worktree-agent-<id> after reset.
2. Anchor preservation discipline (encoded per Subtask): retain all <!-- code-intel:*-start --> / <!-- code-intel:*-end --> anchor pairs verbatim through update-skill / agent-development regeneration. Fall back to manual Edit if regeneration clobbers any pair.
3. Surgical-additions discipline (ID-23.11 specifically, per OQ-F1): read the post-Wave-3 form of triage-finding/SKILL.md FIRST. Verify Branch B/C marker present. Surgical insert only.
4. Pre-merge propagation check (ID-23.10, ID-23.11): verify ID-30 PR-A landed on origin/main BEFORE editing curator skills. STOP on missing prereq.
5. Sequential dispatch only (CLAUDE.md “Sub-agents struggle with multi-skill invocations” + S59 + S60 stall pattern): no parallel /update-skill invocations. The PLAN’s dependencies[] enforces this structurally.
6. Brief-authoring discipline (CLAUDE.md): every Subtask details uses relative paths only. The sole exception is git show origin/main:<relative-path> (worktree- safe pattern).
7. UK English throughout every body edit: “colour”, “organisation”, “behaviour”, DD/MM/YYYY dates (per KH convention).
8. Cite the spec back (per Inv 15 cite-the-impact-verdict pattern, applied transitively): every Subtask’s commit message names the PRODUCT inv number + TECH §-reference: e.g. feat(s68-id-23.11): triage-finding caller-count pre-grep (Inv 8 / TECH §2 row 8).

§10 References

• Linked PRODUCT spec: docs/specs/id-23-code-intelligence-integration/PRODUCT.md (16 invariants + 21-cell matrix + 5 P-OQs)
• Linked TECH spec: docs/specs/id-23-code-intelligence-integration/TECH.md (703 lines; 16 Proposed-changes table; §3 topological order; §4 anchor inventory; §7 13-Subtask outline; §10 5 T-OQs)
• WP0 cross-Task dependency map: docs/research/cross-task-dependency-map-and-sequencing.md (1014 lines; §3 row 5 curator-skill stampede; §6 Wave 5 placement; §7 OQ-B1 + OQ-F1 ratifications)
• Task ID-23 record: docs/reference/task-list.json → .tasks[] where id === "23" (spec chain 23.1 / 23.2 in_progress; 23.3 this PLAN)
• Cross-Task prerequisites (Wave 2 / 3):
  • docs/specs/id-30-roadmap-backlog-consolidation/TECH.md (ID-30 PR-A schema + curator skill rewrite)
  • docs/specs/id-31-canonical-pipeline-task-list-migration/TECH.md §6.4 (ID-31 Promote- mode umbrella_id extension)
• Prior-art pattern: ID-19.4 hook propagation (docs/research/hook-cwd-prefix-gap-investigation.md) — directly mirrored by ID-23.13 propagation discipline + ID-23.15 pre-merge verification
• Tooling directives (sources of truth):
  • .gitnexus/CLAUDE.md (untracked at PLAN time; transitions to tracked in ID-23.13)
  • .ast-dataflow/CLAUDE.md (tracked)
  • ~/.agents/skills/ccc/SKILL.md (user-global; out of scope for body edits per P-OQ-3)
• Skill catalogue (existing — no new skill authoring):
  • update-skill skill — used for all SKILL.md body edits
  • agent-development skill — used for all agent .md body edits
• KH conventions (apply throughout authoring):
  • .planning/codebase/STRUCTURE.md — directory layout
  • docs/reference/test-philosophy.md — tests verify behaviour, not implementation
  • docs/reference/SCHEMA-QUICK-REFERENCE.md — DB schema (N/A for this Task)
  • docs/design/warm-meridian-implementation-spec.md — semantic tokens (N/A — no UI)
• S249 removed pattern (informs T-OQ-1 ratification): commit 4d4524d3 removed __tests__/docs/reference-doc-edit-coupled-freshness.test.ts and lib/docs/tracked-reference-docs.ts — current freshness posture is manually-bumped headers, NOT CI-enforced via registry