scene-capability-engine 3.3.3 → 3.3.5

package/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.3.5] - 2026-02-22
+
+### Added
+- Capability matrix execution assets for Spec 117:
+  - `scripts/symbol-evidence-locate.js`
+  - `scripts/failure-attribution-repair.js`
+  - `scripts/capability-mapping-report.js`
+- New machine-readable contracts and examples under `docs/agent-runtime/`:
+  - `symbol-evidence.schema.json`
+  - `failure-taxonomy-baseline.json`
+  - `capability-mapping-report.schema.json`
+  - `agent-result-summary-contract.schema.json`
+- End-to-end capability matrix runbook:
+  - `docs/sce-capability-matrix-e2e-example.md`
+
+### Changed
+- Orchestration merge governance now enforces sub-agent result summary contract and blocks merge on invalid summaries, failed tests, or unresolved conflict issues when policy requires it.
+- `bootstrap-prompt-builder` now instructs sub-agents to emit a terminal `result_summary` JSON payload.
+- Command reference and roadmap docs now include strategy/symbol/failure/mapping entrypoints and default merge-governance behavior.
+- Core package version updated to `3.3.5`.
+
 ### Added
 - **Auto handoff default takeover hard gate + preflight-check command**: `sce auto handoff` profiles now default to release-gate preflight hard requirement (`default|moqui|enterprise`), added `sce auto handoff preflight-check` (`pass|warning|blocked` + reasons/signals/recommended commands), and `handoff run` precheck/details now exposes full runtime ui-mode pressure aggregates for machine-readable triage.
 - **Interactive runtime ui-mode telemetry closed-loop**: `interactive-customization-loop` now emits runtime policy signal streams (`interactive-runtime-signals.jsonl` global + session) with `ui_mode` violation markers; `interactive-governance-report` now ingests runtime signals by default and reports runtime/ui-mode pressure metrics + alerts; weekly ops summary/gate now carry and enforce runtime ui-mode violation signals (default `RELEASE_WEEKLY_OPS_MAX_RUNTIME_UI_MODE_VIOLATION_TOTAL=0`).

package/docs/README.md

@@ -94,6 +94,8 @@ Detailed technical documentation:
 - **[Moqui Template Core Library Playbook](moqui-template-core-library-playbook.md)** - Default-gated intake flow for absorbing Moqui capabilities into sce templates
 - **[331-poc Dual-Track Integration Guide](331-poc-dual-track-integration-guide.md)** - Handoff contract and integration playbook between 331-poc and sce
 - **[331-poc Adaptation Roadmap](331-poc-adaptation-roadmap.md)** - Ongoing sce-side adaptation backlog and rollout phases
+- **[SCE Capability Matrix Roadmap](sce-capability-matrix-roadmap.md)** - Strategy routing, symbol evidence, self-repair, ontology mapping, and multi-agent merge policy roadmap
+- **[SCE Capability Matrix E2E Example](sce-capability-matrix-e2e-example.md)** - End-to-end example from strategy decision to summary-driven merge block/allow
 - **[Handoff Profile Integration Guide](handoff-profile-integration-guide.md)** - External project intake contract for `default|moqui|enterprise` handoff profiles
 - **[Multi-Agent Coordination Guide](multi-agent-coordination-guide.md)** - Multi-agent parallel coordination for concurrent development
 - **[Troubleshooting](troubleshooting.md)** - Solutions to common problems

package/docs/agent-runtime/agent-result-summary-contract.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://scene-capability-engine.dev/contracts/agent-result-summary-contract.schema.json",
+  "title": "Agent Result Summary Contract",
+  "type": "object",
+  "required": [
+    "spec_id",
+    "changed_files",
+    "tests_run",
+    "tests_passed",
+    "risk_level",
+    "open_issues"
+  ],
+  "properties": {
+    "spec_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "changed_files": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "tests_run": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "tests_passed": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "risk_level": {
+      "type": "string",
+      "enum": [
+        "low",
+        "medium",
+        "high",
+        "unknown"
+      ]
+    },
+    "open_issues": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "additionalProperties": true
+}

package/docs/agent-runtime/agent-result-summary.sample.json

@@ -0,0 +1,11 @@
+{
+  "spec_id": "117-02-symbol-evidence-locator",
+  "changed_files": [
+    "scripts/symbol-evidence-locate.js",
+    "tests/unit/scripts/symbol-evidence-locate.test.js"
+  ],
+  "tests_run": 6,
+  "tests_passed": 6,
+  "risk_level": "low",
+  "open_issues": []
+}

package/docs/agent-runtime/capability-mapping-report.sample.json

@@ -0,0 +1,42 @@
+{
+  "mode": "capability-mapping-report",
+  "mapping_report": [
+    {
+      "change_id": "entity:Order",
+      "capability": "entity:order",
+      "mapped_templates": [
+        "scene-moqui-order-core"
+      ],
+      "ontology_status": "covered",
+      "status": "mapped"
+    },
+    {
+      "change_id": "business_rule:credit-check",
+      "capability": "rule:credit-check",
+      "mapped_templates": [],
+      "ontology_status": "gap",
+      "status": "missing_template_and_ontology_gap"
+    }
+  ],
+  "missing_capabilities": [
+    "rule:credit-check"
+  ],
+  "recommended_templates": [
+    "scene-moqui-order-core"
+  ],
+  "ontology_gaps": [
+    {
+      "change_id": "business_rule:credit-check",
+      "type": "business_rule",
+      "name": "credit-check",
+      "capability": "rule:credit-check"
+    }
+  ],
+  "summary": {
+    "total_changes": 2,
+    "mapped_changes": 1,
+    "missing_capabilities": 1,
+    "ontology_gaps": 1,
+    "coverage_percent": 50
+  }
+}

package/docs/agent-runtime/capability-mapping-report.schema.json

@@ -0,0 +1,136 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://scene-capability-engine.dev/contracts/capability-mapping-report.schema.json",
+  "title": "Capability Mapping Report Contract",
+  "type": "object",
+  "required": [
+    "mode",
+    "mapping_report",
+    "missing_capabilities",
+    "recommended_templates",
+    "ontology_gaps",
+    "summary"
+  ],
+  "properties": {
+    "mode": {
+      "const": "capability-mapping-report"
+    },
+    "mapping_report": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "change_id",
+          "capability",
+          "mapped_templates",
+          "ontology_status",
+          "status"
+        ],
+        "properties": {
+          "change_id": {
+            "type": "string"
+          },
+          "capability": {
+            "type": "string"
+          },
+          "mapped_templates": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "ontology_status": {
+            "type": "string",
+            "enum": [
+              "covered",
+              "gap"
+            ]
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "mapped",
+              "missing_template",
+              "missing_template_and_ontology_gap"
+            ]
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "missing_capabilities": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "recommended_templates": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "ontology_gaps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "change_id",
+          "type",
+          "name",
+          "capability"
+        ],
+        "properties": {
+          "change_id": {
+            "type": "string"
+          },
+          "type": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "capability": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "summary": {
+      "type": "object",
+      "required": [
+        "total_changes",
+        "mapped_changes",
+        "missing_capabilities",
+        "ontology_gaps",
+        "coverage_percent"
+      ],
+      "properties": {
+        "total_changes": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "mapped_changes": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "missing_capabilities": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "ontology_gaps": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "coverage_percent": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 100
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/docs/agent-runtime/failure-taxonomy-baseline.json

@@ -0,0 +1,99 @@
+{
+  "version": "1.0.0",
+  "default_category": "unknown",
+  "categories": [
+    {
+      "id": "rate_limit",
+      "repairable": true,
+      "patterns": [
+        "429",
+        "too many requests",
+        "rate limit",
+        "retry after"
+      ],
+      "default_actions": [
+        "reduce parallelism and retry with backoff",
+        "delay launch window before next execution"
+      ]
+    },
+    {
+      "id": "dependency",
+      "repairable": true,
+      "patterns": [
+        "cannot find module",
+        "module not found",
+        "missing dependency",
+        "no such package"
+      ],
+      "default_actions": [
+        "install or restore missing dependencies",
+        "reconcile lockfile and package manifest"
+      ]
+    },
+    {
+      "id": "compilation",
+      "repairable": true,
+      "patterns": [
+        "syntax error",
+        "type error",
+        "compile failed",
+        "build failed"
+      ],
+      "default_actions": [
+        "fix compile diagnostics at failing symbol",
+        "re-run targeted build validation"
+      ]
+    },
+    {
+      "id": "test_assertion",
+      "repairable": true,
+      "patterns": [
+        "expected",
+        "received",
+        "test suite failed",
+        "assertion"
+      ],
+      "default_actions": [
+        "inspect failing tests and related symbols",
+        "apply minimal fix and re-run failing tests only"
+      ]
+    },
+    {
+      "id": "environment",
+      "repairable": true,
+      "patterns": [
+        "permission denied",
+        "enoent",
+        "timed out",
+        "network"
+      ],
+      "default_actions": [
+        "verify runtime prerequisites",
+        "stabilize environment and re-run deterministic checks"
+      ]
+    },
+    {
+      "id": "policy_gate",
+      "repairable": false,
+      "patterns": [
+        "policy gate",
+        "governance blocked",
+        "authorization denied",
+        "approval required"
+      ],
+      "default_actions": [
+        "request required authorization or approval",
+        "switch to advisory response mode"
+      ]
+    },
+    {
+      "id": "unknown",
+      "repairable": false,
+      "patterns": [],
+      "default_actions": [
+        "collect diagnostics",
+        "escalate with failure summary"
+      ]
+    }
+  ]
+}

package/docs/agent-runtime/multi-agent-coordination-policy-baseline.json

@@ -0,0 +1,38 @@
+{
+  "version": "1.0.0",
+  "roles": {
+    "primary_agent": [
+      "goal decomposition",
+      "policy checks",
+      "final merge decision",
+      "release readiness summary"
+    ],
+    "sub_agent": [
+      "scoped implementation",
+      "targeted test execution",
+      "artifact evidence collection"
+    ]
+  },
+  "parallelism": {
+    "default_max_parallel": 3,
+    "adaptive_on_rate_limit": true,
+    "parallel_floor": 1,
+    "cooldown_ms": 45000
+  },
+  "coordination_rules": {
+    "require_scope_manifest": true,
+    "require_result_summary": true,
+    "block_merge_on_failed_tests": true,
+    "block_merge_on_unresolved_conflicts": true
+  },
+  "result_summary_contract": {
+    "required_fields": [
+      "spec_id",
+      "changed_files",
+      "tests_run",
+      "tests_passed",
+      "risk_level",
+      "open_issues"
+    ]
+  }
+}

package/docs/agent-runtime/strategy-routing-policy-baseline.json

@@ -0,0 +1,24 @@
+{
+  "version": "1.0.0",
+  "decision_actions": [
+    "answer_only",
+    "code_change",
+    "code_fix",
+    "rollback"
+  ],
+  "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,
+  "notes": [
+    "default strategy is conservative and evidence-first",
+    "high-risk failures prefer rollback before iterative repair"
+  ]
+}

package/docs/agent-runtime/symbol-evidence.sample.json

@@ -0,0 +1,34 @@
+{
+  "mode": "symbol-evidence-locate",
+  "query": "approve order",
+  "hits": [
+    {
+      "file": "src/order-service.js",
+      "line": 42,
+      "snippet": "function approveOrder(orderId, actorId) {",
+      "symbol": "approveOrder",
+      "score": 0.92,
+      "source": "symbol-heuristic"
+    },
+    {
+      "file": "src/order-controller.js",
+      "line": 18,
+      "snippet": "const result = orderService.approveOrder(orderId, user.id);",
+      "symbol": "approveOrder",
+      "score": 0.81,
+      "source": "text-grep"
+    }
+  ],
+  "evidence": {
+    "confidence": "high",
+    "reliable": true,
+    "fallback_action": "allow_write",
+    "advisory": "Symbol evidence is strong enough for scoped code change."
+  },
+  "summary": {
+    "searched_files": 38,
+    "candidate_files": 12,
+    "total_hits": 6,
+    "reliable_hits": 3
+  }
+}

package/docs/agent-runtime/symbol-evidence.schema.json

@@ -0,0 +1,128 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://scene-capability-engine.dev/contracts/symbol-evidence.schema.json",
+  "title": "Symbol Evidence Contract",
+  "type": "object",
+  "required": [
+    "mode",
+    "query",
+    "hits",
+    "evidence",
+    "summary"
+  ],
+  "properties": {
+    "mode": {
+      "const": "symbol-evidence-locate"
+    },
+    "query": {
+      "type": "string",
+      "minLength": 1
+    },
+    "hits": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "file",
+          "line",
+          "snippet",
+          "symbol",
+          "score",
+          "source"
+        ],
+        "properties": {
+          "file": {
+            "type": "string",
+            "minLength": 1
+          },
+          "line": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "snippet": {
+            "type": "string"
+          },
+          "symbol": {
+            "type": "string"
+          },
+          "score": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1
+          },
+          "source": {
+            "type": "string",
+            "enum": [
+              "text-grep",
+              "symbol-heuristic"
+            ]
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "evidence": {
+      "type": "object",
+      "required": [
+        "confidence",
+        "reliable",
+        "fallback_action",
+        "advisory"
+      ],
+      "properties": {
+        "confidence": {
+          "type": "string",
+          "enum": [
+            "high",
+            "medium",
+            "low",
+            "none"
+          ]
+        },
+        "reliable": {
+          "type": "boolean"
+        },
+        "fallback_action": {
+          "type": "string",
+          "enum": [
+            "allow_write",
+            "block_high_risk_write"
+          ]
+        },
+        "advisory": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "summary": {
+      "type": "object",
+      "required": [
+        "searched_files",
+        "candidate_files",
+        "total_hits",
+        "reliable_hits"
+      ],
+      "properties": {
+        "searched_files": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "candidate_files": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "total_hits": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "reliable_hits": {
+          "type": "integer",
+          "minimum": 0
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/docs/command-reference.md

@@ -267,6 +267,56 @@ sce orchestrate stop
 
 When you pass `--specs` to `sce spec bootstrap|pipeline run|gate run`, sce now defaults to this orchestrate mode automatically.
 
+### Capability Matrix Utilities
+
+```bash
+# 1) Strategy routing: decide answer_only | code_change | code_fix | rollback
+node scripts/auto-strategy-router.js \
+  --input '{"goal_type":"bugfix","requires_write":true,"test_failures":2,"changed_files":1}' \
+  --policy-file docs/agent-runtime/strategy-routing-policy-baseline.json \
+  --json
+
+# 2) Symbol evidence localization: query -> ranked file/line/symbol hits
+node scripts/symbol-evidence-locate.js \
+  --workspace . \
+  --query "approve order" \
+  --min-reliable-score 0.60 \
+  --json
+
+# Strict evidence gate: exit code 2 when no reliable hit is found
+node scripts/symbol-evidence-locate.js \
+  --workspace . \
+  --query "reconcile invoice accrual" \
+  --strict \
+  --json
+
+# 3) Failure attribution + bounded self-repair plan (single repair pass max by default)
+node scripts/failure-attribution-repair.js \
+  --error "Cannot find module @acme/order-core" \
+  --attempted-passes 0 \
+  --max-repair-passes 1 \
+  --tests "npm run test -- order-service" \
+  --json
+
+# 4) Scene template + ontology capability mapping report
+node scripts/capability-mapping-report.js \
+  --input-file .kiro/reports/capability-mapping-input.json \
+  --out .kiro/reports/capability-mapping-report.json \
+  --json
+```
+
+Contract/baseline files:
+- `docs/agent-runtime/symbol-evidence.schema.json`
+- `docs/agent-runtime/failure-taxonomy-baseline.json`
+- `docs/agent-runtime/capability-mapping-report.schema.json`
+- `docs/agent-runtime/agent-result-summary-contract.schema.json`
+- `docs/agent-runtime/multi-agent-coordination-policy-baseline.json`
+
+Multi-agent merge governance default:
+- `sce orchestrate run` loads `docs/agent-runtime/multi-agent-coordination-policy-baseline.json`.
+- When `coordination_rules.require_result_summary=true`, each sub-agent must produce `spec_id/changed_files/tests_run/tests_passed/risk_level/open_issues`.
+- Merge is blocked when summary contract is invalid, when `tests_passed < tests_run` (if enabled), or when unresolved conflict issues are present (if enabled).
+
 ### Autonomous Close-Loop Program
 
 ```bash
@@ -941,6 +991,20 @@ Release asset integrity check helper (release artifact completeness gate):
   - merges result into `RELEASE_GATE_REPORT_FILE` when provided.
 - npm alias: `npm run gate:release-asset-integrity`
 
+Release optional-asset nonempty normalize helper (pre-upload 0-byte guard):
+- `node scripts/release-asset-nonempty-normalize.js --file <path> [--file <path> ...] [--kind auto|json|jsonl|lines|text] [--note <text>] [--event <event>] [--dry-run] [--json]`:
+  - creates placeholder content when file is missing.
+  - fills placeholder content when file exists but is empty.
+  - keeps file untouched when it already has content.
+  - intended for optional release assets (`.jsonl`, `.lines`) before GitHub Release upload.
+
+Autonomous strategy router helper (answer/code/fix/rollback policy):
+- `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`
+  - returns decision: `answer_only|code_change|code_fix|rollback`.
+  - returns `reasons[]` and `next_actions[]` for auditable routing.
+  - default policy baseline: `docs/agent-runtime/strategy-routing-policy-baseline.json`.
+
 Matrix regression gate helper (script-level configurable hard gate):
 - `node scripts/matrix-regression-gate.js [--baseline <path>] [--max-regressions <n>] [--enforce] [--out <path>] [--json]`: evaluate matrix regression count from baseline compare payload (`coverage_matrix_regressions` preferred, fallback `regressions`) and enforce hard gate when enabled.
   - Default baseline input: `.kiro/reports/release-evidence/moqui-template-baseline.json`