@brainervirus/workit-codex 1.0.0

package/hooks/hooks.json

@@ -0,0 +1,28 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [{ "type": "command", "command": "node ${PLUGIN_ROOT}/dist/workit-hook.js" }]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [{ "type": "command", "command": "node ${PLUGIN_ROOT}/dist/workit-hook.js" }]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "matcher": "*",
+        "hooks": [{ "type": "command", "command": "node ${PLUGIN_ROOT}/dist/workit-hook.js" }]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "matcher": "*",
+        "hooks": [{ "type": "command", "command": "node ${PLUGIN_ROOT}/dist/workit-hook.js" }]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@brainervirus/workit-codex",
+  "version": "1.0.0",
+  "private": false,
+  "description": "Workit Codex CLI and desktop plugin",
+  "keywords": [
+    "agent",
+    "codex",
+    "mcp",
+    "workflow"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BrainerVirus/workit.git"
+  },
+  "bin": {
+    "workit-codex-hook": "./dist/workit-hook.js",
+    "workit-codex-mcp": "./dist/launch-mcp.js"
+  },
+  "files": [
+    "dist/",
+    ".codex-plugin/",
+    ".mcp.json",
+    "hooks/hooks.json",
+    "skills/"
+  ],
+  "type": "module",
+  "main": "./dist/launch-mcp.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun scripts/build.ts"
+  },
+  "dependencies": {
+    "@brainervirus/workit-core": "^1.0.0",
+    "@brainervirus/workit-mcp": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}

package/skills/workit-babysit/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: workit-babysit
+description: Use when a PR needs driving to merge-ready, CI is red, or the user says babysit
+---
+
+# Babysit a PR to merge-ready
+
+Babysit starts automatically on PR creation unless declined (`--no-babysit`).
+One babysitter per PR; never mutate PR topology (no rebase strategy changes,
+no force-push).
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. Declare mode: drive (fix + merge), watch (report only), or threads-only.
+2. Work the merge frontier in order: conflicts → review threads → CI.
+3. Classify CI before retry: flake (rerun once) vs stale base (verify with
+   `git merge-base --is-ancestor` before updating) vs real failure (fix).
+4. Triage bot findings skeptically: reproduce or quote code before acting;
+   invalid bots get a reasoned dismissal, never silent ignore.
+5. Batch fixes into one push wave; re-verify green after every push.
+6. Merge only when green and approved, honoring `pr` settings (squash +
+   delete branch). Stop at the human's line: never merge on explicit hold.
+
+## Completion
+
+PR merged per settings, or a status brief (frontier state, next action) when
+blocked on the human. Record evidence for fixes, findings for blockers.

package/skills/workit-behavioral-tdd/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: workit-behavioral-tdd
+description: Use when policy identifies behavior, side effects, permissions, or data handling that may change and a regression boundary is needed
+---
+
+# Behavioral TDD
+
+Test the observable behavior at a stable boundary, not the implementation shape.
+Use this method when assessment selects the `testing` dimension.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. Inspect the task requirement, current candidate, intended behavior, and real
+   verification entry point with shared `task`, `policy`, and `evidence` operations.
+2. State one behavior and its observable result. Choose the narrowest stable
+   boundary a caller or user depends on; avoid private helpers and incidental
+   representations.
+3. Write one vertical RED slice that fails for the missing behavior, run it, and
+   preserve the actual failure as evidence. Implement the smallest change, then
+   run the same slice GREEN and record its result. Close enforces the order: a
+   testing requirement with GREEN but no preceding RED evidence stays unsatisfied.
+4. Add only another slice for a distinct behavior or risk. Reconcile stale
+   evidence if the candidate changes.
+
+## Reject noisy tests
+
+- A dependency/version-pin assertion is not behavioral evidence.
+- A test that mirrors branches, private calls, or exact implementation structure
+  is coupled to internals; replace it with the public effect.
+- Duplicate assertions and tests that add no distinct failure signal are noise;
+  delete them.
+- Do not claim a passing test satisfies a different requirement.
+- Banned: tautologies (asserts what the code says, not what it must do),
+  ghost loops (assert inside a possibly-empty loop), smoke-only renders,
+  type-only or CSS-class coupling. If the test still passes when every
+  imported function returns undefined, rewrite the assertion or delete it.
+
+Use shared `evidence` operations for RED/GREEN results. Do not add a second
+lifecycle, approval chain, or test workflow outside the current task state.
+
+## Common mistakes
+
+| Mistake | Correction |
+| --- | --- |
+| "The pin changed, so assert the new string" | Exercise the affected consumer behavior. |
+| "The code is obvious" | A small vertical slice still proves the contract. |
+| Keeping a passing test after the boundary moved | Mark it stale and retest the current candidate. |

package/skills/workit-blast-radius/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: workit-blast-radius
+description: Use when a small-looking change could break something else, before close or merge
+---
+
+# Blast radius beyond the diff
+
+A small diff is not a small risk. Prove the one fact it is safe because of,
+with runnable proof — not assertion.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. List what the change touches: callers, shared state, contracts, config,
+   migrations. Grep every caller of each touched function.
+2. For each: state the one fact it is safe because of (type boundary,
+   existing test, unreachable path) plus how to run the proof.
+3. Run the proofs. Unproven claims stay labeled UNPROVEN in findings —
+   never silently treated as safe.
+4. Fix at the shared root (one guard where all callers route through),
+   not per caller.
+
+## Completion
+
+Blast-radius note in evidence or review: each risk with fact + proof
+command, or an UNPROVEN finding for what could not be proven.

package/skills/workit-challenge/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: workit-challenge
+description: Use when a proposal is ambiguous, consequential, disputed, or may hide assumptions, coupling, failure modes, or a simpler solution
+---
+
+# Challenge a proposal with a grounded grill
+
+Treat the proposal as a hypothesis. Facts are the agent's job; decisions are
+the user's. Use this method when assessment selects the `challenge` or
+`decisions` dimension.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. Ground first: inspect the task, policy, candidate, evidence, decisions, and
+   the repo docs that exist. Never ask what code or docs can answer.
+2. Diverge once, bounded: when the approach is unknown, offer 3-5 candidate
+   directions with evidence and tradeoffs in one advisory burst, without
+   critique. Record the burst as artifact evidence when it matters; the user
+   steers or mixes.
+3. Grill one question at a time: each question carries your recommended answer,
+   the facts behind it, and at least one rejected alternative. Resolve
+   dependency order and recompute after every answer — a wall of questions is
+   not an interview.
+4. Funnel every resolution: the moment a consequential choice settles, bind it
+   with a receipt-shaped question (header `Workit decision: <purpose>`, exactly
+   `approved`/`rejected`, the approved description carrying the exact content).
+   If the user already stated the choice in conversation and no receipt can be
+   minted, record it in task progress and reassess so the settled requirement
+   retires — never re-ask to mint a receipt, and never leave it for close to
+   demand.
+5. Durability: write or refresh the spec under `docs/<slug>/` only when the
+   `durable-spec` requirement fires. No glossary, no second lifecycle.
+6. Counter-case: each material recommendation carries one strongest
+   counter-case (hidden assumption, failure mode, coupling, simpler
+   alternative). Stop when a counter-case adds no new constraint.
+
+Stop at an empty frontier or three rounds; the cap is the bound. Say directly
+when the proposal is weak, overcomplicated, or solves the wrong problem.
+
+## Guardrails
+
+- Do not create a universal spec, plan, approval chain, or second lifecycle.
+- Unknowns that affect the dependent action remain unresolved until evidence or a
+  user decision closes them.
+- Use the shared operations for state and provenance; never write task metadata
+  directly.
+- An in-session counter-case is never fresh-context review; claim only what it is.
+
+## Common mistakes
+
+| Mistake | Correction |
+| --- | --- |
+| Asking what the code or docs already answer | Ground first; the user owns choices, not lookups. |
+| Listing every hypothetical objection | One strongest counter-case, then stop. |
+| Asking "what do you think?" without a recommendation | Recommend an option and explain the tradeoff. |
+| Leaving a settled choice for close to confirm | Funnel it when it resolves; progress plus reassessment if no receipt. |

package/skills/workit-debug/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: workit-debug
+description: Use when behavior is failing, surprising, contradictory, or regressed and the root cause is not established
+---
+
+# Debug the root cause
+
+Debugging is investigation, not a fast symptom patch. Use this method when
+assessment selects `root-cause-investigation` or behavior is failing without an
+established root cause.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. Inspect task scope, caller authority, candidate identity, existing evidence,
+   findings, and worker/writer state with shared `task`, `policy`, `evidence`, and
+   `finding` operations.
+2. Reproduce the failure at a stable behavioral boundary. Record observed facts,
+   inferences, and unknowns with references; trace the failing value and all
+   relevant callers before editing.
+3. State the root-cause hypothesis and the smallest in-scope fix. Write a focused
+   regression at the boundary when practical, then run RED and GREEN checks.
+4. Acquire writer authority through `writer` before mutation. Reconcile the
+   candidate, evidence, and findings after the change; investigate sibling paths
+   and stale conclusions rather than assuming the first patch worked.
+
+Honor task status, scope, revisions, and native authority gates. Do not bypass
+them for an incident, create a second lifecycle, or claim a fix from a green
+command that did not exercise the affected behavior.
+
+## Red-capable gate
+
+Never hypothesize without a loop that goes red on this exact failure. Build
+the loop first, in this order: failing test → CLI command + fixture →
+request replay → trace. Tighten it until fast, sharp, deterministic, and
+agent-runnable. No loop → stop, list what was tried, ask for the
+environment or artifact; never theorize without it.
+
+Minimise: cut one element at a time until every remainder is load-bearing;
+the minimised case becomes the regression test. State hypotheses ranked and
+falsifiable (`If <X> then changing <Y> removes it`), probe one variable at
+a time, tag debug logs for grep cleanup. Write the regression at the seam
+where the real pattern occurs — no correct seam means the finding is the
+architecture, so flag it instead of patching around it.
+
+When the host reports writer capability unavailable, do not mutate or delegate
+mutation. Continue inline only if policy and lead authority permit it;
+otherwise report the capability gap.
+
+## Common mistakes
+
+| Mistake                               | Correction                                             |
+| ------------------------------------- | ------------------------------------------------------ |
+| Patching the nearest stack frame      | Trace the input, callers, and shared cause.            |
+| Reproducing only after editing        | Capture the failure before mutation.                   |
+| Treating one passing command as proof | Verify the affected behavior and record real evidence. |

package/skills/workit-deslop/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: workit-deslop
+description: Use before opening a PR or after implementation to remove AI slop from code and prose
+---
+
+# Deslop code and prose
+
+Throughput without quality is slop. Clean it with a minimal diff — deslop
+never refactors behavior.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. Code: delete dead helpers, redundant validators, stub references, and
+   comments that restate the code. Comments die by default; keep one only
+   with proof of an unchangeable constraint, encoded structurally if cheap.
+2. Prose (PR body, spec, docs): cut filler, keep real symbol names and
+   before→after numbers. One doc, one purpose.
+3. Keep the diff minimal: deslop removes lines, never moves logic. If a
+   cleanup wants behavior change, it becomes its own tasked change.
+
+## Completion
+
+A smaller diff with identical behavior and green checks. Report lines
+removed, not lines written.
+
+Record passing check evidence linked to the `pre-pr-cleanup` requirement id
+from the current policy (`kind: check`, `result: passed`, summary naming what
+was removed). That requirement gates `hosting.pull_request` and close. If the
+change genuinely has nothing to clean, ask for an approved limitation
+decision instead of recording evidence that did not happen.

package/skills/workit-diagram/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: workit-diagram
+description: Use when a spec or plan needs a flow or architecture diagram
+---
+
+# Mermaid when needed, never by default
+
+Tables first, ASCII trees second, mermaid only when a flow or architecture
+needs it. Flowchart, sequence, state, or ER only. No renderer, no network.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Syntax rules (mermaid v11)
+
+- Fence as ` ```mermaid `, no surrounding prose inside the fence.
+- Quote node labels containing punctuation: `A["input (x, y)"]`.
+- One direction per diagram (`TD` or `LR`); keep nodes under twelve.
+- Name actors exactly as the codebase names them (real symbols only).
+
+## Verify
+
+Re-read the fence before commit: balanced quotes/brackets, every node
+reachable, labels match spec terms. If it cannot be verified by reading,
+delete it.
+
+## Completion
+
+One diagram that argues a decision, or nothing. Never a diagram suite.

package/skills/workit-green-run/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: workit-green-run
+description: Use to drive a red CI pipeline back to green, usually inside babysit
+---
+
+# The CI loop
+
+Watch, classify, fix, push once, re-verify. Host-native (`gh` / GitLab);
+never invent CI APIs.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. Read the failing checks, not the summary. Quote the failing log lines.
+2. Classify each: flake (rerun once, note it) / stale base (update after
+   merge-base check) / real failure (reproduce locally, then fix).
+3. Fix at root cause with a regression test; push one wave.
+4. Re-verify the same checks green on the new head. A fix without a
+   green re-run is not a fix.
+
+## Completion
+
+Green pipeline on the merge head, or an escalated finding with the exact
+failing logs when the fix needs the human.

package/skills/workit-handoff/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: workit-handoff
+description: Use when work must continue in another session, host, or agent after interruption, transfer, or compaction
+---
+
+# Handoff durable task state
+
+Transfer continuity, not live authority. Use this method when assessment selects
+the `durable-handoff` rule.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. Inspect the current task, scope, decisions, policy requirements, candidate,
+   evidence, findings, progress, and worker states with shared `task` and `state`
+   operations.
+2. Export the compact state through `state.export`. Preserve the objective,
+   exclusions, accepted decisions and reasons, evidence references, open gaps,
+   findings, candidate identity, blockers, and next action. Do not include
+   credentials, live writer ownership, or host authority.
+3. Import only through the destination `state.import` operation and its expected
+   workspace revision. The destination starts paused or otherwise unauthorised
+   until it observes its own host/session and reconciles stale evidence and
+   uncertain workers.
+4. Resume or continue through shared `task`, `policy`, `worker`, `writer`, and
+   `evidence` operations. Record what changed instead of copying a transcript.
+
+A handoff does not require a formal spec or plan unless those are separate
+selected requirements. Never grant destination authority from imported prose,
+create a second lifecycle, or edit task metadata directly.
+
+## Common mistakes
+
+| Mistake | Correction |
+| --- | --- |
+| Sending the whole transcript | Export compact decisions, gaps, evidence, and next action. |
+| Restoring the old writer or credentials | Re-observe authority in the destination. |
+| Calling a handoff complete without reconciliation | Recheck stale files and uncertain workers first. |

package/skills/workit-implement/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: workit-implement
+description: Use when scoped implementation, helper delegation, or checkout writer coordination is required by the current task policy
+---
+
+# Implement within authority
+
+Implement only inside the current task scope and writer boundary. Assignment is
+not launch authority, and a timeout is not proof that a worker stopped.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. Inspect task state, requirements, decisions, candidate, capabilities, and
+   current workers with shared `task`, `policy`, and `worker` operations.
+2. If a helper is useful, assign one bounded objective with allowed paths,
+   applicable requirements, evidence needed, and a stopping condition. Helpers
+   cannot change scope, record binding decisions, close or pause the task, assign
+   helpers, or resolve blockers for the lead.
+3. Observe the native session and worker state. Acquire checkout writer ownership
+   through `writer` before any product-mutating command; release it explicitly.
+   Cancellation remains uncertain until process exit or explicit recovery.
+4. Reconcile the helper report and evidence through shared operations. If required
+   delegation is unavailable, continue inline only when policy allows it and state
+   the capability limitation.
+
+Do not edit Workit metadata directly, create nested helper trees, widen paths, or
+create a second lifecycle. Read-only investigation and bounded reports do not
+grant product-write ownership.
+
+When the host reports writer capability unavailable, do not mutate or delegate
+mutation. Continue inline only if policy and lead authority permit it;
+otherwise report the capability gap.
+
+## Common mistakes
+
+| Mistake                                        | Correction                                          |
+| ---------------------------------------------- | --------------------------------------------------- |
+| "The helper timed out, so the writer is free"  | Observe exit or perform explicit recovery.          |
+| Letting a helper approve its own exception     | Return the decision to the lead/user.               |
+| Running a build while another writer is active | Treat builds and tests that mutate state as writes. |

package/skills/workit-mockup/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: workit-mockup
+description: Use when a UI decision needs sketching before implementation
+---
+
+# ASCII mockups before UI code
+
+Sketch, don't build. Three genuinely different layout hypotheses maximum,
+ASCII only, no code output.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. Fix a legend (`┌─┐ │ └─┘ ░ ≈ [ ] ( )`) and keep sketches 60-80 cols,
+   8-20 rows.
+2. Per hypothesis: regions, component reuse vs new (named against the
+   existing codebase), empty/loading/populated/error states, nav flow.
+3. Ask at most one clarifying question, then recommend. Flag hi-fi
+   escalation when ASCII cannot settle it (density, motion, brand).
+
+## Completion
+
+The sketch plus the decision lands in the spec dir. Throwaway by design.

package/skills/workit-plan/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: workit-plan
+description: Use when dependencies, sequencing, coordination, or resumption make durable next actions useful
+---
+
+# Plan useful coordination
+
+Use a compact plan when assessment selects `artifacts` or `continuity`. A plan
+organizes work; it is not a second lifecycle or a prerequisite for implementation.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. Inspect current task state, scope, decisions, requirements, candidate, workers,
+   findings, and blockers through the shared `task` and `policy` operations.
+2. Record only the useful sequence: objective, dependency, bounded task, evidence
+   needed, owner, and next action. Keep the plan against the existing system.
+3. If policy separately requires a durable specification, record that behavior
+   agreement; otherwise do not invent a spec. A plan without a spec is valid.
+4. Update the shared task progress at meaningful boundaries. Reassess when facts,
+   dependencies, or scope change; preserve unresolved blockers and decisions.
+5. On steering (new instructions mid-task): apply `workit-steer` — park state
+   verbatim, classify same-task / new-task / quick-question, handle, re-anchor.
+
+Use shared task/progress and evidence operations. Do not create a universal
+spec-and-plan ceremony, duplicate task state, approval chain, or custom status
+machine. A short paragraph is enough when it captures the required continuity.
+
+## Triage (automatic)
+
+Set assessor signals from size facts, not memory (`triageTier` /
+`triageSignals` in policy-resolver):
+
+- **Large → spec + full plan:** new/changed observable behavior, open
+  ambiguity, cross-package/host contract or auth/data/security surface,
+  irreversible migration, or ≥3 subsystems / ≥2 packages touched.
+- **Medium → compact plan-only** (Sequence/Acceptance, ~30-60 lines): known
+  approach, single subsystem, 2-8 steps. Step count alone never escalates
+  a known single-subsystem run to spec.
+- **Small → neither** (progress + evidence only): single bounded mechanical
+  action, no open choices, reversible. Record `Spec: none (reason)`.
+
+`task.start` + `policy.assess` stay mandatory at all sizes. The lead may
+re-tier with the reason recorded in progress (override, never silent).
+
+## Decomposition
+
+Slice tracer bullets, not layers: each plan task crosses the necessary
+layers to a small demoable behavior with its blocking edges declared.
+Wide refactors use expand–contract (add the new seam, migrate callers,
+delete the old). Per task record Files (create/modify/test, exact paths),
+exact commands with expected output, and one commit. No placeholders —
+an implementer must be able to execute a task with zero extra context.
+
+## Common mistakes
+
+| Mistake | Correction |
+| --- | --- |
+| Writing a full packet for a small dependency | Capture the next bounded action and its evidence. |
+| Treating the plan as authority | Authority remains in task scope, decisions, revisions, and caller provenance. |
+| Copying a transcript into the plan | Preserve decisions, gaps, blockers, and next action only. |

package/skills/workit-review/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: workit-review
+description: Use when policy requires fresh-context review of a candidate or when an independent correctness and regression check is requested
+---
+
+# Review a candidate
+
+Review the real candidate in a stable context. A review is evidence about the
+current candidate, not an author's success summary.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. Pin or identify the candidate revision before reading conclusions. Inspect the
+   task objective, scope, constraints, accepted decisions, changed files, and
+   actual checks through shared `task`, `evidence`, and `policy` operations.
+2. Examine intent, correctness, regression risk, security or data consequences,
+   and project standards. Use the actual diff and check output; do not infer
+   evidence from a claim.
+3. Record each concern as a `finding` claim with its affected scope and candidate.
+   Investigate it: reproduce or trace the consequence, then fix in scope, dismiss
+   with evidence, defer with a reason, or ask the user about a real tradeoff.
+4. Reconcile conclusions when the candidate changes. Run one substantive review
+   and targeted rechecks; do not cycle reviewers indefinitely.
+
+If the required independent context is unavailable, record the review method as
+`unavailable` and preserve the gap. Same-session self-review is not independent
+review and must not be relabeled as verified.
+
+Use shared `evidence` and `finding` operations. Do not create a parallel review
+lifecycle, universal review panel, or direct metadata files.
+
+## Two axes, pinned
+
+Pin the fixed point first (`git diff <base>...HEAD` plus log); review that
+candidate only. Judge on two axes, never merged or reranked:
+
+- **Standards:** repo standards plus a smell baseline (mysterious name, long
+  method, duplicated logic, refused bequest, and kin); repo rules override
+  the baseline; judgement calls only, never tooling-enforced nits.
+- **Spec:** does the diff implement the originating spec/requirement
+  faithfully — missing, creep, or wrong, quoting the spec line.
+
+Every finding needs proof: the changed hunk, a failing/passing test ref, or
+a before/after. Causal disposition decides the outcome: introduced or
+worsened behavior gets fixed; pre-existing issues become follow-ups;
+inconclusive claims escalate, never silently pass.
+
+## Common mistakes
+
+| Mistake | Correction |
+| --- | --- |
+| Reviewing the summary instead of the candidate | Start from the stable candidate and real refs. |
+| Treating every comment as a defect | Investigate the claim and consequence first. |
+| Calling self-review independent | Preserve an unavailable capability gap. |