@haposoft/cafekit 0.16.0-rc.8 → 0.16.0

package/src/claude/references/debugger/parallel-agent-hydration.md

@@ -1,43 +1,28 @@
-# Swarm Tactics (Parallel Agent Hydration)
+# Permission-Gated Parallel Reconnaissance
 
-In order to resolve wide-radius cascading failures (e.g. Microservices collapsing simultaneously, Databases going down concurrently with Caches, or obscure Data Race conditions), relying purely on single-threaded execution (Serial execution) within an isolated Context Window will overwhelm and burn immense amounts of time. 
+Parallel discovery is optional, not a default Debug phase. Start with focused repository and runtime evidence in the main agent.
 
-Do not attempt to solve everything alone! Elevate yourself to the role of **Head of Debugging (Chief Orchestrator)** and exploit the swarm potential (Parallel Hydration) inherent to the Multi-Agent grid.
+## Delegation Gate
 
-## 1. When to Issue Swarm Directives?
-- **Cross-examination Audits:** When you suspect an error heavily involves 2-3 disparate services. You must read Frontend Server logs, API Backend endpoints, and Slow Query PostgreSQL logs concurrently.
-- **Widespread Impact Reconnaissance:** Exploring how many times an entire codebase invokes an API that recently suffered a Deprecation notice.
-- **Polluter Isolation Tactics:** Scanning isolated codebase sectors independently to track down memory leaks or Data Races. Instead of executing Git Bisect linearly, deploy 3 Sub-Agents to investigate 3 separate commit history timelines simultaneously.
+Delegate only when all are true:
 
-## 2. Dispatching Proxy Agents (Task Management)
+1. The user explicitly requested or permitted delegation or parallel agents.
+2. The active runtime exposes an Explore/delegation capability.
+3. There are at least two distinct, non-overlapping scopes whose read-only evidence can be collected independently.
 
-Fully weaponized with the `TaskCreate` tool. Broadcast multiple `TaskCreate` commands AS EARLY AS POSSIBLE, granting robust execution authority to each spawned Sub-Agent.
+Otherwise continue sequentially. Lack of delegation must never block diagnosis.
 
-### The Classic Execution: 3 Parallel Operatives
-When investigating severe system latency/bottleneck incidents, initiate 3 concurrent Agents before executing localized manual sweeps:
+## Good Independent Scopes
 
-```json
-// TaskCreate Command 1: Assign to Database Analysis Agent
-{
-  "Goal": "Execute EXPLAIN ANALYZE on queries choking within the last 24h block. Must return a list containing the top 3 worst SQL execution plans.",
-  "Files/Context": "src/database/... (assign appropriate CWD)",
-  "ExpectedOutput": "A concise text summary published via TaskUpdate."
-}
+- Frontend console/network evidence vs backend request/log evidence
+- Application trace vs database query/lock evidence
+- Failing CI job vs nearest known-good run
+- Independent service or package boundaries in a cascading incident
 
-// TaskCreate Command 2: Assign to Frontend Performance Agent
-{
-  "Goal": "Monitor Network tabs, analyze HAR files or Load Test scripts. Specifically identify any JS Bundle requiring more than 5 seconds to load.",
-  "Files/Context": "src/frontend/... "
-}
+## Dispatch Contract
 
-// TaskCreate Command 3: Assign to Infrastructure/CI Pipeline Agent
-{
-  "Goal": "Download GitHub Actions pipeline logs executed at midnight. Scan precisely for Out Of Memory (OOM) Errors occurring within Docker pods.",
-  "Files/Context": "Utilize robust bash curl executions pointing to Github APIs."
-}
-```
-
-## 3. Disruption Avoidance Rules (Isolation Paradigms)
-- **Zero Shared Modification Allowed:** Sub-Agents deployed during the "Reconnaissance" Phase (Hydration) are explicitly RESTRICTED TO READ-ONLY OPERATIONS (Read-only, Grep, Log search). Absolutely forbid assigning dual sub-agents to mutate the same `.ts` file simultaneously, an act which guarantees catastrophic Merge Conflicts.
-- **Context Injection (Knowledge Passing):** Do not expect your proxy agents to derive full systemic context from nothing. Inject rich knowledge matrices directly into the Description string during `TaskCreate`: "Navigate exclusively into directory X, execute command Y, locate error line Z. Return report immediately here".
-- **Acknowledge & Gather Pattern (Re-assimilation):** After deploying the fleet, aggressively monitor the grid using `TaskList` or `TaskGet`. Wait for operative `DONE` statuses and updates. Finally, amalgamate returning reports into a master Cross-correlation diagnostic map before passing your final judgment execution.
+- Assign explicit source/log/runtime boundaries with no overlap.
+- Reconnaissance is read-only: no product edits, fix application, migrations, or state mutation.
+- Provide the symptom, known evidence, exact questions, allowed commands, and required provenance.
+- Require findings to distinguish observed fact, inference, and unknown.
+- Join all results before root-cause judgment. Resolve contradictions against primary evidence and record unresolved conflicts.

package/src/claude/references/debugger/performance-diagnostics.md

@@ -33,7 +33,7 @@ Measure before optimizing. A performance fix without a baseline is guessing.
    - Cold starts, cache misses, or dependency latency
 6. **Set verification target**
    - Before metric
-   - After metric
+   - Required after metric for Fix/Test
    - Acceptable threshold
    - Regression guard if feasible
 
@@ -70,7 +70,7 @@ Check:
 - Baseline:
 - Bottleneck layer:
 - Root cause:
-- Proposed fix:
+- Cause-aligned fix direction:
 - Verification target:
 - Regression guard:
 ```

package/src/claude/references/debugger/root-cause-tracing.md

@@ -2,16 +2,47 @@
 
 When dealing with deep-rooted system failures, avoid modifying the surface layer where the error was thrown. The true failure often originated several layers deeper.
 
+## Trace Backward To The Origin
+
+Do not stop at the frame that throws. Trace this chain with evidence:
+
+```text
+symptom -> immediate cause -> caller/data boundary -> origin
+```
+
+At each boundary, record the input, expected invariant, actual value/state, and evidence source. The origin is the earliest owned invariant whose violation is sufficient to explain the downstream symptom.
+
+## Separate Causal Roles
+
+- **Trigger:** event or input that activated the failure now.
+- **Root cause:** violated owned invariant that made the failure possible.
+- **Contributing factor:** condition that increased likelihood or impact but is not sufficient by itself.
+
+Do not label temporal proximity or a recent commit as causation until the mechanism is demonstrated.
+
 ## The 5-Whys Deep Dive
-Continuously ask "Why?" until you hit the architectural bedrock:
+Ask "Why?" until the chain reaches the responsible invariant:
 - **Symptom:** User cannot log in.
 - *Why?* The Frontend received an `undefined` profile object.
 - *Why?* The Backend API returned null.
 - *Why?* The Database query failed silently.
 - *Why?* The ORM mapping model was updated yesterday, but the database schema migration was never executed.
-- **Fix:** Execute the database migration, DO NOT add an `if (!profile)` fallback check on the Frontend.
+- **Root cause direction:** repair the missing migration contract; a frontend fallback would only mask the symptom.
+
+## Call And Data Chain Template
+
+```markdown
+- Symptom boundary: [where failure becomes observable]
+- Immediate cause: [throw/invalid state/timeout]
+- Caller or data producer: [who supplied it]
+- Origin: [first violated owned invariant]
+- Trigger: [event/input or unknown]
+- Contributing factors: [conditions or none evidenced]
+- Evidence links: [file:line/log/config/query/trace]
+```
+
+For test pollution, isolate the polluter with the existing runner's subset, order, seed, or bisection support. Change one variable at a time. Temporary instrumentation must state its purpose and be removed before handoff.
+
+## History And Bisection
 
-## Git Bisect Simulation
-If a bug suddenly appears in a previously working system and the cause is completely obscured, utilize Git history profiling.
-- Command the terminal to run `git log -p path/to/failing-file` to see exactly who altered the logic and what the previous state was.
-- Do not hesitate to use standard Unix commands to track changes over time or locate when a specific variable was dropped.
+Use `git log -p -- path/to/file` to form hypotheses about when behavior changed; history alone is not proof. Use `git bisect run` only in a clean disposable worktree with a deterministic diagnostic command and explicit authorization for the checkout churn. Otherwise provide the bisection plan for Fix/Test to execute.

package/src/claude/references/debugger/side-effect-gate.md

@@ -1,6 +1,6 @@
 # Side-Effect Gate
 
-Use this before claiming a fix is complete. A bug can be fixed locally and still create a regression nearby.
+Debug designs this sweep; `cf:fix` and the canonical test owner execute it after implementation. A local symptom can disappear while a nearby contract regresses.
 
 ## Gate Questions
 
@@ -44,5 +44,7 @@ Use this before claiming a fix is complete. A bug can be fixed locally and still
 - Contract changes:
 - Runtime checks:
 - Security/privacy:
+- Recurrence invariant:
+- Observability/alerting gap:
 - Residual risk:
 ```

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/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,7 +49,7 @@ 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`.

package/src/claude/runtime.json

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