@ccoalm/ccl-skills 0.6.2 → 0.8.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-dev/references/notification-patterns.md

@@ -0,0 +1,40 @@
+# Notification Patterns
+
+Use this when implementing notification clients, webhooks, operator alerts, outbound callbacks, or delivery jobs. For durable delivery state, retries, and terminal-state behavior, also apply `state-machine-task-patterns.md`. (Inbound callback *verification* is `public-api-security-patterns.md`; this file owns the outbound side.)
+
+Sibling note: `go-microservice-dev/references/notification-patterns.md` carries the Go rendering; adapted per stack, kept in sync by review (not under the parallel-stack parity gate).
+
+## Client
+
+- Wrap each delivery provider behind a `typing.Protocol` with a `send(message) -> Result` surface (`dependency-client-patterns.md` owns the Protocol-vs-ABC rule).
+- Build requests with deadlines, content type, status-code validation, and response body size limits.
+- Treat empty message batches as no-op.
+- Parse provider responses into canonical success, retryable error, and permanent error.
+- **Outbound URLs are an SSRF surface** when endpoints are tenant- or operator-configurable: enforce approved schemes/ports; resolve the hostname once, validate the resolved IP against private/link-local/loopback/cloud-metadata ranges, and **connect to that same validated IP** (connect-by-IP with Host/SNI set from the hostname, or a resolver-pinning client hook) — validate-then-let-the-client-re-resolve is bypassed by DNS rebinding returning a public IP to the validator and a private one to the connection; re-run the resolve-validate-pin cycle on every redirect hop, or disable redirects; prefer routing deliveries through a constrained egress proxy.
+
+## Message Shape
+
+- Include notification type, recipient or endpoint reference, template id/version, actor or service identity, trace/log id, safe summary, and dedupe key.
+- Render templates through typed variables, not string concatenation of raw objects.
+- Redact secrets, credentials, tokens, signatures, and large payloads.
+
+## Async Delivery
+
+- Critical delivery uses an outbox table or durable queue with retry count, next retry time, terminal status, and last error.
+- Best-effort alerts may run asynchronously but must recover exceptions and emit logs/metrics on failure (detached-spawn firewall per `async-and-worker-patterns.md`).
+- Use bounded concurrency and backoff; group or throttle repeated alerts by stable fingerprint.
+- Flush or drain delivery workers during graceful shutdown when messages are critical.
+
+## Realtime Client Channels
+
+- For WebSocket/SSE realtime channels, authenticate and resolve app, tenant, and user context before accepting the connection.
+- Keep connection identity in a concurrency-safe registry keyed by the smallest delivery scope, and remove the client on disconnect via `finally`/context-manager cleanup.
+- Rebuild initial client state from the durable store on first connect or cache miss; send a snapshot after connect, then typed/versioned deltas.
+- Maintain cached unread/count state with explicit TTL refresh and atomic increments; a missing realtime cache must not create a durable-count side effect.
+- Queue consumers treat disconnected clients as a no-op delivery outcome after durable storage succeeds.
+
+## Tests
+
+- Test empty batch, timeout, non-2xx response, malformed response, retryable vs permanent classification, redaction, template rendering, dedupe key, throttling, and shutdown drain.
+- Test the SSRF boundary: loopback/private/link-local/metadata-range targets rejected, disallowed scheme/port rejected, redirect to a blocked range rejected, and the pin exercised — assert the connection is made to the validated IP (fake resolver returning different answers on first and second resolution must not reach the second answer).
+- Test realtime connect, duplicate connection, disconnect cleanup, cache-miss bootstrap, disconnected-delivery no-op, and write failure on a closed socket.

package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-dev/references/public-api-security-patterns.md

@@ -19,7 +19,7 @@ Use this for implementing Python public APIs, partner integrations, signed callb
 
 ## Safer Composition (Python 3.14+)
 
-- **Python 3.14 (released 7 October 2025) introduced t-strings via PEP 750** — template literals using `t"..."` syntax that evaluate to `string.templatelib.Template` objects rather than `str`, giving a consuming function access to interpolated values BEFORE they are combined into a string. The standard library exposes `string.templatelib.Template`. **t-strings are inert by themselves — they are NOT automatic injection protection by syntax**. A bare t-string only carries the raw values plus their surrounding template; safety arrives only when a trusted consumer library is t-string-aware and validates/escapes each interpolation according to its target language (SQL, shell, HTML). Writing `t"SELECT * FROM users WHERE id = {user_id}"` and passing it to an ORM/driver that has not added Template support gains nothing over an f-string — and passing it to a function expecting `str` triggers `Template.__str__()` which raises by default, surfacing the misuse rather than silently producing the wrong result. As of 2026-Q1: most popular template engines (Jinja2, Django templates) and most DB drivers do NOT yet consume `Template` directly — verify the specific library's Template support before relying on this rule. **PEP 787 (safer subprocess via t-strings) is currently Deferred to Python 3.15** per peps.python.org — PEP authors are pursuing experimental t-string subprocess work outside the stdlib through 3.14 beta before re-proposing for 3.15. Do NOT assume `subprocess.run(t"...")` works safely in 3.14; for shell/subprocess composition on 3.14, keep using `shlex.quote()` + argument-list form (`subprocess.run(["cmd", arg])`) until PEP 787 or its equivalent lands. For Python ≤3.13 targets, t-strings are unavailable — keep `shlex.quote()` / parameterized DB queries / framework-native HTML escaping; t-strings are a 3.14-and-later opt-in, not a backport.
+- **Python 3.14 (released 7 October 2025) introduced t-strings via PEP 750** — template literals using `t"..."` syntax that evaluate to `string.templatelib.Template` objects rather than `str`, giving a consuming function access to interpolated values BEFORE they are combined into a string. The standard library exposes `string.templatelib.Template`. **t-strings are inert by themselves — they are NOT automatic injection protection by syntax**. A bare t-string only carries the raw values plus their surrounding template; safety arrives only when a trusted consumer library is t-string-aware and validates/escapes each interpolation according to its target language (SQL, shell, HTML). Writing `t"SELECT * FROM users WHERE id = {user_id}"` and passing it to an ORM/driver that has not added Template support gains nothing over an f-string — and passing it to a function expecting `str` triggers `Template.__str__()` which raises by default, surfacing the misuse rather than silently producing the wrong result. As of 2026-Q1: most popular template engines (Jinja2, Django templates) and most DB drivers do NOT yet consume `Template` directly — verify the specific library's Template support before relying on this rule. **PEP 787 (safer subprocess via t-strings) remains a Draft targeting Python 3.15** (postponed from 3.14; per peps.python.org, re-verified 2026-08 — not yet accepted) — PEP authors are pursuing experimental t-string subprocess work outside the stdlib before re-proposing for 3.15. Do NOT assume `subprocess.run(t"...")` works safely in 3.14; for shell/subprocess composition on 3.14, keep using `shlex.quote()` + argument-list form (`subprocess.run(["cmd", arg])`) until PEP 787 or its equivalent lands. For Python ≤3.13 targets, t-strings are unavailable — keep `shlex.quote()` / parameterized DB queries / framework-native HTML escaping; t-strings are a 3.14-and-later opt-in, not a backport.
 
 ## Signature And Replay Verification
 

package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-dev/references/replay-comparison-patterns.md

@@ -0,0 +1,30 @@
+# Replay Comparison Patterns
+
+Use this when implementing replay jobs, shadow execution, response comparison, migration verification, or diff reports. Reuse `state-machine-task-patterns.md` for job transitions and terminal-state behavior.
+
+Sibling note: `go-microservice-dev/references/replay-comparison-patterns.md` carries the Go rendering; adapted per stack, kept in sync by review (not under the parallel-stack parity gate).
+
+## Replay Jobs
+
+- Persist replay jobs with status, target, config version, total/processed/success/failed/diff counts, timeout, concurrency, rate limit, and retention.
+- Use bounded workers with deadlines (`async-and-worker-patterns.md`) for replay execution.
+- Preserve only allowlisted headers and metadata; never replay credentials blindly.
+- Redact captured requests and responses before storage; bound captured payload size.
+- Replay targets must not commit side effects unless isolated by environment, lane, or explicit dry-run mode. Transaction rollback isolates only the local database write — a replayed handler can still send webhooks, publish messages, call payment providers, or write other datastores while its DB transaction rolls back; those adapters need environment/lane isolation or dry-run stubs of their own before rollback counts as isolation.
+
+## Comparator Design
+
+- Define a comparator `typing.Protocol` such as `compare(original, replay) -> Result`; select comparators by method, route, content type, or schema version.
+- Generic JSON comparators normalize strings containing JSON, Pydantic models, dicts, lists, and scalars before comparing.
+- Support ignored fields by exact path/field name only when documented, loaded from config or comparator registration — never hard-coded in the generic comparator.
+- Support custom field comparators for tolerances, unordered collections, timestamps, generated IDs, and approximate numerics.
+
+## Diff Result Shape
+
+- Include field name, field path, original value summary, replay value summary, diff type, diff score, ignored flag, and metadata; bound value summaries so diff records do not store huge payloads.
+- Record total compared fields, diff count, similarity, threshold, comparator name, and comparator version.
+- Distinguish missing value, added value, type mismatch, length mismatch, value mismatch, and custom comparison.
+
+## Tests
+
+- Test None/None, None/value, value/None, JSON-string normalization, model-to-dict conversion, array length mismatch, missing keys, numeric tolerance, ignored fields, custom comparator, threshold behavior, redaction, storage pagination, and replay cancellation.

package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-dev/references/state-machine-task-patterns.md

@@ -0,0 +1,48 @@
+# State Machine And Task Patterns
+
+Use this when implementing durable tasks, async workflows, scheduled jobs, imports, exports, and retryable processors. This is the canonical guide for durable state transitions and terminal-state behavior; generic worker/async mechanics stay in `async-and-worker-patterns.md` and `background-job-patterns.md`.
+
+Sibling note: `go-microservice-dev/references/state-machine-task-patterns.md` carries the Go rendering of the same discipline; content is adapted per stack and kept in sync by review (not under the parallel-stack parity gate).
+
+## State Model
+
+- Define states as a domain-owned `Enum` (per the skill entrypoint's finite-value rule) with documented terminal states.
+- Define allowed transitions in one table or policy function; do not scatter status checks across handlers.
+- Terminal states reject ordinary processing and failure transitions.
+- Include retry count, last error, start time, finish time, progress, result pointer, and idempotency key when tasks are inspectable.
+- Store progress separately from state; progress is best-effort while state transitions are durable.
+- Create the durable task row before launching background work, queueing expensive processing, or generating external artifacts — a crash must leave an inspectable, repairable record.
+
+## Transition Implementation
+
+- Guard transitions with compare-and-update (`UPDATE … SET status=:new WHERE id=:id AND status=:expected` and check rowcount), `SELECT … FOR UPDATE`, or a Redis lock (`redis-cache-lock-patterns.md`) before processing.
+- Lease or lock owners must be unique at the runtime-instance level, not only the service level: include pod/host identity plus process id or a random instance id so replicas cannot claim or complete each other's work.
+- A lock alone does not fence: a paused worker whose lease expired can resume and commit after a new owner took over — unique owner names do not prevent this. Every durable write under a lease carries a fencing check at the store it writes to: a monotonic fencing token compared there, or owner/version compare-and-update (`… WHERE id=:id AND owner=:me AND version=:v`), so a stale holder's write fails instead of overwriting the new owner's state.
+- A store-side check fences only that store: a stale worker can pass the DB compare-and-update, pause, lose its lease, and then fire a NON-transactional external effect (a charge, a send) after the new owner completed. External side effects under a lease go through intent-then-execute (`sqlalchemy-and-migrations-patterns.md` outbox / the intent pattern in `python-service-architecture/references/event-driven-architecture.md`): the durable intent row is claimed with the fencing check, and the provider call carries an idempotency key bound to that intent. This fully fences **only when the provider actually enforces the key** (rejects or deduplicates a replay). For providers that cannot — SMTP, plain webhooks, any at-least-once send with no key support — no fencing eliminates the stale-execution window: shrink it with a claim re-check immediately before the call, then classify the effect honestly as at-least-once with a duplicate-visible reconciliation path, and record the residual duplicate window instead of claiming exactly-once.
+- Re-read task state under the lock before side effects.
+- Make duplicate delivery normal: already-successful is success or no-op; already-terminal is no-op or a typed conflict depending on the caller's contract.
+- Start transitions move pending work to processing before expensive work begins.
+- Failure transitions capture canonical error code, safe message, retryable flag, retry count, and last trace/log id.
+- Success transitions persist the result pointer or summary before publishing completion events; completion events are idempotent.
+
+## Async Processing
+
+- Prefer queue/worker execution (Celery/RQ/arq per `background-job-patterns.md`) for work that must survive process restart.
+- Delayed events and queue messages re-check current task state when consumed.
+- Retry thresholds and backoff live in config or state policy, not inline literals.
+- A broad `except Exception` at the task boundary converts the task to failed or retryable-failed per the retry policy (never swallow `asyncio.CancelledError` — re-raise it after cleanup, per `async-and-worker-patterns.md`).
+- Work that produces a file, report, or media artifact persists the object key or result pointer before the success transition and exposes a retryable failure state when upload/finalization fails.
+
+## Scheduled Repair Jobs
+
+- Scheduled checkers that repair stuck tasks need a job name, interval, distributed lock key, lock lease, per-run max batch size, and max execution time.
+- A job-level lock prevents duplicate scans; a task-level lock or compare-and-update prevents duplicate repair of one record.
+- Time-window selection is explicit, bounded, and based on durable timestamps (`updated_at`), not process memory.
+- Repair actions re-read current task state before changing status or emitting side effects.
+- Emit metrics for scan count, claimed count, repaired count, skipped count, lock conflict, failure, and duration.
+
+## Tests
+
+- Test illegal transition, duplicate event, concurrent processing (two claimers, one winner), already-terminal, retry threshold, cancellation, exception-to-failed conversion, and completion-event idempotency.
+- Test lease expiry with a stale worker resuming after a new owner claimed the task: the stale worker's durable write and side effect must be rejected by the fencing check.
+- Test scheduled repair lock conflict, stale-window selection, per-task duplicate prevention, and repeated-run idempotency.

package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-dev/references/testing-and-quality-patterns.md

@@ -14,6 +14,15 @@ Use this for pytest, async tests, fixtures, fakes, ruff, mypy/pyright, and CI qu
 - Use markers to separate unit, integration, API, contract, E2E, live-infra, failure-mode, and drill tests.
 - Use `pytest-asyncio` for async code according to repo configuration.
 - Avoid long sleeps and live credentials in default tests.
+
+## TC Traceability And Deprecation Cascade
+
+- **TC traceability**: link tests via `@pytest.mark.tc("TC-XX-NNN")` marker. Registers at collection time so `@skip` / `@skipif` / fixture failures still map to Bitable status. Needs the `tc` plugin from `test-artifact-management/references/tc_helpers/tc.py` loaded via `addopts = -p tc`. See `test-artifact-management/references/tc-marker-conventions.md`. Before adding tests, `grep -rn 'pytest\.mark\.tc' tests/` plus the sidecar `test/results/tc-map.jsonl` to check for existing coverage — extend rather than duplicate. When a TC is marked 废弃, grep both source and sidecar; follow deprecation cascade in `testing-strategy`. Tests without any TC link: prompt user only when the underlying code is also removed.
+- **废弃级联：业务代码是否仍在用** — grep 只找出"测试函数引用了什么 import"是第一步；判断"该 import 是否还有其他 caller"才能定生死。Python 顺序：
+  1. 看测试体导入的模块：`grep -E "^(from |import )" tests/test_<x>.py`
+  2. 对每个产品模块（非 stdlib / 非测试 helper），找全仓库 caller：`grep -rEn "from <pkg>\.<mod>|import <pkg>\.<mod>" --include='*.py' --exclude-dir=tests`
+  3. 零产品 caller → 同 commit 删该模块 + 测试；有产品 caller → 测试目标仍在用，不删测试（若 TC 已废弃但代码活，先确认产品决策）
+  4. 边界：动态 import（`importlib.import_module("...")`）grep 抓不到；含 reflection 的代码人工确认；DI/插件注册（`@register` 装饰器）的产品代码需查注册表而非 import
 - For scenario tests, use `testing-strategy` to build the scenario matrix first; in Python services, map scenarios to unit tests, API/contract tests, integration tests, workflow tests, or marked E2E/live-infra tests instead of putting every case into a slow end-to-end suite.
 
 ## Test Target Split
@@ -58,4 +67,4 @@ Use this for pytest, async tests, fixtures, fakes, ruff, mypy/pyright, and CI qu
 - Keep generated or vendored code excluded according to repo policy.
 - Use coverage gates when the repo already enforces them or the change is high risk.
 - **`ruff` (Astral) is the current default-recommendation single tool for lint + format + import sort** — per Astral docs, replaces Flake8 (and dozens of plugins), Black, isort, pydocstyle, pyupgrade, autoflake with one Rust binary; ~900 lint rules (vs Pylint ~409, with ~209 rule overlap); ~tens to hundreds of times faster than the tools it replaces (e.g., the FAQ cites 250k-LOC codebase 2.5min on Pylint vs 0.4s on Ruff). Auto-fix for most violations. Use ruff for new projects by default; existing projects can migrate piecewise (linter and formatter are independent — adopt one without the other). **Pylint coverage gap to audit before retiring it**: ruff does NOT replicate Pylint's deeper semantic / data-flow analysis (Pylint's inference engine can catch e.g. argument-count mismatches across complex call chains, unreachable-after-mutation patterns, type-confusion in dynamically typed code that doesn't reach the type checker), Pylint's broader dead-code detection (beyond ruff's import-level checks — unused-method, unused-attribute, unused-private-member with project-aware reasoning), design smells (cyclomatic-complexity bands, too-many-arguments / too-many-locals / too-many-branches thresholds), duplicate-code detection (`similarities` checker), and any custom in-project Pylint plugin or rule. Strategy: ruff + a type checker (mypy / pyright / ty) replaces Pylint for ~80% of teams; teams relying on the specific Pylint capabilities above should keep Pylint as a slower secondary gate or migrate the equivalents (e.g., use `radon` for complexity, `vulture` for dead-code, a type-checker-level config for design smells) before retiring.
-- **`ty` (Astral, Beta announced 2025-12-16 per Astral's own announcement) is the current state of Rust-based type-checker work** — per the Astral announcement, on full check "consistently between 10x and 60x faster than mypy and Pyright" depending on workload, with editor incremental recompute on the order of ~80x faster than Pyright on a touched load-bearing file in benchmark workloads. Read these as Astral-published numbers on Astral-chosen benchmarks; actual speedup on a given codebase varies. Notable features: first-class intersection types, advanced narrowing, reachability analysis. Status: **Beta, not GA** — appropriate for piloting on a separate CI job alongside the existing mypy / pyright / basedpyright gate, NOT for replacing the production type-check gate on its own yet. **Dual-gate operational cost to size before adopting**: running ty plus mypy/pyright produces a "triage tax" — divergent type narrowing (one tool reports, the other doesn't), different stub-package assumptions (typeshed version skew), duplicated CI latency, and a "fix one, break the other" churn pattern that slows MRs. Make the pilot a non-blocking informational job and budget time for periodic finding-diff review rather than treating both as equal blocking gates. Watch for ty GA before flipping defaults. basedpyright remains a viable strict-mypy-like alternative if Pyright's strictness gaps matter and ty isn't ready.
+- **`ty` (Astral, Beta announced 2025-12-16 per Astral's own announcement) is the current state of Rust-based type-checker work** — per the Astral announcement, on full check "consistently between 10x and 60x faster than mypy and Pyright" depending on workload, with editor incremental recompute on the order of ~80x faster than Pyright on a touched load-bearing file in benchmark workloads. Read these as Astral-published numbers on Astral-chosen benchmarks; actual speedup on a given codebase varies. Notable features: first-class intersection types, advanced narrowing, reachability analysis. Status: **Beta, not GA** (re-verified 2026-08: still beta; Astral projects a stable release within 2026, with the beta→stable gap focused on stability, typing-spec completeness, and first-class Pydantic/Django support) — appropriate for piloting on a separate CI job alongside the existing mypy / pyright / basedpyright gate, NOT for replacing the production type-check gate on its own yet. **Dual-gate operational cost to size before adopting**: running ty plus mypy/pyright produces a "triage tax" — divergent type narrowing (one tool reports, the other doesn't), different stub-package assumptions (typeshed version skew), duplicated CI latency, and a "fix one, break the other" churn pattern that slows MRs. Make the pilot a non-blocking informational job and budget time for periodic finding-diff review rather than treating both as equal blocking gates. Watch for ty GA before flipping defaults. basedpyright remains a viable strict-mypy-like alternative if Pyright's strictness gaps matter and ty isn't ready.

package/dist/assets/marketplace/plugins/ccl-skills/skills/release-coordination/SKILL.md

@@ -61,6 +61,8 @@ This skill coordinates gates; it does **not** itself authorize merge, tag push,
 | Reset dev/test-like branches | Yes | Target/env refs, before SHAs, dry-run/plan, force-with-lease semantics |
 | Post-merge cleanup of the merged temp feature branch (worktree/local/remote) | No — covered by the user's merge authorization (`worktree-isolation` 收尾) | The authorized MR/PR read back as merged at the current head SHA and target; the live remote source ref is absent (already cleaned by the platform) or still equals the merged MR source head (moved → preserve and ask, remote path only — eligible local cleanup proceeds per `worktree-isolation`); no other open or plan-declared MR/PR still consumes the source branch; source branch is a temp feature branch (unclear role → preserve and ask); mechanics/safety rails per `worktree-isolation` |
 
+**The matrix is a ceiling, not a floor.** A `Yes` row scopes authorization to that action and to the reversible mechanical prerequisites *inside* it — those are not re-asked. Inheritance stops there: it never covers a retry of a consumed authorization (`worktree-isolation` 合并执行协议), a follow-up action, or a prerequisite that is itself gated — that one keeps its own row, so "X needs Y" cannot launder Y's gate. Post-merge cleanup is not an instance of this inheritance; it is the separate narrow carve-out that the boundary above and its own row define. An action absent from this matrix does not acquire a gate by analogy with a listed one — route it to its owner's rules. **Absence is not permission**: anything irreversible, destructive, production-affecting, or of unclear authority preserves state and asks even with no row of its own. Only a clearly reversible, ungated action is ordinary work.
+
 ## Minimal checklist
 
 - [ ] Intended scope, base/head refs, and production target identified.

package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/SKILL.md

@@ -111,10 +111,10 @@ Use this skill to turn observed experience into durable agent skills without cop
   - Method: scan the current session's available-skills list before building the owner-generalization map; for each lifecycle stage, name the external-skill candidate alongside the ccl-skill candidate; route to the external skill when it owns the operational recipe and keep the CCL skill as the gate-keeper / cross-cutting rule layer.
   - When external packages are absent in a teammate's environment, the CCL skill's principle wording must stand alone (no broken `superpowers:*` / `gstack-*` references in executable guidance) — name them as "if installed, route to X; otherwise apply the principle inline".
 - When a user correction or self-check exposes one missed extraction dimension, sibling owner, or lifecycle stage, scan the immediate neighbors on the same axis before landing the fix. Reuse existing machinery: target-output map for lifecycle, sibling-generalization mini-map for stack/owner, and the source type's dimension enumeration for judgment axes. Do not invent new axes per task and do not walk beyond immediate neighbors. Land only the smallest needed updates and record one line per neighbor as `update`, `unchanged`, or `routed`. The trigger is a discovered miss, not every extraction.
-- **Class-wide routing/trigger changes require COMPLETE-set coverage in one pass — the immediate-neighbor scan above does NOT apply.** The neighbor scan covers a *single discovered miss*; a change whose rule is "every skill of class C should advertise / scope / carry X" (e.g. "every stack `*-dev`/`*-architecture` should advertise a localized-refactor trigger") is out of its scope.
+- **Class-wide routing/trigger changes require COMPLETE-set coverage in one pass — the immediate-neighbor scan above does NOT apply.** The neighbor scan covers a *single discovered miss*; a change whose rule is "every skill of class C should advertise / scope / carry X" is out of its scope.
   - For such a change, first write an **explicit, narrow, source-backed class predicate** (from how the user/source phrased the class — not an expansive inference from examples; if the predicate is ambiguous or huge, downscope or ask, and record non-member exclusions).
   - Then the COMPLETE set matching that predicate is the required coverage: enumerate the installed members from the session available-skills list PLUS any referenced repo-present CCL members (absent ones get `install-drift: pending` per the next rule, never silent omission), and update or explicitly mark each `unchanged`/`routed` in ONE landing before claiming the class closed.
-  - Landing one member-pair (e.g. Python+Go) and waiting for the user to surface each remaining member across rounds is the defect this prevents; a repeated same-class miss across rounds is the signal.
+  - Landing one member-pair and waiting for the user to surface each remaining member across rounds is the defect this prevents; a repeated same-class miss across rounds is the signal; member-JOIN duty: `references/source-to-skill-extraction.md#member-join-inheritance`.
   - Validation gate: the closeout map lists every predicate-matching member with a status, or the class is not closed.
   - (Ordinary single-skill edits still use owner/sibling checks, not a full-class sweep.)
 - **A referenced ccl-owned/vendored skill not installed in a host is install-drift, not a valid `not-applicable`.** When enumeration reaches a skill that exists in the canonical CCL repo (or is vendored here) and is referenced by the tree but not installed in a host, do NOT mark it `not-applicable: not installed` and move on — that records a symptom as a reason and the skill silently never fires there. Record `install-drift: pending`, surface the exact remediation, and install it ONLY via an approved user/maintainer instruction or the managed install script — do NOT silently create host symlinks or install unprompted (a host mutation changes future routing globally and can point at the wrong checkout). Until installed, that member's coverage stays interim, not omitted. This applies ONLY to ccl-owned/vendored skills; an absent *external/system* package routes to maintainer/upstream, never local install/edit.
@@ -178,9 +178,9 @@ Use this skill to turn observed experience into durable agent skills without cop
   - So the row records, per protected predicate, the removal that was **applied** and observed to turn the suite RED **for the right reason** — a bare non-zero exit does not qualify (a mutant that breaks syntax or fixture setup also exits non-zero and would bank a broken build as proof of sensitivity); the failure must be attributable to the named protected assertion, and attribution is **differential** (the owning assertion passes in the unmutated control and fails under the mutant, with no non-owning assertion failing) rather than a substring match on aggregate output. An unapplied "this mutation would fail it" is a hypothesis. `testing-strategy` owns the encoded form of that walk (route, don't copy) — for a destructive artifact the walk belongs inside the suite so a later fixture change cannot silently re-blind it.
   - A challenge skip row is allowed only for wording-only changes; trivial scope does NOT exempt a non-wording change, and ANY skill `description`/frontmatter edit — including a pure typo fix — is NOT wording-only (it changes the routing surface) — both require the full gate.
   - If a human explicitly asks to skip independent review or challenge, record the review state and residual risk honestly instead of fabricating a pass. Chat or candidate-local text may authorize an in-scope preparation/commit action, but CI authority comes from the protected platform. Distinguish a narrow exact-candidate `review_waiver` (only the review lane becomes non-blocking) from an exact-candidate `merge_authorization` (the human's final merge decision: every CI lane remains visible but none may block that merge). Neither state rewrites failures as passed.
-  - The Agent-autonomous review budget is the initial review plus at most four challenges, five external rounds total; it never limits deep self-review, implementation, tests, or an authenticated human request. `self_review_gate` mechanically fires before external review, after findings/candidate/scope changes, at the post-budget checkpoint, and before an Agent completion claim. Its `blocks` are narrow: another external review and/or the Agent completion claim, not productive work or an authenticated human merge authorization. Candidate-controlled input cannot assert either human decision.
+  - `code-review` permits one review plus four challenges. **Non-wording** Agent-autonomous work MUST use `scripts/extraction_review_gate.sh` at `challenge_budget=2` (three rounds); proven wording-only work keeps the single-review path and no terminal ledger. Later human-requested review is separately attributed outside the non-wording chain, never relabelled round 4/5. Neither budget limits deep self-review, implementation, tests, or authenticated human action. `self_review_gate` fires before external review, after findings/candidate/scope changes, at post-budget, and before an Agent completion claim; it blocks only another review/completion claim, not productive work or human merge authority. Candidate input cannot assert human authority.
   - Agents cannot self-authorize skipping independent review for any shared-skill change, a challenge skip for non-wording shared-skill changes, or skipping the behavioral-evidence row / true baseline comparison for any change that alters behavior or routing.
-  - If a required review/challenge row or its required pass is absent, skipped, inconclusive, or unavailable — a recorded `review unavailable after remediation` (or equivalent non-success) row does NOT satisfy the gate — block the Agent's completion/commit claim, run/remediate the review lane when Agent budget remains, or use an approved alternate independent reviewer with the same bounded-scope, attribution, timeout, and output-validity requirements. When Agent budget is exhausted or every lane remains inconclusive, report an `interim` checkpoint, continue self-review/implementation/tests and independent runnable work, and park only decision-dependent work. Only an authenticated human may waive the review-process gate or stop the overall iteration; neither action is inferred from a local file or Agent statement.
+  - Missing, skipped, inconclusive, or unavailable required review blocks Agent completion/commit; remediate within wrapper budget or use an approved alternate under the same scope, attribution, timeout, and output checks. If all lanes stay inconclusive, report `interim`. At round 3 validate the v3 receipt-bound ledger: it derives state from the supplied controller chain but cannot prove omitted history or live remote currency, so retain history and run the reference's landing recheck. Report non-success, continue independent work, and park only dependent work. Only an authenticated human may waive review or stop iteration.
 - A skill is not done until it is validated for discovery, YAML, generic wording, reference links, and at least one non-static evidence row for any non-wording extraction: source reopen, task-shape replay, runtime/rendered/device check, target-owner behavior proof, or an explicit unavailable-with-remediation record. Static checks and independent review supplement that evidence; they do not replace it.
 - A pressure scenario is not a real extraction test unless it reopens at least one relevant source artifact, reruns the observation -> judgment -> rule -> acceptance path, and either lands a discovered gap or records that no new rule was found. Re-reading only the changed skill text is a static review, not a pressure test.
 - If the primary independent reviewer hangs, returns no output, hits auth/quota/rate-limit, cannot prove tool posture, cannot show its read covered a large candidate file's middle (a fired read tool-call proves access, not content-fidelity — see the read-coverage check in `references/dual-track-review-gate.md`), or expands beyond the intended scope, do not count it as review evidence. First use the owning wrapper's documented remediation path; for Claude review/challenge, use `../code-review/SKILL.md` (`claude_review.sh`, host/direct recovery, structured output validation). The legacy bounded packet in `references/validation-and-landing.md` is debugging/advisory context only — it is never itself the gate-valid review path; the wrapper (or an approved alternate under the same lane, packet, attribution, timeout, and output-validity rules) is. If wrapper remediation still cannot produce a valid result and an approved alternate reviewer is available, switch tools while preserving the same lane (review vs challenge), bounded diff/file packet, attribution, timeout, and output-validity requirements. A free-form or hanging alternate run is still inconclusive; it does not satisfy the row.

package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/coverage-exhaustion-traps.md

@@ -34,6 +34,51 @@ Its fix is therefore not "read the real artifact" but **walk a seed list of chan
 
 **Failure shape:** an agent researching one organization from public sources declares "the public channels are mined out" five separate times; each time the user pushes back, a **previously unconsidered channel class** lands major evidence (an archive route around a bot-block, a regulator's bulk dataset, a mandatory-disclosure regime, another jurisdiction's statutory filings, a filing the organization voluntarily publishes on its own site). No artifact was hiding these — they were never on a list. The domain-side channel taxonomy lives with the research owner (`skills/multi-perspective-research/references/public-disclosure-channels.md`, repo-root relative); what belongs here is the recurrence memory that an exhaustion claim over a *channel set* needs a walked class list, not more effort inside the known classes.
 
+## Variant (d) — the OTHER agent line's store (the corpus you cannot see from where you stand)
+
+More than one agent runs against the same repository, and each keeps its lessons in its own host's store. Those stores do not see each other. An extraction that enumerates "the lesson corpus" from the host it happens to be running on has enumerated **one line's half of it** and will report exhaustion over a corpus it never touched — the core trap, with host boundary as the thing doing the masking.
+
+Measured in round 059: one line held hundreds of `symptom -> cause -> fix` records while another held a few dozen distilled entries, in different trees under different roots with no reference between them. The figures are deliberately not pinned here — these stores are LIVE and grow while you work, so a count written into a durable document is a timestamped measurement that starts rotting the moment it lands; a re-count during this round's own self-check already disagreed with every figure it had recorded hours earlier. State DEPTH, which is stable, not SIZE, which is not. Neither line's store contained a pointer to the other. The consequence is not abstract: one class recurred **eight times across independent sessions** on the line that lacked the abstraction, while the line that had already generalized it — same repository, same weeks — carried the remedy the whole time.
+
+The gate: before any complete / exhausted / no-gap claim over a *lesson or failure* corpus, the landing that makes the claim carries, **for each agent line, a verdict** — `covered` / `digest-only` / `unavailable` / `excluded` — and under it one row per store backing that verdict. A per-store list without a per-line verdict is the failure this gate exists to stop: a reader cannot tell from four mixed rows whether the line was actually covered. A line whose store you cannot read is `unavailable` with the remediation attempted, never an omission; a line you deliberately leave out is `excluded` with the reason. Locate the stores by enumerating the hosts that actually work the repository, not by assuming the layout your own host uses — the other line's may be one large per-session file where yours is a directory of entries, and a path-shaped guess finds nothing and reads as absence (the same "keyed by something other than what you are asking about" failure the blocked-source ladder names).
+
+**Where these rows live — the split that makes the gate checkable.** Two different things get confused here. The *provenance* — the corpus itself, and the project, repository, branch, ticket and contributor identifiers inside it — is what the extraction lifecycle keeps in per-host scratch, and it stays there. An agent product name and its own config path (`~/.codex/memories/`) are neither: they identify a tool this repository already names throughout, carry nothing about any project, and a leakage audit over them comes back clean. The *coverage rows* are store location, status, depth and exclusion reason; they carry no corpus content, so nothing requires them to be private, and holding them in scratch makes the gate unverifiable by the only people who will ever read the claim. So: coverage rows go **where the claim is made**, alongside it and in the same artifact; provenance stays in scratch and the coverage rows point at it by role, never by real path. If a line's store cannot be described without naming something private, that is a sanitization problem to solve in the row, not a reason to move the row. The round that introduced this variant records its own, so the rule is demonstrated rather than asserted:
+
+**Codex line — verdict: `covered`.** One store was read to the bottom, and what was left out is left out for a stated reason, not by omission.
+
+| store | status | depth actually read |
+| --- | --- | --- |
+| `~/.codex/memories/MEMORY.md` | `deep-read` | every session block expanded; every failure bullet read individually, not sampled |
+| `~/.codex/skills/.extraction-work/` | `read` | all artifacts present at the time, charter/closeout fields |
+| `~/.codex/sessions/` | `excluded` | not read — the distilled memory file above is already their `symptom -> cause -> fix` reduction |
+| `~/.codex/memories/raw_memories.md` | `excluded` | not read — same source as the distilled file, which is structured |
+
+**Claude Code line — verdict: `digest-only`.** Deliberately weaker, and the weakness is the point: nothing in this round may rest on this line alone.
+
+| store | status | depth actually read |
+| --- | --- | --- |
+| `~/.claude/projects/<proj>/memory/` | `digest-only` | index lines only; entry bodies not expanded |
+| `~/.claude/skills/.extraction-work/` | `read` | all artifacts present at the time, charter/closeout fields |
+
+**Enumerate the line set before you fill the rows, and record how.** A table of two lines cannot reveal a third that was never listed — the gate false-greens on omission exactly the way the parent trap does on an unenumerated corpus. So the line set is *derived from something observable*, never recalled: list the agent home directories present on the machine (`ls -d ~/.*/ ` and pick the ones carrying agent state), then add any host named in this repository's own tooling and routing that has no directory yet. Record the enumeration you ran next to the verdicts, so a reader checks the SET first and the rows second. This is the channel-taxonomy failure of variant (c) applied to agent lines: nothing masks the missing line, it was simply never in the list.
+
+The worked example below was enumerated that way, and the enumeration immediately paid for itself: run against the machine that produced this round it returned **five** agent directories, not the two the round had been working with. Three had been invisible to an author who was recalling rather than listing. Two of them (`~/.gemini`, `~/.copilot`) hold configuration and installed skills only — no session or lesson state — and drop out on evidence. The third (`~/.cursor`) is a real line carrying substantial chat state, and it earns an `excluded` row with a reason rather than silence. That is the whole point of the gate: without the enumeration the round would have claimed cross-line coverage over a set it had never established.
+
+**Name the lines and their stores.** An anonymised table (`line A`, `line B`, "a memory file") cannot be audited: a reader cannot tell which agents were enumerated, cannot spot a third line that was never listed, and cannot check a store themselves — the gate false-greens on its own example. The private part is the corpus and the project identifiers in it, not the name of the agent that produced it. Name them, and let the sanitization rules do their job on the corpus rows instead of blanking the index.
+
+**Cursor line — verdict: `excluded`, with a reason.**
+
+| store | status | depth actually read |
+| --- | --- | --- |
+| `~/.cursor/chats/` | `excluded` | not read — raw conversation state with no distilled lesson artifact anywhere under the tree, the same class as the raw transcripts excluded on the Codex line |
+| `~/.cursor/agents/` | `excluded` | empty |
+
+**`~/.gemini`, `~/.copilot` — not lines for this purpose.** Configuration and installed skills only; no session or lesson state. Recorded here because "it turned out to hold nothing" is a finding, and leaving them off the list is how the next round re-discovers them.
+
+Two things that table makes visible and prose did not. The lines are **asymmetric by store, not by sampling**: one keeps its lessons in the memory file and the other in the extraction-work directory, and the directory named the same on both holds nine times more on one line than the other. And a same-named path means different things per line, so a lookup shaped by your own layout returns nothing and reads as absence.
+
+Do NOT resolve this by building a sync or mirror between the stores. Two independently-owned stores with a one-time cross-distillation is the shape that has held here; a mirror adds a mechanism to maintain and drifts silently the first time it is not run. The obligation is coverage at extraction time, not continuous replication.
+
 ## Variant (a0) — produced-artifact + next-run-delta (relocated gate detail)
 
 **Firing point: for a task/session retrospective, this variant fires at CHARTER time — the produced-artifact row (i) enters the charter's evidence plan as its FIRST source class (see the Evidence plan field in `source-to-skill-extraction.md`), while the next-run-delta row (ii) is a separate required charter/closeout record, not a source class — not only when an exhausted/complete claim is about to be made** (the original anchor, kept as backstop). Observed failure shape of the late anchor: a 7-session program retro that never claimed "exhausted" walked past this gate entirely, took only correction turns as evidence, and landed zero method/craft lessons while r-series reports and a benchmark corpus sat unread in the project.

package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/dual-track-review-gate.md

@@ -59,6 +59,7 @@ The recurring failure: the agent declares done/covered/converged, and the *user*
 - **Independent oracle.** Where the property has no executable test — rule text, a register row, a doc — the enumeration is discharged only by an **independent oracle**: name the concrete observation that would contradict the property, say where that observation lives (the owner file and line, the primary source, the command whose output would differ), and go look. **Validate the oracle before trusting its verdict**: a check that returns "clean" because it looked in the wrong place, matched case-sensitively, used too narrow a pattern, or swallowed an error is indistinguishable from a passing property, and it fails in the dangerous direction. Before accepting a clean result you must PROVE THE CHECK CAN FAIL — point it at something you know is broken and watch it report that. Confirming it enumerated the inputs you meant is a necessary extra step, never a substitute: correct inputs say nothing about whether the predicate detects a mismatch or whether a non-zero exit was swallowed, so a check that can only ever say clean passes that weaker test. An unvalidated oracle is not weaker evidence than an imagined mutation; it is the same thing wearing a command prompt.
 - **Dimension walk.** Adding cases inside an axis you already had buys nothing against one you did not: the enumeration walks dimensions (shape / provenance-and-trust / cardinality / semantics / ordering) before values — `testing-strategy` owns that list and the precision-row obligation that goes with it. A walk whose rows are all imagined mutations is exhortation wearing a checklist's clothes.
 - **Re-owe after fixes.** Whatever you produced while fixing a previous round's findings is part of the current candidate and re-owes the whole enumeration — that newly-added mechanism is the most dangerous line in the diff, because it has no test yet and you wrote it with your attention on the defect it repairs. "The whole enumeration" includes the **pre-cover axes sweep** (concurrency & lifecycle above all): remediation text written mid-round re-owes the draft-time axes BEFORE the candidate goes back to the reviewer, because a fix written with attention on one defect systematically re-opens the same blind-spot axes the original draft missed. And the loop has an escalation point: when the same blind-spot axis or finding class supplies findings in a **third** round, stop the per-finding loop and run one full-matrix implementer self-enumeration (the artifact's own states × failure points × orderings × residues × cross-references) on the current candidate before any further external round — letting the reviewer surface one hole per round is the reviewer-as-defect-finder failure at its most expensive (observed shape: a multi-round program burned twenty-plus single-finding rounds on one axis family; the one full-lifecycle enumeration, run at the maintainer's correction, found the remaining holes in a single batch).
+- **Classify before fixing.** Persist one transition row per finding class: a stable semantic class key, its root-cause predicate, affected surface, and one disposition per occurrence. Each occurrence names the SHA-256 of its controller receipt plus the canonical JSON SHA-256 of a finding that actually appears in that receipt; the closeout must classify every controller finding exactly once. New wording or a new file is not a new class when the predicate is the same. Root-cause predicates must be unique across classes after case-folding and whitespace collapse; **only that exact normalization is mechanical**. It catches cosmetic case/whitespace key splits but does not decide whether differently worded predicates are semantically equivalent, which remains reviewer-contestable. Resolution is per occurrence, not "the last disposition wins": every `fixed`, `accepted_tradeoff`, `pre_existing_out_of_scope`, or `source_refuted` occurrence names one same-directory structured disposition-evidence file plus its SHA-256. That file binds schema version, exact current candidate, its controller receipt and finding, the disposition, a non-empty evidence list, and the ordered current/prior class occurrences it resolves. It must resolve its own occurrence; a later closing disposition that lists only itself leaves an earlier `open` occurrence unresolved until later evidence explicitly includes that exact receipt/finding pair. A `needs_human_decision` occurrence cannot be resolved by any candidate-local disposition evidence and stays unresolved until an authenticated external human/platform decision takes the separately authorized path. A controller finding disproved by first-hand source or failure-path evidence records `source_refuted`; this is a classification of an invalid finding, not a fourth disposition for a valid P0/P1. The validator binds every JSON input using duplicate-key rejection, plus the evidence file, digest, candidate, occurrence, disposition, and transition links; it does not judge the evidence text or authenticate tradeoff/scope acceptance. The reviewer or human decision-maker still owns those semantic and authority verdicts, and `ready_for_human_decision` is not approval or merge authority. On the class's third appearance, stop patching individual instances and enumerate the complete authoritative surface against that predicate. The sweep names a same-directory manifest plus its SHA-256; its candidate and exact ordered `searched_set` must match the row, and its unmatched list supplies the recorded count. `ready_for_human_decision` requires zero unresolved occurrences and zero unmatched instances; `continuation_authorization_required` and `baseline_race` retain non-zero unmatched evidence instead of lying about closure. Classification is reviewer-contestable evidence, not an author-controlled escape hatch; splitting one predicate into cosmetic sub-classes does not reset the count. `scripts/validate_extraction_review_state.py` enforces these bindings within the referenced receipt/evidence set.
 - **Graded verdict shape.** When the assessed reality is multi-dimensional or partial (capability, coverage, feasibility, quality, completion), collapsing it into one binary verdict — "done/not-done", "possible/impossible", "all correct/all wrong" — is the over-broad-absolute axis applied to your own claim layer: the swing to whichever pole feels safest to assert misrepresents a distribution, and the opposite-pole absolute ("structurally impossible", "nothing works") is the SAME defect as an unearned "done", not a humbler one. Report per-dimension status — what's strong, what's weak, what wasn't checked — with the confidence each part actually earned; and where a binary gate genuinely applies (a pass/fail check, a blocked/allowed decision), still give the clear top-line verdict after the per-dimension basis — calibration is not hedged mush. A user correcting your answers as too absolute ("每次都很绝对") is this defect's recurrence signal, same escalation as the `SKILL.md` rule states.
 - **Honesty (descriptive, not permissive).** This is recognition-dependent salience, not a mechanical gate — an agent that doesn't notice it is done-claiming cannot self-fire it; the mechanical backstops remain the closeout `interim` gates + user-signal escalation. "I didn't notice I was claiming done" does NOT waive the rule — any non-trivial completion/coverage/convergence wording must carry clean-pass evidence or an explicit interim/downscope disposition *before* you emit it. The rule targets completion/coverage/convergence assertions on work whose failure a check could catch, and never narrows the mandatory dual-track challenge (it is the always-on generalization of *self-audit to convergence*, not a replacement for the gate).
 
@@ -146,6 +147,40 @@ instance in the same session shows the same shape at reporting altitude: an empt
 output file plus a stale status snapshot were reported as "the commit did not land" instead
 of being re-read.
 
+### The claim/evidence pair table — the single most-recorded failure class
+
+**Invariant: the proof you hold establishes a DIFFERENT proposition than the one you are about to assert.** Not a weaker proof of the same claim — a sound proof of an adjacent claim. That is why it survives an honest self-check: the agent did verify something, and it was real.
+
+This is the largest class in the round-059 corpus by a wide margin. The counts below are the instances that could be attributed to a specific pair on a re-read — **71 of the 400 failure records read in that pass**, across 14 pairs. (The denominator is the size of that one READ, which is fixed and re-countable from the extraction artifact; it is not the store's current size, which grows.) A coarser class-level pass over the same corpus put the shape higher still, but that figure is not reproducible from this table and is deliberately not quoted here: a table about asserting propositions your evidence does not establish must not open with one. Read 71 as a floor. Every pair is the same sentence with different nouns, which is why patching them one at a time never converged: each fix taught the next agent about `merge` versus `release` and nothing about the shape.
+
+| You are about to claim | What your evidence actually establishes | corpus |
+| --- | --- | --- |
+| the reviewer approved it | the review lane returned no verdict (timeout, quota, auth failure, invalid output, exhausted budget) | 16 |
+| the product or the code is defective | YOUR INVOCATION of it failed — missing runner or binary, container runtime down, sandbox denial, unwritable cache, expired credential, toolchain drift | 22 |
+| released / deployed | merged | 8 |
+| runtime behavior is correct | static, contract, compile, or lint evidence passed | 5 |
+| the content is correct | the command exited 0 | 4 |
+| this produced a product effect | CI is green / the package published | 4 |
+| deletion is authorized | merging was authorized | 3 |
+| the data is physically erased | refs are clean and a fresh clone looks right | 2 |
+| there is a live incident | the code path is reachable | 2 |
+| the item is resolved | a reply was posted | 1 |
+| the capability executes | it is registered or configured | 1 |
+| the caller can read it | the caller is a member | 1 |
+| it is implemented | the plan validated | 1 |
+| the application is authenticated | the user identity is authenticated | 1 |
+
+**How to use it.** Not as a checklist — as a recognition aid at ONE moment: when you are about to write `done` / `complete` / `verified` / `ready` / `passed` / `covered`. Say out loud the proposition your evidence establishes, then say the proposition you are about to assert. If they are not the same sentence, report the one you have and name the one you do not. `merged; the release pipeline has not run` costs one clause and is true.
+
+**What a reader here can and cannot check.** The rows sum to the stated total and that is verifiable in this file. The corpus behind them is NOT in this repository and cannot be: it is per-host agent session history carrying business identifiers, and it stays in private scratch under the extraction lifecycle rules. So the counts are **provenance-bound** — reproducible by whoever holds that corpus, opaque to everyone else. Treat them as what motivated the table, never as a measurement you can audit from here, and do not build a further claim on the exact number. The table earns its keep by whether the shape is recognizable when you next write `done`, which every reader can judge without the corpus.
+
+**Why the table is a table and not a rule per row.** The rows are evidence that the invariant is real and recurrent; they are not the specification. A pair absent from this table is still the same defect — the table earns its place by making the shape recognizable, not by enumerating it. Do not extend it every time a new pair appears in the wild; extend it only when a pair recurs and the invariant alone did not catch it.
+
+**Two families collapse into this one.** The environment row above was first classified as its own class ("an environment-layer failure reported as a product finding") and the whole-document-overwrite family as another ("the write succeeded" from "the command returned success"). Both are this invariant with different nouns, and `defect-diagnosis` already owns the substantive half of the first — its red-CI cause classification and its prove-it-from-the-tool-that-owns-the-state rule. Recording them as rows rather than as new rules is the point: the count is evidence of the shape, and three parallel rules would have taught three vocabularies instead of one invariant.
+
+**Boundary.** This is about the PROPOSITION, orthogonal to `testing-strategy`'s strong/medium/weak evidence *quality* axis: a strong test can perfectly establish the wrong proposition, and that is the failure recorded here. Where a pair has an owner, the substantive rule lives there — release-versus-merge semantics with `release-coordination`, review verdicts in this gate, runtime-versus-static with `testing-strategy` — and this table only makes the class visible at the moment of claiming.
+
+
 ## When dual-track is mandatory
 
 | Extraction type | Review | Challenge |
@@ -170,6 +205,16 @@ Only the challenge pass may be skipped, and only when this table marks challenge
 - **(a) Bounded change class.** The edit changes ONLY typo, grammar, formatting, or a meaning-preserving synonym, and changes NO trigger, scope, routing, validation, acceptance, rule/threshold/boundary text, or any other meaning. Reference/body prose that states a rule, threshold, boundary, rubric, or applies/does-not-apply line IS a semantic surface — editing it is NOT wording-only unless the change is purely typo/grammar/formatting with no meaning change. A synonym substitution usually cannot satisfy (b)'s deterministic evidence bar unless the proof avoids intent/meaning judgment. Description / frontmatter is never wording-only (see below).
 - **(b) Deterministic scope check + independent review.** Dropping challenge for the edit requires a **deterministic scope check** — recorded controller-side or diff-based scope evidence that is decidable without judging intent or meaning, such as: touched files are formatting-only by formatter output; hunks are only meaning-inert whitespace / punctuation / markdown table alignment; or token-level changes are limited to a named typo correction while the surrounding rule sentence is byte-identical. If the proof depends on a human or LLM deciding whether revised prose changes a rule, threshold, boundary, applicability, or acceptance meaning, it is NOT deterministic and challenge stays required. The deterministic evidence **AND** an independent review row confirming the same must both be present. Either piece missing, or any reviewer-flagged / unconfirmed meaning / scope / trigger / routing / validation / acceptance change, **re-arms challenge + the behavioral-evidence row** (never demoted to "recommended").
 
+The executable controller proof is intentionally narrower than every edit a
+human might call wording-only. It accepts only a canonical full-context
+Markdown diff inside one existing skill and recomputes either punctuation-only
+changed lines or one named whole-token replacement with an exact count. Use the
+schema and command in `code-review/references/staged-review-contract.md`; the
+result must carry both `wording_only_scope.status=passed` and the independently
+reviewed `wording_only_boundary` concern. Other grammar/synonym edits, custom or
+context-augmented packets, multiple skills, and any unconfirmed meaning change
+take the normal challenge path.
+
 **If no such deterministic scope check can be formed for the change, challenge stays required.** This is a hard gate, not a default the author may waive: an LLM independent review is hypothesis-grade, so review alone never downgrades a non-wording change. Every shared-skill change still requires the independent review row regardless of class.
 
 If either required pass times out, returns empty output, is rate-limited, cannot access auth, exits nonzero, emits malformed or truncated output, fails JSON/shape parsing when structured output was requested, lacks evidence that the pass inspected the target diff/files, shows a prompt/tool-scope mismatch, or returns any `inconclusive` status, the dual-track gate has not passed **for that lane via that reviewer**. A *recoverable-lane* failure — auth, quota, rate limit, timeout, local cache/db failure, or missing capability — is NOT a terminal stop and is NOT "the gate is unrunnable on this host": before you record `blocked`, you MUST walk the **Primary reviewer failure** remediation ladder below and route to an approved independent third-party reviewer (preferably a different model family) — either your runtime's native multi-model subagent (e.g. an OpenCode `Task`/council subagent on a separate model) or a shell wrapper such as `opencode_review.sh --model <provider/model> --implementer-family <author-family> --mode review|challenge`. A primary CLI lacking auth is a routing trigger to that fallback lane, never a license to declare the gate unrunnable. Only after that ladder is exhausted — every approved independent reviewer probed and unavailable — do you record the row as `pending` or `blocked`, include the remediation attempted (which ladder steps were tried) and the next unblock action, and do not describe the skill change as solved, complete, landed, or fully closed. (A large reviewer INPUT can also be silently middle-truncated, not just the reviewer's OUTPUT — see **Read-coverage of large inputs** under *Sanity checks the gate must enforce*.)
@@ -202,6 +247,43 @@ Rules:
 
 ## Running the review pass
 
+### Freeze the packet against a base you have proven current
+
+A stale base puts the upstream's newer fixes into the packet **reversed**, so the reviewer raises findings against code that is already correct — findings that read as real until someone re-checks history, and that cost a full round each. Freezing and currency are **different properties and the packet owes both**: pinning to an immutable commit stops the base moving mid-read, but says nothing about *which* commit. **Five properties, mutually independent — none implies another, so walk them as a list rather than holding them as a sentence.** Every observed failure of this check satisfied four and missed the fifth.
+
+1. **Target-derived, not caller-chosen.** The landing lane's base is the landing target, derived from trusted configuration rather than an arbitrary caller-supplied `--base`. There is **no declared-intent exemption**: a declaration is author-controlled and cannot distinguish a considered pin from a stale one. A review deliberately scoped to a historical base — auditing what some past release shipped — is a separate lane whose result cannot satisfy landing review.
+2. **Confirmed against the remote that owns the landing target, not against your fetch having run.** `git ls-remote <that remote> refs/heads/<branch>` is the authority — and **`origin` is not automatically it**: on a fork, `origin` is the fork and the landing target lives on the upstream, so querying `origin` confirms a SHA from the wrong authority. Record the **remote, ref, SHA, and the moment confirmed** together; a bare SHA does not preserve which authority supplied it and cannot be audited afterwards. The output must be **non-empty** before it is compared — the command exits `0` with no output for a branch that does not exist on the remote, so a naive comparison turns "the branch is gone" into a silent pass. A fetch that fails, or that succeeds without covering that branch under the configured refspec, leaves the old `origin/<branch>` resolving to a stale commit — a remote-tracking ref is a local mirror and cannot attest to its own freshness.
+3. **Pinned to an immutable object.** Resolve that tip to a SHA, pass the SHA, and record it next to the packet hash. A ref *name* is not enough: it is mutable, so a sibling agent or background fetch between your resolve and packet construction moves it and the packet is built on a base neither recorded nor checked. Re-pin after any rebase or upstream advance mid-round.
+4. **Independent of the candidate.** The base comes from the landing-target authority, outside candidate-controlled inputs. Immutability is not independence — a candidate can commit a tuned fixture and cite its perfectly immutable SHA.
+5. **Contained in HEAD.** `git rev-list --count HEAD..<pinned SHA>` must be `0`, and nothing above implies it: the count passes while a wrapper builds from a stale local `dev` or an old SHA you supplied (a property of HEAD, not of the packet), and a correctly pinned current tip still shows the target's newer commits as *reversals* once the candidate branch has diverged. Count against the **branch tip** — not the derived base commit or a `merge-base HEAD <upstream>` (ancestors of HEAD by construction, so `0` for free), not the *local* branch (the fetch did not advance it), not a *different* branch than the real base. A non-zero count is not a note-and-continue: integrate the target first (`worktree-isolation` owns that sequence and its stale-overwrite hazard), then re-pin and rebuild. **Scoping the packet to the merge base instead does not discharge this** — a three-dot range hides the target's newer commits rather than reversing them, which fixes the reviewer-facing artifact and leaves the real gap: the candidate was never exercised against the code it will land on top of. That is the right bound for reviewing what an author wrote; it is the wrong bound for a landing candidate, whose artifact is the merge.
+
+Walking all five is a **point-in-time attestation, not a lock**: the target can advance after you confirm and pin, while the packet is being built or reviewed. That is what item 2's recorded confirmation moment is for — the verdict covers that base only. So **re-query the authority at landing time, immediately before acting on the verdict**: if its tip is no longer the pinned SHA, the review is not landing evidence until the base is re-pinned and the round re-run. Stating the consequence is not enough without that second query — nothing else would ever detect the movement. A force-push or branch deletion is the sharp case: the new tip need not contain the old one, so "it can only have moved forward" is not an assumption available to you. Do not paper over the window by re-checking harder; bound it, and say when it closed.
+
+When that check detects drift, rebuild instead of improvising: stop the reviewer
+lane; preserve the named candidate manifest/patch and the caller-owned ordered evidence rows;
+integrate the newly attested target in an isolated worktree; reapply only the
+named candidate paths/rows; regenerate derived artifacts; compare the resulting
+path set with the manifest; rerun the selected tests; then re-pin and rebuild the
+packet. Never use a broad reset plus `add -A`, which can silently absorb ambient
+work. Keep every base attestation in one ledger scoped from the first packet
+until landing or a human scheduling decision; repinning, retrying, or rebuilding
+does not reset it. Each row uses one remote/ref, a contiguous sequence, a strictly
+increasing RFC3339 confirmation time, the corresponding controller-receipt hash
+when a round consumed it, and a same-directory hash-bound file containing the
+canonical raw `ls-remote` line. A second ordered SHA change (A→B→C or A→B→A) is
+the second drift and must terminate the lane as `baseline_race`, with the
+unreviewed delta; the drift row and every later row must not map another
+controller receipt. For every non-race closeout — `ready_for_human_decision`
+and `continuation_authorization_required` alike — the final controller receipt
+must consume the latest attested SHA; later same-SHA live rechecks are allowed,
+but an unconsumed newer SHA is not reviewed evidence (a post-final-round drift
+belongs in the next round's ledger, not appended unconsumed to this one). Do not open another
+automatic rebuild after the second drift. The state validator counts these
+transitions and receipt/base associations inside the complete referenced row
+set. Keep independent work moving while a human chooses a landing window.
+
+**Until a wrapper enforces these, the caller owns them — and an unenforced obligation must at least be a recorded one.** No wrapper checks the five live-Git properties (observed 2026-08: `review_gate.sh` freezes whatever base it is handed, and neither wrapper fetches), so an agent that never loads this section can still pass a stale base. The v3 closeout validator makes referenced evidence tampering and broken round association detectable, but it cannot prove that a caller supplied every historical attestation or that the recorded `ls-remote` output is still current; candidate-local receipts are consistency evidence, not remote authority or an append-only log. Therefore **each review/challenge row carries the base attestation — remote, ref, SHA, confirmation moment — and a row without one is `base-unattested`, not landing evidence**, the caller retains the complete history across rebuilds, and item 2's live authority query is still repeated immediately before landing. Mechanising the live checks and history retention into a trusted wrapper/platform is follow-up work. This is the review-lane instance of the baseline rule in `external-practice-controls.md#designing-a-behavioral-evidence-measurement`: the packet is a measurement, and its base must be one the candidate has not moved.
+
 > **Pick the reviewer — route through the owning wrapper before hand-rolling.** The gate needs an independent reviewer; it is **tool-agnostic**. Invariants regardless of tool: prefer a model from a **different family than the author** (cross-model catches shared blind spots — it is symmetric: Claude-authored → OpenAI-family reviews, OpenAI-authored → Claude/Moonshot reviews), and treat any sign-off as **hypothesis-grade** (verify load-bearing claims against primary sources). The agent running the gate, before reviewing:
 >
 > 1. **Resolve the organization `code-review` gate first.** It owns the installed-client checks, local `CODE_REVIEW_CLIENT_ORDER`, same-family exclusion, frozen packet, timeout, egress approval, tool boundary, and verdict parsing for Claude, Kimi, OpenCode, and Codex. Do not preselect a client from `command -v` output.
@@ -214,7 +296,7 @@ Rules:
 
 Primary reviewer failure is a remediation branch only when the owning gate classifies it as candidate-local. Use this ladder separately for the review lane and challenge lane:
 
-1. Persist the owner-guided self-review, pass it through the required `--review-plan-file`, and run `review_gate.sh` once for the lane. A host-returned live `session_id`/execution handle is still that same run: poll it to terminal exit and do not start a replacement or fallback from its empty current output. Record the handle type, opaque host transcript/tool-call reference and terminal exit. If the handle is lost, the lane is infrastructure-inconclusive/manual-review-required and no replacement or fallback may be started or credited; process-tree and wrapper artifacts are diagnostic only. This is a procedural host obligation because the inner gate cannot observe the outer handle; machine enforcement requires a trusted host adapter. Never persist a credential-like raw handle in shared evidence. If Claude then returns `auth_path_unavailable`, perform the one documented host rerun with the same frozen candidate, plan, stage, and `--host-remediation-attempted`.
+1. Persist the owner-guided self-review and pass it through the required `--review-plan-file`. For non-wording extraction work, run `scripts/extraction_review_gate.sh` from round 1; a strictly proven wording-only lane uses the proof-bound generic `code-review` single-review recipe in `code-review/references/staged-review-contract.md`, without chain or completion flags. A host-returned live `session_id`/execution handle is still that same run: poll it to terminal exit and do not start a replacement or fallback from its empty current output. Record the handle type, opaque host transcript/tool-call reference and terminal exit. If the handle is lost, the lane is infrastructure-inconclusive/manual-review-required and no replacement or fallback may be started or credited; process-tree and wrapper artifacts are diagnostic only. This is a procedural host obligation because the inner gate cannot observe the outer handle; machine enforcement requires a trusted host adapter. Never persist a credential-like raw handle in shared evidence. If Claude then returns `auth_path_unavailable`, perform the one documented host rerun with the same frozen candidate, plan, stage, and `--host-remediation-attempted`.
 2. Let the gate continue only for its allowlisted candidate-local classes: missing client/provider, bounded auth failure, quota/rate limit, timeout, missing capability, or malformed model output. It records every skipped/attempted client.
 3. Packet/input/binding/tool-boundary, egress, same-family, mode, and unknown failures are not manually bypassed. A terminal result stops that lane.
 4. If the organization gate could not start at all, an approved alternate wrapper or runtime-native lane may be used only with the same bounded packet, independent family, no-write/no-exec boundary, attribution, and parseable verdict. Do not invent a one-off provider/model chain.
@@ -222,11 +304,16 @@ Primary reviewer failure is a remediation branch only when the owning gate class
 
 Do not call a manual ad-hoc run "fallback review" unless it meets the same evidence bar. Correcting a CLI argument mistake and rerunning is remediation; waiting forever, killing the process, or accepting partial stdout is not evidence.
 
-- **Open the Agent chain on the FIRST review — it cannot be retrofitted.** An extraction's required review and challenge are one tracked multi-round run, so the round budget is decided before round 1, not after reading the review; a run that starts untracked is thrown away and restarted. Every trigger, default, flag, index, prior-result, and advisory rule behind that obligation is owned by `code-review/references/staged-review-contract.md` (Agent review chain), with the runnable pair in `code-review/SKILL.md` — take the command from there and never reconstruct it from this bullet.
+- **Open the non-wording Agent chain on the FIRST review — it cannot be retrofitted.** A non-wording extraction's required review and challenge are one tracked multi-round run through `scripts/extraction_review_gate.sh`, so the round budget is decided before round 1, not after reading the review; a run that starts untracked or through the generic controller is thrown away and restarted. A strictly proven wording-only change instead uses the proof-bound single-review exception and opens no challenge chain or `complete` checkpoint. Every trigger, proof, index, prior-result and advisory rule behind those invocation shapes is owned by `code-review/references/staged-review-contract.md`, with controller options in `code-review/SKILL.md`; do not reconstruct them from this bullet.
 
 - **Compose the packet — it is the mechanism that decides which finding classes are reachable at all.** The lever and its constraints are owned by `code-review`'s `SKILL.md` (packet-bounded reviewer; `--paths` only narrows; `--diff-file` supplies a packet you assembled), including the rule that an "input insufficient to judge" finding is an input defect rather than a candidate defect. What this workflow adds is the shared-skill inclusion list: alongside the diff, carry (a) the canonical rule or contract text the changed clause must not contradict, (b) the sibling clauses in the same section or file, (c) the derived carriers that restate the change — commit message, MR body, register row, `description` surface, (d) the actual output of any gate or script the change touches. Measured over one 11-round gate on a prose-rule change, a diff-only packet surfaced only defects in the tail of the just-edited sentence; the composed packet is what surfaced cross-clause contradiction, cross-carrier drift, and silent weakening of the canonical wording. Reach for packet composition before inventing another prose rule or a wording-level grep for the same defect class, and pick between candidate mechanisms by their hit rate over the round's actual findings, not by whether they feel in scope.
 
-Standard `codex review` against the target diff:
+The following raw CLI shapes are **debugging diagnostics only**. They may help
+isolate an owner-wrapper failure, but neither output is review/challenge evidence
+and neither may replace `scripts/extraction_review_gate.sh` for a non-wording
+lane.
+
+Debug a wrapper with raw `codex review` against the target diff:
 
 ```bash
 cd <skills-repo>
@@ -262,7 +349,7 @@ Output: one finding per line with severity (P0/P1/P2), file:line, scenario, fix.
 
 ## Running the challenge pass
 
-`codex exec` with adversarial prompt (read-only):
+Debug a wrapper with raw `codex exec` and an adversarial prompt (read-only):
 
 ```bash
 timeout 540 codex exec "<adversarial-prompt>" </dev/null \
@@ -436,6 +523,31 @@ Do NOT iterate to zero *findings* — some are intentional design tradeoffs the
 
 The initial independent review plus Agent-initiated challenges share one **Agent-autonomous external-review budget of at most five rounds**. The initial review consumes round 1, so `challenge_budget` is `0..4`. Candidate edits, commits, rebases, amended plans, renamed slices, or a fresh controller invocation do not create more Agent authority. A stateless local controller cannot prove omitted history against a caller that controls its files, so the consuming workflow must preserve the complete review ledger and treat an Agent-created reset as a contract violation.
 
+Five is the generic `code-review` transport ceiling, not this extraction lane's
+spend. Non-wording Agent-autonomous extraction calls go through
+`scripts/extraction_review_gate.sh`, which fixes `challenge_budget=2`: the
+initial review plus at most two challenges. At round 3 the autonomous lane ends.
+An authenticated human may request later review, but that is separately
+attributed human-requested evidence outside this chain/budget, not an Agent
+round 4 or 5. Unused generic capacity never authorizes automatic continuation.
+The v3 closeout validator rejects referenced receipts whose recorded budget is
+not 2 and checks budget and ordering consistency within the caller-supplied
+set. It cannot authenticate that the wrapper produced those receipts or that
+the caller retained every earlier chain or receipt. The wrapper does not mint or
+persist
+`review_chain_id` or `autonomous_review_index`: the caller still supplies both,
+and could start a fresh-looking chain after round 3. The validator detects bad
+order inside the referenced set but cannot detect a prior chain the caller
+omitted, so complete caller-owned ledger retention—and treating an Agent reset
+as a contract violation—remains part of the boundary rather than a property the
+local scripts prove.
+
+A strictly proven wording-only change has no convergence loop: it uses one
+generic `code-review` pass, records the independent-review row and the
+challenge-not-required proof, and does not create a schema-v3 multi-round
+terminal ledger. This exception does not apply to frontmatter, routing,
+validation, acceptance, example, owner or behavior changes.
+
 This budget limits only automatic reviewer invocation. It does **not** stop implementation, tests, debugging, or deep self-review, and it does not limit an authenticated human:
 
 - A human may request another review or self-review, stop a live review or the overall iteration, commit, or merge. Record human-requested review separately from Agent-autonomous rounds.
@@ -457,6 +569,32 @@ At the third Agent-autonomous round, do not start a fourth automatically. If fin
 - mark findings that need product/design/risk authority as `needs_human_decision`, freeze only dependent work, and continue independent runnable slices;
 - enter `awaiting_human` only when no independent runnable work remains. This is a scheduling state, not task failure and not a human merge prohibition.
 
+The terminal checkpoint is an extraction closeout record, not a state emitted by
+`review_gate.py`, and its schema-v3 state is derived from evidence rather than
+trusted as an author assertion. Schema-v2 closeout ledgers are rejected rather
+than silently reinterpreted under the breaking occurrence/evidence shape. The
+ledger and every referenced controller, completion, base, and sweep file live
+in one directory and carry SHA-256s. The validator walks the ordered schema-v3
+controller chain (same chain and scope,
+review then contiguous challenges, packet=candidate, complete prior-result hash
+prefix, fixed `challenge_budget=2`) and binds every closeout candidate to its
+last receipt. Ready requires at least review + challenge; a second base drift may
+stop as race immediately after round 1 rather than spending an illegal challenge
+after the terminal predicate already fired.
+It ends in exactly one state:
+
+- `ready_for_human_decision`: a real `complete` receipt is `passed / self_reviewed`, binds the final external receipt and exact current candidate, and there is no unresolved finding occurrence, unreviewed delta, or unmatched sweep instance.
+- `continuation_authorization_required`: round 3 itself returned `findings / post_review_budget`; a passed/unknown/inconclusive state cannot be relabelled continuation.
+- `baseline_race`: the referenced ordered base rows contain a second SHA change, including A→B→A; there is no completion receipt and the unreviewed delta is non-empty. Open findings and unmatched sweep instances remain visible and do not prevent this stop state.
+
+Run `scripts/validate_extraction_review_state.py <closeout.json>` before reporting
+the state. This proves internal consistency and coverage of the files the ledger
+references. It does **not** authenticate that no earlier receipt/attestation was
+omitted and does not replace the live remote recheck above; the caller still owns
+complete-history retention until a trusted platform owns it. An exhausted budget,
+stale review, omitted evidence, or unknown lane state is never represented as
+convergence.
+
 ### Concrete cadence
 
 For a focused single-skill change: