@emiliosp/pi-maestro 0.11.0 → 0.13.0

package/src/workflow/spec/markSpecReady.ts

@@ -4,6 +4,7 @@
  */
 
 import { readFile } from 'node:fs/promises';
+
 import type { MaestroPaths } from '#MaestroPaths.ts';
 import { pathExists } from '#utils/path-exists.ts';
 import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
@@ -12,7 +13,8 @@ import { writeWorkflowState } from '#workflow/state/writeWorkflowState.ts';
 import { transitionWorkflow } from '#workflow/transitions.ts';
 
 function assertAcceptanceCriterionOrdering(markdown: string): void {
-  const criteria = [...markdown.matchAll(/^### AC(\d+):/gm)];
+  // Match standalone ACs (###), including regression checks, and ACs nested under requirements (####).
+  const criteria = [...markdown.matchAll(/^#{3,4} AC(\d+):/gm)];
 
   if (criteria.some((match, index) => Number(match[1]) !== index + 1)) {
     throw new Error('Fix acceptance criterion ordering in spec.md.');
@@ -46,13 +48,17 @@ export const markSpecReady = async ({
     throw new Error(`Spec file is missing: ${specFilePath}.`);
   }
 
+  const proposalFilePath = paths.getProposalFilePath(specId);
+
+  if (!(await pathExists(proposalFilePath))) {
+    throw new Error(`Proposal file is missing: ${proposalFilePath}.`);
+  }
+
   const workflowPath = paths.getWorkflowPath(specId);
   const current = await readWorkflowState(workflowPath);
 
   if (current.specId !== specId) {
-    throw new Error(
-      `Workflow spec ID mismatch: expected "${specId}", found "${current.specId}".`,
-    );
+    throw new Error(`Workflow spec ID mismatch: expected "${specId}", found "${current.specId}".`);
   }
 
   const state = transitionWorkflow({

package/src/workflow/state/readWorkflowState.ts

@@ -4,14 +4,9 @@
  */
 
 import { readJsonFile } from '#utils/read-json.ts';
-import {
-  assertWorkflowState,
-  type WorkflowState,
-} from '#workflow/state/schema.ts';
+import { assertWorkflowState, type WorkflowState } from '#workflow/state/schema.ts';
 
-export const readWorkflowState = async (
-  path: string,
-): Promise<WorkflowState> => {
+export const readWorkflowState = async (path: string): Promise<WorkflowState> => {
   const state = await readJsonFile({ path, description: 'Workflow state' });
   assertWorkflowState(state);
 

package/src/workflow/state/schema.ts

@@ -5,6 +5,7 @@
 
 import { type Static, Type } from 'typebox';
 import { Value } from 'typebox/value';
+
 import { isValidSpecId, SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
 
 export const WORKFLOW_STATE_VERSION = '1.0.0';
@@ -58,17 +59,13 @@ export const WorkflowStateSchema = Type.Object(
   { additionalProperties: false },
 );
 
-export type WorkflowPhase =
-  (typeof WORKFLOW_PHASES)[keyof typeof WORKFLOW_PHASES];
+export type WorkflowPhase = (typeof WORKFLOW_PHASES)[keyof typeof WORKFLOW_PHASES];
 
-export type WorkflowEvent =
-  (typeof WORKFLOW_EVENTS)[keyof typeof WORKFLOW_EVENTS];
+export type WorkflowEvent = (typeof WORKFLOW_EVENTS)[keyof typeof WORKFLOW_EVENTS];
 
 export type WorkflowState = Static<typeof WorkflowStateSchema>;
 
-function assertWorkflowStateSchema(
-  input: unknown,
-): asserts input is WorkflowState {
+function assertWorkflowStateSchema(input: unknown): asserts input is WorkflowState {
   if (typeof input !== 'object' || input === null || Array.isArray(input)) {
     throw new Error('Workflow state must be a JSON object.');
   }
@@ -80,9 +77,7 @@ function assertWorkflowStateSchema(
   }
 }
 
-export function assertWorkflowState(
-  input: unknown,
-): asserts input is WorkflowState {
+export function assertWorkflowState(input: unknown): asserts input is WorkflowState {
   assertWorkflowStateSchema(input);
 
   if (!isValidSpecId(input.specId)) {

package/src/workflow/state/writeWorkflowState.ts

@@ -4,10 +4,7 @@
  */
 
 import { writeJson } from '#utils/write-json.ts';
-import {
-  assertWorkflowState,
-  type WorkflowState,
-} from '#workflow/state/schema.ts';
+import { assertWorkflowState, type WorkflowState } from '#workflow/state/schema.ts';
 
 type WriteWorkflowStateInput = {
   path: string;

package/src/workflow/transitions.ts

@@ -35,10 +35,7 @@ export const WORKFLOW_TRANSITIONS: Record<WorkflowEvent, WorkflowTransition> = {
     to: WORKFLOW_PHASES.READY_FOR_BUILDER,
   },
   [WORKFLOW_EVENTS.OWNER_REQUEST_SPEC_REVISION]: {
-    from: [
-      WORKFLOW_PHASES.ESCALATION_DECISIONS,
-      WORKFLOW_PHASES.FINDING_DECISIONS,
-    ],
+    from: [WORKFLOW_PHASES.ESCALATION_DECISIONS, WORKFLOW_PHASES.FINDING_DECISIONS],
     to: WORKFLOW_PHASES.DRAFTING_SPEC,
   },
   [WORKFLOW_EVENTS.BUILDER_DONE]: {
@@ -80,10 +77,7 @@ type TransitionWorkflowInput = {
   event: WorkflowEvent;
 };
 
-export const transitionWorkflow = ({
-  state,
-  event,
-}: TransitionWorkflowInput): WorkflowState => {
+export const transitionWorkflow = ({ state, event }: TransitionWorkflowInput): WorkflowState => {
   assertWorkflowState(state);
   const transition = WORKFLOW_TRANSITIONS[event];
 
@@ -92,9 +86,7 @@ export const transitionWorkflow = ({
   }
 
   if (!transition.from.includes(state.phase)) {
-    throw new Error(
-      `Workflow event "${event}" is not allowed from phase "${state.phase}".`,
-    );
+    throw new Error(`Workflow event "${event}" is not allowed from phase "${state.phase}".`);
   }
 
   return {

package/src/workflow/utils/assertSpecAcceptanceCriteria.ts

@@ -12,7 +12,8 @@ export function assertSpecAcceptanceCriteria({
   markdown,
   criterionIds,
 }: AssertSpecAcceptanceCriteriaInput): void {
-  const missingIds = [...markdown.matchAll(/^### AC(\d+):/gm)]
+  // Match standalone ACs (###), including regression checks, and ACs nested under requirements (####).
+  const missingIds = [...markdown.matchAll(/^#{3,4} AC(\d+):/gm)]
     .map((match) => `AC${match[1]}`)
     .filter((id) => !criterionIds.has(id));
 

package/src/workflow/utils/getAgentRole.ts

@@ -18,9 +18,7 @@ const VERIFIER_PHASES: readonly WorkflowState['phase'][] = [
   WORKFLOW_PHASES.FINDING_DECISIONS,
 ];
 
-export const getAgentRole = (
-  phase: WorkflowState['phase'],
-): WorkflowRole | null => {
+export const getAgentRole = (phase: WorkflowState['phase']): WorkflowRole | null => {
   if (BUILDER_PHASES.includes(phase)) {
     return WORKFLOW_ROLES.BUILDER;
   }

package/src/workflow/verifier/completeVerifierPass.ts

@@ -4,6 +4,7 @@
  */
 
 import { mkdir, readFile } from 'node:fs/promises';
+
 import { assertVerifierHandoff } from '#artifacts/verifier-handoff/assertVerifierHandoff.ts';
 import type { VerifierHandoff } from '#artifacts/verifier-handoff/schema.ts';
 import { writeVerifierHandoff } from '#artifacts/verifier-handoff/writeVerifierHandoff.ts';

package/src/workflow/verifier/resolveFindings.ts

@@ -5,10 +5,7 @@
 
 import { assertVerifierHandoff } from '#artifacts/verifier-handoff/assertVerifierHandoff.ts';
 import { readVerifierHandoff } from '#artifacts/verifier-handoff/readVerifierHandoff.ts';
-import type {
-  VerifierFinding,
-  VerifierHandoff,
-} from '#artifacts/verifier-handoff/schema.ts';
+import type { VerifierFinding, VerifierHandoff } from '#artifacts/verifier-handoff/schema.ts';
 import { FINDING_DECISIONS } from '#artifacts/verifier-handoff/schema.ts';
 import type { MaestroPaths } from '#MaestroPaths.ts';
 import { writeJson } from '#utils/write-json.ts';
@@ -48,20 +45,13 @@ const applyFindingDecisions = ({
     }
 
     if (decisionsById.has(decision.findingId)) {
-      throw new Error(
-        `Duplicate decision for finding "${decision.findingId}".`,
-      );
+      throw new Error(`Duplicate decision for finding "${decision.findingId}".`);
     }
 
     decisionsById.set(decision.findingId, decision);
 
-    if (
-      decision.decision === FINDING_DECISIONS.REJECT &&
-      decision.reason.trim().length === 0
-    ) {
-      throw new Error(
-        `Rejection reason for "${decision.findingId}" must not be empty.`,
-      );
+    if (decision.decision === FINDING_DECISIONS.REJECT && decision.reason.trim().length === 0) {
+      throw new Error(`Rejection reason for "${decision.findingId}" must not be empty.`);
     }
   }
 
@@ -94,15 +84,11 @@ const readFindingWorkflow = async ({
   const state = await readWorkflowState(paths.getWorkflowPath(specId));
 
   if (state.specId !== specId) {
-    throw new Error(
-      `Workflow spec ID mismatch: expected "${specId}", found "${state.specId}".`,
-    );
+    throw new Error(`Workflow spec ID mismatch: expected "${specId}", found "${state.specId}".`);
   }
 
   if (state.phase !== WORKFLOW_PHASES.FINDING_DECISIONS) {
-    throw new Error(
-      `Finding resolution requires finding-decisions state, found "${state.phase}".`,
-    );
+    throw new Error(`Finding resolution requires finding-decisions state, found "${state.phase}".`);
   }
 
   const handoff = await readVerifierHandoff({
@@ -111,23 +97,17 @@ const readFindingWorkflow = async ({
   });
 
   if (handoff.findings.length === 0) {
-    throw new Error(
-      'Finding resolution requires at least one current finding.',
-    );
+    throw new Error('Finding resolution requires at least one current finding.');
   }
 
   if (handoff.findings.some(({ decision }) => decision !== null)) {
-    throw new Error(
-      'Current verifier findings already contain an owner decision.',
-    );
+    throw new Error('Current verifier findings already contain an owner decision.');
   }
 
   return { state, handoff };
 };
 
-const getSavedFindingDecision = (
-  decision: FindingDecision | undefined,
-): SavedFindingDecision => {
+const getSavedFindingDecision = (decision: FindingDecision | undefined): SavedFindingDecision => {
   if (decision?.decision === FINDING_DECISIONS.REVISE_SPEC) {
     return {
       decision: FINDING_DECISIONS.REVISE_SPEC,

package/src/workflow/verifier/utils/getWorkflowEventByVerifierHandoff.ts

@@ -3,15 +3,10 @@
  * Used: When a verifier completes a pass or the owner resolves its findings.
  */
 
-import {
-  FINDING_DECISIONS,
-  type VerifierHandoff,
-} from '#artifacts/verifier-handoff/schema.ts';
+import { FINDING_DECISIONS, type VerifierHandoff } from '#artifacts/verifier-handoff/schema.ts';
 import { WORKFLOW_EVENTS, type WorkflowEvent } from '#workflow/state/schema.ts';
 
-export const getWorkflowEventByVerifierHandoff = (
-  handoff: VerifierHandoff,
-): WorkflowEvent => {
+export const getWorkflowEventByVerifierHandoff = (handoff: VerifierHandoff): WorkflowEvent => {
   if (handoff.findings.length === 0) {
     return WORKFLOW_EVENTS.VERIFIER_DONE;
   }
@@ -21,26 +16,16 @@ export const getWorkflowEventByVerifierHandoff = (
   }
 
   if (
-    handoff.findings.some(
-      ({ decision }) => decision?.decision === FINDING_DECISIONS.REVISE_SPEC,
-    )
+    handoff.findings.some(({ decision }) => decision?.decision === FINDING_DECISIONS.REVISE_SPEC)
   ) {
     return WORKFLOW_EVENTS.OWNER_REQUEST_SPEC_REVISION;
   }
 
-  if (
-    handoff.findings.some(
-      ({ decision }) => decision?.decision === FINDING_DECISIONS.FIX_CODE,
-    )
-  ) {
+  if (handoff.findings.some(({ decision }) => decision?.decision === FINDING_DECISIONS.FIX_CODE)) {
     return WORKFLOW_EVENTS.OWNER_REQUEST_FIXES;
   }
 
-  if (
-    handoff.findings.every(
-      ({ decision }) => decision?.decision === FINDING_DECISIONS.REJECT,
-    )
-  ) {
+  if (handoff.findings.every(({ decision }) => decision?.decision === FINDING_DECISIONS.REJECT)) {
     return WORKFLOW_EVENTS.OWNER_REJECT_FINDINGS;
   }
 

package/templates/design.md

@@ -0,0 +1,20 @@
+# <id>: <short, outcome-oriented title>
+
+<!--
+Create this document only when significant technical decisions must be preserved.
+Record approved architectural decisions, important technical constraints, or prototype choices, not routine implementation details.
+Keep motivation and scope in proposal.md. Keep required behavior, edge cases, and acceptance criteria in spec.md.
+Use only the sections that matter. Omit empty sections and these instructions.
+-->
+
+## Decisions
+
+<Describe each approved technical decision and its brief reason. Include only alternatives actually considered and consequences that matter. Link related REQ IDs in spec.md instead of repeating requirements.>
+
+## Contracts and prototypes
+
+<Include interface or data contracts and links to prototypes only when needed to explain the approved design. Keep observable behavior in spec.md and distinguish illustrative prototype content from requirements.>
+
+## Risks and limits
+
+<Record relevant technical risks, migration or rollback constraints, and evidence supporting the decision. Do not add investigation logs. Resolve decisions affecting the contract with the owner before approval.>

package/templates/proposal.md

@@ -0,0 +1,23 @@
+# <id>: <short, outcome-oriented title>
+
+<!--
+Explain why this change exists and where its scope ends. Keep it brief and write for the owner.
+Keep detailed behavior and acceptance criteria in spec.md, and approved technical decisions in design.md when needed.
+Omit empty sections and these instructions. Do not duplicate requirements or investigation logs.
+-->
+
+## Problem
+
+<Describe the current problem, who is affected, and why the change is needed.>
+
+## Goal and scope
+
+<State the intended outcome and the boundaries of this one reversible change.>
+
+## Out of scope
+
+<Name related changes that are explicitly excluded.>
+
+## Required behavior
+
+See [spec.md](spec.md).

package/templates/spec.md

@@ -1,69 +1,40 @@
 # <id>: <short, outcome-oriented title>
 
-> After owner approval, this specification is the contract for the builder and verifier.
-
 <!--
-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.
+Define required behavior, not motivation or implementation. See proposal.md for scope and design.md, when present, for approved technical decisions.
+Write for the owner. State each requirement once and keep its acceptance criteria immediately below it.
+Use the topics below as guidance. Omit empty subsections and these instructions.
+Leave test code, fixtures, mocks, and commands to the builder. Keep execution evidence in handoffs.
 -->
 
-## 1. Context, goals, and scope
-
-<Briefly describe the problem, who is affected, and the intended outcome.>
-
-### Out of scope
-
-<Name related changes that are explicitly excluded.>
-
-## 2. Requirements and constraints
+## Requirements
 
-<Describe required behavior and measurable limits. Include performance, reliability, accessibility, or other quality requirements only when relevant.>
+<Give each requirement its own ### REQ<number>: <title> heading and a unique, stable ID. Document only behavior or constraints this change adds, modifies, or removes, with relevant measurable limits, edge cases, and error handling. Existing behavior must continue working unless explicitly changed or removed; do not list unchanged behavior as requirements. Do not copy repository or agent instructions.>
 
-<Include non-negotiable boundaries and existing behavior that this change must preserve. Do not copy repository or agent instructions.>
+<Give each requirement exactly one Delta value: added, modified, or removed. Keep requirements organized by topic, not by delta category. For modified or removed requirements, add a brief Before description only when useful. Verify the previous behavior from repository evidence; do not invent it or repeat the whole old requirement. State the complete required outcome, including the required absence and any agreed replacement or error behavior for removals. Keep the same pre-change baseline during revisions.>
 
-### Edge cases and error handling
+<Each requirement must have Verified by with Markdown links to its acceptance criteria, using their actual heading anchors. When an existing test covers the exact starting conditions, action, and expected result, link its file relative to spec.md and give the exact scenario name instead of creating a duplicate criterion. Keep criteria for partial or uncertain coverage. A requirement can reference both criteria and tests; check their combined coverage.>
 
-<Describe boundary conditions, failures, and required recovery behavior not already covered above. Keep these requirements even when existing tests cover their scenarios.>
+<Write each requirement-associated AC once, immediately below its primary requirement, with a #### AC<number>: <title> heading. Other requirements can link to it without duplication. A relevant regression AC without an associated changed requirement can instead use a ### AC<number>: <title> heading under an optional ## Regression checks section, with the same probe, expected result, and example fields. Do not invent a REQ or Delta field for it. Include only regressions relevant to this change, not an inventory of existing behavior, and omit the section when unnecessary.>
 
-## 3. Technical decisions and prototypes
+<Number ACs continuously from AC1 across the whole document, including nested and standalone regression criteria. During review, remove criteria already covered exactly by existing tests and update numbering and affected links. Keep required behavior documented when a requirement-associated criterion is omitted; omitting a standalone regression criterion does not require creating a requirement.>
 
-<Record only approved architectural decisions or technical constraints that affect scope or behavior. Explain their reasons briefly. Leave routine implementation choices to the builder.>
+### REQ1: <short required behavior>
 
-<For each relevant topic below, add a short subsection. Omit topics that do not apply.>
+Delta: <added | modified | removed>
 
-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.
+<Describe the requirement once, including relevant boundary conditions and required failure or recovery behavior.>
 
-<Include only evidence and unresolved limits that affect an owner decision. Do not include investigation logs or general verification disclaimers.>
+Verified by: [AC1](#ac1-short-observable-claim)
 
-## 4. Acceptance criteria
+#### AC1: <short observable claim>
 
-<Inspect existing tests before writing criteria. Omit a criterion only if a test covers the same starting conditions, action, and expected result. Keep criteria when coverage is partial or uncertain. During review, remove criteria already covered by tests. Keep numbering continuous from AC1 and update affected references. Keep required behavior in section 2 even when its criterion is omitted.>
-
-<Give each criterion a unique ID, one observable claim, and one coverage label. A probe is the scenario used to check that claim. Describe it in plain language. Use success for a valid action that produces the required result. Use failure for an invalid action that is correctly rejected. Use unchanged when the criterion explicitly checks existing behavior that the change must preserve. The label describes the scenario, not the test outcome. A failure scenario passes when the invalid action is correctly rejected. Do not require all three categories.>
-
-### AC1: <short observable claim>
-
-1. Coverage: <success | failure | unchanged>
-2. Probe: <starting conditions and action or observation, without prescribing test implementation>
-3. Expected result: <observable and measurable outcome>
-4. Example: <specific starting conditions, concrete input or action, and exact expected result for this probe, not a restatement of the claim>
+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, not a restatement of the claim>
 
 <!--
-Example:
-Coverage: success
-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".
-
-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.
+Each AC has one observable claim, a probe, an expected result, and a concrete example.
+Describe relevant valid actions, invalid actions, and regressions directly through those fields, without a separate classification label.
+The builder and verifier each run every probe independently. The builder chooses executable checks; the verifier checks their coverage independently.
 -->