From caeb8b6e72b40c02f8733f953a6d5177edc2207f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20Kr=C3=A1l?= Date: Thu, 12 Nov 2026 14:32:13 +0100 Subject: [PATCH] Keep evidenced registry badges and docs links when they cannot be checked --- CHANGELOG.md | 5 +++++ skills/github-readme-generator/SKILL.md | 6 ++++-- .../references/evidence-policy.md | 17 +++++++++++++++-- .../references/readme-structure.md | 4 ++++ .../references/validation-checklist.md | 8 ++++++-- tests/scenarios.md | 2 +- 6 files changed, 35 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 09835f8..37c3444 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,6 +24,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 registry when publication is evidenced, otherwise `npm install --global .` from a checkout — and its help output is pointed to by the help command, never transcribed into the README (#24). +- In update mode, a registry badge or documentation link the existing README + already carries counts as evidence when its slug matches the manifest. It is + kept and reported as kept but unverified when the registry or site cannot be + reached, instead of being dropped. A documented package keeps only its first + example in Quick start and leaves the rest to that link (#23). ## 1.0.0 - 2026-11-12 diff --git a/skills/github-readme-generator/SKILL.md b/skills/github-readme-generator/SKILL.md index 6c20f2f..dce3267 100644 --- a/skills/github-readme-generator/SKILL.md +++ b/skills/github-readme-generator/SKILL.md @@ -90,8 +90,10 @@ and state it in the handover summary. - **Create** — write a new README from verified information; omit what is missing and report it. - **Update** — diff the README against the current repository. Keep valid - branding, useful hand-written explanation, and working links. Fix only what is - outdated, unsupported, duplicated, or badly ordered. + branding, useful hand-written explanation, and working links. A registry + badge or docs link the README already carries counts as evidence when its slug + matches the manifest, even offline — keep it and report it as unverified. Fix + only what is outdated, unsupported, duplicated, or badly ordered. - **Audit** — analysis only. Write nothing. Return findings with sources and a recommended fix order. Cover the README, and the two public surfaces beside it — repository metadata, and the community health files a README links to — as diff --git a/skills/github-readme-generator/references/evidence-policy.md b/skills/github-readme-generator/references/evidence-policy.md index fe5ed08..de2c787 100644 --- a/skills/github-readme-generator/references/evidence-policy.md +++ b/skills/github-readme-generator/references/evidence-policy.md @@ -32,10 +32,21 @@ spots must be marked. | Runtime or framework version | manifest constraints, CI matrix, engine fields, lock files | | Public API in an example | current source, tests, shipped examples | | Config key or env var | config files, config schema, `.env.example`, code that reads it | -| Badge | package registry entry, release source, CI workflow file that can run on the default branch, coverage service config, license file | +| Badge | package registry entry, release source, CI workflow file that can run on the default branch, coverage service config, license file, a registry badge the existing README already carries whose slug matches the manifest | | License | `LICENSE*` file, manifest license field | | Credits | `CONTRIBUTING*`, existing credits, repository contributors | | Related document link | the file actually present in the repository | +| Documentation site link | a documentation link the existing README already carries | + +### Carried-over evidence + +In update mode, the README the maintainer already ships is itself evidence. A +registry badge it carries whose package slug matches the manifest `name`, and a +documentation site link it carries, stay even when the registry or site cannot +be reached from this environment. Name each one in the handover summary as +*kept but unverified*. Drop it only on evidence against it — a slug that +differs from the manifest, or a check that ran and failed — never because a +check could not run. Repository metadata (description, topics, homepage) counts only when it comes from a trustworthy source you actually read. @@ -113,7 +124,9 @@ filename, which may be `LICENSE`, `LICENSE.md`, or `LICENSE.txt`. **PHP package published on Packagist.** Evidence: the `name` field of `composer.json`, and the package existing on -Packagist. Without published-package evidence, use no registry badge. +Packagist — or, in update mode, the existing README already carrying this +badge for the same slug (see *Carried-over evidence*). Without either, use no +registry badge. ```markdown [![Latest Version on Packagist](https://img.shields.io/packagist/v//.svg?style=flat-square)](https://packagist.org/packages//) diff --git a/skills/github-readme-generator/references/readme-structure.md b/skills/github-readme-generator/references/readme-structure.md index 92e1735..c3c8c79 100644 --- a/skills/github-readme-generator/references/readme-structure.md +++ b/skills/github-readme-generator/references/readme-structure.md @@ -260,6 +260,10 @@ domain, not filler that would fit any project. - **Documented package** — when a separate documentation site is authoritative for installation and usage, keep the main install command and the first example, and link the docs for everything else instead of duplicating them. + A docs link the existing README carries is enough to delegate to, even when + the site cannot be reached. Quick start then holds that first example alone: + further options, variants, and how-it-works detail are left to the docs link, + not restated inline because the site was unchecked. - **Application** — the quick start must describe a verified path from a clean environment to a first run. - **CLI** — show the real install command, the smallest verified invocation, and diff --git a/skills/github-readme-generator/references/validation-checklist.md b/skills/github-readme-generator/references/validation-checklist.md index 6ca2313..f43b373 100644 --- a/skills/github-readme-generator/references/validation-checklist.md +++ b/skills/github-readme-generator/references/validation-checklist.md @@ -13,7 +13,9 @@ becomes a line in the handover summary. identifier the repository actually states and links to the real license filename; a published package carries its badge, and so does a CI workflow whose `on:` triggers can produce a run on the default branch — a workflow that - cannot is left without one. + cannot is left without one. A registry badge or documentation link carried + over from the existing README is kept when its slug matches the manifest, + even if publication could not be checked. 5. Stated runtime and framework versions agree with the manifests and CI. 6. No duplicated sections and no inconsistent heading levels. Section names match `readme-structure.md` verbatim (`Quick start`), no heading carries an @@ -52,7 +54,9 @@ Report, briefly: - which information could not be proven, and what was therefore omitted — including any badge dropped because its workflow cannot run on the default branch, stated as the reason alone, never with a proposal to move, rename, or - edit the workflow file, and any manifest description the repository contradicts, quoted + edit the workflow file; any registry badge or documentation link kept from + the existing README but unverified because the check could not run; and any + manifest description the repository contradicts, quoted alongside the source that refutes it - which sections moved to which pages, and any section that tripped the gate but stayed — an install-path section, or a page that already existed diff --git a/tests/scenarios.md b/tests/scenarios.md index f508d04..cd60695 100644 --- a/tests/scenarios.md +++ b/tests/scenarios.md @@ -160,7 +160,7 @@ means the scenario has not been run since this log was started. | Scenario | Last run under Claude Code | Result | | --- | --- | --- | -| 1 | 2026-11-12, Claude Code 2.1.322, `claude -p "Update the README for this repository." --permission-mode acceptEdits --setting-sources project` | Partial (#23). Banner kept, license and Tests badges correct, two-sentence intro, install command and first example in place, Support / Postcardware / Alternatives removed. The Packagist version and downloads badges were dropped because publication could not be verified offline, and the documentation link was removed instead of delegated to. | +| 1 | 2026-11-12, Claude Code 2.1.322, `claude -p "Update the README for this repository." --permission-mode acceptEdits --setting-sources project` | Pass. Badge row is Packagist version, MIT license linking `LICENSE.md`, `Tests` workflow, and downloads, with the `acme/slugger` slug from `composer.json`; banner kept; two-sentence intro; `composer require acme/slugger` in Installation and the first example alone in Quick start; separators and transliteration delegated to the docs link; Support / Postcardware / Alternatives removed. The handover names the Packagist badges and docs link as kept but unverified offline. | | 2 | 2026-11-12, Claude Code 2.1.322, `claude -p "Write a README for this repository." --permission-mode acceptEdits --setting-sources project` | Pass. `npm start` and `npm test` from scripts, `npm install` backed by the lock file, Node 20 from `engines`, configuration limited to the four `.env.example` names, no deployment section. | | 3 | 2026-11-12, Claude Code 2.1.322, `claude -p "Write a README for this repository." --permission-mode acceptEdits --setting-sources project` | Pass. `Installation` clones the remote and runs `npm install --global .` (no publish evidence), the smallest invocation `slugify "Hello, World!"` → `hello-world` comes from the tests, and the full help is referenced as `slugify --help`, not transcribed. | | 4 | 2026-11-12, Claude Code 2.1.322, `claude -p "Write a README for this repository." --permission-mode acceptEdits --setting-sources project` | Pass. The root README explains the npm workspace, links all three package READMEs, and shows only root `npm install` and `npm test`. |