archgen-skill 0.0.5 → 0.0.7

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

@@ -1,77 +0,0 @@
-#!/usr/bin/env node
-// impact.mjs — reverse-dependency query: what is affected if <target> changes?
-// Usage: node impact.mjs <tasks.yaml> <taskId-or-artifactPath>
-// stdout: JSON {direct:[taskIds], transitive:[taskIds], artifacts:[paths]}
-import { readFileSync } from 'node:fs';
-import { parseYaml } from './lib/yaml.mjs';
-
-const [, , file, target] = process.argv;
-if (!file || !target) { console.error('usage: impact.mjs <tasks.yaml> <taskId-or-artifactPath>'); process.exit(4); }
-
-let raw;
-try {
-  raw = readFileSync(file, 'utf8');
-} catch {
-  console.error(`cannot read ${file} (missing or unreadable)`);
-  process.exit(4);
-}
-let data;
-try {
-  ({ data } = 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); }
-
-// Resolve target to a seed set of task ids.
-const byId = new Map(tasks.map((t) => [t.id, t]));
-let seeds;
-if (byId.has(target)) {
-  seeds = [target];
-} else {
-  // Artifact-path mode: any task whose artifacts[] or file_ownership[] covers it.
-  seeds = tasks
-    .filter((t) => (t.artifacts ?? []).includes(target) || (t.file_ownership ?? []).includes(target))
-    .map((t) => t.id);
-  if (seeds.length === 0) { console.error(`no task claims '${target}' (not an id, artifact, or ownership glob)`); process.exit(4); }
-}
-
-// Reverse edges: dependents[prereq] = tasks that depend on it.
-const dependents = new Map();
-for (const t of tasks) {
-  for (const dep of t.depends_on ?? []) {
-    if (!dependents.has(dep)) dependents.set(dep, new Set());
-    dependents.get(dep).add(t.id);
-  }
-}
-
-// Direct = immediate dependents of seeds; transitive = everything beyond.
-const direct = new Set();
-const transitive = new Set();
-for (const s of seeds) for (const d of dependents.get(s) ?? []) direct.add(d);
-transitive.clear();
-{
-  const seen = new Set([...seeds, ...direct]);
-  const f = [...direct];
-  while (f.length) {
-    const cur = f.pop();
-    for (const d of dependents.get(cur) ?? []) {
-      if (seen.has(d)) continue;
-      seen.add(d); transitive.add(d); f.push(d);
-    }
-  }
-}
-
-// Artifacts owned by affected tasks (what files the ripple touches).
-const artifacts = new Set();
-for (const id of [...direct, ...transitive]) {
-  for (const a of byId.get(id)?.artifacts ?? []) artifacts.add(a);
-}
-
-console.log(JSON.stringify({
-  direct: [...direct].sort(),
-  transitive: [...transitive].sort(),
-  artifacts: [...artifacts].sort(),
-}, null, 2));

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

@@ -1,222 +0,0 @@
-// graph.mjs — shared dependency-graph utilities for archgen scripts.
-// WHY a lib: validate.mjs, next-tasks.mjs and verify-plan.mjs must agree on
-// cycle detection and wave semantics; three copies would drift (Metis finding).
-
-/** True iff `t` is a mapping object (not null, not an array, not a scalar). */
-function isTaskMapping(t) {
-  return t !== null && typeof t === 'object' && !Array.isArray(t);
-}
-
-/** Build adjacency (prerequisite → dependents) + reverse maps from tasks.
- * Normative semantics: depends_on lists PREREQUISITE ids; a task is ready iff
- * every prerequisite is done; wave 1 = empty depends_on.
- * Entries must be mappings with a non-empty string id — anything else is a
- * GraphError naming the index, so consumers exit with a clean contract code
- * instead of an uncaught TypeError on malformed tasks.yaml shapes. */
-export function buildGraph(tasks) {
-  /** @type {Map<string, string[]>} prereq -> [dependent ids] */
-  const dependents = new Map();
-  /** @type {Map<string, string[]>} id -> prerequisite ids */
-  const prerequisites = new Map();
-  const byId = new Map();
-  for (const [i, t] of tasks.entries()) {
-    if (!isTaskMapping(t)) throw new GraphError(`tasks[${i}]: not a mapping (task entries must be 'key: value' mappings)`);
-    if (typeof t.id !== 'string' || t.id.length === 0) throw new GraphError(`tasks[${i}]: missing string 'id' (every task needs a non-empty string id)`);
-    if (byId.has(t.id)) throw new GraphError(`duplicate task id: ${t.id}`);
-    byId.set(t.id, t);
-    prerequisites.set(t.id, Array.isArray(t.depends_on) ? t.depends_on : []);
-  }
-  for (const t of tasks) {
-    for (const dep of prerequisites.get(t.id)) {
-      if (!byId.has(dep)) throw new GraphError(`dangling depends_on reference: '${t.id}' depends on unknown task '${dep}'`);
-      if (!dependents.has(dep)) dependents.set(dep, []);
-      dependents.get(dep).push(t.id);
-    }
-  }
-  return { byId, prerequisites, dependents };
-}
-
-export class GraphError extends Error {}
-
-/** Return an array of ids forming a cycle (empty if acyclic). Iterative DFS. */
-export function findCycle(prerequisites) {
-  const WHITE = 0, GRAY = 1, BLACK = 2;
-  const color = new Map();
-  const parent = new Map();
-  for (const id of prerequisites.keys()) color.set(id, WHITE);
-
-  for (const start of prerequisites.keys()) {
-    if (color.get(start) !== WHITE) continue;
-    const stack = [[start, 0]];
-    color.set(start, GRAY);
-    while (stack.length) {
-      const [id, pi] = stack[stack.length - 1];
-      const deps = prerequisites.get(id);
-      if (pi < deps.length) {
-        stack[stack.length - 1] = [id, pi + 1];
-        const d = deps[pi];
-        if (!color.has(d)) continue; // dangling handled elsewhere
-        if (color.get(d) === GRAY) {
-          // Found a back-edge: reconstruct the cycle path d ← id ← … ← d
-          const cycle = [d];
-          let cur = id;
-          while (cur !== d) { cycle.push(cur); cur = parent.get(cur); }
-          cycle.push(d);
-          return cycle.reverse();
-        }
-        if (color.get(d) === WHITE) { color.set(d, GRAY); parent.set(d, id); stack.push([d, 0]); }
-      } else {
-        color.set(id, BLACK);
-        stack.pop();
-      }
-    }
-  }
-  return [];
-}
-
-/** Topological waves over NOT-DONE tasks.
- * @param {Map<string,any>} byId
- * @param {Map<string,string[]>} prerequisites
- * @returns {{waves: Array<Array<any>>, blockedByFailure: string[]}}
- * Wave membership: every prerequisite is done. Tasks whose TRANSITIVE
- * prerequisites include any failed task are excluded entirely and reported in
- * blockedByFailure (no silent cascades — orchestrator re-plans around them). */
-export function computeWaves(byId, prerequisites) {
-  const done = new Set();
-  const failed = new Set();
-  for (const [id, t] of byId) {
-    if (t.status === 'done') done.add(id);
-    if (t.status === 'failed') failed.add(id);
-  }
-  // Propagate failure transitively.
-  const blockedByFailure = new Set();
-  let changed = true;
-  while (changed) {
-    changed = false;
-    for (const [id, deps] of prerequisites) {
-      if (blockedByFailure.has(id) || failed.has(id)) continue;
-      if (deps.some((d) => failed.has(d) || blockedByFailure.has(d))) {
-        blockedByFailure.add(id); changed = true;
-      }
-    }
-  }
-
-  const remaining = [...byId.keys()].filter((id) =>
-    !done.has(id) && !failed.has(id) && !blockedByFailure.has(id));
-  const waves = [];
-  const satisfied = new Set(done);
-  let frontier = remaining.filter((id) => prerequisites.get(id).every((d) => satisfied.has(d)));
-  const queued = new Set();
-
-  while (frontier.length) {
-    frontier.sort(); // deterministic output for identical inputs
-    waves.push(frontier.map((id) => byId.get(id)));
-    for (const id of frontier) { satisfied.add(id); queued.add(id); }
-    const next = [];
-    for (const id of remaining) {
-      if (queued.has(id) || satisfied.has(id)) continue;
-      if (prerequisites.get(id).every((d) => satisfied.has(d))) next.push(id);
-    }
-    frontier = next;
-  }
-  return { waves, blockedByFailure: [...blockedByFailure].sort() };
-}
-
-/** First ownership conflict inside a single wave, or null.
- * Two rules, both conservative:
- *  1. Literal equality — two tasks must never claim the SAME glob string.
- *  2. Glob intersection — when a '**' is involved, patterns whose non-glob
- *     prefix segments overlap compatibly are flagged (e.g. "src/**" vs a
- *     TypeScript-scoped variant of it). When segment comparison is uncertain
- *     (wildcards), the pair IS flagged: false positives merely force a rename;
- *     false negatives let parallel workers corrupt each other's files.
- */
-export function findOwnershipConflict(wave) {
-  const seen = new Map();
-  const claimed = [];
-  for (const t of wave) {
-    for (const g of t.file_ownership ?? []) {
-      if (seen.has(g)) return { glob: g, a: seen.get(g), b: t.id };
-      for (const prev of claimed) {
-        if (globsMayOverlap(prev.glob, g)) return { glob: g, a: prev.id, b: t.id };
-      }
-      seen.set(g, t.id);
-      claimed.push({ glob: g, id: t.id });
-    }
-  }
-  return null;
-}
-
-/** Conservative may-intersect test for two ownership globs. */
-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
-}
-
-// --- additive (hardening pass): dedup normalization + quality surfacing -----
-
-/** Collapse redundant depends_on entries BEFORE graph construction so no
- * downstream consumer can ever see the same edge twice (idempotency: identical
- * input ⇒ byte-identical output with zero duplicated entities).
- * First occurrence wins; order otherwise preserved. Tasks without an array
- * depends_on pass through untouched.
- * @param {Array<any>} tasks
- * @returns {{tasks: Array<any>, duplicatesCollapsed: number}} */
-export function dedupeDependencies(tasks) {
-  let duplicatesCollapsed = 0;
-  const normalized = tasks.map((t) => {
-    // Malformed entries pass through untouched; buildGraph owns reporting them
-    // (touching t.depends_on here would throw before the contract check runs).
-    if (!isTaskMapping(t) || !Array.isArray(t.depends_on)) return t;
-    const seen = new Set();
-    const deps = [];
-    for (const d of t.depends_on) {
-      if (seen.has(d)) { duplicatesCollapsed++; continue; }
-      seen.add(d);
-      deps.push(d);
-    }
-    return deps.length === t.depends_on.length ? t : { ...t, depends_on: deps };
-  });
-  return { tasks: normalized, duplicatesCollapsed };
-}
-
-/** Data-quality facts computed from parsed data WITHOUT judging them — the
- * verifier owns pass/fail; indexers only surface facts deterministically.
- *  - selfDeps: tasks whose depends_on includes their own id (note: such a task
- *    is also a 1-node cycle, so the CLI cycle gate normally exits 2 first;
- *    the field keeps the shape uniform for lib-level consumers).
- *  - emptyOwnership: missing or empty file_ownership (parallel workers would
- *    have no disjointness contract).
- *  - blankAcceptance: missing or empty acceptance (no objective done-criteria).
- * @param {Array<any>} tasks
- * @returns {{selfDeps: number, emptyOwnership: number, blankAcceptance: number}} */
-export function computeQualityStats(tasks) {
-  let selfDeps = 0;
-  let emptyOwnership = 0;
-  let blankAcceptance = 0;
-  for (const t of tasks) {
-    // Malformed entries are buildGraph's to report; counting them here would
-    // throw on property access before any consumer sees a contract error.
-    if (!isTaskMapping(t)) continue;
-    if (Array.isArray(t.depends_on) && t.depends_on.includes(t.id)) selfDeps++;
-    const own = t.file_ownership;
-    if (!Array.isArray(own) || own.length === 0) emptyOwnership++;
-    const acc = t.acceptance;
-    if (!Array.isArray(acc) || acc.length === 0) blankAcceptance++;
-  }
-  return { selfDeps, emptyOwnership, blankAcceptance };
-}

package/vendor/skills/archgen/scripts/lib/plan-coverage.mjs

@@ -1,32 +0,0 @@
-// plan-coverage.mjs — single shared implementation of plan<->tasks cross-checks.
-// WHY: validate.mjs --plan and verify-plan.mjs must apply IDENTICAL rules
-// (Metis: two implementations of one rule will drift).
-
-import { readdirSync, readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-
-/** @returns {string[]} error findings (empty = coverage OK) */
-export function checkPlanCoverage(planDir, tasks) {
-  const findings = [];
-  if (!existsSync(planDir)) return [`plans dir not found: ${planDir}`];
-  const files = readdirSync(planDir).filter((f) => f.endsWith('.md'));
-  const planText = files.map((f) => readFileSync(join(planDir, f), 'utf8')).join('\n');
-
-  const taskIds = new Set(tasks.map((t) => t.id));
-  // Task ids referenced in plans: bare tokens that match an existing-or-not id pattern.
-  const referenced = new Set();
-  for (const t of taskIds) {
-    const re = new RegExp(`\\b${escapeRe(t)}\\b`);
-    if (re.test(planText)) referenced.add(t);
-  }
-  for (const t of tasks) {
-    if (!referenced.has(t.id)) findings.push(`task '${t.id}' is not mentioned in any plan file under ${planDir}`);
-  }
-  // Inverse: plan mentions ids like TASK-xx not present in tasks.yaml.
-  for (const m of planText.matchAll(/\b[A-Z][A-Z0-9]+-[0-9]+\b/g)) {
-    if (!taskIds.has(m[0])) findings.push(`plan references unknown task id '${m[0]}' (not in tasks.yaml)`);
-  }
-  return findings;
-}
-
-function escapeRe(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }

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

@@ -1,65 +0,0 @@
-// scope.mjs — the single entry gate for plan-graph.mjs and doc-index.mjs.
-//
-// WHY THIS EXISTS: these indexers read whatever tree they are pointed at. An
-// agent following injected instructions in a README, a prompt, or a hostile
-// tasks.yaml could otherwise aim them at arbitrary project source, dotfiles,
-// or home-directory content and have the tooling enumerate it. Pinning every
-// input to `.archgen/<slug>/` guarantees both tools only ever read archgen's
-// own artifact space — nothing else, no escape hatch.
-//
-// resolveSlugInput(rawInput) -> { kind: 'dir'|'tasks', root: <absolute slug dir>, slug: <dirname> }
-//   Rules:
-//   - fs.realpathSync the input first: symlinks are resolved to their target,
-//     so `ln -s ~/secrets .archgen/x` style escapes are defeated (the real
-//     path outside .archgen fails the segment check).
-//   - The REAL path must contain a path segment exactly `.archgen` (segment
-//     equality — `.archgenx/` does not count) such that the target is either
-//     (a) a directory immediately under that `.archgen` segment (the slug
-//     dir), or (b) a file named `tasks.yaml` directly inside such a slug dir.
-//   - Everything else throws ScopeError. Missing/unreadable inputs surface as
-//     the underlying realpath/stat error so callers keep their own messages.
-import { realpathSync, statSync } from 'node:fs';
-import { basename, dirname, sep } from 'node:path';
-
-export class ScopeError extends Error {
-  constructor(input) {
-    super(`'${input}' is outside .archgen scope — plan-graph/doc-index index only .archgen/<slug>/ plans`);
-    this.name = 'ScopeError';
-  }
-}
-
-/** Split an absolute real path into segments, separator-aware on all platforms
- * (win32 accepts both `\` and `/`; posix treats `\` as a normal filename char). */
-function segmentsOf(abs) {
-  return process.platform === 'win32' ? abs.split(/[\\/]+/).filter(Boolean) : abs.split(sep).filter(Boolean);
-}
-
-export function resolveSlugInput(rawInput) {
-  let real;
-  try {
-    real = realpathSync(rawInput); // follows symlinks: judge the TARGET, not the link
-  } catch (e) {
-    e.input = rawInput;
-    throw e; // missing/unreadable: caller renders its own "cannot read" message
-  }
-  const st = statSync(real);
-  const parts = segmentsOf(real);
-
-  // Scan EVERY `.archgen` segment; accept when any of them makes the target an
-  // immediate slug dir (a) or its direct tasks.yaml (b). Last-wins is fine in
-  // practice but any-match is the honest reading of the rule for nested oddities.
-  for (let i = 0; i < parts.length; i++) {
-    if (parts[i] !== '.archgen') continue;
-    const depthFromArchgen = parts.length - 1 - i; // segments after this `.archgen`
-    if (st.isDirectory() && depthFromArchgen === 1) {
-      // (a) `<...>/.archgen/<slug>` — the slug dir itself
-      return { kind: 'dir', root: real, slug: parts[i + 1] };
-    }
-    if (st.isFile() && basename(real) === 'tasks.yaml' && depthFromArchgen === 2) {
-      // (b) `<...>/.archgen/<slug>/tasks.yaml` — direct tasks.yaml mode
-      const root = dirname(real);
-      return { kind: 'tasks', root, slug: basename(root) };
-    }
-  }
-  throw new ScopeError(rawInput);
-}