Make the implement Phase 4.1 documentation gate record only run-specific workpad facts

[The01Geek]

Problem Statement

As the PRFlow maintainer, I want the /prflow:implement Phase 4.1 documentation gate to record only real, run-specific facts on the workpad, so that workpads stop carrying a scripted boilerplate note and never tick a documentation-coupled acceptance criterion on evidence that does not yet exist.

Two things go wrong at the same gate today. First, every implement run writes the same fixed sentence to the workpad, and that sentence is false: it says the gate cannot see a warning that the gate can in fact see. Second, when a deferred acceptance criterion asks for a check to be run, the gate lets the run tick it while pointing at a later step as proof, before that later step has happened. Both fixes live in the same phase file.

Current Behavior

Triggering steps: run /prflow:implement on any issue whose acceptance criteria include a documentation-owned criterion that names a check command, and read the issue workpad after Phase 4.1. Observed on issue #2123 (cloud implement tier, workpad comment https://github.com/The01Geek/prflow/issues/2123#issuecomment-5458815030).

Observed result:

• At 00:13:14 the workpad gained the fixed note "Phase 4.1: extractor span-suppression breadcrumbs are not durably observable on the cloud tier (stderr not captured); a suppressed command/grant literal in the Documentation Needed block leaves no run-record trace". The same sentence is scripted into the phase file, so every run writes it, including a run in which no span was suppressed.
• At 00:15:32 the workpad ticked AC8 ("lib/test/lint-internal-docs.py reports no new violation") with a note saying the docs subagent reported 0 new violations and that this was "re-confirmed over the final committed tree by the Phase 4.3 whole-suite pass". The Phase 4.3 pass ran at 00:38:26, 23 minutes later. No command output for the lint appears anywhere on the workpad.

Expected result: a workpad note about a suppressed span appears only in a run where the extractor actually suppressed one, and names that span; a deferred criterion that names a check command is ticked only after that command has run in the same run over the landed docs, with the command's result quoted in the tick note and no reference to a step that has not run yet.

Environment: the cloud implement tier (GitHub Actions). The prose that causes both behaviors is tier-independent, so the local tier behaves the same way.

Desired Behavior

The helper that reads the Documentation Needed block, scripts/read-doc-needed-deliverables.sh, prints one extra self-identifying stdout line, docgate-suppressed: <span>, when the extractor suppressed a span, carrying the first suppressed span's text with the breadcrumb's surrounding backticks removed. Phase 4.1 Stage 1 records a workpad note naming that span only when such a line is present, passing the text through a file rather than a shell argument, and the fixed once-per-run disclosure sentence is gone from the phase file.

A deferred documentation criterion that names a check command is ticked at Phase 4.1 only after the orchestrator has executed, in its own tool call over the landed docs, the command the criterion names — when the tier does not grant that command, the granted covering run that lib/test/modules/coverage-map.json names for it — and the tick note quotes the result line of the command actually run. A subagent's report that it ran the command does not discharge the criterion. A tick note names no result that has not been produced yet. When the tier refuses both forms, the criterion stays unticked and the run takes the paragraph's existing Blocked arm, with the reflection naming prflow_implement.allowed_tools as the remedy.

User Impact

The maintainer reading a workpad sees a suppressed-span note only when it carries a real fact, and sees a doc-criterion tick backed by evidence the run actually holds. The weekly retrospective's gate signals do not move, because they read workpad reflections, not notes.

Technical Context

Scope note: The files and details below are the known starting points, not the full list. Before implementing, trace the change through the codebase to find every affected call site, consumer, and layer — this issue maps the work, it does not bound it.

• Relevant Classes/Files — skills/implement/phases/phase-4-documentation.md (the disclosure paragraph near line 89 and the deferred doc-AC discharge paragraph near line 177); scripts/read-doc-needed-deliverables.sh (the read boundary whose stdout the gate parses); scripts/extract-doc-needed-paths.sh (the only writer of the breadcrumb); lib/test/run.sh (the extract-doc-needed-paths.sh: command and grant literals inside the Documentation Needed block are tokenized into phantom doc deliverables that Block implement runs #644 and Phase 4.1's Documentation-Needed read produces no observable value and its branch logic is untestable, because it is inline shell written twice #1554 pins); docs/internal/implement-skill.md (the owning page).
• Verified: skills/implement/phases/phase-4-documentation.md says the extractor emits a "breadcrumb on stderr this gate does not capture" and scripts the fixed --note text quoted above into Stage 1.
• Verified: scripts/read-doc-needed-deliverables.sh states the opposite in its header — the caller reads a "tool result that merges this command's stdout with the stderr of" the extractor — so the breadcrumb is visible to the agent in every run; it is only never recorded.
• Verified: scripts/extract-doc-needed-paths.sh prints "suppressed a span (a command/grant/skill literal, or a path mixed with non-path tokens" to stderr at most once per run, from suppress_span(), and exposes the span on no other channel.
• Verified: skills/implement/phases/phase-4-documentation.md discharges a deferred doc-AC on one piece of evidence — "confirm the docs the criterion required actually landed in this run's diff" — and says nothing about a criterion that names a check command.
• Verified: skills/implement/phases/phase-3-ac-gate.md defers only a documentation edit, one that "is left unticked at this gate, recorded in a workpad deferral note naming the AC"; on Grant three drift-detecting helpers to the cloud implement tier and mirror them into the matcher-probe EXTRAS list #2123 a check-command criterion was deferred anyway, so the Phase 4.1 paragraph must cope with that shape.
• Verified: lib/test/run.sh pins that "P4_FILE quotes the extractor's actual breadcrumb phrase" exactly once, and its Phase 4.1's Documentation-Needed read produces no observable value and its branch logic is untestable, because it is inline shell written twice #1554 fixture matrix asserts the exact stdout lines of the helper for an adversarial body.
• Verified: docs/internal/implement-skill.md repeats the false premise — the breadcrumb is "disclosed by Phase 4.1 as ephemeral on the cloud tier" — and must be corrected with the change.
• Verified: .prflow/prompt-extensions/implement.md requires a changeset for a "fix, feature, or breaking change to the engine surface", which includes skills/ and scripts/.
• scripts/workpad.py has no structure that ties an acceptance-criterion tick to a recorded command result: --tick-ac-n flips a row, --note appends text under a 2048-byte budget, and the completion-evidence flags cover the whole-suite gate only. The evidence therefore lives in the tick note's text.
• Architecture Alignment — the helper already owns the gate's stdout contract (self-identifying prefixes, never positions), so a third prefix is the same pattern; the phase file keeps routing on docgate-outcome: and reads the new line by prefix.
• Dependencies — none new. The helper and workpad.py are already invoked by Phase 4.1 on both tiers, so no cloud grant changes. The helper and the phase file reach a consumer in the same vendored plugin fetch, so an old helper beside a new phase file cannot occur; a consumer that has not upgraded keeps today's behavior.
• Data/Schema Considerations — none.
• Cross-layer Impact — one shipped helper, one shipped phase file, its test pins, one internal doc page, one changeset.

Acceptance Criteria

The helper's stdout lines are observed through the #1554 fixture matrix in lib/test/run.sh: rdnd_lines keeps the docgate- lines, and rdnd_run is the unfiltered capture with stderr merged.

• Running scripts/read-doc-needed-deliverables.sh on the Phase 4.1's Documentation-Needed read produces no observable value and its branch logic is untestable, because it is inline shell written twice #1554 adversarial fixture body (a command literal and a grant literal beside a real path) prints the existing docgate-outcome: deliverables and docgate-path: lines plus exactly one docgate-suppressed: line whose value is the first suppressed span's text with the breadcrumb's backticks removed.
• Running the same helper on each existing clean Phase 4.1's Documentation-Needed read produces no observable value and its branch logic is untestable, because it is inline shell written twice #1554 fixture body prints no docgate-suppressed: line, and its existing exact-line expectations pass unchanged.
• Running the helper on the Phase 4.1's Documentation-Needed read produces no observable value and its branch logic is untestable, because it is inline shell written twice #1554 adversarial fixture body through the unfiltered rdnd_run capture prints a line containing extract-doc-needed-paths.sh: suppressed a span, in addition to the docgate- lines the filtered expectation asserts.
• After the change the literal "not durably observable on the cloud tier" appears in no file under skills/.
• After the change the phase file skills/implement/phases/phase-4-documentation.md names the phrase suppressed a span exactly once, in the sentence that tells Stage 1 to record a workpad note naming the span only when a docgate-suppressed: line is present; that sentence delivers the span text to the workpad through a file — the span text is written with the Write tool to a .prflow/tmp/ file and recorded with workpad.py update … --note-file <that file> — and the span text never appears inside a double-quoted --note "…" shell argument (an unquoted or backticked span in a double-quoted shell argument could execute); the extract-doc-needed-paths.sh: command and grant literals inside the Documentation Needed block are tokenized into phantom doc deliverables that Block implement runs #644 pin in lib/test/run.sh passes unchanged.
• After the change the deferred doc-AC paragraph in skills/implement/phases/phase-4-documentation.md states that a deferred criterion naming a check command is ticked only after the orchestrator has run, in its own tool call after the docs commit, that command — when ungranted, the covering run lib/test/modules/coverage-map.json names for it — that a subagent's report that it ran the command does not discharge the criterion, that the tick note quotes the result line of the command actually run, that a tick note names no result of a gate that has not yet run, and that a tier refusal of both forms leaves the criterion unticked and takes the paragraph's existing Blocked arm with a reflection naming prflow_implement.allowed_tools as the remedy.
• After the change the heading sentence Discharge every 3.4-deferred documentation AC (mandatory, before §4.3) is present verbatim exactly once in the phase file, so the Wave 6A — producer/consumer gate fixes: recognize doc-ACs as Phase-4-owned in the 3.4 gate, and harden create-issue's mechanical-claim and Documentation Needed contracts #380 pin in lib/test/run.sh passes unchanged.
• lib/test/lint-reference-size.py reports no violation for skills/implement/phases/phase-4-documentation.md after the change.
• docs/internal/implement-skill.md no longer states that the gate does not capture the extractor's stderr, and states that the helper relays the first suppressed span as a docgate-suppressed: stdout line which Stage 1 records on the workpad.

Implementation Notes

• Approach — In scripts/read-doc-needed-deliverables.sh, redirect the extractor's stderr into a scratch file beside the existing body capture under .prflow/tmp, forward that file to the helper's own stderr unchanged, and when it holds the suppressed a span phrase print one docgate-suppressed: <span> line after the docgate-outcome: line, carrying the span text from the breadcrumb with its surrounding backticks stripped. Both the phrase test and the forwarding use bash builtins (case, while IFS= read -r, ${var#prefix}), because a value that decides an emitted line must not depend on a tool lib/preflight.sh does not guarantee. In the phase file, replace the disclosure paragraph with one sentence: when Stage 1's tool result holds a docgate-suppressed: line, write the text Phase 4.1: extractor suppressed a Documentation Needed span: <span> with the Write tool to .prflow/tmp/docgate-suppressed-note-$ISSUE_NUMBER.txt and record it with workpad.py update $ISSUE_NUMBER --note-file .prflow/tmp/docgate-suppressed-note-$ISSUE_NUMBER.txt, cut to fit the 2048-byte note budget; Stage 2 records nothing. Amend the deferred doc-AC paragraph with the check-command rule stated in Desired Behavior, keeping its heading sentence byte-identical. Update the Phase 4.1's Documentation-Needed read produces no observable value and its branch logic is untestable, because it is inline shell written twice #1554 adversarial exact-line expectation and the doc page. Add one .changeset/*.md file with bump: patch. Every edit to the phase file goes through the superpowers:writing-skills discipline, and the PR description carries the Writing-skills evidence: line.
• Relevant files — scripts/read-doc-needed-deliverables.sh (extractor invocation near line 120; stdout emitters near lines 127–135); skills/implement/phases/phase-4-documentation.md (the paragraph near line 89 and the paragraph near line 177); lib/test/run.sh (the Phase 4.1's Documentation-Needed read produces no observable value and its branch logic is untestable, because it is inline shell written twice #1554 adversarial expectation near line 11371; likely nothing else); docs/internal/implement-skill.md (the sentence near line 1776); .changeset/.
• Code Patterns — the helper's existing prefix contract and its # STDOUT SHAPE header table; the phase file's existing "read the token after that prefix" wording; the existing Blocked arm inside the deferred doc-AC paragraph, reused rather than duplicated.
• Testing Strategy — Shell boundary, driven by the existing Phase 4.1's Documentation-Needed read produces no observable value and its branch logic is untestable, because it is inline shell written twice #1554 fixture matrix in lib/test/run.sh (monolith shard). The one new case: the adversarial-body exact-line expectation gains the docgate-suppressed: line; it is RED against today's helper, which prints no such line, and GREEN after the change. A second new assertion reads rdnd_run (not rdnd_lines) on the adversarial body and checks the merged stream for suppressed a span; it is RED against a helper that captures the extractor's stderr without forwarding it. The clean fixtures already assert exact line sets, so absence of the new line needs no new assertion. The extractor's own stderr fixtures stay untouched. No prose-presence pin is added for the two amended paragraphs: the phase-file wording is agent-executed prose whose control is the review pass.
• Documentation Needed — docs/internal/implement-skill.md: correct the "ephemeral on the cloud tier" sentence and describe the new stdout line and the check-command tick rule.
• Potential Gotchas — At drafting time the phase file sits about 1,900 bytes under the reference-size ceiling that lib/test/lint-reference-size.py enforces, so the two paragraph edits must net out near zero. The span is third-party issue text and is never placed inside a double-quoted shell argument (a backticked span would be executed as a command), which is why the note goes through --note-file. The extract-doc-needed-paths.sh: command and grant literals inside the Documentation Needed block are tokenized into phantom doc deliverables that Block implement runs #644 pin counts suppressed a span in the phase file and fails on any count other than one. The Wave 6A — producer/consumer gate fixes: recognize doc-ACs as Phase-4-owned in the 3.4 gate, and harden create-issue's mechanical-claim and Documentation Needed contracts #380 pin asserts the discharge heading sentence uniquely. workpad.py refuses a note over 2048 bytes, so the span text in the note is cut, never the note dropped. The extractor is invoked twice on a retry, so the stderr scratch file is overwritten per attempt, never appended. Phase 3.4's deferral rule admits only documentation-edit criteria, yet Grant three drift-detecting helpers to the cloud implement tier and mirror them into the matcher-probe EXTRAS list #2123 deferred a check-command criterion; this issue leaves skills/implement/phases/phase-3-ac-gate.md unchanged and makes Phase 4.1 handle that shape. PR Grant three drift-detecting helpers to the cloud implement tier and mirror them into the matcher-probe EXTRAS list #2124 (issue Grant three drift-detecting helpers to the cloud implement tier and mirror them into the matcher-probe EXTRAS list #2123, open at drafting time) adds Bash(lib/test/lint-internal-docs.py:*) to prflow_implement.allowed_tools; that key is trigger-time-resolved from the default branch, so on a cloud run before Grant three drift-detecting helpers to the cloud implement tier and mirror them into the matcher-probe EXTRAS list #2124 merges a deferred criterion naming that command falls to the granted covering run (lib/test/run-shard.sh monolith exercises the lint inside lib/test/run.sh). Nothing in this issue's own acceptance criteria invokes that command.

Generated via /prflow:create-issue (v2.36.15, medium)

[The01Geek]

Investigation record (from the /​prflow:create-issue run)

Passed-over candidates

Considered-and-rejected: 2 heavier candidate(s) — helper-writes-workpad (F1 iii) and a workpad.py tick-evidence structure (F4 iii), both new infrastructure for facts a note already carries.

Criterion disposition record

(appended at Step 3)

• AC1 docgate-suppressed on adversarial body — add; origin: request named the guarantee; merge test: no existing criterion checked by the Phase 4.1's Documentation-Needed read produces no observable value and its branch logic is untestable, because it is inline shell written twice #1554 adversarial expectation.
• AC2 clean fixtures print no such line — add; origin: failure the change introduces (false positive); merge: different fixtures, different evidence.
• AC3 stderr passthrough unchanged — add; origin: failure the change introduces (capturing stderr could swallow it); merge: different channel.
• AC4 boilerplate literal absent from skills/ — add; origin: request (delete the disclosure sentence); merge: none checks absence.
• AC5 phrase once + extract-doc-needed-paths.sh: command and grant literals inside the Documentation Needed block are tokenized into phantom doc deliverables that Block implement runs #644 pin — add; origin: failure the change introduces (pin count); merge: none.
• AC6 check-command tick rule — add; origin: request (Problem 2).
• AC7 Wave 6A — producer/consumer gate fixes: recognize doc-ACs as Phase-4-owned in the 3.4 gate, and harden create-issue's mechanical-claim and Documentation Needed contracts #380 heading unchanged — add; origin: failure the change introduces (pin_unique).
• AC8 byte ceiling hold — add; origin: request (hold or reduce bytes).
• AC9 doc page corrected — add; origin: failure the change introduces (doc now contradicts helper twice).

Steelman record

pass 1

• claims/file-refs/ACs checked: 9 Verified claims, 8 file references, 9 ACs — all confirmed against the tree (each quote contiguous on one source line).
• revised: Approach reworded to the real scratch-file layout and builtin-only phrase test; Gotchas gained the retry-overwrite note; User Impact universal scoped to the reflections-vs-notes fact; Dependencies gained the install-channel clause.
• projection: 7 represented obligations, 0 non-obligations counted separately, 0 unmatched; pre-revision unmatched statements: none; projection disposition: represented.
• value-comparison type-semantics: no type-sensitive comparison in the draft (byte count via wc -c; line presence via exact-line fixture).
• unstated-mechanism-dependency hunt: 4 enumerated — helper scratch dir under .prflow/tmp (present, read at lines 95-105), bash case/read builtins (present by construction), workpad.py --note budget (present, 4333), Phase 4.1's Documentation-Needed read produces no observable value and its branch logic is untestable, because it is inline shell written twice #1554 rdnd_lines filter keeping docgate- lines (present, 11330); new producer docgate-suppressed: absent (producing surface read; repo-wide grep zero hits) — disposition in scope, named as new work in Desired Behavior/AC1.
• universal-quantifier sweep: every run writes it (grounded by Verified bullet 1); appears in no file under skills/ (pinned by AC grep); names no result not yet produced (rule text the change ships); exposes the span on no other channel (grounded by the peer read of the extractor: no flags/env). No ungrounded quantifier remains.
• request-origin sweep: every acceptance criterion and named Testing-Strategy assertion traces to the request or to a failure the change introduces (AC2/3/5/7/9 change-introduced; AC1/4/6/8 request).
• Step 3.6 dimension self-check: 1 finding (deployment-variance silence on install channel), 1 revision.
• evidence bundle coverage: 15 axes evidenced, 1 marked N/A, 0 unestablished.

Evidence bundle

Entry forms: Verified: (1–3 lines) | N/A — checked <how> | unestablished — <why>. Currency triggers: a clarification answer changing the mechanism space; an answer contradicting an entry; a mechanism class added after writing. Effective axis list at pass time: producers; consumers; execution environments; persistence; lifecycle/termination; migration/coexistence; coupled tests+docs; consumer axes: per-profile cloud allowlists, install-channel skew, workpad/retrospective lifecycle surfaces, run.sh pin corpus, grant-timing bootstrap, measurement-command naming; consumers-axis floor; closed-set complements.

• producers — Verified: extract-doc-needed-paths.sh 510–515 emits the breadcrumb on stderr once; read-doc-needed-deliverables.sh 120 DOC_NEEDED_PATHS="$("$EXTRACTOR" < "$BODY_FILE")" captures stdout only. Verified: phase-3-ac-gate.md:66 produces 3.4: doc-AC deferred to Phase 4.1: {AC text}.
• consumers — Verified: map part 2 (call-site reads performed: phase file 78/83/150, run.sh 11330, 37087; workpad.py 5803).
• execution environments — Verified: the helper is invoked identically on the local and cloud implement tiers (phase file 86/128) and is granted today (issue Phase 4.1's Documentation-Needed read produces no observable value and its branch logic is untestable, because it is inline shell written twice #1554), so no new command head. Cloud tier: the lint-internal-docs.py grant shipped by Grant three drift-detecting helpers to the cloud implement tier and mirror them into the matcher-probe EXTRAS list #2123 is trigger-time-resolved, post-merge-only.
• persistence — Verified: workpad note via workpad.py update --note (7659), _NOTE_BYTE_BUDGET = 2048 (4333).
• lifecycle/termination — Verified: phase file ~177 Blocked arm ("do not tick it and do not finalize Complete: take the existing Blocked path"), reused unchanged for a denied verification command.
• migration/coexistence — N/A — checked: no persisted format changes; a consumer whose vendored helper predates the change never prints the new line and the new prose then records nothing (no false note).
• coupled tests+docs — Verified: map part 4.
• per-profile cloud allowlists — Verified: no new command head; docgate-suppressed: is output, not a command.
• install-channel skew — Verified: skills/ and scripts/ both ship by the prflow_version vendor fetch (one artifact); install.sh copies workflows only (CLAUDE.md). No skew for this change.
• workpad/retrospective lifecycle — Verified: notes are not reflections; cheap-gate.jq reads reflections (CLAUDE.md). Removing the boilerplate note perturbs no gate signal.
• run.sh pin corpus — Verified: map part 4.
• grant-timing bootstrap — Verified: no AC obligates running lint-internal-docs.py in this PR's own run; the ACs are fixture-driven suite checks and prose facts.
• measurement-command naming — Verified: the byte AC names wc -c (bytes agree across GNU/BSD).
• closed-set complements — the helper's stdout prefix set becomes exactly {docgate-outcome, docgate-path, docgate-suppressed}; any other stdout line is already handled by the phase file's residual arm (a missing or second outcome line → Blocked) and is otherwise ignored, unchanged.
• consumers-axis floor — Verified: entries above rest on call-site reads, not a textual sweep.

[The01Geek]

/prflow:implement 2129

[github-actions]

PRFlow Workpad — Issue #2129

Status: 🎉 Complete
Branch: issue-2129-make-the-implement-phase-4-1-documentation-gate
Run: View run
PR: #2137
Last updated: 2026-08-29 06:07 UTC

Progress

• Setup — branch & workpad

  • prompt extension resolved: implement
  • 02:08:22 — /prflow:implement run started
  • 02:09:04 — Claude job setup complete; invoking agent
  • 02:12:05 — agent entered Phase 1 setup; workpad triage passed
  • 02:12:10 — agent initialized; Phase 1 workpad hydrated
  • 02:12:32 — Phase 1.3.5: early dependency preflight passed (PROCEED)
  • 02:12:56 — resume-precheck: both open-PR queries ran and returned none for this issue; workpad Branch line absent; no prior attempt to adopt
  • 02:14:50 — issue-claim audit (projection): Desired Behavior obligation is unmatched by the resolved acceptance criteria — reporting specification defect to orchestrator: "Phase 4.1 Stage 1 records a workpad note naming that span only when such a line is present, passing the text through a file rather than a shell argument" (the file-vs-shell-argument mechanism has no AC counterpart)
  • 02:14:50 — issue-claim audit (count): claimed 'about 1,900 bytes' headroom under the reference-size ceiling for phase-4-documentation.md, verified '1,920' bytes (61,750 - 59,830) at HEAD — matches
  • 02:14:50 — issue-claim audit (negative-scope): issue excluded 'cloud grant changes' (Dependencies: none new); trace confirms no impact — the change reuses already-granted helpers (workpad.py --note-file, read-doc-needed-deliverables.sh, Write to .prflow/tmp/**); no skills/*/SKILL.md is edited, only a phase reference file, so the mandatory workflow-impact check does not apply
  • 02:14:50 — issue-claim audit (policy): no policy-referencing AC claims found — pass complete
  • 02:14:50 — issue-claim audit (execution-capability): no workflow-resident acceptance criteria found — pass complete
  • 02:14:50 — issue-claim audit (verified-premise): re-checked 8 Verified: bullet(s) at HEAD — 8 hold, 0 unestablished; no premise refuted
  • 02:15:48 — Phase 1.6 issue-claim audit returned blocked-specification: an independently-verifiable Desired Behavior obligation has no matching acceptance criterion. Stopping before Phase 2 without synthesizing an AC.
  • 02:50:36 — trigger accepted; existing workpad adopted
  • 02:51:24 — Claude job setup complete; invoking agent
  • 02:54:17 — agent entered Phase 1 setup; workpad triage passed
  • 02:54:44 — /prflow:implement new run initialized from terminal workpad; Phase 1 workpad hydrated
  • 02:54:55 — resume-kind: terminal-re-trigger
  • 02:54:55 — classification: bug-report — workpad gains a fixed false note every run and a doc-AC is ticked on evidence not yet produced — a defect in existing gate behavior
  • 02:55:06 — Phase 1.3.5: early dependency preflight passed (PROCEED); Phase 4.1's Documentation-Needed read produces no observable value and its branch logic is untestable, because it is inline shell written twice #1554 reference is a test-fixture pin, not a sequencing dependency
  • 02:55:37 — resume-precheck: both open-PR queries ran and returned none for this issue; workpad Branch line issue-2129-make-the-implement-phase-4-1-documentation-gate; no prior attempt to adopt
  • 02:56:01 — branch-state: Verdict B classified branch issue-2129-make-the-implement-phase-4-1-documentation-gate as FRESH (ahead-of-base=0); proceeding
  • 02:56:23 — checkpoint 1: fast-forwarded to origin/main (ad6da89) and pushed (was behind by 3); tree now current with base
  • 02:57:23 — issue-claim audit (projection): every Desired Behavior obligation is represented in the resolved acceptance criteria — pass complete
  • 02:57:23 — issue-claim audit (count): claimed 'about 1,900 bytes under the ceiling', verified 1920 bytes headroom (59830 bytes vs 61750-byte ceiling) at HEAD
  • 02:57:23 — issue-claim audit (negative-scope): issue excluded 'no cloud grant changes' (Dependencies — none new); trace confirms no impact — workpad.py already supports --note-file and --tick-ac-n
  • 02:57:23 — issue-claim audit (policy): no policy-referencing AC claims found — pass complete
  • 02:57:23 — issue-claim audit (execution-capability): no workflow-resident acceptance criteria found — pass complete
  • 02:57:23 — issue-claim audit (verified-premise): re-checked 7 Verified: bullet(s) at HEAD — 7 hold, 0 unestablished; no premise refuted; no ungraded claims found

• Implement

  • reproduction captured (bug issues only)
  • code + sweeps
  • 03:00:51 — captured reproduction signal: extractor emits 'suppressed a span: bash lib/test/run.sh' on stderr but helper relays no docgate-suppressed line; phase file scripts the fixed false note
  • 03:14:52 — Writing-skills evidence: skills/implement/phases/phase-4-documentation.md mode=subagent skill-loaded=yes (dispatched general-purpose subagent loaded superpowers:writing-skills via the Skill tool; available-skills check reported it PRESENT) guidance-applied=yes (Match the Form to the Failure — both edits are conditional/recipe-shaped prose: the span note fires only on an observed docgate-suppressed line, and the check-command discharge names the exact tick precondition) pressure-scenario=no (a mechanical two-string edit to prose already pinned by lib/test/run.sh extract-doc-needed-paths.sh: command and grant literals inside the Documentation Needed block are tokenized into phantom doc deliverables that Block implement runs #644/Wave 6A — producer/consumer gate fixes: recognize doc-ACs as Phase-4-owned in the 3.4 gate, and harden create-issue's mechanical-claim and Documentation Needed contracts #380 and lint-reference-size.py, adding no rule to rationalize around, so there is no discipline-under-pressure failure for a scenario to elicit) micro-tests=no (behavior is shaped by run.sh pins and the reference-size ceiling, re-verified directly by grep counts and the reference-size lint rather than a no-guidance control)
  • 03:33:02 — Phase 2 §2.3 sweeps: changed-contract (helper stdout gained docgate-suppressed; consumers phase-4 doc + doc page + Phase 4.1's Documentation-Needed read produces no observable value and its branch logic is untestable, because it is inline shell written twice #1554 test all updated), boundary-assumption, self-authored-claim, coverage-claim all clear; stale-prose-lint clean over branch delta
  • 03:33:02 — focused selection: touched surfaces (read-doc-needed-deliverables.sh [unmodularized], phase-4-documentation.md, run.sh Phase 4.1's Documentation-Needed read produces no observable value and its branch logic is untestable, because it is inline shell written twice #1554/extract-doc-needed-paths.sh: command and grant literals inside the Documentation Needed block are tokenized into phantom doc deliverables that Block implement runs #644/Wave 6A — producer/consumer gate fixes: recognize doc-ACs as Phase-4-owned in the 3.4 gate, and harden create-issue's mechanical-claim and Documentation Needed contracts #380 pins, doc page) all run.sh-resident; mid-iteration covering run = lib/test/run-shard.sh monolith (10195 passed, 0 failed, 0 skipped after final edit)
  • 03:33:02 — batched-regeneration: run (coverage-map ratchet added run_sh_blocks '2129' entry via coverage_map_guard.py --fix; committed)

• Review

  • prompt extension resolved: review engine
  • prompt extension resolved: fix loop
  • prompt extension resolved: code-review reception
  • Classify diff (Phase 0.5)
  • Generate verification checklist (Phase 1)
  • Verify checklist (Phase 2)
  • Review agents (Phase 3)
  • Aggregate & verdict (Phase 4)
  • Run complete — everything this run owed
  • /simplify
  • review-and-fix
  • acceptance-criteria gate
  • 03:33:17 — entered Phase 3
  • 03:34:17 — Phase 3.1 checkpoint 2: merged origin/main (UPDATED 14) and pushed; resolve-existing-pr → CREATE
  • 03:36:21 — simplify outcome: findings generated=0, applied=0, skipped-as-AC-conflict=0 (4 cleanup agents — reuse/simplification/efficiency/altitude — all clean; code already at right altitude)
  • 03:36:50 — Phase 3.3: review-and-fix invoked in PR mode with draft PR Make the implement Phase 4.1 documentation gate record only run-specific workpad facts #2137 (bare leading token)
  • 03:36:50 — mid-phase resume point recorded
  • 04:06:35 — review coverage recorded (coverage=full, dispatch=attempted, roster=complete, checklist=complete; as of head a6ca918 at 20260829T040635Z)
  • 04:06:35 — review roster member code-reviewer=dispatched
  • 04:06:35 — review roster member comment-analyzer=dispatched
  • 04:06:35 — review roster member pr-test-analyzer=dispatched
  • 04:06:35 — review roster member requesting-code-review=dispatched
  • 04:06:35 — review roster member silent-failure-hunter=dispatched
  • 04:06:35 — review roster member type-design-analyzer=gated-off
  • 04:06:45 — review engine + fix-loop + code-review-reception extensions all resolved content-present via the load-prompt-extension.sh ladder (whole output observed); loop converged CLEAN-FULL — APPROVE, full-coverage shadow (5-agent roster), 1 Important test-gap fixed, 1 Important pushed back (deterministic extractor), advisories parked
  • 04:17:21 — verified (two-verifier reconciled satisfied); evidence and dispositions in this run's AC dispositions note

• Documentation

  • 04:20:33 — Phase 4.1: docs subagent updated docs/internal/implement-skill.md (added the check-command tick rule); deliverable present in diff; docs labels applied; no docgate-suppressed span in issue Documentation Needed block so no span note owed; no 3.4-deferred doc-ACs (all 9 ACs ticked in 3.4)
  • 04:22:31 — 4.2 claim audit (behavioral): docgate-suppressed relay claim traced to scripts/read-doc-needed-deliverables.sh — accurate, no correction
  • 04:22:31 — 4.2 claim audit (verification): Test Plan rows bind to the Phase 4.1's Documentation-Needed read produces no observable value and its branch logic is untestable, because it is inline shell written twice #1554/Make the implement Phase 4.1 documentation gate record only run-specific workpad facts #2129/extract-doc-needed-paths.sh: command and grant literals inside the Documentation Needed block are tokenized into phantom doc deliverables that Block implement runs #644/Wave 6A — producer/consumer gate fixes: recognize doc-ACs as Phase-4-owned in the 3.4 gate, and harden create-issue's mechanical-claim and Documentation Needed contracts #380 assertions in lib/test/run.sh; covering run lib/test/run-shard.sh monolith — accurate
  • 04:22:31 — 4.2 claim audit (artifact-existence): changeset .changeset/issue-2129-docgate-suppressed-span.md exists (bump: patch); no follow-up-issue claim — accurate
  • 04:22:31 — 4.2: PR body updated from placeholder (confirmed); no code-level fix made
  • 04:22:55 — checkpoint 4: observed token UP_TO_DATE — clean, proceeding to the publish decision
  • 04:43:17 — completion verification recorded (flight bbe9b04ec15c…, validated)

• PR marked ready

  • 04:43:48 — /prflow:implement run finished, PR published (gh pr ready): Make the implement Phase 4.1 documentation gate record only run-specific workpad facts #2137
  • 05:46:24 — Review reception for PR Make the implement Phase 4.1 documentation gate record only run-specific workpad facts #2137 (direct pass): focused-selection record.

Plan

• Relay the first suppressed span from scripts/read-doc-needed-deliverables.sh: capture the extractor's stderr to a scratch file, forward it unchanged, and print a docgate-suppressed: <span> line (backticks stripped) on success tokens
• Add the Phase 4.1's Documentation-Needed read produces no observable value and its branch logic is untestable, because it is inline shell written twice #1554/Make the implement Phase 4.1 documentation gate record only run-specific workpad facts #2129 fixture assertions in lib/test/run.sh (adversarial deliverables + merged-stream breadcrumb + no-deliverables emit site)
• Amend skills/implement/phases/phase-4-documentation.md: replace the fixed disclosure note with a conditional docgate-suppressed-driven --note-file note; add the check-command doc-AC discharge rule
• Correct docs/internal/implement-skill.md to describe the capture/forward/relay and the new stdout line
• Add a .changeset/*.md (bump: patch) for the engine-surface change
• Update lib/test/modules/coverage-map.json run_sh_blocks entry for the new Make the implement Phase 4.1 documentation gate record only run-specific workpad facts #2129 pins

Acceptance Criteria

• Running scripts/read-doc-needed-deliverables.sh on the Phase 4.1's Documentation-Needed read produces no observable value and its branch logic is untestable, because it is inline shell written twice #1554 adversarial fixture body (a command literal and a grant literal beside a real path) prints the existing docgate-outcome: deliverables and docgate-path: lines plus exactly one docgate-suppressed: line whose value is the first suppressed span's text with the breadcrumb's backticks removed.
• Running the same helper on each existing clean Phase 4.1's Documentation-Needed read produces no observable value and its branch logic is untestable, because it is inline shell written twice #1554 fixture body prints no docgate-suppressed: line, and its existing exact-line expectations pass unchanged.
• Running the helper on the Phase 4.1's Documentation-Needed read produces no observable value and its branch logic is untestable, because it is inline shell written twice #1554 adversarial fixture body through the unfiltered rdnd_run capture prints a line containing extract-doc-needed-paths.sh: suppressed a span, in addition to the docgate- lines the filtered expectation asserts.
• After the change the literal "not durably observable on the cloud tier" appears in no file under skills/.
• After the change the phase file skills/implement/phases/phase-4-documentation.md names the phrase suppressed a span exactly once, in the sentence that tells Stage 1 to record a workpad note naming the span only when a docgate-suppressed: line is present; that sentence delivers the span text to the workpad through a file — the span text is written with the Write tool to a .prflow/tmp/ file and recorded with workpad.py update … --note-file <that file> — and the span text never appears inside a double-quoted --note "…" shell argument (an unquoted or backticked span in a double-quoted shell argument could execute); the extract-doc-needed-paths.sh: command and grant literals inside the Documentation Needed block are tokenized into phantom doc deliverables that Block implement runs #644 pin in lib/test/run.sh passes unchanged.
• After the change the deferred doc-AC paragraph in skills/implement/phases/phase-4-documentation.md states that a deferred criterion naming a check command is ticked only after the orchestrator has run, in its own tool call after the docs commit, that command — when ungranted, the covering run lib/test/modules/coverage-map.json names for it — that a subagent's report that it ran the command does not discharge the criterion, that the tick note quotes the result line of the command actually run, that a tick note names no result of a gate that has not yet run, and that a tier refusal of both forms leaves the criterion unticked and takes the paragraph's existing Blocked arm with a reflection naming prflow_implement.allowed_tools as the remedy.
• After the change the heading sentence Discharge every 3.4-deferred documentation AC (mandatory, before §4.3) is present verbatim exactly once in the phase file, so the Wave 6A — producer/consumer gate fixes: recognize doc-ACs as Phase-4-owned in the 3.4 gate, and harden create-issue's mechanical-claim and Documentation Needed contracts #380 pin in lib/test/run.sh passes unchanged.
• lib/test/lint-reference-size.py reports no violation for skills/implement/phases/phase-4-documentation.md after the change.
• docs/internal/implement-skill.md no longer states that the gate does not capture the extractor's stderr, and states that the helper relays the first suppressed span as a docgate-suppressed: stdout line which Stage 1 records on the workpad.

Reproduction

Reproduction — issue #2129

Two defects at the Phase 4.1 documentation gate, both reproduced against the tree at HEAD.

Defect 1 — the suppressed-span breadcrumb is visible to the extractor but never relayed to the gate

The extractor writes a suppressed a span breadcrumb to stderr for an adversarial Documentation Needed block, naming the first suppressed span. Run on the #1554 adversarial body shape:

$ bash scripts/extract-doc-needed-paths.sh .prflow/tmp/repro-body-2129.md 2>&1
extract-doc-needed-paths.sh: suppressed a span (a command/grant/skill literal, or a path mixed with non-path tokens — not a set of bare-path deliverables, so no tokens emitted): `bash lib/test/run.sh`
docs/internal/implement-skill.md
rc=0

But the read boundary the gate parses, scripts/read-doc-needed-deliverables.sh, has no docgate-suppressed stdout line at all — it never carries the span to the workpad:

$ grep -c "docgate-suppressed" scripts/read-doc-needed-deliverables.sh
0

Defect 2 — the phase file scripts a fixed, always-false disclosure note

skills/implement/phases/phase-4-documentation.md scripts a fixed --note sentence written on every run, including runs where no span was suppressed:

$ grep -c "not durably observable on the cloud tier" skills/implement/phases/phase-4-documentation.md
1
$ grep -c "does not capture" docs/internal/implement-skill.md
1

Expected after the fix

• The helper prints one docgate-suppressed: bash lib/test/run.sh stdout line (backticks stripped) on the adversarial body, and none on clean bodies.
• The phase file records a workpad note naming the span ONLY when a docgate-suppressed: line is present, delivered via --note-file; the fixed false sentence is gone.
• The doc page no longer states the gate does not capture the extractor's stderr.

Devflow Reflection

Devflow Reflection (click to expand)

⚠️ Action required

• ⛔ Blocked: Phase 1.6 issue-claim audit — blocked-specification. The projection reconciliation found an independently-verifiable Desired Behavior obligation with no counterpart in the resolved Acceptance Criteria: "Phase 4.1 Stage 1 records a workpad note naming that span only when such a line is present, passing the text through a file rather than a shell argument" The unmatched clause is the file-vs-shell-argument delivery mechanism. It is security-relevant: an unquoted/backticked suppressed span placed in a double-quoted shell argument could execute, which is exactly why the Implementation Notes mandate --note-file. AC4 covers only removal of the fixed disclosure sentence and AC5 covers only that the note is recorded when a docgate-suppressed: line is present; no AC checks that the span text is delivered via a file (e.g. --note-file) rather than a shell argument. Because Phase 3.4 gates solely on the Acceptance Criteria, proceeding would let this obligation ship unverified. Remedy: amend the issue to add (or fold into AC5) an acceptance criterion asserting that Stage 1 delivers the span text through --note-file and never as a double-quoted shell argument, then re-trigger /prflow:implement 2129. The run stopped before Phase 2 and made no history mutation and created no PR; no AC was synthesized or rewritten.

ℹ️ Notes

• ℹ️ freshness (adopted branch 'issue-2129-make-the-implement-phase-4-1-documentation-gate'): behind origin/main by 3 commit(s) - per the read-target rule, 1.6/2.1 verification reads that adjudicate shipped-work claims target origin/main state, not the fork point
• 📝 Issue accuracy: Issue Make the implement Phase 4.1 documentation gate record only run-specific workpad facts #2129 AC6 mandates that the shipped phase file skills/implement/phases/phase-4-documentation.md name the literal lib/test/modules/coverage-map.json, but the implement prompt extension's relocation policy (issue Shipped prompt surfaces instruct a consumer agent to run files the vendor slice prunes, and no guard covers the shipped skill set #1072) states that lib/test/** names "must never ship to a consumer whose tree does not carry them" and the lib/test/lint-shipped-pruned-path.py gate turns the suite RED on such a reference. Satisfying AC6 required shipping the literal behind a <!-- pruned-path-ok: … --> marker; the reference will appear in consumer-installed copies of the phase file where the path does not resolve. The cleaner shipped-surface form is generic ("the covering run the project's coverage map names for it") with the concrete lib/test/modules/coverage-map.json relocated to the repo-local, unshipped .prflow/prompt-extensions/implement.md; a workpad-side AC rewrite to that generic form was blocked on this cloud tier because --scope-decision-rewritten's full-criterion operands carry both backticks and apostrophes and there is no file/heredoc arm for that flag. Maintainer decision: reconsider whether AC6 should mandate generic phrasing so the consumer-shipped body carries no PRFlow-internal path.
• ℹ️ Phase 3.4 AC gate — two-verifier reconciled record (all 9 criteria satisfied, none blocking). Verifiers: prflow:ac-evidence-verifier + prflow:ac-claim-verifier, reconciled by reconcile-ac-verifiers.py (all_satisfied=true). Reviewed head a6ca918. - AC1 satisfied — monolith PASS Phase 4.1's Documentation-Needed read produces no observable value and its branch logic is untestable, because it is inline shell written twice #1554/Make the implement Phase 4.1 documentation gate record only run-specific workpad facts #2129 adversarial (deliverables + one docgate-suppressed: bash lib/test/run.sh + docgate-path); evidence command-run=yes, single-flight=no (direct run); claim command-source-read=yes. - AC2 satisfied — monolith clean-fixture exact-line PASS lines, no docgate-suppressed line; both sides all slots yes. - AC3 satisfied — monolith PASS Make the implement Phase 4.1 documentation gate record only run-specific workpad facts #2129 merged-stream breadcrumb (rdnd_run grep-c==1); both sides all slots yes. - AC4 satisfied — grep -rl 'not durably observable on the cloud tier' skills/ empty; non-command criterion (command-run=no with reason). - AC5 satisfied — phase-4-documentation.md:89 sole 'suppressed a span' via Write+--note-file (no double-quoted --note); monolith PASS extract-doc-needed-paths.sh: command and grant literals inside the Documentation Needed block are tokenized into phantom doc deliverables that Block implement runs #644 pin. - AC6 satisfied — deferred doc-AC paragraph states all six clauses; non-command claim. - AC7 satisfied — heading verbatim once; monolith PASS Wave 6A — producer/consumer gate fixes: recognize doc-ACs as Phase-4-owned in the 3.4 gate, and harden create-issue's mechanical-claim and Documentation Needed contracts #380 W6A. - AC8 satisfied — lint-reference-size.py no violation for phase-4-documentation.md (61015 bytes < 61750); monolith Cap the size of boundary-gated references and skill roots at 95% of the reader's Read cap #1595 clean. - AC9 satisfied — docs/internal/implement-skill.md relays span as docgate-suppressed line Stage 1 records; no residual 'does not capture stderr' claim. No undischarged slots after re-authoring dispositions in parseable '<yes|no> ' form; reconciler exit 0, blocking=[].
• ℹ️ Verification evidence: lib/test/run-parallel.sh — aggregate CLEAN, 22839 passed, 0 failed, 0 skipped; retained-log root .prflow/tmp/parallel-suite/run-929186-0; elapsed 967s; single-flight consulted (claim role=owner, flight bbe9b04e, state=passed, satisfies_verification=true); completion evidence recorded
• ℹ️ batched-regeneration: run (lib/test/regenerate-artifacts.py --with-floors — all rows clean incl. exact-module-floors, exit 0)
• ℹ️ Verification evidence: local/interactive tier CI reading for PR Make the implement Phase 4.1 documentation gate record only run-specific workpad facts #2137 reception pass — head 1f318a3; lib + python tests: success; lint (shellcheck + actionlint + ruff): success; run https://github.com/The01Geek/prflow/actions/runs/33236888049

[The01Geek]

/prflow:implement 2129