Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 18 additions & 1 deletion .github/ISSUE_TEMPLATE/bug.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 4 additions & 3 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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.

Expand Down
20 changes: 10 additions & 10 deletions EVALS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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 <URL>.`
**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 <URL>.`
**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.
Expand Down Expand 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
Expand Down Expand Up @@ -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

Expand All @@ -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;
Expand Down
2 changes: 1 addition & 1 deletion EVAL_RESULTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
10 changes: 6 additions & 4 deletions MIGRATIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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

Expand Down Expand Up @@ -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.
Expand Down
Loading