@massa-ai/codex-plugin 1.26.0 → 1.27.0

package/skills/massa-ai/scripts/validate_audit_report.ts

@@ -0,0 +1,382 @@
+#!/usr/bin/env bun
+/**
+ * validate_audit_report.ts - deterministic schema/ID checks for a saved
+ * audit report markdown file (STO-9 top validator pack).
+ *
+ * Replaces the inline "reread the report and eyeball the finding IDs"
+ * checklist prose that used to live in `references/audit-report-io.md` and
+ * the 9 `*-fix.md` workflows with a scripted check, parameterized by report
+ * family:
+ *
+ *   - metadata field presence (common freshness header + per-family extras)
+ *   - PREFIX-N finding-ID format (or `<Area>/<PREFIX>-N` for the
+ *     implementation composite family)
+ *   - Area<->Prefix table membership (implementation family only) - rejects
+ *     unrecognized Areas, mismatched Area/Prefix pairs, and raw `SONAR-*`
+ *     executable IDs
+ *   - finding-ID uniqueness within the report
+ *   - gap-free per-prefix (or per-area) sequencing: N, N+1, N+2, ... with no
+ *     skipped numbers
+ *
+ * Operates only on the saved report markdown - never on the target
+ * codebase - so it stays stack-agnostic. Bun builtins only, zero
+ * dependencies, same heuristic-markdown-inspection style as validate_spec.ts.
+ *
+ * Usage:
+ *   bun skills/massa-ai/scripts/validate_audit_report.ts <report.md> [--family NAME] [--strict]
+ *
+ *   report.md   Path to a saved audit report markdown file.
+ *   --family    One of: architecture | bugs | code-quality | security |
+ *               requirements | tests | maestro | mobile-figma | implementation
+ *               Auto-detected from the report's `Workflow:` metadata line
+ *               when omitted.
+ *   --strict    Treat warnings as errors.
+ *
+ * Exit codes: 0 pass, 1 errors found (or warnings under --strict), 2 usage error.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+
+interface FamilyConfig {
+  workflow: string;
+  /** Single-lens/MFM/MST prefix, or null for the implementation composite family. */
+  prefix: string | null;
+  extraMetadata: string[];
+}
+
+const COMMON_METADATA = [
+  "Date",
+  "Workflow",
+  "ProjectId",
+  "WorkflowSessionId",
+  "Target",
+  "Target Focus",
+  "Scope",
+  "Git Base",
+  "Git Head",
+  "Source Evidence Timestamp",
+];
+
+/** Canonical area/prefix pairs (audit-report-io.md, Source-Qualified Finding IDs). */
+const AREA_PREFIX: Array<{ area: string; prefix: string }> = [
+  { area: "Correctness", prefix: "BUG" },
+  { area: "Architecture", prefix: "ARCH" },
+  { area: "Code Quality", prefix: "CQ" },
+  { area: "Security", prefix: "SEC" },
+  { area: "Requirements", prefix: "REQ" },
+  { area: "Tests", prefix: "TST" },
+];
+
+const FAMILIES: Record<string, FamilyConfig> = {
+  architecture: { workflow: "architecture-audit", prefix: "ARCH", extraMetadata: ["Requirements Source"] },
+  bugs: { workflow: "bugs-audit", prefix: "BUG", extraMetadata: ["Requirements Source"] },
+  "code-quality": { workflow: "code-quality-audit", prefix: "CQ", extraMetadata: ["Requirements Source"] },
+  security: { workflow: "security-audit", prefix: "SEC", extraMetadata: ["Requirements Source"] },
+  requirements: { workflow: "requirements-audit", prefix: "REQ", extraMetadata: ["Requirements Source"] },
+  tests: { workflow: "tests-audit", prefix: "TST", extraMetadata: ["Requirements Source"] },
+  maestro: {
+    workflow: "maestro-audit",
+    prefix: "MST",
+    extraMetadata: ["Scenario Source", "Maestro CLI", "Device/Emulator Readiness"],
+  },
+  "mobile-figma": {
+    workflow: "mobile-figma-audit",
+    prefix: "MFM",
+    extraMetadata: ["Repository Classification", "Figma Source", "Figma Evidence Timestamp", "Requirements Source"],
+  },
+  implementation: { workflow: "implementation-audit", prefix: null, extraMetadata: ["Requirements Source"] },
+};
+
+/** Mirrors Python's str.splitlines(): universal newline split, no trailing empty element. */
+function splitLines(text: string): string[] {
+  if (text === "") return [];
+  const result: string[] = [];
+  const lineBreakRe = /\r\n|\r|\n/g;
+  let start = 0;
+  let match: RegExpExecArray | null;
+  while ((match = lineBreakRe.exec(text)) !== null) {
+    result.push(text.slice(start, match.index));
+    start = match.index + match[0].length;
+  }
+  if (start < text.length) result.push(text.slice(start));
+  return result;
+}
+
+/** Metadata lines live between the `# Title` line and the first `##` heading. */
+function metadataBounds(lines: string[]): [number, number] {
+  let start = 0;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^#\s+\S/.test(lines[i]!)) {
+      start = i + 1;
+      break;
+    }
+  }
+  let end = lines.length;
+  for (let i = start; i < lines.length; i++) {
+    if (/^##\s+\S/.test(lines[i]!)) {
+      end = i;
+      break;
+    }
+  }
+  return [start, end];
+}
+
+function parseMetadata(lines: string[]): Map<string, string> {
+  const [start, end] = metadataBounds(lines);
+  const fields = new Map<string, string>();
+  const lineRe = /^([A-Za-z][A-Za-z /]*?):\s*(.*)$/;
+  for (let i = start; i < end; i++) {
+    const m = lineRe.exec(lines[i]!.trim());
+    if (m) fields.set(m[1]!.trim(), m[2]!.trim());
+  }
+  return fields;
+}
+
+const PLACEHOLDER_RE = /^<.*>$/;
+
+function checkMetadata(fields: Map<string, string>, required: string[], errors: string[]): void {
+  for (const name of required) {
+    const value = fields.get(name);
+    if (value === undefined || value === "") {
+      errors.push(`missing required metadata field: ${name}`);
+      continue;
+    }
+    if (PLACEHOLDER_RE.test(value)) {
+      // "Requirements Source" and similar fields explicitly allow the
+      // literal value "n/a"; only an unfilled `<template>` token is an error.
+      errors.push(`metadata field '${name}' still has an unfilled template value: ${value}`);
+    }
+  }
+}
+
+interface RawFinding {
+  raw: string;
+  area: string | null;
+  prefix: string;
+  num: number | null;
+  line: number;
+}
+
+const FINDING_HEADER_RE = /^###\s+([^:]+):/;
+/** `<PREFIX>-<N>` (single-lens/MFM/MST) or `<Area>/<PREFIX>-<N>` (implementation composite). */
+const SIMPLE_ID_RE = /^([A-Z][A-Z]*)-(\d+)$/;
+const COMPOSITE_ID_RE = /^([A-Za-z][A-Za-z ]*?)\/([A-Z][A-Z]*)-(\d+)$/;
+
+/** Every `### <id>: <title>` header inside the `## Findings` section, parsed best-effort. */
+function parseFindings(lines: string[], composite: boolean): RawFinding[] {
+  const findings: RawFinding[] = [];
+  let inFindings = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    if (/^##\s+Findings\s*$/.test(line.trim())) {
+      inFindings = true;
+      continue;
+    }
+    if (inFindings && /^##\s+\S/.test(line)) {
+      inFindings = false;
+      continue;
+    }
+    if (!inFindings) continue;
+    const m = FINDING_HEADER_RE.exec(line.trim());
+    if (!m) continue;
+    const idText = m[1]!.trim();
+    if (composite) {
+      const cm = COMPOSITE_ID_RE.exec(idText);
+      if (cm) {
+        findings.push({ raw: idText, area: cm[1]!.trim(), prefix: cm[2]!, num: Number(cm[3]), line: i + 1 });
+      } else {
+        findings.push({ raw: idText, area: null, prefix: "", num: null, line: i + 1 });
+      }
+    } else {
+      const sm = SIMPLE_ID_RE.exec(idText);
+      if (sm) {
+        findings.push({ raw: idText, area: null, prefix: sm[1]!, num: Number(sm[2]), line: i + 1 });
+      } else {
+        findings.push({ raw: idText, area: null, prefix: "", num: null, line: i + 1 });
+      }
+    }
+  }
+  return findings;
+}
+
+function checkFindingIds(
+  findings: RawFinding[],
+  family: FamilyConfig,
+  composite: boolean,
+  errors: string[],
+): void {
+  const seen = new Map<string, number>();
+  const byGroup = new Map<string, number[]>();
+
+  for (const f of findings) {
+    if (f.num === null) {
+      errors.push(`L${f.line}: finding id '${f.raw}' is not in the expected format`);
+      continue;
+    }
+    if (f.prefix.startsWith("SONAR")) {
+      errors.push(`L${f.line}: raw '${f.raw}' is not an executable finding id - normalize SonarQube output to a supported source-qualified id first`);
+      continue;
+    }
+
+    if (composite) {
+      const areaEntry = AREA_PREFIX.find((a) => a.area === f.area);
+      if (!areaEntry) {
+        errors.push(`L${f.line}: '${f.area}' is not a recognized Area (expected one of ${AREA_PREFIX.map((a) => a.area).join(", ")})`);
+        continue;
+      }
+      if (areaEntry.prefix !== f.prefix) {
+        errors.push(`L${f.line}: '${f.raw}' mixes Area '${f.area}' with prefix '${f.prefix}' (expected '${areaEntry.prefix}-N')`);
+        continue;
+      }
+    } else if (family.prefix !== null && f.prefix !== family.prefix) {
+      errors.push(`L${f.line}: '${f.raw}' uses prefix '${f.prefix}', expected '${family.prefix}-N' for this report family`);
+      continue;
+    }
+
+    const key = composite ? `${f.area}/${f.prefix}` : f.prefix;
+    const prior = seen.get(f.raw);
+    if (prior !== undefined) {
+      errors.push(`L${f.line}: duplicate finding id '${f.raw}' (first seen at L${prior})`);
+    } else {
+      seen.set(f.raw, f.line);
+    }
+    if (!byGroup.has(key)) byGroup.set(key, []);
+    byGroup.get(key)!.push(f.num);
+  }
+
+  for (const [key, nums] of byGroup) {
+    const sorted = [...new Set(nums)].sort((a, b) => a - b);
+    for (let expected = 1; expected <= sorted[sorted.length - 1]!; expected++) {
+      if (!sorted.includes(expected)) {
+        errors.push(`${key} finding numbering has a gap: missing ${key}-${expected} (present: ${sorted.map((n) => `${key}-${n}`).join(", ")})`);
+      }
+    }
+  }
+}
+
+function detectFamily(fields: Map<string, string>): string | null {
+  const workflow = fields.get("Workflow");
+  if (!workflow) return null;
+  for (const [name, cfg] of Object.entries(FAMILIES)) {
+    if (cfg.workflow === workflow) return name;
+  }
+  return null;
+}
+
+interface CheckResult {
+  errors: string[];
+  warnings: string[];
+  family: string | null;
+  findingCount: number;
+}
+
+function check(reportPath: string, familyArg: string | null): CheckResult {
+  const text = readFileSync(reportPath, "utf-8");
+  const lines = splitLines(text);
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  const fields = parseMetadata(lines);
+  const family = familyArg ?? detectFamily(fields);
+  if (!family || !(family in FAMILIES)) {
+    errors.push(
+      `could not determine report family (pass --family or a recognized 'Workflow:' value); known families: ${Object.keys(FAMILIES).join(", ")}`,
+    );
+    return { errors, warnings, family: null, findingCount: 0 };
+  }
+  const cfg = FAMILIES[family]!;
+  const composite = cfg.prefix === null;
+
+  checkMetadata(fields, [...COMMON_METADATA, ...cfg.extraMetadata], errors);
+
+  const declaredWorkflow = fields.get("Workflow");
+  if (declaredWorkflow !== undefined && declaredWorkflow !== cfg.workflow) {
+    errors.push(`Workflow field is '${declaredWorkflow}', expected '${cfg.workflow}' for family '${family}'`);
+  }
+
+  const findings = parseFindings(lines, composite);
+  checkFindingIds(findings, cfg, composite, errors);
+
+  return { errors, warnings, family, findingCount: findings.length };
+}
+
+const USAGE = "usage: validate_audit_report.ts [-h] [--family NAME] [--strict] <report.md>";
+const HELP = `${USAGE}
+
+Deterministic schema/ID checks for a saved audit report markdown file.
+
+positional arguments:
+  report.md    Path to a saved audit report markdown file
+
+options:
+  -h, --help     show this help message and exit
+  --family NAME  One of: ${Object.keys(FAMILIES).join(", ")}
+  --strict       Treat warnings as errors`;
+
+interface Args {
+  target: string | null;
+  family: string | null;
+  strict: boolean;
+}
+
+function printUsageError(msg: string): void {
+  process.stderr.write(`${USAGE}\nvalidate_audit_report.ts: error: ${msg}\n`);
+}
+
+function parseArgs(argv: string[]): Args | null {
+  let family: string | null = null;
+  let strict = false;
+  const positionals: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "--family") {
+      if (i + 1 >= argv.length) {
+        printUsageError("argument --family: expected one argument");
+        return null;
+      }
+      family = argv[++i]!;
+    } else if (a.startsWith("--family=")) {
+      family = a.slice("--family=".length);
+    } else if (a === "--strict") {
+      strict = true;
+    } else if (a === "-h" || a === "--help") {
+      console.log(HELP);
+      process.exit(0);
+    } else if (a.startsWith("-") && a !== "-") {
+      printUsageError(`unrecognized arguments: ${a}`);
+      return null;
+    } else {
+      positionals.push(a);
+    }
+  }
+  if (positionals.length !== 1) {
+    printUsageError("exactly one report.md path is required");
+    return null;
+  }
+  return { target: positionals[0]!, family, strict };
+}
+
+function main(argv: string[]): number {
+  const args = parseArgs(argv);
+  if (args === null) return 2;
+
+  if (!args.target || !existsSync(args.target)) {
+    console.error(`validate_audit_report: report not found: ${args.target}`);
+    return 2;
+  }
+
+  const { errors, warnings, family, findingCount } = check(args.target, args.family);
+  for (const w of warnings) console.log(`  WARN  ${w}`);
+  for (const e of errors) console.log(`  ERROR ${e}`);
+  const fail = errors.length > 0 || (warnings.length > 0 && args.strict);
+  console.log(
+    `\nvalidate_audit_report: ${errors.length} error(s), ${warnings.length} warning(s), family=${family ?? "unknown"}, findings=${findingCount} in ${args.target}`,
+  );
+  return fail ? 1 : 0;
+}
+
+if (import.meta.main) {
+  process.exit(main(process.argv.slice(2)));
+}
+
+export { check, FAMILIES, AREA_PREFIX };

package/skills/massa-ai/scripts/validate_design.ts

@@ -0,0 +1,264 @@
+#!/usr/bin/env bun
+/**
+ * validate_design.ts - deterministic closure-gate checks for a feature
+ * design.md (STO-9 top validator pack).
+ *
+ * Turns the spec-driven Design phase's "required sections + every flagged
+ * concern has a mitigation" rule into a checkable pass/fail run, instead of
+ * trusting the model to remember it. Same heuristic-markdown-inspection
+ * style as validate_spec.ts: Bun builtins only, zero dependencies, operates
+ * only on the design.md artifact.
+ *
+ * What it checks:
+ *   ERROR  - a required section is missing (Design Summary, Risks & Concerns,
+ *            Tech Decisions - heading-prefix match, case-insensitive)
+ *   ERROR  - a Risks & Concerns table row has an empty/placeholder Mitigation
+ *            cell (a bare "> None found" section with zero rows is valid -
+ *            it is a real, empty risk register, not an unfilled one)
+ *   WARN   - Risks & Concerns has no table rows and no "None found" marker
+ *            (ambiguous: unfilled template vs. genuinely empty)
+ *
+ * Usage:
+ *   bun skills/massa-ai/scripts/validate_design.ts [target] [--root DIR] [--strict]
+ *
+ *   target    Path to a design.md, a feature directory, or a project root.
+ *             Omitted -> auto-detect the single feature under <root>/.specs/features/.
+ *   --root    Project root that contains .specs/ (default: current dir).
+ *   --strict  Treat warnings as errors.
+ *
+ * Exit codes: 0 pass, 1 errors found (or warnings under --strict), 2 usage error.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+
+const REQUIRED_SECTIONS = ["Design Summary", "Risks & Concerns", "Tech Decisions"];
+const PLACEHOLDER_RE = /^\s*\[.+\]\s*$|^\s*<.+>\s*$|^\s*-?\s*$/;
+
+/** Mirrors os.path.join()'s "./" preservation — see validate_spec.ts for why. */
+function pyJoin(...parts: string[]): string {
+  let result = parts[0] ?? "";
+  for (let i = 1; i < parts.length; i++) {
+    const part = parts[i]!;
+    if (part.startsWith("/")) {
+      result = part;
+    } else if (result === "" || result.endsWith("/")) {
+      result += part;
+    } else {
+      result += `/${part}`;
+    }
+  }
+  return result;
+}
+
+function isFile(p: string): boolean {
+  return existsSync(p) && statSync(p).isFile();
+}
+
+function isDir(p: string): boolean {
+  return existsSync(p) && statSync(p).isDirectory();
+}
+
+function splitLines(text: string): string[] {
+  if (text === "") return [];
+  const result: string[] = [];
+  const lineBreakRe = /\r\n|\r|\n/g;
+  let start = 0;
+  let match: RegExpExecArray | null;
+  while ((match = lineBreakRe.exec(text)) !== null) {
+    result.push(text.slice(start, match.index));
+    start = match.index + match[0].length;
+  }
+  if (start < text.length) result.push(text.slice(start));
+  return result;
+}
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function autodetect(root: string): string | null {
+  const base = pyJoin(root, ".specs", "features");
+  if (!isDir(base)) return null;
+  const features = readdirSync(base)
+    .filter((d) => isFile(pyJoin(base, d, "design.md")))
+    .sort();
+  if (features.length === 1) return pyJoin(base, features[0]!, "design.md");
+  if (features.length === 0) return null;
+  const joined = features.map((f) => pyJoin(base, f, "design.md")).join("\n  ");
+  console.error(`validate_design: multiple features found; pass one explicitly:\n  ${joined}`);
+  process.exit(1);
+}
+
+function resolveDesign(target: string | null, root: string): string | null {
+  if (target) {
+    if (isFile(target)) return target;
+    if (isDir(target)) {
+      const cand = pyJoin(target, "design.md");
+      if (isFile(cand)) return cand;
+      return autodetect(target);
+    }
+    const cand = pyJoin(root, ".specs", "features", target, "design.md");
+    if (isFile(cand)) return cand;
+    return null;
+  }
+  return autodetect(root);
+}
+
+function splitRow(line: string): string[] {
+  const stripped = line.trim().replace(/^\|+/, "").replace(/\|+$/, "");
+  return stripped.split("|").map((c) => c.trim());
+}
+
+function isSeparator(line: string): boolean {
+  return /^\s*\|?[\s:|-]+\|?\s*$/.test(line) && line.includes("-");
+}
+
+/** Return [start, end) for the FIRST `#{1,3} <namePrefix>...` heading (prefix match, case-insensitive). */
+function sectionBoundsPrefix(lines: string[], namePrefix: string): [number, number] | null {
+  const headingRe = new RegExp(`^#{1,3}\\s+${escapeRegExp(namePrefix)}\\b`, "i");
+  let start: number | null = null;
+  for (let i = 0; i < lines.length; i++) {
+    if (headingRe.test(lines[i]!.trim())) {
+      start = i + 1;
+      break;
+    }
+  }
+  if (start === null) return null;
+  let end = lines.length;
+  const nextHeadingRe = /^#{1,3}\s+\S/;
+  for (let j = start; j < lines.length; j++) {
+    if (nextHeadingRe.test(lines[j]!)) {
+      end = j;
+      break;
+    }
+  }
+  return [start, end];
+}
+
+function check(designPath: string): { errors: string[]; warnings: string[] } {
+  const text = readFileSync(designPath, "utf-8");
+  const lines = splitLines(text);
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // 1. Required sections.
+  const bounds = new Map<string, [number, number] | null>();
+  for (const name of REQUIRED_SECTIONS) {
+    const b = sectionBoundsPrefix(lines, name);
+    bounds.set(name, b);
+    if (b === null) {
+      errors.push(`missing required section: ## ${name}`);
+    }
+  }
+
+  // 2. Risks & Concerns: every table row needs a non-empty, non-placeholder
+  //    Mitigation cell. A bare "None found" marker with zero rows is valid.
+  const risksBounds = bounds.get("Risks & Concerns");
+  if (risksBounds) {
+    const [bs, be] = risksBounds;
+    const rows: string[] = [];
+    for (let i = bs; i < be; i++) {
+      if (lines[i]!.trim().startsWith("|")) rows.push(lines[i]!);
+    }
+    const bodyText = lines.slice(bs, be).join("\n").toLowerCase();
+    let data = rows.filter((r) => !isSeparator(r));
+    if (data.length) {
+      const headerCells = splitRow(data[0]!).map((c) => c.toLowerCase());
+      const mitigationIdx = headerCells.findIndex((c) => c.includes("mitigation"));
+      data = data.slice(1); // drop header row
+      for (const r of data) {
+        const cells = splitRow(r);
+        const idx = mitigationIdx >= 0 ? mitigationIdx : cells.length - 1;
+        const mitigation = cells[idx] ?? "";
+        const concern = cells[0] ?? "(unknown concern)";
+        if (!mitigation || PLACEHOLDER_RE.test(mitigation)) {
+          errors.push(`Risks & Concerns row '${concern.slice(0, 50)}' has an empty or unfilled Mitigation cell`);
+        }
+      }
+    } else if (!bodyText.includes("none found")) {
+      warnings.push("Risks & Concerns has no table rows and no 'None found' marker (ambiguous — confirm intentional)");
+    }
+  }
+
+  return { errors, warnings };
+}
+
+const USAGE = "usage: validate_design.ts [-h] [--root ROOT] [--strict] [target]";
+const HELP = `${USAGE}
+
+Closure-gate checks for a feature design.md.
+
+positional arguments:
+  target       Path to a design.md, a feature directory, or a project root
+
+options:
+  -h, --help   show this help message and exit
+  --root ROOT
+  --strict`;
+
+interface Args {
+  target: string | null;
+  root: string;
+  strict: boolean;
+}
+
+function printUsageError(msg: string): void {
+  process.stderr.write(`${USAGE}\nvalidate_design.ts: error: ${msg}\n`);
+}
+
+function parseArgs(argv: string[]): Args | null {
+  let root = ".";
+  let strict = false;
+  const positionals: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "--root") {
+      if (i + 1 >= argv.length) {
+        printUsageError("argument --root: expected one argument");
+        return null;
+      }
+      root = argv[++i]!;
+    } else if (a.startsWith("--root=")) {
+      root = a.slice("--root=".length);
+    } else if (a === "--strict") {
+      strict = true;
+    } else if (a === "-h" || a === "--help") {
+      console.log(HELP);
+      process.exit(0);
+    } else if (a.startsWith("-") && a !== "-") {
+      printUsageError(`unrecognized arguments: ${a}`);
+      return null;
+    } else {
+      positionals.push(a);
+    }
+  }
+  if (positionals.length > 1) {
+    printUsageError(`unrecognized arguments: ${positionals.slice(1).join(" ")}`);
+    return null;
+  }
+  return { target: positionals[0] ?? null, root, strict };
+}
+
+function main(argv: string[]): number {
+  const args = parseArgs(argv);
+  if (args === null) return 2;
+
+  const design = resolveDesign(args.target, args.root);
+  if (!design) {
+    console.error("validate_design: could not locate a design.md. Pass a path or run from the project root.");
+    return 2;
+  }
+
+  const { errors, warnings } = check(design);
+  for (const w of warnings) console.log(`  WARN  ${w}`);
+  for (const e of errors) console.log(`  ERROR ${e}`);
+  const fail = errors.length > 0 || (warnings.length > 0 && args.strict);
+  console.log(`\nvalidate_design: ${errors.length} error(s), ${warnings.length} warning(s) in ${design}`);
+  return fail ? 1 : 0;
+}
+
+if (import.meta.main) {
+  process.exit(main(process.argv.slice(2)));
+}
+
+export { check };

package/skills/massa-ai/workflows/adr.md

@@ -1,8 +1,16 @@
+---
+name: adr
+description: "Use this workflow to record a finalized or being-finalized architecture decision; route open options to rfc and implementation planning to tdd."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### 📜 ADR (Architecture Decision Record)
 
-Use this workflow to record a finalized or being-finalized architecture decision. Do not use it to decide among open options; route undecided proposals to `workflows/rfc.md`. Do not use it for implementation planning; route that to `workflows/tdd.md`.
+Record a finalized or being-finalized architecture decision. Not for deciding among open options — route undecided proposals to `workflows/rfc.md`. Not for implementation planning — route that to `workflows/tdd.md`.
 
-Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
 1. Resolve/reuse `projectId` and `workflowSessionId`: `adr-[entity]`.
 2. Load shared references:
@@ -13,21 +21,21 @@ Before the first substantive read, load `references/project-context.md` and run
 4. Gather source context using `references/adr-authoring.md`:
    - Use explicitly provided Markdown files and prompt context first.
    - Use ADR templates, PRDs, and RFCs from Markdown or Atlassian MCP when provided.
-   - Use optional complementary-stack ADRs from Markdown or Atlassian MCP as cross-stack context only when they affect contracts, constraints, dependencies, risks, or links.
-   - Use optional same-stack example ADRs from Markdown or Atlassian MCP as format/style references only; do not treat their decision context as facts for the new ADR.
-   - Use Figma MCP for UI/UX context only when provided and relevant; otherwise use PRD/RFC/NotebookLM context, or ignore UI/UX when absent.
-   - When supplied Figma links, nodes, desktop selections, or screenshots materially affect the decision, use `workflows/design.md` as optional child context for mobile UI implications only; the ADR still owns the decision record. Screenshots are context-only unless paired with structured Figma evidence.
+   - Use optional complementary-stack ADRs (Markdown or Atlassian MCP) as cross-stack context only when they affect contracts, constraints, dependencies, risks, or links.
+   - Use optional same-stack example ADRs (Markdown or Atlassian MCP) as format/style references only — not as facts for the new ADR.
+   - Use Figma MCP for UI/UX context only when provided and relevant; otherwise fall back to PRD/RFC/NotebookLM context, or skip UI/UX when absent.
+   - When Figma links, nodes, desktop selections, or screenshots materially affect the decision, use `workflows/design.md` as optional child context for mobile UI implications only; the ADR still owns the decision record. Screenshots are context-only unless paired with structured Figma evidence.
    - Use NotebookLM only when the user provides one or more notebook IDs; query each relevant notebook separately, preserve attribution, and do not assume a default notebook.
    - Corroborate with massa-ai search, current repo docs, existing ADRs, and code when the decision depends on current project reality.
 5. Run the ADR readiness gate from `references/adr-authoring.md`:
    - If a needed PRD, RFC, template, decision detail, or source fact is absent, ask for the missing context instead of inventing it.
    - If an RFC is needed but absent and the user does not know the missing context, assume the decision is not made and route to `workflows/rfc.md`.
    - Require a source-backed or user-confirmed title, date, status, context, decision, consequences, links, and supersession status before drafting.
-6. Draft the ADR using the project's provided template when available; otherwise use the format selected through the `references/adr-authoring.md` fallback questions. Keep claims tied to source confidence: confirmed, user-provided, recalled, inferred, or unresolved.
+6. Draft the ADR using the project's template when available; otherwise use the format selected via `references/adr-authoring.md`'s fallback questions. Tie claims to source confidence: confirmed, user-provided, recalled, inferred, or unresolved.
 7. Save the generated ADR using the selected output target:
    - Default: write to the project's standard ADR directory in Default mode. In Plan Mode, propose the path and content without writing.
    - Confluence: when requested and a parent page link is provided, write a child page through Atlassian MCP and report the resulting page link.
    - Fallback: if Confluence was requested without a parent link or Atlassian MCP is unavailable, ask for the parent link or permission to write local Markdown under `.adr/`.
    - Use sequential numbering from the selected local ADR directory when writing Markdown.
-8. At completion, persist the decision via `remember` as a scored `decision` memory with `memory:semantic`, explicitly linking the ADR file path and source context used.
+8. At completion, persist the decision via `remember` as a scored `decision` memory (`memory:semantic`), linking the ADR file path and source context used.
 9. Complete the Evidence Gate from `references/evidence-gate.md`.