@riddledc/riddle-proof-packs 0.4.2 → 0.4.4

package/README.md

@@ -24,6 +24,14 @@ Reusable starter profile definitions and proof-pack metadata for Riddle Proof.
   - Returns first manifest entry for a matching `pack_id`.
 - `instantiateRiddleProofProfile(name, options)`:
   - Returns a copy of a profile with optional `url`, `route`, and `target` overrides.
+- `findHumanReviewPacket(proofOrPacket)`:
+  - Recursively finds the first `human_review_packet` in a proof artifact or returns `null`.
+- `requireHumanReviewPacket(proofOrPacket)`:
+  - Same extraction behavior, but throws if no packet is present.
+- `formatHumanReviewPacketMarkdown(packet, options)`:
+  - Formats a compact Markdown handoff with recommendation, objective receipts, ranking role, proof boundary, listening prompts, and caveats.
+- `createHumanReviewPacketArtifacts(proofOrPacket, options)`:
+  - Returns `{ packet, json, markdown }` for storing a standalone review packet next to a proof run.
 
 ## Proof claims and evidence roles
 
@@ -90,12 +98,40 @@ Profiles are stored under `packs/<slug>/profile.json` and mirrored into the runt
 - `neon-step-sequencer-mobile-trainer-layout`
 - `neon-step-sequencer-full-mix-health-matrix`
 - `neon-step-sequencer-explore-songs-and-mixes`
+- `neon-step-sequencer-ratchet-loop-mix-level-search`
 
 ## Audio and Neon ratchet packs
 
 The `audio-mix` directory contains reusable audio-proof authoring guidance, a profile template, a metrics schema, a ratchet method, and a human-review rubric.
 
-The `neon-step-sequencer` directory contains the first app-specific ratchet lab under the new architecture. Its profiles declare `current_target` or `interaction_snapshots` evidence-role patterns and explicitly state what they do not prove. The case-study files record the claim, evidence, failure classification, smallest layer changed, and next sharper question for each run.
+The `neon-step-sequencer` directory contains the first app-specific ratchet lab under the new architecture. Its profiles declare `current_target` or `interaction_snapshots` evidence-role patterns and explicitly state what they do not prove. The ratchet-loop profile now expects a compact `humanReviewPacket` for listening handoff: supported/rejected candidates, objective guardrails, state restoration, review-order ranking, and taste caveats. The case-study files record the claim, evidence, failure classification, smallest layer changed, and next sharper question for each run.
+
+### Human-review packet handoff
+
+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.
+
+```ts
+import {
+  createHumanReviewPacketArtifacts,
+  findHumanReviewPacket,
+  formatHumanReviewPacketMarkdown,
+} from "@riddledc/riddle-proof-packs";
+
+const proof = JSON.parse(await fs.promises.readFile("proof.json", "utf8"));
+const packet = findHumanReviewPacket(proof);
+if (!packet) throw new Error("proof did not emit a human review packet");
+
+const markdown = formatHumanReviewPacketMarkdown(packet, {
+  title: "Neon Human Review Packet",
+});
+const artifacts = createHumanReviewPacketArtifacts(proof, {
+  title: "Neon Human Review Packet",
+});
+
+console.log(markdown);
+await fs.promises.writeFile("human-review-packet.json", artifacts.json);
+await fs.promises.writeFile("human-review-packet.md", artifacts.markdown);
+```
 
 ## Usage
 

package/dist/index.cjs

@@ -22,6 +22,9 @@ var index_exports = {};
 __export(index_exports, {
   RIDDLE_PROOF_PACK_MANIFEST: () => RIDDLE_PROOF_PACK_MANIFEST,
   RIDDLE_PROOF_PACK_PROFILES: () => RIDDLE_PROOF_PACK_PROFILES,
+  createHumanReviewPacketArtifacts: () => createHumanReviewPacketArtifacts,
+  findHumanReviewPacket: () => findHumanReviewPacket,
+  formatHumanReviewPacketMarkdown: () => formatHumanReviewPacketMarkdown,
   getPackEnabledRiddleProofPackProfiles: () => getPackEnabledRiddleProofPackProfiles,
   getRiddleProofPackProfile: () => getRiddleProofPackProfile,
   getRiddleProofPackProfileByPackId: () => getRiddleProofPackProfileByPackId,
@@ -29,7 +32,8 @@ __export(index_exports, {
   getRiddleProofProfilesByPackId: () => getRiddleProofProfilesByPackId,
   instantiateRiddleProofProfile: () => instantiateRiddleProofProfile,
   listRiddleProofPackProfiles: () => listRiddleProofPackProfiles,
-  listRiddleProofPacks: () => listRiddleProofPacks
+  listRiddleProofPacks: () => listRiddleProofPacks,
+  requireHumanReviewPacket: () => requireHumanReviewPacket
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -1695,6 +1699,7 @@ var ratchet_loop_mix_level_search_default = {
         path: "__NEON_MIX_PROOF__.runRatchetLoop",
         args: [
           {
+            intent: "turn the chord part down a little",
             strategy: "mix-level-search",
             focusTracks: [
               "bass",
@@ -1729,6 +1734,15 @@ var ratchet_loop_mix_level_search_default = {
           },
           {
             path: "supportedClaimCandidateCount"
+          },
+          {
+            path: "humanReviewPacket.status"
+          },
+          {
+            path: "humanReviewPacket.recommendation.candidate.action.track"
+          },
+          {
+            path: "humanReviewPacket.ranking.role"
           }
         ]
       },
@@ -1738,6 +1752,24 @@ var ratchet_loop_mix_level_search_default = {
         expected_value: true,
         timeout_ms: 1e4
       },
+      {
+        type: "assert_window_value",
+        path: "__neonMixProof.ratchetLoop.humanReviewPacket.kind",
+        expected_value: "human_review_packet",
+        timeout_ms: 1e4
+      },
+      {
+        type: "assert_window_value",
+        path: "__neonMixProof.ratchetLoop.humanReviewPacket.ranking.role",
+        expected_value: "review_order_only",
+        timeout_ms: 1e4
+      },
+      {
+        type: "assert_window_value",
+        path: "__neonMixProof.ratchetLoop.humanReviewPacket.request.candidateActionsAreTransient",
+        expected_value: true,
+        timeout_ms: 1e4
+      },
       {
         type: "screenshot",
         label: "neon-ratchet-loop-mix-level-search",
@@ -1785,6 +1817,7 @@ var ratchet_loop_mix_level_search_default = {
       "claim candidates are captured",
       "each candidate records claim receipts",
       "best supported claim candidate or human-review status is captured",
+      "compact human-review packet is captured",
       "state restoration receipt is captured"
     ],
     does_not_prove: [
@@ -2316,10 +2349,142 @@ 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
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   RIDDLE_PROOF_PACK_MANIFEST,
   RIDDLE_PROOF_PACK_PROFILES,
+  createHumanReviewPacketArtifacts,
+  findHumanReviewPacket,
+  formatHumanReviewPacketMarkdown,
   getPackEnabledRiddleProofPackProfiles,
   getRiddleProofPackProfile,
   getRiddleProofPackProfileByPackId,
@@ -2327,5 +2492,6 @@ function instantiateRiddleProofProfile(profileName, options = {}) {
   getRiddleProofProfilesByPackId,
   instantiateRiddleProofProfile,
   listRiddleProofPackProfiles,
-  listRiddleProofPacks
+  listRiddleProofPacks,
+  requireHumanReviewPacket
 });

package/dist/index.d.cts

@@ -59,4 +59,20 @@ interface RiddleProofPackProfileOverrides {
  */
 declare function instantiateRiddleProofProfile(profileName: string, options?: RiddleProofPackProfileOverrides): RiddleProofProfile;
 
-export { RIDDLE_PROOF_PACK_MANIFEST, RIDDLE_PROOF_PACK_PROFILES, type RiddleProofPackProfileManifest, getPackEnabledRiddleProofPackProfiles, getRiddleProofPackProfile, getRiddleProofPackProfileByPackId, getRiddleProofPackProfileManifest, getRiddleProofProfilesByPackId, instantiateRiddleProofProfile, listRiddleProofPackProfiles, listRiddleProofPacks };
+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 };

package/dist/index.d.ts

@@ -59,4 +59,20 @@ interface RiddleProofPackProfileOverrides {
  */
 declare function instantiateRiddleProofProfile(profileName: string, options?: RiddleProofPackProfileOverrides): RiddleProofProfile;
 
-export { RIDDLE_PROOF_PACK_MANIFEST, RIDDLE_PROOF_PACK_PROFILES, type RiddleProofPackProfileManifest, getPackEnabledRiddleProofPackProfiles, getRiddleProofPackProfile, getRiddleProofPackProfileByPackId, getRiddleProofPackProfileManifest, getRiddleProofProfilesByPackId, instantiateRiddleProofProfile, listRiddleProofPackProfiles, listRiddleProofPacks };
+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 };

package/dist/index.js

@@ -1660,6 +1660,7 @@ var ratchet_loop_mix_level_search_default = {
         path: "__NEON_MIX_PROOF__.runRatchetLoop",
         args: [
           {
+            intent: "turn the chord part down a little",
             strategy: "mix-level-search",
             focusTracks: [
               "bass",
@@ -1694,6 +1695,15 @@ var ratchet_loop_mix_level_search_default = {
           },
           {
             path: "supportedClaimCandidateCount"
+          },
+          {
+            path: "humanReviewPacket.status"
+          },
+          {
+            path: "humanReviewPacket.recommendation.candidate.action.track"
+          },
+          {
+            path: "humanReviewPacket.ranking.role"
           }
         ]
       },
@@ -1703,6 +1713,24 @@ var ratchet_loop_mix_level_search_default = {
         expected_value: true,
         timeout_ms: 1e4
       },
+      {
+        type: "assert_window_value",
+        path: "__neonMixProof.ratchetLoop.humanReviewPacket.kind",
+        expected_value: "human_review_packet",
+        timeout_ms: 1e4
+      },
+      {
+        type: "assert_window_value",
+        path: "__neonMixProof.ratchetLoop.humanReviewPacket.ranking.role",
+        expected_value: "review_order_only",
+        timeout_ms: 1e4
+      },
+      {
+        type: "assert_window_value",
+        path: "__neonMixProof.ratchetLoop.humanReviewPacket.request.candidateActionsAreTransient",
+        expected_value: true,
+        timeout_ms: 1e4
+      },
       {
         type: "screenshot",
         label: "neon-ratchet-loop-mix-level-search",
@@ -1750,6 +1778,7 @@ var ratchet_loop_mix_level_search_default = {
       "claim candidates are captured",
       "each candidate records claim receipts",
       "best supported claim candidate or human-review status is captured",
+      "compact human-review packet is captured",
       "state restoration receipt is captured"
     ],
     does_not_prove: [
@@ -2281,9 +2310,141 @@ 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,
+  createHumanReviewPacketArtifacts,
+  findHumanReviewPacket,
+  formatHumanReviewPacketMarkdown,
   getPackEnabledRiddleProofPackProfiles,
   getRiddleProofPackProfile,
   getRiddleProofPackProfileByPackId,
@@ -2291,5 +2452,6 @@ export {
   getRiddleProofProfilesByPackId,
   instantiateRiddleProofProfile,
   listRiddleProofPackProfiles,
-  listRiddleProofPacks
+  listRiddleProofPacks,
+  requireHumanReviewPacket
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riddledc/riddle-proof-packs",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Reusable proof pack profiles and metadata helpers for the Riddle proof framework.",
   "license": "MIT",
   "author": "RiddleDC",

package/packs/neon-step-sequencer/README.md

@@ -33,7 +33,7 @@ This pack is the first app-specific lab for the open Riddle Proof architecture.
 
 The loop is not mix-specific as a proof concept. The proof concept is a bounded ratchet loop: propose a candidate, apply it, collect evidence, classify the result, restore or keep state, and repeat until the budget is exhausted.
 
-This pack's first concrete strategy is `mix-level-search`, which turns small level edits into change-claim candidates. Each candidate says what action will be attempted, what receipts must support the claim, and what evidence should be reviewed afterward. The loop may include a ranking metric to order review, but the verdict comes from receipts and invariants, not from a universal mix-quality number. It still does not decide subjective mix taste; the output is a listening and review packet.
+This pack's first concrete strategy is `mix-level-search`, which turns small level edits into change-claim candidates. Each candidate says what action will be attempted, what receipts must support the claim, and what evidence should be reviewed afterward. The loop may include a ranking metric to order review, but the verdict comes from receipts and invariants, not from a universal mix-quality number. It still does not decide subjective mix taste; the output is a `humanReviewPacket` for listening handoff.
 
 ## Example evidence
 
@@ -44,6 +44,7 @@ The `examples/` directory contains local Playwright proof results captured again
 - `run-003-full-matrix`: passing `current_target` viewport matrix across desktop, phone, iPad Mini, and iPad with `0 px` horizontal overflow.
 - `run-004-ratchet-loop-mix-level-search`: passing `interaction_snapshots` proof where a bounded loop tested six mix-level change-claim candidates, found a supported `chord -0.10` candidate, recorded receipt-level verdicts, and restored app state without keeping the edit.
 - `run-005-explore-songs-and-mixes-final`: passing `current_target` exploration sweep across four songs and eight song/part entries, with `8` passing entries, `0` prioritized findings, and no clipping after the local app-contract and mix-headroom ratchet.
+- `run-006-ratchet-loop-human-review-packet`: passing `interaction_snapshots` proof where the same bounded loop returned a compact `humanReviewPacket` with the recommended `chord -0.10` candidate, objective guardrails, `review_order_only` ranking, state restoration, and explicit listening caveats.
 
 ## Naming note
 

package/packs/neon-step-sequencer/case-study/findings.md

@@ -112,6 +112,17 @@ Pack summary guidance first; Riddle Proof core only if a general display primiti
 - rerun: passed on May 24, 2026 with `8` entries, `8` passed, and `0` findings.
 - next sharper question: can this exploration workflow become the normal local pack/profile loop before any changeset or npm release?
 
+### Run 006 made the listening handoff compact
+
+- run: `run-006-ratchet-loop-human-review-packet`
+- claim: a bounded ratchet loop can return a compact human-review packet that summarizes supported candidates, objective guardrails, state restoration, ranking-as-review-order, and listening caveats.
+- observed evidence: loop status was `claim_candidate_supported`; the packet kind was `human_review_packet`; packet status was `candidate_ready_for_listening_review`; the recommended candidate was `chord -0.10`; supported candidate count was `6`; rejected candidate count was `0`; ranking role was `review_order_only`; app state was restored after the loop; permanent edit was not kept.
+- classification: none; passing `interaction_snapshots` proof with subjective listening caveat.
+- smallest layer changed: app proof contract and proof-pack profile assertions.
+- change made: added `humanReviewPacket` to the Neon ratchet-loop result and updated the pack profile to assert the packet shape.
+- rerun: passed on May 24, 2026 with local Playwright.
+- next sharper question: can the packet become the standard output shape for one-off and background candidate operators across more than `mix-level-search`?
+
 ### Local runner shutdown needs a small ergonomics follow-up
 
 - run: `run-002-mix-change`, `run-003-full-matrix`, `run-004-ratchet-loop-mix-level-search`

package/packs/neon-step-sequencer/case-study/ratchet-card.md

@@ -35,7 +35,8 @@ The project shows that a complex audio app can improve proof confidence mostly b
 - Run 003: a `current_target` matrix passed across desktop, phone, iPad Mini, and iPad with `0 px` horizontal overflow.
 - Run 004: a bounded loop tested six `mix-level-search` change-claim candidates, returned `chord -0.10` as a supported review candidate with receipt-level evidence, and restored app state.
 - Run 005: a `current_target` exploration sweep sampled four songs and eight song/part entries. The first real sweep exposed app-contract normalization gaps and hot built-in song presets; after the local ratchet fixes it passed with `8` entries, `0` findings, and no clipping.
+- Run 006: the bounded loop returned a compact `humanReviewPacket` with the supported `chord -0.10` candidate, objective guardrails, state restoration, review-order ranking, and listening caveats.
 
 ## Honest boundary
 
-These runs prove objective claims about a running app target. They do not prove that the mix is tasteful, that every song section is healthy, or that a release candidate is better than production. Run 005 is still bounded to configured song/part limits. The ratchet loop is a generic proof-loop shape; `mix-level-search` is only the first Neon strategy plugged into it.
+These runs prove objective claims about a running app target. They do not prove that the mix is tasteful, that every song section is healthy, or that a release candidate is better than production. Run 005 is still bounded to configured song/part limits. Run 006 makes the human handoff explicit: the packet is a compact review object, not an automated taste verdict. The ratchet loop is a generic proof-loop shape; `mix-level-search` is only the first Neon strategy plugged into it.

package/packs/neon-step-sequencer/case-study/ratchet-log.md

@@ -282,6 +282,61 @@ Next sharper question:
 
 Can the same exploration shape become a reusable pack/profile workflow where a user can choose a bounded target set, run locally during iteration, and publish only after the evidence is worth sharing?
 
+## Run 006 - Human-review packet handoff
+
+Claim:
+
+Neon can turn the bounded `mix-level-search` loop into a compact handoff object that a human or follow-on agent can review without reading the full proof JSON.
+
+Profile:
+
+`profiles/ratchet-loop-mix-level-search.json`
+
+Evidence to capture:
+
+- loop status and supported candidate count
+- recommended candidate action
+- per-candidate objective guardrail summary
+- state restoration receipt
+- ranking role as review order only
+- listening-review caveats
+
+Possible outcomes:
+
+- `claim_candidate_supported`: at least one candidate has the receipts needed to support its change claim and the packet can recommend it for listening review.
+- `needs_human_review`: evidence is valid but no candidate satisfies every objective receipt.
+- `proof_insufficient`: the app contract does not expose a packet or enough candidate receipts.
+- `profile_calibration`: the packet exists but points to the wrong window, target, or candidate set.
+
+Observed status:
+
+Passed on May 24, 2026 with `local-playwright`.
+
+Observed evidence:
+
+- loop status `claim_candidate_supported`
+- packet kind `human_review_packet`
+- packet status `candidate_ready_for_listening_review`
+- recommended candidate `chord -0.10`
+- recommended action `set_mixer_level chord 0.38 -> 0.28`
+- supported candidates `6`
+- rejected candidates `0`
+- ranking role `review_order_only`
+- state restored after loop `true`
+- permanent edit kept `false`
+
+Failure classification:
+
+None. This was a passing `interaction_snapshots` proof with an explicit listening-review caveat.
+
+Smallest layer changed:
+
+App proof contract and proof-pack profile. Riddle Proof core did not need a change.
+
+Next sharper question:
+
+Can one-off commands and background runs use this packet as their common output surface while strategy-specific code remains behind the app contract?
+
 ## Project note
 
 The ratchet is not a pass. The ratchet is the next sharper question.

package/packs/neon-step-sequencer/case-study/reusable-lessons.md

@@ -22,6 +22,10 @@ Large metrics belong in artifacts. The summary should answer:
 - did the intended metric move?
 - what should a human review next?
 
+## Handoff packets beat raw JSON spelunking
+
+The full proof result should remain auditable, but one-off and background loops need a compact handoff object. A good `humanReviewPacket` lists supported and rejected candidates, objective guardrails, restoration status, review-order ranking, and caveats that separate proof from taste.
+
 ## Core changes are last
 
 Most ratchet steps should change profile JSON, pack docs, app proof contracts, or app fixtures. Riddle Proof core changes are justified only when the missing primitive applies beyond Neon.