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

package/src/claude/rules/manage-docs.md

@@ -54,39 +54,58 @@ Use [Keep a Changelog](https://keepachangelog.com/) convention:
 
 ---
 
-## Specification & Execution Tracker (Hapo Protocol)
+## Process-first specification and execution tracker
 
-### Where Specs Live
-Hapo does not use chaotic plan folders. Requirements and architecture are centralized into a machine-readable Specification structure via `specs`.
+### Where plans live
 
-All specifications exist strictly in `./specs/<feature-slug>/`.
+Keep every new feature packet in one direct child of `./specs/`. The Markdown
+files are the durable state and must remain readable without a compiler or a
+generated index.
+
+### Primary directory layout
 
-### Directory Layout
 ```text
 specs/
 └── user-auth/
-    ├── spec.json               # System state machine & global status
-    ├── design.md               # Architecture, requirements, and data flows
-    └── tasks/
-        ├── task-R0-01-setup.md  # Actionable granular steps for development
-        └── task-R1-01-api.md    # Next requirement-driven task
+    ├── plan.md
+    ├── task-01-setup.md
+    └── task-02-api.md
 ```
 
-### The State Machine (`spec.json`)
-The `spec.json` is the sole source of truth for the Project State. 
-When creating or updating a spec, it must accurately reflect the overall progress.
+Task files are direct children beside `plan.md`; do not place them in a task
+subdirectory.
+The plan records the C1 scope decision, explicit exclusions, acceptance
+criteria, and task mapping. Each task owns one usable outcome, bounded paths,
+dependencies, acceptance, and a runnable Verification Plan.
+
+### Gates and execution handoff
+
+- C1: the user chooses EXPAND, KEEP, or CUT before the plan is written.
+- C2: the user accepts, rejects, or revises deduplicated adversarial findings.
+- Specs stops after planning; implementation begins only through a new explicit
+  Develop invocation.
+- C3: after execution, current receipts and limitations are shown and the user
+  decides whether the feature is complete.
 
-### Architecture Document (`design.md`)
-This blueprint covers:
-- **Context & Overview:** The "Why" of the feature.
-- **Data Flow:** Mandatory Mermaid Data Flow Diagram detailing state transitions, DB interactions, and API payloads.
-- **Risk Assessment:** Pre-identified failure points and mitigations.
+### Task state and proof
 
-### Execution Checklists (`tasks/task-R*.md`)
-Work is decomposed into requirement-driven markdown task files.
-Each task file contains:
-- **Prerequisites:** Blockers that must clear before this stage begins. (Task N+1 cannot start without Task N defining its payload).
-- **Execution Checklist:** Granular `[ ]` markdown items for agents to toggle `[x]` as they implement code.
-- **Success Criteria:** Strict definition of "Done".
+Each task contains exactly one `Status:` field. The final inline `## Receipt`
+is canonical proof and must contain the exact command, `Exit: 0`,
+`Verification: PASS`, runtime-derived Base and Head values, and non-empty
+fenced current output before the task becomes done.
+
+Sync only observed state with surgical edits. Re-read the changed task after
+every update; never infer missing proof, approval, or readiness. When a done
+task changes user-facing behavior, architecture, API contracts, operations, or
+project status, classify docs impact and update only affected existing docs.
 
 Comply with the overarching rules in `./rules/ai-dev-rules.md`.
+
+## Legacy specification layout
+
+Existing features containing `spec.json`, nested `tasks/task-R*.md`, or other
+legacy kernel artifacts keep their installed adapters and original layout.
+Preserve `task_registry`, `semantic_model`, `planning_depth`, lane,
+`execution_tier`, machine authority, typed topology, separate receipts, and
+feature closeout files. Do not migrate them as part of unrelated documentation
+work.

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

@@ -1,62 +1,57 @@
-# Specs v2.1 state synchronization
-
-## Authority layers
-
-`spec.json` is machine semantic authority. Requirements, design, conditional
-research, and conditional task Markdown are human projections. Host state may
-record authority or integrity, but it never supplies product semantics.
-
-Planning depth and assurance level remain independent. The artifact router runs
-before discovery: None persists no spec; Compact and Full persist the bounded
-core; research and tasks remain absent unless their semantic triggers exist.
-
-## Canonical lifecycle
-
-The feature lifecycle is exactly `in_progress`, `paused`, `blocked`, or `done`.
-Authoring state is independently `draft`, `validated`, or `absent`. Do not emit
-legacy lifecycle aliases in a new 2.1 artifact.
-
-Technical readiness is not lifecycle completion. `ready_for_implementation`
-may change only through the installed machine finalization path after every
-routed artifact, projection, semantic review, grounding check, and deterministic
-gate passes. An author must not directly declare readiness, authority, approval,
-review capability, execution proof, or closeout.
-
-## Projection sync
-
-After any semantic Markdown edit:
-
-1. invoke the explicit installed machine semantic-sync step to promote `semantic_model`;
-2. regenerate or reconcile every affected Markdown projection;
-3. verify requirements, decisions, anchors, task registry, typed boundaries,
-   and verification refs round-trip without loss; and
-4. rerun the applicable deterministic validation and grounding checks.
-
-For Claude Code, the isolated promotion is
-`node .claude/scripts/spec-scaffold.cjs <feature> --sync-semantic-model`.
-
-Task Markdown exists only when typed ownership, dependency, transition, proof,
-or parallel topology requires it. Its status and dependencies project the
-matching `task_registry` entry. Its Verification Plan is prospective and never
-contains an execution verdict or proof claim. Topology comes only from typed
-`coordination.boundaries`, never from legacy trigger fields, priority markers,
-related-file lists, or prose.
-
-## Lifecycle updates
-
-- Starting or continuing authored work keeps the feature `in_progress`.
-- A deliberate resumable stop uses `paused` with the exact remaining decision.
-- An external or semantic blocker uses `blocked` with a concrete cause.
-- Task state changes update `task_registry` and the matching task projection
-  together, but only from observed work and verification.
-- Feature `done` is reserved for final-state authority after implementation
-  closeout; authoring or readiness cannot produce it.
-
-State synchronization never fabricates commands, PASS results, timestamps,
-receipts, completed work, reviewer identity, or user approval. When execution
-evidence is absent, preserve the unfinished state and report the missing proof.
-Never hand-author the `semantic_model` shape or treat an unsynchronized Markdown
-edit as machine authority.
-
-Claude-native plan/task state may mirror physical state when available, but it
-is never a substitute for `spec.json` or authority to advance the lifecycle.
+# Process-first state synchronization
+
+## Primary file state
+
+For new work, `specs/<feature>/plan.md` and its direct-child
+`task-NN-*.md` files are canonical, hand-editable state. Task files stay flat
+beside the plan; indexes and host task views are disposable projections.
+
+Each task has exactly one `Status:` field using `pending`, `in_progress`,
+`paused`, `blocked`, or `done`. The controller is the sole writer of task
+status and proof. A task's final `## Receipt` is its only canonical execution
+proof.
+
+## Surgical synchronization
+
+Before changing state:
+
+1. read the plan row and the task's Outcome, Acceptance, Dependencies,
+   Verification Plan, Status, and Receipt;
+2. confirm every dependency and owned path at the requested boundary;
+3. edit only the observed Status, concrete blocker, implemented checkbox, or
+   Receipt; and
+4. re-read the file and confirm exactly one Status field and one Receipt
+   section.
+
+Starting or resuming changes only Status to `in_progress`. Blocking records a
+specific cause without creating proof. Do not replace a whole packet to make a
+state transition.
+
+Set `Status: done` only after the inline Receipt passes the
+`validateCanonicalReceipt` contract: exact command, `Exit: 0`,
+`Verification: PASS`, runtime-derived Base and Head values, and a non-empty
+fenced block of current command output. Missing, stale, contradictory,
+placeholder, copied, failure, or zero-test evidence leaves the task unfinished.
+
+Synchronization never fabricates commands, output, timestamps, completed
+work, reviewer identity, user approval, or product readiness. A passing command
+proves only the boundary it executed.
+
+## Human gates and workflow ownership
+
+- C1 records the user's scope decision before the plan is written.
+- C2 records the user's disposition of deduplicated adversarial findings.
+- Develop starts only after a new explicit user invocation and executes one
+  unblocked task at a time.
+- Sync changes only observed file state and never starts implementation.
+- C3 occurs after current receipts and limitations are shown; the user decides
+  whether the requested feature is complete.
+
+## Legacy compatibility
+
+Existing packets containing `spec.json`, nested `tasks/task-R*.md`, or other
+legacy kernel artifacts stay on their installed adapters. Preserve their
+`task_registry`, `semantic_model`, `planning_depth`, lane,
+`execution_tier`, typed topology, separate receipts, and feature closeout
+contract. Do not migrate that machine authority or storage shape while syncing
+an unrelated process-first packet.

package/src/claude/rules/workflow.md

@@ -12,14 +12,18 @@ Use the CafeKit loop: **Understand -> Plan -> Execute -> Verify -> Sync**.
 
 ## 2. Plan
 
-- For non-trivial features, use `/specs` to create or validate the spec.
-- For technically ready specs, start implementation only after a new explicit Develop invocation and work one task file at a time.
+- For non-trivial features, use `/hapo: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,
+  then select one unblocked task at a time.
 - Extract from the active task:
   - `Status`
   - `Outcome`
   - `Scope`
-  - `Anchors and Ownership`
-  - `Changes`
+  - `Ownership`
   - `Acceptance`
   - `Dependencies`
   - `Verification Plan`
@@ -37,22 +41,26 @@ Use the CafeKit loop: **Understand -> Plan -> Execute -> Verify -> Sync**.
 - Run exact commands from `Verification Plan` first.
 - Then run repo-level lint/test/build as needed for confidence.
 - Use only fresh verification from the current run when claiming completion.
+- Review correctness, security, scope, and reachability without turning the
+  review into execution proof.
 - `PRECHECK_FAIL` outranks `NO_TESTS`.
 - `NO_TESTS` or `0 tests + exit 0` is not a pass when automated tests are required.
 - If verification fails, fix root cause and rerun. After 3 failed attempts, escalate with evidence.
 
 ## 5. Sync
 
-- Mark task state only after implementation, tests/evidence, and review pass.
-- Write task proof to `receipts/<task-basename>.md`; use legacy task-local
-  `## Evidence` only when consuming an old task format.
-- Create `feature-receipt.md` only for final integration closeout.
-- Treat `spec.json` as machine authority; task Markdown is a human projection.
-- Derive task ordering, ownership, proof, and parallel eligibility only from
-  typed `coordination.boundaries`, never `(P)`, `task_triggers`, `Related Files`,
-  or prose markers.
-- Keep `spec.json.task_registry` and markdown task files aligned.
+- Use `/hapo:sync` to edit observed state surgically; the controller is the
+  sole writer of task Status and proof.
+- Keep exactly one `Status:` field. Write or replace the task's final inline
+  `## Receipt` before setting `Status: done`.
+- A canonical Receipt contains the exact command, `Exit: 0`,
+  `Verification: PASS`, runtime-derived Base and Head values, and non-empty
+  fenced current output. Never invent, copy, or infer missing proof.
+- Re-read each edited task and reconcile its plan row, dependencies, acceptance
+  mapping, status, and receipt without rewriting unrelated bytes.
 - Run docs checkpoint when a completed task affects public docs or architecture docs.
+- After all requested work has current proof, show evidence and limitations at
+  C3. The user decides whether the feature is complete.
 
 ## Production Or CI Issues
 
@@ -63,3 +71,12 @@ Use the CafeKit loop: **Understand -> Plan -> Execute -> Verify -> Sync**.
 5. Review before syncing or shipping.
 
 Do not patch symptoms before diagnosis unless the issue is a trivial syntax/type/lint failure with an obvious local cause.
+
+## Legacy compatibility
+
+When an existing feature contains `spec.json`, nested `tasks/task-R*.md`, or
+other legacy kernel artifacts, keep using the installed adapter. Preserve its
+`task_registry`, `semantic_model`, `planning_depth`, lane,
+`execution_tier`, typed boundaries, separate receipts, and final feature
+receipt. Do not project that machine authority or storage shape into a new
+process-first packet.

package/src/claude/scripts/change-firewall.cjs

@@ -37,7 +37,7 @@ const REL = {
   ledger: 'packages/spec/benchmarks/benchmark-failure-ledger.json',
   freeze: 'packages/spec/.cafekit-release/change-firewall-freeze.json',
   receipt: 'packages/spec/.cafekit-release/release-receipt.json',
-  legacyBridge: 'specs/cafekit-semantic-eval-firewall/reports/bootstrap-legacy-bridge-review.json',
+  legacyBridge: 'specs/archive/cafekit-semantic-eval-firewall/reports/bootstrap-legacy-bridge-review.json',
   cafekitReleaseDir: 'packages/spec/.cafekit-release/',
   packageJson: 'packages/spec/package.json',
 };
@@ -716,7 +716,7 @@ function readLegacyBridgeArtifact(root) {
 // C14 BootstrapAttestation / bootstrapBaseline
 // ---------------------------------------------------------------------------
 
-const REL_FEATURE_SPEC = 'specs/cafekit-semantic-eval-firewall/spec.json';
+const REL_FEATURE_SPEC = 'specs/archive/cafekit-semantic-eval-firewall/spec.json';
 
 function readFeatureSpecJson(root) {
   const loaded = readJsonFileIfExists(root, REL_FEATURE_SPEC);

package/src/claude/scripts/generate-skill-catalog.cjs

@@ -41,7 +41,6 @@ function defaultSkillsRoot() {
     path.resolve(__dirname, '..', 'skills'),
     path.resolve(process.cwd(), '.claude', 'skills'),
     path.resolve(process.cwd(), '.agents', 'skills'),
-    path.resolve(process.cwd(), '.opencode', 'skills'),
     path.resolve(__dirname, '..', '..', '.agents', 'skills')
   ];
   return candidates.find((candidate) => fs.existsSync(candidate)) || candidates[0];

package/src/claude/scripts/spec-receipt.cjs

@@ -3,6 +3,7 @@
 const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
+const { annotatedMarkdownLines } = require('./spec-resolver.cjs');
 
 const EVIDENCE_HEADINGS = new Set([
   'Evidence',
@@ -66,6 +67,49 @@ function evidenceBody(text, policy = {}) {
   return lines.slice(start, end).join('\n');
 }
 
+function workflowReceiptBody(text, policy = {}) {
+  const lines = annotatedMarkdownLines(text);
+  const starts = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    if (lines[index].outsideFence && /^##\s+Receipt\s*$/.test(lines[index].line)) starts.push(index + 1);
+  }
+  if (starts.length !== 1) return null;
+
+  const start = starts[0];
+  let end = lines.length;
+  for (let index = start; index < lines.length; index += 1) {
+    if (!lines[index].outsideFence) continue;
+    const heading = lines[index].line.match(/^(#{1,6})\s+/);
+    const tap = typeof policy.isTapMetadataHeading === 'function' && policy.isTapMetadataHeading(lines[index].line);
+    if (heading && heading[1].length <= 2 && !tap) { end = index; break; }
+  }
+  return lines.slice(start, end).map(({ line }) => line).join('\n');
+}
+
+function workflowCanonicalValidationBody(body) {
+  return annotatedMarkdownLines(body)
+    .filter(({ outsideFence }) => outsideFence)
+    .map(({ line }) => line)
+    .join('\n');
+}
+
+function hasNonEmptyFencedBlock(body) {
+  let open = false;
+  let nonEmpty = false;
+  for (const { line, fenceEvent } of annotatedMarkdownLines(body)) {
+    if (fenceEvent === 'open') {
+      open = true;
+      nonEmpty = false;
+    } else if (fenceEvent === 'close') {
+      if (open && nonEmpty) return true;
+      open = false;
+    } else if (open && line.trim() !== '') {
+      nonEmpty = true;
+    }
+  }
+  return false;
+}
+
 function fieldValues(body, name) {
   const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
   const matcher = new RegExp(`^\\s*${escaped}\\s*:\\s*(.*?)\\s*$`, 'i');
@@ -76,6 +120,49 @@ function concrete(value) {
   return typeof value === 'string' && value.trim() !== '' && !/^(?:N\/A|NONE|PENDING|TBD|UNKNOWN|\{\{.*\}\})$/i.test(value.trim());
 }
 
+function normalizedCommand(value) {
+  if (typeof value !== 'string') return null;
+  let command = value.trim();
+  if (/^`[^`\r\n]+`$/.test(command)) command = command.slice(1, -1).trim();
+  if (!concrete(command) || /^<[^>]+>$/.test(command)) return null;
+  return command;
+}
+
+function workflowVerificationCommand(taskText) {
+  const sections = [];
+  let current = null;
+  for (const { line, outsideFence } of annotatedMarkdownLines(taskText)) {
+    if (!outsideFence) continue;
+    if (/^##\s+Verification Plan\s*$/.test(line)) {
+      current = [];
+      sections.push(current);
+      continue;
+    }
+    if (current && /^#{1,2}\s+/.test(line)) {
+      current = null;
+      continue;
+    }
+    if (current) current.push(line);
+  }
+  if (sections.length !== 1) return null;
+  const commands = sections[0]
+    .map((line) => line.match(/^\s*-\s+(?:\*\*Command\*\*|Command)\s*:\s*(.*?)\s*$/i))
+    .filter(Boolean)
+    .map((match) => normalizedCommand(match[1]));
+  return commands.length === 1 ? commands[0] : null;
+}
+
+function workflowCommandFailures(taskText, body) {
+  const planned = workflowVerificationCommand(taskText);
+  const actualValues = [
+    ...fieldValues(body, 'Command'),
+    ...fieldValues(body, 'Commands'),
+  ].map(normalizedCommand);
+  return planned && actualValues.length === 1 && actualValues[0] === planned
+    ? []
+    : ['command_identity'];
+}
+
 function plannedField(taskText, name) {
   const plan = String(taskText || '').split(/^##\s+Verification Plan\s*$/m)[1];
   if (!plan) return null;
@@ -149,6 +236,103 @@ function checkTaskReceipt(featureDir, taskPath, task, runtimeContext, policy) {
   return { ...proof, failures: [...new Set(failures)] };
 }
 
+function checkWorkflowTaskReceipt(featureDir, taskPath, runtimeContext, policy) {
+  const safeTaskPath = typeof taskPath === 'string' && /^task-[A-Za-z0-9][A-Za-z0-9._-]*\.md$/.test(taskPath);
+  if (!safeTaskPath) return { status: 'unsafe', taskPath, failures: ['unsafe_path'] };
+  const taskFile = safeRead(featureDir, taskPath);
+  if (taskFile.status !== 'ok') {
+    return { ...taskFile, taskPath, failures: [taskFile.status === 'unsafe' ? 'unsafe_path' : 'missing_receipt'] };
+  }
+
+  const taskText = taskFile.bytes.toString('utf8');
+  const statusLines = annotatedMarkdownLines(taskText)
+    .filter(({ outsideFence }) => outsideFence)
+    .map(({ line }) => line.match(/^\s*(?:\*\*)?Status(?:\*\*)?\s*:\s*(?:\*\*)?\s*([A-Za-z_-]+)(?:\*\*)?\s*$/i))
+    .filter(Boolean);
+  const body = workflowReceiptBody(taskText, policy);
+  const failures = [];
+  if (statusLines.length !== 1 || statusLines[0][1].toLowerCase().replaceAll('-', '_') !== 'done') {
+    failures.push('task_status');
+  }
+  if (body === null) {
+    failures.push('missing_receipt');
+  } else {
+    const canonicalBody = workflowCanonicalValidationBody(body);
+    const options = typeof policy?.receiptValidatorOptions === 'function'
+      ? policy.receiptValidatorOptions({}, { runtimeContext, requireProvenanceBinding: true })
+      : { requireProvenanceBinding: true };
+    failures.push(...canonicalFailures(canonicalBody, {}, runtimeContext, policy));
+    failures.push(...canonicalFailures(body, {}, runtimeContext, policy)
+      .filter((failure) => ['placeholder', 'verification_state', 'exit_result'].includes(failure)));
+    failures.push(...workflowCommandFailures(taskText, canonicalBody));
+    if (!hasNonEmptyFencedBlock(body)) failures.push('command_output');
+    if (!options.expectedProvenance) failures.push('provenance');
+  }
+  return {
+    status: failures.length === 0 ? 'ok' : 'invalid',
+    source: 'inline',
+    body,
+    receiptBytes: body === null ? null : Buffer.from(body),
+    taskFile,
+    taskText,
+    taskPath,
+    failures: [...new Set(failures)],
+  };
+}
+
+function workflowProofSignature(taskPath, proof) {
+  const hash = crypto.createHash('sha256');
+  hash.update('cafekit-workflow-proof-v1\0');
+  hash.update(String(taskPath));
+  hash.update('\0');
+  hash.update(proof.taskFile?.bytes || Buffer.alloc(0));
+  hash.update('\0');
+  hash.update(proof.receiptBytes || Buffer.alloc(0));
+  hash.update('\0');
+  hash.update(String(proof.status || 'unknown'));
+  return hash.digest('hex');
+}
+
+function workflowDependencyProofState(featureDir, taskRegistry, runtimeContext, policy) {
+  const tasks = {};
+  for (const taskPath of Object.keys(taskRegistry || {}).sort()) {
+    const done = taskRegistry[taskPath]?.status === 'done';
+    const proof = checkWorkflowTaskReceipt(featureDir, taskPath, runtimeContext, policy);
+    const valid = proof.failures.length === 0;
+    tasks[taskPath] = {
+      done,
+      valid,
+      eligible: done && valid,
+      signature: workflowProofSignature(taskPath, proof),
+      failures: [...proof.failures],
+    };
+  }
+  return tasks;
+}
+
+function checkWorkflowReceiptSet(candidates, projectRoot, runtimeSession, policy) {
+  const failures = [];
+  for (const candidate of Array.isArray(candidates) ? candidates : []) {
+    const runtimeContext = policy.deriveRuntimeContext({
+      projectRoot,
+      specsRoot: candidate.specsDir,
+      specFile: candidate.stateFile || candidate.planFile,
+      featureName: candidate.featureName,
+      runtimeSession,
+    });
+    const doneTasks = Object.keys(candidate.taskRegistry || {}).filter((taskPath) => (
+      candidate.taskRegistry[taskPath]?.status === 'done'
+    ));
+    for (const taskPath of doneTasks) {
+      const proof = checkWorkflowTaskReceipt(candidate.featureDir, taskPath, runtimeContext, policy);
+      if (proof.failures.length > 0) {
+        failures.push({ featureName: candidate.featureName, taskPath, failures: proof.failures });
+      }
+    }
+  }
+  return { failures };
+}
+
 function checkFeatureReceipt(featureDir, runtimeContext, policy) {
   const receipt = safeRead(featureDir, 'feature-receipt.md');
   if (receipt.status !== 'ok') return { status: receipt.status, failures: [receipt.status === 'unsafe' ? 'unsafe_path' : 'missing_receipt'] };
@@ -159,4 +343,15 @@ function checkFeatureReceipt(featureDir, runtimeContext, policy) {
   return { status: 'ok', source: 'feature', body, receiptBytes: receipt.bytes, receiptFile: receipt, failures: [...new Set(failures)] };
 }
 
-module.exports = { canonicalTaskReceiptPath, checkFeatureReceipt, checkTaskReceipt, evidenceBody, readTaskProof, safeRead };
+module.exports = {
+  canonicalTaskReceiptPath,
+  checkFeatureReceipt,
+  checkTaskReceipt,
+  checkWorkflowReceiptSet,
+  checkWorkflowTaskReceipt,
+  evidenceBody,
+  readTaskProof,
+  safeRead,
+  workflowDependencyProofState,
+  workflowReceiptBody,
+};