mandrel 1.57.0

package/.agents/scripts/lint-label-vocabulary.js

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+/* node:coverage ignore file */
+
+/**
+ * lint-label-vocabulary.js — enforce that GitHub label tokens cited in
+ * `.agents/docs/SDLC.md` and every `*.md` under `.agents/workflows/` use the
+ * canonical
+ * `<axis>::<value>` separator established by
+ * `.agents/scripts/lib/label-constants.js`.
+ *
+ * Why this exists (Tech Spec F9, Epic #2880): the framework's label
+ * vocabulary is the contract between docs and the runtime. A typo such
+ * as `type/epic` (the original F9 finding at epic-plan.md:49) drifts
+ * silently because nothing reads doc prose against the constants file.
+ * This lint closes that gap by failing CI on any inline code span that
+ * cites a known axis with the wrong separator.
+ *
+ * Scope:
+ *   - Files scanned: `.agents/docs/SDLC.md` plus every `*.md` under
+ *     `.agents/workflows/`.
+ *   - Tokens scanned: inline backtick code spans only (e.g. `type/epic`).
+ *     Prose mentions like "planning/audit metadata" are intentionally
+ *     ignored — only fenced citations are treated as label references.
+ *   - Axes recognized: the union of namespaces exported from
+ *     `lib/label-constants.js` (`agent`, `type`, `status`, `context`,
+ *     `acceptance`, `meta`, `planning`) plus the persona prefix.
+ *   - Violation shape: any axis token using a separator other than `::`
+ *     (e.g. `/`, `:`, `-`). False-positive risk is low because the axes
+ *     are project-specific identifiers, not common English words.
+ *
+ * Exit codes:
+ *   0 — clean.
+ *   1 — at least one violation; offending file + line printed to stderr.
+ *
+ * Ships as part of `npm run lint` via `.agents/scripts/run-lint.js`.
+ */
+
+import { readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { runAsCli } from './lib/cli-utils.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+const DEFAULT_SCAN_TARGETS = Object.freeze([
+  path.join(REPO_ROOT, '.agents', 'docs', 'SDLC.md'),
+  path.join(REPO_ROOT, '.agents', 'workflows'),
+]);
+
+/**
+ * Known label-axis prefixes. Each entry corresponds to a namespace
+ * exported from `.agents/scripts/lib/label-constants.js`. The list is
+ * hard-coded rather than introspected so the lint stays a pure file
+ * walk with no module import side effects.
+ *
+ * Maintainers: when a new label axis lands in `label-constants.js`, add
+ * its prefix here (without trailing colons). Forgetting to add an axis
+ * makes the lint silently lenient for that namespace — the tests in
+ * `tests/contract/lint/label-vocabulary.test.js` lock the canonical
+ * set against drift.
+ */
+export const KNOWN_AXES = Object.freeze([
+  'agent',
+  'type',
+  'status',
+  'persona',
+  'context',
+  'acceptance',
+  'meta',
+  'planning',
+]);
+
+/**
+ * Walk a directory tree synchronously, yielding absolute paths of files
+ * matching `.md`. Mirrors the walker shape in `check-lifecycle-lint.js`.
+ */
+function* walkMd(dir) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return;
+    throw err;
+  }
+  for (const entry of entries) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walkMd(p);
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      yield p;
+    }
+  }
+}
+
+/**
+ * Resolve a mixed list of file/directory paths into the flat set of
+ * markdown files to scan. Missing paths are silently skipped (the
+ * walker handles ENOENT) so the lint is robust under partial trees.
+ */
+function* resolveTargets(targets) {
+  for (const target of targets) {
+    let stat;
+    try {
+      stat = readdirSync(target, { withFileTypes: true });
+    } catch (err) {
+      if (err.code === 'ENOTDIR') {
+        // it's a file path — yield directly if it's .md
+        if (target.endsWith('.md')) yield target;
+        continue;
+      }
+      if (err.code === 'ENOENT') continue;
+      throw err;
+    }
+    // directory — walk it
+    for (const entry of stat) {
+      const p = path.join(target, entry.name);
+      if (entry.isDirectory()) {
+        yield* walkMd(p);
+      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+        yield p;
+      }
+    }
+  }
+}
+
+/**
+ * Scan a single source string for inline backtick code spans containing
+ * a label-shaped token that uses a non-`::` separator after a known
+ * axis. Returns an array of `{ line, token, axis, separator }`.
+ *
+ * The matcher operates on inline code spans only (single backtick
+ * delimited). Fenced code blocks (```…```) are not stripped because
+ * label citations inside them are still drift signals worth flagging.
+ *
+ * @param {string} src
+ * @param {readonly string[]} [axes]
+ * @returns {Array<{ line: number, token: string, axis: string, separator: string }>}
+ */
+export function findVocabularyViolations(src, axes = KNOWN_AXES) {
+  const violations = [];
+  const lines = src.split('\n');
+  // Match inline code spans: `…` where the content does not include a
+  // newline or another backtick. Greedy enough for label citations,
+  // strict enough to avoid swallowing prose.
+  const codeSpanRe = /`([^`\n]+)`/g;
+  const axisSet = new Set(axes);
+  // Anchored axis-drift check. We only flag a code span when its body,
+  // taken as a whole, has the shape `<axis><sep><value>` where:
+  //   - axis is a known label axis (case-insensitive)
+  //   - sep is one of the non-canonical separators we treat as drift:
+  //     `/` (the original F9 finding) or a single `:` (also wrong).
+  //     Hyphens (`agent-protocol`) are intentionally NOT flagged —
+  //     they collide with legitimate concept slugs and filenames.
+  //   - value is a lowercase identifier (`[a-z][a-z0-9-]*`)
+  //
+  // The whole-body anchor avoids false positives on:
+  //   - `context::acceptance-spec` — canonical label, value contains a
+  //     hyphen but is not at axis position.
+  //   - `<type>/<slug>` — template placeholders.
+  //   - `planning.maxTickets` — config-key paths with `.`.
+  //   - `context.{prdId,techSpecId}` — JS destructure shapes.
+  //   - `agent-protocol.md` — filenames / concept slugs.
+  //
+  // Real drift like `type/epic` matches because the WHOLE body is
+  // `type/epic` (axis 'type', single '/', value 'epic').
+  const driftRe = new RegExp(
+    `^(${axes.join('|')})([/:])([a-z][a-z0-9-]*)$`,
+    'i',
+  );
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    codeSpanRe.lastIndex = 0;
+    let span = codeSpanRe.exec(line);
+    while (span !== null) {
+      const body = span[1];
+      const m = driftRe.exec(body);
+      if (m) {
+        const axis = m[1].toLowerCase();
+        const separator = m[2];
+        if (separator !== '::' && axisSet.has(axis)) {
+          violations.push({
+            line: i + 1,
+            token: body,
+            axis,
+            separator,
+          });
+        }
+      }
+      span = codeSpanRe.exec(line);
+    }
+  }
+  return violations;
+}
+
+/**
+ * Aggregate violations across all target files.
+ *
+ * @param {readonly string[]} targets
+ * @param {{ read?: typeof readFileSync }} [opts]
+ * @returns {Array<{ file: string, line: number, token: string, axis: string, separator: string }>}
+ */
+export function lintLabelVocabulary(
+  targets = DEFAULT_SCAN_TARGETS,
+  { read = readFileSync } = {},
+) {
+  const out = [];
+  for (const file of resolveTargets(targets)) {
+    const src = read(file, 'utf8');
+    for (const v of findVocabularyViolations(src)) {
+      out.push({ file, ...v });
+    }
+  }
+  return out;
+}
+
+async function main() {
+  const violations = lintLabelVocabulary();
+  if (violations.length === 0) {
+    process.stdout.write(
+      '[label-vocabulary] clean: no drift from canonical `<axis>::<value>` separator in scanned docs.\n',
+    );
+    return 0;
+  }
+  for (const v of violations) {
+    process.stderr.write(
+      `[label-vocabulary] ${v.file}:${v.line}\n  token \`${v.token}\` uses '${v.separator}' but axis '${v.axis}' requires canonical '::' separator (see .agents/scripts/lib/label-constants.js).\n`,
+    );
+  }
+  return 1;
+}
+
+await runAsCli(import.meta.url, main, {
+  source: 'lint-label-vocabulary',
+  propagateExitCode: true,
+});

package/.agents/scripts/loc-delta.js

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+/* node:coverage ignore file */
+
+/**
+ * loc-delta.js — Epic-level LOC accounting (Epic #1181 / Story #1441 /
+ * Task #1457).
+ *
+ * Verifies the Skills-migration acceptance criterion: across the four
+ * SSOT directories
+ *   - .agents/scripts/
+ *   - .agents/skills/
+ *   - .agents/workflows/
+ *   - .agents/README.md
+ * the signed line delta between `main` and `HEAD` must be < 0 (the
+ * migration is meant to *retire* code, not add it). Smoke-test files
+ * under `tests/skills/` are intentionally excluded — they exist to pin
+ * the migration, not to be counted against the LOC budget.
+ *
+ * Output: a Markdown-flavoured per-directory breakdown on stdout plus a
+ * single signed total line. Exit 0 iff total < 0; exit 1 otherwise.
+ *
+ * Usage:
+ *   node .agents/scripts/loc-delta.js                 # main...HEAD
+ *   node .agents/scripts/loc-delta.js --base main     # explicit base
+ *   node .agents/scripts/loc-delta.js --json          # machine output
+ */
+
+import { spawnSync } from 'node:child_process';
+
+import { runAsCli } from './lib/cli-utils.js';
+
+const SCOPE_PATHS = [
+  '.agents/scripts/',
+  '.agents/skills/',
+  '.agents/workflows/',
+  '.agents/README.md',
+];
+
+const EXCLUDES = ['tests/skills/'];
+
+function parseArgs(argv) {
+  const out = { base: 'main', head: 'HEAD', json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--base') {
+      out.base = argv[++i];
+    } else if (arg === '--head') {
+      out.head = argv[++i];
+    } else if (arg === '--json') {
+      out.json = true;
+    } else if (arg === '--help' || arg === '-h') {
+      out.help = true;
+    }
+  }
+  return out;
+}
+
+/**
+ * Compute the (added, removed) line counts between `base` and `head`
+ * restricted to the given path. Uses `git diff --numstat` so the parse
+ * is unambiguous (tab-separated, additions in column 1, removals in
+ * column 2, path in column 3). Binary files surface as `-` and are
+ * skipped.
+ */
+export function computeDeltaForPath({ base, head, path: scopePath }) {
+  const range = `${base}...${head}`;
+  const result = spawnSync(
+    'git',
+    ['diff', '--numstat', range, '--', scopePath],
+    { encoding: 'utf8' },
+  );
+  if (result.status !== 0) {
+    throw new Error(
+      `git diff failed for ${scopePath}: ${result.stderr || result.stdout}`,
+    );
+  }
+  let added = 0;
+  let removed = 0;
+  for (const rawLine of result.stdout.split('\n')) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    const parts = line.split('\t');
+    if (parts.length < 3) continue;
+    const [a, r, file] = parts;
+    if (a === '-' || r === '-') continue;
+    if (EXCLUDES.some((ex) => file.startsWith(ex))) continue;
+    added += Number.parseInt(a, 10) || 0;
+    removed += Number.parseInt(r, 10) || 0;
+  }
+  return { added, removed, delta: added - removed };
+}
+
+/**
+ * Compute the per-directory deltas + signed total. Returns a shape that
+ * is friendly both for human rendering and for `--json` consumers.
+ */
+export function computeLocDelta({ base, head } = {}) {
+  const effectiveBase = base ?? 'main';
+  const effectiveHead = head ?? 'HEAD';
+  const perPath = SCOPE_PATHS.map((scopePath) => ({
+    path: scopePath,
+    ...computeDeltaForPath({
+      base: effectiveBase,
+      head: effectiveHead,
+      path: scopePath,
+    }),
+  }));
+  const total = perPath.reduce(
+    (acc, row) => ({
+      added: acc.added + row.added,
+      removed: acc.removed + row.removed,
+      delta: acc.delta + row.delta,
+    }),
+    { added: 0, removed: 0, delta: 0 },
+  );
+  return {
+    base: effectiveBase,
+    head: effectiveHead,
+    excludes: EXCLUDES,
+    perPath,
+    total,
+    pass: total.delta < 0,
+  };
+}
+
+function renderHuman(report) {
+  const lines = [];
+  lines.push('--- loc-delta ---');
+  lines.push(`base=${report.base} head=${report.head}`);
+  lines.push(`excluded prefixes: ${report.excludes.join(', ')}`);
+  lines.push('');
+  lines.push('| Directory | Added | Removed | Net delta |');
+  lines.push('| --- | ---: | ---: | ---: |');
+  for (const row of report.perPath) {
+    const sign = row.delta > 0 ? '+' : '';
+    lines.push(
+      `| ${row.path} | ${row.added} | ${row.removed} | ${sign}${row.delta} |`,
+    );
+  }
+  lines.push('');
+  const sign = report.total.delta > 0 ? '+' : '';
+  lines.push(
+    `Totals: added=${report.total.added} · removed=${report.total.removed} · net=${sign}${report.total.delta}`,
+  );
+  lines.push(
+    report.pass
+      ? 'Result: PASS (net LOC delta is negative)'
+      : 'Result: FAIL (net LOC delta is not negative — Epic acceptance not met)',
+  );
+  return lines.join('\n');
+}
+
+function help() {
+  return `Usage: node .agents/scripts/loc-delta.js [--base <ref>] [--head <ref>] [--json]
+
+Verifies that the signed line delta across the four SSOT directories
+(.agents/scripts/, .agents/skills/, .agents/workflows/, .agents/README.md)
+is negative between <base> (default: main) and <head> (default: HEAD).
+Smoke-test files under tests/skills/ are excluded from the count.
+
+Exit code: 0 iff net delta < 0; 1 otherwise.
+`;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    process.stdout.write(help());
+    return 0;
+  }
+  let report;
+  try {
+    report = computeLocDelta({ base: args.base, head: args.head });
+  } catch (err) {
+    process.stderr.write(`loc-delta: ${err.message}\n`);
+    return 1;
+  }
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  } else {
+    process.stdout.write(`${renderHuman(report)}\n`);
+  }
+  return report.pass ? 0 : 1;
+}
+
+// Direct-CLI guard: drives `main()` through the framework's `runAsCli`
+// helper so the canonical main-guard shape (enforced by
+// `tests/enforcement/cli-wrapper.test.js`) stays intact. When imported
+// by a test, runAsCli is a no-op and the named exports remain reachable.
+runAsCli(
+  import.meta.url,
+  async () => {
+    const code = await main();
+    if (code !== 0) process.exit(code);
+  },
+  {
+    source: 'loc-delta',
+    onError(err) {
+      process.stderr.write(
+        `loc-delta: unexpected error: ${err?.message ?? err}\n`,
+      );
+      process.exit(1);
+    },
+  },
+);