Answer architecture round 1: move the base only past a scoring run or a ruling of better, take it from the default branch, run the scoring run when a release's items run out or an item names the floor, rename the seat prompts, and fold the changelog's comprehension entries into the paired ruling
This commit is contained in:
@@ -12,7 +12,7 @@ Decisions live in `docs/decisions.md`:
|
||||
- loop-claude: each project's model lives in `~/.claude/loop-claude-models.json`, which only loop-claude writes
|
||||
- review: a pass gets at most three rounds per chunk; instead of a fourth, the run asks the human
|
||||
- review: a fix for a 🔴 or 🟡 reruns the pass that found it and each pass whose trigger names fixes like it; a fix for a 🟢, a ❓ or a prose finding reruns none
|
||||
- review: the ratchet is a paired ruling against the last measured commit, settled by two agreeing seats or a lead of two votes among four; the four-seat scoring run checks the floor only on each release's last item
|
||||
- review: a paired ruling against the last measured commit decides the ratchet; the four-seat scoring run checks the floor when a release's items run out or an item names the floor
|
||||
- review: a project decision may suspend the comprehension check for the plan items it names
|
||||
- review: a pass skips only on a precedent: a decision, or a plan item crediting the pass, that the repo held before the chunk began
|
||||
- loop-claude: the archive keeps the raw transcript, and a failed archive stops the loop
|
||||
@@ -34,7 +34,7 @@ Decisions live in `docs/decisions.md`:
|
||||
|
||||
## Scoring run
|
||||
|
||||
The project values for `skills/comprehension-panel/scoring-run.md`:
|
||||
The project values for `skills/comprehension-panel/seat-prompts.md`:
|
||||
|
||||
- `{language}`: Python
|
||||
- `{kind}`: a Claude Code configuration with an agent loop and review skills
|
||||
|
||||
+5
-6
@@ -2,21 +2,20 @@
|
||||
|
||||
## Unreleased
|
||||
|
||||
- larv-review's ratchet is a paired ruling. Mid A and the inherited architect each read the project at the PR head and at the commit the default branch's last comprehension record read, and vote whether it reads better, the same or worse. When they disagree, the maintainability senior and Junior A vote too; a ruling settles on a lead of two votes, and four seats without one rule same. A worse ruling blocks the merge as a fall in scores did. The four-seat scoring run, and with it the comprehension floor, runs only on the chunk that ships its release's last item. `docs/comprehension-history.md` keeps each ruling with its votes and the places each seat named.
|
||||
- larv-review's comprehension check. In each architecture pass a paired ruling decides the ratchet: Mid A and the inherited architect read the project at the PR head and at the last measured commit, and vote whether it reads better, the same or worse. The last measured commit is the default branch's newest that added a scoring run or a ruling of better to `docs/comprehension-history.md`. When the two disagree, the maintainability senior and Junior A vote too; a ruling settles on a lead of two votes, and four seats without one rule same. A worse ruling blocks the merge until fixed; after three rounds larv-review asks you, and an unattended run leaves the PR unmerged with the question. The four-seat scoring run checks the comprehension floor when a chunk leaves a release with no plan items, or ships an item naming the floor. A score under the floor blocks the merge until fixed or until you decide to ship; a decision in `docs/decisions.md` that lets every chunk ship under the floor counts as yours.
|
||||
- larv-review reruns fewer passes after a fix. A fix reruns the pass whose 🔴 or 🟡 it answers, plus stability when the fix changes behaviour, security when it opens an untrusted-input boundary or touches authn/authz, secrets or crypto, and architecture when it carries an architectural decision. A rerun reviews only what changed since that pass last reviewed. A fix for a 🟢, a ❓ or any prose finding reruns no pass, and prose takes one round.
|
||||
- larv-review runs one security pass on each change: the full scan alone when it runs, else `/security-review`.
|
||||
- larv-review runs the new `bin/reading-cost`, which measures each chunk `loop-claude` finished from its archive: the new input tokens the worker and its subagents took in before the worker's first commit, and the files git tracks that they read most. It appends each figure the project's `docs/reading-cost.md` lacks. Once 10 chunks are measured, and the last 5 chunks' median is above the 5 before them, larv-review files one plan item naming the files read most, or refreshes it. The chunk that ships it runs `reading-cost --reset`, so the trend counts only chunks that finished after it.
|
||||
- larv-review appends every scoring run to the project's `docs/comprehension-history.md`: the commit the seats read, each seat's five scores and the seats' mean, and the places each seat named. The ratchet compares a run with the history's last run on the default branch. The `comprehension floor:` entry in `docs/decisions.md` keeps only the decisions to ship under the floor; a project's next scoring run moves the last scores the entry still holds into the history. The seats do not read the history.
|
||||
- larv-review appends every paired ruling and scoring run to the project's `docs/comprehension-history.md`: the commit the seats read, each seat's vote or scores, and the places each seat named. The `comprehension floor:` entry in `docs/decisions.md` keeps only the decisions to ship under the floor; a project's next scoring run moves the last scores the entry still holds into the history. The seats do not read the history.
|
||||
- The README's goals put quality with the fewest interrupts first, as goal 1; sharing the setup, backups and leaking nothing follow as goals 2–4.
|
||||
- larv-review reruns the comprehension scoring run before merge when any commit since the last run changes more than `docs/decisions.md`, `docs/comprehension-history.md`, `docs/reading-cost.md`, `todo.md` or `CHANGELOG.md`, so the recorded scores are the merged commit's. A score under the floor, or below the default branch's recorded scores, blocks the merge and is never filed in `todo.md`. A fix lifts either; your decision to ship under the floor lifts only a score under the floor. A rerun counts toward the three-round cap only when it reports a blocking score that no decision of yours covers.
|
||||
- larv-review skips the comprehension scoring run for a chunk whose plan items a project decision names. The decision also names the later item whose scoring run ends the suspension. Neither the comprehension floor nor the ratchet can block a skipped chunk, its summary cites the decision, and a chunk shipping its release's last item is always measured.
|
||||
- larv-review reruns the comprehension check before merge when any commit since its last run changes more than `docs/decisions.md`, `docs/comprehension-history.md`, `docs/reading-cost.md`, `todo.md` or `CHANGELOG.md`, so the recorded result is the merged commit's. A result that blocks the merge is never filed in `todo.md`. A rerun counts toward the three-round cap only when it reports a block that no decision of yours covers.
|
||||
- larv-review skips the comprehension check for a chunk whose plan items a project decision names. The decision also names the later item whose check ends the suspension. Neither the ratchet nor the floor can block a skipped chunk, and its summary cites the decision. A chunk that meets the scoring run's trigger is always measured.
|
||||
- README → Install and Update give the commands that check the latest tag out into `~/.claude`: on a new machine, whether or not Claude Code has already created the directory, and on one already on an older tag.
|
||||
- A session commits changes Claude Code made to `settings.json` only once their diff holds no credential, and asks you to move any credential out of the file first.
|
||||
- A technical principle, "Sane defaults, where a default serves better than an explicit ask". A default suits a value most callers want, does no harm when wrong, and can be seen and changed. It lives at the program's edge, such as a CLI; a library still asks for data, the clock and randomness.
|
||||
- larv-review's principles audit reads only the files under `~/.claude/principles/` that apply to the project, launching a file's auditor when unsure. A file's `Applies to` line says what it covers; one without the line covers every project. The summary names each file left out. After its first round, the architecture pass reruns the scoring run and only the reviewers whose 🔴 or 🟡 the fixes answer, unless the fixes carry an architectural decision.
|
||||
- larv-review's principles audit reads only the files under `~/.claude/principles/` that apply to the project, launching a file's auditor when unsure. A file's `Applies to` line says what it covers; one without the line covers every project. The summary names each file left out. After its first round, the architecture pass reruns only the reviewers whose 🔴 or 🟡 the fixes answer, unless the fixes carry an architectural decision.
|
||||
- When `loop-claude`'s judge rules a chunk unfinished, the resumed worker is shown the passage the judge quoted as the work remaining. A loop started before this change exits 1 at its next reload; rerun it.
|
||||
- larv-review's architecture pass and full security scan get short names, `Architecture` and `Full scan`. Each round's commit is titled with its pass's name in lower case: `Answer full scan round 1: …`.
|
||||
- larv-review's comprehension floor now says, without another file open, what the scoring run measures. A run scoring below the last one blocks the merge until fixed. After three rounds larv-review asks you; an unattended run leaves the PR unmerged with the question. A PR under the floor that scores no lower than the last run merges once you decide to ship. A decision in `docs/decisions.md` that lets every chunk ship under the floor counts as yours.
|
||||
- `loop-claude`'s judge reads your `~/.claude/CLAUDE.md` beside the project's `AGENTS.md` and `docs/decisions.md`. It no longer interrupts for a choice that file settles, and it answers the worker's questions from it.
|
||||
- `loop-claude`'s judge holds a chunk open until each answer you typed in it that a later chunk could need is recorded. An answer counts as recorded once the README's goals or audience, `AGENTS.md`, `docs/decisions.md` or `~/.claude/CLAUDE.md` hold it. It also counts once the transcript shows the worker writing it into the README's goals or audience, `AGENTS.md`, `docs/decisions.md`, `todo.md` or a code comment. The worker writing to `~/.claude/CLAUDE.md` does not count, since new rules there are yours. The resumed worker is told this rule.
|
||||
- `loop-claude` archives each answer the judge quotes, with the question it answers and its UTC time, in `<sha256>.outcomes.md`.
|
||||
|
||||
@@ -34,10 +34,10 @@ How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The
|
||||
|
||||
## Quality
|
||||
|
||||
Quality is proven by review. Every change is reviewed as a diff. The whole project is measured when a change carries an architectural decision, and before each release, because a project can drift from the principles one clean diff at a time. A project decision may suspend only the comprehension check (`larv-review` §3 → "Architecture" → "Suspended"). `larv-review` §3 says which review runs when. Quality has three parts. When two pull against each other, the earlier one wins.
|
||||
Quality is proven by review. Every change is reviewed as a diff. The whole project is measured when a change carries an architectural decision, and before each release, because a project can drift from the principles one clean diff at a time. A project decision may suspend only the comprehension panel's runs (`larv-review` §3 → "Architecture" → "Suspended"). `larv-review` §3 says which review runs when. Quality has three parts. When two pull against each other, the earlier one wins.
|
||||
|
||||
1. **Correct.** The work does what the goals and the plan say, and tests prove it.
|
||||
2. **True to the technical principles** (`~/.claude/principles/technical-principles.md`). The `comprehension-panel` skill measures KISS (`larv-review` §3 → "Architecture"): a score under the comprehension floor, scored before each release, blocks a merge. **Comprehension never falls:** when readers comparing the chunk with the last measured commit rule that it reads worse, improve what they named and rule again. After three such rounds, stop and ask the human.
|
||||
2. **True to the technical principles** (`~/.claude/principles/technical-principles.md`). The `comprehension-panel` skill measures KISS (`larv-review` §3 → "Architecture"). **Comprehension never falls:** when readers comparing the chunk with the last measured commit rule that it reads worse, improve what they named and rule again. After three such rounds, stop and ask the human. Before each release, a score under the comprehension floor blocks a merge.
|
||||
3. **Plainly written**, per "Prose".
|
||||
|
||||
## Prose
|
||||
|
||||
+2
-2
@@ -63,9 +63,9 @@ lilleman decided to ship each of these under the floor on the day listed. Each l
|
||||
|
||||
2026-10-08, lilleman, replacing the 2026-09-30 rule that every fix, a nit's included, re-enters review. Serves goal 1.4. An audit of the four costliest archived chunks (2026-10-08) found nearly every finding that mattered in a pass's first round; later rounds mostly re-checked the last fix, reworded what an earlier round wrote, or contradicted another round on the same line. A round 2 caught real bugs only where a fix changed behaviour, so stability still reruns on every fix that does, and security on every fix that opens an untrusted-input boundary or touches authn/authz, secrets or crypto. Valid while round-2 reviews of nit and prose fixes keep changing nothing a user would notice.
|
||||
|
||||
## review: the ratchet is a paired ruling against the last measured commit, settled by two agreeing seats or a lead of two votes among four; the four-seat scoring run checks the floor only on each release's last item
|
||||
## review: a paired ruling against the last measured commit decides the ratchet; the four-seat scoring run checks the floor when a release's items run out or an item names the floor
|
||||
|
||||
2026-10-08, lilleman. Serves goals 1.1 and 1.4. Two independent four-seat runs moved up to 0.4 on near-identical code, so a fall within that noise forced rounds that changed nothing (PR #224). A seat reading both versions judges the difference on the same material, so the noise the versions share cancels. No conventional significance level lets a sign test settle with four votes, so the human chose a lead of two votes over every other ruling, same included. Two seats that agree settle it, so a PR that leaves the reading as it was costs two seats. A third seat alone can never settle it, so the third and fourth launch together. The base is the commit the last ruling or scoring run on the default branch read. The human chose it on the architect's finding that a merge base lets chunks without an architecture pass, and a suspended restructure's steps, fall unseen one at a time. Valid while seats reading both versions agree more often than two absolute runs do.
|
||||
2026-10-08, lilleman. Serves goals 1.1 and 1.4. Two independent four-seat runs moved up to 0.4 on near-identical code, so a fall within that noise forced rounds that changed nothing (PR #224). A seat reading both versions judges the difference on the same material, so the noise the versions share cancels. No conventional significance level lets a sign test settle with four votes, so the human chose a lead of two votes over every other ruling, same included. Two seats that agree settle it, so a PR that leaves the reading as it was costs two seats. A third seat alone can never settle it, so the third and fourth launch together. The base is the default branch's newest commit that added a scoring run or a ruling of better to the history. The human chose the last measured commit on the architect's finding that a merge base lets chunks without an architecture pass, and a suspended restructure's steps, fall unseen one at a time. A ruling of same leaves the base where it was, or a run of small falls each ruled same would add up unseen. Taking the commit from the default branch keeps the rule working where a project squash-merges, which drops the branch's own commits. The scoring run also runs on a chunk shipping an item that names the floor, so the chunk that lifts a project to the floor can prove it. Valid while seats reading both versions agree more often than two absolute runs do.
|
||||
|
||||
## review: a project decision may suspend the comprehension check for the plan items it names
|
||||
|
||||
|
||||
@@ -95,16 +95,16 @@ the end. Tell everyone not to manufacture confusion.
|
||||
|
||||
A scoring run needs four seats — Junior A, Mid A, the maintainability senior and the inherited
|
||||
architect — plus the calibration seat ("The score") when more than one project is in play. Build
|
||||
the four seats' prompts from `scoring-run.md`, filled in from the project's `AGENTS.md` → "Scoring
|
||||
the four seats' prompts from `seat-prompts.md`, filled in from the project's `AGENTS.md` → "Scoring
|
||||
run". Change neither between runs, or the scores are not comparable. A project without that
|
||||
section gets it at its first scoring run.
|
||||
section gets it at its first scoring run or paired ruling.
|
||||
|
||||
## The paired ruling
|
||||
|
||||
A paired ruling asks whether a change makes a project read better, the same or worse. Each seat
|
||||
reads both versions, so what the two versions share cannot move the ruling. Check out the older
|
||||
version as a detached worktree in your scratchpad, and remove it afterwards. Build each seat's
|
||||
prompt from `scoring-run.md` → "Paired ruling"; the seats and the rule for adding one are the
|
||||
prompt from `seat-prompts.md` → "Paired ruling"; the seats and the rule for adding one are the
|
||||
caller's.
|
||||
|
||||
## What the seven report
|
||||
|
||||
+9
-9
@@ -1,10 +1,12 @@
|
||||
# The comprehension seats' prompts
|
||||
|
||||
Each scoring-run seat's prompt is the four parts below, in order: the opening, the seat's background, the shared brief, and the report for its kind of seat. Copy the text verbatim and replace each `{placeholder}`:
|
||||
A scoring-run seat's prompt is the opening, the seat's background, the shared brief, and the report for its kind of seat, in that order; a paired seat's is "Paired ruling" below. Copy the text verbatim and replace each `{placeholder}`:
|
||||
|
||||
- `{checkout}` and `{branch}`: the worktree the seats read, and its branch.
|
||||
- `{main}`: the project's main checkout.
|
||||
- `{files}`: every tracked non-test file the shared brief does not forbid, from `git -C {checkout} ls-files`, listed as one recursive glob per top-level source directory, such as `bin/loop_claude/**/*.py`.
|
||||
- `{forbidden}`: `todo.md, docs/decisions.md, docs/comprehension-history.md or docs/reading-cost.md (the plan, the decision log, past panels' records and past chunks' reading cost)`.
|
||||
- `{git}`: `git -C {checkout} ls-files`, and for a paired seat also `git -C {base checkout} ls-files`, each in backticks.
|
||||
- `{files}`: every tracked non-test file but those `{forbidden}` names, from `git -C {checkout} ls-files`, listed as one recursive glob per top-level source directory, such as `bin/loop_claude/**/*.py`.
|
||||
- `{preloaded}`: the files the harness pre-loads into a seat, found per `SKILL.md` → "What makes the result trustworthy".
|
||||
- `{anchors}` and `{dimensions}`: the six anchor bullets and the four dimension bullets in `SKILL.md` → "The score", verbatim, without bold and each on one line.
|
||||
- `{language}`, `{kind}`, `{domain}`, `{domain docs}` and `{3am question}`: the project's `AGENTS.md` → "Scoring run".
|
||||
@@ -12,7 +14,7 @@ Each scoring-run seat's prompt is the four parts below, in order: the opening, t
|
||||
## Opening
|
||||
|
||||
```
|
||||
You are one seat of a comprehension panel. Tools: Read, Grep, Glob, and Bash only for `git -C {checkout} ls-files` and `ls`. Never write, edit, run, build or test anything.
|
||||
You are one seat of a comprehension panel. Tools: Read, Grep, Glob, and Bash only for {git} and `ls`. Never write, edit, run, build or test anything.
|
||||
```
|
||||
|
||||
## Backgrounds
|
||||
@@ -27,7 +29,7 @@ You are one seat of a comprehension panel. Tools: Read, Grep, Glob, and Bash onl
|
||||
```
|
||||
Target: the project checked out at {checkout} (branch `{branch}`). Read ONLY there — never {main}, which is a different version.
|
||||
|
||||
Depth 1, the whole project: read README.md, AGENTS.md and CLAUDE.md (the charter), then every non-test tracked file: {files}. Do NOT open todo.md, docs/decisions.md, docs/comprehension-history.md or docs/reading-cost.md (the plan, the decision log, past panels' scores and past chunks' reading cost), nor any review output. You may open a test file when the code does not answer a question; say when you did.
|
||||
Depth 1, the whole project: read README.md, AGENTS.md and CLAUDE.md (the charter), then every non-test tracked file: {files}. Do NOT open {forbidden}, nor any review output. You may open a test file when the code does not answer a question; say when you did.
|
||||
|
||||
Your harness pre-loads these files into your context before your first tool call, from a DIFFERENT version (main): {preloaded}. Treat the worktree's own copies as the ones under review. A pre-loaded AGENTS.md may list decision titles; do not use them as evidence.
|
||||
|
||||
@@ -66,19 +68,17 @@ Report: the verbatim map; where it was wrong and how costly each correction was;
|
||||
|
||||
## Paired ruling
|
||||
|
||||
A paired seat's prompt is the opening, the seat's background, and the paired brief below, with these placeholders besides those above:
|
||||
A paired seat's prompt is the opening, the seat's background, and the paired brief below. Its placeholders besides those above:
|
||||
|
||||
- `{base}` and `{head}`: the commits of the older and the newer version; `{base checkout}`: the worktree holding `{base}`.
|
||||
- `{changed}`: `git -C {checkout} diff --name-status {base} {head}`, less the files the paired brief forbids.
|
||||
|
||||
In the opening, Bash also allows `git -C {base checkout} ls-files`.
|
||||
- `{changed}`: `git -C {checkout} diff --name-status {base} {head}`, less those `{forbidden}` names.
|
||||
|
||||
```
|
||||
Target: two versions of one project. The older, commit {base}, is checked out at {base checkout}; the newer, commit {head}, at {checkout}. Read ONLY there — never {main}, which is a different version.
|
||||
|
||||
Depth 1, the whole project in both versions: read README.md, AGENTS.md and CLAUDE.md (the charter), then every non-test tracked file at {checkout}: {files}. These files differ between the versions; read each at {base checkout} too, where it exists there:
|
||||
{changed}
|
||||
Do NOT open todo.md, docs/decisions.md, docs/comprehension-history.md or docs/reading-cost.md (the plan, the decision log, past panels' rulings and past chunks' reading cost), nor any review output. You may open a test file when the code does not answer a question; say when you did.
|
||||
Do NOT open {forbidden}, nor any review output. You may open a test file when the code does not answer a question; say when you did.
|
||||
|
||||
Your harness pre-loads these files into your context before your first tool call, from main, which may match either version or neither: {preloaded}. Treat the two worktrees' own copies as the ones under review. A pre-loaded AGENTS.md may list decision titles; do not use them as evidence.
|
||||
|
||||
@@ -32,7 +32,7 @@ A pass is one kind of review, a row of the table, named by its first column. Its
|
||||
|
||||
| Pass | Reviewer | Trigger |
|
||||
|------|----------|----------------------------------------|
|
||||
| Architecture | systems-architect, then principles-auditor and the comprehension check | ships its release's last item, or carries an architectural decision: a new, restructured or moved component, module, service or boundary; a new dependency or first use of an infrastructure pattern (queue, cron, cache, websocket, …); a new or changed external contract (routes, request/response shapes, events, webhooks, published file formats, CLI flags and exit codes); a schema change beyond an additive column; a fix, only where it carries an architectural decision |
|
||||
| Architecture | systems-architect, then principles-auditor and the comprehension check | meets the scoring run's trigger ("Architecture"), or carries an architectural decision: a new, restructured or moved component, module, service or boundary; a new dependency or first use of an infrastructure pattern (queue, cron, cache, websocket, …); a new or changed external contract (routes, request/response shapes, events, webhooks, published file formats, CLI flags and exit codes); a schema change beyond an additive column; a fix, only where it carries an architectural decision |
|
||||
| Full scan | the `claude-security` plugin at high effort: `/claude-security scan this branch's changes at high` | touches authn/authz, secrets or crypto, opens an untrusted-input boundary, or adds an external surface |
|
||||
| Security | `/security-review` | changes code or config, unless the full scan runs on the same change; a fix, only where it opens an untrusted-input boundary or touches authn/authz, secrets or crypto, and the full scan does not rerun on it |
|
||||
| Stability | stability-reviewer | changes code, config or tests; a fix, only where it changes behaviour: what the code or its tests do |
|
||||
@@ -86,10 +86,15 @@ Launch systems-architect: review the system as a whole entered through this chan
|
||||
|
||||
Then the principles audit: one principles-auditor for the README's goals, and one per file in `~/.claude/principles/` whose `Applies to` line the project meets, judged from the README, `git ls-files` and the branch diff. A file without the line applies to every project. Unsure → launch it.
|
||||
|
||||
Then the comprehension check. Simulated readers each read the whole project, not the diff. Launch them per `~/.claude/skills/comprehension-panel/SKILL.md` → "The scoring run" and "The paired ruling".
|
||||
Then the comprehension check: simulated readers, launched per `~/.claude/skills/comprehension-panel/SKILL.md`, each read the whole project, not the diff. It has two kinds of run.
|
||||
|
||||
- **Paired ruling**, in every architecture pass. Mid A and the inherited architect each read the project at a base commit and at this branch's head, and vote whether it reads better, the same or worse at the head. The base is the commit the last entry of the history (below) on the default branch read, so the ruling covers every chunk since then. Where that history holds no entry, or its commit is not an ancestor of the head, the base is `git merge-base origin/<default branch> HEAD` after a `git fetch`, or `<default branch>` with no remote. Two votes that agree settle the ruling. Otherwise the maintainability senior and Junior A vote too, launched together: a ruling holding two votes more than every other ruling settles it, and four votes without such a lead rule same.
|
||||
- **Scoring run**, only when the chunk ships its release's last item, leaving `todo.md` with no item for that release. Junior A, Mid A, the maintainability senior and the inherited architect each score the project at the head from 1 to 10 overall and on four dimensions: Navigation, Locality, Shape and Self-sufficiency. A seat's overall may not exceed its lowest dimension by more than 1. Each score is the mean of the four seats, to two decimals.
|
||||
**Paired ruling**, in every architecture pass. Each seat votes whether the project reads better, the same or worse at this branch's head than at the base.
|
||||
|
||||
- **Base.** The last measured commit: the newest commit on `origin/<default branch>`, after a `git fetch`, whose change to the history (below) adds a scoring run or a `Ruling: better` line. Find it with `git log -p origin/<default branch> -- docs/comprehension-history.md`; with no remote, use `<default branch>`. A ruling of same leaves the base where it was, so small falls add up until one is seen. No such commit → the merge base of the head and the default branch.
|
||||
- **Seats.** Mid A and the inherited architect. When their votes differ, the maintainability senior and Junior A vote too, launched together.
|
||||
- **Ruling.** The ruling with two votes more than every other ruling; without one, same.
|
||||
|
||||
**Scoring run**, when the chunk leaves `todo.md` with no item for a release that has work landed towards it, or ships an item whose tagline names the comprehension floor. Junior A, Mid A, the maintainability senior and the inherited architect each score the project at the head from 1 to 10 overall and on four dimensions: Navigation, Locality, Shape and Self-sufficiency. A seat's overall may not exceed its lowest dimension by more than 1. Each score is the mean of the four seats, to two decimals.
|
||||
|
||||
The chunk does not merge while either holds:
|
||||
|
||||
@@ -111,7 +116,7 @@ Put each ruling with its votes, and each run's five scores, in the summary, and
|
||||
|
||||
**Fresh.** Where the chunk ran a comprehension check, the architecture pass is done only once its last paired ruling, and its last scoring run where it ran one, read the commit to merge. They may predate commits that change only `docs/decisions.md`, `docs/comprehension-history.md`, `docs/reading-cost.md`, `todo.md` or `CHANGELOG.md`. Any other commit after them, a prose fix included, because the seats read the docs, calls for a rescore: the comprehension check again, once every other pass is done, the auto-reviewer included. A rescore reporting a 🔴 that no decision to ship answers is an architecture round. Any other rescore is not a round: append only its results to the history, in a commit titled `Rescore: …`. A `Rescore:` commit re-enters no pass: push it and wait for the forge's checks (§4 step 3), not for an auto-review.
|
||||
|
||||
**Suspended.** A decision in the project's `docs/decisions.md`, held before the chunk began, may name plan items to ship without a comprehension check. A named item counts as `todo.md` worded it before the chunk began. The decision must name the later plan item whose chunk ends the suspension with a comprehension check. A chunk may ship named items only with each other. Such a chunk skips the comprehension check, so neither the ratchet nor the floor can block it, and its summary cites the decision. A chunk shipping its release's last item runs the comprehension check, even when every item it ships is named.
|
||||
**Suspended.** A decision in the project's `docs/decisions.md`, held before the chunk began, may name plan items to ship without a comprehension check. A named item counts as `todo.md` worded it before the chunk began. The decision must name the later plan item whose chunk ends the suspension with a comprehension check. A chunk may ship named items only with each other. Such a chunk skips the comprehension check, so neither the ratchet nor the floor can block it, and its summary cites the decision. A chunk that meets the scoring run's trigger runs it, even when every item it ships is named.
|
||||
|
||||
### Security
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
|
||||
`Bar = 9`
|
||||
|
||||
`Next ID = 84`
|
||||
`Next ID = 85`
|
||||
|
||||
| Goal | W |
|
||||
|---|---|
|
||||
@@ -36,6 +36,7 @@
|
||||
| 80 | 0.1.0 | | **State in README → Install that every machine taking this checkout must be a sandbox, as `settings.json`'s auto mode assumes.** | 1 | 1 | 5 | 5 | 4 | 16.8 |
|
||||
| 83 | 0.1.0 | | **Group `bin/` by tool, so each tool's modules and tests sit together.** | 3 | 4 | 4 | 6 | 1.1 | 15.9 |
|
||||
| 5 | 0.1.0 | decision | **Key a project on its checkout's full path, and refuse to start while another session uses that key.** | 5 | 5 | 5 | 6 | 1.1 | 15.6 |
|
||||
| 84 | 0.1.0 | | **Check, at each release's scoring run, that seats in a paired ruling agree more often than two absolute runs do, as the paired-ruling decision assumes.** | 2 | 2 | 4 | 5 | 1.4 | 15.1 |
|
||||
| 67 | 0.1.0 | principle | **Point stability-reviewer at the technical principles in place of its own restatement of them.** | 2 | 3 | 4 | 5 | 1.3 | 14.9 |
|
||||
| 66 | 0.1.0 | principle | **Hold systems-architect's method thresholds only while the comprehension panel finds the flagged code hard.** | 3 | 3 | 4 | 5 | 1.1 | 14.2 |
|
||||
| 69 | 0.1.0 | principle | **Measure test coverage, so a chunk that lowers it is seen.** | 3 | 4 | 4 | 5 | 1.1 | 13.9 |
|
||||
@@ -119,6 +120,10 @@ The key names the project's session, archive folder and models entry. `project_k
|
||||
|
||||
`bin/reading-cost` keys the archive by the main checkout, the parent of git's common dir, since it runs in a chunk's worktree; `loop-claude` keys it by `--show-toplevel`, so a loop started inside a worktree archives where `reading-cost` never looks. Derive both keys one way.
|
||||
|
||||
### 84. Check, at each release's scoring run, that seats in a paired ruling agree more often than two absolute runs do, as the paired-ruling decision assumes.
|
||||
|
||||
Raised by the principles audit of PR #228: the `review: a paired ruling …` entry in `docs/decisions.md` is valid only while that holds, and `docs/comprehension-history.md` keeps every vote, yet nothing reads the agreement rate.
|
||||
|
||||
### 67. Point stability-reviewer at the technical principles in place of its own restatement of them.
|
||||
|
||||
DRY, in `principles/technical-principles.md`: `agents/stability-reviewer.md` restates principles in its own words, and the copy has drifted: it asks for "properly randomised UUIDs" where the principle requires UUID v7.
|
||||
|
||||
Reference in New Issue
Block a user