diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c0dc4d3..f680396 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,6 +18,8 @@ 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 +## Automation -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. +CI validates the schema and rubric on every PR; `node scripts/validate.mjs` runs the same checks locally and lists every `unrated` entry and every entry past the 90-day staleness bar. + +There is **no bot proposing or grading entries** — grading requires independent sources a human has actually read, which is the whole point of the rubric. If that changes, this section changes with it. diff --git a/GRADING.md b/GRADING.md index 0cca5c0..c428652 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. Nothing grades these automatically — an unrated entry is an open task, and `scripts/validate.mjs` lists them all. | ## 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. `scripts/validate.mjs` flags them; a human re-verifies and updates `last_verified` + `grade`. diff --git a/README.md b/README.md index a692219..0ce32db 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`, and every entry is graded by a human against a published rubric. It's **dual-use**: - **Human-browsable** — one markdown file per entry under [`entries/`](entries/). @@ -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. + +**The best first contribution is grading an `unrated` entry.** 48 of 59 entries are `unrated` today — `node scripts/validate.mjs` names every one of them. Pick one, find the independent sources the rubric asks for, and open a PR with `grade` + `evidence[]` filled in. ## Status