Keep the outlived-caveat check and drop restatements
This commit was merged in pull request #8.
This commit is contained in:
@@ -108,8 +108,9 @@ Every PR gets at least this sweep; for sensitive surfaces also recommend the ded
|
||||
- Is naming precise and unambiguous?
|
||||
- **Does every name in the diff still match its (possibly changed) contents?** When a change meaningfully shifts what a file/folder/package/service/variable does, its name must be updated in the same change — flag a stale name left behind by a content/purpose shift (e.g. a `webhook` test helper reworked into a JWT verifier but still called `webhook`/`WEBHOOK_URL`). The rename belongs in the PR, not "later."
|
||||
- Are magic numbers/strings replaced with named constants?
|
||||
- **Judge every comment and prose line the diff adds against `~/.claude/CLAUDE.md` → "Comments and documentation"**, `README.md`, `AGENTS.md` and `docs/` included. Recommend deletion, not trimming; report a density breach with the ratio and the files driving it.
|
||||
- **A pointer is not a definition.** That bar pushes toward deleting prose; this pushes the other way. Flag a comment whose content is a reference — `see AGENTS.md §11`, `per the spec §4` — when what it points at is a *definition* the reader needs to follow the code: what a unit counts, what a term means, what invariant a cache rests on. That belongs at the code, in one line. A pointer carrying *rationale* — a rejected alternative, the premise behind a standing choice — is correct and stays. Definitions in the code, reasoning in the record. A section number in another document is the one comment form that cannot be checked against the code beside it, so it rots invisibly.
|
||||
- **Judge every comment and prose line the diff adds against `~/.claude/CLAUDE.md` → "Comments and documentation"**; report a density breach with the ratio and the files driving it.
|
||||
- **Flag a caveat the diff has outlived**, anywhere in the repo: report the sentence's `file:line` and the behaviour that replaced it.
|
||||
- **A pointer is not a definition.** Flag a comment whose content is a reference — `see AGENTS.md §11`, `per the spec §4` — when what it points at is a *definition* the reader needs to follow the code: what a unit counts, what a term means, what invariant a cache rests on. That belongs at the code, in one line. A pointer carrying *rationale* — a rejected alternative, the premise behind a standing choice — is correct and stays. Definitions in the code, reasoning in the record. A section number in another document is the one comment form that cannot be checked against the code beside it, so it rots invisibly.
|
||||
- **Never propose new documentation as a "nice to have".** Suggesting a doc paragraph is proposing bulk someone must maintain. Raise it as a Stability Warning only when its absence would actively mislead someone, and say which mistake it prevents; otherwise don't raise it at all. Deleting redundant prose is always the cheaper fix.
|
||||
- **Never let documentation stand in for a fix.** A finding is not closed by describing the defect in a README, and neither is one of yours: if the only available remedy is telling the reader, say so and mark it a decision for the human, so it lands in the PR or ticket where a decision record belongs. Naming a residual risk is your job; choosing to publish it in the repo is not yours to hand out.
|
||||
|
||||
|
||||
@@ -4,6 +4,7 @@
|
||||
|
||||
Nine-seat comprehension panel, 2026-09-24, depth 1: Navigation 7.6, Locality 5.0, Shape 6.2, Self-sufficiency 5.3, overall 5.9. Every seat was capped by Locality or Self-sufficiency, and seven of nine named `bin/loop-claude`'s round loop as the unit they would least want to modify. The items below are ordered by how many seats named the place and how much of the cap it carries; each is one chunk.
|
||||
|
||||
- Move "a pointer is not a definition" into `CLAUDE.md` → "Comments and documentation" and cite it from `agents/stability-reviewer.md` §10 and `skills/larv-review/SKILL.md` §7, which each carry a copy today.
|
||||
- Keep the pipeline order and the prose-only path in `skills/larv-review/SKILL.md` alone; its frontmatter, its §8 preamble, its §12 summary list and `CLAUDE.md`'s working loop each spell it today.
|
||||
- State in `bin/loop-claude`'s docstring the Claude Code internals it rests on, with the version they were observed on (2.1.281): the transcript entry shapes `human_turns` reads, the `<id>.jsonl` file and its `.superseded-*`/`.orphaned-*` siblings, `~/.claude.json`'s `hasTrustDialogAccepted`, and `--json-schema` returning `structured_output`. Seven seats reconstructed these from the tests.
|
||||
- Fix in `bin/loop-claude`: a judge failure re-judges after a minute instead of re-running the worker with "stopped before it was finished"; the failure counter survives a reload; `reload_if_edited` runs the new file with `--help` before exec so an import-time error keeps the old one; every directory `archive` creates is 0700, not only the leaf; `human_turns` states the list case positively; `project_path` and `session_name` share one branch; `sections` stops at any heading. Add a test for `run_round`'s resume decision against a stub `claude`.
|
||||
|
||||
Reference in New Issue
Block a user