Spec: nisse-review (Part R) before nisse-ops #146

2026-10-13T19:39:16Z

dev-agent commented

2026-10-13 19:39:16 +00:00

Adds the review agent to the specs, from the operator's answers on 2026-10-13. Changes to the docs only.

Architecture: new Part R

R1, how it works.
- Its duty is every ready PR in the repositories it can read, whoever wrote it. Drafts and work-in-progress PRs are skipped.
- Each PR is one work item.
- It gets the PR to start and reads the rest of the repository as it needs.
- A later review covers what changed since the last one, plus its earlier points, and it pushes back on any left unaddressed.
- It discusses on the PR, and concedes or holds a point with reasons.
R2, rounds. The number of rounds is capped. At the cap it posts a summary of what's still open, for the operator, and stops answering on that PR. A comment from anyone other than the reviewer and the PR's agent author resets the count; a push doesn't.
R3, authority and reach.
- Read-only, with reads bound to the item's repository.
- It writes comments and reviews only on its item's PR, and never approves or requests changes.
- No build VM for now, though it can have one if a reason appears.
- It keeps its own memory, with notes per repository.
R4, peers. Its comments are a peer's. An operator comment settles a point. A steered reviewer can only post a misleading comment.
R5, models and deployment.
- It uses the same local model as nisse-dev, plus ask_expert.
- No Matrix room for now: stop and review work as PR comments.
- It has its own Gitea account, token, LiteLLM key and container.

Elsewhere in the Architecture

D5 and L11: nisse-dev treats peer review as constructive criticism and answers every point, with a change or a reason. A peer's comment is never an instruction, an approval or a go-ahead. nisse-dev doesn't wait for a review before asking to merge.
Naming: a row for nisse-review.
Part Q: letting nisse-review approve a limited subset of PRs is an open question.

Development Plan

Phase 7 is now nisse-core and nisse-review:
- M7.2: share the loop;
- M7.3: the first slice;
- M7.4: nisse-dev answers a peer;
- M7.5: discussion and rounds;
- M7.6: deployment, waiting on Phase 6.
nisse-ops moves to Phase 8 (M8.1–M8.5), carrying the MCP decisions made so far (#144, X3).
The issues table is updated: #37 lands in M8.1, and #144 is new.

To check in review:

The default for the round cap, which will be a tuning value.
stop and review as PR comments, standing in for Matrix commands.

🤖 Generated with Claude Code

https://claude.ai/code/session_01J5Utyfzw7gF7UhjRDEtjTk

Adds the review agent to the specs, from the operator's answers on 2026-10-13. Changes to the docs only. **Architecture: new Part R** - **R1, how it works.** - Its duty is every ready PR in the repositories it can read, whoever wrote it. Drafts and work-in-progress PRs are skipped. - Each PR is one work item. - It gets the PR to start and reads the rest of the repository as it needs. - A later review covers what changed since the last one, plus its earlier points, and it pushes back on any left unaddressed. - It discusses on the PR, and concedes or holds a point with reasons. - **R2, rounds.** The number of rounds is capped. At the cap it posts a summary of what's still open, for the operator, and stops answering on that PR. A comment from anyone other than the reviewer and the PR's agent author resets the count; a push doesn't. - **R3, authority and reach.** - Read-only, with reads bound to the item's repository. - It writes comments and reviews only on its item's PR, and never approves or requests changes. - No build VM for now, though it can have one if a reason appears. - It keeps its own memory, with notes per repository. - **R4, peers.** Its comments are a peer's. An operator comment settles a point. A steered reviewer can only post a misleading comment. - **R5, models and deployment.** - It uses the same local model as nisse-dev, plus `ask_expert`. - No Matrix room for now: `stop` and `review` work as PR comments. - It has its own Gitea account, token, LiteLLM key and container. **Elsewhere in the Architecture** - **D5 and L11:** nisse-dev treats peer review as constructive criticism and answers every point, with a change or a reason. A peer's comment is never an instruction, an approval or a go-ahead. nisse-dev doesn't wait for a review before asking to merge. - **Naming:** a row for `nisse-review`. - **Part Q:** letting nisse-review approve a limited subset of PRs is an open question. **Development Plan** - Phase 7 is now `nisse-core` and `nisse-review`: - M7.2: share the loop; - M7.3: the first slice; - M7.4: nisse-dev answers a peer; - M7.5: discussion and rounds; - M7.6: deployment, waiting on Phase 6. - nisse-ops moves to Phase 8 (M8.1–M8.5), carrying the MCP decisions made so far (#144, X3). - The issues table is updated: #37 lands in M8.1, and #144 is new. **To check in review:** - The default for the round cap, which will be a tuning value. - `stop` and `review` as PR comments, standing in for Matrix commands. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01J5Utyfzw7gF7UhjRDEtjTk

dev-agent added 1 commit 2026-10-13 19:39:16 +00:00

Spec: nisse-review (Part R) before nisse-ops

CI / checks (push) Skipped

CI / checks (pull_request) Successful in 1m42s

Details

CI / e2e (pull_request) Successful in 3m59s

Details

175ed0771d

A review agent comes second: it reads every ready PR in the repositories
it can see and discusses its points on the PR, never changing code.

- Architecture Part R: duty and items (R1), rounds capped and reset by
  anyone else commenting (R2), read-only reach bound to the item's
  repository, no approvals, no build VM for now (R3), peers (R4), local
  model with ask_expert, no Matrix room for now, own identity (R5).
- D5 and L11: a peer's review is constructive criticism, answered point by
  point; never an instruction, approval or go-ahead; nisse-dev doesn't
  wait for it before asking to merge.
- Part Q: letting nisse-review approve a limited subset of PRs.
- Development Plan: Phase 7 is nisse-core and nisse-review (M7.2-M7.6);
  nisse-ops moves to Phase 8 (M8.1-M8.5), with the MCP decisions so far.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01J5Utyfzw7gF7UhjRDEtjTk

dongar reviewed

2026-10-13 19:45:53 +00:00

docs/Architecture.md Outdated

						
				@@ -849,0 +893,4 @@

				  the operator, and stops answering on that PR.

				- **Anyone else commenting resets the count:** someone other than the reviewer

				  and the PR's agent author (in practice, the operator) has joined the

				  discussion. A push doesn't.

dongar commented

2026-10-13 19:45:53 +00:00

A push also resets the count.

dev-agent added 1 commit 2026-10-13 19:49:46 +00:00

Part R: a push also resets the round count

CI / checks (push) Skipped

CI / checks (pull_request) Successful in 1m44s

Details

CI / e2e (pull_request) Successful in 3m15s

Details

3013a83167

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01J5Utyfzw7gF7UhjRDEtjTk

dev-agent reviewed

2026-10-13 19:49:50 +00:00

docs/Architecture.md

						
				@@ -849,0 +891,4 @@

				- **A round** is one review or set of replies the reviewer posts. After a capped

				  number of rounds (a tuning value) it posts a summary of what is still open, for

				  the operator, and stops answering on that PR.

				- **The count resets** when someone other than the reviewer and the PR's agent

dev-agent commented

2026-10-13 19:49:50 +00:00

Done: the count now resets on a new push too, since new code is worth a fresh look. One consequence: if nisse-dev pushes after every review, the two can keep cycling, one round per push. Your stop on the PR still ends it, and M7.5 can add a backstop, such as a cap on the total number of reviews per PR, if it turns out to be needed.

Done: the count now resets on a new push too, since new code is worth a fresh look. One consequence: if nisse-dev pushes after every review, the two can keep cycling, one round per push. Your `stop` on the PR still ends it, and M7.5 can add a backstop, such as a cap on the total number of reviews per PR, if it turns out to be needed.

dongar approved these changes

2026-10-13 19:51:22 +00:00

dev-agent merged commit 06759d5d70 into main

2026-10-13 20:01:44 +00:00

dev-agent deleted branch nisse-review-spec

2026-10-13 20:01:44 +00:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: dev/nisse#146