@riddledc/riddle-proof-packs 0.4.4 → 0.4.5

package/README.md

@@ -110,6 +110,16 @@ The `neon-step-sequencer` directory contains the first app-specific ratchet lab
 
 Human-review packets are proof artifacts for subjective follow-up. They are deliberately not taste scores. A packet should say what objective receipts passed, what was preserved, which candidate is ready for listening review, and which caveats remain.
 
+From the CLI:
+
+```sh
+riddle-proof-review-packet \
+  --proof artifacts/riddle-proof/proof.json \
+  --output artifacts/riddle-proof
+```
+
+This writes `human-review-packet.json` and `human-review-packet.md` next to the proof run. Use `--stdout` when an agent should read the Markdown handoff immediately.
+
 ```ts
 import {
   createHumanReviewPacketArtifacts,

package/bin/riddle-proof-review-packet

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+const cliPath = new URL("../dist/reviewPacketCli.js", import.meta.url);
+await import(cliPath.href);

package/dist/chunk-XQ2N4EYF.js

@@ -0,0 +1,135 @@
+// src/humanReviewPacket.ts
+var isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+var asRecord = (value) => isRecord(value) ? value : null;
+var asArray = (value) => Array.isArray(value) ? value : [];
+var getPath = (value, path) => {
+  let cursor = value;
+  for (const part of path.split(".")) {
+    if (!isRecord(cursor)) return void 0;
+    cursor = cursor[part];
+  }
+  return cursor;
+};
+var formatValue = (value) => {
+  if (value === null || value === void 0 || value === "") return "not captured";
+  if (typeof value === "number") return Number.isInteger(value) ? String(value) : String(Number(value.toFixed(4)));
+  if (typeof value === "boolean") return value ? "true" : "false";
+  return String(value);
+};
+var formatCodeValue = (value) => `\`${formatValue(value)}\``;
+var formatAction = (action) => {
+  const record = asRecord(action);
+  if (!record) return "not captured";
+  const type = record.type ?? "set_mixer_level";
+  const track = record.track ?? "track";
+  const from = formatValue(record.from);
+  const to = formatValue(record.to);
+  const delta = record.delta === null || record.delta === void 0 ? "" : ` (${formatValue(record.delta)})`;
+  return `${type} ${track}: ${from} -> ${to}${delta}`;
+};
+var addOptionalList = (lines, heading, values) => {
+  const entries = asArray(values).filter((entry) => entry !== null && entry !== void 0 && entry !== "");
+  if (!entries.length) return;
+  lines.push("", `## ${heading}`, "");
+  for (const entry of entries) lines.push(`- ${formatValue(entry)}`);
+};
+function findHumanReviewPacket(value) {
+  if (!value || typeof value !== "object") return null;
+  if (isRecord(value) && value.kind === "human_review_packet") return value;
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      const packet = findHumanReviewPacket(entry);
+      if (packet) return packet;
+    }
+    return null;
+  }
+  for (const entry of Object.values(value)) {
+    const packet = findHumanReviewPacket(entry);
+    if (packet) return packet;
+  }
+  return null;
+}
+function requireHumanReviewPacket(value) {
+  const packet = findHumanReviewPacket(value);
+  if (!packet) throw new Error("No human_review_packet found");
+  return packet;
+}
+function formatHumanReviewPacketMarkdown(packet, options = {}) {
+  if (packet.kind !== "human_review_packet") {
+    throw new Error("Expected a human_review_packet");
+  }
+  const recommendation = asRecord(packet.recommendation) ?? {};
+  const candidate = asRecord(recommendation.candidate) ?? {};
+  const guardrails = asRecord(packet.guardrails) ?? {};
+  const ranking = asRecord(packet.ranking) ?? {};
+  const request = asRecord(packet.request) ?? {};
+  const supportedCandidates = asArray(packet.supportedCandidates);
+  const rejectedCandidates = asArray(packet.rejectedCandidates);
+  const selectedSong = getPath(packet, "target.selectedSong.selectedSong") ?? getPath(packet, "target.routeState.selectedSong");
+  const lines = [
+    `# ${options.title ?? "Human Review Packet"}`,
+    "",
+    `- status: ${formatCodeValue(packet.status)}`,
+    `- domain: ${formatCodeValue(packet.domain)}`,
+    `- evidence_role_pattern: ${formatCodeValue(packet.evidenceRolePattern)}`,
+    `- requested_intent: ${formatValue(packet.requestedIntent)}`,
+    `- selected_song: ${formatValue(selectedSong)}`,
+    "",
+    "## Recommendation",
+    "",
+    `- action: ${formatCodeValue(recommendation.action)}`,
+    `- candidate: ${formatCodeValue(candidate.label)}`,
+    `- candidate_action: ${formatCodeValue(formatAction(candidate.action))}`,
+    `- reason: ${formatValue(recommendation.reason)}`,
+    "",
+    "## Objective Receipts",
+    "",
+    `- supported_candidates: ${formatCodeValue(guardrails.supportedClaimCandidateCount ?? supportedCandidates.length)}`,
+    `- rejected_candidates: ${formatCodeValue(guardrails.rejectedCandidateCount ?? rejectedCandidates.length)}`,
+    `- state_restored_after_loop: ${formatCodeValue(guardrails.stateRestoredAfterLoop)}`,
+    `- candidate_actions_are_transient: ${formatCodeValue(request.candidateActionsAreTransient)}`,
+    `- no_permanent_edit_unless_apply_best: ${formatCodeValue(guardrails.noPermanentEditUnlessApplyBest)}`,
+    "",
+    "## Ranking",
+    "",
+    `- metric: ${formatCodeValue(ranking.metric)}`,
+    `- role: ${formatCodeValue(ranking.role)}`,
+    `- lower_is_better: ${formatCodeValue(ranking.lowerIsBetter)}`,
+    `- baseline: ${formatCodeValue(ranking.baselineCandidateRankingMetric)}`,
+    `- best: ${formatCodeValue(ranking.bestCandidateRankingMetric)}`,
+    `- delta: ${formatCodeValue(ranking.rankingMetricDelta)}`,
+    "",
+    "## Boundary",
+    "",
+    formatValue(packet.proofBoundary)
+  ];
+  addOptionalList(lines, "Listening Prompts", packet.listenerPrompts);
+  addOptionalList(lines, "Caveats", packet.caveats);
+  if (rejectedCandidates.length) {
+    lines.push("", "## Rejected Candidates", "");
+    for (const entry of rejectedCandidates) {
+      const rejected = asRecord(entry) ?? {};
+      const failedReceipts = asArray(rejected.failedReceipts).map(formatValue).join(", ") || "not captured";
+      lines.push(`- ${formatCodeValue(rejected.label)}: ${failedReceipts}`);
+    }
+  }
+  return `${lines.join("\n")}
+`;
+}
+function createHumanReviewPacketArtifacts(proofOrPacket, options = {}) {
+  const packet = requireHumanReviewPacket(proofOrPacket);
+  const markdown = formatHumanReviewPacketMarkdown(packet, options);
+  return {
+    packet,
+    json: `${JSON.stringify(packet, null, 2)}
+`,
+    markdown
+  };
+}
+
+export {
+  findHumanReviewPacket,
+  requireHumanReviewPacket,
+  formatHumanReviewPacketMarkdown,
+  createHumanReviewPacketArtifacts
+};

package/dist/humanReviewPacket-APSxuvat.d.cts

@@ -0,0 +1,17 @@
+type HumanReviewPacket = Record<string, unknown> & {
+    kind: "human_review_packet";
+};
+interface HumanReviewPacketMarkdownOptions {
+    title?: string;
+}
+interface HumanReviewPacketArtifacts {
+    packet: HumanReviewPacket;
+    json: string;
+    markdown: string;
+}
+declare function findHumanReviewPacket(value: unknown): HumanReviewPacket | null;
+declare function requireHumanReviewPacket(value: unknown): HumanReviewPacket;
+declare function formatHumanReviewPacketMarkdown(packet: HumanReviewPacket, options?: HumanReviewPacketMarkdownOptions): string;
+declare function createHumanReviewPacketArtifacts(proofOrPacket: unknown, options?: HumanReviewPacketMarkdownOptions): HumanReviewPacketArtifacts;
+
+export { type HumanReviewPacket as H, type HumanReviewPacketArtifacts as a, type HumanReviewPacketMarkdownOptions as b, createHumanReviewPacketArtifacts as c, formatHumanReviewPacketMarkdown as d, findHumanReviewPacket as f, requireHumanReviewPacket as r };

package/dist/humanReviewPacket-APSxuvat.d.ts

@@ -0,0 +1,17 @@
+type HumanReviewPacket = Record<string, unknown> & {
+    kind: "human_review_packet";
+};
+interface HumanReviewPacketMarkdownOptions {
+    title?: string;
+}
+interface HumanReviewPacketArtifacts {
+    packet: HumanReviewPacket;
+    json: string;
+    markdown: string;
+}
+declare function findHumanReviewPacket(value: unknown): HumanReviewPacket | null;
+declare function requireHumanReviewPacket(value: unknown): HumanReviewPacket;
+declare function formatHumanReviewPacketMarkdown(packet: HumanReviewPacket, options?: HumanReviewPacketMarkdownOptions): string;
+declare function createHumanReviewPacketArtifacts(proofOrPacket: unknown, options?: HumanReviewPacketMarkdownOptions): HumanReviewPacketArtifacts;
+
+export { type HumanReviewPacket as H, type HumanReviewPacketArtifacts as a, type HumanReviewPacketMarkdownOptions as b, createHumanReviewPacketArtifacts as c, formatHumanReviewPacketMarkdown as d, findHumanReviewPacket as f, requireHumanReviewPacket as r };

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import * as _riddledc_riddle_proof from '@riddledc/riddle-proof';
 import { RiddleProofProfile } from '@riddledc/riddle-proof';
+export { H as HumanReviewPacket, a as HumanReviewPacketArtifacts, b as HumanReviewPacketMarkdownOptions, c as createHumanReviewPacketArtifacts, f as findHumanReviewPacket, d as formatHumanReviewPacketMarkdown, r as requireHumanReviewPacket } from './humanReviewPacket-APSxuvat.cjs';
 
 interface RiddleProofPackProfileManifest {
     /** Profile slug and canonical manifest key. */
@@ -59,20 +60,4 @@ interface RiddleProofPackProfileOverrides {
  */
 declare function instantiateRiddleProofProfile(profileName: string, options?: RiddleProofPackProfileOverrides): RiddleProofProfile;
 
-type HumanReviewPacket = Record<string, unknown> & {
-    kind: "human_review_packet";
-};
-interface HumanReviewPacketMarkdownOptions {
-    title?: string;
-}
-interface HumanReviewPacketArtifacts {
-    packet: HumanReviewPacket;
-    json: string;
-    markdown: string;
-}
-declare function findHumanReviewPacket(value: unknown): HumanReviewPacket | null;
-declare function requireHumanReviewPacket(value: unknown): HumanReviewPacket;
-declare function formatHumanReviewPacketMarkdown(packet: HumanReviewPacket, options?: HumanReviewPacketMarkdownOptions): string;
-declare function createHumanReviewPacketArtifacts(proofOrPacket: unknown, options?: HumanReviewPacketMarkdownOptions): HumanReviewPacketArtifacts;
-
-export { type HumanReviewPacket, type HumanReviewPacketArtifacts, type HumanReviewPacketMarkdownOptions, RIDDLE_PROOF_PACK_MANIFEST, RIDDLE_PROOF_PACK_PROFILES, type RiddleProofPackProfileManifest, createHumanReviewPacketArtifacts, findHumanReviewPacket, formatHumanReviewPacketMarkdown, getPackEnabledRiddleProofPackProfiles, getRiddleProofPackProfile, getRiddleProofPackProfileByPackId, getRiddleProofPackProfileManifest, getRiddleProofProfilesByPackId, instantiateRiddleProofProfile, listRiddleProofPackProfiles, listRiddleProofPacks, requireHumanReviewPacket };
+export { RIDDLE_PROOF_PACK_MANIFEST, RIDDLE_PROOF_PACK_PROFILES, type RiddleProofPackProfileManifest, getPackEnabledRiddleProofPackProfiles, getRiddleProofPackProfile, getRiddleProofPackProfileByPackId, getRiddleProofPackProfileManifest, getRiddleProofProfilesByPackId, instantiateRiddleProofProfile, listRiddleProofPackProfiles, listRiddleProofPacks };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import * as _riddledc_riddle_proof from '@riddledc/riddle-proof';
 import { RiddleProofProfile } from '@riddledc/riddle-proof';
+export { H as HumanReviewPacket, a as HumanReviewPacketArtifacts, b as HumanReviewPacketMarkdownOptions, c as createHumanReviewPacketArtifacts, f as findHumanReviewPacket, d as formatHumanReviewPacketMarkdown, r as requireHumanReviewPacket } from './humanReviewPacket-APSxuvat.js';
 
 interface RiddleProofPackProfileManifest {
     /** Profile slug and canonical manifest key. */
@@ -59,20 +60,4 @@ interface RiddleProofPackProfileOverrides {
  */
 declare function instantiateRiddleProofProfile(profileName: string, options?: RiddleProofPackProfileOverrides): RiddleProofProfile;
 
-type HumanReviewPacket = Record<string, unknown> & {
-    kind: "human_review_packet";
-};
-interface HumanReviewPacketMarkdownOptions {
-    title?: string;
-}
-interface HumanReviewPacketArtifacts {
-    packet: HumanReviewPacket;
-    json: string;
-    markdown: string;
-}
-declare function findHumanReviewPacket(value: unknown): HumanReviewPacket | null;
-declare function requireHumanReviewPacket(value: unknown): HumanReviewPacket;
-declare function formatHumanReviewPacketMarkdown(packet: HumanReviewPacket, options?: HumanReviewPacketMarkdownOptions): string;
-declare function createHumanReviewPacketArtifacts(proofOrPacket: unknown, options?: HumanReviewPacketMarkdownOptions): HumanReviewPacketArtifacts;
-
-export { type HumanReviewPacket, type HumanReviewPacketArtifacts, type HumanReviewPacketMarkdownOptions, RIDDLE_PROOF_PACK_MANIFEST, RIDDLE_PROOF_PACK_PROFILES, type RiddleProofPackProfileManifest, createHumanReviewPacketArtifacts, findHumanReviewPacket, formatHumanReviewPacketMarkdown, getPackEnabledRiddleProofPackProfiles, getRiddleProofPackProfile, getRiddleProofPackProfileByPackId, getRiddleProofPackProfileManifest, getRiddleProofProfilesByPackId, instantiateRiddleProofProfile, listRiddleProofPackProfiles, listRiddleProofPacks, requireHumanReviewPacket };
+export { RIDDLE_PROOF_PACK_MANIFEST, RIDDLE_PROOF_PACK_PROFILES, type RiddleProofPackProfileManifest, getPackEnabledRiddleProofPackProfiles, getRiddleProofPackProfile, getRiddleProofPackProfileByPackId, getRiddleProofPackProfileManifest, getRiddleProofProfilesByPackId, instantiateRiddleProofProfile, listRiddleProofPackProfiles, listRiddleProofPacks };

package/dist/index.js

@@ -1,3 +1,10 @@
+import {
+  createHumanReviewPacketArtifacts,
+  findHumanReviewPacket,
+  formatHumanReviewPacketMarkdown,
+  requireHumanReviewPacket
+} from "./chunk-XQ2N4EYF.js";
+
 // src/pack-data.ts
 import { normalizeRiddleProofProfile } from "@riddledc/riddle-proof";
 
@@ -2310,135 +2317,6 @@ function instantiateRiddleProofProfile(profileName, options = {}) {
     }
   );
 }
-
-// src/humanReviewPacket.ts
-var isRecord2 = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
-var asRecord = (value) => isRecord2(value) ? value : null;
-var asArray = (value) => Array.isArray(value) ? value : [];
-var getPath = (value, path) => {
-  let cursor = value;
-  for (const part of path.split(".")) {
-    if (!isRecord2(cursor)) return void 0;
-    cursor = cursor[part];
-  }
-  return cursor;
-};
-var formatValue = (value) => {
-  if (value === null || value === void 0 || value === "") return "not captured";
-  if (typeof value === "number") return Number.isInteger(value) ? String(value) : String(Number(value.toFixed(4)));
-  if (typeof value === "boolean") return value ? "true" : "false";
-  return String(value);
-};
-var formatCodeValue = (value) => `\`${formatValue(value)}\``;
-var formatAction = (action) => {
-  const record = asRecord(action);
-  if (!record) return "not captured";
-  const type = record.type ?? "set_mixer_level";
-  const track = record.track ?? "track";
-  const from = formatValue(record.from);
-  const to = formatValue(record.to);
-  const delta = record.delta === null || record.delta === void 0 ? "" : ` (${formatValue(record.delta)})`;
-  return `${type} ${track}: ${from} -> ${to}${delta}`;
-};
-var addOptionalList = (lines, heading, values) => {
-  const entries = asArray(values).filter((entry) => entry !== null && entry !== void 0 && entry !== "");
-  if (!entries.length) return;
-  lines.push("", `## ${heading}`, "");
-  for (const entry of entries) lines.push(`- ${formatValue(entry)}`);
-};
-function findHumanReviewPacket(value) {
-  if (!value || typeof value !== "object") return null;
-  if (isRecord2(value) && value.kind === "human_review_packet") return value;
-  if (Array.isArray(value)) {
-    for (const entry of value) {
-      const packet = findHumanReviewPacket(entry);
-      if (packet) return packet;
-    }
-    return null;
-  }
-  for (const entry of Object.values(value)) {
-    const packet = findHumanReviewPacket(entry);
-    if (packet) return packet;
-  }
-  return null;
-}
-function requireHumanReviewPacket(value) {
-  const packet = findHumanReviewPacket(value);
-  if (!packet) throw new Error("No human_review_packet found");
-  return packet;
-}
-function formatHumanReviewPacketMarkdown(packet, options = {}) {
-  if (packet.kind !== "human_review_packet") {
-    throw new Error("Expected a human_review_packet");
-  }
-  const recommendation = asRecord(packet.recommendation) ?? {};
-  const candidate = asRecord(recommendation.candidate) ?? {};
-  const guardrails = asRecord(packet.guardrails) ?? {};
-  const ranking = asRecord(packet.ranking) ?? {};
-  const request = asRecord(packet.request) ?? {};
-  const supportedCandidates = asArray(packet.supportedCandidates);
-  const rejectedCandidates = asArray(packet.rejectedCandidates);
-  const selectedSong = getPath(packet, "target.selectedSong.selectedSong") ?? getPath(packet, "target.routeState.selectedSong");
-  const lines = [
-    `# ${options.title ?? "Human Review Packet"}`,
-    "",
-    `- status: ${formatCodeValue(packet.status)}`,
-    `- domain: ${formatCodeValue(packet.domain)}`,
-    `- evidence_role_pattern: ${formatCodeValue(packet.evidenceRolePattern)}`,
-    `- requested_intent: ${formatValue(packet.requestedIntent)}`,
-    `- selected_song: ${formatValue(selectedSong)}`,
-    "",
-    "## Recommendation",
-    "",
-    `- action: ${formatCodeValue(recommendation.action)}`,
-    `- candidate: ${formatCodeValue(candidate.label)}`,
-    `- candidate_action: ${formatCodeValue(formatAction(candidate.action))}`,
-    `- reason: ${formatValue(recommendation.reason)}`,
-    "",
-    "## Objective Receipts",
-    "",
-    `- supported_candidates: ${formatCodeValue(guardrails.supportedClaimCandidateCount ?? supportedCandidates.length)}`,
-    `- rejected_candidates: ${formatCodeValue(guardrails.rejectedCandidateCount ?? rejectedCandidates.length)}`,
-    `- state_restored_after_loop: ${formatCodeValue(guardrails.stateRestoredAfterLoop)}`,
-    `- candidate_actions_are_transient: ${formatCodeValue(request.candidateActionsAreTransient)}`,
-    `- no_permanent_edit_unless_apply_best: ${formatCodeValue(guardrails.noPermanentEditUnlessApplyBest)}`,
-    "",
-    "## Ranking",
-    "",
-    `- metric: ${formatCodeValue(ranking.metric)}`,
-    `- role: ${formatCodeValue(ranking.role)}`,
-    `- lower_is_better: ${formatCodeValue(ranking.lowerIsBetter)}`,
-    `- baseline: ${formatCodeValue(ranking.baselineCandidateRankingMetric)}`,
-    `- best: ${formatCodeValue(ranking.bestCandidateRankingMetric)}`,
-    `- delta: ${formatCodeValue(ranking.rankingMetricDelta)}`,
-    "",
-    "## Boundary",
-    "",
-    formatValue(packet.proofBoundary)
-  ];
-  addOptionalList(lines, "Listening Prompts", packet.listenerPrompts);
-  addOptionalList(lines, "Caveats", packet.caveats);
-  if (rejectedCandidates.length) {
-    lines.push("", "## Rejected Candidates", "");
-    for (const entry of rejectedCandidates) {
-      const rejected = asRecord(entry) ?? {};
-      const failedReceipts = asArray(rejected.failedReceipts).map(formatValue).join(", ") || "not captured";
-      lines.push(`- ${formatCodeValue(rejected.label)}: ${failedReceipts}`);
-    }
-  }
-  return `${lines.join("\n")}
-`;
-}
-function createHumanReviewPacketArtifacts(proofOrPacket, options = {}) {
-  const packet = requireHumanReviewPacket(proofOrPacket);
-  const markdown = formatHumanReviewPacketMarkdown(packet, options);
-  return {
-    packet,
-    json: `${JSON.stringify(packet, null, 2)}
-`,
-    markdown
-  };
-}
 export {
   RIDDLE_PROOF_PACK_MANIFEST,
   RIDDLE_PROOF_PACK_PROFILES,

package/dist/reviewPacketCli.cjs

@@ -0,0 +1,319 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/reviewPacketCli.ts
+var reviewPacketCli_exports = {};
+__export(reviewPacketCli_exports, {
+  main: () => main,
+  parseReviewPacketCliArgs: () => parseReviewPacketCliArgs,
+  writeReviewPacketFiles: () => writeReviewPacketFiles
+});
+module.exports = __toCommonJS(reviewPacketCli_exports);
+var import_node_fs = require("fs");
+var import_node_path = __toESM(require("path"), 1);
+
+// src/humanReviewPacket.ts
+var isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+var asRecord = (value) => isRecord(value) ? value : null;
+var asArray = (value) => Array.isArray(value) ? value : [];
+var getPath = (value, path2) => {
+  let cursor = value;
+  for (const part of path2.split(".")) {
+    if (!isRecord(cursor)) return void 0;
+    cursor = cursor[part];
+  }
+  return cursor;
+};
+var formatValue = (value) => {
+  if (value === null || value === void 0 || value === "") return "not captured";
+  if (typeof value === "number") return Number.isInteger(value) ? String(value) : String(Number(value.toFixed(4)));
+  if (typeof value === "boolean") return value ? "true" : "false";
+  return String(value);
+};
+var formatCodeValue = (value) => `\`${formatValue(value)}\``;
+var formatAction = (action) => {
+  const record = asRecord(action);
+  if (!record) return "not captured";
+  const type = record.type ?? "set_mixer_level";
+  const track = record.track ?? "track";
+  const from = formatValue(record.from);
+  const to = formatValue(record.to);
+  const delta = record.delta === null || record.delta === void 0 ? "" : ` (${formatValue(record.delta)})`;
+  return `${type} ${track}: ${from} -> ${to}${delta}`;
+};
+var addOptionalList = (lines, heading, values) => {
+  const entries = asArray(values).filter((entry) => entry !== null && entry !== void 0 && entry !== "");
+  if (!entries.length) return;
+  lines.push("", `## ${heading}`, "");
+  for (const entry of entries) lines.push(`- ${formatValue(entry)}`);
+};
+function findHumanReviewPacket(value) {
+  if (!value || typeof value !== "object") return null;
+  if (isRecord(value) && value.kind === "human_review_packet") return value;
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      const packet = findHumanReviewPacket(entry);
+      if (packet) return packet;
+    }
+    return null;
+  }
+  for (const entry of Object.values(value)) {
+    const packet = findHumanReviewPacket(entry);
+    if (packet) return packet;
+  }
+  return null;
+}
+function requireHumanReviewPacket(value) {
+  const packet = findHumanReviewPacket(value);
+  if (!packet) throw new Error("No human_review_packet found");
+  return packet;
+}
+function formatHumanReviewPacketMarkdown(packet, options = {}) {
+  if (packet.kind !== "human_review_packet") {
+    throw new Error("Expected a human_review_packet");
+  }
+  const recommendation = asRecord(packet.recommendation) ?? {};
+  const candidate = asRecord(recommendation.candidate) ?? {};
+  const guardrails = asRecord(packet.guardrails) ?? {};
+  const ranking = asRecord(packet.ranking) ?? {};
+  const request = asRecord(packet.request) ?? {};
+  const supportedCandidates = asArray(packet.supportedCandidates);
+  const rejectedCandidates = asArray(packet.rejectedCandidates);
+  const selectedSong = getPath(packet, "target.selectedSong.selectedSong") ?? getPath(packet, "target.routeState.selectedSong");
+  const lines = [
+    `# ${options.title ?? "Human Review Packet"}`,
+    "",
+    `- status: ${formatCodeValue(packet.status)}`,
+    `- domain: ${formatCodeValue(packet.domain)}`,
+    `- evidence_role_pattern: ${formatCodeValue(packet.evidenceRolePattern)}`,
+    `- requested_intent: ${formatValue(packet.requestedIntent)}`,
+    `- selected_song: ${formatValue(selectedSong)}`,
+    "",
+    "## Recommendation",
+    "",
+    `- action: ${formatCodeValue(recommendation.action)}`,
+    `- candidate: ${formatCodeValue(candidate.label)}`,
+    `- candidate_action: ${formatCodeValue(formatAction(candidate.action))}`,
+    `- reason: ${formatValue(recommendation.reason)}`,
+    "",
+    "## Objective Receipts",
+    "",
+    `- supported_candidates: ${formatCodeValue(guardrails.supportedClaimCandidateCount ?? supportedCandidates.length)}`,
+    `- rejected_candidates: ${formatCodeValue(guardrails.rejectedCandidateCount ?? rejectedCandidates.length)}`,
+    `- state_restored_after_loop: ${formatCodeValue(guardrails.stateRestoredAfterLoop)}`,
+    `- candidate_actions_are_transient: ${formatCodeValue(request.candidateActionsAreTransient)}`,
+    `- no_permanent_edit_unless_apply_best: ${formatCodeValue(guardrails.noPermanentEditUnlessApplyBest)}`,
+    "",
+    "## Ranking",
+    "",
+    `- metric: ${formatCodeValue(ranking.metric)}`,
+    `- role: ${formatCodeValue(ranking.role)}`,
+    `- lower_is_better: ${formatCodeValue(ranking.lowerIsBetter)}`,
+    `- baseline: ${formatCodeValue(ranking.baselineCandidateRankingMetric)}`,
+    `- best: ${formatCodeValue(ranking.bestCandidateRankingMetric)}`,
+    `- delta: ${formatCodeValue(ranking.rankingMetricDelta)}`,
+    "",
+    "## Boundary",
+    "",
+    formatValue(packet.proofBoundary)
+  ];
+  addOptionalList(lines, "Listening Prompts", packet.listenerPrompts);
+  addOptionalList(lines, "Caveats", packet.caveats);
+  if (rejectedCandidates.length) {
+    lines.push("", "## Rejected Candidates", "");
+    for (const entry of rejectedCandidates) {
+      const rejected = asRecord(entry) ?? {};
+      const failedReceipts = asArray(rejected.failedReceipts).map(formatValue).join(", ") || "not captured";
+      lines.push(`- ${formatCodeValue(rejected.label)}: ${failedReceipts}`);
+    }
+  }
+  return `${lines.join("\n")}
+`;
+}
+function createHumanReviewPacketArtifacts(proofOrPacket, options = {}) {
+  const packet = requireHumanReviewPacket(proofOrPacket);
+  const markdown = formatHumanReviewPacketMarkdown(packet, options);
+  return {
+    packet,
+    json: `${JSON.stringify(packet, null, 2)}
+`,
+    markdown
+  };
+}
+
+// src/reviewPacketCli.ts
+var DEFAULT_JSON_NAME = "human-review-packet.json";
+var DEFAULT_MARKDOWN_NAME = "human-review-packet.md";
+var USAGE = `riddle-proof-review-packet --proof <path|-> [options]
+
+Extract a human_review_packet from a Riddle Proof artifact and write a compact
+JSON/Markdown handoff for listening or follow-up review.
+
+Options:
+  --proof <path|->       Riddle Proof proof.json/profile-result.json, or '-' for stdin.
+  --output <dir>         Output directory. Defaults to the proof file directory.
+  --json <path>          JSON output path. Defaults to <output>/human-review-packet.json.
+  --markdown <path>      Markdown output path. Defaults to <output>/human-review-packet.md.
+  --title <title>        Markdown title. Defaults to "Human Review Packet".
+  --stdout              Also print the Markdown handoff to stdout.
+  --help                Show this help.
+`;
+var readValue = (argv, index, name) => {
+  const value = argv[index + 1];
+  if (!value || value.startsWith("--")) throw new Error(`${name} requires a value.`);
+  return value;
+};
+function parseReviewPacketCliArgs(argv) {
+  const parsed = {
+    help: false,
+    proofPath: null,
+    outputDir: null,
+    jsonPath: null,
+    markdownPath: null,
+    title: null,
+    stdout: false
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--help" || arg === "-h") {
+      parsed.help = true;
+      continue;
+    }
+    if (arg === "--proof") {
+      parsed.proofPath = readValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+    if (arg === "--output" || arg === "--output-dir") {
+      parsed.outputDir = readValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+    if (arg === "--json") {
+      parsed.jsonPath = readValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+    if (arg === "--markdown" || arg === "--md") {
+      parsed.markdownPath = readValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+    if (arg === "--title") {
+      parsed.title = readValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+    if (arg === "--stdout") {
+      parsed.stdout = true;
+      continue;
+    }
+    if (!arg.startsWith("--") && !parsed.proofPath) {
+      parsed.proofPath = arg;
+      continue;
+    }
+    throw new Error(`Unknown argument ${arg}.`);
+  }
+  return parsed;
+}
+var readProofArtifact = (proofPath) => {
+  if (proofPath === "-") return JSON.parse((0, import_node_fs.readFileSync)(0, "utf8"));
+  const absoluteProofPath = import_node_path.default.resolve(proofPath);
+  if (!(0, import_node_fs.existsSync)(absoluteProofPath)) {
+    throw new Error(`Proof artifact not found: ${absoluteProofPath}`);
+  }
+  return JSON.parse((0, import_node_fs.readFileSync)(absoluteProofPath, "utf8"));
+};
+var outputDirFor = (proofPath, outputDir) => {
+  if (outputDir) return import_node_path.default.resolve(outputDir);
+  if (proofPath === "-") return process.cwd();
+  return import_node_path.default.dirname(import_node_path.default.resolve(proofPath));
+};
+function writeReviewPacketFiles({
+  proofPath,
+  outputDir,
+  jsonPath,
+  markdownPath,
+  title
+}) {
+  const proof = readProofArtifact(proofPath);
+  const artifacts = createHumanReviewPacketArtifacts(proof, {
+    title: title ?? void 0
+  });
+  const resolvedOutputDir = outputDirFor(proofPath, outputDir);
+  const resolvedJsonPath = import_node_path.default.resolve(jsonPath ?? import_node_path.default.join(resolvedOutputDir, DEFAULT_JSON_NAME));
+  const resolvedMarkdownPath = import_node_path.default.resolve(markdownPath ?? import_node_path.default.join(resolvedOutputDir, DEFAULT_MARKDOWN_NAME));
+  (0, import_node_fs.mkdirSync)(import_node_path.default.dirname(resolvedJsonPath), { recursive: true });
+  (0, import_node_fs.mkdirSync)(import_node_path.default.dirname(resolvedMarkdownPath), { recursive: true });
+  (0, import_node_fs.writeFileSync)(resolvedJsonPath, artifacts.json);
+  (0, import_node_fs.writeFileSync)(resolvedMarkdownPath, artifacts.markdown);
+  return {
+    ...artifacts,
+    jsonPath: resolvedJsonPath,
+    markdownPath: resolvedMarkdownPath
+  };
+}
+async function main(argv = process.argv.slice(2)) {
+  const args = parseReviewPacketCliArgs(argv);
+  if (args.help) {
+    (0, import_node_fs.writeFileSync)(1, USAGE);
+    return;
+  }
+  if (!args.proofPath) throw new Error("--proof is required.");
+  const result = writeReviewPacketFiles({
+    proofPath: args.proofPath,
+    outputDir: args.outputDir,
+    jsonPath: args.jsonPath,
+    markdownPath: args.markdownPath,
+    title: args.title
+  });
+  if (args.stdout) {
+    (0, import_node_fs.writeFileSync)(1, result.markdown);
+  } else {
+    (0, import_node_fs.writeFileSync)(1, `${JSON.stringify({
+      ok: true,
+      json: result.jsonPath,
+      markdown: result.markdownPath,
+      status: result.packet.status ?? null,
+      recommendation: result.packet.recommendation && typeof result.packet.recommendation === "object" ? result.packet.recommendation.candidate?.label ?? null : null
+    }, null, 2)}
+`);
+  }
+}
+main().catch((error) => {
+  (0, import_node_fs.writeFileSync)(2, `${error instanceof Error ? error.message : String(error)}
+`);
+  process.exitCode = 1;
+});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  main,
+  parseReviewPacketCliArgs,
+  writeReviewPacketFiles
+});

package/dist/reviewPacketCli.d.cts

@@ -0,0 +1,28 @@
+import { H as HumanReviewPacket } from './humanReviewPacket-APSxuvat.cjs';
+
+interface ParsedArgs {
+    help: boolean;
+    proofPath: string | null;
+    outputDir: string | null;
+    jsonPath: string | null;
+    markdownPath: string | null;
+    title: string | null;
+    stdout: boolean;
+}
+declare function parseReviewPacketCliArgs(argv: string[]): ParsedArgs;
+declare function writeReviewPacketFiles({ proofPath, outputDir, jsonPath, markdownPath, title, }: {
+    proofPath: string;
+    outputDir: string | null;
+    jsonPath: string | null;
+    markdownPath: string | null;
+    title: string | null;
+}): {
+    jsonPath: string;
+    markdownPath: string;
+    packet: HumanReviewPacket;
+    json: string;
+    markdown: string;
+};
+declare function main(argv?: string[]): Promise<void>;
+
+export { main, parseReviewPacketCliArgs, writeReviewPacketFiles };

package/dist/reviewPacketCli.d.ts

@@ -0,0 +1,28 @@
+import { H as HumanReviewPacket } from './humanReviewPacket-APSxuvat.js';
+
+interface ParsedArgs {
+    help: boolean;
+    proofPath: string | null;
+    outputDir: string | null;
+    jsonPath: string | null;
+    markdownPath: string | null;
+    title: string | null;
+    stdout: boolean;
+}
+declare function parseReviewPacketCliArgs(argv: string[]): ParsedArgs;
+declare function writeReviewPacketFiles({ proofPath, outputDir, jsonPath, markdownPath, title, }: {
+    proofPath: string;
+    outputDir: string | null;
+    jsonPath: string | null;
+    markdownPath: string | null;
+    title: string | null;
+}): {
+    jsonPath: string;
+    markdownPath: string;
+    packet: HumanReviewPacket;
+    json: string;
+    markdown: string;
+};
+declare function main(argv?: string[]): Promise<void>;
+
+export { main, parseReviewPacketCliArgs, writeReviewPacketFiles };

package/dist/reviewPacketCli.js

@@ -0,0 +1,155 @@
+import {
+  createHumanReviewPacketArtifacts
+} from "./chunk-XQ2N4EYF.js";
+
+// src/reviewPacketCli.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import path from "path";
+var DEFAULT_JSON_NAME = "human-review-packet.json";
+var DEFAULT_MARKDOWN_NAME = "human-review-packet.md";
+var USAGE = `riddle-proof-review-packet --proof <path|-> [options]
+
+Extract a human_review_packet from a Riddle Proof artifact and write a compact
+JSON/Markdown handoff for listening or follow-up review.
+
+Options:
+  --proof <path|->       Riddle Proof proof.json/profile-result.json, or '-' for stdin.
+  --output <dir>         Output directory. Defaults to the proof file directory.
+  --json <path>          JSON output path. Defaults to <output>/human-review-packet.json.
+  --markdown <path>      Markdown output path. Defaults to <output>/human-review-packet.md.
+  --title <title>        Markdown title. Defaults to "Human Review Packet".
+  --stdout              Also print the Markdown handoff to stdout.
+  --help                Show this help.
+`;
+var readValue = (argv, index, name) => {
+  const value = argv[index + 1];
+  if (!value || value.startsWith("--")) throw new Error(`${name} requires a value.`);
+  return value;
+};
+function parseReviewPacketCliArgs(argv) {
+  const parsed = {
+    help: false,
+    proofPath: null,
+    outputDir: null,
+    jsonPath: null,
+    markdownPath: null,
+    title: null,
+    stdout: false
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--help" || arg === "-h") {
+      parsed.help = true;
+      continue;
+    }
+    if (arg === "--proof") {
+      parsed.proofPath = readValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+    if (arg === "--output" || arg === "--output-dir") {
+      parsed.outputDir = readValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+    if (arg === "--json") {
+      parsed.jsonPath = readValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+    if (arg === "--markdown" || arg === "--md") {
+      parsed.markdownPath = readValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+    if (arg === "--title") {
+      parsed.title = readValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+    if (arg === "--stdout") {
+      parsed.stdout = true;
+      continue;
+    }
+    if (!arg.startsWith("--") && !parsed.proofPath) {
+      parsed.proofPath = arg;
+      continue;
+    }
+    throw new Error(`Unknown argument ${arg}.`);
+  }
+  return parsed;
+}
+var readProofArtifact = (proofPath) => {
+  if (proofPath === "-") return JSON.parse(readFileSync(0, "utf8"));
+  const absoluteProofPath = path.resolve(proofPath);
+  if (!existsSync(absoluteProofPath)) {
+    throw new Error(`Proof artifact not found: ${absoluteProofPath}`);
+  }
+  return JSON.parse(readFileSync(absoluteProofPath, "utf8"));
+};
+var outputDirFor = (proofPath, outputDir) => {
+  if (outputDir) return path.resolve(outputDir);
+  if (proofPath === "-") return process.cwd();
+  return path.dirname(path.resolve(proofPath));
+};
+function writeReviewPacketFiles({
+  proofPath,
+  outputDir,
+  jsonPath,
+  markdownPath,
+  title
+}) {
+  const proof = readProofArtifact(proofPath);
+  const artifacts = createHumanReviewPacketArtifacts(proof, {
+    title: title ?? void 0
+  });
+  const resolvedOutputDir = outputDirFor(proofPath, outputDir);
+  const resolvedJsonPath = path.resolve(jsonPath ?? path.join(resolvedOutputDir, DEFAULT_JSON_NAME));
+  const resolvedMarkdownPath = path.resolve(markdownPath ?? path.join(resolvedOutputDir, DEFAULT_MARKDOWN_NAME));
+  mkdirSync(path.dirname(resolvedJsonPath), { recursive: true });
+  mkdirSync(path.dirname(resolvedMarkdownPath), { recursive: true });
+  writeFileSync(resolvedJsonPath, artifacts.json);
+  writeFileSync(resolvedMarkdownPath, artifacts.markdown);
+  return {
+    ...artifacts,
+    jsonPath: resolvedJsonPath,
+    markdownPath: resolvedMarkdownPath
+  };
+}
+async function main(argv = process.argv.slice(2)) {
+  const args = parseReviewPacketCliArgs(argv);
+  if (args.help) {
+    writeFileSync(1, USAGE);
+    return;
+  }
+  if (!args.proofPath) throw new Error("--proof is required.");
+  const result = writeReviewPacketFiles({
+    proofPath: args.proofPath,
+    outputDir: args.outputDir,
+    jsonPath: args.jsonPath,
+    markdownPath: args.markdownPath,
+    title: args.title
+  });
+  if (args.stdout) {
+    writeFileSync(1, result.markdown);
+  } else {
+    writeFileSync(1, `${JSON.stringify({
+      ok: true,
+      json: result.jsonPath,
+      markdown: result.markdownPath,
+      status: result.packet.status ?? null,
+      recommendation: result.packet.recommendation && typeof result.packet.recommendation === "object" ? result.packet.recommendation.candidate?.label ?? null : null
+    }, null, 2)}
+`);
+  }
+}
+main().catch((error) => {
+  writeFileSync(2, `${error instanceof Error ? error.message : String(error)}
+`);
+  process.exitCode = 1;
+});
+export {
+  main,
+  parseReviewPacketCliArgs,
+  writeReviewPacketFiles
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riddledc/riddle-proof-packs",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "Reusable proof pack profiles and metadata helpers for the Riddle proof framework.",
   "license": "MIT",
   "author": "RiddleDC",
@@ -23,9 +23,13 @@
   "files": [
     "dist",
     "packs",
+    "bin",
     "LICENSE",
     "README.md"
   ],
+  "bin": {
+    "riddle-proof-review-packet": "./bin/riddle-proof-review-packet"
+  },
   "sideEffects": false,
   "engines": {
     "node": ">=18"
@@ -39,7 +43,7 @@
     "typescript": "^5.4.5"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts --out-dir dist --clean",
+    "build": "tsup src/index.ts src/reviewPacketCli.ts --format cjs,esm --dts --out-dir dist --clean",
     "clean": "rm -rf dist",
     "lint": "echo 'lint: (not configured)'",
     "test": "npm run build && node test.js"