bmad-module-ultracode-goal 0.2.0 → 0.4.0

package/.claude-plugin/marketplace.json

@@ -19,7 +19,7 @@
       "name": "bmad-module-ultracode-goal",
       "source": "./",
       "description": "Supercharges BMAD with Claude Code Goal Mode, Auto Mode, and Auto Memory: autonomous Epic execution to a machine-checked, TEA-gated Definition-of-Done. Execute Epics. Accumulate Knowledge. Deliver Outcomes.",
-      "version": "0.2.0",
+      "version": "0.4.0",
       "author": {
         "name": "Armel"
       },

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-<img src="docs/assets/ucg-logo.svg" alt="UltraCode Goal — six stage nodes orbiting a deterministic gate whose verdict reads PASS" width="190"/>
+<img src="docs/assets/ucg-logo.svg" alt="UltraCode Goal: six stage nodes orbiting a deterministic gate whose verdict reads PASS" width="190"/>
 
 # UltraCode Goal (UCG)
 
@@ -16,11 +16,11 @@
 [![Docs](https://img.shields.io/badge/docs-online-green)](https://armelhbobdad.github.io/bmad-module-ultracode-goal/)
 [![GitHub stars](https://img.shields.io/github/stars/armelhbobdad/bmad-module-ultracode-goal?style=social)](https://github.com/armelhbobdad/bmad-module-ultracode-goal/stargazers)
 
-**Built for [Claude Code](https://www.anthropic.com/claude-code) — and only Claude Code.** UCG composes `/goal`, Auto Mode, Auto Memory, and runtime hooks, which exist nowhere else. Other editors can hold the skill files; the autonomous run itself requires Claude Code.
+**Built for [Claude Code](https://www.anthropic.com/claude-code), and only Claude Code.** UCG composes `/goal`, Auto Mode, Auto Memory, and runtime hooks; the autonomous run itself requires Claude Code.
 
-_UCG is a standalone [BMAD](https://github.com/bmad-code-org/BMAD-METHOD) module that delivers a BMAD Epic end to end without a babysitter. It preflights to a remediated green light, turns acceptance criteria into executable tests with the Test Architect (TEA), and advances a story only when a deterministic script reads `PASS` from TEA's gate artifact — not when the model decides it feels done._
+**What still ships everywhere, and what doesn't.** The shift-left planning customization and the standalone `/ucg-formalize` readiness gate are provider-portable BMAD content that installs on any editor; the install never refuses. What Claude Code adds is the preflight enforcement that fires `/ucg-formalize` automatically at run start. Off Claude Code, `/ucg-formalize` stays a manual, on-demand verdict you invoke yourself, and its readiness verdict plus five-key headless envelope are byte-identical across providers; only the automatic invocation is Claude-Code-only. ([How portability works →](./docs/how-it-works.md#portability-what-installs-everywhere-and-what-claude-code-adds))
 
-**If UCG shipped an epic while you slept, give it a ⭐ — it helps others find this tool.**
+_UCG is a standalone [BMAD](https://github.com/bmad-code-org/BMAD-METHOD) module that delivers a BMAD Epic end to end without a babysitter. It preflights to a remediated green light, turns acceptance criteria into executable tests with the Test Architect (TEA), and advances a story only when a deterministic script reads `PASS` from TEA's gate artifact, not when the model decides it feels done._
 
 </div>
 
@@ -28,7 +28,7 @@ _UCG is a standalone [BMAD](https://github.com/bmad-code-org/BMAD-METHOD) module
 
 ## The Problem
 
-You hand an agent an epic and tell it to "build until done." It runs, it commits, it declares victory. At review time you discover "done" meant "the model felt done." There are four reasons this keeps happening, and each one is a mechanic, not a vibe:
+You hand an agent an epic and tell it to "build until done." It runs, it commits, it declares victory. At review time you discover "done" meant "the model felt done." Four mechanics, not vibes, make that the default:
 
 - **The `/goal` evaluator only sees the transcript.** It cannot open the gate artifact TEA wrote to disk. So the thing deciding completion is reading a story _about_ the work, not the verdict _on_ the work.
 - **A model grading its own output is the fox auditing the henhouse.** Self-assessment is the weakest possible signal for a release gate, and it is exactly the signal you get by default.
@@ -37,13 +37,11 @@ You hand an agent an epic and tell it to "build until done." It runs, it commits
 
 UCG exists because the documented mechanics make the intuitive shortcut wrong.
 
-## Before vs After
+## The Fix
 
-**Before** — you babysit an epic story-by-story, approving each step, or you let an agent run unattended and find out at review time that its definition of "done" was its own opinion of its own work.
+UCG preflights the epic to a remediated green light before anything launches, turns each story's acceptance criteria into red-phase tests with TEA, and advances only when `gate_eval.py` reads `PASS` from TEA's deterministic `gate-decision.json`. Completion is a fact on disk, not a feeling in the transcript.
 
-**After** — the preflight hard-gates the epic to a remediated green light before anything launches. TEA turns each story's acceptance criteria into red-phase tests. The run advances only when `gate_eval.py` reads `PASS` from TEA's deterministic `gate-decision.json`. Completion is a fact on disk, not a feeling in the transcript.
-
-That verdict is a small, real JSON object. Here is the actual output of `gate_eval.py` reading a passing gate file (`--profile light`):
+That verdict is a small, real JSON object; here is the actual output of `gate_eval.py` reading a passing gate file (`--profile light`):
 
 ```json
 {
@@ -61,39 +59,31 @@ That verdict is a small, real JSON object. Here is the actual output of `gate_ev
 }
 ```
 
-The `gate_status` comes straight from TEA's artifact — `gate_eval.py` never re-derives the thresholds; it reads the status as given and maps it to a `verdict` (`PASS`/`WAIVED` → `advance`, `CONCERNS` → `defer`, `FAIL` → `reloop`, `NOT_EVALUATED` → `escalate`). Under `--profile production` the same run additionally ANDs two signals — `nfr_status` and `review_score` populate, and any failure downgrades an otherwise-`advance` verdict to `reloop`. The contract is fail-closed: a missing or unparseable signal counts as a _failing_ one, so prose drift degrades to a conservative re-loop, never a silent false-advance.
+The `gate_status` comes straight from TEA's artifact: `gate_eval.py` never re-derives the thresholds; it reads the status as given and maps it to a `verdict` (`PASS`/`WAIVED` → advance, `CONCERNS` → defer, `FAIL` → reloop, `NOT_EVALUATED` → escalate). Under `--profile production` the same run additionally ANDs two signals: `nfr_status` and `review_score` populate, and any failure downgrades an otherwise-`advance` verdict to `reloop`. The contract is fail-closed: a missing or unparseable signal counts as a _failing_ one, so prose drift degrades to a conservative re-loop, never a silent false-advance.
 
 ## Install
 
-Requires [Claude Code](https://www.anthropic.com/claude-code) (the runtime UCG conducts — see above), [Node.js](https://nodejs.org/) >= 22, [Python](https://www.python.org/) >= 3.10, [uv](https://docs.astral.sh/uv/) (Python package runner), plus `git` and `gh` on PATH.
+Requires [Claude Code](https://www.anthropic.com/claude-code) (the runtime UCG conducts), [Node.js](https://nodejs.org/) >= 22, [Python](https://www.python.org/) >= 3.10, [uv](https://docs.astral.sh/uv/), plus `git` and `gh` on PATH.
 
 ```bash
 npx bmad-module-ultracode-goal install
 ```
 
-You'll be prompted for a project name, your IDEs, and whether to install the learning material.
-
-> **Hook security:** UCG installs `PreToolUse`/`Stop` hooks into your machine-local, gitignored `.claude/settings.local.json` at preflight — never into a committed file. They run zero-dependency Python scripts shipped in the skill. See [SECURITY.md](SECURITY.md) for exactly what they execute and how to remove them.
+You'll be prompted for a project name, your IDEs, and whether to install the learning material. UCG is also available through the Claude plugin marketplace. See [Getting Started](./docs/getting-started.md) for that path.
 
-UCG is also available through the Claude plugin marketplace as an alternative to the npx installer — see [Getting Started](./docs/getting-started.md) for that path.
+> **Hook security:** UCG installs `PreToolUse`/`Stop` hooks into your machine-local, gitignored `.claude/settings.local.json` at preflight, never into a committed file. They run zero-dependency Python scripts shipped in the skill. See [SECURITY.md](SECURITY.md) for exactly what they execute and how to remove them.
 
 ## Quick Start
 
-Invoke the skill in natural language — "run this epic autonomously," "execute this epic," or `ultracode goal`. The conductor ingests the epic, preflights, defines done with TEA, executes, gates, and finalizes. Flags shape the run:
-
-- `--light` — run the **trace gate only** (the production default runs the full TEA gate set).
-- `--parallel` — opt into the **experimental** worktree fan-out instead of the sequential `/goal` spine.
-- `--yes` — skip Stage 1's open-floor invite and the launch confirm. It **never** skips the hard preflight gate.
-- `-H` — headless: run non-interactively and emit the five-key status JSON at every exit point.
-- `--retro` — run the close-out retrospective (interactive runs offer it anyway; headless runs it only when this flag is passed).
+Invoke the skill in natural language: "run this epic autonomously," "execute this epic," or `ultracode goal`. The conductor ingests the epic, preflights, defines done with TEA, executes, gates, and finalizes. Flags shape the run:
 
-See [How It Works](./docs/how-it-works.md) for the full stage-by-stage walkthrough and headless contract.
+- `--light`: run the **trace gate only** (the production default runs the full TEA gate set).
+- `--parallel`: opt into the **experimental** worktree fan-out instead of the sequential `/goal` spine.
+- `--yes`: skip Stage 1's open-floor invite and the launch confirm. It **never** skips the hard preflight gate.
+- `-H`: headless: run non-interactively and emit the five-key status JSON at every exit point.
+- `--retro`: run the close-out retrospective (interactive runs offer it anyway; headless runs it only when this flag is passed).
 
-## Who Is This For?
-
-- **Claude Code users running BMAD Epics** who want unattended delivery backed by a real gate, not an optimistic transcript.
-- **Anyone burned by "the agent said it was done"** and who wants completion decided by a file on disk they can read themselves.
-- **Engineers who want rollback they can trust** — every green story is one git commit on an isolated epic branch, not a `/rewind` checkpoint that misses Bash changes.
+See [How It Works](./docs/how-it-works.md) for the full six-stage walkthrough, routing conditions, and the headless contract.
 
 ## How UCG Compares
 
@@ -102,53 +92,18 @@ A skeptical reader is probably already running one of these. Here is the honest
 |                            | **UltraCode Goal**                                   | Hand-driven `/goal` per story        | Plain Auto Mode                  | CI-only gating                       |
 | -------------------------- | ---------------------------------------------------- | ------------------------------------ | -------------------------------- | ------------------------------------ |
 | Completion authority       | `gate_eval.py` reads TEA's `gate-decision.json`      | you, story by story                  | the model's self-assessment      | CI, but only after the agent stops   |
-| Preflight autonomy gate    | hard-gate to remediated green (intervention budget 0)| ad hoc, per story                    | none                             | none — CI runs post-hoc              |
+| Preflight autonomy gate    | hard-gate to remediated green (intervention budget 0)| ad hoc, per story                    | none                             | none: CI runs post-hoc               |
 | Invariants enforcement     | `PreToolUse` hooks in `settings.local.json`          | your attention                       | prompt text (context, not a gate)| CI checks, after the fact            |
 | Rollback                   | git: epic branch, one commit per green story         | manual                               | `/rewind` (misses Bash changes)  | revert after merge                   |
 | Knowledge capture          | Auto Memory + CLAUDE.md split at Finalize            | none structured                      | none structured                  | none                                 |
 
-The alternatives aren't bad — they solve different problems. **UCG solves exactly one: advancing an epic only when a deterministic script confirms the gate passed, and giving you the verdict JSON to check it yourself.**
-
-## How It Works
-
-UCG runs six stages in order, each routing by the testable conditions stated in its reference file:
-
-1. **Ingest & Scope** — resolve the epic and its artifacts; confirm the profile (production default / `--light`).
-2. **Preflight** — auto-remediate ambers, then hard-gate on red; create the git branch, merge hooks, populate the allowlist.
-3. **Define Done** — TEA test-design plus per-story ATDD turn acceptance criteria into executable, red-phase tests.
-4. **Execute** — the sequential `/goal` spine (default) or the `--parallel` worktree fan-out.
-5. **Gate** — `gate_eval.py` reads TEA's verdict and routes: advance / defer / reloop / escalate.
-6. **Finalize** — Auto Memory capture, optional retrospective, decision-log audit, run report.
-
-The run is a straight line until the gate, which branches — and a `reloop` sends the story back through Execute within budget, while an unresolved blocker stops the run rather than guessing:
-
-```mermaid
-flowchart TD
-    I["Stage 1 Ingest and Scope"] --> P{"Stage 2 Preflight hard gate"}
-    P -->|"red blocker"| STOP["STOP / blocked"]
-    P -->|"budget 0, green"| D["Stage 3 Define Done"]
-    D --> X["Stage 4 Execute"]
-    X --> G{"Stage 5 gate_eval.py reads TEA verdict"}
-    G -->|"advance, PASS or WAIVED"| F["Stage 6 Finalize"]
-    G -->|"defer, CONCERNS"| L["Ledger then advance"]
-    L --> F
-    G -->|"reloop, FAIL or signal downgrade"| X
-    G -->|"escalate, NOT_EVALUATED or budget out"| STOP
-    classDef gate fill:#6366F1,stroke:#4F46E5,color:#fff
-    class P,G gate
-```
-
-Three enforcement layers keep the autonomy honest:
-
-- **Hooks are the invariants** — `PreToolUse` guards (no commit on a protected branch; no commit before tests ran for the story) live in `settings.local.json`, where the runtime enforces them, not in memory.
-- **`gate_eval.py` is the completion truth** — advancement is decided by reading TEA's gate file, never by the conductor's judgment and never by the `/goal` evaluator alone.
-- **The Stop hook plus the turn cap are the budget** — the in-`/goal`-condition turn cap is the primary runaway guard; the `Stop` hook is a defensive third layer that records overruns against `max_turns_per_story` / `story_token_budget`.
+The alternatives aren't bad; they solve different problems. **UCG solves exactly one: advancing an epic only when a deterministic script confirms the gate passed, and giving you the verdict JSON to check it yourself.**
 
 ## Verifying
 
 You don't have to take the gate's word for it. The deterministic pieces ship with a test suite, and you can run the evaluator on a real artifact yourself.
 
-Run the Python suite (72 tests across the preflight, gate, hook, and fingerprint scripts):
+Run the Python suite (318 tests across the preflight, gate, hook, readiness, memory, and customization scripts):
 
 ```bash
 uv run --with pytest pytest skills/ultracode-goal/scripts/tests/ -v
@@ -162,46 +117,29 @@ uv run skills/ultracode-goal/scripts/gate_eval.py \
   --profile light
 ```
 
-The JSON it prints is the same object UCG routes on — `verdict`, `gate_status`, and the `reasons` trail that explains how it got there. Nothing is hidden behind the model.
-
-## Optional: Cross-Session Recall
-
-If you run claude-mem, this executor consults your past runs in this codebase before it scopes a new Epic and before its preflight gate — so it surfaces what bit you here last time instead of starting amnesiac. You stay in the driver's seat; it informs, it doesn't auto-decide.
-
-Optional. Powered by claude-mem if installed; a silent no-op if not. It is advisory only — never in the gate path — and off by default. Enable it in `_bmad/custom/ultracode-goal.toml`:
-
-```toml
-[workflow]
-cross_session_recall = "on"
-```
-
-See [Cross-Session Recall](./docs/cross-session-recall.md) for the touchpoints, the trust model, and the OFF-coherence disclosure.
-
-## Help UCG Improve
-
-Every run that reaches Finalize ends with a self-improvement check. When it finds a defect in its own stage references, it can file a GitHub issue — deduplicated by a deterministic fingerprint so re-reporting is safe — with your approval. Headless runs queue findings to a machine-local cache instead of filing live. The fingerprint is install-mode-invariant, so the same defect maps to the same issue whether it surfaced in a dev checkout or an installed tree. **Please let runs finish through Finalize**, or [open an issue](https://github.com/armelhbobdad/bmad-module-ultracode-goal/issues/new/choose) directly. If UCG saved you an afternoon of babysitting, a ⭐ helps others find it.
+The JSON it prints is the same object UCG routes on: `verdict`, `gate_status`, and the `reasons` trail that explains how it got there. Nothing is hidden behind the model.
 
 ## Learn More
 
-The docs are organized into three buckets — **Why** (start here), **Try** (do stuff), and **Reference** (look things up):
+The docs are organized into three buckets: **Why** (start here), **Try** (do stuff), and **Reference** (look things up):
 
-**Why**
-
-- **[Why UltraCode Goal](./docs/why-ultracode-goal.md)** — the problem, the three enforcement layers, and when not to use it.
+**Why**: **[Why UltraCode Goal](./docs/why-ultracode-goal.md)**: the problem, the three enforcement layers, and when not to use it.
 
 **Try**
 
-- **[Getting Started](./docs/getting-started.md)** — install, prerequisites, the flags, and your first autonomous run.
-- **[How It Works](./docs/how-it-works.md)** — the six stages, their routing conditions, and the headless five-key emit.
-- **[Parallel Mode](./docs/parallel-mode.md)** — the experimental worktree fan-out and its known limits.
+- **[Getting Started](./docs/getting-started.md)**: install, prerequisites, the flags, and your first autonomous run.
+- **[How It Works](./docs/how-it-works.md)**: the six stages, their routing conditions, and the headless five-key emit.
+- **[Parallel Mode](./docs/parallel-mode.md)**: the experimental worktree fan-out and its known limits.
 
 **Reference**
 
-- **[Architecture](./docs/architecture.md)** — the conductor model, enforcement layers in depth, and `customize.toml` resolution.
-- **[Gate Model](./docs/gate-model.md)** — how `gate_eval.py` maps `gate_status` to a verdict, and the production AND-signals.
-- **[Health Check](./docs/health-check.md)** — the terminal self-improvement loop: what it sends, privacy, and how to disable it.
-- **[Cross-Session Recall](./docs/cross-session-recall.md)** — the optional claude-mem integration: touchpoints, trust model, and how to enable it.
-- **[Troubleshooting](./docs/troubleshooting.md)** — real failure modes and their remediations.
+- **[Architecture](./docs/architecture.md)**: the conductor model, enforcement layers in depth, and `customize.toml` resolution.
+- **[Gate Model](./docs/gate-model.md)**: how `gate_eval.py` maps `gate_status` to a verdict, and the production AND-signals.
+- **[Health Check](./docs/health-check.md)**: the terminal self-improvement loop: what it sends, privacy, and how to disable it.
+- **[Cross-Session Recall](./docs/cross-session-recall.md)**: the optional claude-mem integration: touchpoints, trust model, and how to enable it.
+- **[Troubleshooting](./docs/troubleshooting.md)**: real failure modes and their remediations.
+
+Every run that reaches Finalize ends with a self-improvement check that can file a deduplicated GitHub issue with your approval, so **please let runs finish through Finalize**, or [open an issue](https://github.com/armelhbobdad/bmad-module-ultracode-goal/issues/new/choose) directly. If UCG shipped an epic while you slept, a ⭐ helps others find it.
 
 ## Acknowledgements
 
@@ -210,23 +148,17 @@ UCG is a conductor over primitives it does not replace. It builds on:
 | Tool                                                                   | Role in UCG                                                                    |
 | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
 | [BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD)            | The epic toolbox UCG orchestrates (sprint planning, story creation, dev, review) |
-| [TEA Test Architect](https://github.com/bmad-code-org/BMAD-METHOD)     | Machine-checked quality gates — test-design, ATDD, NFR, trace; the gate artifact |
-| [Claude Code](https://www.anthropic.com/claude-code)                   | `/goal`, Auto Mode, Auto Memory, hooks, and git worktrees — the primitives UCG composes |
+| [TEA Test Architect](https://github.com/bmad-code-org/BMAD-METHOD)     | Machine-checked quality gates: test-design, ATDD, NFR, trace; the gate artifact |
+| [Claude Code](https://www.anthropic.com/claude-code)                   | `/goal`, Auto Mode, Auto Memory, hooks, and git worktrees, the primitives UCG composes |
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
-
-## Changelog
-
-Past releases are documented in [CHANGELOG.md](CHANGELOG.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. Past releases are documented in [CHANGELOG.md](CHANGELOG.md), and [CONTRIBUTORS.md](CONTRIBUTORS.md) lists contributors.
 
 ## License
 
-MIT License — see [LICENSE](LICENSE) for details.
+MIT License. See [LICENSE](LICENSE) for details.
 
 ---
 
-**UltraCode Goal (UCG)** — A standalone [BMAD](https://github.com/bmad-code-org/BMAD-METHOD) module for autonomous epic delivery.
-
-See [CONTRIBUTORS.md](CONTRIBUTORS.md) for contributor information.
+**UltraCode Goal (UCG)**: A standalone [BMAD](https://github.com/bmad-code-org/BMAD-METHOD) module for autonomous epic delivery.

package/docs/404.md

@@ -1,23 +1,23 @@
 ---
 title: Page Not Found
-description: That URL did not resolve. A path the docs cannot verify does not pass — use the search or the cited links below to continue.
+description: That URL did not resolve. A path the docs cannot verify does not pass; use the search or the cited links below to continue.
 template: splash
 ---
 
-## 404 — this URL does not pass
+## 404: this URL does not pass
 
-No page resolves to that address. In the spirit of the rest of this project, a claim that cannot be verified does not get to advance — and that includes a URL the docs site made to itself.
+No page resolves to that address. In the spirit of the rest of this project, a claim that cannot be verified does not get to advance, and that includes a URL the docs site made to itself.
 
 Use the **search bar** at the top of the page, or jump to one of these pages that *do* resolve, grouped the way the sidebar groups them:
 
-**Why** — [Why UltraCode Goal](./why-ultracode-goal.md)
+**Why**: [Why UltraCode Goal](./why-ultracode-goal.md)
 
-**Try** — [Getting Started](./getting-started.md) · [How It Works](./how-it-works.md) · [Parallel Mode](./parallel-mode.md)
+**Try**: [Getting Started](./getting-started.md) · [How It Works](./how-it-works.md) · [Parallel Mode](./parallel-mode.md)
 
-**Reference** — [Architecture](./architecture.md) · [Gate Model](./gate-model.md) · [Health Check](./health-check.md) · [Troubleshooting](./troubleshooting.md)
+**Reference**: [Architecture](./architecture.md) · [Gate Model](./gate-model.md) · [Health Check](./health-check.md) · [Troubleshooting](./troubleshooting.md)
 
 ---
 
 ### Think this page should exist?
 
-A missing page is drift — a link the docs made to themselves that no longer reads green. [Open an issue](https://github.com/armelhbobdad/bmad-module-ultracode-goal/issues/new/choose) with the URL you tried. The same instinct that makes UltraCode Goal re-loop on a failing gate applies here: if a broken path slipped through, it is a defect worth reporting.
+A missing page is drift: a link the docs made to themselves that no longer reads green. [Open an issue](https://github.com/armelhbobdad/bmad-module-ultracode-goal/issues/new/choose) with the URL you tried. The same instinct that makes UltraCode Goal re-loop on a failing gate applies here: if a broken path slipped through, it is a defect worth reporting.

package/docs/_internal/RELEASING.md

@@ -3,14 +3,14 @@ title: Releasing
 description: Maintainer runbook for cutting an UltraCode Goal release via the manual-dispatch, OIDC trusted-publishing release.yaml workflow.
 ---
 
-Maintainer runbook for cutting a release of `bmad-module-ultracode-goal`. The canonical release path is [`.github/workflows/release.yaml`](../../.github/workflows/release.yaml) — manual dispatch, OIDC trusted publishing, no token secrets.
+Maintainer runbook for cutting a release of `bmad-module-ultracode-goal`. The canonical release path is [`.github/workflows/release.yaml`](../../.github/workflows/release.yaml): manual dispatch, OIDC trusted publishing, no token secrets.
 
 ## How a release works
 
 Dispatching `release.yaml` from `main` runs, in order:
 
 1. Quality gate (`npm test`) on the release runner.
-2. Version bump (`npm version` — `alpha`/`beta`/`rc` prerelease or `patch`/`minor`/`major`).
+2. Version bump (`npm version`: `alpha`/`beta`/`rc` prerelease or `patch`/`minor`/`major`).
 3. Sync `.claude-plugin/marketplace.json` `.plugins[0].version` to the new version (atomic jq edit).
 4. CHANGELOG update via `conventional-changelog-cli`, preamble restored to Keep-a-Changelog shape.
 5. Pre-publish `npm publish --dry-run` (catches package validation failures before anything is pushed).
@@ -83,10 +83,10 @@ Create an Environment named `release` with `armelhbobdad` as a required reviewer
 On [npmjs.com](https://www.npmjs.com/) → package settings → Trusted Publisher, register:
 
 - Repository: `armelhbobdad/bmad-module-ultracode-goal`
-- Workflow filename: `release.yaml` (character-for-character — renaming the file breaks publishing)
+- Workflow filename: `release.yaml` (character-for-character: renaming the file breaks publishing)
 - Environment: `release`
 
-The workflow upgrades npm to ≥ 11.5.1 (the OIDC trusted-publishing floor) and pins `NPM_TOKEN: ""` on both publish steps so a stale runner-env token can never be picked up silently. Note: the very first publish of a brand-new package may need to be performed manually (`npm publish` with a granular token) before Trusted Publisher can be attached to the package — check current npm rules when cutting `0.1.0`.
+The workflow upgrades npm to ≥ 11.5.1 (the OIDC trusted-publishing floor) and pins `NPM_TOKEN: ""` on both publish steps so a stale runner-env token can never be picked up silently. Note: the very first publish of a brand-new package may need to be performed manually (`npm publish` with a granular token) before Trusted Publisher can be attached to the package. Check current npm rules when cutting `0.1.0`.
 
 ### 5. Repo settings: auto-merge + Actions PR creation
 
@@ -96,7 +96,7 @@ gh api --method PUT /repos/armelhbobdad/bmad-module-ultracode-goal/actions/permi
   -f default_workflow_permissions=read -F can_approve_pull_request_reviews=true
 ```
 
-Without `allow_auto_merge`, `gh pr merge --auto` in the workflow fails. Without `can_approve_pull_request_reviews` ("Allow GitHub Actions to create and approve pull requests" in Settings → Actions → General — **off by default**), the `Open bot PR` step fails with `GraphQL: GitHub Actions is not permitted to create or approve pull requests`. The workflow-level `permissions: pull-requests: write` declaration is necessary but NOT sufficient — this repo-level toggle gates it independently.
+Without `allow_auto_merge`, `gh pr merge --auto` in the workflow fails. Without `can_approve_pull_request_reviews` ("Allow GitHub Actions to create and approve pull requests" in Settings → Actions → General, **off by default**), the `Open bot PR` step fails with `GraphQL: GitHub Actions is not permitted to create or approve pull requests`. The workflow-level `permissions: pull-requests: write` declaration is necessary but NOT sufficient; this repo-level toggle gates it independently.
 
 ### 6. Health-check labels
 
@@ -110,21 +110,21 @@ done
 
 ## Version-coupling invariant
 
-`package.json` `version` and `.claude-plugin/marketplace.json` `.plugins[0].version` must always be equal. The release workflow enforces this at release time (step 3); between releases, keep them equal by hand — `npm run test:install` asserts the coupling and fails the quality gate on drift.
+`package.json` `version` and `.claude-plugin/marketplace.json` `.plugins[0].version` must always be equal. The release workflow enforces this at release time (step 3); between releases, keep them equal by hand. `npm run test:install` asserts the coupling and fails the quality gate on drift.
 
 ## Cutting a release
 
 1. Confirm `main` is green and the working tree state you want to ship is merged.
-2. Actions → Release → Run workflow → choose the bump type. Prefer an `alpha` for the first cut after any pipeline change — it exercises the full path with a low-stakes version.
+2. Actions → Release → Run workflow → choose the bump type. Prefer an `alpha` for the first cut after any pipeline change; it exercises the full path with a low-stakes version.
 3. Approve the `release` environment run when prompted.
 4. Approve (or admin-merge) the bot PR when checks are green.
-5. After publish, dispatch `install-smoke.yaml` with the new version — it verifies `npx bmad-module-ultracode-goal@<version> --version` on ubuntu/windows/macos.
+5. After publish, dispatch `install-smoke.yaml` with the new version; it verifies `npx bmad-module-ultracode-goal@<version> --version` on ubuntu/windows/macos.
 
 ## Rollback playbook
 
 npm unpublish is heavily restricted; prefer forward fixes.
 
-- **Bad publish, caught quickly:** `npm deprecate bmad-module-ultracode-goal@X.Y.Z "broken — use X.Y.Z+1"`, then cut a patch release.
+- **Bad publish, caught quickly:** `npm deprecate bmad-module-ultracode-goal@X.Y.Z "broken: use X.Y.Z+1"`, then cut a patch release.
 - **Bad prerelease tag:** point the dist-tag back: `npm dist-tag add bmad-module-ultracode-goal@<good> alpha`.
 - **Bad git tag (not yet published):** delete the tag (`git push origin :refs/tags/vX.Y.Z`) and the bot PR/branch, then re-dispatch.
-- **Workflow died mid-flow:** the PR (if opened) is left open by design for inspection. Close it, delete the temp branch, fix the cause, re-dispatch — the `run_id`-suffixed branch name prevents collisions on retry.
+- **Workflow died mid-flow:** the PR (if opened) is left open by design for inspection. Close it, delete the temp branch, fix the cause, re-dispatch; the `run_id`-suffixed branch name prevents collisions on retry.

package/docs/_internal/STABILITY.md

@@ -1,9 +1,9 @@
 ---
 title: Stability and Public Contract
-description: The 0.1.0 stability posture — which CLI, config, JSON, and gate surfaces are the supported public contract versus everything that is @internal and free to change.
+description: "The 0.1.0 stability posture: which CLI, config, JSON, and gate surfaces are the supported public contract versus everything that is @internal and free to change."
 ---
 
-> **Status:** 0.x — pre-1.0. The surfaces below are the intended public contract at `0.1.0`. Per [Semantic Versioning 2.0.0](https://semver.org/), a `0.x` series makes no stability guarantee across minor versions; this document records what we *try* to hold stable and what is explicitly `@internal`, so a consumer knows which surfaces to pin against and which to treat as free to change.
+> **Status:** 0.x, pre-1.0. The surfaces below are the intended public contract at `0.1.0`. Per [Semantic Versioning 2.0.0](https://semver.org/), a `0.x` series makes no stability guarantee across minor versions; this document records what we *try* to hold stable and what is explicitly `@internal`, so a consumer knows which surfaces to pin against and which to treat as free to change.
 
 This is the stability posture for `bmad-module-ultracode-goal` at `0.1.0`. It enumerates the surfaces a downstream consumer or automator may reasonably depend on, versus everything else, which is `@internal`.
 
@@ -20,7 +20,7 @@ The installer CLI is invoked via `npx bmad-module-ultracode-goal <subcommand>`.
 
 ### The `[workflow]` customize.toml keys
 
-The keys in the shipped `[workflow]` block of `customize.toml` — including `persistent_facts`, `tea_config_path`, `trace_output_dir`, `implementation_artifacts`, `deferred_work_path`, `epic_branch_prefix`, `protected_branches`, `max_turns_per_story`, `story_token_budget`, `parallel_max_concurrency`, `allowlist_commands`, and `on_epic_complete` — are the supported override surface. Teams and users override them in `_bmad/custom/ultracode-goal.toml` (and `.user.toml`) with base → team → user resolution (scalars override, tables deep-merge, arrays append). Renaming or removing a key, or changing how it resolves, is a contract change. See [architecture](../architecture.md).
+The keys in the shipped `[workflow]` block of `customize.toml` (including `persistent_facts`, `tea_config_path`, `trace_output_dir`, `implementation_artifacts`, `deferred_work_path`, `epic_branch_prefix`, `protected_branches`, `max_turns_per_story`, `story_token_budget`, `parallel_max_concurrency`, `allowlist_commands`, and `on_epic_complete`) are the supported override surface. Teams and users override them in `_bmad/custom/ultracode-goal.toml` (and `.user.toml`) with base → team → user resolution (scalars override, tables deep-merge, arrays append). Renaming or removing a key, or changing how it resolves, is a contract change. See [architecture](../architecture.md).
 
 ### The headless five-key JSON emit shape
 
@@ -39,7 +39,7 @@ An automator parses this one schema regardless of where the run stopped. Changin
 
 ### The skill name and invocation phrases
 
-The skill name `ultracode-goal` and its documented invocation phrases — "run an epic autonomously", "execute this epic", "ultracode goal", "autonomously deliver the epic" — are part of the contract. Removing or renaming the skill, or dropping a documented trigger phrase, is a contract change.
+The skill name `ultracode-goal` and its documented invocation phrases ("run an epic autonomously", "execute this epic", "ultracode goal", "autonomously deliver the epic") are part of the contract. Removing or renaming the skill, or dropping a documented trigger phrase, is a contract change.
 
 ### gate_eval.py CLI and verdict vocabulary
 
@@ -63,16 +63,16 @@ flowchart LR
 
 The printed JSON object's key set (`verdict`, `gate_status`, `p0_status`, `p1_status`, `overall_status`, `nfr_status`, `review_score`, `reasons`) is the consumable shape; the human-readable `reasons` strings are not contractual wording.
 
-## @internal — not covered
+## @internal: not covered
 
 Everything not enumerated above is `@internal` and may change in any `0.x` release without a deprecation note. Do not pin against:
 
-- **Installer library internals** — the implementation behind the CLI subcommands; what is covered is the observable subcommand surface, not how the files get placed.
-- **Reference file structure** — the `references/*.md` stage files' internal structure, step ordering, prose, and section headings. The stage *names* are referenced by the health-check fingerprint (see below) but the file contents are an authoring surface.
-- **Script internals** — the internal functions, regexes, and intermediate behavior of `preflight_check.py`, `gate_eval.py`, `health_check_fp.py`, and the hook scripts. The covered surface is `gate_eval.py`'s CLI and verdict vocabulary above; everything else (the `preflight_check.py` JSON shape, the fingerprint tuple format, the hook env-var names) is internal and may change.
-- **The experimental `--parallel` workflow** — `assets/execute-epic.workflow.js`, the `/ultracode-goal-execute` registration, its args binding, its return shape, and `parallel_max_concurrency`'s runtime behavior are explicitly experimental and excluded from the contract. See [parallel mode](../parallel-mode.md).
-- **`_bmad-output/` artifact layout** — run folders, the decision log, `run-report.md`, `run-status.json`, the deferred-work ledger, and the improvement queue are run outputs, not a downstream-consumable schema. The headless emit shape (covered above) is the supported way to locate these paths programmatically.
+- **Installer library internals**: the implementation behind the CLI subcommands; what is covered is the observable subcommand surface, not how the files get placed.
+- **Reference file structure**: the `references/*.md` stage files' internal structure, step ordering, prose, and section headings. The stage *names* are referenced by the health-check fingerprint (see below) but the file contents are an authoring surface.
+- **Script internals**: the internal functions, regexes, and intermediate behavior of `preflight_check.py`, `gate_eval.py`, `health_check_fp.py`, and the hook scripts. The covered surface is `gate_eval.py`'s CLI and verdict vocabulary above; everything else (the `preflight_check.py` JSON shape, the fingerprint tuple format, the hook env-var names) is internal and may change.
+- **The experimental `--parallel` workflow**: `assets/execute-epic.workflow.js`, the `/ultracode-goal-execute` registration, its args binding, its return shape, and `parallel_max_concurrency`'s runtime behavior are explicitly experimental and excluded from the contract. See [parallel mode](../parallel-mode.md).
+- **`_bmad-output/` artifact layout**: run folders, the decision log, `run-report.md`, `run-status.json`, the deferred-work ledger, and the improvement queue are run outputs, not a downstream-consumable schema. The headless emit shape (covered above) is the supported way to locate these paths programmatically.
 
 ## SemVer note
 
-This is a `0.x` module: **minor versions may break.** We try to hold the surfaces in [Public contract at 0.1.0](#public-contract-at-010) stable, and the two surfaces an automator is most likely to encode against — the **headless five-key JSON emit shape** and the **`[workflow]` customize.toml keys** — get a deprecation note in `CHANGELOG.md` before changing. `@internal` surfaces change freely. Once the module reaches `1.0.0`, this document is superseded by a full SemVer contract.
+This is a `0.x` module: **minor versions may break.** We try to hold the surfaces in [Public contract at 0.1.0](#public-contract-at-010) stable, and the two surfaces an automator is most likely to encode against, the **headless five-key JSON emit shape** and the **`[workflow]` customize.toml keys**, get a deprecation note in `CHANGELOG.md` before changing. `@internal` surfaces change freely. Once the module reaches `1.0.0`, this document is superseded by a full SemVer contract.