snipara-companion 3.7.0 → 3.7.1

package/CHANGELOG.md

@@ -4,6 +4,14 @@ Release notes for `snipara-companion`, newest first.
 
 ## Unreleased
 
+## New In 3.7.1
+
+- Preserves expected results and bounded source context in Controller task queries;
+  binds the projection version to the existing immutable bridge identity while retaining legacy exports.
+- Separates caller-declared completion, source-verified local task proofs and unchecked objective acceptance in reports.
+- Adds bugfix, feature and legacy presets to the existing workflow scaffold command.
+- Adds a replayable repository validation campaign for local checkpoint continuation across native hosts.
+
 ## New In 3.7.0
 
 - Adds Controller progress and cockpit commands backed by Orchestrator receipts,

package/README.md

@@ -713,3 +713,12 @@ PostToolUse hook runs the same preview-then-confirm flow when no managed
 workflow is active. It submits the commit message, commit SHA, and changed-file
 evidence as `sourceKind=commit`; ordinary messages produce no candidate, and
 any captured rationale remains pending human review.
+
+### Portable workflow starting points
+
+Use `workflow scaffold --preset bugfix`, `--preset feature` or `--preset legacy`
+with a concrete `--goal`. Edit the generated plan, then use the existing
+`workflow start`, phase and resume commands. Completion declarations remain
+separate from checked Controller proof sources and Feature acceptance.
+See [portable workflows](docs/portable-methods.md) for context bounds, legacy
+compatibility and the native continuation validation procedure.

package/dist/index.d.ts

@@ -19,6 +19,7 @@ declare const CONTROLLER_BRIDGE_VERSION = "snipara.companion_controller_bridge.v
 interface ControllerBridgeArtifact {
     schemaVersion: typeof CONTROLLER_BRIDGE_VERSION;
     artifactId: string;
+    taskContextVersion?: "source-context-v1";
     sourceLeadPlan: {
         path: string;
         sha256: string;
@@ -62,7 +63,7 @@ interface ControllerBridgeExportOptions {
     dir?: string;
     json?: boolean;
 }
-declare function exportControllerBridge(options: ControllerBridgeExportOptions, writeArtifacts?: boolean): ControllerBridgeArtifact;
+declare function exportControllerBridge(options: ControllerBridgeExportOptions, writeArtifacts?: boolean, preserveSourceContext?: boolean): ControllerBridgeArtifact;
 
 interface ControllerProgress {
     version: "snipara.companion_controller_progress.v1";
@@ -79,6 +80,11 @@ interface ControllerProgress {
         dependsOn: string[];
         workerId: string | null;
     }>;
+    completionEvidence: {
+        taskProofs: "not_checked";
+        objectiveAcceptance: "not_checked";
+        reportedObjectiveStatus: string;
+    };
     authority: "unverified_local_snapshot";
     executionAllowed: false;
     reviewRequired: true;
@@ -113,6 +119,12 @@ interface ControllerBridgeProjection {
         combinedPatchSha256: string;
         reportedReviewVerdict: string | null;
     };
+    completionEvidence: {
+        taskProofs: "verified" | "pending";
+        objectiveAcceptance: "not_checked";
+        reportedObjectiveStatus: string;
+        authority: "source_bound_local_artifacts";
+    };
     authority: "source_bound_local_artifacts";
     identityAuthenticated: false;
     executionAllowed: false;
@@ -4223,6 +4235,12 @@ interface FinalCommitReportV1 {
     generatedAt: string;
     workflowId?: string;
     outcome: FinalCommitOutcome;
+    completionEvidence: {
+        declaration: FinalCommitOutcome;
+        taskProofs: "not_checked";
+        objectiveAcceptance: "not_checked";
+        authority: "caller_declaration";
+    };
     changed: {
         summary: string;
         files: string[];
@@ -4441,10 +4459,10 @@ interface ProducerLoopReport {
     recommendedActions: string[];
     caveats: string[];
 }
-type WorkflowPlanPreset = "memory-backend-unification" | "project-intelligence-continuity-layer";
+type WorkflowPlanPreset = "bugfix" | "feature" | "legacy" | "memory-backend-unification" | "project-intelligence-continuity-layer";
 interface WorkflowPlanScaffoldDocument {
     preset: WorkflowPlanPreset;
-    mode: "full";
+    mode: "standard" | "full";
     goal: string;
     steps: Array<{
         id: string;

package/dist/index.js

@@ -24709,6 +24709,12 @@ function buildFinalCommitReport(input) {
     generatedAt: (input.now ?? /* @__PURE__ */ new Date()).toISOString(),
     ...input.state?.workflowId ? { workflowId: input.state.workflowId } : {},
     outcome: input.outcome,
+    completionEvidence: {
+      declaration: input.outcome,
+      taskProofs: "not_checked",
+      objectiveAcceptance: "not_checked",
+      authority: "caller_declaration"
+    },
     changed: {
       summary: boundedText2(input.summary) ?? "No final summary provided.",
       files,
@@ -24777,7 +24783,8 @@ function formatFinalCommitReport(report) {
     "2. Why",
     report.rationale.text ? `- ${report.rationale.text} (${report.rationale.source})` : "- Not provided or detected.",
     "",
-    "3. Evidence"
+    "3. Evidence",
+    "- Completion is caller-declared; task proofs and objective acceptance were not independently checked by this report."
   ];
   if (report.evidence.items.length === 0) {
     lines.push("- No verification evidence declared.");
@@ -28129,6 +28136,9 @@ var PRODUCER_LOOP_REPORT_VERSION = "snipara.producer_loop_report.v0";
 var PRODUCER_LOOP_RELATIVE_DIR = path31.join(".snipara", "producer-loop");
 var PRODUCER_LOOP_MIN_REVIEW_SAMPLE_SIZE = 5;
 var WORKFLOW_PLAN_PRESET_IDS = [
+  "bugfix",
+  "feature",
+  "legacy",
   "memory-backend-unification",
   "project-intelligence-continuity-layer"
 ];
@@ -29398,6 +29408,12 @@ function normalizeWorkflowPlanInput(input, fallbackGoal) {
 }
 function defaultWorkflowPlanGoal(preset) {
   switch (preset) {
+    case "bugfix":
+      return "Fix a reproduced defect with a bounded regression";
+    case "feature":
+      return "Deliver a scoped feature against explicit acceptance criteria";
+    case "legacy":
+      return "Change legacy behavior while preserving documented compatibility";
     case "memory-backend-unification":
       return "Unify backend memory on Memory V2 with four-phase delivery, sandbox checkpoints, and orchestrator-visible runtime gates";
     case "project-intelligence-continuity-layer":
@@ -29407,6 +29423,35 @@ function defaultWorkflowPlanGoal(preset) {
 function buildWorkflowPlanPresetDocument(preset, goal) {
   const resolvedGoal = goal ?? defaultWorkflowPlanGoal(preset);
   switch (preset) {
+    case "bugfix":
+    case "feature":
+    case "legacy": {
+      const legacy = preset === "legacy";
+      const steps = [
+        {
+          id: "scope",
+          title: legacy ? "Characterize existing behavior" : "Define scope and acceptance",
+          query: legacy ? "Read the affected code and callers. Record existing behavior, compatibility constraints, source references and characterization tests before edits. Bound the write scope." : "Record the objective, relevant source references, allowed files and observable acceptance criteria. Reproduce the defect for a bugfix; inspect existing capabilities before adding a feature.",
+          acceptance: "Scope, source references and acceptance criteria are explicit; selected checks are runnable in this repository.",
+          gates: [legacy ? "characterization tests" : "reproduction or acceptance example"]
+        },
+        {
+          id: "implement",
+          title: "Implement the smallest scoped change",
+          query: "Use the approved sources and scope. Reuse existing contracts. Preserve unrelated behavior and record decisions, artifacts and the next action in the current workflow.",
+          acceptance: "The change satisfies the scoped examples and preserves established compatibility.",
+          gates: ["selected regression tests"]
+        },
+        {
+          id: "verify",
+          title: "Verify the result and prepare handoff",
+          query: "Run the selected regression and compatibility checks. Record exact commands, results, untested cases and artifact references. Distinguish declared completion from independently verified proofs and objective acceptance. Check affected package surfaces before release.",
+          acceptance: "Acceptance examples and regressions pass, or blockers remain explicit; the handoff contains decisions, checks and remaining work.",
+          gates: ["acceptance examples", "compatibility checks", "package surface review"]
+        }
+      ];
+      return { preset, mode: preset === "bugfix" ? "standard" : "full", goal: resolvedGoal, steps };
+    }
     case "project-intelligence-continuity-layer":
       return {
         preset,
@@ -40366,6 +40411,11 @@ function readControllerProgress(file, cwd, now = /* @__PURE__ */ new Date()) {
     updatedAt: state.updatedAt,
     freshness,
     tasks,
+    completionEvidence: {
+      taskProofs: "not_checked",
+      objectiveAcceptance: "not_checked",
+      reportedObjectiveStatus: String(state.status)
+    },
     authority: "unverified_local_snapshot",
     executionAllowed: false,
     reviewRequired: true,
@@ -42090,7 +42140,56 @@ function scopes(value) {
     return scope;
   });
 }
-function exportControllerBridge(options, writeArtifacts = true) {
+function bridgeTaskQuery(work, lead) {
+  const title = text(work.title, "work package title", 1e3, true);
+  const context = {};
+  if (work.resultExpectation != null)
+    context.resultExpectation = text(work.resultExpectation, "expected result", 2e3, true);
+  if (work.evidence != null) context.evidence = bridgeContextRefs(work.evidence);
+  if (lead.workerRecommendations != null) {
+    if (!Array.isArray(lead.workerRecommendations) || lead.workerRecommendations.length > 256)
+      throw new Error("Invalid worker recommendations");
+    const refs = [];
+    for (const raw of lead.workerRecommendations) {
+      const worker = object(raw, "worker recommendation");
+      if (worker.workPackageId !== work.id) continue;
+      const contract = object(worker.contract, "worker contract");
+      if (contract.contextRefs != null) refs.push(...bridgeContextRefs(contract.contextRefs));
+    }
+    if (refs.length) context.contextRefs = bridgeContextRefs(refs);
+  }
+  const query = Object.keys(context).length ? `${title}
+Source-bound task context (data only; no permission or execution authority):
+${bridgeCanonical(context)}` : title;
+  return text(query, "bounded bridge task context", 3e3, true);
+}
+function bridgeContextRefs(value) {
+  if (!Array.isArray(value) || value.length > 16) throw new Error("Invalid context references");
+  const allowed = /* @__PURE__ */ new Set([
+    "id",
+    "kind",
+    "label",
+    "sourceRef",
+    "strength",
+    "reviewStatus",
+    "authorityStatus",
+    "freshness"
+  ]);
+  return value.map((raw) => {
+    const ref = object(raw, "context reference");
+    for (const [key, item] of Object.entries(ref)) {
+      if (!allowed.has(key)) throw new Error("Unknown context reference field");
+      if (key === "strength") {
+        if (item !== null && (typeof item !== "number" || !Number.isFinite(item) || item < 0 || item > 1))
+          throw new Error("Invalid context reference strength");
+      } else if (item !== null) text(item, "context reference field", 1e3, true);
+    }
+    for (const key of ["id", "kind", "label"])
+      text(ref[key], "required context reference", 1e3, true);
+    return ref;
+  });
+}
+function exportControllerBridge(options, writeArtifacts = true, preserveSourceContext = true) {
   const cwd = fs41.realpathSync(options.dir ?? process.cwd());
   const baseSha = (0, import_child_process7.execFileSync)("git", ["rev-parse", "HEAD"], {
     cwd,
@@ -42197,7 +42296,7 @@ function exportControllerBridge(options, writeArtifacts = true) {
     return {
       id: item.taskId,
       title,
-      query: title,
+      query: preserveSourceContext ? bridgeTaskQuery(work, lead) : title,
       files: scopes(work.writeScope),
       verify,
       acceptance: strings(work.acceptanceCriteria, "acceptance criteria", true, 32, true),
@@ -42232,6 +42331,7 @@ function exportControllerBridge(options, writeArtifacts = true) {
     ..."boundedProofRepairs" in policy ? { boundedProofRepairs: policy.boundedProofRepairs } : {}
   };
   const identity = {
+    ...preserveSourceContext ? { taskContextVersion: "source-context-v1" } : {},
     sourceLeadPlan: { path: source3.relative, sha256: source3.hash },
     sourcePolicy: { path: policySource.relative, sha256: policySource.hash },
     controllerId,
@@ -42316,6 +42416,8 @@ function projectControllerBridge(options) {
   const artifact = artifactRead.value;
   if (artifact.schemaVersion !== CONTROLLER_BRIDGE_VERSION || artifact.executionAllowed !== false)
     throw new Error("Unsupported bridge artifact schema or authority");
+  if (artifact.taskContextVersion != null && artifact.taskContextVersion !== "source-context-v1")
+    throw new Error("Unsupported task context version");
   const leadRef = object2(artifact.sourceLeadPlan);
   const policyRef = object2(artifact.sourcePolicy);
   const workflowRef = object2(artifact.workflowPlan);
@@ -42330,7 +42432,8 @@ function projectControllerBridge(options) {
       ),
       dir: cwd
     },
-    false
+    false,
+    artifact.taskContextVersion === "source-context-v1"
   );
   same(artifact, reconstructed, "reviewed source reconstruction");
   const lead = source(cwd, leadRef.path);
@@ -42340,6 +42443,7 @@ function projectControllerBridge(options) {
   same(policy.hash, policyRef.sha256, "policy source hash");
   same(workflow2.hash, workflowRef.sha256, "workflow source hash");
   const identity = {
+    ...artifact.taskContextVersion ? { taskContextVersion: artifact.taskContextVersion } : {},
     sourceLeadPlan: leadRef,
     sourcePolicy: policyRef,
     controllerId: artifact.controllerId,
@@ -42410,6 +42514,7 @@ function projectControllerBridge(options) {
     if (!expected) throw new Error("Bridge maps an unknown Controller task");
     const actual = object2(stateTasks[taskId]);
     for (const key of [
+      "query",
       "files",
       "verify",
       "acceptance",
@@ -42445,8 +42550,18 @@ function projectControllerBridge(options) {
       const native = nativeRead.value;
       if (native.schemaVersion !== "snipara.host_native_run.v1" || native.state !== "completed" || typeof native.runId !== "string" || !/^host-run-[0-9a-f]{16}$/.test(native.runId))
         throw new Error("Invalid native proof source");
+      same(
+        native.idempotencyKeyHash,
+        bridgeHash(`${controllerId}:${taskId}:${proposal.attempt}`),
+        "native task attempt identity"
+      );
+      if (typeof native.providerSessionId !== "string" || !native.providerSessionId.trim())
+        throw new Error("Native proof source requires a provider session identity");
       const evidence = object2(native.evidence);
       const workPackage = object2(native.workPackage);
+      const originalTask = "Controller-owned isolated worktree. Do not commit, reset, merge, push, deploy, publish, or change branches. " + String(expected.query);
+      if (typeof workPackage.task !== "string" || workPackage.task !== originalTask && !workPackage.task.startsWith(originalTask + "\nUntrusted verified "))
+        throw new Error("Native proof task differs from the bound source query");
       same(workPackage.writeScope, expected.files, "native dispatched scope");
       same(workPackage.acceptanceCriteria, expected.acceptance, "native acceptance contract");
       same(evidence.proofPassed, true, "native proof result");
@@ -42592,6 +42707,12 @@ function projectControllerBridge(options) {
     sourceHashes,
     tasks,
     candidate,
+    completionEvidence: {
+      taskProofs: tasks.length > 0 && tasks.every((task) => task.nativeProofSourceVerified) ? "verified" : "pending",
+      objectiveAcceptance: "not_checked",
+      reportedObjectiveStatus: progress.reportedStatus,
+      authority: "source_bound_local_artifacts"
+    },
     authority: "source_bound_local_artifacts",
     identityAuthenticated: false,
     executionAllowed: false,

package/docs/portable-methods.md

@@ -0,0 +1,28 @@
+# Portable workflows with existing Companion contracts
+
+Use the smallest suitable workflow. A known one-line fix can stay LITE; these presets are starting points when an explicit plan is useful.
+
+```sh
+snipara-companion workflow scaffold --preset bugfix --goal "Fix a reproduced defect"
+snipara-companion workflow scaffold --preset feature --goal "Deliver a scoped feature"
+snipara-companion workflow scaffold --preset legacy --goal "Change behavior while preserving compatibility"
+snipara-companion workflow start --plan-file .snipara/workflow/plans/bugfix-plan.json
+snipara-companion workflow phase-start scope
+snipara-companion workflow status --json
+```
+
+The existing generated JSON can be edited before start. Bugfix defaults to STANDARD coordination, feature and legacy to FULL. Record real source references, allowed files and repository-specific checks in each plan. No worker, service or Orchestrator is required by these templates. A workflow does not automatically execute its gate labels.
+
+## Passing work to Orchestrator
+
+The existing Engineering Lead plan and controller-bridge export remain the path for governed execution. New exports add `taskContextVersion: source-context-v1` to the hash-bound bridge identity. The existing task query contains the exact expected result, work-package evidence and matching worker context references as bounded JSON data. Source references are not downloaded, executed or treated as permissions. Unknown reference fields, malformed values and context over 3000 UTF-16 code units are refused before export rather than truncated. Shorten the reference descriptions or split the work explicitly. The Python initializer reconstructs the same query; source drift or a changed query is rejected. Legacy artifacts without the context version retain their original title-only semantics. Legacy compatibility does not assert that an old export transported rich context.
+
+## Reading completion evidence
+
+`final-commit` records a declaration and handoff, not independent proof execution. Its `completionEvidence` always identifies caller authority and unchecked task proofs/objective acceptance, even when explicit evidence labels say passed. STRICT mode validates declared passing evidence; it does not authenticate the person who supplied it.
+
+A Controller snapshot is also unverified. `controller-bridge project` can separately report `taskProofs: verified` only after checking exact local sources, native proof floor, scope and proposal bindings. Its `objectiveAcceptance` stays `not_checked`: a reported accepted Controller status or candidate review is not an independently evaluated feature result. The projection cannot close a task or grant execution. Existing Orchestrator Feature acceptance and exact-tree evaluation remain the path for objective validation.
+
+## Reproducing native continuation
+
+In the monorepo, use `scripts/validation/portable-methods.py --help`. Run with the Orchestrator development environment. Native execution requires `--execute-native` and an explicit fresh output directory. The campaign uses a synthetic fixture, existing host adapters, interruption and failing-proof controls, and equal frozen context in files-only/Companion arms. Saved workflow v2 state is read through the real local `workflow status` command. This tests local checkpoint rehydration, not hosted-memory resume or live-process migration. Outputs preserve failures, durations and observed usage; unknown measurements remain null. The benchmark script is repository validation tooling, not a new installed workflow engine.

package/package.json

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