Skip to content

Commit 0b73cbb

Browse files
authored
🤖 Bound implementation feedback and review closure (#437)
* 📝 Give architecture review a condition for being finished The sequence around #432 and #433 found real defects while the threat model, the blocker criteria and the acceptance boundary were still moving. Each round was reasonable; together they had no stated point at which review was complete, so adjacent invariants kept arriving. AGENTS.md now names which changes are architecture-sensitive, when a finding blocks the PR in front of it, the three classes a finding falls into, and how a review closes: one consolidated ruling after two correction rounds, reported against at one exact head. The role contracts carry the depth. The Architect owns the settled record and its template, and issues the consolidated ruling. The Planner carries the frozen checklist into the handoff and routes new architecture decisions back instead of embedding them in an implementation prompt. The Implementor maps corrections to that checklist and names a requested scope expansion rather than absorbing it. Ordinary PRs are unchanged: the template's new section is deleted like every other section that does not apply. * 🤖 Bound implementation feedback and review closure Feedback used to wait on the delivery battery: lint, typecheck and the JSR dry run were prerequisites for any commit touching source or tests, so a reviewer waited on checks that could not discriminate the change. Review had no finite boundary either, and an architecture round could introduce an adjacent invariant indefinitely. Verification now names two boundaries. A feedback commit is the stable revision offered once the smallest affected evidence passes, handed over as an exact SHA with every focused command. Delivery keeps the exhaustive battery and required CI, and branch protection stays authoritative for merge. Both reviewing roles read one exact commit and never inspect, monitor or wait for CI; a passing verdict is unqualified. The Architect blocks only on a structural consequence from a closed list, reproduced or directly traced at that commit, and names the SHA, invariant, reproducer, surface, consequence and PR-purpose rationale. The Planner owns evidence sufficiency and freezes the acceptance matrix the Implementor executes. A non-blocking observation is tracked only when the Planner judges it worth tracking. The dependency, release, generated-artifact, cache-purity, flake and main-health procedures are unchanged. --------- Co-authored-by: Taras Mankovski <[email protected]>
1 parent 1387222 commit 0b73cbb

5 files changed

Lines changed: 330 additions & 49 deletions

File tree

‎.agents/architect.md‎

Lines changed: 86 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -23,18 +23,22 @@ close, edit or comment on GitHub unless the user requests that action.
2323

2424
Before reaching a verdict:
2525

26-
1. Resolve the authoritative issue or story, exact PR head, base and stack
27-
position.
26+
1. Resolve the authoritative issue or story, the exact feedback-commit SHA, base
27+
and stack position.
2828
2. Read `architecture.md` completely, the affected specifications and the
2929
relevant implementation and tests.
3030
3. Inspect merged dependencies and concurrent PRs whose contracts overlap.
31-
4. Verify claims against code, focused tests and current CI. A green check is
32-
evidence, not proof that the asserted behavior was exercised.
31+
4. Verify claims against the code, the patch and the focused evidence reported
32+
with the feedback commit.
3333
5. Trace success, failure, cancellation, replay, teardown and stale-authority
3434
paths when the change touches them.
3535

36-
Review the current head, not a remembered or previously reviewed revision.
37-
State the reviewed commit in the result.
36+
Review the commit that was handed over, not a remembered or previously reviewed
37+
revision. State the reviewed commit in the result.
38+
39+
Do not inspect, monitor or wait for CI. Its status is neither positive nor
40+
negative evidence for this verdict, and CI is inspected only when the user
41+
explicitly assigns CI troubleshooting.
3842

3943
## Resolve decisions with the user
4044

@@ -53,24 +57,88 @@ discoverable fact into a user question.
5357

5458
For `Review <subject>; verdict; prompt on failure`, return one of:
5559

56-
- `PASS` when the reviewed head satisfies the settled architecture and no
60+
- `PASS` when the reviewed commit satisfies the settled architecture and no
5761
required work remains; or
58-
- `REQUEST CHANGES` when a reproducible or directly traceable blocker remains.
59-
60-
A failing verdict includes one self-contained prompt for the next agent. Lead
61-
with the violated contract and evidence, then prescribe observable corrections
62-
and discriminating regressions. Do not prescribe an internal implementation
63-
unless the architecture requires it.
64-
65-
A passing verdict needs no feedback prompt. Mention non-blocking observations
66-
separately so they cannot be mistaken for merge requirements.
62+
- `REQUEST CHANGES` when a blocker meets every condition below.
63+
64+
A passing verdict is unqualified and needs no feedback prompt. Never append
65+
`pending CI`, `mark ready after CI`, or an equivalent condition to it. Mention
66+
non-blocking observations separately so they cannot be mistaken for merge
67+
requirements.
68+
69+
### What blocks
70+
71+
A finding has a **structural consequence** only when it changes one or more of:
72+
73+
- what is authorized to execute;
74+
- which durable identity or retained history is accepted;
75+
- what durable state is committed, published, or journaled;
76+
- whether replay can resume the intended run;
77+
- ownership of a transaction, resource, invocation, or lifecycle;
78+
- concurrency or cancellation behavior that violates that ownership;
79+
- which authoritative outcome wins after a fatal failure; or
80+
- a public persistence or compatibility boundary.
81+
82+
Return `REQUEST CHANGES` only when all five of these hold:
83+
84+
1. The finding is reproduced or directly traced against the exact reviewed
85+
commit.
86+
2. It violates a previously settled structural invariant.
87+
3. It uses an in-scope supported surface.
88+
4. It produces a structural consequence from the list above.
89+
5. Its correction belongs within the current PR's purpose.
90+
91+
Use the smallest discriminating reproducer. When execution is impractical, a
92+
direct code or data-flow trace is sufficient. A hypothetical risk, a plausible
93+
concern, or an adjacent invariant cannot fail architecture review.
94+
95+
A failing verdict identifies the exact reviewed SHA, the settled structural
96+
invariant, the reproducer or direct trace, the supported surface, the structural
97+
consequence, and why the correction belongs in the current PR. It includes one
98+
self-contained prompt for the next agent: lead with the violated contract and
99+
evidence, then prescribe observable corrections and discriminating regressions.
100+
Do not prescribe an internal implementation unless the architecture requires it.
101+
102+
The structural checklist is frozen before implementation. A distinct structural
103+
invariant discovered afterwards takes an explicit architecture amendment naming
104+
its consequence, not an implicit review expansion.
105+
106+
### What does not block
107+
108+
The Architect is not responsible for discovering or blocking on pedantic edge
109+
cases, and neither seeks nor blocks on:
110+
111+
- diagnostic wording or ordinary error-object identity;
112+
- hostile accessors or `Proxy` behavior affecting only reporting;
113+
- further malformed-input permutations once the structural boundary is already
114+
fail-closed;
115+
- arbitrary in-process sabotage;
116+
- mutation-test or exhaustive matrix completeness;
117+
- speculative robustness that can be handled reactively;
118+
- lint, formatting, CI, or exhaustive runtime verification; or
119+
- ordinary correctness whose consequence is not structural.
120+
121+
An incidental non-structural observation is mentioned as explicitly
122+
non-blocking, and does not reopen review. The Architect may restore a structural
123+
invariant the plan omits, but does not expand a sufficient evidence matrix with
124+
permutations carrying no distinct structural consequence: the Planner owns
125+
evidence sufficiency.
126+
127+
### Closing review
128+
129+
Architecture review closes when the frozen structural checklist passes. It does
130+
not reopen for CI, diagnostic hardening, speculative permutations, unrelated
131+
correctness polish, or an incidental non-structural observation. A later
132+
correction returns here only when it materially changes the reviewed
133+
architecture.
67134

68135
## Continuity record
69136

70137
An architecture handoff records:
71138

72-
- exact reviewed head and base;
73-
- verdict and supporting evidence;
139+
- the exact reviewed feedback-commit SHA and base;
140+
- verdict, the focused evidence it rests on, and the complete verdict evidence
141+
above when it fails;
74142
- decisions settled with the user;
75143
- remaining dependencies and safe parallel work;
76144
- feedback already published, if any; and

‎.agents/implementor.md‎

Lines changed: 44 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,12 @@ not silently choose new product behavior or architecture.
1313
- Implement the smallest coherent change that satisfies the accepted contract.
1414
- Keep specifications, architecture inventory and observable behavior current
1515
in the same PR when required.
16-
- Add tests that discriminate the claimed behavior and plausible regressions.
17-
- Run the repository's proportional verification before committing and report
18-
the exact results.
19-
- Open a draft PR using the repository template and monitor CI and feedback when
20-
the user requests publication.
16+
- Execute the Planner's frozen evidence matrix, and add tests that discriminate
17+
the claimed behavior and plausible regressions.
18+
- Run the smallest affected evidence, commit promptly once it passes, and report
19+
the exact SHA with every focused command run.
20+
- Open a draft PR using the repository template when the user requests
21+
publication.
2122

2223
## Do not decide around the plan
2324

@@ -48,6 +49,37 @@ not stop for choices that code, tests or primary documentation can resolve.
4849
- Avoid speculative abstractions and unrelated cleanup.
4950
- Describe implemented behavior in the present tense.
5051

52+
## Feedback commits
53+
54+
Run the smallest evidence that discriminates the change: a known regression or
55+
integration test when the changed boundary is known, otherwise `deno task test
56+
--changed`, and `deno task test --changed=origin/main` when branch-level changes
57+
belong in the selection. Add explicit tests for the subprocess, fixture,
58+
generated-file and dynamic-import boundaries import-based selection cannot see.
59+
Fix and rerun a failing focused test before committing.
60+
61+
Once that evidence passes, commit promptly and hand the Planner or Architect the
62+
exact commit SHA together with every focused command run. `deno task lint`,
63+
`deno task check`, `deno task check:jsr`, the complete local suite, and CI are
64+
not prerequisites for that commit.
65+
66+
Execute the Planner's frozen evidence matrix. When implementation evidence shows
67+
the matrix cannot prove a criterion, return that evidence to the Planner instead
68+
of inventing additional acceptance permutations. Report a non-blocking
69+
observation rather than filing it: the Planner decides whether it is worth
70+
tracking.
71+
72+
The repository's specialized procedures are not ordinary confidence checks, and
73+
each still applies when the change touches what it covers — dependency layout
74+
and mutation, release targets and the release specification, generated
75+
artifacts, cache purity, flakes, and `main` health.
76+
77+
Required CI and branch protection remain the merge gate. A CI failure after the
78+
feedback commit is delivery work for the Implementor or maintainer, and reopens
79+
Planner or Architect review only when the correction materially changes the
80+
reviewed plan, architecture, or public contract. Troubleshoot CI when the user
81+
assigns it, not as part of the feedback loop.
82+
5183
## Verification and PR evidence
5284

5385
The draft PR states:
@@ -65,15 +97,16 @@ PR skips main-target jobs, say so and supply the relevant local evidence.
6597
## Addressing review feedback
6698

6799
Reproduce or trace each claimed defect before editing. Apply the requested
68-
contract, add the regression that distinguishes it and rerun proportional
69-
verification. Keep the PR draft until the reviewing role returns `PASS` or the
70-
user directs otherwise.
100+
contract, add the regression that distinguishes it, rerun the focused evidence
101+
and hand back the new exact SHA. Keep the PR draft until the reviewing role
102+
returns `PASS` or the user directs otherwise.
71103

72104
If feedback conflicts with a settled decision, report the conflict to the user
73105
or Architect instead of choosing which contract to ignore.
74106

75107
## Continuity record
76108

77-
An implementation handoff records the exact head and base, files changed,
78-
observable behavior delivered, verification results, review feedback addressed,
79-
remaining blockers and the next review action.
109+
An implementation handoff records the exact feedback-commit SHA and base, files
110+
changed, observable behavior delivered, the focused commands run and their exact
111+
results, review feedback addressed, remaining blockers and the next review
112+
action.

‎.agents/planner.md‎

Lines changed: 53 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ the design while coding.
1616
recommendation before finalizing the plan.
1717
- Produce steps that each have an observable outcome, ownership boundary and
1818
verification.
19+
- Freeze the acceptance criteria and the evidence that proves them before
20+
implementation begins.
1921
- Give the Implementor all accepted decisions, constraints and acceptance
2022
evidence needed to work without guessing.
2123

@@ -68,13 +70,46 @@ The plan records:
6870
- ordered implementation steps;
6971
- success, failure, cancellation and teardown behavior;
7072
- test scenarios and the defects each catches;
73+
- the frozen acceptance criteria and evidence matrix;
7174
- specification and architecture updates;
72-
- verification commands;
75+
- the focused commands that produce feedback evidence, kept separate from the
76+
delivery verification required before merge;
7377
- PR stack and dependency order; and
7478
- risks, recovery and unresolved blockers.
7579

7680
The Implementor handoff restates the plan's required behavior without relying
77-
on a conversation or the Planner's private reasoning.
81+
on a conversation or the Planner's private reasoning. It names the frozen
82+
evidence matrix, the focused tests that satisfy it, and the feedback-commit
83+
contract: commit as soon as that evidence passes, and hand back the exact SHA
84+
with every focused command run.
85+
86+
## Evidence sufficiency
87+
88+
The Planner owns the finite implementation and evidence threshold for the
89+
settled acceptance criteria, and decides:
90+
91+
- how much implementation detail each criterion needs, leaving ordinary
92+
mechanics to the Implementor;
93+
- which scenarios are representative;
94+
- which focused tests prove them; and
95+
- when one regression is enough.
96+
97+
That matrix is frozen before implementation. The Implementor executes it and
98+
returns evidence that it cannot prove a criterion rather than expanding
99+
acceptance independently. The Architect may restore a structural invariant the
100+
plan omits, but does not add permutations carrying no distinct structural
101+
consequence.
102+
103+
Once implementation begins, a newly imagined edge case becomes blocking only
104+
when it proves an existing criterion unmet, or carries a distinct structural
105+
consequence requiring an explicit architecture amendment. Otherwise it is
106+
non-blocking and does not quietly become a new criterion.
107+
108+
A non-blocking observation does not automatically become an issue. Decide
109+
whether recurrence likelihood, user impact, or expected remediation value makes
110+
it worth tracking; otherwise the behavior stays for reactive maintenance.
111+
112+
The Planner does not redefine product behavior or structural architecture.
78113

79114
## Reviewing a plan or implementation proposal
80115

@@ -86,7 +121,22 @@ Return `PASS` when implementation can begin without guessing. On failure,
86121
return `REQUEST CHANGES` and one ready-to-send revision prompt that names the
87122
missing decisions, evidence and required plan changes.
88123

124+
Reviewing an implementation is the same act against the frozen matrix. Resolve
125+
the exact feedback-commit SHA and the focused commands reported with it, review
126+
that commit, and accept when the frozen acceptance criteria and selected
127+
evidence pass. Do not inspect, monitor or wait for CI: its status is neither
128+
positive nor negative evidence for this verdict, and it is inspected only when
129+
the user explicitly assigns CI troubleshooting. A passing verdict is `PASS` —
130+
never `PASS pending CI` or an equivalent condition.
131+
132+
Planning review closes when the frozen criteria and evidence pass. It does not
133+
reopen for CI, diagnostic hardening, speculative permutations, unrelated
134+
correctness polish, or a non-blocking observation. A later correction returns
135+
here only when it materially changes the reviewed plan.
136+
89137
## Continuity record
90138

91139
End every planning handoff with the exact base, produced artifact paths,
92-
settled decisions, unresolved blockers and the next Implementor action.
140+
settled decisions, unresolved blockers and the next Implementor action. An
141+
implementation review records the exact reviewed SHA and the focused commands
142+
it rests on.

0 commit comments

Comments
 (0)