@haposoft/cafekit 0.16.0-rc.8 → 0.16.1

package/src/claude/references/debugger/verification-protocol.md

@@ -1,23 +1,24 @@
-# The Verification Protocol (The Iron Law of Testing)
+# Diagnostic Verification Protocol
 
-A fix is NOT considered complete when the code is written. A fix is only complete when it is PROVEN to work.
+Debug owns the failing baseline and the proof plan. It does not apply or certify the repair.
 
-## The 3-Step Verification Law
+## Ownership Boundary
 
-1. **Pre-Verification (Reproduce the Bug):**
-   Before touching any code, you must execute a command or test script that visibly outputs the failure or reproduces the error. You need a baseline failure state.
+1. **Debug — reproduce and diagnose:**
+   Capture the exact failing command, flow, log trigger, environment, and current output. If reproduction is unsafe or unavailable, state the limitation and use the strongest observable evidence.
 
-2. **Execution (Apply the Fix):**
-   Make the precise code modifications required using targeted edits.
+2. **Debug — design proof:**
+   Name the same reproduction, regression guard, transitive checks, side-effect sweep, and acceptance signal that would prove the proposed direction.
 
-3. **Post-Verification (Confirm the Fix):**
-   Re-run the EXACT SAME command or test script from step 1. The output MUST prove that the bug is resolved (e.g., terminal output showing "Success", HTTP 200, or a clear log assertion).
+3. **Fix/Test — mutate and verify:**
+   The implementation workflow applies the change. The canonical test owner reruns the baseline and the planned regression and side-effect checks with fresh output.
 
 ## What constitutes "Invalid Proof"?
 - **"I have reviewed the code and it looks correct."** -> This is hallucinated confidence. Rejected.
 - **"The unit test should pass now."** -> Assuming outcomes without execution. Rejected.
+- A different command that does not exercise the original failure path.
+- Stale logs, screenshots, or output captured before the final implementation.
+- A green health check when the reported business state remains unobserved.
 
 ## How to execute tests when no test suite exists?
-If the project lacks a formal test suite (e.g., no Jest or Cypress), you must utilize Bash commands to prove it:
-- Use `curl -v http://localhost:...` to prove an endpoint stopped throwing `500`.
-- Inject temporary `console.log()` outputs, trigger the flow, run the script, and grep the output buffer to prove the variable resolves correctly. (Remember to delete the temporary logs after proof is acquired).
+If the project lacks a formal test suite, Debug should define a deterministic native check such as a CLI invocation, read-only query, HTTP request, or browser flow. Temporary diagnostic instrumentation is allowed only to expose hidden state, must not alter product behavior, and must be removed before handoff. Fix/Test executes post-change proof.

package/src/claude/rules/orchestrator.md

@@ -91,7 +91,13 @@ Task cannot be completed as scoped. Never retry with the same inputs — instead
 ### `NEEDS_INFO`
 Agent lacks information to proceed. Supply the missing context and re-dispatch.
 
-> If an agent fails the same task **3+ times**, stop retrying and escalate to the user.
+> If an agent fails the same task **3+ times**, stop retrying and escalate.
+
+## Model Escalation
+
+When the current session or a subagent runs on a model below `fable` (e.g. `opus`, `sonnet`, `haiku`) and hits a hard problem — repeated failed attempts, a high-stakes design fork, or fuzzy requirements — spawn the `strategist` agent for counsel instead of switching the session model. It runs autonomously on the strongest available model and returns full advice in one reply, with no interview and no user round-trips. Give it the task, evidence gathered so far, approaches tried, and the specific question. It advises only; the caller stays responsible for the implementation.
+
+Counsel is not execution proof: it cannot close a task, satisfy a Verification Plan, or stand in for a Receipt. Escalate to the user when the strategist also cannot resolve it, or when the fork is one only the user may decide.
 
 ---
 

package/src/claude/rules/process-management.md

@@ -0,0 +1,39 @@
+# Process and Resource Management
+
+Use this file when a task starts, reuses, or ends long-running processes: dev
+servers, watchers, build daemons, tunnels, test runners, or emulators. It exists
+to prevent orphaned processes from accumulating and exhausting device memory.
+
+## The failure mode
+
+An agent starts a dev environment, then abandons it. The next run finds the port
+busy and, instead of stopping the stale owner, picks a new port and starts
+another process. Repeat, and the machine fills with duplicate processes and held
+ports. Parallel wave worktrees make it worse: each worktree spawns its own
+processes, and when the user removes the worktree or ends the session those
+processes stay behind.
+
+## Rules
+
+- Track every background process you start: command, PID, port, and worktree.
+  Prefer a background facility whose exit you can observe over an unobservable
+  detached run.
+- Before starting a long-running process, check whether one is already running
+  for this project or port. Reuse or stop it; do not spawn a duplicate.
+- Bind to a deterministic port per project or worktree. On "address in use",
+  identify and stop the stale owner rather than taking another port. Inspect
+  with `lsof -i :PORT` or `ss -ltnp` on macOS and Linux, `netstat -ano` on
+  Windows.
+- Stop what you started when its task, session, or worktree ends. Before a
+  `cf:develop` wave releases a worktree, terminate that worktree's background
+  processes so nothing is left orphaned.
+- Reconcile periodically: list your running dev processes (`ps`, `lsof`) and
+  stop the ones that no longer map to an active task or worktree.
+- Stop cleanly first (`SIGTERM`, or `taskkill /PID` on Windows), escalating to a
+  hard kill only when the process ignores the signal.
+
+## Safety
+
+Only stop processes you started or clearly own. Never end a process belonging to
+the user, another session, or the operating system without confirmation, and
+never match a kill pattern broad enough to catch unrelated processes.

package/src/claude/rules/review-audit-self-decision.md

@@ -0,0 +1,48 @@
+# Review, Audit, and Decision Rules
+
+Use this file when reviewing code, applying audit feedback, or cutting scope.
+
+## Verified Decisions
+
+Once a decision is verified by source, tests, or an empirical check, do not
+reverse it because an audit raises an abstract concern. Reverse only when the
+audit adds new evidence or the context changed.
+
+When rejecting an audit concern, name the verification source briefly.
+
+## User Decisions
+
+Do not silently undo an explicit user decision. This covers the C1 scope choice,
+C2 finding dispositions, and C3 completion judgement, along with thresholds,
+selected libraries, feature scope, schema shape, pricing, timelines, compliance
+choices, and UX trade-offs. Those gates are defined in `workflow.md`; this rule
+governs only how a later review may treat them.
+
+If an audit suggests reversing a user decision, present:
+
+- the original decision
+- the audit concern
+- the trade-off
+- the concrete options
+
+Then wait for the user.
+
+## Threat Model
+
+Before applying a security or robustness finding, identify what the code
+actually stores, protects, or exposes. Fix real failure modes. Document
+non-issues briefly. Ask when the risk is plausible but depends on product
+intent.
+
+## Scout First
+
+For questions answerable by reading the repository, scout before asking.
+`cf:scout` owns discovery and `cf:ask` owns the ask-back conditions; do not
+restate that list here.
+
+## Stable Code Artifacts
+
+Do not add plan IDs, phase numbers, CP or AC identifiers, audit labels, or
+finding codes to code comments, migration names, test names, or commit
+messages. Explain the invariant or behavior directly. Artifacts that already
+carry such identifiers stay as they are.

package/src/claude/rules/skill-domain-routing.md

@@ -1,29 +1,31 @@
 # Skill Domain Routing
 
-Advisory routing for installed domain skills (not an automatic hook). Read the selected skill's `SKILL.md` before acting.
+This rule is advisory model guidance, not an automatic prompt hook. Generate the
+current runtime catalog first when capability presence is uncertain, then read
+the selected skill's `SKILL.md` before acting.
 
-| Domain / intent | Skill |
+Resolve a capability slot from catalog `description`, `when_to_use`, `category`,
+and `keywords`; examples below are intent hints, not a copied installed inventory.
+
+| Capability slot | Matching intent |
 |---|---|
-| answer questions from source code/docs/specs/config | `/hapo:question` |
-| file discovery, structure, blast radius | `/hapo:inspect` |
-| style / layout / design system | `/hapo:frontend-design` |
-| React/TypeScript UI implementation | `/hapo:frontend-development` |
-| React/Next performance / re-renders | `/hapo:react-best-practices` |
-| deep UI/UX polish | `/hapo:ui-ux-pro-max` |
-| API, service, auth, database | `/hapo:backend-development` |
-| deploy / Docker / K8s / Cloudflare / CI | `/hapo:devops` |
-| mobile (RN / Flutter / iOS / Android) | `/hapo:mobile-development` |
-| docs init / update / summarize | `/hapo:docs --init` / `--update` / `--summarize` |
-| as-is reconstruction from legacy code | `/hapo:docs --reconstruct <scope>` |
-| future feature requirements | `/hapo:specs` |
-| run suites / scoped verification | `/hapo:test` |
-| E2E / load / a11y strategy | `/hapo:web-testing` |
-| browser snapshots / Browserbase | `/hapo:agent-browser` |
-| Chrome DevTools evidence | `/hapo:chrome-devtools` |
-| diagnose error / CI failure | `/hapo:debug` |
-| external best practices / tool compare | `/hapo:research` |
-| pptx / docx / pdf / xlsx / multimodal | `/hapo:pptx` / `docx` / `pdf` / `xlsx` / `ai-multimodal` |
-| commit / branch / release prep | `/hapo:git` |
-| review before release | `/hapo:code-review` |
+| evidence answer | factual question requiring source/docs/spec/config/current evidence |
+| repository discovery | files, entrypoints, call path, structure, blast radius |
+| product or architecture decision | unresolved outcome, scope, or material trade-off |
+| technical research | external comparison, conflicting evidence, current best practice |
+| specification | concrete substantial work needing durable plan/tasks |
+| implementation or repair | authorized code/content change or cause-aligned fix |
+| diagnosis | bug, failure, CI, incident, regression, or unexpected behavior |
+| verification or review | test execution, independent correctness/security review |
+| browser evidence | page interaction, snapshots, network, performance, or accessibility |
+| repository delivery | explicitly authorized commit, push, or branch operation |
+| document/artifact work | use only a matching installed optional capability |
+
+Choose one primary capability per intent. Add a secondary only when its output is
+an entry condition for the primary. If zero valid capabilities match, continue
+inline when safe or name the gap. If multiple catalog entries expose the same
+public identity, do not auto-route; require explicit user disambiguation.
 
-Pick one primary domain skill; name a secondary only when it changes execution. If none fit, use `skill-workflow-routing.md`.
+Never infer an optional document capability from this rule. Never select the
+explicit-only numeric optimization capability unless the user invokes it with
+its required bounded metric/guard contract.

package/src/claude/rules/skill-workflow-routing.md

@@ -1,24 +1,32 @@
 # Skill Workflow Routing
 
-Use this rule instead of automatic prompt routing. Read the user's intent, choose the primary CafeKit workflow, then load the relevant `.claude/skills/<skill>/SKILL.md`.
+Use native semantic selection, not an automatic prompt-scoring hook. The live
+catalog is descriptive evidence only; it never grants authority or forces a
+workflow.
 
-Do not inject or force a skill when the user explicitly asks for a direct answer, a specific command, or a different workflow.
+## Proportional selection
 
-Claude Code selects skills from frontmatter descriptions; trust it for clear intents.
+1. If the user names a valid installed skill, use it directly.
+2. If one obvious low-risk installed skill covers the intent, use it directly.
+3. For direct factual conversation, answer directly or use the installed
+   evidence-answer capability; do not invoke Route or agents for ceremony.
+4. For ambiguous, multi-step, multi-domain, or elevated/high-risk work, use the
+   installed Route capability to classify and compose the shortest valid chain.
 
-## Core chain
+Resolve every abstract link against the current runtime catalog. An absent,
+invalid, folder-mismatched, duplicate, or retired entry is not routable. Continue
+inline when safe or name the gap; never fabricate a skill or agent.
+
+## Chain shape
 
 ```text
-/hapo:question -> /hapo:brainstorm -> /hapo:specs -> /hapo:develop -> /hapo:test -> /hapo:code-review -> /hapo:git
+understand -> decide -> execute -> verify -> deliver
 ```
 
-Bug path: `/hapo:debug -> /hapo:hotfix` then test/review. As-is docs: `/hapo:inspect` → `/hapo:docs --reconstruct <scope>` → human review → specs → develop. Delegate implementation to an external agent CLI: `/hapo:delegate`.
-
-## Ambiguous cases
+Collapse links whose output is already current and evidenced. Preserve one
+owner, entry condition, and observable exit per retained link. Diagnosis does
+not authorize repair; implementation does not authorize commit, push, deploy,
+publish, or release; no route expands the user's existing authority.
 
-| Ambiguity | Prefer | Not when |
-|---|---|---|
-| debug-vs-hotfix | `/hapo:debug` first when root cause unknown | Root cause is known / trivial local fix → `/hapo:hotfix` |
-| question-vs-research | `/hapo:question` to ask about source code, docs, specs, config, dependencies, or project facts | External best-practice comparison / multi-source investigation → `/hapo:research` |
-| question-vs-brainstorm | `/hapo:question` for factual answers with evidence | Vague idea, missing acceptance criteria, unclear scope, multi-approach tradeoffs → `/hapo:brainstorm` |
-| specs-vs-brainstorm | `/hapo:specs` when intent and acceptance are concrete enough | Unclear idea / architecture choices still open → `/hapo:brainstorm` first |
+Use `skill-domain-routing.md` to resolve domain capability slots. The numeric
+optimization capability remains explicit-only and must never be auto-routed.

package/src/claude/rules/state-sync.md

@@ -30,7 +30,13 @@ state transition.
 Set `Status: done` only after the inline Receipt passes the
 `validateCanonicalReceipt` contract: exact command, `Exit: 0`,
 `Verification: PASS`, runtime-derived Base and Head values, and a non-empty
-fenced block of current command output. Missing, stale, contradictory,
+fenced block of current command output.
+
+A done task keeps that binding while its file differs from its committed bytes,
+and is validated on structure alone once the file is committed, unchanged, and the
+tree outside the specs root is clean. The gate detects drift, not invention: a valid
+Base and Head pair costs one command and no verification run, so neither mode proves
+that the command was executed. Missing, stale, contradictory,
 placeholder, copied, failure, or zero-test evidence leaves the task unfinished.
 
 Synchronization never fabricates commands, output, timestamps, completed

package/src/claude/rules/workflow.md

@@ -12,12 +12,12 @@ Use the CafeKit loop: **Understand -> Plan -> Execute -> Verify -> Sync**.
 
 ## 2. Plan
 
-- For non-trivial features, use `/hapo:specs` to challenge the minimum scope,
+- For non-trivial features, use `/cf:specs` to challenge the minimum scope,
   open C1, and create `specs/<feature>/plan.md` with flat
   `task-NN-*.md` files beside it.
 - After adversarial review, open C2 and apply only the findings the user accepts
   or revises. Specs never starts implementation.
-- Start implementation only after a new explicit `/hapo:develop` invocation,
+- Start implementation only after a new explicit `/cf:develop` invocation,
   then select one unblocked task at a time.
 - Extract from the active task:
   - `Status`
@@ -49,13 +49,15 @@ Use the CafeKit loop: **Understand -> Plan -> Execute -> Verify -> Sync**.
 
 ## 5. Sync
 
-- Use `/hapo:sync` to edit observed state surgically; the controller is the
+- Use `/cf:sync` to edit observed state surgically; the controller is the
   sole writer of task Status and proof.
 - Keep exactly one `Status:` field. Write or replace the task's final inline
   `## Receipt` before setting `Status: done`.
 - A canonical Receipt contains the exact command, `Exit: 0`,
   `Verification: PASS`, runtime-derived Base and Head values, and non-empty
   fenced current output. Never invent, copy, or infer missing proof.
+- When the binding to Base and Head applies, and what the gate does and does not
+  detect, are stated once in `state-sync.md`.
 - Re-read each edited task and reconcile its plan row, dependencies, acceptance
   mapping, status, and receipt without rewriting unrelated bytes.
 - Run docs checkpoint when a completed task affects public docs or architecture docs.

package/src/claude/runtime.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "./runtime.schema.json",
   "privacyBlock": true,
   "inspect": {
     "enabled": true

package/src/claude/runtime.schema.json

@@ -0,0 +1,205 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://haposoft.github.io/cafekit/runtime.schema.json",
+  "title": "CafeKit runtime configuration",
+  "description": "Project-scoped CafeKit settings, installed as .claude/runtime.json and .codex/runtime.json. Every key is optional; an absent key keeps the built-in default. Editors that honour $schema use this file for completion and inline documentation. Secrets do not belong here: this file is meant to be committed.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Path or URL of this schema. Present so editors can validate the file; CafeKit itself ignores it."
+    },
+    "privacyBlock": {
+      "type": "boolean",
+      "default": true,
+      "description": "Block reads of files that usually hold secrets (.env, credentials, keys). Set false to disable the privacy hook for this project."
+    },
+    "inspect": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "The guard that steers broad codebase searches toward the discovery workflow.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": true,
+          "description": "Set false to stop the inspect guard from blocking broad search commands."
+        }
+      }
+    },
+    "docs": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Documentation conventions surfaced to the agent.",
+      "properties": {
+        "maxLoc": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 800,
+          "description": "Lines allowed in one documentation file before the agent is reminded to split it."
+        }
+      }
+    },
+    "paths": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Where this project keeps its documentation, specifications, and plans, relative to the repository root.",
+      "properties": {
+        "docs": { "type": "string", "default": "docs", "description": "Documentation root the docs workflow reads and writes." },
+        "specs": { "type": "string", "default": "specs", "description": "Specification packet root: one direct child per feature." },
+        "plans": { "type": "string", "default": "plans", "description": "Directory holding plan files, one directory per plan." }
+      }
+    },
+    "spec": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Specification workflow guards. These are convenience switches for local work, not authorizations.",
+      "properties": {
+        "scaffold_guard": {
+          "type": "boolean",
+          "default": true,
+          "description": "Require task files to be generated by the scaffold script. Set false to write them by hand."
+        },
+        "tollgate": {
+          "type": "boolean",
+          "default": true,
+          "description": "Report specification state on each prompt. Set false to silence it."
+        },
+        "completion_gate": {
+          "type": "boolean",
+          "default": true,
+          "description": "Not a switch. The completion gate treats this flag as a bypass attempt and blocks while it is present, whatever its value, because a worker-writable file cannot authorize completion. Remove the key and satisfy the gate instead."
+        }
+      }
+    },
+    "usage": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Usage and quota reporting.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": true,
+          "description": "Set false to stop fetching quota data for the statusline."
+        }
+      }
+    },
+    "locale": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Languages the agent should use. null means English, or match the user.",
+      "properties": {
+        "thinkingLanguage": { "type": ["string", "null"], "default": null, "description": "Language for reasoning." },
+        "responseLanguage": { "type": ["string", "null"], "default": null, "description": "Language for user-facing output." }
+      }
+    },
+    "codingLevel": {
+      "type": ["integer", "null"],
+      "minimum": 0,
+      "maximum": 5,
+      "default": 1,
+      "description": "Codex only. How much explanation answers carry: 0 ELI5, 1 junior, 2 mid-level, 3 senior, 4 lead, 5 expert. Codex CLI has no output-style feature, so the rules hook injects the matching file from .codex/output-styles/ once per session. Claude Code loads the same styles natively and reads outputStyle from settings.json instead, so this key is ignored there. null or an out-of-range value injects nothing."
+    },
+    "statusline": {
+      "enum": ["full", "compact", "minimal", "none"],
+      "default": "full",
+      "description": "How much the statusline renders. 'none' prints an empty line."
+    },
+    "statuslineColors": {
+      "type": "boolean",
+      "default": true,
+      "description": "Set false for a statusline without ANSI colour."
+    },
+    "statuslineLayout": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["lines"],
+      "description": "Explicit statusline composition. A valid layout replaces the default renderers; an invalid or empty one falls back to them. The 'statusline' mode still limits how many lines are drawn.",
+      "properties": {
+        "lines": {
+          "type": "array",
+          "description": "One entry per rendered line, each listing section ids in display order.",
+          "items": {
+            "type": "array",
+            "items": { "enum": ["model", "context", "quota", "directory", "git", "plan", "cost", "changes"] }
+          }
+        }
+      }
+    },
+    "assertions": {
+      "type": "array",
+      "description": "Rules injected for files matching a glob.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["pattern", "rule"],
+        "properties": {
+          "pattern": { "type": "string", "description": "Glob the rule applies to, for example \"**/*.go\"." },
+          "rule": { "type": "string", "description": "The rule text shown to the agent." }
+        }
+      }
+    },
+    "trust": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Local trust prompt. Keep the passphrase in your own user configuration, never in this committed file.",
+      "properties": {
+        "enabled": { "type": "boolean", "default": false, "description": "Whether a trust passphrase is required." },
+        "passphrase": { "type": ["string", "null"], "default": null, "description": "Do not set this here. This file is committed." }
+      }
+    },
+    "project": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Detection overrides for a repository the defaults read wrong.",
+      "properties": {
+        "type": { "type": "string", "default": "auto", "description": "Project type, or \"auto\" to detect." },
+        "packageManager": { "type": "string", "default": "auto", "description": "Package manager, or \"auto\" to detect." },
+        "framework": { "type": "string", "default": "auto", "description": "Framework, or \"auto\" to detect." }
+      }
+    },
+    "plan": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Plan directory naming and resolution.",
+      "properties": {
+        "namingFormat": { "type": "string", "default": "{date}-{issue}-{slug}", "description": "Directory name pattern. Variables: {date}, {issue}, {slug}." },
+        "dateFormat": { "type": "string", "default": "YYMMDD-HHmm", "description": "Date portion of the plan name." },
+        "issuePrefix": { "type": ["string", "null"], "default": null, "description": "Prefix for the issue portion, for example \"GH-\"." },
+        "reportsDir": { "type": "string", "default": "reports", "description": "Reports directory inside a plan." },
+        "resolution": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "How the active plan is chosen. Only explicit session state makes a plan active; a branch match is a suggestion.",
+          "properties": {
+            "order": { "type": "array", "items": { "enum": ["session", "branch"] }, "description": "Order the sources are consulted in when resolving the active plan." },
+            "branchPattern": { "type": "string", "description": "Regular expression extracting a plan slug from the branch name." }
+          }
+        },
+        "validation": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Plan validation questioning.",
+          "properties": {
+            "mode": { "enum": ["auto", "prompt", "off"], "default": "prompt", "description": "When to run validation questions." },
+            "minQuestions": { "type": "integer", "minimum": 0, "default": 3, "description": "Fewest questions to ask." },
+            "maxQuestions": { "type": "integer", "minimum": 0, "default": 8, "description": "Most questions to ask." },
+            "focusAreas": { "type": "array", "items": { "type": "string" }, "description": "Topics the questions should cover." }
+          }
+        }
+      }
+    },
+    "hooks": {
+      "type": "object",
+      "deprecated": true,
+      "description": "Not honoured. No hook consults this map, so an entry here disables nothing. Disable a hook by removing its entry from the host's hook configuration instead.",
+      "additionalProperties": { "type": "boolean" }
+    },
+    "develop": {
+      "type": "object",
+      "deprecated": true,
+      "description": "Not honoured. Parallel execution is chosen per invocation with the --parallel flag, not from this file.",
+      "additionalProperties": true
+    }
+  }
+}