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

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

Summary

Integrate the three code-intelligence tools — gitnexus (MCP server, 36,955-symbol graph + 12 queries), ast-dataflow (CLI, 12 ts-morph queries + 9 cross-tool patterns) and ccc (cocoindex-code, semantic codebase index + concept-guide lookup) — into the seven SDLC dispatch surfaces of the Knowledge Hub workflow so that every code-touching sub-agent invocation has a deterministic, named tool-discipline expectation. Today the S61 WP5 audit measured 63 of 63 tool-integration cells MISSING: sub-agents read Orchestrator-extracted gotchas but never .gitnexus/CLAUDE.md / .ast-dataflow/CLAUDE.md directly, so the infrastructure is dead. After this Task lands, the contract for “what a Planner / Executor / Checker / Curator does with the index” is encoded in skill and agent bodies as testable invariants, and a freshness guard prevents future drift.

Problem

Three concrete failure modes the integration eliminates:

• Blind edits. Executors modify symbols without gitnexus_impact first; HIGH / CRITICAL blast-radius warnings never reach the user, regressions land downstream.
• Spec-blind decomposition. Planners author PRODUCT.md / TECH.md without gitnexus_query / gitnexus_context orientation, so spec invariants miss real callers and over-scope the surface area.
• Manual roadmap-vs-backlog guessing. Curators triage findings without gitnexus caller counts to anchor the roadmap-vs-backlog decision, so the binary in-scope-ness rule degrades into intuition.

The three tools already exist, are installed, and are indexed against the current KH corpus. The gap is purely propagation: the Orchestrator’s dispatch brief does not name them, so sub-agents do not invoke them.

Goals

1. Every code-touching dispatch brief names the appropriate code-intelligence tool(s) so the sub-agent invokes them as a deterministic pre-step (not as optional enrichment).
2. Tool-discipline expectations (pre-edit impact analysis, post-rename sweep, audit-time detect-changes) are encoded in skill/agent bodies so propagation survives sub-agent context resets.
3. A freshness guard prevents the integration from regressing — if a new agent body or dispatch surface lands without code-intelligence cells populated, CI catches it.

Non-goals

• Authoring new tools or queries. All three tools exist; this Task only wires them.
• Replacing the binary in-scope-ness rule. The §6.2 file-path / axis predicate stays canonical; gitnexus caller counts become an input to Curator triage, not a replacement for the predicate.
• Forcing tool invocation on documentation-only changes. UK-English copy edits, ADR appends, and pure-prose updates are explicitly out of scope for tool-discipline enforcement.
• Indexing changes (re-running npx gitnexus analyze is operational, not specified here). Stale-index handling is referenced via the existing project-global directive; cadence for re-indexing remains an Orchestrator concern.

Coverage matrix — 7 dispatch surfaces × 3 tools

The matrix below shows which Behavior invariant covers each surface × tool cell. Cells marked N/A are explicitly out of scope, with justification immediately below the table. Every populated cell maps to at least one numbered invariant in the Behavior section.

#	Dispatch surface	gitnexus	ast-dataflow	ccc
1	workflow-orchestration (Orchestrator skill)	Inv 1, Inv 4	Inv 1, Inv 4	Inv 1, Inv 4
2	task-planner (agent) + write-product-spec	Inv 2, Inv 5	Inv 2 (N/A — see)	Inv 2
3	task-executor + implement-subtask	Inv 3, Inv 6	Inv 3, Inv 6	Inv 3 (N/A — see)
4	task-checker (agent)	Inv 7	Inv 7	Inv 7 (N/A — see)
5	workflow-curator + triage-finding	Inv 8	Inv 8	Inv 8 (N/A — see)
6	write-tech-spec (Planner foundation skill)	Inv 9	Inv 9	Inv 9
7	.gitnexus/CLAUDE.md + .ast-dataflow/CLAUDE.md	Inv 10	Inv 10	Inv 10 (N/A — see)

N/A justifications:

• Row 2 (Planner) × ast-dataflow: Planners author specs from product intent; precise call-site enumeration belongs to the Executor’s implementation slice loop. Planners may consult ast-dataflow opportunistically but invocation is not mandated — listing it would pad briefs without changing decomposition quality.
• Row 3 (Executor) × ccc: Executors work against a details-field brief that already names files and functions; semantic codebase search adds noise rather than signal in the scoped slice loop. ccc is a Planner / Curator orientation tool.
• Row 4 (Checker) × ccc: Checker reading order (§4.3 — spec slice → testStrategy → journal → diff) precludes semantic codebase search; spec compliance is the bar, not “what else might exist in the codebase”.
• Row 5 (Curator) × ccc: Curators read roadmap + backlog + finding packet — adding a third semantic search degrades single-pass decision discipline. Curators rely on gitnexus caller counts (deterministic) and ast-dataflow (precise call sites), not semantic similarity.
• Row 7 × ccc: ccc has no project-global directive analogue to .gitnexus/CLAUDE.md / .ast-dataflow/CLAUDE.md; it operates via the ccc skill catalogue alone. Open question P-OQ-3 captures whether a .ccc/CLAUDE.md should be authored under this Task; default is NO (treat ccc as skill-catalogue-only).

Every non-N/A cell is covered by at least one numbered Behavior invariant below.

Behavior

The spec consumer is the Orchestrator (main session) dispatching sub-agents, and the sub-agents themselves (Planner / Executor / Checker / Curator) reading their dispatch briefs. Behavior is described from the perspective of how a dispatch flows — what the Orchestrator must put into the brief, what the sub-agent must do on receipt, and what the freshness guard does if the integration regresses.

Cluster A — Orchestrator brief composition (Inv 1, 4)

1. Code-touching dispatch briefs name the appropriate code-intelligence tool(s). When the Orchestrator composes a dispatch brief whose scope includes editing, renaming, refactoring, or auditing TypeScript / TSX / JavaScript code under app/, lib/, components/, hooks/, contexts/, types/, or scripts/ (the ast-dataflow-covered corpus, see Cluster G), the brief MUST name:

   • For Planner dispatches ({N.2} PRODUCT or {N.3} TECH): gitnexus_query (for execution-flow orientation) and gitnexus_context (when the spec slice touches a specific symbol). ccc is named when the surface is unfamiliar to the Orchestrator (e.g. new domain area), per the dispatch primitives §5.4 of workflow-orchestration.
   • For Executor dispatches (any {N.5+} implementation Subtask): gitnexus_impact (mandatory pre-edit per symbol) and gitnexus_detect_changes (mandatory pre-commit scope-creep check). ast-dataflow is named when the brief includes a rename or a call-chain-pin scenario.
   • For Checker dispatches (standard or quality-review variant): gitnexus_detect_changes (mandatory commit-scope audit) and either gitnexus_route_map / gitnexus_api_impact (when the audit includes new public API routes) or ast-dataflow Q1/Q2/Q3 (when the audit includes a rename verification).
   • For Curator dispatches: gitnexus_context + ast-dataflow callers query (mandatory pre-grep step in triage-finding Step 1 — caller count drives the roadmap-vs-backlog signal).

   Acceptance: a static brief-composition test (or Orchestrator self-check) confirms that every code-touching dispatch brief authored from the workflow-orchestration skill body contains the tool name(s) for its surface.

2. Planner brief template carries gitnexus orientation instructions verbatim. The workflow-orchestration skill body (or its lifecycle-detail.md reference) carries a verbatim instruction block for {N.2} PRODUCT and {N.3} TECH Planner dispatches that reads (paraphrased): “Before drafting spec invariants, invoke gitnexus_query on the feature concept and gitnexus_context on any symbol the brief names. Cite the resulting execution-flow IDs and direct-caller counts in the spec’s Context (TECH) or Problem (PRODUCT) section.” This instruction is mechanically copied into every Planner dispatch brief by the Orchestrator — sub-agents do not auto-discover it.

   Acceptance: a Planner brief audit confirms the instruction block appears verbatim in every {N.2} / {N.3} dispatch brief authored after this Task ships.

3. Executor brief template carries pre-edit + pre-commit gitnexus discipline. The workflow-orchestration skill body carries a verbatim instruction block for Executor dispatches that reads (paraphrased): “Before editing any function, class, or method, invoke gitnexus_impact({target: '<symbolName>', direction: 'upstream'}) and report the blast radius. HIGH or CRITICAL risk warnings MUST be surfaced to the Orchestrator before proceeding. Before invoking commit-commands, invoke gitnexus_detect_changes() to verify the diff only affects expected symbols.” This block is copied into every Executor dispatch brief — sub-agents do not need to read .gitnexus/CLAUDE.md independently (though they may).

   Acceptance: an Executor brief audit confirms the instruction block appears verbatim in every {N.5+} implementation dispatch brief, AND the <info added on …> journal block of completed Executor Subtasks shows evidence of gitnexus_impact invocation (e.g. “blast radius: LOW (3 callers)” lines).

4. Code-intelligence baseline section in workflow-orchestration SKILL.md. A load-bearing section in the workflow-orchestration skill body titled “Code-intelligence baseline” codifies the Orchestrator’s responsibility to propagate gitnexus / ast-dataflow / ccc tool mandates into every code-touching dispatch brief. The section enumerates: (a) the matrix of which tool applies to which sub-agent role, (b) the verbatim instruction blocks per role (referenced from lifecycle-detail.md or inlined), (c) the freshness guard’s expectations (Inv 11), (d) what counts as a “code-touching” dispatch (file-extension allowlist).

   Acceptance: the workflow-orchestration SKILL.md (or a referenced references/code-intelligence.md file) contains a section titled “Code-intelligence baseline” with the four enumerated items present.

Cluster B — Sub-agent receipt-side behaviours (Inv 5, 6, 7, 8)

5. Planners cite gitnexus orientation in spec artefacts. When a Planner produces PRODUCT.md or TECH.md, the resulting spec document references at least one gitnexus_query / gitnexus_context finding in its Problem (PRODUCT) or Context (TECH) section — either as an execution-flow name (e.g. “process: bid-response-edit”), a symbol’s caller count (e.g. “12 direct callers across 4 modules”), or a cluster ID. If the feature is genuinely greenfield with no relevant existing symbols, the spec explicitly notes “gitnexus orientation: no existing symbols match — greenfield surface” rather than omitting the citation silently.

   Acceptance: every PRODUCT.md / TECH.md authored after this Task ships either cites a gitnexus finding or carries the explicit “greenfield surface” disclaimer in its first numbered section.

6. Executors run pre-edit gitnexus_impact per modified symbol and record verdicts in the journal. During the implement-subtask Step 4 slice loop, the Executor invokes gitnexus_impact({target: '<symbolName>', direction: 'upstream'}) once per to-be-modified function / class / method before writing the slice. The Executor reports HIGH / CRITICAL verdicts to the Orchestrator inline (escalation per §4.2) rather than proceeding silently, and records the LOW / MEDIUM verdicts in the <info added on …> journal block on the Subtask’s details field. The journal block also records the pre-commit gitnexus_detect_changes() output (expected vs actual symbol set).

   Acceptance: the <info added on …> journal block schema (Step 5 of implement-subtask) is amended to include lines like “Blast radius: ( callers)” and “Scope verified: gitnexus_detect_changes matched expected symbol set”, and Executor commits whose details journal omits these lines are flagged by the Checker (Inv 7).

7. Checkers run gitnexus_detect_changes and audit scope-containment per commit. The task-checker agent’s standard variant (and quality-review variant) audit axes include scope-containment — verified by invoking gitnexus_detect_changes() against each commit under audit and confirming the affected symbol set falls within the ALLOWED file-ownership boundary. For commits introducing new public API routes (app/api/**/route.ts), the Checker additionally invokes gitnexus_route_map / gitnexus_api_impact to assess downstream consumer impact. For commits where the Executor journal block records a rename, the Checker invokes the ast-dataflow rename-sweep (Q1 string-literal sites + Q2 import-path sweep + Q3 new-symbol references) and reports any residual edits as code-quality findings.

   Acceptance: task-checker.md Standard audit axes table includes a scope-containment row (with gitnexus_detect_changes named) and a renamed rename-sweep row (with ast-dataflow Q1/Q2/Q3 named); the JSON output schema’s axis_scores enum includes "scope-containment".

8. Curators run gitnexus caller counts as a deterministic roadmap-vs-backlog signal. The triage-finding skill’s Step 1 (check for existing coverage) is amended to include a “Caller-count pre-grep” sub-step: for any finding whose evidence cites a symbol name (function, class, method) or column read/write, the Curator first invokes gitnexus_context({name: '<symbolName>'}) and ast-dataflow callers <symbolName> to obtain the deterministic caller count. The count drives Branch B (roadmap candidate) vs Branch C (backlog candidate) classification: callers ≥ 10 across ≥ 3 modules signals cross-cutting → Branch B (roadmap); callers < 10 OR contained to ≤ 2 modules signals single-feature → Branch C (backlog). The count is recorded in the resulting ledger entry’s notes field as “gitnexus caller count at triage: N callers across M modules” so future Curators can re-audit the decision.

   Acceptance: triage-finding/SKILL.md Step 1 contains the “Caller-count pre-grep” sub-step with the ≥ 10 / ≥ 3 module threshold called out, and every Curator-authored roadmap or backlog entry whose finding cited a symbol carries the caller-count notes line.

Cluster C — Foundation skill propagation (Inv 9, 10)

9. write-tech-spec skill body prescribes first-line code-intelligence research pattern. The write-tech-spec skill’s “Research before writing” section is amended to require, as the first-line research pattern: (a) gitnexus_query on the feature concept to find relevant execution flows, (b) gitnexus_context on each named symbol in the PRODUCT.md to obtain caller counts and process membership, (c) ccc semantic search when the surface area is unfamiliar (e.g. new domain), and (d) ast-dataflow queries (column-reads / column-writes for schema-touching changes, callers for refactor scenarios) when the spec slice references a specific data column or refactor. The skill body’s “Knowledge Hub conventions to ground the plan in” list is extended with a “Code intelligence” row pointing to .gitnexus/CLAUDE.md and .ast-dataflow/CLAUDE.md.

   Acceptance: write-tech-spec/SKILL.md “Research before writing” section’s first subsection is titled “Code-intelligence orientation” (or equivalent) and enumerates the four steps above.

10. Project-global directive files carry propagation-discipline bullets. Both .gitnexus/CLAUDE.md and .ast-dataflow/CLAUDE.md are amended with a “Propagation discipline” bullet (in the “Always Do” section for gitnexus; in “When each skill applies” or equivalent for ast-dataflow) that mirrors the ID-19.4 hook propagation rule (CLAUDE.md “Hook propagation discipline”). Content (paraphrased): “Sub-agents inherit the project-global directive only if the Orchestrator’s dispatch brief names the tools. Verify before dispatch that the Orchestrator’s brief contains the tool-discipline instruction blocks (Inv 2, 3, 7, 8). If a sub-agent reports it was dispatched without tool-discipline instructions on a code-touching brief, escalate immediately — this is a brief-composition defect, not a sub-agent failure.”

    Acceptance: .gitnexus/CLAUDE.md “Always Do” section contains a Propagation discipline bullet citing Inv 2/3/7/8; .ast-dataflow/CLAUDE.md contains an equivalent bullet in its “When each skill applies” section.

Cluster D — Freshness guard (Inv 11)

11. Freshness guard catches integration regressions. A guard test (or pre-commit / CI check) verifies that:

    • The workflow-orchestration SKILL.md (or a referenced code-intelligence.md reference file) contains a “Code-intelligence baseline” section (Inv 4).
    • The Planner / Executor / Checker / Curator brief instruction blocks (Inv 2, 3, 7, 8) are present at named anchors (e.g. <!-- code-intel:planner-block -->).
    • .gitnexus/CLAUDE.md “Always Do” and .ast-dataflow/CLAUDE.md carry Propagation-discipline bullets (Inv 10).
    • task-checker.md Standard audit axes table includes scope-containment and rename-sweep rows (Inv 7).
    • triage-finding/SKILL.md Step 1 carries the “Caller-count pre-grep” sub-step (Inv 8).
    • write-tech-spec/SKILL.md carries the “Code-intelligence orientation” subsection (Inv 9).
    • skill-routing-map.md includes the Refactor / Rename / Type-evolution tilt row (Inv 12).

    If any anchor is removed or any required text is missing, the guard fails the build with a directive to invoke the appropriate update-skill / agent-development sub-agent to restore it. The guard’s location is either a Vitest test under __tests__/docs/code-intelligence-integration.test.ts or a pre-commit hook in .claude/settings.json (CI is the canonical surface — P-OQ-2 captures the decision).

    Acceptance: the guard exists at the location named by the P-OQ-2 ratification, fails when any of the above anchors are removed, and passes on the post-Task-23 HEAD.

Cluster E — Skill-routing-map extension (Inv 12, 13)

12. skill-routing-map.md gains a Refactor / Rename / Type-evolution tilt row. The skill routing map’s “Tilt routing table” is extended with a new tilt row covering refactor, rename, and type-evolution Tasks. Required skills: gitnexus-refactoring, gitnexus-impact-analysis, ast-dataflow, ast-dataflow-rename-sweep, ast-dataflow-call-chain-pin. Conditional skills: code-simplification (end-of-task pass); test-driven-development (if behaviour is observable). Anti-patterns: “Do NOT use find-and-replace for renames — gitnexus_rename understands the call graph”; “Do NOT skip gitnexus_impact on HIGH-risk symbol edits”. Example Tasks: column rename across consumers, function extraction, type-narrowing refactor, dead-export sweep.

    Acceptance: skill-routing-map.md contains a row with tilt = "Refactor / Rename / Type-evolution" and the named Required / Conditional / Anti-pattern fields populated.

13. Skill-routing-map location ratified — current docs/reference/ retained. The skill-routing-map remains at docs/reference/skill-routing-map.md (the current location) and is not moved to .claude/skills/workflow-orchestration/references/skill-routing-map.md. Rationale: the map is a Liam-facing lookup table consulted at dispatch composition time, not a sub-agent skill body. Tracked in lib/docs/tracked-reference-docs.ts so the <!-- Last verified --> header maintenance discipline applies. P-OQ-1 captures whether to overturn this default; default is retain.

    Acceptance: 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. If P-OQ-1 ratifies the move, Inv 13 is re-authored as part of the ratification’s amendment.

Cluster F — Journal + traceability (Inv 14, 15)

14. commit-commands integration note in implement-subtask Step 4. The implement-subtask skill body’s Step 4 (Commit) is amended with an integration note (paraphrased): “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.” The note explicitly disclaims that this is a current manual gate (acknowledged in the integration note); future automation is tracked separately.

    Acceptance: implement-subtask/SKILL.md Step 4 contains a paragraph beginning “Pre-commit scope check (manual gate):” (or equivalent) with the gitnexus_detect_changes() invocation named and the escalation path described.

15. lifecycle-detail.md carries cite-the-impact-verdict requirement for Planner sections. The workflow-orchestration/references/lifecycle-detail.md file’s PRODUCT and TECH Planner sub-sections are amended with a one-paragraph requirement (paraphrased): “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. This becomes part of the spec’s risk-mitigation language and informs the Executor’s slice loop sizing.”

    Acceptance: lifecycle-detail.md PRODUCT-Planner sub-section and TECH-Planner sub-section each contain the cite-the-impact-verdict paragraph.

Cluster G — Scope & non-applicability boundaries (Inv 16)

16. Tool-discipline scope is bounded by file-extension allowlist. The “code-touching” classification that triggers Inv 1’s tool-naming requirement is bounded to:

    • *.ts, *.tsx, *.js, *.jsx, *.mjs, *.cjs (TypeScript / JavaScript corpus — ast-dataflow + gitnexus coverage).
    • app/**, lib/**, components/**, hooks/**, contexts/**, types/**, scripts/** (gitnexus-indexed directories).

    Dispatches that touch ONLY the following are out of scope for tool-discipline enforcement (the brief may omit tool names without freshness-guard penalty):

    • *.md, *.mdx, *.txt (documentation).
    • *.json for docs/reference/product-roadmap.json, docs/reference/product-backlog.json, docs/reference/task-list.json (ledger files — ast-dataflow + gitnexus do not index JSON).
    • *.py (Python pipeline — ast-dataflow does not cover Python, per .ast-dataflow/CLAUDE.md; the dispatch brief may name a grep sweep instead).
    • *.sql (Supabase migrations — ast-dataflow does not cover SQL; the brief may name a grep sweep + the supabase-postgres-best-practices skill instead).

    For mixed dispatches (e.g. TypeScript + Markdown), the TypeScript portion governs: if any in-scope file is touched, tool-discipline applies to the whole brief.

    Acceptance: the workflow-orchestration “Code-intelligence baseline” section (Inv 4) enumerates the allowlist and disclaimers above; the freshness guard (Inv 11) does not fire on documentation-only dispatches.

Open questions (for Liam ratification)

The following Open Questions surfaced during spec authoring and require ratification before {N.3} TECH or {N.4} PLAN dispatch. Each has a default and a stated alternative. Defaults assume “lightest-touch propagation” unless evidence points otherwise.

P-OQ-1 — Skill-routing-map location. Default: retain at docs/reference/skill-routing-map.md (Liam-facing lookup, current location, tracked freshness header — Inv 13 is satisfied as written). Alternative: move to .claude/skills/workflow-orchestration/references/skill-routing-map.md (treat as Orchestrator-internal reference, drop the public-doc convention). Reason for surfacing: the Task description’s acceptance criteria explicitly call for this ratification, and the “references/” pattern is now used for other workflow-orchestration sub-files (checker-output-schema.md, lifecycle-detail.md, etc.). If P-OQ-1 ratifies the move, Inv 13 needs amendment.

P-OQ-2 — Freshness-guard surface. Default: Vitest test under __tests__/docs/code-intelligence-integration.test.ts (CI-enforced, runs on every PR). Alternative: pre-commit hook in .claude/settings.json (local-enforced, faster feedback but bypassable with --no-verify — which CLAUDE.md forbids anyway). Reason for surfacing: the canonical pattern for tracked-reference-doc freshness was removed S249 (reference-doc-edit-coupled-freshness.test.ts); the project’s posture is now “manually-bumped headers, CI-asserted invariants”. A Vitest test fits the new posture; a pre-commit hook would re-introduce the rejected pattern.

P-OQ-3 — ccc project-global directive file. Default: do not author .ccc/CLAUDE.md (treat ccc as skill-catalogue-only, like Knip or Prettier). Alternative: author .ccc/CLAUDE.md for symmetry with .gitnexus/CLAUDE.md and .ast-dataflow/CLAUDE.md, so the three code-intelligence tools have parallel propagation surfaces. Reason for surfacing: ccc is the only tool of the three without a project-global directive; if cell N/A is wrong (ccc warrants the same propagation discipline), Inv 10 needs extension and the coverage matrix needs a new entry.

P-OQ-4 — Greenfield-surface disclaimer wording. Default: PRODUCT / TECH specs may satisfy Inv 5 with the literal text “gitnexus orientation: no existing symbols match — greenfield surface” in the first numbered section. Alternative: require an explicit gitnexus_query invocation log (e.g. “queried gitnexus_query({query: 'foo'}) → 0 results”) rather than a free-text disclaimer, to make the audit trail machine-verifiable. Reason for surfacing: the default is human-readable but bypassable; the alternative is strict but adds Planner overhead on greenfield Tasks. The freshness guard’s design (Inv 11) depends on which wording becomes canonical.

P-OQ-5 — Tool-discipline gating on documentation-only dispatches with embedded code references. Default: documentation-only dispatches (Inv 16’s out-of-scope list) skip tool-discipline even when the documentation cites code (e.g. an ADR referencing lib/foo/bar.ts:42). Alternative: dispatches that reference code in documentation must invoke gitnexus_context on cited symbols to confirm the reference is still accurate. Reason for surfacing: stale code references in docs are a real failure mode (observed S250 in cross-surface-schema-alignment.md errata); enforcing the lookup catches drift. The cost is Planner overhead on every documentation update.

Notes for {N.3} TECH (fresh Planner)

• Per-file edit sequence — TECH must enumerate the order in which the 11 surface files are amended (Inv 1–10 + 12 + 14 + 15 map to specific files). Sequential dispatch is mandated per Task ID-23 Constraints (one skill body per Executor brief); TECH should resolve the topological order against any inter-file references (e.g. Inv 4’s section refers to Inv 11’s guard — the guard must exist before the section can cite it, or the section pre-declares the guard’s expected location).
• Freshness-guard implementation — TECH must choose the P-OQ-2 default (Vitest test) OR ratify the alternative, and specify the test’s shape: regex anchors per file, pre-commit-hook integration if applicable, baseline acknowledgement strategy if the guard initially trips on legacy content not yet retrofitted.
• update-skill / agent-development invocation pattern — TECH must specify the per-file invocation pattern for the 11 files. Per Task Constraints, manual Edit on .claude/skills/*/SKILL.md or .claude/agents/*.md is forbidden — every body edit goes through update-skill (for SKILL.md) or agent-development (for agent .md). The observed S59 + S60 stall pattern requires sequential dispatch (no parallel Executors on this Task).
• Anchor naming convention — TECH should propose anchor names (e.g. <!-- code-intel:planner-block -->) for the freshness guard to target, and confirm they survive update-skill regeneration cycles without being clobbered.
• .gitnexus/CLAUDE.md + .ast-dataflow/CLAUDE.md edit pattern — these are not skill bodies; manual Edit is permitted per Task Constraints (the constraint covers .claude/skills/* and .claude/agents/* only). TECH should note this asymmetry.
• Tracked-reference-doc registration — if Inv 13 ratifies P-OQ-1’s alternative (move skill-routing-map), TECH must update lib/docs/tracked-reference-docs.ts to reflect the new location.

OQ → Invariant trace

OQ	Affected invariant(s)	Decision impact
P-OQ-1	Inv 13	If ratified ALT: Inv 13 amended to move file; tracked-reference-doc registry updated.
P-OQ-2	Inv 11	Default: Vitest test surface; ALT: pre-commit hook surface (TECH must specify).
P-OQ-3	Inv 10, matrix row 7	If ratified ALT: .ccc/CLAUDE.md authored; Inv 10 extended; matrix row 7 column 3 changes from N/A.
P-OQ-4	Inv 5, Inv 11	Default: free-text disclaimer; ALT: machine-readable log line (changes guard regex).
P-OQ-5	Inv 16	Default: docs-only dispatches skip tool discipline; ALT: docs-only with code references invoke gitnexus_context.