scene-capability-engine 3.3.4 → 3.3.10

package/docs/adoption-guide.md

@@ -65,10 +65,10 @@ Adoption Plan:
 📦 Creating backup... ✅ backup-20260128-143022
 ✓ Validating backup... ✅ 5 files verified
 📝 Updating files...
-  ✅ .kiro/steering/CORE_PRINCIPLES.md
-  ✅ .kiro/steering/ENVIRONMENT.md
-  ✅ .kiro/tools/ultrawork_enhancer.py
-  ⏭️  .kiro/specs/ (preserved)
+  ✅ .sce/steering/CORE_PRINCIPLES.md
+  ✅ .sce/steering/ENVIRONMENT.md
+  ✅ .sce/tools/ultrawork_enhancer.py
+  ⏭️  .sce/specs/ (preserved)
 ✅ Adoption completed successfully!
 
 📊 Summary:
@@ -94,7 +94,7 @@ sce adopt --dry-run
 ### Automatic Detection
 
 The system automatically detects your project state:
-- Checks for existing `.kiro/` directory
+- Checks for existing `.sce/` directory
 - Reads version information
 - Identifies user content (specs, custom files)
 - Detects potential conflicts
@@ -105,11 +105,11 @@ Based on detection, it chooses the optimal mode:
 
 | Project State | Selected Mode | What Happens |
 |--------------|---------------|--------------|
-| No `.kiro/` | **Fresh** | Creates complete structure |
-| `.kiro/` + same version | **Skip** | Already up-to-date |
-| `.kiro/` + older version | **Smart Update** | Updates templates only |
-| `.kiro/` + newer version | **Warning** | Version mismatch alert |
-| `.kiro/` + no version | **Smart Adopt** | Full adoption with backup |
+| No `.sce/` | **Fresh** | Creates complete structure |
+| `.sce/` + same version | **Skip** | Already up-to-date |
+| `.sce/` + older version | **Smart Update** | Updates templates only |
+| `.sce/` + newer version | **Warning** | Version mismatch alert |
+| `.sce/` + no version | **Smart Adopt** | Full adoption with backup |
 
 ### Automatic Conflict Resolution
 
@@ -136,10 +136,10 @@ Before any modifications:
 
 ### 1. Fresh Adoption
 
-**When**: No `.kiro/` directory exists
+**When**: No `.sce/` directory exists
 
 **Actions**:
-- Creates complete `.kiro/` structure
+- Creates complete `.sce/` structure
 - Copies all template files
 - Creates `version.json`
 - No conflicts, no backup needed
@@ -150,7 +150,7 @@ $ sce adopt
 
 Mode: Fresh
 Actions:
-  - Create .kiro/ directory structure
+  - Create .sce/ directory structure
   - Copy template files
   - Create version.json
 
@@ -180,7 +180,7 @@ No changes needed.
 
 ### 3. Smart Update
 
-**When**: Existing `.kiro/` with older version
+**When**: Existing `.sce/` with older version
 
 **Actions**:
 - Backs up files that will change
@@ -202,10 +202,10 @@ Preserved: 3 specs, CURRENT_CONTEXT.md
 
 ### 4. Smart Adopt
 
-**When**: `.kiro/` exists but no version info
+**When**: `.sce/` exists but no version info
 
 **Actions**:
-- Backs up entire `.kiro/` directory
+- Backs up entire `.sce/` directory
 - Adopts with full structure
 - Preserves user content
 - Creates version.json
@@ -392,13 +392,13 @@ Problem: Unable to create backup of existing files
 
 Possible causes:
   - Insufficient disk space
-  - Permission denied for .kiro/backups/
+  - Permission denied for .sce/backups/
   - File system error
 ```
 
 **Solutions**:
 1. Free up disk space (need ~50MB)
-2. Check file permissions: `ls -la .kiro/`
+2. Check file permissions: `ls -la .sce/`
 3. Try running with elevated permissions (if appropriate)
 
 ---
@@ -409,18 +409,18 @@ Possible causes:
 ```
 ❌ Error: Permission Denied
 
-Problem: Cannot write to .kiro/ directory
+Problem: Cannot write to .sce/ directory
 ```
 
 **Solutions**:
 ```bash
 # Check permissions
-ls -la .kiro/
+ls -la .sce/
 
 # Fix permissions (Unix/Mac)
-chmod -R u+w .kiro/
+chmod -R u+w .sce/
 
-# Windows: Right-click .kiro/ → Properties → Security → Edit
+# Windows: Right-click .sce/ → Properties → Security → Edit
 ```
 
 ---
@@ -535,8 +535,8 @@ sce version-info
 
 Don't delete automatic backups immediately:
 ```bash
-# Backups are in .kiro/backups/
-ls .kiro/backups/
+# Backups are in .sce/backups/
+ls .sce/backups/
 ```
 
 ### 5. Use Verbose for Debugging
@@ -554,7 +554,7 @@ After adoption, your project will have:
 
 ```
 your-project/
-├── .kiro/                          # sce core directory
+├── .sce/                          # sce core directory
 │   ├── version.json                # Version tracking
 │   ├── specs/                      # Spec storage
 │   ├── steering/                   # AI behavior rules
@@ -594,18 +594,18 @@ After successful adoption:
    ```
 
 4. **Read the spec workflow guide**:
-   - See `.kiro/specs/SPEC_WORKFLOW_GUIDE.md`
+   - See `.sce/specs/SPEC_WORKFLOW_GUIDE.md`
 
 5. **Explore Ultrawork**:
    ```bash
-   sce enhance requirements .kiro/specs/01-00-my-feature/requirements.md
+   sce enhance requirements .sce/specs/01-00-my-feature/requirements.md
    ```
 
 ---
 
 ## Getting Help
 
-- **Documentation**: Check README.md in your `.kiro/` directory
+- **Documentation**: Check README.md in your `.sce/` directory
 - **System Check**: `sce doctor`
 - **Version Info**: `sce version-info`
 - **Issues**: https://github.com/heguangyong/scene-capability-engine/issues

package/docs/agent-hooks-analysis.md

@@ -137,7 +137,7 @@ Hooks can perform two types of actions:
   "name": "Auto-generate prompts",
   "when": {
     "type": "fileEdited",
-    "patterns": ["**/.kiro/specs/*/requirements.md", "**/.kiro/specs/*/design.md"]
+    "patterns": ["**/.sce/specs/*/requirements.md", "**/.sce/specs/*/design.md"]
   },
   "then": {
     "type": "askAgent",
@@ -306,7 +306,7 @@ Hooks can perform two types of actions:
 **Goal**: Basic hook support in sce
 
 **Tasks**:
-1. Add hook configuration to `.kiro/hooks/` directory
+1. Add hook configuration to `.sce/hooks/` directory
 2. Create hook templates for common use cases
 3. Add `sce hooks` command group:
    - `sce hooks list` - List all hooks
@@ -400,7 +400,7 @@ Hooks can perform two types of actions:
 ### Hook Storage
 
 ```
-.kiro/
+.sce/
 ├── hooks/
 │   ├── auto-sync.json
 │   ├── quality-gate.json
@@ -555,7 +555,7 @@ Watch mode provides automation for developers not using AI IDE. It monitors file
                ▼
 ┌─────────────────────────────────────┐
 │     Execution Logger                │
-│  (.kiro/watch/execution.log)        │
+│  (.sce/watch/execution.log)        │
 └─────────────────────────────────────┘
 ```
 
@@ -580,15 +580,15 @@ sce watch stop
 
 ### Configuration
 
-Watch mode uses `.kiro/watch-config.json`:
+Watch mode uses `.sce/watch-config.json`:
 
 ```json
 {
   "enabled": true,
   "patterns": [
     "**/tasks.md",
-    "**/.kiro/specs/*/requirements.md",
-    "**/.kiro/specs/*/design.md"
+    "**/.sce/specs/*/requirements.md",
+    "**/.sce/specs/*/design.md"
   ],
   "actions": {
     "**/tasks.md": {
@@ -639,7 +639,7 @@ Watch mode uses `.kiro/watch-config.json`:
 **Without Automation**:
 ```bash
 # 1. Edit tasks.md
-vim .kiro/specs/my-spec/tasks.md
+vim .sce/specs/my-spec/tasks.md
 
 # 2. Save file
 
@@ -662,7 +662,7 @@ sce workspace sync
 sce context export my-spec
 
 # 3. Copy to other tool
-cat .kiro/specs/my-spec/context-export.md
+cat .sce/specs/my-spec/context-export.md
 ```
 
 **Time**: ~1 minute per export
@@ -762,7 +762,7 @@ Start with Phase 1 (foundation) to validate the approach, then expand to Phase 2
   "enabled": true,
   "when": {
     "type": "fileEdited",
-    "patterns": ["**/.kiro/specs/*/tasks.md"]
+    "patterns": ["**/.sce/specs/*/tasks.md"]
   },
   "then": {
     "type": "askAgent",

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
+  }
+}