Repository navigation
docs(readme): back each built requirement with the checks that prove it - #488
Merged
Merged
Conversation
The README's built list now links docs/requirements.md, where each requirement names the tests, clicks journeys and measured numbers (journey <= N clicks in the clicks baseline) that fail when it stops being true. Requirements nothing checks yet say so and link #486. In progress is refreshed from the open pull requests, and a Planned list links where each next step is tracked. The assistant's merged web search, code sandbox, versions and MCP server form join the built list. ci/check_requirements.py (make requirements, and a pre-commit hook that always runs) fails when a built item links no checks, a named test, journey, workflow step or file is gone, a measured number is no longer met, an In progress item is already released, or a Planned item links nowhere. ci/test_check_requirements.py tests it. AGENTS.md gains the rule that requirements move with the code. Closes #483 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MTK8aqzLBhdhfCmVf2LaWZ
#469 merged while this was open: its line moves from In progress to the built list, with its checks. The scorecard (#487) is merged too, so Planned keeps only what it doesn't measure yet. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MTK8aqzLBhdhfCmVf2LaWZ
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Requested by Adeel · project thread
Description
Before: the README's built list made claims with no pointer to what proves them, In progress was missing six open pull requests, and there was no Planned list. A renamed or deleted test could quietly leave a README claim with nothing behind it.
After: every built item in the README (the "What you can do with it" bullets, Install and Light by default) links its section of the new docs/requirements.md. There, 131 requirement rows each name the tests (by function or title), clicks journeys, measured numbers (for example
source-folder≤ 4 clicks inci/clicks/baseline.json, which backs "a local folder in four clicks") or CI workflow steps that fail when the requirement stops being true. Seven requirements have no check yet; their rows say so and link the follow-up issue #486. In progress now lists every open feature PR, and a new Planned list links where each next step is tracked (the docs pages that already label it planned, #481, #482). The assistant's merged web search, code sandbox, conversation versions and MCP server form (#467 to #473) join the built list.make requirementsrunsci/check_requirements.py, and a pre-commit hook that always runs puts it in CI on every pull request. It fails when:Motivation and Context
Closes #483. AGENTS.md (Goal) makes agents own the requirements: keep them in the README's built, in progress and planned lists, each backed by a check, and catch drift. AGENTS.md gains the rule "Requirements move with the code", and docs/contributing.md a Requirements section.
How: five read-only helpers mapped each README claim to the checks that assert it; every name was confirmed by the script itself. Tests that skip in CI (rclone- or Chromium-dependent) were left out as checks and listed in #486 where nothing else covers the claim.
Steps to reproduce (if appropriate):
Raising
source-folderto 5 clicks inci/clicks/baseline.jsonfails it the same way ("takes 5 clicks in baseline.json, not ≤ 4").ci/test_check_requirements.pycovers each rule (12 tests).Types of changes
!in the title)Checklist:
make hookschecks it on commit).docs/accordingly.## UnreleasedinCHANGELOG.md. (n/a: no change for people using Lens)Done questions (AGENTS.md)
docs/requirements.mdis plain Markdown tables and the check is one command (make requirements), so agents read and keep it.mkdocs build --strictis clean.ci/local-ci.sh --jobs pre-commit,title) passed, including both new hooks. Refine later: the seven gaps and the thin checks are in Requirements with no check yet #486.ci/validate_threat_model.py's pattern and the existing pre-commit job; no new workflow.Generated by Claude Code