Kjell Tore Guttormsen
720850a9ad
Measured this build against a documentation brief for public repos. The five original checks covered roughly one of its ten sections, so this adds what a single repo can answer on its own. New: required README headings per class (Non-goals is the cheapest trust-builder there is), in-repo version consistency across manifest / badge / CHANGELOG / tag, badge honesty, boilerplate, licence-claim, and relative links. Findings now carry a BUCKET beside the level - broken / missing / weakening - and output is grouped by it, because that is the order the work gets done in. Traits are a second axis beside class: class is structural and readable off the catalog, a trait says what the code does. `security` attaches SECURITY.md and a Known limitations section. The two names carrying it are proposed, not measured - that list is the operator's. Solo-maintained settles a category: CONTRIBUTING, CODE_OF_CONDUCT and MAINTAINERS are required by no class. Consumer-facing documents are untouched by that; SECURITY.md exists for the stranger who finds a hole. Three bugs found by running against llm-security, not by reading: - ~30 link findings, all noise. Regexes inside code spans are `[...](...)` to a naive scanner. Strip code first. - `file:` and other schemes were treated as repo-relative paths. - Relative links were resolved against the repo root instead of the file they sit in, calling two files missing that sat next to the README linking them. Same fix applied to the boilerplate check: a document ABOUT placeholder detection was tripping the placeholder detector. Also removed this repo's own static tests badge. There is no CI - the forge has zero Actions runners registered - so it could never become real, and it is the exact anti-pattern the gate now flags. 67 tests. Against llm-security every remaining finding is real and matches the census's independent hand-measurement. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WYJ3FHLtVgzFXMZ6UF598h
7.4 KiB
repo-standard
Per-repo gate for the open/ presentation standard: README first screen, install block, files required by the repo's class, and dead repo references.
A repository can be substantially good and still read as abandoned. The gap is almost never the code — it is the first screen, an install path that stops halfway, and references to a name that was retired two renames ago. This plugin checks that surface in one repository and reports what it finds.
Solo-maintained, fork-and-own. This plugin is a starting point, not a vendor product. Issues are welcome as signals; pull requests are not accepted. See the marketplace governance for the full model.
AI-generated: all code produced by Claude Code through dialog-driven development.
Status: maintained, solo. The public API is the gate's finding codes and the
register schema; both can still change before 1.0. There is no CI — the forge
has no Actions runner — so the test claim is one you run yourself, in one
command, from a clean clone: npm test. A badge asserting it would be a claim
dressed as evidence.
Install
Use the https:// form. The forge UI's clone button hands out an ssh:// URL,
and marketplace add answers it with Invalid git URL — a message that never
mentions the protocol.
claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-marketplace.git
claude plugin install repo-standard@ktg-plugin-marketplace
Or enable it directly in ~/.claude/settings.json — a working second path, not
a replacement for the two commands above:
{ "enabledPlugins": { "repo-standard@ktg-plugin-marketplace": true } }
Requirements
Node 18 or newer. No dependencies. The one network call — the org listing, used
to read a repo's published description — reads anonymously, so it needs no
token; --offline skips it.
What it does
Run it inside a repository:
node scripts/repo-standard-check.mjs --dir "$PWD"
The repository's class decides what each check means:
| Check | What fails it |
|---|---|
| First screen | no H1 on line 1, or the line under it is not the published description. An H1 that merely differs from the repo name is a WARN — that is a naming choice, not a defect |
| Install block | the form for this class is missing, incomplete, or shown over ssh:// |
| Required headings | ## Install, ## Non-goals, ## Changelog — per class. Present at the wrong depth is its own finding |
| Required files | a file this class (or trait) needs is absent |
| Repo references | an open/<name> in URL position resolves to nothing |
| Relative links | a link points at a file that is not tracked |
| Licence claim | the README cites a licence the repo has no file for |
| Badges | a static badge asserts a test, build or coverage run that nothing verifies |
| Boilerplate | template text nobody filled in |
| Version consistency | manifest, README badge, newest CHANGELOG entry and the git tag disagree |
| Description | empty, or past the length bound |
Findings carry two independent things: a level (ERROR, WARN, SKIP,
OK) and a bucket, which is what you actually triage on:
- broken now — a stranger is blocked or misled
- missing — an expected artefact is absent
- weakening — present and working, but it reads as amateur
The process exits 1 on any ERROR. A SKIP means the check could not run — an
unreachable forge, an untagged repo, a link that leaves the repository. It is
not a pass, and the output prints those separately under a heading that says so.
Traits — a second axis
Class is structural. A trait is about what the code does, which no remote can
tell you. security attaches the obligations a tool takes on by handling
untrusted input: a SECURITY.md with a real disclosure channel, and a
## Known limitations section. Traits live in the register and are the
maintainer's judgement, not a reading.
What is deliberately not required
CONTRIBUTING.md, CODE_OF_CONDUCT.md and MAINTAINERS.md are required by no
class. This project is solo-maintained and says so publicly; contributor-facing
documentation for something that accepts no contributors is theatre, and a code
of conduct with an unattended placeholder address is worse than none — it is a
visible unfinished template. Consumer-facing documents are untouched by that.
Being solo is not a reason to skip a SECURITY.md; someone finding a hole still
needs somewhere to send it.
The class decides what is required
The class is read off the catalog and the remotes; it is structural, not a
judgement. It lives in register/repos.json.
| Class | Install form | Requires |
|---|---|---|
| plugin | marketplace add and a CLI install command |
README, LICENSE, CHANGELOG, plugin manifest |
| catalog | marketplace add only — it is the marketplace |
+ GOVERNANCE, CONVENTIONS |
| shared-asset | how to vendor it; never a plugin install line | README, LICENSE |
| standalone | pip/uv | README, LICENSE |
| org-profile | none | README |
A flat standard across every class would demand a CONTRIBUTING from a CSS library that accepts no contributions, and a roadmap from a five-line profile. That is how a gate teaches people to switch it off.
Three outcomes on references, not two
"Matches no repository" and "matches something that is deliberately not a repository" are different findings. The second class is real and it is common: a retired name kept alive on purpose in prose, a reserved namespace occupying a repo-shaped path, a published package name that was never a repo. If those share an outcome with genuine dead links, the genuine ones hide inside a pile of correct text.
Only names in URL position are treated as references, which excludes prose,
paths and directory names in one move. The .git suffix is normalised first —
without that, a raw scan turns three dead names into about twenty.
Non-goals
- Anything requiring a view across every repository at once. This gate sees one repo. A README can look correct from the inside and only turn out wrong when a dozen are compared. Org-wide divergence is measured where the org is enumerated, not here.
- Fixing while measuring. It records findings; you fix them afterwards. Patching under measurement is how inconsistency accumulates unnoticed.
- Deciding whether to rename a repo, or whether a roadmap is real. Those are operator calls. The gate brings evidence to them.
- Blocking commits. There is no hook. A gate that fails a correct repository is the mechanism that gets gates switched off, so this one earns that role before it takes it.
Tests
npm test
67 tests over the pure classifiers. The reference fixtures are measured false
positives, each with its expected verdict — the six that produced the
three-outcome reference rule, plus the noise sources found by running the gate
against a real repository: regexes inside code spans that are markdown links to
a naive scanner, file: URLs, and relative links resolved against the wrong
directory.
Changelog
See CHANGELOG.md.