@skyf0xx/hedgehog 6.4.0 → 6.4.2

package/bin/cli.mjs

@@ -105,7 +105,12 @@ import { NOOP_DIR } from '../src/db/noop.mjs';
 import { runFastpath, loadFastpaths, orphanedFastpathTasks, FASTPATH_DIR } from '../src/db/fastpath.mjs';
 import { HOSTS, HOST_FLAGS, DEFAULT_HOST, availableHosts } from '../src/hosts/index.mjs';
 import { recordHosts, installedHosts } from '../src/hosts/installed.mjs';
-import { wrapSection, stripPhaseBlocks } from '../src/hosts/claude-md-merge.mjs';
+import {
+  wrapSection,
+  stripPhaseBlocks,
+  hasCoreSection,
+  appendCoreSection,
+} from '../src/hosts/claude-md-merge.mjs';
 import {
   recordVersion,
   checkForUpdate,
@@ -491,9 +496,9 @@ const PHASE_NAME = 'bootstrap-only';
 // astro.config.mjs, which the engine has no business knowing about. Both
 // must hold: a build graph exists, and at least one task has been
 // compiled into it. The bootstrap file's own {{PROJECT_SUMMARY}}
-// placeholder is the third condition (see shedCommand and
-// writePlannedFile's self-heal) but is checked per-file, since a
-// multi-host project can have several bootstrap files to test.
+// placeholder is the third condition (see summaryUnfilled) but is
+// checked per-file, since a multi-host project can have several
+// bootstrap files to test.
 async function graphPastBootstrap() {
   if (!(await exists(DB_PATH))) return false;
   const db = openDb();
@@ -504,9 +509,18 @@ async function graphPastBootstrap() {
   }
 }
 
+// The shell's placeholder carries its own instructions inside the braces
+// (`{{PROJECT_SUMMARY — 2–4 sentences…}}`), so the match is on the prefix.
+// Bootstrap-only blocks are excluded because the shell's first-message
+// block names the placeholder in prose, and that block is exactly what
+// shedding removes.
+function summaryUnfilled(bootstrapContent) {
+  return stripPhaseBlocks(bootstrapContent, PHASE_NAME).includes('{{PROJECT_SUMMARY');
+}
+
 async function canShed(bootstrapContent) {
   if (!(await graphPastBootstrap())) return false;
-  return !bootstrapContent.includes('{{PROJECT_SUMMARY}}');
+  return !summaryUnfilled(bootstrapContent);
 }
 
 // `hedgehog shed` — strips bootstrap-only content from every host
@@ -550,7 +564,7 @@ async function shedCommand() {
   const unfilled = [];
   for (const { rel, abs } of present) {
     const content = await readFile(abs, 'utf8');
-    if (content.includes('{{PROJECT_SUMMARY}}')) unfilled.push(rel);
+    if (summaryUnfilled(content)) unfilled.push(rel);
   }
   if (unfilled.length > 0) {
     console.error(
@@ -587,13 +601,15 @@ async function writePlannedFile(f) {
     // `planner` already filled in: {{PROJECT_NAME}}/{{PROJECT_SUMMARY}}
     // are filled once, by hand or by `planner`, and never touched again.
     // Starting from the existing file instead of the pristine shell
-    // whenever it's still missing only {{CORE_SECTION}} preserves that —
-    // the shell is the base only for a destination that doesn't exist
-    // yet, or one still holding the raw, unfilled template.
+    // whenever those are filled preserves that — whether the core section
+    // is still the {{CORE_SECTION}} placeholder or an already-filled,
+    // marked section that the new core's content replaces in place. The
+    // shell is the base only for a destination that doesn't exist yet, or
+    // one still holding the raw, unfilled template.
     let out = null;
     if (await exists(f.dest)) {
       const existing = await readFile(f.dest, 'utf8');
-      if (!existing.includes('{{PROJECT_NAME}}') && existing.includes('{{CORE_SECTION}}')) {
+      if (!existing.includes('{{PROJECT_NAME}}') && hasCoreSection(existing)) {
         out = existing;
       } else if (!existing.includes('{{PROJECT_NAME}}') && !f.merge.include) {
         // Brownfield: hand-written content that predates Hedgehog, with
@@ -623,13 +639,15 @@ async function writePlannedFile(f) {
       // both paths' output mutually recognizable is what lets
       // hasCoreSection/appendCoreSection treat a template-filled file
       // and an appended one the same way on a later re-run.
-      out = out.replaceAll('{{CORE_SECTION}}', wrapSection(section));
+      out = out.includes('{{CORE_SECTION}}')
+        ? out.replaceAll('{{CORE_SECTION}}', wrapSection(section))
+        : appendCoreSection(out, section);
     }
     const dispatch = await readFile(join(PKG_ROOT, f.merge.dispatch), 'utf8');
     out = out.replaceAll('{{HOST_DISPATCH}}', dispatch.trimEnd());
     // Self-heal: a project past bootstrap that re-runs `init --force`
-    // must not silently regain bootstrap-only content just because this
-    // write started from the pristine shell again.
+    // leaves this write with no bootstrap-only content, whether or not
+    // `hedgehog shed` ever ran.
     if (await canShed(out)) out = stripPhaseBlocks(out, PHASE_NAME);
     await writeFile(f.dest, out);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyf0xx/hedgehog",
-  "version": "6.4.0",
+  "version": "6.4.2",
   "description": "Install the Hedgehog build discipline (agents + skills) into a repo, for Claude Code, Cursor, or Gemini CLI.",
   "type": "module",
   "repository": {

package/src/hosts/gemini/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "hedgehog",
-  "version": "6.4.0",
+  "version": "6.4.2",
   "description": "Hedgehog build discipline: ordered, tested, verified build steps.",
   "contextFileName": "GEMINI.md"
 }

package/vendor-skills/BMAD/ATTRIBUTION.md

@@ -5,8 +5,8 @@ This directory vendors a subset of [BMAD-METHOD](https://github.com/bmad-code-or
 for the full license text.
 
 - **Source repo:** https://github.com/bmad-code-org/BMAD-METHOD
-- **Vendored from:** tag `v6.11.0`, commit `890fcda760bade4d6080f5fa09aa8f658bc4a4a5`
-- **Vendored on:** 2026-08-11
+- **Vendored from:** tag `v6.12.1`, commit `790dae9c8e2a1d73575cb2d40b14dd4963391f29`
+- **Vendored on:** 2026-10-10
 - **Module:** `bmm` (BMAD Method Module)
 
 ## What's vendored
@@ -26,37 +26,48 @@ they depend on:
   every vendored skill calls, originally at `src/scripts/` in the source
   repo)
 
-Upstream collapsed the four `bmm-skills` above out of numbered
-`1-analysis/` and `2-plan-workflows/` directories into a single flat
-`plan/` directory as of this vendor pass; their content is otherwise
-unchanged. `bmad-deep-recon` is now included in a tagged release
-(previously only on `main`), so this pass pins to the `v6.11.0` tag
-instead of a `main` commit SHA.
-
-`bmad-forge-idea` is new upstream as of this pass: a persona-driven
-interrogation skill that pressure-tests an idea before any artifact gets
-written, added ahead of `bmad-brainstorming` as the shelf's first step.
-It carries its own script, `scripts/resolve_personas.py`, vendored
-alongside it (not shared — only this skill calls it). Its upstream
-counterpart `bmad-party-mode` (the multi-agent roster it can optionally
-draw on) is not vendored, since a real roster needs BMAD's own
-`bmm-skills/agents/bmad-agent-*` persona skills too — a parallel system
-to Hedgehog's own `src/agents/`, out of scope here. `bmad-forge-idea`
-degrades gracefully without it: `resolve_personas.py` returns an empty
-roster and the skill falls back to generating personas on the fly, which
-is its documented normal path, not a degraded one.
+Upstream keeps the four `bmm-skills` above under a single flat
+`bmm-skills/plan/` directory, collapsed out of the numbered
+`1-analysis/` and `2-plan-workflows/` directories an earlier pass found
+them in. `bmad-deep-recon` is in the pinned tag, so this pass pins to a
+release tag rather than a `main` commit SHA.
+
+`bmad-forge-idea` is a persona-driven interrogation skill that
+pressure-tests an idea before any artifact gets written, run ahead of
+`bmad-brainstorming` as the shelf's first step. It carries its own
+script, `scripts/resolve_personas.py`, vendored alongside it (not shared
+— only this skill calls it). Its upstream counterpart `bmad-party-mode`
+(the multi-agent roster it can optionally draw on) is not vendored, since
+a real roster needs BMAD's own `bmm-skills/agents/bmad-agent-*` persona
+skills too — a parallel system to Hedgehog's own `src/agents/`, out of
+scope here. `bmad-forge-idea` degrades gracefully without it:
+`resolve_personas.py` returns an empty roster and the skill falls back to
+generating personas on the fly, which is its documented normal path, not
+a degraded one.
 
 Each skill directory carries its own templates, reference files, and
 scripts as vendored, unmodified except where noted below.
 
+`scripts/resolve_customization.py` resolves the project root by checking,
+in order, the working directory, the script's own install path, and the
+invoking skill's directory — preferring any ancestor holding `_bmad/`
+over one merely holding `.git` at every depth — and warns on stderr when
+a candidate root it didn't pick has an override the chosen root lacks.
+This keeps a skill installed outside the target project (e.g. one that
+would otherwise walk up to `~`) from landing on the wrong root and
+silently missing the project's own override.
+
 ## What's stripped
 
 BMAD-METHOD's own orchestration layer is not vendored and is removed from
 every skill file that referenced it:
 
 - Central config resolution (`_bmad/scripts/resolve_config.py`,
-  `_bmad/config.toml`, `_bmad/bmm/config.yaml`) — replaced with trivial
-  defaults inline in each skill.
+  `_bmad/scripts/config_utils.py`, `_bmad/config.toml`,
+  `_bmad/bmm/config.yaml`) — replaced with trivial defaults inline in
+  each skill. Upstream's `plan/` skills call `resolve_config.py` for
+  this; re-apply the same strip to whatever call shape upstream uses on
+  each re-vendor pass.
 - `bmad-party-mode` (multi-agent roster) mentions and invocations.
 - Chain-forward "common next skill" suggestions and `bmad-help` routing.
 - Misroute-detection logic pointing at non-vendored BMAD skills.
@@ -77,6 +88,18 @@ this vendored tree.
   deliverables are markdown/prose only (skyf0xx/hedgehog#386). A
   re-vendor pass must re-apply this key to the freshly-fetched files
   rather than letting it silently disappear.
+- `persistent_facts` in every vendored `customize.toml` that carries it
+  (`bmad-forge-idea`, `bmad-brainstorming`, `bmad-product-brief`,
+  `bmad-prfaq`, `bmad-prd`, `bmad-ux`) defaults to
+  `["file:{project-root}/**/project-context.md"]`, not upstream's empty
+  default. Upstream moved repo-wide context to a hand-maintained
+  `AGENTS.md` loaded via `bmad-project-context`, a skill not vendored
+  here; Hedgehog's planning intake instead relies on project context
+  flowing into these skills automatically, so requiring a consuming
+  project to discover and set an opt-in override just to keep that
+  behavior would be a regression. A re-vendor pass must re-apply this
+  non-empty default to the freshly-fetched `customize.toml` files rather
+  than letting it silently reset to empty.
 
 ## Re-vendoring
 

package/vendor-skills/BMAD/bmm-skills/plan/bmad-prd/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-prd
-description: Create, update, or validate a PRD. Use when the user wants help producing, editing, or validating a PRD.
+description: Create, update, or validate a PRD. Use when the user wants help producing, editing, or validating a PRD
 ---
 # BMad PRD
 
@@ -17,7 +17,7 @@ You are a master facilitator and coach helping the user create, edit, or validat
 
 **Forwarded activation:** if a caller invoked you with a stated intent and pre-resolved customization fields (e.g. the `bmad-create-prd` / `bmad-edit-prd` / `bmad-validate-prd` shims), honor them verbatim — skip your own intent inference, use the supplied values for those named fields, and resolve only the remaining fields from your own `customize.toml`.
 
-1. Resolve customization: `uv run {bmad-root}/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults.
+1. Resolve customization: `uv run {bmad-root}/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults.
 2. Run `{workflow.activation_steps_prepend}`. Treat `{workflow.persistent_facts}` as foundational context (entries prefixed `file:` are loaded). `{workflow.external_sources}` is an org-configured registry of internal tools (knowledge bases, MCP tools); consult them alongside generic web research on the same triggers, org tools preferred when their directive matches. Research itself fires during Discovery — see **Research subagents**.
 3. Resolve `{user_name}` (ask the user or omit), `{communication_language}` (English), `{document_output_language}` (English), `{planning_artifacts}`, `{project_name}` (infer from the Hedgehog project), `{date}` (today's date) using sensible defaults. Missing values → neutral defaults; never block.
 4. If headless, follow `references/headless.md` for the whole run. Otherwise greet the user **by name** using `{user_name}` and **in their language** using `{communication_language}` — and stay in `{communication_language}` for every turn for the entire run, not just the greeting. In the greeting, let the user know that at any point they can invoke `bmad-advanced-elicitation` for deeper exploration on a specific section.

package/vendor-skills/BMAD/bmm-skills/plan/bmad-prd/assets/prd-template.md

@@ -161,5 +161,5 @@ updated: {YYYY-MM-DD}
 - **Environmental and Reliability Requirements**.
 
 ### Small-scope all-inclusive *(use when scope is 1-2 stories' worth and the user wants a single captured artifact — chosen during the Right-skill check in Discovery)*
-- **Stories** — story-level specs listed inline at the end of the doc. Each story: *"As a [persona], I can [action] [under conditions]. Acceptance: [testable criteria]."* Numbered Story-1, Story-2, ... for reference. Pair with very lean §1 Vision, §2 Target User (often just JTBD + one UJ), §3 Glossary (handful of terms), §4 Features (often a single feature), §6 MVP Scope (in/out very tight). The whole doc fits on a page or two and captures intent + implementable stories in one place. If the user doesn't want the captured artifact at all, `bmad-quick-dev` is the better path — this cluster is only for "I want a doc *and* the stories."
+- **Stories** — story-level specs listed inline at the end of the doc. Each story: *"As a [persona], I can [action] [under conditions]. Acceptance: [testable criteria]."* Numbered Story-1, Story-2, ... for reference. Pair with very lean §1 Vision, §2 Target User (often just JTBD + one UJ), §3 Glossary (handful of terms), §4 Features (often a single feature), §6 MVP Scope (in/out very tight). The whole doc fits on a page or two and captures intent + implementable stories in one place. If the user doesn't want the captured artifact at all, `bmad-build` is the better path — this cluster is only for "I want a doc *and* the stories."
 

package/vendor-skills/BMAD/bmm-skills/plan/bmad-prd/references/validate.md

@@ -41,11 +41,11 @@ Once every selected reviewer has returned, the parent synthesizes one consolidat
    - **Footer.** Rubric path, ISO timestamp.
 3. Write the filled HTML to `{doc_workspace}/validation-report.html`.
 4. Write the markdown twin to `{doc_workspace}/validation-report.md` (same content, grouped by severity rather than by dimension — see format below; this is the canonical form for downstream re-reading).
-5. Open the HTML in the default browser:
+5. Open the HTML in the default browser with the platform opener — `open` on macOS, `xdg-open` on Linux, `start ""` on Windows — double-quoting the path:
    ```bash
-   python3 -c "import webbrowser, pathlib; webbrowser.open(pathlib.Path('{doc_workspace}/validation-report.html').resolve().as_uri())"
+   open "{doc_workspace}/validation-report.html"
    ```
-   Skip the open step in headless mode (see `references/headless.md`).
+   If the command fails, don't retry with another opener: tell the user the file path and move on. Skip the open step in headless mode (see `references/headless.md`).
 
 ### Markdown twin format
 

package/vendor-skills/BMAD/bmm-skills/plan/bmad-prfaq/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-prfaq
-description: Working Backwards PRFAQ challenge that stress-tests a product concept customer-first. Use when the user requests to 'create a PRFAQ', 'work backwards', or 'run the PRFAQ challenge'.
+description: "Test a product concept with Amazon's Working Backwards method: write the press release for the finished product first, then answer hard customer and stakeholder questions, ending in a complete PRFAQ document. Use when the user requests to 'create a PRFAQ', 'work backwards', or 'run the PRFAQ challenge'"
 ---
 
 # Working Backwards: The PRFAQ Challenge
@@ -31,7 +31,7 @@ The PRFAQ forces customer-first clarity: write the press release announcing the
 
 ### Step 1: Resolve the Workflow Block
 
-Run: `uv run {bmad-root}/scripts/resolve_customization.py --skill {skill-root} --key workflow`
+Run: `uv run {bmad-root}/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow`
 
 **If the script fails**, read `{skill-root}/customize.toml` directly and use its defaults.
 

package/vendor-skills/BMAD/bmm-skills/plan/bmad-prfaq/bmad-manifest.json

@@ -4,9 +4,9 @@
     {
       "name": "working-backwards",
       "menu-code": "WB",
-      "description": "Produces battle-tested PRFAQ document and optional LLM distillate for PRD input.",
+      "description": "Produces a PRFAQ document and an optional condensed version for use as PRD input.",
       "supports-headless": true,
-      "phase-name": "1-analysis",
+      "phase-name": "plan",
       "preceded-by": ["brainstorming", "perform-research"],
       "followed-by": ["create-prd"],
       "is-required": false,

package/vendor-skills/BMAD/bmm-skills/plan/bmad-prfaq/references/verdict.md

@@ -78,6 +78,6 @@ purpose: "Token-efficient context for downstream PRD creation"
 
 This is the terminal stage. If the user wants to revise, loop back to the relevant stage. Otherwise, the workflow is done.
 
-Run: `uv run {bmad-root}/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
+Run: `uv run {bmad-root}/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow.on_complete`
 
 If the resolved `workflow.on_complete` is non-empty, follow it as the final terminal instruction before exiting.

package/vendor-skills/BMAD/bmm-skills/plan/bmad-product-brief/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-product-brief
-description: Create, update, or validate a product brief. Use when the user wants help producing, editing, or validating a brief.
+description: Create, update, or validate a product brief. Use when the user wants help producing, editing, or validating a brief
 ---
 
 # Overview
@@ -19,7 +19,7 @@ At the opening greeting, let the user know they can invoke `bmad-advanced-elicit
 
 ## On Activation
 
-1. Resolve customization: `uv run {bmad-root}/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults.
+1. Resolve customization: `uv run {bmad-root}/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults.
 2. Execute each entry in `{workflow.activation_steps_prepend}` in order.
 3. Treat every entry in `{workflow.persistent_facts}` as foundational context for the rest of the run. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim.
 4. `{workflow.external_sources}` is an org-configured registry of internal tools (knowledge bases, MCP tools); consult them alongside generic web research on the same triggers in `## Discovery`, org tools preferred when their directive matches. If a named tool is unavailable at runtime, fall back to standard behavior and note the gap when relevant.

package/vendor-skills/BMAD/bmm-skills/plan/bmad-ux/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-ux
-description: Plan UX patterns and design specifications. Use when the user says "lets create UX design" or "create UX specifications" or "help me plan the UX"
+description: 'Capture the user''s UX vision in two documents: DESIGN.md for how the product looks and EXPERIENCE.md for how it behaves. Use when the user says "lets create UX design" or "create UX specifications" or "help me plan the UX"'
 ---
 # BMad UX
 
@@ -34,7 +34,7 @@ UX may lead, follow, or stand alone. Inherit `sources:` by reference; the spines
 
 ## On Activation
 
-1. Resolve customization: `uv run {bmad-root}/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults.
+1. Resolve customization: `uv run {bmad-root}/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults.
 2. Run `{workflow.activation_steps_prepend}`. Treat `{workflow.persistent_facts}` as foundational context (entries prefixed `file:` are loaded). `{workflow.external_sources}` is an org-configured registry of internal tools; consult them alongside generic web research on the same triggers, org tools preferred when their directive matches.
 3. Resolve `{user_name}` (ask the user or omit), `{communication_language}` (English), `{document_output_language}` (English), `{planning_artifacts}`, `{project_name}` (infer from the Hedgehog project), `{date}` (today's date) using sensible defaults. Missing values → neutral defaults; never block.
 4. If headless, follow `references/headless.md` for the whole run. Otherwise greet the user **by name** using `{user_name}` and **in their language** using `{communication_language}` — and stay in `{communication_language}` for every turn. In the greeting, let the user know `bmad-advanced-elicitation` is always available.

package/vendor-skills/BMAD/bmm-skills/plan/bmad-ux/assets/color-themes.md

@@ -6,4 +6,4 @@ Each variation: header (name + one-line emotional register), token chips for eve
 
 Inline CSS only, system font stack, no JS, no network. Document concrete hex values in `<style>` comments per variation so the user can lift them if they pick that theme. The spine itself stays semantic.
 
-Return to the parent: file path, one-line per variation, mode coverage. Do not dump HTML into the parent context. If interactive, open the file with `python3 -c "import webbrowser, pathlib; webbrowser.open(pathlib.Path('PATH').resolve().as_uri())"`.
+Return to the parent: file path, one-line per variation, mode coverage. Do not dump HTML into the parent context. If interactive, open the file with the platform opener — `open "PATH"` on macOS, `xdg-open` on Linux, `start ""` on Windows, path always double-quoted. On failure, give the user the path instead.

package/vendor-skills/BMAD/bmm-skills/plan/bmad-ux/references/creative-tools.md

@@ -16,4 +16,4 @@ Every renderer writes to `{doc_workspace}/.working/` with a descriptive filename
 
 The parent passes the subagent: current `.memlog.md`, relevant prior `.working/` captures, the user's stated intent for this pass, the output path. The subagent writes its artifact under `.working/` and returns ONLY a compact summary (file path, one line per variant, mode coverage). Parent never holds the full payload.
 
-For HTML, open in browser when interactive: `python3 -c "import webbrowser, pathlib; webbrowser.open(pathlib.Path('PATH').resolve().as_uri())"`. Skip in headless.
+For HTML, open in the browser when interactive with the platform opener — `open "PATH"` on macOS, `xdg-open` on Linux, `start ""` on Windows, path always double-quoted. On failure, give the user the path instead. Skip in headless.

package/vendor-skills/BMAD/bmm-skills/plan/bmad-ux/references/validate.md

@@ -69,7 +69,7 @@ Under Validate intent, after every reviewer returns, render one consolidated rep
 2. Fill `{workflow.validation_report_template}`. No overall grade — the per-category verdicts and severity counts already say what's true. Synthesis paragraph lifts the rubric's overall verdict; add a second if extra reviewers shift the picture. One section per rubric category (open if thin / broken), one per extra reviewer (closed, adversarial voice preserved).
 3. Write `{doc_workspace}/validation-report.html`.
 4. Write the Markdown twin `{doc_workspace}/validation-report.md` — same content grouped by severity.
-5. Open HTML: `python3 -c "import webbrowser, pathlib; webbrowser.open(pathlib.Path('{doc_workspace}/validation-report.html').resolve().as_uri())"`. Skip headless.
+5. Open HTML with the platform opener — `open "{doc_workspace}/validation-report.html"` on macOS, `xdg-open` on Linux, `start ""` on Windows, path always double-quoted. On failure, give the user the path instead. Skip headless.
 
 Re-running overwrites the consolidated report; individual `review-*.md` files persist.
 

package/vendor-skills/BMAD/core-skills/bmad-advanced-elicitation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-advanced-elicitation
-description: 'Push the LLM to reconsider, refine, and improve its recent output. Use when user asks for deeper critique or mentions a known deeper critique method, e.g. socratic, first principles, pre-mortem, red team.'
+description: 'Push the LLM to reconsider, refine, and improve its recent output. Use when user asks for deeper critique or mentions a known deeper critique method, e.g. socratic, first principles, pre-mortem, red team'
 ---
 
 # Advanced Elicitation
@@ -15,12 +15,12 @@ You are BMad's shared refinement checkpoint: other skills invoke you at natural
 
 ## On Activation
 
-1. Resolve customization: `uv run {bmad-root}/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults.
+1. Resolve customization: `uv run {bmad-root}/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults.
 2. Hold every `{workflow.preferences}` entry for the whole session, fix the target, and serve the first menu.
 
 ## Serving the Catalog
 
-`scripts/pick_methods.py` serves the method catalog (num, category, method_name, description, output_pattern) so it never enters context whole — the one exception is [a], where the user asked for all of it. Invoke as:
+`scripts/pick_methods.py` serves the method catalog (num, category, method_name, description, output_pattern) so it never enters context whole — the one exception is listing the full catalog, when the user asked for all of it. Invoke as:
 
 ```bash
 uv run {skill-root}/scripts/pick_methods.py --file {workflow.methods_file} <command>
@@ -29,7 +29,7 @@ uv run {skill-root}/scripts/pick_methods.py --file {workflow.methods_file} <comm
 If `{workflow.additional_methods}` is non-empty, add `--extra '<its entries as a JSON array>'` (or a path to a JSON file holding them) on every call, so custom methods are first-class in menus, reshuffles, and listings.
 
 - `categories` — category names + counts, the cheap map.
-- `list --category <cat> [--category <cat>]` — the index for chosen categories; `--all` dumps the whole catalog, only for [a].
+- `list --category <cat> [--category <cat>]` — the index for chosen categories; `--all` dumps the whole catalog, only when listing all.
 - `show <name-or-num> [...]` — full rows by name or num.
 - `random -n 5 --spread [--exclude <name>]...` — a category-diverse random draw.
 
@@ -37,30 +37,29 @@ If `{workflow.additional_methods}` is non-empty, add `--extra '<its entries as a
 
 ## The Menu
 
-```
-**Advanced Elicitation Options**
-Choose a number (1-5), [r] to Reshuffle, [a] List All, or [x] to Proceed:
-
-1. [Method Name]
-2. [Method Name]
-3. [Method Name]
-4. [Method Name]
-5. [Method Name]
-r. Reshuffle the list with 5 new options
-a. List all methods with descriptions
-x. Proceed / No Further Actions
-```
+HALT and give the user a choice:
+
+- The five offered methods, listed by name. The user may pick one or several.
+- **Reshuffle** — replace the list with five new options.
+- **List all** — show the full catalog with descriptions.
+- **Proceed** — no further elicitation.
 
-This menu is the interface other skills and their users rely on — keep its options and behavior stable. Handle the response:
+This menu is the interface other skills and their users rely on — keep its options and behavior stable.
 
-- **1–5** — run that method (several numbers: in sequence), then re-present the menu.
-- **r** — reshuffle as above and re-present.
-- **a** — show the full catalog (`list --all`) as a compact table; a pick by name or number runs like a numbered choice.
-- **x** — done. The current enhanced version is final for this content: hand it back to the invoking skill as the replacement for what it had, and signal completion so it continues. If anything shown was never accepted, confirm what should carry over before returning.
-- **Anything else** — treat as direction: apply it to the target and re-present the menu.
+- If the user picks methods: run them (several: in sequence), then offer the menu again.
+- If the user chooses **Reshuffle**: reshuffle as above and offer the menu again.
+- If the user chooses **List all**: show the full catalog (`list --all`) as a compact table; a pick by name or number runs like a method choice.
+- If the user chooses **Proceed**: done. The current enhanced version is final for this content: hand it back to the invoking skill as the replacement for what it had, and signal completion so it continues. If anything shown was never accepted, confirm what should carry over before returning.
+- Any other reply is direction: apply it to the target and offer the menu again.
 
 ## Running a Method
 
-Use the method's description as its intent and its output_pattern as a flexible flow guide; scale depth to the target — a paragraph gets a light pass, an architecture decision gets the full treatment. Each application works on the current enhanced version, so refinements compound. Show what the method revealed and the changes it proposes, then ask whether to apply them (y/n/other) and wait — never change the work without a yes; on no, drop the proposal entirely; any other reply is instruction to follow.
+Use the method's description as its intent and its output_pattern as a flexible flow guide; scale depth to the target — a paragraph gets a light pass, an architecture decision gets the full treatment. Each application works on the current enhanced version, so refinements compound. Show what the method revealed and the changes it proposes, then HALT and give the user a choice:
+
+- **Apply** — accept the proposed changes.
+- **Reject** — drop the proposal entirely.
+- Or give different direction.
+
+Never change the work unless the user accepts the proposal. If they reject it, drop the proposal entirely. Any other reply is instruction to follow.
 
 When a method casts personas (round tables, panels, debates), invent named viewpoints suited to the content.

package/vendor-skills/BMAD/core-skills/bmad-brainstorming/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-brainstorming
-description: Facilitate a brainstorming session using diverse creative techniques. Use when the user says 'help me brainstorm' or 'help me ideate'.
+description: Facilitate a brainstorming session using diverse creative techniques. Use when the user says 'help me brainstorm' or 'help me ideate'
 ---
 
 # BMad Brainstorming
@@ -19,7 +19,7 @@ The session runs in one of three stances, chosen by the user — set explicitly
 
 ## On Activation
 
-1. Resolve customization: `uv run {bmad-root}/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, use a subagent to read `{skill-root}/customize.toml` directly with defaults.
+1. Resolve customization: `uv run {bmad-root}/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow`. On failure, use a subagent to read `{skill-root}/customize.toml` directly with defaults.
 2. Run each `{workflow.activation_steps_prepend}` entry. Treat each `{workflow.persistent_facts}` entry as foundational context (`file:`-prefixed entries are paths/globs under `{project-root}` — load their contents; others are facts verbatim).
 3. Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{output_folder}`, `{project_name}` using sensible defaults (ask the user or omit `{user_name}`; English for language fields; infer `{project_name}` from the Hedgehog project); `{date}` is today. Missing values → neutral defaults; never block.
 4. **If launched headless** (a machine signal, not a human asking for output — `references/headless.md` lists them): load `references/headless.md` and follow it for the whole run; never load it otherwise. Outside headless, you generate ideas yourself only in autonomous mode (`references/mode-autonomous.md`) — never in facilitator or partner mode.

package/vendor-skills/BMAD/core-skills/bmad-brainstorming/scripts/brain.py

@@ -692,7 +692,26 @@ def html_doc(rows: list[dict]) -> str:
     )
 
 
+def pin_utf8(stream):
+    """Pin a console stream to UTF-8, keeping its own error handler.
+
+    `--extra` technique text and the technique names echoed to stderr are
+    arbitrary user input, so either stream can carry a character the platform
+    default cannot encode (cp1252 on Windows) and print() then raises.
+
+    errors= is passed through deliberately: reconfigure(encoding=...) alone
+    resets the handler to "strict", which would silently downgrade stderr's
+    POSIX default of "backslashreplace" and turn a diagnostic about an
+    undecodable path into a traceback.
+    """
+    reconfigure = getattr(stream, "reconfigure", None)
+    if reconfigure is not None:
+        reconfigure(encoding="utf-8", errors=getattr(stream, "errors", None) or "strict")
+
+
 def main(argv: list[str] | None = None) -> int:
+    pin_utf8(sys.stdout)
+    pin_utf8(sys.stderr)
     p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     p.add_argument("--file", type=Path, default=DEFAULT_FILE, help="technique CSV (default: sibling assets/brain-methods.csv)")
     p.add_argument("--extra", type=Path, help="JSON overlay of additional techniques (customize.toml additional_techniques), merged into every command")

package/vendor-skills/BMAD/core-skills/bmad-brainstorming/scripts/tests/test_brain.py

@@ -3,6 +3,7 @@
 # dependencies = ["pytest>=8.0"]
 # ///
 """Tests for brain.py. Run: uv run -m pytest scripts/tests/test_brain.py"""
+import io
 import json
 import sys
 from pathlib import Path
@@ -227,6 +228,55 @@ def test_unknown_category_style_uses_fallback_glyph():
     assert glyph == brain._FALLBACK_GLYPH
 
 
+# --- console encoding (Windows cp1252) ----------------------------------
+
+def _cp1252_stream():
+    """A text stream that behaves like a Windows console: cp1252, strict."""
+    return io.TextIOWrapper(io.BytesIO(), encoding="cp1252", errors="strict", write_through=True)
+
+
+def test_extra_technique_prints_when_stdout_encoding_is_cp1252(lib, tmp_path, monkeypatch):
+    # --extra text is arbitrary user input; the shipped catalog happens to be
+    # cp1252-safe, an overlay is not. Unpinned stdout raises UnicodeEncodeError
+    # and the command exits having printed nothing.
+    overlay = tmp_path / "extra.json"
+    overlay.write_text(
+        json.dumps([{"category": "wild", "technique_name": "Fikir Fırtınası 🌪", "description": "Beyin fırtınası — 日本語"}]),
+        encoding="utf-8",
+    )
+    fake = _cp1252_stream()
+    monkeypatch.setattr(sys, "stdout", fake)
+    assert brain.main(["--file", str(lib), "--extra", str(overlay), "list", "--all"]) == 0
+    out = fake.buffer.getvalue().decode("utf-8")
+    assert "Fikir Fırtınası 🌪" in out
+    assert "日本語" in out
+
+
+def test_missing_technique_name_reports_when_stderr_encoding_is_cp1252(lib, monkeypatch):
+    # `show` echoes the name it could not find; that name came from argv.
+    fake = _cp1252_stream()
+    monkeypatch.setattr(sys, "stderr", fake)
+    assert brain.main(["--file", str(lib), "show", "日本語"]) == 1
+    assert "日本語" in fake.buffer.getvalue().decode("utf-8")
+
+
+def test_pin_utf8_preserves_the_streams_error_handler():
+    # reconfigure(encoding=...) on its own resets errors to "strict"; stderr on
+    # POSIX defaults to "backslashreplace" and must keep it, or a diagnostic
+    # carrying a surrogate-escaped path becomes a traceback.
+    stream = io.TextIOWrapper(io.BytesIO(), encoding="ascii", errors="backslashreplace")
+    brain.pin_utf8(stream)
+    assert stream.encoding == "utf-8"
+    assert stream.errors == "backslashreplace"
+
+
+def test_pin_utf8_ignores_a_stream_without_reconfigure():
+    class Captured:  # e.g. pytest's capture object, or a StringIO stand-in
+        errors = None
+
+    brain.pin_utf8(Captured())  # must not raise
+
+
 def test_shipped_selector_is_in_sync_with_catalog():
     # foolproofing: if someone edits brain-methods.csv they must regenerate the page.
     # Regenerate with: uv run brain.py html --out assets/brain-selector.html

package/vendor-skills/BMAD/core-skills/bmad-deep-recon/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-deep-recon
-description: 'Decision-grade research, three ways: draft a deep-research prompt for the user to run in their own tool (ChatGPT, Gemini, Grok, Perplexity, …), process a finished research report — file it, distill a succinct cited summary with metadata that downstream skills consume without reprocessing — or run the research here through web fan-out. Shipped type packs: market, domain, technical, competitive, user-voice, academic-lit — plus a select shape for choose-between decisions and custom types via overrides. Use when the user says "deep recon", "research this", "draft a research prompt", "process this research report", "market research", "domain research", "technical research", "competitor research", "literature review", or "help me choose between".'
+description: 'Research a topic to support a decision, three ways: draft a research prompt for the user to run in their own tool (ChatGPT, Gemini, Grok, Perplexity, …), turn a finished research report into a short summary with cited sources that other skills can use directly, or run the research here with parallel web searches. Built-in research types: market, domain, technical, competitive, user-voice, academic-lit; also supports choosing between candidates, and custom types via overrides. Use when the user says "deep recon", "research this", "draft a research prompt", "process this research report", "market research", "domain research", "technical research", "competitor research", "literature review", or "help me choose between"'
 ---
 
 # BMad Deep Recon
@@ -37,7 +37,7 @@ Three services, freely combined — each detailed in its reference: **Draft** a
 
 **Forwarded activation:** if a caller invoked you with a stated intent, research type, or pre-resolved customization fields, honor them verbatim — skip your own inference for those values and resolve only the rest.
 
-1. Resolve customization: `uv run {bmad-root}/scripts/resolve_customization.py --skill {skill-root} --key workflow` (on failure read `{skill-root}/customize.toml`, use defaults). Run `{workflow.activation_steps_prepend}`, then `{workflow.activation_steps_append}`.
+1. Resolve customization: `uv run {bmad-root}/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow` (on failure read `{skill-root}/customize.toml`, use defaults). Run `{workflow.activation_steps_prepend}`, then `{workflow.activation_steps_append}`.
 2. Resolve `{user_name}` (ask the user or omit), `{communication_language}` (English), `{document_output_language}` (English), `{project_name}` (infer from the Hedgehog project), `{output_folder}`, `{planning_artifacts}` (defaults to `{output_folder}` if unset), and `{date}` (today's date) using sensible defaults; missing values take neutral defaults, never block.
 3. Headless (no interactive user) → see `## Headless Mode`. Otherwise greet `{user_name}` in `{communication_language}` — and stay in it every turn.
 4. Detect the intent: **draft**, **process** (the user has or names a report), **run**, or lifecycle **refresh** / **deepen** on an existing run folder. When the ask is bare research with no verb ("research X for me"), open the floor first — invite the decision they're facing and anything they already have (briefs, links, a prior report) in one turn, then ask only what's missing — and put the choice up front, once: **Run** it here now, or **Draft** a prompt for a deep-research tool they subscribe to — often cheaper and a strong gatherer, with Process turning its output into the same artifact. State the trade honestly (tokens and minutes here vs. one manual round-trip there); their call, remembered for the session.

package/vendor-skills/BMAD/core-skills/bmad-forge-idea/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-forge-idea
-description: Pressure-test an idea through persona-driven interrogation until it hardens, proves out, or dies cheaply. Use when the user says 'forge an idea', 'pressure-test this idea', 'stress-test my thinking', or 'harden this idea'.
+description: Test a half-formed idea in a questioning conversation, with different personas probing its weak points, until the user can act on it or drop it with confidence. Optionally writes a short brief for planning skills to build on. Use when the user says 'forge an idea', 'pressure-test this idea', 'stress-test my thinking', or 'harden this idea'
 ---
 
 # BMad Forge Idea
@@ -23,7 +23,7 @@ Lead by questioning, not lecturing. Ask one question at a time, press on weak po
 
 ## On Activation
 
-1. Resolve customization: `uv run {bmad-root}/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly with defaults. Apply the resolved `{workflow.*}` values throughout.
+1. Resolve customization: `uv run {bmad-root}/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly with defaults. Apply the resolved `{workflow.*}` values throughout.
 2. Run each `{workflow.activation_steps_prepend}` entry; treat each `{workflow.persistent_facts}` entry as foundational context (`file:` entries load their contents, `skill:` names a skill to consult, others are facts verbatim).
 3. Resolve `{user_name}`, `{communication_language}`, `{output_folder}` using sensible defaults (ask the user or omit `{user_name}`; English for language fields); `{date}` is today. Missing values → neutral defaults; never block. Greet `{user_name}` in `{communication_language}` and stay in it.
 4. Resume: glob `{workflow.forge_output_path}/**/.memlog.md` (recursive, so it still finds sessions when `run_folder_pattern` is overridden to nest paths) and read only each match's frontmatter to find any whose `status` is not `complete`. Offer to resume one — then read its full memlog once to rebuild state and continue append-only — or to start fresh.
@@ -48,7 +48,7 @@ Otherwise ask for what's missing, in order:
 
 ### Steering the conversation
 
-Tell the user they can say **"attack this"**, **"defend this"**, or **"switch roles"** at any time to change how the current idea is argued. In attack mode, do not agree with the idea; look for contradictions, weak assumptions, and failure cases. In defend mode, argue for the strongest version of the idea. Tell the user they can also name a persona at any time to change who participates in the session.
+Tell the user they can say **"attack this"**, **"defend this"**, or **"switch roles"** at any time to change how the current idea is argued. In attack mode, do not agree with the idea; look for contradictions, weak assumptions, and failure cases. In defend mode, argue for the strongest version of the idea. Tell the user they can also name a persona or party at any time to change who participates in the session.
 
 ### Set up the session
 

package/vendor-skills/BMAD/core-skills/bmad-forge-idea/scripts/resolve_personas.py

@@ -110,7 +110,9 @@ def find_party_skill(project_root: Path, skill_root: Path):
 def load_party_workflow(project_root: Path, party_skill: Path):
     """Merged [workflow] table for bmad-party-mode (base + user overrides)."""
     resolver = project_root / "_bmad" / "scripts" / "resolve_customization.py"
-    data = _run_json([sys.executable, str(resolver), "--skill", str(party_skill), "--key", "workflow"])
+    data = _run_json(
+        [sys.executable, str(resolver), "--skill", str(party_skill), "--project-root", str(project_root), "--key", "workflow"]
+    )
     if data is not None and isinstance(data.get("workflow"), dict):
         return data["workflow"]
     # Fallback: base customize.toml directly, no override merge.

package/vendor-skills/BMAD/core-skills/bmad-forge-idea/scripts/tests/test_resolve_personas.py

@@ -5,6 +5,7 @@
 """Unit tests for resolve_personas.py — pool merge, alias, party resolution."""
 
 import sys
+import tempfile
 import unittest
 from pathlib import Path
 
@@ -134,5 +135,26 @@ class TestOverrideMergeFallback(unittest.TestCase):
             self.assertEqual([m["code"] for m in wf["party_members"]], ["x", "y"])  # appended
 
 
+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_party_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/vendor-skills/BMAD/scripts/resolve_customization.py

@@ -1,177 +1,104 @@
 #!/usr/bin/env python3
-"""
-Resolve customization for a BMad skill using three-layer TOML merge.
-
-Reads customization from three layers (highest priority first):
-  1. {project-root}/_bmad/custom/{name}.user.toml  (personal, gitignored)
-  2. {project-root}/_bmad/custom/{name}.toml        (team/org, committed)
-  3. {skill-root}/customize.toml                    (skill defaults)
-
-Skill name is derived from the basename of the skill directory.
-
-Outputs merged JSON to stdout. Errors go to stderr.
-
-Uses only the Python stdlib (`tomllib`) — no third-party dependencies.
-BMad is standardizing on `uv run` to invoke scripts (uv provisions a suitable
-interpreter for you); a plain `python3` on PATH still works during the
-transition. Either runner needs Python 3.11+ for `tomllib`.
-
-  uv run resolve_customization.py --skill /abs/path/to/skill-dir
-  uv run resolve_customization.py --skill ... --key agent
-  uv run resolve_customization.py --skill ... --key agent.menu
-
-Merge rules (purely structural — no field-name special-casing):
-  - Scalars (string, int, bool, float): override wins
-  - Tables: deep merge (recursively apply these rules)
-  - Arrays of tables where every item shares the *same* identifier
-    field (every item has `code`, or every item has `id`):
-    merge by that key (matching keys replace, new keys append)
-  - All other arrays — including arrays where only some items have
-    `code` or `id`, or where items mix the two keys:
-    append (base items followed by override items)
-
-No removal mechanism — overrides cannot delete base items. To suppress
-a default, fork the skill or override the item by code with a no-op
-description/prompt.
-"""
+# /// script
+# requires-python = ">=3.11"
+# ///
+"""Resolve a skill's default, team, and user TOML customization layers."""
 
 import argparse
 import json
 import sys
 from pathlib import Path
 
+# Installed scripts are consumer files, not a location for interpreter caches.
+sys.dont_write_bytecode = True
+
 try:
-    import tomllib
-except ImportError:
-    sys.stderr.write(
-        "error: Python 3.11+ is required (stdlib `tomllib` not found).\n"
-        "Install a newer Python or run the resolution manually per the\n"
-        "fallback instructions in the skill's SKILL.md.\n"
-    )
-    sys.exit(3)
+    from config_utils import ConfigError, load_customization
+except ModuleNotFoundError as error:
+    if error.name != "tomllib":
+        raise
+    sys.stderr.write("error: Python 3.11+ is required (stdlib `tomllib` not found).\n")
+    raise SystemExit(3) from None
 
 
 _MISSING = object()
-_KEYED_MERGE_FIELDS = ("code", "id")
 
 
-def find_project_root(start: Path):
+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
-        parent = current.parent
-        if parent == current:
-            return None
-        current = parent
-
-
-def load_toml(file_path: Path, required: bool = False) -> dict:
-    if not file_path.exists():
-        if required:
-            sys.stderr.write(f"error: required customization file not found: {file_path}\n")
-            sys.exit(1)
-        return {}
-    try:
-        with file_path.open("rb") as f:
-            parsed = tomllib.load(f)
-        if not isinstance(parsed, dict):
-            if required:
-                sys.stderr.write(f"error: {file_path} did not parse to a table\n")
-                sys.exit(1)
-            return {}
-        return parsed
-    except tomllib.TOMLDecodeError as error:
-        level = "error" if required else "warning"
-        sys.stderr.write(f"{level}: failed to parse {file_path}: {error}\n")
-        if required:
-            sys.exit(1)
-        return {}
-    except OSError as error:
-        level = "error" if required else "warning"
-        sys.stderr.write(f"{level}: failed to read {file_path}: {error}\n")
-        if required:
-            sys.exit(1)
-        return {}
-
-
-def _detect_keyed_merge_field(items):
-    """Return 'code' or 'id' if every table item carries that *same* field.
-
-    All items must share the same identifier (all `code`, or all `id`).
-    Mixed arrays — where some items use `code` and others use `id` —
-    return None and fall through to append semantics. This is intentional:
-    mixing identifier keys within one array is a schema smell, and
-    append-fallback is safer than guessing which key should merge.
-    """
-    if not items or not all(isinstance(item, dict) for item in items):
-        return None
-    for candidate in _KEYED_MERGE_FIELDS:
-        if all(item.get(candidate) is not None for item in items):
-            return candidate
-    return None
-
+        if git_root is None and (current / ".git").exists():
+            git_root = current
+        if current.parent == current:
+            return git_root
+        current = current.parent
 
-def _merge_by_key(base, override, key_name):
-    result = []
-    index_by_key = {}
-
-    for item in base:
-        if not isinstance(item, dict):
-            continue
-        if item.get(key_name) is not None:
-            index_by_key[item[key_name]] = len(result)
-        result.append(dict(item))
-
-    for item in override:
-        if not isinstance(item, dict):
-            result.append(item)
-            continue
-        key = item.get(key_name)
-        if key is not None and key in index_by_key:
-            result[index_by_key[key]] = dict(item)
-        else:
-            if key is not None:
-                index_by_key[key] = len(result)
-            result.append(dict(item))
 
-    return result
+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 _merge_arrays(base, override):
-    """Shape-aware array merge. Base + override combined tables may opt into
-    keyed merge if every item has `code` or `id`. Otherwise: append."""
-    base_arr = base if isinstance(base, list) else []
-    override_arr = override if isinstance(override, list) else []
-    keyed_field = _detect_keyed_merge_field(base_arr + override_arr)
-    if keyed_field:
-        return _merge_by_key(base_arr, override_arr, keyed_field)
-    return base_arr + override_arr
 
+def candidate_project_roots(skill_dir: Path) -> list[Path]:
+    """Plausible project roots, most trustworthy first.
 
-def deep_merge(base, override):
-    """Recursively merge override into base using structural rules.
-    - Table + table: deep merge
-    - Array + array: shape-aware (keyed merge if all items have code/id, else append)
-    - Anything else: override wins
+    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.
     """
-    if isinstance(base, dict) and isinstance(override, dict):
-        result = dict(base)
-        for key, over_val in override.items():
-            if key in result:
-                result[key] = deep_merge(result[key], over_val)
-            else:
-                result[key] = over_val
-        return result
-    if isinstance(base, list) and isinstance(override, list):
-        return _merge_arrays(base, override)
-    return override
+    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):
-    parts = dotted_key.split(".")
     current = data
-    for part in parts:
+    for part in dotted_key.split("."):
         if isinstance(current, dict) and part in current:
             current = current[part]
         else:
@@ -179,62 +106,59 @@ def extract_key(data, dotted_key: str):
     return current
 
 
-def write_json_stdout(output):
-    """Write JSON as UTF-8 so Windows cp1252 stdout can carry emoji icons."""
+def write_json_stdout(output) -> None:
     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():
+def main() -> int:
     parser = argparse.ArgumentParser(
-        description="Resolve customization for a BMad skill using three-layer TOML merge.",
-        add_help=True,
+        description="Resolve skill customization using three-layer TOML merge."
+    )
+    parser.add_argument(
+        "--skill", "-s", required=True, help="Absolute path to the skill directory"
     )
     parser.add_argument(
-        "--skill", "-s", required=True,
-        help="Absolute path to the skill directory (must contain customize.toml)",
+        "--project-root",
+        "-p",
+        help="Explicit project root containing _bmad/ (recommended)",
     )
     parser.add_argument(
-        "--key", "-k", action="append", default=[],
+        "--key",
+        "-k",
+        action="append",
+        default=[],
         help="Dotted field path to resolve (repeatable). Omit for full dump.",
     )
     args = parser.parse_args()
 
     skill_dir = Path(args.skill).resolve()
-    skill_name = skill_dir.name
-    defaults_path = skill_dir / "customize.toml"
-
-    defaults = load_toml(defaults_path, required=True)
-
-    # Prefer the project that contains this skill. Only fall back to cwd if
-    # the skill isn't inside a recognizable project tree (unusual but possible
-    # for standalone skills invoked directly). Using cwd first is unsafe when
-    # an ancestor of cwd happens to have a stray _bmad/ from another project.
-    project_root = find_project_root(skill_dir) or find_project_root(Path.cwd())
-
-    team = {}
-    user = {}
-    if project_root:
-        custom_dir = project_root / "_bmad" / "custom"
-        team = load_toml(custom_dir / f"{skill_name}.toml")
-        user = load_toml(custom_dir / f"{skill_name}.user.toml")
+    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)
 
-    merged = deep_merge(defaults, team)
-    merged = deep_merge(merged, user)
+    try:
+        merged = load_customization(project_root, skill_dir)
+    except ConfigError as error:
+        sys.stderr.write(f"error: {error}\n")
+        return 1
 
+    output = merged
     if args.key:
         output = {}
         for key in args.key:
             value = extract_key(merged, key)
             if value is not _MISSING:
                 output[key] = value
-    else:
-        output = merged
-
     write_json_stdout(output)
+    return 0
 
 
 if __name__ == "__main__":
-    main()
+    raise SystemExit(main())