Implementation Plan Portable Continuity V2

Portable continuity V2 — conditional implementation plan

Status: proposed; retained for future delivery, not an active implementation assignment. Issue #281 owns the preservation/reconciliation only. The V2 proposal is the owning design and records the accepted basis, two owner-approved V2 choices, original commit and historical schema-26 baseline. The full-product plan retains RM5/RM6's complete outcome. No implementation, test execution, installation, release, owner-data mutation or external service is authorized by this document.

Prerequisites and ownership

Before releasing a source writer:

1. Record the October 16 owner-approved V2 choices—formal-state-preserving import and content access independent of a checkout—through the existing ADR process. The choices are resolved; formal ADR reconciliation remains. Do not edit accepted bodies or treat this approval as acceptance of the detailed implementation plan.
2. Inspect the actual delivery baseline and extend the design's historical schema-26 inventory to every supported domain and lifecycle/recovery obligation. Freeze the model contract only after that coverage is complete. The proposed model-1 encoding, limits and file paths below are starting inputs, not verified current source facts. Existing V1 and seed contracts remain unchanged.
3. Assign the future implementation to an owning ticket with exact scope, current dependencies and authorized endpoint. Use current development roles: Developer or the relevant specialist owns source; QA owns test design and execution; CI/CD owns authorized builds/installation; an independent reviewer covers the material contract, data preservation and recovery changes. Select other roles only for their concrete risks.

Preserve the complete exporter → importer → installed round-trip sequence. One source writer owns overlapping store/root/recovery files at a time. QA and source work can proceed independently only with explicit separate ownership. Importer work consumes a reviewed, committed exporter-produced fixture. No custom workflow engine, copied ledger, direct SQLite tooling or extra verification harness is a prerequisite. Record delivery status/results in the future owning ticket.

The useful September 11 source boundaries and acceptance scenarios follow. They are conditional proposals, not a claim that the named files or tests exist today.

7A — authoritative complete exporter and fixture

Outcome: a usable owner-triggered exporter, strict versioned contract and canonical synthetic fixture generated by that actual exporter. Importer work cannot begin until this is reviewed and committed. Existing v1 and Rekon seed semantics remain.

Files and responsibilities (new paths are proposed):

• ReleaseRadarCore/Portability/PortableProjectModels.swift: fixed v2 manifest, model-1 typed graph, root slots, file inventory, history namespace and limits.
• ReleaseRadarCore/Portability/PortableProjectSnapshot.swift: one complete project/registration-scoped store read, source references and graph validation; reconciles the historical schema-26 families listed in the design with all later supported domains, not DashboardProjection.
• ReleaseRadarCore/Portability/PortableProjectPackage.swift: strict bounded metadata decode, no-follow inert file enumeration/hash/copy and package validation.
• ReleaseRadarCore/Portability/PortableProjectExporter.swift: preview, source revalidation, adjacent staging and exclusive package publication.
• ReleaseRadarCore/Store/DeliveryStore.swift, documentation reader/resolver access seams and project lifecycle capture: only narrow snapshot/authorization reuse.
• ReleaseRadar/Projects/ProjectOverviewView.swift, ProjectsView.swift, ReleaseRadar/App/AppModel.swift, new PortableProjectExportView.swift, and ReleaseRadar/Help/WorkspaceHelpView.swift: complete export journey and Help.
• ReleaseRadarTests/PortableProjectExportTests.swift, PortableProjectPackageTests.swift, PortableProjectExportRenderingTests.swift and ReleaseRadarTests/Fixtures/PortableProject/v2/: synthetic graph and actual exporter output. Add Xcode target/resources references only as needed.

Interfaces: exporter accepts current ProjectRegistration, an owner-selected output and retained source capabilities; preview returns immutable source snapshot identity, counts, root/file inventory and typed blockers. export(preview) returns package URL/ID/digest and a completion result only after exact revalidation. It does not accept raw SQL or arbitrary include paths. validate(package) returns a typed validated manifest/graph with payload digests; it is the importer's input contract. Concrete Swift signatures belong to the future implementation assignment; these behavioral interfaces and data fields are controlling only after owner approval.

• Write failing store/package cases before implementation: all five lanes, unassigned and retired tickets, absent versus empty task plan, superseded task, accepted goal, carried/dropped obligation, lifecycle events, proposal versions and approved-unapplied proposal, reference versions, evidence append ordering, completed/unlinked observations, source audit facts and unknown sends.
• Add source-authority/content cases: multi-root and archived project; primary managed catalog plus legacy evidence; missing required file; stale accepted catalog; lost bookmark; out-of-root evidence; concurrent store/content change; source root replacement. Assert explicit failure and unchanged source files/state.
• Implement typed snapshot, validation and exporter, preserving unknown legacy facts. Verify partial/paginated domain reads never count as a complete snapshot.
• Generate the durable package through the production exporter from repository synthetic XCTest fixtures. Record expected domain counts/IDs/revisions and exact payload identities in the fixture test, without hand-authoring an import archive. Fixture contains no owner data, actual permissions or credentials.
• Test duplicate/unknown fields, path traversal, symlink/hardlink/special files, case/Unicode aliases, size/count boundaries and no-replace output. Verify v1 is clearly identified, no implicit upgrade, and incomplete source cannot export.
• Exercise owner export controls in an authorized inert native host, wide and compact, keyboard/AX, cancellation, blocker recovery and completed-package location.
• Confirm the applicable version-specific decisions were accepted through the ADR process, update affected product docs/Help, catalog fixture artifacts if durable evidence, run documentation checks, obtain independent review and make the scoped commit.

7A acceptance: the actual exporter can produce the complete current model fixture and validates its own transport contract with expected graph/file facts. No import implementation, fixture claim based on handwritten JSON, checkout copy, owner state, notification or replay side effect. This is export delivery, not completion of Phase 7.

7B — complete import, recovery and continuation

Outcome: the exporter-produced package imports into fresh destination content roots with complete recorded state, honest source history and explicit checkout revalidation. Files and the store recover together, without a partial live project or overwritten owner file. This slice includes UI and immediate integration; do not ship a storage-only importer as the complete user outcome.

Consumes: reviewed 7A validator, graph/manifest version, source fixture and explicit owner decisions. Fresh writer baseline contains that exact committed output.

Files and responsibilities:

• New ReleaseRadarCore/Portability/PortableProjectImporter.swift and PortableProjectImportRecovery.swift: preview/confirmation, root mapping, scoped replay receipt and journal protocol defined in the design.
• New ReleaseRadarCore/Portability/PortableProjectHistory.swift: immutable source namespace and source/local event-reference translation for current history edges.
• ReleaseRadarCore/Store/StoreMigrations.swift, DeliveryStore.swift: next additive schema after inspecting actual baseline; imported origin/content-root metadata, local admission state, receipt and source-history relationships. Never copy a DB.
• ReleaseRadarCore/Onboarding/ProjectRootManagement.swift, RepositoryRootRelocation.swift, ProjectOnboarding.swift, ProjectLifecycle.swift, and applicable command/query authorization: distinguish fresh content roots from checkout capabilities, exact registration and explicit owner checkout association. Existing worktree membership checks remain intact.
• ReleaseRadarCore/Recovery/ApplicationBackup.swift, ApplicationRecovery.swift: reconcile pending imports before recovery/reset and include committed provenance in backup/removal retention. No second backup format or new authority.
• ReleaseRadar/Activity/ProjectActivityProjection.swift, ReleaseRadarCore/Search/WorkspaceSearch.swift, evidence/reference/proposal queries, observer/notification admission: show imported source identities, unknowns and stale approval/evidence honestly without replay or name/path rebinding.
• New ReleaseRadar/Projects/PortableProjectImportView.swift, existing Projects, repository recovery, AppModel and Help surfaces: preview, all root mappings, explicit catalog acceptance, conflicts, commit and recoverable continuation.
• New ReleaseRadarTests/PortableProjectImportTests.swift, PortableProjectImportRecoveryTests.swift, PortableProjectHistoryTests.swift, PortableProjectImportRenderingTests.swift; extend existing root, lifecycle, history/search, evidence/proposal, backup/recovery and notification tests only where these integration boundaries change.

Interfaces: preview(package, destinationSelections) returns package digest, validated graph, exact slot-to-new-root mapping, collisions, counts and required owner confirmations. confirm(preview, requestID) returns a committed receipt or recovery state; it rejects stale inputs. recover(operationID) resolves that same journal/receipt before normal admission. Content-root capability cannot satisfy a checkout requirement. associateCheckout is an explicit owner action preserving source associations as history; it verifies the current repository and worktree relationships and never rewrites imported formal state.

• Write failing tests importing 7A's actual fixture into an empty synthetic app store and new destination parents; prove full domain/payload preservation, stable IDs and original historical registrations plus fresh local registration.
• Add migration tests for supported existing store revisions (including the historical schema-26 baseline where compatibility requires it) and immutable local audits; preserve absent/unknown values, foreign keys and existing normal command policy.
• Implement source-history namespace and complete atomic graph insertion; preserve proposal baseline bytes/digests as historical, never actionable local approvals. Re-export the imported graph and compare supported source content semantically, accounting only for declared fresh identity/local import history.
• Implement journal/staging/no-replace commit, then inject failure at each durability boundary: before journal, during copy, after one/all renames, before DB commit, after commit before journal completion, and during readback/restart. Assert no live partial project, no owner overwrite, exact same receipt on replay, preserved diagnostics and exact-folder recovery after permission loss.
• Test same-table ID collision, duplicate import, changed request, live registration replacement, case/normalization/root overlap, destination created after preview, package/content/catalog edit after preview and changed staged file.
• Verify imported event facts, unknown sends, completed observations and old receipts cannot send notifications, change lanes, complete tasks or replay any command on import, first refresh, repeated refresh and relaunch. Fresh later observation must follow normal admission/dedup rules and can report a new event.
• Verify foreign original registrations and legacy root-only commands reject; content roots cannot impersonate worktrees; fresh explicit checkout association still enforces repository identity/membership, readiness and execution evidence.
• Verify current document resolution, older reference availability, evidence historical applicability, History/Search exact destinations and Back/Forward; imported pending proposals require a new baseline and explicit decision.
• Test archive/restore, removal retained source history and full-backup recovery of an imported project, plus reset/restore exclusion while an import is pending. Recovery invalidates earlier destination requests and preserves source provenance.
• Exercise complete native preview/mapping/acceptance/commit/recovery UI with actual file panels and wide/compact keyboard/AX flows. Update Help and directly compare the applicable references; record justified flow deviations in the design.
• Review the combined contract, migrations, containment, recovery and UI through one qualified independent peer; apply Required corrections, rerun affected checks, validate docs and make the scoped local commit at the authorized endpoint.

7B acceptance: all supported rows and required payloads survive exporter-to-importer tests, every authority difference is intentional and observable, and failures preserve owner files and other projects. Compilation alone is insufficient.

7C — installed round-trip acceptance

Outcome: prove the delivered product journey through the actual installed candidate, including fresh macOS folder permissions and recovery, then record whether Phase 7 meets the complete acceptance criteria. This is a later separately authorized task, not permission to install or touch the owner app now.

Use a parent-reserved clean synthetic environment and a signed installed candidate with App Sandbox enabled. Preferred test environment is a separate macOS test account or second Mac with no owner database/Keychain/services, so real panel grants are new. If the actual installed build cannot run safely in that environment, report installed acceptance blocked; an unsigned XCTest host does not satisfy this step. The parent must approve installation target, test account/data and process lifecycle.

1. In source installed app, create the complete supported synthetic graph using supported typed application operations and separately authorized root grants. Use multiple content-bearing roots, valid catalog/archived documents, byte-distinct evidence, accepted/retired/unassigned work, task/proposal/obligation/history and revision-evidence cases from 7A. No direct SQLite seeding in the installed journey.
2. Export through real controls. Verify preview counts/exclusions, successful inert package and no source checkout/credentials/permissions. Preserve exported fixture and exact app/build identity in canonical acceptance evidence.
3. Transfer only that package to the destination test account/Mac. Make original source roots unavailable to the destination; ensure no source bookmarks apply. Preview and authorize each fresh root through macOS panels, inspect catalog acceptance and import. No Git checkout is required to read the imported material.
4. Use app UI and supported complete readback to compare every selected record family, historical event identity/time, domain relationship and file digest. Inspect History, both Goals domains, tasks, evidence, references, proposals, Search and archived recovery. Verify old approved proposals and execution evidence remain historical; a later explicitly prepared checkout exercises fresh association.
5. Relaunch and repeat readback; deny/revoke and restore exact-folder access; verify no command/notification replay. Exercise duplicate import and a pre-existing sentinel destination file; verify sentinel bytes and unrelated projects unchanged.
6. Exercise a controlled interrupted import in the synthetic installed environment at a supported test boundary, restart and complete recovery. If a deterministic boundary is not exposed safely in the installed build, retain direct 7B fault tests and report this installed interruption case unverified rather than claiming it happened. Installed successful import/relaunch/fresh permission remain required.
7. Export again from destination and compare complete content/domain state using declared origin/local metadata differences, not raw package hash equality. Check that provenance does not multiply on repeated transfer and saved workspace queries and credentials did not transfer.
8. Capture actual wide/compact native UI, keyboard/AX and current Help; complete the independent QA review. Record tests, limitations, candidate/build and results in the future owning issue and canonical evidence destination, with affected documentation links updated.

Phase 7 completion requires 7A/7B direct tests and review plus the installed happy path, fresh permissions, durable relaunch and semantic re-export evidence. Any unverified recovery/installed case remains named, with no broader acceptance claim.

Verification and delivery boundary

QA chooses the focused repository-native tests against the exact implementation candidate; CI/CD performs authorized build/install steps in the agreed environment. Use current repository execution recipes, not the original branch's retired worktree paths, app-harness commands, role settings or progress-ledger instructions. The scenarios above are planned evidence, not tests passed by this reconciliation.

Each slice finishes at its separately authorized repository endpoint. Phase 7 is not complete when documents are published or when only export ships. Completion requires the exporter/fixture, complete safe importer, direct recovery/authority checks and the installed happy path, fresh permissions, durable relaunch and semantic re-export. Name any unverified recovery or installed case explicitly.

Source preservation

This plan retains the meaningful 7A/7B/7C boundaries and acceptance cases from docs/delivery/plans/2026-09-11-phase7-portable-continuity.md at a0f22d965395248be6ec5928d2932d3a7ce5166d. The original design, plan and ADR deltas remain in the issue-281 recovery bundle. Old review/model/task chronology, obsolete validation paths and claims of current approval were not carried forward as execution instructions. Issue #281 records migration checks and branch retirement; it is not the Phase 7 implementation ticket.