scene-capability-engine 3.3.4 → 3.3.5

package/docs/sce-capability-matrix-e2e-example.md

@@ -0,0 +1,94 @@
+# SCE Capability Matrix E2E Example
+
+This example shows one complete execution chain:
+
+`input -> strategy decision -> symbol evidence -> failure attribution -> capability mapping -> multi-agent summary merge`
+
+## 1) Input and Strategy Decision
+
+```bash
+node scripts/auto-strategy-router.js \
+  --input '{"goal_type":"bugfix","requires_write":true,"test_failures":1,"changed_files":1}' \
+  --policy-file docs/agent-runtime/strategy-routing-policy-baseline.json \
+  --json
+```
+
+Expected decision: `code_fix` with reasons and next actions.
+
+## 2) Symbol Evidence Gate
+
+```bash
+node scripts/symbol-evidence-locate.js \
+  --workspace . \
+  --query "approve order" \
+  --strict \
+  --json
+```
+
+Expected:
+- reliable evidence => `fallback_action=allow_write`
+- no reliable evidence => `fallback_action=block_high_risk_write` and exit code `2`
+
+## 3) Failure Attribution and Bounded Repair
+
+```bash
+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
+```
+
+Expected:
+- classification into `Failure_Taxonomy`
+- at most one `run_repair_pass`
+- terminal stop summary when budget is exhausted or category is non-repairable
+
+## 4) Capability Mapping (Template + Ontology)
+
+Prepare `mapping-input.json`:
+
+```json
+{
+  "changes": [
+    { "type": "entity", "name": "Order" },
+    { "type": "business_rule", "name": "credit-check" }
+  ],
+  "templates": [
+    { "id": "scene-moqui-order-core", "capabilities": ["entity:order"] }
+  ],
+  "ontology": {
+    "entities": [{ "name": "Order" }],
+    "business_rules": []
+  }
+}
+```
+
+Run report:
+
+```bash
+node scripts/capability-mapping-report.js \
+  --input-file mapping-input.json \
+  --json
+```
+
+Expected:
+- `mapping_report[]`
+- `missing_capabilities[]`
+- `recommended_templates[]`
+- `ontology_gaps[]`
+
+## 5) Multi-Agent Merge Summary Contract
+
+During `sce orchestrate run`, sub-agent completion is validated against:
+
+- `docs/agent-runtime/agent-result-summary-contract.schema.json`
+- `docs/agent-runtime/multi-agent-coordination-policy-baseline.json`
+
+If `require_result_summary=true`, merge is blocked when:
+- summary is missing/invalid
+- `tests_passed < tests_run` (when enabled)
+- unresolved conflict issues are reported (when enabled)
+
+This enforces summary-driven, auditable merge decisions.

package/docs/sce-capability-matrix-roadmap.md

@@ -0,0 +1,48 @@
+# SCE Capability Matrix Roadmap
+
+This roadmap consolidates the next capability uplift priorities for SCE and maps each item to concrete deliverables.
+
+## Priority Matrix
+
+| Capability | Current State | Gap | Next Deliverables |
+| --- | --- | --- | --- |
+| Task decomposition and strategy selection | `auto close-loop`, `orchestrate`, release gates already exist | Missing explicit machine-readable strategy router for `answer_only/code_change/rollback` | `scripts/auto-strategy-router.js` + baseline policy + command-reference integration |
+| Code retrieval and symbol-level localization | `rg`-style file search is common; orchestration has status tracking | Missing unified symbol locator contract and ranked evidence payload | add `symbol-locate` utility + evidence schema + tests |
+| Failure attribution and self-repair | retry/backoff and recovery loops already exist in multiple flows | Missing normalized root-cause taxonomy and bounded second-pass repair contract | add failure taxonomy schema + first/second-pass repair pipeline adapter |
+| Scene template and ontology mapping | strong scene + ontology stack exists (`scene lint/score/ontology`) | Missing cross-project mapping report from runtime changes to ontology/template assets | add mapping report generator and remediation queue sync |
+| Multi-agent coordination strategy | orchestrator + rate-limit adaptive controls already online | Missing explicit primary/sub-agent role policy and merge-summary contract | baseline policy + required result-summary validation in orchestration path |
+
+## Current Baseline Artifacts (This Iteration)
+
+- `scripts/auto-strategy-router.js`
+- `scripts/symbol-evidence-locate.js`
+- `scripts/failure-attribution-repair.js`
+- `scripts/capability-mapping-report.js`
+- `docs/agent-runtime/strategy-routing-policy-baseline.json`
+- `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`
+- `docs/sce-capability-matrix-e2e-example.md`
+
+## Execution Plan
+
+1. Phase 1: Strategy and safety routing
+   - ship strategy router and policy file integration in autonomous entrypoints.
+2. Phase 2: Symbol evidence pipeline
+   - provide deterministic `query -> symbols -> evidence` payload for repair and explanation flows.
+3. Phase 3: Failure attribution and bounded self-repair
+   - classify failures, apply one focused patch pass, rerun scoped tests, stop on bounded retries.
+4. Phase 4: Scene/Ontology cross-project mapping
+   - generate actionable mapping deltas from project changes to reusable scene assets.
+5. Phase 5: Multi-agent merge governance
+   - enforce result summary contract and role-based decision merge.
+
+## Success Criteria
+
+- Strategy router decision accuracy >= 90% on curated regression fixture set.
+- Symbol localization response includes at least one valid evidence hit for >= 95% supported queries.
+- Self-repair flow reduces unresolved test failures by >= 30% in bounded second-pass runs.
+- Scene/Ontology mapping report generated for every release candidate.
+- Multi-agent runs produce complete role-tagged result summary payloads for 100% completed sub-agents.

package/docs/zh/README.md

@@ -190,6 +190,15 @@
 - 主从编排与门禁增强
 - 跨轮次回归与发布治理集成
 
+### [SCE 能力矩阵路线图](../sce-capability-matrix-roadmap.md)
+**核心能力补齐路线（英文）** - 策略路由、符号证据、自修复、ontology 映射与多 agent 汇总
+- 任务策略决策闭环
+- 失败归因与有界修复
+- 跨项目能力沉淀与协同治理
+
+### [SCE 能力矩阵端到端示例](../sce-capability-matrix-e2e-example.md)
+**端到端流程示例（英文）** - 从策略决策到符号证据、失败修复、能力映射和主从摘要合并阻断
+
 ### [Handoff Profile Integration Guide](../handoff-profile-integration-guide.md)
 **外部项目接入规范（英文）** - `default|moqui|enterprise` 三档 handoff profile 契约
 - profile 默认策略与显式参数覆盖规则

package/lib/orchestrator/agent-spawner.js

@@ -248,10 +248,163 @@ class AgentSpawner extends EventEmitter {
     return new Map(this._agents);
   }
 
+  /**
+   * Resolve a structured result summary emitted by a sub-agent.
+   * The summary is extracted from captured JSON events and used by
+   * orchestration merge-governance checks.
+   *
+   * @param {string} agentId
+   * @returns {object|null}
+   */
+  getResultSummary(agentId) {
+    const agent = this._agents.get(agentId);
+    if (!agent || !Array.isArray(agent.events)) {
+      return null;
+    }
+    return this._extractResultSummaryFromEvents(agent.events);
+  }
+
   // ---------------------------------------------------------------------------
   // Private helpers
   // ---------------------------------------------------------------------------
 
+  /**
+   * Parse known summary carriers from agent JSON events.
+   * Prefers the candidate with the most contract fields.
+   *
+   * @param {object[]} events
+   * @returns {object|null}
+   * @private
+   */
+  _extractResultSummaryFromEvents(events) {
+    const candidates = [];
+    const collect = (value) => {
+      if (!value || typeof value !== 'object') {
+        return;
+      }
+      if (this._summaryCandidateFieldCount(value) > 0) {
+        candidates.push(value);
+      }
+    };
+
+    for (const event of events) {
+      if (!event || typeof event !== 'object') {
+        continue;
+      }
+      collect(event.result_summary);
+      collect(event.summary);
+      collect(event.payload && event.payload.result_summary);
+      collect(event.payload && event.payload.summary);
+      collect(event.result && event.result.summary);
+      collect(event.data && event.data.result_summary);
+      collect(event.item && event.item.result_summary);
+
+      collect(this._tryParseSummaryFromText(event.message));
+      collect(this._tryParseSummaryFromText(event.output_text));
+      collect(this._tryParseSummaryFromText(event.text));
+      collect(this._tryParseSummaryFromText(event.item && event.item.text));
+
+      const itemContent = event.item && event.item.content;
+      if (Array.isArray(itemContent)) {
+        for (const entry of itemContent) {
+          if (typeof entry === 'string') {
+            collect(this._tryParseSummaryFromText(entry));
+          } else if (entry && typeof entry === 'object') {
+            collect(entry.result_summary);
+            collect(entry.summary);
+            collect(this._tryParseSummaryFromText(entry.text));
+          }
+        }
+      }
+    }
+
+    if (candidates.length === 0) {
+      return null;
+    }
+
+    candidates.sort((left, right) =>
+      this._summaryCandidateFieldCount(right) - this._summaryCandidateFieldCount(left));
+    return { ...candidates[0] };
+  }
+
+  /**
+   * @param {object} candidate
+   * @returns {number}
+   * @private
+   */
+  _summaryCandidateFieldCount(candidate) {
+    if (!candidate || typeof candidate !== 'object') {
+      return 0;
+    }
+    const fields = [
+      'spec_id',
+      'changed_files',
+      'tests_run',
+      'tests_passed',
+      'risk_level',
+      'open_issues'
+    ];
+    let count = 0;
+    for (const field of fields) {
+      if (Object.prototype.hasOwnProperty.call(candidate, field)) {
+        count += 1;
+      }
+    }
+    return count;
+  }
+
+  /**
+   * Attempt to parse a JSON summary object from free-form text.
+   *
+   * @param {string} text
+   * @returns {object|null}
+   * @private
+   */
+  _tryParseSummaryFromText(text) {
+    if (typeof text !== 'string') {
+      return null;
+    }
+    const trimmed = text.trim();
+    if (!trimmed || !trimmed.includes('spec_id')) {
+      return null;
+    }
+
+    const candidates = [trimmed];
+    const fenced = /```json\s*([\s\S]*?)```/gi;
+    let match;
+    while ((match = fenced.exec(trimmed)) !== null) {
+      if (match[1]) {
+        candidates.push(match[1].trim());
+      }
+    }
+
+    const firstBrace = trimmed.indexOf('{');
+    const lastBrace = trimmed.lastIndexOf('}');
+    if (firstBrace >= 0 && lastBrace > firstBrace) {
+      candidates.push(trimmed.slice(firstBrace, lastBrace + 1));
+    }
+
+    for (const candidate of candidates) {
+      if (!candidate || typeof candidate !== 'string') {
+        continue;
+      }
+      try {
+        const parsed = JSON.parse(candidate);
+        if (parsed && typeof parsed === 'object') {
+          if (parsed.result_summary && typeof parsed.result_summary === 'object') {
+            return parsed.result_summary;
+          }
+          if (this._summaryCandidateFieldCount(parsed) > 0) {
+            return parsed;
+          }
+        }
+      } catch (_err) {
+        // Ignore parse failures and continue.
+      }
+    }
+    return null;
+  }
+
   /**
    * Ensure bootstrap prompt is a non-empty string before using it in spawn args.
    * @param {unknown} prompt

package/lib/orchestrator/bootstrap-prompt-builder.js

@@ -172,6 +172,9 @@ class BootstrapPromptBuilder {
       '5. Mark each task as completed (change `[ ]` or `[-]` to `[x]`) after finishing.',
       '6. Run relevant tests to verify your implementation before moving on.',
       '7. If a task fails after multiple attempts, document the issue and continue.',
+      '8. At completion, output a final JSON object named result_summary with fields:',
+      '   spec_id, changed_files, tests_run, tests_passed, risk_level, open_issues.',
+      '   Keep risk_level in: low | medium | high | unknown.',
       '',
       'Quality requirements:',
       '- All code must compile and pass linting.',