ma-agents 3.17.1 → 3.18.0-beta.2

package/docs/architecture.md

@@ -213,6 +213,17 @@ The registry has stayed **YAML** throughout — only its path has moved. (`tools
 
 > **Maintenance note:** because the registry path has now moved twice (YAML→YAML→YAML at three locations), the cache builder fails loud — if the resolved `type: bmad-org` set is smaller than the known bundled set, or no module source is found, it exits non-zero rather than producing a thin/empty cache, so a future BMAD registry move surfaces at build time, not as a broken air-gapped install.
 
+#### 3.6.1 Air-gap posture with a Confluence-backed knowledge store (NFR80)
+
+F26 lets each of the two knowledge stores choose a `backend` of `file-system` or `confluence`, which changes what "offline" means for a project — so the posture is stated exactly here rather than left to be inferred from the paragraph above:
+
+- **Installation and skill loading require no network at all**, unchanged. Neither reads a knowledge store: the installer writes the binding and generates `_bmad/bmm/config.yaml` from it, and both are local files.
+- **Every `file-system`-backed workflow requires no network at all**, unchanged. The backend gate embedded in the skills that resolve knowledge-store artifacts reads `{system,software}_requirements_backend` out of the generated `config.yaml` — a local read — and on `file-system` proceeds exactly as it did before, consulting nothing.
+- **A `confluence`-backed store additionally requires its Confluence host to be reachable from the machine running the agent.** That is not the same as requiring internet egress: an intra-perimeter Confluence Server or Data Center on an air-gapped network satisfies it. It does require a Confluence-capable MCP server configured in the agent; with none, the affected skill halts loudly and does not degrade to local files (FR262). There is no local mirror, no cache and therefore no sync (P5-9.6).
+- **A project that must operate with no network whatsoever keeps both stores `file-system`-backed.** That is the default, and it is what `--yes` always selects.
+
+Proven rather than asserted: `test/project-layout-confluence-routing.test.js` runs the whole binding-and-generation flow in a child process whose `dns`, `net`, `http`, `https`, `tls` and `fetch` primitives are poisoned, verifies that the block actually armed, and requires the flow to complete having attempted no egress at all.
+
 ## 4. Data Flow
 
 ### 4.1 Install Flow

package/docs/technical-notes/enforcement-hooks-research.md

@@ -294,11 +294,20 @@ All 11 BMAD agents have enforcement via `critical_actions` in `.customize.yaml`
 **Mechanism:**
 ```yaml
 critical_actions:
-  1: "Read the skills MANIFEST at {project-root}/_bmad/skills/MANIFEST.yaml"
+  1: "Read the skills MANIFEST at {project-root}/_bmad/skills/<agent-slug>/MANIFEST.yaml if it exists"
   2: "For each skill marked always_load: true, read the skill file completely"
   3: "Follow all skill directives during this session"
 ```
 
+> **Note (2026-09-12):** this snippet previously showed a bare
+> `{project-root}/_bmad/skills/MANIFEST.yaml`. That path is not what Story 8.3
+> specified — the manifest is per-agent-host, at
+> `{project-root}/_bmad/skills/<agent-slug>/MANIFEST.yaml`, where `<agent-slug>`
+> matches the `skillsDir` in `lib/agents.js` (`sre`, `devops`, `cyber`, `sqa`).
+> The bare form leaked from here into `ma-agent-sqa`'s Critical Actions block and
+> survived there until it was corrected. Keep the slug segment in any copy of this
+> snippet.
+
 **Deployment:** Extension module at `_bmad/extensions/ma-agents-skills/` deployed during BMAD customization pipeline (Stage 3 in `bmad.js`).
 
 **Coverage:**

package/lib/agents.js

@@ -242,8 +242,27 @@ const agents = [
     version: '1.0.0',
     category: 'ide',
     description: 'Google Deepmind Antigravity Agent',
-    skillsDir: '.antigravity/skills',
-    getProjectPath: () => path.join(process.cwd(), '.antigravity', 'skills'),
+    // Bug `antigravity-path-divergence`: this used to read `.antigravity/skills`,
+    // a path ma-agents invented from its own per-tool naming convention. Upstream
+    // bmad-method maps the SAME tool to `.agent/skills`
+    // (node_modules/bmad-method/tools/installer/ide/platform-codes.yaml, platform
+    // `antigravity`, in a file whose header records the paths as "verified against
+    // each tool's primary docs"; its global counterpart `~/.gemini/antigravity/skills`
+    // shows the entry was researched rather than guessed). Because ma-agents
+    // delegates part of the install to that installer, a single run produced TWO
+    // trees — and `.agent/skills`, the one Antigravity actually reads, was named by
+    // neither this registry nor lib/bmad.js, so every ma-agents post-deploy patch
+    // (the on-prem phase prefix among them) silently skipped it. Measured in a real
+    // on-prem project: .claude/.agents/.cline each carried the prefix on 6 personas,
+    // .agent/skills on 0.
+    // Upstream is the authority on which directory a tool reads, so we align —
+    // exactly as copilot/roo-code/kilocode were aligned to `.agents/skills` when
+    // bmad-method 6.5.0 moved them (see the copilot entry above). This is a
+    // per-tool decision on per-tool evidence: the other three divergences in the
+    // table are recorded in PLATFORM_PATH_DIVERGENCES below, deliberately unchanged.
+    // Existing installs migrate via OBSOLETE_TOOL_SKILL_DIRS in lib/installer.js.
+    skillsDir: '.agent/skills',
+    getProjectPath: () => path.join(process.cwd(), '.agent', 'skills'),
     getGlobalPath: () => {
       const platform = os.platform();
       if (platform === 'win32') {
@@ -356,6 +375,64 @@ const agents = [
   // Add them here in a dedicated future story if/when demand appears.
 ];
 
+/**
+ * Declared, deliberate divergences between this registry's project `skillsDir`
+ * and bmad-method's `installer.target_dir` for the SAME tool
+ * (`node_modules/bmad-method/tools/installer/ide/platform-codes.yaml`).
+ * Keyed by bmad platform code (see `getBmadPlatformCode`).
+ *
+ * Why this exists (bug `antigravity-path-divergence`): the two tables had drifted
+ * apart for four tools and nothing compared them outside the five flagships, so a
+ * whole second skill tree appeared in real projects with no owner and no patcher.
+ * `test/routing-parity.test.js` (section 5) now enumerates EVERY tool in BOTH
+ * tables and fails on any divergence that is not declared here — and on any
+ * declaration whose recorded paths have gone stale, so an entry cannot rot into
+ * cover for a different divergence.
+ *
+ * Scope note — PROJECT paths only. `getGlobalPath()` follows a per-OS
+ * application-data convention that differs from upstream's `global_target_dir`
+ * for EVERY tool, claude-code included (`%APPDATA%/Claude/skills` vs
+ * `~/.claude/skills`). That is a whole-table convention difference, not a
+ * per-tool divergence, and is deliberately out of scope here.
+ *
+ * To add an entry you must record BOTH live paths and a real reason. To remove
+ * one, align the paths — the test fails on a declaration whose paths now agree.
+ */
+const PLATFORM_PATH_DIVERGENCES = Object.freeze({
+  gemini: Object.freeze({
+    maSkillsDir: '.gemini/skills',
+    bmadTargetDir: '.agents/skills',
+    reason:
+      "Upstream's `gemini` platform is the Gemini CLI, which reads the shared " +
+      '`.agents/skills` tree; this registry entry targets Google Gemini Code Assist ' +
+      '(the IDE extension — note its instruction file `.gemini/gemini.md`), a ' +
+      'different product sharing the same code. Contained: upstream writes ' +
+      '`.agents/skills`, which is already an IDE skillsDir in this registry, already ' +
+      'a seed in lib/bmad.js TOOL_SKILL_DIRS, and already reconciled by bug 27.16 — ' +
+      'so no tree goes unpatched. Realigning is a compatibility call for its own story.'
+  }),
+  cursor: Object.freeze({
+    maSkillsDir: '.cursor/skills',
+    bmadTargetDir: '.agents/skills',
+    reason:
+      'Cursor reads its own `.cursor/` workspace directory (this registry also stamps ' +
+      '`.cursor/cursor.md` there); upstream routes it to the shared `.agents/skills` ' +
+      'cross-tool tree instead. Contained for the same reason as `gemini`: upstream ' +
+      "'s target is already a known, patched and reconciled tree. Kept deliberately " +
+      'so this bug fix changes the write path of exactly one tool, on that tool’s evidence.'
+  }),
+  opencode: Object.freeze({
+    maSkillsDir: '.opencode/skills',
+    bmadTargetDir: '.agents/skills',
+    reason:
+      'OpenCode is wired here through `opencode.json::instructions[]` plus AGENTS.md ' +
+      '(Story 21.4) against its own `.opencode/` tree; upstream routes it to the shared ' +
+      '`.agents/skills`. Contained for the same reason as `gemini` and `cursor`: ' +
+      "upstream's target is already a known, patched and reconciled tree. Realignment " +
+      'would also have to move the instruction wiring, so it belongs in its own story.'
+  })
+});
+
 function getAgent(agentId) {
   return agents.find(a => a.id === agentId);
 }
@@ -383,5 +460,6 @@ module.exports = {
   getAgent,
   getAllAgents,
   getAgentsByCategory,
-  getBmadPlatformCode
+  getBmadPlatformCode,
+  PLATFORM_PATH_DIVERGENCES
 };

package/lib/bmad-extension/skills/add-sprint/SKILL.md

@@ -11,6 +11,118 @@ triggers:
 
 Guided workflow to create a new sprint entry in the `sprints` section of `sprint-status.yaml` with capacity limits, optional ISO dates, and auto-incremented sprint ID.
 
+## Knowledge Store Binding Preflight
+
+**Gateway check — run this before anything else in this skill.** Before any read, any write, any user prompt, and before any other routing or configuration step below. No other step of this skill executes until this preflight returns PROCEED.
+
+`_bmad/bmm/config.yaml` is a GENERATED file. `ma-agents` derives it from the committed binding in `_bmad-output/project-layout.yaml` on install and on `ma-agents bind`, and records which binding it was generated from in its `project_layout_stamp:` field. If the binding has moved since — the usual cause is a `git pull` that relocated a knowledge store — every path this skill would resolve from `config.yaml` points at where the stores used to be. This preflight refuses to let that happen silently.
+
+**This preflight is read-only.** Whatever it finds, do NOT regenerate, repair, edit or create `config.yaml`, `_bmad-output/project-layout.yaml`, or any other file, and do not offer to. Regenerating the config belongs to the installer and to `ma-agents bind`, never to a skill.
+
+**Compare content, never timestamps.** Never decide staleness from file modification times: mtime ordering is not preserved by `git pull`, `git checkout` or a fresh clone, so it both misses real drift and reports drift on a clean checkout.
+
+Work through the steps below IN ORDER and stop at the first branch that matches. The order is load-bearing — `_bmad-output/project-layout.yaml` is the fact, and the stamp only ever corroborates it.
+
+### Step P1 — Read `_bmad-output/project-layout.yaml`
+
+- **Missing, or present but blank / comments-only** → go to **Step P2**.
+- **Present but not cleanly readable** — it is not valid YAML, it carries unresolved merge-conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`), it yields no readable fields, its `schema_version:` is greater than `2`, its `schema_version:` is present but is not a number, it names a `backend:` or a `mode:` this build does not recognise, or any store record in it cannot be read → **HALT** and report:
+
+  > **ma-agents — stopping: the committed knowledge binding cannot be read.**
+  > `_bmad-output/project-layout.yaml` exists but this build cannot use it: {say exactly what is wrong}.
+  > Every knowledge-store path in `_bmad/bmm/config.yaml` is derived from that file, so nothing this skill would resolve can be trusted. Fix the binding by hand — if this is a merge conflict, resolve it; the file is committed, so conflicts are ordinary — then run `ma-agents bind` to regenerate `_bmad/bmm/config.yaml` from it.
+  > Nothing has been read or written on your behalf. Stopping rather than guessing.
+
+  That list of faults is illustrative, not exhaustive. **Default-deny:** the only two ways out of this step without halting are "absent, or blank / comments-only" (→ Step P2) and "resolves cleanly" (→ Step P3). Anything else takes this HALT, including a fault not named above. Do not fall back to defaults and do not treat this as "no binding". A binding that cannot be read is a different fact from a project that has none.
+- **Present and resolves cleanly** → go to **Step P3**.
+
+### Step P2 — There is no committed binding
+
+No `_bmad-output/project-layout.yaml`. That is the pre-F26 shape and by itself it is NOT drift — but corroborate it instead of trusting it, because "a binding was never written here" and "the binding was deleted, ignored, or not pulled" look identical from the missing file alone. Read `_bmad/bmm/config.yaml`:
+
+- **`config.yaml` does not exist either** → **HALT** and report:
+
+  > **ma-agents — stopping: this project is not configured.**
+  > Neither `_bmad-output/project-layout.yaml` nor `_bmad/bmm/config.yaml` exists, so nothing states where this project's knowledge stores live. Run `npx ma-agents install` to configure the project, or `ma-agents bind` if ma-agents is already installed and only the binding is missing.
+  > Nothing has been read or written on your behalf. Stopping rather than guessing.
+
+- **`config.yaml` exists and carries, at column 0, any of `project_layout_stamp:`, `system_requirements_path:` or `software_requirements_path:`** (a commented-out or indented one does not count — it is not the field) → **HALT** and report:
+
+  > **ma-agents — stopping: the committed knowledge binding is missing.**
+  > `_bmad/bmm/config.yaml` carries {name the fields you found}, which only an F26 generation writes — so this project HAS been bound — but `_bmad-output/project-layout.yaml` is not here. The binding was deleted, is untracked or ignored, or has not been pulled. This is not a pre-F26 project, so proceeding would mean trusting generated paths against a binding that no longer exists.
+  > Restore the file (for example `git checkout -- _bmad-output/project-layout.yaml`), or run `ma-agents bind` to write a fresh one.
+  > Nothing has been read or written on your behalf. Stopping rather than guessing.
+
+  Those three fields are the discriminator and they are reliable: a genuine pre-F26 `config.yaml` carries none of them. Do not skip this check. An absent stamp on its own is never evidence that a project predates the stamp.
+
+- **`config.yaml` exists and carries none of those three fields at column 0** → this is genuinely a pre-F26 project. **PROCEED** with the rest of this skill exactly as it behaved before F26, and say nothing at all about the binding — no warning, no prompt, no offer to bind. Nothing has moved, so there is nothing to re-bind. The existence of `config.yaml` is NOT on its own a reason to take this branch: all three fields must be absent.
+
+### Step P3 — The binding is readable: check what `config.yaml` was generated from
+
+Read `_bmad/bmm/config.yaml`.
+
+- **`config.yaml` does not exist** → **HALT** and report:
+
+  > **ma-agents — stopping: the generated config is missing.**
+  > `_bmad-output/project-layout.yaml` commits this project's knowledge binding, but `_bmad/bmm/config.yaml` — the file this skill resolves its paths from — has never been generated from it. Run `npx ma-agents install` to install into this project, or `ma-agents bind` if ma-agents is already installed, to generate `_bmad/bmm/config.yaml` from the committed binding.
+  > Nothing has been read or written on your behalf. Stopping rather than guessing.
+
+- **No `project_layout_stamp:` line at column 0 of `config.yaml`** (a commented-out or indented one does not count — it is not the field) → **HALT** and report:
+
+  > **ma-agents — stopping: `_bmad/bmm/config.yaml` does not record which binding it came from.**
+  > `_bmad-output/project-layout.yaml` exists, but `config.yaml` carries no `project_layout_stamp:`, so there is no evidence its paths were generated from the committed binding. Run `ma-agents bind` to regenerate it.
+  > Nothing has been read or written on your behalf. Stopping rather than guessing.
+
+- **`project_layout_stamp:` is present but its value is not `sha256:` followed by exactly 64 lowercase hexadecimal characters** — truncated, uppercased, a different algorithm, unbalanced quotes, or trailing content after the digest → **HALT** and report:
+
+  > **ma-agents — stopping: `_bmad/bmm/config.yaml` claims to have been generated and the claim cannot be read.**
+  > Its `project_layout_stamp:` is {quote the value you found}, which is not a stamp ma-agents wrote (expected `sha256:` followed by 64 lowercase hex characters) — merge damage, a hand-edit, or a truncated write. Treat this config as unverified; it is NOT a config that predates the stamp. Run `ma-agents bind` to regenerate it from `_bmad-output/project-layout.yaml`.
+  > Nothing has been read or written on your behalf. Stopping rather than guessing.
+
+- **`project_layout_stamp:` is well-formed** → go to **Step P4**.
+
+### Step P4 — Compare the committed binding against the generated fields
+
+Derive, from `_bmad-output/project-layout.yaml`, what each generated field in `config.yaml` WOULD be if it were regenerated right now, and compare it to what `config.yaml` actually carries. This is a content comparison of the two files — never a timestamp comparison.
+
+A schema-2 binding holds three records: `system_requirements_store:`, `software_requirements_store:` and `sprint_management:`. A legacy schema-1 binding holds a single `knowledgebase:` record, which stands for BOTH requirement stores.
+
+The table below IS the whole comparison: every field named in its right-hand column is compared, and no field outside that column is. Read each field only from a line at column 0, and compare VALUES rather than bytes — the generator quotes its scalars (`sprint_backend: "jira"`, `knowledgebase_path: "."`), so strip one balanced pair of surrounding quotes from each side first.
+
+| When | Binding record it is derived from | Field(s) it generates in `config.yaml` |
+| --- | --- | --- |
+| always | `software_requirements_store` → its `path:` (a store whose `backend:` is not `file-system` has no `path:` at all, and so generates `.`); the artifacts field is that same path, except that a path of `.` gives `{project-root}/_bmad-output/planning-artifacts`; its resolved `backend:` (an absent or empty `backend:` resolves to `file-system`), and, when that backend is `confluence`, its `space_key:` — the generated space-key field is empty for every other backend, so a store re-bound away from Confluence does not keep the old space | `software_requirements_path:`, `knowledgebase_path:`, `planning_artifacts:`, `software_requirements_backend:`, `software_requirements_space_key:` |
+| always | `system_requirements_store` → its `path:` (a store whose `backend:` is not `file-system` has no `path:` at all, and so generates `.`); its resolved `backend:` (an absent or empty `backend:` resolves to `file-system`), and, when that backend is `confluence`, its `space_key:` — the generated space-key field is empty for every other backend, so a store re-bound away from Confluence does not keep the old space | `system_requirements_path:`, `system_requirements_backend:`, `system_requirements_space_key:` |
+| `sprint_management` has `mode: jira` | `sprint_management` → its `jira_url:` and `jira_project_key:`; the backend field is the literal `jira`; the artifacts field is always `{project-root}/_bmad-output/implementation-artifacts`, because a Jira sprint store has no path | `sprint_backend:`, `jira_url:`, `jira_project_key:`, `implementation_artifacts:` |
+| `sprint_management` has any other mode | `sprint_management` → its `path:`; the backend field is the literal `file-system`; the artifacts field is that same path, except that a path of `.` gives `{project-root}/_bmad-output/implementation-artifacts` | `sprint_backend:`, `sprint_management_path:`, `implementation_artifacts:` |
+
+**When the binding says `mode: jira`, `sprint_management_path:` is not compared at all.** The generator writes no `sprint_management_path:` in that mode — and it never DELETES a field, it only updates or appends one. So a project that was bound to the file system and later re-bound to Jira still carries its old `sprint_management_path:` line in a freshly generated `config.yaml`. That leftover line is not drift, and comparing it would halt every Jira project that was ever file-system-bound.
+
+Not every field in that table is a path. Where a store's `backend:` or `space_key:` is what disagrees, the comparison is the same and so is the halt — read the message template's `{path in …}` placeholders as "the value that disagrees", and name the two values you actually compared.
+
+**Any disagreement is drift** → **HALT** and report, naming every store that moved and both of its paths:
+
+> **ma-agents — stopping: `_bmad/bmm/config.yaml` is stale.**
+> The committed binding in `_bmad-output/project-layout.yaml` no longer matches the state `_bmad/bmm/config.yaml` was generated from:
+> - {store name}: was `{path in config.yaml}`, is now `{path in project-layout.yaml}`
+> (one line per store that moved)
+> Running this skill now would read and write artifacts where those stores used to be. Run `ma-agents bind` to regenerate `_bmad/bmm/config.yaml` from the committed binding, then run this skill again.
+> Nothing has been read or written on your behalf. Stopping rather than guessing.
+
+**If everything in the table agrees** → go to **Step P5**.
+
+The stamp covers binding state that `config.yaml` does not carry — a Confluence `root_page:`, a `gitUrl:` — so the table alone cannot see every kind of move. If, and only if, a command shell is available to you and `ma-agents` resolves as a local dependency of this project, you may confirm the comparison exactly, without parsing the stamp yourself:
+
+```bash
+node -e "const c=require('ma-agents/bin/cli.js'),f=require('fs'),p=process.cwd();const t=c.resolveProjectTopology(p);if(!t.ok){console.log('binding:'+t.reason)}else{const s=c.readProjectLayoutStamp(f.readFileSync('_bmad/bmm/config.yaml','utf8'));console.log(s.ok?(s.value===c.computeProjectLayoutStamp(t.topology,p)?'MATCH':'DRIFT'):'stamp:'+s.reason)}"
+```
+
+`DRIFT` is authoritative: HALT with the stale-config message above even when the table found nothing, and say that the binding changed in a way `config.yaml` does not record. Never treat a failure to run this command as a result — if it does not run, the table is the check, and you say nothing about the stamp.
+
+### Step P5 — PROCEED
+
+The generated config matches the committed binding. Say NOTHING about the binding, the stamp or this preflight — a matched project gets no message — and continue with the rest of this skill.
+
 ## Backend Routing
 
 Before executing any file-system operations, determine and route to the correct backend:

package/lib/bmad-extension/skills/add-to-sprint/SKILL.md

@@ -13,6 +13,118 @@ Guided workflow to move backlog items to a sprint in the unified `sprint-status.
 
 **Movement semantics:** Each item exists in exactly one location — either the `backlog` array OR a sprint's `items` array, never both. This skill atomically removes items from `backlog` and appends them to the target sprint's `items` array in a single file write.
 
+## Knowledge Store Binding Preflight
+
+**Gateway check — run this before anything else in this skill.** Before any read, any write, any user prompt, and before any other routing or configuration step below. No other step of this skill executes until this preflight returns PROCEED.
+
+`_bmad/bmm/config.yaml` is a GENERATED file. `ma-agents` derives it from the committed binding in `_bmad-output/project-layout.yaml` on install and on `ma-agents bind`, and records which binding it was generated from in its `project_layout_stamp:` field. If the binding has moved since — the usual cause is a `git pull` that relocated a knowledge store — every path this skill would resolve from `config.yaml` points at where the stores used to be. This preflight refuses to let that happen silently.
+
+**This preflight is read-only.** Whatever it finds, do NOT regenerate, repair, edit or create `config.yaml`, `_bmad-output/project-layout.yaml`, or any other file, and do not offer to. Regenerating the config belongs to the installer and to `ma-agents bind`, never to a skill.
+
+**Compare content, never timestamps.** Never decide staleness from file modification times: mtime ordering is not preserved by `git pull`, `git checkout` or a fresh clone, so it both misses real drift and reports drift on a clean checkout.
+
+Work through the steps below IN ORDER and stop at the first branch that matches. The order is load-bearing — `_bmad-output/project-layout.yaml` is the fact, and the stamp only ever corroborates it.
+
+### Step P1 — Read `_bmad-output/project-layout.yaml`
+
+- **Missing, or present but blank / comments-only** → go to **Step P2**.
+- **Present but not cleanly readable** — it is not valid YAML, it carries unresolved merge-conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`), it yields no readable fields, its `schema_version:` is greater than `2`, its `schema_version:` is present but is not a number, it names a `backend:` or a `mode:` this build does not recognise, or any store record in it cannot be read → **HALT** and report:
+
+  > **ma-agents — stopping: the committed knowledge binding cannot be read.**
+  > `_bmad-output/project-layout.yaml` exists but this build cannot use it: {say exactly what is wrong}.
+  > Every knowledge-store path in `_bmad/bmm/config.yaml` is derived from that file, so nothing this skill would resolve can be trusted. Fix the binding by hand — if this is a merge conflict, resolve it; the file is committed, so conflicts are ordinary — then run `ma-agents bind` to regenerate `_bmad/bmm/config.yaml` from it.
+  > Nothing has been read or written on your behalf. Stopping rather than guessing.
+
+  That list of faults is illustrative, not exhaustive. **Default-deny:** the only two ways out of this step without halting are "absent, or blank / comments-only" (→ Step P2) and "resolves cleanly" (→ Step P3). Anything else takes this HALT, including a fault not named above. Do not fall back to defaults and do not treat this as "no binding". A binding that cannot be read is a different fact from a project that has none.
+- **Present and resolves cleanly** → go to **Step P3**.
+
+### Step P2 — There is no committed binding
+
+No `_bmad-output/project-layout.yaml`. That is the pre-F26 shape and by itself it is NOT drift — but corroborate it instead of trusting it, because "a binding was never written here" and "the binding was deleted, ignored, or not pulled" look identical from the missing file alone. Read `_bmad/bmm/config.yaml`:
+
+- **`config.yaml` does not exist either** → **HALT** and report:
+
+  > **ma-agents — stopping: this project is not configured.**
+  > Neither `_bmad-output/project-layout.yaml` nor `_bmad/bmm/config.yaml` exists, so nothing states where this project's knowledge stores live. Run `npx ma-agents install` to configure the project, or `ma-agents bind` if ma-agents is already installed and only the binding is missing.
+  > Nothing has been read or written on your behalf. Stopping rather than guessing.
+
+- **`config.yaml` exists and carries, at column 0, any of `project_layout_stamp:`, `system_requirements_path:` or `software_requirements_path:`** (a commented-out or indented one does not count — it is not the field) → **HALT** and report:
+
+  > **ma-agents — stopping: the committed knowledge binding is missing.**
+  > `_bmad/bmm/config.yaml` carries {name the fields you found}, which only an F26 generation writes — so this project HAS been bound — but `_bmad-output/project-layout.yaml` is not here. The binding was deleted, is untracked or ignored, or has not been pulled. This is not a pre-F26 project, so proceeding would mean trusting generated paths against a binding that no longer exists.
+  > Restore the file (for example `git checkout -- _bmad-output/project-layout.yaml`), or run `ma-agents bind` to write a fresh one.
+  > Nothing has been read or written on your behalf. Stopping rather than guessing.
+
+  Those three fields are the discriminator and they are reliable: a genuine pre-F26 `config.yaml` carries none of them. Do not skip this check. An absent stamp on its own is never evidence that a project predates the stamp.
+
+- **`config.yaml` exists and carries none of those three fields at column 0** → this is genuinely a pre-F26 project. **PROCEED** with the rest of this skill exactly as it behaved before F26, and say nothing at all about the binding — no warning, no prompt, no offer to bind. Nothing has moved, so there is nothing to re-bind. The existence of `config.yaml` is NOT on its own a reason to take this branch: all three fields must be absent.
+
+### Step P3 — The binding is readable: check what `config.yaml` was generated from
+
+Read `_bmad/bmm/config.yaml`.
+
+- **`config.yaml` does not exist** → **HALT** and report:
+
+  > **ma-agents — stopping: the generated config is missing.**
+  > `_bmad-output/project-layout.yaml` commits this project's knowledge binding, but `_bmad/bmm/config.yaml` — the file this skill resolves its paths from — has never been generated from it. Run `npx ma-agents install` to install into this project, or `ma-agents bind` if ma-agents is already installed, to generate `_bmad/bmm/config.yaml` from the committed binding.
+  > Nothing has been read or written on your behalf. Stopping rather than guessing.
+
+- **No `project_layout_stamp:` line at column 0 of `config.yaml`** (a commented-out or indented one does not count — it is not the field) → **HALT** and report:
+
+  > **ma-agents — stopping: `_bmad/bmm/config.yaml` does not record which binding it came from.**
+  > `_bmad-output/project-layout.yaml` exists, but `config.yaml` carries no `project_layout_stamp:`, so there is no evidence its paths were generated from the committed binding. Run `ma-agents bind` to regenerate it.
+  > Nothing has been read or written on your behalf. Stopping rather than guessing.
+
+- **`project_layout_stamp:` is present but its value is not `sha256:` followed by exactly 64 lowercase hexadecimal characters** — truncated, uppercased, a different algorithm, unbalanced quotes, or trailing content after the digest → **HALT** and report:
+
+  > **ma-agents — stopping: `_bmad/bmm/config.yaml` claims to have been generated and the claim cannot be read.**
+  > Its `project_layout_stamp:` is {quote the value you found}, which is not a stamp ma-agents wrote (expected `sha256:` followed by 64 lowercase hex characters) — merge damage, a hand-edit, or a truncated write. Treat this config as unverified; it is NOT a config that predates the stamp. Run `ma-agents bind` to regenerate it from `_bmad-output/project-layout.yaml`.
+  > Nothing has been read or written on your behalf. Stopping rather than guessing.
+
+- **`project_layout_stamp:` is well-formed** → go to **Step P4**.
+
+### Step P4 — Compare the committed binding against the generated fields
+
+Derive, from `_bmad-output/project-layout.yaml`, what each generated field in `config.yaml` WOULD be if it were regenerated right now, and compare it to what `config.yaml` actually carries. This is a content comparison of the two files — never a timestamp comparison.
+
+A schema-2 binding holds three records: `system_requirements_store:`, `software_requirements_store:` and `sprint_management:`. A legacy schema-1 binding holds a single `knowledgebase:` record, which stands for BOTH requirement stores.
+
+The table below IS the whole comparison: every field named in its right-hand column is compared, and no field outside that column is. Read each field only from a line at column 0, and compare VALUES rather than bytes — the generator quotes its scalars (`sprint_backend: "jira"`, `knowledgebase_path: "."`), so strip one balanced pair of surrounding quotes from each side first.
+
+| When | Binding record it is derived from | Field(s) it generates in `config.yaml` |
+| --- | --- | --- |
+| always | `software_requirements_store` → its `path:` (a store whose `backend:` is not `file-system` has no `path:` at all, and so generates `.`); the artifacts field is that same path, except that a path of `.` gives `{project-root}/_bmad-output/planning-artifacts`; its resolved `backend:` (an absent or empty `backend:` resolves to `file-system`), and, when that backend is `confluence`, its `space_key:` — the generated space-key field is empty for every other backend, so a store re-bound away from Confluence does not keep the old space | `software_requirements_path:`, `knowledgebase_path:`, `planning_artifacts:`, `software_requirements_backend:`, `software_requirements_space_key:` |
+| always | `system_requirements_store` → its `path:` (a store whose `backend:` is not `file-system` has no `path:` at all, and so generates `.`); its resolved `backend:` (an absent or empty `backend:` resolves to `file-system`), and, when that backend is `confluence`, its `space_key:` — the generated space-key field is empty for every other backend, so a store re-bound away from Confluence does not keep the old space | `system_requirements_path:`, `system_requirements_backend:`, `system_requirements_space_key:` |
+| `sprint_management` has `mode: jira` | `sprint_management` → its `jira_url:` and `jira_project_key:`; the backend field is the literal `jira`; the artifacts field is always `{project-root}/_bmad-output/implementation-artifacts`, because a Jira sprint store has no path | `sprint_backend:`, `jira_url:`, `jira_project_key:`, `implementation_artifacts:` |
+| `sprint_management` has any other mode | `sprint_management` → its `path:`; the backend field is the literal `file-system`; the artifacts field is that same path, except that a path of `.` gives `{project-root}/_bmad-output/implementation-artifacts` | `sprint_backend:`, `sprint_management_path:`, `implementation_artifacts:` |
+
+**When the binding says `mode: jira`, `sprint_management_path:` is not compared at all.** The generator writes no `sprint_management_path:` in that mode — and it never DELETES a field, it only updates or appends one. So a project that was bound to the file system and later re-bound to Jira still carries its old `sprint_management_path:` line in a freshly generated `config.yaml`. That leftover line is not drift, and comparing it would halt every Jira project that was ever file-system-bound.
+
+Not every field in that table is a path. Where a store's `backend:` or `space_key:` is what disagrees, the comparison is the same and so is the halt — read the message template's `{path in …}` placeholders as "the value that disagrees", and name the two values you actually compared.
+
+**Any disagreement is drift** → **HALT** and report, naming every store that moved and both of its paths:
+
+> **ma-agents — stopping: `_bmad/bmm/config.yaml` is stale.**
+> The committed binding in `_bmad-output/project-layout.yaml` no longer matches the state `_bmad/bmm/config.yaml` was generated from:
+> - {store name}: was `{path in config.yaml}`, is now `{path in project-layout.yaml}`
+> (one line per store that moved)
+> Running this skill now would read and write artifacts where those stores used to be. Run `ma-agents bind` to regenerate `_bmad/bmm/config.yaml` from the committed binding, then run this skill again.
+> Nothing has been read or written on your behalf. Stopping rather than guessing.
+
+**If everything in the table agrees** → go to **Step P5**.
+
+The stamp covers binding state that `config.yaml` does not carry — a Confluence `root_page:`, a `gitUrl:` — so the table alone cannot see every kind of move. If, and only if, a command shell is available to you and `ma-agents` resolves as a local dependency of this project, you may confirm the comparison exactly, without parsing the stamp yourself:
+
+```bash
+node -e "const c=require('ma-agents/bin/cli.js'),f=require('fs'),p=process.cwd();const t=c.resolveProjectTopology(p);if(!t.ok){console.log('binding:'+t.reason)}else{const s=c.readProjectLayoutStamp(f.readFileSync('_bmad/bmm/config.yaml','utf8'));console.log(s.ok?(s.value===c.computeProjectLayoutStamp(t.topology,p)?'MATCH':'DRIFT'):'stamp:'+s.reason)}"
+```
+
+`DRIFT` is authoritative: HALT with the stale-config message above even when the table found nothing, and say that the binding changed in a way `config.yaml` does not record. Never treat a failure to run this command as a result — if it does not run, the table is the check, and you say nothing about the stamp.
+
+### Step P5 — PROCEED
+
+The generated config matches the committed binding. Say NOTHING about the binding, the stamp or this preflight — a matched project gets no message — and continue with the rest of this skill.
+
 ## Backend Routing
 
 Before executing any file-system operations, determine and route to the correct backend:

package/lib/bmad-extension/skills/bmad-dev-epic/SKILL.md

@@ -9,6 +9,118 @@ description: 'Orchestrate a full epic end-to-end with parallel subagents — per
 
 **Your Role:** You are the Epic Orchestrator. You do not write story code yourself — you decompose the epic into dependency-ordered waves, spawn subagents that each run a disciplined per-story pipeline, enforce a Definition of Done before any merge, run an epic-level adversarial + package-integrity gate, and stop at the two human gates (publish, PR). You are precise about git isolation, model tiers, and failure handling. No noise, no filler.
 
+## Knowledge Store Binding Preflight
+
+**Gateway check — run this before anything else in this skill.** Before any read, any write, any user prompt, and before any other routing or configuration step below. No other step of this skill executes until this preflight returns PROCEED.
+
+`_bmad/bmm/config.yaml` is a GENERATED file. `ma-agents` derives it from the committed binding in `_bmad-output/project-layout.yaml` on install and on `ma-agents bind`, and records which binding it was generated from in its `project_layout_stamp:` field. If the binding has moved since — the usual cause is a `git pull` that relocated a knowledge store — every path this skill would resolve from `config.yaml` points at where the stores used to be. This preflight refuses to let that happen silently.
+
+**This preflight is read-only.** Whatever it finds, do NOT regenerate, repair, edit or create `config.yaml`, `_bmad-output/project-layout.yaml`, or any other file, and do not offer to. Regenerating the config belongs to the installer and to `ma-agents bind`, never to a skill.
+
+**Compare content, never timestamps.** Never decide staleness from file modification times: mtime ordering is not preserved by `git pull`, `git checkout` or a fresh clone, so it both misses real drift and reports drift on a clean checkout.
+
+Work through the steps below IN ORDER and stop at the first branch that matches. The order is load-bearing — `_bmad-output/project-layout.yaml` is the fact, and the stamp only ever corroborates it.
+
+### Step P1 — Read `_bmad-output/project-layout.yaml`
+
+- **Missing, or present but blank / comments-only** → go to **Step P2**.
+- **Present but not cleanly readable** — it is not valid YAML, it carries unresolved merge-conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`), it yields no readable fields, its `schema_version:` is greater than `2`, its `schema_version:` is present but is not a number, it names a `backend:` or a `mode:` this build does not recognise, or any store record in it cannot be read → **HALT** and report:
+
+  > **ma-agents — stopping: the committed knowledge binding cannot be read.**
+  > `_bmad-output/project-layout.yaml` exists but this build cannot use it: {say exactly what is wrong}.
+  > Every knowledge-store path in `_bmad/bmm/config.yaml` is derived from that file, so nothing this skill would resolve can be trusted. Fix the binding by hand — if this is a merge conflict, resolve it; the file is committed, so conflicts are ordinary — then run `ma-agents bind` to regenerate `_bmad/bmm/config.yaml` from it.
+  > Nothing has been read or written on your behalf. Stopping rather than guessing.
+
+  That list of faults is illustrative, not exhaustive. **Default-deny:** the only two ways out of this step without halting are "absent, or blank / comments-only" (→ Step P2) and "resolves cleanly" (→ Step P3). Anything else takes this HALT, including a fault not named above. Do not fall back to defaults and do not treat this as "no binding". A binding that cannot be read is a different fact from a project that has none.
+- **Present and resolves cleanly** → go to **Step P3**.
+
+### Step P2 — There is no committed binding
+
+No `_bmad-output/project-layout.yaml`. That is the pre-F26 shape and by itself it is NOT drift — but corroborate it instead of trusting it, because "a binding was never written here" and "the binding was deleted, ignored, or not pulled" look identical from the missing file alone. Read `_bmad/bmm/config.yaml`:
+
+- **`config.yaml` does not exist either** → **HALT** and report:
+
+  > **ma-agents — stopping: this project is not configured.**
+  > Neither `_bmad-output/project-layout.yaml` nor `_bmad/bmm/config.yaml` exists, so nothing states where this project's knowledge stores live. Run `npx ma-agents install` to configure the project, or `ma-agents bind` if ma-agents is already installed and only the binding is missing.
+  > Nothing has been read or written on your behalf. Stopping rather than guessing.
+
+- **`config.yaml` exists and carries, at column 0, any of `project_layout_stamp:`, `system_requirements_path:` or `software_requirements_path:`** (a commented-out or indented one does not count — it is not the field) → **HALT** and report:
+
+  > **ma-agents — stopping: the committed knowledge binding is missing.**
+  > `_bmad/bmm/config.yaml` carries {name the fields you found}, which only an F26 generation writes — so this project HAS been bound — but `_bmad-output/project-layout.yaml` is not here. The binding was deleted, is untracked or ignored, or has not been pulled. This is not a pre-F26 project, so proceeding would mean trusting generated paths against a binding that no longer exists.
+  > Restore the file (for example `git checkout -- _bmad-output/project-layout.yaml`), or run `ma-agents bind` to write a fresh one.
+  > Nothing has been read or written on your behalf. Stopping rather than guessing.
+
+  Those three fields are the discriminator and they are reliable: a genuine pre-F26 `config.yaml` carries none of them. Do not skip this check. An absent stamp on its own is never evidence that a project predates the stamp.
+
+- **`config.yaml` exists and carries none of those three fields at column 0** → this is genuinely a pre-F26 project. **PROCEED** with the rest of this skill exactly as it behaved before F26, and say nothing at all about the binding — no warning, no prompt, no offer to bind. Nothing has moved, so there is nothing to re-bind. The existence of `config.yaml` is NOT on its own a reason to take this branch: all three fields must be absent.
+
+### Step P3 — The binding is readable: check what `config.yaml` was generated from
+
+Read `_bmad/bmm/config.yaml`.
+
+- **`config.yaml` does not exist** → **HALT** and report:
+
+  > **ma-agents — stopping: the generated config is missing.**
+  > `_bmad-output/project-layout.yaml` commits this project's knowledge binding, but `_bmad/bmm/config.yaml` — the file this skill resolves its paths from — has never been generated from it. Run `npx ma-agents install` to install into this project, or `ma-agents bind` if ma-agents is already installed, to generate `_bmad/bmm/config.yaml` from the committed binding.
+  > Nothing has been read or written on your behalf. Stopping rather than guessing.
+
+- **No `project_layout_stamp:` line at column 0 of `config.yaml`** (a commented-out or indented one does not count — it is not the field) → **HALT** and report:
+
+  > **ma-agents — stopping: `_bmad/bmm/config.yaml` does not record which binding it came from.**
+  > `_bmad-output/project-layout.yaml` exists, but `config.yaml` carries no `project_layout_stamp:`, so there is no evidence its paths were generated from the committed binding. Run `ma-agents bind` to regenerate it.
+  > Nothing has been read or written on your behalf. Stopping rather than guessing.
+
+- **`project_layout_stamp:` is present but its value is not `sha256:` followed by exactly 64 lowercase hexadecimal characters** — truncated, uppercased, a different algorithm, unbalanced quotes, or trailing content after the digest → **HALT** and report:
+
+  > **ma-agents — stopping: `_bmad/bmm/config.yaml` claims to have been generated and the claim cannot be read.**
+  > Its `project_layout_stamp:` is {quote the value you found}, which is not a stamp ma-agents wrote (expected `sha256:` followed by 64 lowercase hex characters) — merge damage, a hand-edit, or a truncated write. Treat this config as unverified; it is NOT a config that predates the stamp. Run `ma-agents bind` to regenerate it from `_bmad-output/project-layout.yaml`.
+  > Nothing has been read or written on your behalf. Stopping rather than guessing.
+
+- **`project_layout_stamp:` is well-formed** → go to **Step P4**.
+
+### Step P4 — Compare the committed binding against the generated fields
+
+Derive, from `_bmad-output/project-layout.yaml`, what each generated field in `config.yaml` WOULD be if it were regenerated right now, and compare it to what `config.yaml` actually carries. This is a content comparison of the two files — never a timestamp comparison.
+
+A schema-2 binding holds three records: `system_requirements_store:`, `software_requirements_store:` and `sprint_management:`. A legacy schema-1 binding holds a single `knowledgebase:` record, which stands for BOTH requirement stores.
+
+The table below IS the whole comparison: every field named in its right-hand column is compared, and no field outside that column is. Read each field only from a line at column 0, and compare VALUES rather than bytes — the generator quotes its scalars (`sprint_backend: "jira"`, `knowledgebase_path: "."`), so strip one balanced pair of surrounding quotes from each side first.
+
+| When | Binding record it is derived from | Field(s) it generates in `config.yaml` |
+| --- | --- | --- |
+| always | `software_requirements_store` → its `path:` (a store whose `backend:` is not `file-system` has no `path:` at all, and so generates `.`); the artifacts field is that same path, except that a path of `.` gives `{project-root}/_bmad-output/planning-artifacts`; its resolved `backend:` (an absent or empty `backend:` resolves to `file-system`), and, when that backend is `confluence`, its `space_key:` — the generated space-key field is empty for every other backend, so a store re-bound away from Confluence does not keep the old space | `software_requirements_path:`, `knowledgebase_path:`, `planning_artifacts:`, `software_requirements_backend:`, `software_requirements_space_key:` |
+| always | `system_requirements_store` → its `path:` (a store whose `backend:` is not `file-system` has no `path:` at all, and so generates `.`); its resolved `backend:` (an absent or empty `backend:` resolves to `file-system`), and, when that backend is `confluence`, its `space_key:` — the generated space-key field is empty for every other backend, so a store re-bound away from Confluence does not keep the old space | `system_requirements_path:`, `system_requirements_backend:`, `system_requirements_space_key:` |
+| `sprint_management` has `mode: jira` | `sprint_management` → its `jira_url:` and `jira_project_key:`; the backend field is the literal `jira`; the artifacts field is always `{project-root}/_bmad-output/implementation-artifacts`, because a Jira sprint store has no path | `sprint_backend:`, `jira_url:`, `jira_project_key:`, `implementation_artifacts:` |
+| `sprint_management` has any other mode | `sprint_management` → its `path:`; the backend field is the literal `file-system`; the artifacts field is that same path, except that a path of `.` gives `{project-root}/_bmad-output/implementation-artifacts` | `sprint_backend:`, `sprint_management_path:`, `implementation_artifacts:` |
+
+**When the binding says `mode: jira`, `sprint_management_path:` is not compared at all.** The generator writes no `sprint_management_path:` in that mode — and it never DELETES a field, it only updates or appends one. So a project that was bound to the file system and later re-bound to Jira still carries its old `sprint_management_path:` line in a freshly generated `config.yaml`. That leftover line is not drift, and comparing it would halt every Jira project that was ever file-system-bound.
+
+Not every field in that table is a path. Where a store's `backend:` or `space_key:` is what disagrees, the comparison is the same and so is the halt — read the message template's `{path in …}` placeholders as "the value that disagrees", and name the two values you actually compared.
+
+**Any disagreement is drift** → **HALT** and report, naming every store that moved and both of its paths:
+
+> **ma-agents — stopping: `_bmad/bmm/config.yaml` is stale.**
+> The committed binding in `_bmad-output/project-layout.yaml` no longer matches the state `_bmad/bmm/config.yaml` was generated from:
+> - {store name}: was `{path in config.yaml}`, is now `{path in project-layout.yaml}`
+> (one line per store that moved)
+> Running this skill now would read and write artifacts where those stores used to be. Run `ma-agents bind` to regenerate `_bmad/bmm/config.yaml` from the committed binding, then run this skill again.
+> Nothing has been read or written on your behalf. Stopping rather than guessing.
+
+**If everything in the table agrees** → go to **Step P5**.
+
+The stamp covers binding state that `config.yaml` does not carry — a Confluence `root_page:`, a `gitUrl:` — so the table alone cannot see every kind of move. If, and only if, a command shell is available to you and `ma-agents` resolves as a local dependency of this project, you may confirm the comparison exactly, without parsing the stamp yourself:
+
+```bash
+node -e "const c=require('ma-agents/bin/cli.js'),f=require('fs'),p=process.cwd();const t=c.resolveProjectTopology(p);if(!t.ok){console.log('binding:'+t.reason)}else{const s=c.readProjectLayoutStamp(f.readFileSync('_bmad/bmm/config.yaml','utf8'));console.log(s.ok?(s.value===c.computeProjectLayoutStamp(t.topology,p)?'MATCH':'DRIFT'):'stamp:'+s.reason)}"
+```
+
+`DRIFT` is authoritative: HALT with the stale-config message above even when the table found nothing, and say that the binding changed in a way `config.yaml` does not record. Never treat a failure to run this command as a result — if it does not run, the table is the check, and you say nothing about the stamp.
+
+### Step P5 — PROCEED
+
+The generated config matches the committed binding. Say NOTHING about the binding, the stamp or this preflight — a matched project gets no message — and continue with the rest of this skill.
+
 ## Conventions
 
 - Bare paths (e.g. `checklist.md`) resolve from the skill root.