Skip to content

docs: state the goal in a testable form and stop carrying counts - #1397

Merged
fdaviddpt merged 2 commits into
mainfrom
fix/1396
Sep 9, 2026
Merged

docs: state the goal in a testable form and stop carrying counts#1397
fdaviddpt merged 2 commits into
mainfrom
fix/1396

Conversation

@fdaviddpt

Copy link
Copy Markdown
Contributor

Closes #1396.

The problem this fixes

docs/overview.md is where this project states what it is for, and it had drifted on five separate
numbers -- commands (8 against 9), agents (5 against 6), phase files (6 against 9), scripts (40
against 86), and the sub-manager's handback states (three against six) -- plus a standing table
dated 2026-09-02 at v0.17.0, carried through fourteen tags.

Every sentence was correct when written. That is the point: it read as current the whole time, which
is this project's own defect class applied to its own prose.

The fix is not to correct the counts

It is to stop carrying them. A goal document that holds no countable fact cannot drift into a wrong
one, and ls is the source of truth for how many commands there are. A page that duplicates it is a
second copy to keep in sync forever, which is the thing the governing rule forbids.

What the page carries now

  • No counts, and a sentence saying why.
  • Four tests for whether work is inside the goal -- does it resolve issues or maintain
    machinery; does it remove a human from the loop or add one; does it leave a second copy of a fact;
    can it tell "found nothing" from "could not look". Work failing one is outside the goal even when
    correct, reproducible and asked for. This is what the page was asked for and did not previously do:
    a boundary test on live work, not a description.
  • The surface -- two verbs, marked as not built yet, and the loop-not-router rule (One entry point: /oss:run asks what this repo needs now #1389).
  • What runs underneath -- framed as internal vocabulary that need not reach the user surface.
  • Cadence is config, not memory (The triage sweep after a release is stated as a rule and implemented by nothing #1386).
  • Where prose lives -- one destination per kind of thing learned, chosen by what each destination
    costs rather than by subject.
  • What is not true yet -- the triage gap, no unattended runtime, and that the loop has only ever
    run in front of the person who wrote it.

Known gap, deliberately not fixed here

The surface section starts at the slash picker. The honest surface starts at the launcher -- install
the plugin, run oss-workspace, it works -- since nobody normally types either verb. #1392 records
that and owns the fix.

Checks run

  • assemble_changelog.py --check -- ok, both fragments parse.
  • tests/test_claude_md_currency.py, tests/test_content_invariants.py,
    tests/test_docs_state_slug_grammar_308.py -- 226 passed.
  • markdownlint via the write validator: 39 errors before this change, 5 after, all remaining ones
    table rows too wide to wrap.

Docs only. No code path changes.

🤖 Generated with Claude Code

https://claude.ai/code/session_012UYdzDHX3k3C2Eh7B5hRVH

[AI-generated]

fdaviddpt and others added 2 commits September 9, 2026 22:44
docs/overview.md had drifted on five numbers -- commands, agents, phase files,
scripts, and the sub-manager handback states -- while still reading as current,
plus a standing table dated to v0.17.0. Correcting the numbers would buy one
cycle before the same drift, so the page now carries no countable fact at all
and says why: ls is the source of truth and a page that duplicates it is a
second copy to keep in sync forever.

In their place: four tests for whether a piece of work is inside the goal, the
two-verb surface the project is moving to (marked as not built, #1389), the
rule that a cadence step with a threshold in config reaches itself while one
written only in prose needs remembering (#1386), a routing table for where each
kind of prose belongs and what each destination costs, and an honest statement
that the loop has only ever run in front of the person who wrote it.

Known gap, recorded in #1392 rather than fixed here: the surface section starts
at the slash picker, and the honest surface starts at the launcher.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012UYdzDHX3k3C2Eh7B5hRVH
tests/test_readme_trim_795.py went red on four legs: docs/overview.md is
where README content moved by #795 lives, and it pins two markers there --
"packages the loop once" and "copies drift". The rewrite dropped the whole
paragraph as redundant with CLAUDE.md, which is wrong: CLAUDE.md is the
loop own document, not the public one, and a reader of docs/ never sees it.
The guard was right and is restored to, not tuned around.

The second marker then failed for a different reason and it is the one this
repo already has a rule about: the paragraph as first rewritten wrapped as
"the copies\ndrift", and the guard matches per line. Nothing was missing --
the layout broke the phrase. Re-wrapped so it sits on one line.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012UYdzDHX3k3C2Eh7B5hRVH
@fdaviddpt
fdaviddpt merged commit 71a100e into main Sep 9, 2026
10 checks passed
@fdaviddpt
fdaviddpt deleted the fix/1396 branch September 9, 2026 21:35
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.

docs/overview.md had drifted and did not state the goal in a form work can be tested against

1 participant