@fro.bot/systematic 3.16.2 → 3.16.4

package/dist/cli.d.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { type CapabilityClock, type CapabilityOutputSink, type ConfigObservationMetadata } from './lib/capability-snapshot.js';
-interface CapabilityCliRoots {
+export interface CapabilityCliRoots {
     readonly agentsRoot: string;
     readonly cwd: string;
     readonly homeDir: string;

package/dist/cli.js

@@ -2085,6 +2085,23 @@ function isLegacyReviewArtifact(value) {
 function hasParentDirectoryTraversal(input) {
   return input.split(/[\\/]+/).some((segment) => segment === "..");
 }
+var ALLOW_OUTSIDE_ARTIFACT_ROOT_FLAG = "--allow-outside-artifact-root";
+var VALIDATE_REVIEW_ARTIFACT_USAGE = "Usage: systematic validate-review-artifact <path> [--allow-outside-artifact-root]";
+function parseValidateReviewArtifactArguments(argv) {
+  const allowOutsideArtifactRoot = argv.includes(ALLOW_OUTSIDE_ARTIFACT_ROOT_FLAG);
+  const positional = argv.filter((arg) => arg !== ALLOW_OUTSIDE_ARTIFACT_ROOT_FLAG);
+  if (positional.length !== 1)
+    return;
+  const path = positional[0];
+  if (path === undefined)
+    return;
+  return { allowOutsideArtifactRoot, path };
+}
+var REVIEW_ARTIFACT_VALID_MESSAGE = "Review artifact is valid";
+var REVIEW_ARTIFACT_VALID_EXTERNAL_MESSAGE = "Review artifact is valid (validated outside the run directory; not evidence for this run)";
+function formatReviewArtifactSuccessMessage(allowOutsideArtifactRoot) {
+  return allowOutsideArtifactRoot ? REVIEW_ARTIFACT_VALID_EXTERNAL_MESSAGE : REVIEW_ARTIFACT_VALID_MESSAGE;
+}
 function pathContainsSymlink(candidate) {
   let current = path3.parse(candidate).root;
   const relative = path3.relative(current, candidate);
@@ -2105,30 +2122,33 @@ function isWithinDirectory(candidate, directory) {
   const relative = path3.relative(directory, candidate);
   return relative !== "" && relative !== ".." && !relative.startsWith(`..${path3.sep}`) && !path3.isAbsolute(relative);
 }
-function resolveReviewArtifactPath(input, cwd) {
+function resolveReviewArtifactPath(input, cwd, options = {}) {
+  const allowOutsideArtifactRoot = options.allowOutsideArtifactRoot ?? false;
   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
-      };
+  if (!allowOutsideArtifactRoot) {
+    const artifactRoot = path3.resolve(cwd, ".context", "systematic", "ce-review");
+    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 };
     }
-  } 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",
+      message: "Review artifact path must not contain symlinks; pass a fully resolved path",
       ok: false
     };
   }
@@ -2138,7 +2158,7 @@ function resolveReviewArtifactPath(input, cwd) {
   } catch {
     return { message: "Review artifact file was not found", ok: false };
   }
-  if (!isWithinDirectory(canonicalTarget, canonicalRoot)) {
+  if (canonicalRoot !== undefined && !isWithinDirectory(canonicalTarget, canonicalRoot)) {
     return {
       message: "Review artifact path must remain inside .context/systematic/ce-review",
       ok: false
@@ -2721,9 +2741,12 @@ Usage:
 Commands:
   list [type]                  List available skills, agents, or commands
   capabilities                 Read-only standalone-CLI observation; not a host-runtime or canonical-registry view
-  validate-review-artifact <path>
+  validate-review-artifact <path> [--allow-outside-artifact-root]
                                Validate a ce:review run artifact
                                The <path> argument is required by design; no artifact discovery is performed.
+                               --allow-outside-artifact-root skips the requirement that <path> resolve
+                               inside .context/systematic/ce-review, for validating artifacts copied from
+                               CI, issues, or fixtures. Not for the ce:review parent's own run artifact.
                                Exit statuses: 0 valid artifact, 1 validation failure,
                                2 operational failure, 3 legacy artifact with no schema_version
   config [subcommand]          Configuration management
@@ -2744,6 +2767,7 @@ Examples:
   systematic list skills
   systematic capabilities
   systematic validate-review-artifact .context/systematic/ce-review/review-summary.json
+  systematic validate-review-artifact --allow-outside-artifact-root /path/to/external-artifact.json
   systematic list agents
   systematic config show
   systematic config show --json
@@ -2774,7 +2798,6 @@ Scope:
   project   <cwd>/.pi/agents (default)
   global    $PI_CODING_AGENT_DIR/agents or ~/.pi/agent/agents
 `;
-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 ? path5.join(process.env.XDG_CONFIG_HOME, "opencode") : path5.join(os2.homedir(), ".config/opencode");
@@ -2935,19 +2958,17 @@ function validateReviewArtifactArgument(argv) {
   const commandIndex = argv[0] === "systematic" ? 1 : 0;
   if (argv[commandIndex] !== "validate-review-artifact")
     return;
-  if (argv.length !== commandIndex + 2)
-    return;
-  return argv[commandIndex + 1];
+  return parseValidateReviewArtifactArguments(argv.slice(commandIndex + 1));
 }
 function runValidateReviewArtifact(options) {
   const outputSink = options.outputSink ?? ((message) => console.log(message));
   const errorSink = options.errorSink ?? ((message) => console.error(message));
-  const input = validateReviewArtifactArgument(options.argv);
-  if (input === undefined) {
+  const parsedArgs = validateReviewArtifactArgument(options.argv);
+  if (parsedArgs === undefined) {
     errorSink(VALIDATE_REVIEW_ARTIFACT_USAGE);
     return 2;
   }
-  const resolved = resolveReviewArtifactPath(input, options.cwd ?? process.cwd());
+  const resolved = resolveReviewArtifactPath(parsedArgs.path, options.cwd ?? process.cwd(), { allowOutsideArtifactRoot: parsedArgs.allowOutsideArtifactRoot });
   if (!resolved.ok) {
     errorSink(resolved.message);
     return 2;
@@ -2972,7 +2993,7 @@ function runValidateReviewArtifact(options) {
     errorSink(`Review artifact validation failed: ${result.error.issues.length} issue(s)`);
     return 1;
   }
-  outputSink("Review artifact is valid");
+  outputSink(formatReviewArtifactSuccessMessage(parsedArgs.allowOutsideArtifactRoot));
   return 0;
 }
 function runValidateReviewArtifactCli(options) {

package/dist/index.js

@@ -11803,7 +11803,7 @@ function createSessionRuntime(options, operationObservers, recoveredOperationCon
       result.satisfiedCount = source.debug.satisfiedCount;
       result.missingCount = source.debug.missingCount;
       result.family = source.debug.family;
-      result.status = source.debug.status;
+      result.debugEpochStatus = source.debug.status;
     }
     return result;
   }
@@ -11845,10 +11845,12 @@ function createSessionRuntime(options, operationObservers, recoveredOperationCon
   function writeCompletionResult(output, result, target) {
     if (!isRecord7(output))
       return;
+    const existingMetadata = isRecord7(output.metadata) ? output.metadata : {};
     if (result.status === "completed" || result.status === "duplicate") {
       output.title = "Workflow transition completed";
       output.output = `workflow guard completed ${target}`;
       output.metadata = {
+        ...existingMetadata,
         ...metadata2(),
         workflowGuard: { status: "completed", target }
       };
@@ -11862,6 +11864,7 @@ function createSessionRuntime(options, operationObservers, recoveredOperationCon
       reasonCode
     });
     output.metadata = {
+      ...existingMetadata,
       ...metadata2(),
       workflowGuard: {
         status: resultStatus,
@@ -11870,6 +11873,19 @@ function createSessionRuntime(options, operationObservers, recoveredOperationCon
       }
     };
   }
+  function writeAbandonedCompletionResult(output, target, reasonCode) {
+    writeCompletionResult(output, { target, status: "unavailable", reasonCode }, target);
+  }
+  function writeAbandonedCompletionMetadata(output, target, reasonCode) {
+    if (!isRecord7(output))
+      return;
+    const existingMetadata = isRecord7(output.metadata) ? output.metadata : {};
+    output.metadata = {
+      ...existingMetadata,
+      ...metadata2(),
+      workflowGuard: { status: "unavailable", target, reasonCode }
+    };
+  }
   function prepareSkill(host, args2) {
     const skill = normalizeSkill(host.tool, args2);
     if (!skill)
@@ -12286,6 +12302,7 @@ function createSessionRuntime(options, operationObservers, recoveredOperationCon
         callId: pending.callID,
         transitionId: pending.transitionId
       });
+      writeAbandonedCompletionMetadata(output, pending.target, "failed-operation");
       return;
     }
     const result = guard.finalizeTransition({
@@ -12440,19 +12457,32 @@ function createSessionRuntime(options, operationObservers, recoveredOperationCon
     }
     return readbacks;
   }
+  function finishMismatchedTarget(callDigest, pending, output) {
+    abandonComplete(callDigest, pending, false);
+    markUnavailable();
+    writeAbandonedCompletionResult(output, pending.target, "invalid-transition");
+  }
+  function finishUnreplayableComplete(finalTarget, output) {
+    markUnavailable();
+    writeAbandonedCompletionResult(output, finalTarget ?? "unit", "guard-unavailable");
+  }
+  function finishUnavailableReadback(callDigest, pending, output) {
+    abandonComplete(callDigest, pending, true);
+    markUnavailable();
+    writeAbandonedCompletionResult(output, pending.target, "finalization-failed");
+  }
   async function finishComplete(host, output) {
     const callDigest = digestCall(ledger, host.callID);
     const pending = pendingCompletes.get(callDigest);
     const finalTarget = normalizeTarget(host.args);
     if (pending && (!finalTarget || finalTarget !== pending.target)) {
-      abandonComplete(callDigest, pending, false);
-      markUnavailable();
+      finishMismatchedTarget(callDigest, pending, output);
       return;
     }
     if (!pending) {
       if (replayTerminalComplete(callDigest, finalTarget, output))
         return;
-      markUnavailable();
+      finishUnreplayableComplete(finalTarget, output);
       return;
     }
     if (!options.observer) {
@@ -12461,8 +12491,7 @@ function createSessionRuntime(options, operationObservers, recoveredOperationCon
     }
     const readbacks = await completionReadbacks();
     if (readbacks.status === "unavailable") {
-      abandonComplete(callDigest, pending, true);
-      markUnavailable();
+      finishUnavailableReadback(callDigest, pending, output);
       return;
     }
     finalizeComplete(callDigest, pending, output, readbacks.status === "ready" ? readbacks.readbacks : undefined);

package/dist/lib/config-handler.d.ts

@@ -1,4 +1,6 @@
 import type { Config } from '@opencode-ai/plugin';
+import type { AgentConfig } from '@opencode-ai/sdk';
+import { type PermissionSetting } from './validation.js';
 export interface ConfigHandlerDeps {
     directory: string;
     bundledSkillsDir: string;
@@ -11,6 +13,41 @@ export interface ConfigHandlerDeps {
 }
 export declare function toTitleCase(name: string): string;
 export declare function formatAgentDescription(name: string, description: string | undefined): string;
+/**
+ * Per-tool permission rule map as actually emitted by {@link permissionFromRules}:
+ * each key is a match pattern (`'*'` or an exact name) mapped to a setting.
+ */
+export type AgentPermissionRuleMap = Record<string, PermissionSetting>;
+/**
+ * Agent permission shape as emitted onto `AgentConfig.permission`, narrowed at
+ * this module's boundary to include `skill`. The `@opencode-ai/sdk` v1 `Config`
+ * type this module targets omits `skill` from `AgentConfig['permission']`
+ * (it only appears on the SDK's v2 `PermissionRuleConfig` surface), but
+ * `applyPermissionOverlay`/`addManagedSkillRules` genuinely write a `skill`
+ * rule map identical in shape to `bash`. This type documents and reads that
+ * real runtime shape without migrating the module to the v2 type surface.
+ *
+ * `permissionFromRules` emits a rule map for whatever tool key gets passed to
+ * `setPermissionRule` — not just the named keys below (e.g. `task`, per
+ * `PermissionConfig` in validation.ts and the `task` overlay field applied at
+ * config-handler.ts's overlay pass). The named keys stay for documentation of
+ * the common cases; the index signature covers every other emitted tool key.
+ */
+export interface EmittedAgentPermission {
+    edit?: AgentPermissionRuleMap;
+    bash?: AgentPermissionRuleMap;
+    webfetch?: AgentPermissionRuleMap;
+    doom_loop?: AgentPermissionRuleMap;
+    external_directory?: AgentPermissionRuleMap;
+    skill?: AgentPermissionRuleMap;
+    readonly [tool: string]: AgentPermissionRuleMap | undefined;
+}
+/**
+ * Read an agent's emitted permission map, narrowed to include `skill` (see
+ * {@link EmittedAgentPermission}). Use this instead of `AgentConfig['permission']`
+ * when a caller needs to observe the `skill` rule map this module writes.
+ */
+export declare function readEmittedAgentPermission(agent: AgentConfig | undefined): EmittedAgentPermission | undefined;
 /**
  * Create the config hook handler for the Systematic plugin.
  *

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

@@ -16,5 +16,16 @@ export declare function formatReviewArtifactIssuePath(issuePath: readonly Proper
 export declare function readReviewArtifact(filePath: string): ReadArtifactResult;
 export declare function isLegacyReviewArtifact(value: unknown): boolean;
 export declare function hasParentDirectoryTraversal(input: string): boolean;
+export declare const ALLOW_OUTSIDE_ARTIFACT_ROOT_FLAG = "--allow-outside-artifact-root";
+export declare const VALIDATE_REVIEW_ARTIFACT_USAGE = "Usage: systematic validate-review-artifact <path> [--allow-outside-artifact-root]";
+export interface ValidateReviewArtifactArguments {
+    readonly path: string;
+    readonly allowOutsideArtifactRoot: boolean;
+}
+export declare function parseValidateReviewArtifactArguments(argv: readonly string[]): ValidateReviewArtifactArguments | undefined;
+export declare function formatReviewArtifactSuccessMessage(allowOutsideArtifactRoot: boolean): string;
 export declare function pathContainsSymlink(candidate: string): boolean;
-export declare function resolveReviewArtifactPath(input: string, cwd: string): ArtifactPathResult;
+export interface ResolveReviewArtifactPathOptions {
+    readonly allowOutsideArtifactRoot?: boolean;
+}
+export declare function resolveReviewArtifactPath(input: string, cwd: string, options?: ResolveReviewArtifactPathOptions): ArtifactPathResult;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/systematic",
-  "version": "3.16.2",
+  "version": "3.16.4",
   "description": "Compound-engineering loops for OpenCode, Pi, and Claude Code",
   "type": "module",
   "homepage": "https://fro.bot/systematic",
@@ -40,6 +40,8 @@
     "test:integration": "bun test tests/integration",
     "test:all": "bun test",
     "typecheck": "tsc --noEmit",
+    "typecheck:scripts": "tsc -p tsconfig.scripts.json",
+    "typecheck:all": "tsc -p tsconfig.tests.json",
     "lint": "biome check .",
     "fix": "bun run lint --fix",
     "docs:dev": "bun run --cwd docs dev",
@@ -93,10 +95,10 @@
     }
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.11",
+    "@biomejs/biome": "2.5.12",
     "@earendil-works/pi-coding-agent": "0.83.0",
-    "@opencode-ai/plugin": "1.18.21",
-    "@opencode-ai/sdk": "1.18.21",
+    "@opencode-ai/plugin": "1.18.27",
+    "@opencode-ai/sdk": "1.18.27",
     "@semantic-release/exec": "7.1.0",
     "@tintinweb/pi-subagents": "0.14.3",
     "@types/bun": "latest",

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

@@ -247,6 +247,18 @@ validation, and it does not delete the artifact to escape the check. A failing
 artifact is evidence and stays on disk; an absent artifact is never evidence
 of a clean run.
 
+Both commands also accept `--allow-outside-artifact-root`, which skips the
+containment check so a copy fetched from CI, an issue attachment, or a fixture
+can be validated from outside `.context/systematic/ce-review`. It also drops
+the requirement that `.context/systematic/ce-review` exist at all. That is not
+a workaround for the "directory is unavailable" degradation described above:
+that degradation is deliberate visible failure for the parent's own run
+artifact, and the flag does not change how the parent's own validation run is
+judged. This is an external-validation mode for artifacts the parent did not
+just produce. The parent must never pass this flag when validating its own
+run's `review-summary.json`; doing so would silently accept a mismatched or
+misplaced artifact as this run's evidence.
+
 This is enforcement by visible failure, not by containment. An agent that
 never runs the command can still finalize an artifact, but produces no evidence
 in either direction. That is why the command exists as an independently