Domdhi logoDOMDHI.OS
BACK_TO_COURSE

The Software Factory — Proof Before Commit

Proof at Commit: the Ship-Check Seal

Seal the Evidence, Then Commit Against It

After the last review fix, ship-check.js seal records exactly what was proven: the HEAD, the gate receipt, a hash of the code, a hash of the verify: records and freeze baselines, the TODO and the stories. It runs the bindings and the tamper check itself; it never trusts records already on disk.

node .claude/core/ship-check.js seal --todo docs/work/todo/TODO_feature.md --stories "A.1,A.2"
node .claude/core/commit.js --ship-check --sc-kind wave --sc-plan docs/.output/plans/{stamp}-run-todo-feature.md --sc-wave 1 \
  --sc-todo docs/work/todo/TODO_feature.md --sc-stories "A.1,A.2"

commit.js --ship-check verifies the seal before anything is staged. A pass adds a Ship-Check: <12 hex> trailer to the commit; any refusal exits 1 and changes nothing.

What Each Refusal Means

Rule Meaning Fix
no-seal / bad-seal No seal, or a malformed one Seal
head-mismatch HEAD moved since the seal Re-gate and re-seal
code-drift Code changed after the seal Re-gate and re-seal; list docs that change later with --docs
receipt Gate receipt missing, invalid or not the sealed one Run gate.js test, then seal
unstaged-code The index differs from the sealed working tree git add the final content
ac-check A frozen test or verify: line changed — an earlier story's baseline included Restore it, or re-freeze with --reason
stories-mismatch The seal and the commit name different stories Re-seal with the commit's --stories
todo-mismatch The seal was made for a different TODO Use that TODO, or re-seal
records-drift Records or baselines changed after the seal Re-seal
completion An acceptance criterion or story marker is still unchecked Finish it
review A wave commit has no filled Review — Wave N entry Write the review log entry

The Audited Skip

When verification genuinely cannot run (a docs-only change, no gate configured), --sc-skip "<reason>" bypasses the seal checks and leaves a Ship-Check-Skip: trailer. The completion check still runs whenever a TODO is named, and a wave commit still needs its review entry. The skip is an audit record, not a shortcut.

TIP

Every refusal points at evidence that went stale. The fix is always to regenerate the evidence (gate, run, seal), never to edit the seal, the records or the binding until the numbers line up.

QUIZ

You seal a wave, then fix a typo in a source file and try to commit. What does commit.js --ship-check do?

Sign in to track lesson progress and earn a certificate.SIGN IN TO SAVE PROGRESS