bmad-plus 0.13.0 → 0.14.0

package/src/bmad-plus/packs/pack-dev-studio/upstream-sync.yaml

@@ -1,15 +1,41 @@
-# Pack Dev Studio — upstream-sync.yaml
-# Tracks the source commit and version from BMAD-METHOD for future updates
+# Dev Studio provenance and selective adaptation ledger.
+# Version and commit below have different, explicitly recorded roles.
+# The 0.14.0 implementation is original BMAD+ work, not a wholesale upstream sync.
+schema_version: 2
 
 upstream:
   repository: https://github.com/bmad-code-org/BMAD-METHOD
   version: "6.6.0"
+  version_role: declared-compatibility-baseline
+  baseline_tag_commit: "e6cdc93b79420fcc915d3bd3ca63387bc86af694"
   commit: "0f852a38ac7c0ac30340b3aedc3aba4505b7c14a"
+  commit_role: historical-partial-import
   synced_at: "2026-05-17"
+  synced_at_role: recorded-date-of-historical-import
   license: MIT
 
+reviewed_reference:
+  version: "6.12.0"
+  commit: "05bfbd46d00766ec88eb9b42e76be2c575d64d7b"
+  reviewed_at: "2026-09-09"
+  status: reviewed-only
+  full_migration: false
+  compatibility_baseline_changed: false
+
+implementation:
+  bmad_plus_version: "0.14.0"
+  origin: original-bmad-plus-instructions-and-context-preparation
+  authored_at: "2026-09-09"
+  execution: host-managed-markdown
+  context_preparation: read-only-cli
+  standalone_llm_runtime: false
+  upstream_runtime_imported: false
+  preserved_public_workflow_ids: 38
+  preserved_personas: 6
+  evidence_limit: Resource reconciliation does not establish host execution or model compliance.
+
 adaptations:
-  format: "BMAD+ BWML (Workflow Markup Language)"
+  format: Original BMAD+ Markdown procedures with explicit inputs, evidence and continuation.
   personas:
     Mary: Miriam (מרים)
     Paige: Huldah (חולדה)
@@ -17,18 +43,63 @@ adaptations:
     Sally: Rachel (רחל)
     Winston: Bezalel (בצלאל)
     Amelia: Oholiab (אהליאב)
-  removed_dependencies:
-    - customize.toml (3-layer TOML config system)
-    - resolve_customization.py (Python variable resolver)
-    - resolve_config.py (Python config merger)
-    - analyze_sources.py (Python source analyzer)
-    - config.yaml (per-project config)
-  added:
-    - BWML specification (shared/bwml-spec.md)
-    - Dev Studio orchestrator
-    - Specialized persona naming
-    - BMAD+ pack integration (module.yaml, CLI, i18n)
+  entry: SKILL.md
+  catalog: shared/catalog.json
+  execution_guide: shared/execution.md
+  historical_bwml_document: shared/bwml-spec.md
+  historical_bwml_document_role: migration-note-not-interpreter-specification
+  configuration:
+    file: _bmad/config.yaml
+    scope: explicitly-selected-project
+    parser: existing-bmad-plus-yaml-parser
+    known_fields:
+      - user_name
+      - communication_language
+      - document_output_language
+      - output_folder
+      - project_name
+    missing_values: Explicit neutral defaults in the execution guide.
+    invalid_present_values: Report an error rather than inventing configuration.
+    preserve_unrelated_settings: true
+    layered_toml_overrides: false
+  retired_dependency_contracts:
+    - Imported PRD headless schemas and automatic HTML validation rendering.
+    - Distillator compression/reconstruction format and Python source analyzer.
+    - Upstream Python/TOML customization discovery and layered override merging.
+    - Implied execution of BWML tags as scheduler, memory, events or validation gates.
+  historical_dependency_note: >-
+    The old removed_dependencies list was not proof that dependent instructions
+    remained executable. Project YAML configuration is supported now; it is not
+    a removed dependency. Per-skill customize.toml files and shared upstream
+    resolvers fall outside the 147-support-file inventory below.
+
+support_reconciliation:
+  source_method: Read-only git ls-tree at the historical import commit.
+  historical_bmad_plus_commit: "913d0600b9e0c3ac12af22b17e2205bf9d394a63"
+  mapped_entry_families: 44
+  excluded_relative_paths:
+    - SKILL.md
+    - customize.toml
+  source_support_files: 147
+  historically_delivered: 15
+  historically_omitted: 132
+  historically_omitted_families: 24
+  omitted_dispositions:
+    replaced-by-self-contained-workflows: 117
+    retired-runtime: 12
+    optional-tests-or-metadata: 3
+  delivered_disposition: retained-as-original-support
+  interpretation: >-
+    Counts describe the pre-remediation snapshot. An omitted support file is not
+    automatically a demonstrated runtime failure. Replaced means the relevant
+    purpose is covered by original instructions, not exact upstream feature parity.
+    Retired-runtime includes unsupported execution contracts even when no working
+    runtime had been delivered.
+  repository_report: docs/research/dev-studio-0.14-validation/migration.md
+  repository_inventory: docs/research/dev-studio-0.14-validation/migration.json
 
+# Historical source mapping only. These are lineage references, not live imports
+# or runtime dependencies. Current routes resolve through shared/catalog.json.
 source_mapping:
   categories/analysis:
     - src/bmm-skills/1-analysis/bmad-agent-analyst → analyst-agent.md

package/src/bmad-plus/packs/pack-memory/README.md

@@ -48,6 +48,12 @@ Dedicated memory agent that can:
 
 ## Installation
 
+The npm pack provides file-based memory and requires Node.js only. Vector/RAG
+recall is an optional, local-only enhancement through a separately deployed
+MCP server. That server, its Python dependencies and its vector index are not
+included in the npm package; `--provision-python` does not install them.
+Missing RAG infrastructure does not disable Markdown memory or the project scanner.
+
 ```bash
 npx bmad-plus install
 # Select "🧠 Memory — Persistent Brain" in the pack menu

package/src/bmad-plus/packs/pack-memory/memory-orchestrator.md

@@ -16,10 +16,17 @@ Pack Memory provides a two-level persistent brain for BMAD+:
 
 ## Activation
 
-Pack Memory activates automatically when installed:
-- At session start: agents load project memory + global identity
-- During session: agents write decisions/lessons/patterns on trigger
-- At session end: session handoff is persisted
+Pack Memory supplies instructions and files for the host agent to use. The host
+must load and follow the memory protocol; installation alone does not execute it.
+No automatic session-start or session-end hooks are installed.
+
+While executing the protocol, the host agent should:
+
+- At session start: load project memory + global identity
+- During the session: record decisions, lessons and patterns when relevant
+- Before ending its work: persist a session handoff
+
+A session that ends without an agent turn has no guaranteed handoff.
 
 Manual activation via Zecher:
 - `"Zecher, scan projects in D:\travail\DEV"` — discover and index all projects
@@ -43,7 +50,7 @@ pack-memory/
 ├── memory-orchestrator.md              ← This file
 ├── zecher-agent.md                     ← Memory Agent (Zecher)
 ├── shared/
-│   ├── karpathy-guardrails.md          ← 4 Karpathy principles + memory hooks
+│   ├── karpathy-guardrails.md          ← 4 Karpathy principles + memory practices
 │   └── memory-protocol.md             ← Complete read/write protocol
 └── templates/
     ├── decisions.md                    ← ADR template

package/src/bmad-plus/packs/pack-seo/SKILL.md

@@ -15,6 +15,31 @@ description: >
 This skill orchestrates 3 specialized agents through a structured workflow.
 Load the full agent files only when activating that agent's phase.
 
+### Runtime availability
+
+The local `scripts/*.py` commands require a working Python environment and their
+optional service credentials or browser setup. Never invent crawl, PageSpeed,
+API or screenshot results.
+
+Use `bmad-plus install --provision-python` to provision the selected Python packs,
+or install this pack's `requirements.txt` in a dedicated environment manually.
+Run scripts with that environment's interpreter, not an assumed system Python.
+Provisioning is optional. Report **prompts-only mode** before starting an audit
+if the environment is unavailable. Do not repeatedly run failing scripts or
+install dependencies without authorization.
+
+### Evidence and reporting
+
+Use evidence available in the session or collected by working tools. Without a
+usable Python environment, use **prompts-only mode** and skip local Python commands.
+Mark missing data `unverified` and omit every score with incomplete inputs,
+including the overall SEO Health Score. Do not substitute zero or reweight the
+remaining categories. For incomplete audits, produce Markdown with explicit
+coverage: pages and checks reviewed, evidence sources, and unverified items.
+Use `scripts/seo_report.py` only when every score value it uses is verified;
+the current exporter has no N/A support. This policy applies to every role and
+overrides numeric placeholders in report templates.
+
 ## Command Router
 
 When the user issues a `/seo` command, route as follows:
@@ -90,7 +115,8 @@ Use `scripts/seo_screenshot.py <url> --viewport mobile` for visual audit.
 **Agent**: Chief (Scorer role)
 **Load**: `seo-chief.md`
 
-Compute SEO Health Score (0–100):
+Compute SEO Health Score (0–100) only when all weighted categories have verified
+inputs. Otherwise report coverage and omit the overall score:
 
 | Category | Weight |
 |----------|--------|

package/src/bmad-plus/packs/pack-seo/seo-chief.md

@@ -6,6 +6,18 @@
 
 You are **Chief**, the strategist and reporting agent of the BMAD+ SEO Engine. You aggregate findings from Scout and Judge, compute the SEO Health Score, generate prioritized action plans, and produce publication-ready reports.
 
+## Evidence and reporting
+
+Use evidence available in the session or collected by working tools. Without a
+usable Python environment, use **prompts-only mode** and skip local Python commands.
+Mark missing data `unverified` and omit every score with incomplete inputs,
+including the overall SEO Health Score. Do not substitute zero or reweight the
+remaining categories. For incomplete audits, produce Markdown with explicit
+coverage: pages and checks reviewed, evidence sources, and unverified items.
+Use `scripts/seo_report.py` only when every score value it uses is verified;
+the current exporter has no N/A support. This policy applies to every role and
+overrides numeric placeholders in report templates.
+
 ## Roles
 
 ### Role: Scorer
@@ -73,13 +85,16 @@ You are **Chief**, the strategist and reporting agent of the BMAD+ SEO Engine. Y
 | 0–39 | 🔴 Critical | Fundamental issues blocking performance |
 
 ### Category Score Calculation
-Each category is scored 0–100 based on the checklist pass rate:
+Score a category 0–100 only when its required checklist inputs are verified:
 - ✅ Pass = full points for that item
 - ⚠️ Warning = 50% points (issue exists but not blocking)
 - ❌ Fail = 0 points (blocking issue)
 
 **Final Score** = Σ(category_score × category_weight)
 
+Compute this total only when all weighted categories are verified. Missing
+evidence remains `unverified`; it is never a failed check or a zero score.
+
 ---
 
 ## Issue Priority Classification

package/src/bmad-plus/packs/pack-seo/seo-judge.md

@@ -6,6 +6,18 @@
 
 You are **Judge**, the content and AI analyst of the BMAD+ SEO Engine. You evaluate content quality, validate structured data, and measure AI search readiness. You are the analytical brain of the audit.
 
+## Evidence and reporting
+
+Use evidence available in the session or collected by working tools. Without a
+usable Python environment, use **prompts-only mode** and skip local Python commands.
+Mark missing data `unverified` and omit every score with incomplete inputs,
+including the overall SEO Health Score. Do not substitute zero or reweight the
+remaining categories. For incomplete audits, produce Markdown with explicit
+coverage: pages and checks reviewed, evidence sources, and unverified items.
+Use `scripts/seo_report.py` only when every score value it uses is verified;
+the current exporter has no N/A support. This policy applies to every role and
+overrides numeric placeholders in report templates.
+
 ## Roles
 
 ### Role: Content Expert

package/src/bmad-plus/packs/pack-seo/seo-scout.md

@@ -6,6 +6,18 @@
 
 You are **Scout**, the technical reconnaissance agent of the BMAD+ SEO Engine. You crawl, fetch, inspect, and photograph websites to produce raw technical intelligence for the audit pipeline.
 
+## Evidence and reporting
+
+Use evidence available in the session or collected by working tools. Without a
+usable Python environment, use **prompts-only mode** and skip local Python commands.
+Mark missing data `unverified` and omit every score with incomplete inputs,
+including the overall SEO Health Score. Do not substitute zero or reweight the
+remaining categories. For incomplete audits, produce Markdown with explicit
+coverage: pages and checks reviewed, evidence sources, and unverified items.
+Use `scripts/seo_report.py` only when every score value it uses is verified;
+the current exporter has no N/A support. This policy applies to every role and
+overrides numeric placeholders in report templates.
+
 ## Roles
 
 You operate in 3 switchable roles:

package/src/bmad-plus/skills/bmad-plus-autopilot/SKILL.md

@@ -50,8 +50,8 @@ The autopilot executes the following pipeline:
 
 Before starting, read `execution_mode` and `checkpoints` from `_bmad/config.yaml`. The checkpoint keys are `discovery` (PRD and UX review), `architecture`, `story` (each completed story), and `delivery`. Apply the configured behavior at each stage:
 
-- **require_approval** (🔴 STOP): Pause execution, send WhatsApp notification, wait for user approval.
-- **notify_only** (🟡 INFO): Send notification, continue unless user intervenes.
+- **require_approval** (🔴 STOP): Present the checkpoint in the session and wait for user approval. If an external notification channel is configured and sending is authorized, also notify through that channel.
+- **notify_only** (🟡 INFO): Report progress in the session and continue. If an external notification channel is configured and sending is authorized, also notify through that channel.
 - **auto** (🟢 AUTO): Continue automatically. Log for audit trail.
 
 ### State Management
@@ -96,4 +96,4 @@ Or via the Orchestrator capabilities menu: `AP`
 - **Test failure**: Auto-retry up to 3 times, then escalate to user
 - **Agent error**: Log error, notify user, skip to next step if non-critical
 - **Conflict in parallel execution**: Pause conflicting agent, resolve, restart
-- **User timeout at checkpoint**: Send reminder after 24h, pause pipeline
+- **User timeout at checkpoint**: Keep the pipeline paused. A reminder requires a configured scheduler and notification channel plus authorization; a bare installation has no background sender.

package/src/bmad-plus/skills/bmad-plus-sync/SKILL.md

@@ -47,8 +47,8 @@ bmad-plus-sync
   ├─ Uses Gemini API for:
   │   └─ AI-powered change classification
   │
-  └─ Notifies via:
-      └─ WhatsApp (Evolution API) or Email
+  └─ Reports in the current session
+      └─ If configured and authorized: WhatsApp (Evolution API) or email
 ```
 
 ## Protected Paths
@@ -66,4 +66,6 @@ Invoke via the Orchestrator (Nexus) or directly:
 bmad-plus-sync
 ```
 
-This skill is also called automatically by the VPS weekly cron job.
+The npm package installs no VPS, cron job or notification sender. An independently
+configured monitor may schedule checks. Use external notifications only when a
+channel is configured and the user has authorized sending; otherwise report inline.

package/src/bmad-plus/skills/dev-studio/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: dev-studio
+description: Open the installed Dev Studio pack for its six personas and 38 product, architecture, documentation and development workflows.
+---
+
+# Dev Studio dispatcher
+
+In an installed project, read the [Dev Studio pack](../pack-dev-studio/SKILL.md)
+and follow its activation procedure. It resolves the requested persona and
+workflow through the shipped catalog. The host executes the instructions;
+`bmad-plus studio prepare` only loads a read-only context bundle.
+
+This dispatcher is installed at `.agents/skills/dev-studio/SKILL.md`. Its sibling
+pack is at `.agents/skills/pack-dev-studio/SKILL.md`. In the BMAD+ source checkout,
+read `src/bmad-plus/packs/pack-dev-studio/SKILL.md` instead; the source and installed
+layouts intentionally differ.
+
+If the pack is absent, report the missing Dev Studio installation. Do not invent
+routes or treat a dispatcher without its resource files as an executable pack.

package/tools/build/check-install-contract.js

@@ -47,7 +47,10 @@ function sameSelection(actual, expected, label) {
 }
 
 /** Compare the installed bytes, normalizing only Windows/Unix line endings. */
-function verifyInstallation(projectDir, { packs, tools, derived, ideConfigs, renderFiles, requireInventory = false }) {
+function verifyInstallation(
+  projectDir,
+  { packs, tools, derived, ideConfigs, renderFiles, requireInventory = false }
+) {
   const manifest = JSON.parse(
     fs.readFileSync(path.join(projectDir, '_bmad', '.bmad-plus-install.json'), 'utf8')
   );
@@ -97,17 +100,88 @@ function verifyInstallation(projectDir, { packs, tools, derived, ideConfigs, ren
     assert.equal(manifest.fileInventory?.schemaVersion, 1, 'Missing file inventory');
     const { collectManagedFiles } = require('../cli/lib/update-transaction');
     const managedFiles = collectManagedFiles({ projectDir, packs });
-    assert.deepEqual(Object.keys(manifest.fileInventory.files).sort(), managedFiles.map(entry => entry.file).sort(),
-      'Inventory does not cover exactly the selected framework files');
+    assert.deepEqual(
+      Object.keys(manifest.fileInventory.files).sort(),
+      managedFiles.map((entry) => entry.file).sort(),
+      'Inventory does not cover exactly the selected framework files'
+    );
     for (const { file } of managedFiles) {
-      const actualHash = crypto.createHash('sha256').update(fs.readFileSync(resolveWithin(projectDir, file))).digest('hex');
-      assert.equal(manifest.fileInventory.files[file], actualHash, `Inventory differs from installed bytes: ${file}`);
+      const actualHash = crypto
+        .createHash('sha256')
+        .update(fs.readFileSync(resolveWithin(projectDir, file)))
+        .digest('hex');
+      assert.equal(
+        manifest.fileInventory.files[file],
+        actualHash,
+        `Inventory differs from installed bytes: ${file}`
+      );
     }
   }
   return files.length;
 }
 
-function run(command, args, { cwd, env, timeout = 60000 }) {
+function verifyDiagnostics(report, { packs, tools, derived }) {
+  assert.equal(report.schemaVersion, 1, 'Unsupported diagnostic report');
+  assert.equal(report.versions.installed, derived.product.version);
+  assert.equal(report.versions.cli, derived.product.version);
+  assert.equal(report.versions.published, null, 'Doctor must not invent npm freshness evidence');
+  sameSelection(
+    report.packs.map(({ id }) => id),
+    packs,
+    'diagnostic packs'
+  );
+  sameSelection(
+    report.integrations.map(({ tool }) => tool),
+    tools,
+    'diagnostic integrations'
+  );
+  for (const integration of report.integrations) {
+    assert.deepEqual(
+      integration,
+      {
+        tool: integration.tool,
+        ...derived.diagnostics.integrations[integration.tool],
+        ownership: 'unchanged',
+        hostVerified: false,
+      },
+      'An installed adapter must not imply verified host execution'
+    );
+  }
+  const expectedErrors = [];
+  assert.deepEqual(
+    report.checks
+      .filter(({ status }) => status === 'error')
+      .map(({ code, path: file }) => `${code}:${file}`)
+      .sort(),
+    expectedErrors.sort(),
+    'Every advertised pack must install without delivery errors'
+  );
+  assert.equal(report.summary.errors, expectedErrors.length);
+  assert.equal(report.inventory.status, 'complete');
+  assert(report.inventory.trackedFiles > 0, 'Doctor did not inspect the ownership inventory');
+  assert.equal(
+    report.checks.filter(({ code }) => code === 'file.unchanged').length,
+    report.inventory.trackedFiles,
+    'Every freshly installed managed file must have matching ownership'
+  );
+  assert(!report.checks.some(({ code }) => ['file.modified', 'file.unowned'].includes(code)));
+  for (const runtime of report.runtimes.filter(({ runtime }) => runtime === 'python')) {
+    assert.equal(
+      runtime.imports,
+      'not-verified',
+      'Presence of requirements cannot prove Python imports'
+    );
+    assert.equal(runtime.environment, 'missing', 'Contract checks must not provision Python');
+  }
+  const expectedStatus = expectedErrors.length
+    ? 'error'
+    : report.summary.warnings
+      ? 'warning'
+      : 'ok';
+  assert.equal(report.status, expectedStatus);
+}
+
+function run(command, args, { cwd, env, timeout = 60000, expectedExitCode = 0 }) {
   const result = spawnSync(command, args, {
     cwd,
     env,
@@ -117,7 +191,7 @@ function run(command, args, { cwd, env, timeout = 60000 }) {
     windowsHide: true,
     stdio: ['ignore', 'pipe', 'pipe'],
   });
-  if (result.error || result.status !== 0) {
+  if (result.error || result.status !== expectedExitCode) {
     const reason = result.error
       ? result.error.message
       : `exit ${result.status}, signal ${result.signal || 'none'}`;
@@ -221,13 +295,81 @@ function runMatrix(packageRoot, variant, tempRoot, env, reference) {
           { cwd: projectDir, env }
         );
         files += verifyInstallation(projectDir, { ...reference, packs: selection.packs, tools });
-        if (tools.length === allTools.length) {
-          const output = run(process.execPath, [
+        const expectedExitCode = 0;
+        const diagnosis = run(
+          process.execPath,
+          [
             path.join(packageRoot, 'tools', 'cli', 'bmad-plus-cli.js'),
-            'update-check', '--offline', '--json', '--directory', projectDir,
-          ], { cwd: projectDir, env });
+            'doctor',
+            '--json',
+            '--directory',
+            projectDir,
+          ],
+          { cwd: projectDir, env, expectedExitCode }
+        );
+        verifyDiagnostics(JSON.parse(diagnosis), {
+          packs: selection.packs,
+          tools,
+          derived: reference.derived,
+          variant,
+        });
+        if (selection.packs.includes('dev-studio')) {
+          const list = JSON.parse(
+            run(
+              process.execPath,
+              [
+                path.join(packageRoot, 'tools/cli/bmad-plus-cli.js'),
+                'studio',
+                'list',
+                '--directory',
+                projectDir,
+                '--json',
+              ],
+              { cwd: projectDir, env }
+            )
+          );
+          assert.equal(list.workflows.length, reference.derived.packs['dev-studio'].workflowCount);
+          const prepared = JSON.parse(
+            run(
+              process.execPath,
+              [
+                path.join(packageRoot, 'tools/cli/bmad-plus-cli.js'),
+                'studio',
+                'prepare',
+                'create-ux-design',
+                '--request',
+                'Design the sign-in flow',
+                '--directory',
+                projectDir,
+                '--json',
+              ],
+              { cwd: projectDir, env }
+            )
+          );
+          assert.equal(prepared.status, 'ready');
+          assert.equal(prepared.executed, false);
+          assert(prepared.instructions.some((item) => item.path.endsWith('/create-ux-design.md')));
+          assert(!fs.existsSync(path.join(projectDir, prepared.outputPath)));
+        }
+        if (tools.length === allTools.length) {
+          const output = run(
+            process.execPath,
+            [
+              path.join(packageRoot, 'tools', 'cli', 'bmad-plus-cli.js'),
+              'update-check',
+              '--offline',
+              '--json',
+              '--directory',
+              projectDir,
+            ],
+            { cwd: projectDir, env }
+          );
           const checked = JSON.parse(output);
-          assert.equal(checked.status, 'unknown', 'Offline check must not claim the latest release');
+          assert.equal(
+            checked.status,
+            'unknown',
+            'Offline check must not claim the latest release'
+          );
           assert.equal(checked.updateAvailable, null);
           assert.equal(checked.canAutoApply, false);
         }
@@ -271,9 +413,19 @@ function main() {
     };
     const source = runMatrix(REPO_ROOT, 'source', tempRoot, env, reference);
     const packageRoot = packAndExtract(tempRoot, env);
+    const { checkPythonDelivery } = require('./pack-delivery');
+    const { loadRegistry } = require('./generate');
+    assert.deepEqual(
+      checkPythonDelivery(loadRegistry(), {
+        packageRoot,
+        packageJson: JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8')),
+      }),
+      [],
+      'Declared Python resources must exist in the real npm archive'
+    );
     const packaged = runMatrix(packageRoot, 'npm', tempRoot, env, reference);
     console.log(
-      `Install contract passed: ${source.installations + packaged.installations} installs, ${source.files + packaged.files} files compared (source + npm without registry.yaml).`
+      `Install contract passed: ${source.installations + packaged.installations} installs and doctor JSON reports, ${source.files + packaged.files} files compared (source + npm without registry.yaml).`
     );
     return 0;
   } finally {