bmad-plus 0.13.0 → 0.16.0

package/tools/cli/lib/installation-health.js

@@ -0,0 +1,366 @@
+/** Read-only by default; optional Python import probes never provision or repair. */
+const fs = require('node:fs');
+const path = require('node:path');
+const semver = require('semver');
+const { DERIVED } = require('./packs');
+const { readInstallManifest } = require('./install-manifest');
+const { inventoryOf, collectManagedFiles, MANIFEST } = require('./update-transaction');
+const { fileHash } = require('./pack-copy');
+const { contentHash } = require('./installed-adapters');
+const {
+  safeTarget,
+  GENERATED_MARKER,
+  USER_CONFIG_MARKER,
+} = require('../../build/generate-adapters');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '../../..');
+
+function inspectFile(root, file) {
+  try {
+    return { state: 'present', bytes: fs.readFileSync(safeTarget(root, file)) };
+  } catch (error) {
+    return { state: error.code === 'ENOENT' ? 'missing' : 'unreadable' };
+  }
+}
+
+function collectInstallationHealth({
+  projectDir = process.cwd(),
+  packageRoot = PACKAGE_ROOT,
+  cliVersion = require('../../../package.json').version,
+  nodeVersion = process.versions.node,
+  verifyPython = false,
+  pythonRunner,
+} = {}) {
+  projectDir = path.resolve(projectDir);
+  const report = {
+    schemaVersion: 1,
+    projectDir,
+    status: 'ok',
+    versions: { installed: null, cli: cliVersion, published: null },
+    inventory: { status: 'unknown', trackedFiles: 0 },
+    packs: [],
+    integrations: [],
+    processExecution: DERIVED.diagnostics.processExecution
+      ? {
+          ...DERIVED.diagnostics.processExecution,
+          availability: 'not-probed',
+        }
+      : null,
+    runtimes: [],
+    checks: [],
+    summary: { passed: 0, warnings: 0, errors: 0 },
+  };
+  function check(code, status, message, extra = {}) {
+    report.checks.push({ code, status, message, ...extra });
+  }
+  function finish() {
+    for (const entry of report.checks) {
+      report.summary[
+        entry.status === 'pass' ? 'passed' : entry.status === 'warning' ? 'warnings' : 'errors'
+      ]++;
+    }
+    report.status = report.summary.errors ? 'error' : report.summary.warnings ? 'warning' : 'ok';
+    return report;
+  }
+
+  const manifestFile = inspectFile(projectDir, MANIFEST);
+  if (manifestFile.state !== 'present') {
+    check(
+      manifestFile.state === 'missing' ? 'installation.missing' : 'manifest.unreadable',
+      'error',
+      manifestFile.state === 'missing'
+        ? 'BMAD+ is not installed in this directory.'
+        : 'Installation manifest cannot be read safely.',
+      { path: MANIFEST }
+    );
+    return finish();
+  }
+  let manifest;
+  try {
+    manifest = readInstallManifest(safeTarget(projectDir, MANIFEST));
+  } catch (error) {
+    check('manifest.invalid', 'error', 'Invalid installation manifest: ' + error.message, {
+      path: MANIFEST,
+    });
+    return finish();
+  }
+  report.versions.installed = manifest.version;
+  check('manifest.valid', 'pass', 'Manifest found: v' + manifest.version);
+  check(
+    'version.cli',
+    manifest.version === cliVersion ? 'pass' : 'warning',
+    manifest.version === cliVersion
+      ? 'Installed and executing CLI versions match.'
+      : 'Version mismatch: installed v' + manifest.version + ', executing CLI v' + cliVersion + '.'
+  );
+
+  const selectedPacks = [...new Set(manifest.packs)];
+  const validPacks = selectedPacks.filter((id) => Object.hasOwn(DERIVED.packs, id));
+  for (const id of selectedPacks) {
+    if (!validPacks.includes(id))
+      check('pack.unknown', 'error', 'Unknown installed pack: ' + id, { pack: id });
+  }
+  if (!selectedPacks.includes('core'))
+    check('pack.core-missing', 'error', 'The required Core pack is not selected.');
+
+  if (selectedPacks.includes('dev-studio')) {
+    try {
+      const studio = require('./studio');
+      const resolved = studio.validatePack(studio.installedPack(projectDir));
+      studio.resolveConfig(projectDir);
+      check(
+        'studio.resources',
+        'pass',
+        `Dev Studio: ${resolved.catalog.workflows.length} routes and ${resolved.resources.length} resources resolved; host execution is not verified.`
+      );
+    } catch (error) {
+      check(
+        'studio.resources',
+        'error',
+        'Dev Studio cannot prepare its workflows: ' + error.message,
+        { path: '.agents/skills/pack-dev-studio' }
+      );
+    }
+  }
+
+  const inventory = inventoryOf(manifest);
+  const validInventory =
+    inventory &&
+    Object.values(inventory).every((hash) => typeof hash === 'string') &&
+    typeof manifest.fileInventory.complete === 'boolean';
+  report.inventory.status =
+    manifest.fileInventory === undefined
+      ? 'legacy'
+      : !validInventory
+        ? 'invalid'
+        : manifest.fileInventory.complete
+          ? 'complete'
+          : 'incomplete';
+  const owned = validInventory ? inventory : {};
+  report.inventory.trackedFiles = Object.keys(owned).length;
+
+  const expectedFiles = new Set(['_bmad/module.yaml', '_bmad/module-help.csv']);
+  for (const id of validPacks) {
+    const pack = DERIVED.packs[id];
+    report.packs.push({ id, runtimes: pack.runtimes, requiredResources: pack.requiredResources });
+    for (const file of pack.requiredResources) expectedFiles.add(file);
+  }
+  // Check delivery against the executing package, even if a manifest omits a file.
+  try {
+    for (const { file } of collectManagedFiles({ projectDir, packageRoot, packs: validPacks }))
+      expectedFiles.add(file);
+  } catch (error) {
+    check('package.unreadable', 'error', 'Cannot inspect the executing package: ' + error.message);
+  }
+  const resources = new Set([...expectedFiles, ...Object.keys(owned)]);
+  for (const file of [...resources].sort()) {
+    if (!Object.hasOwn(owned, file) && report.inventory.status === 'complete')
+      report.inventory.status = 'incomplete';
+    const observed = inspectFile(projectDir, file);
+    if (observed.state !== 'present') {
+      check(
+        'file.' + observed.state,
+        'error',
+        observed.state === 'missing'
+          ? 'Missing required file: ' + file
+          : 'File cannot be read safely: ' + file,
+        { path: file }
+      );
+    } else if (Object.hasOwn(owned, file)) {
+      const unchanged = fileHash(observed.bytes) === owned[file];
+      check(
+        unchanged ? 'file.unchanged' : 'file.modified',
+        unchanged ? 'pass' : 'warning',
+        unchanged
+          ? 'Managed file unchanged.'
+          : 'Managed file modified locally; review before updating.',
+        { path: file }
+      );
+    } else {
+      check('file.unowned', 'warning', 'File present without a recorded ownership hash.', {
+        path: file,
+      });
+    }
+  }
+  if (manifest.fileInventory?.complete && report.inventory.status === 'incomplete') {
+    check(
+      'inventory.omissions',
+      'warning',
+      'Inventory claims completeness but omits expected files.'
+    );
+  }
+  check(
+    'inventory.' + report.inventory.status,
+    report.inventory.status === 'complete'
+      ? 'pass'
+      : report.inventory.status === 'invalid'
+        ? 'error'
+        : 'warning',
+    'File ownership inventory: ' + report.inventory.status + '.'
+  );
+  const config = inspectFile(projectDir, '_bmad/config.yaml');
+  check(
+    'config.' + config.state,
+    config.state === 'present' ? 'pass' : 'error',
+    config.state === 'present'
+      ? 'Project configuration present.'
+      : 'Project configuration missing or unreadable.',
+    { path: '_bmad/config.yaml' }
+  );
+
+  const contract = DERIVED.diagnostics;
+  const declaredTools = Object.keys(contract.integrations);
+  let selectedTools = [];
+  if (manifest.ides === undefined) {
+    selectedTools = declaredTools.filter(
+      (tool) =>
+        inspectFile(projectDir, contract.integrations[tool].instructionFile).state !== 'missing'
+    );
+    check(
+      'integrations.legacy',
+      'warning',
+      'IDE selection was not recorded; existing adapter paths were inspected.'
+    );
+  } else if (
+    !Array.isArray(manifest.ides) ||
+    manifest.ides.some((id) => typeof id !== 'string' || !declaredTools.includes(id))
+  ) {
+    check(
+      'integrations.invalid',
+      'error',
+      'Manifest IDE selection contains invalid or unknown targets.'
+    );
+  } else selectedTools = [...new Set(manifest.ides)];
+
+  const adapterPaths =
+    selectedTools.length || manifest.ides === undefined
+      ? [
+          ...new Set([
+            DERIVED.targets.spine,
+            ...selectedTools.map((tool) => contract.integrations[tool].instructionFile),
+          ]),
+        ]
+      : [];
+  const ownership = new Map();
+  const hashes = manifest.adapterHashes;
+  const validHashes =
+    hashes === undefined ||
+    (hashes &&
+      typeof hashes === 'object' &&
+      !Array.isArray(hashes) &&
+      Object.entries(hashes).every(
+        ([file, hash]) =>
+          [DERIVED.targets.spine, ...DERIVED.targets.adapters.map((entry) => entry.file)].includes(
+            file
+          ) &&
+          typeof hash === 'string' &&
+          /^[a-f0-9]{64}$/.test(hash)
+      ));
+  if (!validHashes) check('adapters.invalid', 'error', 'Adapter ownership hashes are invalid.');
+  for (const file of adapterPaths) {
+    const observed = inspectFile(projectDir, file);
+    let state = observed.state;
+    if (state === 'present') {
+      const text = observed.bytes.toString('utf8');
+      const previous = validHashes && hashes && Object.hasOwn(hashes, file) ? hashes[file] : null;
+      state =
+        text.includes(GENERATED_MARKER) && !text.includes(USER_CONFIG_MARKER)
+          ? 'adopted'
+          : !previous || !text.includes(USER_CONFIG_MARKER)
+            ? 'unowned'
+            : contentHash(text) === previous
+              ? 'unchanged'
+              : 'modified';
+    }
+    ownership.set(file, state);
+    check(
+      'adapter.' + state,
+      ['missing', 'unreadable'].includes(state)
+        ? 'error'
+        : state === 'unchanged'
+          ? 'pass'
+          : 'warning',
+      'Instruction file: ' + state + '.',
+      { path: file }
+    );
+  }
+  report.integrations = selectedTools.map((tool) => ({
+    tool,
+    ...contract.integrations[tool],
+    ownership: ownership.get(contract.integrations[tool].instructionFile),
+    hostVerified: false,
+  }));
+
+  const nodeMinimum = contract.runtimeMinimums.node;
+  const nodeReady = Boolean(semver.valid(nodeVersion) && semver.gte(nodeVersion, nodeMinimum));
+  report.runtimes.push({
+    runtime: 'node',
+    minimum: nodeMinimum,
+    version: nodeVersion,
+    status: nodeReady ? 'verified' : 'unsupported',
+  });
+  check(
+    'runtime.node',
+    nodeReady ? 'pass' : 'error',
+    'Executing Node.js ' + nodeVersion + '; minimum ' + nodeMinimum + '.'
+  );
+  for (const id of validPacks.filter((pack) => DERIVED.packs[pack].runtimes.includes('python'))) {
+    const requirements = DERIVED.pythonPacks[id].requirements.join('/');
+    const delivery = inspectFile(packageRoot, requirements).state;
+    const environmentFile = '.bmad/venv/' + id + '/pyvenv.cfg';
+    const environment = inspectFile(projectDir, environmentFile).state;
+    const runtime = {
+      runtime: 'python',
+      pack: id,
+      minimum: contract.runtimeMinimums.python,
+      requirements,
+      packageRequirements: delivery,
+      environment,
+      imports: 'not-verified',
+    };
+    report.runtimes.push(runtime);
+    check(
+      'runtime.requirements',
+      delivery === 'present' ? 'pass' : 'error',
+      delivery === 'present'
+        ? 'Python requirements are available in the executing package.'
+        : 'Python requirements are missing or unreadable in the executing package.',
+      { pack: id, path: requirements, scope: 'package' }
+    );
+    if (verifyPython) {
+      const { probePythonRuntime } = require('./python-health');
+      const probe = probePythonRuntime({
+        projectDir,
+        packId: id,
+        minimum: contract.runtimeMinimums.python,
+        verifyModules: DERIVED.pythonPacks[id].verifyModules,
+        runner: pythonRunner,
+      });
+      Object.assign(runtime, probe);
+      check(
+        'runtime.python-probe',
+        probe.status === 'verified' ? 'pass' : 'warning',
+        probe.message +
+          (probe.status === 'verified'
+            ? ''
+            : ' Use bmad-plus install --provision-python to provision selected Python packs.'),
+        {
+          pack: id,
+          path: environmentFile,
+        }
+      );
+    } else {
+      check(
+        'runtime.python-unverified',
+        'warning',
+        'Python environment ' +
+          environment +
+          '; interpreter version and imports have not been executed. Use doctor --verify-python to probe them.',
+        { pack: id, path: environmentFile }
+      );
+    }
+  }
+  return finish();
+}
+
+module.exports = { collectInstallationHealth };

package/tools/cli/lib/memory-outcomes.js

@@ -0,0 +1,293 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const nexus = require('./nexus');
+const store = require('./memory-store');
+
+const OUTCOMES = '.bmad/memory/outcomes.ndjson';
+const BOOST = 0.25;
+const digest = (value) =>
+  crypto
+    .createHash('sha256')
+    .update(typeof value === 'string' ? value : JSON.stringify(value))
+    .digest('hex');
+const equal = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+function requiredText(value, label, maximum = 1000) {
+  if (typeof value !== 'string' || !value.trim() || value.length > maximum)
+    throw new Error(label + ' must be non-empty bounded text.');
+  return value;
+}
+function scopePath(value) {
+  if (
+    typeof value !== 'string' ||
+    !value ||
+    value.includes('\\') ||
+    value.startsWith('/') ||
+    value.includes(':') ||
+    value.split('/').some((p) => !p || p === '.' || p === '..')
+  ) {
+    throw new Error('Outcome scope must be a normalized relative path.');
+  }
+  return value;
+}
+function within(child, parent) {
+  return child === parent || child.startsWith(parent + '/');
+}
+function overlaps(a, b) {
+  return a.some((left) => b.some((right) => within(left, right) || within(right, left)));
+}
+function scopes(values) {
+  if (!Array.isArray(values) || !values.length || values.length > 30)
+    throw new Error('An explicit non-empty project scope is required.');
+  return [...new Set(values.map(scopePath))].sort();
+}
+function sourceSection(baseDir, input) {
+  if (
+    !input ||
+    !/^(?:\.agents|\.bmad)\/memory\/(?:decisions|lessons|patterns)\.md$/.test(input.file)
+  )
+    throw new Error(
+      'Outcome memory source must be a project decisions, lessons or patterns Markdown file.'
+    );
+  const heading = requiredText(input.heading, 'Memory heading', 300);
+  const sections = require('./memory-journal')._internal.splitSections(
+    store.readText(baseDir, input.file),
+    input.file
+  );
+  const matches = sections.filter((section) => section.heading === heading);
+  if (matches.length !== 1) throw new Error('Memory heading must identify exactly one section.');
+  const text = (matches[0].heading + '\n' + matches[0].text).trim();
+  return { file: input.file, heading, textSha256: digest(text) };
+}
+
+/** Read-only adapter: Nexus owns the actual verification and freshness policy. */
+function acceptedSource(baseDir, runId, taskId) {
+  const run = nexus.inspectRun(baseDir, runId);
+  if (run.lock || run.recoveryLock)
+    throw new Error(
+      'Nexus state is being written or recovered; retry observation after its owner finishes.'
+    );
+  const task = run.tasks.find((item) => item.id === taskId);
+  const observation = run.observations.find((item) => item.taskId === taskId);
+  const attempt = task?.attempts.at(-1);
+  if (
+    !task ||
+    task.integration !== 'accepted' ||
+    !observation?.evidenceEligible ||
+    observation.stale ||
+    attempt?.execution !== 'completed' ||
+    attempt.verification.status !== 'passed'
+  ) {
+    throw new Error(
+      'Outcome source is not an accepted task with current independently verified evidence.'
+    );
+  }
+  if (
+    task.integrationReceipt?.attemptId !== attempt.id ||
+    !equal(task.integrationReceipt.artifactHashes, attempt.verification.artifactHashes)
+  ) {
+    throw new Error('Nexus acceptance does not bind the current attempt and artifacts.');
+  }
+  const definition = run.plan.tasks.find((item) => item.id === taskId);
+  return {
+    kind: 'nexus',
+    runId,
+    taskId,
+    attemptId: attempt.id,
+    verificationId: attempt.verification.id,
+    verificationSha256: digest(attempt.verification),
+    acceptedAt: task.acceptedAt,
+    artifactHashes: task.integrationReceipt.artifactHashes,
+    resourceHashes: definition.resourceHashes,
+    scope: definition.scope,
+    objective: definition.objective,
+    baseline: attempt.baseline || null,
+  };
+}
+
+function readOutcomes(baseDir) {
+  const text = store.readText(baseDir, OUTCOMES, { missing: true });
+  if (text === null) return [];
+  if (text && !text.endsWith('\n'))
+    throw new Error('Outcome store has an incomplete final record.');
+  const records = text
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+  if (records.length > 1000) throw new Error('Outcome store exceeds 1000 records.');
+  const seen = new Set();
+  const attempts = new Set();
+  for (const record of records) {
+    const { id, ...body } = record;
+    if (
+      body.schemaVersion !== 1 ||
+      body.kind !== 'accepted-outcome' ||
+      id !== digest(body) ||
+      seen.has(id)
+    )
+      throw new Error('Outcome receipt integrity or uniqueness check failed.');
+    if (
+      !Array.isArray(record.supersedes) ||
+      !Array.isArray(record.contradicts) ||
+      [...record.supersedes, ...record.contradicts].some((ref) => !seen.has(ref))
+    )
+      throw new Error('Outcome relationships must identify earlier receipts.');
+    const attemptKey = [record.source?.runId, record.source?.taskId, record.source?.attemptId].join(
+      '\0'
+    );
+    if (!record.source?.attemptId || attempts.has(attemptKey))
+      throw new Error('Duplicate or missing outcome attempt identity.');
+    attempts.add(attemptKey);
+    seen.add(id);
+  }
+  return records;
+}
+
+function observeOutcome(baseDir, input, { now } = {}) {
+  if (!input || typeof input !== 'object') throw new Error('Outcome input is required.');
+  if (typeof now !== 'string' || !Number.isFinite(Date.parse(now)))
+    throw new Error('Outcome timestamp must be injected as an ISO string.');
+  return store.withMemoryLock(baseDir, () => {
+    const records = readOutcomes(baseDir);
+    const source = acceptedSource(
+      baseDir,
+      requiredText(input.runId, 'Run ID'),
+      requiredText(input.taskId, 'Task ID')
+    );
+    if (
+      records.some(
+        (record) =>
+          record.source.runId === source.runId &&
+          record.source.taskId === source.taskId &&
+          record.source.attemptId === source.attemptId
+      )
+    )
+      throw new Error('Duplicate outcome: this task attempt already supplied a receipt.');
+    const memory = sourceSection(baseDir, input.memory);
+    const scope = scopes(input.scope);
+    if (scope.some((item) => !source.scope.some((parent) => within(item, parent))))
+      throw new Error('Outcome scope exceeds the accepted task scope.');
+    const relationships = {};
+    for (const key of ['supersedes', 'contradicts']) {
+      const values = input[key] || [];
+      if (!Array.isArray(values) || values.length > 30 || new Set(values).size !== values.length)
+        throw new Error('Outcome relationships must be a unique bounded receipt-ID list.');
+      for (const id of values) {
+        const prior = records.find((record) => record.id === id);
+        if (!prior || !overlaps(scope, prior.scope))
+          throw new Error('Related outcome must exist in the same applicable project scope.');
+      }
+      relationships[key] = [...values].sort();
+    }
+    if (relationships.supersedes.some((id) => relationships.contradicts.includes(id)))
+      throw new Error('A receipt cannot be both superseded and contradicted.');
+    const body = {
+      schemaVersion: 1,
+      kind: 'accepted-outcome',
+      ts: now,
+      memory,
+      scope,
+      source,
+      interpretation: requiredText(input.interpretation, 'Lesson interpretation', 2000),
+      verification: { status: 'passed', acceptance: 'accepted', lessonCausality: 'unmeasured' },
+      ...relationships,
+    };
+    // Re-read after loading relationships/Markdown; do not persist a torn source observation.
+    if (
+      !equal(source, acceptedSource(baseDir, source.runId, source.taskId)) ||
+      !equal(memory, sourceSection(baseDir, input.memory))
+    )
+      throw new Error('Outcome sources changed while being observed.');
+    if (records.length >= 1000) throw new Error('Outcome store is full; archive it explicitly.');
+    return store.appendRecord(baseDir, OUTCOMES, { id: digest(body), ...body });
+  });
+}
+
+function inspectOutcomes(baseDir, { contextScope } = {}) {
+  const selectedScope = contextScope === undefined ? null : scopes(contextScope);
+  const records = readOutcomes(baseDir);
+  const superseded = new Set(records.flatMap((record) => record.supersedes));
+  const contradictory = new Set();
+  for (const record of records.filter((record) => !superseded.has(record.id))) {
+    for (const other of record.contradicts) {
+      if (!superseded.has(other)) {
+        contradictory.add(record.id);
+        contradictory.add(other);
+      }
+    }
+  }
+  const conflictingAnchors = new Set(
+    records
+      .filter((record) => contradictory.has(record.id))
+      .map((record) => record.memory.file + '\0' + record.memory.heading)
+  );
+  return records.map((record) => {
+    let reason = null;
+    if (superseded.has(record.id)) reason = 'superseded';
+    else if (conflictingAnchors.has(record.memory.file + '\0' + record.memory.heading))
+      reason = 'contradictory';
+    else if (selectedScope && !overlaps(record.scope, selectedScope))
+      reason = 'outside-query-scope';
+    else {
+      try {
+        if (!equal(sourceSection(baseDir, record.memory), record.memory))
+          reason = 'stale-memory-section';
+        else if (
+          !equal(acceptedSource(baseDir, record.source.runId, record.source.taskId), record.source)
+        )
+          reason = 'stale-outcome-source';
+      } catch (error) {
+        reason = 'unavailable-or-ineligible-source: ' + error.message;
+      }
+    }
+    return { ...record, eligible: reason === null, reason };
+  });
+}
+
+function rankWithEvidence(baseDir, candidates, { contextScope } = {}) {
+  const status = inspectOutcomes(baseDir, { contextScope: scopes(contextScope) });
+  const key = (value) => value.file + '\0' + value.heading;
+  const results = [];
+  for (const entry of candidates) {
+    const matching =
+      entry.kind === 'note'
+        ? status.filter(
+            (record) => key(record.memory) === key({ file: entry.sourceFile, heading: entry.ref })
+          )
+        : [];
+    if (!matching.length) {
+      results.push({ ...entry, evidence: { status: 'unverified', receiptIds: [], boost: 0 } });
+      continue;
+    }
+    // A stale, contradicted or superseded anchor must not silently fall back to an authoritative note.
+    const eligible = matching.filter(
+      (record) => record.eligible && record.memory.textSha256 === digest(entry.text)
+    );
+    if (!eligible.length) continue;
+    const reward = require('./memory-journal').computeReward({ acceptance: true });
+    results.push({
+      ...entry,
+      lexicalScore: entry.score,
+      score: entry.score * (1 + BOOST * reward),
+      evidence: {
+        status: 'accepted-current',
+        receiptIds: eligible.map((record) => record.id),
+        reward,
+        boost: BOOST,
+        lessonCausality: 'unmeasured',
+      },
+    });
+  }
+  return results;
+}
+
+module.exports = {
+  observeOutcome,
+  inspectOutcomes,
+  readOutcomes,
+  rankWithEvidence,
+  acceptedSource,
+  OUTCOMES,
+  BOOST,
+};