Skip to content

docs(readme): back each built requirement with the checks that prove it - #488

Merged
adeelahmad merged 3 commits into
mainfrom
claude/project-thread-c5dfhw
Oct 17, 2026
Merged

adeelahmad merged 3 commits into
mainfrom
claude/project-thread-c5dfhw

Conversation

@adeelahmad

Copy link
Copy Markdown
Owner

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 in ci/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 requirements runs ci/check_requirements.py, and a pre-commit hook that always runs puts it in CI on every pull request. It fails when:

  • a built item links no section (or a section no item);
  • a named file, Python test function or class, quoted test title or journey id, or workflow job or step name is gone;
  • a measured number is no longer met in the clicks baseline, or the journey fails there;
  • a "no check yet" row links no issue;
  • an In progress PR is already in the changelog;
  • a Planned item links nowhere.

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):

make requirements                                         # Every built requirement names checks that exist.
sed -i 's/def test_wiki_addresses/def test_x/' fastapi_backend/tests/api/test_entities.py
python3 ci/check_requirements.py                          # … `test_wiki_addresses` is gone from …/test_entities.py

Raising source-folder to 5 clicks in ci/clicks/baseline.json fails it the same way ("takes 5 clicks in baseline.json, not ≤ 4"). ci/test_check_requirements.py covers each rule (12 tests).

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality): a CI check and documentation; no runtime change
  • Breaking change (fix or feature that would cause existing functionality to change; ! in the title)

Checklist:

  • The title is a Conventional Commit.
  • My code follows the code style of this project (make hooks checks it on commit).
  • I added or updated tests.
  • My change requires documentation updates, and I have updated docs/ accordingly.
  • Users need more than the title to understand it, so I wrote it under ## Unreleased in CHANGELOG.md. (n/a: no change for people using Lens)

Done questions (AGENTS.md)

  • Goal: the README's requirements are backed by checks, and drift fails CI. Merges on green CI.
  • Agents: docs/requirements.md is plain Markdown tables and the check is one command (make requirements), so agents read and keep it.
  • Zero setup: n/a for installs. The check needs only Python 3, already required by pre-commit.
  • Fewest clicks: n/a, no UI. The README now states the measured click numbers it claims.
  • Configurable: n/a, no settings.
  • Light: n/a, nothing installed or run in Lens.
  • Private and secure: n/a, no new surface.
  • Cost: n/a, no model calls.
  • User decides: defaults unchanged; no requirement, test or baseline was loosened.
  • Upgrades: n/a, no stored data.
  • Honest: every built claim names its check, and seven with none say "No check yet" (Requirements with no check yet #486). Planned and In progress are labelled and linked.
  • Tests, docs and generated files: 12 unit tests for the check; docs/requirements.md, docs/contributing.md and mkdocs nav updated; mkdocs build --strict is clean.
  • Open standards: plain Markdown and Python standard library, no new dependency.
  • Reported: local CI (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.
  • Reuse: follows ci/validate_threat_model.py's pattern and the existing pre-commit job; no new workflow.

Generated by Claude Code

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
@adeelahmad adeelahmad self-assigned this Oct 17, 2026
#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
@adeelahmad
adeelahmad merged commit 9890e69 into main Oct 17, 2026
9 checks passed
@adeelahmad
adeelahmad deleted the claude/project-thread-c5dfhw branch October 17, 2026 03:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

README requirements: built, in progress and planned lists, each backed by a check

2 participants