> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase12-session02-release-closeout-and-rollout-readiness/spec.md). # Session Specification **Session ID**: `phase12-session02-release-closeout-and-rollout-readiness` **Phase**: 12 - Codex Packaging and Release Readiness **Status**: Complete **Created**: 2026-05-31 **Package**: Cross-cutting **Package Stack**: Node 20+ npm workspaces, JavaScript CLI/hooks, TypeScript protocol/server/web, stable docs, Vitest, Playwright, Biome, release gates *** ## 1. Session Overview This session closes Phase 12 by turning the completed Codex integration and plugin packaging decision into release-ready evidence. Session 01 explicitly deferred Codex plugin packaging for this release because direct user-level Codex hooks are validated, simpler, and sufficient. Session 02 now records the final quality, privacy, security, documentation, uninstall, release-note, known-limitation, and rollout evidence needed to release first-class local Codex CLI hook support without ambiguous plugin or hosted claims. The session is cross-cutting because the release claim spans the CLI installer, hook maps, server ingest, web display and replay surfaces, protocol vocabulary, docs, release guide, and security posture. It should prefer evidence and documentation over new feature work. If a gate exposes a release-blocking regression, fixes must stay narrowly scoped to the owning package and the evidence must record the failure and remediation. The outcome should be a clear release handoff: direct Codex hooks are supported through `factionos init --cli codex` and `/hooks` review; plugin packaging, trust bypass, project-local trusted `.codex` setup, hosted telemetry, production-hosted validation, remote execution, and broad trusted erasure remain not claimed. *** ## 2. Objectives 1. Record final release-readiness gate outcomes for first-class local Codex CLI hook support. 2. Complete privacy, security, docs, uninstall, and rollout reviews with source-backed no-overclaim wording. 3. Prepare release notes or changelog-ready entries that describe Claude Code plus Codex CLI support and known limitations. 4. Produce a validation-ready handoff that keeps plugin packaging deferred and makes all remaining limitations explicit. *** ## 3. Prerequisites ### Required Sessions * [x] `phase12-session01-codex-plugin-packaging` - provides the explicit plugin deferral decision and direct-hook release path. * [x] `phase11-session03-end-to-end-validation-and-integration-fixes` - provides end-to-end Codex install, fixture replay, browser, privacy, and quality evidence. * [x] `phase11-session02-test-fixture-hardening` - provides source-backed Codex fixtures and redaction coverage. * [x] `phase10-session02-codex-hook-install-uninstall-and-diagnostics` - provides Codex installer, diagnostics, and uninstall support. ### Required Tools/Knowledge * npm workspace commands from `.spec_system/CONVENTIONS.md` and `docs/development.md`. * Release gates from `docs/release.md`. * Current Codex support boundaries from `README.md`, `apps/cli/README_cli.md`, `apps/hooks/README_hooks.md`, `docs/api/README_api.md`, and `docs/api/event-api-hook-contracts.md`. * Privacy, security, hosted, deployment, and environment no-claim boundaries from `docs/privacy-and-security.md`, `docs/deployment.md`, and `docs/environments.md`. * Session 01 plugin decision record and validation plan. ### Environment Requirements * Node 20+ and installed npm workspace dependencies. * No live hosted validation claims unless safe public HTTPS targets and credentials are available and sanitized smoke passes. * Isolated `FACTIONOS_HOME`, `CODEX_HOME`, and user hook config state for any install or uninstall reruns. * No raw prompts, patch bodies, command output, terminal output, transcript paths, MCP argument bodies, tokens, credentials, or broad local paths in tracked evidence. * New or changed files must be ASCII-only with Unix LF line endings. *** ## 4. Scope ### In Scope (MVP) * Maintainers can see final gate outcomes for release readiness - record lint, typecheck, focused tests, available CI-equivalent checks, build or media gates where run, and any source-backed exceptions. * Operators can audit Codex privacy and security posture - review install, hooks, server, web, replay, export, logs, diagnostics, backups, uninstall, and no-claim boundaries. * Users can understand the release - prepare release notes or changelog-ready entries for Claude Code plus Codex CLI support, plugin deferral, `/hooks` review, and known limitations. * Maintainers can verify rollout and cleanup posture - record direct install, status, doctor, uninstall, rollback, and documentation handoff checks using isolated state or prior evidence. * Documentation stays synchronized with shipped behavior - update stable docs only where release wording or evidence requires it. ### Out of Scope (Deferred) * New feature implementation beyond release-blocking fixes - *Reason: this is release closeout, not new product scope.* * Shipping a Codex plugin package - *Reason: Session 01 explicitly deferred plugin packaging.* * Plugin install, plugin cache refresh, plugin trust review, or plugin uninstall claims - *Reason: no plugin package exists in this release.* * Bypassing Codex `/hooks` review or creating project-local trusted `.codex` setup - *Reason: trust decisions stay user-owned and Codex-owned.* * Hosted auth, hosted storage, analytics capture, push, tunnel, public replay hosting, or remote execution - *Reason: these remain disabled, unavailable, deferred, or no-claim.* * Full trusted unified erasure - *Reason: uninstall and local cleanup are narrower operational actions, not broad erasure proof.* * Production-hosted release claims without safe live hosted smoke - *Reason: local and no-network evidence do not prove deployed hosted readiness.* *** ## 5. Technical Approach ### Architecture Use an evidence-first closeout flow. Start by creating release evidence artifacts, then run focused Codex checks and available repository gates. Record each gate with `pass`, `fail`, `blocked`, `unavailable`, `no-claim`, or `prior evidence`. Any release-blocking fix must be scoped to the owner package closest to the failing boundary, followed by the smallest validating rerun and a note in the evidence record. Privacy and security review should be boundary-specific. The session must review what each surface exposes or stores rather than relying on one broad secret scan. Documentation updates should come after evidence is known, so release notes and stable docs do not claim plugin support, hosted behavior, production-hosted validation, remote execution, or trusted erasure that the evidence does not prove. ### Design Patterns * Evidence matrix: track each release gate, owner, status, command, and exception in one artifact. * No-overclaim review: make unsupported claims explicit and searchable. * Boundary-specific privacy review: check install, hook, server, web, replay, export, logs, diagnostics, and uninstall separately. * Prior-evidence reuse: cite Phase 11 and Session 01 evidence where rerunning live trust or plugin validation is not applicable. * Narrow remediation: fix only release-blocking regressions and record exact validation after the fix. ### Technology Stack * Node 20+ npm workspaces. * CLI and hooks: JavaScript under `apps/cli` and `apps/hooks`. * Protocol/server/web: TypeScript under `packages/protocol`, `apps/server`, and `apps/web`. * Stable docs: root `README.md`, `docs/`, and package README files. * Release gates: Biome, TypeScript, Vitest, Playwright where required, media gates, hosted smoke no-network mode, secret scan, and `git diff --check`. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------- | | `.spec_system/specs/phase12-session02-release-closeout-and-rollout-readiness/release-readiness-evidence.md` | Final gate matrix, command outcomes, focused checks, prior-evidence citations, exceptions, and remediation notes. | \~220 | | `.spec_system/specs/phase12-session02-release-closeout-and-rollout-readiness/privacy-security-release-review.md` | Boundary-specific privacy, security, uninstall, diagnostics, and no-claim review. | \~180 | | `.spec_system/specs/phase12-session02-release-closeout-and-rollout-readiness/docs-release-review.md` | Stable docs review matrix and required documentation sync notes. | \~140 | | `.spec_system/specs/phase12-session02-release-closeout-and-rollout-readiness/codex-release-notes.md` | Release notes or changelog-ready entries for Claude Code plus Codex CLI support. | \~120 | | `.spec_system/specs/phase12-session02-release-closeout-and-rollout-readiness/known-limitations-and-followups.md` | Known limitations, open questions closed or carried forward, and follow-up work list. | \~140 | | `.spec_system/specs/phase12-session02-release-closeout-and-rollout-readiness/rollout-readiness-checklist.md` | Direct install, status, doctor, uninstall, rollback, docs, and operator rollout checklist. | \~140 | | `.spec_system/specs/phase12-session02-release-closeout-and-rollout-readiness/implementation-notes.md` | Task log, commands run, failures, fixes, evidence summaries, and validate handoff. | \~220 | ### Files to Modify | File | Changes | Est. Lines | | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ---------- | | `README.md` | Final release wording if evidence changes high-level Codex support status or limitations. | \~30 | | `docs/release.md` | Gate outcomes, release notes input, local-vs-hosted no-claim wording, and rollout notes if needed. | \~60 | | `docs/privacy-and-security.md` | Final Codex privacy and uninstall posture if review finds wording gaps. | \~50 | | `docs/development.md` | Direct Codex setup, trust review, and uninstall workflow corrections if needed. | \~30 | | `docs/deployment.md` | Hosted smoke and deployment no-claim wording if release evidence changes. | \~40 | | `apps/cli/README_cli.md` | CLI support and uninstall wording if rollout review finds gaps. | \~30 | | `apps/hooks/README_hooks.md` | Hook trust, privacy, or plugin deferral wording if review finds gaps. | \~30 | | `.spec_system/specs/phase12-session02-release-closeout-and-rollout-readiness/tasks.md` | Implementation workflow task status updates. | \~40 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Final release-readiness evidence records all required and available gates with statuses and exceptions. * [ ] Privacy and security review covers install, hooks, server, web, replay, export, logs, diagnostics, and uninstall. * [ ] Documentation review confirms Claude Code and Codex CLI paths are represented without plugin, hosted, trust-bypass, or erasure overclaims. * [ ] Release notes or changelog-ready entries describe first-class local Codex CLI hook support and plugin deferral. * [ ] Known limitations and follow-up work are explicit, scoped, and source-backed. * [ ] Rollout checklist covers direct install, `/hooks` review, status, doctor, uninstall, and rollback posture. ### Testing Requirements * [ ] Focused CLI and hooks Codex tests pass or release-blocking failures are fixed and rerun. * [ ] Root format, lint, workspace typecheck, and focused or full tests pass or have source-backed exceptions. * [ ] Available CI-equivalent gates are run according to `docs/release.md` or recorded as unavailable/no-claim. * [ ] No plugin validation is represented as passed because plugin packaging is deferred. * [ ] Evidence artifacts pass ASCII/LF and sensitive-string review. ### Non-Functional Requirements * [ ] Evidence uses labels, counts, command names, booleans, source refs, statuses, and redacted summaries only. * [ ] No raw prompts, command bodies, terminal output, patch bodies, transcript paths, MCP argument bodies, tokens, credentials, broad absolute paths, or raw local config bodies are tracked. * [ ] Local-first behavior remains clear: hosted auth, hosted storage, analytics capture, push, tunnel, public replay hosting, remote execution, production-hosted validation, and trusted erasure remain no-claim unless evidence proves them. * [ ] Open security findings remain open/no-claim where this session does not solve them. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] `git diff --check` passes. * [ ] `npm run format:check` and `npm run lint` pass or exceptions are recorded. *** ## 8. Implementation Notes ### Key Considerations * Session 01 already made the plugin decision: do not reopen packaging unless a release blocker contradicts that evidence. * Direct user-level Codex hooks are the supported release path, and `/hooks` trust review remains a manual user step. * Live hosted smoke may be unavailable in the local environment. Record no-claim/unavailable evidence instead of turning local checks into production-hosted claims. * Release notes should describe what works and what remains limited; they should not read like a marketing claim for parity that does not exist. * If release gates fail, the evidence should record the initial failure, owner, remediation, and rerun result. ### Potential Challenges * Full release gates may be expensive: prioritize required closeout checks, use focused gates first, and record unavailable commands honestly. * Existing worktree changes can blur evidence: record touched files and avoid reverting unrelated changes. * Live Codex trust review is interactive: cite Phase 11 exception and do not use trust-bypass flags. * Hosted deployment claims may be tempting because public URLs exist: require sanitized live smoke before any deployed validation claim. * Docs drift can overstate plugin support: keep Session 01 deferral language visible. ### Relevant Considerations * \[P11] **Source-backed docs stay honest**: final release docs must match supported local hook targets, `/hooks` review, and trust boundaries. * \[P11] **Live trust review must stay explicit**: direct hook setup still needs user review in Codex. * \[P10-apps/cli+apps/hooks] **Backup-first Codex hook management worked**: rollout and uninstall evidence must preserve user-owned hook behavior. * \[P07] **Redaction is boundary-specific**: review each release boundary separately rather than relying only on generic scans. * \[P08] **Release-candidate evidence is claim-scoped**: local gates can pass while hosted identity, production-hosted validation, full erasure, and real executors remain no-claim. * \[P03] **Stable docs are the current contract**: use root README, `docs/`, API docs, package READMEs, architecture, privacy, and deployment docs as current truth. * \[Security] **P06-S07-HOSTED-IDENTITY**: this session does not add hosted account identity. * \[Security] **P06-S07-ERASURE**: uninstall and local cleanup remain narrower than trusted unified erasure. * \[Security] **P06-S07-HOSTED-VALIDATION**: local/no-network evidence is not deployed hosted validation. *** ## 9. Testing Strategy ### Unit Tests * Focused CLI installer and hook-map tests for direct Codex install, preservation, diagnostics, and uninstall. * Focused protocol, hook, server, and web tests only if release-blocking fixes touch those packages. ### Integration Tests * Use Phase 11 source-backed fixture evidence for Codex ingest, browser replay, and trust-review exception unless new source changes require reruns. * Run release guide gates that are available locally: format, lint, typecheck, tests, build, media gates, no-network hosted smoke, secret scan, and diff check as scoped by available time and environment. ### Manual Testing * Review release notes, docs, privacy/security evidence, and rollout checklist against Session 01 plugin deferral and Phase 12 non-goals. * Confirm no docs claim plugin install, plugin cache refresh, plugin trust, project-local trusted `.codex`, hosted telemetry, remote execution, production-hosted validation, or broad trusted erasure. ### Edge Cases * Gate failures must not be hidden by prior evidence; record failure before remediation. * Missing hosted credentials or app hosts should be `unavailable` or `no-claim`, not failed local release support. * Plugin validation remains N/A because no plugin package exists. * Sensitive-string scans may find negative-policy wording; record expected matches without copying raw sensitive evidence. *** ## 10. Dependencies ### External Libraries * None expected. ### Other Sessions * **Depends on**: `phase12-session01-codex-plugin-packaging`, `phase11-session03-end-to-end-validation-and-integration-fixes` * **Depended by**: Phase 12 validation and PRD update workflows *** ## Next Steps Run the implement workflow step to begin AI-led implementation. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase12-session02-release-closeout-and-rollout-readiness/spec.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.