@haposoft/cafekit 0.16.0-rc.7 → 0.16.0

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

@@ -1,184 +1,218 @@
 #!/usr/bin/env node
-/**
- * CafeKit skill catalog scanner.
- *
- * This mirrors the Research/.claude approach: expose the installed skill set as
- * a readable catalog so the model can choose skills from rules, not from an
- * automatic prompt-scoring hook.
- */
+/** Generate a fail-closed catalog from the current runtime's installed skills. */
+
+'use strict';
 
 const fs = require('fs');
 const path = require('path');
 
+// Keep synchronized with migration-manifest.json obsolete.skills. Modified
+// retired directories may remain on disk, but they are never automatic routes.
+const RETIRED_DIRECTORIES = new Set([
+  'backend-development',
+  'frontend-development',
+  'frontend-design',
+  'mobile-development',
+  'devops',
+  'react-best-practices',
+]);
+const PUBLIC_SUFFIX_BY_DIRECTORY = {
+  hotfix: 'fix',
+  inspect: 'scout',
+  question: 'ask',
+};
+
 function usage() {
   console.log(`Usage:
-  node .claude/scripts/generate-skill-catalog.cjs [--skills] [--json] [--root <skills-dir>]
+  node <runtime>/scripts/generate-skill-catalog.cjs [--skills] [--json] [--root <skills-dir>]
 
-Examples:
-  node .claude/scripts/generate-skill-catalog.cjs --skills
-  node .claude/scripts/generate-skill-catalog.cjs --json --root .claude/skills`);
+The default root is bound to the script runtime: .claude/skills for Claude,
+.agents/skills for Codex, and ../skills for the source tree.`);
 }
 
 function parseArgs(argv) {
   const args = { json: false, help: false, root: null };
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
     if (arg === '--help' || arg === '-h') args.help = true;
     else if (arg === '--json') args.json = true;
     else if (arg === '--skills') continue;
     else if (arg === '--root') {
-      args.root = argv[i + 1] || null;
-      i += 1;
-    } else {
-      args.root = args.root || arg;
-    }
+      if (!argv[index + 1] || argv[index + 1].startsWith('--')) {
+        throw new Error('--root requires a skills directory');
+      }
+      args.root = argv[++index];
+    } else throw new Error(`unknown option: ${arg}`);
   }
   return args;
 }
 
 function defaultSkillsRoot() {
-  const candidates = [
-    path.resolve(__dirname, '..', 'skills'),
-    path.resolve(process.cwd(), '.claude', 'skills'),
-    path.resolve(process.cwd(), '.agents', 'skills'),
-    path.resolve(__dirname, '..', '..', '.agents', 'skills')
-  ];
-  return candidates.find((candidate) => fs.existsSync(candidate)) || candidates[0];
-}
-
-function readText(filePath) {
-  return fs.readFileSync(filePath, 'utf8');
+  const runtimeRoot = path.dirname(__dirname);
+  const runtimeName = path.basename(runtimeRoot);
+  if (runtimeName === '.codex') return path.join(path.dirname(runtimeRoot), '.agents', 'skills');
+  const claudeRuntimeName = `.${['cla', 'ude'].join('')}`;
+  if (runtimeName === claudeRuntimeName) return path.join(runtimeRoot, 'skills');
+  return path.resolve(__dirname, '..', 'skills');
 }
 
 function extractFrontmatter(content) {
-  const match = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n/);
-  if (!match) return {};
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!match) return null;
   const frontmatter = {};
   const lines = match[1].split(/\r?\n/);
-  for (let i = 0; i < lines.length; i += 1) {
-    const line = lines[i];
-    const kv = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
-    if (!kv) continue;
-    const key = kv[1];
-    let value = kv[2].trim();
-    if (value === '>' || value === '>-' || value === '|' || value === '|-') {
+  const seen = new Set();
+  let nestedKey = null;
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (line.trim() === '') continue;
+    if (/^\s+/.test(line)) {
+      const nested = line.match(/^  ([A-Za-z0-9_-]+):\s*(\S.*)$/);
+      if (!nestedKey || !nested) return null;
+      const identity = `${nestedKey}.${nested[1]}`;
+      if (seen.has(identity) || quotedValue(nested[2]) === null) return null;
+      seen.add(identity);
+      continue;
+    }
+    nestedKey = null;
+    const parsed = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!parsed || seen.has(parsed[1])) return null;
+    seen.add(parsed[1]);
+    let value = parsed[2].trim();
+    if (['>', '>-', '|', '|-'].includes(value)) {
       const block = [];
-      i += 1;
-      while (i < lines.length && /^\s+/.test(lines[i])) {
-        block.push(lines[i].trim());
-        i += 1;
+      while (index + 1 < lines.length && /^\s+/.test(lines[index + 1])) {
+        block.push(lines[++index].trim());
       }
-      i -= 1;
+      if (block.length === 0) return null;
       value = block.join(' ');
     }
-    if (
-      (value.startsWith('"') && value.endsWith('"')) ||
-      (value.startsWith("'") && value.endsWith("'"))
-    ) {
-      value = value.slice(1, -1);
+    if (value === '') {
+      nestedKey = parsed[1];
+      frontmatter[parsed[1]] = '';
+      continue;
     }
-    frontmatter[key] = value;
+    value = quotedValue(value);
+    if (value === null) return null;
+    frontmatter[parsed[1]] = value;
   }
   return frontmatter;
 }
 
-function firstParagraph(content) {
-  const body = content.replace(/^---\s*\n[\s\S]*?\n---\s*\n/, '');
-  const paragraph = [];
-  for (const rawLine of body.split(/\r?\n/)) {
-    const line = rawLine.trim();
-    if (!line || line.startsWith('#')) {
-      if (paragraph.length > 0) break;
-      continue;
-    }
-    paragraph.push(line);
-    if (paragraph.join(' ').length > 160) break;
+function quotedValue(value) {
+  const startsQuote = value.startsWith('"') || value.startsWith("'");
+  const endsQuote = value.endsWith('"') || value.endsWith("'");
+  const startsFlow = value.startsWith('[') || value.startsWith('{');
+  const endsFlow = value.endsWith(']') || value.endsWith('}');
+  if (startsFlow || endsFlow) {
+    const expected = value.startsWith('[') ? ']' : value.startsWith('{') ? '}' : null;
+    if (!expected || !value.endsWith(expected)) return null;
   }
-  return paragraph.join(' ').slice(0, 360);
+  if (!startsQuote && !endsQuote) return value;
+  if (value.length < 2 || value[0] !== value[value.length - 1]) return null;
+  return value.slice(1, -1);
 }
 
-function categorize(name, description) {
-  const text = `${name} ${description}`.toLowerCase();
-  if (/spec|brainstorm|develop|sync/.test(text)) return 'workflow';
-  if (/debug|hotfix|inspect|impact|review|test|agent-browser|chrome/.test(text)) return 'quality';
-  if (/frontend|react|ui|ux|mobile/.test(text)) return 'frontend-mobile';
-  if (/pdf|docx|pptx|xlsx|multimodal/.test(text)) return 'artifacts-tools';
-  if (/backend|devops|api|database|deploy/.test(text)) return 'backend-infra';
-  if (/docs|research|graph/.test(text)) return 'knowledge';
-  if (/git/.test(text)) return 'git';
-  return 'other';
+function parseKeywords(value) {
+  if (!value || !/^\[[^\]]*\]$/.test(value)) return [];
+  return value.slice(1, -1).split(',').map((item) => item.trim()).filter(Boolean);
 }
 
-function scanSkills(root) {
-  if (!fs.existsSync(root)) {
-    throw new Error(`skills root not found: ${root}`);
-  }
-  const entries = fs.readdirSync(root, { withFileTypes: true });
-  const skills = [];
+function publicIdentity(name) {
+  const match = String(name).match(/^cf(?::|-)([a-z0-9]+(?:-[a-z0-9]+)*)$/);
+  return match ? `cf:${match[1]}` : null;
+}
+
+function expectedIdentity(directory) {
+  return `cf:${PUBLIC_SUFFIX_BY_DIRECTORY[directory] || directory}`;
+}
+
+function diagnostic(code, directory, message) {
+  return { code, directory, message };
+}
+
+function scanSkills(requestedRoot) {
+  if (!fs.existsSync(requestedRoot)) throw new Error(`skills root not found: ${requestedRoot}`);
+  const root = fs.realpathSync(requestedRoot);
+  const diagnostics = [];
+  const candidates = [];
+  const entries = fs.readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
+    .sort((left, right) => left.name.localeCompare(right.name));
+
   for (const entry of entries) {
-    if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
     const skillPath = path.join(root, entry.name, 'SKILL.md');
     if (!fs.existsSync(skillPath)) continue;
-    const content = readText(skillPath);
-    const frontmatter = extractFrontmatter(content);
-    const name = frontmatter.name || entry.name;
-    const description = frontmatter.description || firstParagraph(content);
-    skills.push({
-      name,
+    if (RETIRED_DIRECTORIES.has(entry.name)) {
+      diagnostics.push(diagnostic('retired_skill', entry.name, 'excluded from automatic routing'));
+      continue;
+    }
+    const frontmatter = extractFrontmatter(fs.readFileSync(skillPath, 'utf8'));
+    if (!frontmatter) {
+      diagnostics.push(diagnostic('malformed_frontmatter', entry.name, 'missing frontmatter block'));
+      continue;
+    }
+    const identity = publicIdentity(frontmatter.name);
+    if (!identity || !frontmatter.description || frontmatter.description.trim() === '') {
+      diagnostics.push(diagnostic('missing_routing_metadata', entry.name, 'requires valid name and description'));
+      continue;
+    }
+    if (identity !== expectedIdentity(entry.name)) {
+      diagnostics.push(diagnostic('folder_name_mismatch', entry.name, `${identity} does not match directory`));
+      continue;
+    }
+    candidates.push({
+      name: frontmatter.name,
+      public_id: identity,
       directory: entry.name,
-      description,
-      category: categorize(name, description),
+      description: frontmatter.description,
+      when_to_use: frontmatter.when_to_use || '',
+      category: frontmatter.category || 'other',
+      keywords: parseKeywords(frontmatter.keywords),
+      user_invocable: frontmatter['user-invocable'] !== 'false',
       has_references: fs.existsSync(path.join(root, entry.name, 'references')),
       has_scripts: fs.existsSync(path.join(root, entry.name, 'scripts')),
     });
   }
-  return skills.sort((a, b) => a.name.localeCompare(b.name));
+
+  const counts = new Map();
+  for (const skill of candidates) counts.set(skill.public_id, (counts.get(skill.public_id) || 0) + 1);
+  const skills = candidates.filter((skill) => {
+    if (counts.get(skill.public_id) === 1) return true;
+    diagnostics.push(diagnostic('duplicate_public_name', skill.directory, `${skill.public_id} requires explicit user disambiguation`));
+    return false;
+  }).sort((left, right) => left.public_id.localeCompare(right.public_id));
+
+  return { root, skills, diagnostics: diagnostics.sort((left, right) =>
+    `${left.directory}:${left.code}`.localeCompare(`${right.directory}:${right.code}`)) };
 }
 
-function renderMarkdown(skills, root) {
-  const lines = [
-    '# CafeKit Skills Catalog',
-    '',
-    `Skills root: \`${root}\``,
-    `Total skills: ${skills.length}`,
-    '',
-  ];
-  const categories = [...new Set(skills.map((skill) => skill.category))].sort();
-  for (const category of categories) {
-    lines.push(`## ${category}`, '');
-    for (const skill of skills.filter((item) => item.category === category)) {
-      const badges = [
-        skill.has_references ? 'refs' : null,
-        skill.has_scripts ? 'scripts' : null,
-      ].filter(Boolean);
-      lines.push(
-        `- \`${skill.name}\` (${skill.directory})${badges.length ? ` [${badges.join(', ')}]` : ''}: ${skill.description}`
-      );
-    }
-    lines.push('');
+function renderMarkdown(catalog) {
+  const lines = ['# CafeKit Skills Catalog', '', `Skills root: \`${catalog.root}\``,
+    `Routable skills: ${catalog.skills.length}`, ''];
+  for (const skill of catalog.skills) {
+    const intent = skill.when_to_use ? ` Use: ${skill.when_to_use}` : '';
+    lines.push(`- \`${skill.name}\` (${skill.directory}, ${skill.category}): ${skill.description}${intent}`);
   }
-  return lines.join('\n').trim() + '\n';
+  if (catalog.diagnostics.length > 0) {
+    lines.push('', '## Diagnostics', '');
+    for (const item of catalog.diagnostics) lines.push(`- ${item.code} (${item.directory}): ${item.message}`);
+  }
+  return `${lines.join('\n').trim()}\n`;
 }
 
 function main() {
   const args = parseArgs(process.argv.slice(2));
-  if (args.help) {
-    usage();
-    return;
-  }
-
-  const root = path.resolve(process.cwd(), args.root || defaultSkillsRoot());
-  const skills = scanSkills(root);
-  if (args.json) {
-    console.log(JSON.stringify({ root, total: skills.length, skills }, null, 2));
-    return;
-  }
-  console.log(renderMarkdown(skills, root));
+  if (args.help) return usage();
+  const requestedRoot = path.resolve(process.cwd(), args.root || defaultSkillsRoot());
+  const catalog = scanSkills(requestedRoot);
+  if (args.json) console.log(JSON.stringify({ ...catalog, total: catalog.skills.length }, null, 2));
+  else console.log(renderMarkdown(catalog));
 }
 
 try {
   main();
 } catch (error) {
   console.error(`[skill-catalog] ${error.message}`);
-  process.exit(1);
+  process.exitCode = 1;
 }

package/src/claude/scripts/provenance.cjs

@@ -83,9 +83,22 @@ function oneLine(value, label) {
   return output.replace(/\n$/, '');
 }
 
-function gitBase(root) {
-  const output = oneLine(runGit(root, ['rev-parse', 'HEAD'], 'git rev-parse HEAD')).toLowerCase();
-  if (!/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/.test(output)) fail('malformed_git_output', 'git rev-parse HEAD did not return a commit id');
+function gitBase(root, specsRoot) {
+  const specsRelative = path.relative(root, specsRoot).split(path.sep).join('/');
+  const sourceHistory = decode(runGit(
+    root,
+    ['log', '-1', '--format=%H', '--', '.', `:(exclude,literal)${specsRelative}`],
+    'git log source base',
+  )).trim();
+  const roots = sourceHistory ? [] : decode(
+    runGit(root, ['rev-list', '--max-parents=0', '--reverse', 'HEAD'], 'git rev-list root'),
+    'git rev-list root',
+  ).trim().split('\n');
+  if (!sourceHistory && (roots.length === 0 || roots.some((rootId) => !/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/i.test(rootId)))) {
+    fail('malformed_git_output', 'git rev-list root did not return commit ids');
+  }
+  const output = (sourceHistory || roots[0]).toLowerCase();
+  if (!/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/.test(output)) fail('malformed_git_output', 'git source base did not return a commit id');
   return output;
 }
 
@@ -211,11 +224,11 @@ function identity(input) {
 
 function deriveRuntimeProvenance(input) {
   const current = identity(input);
-  const base = gitBase(current.root);
+  const base = gitBase(current.root, current.specsRoot);
   const first = manifest(current.root, current.specsRoot);
   const head = manifestDigest(first);
   const second = manifest(current.root, current.specsRoot);
-  if (JSON.stringify(first) !== JSON.stringify(second) || gitBase(current.root) !== base) fail('worktree_race', 'checkout changed during provenance capture');
+  if (JSON.stringify(first) !== JSON.stringify(second) || gitBase(current.root, current.specsRoot) !== base) fail('worktree_race', 'checkout changed during provenance capture');
   const stable = {
     schema_version: CONTEXT_SCHEMA_VERSION,
     project_root: current.root,

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

@@ -3,6 +3,7 @@
 const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
+const { annotatedMarkdownLines } = require('./spec-resolver.cjs');
 
 const EVIDENCE_HEADINGS = new Set([
   'Evidence',
@@ -67,21 +68,46 @@ function evidenceBody(text, policy = {}) {
 }
 
 function workflowReceiptBody(text, policy = {}) {
-  const lines = String(text || '').split('\n');
+  const lines = annotatedMarkdownLines(text);
   const starts = [];
   for (let index = 0; index < lines.length; index += 1) {
-    if (/^##\s+Receipt\s*$/.test(lines[index])) starts.push(index + 1);
+    if (lines[index].outsideFence && /^##\s+Receipt\s*$/.test(lines[index].line)) starts.push(index + 1);
   }
   if (starts.length !== 1) return null;
 
   const start = starts[0];
   let end = lines.length;
   for (let index = start; index < lines.length; index += 1) {
-    const heading = lines[index].match(/^(#{1,6})\s+/);
-    const tap = typeof policy.isTapMetadataHeading === 'function' && policy.isTapMetadataHeading(lines[index]);
+    if (!lines[index].outsideFence) continue;
+    const heading = lines[index].line.match(/^(#{1,6})\s+/);
+    const tap = typeof policy.isTapMetadataHeading === 'function' && policy.isTapMetadataHeading(lines[index].line);
     if (heading && heading[1].length <= 2 && !tap) { end = index; break; }
   }
-  return lines.slice(start, end).join('\n');
+  return lines.slice(start, end).map(({ line }) => line).join('\n');
+}
+
+function workflowCanonicalValidationBody(body) {
+  return annotatedMarkdownLines(body)
+    .filter(({ outsideFence }) => outsideFence)
+    .map(({ line }) => line)
+    .join('\n');
+}
+
+function hasNonEmptyFencedBlock(body) {
+  let open = false;
+  let nonEmpty = false;
+  for (const { line, fenceEvent } of annotatedMarkdownLines(body)) {
+    if (fenceEvent === 'open') {
+      open = true;
+      nonEmpty = false;
+    } else if (fenceEvent === 'close') {
+      if (open && nonEmpty) return true;
+      open = false;
+    } else if (open && line.trim() !== '') {
+      nonEmpty = true;
+    }
+  }
+  return false;
 }
 
 function fieldValues(body, name) {
@@ -105,22 +131,14 @@ function normalizedCommand(value) {
 function workflowVerificationCommand(taskText) {
   const sections = [];
   let current = null;
-  let fence = null;
-  for (const line of String(taskText || '').split('\n')) {
-    const marker = line.match(/^\s{0,3}(`{3,}|~{3,})/);
-    if (marker) {
-      const kind = marker[1][0];
-      if (fence === null) fence = kind;
-      else if (fence === kind) fence = null;
-      continue;
-    }
-    if (fence !== null) continue;
-    if (fence === null && /^##\s+Verification Plan\s*$/.test(line)) {
+  for (const { line, outsideFence } of annotatedMarkdownLines(taskText)) {
+    if (!outsideFence) continue;
+    if (/^##\s+Verification Plan\s*$/.test(line)) {
       current = [];
       sections.push(current);
       continue;
     }
-    if (fence === null && current && /^#{1,2}\s+/.test(line)) {
+    if (current && /^#{1,2}\s+/.test(line)) {
       current = null;
       continue;
     }
@@ -227,7 +245,10 @@ function checkWorkflowTaskReceipt(featureDir, taskPath, runtimeContext, policy)
   }
 
   const taskText = taskFile.bytes.toString('utf8');
-  const statusLines = [...taskText.matchAll(/^\s*(?:\*\*)?Status(?:\*\*)?\s*:\s*(?:\*\*)?\s*([A-Za-z_-]+)(?:\*\*)?\s*$/gim)];
+  const statusLines = annotatedMarkdownLines(taskText)
+    .filter(({ outsideFence }) => outsideFence)
+    .map(({ line }) => line.match(/^\s*(?:\*\*)?Status(?:\*\*)?\s*:\s*(?:\*\*)?\s*([A-Za-z_-]+)(?:\*\*)?\s*$/i))
+    .filter(Boolean);
   const body = workflowReceiptBody(taskText, policy);
   const failures = [];
   if (statusLines.length !== 1 || statusLines[0][1].toLowerCase().replaceAll('-', '_') !== 'done') {
@@ -236,12 +257,15 @@ function checkWorkflowTaskReceipt(featureDir, taskPath, runtimeContext, policy)
   if (body === null) {
     failures.push('missing_receipt');
   } else {
+    const canonicalBody = workflowCanonicalValidationBody(body);
     const options = typeof policy?.receiptValidatorOptions === 'function'
       ? policy.receiptValidatorOptions({}, { runtimeContext, requireProvenanceBinding: true })
       : { requireProvenanceBinding: true };
-    failures.push(...canonicalFailures(body, {}, runtimeContext, policy));
-    failures.push(...workflowCommandFailures(taskText, body));
-    if (!/```[^\n]*\n[\s\S]*?\S[\s\S]*?\n```/m.test(body)) failures.push('command_output');
+    failures.push(...canonicalFailures(canonicalBody, {}, runtimeContext, policy));
+    failures.push(...canonicalFailures(body, {}, runtimeContext, policy)
+      .filter((failure) => ['placeholder', 'verification_state', 'exit_result'].includes(failure)));
+    failures.push(...workflowCommandFailures(taskText, canonicalBody));
+    if (!hasNonEmptyFencedBlock(body)) failures.push('command_output');
     if (!options.expectedProvenance) failures.push('provenance');
   }
   return {
@@ -256,6 +280,36 @@ function checkWorkflowTaskReceipt(featureDir, taskPath, runtimeContext, policy)
   };
 }
 
+function workflowProofSignature(taskPath, proof) {
+  const hash = crypto.createHash('sha256');
+  hash.update('cafekit-workflow-proof-v1\0');
+  hash.update(String(taskPath));
+  hash.update('\0');
+  hash.update(proof.taskFile?.bytes || Buffer.alloc(0));
+  hash.update('\0');
+  hash.update(proof.receiptBytes || Buffer.alloc(0));
+  hash.update('\0');
+  hash.update(String(proof.status || 'unknown'));
+  return hash.digest('hex');
+}
+
+function workflowDependencyProofState(featureDir, taskRegistry, runtimeContext, policy) {
+  const tasks = {};
+  for (const taskPath of Object.keys(taskRegistry || {}).sort()) {
+    const done = taskRegistry[taskPath]?.status === 'done';
+    const proof = checkWorkflowTaskReceipt(featureDir, taskPath, runtimeContext, policy);
+    const valid = proof.failures.length === 0;
+    tasks[taskPath] = {
+      done,
+      valid,
+      eligible: done && valid,
+      signature: workflowProofSignature(taskPath, proof),
+      failures: [...proof.failures],
+    };
+  }
+  return tasks;
+}
+
 function checkWorkflowReceiptSet(candidates, projectRoot, runtimeSession, policy) {
   const failures = [];
   for (const candidate of Array.isArray(candidates) ? candidates : []) {
@@ -298,5 +352,6 @@ module.exports = {
   evidenceBody,
   readTaskProof,
   safeRead,
+  workflowDependencyProofState,
   workflowReceiptBody,
 };