bmad-module-ultracode-goal 0.1.0

package/skills/ultracode-goal/references/health-check.md

@@ -0,0 +1,332 @@
+---
+# UltraCode-Goal self-improvement health check — captures real workflow
+# friction as GitHub issues. (No name/description keys: those belong only
+# in SKILL.md frontmatter; this is a stage reference, not a skill.)
+healthCheckRepo: '{workflow.health_check_repo}'
+localFallbackFolder: '{workflow.health_check_queue_path}'
+seenCachePath: '{workflow.health_check_seen_cache}'
+liveSubmitSeverities: ['bug']  # friction/gap go local-queue-default with explicit opt-in
+enabled: '{workflow.health_check_enabled}'
+autosubmit: '{workflow.health_check_autosubmit}'
+---
+
+# Health Check: Workflow Self-Improvement
+
+This is the terminal step of Stage 6 (Finalize). Finalize loads it by bare path (`references/health-check.md`); it is fully self-contained and chains nowhere. Reflect on the ultracode-goal run that just completed; if real friction, bugs, or gaps were encountered in the *workflow instructions* (not the user's code), capture them as structured findings for review and optional submission as GitHub issues. Zero overhead for clean runs: if nothing went wrong, log one line and exit.
+
+## Role
+
+You are a self-improvement auditor — honest, precise, evidence-based. You report ONLY what you actually experienced executing the ultracode-goal stages during THIS run. You are NOT a creative writer looking for things to say.
+
+## Anti-fabrication rules
+
+- **DO NOT FABRICATE ISSUES.** If the workflow ran smoothly, say so and exit. Inventing issues to appear thorough is a SYSTEM FAILURE.
+- Only report issues you **ACTUALLY encountered** while following the stage instructions during THIS run.
+- Every finding MUST cite the **specific stage reference file and section** where the issue occurred.
+- If you are unsure whether something was a real issue or your own confusion, DO NOT report it.
+- **Reporting zero issues is the EXPECTED outcome** for a well-designed workflow.
+
+## 0. Announce arrival
+
+Display, in `{communication_language}`: "Running a quick self-improvement check on this run. If nothing rough came up, I will close out immediately."
+
+In headless (`-H`), skip the display and log: "headless: skipped health-check arrival announcement". The line is informational, not a commitment gate — proceed to §0.5 without waiting.
+
+## 0.5. Enabled gate
+
+If `{workflow.health_check_enabled}` is **false**, the health check is off. Log one line — "health-check disabled (health_check_enabled=false); skipping" — and **exit immediately**. Do nothing else: no reflection, no files, no JSON side effects. In headless this returns control so Finalize emits its final JSON unchanged.
+
+Otherwise continue to §1.
+
+## 1. Read run context
+
+From this run's `.decision-log.md` and session context, identify:
+
+- **Stage(s) executed** — which of `ingest-and-scope`, `preflight`, `define-done`, `execute`, `gate`, `finalize` you actually followed.
+- **Friction points** — moments where a stage instruction was unclear, wrong, contradictory, or silent on a scenario you hit.
+
+The finding's `stage` is whichever of the six you were following when the issue bit you.
+
+## 2. Reflect on execution
+
+Silently review the run. Ask:
+
+- Did a stage instruction lead me astray or cause unnecessary back-and-forth?
+- Was a stage ambiguous, so I guessed rather than followed clear guidance?
+- Did I hit a scenario no stage accounted for?
+- Were any stage instructions wrong or contradictory?
+
+If the answer to ALL is "no", display "Health Check: clean run. No workflow issues to report." and **STOP** — the run is done. In headless, log "health-check: clean run, no findings" and return.
+
+## 3. Severity definitions
+
+Classify each genuine finding:
+
+- **`bug`** — Stage instructions were wrong or contradictory.
+- **`friction`** — Stage worked but was unclear, ambiguous, or caused unnecessary back-and-forth.
+- **`gap`** — A scenario arose that the workflow did not account for at all.
+
+## 4. Route by run mode
+
+The routing fork is the run mode, decided once here.
+
+### 4a. Attended routing (HALT gate)
+
+In an attended run there is a human at the keyboard. Present every finding, then HALT.
+
+Present each finding:
+
+| Field | Value |
+|-------|-------|
+| Severity | `bug` / `friction` / `gap` |
+| Stage | one of the six |
+| Step File | `skills/ultracode-goal/references/{stage}.md` |
+| Section | the stable section-heading slug (never line numbers) |
+
+Then ask:
+
+"Submit these findings?
+
+- **[Y]** Yes — submit all findings
+- **[N]** No — discard all findings
+- **[E]** Edit — let me revise before submitting
+
+You are the final filter. Reject any finding that does not reflect a real issue you observed."
+
+**HALT and wait for input.**
+
+- **[Y]** → proceed to §5 (severity routing).
+- **[N]** → display "Findings discarded. Workflow complete." and STOP.
+- **[E]** → let the user keep, modify, or remove findings; re-present the revised list and ask again.
+
+### 4-headless. Unattended routing (no human at the gate)
+
+In headless (`-H`) there is no human to answer [Y]/[N]/[E], so that gate is **bypassed deterministically** — never block waiting for input:
+
+- If `{workflow.health_check_autosubmit}` is **false** (the default): **queue EVERY finding locally** (§5c). Never live-submit in an unattended run with autosubmit off.
+- If `{workflow.health_check_autosubmit}` is **true**: **live-submit `bug` findings only** (§5a) — still script-fingerprinted, remote-dedup-searched, and seen-cache-guarded; **friction and gap always queue** (§5c).
+
+The health check must **NEVER block or delay the final headless JSON emit**. It is fire-and-queue: do the routing above, then return so Finalize emits its JSON. If `gh` is unavailable at any live-submit step, fall through to §5c — never stall.
+
+## 5. Severity routing (attended [Y] path)
+
+Route each confirmed finding:
+
+- **`bug`** → live-submit (§5a). High signal, priority for maintainers.
+- **`friction` / `gap`** → local queue by default (§5c). These are the most subjective categories and produce the most near-duplicates. Ask **once per session**: "Also submit the {N} friction/gap finding(s) as GitHub issues? [y/N]" — only on explicit affirm do they route through §5a.
+
+### 5a. Live-submit: fingerprint, dedup, create
+
+For each finding routed to live-submit:
+
+**1. Compute the fingerprint via the script** — never inline shell. The fingerprint and seen-cache are computed and managed deterministically by `health_check_fp.py`:
+
+```
+uv run {skill-root}/scripts/health_check_fp.py fingerprint \
+  --severity {severity} --stage {stage} --section-slug {slug}
+```
+
+→ `{"fp": "fp-xxxxxxx", "tuple": "<exact hashed input>"}`. The `section-slug` is a kebab-case stable heading slug (e.g. `verdict-mapping`), **never line numbers** — they drift when files are edited.
+
+**Install-mode-invariant dedup (explicit rule):** the script's `workflow` component is `ultracode-goal/{stage}` and its `step_file` component is ALWAYS the source-repo form `skills/ultracode-goal/references/{stage}.md`, regardless of where the skill is installed (`_bmad/` tree vs. dev checkout). The same defect therefore dedups to the same `fp` across every install. Do not substitute the installed path.
+
+**2. Check the seen-cache via the script:**
+
+```
+uv run {skill-root}/scripts/health_check_fp.py seen --fp {fp} --cache {seenCachePath}
+```
+
+→ `{"seen": true, "record": {...}}` means this user already handled this fingerprint on this machine — skip submission silently and log: `"fp-xxxxxxx: already handled on {record.date}, {record.issue_url} — skipping"`. `{"seen": false, "record": null}` means proceed.
+
+**3. Check GitHub CLI** with `gh auth status`. If it fails, fall through to §5c (offline fallback).
+
+**4. Remote dedup search** — one deterministic call:
+
+```
+gh search issues --repo {healthCheckRepo} --state open "{fp} in:title" --json number,url,title --limit 1
+```
+
+**5a-i. If a matching open issue exists**, present:
+
+> "Matching report found: #{N} — {title}
+>
+> Your finding has the same fingerprint `{fp}`. Options:
+> - **[R]** React (👍) on the existing issue — silent upvote, no comment
+> - **[C]** React + comment with YOUR environment/evidence delta (only if it materially differs)
+> - **[N]** Create a new issue anyway — only if you are certain this is a distinct defect
+> - **[S]** Skip — do not submit this finding"
+
+Execute the choice:
+
+- **R:** `gh api -X POST /repos/{healthCheckRepo}/issues/{N}/reactions -f content='+1'`, then record `reacted`.
+- **C:** the reaction call, then `gh issue comment {N} --body "{minimal env+delta body}"` (the Environment table plus ONE sentence on what differs; no session narrative), then record `commented`.
+- **N:** proceed to §5a-ii.
+- **S:** record nothing.
+
+Record the outcome via the script:
+
+```
+uv run {skill-root}/scripts/health_check_fp.py record --fp {fp} --cache {seenCachePath} \
+  --issue-url {url} --action reacted|commented --date {YYYY-MM-DD}
+```
+
+**5a-ii. If no matching open issue exists** — create one.
+
+**First, ensure the `{fp}` label exists** — it is per-fingerprint, so the first reporter of any defect creates a brand-new label, and `gh issue create --label {fp}` hard-fails if the label is missing. Guard it idempotently:
+
+```
+gh label create "{fp}" --repo {healthCheckRepo} --color "ededed" \
+  --description "Health-check fingerprint dedup key" 2>/dev/null || true
+```
+
+The `|| true` makes it idempotent: if the label already exists, `gh label create` exits non-zero and we proceed unharmed. The other labels (`health-check`, `workflow-improvement`, `bug`/`friction`/`gap`) are pre-created repo labels and need no guard.
+
+**Then create the issue:**
+
+```
+gh issue create --repo {healthCheckRepo} \
+  --title "[health-check][{severity}][{fp}] {workflow}: {short description}" \
+  --label "health-check,workflow-improvement,{severity},{fp}" \
+  --body "{structured body below}"
+```
+
+The `{workflow}` in the title is `ultracode-goal/{stage}`. The `{fp}` appears in both title (human-readable) and label (server-side filterable) so maintainers can query all reports for a defect via the `fp-*` label without parsing title text.
+
+After creation, record the mapping via the script so this user never re-reports the fingerprint:
+
+```
+uv run {skill-root}/scripts/health_check_fp.py record --fp {fp} --cache {seenCachePath} \
+  --issue-url {created-url} --action created --date {YYYY-MM-DD}
+```
+
+**Writing rules — non-negotiable:**
+
+- **One issue per finding.** Two independent problems → two issues.
+- **Respect length budgets.** Finding, Expected, Actual, Impact, Suggested Fix are **each ONE sentence**. Evidence is 2-5 bullets, not prose.
+- **Quote, do not paraphrase.** In Evidence, cite the exact `file:line` with the quoted text in quotes.
+- **Never narrate the session.** The reader wants the defect, not the story. If a sentence starts with "During my run…", delete it.
+- **If unsure it is a real issue, do not submit it.**
+
+**Issue body format:**
+
+```markdown
+## Workflow
+ultracode-goal/{stage}
+
+## Step File
+`skills/ultracode-goal/references/{stage}.md`
+
+## Severity
+`{bug | friction | gap}`
+
+## Fingerprint
+`{fp}`
+
+## Finding
+<!-- ONE sentence: what is the problem? -->
+
+## Expected
+<!-- ONE sentence: what did the stage instruct or imply should happen? -->
+
+## Actual
+<!-- ONE sentence: what did you observe instead? -->
+
+## Evidence
+<!-- 2-5 bulleted `file:line` citations with quoted text. No narrative. -->
+- `skills/ultracode-goal/references/{stage}.md:NN` — "quoted text from the file"
+
+## Impact
+<!-- ONE sentence: what did this cost in THIS run? -->
+
+## Suggested Fix
+<!-- ONE sentence, ONE recommendation. -->
+
+## Environment
+| Field | Value |
+|-------|-------|
+| Date | {ISO date} |
+| OS | {e.g. Ubuntu 24.04, macOS 15.2, Windows 11} |
+| AI Editor | {e.g. Claude Code, Cursor} |
+| Model | {e.g. Claude Opus 4.6, Claude Sonnet 4.6} |
+| Profile | {production \| light} |
+| Run mode | {attended \| headless} |
+| Module Version | {resolved per the order below, else N/A} |
+```
+
+**Module Version resolution order** (first hit wins): `{project-root}/_bmad/ucg/VERSION` → `{skill-root}/VERSION` → `.claude-plugin/marketplace.json` `plugins[0].version` → `package.json` `version` → `N/A`.
+
+After creating all issues, display: "{N} issue(s) created on {healthCheckRepo}:" then each URL, then "Workflow complete."
+
+### 5c. Local queue (gh unavailable, autosubmit-off headless, friction/gap default, or [S])
+
+Findings that did not go live — `gh` unavailable, an unattended run with autosubmit off, the user declined the friction/gap opt-in, or the user chose **[S]** — are written one file per finding to `{workflow.health_check_queue_path}/`.
+
+Even when queuing, **still compute the fingerprint via the script** (so the queue file carries the same `fp`) and **record it** with `--action queued` so a later live submission of the same defect dedups against it:
+
+```
+uv run {skill-root}/scripts/health_check_fp.py record --fp {fp} --cache {seenCachePath} \
+  --issue-url "" --action queued --date {YYYY-MM-DD}
+```
+
+**Filename:** `hc-ultracode-goal-{stage}-{YYYYMMDD-HHmmss}.md`.
+
+**File content:** the same structured body as §5a, prefixed with YAML frontmatter:
+
+```yaml
+---
+type: workflow-health-finding
+workflow: ultracode-goal/{stage}
+step_file: skills/ultracode-goal/references/{stage}.md
+severity: {bug | friction | gap}
+fingerprint: {fp-xxxxxxx}
+date: {ISO date}
+---
+```
+
+When `gh auth status` failed, after writing the files display:
+
+"{N} finding(s) saved locally:" then each path, then:
+
+"GitHub CLI is not available. To submit these as issues, run:
+`gh issue create --repo {healthCheckRepo} --title \"[title]\" --body-file {file-path}`
+
+Or open one at <https://github.com/{healthCheckRepo}/issues/new/choose>
+
+Workflow complete."
+
+In an unattended run, do not display prompts — just write the files, log the count and paths, and return.
+
+## CRITICAL STEP COMPLETION NOTE
+
+This is the **terminal step of Finalize**. After it returns — clean run, findings submitted, queued, or discarded — the ultracode-goal run is **fully done**; there is nothing further to load. **In headless, Finalize emits the final five-key JSON AFTER this step returns** — so this step must never block, prompt, or stall waiting for input, and must never mutate or delay that emit.
+
+## SUCCESS / FAILURE metrics
+
+### SUCCESS
+
+- The enabled gate (§0.5) short-circuits to a one-line exit when `health_check_enabled` is false.
+- Clean runs exit immediately with no findings (the most common outcome).
+- Findings cite a specific stage file and section-slug with real `file:line` evidence.
+- In attended runs the [Y]/[N]/[E] gate is presented before any submission.
+- In headless runs the gate is bypassed deterministically: autosubmit-off queues every finding; autosubmit-on live-submits `bug` only and queues friction/gap.
+- Severity routing respected: only `bug` submits live by default; friction/gap need the explicit per-session opt-in (attended) or autosubmit (headless).
+- Fingerprint and seen-cache are computed/managed by `health_check_fp.py` — never inline shell — and are install-mode-invariant.
+- The `fp-*` label is ensured idempotently (`gh label create … || true`) before `gh issue create`.
+- Remote dedup search runs before every live submission; matches get reactions/delta-comments, not duplicates.
+- Local fallback files carry the fingerprint and clear manual-submission instructions.
+- The run ends cleanly and never blocks the headless JSON emit.
+
+### FAILURE
+
+- Fabricating issues not actually encountered during the run.
+- Reporting vague issues without a stage-file citation ("the workflow was confusing").
+- Skipping the attended review gate, or creating issues without confirmation in an attended run.
+- **Live-publishing an unreviewed friction/gap finding in an unattended run, or blocking the headless JSON emit on the health check.**
+- Creating a new issue when a matching `fp-*` open issue exists, without explicit [N].
+- Computing the fingerprint with inline shell or the installed path instead of the script's install-mode-invariant form.
+- Using LLM-judged "similarity" in place of the deterministic fingerprint.
+- Not recording to the seen-cache, causing the same user to re-report identical fingerprints.
+- Not providing the local fallback when `gh` is unavailable.
+- Continuing to load steps after this one (it is terminal).
+
+**Master rule:** honesty is the only policy. Zero findings is the expected, healthy outcome. Fabricating issues to appear thorough undermines the entire self-improvement system and is a SYSTEM FAILURE.

package/skills/ultracode-goal/references/ingest-and-scope.md

@@ -0,0 +1,46 @@
+# Stage 1 — Ingest & Scope
+
+Resolve **which** Epic this run delivers, locate its BMAD artifacts, lock the profile, and record both to the run's `.decision-log.md`. This is the cheap stage that prevents an expensive autonomous run from targeting the wrong Epic. Converse in `{communication_language}`.
+
+The operator is the expert on intent; you are the expert on what the artifacts say. Open the floor — invite them to name the Epic and drop any context (a story ID, a branch, a paste of the Epic body, "the one we discussed yesterday") — then fill only the gaps from the files. With `--yes`, skip this open-floor invite and resolve scope from the inputs and files directly (the hard preflight gate in Stage 2 still runs). In headless (`-H`), skip the conversation: infer scope from the inputs, log every assumption, never prompt.
+
+## First-touch reality check
+
+Before resolving anything, confirm this is even a BMAD project. If the `_bmad/` config **and** `sprint-status.yaml` **and** any Epic are **all** absent, this does not look like a BMAD project — say so plainly, point at `bmad-bmb-setup` (to scaffold the module) and `bmad-sprint-planning` (to generate the sprint plan), and **stop**. Never carry a wrong-repo invocation into preflight. In headless (`-H`), emit the blocked JSON (per SKILL.md Headless) with `reason` "not a BMAD project". This is the only absence that hard-stops at Stage 1; once any one of the three is present, proceed and let the resolution rules below judge the rest.
+
+## Resolve the Epic and its artifacts
+
+A run targets exactly one Epic, identified by its number/id. Find its artifacts under the resolved config paths (these already contain `{project-root}` — never re-prefix):
+
+- **`sprint-status.yaml`** at `{workflow.implementation_artifacts}/sprint-status.yaml` — the authority on which Epics and stories exist and their status (`backlog` / `in-progress` / `ready-for-dev` / `review` / `done`). This is also the file whose mere presence steers TEA test-design to Epic-Level in Stage 2; note its path now, do not create it here.
+- **Epic + story files** under `{workflow.implementation_artifacts}` (the `story_location` BMAD writes to). Stories for an Epic share its number prefix.
+- **PRD and ADR / architecture** under `{planning_artifacts}` — the product and architecture decisions the Epic implements. Stage 2's semantic scan reads these to detect undecided questions; here you only confirm they exist and cover this Epic.
+
+Resolution order:
+
+1. If the operator named an Epic, take it. Otherwise read `sprint-status.yaml` and pick the obvious in-flight Epic (single `in-progress`, or the next `backlog` after the last `done`). If genuinely ambiguous, list the candidates with their status and ask. Headless: pick the lowest-numbered not-`done` Epic and log the choice plus the rejected candidates.
+2. Confirm the Epic has a body (acceptance-bearing stories or an Epic file). A title-only Epic with no stories is not blocking here — Stage 2 generates missing stories/ACs via `bmad-create-story`. Note it so Stage 2 expects remediation.
+3. **Already-done short-circuit.** If every in-scope story for the resolved Epic is already `done`, do not carry a no-op Epic into preflight: surface "this Epic is already complete — re-run anyway?" and proceed only on a yes. Headless: emit the blocked JSON (per SKILL.md Headless) with `reason` "epic already complete".
+4. If `sprint-status.yaml` is absent or `{planning_artifacts}` has no PRD/ADR for this Epic, that is not a hard stop at this stage — record the gap; Stage 2 preflight reports it mechanically and the semantic scan judges whether the missing planning artifact is a true RED (undecided product/architecture) or a benign absence.
+
+Do not open story or planning files for deep reading here — note their paths so Stage 2 and the TEA stages scan them. Reading them now bloats context ahead of delegation.
+
+## Confirm the profile
+
+Profile defaults to **production** — the full TEA chain (test-design + atdd + automate + test-review + nfr + trace + ci) wired as gates. `--light` downscopes to the trace gate only. Headless is always production unless `--light` was passed explicitly.
+
+Surface the default and let the operator downscope: "Production (full TEA gates) unless you want `--light` (trace gate only)." One soft-gate touch — "Anything else on scope before I preflight?" — then move on. Don't re-derive the profile later; Stages 3 and 5 read what you lock here.
+
+Also note execution mode for the log: **sequential** `/goal` spine (default) or `--parallel` (experimental worktree fan-out). It does not change scope, but the log should carry it so the run is reconstructable after compaction.
+
+## Operator notes
+
+This is the operator's last chance to drop a pre-launch hint before they walk away — "watch the auth flow in story 3", "the payments mock is flaky", "story 5's AC is looser than it reads". This is the capture-don't-interrupt case: record each as a named **Operator notes** entry in `.decision-log.md`, tagged with the story it concerns where one is named, rather than letting it float as loose prose. Execute (Stage 4) reads these and surfaces the relevant note into that story's `bmad-dev-story` / review context, so a hint given now actually reaches the unattended run. There may be none — do not invent them; just leave the channel open.
+
+## Record scope + profile
+
+The run folder holding `.decision-log.md` is this run's workspace and canonical memory; compaction can drop everything else. Append a dated session entry capturing: the chosen Epic (id + title), the resolved artifact paths (`sprint-status.yaml`, Epic/stories, PRD/ADR), the profile and why (default vs. operator override), execution mode, any gaps noted for Stage 2 to remediate, any **Operator notes** captured (tagged by story), and — in headless — every inference made in place of the operator.
+
+## Progression
+
+Proceed to `references/preflight.md` once the decision log records: a single resolved Epic id, the located (or explicitly-noted-missing) `sprint-status.yaml` / Epic-stories / PRD-ADR paths, and the locked profile. If the Epic cannot be resolved to one id, stop and ask (headless: emit the blocked JSON per SKILL.md Headless with `reason` "epic unresolved") — never preflight an ambiguous target.

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

@@ -0,0 +1,100 @@
+# Stage 2 — Preflight (the autonomy gate)
+
+This is the load-bearing gate. After this stage the run goes **unattended**: a sequential `/goal` spine or an experimental `--parallel` worktree fan-out, neither of which takes mid-run human input. So everything that would otherwise stall or ask a question must be resolved **now**, or the run must refuse to launch. The posture is **hard gate with auto-remediation**: the script reports mechanical blockers, this stage clears the remediable ones, you add the semantic judgment the script cannot, and launch happens only when the post-remediation intervention budget is zero. Converse in `{communication_language}`; produced markers/docs use `{document_output_language}`.
+
+## 1. Run the mechanical check
+
+```
+uv run {skill-root}/scripts/preflight_check.py --project-root {project-root} --epic <id> --tea-config {workflow.tea_config_path} --impl-artifacts {workflow.implementation_artifacts} --protected-branch <name> [--protected-branch <name> …]
+```
+
+Qualify the script path with `{skill-root}` (per SKILL.md Conventions a bare `scripts/…` resolves from the skill root, but the conductor runs from the project working directory) so it resolves regardless of cwd. Emit one `--protected-branch <name>` per entry in `{workflow.protected_branches}` (the flag is `action='append'`); without it the check falls back to its hardcoded `main, master` and silently no-ops a `protected_branches` override — the mechanical gate would then fail to flag being on a custom protected branch.
+
+`<id>` is the Epic resolved in Stage 1. The script is **plumbing only** — it parses tool versions, git state, and file existence, and reports TEA config flags. It returns JSON:
+
+```
+{green: bool, budget: int,
+ blockers: [{id, kind, severity, detail, remediable: bool}],
+ checks: {cc_version, goal_ok, workflows_ok, automemory_ok, git_branch, git_clean,
+          framework_present, test_artifacts_dirs, sprint_status_present,
+          project_context_count, tea_flags}}
+```
+
+`budget` is the count of mechanical blockers. The script does **not** decide semantic intervention — that is your job in step 3. Treat `green: true` from the script as *necessary but not sufficient*.
+
+## 2. Auto-remediation pass
+
+Clear each remediable blocker, then **re-run the check** so the budget reflects the fixes. Remediate:
+
+- **Test framework absent** (`framework_present: false`): scaffold it via `bmad-testarch-framework` (Playwright/Cypress per `tea_flags`). ATDD in Stage 3 hard-halts without a configured framework — this must exist before launch.
+- **CI quality pipeline absent** (production profile only): if no CI quality pipeline exists yet, scaffold it via `bmad-testarch-ci` **after** the framework exists — `bmad-testarch-ci` halts if the framework is absent, so the strict order is framework → ci. This is one-time infra (force **Create** mode); the pipeline embeds TEA's coverage thresholds so the gate also lives durably in CI, while the per-epic loop gate remains `gate_eval.py` in Stage 5. Skip under `--light`.
+- **Missing acceptance criteria / story** for an in-scope story: generate via `bmad-create-story` so each story carries clear, testable ACs. TEA atdd and trace both need them; a story without ACs has nothing to trace and will stall.
+- **Test-artifacts dirs absent** (`test_artifacts_dirs` incomplete): pre-create the trace/test-design/test-review output dirs (`{workflow.trace_output_dir}` and its siblings under the TEA `test_artifacts` root) so TEA writes land deterministically and `gate_eval.py` finds them in Stage 5.
+- **`project-context.md` count != 1** (`project_context_count`): ensure exactly **one** `project-context.md` exists (generate via `bmad-generate-project-context` if zero; if multiple, this is ambiguous AI-rules state — resolve to one before launch). `{workflow.persistent_facts}` globs this file; duplicates poison Auto Memory grounding.
+- **`sprint-status.yaml` absent** (`sprint_status_present: false`): ensure it is present (via `bmad-sprint-planning`). Its presence makes TEA test-design **auto-select Epic-Level** and skip its interactive System/Epic mode prompt — without it, Stage 3 stalls on a question no one is there to answer.
+- **TEA mode**: force **Create** mode for every TEA workflow this run. Resume/Validate/Edit are interactive and will halt an unattended run. Set/confirm whatever the TEA config exposes (`tea_execution_mode`) so no workflow resumes a prior session.
+- **Secrets / credentials** a story needs (test env keys, API tokens): **interactive** — prompt **once**, now, and capture them out of git. **Headless** — do not prompt; an unresolvable secret becomes a RED blocker (step 4), never a deferred question.
+
+Log each remediation to `.decision-log.md` as you do it. After remediating, run the script from step 1 again and read the new `budget`.
+
+## 3. Semantic intervention scan (the part the script cannot do)
+
+The script counts mechanical facts; it cannot read a PRD and tell that a product decision is still open, or read an ADR and tell that an architecture choice is unresolved. Do that now. Scan the Epic's stories, PRD, and ADR/architecture (paths noted in Stage 1) for **undecided product or architecture decisions** that an autonomous run would have to *guess*:
+
+- open questions, "TBD" / "TODO: decide" / "to be determined" / "(?)" placeholders on a load-bearing requirement,
+- contradictions between PRD and ADR,
+- acceptance criteria that presuppose a decision no artifact actually makes,
+- a story whose "done" is undefinable from the artifacts.
+
+Any such item is **RED** — it cannot be auto-remediated, because the fix is a human decision, and an unattended run guessing it produces confidently wrong work. A purely cosmetic gap is not RED. Record each RED finding with its source and the exact decision needed.
+
+## 4. Hard gate
+
+**Launch only when ALL hold:**
+
+- post-remediation script `budget == 0` (every mechanical blocker cleared),
+- the semantic scan found **no RED** (no undecided product/architecture, no unresolvable secret),
+- **ultracode** session effort and **Auto Mode** are on (gated to Opus/Sonnet 4.6+; required for unattended xhigh + auto-workflow execution).
+
+If any fails: write the blockers — mechanical and semantic — to `.decision-log.md` with what each needs to clear, and **STOP**. Do not launch a partially-ready run; a single guessed architecture decision corrupts the whole Epic. In **headless**, instead emit the blocked JSON in the canonical five-key shape (every key always present; `report` and `deferred_work` are `null` because the run blocked before producing them):
+
+```json
+{"status": "blocked",
+ "skill": "ultracode-goal",
+ "decision_log": "<path to this run's .decision-log.md>",
+ "report": null,
+ "deferred_work": null,
+ "reason": "<first/most-severe blocker, one line>"}
+```
+
+The log carries the full blocker list.
+
+## 5. Arm the environment (only when the gate passes)
+
+Do these in order; each must be asserted, not assumed:
+
+- **Epic branch.** Create the working branch off `{workflow.epic_branch_prefix}<epic-id>` from a clean tree. Rollback for this run is git (per-story commits, worktree isolation under `--parallel`) — `/rewind` checkpoints miss Bash-driven changes, so the branch is the real undo. If the tree is dirty (`git_clean: false`), resolve before branching.
+- **Hooks.** Idempotently merge the **PreToolUse** guard (`scripts/hooks/guard_pretooluse.py`) and the **Stop** budget hook (`scripts/hooks/budget_stop.py`) into `{project-root}/.claude/settings.local.json` (gitignored, machine-local, honored after the workspace trust dialog). Re-merge every run — do not assume a prior run left them. Then **assert they are active** (present in resolved settings); invariants that live only in memory are context, not enforcement, and memory does not block a `git commit`.
+  - **Inject the hook env from the resolved scalars.** Both hooks read config from env first ("env wins so the conductor can inject per run") and fall back to hardcoded defaults (`main/master`, `25`, `1_500_000`, `ultracode/epic-`) otherwise — so a `customize.toml` override of any of these **silently no-ops at the enforcement layer** unless you pass it through. Set these on the hook commands (in the `settings.local.json` hook `command`, e.g. `KEY=value uv run …`) or in the process env the hooks inherit:
+    - `ULTRACODE_PROTECTED_BRANCHES={workflow.protected_branches}` (comma-separated)
+    - `ULTRACODE_IMPL_ARTIFACTS={workflow.implementation_artifacts}`
+    - `ULTRACODE_MAX_TURNS={workflow.max_turns_per_story}`
+    - `ULTRACODE_TOKEN_BUDGET={workflow.story_token_budget}`
+    - `ULTRACODE_EPIC_BRANCH_PREFIX={workflow.epic_branch_prefix}`
+- **Allowlist.** Pre-populate the tool allowlist with `{workflow.allowlist_commands}` so the unattended run (and any fan-out subagents, which inherit the allowlist) can run tests/lint/build/commit without a permission prompt that no one is there to approve.
+
+### Launch briefing (interactive only)
+
+This is the moment the human leaves the loop. Before the first unattended action — **interactive runs only; headless skips this subsection entirely** — surface a one-screen briefing so the operator decides "should I let go right now?" with eyes open:
+
+- **What is about to run unattended:** the Epic (id + title), in-scope story count, profile (production / `--light`), and the Epic branch (`{workflow.epic_branch_prefix}<epic-id>`).
+- **Worst-case envelope:** up to `story count × {workflow.max_turns_per_story}` turns — a smart default from context already in hand, so a first-timer can calibrate launch-now vs. launch-after-lunch.
+- **The autonomy line:** state plainly — *"from here I will not ask you anything."*
+- **Kill switch:** Ctrl-C, or delete the Epic branch — and note that `/rewind` will not help (its checkpoints miss the Bash-driven changes that make up the run, the same reason the branch is the real undo).
+- **Where to watch:** the run's `.decision-log.md` (prose account); on the sequential spine, `{workflow.implementation_artifacts}/run-status.json` (the machine-readable heartbeat Execute updates as the spine advances); under `--parallel`, watch the workflow progress view (`/workflows`) and its run log instead — the fan-out's worktree agents do not write `run-status.json`.
+
+Then **one soft confirm** to cross the line. With `--yes`, skip the confirm and launch straight through — but **still print the briefing** so the operator has the record. Headless never reaches this subsection.
+
+## Progression
+
+Proceed to `references/define-done.md` only after the gate passed AND the Epic branch, both hooks (asserted active), and the allowlist are in place — all recorded in `.decision-log.md`. If the gate did not pass, the run has stopped here (interactive) or returned blocked JSON (headless); there is no progression.