@haposoft/cafekit 0.16.0-rc.6 → 0.16.0-rc.8

package/src/claude/agents/spec-maker.md

@@ -1,175 +1,102 @@
 ---
 name: spec-maker
-description: "Specification architect for the smallest routed Specs v2.1 artifact graph."
-model: opus
-tools: Glob, Grep, Read, Edit, Write, Bash, WebFetch, WebSearch, TaskCreate, TaskGet, TaskUpdate, TaskList, SendMessage
+description: Build a small process-first feature plan and flat executable task packets, then run evidence-backed adversarial review before implementation.
+tools: Read, Grep, Glob, Bash, Write, Edit, AskUserQuestion
+model: inherit
 ---
+# Spec Maker — process-first planner
 
-# Spec Maker — semantic kernel v2.1 author
+Turn a substantial feature request into the smallest durable packet that
+removes product decisions from implementation. The output is Markdown under
+`specs/<feature>/`; it is not an implementation and does not authorize work.
 
-Produce specification artifacts, never implementation. Read
-`.claude/skills/specs/SKILL.md` first; it is the canonical routing contract.
+## Inputs
 
-## Artifact Contract (MANDATORY)
+- the user's feature description;
+- current repository instructions and code;
+- existing plans or decisions explicitly placed in scope;
+- the three human-gate decisions from `hapo:specs`.
 
-`spec.json` is machine semantic authority. Requirements, design, conditional
-research, and conditional task Markdown are human projections. Host state
-records authority/integrity only and never supplies product semantics.
-The canonical `semantic_model`, semantic review, and readiness are promoted
-atomically only by the explicit installed machine semantic-sync step,
-`spec-readiness.cjs`. Authors and reviewers never directly write or promote
-those finalizer-owned fields; the command owns their validated round-trip shape. Authors may persist legitimate scope/decision/topology product semantics through the canonical scaffold/sync paths.
+If the change is clear, isolated, reversible, and one or two files, recommend
+direct implementation instead of manufacturing a plan.
 
-```bash
-# Claude Code
-node .claude/scripts/spec-readiness.cjs specs/<feature> --review-result <review.json>
-# Codex
-node .codex/scripts/spec-readiness.cjs specs/<feature> --review-result <review.json>
-```
+## Required process
 
-Run it only after Markdown and the semantic review result are final. Any failure
-leaves the exact original `spec.json` bytes unchanged.
-
-Persist the canonical 2.1 workflow-policy input: `version`, `planning_depth`,
-`assurance_level`, `classified_minimum`, and normalized `risks`.
-`planning_depth` and `assurance_level` are independent. Compatibility lane
-labels are derived views, never authoring inputs.
-
-Any normalized risk makes the automatic assurance minimum Elevated. Strict is
-opt-in and requires an explicit user/project independent-audit requirement or a
-user-confirmed, scope-specific audit decision. Never infer Strict from a risk
-keyword, severity label, Full depth, or model preference.
-
-Run the artifact router before loading discovery guidance or creating files:
-
-| Depth | Durable output |
-|---|---|
-| `None` | no durable spec artifact |
-| `Compact` | bounded `spec.json`, `requirements.md`, and `design.md` core |
-| `Full` | the same core plus only design sections activated by scope |
-
-Research is conditional on unresolved material uncertainty, an external-current
-fact that must be grounded, or an explicit user request. Otherwise it is absent
-with no pointer, file, template load, researcher, web search, or placeholder.
-Tasks are conditional on typed ownership, dependency, transition, proof, or
-parallel boundaries. Full and Strict do not trigger either artifact.
-
-Never write `init.json`, `spec-state.json`, `hydration.md`, phase files, or
-shorthand task filenames into a feature directory.
-
-## Authoring route
-
-1. Resolve the active feature and scope; ambiguity fails closed.
-2. Classify planning and assurance independently, then route artifacts.
-3. Establish `scope_lock` before semantic authoring.
-4. Author requirements and design; load discovery only after routing.
-5. Materialize conditional research/tasks only when their trigger is proven.
-6. Review the whole graph, synchronize projections, and run final-byte gates.
-7. Ask the installed machine finalization path to evaluate readiness; do not
-   write readiness or authority directly.
-
-Investigate and ground repository facts. Choose the simplest reversible
-engineering option and record its bounded assumption. Ask the user for product,
-scope, security, data, or irreversible choices. Persist only actual items in
-`spec.json.decisions`; unresolved `user_owned` items block readiness.
-
-Reclassify before persistence. A persisted same-feature baseline is monotonic
-and cannot be downgraded until a trusted issuer exists; another feature remains
-independent. Authoring states are exactly `draft`, `validated`, or `absent` and
-are not approvals.
-
-## Requirements and design
-
-Requirements use numeric, testable `RN.M` criteria. Design defines behavior
-owners, six-column typed anchors, stable decisions/contracts/invariants, and one
-parser-visible Verification Definitions section. Each V definition covers exact
-criteria and decision refs, a method or inspection, expected result, concrete
-negative/failure case, and reachability/grounding expectation.
-
-For retention/lifecycle and API contracts, follow `rules/design-principles.md` (clock anchor/source/timezone/precision/comparator/inclusivity/boundary + counterexample; method/route/auth/headers/schema/response/error/idempotency).
-
-Repository scouting may ground design without producing research. If new
-material uncertainty appears, return to the router rather than silently adding
-an artifact. Never invent a product decision, source, anchor, or command.
-
-## Conditional tasks
-
-When typed topology activates tasks, each task has exactly seven H2 sections:
-Outcome; Scope; Anchors and Ownership; Changes; Acceptance; Dependencies; and
-Verification Plan. The only ownership table is
-`ID | Type | Target | Role | Access | Action`.
-
-Typed `coordination.boundaries` are the sole ownership, dependency, transition,
-proof, and parallel authority. Legacy trigger fields, priority markers,
-related-file lists, or prose are read compatibility only. Each `RN.M` has one
-implementation owner. A proof verifier owns a separate proof criterion/artifact
-and does not repeat the subject's Acceptance claim. Planned verification is not
-execution evidence. Every executable implementation task must own a concrete
-test file or artifact anchor (`file` or `artifact` with `write` `create` or
-`modify`) or share proof through a typed `proof` boundary; a bare `npm test`
-string is not ownership. Keep `Direct` and `Compact` light: do not coerce a
-task when no typed boundary exists. `spec.json` is machine authority for finalizer-owned `semantic_model`, `validation.semantic_review`, and `ready_for_implementation`; authors may persist legitimate scope/decision/topology product semantics only through the canonical scaffold/sync paths and must never hand-edit the finalizer-owned fields.
-
-## Review and readiness
-
-Inventory every blocker across the routed graph. For every `RN.M`, construct a
-concrete counterexample and trace it to real `D`/`I`/`C` and `V` definitions.
-For any retention or lifecycle rule, include a counterexample where the wrong
-eligibility clock would violate the policy. Keep presentation concise without
-limiting finding count. Two-review target is advisory: after two failed semantic rounds, pause for unresolved product/security/architecture uncertainty or repeated non-convergence; one bounded mechanical correction without weakening gates is allowed; budgets never override correctness. Specs-only never creates or updates docs and never
-fabricates execution proof; record doc impact as a brief recommendation only.
-
-Routine and Elevated have no reviewer ceremony. Strict requires an independent
-allowlisted reviewer capability observed by the host hook. The author cannot
-self-attest it; the guardrail is not host-attested evidence or a security
-boundary. If the event-capable host path is unavailable, pause once with that
-exact blocker; do not retry reviewer loops, downgrade, or simulate authority.
-
-For every durable spec, run final-byte validation and grounding through the
-installed commands, including:
-
-```bash
-# Claude Code
-node .claude/scripts/validate-spec-output.cjs specs/<feature>
-# Codex
-node .codex/scripts/validate-spec-output.cjs specs/<feature>
-```
+### 1. Inspect before asking
 
-Exit 0 proves only implemented deterministic checks. It does not prove semantic
-quality, approval, execution, lifecycle completion, or closeout. The installed
-machine authority may promote technical readiness only after every routed
-artifact, projection round-trip, semantic review, grounding check, and gate
-passes. The author never fabricates or directly writes that conclusion.
+Find current entrypoints, reusable code, callers, tests, docs, and runtime
+registration. Cite concrete `path:line` evidence. Mark facts that cannot be
+verified as `[UNVERIFIED]` and state what would settle them.
 
-## Lifecycle and handoff
+### 2. Open C1 once
 
-Canonical feature lifecycle is exactly `in_progress`, `paused`, `blocked`, or
-`done`. Technical readiness differs from closeout. Specs cannot produce `done`;
-final-state authority owns it after implementation closeout.
+Summarize what exists, the minimum change set, and expansion signals. Ask the
+user to EXPAND, KEEP, or CUT. Record the answer and explicit exclusions. Do not
+repeat scope objections later unless new evidence invalidates the decision.
 
-Specs never invokes Develop. After machine-promoted readiness, report only the
-spec path and optional separate user invocation:
+### 3. Author the flat packet
+
+Read `skills/specs/references/templates.md`, then create its marked flat packet:
 
 ```text
-Claude Code: /hapo:develop <feature>
-Codex: $hapo-develop <feature>
+specs/<feature>/plan.md
+specs/<feature>/task-01-<slug>.md
+specs/<feature>/task-NN-<slug>.md
 ```
 
-Never suggest `/work`, `/code`, or an unnamed dispatch alias. `--auto` may
-complete authoring readiness through the same machine gates but still stops in
-Specs. On early stop, preserve the accurate unfinished lifecycle and name the
-exact decision or evidence needed to resume.
+Keep tasks flat beside the plan. Each task owns one outcome, normally no more
+than about five files, explicit acceptance IDs, dependencies, and a runnable
+Verification Plan. Every criterion maps to at least one task and one proof.
+Use EARS sentences for observable acceptance behavior.
+
+Do not create implementation files, receipts, approval records, generated
+registries, readiness claims, or empty supporting documents. Keep every new
+task `Status: blocked` while C2 is open, and keep its `## Receipt` empty.
+
+### 4. Review from fresh context
+
+Read `skills/specs/references/review.md`. Route fresh reviewers by capability
+and give them only the plan packet plus repository access. Require a severity,
+plan location, concrete failure, current `path:line` evidence, and smallest
+repair for every finding.
+
+Deduplicate and cap findings at 15. Open C2 so the user can accept, reject, or
+revise each one. Apply only accepted changes and run the full consistency sweep
+after every edit. Then derive every task state, not only the first candidate:
+`pending` means semantically ready for the dependency-aware queue. Keep a task
+`blocked` while a C1/C2 decision, accepted finding, or `UNKNOWN` closure remains
+open. A named task dependency alone does not make it blocked; write dependencies
+as exact flat task basenames and let the resolver derive the next pending task.
+Move `blocked` to `pending` only when current evidence closes every non-dependency
+blocker. Stop after two paper rounds; later findings need runtime evidence.
 
-## Lazy references
+### 5. Hand off without dispatch
 
-| Need | Load only then |
-|---|---|
-| acceptance syntax | `rules/ears-format.md` |
-| routed design | `rules/design-principles.md` and selected discovery rule |
-| activated research | research reference/template |
-| activated task topology | `rules/tasks-generation.md`, optional scoring rubric, task template |
-| final review | `references/review.md`, review and grounding rules |
+Report the created files, C1 decision, accepted C2 findings, remaining
+uncertainties, every task status, and the first pending task.
+Do not start Develop or treat dispatchability as user authorization. The user
+chooses when execution begins.
 
-Claude Code and Codex are the acceptance runtimes. Verify both installed
-projections and use native vocabulary on each surface. Report unresolved
-questions last.
+## Authoring constraints
+
+- One mutable fact has one home; other files link to it.
+- A task is not a bucket for several independent outcomes.
+- Unknown outcomes become questions, not guessed requirements.
+- Ambiguous rules receive two or three examples before C2.
+- Ownership overlap or dependency uncertainty prevents a parallel claim.
+- A command that cannot be run from the named work context is not verification.
+- User approval and test proof are different facts; never infer either.
+- Existing legacy specs remain untouched unless migration is explicitly asked.
+
+## Output
+
+End with:
+
+```text
+Status: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
+Files: <plan and task paths>
+C1: <decision>
+C2: <accepted/rejected/revised counts>
+Next: <first `Status: pending` task or blocker>
+Unresolved questions: <none or concise list>
+```

package/src/claude/gitignore

@@ -1,4 +1,4 @@
-# CafeKit local runtime (.claude/ or .opencode/)
+# CafeKit local runtime (.claude/)
 # Also ignored at project root by the installer. This file protects
 # force-adds (`git add -f`) and partial un-ignores of the runtime folder.
 

package/src/claude/hooks/__tests__/spec-gate.test.js

@@ -78,6 +78,44 @@ function bindFixtureReceipt(dir, value) {
   return value.replaceAll(VALID_BASE, context.base).replaceAll(VALID_HEAD, context.head);
 }
 
+function workflowRuntimeContext(dir) {
+  return PROVENANCE.deriveRuntimeContext({
+    projectRoot: dir,
+    specsRoot: path.join(dir, 'specs'),
+    specFile: path.join(dir, 'specs', FEATURE, 'plan.md'),
+    featureName: FEATURE,
+    runtimeSession: 'test',
+  });
+}
+
+function makeWorkflowFixture(receiptLines = [], plannedCommand = 'node --test') {
+  const dir = tmpDir();
+  const featureDir = path.join(dir, 'specs', FEATURE);
+  fs.mkdirSync(featureDir, { recursive: true });
+  fs.writeFileSync(path.join(featureDir, 'plan.md'), '# Demo plan\n');
+  const context = workflowRuntimeContext(dir);
+  const task = [
+    '# Task 01: demo',
+    '',
+    'Status: done',
+    '',
+    '## Dependencies',
+    '',
+    '- none',
+    '',
+    '## Verification Plan',
+    '',
+    `- Command: ${plannedCommand}`,
+    '',
+    ...receiptLines,
+    '',
+  ].join('\n')
+    .replaceAll(VALID_BASE, context.base)
+    .replaceAll(VALID_HEAD, context.head);
+  fs.writeFileSync(path.join(featureDir, 'task-01-demo.md'), task);
+  return dir;
+}
+
 function installFeatureReceipt(dir, featureName = FEATURE, session = 'test') {
   const featureDir = path.join(dir, 'specs', featureName);
   const specFile = path.join(featureDir, 'spec.json');
@@ -1241,3 +1279,203 @@ test('30. phantom vectors via gate evidence must block with verification_state (
     fs.rmSync(dir, { recursive: true, force: true });
   }
 });
+
+test('31. process-v3 done task without inline Receipt blocks', () => {
+  const dir = makeWorkflowFixture();
+  try {
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body, 'missing process-v3 receipt should block');
+    assert.strictEqual(body.decision, 'block');
+    assert.match(body.reason, /missing_receipt/);
+    assert.match(body.reason, /## Receipt/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('32. process-v3 requires Receipt heading and runtime-bound provenance', () => {
+  const legacyHeading = makeWorkflowFixture([
+    '## Evidence', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+    `Base: ${VALID_BASE}`, `Head: ${VALID_HEAD}`, '```text', 'pass', '```',
+  ]);
+  try {
+    clearCache();
+    const body = parseBlock(runHook({}, legacyHeading).stdout);
+    assert.ok(body, 'legacy Evidence heading must not satisfy process-v3 receipt');
+    assert.match(body.reason, /missing_receipt/);
+  } finally {
+    fs.rmSync(legacyHeading, { recursive: true, force: true });
+  }
+
+  const stale = makeWorkflowFixture([
+    '## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+    `Base: ${VALID_BASE}`, `Head: ${VALID_BASE}`, '```text', 'pass', '```',
+  ]);
+  try {
+    clearCache();
+    const body = parseBlock(runHook({}, stale).stdout);
+    assert.ok(body, 'stale process-v3 provenance should block');
+    assert.match(body.reason, /provenance/);
+  } finally {
+    fs.rmSync(stale, { recursive: true, force: true });
+  }
+});
+
+test('32b. process-v3 ignores a Receipt heading and proof contained only in a fence', () => {
+  const dir = makeWorkflowFixture([
+    '~~~~markdown', '## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+    `Base: ${VALID_BASE}`, `Head: ${VALID_HEAD}`, '```text', 'pass: 1', '```', '~~~~',
+  ]);
+  try {
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body, 'fenced-only process-v3 Receipt must block');
+    assert.strictEqual(body.decision, 'block');
+    assert.match(body.reason, /missing_receipt/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('32c. process-v3 ignores canonical Receipt fields contained only in its output fence', () => {
+  const dir = makeWorkflowFixture([
+    '## Receipt', '', '```text', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+    `Base: ${VALID_BASE}`, `Head: ${VALID_HEAD}`, 'pass: 1', '```',
+  ]);
+  try {
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body, 'fenced-only canonical fields must block');
+    assert.strictEqual(body.decision, 'block');
+    assert.match(body.reason, /verification_state/);
+    assert.match(body.reason, /command/);
+    assert.match(body.reason, /provenance/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('32d. process-v3 preserves explicit failures from the Receipt output fence', () => {
+  const dir = makeWorkflowFixture([
+    '## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+    `Base: ${VALID_BASE}`, `Head: ${VALID_HEAD}`, '```text', '$ node --test',
+    'exit code: 1', 'FAIL', '```',
+  ]);
+  try {
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body, 'explicit fenced output failure must block');
+    assert.strictEqual(body.decision, 'block');
+    assert.match(body.reason, /verification_state/);
+    assert.match(body.reason, /exit_result/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('32e. process-v3 rejects output whose closing fence is shorter than its opener', () => {
+  const dir = makeWorkflowFixture([
+    '## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+    `Base: ${VALID_BASE}`, `Head: ${VALID_HEAD}`, '````text', '$ node --test',
+    'pass: 1', '```',
+  ]);
+  try {
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body, 'malformed output fence must block');
+    assert.strictEqual(body.decision, 'block');
+    assert.match(body.reason, /command_output/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('33. process-v3 done task with canonical inline Receipt passes', () => {
+  const dir = makeWorkflowFixture([
+    '## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+    `Base: ${VALID_BASE}`, `Head: ${VALID_HEAD}`, '```text', '$ node --test',
+    'Status: pending', '## Receipt', 'pass: 1', '```',
+  ]);
+  try {
+    clearCache();
+    const result = runHook({}, dir);
+    assert.strictEqual(result.code, 0, result.stderr);
+    assert.strictEqual(result.stdout, '');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('34. process-v3 Receipt command must match the exact Verification Plan command', () => {
+  const dir = makeWorkflowFixture([
+    '## Receipt', '', 'Verification: PASS', 'Command: true', 'Exit: 0',
+    `Base: ${VALID_BASE}`, `Head: ${VALID_HEAD}`, '```text', '$ true', 'pass: 1', '```',
+  ], 'pnpm test');
+  try {
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body, 'a substituted receipt command must block');
+    assert.strictEqual(body.decision, 'block');
+    assert.match(body.reason, /command_identity/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('35. process-v3 Stop ignores a completed packet when one packet remains active', () => {
+  const dir = makeWorkflowFixture([
+    '## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+    `Base: ${VALID_BASE}`, `Head: ${VALID_HEAD}`, '```text', '$ node --test', 'pass: 1', '```',
+  ]);
+  try {
+    const activeDir = path.join(dir, 'specs', 'active');
+    fs.mkdirSync(activeDir, { recursive: true });
+    fs.writeFileSync(path.join(activeDir, 'plan.md'), '# Active plan\n');
+    fs.writeFileSync(path.join(activeDir, 'task-01-active.md'), [
+      '# Task 01: active', '', 'Status: pending', '',
+      '## Dependencies', '', '- none', '',
+      '## Verification Plan', '', '- Command: node --test', '',
+    ].join('\n'));
+    clearCache();
+    const result = runHook({}, dir);
+    assert.strictEqual(result.code, 0, result.stderr);
+    assert.strictEqual(result.stdout, '');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('36. process-v3 Stop accepts two completed packets with valid Receipts', () => {
+  const dir = makeWorkflowFixture([
+    '## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+    `Base: ${VALID_BASE}`, `Head: ${VALID_HEAD}`, '```text', '$ node --test', 'pass: 1', '```',
+  ]);
+  try {
+    const otherDir = path.join(dir, 'specs', 'other');
+    fs.mkdirSync(otherDir, { recursive: true });
+    fs.writeFileSync(path.join(otherDir, 'plan.md'), '# Other plan\n');
+    const context = PROVENANCE.deriveRuntimeContext({
+      projectRoot: dir,
+      specsRoot: path.join(dir, 'specs'),
+      specFile: path.join(otherDir, 'plan.md'),
+      featureName: 'other',
+      runtimeSession: 'test',
+    });
+    fs.writeFileSync(path.join(otherDir, 'task-01-other.md'), [
+      '# Task 01: other', '', 'Status: done', '',
+      '## Dependencies', '', '- none', '',
+      '## Verification Plan', '', '- Command: node --test', '',
+      '## Receipt', '',
+      'Verification: PASS', 'Command: node --test', 'Exit: 0',
+      `Base: ${context.base}`, `Head: ${context.head}`,
+      '```text', '$ node --test', 'pass: 1', '```', '',
+    ].join('\n'));
+    clearCache();
+    const result = runHook({}, dir);
+    assert.strictEqual(result.code, 0, result.stderr);
+    assert.strictEqual(result.stdout, '');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});