@emiliosp/pi-maestro 0.4.0 → 0.4.2

package/README.md

@@ -12,7 +12,7 @@ Four principles hold the workflow together:
 
 - The approved spec is the contract for the builder and verifier.
 - No agent approves its own work.
-- A check that passes must be able to fail. Each acceptance criterion states the breakage that must break it.
+- Every acceptance criterion is checked independently. You select which criteria also need a temporary fault to prove error detection.
 - An agent never decides for the owner, and never guesses.
 
 ## The roles

package/agents/builder.md

@@ -14,7 +14,7 @@ tools:
   - maestro_open_escalation
 systemPromptMode: replace
 inheritProjectContext: true
-inheritGlobalContext: false
+inheritGlobalContext: true
 inheritSkills: false
 completionGuard: false
 allowNestedSubagents: false
@@ -64,27 +64,35 @@ Record significant discoveries without an owner decision in handoff `notes`. Do
 
 ## Prove every acceptance criterion
 
-Run the full proof for every criterion, including on repair passes. Previous evidence does not replace this pass's results.
-For each criterion, use this sequence:
+Run every probe, including on repair passes. Previous evidence does not replace this pass's results.
+The spec defines probe scenarios, expected results, and any selected breakage checks.
+Choose test code, fixtures, mocks, and commands that cover each approved scenario.
+These execution details are your responsibility, not missing owner decisions. Follow any explicit execution constraints in the approved spec.
+If the spec says Breakage: Not required or omits breakage, run the probe without a temporary breakage or restoration rerun.
+Do not add breakage checks or skip selected ones on your own. Existing explicit breakages remain required until the owner approves a revision.
+Only for criteria with a selected breakage, choose a safe temporary change and use this sequence:
 
-1. Run the specified probe against the implementation and observe the expected result.
-2. Apply only the specified safe, temporary breakage in the current checkout.
+1. Run the executable probe against the implementation and observe the expected result.
+2. Apply the chosen safe, temporary breakage in the current checkout.
 3. Run the same probe and confirm that the breakage causes the expected behavior to fail.
 4. Restore the implementation to its pre-breakage state. Remove temporary files and undo temporary staging changes.
 5. Run the same probe again and confirm that the expected result returns.
 
 Never apply breakage to production data or services. Restore each breakage before testing the next criterion.
-Do not change approved probes, expected results, breakages, or design decisions to obtain passing results.
+Do not change approved probe scenarios, expected results, broken behavior, or design decisions to obtain passing results.
+Keep the executable probe unchanged throughout each pass, fail, pass sequence.
 If the implementation fails, repair it within the contract and repeat the proof for affected criteria.
 If the contract needs clarification or revision, escalate instead of inventing a replacement probe or breakage.
 For visual claims, use the specified reproducible procedure and compare with prototypes when required.
 Run applicable repository checks. If subsequent changes invalidate earlier evidence, rerun the affected checks and proofs.
 
 For each criterion, record its exact `id`, actual command or procedure in `probe`, `probeStatus`, and `breakageStatus`.
-Use `probeStatus: passed` only when the implementation passes before breakage and after restoration.
+For selected breakages, record the criterion ID, temporary change, and observed failure in handoff `notes` so the verifier can reproduce them.
+Use `probeStatus: passed` when the probe passes. If breakage is required, it must pass both before breakage and after restoration.
 Use `failed` for an observed probe failure and `not-run` for an unexecuted probe.
 Use `breakageStatus: confirmed` only when the specified breakage makes the same probe detect the broken behavior.
-Use `not-confirmed` when that detection fails and `not-run` when the breakage check was not executed.
+Use `not-confirmed` when that detection fails and `not-run` when a required breakage check was not executed.
+Use `not-required` only when the approved spec does not require a breakage check. Never use it to hide an unexecuted required check.
 Do not claim confirmed breakage from an unrelated command or environment failure.
 Include every spec criterion once. Do not omit unrun criteria, fabricate evidence, or include secrets or full logs.
 
@@ -93,7 +101,7 @@ Include every spec criterion once. Do not omit unrun criteria, fabricate evidenc
 Before any terminal tool call, restore all temporary breakages and remove temporary verification files. Keep the implementation work.
 Choose the outcome from the actual result:
 
-1. `done`: Implementation and required checks are complete. Every criterion has `probeStatus: passed` and `breakageStatus: confirmed`. Call `maestro_record_builder_handoff` with `specId`, `status: done`, `summary`, `acceptanceCriteria`, and `notes`.
+1. `done`: Implementation and required checks are complete. Every criterion has `probeStatus: passed` and `breakageStatus: confirmed` or `not-required`, as specified by the approved spec. Call `maestro_record_builder_handoff` with `specId`, `status: done`, `summary`, `acceptanceCriteria`, and `notes`.
 2. Escalation: An owner decision is required. Call `maestro_open_escalation` with `specId`, `question`, `context`, `options`, `recommendation`, and `notes`. Include evidence in the context. Give each option an ID, description, consequences, and next step. Use `recommendation: null` unless evidence supports a specific option. Do not also submit a builder handoff.
 3. `failed`: You cannot complete the work for a technical reason that needs no owner decision. Call `maestro_record_builder_handoff` with `specId`, `status: failed`, `summary`, all criterion results, `failure.reason`, and `notes`. Report actual statuses, including `not-run` where applicable.
 
@@ -109,7 +117,7 @@ If a terminal call fails, inspect the error, current phase, and artifacts before
 If validation rejected the submission without writing it, correct the payload to match the tool schema and actual evidence.
 If the tool partially wrote an artifact or changed phase before an error, report it and stop. Do not resubmit.
 Never change honest statuses or omit criteria merely to make a payload pass validation.
-The tool rejects `failed` when a nonempty criterion list contains only `passed` probes and `confirmed` breakages.
+The tool rejects `failed` when a nonempty criterion list contains only `passed` probes and `confirmed` or `not-required` breakages.
 If another technical failure prevents completion in that case, report this protocol limitation to Maestro instead of falsifying criterion results.
 If the terminal call succeeded but the commit failed, address the Git error without submitting a second outcome.
 Do not delete a terminal artifact, edit workflow state, or use a different outcome to bypass an error.

package/agents/verifier.md

@@ -13,7 +13,7 @@ tools:
   - maestro_record_verifier_handoff
 systemPromptMode: replace
 inheritProjectContext: true
-inheritGlobalContext: false
+inheritGlobalContext: true
 inheritSkills: false
 completionGuard: false
 allowNestedSubagents: false
@@ -48,18 +48,28 @@ Do not run `git commit` or change the candidate to make verification succeed.
 ## Regenerate every proof
 
 Verify every acceptance criterion from the candidate, including criteria checked in earlier runs.
-Do not trust the builder's results or silently change the approved behavior, probes, expected results, or breakages.
-For each criterion, use this sequence:
-
-1. Run the specified probe against the candidate and record the observed result.
-2. Apply the specified safe, temporary breakage in the current checkout.
+Do not trust the builder's results or silently change the approved behavior, probe scenarios, expected results, or broken behavior.
+Read executable probes and breakage details from the candidate and builder handoff. Independently check that they cover the approved scenarios.
+The spec need not prescribe test code, fixtures, mocks, commands, or exact code edits. Missing execution details alone are not a contract gap.
+Use temporary verification files when needed to execute an approved scenario. Do not repair committed tests or weaken their coverage.
+If the builder's checks miss required behavior, record a finding even if your own probe passes.
+Follow any explicit execution constraints in the approved spec.
+Check breakage selection against the approved spec, not the builder's status alone.
+If the spec says Breakage: Not required or omits breakage, run the probe without a temporary breakage or restoration rerun.
+Do not add breakage checks or skip selected ones on your own. Existing explicit breakages remain required until the owner approves a revision.
+If the builder skipped a required breakage, record a finding even if your own check succeeds.
+Only for criteria with a selected breakage, use this sequence:
+
+1. Run the executable probe against the candidate and record the observed result.
+2. Apply a safe, temporary change that causes the specified broken behavior in the current checkout.
 3. Run the same probe and record whether it detects the specified broken behavior.
 4. Restore the candidate, including temporary files and staged changes.
 5. Run the same probe again and record the observed result after restoration.
 
+Keep the executable probe unchanged throughout each pass, fail, pass sequence.
 Never apply breakage to production data or services. Restore each breakage before testing the next criterion.
 If a probe fails, record a finding. Do not repair the candidate to continue the sequence.
-If a probe or breakage is unsafe, undefined, or impossible to execute, record the limitation as a finding.
+If a probe or required breakage is unsafe, undefined, or impossible to execute, record the limitation as a finding.
 Continue with other criteria that can be checked safely. Do not stop the entire review at the first finding.
 Use temporary files only as needed for the specified probes and breakages. Remove them before handoff.
 For visual claims, produce reproducible evidence through the spec's procedure, including prototype comparisons when required.
@@ -70,17 +80,19 @@ If a required check changes files, record that effect and restore those changes
 A result obtained only after an automatic fix does not prove that the candidate passes.
 
 For each criterion, record its exact `id`, actual command or procedure in `probe`, `probeStatus`, and `breakageStatus`.
-Use `probeStatus: passed` only when the candidate passes before breakage and after restoration.
+For selected breakages, record the criterion ID, temporary change, and observed failure in handoff `notes`.
+Use `probeStatus: passed` when the probe passes. If breakage is required, it must pass both before breakage and after restoration.
 Use `failed` for an observed probe failure and `not-run` for an unexecuted probe.
 Use `breakageStatus: confirmed` only when the specified breakage makes the same probe detect the broken behavior.
-Use `not-confirmed` when that detection fails and `not-run` when the breakage check was not executed.
+Use `not-confirmed` when that detection fails and `not-run` when a required breakage check was not executed.
+Use `not-required` only when the approved spec does not require a breakage check. Never use it to hide an unexecuted required check.
 An existing baseline failure or unrelated environment error does not confirm breakage.
 Include every spec criterion once. Never omit unrun criteria or fabricate evidence.
 
 ## Record findings, not decisions
 
 Record technical issues supported by fresh evidence. Do not add requirements, style preferences, or unrelated improvements.
-Give every criterion with a probe other than `passed` or breakage other than `confirmed` at least one related finding.
+Give every criterion with a probe other than `passed` or breakage other than `confirmed` or `not-required` at least one related finding.
 Report required repository check failures as findings, even when every acceptance criterion passes.
 Do not copy an earlier rejection into a new finding. Only the owner can reject current findings through Maestro.
 
@@ -94,7 +106,7 @@ For each finding, follow the tool schema:
 6. Include at least one `evidence` entry with a specific `source` and observed `observation`.
 7. Set `rejection: null`.
 
-Use `findings: []` only when every probe passes, every breakage is confirmed, and no other technical findings remain.
+Use `findings: []` only when every probe passes, every required breakage is confirmed, and no other technical findings remain.
 Keep summaries and notes concise. Do not include full logs or secrets.
 
 ## Restore and submit

package/docs/subagent-integration.md

@@ -11,6 +11,8 @@ The package contains two agent definitions:
 1. [`agents/builder.md`](../agents/builder.md) defines the builder role.
 2. [`agents/verifier.md`](../agents/verifier.md) defines the verifier role.
 
+Both agents receive project instructions and your global `AGENTS.md` from the Pi agent directory, normally `~/.pi/agent/AGENTS.md`.
+
 ## Package registration
 
 `package.json` registers the agent directory with Pi:

package/docs/workflow.md

@@ -48,7 +48,7 @@ The builder works on the current branch with a fresh context.
 
 It reads the active spec, implements the approved change, and runs every acceptance criterion.
 
-For each criterion, the builder runs the probe, applies the approved temporary breakage, confirms that the same probe fails, restores the implementation, and confirms that the probe passes again.
+The builder checks every criterion. For the criteria the owner selects in the spec, it also introduces a temporary fault to prove that the check detects it.
 
 The builder ends a run with one of these outcomes:
 
@@ -64,7 +64,7 @@ It reads the active spec and available artifacts. Historical artifacts provide c
 
 Before the verifier starts, Maestro commits a `verifier-running` checkpoint. That checkpoint is the candidate commit.
 
-The verifier does not repair product code. It independently regenerates every probe and breakage from the candidate and restores all temporary changes before its handoff. Maestro relies on verifier instructions for restoration, not a comparison with the candidate commit.
+The verifier does not repair product code. It independently checks every criterion and repeats the fault checks the owner selected in the spec. It restores all temporary changes before reporting its results.
 
 ## Main flow
 
@@ -154,11 +154,11 @@ Checks that leave product files and workflow artifacts unchanged do not need you
 
 If answering a specification question requires temporary product changes, Maestro first agrees on the question and scope with you. Commands with automatic fixes also require this agreement, even if they ultimately change no files. These experiments help clarify the spec. They do not implement the feature or replace the builder and verifier.
 
-Maestro must preserve all pre-existing changes, including uncommitted and untracked files. Before requesting spec approval or resuming the workflow, Maestro must restore only its experiment changes and remove temporary files. If cleanup fails, Maestro reports the remaining changes and stops. Experiments cannot create commits or change `workflow.json`, handoffs, or other protected workflow artifacts. Installing packages or adding or updating dependencies requires explicit owner approval. After cleanup, Maestro records the results and limits in `spec.md`.
+Maestro must preserve all pre-existing changes, including uncommitted and untracked files. Before requesting spec approval or resuming the workflow, Maestro must restore only its experiment changes and remove temporary files. If cleanup fails, Maestro reports the remaining changes and stops. Experiments cannot create commits or change `workflow.json`, handoffs, or other protected workflow artifacts. Installing packages or adding or updating dependencies requires explicit owner approval. After cleanup, Maestro records only conclusions and limits that affect the contract in `spec.md`.
 
 ## Acceptance criterion simplicity principle
 
-Each acceptance criterion must prove exactly one thing.
+Each acceptance criterion describes one observable result.
 
 ```text
 Probe
@@ -170,7 +170,9 @@ Expected result
 Breakage
   How to prove that the probe detects a broken behavior.
 ```
-Builder and verifier both run the probe, apply the specified safe breakage, run the same probe again, restore the breakage, and run the probe again. They restore every temporary change before the handoff.
+
+Breakage checks are not required by default.
+The owner selects a breakage check during spec preparation when a proof, that the test detects a specific error, is needed.
 
 ## Escalations
 
@@ -247,5 +249,5 @@ The default spec directory contains:
 ```
 
 - `builder.json` and `verifier.json` represent the current handoffs and can be overwritten by later runs. 
-- Builder handoff `notes` contain curated significant discoveries that did not require an owner decision; Maestro surfaces the applicable notes in the final workflow summary.
+- Builder handoff `notes` contain evidence for selected fault checks and significant discoveries that did not require an owner decision. Maestro summarizes the relevant results at the end.
 - Earlier versions of all artifacts remain in Git commits.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emiliosp/pi-maestro",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "A spec-driven multiagent development workflow for Pi.",
   "license": "MIT",
   "type": "module",

package/src/artifacts/builder-handoff/assertBuilderHandoff.ts

@@ -26,7 +26,8 @@ const hasOnlyCompletedChecks = (
   acceptanceCriteria.every(
     (criterion) =>
       criterion.probeStatus === PROBE_STATUSES.PASSED &&
-      criterion.breakageStatus === BREAKAGE_STATUSES.CONFIRMED,
+      (criterion.breakageStatus === BREAKAGE_STATUSES.CONFIRMED ||
+        criterion.breakageStatus === BREAKAGE_STATUSES.NOT_REQUIRED),
   );
 
 const hasValidFailedChecks = (
@@ -74,7 +75,7 @@ export function assertBuilderHandoff(
     !hasOnlyCompletedChecks(handoff.acceptanceCriteria)
   ) {
     throw new Error(
-      'Done builder handoff requires every probe to pass and every breakage check to be confirmed.',
+      'Done builder handoff requires every probe to pass and every breakage check to be confirmed or not required.',
     );
   }
 

package/src/artifacts/builder-handoff/schema.ts

@@ -28,6 +28,7 @@ export const BREAKAGE_STATUSES = {
   CONFIRMED: 'confirmed',
   NOT_CONFIRMED: 'not-confirmed',
   NOT_RUN: 'not-run',
+  NOT_REQUIRED: 'not-required',
 } as const;
 
 export type ProbeStatus = (typeof PROBE_STATUSES)[keyof typeof PROBE_STATUSES];

package/src/artifacts/verifier-handoff/assertVerifierHandoff.ts

@@ -17,7 +17,8 @@ import { isValidSpecId } from '#ids/isValidSpecId.ts';
 
 const hasCompletedChecks = (criterion: BuilderAcceptanceCriterion): boolean =>
   criterion.probeStatus === PROBE_STATUSES.PASSED &&
-  criterion.breakageStatus === BREAKAGE_STATUSES.CONFIRMED;
+  (criterion.breakageStatus === BREAKAGE_STATUSES.CONFIRMED ||
+    criterion.breakageStatus === BREAKAGE_STATUSES.NOT_REQUIRED);
 
 function assertVerifierHandoffSchema(
   input: unknown,

package/src/maestro/instructions/getMaestroInstructions.ts

@@ -29,18 +29,26 @@ Wait for each tool result before taking the next workflow action. Do not launch
 2. Read the repository and applicable AGENTS.md files. Investigate the affected behavior before asking the owner for missing information.
 3. Ask one focused question at a time. Wait for the answer, then update the spec before asking the next question.
 4. Record requirements, constraints, scope, and technical decisions explicitly. Do not invent requirements or silently resolve owner decisions.
-5. Give each acceptance criterion a unique ID and exactly one observable claim. Specify its probe, expected result, and safe temporary breakage.
-6. Require the same probe to pass before breakage, fail because of that breakage, and pass after restoration.
-7. Review the complete spec for consistency, missing decisions, measurable goals, and executable acceptance criteria. Resolve gaps with the owner.
+5. Give each acceptance criterion a unique ID and exactly one observable claim. Describe its probe scenario and expected result in plain language.
+6. Select breakage checks explicitly with the owner only where proving error detection adds value. Otherwise write Breakage: Not required. For selected checks, describe the broken behavior and require the same probe to pass, fail during breakage, and pass after restoration.
+7. Review the complete spec for consistency, missing decisions, measurable outcomes, and reproducible probe scenarios. Remove repetition and unnecessary implementation details. Resolve gaps with the owner.
 8. Request explicit approval. Only after approval, call maestro_mark_spec_ready with the active specId.
 9. Ask the owner to commit spec.md, its prototypes, and workflow.json. Do not start the builder until the checkout is clean.
 
+Write spec.md for the owner. Keep detail proportional to the change and state each requirement once.
+Use the template topics as guidance. Omit empty subsections instead of filling them with Not applicable.
+Keep behavior, scope, constraints, and approved architectural decisions in the spec. Leave routine implementation choices to the builder.
+Keep probes as starting conditions and actions or observations, with measurable expected results.
+Every probe remains mandatory for builder and verifier. Breakage checks are not required by default; do not add them to every criterion automatically.
+Describe selected breakages as wrong behavior to detect, not code edits. The builder chooses test code, fixtures, mocks, commands, and safe temporary changes.
+Do not copy agent procedures, repository rules, investigation logs, or workflow history into the spec.
+
 During spec preparation and revisions, investigate each technical decision before presenting options or recommending an answer. Do not wait for the owner to request code analysis.
 Trace the relevant code and data flow across affected components, including transformations that limit the available data.
 Use repository evidence to explain each option's feasibility, required changes, scope, and effects on existing behavior.
 Cite the relevant files. Distinguish confirmed facts from assumptions and state what you could not verify, including deployed state.
 Do not ask the owner questions that repository inspection can answer. Keep requirement choices and technical decisions with the owner.
-Record the supporting evidence and unresolved limits with the decision in spec.md. Follow the check and experiment permissions below.
+In spec.md, keep only a brief reason, essential references, and unresolved limits that affect the decision. Follow the check and experiment permissions below.
 
 ### Spec edits, checks, and experiments
 
@@ -59,7 +67,7 @@ Do not create commits or change workflow.json, handoffs, or other protected work
 Get explicit owner approval before installing packages or adding or updating dependencies.
 Before requesting spec approval or continuing the workflow, restore only your experiment changes and remove your temporary files.
 If cleanup fails, report the remaining changes and stop. Do not discard pre-existing uncommitted or untracked work.
-After cleanup, record the experiment's results and limits in spec.md. Experiments do not replace builder or verifier work.
+After cleanup, summarize only experiment conclusions and limits that affect the contract in spec.md. Experiments do not replace builder or verifier work.
 
 ### Run the workflow
 

package/src/tools/child/record-builder-handoff.ts

@@ -18,7 +18,7 @@ export const BUILDER_HANDOFF_TOOL = {
   NAME: 'maestro_record_builder_handoff',
   LABEL: 'Record Builder Handoff',
   DESCRIPTION:
-    'Record the builder pass as done or failed. Put only significant discoveries that do not require an owner decision in notes. After success, commit the implementation, handoff, and workflow state together with Bash and Git.',
+    'Record the builder pass as done or failed. Put selected breakage evidence and significant discoveries that do not require an owner decision in notes. After success, commit the implementation, handoff, and workflow state together with Bash and Git.',
 } as const;
 
 const BuilderHandoffContentFields = {

package/templates/spec.md

@@ -2,102 +2,65 @@
 
 > After owner approval, this specification is the contract for the builder and verifier.
 
-## 1. Context, goals, and scope
-
-<Describe the current situation, who or what is affected, and the problem or opportunity without describing the implementation.>
+<!--
+Write for the owner, not only for agents. Keep detail proportional to the change.
+State each requirement once. Refer to it from acceptance criteria instead of repeating it.
+Use the topics below as guidance, not a checklist to fill. Omit empty subsections and these instructions.
+Leave local implementation choices, test code, fixtures, mocks, and commands to the builder.
+-->
 
-### Measurable goals
+## 1. Context, goals, and scope
 
-- <Observable outcome that must become possible.>
-- <Metric or verifiable condition that defines success.>
+<Briefly describe the problem, who is affected, and the intended outcome.>
 
 ### Out of scope
 
-- <Related behavior, integration, migration, or component that must not be implemented.>
-- <Existing behavior that remains unchanged and is not being redesigned.>
-
-Write `No additional out-of-scope items.` when none are known.
+<Name related changes that are explicitly excluded.>
 
 ## 2. Requirements and constraints
 
-### Functional requirements
-
-- <Behavior the system must provide.>
-- <Actor or system action and its required outcome.>
-
-Write `No new functional behavior.` when the change is purely technical.
-
-### Non-functional requirements
-
-- <Measurable performance, reliability, security, accessibility, privacy, or compatibility requirement.>
+<Describe required behavior and measurable limits. Include performance, reliability, accessibility, or other quality requirements only when relevant.>
 
-Write `No additional non-functional requirements.` when none apply.
-
-### Constraints
-
-- <Non-negotiable technical, business, legal, security, operational, or compatibility boundary.>
-- <Existing behavior or contract that must remain unchanged.>
-
-Write `No additional constraints.` when none are known.
+<Include non-negotiable boundaries and existing behavior that this change must preserve. Do not copy repository or agent instructions.>
 
 ### Edge cases and error handling
 
-| Case | Expected behavior | State and recovery |
-|---|---|---|
-| <Boundary or error condition> | <Observable system behavior> | <Preserved state, rollback, retry, or recovery behavior> |
-| <Unavailable dependency> | <Error presented to the caller or user> | <Partial state handling and retry behavior> |
-| <Repeated or concurrent operation> | <Idempotent, serialized, or conflict behavior> | <Resulting authoritative state> |
-
-Every required edge case must be covered by an acceptance criterion.
-
-Write `No additional edge cases.` only when none apply.
-
-## 3. Technical design
-
-<Describe the approved technical decisions that affect the repository architecture. Do not list every file or local implementation detail.>
+<Describe boundary conditions, failures, and required recovery behavior not already covered above. Cover each required case in the acceptance criteria.>
 
-Include only relevant optional subsections. Write `No architectural changes. Follow the existing repository patterns.` when none apply.
+## 3. Technical decisions and prototypes
 
-### Components and data flow
+<Record only approved architectural decisions or technical constraints that affect scope or behavior. Explain their reasons briefly. Leave routine implementation choices to the builder.>
 
-<Describe affected components, responsibilities, data models, state changes, and important boundaries.>
+<For each relevant topic below, add a short subsection. Omit topics that do not apply.>
 
-### API specification
+1. Components and data flow: changed responsibilities, data contracts, and important boundaries. No file inventory or function-level design.
+2. API specification: changed operations, permissions, inputs, outputs, errors, side effects, and delivery guarantees.
+3. Prototype and user interaction: link prototypes and identify approved states and interactions. Distinguish illustrative content from requirements.
+4. External integrations: affected services, failure behavior, and retries.
+5. Security and privacy: access rules, sensitive data, retention, and trust boundaries.
+6. Compatibility and migration: compatibility limits, migration, rollout, and rollback requirements.
+7. Monitoring and observability: required signals, alerts, and ownership.
 
-Write `Not applicable.` when no API contract changes.
-
-For each operation, define the protocol and operation, caller permissions, input, successful output, errors and side effects, and delivery or consistency rules.
-
-### Prototype and user interaction
-
-Write `Not applicable.` when there is no visual or interactive behavior.
-
-- `prototypes/<surface-name>.<html|png|jpg|jpeg>`: <surface and states represented by the prototype>
-
-<Describe user triggers, state transitions, validation, feedback, accessibility, and recovery behavior.>
-
-### External integrations
-
-<Describe affected services, SDKs, events, queues, webhooks, failure boundaries, and retry behavior.>
-
-### Security and privacy
-
-<Describe authentication, authorization, trust boundaries, sensitive-data handling, retention, encryption, and redaction.>
-
-### Compatibility and migration
-
-<Describe backward compatibility, migration, rollout, rollback, and coexistence with older versions.>
-
-### Monitoring and observability
-
-Write `Not applicable.` when no operational signal changes.
-
-<Describe required signals, triggers, diagnostic information, alerts, thresholds, ownership, and sensitive data that must not be recorded.>
+<Include only evidence and unresolved limits that affect an owner decision. Do not include investigation logs or general verification disclaimers.>
 
 ## 4. Acceptance criteria
 
+<Give each criterion a unique ID and one observable claim. A probe is the scenario used to check that claim. Describe it in plain language.>
+
 ### AC1: <short observable claim>
 
-- **Probe**: <exact command, API call, or reproducible procedure>
-- **Expected result**: <observable and measurable result>
-- **Breakage**: <specific temporary implementation change that must make the probe fail>
+1. Probe: <starting conditions and action or observation, without prescribing test implementation>
+2. Expected result: <observable and measurable outcome>
+3. Breakage: Not required. <Only when selected with the owner: describe the wrong behavior that a safe temporary change must cause and the probe must detect.>
+
+<!--
+Example:
+Probe: Save a change, then reopen the item.
+Expected result: The saved change is still present.
+Breakage (if selected): Discard the change instead of saving it.
+
+Breakage checks are not required by default. Select them with the owner only when proving error detection adds value.
+The builder and verifier each run every probe. For selected breakages only, they also run the same probe during breakage and after restoration.
+The builder chooses executable checks and safe temporary changes. The verifier checks their coverage independently.
+Keep execution evidence in handoffs, not in this spec.
+-->