bmad-module-ultracode-goal 0.1.1-alpha.0 → 0.2.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.1.1-alpha.0",
+      "version": "0.2.0",
       "author": {
         "name": "Armel"
       },

package/README.md

@@ -13,7 +13,7 @@
 [![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)
+[![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.
@@ -120,6 +120,24 @@ UCG runs six stages in order, each routing by the testable conditions stated in
 5. **Gate** — `gate_eval.py` reads TEA's verdict and routes: advance / defer / reloop / escalate.
 6. **Finalize** — Auto Memory capture, optional retrospective, decision-log audit, run report.
 
+The run is a straight line until the gate, which branches — and a `reloop` sends the story back through Execute within budget, while an unresolved blocker stops the run rather than guessing:
+
+```mermaid
+flowchart TD
+    I["Stage 1 Ingest and Scope"] --> P{"Stage 2 Preflight hard gate"}
+    P -->|"red blocker"| STOP["STOP / blocked"]
+    P -->|"budget 0, green"| D["Stage 3 Define Done"]
+    D --> X["Stage 4 Execute"]
+    X --> G{"Stage 5 gate_eval.py reads TEA verdict"}
+    G -->|"advance, PASS or WAIVED"| F["Stage 6 Finalize"]
+    G -->|"defer, CONCERNS"| L["Ledger then advance"]
+    L --> F
+    G -->|"reloop, FAIL or signal downgrade"| X
+    G -->|"escalate, NOT_EVALUATED or budget out"| STOP
+    classDef gate fill:#6366F1,stroke:#4F46E5,color:#fff
+    class P,G gate
+```
+
 Three enforcement layers keep the autonomy honest:
 
 - **Hooks are the invariants** — `PreToolUse` guards (no commit on a protected branch; no commit before tests ran for the story) live in `settings.local.json`, where the runtime enforces them, not in memory.
@@ -146,6 +164,19 @@ uv run skills/ultracode-goal/scripts/gate_eval.py \
 
 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.
@@ -169,6 +200,7 @@ The docs are organized into three buckets — **Why** (start here), **Try** (do
 - **[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.
 
 ## Acknowledgements

package/docs/404.md

@@ -0,0 +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.
+template: splash
+---
+
+## 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.
+
+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)
+
+**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)
+
+---
+
+### 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.

package/docs/_internal/RELEASING.md

@@ -1,4 +1,7 @@
-# Releasing
+---
+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.
 
@@ -18,6 +21,30 @@ Dispatching `release.yaml` from `main` runs, in order:
 
 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.
 
+How the dispatch ref forks the pipeline, and where the two paths rejoin to tag and publish:
+
+```mermaid
+flowchart TD
+    D["Dispatch release.yaml"] --> P["Approve release environment"]
+    P --> Q["Quality gate, version bump, marketplace + CHANGELOG sync"]
+    Q --> DR["npm publish --dry-run"]
+    DR --> REF{"Dispatched from main?"}
+    REF -->|"yes"| BR["Push commit to temp branch, open bot PR"]
+    BR --> FT["Force-dispatch quality.yaml on temp branch"]
+    FT --> WC["Wait for required status checks"]
+    WC --> AUTH{"Approved or admin-merged?"}
+    AUTH -->|"maintainer approval"| AM["Auto-merge with merge commit"]
+    AUTH -->|"admin bypass-merge"| MG["Merged on main"]
+    AM --> MG
+    MG --> TAG["Tag vX.Y.Z on merge commit"]
+    REF -->|"no"| SKIP["Skip PR flow, anchor tag on CI-ephemeral commit"]
+    SKIP --> TAG
+    TAG --> PUB["npm publish via OIDC trusted publishing"]
+    PUB --> REL["Create GitHub Release"]
+    classDef verdict fill:#4F46E5,stroke:#3730A3,color:#fff
+    class REF,AUTH verdict
+```
+
 ## One-time setup
 
 These must exist before the first `main`-dispatch release. Order matters.
@@ -61,13 +88,15 @@ On [npmjs.com](https://www.npmjs.com/) → package settings → Trusted Publishe
 
 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
+### 5. Repo settings: auto-merge + Actions PR creation
 
 ```bash
 gh api --method PATCH /repos/armelhbobdad/bmad-module-ultracode-goal -f allow_auto_merge=true
+gh api --method PUT /repos/armelhbobdad/bmad-module-ultracode-goal/actions/permissions/workflow \
+  -f default_workflow_permissions=read -F can_approve_pull_request_reviews=true
 ```
 
-Without it, `gh pr merge --auto` in the workflow fails.
+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
 

package/docs/_internal/STABILITY.md

@@ -1,4 +1,7 @@
-# Stability and Public Contract
+---
+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.
+---
 
 > **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.
 
@@ -45,6 +48,19 @@ The skill name `ultracode-goal` and its documented invocation phrases — "run a
 - **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 contractual mapping each `gate_status` resolves to:
+
+```mermaid
+flowchart LR
+    PASS["PASS"] --> ADV["advance"]
+    WAIVED["WAIVED"] --> ADV
+    CONCERNS["CONCERNS"] --> DEF["defer"]
+    FAIL["FAIL"] --> REL["reloop"]
+    NE["NOT_EVALUATED"] --> ESC["escalate"]
+    classDef verdict fill:#4F46E5,stroke:#3730A3,color:#fff
+    class ADV,DEF,REL,ESC verdict
+```
+
 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

package/docs/architecture.md

@@ -1,4 +1,7 @@
-# Architecture
+---
+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.
+---
 
 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.
 
@@ -12,6 +15,38 @@ The skill owns no implementation logic of its own for building features or runni
 
 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)).
@@ -20,6 +55,23 @@ These are the module's non-negotiables. Each exists because the documented mecha
 
 `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
+```
+
 ### 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:
@@ -72,6 +124,24 @@ Configuration resolves in three layers, base → team → user, via `resolve_cus
 
 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:
+
+```mermaid
+flowchart LR
+    BASE["Base - customize.toml"]
+    TEAM["Team - ultracode-goal.toml"]
+    USER["User - ultracode-goal.user.toml"]
+    BASE --> RES["resolve_customization.py merges base then team then user"]
+    TEAM --> RES
+    USER --> RES
+    RES --> WF["resolved workflow block"]
+    WF -->|"conductor reads scalars directly"| COND["conductor stages"]
+    WF -->|"preflight injects ULTRACODE_* env"| HOOKS["PreToolUse + Stop hooks"]
+    HOOKS -. "no env injected, falls back to defaults" .-> DROP["override no-ops at enforcement"]
+    classDef accent fill:#6366F1,stroke:#4F46E5,color:#fff
+    class WF accent
+```
+
 ## 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/cross-session-recall.md

@@ -0,0 +1,107 @@
+---
+title: Cross-Session Recall
+description: The optional claude-mem integration — UCG consults your past runs in this repo before it scopes an Epic and before its preflight gate, advisory only and never in the gate path. Opt-in, hook-latched, off by default.
+---
+
+> **Optional, opt-in, off by default.** Cross-Session Recall is an *advisory* read of your own past runs. It informs the model; it never decides anything. It is wired so it can **never** sit in the gate or completion path, it **fails closed** during a run, and when it is off — or when claude-mem is absent — the run is byte-for-byte the same as a run without it.
+
+## What it does
+
+Cross-Session Recall lets UCG learn from its own history in *this* codebase instead of starting amnesiac every Epic. If you run [claude-mem](https://github.com/thedotmack/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.
+
+The benefit compounds — your first Epic teaches it, your third Epic consults two.
+
+## What you need
+
+You need [claude-mem](https://github.com/thedotmack/claude-mem) installed and the `cross_session_recall` knob set to `on`. That is the whole dependency: UCG reads and writes through claude-mem's MCP tools when they are present, and does nothing recall-related when they are not.
+
+> claude-mem is a third-party plugin maintained independently of this module. We don't bundle, endorse, or install it; Cross-Session Recall simply uses it when you already have it.
+
+## The touchpoints
+
+Recall touches the run in exactly three places, and a machine latch (`.mem-state.json`) gates every one of them. The latch is written **once** at Ingest and removed at Finalize close-out; while it is present a `PreToolUse` hook allows claude-mem calls only when recall is green, and denies them otherwise — fail closed. The Execute and Gate stages are never touched.
+
+```mermaid
+flowchart TD
+    I["Stage 1 Ingest — write latch, advisory scope-recall read"] --> P{"Stage 2 Preflight — prior-failure recall reuses the same fetch"}
+    P -->|"advisory only, voice never vote"| X["Stage 4 Execute — untouched"]
+    X --> G["Stage 5 Gate — untouched, gate_eval.py only"]
+    G --> F["Stage 6 Finalize — one structured write, then remove latch"]
+
+    LATCH{".mem-state.json latch — present and green gates reads and writes; absent or not green denies, fail closed"}
+    LATCH -.->|"gates"| I
+    LATCH -.->|"gates"| P
+    LATCH -.->|"gates"| F
+
+    classDef gate fill:#6366F1,stroke:#4F46E5,color:#fff
+    class P,LATCH gate
+```
+
+- **Ingest (read).** Before UCG scopes the Epic, one advisory read pulls prior run summaries for this repo, sanitizes them, and surfaces what recurred.
+- **Preflight (read, reused).** The prior-failure recall reuses that same fetch — no second round-trip — so the preflight reasoning can see failures that bit you here before. It is advisory context, never a gate input.
+- **Finalize (write).** At close-out UCG records exactly one structured observation summarizing the run's outcome and signatures. The optional retrospective reuses the recurrence counts already computed during the reads.
+
+Outside a run — when the latch file is absent — the hook never touches your claude-mem usage at all. Recall is scoped strictly to an active UCG run.
+
+## The trust model
+
+The rule is **data, never directive**: recalled content is treated as facts to consider, never as instructions to follow, and it never reaches the gate.
+
+What the sanitizer **does** before any advisory is surfaced:
+
+- **Scopes to this repo.** A repository fingerprint pins recall to the same origin and root commit, so another project's history cannot leak in.
+- **Redacts secrets.** High-precision patterns — AWS keys, `ghp_`/`gho_` tokens, `sk-` keys, bearer tokens, PEM headers, `password=`/`token=`/`api_key=` values — are replaced with `[redacted]`.
+- **Neutralizes shape.** Bidi controls are stripped, backticks and code fences removed, newlines collapsed, and each surfaced title clamped to 80 codepoints — so an advisory cannot carry instruction-shaped or prompt-injection payloads.
+- **Drops the stale and the foreign.** Records past the recency horizon are dropped (signatures that recurred across two or more distinct runs earn per-signal horizon immunity), foreign-project and cross-schema records are filtered out, and malformed records are discarded.
+
+What it honestly does **not** do:
+
+- It is **not** a complete secret scrubber — redaction is high-precision pattern matching, not a guarantee that nothing sensitive ever survives.
+- It does **not** vote. Advisories carry only a mechanical `recurred` field (`yes`/`no`/`unknown`) — there are no LLM self-grades, and nothing recall surfaces is ever an input to `gate_eval.py`. The gate reads TEA's `gate-decision.json` and only that. See the [gate model](gate-model.md).
+- It does **not** keep working when claude-mem looks wrong. If the capability contract fails — a missing tool, a malformed probe, a breaking schema change — the latch records recall as absent and the hook denies claude-mem calls for the run. Fail closed, never fail open.
+
+## Turning it on
+
+Set the knob in your project's `_bmad/custom/ultracode-goal.toml` (the same file the other knobs use):
+
+```toml
+[workflow]
+# Cross-Session Recall — consult and record prior runs of this repo via claude-mem.
+# Requires claude-mem installed; advisory only, never part of the gate. Off by default.
+cross_session_recall = "on"
+```
+
+The `[workflow]` table header matters: the resolver extracts the `workflow` block from the merged files, so a bare top-level `cross_session_recall` line is silently discarded and the feature stays off.
+
+With it `on` and claude-mem installed, the next run reads at Ingest and Preflight and writes one observation at Finalize. Nothing else about the run changes.
+
+## Turning it off
+
+Set the knob back to `off` (its default):
+
+```toml
+[workflow]
+cross_session_recall = "off"
+```
+
+> **OFF-coherence disclosure.** Setting `cross_session_recall` to `off` disables **UCG's own** recall and write only. A separately-installed claude-mem still injects its session-start index into your Claude Code sessions — that is claude-mem's behavior, not UCG's. To stop that, configure or uninstall claude-mem itself.
+
+## What happens when claude-mem is absent
+
+Nothing — the run is identical. There is no fallback to emulate, no degraded path, no warning. UCG's control flow is the same whether claude-mem is installed or not; absent claude-mem, the recall touchpoints are simply no-ops and Finalize skips the write. A run with the knob `on` and claude-mem missing behaves exactly like a run with the knob `off`.
+
+## Known limits — be honest
+
+Recall is deliberately bounded. Treat these as the residuals you are signing up for:
+
+- **A factual advisory still informs reasoning.** Sanitized advisories carry no instruction-shaped, stale, or foreign content and never reach the gate — but a well-formed factual advisory can still inform the model's reasoning. That is the feature, bounded; it is not a side channel into the verdict.
+- **UCG serializes only its own writes.** It writes its one observation per run safely, but it cannot control other processes writing the same claude-mem store concurrently.
+- **One structured write per run, in every mode.** UCG contributes exactly one structured observation at Finalize regardless of mode. Any *additional* auto-capture you see is claude-mem's own behavior and may differ in headless runs.
+- **Redaction is high-precision, not complete.** Secret redaction is pattern matching tuned for precision; it is not a complete data-loss-prevention layer.
+- **A breaking claude-mem change latches loudly absent.** If claude-mem ships a schema change that breaks the capability pin, recall latches as absent — loudly off, never silently wrong — until the pin is updated. Run the recall selftest to check the pin against your installed claude-mem.
+
+## The default, and what would flip it
+
+Cross-Session Recall ships **off**. That is the honest default: an advisory that reads your history is worth shipping on by default only once opt-in usage proves it earns its keep without ever touching a verdict.
+
+The default flips to `on` only if, across sustained real-world opt-in use, recalled advisories are corroborated by run outcomes **and** there are zero gate-influence incidents. Until that bar is met, off is the honest default — and "stays off" is a perfectly valid outcome. The criterion is falsifiable on purpose: it is a claim that can fail, not a roadmap promise.

package/docs/gate-model.md

@@ -1,4 +1,7 @@
-# Gate Model
+---
+title: Gate Model
+description: How gate_eval.py turns TEA's gate-decision.json into a fail-closed advance, defer, reloop, or escalate verdict.
+---
 
 Completion in UltraCode Goal is decided by a deterministic artifact read, not by judgment. `scripts/gate_eval.py` reads TEA's `gate-decision.json` and returns a routing verdict the skill executes. This page documents the verdict mapping, the production AND, the thresholds, the fail-closed contract, and why the `/goal` evaluator alone is insufficient — all traced to [`../skills/ultracode-goal/scripts/gate_eval.py`](../skills/ultracode-goal/scripts/gate_eval.py).
 
@@ -12,6 +15,27 @@ The script resolves the gate artifact from the trace output directory:
 
 The script never re-derives TEA's thresholds; it reads `gate_status` as given by the trace workflow.
 
+How the script resolves an artifact into a `gate_status`:
+
+```mermaid
+flowchart TD
+    A["Scan trace-output for a trace report"] --> B{"Frontmatter names a slim gate file?"}
+    B -->|"yes"| C["Use the hinted path"]
+    B -->|"no"| D["Default to gate-decision.json"]
+    C --> E{"Slim file present?"}
+    D --> E
+    E -->|"yes"| F["Read gate_status from slim file"]
+    E -->|"no"| G{"e2e-trace-summary.json present?"}
+    G -->|"yes, has gate fields"| H["Lift gate_status from summary"]
+    G -->|"yes, no gate fields"| I["gate_status = NOT_EVALUATED"]
+    G -->|"no"| I
+    F --> Z["gate_status to verdict mapping"]
+    H --> Z
+    I --> Z
+    classDef verdict fill:#4F46E5,stroke:#3730A3,color:#fff
+    class Z verdict
+```
+
 ## Verdict mapping
 
 The gate status maps to a verdict (`GATE_VERDICT` in the script):
@@ -33,6 +57,24 @@ Under `--profile production`, an otherwise-`advance` verdict is additionally AND
 - **NFR** (`nfr-assessment.md`): the audit's Overall Status must not be `FAIL`.
 - **Test review** (`test-review.md`): the Quality Score must be `>= 80` **and** the Recommendation must not be `Block`.
 
+How the AND folds the two signals in, with every unreadable path counting as a failure:
+
+```mermaid
+flowchart TD
+    V{"Verdict is advance?"} -->|"no, defer/reloop/escalate"| K["Unchanged"]
+    V -->|"yes"| N{"NFR Overall Status"}
+    N -->|"FAIL"| F["Signal failed"]
+    N -->|"file missing or unparsable"| F
+    N -->|"parsed and not FAIL"| R{"Test review"}
+    R -->|"score lt 80 or Block"| F
+    R -->|"score unparsable, file missing"| F
+    R -->|"score gte 80 and not Block"| P["Both signals passed"]
+    F --> D["Downgrade advance to reloop"]
+    P --> A["Stay advance"]
+    classDef verdict fill:#4F46E5,stroke:#3730A3,color:#fff
+    class A,D,K verdict
+```
+
 Under `--profile light` none of this applies — the trace gate is the whole decision.
 
 ## The thresholds

package/docs/getting-started.md

@@ -1,4 +1,7 @@
-# Getting Started
+---
+title: Getting Started
+description: Install UltraCode Goal, point it at a BMAD Epic, and walk the first autonomous run from install through preflight, gate, and run report.
+---
 
 Install UltraCode Goal into a BMAD project, point it at an Epic, and let it run that Epic to a gate-passed Definition-of-Done. This page covers prerequisites, install, the first-run walkthrough, and the run-mode flags.
 
@@ -36,6 +39,32 @@ Invoke the skill with one of its trigger phrases — "run an epic autonomously",
 
 From there the run is autonomous: it defines done with TEA, executes each story to a green commit, gates each one deterministically, and finalizes with a run report and the deferred-work ledger. See [how it works](how-it-works.md) for the full stage-by-stage narration.
 
+The whole first run, from install to run report, with the two points where it can refuse to launch and the verdict that decides each story:
+
+```mermaid
+flowchart TD
+    I["npx install"] --> A["Activate skill via trigger phrase"]
+    A --> N["Stage 1: name the Epic"]
+    N --> BMAD{"BMAD project?"}
+    BMAD -->|"no"| STOP1["Stop: point at setup skills"]
+    BMAD -->|"yes"| PF["Stage 2: preflight check then auto-remediate ambers"]
+    PF --> GATE{"Budget 0 and no red blocker?"}
+    GATE -->|"no"| STOP2["Stop: write blockers to decision log"]
+    GATE -->|"yes"| BRIEF["Arm branch, hooks, allowlist; launch briefing; one soft confirm"]
+    BRIEF --> RUN["Autonomous run: define done, execute each story to a green commit"]
+    RUN --> EVAL["Stage 5: gate_eval.py reads TEA gate-decision.json"]
+    EVAL --> V{"verdict"}
+    V -->|"advance"| NEXT["Next story, or finalize when last"]
+    V -->|"defer"| NEXT
+    V -->|"reloop"| RUN
+    V -->|"escalate"| STOP3["Stop: surface the blocker"]
+    NEXT --> RPT["Stage 6: run report and deferred-work ledger"]
+    class STOP1,STOP2,STOP3 stop
+    class RPT verdict
+    classDef stop fill:#9CA3AF,stroke:#6B7280,color:#fff
+    classDef verdict fill:#4F46E5,stroke:#3730A3,color:#fff
+```
+
 ## Run-mode flags
 
 | Flag | Effect |

package/docs/health-check.md

@@ -1,4 +1,7 @@
-# Health Check
+---
+title: Health Check
+description: The Finalize self-improvement reflection — what it computes locally, what leaves your machine and only after approval, how it dedups, and how to turn it off.
+---
 
 Every UltraCode Goal run that reaches Finalize ends with a health check: a brief self-improvement reflection that audits the run for friction, gaps, or bugs in *this module* and, when it finds something, offers to file a structured GitHub issue. The expected outcome is **zero findings** — a clean run exits in a line. This page covers exactly what it sends, the privacy model, how it dedups, and how to turn it off. The deterministic fingerprint and seen-cache plumbing is [`../skills/ultracode-goal/scripts/health_check_fp.py`](../skills/ultracode-goal/scripts/health_check_fp.py).
 
@@ -24,6 +27,44 @@ Explicitly **not** sent: no source code, no Epic content, no secrets. The eviden
 
 Issues are filed publicly on `armelhbobdad/bmad-module-ultracode-goal`. On an **attended** run nothing is sent silently: the health check always **HALTS at a `[Y]` / `[N]` / `[E]` gate** before submitting — yes to file, no to skip, edit to adjust first. You see the finding and approve it before it leaves your machine.
 
+The boundary below shows the disable path, everything computed on your machine, and the two points where anything crosses to GitHub — both behind a gate:
+
+```mermaid
+flowchart TD
+    Start["Reaches Finalize"] --> Enabled{"health_check_enabled true"}
+    Enabled -->|"false"| Off["Log one line and exit. Nothing computed, nothing sent"]
+    Enabled -->|"true"| Reflect["Reflect on this run. Grade bug, friction, gap"]
+    Reflect --> Clean{"Any findings"}
+    Clean -->|"no"| Done["Clean run. Exit in one line"]
+    Clean -->|"yes"| Gate{"Approved to submit"}
+    Gate -->|"no, queue or skip"| Queue["Write finding to local queue. Stays on disk"]
+    Gate -->|"yes"| Fp["Compute fingerprint and check seen-cache"]
+    Fp --> Search["Remote dedup search on GitHub"]
+    Search --> Create["Create or react on public issue"]
+
+    subgraph local["On your machine"]
+        Enabled
+        Off
+        Reflect
+        Clean
+        Done
+        Gate
+        Queue
+        Fp
+    end
+    subgraph net["Leaves the machine"]
+        Search
+        Create
+    end
+
+    classDef accent fill:#6366F1,stroke:#4F46E5,color:#fff
+    classDef verdict fill:#4F46E5,stroke:#3730A3,color:#fff
+    class Gate accent
+    class Create verdict
+```
+
+The gate that admits anything to the right of the boundary is the `[Y]` approval on an attended run, or the autosubmit opt-in restricted to `bug`-severity findings on a headless run; the Environment table — never source code, Epic content, or secrets — is all that travels with a filed issue.
+
 ## Unattended behavior
 
 Headless runs do not have a human at the gate, so by default they **queue findings locally and never live-submit**. Two config knobs (set in `{project-root}/_bmad/custom/ultracode-goal.toml`) change this:

package/docs/how-it-works.md

@@ -1,4 +1,7 @@
-# How It Works
+---
+title: How It Works
+description: A faithful walkthrough of UltraCode Goal's six stages, the testable conditions that route between them, and the headless contract.
+---
 
 UltraCode Goal runs an Epic through six stages, in order. Each stage routes to the next by testable conditions stated in its reference file under [`../skills/ultracode-goal/references/`](../skills/ultracode-goal/references/). This page narrates the stages faithfully, the conditions that move between them, and the headless contract. For the design behind it, see [architecture](architecture.md); for the gate specifically, see the [gate model](gate-model.md).
 
@@ -13,6 +16,46 @@ UltraCode Goal runs an Epic through six stages, in order. Each stage routes to t
 | 5 | Gate | the `gate_eval.py` verdict: advance / defer / reloop / escalate |
 | 6 | Finalize | terminal — report, ledger, memory capture |
 
+The stages run in order, but the edges are conditional — each one only advances on a testable condition, and two of them loop backward on failure. This shows the real routing, including the preflight remediation loop and the gate re-loop:
+
+```mermaid
+flowchart TD
+    S1["Stage 1 Ingest and Scope"]
+    NotBmad["STOP — not a BMAD project"]
+    S2["Stage 2 Preflight"]
+    Remediate["Auto-remediate then re-run check"]
+    Blocked["STOP or blocked — RED or budget gt 0"]
+    S3["Stage 3 Define Done"]
+    S4["Stage 4 Execute"]
+    S5["Stage 5 Gate via gate_eval.py"]
+    Correct["bmad-correct-course"]
+    S6["Stage 6 Finalize"]
+
+    S1 -->|"config + sprint + epic all absent"| NotBmad
+    S1 -->|"one resolved epic id"| S2
+    S2 -->|"remediable blocker"| Remediate
+    Remediate --> S2
+    S2 -->|"RED found or budget gt 0"| Blocked
+    S2 -->|"budget == 0 and no RED and ultracode plus Auto Mode on"| S3
+    S3 -->|"ATDD hard-halt on vague ACs"| S3
+    S3 -->|"every story has red-phase atdd-checklist"| S4
+    S4 -->|"every story committed at green"| S5
+    S4 -->|"turn-bound escalation"| S5
+    S5 -->|"advance or defer"| S6
+    S5 -->|"reloop — gate FAIL within budget"| Correct
+    Correct --> S4
+    S5 -->|"escalate — NOT_EVALUATED or budget exhausted"| S6
+
+    classDef accent fill:#6366F1,stroke:#4F46E5,color:#fff
+    classDef verdict fill:#4F46E5,stroke:#3730A3,color:#fff
+    classDef stop fill:#9CA3AF,stroke:#6B7280,color:#fff
+    class S5 verdict
+    class S2 accent
+    class NotBmad,Blocked stop
+```
+
+A `defer` verdict appends non-blocking items to the ledger and advances anyway; an `escalate` ends the run as `blocked` at Stage 6 rather than `complete`. The reloop edge re-runs the story only while turn and token budget remain — once exhausted, a FAIL becomes an escalate.
+
 ### Stage 1 — Ingest & Scope
 
 Resolve **which** Epic this run delivers and lock the profile. The operator names the Epic (or the skill picks the obvious in-flight one from `sprint-status.yaml`); the skill locates the Epic/story files, the PRD, and the ADR/architecture, and records the paths to the run's `.decision-log.md`. This is the cheap stage that prevents an expensive run from targeting the wrong Epic.
@@ -41,6 +84,29 @@ Drive each in-scope story from its red-phase tests to a green, committed state.
 
 Decide whether a story (or, after the last story, the Epic) advances — by a deterministic artifact read. In production, the skill first backfills the evidence in order — `bmad-testarch-automate`, `bmad-testarch-trace` (which writes the gate decision), `bmad-testarch-nfr` — then runs `gate_eval.py`. The script reads TEA's `gate-decision.json` and returns a verdict the skill executes: `advance` (move to the next story), `defer` (append non-blocking items to the ledger and advance anyway), `reloop` (run `bmad-correct-course`, re-run the story within the remaining budget), or `escalate` (stop). The invariant: **a P0/critical FAIL never defers** — it re-loops within budget or escalates. See the [gate model](gate-model.md) and [`references/gate.md`](../skills/ultracode-goal/references/gate.md).
 
+This is how the verdict is read deterministically — the conductor never grades the work itself, it runs the script and routes on what comes back:
+
+```mermaid
+sequenceDiagram
+    participant C as Conductor
+    participant TEA as TEA trace
+    participant G as gate_eval.py
+    participant F as gate-decision.json
+    C->>TEA: bmad-testarch-trace writes gate decision
+    C->>G: run gate_eval.py --trace-output DIR
+    G->>F: resolve and read slim file
+    alt slim file absent
+        G->>F: fall back to e2e-trace-summary.json
+    end
+    F-->>G: gate_status
+    Note over G: PASS or WAIVED to advance, CONCERNS to defer, FAIL to reloop, NOT_EVALUATED to escalate
+    Note over G: production only — NFR FAIL or review lt 80 or Block downgrades advance to reloop
+    G-->>C: verdict + reasons JSON
+    C->>C: route the verdict advance / defer / reloop / escalate
+```
+
+The production AND fails closed: a missing or unparseable `nfr-assessment.md` or `test-review.md` is treated as a failing signal, so an otherwise-`advance` story downgrades to `reloop` rather than advancing on evidence the script could not read.
+
 ### Stage 6 — Finalize
 
 Make the run pay off for the next one. Capture learnings deliberately — machine-local quirks to Auto Memory (`remember X`), team standards to the project's CLAUDE.md or `.claude/rules`. Optionally run the retrospective (`--retro`). Audit every `.decision-log.md` entry into the report, the addendum, or explicit process-noise. Produce a `run-report.md` (Epic, profile, per-story outcomes, the Epic-level gate, budget consumed, learnings, a pointer to the ledger), write the terminal `run-status.json`, surface this Epic's deferred-work ledger heading to the user, and fire the `on_epic_complete` hook **only** when the Epic actually advanced. See [`references/finalize.md`](../skills/ultracode-goal/references/finalize.md).