Skip to content

feat(FAFF-402): build-complete checkpoint + push-at-build-complete resumability#287

Merged
alechill merged 2 commits into
mainfrom
faff-402-build-complete-checkpoint
Jul 7, 2026
Merged

feat(FAFF-402): build-complete checkpoint + push-at-build-complete resumability#287
alechill merged 2 commits into
mainfrom
faff-402-build-complete-checkpoint

Conversation

@alechill

@alechill alechill commented Jul 7, 2026

Copy link
Copy Markdown
Contributor

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 origin at build-complete, and the worktree becomes a disposable cache.

How

  • New faff build-progress governance command — a per-issue diff-hash-keyed checkpoint at <run-dir>/<issue>/build-progress.json, mirroring faff review-progress byte-for-byte (pure immutable fold + atomic tmp+rename, read→exit-3-absent/exit-0-JSON, mandatory --selftest). Wired into REGION_MAP / REGION_SELFTEST_ARGV / COMMANDS / --help / docs/guide/cli.md.
  • graft Step 8b (both modes) — push the branch at build-complete → write the checkpoint (push first, so a checkpoint always implies a durable branch). Gated on graft.push_at_build_complete (default on). The diff-hash is the remote three-dot git diff origin/main...origin/<branch> computed in graft prose (the CLI stays pure — no git/network).
  • graft Step 9b narrowed to gh pr create when the branch is already pushed (CI still fires exactly once at PR-open; a no-PR branch push triggers nothing — CI is on: pull_request + push:[main]).
  • graft Step 3 resume-at-review (autonomous L3/L4) — read the checkpoint, recompute the remote hash; on match recreate the worktree graft-direct (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-gate is unchanged — build-progress is a resume artifact, never a merge-floor assertion.

Acceptance Criteria

  • faff build-progress is 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 documented
  • read→exit-3-absent / exit-0-JSON; write --build-complete --diff-hash H --branch B → schema, atomic; missing hash/branch → exit 2
    Verified: test/build-progress.test.mjs 9/9 passing
  • build-progress --selftest pure fold table (no I/O) passes
    Verified: faff build-progress --selftest → PASS (0 failed)
  • graft Step 8b pushes then checkpoints (both modes), gated on graft.push_at_build_complete; Step 9b split; Step 3 resume graft-direct; merge-gate blind to build-progress
    Verified: senior-engineer review pass against the graft SKILL.md prose + cmdMergeGate (reads only ac-checklist + review-verdict)
  • Hash reproducibility (8b hash == remote-three-dot at resume)
    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).

alechill added 2 commits July 7, 2026 15:11
…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.
@alechill alechill merged commit dc2d402 into main Jul 7, 2026
2 checks passed
@alechill alechill deleted the faff-402-build-complete-checkpoint branch July 7, 2026 15:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant