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

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

@@ -70,16 +70,138 @@ function candidateError(reason, code = 'malformed') {
 
 const WORKFLOW_STATUSES = new Set(['pending', 'in_progress', 'paused', 'blocked', 'done']);
 const WORKFLOW_TASK_NAME = /^task-[A-Za-z0-9][A-Za-z0-9._-]*\.md$/;
+const WORKFLOW_CONTRACT = 'process-first-ready-v1';
+
+function annotatedMarkdownLines(content) {
+  let fence = null;
+  return String(content || '').split(/\r?\n/).map((line, index) => {
+    const fenceMatch = line.match(/^ {0,3}(`{3,}|~{3,})(.*)$/);
+    const outsideFence = fence === null && !fenceMatch;
+    let fenceEvent = null;
+    if (fenceMatch) {
+      const marker = fenceMatch[1];
+      if (!fence) {
+        fence = { char: marker[0], length: marker.length };
+        fenceEvent = 'open';
+      } else if (marker[0] === fence.char && marker.length >= fence.length && fenceMatch[2].trim() === '') {
+        fence = null;
+        fenceEvent = 'close';
+      }
+    }
+    return { index, line, outsideFence, fenceEvent };
+  });
+}
+
+function workflowPlanContract(content) {
+  const markers = annotatedMarkdownLines(content)
+    .filter(({ line, outsideFence }) => outsideFence && /^\s*Specs-Contract\s*:/i.test(line))
+    .map(({ line }) => line);
+  if (markers.length === 0) return { workflowContract: null, queueReady: false };
+  if (markers.length !== 1 || markers[0] !== `Specs-Contract: ${WORKFLOW_CONTRACT}`) {
+    throw candidateError(`plan.md must contain exactly one Specs-Contract: ${WORKFLOW_CONTRACT} marker`);
+  }
+  return { workflowContract: WORKFLOW_CONTRACT, queueReady: true };
+}
 
 function workflowTaskStatus(content, taskName) {
-  const matches = String(content || '').matchAll(/^\s*(?:\*\*)?Status(?:\*\*)?\s*:\s*(?:\*\*)?\s*([A-Za-z_-]+)(?:\*\*)?\s*$/gim);
-  const values = [...matches].map((match) => match[1].toLowerCase().replaceAll('-', '_'));
+  const values = annotatedMarkdownLines(content)
+    .filter(({ outsideFence }) => outsideFence)
+    .map(({ line }) => line.match(/^\s*(?:\*\*)?Status(?:\*\*)?\s*:\s*(?:\*\*)?\s*([A-Za-z_-]+)(?:\*\*)?\s*$/i))
+    .filter(Boolean)
+    .map((match) => match[1].toLowerCase().replaceAll('-', '_'));
   if (values.length !== 1 || !WORKFLOW_STATUSES.has(values[0])) {
     throw candidateError(`${taskName} must contain exactly one supported Status field`);
   }
   return values[0];
 }
 
+function workflowTaskNumericPrefix(taskName) {
+  const match = taskName.match(/^task-(\d+)(?:-|\.md$)/);
+  return match ? match[1].replace(/^0+(?=\d)/, '') : null;
+}
+
+function workflowTaskDependencies(content, taskName, taskNames, queueReady) {
+  const lines = annotatedMarkdownLines(content);
+  let sectionStart = -1;
+  let sectionEnd = lines.length;
+  let sectionCount = 0;
+
+  for (let index = 0; index < lines.length; index += 1) {
+    if (!lines[index].outsideFence) continue;
+
+    const heading = lines[index].line.match(/^(#{1,6})\s+(.+?)\s*$/);
+    if (!heading || heading[1].length > 2) continue;
+    const title = heading[2].trim().toLowerCase();
+    if (heading[1].length === 2 && title === 'dependencies') {
+      sectionCount += 1;
+      if (sectionStart < 0) sectionStart = index + 1;
+      continue;
+    }
+    if (sectionStart >= 0 && sectionEnd === lines.length) sectionEnd = index;
+  }
+
+  if (!queueReady && sectionCount === 0) return [];
+  if (sectionCount !== 1 || sectionStart < 0) {
+    throw candidateError(`${taskName} must contain exactly one ## Dependencies section`);
+  }
+
+  const entries = lines.slice(sectionStart, sectionEnd)
+    .filter(({ outsideFence }) => outsideFence)
+    .map(({ line }) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const bullet = line.match(/^-\s+(.+?)\s*$/);
+      if (!bullet) throw candidateError(`${taskName} Dependencies must contain only bullet entries`);
+      const value = bullet[1].replace(/^`([^`]+)`$/, '$1').trim();
+      if (!value) throw candidateError(`${taskName} contains an empty dependency`);
+      return value;
+    });
+
+  if (entries.length === 1 && entries[0].toLowerCase() === 'none') return [];
+  if (entries.length === 0 || entries.some((entry) => entry.toLowerCase() === 'none')) {
+    throw candidateError(`${taskName} must use either - none or exact task basenames`);
+  }
+  const resolved = entries.map((entry) => {
+    if (WORKFLOW_TASK_NAME.test(entry)) return entry;
+    const legacy = !queueReady && entry.match(/^(?:Task\s+)?(\d+)$/i);
+    if (!legacy) throw candidateError(`${taskName} dependencies must be exact flat task basenames`);
+    const numericId = legacy[1].replace(/^0+(?=\d)/, '');
+    const matches = taskNames.filter((candidate) => workflowTaskNumericPrefix(candidate) === numericId);
+    if (matches.length !== 1) {
+      throw candidateError(`${taskName} legacy dependency ${entry} maps to ${matches.length} task basenames`);
+    }
+    return matches[0];
+  });
+  if (new Set(resolved).size !== resolved.length) {
+    throw candidateError(`${taskName} contains duplicate dependencies`);
+  }
+  return resolved;
+}
+
+function assertAcyclicWorkflow(tasks) {
+  const dependencies = new Map(tasks.map((task) => [task.path, [...task.dependencies].sort()]));
+  const state = new Map();
+  const stack = [];
+
+  function visit(taskPath) {
+    state.set(taskPath, 'visiting');
+    stack.push(taskPath);
+    for (const dependency of dependencies.get(taskPath) || []) {
+      if (state.get(dependency) === 'visiting') {
+        const start = stack.indexOf(dependency);
+        throw candidateError(`dependency cycle detected: ${[...stack.slice(start), dependency].join(' -> ')}`);
+      }
+      if (state.get(dependency) !== 'visited') visit(dependency);
+    }
+    stack.pop();
+    state.set(taskPath, 'visited');
+  }
+
+  for (const taskPath of [...dependencies.keys()].sort()) {
+    if (!state.has(taskPath)) visit(taskPath);
+  }
+}
+
 function inspectWorkflowFeature(specsDir, canonicalSpecs, requestedName) {
   const featureDir = path.join(specsDir, requestedName);
   let featureLstat;
@@ -114,6 +236,7 @@ function inspectWorkflowFeature(specsDir, canonicalSpecs, requestedName) {
   if (planLstat.isSymbolicLink() || !planLstat.isFile() || fs.realpathSync(planFile) !== planFile) {
     throw candidateError('plan.md must be a regular non-symlink file in the workflow feature directory');
   }
+  const { workflowContract, queueReady } = workflowPlanContract(fs.readFileSync(planFile, 'utf8'));
 
   const taskNames = fs.readdirSync(canonicalFeature, { withFileTypes: true })
     .filter((entry) => WORKFLOW_TASK_NAME.test(entry.name))
@@ -129,12 +252,26 @@ function inspectWorkflowFeature(specsDir, canonicalSpecs, requestedName) {
     if (taskLstat.isSymbolicLink() || !taskLstat.isFile() || fs.realpathSync(taskFile) !== taskFile) {
       throw candidateError(`${taskName} must be a regular non-symlink file in the workflow feature directory`);
     }
+    const taskContent = fs.readFileSync(taskFile, 'utf8');
     return {
       path: taskName,
-      status: workflowTaskStatus(fs.readFileSync(taskFile, 'utf8'), taskName),
+      status: workflowTaskStatus(taskContent, taskName),
+      dependencies: workflowTaskDependencies(taskContent, taskName, taskNames, queueReady),
     };
   });
-  const taskRegistry = Object.fromEntries(tasks.map((task) => [task.path, { status: task.status }]));
+  const taskNameSet = new Set(taskNames);
+  for (const task of tasks) {
+    if (task.dependencies.includes(task.path)) {
+      throw candidateError(`${task.path} cannot depend on itself`);
+    }
+    const missing = task.dependencies.find((dependency) => !taskNameSet.has(dependency));
+    if (missing) throw candidateError(`${task.path} references missing dependency ${missing}`);
+  }
+  assertAcyclicWorkflow(tasks);
+  const taskRegistry = Object.fromEntries(tasks.map((task) => [task.path, {
+    status: task.status,
+    dependencies: task.dependencies,
+  }]));
   const allTasksDone = tasks.every((task) => task.status === 'done');
   return {
     layoutKind: 'process-v3',
@@ -147,6 +284,8 @@ function inspectWorkflowFeature(specsDir, canonicalSpecs, requestedName) {
     taskRegistry,
     tasks,
     allTasksDone,
+    workflowContract,
+    queueReady,
   };
 }
 
@@ -778,6 +917,7 @@ function refineWorkflowGateResolution(resolved) {
 }
 
 module.exports = {
+  annotatedMarkdownLines,
   specsDirectory,
   findAllActiveSpecs,
   findAllSpecCandidates,

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

@@ -77,6 +77,13 @@ 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.
 
+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.
+
 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.
@@ -89,15 +96,16 @@ failure scenario. Deduplicate, rank, and cap the list 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. Stop after two paper-review rounds; later findings require runtime
-evidence.
+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.
 
 ### 4. Execute one task at a time
 
-An implementation workflow owns execution. It selects one unblocked task,
-changes its single `Status:` field to `in_progress`, respects owned paths, runs
-the task's verification, and appends a real inline `## Receipt` only after the
-command finishes.
+An implementation workflow owns execution. It selects one unblocked task with
+`Status: pending`, changes its single `Status:` field to `in_progress`, respects
+owned paths, runs the task's verification, and appends a real inline `## Receipt`
+only after the command finishes.
 
 Parallel work is allowed only for tasks with disjoint write ownership and
 satisfied dependencies. One file has one writer in a wave. The controller is
@@ -129,7 +137,7 @@ it does not invent product approval, review independence, or runtime coverage.
    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 — Done is derived.** Status follows fresh proof, never confidence.
+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.
 
@@ -141,6 +149,8 @@ Stop gate revalidates every done task's inline Receipt and provenance. The old
 task-scaffold guard remains limited to the older nested layout; flat v3 tasks
 do not invoke that kernel path.
 
+The resolver projects exact `Status:` values; it does not infer blockers from prose.
+
 These checks are a final safety net, not a substitute for C1-C3 judgment. Do
 not add a new schema, approval field, readiness bit, or review state to make the
 Markdown look more authoritative.

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

@@ -15,6 +15,7 @@ evidence.
   list the first ten plus the total.
 - Label an unresolved external or runtime claim `[UNVERIFIED]` and name the
   command, document, or environment that would settle it.
+- Any privacy/security claim names the exact identifier surface at risk, such as an env var, header, path, token class, or field name; generic “sensitive data” is insufficient.
 
 ## Reviewer roles
 
@@ -51,6 +52,7 @@ Use reviewers that did not author the plan and give each one a distinct lens:
 Prompt them to break the plan. For every finding require: severity, exact plan
 location, concrete counterexample, repository evidence, and the smallest repair.
 Ignore style-only feedback.
+Run mutation or destructive negative controls only on disposable copies below a verified temporary root, never tracked worktree or canonical source bytes.
 
 ## Four red-team lenses
 
@@ -81,6 +83,19 @@ Present C2 as a table:
 The user chooses accept, reject, or revise. Do not apply findings before that
 decision. Record the result in the plan review log.
 
+## Accepted-repair closure
+
+After applying an accepted C2 finding, a fresh-context closure pass records and
+freshly replays its original counterexample after the repair under this exact review-log header:
+
+| ID | Decision | Original counterexample | Repaired at | Proved at | Replay | Closure |
+|---|---|---|---|---|---|---|
+
+`Repaired at` cites the repair edit; `Proved at` must cite distinct evidence from the fresh replay, never the repair-edit citation.
+An accepted finding transitions `accepted → repaired → PASS|FAIL|UNKNOWN`.
+Only `PASS` closes it; `FAIL` remains open for the remaining paper-review round; `UNKNOWN` blocks implementation handoff.
+A repair that adds user semantics or scope returns to C1.
+
 ## B3 — consistency sweep
 
 After any accepted finding or user edit:

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

@@ -16,6 +16,7 @@ Keep the plan short enough to scan as one index, normally under 100 lines.
 
 ```markdown
 # <Feature name>
+Specs-Contract: process-first-ready-v1
 
 ## Scope decision (C1 — YYYY-MM-DD)
 - Existing: <reusable code with path:line>
@@ -34,7 +35,7 @@ Keep the plan short enough to scan as one index, normally under 100 lines.
 ## Tasks
 | # | Task | Criteria | Primary ownership | Dependencies | Status |
 |---|---|---|---|---|---|
-| 01 | <one outcome> | AC-01 | `src/example.ts` | - | pending |
+| 01 | <one outcome> | AC-01 | `src/example.ts` | - | blocked |
 
 ## Review log
 - Round 1: <findings accepted/rejected/revised>; sweep <result>.
@@ -50,7 +51,7 @@ Keep one exact `Status:` field. The task file is one owner's packet.
 ````markdown
 # Task NN — <one observable outcome>
 
-Status: pending
+Status: blocked
 
 ## Outcome
 <What becomes true when this task succeeds.>
@@ -68,18 +69,36 @@ Status: pending
 - AC-01: <task-local measurable condition>
 
 ## Dependencies
-- <task number or `none`>
+- <exact `task-NN-*.md` basename or `none`; one bullet per dependency>
 
 ## Verification Plan
 - Command: `<exact runnable command>`
-- Expected: <observable success, including nonzero/negative behavior if relevant>
-- Reachability: <entrypoint or consumer>
-- Artifacts: <path and digest requirement, or none>
+- 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>
+- 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>
 
 ## Receipt
 <!-- 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
+negative controls only on disposable copies under a verified temporary root,
+never tracked worktree or canonical source bytes.
+
+## Status matrix
+
+| Status condition | Persisted state |
+|---|---|
+| C1/C2 decision open | `blocked` |
+| accepted finding open or `UNKNOWN` | `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.
+
 ## Canonical inline Receipt
 
 The completed task keeps this section at the end of the same file. Derive Base
@@ -132,25 +151,35 @@ Question: which environment owns the authoritative integration run?
 
 Keep examples only until they clarify a rule or acceptance criterion.
 
+## 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.
+
+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 |
+|---|---|
+| 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 |
+| Filesystem/security | authoritative root; trusted/untrusted segment grammar; lexical + canonical containment and symlink policy; flags/mode; temp/rename/fsync; lock/stale reclaim; crash cleanup |
+| Time/retention | clock source; unit/precision/timezone; endpoints and inclusion/comparator; anomaly behavior; expiry/purge/recovery |
+| Integration/proof | caller; export/registration; packaging/config; native path/consumer; proof level (`source`/`installed`/`live`); observable failure oracle |
+
 ## Twelve edge-case dimensions
 
 For each material boundary, select relevant dimensions rather than filling a
 ceremonial matrix:
 
-| Dimension | Probe |
-|---|---|
-| Input shape | empty, malformed, duplicate, maximum size |
-| Identity | missing, wrong actor, cross-scope, replay |
-| State | initial, partial, terminal, stale |
-| Order | early, late, repeated, out of order |
-| Concurrency | double writer, race, cancellation |
-| Dependency | missing, blocked, version drift |
-| Failure | timeout, exception, nonzero exit |
-| Recovery | retry, resume, rollback, cleanup |
-| Persistence | partial write, corruption, migration |
-| Integration | caller, registration, packaging, reachability |
-| Security/privacy | injection, traversal, secret exposure |
-| Observability/proof | logs, artifact, negative path, provenance |
+- Input shape, identity, state, order: malformed/duplicate/bounds, wrong actor,
+  partial/stale state, replay/reordering.
+- Concurrency, dependency, failure, recovery: races/cancellation, version drift,
+  timeout/nonzero exit, retry/rollback/cleanup.
+- Persistence, integration, security/privacy, observability/proof: partial
+  writes, registration/reachability, traversal/secrets, artifacts/provenance.
+
+`Crash` means abrupt unhandled termination before the claimed catch point; a catchable failure returns/raises an error or exits nonzero. Never use them interchangeably.
 
 Turn a discovered risk into an EARS criterion, a task acceptance item, or a
 verification probe. Do not duplicate it across all three.

package/src/codex/hooks/spec-state.cjs

@@ -77,15 +77,33 @@ try {
     result[status] = (result[status] || 0) + 1;
     return result;
   }, {});
+  const featureDir = path.join(active.specsDir, active.featureName);
   const statuses = new Map(tasks.map(([taskPath, task]) => [
     taskPath,
     task?.status || 'pending'
   ]));
+  const dependencyProof = processWorkflow
+    ? RECEIPT.workflowDependencyProofState(featureDir, taskRegistry, runtimeContext, POLICY)
+    : {};
+  const taskState = tasks.map(([taskPath, task]) => [
+    taskPath,
+    task?.status || 'pending',
+    [...(Array.isArray(task?.dependencies) ? task.dependencies : [])].sort(),
+  ]).sort(([left], [right]) => left.localeCompare(right));
+  const proofState = Object.entries(dependencyProof).map(([taskPath, proof]) => [
+    taskPath,
+    proof.done,
+    proof.valid,
+    proof.eligible,
+    proof.signature,
+  ]);
   const next = tasks.find(([, task]) => (
-    (task?.status || 'pending') === 'pending'
-    && (task?.dependencies || []).every((dependency) => statuses.get(dependency) === 'done')
+    active.queueReady !== false
+    && (task?.status || 'pending') === 'pending'
+    && (task?.dependencies || []).every((dependency) => (
+      processWorkflow ? dependencyProof[dependency]?.eligible === true : statuses.get(dependency) === 'done'
+    ))
   ));
-  const featureDir = path.join(active.specsDir, active.featureName);
   const featureReceiptPresent = !processWorkflow
     && RECEIPT.safeRead(featureDir, 'feature-receipt.md').status === 'ok';
   const stateKey = JSON.stringify({
@@ -99,6 +117,10 @@ try {
     Head: runtimeContext.head,
     context_id: runtimeContext.context_id,
     phase,
+    workflow_contract: active.workflowContract || null,
+    queue_ready: active.queueReady !== false,
+    task_state: taskState,
+    proof_state: proofState,
     done: counts.done || 0,
     total: tasks.length,
     feature_receipt_present: featureReceiptPresent,
@@ -108,9 +130,12 @@ try {
   try { previous = fs.readFileSync(cache, 'utf8').trim(); } catch { /* first run */ }
 
   if (previous === stateKey) {
+    const migration = processWorkflow && active.queueReady === false
+      ? ' Add `Specs-Contract: process-first-ready-v1` after the plan title before tasks can enter Next.'
+      : '';
     process.stdout.write(
       `> Spec \`${active.featureName}\` @ \`${phase}\` `
-      + `(${counts.done || 0}/${tasks.length} tasks done). Tollgate active.\n`
+      + `(${counts.done || 0}/${tasks.length} tasks done). Tollgate active.${migration}\n`
     );
     process.exit(0);
   }
@@ -125,6 +150,9 @@ try {
     lines.push(`- Flash verification pending: ${flashTasks.map((taskPath) => `\`${taskPath}\``).join(', ')}. A PASS proof keeps the persisted task in_progress until explicit sync-finalize.`);
   }
   if (processWorkflow) {
+    if (active.queueReady === false) {
+      lines.push('- Migration required: add `Specs-Contract: process-first-ready-v1` after the plan title before tasks can enter Next.');
+    }
     lines.push(
       '- Sync each flat task `Status:` only after verified work; task proof belongs in that task\'s inline `## Receipt`.',
       `- Workflow source: \`specs/${active.featureName}/plan.md\`; Stop revalidates every task currently marked done.`,