Docs stage re-runs unnecessarily on resume after a no-op run #265

New issue

david · 2026-08-18T05:59:10Z

david commented

2026-08-18 05:59:10 +00:00

Summary

When the docs stage completes as a no-op (nothing to sync — the diff already matches the docs), it writes an empty docs.diff but creates no Pi-Loop-Stage: 4 commit. On resume, determineResumeStageWithGit required both a commit and a valid artifact to treat docs as complete, so it fell through to remediate (the last stage with a commit) and re-ran the already-completed docs stage.

Observed in practice: remediate completes → docs runs and correctly says "No updates needed" → mr fails with a transient fetch failed. On resume, docs runs again (wasted ~31s + one LLM call) before mr fails again.

Root cause

docs.diff is written unconditionally (even empty) as the stage's documented resume marker (ADR-015 §9), but the resume algorithm didn't trust that marker on its own for docs — it also required a commit, which a no-op docs run never produces.

Fix

determineResumeStageWithGit now treats a valid docs.diff artifact alone as sufficient completion evidence for the docs stage, without requiring a Pi-Loop-Stage: 4 commit. The reset SHA falls back to the remediate stage's commit, since a no-op docs stage leaves the working tree unchanged.

Scope

src/run/services/determineResumeStage.ts — core fix
src/run/services/determineResumeStage.test.ts — updated + new unit tests
src/orchestrator/services/runPipeline.ts — stale comment update
src/orchestrator/services/runPipeline.resume.e2e.test.ts — updated gated e2e assertions
docs/adr/015-documentation-sync-stage.md §9 — updated resume contract description
IMPLEMENTATION_PLAN.md — updated resume-integration bullet

Verified: npm test (1976/1976 passing), npm run lint (clean), npm run build (clean).

## Summary When the docs stage completes as a no-op (nothing to sync — the diff already matches the docs), it writes an empty `docs.diff` but creates **no** `Pi-Loop-Stage: 4` commit. On resume, `determineResumeStageWithGit` required *both* a commit and a valid artifact to treat `docs` as complete, so it fell through to `remediate` (the last stage with a commit) and re-ran the already-completed docs stage. Observed in practice: `remediate` completes → `docs` runs and correctly says "No updates needed" → `mr` fails with a transient `fetch failed`. On resume, `docs` runs again (wasted ~31s + one LLM call) before `mr` fails again. ## Root cause `docs.diff` is written unconditionally (even empty) as the stage's documented resume marker (ADR-015 §9), but the resume algorithm didn't trust that marker on its own for `docs` — it also required a commit, which a no-op docs run never produces. ## Fix `determineResumeStageWithGit` now treats a valid `docs.diff` artifact alone as sufficient completion evidence for the `docs` stage, without requiring a `Pi-Loop-Stage: 4` commit. The reset SHA falls back to the `remediate` stage's commit, since a no-op docs stage leaves the working tree unchanged. ## Scope - `src/run/services/determineResumeStage.ts` — core fix - `src/run/services/determineResumeStage.test.ts` — updated + new unit tests - `src/orchestrator/services/runPipeline.ts` — stale comment update - `src/orchestrator/services/runPipeline.resume.e2e.test.ts` — updated gated e2e assertions - `docs/adr/015-documentation-sync-stage.md` §9 — updated resume contract description - `IMPLEMENTATION_PLAN.md` — updated resume-integration bullet Verified: `npm test` (1976/1976 passing), `npm run lint` (clean), `npm run build` (clean).

david added the

bug

resume

labels

2026-08-18 05:59:10 +00:00

david referenced this issue from a pull request that will close it,

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

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

david closed this issue

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

david referenced this issue

2026-08-18 06:31:01 +00:00