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/USAGE.md

− removed · + added

--- before
+++ after
@@ -1,239 +1,118 @@
 # Usage
 
-Engineering Project OS is built for Codex. Use it when engineering work must survive multiple tasks, preserve evidence or carry reviewed failure lessons into another repository you own. ChatGPT is a companion for explanations, supplied files and portable bundles.
+After [connecting a repository](SETUP.md#connect-a-repository), ask Codex for the engineering work you want. You do not need to manage findings, checkpoint commands or JSON yourself. Use `$project-os` when the request concerns Project OS itself or explicitly selects its knowledge workflow.
 
-After a repository is connected, ordinary product work does not need a Project OS prefix. Use `$project-os` when the request itself concerns inspection, durable work state, findings, knowledge, upgrades or Program lifecycle.
-
-## Compact request table
-
-| Developer job | Codex request | Writes |
-| --- | --- | --- |
-| Understand the system | `$project-os overview` | No |
-| Inspect repository state | `$project-os inspect` | No |
-| Create or adopt the control plane | `$project-os bootstrap` or `$project-os adopt` | After a clean preview |
-| Validate the control plane | `$project-os check` | No |
-| Read remaining work | `$project-os plan status[: <plan-id>]` | No |
-| Resume or manage durable work | `$project-os plan open: <outcome>`, `plan checkpoint`, `plan resume`, `plan complete`, `plan block: <reason>` or `plan supersede: <reason>` | Record changes after review |
-| Coordinate a multi-phase initiative | `$project-os program start: <initiative>`, `program status` or `program close <disposition>` | Start and close after a clean preview; status is read-only |
-| Record and reuse failures | `$project-os finding add: <observation>` or `$project-os knowledge <operation>` | Capture, approval, lifecycle and import operations may write |
-| Upgrade a connected repository | `$project-os upgrade` | Managed files after a clean dry-run |
-
-Use [Reference](REFERENCE.md) for every request variant, exact helper syntax and record schema.
-
-## Return to work in a new Codex task
-
-Open the repository and ask Codex to continue the actual engineering job. Applicable `AGENTS.md` files route it to the current Project OS state automatically.
+## Work on a normal engineering task
 
 ~~~text
-Continue the offline retry work from the current repository state. Verify the recorded blocker before changing code.
+Fix the crash when the input is missing and run the focused tests.
 ~~~
 
-Codex should inspect WORKFLOW, unresolved requests, the active plan with its contract, STATE, relevant findings and referenced evidence. It should distinguish facts that remain current from acceptance gates that still need verification, then continue from the recorded next action.
-
-Use `$project-os plan resume` only when the Project OS plan transition itself is required, such as reactivating a blocked plan after its blocker is proven resolved. A new task does not require a ceremonial resume command when an active plan already routes the work.
-
-## Open and checkpoint a long task
+Codex investigates, reproduces the symptom where practical, makes the authorized correction and checks it. Its repository instructions require recording reproduced defects, including one you already named, while keeping hypotheses distinct from confirmed causes.
 
-Open a plan when an outcome is likely to outlive the current task or needs explicit acceptance conditions:
+The saved finding, evidence and current checkpoint describe what changed, what was checked and what remains. A bounded repair can stay plan-free. Passing tests does not replace this handoff.
 
-~~~text
-$project-os plan open: make password reset idempotent across API retries and worker redelivery
-~~~
+Decisions are needed for material ambiguity, scope changes or actions requiring permission. The agent must follow the workflow; Project OS does not independently discover every defect.
 
-Codex inspects current authority, checks that no other plan is active and prepares one outcome-sized plan. The Markdown plan records scope, exclusions, implementation and decisions. Its adjacent JSON contract owns acceptance conditions, required proof and next actions; the index owns status. It does not implement the feature merely because the plan was opened.
+## Return to work in a new Codex task
 
-Checkpoint after repository truth changes materially or before a handoff:
+Open the repository and ask:
 
 ~~~text
-$project-os plan checkpoint
+Continue the current work from the repository records. Verify what remains before changing code.
 ~~~
 
-A checkpoint reconciles the plan and `STATE.md` with actual work, findings and evidence. It is not a transcript. The result should state what is complete, what remains unverified and the exact next action.
+When execution is available and permitted, Codex first runs the selected helper's read-only `brief`. That compact report keeps complete unfinished requests visible and routes the context, checkpoint and active plan with its acceptance conditions. Codex reads original registries before changing them or when errors or missing detail require it. It verifies consistency and freshness before relying on the saved next action. This also applies after context compaction.
 
-Complete only when the plan's required evidence exists:
+Codex verifies whether a recorded blocker is resolved and asks for a plan choice only when ambiguous. A new chat needs no resume command when the active plan already identifies the work.
 
-~~~text
-$project-os plan complete
-~~~
-
-The request invokes the helper plan complete with a checkpoint draft and reviewed dry run. It cannot close a plan with a pending prerequisite, invalid proof or unresolved scoped request. Completion saves the idle checkpoint and its fresh receipt in the same transaction and verifies CURRENT. Following slices remain planned. Source checks, deployment, public availability and physical acceptance remain separate gates. A passing CI job cannot satisfy a device-specific acceptance condition unless the plan explicitly defines that equivalence.
+Recovery uses saved files, not the entire previous conversation. Codex must reconcile stale records or explain discrepancies for a read-only request. The checkpoint should leave one concrete next action.
 
 ## Add a requirement during work
 
-Send an ordinary instruction, without a Project OS prefix or a separate save command:
-
 ~~~text
 Also handle reconnecting after the app has been offline. Keep the existing retry behavior.
 ~~~
 
-Codex captures the requirement immediately and integrates it into the same outcome's contract. A material outcome change raises contract revision and requires reassessing proof. Captured means saved; integrated means assigned; implemented requires verified linked gates.
+Codex records a material instruction while handling your message, without waiting for a separate save command. A compatible addition joins the current outcome and its acceptance conditions. An independent outcome becomes a planned slice with a recorded order; only one plan runs at a time.
 
-For an independent request such as a new diagnostics screen, Codex creates a planned slice with a contract and recorded sequence. It keeps one active plan. If the addition conflicts with an earlier rule, Codex records needs_clarification, asks for the required decision and continues independent authorized work. An explicit cancellation is recorded as withdrawn with the user's decision; nothing is silently dropped.
+The saved request retains your complete relevant wording verbatim, including conditions, alongside Codex's interpretation, destination and decision. Inclusion in a plan does not mean implementation; completion requires linked conditions and evidence.
 
-After context compaction or in a fresh task, unresolved requests are read from repository files, even when no plan is active. The next task can recover the requirement, destination and next action without the previous chat.
+If the addition conflicts with an earlier requirement, Codex preserves the conflict and asks for the needed decision while continuing independent authorized work. If you explicitly cancel or replace a requirement, it keeps the original request and records your exact cancellation wording with the decision. These records are part of fresh-task recovery even when no plan is active.
 
 ## See what prevents closure
 
 ~~~text
-$project-os plan status
-~~~
-
-The agent runs plan status --require-ready before reporting readiness or suggesting publication. A blocked report starts with "NOT_READY: the outcome is not ready" and the missing acceptance, even when source tests and package checks passed.
-
-A useful response states what was implemented, what was verified and in which target, what remains for closure, which decisions or permissions are needed and where additions were routed. For example: source tests passed; the plan remains open because the remote migration and post-migration scenario are pending; the next step is inspecting the target schema. It must not call the whole feature complete.
-
-A deliberately source-only preparation plan may close without deployment when that was the agreed outcome. A required production migration cannot be relabelled as a following independent slice. A structural PASS does not prove live behavior.
-
-For example, a release ZIP is built and unit tests pass, but fresh-session addition/cancellation recovery has not been checked. The release remains NOT_READY. Run those checks on the isolated candidate before publication; publication is never a prerequisite for discovering whether the promised behavior works.
-
-## Run a Program for a multi-phase initiative
-
-Use a Program only when several plans need one shared contract. A long task by itself belongs in Standard mode.
-
-~~~text
-$project-os program start: migrate authentication across the API, workers, web and mobile without downtime
+$project-os Tell me what is complete, what remains and whether this outcome can be closed.
 ~~~
 
-Codex prepares a definition with an observable outcome, explicit authority, at least two phases, evidence requirements, cost boundaries, exclusions and exit conditions. The helper dry-runs the transition before `.agents/PROGRAM.md` is created. Starting a Program does not create a plan automatically.
+Codex checks conditions, evidence and unresolved requirements. Its report states what was implemented, what was verified and where, what prevents closure, which decisions are needed and the next action.
 
-Report current status without writing:
+For example, local tests pass but a required remote migration is pending. The outcome remains NOT_READY and the plan stays open. Moving that migration into another slice cannot make the original result complete. A deliberately source-only outcome can close without deployment when that was the agreed scope.
 
-~~~text
-$project-os program status
-~~~
-
-Close a Program only when no plan is active:
-
-~~~text
-$project-os program close completed
-$project-os program close stopped: the migration was replaced by a vendor-managed rollout
-~~~
-
-`completed` requires exit evidence. `stopped` requires a precise reason. Closure archives the exact contract with a SHA-256 digest and returns the repository to Standard.
-
-## Everyday findings and reusable lessons
-
-In a connected repository, ask Codex to implement, investigate or verify work normally. Codex should record the findings it discovers, preserve evidence and keep unresolved hypotheses distinct from confirmed mechanisms. You do not need a separate `finding add` request for every observation. Confirmed mechanisms can become project lessons; making them reusable and transferring them requires review and approval.
-
-Bounded repairs also save a finding for a reproduced defect already named by the user. Codex handles `finding record`, the checkpoint draft and its freshness check. A knowledge transfer that pauses for approval uses a small plan: the initial request and approval belong to the same contract and become implemented only after its gates are verified. After guarded completion, the idle checkpoint records the actual imported and skipped IDs, source preservation and next action. A captured request remains unresolved even if its decision text says completed. A structural check alone does not detect a checkpoint that was never updated.
-
-For a new project, open its repository in Codex and send one request:
-
-~~~text
-$project-os Reuse the useful failure lessons from /path/to/earlier-repository here. Set up Project OS if needed, prepare anything that is missing and bring over only lessons that fit this project.
-~~~
+The helper refuses closure for incomplete recorded requirements or proof. It cannot identify omitted prerequisites or validate evidence meaning. Structural PASS and checkpoint CURRENT do not prove production behavior, public availability or physical-device acceptance.
 
-Codex inspects the destination and the read-only source, prepares missing lessons from confirmed evidence, removes private context and checks applicability. It explains irrelevant or unconfirmed skips, presents one batch review of lesson changes and applies only the approved selection. It then validates the destination. Setup is previewed if the new repository is not yet connected. The source stays unchanged during transfer.
+<a id="everyday-findings-and-reusable-lessons"></a>
 
-See [Failure knowledge](../skills/project-os/references/knowledge.md) for the complete recipes, including approved libraries and portable bundles. The individual operations below are useful when you want direct control of a particular stage.
-
-## Advanced: record a particular finding and prepare a lesson
-
-The deterministic finding command accepts a temporary JSON file with title, status, impact, evidence paths and required_check. Use `--id` for an existing finding; fixed_unverified and verified also require resolution. Store real evidence in the repository before previewing:
-
-~~~shell
-python3 /absolute/path/to/project-os/scripts/project_os.py finding record --target /path/to/repository --input /private/tmp/finding.json --dry-run
-python3 /absolute/path/to/project-os/scripts/project_os.py finding record --target /path/to/repository --input /private/tmp/finding.json
-~~~
-
-If upgrade must rewrite a file used by an existing proof, Codex reviews an exact snapshot_evidence map with --finding-proof-review and preserves the old bytes atomically. The original finding then proves historical bytes through evidence_snapshots, not the upgraded file. Repeating the old finding input cannot silently approve current changed bytes; a separately reviewed --id update captures fresh evidence while retaining raw legacy values and archive files. See [Historical evidence snapshots](REFERENCE.md#historical-evidence-snapshots-during-upgrade).
-
-Save a reconciled compact checkpoint with `checkpoint --target /path/to/repository --draft /private/tmp/checkpoint.md`, previewing first with `--dry-run`. Run `checkpoint --target /path/to/repository --check --json` afterward and during fresh recovery. CURRENT verifies the saved body and referenced record hashes; it does not independently prove that the narrative or acceptance claims are complete. See [Maintenance](../skills/project-os/references/maintenance.md) for the draft fields and compatibility boundaries.
-
-Start with an observation, not an invented mechanism:
-
-~~~text
-$project-os finding add: returning from the native camera leaves the preview frozen on the affected iPhone
-~~~
-
-The finding records observed behavior, impact, available evidence and the next decisive check. It may contain hypotheses, but it must label them as unverified.
-
-After evidence confirms the mechanism, capture project knowledge:
-
-~~~text
-$project-os knowledge capture: FIND-012
-~~~
-
-The project lesson can retain local paths, repository names and evidence because it stays in the source repository. It should include applicability, trigger, mechanism, prevention, decisive verification and boundaries.
-
-Prepare reusable knowledge without writing:
-
-~~~text
-$project-os knowledge prepare: all
-~~~
+## Transfer lessons directly to a new repository
 
-Codex sanitizes the proposal by removing project names, credentials, personal data, absolute machine paths, URLs, deployment identifiers, evidence paths and copied product history. Review the proposal, then approve only entries that remain accurate and useful without the source project:
+Open the destination repository and send:
 
 ~~~text
-$project-os knowledge approve: /path/to/proposal.json all
+$project-os Reuse the useful failure lessons from /path/to/earlier-repository here. Prepare only lessons that fit this project, keep the source unchanged and show me one batch to review.
 ~~~
 
-Approval adds reviewed entries to the source repository's user-owned reusable library. It does not publish them, upload them or send them to the Project OS author.
+Codex inspects the destination and reads the source without changing it. It prefers approved reusable lessons. If the source has only confirmed findings or project lessons, it prepares sanitized proposals outside both repositories instead of requiring you to organize an intermediate command sequence.
 
-## Transfer lessons directly to a new repository
+The agent checks mechanisms, prevention, verification and boundaries against the destination. Titles and tags find candidates; they do not establish applicability. It explains exclusions and removes private context.
 
-When Codex can access both repositories on the same machine, open the destination repository and provide the source path:
+The plan saves the request, selection and pending approval. Codex presents one batch with proposed additions, their purpose, skips and conflicts. Review it, then reply:
 
 ~~~text
-$project-os knowledge import: /path/to/earlier-repository
+Approved - apply the proposed additions.
 ~~~
 
-The destination helper reads only the source reusable registry and its approved entries. The dry-run filters active lessons by declared applicability, considers lifecycle tombstones, explains skipped entries and previews target-local changes. The source repository does not change.
+You can approve a subset instead. Codex applies only the approved selection, validates the destination, checks repeated-import behavior and verifies source preservation. It records the approval and actual result, then closes the transfer through the guarded completion operation with a current checkpoint.
 
-Apply only the reviewed result, then run `$project-os check` in the destination. Destination-owned content wins on conflict and repeated imports are idempotent.
+A connected destination and accessible source usually need this request and batch approval. Missing setup permission, unavailable source files or conflicts may require separate decisions. One batch review does not waive those boundaries. An unconnected destination gets a setup preview before connection.
 
-This is the primary Codex path for moving verified failure knowledge between repositories you own. There is no background synchronization and no Project OS-managed shared database.
+Knowledge remains under your control. Transfer does not upload lessons to the Project OS author, create a shared database or enable background synchronization. Use [Reference](REFERENCE.md#user-owned-reusable-knowledge) for lifecycle and conflict rules.
 
 ## Transfer a portable bundle
 
-Use a bundle when the destination is on another machine or when ChatGPT is the companion interface.
+When repositories are on different machines, ask Codex to prepare a portable bundle of approved reusable lessons. It previews the export location outside the source repository and produces a checked bundle after the required approval.
 
-Export from the source repository:
+Supply the bundle and destination context to Codex or the ChatGPT companion. Ask which lessons fit, review the proposed batch and approve only those additions. The saved result should identify imported and skipped lessons, verification and the next action. A bundle does not carry permission to modify an unrelated project.
 
-~~~text
-$project-os knowledge export: /path/to/failure-knowledge.json
-~~~
-
-The helper previews first, then writes a deterministic JSON bundle containing approved reusable entries and complete lifecycle chains. Inspect the output location and SHA-256 before moving it.
-
-In the destination repository, import the supplied bundle:
-
-~~~text
-$project-os knowledge import: /path/to/failure-knowledge.json
-~~~
+## Upgrade Project OS
 
-Where the ChatGPT companion is available, attach the bundle and select the plugin:
+Update the selected installation using [Setup](SETUP.md#upgrade-to-230), then ask `$project-os upgrade` in each connected repository. Codex identifies the installed helper, previews changes, handles any ownership review and applies only the reviewed operation after authorization.
 
-~~~text
-@Engineering Project OS Help me reuse verified failure knowledge from an earlier project in this one.
-~~~
+The upgrade checks and saved checkpoint describe the actual result. Managed files, migration metadata and reviewed historical proof may change; application changes need their own authority. Conflicts stay pending. Do not simulate an upgrade by editing version or schema fields.
 
-ChatGPT works against the supplied bundle and project material. It cannot write to a live local checkout. Apply returned artifacts deliberately, then validate the real destination in Codex. GitHub marketplace installation applies to Codex; companion availability follows the separate [legacy Directory channel](SETUP.md#legacy-directory).
+<a id="compact-request-table"></a>
+<a id="open-and-checkpoint-a-long-task"></a>
+<a id="run-a-program-for-a-multi-phase-initiative"></a>
+<a id="advanced-record-a-particular-finding-and-prepare-a-lesson"></a>
 
-## Upgrade Project OS
+## When you want more control
 
-First update the selected GitHub plugin or standalone Codex skill using [Setup](SETUP.md), resolve duplicate installations and verify the helper version. Updating an installed copy does not update repository-local records. In each connected repository, start a new Codex task and request:
+Ask for a durable plan when an outcome spans sessions or needs explicit acceptance conditions. Standard mode is complete for normal work. Program is optional coordination for an explicitly authorized multi-phase initiative, not a prerequisite for a long task.
 
-~~~text
-$project-os upgrade
-~~~
+The [request catalog](REFERENCE.md#project-os-requests), [plan rules](REFERENCE.md#contracts-intake-and-guarded-completion), [Program contract](REFERENCE.md#standard-and-program) and [helper syntax](REFERENCE.md#helper-summary) cover direct controls. They are available when useful, not steps you must memorize for every repair or transfer.
 
-Codex uses the installed helper to inspect the current release, dry-run the upgrade, review conflicts, apply the same clean operation and run `check`. For the schema-preserving 2.2.4 upgrade, application code and project-owned knowledge must not change.
+## ChatGPT companion boundaries
 
-If a managed file has diverged from its recorded baseline, the helper reports a conflict instead of overwriting it. Resolve ownership deliberately and repeat the dry-run. Do not hand-edit `SYSTEM.release` or schema fields to simulate an upgrade.
+Select `@Engineering Project OS` for explanations, supplied project files and portable bundles. Reviewing an existing setup requires the relevant files. Changed copies remain chat artifacts until you deliberately apply them to the real checkout and validate in Codex.
 
-## ChatGPT companion boundaries
+With a runnable selected helper and permission to execute it, ChatGPT can check the supplied copy and return a validated snapshot. That snapshot must preserve hidden files and the whole checkpoint receipt, use freshly read file bytes and pass checks after the actual archive is reconstructed. A text report alone is not the returned artifact.
 
-ChatGPT can explain the system without files. It can advise on setup from a project description, inspect supplied Project OS records and work with a portable knowledge bundle.
+The agent keeps your original scoped instructions verbatim beside its interpretation, including conditions and later cancellation wording. For returned files, it inventories the actual source tree before copying and includes promised nested proposals and reports. The bundled snapshot utility can check that byte-preserving archive when execution is permitted; it does not run project checks or establish acceptance. See [complete byte snapshots](REFERENCE.md#complete-byte-snapshots).
 
-If a request asks about an existing repository and the required files are not attached, ChatGPT must ask for them. It must not inspect an empty host workspace or present a generic audit as Project OS output.
+If execution is unavailable or forbidden, ChatGPT can review readable files provisionally. It must distinguish recorded claims from checks performed now, preserve pending acceptance and leave integrity, freshness and readiness checks unverified. It must not change records, create a receipt or close a plan through this fallback. A missing helper or a genuinely older helper is reported without silently choosing a different installed copy.
 
-Use Codex for the full repository-native workflow: current Git state, applicable instructions, deterministic helper operations, exact diffs and repository checks.
+When generic file operations are allowed, ChatGPT may return a byte-preserving transport copy with actual file hashes and the full STATE receipt. That proves only the stated byte checks; it is not a helper-validated Project OS export. If reading or creating an actual downloadable file is unavailable, the response must state the limitation. Detailed capability routes are in [Reference](REFERENCE.md#interfaces).
 
 ## Safety rules
 
-- A clear `do not change files` constraint keeps the whole request read-only.
-- Ambiguous mutation requests require one focused clarification before writing.
-- Every helper mutation uses the same reviewed dry-run and apply arguments.
-- Project OS authority never implies permission to edit application code, install dependencies, delete data, commit, push, deploy, publish or contact external services.
-- A passing helper check proves Project OS structural consistency, not the truth of product claims or external evidence.
+An explicit read-only request stays read-only. Project OS does not grant permission to install dependencies, delete data, commit, push, deploy, publish or contact external systems. Necessary decisions remain yours; recording and checking the already authorized work belongs to the agent.