issue-311: Doc updates and validation for the no-code-change comment feature #318

david · 2026-09-05T20:20:12Z

david commented

2026-09-05 20:20:12 +00:00

311: Doc updates and validation for the no-code-change comment feature

Closes #311 — 311.

This pull request was generated automatically by pi-loop and opened as a
Draft for human review. Do not merge without reviewing the changes.

Generated in 19m 15s.

Review findings

Now I'll apply the fixes. First, the README.md Medium finding (exit-code table row + new policy bullet):Now the two DESIGN.md Low findings (artifact-inventory table rows + hard-wrap the §3.4 paragraph):Now normalize README formatting (it is prettier-clean at baseline, so --write only touches my edited region) and inspect the diffs:Both docs fixes are in place. Now re-run the project gates (npm run build, npm run lint, npm test per package.json):All gates pass. Let me verify the working tree contains only the intended doc changes:# Review Findings — 311

Summary

All three findings were resolved in this pass. Medium: README.md's "Exit codes & error handling" section now covers the no-code-change comment path — the exit-0 row names no-code-change success and a new Fatal no-code-change comment policy bullet documents the sole-deliverable/fatal-on-post-failure exception (stage write-back, exit 1, resumable, ADR-021 §5). Low: DESIGN.md §3.4's no-code-change-comment.json paragraph is hard-wrapped to the surrounding prose width (bold markers intact), and the §3.3 artifact-inventory table gained no-code-change-comment.json plus the two sibling completion artifacts (no-code-change.json, mr-skipped.json) for a complete inventory. Gates re-run after the fixes: npm run build ✅ PASS, npm run lint ✅ PASS, npm test ✅ PASS (148 files / 2128 tests). No findings remain.

Critical

High

Medium

README.md:453 — The operator-facing "Exit codes & error handling" section was not updated for the no-code-change comment path: its policy bullets still present write-back as unconditionally non-fatal and the exit-0 row (README.md:436) says success always means "a Draft MR was created". The new AGENTS.md:251 row documents a fatal exception (comment post failure → error.json attributed to write-back, non-zero exit, resumable) that README's policy enumeration now omits — an obvious enumeration gap in an in-scope doc (the AGENTS.md docs-stage default scope includes README.md). Suggested fix: add a bullet under "Exit codes & error handling" stating that on the no-code-change short-circuit the deterministic comment is the sole deliverable and a post failure is fatal (stage write-back, exit 1), and amend the exit-0 wording to cover no-code-change success.

Low

DESIGN.md:334 — The marker description is a single ~400-character un-wrapped paragraph while surrounding §3.4 prose is wrapped at ~80–100 columns, which makes the addition hard to review and diff. Suggested fix: hard-wrap the paragraph to match the surrounding prose width (keep the bold **only after**/**before** emphasis intact).
DESIGN.md:136 — The §3.3 artifact-inventory table (the doc's "Artifacts (the contract between stages)" quick-glance list) does not list no-code-change-comment.json even though the same change documents it in §3.4 (line 333); no-code-change.json and mr-skipped.json are likewise absent (pre-existing drift). Suggested fix: add a no-code-change-comment.json row (produced by: no-code-change short-circuit / write-back; consumed by: resume/skip detection) and optionally backfill the two sibling artifacts for a complete inventory.

## 311: Doc updates and validation for the no-code-change comment feature Closes #311 — [311](https://git.excelera.net/david/pi-loop/issues/311). > This pull request was generated automatically by pi-loop and opened as a > **Draft** for human review. Do not merge without reviewing the changes. Generated in 19m 15s. ## Review findings Now I'll apply the fixes. First, the README.md Medium finding (exit-code table row + new policy bullet):Now the two DESIGN.md Low findings (artifact-inventory table rows + hard-wrap the §3.4 paragraph):Now normalize README formatting (it is prettier-clean at baseline, so `--write` only touches my edited region) and inspect the diffs:Both docs fixes are in place. Now re-run the project gates (`npm run build`, `npm run lint`, `npm test` per package.json):All gates pass. Let me verify the working tree contains only the intended doc changes:# Review Findings — 311 ## Summary All three findings were resolved in this pass. Medium: README.md's "Exit codes & error handling" section now covers the no-code-change comment path — the exit-`0` row names no-code-change success and a new **Fatal no-code-change comment** policy bullet documents the sole-deliverable/fatal-on-post-failure exception (stage `write-back`, exit `1`, resumable, ADR-021 §5). Low: DESIGN.md §3.4's `no-code-change-comment.json` paragraph is hard-wrapped to the surrounding prose width (bold markers intact), and the §3.3 artifact-inventory table gained `no-code-change-comment.json` plus the two sibling completion artifacts (`no-code-change.json`, `mr-skipped.json`) for a complete inventory. Gates re-run after the fixes: `npm run build` ✅ PASS, `npm run lint` ✅ PASS, `npm test` ✅ PASS (148 files / 2128 tests). No findings remain. ## Critical ## High ## Medium - [x] README.md:453 — The operator-facing "Exit codes & error handling" section was not updated for the no-code-change comment path: its policy bullets still present write-back as unconditionally non-fatal and the exit-`0` row (README.md:436) says success always means "a Draft MR was created". The new AGENTS.md:251 row documents a fatal exception (comment post failure → `error.json` attributed to `write-back`, non-zero exit, resumable) that README's policy enumeration now omits — an obvious enumeration gap in an in-scope doc (the AGENTS.md docs-stage default scope includes `README.md`). Suggested fix: add a bullet under "Exit codes & error handling" stating that on the no-code-change short-circuit the deterministic comment is the sole deliverable and a post failure is fatal (stage `write-back`, exit 1), and amend the exit-`0` wording to cover no-code-change success. ## Low - [x] DESIGN.md:334 — The marker description is a single ~400-character un-wrapped paragraph while surrounding §3.4 prose is wrapped at ~80–100 columns, which makes the addition hard to review and diff. Suggested fix: hard-wrap the paragraph to match the surrounding prose width (keep the bold `**only after**`/`**before**` emphasis intact). - [x] DESIGN.md:136 — The §3.3 artifact-inventory table (the doc's "Artifacts (the contract between stages)" quick-glance list) does not list `no-code-change-comment.json` even though the same change documents it in §3.4 (line 333); `no-code-change.json` and `mr-skipped.json` are likewise absent (pre-existing drift). Suggested fix: add a `no-code-change-comment.json` row (produced by: no-code-change short-circuit / write-back; consumed by: resume/skip detection) and optionally backfill the two sibling artifacts for a complete inventory.

david added 2 commits

2026-09-05 20:20:12 +00:00

311: Doc updates and validation for the no-code-change comment feature 993d6cd0a7