slashdevcorpse · slashdevcorpse · May 31, 2026 · May 31, 2026 · May 31, 2026
diff --git a/README.md b/README.md
@@ -210,11 +210,11 @@ The browser talks to local server routes in <code>apps/codex-claw</code>. Those
 
 CodexClaw can move from alpha toward beta when these workflows are reliable:
 
-- Progressive Codex CLI streaming
-- Image attachment pass-through to Codex CLI
-- npm alpha publish through <code>npx codex-claw@alpha</code>
-- release checklist for package contents, smoke tests, and docs
-- CI coverage for app build, tests, lint, and package dry run
+- completed beta backlog features are merged and mapped in [docs/BETA_WORKFLOW.md](docs/BETA_WORKFLOW.md)
+- npm alpha publish works through <code>npx codex-claw@alpha</code>
+- package dry run, packed smoke test, npm smoke test, app lint, app tests, and app build all pass
+- release package tarball and SHA256 checksums are attached to a GitHub release
+- redacted session bundle evidence is captured before public release notes are posted
 
 ## Project Layout
 

diff --git a/docs/BETA_WORKFLOW.md b/docs/BETA_WORKFLOW.md
@@ -0,0 +1,73 @@
+# CodexClaw Beta Workflow
+
+CodexClaw is still public alpha software. This workflow defines what has landed from the research-backed beta backlog and what must pass before the project should be called beta.
+
+## Completed Backlog Map
+
+| Issue | PR | Area | Status |
+| --- | --- | --- | --- |
+| #84 | #97 | Workspace switcher and Codex CLI health dashboard | Merged |
+| #85 | #98 | Repository context explorer and AGENTS.md visibility | Merged |
+| #86 | #99 | Git diff review and commit preparation panel | Merged |
+| #87 | #100 | Sandbox and approval profile controls | Merged |
+| #88 | #101 | MCP server and tool health manager | Merged |
+| #89 | #102 | Background task queue with cancel, retry, and status history | Merged |
+| #90 | #103 | Session search, tags, archive, and saved filters | Merged |
+| #91 | #104 | Artifacts panel for files, patches, logs, and exports | Merged |
+| #92 | #105 | URL and document context attachments | Merged |
+| #93 | #106 | Run timeline, token/context telemetry, and JSON event export | Merged |
+| #94 | #107 | npm alpha install, update, and doctor readiness | Merged |
+| #95 | #108 | Redacted session bundles and issue/PR handoff drafts | Merged |
+
+## Beta Entry Gates
+
+CodexClaw can move from alpha to beta only when all gates below are true:
+
+| Gate | Required evidence |
+| --- | --- |
+| Local app health | <code>pnpm -C apps/codex-claw lint</code>, <code>pnpm -C apps/codex-claw test</code>, and <code>pnpm -C apps/codex-claw build</code> pass on the release branch |
+| Package readiness | <code>pnpm pack:codex-claw</code> and <code>pnpm smoke:codex-claw:pack</code> pass |
+| npm alpha availability | <code>pnpm smoke:codex-claw:npm</code> passes after <code>codex-claw@alpha</code> is published |
+| Security posture | GitHub dependency alerts are triaged, CodeQL passes, GitGuardian passes, and no critical open public security issue remains |
+| User handoff safety | Redacted session bundle, issue draft, and PR draft exports are available without automatic GitHub posting |
+| Documentation | README, package README, roadmap, release notes, install commands, update commands, and troubleshooting are current |
+| Release package | GitHub release workflow produces a tarball and SHA256 checksums |
+
+## Beta Release Flow
+
+1. Start from a clean <code>main</code> branch.
+2. Confirm dependency alerts and open TODO issues are triaged.
+3. Run local validation:
+
+~~~bash
+pnpm -C apps/codex-claw lint
+pnpm -C apps/codex-claw test
+pnpm -C apps/codex-claw build
+pnpm pack:codex-claw
+pnpm smoke:codex-claw:pack
+~~~
+
+4. Publish the alpha package only after npm auth is confirmed:
+
+~~~bash
+npm whoami
+pnpm release:codex-claw
+pnpm smoke:codex-claw:npm
+~~~
+
+5. Create a GitHub release package and attach the generated tarball plus checksum.
+6. Dogfood a fresh <code>npx codex-claw@alpha</code> install on Windows and one Unix-like environment.
+7. Use the redacted session bundle export to capture release evidence before public posting.
+8. Move to a beta tag only after the alpha package is installable and the release evidence is attached.
+
+## Public Write Policy
+
+CodexClaw can generate GitHub issue and PR description drafts, but it must not post them automatically. A user must review and approve every public write.
+
+## Deferred Past Beta Entry
+
+- Hosted multi-user sessions
+- Remote Codex execution
+- Production auth and billing
+- Browser-based secret entry
+- Stable <code>latest</code> npm tag
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
@@ -1,4 +1,4 @@
-# CodexClaw Alpha Roadmap
+# CodexClaw Alpha To Beta Roadmap
 
 CodexClaw is a public alpha. This roadmap tracks the work needed to move from a local proof of concept to a dependable Codex CLI web surface.
 
@@ -8,28 +8,28 @@ CodexClaw is a public alpha. This roadmap tracks the work needed to move from a
 - Server routes call `codex exec --json` through the local adapter.
 - Sessions and history persist in `.codex-claw/sessions.json` by default.
 - CLI bootstrap can clone the template, write Codex CLI defaults, and run doctor checks.
+- Workspace switching, Codex CLI health checks, repository context, AGENTS.md visibility, git review, approval profiles, MCP health, task queue, artifacts, attachments, timeline exports, package doctor checks, and redacted handoff exports have all landed from the beta backlog.
+
+## Beta Workflow
+
+See [BETA_WORKFLOW.md](BETA_WORKFLOW.md) for the public beta entry gates, validation commands, release flow, and completed issue/PR map.
 
 ## Next Milestones
 
-1. Streaming parity
-   - Parse more Codex JSONL event types.
-   - Show assistant progress before the final completed message.
-   - Add regression coverage for event ordering and duplicate events.
-
-2. Attachment support
-   - Pass image attachments through Codex CLI `--image`.
-   - Reject unsupported attachment types with clear UI feedback.
-   - Document attachment limits.
-
-3. npm alpha publish
-   - Reserve the `codex-claw` package name.
-   - Publish `0.1.0-alpha.0` after a clean install smoke test.
-   - Update install docs from local package execution to `npx codex-claw@alpha`.
-
-4. CI and release hygiene
-   - Add build, test, and lint checks on pull requests.
-   - Track dependency update PRs separately from feature work.
-   - Add a release checklist before beta.
+1. npm alpha publish
+   - Confirm npm auth with <code>npm whoami</code>.
+   - Publish <code>0.1.0-alpha.0</code> with the alpha dist-tag.
+   - Run <code>pnpm smoke:codex-claw:npm</code> after publish.
+
+2. Beta release evidence
+   - Attach release package tarball and SHA256 checksums.
+   - Capture a redacted session bundle from the release validation run.
+   - Dogfood <code>npx codex-claw@alpha</code> on Windows and one Unix-like environment.
+
+3. Beta tag decision
+   - Confirm all beta gates in <code>docs/BETA_WORKFLOW.md</code>.
+   - Keep <code>latest</code> unpublished until the alpha package is repeatably installable.
+   - Open follow-up issues for post-beta hosted, auth, and remote-execution work.
 
 ## Not In Scope Yet