ma-agents 3.12.2 → 3.13.0

package/lib/bmad-cache/bmb/skills/bmad-module-builder/assets/setup-skill-template/scripts/merge-config.py

@@ -339,9 +339,42 @@ def write_config(config: dict, config_path: str, verbose: bool = False) -> None:
         )
 
 
+def reject_unresolved_paths(named_paths: list[tuple[str, str]]) -> None:
+    """Exit with a clear error if any path argument still contains the literal
+    ``{project-root}`` token. That token is meaningful only inside config
+    values; filesystem path arguments must be resolved by the caller. Failing
+    loudly here prevents silently creating a junk ``{project-root}/`` directory.
+    """
+    for name, value in named_paths:
+        if value and "{project-root}" in value:
+            print(
+                json.dumps(
+                    {
+                        "status": "error",
+                        "error": (
+                            f"Unresolved '{{project-root}}' token in {name} path: {value!r}. "
+                            "Resolve '{project-root}' to the actual project root before running "
+                            "this script — it is a filesystem path, not a config value."
+                        ),
+                    },
+                    indent=2,
+                ),
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+
 def main():
     args = parse_args()
 
+    reject_unresolved_paths(
+        [
+            ("--config-path", args.config_path),
+            ("--user-config-path", args.user_config_path),
+            ("--legacy-dir", args.legacy_dir),
+        ]
+    )
+
     # Load inputs
     module_yaml = load_yaml_file(args.module_yaml)
     if not module_yaml:

package/lib/bmad-cache/bmb/skills/bmad-module-builder/assets/setup-skill-template/scripts/merge-help-csv.py

@@ -139,9 +139,37 @@ def cleanup_legacy_csvs(
     return deleted
 
 
+def reject_unresolved_paths(named_paths: list[tuple[str, str]]) -> None:
+    """Exit with a clear error if any path argument still contains the literal
+    ``{project-root}`` token. That token is meaningful only inside config
+    values; filesystem path arguments must be resolved by the caller. Failing
+    loudly here prevents silently creating a junk ``{project-root}/`` directory.
+    """
+    for name, value in named_paths:
+        if value and "{project-root}" in value:
+            print(
+                json.dumps(
+                    {
+                        "status": "error",
+                        "error": (
+                            f"Unresolved '{{project-root}}' token in {name} path: {value!r}. "
+                            "Resolve '{project-root}' to the actual project root before running "
+                            "this script — it is a filesystem path, not a config value."
+                        ),
+                    },
+                    indent=2,
+                )
+            )
+            sys.exit(1)
+
+
 def main():
     args = parse_args()
 
+    reject_unresolved_paths(
+        [("--target", args.target), ("--legacy-dir", args.legacy_dir)]
+    )
+
     # Read source entries
     source_header, source_rows = read_csv_rows(args.source)
     if not source_rows:

package/lib/bmad-cache/bmb/skills/bmad-module-builder/assets/standalone-module-template/merge-config.py

@@ -339,9 +339,42 @@ def write_config(config: dict, config_path: str, verbose: bool = False) -> None:
         )
 
 
+def reject_unresolved_paths(named_paths: list[tuple[str, str]]) -> None:
+    """Exit with a clear error if any path argument still contains the literal
+    ``{project-root}`` token. That token is meaningful only inside config
+    values; filesystem path arguments must be resolved by the caller. Failing
+    loudly here prevents silently creating a junk ``{project-root}/`` directory.
+    """
+    for name, value in named_paths:
+        if value and "{project-root}" in value:
+            print(
+                json.dumps(
+                    {
+                        "status": "error",
+                        "error": (
+                            f"Unresolved '{{project-root}}' token in {name} path: {value!r}. "
+                            "Resolve '{project-root}' to the actual project root before running "
+                            "this script — it is a filesystem path, not a config value."
+                        ),
+                    },
+                    indent=2,
+                ),
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+
 def main():
     args = parse_args()
 
+    reject_unresolved_paths(
+        [
+            ("--config-path", args.config_path),
+            ("--user-config-path", args.user_config_path),
+            ("--legacy-dir", args.legacy_dir),
+        ]
+    )
+
     # Load inputs
     module_yaml = load_yaml_file(args.module_yaml)
     if not module_yaml:

package/lib/bmad-cache/bmb/skills/bmad-module-builder/assets/standalone-module-template/merge-help-csv.py

@@ -139,9 +139,37 @@ def cleanup_legacy_csvs(
     return deleted
 
 
+def reject_unresolved_paths(named_paths: list[tuple[str, str]]) -> None:
+    """Exit with a clear error if any path argument still contains the literal
+    ``{project-root}`` token. That token is meaningful only inside config
+    values; filesystem path arguments must be resolved by the caller. Failing
+    loudly here prevents silently creating a junk ``{project-root}/`` directory.
+    """
+    for name, value in named_paths:
+        if value and "{project-root}" in value:
+            print(
+                json.dumps(
+                    {
+                        "status": "error",
+                        "error": (
+                            f"Unresolved '{{project-root}}' token in {name} path: {value!r}. "
+                            "Resolve '{project-root}' to the actual project root before running "
+                            "this script — it is a filesystem path, not a config value."
+                        ),
+                    },
+                    indent=2,
+                )
+            )
+            sys.exit(1)
+
+
 def main():
     args = parse_args()
 
+    reject_unresolved_paths(
+        [("--target", args.target), ("--legacy-dir", args.legacy_dir)]
+    )
+
     # Read source entries
     source_header, source_rows = read_csv_rows(args.source)
     if not source_rows:

package/lib/bmad-cache/bmb/skills/bmad-module-builder/scripts/tests/test-validate-module.py

@@ -12,7 +12,8 @@ from pathlib import Path
 
 SCRIPT = Path(__file__).resolve().parent.parent / "validate-module.py"
 
-CSV_HEADER = "module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs\n"
+CSV_HEADER = "module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs\n"
+LEGACY_CSV_HEADER = "module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs\n"
 
 
 def create_module(tmp: Path, skills: list[str] | None = None, csv_rows: str = "",
@@ -162,6 +163,75 @@ def test_empty_csv():
         assert len(empty) == 1
 
 
+def test_canonical_header_accepted():
+    """The canonical preceded-by/followed-by header must NOT produce a header finding."""
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp = Path(tmp)
+        csv_rows = 'Test Module,tst-foo,Do Foo,DF,Does foo,run,,anytime,,,false,output_folder,report\n'
+        module_dir = create_module(tmp, skills=["tst-foo"], csv_rows=csv_rows)
+
+        code, data = run_validate(module_dir)
+        assert code == 0, f"expected a clean pass: {data}"
+        assert data["status"] == "pass"
+        header_findings = [f for f in data["findings"] if f["category"] == "csv-header"]
+        assert header_findings == [], f"unexpected header findings: {header_findings}"
+
+
+def test_legacy_after_before_header_flagged():
+    """A module-help.csv using the old after/before column names must be flagged as
+    a header mismatch — canonical is preceded-by/followed-by (matches the templates
+    and bmad-help). Regression for the CSV_HEADER drift in validate-module.py."""
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp = Path(tmp)
+        module_dir = tmp / "module"
+        module_dir.mkdir()
+        setup = module_dir / "tst-setup"
+        setup.mkdir()
+        (setup / "SKILL.md").write_text("---\nname: tst-setup\n---\n# Setup\n")
+        (setup / "assets").mkdir()
+        (setup / "assets" / "module.yaml").write_text(
+            'code: tst\nname: "Test Module"\ndescription: "A test module"\n'
+        )
+        (setup / "assets" / "module-help.csv").write_text(
+            LEGACY_CSV_HEADER
+            + 'Test Module,tst-foo,Do Foo,DF,Does foo,run,,anytime,,,false,output_folder,report\n'
+        )
+        (module_dir / "tst-foo").mkdir()
+        (module_dir / "tst-foo" / "SKILL.md").write_text("---\nname: tst-foo\n---\n# tst-foo\n")
+
+        code, data = run_validate(module_dir)
+        assert code == 1, f"expected fail (high-severity header finding): {data}"
+        assert data["status"] == "fail"
+        header_findings = [f for f in data["findings"] if f["category"] == "csv-header"]
+        assert len(header_findings) == 1, f"expected a csv-header finding: {data['findings']}"
+        msg = header_findings[0]["message"]
+        # missing the new names, has the legacy ones
+        assert "preceded-by" in msg and "followed-by" in msg
+        assert "after" in msg and "before" in msg
+
+
+def test_short_row_does_not_crash():
+    """A CSV row with fewer fields than the header must not crash the validator and
+    must be reported as a column-count mismatch. DictReader fills the missing
+    columns with None by default, so the validator's `.strip()` calls would raise
+    AttributeError on a short row — restval="" keeps them safe. Regression test."""
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp = Path(tmp)
+        # Only 5 of the 13 columns present (the remaining 8 are missing entirely).
+        csv_rows = 'Test Module,tst-foo,Do Foo,DF,Does foo\n'
+        module_dir = create_module(tmp, skills=["tst-foo"], csv_rows=csv_rows)
+
+        code, data = run_validate(module_dir)
+        # Valid JSON with findings means the script completed instead of crashing
+        # with an uncaught traceback (which run_validate would surface as raw_*).
+        assert "findings" in data, f"validator crashed instead of reporting: {data}"
+        # A short row is a medium-severity finding: reported, but non-fatal.
+        assert code == 0 and data["status"] == "pass", f"expected non-fatal pass: {data}"
+        col_findings = [f for f in data["findings"] if f["category"] == "csv-columns"]
+        assert len(col_findings) == 1, f"expected a csv-columns finding: {data['findings']}"
+        assert "5 columns" in col_findings[0]["message"]
+
+
 def create_standalone_module(tmp: Path, skill_name: str = "my-skill",
                              csv_rows: str = "", yaml_content: str = "",
                              include_setup_md: bool = True,
@@ -290,6 +360,9 @@ if __name__ == "__main__":
         test_invalid_before_after_ref,
         test_missing_yaml_fields,
         test_empty_csv,
+        test_canonical_header_accepted,
+        test_legacy_after_before_header_flagged,
+        test_short_row_does_not_crash,
         test_valid_standalone_module,
         test_standalone_missing_module_setup_md,
         test_standalone_missing_merge_scripts,

package/lib/bmad-cache/bmb/skills/bmad-module-builder/scripts/validate-module.py

@@ -13,7 +13,7 @@ Performs deterministic structural checks:
 - All skill folders have at least one capability entry in the CSV
 - No orphan CSV entries pointing to nonexistent skills
 - Menu codes are unique
-- Before/after references point to real capability entries
+- preceded-by/followed-by references point to real capability entries
 - Required module.yaml fields are present
 - CSV column count is consistent
 """
@@ -28,7 +28,7 @@ from pathlib import Path
 REQUIRED_YAML_FIELDS = {"code", "name", "description"}
 CSV_HEADER = [
     "module", "skill", "display-name", "menu-code", "description",
-    "action", "args", "phase", "after", "before", "required",
+    "action", "args", "phase", "preceded-by", "followed-by", "required",
     "output-location", "outputs",
 ]
 
@@ -77,12 +77,22 @@ def parse_yaml_minimal(text: str) -> dict[str, str]:
     return result
 
 
-def parse_csv_rows(csv_text: str) -> tuple[list[str], list[dict[str, str]]]:
-    """Parse CSV text into header and list of row dicts."""
-    reader = csv.DictReader(StringIO(csv_text))
+def parse_csv_rows(csv_text: str) -> tuple[list[str], list[dict[str, str]], list[int]]:
+    """Parse CSV text into (header, row dicts, raw column count per data row).
+
+    ``restval=""`` fills missing trailing fields in a short row with empty strings
+    instead of ``None``, so downstream ``.strip()`` calls stay safe on malformed
+    rows. DictReader pads short rows to the header width, so ``len(row)`` cannot
+    reveal a field shortfall; the raw per-row column counts from ``csv.reader``
+    (blank lines skipped, to stay aligned with DictReader) are returned separately
+    for the column-count consistency check.
+    """
+    reader = csv.DictReader(StringIO(csv_text), restval="")
     header = reader.fieldnames or []
     rows = list(reader)
-    return header, rows
+    raw_rows = list(csv.reader(StringIO(csv_text)))
+    col_counts = [len(r) for r in raw_rows[1:] if r != []]
+    return header, rows, col_counts
 
 
 def validate(module_dir: Path, verbose: bool = False) -> dict:
@@ -163,7 +173,7 @@ def validate(module_dir: Path, verbose: bool = False) -> dict:
 
     # 4. Parse and validate CSV
     csv_text = (csv_dir / "assets" / "module-help.csv").read_text(encoding="utf-8")
-    header, rows = parse_csv_rows(csv_text)
+    header, rows, col_counts = parse_csv_rows(csv_text)
 
     # Check header
     if header != CSV_HEADER:
@@ -182,11 +192,12 @@ def validate(module_dir: Path, verbose: bool = False) -> dict:
 
     info["csv_entries"] = len(rows)
 
-    # 5. Check column count consistency
+    # 5. Check column count consistency (using raw field counts: DictReader pads
+    #    short rows to the header width, so len(row) alone can't detect a shortfall)
     expected_cols = len(CSV_HEADER)
-    for i, row in enumerate(rows):
-        if len(row) != expected_cols:
-            finding("medium", "csv-columns", f"Row {i + 2} has {len(row)} columns, expected {expected_cols}",
+    for i, (row, n_cols) in enumerate(zip(rows, col_counts)):
+        if n_cols != expected_cols:
+            finding("medium", "csv-columns", f"Row {i + 2} has {n_cols} columns, expected {expected_cols}",
                     f"skill={row.get('skill', '?')}")
 
     # 6. Collect skills from CSV and filesystem
@@ -220,7 +231,7 @@ def validate(module_dir: Path, verbose: bool = False) -> dict:
         if len(names) > 1:
             finding("high", "duplicate-menu-code", f"Menu code '{code}' used by multiple entries: {', '.join(names)}")
 
-    # 10. Before/after reference validation
+    # 10. preceded-by/followed-by reference validation
     # Build set of valid capability references (skill:action)
     valid_refs = set()
     for row in rows:
@@ -231,7 +242,7 @@ def validate(module_dir: Path, verbose: bool = False) -> dict:
 
     for row in rows:
         display = row.get("display-name", "?")
-        for field in ("after", "before"):
+        for field in ("preceded-by", "followed-by"):
             value = row.get(field, "").strip()
             if not value:
                 continue

package/lib/bmad-cache/bmb/skills/bmad-workflow-builder/assets/sample-customize-product-brief.toml

@@ -1,51 +1,66 @@
-# SAMPLE -- reference copy of bmad-product-brief's customize.toml (from bmm).
-# Use as a worked example when lifting configurables during Configurability Discovery.
-# This is NOT emitted into built skills; it's ground-truth reference for authors.
-
 # DO NOT EDIT -- overwritten on every update.
 #
-# Workflow customization surface for bmad-product-brief. Mirrors the
-# agent customization shape under the [workflow] namespace.
+# Workflow customization surface for bmad-product-brief.
+#
+# Override files (not edited here):
+#   {project-root}/_bmad/custom/bmad-product-brief.toml         (team)
+#   {project-root}/_bmad/custom/bmad-product-brief.user.toml    (personal)
 
 [workflow]
 
 # --- Configurable below. Overrides merge per BMad structural rules: ---
-#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
-#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+#   scalars: override wins • arrays: append
 
 # Steps to run before the standard activation (config load, greet).
-# Overrides append. Use for pre-flight loads, compliance checks, etc.
-
+# Use for pre-flight loads, compliance checks, etc.
 activation_steps_prepend = []
 
-# Steps to run after greet but before Stage 1 of the workflow.
-# Overrides append. Use for context-heavy setup that should happen
-# once the user has been acknowledged.
-
+# Steps to run after greet but before the workflow begins.
+# Use for context-heavy setup that should happen once the user has been acknowledged.
 activation_steps_append = []
 
 # Persistent facts the workflow keeps in mind for the whole run
 # (standards, compliance constraints, stylistic guardrails).
-# Distinct from the runtime memory sidecar -- these are static context
-# loaded on activation. Overrides append.
-#
-# Each entry is either:
-#   - a literal sentence, e.g. "All briefs must include a regulatory-risk section."
-#   - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/standards.md"
-#     (glob patterns are supported; the file's contents are loaded and treated as facts).
-
-persistent_facts = [
-  "file:{project-root}/**/project-context.md",
-]
+# Each entry is either a literal sentence, a skill prefixed with `skill:`, or a `file:`-prefixed path/glob
+# whose contents are loaded as facts.
+# Default is empty. Common opt-ins (set in your team/user override TOML):
+#   "file:{project-root}/_bmad-output/planning-artifacts/project-context.md"  # bmad-generate-project-context output
+#   "skill:acme-co:terms-and-conditions"                                      # a skill that contains some relevant info to the documents that may be generated
+#   "Elvis has left the building"                                             # generic agent instructions
+persistent_facts = []
 
-# Path to the brief structure template used in Stage 4 drafting.
-# Bare paths resolve from the skill root; use `{project-root}/...` to
-# point at an org-owned template elsewhere in the repo. Override wins.
+# Executed when the workflow completes (after the user has been told the
+# brief is ready). Accepts either a string scalar (single instruction)
+# or an array of instructions executed in order. Empty for none.
+on_complete = ""
 
-brief_template = "resources/brief-template.md"
+# Default brief structure. Treated as a starting point — the LLM adapts it
+# to the product, purpose, and domain. Override the path in team/user TOML
+# to enforce a different structure (e.g. regulated-industry, investor-deck).
+brief_template = "assets/brief-template.md"
 
-# Scalar: executed when the workflow reaches its terminal stage, after
-# the main output has been delivered. Override wins. Leave empty for
-# no custom post-completion behavior.
+# Run folder location. The brief, optional addendum, and optional distillate
+# all land inside `{output_dir}/{output_folder_name}/`.
+output_dir = "{planning_artifacts}/briefs"
+output_folder_name = "brief-{project_name}-{date}"
 
-on_complete = ""
+# Document standards applied to human-consumed docs at finalize. Each entry is
+# a `skill:`, `file:`, or plain-text directive; the parent LLM applies the
+# findings before the user sees the draft. Encodes standards, not options.
+#
+# Examples:
+#   "skill:bmad-editorial-review-prose"
+#   "file:{project-root}/_bmad/style-guides/company-voice.md"
+#   "Convert all dates to ISO 8601 format."
+#
+# Suggested order (broader passes first, narrower last):
+#   1. Structural (cuts, reorganization, section sizing)
+#   2. Content/voice/conventions (org standards, tone, terminology, compliance)
+#   3. Prose mechanics (grammar, clarity, typos)
+#
+# Override the array in team/user TOML to add additional standards. Append-only:
+# base entries cannot be removed or replaced (resolver has no removal mechanism).
+doc_standards = [
+  "skill:bmad-editorial-review-structure",
+  "skill:bmad-editorial-review-prose",
+]