@emiliosp/pi-maestro 0.10.1 → 0.12.0

package/src/tools/utils/resolveToolRunContext.ts

@@ -4,6 +4,7 @@
  */
 
 import { realpath } from 'node:fs/promises';
+
 import { loadConfiguration } from '#config/loadConfiguration.ts';
 import type { MaestroConfig } from '#config/schema.ts';
 import { MaestroPaths } from '#MaestroPaths.ts';
@@ -14,9 +15,7 @@ export type ToolRunContext = {
   paths: MaestroPaths;
 };
 
-export const resolveToolRunContext = async (
-  cwd: string,
-): Promise<ToolRunContext> => {
+export const resolveToolRunContext = async (cwd: string): Promise<ToolRunContext> => {
   const projectRoot = await realpath(cwd);
   const config = await loadConfiguration(projectRoot);
 

package/src/utils/is-errno-exception.ts

@@ -3,7 +3,5 @@
  * Used: When filesystem operations handle specific error codes.
  */
 
-export const isErrnoException = (
-  error: unknown,
-): error is NodeJS.ErrnoException =>
+export const isErrnoException = (error: unknown): error is NodeJS.ErrnoException =>
   error instanceof Error && 'code' in error && typeof error.code === 'string';

package/src/utils/path-exists.ts

@@ -4,6 +4,7 @@
  */
 
 import { access } from 'node:fs/promises';
+
 import { isErrnoException } from '#utils/is-errno-exception.ts';
 
 export const pathExists = async (path: string): Promise<boolean> => {

package/src/utils/path-strictly-within.ts

@@ -4,6 +4,7 @@
  */
 
 import { relative } from 'node:path';
+
 import { isPathWithinOrEqual } from '#utils/path-within-or-equal.ts';
 
 type IsPathStrictlyWithinInput = {
@@ -11,9 +12,5 @@ type IsPathStrictlyWithinInput = {
   path: string;
 };
 
-export const isPathStrictlyWithin = ({
-  parent,
-  path,
-}: IsPathStrictlyWithinInput): boolean =>
-  relative(parent, path) !== '' &&
-  isPathWithinOrEqual({ parent, candidate: path });
+export const isPathStrictlyWithin = ({ parent, path }: IsPathStrictlyWithinInput): boolean =>
+  relative(parent, path) !== '' && isPathWithinOrEqual({ parent, candidate: path });

package/src/utils/path-within-or-equal.ts

@@ -10,10 +10,7 @@ type IsPathWithinOrEqualInput = {
   candidate: string;
 };
 
-export const isPathWithinOrEqual = ({
-  parent,
-  candidate,
-}: IsPathWithinOrEqualInput): boolean => {
+export const isPathWithinOrEqual = ({ parent, candidate }: IsPathWithinOrEqualInput): boolean => {
   const pathToCandidate = relative(parent, candidate);
 
   return (

package/src/utils/read-json.ts

@@ -10,10 +10,7 @@ type ReadJsonFileInput = {
   description: string;
 };
 
-export const readJsonFile = async ({
-  path,
-  description,
-}: ReadJsonFileInput): Promise<unknown> => {
+export const readJsonFile = async ({ path, description }: ReadJsonFileInput): Promise<unknown> => {
   const content = await readFile(path, 'utf8');
 
   try {

package/src/utils/write-json.ts

@@ -10,10 +10,7 @@ type WriteJsonInput = {
   data: unknown;
 };
 
-export const writeJson = async ({
-  path,
-  data,
-}: WriteJsonInput): Promise<void> => {
+export const writeJson = async ({ path, data }: WriteJsonInput): Promise<void> => {
   const content = JSON.stringify(data, null, 2);
 
   if (content === undefined) {

package/src/workflow/builder/completeBuilderPass.ts

@@ -4,7 +4,9 @@
  */
 
 import { mkdir, readFile } from 'node:fs/promises';
+
 import { Value } from 'typebox/value';
+
 import { assertBuilderHandoff } from '#artifacts/builder-handoff/assertBuilderHandoff.ts';
 import {
   BUILDER_HANDOFF_VERSION,
@@ -33,8 +35,7 @@ function assertBuilderHandoffSubmission(
 ): asserts input is BuilderHandoffSubmissionInput {
   const [error] = Value.Errors(BuilderHandoffSubmissionSchema, input);
 
-  if (error !== undefined)
-    throw new Error(`Invalid builder submission: ${error.message}.`);
+  if (error !== undefined) throw new Error(`Invalid builder submission: ${error.message}.`);
 }
 
 type CompleteBuilderPassInput = {

package/src/workflow/builder/prepareBuilderRun.ts

@@ -3,8 +3,8 @@
  * Used: Before Maestro runs a builder pass.
  */
 
-import type { MaestroPaths } from '#MaestroPaths.ts';
 import maestroSessionState from '#maestro/session/MaestroSessionState.ts';
+import type { MaestroPaths } from '#MaestroPaths.ts';
 import { pathExists } from '#utils/path-exists.ts';
 import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
 import { WORKFLOW_EVENTS, WORKFLOW_PHASES } from '#workflow/state/schema.ts';
@@ -21,16 +21,11 @@ type AssertBuilderRunBaseInput = {
   specId: string;
 };
 
-async function assertBuilderRunBase({
-  paths,
-  specId,
-}: AssertBuilderRunBaseInput): Promise<void> {
+async function assertBuilderRunBase({ paths, specId }: AssertBuilderRunBaseInput): Promise<void> {
   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.READY_FOR_BUILDER) {

package/src/workflow/builder/resolveEscalations.ts

@@ -26,16 +26,12 @@ type ApplyEscalationDecisionsInput = {
   decisions: EscalationDecision[];
 };
 
-const applyEscalationDecisions = ({
-  escalations,
-  decisions,
-}: ApplyEscalationDecisionsInput) => {
+const applyEscalationDecisions = ({ escalations, decisions }: ApplyEscalationDecisionsInput) => {
   if (escalations.some(({ resolution }) => resolution !== null)) {
     throw new Error('Current questions already contain an owner resolution.');
   }
 
-  if (decisions.length === 0)
-    throw new Error('At least one escalation decision is required.');
+  if (decisions.length === 0) throw new Error('At least one escalation decision is required.');
 
   const expectedIds = new Set(escalations.map(({ id }) => id));
   const resolutions = new Map<string, EscalationResolution>();

package/src/workflow/builder/utils/getWorkflowEventByBuilderHandoff.ts

@@ -9,9 +9,7 @@ import {
 } from '#artifacts/builder-handoff/schema.ts';
 import { WORKFLOW_EVENTS, type WorkflowEvent } from '#workflow/state/schema.ts';
 
-export const getWorkflowEventByBuilderHandoff = ({
-  status,
-}: BuilderHandoff): WorkflowEvent => {
+export const getWorkflowEventByBuilderHandoff = ({ status }: BuilderHandoff): WorkflowEvent => {
   if (status === BUILDER_HANDOFF_STATUSES.DONE) {
     return WORKFLOW_EVENTS.BUILDER_DONE;
   }

package/src/workflow/roles.ts

@@ -1,11 +1,12 @@
 /**
  * Objective: Define the roles used by the Maestro workflow.
- * Used: When workflow code identifies builder and verifier responsibilities.
+ * Used: When workflow code identifies agent responsibilities.
  */
 
 export const WORKFLOW_ROLES = {
   BUILDER: 'builder',
   VERIFIER: 'verifier',
+  SIMPLIFIER: 'simplifier',
 } as const;
 
 export type WorkflowRole = (typeof WORKFLOW_ROLES)[keyof typeof WORKFLOW_ROLES];

package/src/workflow/simplifier/completeSimplifierPass.ts

@@ -0,0 +1,56 @@
+/**
+ * Objective: Save a validated simplifier handoff before completing the workflow.
+ * Used: When the simplifier records its single result.
+ */
+
+import { mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+import { assertSimplifierHandoff } from '#artifacts/simplifier-handoff/assertSimplifierHandoff.ts';
+import type { MaestroPaths } from '#MaestroPaths.ts';
+import { writeJson } from '#utils/write-json.ts';
+import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
+import { WORKFLOW_EVENTS, WORKFLOW_PHASES } from '#workflow/state/schema.ts';
+import { writeWorkflowState } from '#workflow/state/writeWorkflowState.ts';
+import { transitionWorkflow } from '#workflow/transitions.ts';
+
+type CompleteSimplifierPassInput = {
+  paths: MaestroPaths;
+  specId: string;
+  handoff: unknown;
+};
+
+export const completeSimplifierPass = async ({
+  paths,
+  specId,
+  handoff,
+}: CompleteSimplifierPassInput) => {
+  const workflowPath = paths.getWorkflowPath(specId);
+  const state = await readWorkflowState(workflowPath);
+
+  if (state.specId !== specId) {
+    throw new Error(`Workflow spec ID mismatch: expected "${specId}", found "${state.specId}".`);
+  }
+
+  if (state.phase !== WORKFLOW_PHASES.SIMPLIFIER_RUNNING) {
+    throw new Error(
+      `Simplifier handoff requires simplifier-running state, found "${state.phase}".`,
+    );
+  }
+
+  const input = { handoff, specId, projectRoot: paths.getProjectRoot() };
+  assertSimplifierHandoff(input);
+
+  const handoffPath = paths.getSimplifierHandoffPath(specId);
+  await mkdir(dirname(handoffPath), { recursive: true });
+  await writeJson({ path: handoffPath, data: input.handoff });
+
+  const nextState = transitionWorkflow({
+    state,
+    event: WORKFLOW_EVENTS.SIMPLIFIER_DONE,
+  });
+
+  await writeWorkflowState({ path: workflowPath, state: nextState });
+
+  return { handoff: input.handoff, handoffPath, state: nextState };
+};

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';
@@ -17,6 +18,7 @@ export const WORKFLOW_PHASES = {
   READY_FOR_VERIFIER: 'ready-for-verifier',
   VERIFIER_RUNNING: 'verifier-running',
   FINDING_DECISIONS: 'finding-decisions',
+  SIMPLIFIER_RUNNING: 'simplifier-running',
   CANDIDATE_READY: 'candidate-ready',
 } as const;
 
@@ -30,6 +32,8 @@ export const WORKFLOW_EVENTS = {
   RUN_VERIFIER: 'run-verifier',
   VERIFIER_FOUND_FINDINGS: 'verifier-found-findings',
   VERIFIER_DONE: 'verifier-done',
+  SIMPLIFIER_DONE: 'simplifier-done',
+  SIMPLIFIER_SKIPPED: 'simplifier-skipped',
   OWNER_REJECT_FINDINGS: 'owner-reject-findings',
   OWNER_REQUEST_FIXES: 'owner-request-fixes',
 } as const;
@@ -42,6 +46,7 @@ export const WorkflowPhaseSchema = Type.Union([
   Type.Literal(WORKFLOW_PHASES.READY_FOR_VERIFIER),
   Type.Literal(WORKFLOW_PHASES.VERIFIER_RUNNING),
   Type.Literal(WORKFLOW_PHASES.FINDING_DECISIONS),
+  Type.Literal(WORKFLOW_PHASES.SIMPLIFIER_RUNNING),
   Type.Literal(WORKFLOW_PHASES.CANDIDATE_READY),
 ]);
 
@@ -54,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.');
   }
@@ -76,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]: {
@@ -55,10 +52,18 @@ export const WORKFLOW_TRANSITIONS: Record<WorkflowEvent, WorkflowTransition> = {
   },
   [WORKFLOW_EVENTS.VERIFIER_DONE]: {
     from: [WORKFLOW_PHASES.VERIFIER_RUNNING],
-    to: WORKFLOW_PHASES.CANDIDATE_READY,
+    to: WORKFLOW_PHASES.SIMPLIFIER_RUNNING,
   },
   [WORKFLOW_EVENTS.OWNER_REJECT_FINDINGS]: {
     from: [WORKFLOW_PHASES.FINDING_DECISIONS],
+    to: WORKFLOW_PHASES.SIMPLIFIER_RUNNING,
+  },
+  [WORKFLOW_EVENTS.SIMPLIFIER_DONE]: {
+    from: [WORKFLOW_PHASES.SIMPLIFIER_RUNNING],
+    to: WORKFLOW_PHASES.CANDIDATE_READY,
+  },
+  [WORKFLOW_EVENTS.SIMPLIFIER_SKIPPED]: {
+    from: [WORKFLOW_PHASES.SIMPLIFIER_RUNNING],
     to: WORKFLOW_PHASES.CANDIDATE_READY,
   },
   [WORKFLOW_EVENTS.OWNER_REQUEST_FIXES]: {
@@ -72,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];
 
@@ -84,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

@@ -1,6 +1,6 @@
 /**
  * Objective: Resolve the agent responsible for a workflow phase.
- * Used: When workflow logic maps persisted phases to builder or verifier roles.
+ * Used: When workflow logic maps persisted phases to agent roles.
  */
 
 import type { WorkflowRole } from '#workflow/roles.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;
   }
@@ -29,5 +27,9 @@ export const getAgentRole = (
     return WORKFLOW_ROLES.VERIFIER;
   }
 
+  if (phase === WORKFLOW_PHASES.SIMPLIFIER_RUNNING) {
+    return WORKFLOW_ROLES.SIMPLIFIER;
+  }
+
   return null;
 };

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).