@haposoft/cafekit 0.13.0 → 0.13.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "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/spec-ground.cjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+/**
+ * CafeKit spec GROUNDING checker (Specs v2, Layer 2).
+ *
+ * The deterministic validator (`validate-spec-output.cjs`) checks spec SHAPE
+ * (headings, registry sync, coverage). It is blind to whether the file paths a
+ * task cites actually EXIST. This script closes that gap: it parses every task's
+ * `Related Files` table and verifies, against the real work tree, that each
+ * Modify/Delete/Read path exists — unless another task in the same spec Creates
+ * it first (intra-spec resolution).
+ *
+ * Why active-grep instead of opt-in: field tests showed opt-in checks get
+ * skipped by the author. Grounding runs unconditionally over whatever paths the
+ * tasks already declare, so it cannot be dodged by choosing a different format.
+ *
+ * Usage:
+ *   node spec-ground.cjs <specDir> [--root <work-context>]
+ *
+ * <specDir>  : path to specs/<feature>  (relative or absolute)
+ * --root     : work tree the paths resolve against. Default: two levels up from
+ *              specDir (…/<root>/specs/<feature> -> <root>). Override for
+ *              monorepos where the spec lives apart from the code.
+ *
+ * Exit: 0 = GROUNDED, 1 = FAIL (missing path), 2 = usage error.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function usage() {
+  console.error('Usage: node spec-ground.cjs <specDir> [--root <work-context>]');
+}
+
+function parseArgs(argv) {
+  const args = { specDir: null, root: null };
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === '--root') args.root = argv[++i];
+    else if (!args.specDir) args.specDir = argv[i];
+  }
+  return args;
+}
+
+function listTaskFiles(specDir) {
+  const tasksDir = path.join(specDir, 'tasks');
+  if (!fs.existsSync(tasksDir)) return [];
+  return fs
+    .readdirSync(tasksDir, { withFileTypes: true })
+    .filter((e) => e.isFile() && e.name.endsWith('.md'))
+    .map((e) => path.join(tasksDir, e.name))
+    .sort();
+}
+
+/**
+ * Pull rows out of a markdown `## Related Files` table. Returns
+ * [{ path, action, taskFile }]. Tables look like:
+ *   | Path | Action | Description |
+ *   | `front/x.vue` | Modify | ... |
+ */
+function parseRelatedFiles(content, taskFile) {
+  const rows = [];
+  const lines = content.split('\n');
+  let inSection = false;
+  for (const line of lines) {
+    if (/^##+\s+Related Files\s*$/i.test(line)) { inSection = true; continue; }
+    if (inSection && /^##+\s+/.test(line)) break; // next heading ends section
+    if (!inSection) continue;
+    if (!line.trim().startsWith('|')) continue;
+
+    const cells = line.split('|').map((c) => c.trim());
+    // cells[0] is '' (leading pipe). path=cells[1], action=cells[2].
+    const rawPath = (cells[1] || '').replace(/`/g, '').trim();
+    const action = (cells[2] || '').toLowerCase().trim();
+    if (!rawPath || rawPath === 'path') continue;          // header row
+    if (/^-+$/.test(rawPath)) continue;                    // separator row
+    if (!action || !/(create|modify|delete|read)/.test(action)) continue;
+    rows.push({ path: rawPath, action, taskFile: path.basename(taskFile) });
+  }
+  return rows;
+}
+
+/** Lenient existence check with minimal glob handling. */
+function pathExists(root, p) {
+  // Glob-ish path (e.g. `assets/{x,instagram,facebook}.svg` or `dir/*.ts`):
+  // verify the parent directory exists rather than the literal name.
+  if (/[{*]/.test(p)) {
+    const parent = path.dirname(p.replace(/\{.*$/, '').replace(/\*.*$/, ''));
+    return fs.existsSync(path.join(root, parent));
+  }
+  return fs.existsSync(path.join(root, p));
+}
+
+function main() {
+  const { specDir: specInput, root: rootInput } = parseArgs(process.argv);
+  if (!specInput) { usage(); process.exit(2); }
+
+  const specDir = path.resolve(process.cwd(), specInput);
+  if (!fs.existsSync(specDir)) {
+    console.error(`FAIL ${specInput}\n- spec directory does not exist`);
+    process.exit(1);
+  }
+  // Default work-context: two levels up (…/<root>/specs/<feature>).
+  const root = rootInput
+    ? path.resolve(process.cwd(), rootInput)
+    : path.resolve(specDir, '..', '..');
+
+  const taskFiles = listTaskFiles(specDir);
+  const allRows = [];
+  for (const tf of taskFiles) {
+    allRows.push(...parseRelatedFiles(fs.readFileSync(tf, 'utf8'), tf));
+  }
+
+  // Paths that will exist because a task Creates them (intra-spec resolution).
+  const createdPaths = new Set(
+    allRows.filter((r) => r.action.includes('create')).map((r) => r.path),
+  );
+
+  const errors = [];
+  const warnings = [];
+  let checked = 0;
+
+  for (const row of allRows) {
+    const onDisk = pathExists(root, row.path);
+    if (row.action.includes('create')) {
+      if (onDisk) warnings.push(`${row.taskFile}: Create path already exists (will overwrite): ${row.path}`);
+      continue;
+    }
+    // modify / delete / read must exist OR be created by another task in-spec.
+    checked++;
+    if (!onDisk && !createdPaths.has(row.path)) {
+      errors.push(`${row.taskFile}: ${row.action} path not found in work tree: ${row.path}`);
+    }
+  }
+
+  for (const w of warnings) console.warn(`[WARN] ${w}`);
+
+  const rel = path.relative(process.cwd(), specDir) || specDir;
+  if (errors.length > 0) {
+    console.error(`FAIL ${rel}  (root: ${root})`);
+    for (const e of errors) console.error(`- ${e}`);
+    console.error(`\n${errors.length} missing / ${checked} checked path(s).`);
+    process.exit(1);
+  }
+  console.log(`GROUNDED ${rel}  (${checked} path(s) verified against ${root})`);
+}
+
+main();

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

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+/**
+ * CafeKit spec SCAFFOLD generator (Specs v2 — output-cost reducer).
+ *
+ * Field tests showed the dominant cost of a spec run is OUTPUT tokens: the
+ * model hand-Writes spec.json + every task file from scratch (a 16-task spec
+ * emitted ~935K output tokens). This script does the mechanical scaffolding so
+ * the model only has to Edit-fill content, not Write whole files.
+ *
+ * It creates spec.json (with task_files + task_registry pre-populated) and one
+ * stub per task from the canonical templates, leaving the `{{...}}` placeholders
+ * for the model to fill. It NEVER overwrites an existing spec directory.
+ *
+ * Usage:
+ *   node spec-scaffold.cjs <feature> --tasks "R0-01-slug,R1-01-slug,..." \
+ *        [--lang en] [--title "..."] [--specs-root specs]
+ *
+ * Exit: 0 = scaffolded, 2 = usage/precondition error.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const TEMPLATES = path.join(__dirname, '..', 'skills', 'specs', 'templates');
+const TASK_ID_RE = /^R(\d+)-(\d+)-([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+
+function usage() {
+  console.error('Usage: node spec-scaffold.cjs <feature> --tasks "R0-01-slug,R1-01-slug" [--lang en] [--title "..."] [--specs-root specs]');
+}
+
+function parseArgs(argv) {
+  const a = { feature: null, tasks: null, lang: 'en', title: null, specsRoot: 'specs', tasksOnly: false };
+  for (let i = 2; i < argv.length; i++) {
+    const v = argv[i];
+    if (v === '--tasks') a.tasks = argv[++i];
+    else if (v === '--lang') a.lang = argv[++i];
+    else if (v === '--title') a.title = argv[++i];
+    else if (v === '--specs-root') a.specsRoot = argv[++i];
+    else if (v === '--tasks-only') a.tasksOnly = true;
+    else if (!a.feature) a.feature = v;
+  }
+  return a;
+}
+
+function readTemplate(name) {
+  const p = path.join(TEMPLATES, name);
+  if (!fs.existsSync(p)) {
+    console.error(`precondition: template not found: ${p}`);
+    process.exit(2);
+  }
+  return fs.readFileSync(p, 'utf8');
+}
+
+function titleFromSlug(slug) {
+  const s = slug.replace(/-/g, ' ');
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+function registryEntry(t) {
+  return {
+    id: `R${t.req}-${t.seq}`,
+    title: titleFromSlug(t.slug),
+    status: 'pending',
+    dependencies: [],
+    blocker: null,
+    started_at: null,
+    completed_at: null,
+    last_updated_at: null,
+  };
+}
+
+function fillTask(taskTpl, t, feature) {
+  return taskTpl
+    .replace(/\{\{REQ_NUMBER\}\}/g, t.req)
+    .replace(/\{\{SEQ\}\}/g, t.seq)
+    .replace(/\{\{TITLE\}\}/g, titleFromSlug(t.slug))
+    .replace(/\{\{FEATURE_NAME\}\}/g, feature)
+    .replace(/\{\{PRIORITY\}\}/g, 'P2')
+    .replace(/\{\{EFFORT\}\}/g, 'TBD')
+    .replace(/\{\{DEPENDENCIES\}\}/g, 'none');
+}
+
+function nowIso() {
+  // Local ISO with offset, e.g. 2026-06-21T12:30:00+07:00
+  const d = new Date();
+  const pad = (n) => String(n).padStart(2, '0');
+  const off = -d.getTimezoneOffset();
+  const sign = off >= 0 ? '+' : '-';
+  const oh = pad(Math.floor(Math.abs(off) / 60));
+  const om = pad(Math.abs(off) % 60);
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}${sign}${oh}:${om}`;
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  if (!args.feature || !args.tasks) { usage(); process.exit(2); }
+
+  const ids = args.tasks.split(',').map((s) => s.trim()).filter(Boolean);
+  const parsed = [];
+  for (const id of ids) {
+    const m = id.match(TASK_ID_RE);
+    if (!m) {
+      console.error(`precondition: invalid task id "${id}" (want R{N}-{SEQ}-<slug>, SEQ 2 digits)`);
+      process.exit(2);
+    }
+    parsed.push({ raw: id, req: m[1], seq: m[2], slug: m[3], file: `tasks/task-${id}.md` });
+  }
+
+  const specDir = path.resolve(process.cwd(), args.specsRoot, args.feature);
+  const taskTpl = readTemplate('task.md');
+  const ts = nowIso();
+  const created = [];
+
+  // --- --tasks-only: add task stubs + merge registry into an existing spec ---
+  if (args.tasksOnly) {
+    const specPath = path.join(specDir, 'spec.json');
+    if (!fs.existsSync(specPath)) {
+      console.error(`precondition: --tasks-only needs an existing spec.json at ${specPath}`);
+      process.exit(2);
+    }
+    const spec = JSON.parse(fs.readFileSync(specPath, 'utf8'));
+    spec.task_files = spec.task_files || [];
+    spec.task_registry = spec.task_registry || {};
+    fs.mkdirSync(path.join(specDir, 'tasks'), { recursive: true });
+    for (const t of parsed) {
+      const abs = path.join(specDir, t.file);
+      if (fs.existsSync(abs)) continue; // never overwrite an already-filled task
+      fs.writeFileSync(abs, fillTask(taskTpl, t, args.feature));
+      if (!spec.task_files.includes(t.file)) spec.task_files.push(t.file);
+      spec.task_registry[t.file] = registryEntry(t);
+      created.push(t.file);
+    }
+    spec.task_files.sort();
+    spec.updated_at = ts;
+    fs.writeFileSync(specPath, JSON.stringify(spec, null, 2) + '\n');
+    const relTo = path.relative(process.cwd(), specDir) || specDir;
+    console.log(`SCAFFOLDED (tasks-only) ${relTo}`);
+    console.log(`- ${created.length} new task stub(s); task_files + task_registry merged.`);
+    console.log(`- NEXT: Edit-fill {{...}} in each stub; set dependencies; run validator + spec-ground.`);
+    return;
+  }
+
+  if (fs.existsSync(specDir)) {
+    console.error(`precondition: spec dir already exists, refusing to overwrite: ${specDir}`);
+    process.exit(2);
+  }
+
+  fs.mkdirSync(path.join(specDir, 'tasks'), { recursive: true });
+  fs.mkdirSync(path.join(specDir, 'reports'), { recursive: true });
+
+  // --- spec.json (from spec-state.json template) ---
+  const spec = JSON.parse(readTemplate('spec-state.json'));
+  spec.feature_name = args.feature;
+  spec.created_at = ts;
+  spec.updated_at = ts;
+  spec.language = args.lang;
+  spec.timestamps = spec.timestamps || {};
+  spec.timestamps.init = ts;
+  spec.scope_lock = spec.scope_lock || {};
+  spec.scope_lock.source = args.title || `{{PROJECT_DESCRIPTION}}`;
+  spec.task_files = parsed.map((t) => t.file);
+  spec.task_registry = {};
+  for (const t of parsed) spec.task_registry[t.file] = registryEntry(t);
+  fs.writeFileSync(path.join(specDir, 'spec.json'), JSON.stringify(spec, null, 2) + '\n');
+  created.push('spec.json');
+
+  // --- doc templates (placeholders left for the model to fill) ---
+  for (const [tpl, out] of [['requirements.md', 'requirements.md'], ['research.md', 'research.md'], ['design.md', 'design.md']]) {
+    const body = readTemplate(tpl).replace(/\{\{FEATURE_NAME\}\}/g, args.feature);
+    fs.writeFileSync(path.join(specDir, out), body);
+    created.push(out);
+  }
+
+  // --- task stubs (fill the cheap placeholders; leave the rest) ---
+  for (const t of parsed) {
+    fs.writeFileSync(path.join(specDir, t.file), fillTask(taskTpl, t, args.feature));
+    created.push(t.file);
+  }
+
+  const rel = path.relative(process.cwd(), specDir) || specDir;
+  console.log(`SCAFFOLDED ${rel}`);
+  console.log(`- ${created.length} files created: spec.json + 3 docs + ${parsed.length} task stub(s)`);
+  console.log(`- task_files + task_registry pre-populated (${parsed.length} entries, all pending)`);
+  console.log(`- NEXT: Edit-fill the {{...}} placeholders (do NOT leave any); set dependencies in task_registry; run validator + spec-ground before ready.`);
+}
+
+main();

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

@@ -258,9 +258,24 @@ Load: `references/scope-inquiry.md`
 - If Risk = **Chaotic** → exit spec workflow, redirect to `hapo:hotfix`
 - If Risk = **Complex** → include spike/prototype tasks in the spec
 - If Blast Radius = **Critical Path** → spec MUST include rollback strategy and test coverage requirements
+- **Complexity smell check (by numbers)** — quick YAGNI tripwires: >8 files touched / >2 new classes-services / >12 task files → challenge or simplify; **>15 task files → split into sibling specs** (a mega-spec is slow + failure-prone, per field test). Surface tripwires in the scope summary; never silently build the mega-version.
 - User picks scope level: Expand / Hold / Reduce
 - **Skip if:** trivial task (< 20 words, 1 file, user says "just do it")
 
+#### Execution Tier (auto-scale — set right after the 5-Dimension assessment)
+Pick ONE tier from the assessment; it controls how deep the pipeline runs so small specs stay cheap. Record it in `spec.json.design_context.execution_tier`.
+
+| Tier | Trigger | Research (Step 5 external) | Discovery (Step 6) | Red-Team (Step 8) | Always runs |
+|---|---|---|---|---|---|
+| **Light** | Cynefin Clear + Blast Isolated + likely ≤2 tasks | skip (record skip rationale) | minimal | skip → Validate-only | scope_lock, EARS, **Layer 1 + Layer 2 grounding** |
+| **Standard** | default (Complicated / Moderate blast / 3-4 tasks) | targeted | light | per Step 8 auto-decision | all of the above |
+| **Deep** | Complex/Critical-path / security-migration / 5+ tasks | full (researchers + per-area scout) | full | Red-Team → Validate (mandatory) | all of the above |
+
+Rules:
+- Grounding (Layer 2) + structural validator (Layer 1) + scope_lock **never skip**, any tier — they are the quality floor, not depth knobs.
+- Light tier is the antidote to "small spec, full-pipeline overhead". Do NOT use Light for auth/payment/migration/schema/privacy work — those force Deep regardless of size.
+- Tier only changes *research/discovery/review depth*; it never changes the Hard Output Contract or DoCT.
+
 ### Step 4: Init
 - Check for duplicate slugs in `specs/` via Glob
 - Create directory `specs/<feature-name>/`
@@ -286,7 +301,7 @@ Load: `references/scope-inquiry.md`
 - External/current research must prefer official docs, standards, primary sources, or maintained upstream references. Record source links and the date/context of the finding.
 - Write `research.md` before final requirements. It MUST include an Evidence Summary with: codebase scout result, external research result or skip rationale, selected decision, rejected alternatives, remaining gaps, and downstream task/test implications.
 - If evidence exposes unresolved architecture choices, unclear acceptance criteria, or multiple viable approaches with no obvious winner, stop and route to `/hapo:brainstorm` instead of forcing a spec.
-- Write requirements in **EARS** format (see `rules/ears-format.md`)
+- Write requirements in **EARS** format (see `rules/ears-format.md`). Give each acceptance criterion an **explicit literal ID `R{N}.{M}`** (e.g. `- **R1.1** When ...`), NOT a bare numbered list. This activates per-criterion coverage at Layer 1 (each `R1.1` must be mapped by a task `_Requirements: 1.1_`). A bare `1. 2. 3.` list silently disables sub-criterion coverage — do not use it for non-trivial specs.
 - **Feasibility Check:** Cross-check each requirement against known technical constraints from `research.md`.
 - Each requirement gets a unique numeric ID
 - **Verify Quality:** Before proceeding, assert each requirement is: *Singular, Unambiguous, Testable, and has a numeric ID*. Include Non-Functional Requirements (Performance, Security, Scalability, Reliability, Accessibility).
@@ -318,8 +333,11 @@ Load: `references/scope-inquiry.md`
 - 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.
-- Each task file follows template `templates/task.md`
-- `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.
+- **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 (`Edit`/`MultiEdit` are allowed; `Write` is not). Hand-writing whole task files is the single biggest output-token cost — scaffold + fill cuts it. (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`.
 - Each task's `Evidence` MUST choose the right proof type for the touched surface: unit for pure logic, component/integration for UI or state wiring, E2E/UI flow for complete user workflows, visual/responsive checks for style/layout work, accessibility checks for interactive UI, smoke checks for scaffold/config, regression checks for bug fixes, and performance/security checks only when the requirement or risk calls for them.
 - Every task MUST preserve the approved `scope_lock`: implement all scoped acceptance criteria for its requirement, avoid out-of-scope features, and record any intentional deferral as a named later task rather than implicit omission.
@@ -386,6 +404,21 @@ Each task file MUST be **self-contained and implementation-ready** — detailed
 
 **FORBIDDEN:** Task files with only vague checkboxes and no exact files, requirements, or evidence. Compact is good; vague is invalid.
 
+#### Definition of a Complete Task (DoCT) — the quality bar
+A task is "complete enough to implement without guessing" only when ALL hold. Each item is enforced by a named mechanism, not goodwill:
+
+| DoCT element | Enforced by |
+|---|---|
+| **Related Files** name exact real paths (Create/Modify/Delete) | Layer 2 grounding (`spec-ground.cjs`) — phantom path fails |
+| **Contract** (API/DB/event shape) stated concretely | Layer 1 contract-drift check (`<!-- contract:NAME -->`) |
+| **Acceptance** measurable (no "fast/nice/safe" without a threshold) | EARS rule + reviewer judgment |
+| **Evidence** uses commands that exist in the project (`package.json`) | Author + grounding spirit; never invent test commands |
+| **Reachability** names a real entrypoint/caller | `Runtime reachability verification` (Layer 1 presence) + judgment |
+| **Requirements mapping** present (`_Requirements: x.y_`) | Layer 1 coverage check |
+| **FE fidelity** — if a visual reference (image/Figma/tokens/style guide) is provided, the task carries the concrete values (hex/font/spacing/verbatim text) + a `match <reference>` constraint | `tasks-generation.md` Frontend Fidelity Rule + reviewer/visual check |
+
+A stub with unfilled `{{...}}` placeholders fails DoCT by definition. The two scripts (Layer 1 structural + Layer 2 grounding) are the floor; reviewer judgment covers the rest.
+
 ### Step 8: Validation Review (Optional)
 Load: `references/review.md` + `rules/design-review.md`
 - Load `references/ask-user-question-gates.md` before applying validation or red-team changes. User approval is required when findings modify approved scope, requirements, canonical contracts, design decisions, or task behavior.
@@ -398,14 +431,17 @@ Load: `references/review.md` + `rules/design-review.md`
 - **PROHIBITION:** The system MUST NOT skip Red Team because of a prior code-auditor review. Code review ≠ Spec review.
 - **PROHIBITION:** The system MUST NOT create `.ts`, `.js`, `.py` or any implementation files during validation. Spec-only outputs.
 - **Reconciliation Rule:** `validation.status = "completed"` is forbidden until all accepted findings and validation decisions are physically propagated into `requirements.md`, `design.md`, `tasks/*.md`, and `spec.json` where applicable.
-- **Deterministic Gate:** Run `node .claude/scripts/validate-spec-output.cjs specs/<feature>` after all fixes and before final output. Script failure overrides any LLM checklist result and blocks `ready_for_implementation = true`.
+- **Deterministic Gate (2 layers):** Run `node .claude/scripts/validate-spec-output.cjs specs/<feature>` (structural) AND `node .claude/scripts/spec-ground.cjs specs/<feature> [--root <work-context>]` (grounding — paths exist) after all fixes and before final output. Either script failing overrides any LLM checklist result and blocks `ready_for_implementation = true`.
 
 ### Step 8.5: Finalization Audit (MANDATORY)
 - Re-scan the `tasks/` directory and rebuild `spec.json.task_files` + `task_registry` from the real filesystem (sorted relative paths; preserve task status when the path still matches).
-- Run `node .claude/scripts/validate-spec-output.cjs specs/<feature>` and treat any non-zero exit as a blocking failure.
+- **Layer 1 — Structural:** run `node .claude/scripts/validate-spec-output.cjs specs/<feature>` and treat any non-zero exit as a blocking failure.
+- **Layer 2 — Grounding (MANDATORY):** run `node .claude/scripts/spec-ground.cjs specs/<feature> [--root <work-context>]` and treat any non-zero exit as a blocking failure. This greps the real work tree to verify every `Related Files` path a task cites (Modify/Delete/Read) actually exists — or is Created by another task in the spec. Pass `--root` when the code lives apart from the spec (monorepo / sibling project). A spec that PASSES Layer 1 but FAILS Layer 2 is trolling phantom files and is NOT ready.
 
 **Validator-enforced (do not re-check by hand — a clean exit clears all of these):** task_files/task_registry synced to disk; task naming `tasks/task-R{N}-{SEQ}-<slug>.md`; no forbidden artifacts; research.md Evidence Summary present; every requirement **and sub-criterion** covered by a task; each task keeps the full template (Context, Constraints, Steps, Related Files, Completion Criteria, Evidence, Risk Assessment) plus Runtime reachability; numeric requirement IDs only; validation_recommended vs validation.status; timestamps not reused from init; ready_for_implementation blocked while any error exists.
 
+**Grounding-enforced (spec-ground.cjs — do not re-check by hand):** every Modify/Delete/Read path in any task's `Related Files` exists in the work tree or is Created earlier in the spec. Phantom paths hard-fail.
+
 **Judgment-only audit (validator cannot see these — assert manually):**
 - FAIL if a UI/app/runtime spec has multiple user-facing task outputs but no final integration/reachability task or section.
 - FAIL if accepted validation/red-team decisions exist in reports but are not reflected in implementation-facing sections (`Context`, `Steps`, `Requirements`, `Completion Criteria`, `Evidence`, canonical contracts, or requirements text).

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

@@ -121,8 +121,13 @@ Rules:
 3. Sort by severity: Critical → High → Medium
 4. Cap at 15 findings maximum
 
+#### Step 5.5: Evidence Filter (MANDATORY — auto-reject before merit)
+Before adjudicating, drop any finding whose `Location`/`Evidence` does not point at a concrete spot in the spec: a task/section name (`task-R2-01... §Steps`) or a verbatim quote of the offending text. A finding that only asserts a problem in the abstract ("this might race", "auth could be bypassed") **without citing where in the spec** is auto-`Reject (no evidence)` and is NOT counted toward the cap or shown to the user.
+
+Rationale: this is the spec-level analogue of ck-plan's `file:line` evidence gate. It stops reviewers from inventing plausible-sounding flaws that aren't actually in the artifact. A real flaw can always be located; an imagined one cannot.
+
 #### Step 6: Adjudicate
-For each finding, evaluate and propose: **Accept** or **Reject** with rationale.
+For each finding (that survived the Evidence Filter), evaluate and propose: **Accept** or **Reject** with rationale.
 
 #### Step 7: User Review
 Present via `AskUserQuestion`:

package/src/claude/skills/specs/references/scope-inquiry.md

@@ -48,6 +48,17 @@ Assess how many other parts of the system are affected if this change breaks or
 
 > **Rule**: If Blast Radius = Critical Path, the spec MUST include rollback strategy and explicit test coverage requirements in the task files.
 
+### Complexity Smell Check (by numbers)
+
+After the qualitative 5-Dimension pass, run a quick quantitative gut-check. These are YAGNI tripwires, not hard limits — when one trips, pause and justify or simplify before locking scope:
+
+- **> 8 files touched** → challenge whether the same goal is reachable with fewer; flag accidental scope creep.
+- **> 2 new classes / services / modules** → smell; justify each new abstraction (could an existing module absorb it?).
+- **> 12 task files** → the spec is large; consider splitting by deliverable boundary into sibling specs (cross-spec `blockedBy`) rather than one mega-spec.
+- **> 15 task files** → strong signal to split. A single mega-spec is slow to generate, prone to mid-run failure, and hard to review. Prefer 2-3 focused specs unless the work is genuinely one indivisible slice.
+
+If any tripwire fires, surface it in the Scope Inquiry summary and let the user decide (Expand / Hold / Reduce / Split). Do not silently build the mega-version.
+
 ## Level Selection
 
 After completing the 5-Dimension Assessment, present via `AskUserQuestion`:
@@ -77,6 +88,7 @@ Scope Inquiry:
 - Gap Size: [Small/Medium/Large] — [reason]
 - Risk Level: [Clear/Complicated/Complex/Chaotic] — [reason]
 - Blast Radius: [Isolated/Moderate/Critical Path] — [affected modules]
+- Complexity smells: [none | >8 files | >2 new services | >12 tasks → consider split | >15 tasks → split]
 - Minimum Change: [Essential gap vs Niceties]
-- User chose: [Expand / Hold / Reduce]
+- User chose: [Expand / Hold / Reduce / Split]
 ```

package/src/claude/skills/specs/rules/tasks-generation.md

@@ -192,6 +192,21 @@ Choose verification by task risk and touched surface. Do not force every task to
 
 `hapo:specs` writes the expected proof into each task. `hapo:develop` executes the task-local proof before marking the task done. `hapo:test` runs the broader system pass after implementation or for a requested feature scope.
 
+### Frontend Fidelity Rule (when a visual reference is provided)
+
+If the user/spec provides ANY visual reference for a frontend task — design image, Figma frame, screenshot, mockup, brand palette, design tokens, or a style guide — the task MUST reproduce it faithfully, not approximate it. Concretely, the task file MUST:
+
+1. **Extract concrete values into the task** (do NOT paraphrase as "make it look nice"): exact colors (`#DAF1EE`), font family + sizes, spacing/radius/shadow when the reference shows them, and verbatim UI text/labels (especially non-English copy, e.g. `「投稿を削除しました」`).
+2. **State a `MUST: match <reference>` constraint** naming the exact reference (e.g. `image_4.png` / Figma node / `tokens.css`), so fidelity is a requirement, not a suggestion.
+3. **Prove fidelity in Evidence**: a visual/runtime check that compares the rendered UI against the named reference (screenshot diff or side-by-side inspection), plus accessibility/contrast if interactive.
+
+Reuse vs new component:
+- **Reuse** an existing component → reference it by path; it carries the design system's style (no need to restate pixels).
+- **New** component (`Create`) WITH a reference → the task MUST cite the concrete tokens/values from the reference (this is the gap that lets new components drift from the design).
+- **New** component WITHOUT any reference → derive from a named sibling component or explicitly flag it as an open design question; never invent un-grounded styling silently.
+
+> Rationale: a spec that says "build the list screen" but omits the provided palette/text/spacing forces the implementer to guess, and the result drifts from what the user actually showed. When a reference exists, "looks roughly similar" is a failure — the task must carry the real values so the build matches the design.
+
 ## Task Hierarchy Rules
 
 ### Maximum 2 Levels

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

@@ -7,23 +7,24 @@
 
 ### Requirement 1: {{REQUIREMENT_AREA_1}}
 <!-- Requirement headings MUST include a leading numeric ID only (for example: "Requirement 1: ...", "1. Overview", "2 Feature: ..."). Alphabetic IDs like "Requirement A" are not allowed. -->
+<!-- Acceptance criteria use EXPLICIT literal IDs `R{N}.{M}` (R1.1, R1.2, ...), NOT a bare numbered list. This lets the validator verify per-criterion coverage (each R1.1 must be mapped by a task `_Requirements: 1.1_`). Do not switch to a bare `1. 2. 3.` list — that silently disables sub-criterion coverage. -->
 **Objective:** As a {{ROLE}}, I want {{CAPABILITY}}, so that {{BENEFIT}}
 
 #### Acceptance Criteria
-1. When [event], the [system] shall [response/action]
-2. If [trigger], then the [system] shall [response/action]
-3. While [precondition], the [system] shall [response/action]
-4. Where [feature is included], the [system] shall [response/action]
-5. The [system] shall [response/action]
+- **R1.1** When [event], the [system] shall [response/action]
+- **R1.2** If [trigger], then the [system] shall [response/action]
+- **R1.3** While [precondition], the [system] shall [response/action]
+- **R1.4** Where [feature is included], the [system] shall [response/action]
+- **R1.5** The [system] shall [response/action]
 
 ### Requirement 2: {{REQUIREMENT_AREA_2}}
 **Objective:** As a {{ROLE}}, I want {{CAPABILITY}}, so that {{BENEFIT}}
 
 #### Acceptance Criteria
-1. When [event], the [system] shall [response/action]
-2. When [event] and [condition], the [system] shall [response/action]
+- **R2.1** When [event], the [system] shall [response/action]
+- **R2.2** When [event] and [condition], the [system] shall [response/action]
 
-<!-- Additional requirements follow the same pattern -->
+<!-- Additional requirements follow the same pattern, with literal R{N}.{M} IDs -->
 
 ## Non-Functional Requirements
 
@@ -33,19 +34,19 @@
 **Objective:** As a system owner, I want predictable performance characteristics, so that the feature remains usable under expected load.
 
 #### Acceptance Criteria
-{{NEXT_REQ_NUMBER}}.1 The [system] shall [measurable performance metric, e.g. "respond within 500ms"]
-{{NEXT_REQ_NUMBER}}.2 The [system] shall [measurable scale metric, e.g. "support 100 concurrent users"]
+- **R{{NEXT_REQ_NUMBER}}.1** The [system] shall [measurable performance metric, e.g. "respond within 500ms"]
+- **R{{NEXT_REQ_NUMBER}}.2** The [system] shall [measurable scale metric, e.g. "support 100 concurrent users"]
 
 ### Requirement {{NEXT_REQ_NUMBER_PLUS_ONE}}: Security & Privacy
 **Objective:** As a security/compliance stakeholder, I want the feature to protect sensitive data and enforce access boundaries, so that the system is safe to ship.
 
 #### Acceptance Criteria
-{{NEXT_REQ_NUMBER_PLUS_ONE}}.1 The [system] shall [measurable security behavior, e.g. "encrypt data at rest using AES-256"]
-{{NEXT_REQ_NUMBER_PLUS_ONE}}.2 If [unauthorized or invalid condition], the [system] shall [deny or recover with explicit behavior]
+- **R{{NEXT_REQ_NUMBER_PLUS_ONE}}.1** The [system] shall [measurable security behavior, e.g. "encrypt data at rest using AES-256"]
+- **R{{NEXT_REQ_NUMBER_PLUS_ONE}}.2** If [unauthorized or invalid condition], the [system] shall [deny or recover with explicit behavior]
 
 ### Requirement {{NEXT_REQ_NUMBER_PLUS_TWO}}: Reliability & Availability
 **Objective:** As an operator, I want predictable failure handling, so that incidents remain diagnosable and recoverable.
 
 #### Acceptance Criteria
-{{NEXT_REQ_NUMBER_PLUS_TWO}}.1 If [failure condition], the [system] shall [recovery behavior]
-{{NEXT_REQ_NUMBER_PLUS_TWO}}.2 The [system] shall [durability / retry / fallback expectation]
+- **R{{NEXT_REQ_NUMBER_PLUS_TWO}}.1** If [failure condition], the [system] shall [recovery behavior]
+- **R{{NEXT_REQ_NUMBER_PLUS_TWO}}.2** The [system] shall [durability / retry / fallback expectation]

package/src/claude/skills/specs/templates/spec-state.json

@@ -60,6 +60,7 @@
   "design_context": {
     "discovery_mode": null,
     "discovery_reason": null,
+    "execution_tier": "standard",
     "validation_recommended": false
   },
   "validation": {