@emiliosp/pi-maestro 0.1.1 → 0.1.2

package/README.md

@@ -6,7 +6,7 @@ Pi extension for a spec-driven multiagent development workflow.
 
 ## The idea
 
-One spec describes one small reversible change. An agent builds it. A second, independent agent regenerates each acceptance criterion from scratch. The owner performs the final review and controls the Git flow after the candidate is ready.
+One spec describes one small reversible change. An agent builds it. A second, independent agent regenerates each acceptance criterion from scratch. The owner performs the final review. 
 
 Four principles hold the workflow together:
 
@@ -19,7 +19,7 @@ Four principles hold the workflow together:
 
 - **Owner** — You. You bring the problem, decide every escalation and every finding, review the final code, and control the Git flow after the candidate is ready. You never talk to a builder or a verifier.
 - **Maestro** — The agent you talk to. It writes the spec with you, spawns and supervises the other agents, records your decisions, and summarizes the results.
-- **Builder** — The agent that implements one spec. It never verifies its own work.
+- **Builder** — The agent that implements one spec. It never approves its own work.
 - **Verifier** — The agent that verifies if the builder implementation is technically compliant to the spec.
 
 ## Prerequisites
@@ -67,11 +67,11 @@ Follow this workflow:
 3. Review the spec with Maestro.
 4. Approve the spec.
 5. Commit the approved `spec.md` and `workflow.json` on the current branch.
-6. Ask Maestro to launch the builder.
+6. Ask Maestro to run the builder.
 7. Review builder escalations and answer them.
 8. Review verifier findings and choose an action for each finding.
 9. When the workflow reaches `candidate-ready`, read Maestro's summary of the results and Pull Request facts.
-10. Review or change the candidate as needed, then open a Pull Request from the current branch and choose the merge method.
+10. Review or change the candidate as needed. 
 
 Do not change product code while the workflow runs. The workflow is complete when it reaches `candidate-ready`. No final tool call is needed. Changes after completion are outside the Maestro review.
 
@@ -79,7 +79,7 @@ If an escalation or finding requires a contract change, edit and approve `spec.m
 
 Builder and verifier runs stay in the foreground. Pi waits for each run before you continue the conversation. Maestro shows the current phase in Pi's status. Use pi-subagents FleetView or `/subagents-fleet` to inspect live activity and the transcript.
 
-Restarting Pi, disabling Maestro, or using `/resume` clears live session state. Maestro does not recover an incomplete workflow from `workflow.json`.
+Restarting Pi, disabling Maestro, or using `/resume` clears live session state. Maestro does not recover an incomplete workflow. 
 
 ## Configuration
 

package/agents/verifier.md

@@ -24,7 +24,7 @@ You are the independent verifier. Work only in the current Git checkout and bran
 
 Read the approved spec and relevant prototypes, the current workflow state, applicable `AGENTS.md` files, the builder handoff, and earlier verifier handoffs and owner decisions for this spec. The approved `spec.md` is the contract between the owner, Maestro, the builder, and you. Verify the candidate against that contract; do not silently reinterpret or expand it. Use the handoffs for context, not as proof. Follow repository commands and technical rules in the applicable `AGENTS.md` files; do not invent required commands. Do not modify the spec, prototypes, workflow state, or handoff files directly. Use the Maestro child tool for the terminal artifact.
 
-The candidate is the parent of the `verifier-running` checkpoint. Independently regenerate evidence for *every* acceptance criterion from that candidate commit. Run each probe and observe its expected result. Apply the specified safe, temporary breakage only in the current checkout, run the *same* probe and observe failure, restore every breakage fully, then rerun the same probe and observe success. Do not change approved probes, expected results, or breakages. Verify visual claims with reproducible evidence using the spec and repository instructions, including prototype comparisons when required. Run applicable repository checks. Record the actual command or procedure and honest probe and breakage statuses for every criterion, including `not-run` when necessary. Never treat the builder's results as evidence.
+The candidate is the `verifier-running` checkpoint identified by the commit ID supplied by Maestro. Use that fixed commit, not a later `HEAD`. Independently regenerate evidence for *every* acceptance criterion from that candidate commit. Run each probe and observe its expected result. Apply the specified safe, temporary breakage only in the current checkout, run the *same* probe and observe failure, restore every breakage fully, then rerun the same probe and observe success. Do not change approved probes, expected results, or breakages. Verify visual claims with reproducible evidence using the spec and repository instructions, including prototype comparisons when required. Run applicable repository checks. Record the actual command or procedure and honest probe and breakage statuses for every criterion, including `not-run` when necessary. Never treat the builder's results as evidence.
 
 Do not repair product code, even if a probe fails. Use `edit` and `write` only to apply and restore temporary breakages. Record technical observations as findings with evidence, not questions or decisions. Give each finding a unique `F1`, `F2`, etc. ID, an acceptance criterion ID when relevant (otherwise `null`), severity, confidence, concise summary, and source plus observation. Every criterion with a probe other than `passed` or breakage other than `confirmed` needs a related finding. A finding always starts with `rejection: null`; only Maestro can record an owner rejection. Use `findings: []` only if every probe passes and every breakage is confirmed. Do not include full logs or secrets.
 

package/docs/configuration.md

@@ -6,7 +6,7 @@ Maestro reads project configuration from:
 .pi/maestro.json
 ```
 
-The file is optional. Maestro uses all default values when the file is absent.
+The file is optional, and Maestro uses all default values when it is absent.
 
 ## Default configuration
 
@@ -56,10 +56,6 @@ xhigh
 max
 ```
 
-Each object accepts only the documented fields. Unknown fields stop activation and produce an error.
-
-When a run reaches its timeout, Maestro reports it and does not treat the run as complete.
-
 ## Partial configuration
 
 Only `version` is required when the file exists. Each other field overrides its matching default.
@@ -77,19 +73,16 @@ This example keeps every default except the builder timeout.
 
 ## Schema version
 
-`version` identifies the configuration schema. It is separate from the npm package version.
-
-The current schema version is `1.0.0`. An unsupported major version stops Maestro activation. Minor and patch versions represent compatible schema changes supported by the installed Maestro release.
+`version` identifies the configuration schema. It is separate from the npm package version, and it's a mechanism for future-proof additions.
 
 ## Path rules
 
 `specDirectory` must meet these rules:
 
-- The path is relative to the Git repository root.
-- The path points below the repository root.
-- The resolved path stays inside the repository, including through symlinks.
+1. The path is relative to the Git repository root.
+2. The path points below the repository root after `.` and `..` are resolved.
 
-An invalid path stops Maestro activation. Maestro validates the path while it loads configuration, but does not create the directory then. Workflow actions create a spec directory and its artifacts only when they need them.
+It's owner responsibility to arrange the filesystem in order to support artifact writes and Git checkpoints.
 
 ## Model access
 
@@ -97,13 +90,9 @@ Maestro checks both configured models during activation. Each model must exist a
 
 A model error stops activation and identifies the affected model. Update the configuration or authenticate the provider, then run `/maestro` again.
 
-## Fixed values
-
-Agent names:
+Agent names have fixed value:
 
 ```text
 maestro.builder
 maestro.verifier
-```
-
-Maestro does not require a branch naming pattern. The owner selects the current branch before using the workflow.
+```

package/docs/subagent-integration.md

@@ -1,6 +1,8 @@
 # Subagent integration
 
-Maestro uses `pi-subagents` to run the builder and verifier as child sessions. A child session is a separate Pi session that receives one role and one task. An agent definition is a Markdown file that gives the child its role, tools, and system prompt. A system prompt is the instruction text that the child follows.
+Maestro uses `pi-subagents` to run the builder and verifier as child sessions. 
+
+A child session is a separate Pi session that receives one role and one task.
 
 ## Agent definitions
 
@@ -9,10 +11,6 @@ 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.
 
-Each file has YAML frontmatter at the top. Frontmatter is the YAML block between the two `---` lines. The text after the frontmatter is the system prompt.
-
-The frontmatter defines the agent name, tools, context rules, and child-only extensions. The system prompt defines the role rules and the work procedure.
-
 ## Package registration
 
 `package.json` registers the agent directory with Pi:
@@ -29,25 +27,28 @@ The frontmatter defines the agent name, tools, context rules, and child-only ext
 }
 ```
 
-The `pi.subagents.agents` field tells `pi-subagents` to scan `./agents` for agent definitions. Pi scans nested directories as well.
+The `pi.subagents.agents` field tells `pi-subagents` to scan `./agents` for agent definitions. 
 
-The `package` and `name` fields in each file form the runtime name that delegation uses. The builder file has `package: maestro` and `name: builder`, so its runtime name is `maestro.builder`. The verifier runtime name is `maestro.verifier`.
+The `package` and `name` fields in each file form the runtime name that delegation uses.
 
-## Launch flow
+## Run flow
 
-When the owner launches the builder, the integration follows these steps:
+When the owner runs the builder, the integration follows these steps:
 
-1. The owner calls `maestro_launch_builder`.
-2. `src/tools/main/launch-builder.ts` prepares the workflow and emits a delegation request.
+1. The owner calls `maestro_run_builder`.
+2. `src/tools/main/run-builder.ts` prepares the workflow and emits a delegation request.
 3. The request sets `agent: AGENTS.BUILDER`.
 4. `AGENTS.BUILDER` has the value `maestro.builder` in `src/config/schema.ts`.
 5. `pi-subagents` resolves `maestro.builder` to `agents/builder.md`.
 6. The child receives the system prompt and the tools from that agent definition.
+7. Maestro waits for the child to finish, checks its result, and returns it to the owner.
 
-Maestro also passes the explicit spec ID, the current repository root, the configured model, the thinking level, the timeout, and a fresh context. The task text tells the builder to read the applicable `AGENTS.md` files.
+Maestro also passes the explicit spec ID, the current repository root, the configured model, the thinking level, the timeout, and a fresh context.
 
-The verifier uses the same name mapping with `AGENTS.VERIFIER` and `maestro.verifier`.
+`maestro_run_verifier` in `src/tools/main/run-verifier.ts` uses the same flow with `AGENTS.VERIFIER` and `maestro.verifier`. Both tools run in the foreground and wait for a result.
 
 ## Subagent extension
 
-Both agent files set `subagentOnlyExtensions` to `../extensions/maestro-subagent.ts`. This field tells `pi-subagents` to load the extension only in the child session for that agent.
+Both agent files set `subagentOnlyExtensions` to `../extensions/maestro-subagent.ts`. 
+
+This field tells `pi-subagents` to load the extension only in the child session for that agent.

package/docs/workflow.md

@@ -2,17 +2,23 @@
 
 Maestro manages one spec-driven development workflow in the current session.
 
-The approved `spec.md` is the contract between the owner, Maestro, the builder, and the verifier. It defines the intended behavior, constraints, technical decisions, and acceptance criteria. Implementation details that the contract leaves open are decided during the work. Changes to the contract's behavior, scope, or approved decisions require an owner-approved revision.
+The approved `spec.md` is the contract between the owner, Maestro, the builder, and the verifier. 
 
-The owner works with Maestro. Builder and verifier communicate with Maestro through repository handoffs. Maestro prepares the spec, updates workflow state, starts the builder and verifier, and records owner decisions.
+It defines the intended behavior, constraints, technical decisions, and acceptance criteria. 
 
-Maestro uses the current Git checkout and branch. It does not create, switch, name, or validate a branch. It does not create worktrees. If the owner starts on `main`, `master`, or another branch, all workflow commits use that branch.
+The owner works directly with Maestro. 
+
+Maestro, using the current Git branch, prepares the spec, updates workflow state, starts the builder and verifier, and records owner decisions.
+
+Builder and verifier runs are foreground operations, and communicate with Maestro through repository handoffs. 
+
+Pi waits for each run before the owner continues. Maestro's Pi status shows the current phase, and pi-subagents FleetView shows the live activity and transcript.
 
 ## Roles
 
 ### Owner
 
-The owner is the human in the loop. Every decision that needs human judgment returns to the owner.
+The owner is the human in the loop: every decision that needs human judgment returns to the owner.
 
 The owner has final authority over:
 
@@ -25,12 +31,8 @@ The owner has final authority over:
 - Git flow after the candidate is ready
 - Final Pull Request and merge
 
-The owner does not change product code while the workflow is running. The owner may revise `spec.md` while the workflow is blocked, as described below.
-
 ### Maestro
 
-Maestro:
-
 - Discusses the change with the owner
 - Writes and reviews the spec with the owner
 - Creates workflow artifacts on the current branch
@@ -40,11 +42,11 @@ Maestro:
 - Records explicit owner decisions
 - Summarizes the results and facts for a Pull Request when the candidate is ready
 
-Maestro does not know or manage a target branch.
-
 ### Builder
 
-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 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.
 
@@ -52,29 +54,17 @@ The builder ends a run with one of these outcomes:
 
 - `done`
 - `failed`
-- An escalation
-
-The builder uses `maestro_record_builder_handoff` or `maestro_open_escalation`, then commits the implementation, generated workflow state, and handoff together.
+- An `escalation`
 
 ### Verifier
 
-The verifier works on the current branch with a fresh context. It reads the active spec and available artifacts. Historical artifacts provide context, not proof; the verifier decides which information is still applicable to the active spec.
+The verifier works on the current branch with a fresh context. 
 
-The verifier independently regenerates every probe and breakage from the candidate. It does not repair product code and does not commit through Bash.
+It reads the active spec and available artifacts. Historical artifacts provide context, not proof.
 
-Before the verifier starts, Maestro commits a `verifier-running` checkpoint. The candidate is the parent of that checkpoint's `HEAD`.
+Before the verifier starts, Maestro commits a `verifier-running` checkpoint. That checkpoint is the candidate commit.
 
-The verifier applies and restores temporary breakages. `maestro_record_verifier_handoff` compares product files with that parent commit. If the product is unchanged, the tool writes `verifier.json` and `workflow.json` and commits only those protocol files. If product changes remain, the tool returns `PRODUCT_FILES_MODIFIED` and does not write or commit the handoff.
-
-There is no numbered verifier pass and no separate verifier branch. The current artifact is always:
-
-```text
-.specs/<spec-id>/handoffs/verifier.json
-```
-
-Git preserves earlier verifier handoffs.
-
-Builder and verifier runs are foreground operations. Pi waits for each run before the owner continues. Maestro's Pi status shows the current phase, and pi-subagents FleetView shows the live activity and transcript.
+The verifier never changes product code, it independently regenerates every probe and breakage from the candidate.
 
 ## Main flow
 
@@ -95,7 +85,7 @@ flowchart TD
 
     buildOutcome -->|Escalation| escalation[Builder records an escalation and stops]
     escalation --> ownerAnswer[Owner decides]
-    ownerAnswer --> escalationOutcome{Does the contract change?}
+    ownerAnswer --> escalationOutcome{Does the spec change?}
     escalationOutcome -->|No| recordContinue[Maestro records the resolution]
     recordContinue --> build
     escalationOutcome -->|Yes| reviseSpec[Owner revises and approves spec.md]
@@ -127,27 +117,25 @@ flowchart TD
 
 ## Workflow phases
 
-Maestro stores the current phase in `.specs/<spec-id>/workflow.json` by default.
+Each spec has a `workflow.json` file that records its progress. Maestro creates and updates this file. It stores the current phase, which tells you where the work stands. For example, `ready-for-verifier` means that the builder completed the work and the verifier can start.
+
+Maestro stores this file at `.specs/<spec-id>/workflow.json`.
 
 | Phase | Meaning |
 |---|---|
-| `drafting-spec` | Owner and Maestro are preparing the initial spec. |
-| `ready-for-builder` | The owner approved the spec and it awaits a builder run. |
-| `builder-running` | A builder run is active. |
-| `escalation-decision` | The owner must decide how to resolve the active escalation. |
-| `builder-failed` | The builder ended the run with a failure. |
-| `ready-for-verifier` | Builder work is ready for independent verification. |
-| `verifier-running` | A verifier run is active. |
-| `findings-decision` | The owner must decide how to handle verifier findings. |
-| `candidate-ready` | The candidate passed verification or all findings were rejected with reasons. This is the last persisted Maestro phase. |
+| `drafting-spec` | Owner and Maestro are preparing the initial spec |
+| `ready-for-builder` | The owner approved the spec and it awaits a builder run |
+| `builder-running` | A builder run is active |
+| `escalation-decision` | The owner must decide how to resolve the active escalation |
+| `builder-failed` | The builder ended the run with a failure |
+| `ready-for-verifier` | Builder work is ready for independent verification |
+| `verifier-running` | A verifier run is active |
+| `findings-decision` | The owner must decide how to handle verifier findings |
+| `candidate-ready` | The candidate commit passed verification or all findings were rejected with reasons. This is the last persisted Maestro phase |
 
-A session can have one active Maestro workflow. A workflow in `candidate-ready` is complete from Maestro's point of view. Completed or abandoned workflows can remain under the spec directory.
+Disabling Maestro, restarting Pi, or using `/resume` clears live session state. Maestro does not resume an incomplete workflow, the owner must clean it up manually.
 
-Disabling Maestro, restarting Pi, or using `/resume` clears live session state. Maestro does not resume an incomplete workflow from `workflow.json`; the owner must clean it up manually.
-
-## Spec approval and revision
-
-Maestro treats `spec.md` as opaque Markdown. It checks the workflow phase and file existence, but does not parse the spec or compare its content with an earlier version.
+## Spec approval
 
 For the initial spec:
 
@@ -156,22 +144,7 @@ For the initial spec:
 3. `maestro_mark_spec_ready` changes the phase to `ready-for-builder`.
 4. The owner commits `spec.md` and `workflow.json` on the current branch.
 
-The committed `spec.md` and `workflow.json` are the approved contract for the builder and verifier. The contract is immutable during a builder or verifier pass. When a discovery shows that the contract must change, the owner makes an explicit revision and approval before the next pass.
-
-A contract revision is allowed only from these blocked phases:
-
-- `escalation-decision`
-- `findings-decision`
-
-`builder-failed` is a sink state. Maestro reports the technical error and stops the workflow; it does not retry the builder or revise the spec from that state.
-
-The owner edits and approves `spec.md`, then calls `maestro_mark_spec_ready` directly from the blocked phase. The tool changes the phase to `ready-for-builder`. There is no separate revision phase and no new `specId`.
-
-The previous escalation or finding becomes inactive. Its artifact remains in the branch as historical context. Builder and verifier decide whether historical artifacts apply to the current spec.
-
-The workflow does not store a separate spec version. The active contract is the current `spec.md`; Git preserves earlier versions and approvals.
-
-Immediately before each builder launch, Maestro calculates the SHA-256 of the current `spec.md` and stores it only in live session state. Builder handoff and escalation tools compare the current file with that baseline. A spec revision receives its new baseline only after the owner approves it. Restart, `/resume`, and deactivation discard the live baseline.
+The committed `spec.md` represents the approved contract for the builder and verifier. The spec is immutable during a builder or verifier pass.
 
 ## Acceptance criterion simplicity principle
 
@@ -187,23 +160,29 @@ Expected result
 Breakage
   How to prove that the probe detects a broken behavior.
 ```
-
-Each distinct error behavior required by the spec must have its own acceptance criterion. Equivalent inputs that produce the same behavior can share one criterion.
-
-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 must restore every temporary change before the handoff.
+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.
 
 ## Escalations
 
 An escalation is the way Maestro brings a significant implementation discovery to the owner's attention and asks for a decision. It is not necessarily a technical failure, an error, or a blocker.
 
-An escalation is relevant when the work presents meaningful alternatives with different consequences. Examples include a conflict between the approved contract and the repository, behavior that the contract does not define, a material architectural alternative, a possible scope change, or a decision that affects verification or reversibility.
+An escalation is relevant when the work presents meaningful alternatives with different consequences. 
 
-Each escalation presents a question, context and evidence, available options, consequences, next steps, and an optional recommendation. While an escalation is unresolved, the workflow is paused in `escalation-decision` and the owner must decide how to proceed.
+Examples:
+- conflict between the approved spec and the repository.
+- behavior that the spec does not define.
+- a material architectural alternative.
+- a possible scope change.
+- a decision that affects verification or reversibility.
+
+Each escalation presents a question, context and evidence, available options, consequences, next steps, and an optional recommendation. 
+
+While an escalation is unresolved, the workflow is paused in `escalation-decision` and the owner must decide how to proceed.
 
 The owner can choose one of two paths:
 
-- Continue with the current contract. Maestro records the decision and returns the workflow to `ready-for-builder` for another builder run.
-- Change the approved contract. The owner revises and approves `spec.md`, then calls `maestro_mark_spec_ready`. The workflow returns to `ready-for-builder` on the same branch and with the same `specId`.
+- Continue with the current spec. Maestro records the decision and returns the workflow to `ready-for-builder` for another builder run.
+- Change the approved spec. The owner revises and approves the spec, then the workflow returns to `ready-for-builder`.
 
 Each escalation remains in the workflow history as references.
 
@@ -214,26 +193,29 @@ A finding records a technical issue found by the verifier. Every finding blocks
 | Decision | Result |
 |---|---|
 | `reject` | Requires and records the owner’s reason. When every finding is rejected, the candidate becomes ready. |
-| `fix-code` | Keeps the current spec and starts another builder run. |
-| Spec must change | The owner revises `spec.md` from `findings-decision`; previous findings become historical. |
+| `fix-code` | Keeps the current spec and returns the workflow to `ready-for-builder`. |
+| Spec must change | The owner revises the spec from `findings-decision`; previous findings become historical. |
 
-When decisions are mixed, any `fix-code` decision starts another builder run. If the approved contract must change, the owner uses the same spec revision flow instead of resolving obsolete findings.
+When decisions are mixed between `reject` and `fix-code`, any `fix-code` decision returns the workflow to `ready-for-builder`.
 
-## Completion and Pull Request
+If a finding requires a spec change, thw owner must approve a revised spec and run the builder again.
 
-The workflow ends at `candidate-ready` after a verifier run with no findings, or after the owner rejects every finding with a reason.
+## Spec revision
 
-The operations that produce this phase, `maestro_record_verifier_handoff` and `maestro_resolve_findings`, own the required checks:
+A spec revision is allowed only from these blocked phases:
 
-1. Before writing the transition, they make sure that the resulting handoff matches the spec identity and workflow revision, with no active findings.
-2. They reject changes outside the expected protocol files. The verifier must also restore the product to the verified candidate.
-3. They commit only the expected protocol files and return success only when the checkout is clean.
+- `escalation-decision`
+- `findings-decision`
 
-No final tool call or checkpoint is needed. `candidate-ready` is the last persisted Maestro phase.
+The owner edits and approves the spec, then Maestro changes the phase to `ready-for-builder`.
 
-Maestro reads the artifacts and Git information to summarize the changes, verification results, rejected findings and reasons, and applicable builder notes. The summary includes the current branch and final `HEAD`. Rejected findings are owner decisions, not proof that verification passed.
+The previous escalation or finding becomes inactive. Its artifact remains in the branch as historical context. Builder and verifier decide whether historical artifacts apply to the current spec.
+
+## Workflow completion
+
+The workflow ends at `candidate-ready` after a verifier run with no findings, or after the owner rejects every finding with a reason.
 
-The summary does not change files or workflow state, create commits, or run verification again. The owner controls the Git flow, review, Pull Request, and merge. Maestro does not squash, stage, merge, create, or remove branches. It does not create worktrees.
+Maestro reads the artifacts and Git information to summarize the changes, verification results, rejected findings and reasons, and applicable builder notes.
 
 ## Stored artifacts
 
@@ -255,6 +237,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. 
-- Escalations remain in the history directory. 
+- Builder handoff `notes` contain curated significant discoveries that did not require an owner decision; Maestro surfaces the applicable notes in the final workflow summary.
 - Earlier versions of all artifacts remain in Git commits.

package/extensions/maestro.ts

@@ -12,14 +12,6 @@ import {
   CREATE_SPEC_TOOL,
   registerCreateSpecTool,
 } from '#tools/main/create-spec.ts';
-import {
-  LAUNCH_BUILDER_TOOL,
-  registerLaunchBuilderTool,
-} from '#tools/main/launch-builder.ts';
-import {
-  LAUNCH_VERIFIER_TOOL,
-  registerLaunchVerifierTool,
-} from '#tools/main/launch-verifier.ts';
 import {
   MARK_SPEC_READY_TOOL,
   registerMarkSpecReadyTool,
@@ -32,22 +24,30 @@ import {
   RESOLVE_FINDINGS_TOOL,
   registerResolveFindingsTool,
 } from '#tools/main/resolve-findings.ts';
+import {
+  RUN_BUILDER_TOOL,
+  registerRunBuilderTool,
+} from '#tools/main/run-builder.ts';
+import {
+  RUN_VERIFIER_TOOL,
+  registerRunVerifierTool,
+} from '#tools/main/run-verifier.ts';
 
 const MAIN_TOOL_NAMES: readonly string[] = [
   CREATE_SPEC_TOOL.NAME,
   MARK_SPEC_READY_TOOL.NAME,
-  LAUNCH_BUILDER_TOOL.NAME,
+  RUN_BUILDER_TOOL.NAME,
   RESOLVE_ESCALATION_TOOL.NAME,
-  LAUNCH_VERIFIER_TOOL.NAME,
+  RUN_VERIFIER_TOOL.NAME,
   RESOLVE_FINDINGS_TOOL.NAME,
 ];
 
 export default (pi: ExtensionAPI): void => {
   registerCreateSpecTool(pi);
   registerMarkSpecReadyTool(pi);
-  registerLaunchBuilderTool(pi);
+  registerRunBuilderTool(pi);
   registerResolveEscalationTool(pi);
-  registerLaunchVerifierTool(pi);
+  registerRunVerifierTool(pi);
   registerResolveFindingsTool(pi);
 
   const syncMainTools = (): void => {

package/package.json

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

package/src/config/loadConfiguration.ts

@@ -3,15 +3,13 @@
  * Used: When Maestro initializes for a repository.
  */
 
-import { lstat, readFile, realpath } from 'node:fs/promises';
-import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { readFile, realpath } from 'node:fs/promises';
+import { isAbsolute, join, resolve } from 'node:path';
 import { assertConfiguration } from '#config/assertConfiguration.ts';
 import { CONFIG_FILE_PATH, DEFAULT_CONFIG } from '#config/defaults.ts';
 import type { MaestroConfig, PartialMaestroConfig } from '#config/schema.ts';
-import { isErrnoException } from '#utils/is-errno-exception.ts';
 import { pathExists } from '#utils/path-exists.ts';
 import { isPathStrictlyWithin } from '#utils/path-strictly-within.ts';
-import { isPathWithinOrEqual } from '#utils/path-within-or-equal.ts';
 
 const resolveConfiguration = (input: PartialMaestroConfig): MaestroConfig => {
   const resolved: MaestroConfig = {
@@ -35,43 +33,6 @@ const resolveConfiguration = (input: PartialMaestroConfig): MaestroConfig => {
   return resolved;
 };
 
-type ExistingAncestor = {
-  path: string;
-  realPath: string;
-};
-
-const findExistingAncestor = async (
-  path: string,
-): Promise<ExistingAncestor> => {
-  let anchestor = path;
-
-  while (true) {
-    try {
-      // lstat instead of access, because access follows symlinks
-      await lstat(anchestor);
-    } catch (error) {
-      if (!isErrnoException(error) || error.code !== 'ENOENT') {
-        throw error;
-      }
-
-      const parent = dirname(anchestor);
-
-      if (parent === anchestor) {
-        throw new Error(`Cannot resolve an existing ancestor for "${path}".`);
-      }
-
-      anchestor = parent;
-      continue;
-    }
-
-    try {
-      return { path: anchestor, realPath: await realpath(anchestor) };
-    } catch {
-      throw new Error(`Cannot resolve symlink "${anchestor}".`);
-    }
-  }
-};
-
 type AssertSafeDirectoryInput = {
   value: string;
   name: string;
@@ -96,11 +57,11 @@ type ResolveSafeDirectoryInput = {
   name: string;
 };
 
-const resolveSafeDirectory = async ({
+const resolveSafeDirectory = ({
   repositoryRoot,
   directory,
   name,
-}: ResolveSafeDirectoryInput): Promise<string> => {
+}: ResolveSafeDirectoryInput): string => {
   assertSafeDirectoryInput({ value: directory, name });
 
   const requestedDirectory = resolve(repositoryRoot, directory);
@@ -118,31 +79,7 @@ const resolveSafeDirectory = async ({
     throw new Error(`${name} must stay inside the Git root.`);
   }
 
-  // The directory could not exist at the check time. We find the existing anchestor and do the check on that.
-  const ancestor = await findExistingAncestor(requestedDirectory);
-
-  if (
-    !isPathWithinOrEqual({
-      parent: repositoryRoot,
-      candidate: ancestor.realPath,
-    })
-  ) {
-    throw new Error(`${name} resolves outside the Git root through a symlink.`);
-  }
-
-  const unresolvedSuffix = relative(ancestor.path, requestedDirectory);
-  const resolvedDirectory = resolve(ancestor.realPath, unresolvedSuffix);
-
-  if (
-    !isPathStrictlyWithin({
-      parent: repositoryRoot,
-      candidate: resolvedDirectory,
-    })
-  ) {
-    throw new Error(`${name} resolves outside the Git root through a symlink.`);
-  }
-
-  return resolvedDirectory;
+  return requestedDirectory;
 };
 
 type ResolveDirectoriesInput = {
@@ -150,13 +87,11 @@ type ResolveDirectoriesInput = {
   config: MaestroConfig;
 };
 
-const resolveDirectories = async ({
-  repositoryRoot: configuredRepositoryRoot,
+const resolveDirectories = ({
+  repositoryRoot,
   config,
-}: ResolveDirectoriesInput): Promise<MaestroConfig> => {
-  const repositoryRoot = await realpath(configuredRepositoryRoot);
-
-  const specDirectory = await resolveSafeDirectory({
+}: ResolveDirectoriesInput): MaestroConfig => {
+  const specDirectory = resolveSafeDirectory({
     repositoryRoot,
     directory: config.specDirectory,
     name: 'specDirectory',
@@ -186,7 +121,7 @@ export const loadConfiguration = async (
   const targetPath = join(repositoryRoot, CONFIG_FILE_PATH);
 
   if (!(await pathExists(targetPath))) {
-    return await resolveDirectories({ repositoryRoot, config: DEFAULT_CONFIG });
+    return resolveDirectories({ repositoryRoot, config: DEFAULT_CONFIG });
   }
 
   const parsed = await readConfigurationFile(targetPath);
@@ -194,5 +129,5 @@ export const loadConfiguration = async (
   assertConfiguration(parsed);
   const config = resolveConfiguration(parsed);
 
-  return await resolveDirectories({ repositoryRoot, config });
+  return resolveDirectories({ repositoryRoot, config });
 };

package/src/maestro/instructions/getMaestroInstructions.ts

@@ -15,11 +15,11 @@ A builder escalation is an owner decision checkpoint, not only a technical failu
 
 If the approved contract must change from escalation-decision or findings-decision, the owner revises and approves the same specId, then calls maestro_mark_spec_ready. If a builder reports failed for a technical reason, Maestro reports the error and stops the workflow. The owner is responsible for the follow-up; there is no retry or spec revision from builder-failed.
 
-Use the deterministic maestro_* tools for workflow mutations, Git operations, artifact changes, and agent launches. Do not perform these mutations through generic tools.
+Use the deterministic maestro_* tools for workflow mutations, Git operations, artifact changes, and agent runs. Do not perform these mutations through generic tools.
 
 While Maestro mode is active, use generic tools to inspect and discuss the repository, but do not edit normal product files. Builder and verifier work through their dedicated handoff tools and do not communicate with the owner directly. Do not treat their conclusions as owner decisions.
 
-The verifier uses the parent of the verifier-running checkpoint as its candidate and must restore product changes before its handoff. The verifier handoff tool owns the protocol commit. The verifier handoff and finding resolution operations own the checks required to reach candidate-ready.
+The verifier uses the verifier-running checkpoint itself as its fixed candidate and must restore product changes before its handoff. The verifier handoff tool owns the protocol commit. The verifier handoff and finding resolution operations own the checks required to reach candidate-ready.
 
 The workflow ends at candidate-ready. No final tool call, checkpoint, or owner commit is required. You own the final summary. Use inspection tools to read the existing artifacts and Git information. Summarize the changes, verification results, rejected findings with their reasons, and applicable builder notes. Include the current branch and final HEAD after the protocol commit as the Pull Request facts. Do not present owner rejections as passed verification.