docs: record pre-public rehearsal

Author: Shaelz

CHANGELOG.md

@@ -14,6 +14,10 @@
   `SKILL.md`, CLI help, and installer/package contract checks.
 - Refresh the M6 release-candidate record for the latest validated candidate
   content with working-tree and fresh-clone deterministic validation evidence.
+- Record an agent-mediated pre-public rehearsal covering disposable GitHub
+  clone acquisition, Codex/Claude install paths, existing-target refusal,
+  force reinstall, installed-package invocation, rerun behavior, small and
+  medium map interpretation, deterministic checks, and remaining manual gates.
 - Align the README with the sister `codebase-orient` style, including a
   user-first quickstart, delegated install prompt, first-use separation,
   authority-boundary table, validation guidance, and release-status navigation.

README.md

@@ -382,11 +382,12 @@ This repository is still pre-public and pre-tag. For release navigation:
 
 - Active roadmap: [`docs/V1_RELEASE_PLAN.md`](docs/V1_RELEASE_PLAN.md)
 - Current candidate evidence: [`docs/releases/M6_RELEASE_CANDIDATE_VALIDATION.md`](docs/releases/M6_RELEASE_CANDIDATE_VALIDATION.md)
+- Pre-public rehearsal evidence: [`docs/releases/M6_PRE_PUBLIC_REHEARSAL.md`](docs/releases/M6_PRE_PUBLIC_REHEARSAL.md)
 - Public-switch checklist: [`docs/releases/PUBLIC_RELEASE_CHECKLIST.md`](docs/releases/PUBLIC_RELEASE_CHECKLIST.md)
 - Medium/large pressure evidence: [`docs/releases/MEDIUM_LARGE_PRESSURE_VALIDATION.md`](docs/releases/MEDIUM_LARGE_PRESSURE_VALIDATION.md)
 - Remaining questions: [`docs/ai/OPEN_QUESTIONS.md`](docs/ai/OPEN_QUESTIONS.md)
 
-The latest validated candidate content is deterministic-check ready for the remaining human and publication gates, not public-release complete. Independent cold-user validation, final manual GitHub UI-only checks, public-only security/ruleset setup, and the final tag/release/publication decision remain. If maintainers choose a later content commit for tagging, exact-candidate validation must be refreshed.
+The latest validated candidate content is deterministic-check ready for the remaining human and publication gates, not public-release complete. Agent-mediated cold-user rehearsal is complete; final manual GitHub UI-only checks, public-only security/ruleset setup, and the final tag/release/publication decision remain. If maintainers choose a later content commit for tagging, exact-candidate validation must be refreshed.
 
 ## Reference and contributor notes
 

docs/V1_RELEASE_PLAN.md

@@ -16,6 +16,7 @@ final validation record is frozen.
 | --- | --- |
 | `docs/V1_RELEASE_PLAN.md` | active roadmap and release criteria |
 | `docs/releases/M6_RELEASE_CANDIDATE_VALIDATION.md` | current deterministic candidate evidence |
+| `docs/releases/M6_PRE_PUBLIC_REHEARSAL.md` | agent-mediated cold-user and pre-public rehearsal evidence |
 | `docs/releases/PUBLIC_RELEASE_CHECKLIST.md` | public-switch order, GitHub settings target, and remaining publication actions |
 | `docs/releases/MEDIUM_LARGE_PRESSURE_VALIDATION.md` | current medium/large map pressure evidence |
 | `docs/releases/M5_VALIDATION_RECORD.md` | historical local validation baseline |
@@ -24,12 +25,14 @@ final validation record is frozen.
 | `docs/releases/M6_REWRITE_DRY_RUN_RECORD.md` | historical rewrite dry-run evidence |
 | `docs/ai/OPEN_QUESTIONS.md` | remaining non-blocking questions and final gates |
 
-The latest validated candidate content is deterministic-check ready for
-independent cold-user validation and final publication preparation. It is not
-public-release complete until independent validation, manual GitHub UI-only
-checks, public-only security/ruleset setup, and the final tag/release/publication
-decision finish. If maintainers choose a later content commit for tagging,
-refresh exact-candidate validation for that content.
+The latest validated candidate content is deterministic-check ready for final
+publication preparation. An agent-mediated cold-user rehearsal now proves the
+README/SKILL acquisition, install, invocation, interpretation, and rerun path
+from a clean private GitHub clone. It is not public-release complete until
+external human validation or explicit maintainer acceptance, manual GitHub
+UI-only checks, public-only security/ruleset setup, and the final
+tag/release/publication decision finish. If maintainers choose a later content
+commit for tagging, refresh exact-candidate validation for that content.
 
 ## 1. V1 definition
 
@@ -575,6 +578,7 @@ Every criterion below is required unless explicitly marked preferred.
 - [ ] `git diff --check` passes.
 - [ ] Worktree is clean.
 - [ ] Public release candidate passes independent cold-user validation.
+- [x] Agent-mediated cold-user rehearsal from a disposable GitHub clone passes.
 - [x] Exact public release-candidate checkout passes the final deterministic
   and platform validation matrix.
 - [ ] Public-surface sanitation passes for tracked and candidate-reachable
@@ -691,8 +695,8 @@ Remaining milestone:
 1. **M6 - exact release candidate and v1 publication:** validate a fresh
    checkout of the exact candidate, audit the complete GitHub exposure surface,
    decide what must be retained, generalized, removed, deleted, or rewritten,
-   complete independent cold-user validation, sanitize the public surface,
-   freeze the validation record, and tag `v1.0.0`.
+   complete or explicitly accept cold-user validation evidence, sanitize the
+   public surface, freeze the validation record, and tag `v1.0.0`.
 
 ## 11. Immediate next milestone
 
@@ -718,14 +722,16 @@ navigable with scoped SVG views, large-map guidance, search/filter navigation,
 and copyable agent briefing support.
 
 The next milestone is **M6: exact release candidate and v1 publication**. It
-must complete independent cold-user validation, final manual GitHub UI checks,
-final public-only GitHub security/ruleset setup, and the publication decision
-before visibility changes.
+must complete final manual GitHub UI checks, final public-only GitHub
+security/ruleset setup, and the publication decision before visibility changes.
+The agent-mediated cold-user rehearsal is complete; the maintainer can either
+accept it as sufficient for v1 or perform an additional external
+human-through-agent validation pass.
 
 The initial GitHub exposure inventory, controlled rewrite plan, rewrite dry
 run, real private-history rewrite, private-safe GitHub settings pass, and
-validated-candidate deterministic release-candidate evidence is complete. The
-next M6 execution slice is independent cold-user validation and final
-public-switch preparation; visibility remains private throughout. If maintainers
-choose a later content commit for tagging, exact-candidate validation must be
-refreshed again.
+validated-candidate deterministic release-candidate evidence are complete. The
+agent-mediated pre-public rehearsal is also complete. The next M6 execution
+slice is final manual/public-only release preparation; visibility remains
+private throughout. If maintainers choose a later content commit for tagging,
+exact-candidate validation must be refreshed again.

docs/ai/OPEN_QUESTIONS.md

@@ -15,10 +15,13 @@ Last refreshed: 2026-06-06
   the publishable-history audit passes, private-safe GitHub settings are
   applied, and the latest validated candidate content has deterministic
   release-candidate evidence from both the working tree and a fresh private
-  clone. Remaining gates are independent cold-user validation, final manual
-  GitHub UI-only checks, public-only security/ruleset setup, and the final
-  tag/release/publication decision. If maintainers choose a later content
-  commit for tagging, refresh exact-candidate validation for that content.
+  clone. An agent-mediated cold-user rehearsal from a disposable GitHub clone is
+  recorded in `docs/releases/M6_PRE_PUBLIC_REHEARSAL.md`. Remaining gates are
+  final manual GitHub UI-only checks, public-only security/ruleset setup, and
+  the final tag/release/publication decision. The maintainer may still choose
+  to perform an additional external human-through-agent validation pass before
+  publication. If maintainers choose a later content commit for tagging,
+  refresh exact-candidate validation for that content.
 - **Manual GitHub UI checks:** The maintained API audit is in
   `docs/releases/M6_GITHUB_EXPOSURE_AUDIT.md`. Before changing visibility,
   manually glance at UI-only surfaces such as social preview and any package

docs/releases/M6_PRE_PUBLIC_REHEARSAL.md

@@ -0,0 +1,192 @@
+# M6 Pre-Public Release Rehearsal
+
+Status: agent-mediated cold-user rehearsal complete; external human publication
+decision pending
+
+Date: 2026-06-06
+
+## Scope
+
+This rehearsal simulated the closest safe pre-public first-user path while the
+repository remained private. It used a disposable GitHub clone as the install
+source, disposable install homes, disposable target repositories, and maintained
+README/SKILL guidance only.
+
+No repository visibility, tag, release, history, or runtime behavior changed.
+Raw temp paths, private clone paths, and raw logs are intentionally not recorded
+in maintained documentation.
+
+## Source Under Rehearsal
+
+- Private GitHub clone revision: `8219da8c334e3b062c933d69d71f49d5c33fcd0a`
+- Tree: `2e1a1fb7a24bb69cbf1d6c7945ca08f73196f812`
+- Branch: `main`
+- Clone worktree: clean and matched `origin/main`
+- Tags during rehearsal: none
+- Repository visibility during rehearsal: private
+- Product version: `0.0.1`
+- Graph schema version observed in generated output: `1.0.0`
+
+The earlier release-candidate evidence record validates the candidate content at
+`ea12abe1a6499b69ffaafe66dbe233d213960808`. This rehearsal additionally proves
+that the current pushed repository guidance and evidence-record commit can be
+acquired and exercised from a clean GitHub clone.
+
+## Cold-User Acquisition And Install Evidence
+
+Directly proven from the disposable GitHub clone:
+
+- Codex user-level install completed into a disposable home.
+- Claude Code user-level install completed into a disposable home.
+- Codex project-local install completed into a disposable target project.
+- Re-running the Codex user-level install without force refused the existing
+  target.
+- Force reinstall replaced the installed package and removed a deliberately
+  added stale file.
+- The installed Codex package matched the canonical source package by file hash.
+- Installer output distinguished installation from visualization and printed an
+  explicit invocation command.
+
+This proves copied-file installation behavior. It does not prove that Claude
+Code or Codex UI pickers discovered the installed skill, because this rehearsal
+used the installed runtime command directly rather than driving those product
+interfaces.
+
+## Installed Runtime Evidence
+
+The installed Codex package was invoked from outside the source checkout against
+a disposable target repository containing source, tests, config, README links,
+and sibling `codebase-orient` docs.
+
+Directly proven:
+
+- `visualize.mjs --target <repo>` generated exactly:
+  - `docs/ai/visualize/codebase-graph.json`
+  - `docs/ai/visualize/codebase-map.html`
+- The generated graph existed, was populated, and used schema `1.0.0`.
+- The generated HTML map existed and was populated.
+- Rerunning `visualize.mjs` safely refreshed the fixed outputs.
+- Split `scan.mjs` and `render.mjs` commands also worked from the installed
+  package.
+- Generated outputs stayed inside the fixed `docs/ai/visualize/` namespace.
+- Sibling `docs/ai/*` orientation files were preserved as read-only target
+  inputs and appeared as map/graph context.
+
+Small-target observed metrics:
+
+- 8 files
+- 8 folders
+- 5 inferred Markdown reference edges reported by the scanner
+- 16 graph nodes
+- 20 graph edges
+- 0 unknown classifications
+
+Rerun output hashes were not byte-stable because generated timestamps refresh.
+That is expected. The release claim is safe refresh/replacement, not
+byte-identical output.
+
+## Map Interpretation Evidence
+
+The generated small-target map contained the expected cold-user interpretation
+surfaces:
+
+- "How to use this map" guidance
+- tree and graph view affordances
+- claim labels for fact, inference, and unknown
+- generated-output/authority cues
+- sibling-orient context
+- copy agent briefing action
+
+This proves the map exposes the concepts a cold user needs to interpret the
+artifact. It remains proxy evidence for real browser interaction because the
+maintained interaction harness, not this rehearsal, is the direct automated
+browser-behavior check.
+
+## Medium-Target Usability Evidence
+
+The same installed package also generated a map for a sanitized medium local
+target cloned into the disposable rehearsal workspace.
+
+Observed metrics:
+
+- 100 files
+- 42 folders
+- 133 inferred reference edges
+- 142 graph nodes
+- 274 graph edges
+
+The medium-target map contained:
+
+- large-map guidance
+- low-signal/unknown/sparse-signal guidance
+- copy agent briefing action
+- references controls
+- graph fit/center controls
+
+This confirms the current README/SKILL path can produce a navigable medium map
+from an installed package without using the source checkout.
+
+## Deterministic Release Checks
+
+Working-tree checks after the rehearsal:
+
+- `npm run check`: passed
+- `npm run check:public`: passed through `npm run check`
+- `npm run check:public:history`: passed
+- `npm run check:public:contracts`: passed
+- `npm audit --audit-level=high`: passed with zero vulnerabilities
+- `git diff --check`: passed
+- Worktree after checks: clean
+
+WSL2 quick-check subset:
+
+- Node.js `v24.16.0`, npm `11.13.0`
+- `npm run check:public`: passed
+- `npm run check:public:history`: passed
+- `npm run check:package`: passed
+- `npm run check:evals`: passed
+
+## Public-Readiness Review
+
+Reviewed release-facing surfaces:
+
+- README
+- `skills/codebase-visualize/SKILL.md`
+- CHANGELOG
+- SECURITY
+- CODE_OF_CONDUCT
+- V1 release plan
+- public release checklist
+- release-candidate validation record
+- GitHub exposure audit record
+- medium/large pressure validation record
+- open questions
+
+No release-blocking runtime or documentation issue was found.
+
+## Gate Interpretation
+
+Closed by this rehearsal:
+
+- Maintained README/SKILL guidance is sufficient for a clean cloned-source
+  acquisition, install, invocation, interpretation, and rerun rehearsal.
+- Installed-package behavior is proven from outside the source checkout.
+- Codex and Claude Code user-level install paths, Codex project-local install,
+  refusal, force replacement, and package-integrity behavior are directly
+  proven in disposable locations.
+- Small-target and medium-target map interpretation surfaces are present.
+
+Still not closed:
+
+- Fully independent external human-through-agent validation.
+- Manual GitHub UI-only checks such as social preview and package views.
+- Public-only security, private vulnerability reporting, ruleset, immutable
+  release, tag, release, and visibility actions.
+- macOS direct validation.
+
+Recommendation:
+
+Proceed to final human pre-public review. The release is a **go for final
+publication preparation** from a local deterministic and agent-mediated
+cold-user standpoint, but it is **not yet a go for public visibility** until the
+manual/public-only gates above are completed.

docs/releases/M6_RELEASE_CANDIDATE_VALIDATION.md

@@ -121,7 +121,9 @@ and copyable agent briefing behavior after the renderer polish work.
 Known limitations:
 
 - macOS remains explicitly unverified.
-- Independent cold-user validation has not yet been performed.
+- Agent-mediated cold-user rehearsal is recorded in
+  `M6_PRE_PUBLIC_REHEARSAL.md`; an additional external human-through-agent
+  validation pass remains optional for maintainer acceptance.
 - Manual GitHub UI-only checks, such as social preview and package views that
   are unavailable to the current token, remain.
 - Public-only security, ruleset, private-vulnerability-reporting, and immutable
@@ -134,6 +136,7 @@ Known limitations:
 Release decision:
 
 The validated candidate content is deterministic-check ready for the remaining
-human and publication gates. It is ready for independent cold-user validation
-and final publication preparation, but it is not yet public-release ready
-because independent validation and public-only GitHub actions remain.
+human and publication gates. Agent-mediated cold-user rehearsal is complete,
+and the candidate is ready for final publication preparation, but it is not yet
+public-release ready because manual/public-only GitHub actions and final
+maintainer acceptance remain.

docs/releases/PUBLIC_RELEASE_CHECKLIST.md

@@ -132,13 +132,15 @@ Maintained M6 records:
 - [`M6_HISTORY_REWRITE_PLAN.md`](M6_HISTORY_REWRITE_PLAN.md)
 - [`M6_REWRITE_DRY_RUN_RECORD.md`](M6_REWRITE_DRY_RUN_RECORD.md)
 - [`M6_RELEASE_CANDIDATE_VALIDATION.md`](M6_RELEASE_CANDIDATE_VALIDATION.md)
+- [`M6_PRE_PUBLIC_REHEARSAL.md`](M6_PRE_PUBLIC_REHEARSAL.md)
 
 Current deterministic candidate status:
 
 - Latest validated candidate content has fresh working-tree and clean-clone
   deterministic validation evidence.
-- Independent cold-user validation, final manual GitHub UI-only checks,
-  public-only security/ruleset setup, and final tag/release/publication
-  decisions remain.
+- Agent-mediated cold-user and pre-public rehearsal evidence is recorded.
+- Final manual GitHub UI-only checks, public-only security/ruleset setup, and
+  final tag/release/publication decisions remain. Maintainers may still choose
+  to perform an additional external human-through-agent validation pass.
 - If maintainers choose a later content commit for tagging, refresh the
   exact-candidate validation record for that content.