issue-265: fix docs stage resume detection for no-op runs #266

david · 2026-08-18T06:00:11Z

david commented

2026-08-18 06:00:11 +00:00

What & why

determineResumeStageWithGit required both a Pi-Loop-Stage: 4 git commit and a valid docs.diff artifact to treat the docs stage as complete on resume. A no-op docs run (nothing to sync — the diff already matched the docs) never creates that commit, only writes an empty docs.diff. This caused resume to fall through to remediate (the last stage with a commit) and needlessly re-run the already-completed docs stage — costing an extra LLM round-trip on every resume after a no-op docs stage (e.g. when the mr stage failed transiently right after).

docs.diff is written unconditionally (even empty) as the stage's documented resume marker (ADR-015 §9) — the resume algorithm just wasn't trusting it on its own for docs. This PR makes it do so: a valid docs.diff artifact alone is now sufficient completion evidence for docs, without also requiring a commit. The reset SHA falls back to the remediate stage's commit, since a no-op docs stage leaves the working tree unchanged from that point.

Per-file breakdown

Modified:

src/run/services/determineResumeStage.ts — core fix: when walking stages in reverse to find the last completed one, a valid docs.diff without a matching commit is now treated as docs completion (falling back to the remediate commit for the reset SHA), instead of falling through further back in history.
src/run/services/determineResumeStage.test.ts — updated the existing no-op-docs test to assert the new (fixed) mr resume target; added a new test covering the double-no-op case (both remediate and docs made no commit).
src/orchestrator/services/runPipeline.ts — updated a stale comment describing the old "harmless re-run" behavior.
src/orchestrator/services/runPipeline.resume.e2e.test.ts — updated the gated e2e assertions (PILOOP_E2E=1) to expect resume-to-mr regardless of whether the docs stage committed.
docs/adr/015-documentation-sync-stage.md — updated §9 (Resume integration) to describe the new resume contract.
IMPLEMENTATION_PLAN.md — updated the resume-integration bullet to match.

Verification

npm test — 1976/1976 passing
npm run lint — clean
npm run build — clean

Closes #265

## What & why `determineResumeStageWithGit` required *both* a `Pi-Loop-Stage: 4` git commit *and* a valid `docs.diff` artifact to treat the `docs` stage as complete on resume. A no-op docs run (nothing to sync — the diff already matched the docs) never creates that commit, only writes an empty `docs.diff`. This caused resume to fall through to `remediate` (the last stage with a commit) and needlessly re-run the already-completed docs stage — costing an extra LLM round-trip on every resume after a no-op docs stage (e.g. when the `mr` stage failed transiently right after). `docs.diff` is written unconditionally (even empty) as the stage's *documented* resume marker (ADR-015 §9) — the resume algorithm just wasn't trusting it on its own for `docs`. This PR makes it do so: a valid `docs.diff` artifact alone is now sufficient completion evidence for `docs`, without also requiring a commit. The reset SHA falls back to the `remediate` stage's commit, since a no-op docs stage leaves the working tree unchanged from that point. ## Per-file breakdown **Modified:** - `src/run/services/determineResumeStage.ts` — core fix: when walking stages in reverse to find the last completed one, a valid `docs.diff` without a matching commit is now treated as `docs` completion (falling back to the `remediate` commit for the reset SHA), instead of falling through further back in history. - `src/run/services/determineResumeStage.test.ts` — updated the existing no-op-docs test to assert the new (fixed) `mr` resume target; added a new test covering the double-no-op case (both `remediate` and `docs` made no commit). - `src/orchestrator/services/runPipeline.ts` — updated a stale comment describing the old "harmless re-run" behavior. - `src/orchestrator/services/runPipeline.resume.e2e.test.ts` — updated the gated e2e assertions (`PILOOP_E2E=1`) to expect resume-to-`mr` regardless of whether the docs stage committed. - `docs/adr/015-documentation-sync-stage.md` — updated §9 (Resume integration) to describe the new resume contract. - `IMPLEMENTATION_PLAN.md` — updated the resume-integration bullet to match. ## Verification - `npm test` — 1976/1976 passing - `npm run lint` — clean - `npm run build` — clean Closes #265

david added the

bug

resume

labels

2026-08-18 06:00:11 +00:00

david added 1 commit

2026-08-18 06:00:12 +00:00

issue-265: fix docs stage resume detection for no-op runs 2d54b16acf

determineResumeStageWithGit required both a Pi-Loop-Stage: 4 commit and a
valid docs.diff artifact to treat the docs stage as complete. A no-op docs
run (nothing to sync) never creates that commit, so resume fell through to
remediate and needlessly re-ran the completed docs stage.

A valid docs.diff artifact alone is now sufficient completion evidence for
docs, since it is written unconditionally (even empty) as the stage's
documented resume marker. The reset SHA falls back to the remediate
commit, since a no-op docs stage leaves the working tree unchanged.

david merged commit e055515753 into main

2026-08-18 06:00:36 +00:00

david deleted branch bug/issue-265/fix-docs-resume-no-op-detection

2026-08-18 06:00:36 +00:00

david referenced this pull request from a commit

2026-08-18 06:00:37 +00:00

issue-265: fix docs stage resume detection for no-op runs (#266)

Sign in to join this conversation.

No reviewers