feat(cli): align bundle inspect and audit output

EffortlessSteven · EffortlessSteven · commit 94a90e9d3997 · 2026-05-18T05:37:54.000-04:00
diff --git a/.uselesskey/goals/active.toml b/.uselesskey/goals/active.toml
@@ -118,7 +118,7 @@ commands = [
 
 [[work_item]]
 id = "inspect-audit-alignment"
-status = "ready"
+status = "done"
 proposal = "USELESSKEY-PROP-0001"
 spec = "USELESSKEY-SPEC-0014"
 plan = "plans/downstream-ci-polish/implementation-plan.md"
@@ -131,7 +131,7 @@ commands = [
 
 [[work_item]]
 id = "downstream-ci-example"
-status = "planned"
+status = "ready"
 proposal = "USELESSKEY-PROP-0001"
 spec = "USELESSKEY-SPEC-0013"
 plan = "plans/downstream-ci-polish/implementation-plan.md"
diff --git a/crates/uselesskey-cli/src/main.rs b/crates/uselesskey-cli/src/main.rs
@@ -807,6 +807,7 @@ fn render_bundle_inspection_summary(
     format!(
         concat!(
             "Bundle profile: {}\n",
+            "Summary type: quick human bundle summary\n",
             "Purpose: {}\n",
             "Artifacts: {}\n",
             "Verified files: {}\n",
@@ -816,6 +817,7 @@ fn render_bundle_inspection_summary(
             "Runtime material artifacts: {}\n",
             "Verification: ok\n",
             "Receipts: {}\n",
+            "Durable audit receipt: uselesskey audit-bundle --path <bundle-dir> --out <audit-dir>\n",
             "Proof/check path: {}\n",
             "Generated files:\n{}\n",
             "Artifact posture:\n{}\n",
@@ -964,6 +966,11 @@ fn render_bundle_audit_markdown(audit: &BundleAudit) -> String {
     out.push_str(&format!("- Status: {}\n", audit.status));
     out.push_str(&format!("- Bundle: {}\n", audit.bundle_path));
     out.push_str(&format!("- Profile: {}\n", audit.profile));
+    out.push_str("- Receipt type: durable metadata-only reviewer/CI receipt\n");
+    out.push_str("- Quick summary: uselesskey inspect-bundle --path <bundle-dir>\n");
+    out.push_str(
+        "- Payload posture: raw generated fixture payloads are not copied into this receipt\n",
+    );
     out.push_str(&format!(
         "- Manifest: {} (version {})\n",
         audit.manifest_path, audit.manifest_version
diff --git a/crates/uselesskey-cli/tests/cli.rs b/crates/uselesskey-cli/tests/cli.rs
@@ -675,6 +675,9 @@ fn inspect_bundle_summarizes_verified_scanner_safe_receipts() -> TestResult<()>
         .assert()
         .success()
         .stdout(predicate::str::contains("Bundle profile: scanner-safe"))
+        .stdout(predicate::str::contains(
+            "Summary type: quick human bundle summary",
+        ))
         .stdout(predicate::str::contains("Artifacts: 8"))
         .stdout(predicate::str::contains("Verified files: 10"))
         .stdout(predicate::str::contains("Scanner-safe: yes"))
@@ -685,6 +688,9 @@ fn inspect_bundle_summarizes_verified_scanner_safe_receipts() -> TestResult<()>
         .stdout(predicate::str::contains(
             "Receipts: materialization, audit-surface",
         ))
+        .stdout(predicate::str::contains(
+            "Durable audit receipt: uselesskey audit-bundle --path <bundle-dir> --out <audit-dir>",
+        ))
         .stdout(predicate::str::contains(
             "Proof/check path: cargo xtask claim-proof --claim scanner-safe-fixtures",
         ))
@@ -725,11 +731,15 @@ fn inspect_bundle_reports_runtime_material_without_printing_payloads() -> TestRe
     let summary = String::from_utf8(output).test_context("utf-8")?;
 
     assert!(summary.contains("Bundle profile: runtime"));
+    assert!(summary.contains("Summary type: quick human bundle summary"));
     assert!(summary.contains("Scanner-safe: no"));
     assert!(summary.contains("Private key material: yes"));
     assert!(summary.contains("Symmetric secret material: yes"));
     assert!(summary.contains("Runtime material artifacts: 5"));
     assert!(summary.contains("Verification: ok"));
+    assert!(summary.contains(
+        "Durable audit receipt: uselesskey audit-bundle --path <bundle-dir> --out <audit-dir>"
+    ));
     assert!(
         summary.contains(
             "Proof/check path: uselesskey verify-bundle --path target/uselesskey-runtime"
@@ -800,6 +810,9 @@ fn audit_bundle_writes_metadata_only_reviewer_receipts() -> TestResult<()> {
     let audit_md =
         fs::read_to_string(audit_dir.join("bundle-audit.md")).test_context("audit markdown")?;
     assert!(audit_md.contains("Bundle Audit"));
+    assert!(audit_md.contains("durable metadata-only reviewer/CI receipt"));
+    assert!(audit_md.contains("Quick summary: uselesskey inspect-bundle --path <bundle-dir>"));
+    assert!(audit_md.contains("raw generated fixture payloads are not copied"));
     assert!(audit_md.contains("requests/negative-wrong-secret.json"));
     assert!(audit_md.contains("audit-bundle does not prove repo public claims"));
     assert!(audit_md.contains("provider compatibility"));
diff --git a/docs/README.md b/docs/README.md
@@ -98,6 +98,8 @@ Specifications and formal definitions.
 
 - [dependency-economics.md](reference/dependency-economics.md) — Current lane cost receipts
 - [audit-surface.md](reference/audit-surface.md) — Current audit/island receipts
+- [bundle-audit-json.md](reference/bundle-audit-json.md) — Stable installed bundle audit JSON contract
+- [bundle-inspect-vs-audit.md](reference/bundle-inspect-vs-audit.md) — When to use quick bundle inspection versus durable audit receipts
 - [verification-badges.md](reference/verification-badges.md) — Generated README badge endpoint rules and boundaries
 - [requirements-v0.3.md](reference/requirements-v0.3.md) — v0.3 acceptance specification
 - [requirements-v0.4.md](reference/requirements-v0.4.md) — v0.4 RNG boundary refactor specification
diff --git a/docs/reference/bundle-inspect-vs-audit.md b/docs/reference/bundle-inspect-vs-audit.md
@@ -0,0 +1,41 @@
+# Bundle Inspect vs Audit
+
+`inspect-bundle` and `audit-bundle` both read an installed CLI bundle, but they
+serve different jobs.
+
+## `inspect-bundle`
+
+Use `inspect-bundle` when you want a quick terminal summary before debugging or
+reviewing generated files:
+
+```bash
+uselesskey inspect-bundle --path target/uselesskey-webhook
+```
+
+It verifies the manifest, prints the profile, lists generated files, summarizes
+scanner-safe and runtime-material posture, and points to the relevant proof or
+check path. It does not write a durable receipt.
+
+## `audit-bundle`
+
+Use `audit-bundle` when you need a metadata-only reviewer packet or a downstream
+CI gate:
+
+```bash
+uselesskey audit-bundle --path target/uselesskey-webhook --out target/uselesskey-webhook-audit
+uselesskey audit-bundle --path target/uselesskey-webhook --ci
+```
+
+It writes `bundle-audit.json` and `bundle-audit.md` when `--out` is provided.
+Those receipts contain bundle metadata, artifact classifications, stable failure
+classes, checks, and boundaries. They do not copy raw fixture payloads.
+
+## Boundary
+
+`inspect-bundle` is for a human's immediate read. `audit-bundle` is for durable
+reviewer and CI evidence.
+
+Neither command proves repo public claims, release readiness, production
+security, provider compatibility, scanner evasion, or downstream verifier
+correctness. Use repo-local verification commands when you need public-claim or
+release evidence.
