bmad-method 6.11.1-next.8 → 6.12.0

package/src/core-skills/bmad-party-mode/customize.toml

@@ -22,10 +22,10 @@ activation_steps_append = []
 # Persistent facts the orchestrator keeps in mind for the whole session
 # (house rules, running gags, topics to avoid). Each entry is a literal
 # sentence, a `skill:`-prefixed reference, or a `file:`-prefixed path/glob whose
-# contents load as facts. Default picks up project-context.md if one exists.
-persistent_facts = [
-  "file:{project-root}/**/project-context.md",
-]
+# contents load as facts. Empty by default — repo-wide context belongs in AGENTS.md
+# (see bmad-project-context), which every skill already sees. Use this for context only
+# the party needs, loaded on demand rather than carried as constant memory.
+persistent_facts = []
 
 # Which party loads when the user just says "party mode" with no override.
 # Empty = the installed BMAD agents — exactly the default behavior of a plain

package/src/core-skills/bmad-party-mode/references/create-party.md

@@ -30,7 +30,7 @@ Ask which they're after if it isn't obvious, then proceed.
 
 ## Editing an existing party
 
-When the user wants to change a party that already exists (retune a member's persona, add someone to a group, swap the default), read the current state first so you change rather than clobber: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow` returns the merged `party_members`, `party_groups`, and `default_party`. Show the member or group being touched, capture only the delta with the user, and hand that sparse change to `bmad-customize` — it replaces a `party_members`/`party_groups` entry whose `code`/`id` matches and appends the rest, so an edit is just the changed entry, never a full rewrite.
+When the user wants to change a party that already exists (retune a member's persona, add someone to a group, swap the default), read the current state first so you change rather than clobber: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow` returns the merged `party_members`, `party_groups`, and `default_party`. Show the member or group being touched, capture only the delta with the user, and hand that sparse change to `bmad-customize` — it replaces a `party_members`/`party_groups` entry whose `code`/`id` matches and appends the rest, so an edit is just the changed entry, never a full rewrite.
 
 ## Keeping new faces from a session
 

package/src/core-skills/bmad-party-mode/scripts/resolve_party.py

@@ -71,7 +71,9 @@ def load_agents(project_root: Path):
 def load_workflow(project_root: Path, skill_root: Path):
     """Merged [workflow] table. Falls back to the skill's base customize.toml."""
     script = project_root / "_bmad" / "scripts" / "resolve_customization.py"
-    data = _run_json([sys.executable, str(script), "--skill", str(skill_root), "--key", "workflow"])
+    data = _run_json(
+        [sys.executable, str(script), "--skill", str(skill_root), "--project-root", str(project_root), "--key", "workflow"]
+    )
     if data is not None and "workflow" in data:
         return data["workflow"]
     # Fallback: read the skill's base customize.toml directly (no override merge).

package/src/core-skills/bmad-party-mode/scripts/tests/test_resolve_party.py

@@ -5,6 +5,7 @@
 """Unit tests for resolve_party.py — merge, alias, override, group resolution."""
 
 import sys
+import tempfile
 import unittest
 from pathlib import Path
 
@@ -142,5 +143,26 @@ class TestInstalledCodesIsDefaultRoom(unittest.TestCase):
         self.assertEqual(col["bmad-agent-analyst"]["name"], "Mary-Custom")
 
 
+class TestResolverInvocation(unittest.TestCase):
+    """The wrapper knows the project root, so it must not let the resolver
+    infer one from the working directory (#2796)."""
+
+    def _captured_command(self, tmp):
+        captured = []
+        original = rp._run_json
+        rp._run_json = lambda cmd: captured.append(cmd) or {"workflow": {}}
+        try:
+            rp.load_workflow(Path(tmp) / "project", Path(tmp) / "skill")
+        finally:
+            rp._run_json = original
+        return captured[0]
+
+    def test_passes_project_root_to_the_customization_resolver(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            cmd = self._captured_command(tmp)
+            self.assertIn("--project-root", cmd)
+            self.assertEqual(cmd[cmd.index("--project-root") + 1], str(Path(tmp) / "project"))
+
+
 if __name__ == "__main__":
     unittest.main()

package/src/core-skills/bmad-review/SKILL.md

@@ -14,6 +14,7 @@ The lens set is whatever `{workflow.lenses}` resolves to, not a fixed list — o
 - **content** — what to review: a diff, branch, uncommitted changes, file, spec, story, or any document. Args: `[path]`.
 - **lenses** (optional) — one or more lens codes or names, however the caller expresses them: a spoken request, or a directive of the form `skill:bmad-review lenses=<code>[,<code>...]` (the form bmm's `doc_standards` uses). Default: every applicable lens (a full review).
 - **also_consider** (optional) — areas to keep in mind alongside each lens's normal analysis.
+- **claims** (optional) — the change's own narrative: the commit messages it covers, or whatever description of it the caller supplied. Goes to the edge-case lens alone.
 - **pre-resolved customization** (optional) — `[workflow]` field values supplied by a forwarding caller. See Execution step 1.
 
 ## Conventions
@@ -24,12 +25,12 @@ The lens set is whatever `{workflow.lenses}` resolves to, not a fixed list — o
 
 ## Execution
 
-1. **Resolve customization:** `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults. **Forwarded activation:** if a caller invoked you with pre-resolved customization fields (e.g. the `bmad-editorial-review` shim), honor them verbatim for those named fields — they already carry the user's overrides — and resolve only the remaining fields from your own `customize.toml`. Then execute each `{workflow.activation_steps_prepend}` entry in order, hold `{workflow.persistent_facts}` as standing context for the session, and treat `{workflow.review_guidance}` entries as standing review directives for every lens.
-2. **Load the content.** If it is empty or cannot be decoded as text: when the caller expects the raw findings JSON array (e.g. the legacy edge-case forwarder), return `[{"location":"N/A","trigger_condition":"Input empty or undecodable","guard_snippet":"Provide valid content to review","potential_consequence":"Review skipped — no analysis performed"}]` (no `lens` field) and stop; otherwise say what's wrong and ask for reviewable content. Classify the content — diff, source file, function, or document — and whether it is **code** or **docs**; scope rules and lens applicability both depend on it. A document that defines behavior (spec, requirements, plan, story) is `docs` that a behavioral lens may still apply to; judge by `when`.
+1. **Resolve customization:** `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults. **Forwarded activation:** if a caller invoked you with pre-resolved customization fields (e.g. the `bmad-editorial-review` shim), honor them verbatim for those named fields — they already carry the user's overrides — and resolve only the remaining fields from your own `customize.toml`. Then execute each `{workflow.activation_steps_prepend}` entry in order, hold `{workflow.persistent_facts}` as standing context for the session, and treat `{workflow.review_guidance}` entries as standing review directives for every lens.
+2. **Load the content.** Stage it once as a file: when the content is a branch, uncommitted work, or a commit range, use the repository's version-control tooling to write the unified diff to a uniquely-named file in the system temp directory and take that file's absolute path as the content. A branch means its diff against the merge base with its base branch; uncommitted work includes untracked files. Stage `claims` to its own file the same way — it is input for one lens, staged separately precisely so the other lenses never see it. If the content is empty or cannot be decoded as text: when the caller expects the raw findings JSON array (e.g. the legacy edge-case forwarder), return `[{"location":"N/A","trigger_condition":"Input empty or undecodable","guard_snippet":"Provide valid content to review","potential_consequence":"Review skipped — no analysis performed"}]` (no `lens` field) and stop; otherwise say what's wrong and ask for reviewable content. Classify the content — diff, source file, function, or document — and whether it is **code** or **docs**; scope rules and lens applicability both depend on it. A document that defines behavior (spec, requirements, plan, story) is `docs` that a behavioral lens may still apply to; judge by `when`.
 3. **Select lenses** from `{workflow.lenses}`. A lens with an empty `instruction` is disabled. If the user or caller named lenses, run exactly those only — `applies_to` and `when` do not filter an explicit request. Otherwise run every enabled lens whose `applies_to` covers the content class (`any` always covers) and whose `when` applies.
 4. **Announce the plan** in one line before running anything: the content class, the lenses about to run, and — when any lens has `after` set — that it runs on top of the named lens's findings. Skip the announcement entirely when the caller pinned an exact output contract (the legacy forwarders that demand raw JSON or one exact line) — their contract covers everything you emit, not just the findings block. Then execute each `{workflow.activation_steps_append}` entry in order.
-5. **Run the independent lenses** — every selected lens without `after`. Each sees the content and `also_consider`, never another lens's findings. Follow each lens's `instruction`; the shipped lenses load their reference file just-in-time, so load only what runs. When subagents are available, spawn one per lens in parallel: give it the lens `instruction` with `{skill-root}` and paths resolved absolute, the content or where to read it, any `also_consider` areas, the standing review directives, and the constraint "Return ONLY your findings — no other output." Otherwise run the lenses sequentially yourself, completing one before starting the next.
-6. **Run the dependent lenses** — every selected lens with `after`, once the lens it names has completed, passing that lens's findings in. A lens whose `after` target was not selected or produced nothing still runs, with no prior findings. Dependent lenses that name different targets are independent of each other and may run in parallel.
+5. **Run the independent lenses** — every selected lens without `after`. Each sees the content and `also_consider`, never another lens's findings. Follow each lens's `instruction`; the shipped lenses load their reference file just-in-time, so load only what runs. When subagents are available, launch every independent lens before handling any lens's result. Try running them simultaneously: spawn one per lens; give it the lens `instruction` with `{skill-root}` and paths resolved absolute, the absolute path of the staged content file (a lens prompt carries the path and the lens reads the file, never the content bytes; inline the content only when it was never staged as a file), any `also_consider` areas, the standing review directives, the `claims` path to the edge-case lens alone (marked to leave unread until its instructions call for it), and the constraint "Return ONLY your findings — no other output. Do not invoke any skill, and do not spawn subagents of your own — you are the reviewer. Return your findings as text in your final message; do not route them through any findings-reporting tool the host may offer." Otherwise run the lenses sequentially yourself, completing one before starting the next.
+6. **Run the dependent lenses** — every selected lens with `after`, once the lens it names has completed, passing that lens's findings in. A lens whose `after` target was not selected or produced nothing still runs, with no prior findings. Dependent lenses that name different targets are independent of each other: launch every ready one before handling any of their results. Try running them simultaneously. When subagents are available, spawn them with the same constraint as independent lenses: "Return ONLY your findings — no other output. Do not invoke any skill, and do not spawn subagents of your own — you are the reviewer. Return your findings as text in your final message; do not route them through any findings-reporting tool the host may offer."
 7. **Assemble and present** per Output below. Keep every lens's findings — overlap between lenses is signal, not duplication; note it in the markdown report rather than deduping. Execute `{workflow.on_complete}` if set.
 
 ## Output

package/src/core-skills/bmad-review/customize.toml

@@ -23,7 +23,7 @@ activation_steps_append = []
 # prefixed `file:` are paths or globs whose contents load as facts; all others
 # are literal facts. The shipped entry is a project-wide glob — set it to []
 # if you don't want every review scanning for it.
-persistent_facts = ["file:{project-root}/**/project-context.md"]
+persistent_facts = []
 
 # Standing review directives applied on every run alongside each lens's own
 # method. Each entry is a literal sentence or a `file:`-prefixed path/glob

package/src/core-skills/bmad-review/references/lens-edge-case-hunter.md

@@ -9,6 +9,7 @@ You are a pure path tracer. Never comment on whether the content is good or bad;
 - When the content is a diff, scan only the diff hunks and list boundaries that are directly reachable from the changed lines and lack an explicit guard in the diff.
 - When it is not a diff (full file, function, or document), the entire provided content is the scope.
 - Ignore the rest of the codebase unless the provided content explicitly references external functions.
+- When the launch message names a claims file, do NOT read it before Step 4: the path tracing in Steps 1–2 must finish before the narrative is seen.
 
 ## Step 1: Exhaustive path analysis
 
@@ -17,6 +18,8 @@ Walk every branching path and boundary condition within scope — report only un
 - If `also_consider` areas were provided, incorporate them into the analysis
 - Walk all branching paths: control flow (conditionals, loops, error handlers, early returns) and domain boundaries (where values, states, or conditions transition). Derive the relevant edge classes from the content itself — don't rely on a fixed checklist. Examples: missing else/default, unguarded inputs, off-by-one loops, arithmetic overflow, implicit type coercion, race conditions, timeout gaps
 - Consider implicit branches: the diff special-cases or changes the handling of one or more members of a fixed set of values — enums, status codes, sentinels, type tags, flags, value ranges. The rest of the set is implicit branches (e.g. the diff changes the `RED` and `YELLOW` cases of a `RED`/`YELLOW`/`GREEN` enum; `GREEN` is the implicit branch)
+- Consider handle lifetime: when the changed code re-checks, re-fetches, or re-validates something it already held — a handle, index, id, pointer — the re-check exists because an intervening call can invalidate it. Identify that call, what it does to the thing held, and what the changed code silently skips when the re-check fails
+- For each call site the diff adds or changes — in test files as well as production code — read the callee's declaration and check the call against it: argument count, order, types, and defaults. Report any mismatch
 - For each path: determine whether the content handles it
 - Collect only the unhandled paths as findings — discard handled ones silently
 
@@ -38,6 +41,21 @@ Deletion findings go in the same array with the four standard fields plus:
 
 For a deletion finding the standard fields read as: `location` = the removed item; `trigger_condition` = the behavior or contract it enforced; `guard_snippet` = where or how to re-establish it; `potential_consequence` = the regression or orphan.
 
+## Step 4: Claims check
+
+Runs only when the message that launched you named a claims file. Read that file now, for the first time; the path tracing is finished and the claims cannot steer it retroactively.
+
+The file holds the change's own narrative — commit messages and any stated description. The narrative is the author's testimony, not evidence: a claim repeated in a code comment is still the same claim, not confirmation. Extract each checkable claim — what the change does, what it preserves, ordering, arithmetic, and parity with existing code ("exactly as X does") — then try to falsify each one against the code you have already traced. Where your trace is not enough to decide, read the code that decides it: the compared-to function, the actual callee, the state the claim assumes.
+
+Claim findings go in the same array with the four standard fields plus:
+
+- `kind`: `"claim"`
+- `confidence`: `"high"`, `"medium"`, or `"low"`
+
+For a claim finding the standard fields read as: `location` = where the code contradicts the claim; `trigger_condition` = the claim, quoted or tightly paraphrased; `guard_snippet` = what the code actually does; `potential_consequence` = what goes wrong for someone who believed the claim.
+
+Verified claims produce nothing. Add nothing if nothing is falsified.
+
 ## Findings shape
 
 Each edge-case finding contains exactly these four fields:

package/src/core-skills/module-help.csv

@@ -1,5 +1,5 @@
 module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
-Core,_meta,,,,,,,,,false,https://docs.bmad-method.org/llms.txt,
+Core,_meta,,,,,,,,,false,https://docs.bmad-method.org/,
 Core,bmad-brainstorming,Brainstorming,BSP,Use early in ideation or when stuck generating ideas.,,,anytime,,,false,{output_folder}/brainstorming,brainstorming session
 Core,bmad-party-mode,Party Mode,PM,Orchestrate multi-agent discussions when you need multiple perspectives or want agents to collaborate.,,,anytime,,,false,,
 Core,bmad-help,BMad Help,BH,,,,anytime,,,false,,

package/src/scripts/resolve_config.py

@@ -34,6 +34,14 @@ def extract_key(data, dotted_key: str):
     return current
 
 
+def write_json_stdout(output) -> None:
+    """Pin stdout to UTF-8 — a Windows cp1252 default cannot encode emoji icons."""
+    reconfigure = getattr(sys.stdout, "reconfigure", None)
+    if reconfigure is not None:
+        reconfigure(encoding="utf-8")
+    sys.stdout.write(json.dumps(output, indent=2, ensure_ascii=False) + "\n")
+
+
 def main() -> int:
     parser = argparse.ArgumentParser(
         description="Resolve BMad central config using four-layer TOML merge."
@@ -66,7 +74,7 @@ def main() -> int:
             value = extract_key(merged, key)
             if value is not _MISSING:
                 output[key] = value
-    sys.stdout.write(json.dumps(output, indent=2, ensure_ascii=False) + "\n")
+    write_json_stdout(output)
     return 0
 
 

package/src/scripts/resolve_customization.py

@@ -25,15 +25,77 @@ _MISSING = object()
 
 
 def find_project_root(start: Path) -> Path | None:
+    """Nearest ancestor holding `_bmad/`, falling back to the nearest holding `.git`.
+
+    `_bmad/` outranks `.git` at every depth: a submodule or nested repo carries
+    `.git` without being the BMad project, so treating the two as equal stops the
+    walk short of the root that owns `_bmad/custom/`.
+    """
+    git_root: Path | None = None
     current = start.resolve()
     while True:
-        if (current / "_bmad").exists() or (current / ".git").exists():
+        if (current / "_bmad").is_dir():
             return current
+        if git_root is None and (current / ".git").exists():
+            git_root = current
         if current.parent == current:
-            return None
+            return git_root
         current = current.parent
 
 
+def script_project_root() -> Path | None:
+    """Project root implied by this script's own install path.
+
+    Skills invoke `{project-root}/_bmad/scripts/resolve_customization.py`, so when
+    this file sits at that path its grandparent is a project root the caller already
+    resolved.
+    """
+    parents = Path(__file__).resolve().parents
+    if len(parents) >= 3 and parents[0].name == "scripts" and parents[1].name == "_bmad":
+        return parents[2]
+    return None
+
+
+def candidate_project_roots(skill_dir: Path) -> list[Path]:
+    """Plausible project roots, most trustworthy first.
+
+    The working directory leads because the project is where the user is working,
+    not where the skill happens to be installed — a home-installed skill walks up to
+    `~`, and any `~/_bmad` there would otherwise mask the real project's overrides.
+    """
+    ordered: list[Path] = []
+    for root in (
+        find_project_root(Path.cwd()),
+        script_project_root(),
+        find_project_root(skill_dir),
+    ):
+        if root is not None and root not in ordered:
+            ordered.append(root)
+    return ordered
+
+
+def has_override(root: Path, skill_name: str) -> bool:
+    custom_dir = root / "_bmad" / "custom"
+    return any(
+        (custom_dir / name).is_file()
+        for name in (f"{skill_name}.toml", f"{skill_name}.user.toml")
+    )
+
+
+def warn_on_masked_override(chosen: Path, rejected: list[Path], skill_name: str) -> None:
+    """Break the silence when a real override exists under a root we did not pick."""
+    if has_override(chosen, skill_name):
+        return
+    for root in rejected:
+        if has_override(root, skill_name):
+            sys.stderr.write(
+                f"note: resolved project root {chosen} has no customization for "
+                f"`{skill_name}`, but {root} does. Using {chosen}; pass "
+                f"--project-root to select the other explicitly.\n"
+            )
+            return
+
+
 def extract_key(data, dotted_key: str):
     current = data
     for part in dotted_key.split("."):
@@ -73,11 +135,14 @@ def main() -> int:
     args = parser.parse_args()
 
     skill_dir = Path(args.skill).resolve()
-    project_root = (
-        Path(args.project_root).resolve()
-        if args.project_root
-        else find_project_root(skill_dir) or find_project_root(Path.cwd())
-    )
+    if args.project_root:
+        project_root = Path(args.project_root).resolve()
+    else:
+        candidates = candidate_project_roots(skill_dir)
+        project_root = candidates[0] if candidates else None
+        if project_root is not None:
+            warn_on_masked_override(project_root, candidates[1:], skill_dir.name)
+
     try:
         merged = load_customization(project_root, skill_dir)
     except ConfigError as error:

package/src/scripts/tests/test_resolve_config.py

@@ -1,4 +1,5 @@
 import json
+import os
 import shutil
 import subprocess
 import sys
@@ -74,6 +75,33 @@ class ResolveConfigCliTests(unittest.TestCase):
             self.assertNotEqual(result.returncode, 0)
             self.assertIn("failed to parse", result.stderr)
 
+    def test_writes_emoji_json_when_stdout_encoding_is_cp1252(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            root = Path(temp_dir)
+            (root / "_bmad").mkdir(parents=True)
+            (root / "_bmad" / "config.toml").write_text(
+                '[agents]\nname = "Analyst"\nicon = "📊"\n',
+                encoding="utf-8",
+            )
+
+            env = os.environ.copy()
+            env["PYTHONIOENCODING"] = "cp1252"
+            result = subprocess.run(
+                [sys.executable, str(SCRIPT), "--project-root", str(root)],
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                env=env,
+                check=False,
+            )
+
+            stderr = result.stderr.decode("utf-8", errors="replace")
+            self.assertEqual(result.returncode, 0, msg=stderr)
+
+            output = result.stdout.decode("utf-8")
+            self.assertIn("📊", output)
+            resolved = json.loads(output)
+            self.assertEqual(resolved["agents"]["icon"], "📊")
+
     @staticmethod
     def _run(root: Path, *args: str) -> subprocess.CompletedProcess[str]:
         return subprocess.run(

package/src/scripts/tests/test_resolve_customization.py

@@ -73,5 +73,107 @@ class ResolveCustomizationStdoutTests(unittest.TestCase):
             self.assertEqual(resolved["agent"]["icon"], "🧭")
 
 
+def write(path: Path, body: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(body, encoding="utf-8")
+
+
+def facts(*entries: str) -> str:
+    listed = ", ".join(f'"{entry}"' for entry in entries)
+    return f"[workflow]\npersistent_facts = [{listed}]\n"
+
+
+def resolve(skill_dir: Path, cwd: Path, *extra: str):
+    return subprocess.run(
+        [sys.executable, str(SCRIPT), "--skill", str(skill_dir), "--key", "workflow", *extra],
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        cwd=str(cwd),
+        check=False,
+    )
+
+
+class ProjectRootResolutionTests(unittest.TestCase):
+    """Regression cover for #2796 — the project is where the user works, not
+    where the skill is installed."""
+
+    def test_home_installed_skill_reads_project_override_not_home_bmad(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            home = Path(temp_dir) / "home"
+            project = Path(temp_dir) / "project"
+            skill = home / ".claude" / "skills" / "demo-skill"
+            write(skill / "customize.toml", facts("shipped default"))
+            (home / "_bmad" / "custom").mkdir(parents=True)
+            write(project / "_bmad" / "custom" / "demo-skill.toml", facts("team override"))
+
+            result = resolve(skill, project)
+
+            self.assertEqual(result.returncode, 0, msg=result.stderr)
+            resolved = json.loads(result.stdout)["workflow"]["persistent_facts"]
+            self.assertEqual(resolved, ["shipped default", "team override"])
+
+    def test_project_installed_skill_still_resolves(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            project = Path(temp_dir) / "project"
+            skill = project / ".claude" / "skills" / "demo-skill"
+            write(skill / "customize.toml", facts("shipped default"))
+            write(project / "_bmad" / "custom" / "demo-skill.toml", facts("team override"))
+
+            result = resolve(skill, project)
+
+            self.assertEqual(result.returncode, 0, msg=result.stderr)
+            resolved = json.loads(result.stdout)["workflow"]["persistent_facts"]
+            self.assertEqual(resolved, ["shipped default", "team override"])
+
+    def test_walk_prefers_bmad_over_a_nearer_git_directory(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            project = Path(temp_dir) / "project"
+            submodule = project / "vendor" / "sub"
+            skill = Path(temp_dir) / "skills" / "demo-skill"
+            write(skill / "customize.toml", facts("shipped default"))
+            write(project / "_bmad" / "custom" / "demo-skill.toml", facts("team override"))
+            (submodule / ".git").mkdir(parents=True)
+
+            result = resolve(skill, submodule)
+
+            self.assertEqual(result.returncode, 0, msg=result.stderr)
+            resolved = json.loads(result.stdout)["workflow"]["persistent_facts"]
+            self.assertEqual(resolved, ["shipped default", "team override"])
+
+    def test_notes_when_a_rejected_root_holds_the_only_override(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            home = Path(temp_dir) / "home"
+            project = Path(temp_dir) / "project"
+            skill = home / ".claude" / "skills" / "demo-skill"
+            write(skill / "customize.toml", facts("shipped default"))
+            write(home / "_bmad" / "custom" / "demo-skill.toml", facts("home override"))
+            (project / "_bmad" / "custom").mkdir(parents=True)
+
+            result = resolve(skill, project)
+
+            self.assertEqual(result.returncode, 0, msg=result.stderr)
+            resolved = json.loads(result.stdout)["workflow"]["persistent_facts"]
+            self.assertEqual(resolved, ["shipped default"])
+            self.assertIn("demo-skill", result.stderr)
+            self.assertIn("--project-root", result.stderr)
+
+    def test_explicit_project_root_wins_and_stays_quiet(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            home = Path(temp_dir) / "home"
+            project = Path(temp_dir) / "project"
+            skill = home / ".claude" / "skills" / "demo-skill"
+            write(skill / "customize.toml", facts("shipped default"))
+            write(home / "_bmad" / "custom" / "demo-skill.toml", facts("home override"))
+            (project / "_bmad" / "custom").mkdir(parents=True)
+
+            result = resolve(skill, project, "--project-root", str(home))
+
+            self.assertEqual(result.returncode, 0, msg=result.stderr)
+            resolved = json.loads(result.stdout)["workflow"]["persistent_facts"]
+            self.assertEqual(resolved, ["shipped default", "home override"])
+            self.assertEqual(result.stderr, "")
+
+
 if __name__ == "__main__":
     unittest.main()

package/tools/installer/core/installer.js

@@ -13,7 +13,14 @@ const { InstallPaths } = require('./install-paths');
 const { ExternalModuleManager } = require('../modules/external-manager');
 const { resolveModuleVersion } = require('../modules/version-resolver');
 const { MODULE_HELP_CSV_HEADER } = require('../modules/module-help-schema');
-const { inferShimPreference, readInstalledSkillIds } = require('./shim-policy');
+const {
+  formatRemovedShimNotice,
+  formatRetainedShimNotice,
+  inferShimPreference,
+  readInstalledShims,
+  readInstalledSkillIds,
+  selectShimOutcome,
+} = require('./shim-policy');
 
 const { ExistingInstall } = require('./existing-install');
 const { warnPreNativeSkillsLegacy } = require('./legacy-warnings');
@@ -59,6 +66,24 @@ class Installer {
         }),
       };
 
+      const installedShims = existingInstall.installed ? await readInstalledShims(paths.bmadDir) : [];
+      const { retained: retainedShims, removed: removedShims } = selectShimOutcome({
+        installedShims,
+        availableShims,
+        install: shimPolicy.install,
+      });
+
+      // Reported here, not at the prompt, so --yes/--shims/scripted runs get it too.
+      if (retainedShims.length > 0) {
+        await prompts.note(formatRetainedShimNotice(retainedShims), 'Deprecated shim skills retained');
+      }
+      if (removedShims.length > 0) {
+        await prompts.note(formatRemovedShimNotice(removedShims, { canReinstall: shimPolicy.available }), 'Deprecated shim skills removed');
+      }
+
+      // The notices above scroll away on a long install; repeat them in the summary.
+      const shimStatus = { retained: retainedShims.length, removed: removedShims.length };
+
       try {
         await warnPreNativeSkillsLegacy({
           projectRoot: paths.projectRoot,
@@ -132,6 +157,7 @@ class Installer {
         customFiles: restoreResult.customFiles.length > 0 ? restoreResult.customFiles : undefined,
         modifiedFiles: restoreResult.modifiedFiles.length > 0 ? restoreResult.modifiedFiles : undefined,
         preInstallVersions,
+        shimStatus,
       });
 
       return {
@@ -1261,6 +1287,12 @@ class Installer {
     if (context.modifiedFiles && context.modifiedFiles.length > 0) {
       lines.push(`  ${color.yellow(`Modified files backed up (.bak): ${context.modifiedFiles.length}`)}`);
     }
+    if (context.shimStatus?.retained > 0) {
+      lines.push(`  ${color.yellow(`Deprecated shim skills retained: ${context.shimStatus.retained}`)} (re-run to remove them)`);
+    }
+    if (context.shimStatus?.removed > 0) {
+      lines.push(`  ${color.green(`Deprecated shim skills removed: ${context.shimStatus.removed}`)}`);
+    }
 
     // Next steps
     lines.push(

package/tools/installer/core/shim-policy.js

@@ -37,6 +37,7 @@ async function discoverShims(modulePath) {
       if (isShimSkill(metadata)) {
         shims.push({
           id: metadata.name || path.basename(dir),
+          description: typeof metadata.description === 'string' ? metadata.description : '',
           directory: dir,
           relativeDirectory: path.relative(modulePath, dir),
         });
@@ -54,25 +55,40 @@ async function discoverShims(modulePath) {
   return shims;
 }
 
-async function readInstalledSkillIds(bmadDir) {
-  const ids = new Set();
+async function readSkillManifest(bmadDir) {
   const manifestPath = path.join(bmadDir, '_config', 'skill-manifest.csv');
-  if (!(await fs.pathExists(manifestPath))) return ids;
+  if (!(await fs.pathExists(manifestPath))) return [];
 
   try {
     const content = await fs.readFile(manifestPath, 'utf8');
-    const records = csv.parse(content, { columns: true, skip_empty_lines: true });
-    for (const record of records) {
-      if (record.canonicalId) ids.add(record.canonicalId);
-    }
+    return csv.parse(content, { columns: true, skip_empty_lines: true });
   } catch {
     // A missing or unreadable legacy manifest means there is no reliable
     // evidence that compatibility shims were installed.
+    return [];
   }
+}
 
+async function readInstalledSkillIds(bmadDir) {
+  const ids = new Set();
+  for (const record of await readSkillManifest(bmadDir)) {
+    if (record.canonicalId) ids.add(record.canonicalId);
+  }
   return ids;
 }
 
+// The installed manifest carries no lifecycle column, so the description
+// prefix every shim ships with is the only record of what was a shim. This
+// is the same signal validate_skills.py uses to exempt them.
+async function readInstalledShims(bmadDir) {
+  const shims = [];
+  for (const record of await readSkillManifest(bmadDir)) {
+    if (!record.canonicalId || !/^\s*deprecated\b/i.test(record.description || '')) continue;
+    shims.push({ id: record.canonicalId, description: record.description || '', module: record.module || '' });
+  }
+  return shims;
+}
+
 function inferShimPreference({ requested, persisted, availableShims = [], installedSkillIds = new Set(), existing = false }) {
   if (availableShims.length === 0) return false;
   if (typeof requested === 'boolean') return requested;
@@ -82,10 +98,62 @@ function inferShimPreference({ requested, persisted, availableShims = [], instal
   return availableShims.some((shim) => installedSkillIds.has(shim.id));
 }
 
+// Removal is driven by what is installed, not by what this release ships: a
+// shim retired from source is still deleted by the update cleanup.
+function selectShimOutcome({ installedShims = [], availableShims = [], install = false }) {
+  const availableShimIds = new Set(availableShims.map((shim) => shim.id));
+  return {
+    retained: install ? availableShims : [],
+    removed: installedShims.filter((shim) => !(install && availableShimIds.has(shim.id))),
+  };
+}
+
+// Shim descriptions all open with "Deprecated — "; the notice heading says it once.
+function describeShim(shim) {
+  const cleaned = (shim.description || '').replace(/^\s*deprecated\s*[-–—:]*\s*/i, '').trim();
+  const source = shim.module ? ` (${shim.module})` : '';
+  return cleaned ? `  ${shim.id}${source}: ${cleaned}` : `  ${shim.id}${source}`;
+}
+
+function formatRetainedShimNotice(availableShims = []) {
+  const lines = availableShims.map((shim) => describeShim(shim)).sort();
+
+  return [
+    `${availableShims.length} deprecated shim skill(s) are still installed. Each one only forwards to the skill that replaced it:`,
+    '',
+    ...lines,
+    '',
+    'Shims will be removed with v7, and anything still calling the old name stops working then.',
+    'Only keep a shim if you customized it and still need to move that customization to the replacement.',
+    'Once you have, re-run Quick Update and answer No to this question so the shims come off.',
+  ].join('\n');
+}
+
+function formatRemovedShimNotice(removedShims = [], { canReinstall = true } = {}) {
+  const lines = removedShims.map((shim) => describeShim(shim)).sort();
+  const recovery = canReinstall
+    ? 'these shims, move it to the replacement, or re-run with --shims to put the shims back.'
+    : 'these shims, move it to the replacement. This release no longer ships them, so --shims cannot bring them back.';
+
+  return [
+    `${removedShims.length} deprecated shim skill(s) are being removed. Invoking these names will no longer work:`,
+    '',
+    ...lines,
+    '',
+    'Each replacement named above is installed and ready. If you still had a customization on one of',
+    recovery,
+  ].join('\n');
+}
+
 module.exports = {
+  describeShim,
+  formatRemovedShimNotice,
   discoverShims,
+  formatRetainedShimNotice,
   inferShimPreference,
   isShimSkill,
   parseSkillMetadata,
+  readInstalledShims,
   readInstalledSkillIds,
+  selectShimOutcome,
 };