ARCADIA-Studio/harness/PLAN.md

First release execution plan

Latest refinement: consult actual installed Capella 7.1, replace the user-rejected horizontal creation/connection rows with a compact contextual palette and inline authoring, independently critique interaction risks, then build and verify the real workflow at wide/minimum sizes. Benchmark and concrete acceptance. Do not ship the rejected toolbar as the usability correction.

Current priority (7 September): the user's usability correction takes precedence over the advanced feature sequence below. Establish contextual named diagram creation, existing-element placement, basic editing and clear layer transitions, then verify them natively. Desktop checks were explicitly reauthorized. See priority reset and acceptance.

Outcome and baseline

Deliver the first release of Arcadia Studio for system engineers: complete Operational Analysis and System Analysis/System Architecture workflows, equivalent graphical and textual models, clear artifact traceability and a deployable/programmatically accessible Rust service. Logical/Physical Architecture and later Arcadia layers are future releases, as the new objective explicitly states.

The authoritative objective is attachment 10b0f701-1743-4de7-9ee1-225920e19649/goal-objective.md. It retains first-release scope and strengthens domain coherence, alternative evaluation and target-user task evidence. TASK_LEDGER.md separates given/verified facts, assumptions and open candidates; STATE.md records progress. The accepted 0.2.0 prototype is a historical baseline, not proof of release completeness. Its old D:/CodexBuilds archives are unavailable on this machine; existing dist archives must not be replaced until new acceptance passes.

The user's cross-branch reminder led to an ancestry/patch/tree audit. Continue from integrated c091f80 on codex/release1-continuation; direct state/scenario/process, data, hosted and semantic review work already exists here. release-branch-integration-20260906.md records the audit. release-current-coverage-20260906.md is the current measurable acceptance map and supersedes stale absence claims in older narratives below.

Existing architecture and retained decisions

Retain three Rust crates and one typed Project/validated atomic Command boundary. oa-core owns semantics, references, history, transitions, source and persistence; oa-desktop owns Iced interaction/drafts/projections; oa-server owns REST/ETag/current-model storage. Keep identity, semantic containment, allocation and per-diagram placement separate. No runtime plugin framework or later-layer skeleton.

The current forms are a closed typed-record adapter, not a second metamodel. Expand their real creation/reference/variant controls with every semantic addition. Core choices must drive graphical choices. New persistent fields participate in text round trips, identity/removal visitors, transitions, API schemas and graphical authoring tests.

Milestones and measurable acceptance

Nested source ownership and persistent REST bundles are implemented and verified: Windows minimum-size source-to-graphics, nested reparent/source/Undo/Redo/Save/reopen, recovery, rebuilt Linux source/history/Save/reopen, independent review and both platform suites passed. Preserve the existing grammar/updater and separate allocation/order semantics.

Explorer/port discovery, custom routing, direct palette connections, four-side port anchors, contextual menus and source folders have scoped Windows/Linux acceptance. See release-explorer-usability.md, release-routing-verification.md, release-routing-linux.md and release-port-drawing.md for exact evidence and limits.

Direct state-machine editing is accepted through316dc55: typed persisted views, explicit-owner creation, movement, direct transitions/reconnection, typed detail forms, folding, placement and correct camera/tool lifetime. Windows default/minimum and Linux native acceptance plus independent reviews are recorded in release-state-editing.md. Direct scenario/process gestures remain required.

R6 data contracts and direct scenario/process gestures are integrated; native acceptance continues on both platforms. Typed R3 core/source5/REST and scalar review milestones1–2 are integrated and pass full platform checks. Close independent scalar fixes and native review, then finish constructor/keyed/order/reset/artifact and multi-source graphical authoring using the existing shared core planner. Source5 migration retains lexical ownership/comments; no flat source rewrite is allowed. See release-data-contract.md, release-semantic-integration.md and release-semantic-gui.md.

Continue source authoring improvements only through the production parser/updater. The23-test experiment is evidence, not architecture: independent probes exposed comment misattachment and unsupported edits. Additional shorthand must preserve complete edit/delete behavior and exact source history, and justify itself in real human authoring tasks. Shared state placements are now validated; scenario/chain interaction must preserve its own occurrence and ordering semantics.

1. Release coverage audit and interfaces. Compare actual core/UI/API with official Capella OA/SA semantics and the new objective. Freeze a coverage table and concrete variant/reference/transition contracts before editing shared interfaces. Distinguish unsupported later layers from missing OA/SA workflows; V2 exclusions are reconsidered. Native audit exercises onboarding/help/authoring at supported sizes. Independent audits have separate file ownership.
2. Complete engineering semantics. Fill verified gaps in capability relationships and mission involvement; operational process/functional-chain function/control topology; scenario/state/data constructs needed by OA/SA engineers. Add typed semantic-content drift and reviewed existing-counterpart reconciliation, including reference mapping and explicit dependency/ownership decisions. Every addition has a usable graphical authoring workflow, equivalent source/API representation, meaningful reject/undo/delete/reidentify/transition tests and a worked example. Exact additions and invariants are recorded in the coverage/interface artifact from milestone1, avoiding speculative LA/PA concepts.
3. Approachable authoring and help. Replace static help with searchable topic navigation, concise concepts, numbered OA→SA tutorials, related topics and direct workspace actions. Add a focused starting workspace, recent models and practical creation guidance. Improve source authoring with asynchronous versioned lint, semantic warnings, diagnostic navigation and find/go-to tools. Make selection/navigation and hidden/placed model distinctions clear. Add recoverable local checkpoints for unsaved accepted models and drafts; preserve explicit file-save/conflict behavior.
4. Connected automation workflow. Keep headless deployment and shared core REST contract. Add direct optional desktop open/publish/save of hosted models using explicit connection details and conditional ETags, preserving drafts on failure/conflict and keeping credentials in memory. Verify actual desktop→API→desktop edits and artifact integration locally. Update OpenAPI, deployment and source contracts for the expanded release semantics.
5. Release integration and polish. Guided examples cover OA goals/roles/process alternatives, system missions/capabilities/boundary contracts, chains/scenarios/states and evidence. Review default/minimum/wide layouts, practical keyboard paths, empty/loading/error/recovery states and performance on representative models. Build/run the actual native app after each meaningful UI milestone, fix from evidence, then reverify.
6. Independent final acceptance and packaging. Fresh requirements, correctness, native UX and simplicity reviews in parallel; fix all material findings and rerun affected checks. Full Windows/Linux locked tests, formatting, strict Clippy and optimized builds. Operate primary GUI workflows and actual service transport. Verify current docs/reST rendering, examples/migration, reproducible source workflow, package binary equality/archive contents and checksums. Only then replace 0.2.0 bundles and mark this goal complete.

Dependencies: milestone1 freezes shared interfaces for2; guide/lifecycle work in3 can proceed independently once UI ownership is partitioned. Structural counterpart work depends on2. Hosted client4 depends on final core/API types but transport/lifecycle can be developed independently. Milestones5–6 integrate all preceding work.

UI and state flow

Keep task navigation, engineering perspective and context-sensitive properties. A Home/start workspace offers projects, recovery and tutorials without obscuring active modeling. Help uses local Rust-owned content and search/category navigation; workspace links pass explicit events and respect draft/modal guards.

Text edits update a snapshot/version; parsing/semantic lint runs on a blocking worker and only the latest result is adopted. Syntax errors and semantic warnings have distinct severity/location and navigate to source. Applying text remains one atomic model transaction. Invalid text and property input are recoverable drafts.

Recovery writes separate per-session checkpoints in user-local application data, never silently overwrites a model file, and offers explicit restore. Recent paths are convenience metadata. Hosted models use a separate connection/resource/revision/ETag handle; ordinary core editing and Undo stay local until explicit conditional Save. Network/file failures retain the same draft. Tokens are not persisted or included in diagnostics.

Failure and verification strategy

Cover wrong-layer/reference/kind input, ownership/reference cycles, duplicate or ambiguous counterpart matches, stale plans/ETags, typed semantic drift, sequence control topology and repeated occurrences, invalid source/property drafts, external file edits, failed storage/network operations, oversized models and unavailable graphics. Keep incomplete engineering work editable through warnings while rejecting structural corruption.

Tests must cover user-visible meaning and cross-representation invariants, not just serialize the same value twice. Use actual HTTP and native CUA for end-to-end behaviors. Independent review targets current artifacts and the original release objective, not only implementation summaries. Record unsupported/unavailable environments without turning missing required functionality into a limitation.

Definition of done

Every concrete requirement in the new objective and release coverage table has authoritative current evidence. Primary OA/SA engineering workflows work graphically, textually and through the API; help is navigable and useful; native Windows/Linux UI is intentionally designed and exercised; no blocking/high-impact defect remains; strict checks pass; independent findings are closed; durable docs accurately reflect the release; another engineer can build/run/test and use the supplied packages. V2 completion alone does not satisfy this goal.

Historical milestone progress — hosted integration

Milestone4 desktop adapter is implemented on the existing Document/REST boundary. Windows native publish, graphical/text save, rejected invalid source, API artifact reload and stale-revision recovery are demonstrated. Offline/retry and exact local-copy/catalog Open native acceptance passed on Windows. Destination and catalog defects found afterward were fixed/reviewed/integrated; remaining platform/native cases retain their report scope. Constructor/keyed/order/Child/Incident/artifact and multi-source review, Home/recents and checkpoint recovery are now implemented. Their scoped native and automated results are in STATE.md; this older milestone is not a current absence list.

Current execution refinement — 2026-09-07

First-release scope above is unchanged. The user-requested Windows development preview is packaged with565files, including all37 teaching-folder files, and is linked from DEVELOPMENT_SUMMARY.md. Latest Fit6 and two existing scroll/branch regressions pass; full desktop570/570, workspace bins, formatting and strict workspace/all-target Clippy pass. Corrected full server56/56 retains its unchanged-server scope. Exact build status and provenance are recorded in STATE.md. This is not an optimized final release.

Native6BAB operation/recovery/history passes and BCC1 corrected OA/SA nested routing passes retain their separate binary scopes. The latest DC50 preview launched with a clean PATH, and its four-card OA Fit overview was visible at1444×932 and1102×932. Minimum-height, pending-form and remaining process-purpose acceptance are still open. Computer Use was stopped by the user's Escape; leave both live GUI processes untouched and continue independent work.

Native Linux core436passed/2ignored is complete on its frozen455-file snapshot. The original server compile passed, unit2/2 and HTTP50/51 passed, and the single504-versus412 timing fixture failed twice. Its private preparation-gate replacement passes on Windows but still requires Linux execution. Preserve the original failures and exact final-state assertions; do not alter the production30-second deadline to make the fixture pass.

The fresh Linux GUI cross-build passed on immutable458-file snapshot source7-20260907T102528493108Z, including the Fit constructor fix. Run 20260907T1025486926611Z completed in2m20s Cargo time with pre/post checks, ELF requirements and all37 lesson files verified; the compiler lease is released. The subsequent headless guest failed its early IO-APIC timer check on three bounded boots, before SSH/tests. Exact matching boot assets were extracted, but automatic approval review rejected the proposed transient boot workaround before launch. All task VMs are stopped; no application failure or current Linux server pass is inferred. Latest guide-label changes and the validated Exchange/CommonWork native oracles follow the frozen binary snapshot.

Next actions:

1. Retain all three guest boot records and exact-kernel proof; the proposed direct-boot action was denied by automatic approval review and must not be retried or split to bypass it. Resolve the runtime gate through an approved route or changed environment. Verify actual readiness and remaining monotonic budget before running the corrected Linux server gate. Do not restart on observation timeout alone.
2. Preserve the reviewed guide corrections and validated expected-model/source Exchange/CommonWork oracles; the updated guide now builds on Windows and belongs in the next packaged/native snapshot. Complete native purpose authoring/history once control is available.
3. Once native control is authorized again, complete current-layout minimum-height/Focus/pending-form checks, remaining engineering/hosted walkthroughs and actual Linux GUI acceptance using exact model/source/history evidence.
4. Execute the corrected Linux server suite; complete final Windows/Linux optimized builds, package provenance, documentation/contracts, and fresh independent cross-disciplinary end-state review. Successful slices do not complete the goal.