snipara-companion 3.2.14 → 3.2.16

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>;
 
@@ -3131,6 +3149,14 @@ interface AgenticWorkStatus {
         count?: number;
         note: string;
     };
+    operationalLoop: {
+        status: "clear" | "attention" | "blocked";
+        decisionRequestCount: number;
+        receiptGapCount: number;
+        nextActions: string[];
+        receiptActions: string[];
+        caveats: string[];
+    };
     suggestedNextAction: string;
 }
 interface AgenticTimelineEvent {

package/dist/index.js

@@ -23292,6 +23292,68 @@ function buildSuggestedAgenticNextAction(state, risks) {
   }
   return "Run snipara-companion workflow status to inspect the managed workflow.";
 }
+function buildAgenticOperationalLoop(args) {
+  const phase = args.state ? currentWorkflowPhase(args.state) : void 0;
+  const nextActions = [];
+  const receiptActions = [];
+  const caveats = [
+    "Operational Loop is local and advisory; it does not edit Project Policy, approve memory, or bypass verification."
+  ];
+  let receiptGapCount = 0;
+  if (args.pendingDecisionCount > 0) {
+    nextActions.push(
+      `Resolve ${args.pendingDecisionCount} local Decision Request${args.pendingDecisionCount === 1 ? "" : "s"} with snipara-companion workflow decisions and workflow decide.`
+    );
+  }
+  if (args.teamSyncSummary.staleWorkCount > 0) {
+    nextActions.push(
+      "Review stale Team Sync work with snipara-companion team-sync sweep --dry-run before continuing."
+    );
+  }
+  if (args.dirtyFileCount > 0) {
+    nextActions.push("Review dirty git state and run the relevant checks before phase-commit.");
+  }
+  if (args.latestHandoff?.next) {
+    nextActions.push(
+      `Continue latest handoff next step: ${toPreview(args.latestHandoff.next, 160)}`
+    );
+  }
+  if (phase?.status === "blocked") {
+    nextActions.push(`Unblock current phase '${phase.id}' before new implementation work.`);
+  } else if (phase) {
+    nextActions.push(
+      `Continue phase '${phase.id}' and close it with snipara-companion workflow phase-commit ${phase.id}.`
+    );
+  } else if (!args.state) {
+    nextActions.push("Start a managed workflow before multi-step implementation work.");
+  }
+  if (args.state && args.state.status !== "completed") {
+    receiptGapCount += 1;
+    receiptActions.push(
+      "Before closing the phase, capture why/outcome evidence with snipara-companion outcome-capture preview --emit-outcome-receipt."
+    );
+  }
+  if (args.latestHandoff && args.latestHandoff.attention !== "note") {
+    receiptGapCount += 1;
+    receiptActions.push(
+      "Treat the latest Team Sync handoff as needing proof/review evidence before final-commit."
+    );
+  }
+  if (args.pendingDecisionCount > 0) {
+    receiptActions.push(
+      "Decision Request resolution records the human choice; follow-up policy edits remain explicit."
+    );
+  }
+  const status = phase?.status === "blocked" ? "blocked" : args.risks.length > 0 || args.pendingDecisionCount > 0 || receiptGapCount > 0 ? "attention" : "clear";
+  return {
+    status,
+    decisionRequestCount: args.pendingDecisionCount,
+    receiptGapCount,
+    nextActions: uniqueStrings16(nextActions).slice(0, 6),
+    receiptActions: uniqueStrings16(receiptActions).slice(0, 4),
+    caveats
+  };
+}
 function buildAgenticWorkStatus(cwd = process.cwd()) {
   const state = readWorkflowState2(cwd);
   const git = readLocalGitState(cwd);
@@ -23302,6 +23364,7 @@ function buildAgenticWorkStatus(cwd = process.cwd()) {
   const currentPhase = state ? currentWorkflowPhase(state) : void 0;
   const lastPhaseCommit = lastCompletedWorkflowPhase(state);
   const dirtyFileCount = git.statusLines?.length ?? 0;
+  const pendingDecisionCount = decisionPendingCount(cwd);
   const risks = buildAgenticStatusRisks({
     state,
     dirtyFileCount,
@@ -23358,8 +23421,17 @@ function buildAgenticWorkStatus(cwd = process.cwd()) {
     },
     risks,
     openDecisions: {
+      count: pendingDecisionCount,
       note: "Run snipara-companion brief for hosted decisions and memory authority signals."
     },
+    operationalLoop: buildAgenticOperationalLoop({
+      state,
+      dirtyFileCount,
+      risks,
+      pendingDecisionCount,
+      teamSyncSummary,
+      latestHandoff
+    }),
     suggestedNextAction: buildSuggestedAgenticNextAction(state, risks)
   };
 }
@@ -23418,8 +23490,24 @@ function printAgenticWorkStatus(status) {
   }
   console.log("");
   console.log(import_chalk6.default.bold("Open Decisions"));
+  if (typeof status.openDecisions.count === "number") {
+    console.log(`Local pending Decision Requests: ${status.openDecisions.count}`);
+  }
   console.log(status.openDecisions.note);
   console.log("");
+  console.log(import_chalk6.default.bold("Operational Loop"));
+  console.log(`Status: ${status.operationalLoop.status}`);
+  console.log(`Receipt gaps: ${status.operationalLoop.receiptGapCount}`);
+  for (const action of status.operationalLoop.nextActions) {
+    console.log(`- ${action}`);
+  }
+  for (const action of status.operationalLoop.receiptActions) {
+    console.log(`- ${action}`);
+  }
+  for (const caveat of status.operationalLoop.caveats) {
+    console.log(`- ${caveat}`);
+  }
+  console.log("");
   printKeyValue2("Next suggested action:", status.suggestedNextAction);
   if (status.workflow) {
     printKeyValue2("Resume:", status.workflow.resumeCommand);
@@ -30575,6 +30663,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 +30923,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 +31281,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 +31294,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 +33466,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 +33485,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.16",
   "description": "Local-first CLI that asks your repo what breaks before an AI coding agent edits it.",
   "main": "dist/index.js",
   "bin": {