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
18 changes: 10 additions & 8 deletions docs/evidence/application-readiness.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,14 +47,16 @@ Submit only after all are observed:
every version/API incompatibility, with no unexplained tool error.
2. The repository is public with a signed-off `v0.1.0` release, public CI and
reproducible evidence links.
3. At least three unrelated plugin repositories retain the check in their
default-branch workflow.
4. The retained integrations remain green across two consecutive Codex release
updates, or one catches a real regression that an upstream maintainer accepts
or independently reproduces.
5. At least 60 days of public maintenance evidence exists, including issue
triage, review of an external contribution, and two release decisions.
6. Every application claim fits one of the public links in this directory; no
3. At least ten unrelated plugin repositories retain the check in public
default-branch workflows.
4. The retained integrations cover two consecutive Codex release updates and
catch at least one real Codex upgrade regression.
5. At least one separate public upstream issue is accepted or independently
reproduced by its maintainer.
6. At least 60 days of public maintenance evidence exists, including issue
triage, review of an external contribution, and two feedback-driven release
decisions.
7. Every application claim fits one of the public links in this directory; no
stars, downloads, adoption or maintainer duty is inferred from local work.

## Exact form payload still required
Expand Down
3 changes: 3 additions & 0 deletions docs/evidence/maintainer-validation.csv
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
repository,maintainer,public_workflow,contact_route,sent_at,receipt_url,ran_at,unknown_defect,retained_required_ci,response_url,status
https://github.com/bitrouter/bitrouter,@bitrouter,https://github.com/bitrouter/bitrouter/blob/main/.github/workflows/ci.yml,https://github.com/bitrouter/bitrouter/discussions,,,,,,,READY_AFTER_PUBLIC_RELEASE
https://github.com/Cassette-Editor/oh-my-cassette,@Cassette-Editor,https://github.com/Cassette-Editor/oh-my-cassette/blob/main/.github/workflows/ci.yml,https://github.com/Cassette-Editor/oh-my-cassette/discussions,,,,,,,READY_AFTER_PUBLIC_RELEASE
109 changes: 109 additions & 0 deletions docs/evidence/maintainer-validation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
# Maintainer validation ledger

## Decision

`HOLD — 0 contacts, 0 independent runs, 0 retained workflows, 0 unknown
defects`. The technical fixture matrix is complete, but no maintainer has been
contacted and no external outcome exists. A prepared row is not a send, reply,
run, integration, adoption signal, or endorsement.

The machine-readable ledger is
[`maintainer-validation.csv`](maintainer-validation.csv). Blank outcome fields
mean unobserved, not false or unsuccessful.

Repository activity, workflow, and contact-route evidence was checked on
`2026-08-10` from the repositories' own README/contribution files and GitHub
metadata. Re-check each route immediately before any send.

## Qualified first cohort

The initial cohort contains only repositories with both an active public CI
workflow and a project-owned public route that explicitly accommodates this
kind of discussion. Contact remains blocked until the public `v0.1.0` release
and immutable evidence asset exist.

| Repository | Existing public workflow | Maintainer route | Status |
| --- | --- | --- | --- |
| [`bitrouter/bitrouter`](https://github.com/bitrouter/bitrouter) | [`CI`](https://github.com/bitrouter/bitrouter/blob/main/.github/workflows/ci.yml) | [Discussions](https://github.com/bitrouter/bitrouter/discussions) | `READY_AFTER_PUBLIC_RELEASE` |
| [`Cassette-Editor/oh-my-cassette`](https://github.com/Cassette-Editor/oh-my-cassette) | [`CI`](https://github.com/Cassette-Editor/oh-my-cassette/blob/main/.github/workflows/ci.yml) | [Discussions](https://github.com/Cassette-Editor/oh-my-cassette/discussions) | `READY_AFTER_PUBLIC_RELEASE` |

`bitrouter` also publishes a project email for open-source builders and
integrations, but Discussions is the preferred first contact because it keeps
the request and any reply publicly linkable. `oh-my-cassette` explicitly
routes questions, sharing, and plans to Discussions while reserving Issues for
bugs and feature requests.

## Screened but not in the first cohort

| Repository | Verdict | Reason and safe boundary |
| --- | --- | --- |
| [`mostlyharmless-ai/watercooler`](https://github.com/mostlyharmless-ai/watercooler) | `NEEDS_CARE` | Contributions are welcome, but no generic testing request is invited. Contact only with a repository-specific receipt or small proposed PR after reading its contribution guide. |
| [`commercetools/commercetools-ai-plugins`](https://github.com/commercetools/commercetools-ai-plugins) | `SKIP` | Issues and Discussions are disabled; the product support route is not appropriate for unsolicited validation. |
| [`agentis-tools/ctx`](https://github.com/agentis-tools/ctx) | `NEEDS_CARE` | Contribution-first route only; prepare a concrete result or patch before opening an Issue. |
| [`agentmail-to/agentmail-plugins`](https://github.com/agentmail-to/agentmail-plugins) | `NEEDS_CARE` | Issues are open, but no project contact or tool-testing invitation was found. Use only for a reproduced compatibility defect. |
| [`ujjwalredd/sarathi`](https://github.com/ujjwalredd/sarathi) | `NEEDS_CARE` | No contribution or tool-testing invitation was found. Use only for a direct Sarathi defect or patch. |
| [`sofus-nl/cc-plugin-codex`](https://github.com/sofus-nl/cc-plugin-codex) | `NEEDS_CARE` | No contribution or testing route beyond Issues. Contact only with a reproducible receipt or bounded PR offer. |
| [`RMI/speedy-skills`](https://github.com/RMI/speedy-skills) | `NEEDS_CARE` | Its tested `example-minimal` fixture is explicitly temporary. Any future proposal must target a retained plugin and follow the contribution process. |
| [`roadrunner-tuff/roadrunner-admin-plugin`](https://github.com/roadrunner-tuff/roadrunner-admin-plugin) | `NEEDS_CARE` | Preview scaffold with tenant-dependent capability. Contact only with a no-auth, no-tenant reproduction and concrete patch. |

No promotional Issue should be opened in any `NEEDS_CARE` repository. A later
row may be added only when the request has a repository-specific public
workflow target, maintainer route, and concrete evidence payload.

## Exact first-contact payload

Replace every bracketed field and re-check the target project's current
contact guidance immediately before sending. Send at most one public message
per repository.

```text
Hi — I maintain Codex Plugin Check, an experimental GitHub Action that asks a
released Codex binary what it discovered from one local plugin checkout. It
does not call a model or intentionally execute plugin hooks, MCP servers, apps,
or authentication flows.

I tested [REPOSITORY] at [FULL_COMMIT_SHA] using [PREPARATION: DIRECT, or the
exact disclosed static adapter] in a network-denied Linux matrix against Codex
0.147.0 and 0.146.1. That private test passed, but it is not an endorsement and
does not prove runtime behavior or adoption.

Would you be open to running the pinned v0.1.0 check in a branch or PR and
sharing the sanitized receipt? The exact workflow, release, evidence, and
limitations are here: [PUBLIC_RELEASE_URL]. If this is not useful for your
maintenance workflow, no action is needed.
```

The repository-specific message must include the exact tested commit from the
[public fixture matrix](public-fixture-matrix.md), the immutable release URL,
the exact `DIRECT` or adapter preparation, and a full-SHA Action pin. The
`oh-my-cassette` message must say that `STATIC_ADAPTER:local-source-v1` changed
only `/plugins/0/source` from its immutable expected input to the audited local
source form; it must not imply that the original manifest was probed unchanged.
Do not use a floating branch or tag in the proposed workflow.

## Evidence accounting

- Record `sent_at` only after observing the public message URL.
- Record `response_url` only for a maintainer-authored public response.
- Record `ran_at` and `receipt_url` only from a public external workflow or a
maintainer-provided sanitized receipt.
- Set `retained_required_ci` only when the check remains in the repository's
default branch and is required by its actual CI policy.
- Record `unknown_defect` only for a previously unknown checker or Codex defect
that the maintainer reproduces or that has a public accepted issue.
- Never infer adoption from a star, clone, artifact download, green local run,
sent message, or polite reply.

After 20 qualified sends, continue product investment only with at least three
independent runs, at least two retained required-CI integrations, and at least
one credible previously unknown defect. Otherwise record `NO-BUILD` for
further investment while leaving the useful open-source artifact available.

## Application boundary

The Codex for Open Source application remains `HOLD`. This ledger cannot clear
that gate until the stricter public maintenance requirements in
[`application-readiness.md`](application-readiness.md) are also met: ten public
downstream workflows, two feedback-driven releases, a caught Codex upgrade
regression, a separately accepted or reproduced upstream issue, and public
triage/review over the required maintenance period.
2 changes: 1 addition & 1 deletion docs/superpowers/plans/2026-08-10-codex-plugin-check.md
Original file line number Diff line number Diff line change
Expand Up @@ -552,7 +552,7 @@ missing row.
- Application readiness records only public, linkable evidence and keeps
`HOLD` until every market and maintenance gate in the specification passes.

- [ ] **Step 1: Create the evidence ledger and exact outreach payload**
- [x] **Step 1: Create the evidence ledger and exact outreach payload**

Populate at most 20 repositories from the previously audited bespoke-workflow
pool. Each row must bind to a public workflow and a public maintainer route.
Expand Down