pan-wizard 3.12.5 → 3.14.0

package/pan-wizard-core/bin/lib/learn-index.cjs

@@ -69,6 +69,23 @@ const RELEVANCE = {
   'test-patterns':        { planner: 'medium', executor: 'high',   verifier: 'high',   reviewer: 'high' },
   'test-strategy':        { planner: 'high',   executor: 'medium', verifier: 'high',   reviewer: 'high' },
 
+  // Field-harvest 2026-07 (docs/FIELD-HARVEST-2026-07.md)
+  'live-path-honesty':    { planner: 'medium', executor: 'high',   verifier: 'high',   reviewer: 'high' },
+  'test-integrity':       { planner: 'medium', executor: 'high',   verifier: 'high',   reviewer: 'high' },
+  'adversarial-verification': { planner: 'medium', executor: 'low', verifier: 'high',  reviewer: 'high' },
+  'integration-verification': { planner: 'high', executor: 'low',  verifier: 'high',   reviewer: 'medium' },
+  'single-source-of-truth': { planner: 'high', executor: 'high',   verifier: 'medium', reviewer: 'high' },
+  'migration-safety':     { planner: 'high',   executor: 'high',   verifier: 'medium', reviewer: 'high' },
+  'flaky-triage':         { planner: 'low',    executor: 'medium', verifier: 'high',   reviewer: 'medium' },
+  'external-tool-truth':  { planner: 'low',    executor: 'high',   verifier: 'high',   reviewer: 'low' },
+  'golden-sets':          { planner: 'high',   executor: 'medium', verifier: 'high',   reviewer: 'medium' },
+  'harness-isolation':    { planner: 'high',   executor: 'medium', verifier: 'low',    reviewer: 'low' },
+  'workaround-catalog':   { planner: 'low',    executor: 'high',   verifier: 'medium', reviewer: 'low' },
+  'service-security':     { planner: 'medium', executor: 'high',   verifier: 'high',   reviewer: 'high' },
+  'mcp-security':         { planner: 'medium', executor: 'medium', verifier: 'medium', reviewer: 'high' },
+  'audit-convergence':    { planner: 'high',   executor: 'low',    verifier: 'high',   reviewer: 'high' },
+  'fix-campaigns':        { planner: 'high',   executor: 'medium', verifier: 'high',   reviewer: 'high' },
+
   // PAN-internal (loaded only by PAN's own dev sessions)
   'experiment-runner':    { planner: 'low',    executor: 'low',    verifier: 'low',    reviewer: 'low' },
   'external-research':    { planner: 'medium', executor: 'low',    verifier: 'low',    reviewer: 'medium' },

package/pan-wizard-core/bin/lib/memory.cjs

@@ -22,7 +22,7 @@
 const fs = require('fs');
 const path = require('path');
 const { output, error } = require('./core.cjs');
-const { PLANNING_DIR } = require('./constants.cjs');
+const { PLANNING_DIR, CHARS_PER_TOKEN, MEMORY_SELECT_BUDGET_TOKENS, MEMORY_RECENCY_FLOOR, MEMORY_SOFT_CAP_MULT, MEMORY_LOAD_WARN_TOKENS, MEMORY_LOAD_CRIT_TOKENS, MEMORY_LOAD_MAX_FRACTION } = require('./constants.cjs');
 const { planningPath } = require('./utils.cjs');
 
 const MEMORY_DIR = 'memory';
@@ -137,8 +137,18 @@ function appendMemory(cwd, agent, entry) {
     return { error: `Failed to write memory file: ${e.message}` };
   }
 
-  const count = parseEntries(contents).length;
-  return { appended: true, file, count };
+  let count = parseEntries(contents).length;
+  // Soft auto-compaction (ADR-0036): only above a HIGH soft cap (2× the manual
+  // cap) so it never silently drops entries a user expects to survive; trims to
+  // DEFAULT_MAX_ENTRIES and surfaces the result — never fully silent.
+  let auto_compacted;
+  if (count >= DEFAULT_MAX_ENTRIES * MEMORY_SOFT_CAP_MULT) {
+    const c = compactMemory(cwd, agent, DEFAULT_MAX_ENTRIES);
+    if (c && c.compacted) { auto_compacted = { kept: c.kept, removed: c.removed }; count = c.kept; }
+  }
+  return auto_compacted
+    ? { appended: true, file, count, auto_compacted }
+    : { appended: true, file, count };
 }
 
 function buildHeader(agent) {
@@ -211,6 +221,125 @@ function listMemoryAgents(cwd) {
   return { agents };
 }
 
+// ─── Cue + recency scoped, token-budgeted read (ADR-0036 FW-2) ───────────────
+
+/** Tokenize a cue into lowercase words of length >= 3. */
+function cueTokens(cue) {
+  return (typeof cue === 'string' ? cue.toLowerCase() : '').match(/[a-z0-9]{3,}/g) || [];
+}
+
+/** Whole-word keyword-frequency score of an entry against cue tokens. */
+function scoreEntry(entry, tokens) {
+  if (!tokens || !tokens.length) return 0;
+  const lc = entry.toLowerCase();
+  let s = 0;
+  for (const t of tokens) {
+    const re = new RegExp(`\\b${t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'g');
+    s += (lc.match(re) || []).length;
+  }
+  return s;
+}
+
+function estMemoryTokens(str) {
+  return Math.max(1, Math.ceil((str || '').length / CHARS_PER_TOKEN));
+}
+
+/**
+ * Select a cue-relevant, recency-floored, token-budgeted slice of an agent's
+ * memory instead of the whole log (ADR-0036 FW-2) — distill-and-select on the
+ * memory axis, so per-agent memory injection can't flood context.
+ *
+ * Always keeps the newest `recencyFloor` entries (recall never returns empty on
+ * a non-empty log); fills the remaining budget by cue relevance, falling back to
+ * recency-only when the cue is empty or matches nothing; greedily packs under
+ * `tokenBudget`. Output is in stored (chronological) order.
+ *
+ * @param {string} cwd
+ * @param {string} agent
+ * @param {{cue?: string, tokenBudget?: number, recencyFloor?: number}} [opts]
+ * @returns {{agent, cue, selected: string[], total_tokens, considered, dropped, mode}|{error}}
+ */
+function selectMemory(cwd, agent, opts = {}) {
+  const err = validateAgentName(agent);
+  if (err) return { error: err };
+  const mem = readMemory(cwd, agent);
+  if (!mem || mem.entries.length === 0) {
+    return { agent, cue: opts.cue || '', selected: [], total_tokens: 0, considered: 0, dropped: 0, mode: 'empty' };
+  }
+  const all = mem.entries; // oldest -> newest
+  const bN = Number(opts.tokenBudget);
+  const budget = Number.isFinite(bN) && bN > 0 ? bN : MEMORY_SELECT_BUDGET_TOKENS;
+  const fN = Number(opts.recencyFloor);
+  const recencyFloor = Number.isFinite(fN) && fN >= 0 ? fN : MEMORY_RECENCY_FLOOR;
+  const tokens = cueTokens(opts.cue);
+
+  const floorFrom = Math.max(0, all.length - recencyFloor);
+  const scored = all.map((text, i) => ({
+    text, i, tokens: estMemoryTokens(text),
+    score: i >= floorFrom ? Infinity : scoreEntry(text, tokens),
+  }));
+  const anyCueHit = scored.some(e => Number.isFinite(e.score) && e.score > 0);
+  // Priority: recency-floor first (Infinity), then cue score, then newest.
+  scored.sort((a, b) => b.score - a.score || b.i - a.i);
+
+  const chosen = [];
+  let total = 0, dropped = 0;
+  for (const e of scored) {
+    if (total + e.tokens > budget) { dropped++; continue; }
+    chosen.push(e); total += e.tokens;
+  }
+  // Guarantee non-empty on a non-empty log even if budget < the smallest entry.
+  if (chosen.length === 0) {
+    const newest = scored.reduce((a, b) => (b.i > a.i ? b : a));
+    chosen.push(newest); total += newest.tokens; dropped = Math.max(0, dropped - 1);
+  }
+  chosen.sort((a, b) => a.i - b.i); // chronological for output
+  const mode = tokens.length === 0 ? 'recency' : (anyCueHit ? 'cue' : 'recency');
+  return { agent, cue: opts.cue || '', selected: chosen.map(e => e.text), total_tokens: total, considered: all.length, dropped, mode };
+}
+
+/**
+ * Memory-load telemetry gate (ADR-0036 acceptance signal). Estimates the tokens
+ * of memory that would be injected whole (every agent log) and compares to the
+ * median per-agent input from the trustworthy cost ledger (suspect records
+ * quarantined). Read-only, non-blocking; degrades to an absolute-token check
+ * when the ledger is thin.
+ *
+ * @returns {{memory_tokens, agents, median_input_tokens, fraction, status, advisory}}
+ */
+function memoryLoadBudget(cwd, opts = {}) {
+  const { agents } = listMemoryAgents(cwd);
+  let memoryTokens = 0;
+  for (const a of agents) {
+    const mem = readMemory(cwd, a.agent);
+    if (mem) memoryTokens += estMemoryTokens(mem.raw);
+  }
+  let median = null;
+  try {
+    const cost = require('./cost.cjs');
+    const inputs = (cost.readRecords(cwd) || [])
+      .filter(r => !cost.isSuspectRecord(r))
+      .map(r => Number(r.input_tokens) || 0)
+      .filter(n => n > 0)
+      .sort((a, b) => a - b);
+    if (inputs.length) median = inputs[Math.floor(inputs.length / 2)];
+  } catch { /* thin/absent ledger — absolute-token check only */ }
+
+  const fraction = median ? memoryTokens / median : null;
+  const warnT = opts.warnTokens || MEMORY_LOAD_WARN_TOKENS;
+  const critT = opts.critTokens || MEMORY_LOAD_CRIT_TOKENS;
+  const maxFrac = opts.maxFraction || MEMORY_LOAD_MAX_FRACTION;
+  let status = 'ok';
+  if (memoryTokens >= critT || (fraction != null && fraction >= maxFrac * 2)) status = 'critical';
+  else if (memoryTokens >= warnT || (fraction != null && fraction >= maxFrac)) status = 'warning';
+  const advisory = status === 'ok'
+    ? 'Memory-load within budget.'
+    : `Memory injection is ~${memoryTokens} tokens across ${agents.length} agent log(s)` +
+      (fraction != null ? ` (~${Math.round(fraction * 100)}% of median agent input)` : '') +
+      `. Bound it with cue-scoped 'memory select' or trim with 'memory compact <agent>'.`;
+  return { memory_tokens: memoryTokens, agents: agents.length, median_input_tokens: median, fraction, status, advisory };
+}
+
 // ─── CLI command wrappers ────────────────────────────────────────────────────
 
 function cmdMemoryRead(cwd, agent, raw) {
@@ -236,17 +365,31 @@ function cmdMemoryCompact(cwd, agent, maxEntries, raw) {
   output(result, raw);
 }
 
+function cmdMemorySelect(cwd, agent, opts, raw) {
+  if (!agent) { error('Usage: memory select <agent> [--cue <text>] [--token-budget N] [--recency-floor N]'); }
+  output(selectMemory(cwd, agent, opts || {}), raw);
+}
+
+function cmdMemoryBudget(cwd, raw) {
+  output(memoryLoadBudget(cwd), raw);
+}
+
 module.exports = {
   readMemory,
   appendMemory,
   compactMemory,
   listMemoryAgents,
+  selectMemory,
+  memoryLoadBudget,
+  scoreEntry,
   parseEntries,
   validateAgentName,
   cmdMemoryRead,
   cmdMemoryAppend,
   cmdMemoryList,
   cmdMemoryCompact,
+  cmdMemorySelect,
+  cmdMemoryBudget,
   MEMORY_DIR,
   DEFAULT_MAX_ENTRIES,
 };

package/pan-wizard-core/bin/lib/optimize.cjs

@@ -8,7 +8,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { output } = require('./core.cjs');
+const { output, escapeRegex } = require('./core.cjs');
 const { PLANNING_DIR } = require('./constants.cjs');
 
 // ─── Storage layout ──────────────────────────────────────────────────────────
@@ -1052,7 +1052,7 @@ function unpromotePattern(patternId, opts) {
   // Strip the pattern's body section. Pattern body is a `## P-<id> — ...` heading
   // followed by content until the next `## ` or end-of-file.
   const headingRe = new RegExp(
-    `\\n## ${patternId.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')}\\b[^\\n]*[\\s\\S]*?(?=\\n## |$)`,
+    `\\n## ${escapeRegex(patternId)}\\b[^\\n]*[\\s\\S]*?(?=\\n## |$)`,
     ''
   );
   const newBody = parsed.body.replace(headingRe, '');

package/pan-wizard-core/bin/lib/phase-remove.cjs

@@ -47,7 +47,7 @@ function renumberDecimalPhases(phasesDir, baseInt, removedDecimal) {
     const dirs = entries.filter(entry => entry.isDirectory()).map(entry => entry.name).sort((left, right) => comparePhaseNum(left, right));
 
     // Find sibling decimals with higher numbers than the removed one
-    const decPattern = new RegExp(`^${baseInt}\\.(\\d+)-(.+)$`);
+    const decPattern = new RegExp(`^${escapeRegex(String(baseInt))}\\.(\\d+)-(.+)$`);
     const toRename = [];
     for (const dir of dirs) {
       const decMatch = dir.match(decPattern);

package/pan-wizard-core/bin/lib/phase.cjs

@@ -133,7 +133,7 @@ function cmdPhaseNextDecimal(cwd, basePhase, raw) {
     const baseExists = dirs.some(dir => dir.startsWith(normalized + '-') || dir === normalized);
 
     // Find existing decimal phases for this base
-    const decimalPattern = new RegExp(`^${normalized}\\.(\\d+)`);
+    const decimalPattern = new RegExp(`^${escapeRegex(normalized)}\\.(\\d+)`);
     const existingDecimals = [];
 
     for (const dir of dirs) {
@@ -444,7 +444,7 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
   // Normalize input then strip leading zeros for flexible matching
   const normalizedAfter = normalizePhaseName(afterPhase);
   const unpadded = normalizedAfter.replace(/^0+/, '');
-  const afterPhaseEscaped = unpadded.replace(/\./g, '\\.');
+  const afterPhaseEscaped = escapeRegex(unpadded);
   const targetPattern = new RegExp(`#{2,4}\\s*Phase\\s+0*${afterPhaseEscaped}:`, 'i');
   if (!targetPattern.test(content)) {
     error(`Phase ${afterPhase} not found in roadmap.md`);
@@ -458,7 +458,7 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
   try {
     const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
     const dirs = entries.filter(entry => entry.isDirectory()).map(entry => entry.name);
-    const decimalPattern = new RegExp(`^${normalizedBase}\\.(\\d+)`);
+    const decimalPattern = new RegExp(`^${escapeRegex(normalizedBase)}\\.(\\d+)`);
     for (const dir of dirs) {
       const decMatch = dir.match(decimalPattern);
       if (decMatch) existingDecimals.push(parseInt(decMatch[1], 10));
@@ -484,7 +484,7 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
   const phaseEntry = `\n### Phase ${decimalPhase}: ${description} (INSERTED)\n\n**Goal:** [Urgent work - to be planned]\n**Requirements**: TBD\n**Depends on:** Phase ${afterPhase}\n**Plans:** 0 plans\n\nPlans:\n- [ ] TBD (run /pan:plan-phase ${decimalPhase} to break down)\n`;
 
   // Insert after the target phase section
-  const headerPattern = new RegExp(`(#{2,4}\\s*Phase\\s+0*${afterPhaseEscaped}:[^\\n]*\\n)`, 'i');
+  const headerPattern = new RegExp(`(#{2,4}\\s*Phase\\s+0*${afterPhaseEscaped}:[^\\n]*\\n)`, 'i'); // afterPhaseEscaped already run through escapeRegex above
   const headerMatch = content.match(headerPattern);
   if (!headerMatch) {
     error(`Could not find Phase ${afterPhase} header`);

package/pan-wizard-core/bin/lib/review-deep.cjs

@@ -198,7 +198,9 @@ function writeDeepReview(cwd, phaseNum, payload, opts) {
     lines.push('|----------|--------|----------|-------------|------|');
     for (const f of payload.findings) {
       const loc = f.file ? `\`${f.file}${f.line ? `:${f.line}` : ''}\`` : '—';
-      const desc = f.description.replace(/\|/g, '\\|');
+      // Neutralize markdown-table-breaking chars: escape pipes and flatten any
+      // newlines so a finding description can't corrupt the table structure.
+      const desc = String(f.description).replace(/\\/g, '\\\\').replace(/\|/g, '\\|').replace(/[\r\n]+/g, ' ');
       lines.push(`| ${f.severity} | ${f.source} | ${f.category} | ${desc} | ${loc} |`);
     }
     lines.push('');

package/pan-wizard-core/bin/lib/skill-align.cjs

@@ -0,0 +1,364 @@
+/**
+ * Skill-Align — Skill-Aligned Decomposition (SAD) pass for planning
+ * (ADR-0038, spec: docs/specs/skill-aligned-decomposition.md).
+ *
+ * SkillWeaver's finding (arXiv 2606.18051): one-shot task decomposition
+ * misaligns with the tool/skill library that actually exists; feeding
+ * retrieved skill candidates back to the decomposer to realign vocabulary
+ * and granularity lifted decomposition accuracy 51% → 92%.
+ *
+ * PAN's adoption is deliberately minimal and advisory:
+ *   - index built on the fly (~140 small files; no persisted index, no
+ *     staleness, no installer changes)
+ *   - keyword scoring via knowledge.cjs scoreRelevance (no embeddings,
+ *     no vector store — ADR-0036 guardrail)
+ *   - output is names + one-line descriptions, budget-bounded, with
+ *     explicit `dropped` reporting (no silent caps)
+ *   - fail-open: missing roots are skipped, never thrown — the planner
+ *     proceeds as today if anything is absent
+ *
+ * The "rewrite the decomposition" half of the loop stays in the
+ * pan-planner agent (it is already an LLM); this module only retrieves.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { output, error, safeReadFile, toPosix } = require('./core.cjs');
+const {
+  CHARS_PER_TOKEN,
+  SKILL_ALIGN_TOP_K,
+  SKILL_ALIGN_MIN_SCORE,
+  SKILL_ALIGN_VOCAB_BUDGET_TOKENS,
+  SKILL_ALIGN_MAX_TASKS,
+  SKILL_ALIGN_CONTENT_CAP,
+} = require('./constants.cjs');
+const { scoreRelevance } = require('./knowledge.cjs');
+const { readIndex } = require('./learn-index.cjs');
+
+/**
+ * Planning glue words stripped from task cues before scoring. Without this,
+ * "Create the API" matches every skill file containing "create". Nouns that
+ * carry skill signal (test, phase, plan, commit, ...) are deliberately kept.
+ */
+const SAD_STOPWORDS = new Set([
+  'create', 'add', 'implement', 'update', 'write', 'make', 'build',
+  'setup', 'set', 'ensure', 'use', 'using', 'new', 'the', 'and', 'for',
+  'with', 'this', 'that', 'from', 'into', 'each', 'all', 'should', 'must',
+  'task', 'tasks', 'file', 'files',
+]);
+
+/**
+ * Skill roots walked by buildSkillIndex, relative to the resolved root.
+ * The same relative layout holds in the source repo and in every install
+ * (root = the directory containing pan-wizard-core/).
+ */
+const SKILL_ROOTS = [
+  { kind: 'command', rel: path.join('commands', 'pan'), recursive: false },
+  { kind: 'template', rel: path.join('pan-wizard-core', 'templates'), recursive: true },
+  { kind: 'reference', rel: path.join('pan-wizard-core', 'references'), recursive: false },
+];
+
+/**
+ * Default skill root: three levels up from lib/ — the install root
+ * (~/.claude/) or the source repo root. Mirrors experiment.cjs
+ * PAN_SOURCE_ROOT; both layouts keep commands/ and pan-wizard-core/
+ * side by side.
+ */
+function resolveSkillRoot() {
+  return path.resolve(__dirname, '..', '..', '..');
+}
+
+/**
+ * Frontmatter is only needed for two scalar keys; a targeted line scan
+ * avoids importing the full YAML parser for files that may not have
+ * frontmatter at all.
+ */
+function readNameDescription(content) {
+  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return {};
+  const out = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = line.match(/^(name|description):\s*(.+)$/);
+    if (kv && !(kv[1] in out)) out[kv[1]] = kv[2].trim().replace(/^["']|["']$/g, '');
+  }
+  return out;
+}
+
+/** First markdown heading, or first non-empty non-delimiter line. */
+function firstHeading(content) {
+  const body = content.replace(/^---\r?\n[\s\S]*?\r?\n---/, '');
+  for (const line of body.split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t || t === '---' || /^<\/?[\w-]+>$/.test(t)) continue;
+    const h = t.match(/^#+\s+(.+)$/);
+    return (h ? h[1] : t).slice(0, 120);
+  }
+  return '';
+}
+
+function listMdFiles(dir, recursive) {
+  const files = [];
+  let entries = [];
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return files; }
+  for (const e of entries) {
+    const abs = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (recursive) files.push(...listMdFiles(abs, true));
+    } else if (e.name.endsWith('.md')) {
+      files.push(abs);
+    }
+  }
+  return files;
+}
+
+/**
+ * Build the skill index from the filesystem. Never throws: roots or
+ * learnings that are missing/unreadable are skipped and reported in
+ * stats.skipped_roots.
+ *
+ * @param {string} root - install root or source repo root
+ * @returns {{entries: Array, stats: {entries: number, by_kind: Object, skipped_roots: string[]}}}
+ */
+function buildSkillIndex(root) {
+  const entries = [];
+  const skipped = [];
+
+  for (const sr of SKILL_ROOTS) {
+    const dir = path.join(root, sr.rel);
+    const files = listMdFiles(dir, sr.recursive);
+    if (files.length === 0) { skipped.push(toPosix(sr.rel)); continue; }
+    for (const abs of files) {
+      const content = safeReadFile(abs);
+      if (!content) continue;
+      const fm = readNameDescription(content);
+      const relFile = toPosix(path.relative(root, abs));
+      const name = fm.name
+        || toPosix(path.relative(path.join(root, sr.rel), abs)).replace(/\.md$/, '');
+      const description = fm.description || firstHeading(content);
+      entries.push({
+        kind: sr.kind,
+        name,
+        description,
+        file: relFile,
+        tokens_est: Math.ceil(content.length / CHARS_PER_TOKEN),
+        // scoring head, not serialized in CLI output
+        _head: `${name} ${description} ${content.slice(0, SKILL_ALIGN_CONTENT_CAP)}`,
+      });
+    }
+  }
+
+  // Learnings topics via the existing index (built on the fly if index.json
+  // is absent). A root with no learnings yields zero topics, not an error.
+  let topics = [];
+  try { topics = readIndex(root).topics || []; } catch { topics = []; }
+  if (topics.length === 0) skipped.push(toPosix(path.join('pan-wizard-core', 'learnings')));
+  for (const t of topics) {
+    const content = safeReadFile(path.join(root, t.file)) || '';
+    const name = `${t.scope}/${t.name}`;
+    const ids = (t.patterns || []).join(', ');
+    const description = content
+      ? `${firstHeading(content)}${ids ? ` (${ids})` : ''}`
+      : ids;
+    entries.push({
+      kind: 'learning',
+      name,
+      description,
+      file: toPosix(t.file),
+      tokens_est: t.size_tokens_est || Math.ceil(content.length / CHARS_PER_TOKEN),
+      _head: `${name} ${description} ${content.slice(0, SKILL_ALIGN_CONTENT_CAP)}`,
+    });
+  }
+
+  const byKind = {};
+  for (const e of entries) byKind[e.kind] = (byKind[e.kind] || 0) + 1;
+  return {
+    entries,
+    stats: { entries: entries.length, by_kind: byKind, skipped_roots: skipped },
+  };
+}
+
+/**
+ * Parse a draft task blob into task strings. Accepts markdown bullets,
+ * numbered lists, checkboxes, or plain lines; drops headings and blanks.
+ */
+function parseDraftTasks(text) {
+  if (typeof text !== 'string') return [];
+  const tasks = [];
+  for (const line of text.split(/\r?\n/)) {
+    let t = line.trim();
+    if (!t || /^#{1,6}\s/.test(t) || t === '---') continue;
+    t = t.replace(/^(?:[-*+]|\d+[.)])\s+/, '').replace(/^\[[ xX]\]\s+/, '').trim();
+    if (t.length < 3) continue;
+    tasks.push(t);
+  }
+  return tasks;
+}
+
+/** Strip planning glue words so cues carry skill signal only. */
+function cleanCue(task) {
+  return task
+    .split(/\W+/)
+    .filter(w => w.length >= 3 && !SAD_STOPWORDS.has(w.toLowerCase()))
+    .join(' ');
+}
+
+/**
+ * The SAD retrieval pass: score each draft task against the skill index,
+ * return per-task top-k matches plus a deduped, budget-packed vocabulary
+ * hint list for the planner to realign against.
+ *
+ * @param {string} root - skill root (resolveSkillRoot() for callers without an override)
+ * @param {string[]} tasks - draft task strings
+ * @param {Object} [opts] - {topK, minScore, tokenBudget}
+ * @returns {Object} result per docs/specs/skill-aligned-decomposition.md §3.3
+ */
+function alignTasks(root, tasks, opts) {
+  if (!Array.isArray(tasks) || tasks.length === 0) {
+    return { error: 'no tasks to align — provide a non-empty draft task list' };
+  }
+  if (tasks.length > SKILL_ALIGN_MAX_TASKS) {
+    return { error: `draft has ${tasks.length} tasks — max ${SKILL_ALIGN_MAX_TASKS}; a draft this large is a planning smell, split the phase` };
+  }
+  const topK = Math.max(1, Math.min(10, Number(opts?.topK) || SKILL_ALIGN_TOP_K));
+  const minScore = Math.max(1, Number(opts?.minScore) || SKILL_ALIGN_MIN_SCORE);
+  const budget = Math.max(100, Number(opts?.tokenBudget) || SKILL_ALIGN_VOCAB_BUDGET_TOKENS);
+
+  const { entries, stats } = buildSkillIndex(root);
+
+  const perTask = [];
+  const aggregate = new Map(); // kind/name -> {entry, totalScore}
+  for (const task of tasks) {
+    const cue = cleanCue(String(task));
+    const scored = [];
+    if (cue) {
+      for (const e of entries) {
+        const score = scoreRelevance(cue, e._head);
+        if (score >= minScore) scored.push({ e, score });
+      }
+    }
+    scored.sort((a, b) => b.score - a.score || a.e.name.localeCompare(b.e.name));
+    const top = scored.slice(0, topK);
+    for (const { e, score } of top) {
+      const key = `${e.kind}/${e.name}`;
+      const agg = aggregate.get(key) || { entry: e, totalScore: 0 };
+      agg.totalScore += score;
+      aggregate.set(key, agg);
+    }
+    perTask.push({
+      task: String(task),
+      matches: top.map(({ e, score }) => ({ kind: e.kind, name: e.name, file: e.file, score })),
+      matched: top.length > 0,
+    });
+  }
+
+  // Vocabulary: deduped union of all matches, ranked by aggregate score,
+  // greedy-packed into the token budget. Overflow is reported, not hidden.
+  const ranked = [...aggregate.values()]
+    .sort((a, b) => b.totalScore - a.totalScore || a.entry.name.localeCompare(b.entry.name));
+  const vocabulary = [];
+  const dropped = [];
+  let vocabTokens = 0;
+  for (const { entry } of ranked) {
+    const tokens = Math.ceil((entry.name.length + entry.description.length) / CHARS_PER_TOKEN);
+    if (vocabTokens + tokens > budget) {
+      dropped.push({ kind: entry.kind, name: entry.name, tokens });
+      continue;
+    }
+    vocabulary.push({
+      kind: entry.kind,
+      name: entry.name,
+      description: entry.description,
+      file: entry.file,
+      tokens,
+    });
+    vocabTokens += tokens;
+  }
+
+  const matchedCount = perTask.filter(t => t.matched).length;
+  return {
+    tasks: perTask,
+    coverage: {
+      matched: matchedCount,
+      total: perTask.length,
+      ratio: perTask.length ? Math.round((matchedCount / perTask.length) * 100) / 100 : 0,
+    },
+    vocabulary,
+    vocabulary_tokens: vocabTokens,
+    dropped,
+    index_stats: stats,
+    top_k: topK,
+    min_score: minScore,
+    token_budget: budget,
+  };
+}
+
+// ─── CLI wrappers ───────────────────────────────────────────────────────────
+
+function cmdSkillsIndex(root, raw) {
+  const { entries, stats } = buildSkillIndex(root);
+  const result = {
+    entries: entries.map(({ _head, ...rest }) => rest),
+    total: stats.entries,
+    by_kind: stats.by_kind,
+    skipped_roots: stats.skipped_roots,
+  };
+  if (raw) {
+    const lines = [`Skill index (${stats.entries} entries):`, ''];
+    for (const e of result.entries) {
+      lines.push(`  [${e.kind.padEnd(9)}] ${e.name.padEnd(36)} ${String(e.tokens_est).padStart(5)}t  ${e.description}`);
+    }
+    if (stats.skipped_roots.length > 0) {
+      lines.push('', `Skipped roots (missing/empty): ${stats.skipped_roots.join(', ')}`);
+    }
+    output(result, true, lines.join('\n'));
+  } else {
+    output(result, false);
+  }
+}
+
+function cmdSkillsAlign(root, opts, raw) {
+  let draft = opts?.draft;
+  if (!draft && opts?.draftFile) {
+    draft = safeReadFile(opts.draftFile);
+    if (draft === null) {
+      output({ error: `draft file not found or unreadable: ${opts.draftFile}` }, raw);
+      return;
+    }
+  }
+  if (!draft || !draft.trim()) {
+    error('Usage: skills align (--draft "<text>" | --draft-file <path>) [--top <k>] [--min-score <n>] [--token-budget <n>] [--source-root <path>]');
+  }
+  const tasks = parseDraftTasks(draft);
+  const result = alignTasks(root, tasks, opts);
+  if (result.error) { output(result, raw); return; }
+  if (raw) {
+    const lines = [`SAD alignment: ${result.coverage.matched}/${result.coverage.total} tasks matched (${result.index_stats.entries} skills indexed)`, ''];
+    for (const t of result.tasks) {
+      lines.push(`  ${t.matched ? '✓' : '✗'} ${t.task}`);
+      for (const m of t.matches) {
+        lines.push(`      [${m.kind}] ${m.name} (score ${m.score})`);
+      }
+    }
+    lines.push('', `Vocabulary hints (${result.vocabulary.length} skills, ${result.vocabulary_tokens}t of ${result.token_budget}t budget):`);
+    for (const v of result.vocabulary) {
+      lines.push(`  [${v.kind.padEnd(9)}] ${v.name} — ${v.description}`);
+    }
+    if (result.dropped.length > 0) {
+      lines.push(`Dropped (over budget): ${result.dropped.map(d => d.name).join(', ')}`);
+    }
+    output(result, true, lines.join('\n'));
+  } else {
+    output(result, false);
+  }
+}
+
+module.exports = {
+  resolveSkillRoot,
+  buildSkillIndex,
+  parseDraftTasks,
+  alignTasks,
+  cmdSkillsIndex,
+  cmdSkillsAlign,
+  SAD_STOPWORDS,
+  SKILL_ROOTS,
+};