@emiliosp/pi-maestro 0.4.5 → 0.5.1

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.
-- Every acceptance criterion is checked independently. You select which criteria also need a temporary fault to prove error detection.
+- Every acceptance criterion is checked independently.
 - An agent never decides for the owner, and never guesses.
 
 ## The roles

package/agents/builder.md

@@ -54,49 +54,33 @@ Record significant discoveries without an owner decision in handoff `notes`. Do
 ## Prove every acceptance criterion
 
 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.
+The spec defines probe scenarios, expected results, and concrete examples.
 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 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 probe scenarios, expected results, broken behavior, or design decisions to obtain passing results.
-Keep the executable probe unchanged throughout each pass, fail, pass sequence.
+Run each executable probe against the implementation and compare the observed result with the expected result.
+Do not change approved probe scenarios, expected results, examples, or design decisions to obtain passing results.
 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.
+If the contract needs clarification or revision, escalate instead of inventing a replacement probe.
 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`.
-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.
+For each criterion, record its exact `id`, actual command or procedure in `probe`, and `probeStatus`.
+Use `probeStatus: passed` when the observed result matches the expected result.
 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 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.
 
 ## Record exactly one outcome
 
-Before any terminal tool call, restore all temporary breakages and remove temporary verification files. Keep the implementation work.
+Before any terminal tool call, restore temporary verification changes 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` or `not-required`, as specified by the approved spec. 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`. 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.
 
 After a successful terminal call, commit the implementation and generated protocol files together through Bash and Git.
 For `done` or `failed`, include `workflow.json` and `handoffs/builder.json`. For escalation, include `workflow.json` and the generated escalation file.
-Inspect the staged changes before committing. Do not include temporary breakages, temporary files, or unrelated changes.
+Inspect the staged changes before committing. Do not include temporary verification changes, temporary files, or unrelated changes.
 Confirm that the checkout is clean, then return a concise outcome and commit ID to Maestro. Stop the pass.
 Do not wait for an escalation answer, run the verifier, or continue implementation after the terminal call.
 
@@ -106,7 +90,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` or `not-required` breakages.
+The tool rejects `failed` when a nonempty criterion list contains only `passed` probes.
 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

@@ -38,30 +38,17 @@ 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, 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.
+Do not trust the builder's results or silently change the approved behavior, probe scenarios, expected results, or examples.
+Read executable probes 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 required breakage is unsafe, undefined, or impossible to execute, record the limitation as a finding.
+Run each executable probe against the candidate and compare the observed result with the expected result.
+If a probe fails, record a finding. Do not repair the candidate.
+If a probe 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.
+Use temporary files only as needed for the specified probes. Remove them before handoff.
 For visual claims, produce reproducible evidence through the spec's procedure, including prototype comparisons when required.
 
 Follow applicable repository commands and technical rules. Do not invent required commands.
@@ -69,20 +56,15 @@ Inspect check scripts before execution. Do not use automatic fixes to repair the
 If a required check changes files, record that effect and restore those changes before further verification.
 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`.
-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.
+For each criterion, record its exact `id`, actual command or procedure in `probe`, and `probeStatus`.
+Use `probeStatus: passed` when the observed result matches the expected result.
 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 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` or `not-required` at least one related finding.
+Give every criterion with a probe other than `passed` 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.
 
@@ -96,12 +78,12 @@ 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 required breakage is confirmed, and no other technical findings remain.
+Use `findings: []` only when every probe passes and no other technical findings remain.
 Keep summaries and notes concise. Do not include full logs or secrets.
 
 ## Restore and submit
 
-Before handoff, restore every temporary change from probes, breakages, and repository checks.
+Before handoff, restore every temporary change from probes and repository checks.
 Compare both staged and unstaged files with the supplied candidate commit. Inspect untracked files as well.
 Remove only temporary files created during this pass. Do not overwrite unrelated changes or use blanket cleanup commands.
 All files outside the tool-owned `workflow.json` and `handoffs/verifier.json` must match the candidate.

package/docs/workflow.md

@@ -46,9 +46,7 @@ The owner has final authority over:
 
 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.
-
-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.
+It reads the active spec, implements the approved change, and runs every probe against its expected result.
 
 The builder ends a run with one of these outcomes:
 
@@ -64,7 +62,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 checks every criterion and repeats the fault checks the owner selected in the spec. It restores all temporary changes before reporting its results.
+The verifier does not repair product code. It independently runs every probe against its expected result. It restores all temporary changes before reporting its results.
 
 ## Main flow
 
@@ -167,12 +165,11 @@ Probe
 Expected result
   What the probe must observe.
 
-Breakage
-  How to prove that the probe detects a broken behavior.
+Example
+  Specific starting conditions, input or action, and the exact expected result.
 ```
 
-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.
+The builder and verifier each run every probe and compare the observed result with the expected result.
 
 ## Escalations
 
@@ -249,5 +246,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 evidence for selected fault checks and significant discoveries that did not require an owner decision. Maestro summarizes the relevant results at the end.
+- Builder handoff `notes` contain 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.5",
+  "version": "0.5.1",
   "description": "A spec-driven multiagent development workflow for Pi.",
   "license": "MIT",
   "type": "module",

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

@@ -5,7 +5,6 @@
 
 import { Value } from 'typebox/value';
 import {
-  BREAKAGE_STATUSES,
   BUILDER_HANDOFF_STATUSES,
   type BuilderAcceptanceCriterion,
   type BuilderHandoff,
@@ -20,21 +19,17 @@ const hasUniqueAcceptanceCriterionIds = (
   new Set(acceptanceCriteria.map((criterion) => criterion.id)).size ===
   acceptanceCriteria.length;
 
-const hasOnlyCompletedChecks = (
+const hasOnlyPassedProbes = (
   acceptanceCriteria: BuilderAcceptanceCriterion[],
 ): boolean =>
   acceptanceCriteria.every(
-    (criterion) =>
-      criterion.probeStatus === PROBE_STATUSES.PASSED &&
-      (criterion.breakageStatus === BREAKAGE_STATUSES.CONFIRMED ||
-        criterion.breakageStatus === BREAKAGE_STATUSES.NOT_REQUIRED),
+    (criterion) => criterion.probeStatus === PROBE_STATUSES.PASSED,
   );
 
 const hasValidFailedChecks = (
   acceptanceCriteria: BuilderAcceptanceCriterion[],
 ): boolean =>
-  acceptanceCriteria.length === 0 ||
-  !hasOnlyCompletedChecks(acceptanceCriteria);
+  acceptanceCriteria.length === 0 || !hasOnlyPassedProbes(acceptanceCriteria);
 
 function assertBuilderHandoffSchema(
   input: unknown,
@@ -72,11 +67,9 @@ export function assertBuilderHandoff(
 
   if (
     handoff.status === BUILDER_HANDOFF_STATUSES.DONE &&
-    !hasOnlyCompletedChecks(handoff.acceptanceCriteria)
+    !hasOnlyPassedProbes(handoff.acceptanceCriteria)
   ) {
-    throw new Error(
-      'Done builder handoff requires every probe to pass and every breakage check to be confirmed or not required.',
-    );
+    throw new Error('Done builder handoff requires every probe to pass.');
   }
 
   if (

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

@@ -24,28 +24,15 @@ export const PROBE_STATUSES = {
   NOT_RUN: 'not-run',
 } as const;
 
-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];
 
-export type BreakageStatus =
-  (typeof BREAKAGE_STATUSES)[keyof typeof BREAKAGE_STATUSES];
-
 const ProbeStatusSchema = StringEnum(Object.values(PROBE_STATUSES));
 
-const BreakageStatusSchema = StringEnum(Object.values(BREAKAGE_STATUSES));
-
 export const BuilderAcceptanceCriterionSchema = Type.Object(
   {
     id: Type.String({ minLength: 1 }),
     probe: Type.String({ minLength: 1 }),
     probeStatus: ProbeStatusSchema,
-    breakageStatus: BreakageStatusSchema,
   },
   { additionalProperties: false },
 );

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

@@ -4,22 +4,13 @@
  */
 
 import { Value } from 'typebox/value';
-import {
-  BREAKAGE_STATUSES,
-  type BuilderAcceptanceCriterion,
-  PROBE_STATUSES,
-} from '#artifacts/builder-handoff/schema.ts';
+import { PROBE_STATUSES } from '#artifacts/builder-handoff/schema.ts';
 import {
   type VerifierHandoff,
   VerifierHandoffSchema,
 } from '#artifacts/verifier-handoff/schema.ts';
 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.NOT_REQUIRED);
-
 function assertVerifierHandoffSchema(
   input: unknown,
 ): asserts input is VerifierHandoff {
@@ -89,7 +80,10 @@ export function assertVerifierHandoff(
   );
 
   for (const criterion of handoff.acceptanceCriteria) {
-    if (!hasCompletedChecks(criterion) && !findingCriteria.has(criterion.id)) {
+    if (
+      criterion.probeStatus !== PROBE_STATUSES.PASSED &&
+      !findingCriteria.has(criterion.id)
+    ) {
       throw new Error(
         `Verifier handoff incomplete acceptance criterion "${criterion.id}" requires a finding.`,
       );

package/src/maestro/instructions/getMaestroInstructions.ts

@@ -30,10 +30,9 @@ Wait for each tool result before taking the next workflow action. Do not launch
 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. Describe its probe scenario and expected result in plain language. Include a concrete example in every criterion, both in spec.md and when presenting it to the owner.
-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.
+6. 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.
+7. Request explicit approval. Only after approval, call maestro_mark_spec_ready with the active specId.
+8. 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.
@@ -41,10 +40,19 @@ Keep behavior, scope, constraints, and approved architectural decisions in the s
 Keep probes as starting conditions and actions or observations, with measurable expected results.
 Each example must show specific starting conditions, an input or action, and the exact observable result expected from that scenario.
 Use concrete values or states, not a restatement of the claim. Keep examples within the criterion's scope and approved behavior.
-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.
+Every probe remains mandatory for builder and verifier.
+The builder chooses test code, fixtures, mocks, and commands.
 Do not copy agent procedures, repository rules, investigation logs, or workflow history into the spec.
 
+During spec preparation and revisions, identify the decisions and unresolved facts that each open question depends on.
+Ask a question only after its prerequisite decisions are settled and the relevant investigation is complete.
+After each owner answer or investigation result, update the remaining questions and remove those that no longer apply.
+If an earlier decision changes, review the decisions that depend on it.
+
+Before requesting approval for an initial or revised spec, check that all decisions needed for the agreed scope are explicit.
+Resolve open decisions with the owner before requesting approval. Do not leave necessary decisions as implicit assumptions.
+Do not extend this check to routine implementation choices that belong to the builder.
+
 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.

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 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.',
+    'Record the builder pass as done or failed. Put 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

@@ -52,17 +52,14 @@ Leave local implementation choices, test code, fixtures, mocks, and commands to
 1. Probe: <starting conditions and action or observation, without prescribing test implementation>
 2. Expected result: <observable and measurable outcome>
 3. Example: <specific starting conditions, concrete input or action, and exact expected result for this probe, not a restatement of the claim>
-4. 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 to an item's title, then reopen the item.
 Expected result: The saved title is still present.
 Example: An item's title is "Draft". Change it to "Ready", save, and reopen the item. The title is "Ready".
-Breakage (if selected): Discard the title 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.
+The builder and verifier each run every probe.
+The builder chooses executable checks. The verifier checks their coverage independently.
 Keep execution evidence in handoffs, not in this spec.
 -->