snipara-companion 3.2.14 → 3.2.15

package/README.md

@@ -77,6 +77,7 @@ These commands are useful without hosted Snipara:
 | `workflow start` / `phase-start` / `phase-commit` / `resume` | Agent continuity that survives compaction                    |
 | `workflow timeline` / `workflow session`                     | Append-only local activity log and Session Snapshot V0       |
 | `workflow decisions` / `workflow decide`                     | Local human decision requests and response receipts          |
+| `run --emit-policy-decisions`                                | Project Policy review requests in the agent workflow         |
 | `workflow producer-triage`                                   | Ask for human review of unreviewed Producer Loop samples     |
 | `workflow producer-report`                                   | Local Producer Loop adoption and calibration report          |
 | `workflow producer-review`                                   | Mark local Producer Loop samples reviewed or rejected        |

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { ProjectIntentDetectionResult, ProjectPolicyDecision, ProjectRealityCheckResult, ProjectIntelligenceEngineeringLeadPlanSummary, ProjectPolicyRule, OutcomeIntelligenceCalibration, ControlledWorkerExecutionMode, ControlledWorkerExecutionReceipt } from '@snipara/project-intelligence-contracts';
+import { ProjectIntentDetectionResult, ProjectPolicyDecision, ProjectRealityCheckResult, ProjectIntelligenceEngineeringLeadPlanSummary, ProjectPolicyRule, DecisionRequest, OutcomeIntelligenceCalibration, ControlledWorkerExecutionMode, ControlledWorkerExecutionReceipt } from '@snipara/project-intelligence-contracts';
 
 declare function resolveQueryFromToolInput(toolInput?: string, tool?: string): string | null;
 
@@ -2073,6 +2073,14 @@ interface RealityCheckCommandOptions {
 declare function buildLocalProjectRealityCheck(options: RealityCheckCommandOptions): ProjectRealityCheckResult;
 declare function realityCheckCommand(options: RealityCheckCommandOptions): Promise<void>;
 
+interface DecisionRequestWriteResult {
+    status: "written" | "duplicate_pending" | "duplicate_resolved";
+    requestId: string;
+    fingerprint: string;
+    path?: string;
+    relativePath?: string;
+}
+
 interface MemoryHealthCommandOptions {
     scope?: MemoryScope;
     includeInactive?: boolean;
@@ -2463,6 +2471,7 @@ interface ProjectRunCommandOptions {
     servedJudgmentId?: string;
     skipAdvisorReceipts?: boolean;
     outcomeReceiptFiles?: string[];
+    emitPolicyDecisions?: boolean;
     json?: boolean;
 }
 interface ProjectRunGuardResult {
@@ -2509,11 +2518,20 @@ interface ProjectIntelligenceRunResult {
     guard?: ProjectRunGuardResult;
     packageReview?: ProjectRunPackageReview;
     policyGates: ProjectPolicyGatesResult;
+    policyDecisionRequests?: ProjectRunPolicyDecisionRequests;
     advisorReceiptCapture?: ProjectRunAdvisorReceiptCapture;
     outcomeCalibration?: OutcomeIntelligenceCalibration;
     judgmentCard: ProjectIntelligenceJudgmentCard;
     suggestedCommands: string[];
 }
+interface ProjectRunPolicyDecisionRequests {
+    version: "project-intelligence.policy-decision-requests.v1";
+    emitted: boolean;
+    requestCount: number;
+    requests: DecisionRequest[];
+    writes: DecisionRequestWriteResult[];
+    caveats: string[];
+}
 declare function buildProjectIntelligenceRun(options: ProjectRunCommandOptions): Promise<ProjectIntelligenceRunResult>;
 declare function projectIntelligenceRunCommand(options: ProjectRunCommandOptions): Promise<void>;
 

package/dist/index.js

@@ -30575,6 +30575,9 @@ var ADVISOR_RECEIPT_WRITE_LIMIT = 6;
 function normalizeStringList6(values) {
   return [...new Set((values ?? []).map((value) => value.trim()).filter(Boolean))];
 }
+function uniqueStrings18(values) {
+  return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
+}
 function isRecord17(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -30832,6 +30835,73 @@ function verificationExecutedFromEvidence(evidence) {
     (item) => item.command ? `${item.label}: ${item.command} (${item.status})` : `${item.label}: ${item.status}`
   );
 }
+function buildPolicyDecisionRequest(args) {
+  const decision = args.run.policyGates.projectPolicyDecision;
+  if (!decision || decision.verdict === "allow") return void 0;
+  const changedFiles = args.run.brief.changedFiles.slice(0, 24);
+  const matchedRules = decision.matchedRules.slice(0, 8);
+  const options = decision.verdict === "block" ? ["respect_block", "request_exception", "mark_policy_stale"] : ["approve_once", "require_changes", "mark_policy_stale", "keep_advisory"];
+  const recommendation = decision.verdict === "block" ? "respect_block" : "approve_once";
+  return buildDecisionRequest({
+    producer: {
+      kind: "project_policy_review",
+      command: "run --emit-policy-decisions",
+      sourceRef: decision.receipt.receiptId
+    },
+    decision: `project_policy_${decision.verdict}`,
+    question: decision.verdict === "block" ? "Project Policy blocked this action. Should the agent stop, request an exception, or mark the policy stale?" : "Project Policy requires human review. May the agent proceed once, change plan, or mark the policy stale?",
+    evidence: {
+      summary: `Project Policy verdict ${decision.verdict} for task '${args.run.brief.task ?? "unspecified"}'. Receipt ${decision.receipt.receiptId}.`,
+      refs: uniqueStrings18([decision.receipt.receiptId, ...decision.receipt.ruleRefs]),
+      items: matchedRules.map((rule) => ({
+        ref: rule.source.ref,
+        title: rule.title,
+        summary: rule.requirement,
+        kind: rule.source.kind,
+        status: rule.strength,
+        metadata: {
+          ruleId: rule.id,
+          scope: rule.scope,
+          confidence: rule.confidence,
+          reviewStatus: rule.source.reviewStatus ?? null
+        }
+      })),
+      reasonCodes: uniqueStrings18(["project_policy_review", ...decision.reasonCodes]),
+      files: changedFiles,
+      applyPath: "manual_context_review",
+      applyCommand: "Resolve with `snipara-companion workflow decide <request-id> --choose <option> --reviewer <name>`; if policy is stale, update or invalidate the cited decision/policy before rerunning `snipara-companion run`."
+    },
+    options,
+    recommendation,
+    rationale: "Project Policy decisions stay agent-first: the agent asks for explicit human governance and records a response receipt; no dashboard or silent policy mutation is required.",
+    blocking: true,
+    fingerprintParts: [
+      "project_policy_review_v1",
+      decision.receipt.receiptId,
+      decision.verdict,
+      decision.receipt.ruleRefs,
+      changedFiles
+    ]
+  });
+}
+function emitPolicyDecisionRequests(run) {
+  const requests = [buildPolicyDecisionRequest({ run })].filter(
+    (request) => Boolean(request)
+  );
+  const writes = requests.map((request) => writeDecisionRequest(request));
+  return {
+    version: "project-intelligence.policy-decision-requests.v1",
+    emitted: true,
+    requestCount: requests.length,
+    requests,
+    writes,
+    caveats: [
+      "Policy decision requests never apply policy changes automatically.",
+      "Resolve them with workflow decide so the human choice is recorded as a local response receipt.",
+      "Marking a policy stale is a governance signal; the cited memory or policy still needs explicit update or invalidation."
+    ]
+  };
+}
 async function recordFirstPartyAdvisorReceipts(args) {
   const allRecommendations = args.judgmentCard.advisorRecommendations;
   if (args.options.skipAdvisorReceipts) {
@@ -31123,7 +31193,7 @@ async function buildProjectIntelligenceRun(options) {
       ...!options.skipPackageReview && packageReview?.status !== "ok" ? [packageReviewCommand3()] : []
     ] : []
   ];
-  return {
+  const result = {
     version: "project-intelligence.production-run.v1",
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     release: Boolean(options.release),
@@ -31136,6 +31206,10 @@ async function buildProjectIntelligenceRun(options) {
     judgmentCard,
     suggestedCommands: [...new Set(suggestedCommands3)]
   };
+  if (options.emitPolicyDecisions) {
+    result.policyDecisionRequests = emitPolicyDecisionRequests(result);
+  }
+  return result;
 }
 async function projectIntelligenceRunCommand(options) {
   const result = await buildProjectIntelligenceRun(options);
@@ -33304,6 +33378,9 @@ program.command("lead-plan").description("Create a fail-closed Companion Enginee
 program.command("run").description("Run the production Project Intelligence judgment flow for a task or release").option("--task <task>", "Current task or change summary").option("--branch <branch>", "Branch to scope continuity signals").option("--changed-files <changedFiles...>", "Changed files to analyze").option("--recent-files <recentFiles...>", "Recently touched files for continuity lookup").option("--diff-summary <diffSummary>", "Natural-language summary for code impact").option("--max-tokens <number>", "Resume context token budget", "4000").option("--release", "Run release-oriented guard and package surface review").option("--skip-impact", "Do not run companion code impact").option("--skip-memory-health", "Do not call snipara_memory_health").option("--skip-guard", "Skip collaboration guard during release runs").option("--skip-package-review", "Skip npm package surface review").option("--served-judgment-id <id>", "Served judgment id to use for first-party advisor receipts").option("--skip-advisor-receipts", "Skip first-party advisor influence receipt capture").option(
   "--outcome-receipts <files...>",
   "Outcome Intelligence V0 receipt JSON files for local calibration"
+).option(
+  "--emit-policy-decisions",
+  "Write local Decision Requests for Project Policy review/block findings"
 ).option("--json", "Print raw JSON").action(async (options) => {
   await projectIntelligenceRunCommand({
     task: options.task,
@@ -33320,6 +33397,7 @@ program.command("run").description("Run the production Project Intelligence judg
     servedJudgmentId: options.servedJudgmentId,
     skipAdvisorReceipts: Boolean(options.skipAdvisorReceipts),
     outcomeReceiptFiles: options.outcomeReceipts,
+    emitPolicyDecisions: Boolean(options.emitPolicyDecisions),
     json: Boolean(options.json)
   });
 });

package/docs/FULL_REFERENCE.md

@@ -288,6 +288,13 @@ snipara-companion workflow resume --include-session-context
   path declared. Repeated resolved receipts with the same human choice and
   rationale can emit a review-only policy suggestion decision request; the
   suggestion still has a manual apply path and is never auto-applied.
+- `run --emit-policy-decisions` keeps Project Policy administration agent-first:
+  when reviewed project policy evidence produces a `require_review` or `block`
+  verdict, Companion writes a local `project_policy_review` Decision Request.
+  The human resolves it with `workflow decide`; choices such as approving once,
+  requiring changes, respecting a block, requesting an exception, or marking
+  policy stale are recorded as receipts. No policy is edited or invalidated
+  automatically.
 - `memory reviews --scope project --emit-decisions` reads hosted memory review
   queue, clean-candidate, and duplicate-candidate surfaces, summarizes each item,
   and writes local Decision Request artifacts without mutating hosted memory.

package/package.json

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