@jwilger/pi-development-system 0.87.0 → 0.89.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Wilger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,9 +1,25 @@
 # pi-development-system
 
 A [pi](https://pi.dev) extension package representing my seasoned approach to
-software development using a full AI SDLC.
+software development using a full AI SDLC: work is sized, planned in proportion, built
+test-first in small slices, reviewed by fresh-context reviewers and delivered by trunk-based
+commits. Guards enforce what must hold; the rest is guidance with a recorded way out.
 
-> **Status:** under construction (see `docs/plan/development-system-plan.md`).
+## Install
+
+```sh
+pi install npm:@jwilger/pi-development-system
+```
+
+Then `/reload`. To move to a newer release use
+`pi install npm:@jwilger/pi-development-system@<version>`.
+
+Jev, the classifier behind the judgements, is optional. Without a credential configured, the checks
+that rest on a judgement do not run or fall back to a default: the motive behind a test change, whether a
+diff needs an ADR, the quality of a commit rationale and whether a commit mixes changes, the intent
+nudges, the verifier's check of the agent's own claims, and the lens and severity choices in review.
+The status line shows `jev offline` when that is so. Everything deterministic holds without Jev: the
+hard stops, the delivery mode, the review streak, red-first and the slice life cycle.
 
 ## Replaces pi-subagent-manager
 
@@ -22,16 +38,26 @@ what the current phase expects. When you say a slice is finished with no review
 it tells you to start one. The slash commands (`/devsys-start`, `/devsys-plan`, `/devsys-review`,
 `/devsys-lens-review`, `/devsys-adr`, `/devsys-event-model`) are shortcuts to the same tools.
 
+Skills cover the habits behind the gates: `tdd-canon`, `behaviour-tests`, `semantic-types`,
+`typed-errors`, `functional-core-imperative-shell`, `strict-lints`, `delivery-discipline`, `delegation`,
+`code-review`, the language profiles (`profile-rust`, `profile-typescript`), `profile-design-system` for UI
+work (tokens, then components; build from the design system's materials and log a snowflake),
+`threat-modelling` (proportional; a document only when the risk earns it) and the planning skills below.
+
 Product planning has a skill (`product-planning`: brief, decision register, follow-ups,
 terminology, journeys). `devsys_lens_review` plans a review of the brief by five product lenses and
 writes the packets to `docs/product/reviews/`; `devsys_adr_new` creates the next numbered ADR, and
 a commit that shapes the architecture without one is stopped by the soft gate `adr.missing`.
 
+A reviewer subagent hands over its result with `devsys_submit_review` (typed arguments; a result that
+contradicts itself or is for the wrong round is refused with an error id), and `devsys_review_record`
+reads it. A markdown packet is still accepted (ADR 0006).
+
 Event modelling has a skill (`event-modelling`: three slice patterns, Given/When/Then, completeness).
 `devsys_event_model_check` validates a directory of slice files (schema v1) and renders the swimlane
 Markdown or a Mermaid diagram; each profile's `gwt-tests` reference turns scenarios into failing tests.
 A dedicated extension that offers `event_model_validate`, or `event_model.provider` in
-`.development-system.toml`, replaces the builtin tool (`docs/event-model-extension-contract.md`).
+`.development-system.toml`, replaces the builtin tool ([contract](https://github.com/jwilger/pi-development-system/blob/main/docs/event-model-extension-contract.md)).
 
 A slice has a life cycle: `implementing` → `reviewing` (when a review round starts) → `delivering`
 (review satisfied) → `idle`. Editing production source while delivering reopens `implementing`,
@@ -48,6 +74,95 @@ With `codemode` enabled (`"defaultTools": ["+codemode"]` in pi settings), rarely
 reached through scripts and the `judge_*` Jev wrappers exist for scripts only; without codemode
 the rarely used tools are declared directly and the wrappers are absent.
 
+## Configuration
+
+`.development-system.toml` at the repository root (version 1). Every key is optional; an unknown
+key is an error that names it. `/devsys-models` writes the `[models]` table for the models this
+machine can use.
+
+| Table | Keys | Meaning |
+| --- | --- | --- |
+| `[delivery]` | `mode` (`trunk`, `pull-request`, `local-only`), `trunk`, `remote` | Where work lands; the push guard follows it. `local-only` blocks every push. |
+| `[review]` | `required_clean_rounds` (3), `min_rounds` (1) | The clean streak a slice needs before commit. |
+| `[tracker]` | `kind` (`repo-files`, `github`; `jira` and `linear` are not implemented), `repo` | Backlog for `devsys_work_item`. |
+| `[profiles]` | `override` | Languages to apply (`rust`, `typescript`); empty means detect. |
+| `[models]` | one ordered candidate list per slot | See Model tiers below. |
+| `[routing]` | `"<difficulty>/<risk>" = ["<slot>", "<thinking level>"]` | What `devsys_route_task` recommends for a subagent. |
+| `[verifier]` | `max_per_session` (6) | Cap on Jev checks of the agent's own claims. |
+| `[cadence]` | `push_minutes` (60) | Minutes without a push before the cadence nudge. |
+| `[event_model]` | `provider` (`builtin`) | Another provider replaces the builtin validator. |
+
+## Model tiers
+
+Models are asked for by slot, never by id. Three capability tiers (`frontier`, `strong`, `fast`)
+and role slots built on them (`planning`, `advisor`, `implementer`, `reviewer`, `lens`,
+`researcher`, `jev`). A slot is an ordered list of candidates: `provider/id`, a family pattern
+such as `provider/gpt-*-sol` (the newest available id wins) or a slot reference such as `@strong`.
+The first candidate this machine has credentials for is used, so one committed file works across
+accounts. Pin an exact id to stop it rolling forward. `devsys_models` shows what each slot
+resolves to, and the system recommends a model for a phase but never switches yours.
+
+## Enforcement tiers
+
+- **Hard stops** fire for the non-negotiables (`principles/NON-NEGOTIABLES.md`): rewriting
+  published history, force-pushing, deleting remote branches, discarding work with `reset --hard`,
+  `--no-verify`, forbidden commit trailers, pushing onto a red trunk, breaking the delivery mode.
+  Only the user can approve one, once, and only with a UI: a headless run refuses.
+- **Soft gates** guard the defaults (`principles/DEFAULTS.md`): weakening tests, commit rationale,
+  mixed commits, red-first, lint suppression, an unreviewed slice, scope, model for the phase, a
+  skipped planning artifact, a missing ADR. A soft gate is passed by recording a departure with
+  `devsys_record_departure` (what, why, cost if wrong, how long it applies).
+- **Guidance** covers everything else: skills and the phase guide, never enforced.
+
+What the tiers do not cover, so you can decide what to trust:
+
+- **Subagents run unguarded.** A child session is started without extensions, so none of the guards
+  runs inside it. The coordinator commits, pushes and delivers; a subagent's prompt tells it not to,
+  and the coordinator reviews what it produced.
+- **The red-trunk stop needs `gh`.** It reads CI through an authenticated `gh`; where `gh` is missing
+  or offline the trunk reads as unknown and the push is not stopped on that ground.
+- **A departure is the agent's own call.** `devsys_record_departure` waives a soft gate (also with no
+  UI) and is written to the decision log; it is never available for a hard stop.
+- **Gating starts at `devsys_intake`.** With no slice open, the review and red-first gates are off.
+- **Editing gate configuration is not guarded** (`biome.json`, hooks, CI files); review catches it.
+
+## Decision log
+
+Every departure and approval is appended to `docs/decisions/YYYY-MM.md` in the repository, so the
+reasons survive compaction and are reviewable. Architecture-shaping decisions get an ADR in
+`docs/adr/` (`devsys_adr_new`); product decisions go in the decision register that the
+`product-planning` skill describes.
+
+## Commands
+
+All of them are shortcuts to tools; none is required.
+
+| Command | Does |
+| --- | --- |
+| `/devsys-start` | Size the work and propose the artifacts it needs. |
+| `/devsys-plan` | Plan a capability or product, then begin work once approved. |
+| `/devsys-review` | Run a fresh-context review round. |
+| `/devsys-lens-review` | Five product lenses review the brief. |
+| `/devsys-adr` | Create the next ADR. |
+| `/devsys-event-model` | Validate and render an event model. |
+| `/devsys-models` | Write the model matrix for this machine (`--check` to verify). |
+| `/devsys-ci` | Watch CI for the pushed commit. |
+| `/devsys-status` | Phase, slice, review streak, departures and Jev status. |
+| `/agents` | The vendored subagent manager. |
+
+## Agents
+
+Spawn with `agent_spawn`; `devsys_route_task` picks the model and thinking level. `advisor` gives
+read-only decision support, `implementer`, `coder` and `tasker` build (one task record each),
+`reviewer` reviews a diff in fresh context and submits through `devsys_submit_review`,
+`researcher` reads and cites, `architect` and `writer` design and draft, and the five `lens-*`
+agents (Cagan, Torres, Pichler, Perri, Rumelt) review a product brief.
+
+## Changelog
+
+`CHANGELOG.md` is generated from the commit history by `npm run changelog`. A release is the commit that
+changes the version, so run it after that commit exists; the file lists what has been committed so far.
+
 ## Development
 
 ```sh

package/agents/coder.md

@@ -46,7 +46,7 @@ You are a coder. You own a change, whether a feature, refactor, bug fix, or fron
 
 ## Boundaries
 
-- bash is not a sandbox. Use it to inspect, build, test, and run project tooling. Do not commit, push, install dependencies, or touch the network unless the task says to. Other agents may be editing this tree, so do not revert or restyle their changes.
+- bash is not a sandbox. Use it to inspect, build, test, and run project tooling. Do not commit, push, install dependencies, or touch the network unless the task says to. In this session no devsys guards run in your session, so the repository's rules are yours to keep: never weaken, skip or delete a test to get green, never add a lint suppression without a stated reason, never commit secrets, and leave commits, pushes and history to the coordinator. Other agents may be editing this tree, so do not revert or restyle their changes.
 - You cannot delegate. Send agent_update only when the plan changes or a failure is not obvious. If a missing decision, missing access, an exhausted budget, or a stalled investigation blocks you, call agent_pause with the evidence and stop.
 
 ## Handback

package/agents/reviewer.md

@@ -18,6 +18,7 @@ tools:
     - find
     - ls
     - agent_update
+    - devsys_submit_review
     - agent_pause
 ---
 
@@ -41,7 +42,7 @@ Do not modify files. bash is not a sandbox: use it only for read-only inspection
 
 ## Output
 
-Use exactly this packet; the coordinator parses it.
+Submit your result by calling `devsys_submit_review` (slice and round exactly as the task gives them): it checks the call and refuses a self-contradicting one with an error id, which you correct and resubmit. After it accepts, end with one short line. Only when that tool is not available, return exactly this packet instead; the coordinator parses it.
 
 ```markdown
 ## Review — <slice> — round <n> — lenses: <a, b>

package/agents/tasker.md

@@ -56,3 +56,5 @@ Run a proportionate check: the one the task specifies, else a focused test, comm
 - **Gaps**: anything unverified or left for another role.
 
 Send agent_update only when criteria are met, a check fails, or scope is expanding. If blocked, call agent_pause with the blocker and stop.
+
+In this session no devsys guards run in your session, so the repository's rules are yours to keep: never weaken, skip or delete a test to get green, never add a lint suppression without a stated reason, never commit secrets, and leave commits, pushes and history to the coordinator.

package/extensions/development-system.ts

@@ -35,6 +35,8 @@ import { createFinishSliceTool, registerSliceClose } from "../src/planning/slice
 import { createTaskCheckTool } from "../src/planning/task-check-tool.ts";
 import { createLensReviewTool } from "../src/review/lens-review-tool.ts";
 import { createReviewRecordTool, createReviewStartTool } from "../src/review/review-tools.ts";
+import { createSubmissionStore } from "../src/review/submissions.ts";
+import { createSubmitReviewTool } from "../src/review/submit-tool.ts";
 import { registerCiCommand } from "../src/state/ci-command.ts";
 import { loadConfig } from "../src/state/config.ts";
 import { createModelsTool, registerModelsCommand } from "../src/state/models-command.ts";
@@ -186,13 +188,16 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
     createLensReviewTool({ state, jev: (ctx) => jevHolder.forContext(ctx), now: () => new Date() }),
   );
   pi.registerTool(createIntakeTool({ pi, state, jev: (ctx) => jevHolder.forContext(ctx) }));
+  const submissions = createSubmissionStore();
   const reviewDeps = {
     state,
+    submissions,
     jev: (ctx: ExtensionContext) => jevHolder.forContext(ctx),
     exec,
   } satisfies Parameters<typeof createReviewStartTool>[0];
   pi.registerTool(createReviewStartTool(reviewDeps));
   pi.registerTool(createReviewRecordTool(reviewDeps));
+  pi.registerTool(createSubmitReviewTool({ state, submissions }));
   registerModelsCommand(pi);
   piSubagent(pi);
 

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@jwilger/pi-development-system",
-  "version": "0.87.0",
+  "version": "0.89.0",
   "description": "A pi extension package representing a seasoned approach to software development using a full AI SDLC.",
   "keywords": [
     "pi-package"
   ],
+  "license": "MIT",
   "author": "John Wilger",
   "repository": {
     "type": "git",
@@ -57,6 +58,7 @@
   "scripts": {
     "test": "node --experimental-transform-types --no-warnings --test \"test/**/*.test.ts\"",
     "test:jev": "node --experimental-transform-types --no-warnings --test \"test/live/*.live.ts\"",
+    "changelog": "node --experimental-transform-types --no-warnings scripts/changelog.ts",
     "check:jev": "node scripts/run-jev-fixtures.ts",
     "typecheck": "tsc --noEmit",
     "lint": "biome check --error-on-warnings .",

package/prompts/devsys-review.md

@@ -6,5 +6,5 @@ Review the work in progress with the code-review skill.
 
 1. Call `devsys_review_start` (slice and diff range: $ARGUMENTS; omit either to use the active slice and `HEAD`; only the `HEAD` range clears the commit gate).
 2. Run the `agent_spawn` payload it returns, unchanged.
-3. Pass the reviewer's packet verbatim to `devsys_review_record` with the same `slice`, `diffDigest` and `diffRange` the start reply gave.
+3. The reviewer submits its result with `devsys_submit_review`; call `devsys_review_record` with the same `slice`, `diffDigest` and `diffRange` the start reply gave (no packets needed). Only if the reviewer returned a markdown packet instead, pass it verbatim in `packets`.
 4. Report `review: N/R clean` and the next action. If the next action is `fix-findings`, list each blocking and should-fix finding with its `path:line`.

package/skills/code-review/SKILL.md

@@ -17,11 +17,13 @@ Review is a soft gate (`review.unsatisfied`): skipping it needs a recorded depar
    diff digest, lets Jev choose lenses, and returns an exact `agent_spawn` payload.
 2. Run that `agent_spawn` unchanged. The reviewer is a top-level agent, not a
    child of this conversation, so it does not inherit your context.
-3. Pass the reviewer's packet, verbatim, to `devsys_review_record` with the
-   `slice` and `diffDigest` the start reply gave, and the same `diffRange` if you gave one
-   (`packets: [...]`; all lens packets of one
-   round in one call). A packet is recorded once, in the round its header names;
-   if the diff changed since the start, the round is refused: start again.
+3. The reviewer submits its result with `devsys_submit_review` (typed arguments; a
+   self-contradicting or wrong-round result is refused to the reviewer with an error id).
+   Call `devsys_review_record` with the `slice` and `diffDigest` the start reply gave, and
+   the same `diffRange` if you gave one; it reads the submitted results of the round. If a
+   reviewer returned a markdown packet instead, pass it verbatim in `packets: [...]` (all
+   lens packets of one round in one call). A result is recorded once, in the round it
+   names; if the diff changed since the start, the round is refused: start again.
 4. Read the reply: `review: N/R clean` and `next:`.
    - `fix-findings`: fix every blocking and should-fix finding, then start a new round
      (starting again on an unchanged diff is refused).
@@ -29,7 +31,9 @@ Review is a soft gate (`review.unsatisfied`): skipping it needs a recorded depar
    - `stale-diff`: the diff changed after a satisfied review; one more round.
    - `done`: commit.
 
-## The packet
+## The result
+
+The fields of `devsys_submit_review` mirror this packet; the markdown form is the fallback (ADR 0006).
 
 ```markdown
 ## Review — <slice> — round <n> — lenses: <a, b>

package/skills/profile-design-system/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: profile-design-system
+description: Design-system discipline for UI work - tokens before components, building only from existing design-system materials, and a logged decision when something does not fit. Use when a slice adds or changes user interface (components, styles, pages), when a repo has a design system or token files (*.tokens.json, .css, .scss, .tsx, .vue, .svelte), or when reviewing UI code for snowflakes and raw values.
+---
+
+# Design-system profile
+
+Brad Frost's stance, as this system applies it: the AI is deliberately constrained to the
+design system's materials. That constraint is what separates working inside a design
+system from vibe coding. Treat the agent as a smart but sometimes unsophisticated
+junior developer who has read the system's codebase and must follow its conventions.
+
+## Order of work: tokens, then components, then pages
+
+1. **Tokens.** Three tiers. Raw (`color-brand-green`) feeds semantic
+   (`theme-color-primary-background`), which feeds component (`button-primary-background`).
+   Components read the component tier; they never reach for a raw value.
+2. **Components.** Structure, behaviour and accessibility live in a structural component
+   library, kept apart from the aesthetic token layer. Do not fork a component to change
+   how it looks; change tokens.
+3. **Pages.** A page is the test of the system. Build it with real content in more than
+   one shape: a 40 and a 340 character headline, one and ten items, empty and error.
+   Anything that breaks goes back to the component, not into a page-level patch.
+
+## Defaults for a UI slice
+
+- **Use an existing component.** Search the design system first and name what you found
+  in the task record. The plan lists the states and variants the slice must show
+  (default, hover, focus, disabled, loading, empty, error, long content, narrow screen).
+- **No raw values in components.** No hex colours, pixel sizes, z-indexes or font
+  stacks inline. Make this a lint (stylelint, a biome or eslint rule, a grep in CI);
+  prose alone is a write-only channel and is not enforced.
+- **Build states outside the app first** when the repo has Storybook or a pattern lab:
+  write the story with real-content variants, then wire the component into the app.
+- **Accessibility is part of the component**, not a later pass: roles, labels, keyboard
+  path, focus order, contrast from the token pair, reduced motion.
+
+## When it does not fit: 90 percent and missing components
+
+Product pressure will find a way around the system. Decide, do not drift.
+
+| Situation | Decision | Record |
+| --- | --- | --- |
+| The component fits | Use it as is | nothing |
+| It fits about 90 percent | Extend through a documented variant or a token; ask the system owner when the variant is not yours to add | a line in the task record |
+| Nothing fits, and the need will recur | Propose a new component to the system, build it there first | an ADR if it changes the component API |
+| Nothing fits, and the need is one of a kind | A snowflake: allowed once, local, labelled | `devsys_record_departure` with gate `scope.expansion:snowflake`, naming the 90 percent reasoning and when to revisit |
+
+A snowflake written without that record is a defect to fix in review, not a style
+preference.
+
+## Checklist
+
+- [ ] The slice names the design-system components it uses, or why none fits.
+- [ ] No raw colour, size or font value in a component; the tier rule has a lint.
+- [ ] Every state and variant in the plan has a story or screenshot with real content.
+- [ ] Keyboard, focus, labels and contrast checked on the new or changed component.
+- [ ] Any snowflake or forked component has its recorded decision.
+
+## Do not
+
+- Do not invent a component, a token or a variant the system does not have without the
+  decision above.
+- Do not copy a component's markup into a page to restyle it.
+- Do not choose a different UI library for one slice.
+- Do not let a generated component through that only looks right in the happy case.

package/skills/threat-modelling/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: threat-modelling
+description: Proportional threat modelling for a change - decide whether it needs one, ask four questions, and record the result only when the risk earns it. Use before designing or reviewing anything that touches authentication, authorisation, secrets, user data, a network boundary, file or process execution, payments, or a new dependency, or when asked for a threat model or security review.
+---
+
+# Threat modelling
+
+Proportional on purpose. Most changes need thirty seconds of thought and no document.
+A few need a page. None need a framework exercise.
+
+## What this system trusts
+
+This system runs on the author's single-owner machine. Trusted: the author, their
+working tree, their credentials in pi, the local shell and git. Do not model an attacker
+who already has that. Untrusted: everything that arrives from outside it. That means
+network input, file contents from other people, dependency code, model output when it
+becomes a command or a path, and anything a deployed service receives.
+
+## Is a threat model needed?
+
+Ask all four and count the yes answers:
+
+1. Does the change add or move a **trust boundary** (a new input from outside, a new
+   network call, a new account or role)?
+2. Does it handle **secrets, personal data, money or authority** (login, permissions,
+   keys, tokens, payments)?
+3. Does it **execute or interpret** something it did not write (a shell command, a
+   file path, a template, deserialised data, a plugin)?
+4. Does it add a **dependency class** or change how packages are fetched or run?
+
+No yes: no document. Note "no new trust boundary" in the task record and move on. One or
+more yes: do the four questions below.
+
+## The four questions
+
+1. **What are we protecting?** Name the asset: the data, the authority, the money, the
+   machine. If you cannot name one, the change probably does not need this.
+2. **Who or what can reach it, and from where?** List the entry points and who controls
+   each: users, other services, files, the model, a dependency.
+3. **What could go wrong?** For each entry point, a line each for: pretending to be
+   someone else, changing what should not change, denying that it happened, reading what
+   should stay private, making it unavailable, gaining more authority than intended.
+   Skip the ones that do not apply and say so.
+4. **What stops it, and what is left?** Name the control that exists (a check, a limit,
+   a permission, a test). Where there is none, decide: build one, accept the risk, or
+   leave it to a named follow-up. An accepted risk is written down with its cost.
+
+## Checklist for the usual suspects
+
+- [ ] Input is parsed into a type at the boundary; length, size and shape limits exist.
+- [ ] Secrets never reach logs, commit messages, eval fixtures or subagent prompts
+      (non-negotiable 7); they are read from the environment or the credential store.
+- [ ] A path or a command built from input cannot leave its directory or add
+      arguments; use argument arrays, not string concatenation.
+- [ ] Authority is checked on the server side of every boundary, not inferred from the
+      client.
+- [ ] A failure refuses safely: with no user to ask, the answer is no.
+- [ ] Errors do not reveal more than the caller may know.
+- [ ] New dependencies are pinned, maintained and needed; the install does not run code
+      you did not intend.
+- [ ] Each control has a test that fails when the control is removed.
+
+## When to write `docs/security/threat-model.md`
+
+Write it, or extend it, when the change has at least two yes answers above, or any
+accepted risk you would want a reviewer to find later. Keep it to one page: assets,
+entry points, the table from question 3 for what applies, controls with their test
+names, accepted risks with who decided. Link it from the ADR when the decision shapes
+the architecture. Otherwise the task record line is enough.
+
+## Do not
+
+- Do not produce a threat model for a change with no trust boundary to satisfy a process.
+- Do not list generic threats that have no entry point in this system.
+- Do not accept a risk silently; an unrecorded acceptance is an unmanaged one.
+- Do not weaken a control to make a test or a gate pass (non-negotiable 2).

package/src/context/phase-guide.ts

@@ -12,7 +12,7 @@ export function phaseGuide(phase: Phase): string {
     case "implementing":
       return "Implementing one slice. Write a failing test first, make it pass with the least code, run the tests and read the result before claiming anything. Push when the slice is complete and reviewed: a push of a clean tree closes it (devsys_finish_slice closes it explicitly).";
     case "reviewing":
-      return "Reviewing. Call devsys_review_start for a fresh-context review, pass its packet and diffDigest to devsys_review_record, fix every blocking and should-fix finding (red-first still applies), and repeat until the review is satisfied; then the slice moves to delivering.";
+      return "Reviewing. Call devsys_review_start for a fresh-context review, give its diffDigest to devsys_review_record (the reviewer submits through devsys_submit_review), fix every blocking and should-fix finding (red-first still applies), and repeat until the review is satisfied; then the slice moves to delivering.";
     case "delivering":
       return "Delivering. The review is satisfied. Commit with a rationale, push, and release; a push of a clean tree closes the slice (devsys_finish_slice closes it explicitly, or abandons it with a reason). Editing source reopens implementing. A red trunk (CI) is repaired first.";
     default:

package/src/core/review-flow.ts

@@ -176,7 +176,8 @@ export function reviewerTask(input: {
     `Review slice ${input.slice}, round ${input.round}, through these lenses: ${lenses}.`,
     `See the change with \`git diff ${input.diffRange}\` (and \`git diff --stat ${input.diffRange}\`), plus any untracked files listed by \`git ls-files --others --exclude-standard\` (git diff does not show them; read them directly). Read the callers, callees and tests it depends on, no more.`,
     "Do not modify files; report demonstrable defects with a realistic trigger and the smallest local repair.",
-    "Return exactly the review packet from your instructions, with exactly this header (slice and round must not change):",
+    `Report your result by calling devsys_submit_review with slice "${input.slice}", round ${input.round}, lenses ${JSON.stringify(input.lenses)}, your sources, your findings (lens, severity, path, line, summary) and the verdict. If it refuses, for example with verdict-contradicts-findings or wrong-round, correct the call and submit again; when it accepts, end with one short line.`,
+    "Only if devsys_submit_review is not available, return the review packet from your instructions instead, with exactly this header (slice and round must not change):",
     "",
     `## Review — ${input.slice} — round ${input.round} — lenses: ${lenses}`,
     "### Sources inspected",

package/src/core/review-submission.ts

@@ -0,0 +1,60 @@
+import type { Finding, Severity } from "./review.ts";
+import type { ReviewPacket } from "./review-packet.ts";
+
+/** A reviewer's result as it arrives from the typed submit tool (see ADR 0006). */
+export type Submission = {
+  readonly slice: string;
+  readonly round: number;
+  readonly lenses: ReadonlyArray<string>;
+  readonly sources: ReadonlyArray<string>;
+  readonly findings: ReadonlyArray<{
+    readonly lens: string;
+    readonly severity: Severity;
+    readonly path?: string | undefined;
+    readonly line?: number | undefined;
+    readonly summary: string;
+  }>;
+  readonly verdict: "no-blocking" | "blocking";
+};
+
+/** Why a submission was refused: a stable kebab-case id and a message the reviewer can act on. */
+export type SubmitError = {
+  readonly id: "verdict-contradicts-findings" | "finding-lens-not-listed";
+  readonly message: string;
+};
+
+const counts = (f: { severity: Severity }): boolean =>
+  f.severity === "blocking" || f.severity === "should-fix";
+
+/** The packet a submission stands for, or the refusal. The schema has already checked its shape. */
+export function packetFromSubmission(input: Submission): ReviewPacket | SubmitError {
+  const unlisted = input.findings.find((f) => !input.lenses.includes(f.lens));
+  if (unlisted !== undefined) {
+    return {
+      id: "finding-lens-not-listed",
+      message: `a finding names lens "${unlisted.lens}" but the packet's lenses are ${input.lenses.join(", ")}; list every lens you used in \`lenses\``,
+    };
+  }
+  if (input.findings.some(counts) !== (input.verdict === "blocking")) {
+    return {
+      id: "verdict-contradicts-findings",
+      message: `verdict "${input.verdict}" contradicts the findings: blocking/should-fix findings mean "blocking", otherwise "no-blocking"`,
+    };
+  }
+  const findings: Finding[] = input.findings.map((f, i) => ({
+    id: `${f.lens}-${i + 1}`,
+    severity: f.severity,
+    ...(f.path === undefined ? {} : { path: f.path }),
+    ...(f.line === undefined ? {} : { line: f.line }),
+    summary: f.summary,
+    lens: f.lens,
+  }));
+  return {
+    slice: input.slice,
+    round: input.round,
+    lenses: input.lenses,
+    sources: input.sources,
+    findings,
+    verdict: input.verdict,
+  };
+}

package/src/review/review-tools.ts

@@ -30,11 +30,14 @@ import { CONFIG_FILE, loadConfig } from "../state/config.ts";
 import { availableModels } from "../state/models-command.ts";
 import type { SessionState } from "../state/session-state.ts";
 import { snapshotDiff } from "./digest.ts";
+import type { SubmissionStore } from "./submissions.ts";
 
 export type ReviewToolDeps = {
   state: SessionState;
   jev: (ctx: ExtensionContext) => Jev;
   exec: Exec;
+  /** Results reviewers submitted with `devsys_submit_review`, read by `devsys_review_record`. */
+  submissions: SubmissionStore;
   now?: () => Date;
 };
 
@@ -55,6 +58,9 @@ const sliceOf = (given: string | undefined, state: SessionState): SliceRef | und
 const NO_SLICE =
   "no slice: pass `slice`, or start work on a slice first (there is no active slice)";
 
+const NO_RESULT = (slice: string, round: number): string =>
+  `no result for round ${round} of "${slice}": the reviewer submits it with devsys_submit_review before you record, or you pass its packet markdown in \`packets\``;
+
 const StartParameters = Type.Object({
   slice: Type.Optional(
     Type.String({ description: "Slice being reviewed; defaults to the active slice." }),
@@ -120,6 +126,7 @@ function spawnPayload(input: {
 }
 
 type Reply = ReturnType<typeof reply>;
+const replyText = (r: Reply): string => r.content.map((c) => c.text).join("\n");
 type Config = Extract<Awaited<ReturnType<typeof loadConfig>>, { ok: true }>["value"];
 type Snapshot = Extract<Awaited<ReturnType<typeof snapshotDiff>>, { ok: true }>["value"];
 type Prepared = { slice: SliceRef; config: Config; range: string; snap: Snapshot };
@@ -181,6 +188,8 @@ async function startRound(
   const required = requiredRounds(p.config);
   const existing = reviewOf(deps.state.get(), p.slice) ?? startReview(p.slice, required);
   const review: ReviewState = { ...existing, required };
+  // A new round only sees what reviewers submit after it began.
+  deps.submissions.clear(p.slice);
   deps.state.update((s) => upsertReview(s, review));
   deps.state.update((s) => afterReviewRound(s, nextAction(review, p.snap.digest), p.slice));
   const refusal = startRefusal(review, p);
@@ -200,7 +209,7 @@ async function startRound(
     [
       `${reviewLabel(review)}; round ${round}; diff ${p.snap.digest}. ${basis}`,
       `lenses: ${lenses.join(", ")}`,
-      `Spawn the reviewer with agent_spawn using exactly this payload, then pass its packet to devsys_review_record with slice "${p.slice}", diffDigest "${p.snap.digest}"${rangeArg}:`,
+      `Spawn the reviewer with agent_spawn using exactly this payload, then call devsys_review_record with slice "${p.slice}", diffDigest "${p.snap.digest}"${rangeArg}. The reviewer submits its result with devsys_submit_review, so pass no packets (only a markdown packet the reviewer returned instead goes in packets):`,
       JSON.stringify(spawn),
     ].join("\n"),
   );
@@ -214,7 +223,7 @@ export function createReviewStartTool(
     name: "devsys_review_start",
     label: "Start review round",
     description:
-      "Begin a review round for a slice: computes the diff digest, chooses review lenses, and returns the agent_spawn payload for a fresh-context reviewer. Run that spawn, then pass the reviewer's packet to devsys_review_record.",
+      "Begin a review round for a slice: computes the diff digest, chooses review lenses, and returns the agent_spawn payload for a fresh-context reviewer. Run that spawn, then call devsys_review_record (the reviewer submits its result with devsys_submit_review).",
     promptSnippet: "Start a fresh-context review round for a slice",
     parameters: StartParameters,
     exposure: "model-only",
@@ -243,9 +252,12 @@ const RecordParameters = Type.Object({
   slice: Type.Optional(
     Type.String({ description: "Slice reviewed; defaults to the active slice." }),
   ),
-  packets: Type.Array(Type.String(), {
-    description: "Reviewer packets, verbatim markdown: one per lens reviewer, all for one round.",
-  }),
+  packets: Type.Optional(
+    Type.Array(Type.String(), {
+      description:
+        "Reviewer packets, verbatim markdown, for a reviewer that could not call devsys_submit_review. Results submitted through that tool for this round are read without being passed.",
+    }),
+  ),
   diffRange: Type.Optional(
     Type.String({ description: "The range that was reviewed; defaults to HEAD." }),
   ),
@@ -275,15 +287,22 @@ async function adjusted(
   return { findings: out, notes };
 }
 
+const lensKey = (p: ReviewPacket): string => [...p.lenses].sort().join("\u0000");
+
+/** Submitted results win over a markdown packet for the same lenses (a reviewer that did both). */
+function mergeResults(
+  markdown: readonly ReviewPacket[],
+  submitted: readonly ReviewPacket[],
+): { packets: ReviewPacket[]; dropped: number } {
+  const taken = new Set(submitted.map(lensKey));
+  const kept = markdown.filter((m) => !taken.has(lensKey(m)));
+  return { packets: [...kept, ...submitted], dropped: markdown.length - kept.length };
+}
+
 /** Parses every packet, or the reply naming the first malformed one. */
 function parsePackets(
   raw: readonly string[],
 ): { ok: true; value: ReviewPacket[] } | { ok: false; reply: Reply } {
-  if (raw.length === 0)
-    return {
-      ok: false,
-      reply: reply("no packets: pass the reviewer's packet markdown in `packets`", true),
-    };
   const packets: ReviewPacket[] = [];
   for (const [i, text] of raw.entries()) {
     const parsed = parseReviewPacket(text);
@@ -359,7 +378,7 @@ export function createReviewRecordTool(
     name: "devsys_review_record",
     label: "Record review round",
     description:
-      "Record one review round from the reviewer's packet(s): parses findings, lets Jev adjust severity when confident, and returns the clean-round count and the next action.",
+      "Record one review round from the reviewer's submitted result (or markdown packets): reads findings, lets Jev adjust severity when confident, and returns the clean-round count and the next action.",
     promptSnippet: "Record a reviewer packet as a review round",
     parameters: RecordParameters,
     exposure: "direct",
@@ -370,9 +389,23 @@ export function createReviewRecordTool(
       _onUpdate,
       ctx: ExtensionContext,
     ) {
-      if (sliceOf(params.slice, deps.state) === undefined) return reply(NO_SLICE, true);
-      const packets = parsePackets(params.packets);
-      if (!packets.ok) return packets.reply;
+      const slice = sliceOf(params.slice, deps.state);
+      if (slice === undefined) return reply(NO_SLICE, true);
+      const round = (reviewOf(deps.state.get(), slice)?.rounds.length ?? 0) + 1;
+      const markdown = parsePackets(params.packets ?? []);
+      if (!markdown.ok) {
+        return deps.submissions.forRound(slice, round).length === 0
+          ? markdown.reply
+          : reply(
+              `${replyText(markdown.reply)}. A submitted result for round ${round} is waiting: omit \`packets\` to record it.`,
+              true,
+            );
+      }
+      const { packets, dropped } = mergeResults(
+        markdown.value,
+        deps.submissions.forRound(slice, round),
+      );
+      if (packets.length === 0) return reply(NO_RESULT(slice, round), true);
       const prepared = await prepare(
         deps,
         ctx,
@@ -386,7 +419,14 @@ export function createReviewRecordTool(
           true,
         );
       }
-      return recordRound(deps, ctx, prepared.value, packets.value);
+      const recorded = await recordRound(deps, ctx, prepared.value, packets);
+      if (recorded.isError === true) return recorded;
+      deps.submissions.clear(slice);
+      return dropped === 0
+        ? recorded
+        : reply(
+            `${replyText(recorded)}\nNote: ${dropped} markdown packet(s) for lenses already submitted were dropped; the submitted result is the one recorded.`,
+          );
     },
   };
 }

package/src/review/submissions.ts

@@ -0,0 +1,38 @@
+import type { ReviewPacket } from "../core/review-packet.ts";
+
+/** Reviewer results submitted through `devsys_submit_review`, waiting for `devsys_review_record`. */
+export type SubmissionStore = {
+  /**
+   * Keep a packet. One for the same slice and round that shares a lens replaces the earlier one
+   * (a corrected resubmission); packets for disjoint lenses (parallel lens reviewers) are all kept.
+   */
+  put(packet: ReviewPacket): void;
+  forRound(slice: string, round: number): ReviewPacket[];
+  /** Drop every packet of a slice, when a new round starts or one is recorded. */
+  clear(slice: string): void;
+};
+
+const sameRound = (a: ReviewPacket, b: ReviewPacket): boolean =>
+  a.slice === b.slice && a.round === b.round;
+
+const sharesLens = (a: ReviewPacket, b: ReviewPacket): boolean =>
+  a.lenses.some((lens) => b.lenses.includes(lens));
+
+/** In memory on purpose (ADR 0006): a round takes minutes and a lost submission is visible. */
+export function createSubmissionStore(): SubmissionStore {
+  let packets: ReviewPacket[] = [];
+  return {
+    put(packet) {
+      packets = [
+        ...packets.filter((p) => !(sameRound(p, packet) && sharesLens(p, packet))),
+        packet,
+      ];
+    },
+    forRound(slice, round) {
+      return packets.filter((p) => p.slice === slice && p.round === round);
+    },
+    clear(slice) {
+      packets = packets.filter((p) => p.slice !== slice);
+    },
+  };
+}

package/src/review/submit-tool.ts

@@ -0,0 +1,85 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import { SEVERITIES } from "../core/review.ts";
+import { reviewOf } from "../core/review-flow.ts";
+import { packetFromSubmission } from "../core/review-submission.ts";
+import type { SliceRef } from "../core/types.ts";
+import type { SessionState } from "../state/session-state.ts";
+import type { SubmissionStore } from "./submissions.ts";
+
+export const SubmitParameters = Type.Object({
+  slice: Type.String({ description: "The slice you were asked to review, exactly as given." }),
+  round: Type.Integer({ minimum: 1, description: "The round number you were asked to review." }),
+  lenses: Type.Array(Type.String({ minLength: 1 }), {
+    minItems: 1,
+    description: "Every lens you reviewed through.",
+  }),
+  sources: Type.Array(Type.String(), {
+    description: "What you inspected (path:line ranges), and what you checked and refuted.",
+  }),
+  findings: Type.Array(
+    Type.Object({
+      lens: Type.String({ minLength: 1, description: "One of `lenses`." }),
+      severity: Type.Union(SEVERITIES.map((s) => Type.Literal(s))),
+      path: Type.Optional(Type.String({ description: "File the finding is about." })),
+      line: Type.Optional(Type.Integer({ minimum: 1 })),
+      summary: Type.String({
+        minLength: 1,
+        description: "One sentence: the defect, why it matters, and the smallest repair.",
+      }),
+    }),
+    { description: "Empty when there is nothing to report." },
+  ),
+  verdict: Type.Union([Type.Literal("no-blocking"), Type.Literal("blocking")], {
+    description: "`blocking` when any finding is blocking or should-fix, otherwise `no-blocking`.",
+  }),
+});
+
+export type SubmitDeps = { state: SessionState; submissions: SubmissionStore };
+
+const reply = (text: string, isError = false) => ({
+  content: [{ type: "text" as const, text }],
+  details: undefined,
+  isError,
+});
+
+function submit(deps: SubmitDeps, params: Static<typeof SubmitParameters>) {
+  const state = deps.state.get();
+  const slice = params.slice as SliceRef;
+  const review = reviewOf(state, slice);
+  if (review === undefined && state.activeSlice !== slice) {
+    return reply(
+      `unknown-slice: "${params.slice}" is neither the active slice nor under review; use the slice name exactly as given in your task`,
+      true,
+    );
+  }
+  const expected = (review?.rounds.length ?? 0) + 1;
+  if (params.round !== expected) {
+    return reply(
+      `wrong-round: this is for round ${params.round}, but round ${expected} of "${params.slice}" is the one being reviewed; use the round number from your task`,
+      true,
+    );
+  }
+  const packet = packetFromSubmission(params);
+  if ("id" in packet) return reply(`${packet.id}: ${packet.message}`, true);
+  deps.submissions.put(packet);
+  return reply(
+    `submitted: ${params.slice} round ${params.round}, lenses ${params.lenses.join(", ")}, verdict ${params.verdict}, ${params.findings.length} finding(s). End with one short line.`,
+  );
+}
+
+/** `devsys_submit_review`: a reviewer hands over its packet as validated arguments (ADR 0006). */
+export function createSubmitReviewTool(deps: SubmitDeps): ToolDefinition<typeof SubmitParameters> {
+  return {
+    name: "devsys_submit_review",
+    label: "Submit review result",
+    description:
+      "For reviewer subagents only: submit your review result as structured arguments. A result that contradicts itself or is for another round is refused with an error id; fix it and submit again. Then end with one short line.",
+    promptSnippet: "Submit a review result (reviewer subagents)",
+    parameters: SubmitParameters,
+    exposure: "direct",
+    execute(_id, params: Static<typeof SubmitParameters>) {
+      return Promise.resolve(submit(deps, params));
+    },
+  };
+}