scene-capability-engine 3.6.32 → 3.6.37

package/docs/magicball-integration-issue-tracker.md

@@ -0,0 +1,218 @@
+# MagicBall Integration Issue Tracker
+
+> This file is the narrow coordination document between MagicBall and SCE.
+> It is used to record only the minimum integration facts that require cross-project synchronization: active issues, contract gaps, decisions, and verification results.
+> When SCE completes a relevant change that MagicBall needs to know about, the update should be synced here.
+> Once an item is verified and no longer needs cross-project coordination, it should be removed or compacted to avoid the file becoming too large, too noisy, or too hard to maintain.
+
+## Usage Rule
+
+- Keep this file narrow.
+- Add only cross-project integration facts.
+- Prefer short status-oriented records over long design discussion.
+- Move completed items to `Resolved` or remove them once both sides no longer need them.
+
+## Current Contract
+
+### Current SCE capabilities ready for MagicBall integration
+
+SCE changes completed and now available for MagicBall:
+- `app bundle` registry local state and CLI
+- `mode application home --app ... --json`
+- `mode ontology home --app ... --json`
+- `mode engineering home --app ... --json`
+- `app registry status/configure/sync*`
+- `app runtime show/releases/install/activate`
+- `app engineering show/attach/hydrate/activate`
+- `pm requirement/tracking/planning/change/issue` data plane
+- `ontology er/br/dl` + `ontology triad summary`
+- `ontology seed list/show/apply`
+- `assurance resource/logs/backup/config`
+- MagicBall-facing docs updated under `docs/`
+
+### Current recommended MagicBall consumption order
+1. consume `mode * home` as the top-level source for the three modes
+2. consume `pm`, `ontology`, and `assurance` table payloads
+3. wire runtime install/activate and engineering attach/hydrate/activate actions
+4. use demo app: `customer-order-demo`
+
+### Related SCE docs
+- `docs/magicball-sce-adaptation-guide.md`
+- `docs/magicball-write-auth-adaptation-guide.md`
+- `docs/magicball-adaptation-task-checklist-v1.md`
+- `docs/magicball-mode-home-and-ontology-empty-state-playbook.md`
+- `docs/magicball-frontend-state-and-command-mapping.md`
+- `docs/magicball-ui-surface-checklist.md`
+- `docs/magicball-integration-doc-index.md`
+- `docs/magicball-cli-invocation-examples.md`
+- these docs now explicitly capture:
+  - current entry docs vs secondary references vs historical drafts are now separated in `docs/magicball-integration-doc-index.md`
+  - serialized `mode * home` loading as the safe default during `Issue 001` verification
+  - `fallback + optional seed apply` as the recommended default for fresh-project ontology UX under `Issue 003`
+
+### Next Needed From MagicBall
+1. treat the current doc set as stable and move into feedback-driven integration using the current entry docs
+2. continue real integration against `customer-order-demo` for all three `mode * home` pages
+3. keep `mode home` requests serialized during current verification window
+4. keep fresh-ontology UX on `fallback + optional seed apply`:
+   - MagicBall local UI now renders starter seed guidance + preview + explicit apply
+   - `ontology seed apply` is wired through shared write auth using scope `ontology:seed:apply`
+   - keep this item open only for wider field verification, not for strategy selection
+5. if any new integration mismatch appears, record it in `Open Items` with:
+   - exact command
+   - workspace path
+   - current payload
+   - expected payload
+   - UI impact
+
+## Open Items
+
+### Issue 001: SQLite lock when frontend triggers multiple SCE projection commands concurrently
+
+Context:
+- Project: `E:\workspace\331-poc`
+- Upstream docs referenced from: `E:\workspace\kiro-spec-engine\docs`
+- SCE local source version observed: `3.6.34`
+
+Observed behavior:
+- When multiple `sce mode ... home --json` commands are triggered concurrently, frontend occasionally receives:
+  - `database is locked`
+
+Concrete command involved:
+- `sce mode application home --app customer-order-demo --json`
+
+Related commands that were being loaded together:
+- `sce mode application home --app customer-order-demo --json`
+- `sce mode ontology home --app customer-order-demo --json`
+- `sce mode engineering home --app customer-order-demo --json`
+- `sce app engineering show --app customer-order-demo --json`
+
+MagicBall action taken:
+- Changed mode-home loading from parallel to sequential in local store.
+- MagicBall now serializes:
+  1. application home
+  2. ontology home
+  3. engineering home
+  4. engineering show
+
+SCE action taken:
+- Added short read retry handling for retryable sqlite lock errors on app/mode/pm/ontology/assurance read paths.
+- Added short-lived `mode home` projection cache to reduce repeated reads for the same app/projection in a short window.
+- Goal: reduce transient `database is locked` failures for read-heavy MagicBall integration flows.
+
+Current cross-project decision:
+- Keep sequential frontend loading as the current safe default.
+- Treat SCE read retry + projection cache as mitigation, not as permission to switch back to parallel loading immediately.
+
+Status:
+- MagicBall workaround applied
+- SCE mitigation applied
+- still needs wider real-world verification before considering this fully closed
+
+### Issue 003: ontology ER/BR/DL data planes are command-ready but currently empty by default
+
+Context:
+- Project: `E:\workspace\331-poc`
+- SCE source: `E:\workspace\kiro-spec-engine`
+- Commands verified:
+  - `npx sce ontology er list --json`
+  - `npx sce ontology br list --json`
+  - `npx sce ontology dl list --json`
+  - `npx sce ontology triad summary --json`
+
+Observed behavior:
+- ER/BR/DL list commands are stable and return table payloads with `view_model.columns`
+- but all three currently return empty item arrays in the default local state
+- triad summary returns valid shape but zero coverage / all triads missing unless MagicBall applies fallback or the project creates real ontology assets
+
+Impact on MagicBall:
+- frontend can safely wire read flows now
+- but user-visible ontology pages need either sample fallback, a create flow, or starter seed data to avoid blank pages in fresh projects
+- triad completeness currently depends on newly created assets or fallback data
+
+Current cross-project decision:
+- treat empty ontology state as expected for fresh/local projects
+- SCE now provides built-in starter seed support for `customer-order-demo`
+- `ontology triad summary` and `mode ontology home` now also return `starter_seed` guidance when ontology is empty
+- MagicBall local UI now uses `fallback + optional seed apply` as the default policy
+- starter seed preview is driven by `sce ontology seed list/show --json`
+- explicit initialization is driven by `sce ontology seed apply --profile <profile> --auth-lease <lease-id> --json`
+
+Relevant commands:
+- `sce ontology seed list --json`
+- `sce ontology seed show --profile customer-order-demo --json`
+- `sce ontology seed apply --profile customer-order-demo --json`
+
+Status:
+- frontend read path ready
+- ontology write/read loop already verified working
+- starter seed support implemented in SCE
+- payload-level `starter_seed` guidance implemented in SCE
+- MagicBall starter seed preview/apply UI implemented locally in `E:\workspace\331-poc\frontend\src\renderer\components\ontology\OntologyStarterSeedPanel.vue`
+- empty-ontology flow reverified locally on 2026-03-08 in `E:\workspace\331-poc\tmp\sce-empty-ontology-repro`
+- local verification covered: `triad summary` empty -> `seed list/show` preview -> `seed apply` -> `triad summary` ready
+- keep open until broader field verification confirms the UX is stable
+
+## Resolved
+
+### Issue 002: pm requirement upsert succeeds but requirement list still returns empty
+
+Resolution:
+- Reproduced against current source and CLI smoke path.
+- Current behavior is now correct.
+- `pm requirement upsert` followed by `pm requirement list` returns the newly written item in the same workspace context.
+
+Status:
+- resolved on current SCE source
+- keep closed unless MagicBall can reproduce with exact workspace path and command path
+
+### Issue 004: pm tracking/issue upsert succeeds but board queries still return empty
+
+Resolution:
+- Reproduced against current source and CLI smoke path.
+- Current behavior is now correct.
+- `pm tracking upsert` followed by `pm tracking board` returns the newly written item in the same workspace context.
+- `pm issue upsert` followed by `pm issue board` returns the newly written item in the same workspace context.
+
+Status:
+- resolved on current SCE source
+- keep closed unless MagicBall can reproduce with exact workspace path and command path
+
+### Issue 005: pm planning/change list results lag after upsert and can hide the newest local row
+
+Resolution:
+- Reproduced against current source and CLI smoke path.
+- Current behavior is now correct.
+- `pm planning upsert` followed by `pm planning board` returns the newest row first.
+- `pm change upsert` followed by `pm change list` returns the newest row first.
+
+Status:
+- resolved on current SCE source
+- keep closed unless MagicBall can reproduce with exact workspace path, input payloads, and command path
+
+### Verification 001: ontology ER/BR/DL upsert + list round-trip works in current SCE
+
+Observed result:
+- all three upsert commands return `success: true`
+- all three corresponding list commands immediately show the inserted item
+
+Implication for MagicBall:
+- ontology ER/BR/DL minimal write forms can rely on post-save refresh
+- optimistic fallback is optional for ontology write/read loops
+
+Status:
+- verified working
+### Verification 002: pm requirement/tracking/planning/change/issue round-trip works in current `331-poc`
+
+Observed result:
+- local repro on 2026-03-08 shows `requirement`, `tracking`, `planning`, `change`, and `issue` writes all appear on immediate follow-up list/board reads
+- this revalidation was executed in `E:\workspace\331-poc`
+- write payloads used current SCE-required minimal fields rather than older placeholder payloads
+
+Implication for MagicBall:
+- keep optimistic local UI fallback as a defensive strategy
+- but current local evidence no longer shows stale read-after-write behavior for these PM objects
+
+Status:
+- verified working in current local context
+

package/docs/magicball-mode-home-and-ontology-empty-state-playbook.md

@@ -0,0 +1,249 @@
+# MagicBall Mode Home And Ontology Empty-State Playbook
+
+## Goal
+
+Provide a small, implementation-ready playbook for MagicBall frontend integration around the two remaining active cross-project items:
+1. serialized mode-home loading during `Issue 001` verification
+2. fresh-project ontology empty-state handling for `Issue 003`
+
+This document is intentionally narrower than the main adaptation guide.
+It should be used by frontend engineers who are wiring the actual page behavior.
+
+## When To Use This Playbook
+
+Use this playbook when MagicBall is:
+- opening an app workspace
+- switching between `application`, `ontology`, and `engineering` mode
+- rendering a fresh project that has no ontology assets yet
+- deciding whether and when to show starter seed initialization
+
+## Default Product Decisions
+
+Current recommended defaults are:
+- `mode * home` reads stay serialized
+- fresh ontology pages use `fallback + optional seed apply`
+- seed is never auto-applied silently on first load
+
+These defaults should remain in place until `docs/magicball-integration-issue-tracker.md` explicitly closes the relevant open item.
+
+## Part 1: Serialized Mode-Home Loading
+
+### Why
+
+SCE already includes sqlite read-retry and a short-lived projection cache.
+That reduces transient lock failures, but it is not yet a signal that MagicBall should fan out home projections in parallel.
+
+During current verification:
+- frontend stability is more valuable than a small reduction in page bootstrap latency
+- the safest contract is one request at a time
+
+### Required Load Order
+
+When opening an app page, MagicBall should call these commands in order:
+
+1. `sce mode application home --app <app-key> --json`
+2. `sce mode ontology home --app <app-key> --json`
+3. `sce mode engineering home --app <app-key> --json`
+4. `sce app engineering show --app <app-key> --json`
+
+### Frontend State Rule
+
+Treat each call as one step in a small boot pipeline.
+Do not issue step 2 before step 1 resolves.
+Do not issue step 3 before step 2 resolves.
+Do not issue step 4 before step 3 resolves.
+
+Recommended local state shape:
+
+```ts
+interface ModeBootState {
+  appKey: string
+  bootStatus: 'idle' | 'loading' | 'partial' | 'ready' | 'failed'
+  activeStep: 'application-home' | 'ontology-home' | 'engineering-home' | 'engineering-show' | null
+  completedSteps: string[]
+  lastError: string | null
+}
+```
+
+### Recommended UX
+
+During boot:
+- show top-level shell immediately
+- reveal each mode card/section as its payload arrives
+- if step 3 or step 4 fails, keep already-loaded earlier sections visible
+- avoid a full-screen hard failure unless step 1 fails
+
+Recommended status copy:
+- step 1 loading: `Loading application view...`
+- step 2 loading: `Loading ontology view...`
+- step 3 loading: `Loading engineering view...`
+- step 4 loading: `Loading engineering workspace details...`
+
+### Failure Handling
+
+If a step fails:
+- preserve all previously loaded payloads
+- store the exact failing command and stderr text
+- show a retry action for the failed step only
+- do not automatically restart the full four-step sequence unless the app context changed
+
+Recommended retry behavior:
+- retry the failed step once on explicit user action
+- if the step still fails, keep the shell usable and surface the exact command failure
+
+### What Not To Do
+
+Do not:
+- switch back to `Promise.all(...)` style mode-home loading
+- merge multiple raw payloads and pretend they are one synthetic source
+- hide the exact failed step from the user
+
+## Part 2: Fresh Ontology Empty-State Policy
+
+### Why
+
+A fresh/local project can legitimately have:
+- zero ER assets
+- zero BR rules
+- zero DL chains
+- zero triad coverage
+
+That is not a backend failure.
+It is an expected empty workspace state.
+
+### Product Rule
+
+MagicBall should use:
+- explanatory empty state first
+- optional starter seed second
+
+That means:
+- the first ontology page render explains why the page is empty
+- the page reads `starter_seed` guidance from SCE payloads
+- the user can explicitly choose to initialize starter data
+- the page never seeds ontology data automatically without user intent
+
+### Inputs MagicBall Should Read
+
+Primary inputs:
+- `sce mode ontology home --app <app-key> --json`
+- `sce ontology triad summary --json`
+- `sce ontology er list --json`
+- `sce ontology br list --json`
+- `sce ontology dl list --json`
+
+Optional seed inputs:
+- `sce ontology seed list --json`
+- `sce ontology seed show --profile customer-order-demo --json`
+
+Mutation:
+- `sce ontology seed apply --profile customer-order-demo --json`
+
+### Empty-State Trigger
+
+Treat ontology as empty when both conditions hold:
+- ER/BR/DL lists have no items
+- ontology summary or triad summary indicates missing / zero coverage state
+
+The frontend should not require a single exact boolean from one endpoint if the table/list payloads already prove the workspace is empty.
+
+### Recommended UI Layout
+
+Top section:
+- keep ontology summary / triad summary visible
+- if available, surface `starter_seed` guidance text from SCE
+
+Main empty-state card:
+- title: `Ontology is not initialized yet`
+- description: `This is expected for a fresh or local project. You can start from an empty model or initialize starter ontology data.`
+- primary action: `Initialize starter ontology`
+- secondary action: `Continue with empty ontology`
+
+Below the card:
+- ER table shell
+- BR table shell
+- DL table shell
+- each table may remain empty but should not look broken
+
+### Seed Confirmation Flow
+
+When the user clicks `Initialize starter ontology`:
+
+1. optionally call `sce ontology seed show --profile customer-order-demo --json`
+2. show what will be initialized
+3. require explicit confirmation
+4. call `sce ontology seed apply --profile customer-order-demo --json`
+5. show progress state until command completes
+
+Recommended confirmation copy:
+- `Initialize starter ontology data for this app?`
+- `This will create starter ER, BR, and DL assets for the current project.`
+
+### Refresh Chain After Seed Apply
+
+After a successful seed apply, refresh in this order:
+
+1. `sce mode ontology home --app <app-key> --json`
+2. `sce ontology triad summary --json`
+3. `sce ontology er list --json`
+4. `sce ontology br list --json`
+5. `sce ontology dl list --json`
+
+Rationale:
+- summary first so the page-level status updates immediately
+- tables second so the user can see concrete assets appear
+
+### Seed Failure Handling
+
+If seed apply fails:
+- keep the empty-state card visible
+- preserve the exact command error for copy/retry
+- do not hide the ontology page or replace it with a generic crash screen
+- let the user retry the seed action or continue with empty ontology
+
+Recommended failure copy:
+- `Starter ontology initialization failed.`
+- `You can retry, inspect the command error, or continue with an empty ontology.`
+
+## Part 3: Suggested Frontend Call Graph
+
+```text
+App Selected
+  -> app bundle show
+  -> application home
+  -> ontology home
+  -> engineering home
+  -> engineering show
+
+Ontology Tab Opened
+  -> ontology home
+  -> triad summary
+  -> er list
+  -> br list
+  -> dl list
+  -> if empty: show starter seed guidance
+
+User Clicks Initialize Starter Ontology
+  -> seed show (optional)
+  -> seed apply
+  -> ontology home
+  -> triad summary
+  -> er list
+  -> br list
+  -> dl list
+```
+
+## Part 4: Minimal Acceptance Checks
+
+MagicBall can consider this playbook implemented when:
+- mode-home calls are serialized by default
+- each boot step has visible progress and isolated retry
+- ontology empty pages no longer look like backend failure states
+- starter seed is explicit and user-triggered
+- post-seed refresh updates both summary cards and ER/BR/DL tables
+
+## Related Docs
+
+- `docs/magicball-sce-adaptation-guide.md`
+- `docs/magicball-adaptation-task-checklist-v1.md`
+- `docs/magicball-integration-issue-tracker.md`

package/docs/magicball-sce-adaptation-guide.md

@@ -0,0 +1,203 @@
+# MagicBall SCE Adaptation Guide
+
+## Goal
+
+Provide the primary overview for MagicBall to integrate the current SCE capability set.
+
+This document is intentionally concise.
+It defines the stable integration shape, command families, and response contracts.
+Implementation detail should live in the specialized documents listed below.
+
+## Primary Companion Docs
+
+Use these documents together:
+- `docs/magicball-integration-doc-index.md`
+- `docs/magicball-ui-surface-checklist.md`
+- `docs/magicball-mode-home-and-ontology-empty-state-playbook.md`
+- `docs/magicball-frontend-state-and-command-mapping.md`
+- `docs/magicball-cli-invocation-examples.md`
+- `docs/magicball-write-auth-adaptation-guide.md`
+- `docs/magicball-task-feedback-timeline-guide.md`
+- `docs/magicball-integration-issue-tracker.md`
+
+## Current Scope
+
+SCE currently provides MagicBall-facing support for:
+1. `app bundle registry`
+2. `application / ontology / engineering home projections`
+3. `app runtime install / activate`
+4. `app engineering attach / hydrate / activate`
+5. `pm` delivery data plane
+6. `ontology` triad data plane
+7. `assurance` data plane
+8. `write authorization`
+9. `task feedback + timeline`
+
+## Core Integration Positioning
+
+### 1. App identity
+
+MagicBall should keep both:
+- `app_id`
+- `app_key`
+
+Recommended rule:
+- use `app_key` as the stable frontend route token
+- keep `app_id` as the bound SCE identity once resolved
+- prefer `app_name` for user-facing display
+
+### 2. Three-mode entry
+
+MagicBall should enter every app through SCE projections, not through frontend-reconstructed relationships.
+
+Top-level entry commands:
+- `sce mode application home --app <app-id|app-key> --json`
+- `sce mode ontology home --app <app-id|app-key> --json`
+- `sce mode engineering home --app <app-id|app-key> --json`
+
+Current default during `Issue 001` verification:
+- load `mode * home` sequentially, not in parallel
+- recommended order:
+  1. `mode application home`
+  2. `mode ontology home`
+  3. `mode engineering home`
+  4. `app engineering show`
+
+### 3. Fresh ontology behavior
+
+Current default during `Issue 003` verification:
+- treat empty ontology as a valid fresh/local project state
+- use `fallback + optional seed apply`
+- do not auto-apply starter seed silently
+- keep seed apply explicit and user-triggered
+
+## Remote Registry Sources
+
+### Bundle Registry
+- repository: `https://github.com/heguangyong/magicball-app-bundle-registry`
+- example app key: `customer-order-demo`
+
+### Service Catalog
+- repository: `https://github.com/heguangyong/magicball-app-service-catalog`
+- example app key: `customer-order-demo`
+
+## Demo Application
+
+Current first integration target:
+- `app_id`: `app.customer-order-demo`
+- `app_key`: `customer-order-demo`
+
+## Command Families
+
+This guide does not repeat full invocation examples.
+Use `docs/magicball-cli-invocation-examples.md` for copy-ready commands.
+
+### Mode entry
+- `sce app bundle show`
+- `sce mode application home`
+- `sce mode ontology home`
+- `sce mode engineering home`
+- `sce app engineering show`
+
+### Runtime and engineering control
+- `sce app runtime show/releases/install/activate`
+- `sce app engineering show/attach/hydrate/activate`
+- `sce app registry status/configure/sync*`
+
+### Engineering data plane
+- `sce pm requirement list/show/upsert`
+- `sce pm tracking board/show/upsert`
+- `sce pm planning board/show/upsert`
+- `sce pm change list/show/upsert`
+- `sce pm issue board/show/upsert`
+
+### Ontology data plane
+- `sce ontology triad summary`
+- `sce ontology er list/show/upsert`
+- `sce ontology br list/show/upsert`
+- `sce ontology dl list/show/upsert`
+- `sce ontology seed list/show/apply`
+
+### Assurance and governance
+- `sce assurance resource status`
+- `sce assurance logs views`
+- `sce assurance backup list`
+- `sce assurance config switches`
+- `sce auth status/grant/revoke`
+
+### Task and timeline
+- `sce studio events`
+- `sce timeline list/show`
+
+## Stable Response Contracts
+
+### 1. Mode-home payloads
+
+MagicBall should treat the three `mode * home` commands as stable page-shell sources.
+
+Common top-level fields:
+- `mode`
+- `query`
+- `summary`
+- `view_model`
+- `mb_status`
+
+Important additional fields vary by mode:
+- `application home`: release/runtime state
+- `ontology home`: `ontology_core_ui`, triad readiness, `starter_seed`
+- `engineering home`: delivery summary, assurance summary, project metadata
+
+### 2. Table payloads
+
+The following command groups follow a stable table-style output:
+- `sce pm * list/board`
+- `sce ontology * list`
+- `sce assurance *`
+
+Expected fields:
+- `mode`
+- `query`
+- `summary`
+- `items`
+- `filters`
+- `sort`
+- `view_model`
+- `mb_status`
+
+Current stable `view_model` shape:
+
+```json
+{
+  "type": "table",
+  "columns": []
+}
+```
+
+MagicBall should use `view_model.columns` as the preferred visible-column contract.
+
+## Recommended Division Of Responsibility
+
+### This guide owns
+- overall integration shape
+- command family boundaries
+- top-level response contracts
+- current default product decisions
+
+### Specialized docs own
+- page-level done criteria: `docs/magicball-ui-surface-checklist.md`
+- frontend state + command mapping: `docs/magicball-frontend-state-and-command-mapping.md`
+- mode-home + ontology empty-state behavior: `docs/magicball-mode-home-and-ontology-empty-state-playbook.md`
+- copy-ready commands: `docs/magicball-cli-invocation-examples.md`
+- write auth behavior: `docs/magicball-write-auth-adaptation-guide.md`
+- task/timeline behavior: `docs/magicball-task-feedback-timeline-guide.md`
+- live cross-project truth: `docs/magicball-integration-issue-tracker.md`
+
+## Practical Conclusion
+
+MagicBall should now integrate SCE in this order:
+1. use `app_key` as the frontend app token
+2. bootstrap the workspace through serialized `mode * home`
+3. render page surfaces from SCE payloads directly
+4. keep ontology empty-state explicit and seed apply optional
+5. keep write flows lease-aware
+6. use task/timeline view contracts instead of raw event-first rendering