snipara-companion 3.2.32 → 3.2.33

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 Release notes for `snipara-companion`, newest first.
 
+## New In 3.2.33
+
+- Turns `final-commit` into a structured closeout report with seven stable
+  sections: what changed, why, evidence, retained decisions, decisions proposed
+  for review, items not persisted, and risks plus the next step.
+- Writes the same versioned, redacted report to
+  `.snipara/workflow/final-report.json` and includes its path and SHA-256 hash in
+  JSON output for automation and handoff verification.
+- Retains phase commit and Why Capture receipts across a managed workflow so the
+  report distinguishes durable stored knowledge from pending review candidates,
+  duplicates, failures, and handoff-only content.
+- Adds `--why`, repeatable `--evidence <status:text>`, repeatable `--risk`, and
+  `--next-step` to both final-commit entry points while preserving the existing
+  handoff-only memory policy.
+
 ## New In 3.2.32
 
 - Promotes a Hosted MCP `servedJudgmentId` into the first-class Project

package/README.md

@@ -262,6 +262,25 @@ receipts from `.snipara/orchestrator/executions/` with persisted supervisor
 reviews, then emits `workerReceipts` and a per-`workerId`/`workCategory`
 `workerTrust` breakdown. This is observability only: every pair remains
 `probation_supervised` and `hardGateReady=false`.
+
+`final-commit` also prints a stable seven-section closeout report:
+
+1. What changed
+2. Why
+3. Evidence
+4. Decisions kept
+5. Decisions proposed for review
+6. Not persisted
+7. Risks and next step
+
+Pass an explicit rationale with `--why`, repeatable verification receipts with
+`--evidence <status:text>`, remaining risks with `--risk`, and the recommended
+follow-up with `--next-step`. Supported evidence statuses are `passed`,
+`failed`, `not-run`, and `unknown`; evidence without a status remains
+`unknown`. The same redacted, versioned report is written to
+`.snipara/workflow/final-report.json`, and `--json` includes the report plus its
+artifact path and SHA-256 hash. Stored phase outcomes appear under decisions
+kept, while Why Capture candidates remain explicitly pending review.
 The report also recognizes exported PR Answer Pack decision-capture artifacts
 with producer kind `pr_answer_pack_decision_capture`, so calibration can track
 more than the workflow producer once those artifacts are present locally.
@@ -364,4 +383,6 @@ When project auth is configured, `workflow phase-commit`, `final-commit`, and
 read-only preview and confirms only when the server detects durable rationale.
 Confirmed candidates enter the pending review queue; capture failures remain
 visible but do not block the primary workflow command. No documentation prompt
-is shown.
+is shown. `final-commit` remains handoff-only: the report explains what was
+stored or proposed, but it does not approve pending candidates or write final
+summary text as durable memory.

package/dist/index.d.ts

@@ -461,6 +461,34 @@ interface WhyCaptureResult {
     confirmed: boolean;
     candidateCount: number;
     capturedCount?: number;
+    candidates?: Array<{
+        content?: string;
+        type?: string;
+        category?: string;
+        reviewNotes?: string;
+        whyFields?: {
+            decision?: string | null;
+            why?: string | null;
+            outcome?: string | null;
+        };
+    }>;
+    memories?: Array<{
+        id?: string;
+        memory_id?: string;
+        content?: string;
+        type?: string;
+        category?: string;
+        reviewStatus?: string;
+        review_status?: string;
+    }>;
+    decisionCapture?: {
+        createdCount?: number;
+        duplicateCount?: number;
+        failedCount?: number;
+        created?: Array<Record<string, unknown>>;
+        duplicates?: Array<Record<string, unknown>>;
+        failed?: Array<Record<string, unknown>>;
+    };
 }
 interface JournalAppendResult {
     success?: boolean;
@@ -3550,6 +3578,180 @@ declare function getTeamSyncStatePath(rootDir?: string): string;
 declare function buildAgenticHandoffMarkdown(artifact: AgenticHandoffArtifact): string;
 declare function teamSyncSweepCommand(options: TeamSyncCommandOptions): Promise<void>;
 
+interface CompanionWhyCaptureCandidate {
+    text: string;
+    type?: string;
+    category?: string;
+    decision?: string;
+    rationale?: string;
+}
+interface CompanionWhyCaptureMemory {
+    memoryId?: string;
+    text: string;
+    type?: string;
+    category?: string;
+    reviewStatus?: string;
+}
+interface CompanionWhyCaptureIssue {
+    text: string;
+    reason?: string;
+}
+interface CompanionWhyCaptureReceipt {
+    status: "captured" | "no_candidates" | "skipped" | "error";
+    sourceKind: WhyCaptureSourceKind;
+    previewCandidateCount: number;
+    capturedCount: number;
+    previewCandidates: CompanionWhyCaptureCandidate[];
+    pendingMemories: CompanionWhyCaptureMemory[];
+    duplicates: CompanionWhyCaptureIssue[];
+    failed: CompanionWhyCaptureIssue[];
+    commitSha?: string;
+    error?: string;
+}
+
+declare const FINAL_COMMIT_REPORT_VERSION: "snipara.final_commit_report.v1";
+declare const FINAL_COMMIT_REPORT_RELATIVE_PATH: string;
+type FinalCommitOutcome = "completed" | "partial" | "blocked" | "abandoned";
+type FinalCommitEvidenceStatus = "passed" | "failed" | "not_run" | "unknown";
+interface FinalCommitMemoryItem {
+    memoryId?: string;
+    text: string;
+    type?: string;
+    category?: string;
+    reason?: string;
+    reviewStatus?: string;
+    source: "phase_commit" | "why_capture";
+    phaseId?: string;
+}
+interface WorkflowPhaseCommitReceipt {
+    phaseId: string;
+    capturedAt: string;
+    category: string;
+    outcome: FinalCommitOutcome;
+    hostedStatus: "processed" | "local_fallback";
+    stored: FinalCommitMemoryItem[];
+    skipped: FinalCommitMemoryItem[];
+    whyCapture?: CompanionWhyCaptureReceipt;
+}
+interface FinalCommitReportPhase {
+    id: string;
+    title: string;
+    status: string;
+    summary?: string;
+    outcome?: string;
+    files: string[];
+}
+interface FinalCommitReportWorkflowState {
+    workflowId: string;
+    goal: string;
+    status: string;
+    createdAt: string;
+    phases: Array<{
+        id: string;
+        title: string;
+        status: string;
+        summary?: string;
+        outcome?: string;
+        files?: string[];
+    }>;
+    phaseCommitReceipts?: WorkflowPhaseCommitReceipt[];
+    runtime?: {
+        sandbox?: {
+            bindings?: Array<{
+                lastCheckpoint?: {
+                    commands?: string[];
+                };
+            }>;
+        };
+    };
+}
+interface FinalCommitEvidenceItem {
+    status: FinalCommitEvidenceStatus;
+    text: string;
+    source: "explicit" | "runtime_checkpoint";
+}
+interface FinalCommitNotPersistedItem {
+    text: string;
+    reason: string;
+    source: "phase_commit" | "why_capture" | "final_commit";
+}
+interface FinalCommitReportV1 {
+    version: typeof FINAL_COMMIT_REPORT_VERSION;
+    generatedAt: string;
+    workflowId?: string;
+    outcome: FinalCommitOutcome;
+    changed: {
+        summary: string;
+        files: string[];
+        phases: FinalCommitReportPhase[];
+        repository: {
+            branch?: string;
+            head?: string;
+            dirty: boolean;
+            dirtyFiles: string[];
+        };
+    };
+    rationale: {
+        status: "provided" | "captured" | "missing";
+        text?: string;
+        source: "explicit" | "why_capture" | "none";
+    };
+    evidence: {
+        items: FinalCommitEvidenceItem[];
+        counts: Record<FinalCommitEvidenceStatus, number>;
+    };
+    retainedDecisions: {
+        status: "confirmed" | "none" | "unavailable";
+        items: FinalCommitMemoryItem[];
+        note?: string;
+    };
+    pendingDecisions: {
+        status: "pending_review" | "none" | "unavailable";
+        items: FinalCommitMemoryItem[];
+        note?: string;
+    };
+    notPersisted: {
+        items: FinalCommitNotPersistedItem[];
+    };
+    closeout: {
+        risks: string[];
+        nextStep: string;
+    };
+    caveats: string[];
+}
+interface FinalCommitReportArtifact {
+    status: "written" | "error";
+    version: typeof FINAL_COMMIT_REPORT_VERSION;
+    path?: string;
+    relativePath: typeof FINAL_COMMIT_REPORT_RELATIVE_PATH;
+    hash?: string;
+    error?: string;
+}
+interface BuildFinalCommitReportInput {
+    state?: FinalCommitReportWorkflowState;
+    summary: string;
+    why?: string;
+    outcome: FinalCommitOutcome;
+    files?: string[];
+    evidence?: string[];
+    risks?: string[];
+    nextStep?: string;
+    whyCapture: CompanionWhyCaptureReceipt;
+    finalCommitResult: Record<string, unknown>;
+    cwd?: string;
+    now?: Date;
+}
+declare function buildWorkflowPhaseCommitReceipt(input: {
+    phaseId: string;
+    category: string;
+    outcome: FinalCommitOutcome;
+    result: Record<string, unknown>;
+    capturedAt?: string;
+}): WorkflowPhaseCommitReceipt;
+declare function buildFinalCommitReport(input: BuildFinalCommitReportInput): FinalCommitReportV1;
+declare function writeFinalCommitReport(report: FinalCommitReportV1, cwd?: string): FinalCommitReportArtifact;
+declare function formatFinalCommitReport(report: FinalCommitReportV1): string;
+
 type SyncDocumentKind = "DOC" | "BINARY";
 type WorkflowMode = "lite" | "standard" | "auto" | "full" | "orchestrate";
 type OnboardFolderMode = "auto" | "business_context" | "code_project" | "mixed";
@@ -3766,6 +3968,8 @@ interface ManagedWorkflowState {
     phases: ManagedWorkflowPhase[];
     runtime?: ManagedWorkflowRuntimeState;
     coordination?: ManagedWorkflowCoordinationState;
+    phaseCommitReceipts?: WorkflowPhaseCommitReceipt[];
+    finalReport?: FinalCommitReportArtifact;
     lastCommit?: {
         category: string;
         outcome: TaskCommitOutcome;
@@ -4605,4 +4809,4 @@ declare function installAutomationBundle(args: {
 }): Promise<AutomationInstallResult>;
 declare function getAutomationStatus(projectDir?: string): AutomationStatusResult;
 
-export { AUTOMATION_MANIFEST_RELATIVE_PATH, AutomationInstallConflictError, AutomationUnsupportedHookBundleError, CODING_INTELLIGENCE_LEDGER_VERSION, COLLABORATION_STATE_RELATIVE_PATH, ENGINEERING_LEAD_EXECUTION_RECEIPT_STAGES, ENGINEERING_LEAD_EXECUTION_RECEIPT_STATUSES, ENGINEERING_LEAD_POSTURES, ENGINEERING_LEAD_PROOF_VERIFICATION_SOURCES, ENGINEERING_LEAD_PROOF_VERIFICATION_STATUSES, ENGINEERING_LEAD_ROUTING_MODES, ENGINEERING_LEAD_STATUSES, ENGINEERING_LEAD_SUPERVISION_STATUSES, ENGINEERING_LEAD_WORKER_ROLES, ENGINEERING_LEAD_WORK_PACKAGE_STATUSES, ORCHESTRATOR_HANDOFF_RELATIVE_PATH, POLICY_LEDGER_SYNC_REPORT_VERSION, PRODUCER_LOOP_ARTIFACT_VERSION, PRODUCER_LOOP_RELATIVE_DIR, PRODUCER_LOOP_REPORT_VERSION, TEAM_SYNC_STATE_RELATIVE_PATH, WHY_OUTCOME_CAPTURE_VERSION, WORKFLOW_PLANS_RELATIVE_DIR, WORKFLOW_STATE_RELATIVE_PATH, addLocalWorker, agentReadinessAuditCommand, appendActivityEvent, applyLocalContextMutationPlan, archiveInactiveTeamSyncWork, attachLocalContextPackReceipts, autoArchiveTeamSyncState, buildAdaptiveWorkRoutingRecommendation, buildAgentReadinessAuditReport, buildAgenticHandoffMarkdown, buildAgenticTimeline, buildAgenticWorkStatus, buildAutomationInstallPlan, buildCanonicalEvent, buildCodeHooksInstallPlan, buildCodePromotionResult, buildCodeStatusResult, buildCodeSyncResult, buildCodingIntelligenceLedger, buildCollaborationActor, buildCollaborationGuardActionCards, buildCollaborationHooksInstallPlan, buildCommitResultMetadata, buildCompanionEngineeringLeadPlanReport, buildContextPackStats, buildEvalCaseArtifact, buildGeneratedWorkflowPlanDocument, buildHostedCodeOverlayUploadPayload, buildHostedGuardPayload, buildJournalCheckpointEntry, buildLocalCallersResult, buildLocalCodeOverlay, buildLocalContextMutationPlan, buildLocalContextPackReceipt, buildLocalContextPackReceipts, buildLocalImpactResult, buildLocalImportsResult, buildLocalNeighborsResult, buildLocalProjectContextValidationReport, buildLocalProjectDriftReport, buildLocalProjectRealityCheck, buildLocalShortestPathResult, buildLocalSourceSnapshot, buildLocalSourceStatus, buildLocalSourceSyncResult, buildMemoryAudit, buildOnboardFolderManifest, buildOrchestratorHandoff, buildPolicyLedgerSyncReport, buildProducerLoopReport, buildProjectIntelligenceBrief, buildProjectIntelligenceRun, buildProjectJudgmentCard, buildSessionBootstrapBrief, buildSessionBootstrapQuality, buildSessionSnapshot, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildVerificationPlan, buildWhyOutcomeCaptureReport, buildWorkflowImpactGate, buildWorkflowPhaseCommitSummary, buildWorkflowPlanScaffold, categoryFromGuardTag, classifyToolResult, cleanContextPacks, codingLedgerExportCommand, collaborationIdeStatusCommand, collectAgentReadinessLocalSignals, collectPolicyLedgerSyncArtifacts, collectSyncDocuments, collectSyncDocumentsInput, compactHostedGuardResources, compareLocalSourceSnapshots, completeTeamSyncStateFromEvidence, completeTeamSyncWorkFromEvidence, contextControlApplyCommand, contextControlDriftCommand, contextControlPlanCommand, contextControlValidateCommand, contextPackCleanCommand, contextPackPackCommand, contextPackRetrieveCommand, contextPackStatsCommand, controlledWorkerExecuteCommand, createClient, createEmptyCollaborationState, createEmptyTeamSyncState, createLocalQueryCache, deriveLocalCollaborationResourcesFromFiles, detectReleaseSurfacesFromFiles, detectRuntimeEnvironment, evalExportCommand, evalRunCommand, evaluateProjectPolicyGates, extractCommandFromToolInput, extractFilesFromToolInput, formatAgentReadinessAuditReport, formatCompanionEngineeringLeadPlanReport, formatOrchestratorRecommendationReason, formatPolicyGateDecision, formatProjectJudgmentCard, formatStuckGuardDecision, getAutomationManifestPath, getAutomationStatus, getCollaborationStatePath, getConfigPath, getContextPackStoragePaths, getLocalCodeOverlayCachePath, getLocalCodePromotionStatePath, getLocalSourceSnapshotPath, getOrchestratorRecommendation, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, ingestReferences, installAutomationBundle, leadPlanCommand, listProjectsForApiKey, loadAutomationManifest, loadCollaborationState, loadConfig, loadTeamSyncState, memoryAuditCommand, memoryCleanCandidatesCommand, memoryCompactCommand, memoryHealthCommand, memoryLocalCommand, memoryReviewsCommand, normalizeCollaborationFiles, normalizeGuardTag, normalizeWorkflowPlanInput, outcomeCapturePreviewCommand, packContext, parseCollaborationResources, projectIntelligenceBriefCommand, projectIntelligenceRunCommand, readActivityTimeline, readLocalCodeOverlayCache, readLocalCodePromotionState, readLocalSourceSnapshot, readLocalWorkersConfig, readSessionSnapshot, realityCheckCommand, referencesIngestCommand, referencesScanCommand, resolveAutoWorkflowMode, resolveContextPackRecord, resolveFullWorkflowTokenBudget, resolveLocalWorkerRoutingDefaults, resolveQueryFromToolInput, retrieveContextPack, runMemoryGuardCheck, saveCollaborationState, saveConfig, saveTeamSyncState, scanReferences, shouldFailCollaborationGuard, shouldSuggestOrchestratorForWorkflow, shouldSuggestRuntimeForWorkflow, summarizeLocalCodeOverlay, teamSyncSweepCommand, validatePlanResult, verifyCommand, workersLocalAddCommand, workersLocalListCommand, workersLocalProbePrintCommand, workersLocalRemoveCommand, workersLocalStatusCommand, workflowSyncPolicyLedgerCommand, writeLocalCodeOverlayCache, writeLocalCodePromotionState, writeLocalSourceSnapshot, writeOrchestratorHandoff, writeProducerLoopArtifact, writeSessionSnapshot };
+export { AUTOMATION_MANIFEST_RELATIVE_PATH, AutomationInstallConflictError, AutomationUnsupportedHookBundleError, CODING_INTELLIGENCE_LEDGER_VERSION, COLLABORATION_STATE_RELATIVE_PATH, ENGINEERING_LEAD_EXECUTION_RECEIPT_STAGES, ENGINEERING_LEAD_EXECUTION_RECEIPT_STATUSES, ENGINEERING_LEAD_POSTURES, ENGINEERING_LEAD_PROOF_VERIFICATION_SOURCES, ENGINEERING_LEAD_PROOF_VERIFICATION_STATUSES, ENGINEERING_LEAD_ROUTING_MODES, ENGINEERING_LEAD_STATUSES, ENGINEERING_LEAD_SUPERVISION_STATUSES, ENGINEERING_LEAD_WORKER_ROLES, ENGINEERING_LEAD_WORK_PACKAGE_STATUSES, FINAL_COMMIT_REPORT_RELATIVE_PATH, FINAL_COMMIT_REPORT_VERSION, ORCHESTRATOR_HANDOFF_RELATIVE_PATH, POLICY_LEDGER_SYNC_REPORT_VERSION, PRODUCER_LOOP_ARTIFACT_VERSION, PRODUCER_LOOP_RELATIVE_DIR, PRODUCER_LOOP_REPORT_VERSION, TEAM_SYNC_STATE_RELATIVE_PATH, WHY_OUTCOME_CAPTURE_VERSION, WORKFLOW_PLANS_RELATIVE_DIR, WORKFLOW_STATE_RELATIVE_PATH, addLocalWorker, agentReadinessAuditCommand, appendActivityEvent, applyLocalContextMutationPlan, archiveInactiveTeamSyncWork, attachLocalContextPackReceipts, autoArchiveTeamSyncState, buildAdaptiveWorkRoutingRecommendation, buildAgentReadinessAuditReport, buildAgenticHandoffMarkdown, buildAgenticTimeline, buildAgenticWorkStatus, buildAutomationInstallPlan, buildCanonicalEvent, buildCodeHooksInstallPlan, buildCodePromotionResult, buildCodeStatusResult, buildCodeSyncResult, buildCodingIntelligenceLedger, buildCollaborationActor, buildCollaborationGuardActionCards, buildCollaborationHooksInstallPlan, buildCommitResultMetadata, buildCompanionEngineeringLeadPlanReport, buildContextPackStats, buildEvalCaseArtifact, buildFinalCommitReport, buildGeneratedWorkflowPlanDocument, buildHostedCodeOverlayUploadPayload, buildHostedGuardPayload, buildJournalCheckpointEntry, buildLocalCallersResult, buildLocalCodeOverlay, buildLocalContextMutationPlan, buildLocalContextPackReceipt, buildLocalContextPackReceipts, buildLocalImpactResult, buildLocalImportsResult, buildLocalNeighborsResult, buildLocalProjectContextValidationReport, buildLocalProjectDriftReport, buildLocalProjectRealityCheck, buildLocalShortestPathResult, buildLocalSourceSnapshot, buildLocalSourceStatus, buildLocalSourceSyncResult, buildMemoryAudit, buildOnboardFolderManifest, buildOrchestratorHandoff, buildPolicyLedgerSyncReport, buildProducerLoopReport, buildProjectIntelligenceBrief, buildProjectIntelligenceRun, buildProjectJudgmentCard, buildSessionBootstrapBrief, buildSessionBootstrapQuality, buildSessionSnapshot, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildVerificationPlan, buildWhyOutcomeCaptureReport, buildWorkflowImpactGate, buildWorkflowPhaseCommitReceipt, buildWorkflowPhaseCommitSummary, buildWorkflowPlanScaffold, categoryFromGuardTag, classifyToolResult, cleanContextPacks, codingLedgerExportCommand, collaborationIdeStatusCommand, collectAgentReadinessLocalSignals, collectPolicyLedgerSyncArtifacts, collectSyncDocuments, collectSyncDocumentsInput, compactHostedGuardResources, compareLocalSourceSnapshots, completeTeamSyncStateFromEvidence, completeTeamSyncWorkFromEvidence, contextControlApplyCommand, contextControlDriftCommand, contextControlPlanCommand, contextControlValidateCommand, contextPackCleanCommand, contextPackPackCommand, contextPackRetrieveCommand, contextPackStatsCommand, controlledWorkerExecuteCommand, createClient, createEmptyCollaborationState, createEmptyTeamSyncState, createLocalQueryCache, deriveLocalCollaborationResourcesFromFiles, detectReleaseSurfacesFromFiles, detectRuntimeEnvironment, evalExportCommand, evalRunCommand, evaluateProjectPolicyGates, extractCommandFromToolInput, extractFilesFromToolInput, formatAgentReadinessAuditReport, formatCompanionEngineeringLeadPlanReport, formatFinalCommitReport, formatOrchestratorRecommendationReason, formatPolicyGateDecision, formatProjectJudgmentCard, formatStuckGuardDecision, getAutomationManifestPath, getAutomationStatus, getCollaborationStatePath, getConfigPath, getContextPackStoragePaths, getLocalCodeOverlayCachePath, getLocalCodePromotionStatePath, getLocalSourceSnapshotPath, getOrchestratorRecommendation, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, ingestReferences, installAutomationBundle, leadPlanCommand, listProjectsForApiKey, loadAutomationManifest, loadCollaborationState, loadConfig, loadTeamSyncState, memoryAuditCommand, memoryCleanCandidatesCommand, memoryCompactCommand, memoryHealthCommand, memoryLocalCommand, memoryReviewsCommand, normalizeCollaborationFiles, normalizeGuardTag, normalizeWorkflowPlanInput, outcomeCapturePreviewCommand, packContext, parseCollaborationResources, projectIntelligenceBriefCommand, projectIntelligenceRunCommand, readActivityTimeline, readLocalCodeOverlayCache, readLocalCodePromotionState, readLocalSourceSnapshot, readLocalWorkersConfig, readSessionSnapshot, realityCheckCommand, referencesIngestCommand, referencesScanCommand, resolveAutoWorkflowMode, resolveContextPackRecord, resolveFullWorkflowTokenBudget, resolveLocalWorkerRoutingDefaults, resolveQueryFromToolInput, retrieveContextPack, runMemoryGuardCheck, saveCollaborationState, saveConfig, saveTeamSyncState, scanReferences, shouldFailCollaborationGuard, shouldSuggestOrchestratorForWorkflow, shouldSuggestRuntimeForWorkflow, summarizeLocalCodeOverlay, teamSyncSweepCommand, validatePlanResult, verifyCommand, workersLocalAddCommand, workersLocalListCommand, workersLocalProbePrintCommand, workersLocalRemoveCommand, workersLocalStatusCommand, workflowSyncPolicyLedgerCommand, writeFinalCommitReport, writeLocalCodeOverlayCache, writeLocalCodePromotionState, writeLocalSourceSnapshot, writeOrchestratorHandoff, writeProducerLoopArtifact, writeSessionSnapshot };