snipara-companion 3.2.16 → 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.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) {
@@ -34149,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.16",
+  "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": {