@fro.bot/systematic 3.14.4 → 3.15.0

package/dist/claude-code-validator.d.ts

@@ -0,0 +1,8 @@
+interface ValidatorOptions {
+    readonly argv: readonly string[];
+    readonly cwd?: string;
+    readonly outputSink?: (message: string) => void;
+    readonly errorSink?: (message: string) => void;
+}
+export declare function runClaudeCodeValidator(options: ValidatorOptions): number;
+export {};

package/dist/cli.js

@@ -17,9 +17,9 @@ import {
 } from "./index-0stf3ag0.js";
 
 // src/cli.ts
-import fs5 from "fs";
+import fs6 from "fs";
 import os2 from "os";
-import path4 from "path";
+import path5 from "path";
 
 // src/lib/agent-resolver.ts
 import fs from "fs";
@@ -1978,6 +1978,108 @@ function cleanup(agentsRoot, configOptions) {
   return { status: "ok" };
 }
 
+// src/lib/review-artifact-path.ts
+import fs4 from "fs";
+import path3 from "path";
+function formatReviewArtifactIssuePath(issuePath) {
+  if (issuePath.length === 0)
+    return "$";
+  return issuePath.map((segment) => typeof segment === "number" ? String(segment) : segment).join(".");
+}
+function readReviewArtifact(filePath) {
+  let content;
+  try {
+    content = fs4.readFileSync(filePath, "utf8");
+  } catch {
+    return { message: "Review artifact file could not be read", ok: false };
+  }
+  try {
+    return { ok: true, value: JSON.parse(content) };
+  } catch (error) {
+    return {
+      message: error instanceof SyntaxError ? "Review artifact contains malformed JSON" : "Review artifact file could not be read",
+      ok: false
+    };
+  }
+}
+function isLegacyReviewArtifact(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) && !Object.hasOwn(value, "schema_version");
+}
+function hasParentDirectoryTraversal(input) {
+  return input.split(/[\\/]+/).some((segment) => segment === "..");
+}
+function pathContainsSymlink(candidate) {
+  let current = path3.parse(candidate).root;
+  const relative2 = path3.relative(current, candidate);
+  for (const segment of relative2.split(path3.sep)) {
+    if (!segment)
+      continue;
+    current = path3.join(current, segment);
+    try {
+      if (fs4.lstatSync(current).isSymbolicLink())
+        return true;
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+function isWithinDirectory(candidate, directory) {
+  const relative2 = path3.relative(directory, candidate);
+  return relative2 !== "" && relative2 !== ".." && !relative2.startsWith(`..${path3.sep}`) && !path3.isAbsolute(relative2);
+}
+function resolveReviewArtifactPath(input, cwd) {
+  if (hasParentDirectoryTraversal(input)) {
+    return {
+      message: "Review artifact path must not contain parent-directory traversal",
+      ok: false
+    };
+  }
+  const artifactRoot = path3.resolve(cwd, ".context", "systematic", "ce-review");
+  let canonicalRoot;
+  try {
+    canonicalRoot = fs4.realpathSync(artifactRoot);
+    if (!fs4.statSync(canonicalRoot).isDirectory()) {
+      return {
+        message: "Review artifact directory is not a directory",
+        ok: false
+      };
+    }
+  } catch {
+    return { message: "Review artifact directory is unavailable", ok: false };
+  }
+  const candidate = path3.resolve(cwd, input);
+  if (pathContainsSymlink(candidate)) {
+    return {
+      message: "Review artifact path must not contain symlinks",
+      ok: false
+    };
+  }
+  let canonicalTarget;
+  try {
+    canonicalTarget = fs4.realpathSync(candidate);
+  } catch {
+    return { message: "Review artifact file was not found", ok: false };
+  }
+  if (!isWithinDirectory(canonicalTarget, canonicalRoot)) {
+    return {
+      message: "Review artifact path must remain inside .context/systematic/ce-review",
+      ok: false
+    };
+  }
+  try {
+    if (!fs4.lstatSync(canonicalTarget).isFile()) {
+      return {
+        message: "Review artifact target is not a regular file",
+        ok: false
+      };
+    }
+  } catch {
+    return { message: "Review artifact file was not found", ok: false };
+  }
+  return { ok: true, path: canonicalTarget };
+}
+
 // src/lib/review-artifact-schema.ts
 var MAX_REVIEWER_LENGTH = 64;
 var MAX_RUN_ID_LENGTH = 64;
@@ -2216,8 +2318,8 @@ var ReviewArtifactSchema = exports_external.object({
 }).strict();
 
 // src/lib/setup.ts
-import fs4 from "fs";
-import path3 from "path";
+import fs5 from "fs";
+import path4 from "path";
 var SYSTEMATIC_PACKAGE_NAME = "@fro.bot/systematic";
 var PI_PACKAGE_IDENTIFIER = `npm:${SYSTEMATIC_PACKAGE_NAME}`;
 var SETUP_ERROR_NAME = "SetupError";
@@ -2227,10 +2329,10 @@ function createSetupError(message) {
   return error;
 }
 var DEFAULT_OPS = {
-  writeFileSync: fs4.writeFileSync,
-  renameSync: fs4.renameSync,
-  unlinkSync: fs4.unlinkSync,
-  chmodSync: fs4.chmodSync
+  writeFileSync: fs5.writeFileSync,
+  renameSync: fs5.renameSync,
+  unlinkSync: fs5.unlinkSync,
+  chmodSync: fs5.chmodSync
 };
 function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -2252,7 +2354,7 @@ function isPiSystematicIdentifier(identifier) {
 }
 function lstatOrNull(targetPath) {
   try {
-    return fs4.lstatSync(targetPath);
+    return fs5.lstatSync(targetPath);
   } catch (error) {
     if (error instanceof Error && "code" in error && error.code === "ENOENT") {
       return null;
@@ -2261,10 +2363,10 @@ function lstatOrNull(targetPath) {
   }
 }
 function assertRealpathUnderCwd(dir, cwd) {
-  const realDir = fs4.realpathSync(dir);
-  const realCwd = fs4.realpathSync(cwd);
-  const relative2 = path3.relative(realCwd, realDir);
-  if (relative2.startsWith("..") || path3.isAbsolute(relative2)) {
+  const realDir = fs5.realpathSync(dir);
+  const realCwd = fs5.realpathSync(cwd);
+  const relative2 = path4.relative(realCwd, realDir);
+  if (relative2.startsWith("..") || path4.isAbsolute(relative2)) {
     throw createSetupError(`Refusing to write under ${dir}: resolved directory escapes the project root`);
   }
 }
@@ -2277,7 +2379,7 @@ function assertParentTrusted(parentDir, cwd) {
     assertRealpathUnderCwd(parentDir, cwd);
     return;
   }
-  fs4.mkdirSync(parentDir, { recursive: true });
+  fs5.mkdirSync(parentDir, { recursive: true });
   assertRealpathUnderCwd(parentDir, cwd);
 }
 var OPENCODE_TARGET_CANDIDATES = [
@@ -2287,19 +2389,19 @@ var OPENCODE_TARGET_CANDIDATES = [
   "opencode.json"
 ];
 function resolveOpenCodeTargetPath(cwd) {
-  const opencodeDirStat = lstatOrNull(path3.join(cwd, ".opencode"));
+  const opencodeDirStat = lstatOrNull(path4.join(cwd, ".opencode"));
   if (opencodeDirStat?.isSymbolicLink()) {
-    return path3.join(cwd, OPENCODE_TARGET_CANDIDATES[0]);
+    return path4.join(cwd, OPENCODE_TARGET_CANDIDATES[0]);
   }
   for (const candidate of OPENCODE_TARGET_CANDIDATES) {
-    const candidatePath = path3.join(cwd, candidate);
+    const candidatePath = path4.join(cwd, candidate);
     if (lstatOrNull(candidatePath) !== null)
       return candidatePath;
   }
-  return path3.join(cwd, "opencode.jsonc");
+  return path4.join(cwd, "opencode.jsonc");
 }
 var IS_WINDOWS = process.platform === "win32";
-var OPEN_FLAGS = IS_WINDOWS ? fs4.constants.O_RDONLY : fs4.constants.O_RDONLY | fs4.constants.O_NOFOLLOW | fs4.constants.O_NONBLOCK;
+var OPEN_FLAGS = IS_WINDOWS ? fs5.constants.O_RDONLY : fs5.constants.O_RDONLY | fs5.constants.O_NOFOLLOW | fs5.constants.O_NONBLOCK;
 function assertWindowsPreOpenTrust(targetPath) {
   const preStat = lstatOrNull(targetPath);
   if (preStat && (preStat.isSymbolicLink() || !preStat.isFile())) {
@@ -2311,7 +2413,7 @@ function openTrustedExisting(targetPath) {
     assertWindowsPreOpenTrust(targetPath);
   let fd;
   try {
-    fd = fs4.openSync(targetPath, OPEN_FLAGS);
+    fd = fs5.openSync(targetPath, OPEN_FLAGS);
   } catch (error) {
     if (error instanceof Error && "code" in error) {
       if (error.code === "ENOENT")
@@ -2323,13 +2425,13 @@ function openTrustedExisting(targetPath) {
     throw error;
   }
   try {
-    const stat = fs4.fstatSync(fd);
+    const stat = fs5.fstatSync(fd);
     if (!stat.isFile()) {
       throw createSetupError(`Refusing to read ${targetPath}: not a regular file`);
     }
-    return { bytes: fs4.readFileSync(fd), mode: stat.mode & 511 };
+    return { bytes: fs5.readFileSync(fd), mode: stat.mode & 511 };
   } finally {
-    fs4.closeSync(fd);
+    fs5.closeSync(fd);
   }
 }
 function atomicWrite(targetPath, content, originalBytes, mode, ops) {
@@ -2344,8 +2446,8 @@ function atomicWrite(targetPath, content, originalBytes, mode, ops) {
   writeTempAndRename(targetPath, content, mode, preserveMode, ops);
 }
 function writeTempAndRename(destPath, content, mode, preserveExactMode, ops) {
-  const parentDir = path3.dirname(destPath);
-  const tempPath = makeTempPath(parentDir, path3.basename(destPath));
+  const parentDir = path4.dirname(destPath);
+  const tempPath = makeTempPath(parentDir, path4.basename(destPath));
   try {
     ops.writeFileSync(tempPath, content, { flag: "wx", mode });
     if (preserveExactMode) {
@@ -2358,10 +2460,10 @@ function writeTempAndRename(destPath, content, mode, preserveExactMode, ops) {
   }
 }
 function makeTempPath(parentDir, basename2) {
-  return path3.join(parentDir, `.${basename2}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  return path4.join(parentDir, `.${basename2}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
 }
 function cleanupTemp(tempPath, ops) {
-  if (!fs4.existsSync(tempPath))
+  if (!fs5.existsSync(tempPath))
     return;
   try {
     ops.unlinkSync(tempPath);
@@ -2395,7 +2497,7 @@ function parseOpenCodeJsonc(rawText, targetPath) {
 }
 function setupOpenCode(cwd, ops) {
   const targetPath = resolveOpenCodeTargetPath(cwd);
-  assertParentTrusted(path3.dirname(targetPath), cwd);
+  assertParentTrusted(path4.dirname(targetPath), cwd);
   const existing = openTrustedExisting(targetPath);
   if (existing === null) {
     const content = `${JSON.stringify({ plugin: [SYSTEMATIC_PACKAGE_NAME] }, null, 2)}
@@ -2453,8 +2555,8 @@ function assertPiTaggedEntryUsable(entry, targetPath) {
   }
 }
 function setupPi(cwd, ops) {
-  const targetPath = path3.join(cwd, ".pi", "settings.json");
-  assertParentTrusted(path3.dirname(targetPath), cwd);
+  const targetPath = path4.join(cwd, ".pi", "settings.json");
+  assertParentTrusted(path4.dirname(targetPath), cwd);
   const existing = openTrustedExisting(targetPath);
   if (existing === null) {
     const content = `${JSON.stringify({ packages: [PI_PACKAGE_IDENTIFIER] }, null, 2)}
@@ -2514,10 +2616,10 @@ function setupHarness(harness, cwd, opsOverride) {
 // src/cli.ts
 function readPackageMetadata(packageRoot) {
   try {
-    const packageJsonPath = path4.join(packageRoot, "package.json");
-    if (!fs5.existsSync(packageJsonPath))
+    const packageJsonPath = path5.join(packageRoot, "package.json");
+    if (!fs6.existsSync(packageJsonPath))
       return {};
-    const content = fs5.readFileSync(packageJsonPath, "utf8");
+    const content = fs6.readFileSync(packageJsonPath, "utf8");
     const parsed = JSON.parse(content);
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
       return {};
@@ -2531,7 +2633,7 @@ function readPackageMetadata(packageRoot) {
     return {};
   }
 }
-var PACKAGE_ROOT = path4.resolve(import.meta.dirname, "..");
+var PACKAGE_ROOT = path5.resolve(import.meta.dirname, "..");
 var VERSION = readPackageMetadata(PACKAGE_ROOT).version ?? "unknown";
 var HELP = `
 systematic - OpenCode plugin for systematic engineering workflows
@@ -2590,9 +2692,9 @@ Scope:
 var VALIDATE_REVIEW_ARTIFACT_USAGE = "Usage: systematic validate-review-artifact <path>";
 var REVIEW_ARTIFACT_SCHEMA_RELATIVE_PATH = "skills/ce-review/references/review-summary-schema.json";
 function defaultCapabilityRoots() {
-  const configDir = process.env.XDG_CONFIG_HOME ? path4.join(process.env.XDG_CONFIG_HOME, "opencode") : path4.join(os2.homedir(), ".config/opencode");
+  const configDir = process.env.XDG_CONFIG_HOME ? path5.join(process.env.XDG_CONFIG_HOME, "opencode") : path5.join(os2.homedir(), ".config/opencode");
   return {
-    agentsRoot: path4.join(PACKAGE_ROOT, "agents"),
+    agentsRoot: path5.join(PACKAGE_ROOT, "agents"),
     configDir,
     cwd: process.cwd(),
     homeDir: os2.homedir(),
@@ -2691,9 +2793,9 @@ function collectConfigMetadata(roots, injected) {
 }
 function resolveCapabilityRootPath(root) {
   try {
-    return fs5.realpathSync(root);
+    return fs6.realpathSync(root);
   } catch {
-    return path4.resolve(root);
+    return path5.resolve(root);
   }
 }
 function capabilityRoots(roots) {
@@ -2703,7 +2805,7 @@ function capabilityRoots(roots) {
     { id: "package", path: resolveCapabilityRootPath(roots.packageRoot) },
     {
       id: "skills",
-      path: resolveCapabilityRootPath(path4.join(roots.packageRoot, "skills"))
+      path: resolveCapabilityRootPath(path5.join(roots.packageRoot, "skills"))
     },
     { id: "user", path: resolveCapabilityRootPath(roots.homeDir) }
   ];
@@ -2744,85 +2846,6 @@ function runCapabilities(options) {
 function runCapabilitiesCli(options) {
   return runCapabilities(options);
 }
-function hasParentDirectoryTraversal(input) {
-  return input.split(/[\\/]+/).some((segment) => segment === "..");
-}
-function pathContainsSymlink(candidate) {
-  let current = path4.parse(candidate).root;
-  const relative2 = path4.relative(current, candidate);
-  for (const segment of relative2.split(path4.sep)) {
-    if (!segment)
-      continue;
-    current = path4.join(current, segment);
-    try {
-      if (fs5.lstatSync(current).isSymbolicLink())
-        return true;
-    } catch {
-      return false;
-    }
-  }
-  return false;
-}
-function isWithinDirectory(candidate, directory) {
-  const relative2 = path4.relative(directory, candidate);
-  return relative2 !== "" && relative2 !== ".." && !relative2.startsWith(`..${path4.sep}`) && !path4.isAbsolute(relative2);
-}
-function resolveReviewArtifactPath(input, cwd) {
-  if (hasParentDirectoryTraversal(input)) {
-    return {
-      message: "Review artifact path must not contain parent-directory traversal",
-      ok: false
-    };
-  }
-  const artifactRoot = path4.resolve(cwd, ".context", "systematic", "ce-review");
-  let canonicalRoot;
-  try {
-    canonicalRoot = fs5.realpathSync(artifactRoot);
-    if (!fs5.statSync(canonicalRoot).isDirectory()) {
-      return {
-        message: "Review artifact directory is not a directory",
-        ok: false
-      };
-    }
-  } catch {
-    return { message: "Review artifact directory is unavailable", ok: false };
-  }
-  const candidate = path4.resolve(cwd, input);
-  if (pathContainsSymlink(candidate)) {
-    return {
-      message: "Review artifact path must not contain symlinks",
-      ok: false
-    };
-  }
-  let canonicalTarget;
-  try {
-    canonicalTarget = fs5.realpathSync(candidate);
-  } catch {
-    return { message: "Review artifact file was not found", ok: false };
-  }
-  if (!isWithinDirectory(canonicalTarget, canonicalRoot)) {
-    return {
-      message: "Review artifact path must remain inside .context/systematic/ce-review",
-      ok: false
-    };
-  }
-  try {
-    if (!fs5.lstatSync(canonicalTarget).isFile()) {
-      return {
-        message: "Review artifact target is not a regular file",
-        ok: false
-      };
-    }
-  } catch {
-    return { message: "Review artifact file was not found", ok: false };
-  }
-  return { ok: true, path: canonicalTarget };
-}
-function formatReviewArtifactIssuePath(issuePath) {
-  if (issuePath.length === 0)
-    return "$";
-  return issuePath.map((segment) => typeof segment === "number" ? String(segment) : segment).join(".");
-}
 function validateReviewArtifactArgument(argv) {
   const commandIndex = argv[0] === "systematic" ? 1 : 0;
   if (argv[commandIndex] !== "validate-review-artifact")
@@ -2831,25 +2854,6 @@ function validateReviewArtifactArgument(argv) {
     return;
   return argv[commandIndex + 1];
 }
-function readReviewArtifact(filePath) {
-  let content;
-  try {
-    content = fs5.readFileSync(filePath, "utf8");
-  } catch {
-    return { message: "Review artifact file could not be read", ok: false };
-  }
-  try {
-    return { ok: true, value: JSON.parse(content) };
-  } catch (error) {
-    return {
-      message: error instanceof SyntaxError ? "Review artifact contains malformed JSON" : "Review artifact file could not be read",
-      ok: false
-    };
-  }
-}
-function isLegacyReviewArtifact(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value) && !Object.hasOwn(value, "schema_version");
-}
 function runValidateReviewArtifact(options) {
   const outputSink = options.outputSink ?? ((message) => console.log(message));
   const errorSink = options.errorSink ?? ((message) => console.error(message));
@@ -2916,7 +2920,7 @@ function setupCommand(rest) {
   }
 }
 function listItems(type) {
-  const packageRoot = path4.resolve(import.meta.dirname, "..");
+  const packageRoot = path5.resolve(import.meta.dirname, "..");
   const bundledDir = packageRoot;
   let finder;
   let subdir;
@@ -2937,7 +2941,7 @@ function listItems(type) {
       console.error(`Unknown type: ${type}. Use: skills, agents, commands`);
       process.exit(1);
   }
-  const items = finder(path4.join(bundledDir, subdir));
+  const items = finder(path5.join(bundledDir, subdir));
   if (items.length === 0) {
     console.log(`No ${type} found.`);
     return;
@@ -2954,15 +2958,15 @@ function configShow() {
 `);
   console.log(`  User config:    ${paths.userConfig}`);
   console.log(`  Project config: ${paths.projectConfig}`);
-  if (fs5.existsSync(paths.projectConfig)) {
+  if (fs6.existsSync(paths.projectConfig)) {
     console.log(`
 Project configuration:`);
-    console.log(fs5.readFileSync(paths.projectConfig, "utf-8"));
+    console.log(fs6.readFileSync(paths.projectConfig, "utf-8"));
   }
-  if (fs5.existsSync(paths.userConfig)) {
+  if (fs6.existsSync(paths.userConfig)) {
     console.log(`
 User configuration:`);
-    console.log(fs5.readFileSync(paths.userConfig, "utf-8"));
+    console.log(fs6.readFileSync(paths.userConfig, "utf-8"));
   }
 }
 function configPath() {

package/dist/lib/review-artifact-path.d.ts

@@ -0,0 +1,20 @@
+export type ArtifactPathResult = {
+    readonly ok: true;
+    readonly path: string;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+export type ReadArtifactResult = {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+export declare function formatReviewArtifactIssuePath(issuePath: readonly PropertyKey[]): string;
+export declare function readReviewArtifact(filePath: string): ReadArtifactResult;
+export declare function isLegacyReviewArtifact(value: unknown): boolean;
+export declare function hasParentDirectoryTraversal(input: string): boolean;
+export declare function pathContainsSymlink(candidate: string): boolean;
+export declare function resolveReviewArtifactPath(input: string, cwd: string): ArtifactPathResult;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/systematic",
-  "version": "3.14.4",
+  "version": "3.15.0",
   "description": "Compound-engineering loops for OpenCode, Pi, and Claude Code",
   "type": "module",
   "homepage": "https://fro.bot/systematic",

package/skills/ce-compound/SKILL.md

@@ -127,20 +127,22 @@ Launch research subagents. Each returns text data to the orchestrator.
    - Identifies cross-references and links
    - Finds related GitHub issues
    - Flags any related learning or pattern docs that may now be stale, contradicted, or overly broad
-   - **Assesses overlap** with the new doc being created across five dimensions: problem statement, root cause, solution approach, referenced files, and prevention rules. Score as:
+   - **Assesses overlap** with the new doc being created across five dimensions: problem statement, root cause, solution approach, referenced files, and prevention rules. Judge each dimension as match or no-match first, then count the matches, then read the score off the count:
      - **High**: 4-5 dimensions match — essentially the same problem solved again
      - **Moderate**: 2-3 dimensions match — same area but different angle or solution
      - **Low**: 0-1 dimensions match — related but distinct
-   - Returns: Links, relationships, refresh candidates, and overlap assessment (score + which dimensions matched)
+
+     The score is a function of the count, not a separate judgment about how related the docs feel. Two docs on the same topic that match on one dimension score Low. When the score you are inclined to write disagrees with the count, the count wins.
+   - Returns: Links, relationships, refresh candidates, and overlap assessment. State the per-dimension verdicts, then the resulting count, then the score, in that order. Two consistency checks apply in sequence and both must hold: the score follows the count, and the recommendation follows the score. High overlap means update the existing doc, so an assessment that scores High while recommending a new doc has broken the second check even if the first one held. Either break is a defect to re-derive, not a nuance to note.
 
    **Search strategy (grep-first filtering for efficiency):**
 
-   1. Extract keywords from the problem context: module names, technical terms, error messages, component types
+   1. Extract keywords from the problem context: technical terms, error messages, component types. Separately, enumerate the `module:` values already in use across `docs/solutions/` and pick the one or two closest to this problem, rather than inferring a module name from the problem text. Module values are curated identifiers that often do not appear in a problem description at all, so keyword search alone will not find docs clustered under one — and docs sharing a module are among the highest-value candidates.
    2. If the problem category is clear, narrow search to the matching `docs/solutions/<category>/` directory
    3. Use the native content-search tool (e.g., Grep in OpenCode) to pre-filter candidate files BEFORE reading any content. Run multiple searches in parallel, case-insensitive, targeting frontmatter fields. These are template patterns -- substitute actual keywords:
       - `title:.*<keyword>`
       - `tags:.*(<keyword1>|<keyword2>)`
-      - `module:.*<module name>`
+      - `module:.*<module name>` — fill from the values enumerated in step 1, not from free-text keywords
       - `component:.*<component>`
    4. If search returns >25 candidates, re-run with more specific patterns. If <3, broaden to full content search
    5. Read only frontmatter (first 30 lines) of candidate files to score relevance
@@ -422,6 +424,7 @@ What's next?
 
 Overlap detected: docs/solutions/performance-issues/n-plus-one-queries.md
   Matched dimensions: problem statement, root cause, solution, referenced files
+  Count: 4 of 5 -> High
   Action: Updated existing doc with fresher code examples and prevention tips
 
 File updated:

package/skills/ce-review/references/synthesis-artifact-contract.md

@@ -210,15 +210,27 @@ validating it. This ordering makes the artifact validatable at all: without
 `schema_version`, the validator reports the legacy status (exit 3) rather than
 a real validation result.
 
-After writing `review-summary.json`, the parent checks whether the
-`systematic` executable is available on the invoking environment's `PATH`.
-When it is available, the parent runs
-`systematic validate-review-artifact <path>` against it. The executable ships
-through the npm package's `bin` entry; a harness that installs bundled
-markdown without that package will not have it. When it is unavailable, the
-parent records `validation.status: "unavailable"` and a `validation.reason` in
-the run record. When the executable is available and the parent does not run
-it, that is `validation.status: "not_attempted"`, also with a reason. The
+After writing `review-summary.json`, the parent resolves and runs a validator
+in this order: the bundled `systematic-validate-review-artifact <path>` command
+first, then the npm-installed `systematic validate-review-artifact <path>`
+command. Both can be present at once. The bundled command ships beside the
+prose being executed, so it is the one whose behavior matches the contract.
+The parent runs the first command it resolves and reads its result; it does not
+merely test whether a name is on `PATH`, because a version-manager shim can be
+present there and fail on every invocation.
+
+The command runs from the repository root. Containment resolves
+`.context/systematic/ce-review` relative to the working directory. If it runs
+elsewhere, the CLI reports that the directory is unavailable and the parent
+records that reason. This is visible degradation rather than silent success,
+so it is acceptable. If neither command is available, the parent records
+`validation.status: "unavailable"` with a reason that the validator is absent.
+If a resolved command is present but cannot be started or otherwise fails
+before returning a validation result, the parent records the same status with
+a distinct invocation-failure reason. Neither case is `failed`: that value is
+reserved for a validator that ran and found that the artifact did not conform.
+When a validator is available and the parent does not run it, that is
+`validation.status: "not_attempted"`, also with a reason. The
 `validation.status` values are `passed`, `failed`, `unavailable`, and
 `not_attempted`; `validation.reason` is required for every status except
 `passed`, where it is forbidden.