scene-capability-engine 3.0.7 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/CHANGELOG.md +56 -0
  2. package/docs/331-poc-adaptation-roadmap.md +21 -2
  3. package/docs/331-poc-dual-track-integration-guide.md +10 -6
  4. package/docs/331-poc-weekly-delivery-checklist.md +15 -0
  5. package/docs/README.md +6 -0
  6. package/docs/command-reference.md +279 -5
  7. package/docs/handoff-profile-integration-guide.md +88 -0
  8. package/docs/interactive-customization/331-poc-sce-integration-checklist.md +148 -0
  9. package/docs/interactive-customization/README.md +354 -0
  10. package/docs/interactive-customization/adapter-extension-contract.md +55 -0
  11. package/docs/interactive-customization/adapter-extension-contract.sample.json +59 -0
  12. package/docs/interactive-customization/adapter-extension-contract.schema.json +192 -0
  13. package/docs/interactive-customization/change-intent.schema.json +72 -0
  14. package/docs/interactive-customization/change-plan.sample.json +41 -0
  15. package/docs/interactive-customization/change-plan.schema.json +125 -0
  16. package/docs/interactive-customization/cross-industry-replication-guide.md +49 -0
  17. package/docs/interactive-customization/dialogue-governance-policy-baseline.json +49 -0
  18. package/docs/interactive-customization/domain-pack-extension-flow.md +71 -0
  19. package/docs/interactive-customization/execution-record.schema.json +62 -0
  20. package/docs/interactive-customization/governance-alert-playbook.md +51 -0
  21. package/docs/interactive-customization/governance-report-template.md +46 -0
  22. package/docs/interactive-customization/governance-threshold-baseline.json +14 -0
  23. package/docs/interactive-customization/guardrail-policy-baseline.json +27 -0
  24. package/docs/interactive-customization/high-risk-action-catalog.json +22 -0
  25. package/docs/interactive-customization/moqui-adapter-interface.md +40 -0
  26. package/docs/interactive-customization/moqui-context-provider.sample.json +72 -0
  27. package/docs/interactive-customization/moqui-copilot-context-contract.json +50 -0
  28. package/docs/interactive-customization/moqui-copilot-integration-guide.md +100 -0
  29. package/docs/interactive-customization/moqui-interactive-template-playbook.md +94 -0
  30. package/docs/interactive-customization/non-technical-usability-report.md +57 -0
  31. package/docs/interactive-customization/page-context.sample.json +73 -0
  32. package/docs/interactive-customization/page-context.schema.json +150 -0
  33. package/docs/interactive-customization/phase-acceptance-evidence.md +110 -0
  34. package/docs/interactive-customization/runtime-mode-policy-baseline.json +99 -0
  35. package/docs/moqui-template-core-library-playbook.md +71 -0
  36. package/docs/release-checklist.md +29 -4
  37. package/docs/security-governance-default-baseline.md +53 -0
  38. package/docs/starter-kit/README.md +50 -0
  39. package/docs/starter-kit/handoff-manifest.starter.json +32 -0
  40. package/docs/starter-kit/handoff-profile-ci.sample.yml +53 -0
  41. package/docs/starter-kit/release.workflow.sample.yml +41 -0
  42. package/docs/zh/README.md +12 -0
  43. package/lib/auto/moqui-recovery-sequence.js +62 -0
  44. package/lib/commands/auto.js +325 -42
  45. package/lib/commands/scene.js +837 -0
  46. package/lib/data/moqui-capability-lexicon.json +14 -1
  47. package/lib/interactive-customization/change-plan-gate-core.js +201 -0
  48. package/lib/interactive-customization/index.js +9 -0
  49. package/lib/interactive-customization/moqui-interactive-adapter.js +732 -0
  50. package/lib/orchestrator/orchestration-engine.js +64 -6
  51. package/package.json +28 -2
@@ -0,0 +1,88 @@
1
+ # Handoff Profile Integration Guide
2
+
3
+ This guide defines a stable external integration contract for `sce auto handoff` profile-based intake.
4
+
5
+ ## Scope
6
+
7
+ - Profile-based defaults for:
8
+ - `sce auto handoff run`
9
+ - `sce auto handoff capability-matrix`
10
+ - Explicit override model for external projects.
11
+ - Recommended baseline for Moqui-driven template intake.
12
+
13
+ ## Available Profiles
14
+
15
+ | Profile | Use Case | Default Policy Characteristics |
16
+ | --- | --- | --- |
17
+ | `default` | General handoff intake | Current strict baseline gates. |
18
+ | `moqui` | Moqui template-core ingestion | Explicit alias of strict Moqui baseline gates. |
19
+ | `enterprise` | Production-grade controlled rollout | `max-risk-level=medium`, `require-release-gate-preflight=true`, `release-evidence-window=10`. |
20
+
21
+ Notes:
22
+
23
+ - Profile defaults are applied first.
24
+ - Explicit CLI options always override profile defaults.
25
+ - Invalid profile values fail fast.
26
+
27
+ ## Command Contract
28
+
29
+ ```bash
30
+ # capability matrix precheck
31
+ sce auto handoff capability-matrix \
32
+ --manifest docs/handoffs/handoff-manifest.json \
33
+ --profile moqui \
34
+ --fail-on-gap \
35
+ --json
36
+
37
+ # full closed-loop intake
38
+ sce auto handoff run \
39
+ --manifest docs/handoffs/handoff-manifest.json \
40
+ --profile moqui \
41
+ --json
42
+ ```
43
+
44
+ Enterprise mode:
45
+
46
+ ```bash
47
+ sce auto handoff run \
48
+ --manifest docs/handoffs/handoff-manifest.json \
49
+ --profile enterprise \
50
+ --json
51
+ ```
52
+
53
+ ## External Project Manifest Requirements
54
+
55
+ External handoff projects should provide:
56
+
57
+ - `templates[]`: source template set to absorb.
58
+ - `specs[]`: executable integration scope.
59
+ - `ontology_validation`: structured pass/fail payload.
60
+ - `capabilities[]` (recommended): explicit expected capability contract.
61
+
62
+ Recommended evidence files before `handoff run`:
63
+
64
+ - `.kiro/reports/release-evidence/moqui-template-baseline.json`
65
+ - `.kiro/reports/handoff-capability-matrix.json` or `.md`
66
+ - `.kiro/reports/release-evidence/moqui-lexicon-audit.json`
67
+
68
+ ## Override Rules
69
+
70
+ Examples:
71
+
72
+ ```bash
73
+ # profile defaults + explicit override
74
+ sce auto handoff run \
75
+ --manifest docs/handoffs/handoff-manifest.json \
76
+ --profile enterprise \
77
+ --max-risk-level high \
78
+ --no-require-release-gate-preflight \
79
+ --json
80
+ ```
81
+
82
+ `--profile enterprise` applies strict defaults, then explicit flags above override them.
83
+
84
+ ## Recommended External Rollout
85
+
86
+ 1. Start with `--profile moqui` for template sedimentation and matrix closure.
87
+ 2. Move to `--profile enterprise` when release preflight governance is ready.
88
+ 3. Keep explicit overrides minimal and auditable in CI scripts.
@@ -0,0 +1,148 @@
1
+ # 331-poc SCE Integration Checklist
2
+
3
+ This checklist defines the minimum production-ready integration for embedding SCE interactive customization in `331-poc` (Moqui-focused solution).
4
+
5
+ ## 1. Runtime Preconditions
6
+
7
+ - Node runtime: `>=16` (recommended `20.x`).
8
+ - SCE installed and available as `sce`.
9
+ - `docs/interactive-customization/moqui-copilot-context-contract.json` exists and is aligned with current UI payload fields.
10
+ - Interactive policy assets are present:
11
+ - `docs/interactive-customization/guardrail-policy-baseline.json`
12
+ - `docs/interactive-customization/high-risk-action-catalog.json`
13
+
14
+ ## 2. Moqui UI Context Contract
15
+
16
+ Provider payload sent from UI must include:
17
+
18
+ - `product`, `workspace.module`, `workspace.page`
19
+ - `workspace.scene` (id/name/type)
20
+ - `workspace.ontology`:
21
+ - `entities`
22
+ - `relations`
23
+ - `business_rules`
24
+ - `decision_policies`
25
+ - `current_state` (masked/sanitized)
26
+ - `assistant.sessionId`
27
+
28
+ Hard rules:
29
+
30
+ - No plaintext secrets.
31
+ - No forbidden keys from context contract (for example `private_key`).
32
+ - Payload size must stay within contract limits.
33
+
34
+ ## 3. Default One-Command Execution
35
+
36
+ Use this command as the default integration path:
37
+
38
+ ```bash
39
+ sce scene interactive-flow \
40
+ --input <provider-payload.json> \
41
+ --goal "<business goal>" \
42
+ --context-contract docs/interactive-customization/moqui-copilot-context-contract.json \
43
+ --execution-mode apply \
44
+ --auto-execute-low-risk \
45
+ --feedback-score 5 \
46
+ --json
47
+ ```
48
+
49
+ Notes:
50
+
51
+ - Matrix stage is enabled by default.
52
+ - Keep `--no-matrix` only for diagnostics.
53
+
54
+ ## 4. Governance and Gate Defaults
55
+
56
+ Run governance gate on schedule and pre-release:
57
+
58
+ ```bash
59
+ node scripts/interactive-governance-report.js --period weekly --fail-on-alert --json
60
+ ```
61
+
62
+ Run matrix regression gate in release pipeline (configurable):
63
+
64
+ ```bash
65
+ node scripts/matrix-regression-gate.js \
66
+ --baseline .kiro/reports/release-evidence/moqui-template-baseline.json \
67
+ --max-regressions 0 \
68
+ --enforce \
69
+ --json
70
+ ```
71
+
72
+ Recommended GitHub Variables:
73
+
74
+ - `KSE_MATRIX_REGRESSION_GATE_ENFORCE=true`
75
+ - `KSE_MATRIX_REGRESSION_GATE_MAX=0`
76
+ - `KSE_MOQUI_RELEASE_SUMMARY_ENFORCE=true` (optional hard gate for release summary `failed` state)
77
+
78
+ Security baseline:
79
+
80
+ - Apply default controls in `docs/security-governance-default-baseline.md`.
81
+ - Keep context contract strict mode enabled in production integration.
82
+
83
+ ## 5. Evidence Artifacts (Must Keep)
84
+
85
+ - `.kiro/reports/interactive-governance-report.json`
86
+ - `.kiro/reports/interactive-governance-report.md`
87
+ - `.kiro/reports/interactive-matrix-signals.jsonl`
88
+ - `.kiro/reports/release-evidence/moqui-template-baseline.json`
89
+ - `.kiro/reports/release-evidence/matrix-regression-gate-<tag>.json`
90
+ - `.kiro/reports/release-evidence/matrix-remediation-plan-<tag>.json`
91
+ - `.kiro/reports/release-evidence/matrix-remediation-<tag>.lines`
92
+ - `.kiro/reports/release-evidence/matrix-remediation-high-<tag>.lines`
93
+ - `.kiro/reports/release-evidence/matrix-remediation-medium-<tag>.lines`
94
+ - `.kiro/reports/release-evidence/matrix-remediation-goals-high-<tag>.json`
95
+ - `.kiro/reports/release-evidence/matrix-remediation-goals-medium-<tag>.json`
96
+ - `.kiro/reports/release-evidence/matrix-remediation-phased-plan-<tag>.json`
97
+ - `.kiro/reports/release-evidence/weekly-ops-summary-<tag>.json`
98
+ - `.kiro/reports/release-evidence/weekly-ops-summary-<tag>.md`
99
+
100
+ ## 6. Pass Criteria
101
+
102
+ - `interactive-flow.summary.status` is `completed` or `ready-for-apply` by policy.
103
+ - Governance summary status is `ok` (no medium/high breach).
104
+ - Matrix regression gate status is `passed` (or enforced policy satisfied).
105
+ - Release summary status is `passed` or explicitly approved when `incomplete`.
106
+
107
+ ## 7. Remediation Loop
108
+
109
+ When matrix regressions are detected:
110
+
111
+ ```bash
112
+ node scripts/moqui-matrix-remediation-queue.js \
113
+ --baseline .kiro/reports/release-evidence/moqui-template-baseline.json \
114
+ --lines-out .kiro/auto/matrix-remediation.lines \
115
+ --batch-json-out .kiro/auto/matrix-remediation.goals.json \
116
+ --commands-out .kiro/reports/release-evidence/matrix-remediation-commands.md \
117
+ --json
118
+
119
+ # anti-429 phased mode (recommended default)
120
+ sce auto close-loop-batch .kiro/auto/matrix-remediation.goals.high.json \
121
+ --format json \
122
+ --batch-parallel 1 \
123
+ --batch-agent-budget 2 \
124
+ --batch-retry-until-complete \
125
+ --batch-retry-max-rounds 3 \
126
+ --json
127
+ sleep 30
128
+ sce auto close-loop-batch .kiro/auto/matrix-remediation.goals.medium.json \
129
+ --format json \
130
+ --batch-parallel 1 \
131
+ --batch-agent-budget 2 \
132
+ --batch-retry-until-complete \
133
+ --batch-retry-max-rounds 2 \
134
+ --json
135
+
136
+ # one-shot equivalent
137
+ npm run run:matrix-remediation-phased -- --json
138
+
139
+ # zero-prep one-shot (prepare from baseline + run phased)
140
+ node scripts/moqui-matrix-remediation-phased-runner.js \
141
+ --baseline .kiro/reports/release-evidence/moqui-template-baseline.json \
142
+ --json
143
+ npm run run:matrix-remediation-from-baseline -- --json
144
+
145
+ # fallback
146
+ sce auto close-loop-batch .kiro/auto/matrix-remediation.lines --json
147
+ sce auto close-loop-batch .kiro/auto/matrix-remediation.goals.json --format json --json
148
+ ```
@@ -0,0 +1,354 @@
1
+ # Interactive Customization Contracts
2
+
3
+ This directory contains baseline contracts and safety policy artifacts for the interactive business customization model.
4
+
5
+ ## Files
6
+
7
+ - `change-intent.schema.json`: schema for business-level change intents generated from UI copilot conversations.
8
+ - `change-plan.schema.json`: schema for structured change plans (scope, risk, checks, rollback).
9
+ - `execution-record.schema.json`: schema for execution/audit records.
10
+ - `page-context.schema.json`: schema for page-level read-only context payloads.
11
+ - `guardrail-policy-baseline.json`: default secure-by-default guardrail policy.
12
+ - `dialogue-governance-policy-baseline.json`: baseline communication rules for embedded assistant dialogue.
13
+ - `runtime-mode-policy-baseline.json`: baseline runtime mode/environment policy (`user-assist|ops-fix|feature-dev` x `dev|staging|prod`).
14
+ - `high-risk-action-catalog.json`: baseline high-risk action classification for deny/review decisions.
15
+ - `change-plan.sample.json`: runnable sample plan for gate checks.
16
+ - `page-context.sample.json`: runnable page context sample for read-only intent generation.
17
+ - `moqui-context-provider.sample.json`: sample raw payload from Moqui workbench context provider (before normalization).
18
+ - `moqui-copilot-context-contract.json`: Moqui page context contract + security boundary baseline.
19
+ - `moqui-copilot-integration-guide.md`: stage-A Moqui integration guide for page-level copilot embedding.
20
+ - `moqui-adapter-interface.md`: stage-C Moqui adapter contract (`capabilities/plan/validate/apply/rollback`).
21
+ - `moqui-interactive-template-playbook.md`: stage-D template sedimentation playbook for Moqui interactive loop.
22
+ - `adapter-extension-contract.schema.json`: cross-stack adapter extension contract schema.
23
+ - `adapter-extension-contract.sample.json`: adapter extension contract sample payload.
24
+ - `adapter-extension-contract.md`: adapter extension contract guide and conformance checklist.
25
+ - `domain-pack-extension-flow.md`: Domain_Pack extension flow for cross-industry replication.
26
+ - `governance-threshold-baseline.json`: governance KPI threshold baseline for alerting.
27
+ - `governance-report-template.md`: periodic governance report template.
28
+ - `governance-alert-playbook.md`: threshold breach response workflow.
29
+ - `phase-acceptance-evidence.md`: stage A/B/C/D acceptance evidence checklist.
30
+ - `non-technical-usability-report.md`: business-user usability assessment and improvement backlog.
31
+ - `cross-industry-replication-guide.md`: replication boundary and rollout sequence beyond Moqui.
32
+ - `331-poc-sce-integration-checklist.md`: minimal production checklist for embedding SCE interactive flow in 331-poc.
33
+
34
+ ## Usage
35
+
36
+ Validate a plan against guardrails:
37
+
38
+ ```bash
39
+ node scripts/interactive-change-plan-gate.js \
40
+ --plan docs/interactive-customization/change-plan.sample.json \
41
+ --json
42
+ ```
43
+
44
+ Use strict CI gating:
45
+
46
+ ```bash
47
+ node scripts/interactive-change-plan-gate.js \
48
+ --plan path/to/change-plan.json \
49
+ --fail-on-non-allow \
50
+ --json
51
+ ```
52
+
53
+ Normalize Moqui workbench payload into standard page-context:
54
+
55
+ ```bash
56
+ node scripts/interactive-context-bridge.js \
57
+ --input docs/interactive-customization/moqui-context-provider.sample.json \
58
+ --context-contract docs/interactive-customization/moqui-copilot-context-contract.json \
59
+ --json
60
+ ```
61
+
62
+ Bridge output defaults:
63
+
64
+ - Normalized page-context: `.kiro/reports/interactive-page-context.normalized.json`
65
+ - Bridge report: `.kiro/reports/interactive-context-bridge.json`
66
+
67
+ Run one-command full flow (bridge -> loop):
68
+
69
+ ```bash
70
+ node scripts/interactive-flow.js \
71
+ --input docs/interactive-customization/moqui-context-provider.sample.json \
72
+ --goal "Adjust order screen field layout for clearer input flow" \
73
+ --runtime-mode ops-fix \
74
+ --runtime-environment staging \
75
+ --context-contract docs/interactive-customization/moqui-copilot-context-contract.json \
76
+ --dialogue-policy docs/interactive-customization/dialogue-governance-policy-baseline.json \
77
+ --runtime-policy docs/interactive-customization/runtime-mode-policy-baseline.json \
78
+ --execution-mode apply \
79
+ --auto-execute-low-risk \
80
+ --auth-password-hash "<sha256-of-demo-pass>" \
81
+ --auth-password "demo-pass" \
82
+ --feedback-score 5 \
83
+ --json
84
+ ```
85
+
86
+ Matrix stage behavior (enabled by default in `interactive-flow`):
87
+
88
+ - Runs `moqui-template-baseline-report` after loop stage to snapshot template matrix status.
89
+ - Writes session artifacts and appends a global matrix signal stream.
90
+ - Use `--no-matrix` to disable this stage for diagnostics.
91
+
92
+ Common matrix flags:
93
+
94
+ - `--matrix-min-score <0..100>`
95
+ - `--matrix-min-valid-rate <0..100>`
96
+ - `--matrix-compare-with <path>`
97
+ - `--matrix-signals <path>`
98
+ - `--matrix-fail-on-portfolio-fail`
99
+ - `--matrix-fail-on-regression`
100
+
101
+ Flow output defaults:
102
+
103
+ - Flow summary: `.kiro/reports/interactive-flow/<session-id>/interactive-flow.summary.json`
104
+ - Bridge context: `.kiro/reports/interactive-flow/<session-id>/interactive-page-context.normalized.json`
105
+ - Loop summary: `.kiro/reports/interactive-flow/<session-id>/interactive-customization-loop.summary.json`
106
+ - Dialogue governance report: `.kiro/reports/interactive-flow/<session-id>/interactive-dialogue-governance.json`
107
+ - Matrix summary JSON: `.kiro/reports/interactive-flow/<session-id>/moqui-template-baseline.json`
108
+ - Matrix summary Markdown: `.kiro/reports/interactive-flow/<session-id>/moqui-template-baseline.md`
109
+ - Matrix signal stream: `.kiro/reports/interactive-matrix-signals.jsonl`
110
+
111
+ Build read-only change intent from page context:
112
+
113
+ ```bash
114
+ node scripts/interactive-intent-build.js \
115
+ --context docs/interactive-customization/page-context.sample.json \
116
+ --goal "Must improve order approval speed without changing payment authorization policy" \
117
+ --context-contract docs/interactive-customization/moqui-copilot-context-contract.json \
118
+ --user-id demo-user \
119
+ --json
120
+ ```
121
+
122
+ Generate a change plan from intent (suggestion stage):
123
+
124
+ ```bash
125
+ node scripts/interactive-plan-build.js \
126
+ --intent .kiro/reports/interactive-change-intent.json \
127
+ --context docs/interactive-customization/page-context.sample.json \
128
+ --json
129
+ ```
130
+
131
+ Run dialogue governance (communication-rule check only):
132
+
133
+ ```bash
134
+ node scripts/interactive-dialogue-governance.js \
135
+ --goal "Improve order entry speed without changing payment policy" \
136
+ --context docs/interactive-customization/page-context.sample.json \
137
+ --policy docs/interactive-customization/dialogue-governance-policy-baseline.json \
138
+ --json
139
+ ```
140
+
141
+ Run one-command interactive loop (intent -> plan -> gate -> approval; optional low-risk apply):
142
+
143
+ ```bash
144
+ # suggestion-first loop (no apply)
145
+ node scripts/interactive-customization-loop.js \
146
+ --context docs/interactive-customization/page-context.sample.json \
147
+ --context-contract docs/interactive-customization/moqui-copilot-context-contract.json \
148
+ --goal "Improve order entry clarity for business users" \
149
+ --json
150
+
151
+ # low-risk one-click apply loop
152
+ node scripts/interactive-customization-loop.js \
153
+ --context docs/interactive-customization/page-context.sample.json \
154
+ --context-contract docs/interactive-customization/moqui-copilot-context-contract.json \
155
+ --goal "Adjust order screen field layout for clearer input flow" \
156
+ --runtime-mode ops-fix \
157
+ --runtime-environment staging \
158
+ --runtime-policy docs/interactive-customization/runtime-mode-policy-baseline.json \
159
+ --execution-mode apply \
160
+ --auto-execute-low-risk \
161
+ --auth-password-hash "<sha256-of-demo-pass>" \
162
+ --auth-password "demo-pass" \
163
+ --feedback-score 5 \
164
+ --feedback-comment "Flow is clearer and faster." \
165
+ --feedback-tags moqui,approval \
166
+ --json
167
+
168
+ # CLI equivalent
169
+ sce scene interactive-loop \
170
+ --context docs/interactive-customization/page-context.sample.json \
171
+ --context-contract docs/interactive-customization/moqui-copilot-context-contract.json \
172
+ --goal "Adjust order screen field layout for clearer input flow" \
173
+ --execution-mode apply \
174
+ --auto-execute-low-risk \
175
+ --auth-password-hash "<sha256-of-demo-pass>" \
176
+ --auth-password "demo-pass" \
177
+ --feedback-score 5 \
178
+ --json
179
+ ```
180
+
181
+ `--feedback-score` writes feedback into both:
182
+ - Session artifact: `.kiro/reports/interactive-loop/<session-id>/interactive-user-feedback.jsonl`
183
+ - Governance global stream: `.kiro/reports/interactive-user-feedback.jsonl`
184
+ - Context contract validation is strict by default (required fields, payload size, forbidden keys). Use `--no-strict-contract` only for temporary diagnostics.
185
+ - `--execution-mode apply` with mutating actions requires password authorization by default (`plan.authorization.password_required=true`).
186
+ - Runtime policy defaults to `ops-fix@staging`; low-risk auto execute requires runtime decision `allow`.
187
+
188
+ Run runtime mode/environment policy evaluation directly:
189
+
190
+ ```bash
191
+ node scripts/interactive-runtime-policy-evaluate.js \
192
+ --plan .kiro/reports/interactive-change-plan.generated.json \
193
+ --runtime-mode ops-fix \
194
+ --runtime-environment staging \
195
+ --policy docs/interactive-customization/runtime-mode-policy-baseline.json \
196
+ --json
197
+ ```
198
+
199
+ Build interactive work-order artifacts directly:
200
+
201
+ ```bash
202
+ node scripts/interactive-work-order-build.js \
203
+ --plan .kiro/reports/interactive-change-plan.generated.json \
204
+ --dialogue .kiro/reports/interactive-dialogue-governance.json \
205
+ --gate .kiro/reports/interactive-change-plan-gate.json \
206
+ --runtime .kiro/reports/interactive-runtime-policy.json \
207
+ --approval-state .kiro/reports/interactive-approval-state.json \
208
+ --execution-attempted \
209
+ --execution-result success \
210
+ --execution-id exec-xxxx \
211
+ --json
212
+ ```
213
+
214
+ Run approval workflow state machine:
215
+
216
+ ```bash
217
+ # init from generated plan
218
+ node scripts/interactive-approval-workflow.js \
219
+ --action init \
220
+ --plan .kiro/reports/interactive-change-plan.generated.json \
221
+ --actor product-owner \
222
+ --json
223
+
224
+ # submit -> approve -> execute -> verify
225
+ node scripts/interactive-approval-workflow.js --action submit --actor product-owner --json
226
+ node scripts/interactive-approval-workflow.js --action approve --actor security-admin --json
227
+ node scripts/interactive-approval-workflow.js --action execute --actor release-operator --password "demo-pass" --json
228
+ node scripts/interactive-approval-workflow.js --action verify --actor qa-owner --json
229
+ ```
230
+
231
+ Run the Moqui adapter interface (`capabilities/plan/validate/apply/rollback`):
232
+
233
+ ```bash
234
+ # show adapter capability + risk declaration
235
+ node scripts/interactive-moqui-adapter.js \
236
+ --action capabilities \
237
+ --json
238
+
239
+ # build plan from intent through adapter contract
240
+ node scripts/interactive-moqui-adapter.js \
241
+ --action plan \
242
+ --intent .kiro/reports/interactive-change-intent.json \
243
+ --execution-mode suggestion \
244
+ --json
245
+
246
+ # validate/apply with policy gate and execution record output
247
+ node scripts/interactive-moqui-adapter.js \
248
+ --action validate \
249
+ --plan .kiro/reports/interactive-change-plan.adapter.json \
250
+ --json
251
+ node scripts/interactive-moqui-adapter.js \
252
+ --action apply \
253
+ --plan .kiro/reports/interactive-change-plan.adapter.json \
254
+ --json
255
+
256
+ # one-click path: only accepts low-risk + allow decision
257
+ node scripts/interactive-moqui-adapter.js \
258
+ --action low-risk-apply \
259
+ --plan .kiro/reports/interactive-change-plan.adapter.json \
260
+ --json
261
+
262
+ # rollback by execution id from execution ledger
263
+ node scripts/interactive-moqui-adapter.js \
264
+ --action rollback \
265
+ --execution-id exec-xxxx \
266
+ --json
267
+ ```
268
+
269
+ Execution artifacts:
270
+
271
+ - Latest execution record: `.kiro/reports/interactive-execution-record.latest.json`
272
+ - Append-only execution ledger: `.kiro/reports/interactive-execution-ledger.jsonl`
273
+ - Execution records include diff summary, gate decision, validation snapshot, and rollback reference.
274
+
275
+ Append business-user feedback for governance scoring:
276
+
277
+ ```bash
278
+ node scripts/interactive-feedback-log.js \
279
+ --score 5 \
280
+ --comment "Approval flow is clearer and faster." \
281
+ --user-id demo-user \
282
+ --session-id session-20260219 \
283
+ --intent-id intent-xxxx \
284
+ --plan-id plan-xxxx \
285
+ --execution-id exec-xxxx \
286
+ --tags moqui,approval \
287
+ --product moqui-suite \
288
+ --module order \
289
+ --page approval \
290
+ --scene-id scene-moqui-interactive \
291
+ --json
292
+ ```
293
+
294
+ Generate governance KPI report and threshold alerts:
295
+
296
+ ```bash
297
+ node scripts/interactive-governance-report.js \
298
+ --period weekly \
299
+ --json
300
+ ```
301
+
302
+ The governance report consumes feedback events from `.kiro/reports/interactive-user-feedback.jsonl` by default.
303
+ The governance report also consumes matrix signals from `.kiro/reports/interactive-matrix-signals.jsonl` by default.
304
+ When `intent_total` is below `min_intent_samples` (default `5`), adoption emits a low-severity sample warning instead of a breach.
305
+
306
+ Export matrix regression remediation queue lines (for close-loop-batch):
307
+
308
+ ```bash
309
+ node scripts/moqui-matrix-remediation-queue.js \
310
+ --baseline .kiro/reports/release-evidence/moqui-template-baseline.json \
311
+ --top-templates 5 \
312
+ --lines-out .kiro/auto/matrix-remediation.lines \
313
+ --batch-json-out .kiro/auto/matrix-remediation.goals.json \
314
+ --commands-out .kiro/reports/release-evidence/matrix-remediation-commands.md \
315
+ --json
316
+ ```
317
+
318
+ Recommended anti-429 phased execution (default outputs):
319
+
320
+ ```bash
321
+ sce auto close-loop-batch .kiro/auto/matrix-remediation.goals.high.json \
322
+ --format json \
323
+ --batch-parallel 1 \
324
+ --batch-agent-budget 2 \
325
+ --batch-retry-until-complete \
326
+ --batch-retry-max-rounds 3 \
327
+ --json
328
+
329
+ sleep 30
330
+
331
+ sce auto close-loop-batch .kiro/auto/matrix-remediation.goals.medium.json \
332
+ --format json \
333
+ --batch-parallel 1 \
334
+ --batch-agent-budget 2 \
335
+ --batch-retry-until-complete \
336
+ --batch-retry-max-rounds 2 \
337
+ --json
338
+ ```
339
+
340
+ One-shot equivalent:
341
+
342
+ ```bash
343
+ npm run run:matrix-remediation-phased -- --json
344
+ ```
345
+
346
+ Zero-prep one-shot (prepare from baseline + run phased):
347
+
348
+ ```bash
349
+ node scripts/moqui-matrix-remediation-phased-runner.js \
350
+ --baseline .kiro/reports/release-evidence/moqui-template-baseline.json \
351
+ --json
352
+
353
+ npm run run:matrix-remediation-from-baseline -- --json
354
+ ```
@@ -0,0 +1,55 @@
1
+ # Adapter Extension Contract
2
+
3
+ This document defines the cross-stack adapter contract used to onboard new runtimes without changing core guardrail workflow.
4
+
5
+ ## Purpose
6
+
7
+ - Keep `Change_Intent -> Change_Plan -> Gate -> Approval -> Apply -> Rollback` flow unchanged.
8
+ - Allow runtime-specific execution via adapter modules.
9
+ - Guarantee governance compatibility by contract instead of ad-hoc integration.
10
+
11
+ ## Contract Artifacts
12
+
13
+ - Schema: `docs/interactive-customization/adapter-extension-contract.schema.json`
14
+ - Sample: `docs/interactive-customization/adapter-extension-contract.sample.json`
15
+
16
+ ## Mandatory Sections
17
+
18
+ 1. `capability_declaration`
19
+ - Declare supported change types.
20
+ - Declare runtime prerequisites.
21
+
22
+ 2. `risk_declaration`
23
+ - Declare default execution mode (`suggestion` or `apply`).
24
+ - Declare auto-apply risk levels.
25
+ - Declare blocked action types.
26
+
27
+ 3. `interfaces`
28
+ - Must implement:
29
+ - `capabilities()`
30
+ - `plan(changeIntent, context)`
31
+ - `validate(changePlan)`
32
+ - `apply(changePlan)`
33
+ - `rollback(executionId)`
34
+
35
+ 4. `compliance`
36
+ - Must declare compatibility with:
37
+ - guardrail policy
38
+ - approval workflow
39
+ - rollback support
40
+ - Must declare audit record schema linkage.
41
+
42
+ ## Runtime Integration Rules
43
+
44
+ - Adapter must not bypass policy gate.
45
+ - Adapter must not bypass approval state machine for review/high risk plans.
46
+ - Adapter must emit execution records compatible with:
47
+ - `docs/interactive-customization/execution-record.schema.json`
48
+
49
+ ## Conformance Checklist
50
+
51
+ - Contract JSON validates against extension schema.
52
+ - `validate()` returns `allow | review-required | deny`.
53
+ - `apply()` writes execution record and append-only ledger.
54
+ - `rollback()` writes rollback execution record linked by `rollback_ref`.
55
+ - High-risk destructive actions stay blocked by default.