> 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-session01-codex-plugin-packaging/spec.md).

# Session Specification

**Session ID**: `phase12-session01-codex-plugin-packaging` **Phase**: 12 - Codex Packaging and Release Readiness **Status**: Not Started **Created**: 2026-05-31 **Package**: Cross-cutting **Package Stack**: JavaScript CLI/hooks, TypeScript protocol/server/web docs, Node 20+, Codex hook config, optional Codex plugin manifest, Vitest, Biome

***

## 1. Session Overview

This session resolves whether FactionOS should ship a Codex plugin in addition to the supported direct user-level Codex hook installation path. Phase 11 validated first-class local Codex hook support through docs, fixtures, and end-to-end validation. Phase 12 now needs a clear packaging decision that does not turn plugin work into a release blocker.

The session is cross-cutting because the decision depends on CLI install behavior, hook map reuse, Codex trust review, docs, privacy posture, and release maintenance value. The default outcome remains direct user-level hooks unless plugin packaging provides concrete maintenance, distribution, or trust-review value over the already validated path.

Implementation starts with a decision gate. If every packaging criterion passes, the session may create a small Codex plugin package that reuses the existing hook maps, handlers, docs, and privacy rules. If any criterion fails, the session records an explicit deferral and updates stable docs so Session 02 can complete release closeout without ambiguous plugin claims.

***

## 2. Objectives

1. Evaluate Codex plugin packaging against the Phase 12 decision criteria and current direct hook evidence.
2. Record a source-backed packaging decision with clear proceed or defer rationale.
3. Implement only the selected branch: a minimal reusable plugin package if justified, or explicit deferral docs if direct hooks are simpler and safer.
4. Preserve direct user-level Codex hooks as the supported baseline and avoid overclaiming trust bypass, hosted behavior, telemetry, or Codex setting mutation.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase11-session03-end-to-end-validation-and-integration-fixes` - provides install, hook trust or fixture exception, ingest, web display, status, doctor, uninstall, and privacy validation evidence.
* [x] `phase11-session02-test-fixture-hardening` - provides source-backed Codex fixtures and redaction coverage.
* [x] `phase11-session01-documentation-and-privacy-sync` - provides stable Codex setup, trust, and privacy wording.
* [x] `phase10-session02-codex-hook-install-uninstall-and-diagnostics` - provides user-level Codex hook installer, diagnostics, and uninstall support.

### Required Tools/Knowledge

* npm workspace and package boundaries from `.spec_system/CONVENTIONS.md`.
* Codex hook trust and config behavior documented in `apps/hooks/README_hooks.md` and `docs/api/event-api-hook-contracts.md`.
* Phase 12 packaging decision criteria from `.spec_system/PRD/phase_12/PRD_phase_12.md`.
* Direct hook validation evidence from Phase 11 Session 03.
* Current Codex plugin manifest requirements and cache or install behavior, reviewed during implementation before any package files are created.

### Environment Requirements

* Node 20+ and installed npm workspace dependencies.
* Isolated `CODEX_HOME` and `FACTIONOS_HOME` for any install, trust, cache, or uninstall validation.
* No secrets, raw prompts, raw patch bodies, transcript paths, MCP argument bodies, token-like values, 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)

* Operators can see why Codex plugin packaging is shipped or deferred - record the decision criteria, evidence, and release implications.
* Maintainers can compare plugin packaging with direct user-level hooks - evaluate install, trust review, cache refresh, uninstall, reuse, maintenance, and privacy value.
* Users keep direct Codex hooks as the baseline path - update docs so `factionos init --cli codex` remains supported regardless of plugin outcome.
* If packaging proceeds, the plugin package reuses existing hook maps and handlers - avoid a second runtime path, duplicate hook definitions, or divergent privacy rules.
* If packaging is deferred, stable docs explicitly say why - direct hooks are simpler, safer, sufficient, or easier to trust for the first Codex release.

### Out of Scope (Deferred)

* Making plugin packaging mandatory for Codex support - *Reason: direct hooks are the validated supported baseline.*
* Replacing `factionos init --cli codex` or `factionos uninstall --cli codex` - *Reason: existing CLI workflows remain release-critical.*
* Creating project-local trusted `.codex/` state by default - *Reason: trust remains user-reviewed and scoped to Codex behavior.*
* Bypassing Codex `/hooks` trust review - *Reason: trust bypass is not a supported setup path.*
* Mutating Codex auth, provider, model, profile, telemetry, API key, account, or trusted-project settings - *Reason: FactionOS must stay observability-only and local-first.*
* 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 cleanup are not broad erasure claims.*

***

## 5. Technical Approach

### Architecture

Use a decision-gated implementation. Start from the Phase 12 criteria and Phase 11 validation evidence, then review current Codex hook and plugin requirements before creating any plugin package. The decision record is the primary artifact; it must explain which criteria passed, which failed, what evidence was used, and what Session 02 can safely claim.

If the gate passes, add the smallest plugin package that can reuse the existing Codex hook map and handler assets. The package must avoid duplicating runtime logic, must not write user trust state automatically, and must validate install, trust review, cache refresh, and uninstall in an isolated environment. If the gate does not pass, update docs and evidence so the release keeps direct user-level hooks as the supported path without plugin ambiguity.

### Design Patterns

* Decision gate first: create package files only after the criteria are satisfied.
* Baseline preservation: keep direct user-level hooks and uninstall behavior unchanged.
* Reuse over fork: use existing hook maps, handlers, docs, and privacy rules instead of a second hook runtime.
* Isolated local validation: use temporary homes for install, cache, trust, and uninstall checks.
* Boundary-specific redaction: review decision docs, install output, diagnostics, logs, and examples separately.

### Technology Stack

* Node 20+ npm workspaces.
* CLI and hooks: JavaScript under `apps/cli` and `apps/hooks`.
* Stable docs: root README, `docs/`, and package README files.
* Optional plugin package: Codex plugin manifest and bundled hook assets if packaging proceeds.
* Tests and gates: Vitest, Biome, `git diff --check`, secret scan, ASCII/LF checks.

***

## 6. Deliverables

### Files to Create

| File                                                                                             | Purpose                                                                                                     | Est. Lines |
| ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | ---------- |
| `.spec_system/specs/phase12-session01-codex-plugin-packaging/codex-plugin-packaging-decision.md` | Decision record with criteria, source refs, evidence, proceed or defer rationale, and release implications. | \~180      |
| `.spec_system/specs/phase12-session01-codex-plugin-packaging/codex-plugin-validation-plan.md`    | Install, trust, cache refresh, uninstall, privacy, and fallback evidence checklist for the selected branch. | \~120      |
| `.codex-plugin/plugin.json`                                                                      | Conditional minimal plugin manifest if and only if packaging passes the decision gate.                      | \~50       |
| `.codex-plugin/README.md`                                                                        | Conditional plugin usage, trust review, uninstall, and privacy notes if packaging proceeds.                 | \~100      |

### Files to Modify

| File                                                                                  | Changes                                                                                                | Est. Lines |
| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ---------- |
| `apps/cli/README_cli.md`                                                              | Keep direct Codex hooks as baseline and document plugin outcome or deferral.                           | \~40       |
| `apps/hooks/README_hooks.md`                                                          | Align hook package docs with plugin decision, trust review, and reuse boundaries.                      | \~50       |
| `docs/api/event-api-hook-contracts.md`                                                | Update hook contract wording only if packaging changes supported install surfaces or deferral wording. | \~40       |
| `docs/development.md`                                                                 | Update developer workflow notes for plugin packaging or explicit deferral.                             | \~30       |
| `README.md`                                                                           | Update high-level Codex support status only if needed for release clarity.                             | \~30       |
| `.spec_system/specs/phase12-session01-codex-plugin-packaging/implementation-notes.md` | Record commands, evidence, selected branch, tests, privacy review, and handoff to Session 02.          | \~160      |

***

## 7. Success Criteria

### Functional Requirements

* [ ] The session records a clear ship-or-defer decision for Codex plugin packaging.
* [ ] The decision uses Phase 12 criteria and Phase 11 direct hook evidence.
* [ ] Direct user-level Codex hook install, trust review guidance, diagnostics, and uninstall remain the supported baseline.
* [ ] If a plugin package is created, it reuses existing hook maps and handlers and validates install, trust review, cache refresh, and uninstall in isolated homes.
* [ ] If plugin packaging is deferred, stable docs explicitly explain the rationale and supported direct hook path.
* [ ] Docs do not claim trust bypass, project-local trusted `.codex/` setup, hosted telemetry, Codex settings mutation, or plugin mandatory support.

### Testing Requirements

* [ ] Focused CLI and hooks tests pass for any touched install, uninstall, provider posture, or hook map behavior.
* [ ] Any plugin manifest or validation helper is schema-checked or otherwise mechanically validated.
* [ ] Documentation-only deferral is backed by a decision record and no skipped validation is described as passed.
* [ ] Manual evidence is recorded for install, trust, cache, and uninstall only when the plugin branch is implemented.

### Non-Functional Requirements

* [ ] Evidence artifacts contain only labels, counts, safe IDs, command names, booleans, source links, and redacted summaries.
* [ ] No raw prompts, command output, terminal output, patch bodies, transcript paths, MCP argument bodies, tokens, credentials, or broad absolute paths appear in tracked files.
* [ ] Claude defaults and direct Codex hook behavior remain unchanged unless a packaging bug forces a scoped fix.
* [ ] Open security findings remain no-claim where not solved: hosted identity, trusted erasure, and production-hosted validation.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] `npm run format:check` passes for touched source areas or exceptions are recorded.
* [ ] `npm run lint` passes for touched source areas or exceptions are recorded.
* [ ] `git diff --check` passes.

***

## 8. Implementation Notes

### Key Considerations

* The direct hook path already has validation evidence; plugin packaging must add real value, not just another install surface.
* Current docs deliberately say FactionOS does not package a Codex plugin yet. This session either changes that statement with evidence or keeps it explicit.
* A plugin package should not fork `apps/hooks/hooks.codex.json`, handler scripts, or redaction rules unless the decision record explains why reuse is impossible.
* The `/hooks` trust-review step remains user-visible and manual. Do not document bypasses as a normal workflow.
* Session 02 depends on this outcome for release notes, known limitations, and final closeout gates.

### Potential Challenges

* Codex plugin requirements may differ from direct hook config: review current requirements before creating package files.
* Plugin cache refresh can be hard to validate non-interactively: use isolated homes and record any manual step honestly.
* Packaging can duplicate hook assets accidentally: prefer references or generated copies with explicit provenance if packaging requires bundled files.
* Deferral can look like unfinished work: make the decision evidence strong enough for release closeout.
* Late docs edits can overclaim Codex parity: keep no-claim wording for hosted auth, telemetry, trust bypass, remote execution, and trusted erasure.

### Relevant Considerations

* \[P10-apps/cli+apps/hooks] **Backup-first Codex hook management worked**: direct hook install and uninstall must remain reversible and user-owned hook safe.
* \[P11] **Live trust review must stay explicit**: plugin packaging cannot hide or bypass `/hooks` review.
* \[P11] **Source-backed docs stay honest**: stable docs must match shipped behavior and supported setup paths.
* \[P07] **Redaction is boundary-specific**: decision evidence, docs examples, install output, diagnostics, and logs need separate privacy checks.
* \[P03-apps/cli+apps/hooks] **Lifecycle state is local and file-based**: validation should use isolated homes and avoid real user state.
* \[P09-apps/hooks] **Do not forward raw Codex payloads**: raw patch bodies, terminal output, transcript paths, token-like values, and MCP arguments stay summarized or redacted.
* \[Security] **P06-S07-HOSTED-IDENTITY**: this session does not add hosted identity or account proof.
* \[Security] **P06-S07-ERASURE**: uninstall and plugin cleanup are not trusted unified erasure.
* \[Security] **P06-S07-HOSTED-VALIDATION**: local packaging validation is not production-hosted validation.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Plugin package files create a second hook runtime that drifts from the direct hook path.
* Install or cache refresh validation mutates real Codex or FactionOS user state.
* Docs imply plugin packaging is required, trusted automatically, or equivalent to bypassing Codex hook review.
* Evidence or docs leak sensitive Codex-shaped fields while explaining packaging.

***

## 9. Testing Strategy

### Unit Tests

* CLI: focused tests for Codex installer, provider posture, uninstall, and user-owned hook preservation when touched.
* Hooks: focused tests for Codex hook map shape and handler reuse when touched.
* Plugin branch: manifest or packaging helper validation if plugin files are created.

### Integration Tests

* Plugin branch: isolated install, trust review guidance, cache refresh, and uninstall validation against temporary homes.
* Deferral branch: decision record plus docs review proving direct hooks remain the supported path and no plugin files are required.

### Manual Testing

* Review the selected branch against Phase 12 packaging criteria.
* For plugin branch, run the documented plugin install and uninstall workflow without using real user config.
* For deferral branch, verify docs clearly describe direct hooks as supported and plugin packaging as deferred.

### Edge Cases

* Existing user-owned Codex hooks remain present and are not rewritten by packaging checks.
* Malformed or missing Codex hook config does not become a plugin release claim.
* Cache refresh or trust review unavailable states are recorded as unavailable, not passed.
* Docs avoid raw local paths, tokens, command outputs, patch bodies, transcript paths, and MCP argument bodies.

***

## 10. Dependencies

### External Libraries

* None expected unless a plugin validation helper requires a small manifest parser; prefer built-in Node APIs.

### Other Sessions

* **Depends on**: `phase11-session03-end-to-end-validation-and-integration-fixes`
* **Depended by**: `phase12-session02-release-closeout-and-rollout-readiness`

***

## 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-session01-codex-plugin-packaging/spec.md?ask=<question>&goal=<endgoal>
```

`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.