> 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/codex-plugin-validation-plan.md). # Codex Plugin Validation Plan **Session ID**: `phase12-session01-codex-plugin-packaging` **Date**: 2026-05-31 **Selected branch**: Plugin packaging deferred **Status**: Final *** ## Validation Principle Validation must not mutate real user state. Any install, trust, cache, or uninstall check must use isolated `CODEX_HOME` and `FACTIONOS_HOME` values, and tracked evidence must use labels, counts, booleans, command names, source URLs, and redacted summaries only. Because the selected branch defers plugin packaging, plugin install, cache refresh, trust review, and uninstall are not applicable for this session. They are not represented as passed. *** ## Branch-Specific Checklist | Check | Required for defer branch | Result | Evidence | | -------------------------------------- | ------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------- | | Decision record exists | Yes | Pass | `codex-plugin-packaging-decision.md` records defer decision and criteria. | | Direct hook baseline remains supported | Yes | Pass | Stable docs keep `factionos init --cli codex`, `/hooks` review, status, doctor, and uninstall as the supported path. | | `.codex-plugin/plugin.json` absent | Yes | Pass | No package files are created in this branch. | | Repo marketplace entry absent | Yes | Pass | No `.agents/plugins/marketplace.json` is created by this branch. | | Plugin install validation | No | N/A | Deferral branch does not install a plugin. | | Plugin cache refresh validation | No | N/A | Deferral branch does not create or refresh a plugin cache. | | Plugin `/hooks` trust review | No | N/A | Direct hooks keep `/hooks` review guidance; plugin trust is not claimed. | | Plugin uninstall validation | No | N/A | Deferral branch does not create plugin install state. | | Privacy review | Yes | Pass | Evidence files use labels, counts, relative source refs, and no raw Codex payloads. | *** ## Deferral Evidence | Evidence item | Result | Notes | | ----------------------- | ------ | ------------------------------------------------------------------------------------------- | | Selected branch | Defer | Decision record gates packaging behind all criteria and records a failed benefit criterion. | | Plugin manifest | Absent | No `.codex-plugin/` directory is present in the repository. | | Repo marketplace | Absent | No repo marketplace file is present for this branch. | | Plugin source directory | Absent | No repo `plugins/` directory is present for this branch. | | Plugin install | N/A | Not run because no plugin package exists. | | Plugin cache refresh | N/A | Not run because no plugin package exists. | | Plugin trust review | N/A | Not run because no plugin-bundled hooks exist. Direct hooks still require `/hooks` review. | | Plugin uninstall | N/A | Not run because no plugin install state exists. | Command evidence: * Artifact absence check returned `plugin-package-artifacts=absent`. * Manifest validation check returned `plugin-manifest=absent; plugin-validation=n/a`. * Review scan found no claims that plugin install, cache refresh, trust review, or uninstall passed for this branch. * Direct hook validation evidence is inherited from Phase 11; this session did not rerun direct hook install/uninstall because no installer code changed. *** ## Direct Hook Evidence To Carry Forward Session 02 can cite the Phase 11 direct-hook evidence for the supported path: * Isolated `factionos init --cli codex --faction orc` passed. * Reinstall was idempotent and did not duplicate managed hooks. * User-owned Codex hook entries and unknown top-level fields were preserved. * `factionos status --cli codex` and `factionos doctor --cli codex` passed with compact posture and `/hooks` guidance. * `factionos uninstall --cli codex` restored or surgically removed only FactionOS-managed entries and preserved user-owned hooks. * Live `/hooks` trust review was recorded as an interactive exception, not overclaimed. * Fixture replay covered local ingest, WebSocket, browser display, replay, and privacy boundaries without raw payload evidence. *** ## Future Plugin Branch Plan If a later session reopens plugin packaging, run this plan before marking any plugin package as shipped: 1. Create temporary homes outside the repository. 2. Build or copy the plugin into an isolated repo or personal marketplace root. 3. Validate `.codex-plugin/plugin.json` schema and path rules. 4. Verify bundled hooks use `PLUGIN_ROOT` and do not duplicate handler logic. 5. Install the plugin from the isolated marketplace. 6. Restart or refresh Codex as required for local plugin cache behavior. 7. Confirm plugin-bundled hooks appear in `/hooks` as needing user review. 8. Do not use trust-bypass flags as normal validation. 9. Run direct hook regression checks to prove `factionos init --cli codex` still works and remains uninstallable. 10. Uninstall the plugin from the isolated environment and verify no plugin cache or config evidence is claimed beyond the isolated scope. All future evidence must redact temp paths, raw prompts, patch bodies, command output, transcripts, MCP argument bodies, tokens, credentials, auth values, hosted URLs with authority, and broad local paths. *** ## Sensitive Evidence Rules Allowed in tracked evidence: * File names and relative repo paths. * Command names without raw command output. * Counts, booleans, labels, and source URLs. * Status labels such as `pass`, `fail`, `n/a`, `unavailable`, and `manual-review-required`. Not allowed in tracked evidence: * Raw Codex hook payloads. * Prompt bodies. * Raw patch bodies or diffs. * Terminal output bodies. * Transcript paths. * MCP argument bodies. * Token-like values, credentials, API keys, cookies, or auth headers. * Temporary home paths or broad absolute local paths. *** ## Session 02 Handoff Release closeout should state: * Codex plugin packaging is deferred for this release. * Direct user-level Codex hooks are the validated supported setup path. * `/hooks` trust review remains explicit and manual. * Plugin install, cache refresh, trust, and uninstall were not run because no plugin package was created. * This is a deliberate packaging decision, not unfinished validation. --- # 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/codex-plugin-validation-plan.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.