feat: add file reference validator (MSSCI-14579)

.github/workflows/quality.yaml

@@ -113,3 +113,6 @@ jobs:
 
       - name: Test agent compilation components
         run: npm run test:install
+
+      - name: Validate file references
+        run: npm run validate:refs

package.json

@@ -30,8 +30,10 @@
     "release:minor": "npm version minor && git push --follow-tags",
     "release:patch": "npm version patch && git push --follow-tags",
     "release:prerelease": "npm version prerelease && git push --follow-tags",
-    "test": "npm run test:schemas && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
+    "test": "npm run test:schemas && npm run test:refs && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
+    "test:refs": "node test/test-validate-file-refs.cjs",
     "test:schemas": "node test/test-agent-schema.js",
+    "validate:refs": "node tools/validate-file-refs.mjs",
     "validate:schemas": "node test/validate-agent-schema.js"
   },
   "lint-staged": {

src/workflows/agent/data/agent-validation.md

@@ -77,7 +77,7 @@ critical_actions:
 - [ ] ALL sidecar paths: `{project-root}/_bmad/_memory/{sidecar-folder}/...`
 - [ ] `{project-root}` is literal (not replaced)
 - [ ] `{sidecar-folder}` = actual folder name
-- [ ] No `./` or `/Users/` paths
+- [ ] No `./` or `/Users/` paths <!-- validate-file-refs:ignore -->
 
 ### Persona Addition
 - [ ] `communication_style` includes memory reference patterns

src/workflows/workflow/data/frontmatter-standards.md

@@ -16,9 +16,9 @@
 
 | Variable | Example |
 |----------|---------|
-| `{project-root}` | `/Users/user/dev/BMAD-METHOD` |
+| `{project-root}` | `/Users/user/dev/BMAD-METHOD` <!-- validate-file-refs:ignore --> |
 | `{project_name}` | `my-project` |
-| `{output_folder}` | `/Users/user/dev/BMAD-METHOD/output` |
+| `{output_folder}` | `/Users/user/dev/BMAD-METHOD/output` <!-- validate-file-refs:ignore --> |
 | `{user_name}` | `Brian` |
 | `{communication_language}` | `english` |
 | `{document_output_language}` | `english` |
@@ -110,8 +110,8 @@ nextStepFile: './step-02-foo.md'
 | Pattern | Why |
 |---------|-----|
 | `workflow_path: '{project-root}/...'` | Use relative paths |
-| `thisStepFile: './step-XX.md'` | Remove unless referenced |
-| `workflowFile: './workflow.md'` | Remove unless referenced |
+| `thisStepFile: './step-XX.md'` | Remove unless referenced <!-- validate-file-refs:ignore --> |
+| `workflowFile: './workflow.md'` | Remove unless referenced <!-- validate-file-refs:ignore --> |
 | `{workflow_path}/templates/...` | Use `../template.md` |
 | `{workflow_path}/data/...` | Use `./data/file.md` |
 

src/workflows/workflow/data/step-type-patterns.md

@@ -79,7 +79,7 @@ templateFile: '../templates/[template].md'
 ### 2. Init (Continuable)
 **Use:** Multi-session workflow
 
-**Frontmatter:** Add `continueFile: './step-01b-continue.md'`
+**Frontmatter:** Add `continueFile: './step-01b-continue.md'` <!-- validate-file-refs:ignore -->
 
 **Logic:**
 ```markdown

test/fixtures/file-refs/invalid/absolute-path-leak.md

@@ -0,0 +1,5 @@
+# Absolute Path Leak
+
+This file contains a leaked absolute path:
+
+Load config from /Users/developer/project/_bmad/config.yaml

test/fixtures/file-refs/invalid/broken-internal-ref.agent.yaml

@@ -0,0 +1,11 @@
+# Fixture: broken internal {project-root}/_bmad/bmb/ ref
+# Expected: BROKEN (target does not exist in src/)
+agent:
+  metadata:
+    id: test-agent
+    name: Test
+    module: bmb
+  menu:
+    - trigger: XX or fuzzy match on nonexistent
+      exec: "{project-root}/_bmad/bmb/workflows/nonexistent/workflow.md"
+      description: "Broken ref"

test/fixtures/file-refs/invalid/broken-relative-ref.md

@@ -0,0 +1,9 @@
+---
+name: 'step-broken'
+description: 'Test step with broken relative ref'
+nextStepFile: './does-not-exist.md'
+---
+
+# Broken Step
+
+This step has a broken relative ref.

test/fixtures/file-refs/invalid/wrong-depth.md

@@ -0,0 +1,9 @@
+---
+name: 'step-wrong-depth'
+description: 'Step with wrong relative depth (../../ instead of ../)'
+nextStepFile: '../../data/frontmatter-standards.md'
+---
+
+# Wrong Depth
+
+This step uses ../../ when it should use ../ — a common BMB broken ref pattern.

test/fixtures/file-refs/skip/external-core-ref.md

@@ -0,0 +1,10 @@
+---
+name: 'step-with-external'
+description: 'Step with external core module ref (should be skipped)'
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+---
+
+# External Refs
+
+These refs point to the core module and should be skipped by default.

test/fixtures/file-refs/skip/external-relative-ref.md

@@ -0,0 +1,10 @@
+---
+name: 'step-with-relative-external'
+description: 'Step with ../../../../core/ relative ref (should be skipped)'
+advancedElicitationTask: '../../../../core/workflows/advanced-elicitation/workflow.xml'
+partyModeWorkflow: '../../../../core/workflows/party-mode/workflow.md'
+---
+
+# Relative External Refs
+
+These climb out of the src/ directory and should be skipped.

test/fixtures/file-refs/skip/install-generated-ref.md

@@ -0,0 +1,10 @@
+---
+name: 'step-install-generated'
+description: 'Step referencing install-generated files (should be skipped)'
+---
+
+# Install Generated
+
+Load and read full config from {project-root}/_bmad/bmb/config.yaml and resolve variables.
+
+Check KB at {project-root}/_bmad/bmb/docs/workflows/kb.csv for context.

test/fixtures/file-refs/skip/template-placeholder.md

@@ -0,0 +1,11 @@
+---
+name: 'step-[N]-[name]'
+description: 'Template pattern with bracketed placeholders'
+nextStepFile: './step-02-[name].md'
+outputFile: '{output_folder}/[output].md'
+templateFile: '../templates/[template].md'
+---
+
+# Template Placeholders
+
+These bracketed refs are templates, not real file references. They should be skipped.

test/fixtures/file-refs/skip/unresolvable-vars.md

@@ -0,0 +1,10 @@
+---
+name: 'step-with-runtime-vars'
+description: 'Step with runtime variables that cannot be resolved statically'
+workflowPlanFile: '{bmb_creations_output_folder}/workflows/{new_workflow_name}/workflow-plan.md'
+outputFile: '{output_folder}/report-{datetime}.md'
+---
+
+# Runtime Variables
+
+These contain {curly_brace} variables that are resolved at runtime, not statically.

test/fixtures/file-refs/valid/csv-workflow-ref.csv

@@ -0,0 +1,2 @@
+module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs,
+bmb,anytime,Create Agent,CA,10,_bmad/bmb/workflows/agent/workflow-create-agent.md,bmad_bmb_create_agent,false,agent-builder,Create Mode,"Create agent",bmb_creations_output_folder,"agent",

test/fixtures/file-refs/valid/internal-bmb-ref.agent.yaml

@@ -0,0 +1,11 @@
+# Fixture: valid internal {project-root}/_bmad/bmb/ ref
+# Expected: VALID (maps to src/workflows/workflow/workflow-create-workflow.md)
+agent:
+  metadata:
+    id: test-agent
+    name: Test
+    module: bmb
+  menu:
+    - trigger: CW or fuzzy match on create-workflow
+      exec: "{project-root}/_bmad/bmb/workflows/workflow/workflow-create-workflow.md"
+      description: "Test menu item"

test/fixtures/file-refs/valid/relative-ref-target.md

@@ -0,0 +1,3 @@
+# Target File
+
+This file exists so the relative ref in relative-ref.md resolves.

test/fixtures/file-refs/valid/relative-ref.md

@@ -0,0 +1,9 @@
+---
+name: 'step-03-requirements'
+description: 'Test step with valid relative ref'
+nextStepFile: './relative-ref-target.md'
+---
+
+# Test Step
+
+This step has a valid relative ref in frontmatter.