@webpieces/rules-config 0.4.801 → 0.4.803

package/templates/webpieces.git-workflow.md

@@ -19,7 +19,7 @@ That question is already answered: **yes, always.** Run the flow:
 pnpm wp-start-upsert-pr        # ① 3-point update from main. Does NOT push and does NOT build.
 pnpm wp-review-upsert-pr       # ② validates that merge, runs the BUILD GATE, extracts the diff,
                                #   and prints the reviewer subagents to spawn
-# → spawn each reviewer it names (each writes its own review-<id>.json)
+# → spawn each reviewer it names (each submits its own verdict: pnpm wp-write-review --checklist <id>)
 # → write review.json at the exact path it prints
 #   (.webpieces/pr-review/<feature>/review.json — its `title` becomes the PR title)
 pnpm wp-finish-upsert-pr       # ③ creates/updates the PR (and pushes — the ONE push)

package/templates/webpieces.location-matrix.md

@@ -197,7 +197,7 @@ section head (neither the shell's cwd nor a `cd`'s persistence can be assumed).
 | 13 | the same command from a **subagent** runs normally | `w` / `y` — row 8 does not match | ALLOW (handed to L2) | none — a subagent pinned to a worktree is the correct pattern |
 | 14 | inspection inside a SKEWED worktree still runs — `cd <worktree> && ls`/`cat`/`grep` | `w` / `n` / `y` — row 8 does not match | ALLOW (handed to L2) | none — inspection is always open; so are the `Read` tool, `git -C <dir INSIDE this tree> …` and `git show <branch>:<file>`, none of which move you. `git -C <ANOTHER tree>` is a different matter: the harness refuses cross-tree git to a subagent, so it is never the cure for a skew — tell the MAIN agent instead |
 | 15 | `cd <worktree> && pnpm install` still runs while row 8 is live — it is the CURE | L0 allowlist, ahead of L1 | ALLOW | none — a cure must stay reachable from every tree |
-| 16 | a SUBAGENT hits the same block inside `.claude/worktrees/agent-XXXX` | `w` / `n` / `n` — row 8; in-repo placement is still `w` | BLOCK_AI_CURE | READ THE DIRECTION FIRST — the deny prints it. If the MAIN tree is AHEAD (the common case) a subagent fixes this ITSELF, here, by raising this tree's pin to what main already runs; there is nothing to escalate and the deny prints no escalation. Only when main is BEHIND, or when this branch bumped the pin on purpose, is the subagent stuck — the main tree is outside its tree, and a worktree-isolated agent may not even still be in the tree it was launched in (measured: auto-reaped at a turn boundary, resumed on the primary). Then, and only then, forward the deny's verbatim ask to the coordinator and STOP<br>Do NOT: expect exemption because it sits under the repo — K is git's `--git-common-dir` answer, not a path test |
+| 16 | a SUBAGENT hits the same block inside `.claude/worktrees/agent-XXXX` | `w` / `n` / `n` — row 8; in-repo placement is still `w` | BLOCK_AI_CURE | READ THE DIRECTION FIRST — the deny prints it. If the MAIN tree is AHEAD (the common case) a subagent fixes this ITSELF, here, by raising this tree's pin to what main already runs; there is nothing to escalate and the deny prints no escalation. Only when main is BEHIND, or when this branch bumped the pin on purpose, is the subagent stuck — the main tree is outside its tree, and a worktree-isolated agent may not even still be in the tree it was launched in (measured: auto-reaped at a turn boundary, resumed on the primary). Then, and only then, forward the deny's verbatim ask to the coordinator, and do NOT retry the blocked call — it re-fires the identical deny and buries the ask<br>Do NOT: expect exemption because it sits under the repo — K is git's `--git-common-dir` answer, not a path test |
 | 17 | the printed cure REPLACES your `cd`, it does not stack in front of it | `pw` / `y` / `sub` — row 5, on the cure itself | BLOCK_AI_CURE | Option 1 (preferred): run the printed line VERBATIM — `cd <root> && <the work>`, with your own leading `cd` dropped<br>Do NOT: paste `cd <root> && cd <subdir> && <work>`; `effectiveCwd` resolves the leading `cd`s left to right, so that lands in `<subdir>` again and re-fires this exact block |
 | 18 | every command from a worktree another agent REAPED mid-session is blocked | `m` — row 7 | BLOCK_AI_CURE | Option 1 (preferred): run the printed `cd <root> && <the work>` line — it does NOT route back through the dead path<br>Do NOT: re-`cd` into the worktree, or `git worktree add` it back expecting your uncommitted work; that work is gone |
 | 19 | the same block for a NON-git command there — `m` does not care about G | `m` — row 7; K alone decides it | BLOCK_AI_CURE | Option 1 (preferred): the same printed line. A vanished cwd is not a git question — nothing at all can run in a directory that does not exist |

package/templates/webpieces.review-checklists.md

@@ -121,8 +121,8 @@ hand can drift out of date if nothing is restated by hand.
 Unlike the report-only command it replaces, this one **can fail** — on an unresolved merge or a red build.
 It fails before any reviewer is spawned, which is the point.
 
-Checklists already reviewed on this branch are **not** re-listed — verdict files persist, so a second
-start/review/finish cycle re-instructs nothing.
+Checklists already reviewed on this branch are **not** re-listed while their in-scope files are unchanged
+— verdict files persist, so a second start/review/finish cycle re-instructs only what changed.
 
 `wp-finish-upsert-pr` recomputes the same set and **refuses to open the PR** while any reviewer still owes
 a passing verdict, naming only the ones still missing. An optional checklist that was offered and declined
@@ -153,8 +153,22 @@ When `reviewerAgents` is positive, for each matched **required** checklist — a
    `git diff <base> HEAD -- <file>` (base is in `pr-context.json`) — and decide whether the change
    satisfies the checklist. (A path-coarse checklist like "new API/queues" simply reports
    `"status": "green"` when the diffs add no new route/queue.)
-3. Have it **write its verdict** to `.webpieces/pr-review/<featureSlug>/review-<id>.json` (one file per
-   checklist, so concurrent reviewers never clobber each other). `<id>` is the checklist's `id`.
+3. Have it **submit its verdict** with `pnpm wp-write-review --checklist <id>` (the JSON on stdin, or
+   `--file <path>`). The bin writes `review-<id>.json` beside the branch's `review.json` — one file per
+   checklist, so concurrent reviewers never clobber each other — plus `review-<id>.provenance.json`
+   recording WHO submitted it (the harness's own session/agent ids, stamped by the PreToolUse hook), the
+   commit it was briefed on, and a hash of the checklist's in-scope diff. It is the ONLY way a verdict is
+   written: it refuses the coordinating agent, and `wp-finish-upsert-pr` rejects a `review-<id>.json` that
+   has no provenance or was edited after submission. There is no second route.
+
+**Codex has no agent types**, so spawn a generic subagent with NO forked turns — fresh context, never a fork
+of your own conversation — and hand it only the instructions files. The brief on disk is its whole input;
+a forked conversation hands a reviewer the author's reasoning, which costs tokens and its independence.
+
+**Verdicts CARRY while their scope is unchanged.** On a re-run, `wp-review-upsert-pr` keeps a checklist's
+green or yellow verdict while the hash of that checklist's in-scope diff is the one its provenance
+recorded, and prints it as `<id> — carried GREEN from <sha>, in-scope files unchanged`. It briefs only the
+checklists that are red, never ran, were rejected, or whose in-scope files changed. A red is never carried.
 
 **How to ask about the optional ones.** `wp-review-upsert-pr` prints them as their own step, listing each
 with the files it matched and the doc it reviews against. Put them to the human in **ONE multi-select
@@ -163,11 +177,15 @@ answering "no" nine times in a row is being worn down rather than consulted, and
 cheap answer is yes to everything — which is exactly the state `required: false` exists to fix. If they
 pick none, that is a complete answer; go straight to finish.
 
-**You may never write a reviewer's `review-<id>.json` yourself.** If the reviewer agent cannot be spawned,
-that is a config bug, not your cue to self-certify — report it to the human. (webpieces rejects a
-reviewer agent that has no `.claude/agents/<name>.md`, so this should surface as a config error instead.)
+**You may never write or submit a reviewer's verdict yourself.** `wp-write-review` refuses the
+coordinating agent, and a hand-written `review-<id>.json` is rejected at finish. If the reviewer agent cannot
+be spawned, that is a config bug, not your cue to self-certify — report it to the human.
 
-## `review-<id>.json` (each reviewer subagent writes its own)
+**From a plain terminal** (no AI harness in the environment, no hook stamp) `wp-write-review` records the
+submitter as `terminal` — a HUMAN reviewer — and finish accepts it. CI never submits or reads verdicts:
+the review state is local and never committed.
+
+## The verdict each reviewer subagent submits through `wp-write-review`
 
 ```json
 {
@@ -262,7 +280,8 @@ review must not read as a fully-reviewed one.
 ```
 
 Then run `pnpm wp-finish-upsert-pr`. It re-computes the matched checklists, requires a well-formed,
-passing (or overridden) `review-<id>.json` for each, verifies a reviewer subagent ran for each, and
+passing (or overridden) `review-<id>.json` for each — submitted through `wp-write-review`, unedited, and
+judging the in-scope diff as it is now — verifies a reviewer subagent ran for each, and
 only then opens/updates the PR.
 
 > Provenance is verified from Claude Code's own subagent records — it is not tamper-proof (a determined