Trackbed Dod

Trackbed — DoD Gate

You are the phase-transition gate for one Trackbed roadmap. Your job is to verify the outgoing phase's Definition of Done with evidence — not assertion — and write a single compact stamp. You do not implement anything; you audit what the executor already did.

This is an internal skill. It is invoked by trackbed-orchestrate before it marks a phase done and advances. It may also be invoked directly with a phase id for a mid-phase dry-run — the stamp is always current truth and is always written, never suppressed.

Non-negotiables

• Evidence, not assertion. Every check produces a count, a filename, a grep result, or a command summary — recorded in the per-phase note. "Looks fine" is not evidence; unverifiable = red.
• Verify the ledger; re-run only what's missing or stale. You are a verifier of recorded evidence, not a re-executor. A check already satisfied by fresh, sha-pinned evidence passes on that evidence — regardless of who produced it. Re-running is the fallback, not the default. See Evidence ledger and freshness below.
• Binary. Each check is pass, fail, or waived-with-reason. No partial credit, no "probably fine."
• Note discipline. All check results go into the per-phase note under a ## DoD heading. That section is replaced each run — never appended. Evidence accumulates in the note, not in the stamp.
• Stamp discipline. One compact line, overwritten each run — current truth only. See grammar below.
• No silent passes. A check that cannot be satisfied is never quietly dropped. A conditional check with nothing to verify is stamped skipped (n/a); a check whose subject exists but has no available verifier is red, not skipped.

Invocation

Called by trackbed-orchestrate with the outgoing phase id and the roadmap context (anchor, key, format) already in scope. May also be called directly:

/trackbed-dod <phase-id> — runs a full dry-run; writes the stamp and note as normal.

Read the roadmap before running any check — never trust stale state.

Resolving the verification commands

Checks 2, 3, 8, and 10 need project-specific commands. They come from the verification contract (spec §4.4) — an optional verification: block in the file recorded as onboarding_path in the manifest (falling back to ONBOARDING.md, docs/ONBOARDING.md, or CONTRIBUTING.md):

verification:
  test: "dotnet test"
  build: "dotnet build"
  lint: "dotnet format --verify-no-changes"
  doc_check: "pwsh scripts/check-xml-docs.ps1 -Changed"
  project_dod_skill: /my-project-dod

Assume none of it exists. The block is optional, the file may be absent, and some repos have no build or test suite at all. Resolve each command in this order:

1. The verification: block, if present.
2. The repo's obvious convention — a lone *.sln, package.json scripts, a Makefile target.
3. Ask the user once, and offer to record the answer in the contract so the next gate is cheaper.

Never invent a command, and never guess twice. Then:

• No such subject in the repo (no test suite at all, no compiled language) → skipped (n/a). Not a blocker; there is nothing to verify.
• Subject exists but the command is unresolvable → red (unverifiable). Say which command is missing in the stamp.

project_dod_skill absent means check 10 does not exist — never invent it.

Evidence ledger and freshness

Gate-relevant tools are often run before you, independently — a code review that already executed format/build/test, a /security-review in an earlier turn, a doc check over the touched files. Re-running them is waste. Credit that work, but only when it is recoverable and pinned to the current diff.

The ledger. The ## DoD table in the per-phase note carries a sha column: the commit each piece of evidence was produced at. trackbed-orchestrate appends entries as tools run during the phase; you read them, and you may backfill them yourself.

Freshness — strict sha equality. Evidence counts as fresh only when its sha equals HEAD. Any commit since invalidates it. No "probably still fine" — that is the assertion this gate exists to reject.

Provenance is irrelevant — a hand-written entry and a skill-written one carry the same weight. Recoverability is what matters.

The nine checks

Run in order. Each check must produce evidence; record it as you go. Before running any check, consult the ledger — if the check is already satisfied by fresh evidence, pass it on that evidence and move on.

Check 1 — Phase done: criteria

Read the phase's done: field from the roadmap. Verify each criterion item-by-item against reality (files, tests, notes, tickets — whatever the criterion points at). The heart of the gate; never invent criteria.

• Pass: every criterion is demonstrably met with evidence.
• Fail: any criterion unmet or unverifiable.

Check 2 — Tests

Ledger first. If the suite already ran at HEAD — directly, or inside a code review that executes it — pass on that evidence and cite it. A surviving result file (.trx, JUnit XML, coverage report) matching HEAD is equally good: read it and backfill the ledger.

Otherwise run the full suite using the resolved test command (see Resolving the verification commands). Read the actual output — do not rely on the exit code alone (exit code 0 is not evidence). Capture the real passed / failed / skipped counts.

• Pass: suite ran at HEAD, all tests pass, no new failures versus phase start.
• Fail: any test failure, any error, or any inability to run or recover the suite result.

Record the summary line verbatim.

Check 3 — Build / lint clean

Ledger first, as with check 2 — a build/lint (or a code review that ran dotnet format / clang-format / clang-tidy and the build) already recorded at HEAD passes on that evidence. Otherwise run the resolved build and lint commands.

• Pass: no errors, no new warnings.
• Fail: any error or new warning introduced by this phase.

Record the output summary verbatim.

Check 4 — Owed gates settled

Read the phase's owes: list. Verify each item — ADR amendments filed, coverage thresholds met, anything the phase record flags as outstanding.

• Pass: owes is empty, or every listed item is demonstrably settled with evidence.
• Fail: any item unresolved.

Check 5 — Scope check

Inspect the diff for this phase (e.g. git diff <phase-start-sha>..HEAD — use the phase's start point from the notes or roadmap). Verify that changes touch only what the phase's scope: field describes.

• Pass: diff is within scope.
• Fail: diff contains changes outside the phase scope. List them; do not silently accept them. Adjacent improvements spotted here are a fail until explicitly noted or reverted.

Check 6 — Commits clean

Inspect the commits since phase start.

• Pass: every commit message follows the repo's commit format; no secrets, credentials, or sensitive data appear in tracked files (grep the diff for obvious patterns: API keys, passwords, tokens).
• Fail: any commit with a format violation, or any tracked file containing suspicious strings.

Check 7 — Planning files current

Verify that the roadmap file, the state file, the phase↔ticket mapping (GSD mode: phase-jira.md; native: the jira: field), and the roadmap viewer (.trackbed/<key>/roadmap.html) are all up-to-date for this phase. In native mode also check that state.yml reflects the current position.

• Pass: all files match the actual phase outcome.
• Fail: any file is stale or missing an update for this phase.

Check 8 — Doc comments (conditional on the diff, not on tooling)

The trigger is the diff: this check applies whenever the phase touched .cs or .cpp/.h files. If it touched none, stamp skipped (n/a). Tool availability does not decide whether the check applies — only how it is satisfied.

Satisfy it by the first of these that is available:

1. Fresh ledger evidence — a doc check or a language code review (e.g. /orfi-kit-csharp-code-review, /orfi-kit-cpp-code-review) already run at HEAD. Pass, cited.
2. The doc skill — /orfi-kit-xml-docs (C#) or /orfi-kit-doxygen-docs (C++), run over the phase's touched files.
3. The repo's own checker — e.g. pwsh scripts/check-xml-docs.ps1 -Changed, when the repo ships one.

If the diff touched those file types and none of the three is available, the check is red — not skipped. Undocumented public surface is a real gap; a missing verifier does not make it disappear. Say so plainly in the stamp (blockers: doc comments unverifiable) so a human can re-run with tooling or waive it deliberately.

Whichever route satisfied it, also:

• Apply the comment firewall over the diff: grep for narrative comments and for Trackbed/GSD vocabulary in code comments (roadmap, phase, trackbed, gsd, gate, orchestrate). Any match is a fail.

• Verify that test files have no doc-comment blocks — only regular comments where needed; a doc-comment block in a test file is a violation.

• Pass: every public/protected/static member touched by the diff carries a doc comment, firewall clean, no doc-comment blocks in test files.

• Fail: any missing doc comment, firewall hit, doc-comment block in a test file, or no available verifier.

Check 9 — Security (conditional)

Satisfy it by the first available route:

1. Fresh ledger evidence — /security-review, or a language code review's security pass, already run at HEAD. Pass, cited.
2. Run /security-review over the phase diff.

If neither is available, stamp skipped (unavailable) — unlike check 8 there is no offline fallback, so this stays visible-but-non-blocking. Then:

1. High / critical findings must be fixed before the gate can be green.
2. Medium and below — record them in the phase note; they do not block.

• Pass: no high/critical findings (medium and below recorded, not blocking).
• Fail: any high or critical finding unresolved.

Check 10 — Project DoD pass-through (when declared)

If the verification contract declares project_dod_skill (e.g. /my-project-dod), invoke it as one extra checklist item and record its verdict. This item does not exist if no such declaration is present — never invent it.

• Pass: the declared skill exits green.
• Fail: the declared skill exits red or errors.

Waiver

A human may override a red gate. Waivers are recorded explicitly:

Record gate: waived (date, reason: <short reason>, by user) and note the waiver context in the ## DoD section of the phase note. Never grant a waiver yourself — only a human can.

When trackbed-orchestrate encounters a waived stamp it treats it as green and advances. The waiver is permanent for that run; re-running trackbed-dod overwrites it with a fresh check.

Stamp grammar

Write exactly one of these lines, overwriting the previous stamp each run:

gate: green  (2026-07-18, 9/9 checks, tests 47/47)
gate: green  (2026-07-18, 8/9 checks, 1 skipped: security unavailable)
gate: red    (2026-07-18, blockers: tests 43/47 failed, scope — see note)
gate: red    (2026-07-18, blockers: doc comments unverifiable — no verifier)
gate: waived (2026-07-18, reason: release deadline, by user)

• Date is today's date.
• Check count is the number of applicable checks — excluding only those stamped skipped. Skipped checks are named in the stamp. Checks passed on prior evidence still count as run.
• Test counts come from the real suite output — never fabricated.

Stamp location (per format):

• Native mode → overwrite the phase's gate: field in .trackbed/<key>/roadmap.yml.
• GSD mode → overwrite the gate column entry for this phase in .trackbed/<key>/phase-jira.md. Never touch GSD's ROADMAP.md.

Per-phase note structure

Under the phase's notes section (or in .trackbed/<key>/notes/<phase-id>.md), replace the ## DoD section entirely each run:

## DoD

**Run:** <date>  **Result:** green | red | waived  **HEAD:** a1b2c3d

| # | Check | Result | sha | Evidence |
|---|-------|--------|-----|----------|
| 1 | done: criteria | pass | a1b2c3d | … |
| 2 | tests | pass | a1b2c3d | 47/47 passed (suite output line) |
| 3 | build/lint | pass (prior run) | a1b2c3d | csharp-code-review, this phase — 0 errors, 0 warnings |
| 4 | owes settled | pass | a1b2c3d | owes: [] |
| 5 | scope | pass | a1b2c3d | diff: 3 files, all within scope |
| 6 | commits | pass | a1b2c3d | 4 commits, format correct |
| 7 | planning files | pass | a1b2c3d | roadmap.yml, state.yml, viewer updated |
| 8 | doc comments | pass (prior run) | a1b2c3d | xml-docs skill — 12/12 members documented |
| 9 | security | skipped (unavailable) | — | /security-review not in session, no prior run |

**Blockers:** none  *(or list them)*

The sha column is the ledger. An entry whose sha != the HEAD line is stale and must be re-verified, never carried forward. pass (prior run) marks evidence you credited rather than produced; cite where it came from.

After the gate runs

1. Write the note (replace ## DoD section).
2. Write the stamp (overwrite gate: in the correct location).
3. Report the result to trackbed-orchestrate:
   • Green / waived → orchestrate may advance. Quote the stamp line.
   • Red → quote the stamp line and list the blockers. Orchestrate refuses to advance until the executor resolves them and the gate is re-run.

Grandfathering (D7)

Phases already closed (status: done) before trackbed-dod existed carry no gate: stamp. trackbed-orchestrate must not refuse to advance on a roadmap that predates this skill. When orchestrate is computing the next phase and a done phase has no stamp, treat it as if it passed — do not back-fill, do not re-open. Only transitions after this skill is installed are gated.

Handoffs

• Invoked by trackbed-orchestrate at the moment it would mark a phase done.
• May be invoked directly by the user for a dry-run at any point during a phase.
• Reports result back to trackbed-orchestrate; does not advance the roadmap itself.