@haposoft/cafekit 0.13.1 → 0.13.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.13.1",
+  "version": "0.13.3",
   "description": "Claude Code-first spec-driven workflow for AI coding assistants. Bundles CafeKit hapo: skills, runtime hooks, agents, and installer scaffolding.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",

package/src/claude/hooks/task-scaffold-guard.cjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) 2026 Haposoft. MIT License.
+ *
+ * PreToolUse Hook — task-scaffold-guard.cjs
+ * Implements: https://docs.anthropic.com/en/docs/claude-code/hooks
+ *
+ * Forces spec task files to be GENERATED via spec-scaffold.cjs instead of
+ * hand-written. Field tests showed the model dodges the (opt-in) scaffold step
+ * and raw-`Write`s every task file — the single biggest output-token cost of a
+ * spec run. This hook blocks `Write` to `specs/<feature>/tasks/task-*.md`, so
+ * the only path to a task file is: scaffold (creates the stub) -> Edit (fills it).
+ *
+ * Scope is deliberately narrow — it only ever blocks the `Write` tool on a task
+ * file path. `Edit`/`MultiEdit` (filling a stub), and `Write` to any other file
+ * (requirements.md, design.md, source code) are never touched. The scaffold
+ * script itself writes via Node fs through a Bash call, not the `Write` tool, so
+ * it is never blocked.
+ *
+ * Safety valves:
+ *   1. fail-open when spec-scaffold.cjs is absent — you cannot force a tool that
+ *      is not installed, so a hook shipped without its script must not deadlock.
+ *   2. actionable block message — prints the exact scaffold command to run.
+ *   3. escape hatch — "spec": { "scaffold_guard": false } in .claude/runtime.json.
+ *
+ * Exit: 0 = allow, 2 = block.
+ */
+
+try {
+  const fs   = require('fs');
+  const path = require('path');
+
+  const stdin = fs.readFileSync(0, 'utf8').trim();
+  if (!stdin) process.exit(0);
+
+  const data      = JSON.parse(stdin);
+  const toolName  = data.tool_name  || '';
+  const toolInput = data.tool_input || {};
+  const cwd       = data.cwd        || process.cwd();
+
+  // Only `Write` can create a file from scratch. Edit/MultiEdit require an
+  // existing file, so filling a scaffolded stub is always allowed.
+  if (toolName !== 'Write') process.exit(0);
+
+  const filePath = toolInput.file_path || toolInput.path || '';
+  if (!filePath) process.exit(0);
+
+  // Match a spec task file: .../specs/<feature>/tasks/task-<...>.md
+  const norm = filePath.replace(/\\/g, '/');
+  const isTaskFile = /(^|\/)specs\/[^/]+\/tasks\/task-[^/]+\.md$/.test(norm);
+  if (!isTaskFile) process.exit(0);
+
+  // Valve 3: explicit escape hatch via .claude/runtime.json (fail-closed: a
+  // missing/broken runtime.json keeps the guard ON).
+  let runtime = {};
+  try {
+    const rp = path.join(cwd, '.claude', 'runtime.json');
+    if (fs.existsSync(rp)) runtime = JSON.parse(fs.readFileSync(rp, 'utf8'));
+  } catch { /* malformed runtime.json -> keep guard on */ }
+  if (runtime.spec && runtime.spec.scaffold_guard === false) process.exit(0);
+
+  // Valve 1: fail-open if the scaffold script is not installed next to this hook
+  // (hook lives in .claude/hooks/, script in .claude/scripts/). Forcing a tool
+  // that does not exist would deadlock task creation.
+  const scaffold = path.join(__dirname, '..', 'scripts', 'spec-scaffold.cjs');
+  if (!fs.existsSync(scaffold)) process.exit(0);
+
+  // Valve 2: block with an actionable message carrying the exact command.
+  const m = norm.match(/(^|\/)specs\/([^/]+)\/tasks\//);
+  const feature = m ? m[2] : '<feature>';
+  console.log(
+    `TASK SCAFFOLD REQUIRED: task files must be generated, not hand-written.\n` +
+    `Blocked Write: ${filePath}\n\n` +
+    `Generate the stub(s), then Edit-fill the {{...}} placeholders:\n` +
+    `  node .claude/scripts/spec-scaffold.cjs ${feature} --tasks "R0-01-slug,R1-01-slug,..." --tasks-only\n` +
+    `Then use Edit (not Write) on each tasks/task-*.md stub.\n` +
+    `Override: set "spec": { "scaffold_guard": false } in .claude/runtime.json`
+  );
+  process.exit(2);
+
+} catch (e) {
+  // Never let a hook crash block the user — log and fail-open.
+  try {
+    const fs = require('fs'), p = require('path');
+    const d = p.join(__dirname, '.logs');
+    if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
+    fs.appendFileSync(p.join(d, 'hook-log.jsonl'),
+      JSON.stringify({ ts: new Date().toISOString(), hook: 'task-scaffold-guard', status: 'crash', error: e.message }) + '\n');
+  } catch (_) {}
+  process.exit(0);
+}

package/src/claude/migration-manifest.json

@@ -90,6 +90,7 @@
       "hooks/usage.cjs",
       "hooks/privacy-block.cjs",
       "hooks/inspect-block.cjs",
+      "hooks/task-scaffold-guard.cjs",
       "hooks/rules.cjs",
       "hooks/spec-state.cjs",
       "hooks/state.cjs",

package/src/claude/scripts/validate-spec-output.cjs

@@ -132,6 +132,28 @@ function validateTaskSections(taskPath, content, errors) {
   }
 }
 
+/**
+ * Task files are created from the scaffold template (the scaffold-guard hook
+ * forces creation through it), so every task starts as a stub full of `{{...}}`
+ * placeholders. The hook guarantees the stub is CREATED via scaffold, but
+ * nothing guaranteed the model FILLED it. An unfilled `{{...}}` is an
+ * incomplete task — SKILL.md: "Leave NO {{...}} placeholder ... fails DoCT" —
+ * so it is a hard error here. A `.../` path fragment is a not-yet-resolved path
+ * placeholder; it is only a warning, because it usually survives in prose Steps
+ * while the Related Files table (which spec-ground.cjs does verify) is already
+ * concrete. Matching `\.\.\.\/` (three dots + slash) avoids flagging a relative
+ * `../` path or a prose ellipsis.
+ */
+function validateTaskPlaceholders(taskPath, content, errors, warnings) {
+  const stub = content.match(/\{\{[^}\n]+\}\}/);
+  if (stub) {
+    errors.push(`${taskPath}: unfilled scaffold placeholder ${stub[0]} — task stub was not completed`);
+  }
+  if (/\.\.\.\//.test(content)) {
+    warnings.push(`${taskPath}: contains a '.../' path placeholder — replace with a concrete path`);
+  }
+}
+
 /**
  * Each phase completion must carry its own timestamp. Reusing `timestamps.init`
  * for a later phase is forbidden (SKILL.md spec.json Update Rules). This used to
@@ -344,6 +366,7 @@ function validateSpec(specDir) {
     const fullPath = path.join(specDir, taskFile);
     const content = fs.readFileSync(fullPath, 'utf8');
     validateTaskSections(taskFile, content, errors);
+    validateTaskPlaceholders(taskFile, content, errors, warnings);
 
     const idRe = /\b((?:REQ-\d+)|(?:R\d+))\b/gi;
     let match;

package/src/claude/settings/settings.json

@@ -67,6 +67,15 @@
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/inspect-block.cjs\""
           }
         ]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/task-scaffold-guard.cjs\""
+          }
+        ]
       }
     ],
     "PostToolUse": [

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

@@ -333,9 +333,9 @@ Rules:
 - Load `rules/phase-decision-matrix.md` before generating task files. Treat "phase" as an implementation slice/task cluster, not a `phase-XX.md` artifact.
 - Load `rules/task-scoring-rubric.md` for every candidate task to decide priority, split/merge, spike needs, dependencies, parallel eligibility, and evidence depth.
 - Load `references/ask-user-question-gates.md`; if scoring reveals unapproved scope expansion or an unresolved user-owned choice, pause before writing task files.
-- **Scaffold instead of hand-writing (output-cost reducer).** Once the task list is decided, generate the stubs with the CLI rather than `Write`-ing each file by hand:
+- **Scaffold is mandatory — raw `Write` to a task file is blocked.** A PreToolUse hook (`task-scaffold-guard.cjs`) rejects any `Write` whose path matches `specs/<feature>/tasks/task-*.md`. The only path to a task file is scaffold → Edit. Once the task list is decided, generate the stubs:
   `node .claude/scripts/spec-scaffold.cjs <feature> --tasks "R0-01-slug,R1-01-slug,..." --tasks-only`
-  This creates each `tasks/task-R*.md` from `templates/task.md` and merges `task_files` + `task_registry` into the existing `spec.json` (pending, no overwrite of already-filled tasks). Then **Edit-fill** the `{{...}}` placeholders in each stub. Hand-writing whole task files is the single biggest output-token cost — scaffold + fill cuts it.
+  This creates each `tasks/task-R*.md` from `templates/task.md` and merges `task_files` + `task_registry` into the existing `spec.json` (pending, no overwrite of already-filled tasks). Then **Edit-fill** the `{{...}}` placeholders in each stub (`Edit`/`MultiEdit` are allowed; `Write` is not). (The guard fails open if the scaffold script is absent, and can be disabled via `"spec": { "scaffold_guard": false }` in `.claude/runtime.json`.)
 - Each task file follows template `templates/task.md` (scaffold already applies it). **Leave NO `{{...}}` placeholder unfilled** — a stub with placeholders is an incomplete task.
 - `Related Files` and test plans must inherit paths, contracts, and test targets from the codebase scout. If exact files/tests cannot be named for an enhancement, run targeted inspect before generating tasks. Every `Related Files` path will be grounded (Layer 2) at Step 8.5 — phantom paths hard-fail, so cite real paths.
 - Each task file MUST include `Completion Criteria` and `Evidence` sections detailed enough that a downstream quality gate can prove the task is truly done. Existing specs may use `Task Test Plan & Verification Evidence` or legacy `Verification & Evidence`.