@ccoalm/ccl-skills 0.1.0

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

@@ -0,0 +1,197 @@
+# Staged Review Contract
+
+The controller has three modes:
+
+- `review`: initial independent external review;
+- `challenge`: a focused adversarial external round;
+- `complete`: a local deep-self-review checkpoint that calls no reviewer.
+
+Explore/build may configure `challenge_budget=0..4`; release/high-risk requires
+at least one challenge. The initial review consumes Agent round 1, so total
+Agent-autonomous external review is at most five rounds. Human-requested review
+is outside this budget and must be attributed by the consuming trusted platform.
+The budget is a ceiling, not a quota: after a clean tracked challenge, local
+`complete` may close the chain early. It preserves unused-round count but sets
+`autonomous_review_allowed=false`; release/high-risk still requires at least one
+challenge before this early close is eligible.
+
+## Plan and owner binding
+
+The plan is optional for `review` and `challenge` and required for `complete`.
+When supplied, the bounded UTF-8 plan contains exactly intent, acceptance,
+self-review, and evidence. When omitted for review/challenge, the controller
+synthesizes a schema-valid derived default (generic intent/acceptance/evidence
+plus self-review rows covering the required concerns) and stamps
+`review_plan_source=derived-default` on the result so it is never mistaken for a
+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`.
+
+Each self-review row may name a direct sibling skill. Omission selects the
+`code-review` baseline. The controller also derives owners deterministically
+from changed `skills/<name>/` paths, test paths, and supported source extensions.
+With an implementer-supplied plan, every derived owner must have a self-review
+row before provider execution, and missing owners are incomplete self-review. A
+derived-default plan carries no implementer attestation to check against, so it
+waives that pre-attestation requirement while still selecting and loading the
+derived owners for the reviewer. The controller binds regular `SKILL.md` plus
+recursive `references/**/*.md` and reports
+`owner_selection_source=controller-derived+implementer-declared` when derivation
+participates. Linked, inaccessible, or non-regular owner/controller content is a
+terminal local integrity error.
+
+Owner-aware wrappers receive only the canonical registry root, selected names,
+and their frozen hashes. They verify that binding, use the already-installed
+CCL skill registry through each client-native mechanism, and explicitly
+name the selected owners: Claude `--plugin-dir`, Kimi `--skills-dir`, OpenCode
+`skills.paths`, or Codex `$skill-name`. Skill bodies are never copied into the
+review profile or prompt. A client unable to establish this native binding is
+ineligible for the owner-aware lane. Each successful owner-aware wrapper adds a
+post-parse `native_skill_binding=established` receipt; absence fails closed
+before the controller claims usage. Receipt injection itself is part of the
+trusted wrapper path: a local serialization or output failure is terminal
+`local_tool_failure`, never an empty or apparently successful result. After a
+valid verdict, `reviewed_skills` contains only the selected owners passed
+through the client-native invocation;
+the general `code-review` baseline remains in `selected_skills` but is not
+reported as natively invoked. The installed registry may remain visible. For
+Codex, an independently updated installed package must exist and pass the same
+safe-package validation, but its bytes need not equal an older candidate
+branch; `$skill-name` binds the selected identity. The frozen source hash still
+binds controller routing and review-chain reuse, not the host release version.
+For Claude, the public init surface must register the `ccl-skills` plugin while
+the wrapper separately verifies the selected package hashes and explicitly
+names the owners. Current init does not enumerate the selected plugin skills or
+commands; plugin registration is binding evidence, not proof that the model
+read a skill body. If init begins enumerating ccl-registry skills or
+`ccl-skills:` commands, every selected owner must appear in those lists or
+the wrapper fails closed; built-in entries alone do not imply plugin enumeration.
+An owner name that collides with an audited Claude built-in is not representable
+on this surface and is rejected before a binding receipt.
+`skill_usage_evidence` records
+native explicit invocation with `observed=false`; only a public client
+event/export may populate `observed_skill_usage`. Reviewer prose and private
+client databases do not count as observation evidence.
+
+For every client, `native_skill_binding=established` means the wrapper verified
+the frozen selected packages and emitted that client's native explicit-invocation
+syntax. It does not assert internal activation; that stronger claim belongs only
+in `observed_skill_usage`.
+
+This binding check also applies to direct wrapper calls. If a native-installed
+profile selects owners but the matching registry root or owner arguments are
+omitted, every wrapper returns terminal `binding_mismatch` before inference.
+
+Owner-aware Claude requires `--safe-mode` with the explicit `--plugin-dir`, so
+ambient customizations stay disabled while the full installed plugin supplies
+skills and normal OAuth/keychain authentication remains available. The wrapper
+must not add `--bare`, because that flag disables the ordinary OAuth/keychain
+path and turns a logged-in CLI into an auth failure unless a separate API key is
+injected.
+The Claude wrapper also validates the installed plugin manifest before launch:
+its skills entrypoint must be `./skills`, and top-level agents, commands, hooks,
+or MCP servers make the plugin ineligible for this bounded review lane.
+
+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.
+
+## Agent review chain
+
+Multi-round Agent automation supplies `review_chain_id`, a contiguous
+`autonomous_review_index` in `1..5`, and every earlier result through ordered
+`--prior-review-result-file` arguments. Prior rounds may contain findings and
+older candidate hashes; they remain consumed. Candidate edits, commits, plan
+refreshes, mode changes, and renamed invocations do not reset Agent authority.
+An initial `review` with positive challenge capacity must start this chain at
+index 1; an untracked initial review is single-round and therefore uses budget 0.
+
+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,
+risk tags, and challenge budget; chain identity is validated separately. Every
+result also carries the canonical `review_scope` object that digest is taken
+over — intent and acceptance appear only as `intent_sha256` /
+`acceptance_sha256`, never as raw plan text, because results are logged and
+archived independently of the plan. A prior result is accepted only when its
+recorded `review_scope` reproduces its own `review_scope_sha256` and that digest
+matches the current scope, so copying a digest onto a differently-scoped result
+no longer passes. This binding proves internal consistency, not authority: prior
+result files are unauthenticated, so a caller able to rewrite an entire envelope
+consistently is still accepted, per this gate's trusted-local-agent trust model.
+Envelope `schema_version` is `3`; a legacy `2` envelope predates the recorded
+scope and is rejected, which requires restarting an in-flight chain. Every
+prior round must retain the same controller digest, owner-selection source,
+selected owner names, and selected-owner digest. Missing, substituted,
+inconclusive, reordered, renamed-chain, or fourth-round input fails before any
+provider runs. Scope drift returns `review_scope_changed` and requires deep
+self-review plus explicit task reframing; it does not silently create a new
+Agent budget. An untracked challenge is one-off advisory evidence; it cannot
+enter a later Agent round or satisfy the local completion checkpoint.
+
+The controller is stateless and prevents accidental/cooperative resets only. A
+trusted host or platform must retain the ledger when hostile local callers are in
+scope; a repository-local counter cannot authenticate human authority.
+
+## Mechanical self-review gate
+
+Every stable result that reaches the gate's composite stage includes
+controller-owned `self_review_gate` (a freeze-stage argument-validation
+envelope — for example `invalid_input`, or the argument-combination variant of
+`completion_checkpoint_invalid` raised before profile freeze — carries
+`schema_version` but may omit `self_review_gate`, `review_state`, `stage`, and
+`attempts`; consumers must not read those fields unconditionally on every
+exit-2 result):
+
+- `required_triggers`: outstanding deep-self-review checkpoints;
+- `satisfied_triggers`: checkpoints validated by the current plan;
+- `blocks`: only the next external review and/or a completion claim;
+- `allowed_next_actions`: productive work that remains legal.
+
+The controller fires at these boundaries: before external review, findings
+returned, candidate change in a tracked chain, risk/scope escalation, post-budget
+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.
+
+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
+review result plus the current self-review plan, calls no reviewer, rejects stale
+candidate/controller/owner bindings and changed intent or acceptance, while
+allowing refreshed self-review conclusions and evidence, and is the Agent path to
+`completion_gated=false`. Its result preserves the verified chain id, scope,
+round index, prior-result hashes, and prior challenge focuses. It is not a human
+waiver or merge authorization.
+
+## Human and failure boundary
+
+Only an external authenticated platform action may prove human request, stop,
+resume, waiver, commit, or merge authority. A `review_waiver` clears only the
+review-process gate. A distinct exact-candidate `merge_authorization` is the
+human's final decision: CI may keep running and reporting every failed/pending
+gate, but none may block that authorized merge. Report
+`merge_authorized_by_human` / `failed_but_human_overridden`, never `passed`.
+
+Provider/input/integrity failures stop that reviewer lane, not the whole task.
+Their stable action is `stop_reviewer_lane`, never the ambiguous `stop`.
+Budget exhaustion likewise stops only automatic reviewer calls. Continue local
+fixes, self-review, tests, and independent work; park only decision-dependent
+work. Enter `awaiting_human` only when no independent runnable work remains.
+
+The current result envelope is schema 3. The controller bounds cumulative reviewer-lane execution with `--total-timeout`
+(default 2400 seconds, accepted range 5..3600). Setup time reduces the budget,
+and git preflight subprocesses share its deadline; direct filesystem reads
+remain subject to the host's outer timeout. Each client receives the smaller of the requested per-invocation
+timeout and `(remaining total budget - ten controller seconds) / maximum mode
+invocations`; review reserves two invocations and challenge one. If that
+allowance is below five seconds, the gate returns inconclusive `gate_timeout`
+and starts no later client. Each wrapper lane is separately bounded by its
+mode-adjusted allowance plus controller headroom. A lane timeout gets bounded
+TERM/KILL/final-reap cleanup and may cascade while total budget remains; killed
+or partial output is never a verdict. A verdict that arrives after total expiry
+is cleared; prior findings remain only in diagnostic `unbound_findings`, which
+must not be treated as a verdict. Before setup overhead, the practical minimum that can
+start a lane is 21 seconds for review and 16 for challenge; smaller accepted
+values intentionally fail closed.

package/dist/assets/marketplace/plugins/ccl-skills/skills/code-review/references/timeout-auth-and-capabilities.md

@@ -0,0 +1,179 @@
+# Wait Policy Details, Auth Pitfalls, And CLI Capability Notes
+
+Load this file when a wrapper run times out, returns an auth-path failure,
+or when maintaining the wrapper's CLI-flag adoption. The hard rules —
+timeout/no-output is inconclusive and never approval, auth failures are
+classified by evidence, raw `claude -p` never substitutes for the wrapper —
+live in `SKILL.md`; this file holds the operational detail.
+
+## Wait Policy
+
+Do not use a 30 second timeout as a review failure.
+
+- Around 30s with no output: wait.
+- Around 60s with no output: treat as a possible slow or broad review, not approval. Keep waiting if the process is still active.
+- For narrow diff reviews, allow roughly 2-3 minutes before calling it stuck.
+- For broad product/architecture reviews, allow roughly 5 minutes or narrow the prompt.
+- Never treat no output as "no findings."
+
+Host execution APIs may yield before the command exits. A response containing a
+live `session_id`, `cell_id`, or equivalent execution handle is a progress
+response even when its current output string is empty. Resume the same handle
+with the host's polling primitive (`write_stdin`/poll for a unified exec session,
+or `wait` for a yielded cell) until it reports a terminal exit. Do not start a
+second reviewer, enter fallback, or call the partial chunk "empty reviewer
+output" while that handle or its child process is alive. If orchestration loses
+the handle, the lane is infrastructure-inconclusive/manual-review-required and
+no replacement or fallback may be started or credited. The original PID/process
+tree and wrapper-owned result artifacts may be inspected for diagnosis only;
+they cannot reconstruct the missing terminal result or authorize continuation.
+For every yielded run, the caller's lane evidence must record the handle type,
+an opaque host transcript/tool-call reference (never copy a credential-like raw
+handle into shared evidence), and terminal exit status. If the handle was lost,
+record the lost state, any diagnostic process-tree or wrapper artifacts, and
+that fallback was unavailable.
+This is a procedural host-workflow obligation, not a controller-owned field:
+the outer host allocates the handle after launching the gate, so the inner gate
+cannot observe or authenticate it. Hosts that need mechanical enforcement must
+provide their own trusted execution adapter; this repository preserves the
+contract and evidence shape without claiming that enforcement.
+
+The wrapper default timeout is 600 seconds per formal invocation, matching the
+accepted maximum. Measured single-lane costs on this repository's own review
+diffs were roughly 89, 247, and 419 seconds, so a smaller default silently
+converts a working reviewer into an inconclusive timeout; because a timeout is
+cascade-eligible, spending wall-clock is recoverable while a premature timeout
+quietly loses that lane's verdict. Lower it explicitly with `--timeout` when a
+fast bound matters more than lane coverage. It makes no separate model behavior-probe request. Challenge makes one invocation; review and consult may make up to two only through their existing bounded result-recovery paths. The wrapper rejects timeout values below 5 seconds and clamps values above 600 seconds to 600 seconds. The bound is per invocation, not per wrapper run: an outer timeout must cover `timeout` for challenge and up to `2 * timeout` for review or consult, and must never kill the wrapper and then treat the killed output as success. With defaults, allow about ten minutes for challenge and up to twenty minutes for review or consult. If the command is still running but silent, poll the same execution handle again.
+
+The controller separately enforces a cumulative reviewer-lane budget.
+`--total-timeout` defaults to 2400 seconds and accepts 5 to 3600. Its clock
+starts before packet/profile setup, so setup consumes the budget. Git preflight
+subprocesses use the remaining deadline; direct filesystem reads are not
+preempted, so the host's outer timeout remains responsible for stuck file I/O. Before each client attempt it
+passes `min(--timeout, floor((remaining total seconds - 10) / invocation count))`
+to the wrapper. The invocation count is two for review and one for challenge,
+matching each wrapper's maximum recovery path while reserving ten controller
+seconds for wrapper overhead, cleanup, and result handling. An allowance below five seconds cannot
+satisfy the wrapper contract, so the gate returns inconclusive `gate_timeout`
+without starting another client. The
+practical minimum before setup overhead is 21 total seconds for review and 16
+for challenge; smaller accepted values intentionally produce the terminal
+fail-closed result. The controller bounds each wrapper lane by the smaller of
+the remaining total budget and its mode-adjusted invocation allowance plus the
+ten-second headroom. On lane expiry it
+terminates the process group with TERM, waits one second, then uses KILL if
+needed, and bounds final descriptor closure and reap. Cleanup is bounded but may
+finish just after the requested deadline. Partial or killed output is not
+parsed as a verdict. A lane timeout may cascade only when the cumulative clock
+still leaves the next client its minimum allowance; total exhaustion stops the
+lane. With defaults, the
+cumulative reviewer-lane bound is about 40 minutes plus cleanup/launch overhead,
+instead of the prior four-lane worst case of about 80 minutes. Callers needing a
+tighter host bound should lower `--total-timeout` and set their outer runner
+above that value plus setup and cleanup overhead. Process-group termination
+covers the wrapper and descendants that remain in its session; a descendant that deliberately creates a new session can
+escape signaling, but cannot keep the gate waiting or supply a verdict.
+
+Any timeout is an inconclusive result, not an empty-finding result. The final status must say `inconclusive` with the timeout reason so downstream review or merge state cannot treat the missing challenge as approval. If total expiry invalidates a result that already carried findings, the gate clears verdict-bearing fields and may preserve those findings only as diagnostic `unbound_findings`; downstream policy must not promote that field into a verdict.
+
+The wrapper traps TERM/INT and emits an inconclusive JSON result when the shell gives it a recoverable termination signal. SIGKILL and host crashes cannot be trapped, so callers must still treat non-zero exit without valid JSON as inconclusive/manual-review-required, never as success.
+
+### OpenCode native-skill timeout diagnostics
+
+An OpenCode review timeout after an owner-aware run has emitted stream events is
+reported as `reason: review_native_skill_stream_timeout` while retaining the
+existing `reason_code: timeout` category and cascade eligibility. The specific
+reason is evidence-scoped: selected native owner skills plus a valid event with
+a non-empty session identifier and structured stream `part.type`. Empty output,
+non-JSON bytes, and session creation without model-step progress remain the
+generic `review_timeout`; the wrapper must not infer a native-skill stall from
+the requested profile alone.
+
+On a best-effort basis, an OpenCode review-run timeout attaches a bounded
+`timeout_diagnostic` summary:
+stage, selected-skill count, capped event/log observations and byte counts,
+whether a session identifier was observed, and explicit scan-truncated flags. It
+contains no event text, stderr text, log text, session identifier, prompt, diff,
+credential, or model reply, so it can survive the private runtime cleanup
+without widening the ordinary result's evidence class.
+
+For a deeper local investigation, pass `--diagnostic-dir` with an existing,
+absolute, writable, non-symlink directory owned by the invoking user and not
+group- or world-writable, with no extended ACL. Only on a review-run timeout,
+the wrapper creates one mode-0700 child and copies the public event/export
+captures, their stderr captures, the validated agent-boundary output, and regular
+OpenCode log files as mode-0600 files. It never copies `auth.json`, credential
+links, the wrapper prompt file, or the frozen diff as standalone files; event,
+export, and log content may still contain candidate or model data. The result
+reports only the child directory name (the caller already owns the parent) and marks it
+`contains_sensitive_review_data:true`; the caller owns access, retention,
+redaction, and deletion. Credential files are not copied, but captured stderr
+and logs may themselves contain API keys, OAuth material, or other secrets; the
+caller must inspect and redact them before sharing. Files larger than 5 MiB, or
+larger than the remaining 20 MiB copied-payload budget, are skipped entirely;
+at most 5000 runtime-log-tree entries and 1000 regular log files are inspected
+for copying. The manifest and result report only that artifacts or logs were
+skipped, not a per-file list. If summary
+enrichment fails, the wrapper returns the original inconclusive timeout result
+and removes any unreported diagnostic child. No diagnostic child is created on
+success.
+Removal depends on the wrapper's exit and signal handlers. A SIGKILL or host
+crash can strand an unnamed mode-0700 `opencode-review-timeout.*` child, so the
+caller must periodically sweep unreported entries in the diagnostic parent.
+Every successfully enriched review-run timeout also carries a
+`diagnostic_artifacts` object reporting `requested` and `retained`. Requested
+retention that cannot be completed reports `error:retention_failed` with no
+directory name. Successful retention additionally reports `directory_name`,
+`contains_sensitive_review_data`, `credential_files_copied`, `retention_owner`,
+`artifacts_truncated`, and `logs_truncated`.
+Raw artifacts are diagnosis evidence only and cannot reconstruct a missing
+terminal verdict or authorize fallback, merge, or completion.
+
+## Auth And CLI Pitfalls
+
+On this machine, Claude Code and Kimi Code may be logged in locally while a
+sandboxed child cannot reach their host-owned auth paths. Classify auth failures
+by evidence, not by one invocation path.
+
+Kimi has one additional exact false-negative shape: before any model output,
+preparing the OAuth refresh lock fails with `EPERM` or `EACCES` through the
+private runtime-home binding. Preserve the whole source `credentials/` and
+`oauth/` bindings—never copy or disable that lock—and use the same single
+`--host-remediation-attempted` rerun described below. A second lock-path failure
+is `auth_unavailable_after_host_retry` and may cascade; unrelated exit-1 errors
+remain fail-closed.
+
+Codex has a separate sandbox-path false negative: its in-process app-server may
+fail before inference with exact `Operation not permitted` evidence while both
+the event stream and result file are empty. The first occurrence is
+`host_path_unavailable` and requests the same single host rerun.
+Only the marked rerun may classify a repeat as
+`host_path_unavailable_after_host_retry` and continue to another approved
+client; unrelated Codex exit-1 failures remain fail-closed.
+
+Use this bounded host-remediation procedure for either failure class:
+
+1. For Claude, run `claude auth status` first. If it reports logged in, classify the failed invocation as an auth-path false negative; use `claude --version` only to confirm the binary/version when auth status is unavailable or fails.
+2. For Codex, require the wrapper's exact pre-inference app-server `EPERM` classification with empty event/result evidence. Any non-empty inference evidence or broader exit-1 remains terminal.
+3. Confirm a real host/outside-sandbox runner is available, such as an approved unrestricted shell path in the current Codex session. Without it, keep the gate at `next_action=host_retry`; do not reinterpret the path failure as provider unavailability.
+4. Rerun the same `review_gate.sh` command through that host path with `--host-remediation-attempted`, preserving the frozen packet or unchanged base/paths, mode, focus, timeout, implementer family, and egress approval. The gate passes the bounded marker to the affected wrapper; it does not elevate itself.
+5. If the host rerun returns `auth_unavailable_after_host_retry` or `host_path_unavailable_after_host_retry`, the gate may try the next client in the effective `CODE_REVIEW_CLIENT_ORDER`, subject to the egress secret-scan tripwire (a clean packet egresses automatically; a scan hit needs `--allow-fallback-egress`). If no fallback is valid, the lane remains inconclusive. Do not manually invoke raw provider commands for review/challenge as a fallback.
+6. For Claude only, tell the user to log in again only if `claude auth status` also reports logged out, or the same wrapper command fails from the host/local login path. Never repeat host remediation for either client.
+
+Do not manually substitute a raw `claude -p` command for review/challenge after an auth false negative. Raw commands are easy to leave without the wrapper's outer timeout, JSON schema validation, untracked-file handling, and fail-closed classification; a hung or prose-only raw run remains inconclusive. The only exception is wrapper debugging in the same turn: record the wrapper bug being reproduced, edit `scripts/claude_review.sh` or its parser/tests, and do not report the raw run as a review result.
+
+For challenge mode, require `--tools ""` and the included diff packet as the whole review surface; this keeps adversarial passes bounded and avoids silent repo exploration hangs. If the installed Claude CLI does not advertise `--tools`, challenge exits inconclusive and must not be reported as passing or as no findings. The formal invocation's own stream-json init must prove the exact tool surface and empty inherited MCP/skill/command/plugin surfaces before its result can be accepted. A permission denial, unexpected tool use, missing init evidence, or schema drift fails closed; auth/quota evidence remains separately classified. If the challenge run hits an auth false negative, do not spend another Claude invocation inside the same wrapper run; report inconclusive and rerun once from the host path (optionally with `--direct`). Review mode uses the same no-tool, diff-packet-only surface. Repository consult uses `--tools Read,Grep,Glob`, `--permission-mode plan`, and `--add-dir <REPO_ROOT>`; treat those read tools as workspace scoping, not as proof that absolute-path reads are impossible, keep sensitive/harness paths outside `<REPO_ROOT>`, and fail closed if the exact positive read-only surface is unavailable. Prompt-only consult uses `--tools ""` and no `--add-dir`; it requires the needed evidence pasted into `--extra` (the legacy `--allow-prompt-only-advisory` opt-in is accepted for back-compat but no longer required), and the final JSON carries `status: "evidence_only"`, `consult_scope: "prompt-only"`, `advisory: true`, `untrusted_evidence: true`, and `gate_eligible: false` as the guard. Consult findings use scope-specific statuses: repository findings use `status: "findings"` and prompt-only findings use `status: "prompt_only_findings"`; all consult results exit `2`, all consult statuses carry `gate_eligible:false`, and prompt-only findings still require controller-side verification before they affect a landing decision. The prompt boundary is not a sandbox.
+
+Use `--no-session-persistence` for review, challenge, and prompt-only consult when `claude -p --help` advertises it. For no-tool modes (review, challenge, and prompt-only consult), use low effort when supported, because the prompt is otherwise prone to long silent reasoning. Do not enable `--json-schema` by hand for review evidence; the wrapper pairs it with `--output-format stream-json --verbose` when supported and enforces both the runtime init record and final result through its parsers. A bare `--json-schema` without structured capture can return prose or blank stdout. Model selection remains the user's Claude CLI default; the shared wrapper does not pass a model override. Avoid changing capture flags by hand, because some modes can use a different auth path.
+
+## CLI Capability Notes
+
+Current Claude Code CLIs expose capabilities that *could* harden this harness, but they are machine- and version-specific and several have fail-closed implications. These notes are **policy, not a recommendation to flip flags by hand**: a capability may be adopted only inside the wrapper, behind local help/version inspection plus fixture tests that prove the same fail-closed classification, schema validation, attribution, auth hygiene, and timeout semantics the wrapper already guarantees. This local inspection is not a model inference probe. None of this changes review *policy* — when dual-track (independent fact review + adversarial challenge) is required, the convergence standard, and the severity rubric + finding-quality bar are owned by `../skill-extraction-workflow/references/dual-track-review-gate.md` and `../skill-extraction-workflow/references/review-finding-standards.md` (sibling-skill paths, written relative to this skill's directory per repo convention); this skill owns the provider-neutral client invocation mechanics.
+
+- **`--bare` (minimal mode), when advertised**: skips hooks, LSP, plugin sync, auto-memory, background prefetches, keychain reads, and `CLAUDE.md` auto-discovery (skills still resolve), and forces Anthropic auth to be `ANTHROPIC_API_KEY` (or `apiKeyHelper` via `--settings`) — OAuth and keychain are not read. It is therefore forbidden in the normal owner-aware wrapper path, which must preserve the user's existing OAuth/keychain login through `--safe-mode` plus explicit `--plugin-dir`. Two narrow, guarded uses remain outside that normal path:
+  - **Isolation**: it can suppress ambient context the Harness Exclusion section guards against — BUT only when every safety boundary the review depends on is wrapper-owned and independently enforced. Do not use `--bare` to skip hooks/plugins that themselves enforce safety (DLP, tool-deny, audit/logging, policy/model enforcement, org prompt boundaries); confirm none of the skipped mechanisms is a required control before relying on it. Skipping ambient noise is fine; skipping a guardrail is not.
+  - **Sandbox auth**: the host/OAuth rerun remains the PREFERRED remedy for the keychain false-negative. `--bare` + `ANTHROPIC_API_KEY` is a security-sensitive last resort, not a default, because it pushes a credential into exactly the sandbox/review path this skill treats as hostile. Allowed only if the wrapper injects an ephemeral, least-privilege key through a non-logged env path, never writes it to settings, prompt files, logs, or shell history, and treats missing safe-injection as inconclusive rather than exporting a long-lived key. Do not adopt `apiKeyHelper`/on-disk secret config unless the wrapper owns and validates it.
+- **`--output-format stream-json --verbose` — ADOPTED as the default capture**: paired with `--json-schema` when local help advertises schema support and covered by fixture tests (`test_parse_review_json.sh`, `test_classify_envelope.sh`, and `test_parse_probe_result.sh`). The stream envelope is NOT the review schema, so `extract_payload` in `parse_review_json.py` unwraps `structured_output` (or the nested `result` JSON string) and rejects any envelope flagged by `is_error`, `subtype != success`, `api_error_status`, `permission_denials`, or a non-`completed` `terminal_reason`; `classify_envelope.py` turns those same fields into auth/quota/permission/error reasons. Never let the envelope's own success shape (for example `{"result": "...LGTM..."}`) be read as a passing review. The init record from this same formal stream is also the runtime tool-surface evidence; no separate model request is made.
+- **`--fallback-model`, when advertised**: auto-switches when the default model is overloaded or not available (`--print` only). When the team has an approved pinned review model, silent fallback is forbidden unless the fallback target is also explicitly approved for this harness; an unexpected fallback makes the result inconclusive / manual-review-required, not pass or no-findings. Reporting the model used preserves attribution but not approval.
+- **`--max-budget-usd`, when advertised**: caps spend per invocation, but budget exhaustion is an inconclusive output condition, not a clean stop — it can truncate generation into empty, partial, or tail-only output. The wrapper must detect a budget-limit stop reason / usage metadata where available; output produced under a hit or ambiguous cap is inconclusive. Never set a cap low enough to preempt the Output Validity rules or the Wait Policy above.

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

@@ -0,0 +1,98 @@
+# skills/code-review/scripts Agent Contract
+
+Scripts here provide bounded, provider-neutral review/challenge wrappers and
+parsers for Claude, Kimi, OpenCode, and Codex.
+
+Rules:
+
+- Preserve no-tools posture and structured output validation. A malformed,
+  timeout, or inconclusive wrapper result is not a pass.
+- **Never pin the parser to a CLI version's vocabulary.** `parse_probe_result.py`
+  gates on *shape*, not on field/value names: the isolation proof is the exact
+  `tools` allowlist plus the tool_use scan, which no init field can bypass.
+  Field-name and value whitelists were tried twice (`fast_mode_state`, then
+  `capabilities`) and both times a routine CLI release took every Claude lane
+  down while proving nothing. So: unknown init fields are tolerated when scalar
+  or empty-container, and `agents`/`capabilities` are list-of-strings checks
+  with no value vocabulary. Only `permissionMode` stays value-pinned (it widens
+  what the runtime may do with no tool added).
+- **Keep unsafe *values* out of the schema-drift class.** An unrecognized shape
+  means this lane cannot verify isolation → fallback-eligible. A known field
+  carrying an unsafe value (`permissionMode: "bypassPermissions"`) is a breached
+  boundary → terminal. They report through different reasons and different
+  buckets (`unknown_fields` vs `unsafe_values`) precisely so a real privilege
+  escalation cannot inherit the drift class's softer `next_action`. Any new
+  value-pinned field goes in `unsafe_values`.
+- When every Claude run goes inconclusive with "unrecognized surface-shaped init
+  field", the CLI added a NON-EMPTY list/dict under a name the parser does not
+  know — the one shape that could carry a new invocable surface. That reason is
+  fallback-eligible (`capability_missing`), not a terminal boundary violation,
+  so review routes to another client meanwhile. Recipe: (1) capture a normal
+  wrapper invocation and diff its formal review stream's init event against the
+  parser's known fields; do not add a separate inference probe; (2) decide
+  whether the new container is a model-invocable surface — if it is, it belongs
+  in the required-empty set, not the allowlist; (3) if it is host metadata, add
+  the name to `KNOWN_SAFE_INIT_METADATA_FIELDS` (or give it a shape check),
+  never a value whitelist; (4) add RED/GREEN fixtures to
+  `test_parse_probe_result.sh` and record the RED round in the slice's own plan
+  under `specs/` (see `specs/012-challenge-index-default/plan.md` under
+  "Test / register coverage" for the shape); (5) full dual-track before landing.
+- **A fail-closed stop must carry the evidence that justifies it.** When a lane
+  refuses to cascade *because* the output may hold a real finding
+  (`concern_evidence`), a boolean plus a fixed reason string is not enough: the
+  operator is told a finding exists but not what it says, so the documented
+  reject-and-rerun remediation runs blind and a false positive is
+  indistinguishable from a real one. Emit a bounded, line-selected excerpt
+  (`concern_excerpt.py`) — matched lines only, never the raw verdict, which may
+  echo the packet and would widen the evidence row past the class a schema-valid
+  `findings` result already persists. Wrapper run dirs are deleted on exit and the
+  gate unlinks the frozen packet, so anything not in the emitted payload is gone;
+  the OpenCode timeout path may additionally retain only its explicitly requested,
+  curated private diagnostic copy under the contract in
+  `../references/timeout-auth-and-capabilities.md`.
+  `test_concern_excerpt.sh` is the firing path; keep new stop paths covered by it.
+- **Timeout diagnostics separate portable summary from sensitive raw evidence.**
+  The ordinary payload may keep bounded counts/types/booleans needed to classify
+  a stall, but never raw event, log, prompt, diff, session-id, credential, or model
+  text. Raw OpenCode artifacts require an explicit private diagnostic directory,
+  restrictive permissions with no extended ACL, a sensitivity marker,
+  caller-owned retention, and a test proving credential bindings are excluded.
+  A requested owner profile alone
+  does not prove a native-skill stall: require positive structured stream-part
+  evidence or keep the generic timeout classification.
+- Keep review and challenge lanes distinct; do not let one satisfy the other.
+- Do not execute target-repo code or grant broad tools from the reviewer lane.
+- Parser changes need tests with positive, finding, malformed, and inconclusive
+  cases.
+- A recipe step here must never cite a repo path that does not exist in this repo — for the specs/ namespace that is now machine-checked and blocking — and a step whose target is absent is not a step, because a contributor cannot run it. Backticked paths in prose are invisible to `check-markdown-links.py`,
+  which resolves only Markdown inline-link destinations in tracked `*.md`; the
+  gap that leaves is now closed for one namespace by
+  `scripts/check-spec-references.py`, which runs in `make test` and CI and fails
+  when a backticked specs/ token does not resolve. Verify each cited path
+  resolves before landing, and when one is already dead, repoint it at what the
+  repo does rather than creating the missing target — back-filling it fabricates
+  evidence for a round nobody ran.
+- **A path TEMPLATE is not written as a citation.** That checker has no
+  exemption: a backticked token beginning specs/ must resolve, full stop, because
+  the exemption that used to carve out angle-bracket shapes produced five
+  separate bypasses and was deleted. Write a shape by naming it without the
+  prefix and leaving the prefix in prose — a `<NNN>-<slug>/plan.md` file under
+  specs/ — or put it in a fenced block. Keep the backticks: an unbackticked angle
+  bracket is swallowed as an HTML tag when the Markdown renders.
+
+Validation:
+
+- `bash skills/code-review/scripts/test_classify_envelope.sh`
+- `bash skills/code-review/scripts/test_concern_excerpt.sh`
+- `bash skills/code-review/scripts/test_claude_review_probe.sh`
+- `bash skills/code-review/scripts/test_parse_opencode_review.sh`
+- `bash skills/code-review/scripts/test_parse_probe_result.sh`
+- `bash skills/code-review/scripts/test_parse_review_json.sh`
+- `bash skills/code-review/scripts/test_opencode_review_retry.sh`
+- `bash skills/code-review/scripts/test_opencode_review_concurrency.sh`
+- `bash skills/code-review/scripts/test_review_gate.sh`
+- `bash skills/code-review/scripts/test_review_client_order.sh`
+- `bash skills/code-review/scripts/test_cli_review_wrappers.sh`
+- `python3 skills/code-review/scripts/test_kimi_packet_mcp.py`
+- `python3 skills/code-review/scripts/test_review_client_compat.py`
+- `bash skills/code-review/scripts/test_code_review_identity.sh`

package/dist/assets/marketplace/plugins/ccl-skills/skills/code-review/scripts/classify_envelope.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""Classify a non-success Claude JSON or stream-json result envelope.
+
+Reads the captured stdout on stdin. When the captured text is a JSON envelope this
+is the primary, structure-based classifier: it reads `is_error`, `subtype`,
+`api_error_status`, `permission_denials`, and the `result` error text instead of
+grepping raw CLI prose. It prints a single reason token to stdout and exits 0.
+
+Exit 1 means no JSON object/envelope was present (for example a CLI startup auth
+failure that only wrote to stderr); the caller may then use a thin stderr/text
+fallback. Exit 3 means a JSON object/envelope was present but carried no classified
+error; callers must not grep its model-controlled payload as transport diagnostics.
+
+Reason tokens printed on exit 0:
+  auth                 -> not logged in / login required
+  quota:<text>         -> rate limit / quota / api_error_status 429
+  permission_denied    -> tool permission denials present
+  error:<subtype>:<text> -> generic errored envelope
+"""
+from __future__ import annotations
+
+import json
+import re
+import sys
+
+NOT_LOGGED_IN = re.compile(r"(^|[^a-z])not logged in([^a-z]|$)|please run /login", re.I)
+QUOTA = re.compile(r"rate limit exceeded|quota exceeded|hit your limit", re.I)
+
+
+def result_text(env: dict) -> str:
+    result = env.get("result")
+    return result if isinstance(result, str) else ""
+
+
+def classify(env: dict) -> str | None:
+    text = result_text(env)
+    if env.get("permission_denials"):
+        return "permission_denied"
+    api_status = env.get("api_error_status")
+    if api_status == 429:
+        snippet = " ".join(text.split())[:200]
+        return f"quota:{snippet}" if snippet else "quota:rate limit or quota exceeded"
+    subtype = env.get("subtype")
+    errored = env.get("is_error") is True or subtype not in (None, "success")
+    if errored and NOT_LOGGED_IN.search(text):
+        return "auth"
+    if errored and QUOTA.search(text):
+        snippet = " ".join(text.split())[:200]
+        return f"quota:{snippet}" if snippet else "quota:rate limit or quota exceeded"
+    if errored:
+        snippet = " ".join(text.split())[:160]
+        return f"error:{subtype}:{snippet}"
+    return None
+
+
+def decode_result(raw: str) -> dict | None:
+    try:
+        value = json.loads(raw)
+        return value if isinstance(value, dict) else None
+    except json.JSONDecodeError:
+        pass
+    events: list[dict] = []
+    for raw_line in raw.splitlines():
+        line = raw_line.strip()
+        if not line:
+            continue
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError:
+            return None
+        if not isinstance(event, dict):
+            return None
+        events.append(event)
+    results = [event for event in events if event.get("type") == "result"]
+    return results[-1] if results else None
+
+
+def main() -> int:
+    raw = sys.stdin.read().strip()
+    if not raw:
+        return 1
+    env = decode_result(raw)
+    if env is None:
+        return 1
+    reason = classify(env)
+    if reason is None:
+        return 3
+    print(reason)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dist/assets/marketplace/plugins/ccl-skills/skills/code-review/scripts/classify_timeout_exit.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Return success only when an exit is attributable to the timeout supervisor.
+set -u
+
+[ "$#" -eq 3 ] || exit 2
+run_rc="$1"
+run_elapsed="$2"
+timeout_limit="$3"
+case "$run_rc:$run_elapsed:$timeout_limit" in
+  *[!0-9:]*) exit 2 ;;
+esac
+
+[ "$run_rc" -eq 124 ] && exit 0
+[ "$run_rc" -eq 137 ] && [ "$run_elapsed" -gt "$timeout_limit" ] && exit 0
+exit 1