scene-capability-engine 3.0.8 → 3.2.0

package/docs/interactive-customization/execution-record.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://scene-capability-engine.dev/schemas/interactive/execution-record.schema.json",
+  "title": "Interactive Execution Record",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "execution_id",
+    "plan_id",
+    "adapter_type",
+    "policy_decision",
+    "result",
+    "executed_at"
+  ],
+  "properties": {
+    "execution_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "plan_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "adapter_type": {
+      "type": "string",
+      "minLength": 1
+    },
+    "policy_decision": {
+      "type": "string",
+      "enum": [
+        "allow",
+        "review-required",
+        "deny"
+      ]
+    },
+    "approval_snapshot": {
+      "type": "object"
+    },
+    "diff_summary": {
+      "type": "object"
+    },
+    "result": {
+      "type": "string",
+      "enum": [
+        "success",
+        "failed",
+        "rolled-back",
+        "skipped"
+      ]
+    },
+    "rollback_ref": {
+      "type": "string"
+    },
+    "audit_trace_id": {
+      "type": "string"
+    },
+    "executed_at": {
+      "type": "string",
+      "format": "date-time"
+    }
+  }
+}

package/docs/interactive-customization/governance-alert-playbook.md

@@ -0,0 +1,51 @@
+# Governance Alert Playbook
+
+This playbook defines how to respond when governance thresholds are breached.
+
+## Trigger
+
+Any medium/high breach from `interactive-governance-report`:
+
+- adoption-rate-low
+- execution-success-low
+- rollback-rate-high
+- security-intercept-high
+- satisfaction-low
+
+## Severity Policy
+
+- `high`: execution quality/safety risk. Start containment immediately.
+- `medium`: quality/friction drift. Start corrective tuning in current cycle.
+- `low`: data quality warning (e.g., insufficient intent/feedback samples).
+
+## Response Workflow
+
+1. Confirm signal quality
+- Verify report window and evidence file completeness.
+- Re-run report for the same window to exclude transient parse issues.
+
+2. Containment (for high severity)
+- Freeze non-essential apply actions.
+- Force suggestion-only mode for affected scope.
+- Require explicit reviewer approval.
+
+3. Diagnosis
+- Inspect failed/skipped execution records.
+- Inspect blocked action categories from policy decision.
+- Inspect rejected approval events and common intent patterns.
+
+4. Fix
+- Update template governance rules or decision logic.
+- Tune risk classification hints and plan generation prompts.
+- Strengthen pre-apply verification checks.
+
+5. Verification
+- Re-run report in next checkpoint window.
+- Confirm breached metric returns within threshold.
+
+## Mandatory Output
+
+- Incident note with breach IDs.
+- Implemented fix list.
+- Re-validation report link.
+- Rollback evidence (if rollback was executed).

package/docs/interactive-customization/governance-report-template.md

@@ -0,0 +1,46 @@
+# Governance Report Template
+
+Use this template for weekly/monthly interactive customization governance review.
+
+## Header
+
+- Period:
+- Generated at:
+- Scope:
+- Overall status: `ok | alert`
+
+## Core Metrics
+
+1. Adoption rate (%)
+2. Execution success rate (%)
+3. Rollback rate (%)
+4. Security intercept rate (%)
+5. Intent sample count
+6. Satisfaction average score (1-5)
+7. Satisfaction sample count
+
+## Alert Summary
+
+- Breach count:
+- Warning count:
+- Top breach IDs:
+
+## Evidence
+
+- Intent audit:
+- Approval audit:
+- Execution ledger:
+- Feedback file:
+- Threshold baseline:
+
+## Remediation Actions
+
+1. Immediate actions (0-24h):
+2. Short-term actions (1-7d):
+3. Policy/template tuning actions (1-2 iterations):
+
+## Follow-up Checkpoint
+
+- Next review date:
+- Owner:
+- Exit criteria:

package/docs/interactive-customization/governance-threshold-baseline.json

@@ -0,0 +1,14 @@
+{
+  "version": "1.1.0",
+  "min_intent_samples": 5,
+  "adoption_rate_min_percent": 30,
+  "execution_success_rate_min_percent": 90,
+  "rollback_rate_max_percent": 20,
+  "security_intercept_rate_max_percent": 60,
+  "satisfaction_min_score": 4,
+  "min_feedback_samples": 3,
+  "min_matrix_samples": 3,
+  "matrix_portfolio_pass_rate_min_percent": 80,
+  "matrix_regression_positive_rate_max_percent": 20,
+  "matrix_stage_error_rate_max_percent": 20
+}

package/docs/interactive-customization/guardrail-policy-baseline.json

@@ -0,0 +1,27 @@
+{
+  "version": "1.0.0",
+  "mode": "advice-first",
+  "approval_policy": {
+    "require_approval_for_risk_levels": [
+      "high"
+    ],
+    "max_actions_without_approval": 5,
+    "require_dual_approval_for_privilege_escalation": true
+  },
+  "security_policy": {
+    "require_masking_when_sensitive_data": true,
+    "forbid_plaintext_secrets": true,
+    "require_backup_for_irreversible_actions": true
+  },
+  "authorization_policy": {
+    "require_password_for_apply_mutations": true,
+    "password_scope": [
+      "execute"
+    ],
+    "password_hash_env": "SCE_INTERACTIVE_AUTH_PASSWORD_SHA256",
+    "password_ttl_seconds": 600
+  },
+  "catalog_policy": {
+    "catalog_file": "docs/interactive-customization/high-risk-action-catalog.json"
+  }
+}

package/docs/interactive-customization/high-risk-action-catalog.json

@@ -0,0 +1,22 @@
+{
+  "version": "1.0.0",
+  "generated_at": "2026-02-19T00:00:00.000Z",
+  "catalog": {
+    "deny_action_types": [
+      "credential_export",
+      "raw_sql_destructive",
+      "permission_grant_super_admin",
+      "bulk_delete_without_filter"
+    ],
+    "review_required_action_types": [
+      "schema_migration",
+      "workflow_approval_chain_change",
+      "payment_rule_change",
+      "inventory_adjustment_bulk"
+    ],
+    "notes": {
+      "deny": "Actions in deny_action_types are blocked by default.",
+      "review_required": "Actions in review_required_action_types require explicit human approval."
+    }
+  }
+}

package/docs/interactive-customization/moqui-adapter-interface.md

@@ -0,0 +1,40 @@
+# Moqui Adapter Minimal Interface (Stage C)
+
+This document defines the minimal adapter contract used by interactive customization execution in the Moqui experiment product.
+
+## Interface
+
+`capabilities()`
+- Returns capability declaration (`supported_change_types`, risk statement, runtime behavior).
+
+`plan(changeIntent, context)`
+- Converts a `Change_Intent` into a structured `Change_Plan`.
+- Output fields align with `change-plan.schema.json`.
+
+`validate(changePlan)`
+- Evaluates `Change_Plan` with guardrail policy + high-risk catalog.
+- Decision: `allow | review-required | deny`.
+
+`apply(changePlan)`
+- Runs controlled execution after validation.
+- Default behavior is safe simulation; live apply is opt-in.
+- Produces `ExecutionRecord` and appends execution ledger.
+
+`applyLowRisk(changePlan)`
+- One-click execution entry for stage-C.
+- Requires `risk_level=low` and policy decision `allow`, otherwise blocks with `ExecutionRecord(result=skipped)`.
+
+`rollback(executionId)`
+- Generates rollback execution record for a previous execution.
+- Keeps append-only audit behavior.
+
+## Reference Implementation
+
+- Runtime module: `lib/interactive-customization/moqui-interactive-adapter.js`
+- Script entry: `scripts/interactive-moqui-adapter.js`
+- Validation core: `lib/interactive-customization/change-plan-gate-core.js`
+
+## Artifacts
+
+- Latest execution record: `.kiro/reports/interactive-execution-record.latest.json`
+- Execution ledger (JSONL): `.kiro/reports/interactive-execution-ledger.jsonl`

package/docs/interactive-customization/moqui-context-provider.sample.json

@@ -0,0 +1,72 @@
+{
+  "product": "331-moqui-poc",
+  "workspace": {
+    "module": "governance-platform",
+    "page": "screen-explorer-workbench",
+    "scene": {
+      "id": "sce.scene--platform-screen-explorer-assist--0.1.0",
+      "name": "Screen 探索场景",
+      "type": "screen-analysis",
+      "workflow_node": "screen-analysis"
+    },
+    "screen_explorer": {
+      "active_tab": "Overview",
+      "selected_screen": "Screen Explorer",
+      "selected_component": "Entity",
+      "filters": [
+        "AI Components",
+        "Forms",
+        "Widgets"
+      ],
+      "result_total": 0
+    },
+    "ontology": {
+      "entities": [
+        "Screen",
+        "Form",
+        "Widget"
+      ],
+      "relations": [
+        "Screen_has_Form",
+        "Screen_has_Widget"
+      ],
+      "business_rules": [
+        "screen_name_unique",
+        "component_reference_consistency",
+        "change_requires_audit_record"
+      ],
+      "decision_policies": [
+        "publish_requires_risk_review",
+        "fallback_to_read_only_when_gate_non_allow"
+      ]
+    }
+  },
+  "fields": [
+    {
+      "name": "screen_name",
+      "type": "string"
+    },
+    {
+      "name": "component_type",
+      "type": "enum"
+    },
+    {
+      "name": "api_token",
+      "type": "string",
+      "sensitive": true
+    }
+  ],
+  "current_state": {
+    "screen_name": "Screen Explorer",
+    "component_type": "Entity",
+    "api_token": "tok_live_example_abc",
+    "operator": "platform_manager"
+  },
+  "assistant": {
+    "sessionId": "session-1771",
+    "agentId": "codex-gpt4-1",
+    "model": "Spec-Expert",
+    "mode": "read-only",
+    "prompt": "Ask what should be fixed on the current page and propose actionable plan."
+  }
+}

package/docs/interactive-customization/moqui-copilot-context-contract.json

@@ -0,0 +1,50 @@
+{
+  "version": "1.1.0",
+  "product": "scene-capability-engine",
+  "context_contract": {
+    "required_fields": [
+      "product",
+      "module",
+      "page"
+    ],
+    "optional_fields": [
+      "entity",
+      "scene_id",
+      "workflow_node",
+      "fields",
+      "current_state",
+      "scene_workspace",
+      "assistant_panel"
+    ],
+    "max_field_count": 400,
+    "max_payload_kb": 512
+  },
+  "security_contract": {
+    "mode": "read-only",
+    "masking_required": true,
+    "sensitive_key_patterns": [
+      "password",
+      "secret",
+      "token",
+      "api_key",
+      "apikey",
+      "credential",
+      "email",
+      "phone",
+      "bank",
+      "card"
+    ],
+    "forbidden_keys": [
+      "raw_password",
+      "private_key",
+      "access_token_plaintext"
+    ]
+  },
+  "runtime_contract": {
+    "provider": "ui-context-provider",
+    "transport": "json",
+    "schema": "docs/interactive-customization/page-context.schema.json",
+    "consumer": "scripts/interactive-intent-build.js",
+    "loop_entry": "scripts/interactive-customization-loop.js"
+  }
+}

package/docs/interactive-customization/moqui-copilot-integration-guide.md

@@ -0,0 +1,100 @@
+# Moqui Copilot Integration Guide (Stage A)
+
+This guide defines the page-level integration pattern for embedding the SCE Business Copilot into a customized Moqui product.
+
+## Goal
+
+Provide a deterministic and secure context bridge so non-technical users can describe business goals in UI, while backend automation remains read-only at this stage.
+
+## Integration Model
+
+```text
+Moqui Page -> Context Provider -> interactive-context-bridge -> Masking Filter -> Copilot Panel -> interactive-intent-build
+```
+
+At stage A:
+
+- Copilot is read-only.
+- No write action is executed from the panel.
+- Output artifacts are `Change_Intent`, explain markdown, and audit JSONL.
+
+## Context Provider Contract
+
+Reference file:
+
+- `docs/interactive-customization/moqui-copilot-context-contract.json`
+
+Minimum payload fields:
+
+1. `product`
+2. `module`
+3. `page`
+
+Optional but recommended:
+
+1. `entity`
+2. `scene_id`
+3. `workflow_node`
+4. `fields[]`
+5. `current_state`
+6. `scene_workspace` (screen explorer + ontology snapshot)
+7. `assistant_panel` (AI panel session/model metadata)
+
+Schema:
+
+- `docs/interactive-customization/page-context.schema.json`
+
+## Security Boundary
+
+1. Provider must apply key-based masking for sensitive fields before sending context to Copilot.
+2. Forbidden keys must be removed completely, not masked.
+3. Copilot requests must run under read-only runtime identity.
+4. Generated outputs are stored in report paths only, never direct code/runtime mutation.
+
+## Suggested Moqui Hook Points
+
+1. Build a page context object from screen/form state in controller/render pipeline.
+2. Pass provider payload to `interactive-context-bridge` and store normalized page-context artifact.
+3. Pass sanitized context to frontend Copilot panel via JSON endpoint or embedded script tag payload.
+4. Trigger `interactive-intent-build` with user goal + sanitized context.
+
+## Bridge Command
+
+```bash
+node scripts/interactive-context-bridge.js \
+  --input docs/interactive-customization/moqui-context-provider.sample.json \
+  --context-contract docs/interactive-customization/moqui-copilot-context-contract.json \
+  --json
+```
+
+## One-Command Flow
+
+```bash
+node scripts/interactive-flow.js \
+  --input docs/interactive-customization/moqui-context-provider.sample.json \
+  --goal "Adjust order screen field layout for clearer input flow" \
+  --context-contract docs/interactive-customization/moqui-copilot-context-contract.json \
+  --execution-mode apply \
+  --auto-execute-low-risk \
+  --feedback-score 5 \
+  --json
+```
+
+## Example Command
+
+```bash
+node scripts/interactive-intent-build.js \
+  --context docs/interactive-customization/page-context.sample.json \
+  --context-contract docs/interactive-customization/moqui-copilot-context-contract.json \
+  --goal "Must improve approval speed without changing payment authorization policy" \
+  --user-id product-owner \
+  --json
+```
+
+## Acceptance Checklist
+
+1. Context payload validates against schema.
+2. Context contract gate passes (required fields + payload size + forbidden keys).
+3. Sensitive keys are masked or removed.
+4. Copilot outputs contain `readonly=true`.
+5. Audit event is appended to `.kiro/reports/interactive-copilot-audit.jsonl`.

package/docs/interactive-customization/moqui-interactive-template-playbook.md

@@ -0,0 +1,94 @@
+# Moqui Interactive Template Playbook
+
+This playbook defines how to turn validated Moqui interactive customization flows into reusable SCE template assets.
+
+## Scope
+
+- Stage A/B/C artifacts:
+  - `Change_Intent`
+  - `Change_Plan`
+  - guardrail gate decision
+  - approval workflow state
+  - execution/rollback records
+- Stage D target:
+  - scene package template
+  - ontology model
+  - governance contract
+  - operational playbook
+
+## Standard Template Asset
+
+Primary package for the interactive loop:
+
+- `.kiro/templates/scene-packages/kse.scene--moqui-interactive-customization-loop--0.1.0/scene-package.json`
+- `.kiro/templates/scene-packages/kse.scene--moqui-interactive-customization-loop--0.1.0/scene.template.yaml`
+- `.kiro/templates/scene-packages/kse.scene--moqui-interactive-customization-loop--0.1.0/custom/scene.yaml`
+- `.kiro/templates/scene-packages/kse.scene--moqui-interactive-customization-loop--0.1.0/template.manifest.json`
+
+## Capability Matrix Mapping
+
+The template captures one full business-safe loop:
+
+1. `spec.moqui.interactive.intent.build`
+2. `spec.moqui.interactive.plan.generate`
+3. `spec.moqui.interactive.plan.gate`
+4. `spec.moqui.interactive.approval.workflow`
+5. `spec.moqui.interactive.low-risk.apply`
+6. `spec.moqui.interactive.rollback.record`
+
+## Ontology Baseline
+
+Minimum ontology entities:
+
+- `change_intent`
+- `change_plan`
+- `gate_decision`
+- `approval_state`
+- `execution_record`
+- `rollback_record`
+
+Minimum relations:
+
+- `change_intent -> change_plan (produces)`
+- `change_plan -> gate_decision (produces)`
+- `gate_decision -> approval_state (produces)`
+- `approval_state -> execution_record (produces)`
+- `execution_record -> rollback_record (produces)`
+
+## Governance Baseline
+
+Mandatory rule and decision coverage:
+
+- Business rules:
+  - intent phase must remain read-only
+  - high-risk plans require approval
+  - one-click apply restricted to low-risk + allow
+  - rollback trace linkage is mandatory
+- Decision logic:
+  - gate routing (`allow | review-required | deny`)
+  - execution routing (`low-risk apply` only)
+  - rollback routing (execution-ledger based)
+
+## Publish/Gate Workflow
+
+```bash
+# baseline score and ontology quality
+sce scene moqui-baseline --json
+
+# strict intake gate
+sce scene package-publish-batch \
+  --manifest docs/handoffs/handoff-manifest.json \
+  --dry-run \
+  --ontology-min-score 70 \
+  --ontology-min-average-score 70 \
+  --ontology-min-valid-rate 100 \
+  --json
+```
+
+## Acceptance Checklist
+
+- Template has full `capability_contract` chain (intent -> rollback).
+- `ontology_model.entities` and `ontology_model.relations` are non-empty.
+- `governance_contract.business_rules` and `decision_logic` are non-empty and closed.
+- Execution behavior remains guardrail-first (no direct high-risk auto-apply).
+- Template passes baseline and ontology gates without bypass flags.

package/docs/interactive-customization/non-technical-usability-report.md

@@ -0,0 +1,57 @@
+# Non-Technical Usability Report (Moqui Experiment)
+
+This report evaluates whether business users can complete optimization loops without software engineering expertise.
+
+## Target User Profile
+
+- Understands business process and constraints.
+- Does not write source code.
+- Needs explainable, reversible, low-risk change flow.
+
+## Success Cases
+
+1. Read-only understanding
+- User asks for process/field/rule explanation in page context.
+- System returns business-readable explain output and structured intent.
+
+2. Suggestion-first planning
+- User provides goal in business language.
+- System generates structured plan with risk, verification, rollback.
+
+3. Guardrail-protected execution
+- Low-risk and allow decisions can proceed via controlled apply.
+- High-risk/review-required actions are blocked or routed to approval.
+
+4. Traceable rollback
+- User can request rollback by execution id.
+- System records rollback trace without hidden mutation.
+
+## Failure Cases Observed
+
+1. Adoption friction
+- Users may receive too many `review-required`/`deny` outcomes when intent text is vague.
+
+2. Feedback sparsity
+- Satisfaction trend quality is weak when feedback sample count is low.
+
+3. Policy mismatch
+- Some domain intents are classified as medium/high by default and cannot use one-click path.
+
+## Improvement Backlog
+
+1. Improve intent guidance templates
+- Add business-facing prompt examples per module (order/inventory/approval).
+
+2. Add domain-tuned risk hints
+- Improve risk classification precision for repeated safe operations.
+
+3. Improve feedback capture
+- Add lightweight feedback collection in page copilot UI for each action result.
+
+4. Expand safe action catalog
+- Promote proven medium-risk patterns into review-light, still-governed pathways.
+
+## Current Verdict
+
+- Baseline usability is acceptable for guided business users.
+- Continuous improvement depends on better intent guidance + richer feedback samples.