docs: make CLAUDE.md describe the repo that exists - #46
Open
sroberts wants to merge 1 commit into
Open
Conversation
The file opened with "Plumbline is in a pre-implementation / seed state" and "There is no Go module, Makefile, source tree, CI config, or test suite yet. Do not invent commands (go test ..., make ...) until those files actually exist." The repo has 133 files, 8 workflows, 22 signals, a Makefile, and a full test suite. The instruction file told agents not to run the test suite. It is also the artifact l2.agent-instructions scores 1.0 — fairly, by that signal's rule (present, has a heading, >=20 non-blank lines), and SPEC.md §2 rules out grading prose quality on purpose. So nothing in the tool was ever going to catch this. Worth noting when reading plumbline's own verdict: a green L2 means the file exists, not that it is true. Replaces the status section with build/test commands, a package map, and the invariants that are not derivable from reading the code: SPEC.md is the contract, workflow signals go through the AST rather than raw YAML, .plumbline.toon and docs/SIGNALS.md are generated and drift-gated, signal IDs are public API, and a detector gap is a bug against the detector rather than a prompt to reshape the scanned repo's CI. Also marks the L4 anti-pattern as having no detector, and notes how the L3 one is modelled. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XtNwLDzRYmPrXcYeQypTf9
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
1 participant
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.
The problem
CLAUDE.mdopened with:The repo has 133 files, 8 workflows, 22 signals, a Makefile, and a full test suite. The instruction file was telling agents not to run the test suite.
The part worth noticing
This is the artifact
l2.agent-instructionsscores 1.0 on — fairly, by that signal's rule: present, has a heading, ≥20 non-blank lines. And SPEC §2 rules out grading prose quality on purpose, for good reasons (reproducibility, no LLM in the default path). So no signal in the catalog was ever going to catch this, and none should be changed to.It's a useful caveat to keep in mind when reading plumbline's own verdict, and it's now written into the file: a green L2 means the file exists, not that it's true.
What replaces it
make build,make test,make test-race, per-packagego test)SPEC.mdis the contract; change it in the same commit as behaviorinternal/workflows, never raw YAML regex.plumbline.toonis drift-gated in CI; regenerate it with any change that moves the verdictdocs/SIGNALS.mdis generated; don't hand-editAlso updates the anti-pattern list:
l3.metrics-acted-onnow covers the dashboard graveyard (with a note on why it inverts the framing rather than the score), and the L4 one is marked no detector yet.Snapshot regenerated — the excerpt and line count in
.plumbline.toonboth change.🤖 Generated with Claude Code
https://claude.ai/code/session_01XtNwLDzRYmPrXcYeQypTf9