Tracker Phase 1 — MDS plumbing, provably byte-identical

[dean0x]

Initial Request

src/assets/agents/git.md is a 938-line, 59,376-character hand-maintained file [verified: wc -c -l src/assets/agents/git.md → 938 59376] that Phase 2 must split into a contract layer plus generated per-provider references. Splitting it requires the MDS compiler to own it, but the build script today:

• only compiles src/assets/commands/*.mds;
• has no notion of a generator host — an agent file whose real frontmatter must survive as body text so loadShippedDefaults() can still read model:;
• validates its output directory with a raw string equality (scripts/build-mds.ts:166-173 [verified]: const expectedOutputDir = 'dist/commands'; if (host.outputDir !== expectedOutputDir) { … process.exit(1) });
• does not validate the output filename at all (scripts/build-mds.ts:178 [verified]: const dest = path.join(outAbs, \${host.basename}.md`)`);
• is unknown to the installer (src/targets/claude-code/installer.ts:498-524 [verified] reads agentsDir() only) and to the model pipeline (src/core/agent-models.ts:469-504 [verified] loadShippedDefaults reads agentsDir() only).

Phase 1 converts git.md → git.mds, teaches build-mds.ts the generator-host convention through a typed, Result-returning src/core/mds-variants.ts, makes the installer and the model pipeline read the compiled agent with a loud failure rather than a silent skip, and converts every remaining count literal into a name manifest so three later phases stop colliding on the same integer.

AC-1.1 is the whole review: dist/agents/git.md byte-identical to the Phase-0 golden.

Honest user-visible-change statement

"Zero user-visible change. dist/agents/git.md is byte-identical to the file it replaces, the 13 compiled command outputs are byte-unchanged, and the frozen github-status-lines.txt is untouched. The only observable difference is that npm run build:cli alone no longer produces installable agents — npm run build:mds is now required."

This sentence is the CHANGELOG entry and the PR's first paragraph. It is not marketing: it is the claim the golden test mechanically proves.

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

Product Requirements

Depends on

Phase 0 (#322) merged to main. Tracking issue: #321.

Acceptance criteria

• AC-1.1 — dist/agents/git.md byte-identical to the golden captured at the Phase-0 merge commit — this test is the review
• AC-1.2 — no @if with a single reachable arm, no variant list, no (module, op) iteration [DR-16 amendment] grep over the union src/assets/agents/git.mds ∪ src/core/mds-variants.ts ∪ scripts/build-mds.ts — not a git.mds-only grep, which cannot see src/core/ and so cannot mechanically check clause (iii)
• AC-1.3 (amended) — tarball install produces a working git agent; the src-fallback branch is exercised on an unconverted agent, and the loud-failure branch on git — because Phase 1's own negative guard deletes src/assets/agents/git.md, making "dist absent ⇒ falls back to src" unreachable for the converted agent — the AC text as originally written is self-contradictory for git; the reworded text above is the binding one
• AC-1.4 — loadShippedDefaults() has an entry for every getAllAgentNames(), and ['git'] === 'haiku'
• AC-1.5 — the 13 command outputs byte-unchanged
• AC-1.6 — registry completeness holds with git resolved from dist/agents
• AC-1.7 — build-mds exits 1 with the exact "typo?" message for dist/wrong-dir and rejects name-template: ../x, name-template: a/b, output-dir: dist/../.., output-dir: dist/commands/
• AC-1.8 — count literals are name manifests; the build's printed host/partial numbers agree with the manifest (a spawnSync assertion — no test asserts them today) NEW test required — the highest-risk P1 gap. See §12 row P1-a and [C16]. Tracked as open item O-8 in the master artifact.
• AC-1.9 — test:integration runs in CI and covers the dist-preferred agent path
• AC-1.10 — @mdscript/mds devDep pin 0.2.0 + lock mirror + absent-from-dependencies; a repo-wide grep for src/assets/agents/git.md returns only intended src-fallback sites
• AC-1.11 — the frozen status-line fixture unchanged
• AC-1.12 (new) — the tarball's src/assets/mds/*.mds entry count is pinned deliberately (0 or N) — the value is Gate-2 decision D-A: (a) ship it, pin the count
• 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)	Depends on	Gate before next	Handoff contents
S1	build script / TS core / installer	scripts/build-mds.ts (:101-104 readOutputDir [verified], :114-124 stripOutputDirKey [verified], :159-173 escape guard + dest pin [verified], IGNORE_DIRS :40-48 [verified], DEVFLOW_MDS_ROOT escape hatch :34 [verified]) · new src/core/mds-variants.ts · src/core/assets.ts (compiledAgentsDir() after commandsDir() :41-43 [verified]; optional mdsDir()) · src/targets/claude-code/installer.ts:498-524 [verified] · src/core/agent-models.ts:469-504 [verified] · new tests/mds-variants.test.ts · new tests/build-mds-generator-hosts.test.ts	Phase 0 merged to main	G1.1	the exact generator-frontmatter block shape stripGeneratorFrontmatter accepts (reproduced verbatim in §7 P1-S4); the 13 dist/commands/*.md SHA-256s recorded before and after S1, confirming they are unchanged; the new allowlist's resolved-path semantics
S2	prompt assets	src/assets/agents/git.md → src/assets/agents/git.mds (git mv + generator frontmatter + 142 brace escapes + 9 indented fences)	S1 (G1.1 green)	G1.2 — the hard gate	cmp -s dist/agents/git.md tests/fixtures/golden/git-agent.md exit 0, recorded verbatim; the enumerated list of the 9 indented fences with their git.mds line numbers; grep -c '\\{' dist/agents/git.md == 0; the statement that src/assets/agents/git.md no longer exists, which is why AC-1.3's src-fallback arm must be tested on an unconverted agent
S3	tests + packaging + docs	tests/build-mds.test.ts (:67-73, :85-89, :474-482 → name manifests [all verified]) · tests/packaging.test.ts (:42-95 Guard 3 [verified], :213-250 Guard 5 reason string, :324-337 [verified]) · tests/core-paths-assets.test.ts:64-79 · tests/build.test.ts · tests/git-agent.test.ts / registry-integrity.test.ts / skill-references.test.ts / agent-name-guards.test.ts / agent-frontmatter.test.ts (repoint audit — should be no-ops if Phase 0's resolver did its job) · new tests/guards/dist-agents.test.ts · package.json:9-17 [verified] · CLAUDE.md (:89, :91, :116, :257, :276) · five .devflow/features/*/KNOWLEDGE.md [drift: source §P1.3 says six; §0.7 and P1-S15 enumerate five] · docs/reference/platform-assumptions.md · CHANGELOG.md	S2 (G1.2 green)	G1.3	— (terminal)

Gates

Gate	Must be green before	Assertion
G1.1	S2 starts	npm run build exits 0; npm test green; the 13 dist/commands/*.md SHA-256s identical to the Phase-0 merge commit (AC-1.5); the five negative build cases (AC-1.7) exit 1 with the exact … is not the expected '…' — typo? message (AC-1.7).
G1.2	S3 starts — the hard gate	npm run build:mds exits 0 and cmp -s dist/agents/git.md tests/fixtures/golden/git-agent.md and grep -c '\\{' dist/agents/git.md == 0. No test may be repointed before this holds.
G1.3	PR opens	Full prefix-shippability (§2 standing AC); loadShippedDefaults() ⊇ getAllAgentNames() and ['git'] === 'haiku' (AC-1.4); registry completeness with git resolved from dist/agents (AC-1.6); the build's printed host/partial counts agree with the manifest via spawnSync (AC-1.8); github-status-lines.txt unchanged (AC-1.11).

/implement spawn notes

Subtask	Spawn parameters
S1	CREATE_PR: false · HANDOFF_REQUIRED: true
S2	CREATE_PR: false · HANDOFF_REQUIRED: true
S3	CREATE_PR: true · HANDOFF_REQUIRED: false (terminal; S3 opens the PR per implement.mds:409)

Commits are pathspec-scoped (git commit -- <owned paths>) so per-subtask provenance survives the squash-merge (PF-020's validated cheap mitigation). No PR split for Phase 1 (Gate-2 decision D-G) — the phase is one issue, one branch, one PR.

Execution strategy

SEQUENTIAL_CODE_AGENTS — 3 subtasks (S1 → S2 → S3). Context risk: CRITICAL.

Rationale:

• src/assets/agents/git.mds cannot compile until stripGeneratorFrontmatter and the resolved-path dest allowlist exist in scripts/build-mds.ts. The conversion's only verification is the build, so build changes must land first.
• The conversion (S2) is a 59,376-character transformation whose acceptance test is byte-equality against a frozen golden. This is the single highest-risk edit in the whole feature and must be the only thing in its agent's context.
• Test repointing (S3) must not begin until byte-equality holds, or a repointed test's red state is ambiguous between "the repoint is wrong" and "the conversion is wrong."

Why PARALLEL_CODE_AGENTS is rejected — the rejection holds and is phase-independent [DR-23]:

1. npm run build is rm -rf dist && npm run build:cli && npm run build:mds ([verified package.json:20]);
2. /implement has no worktree isolation — a grep for worktree in implement.mds returns zero hits;
3. read closures overlap across every partition (PF-020's 2026-08-30 closure rule).

Because 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 (AC-0.16 / §0.1-R3), any concurrent pair manufactures nondeterministic red. That disqualifier is independent of write-set disjointness. [DR-23] additionally records that Phase 1's S-level dependencies are hard, not merely scheduled: S2 cannot compile without S1's build changes, and S3's red states are ambiguous without S2's byte-equality — this is not one of the two weak dependencies DR-23 flags elsewhere in the plan. If per-agent worktrees ever land, Phase 1 is still not a parallelism candidate. This is a tooling limitation, not a plan limitation.

PR title

refactor(build): compile the Git agent from an MDS generator host

Implementation Plan

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

[dean0x]

Design artifact: tracker-phase-1.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: 323
title: "Tracker Phase 1 — MDS plumbing, provably byte-identical"
slug: tracker-phase-1
created: 2026-09-05T11:55:00Z
execution-strategy: SEQUENTIAL_CODE_AGENTS
context-risk: CRITICAL

Tracking issue: #321 · Depends on: Phase 0 (#322) merged to main · Next phase: Phase 2 (#324)

This artifact is self-contained by design. .devflow/docs/ is gitignored (PF-037 / H9), so a pointer to a sibling artifact resolves to "not committed; ask the author". Every normative rule this phase depends on is inlined below — §14 Normative Appendix carries the cross-phase text verbatim. Do not follow links for normative content; there are none.

---

1. Problem Statement

src/assets/agents/git.md is a 938-line, 59,376-character hand-maintained file [verified: wc -c -l src/assets/agents/git.md → 938 59376] that Phase 2 must split into a contract layer plus generated per-provider references. Splitting it requires the MDS compiler to own it, but the build script today:

• only compiles src/assets/commands/*.mds;
• has no notion of a generator host — an agent file whose real frontmatter must survive as body text so loadShippedDefaults() can still read model:;
• validates its output directory with a raw string equality (scripts/build-mds.ts:166-173 [verified]: const expectedOutputDir = 'dist/commands'; if (host.outputDir !== expectedOutputDir) { … process.exit(1) });
• does not validate the output filename at all (scripts/build-mds.ts:178 [verified]: const dest = path.join(outAbs, \${host.basename}.md`)`);
• is unknown to the installer (src/targets/claude-code/installer.ts:498-524 [verified] reads agentsDir() only) and to the model pipeline (src/core/agent-models.ts:469-504 [verified] loadShippedDefaults reads agentsDir() only).

Phase 1 converts git.md → git.mds, teaches build-mds.ts the generator-host convention through a typed, Result-returning src/core/mds-variants.ts, makes the installer and the model pipeline read the compiled agent with a loud failure rather than a silent skip, and converts every remaining count literal into a name manifest so three later phases stop colliding on the same integer.

AC-1.1 is the whole review: dist/agents/git.md byte-identical to the Phase-0 golden.

Honest user-visible-change statement

"Zero user-visible change. dist/agents/git.md is byte-identical to the file it replaces, the 13 compiled command outputs are byte-unchanged, and the frozen github-status-lines.txt is untouched. The only observable difference is that npm run build:cli alone no longer produces installable agents — npm run build:mds is now required."

This sentence is the CHANGELOG entry and the PR's first paragraph. It is not marketing: it is the claim the golden test mechanically proves.

---

2. Acceptance Criteria

AC text is verbatim from §F.3. Amendments are marked and are themselves normative. (process-only — PR checklist) marks an AC with no mechanical test — do not fake one (Gate-2 decision D-B; option (c), "assert a markdown table exists", was explicitly rejected as the vacuous-guard shape PF-018 names).

AC	Text (verbatim §F.3)	Pinning test	Status
AC-1.1	dist/agents/git.md byte-identical to the golden captured at the Phase-0 merge commit — this test is the review	expect(readFile('dist/agents/git.md')).toBe(loadGolden('git-agent.md')) + bytes(dist/agents/git.md) === 59376 as a named constant with its derivation in a comment	covered
AC-1.2	no @if with a single reachable arm, no variant list, no (module, op) iteration	[DR-16 amendment] grep over the union src/assets/agents/git.mds ∪ src/core/mds-variants.ts ∪ scripts/build-mds.ts — not a git.mds-only grep, which cannot see src/core/ and so cannot mechanically check clause (iii)	covered
AC-1.3 (amended)	tarball install produces a working git agent; the src-fallback branch is exercised on an unconverted agent, and the loud-failure branch on git — because Phase 1's own negative guard deletes src/assets/agents/git.md, making "dist absent ⇒ falls back to src" unreachable for the converted agent	tests/integration/pack-install.test.ts (in CI since P0-S25) + resolver tests	covered — the AC text as originally written is self-contradictory for git; the reworded text above is the binding one
AC-1.4	loadShippedDefaults() has an entry for every getAllAgentNames(), and ['git'] === 'haiku'	registry-completeness assertion (not scanned > 0) [verified: src/assets/agents/git.md:4 is model: haiku]	covered
AC-1.5	the 13 command outputs byte-unchanged	13 SHA-256s recorded before and after S1 (key-only strip retained)	covered
AC-1.6	registry completeness holds with git resolved from dist/agents	expect([...resolveAllAgents().keys()]).toEqual(expect.arrayContaining(getAllAgentNames())) — 16 today, 16 after the P1 rename	covered
AC-1.7	build-mds exits 1 with the exact "typo?" message for dist/wrong-dir and rejects name-template: ../x, name-template: a/b, output-dir: dist/../.., output-dir: dist/commands/	5 × spawnSync subprocess negatives, each status === 1, message preserved (/typo\?/i)	covered
AC-1.8	count literals are name manifests; the build's printed host/partial numbers agree with the manifest (a spawnSync assertion — no test asserts them today)	spawnSync assertion on the printed counts — grep for partial(s) skipped in tests/ returns zero hits today	NEW test required — the highest-risk P1 gap. See §12 row P1-a and [C16]. Tracked as open item O-8 in the master artifact.
AC-1.9	test:integration runs in CI and covers the dist-preferred agent path	ci.yml test:integration step (landed P0-S25)	covered
AC-1.10	@mdscript/mds devDep pin 0.2.0 + lock mirror + absent-from-dependencies; a repo-wide grep for src/assets/agents/git.md returns only intended src-fallback sites	Guard 3 devDep pin + lock sha512 mirror + negative-in-dependencies; grep AC	covered
AC-1.11	the frozen status-line fixture unchanged	tests/fixtures/golden/github-status-lines.txt byte-equal to its Phase-0 capture	covered
AC-1.12 (new)	the tarball's src/assets/mds/*.mds entry count is pinned deliberately (0 or N)	npm pack --dry-run count pinned	covered — the value is Gate-2 decision D-A: (a) ship it, pin the count

Phase-1 exit gate: AC-1.1 · AC-1.2 · AC-1.5 · AC-1.9 · AC-1.11 · F.5-G (i)–(iv).

Standing AC — prefix-shippability (§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 1: no partial, no tracker/ directory, no variant list, no @if. Its mechanical check is AC-1.2's widened grep union [DR-16].

Process-only AC rows (D-B)

The four cross-phase process ACs (AC-0.13, AC-0.15, AC-3.19, AC-2.11's release-blocker label) are enforced by a PR-template checklist in the tracking issue, not by a test. Phase 1's PR carries the checklist block: test-inventory table present with a red proof per guard · CHANGELOG enumerates the user-visible changes with before/after · prefix-shippability command sequence run and pasted · release-blocker items named in the release-readiness section. (process-only — PR checklist)

---

3. Scope

Included

• src/core/mds-variants.ts — new, typed, Result-returning, zero I/O. Exports exactly validateOutputName and resolveOutputDir [DR-16].
• scripts/build-mds.ts — reduced to a shell over mds-variants; stripGeneratorFrontmatter added alongside the retained key-only strip; IGNORE_DIRS += tests, coverage; resolved-path dest allowlist replacing the raw string equality.
• src/core/assets.ts — compiledAgentsDir() (+ optional mdsDir()).
• src/assets/agents/git.md → src/assets/agents/git.mds (git mv + generator frontmatter + brace escapes + indented-fence handling).
• src/targets/claude-code/installer.ts — dist-preferred agent resolution with loud failure.
• src/core/agent-models.ts — loadShippedDefaults reads compiledAgentsDir() merged over agentsDir(), dist wins.
• Test repoints via the Phase-0 resolver; new Phase-1 guards; count literals → name manifests.
• @mdscript/mds devDependency pin guard; deliberate tarball decision; Phase-1 docs sweep.

Deferred to Phase 2+ — explicitly excluded from this phase

Excluded	Why	Enforced by
Any MDS partial (_partials/ entry, src/assets/mds/** module)	clause (iii): a partial with one consumer that is itself unreachable is a Phase-2 artifact	AC-1.2 grep union
A tracker/ directory anywhere	same	AC-1.2 grep union; §0.6 prohibition "the token tracker-{provider}.md appears nowhere"
A variant list (variants: frontmatter key, (module, op) iteration)	Phase 1 has exactly one generator host with exactly one output — a one-element list is structurally identical to the single-arm @if AC-1.2 forbids	AC-1.2 grep union
Any @if directive in git.mds	a single reachable arm is dead structure	AC-1.2 grep union
expandVariants — the function and its tests/mds-variants.test.ts describe block	[DR-16] its only Phase-1 consumer would be its own unit test, which clause (iii) does not count. Introduced in P2-S13, where the (module, op) list is N ≥ 8 from its first commit	AC-1.2 grep union over src/core/mds-variants.ts
Extracting tracker ops into @define op(provider): blocks	Phase 2's contract/mechanics split	—
Regenerating tests/fixtures/golden/git-agent.md	Phase 1's oracle. Regenerating it defeats the phase	H2; AC-1.1
Regenerating tests/fixtures/golden/github-status-lines.txt	frozen through Phase 3	AC-1.11
_mcp.md, --emit, provider modules, .devflow/tracker.md, the Tracker agent	Phase 3	—

---

4. Gap Analysis Results

Gaps and edge cases this phase mitigates, each with the step that closes it.

ID	One-line	Step
GAP-07	scanned > 0 over the agent corpus stays green at 15 while git's coverage silently disappears — registry completeness is the only honest assertion	P1-S10 (repoints), P1-S9 (loadShippedDefaults ⊇ getAllAgentNames())
GAP-22	Every fallible build decision is an untyped inline branch in a file tsc does not check (scripts/ is excluded from tsc)	P1-S2, P1-S3, P1-S11
GAP-23	dist/agents is unknown to the installer, to loadShippedDefaults, to assets.ts and to the packaging guards	P1-S6, P1-S8, P1-S9, P1-S13
GAP-32	Docs drift after an asset-location change	P1-S15
GAP-49	A moved threshold is a lowered threshold — replace count literals with "green and the count has not decreased"	P1-S12
GAP-53	CLAUDE.md:276 ("no generated copies anywhere in the repo") is directly falsified by dist/agents/git.md	P1-S15 row 1
GAP-56	Three phases collide on the same integers (13 / 11 / 14)	P1-S12
GAP-57	The Node-22-only CI assumption is unrecorded (ci.yml matrix: node-version: [22] [verified] vs engines.node >=22.0.0)	P1-S15 row 9
EC-49	discoverHosts() output is unpinned in both directions	P1-S11 (discovery manifest)
EC-50	A .mds fixture under tests/fixtures/ with an output-dir: key writes into the real dist/	P1-S5
EC-51	Dest validation is a raw string equality; mkdirSync(recursive) at :176 runs after the pin, so parent-dir existence was never the blocker	P1-S2, P1-S3
EC-52	The tarball ships src/assets/ wholesale; src/assets/agents/git.mds becomes dead source with no deliberate decision behind it	P1-S14
S12	Output filename is never validated — name-template is a path-injection surface	P1-S2 (^[a-z0-9][a-z0-9._-]{0,63}$, rejects /, \, any .. segment)

---

5. Execution Strategy

SEQUENTIAL_CODE_AGENTS — 3 subtasks (S1 → S2 → S3). Context risk: CRITICAL.

Rationale:

• src/assets/agents/git.mds cannot compile until stripGeneratorFrontmatter and the resolved-path dest allowlist exist in scripts/build-mds.ts. The conversion's only verification is the build, so build changes must land first.
• The conversion (S2) is a 59,376-character transformation whose acceptance test is byte-equality against a frozen golden. This is the single highest-risk edit in the whole feature and must be the only thing in its agent's context.
• Test repointing (S3) must not begin until byte-equality holds, or a repointed test's red state is ambiguous between "the repoint is wrong" and "the conversion is wrong."

Why PARALLEL_CODE_AGENTS is rejected — the rejection holds and is phase-independent [DR-23]:

1. npm run build is rm -rf dist && npm run build:cli && npm run build:mds ([verified package.json:20]);
2. /implement has no worktree isolation — a grep for worktree in implement.mds returns zero hits;
3. read closures overlap across every partition (PF-020's 2026-08-30 closure rule).

Because 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 (AC-0.16 / §0.1-R3), any concurrent pair manufactures nondeterministic red. That disqualifier is independent of write-set disjointness. [DR-23] additionally records that Phase 1's S-level dependencies are hard, not merely scheduled: S2 cannot compile without S1's build changes, and S3's red states are ambiguous without S2's byte-equality — this is not one of the two weak dependencies DR-23 flags elsewhere in the plan. If per-agent worktrees ever land, Phase 1 is still not a parallelism candidate. This is a tooling limitation, not a plan limitation.

Context-risk driver: ~15 files, ~1,500 changed lines — but the number that matters is the single 59,376-character file whose acceptance criterion is byte equality. An LLM re-emitting that body will silently drift; the golden catches it, but the repair loop is expensive and the failure mode ("which of 938 lines differs?") is precisely where an agent is tempted to regenerate the golden.

MANDATORY EXECUTION CONSTRAINT (H1 / H2) — read before touching S2

The Code agent must NEVER re-emit git.md's body.

The conversion is, in this exact order:

1. git mv src/assets/agents/git.md src/assets/agents/git.mds
2. a scripted escape pass — a throwaway node/sed transform the agent authors and runs against the file
3. npm run build:mds && cmp -s dist/agents/git.md tests/fixtures/golden/git-agent.md
4. on mismatch: iterate on the script, never on the file

This turns a 59 KB generation problem into a ~40-line program with a deterministic oracle. The 9 indented fences are the exception requiring hand attention — de-indent to column 0 or escape their contents individually.

Highest consequence: git.md:342-350 and :352-362 [verified] — the post-review-summary FULL and STUB bodies. Both are indented fences inside a numbered list, and both contain {CYCLE_NUMBER} and {REVIEW_TIMESTAMP} inside the dedup marker <!-- devflow:review-summary cycle:{CYCLE_NUMBER} ts:{REVIEW_TIMESTAMP} -->. A lost interpolation yields the marker cycle: ts: and silently breaks D7 dedup on GitHub — a live user-visible regression the golden catches only because the golden exists.

grep -c '\\{' dist/agents/git.md must be 0 (PF-024's seventh instance — escaped braces leaking literal backslashes into dist).

A golden mismatch means the source is wrong, never the fixture. The golden is immutable in Phase 1. npm run test:golden:update -- <target> [DR-03] — target required; github-status-lines refused without --unfreeze. A documented manual ritual only the designated regeneration subtask (P2-S16, Phase 2) may run; CI never auto-regenerates.

---

6. Subtask Breakdown

#	Domain	Owned files (with anchors)	Depends on	Gate before next	Handoff contents
S1	build script / TS core / installer	scripts/build-mds.ts (:101-104 readOutputDir [verified], :114-124 stripOutputDirKey [verified], :159-173 escape guard + dest pin [verified], IGNORE_DIRS :40-48 [verified], DEVFLOW_MDS_ROOT escape hatch :34 [verified]) · new src/core/mds-variants.ts · src/core/assets.ts (compiledAgentsDir() after commandsDir() :41-43 [verified]; optional mdsDir()) · src/targets/claude-code/installer.ts:498-524 [verified] · src/core/agent-models.ts:469-504 [verified] · new tests/mds-variants.test.ts · new tests/build-mds-generator-hosts.test.ts	Phase 0 merged to main	G1.1	the exact generator-frontmatter block shape stripGeneratorFrontmatter accepts (reproduced verbatim in §7 P1-S4); the 13 dist/commands/*.md SHA-256s recorded before and after S1, confirming they are unchanged; the new allowlist's resolved-path semantics
S2	prompt assets	src/assets/agents/git.md → src/assets/agents/git.mds (git mv + generator frontmatter + 142 brace escapes + 9 indented fences)	S1 (G1.1 green)	G1.2 — the hard gate	cmp -s dist/agents/git.md tests/fixtures/golden/git-agent.md exit 0, recorded verbatim; the enumerated list of the 9 indented fences with their git.mds line numbers; grep -c '\\{' dist/agents/git.md == 0; the statement that src/assets/agents/git.md no longer exists, which is why AC-1.3's src-fallback arm must be tested on an unconverted agent
S3	tests + packaging + docs	tests/build-mds.test.ts (:67-73, :85-89, :474-482 → name manifests [all verified]) · tests/packaging.test.ts (:42-95 Guard 3 [verified], :213-250 Guard 5 reason string, :324-337 [verified]) · tests/core-paths-assets.test.ts:64-79 · tests/build.test.ts · tests/git-agent.test.ts / registry-integrity.test.ts / skill-references.test.ts / agent-name-guards.test.ts / agent-frontmatter.test.ts (repoint audit — should be no-ops if Phase 0's resolver did its job) · new tests/guards/dist-agents.test.ts · package.json:9-17 [verified] · CLAUDE.md (:89, :91, :116, :257, :276) · five .devflow/features/*/KNOWLEDGE.md [drift: source §P1.3 says six; §0.7 and P1-S15 enumerate five] · docs/reference/platform-assumptions.md · CHANGELOG.md	S2 (G1.2 green)	G1.3	— (terminal)

Gates

Gate	Must be green before	Assertion
G1.1	S2 starts	npm run build exits 0; npm test green; the 13 dist/commands/*.md SHA-256s identical to the Phase-0 merge commit (AC-1.5); the five negative build cases (AC-1.7) exit 1 with the exact … is not the expected '…' — typo? message (AC-1.7).
G1.2	S3 starts — the hard gate	npm run build:mds exits 0 and cmp -s dist/agents/git.md tests/fixtures/golden/git-agent.md and grep -c '\\{' dist/agents/git.md == 0. No test may be repointed before this holds.
G1.3	PR opens	Full prefix-shippability (§2 standing AC); loadShippedDefaults() ⊇ getAllAgentNames() and ['git'] === 'haiku' (AC-1.4); registry completeness with git resolved from dist/agents (AC-1.6); the build's printed host/partial counts agree with the manifest via spawnSync (AC-1.8); github-status-lines.txt unchanged (AC-1.11).

/implement spawn notes

Subtask	Spawn parameters
S1	CREATE_PR: false · HANDOFF_REQUIRED: true
S2	CREATE_PR: false · HANDOFF_REQUIRED: true
S3	CREATE_PR: true · HANDOFF_REQUIRED: false (terminal; S3 opens the PR per implement.mds:409)

Commits are pathspec-scoped (git commit -- <owned paths>) so per-subtask provenance survives the squash-merge (PF-020's validated cheap mitigation). No PR split for Phase 1 (Gate-2 decision D-G) — the phase is one issue, one branch, one PR.

Reconciliation applied — Conflict C9 (P1-S8 / P1-S9 placement)

plan-1's dependency graph puts P1-S8 (installer) and P1-S9 (loadShippedDefaults) after P1-S7 (the rename); plan-3 puts installer.ts and agent-models.ts in S1, before S2. Both are satisfied by splitting code from proof. The code change (dist-preferred → src-fallback → throw-with-hint) is behaviour-neutral before the rename: dist/agents does not exist yet, so the fallback path applies and every existing test stays green. It lands in S1, with its RED proof taken against a synthetic mkdtemp tree (a fake dist/agents; a missing src/assets/agents/git.md) — the third RED mechanic in §0.1-R1, and the one installer-new.test.ts already uses. The live proofs (loadShippedDefaults()['git'] === 'haiku' with git resolved from dist/agents; the installer's real dist-preferred read) are asserted at G1.3, after S2. This satisfies plan-3's file ownership (which pathspec-scoped commits require) and plan-1's dependency semantics (which is about proof, not about code).

---

7. Implementation Plan

Authoring order for every step: write the guard → observe RED → apply the change → GREEN. A guard with no known-bad sample is not accepted (§0.1-R1). An agent must never revert a landed fix to demonstrate red (H10).

P1-S1 — Branch and pre-flight (prep) → S1

• Goal: Branch from main after P0's squash-merge and confirm the golden is the measurement subject.
• Files: none (branch only).
• Verify: loadGolden('git-agent.md') equals src/assets/agents/git.md byte-for-byte at HEAD; the four gate commands (npm run build && npm test && npm run test:integration && npm pack --dry-run) green.
• Deps: Phase 0 (Tracker Phase 0 — harness first + live-defect fixes #322) merged to main. No phase PR is ever opened against another phase's branch (§14 merge protocol).

P1-S2 — src/core/mds-variants.ts (typed, Result-returning, zero I/O) → S1

• Goal: Extract every fallible build decision into a pure typed module so build-mds.ts becomes a shell.
• Files: new src/core/mds-variants.ts.
• Change: exports validateOutputName and resolveOutputDir [DR-16 — expandVariants REMOVED from this step's export list; Phase 1 ships only validateOutputName, resolveOutputDir and (in build-mds.ts) stripGeneratorFrontmatter. expandVariants moves to Phase 2, P2-S13], each returning a local Result — src/core/agent-frontmatter.ts:19 [verified: // Result type (local; matches codebase per-module pattern)] records that per-module Result duplication is deliberate policy; do not import a shared one. The module header restates agent-frontmatter.ts:1-16 [verified] in shape: "Pure module — zero I/O … applies ADR-013 … avoids PF-014: no process.exit(); all fallible paths return Result."
  • validateOutputName uses ^[a-z0-9][a-z0-9._-]{0,63}$ — the charset S12 prescribes, structurally MODEL_NAME_RE (agent-frontmatter.ts:42) — and rejects /, \, and any .. segment.
  • resolveOutputDir calls src/core/paths.ts:20-26 isContainedIn [verified: pure, relative()-based, already exists] rather than re-deriving the startsWith(outAbs + path.sep) form build-mds.ts:160 hand-rolls today.
• Ids: S12, AC-1.7, GAP-22, EC-51. [DR-16]
• RED-first: unit tests RED for each hostile input: name-template: ../x, name-template: a/b, output-dir: dist/../.., output-dir: dist/commands/. Note that scripts/ is excluded from tsc, so this module living in src/core/ is what makes it type-checked at all.

P1-S3 — build-mds.ts reduced to a shell over mds-variants → S1

• Files: scripts/build-mds.ts:
  • :101-104 [verified] readOutputDir → readFrontmatterKey, still a scalar regex — there is no YAML parser anywhere and §C.6 forbids adding one;
  • :114-124 [verified] keep stripOutputDirKey for the 13 commands so their bytes do not move;
  • :159-164 [verified] keep the path-escape guard; add validateOutputName before const dest = path.join(outAbs, …) at :178 [verified];
  • :166-173 [verified] replace the expectedOutputDir === 'dist/commands' raw equality with a resolved-path allowlist (dist/commands, dist/agents), preserving the exact ${rel}: output-dir '${host.outputDir}' is not the expected '${expected}' — typo? message and process.exit(1).
• Change: all process.exit stays in the script; the shell exits on !ok. fs.mkdirSync(outAbs, { recursive: true }) at :176 [verified] runs after the pin, so parent-dir existence was never the blocker (EC-51).
• Ids: AC-1.5, AC-1.7, EC-51, S12.
• RED-first / Verify: build-mds.test.ts:495-531-shaped spawnSync subprocess tests for every new build branch — mkdtemp fake root → write fixtures under <fakeRoot>/src/assets/commands/ → spawnSync(TSX_BIN, [path.join(ROOT,'scripts','build-mds.ts')], { cwd: ROOT, encoding:'utf-8', timeout: 60_000, env: { ...process.env, DEVFLOW_MDS_ROOT: fakeRoot } }) → if (result.error) throw result.error → expect(result.status).toBe(1) → expect(stdout+stderr).toMatch(/typo\?/i) → finally { await fs.rm(fakeRoot, { recursive: true, force: true }) }. [verified shape] This is the only existing shape that tests build branches.

P1-S4 — stripGeneratorFrontmatter + the generator-host convention → S1

• Goal: Let an agent file carry its real frontmatter as body text so model: stays visible to loadShippedDefaults().

• Files: scripts/build-mds.ts:114-124 [verified] — add stripGeneratorFrontmatter (whole first block) alongside the retained key-only strip.

• Change: the host shape, demonstrated byte-identical during the CONTEXT-PACK measurement run (mds-proto/agents/git_p.mds:1-12 [drift: the mds-proto/ prototype tree is not committed to this repo — the shape it demonstrates is reproduced verbatim here, which is the load-bearing part]):

  ---
  output-dir: dist/agents
  ---
  @import { … } from "./…"
  ---
  name: Git
  description: Unified agent for all git/GitHub operations - issues, PR comments, tech debt, releases
  model: haiku
  skills:
    - devflow:git
    - devflow:worktree-support
  ---
  
  <body …>
  

  Block 1 (output-dir:) is stripped whole. Block 2 carries the agent's real name/description/model/skills [verified against src/assets/agents/git.md:1-8] and becomes body text with its trailing blank line preserved.

• Ids: AC-1.4, AC-1.5, and the MDS facts below (frontmatter at offset 0 is emitted verbatim; blank lines immediately after the closing --- are DELETED — hence the second block, not the first).

• RED-first / Verify: subprocess test asserting the 13 command outputs byte-unchanged (AC-1.5) and that the generator host's second block survives with its blank line.

P1-S5 — Harden IGNORE_DIRS → S1

• Files: scripts/build-mds.ts IGNORE_DIRS (:40-48 [verified: node_modules, dist, .git, .devflow, .claude, .release, tmp]) — add tests, coverage. Keep the DEVFLOW_MDS_ROOT escape hatch (:34 [verified]) — every subprocess build test depends on it.
• Change: lands in the same PR that introduces src/assets/mds/-adjacent fixtures — a .mds fixture under tests/fixtures/ with an output-dir: key otherwise writes into the real dist/. [deviation from source P1-S5: src/assets/mds/ does not exist until Phase 2; the Phase-1 trigger is the new .mds test fixtures]
• Ids: EC-50.
• RED-first: a fixture .mds under tests/fixtures/ with output-dir: dist/commands is discovered before the change and not after.

P1-S6 — compiledAgentsDir() (+ optional mdsDir()) → S1

• Files: src/core/assets.ts — add compiledAgentsDir() → join(getPackageRoot(), 'dist', 'agents') immediately after commandsDir() (:41-43 [verified]); optional mdsDir() for manifests.
• Ids: AC-1.3, AC-1.4, GAP-23.
• Verify: tests/core-paths-assets.test.ts:64-79 — keep the existing agentsDir() shape tests, add compiledAgentsDir() equivalents.

MDS facts the conversion relies on

Measured on the installed compiler (@mdscript/mds 0.2.0, native backend with WASM fallback; a devDependency, invoked as compileFile(path, { vars })). These are load-bearing for P1-S7's escape pass — the whole conversion is a direct consequence of them.

1. Only column-0 triple-backtick fences are raw. Indented fences, ~~~ fences, inline code and prose ARE interpolated. \{x\} ⇒ {x}. Params do not interpolate inside column-0 fences.
2. Frontmatter at byte offset 0 is emitted verbatim and is NOT interpolated. This is why the generator block must be block 1 and the agent's real frontmatter block 2.
3. Blank lines immediately after the closing --- are DELETED. This is the second reason for the two-block host shape: the agent's real frontmatter must be body, so its following blank line survives.
4. 2+ consecutive blank lines collapse to 1 — even inside fences. Trailing newline appended. Everything else is byte-preserved.
5. One output string per compile ⇒ N provider files = N compileFile calls with different vars. All 13 hosts compile in ~7 ms; re-compiling reproduces the committed dist/commands/*.md byte-for-byte (13/13).
6. Byte-identical agent extraction is achievable and was demonstrated — the measurement run reproduced 59,376 bytes == today's git.md through a generator host. Hazards recorded by that run: braces outside fences need \{ \}; an inline @define used as a scalar injects a trailing newline (use vars for scalars); indented fences in numbered lists (e.g. git.md L346) are interpolated.
7. Undefined variable ⇒ hard fail mds::undefined_var. No recursion. No </>, no in, no inline array literals.
8. Runtime selection is impossible in MDS — compile-time only; zero directives survive into dist. (Recorded for Phase 2/3; Phase 1 uses no directives at all.)

P1-S7 — The escape pass: 142 braces and 9 indented fences in git.md → S2

• Goal: Convert git.md to git.mds with zero byte movement.
• Files: src/assets/agents/git.md → src/assets/agents/git.mds (git mv — never delete-and-recreate, or the diff becomes unreviewable and the body is at risk of re-emission).
• Change: verified counts: 142 opening braces outside column-0 fences; 18 indented-fence lines = 9 indented fences. Per MDS fact 1:
  • escape every { / } outside a column-0 fence as \{ / \};
  • for the 9 indented fences, either de-indent to column 0 or escape their contents — decide per fence, and enumerate all 9 with their git.mds line numbers in the S2 handoff;
  • highest consequence: git.md:342-350 (FULL mode) and :352-362 (STUB mode) [verified] — the post-review-summary bodies. Both carry <!-- devflow:review-summary cycle:{CYCLE_NUMBER} ts:{REVIEW_TIMESTAMP} -->; a lost {CYCLE_NUMBER} / {REVIEW_TIMESTAMP} yields marker cycle: ts: and silently breaks D7 dedup on GitHub;
  • the escape-pass asymmetry (escaped in prose vs raw inside a column-0 fence) is the only rule the transform script needs — a fence-state machine over the file, escaping outside column-0 fences and leaving inside them alone. Worked example: mds-proto/agents/_partials/_tracker_p.mds:21/:24/:35/:39 (escaped in prose) vs :44-60 (raw inside a column-0 fence) [prototype tree from the planning scratchpad, not committed — the two-block host shape is reproduced inline in P1-S4].
• Ids: B-4, AC-1.1, AC-1.2 (single generator host — no partial, no tracker/ directory, no variant list, no @if; ADR-003 clause (iii)).
• Method — non-negotiable (H1): git mv → scripted transform → npm run build:mds → cmp → iterate on the script. The Code agent never re-emits the body. See §5's mandatory execution constraint.
• Verify: AC-1.1 is the whole review — dist/agents/git.md byte-identical to loadGolden('git-agent.md'). Additionally: the escaped-brace guard (build-mds.test.ts:283-300) extended to dist/agents, RED if a single \{ is missed; grep -c '\\{' dist/agents/git.md == 0 (PF-024's seventh instance).

P1-S8 — Installer per-agent dist-preferred resolution with loud failure → S1 (code) / G1.3 (live proof)

• Files: src/targets/claude-code/installer.ts:498-524 [verified] — the loop resolves path.join(aDir, mdFileName(agentName)) and throws at :519-521 [verified text: Agent source not found for declared agent "${agentName}": ${srcFile}. Ensure the agent file exists in src/assets/agents/.].
• Change: try compiledAgentsDir() first, fall back to agentsDir(), throw with the npm run build:mds hint appended to the existing text. Never silently skip — tests/helpers.ts:14-23 [verified: "A guard that silently skips on a missing build artifact is not a guard."] is the doctrine.
• Ids: AC-1.3 (amended), GAP-23.
• Placement: code in S1, live proof at G1.3 [C9] — behaviour-neutral before the rename because dist/agents does not exist yet.
• RED-first: synthetic mkdtemp tree — a fake dist/agents (dist-preferred branch) and a missing src/assets/agents/git.md (loud-failure branch).
• Verify: tests/installer-new.test.ts:434-435 [verified anchor, drift D17: plan-1 said :435] asserts expect(caught!.message).toContain('src/assets/agents') — Phase 1 rewrites that error text; update it in the same commit (or it was already repointed to a stable substring in P0-A3). AC-1.3 is self-contradictory for git and is reworded (see §2): test the src-fallback on an unconverted agent and the loud failure on git, because P1-S11's negative guard deletes src/assets/agents/git.md, making "dist absent ⇒ falls back to src" unreachable for the converted agent.

P1-S9 — loadShippedDefaults reads the compiled dir merged over src → S1 (code) / G1.3 (live proof)

• Files: src/core/agent-models.ts:469-504 [verified: export async function loadShippedDefaults() reads agentsDir() only].
• Change: read compiledAgentsDir() merged over agentsDir() (dist wins), leaving mdEntryName (src/core/orphan-sweep.ts:39-41) .md-only. Closing the "make mdEntryName extension-aware" branch explicitly prevents a meaning change at four call sites, two of which are installed-directory orphan sweeps.
• Ids: AC-1.4, GAP-23.
• Placement: code in S1, live proof at G1.3 [C9].
• RED-first: loadShippedDefaults() ⊇ getAllAgentNames() (16) and loadShippedDefaults()['git'] === 'haiku' [verified: src/assets/agents/git.md:4 is model: haiku] — both fail against the rename without this change. Known-bad for non-vacuity: drop git from the merge ⇒ red.

P1-S10 — Test repoints (all via the resolver, zero literal paths) → S3

• Files:
  • tests/git-agent.test.ts:2 / :18 / :42;
  • tests/agent-frontmatter.test.ts:21 and :35-53 — the hardcoded 16-filename array containing 'git.md', under a describe titled "all 16 real agent files" at :35. This is the only hand-maintained agent enumeration in the repo;
  • tests/registry-integrity.test.ts:393 [verified, drift D2: plan said :392, which is distCommandsDir] and :49-56;
  • tests/build.test.ts:45-55 / :84-92 / :100-140 [drift D21 — UNRESOLVED: plan-1 says :46-55 / :84-91 / :106-135, plan-2 says the wider ranges; neither is marked verified. Re-verify at implementation time and prefer the wider plan-2 ranges so nothing is missed];
  • tests/skill-references.test.ts:231, :248-262 [drift D5: plan said :247], :275-292 [drift D5: plan said :270], :954 [drift D5: :951 is the it( title];
  • tests/agent-name-guards.test.ts:34, :513, :746-750;
  • tests/core-paths-assets.test.ts:64-79.
• Change: replace agent-frontmatter.test.ts's literal array with getAllAgentNames() in this commit (GAP-07). Without repointing skill-references.test.ts, git's frontmatter skills: coverage silently disappears — that file is the one repoint whose omission is invisible.
• Ids: AC-1.6, GAP-07.
• Deps: P0-S17 (the resolver), P1-S7 (the rename).
• Verify: expect([...resolveAllAgents().keys()]).toEqual(expect.arrayContaining(getAllAgentNames())) holds with git resolved from dist/agents; RED if any repoint is missed. If P0-A3 did its job, most of these are no-ops — an audit, not a rewrite.
• Mode discipline [DR-18]: every extractOpSectionFromCorpus call names its mode — D11 forward guard 'union'; seam-test **Input:** lookup 'sole'; Guard 2's bound its 'sole' (the moved copy) — see §8 mode-discipline table.
• Anti-pattern to name explicitly: scanned > 0 over the agent corpus. Two scanned > 0-shaped assertions already exist and would stay green at 15 while git's coverage vanishes (GAP-07 / B-11). Registry completeness is the only honest assertion.

P1-S11 — New Phase-1 guards → S3

• Files: new its across tests/build-mds.test.ts, tests/build.test.ts, tests/packaging.test.ts; new tests/guards/dist-agents.test.ts.
• Change:
  • Guard-4-equivalent for dist/agents — dist↔src both ways, with the fail-loud fix. Do not copy tests/packaging.test.ts:121-137 Guard 4, which has catch { return } and if (distFiles.length === 0) return and is green when the corpus is absent. Copy requireDistFiles()'s throw-with-a-build-hint contract instead.
  • spawnSync subprocess tests for every new build branch (the build-mds.test.ts:495-531 shape).
  • Recursive partial guard + an explicit no-subdirectories assertion — build-mds.test.ts:85-89 [verified: fs.readdir(PARTIALS_DIR, { withFileTypes: true }), non-recursive] is exactly why _partials/ must have no subdirectories.
  • A discovery manifest assertion: discoverHosts() output equals an explicit (file, role, outputDir) list, both directions (EC-49).
  • The escaped-brace guard extended to dist/agents.
  • A negative guard: "no .md in src/assets/agents/ for any agent with an .mds host".
• Ids: AC-1.7, EC-49, EC-50, GAP-22.
• RED-first: each guard RED against a named known-bad fixture — dist/agents/orphan.md with no source; the four bad frontmatter values (dist/wrong-dir, dist/../.., dist/commands/, name-template: ../x / a/b).

P1-S12 — Count literals → name manifests → S3

• Goal: Stop three phases from colliding on the same integer, and close the un-asserted printed counts.
• Files: tests/build-mds.test.ts:67-73 (13 hosts [verified: expect(hostFiles).toHaveLength(13)]), :85-89 (11 partials, non-recursive readdir [verified]), :474-482 (14 dist files [verified: .toBe(14)]); tests/packaging.test.ts:324-337 ([verified: .toHaveLength(14)]).
• Change: replace each literal with a name manifest derived from the same manifest the build reads, following the src/core/compliance-compose.ts bidirectional-registry model [verified: :20 COMPLIANCE_CONTROL_COLUMNS, :36 COMPLIANCE_SKILL_TOKENS, :50 COMPLIANCE_RULE_TOKENS, each documented "every token here must exist in the template; every template token must be listed here"].
• The AC-1.8 problem, stated precisely [C16]: scripts/build-mds.ts:219-221 [verified] prints

  const partialCount = totalCount - hosts.length;
  console.log(`  ${partialCount} partial(s) skipped (no output-dir:)`);
  console.log(`  ${hosts.length} host(s) to compile:\n`);
  

  totalCount comes from a repo-wide walk, while build-mds.test.ts:85-89 is scoped to PARTIALS_DIR. So Phase 2's src/assets/mds/tracker/*.mds will change the printed number while the scoped guard stays green. A grep for partial(s) skipped in tests/ returns zero hits today — nothing asserts these numbers at all. AC-1.8 therefore requires a spawnSync assertion on the build's printed output, built in Phase 1.
• Ids: AC-1.8, EC-49, GAP-56, F.5-H, GAP-49.
• RED-first: add a fixture host under a DEVFLOW_MDS_ROOT tree and assert both the manifest guard and the printed-count guard go red. Manifest length floors asserted (>= 13, >= 11) — the floors never decrease (§0.1-R2: when text moves, the corpus widens; the number does not move).

P1-S13 — @mdscript/mds devDependency pin guard → S3

• Files: tests/packaging.test.ts:42-95 (Guard 3).
• Change: loadDependencies() reads only pkgJson.dependencies [verified :45-52: const pkgJson = JSON.parse(...) as { dependencies?: Record<string,string> }; dependencies = pkgJson.dependencies ?? {}], so the pin cannot go there as originally specified. Add:
  1. a devDependency-scoped assertion (=== '0.2.0', no ^, no ~);
  2. the lock sha512 mirror (mirroring packaging.test.ts:73-95);
  3. a negative assertion that @mdscript/mds is absent from dependencies.
• Ids: AC-1.10, GAP-23.
• RED-first: RED against ^0.2.0; RED against a dependencies entry.

P1-S14 — Deliberate tarball decision → S3

• Files: package.json:9-17 [verified: files: ["dist/", "!dist/**/*.map", "!dist/**/*.d.ts", "src/assets/", "src/targets/claude-code/templates/", "README.md", "LICENSE", "CHANGELOG.md"]]; tests/packaging.test.ts:213-250 Guard 5.
• Decision — Gate-2 D-A, option (a), ACCEPTED: ship src/assets/mds/** and src/assets/agents/git.mds in the tarball. No files change. Rationale: the 13 command .mds sources already ship today under the wholesale src/assets/ entry; excluding the new ones would diverge from an unbroken precedent and create a second rule to remember when a future asset type is added. The cost is a few tens of KB of dead source, which a consumer who inspects the package can at least read honestly.
• Change: dist/agents/ already ships (no files change required). P1-S14 pins the npm pack --dry-run count deliberately and updates packaging Guard 5's reason string, which today describes src/assets/ as "skills, agents, rules, hook scripts" — untrue once .mds generator hosts ship. New reason string names the generator sources explicitly.
• Ids: AC-1.12 (new), EC-52.
• Verify: npm pack --dry-run assertion pinning the expected src/assets/**/*.mds entry count at N (not 0); Guard 5's reason string updated in the same commit.

P1-S15 — Phase-1 docs sweep → S3

Rule (H6 / PF-025): this subtask sweeps the branch's final tree, not its own commit, and greps for artifact names (git.md, src/assets/agents/git.md, dist/agents) rather than re-reading remembered files.

#	File:line	Change
1	CLAUDE.md:276	"src/assets/skills/, src/assets/agents/, and src/assets/rules/ are the single source of truth — no generated copies anywhere in the repo" is directly falsified by dist/agents/git.md. Restate as: "generated files never live in src/" (GAP-53)
2	CLAUDE.md:91	"13 hosts + 11 partials" — restate against the P1-S12 manifest rather than the integers
3	CLAUDE.md:89, :116, :257	agent count / vim src/assets/agents/code.md / "Shared agents live in src/assets/agents/" — note the .mds host exception
4–8	.devflow/features/{compliance-feature :12/:298· resolve-pipeline:6/:97/:291· installer-shadowing:36/:56· dynamic-workflow-engine:71/:278· feature-knowledge-system:109/:188}/KNOWLEDGE.md	path literals naming src/assets/agents/git.md
9	docs/reference/platform-assumptions.md	Record the Node-22-only CI assumption (GAP-57; ci.yml matrix: node-version: [22] [verified] vs engines.node >=22.0.0). The file is created in Phase 0, extended here, and completed in 3a — a deliberate, labelled three-phase treatment [DR-28]
10	CLAUDE.md Build System	Record that npm run build:cli alone no longer produces installable agents
11	CHANGELOG.md	### Changed — the build now compiles git.md from an MDS generator host; zero user-visible change

• Ids: GAP-53, GAP-57, GAP-32.
• Verify: the retired-wording grep's Phase-1 allowlist adds "no generated copies anywhere"; a repo-wide grep for src/assets/agents/git.md returns only intended src-fallback sites (AC-1.10).
• Note [DR-28]: dynamic-workflow-engine/KNOWLEDGE.md is touched by Phase 0 (14th command + DIST_FILES divergence) and Phase 1 (:71/:278 path literals) at disjoint anchors. §0.7's invariant is "no docs change is made twice", not "no file is swept twice"; H6's final-tree rule is what makes the overlap safe.

---

8. Test Strategy

New test files

Path	describe blocks	Precedent
tests/mds-variants.test.ts	validateOutputName · resolveOutputDir (containment) · Result error-union completeness. [DR-16: the expandVariants describe block is REMOVED from this file and moves to Phase 2]	tests/agent-frontmatter.test.ts structure; src/core/agent-frontmatter.ts:42 MODEL_NAME_RE is the literal charset S12 prescribes
tests/build-mds-generator-hosts.test.ts	generator frontmatter whole-block strip · 13 command outputs byte-unchanged (key-only strip retained) · dest allowlist negatives · filename validation negatives · IGNORE_DIRS covers tests/ and coverage/ · printed host/partial counts agree with the manifest	tests/build-mds.test.ts:495-531 [verified] — mkdtemp + spawnSync(TSX_BIN, [script], { cwd: ROOT, encoding:'utf-8', timeout: 60_000, env: { ...process.env, DEVFLOW_MDS_ROOT: fakeRoot } }) → if (result.error) throw result.error → expect(result.status).toBe(1) → expect(stdout+stderr).toMatch(/typo\?/i) → finally { await fs.rm(fakeRoot, { recursive: true, force: true }) }. scripts/ is excluded from tsc, so every new build branch needs one of these
tests/guards/dist-agents.test.ts	Guard-4-equivalent for dist/agents (dist↔src both ways) · escaped-brace guard extended to dist/agents · no .md in src/assets/agents for any agent with an .mds host	tests/packaging.test.ts:121-137 Guard 4 shape — with the fail-loud fix, never its catch { return }

File-naming scheme (repo-wide for this feature): tests/seams/ · tests/goldens/ · tests/guards/ · tests/tracker/ · tests/installer/ · tests/dynamic/ · tests/core/.

Existing tests: count literals → name manifests

Anchor [verified]	Today	Becomes
tests/build-mds.test.ts:67-73	expect(hostFiles).toHaveLength(13)	set-equality against the manifest the build itself reads
tests/build-mds.test.ts:85-89	expect(partialFiles).toHaveLength(11) (non-recursive readdir; [verified: 11 files, no subdirs])	name manifest + an explicit no-subdirectories assertion
tests/build-mds.test.ts:474-482	.toBe(14) dist files	name manifest (13 compiled + release.md)
tests/packaging.test.ts:324-337	.toHaveLength(14) tarball dist commands	the same manifest

Repoints — all via the resolver, zero literal agent paths

As P1-S10. The contract is resolveAgentSource(name) → { path, content, origin: 'dist' | 'src' } (dist-preferred, ENOENT-tolerant on the dist side only) and resolveAllAgents() → Map<name, {path, content, origin}>, both landed in tests/helpers.ts in Phase 0 beside requireDistFile (:29 [verified]). The mandatory assertion used by every consumer:

expect([...resolveAllAgents().keys()]).toEqual(expect.arrayContaining(getAllAgentNames()))

16 today, 16 after the P1 rename, 17 after 3a. Rationale to keep in the header (GAP-07): 15 of 16 agents survive scanned > 0 while coverage of git silently disappears.

extractOpSectionFromCorpus mode discipline [DR-18]. The Phase-0 helper's signature is extractOpSectionFromCorpus(corpus, op, { mode: 'union' | 'sole' }) with no default: 'sole' throws when the anchor matches in more than one corpus file (naming both paths); 'union' returns the concatenation with a match count. Every Phase-1 repoint that touches this helper must name the mode its consumer uses:

Consumer	Mode	Why
D11 forward guard (postingOps.length >= 8)	'union'	a posting op's D11 reference may live outside git.md; first-match would under-count and silently lower the effective floor without touching the literal 8 — the exact evasion §0.1-R2 and H3 exist to prevent
seam test **Input:** lookup	'sole'	must resolve to the single contract authority in git.md; unioning would let a key declared by only one source satisfy the forward check
Guard 2's four bound its	'sole' in Phase 1 (single corpus file)	they become 'union' consumers only when Phase 2 moves mechanics

In Phase 1 the corpus is still one file, so 'sole' and 'union' coincide — which is exactly why the mode must be written down now, while the choice is free, rather than discovered in Phase 2 when it is load-bearing.

The AC-1.8 printed-count spawnSync test (the flagged gap)

build a DEVFLOW_MDS_ROOT tree with a known host/partial population
  → spawnSync(TSX_BIN, [scripts/build-mds.ts], { env: { …, DEVFLOW_MDS_ROOT } })
  → expect(status).toBe(0)
  → parse `  {n} partial(s) skipped (no output-dir:)` and `  {m} host(s) to compile:` from stdout
  → expect(n).toBe(manifest.partials.length) and expect(m).toBe(manifest.hosts.length)

Non-vacuity: add a fixture host to the tree and assert the printed-count guard goes red. This is the only Phase-1 AC with no existing or repointed test behind it.

Goldens

tests/fixtures/golden/git-agent.md becomes live in Phase 1: expect(readFile('dist/agents/git.md')).toBe(loadGolden('git-agent.md')) — AC-1.1, this test is the review. loadGolden(name) mirrors requireDistFile's throw-with-a-command-hint, never-skip shape (tests/helpers.ts:25-38 [verified]). Comparison is a bare expect(actual).toBe(loadGolden(...)). Do not make it self-heal. The mismatch message uses the <<</>>> byte-boundary marker device. No snapshot API — toMatchSnapshot has 0 hits repo-wide; keep it that way; no __snapshots__ directory exists.

The golden is NOT regenerated in Phase 1 — a regeneration would defeat the entire phase. github-status-lines.txt stays frozen (AC-1.11).

Seam tests

No new seams. The Phase-0 seam test must stay green with git resolved from dist/agents — and needs zero edits, because the resolver landed in P0.

Edge-case tests

EC	Test	Fixture	Expected
EC-49	discovery manifest	discoverHosts() output	equals an explicit (file, role, outputDir) list, both directions
EC-50	IGNORE_DIRS += tests, coverage in the same PR that introduces the new .mds fixtures	a .mds with output-dir: under tests/fixtures/ in a DEVFLOW_MDS_ROOT tree	not discovered; the DEVFLOW_MDS_ROOT escape hatch (build-mds.ts:34) kept
EC-51 / AC-1.7	dest allowlist replaces raw equality, message preserved	output-dir: dist/wrong-dir, dist/../.., dist/commands/; name-template: ../x, a/b	exit 1 + /typo\?/i. mkdirSync(recursive) at :176 runs after the pin
EC-52 / AC-1.12	tarball entry count for src/assets/**/*.mds	npm pack --dry-run	pinned deliberately at N (D-A option (a)); Guard 5's reason string "skills, agents, rules, hook scripts" updated
AC-1.4	loadShippedDefaults() ⊇ getAllAgentNames(); ['git'] === 'haiku'	dist merged over src	every agent has an entry; mdEntryName stays .md-only
AC-1.10	grep AC	repo-wide	src/assets/agents/git.md appears only at documented src-fallback sites
GAP-57	Node-22-only assumption recorded	docs/reference/platform-assumptions.md	row present

Byte identity

bytes(dist/agents/git.md) === 59376 at the Phase-1 end state, asserted as a named constant with its derivation in a comment, alongside the golden equality. [verified: wc -c src/assets/agents/git.md → 59376] This is the strongest possible statement of "provably byte-identical" for one line.

Non-vacuity register

Guard	Non-vacuity	Known-bad
every new build branch	spawnSync status assertion (status === 1), never a source-level unit assertion	the four negative frontmatter values
dist↔src Guard-4-equivalent	both directions counted, > 0 each	dist/agents/orphan.md with no source
name manifests	manifest length floors asserted (>= 13, >= 11)	manifest with an entry removed ⇒ red
loadShippedDefaults	registry completeness, not scanned > 0	drop git from the merge ⇒ red
printed counts (AC-1.8)	parse stdout, compare against the manifest	add a fixture host ⇒ red
escaped-brace guard on dist/agents	grep -c '\\{' == 0	seed one unescaped \{ ⇒ red

Test-inventory table — the PR body carries one row per guard: guard name · file:line it lands in · the known-bad sample it must fail on · the commit in which it was proven red. A guard with no recorded red proof is not a deliverable. (process-only — PR checklist)

---

9. Patterns to Follow

Pattern	Precedent (file:line)	What to copy
Pure-module header	src/core/agent-frontmatter.ts:1-16 [verified]	"Pure module — zero I/O. All functions take content strings and return new content strings; callers own file reads and writes. applies ADR-013 … avoids PF-014: no process.exit(); all fallible paths return Result." Restate this shape verbatim at the top of src/core/mds-variants.ts
Per-module local Result	src/core/agent-frontmatter.ts:19 [verified: // Result type (local; matches codebase per-module pattern)]	Duplicate the Result type locally. Do not import a shared one — the duplication is deliberate policy
Path containment	src/core/paths.ts:20-26 isContainedIn [verified: relative()-based, pure, rejects '', .., absolutes]	Call it from resolveOutputDir instead of re-deriving startsWith(outAbs + path.sep) the way build-mds.ts:160 hand-rolls today
Charset regex	src/core/agent-frontmatter.ts:42 MODEL_NAME_RE	validateOutputName's ^[a-z0-9][a-z0-9._-]{0,63}$ is structurally the same anchored, bounded, no-alternation shape
Generator host shape	mds-proto/agents/git_p.mds:1-12 [drift: prototype tree, not committed — the shape is reproduced verbatim in §7 P1-S4, which is the load-bearing part]	Two frontmatter blocks: block 1 output-dir: (stripped whole), block 2 the agent's real name/description/model/skills (becomes body, blank line preserved)
Bidirectional registry	src/core/compliance-compose.ts:20 / :36 / :50 [verified]	"every token here must exist in the template; every template token must be listed here" — the exact model for P1-S12's name manifests, with the enforcement test named in the JSDoc
Fail-loud dist access	tests/helpers.ts:14-23 requireDistFiles() / :29-37 requireDistFile() [verified]	Throw with a build hint; never return or skip. "A guard that silently skips on a missing build artifact is not a guard."
Build-branch subprocess test	tests/build-mds.test.ts:495-531 [verified]	The full mkdtemp → spawnSync(..., { env: { …, DEVFLOW_MDS_ROOT } }) → status/message assertions → finally { rm } shape
Anchor extraction that throws	tests/helpers.ts:49-56 extractSection [verified: throws on a missing anchor]	Never the return '' variant, which is a vacuity hole

Anti-patterns named explicitly: scanned > 0 over the agent corpus (GAP-07 / B-11 — two such assertions already exist and stay green at 15) · tests/packaging.test.ts:121-137 Guard 4's catch { return } + if (distFiles.length === 0) return · toMatchSnapshot (0 hits repo-wide; keep it 0) · a self-healing golden · adding a YAML parser to the build (§C.6 forbids it — readFrontmatterKey stays a scalar regex).

---

10. Integration Points

Surface	Anchor	Phase-1 change
Installer agent loop	src/targets/claude-code/installer.ts:498-524 [verified]	dist-preferred → src-fallback → throw with the npm run build:mds hint appended to the existing Agent source not found for declared agent "…" text (:519-521 [verified])
Model pipeline	src/core/agent-models.ts:469-504 [verified] loadShippedDefaults	reads compiledAgentsDir() merged over agentsDir(), dist wins; mdEntryName stays .md-only
Asset paths	src/core/assets.ts:41-43 [verified]

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