From 8d9ff4856775ecb71319a24a2333c939869fa93a Mon Sep 17 00:00:00 2001 From: john-the-dev <52230987+john-the-dev@users.noreply.github.com> Date: Mon, 31 Aug 2026 02:47:42 -0700 Subject: [PATCH 1/2] docs: state the maintainer bot as planned, and point at the 48 unrated MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README's differentiator paragraph, its architecture diagram, CONTRIBUTING, and GRADING all describe an automated maintainer in the present tense. It does not exist: scripts/ holds build, lib and validate; the only workflow is validate.yml (pull_request + push, never scheduled); all 13 commits are human; there is no bot config. The 11 A grades came from one hand-written commit. Meanwhile 48 of 59 entries are grade: unrated, which the README's own "continuously-maintained, quality-graded" claim invites a visitor to check. Two things get fixed by saying so plainly: - The claim becomes true, and stays true whether or not the bot is built. Every edit is phrased as "planned, not yet running" rather than removed, so nothing here forecloses building it. - The 48 unrated stop being someone else's job. GRADING.md told a reader the bot would grade them, which is exactly the sentence that stops a contributor from doing it. README now names them as the good first contribution, with the rubric and the command that lists them. Validated: `node scripts/validate.mjs` -> 59 entries valid, 48 warnings, rc=0, identical with these docs and with the originals (docs are not validator input; run from a path without spaces — lib.mjs:66 does not decode %20). Co-Authored-By: Claude Opus 5 (1M context) --- CONTRIBUTING.md | 4 ++-- GRADING.md | 4 ++-- README.md | 8 +++++--- 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c0dc4d3..fcfb7bb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,6 +18,6 @@ Thanks for helping keep AI-agent engineering knowledge accurate and fresh. - **Lessons are public-only.** `category: lessons` entries must come from famous, publicly-documented projects/post-mortems. Never include private, proprietary, or non-public project details (anyone's). - **Primary sources first** — official docs / papers / release notes over secondhand blogs. -## The maintainer bot +## The maintainer bot (planned) -An automated maintainer (Sutando) also opens PRs — proposing new entries from the latest releases/research and flagging entries whose `last_verified` is >90 days old. Bot PRs are reviewed and merged by a human, same as any other. +An automated maintainer that proposes new entries and flags entries whose `last_verified` is >90 days old is planned but **not running yet**. Until it exists, both jobs are human: `scripts/validate.mjs` warns on every `unrated` entry, and stale ones are found by the same rubric a bot would apply. Bot PRs, when they arrive, will be reviewed and merged by a human like any other. diff --git a/GRADING.md b/GRADING.md index 0cca5c0..5f010b6 100644 --- a/GRADING.md +++ b/GRADING.md @@ -10,7 +10,7 @@ Grades exist so "bad tech" and "outdated knowledge" are **evidence-based, not op | **B** | Solid and useful, with caveats. Maintained but niche, or accurate-but-aging, or best-for-specific-cases. Note the caveat in `evidence`. | | **C** | Use with caution. Slowing maintenance, partial adoption, known rough edges, or partially superseded. | | **D** | Discouraged. Deprecated, abandoned, superseded, or carrying unresolved security/correctness issues. Kept for the historical record and to warn readers — set `status: deprecated` (or `superseded`) and fill `superseded_by`. | -| **unrated** | Seeded or newly-added, not yet evidence-graded. The maintainer bot grades these on its next pass. | +| **unrated** | Seeded or newly-added, not yet evidence-graded. `scripts/validate.mjs` warns on each one; grading them is open contribution work. | ## Signals (what `evidence` should cite) @@ -35,4 +35,4 @@ Each `evidence` item should be a dated, checkable statement, e.g.: ## Staleness -An entry is **stale** when `last_verified` is more than **90 days** old. The maintainer bot flags stale entries in a `review-needed` PR; a human (or the bot with evidence) re-verifies and updates `last_verified` + `grade`. +An entry is **stale** when `last_verified` is more than **90 days** old. Re-verify it and update `last_verified` + `grade` with fresh evidence. (Automated flagging is planned; today this is a manual check — as of the last measurement no entry was over 90 days.) diff --git a/README.md b/README.md index a692219..f6cd669 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ A continuously-maintained, **quality-graded** knowledge base of AI-agent engineering — frameworks, orchestration, evaluation, memory, tools, protocols, security, and research. -Most "awesome" lists rot: agent tooling ships breaking changes monthly, and stale entries mislead more than they help. This repo's differentiator is **freshness + grading**: every entry carries a `status`, a `last_verified` date, and an evidence-backed `grade`, and an automated maintainer bot proposes additions and flags stale entries for review. +Most "awesome" lists rot: agent tooling ships breaking changes monthly, and stale entries mislead more than they help. This repo's differentiator is **freshness + grading**: every entry carries a `status`, a `last_verified` date, and an evidence-backed `grade`. An automated maintainer that proposes additions and flags stale entries is planned, not yet running — grading is done by maintainers and contributors today. It's **dual-use**: - **Human-browsable** — one markdown file per entry under [`entries/`](entries/). @@ -23,7 +23,7 @@ It's CC BY 4.0: any surface using this content must visibly credit **The Agent L ``` entries/*.md ──build──▶ dist/kb.json ──ingest──▶ agent-loop.xyz RAG ▲ - └── humans (PRs) + Sutando maintainer-bot (auto-PRs new entries, flags stale) + └── humans (PRs) [maintainer-bot: planned, not yet running] ``` ## Entry format @@ -55,7 +55,9 @@ Entries are graded **A/B/C/D** on an evidence-based rubric (see [`GRADING.md`](G ## Contributing -PRs welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md). CI validates every entry against the schema + rubric. The maintainer bot opens PRs too; humans review and merge. +PRs welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md). CI validates every entry against the schema + rubric. + +**Good first contribution:** 48 of 59 entries are `grade: unrated`. `scripts/validate.mjs` names every one of them, and [`GRADING.md`](GRADING.md) is the rubric. One entry, graded with dated evidence, is a complete and useful PR. ## Status From 8ed44e6bebd72c12c0e0249c54b51b3608afc1fc Mon Sep 17 00:00:00 2001 From: john-the-dev <52230987+john-the-dev@users.noreply.github.com> Date: Mon, 31 Aug 2026 03:20:12 -0700 Subject: [PATCH 2/2] docs(readme): don't hardcode the unrated count in the contribution CTA MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit "48 of 59 entries are grade: unrated" was true when written and false by the time this branch was pushed — #21 grades 58 of 59, and it was already open. A number whose truth depends on which of two open PRs merges first should not be in the README at all. The CTA now points at what validate.mjs reports rather than a snapshot of it, and names re-grading as equally welcome — which is the contribution surface that survives #21 landing. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f6cd669..9763d90 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,7 @@ Entries are graded **A/B/C/D** on an evidence-based rubric (see [`GRADING.md`](G PRs welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md). CI validates every entry against the schema + rubric. -**Good first contribution:** 48 of 59 entries are `grade: unrated`. `scripts/validate.mjs` names every one of them, and [`GRADING.md`](GRADING.md) is the rubric. One entry, graded with dated evidence, is a complete and useful PR. +**Good first contribution:** any entry `scripts/validate.mjs` still flags as `grade: unrated`, or any entry whose `evidence` you can strengthen — or contradict — with a dated, checkable source. [`GRADING.md`](GRADING.md) is the rubric, and re-grading against it counts as much as first-grading. One entry, evidenced, is a complete and useful PR. ## Status