snipara-companion 3.5.8 → 3.5.9

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 Release notes for `snipara-companion`, newest first.
 
+## New In 3.5.9
+
+- Routes explicit `workflow phase-commit` and `final-commit` rationale through
+  the hosted atomic `why` block instead of issuing a second Why Capture request.
+- Exposes decision, rationale, alternatives, constraints, and observed outcome
+  inputs on workflow commits while keeping candidates review-pending.
+- Preserves handoff-only final commits when no structured rationale is supplied.
+
 ## New In 3.5.8
 
 - Preserves the exact collaboration actor identity on hosted lease heartbeat

package/dist/index.d.ts

@@ -519,6 +519,13 @@ interface WhyCaptureResult {
         failed?: Array<Record<string, unknown>>;
     };
 }
+interface EndOfTaskCommitWhyInput {
+    decision?: string;
+    rationale?: string;
+    alternatives?: string[];
+    constraints?: string[];
+    observedOutcome?: string;
+}
 interface JournalAppendResult {
     success?: boolean;
     date?: string;
@@ -1516,6 +1523,8 @@ declare class RLMClient {
     getSessionMemories(maxCriticalTokens?: number, maxDailyTokens?: number, includeYesterday?: boolean): Promise<SessionMemoriesResult>;
     endOfTaskCommit(args: {
         summary: string;
+        task?: string;
+        why?: EndOfTaskCommitWhyInput;
         category?: string;
         outcome?: "completed" | "partial" | "blocked" | "abandoned";
         filesTouched?: string[];

package/dist/index.js

@@ -1724,6 +1724,16 @@ var RLMClient = class {
   async endOfTaskCommit(args) {
     return this.mcpCall("snipara_end_of_task_commit", {
       summary: args.summary,
+      ...args.task ? { task: args.task } : {},
+      ...args.why ? {
+        why: {
+          ...args.why.decision ? { decision: args.why.decision } : {},
+          ...args.why.rationale ? { rationale: args.why.rationale } : {},
+          ...args.why.alternatives ? { alternatives: args.why.alternatives } : {},
+          ...args.why.constraints ? { constraints: args.why.constraints } : {},
+          ...args.why.observedOutcome ? { observed_outcome: args.why.observedOutcome } : {}
+        }
+      } : {},
       category: args.category,
       outcome: args.outcome || "completed",
       files_touched: args.filesTouched || [],
@@ -17901,16 +17911,16 @@ function previewCandidateReceipt(value) {
   if (!isRecord9(value)) {
     return void 0;
   }
-  const whyFields = isRecord9(value.whyFields) ? value.whyFields : void 0;
+  const whyFields = isRecord9(value.whyFields) ? value.whyFields : isRecord9(value.why_fields) ? value.why_fields : void 0;
   const decision = boundedText(whyFields?.decision);
-  const rationale = boundedText(whyFields?.why);
-  const text = boundedText(value.content) ?? decision;
+  const rationale = boundedText(whyFields?.why ?? whyFields?.rationale);
+  const text = boundedText(value.content ?? value.text) ?? decision;
   if (!text) {
     return void 0;
   }
   return {
     text,
-    ...boundedText(value.type, 80) ? { type: boundedText(value.type, 80) } : {},
+    ...boundedText(value.type ?? value.memory_type, 80) ? { type: boundedText(value.type ?? value.memory_type, 80) } : {},
     ...boundedText(value.category, 120) ? { category: boundedText(value.category, 120) } : {},
     ...decision ? { decision } : {},
     ...rationale ? { rationale } : {}
@@ -17921,23 +17931,25 @@ function pendingMemoryReceipt(value) {
     return void 0;
   }
   const memoryId = boundedText(value.memory_id ?? value.memoryId ?? value.id, 200);
-  const text = boundedText(value.content) ?? (memoryId ? `Memory ${memoryId}` : void 0);
+  const text = boundedText(value.content ?? value.text) ?? (memoryId ? `Memory ${memoryId}` : void 0);
   if (!text) {
     return void 0;
   }
   return {
     ...memoryId ? { memoryId } : {},
     text,
-    ...boundedText(value.type, 80) ? { type: boundedText(value.type, 80) } : {},
-    ...boundedText(value.category, 120) ? { category: boundedText(value.category, 120) } : {},
-    reviewStatus: boundedText(value.review_status ?? value.reviewStatus, 80) ?? "pending"
+    ...boundedText(value.type ?? value.memory_type, 80) ? { type: boundedText(value.type ?? value.memory_type, 80) } : {},
+    category: boundedText(value.category, 120) ?? "why-capture",
+    reviewStatus: boundedText(value.review_status ?? value.reviewStatus, 80) ?? "PENDING"
   };
 }
 function issueReceipt(value, fallbackReason) {
   if (!isRecord9(value)) {
     return void 0;
   }
-  const text = boundedText(value.content ?? value.decision ?? value.title ?? value.error ?? value.reason) ?? "Why Capture item";
+  const text = boundedText(
+    value.content ?? value.decision ?? value.title ?? value.error ?? value.reason ?? value.decision_id ?? value.id
+  ) ?? "Why Capture item";
   const reason = boundedText(value.reason ?? value.error, 160) ?? fallbackReason;
   return { text, ...reason ? { reason } : {} };
 }
@@ -17975,6 +17987,47 @@ function readLatestWorkflowCommands(cwd) {
   }
   return [];
 }
+function recordItems(value) {
+  return Array.isArray(value) ? value.filter(isRecord9) : [];
+}
+function taskCommitWhyCaptureReceipt(result, sourceKind, cwd = process.cwd()) {
+  const commitSha = readCommitSha(cwd);
+  const candidates = recordItems(result.candidates).filter(
+    (candidate) => isRecord9(candidate.why_fields) || isRecord9(candidate.whyFields)
+  );
+  const storedCandidates = recordItems(result.stored_candidates).filter(
+    (candidate) => isRecord9(candidate.why_fields) || isRecord9(candidate.whyFields)
+  );
+  const decisionCapture = isRecord9(result.decision_capture) ? result.decision_capture : {};
+  const duplicates = recordItems(decisionCapture.duplicates).map((item) => issueReceipt(item, "duplicate")).filter((item) => Boolean(item));
+  const failed = recordItems(decisionCapture.failed).map((item) => issueReceipt(item, "capture_failed")).filter((item) => Boolean(item));
+  const caveats = Array.isArray(result.caveats) ? result.caveats.filter((item) => typeof item === "string") : [];
+  const hostedPhaseCommit = isRecord9(result.hosted_phase_commit) ? result.hosted_phase_commit : void 0;
+  const hostedFinalCommit = isRecord9(result.hosted_final_commit) ? result.hosted_final_commit : void 0;
+  const hostedError = boundedText(hostedPhaseCommit?.error ?? hostedFinalCommit?.error);
+  const previewCandidates = candidates.map(previewCandidateReceipt).filter((item) => Boolean(item));
+  const pendingMemories = storedCandidates.map(pendingMemoryReceipt).filter((item) => Boolean(item));
+  const baseReceipt = {
+    sourceKind,
+    previewCandidateCount: previewCandidates.length,
+    capturedCount: pendingMemories.length,
+    previewCandidates,
+    pendingMemories,
+    duplicates,
+    failed,
+    ...commitSha ? { commitSha } : {}
+  };
+  if (hostedError) {
+    return { ...baseReceipt, status: "error", error: hostedError };
+  }
+  if (caveats.includes("why_requires_human_owner")) {
+    return { ...baseReceipt, status: "skipped", error: "why_requires_human_owner" };
+  }
+  if (candidates.length === 0) {
+    return { ...baseReceipt, status: "no_candidates" };
+  }
+  return { ...baseReceipt, status: "captured" };
+}
 async function captureCompanionWhy(input) {
   const cwd = input.cwd ?? process.cwd();
   const commitSha = readCommitSha(cwd);
@@ -20739,7 +20792,7 @@ function recordList(value) {
   return Array.isArray(value) ? value.filter(isRecord11) : [];
 }
 function buildWorkflowPhaseCommitReceipt(input) {
-  const stored = recordList(input.result.stored_candidates).map((item) => normalizedMemoryItem(item, "phase_commit", input.phaseId)).filter((item) => Boolean(item));
+  const stored = recordList(input.result.stored_candidates).filter((item) => !isRecord11(item.why_fields) && !isRecord11(item.whyFields)).map((item) => normalizedMemoryItem(item, "phase_commit", input.phaseId)).filter((item) => Boolean(item));
   const skipped = recordList(input.result.skipped_candidates).map((item) => normalizedMemoryItem(item, "phase_commit", input.phaseId)).filter((item) => Boolean(item));
   const hostedPhaseCommit = isRecord11(input.result.hosted_phase_commit) ? input.result.hosted_phase_commit : void 0;
   return {
@@ -32226,6 +32279,8 @@ async function commitTaskMemory(options) {
   const client = createClient(TASK_COMMIT_TIMEOUT_MS);
   return client.endOfTaskCommit({
     summary: options.summary,
+    task: options.task,
+    why: options.why,
     category: options.category,
     outcome: options.outcome,
     filesTouched: options.files
@@ -32298,9 +32353,11 @@ async function commitFinalTaskMemory(options) {
   });
   const callHosted = async (summary, timeoutMs) => {
     const client = createClient(timeoutMs);
-    const handoffOnly = isFinalCommitCategory(category);
+    const handoffOnly = isFinalCommitCategory(category) && !options.why;
     return client.endOfTaskCommit({
       summary,
+      task: options.task,
+      why: options.why,
       category,
       outcome: options.outcome,
       filesTouched: options.files,
@@ -32354,6 +32411,28 @@ async function commitFinalTaskMemory(options) {
     message: "Hosted final-commit failed; local fallback handoff created"
   };
 }
+function structuredTaskCommitWhy(options) {
+  const rationale = compactWhitespace2(options.why ?? "");
+  const explicitDecision = compactWhitespace2(options.decision ?? "");
+  const alternatives = [
+    ...new Set((options.alternatives ?? []).map(compactWhitespace2).filter(Boolean))
+  ];
+  const constraints = [
+    ...new Set((options.constraints ?? []).map(compactWhitespace2).filter(Boolean))
+  ];
+  const observedOutcome = compactWhitespace2(options.observedOutcome ?? "");
+  const decision = explicitDecision || (rationale ? compactWhitespace2(options.summary) : "");
+  if (!decision && !rationale && alternatives.length === 0 && constraints.length === 0 && !observedOutcome) {
+    return void 0;
+  }
+  return {
+    ...decision ? { decision } : {},
+    ...rationale ? { rationale } : {},
+    ...alternatives.length > 0 ? { alternatives } : {},
+    ...constraints.length > 0 ? { constraints } : {},
+    ...observedOutcome ? { observedOutcome } : {}
+  };
+}
 function printJournalWarning(result) {
   if (result?.status === "error" && result.error) {
     console.log(`Journal checkpoint: ${result.error}`);
@@ -32399,8 +32478,11 @@ async function workflowPhaseCommitCommand(options) {
     phase,
     summary: options.summary
   });
+  const structuredWhy = structuredTaskCommitWhy(options);
   const result = await commitPhaseTaskMemory({
     summary: durableSummary,
+    task: `${state.goal} / ${phase.title}`,
+    why: structuredWhy,
     category,
     outcome,
     files
@@ -32475,14 +32557,7 @@ async function workflowPhaseCommitCommand(options) {
     journalAttempted: true,
     teamSyncCompletionAttempted: shouldCompleteTeamSyncWork
   });
-  const whyCapture = await captureCompanionWhy({
-    sourceKind: "phase_commit",
-    sourceSessionId: state.workflowId,
-    task: `${state.goal} / ${phase.title}`,
-    summary: options.summary,
-    files,
-    commands: readLatestWorkflowCommands(process.cwd())
-  });
+  const whyCapture = taskCommitWhyCaptureReceipt(result, "phase_commit");
   phaseCommitReceipt.whyCapture = whyCapture;
   writeWorkflowState(state);
   const coordinationRelease = await releaseWorkflowCoordination(
@@ -32580,8 +32655,11 @@ async function finalCommitCommand(options) {
   });
   const outcome = options.outcome ?? "completed";
   const category = normalizeFinalCommitCategory(options.category);
+  const structuredWhy = structuredTaskCommitWhy(options);
   const result = await commitFinalTaskMemory({
     workflowId: state?.workflowId,
+    task: state?.goal,
+    why: structuredWhy,
     summary: options.summary,
     category,
     outcome,
@@ -32633,15 +32711,7 @@ async function finalCommitCommand(options) {
     journalAttempted: true,
     teamSyncCompletionAttempted: outcome === "completed"
   });
-  const whyCapture = await captureCompanionWhy({
-    sourceKind: "final_commit",
-    sourceSessionId: state?.workflowId ?? loadConfig().sessionId,
-    task: state?.goal,
-    summary: options.summary,
-    why: options.why,
-    files: options.files,
-    commands: readLatestWorkflowCommands(process.cwd())
-  });
+  const whyCapture = taskCommitWhyCaptureReceipt(result, "final_commit");
   const coordinationRelease = state ? await releaseWorkflowCoordination(state, `Workflow ${state.workflowId} final-commit.`) : void 0;
   const report = buildFinalCommitReport({
     state,
@@ -40034,7 +40104,7 @@ workflow.command("runtime-checkpoint").description(
 });
 workflow.command("phase-commit").description(
   "Persist a phase outcome through snipara_end_of_task_commit and advance the workflow"
-).argument("<phaseId>", "Workflow phase id").requiredOption("-s, --summary <summary>", "Phase outcome summary").option("-c, --category <category>", "Memory category", "workflow-phase").option("-o, --outcome <outcome>", "completed|partial|blocked|abandoned", "completed").option("-f, --files <files...>", "Files touched").option(
+).argument("<phaseId>", "Workflow phase id").requiredOption("-s, --summary <summary>", "Phase outcome summary").option("--decision <decision>", "Decision text; defaults to summary when --why is set").option("--why <why>", "Decision rationale; never inferred when absent").option("--alternative <alternative>", "Rejected alternative; repeatable", collectOption, []).option("--constraint <constraint>", "Decision constraint; repeatable", collectOption, []).option("--observed-outcome <outcome>", "Observed result, distinct from execution status").option("-c, --category <category>", "Memory category", "workflow-phase").option("-o, --outcome <outcome>", "completed|partial|blocked|abandoned", "completed").option("-f, --files <files...>", "Files touched").option(
   "--evidence <evidence>",
   "Phase evidence as passed|failed|not-run|unknown:text; repeatable",
   collectOption,
@@ -40043,6 +40113,11 @@ workflow.command("phase-commit").description(
   await workflowPhaseCommitCommand({
     phaseId,
     summary: options.summary,
+    decision: options.decision,
+    why: options.why,
+    alternatives: options.alternative,
+    constraints: options.constraint,
+    observedOutcome: options.observedOutcome,
     category: options.category,
     outcome: options.outcome,
     files: options.files,
@@ -40050,7 +40125,7 @@ workflow.command("phase-commit").description(
     json: options.json
   });
 });
-workflow.command("final-commit").description("Persist the final workflow outcome and close the local workflow state").requiredOption("-s, --summary <summary>", "Final outcome summary").option("--why <why>", "Decision rationale; never inferred when absent").option("-c, --category <category>", "Memory category", "final-commit").option("-o, --outcome <outcome>", "completed|partial|blocked|abandoned", "completed").option("-f, --files <files...>", "Files touched").option(
+workflow.command("final-commit").description("Persist the final workflow outcome and close the local workflow state").requiredOption("-s, --summary <summary>", "Final outcome summary").option("--decision <decision>", "Decision text; defaults to summary when --why is set").option("--why <why>", "Decision rationale; never inferred when absent").option("--alternative <alternative>", "Rejected alternative; repeatable", collectOption, []).option("--constraint <constraint>", "Decision constraint; repeatable", collectOption, []).option("--observed-outcome <outcome>", "Observed result, distinct from execution status").option("-c, --category <category>", "Memory category", "final-commit").option("-o, --outcome <outcome>", "completed|partial|blocked|abandoned", "completed").option("-f, --files <files...>", "Files touched").option(
   "--evidence <evidence>",
   "Verification evidence as passed|failed|not-run|unknown:text; repeatable",
   collectOption,
@@ -40058,7 +40133,11 @@ workflow.command("final-commit").description("Persist the final workflow outcome
 ).option("--risk <risk>", "Known residual risk; repeatable", collectOption, []).option("--next-step <nextStep>", "Recommended next action").option("--json", "Print raw JSON").action(async (options) => {
   await finalCommitCommand({
     summary: options.summary,
+    decision: options.decision,
     why: options.why,
+    alternatives: options.alternative,
+    constraints: options.constraint,
+    observedOutcome: options.observedOutcome,
     category: options.category,
     outcome: options.outcome,
     files: options.files,
@@ -41083,7 +41162,7 @@ program.command("task-commit").description("Persist durable outcomes after meani
     json: options.json
   });
 });
-program.command("final-commit").description("Persist the final managed workflow outcome through snipara_end_of_task_commit").requiredOption("-s, --summary <summary>", "Final outcome summary").option("--why <why>", "Decision rationale; never inferred when absent").option("-c, --category <category>", "Category", "final-commit").option("-o, --outcome <outcome>", "Outcome", "completed").option("-f, --files <files...>", "Files touched").option(
+program.command("final-commit").description("Persist the final managed workflow outcome through snipara_end_of_task_commit").requiredOption("-s, --summary <summary>", "Final outcome summary").option("--decision <decision>", "Decision text; defaults to summary when --why is set").option("--why <why>", "Decision rationale; never inferred when absent").option("--alternative <alternative>", "Rejected alternative; repeatable", collectOption, []).option("--constraint <constraint>", "Decision constraint; repeatable", collectOption, []).option("--observed-outcome <outcome>", "Observed result, distinct from execution status").option("-c, --category <category>", "Category", "final-commit").option("-o, --outcome <outcome>", "Outcome", "completed").option("-f, --files <files...>", "Files touched").option(
   "--evidence <evidence>",
   "Verification evidence as passed|failed|not-run|unknown:text; repeatable",
   collectOption,
@@ -41091,7 +41170,11 @@ program.command("final-commit").description("Persist the final managed workflow
 ).option("--risk <risk>", "Known residual risk; repeatable", collectOption, []).option("--next-step <nextStep>", "Recommended next action").option("--json", "Print raw JSON").action(async (options) => {
   await finalCommitCommand({
     summary: options.summary,
+    decision: options.decision,
     why: options.why,
+    alternatives: options.alternative,
+    constraints: options.constraint,
+    observedOutcome: options.observedOutcome,
     category: options.category,
     outcome: options.outcome,
     files: options.files,

package/docs/FULL_REFERENCE.md

@@ -1632,10 +1632,17 @@ Companion separates two concepts:
   `workflow phase-commit` and `final-commit` keep local workflow state moving on transient
   hosted commit timeouts and surface that local fallback explicitly in the result.
 
-`final-commit` itself remains handoff-only. Its seven-section report reads the
-durable phase receipts already stored, marks Why Capture candidates as pending
-review, lists skipped/duplicate/failed items as not persisted, and never treats
-the final summary or handoff as newly approved durable memory.
+`final-commit` remains handoff-only when no structured rationale is supplied.
+When `--why` or another structured Why Capture field is present, Companion sends
+one atomic `why` block with the handoff commit; it does not issue a second capture
+request. `--decision` overrides the decision text, while `--why` uses the commit
+summary as the decision fallback. Repeat `--alternative` and `--constraint` as
+needed, and use `--observed-outcome` only for an observed result rather than the
+execution status. `workflow phase-commit` exposes the same fields. The resulting
+candidate remains pending review. The seven-section final report reads durable
+phase receipts already stored, marks Why Capture candidates as pending review,
+lists skipped/duplicate/failed items as not persisted, and never treats the final
+summary or handoff as newly approved durable memory.
 
 Do not call `snipara_end_of_task_commit` mechanically for every Git commit. For risky commits,
 package releases, or retries after failures, run Memory Guard first so the agent sees relevant

package/package.json

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