ma-agents 3.17.1 → 3.18.0-beta.2

package/lib/bmad-extension/skills/bmad-dev-story/workflow.md

@@ -13,6 +13,118 @@
 
 ---
 
+## 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.
+
 ## INITIALIZATION
 
 ### Configuration Loading

package/lib/bmad-extension/skills/bmad-knowledge/SKILL.md

@@ -12,6 +12,118 @@ triggers:
 
 Generate a self-contained, offline-ready Knowledge Atlas HTML site from the project's planning and implementation artifacts. No network access is required at generation or view time.
 
+## 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.
+
 ## Prerequisites
 
 - The project must have a `_bmad-output/` directory (created by BMAD install) and/or a `_bmad/bmm/config.yaml` pointing at where its knowledge actually lives.

package/lib/bmad-extension/skills/bmad-sprint-planning/workflow.md

@@ -6,6 +6,167 @@
 
 ---
 
+## 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.
+
+## Knowledge Store Backend Routing
+
+**Gateway check — run this immediately after the preflight above, and before anything else.** Before any read, any write, any user prompt, and before the sprint-tracking `## Backend Routing` check below. No step of this skill executes until this check returns PROCEED.
+
+This is the SAME routing pattern the sprint skills use for Jira, applied to a knowledge store instead of to sprint tracking. It is not a second mechanism: read the backend from the resolved configuration, branch on its value, and where it cannot be honoured say exactly what is wrong and stop. `mcp-detection-pattern-spec.md` defines the shape — §2.6 (this is a gateway check, not an afterthought), §2.7 (absent or empty means `file-system`), §6.6 (a backend is added by adding a branch, and the `file-system` branch is untouched).
+
+**Which store gates this skill.** This skill resolves epics, and epics are a *software requirements* artifact (FR256), so the store that gates it is the **software requirements store**. Read these two fields from `_bmad/bmm/config.yaml`, each only from a line at column 0, stripping one balanced pair of surrounding quotes from the value:
+
+- `software_requirements_backend:` — the backend of the store this skill reads its epics from.
+- `software_requirements_space_key:` — that store's Confluence space, when it has one.
+
+A skill that resolves a *system requirements* artifact reads `system_requirements_backend:` and `system_requirements_space_key:` instead and takes exactly these branches; nothing else about the check changes. Sprint execution state — story files, `sprint-status.yaml`, bugs, retrospectives — belongs to NEITHER knowledge store (FR267), so nothing this skill does with those artifacts is affected by any branch below.
+
+Take the first branch that matches, and stop there.
+
+### Step B1 — `file-system`, or the field is absent, or its value is empty
+
+**PROCEED** with the rest of this skill exactly as written below, unchanged. Say NOTHING about the backend: a file-system project gets no message from this section, no prompt, and no offer. This is the default (§2.7), and it is what every project that has not configured a Confluence store gets — including every project generated before the field existed. Nothing in this section reads, writes, resolves or reports anything on this path.
+
+### Step B2 — `confluence`
+
+That store's artifacts live in Confluence, and Confluence is the source of truth for them. Before resolving, reading or writing ANY artifact belonging to that store, determine whether a Confluence-capable tool is available to you in your current tool context — an MCP server, plugin or native integration connected to the Confluence instance that hosts the space named above. Do not assume one is present because the backend says `confluence`: the backend is a statement of configuration, and availability is a fact about this run.
+
+- **A Confluence-capable tool IS available** → route this store's reads and writes to it, in the space named by the space-key field, and treat what it returns as the source of truth for that store. Do NOT read that store's artifacts from a local directory instead, and do NOT write, copy, cache, export or reconcile a local copy of anything Confluence returns. There is no mirror and no cache, so there is nothing to synchronise and nothing to fall out of date.
+
+  **Where that store's artifacts live in the space, and how to write one.** ONE page per markdown artifact, nested under the store's root page so the pages match the source folder structure: `epics.md` is the page titled `epics` directly under that root page, and `prd/capabilities/skills-platform.md` is `skills-platform` under `capabilities` under `prd`, which is also how a sharded document becomes an index page with its shards as children. A page title is unique within a space, so the title identifies the page and the parent only says where it hangs. Run `ma-agents confluence-plan` to print that mapping for THIS project together with the complete set of operations a publish performs and the order to perform them in, parents first; it enumerates the plan and performs none of it, because the Confluence-capable tool is in your context and not in that process. To write, take the pages in the order it prints and, for each, look its title up in the space: update that page when it is already there and create it when it is not. That is an idempotent write, not a reconciliation — there are never two versions to compare, so a second publish of the same artifacts lands on the same pages and their history and comments survive. Report the root page by name to the user, and when it was created rather than found, record the id Confluence gave it by running `ma-agents confluence-record-root-page` so later runs address it directly. If any write does not report success, STOP, say which page failed, and report no publish.
+
+- **No Confluence-capable tool is available** → **HALT** and report:
+
+  > **ma-agents — stopping: this knowledge store is Confluence-backed and no Confluence MCP was detected.**
+  > Store: the software requirements store. Space: {the value of the space-key field, or `not recorded` when that field is absent or empty}.
+  > No Confluence MCP server is available in this agent's tool context, so that store cannot be read or written.
+  > To configure one, add a Confluence-capable MCP server to your agent's MCP configuration, pointed at the Confluence instance that hosts that space, and authorise it; then run this skill again. Alternatively, re-run the installer (or `ma-agents bind`) to bind that store to the file system instead.
+  > Nothing has been read or written on your behalf, and nothing has been written locally. Stopping rather than guessing.
+
+  Then STOP. Do NOT fall back to the file system. Do NOT read, create or offer to create a local copy of that store's artifacts. Do NOT continue with a partial or empty result as though the store were empty. Do NOT change the configured backend on the user's behalf. A Confluence-backed store with no Confluence MCP has no degraded mode — halting IS the behaviour, not a failure to find one.
+
+### Step B3 — any other value
+
+**HALT** and report:
+
+  > **ma-agents — stopping: unrecognised knowledge-store backend.**
+  > Store: the software requirements store. Backend: `{the value you read}`. The backends this build understands are `file-system` and `confluence`.
+  > `_bmad/bmm/config.yaml` is generated, so a value outside that set means it was hand-edited or written by a different build — and every artifact this skill would resolve for that store depends on which of the two it actually is.
+  > Run `ma-agents bind` to regenerate `_bmad/bmm/config.yaml`, or re-run the installer.
+  > Nothing has been read or written on your behalf. Stopping rather than guessing.
+
+**Default-deny, deliberately.** This is the one place this block departs from `mcp-detection-pattern-spec.md`, which for an unrecognised *sprint tracking* value prints a message and falls back to the file system (§2.5). A knowledge store does not get that treatment: falling back would resolve a store this build cannot identify to local files, which is exactly the silent degradation FR262 forbids. Step B1's default is for a field that was never stated. It is not a catch-all, and it must never absorb a value that IS stated and is not understood.
+
 ## INITIALIZATION
 
 ### Configuration Loading

package/lib/bmad-extension/skills/bmad-sprint-status/workflow.md

@@ -8,6 +8,118 @@
 
 ---
 
+## 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.
+
 ## INITIALIZATION
 
 ### Configuration Loading