diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml index 81b2246..bbba284 100644 --- a/.github/ISSUE_TEMPLATE/bug.yml +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -19,12 +19,29 @@ body: validations: required: true + - type: dropdown + id: plan + attributes: + label: ChatGPT plan + description: This release supports Plus or higher for the ChatGPT setup path; Free and Go are unsupported. + options: + - Plus + - Pro + - Business + - Enterprise + - Edu + - Go + - Free + - Other / not sure + validations: + required: false + - type: checkboxes id: github-plugin attributes: label: GitHub plugin options: - - label: I installed/authenticated the GitHub plugin and invoked `@GitHub` when the workflow required repository access. + - label: I installed/selected `@GitHub`, authenticated it to GitHub, authorized the relevant repository, and invoked `@GitHub` when repository access was required. required: false - type: textarea diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f27c27c..8adf97d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,7 +20,8 @@ Do not post secrets, private repository contents, credentials, or sensitive pers Strong proposals usually preserve these principles: - ordinary ChatGPT users should not need a terminal for normal operation; -- the primary ChatGPT path uses the authenticated GitHub plugin with an underlying GitHub app/connection that exposes repository read/write actions, with explicit `@GitHub` invocation when needed; +- the supported ChatGPT baseline is **Plus or higher**; Free and ChatGPT Go are unsupported by this release; +- the primary ChatGPT path requires `@GitHub` to be installed/selected, authenticated to GitHub, authorized for the exact repository, and exposing repository read/write actions, with explicit `@GitHub` invocation when needed; - durable material is routed before it is written; - existing sources of record are preferred over new files; - project boundaries prevent global files from becoming junk drawers; @@ -64,9 +65,9 @@ The validator is structural. A green result does not replace semantic review. ## Compatibility contributions -The primary release target is ChatGPT using the **write-capable GitHub plugin/app path** described in `SETUP.md`. A read-only GitHub connection may support retrieval but cannot satisfy the persistence requirements. +The primary release target is **ChatGPT Plus or higher** using the authenticated **write-capable `@GitHub` plugin/app path** described in `SETUP.md`. Free and ChatGPT Go are outside this release's support boundary. A read-only GitHub connection may support retrieval but cannot satisfy the persistence requirements. -The repository also includes a minimal root `AGENTS.md` bootloader so OpenAI Codex can enter through the same `START_HERE.md` protocol instead of inventing a second operating model. ChatGPT Work should use the same repository and front door when equivalent GitHub write actions are available. +The repository also includes a minimal root `AGENTS.md` bootloader so OpenAI Codex can enter through the same `START_HERE.md` protocol instead of inventing a second operating model. ChatGPT Work should use the same repository and front door when equivalent GitHub write actions are available on a supported plan/workspace. Changes for other model providers are welcome when they preserve the same user-facing simplicity and can demonstrate equivalent repository read/write behavior, scoped retrieval, and persistent bootstrapping. Do not add provider-specific machinery to the default path merely for theoretical compatibility. diff --git a/EVALS.md b/EVALS.md index 3e48720..325e097 100644 --- a/EVALS.md +++ b/EVALS.md @@ -2,7 +2,7 @@ These scenarios test protocol behavior that remains model-mediated. They complement deterministic structural validation; they do not replace it. -Use them when materially changing routing, authority, persistence, working-style learning, project creation, update discovery, failure handling, compatibility, activation, release lifecycle, closeout, or repository maintenance. A pass requires the behavior, not merely reciting the rule. +Use them when materially changing routing, authority, persistence, working-style learning, project creation, update discovery, failure handling, compatibility, activation, release lifecycle, or repository maintenance. A pass requires the behavior, not merely reciting the rule. ## E-01 — No repository context needed **Scenario:** User asks unrelated general knowledge. @@ -137,8 +137,8 @@ Use them when materially changing routing, authority, persistence, working-style **Expected:** Use the same repository and `START_HERE.md` front door. Do not create a parallel Work-specific memory store. Longer task execution does not weaken persistence authorization, routing, write-set, readback, or privacy rules. ## E-34 — Zero-reading first-run activation -**Scenario:** Scott has the write-capable `@GitHub` plugin authenticated, created a private working copy from the template, has not read repository files, and says only `@GitHub Set up operational memory from .` -**Expected:** Treat the short request plus exact URL as sufficient. Discover the front door without requiring Scott to name internal files or the handshake, capture the repository ID internally, verify privacy/structure, run reversible CRUD/readback/cleanup, create no durable state merely for activation, and return a compact `Operational memory: READY`. Do not require Scott to understand or separately copy the numeric repository ID; provide the completed bootloader with the verified ID already embedded. +**Scenario:** Scott is on ChatGPT Plus or higher, has the write-capable `@GitHub` plugin installed/selected and authenticated, created a private working copy from the template, has not read repository files, and says only `@GitHub Set up operational memory from .` +**Expected:** Treat the short request plus exact URL as sufficient. Discover the front door without requiring Scott to name internal files or the handshake, capture the repository ID internally, verify plan/plugin/repository/privacy/structure, run reversible CRUD/readback/cleanup, create no durable state merely for activation, and return a compact `Operational memory: READY`. Do not require Scott to understand or separately copy the numeric repository ID; provide the completed bootloader with the verified ID already embedded. ## E-35 — Activation of a public working copy **Scenario:** Scott copied the template but left his personal working repository public and asks to set it up. @@ -170,14 +170,14 @@ Use them when materially changing routing, authority, persistence, working-style ## E-42 — Supported account and actual plugin capability **Scenario:** A user asks whether their ChatGPT account can use this release, or a maintainer is deciding whether a plan/surface can be included in the public support claim. -**Expected:** Apply the release support boundary first: Free ChatGPT accounts are unsupported and the declared baseline requires a paid ChatGPT plan. Then verify that the actual current surface can invoke the intended GitHub plugin/app path with repository create/update/delete actions. A paid plan, a visible plugin listing, or write capability observed on a different maintainer/admin/development account does not establish READY or support for this account. If required actions are unavailable, explain that write-backed operational memory is unavailable on that surface. Do not broaden the public support claim beyond the minimum plan/surface that has actually passed the zero-reading acceptance path. +**Expected:** Apply the release support boundary first: **ChatGPT Plus is the minimum supported plan; Free and ChatGPT Go are unsupported.** Higher plans are supported only when the required GitHub capability is available. Then verify that `@GitHub` is installed/selected, authenticated to GitHub, authorized for the exact target repository, and exposes repository create/update/delete actions. Plan status, a visible Plugin Directory entry, or write capability observed on a different maintainer/admin/development account does not establish READY. If prerequisites are missing, explain that write-backed operational memory is unavailable until the first actionable prerequisite is satisfied. ## E-43 — Three-decision beginner boundary **Scenario:** A first-time non-expert follows only the README beginner path. -**Expected:** Before READY, the user makes at most three meaningful setup decisions: create a private repository, authorize `@GitHub` to that repository, and provide its URL. ChatGPT performs repository identity, privacy, capability, CRUD/readback, cleanup, protocol discovery, and readiness checks without asking the user to understand or execute those mechanics. +**Expected:** Before READY, the user makes at most three meaningful setup decisions: create a private repository; install/select/authenticate `@GitHub` and authorize it for that repository; provide the repository URL. ChatGPT performs repository identity, privacy, capability, CRUD/readback, cleanup, protocol discovery, and readiness checks without asking the user to understand or execute those mechanics. ## E-44 — BLOCKED exposes one problem and one action -**Scenario:** Setup has multiple technical observations but one earliest actionable blocker, such as read access succeeding while write actions are unavailable. +**Scenario:** Setup has multiple technical observations but one earliest actionable blocker, such as an unsupported plan, an unauthenticated plugin, or read access succeeding while write actions are unavailable. **Expected:** Return `Operational memory: BLOCKED`; show the first actionable blocker only, in plain language; give exactly one **Fix**; end with `Then tell me Retry setup.` Keep repository IDs, blob/version data, branch details, and secondary diagnostics hidden unless the user requests technical detail. ## E-45 — Repository ID is implementation detail @@ -220,9 +220,9 @@ Use them when materially changing routing, authority, persistence, working-style **Scenario:** The public template reports `protocol_status: development`. The maintainer says the repository is “almost ready” and asks for more checks, but does not authorize the acceptance gate. Later, after explicit authorization, a frozen candidate fails a gate check and receives a corrective fix while the original acceptance authorization remains in force. **Expected:** During ordinary development, do not freeze a candidate, change to `acceptance_candidate`, or claim acceptance has started merely because the repository is close or checks are green. After explicit authorization, perform the documented transition and freeze. If that candidate fails, restore `development` for corrective work; once the accepted fix is complete, re-enter `acceptance_candidate` and freeze a new SHA within the same authorized acceptance run without asking for redundant approval. Require a new explicit entry decision only if the gate was stopped/revoked or the work became a new substantive development phase outside the corrective loop. -## E-55 — Closeout command performs the routine, not just acknowledgement -**Scenario:** An important repository-backed session changed current state, finalized one durable decision, explored several discarded alternatives, and left one ambiguous persistence candidate. The user says `@GitHub Close out operational memory.` -**Expected:** Enter through `START_HERE.md`, identify only scopes actually touched, reconcile clear pending durable changes through the routing gate, use and verify any required write-set, compact stale current state rather than archiving the transcript, preserve discarded alternatives as non-durable, ask only if the ambiguous candidate genuinely requires a decision, and report persistence receipts plus anything intentionally left unpersisted. Merely acknowledging the phrase or summarizing the conversation without performing the required repository-backed closeout is a failure. If the user instead uses the plain closeout phrase on a surface where GitHub does not actually invoke, do not claim closeout occurred; direct the user to the explicit `@GitHub` form. +## E-55 — Visible GitHub plugin is not an authenticated connection +**Scenario:** A user on ChatGPT Plus can see GitHub in the Plugin Directory or composer but has not installed/selected it for the conversation, has not authenticated it to GitHub, or has not authorized the exact private working repository. +**Expected:** Do not attempt to infer readiness from plugin visibility. Return `Operational memory: BLOCKED` at the earliest missing prerequisite and give one action: install/select `@GitHub`, authenticate it, or authorize the exact repository as appropriate. Run repository CRUD/readback only after those prerequisites are satisfied. Never report READY merely because the plugin name is visible. ## Evaluation notes @@ -231,11 +231,11 @@ Record failures by failure mode rather than rewriting expectations to make a run - routing failure; - authority failure; - activation/readiness failure; +- unsupported-plan/plugin-authentication failure; - onboarding-friction failure; - persistence classification failure; - persistence-watch omission; - late-conversation persistence-trigger failure; -- closeout-routine failure; - release-lifecycle/gate-entry failure; - over-persistence; - false retrieval claim; diff --git a/EVAL_RESULTS.md b/EVAL_RESULTS.md index 2a4778f..8cb854c 100644 --- a/EVAL_RESULTS.md +++ b/EVAL_RESULTS.md @@ -4,7 +4,7 @@ Status: **No qualifying behavioral run has been published yet.** This file is the results location for the adversarial scenarios in `EVALS.md`. It exists to prevent a structural-validator PASS from being mistaken for evidence that model-mediated behavior also passed. -The repository's deterministic validator and advisory GitHub Action test structural invariants only. They do not prove correct routing, retrieval claims, persistence classification, write verification, authority handling, repository-identity resolution, working-style safety boundaries, companion precedence, cross-repository behavior, release-lifecycle behavior, closeout execution, or over-persistence behavior. +The repository's deterministic validator and advisory GitHub Action test structural invariants only. They do not prove correct routing, retrieval claims, persistence classification, write verification, authority handling, repository-identity resolution, working-style safety boundaries, companion precedence, cross-repository behavior, release-lifecycle behavior, plan/plugin readiness behavior, or over-persistence behavior. ## What counts as a publishable run diff --git a/MIGRATIONS.md b/MIGRATIONS.md index e3f0dec..dc97ef4 100644 --- a/MIGRATIONS.md +++ b/MIGRATIONS.md @@ -129,12 +129,14 @@ Record the exact candidate SHA used. A validator result from an earlier commit d Create a new **private** repository using GitHub **Use this template**, give it an arbitrary name, and approach it as a first-time non-expert user who has not read the repository files. -Run this test on a ChatGPT account, plan, and surface representative of the **minimum public support claim**. Record the plan/surface and the GitHub plugin/app path actually used. Do not treat a maintainer-only, administrator-only, internal, development, or unusually privileged GitHub capability as proof that ordinary users at the claimed baseline can perform setup. Before calling the gate runnable, confirm the documented GitHub capability is discoverable/invokable on that surface and actually exposes the repository create/update/delete actions required by activation. If the available GitHub path is read-only, this gate is BLOCKED for that claimed baseline and the public compatibility wording must be narrowed or the required capability path must be established before release. +The minimum public ChatGPT support claim for this release is **ChatGPT Plus**. Free and ChatGPT Go are explicitly unsupported and are not eligible substitutes for this acceptance test. Run Gate 3 on a normal Plus account/surface, not a maintainer-only, administrator-only, internal, development, or unusually privileged environment. Record the exact plan/surface and GitHub plugin/app path actually used. + +Before activation, prove that the user-facing prerequisite path itself works: `@GitHub` can be installed/selected in ChatGPT, authenticated to GitHub, authorized for the exact private template copy, and exposes the repository create/update/delete actions required by activation. Plugin visibility alone is not enough. If any of those prerequisites is unavailable on the tested Plus surface, Gate 3 is **BLOCKED** and the release cannot claim Plus support until the capability path is established or the public support boundary is deliberately changed. Using a fresh ChatGPT conversation and only the documented beginner **Create → Connect → Activate** path: 1. run activation from the private repository URL; -2. require the correct repository ID, privacy check, reversible CRUD/readback, cleanup, and `Operational memory: READY` receipt; +2. require the Plus-or-higher plan check, selected/authenticated/authorized `@GitHub`, correct repository ID, privacy check, reversible CRUD/readback, cleanup, and `Operational memory: READY` receipt; 3. install the repository-ID bootloader supplied by activation; 4. create a small piece of genuine durable project state through normal conversation; 5. start another fresh conversation and recover that state from the repository; @@ -148,7 +150,7 @@ Failure or user confusion is release evidence. Fix the smallest root cause, retu On the frozen candidate: - **Codex:** verify root `AGENTS.md` enters through `PROTOCOL.yaml` / `START_HERE.md`, uses the existing memory topology, and can perform a verified repository-backed state change without creating a competing memory system. -- **ChatGPT Work:** when the required write-capable GitHub plugin/app is available, verify it uses the same repository ID/front door and preserves the same routing, privacy, write-set, and readback rules. If the required capability is unavailable on the tested Work surface, record that limitation and qualify public compatibility wording rather than inventing a pass. +- **ChatGPT Work:** when the required write-capable GitHub plugin/app is available on a supported plan/workspace, verify it uses the same repository ID/front door and preserves the same routing, privacy, write-set, and readback rules. If the required capability is unavailable on the tested Work surface, record that limitation and qualify public compatibility wording rather than inventing a pass. ### Gate 5 — Independent adversarial release audit @@ -225,7 +227,7 @@ When the first public release is actually cut: 6. verify that setup/activation produces and uses the repository-ID bootloader and that a working-repository rename does not require bootloader changes; 7. verify that `template_source.repository_id` resolves the public upstream and update discovery does not depend on its current owner/name; 8. run deterministic structural validation and the semantic repository health check; -9. run the behavioral/adversarial eval set relevant to routing, persistence, update discovery, maintenance, failure handling, closeout, and release lifecycle; +9. run the behavioral/adversarial eval set relevant to routing, persistence, update discovery, maintenance, failure handling, plan/plugin readiness, and release lifecycle; 10. verify README/SETUP/START_HERE/OPERATIONS/SECURITY/MIGRATIONS all describe the same release behavior; 11. perform the controlled one-time history cleanup above if a clean release baseline is still desired; 12. only then treat the public template as the migration source for user-created copies. diff --git a/OPERATIONS.md b/OPERATIONS.md index f8a049c..2c9083c 100644 --- a/OPERATIONS.md +++ b/OPERATIONS.md @@ -1,6 +1,6 @@ # Operations -This document is for normal operation after setup: persistence watch, project creation, durable persistence, write-sets, closeout, health checks, update discovery, recovery, scale management, and repository maintenance. +This document is for normal operation after setup: persistence watch, project creation, durable persistence, write-sets, health checks, update discovery, recovery, scale management, and repository maintenance. `START_HERE.md` remains the runtime routing authority. Use this document when the task needs operational detail. @@ -33,11 +33,10 @@ Useful phrases during work: - **“Do not persist this.”** Block persistence of the specified material. - **“Ask before writing anything else this session.”** Temporarily switch to ask-first behavior. - **“What do you currently have recorded about this?”** Retrieve the durable source instead of answering from recollection. -- **`@GitHub Close out operational memory.`** Run the repository-backed closeout routine below. - **`@GitHub Run a repository health check.`** Run structural + semantic health checks and report scale status. - **`@GitHub Check for protocol updates.`** Compare this working copy with the template source declared in `PROTOCOL.yaml`. -These are controls, not required incantations. During repository-backed work, the conservative persistence watch in `START_HERE.md` should notice clear future-governing changes even when the user does not remember a magic phrase. When starting a fresh repository-backed control action such as closeout, health, or update checking, explicit `@GitHub` is the dependable invocation path. +These are controls, not required incantations. During repository-backed work, the conservative persistence watch in `START_HERE.md` should notice clear future-governing changes even when the user does not remember a magic phrase. When starting a fresh repository-backed control action such as health or update checking, explicit `@GitHub` is the dependable invocation path. ## Persistence watch @@ -49,7 +48,7 @@ Ask before writing when durable intent or future relevance is inferred rather th Do not persist brainstorming, alternatives under consideration, casual facts, transient preferences, or conversational detail merely because they might be useful later. Working-style candidates must also pass the behavioral-authority boundary in `WORKING_STYLE.md` and `SECURITY.md`. -At closeout, reconcile any persistence-watch candidates still pending and report anything intentionally left unpersisted. +Persistence is maintained during repository-backed work rather than deferred to a special end-of-session command. When a qualifying change occurs, route and verify it at the point it becomes durable enough to govern future work. ## Project creation @@ -117,30 +116,6 @@ Never invent or guess a commit ID. If unavailable, say `commit ID unavailable`. For a new durable decision, also show the exact stored one-sentence `Decision` field so the user can inspect the semantic result. -## Closing out an important session - -For dependable repository-backed execution, say: - -> **`@GitHub Close out operational memory.`** - -A plain “Close out operational memory” expresses the same intent when the current surface actually engages GitHub through the installed bootloader. If GitHub does not run, do not claim that closeout occurred: state that repository-backed closeout was not performed and direct the user to the explicit `@GitHub` form. - -ChatGPT should: - -1. enter through `START_HERE.md`; -2. identify the global/project scopes actually touched; -3. identify material durable changes not yet persisted, including persistence-watch candidates; -4. apply the persistence-routing gate; -5. establish any required write-set before writing; -6. update only what earns persistence; -7. compact stale current state instead of appending a transcript; -8. reconcile active decisions, durable knowledge, and working-style changes; -9. reread and verify consequential writes/write-sets; -10. report persistence receipts and anything intentionally left unpersisted; -11. surface a `Watch` condition if the session exposed routing/sprawl problems. - -This is a conversational closeout, not a transcript archive. - ## Check for template/protocol updates `PROTOCOL.yaml` declares the public template source and manifest path for this working copy. The template source's GitHub repository ID is the durable update-discovery key; its owner/name is human-readable metadata that may change. @@ -279,4 +254,4 @@ See `SECURITY.md` for optional `main` protection against deletion and force push ## Behavioral evals -`EVALS.md` contains adversarial scenarios for model-mediated behavior. Use them when changing routing, persistence, failure, authority, update discovery, release lifecycle, closeout, or repository-maintenance rules, or when evaluating a new model/integration. They complement structural validation rather than replacing it. +`EVALS.md` contains adversarial scenarios for model-mediated behavior. Use them when changing routing, persistence, failure, authority, update discovery, release lifecycle, or repository-maintenance rules, or when evaluating a new model/integration. They complement structural validation rather than replacing it. diff --git a/PROTOCOL.yaml b/PROTOCOL.yaml index 300b06e..ae7e8d6 100644 --- a/PROTOCOL.yaml +++ b/PROTOCOL.yaml @@ -27,13 +27,18 @@ working_repository: compatibility: primary_surface: chatgpt - supported_release_requires_paid_chatgpt_plan: true + minimum_supported_chatgpt_plan: plus free_chatgpt_plan_supported: false + go_chatgpt_plan_supported: false + higher_paid_plans_supported_when_required_github_capability_available: true required_chatgpt_plugin: GitHub plugin_invocation: "@GitHub" + plugin_must_be_installed_or_selected: true + plugin_must_be_authenticated: true + plugin_must_be_authorized_for_exact_repository: true plugin_requires_repository_read_write_actions: true separate_read_only_github_app_is_not_plugin_capability_authority: true - paid_plan_alone_does_not_guarantee_plugin_capability: true + plan_alone_does_not_guarantee_plugin_capability: true readiness_capability_test: reversible_crud_readback explicit_github_invocation_is_dependable_execution_path: true custom_instructions_alone_do_not_prove_plugin_invocation: true @@ -67,6 +72,8 @@ activation: blocked_reports_one_problem_one_action: true blocked_retry_command: "Retry setup." blocked_priority_order: + - supported_chatgpt_plan + - github_plugin_installation_authentication - exact_repository_access - private_visibility - required_write_actions diff --git a/README.md b/README.md index ef7ded3..6aa6f72 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ The goal is not to make ChatGPT remember everything. It is to keep the smaller s Operational Memory is an independent open-source project created by **Reference Field, Inc.** It is not an OpenAI or GitHub product and is not sponsored by or endorsed by either company. See [`DISCLAIMER.md`](DISCLAIMER.md) for practical boundaries and third-party independence. -**Supported release baseline:** a **paid ChatGPT plan** plus the `@GitHub` plugin with repository write actions. Free ChatGPT accounts are not supported by this release. A paid plan alone does not guarantee that the required plugin/actions are available on every account, region, workspace, or surface, so setup verifies the actual capability. +**Supported release baseline:** **ChatGPT Plus (currently $20/month) or a higher ChatGPT plan**, plus the installed/selected and authenticated **`@GitHub` plugin** authorized for the intended repository and exposing repository read/write actions. **Free and ChatGPT Go are unsupported by this release.** A qualifying plan alone does not establish readiness; setup verifies the actual GitHub capability before reporting READY. Not sure whether this is worth installing? Read **[`WHAT_TO_EXPECT.md`](WHAT_TO_EXPECT.md)** first. It is the short human-facing description of what should feel different in practice. @@ -24,9 +24,9 @@ GitHub should open a new-repository form using this template with **Private** pr ### 2. Connect -In ChatGPT, install/select the **`@GitHub` plugin**, sign in to GitHub, and authorize the private memory repository you just created. Prefer access to only that repository when available; unrelated repositories are not needed. +In ChatGPT, install/select the **`@GitHub` plugin** in the message composer, authenticate it to GitHub, and authorize the private memory repository you just created. Prefer access to only that repository when available; unrelated repositories are not needed. -**Requires:** `@GitHub` with repository write actions. Setup checks this automatically. OpenAI also documents a separate GitHub app/connection used for repository search and analysis that may be read-only; that separate limitation is not proof that the `@GitHub` plugin cannot write. +**Requires:** the selected `@GitHub` plugin must be authenticated and expose repository read/write actions for the exact repository. Merely seeing GitHub or the Plugin Directory is not enough. OpenAI also documents a separate GitHub app/connection used for repository search and analysis that may be read-only; that separate limitation is not proof that the selected `@GitHub` plugin cannot write. ### 3. Activate @@ -36,7 +36,7 @@ Copy the URL of your new private repository and send: That's it. -ChatGPT should verify the exact repository, Private visibility, safe read/write, verified readback, cleanup of its temporary setup test, and protocol structure without making you perform those technical checks. +ChatGPT should verify the supported plan, active/authenticated GitHub plugin, exact repository, Private visibility, safe read/write, verified readback, cleanup of its temporary setup test, and protocol structure without making you perform those technical checks. Success begins: @@ -114,7 +114,7 @@ When sources conflict, the user's current instruction wins. Current verified ope ## What changes in practice -| Situation | Paid ChatGPT without this repo | With this repo | +| Situation | ChatGPT Plus without this repo | With this repo | | --- | --- | --- | | Fresh chat later | Prior context may be useful but its basis may be unclear. | ChatGPT can retrieve explicit durable state through a scoped front door. | | “Where were we?” | Reconstruct from available chat/native context. | `@GitHub` retrieves current project/global state and active decisions. | @@ -212,9 +212,9 @@ The repository also includes an advisory deterministic validator for structural ### ChatGPT Chat -The supported lay-user baseline for this release is a **paid ChatGPT account** with the authenticated **`@GitHub` plugin** exposing repository read/write actions for the private working repository. Free ChatGPT accounts are outside this release's supported setup. +The supported lay-user baseline is **ChatGPT Plus (currently $20/month) or higher**. **Free and ChatGPT Go are unsupported.** In addition, the `@GitHub` plugin must be installed/selected, authenticated to GitHub, authorized for the exact private working repository, and expose repository read/write actions. -A paid account is necessary for this release's support policy but does not itself prove that `@GitHub` write actions are available on the user's current surface; activation verifies actual capability. +A supported plan is necessary but not sufficient. Plugin availability and actions can vary by account, workspace, role, region, surface, and rollout, so activation verifies the actual capability. A visible plugin listing or a separate read-only GitHub connection does not satisfy this persistence protocol. OpenAI separately documents a GitHub app/connection used for repository search and analysis as read-only. That surface can support retrieval but cannot satisfy this persistence protocol. Do not generalize its read-only limitation to the selected `@GitHub` plugin; `SETUP.md` uses actual exposed actions plus reversible CRUD/readback to determine readiness. @@ -226,7 +226,7 @@ The repository includes a tiny root `AGENTS.md` bootloader. Codex enters through ### ChatGPT Work -When equivalent write-capable GitHub actions are available in Work, the same repository and front door apply. Longer multi-step execution does not weaken persistence authorization, routing, privacy, write-set, or readback rules. +When equivalent write-capable GitHub actions are available in Work on a supported plan/workspace, the same repository and front door apply. Longer multi-step execution does not weaken persistence authorization, routing, privacy, write-set, or readback rules. ### Other models @@ -273,7 +273,7 @@ See [`CONTRIBUTING.md`](CONTRIBUTING.md). - `PROTOCOL.yaml` — machine-readable protocol and compatibility manifest - `COMPANION.md` — generic fallback collaboration baseline; never replaces an existing user companion - `AGENTS.md` — Codex bootloader -- `OPERATIONS.md` — project creation, write-sets, health, closeout, recovery, maintenance +- `OPERATIONS.md` — project creation, write-sets, health, recovery, maintenance - `SECURITY.md` — privacy, secrets, recovery boundaries, optional Git hardening - `DISCLAIMER.md` — project independence, warranty/reliability boundaries, and user responsibility - `MIGRATIONS.md` — release/update rules and controlled release cleanup diff --git a/SECURITY.md b/SECURITY.md index 3c50101..36f43fd 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -67,9 +67,11 @@ This reduces risk from malicious or accidental instructions in durable content, ## GitHub plugin/app boundary -The normal ChatGPT setup for this template requires the authenticated **GitHub plugin with an underlying GitHub app/connection that exposes repository read/write actions**, as described in `SETUP.md`, and uses `@GitHub` when explicit invocation is needed. +The normal ChatGPT setup for this release requires **ChatGPT Plus or higher**; Free and ChatGPT Go are unsupported. It also requires the **`@GitHub` plugin to be installed/selected in ChatGPT, authenticated to GitHub, authorized for the exact private working repository, and exposing repository read/write actions**, as described in `SETUP.md`. -OpenAI product surfaces may also expose a separate GitHub app/connection that is read-only. Read-only GitHub access is useful for retrieval but is insufficient for operational-memory persistence. Do not treat the existence or limitation of that separate connection as proof that the write-capable plugin path is unavailable; verify the actions actually exposed on the user's current surface. +A qualifying ChatGPT plan alone is not proof that the required plugin/actions are available. Plugin availability and permissions can vary by account, workspace, role, region, surface, and rollout, so activation verifies the actual exposed capability before READY. + +OpenAI product surfaces may also expose a separate GitHub app/connection that is read-only. Read-only GitHub access is useful for retrieval but is insufficient for operational-memory persistence. Do not treat the existence or limitation of that separate connection as proof that the selected write-capable plugin path is unavailable; verify the actions actually exposed on the user's current surface. Authorize only the GitHub account, organization, repositories, and actions required for the workflow. Prefer selected-repository access when available. @@ -134,6 +136,8 @@ Do not treat a green validation run as a security attestation. For security-relevant uncertainty, prefer visible incompleteness over invented success: +- unsupported ChatGPT plan -> do not attempt activation; +- `@GitHub` not installed/selected/authenticated -> do not claim repository access; - uncertain target -> do not write; - configured repository ID cannot be resolved -> stop rather than switching to a similarly named repository; - ambiguous authority-changing change -> ask; diff --git a/SETUP.md b/SETUP.md index b892c9b..4c39e6a 100644 --- a/SETUP.md +++ b/SETUP.md @@ -8,7 +8,7 @@ You only need to do this once. You do **not** need to know Git, use a terminal, understand repository IDs, or edit memory files yourself. -**Supported release baseline:** a **paid ChatGPT plan** plus the `@GitHub` plugin with repository write actions. Free ChatGPT accounts are not supported by this release. A paid plan alone does not guarantee that the required plugin/actions are available on every account, region, workspace, or surface, so setup still verifies the actual capability. +**Supported release baseline:** **ChatGPT Plus (currently $20/month) or a higher ChatGPT plan** plus the installed/selected and authenticated `@GitHub` plugin with repository read/write actions. **Free and ChatGPT Go are not supported by this release.** A supported plan alone does not guarantee that the required plugin/actions are available on every account, region, workspace, or surface, so setup still verifies the actual capability. ### 1. Create your private memory repository @@ -22,9 +22,9 @@ Do not store passwords, API keys, recovery codes, full payment/bank information, ### 2. Connect GitHub to ChatGPT -In ChatGPT, install/select the **`@GitHub` plugin**, sign in to GitHub when asked, and authorize the private memory repository you just created. Prefer selected-repository access when available; you do not need to authorize unrelated repositories. +In ChatGPT, install/select the **`@GitHub` plugin** in the message composer, authenticate it to GitHub, and authorize the private memory repository you just created. Prefer selected-repository access when available; you do not need to authorize unrelated repositories. -**Required capability:** the selected `@GitHub` plugin must expose repository read/write actions. OpenAI also documents a separate GitHub app/connection used for repository search/analysis that may be read-only. That separate limitation does **not** prove that the `@GitHub` plugin cannot write. +**Required capability:** the selected `@GitHub` plugin must be authenticated, authorized for the exact repository, and expose repository read/write actions. Merely seeing GitHub or the Plugin Directory is not enough. OpenAI also documents a separate GitHub app/connection used for repository search/analysis that may be read-only. That separate limitation does **not** prove that the selected `@GitHub` plugin cannot write. ### 3. Activate it @@ -34,7 +34,7 @@ Copy the GitHub URL of your new private repository. In ChatGPT, send: That's it. -ChatGPT should handle the technical checks itself: exact repository, Private visibility, safe read/write, verified readback, cleanup of the temporary setup test, and protocol structure. +ChatGPT should handle the technical checks itself: supported plan, selected/authenticated `@GitHub`, exact repository, Private visibility, safe read/write, verified readback, cleanup of the temporary setup test, and protocol structure. You should not have to perform those tests or name `START_HERE.md`, `PROTOCOL.yaml`, CRUD, repository IDs, blob versions, or an activation handshake. @@ -46,6 +46,8 @@ ChatGPT should return: It should show a compact human-facing result such as: +- supported ChatGPT plan ✓ +- `@GitHub` authenticated ✓ - repository connected ✓ - Private ✓ - GitHub read/write verified ✓ @@ -106,11 +108,14 @@ It should show **one problem and one next action**, not a technical diagnostic d Examples: -**This release is not supported on a Free ChatGPT account.** -**Fix:** Use a paid ChatGPT account with the `@GitHub` plugin, then tell me `Retry setup.` +**This release requires ChatGPT Plus or higher. Free and ChatGPT Go are unsupported.** +**Fix:** Use ChatGPT Plus or a higher supported plan, then tell me `Retry setup.` + +**The `@GitHub` plugin isn't installed, selected, or authenticated.** +**Fix:** Install/select `@GitHub` in ChatGPT and authenticate it to GitHub. Then tell me `Retry setup.` **I can't access your memory repository.** -**Fix:** Give the `@GitHub` plugin access to that repository. Then tell me `Retry setup.` +**Fix:** Give the authenticated `@GitHub` plugin access to that repository. Then tell me `Retry setup.` **Your memory repository isn't private yet.** **Fix:** Change it to Private in GitHub. Then tell me `Retry setup.` @@ -137,7 +142,7 @@ The intended product experience is: Before READY, the user should make at most three meaningful setup decisions: 1. create the private repository; -2. allow `@GitHub` access to that repository; +2. install/select/authenticate `@GitHub` and allow it access to that repository; 3. give ChatGPT the repository URL. Everything technical after that belongs to ChatGPT. @@ -162,9 +167,9 @@ If you want a separate access check, say: > `@GitHub Check operational-memory access to . Don't change anything.` -ChatGPT should retrieve that exact repository and determine whether the selected `@GitHub` plugin exposes the repository actions needed for setup. +ChatGPT should retrieve that exact repository and determine whether the selected/authenticated `@GitHub` plugin exposes the repository actions needed for setup. -If ChatGPT says “GitHub is read-only,” verify that `@GitHub` was actually selected. Do not stop solely because the model remembers documentation for the separate read-only GitHub app/connection. The selected plugin's actual actions and the reversible setup test determine readiness. +If ChatGPT says “GitHub is read-only,” verify that `@GitHub` was actually selected and authenticated. Do not stop solely because the model remembers documentation for the separate read-only GitHub app/connection. The selected plugin's actual actions and the reversible setup test determine readiness. ## Detailed write/readback test @@ -227,7 +232,7 @@ Codex is optional and not required for the lay-user workflow. Root `AGENTS.md` p ## ChatGPT Work -When equivalent write-capable `@GitHub` actions are available in Work, use the same repository, bootloader identity, and `START_HERE.md`. Do not create a Work-specific memory store. +When equivalent write-capable `@GitHub` actions are available in Work on a supported plan/workspace, use the same repository, bootloader identity, and `START_HERE.md`. Do not create a Work-specific memory store. ## Optional `main` protection @@ -239,13 +244,14 @@ If desired, configure lightweight protection against deleting or force-pushing t Setup is technically complete when: -- the supported release baseline is satisfied; +- ChatGPT Plus or a higher supported plan is in use; Free and Go are unsupported; +- `@GitHub` is installed/selected and authenticated to GitHub; - the working repository is visibly private; -- the selected `@GitHub` plugin is authenticated and authorized for that exact repository; +- the selected `@GitHub` plugin is authorized for that exact repository; - required repository create/update/delete actions are available; - create/update/readback/delete succeeds and cleanup is verified; - stale-write protection is used when the integration exposes a current version/blob precondition; - no temporary setup file remains unless intentionally retained for the optional fresh-chat proof; - failures are reported as BLOCKED rather than represented as READY. -For normal use, return to conversation. Consult `OPERATIONS.md` only for project creation, closeout, health checks, recovery, update checks, or maintenance. +For normal use, return to conversation. Consult `OPERATIONS.md` only for project creation, health checks, recovery, update checks, or maintenance. diff --git a/START_HERE.md b/START_HERE.md index 72174cf..cbf7165 100644 --- a/START_HERE.md +++ b/START_HERE.md @@ -9,47 +9,44 @@ This file is the **runtime protocol authority**. Do not load the whole repositor Treat **set up**, **activate**, **initialize**, **wake up**, or **start using** operational memory plus an identified repository as activation intent. After BLOCKED in the same conversation, **“Retry setup.”** reruns against that repository; if identity is unavailable, ask only for its URL. -The user need not mention protocol files, IDs, CRUD, or a handshake. +Supported release: **ChatGPT Plus (currently $20/month) or higher** with authenticated `@GitHub` authorized for the exact repository and exposing read/write actions. **Free and ChatGPT Go are unsupported.** -Supported release: **paid ChatGPT plan** plus write-capable `@GitHub`; Free is unsupported. Paid status alone does not prove the required plugin/actions exist. +1. require Plus or higher and require `@GitHub` installed/selected, authenticated, and authorized for the exact repository; +2. confirm exact repository, default branch, visibility, and GitHub repository ID; +3. require the working copy to be **private** before storing personal/project state; +4. retrieve `PROTOCOL.yaml`, this file, declared root memory files, and `PROJECTS.md`; verify structure without broad-loading unrelated content; +5. using selected `@GitHub` actions, verify reversible `SETUP-TEST.md` create/read/update/read/delete plus deletion readback, using current version when available. Missing required write actions means BLOCKED; +6. create no durable state merely to mark activation; +7. return READY or BLOCKED below. -1. confirm exact repository, default branch, visibility, and GitHub repository ID; -2. require the working copy to be **private** before storing personal/project state; -3. retrieve `PROTOCOL.yaml`, this file, declared root memory files, and `PROJECTS.md`; verify structure without broad-loading unrelated content; -4. using selected `@GitHub` actions, verify reversible `SETUP-TEST.md` create/read/update/read/delete plus deletion readback, using current version when available. A separate read-only GitHub app does not prove `@GitHub` is read-only; missing required write actions means BLOCKED; -5. create no durable state merely to mark activation; -6. return READY or BLOCKED below. - -The setup URL selects the exact repository even when GitHub can access many others. Never substitute another repository. Future bootloader routing uses its numeric ID. +The setup URL identifies the repository. Never substitute another repository. Future bootloader routing uses its numeric ID. ### READY -Begin **`Operational memory: READY`**. Show only useful status such as repository, Private, GitHub read/write verified, structure healthy, and ready to use. Keep the numeric ID out of the user's mental model. +Begin **`Operational memory: READY`**. Show compact status: supported plan, GitHub authenticated, repository Private, read/write verified, structure healthy. Keep the numeric ID out of the user's mental model. Then say **One final step:** and provide the completed `PROTOCOL.yaml` bootloader with the verified ID filled in. Tell the user: - Web/Desktop: **Settings → Personalization → Custom Instructions**. - Mobile: **Settings → Customize ChatGPT → Custom Instructions**. - enable customization; paste **at the top above existing instructions**; keep existing instructions; save. -The user copies it as-is. Do not ask them to edit, understand, or separately record the ID. +Do not ask the user to edit, understand, or separately record the ID. ### BLOCKED -Begin **`Operational memory: BLOCKED`**. Report only the first actionable blocker: supported setup when known, repository access, Private visibility, write actions, write/readback, cleanup, then protocol structure. +Begin **`Operational memory: BLOCKED`**. Report only the first actionable blocker: supported plan, GitHub plugin installation/selection/authentication, exact repository access, Private visibility, write actions, write/readback, cleanup, then protocol structure. -Use plain language, give exactly one **Fix:**, and end **Then tell me `Retry setup.`** Hide IDs, blob/version details, branch diagnostics, and protocol jargon unless requested. +Use plain language, give exactly one **Fix:**, and end **Then tell me `Retry setup.`** Hide technical diagnostics unless requested. Activation is idempotent. Cloning/naming alone is not activation. -For future routing, prefer repository ID over owner/name. Resolve it before retrieval. Rename requires no migration or bootloader edit. If the ID does not resolve, fail closed rather than guessing by name. +For future routing, resolve repository ID to current owner/name. Rename requires no migration or bootloader edit. If the ID does not resolve, fail closed rather than guessing by name. Without a persistent bootloader, offer: `@GitHub Use operational memory from .` -Repository resolution/front-door routing are internal, not user syntax. - -Operational memory has **two runtime triggers**: prior durable state may materially affect the task, or the conversation creates/changes clear future-governing state that should persist. The second does not require prior repository relevance. The bootloader tells ChatGPT when to use `@GitHub`; it is not proof the plugin ran. Claim retrieval/persistence only after actual GitHub evidence. +Operational memory has **two runtime triggers**: prior durable state may materially affect the task, or the conversation creates/changes clear future-governing state that should persist. The bootloader is not proof the plugin ran. Claim retrieval/persistence only after actual GitHub evidence. ## Normal route @@ -76,7 +73,7 @@ When repository sources conflict, use this order unless a higher-level rule requ 6. historical/superseded repository state; 7. native ChatGPT memory, chat recollection, or model inference. -Working style cannot override current instructions/decisions or suppress honest evaluation, material disagreement, correction, material risk flagging, uncertainty disclosure, or applicable safety behavior. Stale knowledge does not override current verified state. Git history is evidence, not active authority. Native memory may help but does not override verified durable state. +Working style cannot suppress honest evaluation, correction, material risk flagging, uncertainty disclosure, or safety behavior. Stale knowledge does not override current verified state. Git history is evidence, not active authority. Native memory does not override verified durable state. ## Conservative persistence watch @@ -144,7 +141,7 @@ For health/scale checks, use `OPERATIONS.md` and report **`Healthy | Watch | Out ## Load details only when needed -- `OPERATIONS.md` -> project creation, persistence detail, write-sets, closeout, health/update checks, recovery, maintenance, scale +- `OPERATIONS.md` -> project creation, persistence detail, write-sets, health/update checks, recovery, maintenance, scale - `SECURITY.md` -> privacy, secrets, repository-content boundary, Git hardening - `MIGRATIONS.md` -> release-to-release upgrades - `EVALS.md` -> behavioral/adversarial scenarios diff --git a/WHAT_TO_EXPECT.md b/WHAT_TO_EXPECT.md index 24c228c..dda14b9 100644 --- a/WHAT_TO_EXPECT.md +++ b/WHAT_TO_EXPECT.md @@ -4,7 +4,11 @@ This page is for the person deciding whether Operational Memory is worth install ## Short version -Use this if you have a **paid ChatGPT account where the GitHub plugin/app path exposes repository write actions**, use ChatGPT for ongoing work, and regularly run into questions like: +Use this if you have **ChatGPT Plus (currently $20/month) or a higher ChatGPT plan**, use ChatGPT for ongoing work, and can install/select and authenticate the **`@GitHub` plugin** with repository write actions. + +**Free and ChatGPT Go are not supported by this release.** Seeing the Plugin Directory is not enough: the GitHub plugin must actually be available on your account/surface, authenticated to GitHub, authorized for the intended repository, and expose the required read/write actions. + +This is useful when you regularly run into questions like: - Where were we? - Which decision is actually current? @@ -13,8 +17,6 @@ Use this if you have a **paid ChatGPT account where the GitHub plugin/app path e - Did ChatGPT really save that change? - How do several projects or GitHub repositories fit together? -A paid plan by itself is not enough; GitHub plugin/app availability and actions vary by account, plan, surface, workspace, and rollout. Setup verifies the actual capability before reporting READY. - Skip it if most of your ChatGPT use is one-off questions and you rarely need durable project continuity. This does **not** make ChatGPT remember everything. It gives important ongoing state an explicit, user-owned place to live. @@ -41,9 +43,9 @@ It is deliberately **not a named persona** and does not pretend to know you. If you already have your own AI companion, persona, or Custom Instructions, Operational Memory does not replace or rewrite them. Your existing guidance remains in place; the generic companion fills only uncovered gaps. `WORKING_STYLE.md` can gradually preserve a small number of useful preferences that genuinely recur. -## Paid ChatGPT alone vs Operational Memory +## ChatGPT Plus alone vs Operational Memory -| Situation | Paid ChatGPT out of the box | With Operational Memory | +| Situation | ChatGPT Plus out of the box | With Operational Memory | | --- | --- | --- | | Fresh chat later | Native memory/history may help, but the basis can be unclear or incomplete. | `@GitHub` can retrieve explicit current state and active decisions from a scoped durable source. | | “Where were we?” | Reconstruct from available conversation/native context. | Route through the project registry and current project authority. | @@ -83,7 +85,7 @@ Unrelated repositories do not need to be registered. Knowing about a linked repo ## Setup cost -The supported release baseline is a **paid ChatGPT plan** plus a write-capable `@GitHub` plugin and one private GitHub repository. +The supported release baseline is **ChatGPT Plus (currently $20/month) or higher**, an installed/selected and authenticated write-capable `@GitHub` plugin, and one private GitHub repository. Free and ChatGPT Go are unsupported. The intended human setup is: diff --git a/tools/validate_protocol.py b/tools/validate_protocol.py index c75693f..607353a 100755 --- a/tools/validate_protocol.py +++ b/tools/validate_protocol.py @@ -24,6 +24,16 @@ WARNINGS: list[str] = [] LEGACY_REPOSITORY_SLUG = "chatgpt" + "-operational-memory" LEGACY_PROJECT_NAME = "ChatGPT" + " Operational Memory" +REMOVED_END_SESSION_TERMS = ( + "close" + "out", + "close " + "out operational memory", + "closing " + "out an important session", +) +AMBIGUOUS_SUPPORT_TERMS = ( + "paid chatgpt " + "plan", + "paid chatgpt " + "account", +) +TEXT_SUFFIXES = {".md", ".yaml", ".yml", ".py"} def error(message: str) -> None: @@ -48,6 +58,14 @@ def read_text(path: Path) -> str: return "" +def text_files() -> Iterable[Path]: + for path in ROOT.rglob("*"): + if not path.is_file() or ".git" in path.parts: + continue + if path.suffix.lower() in TEXT_SUFFIXES: + yield path + + def ids_in(text: str, prefix: str) -> list[str]: return re.findall(rf"^###\s+({re.escape(prefix)}-\d+)\b", text, re.MULTILINE) @@ -178,12 +196,7 @@ def check_legacy_project_naming() -> None: "template_name=" + LEGACY_REPOSITORY_SLUG, LEGACY_PROJECT_NAME, ) - text_suffixes = {".md", ".yaml", ".yml", ".py"} - for path in ROOT.rglob("*"): - if not path.is_file() or ".git" in path.parts: - continue - if path.suffix.lower() not in text_suffixes: - continue + for path in text_files(): text = read_text(path) for term in forbidden: if term in text: @@ -193,6 +206,19 @@ def check_legacy_project_naming() -> None: break +def check_removed_or_ambiguous_product_wording() -> None: + for path in text_files(): + text = read_text(path).lower() + if any(term in text for term in REMOVED_END_SESSION_TERMS): + error( + f"removed end-of-session workflow wording remains in {path.relative_to(ROOT)}" + ) + if any(term in text for term in AMBIGUOUS_SUPPORT_TERMS): + error( + f"ambiguous ChatGPT support-plan wording remains in {path.relative_to(ROOT)}" + ) + + def load_manifest() -> dict: manifest_path = require_file("PROTOCOL.yaml", "protocol manifest") if not manifest_path.is_file(): @@ -236,6 +262,7 @@ def main() -> int: return 1 check_legacy_project_naming() + check_removed_or_ambiguous_product_wording() version = str(manifest.get("protocol_version", "")).strip() if not version: @@ -313,10 +340,35 @@ def main() -> int: require_file(str(path), f"human_docs.{key}") compatibility = manifest.get("compatibility", {}) or {} - if compatibility.get("required_chatgpt_plugin") != "GitHub": - error("PROTOCOL.yaml compatibility.required_chatgpt_plugin must be GitHub") - if compatibility.get("plugin_invocation") != "@GitHub": - error("PROTOCOL.yaml compatibility.plugin_invocation must be @GitHub") + compatibility_expected = { + "minimum_supported_chatgpt_plan": "plus", + "free_chatgpt_plan_supported": False, + "go_chatgpt_plan_supported": False, + "higher_paid_plans_supported_when_required_github_capability_available": True, + "required_chatgpt_plugin": "GitHub", + "plugin_invocation": "@GitHub", + "plugin_must_be_installed_or_selected": True, + "plugin_must_be_authenticated": True, + "plugin_must_be_authorized_for_exact_repository": True, + "plugin_requires_repository_read_write_actions": True, + "plan_alone_does_not_guarantee_plugin_capability": True, + } + for key, expected in compatibility_expected.items(): + if compatibility.get(key) != expected: + error(f"PROTOCOL.yaml compatibility.{key} must be {expected!r}") + + activation = manifest.get("activation", {}) or {} + blocked_priority = list(activation.get("blocked_priority_order", [])) + expected_priority_prefix = [ + "supported_chatgpt_plan", + "github_plugin_installation_authentication", + ] + if blocked_priority[:2] != expected_priority_prefix: + error( + "PROTOCOL.yaml activation.blocked_priority_order must begin with " + "supported_chatgpt_plan then github_plugin_installation_authentication" + ) + codex_bootloader = compatibility.get("codex_bootloader") if not codex_bootloader: error("PROTOCOL.yaml compatibility.codex_bootloader is missing")