@ccoalm/ccl-skills 0.15.5 → 0.17.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/code-review/SKILL.md

@@ -74,7 +74,7 @@ Positive challenge capacity opens it at index 1; budget zero is untracked.
 The sole release/high-risk budget-zero exception is a controller-proved
 `markdown-punctuation-only` review: it requires `wording_only_boundary`, permits
 no `complete`, and rejects an author assertion alone (recipe:
-`references/staged-review-contract.md`). After a clean/source-refuted tracked
+`references/wording-only-review.md`). After a clean/source-refuted tracked
 challenge, `complete` may close early and preserve unused rounds. Every result
 exposes controller-owned `self_review_gate`; an outstanding checkpoint blocks
 only external review or completion, not implementation or tests. Even a passed
@@ -134,17 +134,16 @@ echo "code_review_skill_dir=$CODE_REVIEW_SKILL_DIR" >&2
 : "${REVIEW_CHAIN_ID:?set REVIEW_CHAIN_ID to a task-scoped chain id: letters, digits, dot, underscore, hyphen only}"
 : "${REVIEW_STAGE:?set REVIEW_STAGE to the stage this candidate is actually at: explore, build, or release}"
 : "${REVIEW_EVIDENCE_DIR:?set REVIEW_EVIDENCE_DIR to a durable directory you control for the per-round result rows}"
-# Exactly one frozen packet source: a packet you composed (REVIEW_DIFF_FILE, see the
-# packet-composition rules below) or a base ref (REVIEW_BASE). The gate rejects both.
-if [ -n "${REVIEW_DIFF_FILE:-}" ] && [ -n "${REVIEW_BASE:-}" ]; then
-  echo "set exactly one of REVIEW_DIFF_FILE or REVIEW_BASE" >&2; exit 1
-elif [ -n "${REVIEW_DIFF_FILE:-}" ]; then
-  PACKET_ARGS=(--diff-file "$REVIEW_DIFF_FILE")
-elif [ -n "${REVIEW_BASE:-}" ]; then
-  PACKET_ARGS=(--base "$REVIEW_BASE")
-else
-  echo "set exactly one of REVIEW_DIFF_FILE or REVIEW_BASE" >&2; exit 1
+# REVIEW_BASE names the candidate, REVIEW_DIFF_FILE widens what the reviewer reads,
+# and BOTH is a widened packet that must BEGIN with the candidate (composition
+# rules: references/staged-review-contract.md). if-blocks, not `[ -n ... ] && ...`: a
+# trailing false test returns non-zero and `set -e` would kill the caller.
+if [ -z "${REVIEW_DIFF_FILE:-}" ] && [ -z "${REVIEW_BASE:-}" ]; then
+  echo "set REVIEW_BASE, REVIEW_DIFF_FILE, or both" >&2; exit 1
 fi
+PACKET_ARGS=()
+if [ -n "${REVIEW_BASE:-}" ]; then PACKET_ARGS+=(--base "$REVIEW_BASE"); fi
+if [ -n "${REVIEW_DIFF_FILE:-}" ]; then PACKET_ARGS+=(--diff-file "$REVIEW_DIFF_FILE"); fi
 # REVIEW_RUN_DIR holds the raw round-1 result only for the chain handoff; the durable
 # per-round evidence is persisted to REVIEW_EVIDENCE_DIR, whose confidentiality you own.
 REVIEW_RUN_DIR="$(mktemp -d "${TMPDIR:-/tmp}/review-run.XXXXXX")" || exit 1
@@ -199,10 +198,11 @@ bash "$CODE_REVIEW_SKILL_DIR/scripts/review_gate.sh" \
   >"$REVIEW_RUN_DIR/round2.json"
 require_tracked_result "$REVIEW_RUN_DIR/round2.json" challenge 2
 # Both rounds must bind the SAME candidate: the chain accepts older candidate hashes,
-# so a packet edited between rounds would otherwise be persisted as one coherent pair.
+# so a candidate edited between rounds would otherwise be persisted as one coherent
+# pair. Their packets may differ; each receipt records the packet it actually read.
 python3 -c 'import json,sys; a=json.load(open(sys.argv[1])); b=json.load(open(sys.argv[2])); h=a.get("candidate_sha256"); sys.exit(0 if h and h==b.get("candidate_sha256") else 1)' \
   "$ROUND1_RESULT_FILE" "$REVIEW_RUN_DIR/round2.json" \
-  || { echo "round 2 reviewed a different packet than round 1; rerun the pair on one frozen candidate" >&2; exit 1; }
+  || { echo "round 2 bound a different candidate than round 1; rerun the pair on one frozen candidate" >&2; exit 1; }
 cp "$REVIEW_RUN_DIR/round2.json" "$EVIDENCE_RUN_DIR/round2-challenge.json" || exit 1
 cat "$EVIDENCE_RUN_DIR/round2-challenge.json"
 # A secret-free diff egresses to non-Claude reviewers automatically; add
@@ -216,10 +216,10 @@ Run the script by path while keeping `--cwd` pointed at the product repository u
 **The packet is the reviewer's whole world — compose it deliberately.** Review and challenge are built packet-bounded — Claude runs `--tools ""` with no `--add-dir`, and the other wrappers run in an isolated run workspace or a packet-only read surface. Treat the packet as the reviewer's whole world when deciding coverage: it is the only content bound by the packet hash and scanned before egress, so anything outside it is neither reliably visible to the reviewer nor covered by the verdict; a diff-only packet surfaces defects visible inside the changed lines and little else, and `--paths` only narrows it further. Whatever is absent from the packet is unreachable, not merely missed: a contradiction with an unchanged sibling clause, drift against a carrier outside the diff, or a silent weakening of upstream wording cannot be found by a reviewer who never saw the other side — that is the packet's shape, not the reviewer's weakness.
 
 - Codex permits frozen-packet read/search; see [tool boundaries](references/development-completion.md#review-tools).
-- To widen the packet, assemble it yourself and pass `--diff-file`: it replaces base-derived generation, is mutually exclusive with `--base`/`--paths`, and must name a regular file (no symlink or hardlink) holding text without NUL bytes. Worth adding beyond the diff — the canonical rule or contract text the changed lines must not contradict, the sibling clauses in the same file, the derived carriers that restate the change (commit message, MR/PR body), and the actual output of a gate or script under review. The gate hard-caps a packet at 200,000 bytes; split a larger candidate as described in the next bullet.
-- A verdict covers exactly the packet it was taken on, because the recorded packet hash is the reviewed identity. Within a packet, added context sits on top of the candidate diff and never in place of part of it. A candidate too large for one packet is split by file group or risk class into a partition that still covers the whole candidate — every part in some packet, none dropped — each partition's verdict recorded against its own packet hash, and the candidate-wide claim withheld until every partition is conclusive; one partition's `no blocking findings` is never a verdict on the landing candidate. Cross-partition contradictions are unreachable by construction, so repeat the shared canonical context in every partition's packet and review anything that spans partitions as its own packet.
+- To widen the packet, assemble it yourself and pass `--diff-file`, plus `--base` whenever the round must bind a landing candidate ([composition rules](references/staged-review-contract.md#the-packet-and-the-candidate)). It must name a regular file (no symlink or hardlink) holding text without NUL bytes. The gate hard-caps a packet at 200,000 bytes; split a larger candidate as described in the next bullet.
+- A verdict covers exactly the packet it was taken on; the receipt records `packet_sha256` for those bytes and `candidate_sha256` for the base-derived candidate that will land, equal unless the packet was widened. A candidate too large for one packet is split by file group or risk class into a partition that still covers the whole candidate — every part in some packet, none dropped — each partition's verdict recorded against its own packet hash, and the candidate-wide claim withheld until every partition is conclusive; one partition's `no blocking findings` is never a verdict on the landing candidate. Cross-partition contradictions are unreachable by construction, so repeat the shared canonical context in every partition's packet and review anything that spans partitions as its own packet.
 - Added context egresses to the selected reviewer exactly like the diff does, through the same credential tripwire — which catches machine-detectable secrets only. Paste rule text, carriers, and tool output; never paste credentials or material you would not send to that provider.
-- A finding that the input is insufficient to judge the change is an input defect, not a candidate defect: widen the packet and rerun that lane rather than editing the candidate to satisfy it.
+- A finding that the input is insufficient to judge the change is an input defect, not a candidate defect: widen the packet and rerun that lane, keeping `--base` so it still binds the same candidate, rather than editing the candidate to satisfy it.
 
 When intentionally reviewing `code-review` itself, override the resolver from the ccl-skills repo under review before invoking the gate:
 
@@ -280,7 +280,7 @@ For diffs over roughly 2,000 changed lines or 50 files, split review/challenge b
 
 Never treat a timeout, silence, or empty output as approval or "no findings": any timeout is inconclusive, and the final status must say `inconclusive` with the timeout reason so downstream review or merge state cannot treat the missing lane as approval. A live host execution handle such as `session_id` or `cell_id` means the same command is still running; poll that exact handle to terminal exit, and never start a replacement/fallback while its process is live. Do not use a 30 second silence as a review failure — narrow diff reviews legitimately take 2-3 minutes and broad reviews about 5. Challenge makes one formal Claude invocation; review and consult may make at most two only for their existing bounded result-recovery paths. After that, mark the Claude lane inconclusive and apply fallback only if the owning gate allows it. The wrapper traps TERM/INT/HUP and emits terminal `operator_interrupt`; the gate never starts another client after an operator interruption. SIGKILL and host crashes cannot be trapped, so non-zero exit without valid JSON remains inconclusive/manual-review-required, never as success. The timeout bound is per formal invocation, not per wrapper run; outer timeouts must cover the mode's worst case and must never kill the wrapper and then treat the killed output as success. For a yielded run, the caller's lane evidence records handle type, an opaque host transcript/tool-call reference rather than a raw credential-like handle, and terminal exit status. If that handle is lost, the lane is infrastructure-inconclusive/manual-review-required and no replacement or fallback may be started or credited; a `ps`/process-tree capture and wrapper artifacts are diagnostic only and cannot reconstruct the missing terminal result. The outer host assigns this handle after launch, so this is a host-workflow obligation rather than a controller-owned field; exact enforcement requires a trusted host adapter. Recovery detail and timing formulas live in `references/timeout-auth-and-capabilities.md`.
 
-`review_gate.sh` also enforces a cumulative reviewer-lane budget: `--total-timeout` defaults to 2400 seconds, accepts 5 to 3600, reserves ten controller seconds, and divides the remainder by the mode's maximum invocation count. Starting a lane requires at least 21 seconds for review or 16 for challenge, plus setup overhead; smaller accepted values fail closed. Git preflight subprocesses share this deadline; direct filesystem reads still need the host's outer timeout. A timed-out client process group gets bounded cleanup and may cascade only while enough total budget remains. Total exhaustion returns terminal inconclusive `gate_timeout`; killed output is never a verdict. Timing details live in `references/timeout-auth-and-capabilities.md`.
+`review_gate.sh` also enforces a cumulative reviewer-lane budget (`--total-timeout`), shared by git preflight but not by direct filesystem reads, which still need the host's outer timeout. Its default, range, reserved controller seconds, per-invocation division, and per-mode fail-closed minimums are in `references/timeout-auth-and-capabilities.md`. A timed-out client process group gets bounded cleanup and may cascade only while enough total budget remains. Total exhaustion returns terminal inconclusive `gate_timeout`; killed output is never a verdict.
 
 ## Auth And CLI Pitfalls
 
@@ -311,7 +311,8 @@ activation was observed; only a public event/export may populate
 
 ## Reference Loading
 
-- `references/staged-review-contract.md` — required review-plan schema, stage concerns, high-risk depth, prompt layers, and challenge budget. Load before review/challenge.
+- `references/staged-review-contract.md` — review-plan schema, stage concerns, high-risk depth, prompt layers, challenge budget. Load before review/challenge.
+- `references/wording-only-review.md` — the proof-bound wording-only single review. Load when claiming it.
 - `references/manual-invocation-and-prompts.md` — manual command shape, filesystem-boundary text, and the review/challenge prompt templates. Load only when debugging or patching the wrapper or its prompt construction.
 - `references/timeout-auth-and-capabilities.md` — wait-policy timing tables, the numbered auth-recovery procedure, per-mode tool-flag matrix, and CLI capability adoption notes. Load on timeout/auth failures or when maintaining wrapper flag adoption.
 - `references/client-routing.md` — `review_gate.sh` client order, family exclusion, egress, Kimi/Codex boundaries, OpenCode user-model binding, and concurrency rollback. Load when running or diagnosing review/challenge routing.
@@ -341,8 +342,9 @@ In the final work summary, include:
 - mode: review, challenge, complete, or consult
 - command scope, not the full prompt unless useful
 - result: blocking findings, no blocking findings, or inconclusive
-- the reviewed identity — a hash of the exact diff packet reviewed, **required** whenever the reviewed content includes staged, unstaged, untracked, or generated files (later worktree edits keep the same base/head SHA, so SHA alone cannot detect the change); the base/head commit SHA alone suffices only for a clean, fully-committed candidate tree. A review/challenge `no blocking findings` is valid **only** for that exact reviewed content: any later edit, rebase, amend, or new commit voids it and requires a fresh run (mirrors the agentic candidate-SHA binding). A caller — especially one invoking this skill standalone, outside a controller that already tracks the head SHA — must not reuse a prior pass as approval for changed content.
+- the reviewed identity — a hash of the exact diff packet reviewed, **required** whenever the reviewed content includes staged, unstaged, untracked, or generated files (later worktree edits keep the same base/head SHA, so SHA alone cannot detect the change); the base/head commit SHA alone suffices only for a clean, fully-committed candidate tree. A `no blocking findings` result is valid **only** for that exact content: any later edit, rebase, amend, or new commit voids it and requires a fresh run (mirrors the agentic candidate-SHA binding), and no caller — least of all one invoking this skill standalone, outside a controller tracking the head SHA — may reuse a prior pass as approval for changed content.
 - any follow-up fixes made because of the review
+- if `recurring_findings_design_check` fired, the `keep`/`delete`/`narrow`/`replace` decision, what it recurred across, and who ratified it
 - if skipped or inconclusive, the exact reason
 - for a host-yielded execution, the handle type, opaque host transcript/tool-call reference, and terminal exit status; if the handle was lost, record that infrastructure-inconclusive state, diagnostic artifacts, and that fallback was unavailable; never persist a credential-like raw handle in shared evidence
 

package/dist/assets/marketplace/plugins/ccl-skills/skills/code-review/references/staged-review-contract.md

@@ -58,7 +58,12 @@ hand-attested plan (`review_plan_source=implementer-supplied` otherwise).
 Self-review accumulates stage concerns: explore covers correctness and
 safety; build adds failure paths, tests, and compatibility; release adds rollout
 and operations. High-risk input raises depth to release and adds
-`high_risk_boundary`.
+`high_risk_boundary`. That set has one owner, and
+`review_gate.sh --print-required-concerns --stage <stage> [--risk-tag <tag>]`
+prints it, so a caller building a plan derives the list instead of keeping a copy
+that silently stops satisfying the gate when the set changes. It prints what the
+PLAN owes: the synthetic challenge slot and the wording-only boundary, which the
+controller adds for the reviewer and never for the plan, are absent.
 
 The serialized plan is at most 32,000 bytes and `intent` is 8..4,000
 characters. Those are validation limits, not permission for a caller to slice a
@@ -168,6 +173,28 @@ top-level agents, commands, hooks, or MCP servers is not loaded.
 Wrappers keep an explicit selected-owner count instead of testing empty Bash
 arrays under `set -u`, preserving the no-owner lane on Bash 3.2.
 
+### The claim-strength walk, and why the late correction is not cheaper
+
+`claim_strength` is a required self-review concern at build and release depth. The
+plan walks the candidate's load-bearing claims — absolutes, universals, causal
+statements, exhaustiveness — and for each one either names evidence that would
+survive a challenge or weakens the claim on the spot. It is owed before round 1
+because that is the only point in a round where correcting a claim is free: once a
+round binds the candidate, an edit inside a selected owner package voids every
+receipt bound to it, so a sentence that claims too much costs exactly what a changed
+predicate costs. The concern also reaches the reviewer, so a claim that survives the
+walk comes back as a round-1 finding — inside the fix batch the round was going to
+pay for anyway — rather than at closeout, where the remaining moves are a fresh chain
+or leaving it standing.
+
+There is deliberately no cheap late path. The proof-bound single review
+(`wording-only-review.md`) refuses any changed non-punctuation character, which is
+exactly what weakening a claim is, and an exception keyed on the author's own "this
+edit only weakens a claim" is an assertion the controller cannot re-derive — a waiver
+of that shape was carried here once and removed, because a predicate that approximates
+meaning keeps admitting shapes it did not anticipate. The price stays uniform in both
+directions; the walk is what moves the correction to where the price is zero.
+
 ## Base-derived packet input boundary
 
 `--base` freezes the tracked diff plus every non-ignored untracked path in
@@ -184,128 +211,51 @@ commit an in-scope path when Git should represent it; or compose complete
 `--diff-file` partitions when the candidate must be split. Never omit a path
 and report the remaining packet as the whole candidate.
 
+## The packet and the candidate
+
+They are two objects. The **packet** is what the reviewer reads; the **candidate**
+is what will land and what `review_ledger_binding.py` recomputes at merge time.
+A receipt records both hashes.
+
+They hold the same value when the packet came from `--base` alone. Pass
+`--diff-file` **with** `--base`/`--paths` to widen what the reviewer reads while
+the round still binds the landing candidate — the shape an evidence-gap finding
+needs, since editing the candidate would answer an input defect with a candidate
+change. `--diff-file` alone binds no landing; only the combined form rejects a
+`--wording-only-proof-file`.
+
+What makes the widened form safe is a **prefix requirement**: the packet begins
+with the base-derived candidate, byte for byte, so nothing lands unread.
+
+- **Append context after the candidate diff.** Putting anything before the
+  candidate fails, and that is not cosmetic: a packet preceding it with a decoy
+  diff would read as the change while the real candidate read as context.
+  Interleaving context inside the candidate fails, as does dropping any part of
+  it. The reviewer is told where the candidate ends — the profile carries
+  `candidate_bytes` and states that exactly the first N packet bytes land — so
+  appended hunks that continue or seem to revert the diff cannot pass as it.
+- **Keep the packet file outside the repository, and put nothing else in the
+  tree while the rounds run.** The controller counts every untracked path into
+  the candidate; the binder counts only committed content minus the receipt JSON
+  a round adds. A packet file, a superseded round's receipt, or any scratch
+  artifact in the worktree therefore moves the candidate the rounds bind and the
+  binder never computes it — the mirror of committing a plain-text attestation
+  after the rounds. Bound evidence lands before the rounds, receipts after,
+  nothing else present.
+- **Read the candidate identity, do not reconstruct it.** `--print-candidate`
+  is the authority: its base is a fork point, its paths carry the round's
+  exclusions, and it refuses an uncommitted tree.
+- Worth adding beyond the diff — the canonical rule the changed lines must not
+  contradict, sibling clauses, the carriers restating the change, gate output.
+
+Rounds in one chain agree on the **candidate**, not the packet, which lets a
+later round read more than an earlier one.
+
 ## Proof-bound wording-only single review
 
-The wording-only exception is one untracked `review` with
-`challenge_budget=0`; it is not a chain, challenge, or `complete` checkpoint.
-Supply `--wording-only-proof-file` to bind the exception to the exact packet.
-Without that proof, an explore/build budget-zero review remains an ordinary
-single review and cannot be recorded as the wording-only exception;
-release/high-risk budget zero fails before inference.
-
-At release depth, including depth raised by a high-risk tag, only a
-controller-proved `markdown-punctuation-only` check may use this exception.
-`markdown-token-replacement` remains available for explore/build budget-zero
-review, but it cannot waive the release/high-risk challenge: byte-exact token
-replacement does not prove that the old and new tokens have the same meaning.
-
-The proof is a single-link regular UTF-8 JSON file of at most 16,000 bytes:
-
-```json
-{"schema_version":1,"candidate_sha256":"<packet-sha256>","check":{"kind":"markdown-punctuation-only"}}
-```
-
-The other fixed check is
-`markdown-token-replacement`, whose `check` also contains `old_token`,
-`new_token`, and integer `expected_count` (1..100). The controller never trusts
-a caller-supplied pass result. It reparses the frozen packet and derives the
-status, files, changed-line count, replacement count, and scope SHA-256.
-
-The accepted packet is deliberately narrow: a canonical full-context unified
-Git diff, LF-terminated, at most 200,000 bytes, changing existing regular
-Markdown files inside exactly one existing non-linked skill package. Every
-file's first hunk starts at line 1 so frontmatter is inspectable. Adds,
-deletes, renames, multi-skill changes, frontmatter or `description` edits,
-non-regular Git modes, custom/compact packets, extra context outside the diff,
-and files without a final newline fail closed. `markdown-punctuation-only`
-accepts only one-for-one plain-prose line replacements whose non-punctuation
-characters remain identical; numeric tokens must additionally survive
-byte-for-byte (deleting the dot in `5.5` is a threshold change, not
-punctuation), and a question mark may not be added or removed (a statement
-turned into a question is a meaning change). Lines must start at column zero
-and contain prose; line adds/deletes, Markdown headings, lists, block quotes,
-links, tables, inline code, fenced or indented code, and raw HTML `pre`/`code`
-containers fail closed. `markdown-token-replacement` requires every changed
-line pair to differ only by the named whole-token replacement, with the exact
-total count, and rejects packets whose changed lines touch a Markdown or HTML
-code container.
-
-This recipe produces the exact packet and proof without a second parser or a
-pretend verifier command. Set `WORDING_KIND=markdown-punctuation-only`, or set
-`WORDING_KIND=markdown-token-replacement` plus `WORDING_OLD`, `WORDING_NEW`, and
-`WORDING_COUNT`:
-
-```bash
-: "${CODE_REVIEW_SKILL_DIR:?set the installed code-review skill directory}"
-: "${REPO_ROOT:?set the absolute repository root}"
-: "${REVIEW_BASE:?set the exact base ref}"
-: "${SKILL_NAME:?set the one existing skill package name}"
-: "${REVIEW_STAGE:?set explore, build, or release}"
-: "${IMPLEMENTER_FAMILY:?set the implementer model family}"
-: "${REVIEW_PLAN_FILE:?set the absolute review-plan JSON path}"
-: "${REVIEW_EVIDENCE_DIR:?set an existing durable private evidence directory}"
-: "${WORDING_KIND:?set one supported wording-only check kind}"
-
-umask 077
-WORDING_RUN_DIR="$(mktemp -d "$REVIEW_EVIDENCE_DIR/wording-review.XXXXXX")" || exit 1
-WORDING_DIFF="$WORDING_RUN_DIR/candidate.diff"
-WORDING_PROOF="$WORDING_RUN_DIR/proof.json"
-WORDING_RESULT="$WORDING_RUN_DIR/review.json"
-
-git -C "$REPO_ROOT" diff --no-color --no-ext-diff --no-textconv --full-index \
-  --src-prefix=a/ --dst-prefix=b/ --unified=1000000 \
-  "$REVIEW_BASE" -- "skills/$SKILL_NAME" >"$WORDING_DIFF" || exit 1
-
-python3 - "$WORDING_DIFF" "$WORDING_PROOF" "$WORDING_KIND" \
-  "${WORDING_OLD:-}" "${WORDING_NEW:-}" "${WORDING_COUNT:-0}" <<'PY'
-import hashlib
-import json
-import sys
-from pathlib import Path
-
-diff_path, proof_path = map(Path, sys.argv[1:3])
-kind, old, new, count = sys.argv[3:]
-check = {"kind": kind}
-if kind == "markdown-token-replacement":
-    check.update(old_token=old, new_token=new, expected_count=int(count))
-elif kind != "markdown-punctuation-only":
-    raise SystemExit("unsupported WORDING_KIND")
-payload = {
-    "schema_version": 1,
-    "candidate_sha256": hashlib.sha256(diff_path.read_bytes()).hexdigest(),
-    "check": check,
-}
-proof_path.write_text(
-    json.dumps(payload, ensure_ascii=False, separators=(",", ":")) + "\n",
-    encoding="utf-8",
-)
-PY
-
-WORDING_RISK_ARGS=()
-for tag in ${REVIEW_RISK_TAGS:-}; do WORDING_RISK_ARGS+=(--risk-tag "$tag"); done
-if ! bash "$CODE_REVIEW_SKILL_DIR/scripts/review_gate.sh" \
-  --mode review --stage "$REVIEW_STAGE" --challenge-budget 0 \
-  --cwd "$REPO_ROOT" --diff-file "$WORDING_DIFF" \
-  --review-plan-file "$REVIEW_PLAN_FILE" \
-  --wording-only-proof-file "$WORDING_PROOF" \
-  ${WORDING_RISK_ARGS[@]+"${WORDING_RISK_ARGS[@]}"} \
-  --implementer-family "$IMPLEMENTER_FAMILY" >"$WORDING_RESULT"; then
-  cat "$WORDING_RESULT" >&2
-  exit 1
-fi
-cat "$WORDING_RESULT"
-```
-
-A valid result carries `wording_only_proof_sha256`, controller-derived
-`wording_only_scope.status=passed`, and a reviewed
-`wording_only_boundary` concern. That concern independently confirms the edit
-changes no trigger, scope, routing, validation, acceptance, rule, threshold,
-boundary, frontmatter, description, or other meaning. If it is missing,
-inconclusive, or reports a possible semantic change, the wording-only exception
-does not apply: use the normal challenge and behavioral-evidence path. Any
-candidate edit regenerates the packet and proof and requires a new review.
-Keep the diff, proof, and result together; a digest whose source artifact was
-deleted is not independently auditable evidence.
+The wording-only exception — its depth limits, the proof schema, the accepted
+packet, the recipe that produces both, and how a valid result is read — is
+specified in `wording-only-review.md`.
 
 ## Agent review chain
 
@@ -322,8 +272,10 @@ index 1; an untracked initial review is single-round and therefore uses budget 0
 candidate can never be challenged inside it. One succeeding chain may open at
 index 1 in `challenge` mode by supplying `--predecessor-chain-result-file` — the
 ended chain's terminal receipt — instead of an in-chain prior result. The
-controller accepts it only when that receipt is a tracked challenge at its own
-chain's terminal index, carries this chain's `review_scope_sha256` and matching
+controller accepts it only when that receipt is the tracked round its chain ended
+on — a terminal challenge, or a round-1 review whose own
+arithmetic still reports its challenge unspent — carrying this chain's
+`review_scope_sha256` and matching
 stage/depth/risk-tags/budget, preserves the controller digest, owner-selection
 source, and selected owner names, and binds a candidate that DIFFERS from this
 packet: the owner-package digest is the one binding allowed to move, because its
@@ -335,6 +287,24 @@ differ from every focus the ended chain spent. The result records
 satisfied self-review trigger. Succession carries history rather than resetting
 it: consumers still sum rounds across both chains.
 
+A chain ends where the candidate moves, and a fix applied straight after the review
+moves the owner digest exactly as one applied after the challenge does. Requiring a
+challenge receipt here never protected the landing candidate — the succession
+challenge binds that either way — it only forced the challenge to be spent on a
+candidate the author had already decided to replace. The single class that stops
+being owed is a challenge on a candidate that will never land, which carries no
+evidence about the one that does; every other binding is unchanged, the candidate
+must still have moved, succession still does not compose, and this path spends
+fewer rounds than the old one, never more. What bounds it is the receipt's own arithmetic, and that is a
+forgery guard rather than a history check: a genuine round-1 review reads the same
+whether its chain later ran a challenge or not, so a caller who spent the challenge
+and presents only the review is accepted, and the successor inherits no challenge
+focuses — a focus that chain did spend can be spent again. This is the same
+omitted-history boundary the rest of this contract states rather than a new one, and
+the closeout validator's ordered receipt set is where a retained challenge receipt
+would show it; no check at the succession call site can close it, and none is
+claimed.
+
 The chain binds task scope, candidate identity per round, result hashes, mode,
 status, challenge focus, controller, and selected owners. The opaque
 `review_scope_sha256` always hashes normalized intent, acceptance, stage/depth,
@@ -390,6 +360,26 @@ checkpoint, and before a completion claim. Findings never produce a blind
 review-fix-review loop: they block another reviewer call, return to implementer
 triage, and still allow implementation, tests, and independent runnable work.
 
+**Findings that come back are a design question.** When a round returns findings and
+the history it carries already holds one — an earlier round of this chain, or the
+predecessor chain a succession names — the gate adds
+`recurring_findings_design_check` to the required triggers and
+`decide_keep_delete_narrow_replace` to the allowed actions. It blocks nothing that
+`findings_returned` does not already block; what it adds is the question the next
+patch would walk past: whether the reviewed surface should exist in this shape at
+all, answered as `keep`, `delete`, `narrow`, or `replace`, resting on the rounds and
+findings it recurred across, and ratified by a risk owner other than the one
+proposing it. `../../skill-extraction-workflow/SKILL.md` owns that rule; this is where
+it fires, because the situation arises inside a chain and that skill is usually not
+loaded there. Two findings rounds need not share a class, so the trigger over-fires
+by design — answering an inapplicable question costs a line, and the round it saves
+does not.
+
+The count is what the controller can prove, and no more: the rounds of this chain plus
+the predecessor a succession names, which is why the trigger reaches across a chain
+break at all (Chain succession, below). Succession does not compose, so a third chain
+opened fresh carries no history and the recurrence becomes the round's own record.
+
 A passed final external round returns
 `next_action=deep_self_review_before_completion` and remains
 `completion_gated=true`. `--mode complete` accepts one exact-candidate passed

package/dist/assets/marketplace/plugins/ccl-skills/skills/code-review/references/wording-only-review.md

@@ -0,0 +1,136 @@
+# Proof-bound wording-only single review
+
+The wording-only exception to `staged-review-contract.md`: when one review may
+stand in for the review-plus-challenge pair, what the controller re-derives
+before it will say so, and how to produce the packet and proof it accepts.
+
+## The exception and its depth limits
+
+The wording-only exception is one untracked `review` with
+`challenge_budget=0`; it is not a chain, challenge, or `complete` checkpoint.
+Supply `--wording-only-proof-file` to bind the exception to the exact packet.
+Without that proof, an explore/build budget-zero review remains an ordinary
+single review and cannot be recorded as the wording-only exception;
+release/high-risk budget zero fails before inference.
+
+At release depth, including depth raised by a high-risk tag, only a
+controller-proved `markdown-punctuation-only` check may use this exception.
+`markdown-token-replacement` remains available for explore/build budget-zero
+review, but it cannot waive the release/high-risk challenge: byte-exact token
+replacement does not prove that the old and new tokens have the same meaning.
+
+## The proof
+
+The proof is a single-link regular UTF-8 JSON file of at most 16,000 bytes:
+
+```json
+{"schema_version":1,"candidate_sha256":"<packet-sha256>","check":{"kind":"markdown-punctuation-only"}}
+```
+
+The other fixed check is
+`markdown-token-replacement`, whose `check` also contains `old_token`,
+`new_token`, and integer `expected_count` (1..100). The controller never trusts
+a caller-supplied pass result. It reparses the frozen packet and derives the
+status, files, changed-line count, replacement count, and scope SHA-256.
+
+## The accepted packet
+
+The accepted packet is deliberately narrow: a canonical full-context unified
+Git diff, LF-terminated, at most 200,000 bytes, changing existing regular
+Markdown files inside exactly one existing non-linked skill package. Every
+file's first hunk starts at line 1 so frontmatter is inspectable. Adds,
+deletes, renames, multi-skill changes, frontmatter or `description` edits,
+non-regular Git modes, custom/compact packets, extra context outside the diff,
+and files without a final newline fail closed. `markdown-punctuation-only`
+accepts only one-for-one plain-prose line replacements whose non-punctuation
+characters remain identical; numeric tokens must additionally survive
+byte-for-byte (deleting the dot in `5.5` is a threshold change, not
+punctuation), and a question mark may not be added or removed (a statement
+turned into a question is a meaning change). Lines must start at column zero
+and contain prose; line adds/deletes, Markdown headings, lists, block quotes,
+links, tables, inline code, fenced or indented code, and raw HTML `pre`/`code`
+containers fail closed. `markdown-token-replacement` requires every changed
+line pair to differ only by the named whole-token replacement, with the exact
+total count, and rejects packets whose changed lines touch a Markdown or HTML
+code container.
+
+## Producing the packet and proof
+
+This recipe produces the exact packet and proof without a second parser or a
+pretend verifier command. Set `WORDING_KIND=markdown-punctuation-only`, or set
+`WORDING_KIND=markdown-token-replacement` plus `WORDING_OLD`, `WORDING_NEW`, and
+`WORDING_COUNT`:
+
+```bash
+: "${CODE_REVIEW_SKILL_DIR:?set the installed code-review skill directory}"
+: "${REPO_ROOT:?set the absolute repository root}"
+: "${REVIEW_BASE:?set the exact base ref}"
+: "${SKILL_NAME:?set the one existing skill package name}"
+: "${REVIEW_STAGE:?set explore, build, or release}"
+: "${IMPLEMENTER_FAMILY:?set the implementer model family}"
+: "${REVIEW_PLAN_FILE:?set the absolute review-plan JSON path}"
+: "${REVIEW_EVIDENCE_DIR:?set an existing durable private evidence directory}"
+: "${WORDING_KIND:?set one supported wording-only check kind}"
+
+umask 077
+WORDING_RUN_DIR="$(mktemp -d "$REVIEW_EVIDENCE_DIR/wording-review.XXXXXX")" || exit 1
+WORDING_DIFF="$WORDING_RUN_DIR/candidate.diff"
+WORDING_PROOF="$WORDING_RUN_DIR/proof.json"
+WORDING_RESULT="$WORDING_RUN_DIR/review.json"
+
+git -C "$REPO_ROOT" diff --no-color --no-ext-diff --no-textconv --full-index \
+  --src-prefix=a/ --dst-prefix=b/ --unified=1000000 \
+  "$REVIEW_BASE" -- "skills/$SKILL_NAME" >"$WORDING_DIFF" || exit 1
+
+python3 - "$WORDING_DIFF" "$WORDING_PROOF" "$WORDING_KIND" \
+  "${WORDING_OLD:-}" "${WORDING_NEW:-}" "${WORDING_COUNT:-0}" <<'PY'
+import hashlib
+import json
+import sys
+from pathlib import Path
+
+diff_path, proof_path = map(Path, sys.argv[1:3])
+kind, old, new, count = sys.argv[3:]
+check = {"kind": kind}
+if kind == "markdown-token-replacement":
+    check.update(old_token=old, new_token=new, expected_count=int(count))
+elif kind != "markdown-punctuation-only":
+    raise SystemExit("unsupported WORDING_KIND")
+payload = {
+    "schema_version": 1,
+    "candidate_sha256": hashlib.sha256(diff_path.read_bytes()).hexdigest(),
+    "check": check,
+}
+proof_path.write_text(
+    json.dumps(payload, ensure_ascii=False, separators=(",", ":")) + "\n",
+    encoding="utf-8",
+)
+PY
+
+WORDING_RISK_ARGS=()
+for tag in ${REVIEW_RISK_TAGS:-}; do WORDING_RISK_ARGS+=(--risk-tag "$tag"); done
+if ! bash "$CODE_REVIEW_SKILL_DIR/scripts/review_gate.sh" \
+  --mode review --stage "$REVIEW_STAGE" --challenge-budget 0 \
+  --cwd "$REPO_ROOT" --diff-file "$WORDING_DIFF" \
+  --review-plan-file "$REVIEW_PLAN_FILE" \
+  --wording-only-proof-file "$WORDING_PROOF" \
+  ${WORDING_RISK_ARGS[@]+"${WORDING_RISK_ARGS[@]}"} \
+  --implementer-family "$IMPLEMENTER_FAMILY" >"$WORDING_RESULT"; then
+  cat "$WORDING_RESULT" >&2
+  exit 1
+fi
+cat "$WORDING_RESULT"
+```
+
+## Validating the result
+
+A valid result carries `wording_only_proof_sha256`, controller-derived
+`wording_only_scope.status=passed`, and a reviewed
+`wording_only_boundary` concern. That concern independently confirms the edit
+changes no trigger, scope, routing, validation, acceptance, rule, threshold,
+boundary, frontmatter, description, or other meaning. If it is missing,
+inconclusive, or reports a possible semantic change, the wording-only exception
+does not apply: use the normal challenge and behavioral-evidence path. Any
+candidate edit regenerates the packet and proof and requires a new review.
+Keep the diff, proof, and result together; a digest whose source artifact was
+deleted is not independently auditable evidence.