Tracker Phase 2 — contract/mechanics split (GitHub only)

[dean0x]

Initial Request

src/assets/agents/git.md is 938 L / 59,376 ch [verified @ e726874], re-sent on every Git spawn (PF-026: a shared agent prompt file is billed PER SPAWN). Roughly 9,400 of those characters are GitHub-specific mechanics — gh invocations, header names, rate-limit detectors — interleaved with the provider-independent contract (each op's **Input:**, its **Output:** template, its **Degradation (D4):** clause, the D4/D11 invariants).

Three live consequences:

1. PF-023 has ~30 filename-composition sinks instead of one convergence point (GAP-10, CRITICAL). There is no single place where a provider is resolved, so any future provider token would have to be threaded through every sink.
2. The always-loaded D4/D11 cross-cutting text is GitHub-specific while §F.1 declares it provider-independent (GAP-03, CRITICAL) — two authorities on the secret-redaction path. This is the same shape as the live D9 divergence Phase 0 repaired.
3. src/assets/skills/git/SKILL.md (283 L / 9,236 ch) carries two live safety contradictions: :196 if [ "$REMAINING" -lt 10 ]; then sleep 60; fi [verified] directly contradicts D4's STOP-the-fan-out rule at git.md:25; and :211 gh release create … --notes "$NOTES" [verified — [drift: plan-1, plan-2 and §B.2 all cite :212; the live line is :211]] is an inline-body recipe where create-release mandates --notes-file after a scrub whose failure is a HARD fail. Both are invisible to every existing guard: INLINE_BODY_RE (tests/git-agent.test.ts:412 [verified]) matches only gh (?:pr|issue), and GIT_AGENT_PATH scans only git.md.

Phase 2 splits contract from mechanics for GitHub only, moving mechanics into generated per-op skill references addressed skill-relatively, adds a ≤40-line provider-resolution preamble at git.md:29 [verified: :29 is the blank line after the D4 block :22-28 and before ## Publication gate (D10) at :30], replaces five divergent inline issue-parse rules in the command layer with one neutral vocabulary partial, and installs the generated references with a converge-not-merge staged swap that a shadow cannot subvert.

Honest user-visible-change statement (the phase label)

No change to any GitHub-rendered artifact. Tracked = #{n}, Depends on: #{n}, 42-jwt-auth.{ts}.md and issue: 42 are byte-identical to Phase 0 under github, and the frozen github-status-lines.txt fixture is untouched. New files appear under the installed skill directory (~/.claude/skills/devflow:git/references/tracker/github/); no new file appears in any user's project tree and no new prompt is asked. No Jira or Linear literal exists anywhere yet.

Phase 2 therefore delivers zero user-facing value and introduces two new failure modes (an overlay that can partially fail; a generated reference that can be absent at runtime) — GAP-45. That is recorded deliberately, not hidden: the release-coupling decision is in §2, release readiness.

Execution: SEQUENTIAL_CODE_AGENTS · context-risk: CRITICAL · Design artifact: .devflow/docs/design/tracker-phase-2.2026-09-05_1155.md (authoritative; local, gitignored — a 60k-truncated copy is posted as a collapsed comment).

Product Requirements

Depends on

Phase 1 (#323) merged to main. Tracking issue: #321.

Acceptance criteria

• AC-2.1 — the golden diff contains only the intended text moves; the frozen status-line fixture unchanged [DR-27(b)] the frozen-fixture half stays mechanical; the "only intended moves" half is bound to the containment-test exemption list created in P2-S6 ([DR-17]) — an asserted-non-empty, per-range justified list of deliberately rewritten line ranges
• AC-2.2 — containment passes with zero unaccounted lines (incl. moved github-api.md/SKILL.md lines)
• AC-2.3 — the D11 guards stay green with the floor at >= 8 over the joined corpus, not lowered, and fail on a known-bad sample [DR-18] the D11 forward guard extracts with mode 'union' over the joined corpus, named explicitly at the call site
• AC-2.4a — a shadowed devflow:git receives the canonical GitHub references
• AC-2.4b — REWORDED [DR-05]: an unreadable generated reference ⇒ that provider's directory is left unchanged, InstallReport.overlayFailures names the provider, and the install succeeds; an absent canonical GitHub reference ⇒ loud failure with a build hint — the provider directory is atomic: a per-file failure aborts that provider's swap, rms the tmp tree, and pushes the provider onto overlayFailures — it never renames a partial tree over a good one
• AC-2.4c — a shadow-supplied file under references/tracker/** not in the manifest is absent after install
• AC-2.5 (re-derived, §F.4) — bytes(dist/agents/git.md) ≤ 49600, bytes(skills/git/SKILL.md) ≤ 6600, loaded set ≤ 71562 on the worst-case tracker spawn, each a named constant with its derivation in a comment, evaluated as a four-shape table test; the only reference-naming line outside a tracker-op section is the single preamble load instruction [DR-12] the loaded-set formula gains + max over ops of (sum of every reference file that op's load instructions can name in one spawn), with a bidirectional structural check. [DR-13(a)] the preamble ceiling is promoted into this AC: "the preamble at git.md:29 is ≤40 lines". [DR-27(c)] the second clause gets its own assertion: "exactly one line in dist/agents/git.md names a references/tracker/ path, and it is inside the preamble", non-vacuous against a seeded second naming line
• AC-2.6 — all git-agent.test.ts guards green and the guard count has not decreased; registry Guard 6 green with op names unchanged [DR-20] the guard-count accounting explicitly records the D10 scope guard's successor pair so the replacement is visibly not a net loss
• AC-2.7 — every generated Phase-2 reference line is reachable on the gh path; no _mcp.md exists after a GitHub-only build; no Jira/Linear literal anywhere amended to the positive form: every generated Phase-2 reference line is reachable on the gh path; after a GitHub-only build not exists('references/tracker/_mcp.md') and '_mcp.md' not in read(references/tracker/github/{op}.md) for every op. Per Gate-2 D-D (clause (iii) read per phase), _mcp.md is NOT generated in Phase 2 — the guard text is re-scoped in 3a-4 (Conflict C5 / H7); Phase 2's wording is the correct Phase-2 form
• AC-2.8 — the retired-wording grep is clean against the Phase-2 allowlist
• AC-2.9 — _tracker.mds ships the two-armed GitHub foreign-shape rule — ships two-armed from day one so no single-arm guard ever exists (clause (iii))
• AC-2.10 — Tracked = #{n}, Depends on: #{n}, 42-jwt-auth.{ts}.md and issue: 42 byte-identical to Phase 0 under github
• AC-2.11 — UAC-28 (shadow overlay) is a release blocker, not merely an AC — Gate-2 D-B: the test is AC-2.4a; the "release blocker" label is a process label recorded in the release-readiness subsection — the label is (process-only — PR checklist)
• AC-2.12 (new) — collectSkillRefFiles is recursive, so the references/tracker/** guards are non-vacuous — lands in T1, in the same commit that creates the subtree (Conflict C7)
• AC-2.13 (new) — the D4 and D11 legend rows survive in git.md; no surviving label lacks its definition — asserted as a set relation, not per-row
• Prefix-shippability — After phase N: (i) npm run build && npm test && npm run test:integration && npm pack --dry-run are green; (ii) a fresh install from the tarball drives /plan → /implement → /code-review → /resolve → /release on a GitHub project with no new prompt and no new file in git status; (iii) every artifact in the tree has at least one reachable consumer in this phase's end-state — no file, define, list element, frontmatter key or conditional arm exists solely for a later phase (ADR-003); (iv) the frozen github-status-lines.txt fixture is byte-identical to its Phase-0 capture.

Subtasks

#	Domain	Owned files (with anchors)	Steps	Depends on	Gate before next	Handoff contents
T1	build script / prompt assets / tests	scripts/build-mds.ts (flat (module, op) list, N ≥ 8 from its first commit) · new src/assets/mds/tracker/_github.mds · src/assets/agents/git.mds preamble insert at :29 (≤40 lines) · src/core/mds-variants.ts (expandVariants introduced here, [DR-16]) · src/core/assets.ts (compiledSkillRefsDir()) · new tests/tracker/byte-budget.test.ts · tests/mds-variants.test.ts (the expandVariants describe moved in from Phase 1) · tests/skill-references.test.ts:96-108 (collectSkillRefFiles → recursive)	P2-S1, P2-S2, P2-S3, P2-S13	Phase 1 merged to main	G2.1	the (module, op) manifest as shipped (N ≥ 8 names); the preamble's final line count against the ≤40 ceiling and byte count; the load-instruction literal verbatim, so T2 restates it identically per op; the four-shape table's named rows incl. learn-conventions.md and publication-gate.md ([DR-12]); the explicit statement that the golden is expected RED from here
T2	prompt assets	src/assets/agents/git.mds (10 ops' **Process:** blocks; D4 :22-28 / D11 :43-59 invariant-detector split; legend :84-98 per E10; D10 :30-41; learn-conventions :517-565; the two new Output-block producer lines) · src/assets/skills/git/SKILL.md (:73, :115-127, :152, :192-199, :206-214, :232-251, :252-264, :265-273) · src/assets/skills/git/references/github-api.md (5 tracker sections)	P2-S4, P2-S5, P2-S6, P2-S7, P2-S8	T1	G2.2	the per-op retained/moved table (a Phase-2 gate deliverable per GAP-01) — one row per op × {moved lines, retained lines, extraction mode 'union'/'sole' used by each guard that reads it ([DR-18])}; the containment-test exemption list with a justification per rewritten range ([DR-17]); the exact - **PR link line**: and - **Branch token**: Output-block literals now emitted by setup-task and fetch-issue (verbatim, for T3); measured bytes(dist/agents/git.md) and bytes(SKILL.md) against the pins ≤ 49,600 / ≤ 6,600
T3	prompt assets (commands + partials)	new src/assets/commands/_partials/_tracker.mds · plan.mds · implement.mds · debug.mds · dynamic-build.mds (:73, :466-474, :522) · dynamic-plan.mds · _partials/_ticket_template.mds · _partials/_wave.mds · _partials/_engine.mds:232 · _partials/_preamble.mds:31, :75 · src/assets/agents/code.md (:35, :93, :95, :99) · src/assets/skills/docs-framework/SKILL.md (:45, :106, :144) · resolve.mds (:244, :352, :499, :508, :539, :619) · plan.mds (:350, :404, :440)	P2-S9, P2-S10, P2-S11, P2-S12	T2 (producers land in T2's Output blocks; T3 wires the consumers — Conflict C11)	G2.3	the five hosts that adopted _tracker.mds and their @import line numbers; confirmation that dynamic-build.mds:522's marker literal is gone and build-mds.test.ts:853 was replaced by the negative guard; the two disposition lines (_engine.mds:232 guard-with-test; _preamble.mds:75 explicit NO-CHANGE)
T4	installer + CLI	src/targets/claude-code/installer.ts:571 + :37-45 · new recursive path-keyed prune (beside src/core/orphan-sweep.ts) · src/cli/commands/init.ts:1911 (formatOverlaySummary) · new tests/installer/reference-overlay.test.ts · tests/installer-new.test.ts (error-text repoint only)	P2-S14	T1 (needs the generated tree in dist)	G2.4	InstallReport's new field names (overlaidRefs, overlayFailures) and the render site; the manifest path the prune converges against; the atomic-provider-swap contract ([DR-05]) as implemented
T5	tests + docs	tests/git-agent.test.ts (corpus follows the moved text) · tests/build-mds.test.ts · new tests/tracker/containment.test.ts · new tests/dynamic/depends-on-grammar.test.ts · new tests/guards/capability-hoist.test.ts ([DR-11] — renamed from identity-hoist) · widened INLINE_BODY_RE · the negative-guard battery · then, in its own commit, tests/fixtures/golden/git-agent.md regenerated · docs sweep	P2-S15, P2-S16, P2-S17	T2–T4	G2.5	— (terminal)

Gates

Gate	Must be green before	Assertion
G2.1	T2 starts	npm run build exits 0 with the new (module, op) list; the preamble compiles into dist/agents/git.md and is ≤40 lines; collectSkillRefFiles is recursive and sees the new subtree; expandVariants has ≥ 8 real pairs. The golden is expected RED from here — record the expectation explicitly in the handoff so no agent "fixes" it.
G2.2	T3 starts	Containment: zero unaccounted lines across git.md ∪ dist/skills/git/references/** incl. the moved github-api.md / SKILL.md lines (AC-2.2), with the exemption list asserted non-empty and justified. Byte-budget table green: ≤ 49600 / ≤ 6600 / loaded set ≤ 71562 (AC-2.5). D11 floor >= 8 over the joined corpus in mode 'union', not lowered (AC-2.3). AC-2.13 (D4/D11 legend rows survive).
G2.3	T4 starts	_tracker.mds two-armed rule present (AC-2.9); Tracked = #{n}, Depends on: #{n}, 42-jwt-auth.{ts}.md, issue: 42 byte-identical under github (AC-2.10); frozen status lines unchanged.
G2.4	T5's golden-regeneration commit	AC-2.4a/b/c all green (shadow overlay, atomic unreadable-reference isolation, injected-file prune); the references/tracker/** guards proven non-vacuous (AC-2.12).
G2.5	PR opens	Full prefix-shippability (i)–(iv); git-agent.test.ts guard count has not decreased (AC-2.6); the golden regeneration is a standalone commit reviewed as a text diff.

/implement spawn notes

• One Code agent per subtask, strictly sequential; each verifies with npm run build && npm test && npm run test:integration && npm pack --dry-run before handing off (R6: every commit is green on its own).
• T2 is spawned with the per-op commit instruction as its default (D-G(a)) — 10 pathspec-scoped commits, containment test after each. gather-release-evidence is two commits (A then B) per [DR-17], so T2 lands 11 commits.
• Every prompt carries the H2 standing instruction and the "golden expected RED" statement verbatim.
• Every prompt carries §14's normative appendix inline. Do not pass a path to this artifact as a substitute — .devflow/docs/ is gitignored.
• CREATE_PR: false and PUSH: false on T1–T4; CREATE_PR: true and PUSH: true on T5, whose terminal act (after the golden-regeneration commit) opens the PR at G2.5. PUSH is a Code-agent input (code.md:34) that implement.mds's spawn template does not carry — state it explicitly in each spawn prompt.
• HANDOFF_REQUIRED: true on T1–T4; each writes .devflow/docs/handoff-{branch_slug}.md with the Handoff-contents column of the §6 table; T5 reads it.

Execution strategy

SEQUENTIAL_CODE_AGENTS — 5 subtasks (T1 → T5). Context risk: CRITICAL.

Largest phase by volume (~40 files, ~2,500–3,500 lines) across four distinct domains, bound by one invariant that spans all of them: the containment test's zero unaccounted lines across git.md ∪ generated references.

Two parallel candidates were evaluated and rejected:

• Installer overlay (TS) ∥ prompt split (assets) — write-disjoint, but the overlay's tests install from dist/skills/git/references/tracker/**, which only exists after the split's build manifest lands. Read closure overlaps completely.
• Command layer (_tracker.mds + 5 hosts) ∥ git.md op split — write-disjoint, but both mutate tests/build-mds.test.ts (partial manifest, escaped-brace guard, DIST_FILES scope) and both sit inside the seam test's and the frozen fixture's corpus.

Plus the feature-wide disqualifier (PF-020 closure rule, DR-23 ALREADY-ADDRESSED): npm run build is rm -rf dist && … (package.json:20) in a shared worktree, and /implement has no worktree isolation (grep for worktree in implement.mds returns zero hits). Every Code agent's verification step deletes the shared dist/ while a sibling is mid-suite, and Phase 0 deliberately makes every dist-scanning guard fail loud on a missing directory (R3 / AC-0.16). Any concurrent pair manufactures nondeterministic red. This is a tooling limitation, not a plan limitation, and it holds for all four phases.

PR title

refactor(git-agent): split tracker mechanics into generated GitHub references

Implementation Plan

Design artifact (authoritative): .devflow/docs/design/tracker-phase-2.2026-09-05_1155.md — local and gitignored. A copy truncated at the 60k comment cap is posted as a collapsed comment: #324 (comment). Run with /implement .devflow/docs/design/tracker-phase-2.2026-09-05_1155.md. Tracking issue: #321.

[dean0x]

Design artifact: tracker-phase-2.2026-09-05_1155.md (excerpt truncated at the 60k comment cap — the local file is authoritative)

---

type: design-artifact
version: 1
status: APPROVED
issue: 324
title: "Tracker Phase 2 — contract/mechanics split (GitHub only)"
slug: tracker-phase-2
created: 2026-09-05T11:55:00Z
execution-strategy: SEQUENTIAL_CODE_AGENTS
context-risk: CRITICAL

Tracking issue: #321 · Depends on: Phase 1 (#323) merged to main · Next phase: Phase 3 (#325)

This artifact is self-contained. .devflow/docs/ is gitignored (PF-037 / H9), so a pointer to another planning document resolves to "not committed; ask the author". Everything Phase 2 needs — the cross-phase normative appendix, the glossary, the DEGRADED table, the byte-budget derivations, the merge protocol — is inlined in §14. Never link; always inline.

---

1. Problem Statement

src/assets/agents/git.md is 938 L / 59,376 ch [verified @ e726874], re-sent on every Git spawn (PF-026: a shared agent prompt file is billed PER SPAWN). Roughly 9,400 of those characters are GitHub-specific mechanics — gh invocations, header names, rate-limit detectors — interleaved with the provider-independent contract (each op's **Input:**, its **Output:** template, its **Degradation (D4):** clause, the D4/D11 invariants).

Three live consequences:

1. PF-023 has ~30 filename-composition sinks instead of one convergence point (GAP-10, CRITICAL). There is no single place where a provider is resolved, so any future provider token would have to be threaded through every sink.
2. The always-loaded D4/D11 cross-cutting text is GitHub-specific while §F.1 declares it provider-independent (GAP-03, CRITICAL) — two authorities on the secret-redaction path. This is the same shape as the live D9 divergence Phase 0 repaired.
3. src/assets/skills/git/SKILL.md (283 L / 9,236 ch) carries two live safety contradictions: :196 if [ "$REMAINING" -lt 10 ]; then sleep 60; fi [verified] directly contradicts D4's STOP-the-fan-out rule at git.md:25; and :211 gh release create … --notes "$NOTES" [verified — [drift: plan-1, plan-2 and §B.2 all cite :212; the live line is :211]] is an inline-body recipe where create-release mandates --notes-file after a scrub whose failure is a HARD fail. Both are invisible to every existing guard: INLINE_BODY_RE (tests/git-agent.test.ts:412 [verified]) matches only gh (?:pr|issue), and GIT_AGENT_PATH scans only git.md.

Phase 2 splits contract from mechanics for GitHub only, moving mechanics into generated per-op skill references addressed skill-relatively, adds a ≤40-line provider-resolution preamble at git.md:29 [verified: :29 is the blank line after the D4 block :22-28 and before ## Publication gate (D10) at :30], replaces five divergent inline issue-parse rules in the command layer with one neutral vocabulary partial, and installs the generated references with a converge-not-merge staged swap that a shadow cannot subvert.

Honest user-visible-change statement (the phase label)

No change to any GitHub-rendered artifact. Tracked = #{n}, Depends on: #{n}, 42-jwt-auth.{ts}.md and issue: 42 are byte-identical to Phase 0 under github, and the frozen github-status-lines.txt fixture is untouched. New files appear under the installed skill directory (~/.claude/skills/devflow:git/references/tracker/github/); no new file appears in any user's project tree and no new prompt is asked. No Jira or Linear literal exists anywhere yet.

Phase 2 therefore delivers zero user-facing value and introduces two new failure modes (an overlay that can partially fail; a generated reference that can be absent at runtime) — GAP-45. That is recorded deliberately, not hidden: the release-coupling decision is in §2, release readiness.

---

2. Acceptance Criteria

AC text is verbatim from §F.3. Amendments accepted at Gate 2 are marked and folded in. Every row names its pinning test. Rows marked (process-only — PR checklist) have no mechanical test and must not be given a faked one (§0.10 / Gate-2 decision D-B).

AC	Text (verbatim §F.3)	Amendment folded in	Pinning test	Status
AC-2.1	the golden diff contains only the intended text moves; the frozen status-line fixture unchanged	[DR-27(b)] the frozen-fixture half stays mechanical; the "only intended moves" half is bound to the containment-test exemption list created in P2-S6 ([DR-17]) — an asserted-non-empty, per-range justified list of deliberately rewritten line ranges	frozen-fixture byte-equality in tests/goldens/github-status-lines.test.ts; exemption-list assertion in tests/tracker/containment.test.ts; golden regeneration reviewed as a text diff	covered (mechanical half) + (process-only — PR checklist) for the line-by-line diff read
AC-2.2	containment passes with zero unaccounted lines (incl. moved github-api.md/SKILL.md lines)	—	tests/tracker/containment.test.ts (unaccountedLines === 0 and linesScanned > 0)	covered
AC-2.3	the D11 guards stay green with the floor at >= 8 over the joined corpus, not lowered, and fail on a known-bad sample	[DR-18] the D11 forward guard extracts with mode 'union' over the joined corpus, named explicitly at the call site	tests/git-agent.test.ts:359-425 over gitAgentSinkCorpus()	covered
AC-2.4a	a shadowed devflow:git receives the canonical GitHub references	—	tests/installer/reference-overlay.test.ts	covered
AC-2.4b	REWORDED [DR-05]: an unreadable generated reference ⇒ that provider's directory is left unchanged, InstallReport.overlayFailures names the provider, and the install succeeds; an absent canonical GitHub reference ⇒ loud failure with a build hint	the provider directory is atomic: a per-file failure aborts that provider's swap, rms the tmp tree, and pushes the provider onto overlayFailures — it never renames a partial tree over a good one	same file; new row "one unreadable file in jira/ ⇒ pre-existing jira/ byte-unchanged, github/ installed normally"	covered
AC-2.4c	a shadow-supplied file under references/tracker/** not in the manifest is absent after install	—	same file	covered
AC-2.5 (re-derived, §F.4)	bytes(dist/agents/git.md) ≤ 49600, bytes(skills/git/SKILL.md) ≤ 6600, loaded set ≤ 71562 on the worst-case tracker spawn, each a named constant with its derivation in a comment, evaluated as a four-shape table test; the only reference-naming line outside a tracker-op section is the single preamble load instruction	[DR-12] the loaded-set formula gains + max over ops of (sum of every reference file that op's load instructions can name in one spawn), with a bidirectional structural check. [DR-13(a)] the preamble ceiling is promoted into this AC: "the preamble at git.md:29 is ≤40 lines". [DR-27(c)] the second clause gets its own assertion: "exactly one line in dist/agents/git.md names a references/tracker/ path, and it is inside the preamble", non-vacuous against a seeded second naming line	tests/tracker/byte-budget.test.ts — four-shape table + three named constants + preamble line-count + the single-naming-line assertion + the bidirectional file-set check	covered
AC-2.6	all git-agent.test.ts guards green and the guard count has not decreased; registry Guard 6 green with op names unchanged	[DR-20] the guard-count accounting explicitly records the D10 scope guard's successor pair so the replacement is visibly not a net loss	guard-count assertion (it( count ≥ the Phase-0 count; 40 today [verified], Phase 0 takes it to 42+) + Guard 6	covered
AC-2.7	every generated Phase-2 reference line is reachable on the gh path; no _mcp.md exists after a GitHub-only build; no Jira/Linear literal anywhere	amended to the positive form: every generated Phase-2 reference line is reachable on the gh path; after a GitHub-only build not exists('references/tracker/_mcp.md') and '_mcp.md' not in read(references/tracker/github/{op}.md) for every op. Per Gate-2 D-D (clause (iii) read per phase), _mcp.md is NOT generated in Phase 2	tests/tracker/containment.test.ts + the negative battery in tests/git-agent.test.ts	covered — the guard text is re-scoped in 3a-4 (Conflict C5 / H7); Phase 2's wording is the correct Phase-2 form
AC-2.8	the retired-wording grep is clean against the Phase-2 allowlist	Phase-2 allowlist narrowed to: gh issue, sleep 60, <!-- devflow: in commands, {issue} in docs-framework	tests/guards/retired-wording.test.ts	covered
AC-2.9	_tracker.mds ships the two-armed GitHub foreign-shape rule	ships two-armed from day one so no single-arm guard ever exists (clause (iii))	two-armed rule present in dist/commands/*.md	covered
AC-2.10	Tracked = #{n}, Depends on: #{n}, 42-jwt-auth.{ts}.md and issue: 42 byte-identical to Phase 0 under github	—	byte-identity assertions ×4	covered
AC-2.11	UAC-28 (shadow overlay) is a release blocker, not merely an AC	Gate-2 D-B: the test is AC-2.4a; the "release blocker" label is a process label recorded in the release-readiness subsection below	AC-2.4a covers the behaviour	covered by test; the label is (process-only — PR checklist)
AC-2.12 (new)	collectSkillRefFiles is recursive, so the references/tracker/** guards are non-vacuous	lands in T1, in the same commit that creates the subtree (Conflict C7)	recursion + nested-file count > 0 in tests/skill-references.test.ts	covered
AC-2.13 (new)	the D4 and D11 legend rows survive in git.md; no surviving label lacks its definition	asserted as a set relation, not per-row	tests/git-agent.test.ts legend set-relation it	covered
—	_engine.mds:232 neutralisation: is it a guard or documentation? (GAP-41)	RESOLVED to guard-with-test (Conflict C10)	grep guard asserting the neutral wording, non-vacuous against the current GitHub-bound literal	closed
—	_preamble.mds:75 disposition (change or explicit no-change)	RESOLVED to an explicit NO-CHANGE disposition line (Conflict C10)	no test — the disposition line is the deliverable	closed (process-only — PR checklist)

Prefix-shippability — standing AC (§F.5-G, verbatim)

After phase N: (i) npm run build && npm test && npm run test:integration && npm pack --dry-run are green; (ii) a fresh install from the tarball drives /plan → /implement → /code-review → /resolve → /release on a GitHub project with no new prompt and no new file in git status; (iii) every artifact in the tree has at least one reachable consumer in this phase's end-state — no file, define, list element, frontmatter key or conditional arm exists solely for a later phase (ADR-003); (iv) the frozen github-status-lines.txt fixture is byte-identical to its Phase-0 capture.

Command sequence run at the phase boundary:

npm run build && npm test && npm run test:integration && npm pack --dry-run
git status --porcelain                     # must be empty
cmp -s <(extract-status-lines) tests/fixtures/golden/github-status-lines.txt   # clause (iv)

Clause (ii) additionally requires, once before merge, a manual install of the packed tarball into a scratch $HOME and the five-command walk-through. (process-only — PR checklist)

What clause (iii) forces in Phase 2 (Gate-2 D-D: clause (iii) is read PER PHASE, per §F.5-G's own "After phase N"):

Consequence	Pinning
_mcp.md is forced to 3a — it is not generated in Phase 2	AC-2.7
the GitHub foreign-shape rule ships two-armed in P2, together with the grammar	AC-2.9
the (module, op) list is N ≥ 8 from its first commit — a one-element list is structurally identical to the single-arm @if AC-1.2 forbids	pairList.length >= 8

Release readiness (D-B, GAP-45)

• AC-2.11 — release blocker: UAC-28 (a shadowed devflow:git must still receive the canonical GitHub references) is a release blocker. If AC-2.4a is red, the release does not ship, regardless of every other green.
• Phase 2 delivers no user-facing value and adds two new failure modes (partial overlay; absent generated reference at runtime). The DEGRADED reason for the second — tracker mechanics unavailable — is registered in §14's table and is reachable by design from P2-S14; its runtime arm lands in Phase 3 (P3a-S14). Record this in the release notes as an internal refactor.
• PR-template checklist rows for this phase: test-inventory table present with a red proof per guard · CHANGELOG ### Changed enumerates the internal changes · prefix-shippability command sequence run and pasted · release-blocker items named in the release-readiness section.

---

3. Scope

Included

• The 10-op contract/mechanics split for GitHub (P2-S4, P2-S6) into dist/skills/git/references/tracker/github/{op}.md, generated from src/assets/mds/tracker/_github.mds.
• The ≤40-line provider-resolution preamble at git.md:29, resolving manifest-only in Phase 2 (P2-S3).
• The D4/D11 invariant-vs-detector split (P2-S4) — the D11 section itself never moves.
• The three cross-cutting cuts (P2-S5): learn-conventions Process, the D10 step-order block, the marker legend (revised per E10 — D4 and D11 rows stay).
• The skills/git/SKILL.md cut to ≤6,600 ch including both live safety contradictions (P2-S7), and github-api.md's five tracker sections (P2-S8).
• _partials/_tracker.mds and its five adoption sites (P2-S9); the ISSUE_PR_LINK/ISSUE_BRANCH_TOKEN producers and the code.md paste (P2-S10); vocabulary and grammar edits across the command layer (P2-S11); wave grammar, _engine.mds/_preamble.mds dispositions, and the dynamic-build.mds:522 marker removal (P2-S12).
• compiledSkillRefsDir() and the flat (module, op) build list with expandVariants (P2-S13, [DR-16]).
• The installer reference overlay — converge-not-merge, staged swap, atomic per provider directory (P2-S14).
• The byte-budget guard (P2-S1), recursive collectSkillRefFiles (P2-S2), the Phase-2 guard battery (P2-S15), the golden regeneration in its own commit (P2-S16), and the docs sweep (P2-S17).

Deferred to Phase 3 (explicitly not in this phase)

Deferred	Why	Lands in
references/tracker/_mcp.md and src/assets/mds/tracker/_mcp.mds	clause (iii) read per phase (D-D): no MCP-backed provider module exists in Phase 2, so _mcp.md would have no reachable consumer	3a (P3a-S12)
_jira.mds / _linear.mds provider modules and their generated trees	no provider is selectable yet	3b / 3c
The devflow init tracker step, --tracker, manifest.features.tracker, src/core/tracker.ts, src/cli/commands/tracker.ts	selection substrate	3a
src/assets/agents/tracker.md (the background Tracker agent) and the hook Section 3	learning substrate	3a
redact-secrets.cjs --emit and the MCP-shaped bypass guard	ships in the same PR as the first MCP sink	3a
The per-repo config key, the ref-grammar corroboration rule, the project-key resolution rule, the provider-mismatch guard, the # UNRESOLVED: sentinel, the - **Tracker**: status line	the preamble reserves the resolution slot in Phase 2 and resolves manifest-only	3a (P3a-S13, P3a-S14)
Agent-side adjudication of a bare number under a non-github provider	the _tracker.mds partial forwards the raw token verbatim; adjudication is in the agent	3a
The shared-literal registry's MCP arm	_mcp.md does not exist yet	3a ([DR-19])

Excluded (not in any phase of this feature)

• SG-7's second, larger git.md cut (8 PR/review op bodies, 381 L / 25,175 ch ≈ 6,294 tok). Filed as a separate follow-up issue with SG-8's constraint quoted verbatim (Gate-2 D-H(a)).
• Moving post-review-summary / post-resolution-summary mechanics — written exclusion SG-8: both are D10 and D11 sinks and may move only in a PR that moves their guards, never as a size optimisation.
• Moving ## Comment-sink scrub (D11) — never moves (§C.5 rule 1; making the containment control loadable is precisely PF-027's failure mode).
• Any user-visible behaviour change, any new prompt, any new file in a user's project tree, any Jira/Linear literal.

---

4. Gap Analysis Results

Id	One-line	Mitigating step
GAP-01	The PF-026 saving is ~3× overstated; the split as specified could be a net context regression for 6 of 8 command runs	P2-S1 (four-shape table, budget as an AC), P2-S5, P2-S6
GAP-03	The always-loaded cross-cutting D4/D11 text is GitHub-specific while §F.1 declares it provider-independent — two authorities on the redaction path	P2-S4 (invariants stay, detectors move)
GAP-05	dynamic-build.mds:466-474 already wraps <untrusted-issue-body> caller-side; after P0-S10 moved containment into the op's Output block this double-wraps	P2-S12 (explicit disposition)
GAP-06	Phase 0 invalidates the golden Phase 1 is measured against; no artifact protects byte-stable GitHub status lines across four phases	P2-S16 (own-commit regeneration; frozen fixture untouched)
GAP-08	ISSUE_REF carries two incompatible definitions and collides with ISSUE_REFS; the ISSUE_NUMBER-is-kept decision was dropped in synthesis	P2-S9, P2-S10, P2-S11 (§F.5-A glossary is the authority)
GAP-10	provider: reaches ~30 filename-composition sinks; PF-023 requires exactly one; the reference has no declared resolution root	P2-S3 (one convergence point; skill-relative addressing)
GAP-11	The flat file shape is load-bearing while listed "open"; the token tracker-{provider}.md must appear nowhere	P2-S6, P2-S13, P2-S15 (negative guard)
GAP-13	~13 new DEGRADED literals with three synonyms for one condition and no consolidated registry	§14's canonical table + retired-synonym list; P2-S4
GAP-15	ISSUE_PR_LINK / ISSUE_BRANCH_TOKEN are consumed but no op produces them; the commit heredoc is safe only by its quoted delimiter	P2-S10 (producers), P2-S7 (<<'EOF' kept, S10)
GAP-20	Marker ownership violated by a live caller-restated literal (intent #6)	P2-S12 (dynamic-build.mds:522 removal + negative guard)
GAP-21	Guard classes must move with the text, not be lowered or rewritten in the same PR as the corpus; three bound guards break silently	P2-S5 Verify (Guard 2's four its and the 10 D10 its follow the corpus, literals unchanged)
GAP-24	The installer overlay: additive copy leaves shadow-supplied mechanics in place, no atomicity, no prune, no render site, no per-item isolation	P2-S14 (converge-not-merge, staged swap, prune, formatOverlaySummary)
GAP-25	73 of skills/git/SKILL.md's 283 preloaded lines are op-specific or duplicative; two contradict git.md; neither it nor github-api.md's five tracker sections is assigned to any phase	P2-S7, P2-S8
GAP-26	Remote-call efficiency unspecified: a ≤100-call N+1, a per-issue "batch" op, a per-round wave re-read, an unhoisted identity call	P2-S6 (gather-release-evidence fix), P2-S11 (_wave.mds), P2-S15 (capability-hoist guard); the fetch-issues-batch rewrite moved to Phase 0 [DR-07]
GAP-27	The wave dependency grammar changes writer and reader with no two-sided test; the command-side grammar ships a foreign-ref shape whose adjudication lands in Phase 3	P2-S9 (two-armed rule from day one), P2-S11 (two-sided test)
GAP-31	Nothing asserts the compliance gate still resolves before its first consumer once a tracker preamble is inserted	P2-S15 edge-case row (gate resolution point unchanged)
GAP-41	_preamble.mds:75 silently dropped from the neutralisation list; the _engine.mds:232 reword may be documentation rather than a guard	P2-S12 (Conflict C10 dispositions)
GAP-42	A single-provider "file-set parity scaffold" is a vacuous scan — the exact PF-018 trap	P2-S13 (structural parity, pairs.length >= 8)
GAP-44	Define-set parity by mds::undefined_var catches omission but not a placeholder body	P2-S9, P2-S15 (per-define minimum byte count and a required phrase)
GAP-45	Phase 2 delivers zero user-facing value while introducing two new failure modes; the release-coupling decision is unmade	§2 release-readiness subsection (D-B)
GAP-47	The design-artifact naming change is a two-sided writer/reader seam with no test	P2-S11 (plan.mds ↔ docs-framework pair, same file as the Depends on: pair)
GAP-49	AC-2.6 pins "all 40 git-agent guards" — a literal Phase 0 already invalidates	P2-S15 (property: green and count not decreased)
EC-38	Resolution would otherwise run on every tracker op — two file reads × 7 Git spawns per /resolve	P2-S3 (resolve once per spawn, pass down)
EC-44	~ is not expanded by the Read tool — only by Bash (PF-035)	P2-S3 (Read tool, absolute path, never cat/head/tail)
EC-45	A hand-edited oversized tracker.md risks a silent partial read	P2-S3 (over the bound ⇒ read fully anyway + named DEGRADED, never a partial read)
S5 / S13	Ref-grammar layering (§F.5-A / §F.1 L2) — three regex layers stated separately, never interchanged	P2-S3, P2-S9, §14 glossary
S6 / S15	tracker.md sink validators and the Read-tool rule (§F.5-E, EC-44)	P2-S3 (the slot is reserved; validators land in 3a)
S10	The commit HEREDOC is safe only by its single-quoted delimiter	P2-S7 (keep <<'EOF'; compose the ref line before the heredoc; repo-wide unquoted-delimiter guard)
S11	Installer overlay staged swap	P2-S14

---

5. Execution Strategy

SEQUENTIAL_CODE_AGENTS — 5 subtasks (T1 → T5). Context risk: CRITICAL.

Largest phase by volume (~40 files, ~2,500–3,500 lines) across four distinct domains, bound by one invariant that spans all of them: the containment test's zero unaccounted lines across git.md ∪ generated references.

Two parallel candidates were evaluated and rejected:

• Installer overlay (TS) ∥ prompt split (assets) — write-disjoint, but the overlay's tests install from dist/skills/git/references/tracker/**, which only exists after the split's build manifest lands. Read closure overlaps completely.
• Command layer (_tracker.mds + 5 hosts) ∥ git.md op split — write-disjoint, but both mutate tests/build-mds.test.ts (partial manifest, escaped-brace guard, DIST_FILES scope) and both sit inside the seam test's and the frozen fixture's corpus.

Plus the feature-wide disqualifier (PF-020 closure rule, DR-23 ALREADY-ADDRESSED): npm run build is rm -rf dist && … (package.json:20) in a shared worktree, and /implement has no worktree isolation (grep for worktree in implement.mds returns zero hits). Every Code agent's verification step deletes the shared dist/ while a sibling is mid-suite, and Phase 0 deliberately makes every dist-scanning guard fail loud on a missing directory (R3 / AC-0.16). Any concurrent pair manufactures nondeterministic red. This is a tooling limitation, not a plan limitation, and it holds for all four phases.

Recorded so it is not re-litigated (DR-23): T4 declares Depends on: T1 only, and P2-S14's tests use mkdtemp fixtures rather than the real dist tree — so T4 is scheduled after T2/T3 for reviewability, not for correctness. If per-agent worktrees ever exist, this is the first seam to revisit. Do not parallelise it under the current tooling.

Context-risk driver: T2 — ~9,400 characters of **Process:** text moved verbatim out of git.mds into MDS defines, plus a rewrite of two cross-cutting sections. Verbatim movement across a compiler boundary is exactly where an agent paraphrases. Mitigation is baked into the gates: the containment test (zero unaccounted lines) is the oracle, and the golden diff must contain only intended moves (AC-2.1, bound to the exemption list).

Pre-authorised split (Gate-2 D-G(a)): T2 commits per op — 10 ops / 11 commits (gather-release-evidence is A+B, [DR-17]), pathspec-scoped (git commit -- <owned paths>), running the containment test after each. This is the default, not an escalation. A single 10-op commit makes the golden diff unreviewable and hides a paraphrase inside an 800-line hunk (H11). Within-PR splits have no merge consequence; a PR-level split would change the issue count and requires explicit approval.

Standing instruction carried into every Code prompt (H2): "A golden mismatch means the source is wrong, never the fixture." The git-agent.md golden is expected RED from G2.1 until T5's regeneration commit. Record this expectation in every handoff so no agent "fixes" it early. Only T5's designated commit may run the regeneration ritual.

Authoring order for every step (R1, TDD): write the guard → observe RED → apply the change → GREEN. A guard with no known-bad sample is not accepted. Each phase issue carries a test-inventory table: guard name · file:line it lands in · the known-bad sample it must fail on · the commit in which it was proven red. An agent must never revert a landed fix to demonstrate red (H10).

---

6. Subtask Breakdown

#	Domain	Owned files (with anchors)	Steps	Depends on	Gate before next	Handoff contents
T1	build script / prompt assets / tests	scripts/build-mds.ts (flat (module, op) list, N ≥ 8 from its first commit) · new src/assets/mds/tracker/_github.mds · src/assets/agents/git.mds preamble insert at :29 (≤40 lines) · src/core/mds-variants.ts (expandVariants introduced here, [DR-16]) · src/core/assets.ts (compiledSkillRefsDir()) · new tests/tracker/byte-budget.test.ts · tests/mds-variants.test.ts (the expandVariants describe moved in from Phase 1) · tests/skill-references.test.ts:96-108 (collectSkillRefFiles → recursive)	P2-S1, P2-S2, P2-S3, P2-S13	Phase 1 merged to main	G2.1	the (module, op) manifest as shipped (N ≥ 8 names); the preamble's final line count against the ≤40 ceiling and byte count; the load-instruction literal verbatim, so T2 restates it identically per op; the four-shape table's named rows incl. learn-conventions.md and publication-gate.md ([DR-12]); the explicit statement that the golden is expected RED from here
T2	prompt assets	src/assets/agents/git.mds (10 ops' **Process:** blocks; D4 :22-28 / D11 :43-59 invariant-detector split; legend :84-98 per E10; D10 :30-41; learn-conventions :517-565; the two new Output-block producer lines) · src/assets/skills/git/SKILL.md (:73, :115-127, :152, :192-199, :206-214, :232-251, :252-264, :265-273) · src/assets/skills/git/references/github-api.md (5 tracker sections)	P2-S4, P2-S5, P2-S6, P2-S7, P2-S8	T1	G2.2	the per-op retained/moved table (a Phase-2 gate deliverable per GAP-01) — one row per op × {moved lines, retained lines, extraction mode 'union'/'sole' used by each guard that reads it ([DR-18])}; the containment-test exemption list with a justification per rewritten range ([DR-17]); the exact - **PR link line**: and - **Branch token**: Output-block literals now emitted by setup-task and fetch-issue (verbatim, for T3); measured bytes(dist/agents/git.md) and bytes(SKILL.md) against the pins ≤ 49,600 / ≤ 6,600
T3	prompt assets (commands + partials)	new src/assets/commands/_partials/_tracker.mds · plan.mds · implement.mds · debug.mds · dynamic-build.mds (:73, :466-474, :522) · dynamic-plan.mds · _partials/_ticket_template.mds · _partials/_wave.mds · _partials/_engine.mds:232 · _partials/_preamble.mds:31, :75 · src/assets/agents/code.md (:35, :93, :95, :99) · src/assets/skills/docs-framework/SKILL.md (:45, :106, :144) · resolve.mds (:244, :352, :499, :508, :539, :619) · plan.mds (:350, :404, :440)	P2-S9, P2-S10, P2-S11, P2-S12	T2 (producers land in T2's Output blocks; T3 wires the consumers — Conflict C11)	G2.3	the five hosts that adopted _tracker.mds and their @import line numbers; confirmation that dynamic-build.mds:522's marker literal is gone and build-mds.test.ts:853 was replaced by the negative guard; the two disposition lines (_engine.mds:232 guard-with-test; _preamble.mds:75 explicit NO-CHANGE)
T4	installer + CLI	src/targets/claude-code/installer.ts:571 + :37-45 · new recursive path-keyed prune (beside src/core/orphan-sweep.ts) · src/cli/commands/init.ts:1911 (formatOverlaySummary) · new tests/installer/reference-overlay.test.ts · tests/installer-new.test.ts (error-text repoint only)	P2-S14	T1 (needs the generated tree in dist)	G2.4	InstallReport's new field names (overlaidRefs, overlayFailures) and the render site; the manifest path the prune converges against; the atomic-provider-swap contract ([DR-05]) as implemented
T5	tests + docs	tests/git-agent.test.ts (corpus follows the moved text) · tests/build-mds.test.ts · new tests/tracker/containment.test.ts · new tests/dynamic/depends-on-grammar.test.ts · new tests/guards/capability-hoist.test.ts ([DR-11] — renamed from identity-hoist) · widened INLINE_BODY_RE · the negative-guard battery · then, in its own commit, tests/fixtures/golden/git-agent.md regenerated · docs sweep	P2-S15, P2-S16, P2-S17	T2–T4	G2.5	— (terminal)

Gates

Gate	Must be green before	Assertion
G2.1	T2 starts	npm run build exits 0 with the new (module, op) list; the preamble compiles into dist/agents/git.md and is ≤40 lines; collectSkillRefFiles is recursive and sees the new subtree; expandVariants has ≥ 8 real pairs. The golden is expected RED from here — record the expectation explicitly in the handoff so no agent "fixes" it.
G2.2	T3 starts	Containment: zero unaccounted lines across git.md ∪ dist/skills/git/references/** incl. the moved github-api.md / SKILL.md lines (AC-2.2), with the exemption list asserted non-empty and justified. Byte-budget table green: ≤ 49600 / ≤ 6600 / loaded set ≤ 71562 (AC-2.5). D11 floor >= 8 over the joined corpus in mode 'union', not lowered (AC-2.3). AC-2.13 (D4/D11 legend rows survive).
G2.3	T4 starts	_tracker.mds two-armed rule present (AC-2.9); Tracked = #{n}, Depends on: #{n}, 42-jwt-auth.{ts}.md, issue: 42 byte-identical under github (AC-2.10); frozen status lines unchanged.
G2.4	T5's golden-regeneration commit	AC-2.4a/b/c all green (shadow overlay, atomic unreadable-reference isolation, injected-file prune); the references/tracker/** guards proven non-vacuous (AC-2.12).
G2.5	PR opens	Full prefix-shippability (i)–(iv); git-agent.test.ts guard count has not decreased (AC-2.6); the golden regeneration is a standalone commit reviewed as a text diff.

/implement spawn notes

• One Code agent per subtask, strictly sequential; each verifies with npm run build && npm test && npm run test:integration && npm pack --dry-run before handing off (R6: every commit is green on its own).
• T2 is spawned with the per-op commit instruction as its default (D-G(a)) — 10 pathspec-scoped commits, containment test after each. gather-release-evidence is two commits (A then B) per [DR-17], so T2 lands 11 commits.
• Every prompt carries the H2 standing instruction and the "golden expected RED" statement verbatim.
• Every prompt carries §14's normative appendix inline. Do not pass a path to this artifact as a substitute — .devflow/docs/ is gitignored.
• CREATE_PR: false and PUSH: false on T1–T4; CREATE_PR: true and PUSH: true on T5, whose terminal act (after the golden-regeneration commit) opens the PR at G2.5. PUSH is a Code-agent input (code.md:34) that implement.mds's spawn template does not carry — state it explicitly in each spawn prompt.
• HANDOFF_REQUIRED: true on T1–T4; each writes .devflow/docs/handoff-{branch_slug}.md with the Handoff-contents column of the §6 table; T5 reads it.

---

7. Implementation Plan

Steps are listed in numeric order; commit order is the §6 subtask order — P2-S13 belongs to T1 and runs before P2-S4…P2-S12.

P2-S1 — Branch, budget constants, and the four-shape table test before any text moves → T1

Goal: Pin the byte budget as an AC from the corrected baseline, so the split cannot be "satisfied while the total gets worse".

Files: new tests/tracker/byte-budget.test.ts (path per Conflict C6; §0.11 scheme; sibling of tests/tracker/containment.test.ts).

Change: named constants with derivations in comments:

BUDGET_GIT_MD      = 49600   // 59376 − 9813 = 49563; headroom 37
BUDGET_SKILL_MD    =  6600   // 9236 − 2636 (D3 template, throttling, PR comments, releases, naming authority)
BUDGET_LOADED_SET  = 71562   // the pre-split preloaded set @ e726874, measured
                             // (lives in tests/goldens/github-status-lines.test.ts from P0)

worstCaseTrackerSpawnBytes =
    bytes(dist/agents/git.md) + bytes(skills/git/SKILL.md) + bytes(skills/worktree-support/SKILL.md)
  + bytes(references/tracker/_mcp.md)              // 0 on the GitHub path
  + max_op bytes(references/tracker/github/{op}.md)
  + max over ops of ( sum of every reference file that op's load instructions can name
                      in one spawn )              // [DR-12]

[DR-12] amendment. The formula previously counted P2-S5's two new references as pure subtractions from git.md while their bytes stayed loadable within one spawn. The genuine worst case — setup-task with .devflow/conventions.md absent — loads git.md + SKILL.md + worktree-support + github/setup-task.md + learn-conventions.md, ~3,300 ch above the previously modelled maximum; post-review-summary similarly under-counted by ~1,113 via publication-gate.md. Two consequences, both landing here:

1. The extended term above.
2. A bidirectional structural check in the same file: the set of files summed by the formula equals the set of files nameable from any single op's load instructions — asserted in both directions, each with a why message, non-vacuous by count. Model: the compliance-compose.ts:20/:36/:50 bidirectional registry ("every token here must exist in the template; every template token must be listed here").
3. learn-conventions.md and publication-gate.md become named rows of the four-shape table, so their cost is recorded, not merely deducted.

[DR-13(a)] amendment. The preamble's ≤40-line ceiling was a handoff deliverable with no AC. It is promoted into AC-2.5 and asserted here: dist/agents/git.md's preamble block at :29 is ≤ 40 lines.

[DR-27(c)] amendment. AC-2.5's second clause gets its own assertion here: exactly one line in dist/agents/git.md names a references/tracker/ path, and it is inside the preamble — non-vacuous against a seeded second naming line.

Revised cut list (E10 correction): tracker mechanics −9,400 · learn-conventions body −3,300 · marker legend −1,400 (not −1,641: the D4 and D11 rows stay) · D10 step-order −1,113 · add-back +5,400 ⇒ −9,813 ⇒ git.md = 49,563 ch.

Evaluated as a four-shape table test so the per-provider disqualification (+31% to +41%) and per-op-without-_mcp (≈ −17% on a tracker spawn) are recorded as computed rows, not asserted pass/fail — a table test keeps the decision from being re-litigated.

Ids: AC-2.5 (re-derived), GAP-01, §F.4, B-5. Folds: [DR-12], [DR-13(a)], [DR-27(c)].

Verify: RED at HEAD (git.md is 59,376 > 49,600) — the guard is the phase's progress meter, and T5 only keeps it green; T5 does not create it (Conflict C6). Written exclusions asserted: ## Comment-sink scrub (D11) never moves, and post-review-summary / post-resolution-summary mechanics may move only in a PR that moves their guards (SG-8).

---

P2-S2 — Make collectSkillRefFiles recursive → T1

Goal: Prevent every references/tracker/** guard from being vacuous from birth.

Files: tests/skill-references.test.ts:96-108 ★ — [verified] non-recursive: for (const file of readdirSync(refsDir).filter(f => f.endsWith('.md'))). It walks the flat references/ dir and frameworks/{id}/ only. The nested references/tracker/{provider}/ subtree would be invisible to the :537 and :595 scans, making both vacuous (PF-018). MARKER_REFS at :196 [verified: declared :196, used :466 / :665] [drift: plan says :196/:451].

Change: recurse; land in the same commit that creates the subtree — T1, not T5 (Conflict C7 resolved to T1; AC-2.12's own wording is decisive).

Ids: AC-2.12 (new), PF-018.

Verify: RED against a fixture file at references/tracker/github/setup-task.md that violates a MARKER_REFS rule — the guard must see it. Non-vacuity: nested-file count > 0.

---

P2-S3 — The ≤40-line preamble at git.md:29 → T1

Goal: Resolve the provider once, before every op and both cross-cutting sections, and never again (PF-023 requires exactly one convergence point, not ~30 filename-composition sinks).

Files: src/assets/agents/git.mds — insert at :29 [verified: :14-19 ## Input, :22-28 the D4 block, :29 blank, :30 ## Publication gate (D10)].

Contents (all ≤40 lines):

1. Provider resolution via a static path map — trim → strip surrounding quotes → reject if the raw value contains any character outside [A-Za-z] → ASCII-lowercase → exact membership in {github, jira, linear}; reject, never repair. The token selects a hardcoded path prefix from the map and is never concatenated into a path.
2. The four ADR-007 neutral values.
3. The ## Tracker input contract block.
4. The Read-tool rule — absolute path, never ~, never cat/head/tail (PF-035, EC-44: ~ is expanded by Bash, not by the Read tool).
5. The size bound — ≤120 L / ≤8,000 ch; over ⇒ read fully anyway + DEGRADED (tracker.md exceeds size bound), never a partial read (EC-45: a partial read is indistinguishable from a missing section, which maps to a different neutral value).
6. [DR-11] the capability-hoist line, widened from identity-only to all capabilities:

   "Resolve tracker capabilities and the current-user identity exactly once per spawn, before any loop; pass the resolved set to nested invocations; never invoke a capability probe inside a loop."
   Rationale: identity is one capability among fifteen (§14's capability column). Nothing previously forbade a mechanics file from probing capabilities inside the ≤50 loops of backlink-shipped-issues or resolve-review-threads, and the old guard's regex was scoped to identity verbs only.

7. The single load instruction, addressed skill-relatively (the git.md:596 form [verified] — the only reference cross-ref in the file today). Its literal text is a T1 handoff deliverable so T2 restates it identically per op.
8. The "never fabricate provider mechanics" literal, reused verbatim from src/core/compliance-compose.ts:266-270.

In Phase 2 the preamble reserves the resolution slot but resolves manifest-only — the per-repo config key and the ref-grammar corroboration arrive in P3a-S13.

Ids: GAP-10 (CRITICAL), AC-2.5's scope clause, EC-38, EC-44, EC-45, S5, S6, S15. Folds: [DR-11].

Verify: hostile-provider table mirroring compliance-install.test.ts AC-35: ../../../etc/passwd, github/../../rules/devflow, GitHub, jira (trailing space), jira-cloud, `id`, empty, 200 chars, . Assert the normalisation literal appears exactly once; no mechanics file reads provider:; no generated reference path literal begins with ~/.claude — a hard-coded ~/.claude/… is absent for CLAUDE_CODE_DIR users (claude-paths.ts:44-56) and for local-scope installs (:104-111), and the fail-closed neutral value would then cost such a GitHub user issue creation, branch traceability and back-links entirely.

---

P2-S4 — D4/D11 invariant-vs-detector split → T2

file:line	Invariants that stay in git.md	Detectors that move to references/tracker/github/{op}.md
git.md:22-28 (D4) [verified]	STOP on secondary limit; THROTTLED ({n} not processed); never report COMPLETE while items went unprocessed	:25 X-RateLimit-Remaining < 10 + "extends GitHub's penalty window"; :28 the < 50 → 3s rung
git.md:43-59 (D11)	:52-59 — scrub unconditional and fail-closed; DO-NOT-POST on non-zero; per-invocation mktemp (:59); never post the RAW buffer; && never a pipeline (:47-51)	:45 "to GitHub" → provider-neutral; :49-51 the literal node …redact-secrets.cjs … && gh … chain → the provider file

Change: §C.5 rule 1 — the D11 section itself never moves. Making the containment control loadable is precisely PF-027's failure mode. Only the detectors relocate; the invariants remain in the always-loaded file.

Ids: GAP-03 (CRITICAL), GAP-13, S13.

Verify: negative guard — no gh literal survives in any cross-cutting section of git.md; single-authority assertion per rule (each invariant appears exactly once; each detector exactly once per provider); the Phase-0 D11 union guards stay green with the floor at >= 8, not lowered (AC-2.3), extracted in mode 'union' ([DR-18]).

---

P2-S5 — The three cross-cutting cuts → T2

#	file:line	Change	Δ ch
1	git.md:517-565 (learn-conventions Process) [verified: :511 heading, :513 prose, :515 Input, :517 Process, :564-565 post-composition check, :566 D4, :568-583 Output, :585 ---]	→ references/learn-conventions.md, loaded only when .devflow/conventions.md is absent. [DR-15] Generate it from a define in src/assets/mds/ — not hand-authored — so Phase 3's Tracker agent can NAME it rather than restate it. [drift: plan says body :511-586 / "76 lines"; the movable body is 49 lines]	−3,300
2	git.md:30-41 (D10 step-order block)	→ references/publication-gate.md, named from the 2 summary ops only	−1,113
3	git.md:84-98 marker legend [verified: :84 header, :86-87 table head, :88-98 rows D1–D11]	REVISED — do not delete wholesale. :91 is the only definition of **Degradation (D4):** and :98 the only definition of Comment-sink scrub (D11), and both labels survive the cut. Keep a two-row inline legend (D4, D11); delete or re-home D1–D3 / D5–D10 to references/decision-markers.md. D9's definition at :96 [verified] is separately pinned by git-agent.test.ts:167-168 [drift: plan-1 P0-S8 and §E10 cite :163; the it( is :162], so its row is load-bearing until that guard is repointed	−1,400

[DR-15] — why cut 1 is generated rather than hand-authored. Phase 3's P3a-S9 would otherwise copy git.md:517-565 wholesale into src/assets/agents/tracker.md — the bounded-scan literals (head -50, head -20, --limit 30, --max-count=200), the UNTRUSTED-strings block (:521-528) and the post-composition verbatim-match check (:564-565) would then live in two independently hand-maintained copies, the second one outside every corpus the single-authority guards scan. That is the D9 failure Phase 0 exists to repair, reproduced deliberately, on security-relevant text. Generating the reference from a define makes it nameable, so Phase 3 names it and no second copy is created.

[DR-19] — the shared-literal registry starts here. Build a registry of the normative sentences of references/{publication-gate,learn-conventions,decision-markers}.md (the same device §14's DEGRADED table uses for reasons and MARKER_REFS uses for markers), with both arms:

• positive: every registry entry appears in exactly one of the three files;
• negative ("no restatement"): no sentence in the registry appears in any references/tracker/{provider}/{op}.md — non-vacuous against a seeded restatement.
  Assert the registry is non-empty and each entry justified. The _mcp.md arm lands in Phase 3 (P3c-S6) — _mcp.md does not exist in Phase 2.

Ids: GAP-01, E10, AC-2.13 (new), ADR-003. Folds: [DR-15], [DR-19], [DR-20], [DR-18].

Verify:

• AC-2.13 — the D4 and D11 legend rows survive; no surviving label lacks its definition, asserted as a set relation, not per-row.
• Guard 2's four bound pins (git-agent.test.ts:129-159: head -50, head -20, --limit 30, --max-count=200 — four its, all reading extractOpSection(content, 'learn-conventions')) all live in the body that moves; repoint them to the corpus extractor in the same commit that moves the text, literals unchanged. [DR-18] each of the four uses the moved copy — extraction mode is named at the call site.
• [DR-20] the D10 scope guard's successor property. git-agent.test.ts:235-325 holds the 10 D10 its including the negative-scope one at :307-325 asserting gh repo view appears in exactly ['post-resolution-summary','post-review-summary'] [drift: plan-1 P2-S5 cites :237-325; plan-1's own Critical-Files line and plan-2 both say :235-325 — use :235-325]. After the move the literal lives once in a shared, op-agnostic file, so "recompute over the joined corpus" would only establish that the literal exists — the scope property evaporates (CONTEXT-PACK §3 B3: "gh repo view allowed ONLY in the two summary ops"). Replace "follows the corpus" with the explicit successor property, two assertions:
  1. references/publication-gate.md is named from exactly ['post-resolution-summary','post-review-summary'];
  2. gh repo view appears only in that file.
     Both non-vacuous (opNames.length > 2; a seeded third op naming the file goes red). Add the pair to AC-2.6's guard-count accounting so the replacement is visibly not a net loss.

---

P2-S6 — The op-by-op split table → T2

Files: src/assets/agents/git.mds → src/assets/mds/tracker/_github.mds → generated dist/skills/git/references/tracker/github/{op}.md.

Structure verified across all 18 ops: ## Operation: X → prose → **Input:** → (**Degradation (D4):**) → **Process:** → **Output:** fence → ---. All ten op headings [verified].

Op	Moves to references/tracker/github/{op}.md	Stays in git.md
setup-task :196-254	**Process:** steps (1b/1c/3 mechanics)	:196 heading, :198 prose, :200-206 Input, Output :236-253 (### Traceability :244-246)
fetch-issue :257-285	**Process:** :263-266	:257, :259, :261 Input, Output :268-284
fetch-issues-batch :288-319	**Process:** :294-298 — a pure verbatim move [DR-07]	:288, :290, :292 Input, Output :300-318 [drift: P0-S15 lists :302-319, P0-S10 says :300-319; use :300-318]
manage-debt :379-411	**Process:** :384-394	:379, :381, :383 Input, the P0-S9 D4 clause, Output :397-409
create-release :444-476	the ## Closed Issues step only	tag/release/notes, D4 carve-out :450, Output :465-474
gather-release-evidence :478-509	two commits [DR-17] — A: ref-parsing step :490 moved verbatim; B: the ≤100-call N+1 fix applied in the moved reference (batch-first closing_refs_for_commits, ≤25 sequential sub-bound, PR-number dedup). closingIssuesReferences is GitHub-only	Input, D4 :484, Output :493-507
backlink-shipped-issues :785-833	**Process:** (viewer-login hoist, marker post, throttle)	Input, D4 :793-798, Output :820-831
ensure-traceable-issue :835-872	**Process:** :846-862 (gh issue create, the <details> comment)	Input, D4 :841, Output :863-870
post-wave-report :874-911	**Process:** mechanics	Input, D4 :885, Output :903-909
ensure-pr-ready :102-152	step 4b only (exists_open + render_pr_link)	4a/4c, the D11 sink, Output :138-150

[DR-07] — the fetch-issues-batch rewrite is gone from this step. The single-GraphQL-query rewrite happened in Phase 0 (P0-S12, in the same A1 commit that wired the caller). ADR-003 forbids relocating known-defective text unchanged; fixing in place in Phase 0 and moving the fixed text verbatim here satisfies it strictly better, and A2 captured the golden from the post-A1 tree so the move stays pure. Delete the rewrite clause; this row is a plain verbatim move. The edge-case assertion "'gh issue view' absent from the batch reference" stays in Phase 0's table scoped to git.md; Phase 2 re-asserts it against the moved reference.

[DR-17] — mixed moves and rewrites need a mechanical distinction. The oracle for T2 is "zero unaccounted lines", which is undefined for lines that were rewritten rather than relocated — and gather-release-evidence is a remote-I/O rewrite with new failure modes (a batch call that 4xx's where 100 individual calls previously item-degraded per D4). Three consequences, all landing here:

1. Split the row into two commits within T2. Commit A moves the **Process:** block verbatim — containment green, golden diff a pure move. Commit B applies the batch-first fix in the moved reference, with its own RED proof (≤25 present; the per-commit gh api loop absent) and its own golden-diff hunk.
2. A containment-test exemption list, naming any deliberately rewritten line ranges with a rationale per range, asserted non-empty and justified — the same device P0-S22 ships for the Extended-References generated-path exception. AC-2.1's "only intended moves" half is bound to this list [DR-27(b)], which makes that half mechanical rather than a reviewer's attention.
3. A new P2.7 risk row for the rewrite's new remote failure modes (see §12, H12).

Ids: GAP-01, GAP-11 (per-op files; the token tracker-{provider}.md appears nowhere), GAP-26, F.2. Folds: [DR-07], [DR-17], [DR-18].

Verify: containment test over git.md ∪ generated GitHub references with zero unaccounted lines; the per-op retained/moved table published as a gate deliverable, carrying each guard's extraction mode ('union' | 'sole') per [DR-18].

---

P2-S7 — skills/git/SKILL.md cut (target ≤6,600 ch; 283 L / 9,236 ch today [verified]) → T2

file:line	Change
:232-251 D3 template [drift: plan says :232-250; the Rules: bullets run to :251]	→ references/tracker/github/ensure-traceable-issue.md — provider-varying content in a provider-blind preloaded file
:192-199 ### Standard Throttling [verified] [drift: plan says :188-198; ## GitHub API + the rate-limit blockquote are :188-190]	→ references/github-api.md. :196 if [ "$REMAINING" -lt 10 ]; then sleep 60; fi [verified] directly contradicts D4's STOP-the-fan-out rule (git.md:25, intent #3) — two opposed rate-limit policies preloaded in one context
:200-204 ### PR Comments	→ references/github-api.md
:206-214 ### Releases [drift: plan says :206-213]	→ references/github-api.md. gh release create … --notes "$NOTES" is an inline-body recipe where create-release mandates --notes-file after a scrub whose failure is a HARD fail — invisible to every existing guard because INLINE_BODY_RE matches only `gh (?:pr
:252-264 ## Naming Conventions Authority	→ a one-line pointer to learn-conventions. :259 holds ≤50 branches [verified] [drift: plan says :260] — AC: count('≤50 branches') == 1 across git.md ∪ skills/git/**
:73 protected-branch list (under ### Branch Safety :71)	Delete the duplicate in favour of the worktree-support canonical list
:115-127 HEREDOC, :125 Closes #123	Keep <<'EOF' (S10). Compose the ref line before the heredoc, validated against the provider ref shape, leaving the heredoc body a literal template. Add: "the heredoc delimiter is single-quoted; unquoting it makes every interpolated value a command."
:152 | Related Issues | Closes/relates to links | [drift: CONTEXT-PACK says L148; verified :152]	{ISSUE_REF} vocabulary
:265-273 Extended References	New row at :274 for the generated references/tracker/ directory

Ids: GAP-25, S10, AC-2.5, GAP-15.

Verify: 'sleep 60' absent; count('≤50 branches') == 1; INLINE_BODY_RE widened and rescoped, proven RED before the fix (the release recipe is the known-bad sample already in the tree):

today   [verified tests/git-agent.test.ts:412]:
  /gh (?:pr|issue) [a-z-]+[^`\n]*--body[ "]|-f body=/g          // scope: git.md only
becomes:
  /gh (?:pr|issue|release) [a-z-]+[^`\n]*--(?:body|notes)[ "]|-f body=/g
  scope: [git.md, skills/git/SKILL.md, skills/git/references/*.md, references/tracker/**]

Keep the existing inline non-vacuity probe (:419-424 [verified]) and add a second for the new arm: 'gh release create v1 --notes "unscrubbed"' must match. Also a repo-wide negative guard against any unquoted heredoc delimiter (<<[A-Z]) in src/assets/, non-vacuous against a known-bad sample; the P0-S22 Extended-References guard green with the new row.

---

P2-S8 — github-api.md tracker sections → T2

Files: src/assets/skills/git/references/github-api.md:137 ## Issue Operations, :139 ### Fetch Issue with All Details (★ :142 gh issue view "$ISSUE_NUMBER" — the sixth ISSUE_NUMBER file, which GAP-08 names without a line), :146 ### Create Issue with Labels and Assignees, :168 ### Tech Debt Issue Management, :206 ### Extract Issue Data, :283 ## Branch Name from Issue.

Change: move into references/tracker/github/ or record an explicit exemption with a rationale — never leave them unassigned; add the moved lines to the containment test.

Ids: GAP-25, GAP-08 (PF-025 sweep set).

Verify: containment test counts these lines; RED if any is unaccounted.

---

P2-S9 — _partials/_tracker.mds and its five adoption sites → T3

Files: new src/assets/commands/_partials/_tracker.mds; imports at plan.mds:8, implement.mds:8, debug.mds:7, dynamic-build.mds:12, dynamic-plan.mds:9 (existing @import blocks: plan :5-7, implement :5-7, debug :5-6, dynamic-build :6-11, dynamic-plan :6-8); replacements at plan.mds:27/:32, implement.mds:59, debug.mds:46-52, dynamic-build.mds:73, dynamic-plan.mds:103.

Change: exactly two zero-arg defines — issue_ref_grammar() and issue_capture_contract() — plus two @export lines, one per line, never a list. Structurally _partials/_publication.mds ×2 (7 lines: @define / bold-lead paragraph / blank / a Note: paragraph pre-empting a misreading / @end / blank / @export).

Copy the Note: device for bare-number adjudication: bare digits are a reference only under github, adjudicated in the agent; the partial forwards the raw token verbatim.

Ships the two-armed GitHub foreign-shape rule from day one — {ISSUE_REF} not #N/digits ⇒ TRACEABILITY: DEGRADED (issue reference "{ref}" does not match github reference grammar); never coerced, never dropped silently — so no single-arm guard ever exists (clause (iii)). tracker_learn_step() is dropped with the question step. [verified: _partials/ has 11 files and no subdirectories — now a rule.]

Ids: AC-2.9, GAP-08, GAP-27, F.1 L1.

Verify: toHaveLength(11) at build-mds.test.ts:85-89 [verified] becomes 12 via the P1-S12 name manifest — a manifest entry, not a bumped literal (H4); all-hosts adoption guard for the two defines mirroring the P0-S22 compliance_gate guard; per-define non-emptiness — an exported define with a placeholder body compiles cleanly (mds::undefined_var catches omission but not emptiness, GAP-44), so assert a minimum byte count and a required phrase per define.

---

P2-S10 — ISSUE_PR_LINK / ISSUE_BRANCH_TOKEN producers and the code.md paste → T3 (producer lines physically written in T2)

Goal: Give two consumed values their missing producers, so B2's ALWAYS-ON Closes #n rule does not die silently on GitHub too.

Files: (T2) git.md setup-task Output :236-253 and fetch-issue Output :268-284 — emit - **PR link line**: {rendered} and - **Branch token**: {token}. (T3) src/assets/agents/code.md:35 (ISSUE_NUMBER input), :93 (table row | Related Issues (ISSUE_NUMBER provided) | \## Related Issues` · `Closes #{n}` |), :95(ALWAYS-ON prose),:99(D11 sink +TRACEABILITY: DEGRADED (redaction unavailable)`).

Change: code.md pastes ISSUE_PR_LINK after re-checking its shape. Spawn key name ISSUE_NUMBER is KEPT at all 14 sites (implement.mds 8, dynamic-build.mds 6) — only its value becomes provider-canonical.

Conflict C11 (ownership): the step is assigned to T3, and the two producer lines are physically written by T2 under P2-S6's "Stays in git.md" column — T2 owns git.mds, and pathspec-scoped commits cannot straddle that. The T2 → T3 handoff carries the two Output-block literals verbatim so T3 wires against the exact strings.

Ids: GAP-15 (CRITICAL), AC-2.5, §F.5-A, B-7.

Verify: the P0-S16 seam test's **third

…truncated — full report in the local design artifact .devflow/docs/design/tracker-phase-2.2026-09-05_1155.md (not committed; ask the author)