@riddledc/riddle-proof-packs 0.4.4 → 0.4.6

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-SAE6HFAG.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.6",
   "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"

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

@@ -28,6 +28,7 @@ This pack is the first app-specific lab for the open Riddle Proof architecture.
 - `profiles/full-mix-health-matrix.json`: current-target matrix across desktop, phone, iPad Mini, and iPad.
 - `profiles/explore-songs-and-mixes.json`: exploration sweep for proof-window health.
 - `profiles/ratchet-loop-mix-level-search.json`: bounded ratchet loop using the Neon `mix-level-search` strategy.
+- `profiles/ratchet-loop-approved-candidate.json`: bounded ratchet loop that uses an explicit operator-approval surrogate, applies the supported candidate, and keeps the listening-review caveat visible.
 
 ## Ratchet loop strategy
 
@@ -35,6 +36,8 @@ The loop is not mix-specific as a proof concept. The proof concept is a bounded
 
 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.
 
+The approved-candidate profile is the next handoff pattern after review-packet generation. It only applies a candidate when the app contract reports that the candidate's objective receipts passed, and the packet records `approvedCandidateApplied` plus the approval mode. The approval mode can keep development moving, but it is still an operator surrogate; it does not prove listener preference.
+
 ## Example evidence
 
 The `examples/` directory contains local Playwright proof results captured against LilArcade Neon Step Sequencer on May 24, 2026:

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

@@ -123,6 +123,17 @@ Pack summary guidance first; Riddle Proof core only if a general display primiti
 - 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`?
 
+### Run 007 made applying a candidate explicit and auditable
+
+- run: `run-007-approved-candidate-applied`
+- claim: a bounded ratchet loop can apply a supported candidate only after an explicit approval mode, then record that final apply step without claiming subjective mix quality.
+- observed evidence: loop status was `claim_candidate_supported`; packet status was `candidate_applied_for_listening_review`; approval mode was `mixing_canon_surrogate`; recommended candidate was `chord -0.10`; applied-candidate receipt passed with observed level `0.28`; supported candidate count was `6`; rejected candidate count was `0`; state was restored before the final apply; ranking role stayed `review_order_only`.
+- classification: none; passing `interaction_snapshots` proof with subjective listening caveat.
+- smallest layer changed: app proof contract and proof-pack profile assertions.
+- change made: made `applyBest` require a supported claim candidate, added an applied-candidate receipt, surfaced approval metadata in the human-review packet, and added an approved-candidate profile.
+- rerun: passed on May 24, 2026 with local Playwright.
+- next sharper question: can follow-on agents use the applied-candidate packet to prepare a code/config patch only when the operator explicitly asks for a durable edit?
+
 ### 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

@@ -36,7 +36,8 @@ The project shows that a complex audio app can improve proof confidence mostly b
 - 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.
+- Run 007: the approved-candidate profile used a `mixing_canon_surrogate` approval mode, restored loop state, applied the supported `chord -0.10` candidate, and recorded an applied-candidate receipt for listening review.
 
 ## 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. 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.
+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. Runs 006 and 007 make the human handoff explicit: the packet is a compact review object, and the approval mode is a visible operator/surrogate choice, 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

@@ -337,6 +337,61 @@ 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?
 
+## Run 007 - Approved candidate applied
+
+Claim:
+
+Neon can use an explicit approval mode to apply a supported change-claim candidate for listening review while keeping objective proof receipts and subjective taste separate.
+
+Profile:
+
+`profiles/ratchet-loop-approved-candidate.json`
+
+Evidence to capture:
+
+- supported claim candidate
+- explicit approval mode
+- state restoration before the final apply
+- applied-candidate receipt
+- compact human-review packet
+- listening-review caveat
+
+Possible outcomes:
+
+- `candidate_applied_for_listening_review`: a supported candidate was applied after explicit approval and the final app state reflects the candidate.
+- `candidate_ready_for_listening_review`: a supported candidate exists, but the profile did not request final application.
+- `needs_human_review`: no candidate satisfied every objective receipt.
+- `product_regression`: the selected candidate could not be applied or the final mixer state did not reflect it.
+
+Observed status:
+
+Passed on May 24, 2026 with `local-playwright`.
+
+Observed evidence:
+
+- loop status `claim_candidate_supported`
+- packet status `candidate_applied_for_listening_review`
+- approval mode `mixing_canon_surrogate`
+- recommended candidate `chord -0.10`
+- final applied level `0.28`
+- applied-candidate receipt `ok`
+- supported candidates `6`
+- rejected candidates `0`
+- state restored before apply `true`
+- ranking role `review_order_only`
+
+Failure classification:
+
+None. This was a passing `interaction_snapshots` proof. The approval mode is intentionally labeled as a surrogate so the packet does not imply a real listener has judged the mix.
+
+Smallest layer changed:
+
+App proof contract and proof-pack profile. Riddle Proof core did not need a change.
+
+Next sharper question:
+
+Can the reusable pack expose this approved-candidate shape without making approval automatic, and can follow-on agents use the packet to prepare a code/config patch only when the operator explicitly asks for one?
+
 ## Project note
 
 The ratchet is not a pass. The ratchet is the next sharper question.

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

@@ -2,7 +2,7 @@
 
 These examples are local Playwright runner outputs captured against LilArcade Neon Step Sequencer on May 24, 2026. They are included to show how this pack records atomic proof claims with explicit evidence-role patterns.
 
-The raw `profile-result.json` files are real runner outputs. They intentionally keep enough evidence to audit the verdict, but the summaries are the preferred place to start. Run 006 also includes standalone `human-review-packet.json` and `human-review-packet.md` files generated from the proof artifact.
+The raw `profile-result.json` files are real runner outputs. They intentionally keep enough evidence to audit the verdict, but the summaries are the preferred place to start. Runs 006 and 007 also include standalone `human-review-packet.json` and `human-review-packet.md` files generated from the proof artifact.
 
 ## Runs
 
@@ -14,6 +14,7 @@ The raw `profile-result.json` files are real runner outputs. They intentionally
 | `run-004-ratchet-loop-mix-level-search` | `interaction_snapshots` | passed | A bounded ratchet loop tests mix-level change-claim candidates, records receipt verdicts, chooses a supported candidate for review, and restores app state. |
 | `run-005-explore-songs-and-mixes-final` | `current_target` | passed | A bounded exploration sweep samples four songs and eight song/part entries, producing a zero-finding confidence map after app-contract and mix-headroom fixes. |
 | `run-006-ratchet-loop-human-review-packet` | `interaction_snapshots` | passed | A bounded ratchet loop returns a compact `humanReviewPacket` for handoff: supported candidates, objective guardrails, state restoration, review-order ranking, and listening caveats. |
+| `run-007-approved-candidate-applied` | `interaction_snapshots` | passed | A bounded ratchet loop uses an explicit operator-approval surrogate, applies the supported `chord -0.10` candidate, and keeps the listening-review caveat in the packet. |
 
 ## What these examples do not prove
 
@@ -24,3 +25,4 @@ The raw `profile-result.json` files are real runner outputs. They intentionally
 - The ratchet-loop run does not prove that the loop primitive is mix-specific; `mix-level-search` is only this pack's first concrete strategy.
 - The ratchet-loop run does not prove that the supported candidate should be kept. Its ranking metric is a review-order hint, not a taste verdict.
 - The human-review packet does not replace listening judgment. It compresses objective receipts and caveats so a person or follow-on agent can decide what to review next.
+- The approved-candidate run does not prove that the surrogate approval is a real listener preference; it proves that the apply step was explicit, guarded by supported receipts, and recorded for review.

package/packs/neon-step-sequencer/examples/run-006-ratchet-loop-human-review-packet/human-review-packet.md

@@ -20,6 +20,9 @@
 - state_restored_after_loop: `true`
 - candidate_actions_are_transient: `true`
 - no_permanent_edit_unless_apply_best: `true`
+- approved_candidate_applied: `not captured`
+- approval_mode: `not captured`
+- approval_basis: not captured
 
 ## Ranking
 

package/packs/neon-step-sequencer/examples/run-007-approved-candidate-applied/artifact-manifest.json

@@ -0,0 +1,32 @@
+{
+  "version": "riddle-proof-local-runner-manifest.v1",
+  "runner": "local-playwright",
+  "profile_name": "lilarcade-neon-ratchet-loop-approved-candidate",
+  "captured_at": "2026-05-24T13:41:23.987Z",
+  "artifacts": [
+    {
+      "name": "proof.json",
+      "path": "proof.json",
+      "kind": "text",
+      "bytes": 506212
+    },
+    {
+      "name": "console.json",
+      "path": "console.json",
+      "kind": "text",
+      "bytes": 38
+    },
+    {
+      "name": "dom-summary.json",
+      "path": "dom-summary.json",
+      "kind": "text",
+      "bytes": 815
+    },
+    {
+      "name": "profile-result.json",
+      "path": "profile-result.json",
+      "kind": "text",
+      "bytes": 506212
+    }
+  ]
+}

package/packs/neon-step-sequencer/examples/run-007-approved-candidate-applied/console.json

@@ -0,0 +1,4 @@
+{
+  "events": [],
+  "fatal_count": 0
+}

package/packs/neon-step-sequencer/examples/run-007-approved-candidate-applied/dom-summary.json

@@ -0,0 +1,40 @@
+{
+  "expected_viewport_count": 1,
+  "viewport_count": 1,
+  "partial": false,
+  "routes": [
+    {
+      "requested": "http://127.0.0.1:5177/games/drum-sequencer?song=monkberry-moon-delight-tab&mix=profile&view=trainer&instrument=bass",
+      "observed": "/games/drum-sequencer",
+      "expected_path": "/games/drum-sequencer",
+      "matched": true,
+      "http_status": 200
+    }
+  ],
+  "titles": [
+    "LilArcade"
+  ],
+  "overflow_px": [
+    0
+  ],
+  "bounds_overflow_px": [
+    0
+  ],
+  "overflow_offender_counts": [
+    0
+  ],
+  "frames": [
+    {
+      "viewport": "desktop",
+      "selectors": []
+    }
+  ],
+  "http_status": [],
+  "link_status": [],
+  "route_inventory": [],
+  "network_mock_count": 0,
+  "network_mock_hit_count": 0,
+  "dialog_count": 0,
+  "dialog_accept_count": 0,
+  "dialog_dismiss_count": 0
+}