@haposoft/cafekit 0.16.0-rc.8 → 0.16.0

package/src/claude/skills/brainstorm/references/question-framework.md

@@ -1,232 +1,170 @@
 # Brainstorm Question Framework
 
-Use this reference to decide **what to ask**, **what not to ask**, and **how to record decisions** during `hapo:brainstorm`.
+Use this reference to ask the smallest set of questions that can materially
+change the selected route or design. It does not override front-door routing in
+`cf:brainstorm`.
 
-The goal is not to ask many questions. The goal is to ask the smallest set of questions that can materially change the design.
+## Contract gaps and accepted decisions
 
-## Source Hierarchy
+The four user-owned contract fields are Outcome, Constraints, Non-goals, and
+Acceptance. Evaluate them independently:
 
-Generate questions from this hierarchy, in order:
+- Reuse a field only when current user text or an approved artifact binds it to
+  the same target and revision.
+- Preserve a current non-conflicting field; do not ask the user to repeat it.
+- Treat a missing, stale, or conflicting field as unresolved and ask only when
+  it materially changes scope, safety, public behavior, or proof.
+- Never convert an assumption or old “approved” label into user acceptance.
+- Hydration never selects the route; classify the remaining request afterward.
 
-1. **Scout evidence** — repo type, framework, existing modules, docs, specs, plans, runtime config, and constraints.
-2. **User intent** — nouns, verbs, success language, target users, examples, and implied deliverables in the prompt.
-3. **Exact requirement gaps** — expected output, acceptance criteria, scope boundary, non-negotiable constraints, touchpoints.
-4. **Domain matrix** — only domains that actually apply to the request.
-5. **Risk matrix** — security, privacy, cost, runtime limits, provider failure, migration, compliance, maintainability.
+Technical touchpoints are evidence, not a fifth user-owned field. Derive paths,
+modules, schemas, APIs, and conventions from scouting; ask only when ownership or
+scope is genuinely a user decision.
 
-Never ask a question that the repository, docs, or trusted technical research can answer directly.
+## Source hierarchy
 
-## Ask / Do Not Ask
+Generate candidates in this order:
+
+1. Scout evidence: relevant code, docs, specs, plans, runtime, and constraints.
+2. User intent: outcome language, target users, examples, and delivery format.
+3. Missing or conflicting contract fields.
+4. Applicable Domain Matrix entries.
+5. Applicable risk surfaces.
 
-Ask the user when the answer changes:
+Never ask a question the repository, docs, or trusted technical research can
+answer directly.
 
-- product scope or MVP boundaries
-- target user workflow or UX surface
-- expected output artifact or delivery format
-- acceptance criteria
-- business priority, timeline, or rollout
-- cost, privacy, API-key ownership, external provider choice
-- irreversible workspace action such as renaming/moving/deleting
-- whether to accept a trade-off after you explain it
+## Ask / Do Not Ask
 
-Do **not** ask the user when the answer is a technical fact you should verify:
+Ask when the answer changes:
 
-- browser or runtime limits
-- package/API compatibility
-- dependency maintenance state
-- security best practice
-- exact syntax for framework config
-- existing code location, schema, endpoint, or convention
+- outcome, MVP boundary, non-goal, or acceptance evidence;
+- target user workflow, UX surface, or output artifact;
+- business priority, rollout, cost, privacy, provider/key ownership;
+- an irreversible workspace action or a public compatibility contract;
+- acceptance of a material trade-off after its consequences are explained.
 
-If a topic mixes user preference and technical fact, verify the technical facts first, then ask the preference question with those facts included.
+Do not ask for technical facts such as current code locations, schema shape,
+runtime/browser limits, package/API compatibility, dependency state, security
+practice, or framework syntax. Verify first, then ask only the remaining product
+or trade-off decision.
 
 ## Prioritization
 
-Before asking, score each candidate question:
+Score candidate questions before asking:
 
 | Signal | Score |
 |---|---:|
-| Could change architecture, data model, or platform | +3 |
-| Could change MVP scope or exclude a feature | +3 |
-| Could affect cost, privacy, security, or compliance | +3 |
-| Defines observable acceptance criteria | +2 |
-| Defines UX flow or primary user surface | +2 |
-| Can be answered from repo/docs/research | -4 |
-| Merely names an implementation detail with a safe default | -2 |
-
-Ask only the highest-impact question. If several are tied and independent, ask at most 3 in one `AskUserQuestion` batch; otherwise ask one at a time.
-
-## Required Decision Surfaces
-
-Every brainstorm must eventually resolve these surfaces:
+| Changes architecture, data model, platform, scope, privacy, security, or compliance | +3 |
+| Defines acceptance, primary flow, or user-visible output | +2 |
+| Answerable from code, docs, or research | -4 |
+| Safe implementation default only | -2 |
 
-| Surface | Question Intent |
-|---|---|
-| Outcome | What does the user expect to exist or happen after the work? |
-| Done | How will the user verify it works? |
-| Scope | What is explicitly not included now? |
-| Constraints | What cannot change: stack, platform, naming, runtime, compatibility, deadline? |
-| Touchpoints | Which existing files/modules/contracts will this affect? |
-
-If any surface is missing, ask a grounded question before proposing architecture.
+Ask the highest-impact question. Batch at most three tied, independent questions;
+otherwise ask one. Stop when the next answer would not change the contract.
 
 ## Domain Matrix
 
-Use only the domains that match the request.
+Use only matching domains. These are prompts for material gaps, not a checklist.
 
 ### Product / UX
 
-Ask when the prompt includes UI, workflow, dashboard, extension, app, or user-facing behavior.
-
-- Primary user: who uses this first?
-- Primary flow: what is the shortest successful path?
-- Surface: page, overlay, sidebar, modal, command, background task?
-- State: loading, empty, error, partial result, retry?
-- Accessibility or localization expectations?
+- Primary user and shortest successful flow?
+- Surface and loading/empty/error/partial/retry states?
+- Accessibility, localization, responsive, or native constraints?
 
 ### Browser Extension
 
-Ask when the work involves Chrome, Edge, Firefox, YouTube, DOM injection, content scripts, popup, options page, or browser APIs.
-
-- Target browser/runtime and manifest version?
-- UI surface: content overlay, sidebar, popup, options page, or all?
-- Permissions posture: minimal host permissions or broader convenience?
-- Storage: browser storage, IndexedDB, sync storage, or no persistence?
-- Publishing target: dev-only, Chrome Web Store, enterprise install?
-
-Verify instead of asking:
-
-- Manifest V3 service worker lifetime.
-- Browser-reserved shortcut conflicts.
-- Content script isolated-world vs main-world behavior.
-- Current Chrome API compatibility.
+- Browser/manifest target, UI surface, permission posture, storage, publishing?
+- Verify service-worker lifetime, shortcut conflicts, execution worlds, and API
+  compatibility rather than asking the user.
 
 ### AI / LLM
 
-Ask when the work involves translation, summarization, agents, prompt output, generation, or provider choice.
-
-- Provider ownership: user API key, app-owned key, proxy, or local model?
-- Provider shape: fixed provider, multi-provider, or custom base URL?
-- Output contract: prose, JSON, markdown, SRT, code, patch?
-- Failure behavior: retry, fallback, partial result, ask user, or stop?
-- Cache policy: never, per session, persistent, or shared?
-- Privacy boundary: what content may leave the browser/server?
+- Provider/key ownership, output contract, failure/fallback, cache, privacy?
+- Verify endpoint/auth shape, tool/schema/streaming support, and provider
+  compatibility rather than asking the user.
 
-Verify instead of asking:
+### Data / Documents / Media
 
-- Whether a provider is Anthropic-compatible vs OpenAI-compatible.
-- Whether a provider supports tool use / JSON schema / streaming.
-- Current API endpoint paths and auth header format.
-
-### Data / Transcript / Documents
-
-Ask when the work transforms documents, captions, data, logs, OCR, audio, video, or legacy code into another artifact.
-
-- Source priority and fallback order?
-- Output format and fidelity level?
-- Confidence / evidence tracking requirement?
-- Missing/unknown handling?
-- Export/import requirements?
+- Source priority, output format/fidelity, unknown/confidence handling, export?
 
 ### Backend / API / Database
 
-Ask when the work includes server endpoints, persistence, auth, jobs, integrations, or migrations.
-
-- API contract: endpoint, method, request/response shape?
-- Persistence: new table, existing table, no DB?
-- Auth/permission model?
-- Idempotency, retries, and background job behavior?
-- Migration and rollback constraints?
+- Public request/response behavior, identity/permissions, persistence,
+  idempotency/retry, migration and rollback?
 
 ### Docs / Legacy Reconstruction
 
-Ask when the work is documentation, legacy analysis, or requirement reconstruction.
-
-- Scope path/module to reconstruct?
-- Output docs required: overview, requirements, architecture, evidence map, unknowns?
-- Evidence level: observed-only or inferred allowed with confidence?
-- Review gate: who approves the reconstructed docs?
-- Change request follows reconstruction or is separate?
+- Scope, required artifacts, allowed inference/evidence level, human review,
+  and whether a later change request is separate?
 
 ### Release / Packaging
 
-Ask when the work includes publish, store listing, npm release, versioning, or deployment.
-
-- Target release channel?
-- Version bump type?
-- Required checks before publish?
-- Store/listing metadata ownership?
-- Rollback or deprecation plan?
+- Channel, version intent, required checks, metadata ownership, rollback?
 
-## Question Format
+## Risk surfaces
 
-Use `AskUserQuestion` when available.
+Raise only risks that can change the contract or approval path:
 
-- Use 2-4 concrete options.
-- Put the recommended option first and label it `(Recommended)`.
-- Include a one-sentence impact description per option.
-- Do not add an explicit "Other" option; the tool supplies it.
-- Avoid abstract labels like "Option A" unless paired with concrete meaning.
+- **Critical section decision:** auth/secrets/privacy; destructive/irreversible
+  behavior or data loss; money/privilege/safety; production-state mutation.
+- **Other material risks:** external-provider failure, cost limits, migration,
+  compatibility, concurrency, compliance, maintainability, or unavailable proof.
 
-Good:
+Explain the verified risk and viable consequences before asking. Do not create a
+ceremonial risk matrix.
 
-> "Where should transcript fallback live?"
-> - "Defer STT for MVP (Recommended)" — Ships faster; no fragile audio extraction now.
-> - "Browser-only STT" — No backend, but fragile and heavy.
-> - "Companion backend" — More robust, but requires hosting and ops.
+## Evidence calibration
 
-Bad:
+Keep these independent in every recommendation:
 
-> "What architecture do you want?"
+- **Feasibility:** `confirmed | plausible | unknown | infeasible`.
+- **Confidence:** `high | medium | low`.
+- **Disposition:** `chosen | rejected | deferred`.
 
-## Explain Before Asking
+Every value cites its repository/current-research evidence or stated basis.
+Missing evidence forces feasibility `unknown` and confidence `low`; it never
+becomes a confident guess. A numeric estimate is valid only with range, unit,
+basis, evidence, and assumptions. Otherwise write `unknown`, not a factual
+number. Record why an inapplicable Deep lens was skipped so selective analysis
+is auditable without forcing ceremony.
 
-When the user cannot reasonably know the answer, first explain the trade-off briefly, then ask.
+## Question format
 
-Use this pattern:
+Use the runtime's native structured user-input tool when available.
 
-1. State why the decision matters.
-2. Give 2-3 viable options with consequences.
-3. Recommend one.
-4. Ask the user to confirm or override.
-
-Do not force a choice before explaining hidden technical risk.
+- Give 2–4 concrete options and put the recommended one first.
+- Explain one consequence per option; do not use abstract “Option A” labels.
+- Do not add an explicit Other choice when the runtime supplies it.
+- If the user cannot know a hidden technical fact, explain it before asking.
 
 ## Decision Register
 
-Every final brainstorm report must include a decision register.
-
-```markdown
-## Decision Register
+For a durable delivery summary, record only decisions actually made:
 
-| ID | Question | Options Presented | User Decision | Rationale | Impact |
+| ID | Question | Options | User Decision | Rationale | Impact |
 |---|---|---|---|---|---|
-| D-001 | Where does transcript fallback live? | Defer STT / Browser-only / Backend | Defer STT | Ships MVP safely | Phase 7 becomes graceful fallback |
-```
-
-Rules:
-
-- Record only decisions actually made by the user or explicitly accepted in chat.
-- Do not write "user selected" unless `AskUserQuestion` or direct user text confirms it.
-- If you infer a default, label it as `Assumption`, not `User Decision`.
-- Carry unresolved decisions into `Open Questions`.
-
-## Maximum Question Budget
+| D-001 | <material choice> | <options shown> | <confirmed answer> | <why> | <effect> |
 
-Default budget:
+- Do not write "user selected" unless direct user text or the native input tool
+  confirms it.
+- Label inferred defaults as `Assumption`, not `User Decision`.
+- Carry truly blocking unknowns into `Open Questions`; defer safe defaults.
 
-- Small change: 1-2 questions.
-- Medium feature: 3-6 questions.
-- Large/greenfield/architecture-heavy: 6-10 questions across multiple rounds.
+## Question budget
 
-Stop asking when the next question would only refine an implementation detail with a safe default. Propose the design and list remaining assumptions instead.
+- Small change: usually 1–2.
+- Medium feature: usually 3–6.
+- Large or architecture-heavy work: usually 6–10 across rounds.
 
-## Final Self-Check
+Budgets are ceilings, not targets. Non-bug exploration may need no approval
+question; an accepted contract may need only one missing-field question.
 
-Before presenting design:
+## Final self-check
 
-- Did each asked question map to one of the required decision surfaces or domain risks?
-- Did any question ask the user to answer a technical fact that should have been researched?
-- Are all user decisions captured in the decision register?
-- Are assumptions clearly separated from user decisions?
-- Are open questions truly blocking, or can they be deferred?
+- Did direct routing happen before scout and questions?
+- Is each question tied to a user-owned contract field or material risk?
+- Were technical facts discovered instead of delegated to the user?
+- Are decisions, assumptions, and open questions separated?
+- Would another question materially change the outcome?

package/src/claude/skills/chrome-devtools/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: hapo:chrome-devtools
+name: cf:chrome-devtools
 description: Automate browsers with Puppeteer CLI scripts and persistent sessions. Use for screenshots, performance analysis, network monitoring, web scraping, form automation, JavaScript debugging.
 license: Apache-2.0
 user-invocable: true

package/src/claude/skills/code-review/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: hapo:code-review
+name: cf:code-review
 description: "Review a change for correctness, security, and specification compliance without owning execution proof."
 user-invocable: true
 when_to_use: "Use for a pending diff, commit, PR, or explicitly scoped review."
@@ -14,14 +14,21 @@ metadata:
 
 Review evaluates correctness, security, scope, architecture, and specification
 compliance. It does not execute the test suite, create a canonical execution
-receipt, or turn a missing test result into a review-owned proof. `hapo:test`
+receipt, or turn a missing test result into a review-owned proof. `cf:test`
 owns execution proof; the single closeout owner combines both results.
 
 ## Input and depth
 
 With no argument, review the pending diff. Supported targets are a PR, commit,
-pending changes, or an explicit path. Load only the spec and references needed
-for the target.
+pending changes, or an explicit path. Load only current target bytes and needed
+references. For a valid process-first target, read `plan.md`, the active flat
+`task-NN-*.md`, and the controller-validated `test-proof-v1` handoff. Mixed,
+orphaned, malformed, symlinked, nonregular, or identity-conflicting packet state
+is `BLOCKED`; review never migrates it.
+
+For process-first proof consumption, this skill's `## Execution-proof boundary`
+is authoritative. Do not load or follow legacy separate-receipt paragraphs from
+references; they apply only after the Legacy route below is selected.
 
 Select review depth from `assurance_level`, risk, and blast radius. Lane is a
 derived view:
@@ -38,10 +45,9 @@ fixed Light/Standard/Deep sequence.
 
 ### 1. Specification compliance
 
-Compare the diff with `scope_lock`, requirements, design contracts, active task
-Outcome/Scope/Anchors and Ownership/Changes/Acceptance/Dependencies/
-`Verification Plan`, typed `coordination.boundaries`, and declared
-runtime reachability. Identify missing behavior,
+For process-first work, compare the diff with current plan scope and the active
+task's Outcome, Scope, Coverage, Ownership, Acceptance, Dependencies,
+Verification Plan, and declared runtime reachability. Identify missing behavior,
 unjustified extras, contract substitution, orphaned outputs, and incorrect
 completion claims. If a design image or document carries requirements, load its
 multimodal reference only when needed; do not guess from a filename.
@@ -69,18 +75,20 @@ provenance is insufficient.
 
 ## Execution-proof boundary
 
-Consume the current canonical receipt when available and report its identity,
-scope, and caveats. Never rerun commands to manufacture proof. If execution
-proof is missing, say `execution proof unavailable` and leave the overall
-closeout to the test owner; do not claim PASS on the feature from review alone.
-A review can still return a correctness verdict when its review inputs are
-complete.
-
-For new tasks, read proof from `receipts/<task-basename>.md`; use legacy task
-`## Evidence` only as fallback. If both exist and their proof identities
-conflict, fail closed. At feature closeout also consume `feature-receipt.md`.
-Receipt validity never supplies approval, readiness, audit status, or product
-semantics.
+For process-first work, consume only the controller-validated `test-proof-v1`
+handoff. Require its exact closed schema, stable digest, current Base/Head,
+target task, exact command, exit/counts, raw output, reachability, proof level,
+artifacts, branches, and redactions. Unknown keys/verdicts, duplicate or missing
+branches, stale provenance, zero execution, required skips, unsafe redaction, or
+`PASS_WITH_WARNINGS` remain unfinished. Never create or search for a separate
+process-first receipt; Develop alone writes Status and inline `## Receipt` after
+proof and review are both literal `PASS`.
+
+Never rerun commands to manufacture proof. If execution proof is missing or
+invalid, say `execution proof unavailable` and leave closeout unfinished; do not
+claim feature PASS from review alone. A review may still return a correctness
+verdict when its review inputs are complete, but that verdict is not execution
+proof or C3 approval.
 
 ## Verdict
 
@@ -99,12 +107,12 @@ closeout result; only literal `PASS` can finish a task. `BLOCKED` means the revi
 decision is unavailable.
 
 ```markdown
-# Code Review Results [hapo:code-review]
+# Code Review Results [cf:code-review]
 
 **Verdict:** PASS | PASS_WITH_WARNINGS | FAIL | BLOCKED
 **Target:** [PR | Commit | Path]
 **Assurance / risk:** [canonical policy input and relevant signals]
-**Execution proof:** consumed | unavailable (owned by hapo:test)
+**Execution proof:** test-proof-v1 consumed | unavailable (owned by cf:test)
 
 ## Findings
 - [Critical|High|Medium|Low] path:line — issue, failure scenario, evidence,
@@ -119,10 +127,20 @@ decision is unavailable.
 Do not add a test command, a fabricated receipt, or an `Audit: PASS` marker to
 make the review look complete. Return unresolved questions at the end.
 
+## Legacy workflow compatibility
+
+For a valid legacy packet only, retain its current spec/task resolution,
+separate `receipts/<task-basename>.md` fallback, feature receipt, persisted audit
+obligations, and legacy verdict normalization. If separate and embedded legacy
+proof identities conflict, fail closed. Never copy that adapter into a flat
+process-first packet.
+
 ## References
 
-- `references/spec-compliance-review.md` — load for detailed scope checks.
+- `references/spec-compliance-review.md` — load only its detailed scope checks;
+  its separate-receipt paragraph is Legacy-only.
 - `references/pre-landing-checklists.md` — load for the selected risk surface.
 - `references/adversarial-review.md` — load for Critical/adversarial depth.
-- `references/verification-gate.md` — receipt consumption only; execution stays
-  with `hapo:test`.
+- `references/verification-gate.md` — Legacy separate-receipt consumption only;
+  process-first proof uses this skill's execution-proof boundary. Execution
+  always stays with `cf:test`.

package/src/claude/skills/code-review/references/spec-compliance-review.md

@@ -1,6 +1,6 @@
 ---
 name: spec-compliance-review
-description: Hapo native protocol for verifying core implementation requirements using multimodal visual validation via ai-multimodal.
+description: Hapo native protocol for verifying core implementation requirements, using multimodal visual validation when available.
 ---
 
 # Spec Compliance Review (Stage 1)
@@ -19,8 +19,7 @@ Do not attempt a standard text-based review if the project includes Visual Specs
 
 **Spec Detection Algorithm:**
 1. Check if the `.specs/` directory, user instructions, or Jira tickets contain attached Image files (`.png`, `.jpg`, `.svg`) or Documents (`.pdf`).
-2. If YES: IMMEDIATELY halt static code analysis. Delegate the generated Frontend code / Logic code along with the Image/PDF to the **`hapo:ai-multimodal` analysis gateway**.
-   - *Prompt:* "Hey `hapo:ai-multimodal`, please look at this design mockup/document and compare it with the layout/logic described in this Code. Are there any discrepancies?"
+2. If YES: use **`cf:ai-multimodal` when installed**, or the runtime's available multimodal capability. If neither is available, mark visual comparison `UNPROVEN` and continue the non-visual review.
 3. If NO (Markdown Spec only): Read the spec directly and extract:
    - requirement bullets
    - task `Outcome`, `Scope`, `Anchors and Ownership`, `Changes`, `Acceptance`,
@@ -42,7 +41,7 @@ Each Requirement in the Spec must return 1 of 3 states:
 - `[PASS]` Fully implemented. Proceed to Code Quality Review.
 - `[MISSING]` Forgotten feature. Force the Developer to add it immediately (BLOCK MERGE).
 - `[EXTRA]` The code has bloated with spontaneous features not in the spec card. If unjustified -> FAIL.
-- `[VISUAL_MISMATCH]` (For UI Design): The report from `ai-multimodal` indicates this screen will break layout or violate the Design System.
+- `[VISUAL_MISMATCH]` (For UI Design): Available multimodal evidence indicates this screen will break layout or violate the Design System.
 - `[UNPROVEN]` Required artifact/runtime behavior or verification evidence is missing, so completion cannot be trusted.
 
 ## 4. Red Flags

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

@@ -25,7 +25,7 @@ To clear the Verification Gate, you must cite one of the following concrete proo
 - **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:** `hapo:ai-multimodal` confirming that the visual rendering perfectly matches the design layout.
+- **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