bmad-method 6.8.1-next.2 → 6.8.1-next.20

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

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# ///
+"""Unit tests for resolve_party.py — merge, alias, override, group resolution."""
+
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+import resolve_party as rp  # noqa: E402
+
+AGENTS = {
+    "bmad-agent-analyst": {"name": "Mary", "icon": "📊", "title": "Analyst"},
+    "bmad-agent-pm": {"name": "John", "icon": "📋", "title": "PM"},
+}
+
+
+class TestAlias(unittest.TestCase):
+    def test_strips_known_prefixes(self):
+        self.assertEqual(rp._alias("bmad-agent-analyst"), "analyst")
+        self.assertEqual(rp._alias("bmad-foo"), "foo")
+
+    def test_passes_through_unprefixed(self):
+        self.assertEqual(rp._alias("morpheus"), "morpheus")
+
+
+class TestBuildCollective(unittest.TestCase):
+    def test_installed_agents_indexed_by_code_alias_and_name(self):
+        col, idx, _ = rp.build_collective(AGENTS, [])
+        self.assertEqual(set(col), {"bmad-agent-analyst", "bmad-agent-pm"})
+        self.assertEqual(idx["analyst"], "bmad-agent-analyst")      # alias
+        self.assertEqual(idx["mary"], "bmad-agent-analyst")         # name (ci)
+        self.assertEqual(idx["bmad-agent-pm"], "bmad-agent-pm")     # full code
+        self.assertEqual(col["bmad-agent-analyst"]["source"], "installed")
+
+    def test_custom_member_appends(self):
+        col, _, _ = rp.build_collective(AGENTS, [{"code": "morpheus", "name": "Morpheus", "persona": "riddles"}])
+        self.assertIn("morpheus", col)
+        self.assertEqual(col["morpheus"]["source"], "custom")
+        self.assertEqual(col["morpheus"]["persona"], "riddles")
+
+    def test_custom_overrides_installed_by_alias(self):
+        col, _, _ = rp.build_collective(AGENTS, [{"code": "analyst", "name": "Mary-Custom", "persona": "p"}])
+        # Override lands on the canonical installed code, not a new "analyst" entry.
+        self.assertNotIn("analyst", col)
+        self.assertEqual(col["bmad-agent-analyst"]["source"], "custom")
+        self.assertEqual(col["bmad-agent-analyst"]["name"], "Mary-Custom")
+
+    def test_member_without_code_skipped(self):
+        col, _, _ = rp.build_collective(AGENTS, [{"name": "Nameless"}])
+        self.assertEqual(set(col), {"bmad-agent-analyst", "bmad-agent-pm"})
+
+
+class TestResolveMembers(unittest.TestCase):
+    def setUp(self):
+        self.col, self.idx, _ = rp.build_collective(AGENTS, [{"code": "morpheus", "name": "Morpheus"}])
+
+    def test_resolves_in_listed_order_and_flags_unknowns(self):
+        resolved, unresolved = rp.resolve_members(["morpheus", "analyst", "ghost"], self.col, self.idx)
+        self.assertEqual([m["code"] for m in resolved], ["morpheus", "bmad-agent-analyst"])
+        self.assertEqual(unresolved, ["ghost"])
+
+    def test_empty(self):
+        self.assertEqual(rp.resolve_members([], self.col, self.idx), ([], []))
+
+
+class TestGroups(unittest.TestCase):
+    GROUPS = [
+        {"id": "wr", "name": "Writers", "members": ["analyst", "morpheus"]},
+        {"id": "bad"},  # no name -> falls back to id; no members -> count 0
+        {"name": "no-id"},  # dropped from menu
+    ]
+
+    def test_menu_is_names_only_with_counts_and_open_cast_flag(self):
+        menu = rp.group_menu(self.GROUPS)
+        self.assertEqual(menu, [
+            {"id": "wr", "name": "Writers", "member_count": 2},
+            {"id": "bad", "name": "bad", "member_count": 0, "open_cast": True},
+        ])
+
+    def test_find_group(self):
+        self.assertEqual(rp.find_group(self.GROUPS, "wr")["name"], "Writers")
+        self.assertIsNone(rp.find_group(self.GROUPS, "missing"))
+
+
+class TestGroupDetail(unittest.TestCase):
+    def setUp(self):
+        self.col, self.idx, _ = rp.build_collective(AGENTS, [{"code": "morpheus", "name": "Morpheus"}])
+
+    def test_scene_passes_through_when_present(self):
+        g = {"id": "tos-10-forward", "name": "Ten Forward", "members": ["morpheus"],
+             "scene": "Late evening, a few rounds in."}
+        d = rp.group_detail(g, self.col, self.idx)
+        self.assertEqual(d["scene"], "Late evening, a few rounds in.")
+        self.assertEqual([m["code"] for m in d["members"]], ["morpheus"])
+
+    def test_scene_omitted_when_absent_or_empty(self):
+        for g in ({"id": "g", "members": ["morpheus"]},
+                  {"id": "g", "members": ["morpheus"], "scene": ""}):
+            self.assertNotIn("scene", rp.group_detail(g, self.col, self.idx))
+
+    def test_anchored_group_is_not_open_cast(self):
+        g = {"id": "g", "members": ["morpheus"]}
+        self.assertNotIn("open_cast", rp.group_detail(g, self.col, self.idx))
+
+    def test_open_cast_group_flagged_with_empty_members(self):
+        g = {"id": "rebels", "name": "Star Wars Rebels",
+             "scene": "Figures from the Rebels universe drop in as the topic calls for them."}
+        d = rp.group_detail(g, self.col, self.idx)
+        self.assertTrue(d["open_cast"])
+        self.assertEqual(d["members"], [])
+        self.assertEqual(d["scene"][:7], "Figures")
+
+    def test_memory_enabled_follows_group_flag_and_defaults_off(self):
+        on = rp.group_detail({"id": "g", "members": ["morpheus"], "memory": True}, self.col, self.idx)
+        self.assertTrue(on["memory_enabled"])
+        off = rp.group_detail({"id": "g", "members": ["morpheus"], "memory": False}, self.col, self.idx)
+        self.assertFalse(off["memory_enabled"])
+        absent = rp.group_detail({"id": "g", "members": ["morpheus"]}, self.col, self.idx)
+        self.assertFalse(absent["memory_enabled"])  # opt-in per named group
+
+
+class TestInstalledCodesIsDefaultRoom(unittest.TestCase):
+    """The default room is installed agents only; pure customs stay in the pool."""
+
+    def test_pure_custom_excluded_override_kept_in_default_room(self):
+        col, _, installed = rp.build_collective(AGENTS, [
+            {"code": "morpheus", "name": "Morpheus"},                 # pure custom
+            {"code": "analyst", "name": "Mary-Custom", "persona": "p"},  # override
+            {"code": "sec-hawk", "name": "Vex"},                      # shipped crew member
+        ])
+        # Pure customs are in the pool...
+        self.assertIn("morpheus", col)
+        self.assertIn("sec-hawk", col)
+        # ...but NOT in the default room.
+        self.assertEqual(installed, ["bmad-agent-analyst", "bmad-agent-pm"])
+        default_room = [col[c]["code"] for c in installed]
+        self.assertEqual(default_room, ["bmad-agent-analyst", "bmad-agent-pm"])
+        # An override keeps its installed slot (and its custom content).
+        self.assertEqual(col["bmad-agent-analyst"]["name"], "Mary-Custom")
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -18,7 +18,7 @@ Multiple skills may call to update the same spec over time.
 
 ## On Activation
 
-1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly.
+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.
 2. Run `{workflow.activation_steps_prepend}`. Treat `{workflow.persistent_facts}` as foundational context (`file:` entries are loaded).
 3. Load `{project-root}/_bmad/core/config.yaml` (and `config.user.yaml` if present), root level and `bmm` section. Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`.
 4. Detect mode. **Headless** when any of: no TTY, programmatic caller (another skill or non-interactive runner), or the first message pre-supplies all inputs and asks for an artifact path back. **Interactive** otherwise. In interactive mode, greet by `{user_name}` in `{communication_language}`, stay in that language, and mention that `bmad-party-mode` and `bmad-advanced-elicitation` are available for deeper exploration on any field.
@@ -43,22 +43,38 @@ Inside the spec folder:
 
 ```
 <spec-folder>/
-  SPEC.md                  ← uppercase, the kernel
-  <companion-1>.md         ← optional, content-typed (e.g. glossary.md)
+  SPEC.md                  ← uppercase, the kernel — DERIVED from .memlog.md, never hand-edited
+  <companion-1>.md         ← optional, content-typed (e.g. glossary.md); spec-authored ones are derived too
   <companion-2>.md
-  .decision-log.md         ← canonical memory for this spec
+  .memlog.md               ← canonical, append-only memory; what SPEC.md is distilled from
 ```
 
+## Memory and derivation
+
+`.memlog.md` is canonical — an append-only, chronological record of every decision, constraint, capability (with its stable `CAP-N`), assumption, open question, and bit of user direction, one line each in the order it happened, never edited or reordered. `SPEC.md` and every spec-authored companion are **derived on each run** from the memlog (the decision-of-record) plus the sources it cites for raw content — never hand-patched.
+
+Deriving the contract from a living log instead of editing the contract in place is what lets the steps around the spec (PRD, UX, architecture, epics) run in any order and feed the same spec without merge drift: the log only accumulates, the artifact is re-rendered. So the spec is updated *only* by re-deriving it here — bmad-spec is its single writer; a hand-edit to `SPEC.md` from outside is unsupported and is overwritten on the next derive.
+
+Writes go through the shared script — `{project-root}/_bmad/scripts/memlog.py`, the same location as `resolve_customization.py` (atomic; never read it back except to resume):
+
+- `uv run {project-root}/_bmad/scripts/memlog.py init --workspace {spec-folder} --field topic="<what is being specced>"` — once, at create.
+- `uv run {project-root}/_bmad/scripts/memlog.py append --workspace {spec-folder} --type <decision|constraint|capability|assumption|question|direction|note|event> --text "<one-line gist, reason included>"` — as each lands.
+- Terminal moments (a validation verdict, "spec finalized") are `--type event` entries; the memlog carries no status field.
+
 ## The Operation
 
-Read the input and its ancillary linked materials. If there is no input, follow the no-input branch in **Workspace** (ask or block). If a prior `SPEC.md` exists at the target folder, read it too — the operation becomes an update. Preserve capability IDs; new capabilities get the next unused `CAP-N`; never reuse retired IDs. Otherwise this is a create.
+Read the input and its ancillary linked materials. If there is no input, follow the no-input branch in **Workspace** (ask or block). If a prior `.memlog.md` exists at the target folder, read it — the operation becomes an update, and the memlog (not the rendered `SPEC.md`) is the authority on what was decided and on capability IDs. Preserve those IDs; new capabilities get the next unused `CAP-N`; never reuse retired IDs. Otherwise this is a create, and the first move is `memlog.py init`.
 
 When the input is structured and pre-sorted (a PRD with an addendum, a GDD, a brief produced by an upstream BMad skill), trust the authored separation: lift kernel-fitting content into SPEC.md, lift overflow into appropriately-named companions. When the input is mixed (a brain dump, a transcript, an RFC, a customer email), do the sorting yourself: walk each claim, apply the three-lens load-bearing test (Spec Law rule 7), and route to the kernel field or a companion.
 
 Distill the input into the five-field kernel using `{workflow.spec_template}` as the skeleton. When input is rich, extract directly — no elicitation. When input is sparse, choose: **express** (best-effort distill, every gap becomes an `open_questions[]` entry) or **guided** (walk the five fields with the user one at a time). Headless defaults to express and logs the choice. Interactive asks.
 
+A recognized domain implication the input leaves unaddressed *is* such a gap — name it as an `open_questions[]` entry (healthcare input silent on PHI/HIPAA, payments silent on PCI, control systems silent on fail-safe) and move on. Flag it; never invent the answer or coach toward it. If these dominate, the input is too thin — suggest `bmad-prd`.
+
 Write lean from the first pass: every sentence must earn its place. Decoration costs tokens and dilutes downstream readers.
 
+Log each decision, capability, constraint, and accepted change to `.memlog.md` as it is made — that running record is what the render reads. Because the log is append-only, a later entry supersedes an earlier one on the same point while the history stays intact. When two currently-live sources or companions disagree on the same field, or an either/or never got resolved, surface it to the user rather than silently choosing — the resolution is itself a new memlog entry.
+
 If the input is genuinely too thin to distill (e.g. "an app for hikers" with no surrounding context), stop and suggest `bmad-prd` (or sibling ceremony skill). This skill distills; it does not coach.
 
 ## Load-bearing
@@ -94,7 +110,7 @@ Every spec must satisfy these eight rules. The operation aims for them; the self
 5. **Success signal is concrete enough to test or demonstrate against.** "Users love it" doesn't qualify.
 6. **Capability IDs are stable and unique.** Never reused, never renumbered.
 7. **Preservation.** Every load-bearing source claim lands in SPEC.md or a companion. Wrapper ceremony does not.
-8. **Lean prose.** Every sentence carries load-bearing content. Cut decoration, hedges, backstory, throat-clearing. Applies to SPEC.md, companions, and `.decision-log.md`.
+8. **Lean prose.** Every sentence carries load-bearing content. Cut decoration, hedges, backstory, throat-clearing. Applies to SPEC.md, companions, and `.memlog.md`.
 
 ## Self-Validate
 
@@ -104,7 +120,7 @@ After every create or update, sweep the resulting artifact in **two passes** bef
 
 **Pass 2 — Preservation.** Walk the source claim by claim. Confirm each load-bearing claim landed in SPEC.md or a companion. Wrapper-ceremony drops are logged under "Wrapper-only content" so the drop is on the record, not silent.
 
-Append a one-paragraph verdict to `.decision-log.md` covering both passes. In interactive mode, review the verdict with the user. In headless mode, `.decision-log.md` is one of the files returned, so the caller (or its downstream LLM) reads the verdict there.
+Record the verdict for each pass to `.memlog.md` (`append --type event`). In interactive mode, review it with the user. In headless mode, `.memlog.md` is one of the files returned, so the caller (or its downstream LLM) reads the verdict there.
 
 ## Spec with no change signal
 
@@ -120,10 +136,10 @@ Run `{workflow.on_complete}` if set.
 
 ## After Spec is Output
 
-Any update to spec regarding assumptions, open questions, or other changes should be appended to that source's decision log also and offer to update the source.
+Any update to the spec — resolved assumptions, answered open questions, other changes — is appended to `.memlog.md` as it happens. When a change overrides something that came from a source input, offer to update that source too, so upstream and the spec don't silently diverge.
 
 ## Frontmatter conventions
 
 - `companions:` array of `.md` files downstream MUST read alongside SPEC.md to have the full contract. Paths may point inside the spec folder (spec-authored companions like `glossary.md`) or outside it (adopted companions like `../planning-artifacts/ux-designs/ux-foo-bar-2026-05-23/DESIGN.md`). The split between spec-authored and adopted is implicit by path; downstream treats both the same.
 - `sources:` array of paths to files that were **fully absorbed** into the SPEC, with no remaining downstream value (e.g., a PRD whose every load-bearing claim is now in the kernel). Listed for audit and for bmad-spec to re-read on update. Downstream does NOT read these. Files that downstream still needs to read belong in `companions:`, not here.
-- **Do not list** decision logs, README files, organizational artifacts, or any operational record of how upstream skills produced their artifacts. Those are not source content; they are process metadata that downstream consumers don't need.
+- **Do not list** the memlog, README files, organizational artifacts, or any operational record of how upstream skills produced their artifacts. Those are not source content; they are process metadata that downstream consumers don't need.

package/src/core-skills/bmad-spec/assets/headless-schemas.md

@@ -1,6 +1,6 @@
 # Headless JSON Response
 
-The default invocation is headless: input goes in, JSON comes out. The contract is intentionally tiny — return the outcome and the files touched. Anything else a caller needs is inside those files (SPEC.md, companions, `.decision-log.md`).
+The default invocation is headless: input goes in, JSON comes out. The contract is intentionally tiny — return the outcome and the files touched. Anything else a caller needs is inside those files (SPEC.md, companions, `.memlog.md`).
 
 ## Success
 
@@ -10,12 +10,12 @@ The default invocation is headless: input goes in, JSON comes out. The contract
   "files": [
     "_bmad-output/specs/spec-quarter-drop/SPEC.md",
     "_bmad-output/specs/spec-quarter-drop/glossary.md",
-    "_bmad-output/specs/spec-quarter-drop/.decision-log.md"
+    "_bmad-output/specs/spec-quarter-drop/.memlog.md"
   ]
 }
 ```
 
-`files` lists every file written or modified in this run, in any order. The spec folder, kernel filename, decision log location, capabilities, companions, and verdict are all readable from those files; no need to re-encode them in the response.
+`files` lists every file written or modified in this run, in any order. The spec folder, kernel filename, memlog location, capabilities, companions, and verdict are all readable from those files; no need to re-encode them in the response.
 
 ## Blocked
 

package/src/core-skills/bmad-spec/assets/spec-template.md

@@ -1,7 +1,7 @@
 ---
 id: SPEC-{slug}
 companions: []     # files downstream MUST read alongside SPEC.md. Paths may point inside the spec folder (spec-authored) or outside it (adopted from an upstream skill).
-sources: []        # files fully absorbed into the SPEC (audit only; downstream does NOT read these). Never decision logs.
+sources: []        # files fully absorbed into the SPEC (audit only; downstream does NOT read these). Never the memlog.
 ---
 
 > **Canonical contract.** This SPEC and the files in `companions:` are the complete, preservation-validated contract for what to build, test, and validate. Source documents listed in frontmatter are for traceability only — consult them only if you need narrative rationale or prose color this contract intentionally omits.
@@ -20,9 +20,9 @@ Name which (or which combination) applies, who is affected, and the backdrop tha
 
 ## Capabilities
 
-- id: CAP-1
-  intent: {One sentence. "User or system can do X to achieve Y." WHAT, not HOW.}
-  success: {Testable or demonstrable criterion. Something a test or a real demonstration can decide.}
+- **CAP-1**
+  - **intent:** {One sentence. "User or system can do X to achieve Y." WHAT, not HOW.}
+  - **success:** {Testable or demonstrable criterion. Something a test or a real demonstration can decide.}
 
 ## Constraints
 

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

@@ -11,3 +11,4 @@ Core,bmad-review-adversarial-general,Adversarial Review,AR,"Use for quality assu
 Core,bmad-review-edge-case-hunter,Edge Case Hunter Review,ECH,Use alongside adversarial review for orthogonal coverage — method-driven not attitude-driven.,,[path],anytime,,,false,,
 Core,bmad-spec,Spec,SP,"Use to distill any intent input (brief, PRD, transcript, brain dump, design folder, mixed multi-source) into a succinct, no-fluff SPEC.md contract + companions that downstream work derives from. Locks the WHAT before the HOW. Works for software, game design, research, editorial, policy, business, anything intent-bearing. Validation mode also available.",,[path],anytime,,,false,{output_folder}/specs/spec-{slug},SPEC.md + companion files
 Core,bmad-customize,BMad Customize,BC,"Use when you want to change how an agent or workflow behaves — add persistent facts, swap templates, insert activation hooks, or customize menus. Scans what's customizable, picks the right scope (agent vs workflow), writes the override to _bmad/custom/, and verifies the merge. No TOML hand-authoring required.",,,anytime,,,false,{project-root}/_bmad/custom,TOML override files
+Core,bmad-forge-idea,Forge Idea,FI,"Use to pressure-test and harden an idea — software, business, creative, research, or life — until it proves out, hardens into something buildable, or dies cheaply. Persona-driven interrogation; optional handoff to bmad-spec or bmad-quick-dev.",,,anytime,,,false,{output_folder}/forge,refined-idea brief (optional)

package/src/{core-skills/bmad-brainstorming/scripts → scripts}/memlog.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 # /// script
-# requires-python = ">=3.10"
+# requires-python = ">=3.8"
 # ///
 """memlog — an append-only memory log: LLM-optimal working memory for a skill.
 
@@ -15,21 +15,31 @@ It is a FLAT log: there are no sections or grouping. Every entry is one line, re
 at the END in the order it happened. The chronology itself is the structure — an event
 like "started technique X" is just another entry, same as an idea or an insight.
 
-Two invariants make it trustworthy:
+Three invariants make it trustworthy:
 
   1. Append-only, chronological. Entries land at the end, in the order they happen.
-     Nothing is ever inserted backward, reordered, or grouped.
+     Nothing is ever inserted backward, reordered, edited, or removed. There is no
+     edit or delete subcommand by design; history is never rewritten.
   2. Write-only / blind. Every command is an atomic, context-free write and echoes the
-     new state as JSON, so the caller never re-reads the file mid-session. The one time
-     the file is read is on resume — and the caller reads it itself, not via this script.
+     new state as one line of JSON, so the caller never re-reads the file mid-session.
+     The one time the file is read is on resume — and the caller reads it itself, not
+     via this script.
+  3. No lifecycle status. A memory log has no "complete" flag. Whether the work is done,
+     blocked, or paused is itself a fact that happened, so it is recorded as an entry
+     (e.g. `append --type event --text "session complete"`), never as frontmatter the
+     log would have to mutate. The chronology stays the single source of truth, and a
+     resume learns the state by reading the last entries — the same way it learns
+     everything else.
+
+Atomicity: every write goes to a temp file, is flushed and fsync'd, then atomically
+renamed over the target, so a crash never leaves a half-written entry.
 
 The file shape (.memlog.md):
 
     ---
     topic: Onboarding flow for a budgeting app
     goal: lift week-1 retention
-    status: active
-    updated: 2026-05-30T14:22
+    updated: 2026-06-07T14:22
     ---
 
     - (note) user picked techniques: SCAMPER, then Six Thinking Hats
@@ -37,25 +47,27 @@ The file shape (.memlog.md):
     - (idea) skip the signup wall: let people try with sample data first
     - (idea) auto-import one bank account so the first screen shows real numbers
     - (question) is open-banking consent too heavy for step one?
-    - (technique) started Six Thinking Hats
-    - (idea) black-hat: imported transactions look scary before they're categorized
     - (insight) the "scary numbers" risk and the "real numbers" idea are one lever: show real data, pre-categorized
-    - (direction) user wants to optimize for the anxious first-timer, not the power user
+    - (direction) optimize for the anxious first-timer, not the power user
     - (decision) lead with one pre-categorized account; defer multi-account import
+    - (event) session complete
 
 Each entry may carry an optional `--type` — what KIND it is (idea, insight, question,
-decision, technique, …) — and an optional `--by` naming who it came from (e.g. `user`,
-`coach`), for sessions where authorship matters. Both render into one short inline tag:
-`(idea)`, `(idea by user)`, `(by coach)`. Omit them for a plain note. The host skill
-names the vocabulary; the script does not.
+decision, direction, assumption, gap, note, event, …) — and an optional `--by` naming
+who it came from (e.g. `user`, `coach`), for sessions where authorship matters. Both
+render into one short inline tag: `(idea)`, `(idea by user)`, `(by coach)`. Omit them
+for a plain note. The host skill names the vocabulary; the script does not enforce one.
 
 Commands:
-  init   --workspace DIR [--field k=v ...]              create the memlog (errors if it exists)
-  append --workspace DIR --text STR [--type T] [--by W]  append one entry at the end
-  set    --workspace DIR --key K --value V              set/replace a frontmatter field
+  init   (--workspace DIR | --path FILE) [--field k=v ...]    create the memlog (errors if it exists)
+  append (--workspace DIR | --path FILE) --text STR [--type T] [--by W]  append one entry at the end
+  set    (--workspace DIR | --path FILE) --key K --value V    set/replace a descriptive frontmatter field
 
-The workspace is the run folder; the memlog is always {workspace}/.memlog.md.
+Addressing: `--workspace` is the run folder, and the memlog is always {workspace}/.memlog.md.
+`--path` points straight at the memlog file instead, for callers that already hold the path.
 """
+from __future__ import annotations  # keep type-hint syntax lazy so the script runs on 3.8+
+
 import argparse
 import json
 import os
@@ -70,8 +82,9 @@ def now() -> str:
     return datetime.now().strftime("%Y-%m-%dT%H:%M")
 
 
-def memlog_path(workspace: str) -> Path:
-    return Path(workspace) / MEMLOG
+def resolve(args) -> Path:
+    """The memlog file, from either addressing mode: {workspace}/.memlog.md or an explicit --path."""
+    return Path(args.path) if args.path else Path(args.workspace) / MEMLOG
 
 
 def split(text: str) -> tuple[dict, str]:
@@ -107,8 +120,12 @@ def touch(meta: dict) -> None:
 
 
 def write_atomic(path: Path, text: str) -> None:
+    """Temp + flush + fsync + atomic rename, so a crash never half-writes an entry."""
     tmp = path.with_suffix(path.suffix + ".tmp")
-    tmp.write_text(text, encoding="utf-8")
+    with open(tmp, "w", encoding="utf-8") as f:
+        f.write(text)
+        f.flush()
+        os.fsync(f.fileno())
     os.replace(tmp, path)
 
 
@@ -116,18 +133,17 @@ def entry_count(body: str) -> int:
     return sum(1 for ln in body.splitlines() if ln.startswith("- "))
 
 
-def ack(path: Path, meta: dict, body: str) -> None:
+def ack(path: Path, body: str) -> None:
     """Echo new state so the caller never re-reads the file to know where it stands."""
     print(json.dumps({
         "ok": True,
         "memlog": str(path),
-        "status": meta.get("status", ""),
         "entries": entry_count(body),
     }))
 
 
 def cmd_init(args) -> int:
-    path = memlog_path(args.workspace)
+    path = resolve(args)
     if path.exists():
         print(f"error: {path} already exists; use append/set to update it", file=sys.stderr)
         return 2
@@ -139,15 +155,14 @@ def cmd_init(args) -> int:
             return 2
         k, v = pair.split("=", 1)
         meta[k.strip()] = v.strip()
-    meta.setdefault("status", "active")
     touch(meta)
     write_atomic(path, render(meta, ""))
-    ack(path, meta, "")
+    ack(path, "")
     return 0
 
 
 def cmd_append(args) -> int:
-    path = memlog_path(args.workspace)
+    path = resolve(args)
     meta, body = split(path.read_text(encoding="utf-8"))
     text = " ".join(args.text.split())  # collapse newlines/runs → one-line entry, no prose bloat
     label = args.type or ""
@@ -158,38 +173,45 @@ def cmd_append(args) -> int:
     body = (body.rstrip("\n") + "\n" + entry) if body.strip() else entry  # always at the end
     touch(meta)
     write_atomic(path, render(meta, body))
-    ack(path, meta, body)
+    ack(path, body)
     return 0
 
 
 def cmd_set(args) -> int:
-    path = memlog_path(args.workspace)
+    path = resolve(args)
     meta, body = split(path.read_text(encoding="utf-8"))
     meta[args.key] = args.value
     touch(meta)
     write_atomic(path, render(meta, body))
-    ack(path, meta, body)
+    ack(path, body)
     return 0
 
 
+def add_target(sp) -> None:
+    """Every command addresses the memlog the same way: a run folder or an explicit path."""
+    g = sp.add_mutually_exclusive_group(required=True)
+    g.add_argument("--workspace", help="run folder; the memlog is {workspace}/.memlog.md")
+    g.add_argument("--path", help="explicit memlog file path (alternative to --workspace)")
+
+
 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)
 
     pi = sub.add_parser("init", help="create the memlog")
-    pi.add_argument("--workspace", required=True)
+    add_target(pi)
     pi.add_argument("--field", action="append", metavar="KEY=VALUE", help="frontmatter field (repeatable)")
     pi.set_defaults(func=cmd_init)
 
     pa = sub.add_parser("append", help="append one entry at the end")
-    pa.add_argument("--workspace", required=True)
+    add_target(pa)
     pa.add_argument("--text", required=True)
     pa.add_argument("--type", help="entry kind, rendered as an inline tag")
     pa.add_argument("--by", help="who the entry came from (e.g. user, coach); rendered into the tag")
     pa.set_defaults(func=cmd_append)
 
-    pset = sub.add_parser("set", help="set a frontmatter field")
-    pset.add_argument("--workspace", required=True)
+    pset = sub.add_parser("set", help="set a descriptive frontmatter field")
+    add_target(pset)
     pset.add_argument("--key", required=True)
     pset.add_argument("--value", required=True)
     pset.set_defaults(func=cmd_set)

package/src/scripts/resolve_config.py

@@ -10,12 +10,14 @@ Reads from four layers (highest priority last):
 
 Outputs merged JSON to stdout. Errors go to stderr.
 
-Requires Python 3.11+ (uses stdlib `tomllib`). No `uv`, no `pip install`,
-no virtualenv — plain `python3` is sufficient.
-
-  python3 resolve_config.py --project-root /abs/path/to/project
-  python3 resolve_config.py --project-root ... --key core
-  python3 resolve_config.py --project-root ... --key agents
+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_config.py --project-root /abs/path/to/project
+  uv run resolve_config.py --project-root ... --key core
+  uv run resolve_config.py --project-root ... --key agents
 
 Merge rules (same as resolve_customization.py):
   - Scalars: override wins

package/src/scripts/resolve_customization.py

@@ -11,12 +11,14 @@ Skill name is derived from the basename of the skill directory.
 
 Outputs merged JSON to stdout. Errors go to stderr.
 
-Requires Python 3.11+ (uses stdlib `tomllib`). No `uv`, no `pip install`,
-no virtualenv — plain `python3` is sufficient.
-
-  python3 resolve_customization.py --skill /abs/path/to/skill-dir
-  python3 resolve_customization.py --skill ... --key agent
-  python3 resolve_customization.py --skill ... --key agent.menu
+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