strikethroo 3.14.2 → 3.15.0

package/templates/harness/skills/st-code-review/scripts/find-strikethroo-root.cjs

@@ -0,0 +1,116 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/skill-scripts/find-strikethroo-root.ts
+var find_strikethroo_root_exports = {};
+__export(find_strikethroo_root_exports, {
+  main: () => main
+});
+module.exports = __toCommonJS(find_strikethroo_root_exports);
+
+// src/skill-scripts/shared/root.ts
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var EXPECTED_SCHEMA = true ? 4 : 4;
+var isValidStrikethrooRoot = (strikethrooPath) => {
+  try {
+    if (!fs.existsSync(strikethrooPath)) return false;
+    if (!fs.lstatSync(strikethrooPath).isDirectory()) return false;
+    const metadataPath = path.join(strikethrooPath, ".init-metadata.json");
+    if (!fs.existsSync(metadataPath)) return false;
+    const metadata = JSON.parse(fs.readFileSync(metadataPath, "utf8"));
+    return metadata && typeof metadata === "object" && "version" in metadata;
+  } catch (_err) {
+    return false;
+  }
+};
+var getStrikethrooAt = (directory) => {
+  const strikethrooPath = path.join(directory, ".ai", "strikethroo");
+  return isValidStrikethrooRoot(strikethrooPath) ? strikethrooPath : null;
+};
+var getParentPaths = (currentPath, acc = []) => {
+  const absolutePath = path.resolve(currentPath);
+  const nextAcc = [...acc, absolutePath];
+  const parentPath = path.dirname(absolutePath);
+  if (parentPath === absolutePath) return nextAcc;
+  return getParentPaths(parentPath, nextAcc);
+};
+var checkWorkspaceSchema = (metadataPath) => {
+  let metadata;
+  try {
+    metadata = JSON.parse(fs.readFileSync(metadataPath, "utf8"));
+  } catch {
+    return;
+  }
+  const actual = typeof metadata.workspaceSchemaVersion === "number" ? metadata.workspaceSchemaVersion : 1;
+  if (actual === EXPECTED_SCHEMA) return;
+  if (actual < EXPECTED_SCHEMA) {
+    process.stderr.write(
+      `Workspace schema v${actual} is older than this skill requires (v${EXPECTED_SCHEMA}). Re-run \`npx strikethroo init\` with the latest CLI to update.
+`
+    );
+  } else {
+    process.stderr.write(
+      `This skill (built for workspace schema v${EXPECTED_SCHEMA}) is older than the workspace (v${actual}). Re-run \`npx skills add e0ipso/strikethroo\` to update skills.
+`
+    );
+  }
+  process.exit(1);
+};
+var findStrikethrooRoot = (startPath = process.cwd()) => {
+  const paths = getParentPaths(startPath);
+  const found = paths.find((p) => getStrikethrooAt(p));
+  if (!found) return null;
+  const root = getStrikethrooAt(found);
+  if (root) checkWorkspaceSchema(path.join(root, ".init-metadata.json"));
+  return root;
+};
+
+// src/skill-scripts/find-strikethroo-root.ts
+var main = () => {
+  const startPath = process.argv[2] || process.cwd();
+  const root = findStrikethrooRoot(startPath);
+  if (!root) {
+    process.stderr.write(
+      `Could not find .ai/strikethroo root from ${startPath} or any parent directory.
+`
+    );
+    process.exit(1);
+  }
+  process.stdout.write(`${root}
+`);
+  process.exit(0);
+};
+if (require.main === module) {
+  main();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  main
+});

package/templates/harness/skills/st-code-review/scripts/validate-plan-blueprint.cjs

@@ -0,0 +1,429 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/skill-scripts/validate-plan-blueprint.ts
+var validate_plan_blueprint_exports = {};
+__export(validate_plan_blueprint_exports, {
+  main: () => main
+});
+module.exports = __toCommonJS(validate_plan_blueprint_exports);
+
+// src/skill-scripts/shared/root.ts
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var EXPECTED_SCHEMA = true ? 4 : 4;
+var isValidStrikethrooRoot = (strikethrooPath) => {
+  try {
+    if (!fs.existsSync(strikethrooPath)) return false;
+    if (!fs.lstatSync(strikethrooPath).isDirectory()) return false;
+    const metadataPath = path.join(strikethrooPath, ".init-metadata.json");
+    if (!fs.existsSync(metadataPath)) return false;
+    const metadata = JSON.parse(fs.readFileSync(metadataPath, "utf8"));
+    return metadata && typeof metadata === "object" && "version" in metadata;
+  } catch (_err) {
+    return false;
+  }
+};
+var getStrikethrooAt = (directory) => {
+  const strikethrooPath = path.join(directory, ".ai", "strikethroo");
+  return isValidStrikethrooRoot(strikethrooPath) ? strikethrooPath : null;
+};
+var getParentPaths = (currentPath, acc = []) => {
+  const absolutePath = path.resolve(currentPath);
+  const nextAcc = [...acc, absolutePath];
+  const parentPath = path.dirname(absolutePath);
+  if (parentPath === absolutePath) return nextAcc;
+  return getParentPaths(parentPath, nextAcc);
+};
+var checkWorkspaceSchema = (metadataPath) => {
+  let metadata;
+  try {
+    metadata = JSON.parse(fs.readFileSync(metadataPath, "utf8"));
+  } catch {
+    return;
+  }
+  const actual = typeof metadata.workspaceSchemaVersion === "number" ? metadata.workspaceSchemaVersion : 1;
+  if (actual === EXPECTED_SCHEMA) return;
+  if (actual < EXPECTED_SCHEMA) {
+    process.stderr.write(
+      `Workspace schema v${actual} is older than this skill requires (v${EXPECTED_SCHEMA}). Re-run \`npx strikethroo init\` with the latest CLI to update.
+`
+    );
+  } else {
+    process.stderr.write(
+      `This skill (built for workspace schema v${EXPECTED_SCHEMA}) is older than the workspace (v${actual}). Re-run \`npx skills add e0ipso/strikethroo\` to update skills.
+`
+    );
+  }
+  process.exit(1);
+};
+var findStrikethrooRoot = (startPath = process.cwd()) => {
+  const paths = getParentPaths(startPath);
+  const found = paths.find((p) => getStrikethrooAt(p));
+  if (!found) return null;
+  const root = getStrikethrooAt(found);
+  if (root) checkWorkspaceSchema(path.join(root, ".init-metadata.json"));
+  return root;
+};
+
+// src/skill-scripts/shared/plan-scan.ts
+var fs2 = __toESM(require("fs"));
+var path2 = __toESM(require("path"));
+
+// src/skill-scripts/shared/frontmatter.ts
+var ID_PATTERNS = [
+  /^\s*["']?id["']?\s*:\s*["']?([+-]?\d+)["']?\s*(?:#.*)?$/im,
+  /^\s*id\s*:\s*([+-]?\d+)\s*(?:#.*)?$/im,
+  /^\s*["']?id["']?\s*:\s*"([+-]?\d+)"\s*(?:#.*)?$/im,
+  /^\s*["']?id["']?\s*:\s*'([+-]?\d+)'\s*(?:#.*)?$/im,
+  /^\s*["']id["']\s*:\s*([+-]?\d+)\s*(?:#.*)?$/im,
+  /^\s*id\s*:\s*[|>]\s*([+-]?\d+)\s*$/im
+];
+var validateId = (rawId) => {
+  const id = parseInt(rawId, 10);
+  if (Number.isNaN(id) || id < 0 || id > Number.MAX_SAFE_INTEGER) return null;
+  return id;
+};
+var extractIdFromMarkdown = (content) => {
+  const frontmatterMatch = content.match(/^---\s*\r?\n([\s\S]*?)\r?\n---/);
+  if (!frontmatterMatch || !frontmatterMatch[1]) return null;
+  const block = frontmatterMatch[1];
+  for (const pattern of ID_PATTERNS) {
+    const match = block.match(pattern);
+    if (match && match[1]) {
+      const id = validateId(match[1]);
+      if (id !== null) return id;
+    }
+  }
+  return null;
+};
+var extractPlanId = (content, _filePath) => {
+  return extractIdFromMarkdown(content);
+};
+
+// src/skill-scripts/shared/plan-scan.ts
+var PLAN_EXTENSIONS = [".md"];
+var scanPlanDir = (planDirPath, dirName, isArchive) => {
+  let entries;
+  try {
+    entries = fs2.readdirSync(planDirPath, { withFileTypes: true });
+  } catch (_err) {
+    return [];
+  }
+  return entries.filter((e) => e.isFile() && PLAN_EXTENSIONS.some((ext) => e.name.endsWith(ext))).flatMap((e) => {
+    const filePath = path2.join(planDirPath, e.name);
+    try {
+      const content = fs2.readFileSync(filePath, "utf8");
+      const id = extractPlanId(content, filePath);
+      if (id === null) return [];
+      return [{ id, file: filePath, dir: planDirPath, isArchive, name: dirName }];
+    } catch (_err) {
+      return [];
+    }
+  });
+};
+var getAllPlans = (taskManagerRoot) => {
+  const sources = [
+    { dir: path2.join(taskManagerRoot, "plans"), isArchive: false },
+    { dir: path2.join(taskManagerRoot, "archive"), isArchive: true }
+  ];
+  return sources.flatMap(({ dir, isArchive }) => {
+    if (!fs2.existsSync(dir)) return [];
+    let entries;
+    try {
+      entries = fs2.readdirSync(dir, { withFileTypes: true });
+    } catch (_err) {
+      return [];
+    }
+    return entries.filter((e) => e.isDirectory()).flatMap((e) => scanPlanDir(path2.join(dir, e.name), e.name, isArchive));
+  });
+};
+
+// src/skill-scripts/shared/plan-resolve.ts
+var fs3 = __toESM(require("fs"));
+var path3 = __toESM(require("path"));
+var isValidRootDir = (strikethrooPath) => {
+  try {
+    if (!fs3.existsSync(strikethrooPath)) return false;
+    if (!fs3.lstatSync(strikethrooPath).isDirectory()) return false;
+    const metadataPath = path3.join(strikethrooPath, ".init-metadata.json");
+    if (!fs3.existsSync(metadataPath)) return false;
+    const metadata = JSON.parse(fs3.readFileSync(metadataPath, "utf8"));
+    return metadata && typeof metadata === "object" && "version" in metadata;
+  } catch (_err) {
+    return false;
+  }
+};
+var checkStandardRootShortcut = (filePath) => {
+  const planDir = path3.dirname(filePath);
+  const parentDir = path3.dirname(planDir);
+  const possibleRoot = path3.dirname(parentDir);
+  const parentBase = path3.basename(parentDir);
+  if (parentBase !== "plans" && parentBase !== "archive") return null;
+  if (path3.basename(possibleRoot) !== "strikethroo") return null;
+  const dotAiDir = path3.dirname(possibleRoot);
+  if (path3.basename(dotAiDir) !== ".ai") return null;
+  return isValidRootDir(possibleRoot) ? possibleRoot : null;
+};
+var resolveByPath = (absolutePath) => {
+  let content;
+  try {
+    content = fs3.readFileSync(absolutePath, "utf8");
+  } catch (_err) {
+    return null;
+  }
+  const planId = extractPlanId(content, absolutePath);
+  if (planId === null) return null;
+  const tmRoot = checkStandardRootShortcut(absolutePath) || findStrikethrooRoot(path3.dirname(absolutePath));
+  if (!tmRoot) return null;
+  return {
+    planFile: absolutePath,
+    planDir: path3.dirname(absolutePath),
+    strikethrooRoot: tmRoot,
+    planId
+  };
+};
+var resolveByIdInAncestry = (planId, startPath, searched = /* @__PURE__ */ new Set()) => {
+  const tmRoot = findStrikethrooRoot(startPath);
+  if (!tmRoot) return null;
+  const normalized = path3.normalize(tmRoot);
+  if (searched.has(normalized)) return null;
+  searched.add(normalized);
+  const plans = getAllPlans(tmRoot);
+  const match = plans.find((p) => p.id === planId);
+  if (match) {
+    return {
+      planFile: match.file,
+      planDir: match.dir,
+      strikethrooRoot: tmRoot,
+      planId
+    };
+  }
+  const parentOfRoot = path3.dirname(path3.dirname(tmRoot));
+  if (parentOfRoot === tmRoot) return null;
+  return resolveByIdInAncestry(planId, parentOfRoot, searched);
+};
+var resolvePlan = (input, startPath = process.cwd()) => {
+  if (input === null || input === void 0 || input === "") return null;
+  const inputStr = String(input);
+  if (inputStr.startsWith("/")) {
+    return resolveByPath(inputStr);
+  }
+  const planId = parseInt(inputStr, 10);
+  if (Number.isNaN(planId)) return null;
+  return resolveByIdInAncestry(planId, startPath);
+};
+
+// src/skill-scripts/shared/blueprint-detection.ts
+var fs4 = __toESM(require("fs"));
+var hasExecutionBlueprint = (planFile) => {
+  try {
+    const content = fs4.readFileSync(planFile, "utf8");
+    return /^## Execution Blueprint/m.test(content);
+  } catch (_err) {
+    return false;
+  }
+};
+
+// src/skill-scripts/shared/task-count.ts
+var fs5 = __toESM(require("fs"));
+var path4 = __toESM(require("path"));
+var countTaskFiles = (planDir) => {
+  const tasksDir = path4.join(planDir, "tasks");
+  if (!fs5.existsSync(tasksDir)) return 0;
+  try {
+    const stat = fs5.lstatSync(tasksDir);
+    if (!stat.isDirectory()) return 0;
+    return fs5.readdirSync(tasksDir).filter((f) => f.endsWith(".md")).length;
+  } catch (_err) {
+    return 0;
+  }
+};
+
+// src/skill-scripts/shared/task-complexity.ts
+var fs6 = __toESM(require("fs"));
+var path5 = __toESM(require("path"));
+
+// src/skill-scripts/shared/complexity-score.ts
+var validateComplexityScore = (value) => {
+  const trimmed = value.trim();
+  if (!/^\d+$/.test(trimmed)) {
+    return { valid: false, reason: "non-integer" };
+  }
+  const parsed = Number.parseInt(trimmed, 10);
+  if (parsed < 1 || parsed > 10) {
+    return { valid: false, reason: "out-of-range", value: parsed };
+  }
+  return { valid: true, value: parsed };
+};
+
+// src/skill-scripts/shared/task-file.ts
+var extractFrontmatter = (content) => {
+  const match = content.match(/^---\s*\r?\n([\s\S]*?)\r?\n---/);
+  return match && match[1] ? match[1] : null;
+};
+
+// src/skill-scripts/shared/task-complexity.ts
+var validateTaskComplexityScores = (planDir) => {
+  const tasksDir = path5.join(planDir, "tasks");
+  if (!fs6.existsSync(tasksDir)) return [];
+  let files;
+  try {
+    if (!fs6.lstatSync(tasksDir).isDirectory()) return [];
+    files = fs6.readdirSync(tasksDir).filter((f) => f.endsWith(".md")).sort();
+  } catch (_err) {
+    return [];
+  }
+  const invalid = [];
+  for (const file of files) {
+    let content;
+    try {
+      content = fs6.readFileSync(path5.join(tasksDir, file), "utf8");
+    } catch (_err) {
+      invalid.push(`${file}: unreadable`);
+      continue;
+    }
+    const frontmatter = extractFrontmatter(content);
+    const match = frontmatter ? frontmatter.match(/^\s*complexity_score\s*:\s*(.*?)\s*(?:#.*)?$/im) : null;
+    if (!match || match[1] === void 0) {
+      invalid.push(`${file}: missing complexity_score`);
+      continue;
+    }
+    const raw = match[1].trim();
+    const result = validateComplexityScore(raw);
+    if (result.valid) continue;
+    if (result.reason === "non-integer") {
+      invalid.push(`${file}: non-integer complexity_score "${raw}"`);
+      continue;
+    }
+    invalid.push(`${file}: complexity_score ${result.value} out of range 1-10`);
+  }
+  return invalid;
+};
+
+// src/skill-scripts/validate-plan-blueprint.ts
+var VALID_FIELDS = [
+  "planFile",
+  "planDir",
+  "taskCount",
+  "blueprintExists",
+  "strikethrooRoot",
+  "planId",
+  "complexityScoresValid",
+  "invalidComplexityTasks"
+];
+var usage = () => {
+  const lines = [
+    "Plan ID or absolute path is required",
+    "",
+    "Usage: node validate-plan-blueprint.cjs <plan-id-or-path> [field-name]",
+    "",
+    "Examples:",
+    "  node validate-plan-blueprint.cjs 47",
+    "  node validate-plan-blueprint.cjs /path/to/plan.md",
+    "  node validate-plan-blueprint.cjs 47 planFile",
+    "  node validate-plan-blueprint.cjs 47 blueprintExists"
+  ];
+  lines.forEach((l) => process.stderr.write(`[ERROR] ${l}
+`));
+};
+var listAvailablePlans = (startPath) => {
+  const tmRoot = findStrikethrooRoot(startPath);
+  if (!tmRoot) return [];
+  const plans = getAllPlans(tmRoot);
+  return plans.map((p) => p.name).sort((a, b) => {
+    const aMatch = a.match(/^(\d+)--/);
+    const bMatch = b.match(/^(\d+)--/);
+    if (!aMatch || !bMatch || !aMatch[1] || !bMatch[1]) return 0;
+    return parseInt(aMatch[1], 10) - parseInt(bMatch[1], 10);
+  });
+};
+var main = () => {
+  const inputId = process.argv[2];
+  const fieldName = process.argv[3];
+  if (!inputId) {
+    usage();
+    process.exit(1);
+  }
+  const numericInput = parseInt(inputId, 10);
+  const isNumeric = !Number.isNaN(numericInput);
+  const isAbsolutePath = inputId.startsWith("/");
+  if (!isNumeric && !isAbsolutePath) {
+    process.stderr.write(`[ERROR] Invalid plan ID: "${inputId}" is not a valid number
+`);
+    process.exit(1);
+  }
+  const resolved = resolvePlan(inputId);
+  if (!resolved) {
+    process.stderr.write(`[ERROR] Plan ID ${inputId} not found or invalid
+`);
+    process.stderr.write("[ERROR] \n");
+    const available = listAvailablePlans(process.cwd());
+    if (available.length > 0) {
+      process.stderr.write("[ERROR] Available plans:\n");
+      available.forEach((name) => process.stderr.write(`[ERROR]   ${name}
+`));
+    }
+    process.exit(1);
+  }
+  const invalidComplexity = validateTaskComplexityScores(resolved.planDir);
+  const result = {
+    planFile: resolved.planFile,
+    planDir: resolved.planDir,
+    strikethrooRoot: resolved.strikethrooRoot,
+    planId: resolved.planId,
+    taskCount: countTaskFiles(resolved.planDir),
+    blueprintExists: hasExecutionBlueprint(resolved.planFile) ? "yes" : "no",
+    complexityScoresValid: invalidComplexity.length === 0 ? "yes" : "no",
+    invalidComplexityTasks: invalidComplexity.join("; ")
+  };
+  if (fieldName) {
+    if (!VALID_FIELDS.includes(fieldName)) {
+      process.stderr.write(`[ERROR] Invalid field name: ${fieldName}
+`);
+      process.stderr.write(`[ERROR] Valid fields: ${VALID_FIELDS.join(", ")}
+`);
+      process.exit(1);
+    }
+    const value = result[fieldName];
+    process.stdout.write(`${String(value)}
+`);
+  } else {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+  }
+  process.exit(0);
+};
+if (require.main === module) {
+  main();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  main
+});

package/templates/harness/skills/st-execute-blueprint/SKILL.md

@@ -64,7 +64,9 @@ If generation still leaves the plan without tasks or a blueprint, stop and repor
 
 ### 5. Optionally create a feature branch
 
-Run `scripts/create-feature-branch.cjs <plan-id>` once before phase execution. Branch creation is best-effort: when the script reports that it skipped creation (for example, not on `main`/`master`), continue on the current branch and do not retry or create a branch manually. When the script exits with an error (for example, uncommitted changes on `main`/`master`), halt and report the error. Do not treat a skipped branch as a failure or spend effort working around a skip.
+Run `scripts/create-feature-branch.cjs <plan-id>` once before phase execution. Branch creation is best-effort: when the script reports that it skipped creation (for example, not on `main`/`master`), continue on the current branch and do not retry or create a branch manually. Uncommitted or untracked changes are permitted only when every change is inside the repository-root `.ai/strikethroo` subtree, so a newly generated plan and tasks can remain uncommitted before execution. When the script exits with an error—including changes anywhere outside that subtree or an inability to inspect Git status on `main`/`master`—halt and report the error. Do not treat a skipped branch as a failure or spend effort working around a skip.
+
+After the branch step, run `scripts/capture-base-commit.cjs <plan-id>` once. It records the commit the review gate diffs against. A `skipped` result is not a failure — continue execution and note that the review gate will skip. Only an `error` result halts.
 
 ### 6. Load project context and execution blueprint
 
@@ -162,6 +164,51 @@ Read `<root>/config/hooks/POST_EXECUTION.md` and execute its instructions. If va
 
 Before declaring execution complete, apply the evidence gate in `<root>/config/shared/verification-gate.md` to the plan's Success Criteria and Self Validation steps.
 
+#### Run the code review gate
+
+After `POST_EXECUTION.md` reports green and before appending the execution summary, follow the `st-code-review` skill and run one review round with its bundled mechanism:
+
+```text
+code-review.cjs <plan-id> <current-harness> <round>
+```
+
+`code-review.cjs` ships with the `st-code-review` skill and lives in that skill's own `scripts` directory, a sibling of this one. Resolve it there; it is not bundled with this skill. If the `st-code-review` skill is not installed on this harness, record that as the review outcome in the execution summary and continue to the summary and archival.
+
+`<current-harness>` is the exact supported harness identifier running this skill. `<round>` is `1` on the first invocation, and thereafter the exact `decision.nextRound` the previous round returned. The command emits exactly one JSON line on stdout. Read its `kind`, then — when `kind` is `reviewed` — its `decision.kind`, and do exactly what the matching row states.
+
+| Result | What you do |
+| --- | --- |
+| `skipped` | The gate is disabled or unconfigured. Record `reason` and `detail` verbatim in the execution summary, then continue to the summary and archival. A skip is never a failure. |
+| `reviewed`, `decision.kind` = `gate-passed` | The gate passed. Record `findingsGate.recorded` and `findingsGate.aboveFloorWithoutSuggestion` — real findings deliberately not applied — then continue to the summary and archival. |
+| `reviewed`, `decision.kind` = `fix-and-continue` | Apply the `actionable` set from `<plan-dir>/review/round-<n>/findings.json` on the implementer route. Re-run `POST_EXECUTION.md` in full. Then run the gate again with `<round>` set to `decision.nextRound`. |
+| `reviewed`, `decision.kind` = `budget-exhausted` | Halt exactly as any mechanical gate failure. Leave the plan in `plans/`, do not append a completion summary, do not archive, and report the outstanding findings with actionable next steps. |
+| `reviewed`, `decision.kind` = `round-failed` | The round was not certified — the findings document was absent or invalid, or no validator was available. Halt and report `decision.detail`. Never report an uncertified round as clean. |
+| `budget-exhausted` | A round past the enforced budget was requested and no reviewer was dispatched. Halt exactly as `decision.kind` = `budget-exhausted` above. |
+| `launched-failure` | The reviewer harness exited non-zero. Halt and report `detail`. |
+| `fallback` | The reviewer never ran — the harness was unavailable or authentication failed. Record `reason` and `detail` verbatim in the execution summary, then continue to the summary and archival. |
+| `infrastructure-failure` | A real error. Halt and report `detail`. Do not retry on a different route. |
+
+<details>
+<summary>Applying an actionable finding</summary>
+
+`<plan-dir>/review/round-<n>/findings.json` holds that round's partition. Its `actionable` array is the only set you apply. Its `recorded` array is inspection material and is never applied.
+
+Each actionable entry names a file, a location, and a suggestion whose `original-code` was copied verbatim from that file. Apply it as an exact text replacement of `original-code` by `proposed-code`, and change nothing else. When `original-code` no longer matches the file, record the finding as not applied and move to the next one. Do not reconstruct the fix, widen it, or refactor around it.
+
+Dispatch every fix on the implementer route. Earlier rounds' rulings are carried into the next round by the mechanism itself, which reads the partitions it already wrote; do not pass them back on the command line.
+
+</details>
+
+Hard rules:
+
+- The gate creates no task files.
+- The gate never mutates the Execution Blueprint.
+- The gate is terminal only — never per phase, never per task.
+- The reviewer never fixes its own findings. Detection runs on the reviewer route, fixes run on the implementer route.
+- Any applied fix invalidates the green build that preceded it. Re-run `POST_EXECUTION.md` in full — lint, tests, and Self Validation — before the gate runs again. Never re-verify against the prior green build.
+- Whether another round runs is `decision.kind`'s to state and yours to obey. Do not count rounds, reason about the budget, or invoke a round the mechanism did not name.
+- A green gate is not a correctness guarantee. It reduces the exposure a human PR approval reduces, and it leaves the same exposure behind.
+
 ### 9. Append execution summary
 
 Append an execution summary section to the plan document using the format described in `<root>/config/templates/EXECUTION_SUMMARY_TEMPLATE.md`. Populate:
@@ -169,7 +216,7 @@ Append an execution summary section to the plan document using the format descri
 - **Status**: Completed Successfully
 - **Completed Date**: current date
 - **Results**: brief summary of deliverables
-- **Noteworthy Events**: all decisions, issues, and outcomes encountered during execution. If none occurred, state "No significant issues encountered."
+- **Noteworthy Events**: all decisions, issues, and outcomes encountered during execution. Always record the review gate's outcome here: the reviewer harness, the number of rounds run, and the counts of findings recorded versus applied — or, when the gate did not run, its `reason` and `detail` verbatim. If nothing else occurred, state "No significant issues encountered." after the review outcome.
 - **Necessary follow-ups**: any follow-up actions or optimizations
 
 ### 10. Archive the plan