scene-capability-engine 3.6.22 → 3.6.24

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.6.24] - 2026-03-06
+
+### Added
+- Capability inventory payload now exposes fixed homepage query metadata (`query`) and sorting metadata (`sort`).
+- Capability iteration schema and Magicball docs now define the fixed homepage inventory protocol.
+
+## [3.6.23] - 2026-03-06
+
+### Added
+- Capability inventory now applies a default homepage sort: blocked scenes first, then triad-gap priority, then value score.
+- Magicball capability iteration docs now define the default scene inventory ordering contract.
+
 ## [3.6.22] - 2026-03-06
 
 ### Added
@@ -17,6 +29,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - New `sce capability inventory` command provides scene-level triad/readiness aggregation for homepage views.
+- Capability inventory now applies default sorting: publish-ready last, then triad-gap priority, then value score.
 - Capability catalog list/search now supports `--release-ready` and `--missing-triad` filters for pre-publish triage.
 - Magicball capability library docs now show list-level triage filter examples.
 

package/README.md

@@ -218,5 +218,5 @@ MIT. See [LICENSE](LICENSE).
 
 ---
 
-**Version**: 3.6.22  
+**Version**: 3.6.24  
 **Last Updated**: 2026-03-05

package/README.zh.md

@@ -218,5 +218,5 @@ MIT，见 [LICENSE](LICENSE)。
 
 ---
 
-**版本**：3.6.22  
+**版本**：3.6.24  
 **最后更新**：2026-03-05

package/docs/agent-runtime/capability-iteration-ui.schema.json

@@ -21,6 +21,9 @@
     },
     "registry": {
       "$ref": "#/definitions/registry"
+    },
+    "inventory": {
+      "$ref": "#/definitions/inventory"
     }
   },
   "definitions": {
@@ -654,6 +657,153 @@
         }
       },
       "additionalProperties": false
+    },
+    "inventory": {
+      "type": "object",
+      "required": [
+        "mode",
+        "generated_at",
+        "query",
+        "scene_total",
+        "scene_count",
+        "sort",
+        "scenes"
+      ],
+      "properties": {
+        "mode": {
+          "const": "capability-inventory"
+        },
+        "generated_at": {
+          "type": "string"
+        },
+        "query": {
+          "type": "object",
+          "required": [
+            "protocol_version",
+            "scene_id",
+            "limit",
+            "sample_limit",
+            "filters"
+          ],
+          "properties": {
+            "protocol_version": {
+              "type": "string"
+            },
+            "scene_id": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "limit": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "sample_limit": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "filters": {
+              "type": "object",
+              "required": [
+                "release_ready",
+                "missing_triad"
+              ],
+              "properties": {
+                "release_ready": {
+                  "type": [
+                    "boolean",
+                    "null"
+                  ]
+                },
+                "missing_triad": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false
+        },
+        "scene_total": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "scene_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "sort": {
+          "type": "object",
+          "required": [
+            "strategy",
+            "triad_priority"
+          ],
+          "properties": {
+            "strategy": {
+              "type": "string"
+            },
+            "triad_priority": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          "additionalProperties": false
+        },
+        "scenes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "scene_id",
+              "summary",
+              "source",
+              "ontology_scope",
+              "ontology_core",
+              "ontology_core_ui",
+              "release_readiness",
+              "release_readiness_ui",
+              "score_preview"
+            ],
+            "properties": {
+              "scene_id": {
+                "type": "string"
+              },
+              "summary": {
+                "type": "object"
+              },
+              "source": {
+                "type": "object"
+              },
+              "ontology_scope": {
+                "$ref": "#/definitions/ontology_scope"
+              },
+              "ontology_core": {
+                "$ref": "#/definitions/ontology_core"
+              },
+              "ontology_core_ui": {
+                "$ref": "#/definitions/ontology_core_ui"
+              },
+              "release_readiness": {
+                "type": "object"
+              },
+              "release_readiness_ui": {
+                "type": "object"
+              },
+              "score_preview": {
+                "type": "object"
+              }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
     }
   },
   "additionalProperties": false

package/docs/command-reference.md

@@ -1875,6 +1875,8 @@ sce capability inventory --json
 sce capability inventory --release-ready false --missing-triad decision_strategy --json
 ```
 
+`capability inventory` returns fixed homepage query metadata in `query` and sorting metadata in `sort`.
+
 
 Capability candidates are now evaluated against the ontology core triad by default:
 - entity + relation

package/docs/magicball-capability-iteration-api.md

@@ -177,3 +177,14 @@ sce capability register --input <template_file> --risk-level <level> --difficult
 4. `/api/capability/map`
 5. `/api/capability/register`
 
+
+## 6. Inventory 固定查询协议
+
+- `query.protocol_version`：前后端协议版本
+- `query.scene_id`：单场景盘点时使用，否则为 `null`
+- `query.limit`：场景返回上限
+- `query.sample_limit`：每个 spec 抽样任务上限
+- `query.filters.release_ready`：发布可用性过滤
+- `query.filters.missing_triad`：triad 缺口过滤
+- `sort.strategy`：默认排序策略说明
+- `sort.triad_priority`：triad 优先级数组

package/docs/magicball-capability-iteration-ui.md

@@ -192,3 +192,17 @@ sce capability register --input <template.json> --json
 - 发布页直接消费 `release_readiness.ready`
 - 若为 `false`，展示 `blockers[].reason`、`blockers[].missing`、`blockers[].remediation`
 - 默认阻断文案：`能力模板未达到发布条件`
+
+## 10. 默认排序
+
+- 先显示 `release_readiness_ui.publish_ready = false` 的 scene
+- 再按 triad 缺口优先级排序：`decision_strategy` -> `business_rules` -> `entity_relation`
+- 再按 `score_preview.value_score` 降序
+- 最后按 `scene_id` 升序
+
+## 11. 首页固定查询协议
+
+- 使用 `capability-inventory` 返回的 `query` 作为首页请求回显
+- 使用 `sort` 作为排序策略展示来源
+- 首页筛选器应直接映射：`query.filters.release_ready`、`query.filters.missing_triad`
+- 首页顶部可显示：`scene_total` / `scene_count`

package/lib/commands/capability.js

@@ -820,6 +820,45 @@ async function listCapabilityInventorySceneIds(options = {}, dependencies = {})
   return [];
 }
 
+function resolveCapabilityTriadPriority(entry) {
+  const missing = Array.isArray(entry && entry.release_readiness_ui && entry.release_readiness_ui.blocking_missing)
+    ? entry.release_readiness_ui.blocking_missing
+    : [];
+  if (missing.includes('decision_strategy')) {
+    return 0;
+  }
+  if (missing.includes('business_rules')) {
+    return 1;
+  }
+  if (missing.includes('entity_relation')) {
+    return 2;
+  }
+  return 3;
+}
+
+function sortCapabilityInventoryEntries(entries) {
+  return [...(Array.isArray(entries) ? entries : [])].sort((left, right) => {
+    const leftReady = Boolean(left && left.release_readiness_ui && left.release_readiness_ui.publish_ready);
+    const rightReady = Boolean(right && right.release_readiness_ui && right.release_readiness_ui.publish_ready);
+    if (leftReady !== rightReady) {
+      return leftReady ? 1 : -1;
+    }
+
+    const triadDelta = resolveCapabilityTriadPriority(left) - resolveCapabilityTriadPriority(right);
+    if (triadDelta !== 0) {
+      return triadDelta;
+    }
+
+    const leftValue = Number(left && left.score_preview && left.score_preview.value_score || 0);
+    const rightValue = Number(right && right.score_preview && right.score_preview.value_score || 0);
+    if (leftValue !== rightValue) {
+      return rightValue - leftValue;
+    }
+
+    return String(left && left.scene_id || '').localeCompare(String(right && right.scene_id || ''));
+  });
+}
+
 function filterCapabilityInventoryEntries(entries, options = {}) {
   const normalizedMissingTriad = normalizeText(options.missingTriad || options.missing_triad).toLowerCase();
   const releaseReadyFilter = normalizeText(options.releaseReady || options.release_ready).toLowerCase();
@@ -874,11 +913,27 @@ async function runCapabilityInventoryCommand(options = {}, dependencies = {}) {
     });
   }
 
-  const filteredScenes = filterCapabilityInventoryEntries(scenes, options);
+  const filteredScenes = sortCapabilityInventoryEntries(filterCapabilityInventoryEntries(scenes, options));
+  const releaseReadyFilterRaw = normalizeText(options.releaseReady || options.release_ready).toLowerCase();
   const payload = {
     mode: 'capability-inventory',
     generated_at: new Date().toISOString(),
+    query: {
+      protocol_version: '1.0',
+      scene_id: normalizeText(options.scene || options.sceneId || options.scene_id) || null,
+      limit: limit,
+      sample_limit: toPositiveInteger(options.sample_limit, 5),
+      filters: {
+        release_ready: releaseReadyFilterRaw ? ['1', 'true', 'yes', 'ready'].includes(releaseReadyFilterRaw) : null,
+        missing_triad: normalizeText(options.missingTriad || options.missing_triad) || null
+      }
+    },
+    scene_total: scenes.length,
     scene_count: filteredScenes.length,
+    sort: {
+      strategy: 'publish_ready -> missing_triad_priority -> value_score_desc -> scene_id',
+      triad_priority: ['decision_strategy', 'business_rules', 'entity_relation']
+    },
     scenes: filteredScenes
   };
 
@@ -1661,5 +1716,6 @@ module.exports = {
   enrichCapabilityTemplateForUi,
   buildCapabilityReleaseReadinessUi,
   filterCapabilityCatalogEntries,
-  filterCapabilityInventoryEntries
+  filterCapabilityInventoryEntries,
+  sortCapabilityInventoryEntries
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scene-capability-engine",
-  "version": "3.6.22",
+  "version": "3.6.24",
   "description": "SCE (Scene Capability Engine) - A CLI tool and npm package for spec-driven development with AI coding assistants.",
   "main": "index.js",
   "bin": {