@fro.bot/systematic 3.4.1 → 3.5.1

package/dist/lib/pi-subagents-export.d.ts

@@ -0,0 +1,143 @@
+/**
+ * pi-subagents export lifecycle: resolve, preview, export, refresh, cleanup.
+ *
+ * Writes user-chosen agents dirs ($PI_CODING_AGENT_DIR/agents or
+ * <cwd>/.pi/agents). Batch-transactional with rollback: if any file write or
+ * the manifest write fails, the operation rolls back to the pre-operation
+ * state. Rollback reports any restoration failures explicitly.
+ *
+ * Manifest tracks ownership. Malformed or hostile manifests cause every
+ * lifecycle verb to refuse before mutation. No writes from module import.
+ */
+export type ExportScope = 'project' | 'global';
+/**
+ * Scope-appropriate config resolution for export/preview/refresh. When
+ * provided, the effective config (`user → project → custom` for project
+ * scope; `user → custom` for global scope — never absorbing cwd project
+ * overlays) is applied to each exported persona's frontmatter: `model`
+ * resolved from the `categories`/`agents` overlay (per-agent beats category;
+ * `model: null` omits) and Pi-native `pi_subagents` fields (`thinking`,
+ * `max_turns`, `tools`, `skills`) resolved from the `pi_subagents`
+ * namespace after trust filtering. Omitting `configOptions` preserves the
+ * model-free, config-neutral export (backward compatible default).
+ */
+export interface ExportConfigOptions {
+    scope: ExportScope;
+    cwd: string;
+}
+export declare const MANIFEST_FILENAME = ".systematic-personas.json";
+/** Exclusive per-root mutation lock. Guards export/refresh/cleanup; preview is lock-free. */
+export declare const LOCK_FILENAME = ".systematic-personas.lock";
+export interface ManifestFileEntry {
+    filename: string;
+    hash: string;
+    status: 'exported' | 'exported-with-warning';
+}
+export interface PiSubagentsManifest {
+    generatedAt: string;
+    agentsRoot: string;
+    files: ManifestFileEntry[];
+}
+/**
+ * Strict manifest read result — distinguishes absent from malformed.
+ *
+ *   absent   → no manifest file; operations proceed as first-export.
+ *   ok       → valid manifest, returned in `manifest`.
+ *   malformed → manifest file exists but is invalid (bad JSON, wrong schema,
+ *               duplicate filenames, unsafe filenames). Operations must refuse.
+ */
+export type ManifestReadResult = {
+    kind: 'absent';
+} | {
+    kind: 'ok';
+    manifest: PiSubagentsManifest;
+} | {
+    kind: 'malformed';
+    error: string;
+};
+export declare function resolveAgentsRoot(scope: ExportScope, cwd: string): string;
+/**
+ * Resolve the safety anchor for a scope: the topmost directory whose
+ * descendants (down to agentsRoot) are walked and lstat-checked for
+ * symlinks/non-directories. Never inspects ancestors above this anchor
+ * (avoids false positives from OS-level ancestor symlinks, e.g. macOS
+ * `/var` -> `/private/var`).
+ *
+ * - project: cwd
+ * - global with PI_CODING_AGENT_DIR set: the env dir's PARENT (so the env
+ *   dir itself is included in the walk and checked)
+ * - global without PI_CODING_AGENT_DIR: homedir
+ */
+export declare function resolveAnchor(scope: ExportScope, cwd: string): string;
+export declare function readManifestStrict(agentsRoot: string): ManifestReadResult;
+/**
+ * Convenience wrapper: returns the manifest for 'ok', null for 'absent', throws
+ * a structured Error for 'malformed'. Used by callers that already distinguished absent.
+ */
+export declare function readManifest(agentsRoot: string): PiSubagentsManifest | null;
+export declare function writeManifest(agentsRoot: string, manifest: PiSubagentsManifest): void;
+export interface TxResult {
+    ok: boolean;
+    error?: string;
+    rollbackFailed: string[];
+}
+/**
+ * Run a sequence of filesystem operations under snapshot/rollback protection.
+ *
+ * 1. Snapshot `pathsToWatch` (current content or absent marker).
+ * 2. Execute each `op` in order. On the first throw, stop.
+ * 3. On any failure: restore all watched paths to their snapshotted state.
+ *    Returns `{ ok: false, error, rollbackFailed }` — `rollbackFailed` lists
+ *    paths whose restoration itself failed (partial rollback, reported honestly).
+ * 4. On full success: returns `{ ok: true, rollbackFailed: [] }`.
+ *
+ * Exported for direct testing; also used by all production commit/delete paths.
+ */
+export declare function runWithRollback(pathsToWatch: string[], ops: Array<() => void>): TxResult;
+export type PlanAction = {
+    action: 'create';
+    filename: string;
+} | {
+    action: 'update';
+    filename: string;
+} | {
+    action: 'refuse';
+    filename: string;
+    reason: string;
+} | {
+    action: 'remove';
+    filename: string;
+} | {
+    action: 'skip';
+    filename: string;
+};
+export interface ExportPlan {
+    status: 'ok' | 'error';
+    error?: string;
+    agentsRoot: string;
+    actions: PlanAction[];
+}
+export declare function preview(agentsRoot: string, configOptions?: ExportConfigOptions): ExportPlan;
+export interface ExportResult {
+    status: 'ok' | 'error';
+    written: number;
+    skipped: number;
+    refused: Array<{
+        filename: string;
+        reason: string;
+    }>;
+    error?: string;
+}
+export declare function exportPersonas(agentsRoot: string, configOptions?: ExportConfigOptions): ExportResult;
+export interface RefreshResult {
+    status: 'ok' | 'error';
+    updated: number;
+    skippedUnowned: number;
+    error?: string;
+}
+export declare function refresh(agentsRoot: string, configOptions?: ExportConfigOptions): RefreshResult;
+export interface CleanupResult {
+    status: 'ok' | 'error';
+    error?: string;
+}
+export declare function cleanup(agentsRoot: string, configOptions?: ExportConfigOptions): CleanupResult;

package/dist/lib/pi-subagents-personas.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Pure persona generation logic for pi-subagents interop.
+ *
+ * Contains the curated persona list, compatibility screening, content
+ * generation, and generateAll(). Importable from both src/ and scripts/.
+ * No filesystem writes; no CLI entrypoint.
+ */
+/** Compatibility severity: info = fully usable, warning = may differ, critical = excluded. */
+export type CompatibilitySeverity = 'info' | 'warning' | 'critical';
+/** Result of classifying a persona's pi-subagents compatibility. */
+export interface CompatibilityStatus {
+    severity: CompatibilitySeverity;
+    /** Human-readable reasons for the severity (empty for info). */
+    reasons: string[];
+}
+/** Per-persona entry in the manifest. */
+export interface ManifestEntry {
+    /** Emitted filename, e.g. `systematic-best-practices-researcher.md`. */
+    filename: string;
+    /** Export status. */
+    status: 'exported' | 'exported-with-warning' | 'excluded-critical';
+    /** Repo-relative source path, e.g. `agents/research/best-practices-researcher.md`. */
+    sourceRelPath: string;
+    /** SHA-256 hex of the generated content (only for exported entries). */
+    hash: string;
+    /** Generated content (only for exported entries). */
+    content?: string;
+    /** Human-readable reason (for excluded-critical and exported-with-warning). */
+    reason?: string;
+}
+/**
+ * The authoritative curated-include list with per-persona compatibility
+ * rationale. Only personas in this list are candidates for export.
+ *
+ * Exclusion rationale (not in list):
+ *   - agents/workflow/systematic-implementer.md — CRITICAL: dispatched-by-parent assumption.
+ *   - agents/design/design-iterator.md — CRITICAL: requires agent-browser + skill load.
+ *   - agents/review/agent-native-reviewer.md — CRITICAL: Systematic/OpenCode-specific context.
+ *   - agents/review/project-standards-reviewer.md — CRITICAL: requires orchestrator <standards-paths>.
+ *   - agents/review/kieran-typescript-reviewer.md — WARNING: excluded by plan recommendation.
+ *   - agents/research/slack-researcher.md — CRITICAL: requires Slack MCP environment.
+ *   - agents/research/learnings-researcher.md — CRITICAL: references Systematic skill paths.
+ *   - agents/workflow/pr-comment-resolver.md — WARNING: "Spawned by the resolve-pr-feedback skill".
+ */
+export interface CuratedPersonaEntry {
+    relPath: string;
+    rationale: string;
+}
+export declare const CURATED_PERSONAS: CuratedPersonaEntry[];
+/**
+ * Sanitize a persona name for use as a pi-subagents filename stem.
+ * Returns empty string if no safe characters remain — callers must reject
+ * empty to avoid producing `systematic-.md`.
+ */
+export declare function sanitizeName(name: string): string;
+export declare function classifyCompatibility(content: string): CompatibilityStatus;
+export declare function generatePersonaContent(sourceRef: string, rawContent: string): string | null;
+export declare function generatePersonaManifest(sourceRelPath: string, rawContent: string, _repoRoot: string): ManifestEntry;
+/**
+ * Generate all curated personas from repoRoot/agents/.
+ * Throws on collision, new critical coupling, or read errors.
+ * Pure — no writes.
+ */
+export declare function generateAll(repoRoot: string): ManifestEntry[];

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

@@ -1,5 +1,6 @@
 import { type ReceiptClassifier } from './receipt-classifier.js';
 import type { ReceiptLedger, ReceiptOperation } from './receipt-ledger.js';
+import type { ReceiptResourceScope } from './receipt-readback.js';
 export type WorkflowMode = 'protected' | 'disabled' | 'unavailable';
 export type WorkflowState = 'protected' | 'waiting' | 'rejected' | 'disabled' | 'unavailable';
 export type RepairKind = 'fresh-readback' | 'rerun-operation' | 'question-attestation';
@@ -34,6 +35,12 @@ export interface UnitSnapshot {
     status: 'active' | 'completed';
     requiredOperations: readonly ReceiptOperation[];
     requiredResourceOperations: readonly ReceiptOperation[];
+    resourceScopes: readonly ReceiptResourceScope[];
+}
+export interface CurrentOperationContext {
+    readonly workspaceIdentity: string;
+    readonly repositoryIdentity?: string;
+    readonly worktreeIdentity?: string;
 }
 export interface WorkflowStatus {
     state: WorkflowState;
@@ -125,7 +132,14 @@ export interface WorkflowGuard {
     observeReceipt(input: unknown): EvidenceObservationResult;
     observeAttempt(input: unknown): EvidenceObservationResult;
     observeOperation(input: unknown): Promise<EvidenceObservationResult>;
+    /**
+     * Internal recovery seam. Callers MUST validate host lineage, own
+     * registration/seed/readback, stable workspace, and current mutable
+     * revisions before using this classifier-bypassing path.
+     */
+    observeTrustedRecoveredOperation(input: unknown): Promise<EvidenceObservationResult>;
     observeReadback(input: unknown): ReadbackObservationResult;
+    currentOperationContext(): CurrentOperationContext;
     status(): WorkflowStatus;
     prepareTransition(input: unknown): TransitionPrepareResult;
     finalizeTransition(input: unknown): TransitionFinalizeResult;

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

@@ -26,8 +26,11 @@
     "workflow_guard": {
       "$ref": "#/definitions/__schema57"
     },
-    "skills_as_commands": {
+    "pi_subagents": {
       "$ref": "#/definitions/__schema61"
+    },
+    "skills_as_commands": {
+      "$ref": "#/definitions/__schema72"
     }
   },
   "additionalProperties": false,
@@ -1368,16 +1371,178 @@
       "type": "boolean"
     },
     "__schema61": {
+      "default": {
+        "categories": {},
+        "agents": {}
+      },
+      "description": "Pi-native pi-subagents export field overlays (thinking, max_turns, tools, skills). Category values apply first; per-agent values override. No model field — model stays in the categories/agents overlay.",
+      "examples": [
+        {
+          "categories": {
+            "research": {
+              "thinking": "high"
+            }
+          },
+          "agents": {
+            "repo-research-analyst": {
+              "max_turns": 10
+            }
+          }
+        }
+      ],
+      "allOf": [
+        {
+          "$ref": "#/definitions/__schema62"
+        }
+      ]
+    },
+    "__schema62": {
+      "type": "object",
+      "properties": {
+        "categories": {
+          "default": {},
+          "description": "Per-category pi-subagents export overlays keyed by category name",
+          "examples": [
+            {
+              "research": {
+                "thinking": "high"
+              }
+            },
+            {}
+          ],
+          "allOf": [
+            {
+              "$ref": "#/definitions/__schema63"
+            }
+          ]
+        },
+        "agents": {
+          "default": {},
+          "description": "Per-agent pi-subagents export overlays keyed by bundled agent name",
+          "examples": [
+            {
+              "repo-research-analyst": {
+                "max_turns": 10
+              }
+            },
+            {}
+          ],
+          "allOf": [
+            {
+              "$ref": "#/definitions/__schema71"
+            }
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "__schema63": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {
+        "description": "Per-category pi-subagents export overlay (Pi-native fields only; no model)",
+        "examples": [
+          {
+            "thinking": "medium"
+          }
+        ],
+        "allOf": [
+          {
+            "$ref": "#/definitions/__schema70"
+          }
+        ]
+      }
+    },
+    "__schema64": {
+      "type": "string",
+      "enum": ["off", "minimal", "low", "medium", "high", "xhigh", "max"],
+      "description": "pi-subagents reasoning effort level for exported persona frontmatter",
+      "examples": ["off", "medium", "high"],
+      "trust": "project-or-higher"
+    },
+    "__schema65": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "pi-subagents maximum turns for a delegated persona (0 = unlimited)",
+      "examples": [0, 10, 25],
+      "trust": "any"
+    },
+    "__schema66": {
+      "type": "string",
+      "minLength": 1,
+      "description": "pi-subagents comma-selector tool string (built-ins, */all/none, or extension selectors)",
+      "examples": ["*", "read,grep,glob", "none"],
+      "trust": "project-or-higher"
+    },
+    "__schema67": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/__schema68"
+        },
+        {
+          "$ref": "#/definitions/__schema69"
+        }
+      ],
+      "description": "pi-subagents skills selector: true (all) or a comma-separated list of skill names",
+      "examples": [true, "ce:plan,ce:review"],
+      "trust": "project-or-higher"
+    },
+    "__schema68": {
+      "type": "boolean",
+      "const": true
+    },
+    "__schema69": {
+      "type": "string",
+      "minLength": 1
+    },
+    "__schema70": {
+      "type": "object",
+      "properties": {
+        "thinking": {
+          "$ref": "#/definitions/__schema64"
+        },
+        "max_turns": {
+          "$ref": "#/definitions/__schema65"
+        },
+        "tools": {
+          "$ref": "#/definitions/__schema66"
+        },
+        "skills": {
+          "$ref": "#/definitions/__schema67"
+        }
+      },
+      "additionalProperties": false,
+      "description": "Per-agent pi-subagents export overlay (Pi-native fields only; no model)",
+      "examples": [
+        {
+          "thinking": "high",
+          "max_turns": 10
+        }
+      ]
+    },
+    "__schema71": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {
+        "$ref": "#/definitions/__schema70"
+      }
+    },
+    "__schema72": {
       "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/__schema62"
+          "$ref": "#/definitions/__schema73"
         }
       ]
     },
-    "__schema62": {
+    "__schema73": {
       "type": "boolean"
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/systematic",
-  "version": "3.4.1",
+  "version": "3.5.1",
   "description": "Compound-engineering loops for OpenCode, Pi, and Claude Code",
   "type": "module",
   "homepage": "https://fro.bot/systematic",
@@ -90,11 +90,12 @@
     }
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.5",
+    "@biomejs/biome": "2.5.6",
     "@earendil-works/pi-coding-agent": "0.80.10",
-    "@opencode-ai/plugin": "1.18.5",
-    "@opencode-ai/sdk": "1.18.5",
+    "@opencode-ai/plugin": "1.18.8",
+    "@opencode-ai/sdk": "1.18.8",
     "@semantic-release/exec": "7.1.0",
+    "@tintinweb/pi-subagents": "0.14.3",
     "@types/bun": "latest",
     "@types/js-yaml": "4.0.9",
     "@types/node": "24.13.3",

package/skills/using-systematic/references/pi-profile.md

@@ -4,14 +4,14 @@ Evidence registry: see [`HARNESSES.md`](../../../HARNESSES.md).
 
 | Capability | Mechanism | Status | Fallback |
 |---|---|---|---|
-| Subagent delegation | `systematic_delegate({agent, task})` with bundled personas | degraded; execution is sequential only | Dispatch sequentially in dependency order or do the work inline |
+| Subagent delegation | Bounded built-in delegate via `systematic_delegate({agent, task})`; optional mature delegation via [pi-subagents](https://github.com/tintinweb/pi-subagents) through opt-in persona export | built-in: degraded (sequential only); pi-subagents path: outside Systematic's bounded-delegate guarantees | Dispatch sequentially in dependency order or do the work inline |
 | Blocking user interaction | No native blocking tool | degraded | Present numbered options in chat and wait |
 | Task tracking | No native task-tracking mechanism | unavailable | Maintain a visible task list in responses |
 | Skill loading | `systematic_skill` tool or Pi-native skill activation | supported | Read the skill instructions listed by the active harness |
 
 ## Invocation examples
 
-### Subagent delegation
+### Subagent delegation (built-in)
 
 ```typescript
 systematic_delegate({
@@ -20,6 +20,32 @@ systematic_delegate({
 })
 ```
 
+`systematic_delegate` is sequential, capped at 20 turns, depth-1, and spawns its child with `noExtensions: true`. The `noExtensions` guarantee bounds `systematic_delegate`'s own recursion — it does not bound end-to-end delegation depth across a combined pi-subagents + Systematic path.
+
+### Optional: pi-subagents delegation
+
+Export Systematic personas for use with [pi-subagents](https://github.com/tintinweb/pi-subagents) (parallel/multi-model delegation). All writes are opt-in; nothing is exported at extension load.
+
+Tested against pi-subagents v0.14.3 (verified contract as of July 29, 2026). Versions outside the tested range are unsupported but nonfatal.
+
+Exact CLI form: `systematic pi-subagents <preview|export|refresh|cleanup> --scope project|global`. `--scope` is optional and defaults to `project`.
+
+```bash
+systematic pi-subagents preview [--scope project|global]
+systematic pi-subagents export  [--scope project|global]
+systematic pi-subagents refresh [--scope project|global]
+systematic pi-subagents cleanup [--scope project|global]
+```
+
+- `project` (default) targets `<cwd>/.pi/agents/`.
+- `global` targets `$PI_CODING_AGENT_DIR/agents/`, or `~/.pi/agent/agents/` if `$PI_CODING_AGENT_DIR` is unset.
+
+The pi-subagents delegation path is **outside Systematic's bounded-delegate guarantees** and governed by pi-subagents' own configuration. `systematic_delegate` remains the bounded default.
+
+`export`/`refresh`/`cleanup` hold an exclusive per-root mutation lock and fail closed if any path component between the selected scope's anchor and the agents directory is a symlink or not a directory. A manifest (`.systematic-personas.json`) tracks ownership by filename and content hash; cleanup and stale-file removal only delete a file whose on-disk content still matches its recorded hash, refusing otherwise. Manifest hashes are drift evidence, not a cryptographic authenticity guarantee.
+
+Systematic's own config (`systematic.json`/`.jsonc`) is the durable source of truth for exported personas; the generated files and their manifest are a disposable projection that `export`/`refresh`/`cleanup` regenerate or remove, and `refresh` intentionally overwrites manifest-owned generated files that diverge from current config — run `preview` first to see what would change. See the [pi-subagents pairing guide](https://fro.bot/systematic/guides/pi-subagents/) for the config precedence, trust boundaries, and a canonical example.
+
 ### Blocking user interaction
 
 ```text