Update to Engineering Project OS

Changed files

Choose a file to see its text changes. Binary or large files show metadata only.

.codex-plugin/plugin.json →

CHANGELOG.md →

CONTRIBUTING.md →

README.md →

SECURITY.md →

docs/HOW_IT_WORKS.md →

docs/PACKAGING.md →

docs/PRIVACY.md →

docs/REFERENCE.md →

docs/SETUP.md →

docs/USAGE.md →

plugin.json →

scripts/check_codex_review.py →

skills/project-os/SKILL.md →

skills/project-os/assets/templates/core/.agents/WORKFLOW.md →

skills/project-os/assets/templates/core/AGENTS.md →

skills/project-os/evals/README.md →

skills/project-os/evals/continuity.json →

skills/project-os/evals/prepare_fixture.py →

skills/project-os/evals/prompts.json →

skills/project-os/references/knowledge.md →

skills/project-os/references/maintenance.md →

skills/project-os/scripts/project_os.py →

skills/project-os/scripts/snapshot.py →

docs/SETUP.md

− removed · + added

--- before
+++ after
@@ -1,159 +1,113 @@
 # Setup
 
-Engineering Project OS is a Codex developer tool distributed primarily through its GitHub marketplace. Installation makes the Project OS skill available, but it does not attach a repository or write Project OS records.
+Install Engineering Project OS, then ask Codex to connect the repository you want to work in. Installation makes the skill available; connection creates or adopts that repository's working records.
+
+This guide targets Project OS 2.3.0 source. Verify release availability and the version resolved by the chosen channel separately. Versioned URLs below require the matching published tag; a candidate checkout does not make those URLs available. Before publication, evaluate a frozen supplied candidate in isolation without replacing the installed stable copy.
 
 ## Requirements
 
-- A Codex CLI with plugin support for marketplace installation, or the built-in Codex skill installer for a standalone skill.
-- A local repository opened as the Codex workspace.
-- Python 3.9 or newer on macOS or Linux for deterministic helper operations.
-- A clean understanding of any existing `AGENTS.md`, `.agents/` records and uncommitted work before setup.
+- A local repository opened in Codex.
+- Python 3.9 or newer on macOS or Linux for the deterministic helper.
+- For the GitHub alternative, a Codex CLI with plugin support.
 
-## 1. Install in Codex from GitHub
+Codex inspects existing instructions and configuration. You do not need to choose packs or edit JSON.
 
-Run these commands in Terminal:
+<a id="legacy-directory"></a>
 
-~~~shell
-codex plugin marketplace add innrvoice/engineering-project-os --ref main
-codex plugin add engineering-project-os@engineering-project-os
-~~~
+## Install from the Plugin Directory
 
-The first command registers the repository marketplace from `main`. The catalog's plugin entry pins the installed source to `v2.2.4`. Open the target repository in Codex and start a new task so the installed skill is available. Confirm the selected helper's version is `2.2.4` before connecting or upgrading a repository:
+1. Open the [Engineering Project OS card in the Plugin Directory](https://chatgpt.com/plugins/plugins_6aa793523ba481918ea921c5438d98c9) and check the version offered. It must match 2.3.0 when validating this source version.
+2. Use the plus button to install, as described in [OpenAI's plugin guide](https://learn.chatgpt.com/docs/plugins).
+3. Start a new Codex chat in your repository. Ask Codex to verify the selected Directory source and actual installed helper version, then [connect the repository](#connect-a-repository). An earlier installed release does not test this candidate.
 
-~~~shell
-python3 -B -c 'import runpy; print(runpy.run_path("/absolute/path/to/project-os/scripts/project_os.py")["VERSION"])'
-~~~
-
-Resolve this path from the installed skill selected by Codex. Do not guess a cache path or copy plugin files into the repository. Marketplace registration and plugin installation belong to the user profile while Project OS records belong to each connected repository. For a standalone skill, use the [secondary installation route](#standalone-codex-skill).
+In ChatGPT, select `@Engineering Project OS` for the companion workflow over supplied files. Installation alone does not give ChatGPT access to your local checkout.
 
-The official [plugin packaging guide](https://developers.openai.com/plugins/build/plugins#add-a-marketplace-from-the-cli) describes marketplace registration and local plugin sources for supported clients, including Codex CLI and Codex in the ChatGPT desktop app. The commands here use the CLI; desktop marketplace controls follow the host's current UI.
+<a id="2-inspect-the-repository"></a>
+<a id="3-preview-and-connect"></a>
+<a id="4-validate-and-restart"></a>
 
-## 2. Inspect the repository
+## Connect a repository
 
-**Type this in Codex chat:**
+Open the intended repository and send:
 
 ~~~text
-$project-os inspect
+$project-os Help me set up Project OS for this repository and start with a safe preview.
 ~~~
 
-Inspection is read-only. Codex reads Git state, applicable instructions, existing Project OS records, documentation and available engineering configuration. It reports one recommended connection path and the files that path would affect.
+Codex inspects Git state, instructions and existing records. It chooses a fresh setup, preserves existing instructions or adopts compatible records. You do not select the internal operation yourself.
 
-The possible paths are:
+Before writing, Codex shows the proposed files and explains what it will preserve. Review that preview and approve the proposed connection. If the root, ownership or existing instructions are ambiguous, Codex asks for the decision it needs instead of replacing them.
 
-- **Clean bootstrap:** no existing Project OS authority needs preservation.
-- **`AGENTS.md`-preserving bootstrap:** a compatible root instruction file already exists and must remain authoritative.
-- **Adoption:** compatible context, plans, findings, evidence or knowledge already exist and should be mapped instead of replaced.
+The result is a connected repository in Standard mode, with context, working records and instruction routing. Setup preserves project authority and safe unrelated namespaces. It does not open a plan, start a Program or change application code. Adoption preserves compatible records and their ownership.
 
-Stop if the report cannot identify the repository root, finds ambiguous ownership or would overwrite project-owned authority.
+After setup, Codex checks and reports the changed files. Start a new chat to load the repository instructions. Then ask for normal engineering work without a Project OS prefix.
 
-## 3. Preview and connect
+For a read-only assessment, ask `$project-os inspect`. Exact operations are in [Reference](REFERENCE.md#project-os-requests).
 
-For a bootstrap, continue with:
+<a id="upgrade-to-224"></a>
 
-~~~text
-$project-os bootstrap
-~~~
+## Upgrade to 2.3.0
 
-For compatible existing records, use:
+Update your installation first using the Directory host controls or the [GitHub](#github-marketplace-alternative) or [standalone](#standalone-codex-skill) route below. Then open the connected repository in a new Codex chat and send:
 
 ~~~text
-$project-os adopt
+$project-os upgrade
 ~~~
 
-Codex inspects again, prepares the operation and runs the deterministic helper with `--dry-run`. Review the proposed files before authorizing the same operation without `--dry-run`.
+Codex previews the upgrade and applies the reviewed operation after authorization, then checks records and changed paths. Locally modified managed content requires an ownership decision before overwriting.
 
-Bootstrap creates Standard mode. It does not create a Program, active plan or application code. It preserves safe unrelated `.agents` namespaces such as `.agents/plugins` and refuses an unsafe overwrite.
+Updating the installed copy does not upgrade repository records by itself. The transaction can update managed instructions, routing and migration metadata. A reviewed proof migration can add helper-owned metadata or historical evidence archives while preserving original values and hashes. It does not authorize application changes or turn historical acceptance into newly verified behavior.
 
-Adoption maps compatible records to the Project OS ownership model. It does not silently treat arbitrary Markdown as current authority.
+The upgrade delivers the compact recovery instructions to existing repositories while preserving project-owned records. A helper that genuinely lacks `brief` uses its own supported checks and targeted record reads; a stale or invalid checkpoint is an error to inspect, not evidence that the helper is old. See [Reference](REFERENCE.md#interfaces).
 
-## 4. Validate and restart
+## Legacy finding proof ownership
 
-After the reviewed operation is applied, run:
+Some repositories using 2.2.3 need an explicit review to distinguish earlier helper proofs from project-owned fields. Codex prepares that review and preserves the original data. If upgrade changes a file used as evidence, it also identifies the exact historical bytes that need archival consent. Missing proof or unclear ownership blocks the operation.
 
-~~~text
-$project-os check
-~~~
+The [technical ownership contract](REFERENCE.md#legacy-finding-proof-ownership) describes `--finding-proof-review` and [historical snapshots](REFERENCE.md#historical-evidence-snapshots-during-upgrade). You do not need to assemble that JSON for the ordinary upgrade request.
 
-A successful setup requires the helper check to pass and the Git diff to contain only the approved control-plane files. Start a new Codex task after `AGENTS.md` is created or changed so its instruction route enters the task startup chain.
+## ChatGPT companion setup
+
+Select `@Engineering Project OS` in ChatGPT. Explanations need no files; setup advice can start from a description. Inspecting or updating an existing setup requires its instructions and records. ChatGPT must ask for missing material.
 
-Ordinary engineering work now uses ordinary requests. Use `$project-os` when the request concerns Project OS maintenance, durable plan state, findings, evidence, knowledge or Program lifecycle.
+Changed files remain supplied-copy artifacts until you deliberately apply them to the real repository and validate them in Codex. File reading, helper execution and downloadable output depend on the current host and permissions. If a required capability is absent, ChatGPT must name it and leave the affected operation unverified rather than inventing a successful check or file. Use [Usage](USAGE.md#chatgpt-companion-boundaries) for that boundary.
 
-## Upgrade to 2.2.4
+<a id="1-install-in-codex-from-github"></a>
 
-Project OS 2.2.4 retains SYSTEM schema 5, plans schema 2, JSON acceptance contracts and durable request intake. It corrects proof refresh and separates helper-owned finding proofs from project extensions while retaining checkpoint verification and atomic completion. Upgrading a legacy schema also delivers the schema-5 continuity records; upgrading an existing schema-5 repository keeps the schema and knowledge-transfer formats unchanged.
+## GitHub marketplace alternative
 
-For an already registered GitHub marketplace, refresh its catalog and install the pinned plugin in Terminal:
+Use the GitHub marketplace if you prefer that distribution route. Run these commands in Terminal:
 
 ~~~shell
-codex plugin marketplace upgrade engineering-project-os
+codex plugin marketplace add innrvoice/engineering-project-os --ref main
 codex plugin add engineering-project-os@engineering-project-os
 ~~~
 
-For a first GitHub installation, use the registration commands above. For a standalone installation, use the pinned skill-installer request below. Resolve duplicate installations and verify the selected helper version, then start a new Codex task in the repository and type:
-
-~~~text
-$project-os upgrade
-~~~
-
-Codex must use the installed 2.2.4 helper transaction:
-
-~~~text
-python3 /absolute/path/to/project-os/scripts/project_os.py upgrade --target /path/to/repository --dry-run
-python3 /absolute/path/to/project-os/scripts/project_os.py upgrade --target /path/to/repository
-python3 /absolute/path/to/project-os/scripts/project_os.py check --target /path/to/repository
-git diff --check
-~~~
-
-Review the dry-run before applying it. After the check, inspect the exact changed paths. The reviewed transaction adds managed WORKFLOW, an empty requests registry, minimal AGENTS routing and plan-index migration metadata. Existing Markdown plans, context, state, evidence and application code remain unchanged. Findings retain their legacy fields; an explicitly reviewed proof adoption can add only the helper-owned namespace. Historical closed plans retain their dispositions without new proof. Before resuming a legacy unfinished plan, review its contract and remove its migration mark. Existing legacy knowledge migration rules remain applicable.
-
-Updating the installed plugin or standalone skill alone does not upgrade a connected repository. Each repository keeps its recorded release until this explicit transaction succeeds.
-
-## Legacy finding proof ownership
-
-When the source repository records 2.2.3 and contains bare finding proof-like fields, Codex must prepare an explicit ownership review before upgrade. It preserves every project-owned field and adopts proven helper proofs without changing their original hashes. Ambiguous ownership stays pending; it is not resolved by deleting data or accepting changed evidence.
-
-The [technical ownership migration contract](REFERENCE.md#legacy-finding-proof-ownership) describes `--finding-proof-review`, its exact registry hash, complete ID decisions and preview/apply commands. Earlier repositories preserve bare extension fields automatically. Updating the installed plugin does not perform this review or upgrade project records by itself.
-
-## ChatGPT companion setup
-
-ChatGPT is a companion for explanations, supplied project files and portable knowledge bundles. Where the companion is available in ChatGPT, start a new chat and select it with `@Engineering Project OS`. Codex marketplace commands install into Codex; they do not install a plugin in ChatGPT Web. See the [legacy Directory status](#legacy-directory) for that separate channel.
-
-An overview needs no repository input:
+The catalog comes from `main`; this checkout's plugin entry pins the source to `v2.3.0`. The published catalog can still name an earlier release, so verify the resolved source and actual helper bytes. Registering `main` does not select an uncommitted candidate checkout. For an existing marketplace registration, refresh it in Terminal:
 
-~~~text
-@Engineering Project OS Tell me how Project OS helps Codex resume real engineering work across sessions.
+~~~shell
+codex plugin marketplace upgrade engineering-project-os
+codex plugin add engineering-project-os@engineering-project-os
 ~~~
 
-Setup advice can begin from a project description. Claims about an existing setup require the relevant files, usually `AGENTS.md`, `.agents/SYSTEM.json`, `.agents/CONTEXT.md`, `.agents/STATE.md` and the registries involved in the request. A complete repository archive is optional and appropriate only when the complete tree matters.
-
-ChatGPT works against the supplied copies. It cannot connect to a live local checkout through installation alone. Any generated or changed files remain chat artifacts until the user deliberately applies them to the repository and validates the result in Codex.
+Start a new Codex chat afterward. Codex must verify the selected installation and helper version before connecting or upgrading a repository. These commands do not install the ChatGPT Web companion.
 
 ## Standalone Codex skill
 
-The secondary route installs only the standalone Codex skill. Send the following message in Codex chat, not Terminal:
+After the matching tag is published, send this message in Codex chat for a skill-only installation, not Terminal:
 
 ~~~text
-$skill-installer Install project-os from https://github.com/innrvoice/engineering-project-os/tree/v2.2.4/skills/project-os
+$skill-installer Install project-os from https://github.com/innrvoice/engineering-project-os/tree/v2.3.0/skills/project-os
 ~~~
 
-Start a new Codex task after installation. This versioned URL does not follow `main` automatically. Verify the selected helper version before upgrading any repository.
+Start a new chat afterward. This pinned skill does not follow future releases or provide the ChatGPT companion. Continue with [connection](#connect-a-repository) or [repository upgrade](#upgrade-to-230).
 
 ## Resolve duplicate installations
 
-Keep one intended Project OS installation active. Inspect the selected skill path and helper version before relying on `$project-os`; a GitHub plugin, an older Directory plugin and a standalone skill can otherwise compete. Disable an obsolete plugin through its host controls or remove an obsolete standalone skill only after confirming its path and obtaining any required authorization. Preserve repository-owned `AGENTS.md` and `.agents/` records. Start a new task and verify the selected version again.
-
-## Legacy Directory
-
-The existing [Universal Plugin Directory listing](https://chatgpt.com/plugins/plugins_6aa793523ba481918ea921c5438d98c9) remains on 2.2.2. On 2026-10-16, the maintainer reported that the Portal would not accept an updated skills-only submission for Engineering Project OS. This observation concerns this plugin's submission, so the GitHub release proceeds independently.
-
-An existing Directory installation can retain its own companion access and older skill. Installing from GitHub does not upgrade that listing or prove that a new version is available in ChatGPT. Resolve any duplicate Codex installation before using the GitHub helper.
+To move from GitHub to Directory, install the intended Directory release first. In a new chat, have Codex verify its source, path and actual helper version. Then disable the GitHub copy, leave one installation active and start a new chat. Preserve `AGENTS.md` and `.agents/`; connecting again is unnecessary. Run `$project-os upgrade` separately if the repository needs it.
 
-## Setup boundaries
+For a standalone duplicate, confirm its path and removal permission first. After switching, verify the selected copy again.
 
-- Installing the plugin is not connecting a repository.
-- Connecting a repository is not opening a plan.
-- Opening a plan is not starting a Program.
-- A passing Project OS check proves structural consistency, not product acceptance.
-- No setup path authorizes dependency installation, application edits, Git operations, deployment or publication.
+<a id="setup-boundaries"></a>
 
-Use [Usage](USAGE.md) for developer workflows, [Reference](REFERENCE.md) for exact syntax and [Packaging](PACKAGING.md) for maintainer release procedures.
+Setup grants no permission to install dependencies, delete data, commit, push, deploy or publish. Continue with [Usage](USAGE.md); exact syntax and formats belong in [Reference](REFERENCE.md).