snipara-companion 3.2.15 → 3.2.17

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          |
+| `workflow policy-ledger`                                     | Project Policy decisions for agent review and audit          |
 | `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          |
@@ -144,6 +145,7 @@ npx -y snipara-companion lead-plan --from-plan ./project-health-lead-plan.json -
 npx -y snipara-companion workflow phase-commit audit --summary "mapped auth impact"
 npx -y snipara-companion workflow producer-triage
 npx -y snipara-companion workflow decisions
+npx -y snipara-companion workflow policy-ledger
 npx -y snipara-companion workflow decide decision-abc123 --choose accept_all --reviewer alice
 npx -y snipara-companion workflow timeline
 npx -y snipara-companion workflow timeline --export md
@@ -193,6 +195,10 @@ opaque refs. Decision requests never resolve by timeout or default, and only
 When repeated resolved receipts share the same human choice and rationale,
 `workflow decide` may emit a new review-only policy suggestion decision request;
 it still uses manual apply instructions and never writes policy automatically.
+`workflow policy-ledger` gives the LLM agent a consolidated view of pending,
+approved, refused, modified, and deferred Project Policy decision artifacts,
+plus the exact pending requests it should ask the human about. It is read-only
+and does not apply policy edits.
 Other producers such as `outcome-capture preview --emit-decisions`,
 `memory reviews --emit-decisions`, `workflow decision-producer memory`, and
 `workflow decision-producer context-risk` emit requests with their existing apply

package/dist/index.d.ts

@@ -3149,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

@@ -18917,6 +18917,163 @@ function compactDecisionRequest(request, status) {
     expiresAt: request.expiresAt
   };
 }
+function isPolicyDecisionRequest(request) {
+  return request.producer.kind === "project_policy_review" || request.producer.kind === "policy_suggestion" || request.evidence.reasonCodes.some((code2) => /policy/i.test(code2)) || /project policy|policy suggestion|policy/i.test(
+    [
+      request.decision,
+      request.question,
+      request.evidence.summary,
+      request.evidence.applyPath ?? ""
+    ].join(" ")
+  );
+}
+function classifyResolvedPolicyDecisionChoice(choice) {
+  switch (choice) {
+    case "approve_once":
+    case "accept":
+    case "accept_all":
+    case "create_policy_suggestion":
+    case "keep_advisory":
+      return "approved";
+    case "reject":
+    case "reject_all":
+    case "reject_policy_suggestion":
+    case "require_changes":
+    case "respect_block":
+      return "refused";
+    case "mark_policy_stale":
+    case "request_exception":
+      return "modified";
+    case "ignore_once":
+    case "inspect":
+    case "defer":
+    default:
+      return "deferred";
+  }
+}
+function buildPolicyLedgerEntries() {
+  const pending = listPendingDecisionRequests().filter((entry) => isPolicyDecisionRequest(entry.request)).map((entry) => {
+    const request = entry.request;
+    return {
+      requestId: request.requestId,
+      fingerprint: request.fingerprint,
+      status: entry.status,
+      producerKind: request.producer.kind,
+      decision: request.decision,
+      question: request.question,
+      recommendation: request.recommendation,
+      evidenceSummary: request.evidence.summary,
+      reasonCodes: request.evidence.reasonCodes,
+      files: request.evidence.files ?? [],
+      applyPath: request.evidence.applyPath,
+      applyCommand: request.evidence.applyCommand,
+      createdAt: request.createdAt
+    };
+  });
+  const resolved = listResolvedDecisionRecords().filter((record) => isPolicyDecisionRequest(record.request)).map((record) => {
+    const request = record.request;
+    return {
+      requestId: request.requestId,
+      fingerprint: request.fingerprint,
+      status: classifyResolvedPolicyDecisionChoice(record.response.choice),
+      producerKind: request.producer.kind,
+      decision: request.decision,
+      question: request.question,
+      recommendation: request.recommendation,
+      humanChoice: record.response.choice,
+      reviewer: record.response.reviewer,
+      note: record.response.note,
+      evidenceSummary: request.evidence.summary,
+      reasonCodes: request.evidence.reasonCodes,
+      files: request.evidence.files ?? [],
+      applyPath: request.evidence.applyPath,
+      applyCommand: request.evidence.applyCommand,
+      createdAt: request.createdAt,
+      resolvedAt: record.response.resolvedAt
+    };
+  });
+  return [...pending, ...resolved].sort((left, right) => {
+    const leftTime = left.resolvedAt ?? left.createdAt;
+    const rightTime = right.resolvedAt ?? right.createdAt;
+    return rightTime.localeCompare(leftTime) || left.requestId.localeCompare(right.requestId);
+  });
+}
+function summarizePolicyLedger(entries) {
+  const counts = {
+    pending: 0,
+    expired_pending: 0,
+    approved: 0,
+    refused: 0,
+    modified: 0,
+    deferred: 0
+  };
+  for (const entry of entries) {
+    counts[entry.status] += 1;
+  }
+  return {
+    total: entries.length,
+    pending: counts.pending,
+    expiredPending: counts.expired_pending,
+    approved: counts.approved,
+    refused: counts.refused,
+    modified: counts.modified,
+    deferred: counts.deferred
+  };
+}
+function buildPolicyLedgerAgentPrompt(entries) {
+  const active = entries.filter(
+    (entry) => entry.status === "pending" || entry.status === "expired_pending"
+  );
+  if (active.length === 0) {
+    return ["No pending Project Policy decision needs a human response right now."];
+  }
+  return active.slice(0, 5).map((entry) => {
+    const options = entry.recommendation ? ` Recommended: ${entry.recommendation}.` : "";
+    return `Ask the user: ${entry.question} Options are recorded in the pending Decision Request.${options} Resolve with snipara-companion workflow decide ${entry.requestId} --choose <human-choice> --reviewer <name>.`;
+  });
+}
+async function workflowPolicyLedgerCommand(options) {
+  const entries = buildPolicyLedgerEntries();
+  const summary = summarizePolicyLedger(entries);
+  const payload = {
+    version: "snipara.workflow_policy_ledger.v0",
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    summary,
+    entries,
+    agentPrompt: buildPolicyLedgerAgentPrompt(entries),
+    caveats: [
+      "Policy ledger is observational; it never applies or edits Project Policy automatically.",
+      "The LLM agent must ask the user for pending policy decisions and resolve them with workflow decide.",
+      "The dashboard is for auditability and administration, not a replacement for explicit human approval."
+    ]
+  };
+  if (options.json) {
+    printJson2(payload);
+    return;
+  }
+  console.log(import_chalk6.default.bold("Project Policy Ledger"));
+  printKeyValue2("Pending:", String(summary.pending));
+  printKeyValue2("Approved:", String(summary.approved));
+  printKeyValue2("Refused:", String(summary.refused));
+  printKeyValue2("Modified:", String(summary.modified));
+  if (entries.length === 0) {
+    console.log("No Project Policy decision artifacts found.");
+    return;
+  }
+  for (const entry of entries.slice(0, 20)) {
+    const actor = entry.reviewer ? ` by ${entry.reviewer}` : "";
+    console.log(`- ${entry.requestId} [${entry.status}${actor}] ${entry.question}`);
+    if (entry.humanChoice) {
+      console.log(`  choice: ${entry.humanChoice}`);
+    }
+    console.log(`  evidence: ${entry.evidenceSummary}`);
+    if (entry.status === "pending" || entry.status === "expired_pending") {
+      console.log(
+        `  ask: snipara-companion workflow decide ${entry.requestId} --choose <human-choice> --reviewer <name>`
+      );
+    }
+  }
+}
 function printDecisionRequests(entries) {
   console.log(import_chalk6.default.bold("Pending Decision Requests"));
   if (entries.length === 0) {
@@ -23292,6 +23449,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 +23521,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 +23578,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 +23647,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);
@@ -34061,6 +34306,9 @@ workflow.command("scaffold").description("Generate a reusable managed workflow p
 workflow.command("decisions").description("List pending local decision requests for the LLM to ask the human").option("--json", "Print raw JSON").action(async (options) => {
   await workflowDecisionsCommand({ json: options.json });
 });
+workflow.command("policy-ledger").description("Summarize Project Policy decisions for agent-mediated review and audit").option("--json", "Print raw JSON").action(async (options) => {
+  await workflowPolicyLedgerCommand({ json: options.json });
+});
 workflow.command("decide").description("Resolve a pending local decision request with an explicit human choice").argument("<request-id>", "Decision request id or fingerprint").requiredOption("--choose <option>", "Chosen option from the decision request").requiredOption("--reviewer <name>", "Human reviewer name or handle").option("--note <note>", "Review note").option("--json", "Print raw JSON").action(async (requestId, options) => {
   await workflowDecideCommand({
     requestId,

package/docs/FULL_REFERENCE.md

@@ -225,6 +225,7 @@ snipara-companion workflow phase-commit build --summary "tests green"
 snipara-companion workflow impact-gate
 snipara-companion workflow producer-triage
 snipara-companion workflow decisions
+snipara-companion workflow policy-ledger
 snipara-companion workflow decide decision-abc123 --choose accept_all --reviewer alice
 snipara-companion workflow producer-report
 snipara-companion workflow producer-review --latest --outcome useful --reviewer alice
@@ -280,6 +281,10 @@ snipara-companion workflow resume --include-session-context
   client can render as a human question, including evidence, options,
   recommendation, declared apply path, and readable evidence items for batched
   decisions.
+- `workflow policy-ledger` summarizes local Project Policy decision artifacts
+  for agent-mediated governance. It reports pending, approved, refused,
+  modified, deferred, and expired policy decisions, includes agent prompts for
+  pending human choices, and never applies or edits policy automatically.
 - `workflow decide <request-id> --choose <option> --reviewer <name>` writes a
   Decision Response receipt under `.snipara/decisions/resolved/`. For
   Producer Loop triage accept/reject choices, it applies the existing
@@ -1277,6 +1282,7 @@ Semantics:
 - `snipara-companion workflow phase-commit` = calls hosted `snipara_end_of_task_commit` for that phase, updates local state, and advances the next phase; if the hosted commit times out or hits a transient network failure, local workflow state still advances with an explicit local fallback record
 - `snipara-companion workflow phase-commit` and `workflow final-commit` also emit local Producer Loop artifacts under `.snipara/producer-loop/`, backed by the redacted Coding Intelligence Ledger. PR Answer Pack decision capture uses the same schema with producer kind `pr_answer_pack_decision_capture` when the artifact is exported or embedded by the hosted PR pack producer. These artifacts are review evidence only: they do not launch workers, approve durable memory, claim calibrated confidence, or provide server-side attestation.
 - `snipara-companion workflow decisions` = lists local pending Decision Request artifacts for LLM clients to ask the human, with evidence, options, recommendation, and apply-path metadata
+- `snipara-companion workflow policy-ledger` = read-only local Project Policy ledger for pending, approved, refused, modified, deferred, and expired policy decisions, including agent prompts for unresolved human choices
 - `snipara-companion workflow decide` = records a Decision Response receipt and moves the request to `.snipara/decisions/resolved/`; it never resolves by timeout/default, only applies existing reviewed paths such as `workflow producer-review`, and may emit review-only policy suggestion requests when repeated receipts show the same human rule
 - `snipara-companion workflow producer-triage` = emits a batched decision request for unreviewed Producer Loop samples; it does not mark samples reviewed until `workflow decide` records the human answer
 - `snipara-companion workflow producer-report` = scans local Producer Loop artifacts and reports adoption, producer kinds, workflow ids, latest artifact, reason-code counts, invalid artifacts, sample size, reviewed/rejected/unreviewed counts, and calibration caveats with `hardGateReady=false`

package/package.json

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