@haposoft/cafekit 0.12.0 → 0.13.1

package/package.json

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

@@ -77,6 +77,27 @@ try {
     return status === 'pending' && deps.every((dep) => taskStatusByPath.get(dep) === 'done');
   });
 
+  // ── State-change gate: only emit the full tollgate when spec state changed ──
+  // This hook runs on EVERY UserPromptSubmit. Re-printing the whole block when
+  // phase + done/total are unchanged is wasted context (~460 tok/turn). We keep
+  // a tiny state fingerprint in a temp file: same -> one-line reminder; changed
+  // -> full block (and refresh the fingerprint). Fail-open at every step.
+  const stateKey = `${phase}|${taskCounts.done || 0}/${taskEntries.length}`;
+  const cacheFile = path.join(__dirname, '.logs', 'tollgate-last.txt');
+
+  let lastKey = '';
+  try { lastKey = fs.readFileSync(cacheFile, 'utf8').trim(); } catch { /* first run */ }
+
+  if (lastKey === stateKey) {
+    console.log(`\n> 🔵 Spec \`${featureName}\` @ \`${phase}\` (${taskCounts.done || 0}/${taskEntries.length} tasks done). Tollgate active — sync \`spec.json\` when state changes.\n`);
+    process.exit(0);
+  }
+
+  try {
+    fs.mkdirSync(path.dirname(cacheFile), { recursive: true });
+    fs.writeFileSync(cacheFile, stateKey);
+  } catch { /* fail-open: if the write fails we still print the full block */ }
+
   // Format the output
   const lines = [];
   lines.push('');

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/scripts/validate-spec-output.cjs

@@ -85,6 +85,25 @@ function extractRequirementIds(requirementsText) {
   return [...ids].filter((id) => id !== 'R0').sort();
 }
 
+/**
+ * Extract sub-criteria IDs (e.g. R3.4) ONLY when requirements.md declares them
+ * as explicit literals — bold `**R3.4**` or a line-leading `R3.4`. Specs that
+ * write acceptance criteria as a plain numbered list under a heading declare no
+ * such literals, so this returns empty and per-criterion coverage is skipped
+ * for them (no behaviour change). This is a progressive check: it rewards an
+ * unambiguous format, it never penalises the legacy one.
+ */
+function extractSubCriteriaIds(requirementsText) {
+  const ids = new Set();
+  const re = /(?:^|\s)\**(R\d+\.\d+)\**/gim;
+  let match;
+  while ((match = re.exec(requirementsText)) !== null) {
+    const id = match[1].toUpperCase();
+    if (!id.startsWith('R0.')) ids.add(id);
+  }
+  return [...ids].sort();
+}
+
 function validateTaskSections(taskPath, content, errors) {
   const hasContext = hasHeading(content, 'Context');
   const hasConstraints = hasHeading(content, 'Constraints');
@@ -113,6 +132,75 @@ function validateTaskSections(taskPath, content, errors) {
   }
 }
 
+/**
+ * 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
+ * be a prompt-only rule the model had to remember; here it is a hard backstop.
+ */
+function validateTimestamps(spec, errors) {
+  const ts = spec.timestamps;
+  if (!ts || typeof ts !== 'object') return;
+  const init = ts.init;
+  if (!init) return;
+
+  for (const phase of ['requirements_done', 'design_done', 'tasks_done']) {
+    if (ts[phase] && ts[phase] === init) {
+      errors.push(
+        `spec.json.timestamps.${phase}: reuses init timestamp (${init}); ` +
+          'each phase must stamp its own completion time',
+      );
+    }
+  }
+}
+
+/** Normalize a fenced code block body for byte-comparison: trim + collapse
+ * trailing whitespace per line + drop blank edges. Keeps inner structure so a
+ * real field rename (user_name vs userName) still differs. */
+function normalizeBlock(body) {
+  return body
+    .split('\n')
+    .map((line) => line.replace(/\s+$/, ''))
+    .join('\n')
+    .replace(/^\n+|\n+$/g, '');
+}
+
+/**
+ * Parse canonical contract definitions from design.md. A definition is an HTML
+ * marker `<!-- contract:NAME -->` immediately followed by a fenced code block.
+ * Returns a Map<name, normalizedBody>. Empty when the spec uses no markers —
+ * which makes the whole cross-layer check opt-in (no effect on legacy specs).
+ */
+function extractContractDefs(designText) {
+  const defs = new Map();
+  const re = /<!--\s*contract:([A-Za-z0-9_.-]+)\s*-->\s*\n```[^\n]*\n([\s\S]*?)\n```/g;
+  let match;
+  while ((match = re.exec(designText)) !== null) {
+    defs.set(match[1], normalizeBlock(match[2]));
+  }
+  return defs;
+}
+
+/**
+ * From a task body, return the contracts it claims plus the first fenced block
+ * it carries (the task's local copy of the contract). Shape:
+ *   { names: string[], block: string|null }
+ * `names` come from a `Contracts: A, B` line; `block` is the first fenced code
+ * block in the task (normalized) used to compare against the canonical defs.
+ */
+function extractTaskContracts(taskText) {
+  const names = [];
+  const nameLine = taskText.match(/^\s*Contracts:\s*([^\n]+)$/im);
+  if (nameLine) {
+    for (const token of nameLine[1].split(',')) {
+      const name = token.trim();
+      if (name) names.push(name);
+    }
+  }
+  const blockMatch = taskText.match(/```[^\n]*\n([\s\S]*?)\n```/);
+  const block = blockMatch ? normalizeBlock(blockMatch[1]) : null;
+  return { names, block };
+}
+
 function validateSpec(specDir) {
   const errors = [];
   const warnings = [];
@@ -141,6 +229,8 @@ function validateSpec(specDir) {
     errors.push('spec.json.scope_lock: must be an object, not a boolean or array');
   }
 
+  validateTimestamps(spec, errors);
+
   const taskFiles = listTaskFiles(specDir);
   const taskFileSet = new Set(taskFiles);
 
@@ -236,11 +326,20 @@ function validateSpec(specDir) {
   }
 
   let requirementIds = [];
+  let subCriteriaIds = [];
   if (fs.existsSync(requirementsPath)) {
-    requirementIds = extractRequirementIds(fs.readFileSync(requirementsPath, 'utf8'));
+    const requirementsText = fs.readFileSync(requirementsPath, 'utf8');
+    requirementIds = extractRequirementIds(requirementsText);
+    subCriteriaIds = extractSubCriteriaIds(requirementsText);
   }
 
   const coveredRequirementIds = new Set();
+  const coveredSubCriteriaIds = new Set();
+  // Cross-layer contract defs (opt-in): empty unless design.md uses
+  // <!-- contract:NAME --> markers, so legacy specs are unaffected.
+  const contractDefs = fs.existsSync(designPath)
+    ? extractContractDefs(fs.readFileSync(designPath, 'utf8'))
+    : new Map();
   for (const taskFile of taskFiles) {
     const fullPath = path.join(specDir, taskFile);
     const content = fs.readFileSync(fullPath, 'utf8');
@@ -256,8 +355,30 @@ function validateSpec(specDir) {
     const numericMappingRe = /_Requirements:\s*([^_\n]+)_/gi;
     while ((match = numericMappingRe.exec(content)) !== null) {
       for (const token of match[1].split(',')) {
-        const number = token.trim().match(/^(\d+)(?:\.\d+)?$/);
-        if (number) coveredRequirementIds.add(`R${number[1]}`);
+        const trimmed = token.trim();
+        const major = trimmed.match(/^(\d+)(?:\.\d+)?$/);
+        if (major) coveredRequirementIds.add(`R${major[1]}`);
+        // Record the full sub-criterion (e.g. 3.4 -> R3.4) for per-criterion coverage.
+        const sub = trimmed.match(/^(\d+\.\d+)$/);
+        if (sub) coveredSubCriteriaIds.add(`R${sub[1]}`);
+      }
+    }
+
+    // Cross-layer contract check (opt-in via design.md markers). When a task
+    // claims `Contracts: NAME`, that name must exist in design.md and the task's
+    // local copy of the block must match the canonical definition byte-for-byte
+    // (after whitespace normalization). This catches BE/FE drift like
+    // user_name vs userName before integration.
+    if (contractDefs.size > 0) {
+      const { names, block } = extractTaskContracts(content);
+      for (const name of names) {
+        if (!contractDefs.has(name)) {
+          errors.push(`${taskFile}: declares unknown contract "${name}" (not defined in design.md)`);
+          continue;
+        }
+        if (block !== null && block !== contractDefs.get(name)) {
+          errors.push(`${taskFile}: contract "${name}" body diverges from the canonical definition in design.md`);
+        }
       }
     }
   }
@@ -268,6 +389,18 @@ function validateSpec(specDir) {
     }
   }
 
+  // Per-criterion coverage: only enforced when requirements.md declares explicit
+  // R{N}.{M} literals AND tasks use the numeric `_Requirements: x.y_` mapping.
+  // If a spec declares sub-criteria but no task maps any at sub-level, that is the
+  // legacy coarse format (major-only) — skip silently to avoid false failures.
+  if (subCriteriaIds.length > 0 && coveredSubCriteriaIds.size > 0) {
+    for (const subId of subCriteriaIds) {
+      if (!coveredSubCriteriaIds.has(subId)) {
+        errors.push(`requirements.md:${subId}: acceptance criterion not covered by any task`);
+      }
+    }
+  }
+
   if (spec.ready_for_implementation === true && errors.length > 0) {
     errors.push('spec.json.ready_for_implementation: cannot be true while validator errors exist');
   }

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

@@ -19,7 +19,7 @@ metadata:
 This skill provides a 10-step workflow to transform ideas into evidence-backed specs:
 
 ```
-Analyze → Dependency Scan → Complexity Assessment → Init → Evidence Gate + Requirements → Design → Tasks → Hydration → Review → Completion
+Analyze → Dependency Scan → Complexity Assessment → Init → Evidence Gate + Requirements → Design → Tasks → Review → Completion
 ```
 
 An entry/dispatch layer sits in front of the pipeline: four flags (`--auto`, `--validate`, `--status`, `--archive`) plus **Interactive State Discovery** (the no-flag path) decide *which part of the pipeline to run and where to stop* — see **Default Behavior**. The pipeline itself is unchanged regardless of how it is invoked.
@@ -90,7 +90,6 @@ Forbidden generated artifacts:
 - Do NOT create `specs/<feature>/hydration.md`.
 - Do NOT create shorthand task files such as `tasks/task-R0-1.md`, `tasks/task-R1-1.md`, or `tasks/R0-1-<slug>.md`.
 - The template file name is never the output file name. `templates/spec-state.json` is only the schema source for generated `spec.json`.
-- Task hydration is session/task-state synchronization only; it MUST NOT be written as a markdown artifact.
 - Before marking a spec ready, run the deterministic validator:
   - `node .claude/scripts/validate-spec-output.cjs specs/<feature>`
   - Any validator failure blocks `ready_for_implementation = true`.
@@ -111,7 +110,7 @@ Forbidden generated artifacts:
 ### Dispatch order
 
 1. `--status` (or bare `status`) → run the status report (see **Subcommands**), then stop.
-2. `--validate <feature>` → jump to **Step 9** (the `--validate` rules below are unchanged).
+2. `--validate <feature>` → jump to **Step 8** (the `--validate` rules below are unchanged).
 3. `--archive` (or bare `archive`) → run the archive workflow, then stop.
 4. `--auto` → **non-interactive run**. If the argument matches an unfinished spec → resume it from `current_phase` and finish to Tasks. Otherwise create new and run the full pipeline (Step 1→10) end-to-end. Either way: auto-approve and skip the Creation Mode question; if a new description is missing, ask only for it; the hard safety gates still apply.
 5. Otherwise (`/hapo:specs` or `/hapo:specs "<description>"`) → **Interactive State Discovery**.
@@ -131,7 +130,7 @@ Goal: ask the user enough to determine **state** and **intent**, then run the ex
    - For non-trivial specs, execute the Step 5 Evidence Gate before writing final requirements. Do not design from memory when codebase or current external evidence can answer the question.
 3. **Creation Mode Gate** (how far to run) — see the dedicated section below. Options: `Auto (→ Tasks)` · `Stop after Design` · `Step by step`. If `.claude/settings.json` → `language` is not English, also offer the **Translation Mirror** (see below).
 4. **Continue an unfinished spec** → read `spec.json.current_phase`, then `AskUserQuestion` offering the **remaining** stop points (e.g. `→ Design`, `→ Tasks`, `Step by step`) and resume the existing pipeline from that phase. If a message accompanied the call, treat it as added context for the next phase (scope expansion → ask, per `references/ask-user-question-gates.md`).
-5. **Run the chosen scope.** On an early stop, emit the Paused Block (Step 10). Sync `spec.json` per `state-sync.md`.
+5. **Run the chosen scope.** On an early stop, emit the Paused Block (Step 9b). Sync `spec.json` per `state-sync.md`.
 
 > The pipeline, validator, templates, and rules are unchanged. "Stop after Design" simply halts before Step 7; it runs Steps 1–6 exactly as specified.
 
@@ -147,7 +146,7 @@ Shown once (via `AskUserQuestion`) on the no-flag create path, after the descrip
 
 Rules:
 - `--auto` equals choosing **Auto (→ Tasks)** without showing this gate.
-- **Stop after Design** / **Step by step** leave `ready_for_implementation=false` and emit the Paused Block (Step 10).
+- **Stop after Design** / **Step by step** leave `ready_for_implementation=false` and emit the Paused Block (Step 9b).
 - Continuing later: run `/hapo:specs` again → Interactive State Discovery detects the unfinished spec and offers the remaining stop points. No flag or keyword required.
 
 ### Translation Mirror (optional reference copy)
@@ -161,7 +160,7 @@ Load `references/translation-mirror.md`. This is the only language feature in th
 
 ### When called WITH `--validate` argument
 
-System IMMEDIATELY jumps to **Step 9: Validation Review**.
+System IMMEDIATELY jumps to **Step 8: Validation Review**.
 The system MUST NOT execute Steps 1-8. Instead, load `references/review.md` and follow it **step-by-step**.
 
 #### `--validate` Guardrails (NON-NEGOTIABLE)
@@ -216,8 +215,7 @@ flowchart TD
     CM -->|"Stop after Design"| STOP["Paused at design → emit Paused Block"]
     CM -->|"Auto / Step by step"| S["Step 7: Tasks — split into individual files"]
     S --> T["Create tasks/task-R*.md + task_registry"]
-    T --> U["Step 8: Hydrate Claude Tasks if >= 3 task files"]
-    U --> V{Review?}
+    T --> V{Review?}
     V -->|Yes| W["Run review — auto-pick red team or validation"]
     V -->|No| X["Update spec.json → DONE"]
     W --> X
@@ -260,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>/`
@@ -288,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).
@@ -310,6 +323,7 @@ Load: `references/scope-inquiry.md`
 - Design decisions MUST trace back to `research.md` evidence. If a design choice lacks evidence and is not a user-approved constraint, gather more evidence or ask the user before finalizing.
 - Add diagrams only when design has multi-step or cross-boundary flows
 - For auth/session, transport/entrypoint, persistence/schema, generated-artifact, or runtime-sensitive work, the design MUST fill the `Canonical Contracts & Invariants` section and tasks MUST inherit the same decisions verbatim.
+- When a data shape must stay byte-identical across layers (e.g. an API response consumed by both a backend task and a frontend task, or a DB row shape), declare it as a **named contract block** — `<!-- contract:NAME -->` followed by a fenced block — per `templates/design.md`. Tasks that produce/consume it add `Contracts: NAME` and copy the block verbatim; the validator then hard-fails on cross-layer drift. Prefer this for any spec spanning BE/FE/DB.
 - Update `spec.json` phase, timestamps, discovery mode
 
 ### Step 7: Task Breakdown
@@ -319,9 +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.
-- Load `rules/tasks-parallel-analysis.md` for parallel markers (default: enabled)
-- 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 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:
+  `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.
+- 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.
@@ -388,14 +404,22 @@ 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.
 
-### Step 8: Task Hydration
-Load: `references/task-hydration.md`
-- Only run if >= 3 task files
-- Convert task files → Claude Tasks with dependency chain (`addBlockedBy`)
-- If TaskCreate tool unavailable → fallback to `TodoWrite`
-- Task files are the single source of truth — hydration is just a convenience
+#### 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 9: Validation Review (Optional)
+### 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.
 - System auto-evaluates spec complexity and decides review depth:
@@ -407,35 +431,31 @@ 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`.
-
-### Step 9.5: Finalization Audit (MANDATORY)
-- Re-scan the `tasks/` directory and rebuild `spec.json.task_files` from the real filesystem (sorted, relative paths)
-- Rebuild `spec.json.task_registry` from the real filesystem if it is missing, stale, or missing keys. Preserve task status fields 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.
-- FAIL if any task file exists on disk but is missing from `task_files`
-- FAIL if any path in `task_files` does not exist on disk
-- FAIL if any task file exists on disk but is missing from `task_registry`
-- FAIL if any path in `task_registry` does not exist on disk
-- FAIL if any task file path does not match `tasks/task-R{N}-{SEQ}-<slug>.md` with two-digit `SEQ` (for example `tasks/task-R0-01-project-scaffolding.md`)
-- FAIL if a newly generated non-trivial spec lacks a `research.md` Evidence Summary with codebase scout result, external research result or skip rationale, selected decision, rejected alternatives, and downstream task/test implications.
-- FAIL if any requirement or NFR mapping uses non-numeric labels (`NFR-1`, `SEC-1`, etc.)
-- FAIL if a task lacks `Completion Criteria` or `Evidence` (existing `Task Test Plan & Verification Evidence` or legacy `Verification & Evidence` is accepted)
-- FAIL if a task creates runtime-facing artifacts but neither proves reachability from an entrypoint/caller nor names a later integration task responsible for wiring them.
-- FAIL if a UI/app/runtime spec has multiple user-facing task outputs but no final integration/reachability task or final integration section.
-- FAIL if accepted validation decisions exist in reports but are not reflected in the implementation-facing sections of affected artifacts (`Context`, `Steps`, `Requirements`, `Completion Criteria`, `Evidence`, canonical contracts, or requirements text).
-- FAIL if any generated task replaces the required task template with a reduced `Objective` / `Steps` / `Evidence` shape. `Context`, `Constraints`, `Related Files`, `Completion Criteria`, `Evidence`, and `Risk Assessment` must all remain present.
-- FAIL if the spec scope/provider was switched away from Anthropic/Claude but `requirements.md`, `design.md`, or `tasks/*.md` still contain stale provider-specific strings such as `Claude API`, `Haiku`, or `haiku_reachable`. `research.md` is the only allowed place for historical cost comparisons.
+- **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).
+- **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).
+- FAIL if the scope/provider switched away from Anthropic/Claude but `requirements.md`, `design.md`, or `tasks/*.md` still contain stale strings such as `Claude API`, `Haiku`, or `haiku_reachable`. `research.md` is the only allowed place for historical comparisons.
 - FAIL if privacy/delete-data work lacks a single canonical deletion policy. The design MUST explicitly choose either:
   1. hard-delete with no re-registration lock, or
   2. privacy-preserving re-registration lock using a non-raw identifier (for example `email_hash` / `email_fingerprint`) with a retention period.
   Tasks and requirements must reuse the same policy verbatim; mixed policies are invalid.
-- FAIL if `validation.status = "completed"` but `timestamps.validation_done` / `timestamps.review_done`, `updated_at`, and report metadata are not synchronized with the final reviewed state.
-- If `validation_recommended = true` and `validation.status` is not `completed` (or an explicit accepted-risk state recorded by the user), `ready_for_implementation` MUST remain `false`
-- If `translation.enabled = true`, ensure `i18n/<language_code>/` exists and was re-synced after the final canonical write; the mirror itself is excluded from validation and never blocks `ready_for_implementation`.
-- Only after this audit passes may the system mark `progress.tasks = "done"` and `ready_for_implementation = true`
+- FAIL if `validation.status = "completed"` but `timestamps.validation_done` / `review_done`, `updated_at`, and report metadata are not synchronized with the final reviewed state.
+- If `validation_recommended = true` and `validation.status` is not `completed` (or an explicit user-accepted risk state), `ready_for_implementation` MUST remain `false`.
+- If `translation.enabled = true`, ensure `i18n/<language_code>/` exists and was re-synced after the final canonical write; the mirror is excluded from validation and never blocks `ready_for_implementation`.
+- Only after this audit passes may the system mark `progress.tasks = "done"` and `ready_for_implementation = true`.
 
-### Step 10: Completion — Context Reminder (MANDATORY)
+### Step 9: Completion — Context Reminder (MANDATORY)
 After completing the spec, output a short summary of what was generated, then you MUST output the following block EXACTLY as written. DO NOT use awkward translations like "Điểm đã phản ánh đúng quyết định của bạn", keep it professional or just output the block directly:
 
 **Command integrity:** The implementation handoff command is always `/hapo:develop <feature>`. Never suggest `/work`, `/code`, or any non-CafeKit alias as the next step for this workflow.
@@ -448,7 +468,7 @@ After completing the spec, output a short summary of what was generated, then yo
 💡 Tip: Run /clear or start a new chat session before implementing to reduce planning context carryover.
 ```
 
-### Step 10b: Paused Block (early stop)
+### Step 9b: Paused Block (early stop)
 
 When the run stops before Tasks (Creation Mode = **Stop after Design** or **Step by step**), do NOT print the completion block above and do NOT run the deterministic validator (no tasks exist yet). Instead print:
 
@@ -583,26 +603,19 @@ The canonical surface is four flags. Bare-verb forms are kept only as silent bac
 - No over-engineering: if a function suffices, don't create a class
 
 ### Pre-Finalization Checklist
-Before finalizing any specification, assert all the following:
-- [ ] **scope_lock** initialized and respected throughout all phases
-- [ ] **Evidence Summary** exists in `research.md` with codebase scout, external research or skip rationale, selected decision, rejected alternatives, and task/test implications
-- [ ] **EARS format** applied to all acceptance criteria in requirements.md
-- [ ] **Numeric requirement IDs** assigned to every requirement
+Before finalizing any specification, assert all the following.
+
+**Machine-enforced** (run `node .claude/scripts/validate-spec-output.cjs specs/<feature>` — it hard-fails on all of these, so do not re-verify by hand): scope_lock object, research.md Evidence Summary, every requirement + sub-criterion covered by a task, each task has Completion Criteria + Evidence + Risk Assessment + the required headings, task_files/task_registry synced to disk with valid dependencies, task naming convention, validation gate vs validation.status, timestamps not reused. A clean validator exit clears this whole group.
+
+**Judgment-only** (validator cannot see these — assert manually):
+- [ ] **EARS format** applied to all acceptance criteria, with measurable thresholds (no "fast"/"safe"/"robust")
 - [ ] **Discovery mode** selected and recorded in spec.json.design_context
 - [ ] **Requirements traceability** matrix present in design.md
-- [ ] **Canonical Contracts & Invariants** filled for auth/transport/persistence/artifact-sensitive work
-- [ ] **Every task file** maps to at least 1 valid in-scope requirement ID
-- [ ] **Every task file** includes `Evidence` with executable or inspectable proof
+- [ ] **Canonical Contracts & Invariants** filled for auth/transport/persistence/artifact-sensitive work, and inherited verbatim by every task that touches the contract
 - [ ] **State Machine Blueprint:** design.md contains Mermaid diagrams for non-trivial flows
-- [ ] **Dependency graph complete**: no task can start before its blockers are listed
-- [ ] **Risk matrix filled**: likelihood × impact, with mitigation for High items
 - [ ] **Test strategy defined**: what gets unit tested, integration tested, e2e validated
-- [ ] **task_files inventory synced**: no missing or orphaned task references
-- [ ] **task_registry synced**: every task file has exactly one machine-state entry with valid status + dependencies
-- [ ] **deterministic validator passed**: `node .claude/scripts/validate-spec-output.cjs specs/<feature>`
-- [ ] **Validation gate consistent**: validation_recommended and validation.status agree with spec risk
 - [ ] **Provider wording clean**: no stale vendor/provider strings outside allowed research context
-- [ ] **spec.json fully updated**: phase, current_phase, progress, timestamps, approvals, design_context
+- [ ] **Validation decisions propagated** into implementation-facing sections, not only reports/Risk Assessment
 
 ## When TO Use
 
@@ -635,8 +648,7 @@ Before finalizing any specification, assert all the following:
 - `design-discovery-light.md` — Lightweight research workflow
 - `design-review.md` — Design review GO/NO-GO process
 - `phase-decision-matrix.md` — Implementation slice/task-cluster boundary rules
-- `tasks-generation.md` — Task generation rules (includes spike task rules)
-- `tasks-parallel-analysis.md` — Parallel task analysis
+- `tasks-generation.md` — Task generation rules (includes spike task rules + parallel analysis)
 - `task-scoring-rubric.md` — Task priority, split/merge, spike, dependency, and evidence-depth scoring
 
 ### References (`references/`)
@@ -645,7 +657,6 @@ Before finalizing any specification, assert all the following:
 - `scope-inquiry.md` — 5-Dimension Complexity Assessment (Semantic, Hypothesis, Gap, Risk/Cynefin, Blast Radius)
 - `research-strategy.md` — Research strategy (7 tools)
 - `codebase-analysis.md` — Codebase analysis (4 mandatory files)
-- `task-hydration.md` — Task files → Claude Tasks conversion
 - `review.md` — Spec review (auto-decides: red team 8 steps + validate 6 steps)
 - `archive-workflow.md` — Archive workflow (5 steps)
 - `translation-mirror.md` — Optional reference-only translation mirror (detection, layout, sync, fields)

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
@@ -212,13 +227,15 @@ Choose verification by task risk and touched surface. Do not force every task to
   - No data dependency on other pending tasks
   - No shared file or resource contention
   - No prerequisite review/approval from another task
+  - Environment/setup work needed by the task is already satisfied or covered within the task itself
 - Validate that identified parallel tasks operate within separate boundaries defined in the Architecture Pattern & Boundary Map.
 - Confirm API/event contracts from design.md do not overlap in ways that cause conflicts.
-- Append `(P)` immediately after the task number for each parallel-capable task:
+- Append `(P)` immediately after the task number for each parallel-capable task, kept **outside** the checkbox brackets:
   - Example: `- [ ] 2.1 (P) Build background worker`
   - Apply to both major tasks and sub-tasks when appropriate.
 - If sequential mode is requested, omit `(P)` markers entirely.
 - Group parallel tasks logically (same parent when possible) and highlight any ordering caveats in detail bullets.
+- Do not mark container-only major tasks (no own actionable bullets) with `(P)` — evaluate parallelism at the sub-task level.
 - Explicitly call out dependencies that prevent `(P)` even when tasks look similar.
 
 ### Checkbox Format

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

@@ -79,6 +79,12 @@ Capture only the contracts whose inconsistency would break downstream implementa
 
 > Task files must reuse the same contract wording. If the feature touches delete-data or privacy retention, explicitly decide whether re-registration is blocked and how that lock works without keeping raw PII. If implementation later needs a different contract, update this section first before generating or editing tasks.
 
+### Machine-checkable contracts (optional, recommended for cross-layer work)
+
+When a data shape must stay identical across layers (e.g. a response consumed by both a backend task and a frontend task), define it as a **named contract block** so the validator can detect drift. Mark it with an HTML comment `<!-- contract:NAME -->` on its own line, immediately followed by a fenced code block holding the shape. For example, a contract named `OrderResponse` would be an HTML marker line followed by a json fenced block containing `{ "orderId": "string", "total": "number" }`.
+
+Any task that produces or consumes this shape adds a `Contracts: OrderResponse` line in its body and **copies the same fenced block verbatim**. `validate-spec-output.cjs` then fails the spec if a task's copy diverges from this canonical definition, or references a contract name not defined here. This is opt-in: specs without `<!-- contract:* -->` markers are unaffected.
+
 ## System Flows
 
 Provide only the diagrams needed to explain non-trivial flows. Use pure Mermaid syntax. Common patterns:

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": {

package/src/claude/skills/specs/references/task-hydration.md

@@ -1,93 +0,0 @@
-# Task Hydration
-
-## Purpose
-
-Convert task files (persistent storage) into Claude Tasks (session-scoped only), enabling real-time progress tracking and automatic unblocking when predecessor tasks complete. `spec.json.task_registry` is the machine-state bridge between markdown task files and session-scoped Claude Tasks.
-
-## When to Run
-
-- **Default:** Auto-run after task files are created
-- **Skip if:** Fewer than 3 task files (overhead not worth it)
-- **User opt-out:** When user explicitly says no task tracking
-
-## Hydrate ↔ Sync-back Diagram
-
-```
-┌──────────────────┐  Hydrate   ┌───────────────────┐
-│ Task Files       │ ─────────► │ Claude Tasks      │
-│ (persistent)     │            │ (session-scoped)  │
-│ [ ] task-R0-01   │            │ ◼ pending         │
-│ [ ] task-R0-02   │            │ ◼ pending         │
-└──────────────────┘            └───────────────────┘
-                                        │ Work
-                                        ▼
-┌──────────────────┐  Sync-back ┌───────────────────┐
-│ Task Files       │ ◄───────── │ Task Updates      │
-│ (updated)        │            │ (completed)       │
-│ [x] task-R0-01   │            │ ✓ completed       │
-│ [ ] task-R0-02   │            │ ◼ in_progress     │
-└──────────────────┘            └───────────────────┘
-```
-
-- **Hydrate:** Read task files → `TaskCreate` for each unchecked `[ ]` item
-- **Work:** `TaskUpdate` tracks in_progress/completed in real-time
-- **Sync-back:** Update `[ ]` → `[x]` in task files, update `spec.json` progress
-
-## Required Metadata for Task Creation
-
-| Field | Description | Example |
-|---|---|---|
-| `taskNumber` | Task sequence number | `R0-02` |
-| `priority` | Priority level | `P1`, `P2`, `P3` |
-| `effort` | Time estimate | `2h` |
-| `specDir` | Spec directory path | `specs/mobile-app/` |
-| `taskFile` | Task file name | `task-R0-02-extension-shell.md` |
-
-## Hydration Workflow
-
-1. Read all `tasks/task-R*.md` files → filter incomplete tasks
-2. Load `spec.json.task_registry` and prefer its task status/dependencies when present
-3. Create `TaskCreate` for each major task, attach `addBlockedBy` per dependency chain:
-   ```
-   Task R0-01 (no blockers) ← start here
-   Task R0-02 (addBlockedBy: [task-R0-01-id])
-   Task R1-01 (addBlockedBy: [task-R0-02-id])
-   ```
-4. Create additional `TaskCreate` for high-risk steps within tasks (if any)
-5. Verify: no dependency cycles, all tasks have complete metadata, and every hydrated task has a corresponding `task_registry` entry
-
-## Fallback
-
-`TaskCreate`/`TaskUpdate`/`TaskGet`/`TaskList` tools are CLI-only. If running in VSCode extension:
-- Use `TodoWrite` as a tracking substitute
-- Task files remain the single source of truth
-- Hydration is an optimization convenience, NOT a requirement
-
-## Cook Handoff Protocol
-
-### Same session (spec → code immediately)
-1. Spec creates tasks + hydrates → tasks exist in session
-2. Code reads `TaskList` → finds existing tasks → picks them up
-3. Skips re-creation, begins implementing directly
-
-### New session (resume)
-1. User runs `/hapo:develop <feature>` in a new session
-2. Code reads `TaskList` → empty (tasks died with old session)
-3. Code reads task files → re-hydrates from `[ ]` items
-4. `[x]` items = done, skip those
-
-### Sync-back (after code completes)
-1. `TaskUpdate` marks tasks as completed
-2. Update `[ ]` → `[x]` in task files
-3. Update `spec.json.task_registry[path].status`, timestamps, blocker, and last_updated_at
-4. Update `spec.json` progress for the corresponding phase
-5. Git commit captures the state transition
-
-## Quality Checks
-
-After hydration, verify:
-- [ ] Dependency chain has no cycles
-- [ ] All task files have corresponding Tasks
-- [ ] Required metadata fields are complete
-- [ ] Task count matches `[ ]` items in files
-- Output: `✓ Hydrated [N] tasks with dependency chain`

package/src/claude/skills/specs/rules/tasks-parallel-analysis.md

@@ -1,34 +0,0 @@
-# Parallel Task Analysis Rules
-
-## Purpose
-Provide a consistent way to identify implementation tasks that can be safely executed in parallel while generating individual task files.
-
-## When to Consider Tasks Parallel
-Only mark a task as parallel-capable when **all** of the following are true:
-
-1. **No data dependency** on pending tasks.
-2. **No conflicting files or shared mutable resources** are touched.
-3. **No prerequisite review/approval** from another task is required beforehand.
-4. **Environment/setup work** needed by this task is already satisfied or covered within the task itself.
-
-## Marking Convention
-- Append `(P)` immediately after the numeric identifier for each qualifying task.
-  - Example: `- [ ] 2.1 (P) Build background worker for emails`
-- Apply `(P)` to both major tasks and sub-tasks when appropriate.
-- If sequential execution is requested (e.g. via `--sequential` flag), omit `(P)` markers entirely.
-- Keep `(P)` **outside** of checkbox brackets to avoid confusion with completion state.
-
-## Grouping & Ordering Guidelines
-- Group parallel tasks under the same parent whenever the work belongs to the same theme.
-- List obvious prerequisites or caveats in the detail bullets (e.g., "Requires schema migration from 1.2").
-- When two tasks look similar but are not parallel-safe, call out the blocking dependency explicitly.
-- Skip marking container-only major tasks (those without their own actionable detail bullets) with `(P)`—evaluate parallel execution at the sub-task level instead.
-
-## Quality Checklist
-Before marking a task with `(P)`, ensure you have:
-
-- Verified that running this task concurrently will not create merge or deployment conflicts.
-- Captured any shared state expectations in the detail bullets.
-- Confirmed that the implementation can be tested independently.
-
-If any check fails, **do not** mark the task with `(P)` and explain the dependency in the task details.