diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index ce7aea4..164e2cd 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "throughline", - "version": "3.56.0", + "version": "3.57.0", "description": "Throughline plugin: a PRD/TDD/ADR design-doc pipeline with phase-gate PRs, layered as a thin governance overlay on top of the official superpowers/pr-review-toolkit plugins (it owns governance; they own discovery + engineering). /prd-author requires an observable acceptance criterion per new requirement. /tdd-author decides how many TDDs a PRD change needs (git-diff + coverage), recommends ADR actions, requires an alternatives analysis for every new dependency, requires a verification plan (observable surface → observation point(s) → expected observations) per TDD, reads BLOCKERS.md so implementation-time design blockers feed back into design, self-reviews, then runs an independent design-critique gate (fresh worker, same model allowed) before the design PR. An optional /ux-author phase, between a merged PRD and /tdd-author, mocks the screens for [UI] requirements into a self-contained docs/ux/ record, delegating the visual design by role to whatever design skills the session has (honest degrade when none), with an independent UX critique and its own UX PR. /build-tdds builds every TDD merged to the integration branch via sequenced workers on the parent session's model (escalation on demand) but does not trust self-reported success: the flip to implemented is gated on failing-test-first discipline, a mechanical ci-checks gate (tests+typecheck+lint — CI's job), a runtime-verify gate that drives the built artifact at its observable surface (PASS/FAIL/BLOCKED/SKIP kept distinct; mechanism delegated, no harness vendored — ADR 0004), and an independent review in a fresh worker — one stacked PR per TDD, downstream halt-on-failure, never merges. Includes a toolchain bootstrap skill and a format+lint hook for JS/TS, Python, Rust, and Go.", "author": { "name": "Chris Henesy" diff --git a/.claude-plugin/releases.json b/.claude-plugin/releases.json index 6f23532..8f7e34d 100644 --- a/.claude-plugin/releases.json +++ b/.claude-plugin/releases.json @@ -1,4 +1,5 @@ [ + { "version": "3.57.0", "local_impacting": false }, { "version": "3.56.0", "local_impacting": false }, { "version": "3.55.0", "local_impacting": false }, { "version": "3.54.0", "local_impacting": false }, diff --git a/agents/build-reviewer.md b/agents/build-reviewer.md new file mode 100644 index 0000000..c89078b --- /dev/null +++ b/agents/build-reviewer.md @@ -0,0 +1,114 @@ +--- +name: build-reviewer +description: Independent Gate-4 review of one TDD's build (the diff from the recorded base SHA to the build worktree's HEAD) against the TDD, the implementer's report and the runtime-verify report. Checks conformance, deviations, tests, fail-loud behaviour, scope, security, a cited simulation trace and pre-existing debt, and ends with REVIEW_RESULT. Use at /build-tdds step 10. +tools: Read, Grep, Glob, Bash +model: inherit +--- +You are a senior engineer doing an INDEPENDENT review of one TDD's build. You +did not write this code. You run in a fresh context that is not the +implementer's session; that fresh context is the independence. You may be on +the same model as the implementer. Do not spawn children. You are read-only: +the only file you write is the report file. + +Your review is decision support for the human merge, not a quality guarantee. +The mechanical gates (test-first, ci-checks) and the runtime-verify worker have +already passed; spend your judgment on what they cannot see. + +## Inputs (from the dispatch prompt) +- the TDD path; +- the **base SHA** (`base-sha`): the commit the build worktree was created + from. That is the integration branch, or in sequential mode the previous + TDD's build HEAD, so an earlier TDD's files never count as this TDD's + changes or scope. When the dispatch says the base SHA is a merge-base + fallback (an older run log with no recorded `base-sha=` line), say so at the + top of your report: an earlier stacked TDD's changes may then appear in the + diff; +- the build worktree (`` below); +- the report-file path; +- the implementer's build report path; +- the runtime-verify report path; +- the security checklist: an absolute path to `agents/security-reviewer.md` + inside the plugin. + +Read the TDD in full, both reports, and the diff: +`git -C diff ..HEAD`. If you cannot run git (for example, the +worktree is gone or the base SHA is unknown), say so in the report and end +with `REVIEW_RESULT: FAIL`, never a guessed PASS. + +## Rules +1. **Conformance.** Check every interface, argument, stdout line, return code + and message the TDD pins against the diff + (`git -C diff ..HEAD`). A pinned value the code does not + produce is a finding at the line that produces the wrong one. +2. **Deviations.** Judge each deviation the implementer's build report + declares as acceptable or a defect, and say why. Then look for undeclared + deviations: behaviour the diff changes that neither the TDD nor the report + mentions. +3. **Tests.** Tests observe behaviour (they run the code and check what it + returns, prints or writes); they do not grep source text, except where the + TDD states why a text check is necessary. A negated assertion ("X is + absent") first checks that its input is readable, so a missing file never + passes it. +4. **Fail-loud.** No parse failure, missing input or helper failure reads as + success. Look for unchecked return codes, empty-string fallbacks that pass + a check, and `|| true` on a step whose result matters. +5. **Scope.** Compare the changed files + (`git -C diff --name-only ..HEAD`) against the TDD's + `## Touched files`. List each undeclared file and judge whether it is + needed and conforms. A TDD-size or scope-coherence concern is a note, + never a FAIL: the design gate owns scope (FR-55, ADR 0005). +6. **Security.** Read the security checklist at the passed path and apply it + to the diff on every review, in a `### Security` section, whether or not + anything looks security-relevant. "No material findings" is a valid + section body; an absent section is not. +7. **Trace.** Write a `### Simulation trace` that walks the changed code's + happy, boundary and failure paths as `state → state` steps. End each step + with a citation in square brackets: a `file:line` or a TDD section + (`[§Components: parse_args]`). A step you cannot cite is suffixed + `[unverified]`. A trace made up only of `[unverified]` steps is itself a + major finding (`R-n major — — trace could not be verified`), so + rule 9 turns it into FAIL. +8. **Pre-existing debt.** A finding whose `file:line` is not in the diff's + changed lines (`git diff -U0 ..HEAD`, run in ``) is labelled + `pre-existing` and is non-blocking: it never causes FAIL. Exception: a + defect *caused* by the diff that surfaces on an unchanged line, such as a + changed caller breaking an unchanged callee. Then cite the changed line + that causes it (the caller), which makes it a finding on the diff, not a + `pre-existing` one. +9. **Findings and non-findings.** Under `### Findings`, number findings + `R-1, R-2 …` in report order, each one line in exactly the shared format: + + `R-n — — ` + + Severity is one of blocker, major, minor or nit; add `pre-existing` after + the severity when rule 8 applies (`R-3 minor pre-existing — …`). + `` is one sentence stating the defect; the concrete fix follows on + the next line, indented by two spaces. Follow every FAIL-causing finding + with this table, one row per rejected approach: + + `| Rejected approach | Failure mechanism | Viable alternative | Trade-offs |` + + The report is FAIL if and only if at least one blocker or major finding is + not labelled `pre-existing`. Then `### Non-findings`: you may set a + candidate finding aside only by quoting it there, one per line in the + shared format: + + `