@haposoft/cafekit 0.16.0-rc.8 → 0.16.0

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

@@ -1,6 +1,6 @@
 ---
-name: hapo:specs
-description: "Turn a substantial feature idea into a bounded, reviewed plan and executable flat task files, with human decisions at scope, findings, and completion. Use when the work needs durable coordination; skip for a clear one-file or two-file change."
+name: cf:specs
+description: "Turn a substantial or risk-elevated feature idea into a bounded, reviewed plan and executable flat task files, with human decisions at scope, findings, and completion. Use when work needs durable coordination or is not eligible for direct work; skip only when a change is clear, isolated, reversible, routine, and likely limited to one or two files."
 user-invocable: true
 argument-hint: "<feature-description>"
 metadata:
@@ -9,19 +9,23 @@ metadata:
 ---
 # Specs — process-first planning
 
-Quality comes from a short decision process; honesty comes from evidence. Keep
-the human at exactly three gates and let the agent do the work between them.
-The durable output is Markdown that can be read and edited without a compiler.
+Quality comes from a short decision process; honesty comes from evidence. Keep the human at exactly three gates; durable output is editable Markdown.
 
-## Step 0 — decide whether a plan earns its cost
+## Step 0 — classify risk before routing
 
-Work directly when the cause and change are clear, isolated, reversible, and
-likely limited to one or two files. Use this skill when the request crosses
-components, contains a product or architecture choice, has meaningful failure
-risk, or needs several tasks, sessions, or owners.
+Classify material risk before choosing a workflow; user wording never lowers an observed floor.
 
-Do not create a plan merely because this skill was mentioned in surrounding
-documentation. The user must invoke Specs or ask for durable planning.
+- `critical`: auth/secrets/privacy; destructive/irreversible work or possible data loss/corruption; money/privilege/safety; production-state mutation.
+- `elevated`: cross-component contracts, compatibility, concurrency, external integration, or installed/runtime behavior.
+- `routine`: only when no elevated or critical signal applies.
+
+Work directly only when the cause and change are clear, isolated, reversible,
+`routine`, and likely limited to one or two files. Route unresolved user-owned
+observable choices to C1/C2 first; after they settle, route material competing
+technical designs through Brainstorm. Split three or more independent
+subsystems; otherwise use one Specs packet for any material work that does not qualify for direct work or Brainstorm-only exploration. A subsystem is independent only when its outcome, boundary, and verification/deployment path can move through the lifecycle separately.
+
+Do not create a plan merely because documentation mentions this skill; the user must invoke Specs or ask for durable planning.
 
 ## The three human gates
 
@@ -31,9 +35,7 @@ documentation. The user must invoke Specs or ask for durable planning.
 | C2 — Findings | after adversarial review | accept, reject, or revise each deduplicated finding |
 | C3 — Done | after execution | accept completion from current command output and receipts |
 
-Ask once at each gate. Do not ask for routine implementation choices between
-the gates. If new evidence invalidates the scope, return to C1 instead of
-silently expanding it.
+Ask once at each gate. Do not ask for routine implementation choices between them. New evidence that invalidates scope returns to C1.
 
 ## Primary output layout
 
@@ -46,59 +48,44 @@ specs/<feature>/
 └── task-02-<slug>.md
 ```
 
-Task files are flat beside `plan.md`. Do not create a nested task directory.
-Use safe lowercase feature and task slugs. Read
-[`references/templates.md`](references/templates.md) before authoring these
-files.
+Task files are flat beside `plan.md`. Do not create a nested task directory. Use safe lowercase slugs and read [`references/templates.md`](references/templates.md) first.
 
 ## Flow
 
 ### 1. Challenge scope, then open C1
 
-Inspect the repository before drafting. Answer three questions with current
-`path:line` evidence:
+Inspect the repository before drafting. Answer three questions with current `path:line` evidence:
 
 1. What already exists and can be reused?
 2. What is the smallest change set that delivers the requested outcome?
-3. What signals expansion: more than eight touched files, more than two new
-   services/classes, or more than three independent work groups?
+3. What signals expansion: more than eight touched files, more than two new services/classes, or three or more independently deliverable subsystems?
 
 Present the answers and ask the user to EXPAND, KEEP, or CUT. Record the chosen
 scope and explicit exclusions in `plan.md`.
 
 ### 2. Write the plan and task packets
 
-Keep `plan.md` as the short index: C1 decision, EARS acceptance criteria,
-explicit exclusions, and a task table. Every acceptance criterion receives a
-stable ID, and every task row lists the criteria it satisfies.
+Keep `plan.md` as the short index: C1 decision, EARS criteria, exclusions, and task table. Give every criterion a stable ID mapped by task rows.
+
+For a Specs route, persist the canonical `## Coverage profile` from
+`references/templates.md`: one `CP-NN` row per observable outcome; tasks reference IDs instead of copying it.
 
-Make each task small enough for one owner to hold in one reading: one outcome,
-normally no more than about five owned files, explicit dependencies, measurable
-acceptance, and a runnable verification command. A task must deliver usable
-behavior; do not create preparation-only tasks.
+Each task has one usable outcome, normally at most about five owned files, explicit dependencies, measurable acceptance, and a runnable verification command; no preparation-only tasks.
 
-Author exact task state, not prose readiness. `pending` means semantically ready
-for the dependency-aware queue. Use `blocked` while a C1/C2 decision, an
-accepted finding, or `UNKNOWN` closure remains open. A named task dependency
-alone does not change `pending` to `blocked`; the resolver derives which pending
-task is next. Change `blocked` to `pending` only after current evidence closes
-every non-dependency blocker; keep pre-execution Receipts empty.
+Author exact state: `pending` means semantically ready for the dependency-aware queue.
+Use `blocked` while a C1/C2 decision, accepted finding, or `UNKNOWN` closure remains
+open. Dependencies alone do not change `pending`; the resolver queues them. Promote only after current evidence closes every non-dependency blocker; keep pre-execution Receipts empty.
 
-When an outcome is uncertain, write a question rather than guessing. When a
-rule remains ambiguous, add two or three concrete examples and resolve the rule
-at C1 or C2.
+`Required proof` is planned, not executed evidence. Unknown command/caller/environment
+reachability blocks `pending`; known unrun proof does not. Missing, failed, or unavailable
+required evidence blocks `done`/C3; levels never promote. Rederive affected CP rows after accepted scope, outcome, criteria, ownership, dependency, risk, or proof deltas, before status.
+Source/static checks prove the written contract, not live-model adherence.
 
 ### 3. Review adversarially, then open C2
 
-Read [`references/review.md`](references/review.md) and run its fresh-context
-review. Every finding needs a reproducible `path:line` citation and a concrete
-failure scenario. Deduplicate, rank, and cap the list at 15.
+Read [`references/review.md`](references/review.md) and run its fresh-context review. Require reproducible `path:line` plus a failure scenario; deduplicate, rank, and cap at 15.
 
-Ask the user to accept, reject, or revise each finding. Apply only accepted
-decisions. After every plan edit, run the consistency sweep across all plan and
-task files, then rederive every task status rather than only the first candidate.
-Write task dependencies as exact flat task basenames so the queue can derive them.
-Stop after two paper-review rounds; later findings require runtime evidence.
+Ask the user to accept, reject, or revise each finding; apply only accepted decisions. After every edit, sweep all packet files and rederive every status. Dependencies use exact flat task basenames. Stop after two paper rounds; later findings require runtime evidence.
 
 ### 4. Execute one task at a time
 
@@ -127,19 +114,13 @@ it does not invent product approval, review independence, or runtime coverage.
 1. **A1 — Scope once.** Raise scope pressure at C1; reopen only with new proof.
 2. **A2 — Small packets.** One task, one outcome, one owner, one proof command.
 3. **A3 — One fact, one home.** Reference decisions; never copy mutable lists.
-4. **A4 — Files are state.** `plan.md` and flat task files are canonical and
-   hand-editable; indexes are disposable views.
-5. **B1 — Cite the repository.** Codebase claims carry current `path:line`
-   evidence or an explicit `[UNVERIFIED]` marker.
-6. **B2 — Review from fresh context.** The author does not impersonate the
-   independent adversarial reviewer.
-7. **B3 — Sweep after edits.** Search renamed concepts, rejected assumptions,
-   ownership, dependencies, criteria IDs, and copied prose across every file.
-8. **B4 — Stop paper churn.** Two pre-code review rounds maximum; later claims
-   need runtime evidence.
-9. **C1 — State is derived.** Status follows fresh blocker and proof evidence.
-10. **C2 — Rules pay rent.** Add a rule or machine check only when it prevents a
-    cited real incident; reassess rules when the primary model changes.
+4. **A4 — Files are state.** Markdown is canonical; indexes are disposable.
+5. **B1 — Cite the repository.** Use current `path:line` or `[UNVERIFIED]`.
+6. **B2 — Review fresh.** The author does not impersonate the reviewer.
+7. **B3 — Sweep edits.** Reconcile names, decisions, CP rows, ownership, dependencies, criteria, and proof.
+8. **B4 — Stop paper churn.** Two pre-code rounds; later claims need runtime evidence.
+9. **C1 — Derive state.** Status follows fresh blocker and proof evidence.
+10. **C2 — Rules pay rent.** Require a cited failure; reassess for model changes.
 
 ## Machine boundary
 

package/src/claude/skills/specs/references/review.md

@@ -26,19 +26,22 @@ evidence.
 | Scope Auditor | Is new state scoped to the right lifetime and owner? | constructors, writers, cleanup, and existing equivalents |
 | Contract Verifier | Are all consumers and compatibility surfaces covered? | caller/test/export/config/help inventory |
 
-Scale the review to the number of independent work groups:
+Keep Fact Checker as the baseline. Assign every remaining material CP risk to a
+named reviewer lens; a critical row includes both relevant security-adversary and
+failure-mode coverage, and nonmaterial lenses are not added. Scale reviewer count
+to independent work groups:
 
 | Groups | Reviewers | Roles | Claim budget |
 |---|---:|---|---:|
-| 1-2 | 2 | Fact Checker plus the highest-risk role | about 5 per group |
-| 3-5 | 3 | Fact Checker, Contract Verifier, one risk role | about 10 per group |
-| 6+ | 4 | all roles | at least 15 total |
+| 1-2 | 2 | Fact Checker plus all matching material lenses | about 5 per group |
+| 3-5 | 3 | Fact Checker plus all matching material lenses | about 10 per group |
+| 6+ | 4 | Fact Checker plus all matching material lenses | at least 15 total |
 
-The table is a sizing guide, not permission to skip a material boundary.
+Reviewer count is fixed by the table, not lens count. Give each reviewer a distinct primary lens; when material lenses exceed reviewers, combine related named lenses on one reviewer and keep every material lens assigned.
 
 ## B2 — fresh-context red team
 
-Use reviewers that did not author the plan and give each one a distinct lens:
+Use reviewers that did not author the plan and assign these lenses from affected CP rows:
 
 - **Security adversary:** authorization bypass, injection, secret exposure,
   unsafe path and trust-boundary transitions.
@@ -101,8 +104,8 @@ A repair that adds user semantics or scope returns to C1.
 After any accepted finding or user edit:
 
 1. Reread every file in `specs/<feature>/`.
-2. List deltas: renamed terms, changed decisions, removed assumptions, task
-   order, ownership, dependencies, acceptance IDs, and commands.
+2. List accepted deltas; rederive affected CP rows using the canonical delta list
+   in the templates before task status.
 3. Search every delta and its old spelling across the whole feature packet.
 4. Reconcile the plan table, task details, examples, acceptance mapping, and
    verification commands.

package/src/claude/skills/specs/references/templates.md

@@ -27,6 +27,11 @@ Specs-Contract: process-first-ready-v1
 ## Out of scope
 - <deliberate exclusion>
 
+## Coverage profile
+| ID | Outcome | Change kinds | Material surfaces | Ambiguity/action | Risk/evidence | Required proof |
+|---|---|---|---|---|---|---|
+| CP-01 | <externally observable outcome> | <all kinds> | <all material surfaces> | <state + action> | <level + evidence> | <source/installed/live set> |
+
 ## Acceptance criteria
 | ID | EARS criterion | Proof |
 |---|---|---|
@@ -60,6 +65,9 @@ Status: blocked
 - In: <exact behavior>
 - Out: <nearby behavior deliberately excluded>
 
+## Coverage
+- <exact `CP-NN` IDs owned by this task>
+
 ## Ownership
 - Modify: `src/a.ts`
 - Create: `test/a.test.ts`
@@ -74,7 +82,7 @@ Status: blocked
 ## Verification Plan
 - Command: `<exact runnable command>`
 - Named probe: <existing concrete probe/test/hook ID; never only a suite label>
-- Reachability: <real entrypoint/caller at each `source`/`installed`/`live` level; `UNKNOWN` if unexecuted>
+- Reachability: <known command/caller/environment per required level; `UNKNOWN` only when the path cannot yet be established>
 - Oracle: <externally observable success or failure>
 - Counterexample: <material alternative behavior that must make this proof fail>
 - Artifacts: <required artifact path plus digest algorithm/comparison rule, or explicitly ephemeral with cleanup rule>
@@ -83,18 +91,22 @@ Status: blocked
 <!-- Fill only after execution; see canonical form below. -->
 ````
 
-Trace `Command → Named probe → Reachability → Oracle`. Aggregate suites
-name the owning concrete probe. Proof at `source`/`installed`/`live` stays
-separate; one level never promotes another. Run mutation or destructive
+Trace `Command → Named probe → Reachability → Oracle`. Aggregate suites name the
+owning concrete probe. `Required proof` is a planned level set, not execution
+evidence: known but unrun proof may be `pending`; `UNKNOWN` reachability blocks
+`pending`; missing, failed, or unavailable required evidence blocks `done`/C3.
+Levels stay separate and never promote one another. Run mutation or destructive
 negative controls only on disposable copies under a verified temporary root,
 never tracked worktree or canonical source bytes.
+For every required level in each referenced CP row, map its named probe and
+reachability here; one command may own several explicitly named level probes.
 
 ## Status matrix
 
 | Status condition | Persisted state |
 |---|---|
 | C1/C2 decision open | `blocked` |
-| accepted finding open or `UNKNOWN` | `blocked` |
+| accepted finding open or `UNKNOWN` reachability | `blocked` |
 | every non-dependency blocker closed | `pending` |
 | named task dependency not done | keep `pending`; queue gates it |
 Use only direct-child task basenames or `none` under `## Dependencies`; keep `## Receipt` empty until execution produces canonical proof.
@@ -138,33 +150,37 @@ Avoid implementation detail unless it is a user-approved contract. Replace
 
 ## Example Mapping rule
 
-When the expected outcome is uncertain, write a question and take it to C1 or
-C2; do not guess. When a rule is ambiguous, add two or three examples:
+Classify ambiguity in every affected CP row:
 
-```text
-Rule: A done task has fresh executable proof.
-Example: command exits 0 and reports 3 tests passed -> done may be proposed.
-Example: command exits 0 but reports 0 tests -> remains unfinished.
-Example: output is copied from an earlier session -> remains unfinished.
-Question: which environment owns the authoritative integration run?
-```
+| State | Required action |
+|---|---|
+| `none` | proceed |
+| `examples-needed` | add two or three examples only for an already decided rule; promote to `decision-needed` if an example changes observable behavior |
+| `decision-needed` | ask the user at C1/C2 and keep affected tasks blocked |
+| `design-needed` | after user-owned decisions settle, route material competing technical designs through Brainstorm |
 
-Keep examples only until they clarify a rule or acceptance criterion.
+Do not let examples choose a product outcome: retention of 30 versus 90 days is
+`decision-needed`. Keep examples only until they clarify the decided rule.
 
 ## No-invention and conditional boundary contracts
 
 Before implementation handoff, apply the **no-invention gate**: if two implementations conform to the packet text yet can produce different externally observable output, state, error, security, or compatibility behavior, surface the missing choice as an explicit C1 or C2 question and block handoff.
 
+For a Specs route, `plan.md` owns one `## Coverage profile` row per externally observable outcome; direct and Brainstorm-only routes do not persist it. Change kinds are multi-valued (`add`, `modify`, `fix`, `refactor`, `remove`, `migrate`, `integrate`), and unfamiliar kinds or surfaces use `other:<verbatim>` rather than disappearing. Each task references its CP IDs; authoring, review, edge, and proof obligations union only inside affected rows/tasks. Rederive affected CP rows after any accepted scope, outcome, criteria, ownership, dependency, risk, or proof delta before task status.
+
 A boundary is material when the task creates, changes, or depends on it and a different choice changes an external observation, security, durable data, compatibility, or proof reachability. Require only the matching material row; omit nonmaterial categories.
 For every required row, name each listed choice exactly; labels such as “JSON”, “local path”, “locked”, or “timestamped” alone remain unresolved.
 
 | Boundary | Required contract when material |
 |---|---|
+| Interaction/UI | entry journey; visible/loading/empty/error states; input/focus/keyboard; accessibility; responsive/native/device behavior |
 | API/CLI | entrypoint/route or command grammar; identity/auth; input/default/normalization; success output; error/status/exit; duplicate/retry/idempotency; compatibility |
-| Schema | version; exact keys/nesting/types; required/optional; enum/format/bounds/cardinality; unknown-field behavior; compatibility/migration |
-| State/concurrency | initial/terminal states; event + guard + effect + next + error; ordering; duplicate/retry; writer/lock acquire/contention/release; rollback/recovery |
+| Data/schema | authority/storage/transaction; version; exact keys/nesting/types; required/optional; enum/format/bounds/cardinality; unknown-field behavior; compatibility/migration |
+| Async/state | initial/terminal states; event + guard + effect + next + error; ordering/concurrency; duplicate/retry; writer/lock acquire/contention/release; cancellation; rollback/recovery |
 | Filesystem/security | authoritative root; trusted/untrusted segment grammar; lexical + canonical containment and symlink policy; flags/mode; temp/rename/fsync; lock/stale reclaim; crash cleanup |
+| Runtime/deploy | config/env/flags; registration/packaging; OS/arch; rollout/rollback; health/logging; operator recovery |
 | Time/retention | clock source; unit/precision/timezone; endpoints and inclusion/comparator; anomaly behavior; expiry/purge/recovery |
+| AI/model | provider/model/prompt/tool schema; nondeterminism/bounds; safety/privacy; fallback; cost/token limit; eval oracle |
 | Integration/proof | caller; export/registration; packaging/config; native path/consumer; proof level (`source`/`installed`/`live`); observable failure oracle |
 
 ## Twelve edge-case dimensions
@@ -194,7 +210,7 @@ Before C2 confirm:
 - dependencies are acyclic and refer to real task numbers;
 - commands are runnable from the named work context;
 - negative, recovery, and reachability probes exist where risk requires them;
-- examples settle ambiguous rules rather than adding prose;
+- every ambiguity follows its required action; examples only clarify decided rules;
 - the latest consistency sweep reports zero unresolved contradictions.
 
 Stop expanding when a fresh reviewer finds no new material failure with new

package/src/claude/skills/specs/templates/requirements-init.md

@@ -4,5 +4,5 @@
 {{PROJECT_DESCRIPTION}}
 
 ## Requirements
-<!-- Will be generated during the hapo:specs requirements phase -->
+<!-- Will be generated during the cf:specs requirements phase -->
 

package/src/claude/skills/specs/templates/research.md

@@ -8,11 +8,11 @@ Research exists only because this uncertainty can change requirements or design.
 
 ## Evidence Summary
 
-<!-- Cite concrete repository evidence or current primary sources that resolve the uncertainty. -->
+<!-- Keep the mandatory H2 headings in this exact order. Record each material claim with: claim; URL or repository path:line; authority; date/version; project applicability; confirmed|inferred|unresolved. For comparisons include ranked fit, decisive tradeoffs, contradictions, and limits. -->
 
 ## Decision
 
-<!-- State the selected decision and how the evidence supports it. -->
+<!-- State the selected decision, research depth, and decisive evidence; if evidence cannot choose safely, state unresolved and name what would settle it. -->
 
 ## Remaining Gaps
 

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

@@ -1,5 +1,5 @@
 ---
-name: hapo:sync
+name: cf:sync
 description: "Synchronize process-first task Status and inline Receipts without inventing proof; also preserves existing legacy Specs state."
 user-invocable: true
 when_to_use: "Invoke after implementation or verification changes a task's real state, or to audit a feature packet for drift."
@@ -19,11 +19,11 @@ state. Never infer proof, approval, review independence, or product readiness.
 ## Commands
 
 ```text
-/hapo:sync <feature> <task-NN-slug.md> in_progress
-/hapo:sync <feature> <task-NN-slug.md> blocked "reason"
-/hapo:sync <feature> <task-NN-slug.md> done
-/hapo:sync <feature> <task-NN-slug.md> sync-finalize
-/hapo:sync audit <feature>
+/cf:sync <feature> <task-NN-slug.md> in_progress
+/cf:sync <feature> <task-NN-slug.md> blocked "reason"
+/cf:sync <feature> <task-NN-slug.md> done
+/cf:sync <feature> <task-NN-slug.md> sync-finalize
+/cf:sync audit <feature>
 ```
 
 Resolve one regular direct-child task inside `specs/<feature>/`. Reject path

package/src/claude/skills/sync/references/sync-protocols.md

@@ -22,7 +22,7 @@ to change one task state.
   changes; retain the stale receipt only when clearly labelled non-authoritative.
 
 For Flash, keep `Status: in_progress`, `FLASH_UNVERIFIED`, and blocker
-`awaiting /hapo:test <feature>`. Only sync-finalize with fresh canonical proof
+`awaiting /cf:test <feature>`. Only sync-finalize with fresh canonical proof
 may replace that marker and set done.
 
 ## Receipt update