bmad-plus 0.13.0 → 0.16.0

package/src/bmad-plus/packs/pack-dev-studio/upstream-sync.yaml

@@ -1,15 +1,41 @@
-# Pack Dev Studio — upstream-sync.yaml
-# Tracks the source commit and version from BMAD-METHOD for future updates
+# Dev Studio provenance and selective adaptation ledger.
+# Version and commit below have different, explicitly recorded roles.
+# The 0.14.0 implementation is original BMAD+ work, not a wholesale upstream sync.
+schema_version: 2
 
 upstream:
   repository: https://github.com/bmad-code-org/BMAD-METHOD
   version: "6.6.0"
+  version_role: declared-compatibility-baseline
+  baseline_tag_commit: "e6cdc93b79420fcc915d3bd3ca63387bc86af694"
   commit: "0f852a38ac7c0ac30340b3aedc3aba4505b7c14a"
+  commit_role: historical-partial-import
   synced_at: "2026-05-17"
+  synced_at_role: recorded-date-of-historical-import
   license: MIT
 
+reviewed_reference:
+  version: "6.12.0"
+  commit: "05bfbd46d00766ec88eb9b42e76be2c575d64d7b"
+  reviewed_at: "2026-09-09"
+  status: reviewed-only
+  full_migration: false
+  compatibility_baseline_changed: false
+
+implementation:
+  bmad_plus_version: "0.14.0"
+  origin: original-bmad-plus-instructions-and-context-preparation
+  authored_at: "2026-09-09"
+  execution: host-managed-markdown
+  context_preparation: read-only-cli
+  standalone_llm_runtime: false
+  upstream_runtime_imported: false
+  preserved_public_workflow_ids: 38
+  preserved_personas: 6
+  evidence_limit: Resource reconciliation does not establish host execution or model compliance.
+
 adaptations:
-  format: "BMAD+ BWML (Workflow Markup Language)"
+  format: Original BMAD+ Markdown procedures with explicit inputs, evidence and continuation.
   personas:
     Mary: Miriam (מרים)
     Paige: Huldah (חולדה)
@@ -17,18 +43,63 @@ adaptations:
     Sally: Rachel (רחל)
     Winston: Bezalel (בצלאל)
     Amelia: Oholiab (אהליאב)
-  removed_dependencies:
-    - customize.toml (3-layer TOML config system)
-    - resolve_customization.py (Python variable resolver)
-    - resolve_config.py (Python config merger)
-    - analyze_sources.py (Python source analyzer)
-    - config.yaml (per-project config)
-  added:
-    - BWML specification (shared/bwml-spec.md)
-    - Dev Studio orchestrator
-    - Specialized persona naming
-    - BMAD+ pack integration (module.yaml, CLI, i18n)
+  entry: SKILL.md
+  catalog: shared/catalog.json
+  execution_guide: shared/execution.md
+  historical_bwml_document: shared/bwml-spec.md
+  historical_bwml_document_role: migration-note-not-interpreter-specification
+  configuration:
+    file: _bmad/config.yaml
+    scope: explicitly-selected-project
+    parser: existing-bmad-plus-yaml-parser
+    known_fields:
+      - user_name
+      - communication_language
+      - document_output_language
+      - output_folder
+      - project_name
+    missing_values: Explicit neutral defaults in the execution guide.
+    invalid_present_values: Report an error rather than inventing configuration.
+    preserve_unrelated_settings: true
+    layered_toml_overrides: false
+  retired_dependency_contracts:
+    - Imported PRD headless schemas and automatic HTML validation rendering.
+    - Distillator compression/reconstruction format and Python source analyzer.
+    - Upstream Python/TOML customization discovery and layered override merging.
+    - Implied execution of BWML tags as scheduler, memory, events or validation gates.
+  historical_dependency_note: >-
+    The old removed_dependencies list was not proof that dependent instructions
+    remained executable. Project YAML configuration is supported now; it is not
+    a removed dependency. Per-skill customize.toml files and shared upstream
+    resolvers fall outside the 147-support-file inventory below.
+
+support_reconciliation:
+  source_method: Read-only git ls-tree at the historical import commit.
+  historical_bmad_plus_commit: "913d0600b9e0c3ac12af22b17e2205bf9d394a63"
+  mapped_entry_families: 44
+  excluded_relative_paths:
+    - SKILL.md
+    - customize.toml
+  source_support_files: 147
+  historically_delivered: 15
+  historically_omitted: 132
+  historically_omitted_families: 24
+  omitted_dispositions:
+    replaced-by-self-contained-workflows: 117
+    retired-runtime: 12
+    optional-tests-or-metadata: 3
+  delivered_disposition: retained-as-original-support
+  interpretation: >-
+    Counts describe the pre-remediation snapshot. An omitted support file is not
+    automatically a demonstrated runtime failure. Replaced means the relevant
+    purpose is covered by original instructions, not exact upstream feature parity.
+    Retired-runtime includes unsupported execution contracts even when no working
+    runtime had been delivered.
+  repository_report: docs/research/dev-studio-0.14-validation/migration.md
+  repository_inventory: docs/research/dev-studio-0.14-validation/migration.json
 
+# Historical source mapping only. These are lineage references, not live imports
+# or runtime dependencies. Current routes resolve through shared/catalog.json.
 source_mapping:
   categories/analysis:
     - src/bmm-skills/1-analysis/bmad-agent-analyst → analyst-agent.md

package/src/bmad-plus/packs/pack-memory/README.md

@@ -4,7 +4,10 @@
 
 ## What is Pack Memory?
 
-Pack Memory adds a **persistent brain** to BMAD+. Every decision logged, every lesson learned, every pattern discovered — they all survive between sessions. Your agents get smarter over time.
+Pack Memory stores decisions, lessons and patterns between sessions. Optional
+project-local outcome evidence helps distinguish current verified sources from
+stale or contradictory advice. Better downstream agent performance must be measured
+separately; persistence alone does not establish it.
 
 ### Two Levels of Memory
 
@@ -21,7 +24,7 @@ Pack Memory adds a **persistent brain** to BMAD+. Every decision logged, every l
 
 ### 🧠 Persistent Memory
 - `decisions.md` — ADR-style architectural decisions with rationale
-- `lessons.md` — Things that burned you, logged immediately, never repeated
+- `lessons.md` — Unexpected outcomes and lessons to review before similar work
 - `patterns.md` — Validated solutions that work, ready to reuse
 - `context.md` — Living project state, auto-updated by agents
 - `sessions/` — Session handoffs for seamless context transfer
@@ -33,7 +36,8 @@ Pack Memory adds a **persistent brain** to BMAD+. Every decision logged, every l
 - Build a complete portfolio index in your global brain
 
 ### 🛡️ Karpathy Guardrails
-Four behavioral principles (from Andrej Karpathy, 132K ⭐) woven into every agent:
+Four behavioral principles from the community `andrej-karpathy-skills` project,
+inspired by Andrej Karpathy's development guidance:
 1. **Think Before Coding** — Surface assumptions, don't guess
 2. **Simplicity First** — Minimum code, nothing speculative
 3. **Surgical Changes** — Touch only what you must
@@ -48,6 +52,33 @@ Dedicated memory agent that can:
 
 ## Installation
 
+The npm pack provides file-based memory and requires Node.js only. Vector/RAG
+recall is an optional, local-only enhancement through a separately deployed
+MCP server. That server, its Python dependencies and its vector index are not
+included in the npm package; `--provision-python` does not install them.
+Missing RAG infrastructure does not disable Markdown memory or the project scanner.
+
+### Verified project outcomes
+
+The portable CLI supports `mem observe --input memory-observation.json` after an
+independently verified Nexus task is accepted. The JSON input identifies `runId`,
+`taskId`, one `memory` section (`file` and `heading`), its applicable `scope` paths
+and the operator's `interpretation`. Optional `supersedes`/`contradicts` lists refer
+to existing outcome receipt IDs. This association records provenance; it does not
+prove that the lesson caused the task to succeed.
+
+```sh
+bmad-plus mem outcomes --json
+bmad-plus mem recall "cache values" --ranking evidence --context-scope src/cache --json
+```
+
+The opt-in ranking rechecks source hashes and Nexus acceptance, excludes explicitly
+stale/superseded/contradictory evidence and applies a bounded relevance-dependent
+boost. `mem outcomes` explains eligibility. Default lexical recall is unchanged.
+Failed, unverified and duplicate task attempts cannot supply successful evidence;
+manually supplied `mem reinforce` signals do not influence this ranking. No vector
+service, background observer, cross-project access or model training is required.
+
 ```bash
 npx bmad-plus install
 # Select "🧠 Memory — Persistent Brain" in the pack menu
@@ -102,5 +133,5 @@ pack-memory/
 ## Credits
 
 - Memory architecture inspired by Laurent Rochetta's `_brain/` methodology
-- Behavioral guardrails adapted from [Andrej Karpathy](https://github.com/multica-ai/andrej-karpathy-skills) (MIT License)
+- Behavioral guardrails adapted from the community [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) project (plugin author: forrestchang; manifest declares MIT), inspired by Andrej Karpathy. See the distribution's third-party license notice.
 - BMAD+ by [Laurent Rochetta](https://github.com/lrochetta/BMAD-PLUS)

package/src/bmad-plus/packs/pack-memory/memory-orchestrator.md

@@ -16,10 +16,17 @@ Pack Memory provides a two-level persistent brain for BMAD+:
 
 ## Activation
 
-Pack Memory activates automatically when installed:
-- At session start: agents load project memory + global identity
-- During session: agents write decisions/lessons/patterns on trigger
-- At session end: session handoff is persisted
+Pack Memory supplies instructions and files for the host agent to use. The host
+must load and follow the memory protocol; installation alone does not execute it.
+No automatic session-start or session-end hooks are installed.
+
+While executing the protocol, the host agent should:
+
+- At session start: load project memory + global identity
+- During the session: record decisions, lessons and patterns when relevant
+- Before ending its work: persist a session handoff
+
+A session that ends without an agent turn has no guaranteed handoff.
 
 Manual activation via Zecher:
 - `"Zecher, scan projects in D:\travail\DEV"` — discover and index all projects
@@ -43,7 +50,7 @@ pack-memory/
 ├── memory-orchestrator.md              ← This file
 ├── zecher-agent.md                     ← Memory Agent (Zecher)
 ├── shared/
-│   ├── karpathy-guardrails.md          ← 4 Karpathy principles + memory hooks
+│   ├── karpathy-guardrails.md          ← 4 Karpathy principles + memory practices
 │   └── memory-protocol.md             ← Complete read/write protocol
 └── templates/
     ├── decisions.md                    ← ADR template
@@ -70,7 +77,27 @@ When Pack Memory is selected during `npx bmad-plus install`:
 4. **Identity setup** — Generates `identity.yaml` from user's install answers
 5. **Guardrails injection** — Makes `karpathy-guardrails.md` available to all agents
 
-## CLI Commands (planned)
+## Project memory CLI
+
+`mem` is the portable project journal and retrieval command. Ordinary lexical recall
+needs no outcome records; optional evidence ranking requires an accepted/current
+Nexus source and explicit project context scope. Inspect eligibility before using
+an observation; success of the source task does not prove that its lesson caused it.
+
+```sh
+bmad-plus mem recall "cache values" --json
+bmad-plus mem observe --input memory-observation.json --json
+bmad-plus mem outcomes --json
+bmad-plus mem recall "cache values" --ranking evidence --context-scope src/cache --json
+```
+
+The observation JSON names `runId`, `taskId`, `memory.file`, `memory.heading`,
+`scope` and `interpretation`. It can name existing receipt IDs in `supersedes` or
+`contradicts`. Shared project writers are serialized and duplicate task attempts
+are refused. No note rewriting, agent installation changes, automatic portfolio
+promotion or background observer is implied.
+
+## Existing scanner and brain commands
 
 ```
 npx bmad-plus scan [path]      — Scan and index projects interactively

package/src/bmad-plus/packs/pack-memory/shared/karpathy-guardrails.md

@@ -1,6 +1,6 @@
 # Karpathy Guardrails — BMAD+ Agent Behavioral Guidelines
 
-> Adapted from [andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) (132K ⭐, MIT License)
+> Adapted from the community [andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) project (plugin author: forrestchang; manifest declares MIT)
 > Enhanced with BMAD+ memory integration
 
 ---
@@ -76,11 +76,11 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
 - Fewer rewrites due to overcomplication — code is simple the first time
 - Clarifying questions come BEFORE implementation — not after mistakes
 - Clean, minimal PRs — no drive-by refactoring or "improvements"
-- **Persistent learning** — the same mistake never happens twice because it's in lessons.md
+- **Persistent context** — previous mistakes are recorded for review; avoiding recurrence still requires verification
 
 ---
 
 ## Attribution
 
-Behavioral principles by [Andrej Karpathy](https://x.com/karpathy) via [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) (MIT License).
+Adapted from the community [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) project, whose plugin author is forrestchang and whose manifest declares MIT. The project is inspired by [Andrej Karpathy](https://x.com/karpathy); it is not attributed to him as the repository's author. See the distribution's third-party license notice.
 Memory integration by [Laurent Rochetta](https://github.com/lrochetta/BMAD-PLUS).

package/src/bmad-plus/packs/pack-memory/shared/memory-protocol.md

@@ -90,13 +90,37 @@ If meaningful work was done:
 1. **Write session handoff** → `sessions/YYYY-MM-DD-<topic>.md`
 2. **Update `context.md`** → Reflect new reality
 3. **Review pending lessons** → Any surprise worth logging?
-4. **Cross-project check** → Any lesson/pattern that applies to ALL projects? → Copy to global brain.
+4. **Cross-project check** → Propose applicable lessons for promotion. Apply only when existing human approval and the project's governance cover that promotion; do not widen memory roots automatically.
 
 ---
 
 ## The Golden Rule
 
-> **If info applies to 1 project → project memory. If 2+ projects → global brain.**
+> **If info applies to 1 project → project memory. If 2+ projects → consider a governed global promotion.**
+
+## Outcome evidence and recall
+
+Keep an interpretation separate from observed success. A successful narrative,
+manual reward or completed process is insufficient: `bmad-plus mem observe --input
+memory-observation.json` requires an independently verified, currently accepted
+Nexus task. The input binds run/task, one exact Markdown heading, applicable task
+scope and the proposed interpretation. Receipts record attempt/verifier IDs and
+artifact/source hashes. One attempt supplies one receipt.
+
+Use `bmad-plus mem outcomes --json` to inspect current eligibility. Optional
+`mem recall "query" --ranking evidence --context-scope src/component --json`
+rechecks the source and gives current relevant evidence a bounded boost. Unsupported
+notes remain `unverified`; stale evidence, explicit supersession and unresolved
+contradictions cannot silently present themselves as current advice. The default
+lexical recall remains available. Do not infer a measured LLM-quality improvement
+from a successful retrieval.
+
+Contradiction and supersession refer to explicit existing receipt IDs; they do not
+rewrite the underlying note or automatically promote it. Never manufacture a new
+receipt ID to repeat support from the same task attempt. Shared memory writers use
+`.bmad/memory/writer.lock`; after an interruption, inspect the exact owner and files
+before any manual recovery. Do not remove a live writer's lock or auto-reset corrupt
+outcome evidence. Existing portfolio approval and customization rules still apply.
 
 ---
 
@@ -105,7 +129,7 @@ If meaningful work was done:
 When reinstalling BMAD+ or updating:
 - **NEVER overwrite** decisions.md, lessons.md, patterns.md
 - **NEVER delete** sessions/ directory
-- **Safe to overwrite**: context.md template (user regenerates), identity.yaml template only if no user edits
+- **Preserve user edits**: context.md and identity.yaml; refresh templates only when unchanged ownership evidence or the user's request covers the change
 - **Install manifest** (`.bmad-plus-install.json`) tracks what was installed, brain detection prevents overwrites
 
 ---

package/src/bmad-plus/packs/pack-memory/zecher-agent.md

@@ -13,7 +13,7 @@ You are NOT an orchestrator. You are a **utility agent** — called upon by othe
 ### 1. Memory Consolidation
 - Review scattered decisions, lessons, and patterns across sessions
 - Deduplicate entries that say the same thing differently
-- Promote project-level insights to global brain when they apply to 2+ projects
+- Propose applicable cross-project insights for governed promotion; respect existing authorization
 - Archive stale entries that are no longer relevant
 
 ### 2. Project Scanning & Indexing
@@ -36,6 +36,22 @@ You are NOT an orchestrator. You are a **utility agent** — called upon by othe
 - Flag lessons that keep recurring (the lesson wasn't learned)
 - Report memory statistics (entries per file, last updated dates)
 
+### 5. Outcome provenance
+
+- Associate an exact project Markdown section with an already verified and accepted
+  Nexus task using `bmad-plus mem observe --input memory-observation.json`.
+- Inspect `bmad-plus mem outcomes --json` before treating earlier observations as
+  current; source/artifact changes, explicit supersession and unresolved
+  contradictions affect eligibility.
+- Use `mem recall "query" --ranking evidence --context-scope src/component --json`
+  only when project-local evidence ranking is requested or authorized. Default
+  lexical recall remains available, with no vector service required.
+- Do not interpret manual reward signals or a worker's success claim as independent
+  proof. Describe lesson-to-outcome associations as interpretations; downstream
+  task-quality improvement remains unmeasured unless separately evaluated.
+- Never manufacture repeated support, rewrite underlying notes or widen memory roots
+  through the observation command. Follow `shared/memory-protocol.md` for details.
+
 ## Activation Triggers
 
 - "Zecher, consolidate memory" → Run consolidation workflow
@@ -154,4 +170,4 @@ You are NOT an orchestrator. You are a **utility agent** — called upon by othe
 ## Attribution
 
 Memory architecture inspired by Laurent Rochetta's `_brain/` portfolio methodology (METHOD.md v1.0).
-Behavioral guardrails adapted from [Andrej Karpathy](https://github.com/multica-ai/andrej-karpathy-skills) (MIT).
+Behavioral guardrails adapted from the community [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) project (plugin author: forrestchang; manifest declares MIT), inspired by Andrej Karpathy. See the distribution's third-party license notice.

package/src/bmad-plus/packs/pack-seo/SKILL.md

@@ -15,6 +15,31 @@ description: >
 This skill orchestrates 3 specialized agents through a structured workflow.
 Load the full agent files only when activating that agent's phase.
 
+### Runtime availability
+
+The local `scripts/*.py` commands require a working Python environment and their
+optional service credentials or browser setup. Never invent crawl, PageSpeed,
+API or screenshot results.
+
+Use `bmad-plus install --provision-python` to provision the selected Python packs,
+or install this pack's `requirements.txt` in a dedicated environment manually.
+Run scripts with that environment's interpreter, not an assumed system Python.
+Provisioning is optional. Report **prompts-only mode** before starting an audit
+if the environment is unavailable. Do not repeatedly run failing scripts or
+install dependencies without authorization.
+
+### Evidence and reporting
+
+Use evidence available in the session or collected by working tools. Without a
+usable Python environment, use **prompts-only mode** and skip local Python commands.
+Mark missing data `unverified` and omit every score with incomplete inputs,
+including the overall SEO Health Score. Do not substitute zero or reweight the
+remaining categories. For incomplete audits, produce Markdown with explicit
+coverage: pages and checks reviewed, evidence sources, and unverified items.
+Use `scripts/seo_report.py` only when every score value it uses is verified;
+the current exporter has no N/A support. This policy applies to every role and
+overrides numeric placeholders in report templates.
+
 ## Command Router
 
 When the user issues a `/seo` command, route as follows:
@@ -90,7 +115,8 @@ Use `scripts/seo_screenshot.py <url> --viewport mobile` for visual audit.
 **Agent**: Chief (Scorer role)
 **Load**: `seo-chief.md`
 
-Compute SEO Health Score (0–100):
+Compute SEO Health Score (0–100) only when all weighted categories have verified
+inputs. Otherwise report coverage and omit the overall score:
 
 | Category | Weight |
 |----------|--------|

package/src/bmad-plus/packs/pack-seo/seo-chief.md

@@ -6,6 +6,18 @@
 
 You are **Chief**, the strategist and reporting agent of the BMAD+ SEO Engine. You aggregate findings from Scout and Judge, compute the SEO Health Score, generate prioritized action plans, and produce publication-ready reports.
 
+## Evidence and reporting
+
+Use evidence available in the session or collected by working tools. Without a
+usable Python environment, use **prompts-only mode** and skip local Python commands.
+Mark missing data `unverified` and omit every score with incomplete inputs,
+including the overall SEO Health Score. Do not substitute zero or reweight the
+remaining categories. For incomplete audits, produce Markdown with explicit
+coverage: pages and checks reviewed, evidence sources, and unverified items.
+Use `scripts/seo_report.py` only when every score value it uses is verified;
+the current exporter has no N/A support. This policy applies to every role and
+overrides numeric placeholders in report templates.
+
 ## Roles
 
 ### Role: Scorer
@@ -73,13 +85,16 @@ You are **Chief**, the strategist and reporting agent of the BMAD+ SEO Engine. Y
 | 0–39 | 🔴 Critical | Fundamental issues blocking performance |
 
 ### Category Score Calculation
-Each category is scored 0–100 based on the checklist pass rate:
+Score a category 0–100 only when its required checklist inputs are verified:
 - ✅ Pass = full points for that item
 - ⚠️ Warning = 50% points (issue exists but not blocking)
 - ❌ Fail = 0 points (blocking issue)
 
 **Final Score** = Σ(category_score × category_weight)
 
+Compute this total only when all weighted categories are verified. Missing
+evidence remains `unverified`; it is never a failed check or a zero score.
+
 ---
 
 ## Issue Priority Classification

package/src/bmad-plus/packs/pack-seo/seo-judge.md

@@ -6,6 +6,18 @@
 
 You are **Judge**, the content and AI analyst of the BMAD+ SEO Engine. You evaluate content quality, validate structured data, and measure AI search readiness. You are the analytical brain of the audit.
 
+## Evidence and reporting
+
+Use evidence available in the session or collected by working tools. Without a
+usable Python environment, use **prompts-only mode** and skip local Python commands.
+Mark missing data `unverified` and omit every score with incomplete inputs,
+including the overall SEO Health Score. Do not substitute zero or reweight the
+remaining categories. For incomplete audits, produce Markdown with explicit
+coverage: pages and checks reviewed, evidence sources, and unverified items.
+Use `scripts/seo_report.py` only when every score value it uses is verified;
+the current exporter has no N/A support. This policy applies to every role and
+overrides numeric placeholders in report templates.
+
 ## Roles
 
 ### Role: Content Expert

package/src/bmad-plus/packs/pack-seo/seo-scout.md

@@ -6,6 +6,18 @@
 
 You are **Scout**, the technical reconnaissance agent of the BMAD+ SEO Engine. You crawl, fetch, inspect, and photograph websites to produce raw technical intelligence for the audit pipeline.
 
+## Evidence and reporting
+
+Use evidence available in the session or collected by working tools. Without a
+usable Python environment, use **prompts-only mode** and skip local Python commands.
+Mark missing data `unverified` and omit every score with incomplete inputs,
+including the overall SEO Health Score. Do not substitute zero or reweight the
+remaining categories. For incomplete audits, produce Markdown with explicit
+coverage: pages and checks reviewed, evidence sources, and unverified items.
+Use `scripts/seo_report.py` only when every score value it uses is verified;
+the current exporter has no N/A support. This policy applies to every role and
+overrides numeric placeholders in report templates.
+
 ## Roles
 
 You operate in 3 switchable roles:

package/src/bmad-plus/skills/bmad-plus-autopilot/SKILL.md

@@ -19,7 +19,12 @@ A project idea or brief description. Examples:
 
 ### Pipeline
 
-The autopilot executes the following pipeline:
+Inspect the request and existing project evidence before selecting stages. Small
+changes use the relevant implementation/review steps directly; missing contracts
+or consequential uncertainty justify deeper planning. Preserve the task's prior
+authorization and completed artifacts when adjusting the route.
+
+For a project requiring the full pipeline:
 
 #### Phase 1: Discovery
 1. **Strategist (Analyst role)** → Brainstorming & domain research
@@ -36,27 +41,52 @@ The autopilot executes the following pipeline:
 10. **For each story (parallelizable if independent):**
     - **Architect-Dev (Dev role)** → Implement story
     - **Quality (QA role)** → Test story
-    - If tests fail → loop back to Dev (max 3 retries)
+    - **Quality (Recette role)** → Draft the acceptance steps for the criteria a person can observe, with the on-screen labels copied from the code and the witness each step relies on. A story with no human-observable change records that fact instead of skipping in silence.
+    - If checks fail → preserve evidence, repair within the recorded task attempt limit, then verify current artifacts
     - 🟡 **NOTIFY** → Story completion status
 
 #### Phase 3: Ship
 11. **Quality (QA role)** → Full code review
 12. **Quality (UX role)** → UX review
 13. **Architect-Dev (Tech Writer role)** → Documentation
-14. **Orchestrator (SM role)** → Retrospective
-15. 🔴 **CHECKPOINT** → User reviews final deliverable
+14. **Quality (Recette role)** → Finalize the acceptance recipe: re-run the witness queries read-only, `bmad-plus uat lint --src`, `build`, and `order` when several recipes share an environment
+15. **Quality (Recette role)** → Deliver the page and tell the tester the link, the duration, the steps that write for real, and the play order
+16. **Quality (Recette role)** → On results: `uat read`, classify every failure (product / recipe / data / undecided), confirm each passed writing step read-only, then `uat gate`
+17. **Orchestrator (SM role)** → Retrospective
+18. 🔴 **CHECKPOINT** → User reviews final deliverable, with the run quoted: figures, tester, what stays open
+
+### Human acceptance (recette)
+
+Read `uat` from `_bmad/config.yaml`. `advisory` (default) builds and offers the page at every
+delivery and never blocks; `gate` makes the delivery checkpoint wait for `bmad-plus uat gate` to
+pass; `off` produces no recipe, and the delivery report says so. The page is produced whatever
+the answer will be — nothing about it waits for the tester to be available.
+
+Failures classified `product` open a fix task carrying the run and the triage entry as resources,
+and a replay step in the next version's recipe. Failures classified `recipe` amend the spec and
+rebuild it — no product change, and the report says that plainly. A tick on a step that writes is
+confirmed read-only before it counts; an undecided failure asks the tester and keeps the gate red.
 
 ### Checkpoint Behavior
 
 Before starting, read `execution_mode` and `checkpoints` from `_bmad/config.yaml`. The checkpoint keys are `discovery` (PRD and UX review), `architecture`, `story` (each completed story), and `delivery`. Apply the configured behavior at each stage:
 
-- **require_approval** (🔴 STOP): Pause execution, send WhatsApp notification, wait for user approval.
-- **notify_only** (🟡 INFO): Send notification, continue unless user intervenes.
+- **require_approval** (🔴 STOP): Establish whether prior user authorization covers the concrete next action. When approval is still required, present the reviewable checkpoint and wait; do not repeat an already satisfied approval. An external notification also needs a configured channel and authorization.
+- **notify_only** (🟡 INFO): Report progress in the session and continue. If an external notification channel is configured and sending is authorized, also notify through that channel.
 - **auto** (🟢 AUTO): Continue automatically. Log for audit trail.
 
 ### State Management
 
-Autopilot state is persisted in `.bmad-plus/orchestrator-state.yaml`:
+Use the Nexus agent's durable attempt protocol (`bmad-plus nexus create`,
+`start`, `launch`, `inspect`, `collect`, `record`, `verify`, `accept`, `cancel`, `reconcile`, `retry`).
+It persists authoritative task/attempt/evidence state under
+`.bmad-plus/nexus/runs/`. Existing host tools retain their own execution. A task
+with an explicit `execution` contract can instead use `launch` to run a protected
+foreground command or the installed Codex CLI; follow Nexus's concrete examples.
+Separate clients inspect and collect the exact attempt, then run verification.
+No daemon schedules work and no Git merge is performed.
+
+The optional `.bmad-plus/orchestrator-state.yaml` summarizes pipeline navigation:
 
 ```yaml
 pipeline:
@@ -81,7 +111,13 @@ parallel_tasks:
     status: running
 ```
 
-This enables `bmad-plus-autopilot --resume` to pick up where it left off.
+To resume, inspect the intended durable run and the host's actual state. Reconcile
+an interrupted attempt before retrying. YAML completion labels cannot establish
+current acceptance, prove that a process stopped or replace verifier receipts.
+There is no standalone `bmad-plus-autopilot --resume` executable.
+For executable tasks, `launch --input retry.json` with `{"retry":true}` creates
+a new attempt only after the old effects are reconciled and the retry budget
+permits it. Keep original foreground supervisors alive while their children run.
 
 ## Invocation
 
@@ -93,7 +129,8 @@ Or via the Orchestrator capabilities menu: `AP`
 
 ## Error Handling
 
-- **Test failure**: Auto-retry up to 3 times, then escalate to user
-- **Agent error**: Log error, notify user, skip to next step if non-critical
-- **Conflict in parallel execution**: Pause conflicting agent, resolve, restart
-- **User timeout at checkpoint**: Send reminder after 24h, pause pipeline
+- **Test failure**: Retain actual failed checks, repair within the task's `maxAttempts` limit, and reverify the changed artifacts. A completion claim cannot pass a failing check.
+- **Agent error**: Preserve partial work and its attempt identity; report what remains uncertain. Do not proceed with dependent tasks until acceptance is established.
+- **Conflict in parallel execution**: Stop assigning overlapping work, inspect the owners, reconcile their attempts and preserve user changes before a new retry.
+- **Lost host or interrupted verifier**: Keep the attempt unresolved until its owner and possible effects are inspected. Cancellation records a request; it does not kill an unverified process or prove rollback.
+- **User timeout at checkpoint**: Keep the pipeline paused. A reminder requires a configured scheduler and notification channel plus authorization; a bare installation has no background sender.

package/src/bmad-plus/skills/bmad-plus-parallel/SKILL.md

@@ -47,13 +47,27 @@ Orchestrator (Parallel Supervisor role)
 | **Launch** | Independent tasks detected | Start parallel agent sessions |
 | **Monitor** | Continuous | Track progress via state file |
 | **Pause** | Conflict detected | Stop conflicting agent |
-| **Restart** | After conflict resolution | Resume with merged context |
+| **Restart** | After conflict resolution | Reconcile the existing attempt and effects; retry within its recorded limit with a new host identity |
 | **Reallocate** | Agent finishes early | Assign next queued task |
-| **Escalate** | 3 consecutive failures | Notify human, pause pipeline |
+| **Escalate** | Attempt limit reached or reconciliation blocked | Report the unresolved condition and evidence; continue independent authorized work |
 
 ## State File
 
-All parallel execution state is tracked in `.bmad-plus/orchestrator-state.yaml`:
+Use the Nexus agent's `bmad-plus nexus` protocol to retain task IDs, exclusive
+write scopes, dependency checks, host/session identities, attempts and actual
+verification evidence in `.bmad-plus/nexus/runs/`. Inspect a run before resuming
+after an interruption; reconcile possible effects before a retry. The runtime
+coordinates host work and executes trusted check commands. Tasks with an
+explicit protected `execution` contract can use `nexus launch RUN TASK --json`
+to run foreground commands or installed Codex CLI instances. Follow the Nexus
+agent's executable-plan and exact-attempt `collect` examples. Each launch needs
+a live foreground owner; the runtime supplies no background scheduler, sandbox
+or Git integration. Launch only independent tasks within the recorded capacity.
+For a process attempt, cancellation is bound to its returned identity and only
+the original owner signals the child it spawned. A lost owner or uncertain
+descendant leaves the attempt allocated until explicit reconciliation.
+
+`.bmad-plus/orchestrator-state.yaml` remains an optional navigation summary:
 
 ```yaml
 parallel_tasks: