snipara-companion 3.3.0 → 3.4.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 Release notes for `snipara-companion`, newest first.
 
+## New In 3.4.0
+
+- Adds repeatable `workers execute --output-fragment` contracts.
+- Fails a worker receipt closed when declared output fragments are missing,
+  while preserving explicit approval, proof, and Git scope gates.
+- Persists missing output fragments in the receipt for review and calibration.
+
 ## New In 3.3.0
 
 - Adds reviewed, scoped Worker Trust Promotion commands: `workers trust

package/dist/index.d.ts

@@ -4575,6 +4575,7 @@ interface ControlledWorkerExecuteOptions {
     writeScope?: string[];
     acceptance?: string[];
     proof?: string[];
+    outputFragments?: string[];
     workCategory?: WorkerTrustCategory;
     trustEvent?: string;
     profileHash?: string;

package/dist/index.js

@@ -11247,6 +11247,8 @@ function buildControlledWorkerExecutionReceipt(input) {
   const writeScope = uniqueStrings9(input.writeScope ?? []);
   const acceptanceCriteria = uniqueStrings9(input.acceptanceCriteria ?? []);
   const proofRequired = uniqueStrings9(input.proofRequired ?? []);
+  const outputFragments = uniqueStrings9(input.outputFragments ?? []);
+  const missingOutputFragments = uniqueStrings9(input.missingOutputFragments ?? []);
   const reasonCodes = /* @__PURE__ */ new Set([
     "controlled_worker_execution_v0",
     `controlled_worker_execution_${mode}`,
@@ -11266,6 +11268,8 @@ function buildControlledWorkerExecutionReceipt(input) {
     writeScope,
     acceptanceCriteria,
     proofRequired,
+    outputFragments,
+    missingOutputFragments,
     approvalReceiptId: input.approvalReceiptId ?? null,
     outcomeReceiptId: input.outcomeReceiptId ?? null,
     command,
@@ -11282,6 +11286,9 @@ function buildControlledWorkerExecutionReceipt(input) {
   if (acceptanceCriteria.length === 0) {
     reasonCodes.add("controlled_worker_execution_missing_acceptance");
   }
+  if (missingOutputFragments.length > 0) {
+    reasonCodes.add("controlled_worker_execution_output_contract_failed");
+  }
   return {
     version: CONTROLLED_WORKER_EXECUTION_RECEIPT_VERSION,
     receiptId: `worker-exec-${receiptHash.slice(0, 16)}`,
@@ -11294,6 +11301,8 @@ function buildControlledWorkerExecutionReceipt(input) {
       writeScope,
       acceptanceCriteria,
       proofRequired,
+      outputFragments,
+      missingOutputFragments,
       approvalReceiptId: input.approvalReceiptId ?? null,
       outcomeReceiptId: input.outcomeReceiptId ?? null
     },
@@ -29914,6 +29923,7 @@ function controlledWorkerExecuteCommand(options) {
   const execute = Boolean(options.execute);
   const mode = normalizeMode(options.mode, execute);
   const commandArgs = normalizeCommandArgs(options.commandArgs);
+  const outputFragments = normalizeOutputFragments(options.outputFragments);
   const legacyCommand = stringValue8(options.command);
   const command = commandArgs.length > 0 ? commandArgs.join(" ") : legacyCommand;
   const risk = command ? commandRisk(command) : "none";
@@ -29959,6 +29969,7 @@ function controlledWorkerExecuteCommand(options) {
   let executionAttempted = false;
   let changedFiles = [];
   let scopeViolations = [];
+  let missingOutputFragments = [];
   if (execute) reasonCodes.add("controlled_worker_execution_requested");
   if (!execute) reasonCodes.add("controlled_worker_execution_dry_run_only");
   if (missingApproval) reasonCodes.add("controlled_worker_execution_missing_approval");
@@ -29996,6 +30007,13 @@ function controlledWorkerExecuteCommand(options) {
     exitCode = typeof result2.status === "number" ? result2.status : 1;
     stdout = result2.stdout ?? "";
     stderr = result2.stderr ?? "";
+    missingOutputFragments = outputFragments.filter(
+      (fragment) => !normalizeComparableText(stdout).includes(normalizeComparableText(fragment))
+    );
+    if (missingOutputFragments.length > 0) {
+      blocked = true;
+      reasonCodes.add("controlled_worker_execution_output_contract_failed");
+    }
     reasonCodes.add(
       exitCode === 0 ? "controlled_worker_execution_command_succeeded" : "controlled_worker_execution_command_failed"
     );
@@ -30030,6 +30048,8 @@ function controlledWorkerExecuteCommand(options) {
     writeScope: options.writeScope,
     acceptanceCriteria: options.acceptance,
     proofRequired: options.proof,
+    outputFragments,
+    missingOutputFragments,
     approvalReceiptId: options.approvalReceipt ?? null,
     outcomeReceiptId: options.outcomeReceipt ?? null,
     command: command ?? null,
@@ -30100,6 +30120,12 @@ function controlledWorkerExecuteCommand(options) {
 function normalizeCommandArgs(values) {
   return (values ?? []).map((value) => value.trim()).filter(Boolean);
 }
+function normalizeOutputFragments(values) {
+  return [...new Set((values ?? []).map((value) => value.trim()).filter(Boolean))].slice(0, 32);
+}
+function normalizeComparableText(value) {
+  return value.toLowerCase().replace(/\s+/g, "");
+}
 function gitScopeSnapshot(workspaceRoot2) {
   const status = (0, import_node_child_process12.spawnSync)("git", ["status", "--porcelain=v1", "-z", "--untracked-files=all"], {
     cwd: workspaceRoot2,
@@ -38841,6 +38867,11 @@ workers.command("execute").description("Create a policy-gated Controlled Worker
   "Required proof or verification command; repeatable",
   collectOption,
   []
+).option(
+  "--output-fragment <fragment>",
+  "Required output fragment; repeatable and checked after execution",
+  collectOption,
+  []
 ).option(
   "--work-category <category>",
   "Trust category; conservative task and scope signals can only escalate it"
@@ -38862,6 +38893,7 @@ workers.command("execute").description("Create a policy-gated Controlled Worker
     writeScope: options.writeScope,
     acceptance: options.acceptance,
     proof: options.proof,
+    outputFragments: options.outputFragment,
     workCategory: options.workCategory,
     trustEvent: options.trustEvent,
     profileHash: options.profileHash,

package/docs/FULL_REFERENCE.md

@@ -1335,6 +1335,7 @@ snipara-companion workers execute \
   --write-scope docs/features/PROJECT_INTELLIGENCE.md \
   --acceptance "docs match shipped behavior" \
   --proof "pnpm --filter @snipara/web type-check" \
+  --output-fragment "expected output line" \
   --project-id proj_123 \
   --json
 ```
@@ -1345,6 +1346,8 @@ values for real execution. A legacy `--command` string still requires a fresh
 approval receipt and cannot consume delegated trust. High-risk commands are
 blocked locally, and successful low-risk commands produce
 `verification_required` receipts so proof review remains explicit. When
+`--output-fragment` is provided, every declared fragment must appear in stdout;
+missing fragments fail the receipt closed and are listed in the contract.
 `--project-id` is provided,
 Companion also writes a local Unified Receipt Ledger projection under
 `.snipara/unified-receipts/`; use `--unified-output <file>` to choose the sidecar

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snipara-companion",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "Local-first CLI that asks your repo what breaks before an AI coding agent edits it.",
   "main": "dist/index.js",
   "bin": {