create-byan-agent 2.19.2 → 2.20.0

package/install/templates/.claude/workflows/testarch-atdd.js

@@ -0,0 +1,287 @@
+export const meta = {
+  name: 'testarch-atdd',
+  description: 'Native port of the BYAN testarch-atdd workflow (create mode): generate FAILING acceptance tests before implementation (TDD red phase). Preflight+context, generation mode, test strategy, parallel API+E2E failing-test generation, aggregate+verify red-phase compliance, then return a structured verdict for the orchestrating skill to present at the human gate.',
+  phases: [
+    { title: 'PREFLIGHT', detail: 'verify prerequisites and load story, framework, and knowledge base' },
+    { title: 'MODE', detail: 'choose AI generation vs recording mode' },
+    { title: 'STRATEGY', detail: 'map acceptance criteria to test levels and P0-P3 priorities' },
+    { title: 'GENERATE', detail: 'parallel fan-out: FAILING API tests and FAILING E2E tests (red phase)' },
+    { title: 'AGGREGATE', detail: 'aggregate subprocess outputs, verify TDD red-phase compliance, build infra + checklist' },
+    { title: 'VALIDATE', detail: 'validate against checklist and return a completion verdict' },
+  ],
+}
+
+// ---------------------------------------------------------------------------
+// FD / STRICT STATE CONTRACT  (re-asserted inline — enforcement-bridge).
+//
+// The in-CLI Workflow tool runs this script OUTSIDE the conversation turn, so
+// BYAN's main-thread hooks (fd-phase-guard, strict-scope-guard, strict-stop-
+// guard, mantra-validate) DO NOT fire here. This script therefore:
+//   - NEVER imports/requires _byan/.../lib/fd-state.js and NEVER writes
+//     fd-state.json directly  (enforced by byan-lint-workflows.js).
+//   - uses NO wall-clock and NO randomness primitive (wall-clock / wall-clock /
+//     RNG break resume); any timestamp/id arrives via `args`.
+//   - returns DATA only. The orchestrating skill is the human-gated conductor;
+//     IT records FD/strict state via the byan_fd_* / byan_strict_* MCP tools
+//     AT the gate. The ATDD test files + checklist on disk are the workflow's
+//     product (written by the generate/aggregate leaves), not platform state.
+// ---------------------------------------------------------------------------
+
+// Mirrors source step-04 "Prepare Subprocess Inputs": the source builds a
+// timestamp via `an injected timestamp` for /tmp file naming. The sandbox
+// forbids wall-clock, so the id is passed in via args (orchestrator-supplied)
+// with a deterministic fallback. This keeps temp-file naming reproducible.
+const story = (args && args.story) || 'next approved story with clear acceptance criteria'
+const runId = (args && args.runId) || 'atdd-run'
+
+// Source step-04c "Verify TDD Red Phase Compliance": every generated test MUST
+// carry test.skip(), assert EXPECTED behavior (no expect(true).toBe(true)
+// placeholders), and be flagged expected_to_fail. This schema turns that prose
+// gate into a structured, validated subprocess contract.
+const GEN_SCHEMA = {
+  type: 'object',
+  required: ['success', 'tdd_phase', 'tests', 'test_count'],
+  properties: {
+    success: { type: 'boolean' },
+    subprocess: { type: 'string' },
+    tdd_phase: { type: 'string', description: "must be 'RED' for ATDD" },
+    tests: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['file', 'uses_test_skip', 'expected_to_fail', 'placeholder_assertions'],
+        properties: {
+          file: { type: 'string' },
+          uses_test_skip: { type: 'boolean', description: 'true if every test in the file uses test.skip()' },
+          expected_to_fail: { type: 'boolean' },
+          placeholder_assertions: { type: 'boolean', description: 'true if any expect(true).toBe(true) placeholders exist (must be false)' },
+          acceptance_criteria_covered: { type: 'array', items: { type: 'string' } },
+        },
+      },
+    },
+    fixture_needs: { type: 'array', items: { type: 'string' } },
+    test_count: { type: 'integer' },
+    summary: { type: 'string' },
+  },
+}
+
+// Source step-04c red-phase gate, applied to a subprocess result object.
+function redPhaseCompliant(out) {
+  if (!out || out.success !== true) return false
+  if (out.tdd_phase !== 'RED') return false
+  const tests = (out && out.tests) || []
+  if (tests.length === 0) return false
+  return tests.every((t) => t && t.uses_test_skip === true && t.expected_to_fail === true && t.placeholder_assertions === false)
+}
+
+// === Step 1: Preflight & Context Loading (steps-c/step-01) ===
+phase('PREFLIGHT')
+const preflight = await agent(
+  `You are the Master Test Architect running the ATDD workflow (create mode), step 1 (preflight & context). ` +
+    `Read the real source step file _byan/workflow/simple/testarch/atdd/steps-c/step-01-preflight-and-context.md. ` +
+    `Target story: ${JSON.stringify(story)}.\n` +
+    `1) Verify HARD prerequisites: story approved with clear, testable acceptance criteria; a test framework is configured ` +
+    `(playwright.config.ts or cypress.config.ts); a dev environment is available. If any is missing, HALT: set proceed=false and list what is missing.\n` +
+    `2) Load story context: read the story markdown, extract acceptance criteria + constraints, identify affected components and integrations.\n` +
+    `3) Load framework + existing patterns: inspect the tests/ dir for fixtures/helpers; read TEA config flags tea_use_playwright_utils and tea_use_mcp_enhancements.\n` +
+    `4) Load knowledge-base fragments (data-factories, component-tdd, test-quality, test-healing-patterns, selector-resilience, timing-debugging; plus playwright-utils OR traditional fixture-architecture/network-first per the utils flag).\n` +
+    `Report a concise summary of loaded inputs.`,
+  {
+    label: 'preflight',
+    phase: 'PREFLIGHT',
+    schema: {
+      type: 'object',
+      required: ['proceed'],
+      properties: {
+        proceed: { type: 'boolean', description: 'false if any hard prerequisite is missing (HALT)' },
+        missing: { type: 'array', items: { type: 'string' } },
+        acceptance_criteria: { type: 'array', items: { type: 'string' } },
+        framework: { type: 'string', description: 'playwright | cypress | unknown' },
+        use_playwright_utils: { type: 'boolean' },
+        use_mcp_enhancements: { type: 'boolean' },
+        notes: { type: 'string' },
+      },
+    }
+  }
+)
+
+// Hard prerequisite gate (source step-01: "If any are missing: HALT").
+if (!preflight.proceed) {
+  return {
+    workflow: 'testarch-atdd',
+    story,
+    status: 'halted-prerequisites',
+    summary: 'Preflight HALT: hard prerequisites missing (acceptance criteria / framework / env).',
+    missing: (preflight && preflight.missing) || [],
+    steps: 1,
+    needsHumanGate: true,
+  }
+}
+
+// === Step 2: Generation Mode Selection (steps-c/step-02) ===
+phase('MODE')
+const mode = await agent(
+  `ATDD step 2 (generation mode). Read _byan/workflow/simple/testarch/atdd/steps-c/step-02-generation-mode.md. ` +
+    `Context: framework=${(preflight && preflight.framework) || 'unknown'}, use_mcp_enhancements=${Boolean(preflight && preflight.use_mcp_enhancements)}.\n` +
+    `Default to AI generation when acceptance criteria are clear and scenarios are standard (CRUD/auth/API/navigation). ` +
+    `Choose recording mode ONLY for complex UI (drag/drop, multi-step wizards) when tea_use_mcp_enhancements is true AND Playwright MCP tools are available. ` +
+    `State the chosen mode and why.`,
+  {
+    label: 'generation-mode',
+    phase: 'MODE',
+    schema: {
+      type: 'object',
+      required: ['mode'],
+      properties: {
+        mode: { type: 'string', description: 'ai-generation | recording' },
+        rationale: { type: 'string' },
+      },
+    }
+  }
+)
+
+// === Step 3: Test Strategy (steps-c/step-03) ===
+phase('STRATEGY')
+const strategy = await agent(
+  `ATDD step 3 (test strategy). Read _byan/workflow/simple/testarch/atdd/steps-c/step-03-test-strategy.md. ` +
+    `Acceptance criteria: ${JSON.stringify((preflight && preflight.acceptance_criteria) || [])}.\n` +
+    `1) Convert each acceptance criterion into test scenarios, including negative/edge cases where risk is high. ` +
+    `2) Select the best level per scenario: E2E for critical journeys, API for business logic/service contracts, Component for UI behavior; avoid duplicate coverage across levels. ` +
+    `3) Assign P0-P3 priorities by risk + business impact. ` +
+    `4) Confirm every test is designed to FAIL before implementation (TDD red phase). ` +
+    `Output the prioritized scenario plan split into apiScenarios and e2eScenarios.`,
+  {
+    label: 'test-strategy',
+    phase: 'STRATEGY',
+    schema: {
+      type: 'object',
+      required: ['apiScenarios', 'e2eScenarios'],
+      properties: {
+        apiScenarios: { type: 'array', items: { type: 'string' } },
+        e2eScenarios: { type: 'array', items: { type: 'string' } },
+        redPhaseConfirmed: { type: 'boolean' },
+        notes: { type: 'string' },
+      },
+    }
+  }
+)
+
+// === Step 4: Orchestrate Parallel FAILING Test Generation (steps-c/step-04 + 04a + 04b) ===
+// Source mandates TWO subprocesses launched in PARALLEL and waits for BOTH:
+//   04a -> FAILING API tests, 04b -> FAILING E2E tests. This is a genuine
+//   fan-out over two independent generators, so parallel() mirrors it exactly.
+phase('GENERATE')
+const [apiOut, e2eOut] = await parallel([
+  () =>
+    agent(
+      `ATDD subprocess 4A (FAILING API tests, TDD RED phase). Read _byan/workflow/simple/testarch/atdd/steps-c/step-04a-subprocess-api-failing.md. ` +
+        `Temp output id: ${JSON.stringify(runId)}.\n` +
+        `From the API scenarios ${JSON.stringify((strategy && strategy.apiScenarios) || [])}, generate FAILING API test files under tests/api/. ` +
+        `Each test MUST use test.skip() (intentional red phase), assert EXPECTED request/response contracts + status codes + error cases (NO expect(true).toBe(true) placeholders), ` +
+        `use realistic data via factories, and carry priority tags [P0]-[P3]. Track fixture needs (do not build them yet). Do NOT generate E2E tests. Do NOT run tests.`,
+      { label: 'gen-api-red', phase: 'GENERATE', schema: GEN_SCHEMA }
+    ),
+  () =>
+    agent(
+      `ATDD subprocess 4B (FAILING E2E tests, TDD RED phase). Read _byan/workflow/simple/testarch/atdd/steps-c/step-04b-subprocess-e2e-failing.md. ` +
+        `Temp output id: ${JSON.stringify(runId)}.\n` +
+        `From the E2E scenarios ${JSON.stringify((strategy && strategy.e2eScenarios) || [])}, generate FAILING E2E test files under tests/e2e/. ` +
+        `Each test MUST use test.skip() (intentional red phase), assert EXPECTED UI behavior with resilient selectors (getByRole/getByText/getByLabel), follow network-first, use deterministic waits (no hard sleeps), ` +
+        `cover complete user journeys, and carry priority tags [P0]-[P3]. Track fixture needs (do not build them yet). Do NOT generate API tests. Do NOT run tests.`,
+      { label: 'gen-e2e-red', phase: 'GENERATE', schema: GEN_SCHEMA }
+    ),
+])
+
+// === Step 4C: Aggregate + verify TDD red-phase compliance (steps-c/step-04c) ===
+phase('AGGREGATE')
+// Source step-04c: if either subprocess failed OR red-phase compliance fails,
+// "report error and stop (don't proceed)". Surface the gap as a verdict; the
+// orchestrating skill decides at the human gate (gap is not a silent cut).
+const apiOk = redPhaseCompliant(apiOut)
+const e2eOk = redPhaseCompliant(e2eOut)
+log(`red-phase compliance: api=${apiOk} e2e=${e2eOk}`)
+
+if (!apiOk || !e2eOk) {
+  const blocking = []
+  if (!apiOk) blocking.push('API subprocess failed red-phase compliance (success/RED/test.skip/expected_to_fail/no-placeholder)')
+  if (!e2eOk) blocking.push('E2E subprocess failed red-phase compliance (success/RED/test.skip/expected_to_fail/no-placeholder)')
+  return {
+    workflow: 'testarch-atdd',
+    story,
+    status: 'red-phase-violation',
+    summary: 'Aggregation stopped: at least one subprocess did not produce compliant FAILING tests.',
+    blocking,
+    apiTestCount: (apiOut && apiOut.test_count) || 0,
+    e2eTestCount: (e2eOut && e2eOut.test_count) || 0,
+    steps: 5,
+    needsHumanGate: true,
+  }
+}
+
+const aggregate = await agent(
+  `ATDD step 4C (aggregate). Read _byan/workflow/simple/testarch/atdd/steps-c/step-04c-aggregate.md. ` +
+    `Both subprocesses are red-phase compliant. API result: ${JSON.stringify(apiOut)}. E2E result: ${JSON.stringify(e2eOut)}.\n` +
+    `1) Write all generated test files to disk (tests/api/*, tests/e2e/*) keeping every test.skip(). ` +
+    `2) Aggregate + dedupe fixture needs and create the minimal red-phase fixture infrastructure (e.g. tests/fixtures/test-data.ts). ` +
+    `3) Generate the ATDD checklist (story summary, AC coverage, RED-phase status, GREEN-phase next steps: remove test.skip() -> run -> verify pass, implementation guidance for endpoints + UI flows) and save it under the configured output folder as atdd-checklist-<story-id>.md. ` +
+    `Do NOT remove any test.skip() and do NOT run the tests yet. Report counts and written paths.`,
+  {
+    label: 'aggregate',
+    phase: 'AGGREGATE',
+    schema: {
+      type: 'object',
+      required: ['filesWritten', 'totalTests', 'checklistPath'],
+      properties: {
+        filesWritten: { type: 'array', items: { type: 'string' } },
+        totalTests: { type: 'integer' },
+        apiTests: { type: 'integer' },
+        e2eTests: { type: 'integer' },
+        fixturesCreated: { type: 'integer' },
+        checklistPath: { type: 'string' },
+        acceptanceCriteriaCovered: { type: 'array', items: { type: 'string' } },
+        notes: { type: 'string' },
+      },
+    }
+  }
+)
+
+// === Step 5: Validate & Complete (steps-c/step-05) ===
+phase('VALIDATE')
+const validation = await agent(
+  `ATDD step 5 (validate & complete). Read _byan/workflow/simple/testarch/atdd/steps-c/step-05-validate-and-complete.md and the workflow checklist.md. ` +
+    `Aggregation result: ${JSON.stringify(aggregate)}.\n` +
+    `Validate against the checklist: prerequisites satisfied; test files created correctly; checklist matches the acceptance criteria; every test is designed to FAIL before implementation (RED phase). ` +
+    `List any gaps that still need fixing. Then give a completion summary: test files created, checklist output path, key risks/assumptions, and the next recommended workflow (implementation, then 'automate' for the green phase).`,
+  {
+    label: 'validate-complete',
+    phase: 'VALIDATE',
+    schema: {
+      type: 'object',
+      required: ['valid'],
+      properties: {
+        valid: { type: 'boolean', description: 'true only if all checklist completion criteria are satisfied' },
+        gaps: { type: 'array', items: { type: 'string' } },
+        nextWorkflow: { type: 'string' },
+        summary: { type: 'string' },
+      },
+    }
+  }
+)
+
+// Return DATA only. The orchestrating skill presents this at the human gate
+// and records FD/strict state via MCP. No platform state is written here.
+return {
+  workflow: 'testarch-atdd',
+  story,
+  status: validation.valid ? 'red-phase-ready' : 'gaps-found',
+  mode: (mode && mode.mode) || 'ai-generation',
+  totalTests: (aggregate && aggregate.totalTests) || 0,
+  apiTests: (aggregate && aggregate.apiTests) || (apiOut && apiOut.test_count) || 0,
+  e2eTests: (aggregate && aggregate.e2eTests) || (e2eOut && e2eOut.test_count) || 0,
+  checklistPath: (aggregate && aggregate.checklistPath) || '',
+  gaps: (validation && validation.gaps) || [],
+  nextWorkflow: (validation && validation.nextWorkflow) || 'automate',
+  steps: 6,
+  needsHumanGate: true,
+  result: validation,
+}

package/install/templates/.claude/workflows/testarch-automate.js

@@ -0,0 +1,229 @@
+export const meta = {
+  name: 'testarch-automate',
+  description: 'Native port of the BYAN testarch-automate workflow: expand test automation coverage after implementation (or analyze an existing codebase) by preflighting the framework, identifying targets and levels, generating API + E2E tests in parallel, aggregating into files and fixtures, and validating into an automation summary. Returns a structured verdict for the orchestrating skill to present at the human gate.',
+  phases: [
+    { title: 'PREFLIGHT', detail: 'verify framework, determine mode (BMad-integrated vs standalone), load context + TEA knowledge fragments' },
+    { title: 'TARGETS', detail: 'identify automation targets, choose test levels (E2E/API/Component/Unit), assign P0-P3 priorities, produce coverage plan' },
+    { title: 'GENERATE', detail: 'parallel fan-out: subprocess A generates API tests, subprocess B generates E2E tests' },
+    { title: 'AGGREGATE', detail: 'aggregate subprocess outputs, write test files + shared fixtures/factories/helpers, compute summary stats' },
+    { title: 'VALIDATE', detail: 'validate against the checklist and produce the automation summary; return the verdict' },
+  ],
+}
+
+// ---------------------------------------------------------------------------
+// FD / STRICT STATE CONTRACT  (re-asserted inline — enforcement-bridge).
+//
+// The in-CLI Workflow tool runs this script OUTSIDE the conversation turn, so
+// BYAN's main-thread hooks (fd-phase-guard, strict-scope-guard, strict-stop-
+// guard, mantra-validate) DO NOT fire here. This script therefore:
+//   - NEVER imports/requires _byan/.../lib/fd-state.js and NEVER writes
+//     fd-state.json directly (forbidden by byan-lint-workflows.js).
+//   - uses NO wall-clock (wall-clock / wall-clock) and NO randomness (RNG
+//     / crypto). The source step-03 derives a temp-file timestamp from
+//     a wall-clock read; the sandbox forbids that (it breaks resume), so any id/ts is
+//     passed in via `args` instead (args.runId).
+//   - returns DATA only. The orchestrating skill is the human-gated conductor;
+//     IT records FD/strict state via byan_fd_* / byan_strict_* MCP tools AT the
+//     gate. The generated tests + automation summary are the workflow product
+//     (written by the leaves), not BYAN platform state.
+// ---------------------------------------------------------------------------
+
+// Inputs mirror workflow.yaml variables. The source is autonomous
+// (execution_hints.autonomous=true, interactive=false): it proceeds without
+// prompts unless blocked, so this is a linear step sequence (one agent per
+// real source step), not a retry loop.
+const sourceDir = (args && args.sourceDir) || '{project-root}'
+const testDir = (args && args.testDir) || '{project-root}/tests'
+const coverageTarget = (args && args.coverageTarget) || 'critical-paths'
+const targetFeature = (args && args.targetFeature) || null // optional: focus a feature/files
+const runId = (args && args.runId) || 'run' // ts/id passed in (no clock in sandbox)
+
+// Step 1 of the source HALTs if no test framework is configured. That gate is a
+// hard precondition, not a human decision, so the script surfaces it as a
+// verdict field rather than continuing to invent tests against a missing config.
+const PREFLIGHT_SCHEMA = {
+  type: 'object',
+  required: ['frameworkReady', 'mode'],
+  properties: {
+    frameworkReady: { type: 'boolean', description: 'true only if playwright.config.ts or cypress.config.ts exists AND package.json has the test deps' },
+    framework: { type: 'string', description: 'detected framework (playwright | cypress | none)' },
+    mode: { type: 'string', description: 'bmad-integrated (story/tech-spec/test-design found) or standalone (source only)' },
+    usePlaywrightUtils: { type: 'boolean', description: 'value of tea_use_playwright_utils from config' },
+    knowledgeFragments: { type: 'array', items: { type: 'string' }, description: 'TEA knowledge fragments loaded' },
+    notes: { type: 'string' },
+  },
+}
+
+const PLAN_SCHEMA = {
+  type: 'object',
+  required: ['targets', 'levels'],
+  properties: {
+    targets: { type: 'array', items: { type: 'string' }, description: 'features/files to test' },
+    levels: { type: 'array', items: { type: 'string' }, description: 'selected test levels: e2e, api, component, unit' },
+    priorities: { type: 'object', description: 'priority assignment summary (P0-P3)' },
+    justification: { type: 'string', description: 'why this coverage scope (critical-paths/comprehensive/selective)' },
+  },
+}
+
+const SUBPROCESS_SCHEMA = {
+  type: 'object',
+  required: ['success', 'subprocess', 'testCount'],
+  properties: {
+    success: { type: 'boolean' },
+    subprocess: { type: 'string', description: 'api-tests | e2e-tests' },
+    files: { type: 'array', items: { type: 'string' }, description: 'test file paths produced' },
+    testCount: { type: 'integer' },
+    fixtureNeeds: { type: 'array', items: { type: 'string' } },
+    summary: { type: 'string' },
+  },
+}
+
+const VALIDATE_SCHEMA = {
+  type: 'object',
+  required: ['passed'],
+  properties: {
+    passed: { type: 'boolean', description: 'true only if all checklist completion criteria are met' },
+    gaps: { type: 'array', items: { type: 'string' }, description: 'unmet checklist items' },
+    summaryPath: { type: 'string', description: 'path to the written automation summary' },
+    nextWorkflow: { type: 'string', description: 'recommended follow-up workflow (test-review or trace)' },
+  },
+}
+
+// --- Step 1: Preflight & Context Loading (steps-c/step-01) -----------------
+phase('PREFLIGHT')
+const preflight = await agent(
+  `You are the Master Test Architect running testarch-automate (autonomous mode: proceed without prompts unless blocked).\n` +
+    `STEP 1 - Preflight & Context. Source dir: ${JSON.stringify(sourceDir)}; test dir: ${JSON.stringify(testDir)}.\n` +
+    `1. Verify a test framework exists (playwright.config.ts or cypress.config.ts AND test deps in package.json). ` +
+    `If the framework is completely missing, set frameworkReady=false (the source HALTs here with "Run the framework workflow first") and do NOT fabricate tests.\n` +
+    `2. Determine execution mode: bmad-integrated if a story / tech-spec / test-design artifact is present, else standalone (source code only).\n` +
+    `3. Load context: framework config, existing test structure under the test dir, existing tests (for coverage gaps). Read tea_use_playwright_utils from config.\n` +
+    `4. Load the required TEA knowledge fragments (test-levels-framework, test-priorities-matrix, data-factories, selective-testing, ci-burn-in, test-quality; plus playwright-utils OR traditional fixture/network-first fragments per config).\n` +
+    `Report the detected framework, mode, playwright-utils flag, and the fragments loaded.`,
+  { label: 'preflight', phase: 'PREFLIGHT', schema: PREFLIGHT_SCHEMA }
+)
+log(`preflight: frameworkReady=${Boolean(preflight && preflight.frameworkReady)} mode=${preflight && preflight.mode}`)
+
+// Hard precondition gate (mirrors step-01 HALT). Return early as a verdict;
+// the human-gated skill decides whether to run the framework workflow first.
+if (!preflight || !preflight.frameworkReady) {
+  return {
+    workflow: 'testarch-automate',
+    status: 'halted-no-framework',
+    summary: 'No test framework configured (playwright.config.ts / cypress.config.ts missing). Run the framework workflow first.',
+    steps: 1,
+    preflight,
+    needsHumanGate: true,
+  }
+}
+
+// --- Step 2: Identify Automation Targets (steps-c/step-02) -----------------
+phase('TARGETS')
+const plan = await agent(
+  `STEP 2 - Identify automation targets and build the coverage plan. Mode: ${preflight.mode}. ` +
+    `Coverage target: ${JSON.stringify(coverageTarget)}. Focus: ${targetFeature ? JSON.stringify(targetFeature) : 'auto-discover features in the source dir'}.\n` +
+    `1. Determine targets: bmad-integrated -> map acceptance criteria to scenarios, check existing ATDD outputs to avoid duplication, expand with edge/negative paths. ` +
+    `standalone -> focus the given feature/files if provided, else auto-discover; prioritize critical paths, integrations, untested logic.\n` +
+    `2. Choose test levels per test-levels-framework: E2E for critical journeys, API for business logic/contracts, Component for UI behavior, Unit for pure logic/edge cases. Avoid duplicate coverage across levels.\n` +
+    `3. Assign priorities per test-priorities-matrix (P0 critical+high-risk, P1 important+medium/high-risk, P2 secondary+edge, P3 optional).\n` +
+    `4. Produce a concise coverage plan: targets by level, priority assignments, and justification for the ${coverageTarget} scope.`,
+  { label: 'coverage-plan', phase: 'TARGETS', schema: PLAN_SCHEMA }
+)
+log(`plan: targets=${(plan && plan.targets && plan.targets.length) || 0} levels=${(plan && plan.levels && plan.levels.join(',')) || ''}`)
+
+// --- Step 3: Orchestrate Parallel Test Generation (steps-c/step-03) --------
+// The source mandates a PARALLEL fan-out: subprocess 3A (API) and 3B (E2E)
+// run simultaneously, and step-03c waits for BOTH before aggregating. parallel()
+// is the faithful native shape (NOT sequential — sequential is a SYSTEM FAILURE
+// per the source's own rules).
+phase('GENERATE')
+const planJson = JSON.stringify(plan)
+const [apiGen, e2eGen] = await parallel([
+  // Subprocess A: API tests ONLY (steps-c/step-03a-subprocess-api).
+  () =>
+    agent(
+      `SUBPROCESS A (run ${runId}) - generate API tests ONLY (no E2E, no fixtures yet, do not run tests).\n` +
+        `Coverage plan: ${planJson}. Playwright-utils enabled: ${Boolean(preflight.usePlaywrightUtils)}.\n` +
+        `From the plan, identify API endpoints, request/response shapes, auth needs, error scenarios. ` +
+        `For each, create tests/api/[feature].spec.ts: use apiRequest() if playwright-utils enabled (else the request fixture), ` +
+        `data factories for test data, priority tags [P0]-[P3], happy-path AND error scenarios, proper TS types, deterministic assertions. ` +
+        `Track (do NOT create) the fixture needs for the aggregation step. Report the files, test count, and fixture needs.`,
+      { label: 'gen-api', phase: 'GENERATE', schema: SUBPROCESS_SCHEMA }
+    ),
+  // Subprocess B: E2E tests ONLY (steps-c/step-03b-subprocess-e2e).
+  () =>
+    agent(
+      `SUBPROCESS B (run ${runId}) - generate E2E tests ONLY (no API, no fixtures yet, do not run tests).\n` +
+        `Coverage plan: ${planJson}. Playwright-utils enabled: ${Boolean(preflight.usePlaywrightUtils)}.\n` +
+        `From the plan, identify the critical user journeys. ` +
+        `For each, create tests/e2e/[feature].spec.ts: fixture-architecture patterns, network-first (intercept BEFORE navigate), ` +
+        `resilient selectors (getByRole/getByText/getByLabel), priority tags [P0]-[P3], complete journeys (not isolated clicks), ` +
+        `proper TS types, deterministic waits (no hard sleeps). ` +
+        `Track (do NOT create) the fixture needs for aggregation. Report the files, test count, and fixture needs.`,
+      { label: 'gen-e2e', phase: 'GENERATE', schema: SUBPROCESS_SCHEMA }
+    ),
+])
+log(
+  `generate: api.success=${Boolean(apiGen && apiGen.success)} (${(apiGen && apiGen.testCount) || 0}) ` +
+    `e2e.success=${Boolean(e2eGen && e2eGen.success)} (${(e2eGen && e2eGen.testCount) || 0})`
+)
+
+// Mirror of step-03 / step-03c exit guard: do NOT aggregate if either
+// subprocess failed. This is a precondition, not a human decision.
+const bothSucceeded = Boolean(apiGen && apiGen.success) && Boolean(e2eGen && e2eGen.success)
+if (!bothSucceeded) {
+  return {
+    workflow: 'testarch-automate',
+    status: 'failed-generation',
+    summary: 'One or both test-generation subprocesses failed; aggregation skipped (mirrors step-03 exit condition).',
+    steps: 3,
+    preflight,
+    plan,
+    generation: { api: apiGen, e2e: e2eGen },
+    needsHumanGate: true,
+  }
+}
+
+// --- Step 3C: Aggregate (steps-c/step-03c-aggregate) -----------------------
+phase('AGGREGATE')
+const aggregate = await agent(
+  `STEP 3C - Aggregate the two subprocess outputs and complete the test infrastructure (do NOT regenerate tests, do NOT run them).\n` +
+    `API subprocess output: ${JSON.stringify(apiGen)}\nE2E subprocess output: ${JSON.stringify(e2eGen)}\n` +
+    `1. Write all API and E2E test files to disk.\n` +
+    `2. Aggregate the fixture needs from both subprocesses (de-duplicate), categorize them (auth fixtures, data factories, network mocks, helpers).\n` +
+    `3. Generate the shared fixture infrastructure: tests/fixtures/auth.ts (test.extend with auto-cleanup), tests/fixtures/data-factories.ts (faker-based, override-able), tests/fixtures/network-mocks.ts, tests/fixtures/helpers.ts.\n` +
+    `4. Compute summary statistics: total/api/e2e test counts, fixtures created, per-priority breakdown (P0-P3), knowledge fragments used.\n` +
+    `Report the written files and the computed statistics.`,
+  { label: 'aggregate', phase: 'AGGREGATE' }
+)
+
+// --- Step 4: Validate & Summarize (steps-c/step-04-validate-and-summarize) -
+phase('VALIDATE')
+const validate = await agent(
+  `STEP 4 - Validate the generated outputs against the automate checklist and produce the automation summary.\n` +
+    `Aggregation result: ${aggregate}\n` +
+    `1. Validate per checklist.md: framework readiness, coverage mapping, test quality/structure, fixtures/factories/helpers, no duplicate coverage, priority tags present, network-first applied, deterministic (no hard waits). Fix gaps before completing; report any that remain.\n` +
+    `2. Write the automation summary to the output folder (automation-summary.md): coverage plan by level and priority, files created/updated, key assumptions and risks, and the recommended next workflow (test-review or trace).\n` +
+    `Set passed=true only if every completion criterion is satisfied.`,
+  { label: 'validate-summarize', phase: 'VALIDATE', schema: VALIDATE_SCHEMA }
+)
+log(`validate: passed=${Boolean(validate && validate.passed)} gaps=${(validate && validate.gaps && validate.gaps.length) || 0}`)
+
+// Return DATA only. The orchestrating skill presents this at the human gate
+// and records FD/strict state via MCP.
+return {
+  workflow: 'testarch-automate',
+  status: validate && validate.passed ? 'complete' : 'needs-fixes',
+  summary:
+    `Generated ${(apiGen.testCount || 0) + (e2eGen.testCount || 0)} tests ` +
+    `(${apiGen.testCount || 0} API, ${e2eGen.testCount || 0} E2E) for ${coverageTarget} coverage in ${preflight.mode} mode.`,
+  steps: 5,
+  mode: preflight.mode,
+  coverageTarget,
+  preflight,
+  plan,
+  generation: { api: apiGen, e2e: e2eGen },
+  aggregation: aggregate,
+  validation: validate,
+  needsHumanGate: true,
+}