scene-capability-engine 3.6.45 → 3.6.46

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.6.46] - 2026-03-13
+
+### Added
+- Added `scripts/npm-package-runtime-asset-check.js` and the `npm run gate:npm-runtime-assets` release gate to verify that every runtime `scripts/*.js` file is present in the npm pack dry-run payload before publish.
+- Added Spec `123-00-npm-package-runtime-asset-integrity` with requirements, design, tasks, and deliverables to formalize the npm runtime asset integrity fix.
+- Added unit coverage for runtime script discovery, pack payload parsing, missing-script detection, and pack execution failure reporting.
+
+### Fixed
+- Fixed npm package publish contents by including the root `scripts/` directory in the package `files` allowlist, so installed `sce` tarballs no longer crash on missing runtime assets such as `scripts/git-managed-gate.js`.
+- Fixed the new runtime asset gate on Windows by executing `npm pack --json --dry-run` through a shell-compatible path and raising the output buffer ceiling for large package manifests.
+
 ## [3.6.45] - 2026-03-13
 
 ### Added

package/docs/releases/README.md

@@ -9,6 +9,7 @@ This directory stores release-facing documents:
 ## Archived Versions
 
 - [Release checklist](../release-checklist.md)
+- [v3.6.46 release notes](./v3.6.46.md)
 - [v3.6.45 release notes](./v3.6.45.md)
 - [v3.6.44 release notes](./v3.6.44.md)
 - [v3.6.43 release notes](./v3.6.43.md)

package/docs/releases/v3.6.46.md

@@ -0,0 +1,23 @@
+# v3.6.46 Release Notes
+
+Release date: 2026-03-13
+
+## Highlights
+
+- Fixed the npm package publish surface so the root `scripts/` directory is included in the released tarball again.
+- Added `npm run gate:npm-runtime-assets`, which inspects `npm pack --json --dry-run` output and blocks publish if any runtime `scripts/*.js` file would be missing from the package.
+- Hardened the new gate for Windows by running `npm pack` through a shell-compatible path and increasing the command output buffer for the repository's large manifest.
+
+## Verification
+
+- `npx jest tests/unit/scripts/npm-package-runtime-asset-check.test.js --runInBand`
+- `node scripts/npm-package-runtime-asset-check.js --json`
+- `npm pack --json --dry-run`
+- Installed the packed `scene-capability-engine-3.6.46.tgz` into a clean temp project and verified:
+  - `node node_modules/scene-capability-engine/bin/scene-capability-engine.js --version`
+  - `node node_modules/scene-capability-engine/bin/scene-capability-engine.js workspace delivery-audit --json`
+
+## Release Notes
+
+- This release fixes the broken runtime asset packaging observed in `3.6.44` and `3.6.45`. The failure mode was a missing `scripts/git-managed-gate.js`, but the underlying defect affected the full root `scripts/` runtime surface.
+- For already-installed `3.6.44` or `3.6.45`, the smallest emergency patch is to restore `scripts/git-managed-gate.js` into the installed package. `3.6.46` is the proper fix and should replace those versions.

package/docs/zh/releases/README.md

@@ -9,6 +9,7 @@
 ## 历史版本归档
 
 - [发布检查清单](../release-checklist.md)
+- [v3.6.46 发布说明](./v3.6.46.md)
 - [v3.6.45 发布说明](./v3.6.45.md)
 - [v3.6.44 发布说明](./v3.6.44.md)
 - [v3.6.43 发布说明](./v3.6.43.md)

package/docs/zh/releases/v3.6.46.md

@@ -0,0 +1,23 @@
+# v3.6.46 发布说明
+
+发布日期：2026-03-13
+
+## 重点变化
+
+- 修复 npm 包发布内容，重新把根目录 `scripts/` 一并纳入 tarball，避免安装后的 `sce` 因缺少运行时脚本而崩溃。
+- 新增 `npm run gate:npm-runtime-assets`，基于 `npm pack --json --dry-run` 检查所有运行时 `scripts/*.js` 是否都会进入发布包，缺失时直接阻断发布。
+- 加固了该门禁在 Windows 下的执行路径，避免 `npm pack` 命令解析和大体积输出导致误判。
+
+## 验证
+
+- `npx jest tests/unit/scripts/npm-package-runtime-asset-check.test.js --runInBand`
+- `node scripts/npm-package-runtime-asset-check.js --json`
+- `npm pack --json --dry-run`
+- 将打出的 `scene-capability-engine-3.6.46.tgz` 安装到全新临时工程后验证：
+  - `node node_modules/scene-capability-engine/bin/scene-capability-engine.js --version`
+  - `node node_modules/scene-capability-engine/bin/scene-capability-engine.js workspace delivery-audit --json`
+
+## 发布说明
+
+- 这次补丁修复的是 `3.6.44` 与 `3.6.45` 中已经暴露的 npm 运行时缺件问题。表面报错是 `scripts/git-managed-gate.js` 缺失，但根因是整个根级 `scripts/` 运行时面没有被发布进去。
+- 对已经安装的 `3.6.44` 或 `3.6.45`，最小应急补丁是补回安装目录中的 `scripts/git-managed-gate.js`；`3.6.46` 才是完整的正式修复版本。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scene-capability-engine",
-  "version": "3.6.45",
+  "version": "3.6.46",
   "description": "SCE (Scene Capability Engine) - A CLI tool and npm package for spec-driven development with AI coding assistants.",
   "main": "index.js",
   "bin": {
@@ -10,6 +10,7 @@
   "files": [
     "bin/",
     "lib/",
+    "scripts/",
     "template/",
     "!template/.sce/tools/__pycache__/",
     "!template/.sce/tools/**/*.pyc",
@@ -37,6 +38,7 @@
     "test:interactive-flow-smoke": "node scripts/interactive-flow-smoke.js --json",
     "test:skip-audit": "node scripts/check-skip-allowlist.js",
     "test:sce-tracking": "node scripts/check-sce-tracking.js",
+    "gate:npm-runtime-assets": "node scripts/npm-package-runtime-asset-check.js --fail-on-violation",
     "test:brand-consistency": "node scripts/check-branding-consistency.js",
     "audit:steering": "node scripts/steering-content-audit.js --fail-on-error",
     "audit:state-storage": "node scripts/state-storage-tiering-audit.js",
@@ -82,7 +84,7 @@
     "gate:release-asset-integrity": "node scripts/release-asset-integrity-check.js",
     "report:release-risk-remediation": "node scripts/release-risk-remediation-bundle.js --json",
     "report:moqui-core-regression": "node scripts/moqui-core-regression-suite.js --json",
-    "prepublishOnly": "npm run test:release && npm run test:skip-audit && npm run test:sce-tracking && npm run test:brand-consistency && npm run audit:steering && npm run gate:git-managed && npm run gate:errorbook-registry-health && npm run gate:errorbook-release && npm run report:interactive-governance -- --fail-on-alert",
+    "prepublishOnly": "npm run test:release && npm run test:skip-audit && npm run test:sce-tracking && npm run gate:npm-runtime-assets && npm run test:brand-consistency && npm run audit:steering && npm run gate:git-managed && npm run gate:errorbook-registry-health && npm run gate:errorbook-release && npm run report:interactive-governance -- --fail-on-alert",
     "publish:manual": "npm publish --access public",
     "install-global": "npm install -g .",
     "uninstall-global": "npm uninstall -g scene-capability-engine"

package/scripts/auto-strategy-router.js

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function readJsonFile(filePath) {
+  const resolved = path.resolve(filePath);
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`file not found: ${filePath}`);
+  }
+  return JSON.parse(fs.readFileSync(resolved, 'utf8'));
+}
+
+function toBool(value, fallback = false) {
+  if (typeof value === 'boolean') {
+    return value;
+  }
+  if (typeof value === 'string') {
+    const lowered = value.trim().toLowerCase();
+    if (['1', 'true', 'yes', 'y', 'on'].includes(lowered)) {
+      return true;
+    }
+    if (['0', 'false', 'no', 'n', 'off'].includes(lowered)) {
+      return false;
+    }
+  }
+  return fallback;
+}
+
+function toFiniteNumber(value, fallback = 0) {
+  const num = Number(value);
+  return Number.isFinite(num) ? num : fallback;
+}
+
+function normalizeInput(input = {}) {
+  const goalTypeRaw = typeof input.goal_type === 'string' ? input.goal_type.trim().toLowerCase() : '';
+  return {
+    goal_type: goalTypeRaw || 'unknown',
+    requires_write: toBool(input.requires_write, false),
+    high_risk: toBool(input.high_risk, false),
+    last_run_failed: toBool(input.last_run_failed, false),
+    has_rollback_checkpoint: toBool(input.has_rollback_checkpoint, false),
+    test_failures: toFiniteNumber(input.test_failures, 0),
+    changed_files: toFiniteNumber(input.changed_files, 0),
+    user_explicit_answer_only: toBool(input.user_explicit_answer_only, false),
+    user_explicit_rollback: toBool(input.user_explicit_rollback, false)
+  };
+}
+
+function resolvePolicy(policy = {}) {
+  const fallback = {
+    answer_only_goal_types: ['question', 'analysis', 'explain', 'summarize'],
+    rollback_when: {
+      require_checkpoint: true,
+      require_high_risk_or_explicit: true
+    },
+    code_fix_when_tests_fail: true
+  };
+  const answerTypes = Array.isArray(policy.answer_only_goal_types)
+    ? policy.answer_only_goal_types
+      .map(item => `${item || ''}`.trim().toLowerCase())
+      .filter(Boolean)
+    : fallback.answer_only_goal_types;
+  return {
+    answer_only_goal_types: answerTypes.length > 0 ? answerTypes : fallback.answer_only_goal_types,
+    rollback_when: {
+      require_checkpoint: toBool(
+        policy.rollback_when && policy.rollback_when.require_checkpoint,
+        fallback.rollback_when.require_checkpoint
+      ),
+      require_high_risk_or_explicit: toBool(
+        policy.rollback_when && policy.rollback_when.require_high_risk_or_explicit,
+        fallback.rollback_when.require_high_risk_or_explicit
+      )
+    },
+    code_fix_when_tests_fail: toBool(policy.code_fix_when_tests_fail, fallback.code_fix_when_tests_fail)
+  };
+}
+
+function evaluateStrategy(input = {}, policyInput = {}) {
+  const payload = normalizeInput(input);
+  const policy = resolvePolicy(policyInput);
+  const reasons = [];
+  let decision = 'answer_only';
+  let confidence = 'low';
+
+  if (payload.user_explicit_answer_only) {
+    decision = 'answer_only';
+    confidence = 'high';
+    reasons.push('explicit user instruction: answer only');
+  } else if (payload.user_explicit_rollback) {
+    const checkpointOk = !policy.rollback_when.require_checkpoint || payload.has_rollback_checkpoint;
+    const riskGateOk = !policy.rollback_when.require_high_risk_or_explicit || payload.high_risk || payload.user_explicit_rollback;
+    if (checkpointOk && riskGateOk) {
+      decision = 'rollback';
+      confidence = 'high';
+      reasons.push('explicit user instruction: rollback');
+    } else {
+      decision = 'answer_only';
+      confidence = 'medium';
+      reasons.push('rollback requested but preconditions are not met');
+    }
+  } else if (
+    payload.last_run_failed
+    && payload.has_rollback_checkpoint
+    && payload.high_risk
+    && payload.changed_files > 0
+  ) {
+    decision = 'rollback';
+    confidence = 'high';
+    reasons.push('last run failed with high risk and rollback checkpoint available');
+  } else if (
+    policy.answer_only_goal_types.includes(payload.goal_type)
+    && !payload.requires_write
+  ) {
+    decision = 'answer_only';
+    confidence = 'high';
+    reasons.push(`goal_type=${payload.goal_type} with no write requirement`);
+  } else if (
+    policy.code_fix_when_tests_fail
+    && payload.test_failures > 0
+    && payload.changed_files > 0
+  ) {
+    decision = 'code_fix';
+    confidence = 'high';
+    reasons.push('tests failing after code changes, prioritize focused repair');
+  } else if (payload.requires_write || payload.goal_type === 'feature' || payload.goal_type === 'bugfix') {
+    decision = 'code_change';
+    confidence = 'medium';
+    reasons.push('write-required goal needs implementation changes');
+  } else {
+    decision = 'answer_only';
+    confidence = 'low';
+    reasons.push('insufficient signals for safe code changes');
+  }
+
+  const next_actions = [];
+  if (decision === 'rollback') {
+    next_actions.push('execute rollback to latest stable checkpoint');
+    next_actions.push('collect failure evidence before reattempt');
+  } else if (decision === 'code_fix') {
+    next_actions.push('locate failing symbols and failing tests first');
+    next_actions.push('apply minimal patch and re-run targeted tests');
+  } else if (decision === 'code_change') {
+    next_actions.push('confirm affected scope and symbol locations');
+    next_actions.push('implement change and run validation tests');
+  } else {
+    next_actions.push('answer request with evidence and constraints');
+    next_actions.push('avoid repository writes in current turn');
+  }
+
+  return {
+    mode: 'auto-strategy-router',
+    decision,
+    confidence,
+    reasons,
+    next_actions,
+    input: payload,
+    policy
+  };
+}
+
+function parseArgs(argv = []) {
+  const options = {
+    input: null,
+    inputFile: '',
+    policyFile: '',
+    json: false
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === '--input') {
+      options.input = argv[i + 1] || '';
+      i += 1;
+      continue;
+    }
+    if (token === '--input-file') {
+      options.inputFile = argv[i + 1] || '';
+      i += 1;
+      continue;
+    }
+    if (token === '--policy-file') {
+      options.policyFile = argv[i + 1] || '';
+      i += 1;
+      continue;
+    }
+    if (token === '--json') {
+      options.json = true;
+      continue;
+    }
+    if (token === '-h' || token === '--help') {
+      console.log([
+        'Usage:',
+        '  node scripts/auto-strategy-router.js --input-file <path> [--policy-file <path>] --json',
+        '  node scripts/auto-strategy-router.js --input \'{\"goal_type\":\"bugfix\",\"requires_write\":true}\' --json'
+      ].join('\n'));
+      process.exit(0);
+    }
+  }
+  return options;
+}
+
+if (require.main === module) {
+  const args = parseArgs(process.argv.slice(2));
+  let inputPayload = {};
+  let policyPayload = {};
+  if (args.inputFile) {
+    inputPayload = readJsonFile(args.inputFile);
+  } else if (args.input) {
+    inputPayload = JSON.parse(args.input);
+  }
+  if (args.policyFile) {
+    policyPayload = readJsonFile(args.policyFile);
+  }
+  const result = evaluateStrategy(inputPayload, policyPayload);
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    process.stdout.write(
+      `[auto-strategy-router] decision=${result.decision} confidence=${result.confidence} reasons=${result.reasons.join('; ')}\n`
+    );
+  }
+}
+
+module.exports = {
+  evaluateStrategy,
+  normalizeInput,
+  parseArgs,
+  resolvePolicy
+};

package/scripts/capability-mapping-report.js

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+
+function parseArgs(argv = []) {
+  const options = {
+    input: '',
+    inputFile: '',
+    changesFile: '',
+    templatesFile: '',
+    ontologyFile: '',
+    out: '',
+    json: false
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    const next = argv[index + 1];
+    if (token === '--input' && next) {
+      options.input = next;
+      index += 1;
+      continue;
+    }
+    if (token === '--input-file' && next) {
+      options.inputFile = next;
+      index += 1;
+      continue;
+    }
+    if (token === '--changes-file' && next) {
+      options.changesFile = next;
+      index += 1;
+      continue;
+    }
+    if (token === '--templates-file' && next) {
+      options.templatesFile = next;
+      index += 1;
+      continue;
+    }
+    if (token === '--ontology-file' && next) {
+      options.ontologyFile = next;
+      index += 1;
+      continue;
+    }
+    if (token === '--out' && next) {
+      options.out = next;
+      index += 1;
+      continue;
+    }
+    if (token === '--json') {
+      options.json = true;
+      continue;
+    }
+    if (token === '--help' || token === '-h') {
+      printHelpAndExit(0);
+    }
+  }
+
+  return options;
+}
+
+function printHelpAndExit(code) {
+  const lines = [
+    'Usage: node scripts/capability-mapping-report.js [options]',
+    '',
+    'Options:',
+    '  --input <json>            Inline input payload (changes/templates/ontology)',
+    '  --input-file <path>       Input JSON file (changes/templates/ontology)',
+    '  --changes-file <path>     Changes JSON file (array)',
+    '  --templates-file <path>   Template catalog JSON file (array)',
+    '  --ontology-file <path>    Ontology model JSON file',
+    '  --out <path>              Output report path',
+    '  --json                    Print JSON payload',
+    '  -h, --help                Show this help'
+  ];
+  console.log(lines.join('\n'));
+  process.exit(code);
+}
+
+async function readJsonIfExists(filePath) {
+  if (!filePath) {
+    return null;
+  }
+  const resolved = path.resolve(process.cwd(), filePath);
+  if (!(await fs.pathExists(resolved))) {
+    throw new Error(`file not found: ${filePath}`);
+  }
+  return fs.readJson(resolved);
+}
+
+function normalizeChanges(changes) {
+  const array = Array.isArray(changes) ? changes : [];
+  return array
+    .filter((item) => item && typeof item === 'object')
+    .map((item) => {
+      const type = `${item.type || item.node_type || ''}`.trim().toLowerCase();
+      const name = `${item.name || item.ref || item.id || ''}`.trim();
+      const changeId = `${item.change_id || item.id || (type && name ? `${type}:${name}` : name || type || 'unknown')}`;
+      return {
+        change_id: changeId,
+        type: type || 'unknown',
+        name: name || changeId,
+        operation: `${item.operation || item.action || 'update'}`.trim().toLowerCase()
+      };
+    });
+}
+
+function normalizeTemplates(templates) {
+  const array = Array.isArray(templates) ? templates : [];
+  return array
+    .filter((item) => item && typeof item === 'object')
+    .map((item) => ({
+      id: `${item.id || item.template_id || item.name || 'unknown-template'}`.trim(),
+      capabilities: Array.isArray(item.capabilities)
+        ? item.capabilities.map((capability) => `${capability}`.trim().toLowerCase()).filter(Boolean)
+        : []
+    }));
+}
+
+function normalizeOntology(ontology = {}) {
+  const pickNames = (values) => {
+    if (!Array.isArray(values)) {
+      return new Set();
+    }
+    return new Set(
+      values
+        .map((value) => {
+          if (typeof value === 'string') {
+            return value.trim().toLowerCase();
+          }
+          if (value && typeof value === 'object') {
+            return `${value.name || value.ref || value.id || ''}`.trim().toLowerCase();
+          }
+          return '';
+        })
+        .filter(Boolean)
+    );
+  };
+
+  return {
+    entities: pickNames(ontology.entities),
+    business_rules: pickNames(ontology.business_rules),
+    decision_strategies: pickNames(ontology.decision_strategies),
+    relations: Array.isArray(ontology.relations) ? ontology.relations : []
+  };
+}
+
+function normalizeCapability(type, name) {
+  const loweredName = `${name || ''}`.trim().toLowerCase();
+  if (!loweredName) {
+    return 'unknown:unknown';
+  }
+  if (type === 'entity') {
+    return `entity:${loweredName}`;
+  }
+  if (type === 'business_rule' || type === 'rule') {
+    return `rule:${loweredName}`;
+  }
+  if (type === 'decision_strategy' || type === 'decision') {
+    return `decision:${loweredName}`;
+  }
+  if (type === 'service') {
+    return `service:${loweredName}`;
+  }
+  if (type === 'scene') {
+    return `scene:${loweredName}`;
+  }
+  return `${type || 'unknown'}:${loweredName}`;
+}
+
+function capabilityMatches(capability, templateCapability) {
+  if (!capability || !templateCapability) {
+    return false;
+  }
+  if (templateCapability === capability) {
+    return true;
+  }
+  if (templateCapability.endsWith('*')) {
+    const prefix = templateCapability.slice(0, -1);
+    return capability.startsWith(prefix);
+  }
+  return false;
+}
+
+function findMappedTemplates(capability, templates) {
+  const mapped = [];
+  for (const template of templates) {
+    if (template.capabilities.some((item) => capabilityMatches(capability, item))) {
+      mapped.push(template.id);
+    }
+  }
+  return mapped;
+}
+
+function checkOntologyCoverage(type, name, ontology) {
+  const loweredName = `${name || ''}`.trim().toLowerCase();
+  if (!loweredName) {
+    return false;
+  }
+  if (type === 'entity') {
+    return ontology.entities.has(loweredName);
+  }
+  if (type === 'business_rule' || type === 'rule') {
+    return ontology.business_rules.has(loweredName);
+  }
+  if (type === 'decision_strategy' || type === 'decision') {
+    return ontology.decision_strategies.has(loweredName);
+  }
+  return true;
+}
+
+function buildMappingReport({ changes, templates, ontology }) {
+  const mappingReport = [];
+  const missingCapabilities = [];
+  const recommendedTemplates = new Set();
+  const ontologyGaps = [];
+
+  for (const change of changes) {
+    const capability = normalizeCapability(change.type, change.name);
+    const mappedTemplates = findMappedTemplates(capability, templates);
+    const ontologyCovered = checkOntologyCoverage(change.type, change.name, ontology);
+
+    for (const templateId of mappedTemplates) {
+      recommendedTemplates.add(templateId);
+    }
+
+    if (mappedTemplates.length === 0) {
+      missingCapabilities.push(capability);
+    }
+    if (!ontologyCovered) {
+      ontologyGaps.push({
+        change_id: change.change_id,
+        type: change.type,
+        name: change.name,
+        capability
+      });
+    }
+
+    const status = mappedTemplates.length > 0
+      ? 'mapped'
+      : (ontologyCovered ? 'missing_template' : 'missing_template_and_ontology_gap');
+
+    mappingReport.push({
+      change_id: change.change_id,
+      capability,
+      mapped_templates: mappedTemplates,
+      ontology_status: ontologyCovered ? 'covered' : 'gap',
+      status
+    });
+  }
+
+  const totalChanges = mappingReport.length;
+  const mappedChanges = mappingReport.filter((item) => item.mapped_templates.length > 0).length;
+  const coveragePercent = totalChanges === 0
+    ? 100
+    : Number(((mappedChanges / totalChanges) * 100).toFixed(2));
+
+  return {
+    mode: 'capability-mapping-report',
+    generated_at: new Date().toISOString(),
+    mapping_report: mappingReport,
+    missing_capabilities: [...new Set(missingCapabilities)],
+    recommended_templates: [...recommendedTemplates],
+    ontology_gaps: ontologyGaps,
+    summary: {
+      total_changes: totalChanges,
+      mapped_changes: mappedChanges,
+      missing_capabilities: [...new Set(missingCapabilities)].length,
+      ontology_gaps: ontologyGaps.length,
+      coverage_percent: coveragePercent
+    }
+  };
+}
+
+async function loadInput(options) {
+  const inline = options.input ? JSON.parse(options.input) : null;
+  const inputFilePayload = options.inputFile ? await readJsonIfExists(options.inputFile) : null;
+  const changesPayload = options.changesFile ? await readJsonIfExists(options.changesFile) : null;
+  const templatesPayload = options.templatesFile ? await readJsonIfExists(options.templatesFile) : null;
+  const ontologyPayload = options.ontologyFile ? await readJsonIfExists(options.ontologyFile) : null;
+
+  const source = inline || inputFilePayload || {};
+  const changes = normalizeChanges(
+    changesPayload || source.changes || source.change_set || source.mapping_input
+  );
+  const templates = normalizeTemplates(
+    templatesPayload || source.templates || source.template_catalog || source.scene_templates
+  );
+  const ontology = normalizeOntology(
+    ontologyPayload || source.ontology || source.ontology_model || {}
+  );
+
+  return {
+    changes,
+    templates,
+    ontology
+  };
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const input = await loadInput(options);
+  const payload = buildMappingReport(input);
+
+  if (options.out) {
+    const outPath = path.resolve(process.cwd(), options.out);
+    await fs.ensureDir(path.dirname(outPath));
+    await fs.writeJson(outPath, payload, { spaces: 2 });
+  }
+
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+  } else {
+    process.stdout.write(`capability mapping coverage=${payload.summary.coverage_percent}%\n`);
+    process.stdout.write(`missing_capabilities=${payload.summary.missing_capabilities}\n`);
+    process.stdout.write(`ontology_gaps=${payload.summary.ontology_gaps}\n`);
+  }
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    console.error(`capability-mapping-report failed: ${error.message}`);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  parseArgs,
+  normalizeChanges,
+  normalizeTemplates,
+  normalizeOntology,
+  normalizeCapability,
+  capabilityMatches,
+  findMappedTemplates,
+  checkOntologyCoverage,
+  buildMappingReport,
+  loadInput
+};