snipara-companion 2.0.4 → 2.0.6

package/README.md

@@ -724,6 +724,12 @@ snipara-companion run \
 package-surface review, verification plan, and final Judgment Card. Review-only
 guard findings can be acknowledged with the printed guard action card command;
 blocking conflicts still make the release judgment non-proceedable.
+When a served judgment id is available, add `--served-judgment-id` so `run` can
+write first-party Advisor Influence receipts for recommendations that visibly
+change the plan. The receipt payload includes stable skip/record counts,
+bounded automation metadata, and observed verification evidence from guard,
+package review, and policy-gate results without treating those checks as
+outcome proof.
 
 For the full Project Intelligence and Continuity Layer roadmap, scaffold the
 built-in managed workflow plan:

package/dist/index.d.ts

@@ -565,7 +565,21 @@ interface RecordAdvisorInfluenceReceiptInput {
     behaviorChange: string;
     verificationExecuted: string[];
     outcomeLinkStatus?: AdvisorInfluenceOutcomeLinkStatus;
-    metadata?: Record<string, unknown>;
+    metadata?: AdvisorInfluenceReceiptMetadataInput;
+}
+interface AdvisorInfluenceReceiptMetadataInput extends Record<string, unknown> {
+    source?: string;
+    firstParty?: boolean;
+    planBefore?: string | null;
+    planAfter?: string | null;
+    changedBecauseOfRecommendation?: boolean | null;
+    filesAffected?: string[];
+    toolActions?: string[];
+    humanOverride?: string | null;
+    task?: string | null;
+    branch?: string | null;
+    runId?: string | null;
+    generatedAt?: string | null;
 }
 interface RecordAdvisorInfluenceReceiptResult {
     project: {
@@ -2129,17 +2143,24 @@ interface ProjectRunPackageReview {
 }
 interface ProjectRunAdvisorReceiptWrite {
     advisorRecommendationId: string;
-    status: "recorded" | "error";
+    status: "recorded" | "skipped" | "error";
+    agentDecision?: AdvisorInfluenceAgentDecision;
+    changedBecauseOfRecommendation?: boolean;
     result?: RecordAdvisorInfluenceReceiptResult;
+    reason?: ProjectRunAdvisorReceiptSkipReason;
     error?: string;
 }
+type ProjectRunAdvisorReceiptSkipReason = "explicitly_skipped" | "no_advisor_recommendations" | "missing_served_judgment_id" | "no_plan_adaptation" | "write_limit_exceeded";
 interface ProjectRunAdvisorReceiptCapture {
     status: "skipped" | "recorded" | "partial" | "error";
     servedJudgmentId?: string;
+    totalRecommendationCount: number;
+    eligibleCount: number;
     attemptedCount: number;
     recordedCount: number;
+    skippedCount: number;
     writes: ProjectRunAdvisorReceiptWrite[];
-    reason?: string;
+    reason?: ProjectRunAdvisorReceiptSkipReason;
 }
 interface ProjectIntelligenceRunResult {
     version: "project-intelligence.production-run.v1";

package/dist/index.js

@@ -11945,6 +11945,7 @@ function formatPolicyGateDecision(gateDecision) {
 // src/commands/run.ts
 var GUARD_MAX_BUFFER_BYTES = 16 * 1024 * 1024;
 var RAW_OUTPUT_PREVIEW_BYTES = 64e3;
+var ADVISOR_RECEIPT_WRITE_LIMIT = 6;
 function normalizeStringList2(values) {
   return [...new Set((values ?? []).map((value) => value.trim()).filter(Boolean))];
 }
@@ -12036,6 +12037,21 @@ function advisorReceiptDecision(recommendation, judgmentCard) {
   }
   return "modified";
 }
+function advisorReceiptChangedBecauseOfRecommendation(args) {
+  if (args.recommendation.severity === "block" && args.judgmentCard.canProceed === "block") {
+    return true;
+  }
+  if (args.recommendation.severity === "risk") {
+    return true;
+  }
+  if (args.recommendation.expectedBehaviorChange?.trim()) {
+    return true;
+  }
+  if (args.recommendation.recommendedVerification.length > 0) {
+    return true;
+  }
+  return args.judgmentCard.requiredActions.length > 0;
+}
 function advisorReceiptBehaviorChange(recommendation, judgmentCard) {
   const verification = recommendation.recommendedVerification.slice(0, 3).join("; ");
   const mode = recommendation.severity === "block" || recommendation.severity === "risk" ? "required action" : "advisory action";
@@ -12046,73 +12062,243 @@ function advisorReceiptBehaviorChange(recommendation, judgmentCard) {
     `Judgment state after adaptation: ${judgmentCard.state}.`
   ].filter(Boolean).join(" ");
 }
+function advisorReceiptPlanBefore(options) {
+  return options.task ?? options.diffSummary ?? (options.changedFiles && options.changedFiles.length > 0 ? `Work on ${options.changedFiles.slice(0, 8).join(", ")}` : null);
+}
+function advisorReceiptPlanAfter(args) {
+  const requiredActions = args.judgmentCard.requiredActions.slice(0, 5).map((action) => action.command ?? action.title).filter(Boolean);
+  return [
+    args.behaviorChange,
+    requiredActions.length > 0 ? `Visible plan now includes required action(s): ${requiredActions.join("; ")}.` : null,
+    args.recommendation.recommendedVerification.length > 0 ? `Recommended verification stays open: ${args.recommendation.recommendedVerification.slice(0, 5).join("; ")}.` : null
+  ].filter(Boolean).join(" ");
+}
+function advisorReceiptMetadata(args) {
+  const toolActions = normalizeStringList2([
+    ...args.recommendation.recommendedVerification,
+    ...args.judgmentCard.requiredActions.map((action) => action.command ?? action.title)
+  ]).slice(0, 20);
+  const filesAffected = normalizeStringList2([
+    ...args.brief.changedFiles ?? [],
+    ...args.options.changedFiles ?? []
+  ]).slice(0, 80);
+  return {
+    source: "snipara-companion:run",
+    firstParty: true,
+    runVersion: "project-intelligence.production-run.v1",
+    runId: process.env.SNIPARA_SESSION_ID ?? process.env.CODEX_SESSION_ID ?? null,
+    generatedAt: args.judgmentCard.generatedAt,
+    release: Boolean(args.options.release),
+    task: args.brief.task ?? args.options.task ?? null,
+    branch: args.brief.branch ?? args.options.branch ?? null,
+    filesAffected,
+    changedFiles: filesAffected,
+    planBefore: advisorReceiptPlanBefore(args.options),
+    planAfter: advisorReceiptPlanAfter({
+      recommendation: args.recommendation,
+      behaviorChange: args.behaviorChange,
+      judgmentCard: args.judgmentCard
+    }),
+    changedBecauseOfRecommendation: args.agentDecision !== "ignored",
+    toolActions,
+    humanOverride: null,
+    judgmentState: args.judgmentCard.state,
+    canProceed: args.judgmentCard.canProceed,
+    verificationEvidence: args.verificationEvidence,
+    verificationBackfill: {
+      version: "advisor-receipt-verification-backfill-v1",
+      executedCount: args.verificationEvidence.filter((item) => item.status !== "skipped").length,
+      skippedCount: args.verificationEvidence.filter((item) => item.status === "skipped").length,
+      caveat: "Verification evidence records commands or gates observed by this run; it is not outcome proof."
+    },
+    receiptAutomation: {
+      version: "first-party-advisor-receipt-automation-v1",
+      trigger: "snipara-companion run",
+      selectedRecommendationRank: args.recommendationIndex + 1,
+      totalRecommendations: args.totalRecommendations,
+      writeLimit: ADVISOR_RECEIPT_WRITE_LIMIT,
+      skipReason: null,
+      reason: "served judgment id and plan adaptation were present"
+    }
+  };
+}
+function skippedAdvisorReceiptWrite(recommendation, reason, agentDecision, changedBecauseOfRecommendation) {
+  return {
+    advisorRecommendationId: recommendation.id,
+    status: "skipped",
+    ...agentDecision ? { agentDecision } : {},
+    ...changedBecauseOfRecommendation !== void 0 ? { changedBecauseOfRecommendation } : {},
+    reason
+  };
+}
+function advisorReceiptCaptureStatus(args) {
+  if (args.eligibleCount === 0) return "skipped";
+  if (args.recordedCount === args.eligibleCount && args.errorCount === 0 && args.skippedCount === 0) {
+    return "recorded";
+  }
+  if (args.recordedCount > 0) return "partial";
+  if (args.errorCount > 0) return "error";
+  return "skipped";
+}
+function verificationEvidenceFromRun(args) {
+  const evidence = [];
+  if (args.guard) {
+    evidence.push({
+      source: "collaboration_guard",
+      label: "Collaboration guard",
+      status: args.guard.status === 0 ? "passed" : "failed",
+      command: args.guard.command,
+      exitCode: args.guard.status,
+      detail: args.guard.status === 0 ? "Pre-deploy collaboration guard passed or only review-only warnings were acknowledged." : args.guard.error ?? args.guard.stderr.trim() ?? `Guard exited ${args.guard.status}.`
+    });
+  }
+  if (args.packageReview) {
+    evidence.push({
+      source: "package_review",
+      label: "Package surface review",
+      status: args.packageReview.status === "ok" ? "passed" : args.packageReview.status === "skipped" ? "skipped" : "failed",
+      command: args.packageReview.command,
+      detail: args.packageReview.status === "ok" ? "npm package metadata was read successfully." : args.packageReview.error ?? `Package review ${args.packageReview.status}.`
+    });
+  }
+  if (args.policyGates) {
+    evidence.push({
+      source: "policy_gates",
+      label: "Policy gates",
+      status: args.policyGates.summary.block > 0 ? "failed" : args.policyGates.summary.requiredAction > 0 ? "warning" : "passed",
+      detail: `Strongest policy gate: ${args.policyGates.summary.strongestSeverity}; advisory ${args.policyGates.summary.advisory}, required ${args.policyGates.summary.requiredAction}, block ${args.policyGates.summary.block}.`
+    });
+  }
+  return evidence;
+}
+function verificationExecutedFromEvidence(evidence) {
+  return evidence.filter((item) => item.status !== "skipped").map(
+    (item) => item.command ? `${item.label}: ${item.command} (${item.status})` : `${item.label}: ${item.status}`
+  );
+}
 async function recordFirstPartyAdvisorReceipts(args) {
+  const allRecommendations = args.judgmentCard.advisorRecommendations;
   if (args.options.skipAdvisorReceipts) {
     return {
       status: "skipped",
+      totalRecommendationCount: allRecommendations.length,
+      eligibleCount: 0,
       attemptedCount: 0,
       recordedCount: 0,
+      skippedCount: allRecommendations.length,
       writes: [],
-      reason: "advisor receipt capture was explicitly skipped"
+      reason: "explicitly_skipped"
     };
   }
-  if (args.judgmentCard.advisorRecommendations.length === 0) {
-    return void 0;
+  if (allRecommendations.length === 0) {
+    return {
+      status: "skipped",
+      totalRecommendationCount: 0,
+      eligibleCount: 0,
+      attemptedCount: 0,
+      recordedCount: 0,
+      skippedCount: 0,
+      writes: [],
+      reason: "no_advisor_recommendations"
+    };
   }
   const servedJudgmentId = servedJudgmentIdForRun(args.options, args.brief);
   if (!servedJudgmentId) {
+    const writes2 = allRecommendations.slice(0, ADVISOR_RECEIPT_WRITE_LIMIT).map(
+      (recommendation) => skippedAdvisorReceiptWrite(recommendation, "missing_served_judgment_id")
+    );
     return {
       status: "skipped",
+      totalRecommendationCount: allRecommendations.length,
+      eligibleCount: 0,
       attemptedCount: 0,
       recordedCount: 0,
-      writes: [],
-      reason: "no served judgment id was available for first-party advisor receipts"
+      skippedCount: writes2.length,
+      writes: writes2,
+      reason: "missing_served_judgment_id"
     };
   }
   const client = createClient(1e4);
-  const recommendations = args.judgmentCard.advisorRecommendations.slice(0, 6);
-  const writes = await Promise.all(
-    recommendations.map(async (recommendation) => {
-      try {
-        const result = await client.recordAdvisorInfluenceReceipt({
-          servedJudgmentId,
-          recommendation: advisorReceiptRecommendation(recommendation),
-          agentDecision: advisorReceiptDecision(recommendation, args.judgmentCard),
-          behaviorChange: advisorReceiptBehaviorChange(recommendation, args.judgmentCard),
-          verificationExecuted: [],
-          outcomeLinkStatus: "pending",
-          metadata: {
-            source: "snipara-companion:run",
-            firstParty: true,
-            runVersion: "project-intelligence.production-run.v1",
-            generatedAt: args.judgmentCard.generatedAt,
-            release: Boolean(args.options.release),
-            branch: args.brief.branch ?? args.options.branch ?? null,
-            changedFiles: args.brief.changedFiles,
-            judgmentState: args.judgmentCard.state,
-            canProceed: args.judgmentCard.canProceed
+  const verificationEvidence = args.verificationEvidence ?? [];
+  const verificationExecuted = verificationExecutedFromEvidence(verificationEvidence);
+  const selectedRecommendations = allRecommendations.slice(0, ADVISOR_RECEIPT_WRITE_LIMIT);
+  const overflowWrites = allRecommendations.slice(ADVISOR_RECEIPT_WRITE_LIMIT).map((recommendation) => skippedAdvisorReceiptWrite(recommendation, "write_limit_exceeded"));
+  const writes = [
+    ...await Promise.all(
+      selectedRecommendations.map(
+        async (recommendation, recommendationIndex) => {
+          const agentDecision = advisorReceiptDecision(recommendation, args.judgmentCard);
+          const changedBecauseOfRecommendation = advisorReceiptChangedBecauseOfRecommendation({
+            recommendation,
+            judgmentCard: args.judgmentCard
+          });
+          if (!changedBecauseOfRecommendation) {
+            return skippedAdvisorReceiptWrite(
+              recommendation,
+              "no_plan_adaptation",
+              agentDecision,
+              false
+            );
           }
-        });
-        return {
-          advisorRecommendationId: recommendation.id,
-          status: "recorded",
-          result
-        };
-      } catch (error) {
-        return {
-          advisorRecommendationId: recommendation.id,
-          status: "error",
-          error: error instanceof Error ? error.message : String(error)
-        };
-      }
-    })
-  );
+          try {
+            const behaviorChange = advisorReceiptBehaviorChange(recommendation, args.judgmentCard);
+            const result = await client.recordAdvisorInfluenceReceipt({
+              servedJudgmentId,
+              recommendation: advisorReceiptRecommendation(recommendation),
+              agentDecision,
+              behaviorChange,
+              verificationExecuted,
+              outcomeLinkStatus: "pending",
+              metadata: advisorReceiptMetadata({
+                options: args.options,
+                brief: args.brief,
+                judgmentCard: args.judgmentCard,
+                recommendation,
+                recommendationIndex,
+                totalRecommendations: allRecommendations.length,
+                verificationEvidence,
+                agentDecision,
+                behaviorChange
+              })
+            });
+            return {
+              advisorRecommendationId: recommendation.id,
+              status: "recorded",
+              agentDecision,
+              changedBecauseOfRecommendation,
+              result
+            };
+          } catch (error) {
+            return {
+              advisorRecommendationId: recommendation.id,
+              status: "error",
+              agentDecision,
+              changedBecauseOfRecommendation,
+              error: error instanceof Error ? error.message : String(error)
+            };
+          }
+        }
+      )
+    ),
+    ...overflowWrites
+  ];
   const recordedCount = writes.filter((write) => write.status === "recorded").length;
+  const skippedCount = writes.filter((write) => write.status === "skipped").length;
+  const errorCount = writes.filter((write) => write.status === "error").length;
+  const eligibleCount = writes.filter((write) => write.status !== "skipped").length;
   return {
-    status: recordedCount === writes.length ? "recorded" : recordedCount > 0 ? "partial" : "error",
+    status: advisorReceiptCaptureStatus({
+      eligibleCount,
+      recordedCount,
+      skippedCount,
+      errorCount
+    }),
     servedJudgmentId,
-    attemptedCount: writes.length,
+    totalRecommendationCount: allRecommendations.length,
+    eligibleCount,
+    attemptedCount: eligibleCount,
     recordedCount,
+    skippedCount,
     writes
   };
 }
@@ -12231,11 +12417,6 @@ async function buildProjectIntelligenceRun(options) {
     packageReview,
     errors: runErrors
   });
-  const advisorReceiptCapture = await recordFirstPartyAdvisorReceipts({
-    options,
-    brief,
-    judgmentCard
-  });
   const policyGates = evaluateProjectPolicyGates({
     task: options.task,
     release: options.release,
@@ -12247,6 +12428,17 @@ async function buildProjectIntelligenceRun(options) {
     packageReview,
     judgmentCard
   });
+  const verificationEvidence = verificationEvidenceFromRun({
+    guard,
+    packageReview,
+    policyGates
+  });
+  const advisorReceiptCapture = await recordFirstPartyAdvisorReceipts({
+    options,
+    brief,
+    judgmentCard,
+    verificationEvidence
+  });
   const suggestedCommands = [
     ...brief.suggestedCommands,
     ...policyGates.suggestedCommands,
@@ -12325,8 +12517,16 @@ async function projectIntelligenceRunCommand(options) {
       console.log(
         `Recorded: ${result.advisorReceiptCapture.recordedCount}/${result.advisorReceiptCapture.attemptedCount}`
       );
+      if (result.advisorReceiptCapture.skippedCount > 0) {
+        console.log(`Skipped: ${result.advisorReceiptCapture.skippedCount}`);
+      }
       if (result.advisorReceiptCapture.reason) {
-        console.log(result.advisorReceiptCapture.reason);
+        console.log(`Reason: ${result.advisorReceiptCapture.reason}`);
+      }
+      for (const write of result.advisorReceiptCapture.writes.slice(0, 4)) {
+        if (write.status === "skipped" && write.reason) {
+          console.log(`- skipped ${write.advisorRecommendationId}: ${write.reason}`);
+        }
       }
       console.log("");
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snipara-companion",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "Snipara Git-style companion CLI for local workflow continuity, hooks, hosted context, and Mini Snipara OSS workflows",
   "main": "dist/index.js",
   "bin": {