feat(FAFF-402): build-complete checkpoint + push-at-build-complete resumability#287
Merged
Merged
Conversation
…sumability Makes graft's build stage deterministically resumable so a review-provider outage never costs a rebuild (unblocks FAFF-403). - New `faff build-progress` governance command (bin/faff): a per-issue diff-hash-keyed checkpoint at <run-dir>/<issue>/build-progress.json, mirroring review-progress (pure immutable fold + atomic tmp+rename, read-exit-3, mandatory --selftest). Registered in REGION_MAP/REGION_SELFTEST_ARGV/COMMANDS + --help + docs/guide/cli.md. - graft SKILL.md: new Step 8b (push branch at build-complete → write the checkpoint, gated on graft.push_at_build_complete, default on); Step 9b narrowed to gh pr create when the branch is already pushed; Step 3 resume-at-review (recreate the worktree graft-direct from origin/<branch>, skip the build, re-run gates+AC, enter at review). - CI is PR-gated (on: pull_request + push:[main]), so the early no-PR branch push fires zero CI. merge-gate stays blind to build-progress (a resume artifact). Tests: 9 new in test/build-progress.test.mjs (selftest, round-trip, read-exit-3, missing-flag exit-2s, re-write). Governance region selftest + lint-cli-doc pass.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes FAFF-402. Keystone of the "build-ahead, resume the review→ship tail later" posture; unblocks FAFF-403.
What
Makes graft's build stage deterministically resumable so a review-provider outage (or a turn boundary) never costs a rebuild. Built work becomes durable on
originat build-complete, and the worktree becomes a disposable cache.How
faff build-progressgovernance command — a per-issue diff-hash-keyed checkpoint at<run-dir>/<issue>/build-progress.json, mirroringfaff review-progressbyte-for-byte (pure immutable fold + atomic tmp+rename,read→exit-3-absent/exit-0-JSON, mandatory--selftest). Wired intoREGION_MAP/REGION_SELFTEST_ARGV/COMMANDS/--help/docs/guide/cli.md.graft.push_at_build_complete(default on). The diff-hash is the remote three-dotgit diff origin/main...origin/<branch>computed in graft prose (the CLI stays pure — no git/network).gh pr createwhen the branch is already pushed (CI still fires exactly once at PR-open; a no-PR branch push triggers nothing — CI ison: pull_request+push:[main]).git worktree add <path> <branch>, no-b), skip the build, re-run gates+AC, enter at review. Hint-not-authoritative: any mismatch rebuilds.faff merge-gateis unchanged — build-progress is a resume artifact, never a merge-floor assertion.Acceptance Criteria
faff build-progressis a governance command (REGION_MAP / REGION_SELFTEST_ARGV / COMMANDS / --help / cli.md)Verified:
faff regions selftest --region governance→ build-progress PASS;faff lint-cli-doc→ 50 subcommands documentedread→exit-3-absent / exit-0-JSON;write --build-complete --diff-hash H --branch B→ schema, atomic; missing hash/branch → exit 2Verified:
test/build-progress.test.mjs9/9 passingbuild-progress --selftestpure fold table (no I/O) passesVerified:
faff build-progress --selftest→ PASS (0 failed)graft.push_at_build_complete; Step 9b split; Step 3 resume graft-direct; merge-gate blind to build-progressVerified: senior-engineer review
passagainst the graft SKILL.md prose +cmdMergeGate(reads only ac-checklist + review-verdict)Prose scenario (born-verifiable), no unit test — inherent to the purity boundary: the git hash is graft-prose, the CLI is deliberately pure. Fail-safe by construction (mismatch → rebuild).
Full
node --test: 1178 pass / 3 fail (pre-existing sandbox — docker-gated holdout, eval-model spawn — none in files this diff touches).