archgen-skill 0.1.1 → 0.1.2

package/lib/node_modules/archgen-mcp/src/core/tokens.mjs

@@ -0,0 +1,78 @@
+// tokens.mjs — the ONE token estimator.
+//
+// WHY IT LIVES HERE AND NOT ONLY IN internal/: the estimate is now part of
+// the SERVER's output. Every envelope carries what the call cost, and every
+// dispatch brief and worker contract carries what the prompt will cost — so
+// the orchestrator can see the price of its own behaviour instead of
+// discovering it at the end of a run.
+//
+// The repo's QA tool (`internal/tools/context-budget.mjs`) imports THIS one,
+// so the number the CI gate reports and the number the server reports are
+// the same number.
+//
+// Approximation via a BPE-style pre-tokenizer (±10% for English prose,
+// markdown and YAML).
+
+/** CJK + full-width ranges: ~1 token per character. */
+const CJK_RE = /[\u1100-\u11ff\u2e80-\u303f\u3040-\u30ff\u3130-\u318f\u3400-\u4dbf\u4e00-\u9fff\ua960-\ua97f\uac00-\ud7af\uf900-\ufaff\ufe30-\ufe4f\uff00-\uffef]/gu;
+
+/** Alphanumeric runs (letters, marks, numbers) — one "word" to the estimator. */
+const WORD_RE = /[\p{L}\p{M}\p{N}]+/gu;
+
+/**
+ * Estimate the token count of a string.
+ *
+ * @param {string} text
+ * @param {{calibration?: number}} [opts] multiplier on the raw estimate
+ * @returns {number}
+ */
+export function estimateTokens(text, opts = {}) {
+  if (typeof text !== 'string' || text.length === 0) return 0;
+  const calibration = typeof opts.calibration === 'number' && opts.calibration > 0 ? opts.calibration : 1;
+
+  let tokens = 0;
+
+  // CJK first: these characters are \p{L}, so the word regex would swallow
+  // them into long "words" and undercount badly.
+  const cjk = text.match(CJK_RE);
+  if (cjk) tokens += cjk.length;
+
+  // Strip CJK so the latin pass never double-counts it.
+  const latin = text.replace(CJK_RE, ' ');
+
+  // Words: max(1, round(len/4)).
+  const words = latin.match(WORD_RE);
+  if (words) {
+    for (const w of words) {
+      const len = w.length;
+      // Long identifiers/digits pack denser than prose (roughly len/3.5);
+      // short words pack looser. One threshold keeps the model simple and
+      // monotonic in length.
+      tokens += len <= 6 ? 1 : Math.max(1, Math.round(len / (len > 12 ? 3.5 : 4)));
+    }
+  }
+
+  // Symbols: every non-space, non-alphanumeric character is its own token
+  // in practice ("tasks.yaml" -> "tasks" "." "yaml").
+  const symbols = latin.match(/[^\s\p{L}\p{M}\p{N}]/gu);
+  if (symbols) tokens += symbols.length;
+
+  return Math.max(0, Math.round(tokens * calibration));
+}
+
+/**
+ * Estimate the token count of any payload — a string, or anything JSON-able.
+ *
+ * @param {unknown} value
+ * @returns {number}
+ */
+export function estimatePayloadTokens(value) {
+  if (value === null || value === undefined) return 0;
+  if (typeof value === 'string') return estimateTokens(value);
+  if (typeof value === 'number' || typeof value === 'boolean') return estimateTokens(String(value));
+  try {
+    return estimateTokens(JSON.stringify(value) ?? '');
+  } catch {
+    return 0;
+  }
+}

package/lib/node_modules/archgen-mcp/src/core/validator.mjs

@@ -0,0 +1,121 @@
+// validator.mjs — schema / link / cycle validation for tasks.yaml.
+//
+// Extracted verbatim from skill/scripts/validate.mjs (which is deleted in the
+// MCP-first cutover). The logic is unchanged; only the I/O shell differs:
+// argv parsing and process.exit become arguments and a returned report.
+//
+// Semantics preserved:
+//   - warnings are non-fatal
+//   - an unparseable file is a hard INVALID_INPUT
+//   - `--plan` with no value is a usage error, never a silent skip
+import { readFileSync } from 'node:fs';
+import { parseYaml } from './yaml.mjs';
+import { buildGraph, findCycle, GraphError } from './graph.mjs';
+import { checkPlanCoverage } from './plan-coverage.mjs';
+import { invalidInput, ArchgenError } from './errors.mjs';
+
+export const STATUSES = ['pending', 'ready', 'running', 'blocked', 'done', 'failed'];
+export const REQUIRED = ['id', 'title', 'file_ownership'];
+export 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 the task tools cannot address the task.
+export const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+
+/**
+ * Validate a tasks.yaml file.
+ *
+ * @param {string} file absolute path to tasks.yaml
+ * @param {{planDir?: string|null}} [opts] planDir adds plan<->task coverage checks
+ * @returns {{valid: boolean, errors: string[], warnings: string[], counts: {tasks: number, errors: number, warnings: number}}}
+ */
+export function validateTasksYaml(file, opts = {}) {
+  const planDir = opts.planDir ?? null;
+  const errors = [];
+  const warnings = [];
+
+  let raw;
+  try {
+    raw = readFileSync(file, 'utf8');
+  } catch (e) {
+    // A missing or unreadable file is NOT an internal error. The agent is
+    // told to branch on the code, and "the file is not there" is a fact it
+    // can act on — an INTERNAL tells it nothing and hides which path failed.
+    const code = e?.code === 'ENOENT' ? 'NOT_FOUND' : 'INVALID_INPUT';
+    throw new ArchgenError(
+      code,
+      `${code === 'NOT_FOUND' ? 'tasks file not found' : `cannot read tasks file`}: ${file}`,
+      { file },
+    );
+  }
+  let data;
+  try {
+    ({ data } = parseYaml(raw, { filename: file }));
+  } catch (e) {
+    throw invalidInput(String(e?.message ?? e), { file });
+  }
+  const tasks = data?.tasks;
+  if (!Array.isArray(tasks) || tasks.length === 0) {
+    throw invalidInput('missing or empty `tasks:` sequence', { file });
+  }
+
+  // Root-level typo guard: e.g. `task:` instead of `tasks:` would otherwise
+  // silently produce the missing-tasks error with no hint as to why.
+  for (const k of Object.keys(data ?? {})) {
+    if (k !== 'tasks') warnings.push(`unknown root key '${k}' (expected only 'tasks')`);
+  }
+
+  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)`);
+    // 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`);
+    }
+  }
+
+  try {
+    const { prerequisites } = buildGraph(tasks);
+    const cycle = findCycle(prerequisites);
+    if (cycle.length) errors.push(`dependency cycle: ${cycle.join(' -> ')}`);
+  } catch (e) {
+    if (e instanceof GraphError) errors.push(e.message);
+    else throw e;
+  }
+
+  if (planDir) {
+    // Delegate plan<->task coverage checks to the single shared implementation.
+    for (const f of checkPlanCoverage(planDir, tasks).findings) errors.push(f);
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    counts: { tasks: tasks.length, errors: errors.length, warnings: warnings.length },
+  };
+}

package/lib/node_modules/archgen-mcp/src/core/verifier.mjs

@@ -0,0 +1,99 @@
+// verifier.mjs — the VERIFIER gate as an executable check.
+//
+// Extracted verbatim from skill/scripts/verify-plan.mjs (deleted in the
+// MCP-first cutover). This is the DETERMINISTIC FLOOR of the gate: the
+// agent-side verifier adds judgment on top (wave-boundary sanity, objective
+// verifiability of acceptance criteria, code-standards plausibility).
+//
+// A gate reports findings, it never crashes: exotic inputs surface as an
+// ISSUES verdict, not a raw stack trace.
+import { readFileSync } from 'node:fs';
+import { parseYaml } from './yaml.mjs';
+import { buildGraph, findCycle, computeWaves, findOwnershipConflict, GraphError } from './graph.mjs';
+import { checkPlanCoverage } from './plan-coverage.mjs';
+
+/**
+ * Run the deterministic verifier gate.
+ *
+ * @param {string} file absolute path to tasks.yaml
+ * @param {string} planDir absolute path to the plans directory
+ * @returns {{verdict: 'APPROVE'|'ISSUES', issues: string[]}}
+ */
+export function verifyPlan(file, planDir) {
+  const issues = [];
+
+  let data;
+  try {
+    ({ data } = parseYaml(readFileSync(file, 'utf8'), { filename: file }));
+  } catch (e) {
+    return { verdict: 'ISSUES', issues: [`unparseable tasks.yaml: ${e.message}`] };
+  }
+  const tasks = data?.tasks;
+  if (!Array.isArray(tasks)) issues.push('missing tasks: sequence');
+
+  if (issues.length === 0) {
+    try {
+      const { byId, prerequisites } = buildGraph(tasks);
+      const cycle = findCycle(prerequisites);
+      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. 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`);
+        }
+      }
+
+      if (!issues.length) {
+        const { waves } = computeWaves(byId, prerequisites);
+        for (const wave of waves) {
+          const conflict = findOwnershipConflict(wave);
+          if (conflict) {
+            issues.push(`same-wave ownership overlap: '${conflict.glob}' on '${conflict.a}' and '${conflict.b}'`);
+          }
+        }
+      }
+
+      issues.push(...checkPlanCoverage(planDir, tasks).findings);
+    } catch (e) {
+      if (e instanceof GraphError) issues.push(e.message);
+      else issues.push(`internal check failure: ${e?.message ?? String(e)}`);
+    }
+  }
+
+  return { verdict: issues.length ? 'ISSUES' : 'APPROVE', issues };
+}
+
+/**
+ * Plan<->task coverage on its own (the `coverage` action of archgen_plan).
+ *
+ * @param {string} file absolute path to tasks.yaml
+ * @param {string} planDir absolute path to the plans directory
+ * @returns {{covered: string[], uncovered: string[], findings: string[]}}
+ */
+export function planCoverage(file, planDir) {
+  let data;
+  try {
+    ({ data } = parseYaml(readFileSync(file, 'utf8'), { filename: file }));
+  } catch (e) {
+    return { covered: [], uncovered: [], findings: [`unparseable tasks.yaml: ${e.message}`] };
+  }
+  const tasks = Array.isArray(data?.tasks) ? data.tasks : [];
+  const { findings, referenced, mentionedInTasks } = checkPlanCoverage(planDir, tasks);
+  const covered = [];
+  const uncovered = [];
+  for (const t of tasks) {
+    const id = String(t?.id ?? '');
+    if (!id) continue;
+    const mentioned = referenced.has(id) || mentionedInTasks.has(id);
+    (mentioned ? covered : uncovered).push(id);
+  }
+  return { covered, uncovered, findings };
+}

package/lib/node_modules/archgen-mcp/src/core/wave-resolver.mjs

@@ -0,0 +1,116 @@
+// wave-resolver.mjs — topological wave resolver for tasks.yaml.
+//
+// Extracted verbatim from skill/scripts/next-tasks.mjs (deleted in the
+// MCP-first cutover).
+//
+// Exit-code semantics become typed errors:
+//   2 -> CYCLE             (dependency cycle)
+//   3 -> OWNERSHIP_CONFLICT (same-wave file_ownership overlap)
+//   4 -> INVALID_INPUT     (missing/invalid file)
+import { readFileSync } from 'node:fs';
+import { parseYaml } from './yaml.mjs';
+import { buildGraph, findCycle, computeWaves, findOwnershipConflict, GraphError } from './graph.mjs';
+import { cycle, invalidInput, ownershipConflict } from './errors.mjs';
+
+/**
+ * Resolve the executable waves of a task graph.
+ *
+ * @param {string} file absolute path to tasks.yaml
+ * @returns {{waves: Array<Array<{id: string, title: string, status: string, file_ownership: string[]}>>, blockedByFailure: string[]}}
+ */
+export function resolveWaves(file) {
+  let raw;
+  try {
+    raw = readFileSync(file, 'utf8');
+  } catch {
+    throw invalidInput(`cannot read ${file} (missing or unreadable)`, { file });
+  }
+  let data;
+  try {
+    ({ data } = parseYaml(raw, { filename: file }));
+  } catch (e) {
+    throw invalidInput(String(e.message ?? e), { file });
+  }
+  const tasks = data?.tasks;
+  if (!Array.isArray(tasks)) throw invalidInput(`${file}: missing 'tasks:' sequence`, { file });
+
+  let byId;
+  let prerequisites;
+  try {
+    ({ byId, prerequisites } = buildGraph(tasks));
+  } catch (e) {
+    if (e instanceof GraphError) throw invalidInput(e.message, { file });
+    throw e;
+  }
+
+  const cyclePath = findCycle(prerequisites);
+  if (cyclePath.length) {
+    throw cycle(`dependency cycle detected: ${cyclePath.join(' -> ')}`, { file, cycle: cyclePath });
+  }
+
+  const { waves, blockedByFailure } = computeWaves(byId, prerequisites);
+
+  for (const wave of waves) {
+    const conflict = findOwnershipConflict(wave);
+    if (conflict) {
+      throw ownershipConflict(
+        `file_ownership conflict in same wave: glob '${conflict.glob}' claimed by '${conflict.a}' and '${conflict.b}'`,
+        { file, glob: conflict.glob, a: conflict.a, b: conflict.b },
+      );
+    }
+  }
+
+  return {
+    waves: waves.map((w) =>
+      w.map((t) => ({
+        id: t.id,
+        title: t.title,
+        status: t.status,
+        file_ownership: t.file_ownership,
+      }))),
+    blockedByFailure,
+  };
+}
+
+/**
+ * Flat, filtered view of the task graph (the `list` action of archgen_tasks).
+ *
+ * @param {string} file absolute path to tasks.yaml
+ * @param {{status?: string|null, module?: string|null}} [opts]
+ * @returns {{tasks: Array<Record<string, unknown>>, total: number}}
+ */
+export function listTasks(file, opts = {}) {
+  const { status = null, module = null } = opts;
+  let raw;
+  try {
+    raw = readFileSync(file, 'utf8');
+  } catch {
+    throw invalidInput(`cannot read ${file} (missing or unreadable)`, { file });
+  }
+  let data;
+  try {
+    ({ data } = parseYaml(raw, { filename: file }));
+  } catch (e) {
+    throw invalidInput(String(e.message ?? e), { file });
+  }
+  const tasks = Array.isArray(data?.tasks) ? data.tasks : [];
+  const filtered = tasks.filter((t) => {
+    if (status && (t?.status ?? 'pending') !== status) return false;
+    if (module) {
+      const owned = Array.isArray(t?.file_ownership) ? t.file_ownership.join(' ') : '';
+      if (!owned.includes(module)) return false;
+    }
+    return true;
+  });
+  return {
+    tasks: filtered.map((t) => ({
+      id: t?.id ?? null,
+      title: t?.title ?? null,
+      status: t?.status ?? 'pending',
+      depends_on: Array.isArray(t?.depends_on) ? t.depends_on : [],
+      file_ownership: Array.isArray(t?.file_ownership) ? t.file_ownership : [],
+      artifacts: Array.isArray(t?.artifacts) ? t.artifacts : [],
+    })),
+    total: filtered.length,
+  };
+}