archgen-skill 0.0.3 → 0.0.4

package/vendor/skills/archgen/scripts/lib/yaml.mjs

@@ -32,7 +32,11 @@ const INDENT_UNIT = 2;
  */
 export function parseYaml(text, opts = {}) {
   const filename = opts.filename ?? '<input>';
-  const lines = text.split('\n');
+  // Normalize CRLF: split on '\n' leaves a stray '\r' at the end of every line
+  // in Windows-authored files; stripping it here keeps scalar values and
+  // comment texts free of carriage returns so stringify can never double them
+  // up when re-emitting with the file's dominant EOL (see stringifyYaml eol).
+  const lines = text.split('\n').map((l) => (l.endsWith('\r') ? l.slice(0, -1) : l));
   // Strip a single trailing newline artifact so the last real line is processed.
   if (lines.length && lines[lines.length - 1] === '') lines.pop();
 
@@ -120,6 +124,11 @@ function parseMapping(lines, pos, indent, ctx, basePath = []) {
     const m = matchKey(c.text);
     if (!m) fail(ctx, pos.i + 1, `expected 'key:' mapping entry, got: ${c.bare.slice(0, 40)}`);
     assertKeyWellFormed(ctx, pos.i + 1, m);
+    // Duplicate keys are a corruption class (real YAML parsers reject them):
+    // silent last-wins hides data from every downstream check.
+    if (Object.prototype.hasOwnProperty.call(out, m.key)) {
+      fail(ctx, pos.i + 1, `duplicate key '${m.key}' in mapping`);
+    }
     const keyPath = [...basePath, m.key];
     const key = consumePendingAndParseKey(ctx, c, pos.i + 1, keyPath);
     pos.i++;
@@ -295,6 +304,9 @@ function parseScalarOrFlow(v, ctx, lineNo) {
       const m = matchKey(part);
       if (!m) fail(ctx, lineNo, `flow mapping entry must be 'key: value', got: ${part}`);
       assertKeyWellFormed(ctx, lineNo, m);
+      if (Object.prototype.hasOwnProperty.call(obj, m.key)) {
+        fail(ctx, lineNo, `duplicate key '${m.key}' in flow mapping`);
+      }
       const val = part.slice(m.end).trim();
       if (val.startsWith('{')) fail(ctx, lineNo, `nested flow mappings are not supported: ${val}`);
       obj[m.key] = parseScalarOrFlow(val, ctx, lineNo);
@@ -384,8 +396,12 @@ function flushPendingInto(comments, pending, path, _inline) {
  * Serialize data back to the YAML subset, re-emitting comments positionally.
  * @param {any} data
  * @param {YamlComment[]} [comments]
+ * @param {{eol?: string}} [opts] `eol` joins lines with the given line ending
+ *   (default '\n'); callers that detected a CRLF source pass '\r\n' so the
+ *   rewrite preserves the file's dominant convention byte-for-byte.
  */
-export function stringifyYaml(data, comments = []) {
+export function stringifyYaml(data, comments = [], opts = {}) {
+  const eol = opts.eol ?? '\n';
   const out = [];
   const used = new Set();
   emitValue(out, data, 0, comments, used, []);
@@ -393,7 +409,7 @@ export function stringifyYaml(data, comments = []) {
   for (let i = 0; i < comments.length; i++) {
     if (!used.has(i) && comments[i].path === null) out.push(comments[i].text);
   }
-  return out.join('\n') + '\n';
+  return out.join(eol) + eol;
 }
 
 function preComments(out, comments, used, path) {

package/vendor/skills/archgen/scripts/plan-graph.mjs

@@ -0,0 +1,329 @@
+#!/usr/bin/env node
+// plan-graph.mjs — dependency-graph lens over a plan: overview, task neighborhood,
+// Mermaid rendering, module filtering.
+// Usage:
+//   node plan-graph.mjs <slug-dir-or-tasks.yaml>                     overview JSON
+//   node plan-graph.mjs <...> --node TASK-03                         neighborhood JSON
+//   node plan-graph.mjs <...> --node TASK-03 --mermaid [--status]    neighborhood Mermaid
+//   node plan-graph.mjs <...> --mermaid [--status]                   whole-graph Mermaid
+//   node plan-graph.mjs <...> --module <name>                        module filter JSON
+// Input is either a `.archgen/<slug>/` directory (finds tasks.yaml inside; also
+// reads architecture.yaml modules when present) or a direct path to tasks.yaml.
+// Scope-hardened: refuses any input outside .archgen/<slug>/ (see lib/scope.mjs).
+// Exit codes: 0 ok · 2 cycle / duplicate task id / dangling depends_on
+// (GraphError class) · 4 invalid input/file/flags or oversized render request.
+//
+// DEDUP GUARANTEES (stateless idempotency): identical input yields byte-
+// identical output AND zero duplicated entities inside one output. Duplicate
+// depends_on entries (`[A, A]`) collapse to one edge before graph build —
+// overview reports how many via `duplicatesCollapsed`, edgeCount counts unique
+// edges, and Mermaid can never emit the same `X --> Y` line twice. Duplicate
+// task ids are a hard GraphError → exit 2 naming the id.
+//
+// SCALE GUARDS: every traversal is iterative (explicit stack/queue — no
+// recursion on graph depth); whole-graph `--mermaid` refuses graphs over 250
+// nodes (exit 4 with a scope-it hint; --node neighborhood and --module views
+// stay exempt); JSON emits each title once per node object, never per edge.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseYaml } from './lib/yaml.mjs';
+import { buildGraph, findCycle, computeWaves, dedupeDependencies, computeQualityStats, GraphError } from './lib/graph.mjs';
+import { resolveSlugInput, ScopeError } from './lib/scope.mjs';
+
+const USAGE = 'usage: plan-graph.mjs <slug-dir-or-tasks.yaml> [--node <id>] [--mermaid] [--status] [--module <name>]';
+// Whole-graph Mermaid above this node count is refused: the text would flood an
+// LLM context without adding information. Scoped renders stay exempt.
+const MERMAID_WHOLE_MAX_NODES = 250;
+function die(msg, code = 4) { console.error(msg); process.exit(code); }
+
+// --- argument parsing -------------------------------------------------------
+const argv = process.argv.slice(2);
+const opts = { input: null, node: null, mermaid: false, status: false, module: null };
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === '--node') opts.node = argv[++i];
+  else if (a === '--mermaid') opts.mermaid = true;
+  else if (a === '--status') opts.status = true;
+  else if (a === '--module') opts.module = argv[++i];
+  else if (a.startsWith('--')) die(`${USAGE} — unknown option '${a}'`);
+  else if (opts.input === null) opts.input = a;
+  else die(`${USAGE} — unexpected extra argument '${a}'`);
+}
+if (!opts.input) die(USAGE);
+if (opts.node === undefined || opts.module === undefined) die(`${USAGE} — --node/--module require a value`);
+if (opts.node === '' || opts.module === '') die(`${USAGE} — --node/--module require a non-empty value`);
+if (opts.module !== null && (opts.node !== null || opts.mermaid)) die(`${USAGE} — --module cannot combine with --node/--mermaid`);
+if (opts.status && !opts.mermaid) die(`${USAGE} — --status requires --mermaid`);
+
+// --- input resolution -------------------------------------------------------
+// The scope gate is the ONLY way in: directory input must be an immediate child
+// of a `.archgen` segment, direct-file input must be that slug dir's own
+// tasks.yaml; symlinks are judged by their real target. Everything inside runs
+// off the resolved absolute root.
+let scoped;
+try {
+  scoped = resolveSlugInput(opts.input);
+} catch (e) {
+  if (e instanceof ScopeError) die(`plan-graph: ${e.message}`);
+  die(`cannot read ${opts.input} (missing or unreadable)`);
+}
+const planDir = scoped.root; // absolute slug dir for BOTH kinds (tasks.yaml sits directly inside it)
+const tasksFile = join(planDir, 'tasks.yaml');
+const slug = scoped.slug;
+
+let raw;
+try {
+  raw = readFileSync(tasksFile, 'utf8');
+} catch {
+  die(`cannot read ${tasksFile} (missing or unreadable)`);
+}
+let data;
+try {
+  ({ data } = parseYaml(raw, { filename: tasksFile }));
+} catch (e) {
+  die(`${tasksFile}: unparseable YAML (${String(e?.message ?? e).replace(/^[^:]*:\d+:\s*/, '')})`);
+}
+const tasks = data?.tasks;
+if (!Array.isArray(tasks)) die(`${tasksFile}: missing 'tasks:' sequence`);
+
+// --- dedup normalization (A1) -----------------------------------------------
+// Collapse duplicate depends_on entries BEFORE graph build so every downstream
+// view (adjacency, waves, Mermaid, counts) sees each edge exactly once.
+const { tasks: uniqueTasks, duplicatesCollapsed } = dedupeDependencies(tasks);
+const quality = computeQualityStats(uniqueTasks); // facts only — never fails
+
+// --- shared engine ----------------------------------------------------------
+let byId, prerequisites, dependents;
+try {
+  ({ byId, prerequisites, dependents } = buildGraph(uniqueTasks));
+} catch (e) {
+  // GraphError class = structurally invalid graph (duplicate task id, dangling
+  // depends_on): exit 2 like cycles — the plan is unexecutable, not merely a
+  // bad flag. The message names the offending id.
+  if (e instanceof GraphError) die(e.message, 2);
+  throw e;
+}
+const cycle = findCycle(prerequisites);
+if (cycle.length) die(`dependency cycle detected: ${cycle.join(' -> ')}`, 2);
+const { waves } = computeWaves(byId, prerequisites);
+
+// --- helpers ----------------------------------------------------------------
+const byIdAsc = (a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+
+/** BFS hop-distances from start across an adjacency map (start itself at 0). */
+function bfsDistances(start, adjacency) {
+  const dist = new Map([[start, 0]]);
+  const queue = [start];
+  while (queue.length) {
+    const cur = queue.shift();
+    for (const next of adjacency.get(cur) ?? []) {
+      if (!dist.has(next)) { dist.set(next, dist.get(cur) + 1); queue.push(next); }
+    }
+  }
+  return dist;
+}
+
+/** Transitive neighborhood at distance >= 1, sorted by distance then id. */
+function neighborhood(start, adjacency) {
+  return [...bfsDistances(start, adjacency)]
+    .filter(([id]) => id !== start)
+    .map(([id, distance]) => ({ id, title: byId.get(id).title, status: byId.get(id).status, distance }))
+    .sort((a, b) => a.distance - b.distance || byIdAsc(a, b));
+}
+
+// Local copy of lib/graph.mjs's internal glob-overlap heuristic: it is not
+// exported upstream and existing files must not be modified, so --module keeps
+// the exact conservative rules here rather than inventing divergent ones.
+function globsMayOverlap(a, b) {
+  if (a === b) return true;
+  // Deepen the check only when a recursive '**' is involved; plain literal
+  // globs keep the cheap equality rule above.
+  if (!a.includes('**') && !b.includes('**')) return false;
+  const as = a.split('/');
+  const bs = b.split('/');
+  const n = Math.min(as.length, bs.length);
+  for (let i = 0; i < n; i++) {
+    const x = as[i];
+    const y = bs[i];
+    if (x === y) continue;
+    if (x === '**' || y === '**') return true; // '**' swallows any divergence below it
+    if (x.includes('*') || y.includes('*') || x.includes('?') || y.includes('?')) return true; // uncertain -> flag
+    return false; // both segments literal and different: paths diverge here
+  }
+  return true; // one pattern is a segment-prefix of the other
+}
+
+// architecture.yaml is optional enrichment; a PRESENT-but-unparseable one is
+// refused loudly — silent data loss is the corruption class this repo guards
+// against everywhere else (see lib/yaml.mjs).
+function readModuleNames(dir) {
+  if (!dir) return null;
+  const p = join(dir, 'architecture.yaml');
+  let archRaw;
+  try {
+    archRaw = readFileSync(p, 'utf8');
+  } catch {
+    return null; // absent: fine, overview simply omits modules
+  }
+  let parsed;
+  try {
+    parsed = parseYaml(archRaw, { filename: p }).data;
+  } catch (e) {
+    die(`${p}: unparseable YAML (${String(e?.message ?? e).replace(/^[^:]*:\d+:\s*/, '')})`);
+  }
+  const mods = parsed?.modules;
+  if (!Array.isArray(mods)) return null;
+  return mods.map((m) => m?.name).filter((n) => typeof n === 'string' && n !== '').sort();
+}
+
+// --- Mermaid rendering ------------------------------------------------------
+// Tasteful, professional palette; only done/running/failed get classes — every
+// other status (pending, ready, blocked) renders with Mermaid's default look.
+const MERMAID_CLASSES = {
+  done: 'fill:#e8f5e9,stroke:#2e7d32,stroke-width:1.5px',
+  running: 'fill:#e3f2fd,stroke:#1565c0,stroke-width:1.5px',
+  failed: 'fill:#ffebee,stroke:#c62828,stroke-width:1.5px',
+};
+const FOCUS_CLASS = 'fill:#fff8e1,stroke:#b45309,stroke-width:2px';
+
+const esc = (s) => String(s).replace(/"/g, "'");
+const shortTitle = (t) => {
+  const s = String(t.title ?? '');
+  return s.length > 36 ? `${s.slice(0, 35).trimEnd()}…` : s;
+};
+const nodeDecl = (t) => `${t.id}["${esc(t.id)} ${esc(shortTitle(t))}"]`;
+
+/** classDef lines for the given class names, in fixed order (focus first). */
+function classDefLines(classNames) {
+  const lines = [];
+  if (classNames.includes('focus')) lines.push(`  classDef focus ${FOCUS_CLASS};`);
+  for (const cls of Object.keys(MERMAID_CLASSES)) {
+    if (classNames.includes(cls)) lines.push(`  classDef ${cls} ${MERMAID_CLASSES[cls]};`);
+  }
+  return lines;
+}
+
+/** One `class` statement per styled status over `ids`, sorted — deterministic. */
+function statusClassLines(ids) {
+  const lines = [];
+  for (const cls of Object.keys(MERMAID_CLASSES)) {
+    const members = ids.filter((id) => byId.get(id)?.status === cls);
+    if (members.length) lines.push(`  class ${members.join(',')} ${cls};`);
+  }
+  return lines;
+}
+
+/** Deduped [prerequisite, dependent] pairs, sorted lexicographically. */
+function allEdges() {
+  const seen = new Set();
+  const edges = [];
+  for (const [prereq, deps] of dependents) {
+    for (const dep of deps) {
+      const key = `${prereq}\u0000${dep}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      edges.push([prereq, dep]);
+    }
+  }
+  return edges.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : a[1] < b[1] ? -1 : 1));
+}
+
+function wholeMermaid() {
+  const ids = uniqueTasks.map((t) => t.id).sort();
+  const lines = [
+    'flowchart LR',
+    ...(opts.status ? classDefLines(Object.keys(MERMAID_CLASSES)) : []),
+    ...ids.map((id) => `  ${nodeDecl(byId.get(id))}`),
+    // allEdges() is deduped by construction (and normalized upstream), so no
+    // `X --> Y` line can ever repeat here.
+    ...allEdges().map(([a, b]) => `  ${a} --> ${b}`),
+  ];
+  if (opts.status) lines.push(...statusClassLines(ids));
+  return lines.join('\n');
+}
+
+function neighborhoodMermaid(focus) {
+  const up = [...bfsDistances(focus.id, prerequisites)].filter(([id]) => id !== focus.id).map(([id]) => id).sort();
+  const down = [...bfsDistances(focus.id, dependents)].filter(([id]) => id !== focus.id).map(([id]) => id).sort();
+  const lines = ['flowchart LR', ...classDefLines(opts.status ? ['focus', ...Object.keys(MERMAID_CLASSES)] : ['focus'])];
+  if (up.length) lines.push('  subgraph upstream', ...up.map((id) => `    ${nodeDecl(byId.get(id))}`), '  end');
+  lines.push(`  ${nodeDecl(focus)}`);
+  if (down.length) lines.push('  subgraph downstream', ...down.map((id) => `    ${nodeDecl(byId.get(id))}`), '  end');
+  const visible = new Set([focus.id, ...up, ...down]);
+  lines.push(...allEdges()
+    .filter(([a, b]) => visible.has(a) && visible.has(b))
+    .map(([a, b]) => `  ${a} --> ${b}`));
+  lines.push(`  class ${focus.id} focus;`);
+  if (opts.status) lines.push(...statusClassLines([...up, ...down]));
+  return lines.join('\n');
+}
+
+// --- modes ------------------------------------------------------------------
+if (opts.node !== null) {
+  const t = byId.get(opts.node);
+  if (!t) die(`no task '${opts.node}' in ${tasksFile}`);
+  if (opts.mermaid) {
+    console.log(neighborhoodMermaid(t));
+  } else {
+    console.log(JSON.stringify({
+      id: t.id,
+      title: t.title,
+      status: t.status,
+      upstream: neighborhood(t.id, prerequisites),
+      downstream: neighborhood(t.id, dependents),
+      // Peers only — the node itself is already the subject of the report.
+      sameWave: (waves.find((w) => w.some((n) => n.id === t.id)) ?? [])
+        .filter((n) => n.id !== t.id).map((n) => n.id).sort(),
+      ownedFiles: [...(t.file_ownership ?? [])].sort(),
+      acceptanceCount: Array.isArray(t.acceptance) ? t.acceptance.length : 0,
+      artifacts: [...(t.artifacts ?? [])].sort(),
+    }, null, 2));
+  }
+} else if (opts.mermaid) {
+  // Scale guard (B6): whole-graph renders above the node ceiling are refused
+  // with an actionable hint; --node neighborhood and --module views below stay
+  // exempt because their output is bounded by the scope, not the graph.
+  const nodeCount = uniqueTasks.length;
+  if (nodeCount > MERMAID_WHOLE_MAX_NODES) {
+    die(`graph too large to render whole (${nodeCount} nodes) — scope it: --node <id> | --module <name> | --file <path>`);
+  }
+  console.log(wholeMermaid());
+} else if (opts.module !== null) {
+  // Module filter: a task plausibly touches module <name> when any ownership
+  // glob may overlap "<name>/**" — conservative, same rules as the same-wave
+  // clash detector in lib/graph.mjs.
+  const pattern = `${opts.module}/**`;
+  const matched = uniqueTasks
+    .filter((t) => (t.file_ownership ?? []).some((g) => globsMayOverlap(g, pattern)))
+    .sort(byIdAsc);
+  console.log(JSON.stringify({
+    module: opts.module,
+    tasks: matched.map((t) => ({ id: t.id, title: t.title, status: t.status, file_ownership: t.file_ownership })),
+  }, null, 2));
+} else {
+  const out = {
+    slug,
+    taskCount: uniqueTasks.length,
+    // Unique edges post-dedup (raw depends_on entries that collapsed are
+    // reported separately as duplicatesCollapsed).
+    edgeCount: uniqueTasks.reduce((n, t) => n + (Array.isArray(t.depends_on) ? t.depends_on.length : 0), 0),
+    duplicatesCollapsed,
+    // Facts, not verdicts — verify-plan.mjs owns pass/fail.
+    quality,
+    waves: waves.map((w) => w.map((t) => ({ id: t.id, status: t.status }))),
+    roots: uniqueTasks.filter((t) => prerequisites.get(t.id).length === 0).map((t) => t.id).sort(),
+    leaves: uniqueTasks.filter((t) => (dependents.get(t.id) ?? []).length === 0).map((t) => t.id).sort(),
+  };
+  const modules = readModuleNames(planDir);
+  if (modules) out.modules = modules;
+  console.log(JSON.stringify(out, null, 2));
+}
+
+// ---------------------------------------------------------------------------
+// WHY plan-graph.mjs EXISTS: generic code indexers (GitHub code nav, Sourcegraph,
+// CodeGraph-style SQLite MCP servers) model source symbols, not YAML task-DAG edges
+// (ast-grep parses YAML ASTs but stays stateless search), so every YAML-DAG system —
+// GitLab needs, Buildkite depends_on, Concourse passed, Argo dependencies — ships its
+// own schema-specific extractor. This script is archgen's; its Mermaid text renders
+// natively on GitHub/GitLab markdown with zero dependencies.
+// ---------------------------------------------------------------------------

package/vendor/skills/archgen/scripts/set-status.mjs

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 // set-status.mjs — atomic, comment-preserving task status mutator.
 // Usage: node set-status.mjs <tasks.yaml> <taskId> <status> [--force]
-// Illegal transitions (done -> pending|ready) require --force. Exit 4 on refusal.
-// Writes via temp-file + rename so concurrent readers never see partial files.
+// ANY transition out of 'done' requires --force (reopening completed work —
+// directly or via a failed/blocked hop — needs explicit intent). Exit 4 on refusal.
+// Writes via temp-file + rename so concurrent readers never see partial files,
+// and re-emits the file's dominant line-ending convention (CRLF stays CRLF).
 import { readFileSync, writeFileSync, renameSync } from 'node:fs';
 import { parseYaml, stringifyYaml } from './lib/yaml.mjs';
 
@@ -19,8 +21,26 @@ if (!STATUSES.includes(nextStatus)) {
   process.exit(4);
 }
 
-const raw = readFileSync(file, 'utf8');
-const { data, comments } = parseYaml(raw, { filename: file });
+let raw;
+try {
+  raw = readFileSync(file, 'utf8');
+} catch {
+  console.error(`cannot read ${file} (missing or unreadable)`);
+  process.exit(4);
+}
+// Detect the file's dominant line ending BEFORE parsing so the rewrite keeps
+// the author's convention instead of churning every line CRLF<->LF.
+const crlfCount = (raw.match(/\r\n/g) ?? []).length;
+const loneLfCount = (raw.match(/(?<!\r)\n/g) ?? []).length;
+const eol = crlfCount > loneLfCount ? '\r\n' : '\n';
+
+let data, comments;
+try {
+  ({ data, comments } = parseYaml(raw, { filename: file }));
+} catch (e) {
+  console.error(`${file}: unparseable YAML (${String(e?.message ?? e).replace(/^[^:]*:\d+:\s*/, '')})`);
+  process.exit(4);
+}
 const tasks = data?.tasks;
 if (!Array.isArray(tasks)) { console.error(`${file}: missing 'tasks:' sequence`); process.exit(4); }
 
@@ -28,13 +48,13 @@ const task = tasks.find((t) => t && t.id === taskId);
 if (!task) { console.error(`task '${taskId}' not found in ${file}`); process.exit(4); }
 
 const prev = task.status ?? 'pending';
-if ((prev === 'done') && (nextStatus === 'pending' || nextStatus === 'ready') && !force) {
+if (prev === 'done' && nextStatus !== 'done' && !force) {
   console.error(`refusing ${prev} -> ${nextStatus} for '${taskId}' without --force (reopening completed work needs explicit intent)`);
   process.exit(4);
 }
 
 task.status = nextStatus;
 const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
-writeFileSync(tmp, stringifyYaml(data, comments));
+writeFileSync(tmp, stringifyYaml(data, comments, { eol }));
 renameSync(tmp, file); // atomic on POSIX: readers observe old-or-new, never partial
 console.log(`${taskId}: ${prev} -> ${nextStatus}`);

package/vendor/skills/archgen/scripts/update-agents.mjs

@@ -75,8 +75,9 @@ function fmtDate(d) {
 /**
  * Derive the one-word registry status from a parsed tasks.yaml `tasks`
  * sequence. Precedence: unreadable -> unknown; any blocked -> blocked; all
- * done -> done; all pending/ready -> planned; everything else (any running,
- * or a done/pending/failed mix) -> in progress.
+ * failed -> blocked (dead work is never "in progress"); all done -> done;
+ * all pending/ready -> planned; everything else (any running, or a
+ * done/pending/failed mix) -> in progress.
  */
 function deriveStatus(tasks) {
   if (!Array.isArray(tasks)) return 'unknown';
@@ -89,6 +90,7 @@ function deriveStatus(tasks) {
   }
   if (statuses.length === 0) return 'planned'; // scaffolded folder, no entries yet
   if (statuses.includes('blocked')) return 'blocked';
+  if (statuses.every((s) => s === 'failed')) return 'blocked'; // all-failed feature: nothing is progressing
   if (statuses.every((s) => s === 'done')) return 'done';
   if (statuses.every((s) => s === 'pending' || s === 'ready')) return 'planned';
   return 'in progress';

package/vendor/skills/archgen/scripts/validate.mjs

@@ -11,10 +11,18 @@ import { buildGraph, findCycle, GraphError } from './lib/graph.mjs';
 const STATUSES = ['pending', 'ready', 'running', 'blocked', 'done', 'failed'];
 const REQUIRED = ['id', 'title', 'file_ownership'];
 const KNOWN_KEYS = new Set(['id', 'title', 'status', 'depends_on', 'parallel_group', 'file_ownership', 'artifacts', 'acceptance']);
+// Mirrors schemas/tasks.schema.json `id.pattern` — ids are strings, never
+// numeric-coerced scalars, or set-status/next-tasks cannot address the task.
+const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 
 const [, , file, ...rest] = process.argv;
 if (!file) { console.error('usage: validate.mjs <tasks.yaml> [--plan <dir>]'); process.exit(1); }
 const planDirIdx = rest.indexOf('--plan');
+if (planDirIdx >= 0 && rest[planDirIdx + 1] === undefined) {
+  // '--plan' with no value must never silently skip coverage checks.
+  console.error('usage: validate.mjs <tasks.yaml> [--plan <dir>] (--plan requires a directory value)');
+  process.exit(2);
+}
 const planDir = planDirIdx >= 0 ? rest[planDirIdx + 1] : null;
 
 /** @type {string[]} errors */ const errors = [];
@@ -42,7 +50,16 @@ for (const [i, t] of tasks.entries()) {
   const where = `tasks[${i}] (${t?.id ?? '<no-id>'})`;
   if (t === null || typeof t !== 'object' || Array.isArray(t)) { errors.push(`${where}: not a mapping`); continue; }
   for (const k of Object.keys(t)) if (!KNOWN_KEYS.has(k)) warnings.push(`${where}: unknown key '${k}' (ignored)`);
-  for (const r of REQUIRED) if (t[r] === undefined) errors.push(`${where}: missing required field '${r}'`);
+  // Required means present AND non-empty: `id:` parses to null, which is not
+  // undefined — an explicit empty value must fail, not bypass the check.
+  for (const r of REQUIRED) {
+    const v = t[r];
+    if (v === undefined) errors.push(`${where}: missing required field '${r}'`);
+    else if (v === null || (typeof v === 'string' && v.trim() === '')) errors.push(`${where}: required field '${r}' is empty`);
+  }
+  if (t.id !== undefined && t.id !== null && (typeof t.id !== 'string' || !ID_PATTERN.test(t.id))) {
+    errors.push(`${where}: invalid id '${t.id}' (must be a string matching ^[A-Za-z0-9][A-Za-z0-9._-]*$)`);
+  }
   if (t.status !== undefined && !STATUSES.includes(t.status)) errors.push(`${where}: invalid status '${t.status}' (allowed: ${STATUSES.join('|')})`);
   if (Array.isArray(t.file_ownership) && t.file_ownership.length === 0) errors.push(`${where}: file_ownership must be non-empty`);
   if (t.depends_on !== undefined && !Array.isArray(t.depends_on)) errors.push(`${where}: depends_on must be a list`);

package/vendor/skills/archgen/scripts/verify-plan.mjs

@@ -11,7 +11,7 @@ import { checkPlanCoverage } from './lib/plan-coverage.mjs';
 
 const [, , file, ...rest] = process.argv;
 const planIdx = rest.indexOf('--plan');
-if (!file || planIdx < 0) {
+if (!file || planIdx < 0 || !rest[planIdx + 1]) {
   console.error('usage: verify-plan.mjs <tasks.yaml> --plan <plans-dir>');
   process.exit(2);
 }
@@ -35,10 +35,13 @@ if (issues.length === 0) {
     if (cycle.length) issues.push(`dependency cycle: ${cycle.join(' -> ')}`);
 
     // Every task must carry acceptance criteria — the verifier refuses work
-    // that cannot be objectively checked later.
+    // that cannot be objectively checked later. Entries must be non-blank
+    // strings: whitespace-only or empty entries are placeholders, not criteria.
     for (const t of tasks) {
       if (!Array.isArray(t.acceptance) || t.acceptance.length === 0) {
         issues.push(`task '${t.id}' has no acceptance criteria`);
+      } else if (t.acceptance.some((a) => typeof a !== 'string' || a.trim() === '')) {
+        issues.push(`task '${t.id}' has empty or whitespace-only acceptance criteria`);
       }
       if (!Array.isArray(t.file_ownership) || t.file_ownership.length === 0) {
         issues.push(`task '${t.id}' has empty file_ownership`);
@@ -55,8 +58,10 @@ if (issues.length === 0) {
 
     issues.push(...checkPlanCoverage(planDir, tasks));
   } catch (e) {
+    // Exotic inputs must surface as a clean ISSUES verdict, never a raw stack:
+    // the verifier is a gate, and gates report findings, not crashes.
     if (e instanceof GraphError) issues.push(e.message);
-    else throw e;
+    else issues.push(`internal check failure: ${e?.message ?? String(e)}`);
   }
 }