bmad-module-ultracode-goal 0.1.0

package/skills/ultracode-goal/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: ultracode-goal
+description: Runs a BMAD Epic autonomously to a machine-checked Definition-of-Done. Use when the user requests to 'run an epic autonomously', 'execute this epic', 'ultracode goal', or 'autonomously deliver the epic'.
+---
+
+# UltraCode Goal
+
+## Overview
+
+This skill autonomously delivers a BMAD Epic to a **machine-checked** Definition-of-Done. Act as an autonomous delivery conductor — a staff engineer who also owns the release gate. It preflights the Epic to a hard, *remediated* green light, turns acceptance criteria into executable tests with the Test Architect (TEA), drives the stories to completion, and advances only when TEA's deterministic quality gate reads PASS — capturing what it learns to Auto Memory so the next run is sharper. Your output is a delivered, gate-passed Epic, a run report, and a deferred-work ledger of anything safely parked for later.
+
+Module `bmad-module-ultracode-goal`. It orchestrates the installed BMAD epic toolbox (`bmad-sprint-planning`, `bmad-create-story`, `bmad-check-implementation-readiness`, `bmad-dev-story`, `bmad-code-review`, `bmad-correct-course`, `bmad-sprint-status`, `bmad-retrospective`) and the TEA gates (`bmad-testarch-framework`, `-ci`, `-test-design`, `-atdd`, `-automate`, `-test-review`, `-nfr`, `-trace`). It composes Claude Code primitives — `/goal`, Auto Mode, Auto Memory, hooks, git/worktree isolation — it is a conductor over them, not a replacement for them.
+
+## Conventions
+
+- Bare paths (e.g. `references/preflight.md`) resolve from the skill root.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+
+## On Activation
+
+### Step 1: Resolve the Workflow Block
+
+Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
+
+If it fails, resolve the `workflow` block yourself by reading these three files in base → team → user order (scalars override, tables deep-merge, arrays append): `{skill-root}/customize.toml`, `{project-root}/_bmad/custom/{skill-name}.toml`, `{project-root}/_bmad/custom/{skill-name}.user.toml`. Read every customized value below as `{workflow.<name>}`.
+
+Load config from `{project-root}/_bmad/config.yaml` and `config.user.yaml` (root + `bmm` section for `{planning_artifacts}`); fall back to `{project-root}/_bmad/bmm/config.yaml`. If config is missing, note that `bmad-bmb-setup` is available and continue with defaults. Load `{workflow.persistent_facts}` and greet in `{communication_language}`.
+
+**Run modes.** Profile defaults to **production** (full TEA gates); `--light` runs the trace gate only. Execution defaults to the **sequential** `/goal` spine; `--parallel` opts into the experimental worktree fan-out. `-H` is headless. `--yes` skips Stage 1's open-floor invite and the launch confirm (the launch briefing still prints) — it **never** skips the hard preflight gate. `--retro` runs the close-out retrospective: interactive runs offer it at Epic close anyway, but headless runs it only when `--retro` was passed.
+
+**Resume.** The workspace is this skill's run folder holding `.decision-log.md`. If one exists for the Epic, surface it with its last session date and offer to resume — the log recovers full state regardless of compaction. Otherwise create it at intent and append a session heading. On resume, re-enter Execute at the first story whose last logged gate verdict is not advance; advanced stories are not re-run; re-assert (do not rebuild) the Epic branch, hooks, and allowlist before continuing.
+
+## Non-negotiables
+
+These exist because the documented mechanics make the intuitive shortcut wrong. Do not optimize them away.
+
+- **Completion is decided by `scripts/gate_eval.py` reading TEA's `gate-decision.json` — never your own judgment, and never the `/goal` evaluator alone.** That evaluator only sees the transcript; it cannot read the gate file. The JSON is the truth.
+- **Launch the unattended run only when `scripts/preflight_check.py` returns green *after the remediation pass* (intervention budget == 0) and ultracode + Auto Mode are on.** Under `--parallel`, the fan-out takes no mid-run input — every gate is resolved before launch or not at all.
+- **Only non-gate-blocking work defers** to `{workflow.deferred_work_path}`, and the Epic keeps moving; a P0/critical FAIL never defers — it re-loops within budget or escalates.
+- **Rollback is git** — Epic branch off `{workflow.epic_branch_prefix}`, one commit per green story, worktree isolation. `/rewind` checkpoints miss Bash changes; do not rely on them.
+- **Invariants live in PreToolUse hooks**, auto-merged into `.claude/settings.local.json` at preflight — not in memory, which is context, not enforcement.
+
+## Stages
+
+| # | Stage | Purpose | Location |
+|---|-------|---------|----------|
+| 1 | Ingest & Scope | Resolve the Epic + artifacts; confirm profile (production default / `--light`) | `references/ingest-and-scope.md` |
+| 2 | Preflight | Auto-remediate ambers, then hard-gate on red; git branch, hooks, allowlist | `references/preflight.md` |
+| 3 | Define Done | TEA test-design + per-story ATDD → executable acceptance tests | `references/define-done.md` |
+| 4 | Execute | Sequential `/goal` spine (default) or `--parallel` worktree fan-out | `references/execute.md` |
+| 5 | Gate | `gate_eval.py` verdict → advance / defer / reloop / escalate | `references/gate.md` |
+| 6 | Finalize | Auto Memory capture, optional retrospective, decision-log audit, report, workflow health check | `references/finalize.md` |
+
+Run the stages in order; each routes by the testable conditions stated in its file. The decision log is canonical memory — record scope, the preflight verdict, every gate outcome, and every deferral as you go.
+
+## Headless
+
+With `-H`, run non-interactively: infer scope, default to **production** (unless `--light`), never prompt — a secret that cannot be resolved becomes a red blocker, not a question — and let `.decision-log.md` absorb every assumption.
+
+**One emit shape, every exit point.** Whether the run completes (Stage 6), or blocks early at ingest (Stage 1, e.g. epic unresolved), at preflight (Stage 2), or at a story escalation (Stage 6), emit this exact object — all five keys always present, `null` when that artifact was not produced, and `reason` carrying a one-line cause **only** when blocked:
+
+```json
+{"status": "complete|blocked",
+ "skill": "ultracode-goal",
+ "decision_log": "<path to this run's .decision-log.md>",
+ "report": "<path to run-report.md, or null>",
+ "deferred_work": "<path to {workflow.deferred_work_path}, or null>",
+ "reason": "<one line, present only when blocked>"}
+```
+
+An automator parses one schema regardless of where the run stopped; a blocked-before-report exit returns `report` and `deferred_work` as `null` rather than omitting them.
+
+Runs that reach Stage 6 (complete or escalated) also run the terminal workflow health check before emitting — in headless it queues findings locally and never blocks the emit. Runs that block at Stage 1 or Stage 2 do not: there is no executed workflow surface to audit, and inventing findings there would be fabrication.

package/skills/ultracode-goal/assets/execute-epic.workflow.js

@@ -0,0 +1,208 @@
+// EXPERIMENTAL — ultracode-goal --parallel worktree fan-out.
+//
+// This is the additive, opt-in parallel execution path (decision D4'/D7). The DEFAULT
+// path is the sequential /goal spine in references/execute.md; this script only runs when
+// the operator passes --parallel. It shares the SAME truth sources as the sequential path:
+// the deterministic gate is scripts/gate_eval.py reading TEA's gate-decision.json (never
+// the model, never the transcript-only /goal evaluator), and the same PreToolUse + Stop
+// hooks merged into .claude/settings.local.json at preflight enforce the invariants.
+//
+// WHY EXPERIMENTAL: this path leans on workflow<->skill interplay the Claude Code docs
+// leave under-specified — whether worktree-isolated agents can reliably drive BMAD/TEA
+// skills, and how concurrent stories interact with the single per-repo auto-memory
+// directory (all worktrees of one git repo SHARE one ~/.claude/projects/<repo>/memory/,
+// a known cross-writer collision risk). There is no mid-run user input here: every gate
+// is resolved before launch or not at all. Validate empirically before trusting it
+// unattended; on any doubt, fall back to the sequential spine.
+//
+// Available workflow primitives (top-level await + return supported):
+//   meta            — pure literal exported below (no runtime values)
+//   phase(title)    — declare the current phase for the run log/UI
+//   log(msg)        — append to the run log
+//   parallel([fns]) — run zero-arg thunks concurrently, returns results array
+//   pipeline(items, ...stageFns) — map items through ordered stages
+//   agent(prompt, { label, phase, schema, isolation }) — spawn a subagent; isolation:
+//                     'worktree' runs it in .claude/worktrees/ on its own branch so
+//                     concurrent stories never overwrite each other's working tree.
+
+export const meta = {
+  name: 'ultracode-goal-execute',
+  description:
+    'EXPERIMENTAL --parallel path: fan a BMAD Epic out across worktree-isolated per-story agents (dev-story un-skipping ATDD, tests/lint/build, production test-review + code-review, commit at green), gate each story with gate_eval.py, then run one epic-level trace gate. Shares the sequential spine gate + hooks.',
+  phases: [
+    { title: 'Stories', detail: 'Per-story worktree-isolated dev -> verify -> review -> commit -> gate_eval, batched to max_concurrency' },
+    { title: 'EpicGate', detail: 'Epic-level TEA trace gate over the merged result via gate_eval.py' },
+  ],
+}
+
+// ---------------------------------------------------------------------------
+// args (supplied by the skill when it invokes this workflow):
+//   epic                 — Epic id/string
+//   stories[]            — ordered list of in-scope stories (id + path/context)
+//   profile              — 'production' (full TEA + reviews) | 'light' (trace gate only)
+//   paths.{trace_output, deferred_work, implementation_artifacts, tea_config, skill_root}
+//                          skill_root is the resolved {skill-root} — the skill threads it in
+//                          because this .js is run by the dynamic-workflow runtime, which has
+//                          no {skill-root} resolver, so the gate_eval.py path must arrive absolute.
+//   max_concurrency      — cap on simultaneous worktree agents; the GOVERNING value is the
+//                          passed parallel_max_concurrency ({workflow.parallel_max_concurrency},
+//                          customize.toml default 8). The literal 4 below is only a fallback when
+//                          the skill invokes this workflow without supplying max_concurrency.
+// ---------------------------------------------------------------------------
+const {
+  epic,
+  stories = [],
+  profile = 'production',
+  paths = {},
+  max_concurrency = 4,
+} = args
+
+const traceOutput = paths.trace_output
+const deferredWork = paths.deferred_work
+const implArtifacts = paths.implementation_artifacts
+const teaConfig = paths.tea_config
+// Resolved {skill-root}; substituted into the gate_eval.py prompt strings below so the
+// spawned worktree agent receives an absolute script path, not an unresolved brace token.
+const skillRoot = paths.skill_root
+const isProduction = profile === 'production'
+const concurrency = Math.max(1, Number(max_concurrency) || 1)
+
+// Verdict mapping is OWNED by gate_eval.py — this schema only captures what the agent
+// reports back from running it. The agent MUST NOT recompute TEA thresholds or decide the
+// verdict itself; it runs the script and returns the script's stdout fields verbatim.
+const STORY_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['story', 'verdict', 'gate_status', 'committed'],
+  properties: {
+    story: { type: 'string', description: 'the story id' },
+    verdict: { type: 'string', enum: ['advance', 'defer', 'reloop', 'escalate'], description: 'verbatim gate_eval.py verdict' },
+    gate_status: { type: 'string', description: 'verbatim gate_eval.py gate_status (PASS|CONCERNS|FAIL|WAIVED|NOT_EVALUATED)' },
+    committed: { type: 'boolean', description: 'true only if tests/lint/build were green AND a single commit was made on the story branch' },
+    branch: { type: 'string', description: 'the worktree branch this story was developed on' },
+    evidence: { type: 'string', description: 'short summary of printed test/lint/build evidence' },
+    deferred: {
+      type: 'array',
+      description: 'non-gate-blocking items to append to the deferred-work ledger; NEVER a P0/critical FAIL',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['source', 'severity', 'reason', 'suggested_action'],
+        properties: {
+          source: { type: 'string', enum: ['gate', 'code-review', 'nfr', 'decision'] },
+          severity: { type: 'string', enum: ['low', 'med', 'high'] },
+          reason: { type: 'string' },
+          suggested_action: { type: 'string' },
+        },
+      },
+    },
+    reasons: { type: 'array', items: { type: 'string' }, description: 'gate_eval.py reasons[]' },
+  },
+}
+
+const EPICGATE_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['verdict', 'gate_status'],
+  properties: {
+    verdict: { type: 'string', enum: ['advance', 'defer', 'reloop', 'escalate'] },
+    gate_status: { type: 'string' },
+    reasons: { type: 'array', items: { type: 'string' } },
+  },
+}
+
+function storyId(s, i) {
+  if (typeof s === 'string') return s
+  return s.id || s.story || s.path || `story-${i + 1}`
+}
+
+function storyContext(s) {
+  if (typeof s === 'string') return s
+  return [s.path ? `path: ${s.path}` : '', s.context || s.title || ''].filter(Boolean).join('\n')
+}
+
+// One worktree-isolated agent per story. The pipeline below batches these so no more than
+// `concurrency` run at once; within a story the steps are strictly ordered.
+function runStory(s, i) {
+  const id = storyId(s, i)
+  const reviewStep = isProduction
+    ? `4. PRODUCTION reviews (skip under --light): run bmad-testarch-test-review then bmad-code-review on this story's diff. P0/critical findings are NOT deferrable — they must be fixed in this worktree before commit (re-loop within {workflow.max_turns_per_story}). Non-critical findings go into the "deferred" array.\n`
+    : `4. LIGHT profile: skip test-review/code-review (trace gate only).\n`
+
+  return agent(
+    `You are delivering ONE story of BMAD Epic "${epic}" inside an ISOLATED git worktree (isolation: worktree). ` +
+      `Your working tree is private — other stories run concurrently in their own worktrees on their own branches, so commit only your own story's changes. ` +
+      `This is the EXPERIMENTAL --parallel path; there is NO mid-run human input. Profile: ${profile}.\n\n` +
+      `STORY: ${id}\n${storyContext(s)}\n\n` +
+      `Execute these steps IN ORDER, printing real evidence at each step (the printed evidence keeps the run auditable, but the GATE is gate_eval.py, not your judgment):\n` +
+      `1. bmad-create-story (Create mode only — never Resume) to fully context the story file if it is not already complete.\n` +
+      `2. bmad-dev-story to implement it, UN-SKIPPING the red-phase ATDD acceptance tests for this story (remove the test.skip markers that define the Definition-of-Done) so they actually run.\n` +
+      `3. Run and PRINT the project's test, lint, and build commands. Once all three are green, write the tests-ran marker file ${implArtifacts}/.tests-ran-${id} (exact name the PreToolUse hook checks, with ULTRACODE_STORY_ID=${id} for this worktree) so the hook permits the commit. Do NOT proceed to commit unless all three are green.\n` +
+      reviewStep +
+      `5. COMMIT AT GREEN: make exactly ONE commit on this worktree's branch capturing the story. The PreToolUse hook will deny the commit on a protected branch or without the tests-ran marker — that is expected enforcement, satisfy it rather than bypass it. Set committed=true only if the commit succeeded on green.\n` +
+      `6. GATE THIS STORY — run EXACTLY:\n` +
+      `   uv run ${skillRoot}/scripts/gate_eval.py --trace-output ${traceOutput} --profile ${profile}` +
+      (isProduction ? ` --nfr <nfr-assessment.md> --test-review <test-review.md>` : ``) + `\n` +
+      `   (in production, first run bmad-testarch-automate to backfill coverage, then bmad-testarch-trace, then bmad-testarch-nfr so the gate file exists before you read it). ` +
+      `Return the script's verdict, gate_status, and reasons VERBATIM. Do not recompute TEA thresholds and do not override the verdict.\n\n` +
+      `INVARIANT: a P0/critical FAIL NEVER goes into "deferred" — fix-and-reloop within budget, or let the verdict be reloop/escalate. Only non-gate-blocking items (CONCERNS, non-critical review/NFR findings, parked decisions) belong in "deferred".\n\n` +
+      `Return ONLY the JSON object matching the schema. No prose outside it.`,
+    { label: `story:${id}`, phase: 'Stories', schema: STORY_SCHEMA, isolation: 'worktree' }
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Phase 1: per-story fan-out, batched to honor max_concurrency.
+// pipeline() maps each concurrency-sized chunk through one stage that fans the chunk out
+// with parallel(); chunks run sequentially, stories within a chunk run in parallel.
+// ---------------------------------------------------------------------------
+phase('Stories')
+log(`Epic ${epic}: ${stories.length} story(ies), profile=${profile}, concurrency=${concurrency} (EXPERIMENTAL --parallel)`)
+
+const indexed = stories.map((s, i) => ({ s, i }))
+const batches = []
+for (let b = 0; b < indexed.length; b += concurrency) {
+  batches.push(indexed.slice(b, b + concurrency))
+}
+
+const batchResults = await pipeline(
+  batches,
+  (batch) => parallel(batch.map(({ s, i }) => () => runStory(s, i)))
+)
+
+const perStory = batchResults.flat().filter(Boolean)
+log(`Stories complete: ${perStory.map((r) => `${r.story}=${r.verdict}/${r.gate_status}`).join(', ')}`)
+
+// Collect non-gate-blocking deferrals for the ledger (the skill, not this script, writes
+// the markdown table at {workflow.deferred_work_path} using the ledger schema).
+const deferred = []
+for (const r of perStory) {
+  for (const d of r.deferred || []) {
+    deferred.push({ story: r.story, ...d })
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Phase 2: epic-level trace gate over the whole epic once every story has landed.
+// ---------------------------------------------------------------------------
+phase('EpicGate')
+const epicGate = await agent(
+  `All stories of BMAD Epic "${epic}" have been delivered on their worktree branches. ` +
+    `Run the EPIC-LEVEL TEA quality gate over the consolidated epic` +
+    (isProduction ? ` (run bmad-testarch-automate -> bmad-testarch-trace -> bmad-testarch-nfr first)` : ` (run bmad-testarch-trace first)`) +
+    `, then run EXACTLY:\n` +
+    `  uv run ${skillRoot}/scripts/gate_eval.py --trace-output ${traceOutput} --profile ${profile}` +
+    (isProduction ? ` --nfr <nfr-assessment.md> --test-review <test-review.md>` : ``) + `\n` +
+    `Return the script's verdict, gate_status, and reasons VERBATIM. Do not recompute thresholds or override the verdict.\n` +
+    `Per-story outcomes for context: ${JSON.stringify(perStory.map((r) => ({ story: r.story, verdict: r.verdict, gate_status: r.gate_status })))}\n\n` +
+    `Return ONLY the JSON object matching the schema.`,
+  { label: `epic-gate:${epic}`, phase: 'EpicGate', schema: EPICGATE_SCHEMA }
+)
+
+log(`Epic gate: ${epicGate ? `${epicGate.verdict}/${epicGate.gate_status}` : 'unavailable'}; deferred items: ${deferred.length}`)
+
+return {
+  perStory: perStory.map((r) => ({ story: r.story, verdict: r.verdict, gate_status: r.gate_status })),
+  epicGate,
+  deferred,
+}

package/skills/ultracode-goal/customize.toml

@@ -0,0 +1,47 @@
+# Customization for ultracode-goal.
+# Resolved at activation via resolve_customization.py (base -> team -> user).
+# Teams/users override in {project-root}/_bmad/custom/ultracode-goal.toml (and .user.toml)
+# without editing this file.
+
+[workflow]
+activation_steps_prepend = []
+activation_steps_append = []
+persistent_facts = ["file:{project-root}/**/project-context.md"]
+
+# --- Paths: TEA + BMAD artifacts ---
+tea_config_path = "{project-root}/_bmad/tea/config.yaml"
+trace_output_dir = "{project-root}/_bmad-output/test-artifacts/traceability"
+implementation_artifacts = "{project-root}/_bmad-output/implementation-artifacts"
+deferred_work_path = "{project-root}/_bmad-output/implementation-artifacts/deferred-work.md"
+
+# --- Git isolation + guardrails ---
+epic_branch_prefix = "ultracode/epic-"
+protected_branches = ["main", "master"]
+
+# --- Budget guardrails (runaway-proofing) ---
+max_turns_per_story = 25
+story_token_budget = 1500000
+
+# --- Experimental --parallel worktree fan-out ---
+# 8 chosen under the platform's 16-concurrent ceiling; the .js default is only a fallback when unset.
+parallel_max_concurrency = 8
+
+# --- Commands pre-populated to the allowlist before an unattended run ---
+allowlist_commands = ["git status", "git add -A", "git commit", "npm test", "npm run lint", "npm run build", "pytest", "uv run"]
+
+# --- Hook fired at epic completion (prompt or shell command); empty = none ---
+on_epic_complete = ""
+
+# --- Health check (workflow self-improvement; opt-out + autonomy-safe) ---
+# The terminal Finalize step reflects on the run and can file genuine workflow
+# friction as fingerprint-deduped GitHub issues. Honesty-by-default: zero
+# findings is the expected, healthy outcome. See docs/health-check.md.
+health_check_enabled = true
+health_check_repo = "armelhbobdad/bmad-module-ultracode-goal"
+health_check_seen_cache = "$HOME/.ultracode-goal/health-check-seen.json"
+health_check_queue_path = "{project-root}/_bmad-output/ultracode-goal/improvement-queue"
+# In unattended/headless runs there is no human at the [Y]/[N]/[E] gate.
+# false (default) = queue findings locally, NEVER live-submit without a human.
+# true = additionally live-submit `bug`-severity findings unattended (still
+#        deduped + seen-cache-guarded). friction/gap never auto-submit.
+health_check_autosubmit = false

package/skills/ultracode-goal/references/define-done.md

@@ -0,0 +1,41 @@
+# Stage 3 — Define Done
+
+Turn the Epic's acceptance criteria into **executable, red-phase acceptance tests** before any production code is written. The output of this stage is a per-story, machine-checkable Definition-of-Done: a generated `atdd-checklist` plus failing (`test.skip`) acceptance tests that Stage 4 will un-skip and drive to green. Run entirely in `{communication_language}`; TEA-produced documents are written in `{document_output_language}`.
+
+This stage runs only after Stage 2 preflight returns green (intervention budget == 0). Preflight has already scaffolded the test framework (`bmad-testarch-framework`) and generated any missing acceptance criteria (`bmad-create-story`), so the framework is present and every in-scope story has *some* ACs by the time you arrive here. This stage hardens that into per-story executable tests.
+
+## Per Epic — Test Design (once)
+
+Run `bmad-testarch-test-design` in **Epic-Level Mode** for the Epic. This is the risk-and-priority backbone the rest of the run reads from. Its job here:
+
+- **Risk matrix** — genuine risks (not features) with unique IDs, classified by category (TECH / SEC / PERF / DATA / BUS / OPS), each scored probability × impact (1–3 each); score ≥6 is high-priority and must carry a mitigation. This is what `bmad-testarch-trace` later resolves the gate against, so it must exist before Execute.
+- **Priority classification P0–P3** — P0 = blocks core flow + high risk + no workaround. The gate Stage 5 reads (`gate_eval.py`) keys P0, P1, and overall thresholds to these priorities; those thresholds are hardcoded in TEA and TEA-owned. Do **not** restate or recompute the percentages; just ensure the test-design assigns the priorities honestly.
+- **NFR thresholds** — for every NFR in scope, extract the concrete threshold from PRD / architecture / ADRs / epics / stories. Unknown thresholds are marked `UNKNOWN` and converted into a risk, assumption, or deferred item — **never guessed**. In production these feed `bmad-testarch-nfr` at the gate; a missing threshold that should have a value is a deferral candidate, not a fabrication.
+
+Epic-Level Mode is selected by the presence of `sprint-status.yaml` (preflight reports `sprint_status_present`); if test-design prompts for system-vs-epic, choose **epic**. Force **Create** mode if it offers Resume/Validate/Edit — those are interactive and stall an unattended run.
+
+A `CONCERNS`-grade gap in the test plan (e.g. an `UNKNOWN` NFR threshold that does not block any P0 story) appends to `{workflow.deferred_work_path}` and the Epic keeps moving. A genuine red gap — no risk coverage for a P0 flow — is not deferrable; resolve it before proceeding to per-story work.
+
+## Per Story — Create then ATDD
+
+For every **in-scope** story, in sprint order:
+
+1. **`bmad-create-story`** — produce the dedicated story file with full implementation context and *clear, testable* acceptance criteria. If preflight already generated this story, treat the change request as a refinement, not a re-create. Vague ACs are the single most common cause of the next step halting — sharpen them here.
+
+2. **`bmad-testarch-atdd`** — generate the red-phase acceptance test scaffolds for that story. This writes:
+   - `atdd-checklist-{story_key}.md` under the TEA test-artifacts directory — the per-story checklist mapping each AC to its planned test(s).
+   - The acceptance test files themselves, **every test marked `test.skip()`** (TDD red phase). ATDD verifies this and errors if any generated test is not skipped — that is correct and expected; the tests are *supposed* to fail/skip until Stage 4 implements the feature and un-skips them.
+
+   `bmad-testarch-atdd` **HARD HALTS** if the story lacks clear acceptance criteria or the framework is not configured. Both are preconditions this stage's step 1 and Stage 2 preflight exist to satisfy — if atdd halts anyway, the story's ACs are still too vague: loop back to `bmad-create-story` for that story and re-run atdd. Do not hand a story to Execute with a halted or absent atdd-checklist.
+
+   Force **Create** mode (not Resume/Validate/Edit) for the same unattended reason.
+
+## Exit condition (testable)
+
+Stage 3 is complete, and Stage 4 may begin, when **all three** hold:
+
+- The Epic has a `bmad-testarch-test-design` plan with a populated risk matrix, P0–P3 priorities assigned, and every in-scope NFR threshold either resolved or explicitly marked `UNKNOWN`/deferred.
+- **Every in-scope story** has a story file with clear acceptance criteria.
+- **Every in-scope story** has a generated `atdd-checklist-{story_key}.md` and red-phase (`test.skip`) acceptance tests on disk.
+
+If any in-scope story is missing its atdd-checklist, this stage is not done — Execute has nothing executable to drive that story to. Record in `.decision-log.md`: the test-design verdict, each story's AC + checklist status, and any deferral appended to `{workflow.deferred_work_path}`.

package/skills/ultracode-goal/references/execute.md

@@ -0,0 +1,90 @@
+# Stage 4 — Execute
+
+Drive each in-scope story from its red-phase acceptance tests (generated in Stage 3) to a green, committed state. This stage **produces and prints evidence**; it does **not** decide completion. The completion verdict belongs to Stage 5 (`scripts/gate_eval.py` reading TEA's `gate-decision.json`) — never the `/goal` transcript evaluator, which can only see what you surface and cannot read the gate file. Run prose in `{communication_language}`.
+
+Two paths. **Sequential `/goal` spine is the DEFAULT.** `--parallel` worktree fan-out is an additive, **EXPERIMENTAL** opt-in. Both share the same hooks and the same Stage 5 gate.
+
+Preconditions (asserted, not assumed): you are on the Epic branch (`{workflow.epic_branch_prefix}…`, off a `{workflow.protected_branches}` branch), PreToolUse + Stop hooks are active in `.claude/settings.local.json`, the allowlist is pre-populated, and every in-scope story has an `atdd-checklist-{story_key}.md` with `test.skip` acceptance tests. If any is false, return to Stage 2.
+
+**On resume, re-enter Execute at the first story whose last logged gate verdict is not advance; advanced stories are not re-run; re-assert (do not rebuild) the Epic branch, hooks, and allowlist before continuing.**
+
+## Default — Sequential `/goal` spine
+
+For each in-scope story, in sprint order, run this loop:
+
+0. **Set the current story** so the PreToolUse hook can locate this story's marker: write the story id to `{workflow.implementation_artifacts}/.current-story` (or export `ULTRACODE_STORY_ID=<story_id>` for the run). The guard reads the story id from `ULTRACODE_STORY_ID`, falling back to that `.current-story` file — without one set, it cannot find the marker and denies every commit.
+1. `bmad-create-story` (if not already current) → `bmad-dev-story` implementing the feature and **un-skipping** the story's ATDD acceptance tests (remove `test.skip()`). Before delegating, check the run's `.decision-log.md` for an **Operator notes** entry naming this story (a pre-launch hint like "watch the auth flow in story 3") and surface that note into the `bmad-dev-story` / review context for this story so the operator's last words actually reach the work.
+2. Run the tests, lint, and build, and **PRINT the raw output** (pass/fail counts, lint result, build result) into the transcript. This printed evidence is what keeps the run judgeable mid-flight and what the `/goal` driver reads to pace itself — but it is *evidence*, not the gate. **Once all three go green, write the tests-ran marker** `{workflow.implementation_artifacts}/.tests-ran-<story_id>` (mirroring `assets/execute-epic.workflow.js` step 3) — the PreToolUse guard denies the step-4 commit unless this marker exists for the current story, so write it only after a real green run.
+3. **Production profile only:** `bmad-testarch-test-review`, then `bmad-code-review`. A `CONCERNS`-grade or non-critical finding appends to `{workflow.deferred_work_path}` and the story proceeds. A **P0 / critical FAIL never defers** — re-loop within the turn budget or escalate.
+4. **Commit at green** (one commit per green story). The PreToolUse hook blocks a commit on a protected branch and blocks a commit when no "tests-ran" marker exists for the current story, so step 0 must have set the current story and step 2 must have actually run and written `{workflow.implementation_artifacts}/.tests-ran-<story_id>`.
+
+**Sub-skill halt catch-all.** If any orchestrated sub-skill blocks on interactive input mid-run, treat it as escalate for that story — write the escalation marker and stop; do not answer its prompt blind.
+
+### Authoring the `/goal` condition
+
+Wrap the loop in a single `/goal` whose condition is **under 4000 characters** and encodes the per-story Definition-of-Done as the success criterion, with an explicit escape clause. The condition must:
+
+- State the DoD in checkable terms: ATDD acceptance tests for the story un-skipped and **passing**, lint clean, build green, and (production) test-review + code-review passed — mirroring the printed evidence so the transcript-only evaluator can corroborate it.
+- Include the literal escape: **"…or stop after {workflow.max_turns_per_story} turns."** This is the in-condition runaway guard. The `budget_stop.py` Stop hook is belt-and-suspenders — it tracks turns/tokens against `{workflow.max_turns_per_story}` / `{workflow.story_token_budget}` and writes an escalation marker when exceeded — but a Stop hook **cannot force `/goal` to halt mid-condition**, so the turn clause inside the condition is the real bound. State it.
+- Make explicit that **passing the condition is not completion** — the authoritative verdict is Stage 5's `gate_eval.py`. The `/goal` condition gets a story to a *plausibly* done, evidence-printed state; the gate decides.
+
+Keep it under the character limit by referencing the story's `atdd-checklist` and printed test output rather than restating ACs verbatim.
+
+After the spine finishes (all stories committed-at-green, or a story hit its turn bound and wrote an escalation marker), proceed to Stage 5 for the deterministic per-story and epic-level gate.
+
+## Experimental — `--parallel` worktree fan-out
+
+Only when the user passed `--parallel`. Invoke the saved dynamic workflow `assets/execute-epic.workflow.js` (registered as `/ultracode-goal-execute`) with:
+
+```
+args = {
+  epic,                       # Epic id
+  stories,                    # in-scope story ids/keys, sprint order
+  profile,                    # "production" | "light"
+  paths: {
+    trace_output:           {workflow.trace_output_dir},
+    deferred_work:          {workflow.deferred_work_path},
+    implementation_artifacts: {workflow.implementation_artifacts},
+    tea_config:             {workflow.tea_config_path},
+    skill_root:             {skill-root}   # resolved absolute skill dir; the .js has no
+                                           # {skill-root} resolver, so it must arrive pre-resolved
+  },
+  max_concurrency: {workflow.parallel_max_concurrency}
+}
+```
+
+Pass `paths.skill_root` as the **resolved** `{skill-root}` (the absolute install dir). The workflow runtime executes the `.js` directly and has no `{skill-root}` resolver, so it substitutes this value into the `gate_eval.py` invocations it emits to each subagent; without it the spawned worktree agent receives a literal `{skill-root}` and must guess the script's path.
+
+Each story runs isolated in its own worktree: `bmad-dev-story` (un-skip ATDD) → run tests/lint/build → (production) `bmad-testarch-test-review` → `bmad-code-review` → commit at green → per-story `gate_eval`. After all stories, an epic-level trace gate. The workflow returns `{ perStory: [{story, verdict, gate_status}], epicGate, deferred: […] }`, which feeds Stage 5/6.
+
+**This path is experimental — be explicit about its limits and do not silently rely on it:**
+
+- **No mid-run input.** The fan-out takes no interactive input once launched; every blocker must be resolved at preflight or not at all. This is why launch requires post-remediation budget == 0.
+- **Shared Auto Memory.** Concurrent worktrees write to **one** Auto Memory directory — there is no per-worktree isolation of learned facts; expect interleaving.
+- **Under-documented interplay.** The workflow↔skill handoff (how args bind, how subagents inherit the allowlist and hooks) is not fully specified by the platform docs; treat its behavior as empirically validated, not guaranteed.
+- **No `run-status.json` heartbeat.** Worktree agents cannot reliably write one shared snapshot (each worktree sees its own copy of `{workflow.implementation_artifacts}`), so this path does not write it — progress is watched via the workflow progress view (`/workflows`) and its run log, and the launch briefing says so.
+
+### Graceful degradation
+
+If dynamic workflows are **unavailable** (wrong Claude Code version, workflows feature off, or the saved command does not resolve), **fall back to the sequential `/goal` spine above** and log a one-line note in `.decision-log.md` recording why `--parallel` degraded. The Epic still ships; it just ships sequentially.
+
+## Record
+
+Log to `.decision-log.md`: the path taken (sequential / parallel / degraded-fallback), per-story turn-budget outcomes, every commit-at-green, every deferral appended to `{workflow.deferred_work_path}`, and any escalation marker. The printed test/lint/build evidence stays in the transcript; the decision log carries the durable account across compaction.
+
+## Run-status heartbeat
+
+As the spine advances — each time you move to a new story, log a gate verdict, or spend a re-loop — write `{workflow.implementation_artifacts}/run-status.json` so an automator (or an anxious human) polling a long/headless run has something structured to read instead of prose. Overwrite it in place; it is a single live snapshot, not an append log:
+
+```json
+{"epic": "<epic id>",
+ "story": "<current story id>",
+ "index": <1-based position of the current story>,
+ "total": <in-scope story count>,
+ "last_verdict": "<advance|defer|reloop|escalate, or null before the first gate>",
+ "reloop_count": <re-loops spent so far this run>,
+ "profile": "production|light",
+ "updated": "<ISO-8601 timestamp>"}
+```
+
+This is the file the Stage 2 launch briefing points the operator at ("where to watch"); Stage 6 (finalize) records the terminal state into it when the run closes.

package/skills/ultracode-goal/references/finalize.md

@@ -0,0 +1,64 @@
+# Stage 6 — Finalize
+
+**Goal:** Make the run pay off for the next one. Capture what was learned to the right durable store, optionally run a retrospective, audit the decision log, produce a run report, and surface the deferred-work ledger. This is the terminal stage — reached after the Epic-level gate advanced, or when a story escalated and the run is `blocked`. Converse in `{communication_language}`; the run report and ledger are written in `{document_output_language}`.
+
+## Capture to Auto Memory — deliberately
+
+Auto Memory is passive by default; drive it on purpose so the learnings land in the right place and the next run starts sharper. Decide each learning's home:
+
+- **Machine-local learnings** (this repo's build quirks, a flaky-test workaround, a path that differs from convention, a TEA config gotcha) → tell the session to **`remember X`** so it persists to Auto Memory. Keep `MEMORY.md` terse — a short index that points to per-topic files; put the detail in the topic file, not the index.
+- **Team standards** (a convention every contributor and future run should follow — a lint rule, a commit-message shape, a forbidden pattern) → write to `{project-root}/CLAUDE.md` or `{project-root}/.claude/rules`, not to machine-local memory. CLAUDE.md is context the whole team and every agent inherits; Auto Memory is yours alone.
+
+The split matters: a team standard buried in machine-local memory never reaches the team, and a machine-local quirk in CLAUDE.md pollutes shared context. Route each learning by who needs it.
+
+## Optional retrospective (`--retro`)
+
+Interactive runs **offer** the retrospective at Epic close (skip it by default if the user declines); headless runs it **only when `--retro` was passed**. When run, `bmad-retrospective` covers the Epic, and its lessons feed back through the capture step above — durable conclusions go to memory or CLAUDE.md by the same machine-local-vs-team split. It is additive, not required to close the run.
+
+## Decision-log audit
+
+Walk every entry in this run's `.decision-log.md` (scope, preflight verdict, each gate verdict, each deferral, every assumption). Each must resolve to one of three: **captured in the run report** (a primary decision or outcome the user takes away), **captured in the addendum** (a parked alternative or rejected option that needs a home but not the report), or **explicitly marked process noise** (set aside, not silently dropped). End with a shared accounting of how the run's reasoning was handled — not a one-sided polish.
+
+## Run report
+
+Produce a report (write it as a peer of `.decision-log.md` in the run folder, e.g. `run-report.md`) covering:
+
+- Epic and profile (production / `--light`), branch off `{workflow.epic_branch_prefix}`, sequential vs `--parallel`.
+- Per-story outcome: gate_status and verdict (advance / defer / reloop / escalate), and any re-loops spent against budget.
+- The Epic-level gate result.
+- Budget consumed vs `{workflow.max_turns_per_story}` / `{workflow.story_token_budget}`.
+- Learnings captured and where they went (memory vs CLAUDE.md).
+- A pointer to the deferred-work ledger and its open-item count.
+
+## Record the terminal run-status
+
+Execute maintains the heartbeat `{workflow.implementation_artifacts}/run-status.json` as the spine advances (shape: `{epic, story, index, total, last_verdict, reloop_count, profile, updated}`). At close, write its **terminal** state — the final story/index, the Epic-level `last_verdict` (`advance` when complete, the escalating story's verdict when blocked), and a fresh `updated` timestamp — so a poller reading the file after the run sees the settled outcome, not a stale mid-run snapshot.
+
+## Surface the deferred-work ledger
+
+Show the user **this run's Epic heading** from the ledger at `{workflow.deferred_work_path}` — the open items under that one heading, their severity and suggested actions — so nothing parked during the run is invisible at handoff. The ledger holds one heading per Epic across runs; do not surface other Epics' parked work. If the file (or this Epic's heading) does not exist, say so plainly: nothing was deferred this run.
+
+## Epic-complete hook
+
+This hook fires **only when the Epic-level gate verdict was `advance`** (a `complete` run). On a `blocked` run — a story escalated and the Epic never advanced — skip this step entirely; a "notify success" command must not fire on a blocked Epic.
+
+When the Epic advanced, run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_epic_complete`
+
+If the resolved `{workflow.on_epic_complete}` is non-empty, follow it as the final terminal instruction (a prompt to run or a shell command) before exiting.
+
+## Headless output
+
+In headless (`-H`), compose the final JSON, run the Workflow health check (below) in its unattended queue-only mode, then emit the JSON and stop. `status` is `complete` when the Epic-level gate advanced, or `blocked` when a story escalated. This is the **same five-key shape every headless exit point honors** (Stage 1 first-touch / already-done blocks, Stage 2 preflight block, and this Stage 6 final emit): all five keys are **always present**, with `report` and `deferred_work` set to `null` when not produced, and `reason` carrying a one-line cause only when `blocked` (`null` otherwise). An early `blocked` exit that produced no report still emits `"report": null` — never a missing key — so a caller parsing the documented shape never raises a KeyError:
+
+```json
+{"status": "complete|blocked",
+ "skill": "ultracode-goal",
+ "decision_log": "<path to this run's .decision-log.md>",
+ "report": "<path to run-report.md, or null>",
+ "deferred_work": "<path to {workflow.deferred_work_path}, or null>",
+ "reason": "<one line when blocked, else null>"}
+```
+
+## Workflow health check (terminal)
+
+After the run-status is settled and (in headless) the JSON is composed but **before** the final emit/exit, load `references/health-check.md`, read it fully, and execute it. This is the true terminal step for every run that reached Stage 6 — both a `complete` run and a `blocked` (escalated) run, since the workflow drove real work either way and genuine friction is observable. In headless it runs in its unattended queue-only mode and **never blocks the emit**; see that file's routing rules. Do not perform any other action between this section and executing the health check.

package/skills/ultracode-goal/references/gate.md

@@ -0,0 +1,70 @@
+# Stage 5 — Gate
+
+**Goal:** Decide whether a completed story (or, after the last story, the Epic) advances — by a deterministic artifact read, not by judgment. `scripts/gate_eval.py` reads TEA's `gate-decision.json` and returns a routing verdict. You execute the route. Converse in `{communication_language}`; the deferred-work ledger is written in `{document_output_language}`.
+
+This is the completion authority. The `/goal` evaluator only sees the transcript; it cannot read the gate file. Never substitute your own read of "the tests look green" or the evaluator's transcript-only verdict for this script. The JSON is the truth.
+
+## Backfill the gate evidence (production only)
+
+The gate reads artifacts TEA produces. In **production**, before running the gate, generate the evidence in order so the gate has something current to read:
+
+1. `bmad-testarch-automate` — backfill coverage for code that landed during Execute.
+2. `bmad-testarch-trace` — (re)build the traceability matrix and write the gate decision.
+3. `bmad-testarch-nfr` — audit NFR evidence; produces `nfr-assessment.md`.
+
+`bmad-testarch-test-review` runs in Execute per story; if you do not have a current `test-review.md` for the story, run it now too. In **`--light`**, skip all of the above and run only `bmad-testarch-trace`, then the gate with `--profile light` (trace gate only — no NFR/review AND).
+
+## Run the gate
+
+Production:
+
+```
+uv run {skill-root}/scripts/gate_eval.py --trace-output {workflow.trace_output_dir} --profile production --nfr {nfr-assessment.md} --test-review {test-review.md}
+```
+
+Light:
+
+```
+uv run {skill-root}/scripts/gate_eval.py --trace-output {workflow.trace_output_dir} --profile light
+```
+
+Resolve `{nfr-assessment.md}` and `{test-review.md}` to the paths TEA wrote them to (under `{workflow.trace_output_dir}` or the TEA output root); pass the production-only flags only in production. The script reads `gate-decision.json` (resolving its filename from the trace report frontmatter, falling back to the `e2e-trace-summary.json` gate fields when the slim file is absent — that fallback is **not** a failure). It returns JSON:
+
+```json
+{"verdict": "advance|defer|reloop|escalate",
+ "gate_status": "PASS|CONCERNS|FAIL|WAIVED|NOT_EVALUATED",
+ "p0_status": "...", "p1_status": "...", "overall_status": "...",
+ "nfr_status": "...", "review_score": 0, "reasons": ["..."]}
+```
+
+Do not recompute TEA thresholds or re-judge `gate_status` — read it as given. The script already ANDs the production signals (an `advance` is downgraded to `reloop` if `nfr-assessment.md` overallStatus is FAIL, or `test-review.md` score < 80 or recommendation is Block). Record the full verdict JSON and its `reasons` in `.decision-log.md` for this story.
+
+## Route on the verdict
+
+- **`advance`** (gate_status PASS or WAIVED) → the story passes. Move to the next story; when the last story passes, run the Epic-level trace gate the same way, then proceed to Stage 6 (`references/finalize.md`).
+
+- **`defer`** (gate_status CONCERNS, or non-critical code-review / NFR findings that did not flip the gate) → append the open items to the ledger at `{workflow.deferred_work_path}` using the schema below, then **advance** anyway. The Epic keeps moving; the parked work is visible.
+
+- **`reloop`** (gate_status FAIL, or a production signal downgraded an advance) → run `bmad-correct-course` to diagnose and adjust, then re-run the story (back through Execute, `references/execute.md`) — **within the remaining turn/token budget**. Re-run the gate after. If the re-loop would exceed `{workflow.max_turns_per_story}` or `{workflow.story_token_budget}`, treat it as `escalate` instead.
+
+- **`escalate`** (gate_status NOT_EVALUATED — the gate could not be read — or budget exhausted on a FAIL) → **stop.** Do not advance, do not defer the failing item. Record the reason and the verdict JSON in `.decision-log.md`. In an attended run, surface the blocker to the user. In headless, this is a `blocked` outcome — emit the JSON in Stage 6 (`references/finalize.md`).
+
+**INVARIANT — a P0/critical FAIL never defers.** A failing gate (or a P0/P1/overall threshold miss) is `reloop` or `escalate`, never `defer`. Only non-gate-blocking work (CONCERNS, non-critical findings, parked decisions) is allowed onto the ledger. If you find yourself about to write a FAIL or a critical finding to the ledger, you are violating the gate — re-loop within budget or escalate instead.
+
+If any orchestrated sub-skill blocks on interactive input mid-run, treat it as `escalate` for that story — write the escalation marker and stop; do not answer its prompt blind.
+
+## Deferred-work ledger schema
+
+Append to `{workflow.deferred_work_path}` (create on first use). One heading per Epic, then a row per parked item; `status` is `open` at write time:
+
+```markdown
+# Deferred Work — <epic>
+
+| id | source | severity | story | reason | suggested_action | status |
+|----|--------|----------|-------|--------|------------------|--------|
+| d1 | gate | low | <story-id> | <why parked> | <what to do later> | open |
+```
+
+- `source` ∈ `gate` (CONCERNS), `code-review` (non-critical finding), `nfr` (non-FAIL finding), `decision` (parked decision).
+- `severity` ∈ `low`, `med`, `high`. A `high` that maps to a gate FAIL or a P0/critical finding does **not** belong here — re-loop or escalate it.
+- `id` is unique within the Epic heading (append `d2`, `d3`, … ); never rewrite existing rows.