@massa-ai/codex-plugin 1.34.0 → 1.35.1

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

@@ -0,0 +1,335 @@
+#!/usr/bin/env bun
+/**
+ * check_fix_closure.ts - deterministic gate: a `*-fix` workflow's Fix Closure
+ * Report is committed, complete, and evidence-backed before Propose/Evidence
+ * Gate (the fix-family analogue of check_specs_delivered.ts).
+ *
+ * Three conjunctive checks against the closure contract in
+ * `references/audit-report-io.md` (Fix Closure Report Contract):
+ *
+ *   1. The closure file exists, is tracked on HEAD, and is porcelain-clean
+ *      (not modified-but-uncommitted).
+ *   2. Every finding ID selected from the source audit report has a Closure
+ *      Matrix row with a terminal status (`fixed|blocked|deferred|skipped`).
+ *      The selected set is every finding in the source report, or the subset
+ *      named via --findings. The source report path comes from the closure
+ *      file's `Source Report:` metadata line, or --report.
+ *   3. No `fixed` row carries a placeholder Command/Artifact or Result cell
+ *      (empty, `<template>`, `TBD`, `-`, or `n/a`).
+ *
+ * Reuses the `### <PREFIX>-N:` finding parser exported by
+ * validate_audit_report.ts, so the two scripts cannot drift on ID shape.
+ * Bun builtins only. Run from the project root, or pass --root.
+ *
+ * Usage:
+ *   bun skills/massa-ai/scripts/check_fix_closure.ts <closure.md> --family <family>
+ *        [--report <report.md>] [--findings ID,ID,...] [--root DIR]
+ *
+ * Exit codes: 0 pass, 1 closure incomplete/dirty/placeholder (reasons named),
+ *             2 usage/git error.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+
+import { FAMILIES, parseFindings, splitLines } from "./validate_audit_report.ts";
+
+const TERMINAL_STATUSES = new Set(["fixed", "blocked", "deferred", "skipped"]);
+const PLACEHOLDER_CELL_RE = /^(<.*>|TBD|-|n\/a)?$/i;
+
+function runGit(args: string[], root: string): { exitCode: number; stdout: string; stderr: string } {
+  try {
+    const proc = Bun.spawnSync(["git", ...args], { cwd: root, stdout: "pipe", stderr: "pipe" });
+    return { exitCode: proc.exitCode ?? -1, stdout: proc.stdout.toString(), stderr: proc.stderr.toString() };
+  } catch {
+    console.error("check_fix_closure: git not found on PATH");
+    process.exit(2);
+  }
+}
+
+interface ClosureRow {
+  findingId: string;
+  status: string;
+  commandArtifact: string;
+  result: string;
+  line: number;
+}
+
+/** Parse `Source Report:` and `Finding Selector:` metadata lines. */
+function parseClosureMetadata(lines: string[]): Map<string, string> {
+  const fields = new Map<string, string>();
+  const lineRe = /^([A-Za-z][A-Za-z ./]*?):\s*(.*)$/;
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (/^##\s+\S/.test(line)) break;
+    const m = lineRe.exec(line);
+    if (m) fields.set(m[1]!.trim(), m[2]!.trim());
+  }
+  return fields;
+}
+
+/** Split a markdown table row into trimmed cells (drops leading/trailing empties). */
+function tableCells(line: string): string[] {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith("|")) return [];
+  const cells = trimmed.split("|").map((c) => c.trim());
+  // First and last entries are the empty strings outside the outer pipes.
+  return cells.slice(1, cells.length - 1);
+}
+
+/** Rows of the `## Closure Matrix` table, resolved by header-name lookup. */
+function parseClosureMatrix(lines: string[], errors: string[]): ClosureRow[] {
+  let inMatrix = false;
+  let header: string[] | null = null;
+  const rows: ClosureRow[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    if (/^##\s+Closure Matrix\s*$/.test(line.trim())) {
+      inMatrix = true;
+      continue;
+    }
+    if (inMatrix && /^##\s+\S/.test(line)) break;
+    if (!inMatrix) continue;
+    const cells = tableCells(line);
+    if (cells.length === 0) continue;
+    if (header === null) {
+      header = cells;
+      continue;
+    }
+    if (cells.every((c) => /^[-: ]*$/.test(c))) continue; // separator row
+    const col = (name: string): string => {
+      const idx = header!.findIndex((h) => h.toLowerCase() === name.toLowerCase());
+      return idx >= 0 && idx < cells.length ? cells[idx]! : "";
+    };
+    rows.push({
+      findingId: col("Finding ID"),
+      status: col("Status").toLowerCase(),
+      commandArtifact: col("Command/Artifact"),
+      result: col("Result"),
+      line: i + 1,
+    });
+  }
+  if (header !== null) {
+    for (const required of ["Finding ID", "Status", "Command/Artifact", "Result"]) {
+      if (!header.some((h) => h.toLowerCase() === required.toLowerCase())) {
+        errors.push(`Closure Matrix header is missing the '${required}' column`);
+      }
+    }
+  } else {
+    errors.push("no '## Closure Matrix' table found in the closure report");
+  }
+  return rows;
+}
+
+interface CheckResult {
+  errors: string[];
+  selected: string[];
+}
+
+function check(
+  root: string,
+  closurePath: string,
+  family: string,
+  reportArg: string | null,
+  findingsArg: string[] | null,
+): CheckResult {
+  const errors: string[] = [];
+
+  // 1. Committed and clean.
+  const relClosure = relative(root, resolve(closurePath)).split(sep).join("/");
+  const tracked = runGit(["ls-tree", "-r", "--name-only", "HEAD"], root);
+  if (tracked.exitCode !== 0) {
+    console.error(`check_fix_closure: git ls-tree failed: ${tracked.stderr.trim()}`);
+    process.exit(2);
+  }
+  if (!splitLines(tracked.stdout).includes(relClosure)) {
+    errors.push(`closure report not tracked on HEAD: ${relClosure}`);
+  }
+  const porcelain = runGit(["status", "--porcelain", "--", relClosure], root);
+  for (const ln of splitLines(porcelain.stdout).filter((l) => l.trim() !== "")) {
+    errors.push(`closure report uncommitted/modified: ${ln.trim()}`);
+  }
+
+  const closureText = readFileSync(closurePath, "utf-8");
+  const closureLines = splitLines(closureText);
+  const meta = parseClosureMetadata(closureLines);
+
+  // 2. Every selected source-report finding has a terminal-status row.
+  const reportPath = reportArg ?? meta.get("Source Report") ?? null;
+  const composite = family === "implementation";
+  let selected: string[] = [];
+  if (findingsArg !== null) {
+    selected = findingsArg;
+  } else if (reportPath !== null && reportPath !== "") {
+    const absReport = isAbsolute(reportPath) ? reportPath : join(root, reportPath);
+    if (!existsSync(absReport)) {
+      errors.push(`source report not found: ${reportPath}`);
+    } else {
+      const reportLines = splitLines(readFileSync(absReport, "utf-8"));
+      selected = parseFindings(reportLines, composite)
+        .filter((f) => f.num !== null)
+        .map((f) => f.raw);
+    }
+  } else {
+    errors.push("no source report: closure has no 'Source Report:' line and no --report/--findings was given");
+  }
+
+  const rows = parseClosureMatrix(closureLines, errors);
+  const rowById = new Map<string, ClosureRow>();
+  for (const row of rows) {
+    if (row.findingId !== "") rowById.set(row.findingId, row);
+  }
+
+  for (const id of selected) {
+    const row = rowById.get(id);
+    if (row === undefined) {
+      errors.push(`selected finding has no Closure Matrix row: ${id}`);
+      continue;
+    }
+    if (!TERMINAL_STATUSES.has(row.status)) {
+      errors.push(
+        `L${row.line}: finding ${id} has non-terminal status '${row.status}' (expected fixed|blocked|deferred|skipped)`,
+      );
+    }
+  }
+
+  // 3. No fixed row with placeholder evidence.
+  for (const row of rows) {
+    if (row.status !== "fixed") continue;
+    if (PLACEHOLDER_CELL_RE.test(row.commandArtifact)) {
+      errors.push(`L${row.line}: fixed finding ${row.findingId} has a placeholder Command/Artifact cell`);
+    }
+    if (PLACEHOLDER_CELL_RE.test(row.result)) {
+      errors.push(`L${row.line}: fixed finding ${row.findingId} has a placeholder Result cell`);
+    }
+  }
+
+  return { errors, selected };
+}
+
+const USAGE =
+  "usage: check_fix_closure.ts [-h] --family NAME [--report PATH] [--findings IDS] [--root ROOT] closure.md";
+const HELP = `${USAGE}
+
+Gate: the Fix Closure Report is committed, complete, and evidence-backed
+before Propose/Evidence Gate (references/audit-report-io.md, Fix Closure
+Report Contract).
+
+positional arguments:
+  closure.md      Path to the Fix Closure Report markdown file
+
+options:
+  -h, --help      show this help message and exit
+  --family NAME   One of: ${Object.keys(FAMILIES).join(", ")}
+  --report PATH   Source audit report (default: the closure's 'Source Report:' line)
+  --findings IDS  Comma-separated finding IDs (default: every finding in the source report)
+  --root ROOT     Project root (default: current dir)`;
+
+interface Args {
+  closure: string;
+  family: string;
+  report: string | null;
+  findings: string[] | null;
+  root: string;
+}
+
+function printUsageError(msg: string): void {
+  process.stderr.write(`${USAGE}\ncheck_fix_closure.ts: error: ${msg}\n`);
+}
+
+function parseArgs(argv: string[]): Args | null {
+  let family: string | null = null;
+  let report: string | null = null;
+  let findings: string[] | null = null;
+  let root = ".";
+  const positionals: string[] = [];
+  const takeValue = (i: number, name: string): string | null => {
+    if (i + 1 >= argv.length) {
+      printUsageError(`argument ${name}: expected one argument`);
+      return null;
+    }
+    return argv[i + 1]!;
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "--family") {
+      const v = takeValue(i, "--family");
+      if (v === null) return null;
+      family = v;
+      i++;
+    } else if (a.startsWith("--family=")) {
+      family = a.slice("--family=".length);
+    } else if (a === "--report") {
+      const v = takeValue(i, "--report");
+      if (v === null) return null;
+      report = v;
+      i++;
+    } else if (a.startsWith("--report=")) {
+      report = a.slice("--report=".length);
+    } else if (a === "--findings") {
+      const v = takeValue(i, "--findings");
+      if (v === null) return null;
+      findings = v.split(",").map((s) => s.trim()).filter((s) => s !== "");
+      i++;
+    } else if (a.startsWith("--findings=")) {
+      findings = a
+        .slice("--findings=".length)
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s !== "");
+    } else if (a === "--root") {
+      const v = takeValue(i, "--root");
+      if (v === null) return null;
+      root = v;
+      i++;
+    } else if (a.startsWith("--root=")) {
+      root = a.slice("--root=".length);
+    } 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 closure.md path is required");
+    return null;
+  }
+  if (family === null) {
+    printUsageError("the following arguments are required: --family");
+    return null;
+  }
+  if (!(family in FAMILIES)) {
+    printUsageError(`unknown family '${family}' (known: ${Object.keys(FAMILIES).join(", ")})`);
+    return null;
+  }
+  return { closure: positionals[0]!, family, report, findings, root };
+}
+
+function main(argv: string[]): number {
+  const args = parseArgs(argv);
+  if (args === null) return 2;
+  const root = resolve(args.root);
+  const closurePath = isAbsolute(args.closure) ? args.closure : join(root, args.closure);
+  if (!existsSync(closurePath)) {
+    console.error(`check_fix_closure: closure report not found: ${args.closure}`);
+    return 2;
+  }
+
+  const { errors, selected } = check(root, closurePath, args.family, args.report, args.findings);
+
+  for (const e of errors) console.log(`  ERROR ${e}`);
+  console.log(`\ncheck_fix_closure: checked ${selected.length} selected finding(s):`);
+  for (const id of selected) console.log(`  - ${id}`);
+  console.log(`check_fix_closure: ${errors.length} error(s)`);
+  return errors.length ? 1 : 0;
+}
+
+if (import.meta.main) {
+  process.exit(main(process.argv.slice(2)));
+}
+
+export { check, parseClosureMatrix, tableCells };

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

@@ -26,7 +26,13 @@
  * --root.
  *
  * Usage:
- *   bun skills/massa-ai/scripts/check_specs_delivered.ts <feature> [--root DIR]
+ *   bun skills/massa-ai/scripts/check_specs_delivered.ts <feature> [--root DIR] [--kind KIND]
+ *
+ * --kind selects the artifact shape gated (default `feature`, byte-identical
+ * to the historical behavior): `quick` gates .specs/quick/<slug>/
+ * TASK.md+SUMMARY.md, `debug` gates .specs/debug/<slug>/REPORT.md, `refactor`
+ * gates .specs/refactors/<slug>/CHARACTERIZATION.md (+ present PLAN/SENSOR).
+ * Non-feature kinds do not require the project STATE files.
  *
  * Exit codes: 0 all required paths clean + tracked, 1 a required path is dirty,
  *             untracked, or not tracked on HEAD (paths named), 2 usage/git error.
@@ -46,6 +52,25 @@ const STATE_FILES = [
   join(".specs", "project", "FEATURES.json"),
 ];
 
+interface KindConfig {
+  /** Slug parent dir under .specs/, e.g. ["features"]. */
+  dir: string[];
+  required: string[];
+  optional: string[];
+  /** Whether the project STATE files are part of the gate. */
+  stateFiles: boolean;
+}
+
+// `feature` is the default and must stay byte-identical to the historical
+// behavior (frozen pyts-golden corpus). The non-feature kinds gate the light
+// workflows' durable artifacts and do NOT require the project STATE files.
+const KINDS: Record<string, KindConfig> = {
+  feature: { dir: ["features"], required: FEATURE_REQUIRED, optional: FEATURE_OPTIONAL, stateFiles: true },
+  quick: { dir: ["quick"], required: ["TASK.md", "SUMMARY.md"], optional: [], stateFiles: false },
+  debug: { dir: ["debug"], required: ["REPORT.md"], optional: [], stateFiles: false },
+  refactor: { dir: ["refactors"], required: ["CHARACTERIZATION.md"], optional: ["PLAN.md", "SENSOR.md"], stateFiles: false },
+};
+
 /** Mirrors Python's str.splitlines(): universal newline split, no trailing empty element. */
 function splitLines(text: string): string[] {
   if (text === "") return [];
@@ -92,39 +117,41 @@ function trackedOnHead(root: string): Set<string> {
   return new Set(splitLines(out));
 }
 
-function resolveFeatureDir(root: string, feature: string): string {
+function resolveFeatureDir(root: string, feature: string, kind: KindConfig): string {
   if (isAbsolute(feature) || feature.includes(sep)) {
     return resolve(feature);
   }
-  return join(root, ".specs", "features", feature);
+  return join(root, ".specs", ...kind.dir, feature);
 }
 
 /** Repo-root-relative, '/'-separated paths this feature must have tracked. */
-function requiredPaths(root: string, feature: string): string[] {
-  const fdir = resolveFeatureDir(root, feature);
+function requiredPaths(root: string, feature: string, kind: KindConfig): string[] {
+  const fdir = resolveFeatureDir(root, feature, kind);
   const fdirRel = relative(root, fdir);
-  const paths = FEATURE_REQUIRED.map((name) => join(fdirRel, name));
+  const paths = kind.required.map((name) => join(fdirRel, name));
   if (existsSync(fdir) && statSync(fdir).isDirectory()) {
-    for (const name of FEATURE_OPTIONAL) {
+    for (const name of kind.optional) {
       const candidate = join(fdir, name);
       if (existsSync(candidate) && statSync(candidate).isFile()) {
         paths.push(join(fdirRel, name));
       }
     }
   }
-  paths.push(...STATE_FILES);
+  if (kind.stateFiles) {
+    paths.push(...STATE_FILES);
+  }
   return paths.map((p) => p.split(sep).join("/"));
 }
 
 /** Return { errors, checked }. errors empty = pass. */
-function check(root: string, feature: string): { errors: string[]; checked: string[] } {
+function check(root: string, feature: string, kind: KindConfig): { errors: string[]; checked: string[] } {
   const errors: string[] = [];
 
   for (const ln of porcelainDirtyPaths(root)) {
     errors.push(`uncommitted/untracked under .specs/: ${ln.trim()}`);
   }
 
-  const paths = requiredPaths(root, feature);
+  const paths = requiredPaths(root, feature, kind);
   const tracked = trackedOnHead(root);
   for (const p of paths) {
     if (!tracked.has(p)) {
@@ -135,21 +162,27 @@ function check(root: string, feature: string): { errors: string[]; checked: stri
   return { errors, checked: paths };
 }
 
-const USAGE = "usage: check_specs_delivered.ts [-h] [--root ROOT] feature";
+const USAGE = "usage: check_specs_delivered.ts [-h] [--root ROOT] [--kind KIND] feature";
 const HELP = `${USAGE}
 
 Gate: .specs/ artifacts committed on the branch before PR (GATE-02).
 
 positional arguments:
-  feature      Feature slug under <root>/.specs/features/, or a direct path
+  feature      Slug under the kind's .specs/ directory, or a direct path
 
 options:
   -h, --help   show this help message and exit
-  --root ROOT  Project root containing .specs/ (default: current dir)`;
+  --root ROOT  Project root containing .specs/ (default: current dir)
+  --kind KIND  One of: ${Object.keys(KINDS).join(", ")} (default: feature)
+               feature  .specs/features/<slug>/  spec.md (+ present phase files) + project STATE files
+               quick    .specs/quick/<slug>/     TASK.md + SUMMARY.md
+               debug    .specs/debug/<slug>/     REPORT.md
+               refactor .specs/refactors/<slug>/ CHARACTERIZATION.md (+ present PLAN.md/SENSOR.md)`;
 
 interface Args {
   feature: string;
   root: string;
+  kind: string;
 }
 
 function printUsageError(msg: string): void {
@@ -158,6 +191,7 @@ function printUsageError(msg: string): void {
 
 function parseArgs(argv: string[]): Args | null {
   let root = ".";
+  let kind = "feature";
   const positionals: string[] = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]!;
@@ -169,6 +203,14 @@ function parseArgs(argv: string[]): Args | null {
       root = argv[++i]!;
     } else if (a.startsWith("--root=")) {
       root = a.slice("--root=".length);
+    } else if (a === "--kind") {
+      if (i + 1 >= argv.length) {
+        printUsageError("argument --kind: expected one argument");
+        return null;
+      }
+      kind = argv[++i]!;
+    } else if (a.startsWith("--kind=")) {
+      kind = a.slice("--kind=".length);
     } else if (a === "-h" || a === "--help") {
       console.log(HELP);
       process.exit(0);
@@ -187,7 +229,11 @@ function parseArgs(argv: string[]): Args | null {
     printUsageError(`unrecognized arguments: ${positionals.slice(1).join(" ")}`);
     return null;
   }
-  return { feature: positionals[0]!, root };
+  if (!(kind in KINDS)) {
+    printUsageError(`argument --kind: invalid choice: '${kind}' (choose from ${Object.keys(KINDS).join(", ")})`);
+    return null;
+  }
+  return { feature: positionals[0]!, root, kind };
 }
 
 function main(argv: string[]): number {
@@ -195,7 +241,7 @@ function main(argv: string[]): number {
   if (args === null) return 2;
   const root = resolve(args.root);
 
-  const { errors, checked } = check(root, args.feature);
+  const { errors, checked } = check(root, args.feature, KINDS[args.kind]!);
 
   for (const e of errors) console.log(`  ERROR ${e}`);
   console.log(`\ncheck_specs_delivered: checked ${checked.length} path(s):`);

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

@@ -379,4 +379,5 @@ if (import.meta.main) {
   process.exit(main(process.argv.slice(2)));
 }
 
-export { check, FAMILIES, AREA_PREFIX };
+export { check, FAMILIES, AREA_PREFIX, parseFindings, splitLines };
+export type { RawFinding };

package/skills/massa-ai/workflows/architecture/architecture-fix.md

@@ -3,7 +3,7 @@ name: architecture-fix
 description: "Executes fixes from a saved architecture audit report; not for findings-only review or broad new design work with missing requirements."
 license: MIT
 metadata:
-  version: "1.1.0"
+  version: "1.2.0"
 ---
 
 ### Architecture Fix
@@ -12,7 +12,9 @@ Execute fixes from an architecture audit markdown report only.
 
 Load `references/project-context.md` (intake sweep) before the first substantive read.
 
-Before the first repository mutation, load `references/implementation-delivery.md` (delivery chain: worktree, atomic commits, PR, CI watch, merge gate) and `references/code-annotation.md` (doc blocks, rationale, test coverage). After two consecutive failed fixes on one symptom, stop editing and load `references/root-cause-scripts.md`.
+Before the first repository mutation, load `references/implementation-delivery.md` (delivery chain: worktree, atomic commits, PR, CI watch, merge gate) — its Stage 3 delivery-authorization scope covers one go-ahead through PR creation; force-push/deploy/merge stay separately gated — and `references/code-annotation.md` (doc blocks, rationale, test coverage). After two consecutive failed fixes on one symptom, stop editing and load `references/root-cause-scripts.md`.
+
+**Isolation Gate — before the first file edit:** execute `references/implementation-delivery.md` Stage 0–1 now (fetch base, create the worktree + branch, work inside it) and record the worktree path + branch — or one of Stage 1's two legal skip reasons, verbatim — before any repository mutation.
 
 Not for findings-only architecture review — route to `workflows/architecture/architecture-audit.md`. Not for broad new design work with missing requirements — route to `workflows/spec-driven.md`.
 
@@ -28,6 +30,9 @@ Not for findings-only architecture review — route to `workflows/architecture/a
    - `references/verification-ladder.md` before non-trivial edits
    - `references/context-firewall.md` before inspecting large diffs, dependency graphs, generated reports, or broad search output
    - `references/agent-orchestration.md` only for large/high-risk findings, disjoint implementation slices, or independent verification
+   - `references/discrimination-sensor.md` before marking any Standard+/Spec-driven-sized or high/critical-severity finding `fixed`
+   - `references/knowledge-verification-chain.md` when a fix leans on an external library or API — the trigger is step 8's ports/adapters clause on "external dependency pressure"
+   - `references/brownfield-mapping.md` (Minimum Bar only, Standard+ findings) when step 3's recall returns no hit for the target and no gate command is derivable from the report's evidence; its CONCERNS.md is satisfied by citation when the report's lens evidence already maps the risk surface — cite that evidence rather than deriving CONCERNS.md fresh
 3. `recall` -> load ADRs, known boundaries, coupling patterns, accepted exceptions, rejected refactors, verification recipes, and project constraints for the report target.
 4. Select the architecture audit report with execution focus:
    - Establish the report selector, target focus, and optional finding selector before selecting a report. Target focus can be a module, boundary, flow, files/globs, branch comparison, commit range, symbol/class/function, or explicit whole-repo target.
@@ -63,7 +68,7 @@ Not for findings-only architecture review — route to `workflows/architecture/a
    - Characterize current behavior before moving code with tests, static checks, import graphs, source inspection, or artifact snapshots.
    - Keep public contracts stable unless the audit finding explicitly requires contract change.
    - Update tests, docs, and imports only where required by the architecture fix.
-10. Use agent orchestration only when it improves signal. Dispatch per `references/agent-orchestration.md`:
+10. Use agent orchestration only when it improves signal — except the verifier dispatch below, which is tier-gated mandatory rather than discretionary, carved out under `references/agent-orchestration.md`'s Independent Verification Exception. Dispatch per `references/agent-orchestration.md`:
 
 > **Dispatch: `massa-ai-builder`** (role: `builder`) — charter `skills/agents/builder/SKILL.md`
 > - trigger: large/high-risk finding, disjoint implementation slice, or explicit subagent request
@@ -76,33 +81,37 @@ Not for findings-only architecture review — route to `workflows/architecture/a
 > - memory: suggest-only; main agent persists reusable architecture patterns
 > - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
 
-> **Dispatch: `massa-ai-verification-agent`** (role: `verification-agent`) — charter `skills/agents/verification-agent/SKILL.md`
-> - trigger: independent verification of a high-risk or multi-file architecture fix
-> - scope: the fixed finding's dependency direction, tests, imports, and report claim closure
-> - permissions: read-only
-> - inputs: the finding, the applied fix, the verification suggestion, and validation assets
-> - sensors: deterministic command (targeted tests, import-cycle check, dependency-direction check) and report claim closure check
-> - output: confirmed/disproven closure verdict with evidence
-> - firewall: raw test output/logs summarized
-> - memory: suggest-only; main agent persists reusable verification recipes
-> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
-
 > **Dispatch: `massa-ai-reviewer`** (role: `reviewer`) — charter `skills/agents/reviewer/SKILL.md`
-> - trigger: implementation complete, before the verification gate — never optional
+> - trigger: implementation of the architecture finding complete, before the verification gate — never optional
 > - scope: the fix's diff surface and its task/AC context
 > - permissions: read-only
-> - inputs: diff, acceptance context, recalled code-quality conventions
+> - inputs: diff, ARCH acceptance context, recalled code-quality conventions
 > - sensors: bugs, regressions, missing edge cases, smells introduced by the diff
-> - output: ranked findings, blocking vs advisory; blocking findings become fix items before verification runs
+> - output: ranked findings, blocking vs advisory; blocking findings become architecture fix items before verification runs
 > - firewall: summarized findings only, never raw diff dumps
-> - memory: suggest-only; main agent persists
+> - memory: suggest-only; main agent persists review outcomes for the architecture fix
 > - fallback: if the subagent is unavailable, run a standalone fresh-eyes review against this output contract and record the skipped-delegation reason
 > - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
 
+> **Dispatch: `massa-ai-verification-agent`** (role: `verification-agent`) — charter `skills/agents/verification-agent/SKILL.md`
+> - trigger: mandatory at Standard+/Spec-driven-sized findings or high/critical severity, per the Independent Verification Mandate in `references/verification-ladder.md`'s Mandatory Verification Fix Gate; Quick-tier findings take the fallback below instead
+> - scope: the fixed finding's dependency direction, seam/adapter shape, tests, imports, and report claim closure
+> - permissions: read-only
+> - inputs: the finding, the applied fix, the verification suggestion, dependency-direction/import-cycle evidence, and validation assets
+> - sensors: deterministic command (targeted tests, import-cycle check, dependency-direction check), report claim closure check; discrimination sensor per `references/discrimination-sensor.md` (mutate the fixed dependency direction, seam, or boundary contract in a scratch worktree)
+> - output: confirmed/disproven closure verdict with evidence, feeding the Fix Closure Report's Independent Verifier column
+> - firewall: raw test output/logs summarized
+> - memory: suggest-only; main agent persists architecture verification outcomes
+> - fallback: if the subagent is unavailable, run a standalone fresh-eyes re-check of the architecture closure evidence against this output contract and record the skipped-delegation reason
+> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
+
 11. Verify each completed finding:
    - If verification found a reusable signal (`ac_gap`, `surviving_mutant`, `spec_precision_gap`, `spec_deviation`, `gate_fail`), record it via `references/lessons.md`:
      `bun skills/massa-ai/scripts/lessons.ts --root . add --feature "<slug>" --signal "<signal>" --source "<ref>" --text "<one terse lesson>"`
    - Apply the Mandatory Verification Fix Gate from `references/verification-ladder.md`: run the report's Verification Suggestion or an equivalent deterministic command/artifact check for each selected finding or coherent group.
+   - Run the sensors at the mandate's own tier gate: dispatch the verification-agent block above at Standard+/Spec-driven size or high/critical severity; a Quick-tier finding runs its fallback fresh-eyes self-check instead — the hop is skippable, the check never is.
+   - A surviving mutant on the discrimination sensor marks the finding's Closure Matrix row `blocked` and records a `surviving_mutant` signal via `references/lessons.md`.
+   - The fix→re-verify loop is capped per `references/verification-ladder.md`'s Bounded Fix→Re-verify Loop; exhausting it also marks the row `blocked`. That cap counts re-verify cycles across the whole finding and is a different counter from the two-consecutive-failed-fixes breaker in this file's preamble, which fires inside a single edit iteration.
    - A finding cannot be marked `fixed` when a target-relevant command or artifact check exists but was not attempted; if verification cannot run, mark it `blocked`, `deferred`, or `skipped` with an allowed skipped-check reason.
    - Run the report's verification suggestion when available.
    - Add static checks for dependency direction/import cycles when feasible.
@@ -114,7 +123,8 @@ Not for findings-only architecture review — route to `workflows/architecture/a
 12. At completion, persist only durable knowledge:
    - Accepted architecture constraints, new seams, rejected broad refactors, reusable dependency checks, or recurring coupling patterns after scoring with the Importance Calibration System.
    - Use required tags: `project:<projectId>`, `session:<workflowSessionId>`, `workflow:architecture-fix`, `entity:<entity>`, and one `memory:<tier>` tag.
-13. Complete the Evidence Gate from `references/evidence-gate.md`.
+13. Write the Fix Closure Report per `references/audit-report-io.md`'s Fix Closure Report Contract, at `audits/architecture/<YYYY-MM-DD architecture-fix-closure>.md`, sibling of the consumed audit report. Then run `bun skills/massa-ai/scripts/check_fix_closure.ts <closure.md> --family architecture` before the Propose/Evidence Gate step below; a non-zero exit blocks completion. If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved).
+14. Complete the Evidence Gate from `references/evidence-gate.md`.
 
 ## Examples
 
@@ -131,3 +141,5 @@ User asks: "Fix finding ARCH-2 from audits/architecture/2026-06-06 architecture-
 1. Read the specified report and only execute `ARCH-2`.
 2. Preserve unaffected architecture findings for later.
 3. Report evidence for `ARCH-2` closure and residual risks.
+
+<!-- validator anchors: Stage 3 delivery-authorization scope | Independent Verification Exception | surviving_mutant | Bounded Fix→Re-verify Loop | Fix Closure Report Contract | CONCERNS.md is satisfied by citation | graceful degradation preserved -->