scene-capability-engine 3.2.0 → 3.3.1

package/docs/interactive-customization/dual-ui-mode-integration-guide.md

@@ -0,0 +1,92 @@
+# Dual UI Mode Integration Guide
+
+This guide maps two UI surfaces to SCE interactive governance behavior.
+
+## 1. Target Surfaces
+
+- `user-app`: end-user business operation UI.
+- `ops-console`: maintenance and new-requirement management UI.
+
+## 2. Default Governance Mapping
+
+- `user-app`
+  - Recommended dialogue profile: `business-user`
+  - Recommended execution mode: `suggestion`
+  - Apply intent is denied by authorization dialogue policy by default.
+- `ops-console`
+  - Recommended dialogue profile: `system-maintainer`
+  - Execution mode: `suggestion|apply` (subject to runtime/authorization-tier/approval gates)
+
+## 3. Runtime Integration Pattern
+
+Use the same backend flow and switch only mode/profile by surface:
+
+```bash
+# user-facing application UI
+sce scene interactive-flow \
+  --input <provider-payload.json> \
+  --goal "<business-goal>" \
+  --ui-mode user-app \
+  --dialogue-profile business-user \
+  --execution-mode suggestion \
+  --json
+
+# operations / maintenance console
+sce scene interactive-flow \
+  --input <provider-payload.json> \
+  --goal "<maintenance-goal>" \
+  --ui-mode ops-console \
+  --dialogue-profile system-maintainer \
+  --execution-mode apply \
+  --runtime-environment staging \
+  --auto-execute-low-risk \
+  --json
+```
+
+## 4. UI Rendering Contract
+
+Read these fields from loop/flow output:
+
+- `summary.ui_mode`
+- `summary.dialogue_authorization_decision`
+- `summary.authorization_tier_decision`
+- `summary.execution_block_reason_category`
+- `summary.execution_block_remediation_hint`
+
+Recommended rendering:
+
+- `dialogue_authorization_decision=deny`: block execute button and show guided fallback.
+- `dialogue_authorization_decision=review-required`: show review handoff panel.
+- `authorization_tier_decision=allow` and runtime/gate allow: enable guarded apply action.
+
+## 5. Runtime UI-Mode Contract (Default)
+
+`runtime-mode-policy-baseline.json` now includes `ui_modes` policy:
+
+- `user-app`
+  - `allow_execution_modes=["suggestion"]`
+  - `deny_execution_modes=["apply"]`
+  - Apply intents should switch to `ops-console`.
+- `ops-console`
+  - `allow_execution_modes=["suggestion","apply"]`
+  - Supports maintenance/apply flows with approval and authorization-tier gates.
+
+When evaluating runtime policy directly, pass `--ui-mode`:
+
+```bash
+node scripts/interactive-runtime-policy-evaluate.js \
+  --plan .kiro/reports/interactive-change-plan.generated.json \
+  --ui-mode user-app \
+  --runtime-mode ops-fix \
+  --runtime-environment staging \
+  --json
+```
+
+## 6. Audit and Compliance
+
+For both modes, persist:
+
+- work-order (`interactive-work-order.json|.md`)
+- approval events (`interactive-approval-events.jsonl`)
+- execution ledger (`interactive-execution-ledger.jsonl`)
+- authorization-tier signals (`interactive-authorization-tier-signals.jsonl`)

package/docs/interactive-customization/embedded-assistant-authorization-dialogue-rules.md

@@ -0,0 +1,78 @@
+# Embedded Assistant Authorization Dialogue Rules
+
+This guide defines mandatory conversation and authorization behavior for an embedded AI assistant using SCE interactive flow inside business systems.
+
+## 1. Goals
+
+- Keep non-technical users productive in `suggestion` mode by default.
+- Prevent unsafe or unauthorized system mutation.
+- Ensure every mutation path is explainable, reversible, and auditable.
+
+## 2. Dialogue Profiles
+
+- `business-user`:
+  - Default profile for end users.
+  - Allowed mode: `suggestion` only.
+  - Any apply request must be refused with guided escalation steps.
+- `system-maintainer`:
+  - For operators/maintainers with change responsibility.
+  - `apply` can be evaluated, but must still pass runtime + authorization-tier + approval policy checks.
+
+## 3. Mandatory Conversation Flow
+
+1. Clarify intent and scope:
+- Assistant must restate target `product/module/page/entity/scene`.
+- Assistant must ask for missing business constraints before planning.
+
+2. Explain plan before execution:
+- Assistant must show `risk_level`, verification checks, and rollback plan.
+- Assistant must explicitly say whether execution is blocked, review-required, or allowed.
+
+3. Confirmation before mutation:
+- For `apply`, assistant must ask a final explicit confirmation.
+- Confirmation text must include impact summary and rollback availability.
+
+## 4. Step-Up Authorization Rules
+
+- Password step-up:
+  - When policy requires password for apply, assistant must ask for one-time password confirmation.
+  - Assistant must never echo raw password in logs or summaries.
+- Role-policy step-up:
+  - When role policy is required, assistant must ask for actor role and approver role.
+  - If separation-of-duties is required, roles must be distinct.
+- Review-required:
+  - Assistant must stop execution and generate review handoff instructions.
+
+## 5. Deny and Fallback Behavior
+
+- If decision is `deny`, assistant must:
+  - reject execution,
+  - explain the blocked policy reason in plain language,
+  - provide at least one safe alternative (`suggestion`, ticket, or scope reduction).
+- If environment is rate-limited or unstable (`429`/timeouts), assistant must:
+  - avoid aggressive retries,
+  - switch to phased queue execution guidance,
+  - preserve pending work-order state for resume.
+
+## 6. Audit Requirements
+
+Each interactive mutation attempt must leave:
+
+- work-order artifacts (`interactive-work-order.json|.md`)
+- approval event audit (`interactive-approval-events.jsonl`)
+- execution ledger (`interactive-execution-ledger.jsonl`)
+- authorization-tier signal (`interactive-authorization-tier-signals.jsonl`)
+
+Assistant responses for mutation flow must include a traceable reference:
+- `session_id`
+- `work_order_id` (or pending ticket id)
+- current decision (`allow|review-required|deny`)
+
+## 7. UX Copy Requirements
+
+- Use direct and business-readable language (no internal jargon only).
+- Every blocked response must end with actionable next steps.
+- Every allowed apply response must include:
+  - what will change now,
+  - what will not change,
+  - how to rollback.

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

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.0",
+  "version": "1.3.0",
   "min_intent_samples": 5,
   "adoption_rate_min_percent": 30,
   "execution_success_rate_min_percent": 90,
@@ -8,6 +8,13 @@
   "satisfaction_min_score": 4,
   "min_feedback_samples": 3,
   "min_matrix_samples": 3,
+  "min_dialogue_authorization_samples": 3,
+  "dialogue_authorization_block_rate_max_percent": 40,
+  "min_runtime_samples": 3,
+  "runtime_block_rate_max_percent": 40,
+  "runtime_ui_mode_violation_max_total": 0,
+  "min_authorization_tier_samples": 3,
+  "authorization_tier_block_rate_max_percent": 40,
   "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/runtime-mode-policy-baseline.json

@@ -59,6 +59,32 @@
       "require_work_order": true
     }
   },
+  "ui_modes": {
+    "user-app": {
+      "description": "End-user business operation surface. Apply should be routed through ops console.",
+      "allow_runtime_modes": [
+        "user-assist",
+        "ops-fix"
+      ],
+      "allow_execution_modes": [
+        "suggestion"
+      ],
+      "deny_execution_modes": [
+        "apply"
+      ]
+    },
+    "ops-console": {
+      "description": "Operations and maintenance console surface.",
+      "allow_runtime_modes": [
+        "ops-fix",
+        "feature-dev"
+      ],
+      "allow_execution_modes": [
+        "suggestion",
+        "apply"
+      ]
+    }
+  },
   "environments": {
     "dev": {
       "allow_live_apply": true,

package/docs/release-checklist.md

@@ -135,7 +135,10 @@ Ensure:
   - `KSE_RELEASE_WEEKLY_OPS_REQUIRE_SUMMARY`: require weekly summary artifact (`true|false`, default `true`)
   - `KSE_RELEASE_WEEKLY_OPS_MAX_RISK_LEVEL`: `low|medium|high|unknown` (default `medium`)
   - `KSE_RELEASE_WEEKLY_OPS_MAX_GOVERNANCE_BREACHES`: optional max breach count
+  - `KSE_RELEASE_WEEKLY_OPS_MAX_AUTHORIZATION_TIER_BLOCK_RATE_PERCENT`: max authorization-tier deny/review block rate percent (default `40`)
+  - `KSE_RELEASE_WEEKLY_OPS_MAX_DIALOGUE_AUTHORIZATION_BLOCK_RATE_PERCENT`: max dialogue-authorization block rate percent (default `40`)
   - `KSE_RELEASE_WEEKLY_OPS_MAX_MATRIX_REGRESSION_RATE_PERCENT`: optional max regression-positive rate percent
+  - Invalid numeric values are reported as gate `config_warnings` and default threshold fallback is applied.
 - Optional: tune release asset integrity gate:
   - `KSE_RELEASE_ASSET_INTEGRITY_ENFORCE`: `true|false` (default `true`)
   - `KSE_RELEASE_ASSET_INTEGRITY_REQUIRE_NON_EMPTY`: `true|false` (default `true`)

package/docs/security-governance-default-baseline.md

@@ -15,6 +15,7 @@ This baseline is the default operating policy for SCE-driven delivery, including
 - Low-risk auto-apply is allowed only when gate result is `allow`.
 - Runtime policy gate is mandatory before apply (`runtime_mode=ops-fix`, `runtime_environment=staging` by default).
 - Runtime non-allow (`deny|review-required`) should block unattended apply (`--fail-on-runtime-non-allow`).
+- Authorization-tier gate is mandatory before apply (profile+environment step-up checks).
 - Enable role-based action control when environment requires stronger separation of duties (`approval-role-policy-baseline.json` + `--actor-role`).
 - Apply-mode mutating plans require password authorization (`authorization.password_required=true` by default).
 - Password verifier hash must be supplied via `SCE_INTERACTIVE_AUTH_PASSWORD_SHA256` (or explicit override).
@@ -37,6 +38,9 @@ This baseline is the default operating policy for SCE-driven delivery, including
 - `.kiro/reports/release-evidence/governance-snapshot-<tag>.json`
 - `.kiro/reports/release-evidence/weekly-ops-summary-<tag>.json`
 - `.kiro/reports/interactive-governance-report.json`
+- `.kiro/reports/interactive-dialogue-authorization-signals.jsonl`
+- `.kiro/reports/interactive-runtime-signals.jsonl`
+- `.kiro/reports/interactive-authorization-tier-signals.jsonl`
 - `.kiro/reports/interactive-dialogue-governance.json`
 - `.kiro/reports/interactive-execution-ledger.jsonl`
 - `.kiro/reports/interactive-approval-events.jsonl`
@@ -52,3 +56,5 @@ node scripts/release-asset-integrity-check.js
 ```
 
 If weekly ops summary risk is `high`, freeze release and run remediation before next tag.
+Keep weekly ops block-rate thresholds enabled for both authorization tiers and dialogue authorization (default `40%` each).
+Keep weekly ops runtime ui-mode violation threshold enabled (`RELEASE_WEEKLY_OPS_MAX_RUNTIME_UI_MODE_VIOLATION_TOTAL`, default `0`).