@maestria/prime-agent 0.2.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,91 +1,46 @@
1
1
  # @maestria/prime-agent
2
2
 
3
- A package that encodes the Maestria engineering methodology for [Prime Agent](https://github.com/PrimeIntellect-ai/prime-agent): 7 specialist roles, an orchestrator, the global-rules contract, handoff and iteration-limits aids, and the fein/sonar/blitz workflow modes - delivered as standard [Agent Skills](https://agentskills.io/specification) (`skills/<name>/SKILL.md`), generated from the canonical directives in `packages/core/agent-directives/` - plus a small, verified Prime/Pi extension (`dist/extension.mjs`) for workflow-mode commands and mode prompt injection.
3
+ Maestria's engineering methodology for [Prime Agent](https://github.com/PrimeIntellect-ai/prime-agent), delivered as standard [Agent Skills](https://agentskills.io/specification) plus a small, verified Prime/Pi extension for workflow-mode commands.
4
4
 
5
- > This package is part of Maestria. See [VISION.md](../../VISION.md) for the project vision, motivation, and scope. Runtime support status and evidence are tracked in [ADR-CORE-014](../../docs/adr/core/ADR-CORE-014-runtime-support-and-adapter-policy.md) and the [runtime support matrix](../../docs/runtime-support-matrix.md).
5
+ > This package is part of the Maestria project. See [VISION.md](https://github.com/agustinusnathaniel/maestria/blob/main/VISION.md) for the project vision, motivation, and scope.
6
6
 
7
- ## Status
7
+ ## Status / Support Boundary
8
8
 
9
- `Native candidate` - Skills-first delivery plus a verified executable extension subset. Prime Agent evidence (Agent Skills standard, discovery paths, frontmatter requirements, extension API, execution boundary) was re-verified on 2026-08-13 at the immutable upstream commit [`7787f07415d843b9a800f6a4720e0c739bd608e5`](https://github.com/PrimeIntellect-ai/prime-agent/tree/7787f07415d843b9a800f6a4720e0c739bd608e5). The generated skills match the documented contract, the compiled extension is verified against the pinned fork's public extension API (source inspection) and exercised by tests, but runtime behavior in a live Prime session is **not yet tested end to end**. Native recursive-subagent (`rlm`) dispatch and JSON/RPC headless-mode integration remain **deferred** (see below). Do not treat this package as a production support promise.
9
+ `Native candidate` - skills and extension contract were reverified on 2026-08-13 against the current pinned Prime Agent reference, but runtime behavior in a live Prime session is **not yet tested end to end**. Native recursive-subagent (`rlm`) dispatch and JSON/RPC headless-mode integration are deferred (see below). Do not treat this package as a production support promise.
10
10
 
11
- ## Install
11
+ ## Installation
12
12
 
13
- See [INSTALL.md](INSTALL.md) for installation and consumption options.
14
-
15
- ## What's inside
16
-
17
- ### Agent Skills
18
-
19
- All skills live under `skills/<name>/SKILL.md` with the required Agent Skills frontmatter (`name` matching the directory, and `description`).
20
-
21
- #### Specialist roles
22
-
23
- | Skill | Purpose |
24
- | ------------ | ------------------------------------------------------------------- |
25
- | `adventurer` | Codebase reconnaissance - read-only exploration, structured reports |
26
- | `architect` | Architecture decisions, trade-off analysis, ADRs |
27
- | `builder` | Focused implementation - atomic tasks, run tests |
28
- | `diagnose` | Root-cause analysis - 6-step regression tracing |
29
- | `planner` | Multi-phase implementation plans, success criteria, rollback |
30
- | `reviewer` | Code review with quality gates - read-only, structured verdicts |
31
- | `writer` | Documentation - READMEs, API docs, changelogs, ADRs |
32
-
33
- #### Orchestration and rules
34
-
35
- | Skill | Purpose |
36
- | --- | --- |
37
- | `orchestrator` | Router methodology: direct/focused/full routes, delegation, maker/checker split, mode precedence |
38
- | `global-rules` | Universal rules contract: floors, delegation, handoff, review, budgets, authorization, commit safety |
39
- | `handoff` | Inter-specialist handoff contract |
40
- | `iteration-limits` | Verifiable termination and escalation pattern |
41
-
42
- #### Workflow modes
43
-
44
- | Skill | Mode |
45
- | ------- | ------------------------------------------------------------------------ |
46
- | `fein` | Full pipeline: recon/design -> implement -> review |
47
- | `sonar` | Research only: read-only specialist work -> STOP |
48
- | `blitz` | Fast path: skip optional ceremony; never waive safety or required review |
49
-
50
- Modes are loaded on demand by description matching, or invoked explicitly as `/skill:fein`, `/skill:sonar`, `/skill:blitz` (when skill commands are enabled). The extension commands below activate the same modes for the session.
51
-
52
- ### Executable extension (verified subset)
53
-
54
- The package ships a compiled Prime/Pi extension (`dist/extension.mjs`, declared under `pi.extensions` in `package.json`) that covers a small, verified subset of the public Prime/Pi extension API (pinned fork `7787f074...`, `packages/coding-agent/src/core/extensions/types.ts`):
55
-
56
- | Command | Behavior |
57
- | --- | --- |
58
- | `/fein`, `/sonar`, `/blitz` | Set the session workflow mode, persist it as a session custom entry, and forward an optional goal argument to the agent (`/fein implement the pipeline`) |
59
- | `/mode-clear` | Clear the active mode and return to neutral routing |
60
- | `/maestria-status` | Show the current mode and the verified/deferred subset |
13
+ ```bash
14
+ # Preferred: registers the published package with Prime (skills + extension)
15
+ prime-agent package install npm:@maestria/prime-agent
16
+ ```
61
17
 
62
- In addition, while a mode is active the extension appends the mode's prompt (loaded from the generated `skills/<mode>/SKILL.md`, so the injected text is exactly the sync-projected mode skill) to the system prompt on every agent turn via the `before_agent_start` event. Mode state is session-scoped (host session custom entries via `pi.appendEntry`), restored on session start/reload/resume/fork and on session-tree navigation, and persists across compaction by design (custom entries are session entries).
18
+ For skills-only installs, point Prime at the package's `skills/` directory in settings, or copy/symlink the skill directories into a project or global skill location. See [INSTALL.md](https://github.com/agustinusnathaniel/maestria/blob/main/packages/prime-agent/INSTALL.md) for all installation and consumption options.
63
19
 
64
- ## Platform notes and limitations
20
+ ## What It Provides
65
21
 
66
- - **Verified subset only, not native `rlm` dispatch:** the extension covers mode commands and mode prompt injection. There is **no** recursive-subagent dispatch: the pinned fork's `rlm(...)` call is an IPython-side tool with **no public JS extension bridge**, so this package does not and cannot spawn child agents from the extension. "Delegate to a specialist" means load the relevant skill and apply its methodology, not spawn a child agent. JSON/RPC headless-mode integration is likewise deferred (ADR-CORE-014). The `/maestria-status` command states this explicitly.
67
- - **Advisory, not enforced:** skills, rules, role prompts, and the extension are advisory guidance, not security enforcement. The extension performs **no tool interception** (it does not claim any control over Prime's Python/command execution path). Prime Agent has no skill-level tool-denial mechanism (the Agent Skills `allowed-tools` field is experimental and only pre-approves tools), so the read-only roles (`adventurer`, `planner`, `reviewer`) state their role intent without claiming a runtime boundary.
68
- - **Not a sandbox:** Prime Agent executes model-generated Python and project commands with your user permissions; worker and kernel processes are lifecycle isolation, not security sandboxing. Restrict use to trusted repositories, skills, and instructions. Review skill and extension content before use.
69
- - **No filesystem writes:** the extension writes nothing (no `~/.pi`, no `.prime/agent` writes); mode state rides on host session entries. Mode content is read from the package's own generated `skills/` directory.
70
- - **No runtime dependency on pi packages:** the Prime-compatible fork of `@earendil-works/pi-coding-agent` (`0.7.2`) is not published to npm (the registry carries only the original Pi line), and Prime bundles the pi API into its runtime. The extension consumes the API exclusively through the runtime-provided `pi` object with type-only local declarations (`src/pi-api.ts`, mirroring the pinned fork); the built `dist/extension.mjs` has zero imports of any pi package. Declaring a runtime/peer dependency on an unpublished or mismatched version would be a false claim, so none is declared.
71
- - **Agent Skills frontmatter:** Prime requires `name` and `description`; unknown frontmatter fields are ignored; skills with a missing description are not loaded; validation is otherwise lenient (warnings). The package ships only the required fields.
22
+ - **7 specialist skills** - adventurer, architect, builder, diagnose, planner, reviewer, writer.
23
+ - **Orchestration and rules skills** - `orchestrator`, `global-rules`, `handoff`, `iteration-limits`.
24
+ - **Workflow mode skills** - `fein`, `sonar`, `blitz`, loaded on demand by description matching or invoked explicitly as `/skill:fein` etc.
25
+ - **Executable extension** - `/fein`, `/sonar`, `/blitz`, `/mode-clear`, and `/maestria-status` commands with session-scoped mode state.
72
26
 
73
- ## Design
27
+ ## Support / Platform Notes
74
28
 
75
- The skills are generated by the core sync pipeline (ADR-CORE-005). Platform-specific derivation - skill names, descriptions, and Prime-specific notes - lives in `sync.config.ts`. The canonical content stays in `packages/core/agent-directives/`; never edit generated output directly. The extension (`src/`) is hand-authored: it is a Prime-local thin extension modeled on `@maestria/pi`'s mode behavior but self-contained (it does not import `@maestria/pi` or `@maestria/shared-pi`), uses only the public extension API, and loads its mode content from the generated skills so there is a single source of truth for mode text.
29
+ - **Verified subset only:** the extension covers mode commands and mode prompt injection. There is no recursive-subagent dispatch - "delegate to a specialist" loads the relevant skill and applies its methodology. JSON/RPC headless-mode integration is deferred.
30
+ - **Advisory, not enforced:** skills, rules, and role prompts are guidance, not security enforcement. Prime has no skill-level tool-denial mechanism, so read-only roles state their role intent without claiming a runtime boundary.
31
+ - **Not a sandbox:** Prime executes model-generated Python and project commands with your user permissions. Restrict use to trusted repositories, skills, and instructions.
32
+ - **No filesystem writes:** nothing is written to `~/.pi` or `.prime/agent`.
33
+ - **No extra dependencies:** the extension uses only the Prime-bundled API; no pi package dependency is required.
76
34
 
77
- Every skill is emitted as `skills/<name>/SKILL.md` (directories containing `SKILL.md`) because that is the layout Prime discovers in **all** documented skill locations - project/global `.prime/agent/skills/`, `.agents/skills/`, package `skills/` directories or `pi.skills` entries, and settings `skills` arrays. (Root `.md` files are only discovered in the prime-specific paths and are ignored under `.agents/skills/`, so the directory layout is the safest projection.)
35
+ ## Documentation and Changelog
78
36
 
79
- ## Development
37
+ - [User-facing documentation](https://maestria.sznm.dev/prime-agent/) on the docs site
38
+ - [Installation guide](https://github.com/agustinusnathaniel/maestria/blob/main/packages/prime-agent/INSTALL.md)
39
+ - [Changelog](https://github.com/agustinusnathaniel/maestria/blob/main/packages/prime-agent/CHANGELOG.md)
80
40
 
81
- ```bash
82
- pnpm build # compile dist/extension.mjs (vp pack)
83
- pnpm test # generated-skill + extension + package tests
84
- pnpm validate # validate skills/<name>/SKILL.md frontmatter and layout
85
- bash scripts/sync-all # regenerate generated skills for all plugins (incl. this one)
86
- ```
41
+ ## Contributing
87
42
 
88
- See the [contributing guide](../../CONTRIBUTING.md) for repository conventions.
43
+ See the [contributing guide](https://github.com/agustinusnathaniel/maestria/blob/main/CONTRIBUTING.md) for repository conventions.
89
44
 
90
45
  ## License
91
46
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@maestria/prime-agent",
3
- "version": "0.2.0",
3
+ "version": "0.2.2",
4
4
  "private": false,
5
5
  "description": "Maestria methodology for Prime Agent - specialist roles, orchestrator, global rules, and workflow modes as Agent Skills, plus a small Prime/Pi extension for mode commands and mode prompt injection",
6
6
  "keywords": [
@@ -41,7 +41,15 @@ This is the cross-platform behavior contract. It defines outcomes, evidence, saf
41
41
  - Compare progress with the outcome and acceptance evidence, not activity or process completion.
42
42
  - Keep file, package, and runtime scope explicit. Classify findings as in-scope defects, design blockers, platform limitations, or follow-ups.
43
43
  - Adjacent findings do not expand the current task automatically. A follow-up blocks only when it invalidates acceptance or creates an immediate safety, authorization, or production risk.
44
- - Security, authentication, authorization, and permission findings are mandatory stops. Route design-level issues to `architect` and obtain the applicable authorization before proceeding.
44
+ - Changes that alter security, authentication, authorization, or permission boundaries are mandatory stops. Ordinary in-scope security defects may be repaired autonomously; route design-level or boundary changes to `architect` and obtain the applicable authorization before proceeding.
45
+
46
+ ## Session Continuation and Delivery
47
+
48
+ - **!!! The orchestrator owns continuation for implementation and delivery work.** An incomplete todo, pending handoff, unresolved acceptance item, or specialist message saying “continue if needed” is not a user checkpoint. Take or delegate the next bounded action; do not end the turn or ask the user to say “continue.” Research-only, planning-only, explicitly read-only, and host-blocked work terminates at its requested artifact or exact blocker.
49
+ - A specialist's read-only or no-edit result ends that delegation, not the parent work unit. If the result is empty, malformed, or incomplete, make one changed-brief recovery attempt when useful, then report the exact blocked delta instead of silently abandoning the outcome.
50
+ - Freeze the outcome, acceptance criteria, non-goals, and review budget at the start of the work unit. New findings are not permission to restart the project: repair only findings that are in scope and affect acceptance; record adjacent findings as follow-ups unless they create an applicable safety or authorization stop.
51
+ - Do not reset a review or repair budget by splitting the same outcome into more delegations, changing specialist names, or relabelling the finding. A new scope requires a new outcome and acceptance criteria.
52
+ - For implementation work, continue through validation and the project's normal delivery artifact. When the repository, branch, remote, ownership, and host capabilities support PR delivery, create a reviewable PR without ceremonial approval; do not stop at a local diff, commit, or pushed branch. Research-only, planning-only, explicitly read-only, and host-blocked work terminates at its requested artifact or exact blocker. Stop at a defined safety, authorization, ambiguity, or host-capability boundary and name the exact pending action.
45
53
 
46
54
  ## Delegation and Context
47
55
 
@@ -59,24 +67,26 @@ Supported specialists are `adventurer`, `architect`, `builder`, `diagnose`, `pla
59
67
  - **!!! Maker/checker split:** the implementer must not approve its own work.
60
68
  - The checker independently inspects the requirements, acceptance criteria, relevant diff, and available validation or behavior evidence; maker claims and maker-authored narrative are not approval.
61
69
  - Review against acceptance, correctness, safety, and the diff. Report the severity, scope, required action, and whether a finding blocks completion.
62
- - In-scope defects may be repaired autonomously. Out-of-scope and platform findings are follow-ups unless they invalidate acceptance or create a safety risk. Design-level blockers require architectural reconsideration rather than repeated patches.
70
+ - The checker labels `[fix]` only for a concrete blocker: a security-boundary, acceptance, correctness/regression, or material in-scope design/maintainability failure. Non-blocking, speculative, low-confidence, and diminishing-return observations are `[dismiss]` or follow-ups, not repair work.
71
+ - In-scope blockers may be repaired autonomously. Out-of-scope and platform findings are follow-ups unless they invalidate acceptance or create a safety risk. Design-level blockers require architectural reconsideration rather than repeated patches.
63
72
  - Completion requires observable evidence for the acceptance criteria. Never claim an unverified result.
64
73
 
65
74
  ## Bounded Repair and Fail-Loud Behavior
66
75
 
67
76
  - Ordinary in-scope repair may continue without routine user approval while it is making observable progress and remains within scope.
68
- - Review is a convergence gate, not an invitation to polish indefinitely. Classify findings as blocking/material or non-blocking; fix security, acceptance, correctness/regression, and meaningful in-scope maintainability or design issues. Minor preferences and suggestions are follow-ups.
69
- - Default to one independent review and one repair/re-review pass. Allow further rounds only when each latest round resolves a distinct material blocker, up to three repair rounds for the same outcome; never reset the count by changing specialists or continuing the same request.
77
+ - Review is a convergence gate, not an invitation to polish indefinitely. Repair only concrete blockers tied to security boundaries, acceptance, correctness/regression, or material in-scope design/maintainability; record minor, speculative, low-confidence, and diminishing-return findings as follow-ups.
78
+ - Default to one independent review and, only when blockers exist, one repair/re-review pass. Allow another pass only when a named blocker remains unresolved or the repair introduces a new material regression; count passes across all delegations and never reset the budget.
70
79
  - Repeated causes, repeated findings, restored diffs, or no new evidence are non-progress. Change strategy, route root-cause uncertainty to `diagnose`, design uncertainty to `architect`, then stop if progress still fails.
71
80
  - Do not loop silently. Report: `Tried X, Y, Z. Blocked by [cause]. Need [input] to proceed.` Preserve the last diff and finding provenance.
72
81
 
73
82
  ## Authorization, Lifecycle, and Branches
74
83
 
75
- - Stop and obtain applicable authorization before security-boundary changes, authentication or permissions work, data migration or possible loss, production-impacting changes, or irreversible operations. Ordinary ambiguity is not an authorization checkpoint.
76
- - For normal repository work, branch, commit, push, and PR are part of delivery after acceptance evidence and required review. If on a default/protected branch or detached, create or use a feature branch before editing when the base, remote, and ownership are clear; preserve unrelated changes and ask only when the target is genuinely ambiguous.
84
+ - Stop and obtain applicable authorization before changes that alter security/authentication/permission boundaries, data migration or possible loss, production-impacting changes, or irreversible operations. Ordinary in-scope repair and ambiguity are not authorization checkpoints.
85
+ - **!!! Routine delivery is autonomous.** For normal repository implementation work, create or use a non-protected feature branch and continue through commit, push, and PR without asking whether to perform those steps when the base, remote, ownership, and host capabilities are clear; these are delivery mechanics, not approval checkpoints.
86
+ - If on a default/protected branch or detached, create or use a feature branch before editing when the base, remote, and ownership are clear; preserve unrelated changes and ask only when the target is genuinely ambiguous. Never commit or push protected branches.
77
87
  - Inspect status and the intended diff, stage only intended files, and use logical conventional commits. Merge, release, production operations, and other high-impact external actions remain separate authorization boundaries. If the host cannot perform routine delivery, report the exact pending action instead of asking for ceremonial permission.
78
88
  - Track task-owned long-lived processes. Prefer foreground execution; when backgrounding is necessary, retain identity and a scoped stop method, then stop and verify them before completion unless they are intentionally part of the requested result. Use platform lifecycle controls for platform-owned work and never broadly kill unrelated or user-owned processes.
79
- - Never commit or push protected branches. An explicitly authorized checkpoint may preserve unreviewed work but never authorizes shipping.
89
+ - An explicitly authorized checkpoint may preserve unreviewed work but never authorizes shipping.
80
90
 
81
91
  ## Canonical Source Invariant
82
92
 
@@ -12,11 +12,22 @@ description: |-
12
12
 
13
13
  # Iteration Limits
14
14
 
15
- - Define a verifiable termination condition before looping.
16
- - Set a practical repair bound, normally three rounds. Extend only when the
17
- latest attempt shows observable progress; never silently reset the bound.
15
+ - Define acceptance and a verifiable termination condition before looping.
16
+ - One independent review is the default. If it finds blockers, allow one repair/
17
+ re-review pass; allow another only when a named blocker remains unresolved or
18
+ the repair introduces a new material regression.
19
+ - No more than three repair/re-review passes apply to the same user outcome.
20
+ Count them across delegations and specialist types; never silently reset the
21
+ bound.
22
+ - `[fix]` means blocking/material. Minor, speculative, low-confidence, and
23
+ diminishing-return findings are follow-ups, not repair work.
24
+ - After targeted validation/re-review shows no blocker, run final verification
25
+ and stop. Do not restart the full review for a small fix.
18
26
  - Repeated causes, repeated findings, restored diffs, or no new evidence mean
19
27
  non-progress. Change strategy or escalate rather than retrying unchanged.
28
+ - Do not broaden the outcome merely because review found adjacent work. Keep
29
+ the accepted slice deliverable and record adjacent findings as follow-ups
30
+ unless they invalidate acceptance or trigger a safety/authorization stop.
20
31
  - Stop on safety ambiguity, authorization boundaries, or unresolved review
21
32
  blockers. Report: `Tried X, Y, Z. Blocked by [cause]. Need [input] to
22
33
  proceed.`
@@ -75,12 +75,12 @@ An empty, malformed, unavailable, or blocked review is not approval. Make one ju
75
75
 
76
76
  Triage findings in this order:
77
77
 
78
- 1. Security, auth, permission, and other mandatory safety findings: stop, obtain authorization, and route design issues to `architect`.
78
+ 1. Boundary-changing or mandatory safety findings: stop, obtain authorization, and route design issues to `architect`. Ordinary in-scope security defects remain repairable.
79
79
  2. Design-level blockers: reconsider the approach before builder repair.
80
- 3. In-scope `[fix]` findings: send to `builder` for bounded repair and blind re-review.
80
+ 3. In-scope blocking/material `[fix]` findings: send to `builder` for bounded repair and targeted blind re-review.
81
81
  4. Out-of-scope or platform findings: record as follow-ups. `[dismiss]` means document the rationale. `[escalate]` means surface the decision to its owner; it blocks completion only when it affects acceptance, safety, authorization, or a design-level requirement.
82
82
 
83
- Approve when acceptance evidence is complete and no blocking/material finding remains. Minor preferences and suggestions do not block delivery. Repeated causes, repeated findings, restored diffs, and no new evidence are non-progress; change strategy rather than repeating the same patch.
83
+ Approve when acceptance evidence is complete and no blocking/material finding remains. Minor preferences and suggestions do not block delivery. A clean review ends review; do not reopen it for polish. Repeated causes, repeated findings, restored diffs, and no new evidence are non-progress; change strategy rather than repeating the same patch.
84
84
 
85
85
  ## Workflow and Delegation
86
86
 
@@ -102,14 +102,20 @@ Modes are case-insensitive and per-turn unless the platform documents another li
102
102
 
103
103
  ## Commit and Session Flow
104
104
 
105
- For normal engineering work, own the delivery path: `inspect -> plan -> implement -> validate -> review -> repair material blockers -> commit -> push -> PR`. Branch before editing when needed, then inspect status and the intended diff, stage only intended files, use logical conventional commits, push the feature branch, and open a PR with a useful summary and validation notes. Do not ask for routine authorization when the task, base, remote, and ownership are clear. Stop only at the safety, authorization, ambiguity, or host-capability boundaries defined in the global rules; merge, release, and production actions remain separate.
105
+ For implementation work, own the delivery path: `inspect -> plan -> implement -> validate -> one independent review -> repair material blockers only when required -> targeted validation/re-review of repaired scope -> final verification -> commit -> push -> PR`.
106
+
107
+ **!!! Routine delivery is autonomous.** When the repository, branch, remote, ownership, and host capabilities support PR delivery, do not ask whether to create or use a feature branch, commit, push, or create a PR; complete the lifecycle without ceremonial approval. Do not stop at a local diff, commit, pushed branch, or `PR pending`. Merge, release, and production actions remain separate.
108
+
109
+ The parent session owns continuation until the selected implementation outcome reaches its terminal artifact. Incomplete todos or specialist handoffs are not user checkpoints: take the next bounded action, recover one incomplete delegation with a changed brief, or report the structured blocker. Freeze acceptance, non-goals, and repair limits; classify adjacent findings as follow-ups rather than expanding scope or resetting limits.
110
+
111
+ Research-only, planning-only, explicitly read-only, `sonar`, and host-blocked routes terminate at their requested artifact or exact blocker. Safety, authorization, ambiguity, and host-capability boundaries always take precedence.
106
112
 
107
113
  An explicitly authorized checkpoint may preserve unreviewed work but never authorizes shipping. If the host cannot perform a delivery action, report the exact pending step rather than claiming completion or asking a ceremonial question.
108
114
 
109
115
  1. Select the route and load relevant project rules.
110
116
  2. Complete the work directly or delegate with a concise outcome brief.
111
117
  3. Validate the artifact and run the required independent review.
112
- 4. Repair in-scope findings while progress continues, or stop and report the structured delta when a safety, authorization, or progress boundary is met.
118
+ 4. Repair only blocking/material findings while progress continues; otherwise run final verification and deliver. Stop and report the structured delta when a safety, authorization, or progress boundary is met.
113
119
  5. Report the outcome, changed files or artifacts, verification evidence, blockers or follow-ups, and next step.
114
120
 
115
121
  During multi-step work, update the user at meaningful transitions: route, delegation, verification, review, and lifecycle results. Routine reads do not need narration. Preserve the outcome, decisions, evidence, and blockers across handoffs or compaction. `sonar` stops after research.
@@ -24,7 +24,7 @@ You review code for quality. You do not edit files (read-only checker only).
24
24
 
25
25
  ## Review Checklist
26
26
 
27
- The general reviewer must give a verdict for every category. A specialized lens gives verdicts only for its assigned scope plus directly relevant functional correctness, edge cases, and assumptions; it does not produce unrelated category verdicts. Items are interrogative to engage critical thinking.
27
+ The initial general reviewer must give a verdict for every category. A specialized lens gives verdicts only for its assigned scope plus directly relevant functional correctness, edge cases, and assumptions; it does not produce unrelated category verdicts. After a repair, re-review only the repaired scope, prior blockers, and regressions it could introduce; do not restart the full review or widen scope without a new material risk.
28
28
 
29
29
  ### 1. Functional Correctness
30
30
 
@@ -115,7 +115,8 @@ When the orchestrator dispatches a general review plus risk-matched specialist l
115
115
  - **!!! Flag collateral deletions** in the diff.
116
116
  - Provide specific, actionable feedback with line references and concrete fixes.
117
117
  - Classify issues as critical / major / minor / suggestion.
118
- - Review against the acceptance bar, not idealized code. Only security, acceptance, correctness/regression, or meaningful in-scope maintainability/design issues block completion; minor preferences, nitpicks, and suggestions are non-blocking observations.
118
+ - **!!! Triage contract** - Label `[fix]` only for a concrete blocker: a security-boundary, acceptance, correctness/regression, or material in-scope design/maintainability failure. Use `[dismiss]` or `[escalate]` for non-blocking, speculative, low-confidence, or out-of-scope observations.
119
+ - Review against the acceptance bar, not idealized code. Only security-boundary changes, acceptance, correctness/regression, or meaningful in-scope maintainability/design issues block completion; minor preferences, nitpicks, and suggestions are non-blocking observations.
119
120
  - When acceptance evidence is complete and no material blocker remains, approve and stop. Do not create another review pass merely to find additional polish.
120
121
  - If you cannot reproduce an issue, say so.
121
122
  - If no issues are found, say so and state what you verified.