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

[dean0x]

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.

Problem Being Solved

Phase 2 must split git.md into a contract layer plus generated per-provider references. The build could not own an agent file at all:

• no generator-host convention — every .mds host wrote to dist/commands/, and the strip logic assumed a single frontmatter block
• dest validation compared raw strings, so dist/skills/../commands resolved onto an allowlisted target and was accepted
• the emitted output filename was never validated before being joined onto the destination
• dist/agents was unknown to the installer and to the per-agent model pipeline, so a compiled agent had nowhere to land

This PR is the plumbing for that split, and nothing else. Phase 2 constructs are pinned absent (AC-1.2) so their arrival is a reviewed change rather than something that accreted here.

Key Changes

Core (S1)

• src/core/mds-variants.ts — new, pure, zero I/O, no process.exit: validateOutputName and resolveOutputDir. Deliberately no expandVariants (DR-16). Three refusal kinds, evaluated in order: escapes-root (resolved-path containment), non-canonical (dist/commands/, ./dist/agents, dist/skills/../commands), not-allowlisted (compared on resolved absolute paths, not raw strings).
• scripts/build-mds.ts is now a shell over it — it owns every message and every exit. The pre-existing — typo? template is byte-preserved with the allowlist rendered into its single expected slot, so every /typo\?/i matcher still hits.
• stripGeneratorFrontmatter (whole-block, for output-dir: dist/agents) lands alongside the retained key-only stripOutputDirKey (for dist/commands), so the 13 command outputs do not move a byte. Both strips run after compileFile: only a block at byte offset 0 is emitted verbatim, so block 2 survives as body text and its trailing blank line is preserved.
• IGNORE_DIRS += tests, coverage — the build's own test fixtures declare output-dir: and would otherwise be discovered by the whole-repo walk and compiled into the real dist/ (EC-50).
• compiledAgentsDir() in src/core/assets.ts; the installer and loadShippedDefaults() resolve agents dist-first with a src fallback and fail loudly naming both paths.

Conversion (S2)

• src/assets/agents/git.md → git.mds (recorded by git as R079; the 21% is escape backslashes). 171 { and 171 } outside column-0 fences escaped as \{ / \}; 141 inside fences left raw. cmp exited 0 on the first build.

Tests and packaging (S3, this subtask)

• Three corpus scans that had silently lost git are repointed and now name the expected roster instead of counting it.
• Count literals → tests/fixtures/mds-manifest.ts, one definition consumed by four assertion sites plus the printed-count test.
• The build's printed counts are asserted for the first time (AC-1.8) — grep 'partial(s) skipped' tests/ returned zero hits before this PR.
• tests/guards/dist-agents.test.ts — parity, escaped braces, no-.md-shadowing-an-.mds, resolver origins, and the AC-1.2 absence guard.
• @mdscript/mds devDependency pin guard (Guard 3 reads dependencies only).
• Tarball decision D-A(a) accepted: the .mds sources ship, and the count is now pinned deliberately at 25 rather than being an accident of a broad glob.

Breaking Changes

None user-visible. One contributor-visible change: npm run build:cli alone no longer produces installable agents. npm run build runs both steps and is unchanged. The packaging and pack-install guards fail loudly if the compiled agent is missing from the tarball.

Reviewer Focus Areas

1. The golden equality test IS the review. dist/agents/git.md must equal tests/fixtures/golden/git-agent.md byte-for-byte, and bytes === 66180. A mismatch means the source is wrong, never the fixture (H2). The golden was never regenerated: git diff main -- tests/fixtures/golden/ is empty.

2. The 10 indented fences. All are inside numbered lists; de-indenting would not be byte-preserving, so every one is treated as prose and has its braces escaped. Line numbers are in git.mds (+3 vs the old git.md). Start with fences 3 and 4 — post-review-summary FULL and STUB — which carry the D7 dedup marker:

   #	open → close	opener	owning operation
   3	L394 → L402	5-space ```	post-review-summary (FULL)
   4	L404 → L414	5-space ```	post-review-summary (STUB)
   1	L222 → L224	3-space ```bash	setup-task
   2	L320 → L326	3-space ```	fetch-issues-batch
   5	L600 → L617	3-space ```markdown	learn-conventions
   6	L772 → L778	5-space ```	post-resolution-summary
   7	L781 → L791	5-space ```	post-resolution-summary
   8	L869 → L872	3-space ```	backlink-shipped-issues
   9	L904 → L908	5-space ```markdown	ensure-traceable-issue
   10	L951 → L954	3-space ```markdown	post-wave-report

   The exact string cycle:{CYCLE_NUMBER} ts:{REVIEW_TIMESTAMP} occurs 3× in dist/agents/git.md and 3× in the golden. The degenerate cycle: ts: that a lost interpolation would produce occurs 0×.

3. grep -c -F '\{' dist/agents/git.md = 0 (grep exits 1, no match). -F is required: in BRE, \{ is an interval operator. Proven non-vacuous against a seeded file first, which returned 2.

4. The 13 command SHA-256s are unchanged from the pre-S1 recording, verified after a full rm -rf dist && npm run build.

   AC-1.5 evidence — shasum -a 256 dist/commands/*.md, before vs after

   Before is the pre-S1 recording, taken from the tree at main before the first commit of this branch. After is the current build of this branch. diff of the two lists is empty — all 14 lines (13 compiled + the hand-authored release.md) are byte-identical, so no compiled command output moved.

   12769f62287032f62398f5255d9925df7bf77fbd41d49926153cf81d83a017b1  dist/commands/bug-analysis.md
   ba20df110bfc818ec43e738e92ad7317c21961b08c23f47bc267b4c8781f207b  dist/commands/code-review.md
   a1c108e214abeafe1af59090a93d8af2c7cab6c61a96cdeb8b780a6b715a2a89  dist/commands/debug.md
   e4c7cb75a44b1b314b5a654a2344d0faa975d2801b6ac6c88e5b43ab912a6ab7  dist/commands/dynamic-build.md
   26fd83241eab77221b0517e022fc25267979ea645f8504eafc25a491cfd037dd  dist/commands/dynamic-plan.md
   2d5f649b4d7d382937c65afc26b18ceff4bd2fa2439ba026f1320564bdbe7d50  dist/commands/dynamic-profile.md
   d0b533422614c0c130a5a721d6bffe766a5456952b8d8ccd8bc740bc8cf5f345  dist/commands/dynamic-tickets.md
   28c90a06468a008d9b7f8b0b3729f62dfaadb61c61ebcc2190c860eab3d1562a  dist/commands/explore.md
   3b9d4db64b6242a223ebd9afbc92cc3a344df85c36756d8447a05fd87692a0fb  dist/commands/implement.md
   cf85c1f4ce4405af75c1ca3eef232a4c04ccfd9755ce565120673714d7c32bac  dist/commands/plan.md
   1eefa92b7027205bd5b46eb3a5e9cda93af1465c01233ce906d9a77ee20c0bc3  dist/commands/release.md
   771792d722a1931cbc1aaff074ea134d800d5c95910848a4f3139107b96a14f4  dist/commands/research.md
   c6e3aa6de707d9ed0f1a24dacc4e7acf82bc168ebe487bda783763e8b4a89476  dist/commands/resolve.md
   36df553aa2c5fbd48b577888e518124a546f8fabf4fa3867b0698e485a9deeda  dist/commands/self-review.md
   

   release.md is in the list because it is a deployed command file, but it is hand-authored and copied verbatim — only the other 13 are MDS-compiled outputs. The equality is also pinned in CI, not only here: tests/build-mds-generator-hosts.test.ts:367 builds a copy of the committed tree under a temp DEVFLOW_MDS_ROOT and compares the result to the on-disk dist/, proving dist/commands/ is byte-idempotent without re-running the real build.

5. Tarball decision and Guard 5's reason string. src/assets/ already shipped wholesale, so the 24 command-side .mds files were already inside every published tarball; git.mds joins them. No files[] change. The count is now pinned at 25 and Guard 5's reason string names the generator sources.

6. The AC-1.8 printed-count test. discoverHosts() cannot be imported (build-mds.ts is a tsx script outside tsc), so the printed output is the seam — which is also the seam a human reads. parsePrintedCounts() throws on a missing line rather than parsing it as 0.

Test inventory

Every guard, its known-bad sample, and the commit at which it was proven red. Each file:line points at the owning describe/it at this branch's head — the section markers the table previously carried are superseded by the line numbers.

Guard	File	Known-bad sample	Proven red at
validateOutputName charset/bounds	tests/mds-variants.test.ts:80	charset widened to /^[A-Za-z0-9][A-Za-z0-9._\/-]*$/ → 2 red	pre-b5272d1
validateOutputName traversal/separator kinds	tests/mds-variants.test.ts:101	module absent → suite red	pre-b5272d1
resolveOutputDir two-entry allowlist	tests/mds-variants.test.ts:160	allowlist shrunk to ['dist/commands'] → 3 red	pre-b5272d1
resolveOutputDir canonical-declaration rule	tests/mds-variants.test.ts:190	canonical check deleted → 3 red	pre-b5272d1
Result error-union completeness	tests/mds-variants.test.ts:292	phantom-kind injected into the expected set	b5272d1 (in-test probe)
generator whole-block strip	tests/build-mds-generator-hosts.test.ts:227	key-only-strip result ---\n---\n… asserted not.toBe	pre-a2ed82f (12 red)
13 command outputs keep key-only strip	tests/build-mds-generator-hosts.test.ts:327	real implement.md with the whole-block strip applied fails the same collector	a2ed82f (in-test probe)
dist/commands rebuild byte-idempotence	tests/build-mds-generator-hosts.test.ts:367	paired with the recorded pre-S1 SHAs	a2ed82f
dest allowlist negatives (3)	tests/build-mds-generator-hosts.test.ts:415	dist/wrong-dir, dist/commands/, dist/../..	pre-a2ed82f
filename negatives (2)	tests/build-mds-generator-hosts.test.ts:551	output-name: ../x, output-name: a/b	pre-a2ed82f
IGNORE_DIRS covers tests/ and coverage/	tests/build-mds-generator-hosts.test.ts:606	same fixture outside an ignored dir IS compiled	pre-a2ed82f
compiledAgentsDir() shape	tests/core-paths-assets.test.ts:91	accessor absent → 3 red	pre-ef0b30f
installer dist-preferred order	tests/installer-new.test.ts:718	src-first order installs the src file	pre-ef0b30f
installer loud failure on both-absent	tests/installer-new.test.ts:443	both dirs empty; asserts build:mds + both paths in message	pre-ef0b30f
loadShippedDefaults ⊇ registry	tests/agent-models.test.ts:1072	registry-completeness, never scanned > 0	ef0b30f
loadShippedDefaults compiled-over-source	tests/agent-models.test.ts:1094	dropping the dist dir loses git; reversed order flips the winner	pre-ef0b30f
git.md ≡ golden, byte-for-byte	tests/goldens/git-agent-golden.test.ts:34	cmp is the oracle; grep known-positive returned 2 on a seeded file	e768675
agent-corpus completeness (3 sites)	tests/build.test.ts:177, tests/registry-integrity.test.ts:134, tests/core-paths-assets.test.ts:75	the pre-repoint .md-only filter, run over the same input, loses git	f218c00 (mechanic 1 recorded in the commit body + in-test probes)
recursive partial collector + no-subdirectories	tests/build-mds.test.ts:179	temp dir with nested/_buried.mds and a subdirectory	8b99dc1 (in-test probe)
printed host/partial counts (AC-1.8)	tests/build-mds-generator-hosts.test.ts:679	a DEVFLOW_MDS_ROOT copy of the real tree, seeded with one extra host → 15 ≠ 14	8b99dc1 (in-test probe)
dist/agents ↔ src parity, both directions	tests/guards/dist-agents.test.ts:96	temp tree with dist/agents/orphan.md and an uncompiled uncompiled.mds; absent dist/agents/ throws	cc95210 (in-test probes)
no escaped braces in dist/agents/*.md	tests/guards/dist-agents.test.ts:175	seeded cycle:\{CYCLE_NUMBER\}; clean {CYCLE_NUMBER} must NOT be flagged	cc95210 (in-test probe)
no .md shadowing an .mds host	tests/guards/dist-agents.test.ts:293	temp dir holding both x.md and x.mds	cc95210 (in-test probe)
resolver origins (dist arm, src arm, loud-failure arm)	tests/guards/dist-agents.test.ts:322	unbuilt temp tree with only the .mds → throws with a build hint	cc95210 (in-test probe)
AC-1.2 Phase-2 constructs absent	tests/guards/dist-agents.test.ts:424	each of the 8 tokens seeded; plus a scoping probe showing @import in a .ts is not flagged	cc95210 (in-test probes)
AC-1.1 byte baseline + origin === 'dist'	tests/goldens/git-agent-golden.test.ts:71	equality baseline, moves only with the fixture	cc95210
@mdscript/mds exact devDep pin	tests/packaging.test.ts:140 (Guard 3b)	^0.2.0, ~0.2.0, undefined fed to the same collector; exact spelling must still pass	cf09961 (in-test probe)
tarball carries dist/agents/git.md	tests/packaging.test.ts:470 (Guard 6)	dist/agents/git.md moved aside → expected [] to deeply equal [ 'dist/agents/git.md' ]	cf09961 (mechanic 1, recorded in the commit body)
tarball ships 25 .mds sources (D-A(a))	tests/packaging.test.ts:504 (Guard 6)	count derived from the manifest; measured 25	cf09961
installed agent came from dist/agents/	tests/integration/clause-ii-file-residue.test.ts:304	byte-compares the file devflow init wrote against the tarball's compiled artifact	cf09961
retired wording: no generated copies anywhere	tests/guards/retired-wording.test.ts:212	guard run against the pre-sweep CLAUDE.md → red naming the file and the literal	596233d (mechanic 1, recorded in the commit body)
requireBuiltCli fail-loud build gate	tests/guards/literal-agent-paths.test.ts:194	temp root with no dist/	03ef52d

Prefix-shippability

$ npm run build
EXIT=0

$ npm test
 Test Files  117 passed (117)
      Tests  4216 passed (4216)
EXIT=0

$ npm run test:integration
 Test Files  5 passed (5)
      Tests  50 passed (50)
EXIT=0

$ npm pack --dry-run
package size: 989.2 kB
unpacked size: 3.2 MB
total files: 377
EXIT=0

$ git status --porcelain
(empty)

$ git diff main -- tests/fixtures/golden/
(empty)

$ grep -c -F '\{' dist/agents/git.md
0                     (grep exit 1 — no match)

$ shasum -a 256 dist/agents/git.md tests/fixtures/golden/git-agent.md
84078f9c443ab036fc885670e15982c63d5fd0339de90cd1500e14a07f0e0a53  dist/agents/git.md
84078f9c443ab036fc885670e15982c63d5fd0339de90cd1500e14a07f0e0a53  tests/fixtures/golden/git-agent.md

$ stat -f %z dist/agents/git.md
66180

$ npm run build:mds | grep -E 'partial|host'
  11 partial(s) skipped (no output-dir:)
  14 host(s) to compile:

live: loadShippedDefaults keys: 16 | registry: 16
      superset (loadShippedDefaults ⊇ getAllAgentNames): true
      defaults['git'] = haiku

resolveAgentSource('git').origin === 'dist' is asserted in tests/goldens/git-agent-golden.test.ts and, for every generator host, in tests/guards/dist-agents.test.ts.

Process-only checklist:

• 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 — none for Phase 1
• clause (ii) — waived per Pluggable issue tracker (GitHub + Jira + Linear) — tracking #321 "Clause (ii) waiver" section: one live walk-through runs after Phase 3 merges

Deviations

• S1 — dist/../.. is caught by the retained escape guard and reports escapes the repo root, not — typo?. The two messages are distinct by design: an escaping path throws and fails the build, a mis-spelled one exits 1 with the typo hint. The AC-1.7 pinning test is amended accordingly: /typo\?/i binds to the two allowlist rejections only (dist/wrong-dir, dist/commands/); the other three negatives pin their own messages — dist/../.. pins escapes the repo root, and the two output-name negatives (../x, a/b) pin is not a valid output filename. A later phase should not re-derive /typo\?/i as the contract for all five.
• S1 — output-name: is read and validated but no shipped host declares it. Its consumer is real (it determines the emitted filename when present) and the AC-1.7 negatives require the key to be read, but in Phase 1's end state it is exercised only by tests. This is the one place the phase sits closest to the clause-(iii) line, flagged rather than buried. Commit e054f04 renamed the key from its earlier templating spelling; that earlier spelling is deliberately unclaimed and reserved for Phase 2 (scripts/build-mds.ts:5-13).
• S2 — five test sites were repointed through resolveAgentSource in the conversion commit itself, purely to keep that commit green (R6); all five are listed in its commit body.
• S3 — numeric-floors.json: dist-host-count and partial-count are re-registered at the same floors (13, 11) with the new spelling toBeGreaterThanOrEqual(N), because the assertions that carried them became set-equalities and the floor moved onto the manifest's length. No floor lowered, no entry removed. dist-files-count is untouched — toBe(14) still occurs 3× in build-mds.test.ts.
• S3 — SKILL_GIT_CHARS moves 9_204 → 9_205. Fixing src/assets/skills/git/SKILL.md's cross-reference to a deleted file costs exactly one character. It is an equality baseline, not a floor, and it moves in the same commit as the file it measures.
• S3 — the AC-1.9 "installed agent came from dist" proof lives in clause-ii-file-residue.test.ts, not pack-install.test.ts. pack-install never runs devflow init and has no scratch HOME, so it can only prove the tarball carries the artifact; the init-running test is where the installed file can be compared.
• S3 — tests/goldens/git-agent-golden.test.ts was dropped from the literal-agent-paths exclusion list. Its description named a deleted path; rewriting it removed the last literal, so the exclusion entry and its justification paragraph went with it rather than being left as residue (ADR-003).
• S3 — the retired-wording corpus widened to dist/agents/, docs/ and the root prose so the new Phase-1 entry has something to scan. .devflow/features/*/KNOWLEDGE.md is deliberately excluded: those files record what each literal was and why it was retired, and a residue grep must not demand deleting provenance (PF-040).
• S3 — the skipIf→fail-loud migration touched three Phase-0-era files (cli-unknown-command, init-e2e-flags, integration/clause-ii-file-residue) plus compliance-e2e, and on review also init-review-publication (last hand-rolled dist/cli.js consumer) and one stale tombstone in registry-integrity; an unbuilt local tree now reports a collection error naming npm run build instead of SKIP marks (CI unaffected: build precedes test). Commits 03ef52d, a98af63, 7912ffb, dd7b53a.

Related Issues

Closes #323

Tracking issue #321. Depends on #322 (merged via #327).

[dean0x]

Code Review — Cycle 1

Full summary withheld (public repository).

Category	CRITICAL	HIGH	MEDIUM	LOW	Total
Blocking	1	6	7	-	14
Should Fix	-	3	15	1	19
Pre-existing	-	-	2	2	4

Full report: /Users/dean/Sandbox/devflow/.devflow/docs/reviews/feat-323-tracker-phase-1-mds-plumbing-provably-by/2026-09-09_2237/review-summary.md (not committed; ask the author)
Posted by devflow · cycle 1

[dean0x]

Resolution Summary

Full summary withheld (public repository).

Metric	Value
Total Issues	94
Fixed	48
False Positive	2
By Design	9
Deferred	4
Blocked	0
Escalated	0
Duplicates Collapsed	31

Full report: /Users/dean/Sandbox/devflow/.devflow/docs/reviews/feat-323-tracker-phase-1-mds-plumbing-provably-by/2026-09-09_2237/resolution-summary.md (not committed; ask the author)
Posted by devflow