@fro.bot/systematic 3.2.8 → 3.3.1

package/dist/lib/workflow-guard.d.ts

@@ -0,0 +1,136 @@
+import { type ReceiptClassifier } from './receipt-classifier.js';
+import type { ReceiptLedger, ReceiptOperation } from './receipt-ledger.js';
+export type WorkflowMode = 'protected' | 'disabled' | 'unavailable';
+export type WorkflowState = 'protected' | 'waiting' | 'rejected' | 'disabled' | 'unavailable';
+export type RepairKind = 'fresh-readback' | 'rerun-operation' | 'question-attestation';
+export type TransitionTarget = 'unit' | 'epoch';
+export type EpochFamily = 'work' | 'shipping';
+export type WorkflowReasonCode = 'abandoned-transition' | 'call-context-conflict' | 'cancelled-operation' | 'consumed-receipt' | 'disabled' | 'epoch-completed' | 'epoch-mismatch' | 'failed-operation' | 'family-conflict' | 'finalization-failed' | 'foreign-registration' | 'forbidden-field' | 'guard-unavailable' | 'incompatible-receipt' | 'invalid-configuration' | 'invalid-control' | 'invalid-receipt' | 'invalid-transition' | 'missing-evidence' | 'no-supported-repair' | 'no-active-epoch' | 'no-active-unit' | 'no-op-operation' | 'operation-not-required' | 'receipt-mismatch' | 'rejected-operation' | 'resource-mismatch' | 'running-operation' | 'stale-receipt' | 'transition-finalized' | 'transition-terminal' | 'transition-replayed' | 'unattributed-operation' | 'unit-active' | 'unit-completed' | 'unit-incomplete' | 'unit-mismatch' | 'unit-ready' | 'workspace-mismatch' | 'runtime-scope-conflict' | 'invalid-recovery' | 'recovery-conflict' | 'fork-copy-not-lineage';
+export interface WorkflowGuardOptions {
+    ledger: ReceiptLedger;
+    classifier?: ReceiptClassifier;
+    workspaceIdentity: string;
+    repositoryIdentity?: string;
+    worktreeIdentity?: string;
+    supportedRepairs?: readonly RepairKind[];
+    questionEligibleOperations?: readonly ReceiptOperation[];
+    runtimeRequiredOperations?: readonly ReceiptOperation[];
+    runtimeResourceScopes?: Readonly<Record<string, string>>;
+    mode?: WorkflowMode;
+    maxReceiptAgeMs?: number;
+    clock?: () => number;
+}
+export interface RuntimeUnitPolicy {
+    requiredOperations?: readonly ReceiptOperation[];
+    resourceScopes?: Readonly<Record<string, string>>;
+}
+export interface EpochSnapshot {
+    epochId: string;
+    family: EpochFamily;
+    status: 'active' | 'completed';
+}
+export interface UnitSnapshot {
+    unitId: string;
+    status: 'active' | 'completed';
+    requiredOperations: readonly ReceiptOperation[];
+    requiredResourceOperations: readonly ReceiptOperation[];
+}
+export interface WorkflowStatus {
+    state: WorkflowState;
+    reasonCode: WorkflowReasonCode;
+    repair?: RepairKind;
+    statusKey: string;
+    epoch: EpochSnapshot | null;
+    unit: UnitSnapshot | null;
+    satisfiedOperations: readonly ReceiptOperation[];
+    missingOperations: readonly ReceiptOperation[];
+}
+export type ActivationResult = {
+    status: 'activated' | 'reused' | 'attached';
+    epoch: EpochSnapshot;
+} | {
+    status: 'ignored';
+    reasonCode: WorkflowReasonCode;
+} | {
+    status: 'rejected';
+    reasonCode: WorkflowReasonCode;
+};
+export type StartUnitResult = {
+    status: 'started';
+    unit: UnitSnapshot;
+} | {
+    status: 'rejected';
+    reasonCode: WorkflowReasonCode;
+};
+export type EvidenceObservationResult = {
+    status: 'accepted';
+    operation: ReceiptOperation;
+} | {
+    status: 'rejected';
+    reasonCode: WorkflowReasonCode;
+} | {
+    status: 'unavailable';
+    reasonCode: WorkflowReasonCode;
+};
+export type ReadbackObservationResult = {
+    status: 'accepted';
+    changed: boolean;
+} | {
+    status: 'rejected';
+    reasonCode: WorkflowReasonCode;
+};
+export type TransitionPrepareResult = {
+    status: 'allowed';
+    transitionId: string;
+} | {
+    status: 'waiting' | 'rejected' | 'unavailable';
+    reasonCode: WorkflowReasonCode;
+};
+export type TransitionFinalizeResult = {
+    status: 'completed' | 'duplicate';
+    target: TransitionTarget;
+    transitionId: string;
+} | {
+    status: 'waiting' | 'rejected' | 'unavailable';
+    reasonCode: WorkflowReasonCode;
+};
+export type AbandonTransitionResult = {
+    status: 'abandoned';
+} | {
+    status: 'duplicate';
+    reasonCode: 'abandoned-transition';
+} | {
+    status: 'rejected';
+    reasonCode: WorkflowReasonCode;
+};
+export type ControlResult = {
+    status: 'changed' | 'unchanged';
+    mode: WorkflowMode;
+} | {
+    status: 'rejected';
+    reasonCode: WorkflowReasonCode;
+};
+export type WorkflowRecoveryResult = {
+    status: 'restored' | 'duplicate';
+    provenance: 'restart';
+    epoch: EpochSnapshot;
+    unit: UnitSnapshot | null;
+} | {
+    status: 'rejected';
+    reasonCode: WorkflowReasonCode;
+};
+export interface WorkflowGuard {
+    activate(input: unknown): ActivationResult;
+    startUnit(input: unknown, policy?: RuntimeUnitPolicy): StartUnitResult;
+    observeReceipt(input: unknown): EvidenceObservationResult;
+    observeAttempt(input: unknown): EvidenceObservationResult;
+    observeOperation(input: unknown): Promise<EvidenceObservationResult>;
+    observeReadback(input: unknown): ReadbackObservationResult;
+    status(): WorkflowStatus;
+    prepareTransition(input: unknown): TransitionPrepareResult;
+    finalizeTransition(input: unknown): TransitionFinalizeResult;
+    abandonTransition(input: unknown): AbandonTransitionResult;
+    restore(input: unknown): WorkflowRecoveryResult;
+    setMode(input: unknown): ControlResult;
+}
+export declare function createWorkflowGuard(options: WorkflowGuardOptions): WorkflowGuard;

package/dist/schemas/systematic-config.schema.json

@@ -23,8 +23,11 @@
     "bootstrap": {
       "$ref": "#/definitions/__schema51"
     },
-    "skills_as_commands": {
+    "workflow_guard": {
       "$ref": "#/definitions/__schema57"
+    },
+    "skills_as_commands": {
+      "$ref": "#/definitions/__schema61"
     }
   },
   "additionalProperties": false,
@@ -1314,16 +1317,67 @@
       "type": "string"
     },
     "__schema57": {
+      "default": {
+        "mode": "observe",
+        "debug": false
+      },
+      "description": "Workflow guard configuration",
+      "examples": [
+        {
+          "mode": "observe",
+          "debug": false
+        }
+      ],
+      "allOf": [
+        {
+          "$ref": "#/definitions/__schema58"
+        }
+      ]
+    },
+    "__schema58": {
+      "type": "object",
+      "properties": {
+        "mode": {
+          "default": "observe",
+          "description": "Workflow guard mode",
+          "examples": ["observe", "protected", "disabled"],
+          "allOf": [
+            {
+              "$ref": "#/definitions/__schema59"
+            }
+          ]
+        },
+        "debug": {
+          "default": false,
+          "description": "Enable workflow guard debugging",
+          "examples": [false, true],
+          "allOf": [
+            {
+              "$ref": "#/definitions/__schema60"
+            }
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "__schema59": {
+      "type": "string",
+      "enum": ["observe", "protected", "disabled"]
+    },
+    "__schema60": {
+      "type": "boolean"
+    },
+    "__schema61": {
       "default": true,
       "description": "Register skills discovered from user/project skill directories (OpenCode config and other agent-harness-standard locations) as slash commands. Default true.",
       "examples": [true, false],
       "allOf": [
         {
-          "$ref": "#/definitions/__schema58"
+          "$ref": "#/definitions/__schema62"
         }
       ]
     },
-    "__schema58": {
+    "__schema62": {
       "type": "boolean"
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/systematic",
-  "version": "3.2.8",
+  "version": "3.3.1",
   "description": "Structured engineering workflows for OpenCode",
   "type": "module",
   "homepage": "https://fro.bot/systematic",
@@ -103,12 +103,14 @@
     "rimraf": "6.1.3",
     "semantic-release": "25.0.8",
     "semantic-release-export-data": "1.2.0",
-    "typebox": "1.3.6",
+    "typebox": "1.3.8",
     "typescript": "6.0.3"
   },
   "dependencies": {
     "js-yaml": "^4.1.1",
     "jsonc-parser": "^3.3.0",
+    "tree-sitter-bash": "0.25.1",
+    "web-tree-sitter": "0.25.10",
     "zod": "4.4.3"
   },
   "overrides": {