snipara-companion 3.2.29 → 3.2.31

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 Release notes for `snipara-companion`, newest first.
 
+## New In 3.2.31
+
+- Sends phase commits, final commits, and Team Sync handoffs to project-scoped
+  Why Capture with the existing goal, summary, files, verification commands,
+  session reference, and commit SHA.
+- Preserves reviewed-memory governance with an automatic read-only preview
+  followed by confirmation only when durable rationale candidates exist; filed
+  candidates remain `PENDING` in the review queue.
+- Keeps capture best-effort and observable in JSON receipts and the activity
+  timeline, so a Why Capture outage never rolls back a completed workflow or
+  handoff and never introduces a documentation prompt.
+
+## New In 3.2.30
+
+- Persists an explicit `--ack-review-only` as a 15-minute, one-use
+  acknowledgement bound to the exact guard profile, action, and finding
+  fingerprint, so the immediately following Git hook can consume it safely.
+- Invalidates that acknowledgement when findings change and never applies it
+  to required acknowledgements, active conflicts, or hard blocks.
+- Resolves collaboration state from `SNIPARA_WORKSPACE_DIR` or the Git
+  top-level directory, preventing filtered package commands from writing a
+  nested `packages/cli/.snipara/` session.
+
 ## New In 3.2.29
 
 - Extends `workflow producer-report` with attributed gated-execution samples

package/README.md

@@ -359,3 +359,9 @@ Launch assets, demo scripts, and post drafts live in
 [docs/launch/LAUNCH_KIT.md](./docs/launch/LAUNCH_KIT.md).
 
 Release notes live in [CHANGELOG.md](./CHANGELOG.md).
+When project auth is configured, `workflow phase-commit`, `final-commit`, and
+`team-sync handoff` also run reviewed Why Capture. The Companion first sends a
+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.

package/dist/index.d.ts

@@ -441,6 +441,27 @@ interface SessionPersistResult {
     session_id: string;
     files_tracked: number;
 }
+type WhyCaptureSourceKind = "phase_commit" | "final_commit" | "handoff";
+interface WhyCaptureInput {
+    decision?: string;
+    why?: string;
+    rationale?: string;
+    sourceText?: string;
+    sourceKind: WhyCaptureSourceKind;
+    sourceSessionId?: string;
+    task?: string;
+    changedFiles?: string[];
+    commands?: string[];
+    commitSha?: string;
+    confirmed?: boolean;
+    previewOnly?: boolean;
+}
+interface WhyCaptureResult {
+    previewOnly: boolean;
+    confirmed: boolean;
+    candidateCount: number;
+    capturedCount?: number;
+}
 interface JournalAppendResult {
     success?: boolean;
     date?: string;
@@ -1273,6 +1294,7 @@ declare class RLMClient {
         payload?: Record<string, unknown>;
     }): Promise<EmitEventResult>;
     recordAdvisorInfluenceReceipt(input: RecordAdvisorInfluenceReceiptInput): Promise<RecordAdvisorInfluenceReceiptResult>;
+    captureWhy(input: WhyCaptureInput): Promise<WhyCaptureResult>;
     getAutomationEvents(args?: {
         sessionId?: string;
         limit?: number;
@@ -2831,6 +2853,7 @@ declare function buildCodingIntelligenceLedger(options?: CodingLedgerBuildOption
 declare function codingLedgerExportCommand(options: CodingLedgerExportCommandOptions): Promise<void>;
 
 declare const COLLABORATION_STATE_RELATIVE_PATH: string;
+type CollaborationGuardProfile = "edit" | "pre-commit" | "pre-push" | "pre-deploy" | "migration" | "schema" | "release-package";
 type CollaborationGuardActionKind = "safe_to_ack" | "needs_handoff" | "needs_test" | "needs_package_review" | "blocking_conflict" | "guard_unavailable";
 interface CollaborationGuardActionCard {
     kind: CollaborationGuardActionKind;
@@ -2910,6 +2933,13 @@ interface CollaborationLocalLeaseRecord {
     expiresAt?: string | null;
     workSessionId?: string;
 }
+interface CollaborationReviewOnlyAcknowledgement {
+    profile: CollaborationGuardProfile;
+    action: string;
+    findingFingerprint: string;
+    acknowledgedAt: string;
+    expiresAt: string;
+}
 interface CollaborationLocalState {
     schemaVersion: "snipara.collaboration.v1";
     updatedAt: string;
@@ -2926,6 +2956,7 @@ interface CollaborationLocalState {
     files: string[];
     resources: CollaborationResource[];
     leases: CollaborationLocalLeaseRecord[];
+    reviewOnlyAcknowledgements: CollaborationReviewOnlyAcknowledgement[];
     lastGuard?: {
         decision: CollaborationGuardDecision;
         severity: string;