From 06a8bbd26b004a99c084e28b3b8a7113d0fae588 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=E1=BB=93=20Kh=E1=BA=AFc=20Huy?= <256174233+builtbyhuy@users.noreply.github.com> Date: Mon, 10 Aug 2026 19:42:04 +0700 Subject: [PATCH] docs: prepare maintainer validation --- docs/evidence/application-readiness.md | 18 +-- docs/evidence/maintainer-validation.csv | 3 + docs/evidence/maintainer-validation.md | 109 ++++++++++++++++++ .../plans/2026-08-10-codex-plugin-check.md | 2 +- 4 files changed, 123 insertions(+), 9 deletions(-) create mode 100644 docs/evidence/maintainer-validation.csv create mode 100644 docs/evidence/maintainer-validation.md diff --git a/docs/evidence/application-readiness.md b/docs/evidence/application-readiness.md index e4b0917..7fd2f14 100644 --- a/docs/evidence/application-readiness.md +++ b/docs/evidence/application-readiness.md @@ -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 diff --git a/docs/evidence/maintainer-validation.csv b/docs/evidence/maintainer-validation.csv new file mode 100644 index 0000000..2e9e5aa --- /dev/null +++ b/docs/evidence/maintainer-validation.csv @@ -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 diff --git a/docs/evidence/maintainer-validation.md b/docs/evidence/maintainer-validation.md new file mode 100644 index 0000000..e15e9ae --- /dev/null +++ b/docs/evidence/maintainer-validation.md @@ -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. diff --git a/docs/superpowers/plans/2026-08-10-codex-plugin-check.md b/docs/superpowers/plans/2026-08-10-codex-plugin-check.md index dc782a1..8781486 100644 --- a/docs/superpowers/plans/2026-08-10-codex-plugin-check.md +++ b/docs/superpowers/plans/2026-08-10-codex-plugin-check.md @@ -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.