@haposoft/cafekit 0.16.7 → 0.18.1

package/src/claude/skills/code-review/references/verification-gate.md

@@ -1,46 +0,0 @@
----
-name: verification-gate
-description: The Iron Law of Proof. Prohibits reporting a 'PASS' status without providing concrete execution proofs (like exit code 0 or successfully passing tests).
----
-
-# Verification Gate: The Iron Law of Proof
-
-In the Hapo ecosystem, words are cheap. Code that "looks right" to an AI can easily break in production. This reference defines the strictest, most uncompromising rule for Code Review.
-
-## 1. The Iron Law
-**You MUST NOT issue a final verdict of PASS unless you hold concrete, verifiable execution proof.**
-
-## 2. Hallucination Block
-Never use the following phrases or implications to assess code functionality:
-- "The code looks good."
-- "The logic seems sound."
-- "This should work as expected."
-- "There are no obvious errors."
-
-If you have not compiled it, ran it, or seen it pass tests, **you do not know if it works**.
-
-## 3. Accepted Proofs of Execution
-To clear the Verification Gate, you must cite one of the following concrete proofs in your report:
-
-- **Test Suite Logs:** Output showing tests ran and passed (e.g., `PASS src/components/Login.test.tsx`).
-- **Compilation/Build Status:** Terminal output proving the typescript compiler (`tsc`) or bundler succeeded with `Exit code: 0`.
-- **Linter Completion:** Output proving no syntax errors exist.
-- **Multimodal Visual Evidence:** `cf:ai-multimodal` when installed, or another available runtime visual capability; otherwise report visual parity as `UNPROVEN`.
-
-For Specs v2, accepted proof must be persisted by the test owner at
-`receipts/<task-basename>.md`; legacy `## Evidence` remains fallback-only. The
-receipt includes identity/path, exact command, exit/result, expected versus
-observed behavior, applicable negative/reachability/artifact proof, and bound
-Base/Head. Final integration uses `feature-receipt.md`. Missing final receipt is
-normal before closeout, but mandatory at closeout. Neither receipt grants
-approval, readiness, audit status, or product semantics.
-
-For v2.1, the semantic receipt is reviewed input, not execution proof. It binds
-exact criteria and counterexamples shaped as `criterion`, `case_kind`,
-`scenario`, `expected`, `decision_refs`, and `verification_ref`. Deterministic
-validator success is never a semantic-review verdict.
-
-## 4. How to Handle Missing Proof
-If you are asked to review a PR or commit and no execution proof is available:
-1. **Return `BLOCKED`** and name missing commands, artifacts, permissions, or environment access.
-2. Do not issue `PASS`, do not downgrade to a tentative pass, and do not blind-retry. Resume only after proof arrives.

package/src/claude/skills/delegate/SKILL.md

@@ -1,124 +0,0 @@
----
-name: cf:delegate
-description: "Delegate implementation tasks from Claude Code to external CLI agents (Codex or Grok). Covers task-brief authoring, non-interactive dispatch, permission setup, background monitoring, resume, and independent verification of the returned work."
-user-invocable: true
-when_to_use: "Invoke when the user asks to assign/offload a coding task to codex or grok, or to run work on an external agent CLI."
-category: orchestration
-keywords: [delegate, codex, grok, external-agent, offload, assign]
-argument-hint: "<codex|grok> <task-description | path/to/task-brief.md>"
-metadata:
-  author: haposoft
-  version: "1.0.0"
----
-# Delegate to External Agents (Codex / Grok)
-
-Dispatch a well-scoped implementation task to an external agentic CLI — **Codex** (OpenAI) or **Grok** (xAI Grok Build) — from a Claude Code session acting as orchestrator. Claude Code stays responsible for: writing the task brief, choosing safe permissions, monitoring, and **independently verifying** the result before reporting completion.
-
-**Mantra:** Brief precisely, sandbox tightly, verify independently.
-
-## When to Use
-
-- User explicitly asks to hand a task to codex/grok ("giao cho codex", "assign to grok").
-- Parallel workstreams: Claude Code keeps orchestrating while an external agent implements a scoped task.
-- Cross-checking: a second model implements or reviews independently.
-
-Do NOT delegate: tasks touching secrets/`.env`, deploys to shared environments, destructive migrations on live data, or tasks whose scope is still unclear (clarify first — a vague brief wastes an entire agent run).
-
-## Workflow
-
-### 1. Write the task brief (mandatory, file-based)
-
-External agents run **fresh-context** — they see none of your conversation. Write the brief to a file (convention: `plans/<slug>-task.md` in the target repo), never inline-only. Follow the orchestrator prompt rules (`.claude/rules/orchestrator.md`): the brief must be self-contained.
-
-Required sections:
-
-```markdown
-# Task: <title>
-
-> Self-contained brief for a fresh-context agent. Date: <YYYY-MM-DD>.
-> FOUNDATION: <state of the working tree the agent builds on — branch,
-> uncommitted changes it must NOT revert, verified test/build status>
-
-## Context        — project, architecture, why this task exists
-## Scope          — numbered work items with exact file paths
-## Constraints    — what must NOT be touched (staging data, .env, deploys,
-                    unrelated refactors); repo rules to obey (CLAUDE.md)
-## Completion Criteria — verifiable, numbered
-## Evidence required   — exact commands whose output proves completion
-```
-
-Rules of thumb:
-- Name exact files and line-level anchors where known; agents burn tokens rediscovering what you already know.
-- State dependency order explicitly if this task builds on another agent's uncommitted work ("do NOT revert/stash existing changes").
-- Put user-pending decisions in Constraints as forbidden actions (e.g. "do NOT touch staging rows until user confirms").
-
-### 2. Protect the working tree
-
-Before dispatch, snapshot state you cannot afford to lose:
-
-```bash
-git stash push -u -m "backup: <reason>" && git stash apply -q   # snapshot, keep tree intact
-```
-
-Prefer isolation when the task is risky or parallel to other edits:
-- Grok: `--worktree=<name>` (built-in).
-- Codex: run with `-C <worktree-dir>` after creating a git worktree yourself.
-
-If the agent must build on uncommitted changes, isolation is not possible — use the stash-backup pattern above and say so in the brief.
-
-### 3. Dispatch
-
-Load the matching reference for exact flags, permission model, and pitfalls:
-- **Codex:** `./references/codex-delegation.md`
-- **Grok:** `./references/grok-delegation.md`
-
-Common principles:
-- Run non-interactive/headless mode in a **background** shell; both CLIs stream progress to stdout.
-- Grant the **minimum** permission set that lets the agent write code and run its Evidence commands (npm/node). Never grant full-access/bypass modes for routine tasks.
-- Model/effort overrides: pass explicitly rather than relying on user config, so the run is reproducible.
-- Capture the output file path; check progress after ~20–30s to confirm the agent actually started (auth errors, bad flags, and permission blocks surface early).
-
-### 4. Monitor
-
-- Poll the background output periodically; look for permission-block messages — both CLIs degrade to "design-only" output instead of failing loudly when a write tool is blocked.
-- If blocked on permissions: **resume the same session** with corrected flags (both CLIs support resume; see references) — context is preserved, work continues instead of restarting.
-- Apply the 3-strike rule from `.claude/rules/orchestrator.md`: same failure 3+ times → stop, escalate to user with evidence.
-
-### 5. Verify independently (non-negotiable)
-
-External-agent claims are **not** evidence (CLAUDE.md: no completion claim without fresh proof from the current run). After the agent reports done:
-
-1. `git status` / `git diff` — confirm the changed file set matches the brief's Scope; flag out-of-scope edits.
-2. Run the brief's Evidence commands yourself (tests, build). The agent's transcript of a test run does not count.
-3. Check Completion Criteria one by one.
-4. Report to user: what was delegated, what came back, verification results, and any deviations.
-
-### 6. Sync
-
-- Keep the brief file updated (checklist ticks / blockers) so it doubles as task state.
-- If a spec (`specs/<slug>/`) governs the work, follow the Tollgate Protocol (`.claude/rules/state-sync.md`): update `spec.json` + task files only after verification passes.
-- The user decides commit/merge/deploy — delegation ends at verified working-tree changes unless told otherwise.
-
-## Choosing Codex vs Grok
-
-Both are capable general coding agents; prefer the one the user names. If unspecified:
-
-| Factor | Codex | Grok |
-|---|---|---|
-| Isolation | manual git worktree + `-C` | built-in `--worktree=<name>` |
-| Structured output | `--output-schema` (JSON Schema) | `--json-schema` |
-| Self-verification | ask in the brief | `--check` flag appends a verify loop |
-| Resume | `codex exec resume <id>` | `grok --resume <id>` |
-
-## Rules
-
-- Never grant `--dangerously-bypass-approvals-and-sandbox` (codex) or `bypassPermissions` (grok) for routine delegation.
-- Never let an external agent touch `.env`, secrets, staging/production data, or run deploys.
-- Never report the agent's own success claim as completion — verify first.
-- Never re-dispatch a blocked task unchanged (BLOCKED ≠ retry; fix the cause: permissions, context, or scope).
-- One writer per file set: don't run two agents (or an agent + yourself) editing the same files concurrently.
-
-## References
-
-- `./references/codex-delegation.md` — Codex CLI: exec mode, sandbox/approval model, resume, pitfalls
-- `./references/grok-delegation.md` — Grok CLI: headless mode, worktree, permission rules, resume, pitfalls

package/src/claude/skills/delegate/references/codex-delegation.md

@@ -1,71 +0,0 @@
-# Delegating to Codex CLI
-
-Verified against codex-cli 0.144.4 (2026-07). Re-check `codex exec --help` if flags fail — the CLI evolves quickly.
-
-## Preflight
-
-```bash
-which codex && codex --version        # installed?
-codex doctor                          # auth + runtime health (slow; run only when suspicious)
-```
-
-User-level defaults live in `~/.codex/config.toml` (`model`, `model_reasoning_effort`, agents, MCP servers). Overrides via `-m` and `-c key=value` beat config — pass them explicitly for reproducible runs.
-
-## Non-interactive dispatch: `codex exec`
-
-Reads the prompt from an argument, or from **stdin** when the argument is `-`. Prefer stdin + brief file:
-
-```bash
-codex exec \
-  -m gpt-5.6-terra \
-  -c model_reasoning_effort='"max"' \
-  --sandbox workspace-write \
-  -o /tmp/codex-last-message.txt \
-  - < plans/<slug>-task.md
-```
-
-Run it in a background shell and poll the output.
-
-### Key flags
-
-| Flag | Notes |
-|---|---|
-| `-m <model>` | model ID, e.g. `gpt-5.6-terra` (note spelling: *terra*) |
-| `-c model_reasoning_effort='"max"'` | TOML-parsed value — keep the inner quotes |
-| `--sandbox <mode>` | `read-only` \| `workspace-write` \| `danger-full-access` |
-| `-o <file>` | write the agent's final message to a file — easiest completion check |
-| `-C <dir>` | working root (use for delegating into a git worktree) |
-| `--add-dir <dir>` | extra writable dirs alongside the workspace |
-| `--output-schema <file>` | JSON Schema constraining the final response |
-| `--json` | JSONL event stream on stdout (machine parsing) |
-| `--ephemeral` | don't persist session files |
-
-### Pitfalls
-
-- **`-a` / `--ask-for-approval` is TUI-only.** `codex exec` rejects it (`error: unexpected argument '-a' found`). Exec mode is implicitly `approval: never` — sandbox mode is your only control there.
-- **`workspace-write` limits writes, not reads**, to: workdir, `/tmp`, `$TMPDIR`. Network is available. Commands needing writes outside (global installs) will fail — keep Evidence commands repo-local.
-- **Effort value is TOML**: `-c model_reasoning_effort='"max"'` (double-quoted inside single quotes). Bare `max` may parse as a literal string too, but the quoted form is unambiguous.
-- Startup banner echoes `model:`, `reasoning effort:`, `sandbox:` — **verify these lines** ~20s after dispatch instead of assuming flags took effect.
-- User config may define agents/hooks/MCP servers that activate automatically; `--ignore-user-config` gives a clean run if they interfere.
-
-## Monitor & verify liveness
-
-```bash
-# ~20-30s after dispatch: banner shows model/sandbox; then agent narration follows
-head -c 1200 <output-file>
-tail -c 1500 <output-file>            # progress
-cat /tmp/codex-last-message.txt       # exists → run finished; content = final report
-```
-
-## Resume
-
-```bash
-codex exec resume --last "<follow-up>"          # most recent session
-codex exec resume <SESSION_ID> "<follow-up>"    # by id (session id printed in banner)
-```
-
-Use resume (not a fresh dispatch) when: permission-blocked mid-run, follow-up fixes after your verification failed, or continuing a design into implementation.
-
-## Review mode
-
-`codex review` (or `codex exec review`) runs a non-interactive code review of the current repo — useful as an independent second-opinion pass on another agent's diff.

package/src/claude/skills/delegate/references/grok-delegation.md

@@ -1,84 +0,0 @@
-# Delegating to Grok CLI (Grok Build)
-
-Verified against grok 0.2.101 (2026-07). Re-check `grok --help` if flags fail.
-
-## Preflight
-
-```bash
-which grok && grok --version
-grok models          # available model IDs
-```
-
-## Non-interactive dispatch
-
-Two forms:
-
-```bash
-# single-turn from a brief file (preferred for delegation)
-grok --prompt-file plans/<slug>-task.md \
-     --worktree=<slug> \
-     --check \
-     --permission-mode acceptEdits \
-     --allow "Bash(npm:*)" --allow "Bash(node:*)" \
-     --output-format plain
-
-# short single-turn prompt
-grok -p "<prompt>"
-```
-
-Run in a background shell and poll the output.
-
-### Key flags
-
-| Flag | Notes |
-|---|---|
-| `--prompt-file <path>` | single-turn prompt from file |
-| `-p, --single <prompt>` | single-turn inline prompt |
-| `--worktree=<name>` | built-in git worktree isolation (grok-managed; see pitfalls) |
-| `--check` | appends a self-verification loop (headless only) — use it |
-| `--permission-mode <mode>` | `default` \| `acceptEdits` \| `auto` \| `dontAsk` \| `bypassPermissions` \| `plan` |
-| `--allow "<RULE>"` / `--deny "<RULE>"` | permission rules, Claude Code syntax: `Bash(npm:*)`, `Write`, `Edit` |
-| `-m <model>` / `--reasoning-effort` | model + effort overrides |
-| `--max-turns <N>` | hard cap on agent turns |
-| `--json-schema '<schema>'` | structured final output |
-| `--output-format plain\|json\|streaming-json` | headless output format |
-| `--resume <SESSION_ID>` | continue a session (context preserved) |
-| `--best-of-n <N>` | run task N ways in parallel, pick best (headless) |
-
-## Permission model — the #1 pitfall
-
-`--permission-mode acceptEdits` **does not reliably unblock file writes in headless runs**; grok may report "Write tool blocked" and quietly degrade to a **design-only** response that reads like progress. It still exits 0.
-
-Mitigations:
-- Add explicit allow rules for write tools on the first dispatch: `--allow "Write" --allow "Edit" --allow "StrReplace"` alongside `--allow "Bash(npm:*)" --allow "Bash(node:*)"`.
-- After ~30s, grep the output for `blocked`/`chặn` — catch degradation early.
-- If the run finished design-only: **resume the same session** with widened allows and an explicit apply instruction; grok picks up its own design and implements without re-exploring:
-
-```bash
-grok --resume <SESSION_ID> --no-plan \
-     --permission-mode acceptEdits \
-     --allow "Write" --allow "Edit" --allow "StrReplace" \
-     --allow "Bash(npm:*)" --allow "Bash(node:*)" \
-     --check -p "Continue: apply the designed changes, run tests, report results."
-```
-
-Even with allows granted, shell may still be policy-restricted (runs finish with "npm test BLOCKED — shell not pre-approved"). That's fine: **you run the Evidence commands yourself during verification** — do not loosen to `bypassPermissions` just to make the agent self-verify.
-
-## Worktree pitfalls
-
-- `--worktree=<name>` worktrees are **grok-managed**: they may not appear in the target repo's `git worktree list` and `grok worktree list` may still say "No worktrees found". **Do not trust either listing** — after the run, check `git status` in the main repo to find where changes actually landed. In practice (0.2.101, resumed sessions) grok can write **directly into the main working tree** despite the flag.
-- Consequence: always take a stash-backup snapshot before dispatch (`git stash push -u -m "backup: ..." && git stash apply -q`), and treat the main tree as potentially modified.
-
-## Session management
-
-```bash
-grok sessions list                      # ids + summaries
-grok --resume <SESSION_ID> [flags] -p "..."   # continue with same context
-grok export <SESSION_ID>                # transcript as Markdown
-```
-
-## Quirks
-
-- Grok reads the target repo's `CLAUDE.md` and obeys it (including tone rules) — repo constraints apply automatically, but so do repo-wide bans; account for that in the brief.
-- `--check` produces a self-verification section in the final report — useful signal, **not** a substitute for your independent verification.
-- Exit code 0 means the CLI ran, not that the task succeeded. Judge by diff + your own Evidence runs.

package/src/claude/skills/hotfix/SKILL.md

@@ -1,289 +0,0 @@
----
-name: cf:fix
-description: "Use when asked to FIX a bug, error, test failure, CI/CD issue, type error, lint error, log error, UI issue, or code problem. Uses cf:debug for evidence-first diagnosis before any code change."
-user-invocable: true
-when_to_use: "Invoke to fix a bug or failure with scout-first diagnosis before change."
-category: dev-tools
-keywords: [hotfix, fix, bug, diagnosis]
-argument-hint: "[issue] --quick|--parallel|--from-debug"
-metadata:
-  author: haposoft
-  version: "2.0.0"
----
-# Fix — root-cause repair workflow
-
-Fix the diagnosed root cause, prove the fix with fresh evidence, and leave no
-side effects. Evidence first, fix second.
-
-## Arguments
-
-- `--quick` - Reduced-depth path for trivial issues (lint, type errors, syntax); still scout-first
-- `--parallel` - Fix independent issues concurrently, only through the Delegation Gate below
-- `--from-debug` - Start from an existing `cf:debug` report and validate its contract before accepting it
-
-Default: deterministic scout-first fix. There is no initial mode selection step.
-
-## Proportional depth
-
-Choose the smallest adequate depth from the diagnosed evidence. Depth vocabulary
-follows `cf:debug`:
-
-- **Quick/local:** one deterministic syntax, lint, type, or isolated-test failure
-  with obvious local scope. Quick mode only reduces depth; it never skips scout, pre-fix evidence, diagnosis, or before/after verification.
-- **Standard:** a diagnosed root cause inside one bounded area. Fix plus a
-  regression test that fails without the fix and passes with it.
-- **Incident/deep:** production impact, multiple components, intermittent
-  behavior, data/security risk, or concurrency. Consume the full Incident/deep
-  debug handoff (timeline, elimination path, recurrence candidates), implement in
-  stages, and verify each stage.
-
-Depth changes evidence breadth, never the gates: scout, diagnosis, before/after
-proof, and the side-effect gate apply at every depth.
-
-## Bounded repair frame
-
-Quick/local does not add a separate framing ceremony when the issue and diagnosis
-already establish the repaired behavior and proof. For Standard or Incident/deep,
-or whenever scope or risk remains ambiguous after diagnosis, record four short
-fields before choosing an implementation:
-
-- **Outcome:** the observable repaired behavior.
-- **Constraints:** compatibility, safety, ownership, rollout, and time boundaries.
-- **Non-goals:** adjacent behavior the repair must not absorb.
-- **Acceptance:** the exact reproduction plus broader evidence that proves completion.
-
-Derive repository-owned facts from scout and diagnosis. Ask the user only for a
-missing user-owned decision that could materially change the repair. This frame
-does not select a solution, widen the issue into feature work, or run before the
-root cause is proven.
-
-<HARD-GATE>
-Do not propose or implement a fix before Steps 1-2 (scout + diagnosis) complete.
-A symptom patch without a diagnosed root cause is a failed fix.
-The exact root-cause contract in Step 2 is mandatory; answer each field in one concrete sentence.
-An answer containing 'probably', 'I think', 'something with', or 'maybe' is not an answer; gather evidence instead.
-If 3+ fix attempts fail, stop, question the architecture, and discuss with the user.
-</HARD-GATE>
-
-<HARD-GATE-SCOUT-FIRST>
-Fix always scouts before asking broad clarification questions, forming hypotheses, or changing files.
-Collect these scout outputs first:
-1. Project type, language(s), framework(s), and package/test runner from repo files.
-2. Exact file(s) where the symptom surfaces and their direct callers/dependents.
-3. Related tests covering the affected area.
-4. Recent commits touching affected files: `git log --oneline -10 -- <affected-files>`.
-5. Existing patterns/conventions for this kind of fix.
-Then state a concise 3-6 bullet codebase-context summary before Step 2.
-Do not ask generic questions before this step unless there is no repo, no error text, and no observable artifact to inspect.
-</HARD-GATE-SCOUT-FIRST>
-
-<HARD-GATE-NO-SIDE-EFFECTS>
-The fix is not done until Step 5 proves:
-1. The original symptom no longer reproduces with the exact pre-fix command/user flow.
-2. Modified files and transitively affected modules still pass relevant tests.
-3. Blast-radius workflows have no business-logic regression.
-4. No new lint/type/build errors were introduced.
-5. Public contracts are unchanged unless intentionally called out: function signatures, exported types, response shapes, DB schemas, env vars.
-
-If verification reveals a side effect or regression, stop and present 2-4 concrete options to the user:
-- Revert this fix and try a different root-cause angle
-- Keep the fix and update <dependent files> to match the new contract
-- Narrow the fix to <subset> so the regression disappears
-- Accept the change — the old behavior was itself a bug
-Do not silently patch around the regression.
-</HARD-GATE-NO-SIDE-EFFECTS>
-
-## Delegation Gate
-
-Dispatch subagents (parallel scouts, hypothesis tests, deep research, or
-`--parallel` fix trees) only when all three conditions hold:
-
-- The user explicitly requested or permitted delegation or parallel agents.
-- The active runtime exposes an Explore/delegation capability.
-- The work splits into at least two distinct, non-overlapping scopes with useful independent work.
-
-Otherwise continue sequentially in the main agent with focused local evidence.
-Task-tracking tools are an optional visibility fallback, never a required step;
-a concise markdown checklist is always sufficient.
-
-## Process Flow
-
-```mermaid
-flowchart TD
-    A[Issue Input] --> B[Step 1: Scout via cf:scout]
-    B --> C[Step 2: Diagnose via cf:debug]
-    C --> D[Step 3: Select Depth]
-    D --> E[Step 4: Implement Fix]
-    E --> F[Step 5: Verify + Prevent]
-    F --> G[Side-Effect Gate]
-    G -->|Pass| H[Step 6: Finalize]
-    G -->|Regression risk| C
-    F -->|Fail, <3 attempts| C
-    F -->|Fail, 3+ attempts| I[Question architecture with user]
-    H --> J[Report]
-```
-
-If prose conflicts with this flow, follow the diagram.
-
----
-
-## Step 1: Scout
-
-Understand the affected codebase before forming any hypotheses. Activate
-`cf:scout` or perform an equivalent focused local scout (`rg` plus targeted
-reads) to map the blast radius.
-
-| Path | Scout depth |
-|------|-------------|
-| Quick/local | Minimal - project type, affected file(s), direct callers/dependents, related tests, recent commits |
-| Standard and deeper | Full - module boundaries, test coverage, call chains, recent changes, existing patterns |
-| `--parallel` | Per-issue independent scouts, one scope each, only through the Delegation Gate |
-
-**Output:** `✓ Step 1: Scouted — [N] files mapped, [M] dependencies, [K] tests found`
-
----
-
-## Step 2: Diagnose via `cf:debug`
-
-Evidence-based root cause analysis; no guessing. Use `cf:debug`, or validate
-an existing debug report when `--from-debug` is provided. See
-`references/diagnosis-protocol.md` for the Fix-local checklist.
-
-Diagnosis chain:
-
-1. **Capture pre-fix state:** exact error messages, failing test output, stack traces. This is the baseline for Step 5.
-2. **Observe:** read the actual error; locate where it occurs and when it started (`git log -p`).
-3. **Hypothesize:** form 2-3 hypotheses, each with confirm/refute evidence and a quick test.
-4. **Test:** validate each hypothesis against codebase evidence with focused local reads; test hypotheses in parallel only through the Delegation Gate.
-5. **Trace root cause:** symptom → immediate cause → contributing factor → root cause.
-6. **Escalate:** if 2+ hypotheses fail, apply `references/escalation-tactics.md`.
-
-**Exact root-cause contract:**
-- Symptom: exact observable failure
-- Reproduction: command, user flow, CI job, log trigger, or route
-- Expected vs actual behavior
-- Trigger: event or input that activated the failure, or `unknown`
-- Root cause: file:line, config, environment, dependency, or data source
-- Contributing factors: conditions that raised likelihood or impact but are not sufficient causes, or `none evidenced`
-- Why now: recent change, dependency drift, data state, environment, timing, or load
-- Evidence chain: observations proving the cause
-- Blast radius: affected files, modules, tests, users, workflows, or release paths
-
-With `--from-debug`, validate the report before accepting it:
-
-- the exact root-cause contract above is complete;
-- `Evidence Timeline` is present — a skipped timeline is valid in either producer form (`Timeline: skipped - <reason>` or `- skipped: <reason>`);
-- `Elimination Path` records the decisive observation for each removed or retained candidate;
-- `Recurrence-Prevention Handoff`, when present, carries evidence-backed candidates only.
-
-A report missing required fields routes back to diagnosis (`cf:debug`); it
-does not enter implementation.
-
-If any contract field is vague or missing file:line/config/env evidence, keep
-diagnosing or ask the user for the specific missing artifact. Do not implement.
-
-**Output:** `✓ Step 2: Diagnosed — Root cause: [summary], Evidence: [brief], Scope: [N files]`
-
----
-
-## Step 3: Select Depth + Bound Repair
-
-Apply the Proportional depth rule above. For 2+ independent issues (or
-`--parallel`), evaluate the Delegation Gate; when it is closed, fix the issues
-sequentially. Track progress with the runtime's task surface when available, or
-a markdown checklist otherwise.
-
-For Standard and Incident/deep, complete the bounded repair frame above. Quick
-records no separate frame unless scope or risk is still ambiguous.
-
-**Output:** `✓ Step 3: [Depth] selected — [workflow]`
-
----
-
-## Step 4: Implement Fix
-
-Rules:
-- Fix the root cause, not the symptom. Follow diagnosis findings.
-- Minimal changes only; follow existing code patterns.
-- One logical change per commit boundary.
-
-Workflows by depth:
-- **Quick:** apply the minimal fix from completed scout + diagnosis, run the exact pre-fix command plus typecheck/lint immediately, report before/after proof.
-- **Standard:** implement the fix, add or update a regression test that fails without the fix and passes with it, run the relevant suite.
-- **Incident/deep:** after diagnosis, research only unresolved external facts. If
-  multiple cause-aligned remedies or an architecture decision remain, use
-  `cf:brainstorm` to compare 2-3 options against the bounded repair frame, then
-  write a concise staged implementation plan with dependencies and proof per
-  stage. When diagnosis leaves one safe direct repair, skip research and
-  brainstorm, record why it satisfies the frame, and implement it. Delegated
-  research follows the Delegation Gate; implementation starts only after the
-  direction is resolved.
-- **Parallel:** one independent issue per agent, each following Steps 1-5, dispatched only through the Delegation Gate; aggregate results on completion.
-
-**Output:** `✓ Step 4: Fixed — [N] files changed`
-
----
-
-## Step 5: Verify + Prevent
-
-1. **Iron-law verification:** run the exact commands from the pre-fix state capture and compare output. No claims without fresh command output from the current run.
-2. **Regression test:** must fail without the fix and pass with it.
-3. **Full check:** typecheck + lint + build + test (see `references/parallel-patterns.md` Pattern C).
-4. **Prevention guard (Standard+):** see `references/prevention-gate.md`; consume the debug report's recurrence candidates when present.
-5. **Side-effect gate:** sweep the full blast radius from Step 2 against the five checks in the gate above.
-6. **Review:** trigger `cf:code-review`; see `references/review-cycle.md`.
-
-Verification and review report `PASS | PASS_WITH_WARNINGS | FAIL | BLOCKED`.
-The definition of `PASS` defers to `cf:code-review`. `PASS_WITH_WARNINGS`
-routes through the same remediation or user-pause path as `FAIL` and never
-auto-accepts. `BLOCKED` is terminal for the cycle; resolve the blocker instead
-of retrying. A review-only result is not execution proof; completion claims
-require fresh command output.
-
-If verification fails: under 3 attempts, loop back to Step 2 and re-diagnose
-with the new evidence; at 3+ attempts, stop and discuss with the user. Never
-weaken, delete, or mock a failing assertion to obtain green.
-
-**Output:** `✓ Step 5: Verified + Prevented — [before/after comparison], [N] tests added`
-
----
-
-## Step 6: Finalize
-
-1. **Report:** root cause, changes made, files affected, prevention measures, side-effect sweep result, and any remaining limitations.
-2. **Docs update:** if API or behavior changed, update only the affected existing docs through the docs flow.
-3. **Commit:** ask the user before committing; use conventional commits.
-
-**Output:** `✓ Step 6: Complete — [action taken]`
-
----
-
-## Output Format
-
-Unified step markers (emit after each step):
-```
-✓ Step 1: Scouted — [N] files, [M] deps
-✓ Step 2: Diagnosed — Root cause: [summary]
-✓ Step 3: [Depth] selected — [workflow]
-✓ Step 4: Fixed — [N] files changed
-✓ Step 5: Verified + Prevented — [tests added], [guards added]
-✓ Step 6: Complete — [action taken]
-```
-
-## Specialized Paths
-
-Use `references/workflow-specialized.md` as a progressively disclosed overlay
-after Step 1 scout for CI/CD failures, test suite failures, TypeScript type
-errors, UI/visual issues, and application log errors. Load only the matching
-section. Specialized paths add category-specific evidence and proof; they do
-not replace the six-step flow, weaken diagnosis, or broaden the repair scope.
-
-## References
-
-Load as needed:
-- `references/diagnosis-protocol.md` — Structured root cause analysis and the exact root-cause contract
-- `references/escalation-tactics.md` — What to do when hypotheses fail (Inversion, Scale Game)
-- `references/prevention-gate.md` — Defense-in-depth validation after fix
-- `references/review-cycle.md` — Review verdict handling and required user-pause conditions
-- `references/parallel-patterns.md` — Delegation Gate patterns for parallel work
-- `references/workflow-specialized.md` — CI/CD, test, TypeScript, UI-specific workflows