bmad-method 6.10.1-next.2 → 6.10.1-next.21

package/src/core-skills/bmad-deep-recon/scripts/recon_kit.py

@@ -0,0 +1,322 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# ///
+"""recon_kit — deterministic helpers for bmad-deep-recon.
+
+The mechanical half of the research workflow: everything here is exact,
+repeatable work the LLM should never re-derive by hand. All subcommands
+print one JSON object to stdout; diagnostics go to stderr. Exit codes:
+0 = pass, 1 = findings that need attention, 2 = usage/parse error.
+
+Subcommands:
+  citations RESEARCH_MD
+      Cross-check inline [n] markers against the source-appendix table:
+      dangling markers (no appendix row) and orphaned rows (never cited).
+  tally MEMLOG_MD
+      Count memlog entries by type, and claim entries by status.
+      Claim lines carry `status=<word>` and optionally `ref=[n]`; for a
+      given ref the LAST status wins, so status changes are appends.
+  staleness CLAIMS_JSON --windows JSON [--today YYYY-MM-DD]
+      Given claims [{claim, class, pub_date}] and a months-per-class map
+      (e.g. '{"size/growth": 18, "pricing": 3}'), compute each claim's
+      re-check date, flag stale ones, and report the earliest re-check.
+  slug TOPIC --type TYPE [--pattern P] [--date YYYY-MM-DD]
+      Expand the run-folder pattern deterministically so the same topic
+      always lands in the same folder across draft -> process -> refresh.
+  escape-sources RESEARCH_MD
+      Emit the source-appendix table as HTML with every cell escaped and
+      only validated http(s) URLs turned into links, for the briefing.
+"""
+from __future__ import annotations
+
+import argparse
+import calendar
+import html
+import json
+import re
+import sys
+import unicodedata
+from datetime import date, datetime
+from pathlib import Path
+from urllib.parse import urlparse
+
+MARKER_RE = re.compile(r"\[(\d+)\](?!\()")  # [3] but not a [3](url) link
+MD_LINK_RE = re.compile(r"\[([^\]]*)\]\((\S+?)\)")
+BARE_URL_RE = re.compile(r"https?://[^\s|)\]]+")
+
+
+def out(payload: dict, exit_code: int) -> int:
+    print(json.dumps(payload, indent=2, ensure_ascii=False, default=str))
+    return exit_code
+
+
+def read_text(path_arg: str) -> str:
+    if path_arg == "-":
+        return sys.stdin.read()
+    return Path(path_arg).read_text(encoding="utf-8")
+
+
+def strip_fences(text: str) -> str:
+    """Blank out fenced code blocks so their contents never count as markers or rows."""
+    lines, fenced = [], False
+    for ln in text.splitlines():
+        if ln.lstrip().startswith("```"):
+            fenced = not fenced
+            lines.append("")
+            continue
+        lines.append("" if fenced else ln)
+    return "\n".join(lines)
+
+
+def table_cells(line: str) -> list[str]:
+    return [c.strip() for c in line.strip().strip("|").split("|")]
+
+
+def appendix_rows(text: str) -> dict[int, list[str]]:
+    """Source-appendix rows: markdown table rows whose first cell is a bare [n] / n."""
+    rows: dict[int, list[str]] = {}
+    for ln in text.splitlines():
+        stripped = ln.strip()
+        if not stripped.startswith("|"):
+            continue
+        cells = table_cells(stripped)
+        if not cells or len(cells) < 2:
+            continue
+        m = re.fullmatch(r"\[?(\d+)\]?", cells[0])
+        if m:
+            rows[int(m.group(1))] = cells
+    return rows
+
+
+# --- citations ---------------------------------------------------------------
+
+def cmd_citations(args) -> int:
+    text = strip_fences(read_text(args.file))
+    rows = appendix_rows(text)
+    markers: set[int] = set()
+    for ln in text.splitlines():
+        stripped = ln.strip()
+        if stripped.startswith("|"):
+            cells = table_cells(stripped)
+            if cells and re.fullmatch(r"\[?(\d+)\]?", cells[0]):
+                continue  # an appendix row is not a citation of itself
+        markers.update(int(n) for n in MARKER_RE.findall(ln))
+    dangling = sorted(markers - set(rows))
+    orphaned = sorted(set(rows) - markers)
+    ok = not dangling and not orphaned
+    return out({
+        "markers": sorted(markers),
+        "appendix_rows": sorted(rows),
+        "dangling_markers": dangling,
+        "orphaned_rows": orphaned,
+        "ok": ok,
+    }, 0 if ok else 1)
+
+
+# --- tally -------------------------------------------------------------------
+
+ENTRY_RE = re.compile(r"^- (?:\(([\w-]+)(?: by [^)]*)?\)\s*)?(.*)$")
+
+
+def cmd_tally(args) -> int:
+    text = read_text(args.file)
+    body = text.split("---", 2)[-1] if text.startswith("---") else text
+    by_type: dict[str, int] = {}
+    by_ref: dict[int, str] = {}
+    unref_status: dict[str, int] = {}
+    entries = 0
+    for ln in body.splitlines():
+        m = ENTRY_RE.match(ln)
+        if not m or not ln.startswith("- "):
+            continue
+        entries += 1
+        etype = m.group(1) or "note"
+        by_type[etype] = by_type.get(etype, 0) + 1
+        if etype == "claim":
+            status_m = re.search(r"status=([\w-]+)", m.group(2))
+            status = status_m.group(1) if status_m else "unknown"
+            ref_m = re.search(r"ref=\[?(\d+)\]?", m.group(2))
+            if ref_m:
+                by_ref[int(ref_m.group(1))] = status  # last status wins per ref
+            else:
+                unref_status[status] = unref_status.get(status, 0) + 1
+    claims: dict[str, int] = dict(unref_status)
+    for status in by_ref.values():
+        claims[status] = claims.get(status, 0) + 1
+    return out({
+        "entries": entries,
+        "by_type": dict(sorted(by_type.items())),
+        "claims": dict(sorted(claims.items())),
+        "claims_total": sum(claims.values()),
+    }, 0)
+
+
+# --- staleness ---------------------------------------------------------------
+
+def parse_date(raw: str) -> date:
+    raw = raw.strip()
+    for fmt in ("%Y-%m-%d", "%Y-%m", "%Y"):
+        try:
+            return datetime.strptime(raw, fmt).date()
+        except ValueError:
+            continue
+    raise ValueError(f"unparseable date: {raw!r} (want YYYY[-MM[-DD]])")
+
+
+def add_months(d: date, months: int) -> date:
+    total = d.month - 1 + months
+    year, month = d.year + total // 12, total % 12 + 1
+    return date(year, month, min(d.day, calendar.monthrange(year, month)[1]))
+
+
+def cmd_staleness(args) -> int:
+    try:
+        payload = json.loads(read_text(args.file))
+        windows = {k.lower(): int(v) for k, v in json.loads(args.windows).items()}
+        today = parse_date(args.today) if args.today else date.today()
+    except (ValueError, json.JSONDecodeError) as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+    claims = payload["claims"] if isinstance(payload, dict) else payload
+    results, no_window, stale_count = [], set(), 0
+    earliest: date | None = None
+    for c in claims:
+        cls = str(c.get("class", "")).lower()
+        try:
+            pub = parse_date(str(c["pub_date"]))
+        except (KeyError, ValueError) as e:
+            print(f"error in claim {c!r}: {e}", file=sys.stderr)
+            return 2
+        months = windows.get(cls)
+        if months is None:
+            no_window.add(cls)
+            results.append({**c, "recheck": None, "stale": None})
+            continue
+        recheck = add_months(pub, months)
+        stale = recheck <= today
+        stale_count += stale
+        earliest = recheck if earliest is None or recheck < earliest else earliest
+        results.append({**c, "recheck": recheck.isoformat(), "stale": stale})
+    return out({
+        "today": today.isoformat(),
+        "claims": results,
+        "stale_count": stale_count,
+        "earliest_recheck": earliest.isoformat() if earliest else None,
+        "no_window_classes": sorted(no_window),
+    }, 1 if stale_count else 0)
+
+
+# --- slug --------------------------------------------------------------------
+
+def slugify(text: str, max_len: int = 40) -> str:
+    text = unicodedata.normalize("NFKD", text).encode("ascii", "ignore").decode()
+    text = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
+    return re.sub(r"-{2,}", "-", text)[:max_len].rstrip("-")
+
+
+def cmd_slug(args) -> int:
+    slug = slugify(args.topic)
+    if not slug:
+        print("error: topic slugified to an empty string", file=sys.stderr)
+        return 2
+    folder = (args.pattern
+              .replace("{research_type}", args.type)
+              .replace("{topic_slug}", slug)
+              .replace("{date}", args.date or date.today().isoformat()))
+    return out({"topic_slug": slug, "folder": folder}, 0)
+
+
+# --- escape-sources ----------------------------------------------------------
+
+def safe_url(raw: str) -> str | None:
+    parsed = urlparse(raw)
+    return raw if parsed.scheme in ("http", "https") and parsed.netloc else None
+
+
+def cell_html(cell: str, invalid: list[str]) -> str:
+    """Escape a cell; a markdown link or bare URL becomes an <a> only when http(s)."""
+    link = MD_LINK_RE.search(cell)
+    if link:
+        url = safe_url(link.group(2))
+        label = html.escape(link.group(1) or link.group(2))
+        if url:
+            return html.escape(cell[:link.start()]) + \
+                f'<a href="{html.escape(url, quote=True)}" target="_blank" rel="noopener">{label}</a>' + \
+                html.escape(cell[link.end():])
+        invalid.append(link.group(2))
+        return html.escape(cell.replace(link.group(0), link.group(1) or link.group(2)))
+    bare = BARE_URL_RE.search(cell)
+    if bare:
+        url = safe_url(bare.group(0))
+        if url:
+            escaped = html.escape(url, quote=True)
+            return html.escape(cell[:bare.start()]) + \
+                f'<a href="{escaped}" target="_blank" rel="noopener">{escaped}</a>' + \
+                html.escape(cell[bare.end():])
+        invalid.append(bare.group(0))
+    return html.escape(cell)
+
+
+def cmd_escape_sources(args) -> int:
+    text = strip_fences(read_text(args.file))
+    rows = appendix_rows(text)
+    if not rows:
+        print("error: no source-appendix table rows found", file=sys.stderr)
+        return 2
+    invalid: list[str] = []
+    body_rows = []
+    for n in sorted(rows):
+        cells = rows[n]
+        tds = "".join(f"<td>{cell_html(c, invalid)}</td>" for c in cells[1:])
+        body_rows.append(f'<tr id="src-{n}"><td>[{n}]</td>{tds}</tr>')
+    table = ('<table class="sources"><tbody>' + "".join(body_rows) + "</tbody></table>")
+    return out({"rows": len(rows), "invalid_urls": invalid, "html": table},
+               1 if invalid else 0)
+
+
+# --- entry point -------------------------------------------------------------
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description=__doc__,
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    pc = sub.add_parser("citations", help="cross-check [n] markers vs the source appendix")
+    pc.add_argument("file", help="path to research.md (or - for stdin)")
+    pc.set_defaults(func=cmd_citations)
+
+    pt = sub.add_parser("tally", help="count memlog entries by type and claims by status")
+    pt.add_argument("file", help="path to .memlog.md (or - for stdin)")
+    pt.set_defaults(func=cmd_tally)
+
+    ps = sub.add_parser("staleness", help="compute re-check dates from freshness windows")
+    ps.add_argument("file", help="claims JSON: [{claim, class, pub_date}] (or - for stdin)")
+    ps.add_argument("--windows", required=True,
+                    help='JSON months-per-class map, e.g. \'{"pricing": 3}\'')
+    ps.add_argument("--today", help="override today's date (YYYY-MM-DD)")
+    ps.set_defaults(func=cmd_staleness)
+
+    pg = sub.add_parser("slug", help="expand the run-folder pattern deterministically")
+    pg.add_argument("topic", help="research topic text")
+    pg.add_argument("--type", required=True, help="research type code (e.g. market)")
+    pg.add_argument("--pattern", default="{research_type}-{topic_slug}-{date}",
+                    help="folder pattern (default: {research_type}-{topic_slug}-{date})")
+    pg.add_argument("--date", help="override date (YYYY-MM-DD; default today)")
+    pg.set_defaults(func=cmd_slug)
+
+    pe = sub.add_parser("escape-sources",
+                        help="source appendix as escaped HTML with validated links")
+    pe.add_argument("file", help="path to research.md (or - for stdin)")
+    pe.set_defaults(func=cmd_escape_sources)
+
+    args = p.parse_args(argv)
+    try:
+        return args.func(args)
+    except FileNotFoundError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/src/core-skills/bmad-deep-recon/scripts/tests/test_recon_kit.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# ///
+"""Tests for recon_kit.py."""
+
+import io
+import json
+import sys
+import unittest
+from contextlib import redirect_stdout
+from datetime import date
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from recon_kit import add_months, main, parse_date, slugify
+
+REPORT = """---
+title: 'market research: widgets'
+---
+
+# Report
+
+The market is growing fast [1] and pricing clusters at $20 [2].
+An uncited assertion sits here [4].
+
+```
+[9] inside a fence never counts
+```
+
+## Source appendix
+
+| [n] | Supports | Publisher | Pub date | Accessed | Confidence |
+| --- | --- | --- | --- | --- | --- |
+| [1] | market growth | [Gartner](https://example.com/g) | 2026-01 | 2026-07-01 | high |
+| [2] | pricing | [Acme](javascript:alert(1)) | 2026-05 | 2026-07-01 | medium |
+| [3] | never cited | https://example.com/x | 2025-11 | 2026-07-01 | low |
+"""
+
+MEMLOG = """---
+topic: widgets
+updated: 2026-07-22T10:00
+---
+
+- (decision) plan approved
+- (source) round 1 batch: 4 sources
+- (claim) ref=[1] status=verified class=size/growth pub=2026-01 — market growing 12% CAGR
+- (claim) ref=[2] status=unverified class=pricing pub=2026-05 — pricing clusters at $20
+- (claim) ref=[2] status=verified class=pricing pub=2026-05 — confirmed by second source
+- (claim) status=unverified class=behavior pub=2025-03 — users churn at day 8
+- (event) dimension 1 complete
+"""
+
+
+def run(argv):
+    buf = io.StringIO()
+    with redirect_stdout(buf):
+        code = main(argv)
+    return code, json.loads(buf.getvalue())
+
+
+class CitationsTest(unittest.TestCase):
+    def test_cross_check(self):
+        report = Path(__file__).parent / "_report.md"
+        report.write_text(REPORT, encoding="utf-8")
+        try:
+            code, result = run(["citations", str(report)])
+        finally:
+            report.unlink()
+        self.assertEqual(result["dangling_markers"], [4])
+        self.assertEqual(result["orphaned_rows"], [3])
+        self.assertNotIn(9, result["markers"])  # fenced content ignored
+        self.assertEqual(code, 1)
+
+
+class TallyTest(unittest.TestCase):
+    def test_last_status_wins_per_ref(self):
+        log = Path(__file__).parent / "_memlog.md"
+        log.write_text(MEMLOG, encoding="utf-8")
+        try:
+            code, result = run(["tally", str(log)])
+        finally:
+            log.unlink()
+        self.assertEqual(result["by_type"]["claim"], 4)
+        self.assertEqual(result["claims"], {"unverified": 1, "verified": 2})
+        self.assertEqual(result["claims_total"], 3)  # ref=[2] counted once
+        self.assertEqual(code, 0)
+
+
+class StalenessTest(unittest.TestCase):
+    def test_dates(self):
+        self.assertEqual(parse_date("2026-01"), date(2026, 1, 1))
+        self.assertEqual(add_months(date(2026, 1, 31), 1), date(2026, 2, 28))
+
+    def test_windows(self):
+        claims = json.dumps([
+            {"claim": "sizing", "class": "size/growth", "pub_date": "2024-06"},
+            {"claim": "pricing", "class": "pricing", "pub_date": "2026-06"},
+            {"claim": "odd", "class": "unmapped", "pub_date": "2026-06"},
+        ])
+        f = Path(__file__).parent / "_claims.json"
+        f.write_text(claims, encoding="utf-8")
+        try:
+            code, result = run([
+                "staleness", str(f),
+                "--windows", '{"size/growth": 18, "pricing": 3}',
+                "--today", "2026-07-22",
+            ])
+        finally:
+            f.unlink()
+        self.assertEqual(result["stale_count"], 1)  # sizing recheck 2025-12 < today
+        self.assertEqual(result["earliest_recheck"], "2025-12-01")
+        self.assertEqual(result["no_window_classes"], ["unmapped"])
+        self.assertEqual(code, 1)
+
+
+class SlugTest(unittest.TestCase):
+    def test_deterministic_folder(self):
+        self.assertEqual(slugify("Créme Brûlée: AI Tools!"), "creme-brulee-ai-tools")
+        code, result = run(["slug", "SMB Accounting SaaS", "--type", "market",
+                            "--date", "2026-07-22"])
+        self.assertEqual(result["folder"], "market-smb-accounting-saas-2026-07-22")
+        self.assertEqual(code, 0)
+
+
+class EscapeSourcesTest(unittest.TestCase):
+    def test_escaping_and_url_validation(self):
+        report = Path(__file__).parent / "_report.md"
+        report.write_text(REPORT, encoding="utf-8")
+        try:
+            code, result = run(["escape-sources", str(report)])
+        finally:
+            report.unlink()
+        self.assertEqual(result["rows"], 3)
+        self.assertTrue(any(u.startswith("javascript:") for u in result["invalid_urls"]))
+        self.assertNotIn("javascript:", result["html"])  # never linked
+        self.assertIn('href="https://example.com/g"', result["html"])
+        self.assertIn('id="src-1"', result["html"])
+        self.assertEqual(code, 1)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/src/core-skills/bmad-deep-recon/types/academic-lit.md

@@ -0,0 +1,19 @@
+# Academic Literature Pack
+
+Serves: ground an approach in published research, scan the state of the art, run a defensible literature review, cite properly in technical writing.
+
+**Dimensions (priority order — prune to the decision):**
+
+1. The canon — seminal papers and the best recent surveys of the area
+2. State of the art — current best results, benchmarks, and how they're measured
+3. Methods & limitations — what the leading approaches assume and where they break
+4. Open problems & live debates — what the field disagrees about right now
+5. Who works on this — the labs and groups whose output to watch
+
+**Craft (the non-obvious):** find one good survey before reading twenty abstracts; chase citations both directions — who they cite and who cites them (Semantic Scholar/Google Scholar); label preprint vs peer-reviewed on every citation — arXiv is not acceptance; take benchmark numbers from the original paper, never from a competitor's comparison table; check retraction and replication status on any load-bearing empirical claim; a result only ever shown by one lab is a lead, not a fact.
+
+**Freshness:** state-of-the-art claims ≤ 12 mo (ML ≤ 6 mo) · seminal work has no freshness bar — but check whether it was since superseded.
+
+**Two-source classes:** any empirical claim a conclusion rests on — independent replication or corroboration, not the same lab twice.
+
+**Feeds (bmm):** technical and architecture bets · content and writing that cites · build-vs-adopt judgments on research-grade techniques.

package/src/core-skills/bmad-deep-recon/types/competitive.md

@@ -0,0 +1,19 @@
+# Competitive Research Pack
+
+Serves: position against *named* competitors, build battlecards, sharpen differentiation, anticipate their next move. (Surveying an unnamed field is the market type; this pack is for teardowns of specific players.)
+
+**Dimensions (priority order — prune to the decision):**
+
+1. Offer & feature teardown — what they actually ship, tried directly where possible
+2. Pricing & packaging — models, tiers, what changed recently and which direction
+3. Positioning & messaging — who they claim to serve, the story they tell, the gap between claim and product
+4. Trajectory — funding, hiring, release cadence: where they're headed
+5. Their customers' voice — what users of *their* product praise and complain about
+
+**Craft (the non-obvious):** their changelog and release notes are roadmap truth; job postings reveal strategy six months early; their customers' 1–3★ reviews are your wedge; archived pricing pages (Wayback) show pricing direction, not just position; sales-facing comparison pages overclaim — verify capability claims against their docs; try the product yourself when a trial exists — an hour in-product beats ten reviews.
+
+**Freshness:** pricing & features ≤ 3 mo · trajectory signals ≤ 6 mo · customer sentiment ≤ 12 mo.
+
+**Two-source classes:** traction and market-share claims; any capability claim of theirs that your differentiation rests on.
+
+**Feeds (bmm):** brief (alternatives) · PRD (differentiation) · GTM battlecards and positioning.

package/src/core-skills/bmad-deep-recon/types/domain.md

@@ -0,0 +1,19 @@
+# Domain Research Pack
+
+Serves: commit to building in an industry, talk credibly with domain experts, scope a product for a regulated field, brief a team entering unfamiliar territory.
+
+**Dimensions (priority order — prune to the decision):**
+
+1. Industry structure & value chain — how value flows, who captures margin where
+2. Key players & gatekeepers — incumbents, platforms, whose APIs/standards/marketplaces you build with or against
+3. Rules of the game — laws, licenses, de-facto standards, what compliance costs a new entrant
+4. Language & mental models — the vocabulary and implicit workflows practitioners think in; **build the glossary — it's why domain research exists**
+5. Technology adoption — the current technical baseline and where the industry sits on the adoption curve
+
+**Craft (the non-obvious):** annual-report industry sections are free structured teardowns; conference keynotes reveal who actually matters; go to regulator sites directly for any load-bearing claim — and read enforcement actions to learn what's actually punished versus merely written; job postings name the real tools and skills; pending regulatory changes matter as much as current text.
+
+**Freshness:** structure ≤ 3 yr · player landscape ≤ 18 mo · regulatory status: verify current on every load-bearing claim, whatever its date · tech adoption ≤ 18 mo, AI-adoption claims ≤ 6 mo.
+
+**Two-source classes:** regulatory and compliance assertions; quantitative industry figures a recommendation rests on; claims about a gatekeeper's policy.
+
+**Feeds (bmm):** brief (context, feasibility) · PRD (constraints, domain vocabulary) · architecture (integration landscape, compliance requirements).

package/src/core-skills/bmad-deep-recon/types/market.md

@@ -0,0 +1,19 @@
+# Market Research Pack
+
+Serves: enter or skip a market, position a product, pick a segment, price an offer, pitch investors.
+
+**Dimensions (priority order — prune to the decision):**
+
+1. Market size & growth — the *reachable* market, not the headline TAM
+2. Customer segments & behavior — who buys, deciding how, valuing what
+3. Pain points & unmet needs — what they complain about, work around, pay to avoid
+4. Competitive landscape — who competes for this budget, including substitutes and "do nothing"
+5. GTM & pricing dynamics — channels, sales motion, accepted pricing models, realistic CAC
+
+**Craft (the non-obvious):** 1–3★ reviews are the gold for pains; public-company 10-K/S-1 industry sections are free analyst-grade sizing; read competitor pricing pages directly, never roundups; funding history + job postings reveal competitor trajectory; a complaint pattern persisting across years is a stronger finding, not a stale one.
+
+**Freshness:** size/growth ≤ 18 mo · pricing & feature claims ≤ 3 mo · behavior data ≤ 2 yr · GTM benchmarks ≤ 12 mo.
+
+**Two-source classes:** market size and growth figures; any quantitative claim a recommendation rests on; competitor traction claims.
+
+**Feeds (bmm):** brief (opportunity, problem, users) · PRD (personas, differentiation) · pricing and GTM decisions.

package/src/core-skills/bmad-deep-recon/types/technical.md

@@ -0,0 +1,19 @@
+# Technical Research Pack
+
+Serves: adopt a technology area, design an integration approach, ground an architecture in current practice, assess feasibility before committing a roadmap.
+
+**Dimensions (priority order — prune to the decision):**
+
+1. Landscape & maturity — dominant approaches, what's consolidating vs churning, what the current generation newly makes possible
+2. Integration & interoperability — protocols, formats, auth patterns, where integrations actually hurt
+3. Architecture patterns in practice — which named patterns dominate at what scale, and what the failures teach
+4. Implementation reality — learning curve, tooling, operational burden, what teams say 6–12 months in
+5. Ecosystem health — contributor/release vitality, backing durability, the five-year regret risk
+
+**Craft (the non-obvious):** read the retrospective threads, not the launch threads; favor accounts with production numbers over advocacy; before citing a pain point, check whether it was since fixed — an old complaint against a current version is a false claim; read repository metrics over time, never snapshots; issue trackers reveal the gap between docs and reality.
+
+**Freshness:** versions & compatibility ≤ 1 mo · ecosystem signals ≤ 6 mo · landscape ≤ 12 mo (AI-adjacent ≤ 3 mo) · patterns ≤ 2 yr.
+
+**Two-source classes:** version/compatibility claims; performance or scale numbers a recommendation rests on; claims that a technology or pattern failed — one post-mortem is an anecdote.
+
+**Feeds (bmm):** architecture spine (candidate paradigms, operational constraints) · brief (feasibility) · roadmap risk and estimates.

package/src/core-skills/bmad-deep-recon/types/user-voice.md

@@ -0,0 +1,19 @@
+# User-Voice Research Pack
+
+Serves: understand what users of a product or category actually experience and want — personas, jobs-to-be-done, requirements grounded in evidence rather than assumption.
+
+**Dimensions (priority order — prune to the decision):**
+
+1. Who they are & their jobs-to-be-done — the progress they're hiring the product to make
+2. Complaint & workaround patterns — where current options fail them
+3. Delight & switching triggers — why they stay, what made them move
+4. Unmet needs & requests — what they ask for, and the deeper need under the ask
+5. Their language — the words users say, versus the words vendors use
+
+**Craft (the non-obvious):** mine 1–3★ reviews for pain *and* 5★ for why they stay; a workaround is unpriced demand — someone laboring around a gap has already voted; forums, Discord, and Reddit surface what surveys miss — people lie less when nobody's asking — but they over-sample the loud, so triangulate against reviews and any survey data; keep verbatim quotes, redacted — user words carry evidence paraphrase destroys, but usernames, handles, emails, and identifying links never enter the report or memlog; feature-request boards measure willingness to wait, not willingness to pay; distinguish loud power-users from the silent majority — count distinct voices, not thread length.
+
+**Freshness:** sentiment ≤ 18 mo · complaints re-checked against the current version before citing.
+
+**Two-source classes:** any prevalence claim ("most users…", "the top complaint is…") — two independent communities, not two threads in the same one.
+
+**Feeds (bmm):** PRD (personas, requirements rationale) · UX research inputs · brief (problem) · product copy in the users' own language.

package/src/core-skills/bmad-forge-idea/SKILL.md

@@ -24,7 +24,7 @@ Lead by questioning, not lecturing. Ask one question at a time, press on weak po
 
 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 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. Load `{project-root}/_bmad/core/config.yaml` (and `config.user.yaml` if present); resolve `{user_name}`, `{communication_language}`, `{output_folder}`. Missing → neutral defaults; never block. Greet `{user_name}` in `{communication_language}` and stay in it.
+3. Resolve central config: `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} --key core`; from the merged JSON read `{user_name}`, `{communication_language}`, `{output_folder}`. On failure use neutral defaults; never block. Greet `{user_name}` in `{communication_language}` and stay in it.
 4. Note whether a BMad persona is already active in this conversation — the user loaded one (e.g. the analyst, the storyteller) and invoked the forge from within it. If so, that persona leads the session, in voice, throughout.
 5. 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.
 6. Run each `{workflow.activation_steps_append}` entry.
@@ -97,7 +97,7 @@ Voice the personas yourself by default. Spawn separate agents only when a branch
 
 The session can end in three valid states:
 
-- **Hardened** — the idea is stronger and specific enough to use. Distill the memlog into `{workspace}/forged-idea.md`. Keep it extremely short: only the decisions, rejected options, and reasons that matter downstream, in the user's meaning. Do not write a prose summary, template, or conversation recap. If it reads like a document, it is too long. Note that it can feed `bmad-spec`, `bmad-prd`, or `bmad-prfaq`.
+- **Hardened** — the idea is stronger and specific enough to use. Distill the memlog into `{workspace}/forged-idea.md`. Keep it extremely short: only the decisions, rejected options, and reasons that matter downstream, in the user's meaning. Do not write a prose summary, template, or conversation recap. If it reads like a document, it is too long. If planning or dev skills are installed (`bmad-spec`, `bmad-prd`, `bmad-prfaq`, `bmad-quick-dev`), offer the file as their input; if none are, the file stands on its own — never treat a missing skill as an error.
 - **Killed** — the idea does not hold up. Say so plainly and record why. Finding that out early is a valid outcome.
 - **Clearer** — the user understands the idea better, but there is no hardened idea to hand off. Leave the memlog as the record; no `forged-idea.md` is needed.
 

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

@@ -186,7 +186,10 @@ def build_pool(agents: dict, party_members: list):
             continue
         canonical = index.get(code) or index.get(code.lower()) or code
         was_installed = canonical in pool
-        entry = {"code": canonical, "source": "custom"}
+        # Start from the installed entry so fields the override omits
+        # (icon, title, description) survive.
+        entry = dict(pool.get(canonical, {}))
+        entry.update({"code": canonical, "source": "custom"})
         for field in ("name", "icon", "title", "persona", "capabilities", "model"):
             if m.get(field) is not None:
                 entry[field] = m[field]

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

@@ -23,7 +23,7 @@ When this skill completes, the user should:
 ## Data Sources
 
 - **Catalog**: `{project-root}/_bmad/_config/bmad-help.csv` — assembled manifest of all installed module skills
-- **Config**: Run `uv run --python 3.11 {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root}` and use the merged JSON to resolve `output-location` variables and read `core.communication_language` and `modules.bmm.project_knowledge`. The resolver merges `_bmad/config.toml`, `_bmad/config.user.toml`, `_bmad/custom/config.toml`, and `_bmad/custom/config.user.toml` in that order.
+- **Config**: Run `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root}` and use the merged JSON to resolve `output-location` variables and read `core.communication_language` and `modules.bmm.project_knowledge`. The resolver merges `_bmad/config.toml`, `_bmad/config.user.toml`, `_bmad/custom/config.toml`, and `_bmad/custom/config.user.toml` in that order.
 - **Artifacts**: Files matching `outputs` patterns at resolved `output-location` paths reveal which steps are possibly completed; their content may also provide grounding context for recommendations
 - **Project knowledge**: If `project_knowledge` resolves to an existing path, read it for grounding context. Never fabricate project-specific details.
 - **Module docs**: Rows with `_meta` in the `skill` column carry a URL or path in `output-location` pointing to the module's documentation (e.g., llms.txt). Fetch and use these to answer general questions about that module.

package/src/core-skills/bmad-party-mode/SKILL.md

@@ -10,14 +10,14 @@ Run a round-table where these agents talk to each other and to the user like rea
 ## Conventions
 
 - **Paths:** bare paths (e.g. `references/create-party.md`) resolve from `{skill-root}` (where `customize.toml` lives); `{project-root}`-prefixed paths from the project working dir. `{workflow.<name>}` resolves to `customize.toml`'s `[workflow]` table (overrides win).
-- **Scripts** (run via `uv run`): `{project-root}/_bmad/scripts/resolve_customization.py` resolves `{workflow.*}`; `{skill-root}/scripts/resolve_party.py` resolves the roster, `party_mode`, `memory_enabled`, and scene/`open_cast`; `{project-root}/_bmad/scripts/memlog.py` reads/writes per-party memory.
+- **Scripts** (run via `uv run`): `{project-root}/_bmad/scripts/resolve_config.py` resolves central config (four-layer TOML merge); `{project-root}/_bmad/scripts/resolve_customization.py` resolves `{workflow.*}`; `{skill-root}/scripts/resolve_party.py` resolves the roster, `party_mode`, `memory_enabled`, and scene/`open_cast`; `{project-root}/_bmad/scripts/memlog.py` reads/writes per-party memory.
 - **File roles:** a party's memory is the per-party memlog at `{workflow.memory_dir}/<party>/.memlog.md`; custom members and groups live in the user's `customize.toml` overrides. Mechanics in `references/party-memory.md` (memory) and `references/create-party.md` (authoring).
 - **Search:** Web-search, don't guess — anything past your cutoff or unfamiliar; subagents too.
 
 ## On Activation
 
 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. Then run each `{workflow.activation_steps_prepend}` entry, and hold each `{workflow.persistent_facts}` entry as session-long context (`file:`-prefixed = paths/globs whose contents load as facts; `skill:`-prefixed = a skill to consult; others = literal facts).
-2. Load `{project-root}/_bmad/core/config.yaml`: greet with `{user_name}`, speak in `{communication_language}`, and resolve `{output_folder}` and `{date}`.
+2. **Resolve core config:** `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root}`. From the merged JSON's `core` table: greet with `{user_name}`, speak in `{communication_language}`, and resolve `{output_folder}`; `{date}` is today's date.
 3. **Detect intent and route.** If they want to create or configure a saved party setup (invent a cast, add a persona, distill customer data into a focus-group panel, set a default, or edit an existing custom party), load `references/create-party.md` and follow it. Otherwise run a party — continue below.
 4. **Resolve the roster:** `uv run {skill-root}/scripts/resolve_party.py --project-root {project-root} --skill {skill-root}`. It returns the active roster (`{workflow.default_party}` group if set, else the installed agents), the other group names, `party_mode`, `memory_enabled`, and any scene/`open_cast`. Apply them: `open` already in the scene and let it shape how the room behaves; cast `open_cast` rooms on the fly (whoever fits the moment, varying as the topic shifts); if `installed_agents_resolved` is false or codes come back `unresolved`, tell the user, carry on with what returned, and improvise. Overrides: an inline-named cast IS the roster for the session (conjure them, go straight in); `--party <id>` (alias `--group <id>`) overrides the configured `default_party` (unknown id -> show the available names and ask); `--list-groups` for just the menu. Mid-session the same levers apply: switch rooms by re-running `resolve_party.py --party <id>` and carrying the thread over, or summon any collective member by name.
 5. **Memory.** If `memory_enabled` (from `resolve_party.py`), follow `references/party-memory.md` for the whole run.