bmad-module-ultracode-goal 0.3.0 → 0.5.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.3.0",
+      "version": "0.5.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,9 @@
 [![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._
-
-**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 +26,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 +35,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
-
-**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.
+## The Fix
 
-**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.
+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.
 
-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 +57,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 and whether to install the learning material; the skill installs for Claude Code. 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).
-
-See [How It Works](./docs/how-it-works.md) for the full stage-by-stage walkthrough and headless contract.
+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:
 
-## Who Is This For?
+- `--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).
 
-- **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 +90,20 @@ 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:
+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.**
 
-- **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`.
+UCG's closest peer is [bmad-auto](https://github.com/bmad-code-org/bmad-auto) (published under the bmad-code-org org), which makes the opposite architectural bet (a deterministic Python loop driving any CLI from outside the agent). For an honest, side-by-side look at where each one wins, see [UCG vs bmad-auto](https://armelhbobdad.github.io/bmad-module-ultracode-goal/comparison/).
 
 ## 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.

package/docs/architecture.md

@@ -1,89 +1,40 @@
 ---
 title: Architecture
-description: How UltraCode Goal works as a conductor over BMAD, TEA, and Claude Code primitives — the three enforcement layers, file layout, and customization resolution.
+description: "How UltraCode Goal works as a conductor over BMAD, TEA, and Claude Code primitives: the three enforcement layers, file layout, and customization resolution."
 ---
 
-UltraCode Goal is a conductor. It orchestrates the installed BMAD epic toolbox and the TEA gates, composing Claude Code primitives — `/goal`, Auto Mode, Auto Memory, hooks, git/worktree isolation — and replaces none of them. This page covers the conductor model, the three enforcement layers in depth, the file layout, customization resolution, and why the hooks live where they do.
+UltraCode Goal is a conductor. It orchestrates the installed BMAD epic toolbox and the TEA gates, composing Claude Code primitives (`/goal`, Auto Mode, Auto Memory, hooks, git/worktree isolation) and replaces none of them. This page covers the conductor model, the three enforcement layers in depth, the file layout, customization resolution, and why the hooks live where they do.
 
 ## The conductor model
 
 The skill owns no implementation logic of its own for building features or running tests. What it owns is the *order*, the *gates*, and the *enforcement*. It delegates:
 
-- **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`.
-- **TEA gates** — `bmad-testarch-framework`, `-ci`, `-test-design`, `-atdd`, `-automate`, `-test-review`, `-nfr`, `-trace`.
-- **Claude Code primitives** — the `/goal` loop drives execution; Auto Mode and ultracode session effort make the unattended run possible; Auto Memory carries learnings forward; hooks enforce invariants; git branches and worktrees provide isolation and rollback.
+- **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`.
+- **TEA gates**: `bmad-testarch-framework`, `-ci`, `-test-design`, `-atdd`, `-automate`, `-test-review`, `-nfr`, `-trace`.
+- **Claude Code primitives**: the `/goal` loop drives execution; Auto Mode and ultracode session effort make the unattended run possible; Auto Memory carries learnings forward; hooks enforce invariants; git branches and worktrees provide isolation and rollback.
 
 Because it is a conductor, the truth of "is this done" lives in the artifacts its delegates produce, not in the conductor's own reasoning. That is the whole design: the model arranges the work, but a script reads the verdict.
 
-The conductor sits between three sets of things it does not own — the BMAD epic toolbox it orchestrates, the TEA gates it sequences, and the Claude Code primitives it composes:
-
-```mermaid
-flowchart TD
-    UCG["UltraCode Goal conductor - owns order, gates, enforcement"]
-    subgraph toolbox["BMAD epic toolbox"]
-        SP["sprint-planning"]
-        CS["create-story"]
-        DS["dev-story"]
-        CR["code-review"]
-        CC["correct-course"]
-    end
-    subgraph tea["TEA gates"]
-        TD["test-design"]
-        ATDD["atdd"]
-        TR["trace writes gate-decision.json"]
-        NFR["nfr"]
-    end
-    subgraph cc["Claude Code primitives"]
-        GOAL["/goal loop"]
-        AUTO["Auto Mode"]
-        MEM["Auto Memory"]
-        HOOKS["PreToolUse + Stop hooks"]
-        GIT["git branch + worktrees"]
-    end
-    UCG -->|"delegates building"| toolbox
-    UCG -->|"sequences"| tea
-    UCG -->|"composes"| cc
-    classDef accent fill:#6366F1,stroke:#4F46E5,color:#fff
-    class UCG accent
-```
-
 ## The three enforcement layers
 
 These are the module's non-negotiables. Each exists because the documented mechanics make the intuitive shortcut wrong (see [why](why-ultracode-goal.md)).
 
 ### 1. Deterministic gate truth
 
-`scripts/gate_eval.py` reads TEA's `gate-decision.json` and maps its gate status to a routing verdict. It never re-derives TEA's thresholds and never reads the transcript. The `/goal` evaluator that drives execution can only see what the run surfaces — it cannot open the gate file — so it is structurally incapable of being the completion authority. The script is. See the [gate model](gate-model.md) for the full mapping, thresholds, and the fail-closed contract.
-
-The mapping is fixed, and in production two extra signals can only downgrade an `advance`, never lift a lower verdict:
-
-```mermaid
-flowchart TD
-    READ["gate_eval.py reads gate-decision.json"]
-    READ --> ST{"gate_status"}
-    ST -->|"PASS or WAIVED"| ADV["advance"]
-    ST -->|"CONCERNS"| DEF["defer - park to ledger, keep moving"]
-    ST -->|"FAIL"| REL["reloop - correct-course, re-run in budget"]
-    ST -->|"NOT_EVALUATED"| ESC["escalate - stop"]
-    ADV --> PROD{"production profile"}
-    PROD -->|"nfr FAIL, review under 80, Block, or unreadable signal"| REL
-    PROD -->|"both signals read and pass"| ADVOK["advance confirmed"]
-    classDef verdict fill:#4F46E5,stroke:#3730A3,color:#fff
-    class ADV,DEF,REL,ESC,ADVOK verdict
-```
+`scripts/gate_eval.py` reads TEA's `gate-decision.json` and maps its gate status to a routing verdict (`PASS`/`WAIVED` → advance, `CONCERNS` → defer, `FAIL` → reloop, `NOT_EVALUATED` → escalate). It never re-derives TEA's thresholds and never reads the transcript. The `/goal` evaluator that drives execution can only see what the run surfaces, it cannot open the gate file, so it is structurally incapable of being the completion authority. The script is. In production, two extra signals can only downgrade an `advance`, never lift a lower verdict. See the [gate model](gate-model.md) for the full mapping diagram, thresholds, and the fail-closed contract.
 
 ### 2. Hooks as invariants
 
 Two invariants must hold for every commit, and neither can live in memory, which is context the model may or may not weigh:
 
-- **`scripts/hooks/guard_pretooluse.py`** (PreToolUse) — inspects each `git commit`/`git push`. It denies the command on a protected branch, and denies a `git commit` when no tests-ran marker (`<impl-artifacts>/.tests-ran-<story_id>`) exists for the current story. It returns a `deny` decision in the hook JSON and also exits 2 with the reason on stderr so older clients that ignore the JSON still block.
-- **`scripts/hooks/budget_stop.py`** (Stop) — counts turns and accumulated tokens for the current story against `max_turns_per_story` / `story_token_budget`. On overrun it writes an escalation marker and surfaces a message, then **lets the stop proceed**. Its documented limitation: a Stop hook fires only when Claude is already trying to stop, so it cannot interrupt a `/goal` condition mid-turn — the in-condition "stop after N turns" clause and the gate's re-loop budget are the real bounds; this hook is the third, defensive layer.
+- **`scripts/hooks/guard_pretooluse.py`** (PreToolUse): inspects each `git commit`/`git push`. It denies the command on a protected branch, and denies a `git commit` when no tests-ran marker (`<impl-artifacts>/.tests-ran-<story_id>`) exists for the current story. It returns a `deny` decision in the hook JSON and also exits 2 with the reason on stderr so older clients that ignore the JSON still block.
+- **`scripts/hooks/budget_stop.py`** (Stop): counts turns and accumulated tokens for the current story against `max_turns_per_story` / `story_token_budget`. On overrun it writes an escalation marker and surfaces a message, then **lets the stop proceed**. Its documented limitation: a Stop hook fires only when Claude is already trying to stop, so it cannot interrupt a `/goal` condition mid-turn. The in-condition "stop after N turns" clause and the gate's re-loop budget are the real bounds; this hook is the third, defensive layer.
 
-Both hooks read their config from env first (so the conductor injects per-run values) and fall back to hardcoded defaults (`main`/`master`, `25`, `1_500_000`, `ultracode/epic-`). Because of that fallback, a `customize.toml` override **silently no-ops at the enforcement layer** unless the conductor passes it through the hook env — so preflight injects `ULTRACODE_PROTECTED_BRANCHES`, `ULTRACODE_IMPL_ARTIFACTS`, `ULTRACODE_MAX_TURNS`, `ULTRACODE_TOKEN_BUDGET`, and `ULTRACODE_EPIC_BRANCH_PREFIX`.
+Both hooks read their config from env first (so the conductor injects per-run values) and fall back to hardcoded defaults (`main`/`master`, `25`, `1_500_000`, `ultracode/epic-`). Because of that fallback, a `customize.toml` override **silently no-ops at the enforcement layer** unless the conductor passes it through the hook env, so preflight injects `ULTRACODE_PROTECTED_BRANCHES`, `ULTRACODE_IMPL_ARTIFACTS`, `ULTRACODE_MAX_TURNS`, `ULTRACODE_TOKEN_BUDGET`, and `ULTRACODE_EPIC_BRANCH_PREFIX`.
 
 ### 3. Budget enforcement
 
-A runaway story is bounded by three layers in order of authority: the **in-condition** "…or stop after N turns" clause inside the `/goal` condition (the real in-loop bound), the **gate re-loop budget** (a `reloop` that would exceed `max_turns_per_story` or `story_token_budget` becomes `escalate`), and the **Stop hook** as the defensive backstop described above. Rollback is git, not `/rewind` — an Epic branch off a protected branch, one commit per green story, worktree isolation under `--parallel` — because `/rewind` checkpoints miss the Bash-driven changes that make up the run.
+A runaway story is bounded by three layers in order of authority: the **in-condition** "…or stop after N turns" clause inside the `/goal` condition (the real in-loop bound), the **gate re-loop budget** (a `reloop` that would exceed `max_turns_per_story` or `story_token_budget` becomes `escalate`), and the **Stop hook** as the defensive backstop described above. Rollback is git, not `/rewind` (an Epic branch off a protected branch, one commit per green story, worktree isolation under `--parallel`) because `/rewind` checkpoints miss the Bash-driven changes that make up the run.
 
 ## File layout
 
@@ -94,37 +45,50 @@ skills/ultracode-goal/
 ├── SKILL.md                       # Entry point: overview, conventions, run modes,
 │                                  #   non-negotiables, the 6-stage table, headless contract
 ├── customize.toml                 # Config base layer (the [workflow] block)
-├── references/                    # One file per stage, loaded just-in-time
+├── references/                    # Loaded just-in-time
 │   ├── ingest-and-scope.md        #   Stage 1
 │   ├── preflight.md               #   Stage 2 (the autonomy gate)
 │   ├── define-done.md             #   Stage 3
 │   ├── execute.md                 #   Stage 4
 │   ├── gate.md                    #   Stage 5
-│   └── finalize.md                #   Stage 6
+│   ├── finalize.md                #   Stage 6
+│   └── health-check.md            #   Finalize self-improvement reflection
 ├── scripts/                       # Deterministic truth (run via `uv`)
 │   ├── preflight_check.py         #   mechanical preflight facts + blocker budget
 │   ├── gate_eval.py               #   gate status -> verdict (the completion authority)
+│   ├── formalize_check.py         #   readiness kernel behind the /ucg-formalize gate
+│   ├── headless_envelope.py       #   the one five-key headless-envelope adapter
 │   ├── health_check_fp.py         #   health-check fingerprint + seen-cache plumbing
+│   ├── mem_observation.py         #   Cross-Session Recall write path (build/spill/drain)
+│   ├── mem_recall.py              #   Cross-Session Recall read path (latch + filter)
+│   ├── merge_config.py            #   install-time config merge into shared _bmad
+│   ├── merge_customization.py     #   install-time UCG-awareness fragment merge
+│   ├── merge_help_csv.py          #   install-time help-CSV merge
+│   ├── lib/mem_common.py          #   shared Cross-Session Recall primitives
 │   └── hooks/
 │       ├── guard_pretooluse.py    #   commit invariants (PreToolUse)
 │       └── budget_stop.py         #   turn/token budget (Stop)
+├── skills/
+│   └── ucg-formalize/             # Standalone readiness gate
 └── assets/
-    └── execute-epic.workflow.js   # EXPERIMENTAL --parallel worktree fan-out
+    ├── execute-epic.workflow.js   # EXPERIMENTAL --parallel worktree fan-out
+    ├── module.yaml · module-setup.md · module-help.csv   # install metadata
+    └── ucg-awareness/             # shift-left planning customization fragments
 ```
 
-`SKILL.md` carries the routing and the contract; the `references/*.md` stage files carry the procedure and the testable routing conditions; the `scripts/*.py` files carry the deterministic facts the model cannot fudge; the `assets/*.js` workflow is the opt-in experimental execution path. See [how it works](how-it-works.md) for the stages and [parallel mode](parallel-mode.md) for the asset.
+`SKILL.md` carries the routing and the contract; the `references/*.md` files carry each stage's procedure and testable routing conditions; the `scripts/*.py` files carry the deterministic facts the model cannot fudge (the gate, preflight, readiness kernel, hooks, and the install-time/recall plumbing); the `skills/ucg-formalize/` subskill is the standalone readiness gate; and the `assets/` hold the experimental `--parallel` workflow plus install metadata and the planning-customization fragments. See [how it works](how-it-works.md) for the stages and [parallel mode](parallel-mode.md) for the workflow asset.
 
 ## Customization resolution
 
 Configuration resolves in three layers, base → team → user, via `resolve_customization.py`:
 
-1. **Base** — `customize.toml` in the skill root (the shipped `[workflow]` block).
-2. **Team** — `{project-root}/_bmad/custom/ultracode-goal.toml`.
-3. **User** — `{project-root}/_bmad/custom/ultracode-goal.user.toml`.
+1. **Base**: `customize.toml` in the skill root (the shipped `[workflow]` block).
+2. **Team**: `{project-root}/_bmad/custom/ultracode-goal.toml`.
+3. **User**: `{project-root}/_bmad/custom/ultracode-goal.user.toml`.
 
-Merge semantics: **scalars override**, **tables deep-merge**, **arrays append**. At activation the skill runs `resolve_customization.py --skill {skill-root} --key workflow`; if that fails, it resolves the three files itself in the same order. The shipped base layer defines the run's knobs — the TEA/artifact paths (`tea_config_path`, `trace_output_dir`, `implementation_artifacts`, `deferred_work_path`), the git guardrails (`epic_branch_prefix`, `protected_branches`), the budgets (`max_turns_per_story`, `story_token_budget`), the experimental `parallel_max_concurrency`, the `allowlist_commands`, and the `on_epic_complete` hook. Teams and users override without editing the shipped file. Remember that a budget or branch override only reaches the *enforcement* layer because preflight threads it into the hook env (see layer 2 above).
+Merge semantics: **scalars override**, **tables deep-merge**, **arrays append**. At activation the skill runs `resolve_customization.py --skill {skill-root} --key workflow`; if that fails, it resolves the three files itself in the same order. The shipped base layer defines the run's knobs: the TEA/artifact paths (`tea_config_path`, `trace_output_dir`, `implementation_artifacts`, `deferred_work_path`), the git guardrails (`epic_branch_prefix`, `protected_branches`), the budgets (`max_turns_per_story`, `story_token_budget`), the experimental `parallel_max_concurrency`, the `allowlist_commands`, and the `on_epic_complete` hook. Teams and users override without editing the shipped file. Remember that a budget or branch override only reaches the *enforcement* layer because preflight threads it into the hook env (see layer 2 above).
 
-The three TOML layers merge once, but a branch or budget value then travels two ways — the conductor reads it directly, while the hooks only see it if preflight re-injects it as env:
+The three TOML layers merge once, but a branch or budget value then travels two ways: the conductor reads it directly, while the hooks only see it if preflight re-injects it as env:
 
 ```mermaid
 flowchart LR
@@ -142,6 +106,6 @@ flowchart LR
     class WF accent
 ```
 
-## Why the hooks live in settings.local.json (decision D6)
+## Why the hooks live in settings.local.json
 
-The PreToolUse and Stop hooks are auto-merged into `{project-root}/.claude/settings.local.json` — machine-local, gitignored, honored after the workspace trust dialog — not into a committed settings file or memory. The reasoning: these hooks are **enforcement, not context**. A committed hook would impose this module's commit guard on every contributor and every unrelated session in the repo; a hook in memory would not block a commit at all. The machine-local file scopes enforcement to the machine actually running the unattended Epic, and the gitignore keeps it out of shared history. The skill re-merges them every run (idempotently) and asserts they are active before the run goes unattended — it does not assume a prior run left them in place. Because the file is machine-local and executes on your machine, review what is merged; see [SECURITY.md](../SECURITY.md).
+The PreToolUse and Stop hooks are auto-merged into `{project-root}/.claude/settings.local.json` (machine-local, gitignored, honored after the workspace trust dialog), not into a committed settings file or memory. The reasoning: these hooks are **enforcement, not context**. A committed hook would impose this module's commit guard on every contributor and every unrelated session in the repo; a hook in memory would not block a commit at all. The machine-local file scopes enforcement to the machine actually running the unattended Epic, and the gitignore keeps it out of shared history. The skill re-merges them every run (idempotently) and asserts they are active before the run goes unattended; it does not assume a prior run left them in place. Because the file is machine-local and executes on your machine, review what is merged; see [SECURITY.md](../SECURITY.md).