@fro.bot/systematic 3.14.5 → 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.5",
+  "version": "3.15.0",
   "description": "Compound-engineering loops for OpenCode, Pi, and Claude Code",
   "type": "module",
   "homepage": "https://fro.bot/systematic",

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.