pirl-framework-cli 0.0.0-stage → 1.0.0

package/bundled-framework/files/.agents/instructions/plan.instructions.md

@@ -0,0 +1,292 @@
+---
+name: "Plan Layer Instructions"
+description: "Create a short Plan in English, settle the business logic, assign implementation roles and verification roles that verify by reasoning."
+applyTo: ".agents/instructions/plan.instructions.md"
+metadata:
+  id: ".agents/instructions/plan"
+  kind: "instruction"
+  version: "2.0.3"
+  status: "active"
+---
+
+# Plan Layer Instructions
+
+Apply the Plan process only when the request and the [router](layered-task-execution.instructions.md)
+have selected this layer. Reading or updating a Plan/report file does not
+activate another layer. The run is carried out through the
+[`pirl-plan` skill](../../.skills/pirl-plan/SKILL.md), which owns the run procedure, the
+Plan file format and the helper script; this contract owns the decisions and
+the exit conditions.
+
+A Plan settles the work to do, how to do it, the implementation roles, the
+verification roles and the logic that must hold. Write it in English; keep
+IDs, data keys, symbols, commands and paths verbatim when referencing them. The
+output is short, but the implementers must not have to re-decide product
+behavior themselves.
+
+## AI Agent roles at the Plan layer
+
+The role catalog lives in the [standalone and maintenance instructions](standalone-and-maintenance.instructions.md#role-catalog) and the
+assignment principles in the [router](layered-task-execution.instructions.md#assignment-principles);
+each role's expertise lives in the role file linked in the table.
+Plan picks the smallest team with enough expertise for the request using the
+"Select when" column and records it in `planning_roles`. When the user names
+roles, keep exactly that list. Do not add roles just to complete the process.
+
+| Role | Select when | Responsibility at Plan | Input | Done when |
+| --- | --- | --- | --- | --- |
+| [`business-analyst`](../roles/business-analyst.role.md) | The request has business behavior to settle | Settle REQs, business logic and QGs; find missing product decisions | Request, existing decisions, specifications | Each REQ has a source and an outcome; a source is recorded as the user's decision only for what is in the user's words or in the verbatim text of the choices and choice descriptions the user saw when choosing; what is inferred from the source or the repository's conventions, what interprets or extends a choice, and what the agent chose itself in work the user explicitly delegated to the agent are all recorded as decided by the agent, with their basis; product choices that change the result and that nobody has decided have been asked or marked unsettled; each QG states its required logic; the basis is read from sources by the role, which runs or builds measuring tools only when the user asks for a root-cause investigation ([Investigating and settling decisions](#investigating-and-settling-decisions)) |
+| [`code-analyst`](../roles/code-analyst.role.md) | The request touches the target repository's source or documentation | Read callers/consumers, configuration and constraints; identify change points and affected documentation | Source of the target repository | The change scope and allowed paths are grounded in the source; for changes that spread to other elements or consumers (inherited properties, creating a containing block or stacking context, default configuration), the element carrying the change and the list of affected ones are stated; the basis is read from sources by the role, which runs or builds measuring tools only when the user asks for a root-cause investigation ([Investigating and settling decisions](#investigating-and-settling-decisions)) |
+| [`solution-architect`](../roles/solution-architect.role.md) | API/data/permission contracts change, or the package has several tasks | Settle contracts, ownership, permission model, boundaries and dependencies between tasks | Source, shared contracts | Each task has its own acceptance outcome; real dependencies are recorded; for each value, symbol or file that a task adds, changes or removes, every passage of a file shared between tasks (including context documentation) that mentions it is in that same task's REQs, `Allowed paths` and QGs, so the file stays right after each task completes; the basis is read from sources by the role, which runs or builds measuring tools only when the user asks for a root-cause investigation ([Investigating and settling decisions](#investigating-and-settling-decisions)) |
+| [`ux-designer`](../roles/ux-designer.role.md) | The request touches what the user sees | Settle screens, display states, interaction flows, UI strings per language and viewports; write UI QGs as state and layout logic | Request, existing UI, the repository's context documentation | Every display state created or changed has a QG; the basis is read from sources by the role, which runs or builds measuring tools only when the user asks for a root-cause investigation ([Investigating and settling decisions](#investigating-and-settling-decisions)) |
+| [`process-auditor`](../roles/process-auditor.role.md) | Every Plan run; not recorded in `planning_roles` | Self-evaluate the Plan run per the [router](layered-task-execution.instructions.md#self-evaluation-and-improvement) | Plan, sources used, each role's decisions | Record written; improvements applied or summarized for the user |
+
+The Plan coordinator merges the roles' conclusions, settles disagreements by
+sources (not by voting), writes the Plan and self-reviews it. Each role returns
+expert decisions with the sources that change the approach. Each Plan file
+records how the planning roles were performed on the `Planning` line of the
+`Participating roles` section: a separate agent, or the coordinator
+self-performing with the reason delegation was not possible, per role when they
+differ. When self-performed, do not claim an independent challenge happened.
+
+## Investigating and settling decisions
+
+- Read the request and the existing decisions; identify the target repository
+  per [AGENTS.md](../../AGENTS.md#target-repository) and the part to
+  change from the source.
+- Read the related callers/consumers, constraints and configuration before
+  claiming a mechanism is missing; do not infer the whole system from one file
+  or from an unverified review. Planning roles investigate by reading the
+  source, documentation, git history and existing records; they do not build
+  mock pages or measuring tools and do not run the application or a browser.
+  A quantity that reading does not yield is computed from the source with its
+  formula, or recorded as not yet measured. Only when the user asks for a
+  root-cause investigation may the responsible role reproduce the defect per the
+  [router](layered-task-execution.instructions.md#verification-by-reasoning);
+  the Plan records the distinguished cause and does not turn the reproduction
+  result into a QG.
+- Settle the difference between the current state and the target outcome. Ask
+  when a product choice that changes the result is missing; resolve details
+  yourself from the source and the repository's conventions. If only one branch
+  is blocked, complete the independent part of the Plan and mark the limit clearly.
+
+## Splitting tasks for separate implementation and acceptance
+
+- Prefer each Plan file to be one piece of work with its own outcome and
+  independently verifiable QGs. Draw boundaries by behavior/contracts that can
+  be completed, not by file count, technical layer or a goal of splitting as
+  small as possible. Shipping in the same release is no reason to merge all
+  work into one task.
+- For each task, consider the state made of only the original source, the
+  outputs of completed prerequisite tasks and the task's own changes: every QG
+  must be provable by reasoning on the source of that state. A QG must not need
+  code, configuration, fixes or evidence that are assigned only to a later task
+  or a task planned to run in parallel. Do not create a task that, once
+  implemented, still has to wait for a later task before Review can PASS.
+- Reduce dependencies with settled contracts and a clear change scope. For
+  APIs, schemas or shared files, state which part already exists, which part
+  needs implementing and which task owns each change. For documents that
+  several tasks edit, assign by change, not by section, column or topic: for
+  each value, symbol or file that a task adds, changes or removes, search by
+  token name, value and file name for every passage that mentions it, including
+  exhaustive listings (component lists, directory trees), then assign that
+  passage to that same task. When two tasks change the same value, each task
+  updates that passage for its own change. A contract on paper does not replace
+  the implementation needed to conclude a QG; two tasks editing the same
+  symbol/decision cannot be treated as independent just because of
+  `depends_on: []`.
+- When there is a real dependency, record `depends_on` and the concrete output
+  to receive in `How to do it`. The prerequisite task must meet its own QGs
+  before the dependent task starts the part that needs that output. If the QGs
+  cannot be closed separately, change the boundary, make the shared part a
+  prerequisite task with a verifiable outcome, or merge exactly the parts that
+  cannot be separated. Do not hide a dependency with mocks, deleted
+  declarations, weakened QGs or abstractions created only to split tasks.
+- Assign each acceptance condition to the task that owns that outcome.
+  End-to-end criteria, or removing an old mechanism, that only hold once several
+  parts are combined belong to an integration task that depends on those parts;
+  do not restate such criteria as PASS conditions of a prerequisite task. Keep
+  all package-wide requirements, and do not push a task's core behavior into
+  the integration so that the task can PASS. Reasoning on a local contract does
+  not prove the real execution path or data invariants; QGs of that kind must
+  name the write/read points to trace.
+- `depends_on` points to tasks in the same package, never to itself, and never
+  forms a cycle. Re-read all QGs to find implicit dependencies: T02 needing T01
+  while T01's QG needs T02 is still a cycle even when the `depends_on` list is
+  valid. Fix the assignment/QGs before handoff; do not leave Implement/Review
+  to repeatedly edit code to work around a task-splitting mistake.
+
+## Scope of work: source code, documentation and functional tests
+
+Per the [router](layered-task-execution.instructions.md#verification-by-reasoning),
+a task covers implementing product source code (with accompanying documentation
+in the target repository), creating/updating the target repository's context
+documentation ([AGENTS.md](../../AGENTS.md#target-repository)), and functional
+tests under the [FUT rule](layered-task-execution.instructions.md#functional-tests-fut-rule)
+when a REQ/specification needs them.
+
+- Never create a task, a `How to do it` step, a REQ, a QG, a `Done when` or
+  `Allowed paths` for building, running the application/database/browser for
+  acceptance, measuring performance, new harnesses or verification scripts,
+  deploying or releasing. [Layout verification with mocks](implement.instructions.md#layout-verification-with-mocks)
+  is something Implement does on its own when the diff changes the UI: the
+  Plan creates no task, step or QG for it, including a numbered step assigning
+  the implementation role to capture layout. UI QGs are still written as
+  layout/state logic. What needs to be captured or measured beyond that
+  section (viewports the user asked for, thresholds computable from the source,
+  computed properties to record) goes in the logic of the UI QGs and in the
+  implementation role's `Done when`; how to build the state without the diff
+  belongs to that section.
+- When a task has tests, state the REQ/behavior under test, the affected
+  functionality with its grounds (call path, contract or shared data that is
+  changed), the test files allowed to be edited and exactly which tests run.
+  Do not assign tests for unrelated functionality, do not assign running the
+  whole suite, and do not invent test viewpoints beyond the specification.
+- Specification goals that belong to the user's stage (performance thresholds,
+  device testing, running the whole system, release) do not become work in the
+  package; write one line in `What to do` saying they belong to the user's
+  build/test/release stage.
+- QGs do not use test/build/run results as a baseline. Do not write QGs like
+  "test X is green", "the full test suite is green", "`npm run build` passes",
+  "seen in the browser…", "evidence on the real database" or a measurement.
+  Write the source logic that must hold: situation → where it is handled →
+  outcome/state and failure branches, enough for the verification role to
+  trace through the source and conclude. For example, replace "the sign-up test
+  is green" with "a valid code creates a `PENDING` account; a wrong code returns
+  `400` and writes no data".
+
+## Separating implementation roles from verification roles
+
+- `implementation_roles` produce the task's output. `verification_roles` do not
+  edit the output; after the implementation roles finish, they conclude each
+  QG by reasoning per the
+  [Implement contract](implement.instructions.md#verifying-quality-gates-by-reasoning).
+  Each task has at least one role of each kind, and the two lists do not
+  overlap: a role does not verify what it implemented itself.
+- Pick implementation roles from the
+  [Implement](implement.instructions.md#ai-agent-roles-at-the-implement-layer)
+  catalog by the kind of work: `backend-developer` for all non-UI code (API,
+  domain, data, jobs, CLI, scripts, tools), `frontend-developer` for the UI,
+  `technical-writer` for documentation-only tasks. When a task has both sides,
+  record the real dependency order, for example `backend-developer` before
+  `frontend-developer` uses the new API.
+- Pick verification roles by the question the QG must answer, not by a fixed
+  pairing with the implementation role:
+  - `code-reviewer` challenges the diff: bugs, regressions, permissions and
+    security, data/state inconsistency, guards/validators/error handling that
+    report false success, contract violations; the default for every code change.
+  - `code-analyst` traces the flow from the entrypoint to the final state
+    through every caller/consumer and builds scenario tables for QGs with many
+    branches, states or orderings; suited to contract changes, many
+    integration points, or documentation that must match the source.
+  - `ux-designer` checks layout screenshots against UI QGs; pick it when the
+    task has UI QGs.
+
+  Examples: fixing one bug → `code-reviewer`; changing an API with its docs →
+  `code-reviewer` for permissions/regressions and `code-analyst` for consumers
+  and docs; adding a screen → `code-reviewer` and `ux-designer`. Combine
+  several roles only when each answers its own question; each QG has exactly
+  one verification role accountable for its conclusion.
+- Verification is not running scripts, creating tests or running commands. Do
+  not assign verification roles to build, write/run tests, run the application
+  or write tools; tests belong to the implementation roles. A verification
+  role's `Done when` is a `PASS|FAIL|BLOCKED` conclusion for each assigned QG,
+  with the path traced, counterexamples and sources, plus a check of the tests
+  in the diff against FUT when the task has tests.
+
+## Content must be sufficient to execute
+
+- Each REQ has a source and a concrete outcome; a QG says when something is
+  allowed/refused, the state to preserve and the related failure branches. Only
+  include risks with a mechanism within the request's scope; do not add
+  platforms, coverage or operations that were not assigned.
+- `Allowed paths` include known documents that describe the behavior about to
+  change (an earlier task's contract, indexes, status tables, API/error/
+  configuration/permission catalogs): search by route name, error code,
+  collection, configuration, token, file name or phrases like "until task N",
+  then name them.
+  Anything missed is still swept by Implement under its contract; the Plan does
+  not need to list every place.
+- Processing steps state the change point, the chosen direction, the order that
+  is really needed and the outcome. Settle decisions that affect APIs/data/
+  ownership; leave equivalent implementation details for Implement to choose.
+  Do not hide a missing decision inside the word "integrate".
+- Pick `implementation_roles` and responsibilities by the work, not by the
+  number of layers or directories; pick `verification_roles` per the section
+  above. Do not make several roles accountable for the same decision without a
+  merging owner.
+- Re-read using one main scenario and one scenario that could refute the
+  approach. The right criterion is behavior the source must guarantee, provable
+  by reasoning on the source; a test/build/validator PASS does not replace that
+  logic. When the task is content, the criterion is that the instructions lead
+  to the right decision, not that a tool accepts the text.
+
+## Plan file format
+
+Each task is one Plan file. The [`pirl-plan` skill](../../.skills/pirl-plan/SKILL.md)
+owns its format: the [template](../../.skills/pirl-plan/assets/plan-template.md)
+with the four sections `What to do`, `How to do it`, `Participating roles` and
+`Required quality gates`, and the [format reference](../../.skills/pirl-plan/references/plan-format.md)
+with the frontmatter fields, file naming and output location. This contract
+owns what those sections must settle.
+
+## Self-review before handoff
+
+1. Check each role's contribution against the request, the source, the approach
+   and the QGs. If the Plan is wrong or lacks a mandatory decision, fix the
+   content before declaring it ready. For a multi-task package, check separate
+   acceptability per the task-splitting section above and confirm every
+   package-wide requirement still has an owning task. Confirm each task
+   separates implementation roles from verification roles that fit the QGs'
+   questions, that no task, step or QG belongs to the user's build/test/release
+   stage, that there is no separate QG for capturing layout, and that the test
+   part (if any) is limited to FUT. Before declaring the Plan ready, re-read it
+   with the following five checks and fix the Plan if anything is wrong:
+   - Every claim about the current state (sections, tables, files, behavior,
+     languages that exist) has been opened and confirmed at exactly each
+     location or language the Plan names; what does not exist yet is recorded in
+     the REQ as new.
+   - Every table of values or derived numbers with a measurable constraint
+     (contrast, luminance, size, limits) has been recalculated value by value
+     against each constraint; on a conflict, fix the table or the constraint
+     instead of handing over both.
+   - A REQ that changes a composite element (label, icon, border, background)
+     states which parts are kept, removed or added.
+   - FUT commands name only test files that exist, or test files whose name a
+     REQ settles for the task to create; when the Plan leaves Implement to choose
+     between editing or replacing a unit (for example replacing a hook), refer to
+     the test file by that unit ("the test file of the replacement hook")
+     instead of naming a file that may no longer exist. `Allowed paths` include
+     the shared test setup or configuration files the change needs (for example
+     a fake of a browser API the test environment lacks).
+   - No step of `How to do it` assigns the implementation role to capture
+     layout, measure or run the application, not even a short step like
+     "capture layout per the layout verification instructions": the extra viewports, states and properties
+     to capture go in the UI QGs and in the implementation role's `Done when`.
+     The UI verification role's step only says it runs after the implementation
+     role captures.
+2. Run the Plan validator (command in the
+   [`pirl-plan` skill's procedure](../../.skills/pirl-plan/SKILL.md#procedure)) and fix
+   structural errors before handoff. The validator only checks the handoff
+   input (schema, required fields, roles, dependencies, time zone); it does not
+   grade content. The reviewer still has to prove the Plan is right.
+3. `process-auditor` self-evaluates the Plan run, applies improvements and
+   writes the record per the [router](layered-task-execution.instructions.md#self-evaluation-and-improvement).
+   Defects of the Plan itself are fixed in the Plan before handoff; instruction
+   defects do not turn into new product requirements.
+
+## Saving and handoff
+
+- After the final review and self-evaluation, the coordinator and every role
+  complete the [temporary-resource cleanup](layered-task-execution.instructions.md#cleaning-up-temporary-resources-before-handoff)
+  and check again before declaring the Plan ready. A blocked draft must still
+  clean up what is no longer needed; do not hand Plan clutter to Implement.
+- Save each task file where the user says, or by default under the Hub root,
+  per the [Plan file format](../../.skills/pirl-plan/references/plan-format.md).
+  Do not overwrite history.
+- State clearly whether the Plan has all decisions or still has unsettled
+  parts, its path and the self-improvement result per the router's reporting
+  section. Do not call a draft with insufficient input ready for Implement.
+- Do not edit product source at Plan. Finish and hand off the specific files
+  to the corresponding Implement instruction; do not start the next task on
+  your own.

package/bundled-framework/files/.agents/instructions/review.instructions.md

@@ -0,0 +1,236 @@
+---
+name: "Review Layer Instructions"
+description: "Check the Plan's quality gates by reasoning on the source, without relying on builds/tests, and report Business and Evaluations (assessment of the Implement roles, causes of their issues and improvements applied)."
+applyTo: ".agents/instructions/review.instructions.md"
+metadata:
+  id: ".agents/instructions/review"
+  kind: "instruction"
+  version: "2.0.4"
+  status: "active"
+---
+
+# Review Layer Instructions
+
+Apply the Review process only when the request and the [router](layered-task-execution.instructions.md)
+have selected this layer. Reading or updating a Plan/report file does not
+activate another layer.
+
+This contract owns the decisions and the exit conditions of a Review against a
+Plan; the run is carried out through the
+[`pirl-review` skill](../../.skills/pirl-review/SKILL.md), which owns the run procedure,
+the report template, its presentation rules, its location and the helper
+script. Review must distinguish a wrong product, insufficient evidence and
+instructions that led an agent to a wrong decision.
+Use exactly the two sections `Business` and `Evaluations`; keep IDs, symbols,
+role names and paths verbatim, and explain in plain English.
+
+## AI Agent roles at the Review layer
+
+The role catalog lives in the [standalone and maintenance instructions](standalone-and-maintenance.instructions.md#role-catalog) and the
+assignment principles in the [router](layered-task-execution.instructions.md#assignment-principles);
+each role's expertise lives in the role file linked in the table.
+Review picks `review_roles` from the table below using the "Select when"
+column, in the table's order: the first four roles are the default, and
+`ux-designer` is added when the diff changes the UI. Each role applies its own
+expertise to specific QGs/boundaries; do not force every role to find a defect.
+
+| Role | Select when | Responsibility at Review | Done when |
+| --- | --- | --- | --- |
+| [`code-analyst`](../roles/code-analyst.role.md) | Default | Trace the entrypoint, callers, writers/readers and configuration to the final state of each QG | QG conclusions with the path traced and sources |
+| [`code-reviewer`](../roles/code-reviewer.role.md) | Default | Challenge the diff: bugs, regressions, permissions and security, inconsistency, guards/error handling, tests that violate FUT | Each suspicion is proven as a FIND or refuted with sources |
+| [`business-analyst`](../roles/business-analyst.role.md) | Default | Check the REQs and the QGs' `Required logic` against the source's behavior; block self-invented criteria | Each QG has `PASS\|FAIL\|BLOCKED` true to its REQ |
+| [`solution-architect`](../roles/solution-architect.role.md) | Default | Consider whether contracts, ownership, task boundaries and dependencies are broken | Names the affected QGs or confirms there is no impact |
+| [`ux-designer`](../roles/ux-designer.role.md) | The diff changes the UI | Read Implement's `layout_verification` and screenshots and check them against the UI QGs | Each UI QG has a conclusion with the screenshots and source checked |
+| [`process-auditor`](../roles/process-auditor.role.md) | Every Review round; not recorded in `review_roles` | Re-evaluate the Implement roles (Evaluations section) and self-evaluate the Review run per the [router](layered-task-execution.instructions.md#self-evaluation-and-improvement) | Evaluations cover the Implement team; record written; improvements applied or summarized for the user |
+
+- Settle disagreements by the source and merge suspicions with the same cause;
+  do not vote. Delegate each role in `review_roles` per the
+  [assignment principles](layered-task-execution.instructions.md#assignment-principles). The report records
+  how each role was performed (a separate agent, or self-performed with the
+  reason) and the actual level of independence when a role has read the run's
+  drafts or conclusions or has consulted a reviewer outside the role team.
+- For each Implement record, assign one evaluation owner and cross-check when
+  there is a suspicion.
+
+## Inputs and permissions
+
+- Read exactly the `pirl-plan/v1` Plan, the Implementation Record, the
+  source/diff of the assigned run and any earlier report for the same task.
+  Identify the snapshot before concluding and read it per the
+  [Shared snapshots and older records section](layered-task-execution.instructions.md#shared-snapshots-and-older-records)
+  of the router.
+- Conclude each QG on the final source; when several tasks share a snapshot,
+  record the shared snapshot in `implementation_target`. A mismatch with an
+  earlier task's QG that belongs to a later task, in the order rebuilt per the
+  router, is not a FAIL of the earlier task and is not counted against the
+  earlier task's Implement roles; if it lies outside the later task's REQs, it
+  is a FIND of the later task. An unowned change is not a FIND of any task: if
+  it breaks a QG of the task under review, record that QG `BLOCKED` with an
+  `escalate` BLOCK because there is no owner to assign a `repair` to; otherwise
+  state it in `implementation_target` and `Next`.
+- A Plan with `Confirmed change` annotations is the current Plan: conclude the
+  QGs against it, after finding the trace of each annotation per the
+  [Implement rule](implement.instructions.md#changes-to-the-plan-confirmed-by-the-user):
+  the `plan_amendments` field of the Implementation Record, or the record of the
+  Plan run for the same task whose `record_id` the annotation states. An
+  annotation without any trace, or whose trace does not state the user's
+  confirmation of that change, is not a baseline: conclude the QGs against the
+  value before the change and record an `escalate` BLOCK for the user to confirm.
+- Product source, tests, config, the Plan and the Implementation Record are
+  read-only inputs. Review writes this run's report; framework files are edited
+  only by `process-auditor` per the [router](layered-task-execution.instructions.md#self-evaluation-and-improvement).
+  Do not edit the product, the Plan or the Implementation Record.
+
+## Business: prove or refute each suspicion
+
+1. Take the QGs and `Required logic` verbatim from the Plan. The REQs and the
+   user's decisions explain the criteria; rubrics, reviewer preferences and
+   instruction defects do not create new product criteria.
+   Check against the [Plan's task boundaries](plan.instructions.md#splitting-tasks-for-separate-implementation-and-acceptance):
+   do not use another task's integration criteria as a PASS condition of the
+   task under review. If a QG itself needs work assigned to a later/parallel
+   task, record that QG `BLOCKED` and create an `escalate` BLOCK back to Plan to
+   fix the assignment/QG; do not assign `repair`/`retry` to the same task just
+   to wait for that work. Do not drop the QG or record PASS yourself; still
+   evaluate independent implementation defects that have enough evidence.
+2. Trace the entrypoint, callers, guards, writers/readers, configuration and
+   failure branches that can occur. Confirm the trigger is within the usage
+   contract. An internal function that does not validate data does not prove
+   the whole system lacks validation.
+3. For a suspicion, connect trigger → mechanism → consequence → violated QG.
+   Actively look for refuting sources, including deliberate invariants.
+   Severity must rest on impact and on whether the failure path is reachable;
+   a name, a regex or a code fragment is not enough to prove a deadlock, data
+   loss or a Critical defect.
+4. Conclude QGs by reasoning on the source per the
+   [router](layered-task-execution.instructions.md#verification-by-reasoning):
+   Review does not build, does not create/run tests, scripts, mocks or the
+   application, and does not use test/build results, including results written
+   in the Implementation Record, as a baseline or PASS/FAIL evidence. When the
+   diff changes the UI, read the `layout_verification` and screenshots that
+   Implement captured per
+   [layout verification with mocks](layout-verification.instructions.md)
+   as a source for UI QGs, without capturing again. A green test does not prove
+   the business logic is right, and a red test does not prove the product is
+   wrong. A counterexample is an input and call path traceable on the source,
+   valid only if it can occur within the QG's scope.
+5. Keep only well-grounded conclusions:
+   - `FIND`: a real bug that violates a QG, with trigger, source, cause and impact.
+   - `RISK`: a grounded risk mechanism while the QG still holds; record the
+     limit, owner and revisit condition. A risk does not require a fix or
+     block a business PASS.
+   - `BLOCK`: missing sources, conditions or decisions needed to conclude a
+     QG; state the missing evidence, who provides it and the action to continue.
+   A refuted suspicion is removed from the findings, not relabeled as a risk to
+   keep it. Missing tests, not having built/run, or red/green test results are
+   not by themselves a FIND, RISK or BLOCK; do not ask for more tests, builds or
+   releases. Conversely, tests in the diff that violate the
+   [FUT rule](layered-task-execution.instructions.md#functional-tests-fut-rule)
+   (not traceable to a REQ/specification, outside the functionality under
+   development and the affected functionality, redundant duplicates, assertions
+   contrary to the specification or that block a correct result) are a
+   `repair` FIND; its QG field records `FUT` with the related REQ. A diff that
+   changes the UI while the Implementation Record lacks `layout_verification`,
+   or screenshots showing a layout that violates a QG, is also a `repair` FIND
+   for the implementation role that owns the UI.
+6. Give instructions by the mechanism to fix, file/symbol, order and the
+   outcome to preserve; instructions cover editing source, documentation or
+   tests under FUT; do not assign builds or running tests outside FUT.
+   A FIND within the Plan's scope uses `repair`; if it changes settled
+   behavior, paths or decisions, use `replan`. While any `replan` remains,
+   leave `repair_roles` empty and hand off to Plan. If the fix stays within
+   scope, the repair team is exactly the implementation roles accountable for
+   `repair` FINDs and `retry` BLOCKs, in handoff order.
+   RISKs are deferred: `Instructions` and `Revisit when` name the task and layer
+   that will handle them or the work the user needs to assign; while there is no
+   owning task, do not write "a later run" or "the next edit of <file>", and
+   instructions for another task to handle name that task. `escalate` BLOCKs
+   move to another owner. Assign `retry` only when there is a new
+   action/condition; do not open another round for the same blocker.
+7. Record QG `PASS|FAIL|BLOCKED`. Business is `FAIL` when a QG has failed or
+   there is a `FUT` FIND; if nothing failed but mandatory grounds are missing,
+   it is `BLOCKED`; otherwise `PASS`. Risks and instruction defects alone do not
+   reverse this conclusion.
+
+## Evaluations: assessing Implement roles
+
+This section answers: did each role of the reviewed Implement run do its
+assigned part correctly, and if not, what was the root cause and where was the
+framework improved. The Review's `process-auditor` carries out this section
+together with the Review run's self-evaluation, per the
+[router](layered-task-execution.instructions.md#self-evaluation-and-improvement).
+Review also knows the FINDs that the Implement run missed, so this evaluation
+has more evidence than Implement's own self-evaluation.
+
+1. Find the record of the reviewed Implement run with
+   `python -B .agents/evals/layer_record.py query --layer implement --plan-set <plan-set> --task <task-id>`.
+   In the result, pick the latest record whose `roles` list contains the
+   Implement roles to evaluate and write it into the Review record's `evaluates`.
+   A record that only applies improvements or corrections (`supersedes` set,
+   `roles` containing only `coordinator`) is not the evaluated record; mention it
+   in the EVAL's Evidence field. A correction record that carries all the roles
+   is itself the evaluated record.
+2. Create one EVAL for each role in `effective_implementation_roles`, then each
+   verification role of the Plan, in the Implementation Record's order. Evaluate
+   against the work, information and instructions actually assigned; do not
+   fail the whole team over one bug. A verification role is evaluated on its QG
+   conclusions: whether its reasoning stands against the source, whether it
+   missed FINDs that Review found, whether it relied on run results instead of
+   reasoning.
+3. Each issue of an Implement role is classified by cause and improved per the
+   [self-evaluation instructions](self-evaluation.instructions.md#issues-and-causes),
+   recorded in the Review record with `record` set to the record in
+   `evaluates`; the issue is attributed to the task and run that produced it per
+   the [Shared snapshots and older records section](layered-task-execution.instructions.md#shared-snapshots-and-older-records)
+   of the router. The EVAL records the cause, the `issue_key` and where it was
+   fixed, or that it is pending the user.
+4. Do not invent issues. Role or instruction issues do not lower the Business
+   verdict and do not block handing off a delivery that already qualifies; if
+   the report itself is wrong, fix the report before settling it.
+
+## Report and rounds
+
+Each Review round writes one `pirl-review/v1` report, built from the `review`
+skill's [template](../../.skills/pirl-review/assets/review-template.md) and saved
+where the user says, or by default under the Hub root, per the
+[report format](../../.skills/pirl-review/references/review-format.md). The first
+round has `prior_review: null`; later rounds reference the report immediately
+before.
+A request for additional phases or evidence for the same implementation run
+belongs to the current Review round: update that report and keep
+`review_round` and `prior_review`. Do not increment the round just because of
+a message, the time of verification or an extra investigation scope. Open a new
+round when assigned to review the next implementation/repair run or when the
+user explicitly asks for an independent round. When editing a settled report,
+record the reason for the edit in the report and leave the other rounds intact.
+
+## Finishing and next permissions
+
+Run the report validator (command in the
+[`pirl-review` skill's procedure](../../.skills/pirl-review/SKILL.md#procedure)) and fix
+structural errors before the final response.
+
+The coordinator and every Review role carry out the
+[temporary-resource cleanup](layered-task-execution.instructions.md#cleaning-up-temporary-resources-before-handoff)
+after the final verification, self-evaluation and record writing, then check
+again before the final response. The rule applies even when Business is FAIL or
+the Review is blocked; do not claim completion just because the report and
+validator pass.
+
+`verdict` equals `business_verdict`. `status: completed` means the evaluation
+is complete: Business has a well-grounded conclusion, Evaluations cover the
+Implement team, the Review record is written, and temporary resources have been
+cleaned up and checked again under the shared contract.
+A Business FAIL can still be a completed Review. Missing input needed for the
+evaluation uses `status: blocked`.
+
+If the Implementation Record or the implementation run's input is missing,
+keep a two-part draft with exactly the missing input. A draft that does not
+meet the contract cannot be used as a source for assigning product repairs.
+Complete it directly on the draft when the input arrives; do not open a round
+just to fill in missing information.
+
+Report the Business result, the level of evaluation completion, the
+self-improvement result per the router's reporting section and links to the
+report/Plan. Finish at handoff; do not implement the product, pick the next
+task or open a new Review round on your own.