bmad-module-ultracode-goal 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "bmad-module-ultracode-goal",
+  "owner": { "name": "Armel" },
+  "license": "MIT",
+  "homepage": "https://github.com/armelhbobdad/bmad-module-ultracode-goal",
+  "repository": "https://github.com/armelhbobdad/bmad-module-ultracode-goal",
+  "keywords": ["bmad", "claude-code", "goal-mode", "autonomous-delivery", "test-architect", "quality-gates"],
+  "plugins": [
+    {
+      "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.1.0",
+      "author": { "name": "Armel" },
+      "skills": [
+        "./skills/ultracode-goal"
+      ]
+    }
+  ]
+}

package/.gitattributes

@@ -0,0 +1,16 @@
+# Normalize all text files to LF in the repo and on checkout, regardless of
+# the contributor's platform or core.autocrlf setting. UCG runs on Linux,
+# macOS, and Windows (Git Bash / WSL2); LF-everywhere keeps prettier
+# clean and avoids spurious diffs from line-ending churn.
+* text=auto eol=lf
+
+# Binary blobs — never touch.
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.pdf binary
+*.zip binary
+*.gz binary
+*.tgz binary

package/.nvmrc

@@ -0,0 +1 @@
+22

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 Armel (armelhbobdad)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+TRADEMARK NOTICE:
+BMad™ , BMAD-CORE™ and BMAD-METHOD™ are trademarks of BMad Code, LLC. The use of these
+trademarks in this software does not grant any rights to use the trademarks
+for any other purpose.
+

package/README.md

@@ -0,0 +1,200 @@
+<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"/>
+
+# UltraCode Goal (UCG)
+
+**Run a BMAD Epic autonomously to a machine-checked Definition-of-Done.**
+
+[![Requires Claude Code](https://img.shields.io/badge/requires-Claude%20Code-D97757?logo=claude&logoColor=white)](https://www.anthropic.com/claude-code)
+[![Quality & Validation](https://github.com/armelhbobdad/bmad-module-ultracode-goal/actions/workflows/quality.yaml/badge.svg)](https://github.com/armelhbobdad/bmad-module-ultracode-goal/actions/workflows/quality.yaml)
+[![npm](https://img.shields.io/npm/v/bmad-module-ultracode-goal)](https://www.npmjs.com/package/bmad-module-ultracode-goal)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![BMAD Module](https://img.shields.io/badge/BMAD-module-blue)](https://github.com/bmad-code-org/BMAD-METHOD)
+[![Python Version](https://img.shields.io/badge/python-%3E%3D3.10-blue?logo=python&logoColor=white)](https://www.python.org)
+[![uv](https://img.shields.io/badge/uv-package%20manager-blueviolet?logo=uv)](https://docs.astral.sh/uv/)
+[![Docs](https://img.shields.io/badge/docs-online-green)](./docs/index.md)
+[![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.
+
+_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.**
+
+</div>
+
+---
+
+## 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:
+
+- **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.
+- **`/rewind` checkpoints miss Bash changes.** Rollback you cannot trust is rollback you do not have.
+- **Memory is context, not enforcement.** Telling the agent "never commit on `main`" in a prompt is a suggestion. An invariant has to be a hook the runtime _executes_, or it is not an invariant.
+
+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.
+
+**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`):
+
+```json
+{
+  "verdict": "advance",
+  "gate_status": "PASS",
+  "p0_status": "100%",
+  "p1_status": "95%",
+  "overall_status": "88%",
+  "nfr_status": null,
+  "review_score": null,
+  "reasons": [
+    "gate read from gate-decision.json",
+    "gate_status PASS -> 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.
+
+```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.
+
+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.
+
+## 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.
+
+## 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.
+
+## How UCG Compares
+
+A skeptical reader is probably already running one of these. Here is the honest contrast:
+
+|                            | **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              |
+| 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.
+
+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`.
+
+## 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):
+
+```bash
+uv run --with pytest pytest skills/ultracode-goal/scripts/tests/ -v
+```
+
+Then inspect any `gate-decision.json` TEA wrote and evaluate it directly:
+
+```bash
+uv run skills/ultracode-goal/scripts/gate_eval.py \
+  --trace-output path/to/traceability \
+  --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.
+
+## 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.
+
+## Learn More
+
+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.
+
+**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.
+
+**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.
+- **[Troubleshooting](./docs/troubleshooting.md)** — real failure modes and their remediations.
+
+## Acknowledgements
+
+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 |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## Changelog
+
+Past releases are documented in [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+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.

package/docs/_internal/RELEASING.md

@@ -0,0 +1,101 @@
+# Releasing
+
+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`).
+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).
+6. **PR-auto-merge flow**: the release commit is pushed to a temp branch `release/bot/vX.Y.Z-<run_id>`, a bot PR is opened against `main`, `quality.yaml` is force-dispatched against the temp branch (PR events from `GITHUB_TOKEN` do not fire workflows), the workflow waits for all required status checks, then for maintainer approval (or an admin bypass-merge), then auto-merges with a merge commit.
+7. Tag `vX.Y.Z` anchored on the merge commit.
+8. `npm publish` via OIDC trusted publishing (provenance auto-attached).
+9. GitHub Release created from generated notes.
+
+Dispatching from a non-`main` ref skips the PR flow: the tag anchors on the CI-ephemeral commit and `main` is not advanced. This is the expected path for prerelease cuts from feature branches.
+
+## One-time setup
+
+These must exist before the first `main`-dispatch release. Order matters.
+
+### 1. Required-check contexts must exist
+
+Branch-protection rulesets can only require status checks that have reported at least once. Open any PR (or dispatch `quality.yaml` manually) so these seven contexts exist:
+
+```text
+prettier
+eslint
+markdownlint
+validate (ubuntu-latest)
+validate (windows-latest)
+python (ubuntu-latest)
+python (windows-latest)
+```
+
+### 2. Main-branch ruleset
+
+Create a ruleset on `main` requiring the seven contexts above, with `bypass_actors` = Admin RepositoryRole, `bypass_mode: pull_request`. Then record its id in the repo variable the workflow reads:
+
+```bash
+gh api /repos/armelhbobdad/bmad-module-ultracode-goal/rulesets --jq '.[] | {id, name}'
+gh variable set RELEASE_RULESET_ID --body "<id>"
+```
+
+The wait-for-checks step fetches the required-context list from this ruleset at run time, so the workflow can never drift from branch protection. It fails fast with a setup hint if the variable is unset.
+
+### 3. `release` GitHub Environment
+
+Create an Environment named `release` with `armelhbobdad` as a required reviewer. `github-actions[bot]` cannot self-approve; every release run pauses for this approval before any step executes.
+
+### 4. npm Trusted Publisher
+
+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)
+- 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`.
+
+### 5. Auto-merge repo setting
+
+```bash
+gh api --method PATCH /repos/armelhbobdad/bmad-module-ultracode-goal -f allow_auto_merge=true
+```
+
+Without it, `gh pr merge --auto` in the workflow fails.
+
+### 6. Health-check labels
+
+The health-check loop's `gh issue create` hard-fails on missing labels (only the per-fingerprint `fp-*` label is guarded with `|| true`). Pre-create the fixed set:
+
+```bash
+for L in "health-check:0E8A16" "workflow-improvement:1D76DB" "bug:D73A4A" "friction:FBCA04" "gap:C5DEF5" "duplicate:CFD3D7"; do
+  gh label create "${L%%:*}" --repo armelhbobdad/bmad-module-ultracode-goal --color "${L##*:}" 2>/dev/null || true
+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.
+
+## 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.
+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.
+
+## 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 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.

package/docs/_internal/STABILITY.md

@@ -0,0 +1,62 @@
+# Stability and Public Contract
+
+> **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`.
+
+## Public contract at 0.1.0
+
+The following surfaces are the intended public contract. We aim not to break them within the `0.x` series without a deprecation note; see [SemVer note](#semver-note).
+
+### CLI command surface
+
+The installer CLI is invoked via `npx bmad-module-ultracode-goal <subcommand>`. Covered:
+
+- **Subcommands**: `install`, `update`, `status`, `uninstall`. Renaming, removing, or changing the semantics of any subcommand is a contract change.
+- **Options**: `-V` / `--version` (prints the installed package version) and `-h` / `--help` (top-level and per-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 headless five-key JSON emit shape
+
+Every headless (`-H`) exit point emits one object with exactly these five keys, always present, `null` when an artifact was not produced, `reason` carrying a one-line cause only when blocked:
+
+```json
+{"status": "complete|blocked",
+ "skill": "ultracode-goal",
+ "decision_log": "<path>",
+ "report": "<path or null>",
+ "deferred_work": "<path or null>",
+ "reason": "<one line when blocked, else null>"}
+```
+
+An automator parses this one schema regardless of where the run stopped. Changing a key name, adding or removing a key, or changing the `null`-when-absent guarantee is a contract change.
+
+### 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.
+
+### gate_eval.py CLI and verdict vocabulary
+
+`scripts/gate_eval.py` is the deterministic completion authority. Covered:
+
+- **CLI flags**: `--trace-output` (required), `--profile` (`light` | `production`, required), `--nfr`, `--test-review` (production only).
+- **Verdict vocabulary**: the `verdict` values `advance` / `defer` / `reloop` / `escalate`, and the `gate_status` values `PASS` / `CONCERNS` / `FAIL` / `WAIVED` / `NOT_EVALUATED`, plus the mapping between them. See the [gate model](../gate-model.md).
+
+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
+
+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.
+
+## 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.

package/docs/architecture.md

@@ -0,0 +1,77 @@
+# Architecture
+
+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.
+
+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 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.
+
+### 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.
+
+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.
+
+## File layout
+
+The skill routes from a thin entry point down to just-in-time stage files, deterministic scripts, and an experimental asset:
+
+```
+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
+│   ├── 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
+├── scripts/                       # Deterministic truth (run via `uv`)
+│   ├── preflight_check.py         #   mechanical preflight facts + blocker budget
+│   ├── gate_eval.py               #   gate status -> verdict (the completion authority)
+│   ├── health_check_fp.py         #   health-check fingerprint + seen-cache plumbing
+│   └── hooks/
+│       ├── guard_pretooluse.py    #   commit invariants (PreToolUse)
+│       └── budget_stop.py         #   turn/token budget (Stop)
+└── assets/
+    └── execute-epic.workflow.js   # EXPERIMENTAL --parallel worktree fan-out
+```
+
+`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.
+
+## 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`.
+
+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).
+
+## Why the hooks live in settings.local.json (decision D6)
+
+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).

package/docs/assets/ucg-logo.svg

@@ -0,0 +1,73 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 480 480" width="480" height="480" role="img" aria-labelledby="ucgTitle ucgDesc">
+  <title id="ucgTitle">UltraCode Goal</title>
+  <desc id="ucgDesc">Six stage nodes orbit a hexagonal gate; an autonomous conductor circles them, and the centre verdict reads PASS.</desc>
+  <defs>
+    <linearGradient id="gateGrad" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#6366F1"/>
+      <stop offset="1" stop-color="#4F46E5"/>
+    </linearGradient>
+    <radialGradient id="glow" cx="0.5" cy="0.5" r="0.5">
+      <stop offset="0" stop-color="#6366F1" stop-opacity="0.16"/>
+      <stop offset="1" stop-color="#6366F1" stop-opacity="0"/>
+    </radialGradient>
+    <path id="orbit" d="M 240 70 A 170 170 0 1 1 239.99 70.0003" fill="none"/>
+  </defs>
+
+  <!-- ambient glow -->
+  <circle cx="240" cy="240" r="232" fill="url(#glow)"/>
+
+  <!-- outer gate frame (hexagon) -->
+  <polygon points="240,15 434.9,127.5 434.9,352.5 240,465 45.1,352.5 45.1,127.5"
+           fill="none" stroke="url(#gateGrad)" stroke-width="10" stroke-linejoin="round" opacity="0.9"/>
+
+  <!-- orbit ring -->
+  <circle cx="240" cy="240" r="170" fill="none" stroke="#818CF8" stroke-opacity="0.35"
+          stroke-width="3" stroke-dasharray="2 12" stroke-linecap="round"/>
+
+  <!-- six stage nodes (Ingest, Preflight, Define Done, Execute, Gate, Finalize) -->
+  <g fill="#818CF8">
+    <circle cx="240" cy="70" r="11" opacity="0.5">
+      <animate attributeName="opacity" values="0.5;1;0.5;0.5" keyTimes="0;0.06;0.14;1" dur="9s" begin="0s" repeatCount="indefinite"/>
+    </circle>
+    <circle cx="387.2" cy="155" r="11" opacity="0.5">
+      <animate attributeName="opacity" values="0.5;1;0.5;0.5" keyTimes="0;0.06;0.14;1" dur="9s" begin="1.5s" repeatCount="indefinite"/>
+    </circle>
+    <circle cx="387.2" cy="325" r="11" opacity="0.5">
+      <animate attributeName="opacity" values="0.5;1;0.5;0.5" keyTimes="0;0.06;0.14;1" dur="9s" begin="3s" repeatCount="indefinite"/>
+    </circle>
+    <circle cx="240" cy="410" r="11" opacity="0.5">
+      <animate attributeName="opacity" values="0.5;1;0.5;0.5" keyTimes="0;0.06;0.14;1" dur="9s" begin="4.5s" repeatCount="indefinite"/>
+    </circle>
+    <circle cx="92.8" cy="325" r="11" opacity="0.5">
+      <animate attributeName="opacity" values="0.5;1;0.5;0.5" keyTimes="0;0.06;0.14;1" dur="9s" begin="6s" repeatCount="indefinite"/>
+    </circle>
+    <circle cx="92.8" cy="155" r="11" opacity="0.5">
+      <animate attributeName="opacity" values="0.5;1;0.5;0.5" keyTimes="0;0.06;0.14;1" dur="9s" begin="7.5s" repeatCount="indefinite"/>
+    </circle>
+  </g>
+
+  <!-- the autonomous conductor, circling the stages -->
+  <g>
+    <circle r="8" fill="#A5B4FC">
+      <animateMotion dur="9s" repeatCount="indefinite">
+        <mpath href="#orbit"/>
+      </animateMotion>
+    </circle>
+    <circle r="14" fill="none" stroke="#A5B4FC" stroke-opacity="0.45" stroke-width="2">
+      <animateMotion dur="9s" repeatCount="indefinite">
+        <mpath href="#orbit"/>
+      </animateMotion>
+    </circle>
+  </g>
+
+  <!-- inner gate -->
+  <polygon points="240,122 342.2,181 342.2,299 240,358 137.8,299 137.8,181"
+           fill="url(#gateGrad)" stroke="#4F46E5" stroke-width="4" stroke-linejoin="round"/>
+
+  <!-- the machine-checked verdict -->
+  <path d="M 193 248 L 226 281 L 291 203" fill="none" stroke="#FFFFFF"
+        stroke-width="20" stroke-linecap="round" stroke-linejoin="round"
+        stroke-dasharray="170" stroke-dashoffset="170">
+    <animate attributeName="stroke-dashoffset" from="170" to="0" dur="0.9s" begin="0.5s" fill="freeze"/>
+  </path>
+</svg>