From 657933671981eb6802cec9b41fd32e593be26648 Mon Sep 17 00:00:00 2001 From: Kyle Van Essen Date: Sat, 14 Nov 2026 17:44:05 -0500 Subject: [PATCH 01/12] docs(Mobius): plan persistent code-review workspaces Define the product scope, revision-aware progress, concurrent workspace model, GitHub feedback, private iCloud continuity, and a later embedding experiment. Detail the local state foundation and preserve later work as six outlines with refinement gates. Validation: reviewed the complete plan, verified 103 local links and anchors, checked the seven-plan dependency graph and all 12 requirement owners, and passed git diff --cached --check. Product tests and SwiftFormat were skipped because only planning Markdown changed. Mermaid was source-reviewed; no local renderer was available. --- .../01-review-state-foundation.md | 174 ++++++++++ .../02-application-workspace.md | 77 +++++ .../03-github-and-revision-comparison.md | 78 +++++ .../04-repository-exploration.md | 71 +++++ Plans/2026-11-14-mobius/05-review-feedback.md | 80 +++++ .../06-icloud-resume-and-release.md | 86 +++++ .../07-embedded-review-experiment.md | 64 ++++ Plans/2026-11-14-mobius/README.md | 298 ++++++++++++++++++ 8 files changed, 928 insertions(+) create mode 100644 Plans/2026-11-14-mobius/01-review-state-foundation.md create mode 100644 Plans/2026-11-14-mobius/02-application-workspace.md create mode 100644 Plans/2026-11-14-mobius/03-github-and-revision-comparison.md create mode 100644 Plans/2026-11-14-mobius/04-repository-exploration.md create mode 100644 Plans/2026-11-14-mobius/05-review-feedback.md create mode 100644 Plans/2026-11-14-mobius/06-icloud-resume-and-release.md create mode 100644 Plans/2026-11-14-mobius/07-embedded-review-experiment.md create mode 100644 Plans/2026-11-14-mobius/README.md diff --git a/Plans/2026-11-14-mobius/01-review-state-foundation.md b/Plans/2026-11-14-mobius/01-review-state-foundation.md new file mode 100644 index 000000000..7e9555b26 --- /dev/null +++ b/Plans/2026-11-14-mobius/01-review-state-foundation.md @@ -0,0 +1,174 @@ +# 01 — Review-state foundation + +- Status: ready +- Depends on: None. +- Shared context: [Overview](README.md). + +## Deliverable + +A `MobiusCore` library that can preserve and reopen several review workspaces without a UI or live provider. Explicit file-review receipts are valid only for the exact comparison they describe. Reading positions and drafts survive a new store instance. This is groundwork; it does not provide the first-release GitHub or iCloud experience. + +## User stories and requirements + +| Story | Requirement | Behavior delivered here | +| --- | --- | --- | +| US-01, US-02 | R-02, R-03 | Typed workspace documents, independent reading locations, explicit receipts, drafts, and local restoration. | +| US-03 | R-04 | Pure progress evaluation against immutable file-comparison identities and an explicit checkpoint. | +| US-06 | R-07 | Stable entity/account identities and versioned records that future sync can address; no sync yet. | +| US-07 | R-08, R-09 | Honest save/load errors, stale-mutation rejection, account partitioning, and separate evictable content references. | +| Supporting | R-11 | Module documentation, package/test registration, and dependency guards. | + +Definitions live in [Requirements](README.md#requirements). X-01 applies to this planning turn; implementation below is only for a subsequent execution request. X-03, X-05, and X-07 constrain that implementation. Network access, token storage, UI rendering, and CloudKit transport are not delivered here. + +## Context and constraints + +Read the [root contract](../../AGENTS.md), [Plans contract](../AGENTS.md), and [running-tests skill](../../.agents/skills/running-tests/SKILL.md) before execution. `Package.swift`, `Project.swift`, `BumperBowling.swift`, and `.bumper/RULES.md` are the integration owners. Existing `WhereArchitectureTests` exercise dependency diagnostics; they do not yet cover Mobius. + +Create `Mobius/README.md` and `Mobius/AGENTS.md` for the product group, plus `Mobius/MobiusCore/{Sources,Tests,README.md,AGENTS.md}`. Core initially uses Foundation only. It must not import SwiftUI, UIKit, Where modules, or a UI facade. Do not create empty later modules or provider abstractions with no current consumer. + +Rules and guards to add together: + +| Invariant | Owner | Proposed guard | +| --- | --- | --- | +| Provider identity is distinct from names/URLs; generated IDs exist only for newly created local entities. | `ReviewIdentity.swift` and module contract. | `ReviewIdentityTests`; persisted identity round trips and no fallback generation. | +| Review receipts bind both file sides, paths, modes, and comparison kind; visiting is not reviewing. | `FileReviewReceipt.swift`, `ReviewProgress.swift`. | Matching tests with changed base/head, rename, deletion, and incomplete inputs. | +| Acknowledged mutations are persisted before they become the store's published snapshot. | `WorkspaceStore.swift`, `AtomicWorkspacePersistence.swift`. | Failure injection and reopen tests using the real persistence implementation. | +| Window edits cannot overwrite a newer state silently. | Store version check. | Competing mutations from the same expected version; one must receive a stale-version error. | +| Core has no app/UI dependency. | New module AGENTS and Bumper configuration. | Mutation test rejecting UIKit and WhereCore, plus an allowed Foundation neighbor. | + +[Q-09](README.md#q-09) will determine remote merges. This step implements local serialization and revision preservation, not distributed conflict resolution. Its record schema remains provisional until sync refinement. + +## Data flow + +```mermaid +flowchart LR + Intent["Proposed workspace mutation"] -->|expected local version| Store["Proposed WorkspaceStore actor"] + Store -->|validate and compute| Candidate["Proposed immutable candidate snapshot"] + Candidate -->|versioned archive| Disk["Proposed atomic persistence adapter"] + Disk -->|save succeeded| Publish["Return new snapshot and local version"] + Disk -->|original error| Failure["Keep previous snapshot; report failure"] + Disk -->|load at restart| Store + Comparisons["Synthetic complete/partial file comparisons"] --> Policy["Proposed ReviewProgress policy"] + Receipts["Persisted explicit receipts"] --> Policy + Policy --> Result["Reviewed, needs review, or unavailable"] +``` + +All named domain components are proposed. The filesystem and Foundation serialization are existing platform facilities. No remote mutation or live code download occurs. Cache contents are outside the authoritative metadata archive. + +## Architecture sketch + +```swift +// Proposed pseudocode. Concrete Codable DTO fields and error cases are defined +// during step 2 and documented as a versioned wire contract. +struct ReviewTarget: Hashable, Codable, Sendable { + let accountID: Account.ID + let repositoryID: Repository.ID + let pullRequestNumber: PullRequest.Number +} + +enum WorkspaceDocument: Codable, Sendable { + case review(ReviewDocument) + case source(SourceDocument) + case search(SearchDocument) +} + +struct FileComparisonIdentity: Hashable, Codable, Sendable { + let kind: ComparisonKind + let before: FileRevision // Includes absent/blob/submodule, path, mode, object ID. + let after: FileRevision +} + +struct FileReviewReceipt: Codable, Sendable { + let target: ReviewTarget + let comparison: FileComparisonIdentity + let reviewedAtRevision: ReviewRevision +} + +protocol WorkspacePersisting: Sendable { + func load() throws -> WorkspaceArchive? + func save(_ archive: WorkspaceArchive) throws +} + +actor WorkspaceStore { + private let persistence: any WorkspacePersisting + private var snapshot: WorkspaceSnapshot + + func apply(_ mutation: WorkspaceMutation, + expectedVersion: WorkspaceVersion) throws -> WorkspaceSnapshot { + // Reject a stale version; construct a candidate without mutating snapshot. + // Synchronously persist the candidate on this actor, with no await gap. + // Only then replace snapshot and return the accepted version. + } +} +``` + +Every `ID`, Git object identity, path, PR number, and version is a dedicated domain type. Account identity includes the provider host and provider user identity; display login is not the key. Local workspace/document/draft IDs are created once. An absent persisted identity is an error, not a new UUID. + +Keep `ReadingLocation`, `ReviewCheckpoint`, `FileReviewReceipt`, and `ReviewDraft` as separate concepts. A location holds a document/content identity and a code anchor; its validity is checked on reopen. A receipt is only issued for complete supported comparison data. Absence of a blob for an addition/deletion is a typed file state, not a failed fetch. Unknown or missing objects remain unavailable. + +A changed PR head with identical before/after file content, paths, modes, and comparison kind may retain that file's receipt. A changed base side, rename, or mode change requires another review under the initial conservative policy. Do not infer cross-file or cross-path equivalence from a matching blob alone. A checkpoint also retains the PR base/head and comparison context so later code can detect unavailable or rewritten history. + +Receipt lookup must also match the account/repository/PR target. A since-checkpoint receipt does not automatically become a current-PR receipt. A UI action may explicitly mark the named current file comparison after the user inspects its delta; the action must identify that exact target instead of inferring intent from the visible tab. + +`WorkspacePersisting.load()` returns nil only for a genuinely absent archive. Decoding, permission, unsupported-version, and I/O failures throw the original error or an error that retains it. Domain values cross actor boundaries as immutable Sendable snapshots. UI observation is a later adapter. + +## Steps + +1. **Register Core and its guards.** Add the package library and a `MobiusCoreTests` hosted bundle through the existing `unitTests` helper, with the first identity value and its matching test so both targets are nonempty. Include the bundle in `Stuff-iOS-Tests`; use `StuffTestHost`. Extend Bumper's component catalog/included paths with MobiusCore's foundation boundary and tests rejecting UI/Where imports. Update the catalog, root architecture description, module docs, and run `./sync-agents`. +2. **Define and test the durable model.** Add focused files for identity, workspace documents, reading locations, checkpoints, receipts, progress, drafts, and the archive DTO. Keep 1:1 test filenames and shared builders in `MobiusCoreTestSupport.swift`. Document stable serialized keys/cases and an explicit schema version. Drafts retain user text and original revision anchors; no publication state machine is implemented yet. A local mutation version must not be presented as a cross-device causal clock. +3. **Implement local persistence and serialization.** Add `AtomicWorkspacePersistence.swift` and the serial `WorkspaceStore.swift`. Write an archive atomically before publishing the new snapshot. Scope file locations by account identity; keep source blobs/indexes outside the metadata archive. Missing files initialize an empty store; corrupt or unknown-version files remain intact and surface an error. Inject the persistence protocol into the store; fakes conform to that protocol. +4. **Prove transitions.** Implement the scenario matrix below. Include independent workspaces, stale callers, failed saves, reopening, and explicit progress changes. Opening/selecting a document does not create a receipt. Marking a file unreviewed changes only that review's local state. Preserve the original checkpoint when a newer PR snapshot is supplied. +5. **Review and publish groundwork.** Run the listed checks, inspect the complete diff through code-review, and use github-workflow for commit/push/PR. Record actual counts and revisions here. Reconcile an implementation issue created from STU-329 before beginning execution; do not close the planning issue as evidence of a shipped app. Update the horizon using the actual model before refining 02/03. + +Each meaningful implementation step is a coherent commit after its applicable checks. Do not commit a failing intermediate target graph. + +## Acceptance and verification + +Commands run from the repository root after the new targets exist. Test names below are proposed coverage, not claims of existing tests. + +| Requirement | Acceptance criterion | Procedure | Expected result | +| --- | --- | --- | --- | +| R-02/R-03 | Two PR documents plus a source and search document retain independent identity, ordering, location, and draft text after reopening. | `./test MobiusCoreTests`; `WorkspaceTests`, `WorkspaceStoreTests`. | Same persisted values from a new store; no generated replacement IDs. | +| R-03/X-03 | Opening, scrolling, and refreshing do not mark a file reviewed or submit feedback. | `ReviewProgressTests` with the same document under each operation. | Receipt set changes only for the explicit review intent. | +| R-04/R-09 | Within the same account/repository/PR, identical compared file content retains progress; changed sides, path, mode, or comparison kind requires review. Identical content in another PR/account cannot reuse a receipt. | Parameterized `FileReviewReceiptTests` / `ReviewProgressTests`. | No timestamp/head-only shortcut or cross-target progress leak. | +| R-04/R-08 | Partial manifests, missing baselines, unsupported file kinds, and unavailable content cannot report complete review. | Synthetic fixtures with explicit coverage states. | Typed unavailable/needs-review result; existing checkpoint preserved. | +| R-08 | A failed replacement keeps the prior accepted state; a stale window mutation is rejected. | Store tests with protocol-conforming failure injection and concurrent calls. | Original error retained, no partial in-memory commit or lost newer state. | +| R-03/R-09 | Real archive save/reopen works; corrupt/unknown-version input is preserved; account A cannot load account B's file. | `AtomicWorkspacePersistenceTests` in temporary directories. | Exact round trip, visible failures, isolated stores. | +| R-11 | New bundle is selected, Core dependencies are enforced, and formatting passes. | `./ide --no-open`, `./test MobiusCoreTests`, `./swiftformat --lint`. | Nonempty suite; default architecture checks and mutations pass. | + +Inspect all source/test selection and the generated target graph. A zero-test pass is not acceptance. These checks establish local behavior only; no image, GitHub, Catalyst, or CloudKit result is claimed by this deliverable. + +## Recovery + +A mutation that fails before replacement leaves the prior archive authoritative and the candidate unpublished. Retry only after reporting the failure and reconciling the caller's expected version. On startup, preserve a corrupt or unsupported archive and report it; never replace it with an empty workspace. A temporary incomplete write is not an accepted archive. Implement cleanup only for temporary files owned by this store. + +If the process ends after replacement but before the caller receives acknowledgment, reopen the durable version before retrying. Do not replay the old mutation against a guessed version. Include a restart test seeded with that committed-but-unacknowledged snapshot. + +If manifest generation or tests stop partway, inspect the existing edits and rerun `./ide --no-open` after completing the graph. Do not delete caches, simulators, or unrelated work to recover. No live account data is involved in the synthetic tests. + +## Decisions and revisions + +| Date | Decision | Source | +| --- | --- | --- | +| 2026-11-14 | Make durable review identity/progress the first deliverable; use a small atomic metadata store with a replaceable persistence interface. | [Shared decisions](README.md#shared-decisions). | +| 2026-11-14 | Keep network, remote conflict policy, and scene layout outside this executable horizon. | Q-08–Q-11 do not affect local fixture acceptance. | + +## Progress + +- [ ] Register module, tests, docs, and boundary guards. +- [ ] Implement typed values and explicit progress semantics. +- [ ] Implement accepted-state persistence and recovery. +- [ ] Verify the scenario matrix and applicable checks. +- [ ] Review, commit, push, and publish the implementation. + +## Execution record + +Not started. Plan creation did not generate an Xcode project, implement the module, or run its future tests. + +## Resume point + +After an execution request, verify the plan review and source baseline, create/link the implementation issue, then begin step 1. No product decision blocks this synthetic foundation. If later sync design changes its wire contract, revise the affected plans before proceeding. + +## Outcome + +Not implemented. Acceptance here will establish local review-state groundwork, not completion of the first release. diff --git a/Plans/2026-11-14-mobius/02-application-workspace.md b/Plans/2026-11-14-mobius/02-application-workspace.md new file mode 100644 index 000000000..06506afbd --- /dev/null +++ b/Plans/2026-11-14-mobius/02-application-workspace.md @@ -0,0 +1,77 @@ +# 02 — Application workspace + +- Status: outline +- Depends on: [01 — Review-state foundation](01-review-state-foundation.md). +- Shared context: [Overview](README.md). + +## Intended outcome + +Mobius launches on iPhone, iPad, and Mac Catalyst with a real persistent workspace. A reviewer opens multiple synthetic PRs and repository documents, switches among them, and returns to the same work after relaunch. iPad/Mac support multiple windows; iPhone provides a usable document/tab switcher within its available scene capabilities. + +Success is a runtime demonstration with two reviews and several reference documents, independent window selections, Mac menu/keyboard actions, and restoration. This is fixture-backed groundwork, not live GitHub or sync delivery. + +## User stories and requirements + +| Story | Requirement | Intended contribution | +| --- | --- | --- | +| US-01, US-02 | R-02, R-03 | Persistent documents, tab switching, reading positions, and scene restoration. | +| US-06 | R-01 | iPhone/iPad app and Mac Catalyst windows, menus, and shortcuts. | +| US-01, US-06 | R-10 | Accessible adaptive layout and keyboard/focus behavior. | +| Supporting | R-11 | Host/UI targets, docs, unit/image coverage, and Catalyst validation. | + +See [definitions and exclusions](README.md#requirements). X-03 and X-07 apply. Do not build a single disposable PR-detail flow and defer the workspace model; concurrency of reviews is this deliverable's purpose. Do not add live provider or CloudKit behavior here. + +## Known design and assumptions + +Proposed paths: `Mobius/MobiusUI/{Sources,Tests,SnapshotTests,README.md,AGENTS.md}` and `Mobius/Mobius/{Sources,Tests,Resources,README.md,AGENTS.md}`. Add the host and UI products through the root manifests. Give Mobius explicit iPhone/iPad/Catalyst destinations; do not expand Where's destination constant. + +Create the Core runtime once in the process composition root. Each scene receives a `WorkspaceModel` with its own local presentation and the shared store. Restore scene-to-workspace references; missing or explicitly deleted workspace identity produces a recovery/selection state, not a new random identity. Window closure releases that scene's work; it does not delete the workspace or affect another scene's tasks. + +A visible tab bar or compact switcher selects typed review/source/search documents. Explore in a new document by default. Optional panes on larger layouts preserve the same model; no free-form floating-window system is required inside an iPhone screen. Mac windows use system scene APIs, with app-specific menu and shortcut routing to the focused scene. Separate shared document closure from closing a native window. + +```mermaid +flowchart LR + Root["Proposed Mobius composition root"] --> Runtime["Proposed runtime using 01 store"] + Runtime --> A["Proposed scene A model"] + Runtime --> B["Proposed scene B model"] + A --> ViewA["Proposed workspace view A"] + B --> ViewB["Proposed workspace view B"] + Native["Existing UIKit scene lifecycle"] --> A + Native --> B +``` + +```swift +// Proposed composition sketch; API details await 01. +@MainActor +func makeScene(workspaceID: Workspace.ID, runtime: MobiusRuntime) -> WorkspaceModel { + WorkspaceModel(workspaceID: workspaceID, runtime: runtime) +} +// Each scene owns its model; the process owns runtime and persistence. +``` + +Use the [building-ui skill](../../.agents/skills/building-ui/SKILL.md), Broadway root/stylesheet conventions, and production-shaped injected fixtures. Add `MobiusUITests` to `Stuff-iOS-Tests` and `MobiusUISnapshotTests` to `StuffSnapshotTests`, with no new snapshot scheme. Follow full-content capture rules for scrolling panes and pair them with bounded shell captures. SnapshotKit's iOS renderer does not establish Catalyst window behavior. + +Declare Mobius's attribution inputs and bundled report through CreditKit's existing tooling. Generate the report when adding linked dependencies, and include `./attribution --check` in acceptance. Read the current CreditKit contract during refinement; Where's report is not Mobius's report. + +## Questions and learning needed + +- [Q-10](README.md#q-10): Select the code-text substrate and layout after measuring long lines, many documents, accessibility sizes, selection, and VoiceOver. Identify real latency/memory budgets and fixture sizes before readiness. +- [Q-11](README.md#q-11): Specify CLI Catalyst compile coverage and a native window/menu smoke test. Existing `./test` cannot be assumed to target Catalyst. Extend repository tooling only where required, with its public-command tests and owning docs. +- Reuse the current Broadway scroll restoration seam if it fits local reading positions; it is not itself the durable cross-device workspace store. + +## Refinement trigger + +- Trigger: 01 completes with actual state/persistence interfaces. +- Evidence needed: Working Core types, renderer/layout probe results, dependency closure, an explicit Catalyst build/runtime procedure, and an accessible tab/window interaction specification. +- Next action: Read the applicable UI/module/tooling contracts, expand this file into executable steps and acceptance criteria, and review it before implementation. Keep the first runtime demo synthetic and repeatable. + +## Decisions and revisions + +| Date | Decision | Source | +| --- | --- | --- | +| 2026-11-14 | Share UIKit/Broadway through Catalyst, with Mac-specific windows, menus, and shortcuts. | Q-04. | +| 2026-11-14 | Keep platform scene presentation local while workspace identity persists. | Overview design proposal. | + +## Resume point + +Await 01 evidence, then resolve Q-10 and the build/runtime portion of Q-11. Implementation has not started. diff --git a/Plans/2026-11-14-mobius/03-github-and-revision-comparison.md b/Plans/2026-11-14-mobius/03-github-and-revision-comparison.md new file mode 100644 index 000000000..8c89f89ff --- /dev/null +++ b/Plans/2026-11-14-mobius/03-github-and-revision-comparison.md @@ -0,0 +1,78 @@ +# 03 — GitHub and revision comparison + +- Status: outline +- Depends on: [01 — Review-state foundation](01-review-state-foundation.md), [02 — Application workspace](02-application-workspace.md). +- Shared context: [Overview](README.md). + +## Intended outcome + +The workspace opens actual GitHub PRs and discussions. A reviewer can inspect the current PR diff, set a personal checkpoint, leave, and return after changes to identify what requires another pass. The app shows the revisions and completeness of the comparison it actually loaded. + +Demonstrate ordinary pushes, force-push/rebase, base-branch movement, unchanged files, renamed/deleted files, unavailable old history, and paginated/limited responses. Honest unavailable history is an acceptable state; falsely reporting “nothing changed” is not. + +## User stories and requirements + +| Story | Requirement | Intended contribution | +| --- | --- | --- | +| US-03 | R-04 | Current-PR and since-checkpoint comparisons, using 01's receipts. | +| US-05 | R-06 | Authenticated PR/diff/discussion reading; submission remains in 05. | +| US-07 | R-08, R-09 | Credential/account boundaries, immutable snapshots, coverage, and stale-result control. | +| US-01, US-06 | R-10 | Bounded diff loading/rendering with measured budgets. | + +All [exclusions](README.md#not-required-and-explicitly-avoided) apply. Do not introduce Git authoring or treat GitHub's submitted-review/file-viewed state as Mobius's private progress. Support public and private repositories the selected identity can access; authorization failure must remain distinct from an empty PR list. + +## Known design and assumptions + +Keep product-specific GitHub adapters in `Mobius/MobiusCore/Sources/GitHub/`, revision logic in `Mobius/MobiusCore/Sources/Review/`, and credential storage behind a device-local interface. The root injects transport, credential, cache, and persistence collaborators. UI owns the native authentication presentation adapter. No new general GitHub framework is justified by this plan alone. + +The proposed `ReviewRevision` captures base tip, head tip, and the resolved comparison base. Current PR comparison uses the appropriate merge-base-to-head content. The since-checkpoint surface compares saved and current head trees directly, with a separate indication when the PR's base/comparison context changed. Do not present a three-dot comparison as an exact old-tree-to-new-tree delta after a rebase. Changes to the PR comparison itself must re-evaluate both sides of file receipts, even when head content is unchanged. + +```mermaid +flowchart LR + PR["GitHub PR identity and refs"] --> Resolve["Proposed revision resolver"] + Resolve --> Snapshot["Immutable trees/blobs and coverage"] + Snapshot --> Diff["Proposed comparison engine"] + Checkpoint["Saved personal checkpoint"] --> Diff + Diff --> Progress["ReviewProgress from 01"] + Progress --> UI["Workspace diff documents from 02"] +``` + +```swift +// Proposed seam; not existing API or production code. +protocol ReviewRepository: Sendable { + func snapshot(for target: ReviewTarget) async throws -> ReviewSnapshot + func file(at revision: FileRevision) async throws -> FileContent +} +// ReviewSnapshot retains immutable revision identity and explicit coverage. +// Failures are thrown; unavailable content is never represented by empty text. +``` + +GitHub PR-file/compare responses have documented limits; see [research](README.md#research-and-evidence). Treat them as useful metadata, not guaranteed complete manifests. Resolve immutable trees and blobs, traverse truncated trees by subtree, and retain coverage for every material omission. A refresh must not splice pages from different moving revisions. Bound retries if the PR changes while resolving it. + +Re-evaluate exact file comparison identities rather than resetting all progress on every new head. Keep refresh separate from setting the personal checkpoint. Retain cached baseline evidence when available. Since full caches do not sync, a new device may have to fetch old objects; deleted/unreachable objects must produce a visible baseline gap, not fabricated equivalence. + +Fixtures must include binary/non-text and oversized files, missing patches, CRLF/Unicode/long lines, submodules, rename/mode changes, missing pages, permission loss, cancellation, rate limiting, and superseded refreshes. Define supported rendering and indexing limits before readiness. Show unsupported content honestly without marking its review complete. + +## Questions and learning needed + +- [Q-08](README.md#q-08) blocks readiness: compare GitHub App and OAuth App access/onboarding; verify PKCE/callback/token-refresh behavior and concrete client-credential handling. Decide whether native public-client behavior is acceptable or an authentication broker is required. Do not assume the developer's `gh` credentials can ship in Mobius. +- Clarify the first supported GitHub host/organization policies during authentication refinement. Repository-account identity must support safe sign-out and switching regardless of initial account-picker scope. +- [Q-10](README.md#q-10): Choose a bounded line-diff/rendering path using fixtures; distinguish an API-derived patch from a locally computed exact-tree comparison. +- A stale review anchor is retained for 05 to resolve; network refresh must not silently rewrite user draft intent. + +## Refinement trigger + +- Trigger: Core contracts and the fixture workspace are validated. +- Evidence needed: Supported auth registration/flow, permission matrix, concrete GitHub response fixtures, exact comparison semantics, and measured diff budgets. Any required account/app registration is a recorded execution prerequisite. +- Next action: Research and, when execution is authorized, run a bounded auth/read probe. Integrate its evidence here, resolve Q-08, and write tests/steps/recovery for the selected adapter. No API write is needed for this deliverable. + +## Decisions and revisions + +| Date | Decision | Source | +| --- | --- | --- | +| 2026-11-14 | Use immutable revisions and explicit coverage; timestamps and a single head SHA are insufficient review evidence. | Q-03, R-04, official API research. | +| 2026-11-14 | Keep private personal checkpoints independent of GitHub's review publication. | Overview product model. | + +## Resume point + +Refine after 01/02. Resolve Q-08 and diff-specific Q-10 before readiness. No live authentication or revision experiment has run. diff --git a/Plans/2026-11-14-mobius/04-repository-exploration.md b/Plans/2026-11-14-mobius/04-repository-exploration.md new file mode 100644 index 000000000..986700aae --- /dev/null +++ b/Plans/2026-11-14-mobius/04-repository-exploration.md @@ -0,0 +1,71 @@ +# 04 — Repository exploration + +- Status: outline +- Depends on: [02 — Application workspace](02-application-workspace.md), [03 — GitHub and revision comparison](03-github-and-revision-comparison.md). +- Shared context: [Overview](README.md). + +## Intended outcome + +Browse the repository and search file paths and text while the current review stays open. Results open as additional workspace documents at a stated revision. Returning to the review preserves its location and progress. + +Demonstrate a search from PR A, opening a file outside its diff, switching to PR B, and returning to A unchanged. Repeat at different revisions where the same path has different content. Partial indexing must not look like a complete “no results” response. + +## User stories and requirements + +| Story | Requirement | Intended contribution | +| --- | --- | --- | +| US-01, US-04 | R-02, R-05 | Repository tree, path search, text search, and persistent source/search documents. | +| US-02 | R-03 | Restore semantic queries and reading locations without replacing the active review. | +| US-07 | R-08, R-09 | Revision/coverage labels, account-isolated caches, and cancellation. | +| US-04, US-06 | R-10 | Accessible results and bounded indexing/rendering workloads. | + +X-02, X-05, and X-07 apply. Editing code, terminal access, language-server navigation, and arbitrary execution are not required by this deliverable. + +## Known design and assumptions + +Use the immutable tree/blob provider from 03 and typed document routes from 01. Put navigation/search policy in focused Core types and the observable interaction in UI. Scope indexes by account, repository, and immutable tree; never silently answer a PR-head search with default-branch results. + +Proposed search design: fast path/name matching over the enumerated tree, plus local text indexing of supported fetched blobs. Fetch missing content on a bounded, cancellable schedule, with explicit progress and coverage. Define file-size, storage, network, and indexing limits during Q-10 refinement. Keep useful partial results while distinguishing indexing, complete, incomplete, and failed states. Source/index cache eviction must not delete draft text, receipts, or workspace document identities. + +```mermaid +flowchart LR + Route["Revision-bound repository route"] --> Tree["Provider from 03"] + Tree --> Paths["Proposed path search"] + Tree --> Blobs["Account-scoped blob cache"] + Blobs --> Index["Proposed text index with coverage"] + Paths --> Results["Proposed result document"] + Index --> Results + Results -->|open alongside review| Workspace["Workspace from 02"] +``` + +```swift +// Proposed values, not compiled API. +struct RepositorySearch: Sendable { + let revision: RepositoryRevision + let query: SearchQuery + let scope: SearchScope +} +// A result carries its exact revision and coverage; opening uses that revision. +``` + +GitHub's default-branch code-search endpoint is not the implementation of PR-revision search; see [research](README.md#research-and-evidence). No complete offline clone is promised. Previously cached documents remain useful when offline; missing content remains visibly unavailable. + +## Questions and learning needed + +[Q-10](README.md#q-10) covers measured indexing limits, large results, keyboard navigation, VoiceOver, and long-file handling. 03 must establish source access for forked PR heads and missing objects. Do not quietly change query scope when access differs. + +## Refinement trigger + +- Trigger: 03 supplies a tested revision-bound tree/blob API and 02 supplies document navigation. +- Evidence needed: Representative repository trees, indexing measurements, explicit coverage/cancellation policy, and restored-query behavior. +- Next action: Define query/index/result contracts, choose a measured storage/index implementation, then write executable acceptance for same-path/different-revision and interrupted-index scenarios. + +## Decisions and revisions + +| Date | Decision | Source | +| --- | --- | --- | +| 2026-11-14 | Repository exploration is part of the review workspace, with path and text search at an explicit revision. | Q-03, R-05. | + +## Resume point + +Refine after 02/03 and resolve indexing-specific Q-10. Implementation has not started. diff --git a/Plans/2026-11-14-mobius/05-review-feedback.md b/Plans/2026-11-14-mobius/05-review-feedback.md new file mode 100644 index 000000000..870890863 --- /dev/null +++ b/Plans/2026-11-14-mobius/05-review-feedback.md @@ -0,0 +1,80 @@ +# 05 — Review feedback + +- Status: outline +- Depends on: [01 — Review-state foundation](01-review-state-foundation.md), [03 — GitHub and revision comparison](03-github-and-revision-comparison.md), [04 — Repository exploration](04-repository-exploration.md). +- Shared context: [Overview](README.md). + +## Intended outcome + +Write comments while exploring code, retain them when switching tasks, and explicitly submit a comment, approval, or request for changes. Feedback is attached to the intended PR and revision. Interrupted or ambiguous publication preserves the user's text and provides a clear recovery path. + +Demonstrate a multi-file draft, task switching, relaunch, a PR update while drafting, successful submission, and a lost response after the server may have accepted the write. Personal reviewed-file markers remain independent of GitHub submission. + +## User stories and requirements + +| Story | Requirement | Intended contribution | +| --- | --- | --- | +| US-02, US-05 | R-03, R-06 | Durable local drafts, discussion reading/replies, and explicit review events. | +| US-03, US-07 | R-04, R-08 | Validate revision/line anchors; reconcile uncertain results without blind retries. | +| US-07 | R-09 | Apply the selected account and permission scope; preserve private user text. | + +X-02, X-03, and X-05 apply. No automatic review publication on navigation, backgrounding, sync, or a “mark reviewed” action. Code-edit suggestions, merge, dismissal, thread resolution, and broader PR administration are not required for this deliverable. + +## Known design and assumptions + +Core owns `ReviewDraft`, anchor mapping, and a proposed `ReviewPublisher`. UI owns composition, confirmation, and recovery presentation. Scope publication by account, PR, and draft revision; one local owner serializes mutations for that draft. Record the original immutable file comparison and anchor when text is authored. + +Read the current PR state before submission. If the head or comparison context changed, show the change and retain the draft until its target is revalidated. A comment authored while viewing a since-checkpoint comparison must map to a valid location in the PR review diff, or remain an unsubmitted draft with a useful explanation. Never attach a comment to the same line number in unrelated content. Submit an explicit commit ID where the API supports it; a preflight read does not make a later API write atomic with branch updates. + +```mermaid +stateDiagram-v2 + [*] --> Draft + Draft --> Validating: explicit submit + Validating --> Draft: stale anchor or permission failure + Validating --> Publishing: revision accepted + Publishing --> Published: remote identity confirmed + Publishing --> Draft: definitive server rejection + Publishing --> Uncertain: timeout or lost response + Uncertain --> Published: reconciliation confirms identity + Uncertain --> Draft: absence established or user resolves ambiguity +``` + +This is a proposed domain state machine, not a guarantee of exactly-once remote effects. A definitive rejected request preserves an editable draft and original error. Cancellation after dispatch may require reconciliation; it cannot be treated as proof that nothing was posted. + +```swift +// Proposed pseudocode; exact associated values await provider evidence. +enum SubmissionState { + case draft(ReviewDraft) + case validating(SubmissionIntent) + case publishing(SubmissionIntent) + case uncertain(SubmissionIntent, Error) + case published(PublicationReceipt) +} +// SubmissionIntent retains the draft revision, account, PR, and reviewed head. +// Persist wire-safe intent/receipt data separately from the original runtime Error. +``` + +GitHub review/comment schemas are linked in [research](README.md#research-and-evidence). Separate general PR conversation comments from inline review comments. Keep remote IDs after confirmed creation. Reconcile pending reviews and comments on reconnect, including reviews begun outside Mobius. Do not assume a generic idempotency key exists or blindly repeat a timed-out POST. Ambiguous matching must remain visible rather than selecting a guessed remote comment. + +## Questions and learning needed + +- Provider evidence from 03 must establish actual permission failures, pending-review constraints, line/range validation, and supported reply/review operations. +- [Q-09](README.md#q-09): Define cross-device publication ownership before sync. Syncing a draft or an uncertain intent must not automatically send it. Manual concurrent submission of the same shared draft needs a concrete conflict policy; local serialization does not solve that race. +- Draft conflict handling must preserve both authored texts. Publication receipts must identify which draft revision was sent so later edits are not falsely marked published. + +## Refinement trigger + +- Trigger: 03 has real provider/account/revision contracts and 04 proves exploration preserves review state. +- Evidence needed: Synthetic API fixtures for accepted, rejected, and response-lost writes; a supported remote reconciliation strategy; draft/submission persistence design; planned two-device conflict cases. +- Next action: Expand the state machine into executable steps and failure/race tests. Live write verification during execution must use an explicitly selected test PR and account; planning itself posts no product review comments. + +## Decisions and revisions + +| Date | Decision | Source | +| --- | --- | --- | +| 2026-11-14 | Submission is explicit; personal progress and GitHub review events remain separate. | Q-02/Q-03, R-03/R-06. | +| 2026-11-14 | Preserve uncertain publication rather than claiming success or automatically duplicating a write. | R-08 and the external-effect boundary. | + +## Resume point + +Refine after 03/04. Resolve the remote reconciliation and cross-device ownership contracts before readiness. Implementation has not started. diff --git a/Plans/2026-11-14-mobius/06-icloud-resume-and-release.md b/Plans/2026-11-14-mobius/06-icloud-resume-and-release.md new file mode 100644 index 000000000..1770efccb --- /dev/null +++ b/Plans/2026-11-14-mobius/06-icloud-resume-and-release.md @@ -0,0 +1,86 @@ +# 06 — iCloud resume and first-release acceptance + +- Status: outline +- Depends on: [01](01-review-state-foundation.md), [02](02-application-workspace.md), [03](03-github-and-revision-comparison.md), [04](04-repository-exploration.md), [05](05-review-feedback.md). +- Shared context: [Overview](README.md). + +## Intended outcome + +Start reviews on one device and continue them on another using private iCloud under the same Apple ID. Workspace documents, personal checkpoints/receipts, and drafts converge without losing user work or taking over another device's window focus. Each device authenticates its own GitHub account before retrieving protected source. + +This deliverable is required for the first release. Demonstrate an iPhone-to-iPad-to-Mac handoff, concurrent edits, offline work, reconnect, account transitions, and a complete GitHub review flow. A local-only app or simulator-only sync demonstration does not satisfy it. + +## User stories and requirements + +| Story | Requirement | Intended contribution | +| --- | --- | --- | +| US-02, US-06 | R-03, R-07 | Private cross-device continuity of semantic workspace state and drafts. | +| US-07 | R-08, R-09 | Conflict preservation, account isolation, visible sync state, and non-replayed publication intents. | +| US-01, US-04, US-06 | R-01, R-10 | Final device/window/input/accessibility acceptance. | +| Supporting | R-11 | Platform CI/runtime coverage, signing/distribution decision, and release evidence. | + +X-05 and X-06 apply. No custom workspace-sync backend, different-Apple-ID continuity, or full repository/credential sync. Reopening on another device may require GitHub sign-in and fetching uncached source. That limitation must be visible rather than hidden behind a successful workspace-metadata sync badge. + +## Known design and assumptions + +The candidate transport is `CKSyncEngine` over a dedicated private CloudKit database/container. The app owns local atomic persistence, pending record changes, serialized engine state, conflict policy, and account transitions. Keep the Core store's accepted-state interface; measure whether record projection requires a different internal persistence implementation. + +Use stable per-entity records instead of a single last-writer-wins workspace blob. Design tombstones and deterministic merge rules for document membership/order, checkpoints, receipts, and draft revisions. Preserve competing draft texts. Explicitly distinguish opening a new document from an old offline device replaying a deleted document. Wall-clock order alone must not discard user-authored content. + +```mermaid +flowchart LR + Local["WorkspaceStore from 01"] <-->|typed records and local commits| Adapter["Proposed WorkspaceSync"] + Adapter <-->|engine events and saved state| Engine["Existing CKSyncEngine candidate"] + Engine <-->|private changes| Cloud["Private iCloud database"] + Adapter -->|sync status| UI["Workspace UI from 02"] + Cloud <-->|same Apple ID| Other["Another Mobius device"] +``` + +```swift +// Proposed boundary, not a final CloudKit schema. +protocol WorkspaceSynchronizing: Sendable { + func synchronize() async throws +} +// The implementation projects persisted entities through stable record IDs. +// It does not publish GitHub feedback or copy authentication credentials. +``` + +Native window bounds, selected panes, focus, and local scene IDs remain device-local. Restored workspace content must fit the receiving device. Preserve semantic reading anchors; do not promise identical pixel offsets. Remote work becomes available without unexpectedly opening windows or closing a focused local document during an edit. + +Account changes must stop the prior sync scope and isolate its files/records before any new scope starts. iCloud sign-out must not silently upload one account's drafts into another account. GitHub sign-out/revocation must prevent protected fetches and display, with an explicit policy for retained private drafts and caches. Preserve recoverable user work while resolving access; never infer fresh access from stale credentials. + +## Questions and learning needed + +- [Q-09](README.md#q-09) blocks readiness: exact schema, tombstone retention, draft conflicts, metadata migration/recovery, account changes, and cross-device publication ownership. Use controlled two-replica tests and actual CKSyncEngine events; do not infer a transactional guarantee between CloudKit and GitHub. +- [Q-11](README.md#q-11) blocks release delivery: confirm the supported Catalyst CI/test route, signed app identities, iCloud entitlements/container, and distribution audience. The existing iOS installer system does not establish Mac distribution support. +- Resolve remaining performance/accessibility findings from Q-10 against real workloads. Avoid adding product telemetry of private code or comments to gather these measurements. + +## Refinement trigger + +- Trigger: The standalone review loop works and its persistent entities/publication receipts are stable enough to design sync. +- Evidence needed: Record/merge specification, synthetic concurrent-edit cases, selected signing/container configuration, a real-device/Mac test environment, and explicit platform build/runtime commands. +- Next action: Expand this file before adding CloudKit behavior. Run bounded merge/account experiments, revise earlier schemas where necessary, then implement and validate. Missing device/container access blocks real sync acceptance; it is not a passing inconclusive product result. + +## First-release demonstration + +The executable refinement must preserve this sequence: + +1. Open two PRs and repository context on iPhone; explicitly mark part of one review and save feedback text. +2. Resume on iPad; open a second window and follow a search result without losing either review. +3. Change the test PR; verify the since-checkpoint comparison and unchanged-file receipts on Mac, including menu/keyboard navigation. +4. Make competing offline draft edits on two devices; reconnect and recover both texts. Exercise document close/reopen and account switching. +5. Submit feedback once through an explicit user action; interrupt the response and prove recovery does not blindly replay the write from either device. +6. Verify the same workflow with accessibility text sizes and VoiceOver, and inspect the platform-specific CI/runtime evidence. + +This is a planned acceptance flow, not a measured result. Refine exact assertions and data before execution. + +## Decisions and revisions + +| Date | Decision | Source | +| --- | --- | --- | +| 2026-11-14 | Private iCloud continuity is in the first release and uses the same Apple ID. | Q-05/Q-07. | +| 2026-11-14 | Sync semantic workspace metadata/drafts, retaining native presentation and source caches locally. | Overview design proposal. | + +## Resume point + +After 01–05, resolve Q-09/Q-11 and refine this file. Do not call the first release complete before its cross-device and all-platform acceptance passes. diff --git a/Plans/2026-11-14-mobius/07-embedded-review-experiment.md b/Plans/2026-11-14-mobius/07-embedded-review-experiment.md new file mode 100644 index 000000000..a73b216b4 --- /dev/null +++ b/Plans/2026-11-14-mobius/07-embedded-review-experiment.md @@ -0,0 +1,64 @@ +# 07 — Embedded review and live-context experiment + +- Status: outline +- Depends on: [02 — Application workspace](02-application-workspace.md), [05 — Review feedback](05-review-feedback.md), [06 — iCloud resume and release](06-icloud-resume-and-release.md). +- Shared context: [Overview](README.md). + +## Intended outcome + +Establish whether an owning app can embed the same Mobius reviewer and expose a useful bounded live-context action. Produce evidence and a recommendation for a later product decision. A supported negative result can complete the experiment; it does not deliver embedded review as a shipping feature. + +## User stories and requirements + +| Story | Requirement | Intended contribution | +| --- | --- | --- | +| US-08 | R-12 | Demonstrate or reject host injection, truthful build/revision context, and one useful live action. | +| US-07 | R-08, R-09 | Preserve account/store ownership and show revision mismatch or unavailable identity honestly. | + +X-04 applies: no downloaded PR execution, arbitrary native hot loading, or general build service. A running binary contains the code it was built with. Do not label its behavior as the selected PR revision without matching evidence. + +## Known design and assumptions + +Use a synthetic test host with injected Mobius runtime and a precompiled demonstration action, such as opening a known sample screen with chosen fixture data. Reuse the production review presentation rather than copying it into a separate embedded UI. The host owns the action and supplies build identity; the reviewer compares that identity with the selected PR snapshot. + +Bound the refined experiment to one host, one precompiled action, and matching/mismatching/unknown build identity cases. Proposed effort bound: two engineering days after prerequisites are ready; refine this bound before execution. Preserve a report and minimal repeatable harness if it proves useful. Remove unused prototype targets and keep experimental controls out of shipping host behavior. + +```mermaid +flowchart LR + Host["Proposed synthetic host"] -->|injected runtime and build identity| Reviewer["Shared Mobius reviewer from 02/05"] + Reviewer -->|explicit request for known action| Capability["Host-owned precompiled capability"] + Capability -->|observed result and actual build identity| Reviewer +``` + +```swift +// Proposed pseudocode; not a shipping embedding API. +struct EmbeddedReviewContext { + let runtime: MobiusRuntime + let buildIdentity: HostBuildIdentity // Known revision or explicitly unavailable. + let capabilities: [HostReviewCapability] // Typed, precompiled host actions. +} +// The host injects existing resources. Embedding does not open another store. +``` + +Explore whether a built-in action provides enough context to be valuable. If useful execution requires a separately built app or another execution environment, record that as a finding with its scope and operational cost; do not silently implement a runner during this experiment. + +## Questions and learning needed + +[Q-12](README.md#q-12): Which host/context action is useful, what proves revision correspondence, and what UI/lifecycle APIs are needed? Inspect runtime ownership, dismissal, in-flight task cancellation, access boundaries, and host resource use. A screenshot of the embedded view alone is insufficient evidence of safe lifecycle reuse. + +## Refinement trigger + +- Trigger: Standalone workspace and feedback interfaces are proven through 06. +- Evidence needed: Reusable public presentation seam, process/account lifetime contract, selected synthetic host, exact build-identity inputs, and a bounded method. +- Next action: Expand with the experiment template's method, effort bound, evidence criteria, cleanup/retention, and explicit acceptance for positive, negative, and permitted inconclusive outcomes. Keep affected product questions unresolved if evidence is inconclusive. + +## Decisions and revisions + +| Date | Decision | Source | +| --- | --- | --- | +| 2026-11-14 | Investigate embedding/live context later within this series; do not promise it in the first release. | Q-06. | +| 2026-11-14 | Use host-supplied compiled capabilities and truthful revision identity as the initial experiment boundary. | R-12 and X-04. | + +## Resume point + +After 06, resolve the experiment prerequisites and refine Q-12. No host integration or live execution experiment has started. diff --git a/Plans/2026-11-14-mobius/README.md b/Plans/2026-11-14-mobius/README.md new file mode 100644 index 000000000..e27ea06e9 --- /dev/null +++ b/Plans/2026-11-14-mobius/README.md @@ -0,0 +1,298 @@ +# Mobius: a persistent code-review workspace + +## Planning checkpoint + +- Updated: 2026-11-14; repository baseline `b629d56ac44a3f2a5ea59c3d6ae9cd5401f37674`. +- Operation: Create a plan. Product implementation is not requested. +- Requested scope and source: The user's 2026-11-14 chat request and answers to [Q-01–Q-07](#questions-and-resolutions). +- Stage: Publication. +- Completed: Product discovery, repository inspection, primary-source API research, and Linear duplicate search. Created [STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app) for this planning work. +- Pending: Publish the reviewed plan PR and update the Linear link. Later technical decisions remain in Q-08–Q-12. +- Next action: Publish this documentation change, then await an execution or refinement request. The first execution resume point is [01](01-review-state-foundation.md#resume-point). + +## Outcome and scope + +Mobius keeps code review open as ongoing work. A reviewer can leave several pull requests, source files, and searches open, explore without losing a review, and resume on another device. Personal progress records which version was reviewed, so returning after a push reveals what needs another pass. Nobody needs a temporary “got to here” GitHub comment. + +The first release targets **iPhone, iPad, and Mac Catalyst**, including Mac windows, menus, and shortcuts. It supports GitHub PR diffs, comments, approvals, and requests for changes. Private iCloud sync carries workspaces and personal progress between devices using the same Apple ID. These are first-release requirements even though implementation is divided into deliverables. + +Embedding the reviewer inside an owning app, with a possible live execution surface, is a **later feasibility experiment** in this series. It is not a first-release capability promise. + +## User stories + +| ID | Story | +| --- | --- | +| US-01 | Keep several reviews and reference documents open, so investigating one question does not discard another task. | +| US-02 | Resume my place, drafts, and explicit progress without reconstructing my last session. | +| US-03 | Distinguish unchanged reviewed work from new PR changes, so I can concentrate on what needs another pass. | +| US-04 | Browse and search repository context without leaving the review workspace. | +| US-05 | Comment, approve, or request changes against the code I inspected. | +| US-06 | Resume the same work on iPhone, iPad, and Mac. | +| US-07 | Trust progress and recover from failures without incomplete downloads or interrupted submissions appearing complete. | +| US-08 | Learn whether embedding Mobius beside the running app can improve review with live context. | + +## Requirements + +R-01–R-07 and R-12 derive from the user's product choices. R-08–R-11 support repository contracts and correctness. Design details are proposals unless identified as user decisions. + +| ID | Required behavior or constraint | Story | Implementing plan | +| --- | --- | --- | --- | +| R-01 | Run on iPhone, iPad, and Mac Catalyst, with Mac windows, menus, and keyboard commands. | US-06 | [02](02-application-workspace.md), [06](06-icloud-resume-and-release.md) | +| R-02 | Keep multiple PRs, files, and searches open as workspace documents. Opening context preserves the existing review. | US-01, US-04 | [01](01-review-state-foundation.md), [02](02-application-workspace.md), [04](04-repository-exploration.md) | +| R-03 | Persist documents, reading positions, personal review receipts, and drafts across relaunch. Reading position, explicit progress, and a submitted GitHub review are separate facts. | US-02 | [01](01-review-state-foundation.md), [02](02-application-workspace.md), [05](05-review-feedback.md) | +| R-04 | Identify changes since an explicit personal checkpoint using immutable revisions. Distinguish current PR changes from changes since that checkpoint. Preserve unaffected progress without silently advancing the checkpoint. | US-03 | [01](01-review-state-foundation.md), [03](03-github-and-revision-comparison.md) | +| R-05 | Browse files and search paths and text at an identified repository revision within Mobius. Open results without replacing the review and show search coverage. | US-04 | [04](04-repository-exploration.md) | +| R-06 | Read review discussion; compose and explicitly submit comments, approvals, and requests for changes with revision validation and recoverable drafts. | US-05 | [03](03-github-and-revision-comparison.md), [05](05-review-feedback.md) | +| R-07 | Resume documents, progress, and draft work through private iCloud sync on the same Apple ID. Keep device window placement local and expose sync state. | US-02, US-06 | [01](01-review-state-foundation.md) supplies identities; [06](06-icloud-resume-and-release.md) delivers sync | +| R-08 | Preserve original failures, last usable data, and incomplete coverage. Older requests cannot overwrite active state. Missing history cannot imply “reviewed” or “no changes.” | US-07 | [01](01-review-state-foundation.md), [03](03-github-and-revision-comparison.md), [04](04-repository-exploration.md), [05](05-review-feedback.md), [06](06-icloud-resume-and-release.md) | +| R-09 | Scope data by account and repository identity. Keep credentials in device-local Keychain; do not sync them or full repository caches. Protect private code and draft text from diagnostic export. | US-07 | [01](01-review-state-foundation.md), [03](03-github-and-revision-comparison.md), [06](06-icloud-resume-and-release.md) | +| R-10 | Support touch, keyboard, VoiceOver, accessibility text sizes, long lines, and large diffs. Define measured rendering/indexing budgets before the corresponding plan becomes ready. | US-01, US-04, US-06 | [02](02-application-workspace.md), [03](03-github-and-revision-comparison.md), [04](04-repository-exploration.md) | +| R-11 | Integrate module docs, manifests, tests, architecture boundaries, attribution, and CI. Release acceptance requires evidence on all three destinations and real cross-device sync. | Supporting constraint | [01](01-review-state-foundation.md), [02](02-application-workspace.md), [06](06-icloud-resume-and-release.md) | +| R-12 | Evaluate a host-injected embedded reviewer and bounded live-context action; report feasibility and limitations without promising arbitrary PR execution. | US-08 | [07](07-embedded-review-experiment.md) | + +## Not required and explicitly avoided + +| ID | Category | Exclusion | Reason | +| --- | --- | --- | --- | +| X-01 | Explicitly avoided | Product implementation during this planning operation. | Only planning is authorized. | +| X-02 | Not required | Other Git hosting providers, a general code editor, Git push/merge tools, and automatic AI reviews. | The selected workflow is GitHub review. | +| X-03 | Explicitly avoided | Marking files reviewed merely because they were opened; using scroll offsets as review receipts; posting personal progress as GitHub comments. | These recreate the continuity problem. | +| X-04 | Explicitly avoided | Executing downloaded PR code, arbitrary native hot loading, or promising a general build service. | Q-06 selected a later investigation. | +| X-05 | Explicitly avoided | Treating truncated data, missing history, ambiguous lineage, failed saves, or uncertain submissions as success. | Progress must remain trustworthy. | +| X-06 | Not required | A Mobius service for workspace sync or sync across different Apple IDs. | Q-07 selected private iCloud. Authentication hosting remains an alternative in Q-08. | +| X-07 | Explicitly avoided | Importing Where's product models or repurposing InstallerKit's catalog client as a GitHub client. | Mobius owns its domain; shared modules retain their contracts. | + +## Context and discovery + +- Planning issue: [STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app). Completion means plan delivery, not a shipped app. Create linked implementation issues for selected deliverables before execution; preserve this series as the execution record. +- No Mobius matches were found in Markdown or Swift at the baseline. Linear search included all pages, assignees, states, and `includeArchived: true`: 326 issues returned, with no matching app proposal. +- [Package.swift](../../Package.swift) owns libraries; [Project.swift](../../Project.swift) owns app/test targets. RegionViewer demonstrates target-specific Catalyst support without changing the shared iOS destinations. +- [Broadway](../../Shared/Broadway/AGENTS.md) and [SnapshotKit](../../Shared/SnapshotKit/AGENTS.md) use UIKit. Catalyst fits that direction, but Mobius's dependency closure has not been built. +- [InstallerKit's UpdateClient](../../Shared/InstallerKit/Sources/UpdateClient.swift) reads credential-free catalogs. It is not an existing GitHub client. +- [JournalKit](../../Shared/JournalKit/AGENTS.md) drops old segments under a byte budget. It is not selected as the authoritative workspace/draft store. +- Current `./test --help` selects iOS bundles or the host macro bundle. There is no Catalyst test destination. Host macro tests cannot establish Mobius's Mac behavior. + +## Research and evidence + +Consulted 2026-11-14. External sources establish documented capabilities, not live integration results. + +| Question | Evidence | Implication | +| --- | --- | --- | +| Can a PR file response prove complete coverage? | GitHub documents a 3,000-file ceiling for [PR files](https://docs.github.com/en/rest/pulls/pulls#list-pull-requests-files). | Detect incomplete enumeration and expose coverage. | +| Is the compare endpoint sufficient? | [Compare commits](https://docs.github.com/en/rest/commits/commits#compare-two-commits) returns at most 300 changed files, on the first page. | It cannot be the sole authoritative file enumeration. Tree/blob comparison is the proposed fallback. | +| Can GitHub code search follow a PR revision? | [Code search](https://docs.github.com/en/rest/search/search#search-code) considers the default branch and has size/result limits. | Use a revision-bound tree and local text index for PR context. | +| Can trees be enumerated completely? | [Git trees](https://docs.github.com/en/rest/git/trees#get-a-tree) reports truncation and directs clients to fetch subtrees non-recursively. | Track traversal coverage; a missing subtree is not empty. | +| How does feedback bind to code? | [Reviews](https://docs.github.com/en/rest/pulls/reviews#create-a-review-for-a-pull-request) carry a commit ID and event; [review comments](https://docs.github.com/en/rest/pulls/comments#create-a-review-comment-for-a-pull-request) use path, side, and line/range. | Preserve immutable local anchors and validate them against the PR before submission. | +| What native authentication is supported? | GitHub's [user-token flow](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) documents PKCE and client credentials; [public-client guidance](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/best-practices-for-creating-an-oauth-app) addresses native clients. | Do not assume a secretless exchange or default to pasted personal tokens. Resolve Q-08. | +| Can UIKit support the workspace on Mac? | Apple's [Catalyst guidance](https://developer.apple.com/videos/play/wwdc2021/10053/) covers scene-backed windows and menus; [multiple-window guidance](https://developer.apple.com/documentation/uikit/supporting-multiple-windows-on-ipad) separates scenes from shared data. | Share services; keep scene presentation independent. Phone tabs must not require multiple windows. | +| Does CloudKit define merge behavior? | Apple's [CKSyncEngine guidance](https://developer.apple.com/videos/play/wwdc2023/10188/) assigns state persistence and conflict handling to the app. Its [sample](https://github.com/apple/sample-cloudkit-sync-engine) documents container, signing, and real-device/Mac prerequisites. | Define merge/account policies and obtain real two-device evidence. | + +## Design overview + +### Product concepts + +- **Workspace:** a durable collection of review, source, and search documents. Opening another task does not replace the current review. +- **Document:** a typed route with account/repository identity and an explicit revision policy. Pinned source tabs must not silently follow moving branches. +- **Window presentation:** device-local selection, panes, focus, and scene identity. Synced work becomes available to resume without stealing focus or automatically spawning windows. +- **Review receipt:** explicit evidence for a file comparison, including both sides, paths, modes, and content identities. A new head alone neither invalidates every receipt nor proves any one remains current. +- **Checkpoint:** a deliberately captured PR revision and comparison context. “Changes since checkpoint” differs from “current PR changes.” Refresh does not advance the checkpoint. +- **Draft:** user text with its original revision/anchor. Draft, publishing, uncertain outcome, and confirmed publication remain distinct states. + +### Proposed ownership + +Start with `MobiusCore`, `MobiusUI`, and a thin `Mobius` app host. These are proposed names, not existing APIs. + +Core owns typed values, revision/progress policy, local storage, provider protocols, GitHub transport, and sync policy in focused source directories. UI owns observable presentation, Broadway styling, code-rendering adapters, and navigation. The process composition root creates one runtime and injects it into each scene. Views do not open stores or create shared services. + +The initial store is a serial actor with an atomically replaced, versioned metadata file. Source blobs and indexes occupy an independently evictable cache. Stable entity IDs support later CloudKit record projection. Revisit storage technology if measured scale requires it; preserve accepted-data semantics and the store interface. + +```mermaid +flowchart LR + GitHub["GitHub API: existing external"] -->|revision data| Core["MobiusCore: proposed services"] + Core -->|snapshots and failures| UI["MobiusUI: proposed scene models"] + UI -->|intents| Core + Core -->|atomic metadata save| Store["WorkspaceStore: proposed actor"] + Store -->|durable snapshot| Core + Core -->|evictable source objects| Cache["Proposed local cache"] + Store <-->|projection and merge| Sync["Proposed WorkspaceSync"] + Sync <-->|private records| Cloud["iCloud: existing external"] + UI -->|explicit submit| Publish["Proposed ReviewPublisher"] + Publish -->|revision and feedback| GitHub + Publish -->|receipt or uncertain result| Store +``` + +Credentials come from device-local Keychain and are omitted. Sync carries metadata and draft text, not full source caches. Identity/generation checks precede mutation after asynchronous work. A local save and a GitHub write are not one atomic transaction. + +```swift +// Proposed ownership only; not compiled code or existing APIs. +@MainActor +final class MobiusRuntime { + let workspaceStore: WorkspaceStore + let repository: any ReviewRepository + let reviewPublisher: ReviewPublisher + let workspaceSync: WorkspaceSync + // One process/account scope, injected into all scenes. +} + +@MainActor +final class WorkspaceModel { + let workspaceID: Workspace.ID + let runtime: MobiusRuntime + var presentation: WindowPresentation // Device-local. +} + +actor WorkspaceStore { + func apply(_ mutation: WorkspaceMutation, + expectedVersion: WorkspaceVersion) throws -> WorkspaceSnapshot + // External callers await actor isolation. There is no await gap inside + // a local save; publish only after persistence succeeds. +} +``` + +[01](01-review-state-foundation.md) defines the initial value/persistence contracts. Network, sync, and renderer interfaces remain provisional until their outlines are refined. Authentication UI and native scene adapters are omitted. + +## Execution order + +| Order | Plan | Deliverable | +| --- | --- | --- | +| 1 | [Review-state foundation](01-review-state-foundation.md) | Typed workspace/progress state, restart-safe local persistence, and deterministic guards. | +| 2 | [Application workspace](02-application-workspace.md) | Fixture-backed app on all three destinations with tabs, scenes, restoration, and accessible navigation. | +| 3 | [GitHub and revision comparison](03-github-and-revision-comparison.md) | Authenticated PR reading and trustworthy revision-aware diffs/progress. | +| 4 | [Repository exploration](04-repository-exploration.md) | Revision-bound browsing and path/text search alongside reviews. | +| 5 | [Review feedback](05-review-feedback.md) | Comments and reviews with retained drafts and uncertain-outcome recovery. | +| 6 | [iCloud resume and release](06-icloud-resume-and-release.md) | Cross-device continuity and verified first-release acceptance. | +| 7 | [Embedded review experiment](07-embedded-review-experiment.md) | Evidence and a recommendation for embedded review with bounded live context. | + +## Planning horizon + +- Detail now: [01](01-review-state-foundation.md). Synthetic immutable inputs suffice; no GitHub registration, CloudKit container, or renderer choice is required. +- Later selected work: 02–07 remain outlines with refinement triggers, not executable plans. +- Next horizon review: Use 01's actual model and persistence evidence to refine 02 and 03. Resolve Q-08/Q-10 then. Resolve the sync merge policy before 06 becomes executable; 01 preserves the IDs and revisions it needs. +- First-release gate: **01–06 together**. A local foundation or fixture app does not waive sync or GitHub feedback. + +## Shared decisions + +| Date | Decision and reason | Source | +| --- | --- | --- | +| 2026-11-14 | Mobius is a persistent workspace for concurrent review and exploration. | Request, Q-03. | +| 2026-11-14 | iPhone/iPad plus Mac Catalyst with Mac windows, menus, and shortcuts. | Q-01, Q-04. | +| 2026-11-14 | GitHub diffs, comments, approvals, and requests for changes in the first release. | Q-02. | +| 2026-11-14 | Private iCloud continuity on the same Apple ID is a first-release requirement. | Q-05, Q-07. | +| 2026-11-14 | Embedding/live context receives a later experiment. | Q-06. | +| 2026-11-14 | Proposed: personal receipts and explicit checkpoints remain separate from submitted GitHub reviews. | R-03/R-04; immutable revision evidence. | +| 2026-11-14 | Proposed: sync semantic workspace data and drafts; keep native geometry/focus and full code caches local. | R-07/R-09. | +| 2026-11-14 | Proposed: atomic metadata storage, not a bounded journal as the only copy of user work. | JournalKit contract. | + +## Questions and resolutions + +| ID | Status | Question | Affected work | Blocking impact / next action | +| --- | --- | --- | --- | --- | +| [Q-01](#q-01) | closed | First platforms? | R-01, 02, 06 | Resolved; preserve all three. | +| [Q-02](#q-02) | closed | First workflow/provider? | R-06, 03, 05 | Resolved; preserve GitHub review actions. | +| [Q-03](#q-03) | closed | What problem should Mobius solve? | US-01–US-04, R-02–R-05 | Resolved; continuity and exploration remain central. | +| [Q-04](#q-04) | closed | Native macOS or Catalyst? | R-01, 02 | Resolved; validate a Mac-appropriate Catalyst UI. | +| [Q-05](#q-05) | closed | Sync in first release? | R-07, 06 | Resolved; do not defer beyond the release. | +| [Q-06](#q-06) | closed | Embedding/live-review scope? | R-12, 07 | Resolved; later bounded experiment. | +| [Q-07](#q-07) | closed | iCloud or GitHub-backed sync identity? | R-07/R-09, 06 | Resolved; private iCloud, same Apple ID. | +| [Q-08](#q-08) | deferred | GitHub App/OAuth App, token exchange, permissions, and repository access? | 03, 05 | Blocks 03 readiness; validate the supported native flow before refinement. | +| [Q-09](#q-09) | deferred | CloudKit mapping and concurrent edit/delete/account policy? | 05, 06 | Publication ownership blocks 05 readiness; full merge/schema policy blocks 06. 01 must retain stable IDs and revision evidence. | +| [Q-10](#q-10) | deferred | Renderer and measured large-workspace budgets? | 02–04 | Blocks UI/diff readiness; benchmark fixtures during refinement. | +| [Q-11](#q-11) | deferred | Catalyst validation and release distribution/signing? | 02, 06 | Specify compile/runtime validation in 02; resolve distribution in 06. | +| [Q-12](#q-12) | deferred | What can an embedded reviewer prove about a build and PR? | 07 | Blocks a product promise; choose a synthetic host after standalone delivery. | + +All user answers below came from this chat on 2026-11-14. Each was integrated and reviewed for consistency on that date. No user question remains unanswered for the current horizon. + +### Q-01 + +- Answer: iPhone, iPad, and macOS. +- Integration: R-01, US-06, 02, 06; Q-04 selects the Mac implementation. +- History: Opened, answered, integrated, and closed after platform-coverage review. + +### Q-02 + +- Answer: Review GitHub PRs: diffs, comments, approvals, requests for changes. +- Integration: R-06, US-05, 03, 05, and the release gate. +- History: Opened, answered, integrated, and closed after scope review. + +### Q-03 + +- Answer: Linear review flows lose progress; changes since the prior pass are hard to see; iOS makes concurrent reviews difficult; repository exploration interrupts review. The user imagines tabs or desktop-style windows. +- Integration: Outcome, US-01–US-04, R-02–R-05, product concepts, 01–04. Q-06 separately scopes the suggested embedding idea. +- History: Opened, answered, integrated, and closed after checking each problem has an owned deliverable. + +### Q-04 + +- Answer: Mac Catalyst with Mac-specific windows, menus, and shortcuts. +- Integration: R-01, ownership design, 02, 06. +- History: Opened, answered, integrated, and closed against the UIKit module constraints. + +### Q-05 + +- Answer: Resume the same work across all three platforms in the first release. +- Integration: R-07, 06, first-release gate. Local persistence alone is groundwork. +- History: Opened, answered, integrated, and closed after checking release scope. + +### Q-06 + +- Answer: Include a later feasibility experiment for embedding and live execution. +- Integration: R-12, X-04, 07. Negative evidence can complete an experiment without satisfying a product hypothesis. +- History: Opened, answered, integrated, and closed after experiment-scope review. + +### Q-07 + +- Answer: Private iCloud sync using the same Apple ID. +- Integration: R-07/R-09, X-06, design flow, 06. +- History: Opened, answered, integrated, and closed after sync-scope review. + +### Q-08 + +- Answer/source: Unresolved; official token/public-client sources are in Research and evidence. +- Integration: 03 owns registration choice, callback/token refresh, private repositories, organization restrictions, and any necessary authentication service. A confidential credential cannot be assumed secure inside a native binary. +- Deferral: Needed before 03, not the synthetic local foundation. Validate the concrete flow, integrate the result, and repeat review. Do not default to PAT-based onboarding. +- History: Opened and deferred on 2026-11-14. + +### Q-09 + +- Answer/source: iCloud transport is selected; record and merge policies remain unresolved. +- Integration: 05 owns publication intent/receipt identity and must settle cross-device submission ownership before readiness. 06 owns engine-state persistence, account partitioning, close/reorder races, and conflicting draft edits. Preserve both texts on concurrent draft conflict. +- Deferral: Design publication ownership before implementing 05 and the full record/merge policy before 06, using 01's stable IDs. Revise earlier schemas if the evidence requires it. CKSyncEngine is a candidate transport, not a conflict policy. +- History: Opened and deferred on 2026-11-14. + +### Q-10 + +- Answer/source: UIKit/Broadway direction is established; renderer and budgets remain unresolved. +- Integration: 02 owns tabs/scenes/keyboard/VoiceOver; 03/04 own diff and indexing workloads. +- Deferral: Benchmark representative fixtures and set explicit latency/memory budgets before readiness. Initial metadata tests do not depend on the renderer. +- History: Opened and deferred on 2026-11-14. + +### Q-11 + +- Answer/source: Unresolved. RegionViewer and current `./test --help` were inspected; no Catalyst test command exists. +- Integration: 02 must specify a CLI Catalyst build and real window smoke test; 06 owns signed distribution and final runtime acceptance. +- Deferral: Read current tooling and installer contracts before extending them. Use existing iOS test/snapshot schemes and add missing Catalyst coverage. No distribution action is authorized by plan creation. +- History: Opened and deferred on 2026-11-14. + +### Q-12 + +- Answer/source: Unresolved; the user selected an experiment. +- Integration: 07 owns host injection, build identity, bounded live actions, and negative/inconclusive outcomes. +- Deferral: Select the host/method after reusable UI/services exist. Opening a PR does not make its code executable in the running binary. +- History: Opened and deferred on 2026-11-14. + +## Plan review + +- Reviewed: 2026-11-14 against `b629d56ac44a3f2a5ea59c3d6ae9cd5401f37674`, covering all eight files, requirement/exclusion traceability, dependency order, and executable detail for 01. User-answer integration was checked against the complete series. +- Findings and disposition: Aligned the overview's store signature with 01's version-checked, non-reentrant save; corrected 02's claim that a runtime already comes from 01; made Core paths repository-relative; added cross-account/PR receipt tests and post-save/pre-acknowledgment recovery; assigned app attribution to 02. Brought Q-09's submission-ownership decision forward to 05 and added its definitive rejection transition. Later technical decisions remain explicitly deferred to their owners. +- Readiness: 01 is ready for a subsequent execution request. No blocking finding remains in that horizon. 02–07 remain outlines and require refinement before execution. +- Verification: All local Markdown links and anchors resolve; fences are balanced; the dependency graph is acyclic; `git diff --cached --check` passes. Requirements R-01–R-12 have implementing owners. These checks validate the plan, not the proposed app. +- Validation limits: No prototype, device test, product API write, or sync experiment has run. Swift is pseudocode. Mermaid was inspected as source; no local renderer was found. `./test` and `./swiftformat --lint` were skipped because only planning Markdown changed. + +## Review and delivery + +- Plan review: Publication pending. +- Implementation: Not requested or started. +- Review focus: Checkpoint semantics; shared work versus local windows; incomplete coverage and lost history; sync as a release gate. + +## Outcome + +The product direction is established. The series is being prepared for review; execution awaits a new request. From 5ccd37966d21faf0aa1f7c50b8ee8bd536666980 Mon Sep 17 00:00:00 2001 From: Kyle Van Essen Date: Sat, 14 Nov 2026 17:49:57 -0500 Subject: [PATCH 02/12] docs(Mobius): record plan review handoff Link PR #497, record STU-329 as In Review, and preserve the next planning or execution resume action. Reviewed the handoff diff and passed git diff --check; no product code changed. --- Plans/2026-11-14-mobius/README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Plans/2026-11-14-mobius/README.md b/Plans/2026-11-14-mobius/README.md index e27ea06e9..3179d3774 100644 --- a/Plans/2026-11-14-mobius/README.md +++ b/Plans/2026-11-14-mobius/README.md @@ -5,10 +5,10 @@ - Updated: 2026-11-14; repository baseline `b629d56ac44a3f2a5ea59c3d6ae9cd5401f37674`. - Operation: Create a plan. Product implementation is not requested. - Requested scope and source: The user's 2026-11-14 chat request and answers to [Q-01–Q-07](#questions-and-resolutions). -- Stage: Publication. -- Completed: Product discovery, repository inspection, primary-source API research, and Linear duplicate search. Created [STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app) for this planning work. -- Pending: Publish the reviewed plan PR and update the Linear link. Later technical decisions remain in Q-08–Q-12. -- Next action: Publish this documentation change, then await an execution or refinement request. The first execution resume point is [01](01-review-state-foundation.md#resume-point). +- Stage: Handoff; plan published for review. +- Completed: Product discovery, repository inspection, primary-source API research, Linear duplicate search, and review of all eight plan files. Published [PR #497](https://github.com/kyleve/Stuff/pull/497); [STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app) is In Review and links the plan and PR. +- Pending: PR review and merge. Later technical decisions remain in Q-08–Q-12 at their recorded refinement gates. Product execution has not been requested. +- Next action: Await a request to execute 01 or refine a named outline; inspect current PR feedback and repository state when resuming. The first execution resume point is [01](01-review-state-foundation.md#resume-point). ## Outcome and scope @@ -289,10 +289,10 @@ All user answers below came from this chat on 2026-11-14. Each was integrated an ## Review and delivery -- Plan review: Publication pending. +- Plan review: [PR #497](https://github.com/kyleve/Stuff/pull/497), ready for review. [STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app) remains In Review until merge and acceptance verification. - Implementation: Not requested or started. - Review focus: Checkpoint semantics; shared work versus local windows; incomplete coverage and lost history; sync as a release gate. ## Outcome -The product direction is established. The series is being prepared for review; execution awaits a new request. +The reviewed series is published. Plan 01 is ready; 02–07 remain outlines. Execution awaits a new request. From bf933c70e1fe1f7ed1356500b4919a2c8c287c89 Mon Sep 17 00:00:00 2001 From: Kyle Van Essen Date: Sat, 14 Nov 2026 19:08:23 -0500 Subject: [PATCH 03/12] docs(Mobius): refine review continuity and prototype-first delivery Record independent PR workspaces, file-top resumption, and remaining work based on each file last marked reviewed, while keeping full PR diffs accessible. Insert a lightweight interactive mockup across phone, tablet, and desktop before durable storage, and return the foundation to outline. Preserve the tentative answers and subsequent clarifications in Q-13 through Q-18. Validation: reviewed the revised nine-file series and current prototype horizon, checked 118 local links and anchors, balanced fences, eight acyclic plan dependencies, all 12 requirement owners, and git diff --cached --check. No prototype was implemented. Product tests and SwiftFormat were skipped for Markdown-only changes; Mermaid was source-reviewed without a local renderer. --- .../01-review-state-foundation.md | 172 ++++++------------ .../01a-workspace-prototype.md | 103 +++++++++++ .../02-application-workspace.md | 15 +- .../03-github-and-revision-comparison.md | 13 +- .../04-repository-exploration.md | 5 +- Plans/2026-11-14-mobius/05-review-feedback.md | 3 +- .../06-icloud-resume-and-release.md | 13 +- Plans/2026-11-14-mobius/README.md | 128 +++++++++---- 8 files changed, 275 insertions(+), 177 deletions(-) create mode 100644 Plans/2026-11-14-mobius/01a-workspace-prototype.md diff --git a/Plans/2026-11-14-mobius/01-review-state-foundation.md b/Plans/2026-11-14-mobius/01-review-state-foundation.md index 7e9555b26..34e12c4a7 100644 --- a/Plans/2026-11-14-mobius/01-review-state-foundation.md +++ b/Plans/2026-11-14-mobius/01-review-state-foundation.md @@ -1,174 +1,104 @@ # 01 — Review-state foundation -- Status: ready -- Depends on: None. +- Status: outline +- Depends on: [01a — Workspace prototype](01a-workspace-prototype.md). - Shared context: [Overview](README.md). -## Deliverable +## Intended outcome -A `MobiusCore` library that can preserve and reopen several review workspaces without a UI or live provider. Explicit file-review receipts are valid only for the exact comparison they describe. Reading positions and drafts survive a new store instance. This is groundwork; it does not provide the first-release GitHub or iCloud experience. +A `MobiusCore` library preserves independent PR workspaces, the last review file, per-file reviewed versions, and drafts across relaunch. Returning to a review starts at the top of its last file. Remaining-work policy follows Q-15: new edits since each reviewed file's last-reviewed version, and the full PR diff for an unreviewed file, with full PR diffs available for either. + +This is production groundwork after prototype learning. It does not itself deliver a native app, live GitHub integration, or iCloud sync. The earlier ready assessment and detailed implementation sequence are superseded by Q-13–Q-18; the prototype now comes first. ## User stories and requirements -| Story | Requirement | Behavior delivered here | +| Story | Requirement | Intended contribution | | --- | --- | --- | -| US-01, US-02 | R-02, R-03 | Typed workspace documents, independent reading locations, explicit receipts, drafts, and local restoration. | -| US-03 | R-04 | Pure progress evaluation against immutable file-comparison identities and an explicit checkpoint. | -| US-06 | R-07 | Stable entity/account identities and versioned records that future sync can address; no sync yet. | -| US-07 | R-08, R-09 | Honest save/load errors, stale-mutation rejection, account partitioning, and separate evictable content references. | -| Supporting | R-11 | Module documentation, package/test registration, and dependency guards. | - -Definitions live in [Requirements](README.md#requirements). X-01 applies to this planning turn; implementation below is only for a subsequent execution request. X-03, X-05, and X-07 constrain that implementation. Network access, token storage, UI rendering, and CloudKit transport are not delivered here. +| US-01, US-02 | R-02, R-03 | One workspace per PR; independent documents, last-file selection, reviewed versions, drafts, and local restoration. | +| US-03 | R-04 | Immutable per-file review evidence and pure remaining-work evaluation. | +| US-06 | R-07 | Stable identities and versioned data that later sync can address. | +| US-07 | R-08, R-09 | Honest failures, isolation by account/repository/PR, and preservation of accepted data. | +| Supporting | R-11 | Module documentation, manifests, tests, and dependency guards. | -## Context and constraints +[Requirements and exclusions](README.md#requirements) remain authoritative. Precise in-file restoration, reviewed-range tracking, and a manually captured PR-wide checkpoint are not required by the selected workflow. Remote sync, renderer behavior, and publication remain later work. -Read the [root contract](../../AGENTS.md), [Plans contract](../AGENTS.md), and [running-tests skill](../../.agents/skills/running-tests/SKILL.md) before execution. `Package.swift`, `Project.swift`, `BumperBowling.swift`, and `.bumper/RULES.md` are the integration owners. Existing `WhereArchitectureTests` exercise dependency diagnostics; they do not yet cover Mobius. +## Known boundaries and candidate design -Create `Mobius/README.md` and `Mobius/AGENTS.md` for the product group, plus `Mobius/MobiusCore/{Sources,Tests,README.md,AGENTS.md}`. Core initially uses Foundation only. It must not import SwiftUI, UIKit, Where modules, or a UI facade. Do not create empty later modules or provider abstractions with no current consumer. +Read the root and Plans contracts and the running-tests skill during refinement. Proposed paths remain `Mobius/MobiusCore/{Sources,Tests,README.md,AGENTS.md}`, plus the product-group docs. Core initially uses Foundation and must not import UIKit, SwiftUI, Where modules, or a UI facade. Register its library in `Package.swift`, its hosted tests through `Project.swift`, and relevant Bumper boundaries and mutation tests when implemented. -Rules and guards to add together: - -| Invariant | Owner | Proposed guard | -| --- | --- | --- | -| Provider identity is distinct from names/URLs; generated IDs exist only for newly created local entities. | `ReviewIdentity.swift` and module contract. | `ReviewIdentityTests`; persisted identity round trips and no fallback generation. | -| Review receipts bind both file sides, paths, modes, and comparison kind; visiting is not reviewing. | `FileReviewReceipt.swift`, `ReviewProgress.swift`. | Matching tests with changed base/head, rename, deletion, and incomplete inputs. | -| Acknowledged mutations are persisted before they become the store's published snapshot. | `WorkspaceStore.swift`, `AtomicWorkspacePersistence.swift`. | Failure injection and reopen tests using the real persistence implementation. | -| Window edits cannot overwrite a newer state silently. | Store version check. | Competing mutations from the same expected version; one must receive a stale-version error. | -| Core has no app/UI dependency. | New module AGENTS and Bumper configuration. | Mutation test rejecting UIKit and WhereCore, plus an allowed Foundation neighbor. | +Each workspace belongs to one typed account/repository/PR target. Workspace documents can include that review, reference files, and searches. Two PRs with the same file path still have independent progress. A stack connection does not combine their stores, baselines, drafts, or feedback actions. -[Q-09](README.md#q-09) will determine remote merges. This step implements local serialization and revision preservation, not distributed conflict resolution. Its record schema remains provisional until sync refinement. +A resume value identifies the last review file; it does not persist a reviewed line range or require exact scroll restoration. Per-file review evidence records the immutable comparison/version accepted by the explicit file-review action. A new push may make that file need review again, but must retain the earlier evidence needed to calculate its new edits. Unreviewed files have no reviewed baseline and show the full PR diff. -## Data flow +The previous candidate was a serial store actor with version-checked mutations and atomic metadata replacement, separate from evictable source blobs/indexes. Retain it as an option to evaluate after the prototype; do not implement its schema just because it was previously specified. Production identity, errors, migrations, concurrency, and recovery need executable refinement. ```mermaid flowchart LR - Intent["Proposed workspace mutation"] -->|expected local version| Store["Proposed WorkspaceStore actor"] - Store -->|validate and compute| Candidate["Proposed immutable candidate snapshot"] - Candidate -->|versioned archive| Disk["Proposed atomic persistence adapter"] - Disk -->|save succeeded| Publish["Return new snapshot and local version"] - Disk -->|original error| Failure["Keep previous snapshot; report failure"] - Disk -->|load at restart| Store - Comparisons["Synthetic complete/partial file comparisons"] --> Policy["Proposed ReviewProgress policy"] - Receipts["Persisted explicit receipts"] --> Policy - Policy --> Result["Reviewed, needs review, or unavailable"] + Prototype["01a interaction evidence and user feedback"] --> Model["Proposed per-PR workspace model"] + Intent["Explicit file-review action"] --> Evidence["Proposed per-file reviewed version"] + Evidence --> Policy["Proposed remaining-work policy"] + Revisions["Immutable current comparison and coverage"] --> Policy + Model --> Store["Candidate durable store"] + Evidence --> Store + Store --> Resume["Last review file; reopen at top"] + Policy --> Result["New edits / full unreviewed diff / unavailable"] ``` -All named domain components are proposed. The filesystem and Foundation serialization are existing platform facilities. No remote mutation or live code download occurs. Cache contents are outside the authoritative metadata archive. - -## Architecture sketch - ```swift -// Proposed pseudocode. Concrete Codable DTO fields and error cases are defined -// during step 2 and documented as a versioned wire contract. +// Proposed concepts only. Final fields and APIs follow prototype evaluation. struct ReviewTarget: Hashable, Codable, Sendable { let accountID: Account.ID let repositoryID: Repository.ID let pullRequestNumber: PullRequest.Number } -enum WorkspaceDocument: Codable, Sendable { - case review(ReviewDocument) - case source(SourceDocument) - case search(SearchDocument) -} - -struct FileComparisonIdentity: Hashable, Codable, Sendable { - let kind: ComparisonKind - let before: FileRevision // Includes absent/blob/submodule, path, mode, object ID. - let after: FileRevision +struct ReviewResumeFile: Codable, Sendable { + let file: ReviewFile.ID } struct FileReviewReceipt: Codable, Sendable { let target: ReviewTarget - let comparison: FileComparisonIdentity - let reviewedAtRevision: ReviewRevision -} - -protocol WorkspacePersisting: Sendable { - func load() throws -> WorkspaceArchive? - func save(_ archive: WorkspaceArchive) throws -} - -actor WorkspaceStore { - private let persistence: any WorkspacePersisting - private var snapshot: WorkspaceSnapshot - - func apply(_ mutation: WorkspaceMutation, - expectedVersion: WorkspaceVersion) throws -> WorkspaceSnapshot { - // Reject a stale version; construct a candidate without mutating snapshot. - // Synchronously persist the candidate on this actor, with no await gap. - // Only then replace snapshot and return the accepted version. - } + let file: ReviewFile.ID + let reviewedComparison: FileComparisonIdentity + let reviewedRevision: ReviewRevision } +// Workspace owns one ReviewTarget, its documents, resume file, and receipts. +// File identity across renames and comparison context requires refinement. ``` -Every `ID`, Git object identity, path, PR number, and version is a dedicated domain type. Account identity includes the provider host and provider user identity; display login is not the key. Local workspace/document/draft IDs are created once. An absent persisted identity is an error, not a new UUID. +All named domain types are proposed. Receipt/content identity must distinguish both sides, paths, modes, and comparison kind where they affect what was reviewed. A new head alone cannot prove content changed or that it remains reviewed. The progress policy must preserve unavailable evidence as unavailable. Technical handling of rebases, changed bases, renames, missing history, and files leaving the PR diff belongs in the joint refinement of 01 and 03. -Keep `ReadingLocation`, `ReviewCheckpoint`, `FileReviewReceipt`, and `ReviewDraft` as separate concepts. A location holds a document/content identity and a code anchor; its validity is checked on reopen. A receipt is only issued for complete supported comparison data. Absence of a blob for an addition/deletion is a typed file state, not a failed fetch. Unknown or missing objects remain unavailable. +## Questions and learning needed -A changed PR head with identical before/after file content, paths, modes, and comparison kind may retain that file's receipt. A changed base side, rename, or mode change requires another review under the initial conservative policy. Do not infer cross-file or cross-path equivalence from a matching blob alone. A checkpoint also retains the PR base/head and comparison context so later code can detect unavailable or rewritten history. +- [01a](01a-workspace-prototype.md) must supply observed navigation and remaining-work behavior plus the user's feedback before the production model is fixed. If feedback changes Q-13–Q-15, revise the affected requirements first. +- Choose the persistence representation, mutation/version contract, migration behavior, and failure recovery from the evaluated model. The earlier atomic-file proposal remains an option. +- [Q-09](README.md#q-09) owns distributed merge/account policy. Preserve stable identities and revision evidence; local mutation versions must not be presented as distributed causal clocks. +- Keep original errors and accepted user work on failure. Missing storage may initialize an empty store; corrupt or unsupported storage must not be silently replaced with one. -Receipt lookup must also match the account/repository/PR target. A since-checkpoint receipt does not automatically become a current-PR receipt. A UI action may explicitly mark the named current file comparison after the user inspects its delta; the action must identify that exact target instead of inferring intent from the visible tab. +## Refinement trigger and intended verification -`WorkspacePersisting.load()` returns nil only for a genuinely absent archive. Decoding, permission, unsupported-version, and I/O failures throw the original error or an error that retains it. Domain values cross actor boundaries as immutable Sendable snapshots. UI observation is a later adapter. +- Trigger: 01a's artifact and evaluation are complete, and resulting product decisions are integrated. +- Evidence needed: Accepted workflow, concrete workspace/document/receipt identities, the last-file resume behavior, and the required state transitions demonstrated by the mockup. +- Next action: Expand this file into an executable plan with owned interfaces, implementation steps, schema/recovery details, and a test matrix. Recheck the target graph and relevant repository contracts before readiness. -## Steps - -1. **Register Core and its guards.** Add the package library and a `MobiusCoreTests` hosted bundle through the existing `unitTests` helper, with the first identity value and its matching test so both targets are nonempty. Include the bundle in `Stuff-iOS-Tests`; use `StuffTestHost`. Extend Bumper's component catalog/included paths with MobiusCore's foundation boundary and tests rejecting UI/Where imports. Update the catalog, root architecture description, module docs, and run `./sync-agents`. -2. **Define and test the durable model.** Add focused files for identity, workspace documents, reading locations, checkpoints, receipts, progress, drafts, and the archive DTO. Keep 1:1 test filenames and shared builders in `MobiusCoreTestSupport.swift`. Document stable serialized keys/cases and an explicit schema version. Drafts retain user text and original revision anchors; no publication state machine is implemented yet. A local mutation version must not be presented as a cross-device causal clock. -3. **Implement local persistence and serialization.** Add `AtomicWorkspacePersistence.swift` and the serial `WorkspaceStore.swift`. Write an archive atomically before publishing the new snapshot. Scope file locations by account identity; keep source blobs/indexes outside the metadata archive. Missing files initialize an empty store; corrupt or unknown-version files remain intact and surface an error. Inject the persistence protocol into the store; fakes conform to that protocol. -4. **Prove transitions.** Implement the scenario matrix below. Include independent workspaces, stale callers, failed saves, reopening, and explicit progress changes. Opening/selecting a document does not create a receipt. Marking a file unreviewed changes only that review's local state. Preserve the original checkpoint when a newer PR snapshot is supplied. -5. **Review and publish groundwork.** Run the listed checks, inspect the complete diff through code-review, and use github-workflow for commit/push/PR. Record actual counts and revisions here. Reconcile an implementation issue created from STU-329 before beginning execution; do not close the planning issue as evidence of a shipped app. Update the horizon using the actual model before refining 02/03. - -Each meaningful implementation step is a coherent commit after its applicable checks. Do not commit a failing intermediate target graph. - -## Acceptance and verification - -Commands run from the repository root after the new targets exist. Test names below are proposed coverage, not claims of existing tests. - -| Requirement | Acceptance criterion | Procedure | Expected result | -| --- | --- | --- | --- | -| R-02/R-03 | Two PR documents plus a source and search document retain independent identity, ordering, location, and draft text after reopening. | `./test MobiusCoreTests`; `WorkspaceTests`, `WorkspaceStoreTests`. | Same persisted values from a new store; no generated replacement IDs. | -| R-03/X-03 | Opening, scrolling, and refreshing do not mark a file reviewed or submit feedback. | `ReviewProgressTests` with the same document under each operation. | Receipt set changes only for the explicit review intent. | -| R-04/R-09 | Within the same account/repository/PR, identical compared file content retains progress; changed sides, path, mode, or comparison kind requires review. Identical content in another PR/account cannot reuse a receipt. | Parameterized `FileReviewReceiptTests` / `ReviewProgressTests`. | No timestamp/head-only shortcut or cross-target progress leak. | -| R-04/R-08 | Partial manifests, missing baselines, unsupported file kinds, and unavailable content cannot report complete review. | Synthetic fixtures with explicit coverage states. | Typed unavailable/needs-review result; existing checkpoint preserved. | -| R-08 | A failed replacement keeps the prior accepted state; a stale window mutation is rejected. | Store tests with protocol-conforming failure injection and concurrent calls. | Original error retained, no partial in-memory commit or lost newer state. | -| R-03/R-09 | Real archive save/reopen works; corrupt/unknown-version input is preserved; account A cannot load account B's file. | `AtomicWorkspacePersistenceTests` in temporary directories. | Exact round trip, visible failures, isolated stores. | -| R-11 | New bundle is selected, Core dependencies are enforced, and formatting passes. | `./ide --no-open`, `./test MobiusCoreTests`, `./swiftformat --lint`. | Nonempty suite; default architecture checks and mutations pass. | - -Inspect all source/test selection and the generated target graph. A zero-test pass is not acceptance. These checks establish local behavior only; no image, GitHub, Catalyst, or CloudKit result is claimed by this deliverable. - -## Recovery - -A mutation that fails before replacement leaves the prior archive authoritative and the candidate unpublished. Retry only after reporting the failure and reconciling the caller's expected version. On startup, preserve a corrupt or unsupported archive and report it; never replace it with an empty workspace. A temporary incomplete write is not an accepted archive. Implement cleanup only for temporary files owned by this store. - -If the process ends after replacement but before the caller receives acknowledgment, reopen the durable version before retrying. Do not replay the old mutation against a guessed version. Include a restart test seeded with that committed-but-unacknowledged snapshot. - -If manifest generation or tests stop partway, inspect the existing edits and rerun `./ide --no-open` after completing the graph. Do not delete caches, simulators, or unrelated work to recover. No live account data is involved in the synthetic tests. +The eventual checks must demonstrate two independent PR workspaces reopening with their references and drafts; file-top resumption; per-file new-edit/full-diff selection; preserved prior review evidence after a push; no cross-PR progress leakage; explicit baseline advancement; honest incomplete history; and failed/stale saves preserving accepted state. Include real persistence round trips and controlled competing mutations. Use the matching Core tests, architecture checks, and formatting after targets exist; a zero-test pass is not acceptance. ## Decisions and revisions | Date | Decision | Source | | --- | --- | --- | -| 2026-11-14 | Make durable review identity/progress the first deliverable; use a small atomic metadata store with a replaceable persistence interface. | [Shared decisions](README.md#shared-decisions). | -| 2026-11-14 | Keep network, remote conflict policy, and scene layout outside this executable horizon. | Q-08–Q-11 do not affect local fixture acceptance. | - -## Progress - -- [ ] Register module, tests, docs, and boundary guards. -- [ ] Implement typed values and explicit progress semantics. -- [ ] Implement accepted-state persistence and recovery. -- [ ] Verify the scenario matrix and applicable checks. -- [ ] Review, commit, push, and publish the implementation. +| 2026-11-14 | Initially proposed foundation-first delivery with atomic metadata persistence and PR-wide explicit checkpoints. | Initial plan at `d1ee30cc82d110dfac94fecb58fce9762020cb58`; no implementation ran. | +| 2026-11-14 | Replace the checkpoint model with per-file reviewed versions; resume from the file top; keep one workspace per PR. | Q-13–Q-15. | +| 2026-11-14 | Return this deliverable to outline and refine it after a lightweight, three-layout prototype. | Q-16–Q-18. | ## Execution record -Not started. Plan creation did not generate an Xcode project, implement the module, or run its future tests. +Not started. No module, schema, Xcode project generation, or implementation test was produced by planning. ## Resume point -After an execution request, verify the plan review and source baseline, create/link the implementation issue, then begin step 1. No product decision blocks this synthetic foundation. If later sync design changes its wire contract, revise the affected plans before proceeding. +Await 01a evidence, integrate it, then refine this outline and repeat review before execution. ## Outcome -Not implemented. Acceptance here will establish local review-state groundwork, not completion of the first release. +Pending prototype learning and executable refinement. Completion will establish durable local review state, not the first release. diff --git a/Plans/2026-11-14-mobius/01a-workspace-prototype.md b/Plans/2026-11-14-mobius/01a-workspace-prototype.md new file mode 100644 index 000000000..0386b84ff --- /dev/null +++ b/Plans/2026-11-14-mobius/01a-workspace-prototype.md @@ -0,0 +1,103 @@ +# 01a — Workspace and remaining-work prototype + +- Status: ready +- Depends on: None. +- Ordering: Inserted before [01](01-review-state-foundation.md); the [overview](README.md#execution-order) owns execution order. +- Shared context: [Overview](README.md). + +## Deliverable and investigation + +A lightweight interactive mockup for evaluating independent PR workspaces, file-top resumption, and remaining work across phone, tablet, and desktop layouts. The user selected a prototype before durable state work (Q-16), all three layouts together (Q-17), and a lightweight mockup for quick iteration (Q-18). + +Investigate whether the navigation and comparison labels make it clear which PR, file, version, and unfinished work the reviewer is seeing. The agreed behavior comes from Q-13–Q-15; layout and navigation details are hypotheses to evaluate, not final native UI decisions. + +Bound the first pass to one self-contained browser artifact, two synthetic PR workspaces, two fixture revisions, three viewport layouts, and one feedback round. Record further iterations explicitly rather than expanding the prototype into a production implementation. + +## User stories and requirements + +| Story | Requirement | Evidence from this prototype | +| --- | --- | --- | +| US-01, US-04 | R-02, R-05 | Separate PR contexts; reference files and a fixture search remain with their PR. | +| US-02 | R-03 | Returning to a PR restores its last review file at the top. | +| US-03 | R-04 | Reviewed files show new edits; unreviewed files show the full PR diff; either can open its full PR diff. | +| US-06 | R-01, R-10 | The same interaction is inspectable at phone, tablet, and desktop viewport sizes. This is not native platform acceptance. | + +The prototype supplies interaction evidence for these requirements; it does not complete their production acceptance. R-06/R-07 and the rest of the release requirements remain in later plans. + +## Scope and artifacts + +Proposed artifact: `Plans/2026-11-14-mobius/Prototype/index.html`, with embedded styles, scripts, and synthetic fixtures. Use semantic browser controls and no external dependencies or network data. Store the interaction evidence and feedback in this plan's execution record. Read the repository and Plans contracts before implementation. + +Keep session state in memory so fixture behavior is reproducible through an explicit Reset action. Workspace switching within the mockup preserves each PR's documents, last file, draft fixture, and review state. Reload durability, CloudKit, authentication, native menus/windows, a real Git engine, real search indexing, and live GitHub feedback are outside this artifact. Those exclusions do not alter first-release scope. + +The artifact must identify itself as a mockup using sample data. Do not copy its state schema into production automatically; 01 must derive its model from evaluated behavior and repository contracts. + +## Scenario and state flow + +Use synthetic PR 42 and PR 43. Each has a distinct workspace even if they share a file path. An optional stack-connection label links the PRs without combining their state. + +Within PR 42, version 1 includes `Parser.swift`, `Store.swift`, and `Stable.swift`. Mark Parser and Stable reviewed; leave Store unreviewed. The simulated push to version 2 changes Parser and Store, while Stable stays unchanged. + +- Remaining work shows Parser's new edits since its last reviewed version and Store's full current PR diff. Stable has no new work and remains reachable through the full PR view. +- Opening the full PR diff for Parser shows its complete current PR change. Changing views does not advance a reviewed version. +- Marking Parser reviewed at version 2 advances only Parser's baseline. Keep the visible file understandable while updating the remaining-work list; the precise transition is part of the evaluation. +- Open a fixture reference file and search in PR 42, switch to PR 43, then return. Restore PR 42's context and open its last review file at the top. A reference document is not a new review workspace. + +```mermaid +flowchart LR + Fixtures["Synthetic PRs and prepared revision diffs"] --> Session["Proposed in-memory mockup session"] + Actions["Switch PR / file / comparison view"] --> Session + Mark["Explicit mark-file-reviewed action"] -->|that PR and file only| Session + Push["Simulate push"] -->|new fixture revision; retain reviewed versions| Session + Session --> Remaining["New edits or full diff for unreviewed file"] + Session --> Full["Full current PR diff"] + Remaining --> Layouts["Phone / tablet / desktop layouts"] + Full --> Layouts + Reset["Reset sample data"] --> Session +``` + +All components are proposed mockup state. Swift pseudocode does not apply to this browser artifact; the native ownership sketch remains provisional in the overview. Predefined fixture diffs simulate comparisons and do not verify a Git diff algorithm. + +## Steps + +1. **Build the scenario fixture.** Define two PR identities, independent document collections and last-file selections, per-file reviewed versions, and prepared full/incremental diffs for the two versions. Keep shared-path fixtures isolated by PR. Document the fixture states alongside the artifact. +2. **Create the interactive shell.** Add workspace switching, a review-file list, remaining-work/full-PR views, a full-diff action for the selected file, fixture reference/search navigation, explicit file-review actions, Simulate push, and Reset. Prototype suitable navigation for narrow, medium, and wide viewports using the same state. Treat layout and labels as candidates for feedback. +3. **Exercise the return visit.** Run the scenario above at recorded phone, tablet, and desktop viewport sizes. Confirm a resumed review file starts at the top and that another PR's state is unaffected. Check both mouse/pointer and keyboard operation; inspect narrow-layout touch-target usability. Record what was actually exercised rather than claiming native device validation. +4. **Collect evidence and feedback.** Deliver the artifact with the scenario and representative captures of the three layouts. Ask the user to try workspace switching and the post-push remaining-work view. Record confusing transitions, requested changes, and whether the workflow should proceed, change, or receive another prototype iteration. +5. **Review and hand off.** Integrate supported feedback into the overview and affected outlines, retaining unresolved decisions. Review the changed artifact and plan through code-review, run relevant checks, then commit/push and publish through github-workflow. Do not refine the durable model until the required prototype feedback is recorded. + +For local browser inspection, a loopback-only static server can serve the artifact, for example `python3 -m http.server 8765 --bind 127.0.0.1 --directory Plans/2026-11-14-mobius/Prototype`. Use an available port and stop the owned server after inspection. If browser automation is unavailable, record the missing runtime evidence; source inspection alone does not establish interactive acceptance. + +## Acceptance and verification + +| Criterion | Check | Expected evidence | +| --- | --- | --- | +| Workspaces stay independent. | Switch PR 42 → PR 43 → PR 42 after opening context and changing review state. | Each retains its own documents, last file, and reviewed versions; a stack link has no shared-state effect. | +| Resume starts at the file top. | Scroll within a review file, leave the PR, and return. | The same review file opens from the top. No reviewed-range state is inferred. | +| Remaining work follows the chosen model. | Mark Parser/Stable reviewed at version 1, leave Store unreviewed, then simulate version 2. | Parser shows new edits; Store shows its full PR diff; Stable has no remaining changes. | +| Full context is accessible. | Open the full PR diff for both Parser and Store; switch views and PR workspaces. | Complete current PR diffs remain available and baselines change only through the explicit file-review action. | +| All three layouts can be evaluated. | Execute the scenario at recorded narrow, medium, and wide browser sizes. | Captures plus interaction notes identify each viewport and any usability failures. | +| The experiment produces a decision. | Review the artifact with the user. | Recorded feedback supports proceeding, revising, or another bounded iteration. A supported negative result is valid; pending feedback leaves the experiment incomplete. | + +Inspect the browser console for runtime errors and verify all artifact resources load locally. Use `git diff --check` and review local plan links after updates. No app test suite or snapshot baseline is implied by this browser mockup; use proportionate browser interaction checks. Do not claim iPhone/iPad/Catalyst runtime, VoiceOver, persistence, provider, or sync validation from viewport captures. + +## Recovery and retention + +Reset restores the known fixture; reload also starts a fresh session. Keep the prototype isolated from real accounts and data. Preserve the artifact and concise evaluation record as design evidence. Remove abandoned variants before publication; retain any alternative only when its recorded feedback explains why it is useful. Native implementation must not import the prototype runtime. + +## Progress and execution record + +- [ ] Create fixture and interactive artifact. +- [ ] Exercise all three layouts and capture evidence. +- [ ] Collect and integrate user feedback. +- [ ] Review and publish the artifact and evaluation record. + +Not started. No prototype artifact or runtime result exists yet. + +## Resume point + +After an execution request, read current plan feedback and the latest question resolutions, then begin the bounded artifact. Plan creation and the selection of this deliverable did not authorize its execution. + +## Outcome + +Pending prototype evidence and feedback. [01](01-review-state-foundation.md) remains an outline until those findings are integrated. diff --git a/Plans/2026-11-14-mobius/02-application-workspace.md b/Plans/2026-11-14-mobius/02-application-workspace.md index 06506afbd..4a9132c7d 100644 --- a/Plans/2026-11-14-mobius/02-application-workspace.md +++ b/Plans/2026-11-14-mobius/02-application-workspace.md @@ -6,15 +6,15 @@ ## Intended outcome -Mobius launches on iPhone, iPad, and Mac Catalyst with a real persistent workspace. A reviewer opens multiple synthetic PRs and repository documents, switches among them, and returns to the same work after relaunch. iPad/Mac support multiple windows; iPhone provides a usable document/tab switcher within its available scene capabilities. +Mobius launches on iPhone, iPad, and Mac Catalyst with a persistent workspace per PR. A reviewer switches between independent synthetic PR workspaces, each retaining its reference files and searches. Returning to a review opens its last file from the top. iPad/Mac support multiple windows; iPhone provides usable workspace/document switching within its available scene capabilities. -Success is a runtime demonstration with two reviews and several reference documents, independent window selections, Mac menu/keyboard actions, and restoration. This is fixture-backed groundwork, not live GitHub or sync delivery. +Success is a native runtime demonstration with two independent review workspaces and their reference documents, independent window selections, Mac menu/keyboard actions, and file-top resumption. It follows the evaluated browser mockup in [01a](01a-workspace-prototype.md). This is fixture-backed groundwork, not live GitHub or sync delivery. ## User stories and requirements | Story | Requirement | Intended contribution | | --- | --- | --- | -| US-01, US-02 | R-02, R-03 | Persistent documents, tab switching, reading positions, and scene restoration. | +| US-01, US-02 | R-02, R-03 | Independent PR workspaces, document switching, file-top resumption, and scene restoration. | | US-06 | R-01 | iPhone/iPad app and Mac Catalyst windows, menus, and shortcuts. | | US-01, US-06 | R-10 | Accessible adaptive layout and keyboard/focus behavior. | | Supporting | R-11 | Host/UI targets, docs, unit/image coverage, and Catalyst validation. | @@ -25,9 +25,9 @@ See [definitions and exclusions](README.md#requirements). X-03 and X-07 apply. D Proposed paths: `Mobius/MobiusUI/{Sources,Tests,SnapshotTests,README.md,AGENTS.md}` and `Mobius/Mobius/{Sources,Tests,Resources,README.md,AGENTS.md}`. Add the host and UI products through the root manifests. Give Mobius explicit iPhone/iPad/Catalyst destinations; do not expand Where's destination constant. -Create the Core runtime once in the process composition root. Each scene receives a `WorkspaceModel` with its own local presentation and the shared store. Restore scene-to-workspace references; missing or explicitly deleted workspace identity produces a recovery/selection state, not a new random identity. Window closure releases that scene's work; it does not delete the workspace or affect another scene's tasks. +Create the Core runtime once in the process composition root. Each scene receives a `WorkspaceModel` for one PR with local presentation and the shared store. Restore scene-to-workspace references; missing or explicitly deleted workspace identity produces a recovery/selection state, not a new random identity. Window closure releases that scene's work; it does not delete the workspace or affect another scene's tasks. PRs remain independent when a stack connection is displayed. -A visible tab bar or compact switcher selects typed review/source/search documents. Explore in a new document by default. Optional panes on larger layouts preserve the same model; no free-form floating-window system is required inside an iPhone screen. Mac windows use system scene APIs, with app-specific menu and shortcut routing to the focused scene. Separate shared document closure from closing a native window. +Use 01a's evaluated interactions to distinguish switching PR workspaces from switching documents inside one PR. Layouts and labels from the mockup remain candidates until validated natively. Mac windows use system scene APIs, with app-specific menu and shortcut routing to the focused scene. Separate shared document closure from closing a native window. Reopening a review file starts at its top; precise in-file restoration is not required. ```mermaid flowchart LR @@ -57,11 +57,11 @@ Declare Mobius's attribution inputs and bundled report through CreditKit's exist - [Q-10](README.md#q-10): Select the code-text substrate and layout after measuring long lines, many documents, accessibility sizes, selection, and VoiceOver. Identify real latency/memory budgets and fixture sizes before readiness. - [Q-11](README.md#q-11): Specify CLI Catalyst compile coverage and a native window/menu smoke test. Existing `./test` cannot be assumed to target Catalyst. Extend repository tooling only where required, with its public-command tests and owning docs. -- Reuse the current Broadway scroll restoration seam if it fits local reading positions; it is not itself the durable cross-device workspace store. +- Integrate Q-13–Q-15 and prototype feedback: one workspace per PR, file-top resumption, and clear remaining-work/full-PR navigation. Existing scroll-restoration machinery does not establish a requirement to restore an exact review offset. ## Refinement trigger -- Trigger: 01 completes with actual state/persistence interfaces. +- Trigger: 01a's feedback is integrated and 01 supplies actual state/persistence interfaces. - Evidence needed: Working Core types, renderer/layout probe results, dependency closure, an explicit Catalyst build/runtime procedure, and an accessible tab/window interaction specification. - Next action: Read the applicable UI/module/tooling contracts, expand this file into executable steps and acceptance criteria, and review it before implementation. Keep the first runtime demo synthetic and repeatable. @@ -71,6 +71,7 @@ Declare Mobius's attribution inputs and bundled report through CreditKit's exist | --- | --- | --- | | 2026-11-14 | Share UIKit/Broadway through Catalyst, with Mac-specific windows, menus, and shortcuts. | Q-04. | | 2026-11-14 | Keep platform scene presentation local while workspace identity persists. | Overview design proposal. | +| 2026-11-14 | Adopt per-PR grouping and file-top resumption after the lightweight mockup is evaluated. | Q-13/Q-14, Q-16–Q-18. | ## Resume point diff --git a/Plans/2026-11-14-mobius/03-github-and-revision-comparison.md b/Plans/2026-11-14-mobius/03-github-and-revision-comparison.md index 8c89f89ff..07bf0469f 100644 --- a/Plans/2026-11-14-mobius/03-github-and-revision-comparison.md +++ b/Plans/2026-11-14-mobius/03-github-and-revision-comparison.md @@ -6,7 +6,7 @@ ## Intended outcome -The workspace opens actual GitHub PRs and discussions. A reviewer can inspect the current PR diff, set a personal checkpoint, leave, and return after changes to identify what requires another pass. The app shows the revisions and completeness of the comparison it actually loaded. +Each workspace opens its own GitHub PR and discussion. A reviewer marks individual files reviewed, leaves, and returns after a push. Remaining work shows new edits since each reviewed file's last-reviewed version and the full PR diff for unreviewed files. Either file can open its full current PR diff. The app shows the revisions and completeness of the comparison it actually loaded. Demonstrate ordinary pushes, force-push/rebase, base-branch movement, unchanged files, renamed/deleted files, unavailable old history, and paginated/limited responses. Honest unavailable history is an acceptable state; falsely reporting “nothing changed” is not. @@ -14,7 +14,7 @@ Demonstrate ordinary pushes, force-push/rebase, base-branch movement, unchanged | Story | Requirement | Intended contribution | | --- | --- | --- | -| US-03 | R-04 | Current-PR and since-checkpoint comparisons, using 01's receipts. | +| US-03 | R-04 | Per-file new-edit comparisons and full PR diffs, using 01's reviewed-version evidence. | | US-05 | R-06 | Authenticated PR/diff/discussion reading; submission remains in 05. | | US-07 | R-08, R-09 | Credential/account boundaries, immutable snapshots, coverage, and stale-result control. | | US-01, US-06 | R-10 | Bounded diff loading/rendering with measured budgets. | @@ -25,14 +25,14 @@ All [exclusions](README.md#not-required-and-explicitly-avoided) apply. Do not in Keep product-specific GitHub adapters in `Mobius/MobiusCore/Sources/GitHub/`, revision logic in `Mobius/MobiusCore/Sources/Review/`, and credential storage behind a device-local interface. The root injects transport, credential, cache, and persistence collaborators. UI owns the native authentication presentation adapter. No new general GitHub framework is justified by this plan alone. -The proposed `ReviewRevision` captures base tip, head tip, and the resolved comparison base. Current PR comparison uses the appropriate merge-base-to-head content. The since-checkpoint surface compares saved and current head trees directly, with a separate indication when the PR's base/comparison context changed. Do not present a three-dot comparison as an exact old-tree-to-new-tree delta after a rebase. Changes to the PR comparison itself must re-evaluate both sides of file receipts, even when head content is unchanged. +The proposed `ReviewRevision` captures base tip, head tip, and the resolved comparison base. Current PR comparison uses the appropriate merge-base-to-head content. For a previously reviewed file, the candidate new-edit comparison uses its saved reviewed version and current content, with a separate indication when the PR's base/comparison context changed. Each file can have a different reviewed baseline. Do not present a three-dot comparison as an exact old-tree-to-new-tree delta after a rebase. Refine rename, removed-file, and base-movement behavior with 01; a head-only delta must not hide a changed PR comparison. ```mermaid flowchart LR PR["GitHub PR identity and refs"] --> Resolve["Proposed revision resolver"] Resolve --> Snapshot["Immutable trees/blobs and coverage"] Snapshot --> Diff["Proposed comparison engine"] - Checkpoint["Saved personal checkpoint"] --> Diff + Baseline["This PR file's last-reviewed version, if any"] --> Diff Diff --> Progress["ReviewProgress from 01"] Progress --> UI["Workspace diff documents from 02"] ``` @@ -49,7 +49,7 @@ protocol ReviewRepository: Sendable { GitHub PR-file/compare responses have documented limits; see [research](README.md#research-and-evidence). Treat them as useful metadata, not guaranteed complete manifests. Resolve immutable trees and blobs, traverse truncated trees by subtree, and retain coverage for every material omission. A refresh must not splice pages from different moving revisions. Bound retries if the PR changes while resolving it. -Re-evaluate exact file comparison identities rather than resetting all progress on every new head. Keep refresh separate from setting the personal checkpoint. Retain cached baseline evidence when available. Since full caches do not sync, a new device may have to fetch old objects; deleted/unreachable objects must produce a visible baseline gap, not fabricated equivalence. +Re-evaluate exact file comparison identities rather than resetting all progress on every new head. Retain prior review evidence when new edits appear. Only the explicit file-review action advances that file's baseline; navigation, full-diff viewing, and refresh do not. Since full caches do not sync, a new device may have to fetch old objects. Deleted/unreachable objects must produce a visible baseline gap with access to the current full PR diff, not fabricated equivalence or a claim that no work remains. Fixtures must include binary/non-text and oversized files, missing patches, CRLF/Unicode/long lines, submodules, rename/mode changes, missing pages, permission loss, cancellation, rate limiting, and superseded refreshes. Define supported rendering and indexing limits before readiness. Show unsupported content honestly without marking its review complete. @@ -58,6 +58,7 @@ Fixtures must include binary/non-text and oversized files, missing patches, CRLF - [Q-08](README.md#q-08) blocks readiness: compare GitHub App and OAuth App access/onboarding; verify PKCE/callback/token-refresh behavior and concrete client-credential handling. Decide whether native public-client behavior is acceptable or an authentication broker is required. Do not assume the developer's `gh` credentials can ship in Mobius. - Clarify the first supported GitHub host/organization policies during authentication refinement. Repository-account identity must support safe sign-out and switching regardless of initial account-picker scope. - [Q-10](README.md#q-10): Choose a bounded line-diff/rendering path using fixtures; distinguish an API-derived patch from a locally computed exact-tree comparison. +- Apply [Q-15](README.md#q-15) and 01a feedback. The comparison model is per file within one PR; stack links do not combine progress. Refine edge cases without replacing the selected workflow with a PR-wide manual checkpoint. - A stale review anchor is retained for 05 to resolve; network refresh must not silently rewrite user draft intent. ## Refinement trigger @@ -71,7 +72,7 @@ Fixtures must include binary/non-text and oversized files, missing patches, CRLF | Date | Decision | Source | | --- | --- | --- | | 2026-11-14 | Use immutable revisions and explicit coverage; timestamps and a single head SHA are insufficient review evidence. | Q-03, R-04, official API research. | -| 2026-11-14 | Keep private personal checkpoints independent of GitHub's review publication. | Overview product model. | +| 2026-11-14 | Replace the earlier PR-wide checkpoint proposal with per-file reviewed versions and remaining work, while keeping full PR diffs accessible. | Q-15. | ## Resume point diff --git a/Plans/2026-11-14-mobius/04-repository-exploration.md b/Plans/2026-11-14-mobius/04-repository-exploration.md index 986700aae..658c4d337 100644 --- a/Plans/2026-11-14-mobius/04-repository-exploration.md +++ b/Plans/2026-11-14-mobius/04-repository-exploration.md @@ -6,7 +6,7 @@ ## Intended outcome -Browse the repository and search file paths and text while the current review stays open. Results open as additional workspace documents at a stated revision. Returning to the review preserves its location and progress. +Browse the repository and search file paths and text while the current review stays open. Results belong to that PR's workspace and open at a stated revision. Switching PRs preserves each workspace's context; resuming the review returns to its last file at the top with progress preserved. Demonstrate a search from PR A, opening a file outside its diff, switching to PR B, and returning to A unchanged. Repeat at different revisions where the same path has different content. Partial indexing must not look like a complete “no results” response. @@ -15,7 +15,7 @@ Demonstrate a search from PR A, opening a file outside its diff, switching to PR | Story | Requirement | Intended contribution | | --- | --- | --- | | US-01, US-04 | R-02, R-05 | Repository tree, path search, text search, and persistent source/search documents. | -| US-02 | R-03 | Restore semantic queries and reading locations without replacing the active review. | +| US-02 | R-03 | Restore semantic queries and the last review file within its PR workspace. | | US-07 | R-08, R-09 | Revision/coverage labels, account-isolated caches, and cancellation. | | US-04, US-06 | R-10 | Accessible results and bounded indexing/rendering workloads. | @@ -65,6 +65,7 @@ GitHub's default-branch code-search endpoint is not the implementation of PR-rev | Date | Decision | Source | | --- | --- | --- | | 2026-11-14 | Repository exploration is part of the review workspace, with path and text search at an explicit revision. | Q-03, R-05. | +| 2026-11-14 | Keep exploration documents with their PR when switching to another PR workspace. | Q-13. | ## Resume point diff --git a/Plans/2026-11-14-mobius/05-review-feedback.md b/Plans/2026-11-14-mobius/05-review-feedback.md index 870890863..fcff7e696 100644 --- a/Plans/2026-11-14-mobius/05-review-feedback.md +++ b/Plans/2026-11-14-mobius/05-review-feedback.md @@ -24,7 +24,7 @@ X-02, X-03, and X-05 apply. No automatic review publication on navigation, backg Core owns `ReviewDraft`, anchor mapping, and a proposed `ReviewPublisher`. UI owns composition, confirmation, and recovery presentation. Scope publication by account, PR, and draft revision; one local owner serializes mutations for that draft. Record the original immutable file comparison and anchor when text is authored. -Read the current PR state before submission. If the head or comparison context changed, show the change and retain the draft until its target is revalidated. A comment authored while viewing a since-checkpoint comparison must map to a valid location in the PR review diff, or remain an unsubmitted draft with a useful explanation. Never attach a comment to the same line number in unrelated content. Submit an explicit commit ID where the API supports it; a preflight read does not make a later API write atomic with branch updates. +Read the current PR state before submission. If the head or comparison context changed, show the change and retain the draft until its target is revalidated. A comment authored while viewing a file's new edits since its reviewed version must map to a valid location in the PR review diff, or remain an unsubmitted draft with a useful explanation. Never attach a comment to the same line number in unrelated content. Submit an explicit commit ID where the API supports it; a preflight read does not make a later API write atomic with branch updates. ```mermaid stateDiagram-v2 @@ -61,6 +61,7 @@ GitHub review/comment schemas are linked in [research](README.md#research-and-ev - Provider evidence from 03 must establish actual permission failures, pending-review constraints, line/range validation, and supported reply/review operations. - [Q-09](README.md#q-09): Define cross-device publication ownership before sync. Syncing a draft or an uncertain intent must not automatically send it. Manual concurrent submission of the same shared draft needs a concrete conflict policy; local serialization does not solve that race. - Draft conflict handling must preserve both authored texts. Publication receipts must identify which draft revision was sent so later edits are not falsely marked published. +- Q-13/Q-15 keep feedback and per-file progress inside the owning PR workspace. A stack connection does not batch publication or advance another PR's progress. ## Refinement trigger diff --git a/Plans/2026-11-14-mobius/06-icloud-resume-and-release.md b/Plans/2026-11-14-mobius/06-icloud-resume-and-release.md index 1770efccb..3e585ae9a 100644 --- a/Plans/2026-11-14-mobius/06-icloud-resume-and-release.md +++ b/Plans/2026-11-14-mobius/06-icloud-resume-and-release.md @@ -6,7 +6,7 @@ ## Intended outcome -Start reviews on one device and continue them on another using private iCloud under the same Apple ID. Workspace documents, personal checkpoints/receipts, and drafts converge without losing user work or taking over another device's window focus. Each device authenticates its own GitHub account before retrieving protected source. +Start reviews on one device and continue them on another using private iCloud under the same Apple ID. Independent PR workspaces, documents, last review files, per-file reviewed versions, and drafts converge without losing user work or taking over another device's window focus. Reopening a review starts at the top of its last file. Each device authenticates its own GitHub account before retrieving protected source. This deliverable is required for the first release. Demonstrate an iPhone-to-iPad-to-Mac handoff, concurrent edits, offline work, reconnect, account transitions, and a complete GitHub review flow. A local-only app or simulator-only sync demonstration does not satisfy it. @@ -25,7 +25,7 @@ X-05 and X-06 apply. No custom workspace-sync backend, different-Apple-ID contin The candidate transport is `CKSyncEngine` over a dedicated private CloudKit database/container. The app owns local atomic persistence, pending record changes, serialized engine state, conflict policy, and account transitions. Keep the Core store's accepted-state interface; measure whether record projection requires a different internal persistence implementation. -Use stable per-entity records instead of a single last-writer-wins workspace blob. Design tombstones and deterministic merge rules for document membership/order, checkpoints, receipts, and draft revisions. Preserve competing draft texts. Explicitly distinguish opening a new document from an old offline device replaying a deleted document. Wall-clock order alone must not discard user-authored content. +Use stable per-entity records instead of a single last-writer-wins workspace blob. Design tombstones and deterministic merge rules for document membership/order, last review file, per-file review evidence, and draft revisions. Preserve competing draft texts. Explicitly distinguish opening a new document from an old offline device replaying a deleted document. Wall-clock order alone must not discard user-authored content. ```mermaid flowchart LR @@ -45,7 +45,7 @@ protocol WorkspaceSynchronizing: Sendable { // It does not publish GitHub feedback or copy authentication credentials. ``` -Native window bounds, selected panes, focus, and local scene IDs remain device-local. Restored workspace content must fit the receiving device. Preserve semantic reading anchors; do not promise identical pixel offsets. Remote work becomes available without unexpectedly opening windows or closing a focused local document during an edit. +Native window bounds, selected panes, focus, and local scene IDs remain device-local. Restored workspace content must fit the receiving device. Preserve the semantic last-file identity and open a resumed review at its top; exact scroll offsets are not part of the continuity contract. Remote work becomes available without unexpectedly opening windows or closing a focused local document during an edit. Account changes must stop the prior sync scope and isolate its files/records before any new scope starts. iCloud sign-out must not silently upload one account's drafts into another account. GitHub sign-out/revocation must prevent protected fetches and display, with an explicit policy for retained private drafts and caches. Preserve recoverable user work while resolving access; never infer fresh access from stale credentials. @@ -65,9 +65,9 @@ Account changes must stop the prior sync scope and isolate its files/records bef The executable refinement must preserve this sequence: -1. Open two PRs and repository context on iPhone; explicitly mark part of one review and save feedback text. -2. Resume on iPad; open a second window and follow a search result without losing either review. -3. Change the test PR; verify the since-checkpoint comparison and unchanged-file receipts on Mac, including menu/keyboard navigation. +1. Open two independent PR workspaces and their repository context on iPhone; mark a file reviewed in one PR, leave another unreviewed, and save feedback text. +2. Resume on iPad at the top of the last review file; open a second window and follow a search result without losing either PR's context. +3. Change the test PR; on Mac, verify new edits against each reviewed file's baseline, the full PR diff for an unreviewed file, and full-diff access for either. Check menu/keyboard navigation and that the second PR's progress is unaffected. 4. Make competing offline draft edits on two devices; reconnect and recover both texts. Exercise document close/reopen and account switching. 5. Submit feedback once through an explicit user action; interrupt the response and prove recovery does not blindly replay the write from either device. 6. Verify the same workflow with accessibility text sizes and VoiceOver, and inspect the platform-specific CI/runtime evidence. @@ -80,6 +80,7 @@ This is a planned acceptance flow, not a measured result. Refine exact assertion | --- | --- | --- | | 2026-11-14 | Private iCloud continuity is in the first release and uses the same Apple ID. | Q-05/Q-07. | | 2026-11-14 | Sync semantic workspace metadata/drafts, retaining native presentation and source caches locally. | Overview design proposal. | +| 2026-11-14 | Sync independent PR workspaces, last-file identity, and per-file reviewed versions; resume at the file top. | Q-13–Q-15. | ## Resume point diff --git a/Plans/2026-11-14-mobius/README.md b/Plans/2026-11-14-mobius/README.md index 3179d3774..fb71403b2 100644 --- a/Plans/2026-11-14-mobius/README.md +++ b/Plans/2026-11-14-mobius/README.md @@ -3,16 +3,18 @@ ## Planning checkpoint - Updated: 2026-11-14; repository baseline `b629d56ac44a3f2a5ea59c3d6ae9cd5401f37674`. -- Operation: Create a plan. Product implementation is not requested. -- Requested scope and source: The user's 2026-11-14 chat request and answers to [Q-01–Q-07](#questions-and-resolutions). -- Stage: Handoff; plan published for review. -- Completed: Product discovery, repository inspection, primary-source API research, Linear duplicate search, and review of all eight plan files. Published [PR #497](https://github.com/kyleve/Stuff/pull/497); [STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app) is In Review and links the plan and PR. -- Pending: PR review and merge. Later technical decisions remain in Q-08–Q-12 at their recorded refinement gates. Product execution has not been requested. -- Next action: Await a request to execute 01 or refine a named outline; inspect current PR feedback and repository state when resuming. The first execution resume point is [01](01-review-state-foundation.md#resume-point). +- Operation: Revise the plan following product discovery. Product implementation is not requested. +- Requested scope and source: The user's 2026-11-14 request, Q-01–Q-07 answers, and Q-13–Q-18 follow-ups on review continuity and prototype priority; see [question history](#questions-and-resolutions). +- Stage: Handoff; revised plan for review. +- Completed: Initial research and publication in [PR #497](https://github.com/kyleve/Stuff/pull/497); integrated one workspace per PR, file-top resumption, per-file remaining work, and a lightweight mockup across all three layouts. [STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app) tracks plan delivery. +- Pending: PR review and merge. Q-08–Q-12 remain at their technical refinement gates. The mockup must supply interaction evidence before the durable model becomes executable. +- Next action: Await a request to execute [01a](01a-workspace-prototype.md#resume-point), then inspect current feedback and repository state. Choosing the first deliverable does not itself request its implementation. ## Outcome and scope -Mobius keeps code review open as ongoing work. A reviewer can leave several pull requests, source files, and searches open, explore without losing a review, and resume on another device. Personal progress records which version was reviewed, so returning after a push reveals what needs another pass. Nobody needs a temporary “got to here” GitHub comment. +Mobius keeps code review open as ongoing work. Each PR has its own workspace containing its review, reference files, and searches. Reviewers switch between those independent workspaces and resume at the top of the file they left. A remaining-work view shows new edits in previously reviewed files and the full PR diff for unreviewed files; the full PR diff stays available for either. Each reviewed file has its own last-reviewed version. Nobody needs a temporary “got to here” GitHub comment. + +PRs remain separate even when GitHub connects them in a stack. If a stack connection is shown, it is an informational link; it does not combine progress, drafts, comparison baselines, or submission actions. Stack discovery is not an additional first-release integration requirement. The first release targets **iPhone, iPad, and Mac Catalyst**, including Mac windows, menus, and shortcuts. It supports GitHub PR diffs, comments, approvals, and requests for changes. Private iCloud sync carries workspaces and personal progress between devices using the same Apple ID. These are first-release requirements even though implementation is divided into deliverables. @@ -23,7 +25,7 @@ Embedding the reviewer inside an owning app, with a possible live execution surf | ID | Story | | --- | --- | | US-01 | Keep several reviews and reference documents open, so investigating one question does not discard another task. | -| US-02 | Resume my place, drafts, and explicit progress without reconstructing my last session. | +| US-02 | Resume my review file from its top, with drafts and progress preserved, without reconstructing my last session. | | US-03 | Distinguish unchanged reviewed work from new PR changes, so I can concentrate on what needs another pass. | | US-04 | Browse and search repository context without leaving the review workspace. | | US-05 | Comment, approve, or request changes against the code I inspected. | @@ -38,9 +40,9 @@ R-01–R-07 and R-12 derive from the user's product choices. R-08–R-11 support | ID | Required behavior or constraint | Story | Implementing plan | | --- | --- | --- | --- | | R-01 | Run on iPhone, iPad, and Mac Catalyst, with Mac windows, menus, and keyboard commands. | US-06 | [02](02-application-workspace.md), [06](06-icloud-resume-and-release.md) | -| R-02 | Keep multiple PRs, files, and searches open as workspace documents. Opening context preserves the existing review. | US-01, US-04 | [01](01-review-state-foundation.md), [02](02-application-workspace.md), [04](04-repository-exploration.md) | -| R-03 | Persist documents, reading positions, personal review receipts, and drafts across relaunch. Reading position, explicit progress, and a submitted GitHub review are separate facts. | US-02 | [01](01-review-state-foundation.md), [02](02-application-workspace.md), [05](05-review-feedback.md) | -| R-04 | Identify changes since an explicit personal checkpoint using immutable revisions. Distinguish current PR changes from changes since that checkpoint. Preserve unaffected progress without silently advancing the checkpoint. | US-03 | [01](01-review-state-foundation.md), [03](03-github-and-revision-comparison.md) | +| R-02 | Keep one independent workspace per PR, with its reference files and searches. Switching PRs preserves each workspace. Stack connections, if shown, are informational. | US-01, US-04 | [01a](01a-workspace-prototype.md) explores interaction; [01](01-review-state-foundation.md), [02](02-application-workspace.md), [04](04-repository-exploration.md) deliver it | +| R-03 | Persist workspace documents, the last review file, per-file reviewed versions, and drafts across relaunch. Resume the file from its top; precise in-file position and reviewed-range tracking are not required. Personal progress and submitted GitHub feedback remain separate facts. | US-02 | [01a](01a-workspace-prototype.md) explores interaction; [01](01-review-state-foundation.md), [02](02-application-workspace.md), [05](05-review-feedback.md) deliver it | +| R-04 | Within one PR, remaining work combines new edits since each reviewed file's last-reviewed version with the full PR diff for unreviewed files. Let either file open its full PR diff. An explicit file-review action advances that file's baseline; navigation and refresh do not. | US-03 | [01a](01a-workspace-prototype.md) explores interaction; [01](01-review-state-foundation.md), [03](03-github-and-revision-comparison.md) deliver it | | R-05 | Browse files and search paths and text at an identified repository revision within Mobius. Open results without replacing the review and show search coverage. | US-04 | [04](04-repository-exploration.md) | | R-06 | Read review discussion; compose and explicitly submit comments, approvals, and requests for changes with revision validation and recoverable drafts. | US-05 | [03](03-github-and-revision-comparison.md), [05](05-review-feedback.md) | | R-07 | Resume documents, progress, and draft work through private iCloud sync on the same Apple ID. Keep device window placement local and expose sync state. | US-02, US-06 | [01](01-review-state-foundation.md) supplies identities; [06](06-icloud-resume-and-release.md) delivers sync | @@ -89,13 +91,22 @@ Consulted 2026-11-14. External sources establish documented capabilities, not li ## Design overview +### Discovery scenario + +PR 42 and PR 43 each have their own workspace. Opening a reference file or search from PR 42 retains it there when switching to PR 43. Returning to PR 42 restores its last review file at the top. A stack link between those PRs does not merge their work. + +Within PR 42, mark `Parser.swift` reviewed at version 1 and leave `Store.swift` unreviewed. A simulated push supplies version 2. Remaining work shows the version-1-to-version-2 edits for `Parser.swift` and the full current PR diff for `Store.swift`. Either can open its full PR diff. Marking `Parser.swift` reviewed again advances only its baseline. These are files within one PR, not three separate reviews. + +The first deliverable is a lightweight interactive mockup with phone, tablet, and desktop layouts. It will explore navigation, labels, and layout using synthetic PRs before native implementation or durable storage. See [01a](01a-workspace-prototype.md). A mockup result will not establish native platform, persistence, provider, or sync feasibility. + ### Product concepts -- **Workspace:** a durable collection of review, source, and search documents. Opening another task does not replace the current review. +- **Workspace:** one PR's review, source, and search documents. Another PR has a separate workspace, including when the PRs belong to a stack. - **Document:** a typed route with account/repository identity and an explicit revision policy. Pinned source tabs must not silently follow moving branches. - **Window presentation:** device-local selection, panes, focus, and scene identity. Synced work becomes available to resume without stealing focus or automatically spawning windows. +- **Resume file:** the last review file within that PR workspace. Reopening starts at its top; an exact scroll position is not durable review progress. - **Review receipt:** explicit evidence for a file comparison, including both sides, paths, modes, and content identities. A new head alone neither invalidates every receipt nor proves any one remains current. -- **Checkpoint:** a deliberately captured PR revision and comparison context. “Changes since checkpoint” differs from “current PR changes.” Refresh does not advance the checkpoint. +- **Per-file baseline:** the version last marked reviewed for that file. Remaining work compares against it; a file with no baseline shows its full PR diff. A separate manually captured PR-wide checkpoint is not required by the selected workflow. - **Draft:** user text with its original revision/anchor. Draft, publishing, uncertain outcome, and confirmed publication remain distinct states. ### Proposed ownership @@ -104,7 +115,7 @@ Start with `MobiusCore`, `MobiusUI`, and a thin `Mobius` app host. These are pro Core owns typed values, revision/progress policy, local storage, provider protocols, GitHub transport, and sync policy in focused source directories. UI owns observable presentation, Broadway styling, code-rendering adapters, and navigation. The process composition root creates one runtime and injects it into each scene. Views do not open stores or create shared services. -The initial store is a serial actor with an atomically replaced, versioned metadata file. Source blobs and indexes occupy an independently evictable cache. Stable entity IDs support later CloudKit record projection. Revisit storage technology if measured scale requires it; preserve accepted-data semantics and the store interface. +The earlier candidate store is a serial actor with an atomically replaced, versioned metadata file, separate from evictable source blobs and indexes. Its concrete model and technology remain provisional until the mockup is evaluated. Stable identities, honest errors, and preservation of accepted user work remain constraints for later refinement. ```mermaid flowchart LR @@ -149,26 +160,29 @@ actor WorkspaceStore { } ``` -[01](01-review-state-foundation.md) defines the initial value/persistence contracts. Network, sync, and renderer interfaces remain provisional until their outlines are refined. Authentication UI and native scene adapters are omitted. +[01](01-review-state-foundation.md) will define production value/persistence contracts after the mockup. This ownership sketch is a candidate native design; the mockup does not implement these services. Network, sync, and renderer interfaces remain provisional until their outlines are refined. Authentication UI and native scene adapters are omitted. ## Execution order | Order | Plan | Deliverable | | --- | --- | --- | -| 1 | [Review-state foundation](01-review-state-foundation.md) | Typed workspace/progress state, restart-safe local persistence, and deterministic guards. | -| 2 | [Application workspace](02-application-workspace.md) | Fixture-backed app on all three destinations with tabs, scenes, restoration, and accessible navigation. | -| 3 | [GitHub and revision comparison](03-github-and-revision-comparison.md) | Authenticated PR reading and trustworthy revision-aware diffs/progress. | -| 4 | [Repository exploration](04-repository-exploration.md) | Revision-bound browsing and path/text search alongside reviews. | -| 5 | [Review feedback](05-review-feedback.md) | Comments and reviews with retained drafts and uncertain-outcome recovery. | -| 6 | [iCloud resume and release](06-icloud-resume-and-release.md) | Cross-device continuity and verified first-release acceptance. | -| 7 | [Embedded review experiment](07-embedded-review-experiment.md) | Evidence and a recommendation for embedded review with bounded live context. | +| 1 | [01a — Workspace prototype](01a-workspace-prototype.md) | Lightweight interactive mockup of separate PR workspaces and remaining work across phone, tablet, and desktop layouts. | +| 2 | [01 — Review-state foundation](01-review-state-foundation.md) | Durable workspace/progress state informed by prototype evidence. | +| 3 | [02 — Application workspace](02-application-workspace.md) | Native app with tabs, scenes, file-top resumption, and accessible navigation. | +| 4 | [03 — GitHub and revision comparison](03-github-and-revision-comparison.md) | Authenticated PR reading and per-file remaining-work comparisons. | +| 5 | [04 — Repository exploration](04-repository-exploration.md) | Revision-bound browsing and path/text search alongside each review. | +| 6 | [05 — Review feedback](05-review-feedback.md) | Comments and reviews with retained drafts and uncertain-outcome recovery. | +| 7 | [06 — iCloud resume and release](06-icloud-resume-and-release.md) | Cross-device continuity and verified first-release acceptance. | +| 8 | [07 — Embedded review experiment](07-embedded-review-experiment.md) | Evidence and a recommendation for embedded review with bounded live context. | + +01a is an inserted prerequisite; the earlier reviewed filenames remain stable. This table defines execution order. ## Planning horizon -- Detail now: [01](01-review-state-foundation.md). Synthetic immutable inputs suffice; no GitHub registration, CloudKit container, or renderer choice is required. -- Later selected work: 02–07 remain outlines with refinement triggers, not executable plans. -- Next horizon review: Use 01's actual model and persistence evidence to refine 02 and 03. Resolve Q-08/Q-10 then. Resolve the sync merge policy before 06 becomes executable; 01 preserves the IDs and revisions it needs. -- First-release gate: **01–06 together**. A local foundation or fixture app does not waive sync or GitHub feedback. +- Detail now: [01a](01a-workspace-prototype.md), selected in Q-16–Q-18 to explore all three layouts through a lightweight interactive mockup. +- Later selected work: 01–07 are outlines. The earlier claim that 01 was ready is superseded; its model must follow prototype learning. +- Next horizon review: Record prototype observations and the user's feedback, integrate changed decisions, then refine 01 and reconsider 02/03. Technical decisions Q-08–Q-12 retain their recorded gates. +- First-release gate: **01–06 together**, preceded by prototype learning. The mockup does not deliver or waive native platform, GitHub feedback, persistence, or sync requirements. ## Shared decisions @@ -179,7 +193,10 @@ actor WorkspaceStore { | 2026-11-14 | GitHub diffs, comments, approvals, and requests for changes in the first release. | Q-02. | | 2026-11-14 | Private iCloud continuity on the same Apple ID is a first-release requirement. | Q-05, Q-07. | | 2026-11-14 | Embedding/live context receives a later experiment. | Q-06. | -| 2026-11-14 | Proposed: personal receipts and explicit checkpoints remain separate from submitted GitHub reviews. | R-03/R-04; immutable revision evidence. | +| 2026-11-14 | One workspace per PR; stack connections are informational. | Q-13 and Q-15 clarification. | +| 2026-11-14 | Resume at the top of the last review file. | Q-14 follow-up. | +| 2026-11-14 | Remaining work uses each reviewed file's last-reviewed version and includes the full PR diff for unreviewed files. Full PR diffs remain available. | Q-15 follow-up; replaces the earlier PR-wide explicit-checkpoint proposal. | +| 2026-11-14 | Start with a lightweight interactive mockup exploring phone, tablet, and desktop together. | Q-16–Q-18; replaces foundation-first sequencing. | | 2026-11-14 | Proposed: sync semantic workspace data and drafts; keep native geometry/focus and full code caches local. | R-07/R-09. | | 2026-11-14 | Proposed: atomic metadata storage, not a bounded journal as the only copy of user work. | JournalKit contract. | @@ -199,8 +216,14 @@ actor WorkspaceStore { | [Q-10](#q-10) | deferred | Renderer and measured large-workspace budgets? | 02–04 | Blocks UI/diff readiness; benchmark fixtures during refinement. | | [Q-11](#q-11) | deferred | Catalyst validation and release distribution/signing? | 02, 06 | Specify compile/runtime validation in 02; resolve distribution in 06. | | [Q-12](#q-12) | deferred | What can an embedded reviewer prove about a build and PR? | 07 | Blocks a product promise; choose a synthetic host after standalone delivery. | +| [Q-13](#q-13) | closed | How is concurrent review work grouped? | R-02, 01a, 01, 02, 04 | One independent workspace per PR. | +| [Q-14](#q-14) | closed | What should resuming a review restore? | R-03, 01a, 01, 02, 06 | Return to the review file and start at its top. | +| [Q-15](#q-15) | closed | How should new edits and unfinished work appear within one PR? | R-04, 01a, 01, 03, 05, 06 | Per-file last-reviewed versions; full PR diffs for unreviewed files and as an available alternate view. | +| [Q-16](#q-16) | closed | What should the first deliverable validate? | Execution order, 01a, 01, 02 | Interactive prototype with sample PRs before durable state work. | +| [Q-17](#q-17) | closed | Which layouts should the prototype explore? | 01a | Phone, tablet, and desktop together. | +| [Q-18](#q-18) | closed | What form should the prototype take? | 01a | Lightweight interactive mockup for quick iteration. | -All user answers below came from this chat on 2026-11-14. Each was integrated and reviewed for consistency on that date. No user question remains unanswered for the current horizon. +User answers came from this chat on 2026-11-14. Q-13–Q-18 refine the original answers without reopening the selected platforms, provider, or iCloud scope. The current horizon is prototype evaluation; detailed navigation and layout are hypotheses to explore through it. ### Q-01 @@ -279,20 +302,57 @@ All user answers below came from this chat on 2026-11-14. Each was integrated an - Deferral: Select the host/method after reusable UI/services exist. Opening a PR does not make its code executable in the running binary. - History: Opened and deferred on 2026-11-14. +### Q-13 + +- Answer/source: The user selected a workspace per PR. The Q-15 clarification also establishes that separate PRs are separate reviews, with a stack connection largely an informational note. +- Integration: R-02, product concepts, 01a, and the workspace ownership and navigation in 01/02/04/06. +- History: Asked, answered, integrated, and closed after checking that documents and progress do not merge across PRs. This does not require implementing GitHub stack discovery. + +### Q-14 + +- Answer/source: Initially uncertain between a point in a file and the file reached in order. The follow-up answer was to start from the top of the file. +- Integration: R-03, resume-file concept, 01a/01/02/06. Precise in-file restoration and reviewed-range tracking are not first-release requirements. +- History: Kept open after the tentative answer; closed after the file-top preference was integrated. Reading or returning to a file does not itself mark it reviewed. + +### Q-15 + +- Answer/source: Initially uncertain and described as personal; suggested a diff since the last review and/or unreviewed files. An ambiguous A/B/C example prompted clarification that PRs must stay independent. A subsequent example explicitly used two files within one PR; the user accepted showing new edits in a reviewed file and the full PR diff in an unreviewed file, using each file's last-marked-reviewed version and keeping full PR diffs accessible. +- Integration: R-04, per-file baseline concept, 01a/01/03/05/06. A manually captured PR-wide checkpoint is no longer the selected model. +- History: Kept open through the tentative answer and scenario clarification; closed after the per-file proposal was accepted and integrated. No configurable collection of alternative baseline modes was requested. + +### Q-16 + +- Answer/source: Interactive prototype with sample PRs as the first deliverable. +- Integration: Inserted 01a before 01; returned 01 to outline and made prototype evidence its refinement prerequisite. +- History: Asked, answered, integrated, and closed after dependency review. This selects the plan's first deliverable; implementation still requires an execution request. + +### Q-17 + +- Answer/source: Explore all three layouts together. +- Integration: 01a covers phone, tablet, and desktop viewports with the same synthetic workflow. +- History: Asked, answered, integrated, and closed. Viewport demonstrations do not establish native iPhone/iPad/Catalyst behavior. + +### Q-18 + +- Answer/source: Lightweight interactive mockup for quick iteration. +- Integration: 01a produces a self-contained browser artifact; native UIKit targets, persistent stores, authentication, and CloudKit remain later work. +- History: Asked, answered, integrated, and closed after checking prototype scope and acceptance. Browser technology is an implementation choice for the mockup, not the production app architecture. + ## Plan review -- Reviewed: 2026-11-14 against `b629d56ac44a3f2a5ea59c3d6ae9cd5401f37674`, covering all eight files, requirement/exclusion traceability, dependency order, and executable detail for 01. User-answer integration was checked against the complete series. -- Findings and disposition: Aligned the overview's store signature with 01's version-checked, non-reentrant save; corrected 02's claim that a runtime already comes from 01; made Core paths repository-relative; added cross-account/PR receipt tests and post-save/pre-acknowledgment recovery; assigned app attribution to 02. Brought Q-09's submission-ownership decision forward to 05 and added its definitive rejection transition. Later technical decisions remain explicitly deferred to their owners. -- Readiness: 01 is ready for a subsequent execution request. No blocking finding remains in that horizon. 02–07 remain outlines and require refinement before execution. -- Verification: All local Markdown links and anchors resolve; fences are balanced; the dependency graph is acyclic; `git diff --cached --check` passes. Requirements R-01–R-12 have implementing owners. These checks validate the plan, not the proposed app. +- Initial review: 2026-11-14 against `b629d56ac44a3f2a5ea59c3d6ae9cd5401f37674`, covering the original eight files. Its readiness finding for 01 is superseded by Q-13–Q-18 and prototype-first sequencing. +- Initial findings and disposition (historical): Aligned the overview's store signature with 01's then-proposed version-checked save; corrected 02's runtime ownership claim; added receipt-isolation and persistence-recovery scenarios; assigned app attribution to 02. Brought Q-09's submission-ownership decision forward to 05 and added its definitive rejection transition. No implementation tests ran; 01's detailed design is now deferred until prototype evaluation. +- Revision review: Integrated Q-13–Q-18 across the nine-file series, including workspace isolation, file-top resumption, per-file baselines, and prototype-first dependencies. Reviewed 01a for executable experiment detail; 01–07 remain outlines. +- Readiness: 01a is ready for a subsequent execution request. Prototype interaction findings and user feedback are prerequisites to refining 01. A negative prototype result can lead to a revised design; it does not establish production feasibility. +- Verification: All 118 local Markdown links and anchors resolve across nine files; fences are balanced; the eight-plan dependency graph is acyclic; all 12 requirements have implementing owners; `git diff --check` passes. These checks validate the plan, not the proposed app. - Validation limits: No prototype, device test, product API write, or sync experiment has run. Swift is pseudocode. Mermaid was inspected as source; no local renderer was found. `./test` and `./swiftformat --lint` were skipped because only planning Markdown changed. ## Review and delivery - Plan review: [PR #497](https://github.com/kyleve/Stuff/pull/497), ready for review. [STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app) remains In Review until merge and acceptance verification. - Implementation: Not requested or started. -- Review focus: Checkpoint semantics; shared work versus local windows; incomplete coverage and lost history; sync as a release gate. +- Review focus: Independent PR workspaces; per-file remaining work and full-diff access; file-top resumption; prototype learning before the durable model; sync as a release gate. ## Outcome -The reviewed series is published. Plan 01 is ready; 02–07 remain outlines. Execution awaits a new request. +The revised series starts with the lightweight, three-layout mockup in 01a. Plans 01–07 remain outlines informed by later evidence. Execution awaits a new request. From 11175ae1ad70a7742d5a38701b03408a0a891371 Mon Sep 17 00:00:00 2001 From: Kyle Van Essen Date: Sat, 14 Nov 2026 19:16:03 -0500 Subject: [PATCH 04/12] docs(Mobius): record background prototype execution Record the user-authorized 01a execution branch and isolated worktree while keeping production-plan discussion in the parent checkout. Reviewed the checkpoint and passed git diff --check; Markdown-only change, so app tests and SwiftFormat were not run. --- Plans/2026-11-14-mobius/README.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/Plans/2026-11-14-mobius/README.md b/Plans/2026-11-14-mobius/README.md index fb71403b2..5482ab805 100644 --- a/Plans/2026-11-14-mobius/README.md +++ b/Plans/2026-11-14-mobius/README.md @@ -3,12 +3,13 @@ ## Planning checkpoint - Updated: 2026-11-14; repository baseline `b629d56ac44a3f2a5ea59c3d6ae9cd5401f37674`. -- Operation: Revise the plan following product discovery. Product implementation is not requested. +- Operation: Execute 01a in a background agent while continuing production-plan discussion here. Native implementation is not requested. - Requested scope and source: The user's 2026-11-14 request, Q-01–Q-07 answers, and Q-13–Q-18 follow-ups on review continuity and prototype priority; see [question history](#questions-and-resolutions). -- Stage: Handoff; revised plan for review. +- Stage: Prototype execution in an isolated worktree; production planning continues separately. - Completed: Initial research and publication in [PR #497](https://github.com/kyleve/Stuff/pull/497); integrated one workspace per PR, file-top resumption, per-file remaining work, and a lightweight mockup across all three layouts. [STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app) tracks plan delivery. -- Pending: PR review and merge. Q-08–Q-12 remain at their technical refinement gates. The mockup must supply interaction evidence before the durable model becomes executable. -- Next action: Await a request to execute [01a](01a-workspace-prototype.md#resume-point), then inspect current feedback and repository state. Choosing the first deliverable does not itself request its implementation. +- Pending: Prototype implementation, browser validation, and user feedback; PR review and merge. Q-08–Q-12 remain at their technical refinement gates. The mockup must supply interaction evidence before the durable model becomes executable. +- Execution authorization: The user subsequently requested background execution of 01a on 2026-11-14. The prototype runs on `codex/mobius-prototype` in `/Users/kve/.codex/worktrees/mobius-prototype/Stuff`, based on `4e70677e7`. Its branch owns the artifact and 01a execution evidence; this branch owns the overview and production-plan discussion. +- Next action: The background agent implements and validates [01a](01a-workspace-prototype.md#resume-point), then returns the artifact for user evaluation. Continue production discovery here without assuming the prototype has already validated its hypotheses. ## Outcome and scope @@ -56,7 +57,7 @@ R-01–R-07 and R-12 derive from the user's product choices. R-08–R-11 support | ID | Category | Exclusion | Reason | | --- | --- | --- | --- | -| X-01 | Explicitly avoided | Product implementation during this planning operation. | Only planning is authorized. | +| X-01 | Explicitly avoided | Native product implementation during the current prototype operation. | The execution request covers the lightweight 01a mockup. | | X-02 | Not required | Other Git hosting providers, a general code editor, Git push/merge tools, and automatic AI reviews. | The selected workflow is GitHub review. | | X-03 | Explicitly avoided | Marking files reviewed merely because they were opened; using scroll offsets as review receipts; posting personal progress as GitHub comments. | These recreate the continuity problem. | | X-04 | Explicitly avoided | Executing downloaded PR code, arbitrary native hot loading, or promising a general build service. | Q-06 selected a later investigation. | @@ -350,9 +351,9 @@ User answers came from this chat on 2026-11-14. Q-13–Q-18 refine the original ## Review and delivery - Plan review: [PR #497](https://github.com/kyleve/Stuff/pull/497), ready for review. [STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app) remains In Review until merge and acceptance verification. -- Implementation: Not requested or started. +- Implementation: 01a is authorized and running in an isolated background worktree. Native plans 01–07 have not started. - Review focus: Independent PR workspaces; per-file remaining work and full-diff access; file-top resumption; prototype learning before the durable model; sync as a release gate. ## Outcome -The revised series starts with the lightweight, three-layout mockup in 01a. Plans 01–07 remain outlines informed by later evidence. Execution awaits a new request. +The revised series starts with the lightweight, three-layout mockup in 01a, now authorized for background execution. Plans 01–07 remain outlines informed by later evidence and production discussion. From 043feed20a36f51c95008d26faa1efae31104f00 Mon Sep 17 00:00:00 2001 From: Kyle Van Essen Date: Sat, 14 Nov 2026 20:21:02 -0500 Subject: [PATCH 05/12] Clarify logical Mobius workspaces and child window restoration --- .../01-review-state-foundation.md | 23 ++-- .../02-application-workspace.md | 30 +++--- .../03-github-and-revision-comparison.md | 2 + .../04-repository-exploration.md | 13 +-- Plans/2026-11-14-mobius/05-review-feedback.md | 2 + .../06-icloud-resume-and-release.md | 13 +-- .../07-embedded-review-experiment.md | 3 + Plans/2026-11-14-mobius/README.md | 100 ++++++++++++------ 8 files changed, 116 insertions(+), 70 deletions(-) diff --git a/Plans/2026-11-14-mobius/01-review-state-foundation.md b/Plans/2026-11-14-mobius/01-review-state-foundation.md index 34e12c4a7..a396d2961 100644 --- a/Plans/2026-11-14-mobius/01-review-state-foundation.md +++ b/Plans/2026-11-14-mobius/01-review-state-foundation.md @@ -6,7 +6,7 @@ ## Intended outcome -A `MobiusCore` library preserves independent PR workspaces, the last review file, per-file reviewed versions, and drafts across relaunch. Returning to a review starts at the top of its last file. Remaining-work policy follows Q-15: new edits since each reviewed file's last-reviewed version, and the full PR diff for an unreviewed file, with full PR diffs available for either. +A `MobiusCore` library preserves independent logical PR workspaces, their child-view identities/navigation, per-file reviewed versions, and drafts across relaunch. Returning restores a workspace's arrangement and last-focused child. Resuming a review child starts at the top of its selected file. Remaining-work policy follows Q-15: new edits since each reviewed file's last-reviewed version, and the full PR diff for an unreviewed file, with full PR diffs available for either. This is production groundwork after prototype learning. It does not itself deliver a native app, live GitHub integration, or iCloud sync. The earlier ready assessment and detailed implementation sequence are superseded by Q-13–Q-18; the prototype now comes first. @@ -14,7 +14,7 @@ This is production groundwork after prototype learning. It does not itself deliv | Story | Requirement | Intended contribution | | --- | --- | --- | -| US-01, US-02 | R-02, R-03 | One workspace per PR; independent documents, last-file selection, reviewed versions, drafts, and local restoration. | +| US-01, US-02 | R-02, R-03 | One workspace per PR; identified child views with independent navigation; workspace review progress/drafts and local arrangement/focus restoration. | | US-03 | R-04 | Immutable per-file review evidence and pure remaining-work evaluation. | | US-06 | R-07 | Stable identities and versioned data that later sync can address. | | US-07 | R-08, R-09 | Honest failures, isolation by account/repository/PR, and preservation of accepted data. | @@ -26,9 +26,9 @@ This is production groundwork after prototype learning. It does not itself deliv Read the root and Plans contracts and the running-tests skill during refinement. Proposed paths remain `Mobius/MobiusCore/{Sources,Tests,README.md,AGENTS.md}`, plus the product-group docs. Core initially uses Foundation and must not import UIKit, SwiftUI, Where modules, or a UI facade. Register its library in `Package.swift`, its hosted tests through `Project.swift`, and relevant Bumper boundaries and mutation tests when implemented. -Each workspace belongs to one typed account/repository/PR target. Workspace documents can include that review, reference files, and searches. Two PRs with the same file path still have independent progress. A stack connection does not combine their stores, baselines, drafts, or feedback actions. +Each workspace belongs to one typed account/repository/PR target, independent of its outer tab/window presentation. It owns identified child views for review, reference files, and research. View kind or document route is not a unique child identity: two children can inspect the same file with independent navigation. Their review receipts belong to the PR workspace. Two PRs with the same file path still have independent progress. A stack connection does not combine their stores, baselines, drafts, or feedback actions. -A resume value identifies the last review file; it does not persist a reviewed line range or require exact scroll restoration. Per-file review evidence records the immutable comparison/version accepted by the explicit file-review action. A new push may make that file need review again, but must retain the earlier evidence needed to calculate its new edits. Unreviewed files have no reviewed baseline and show the full PR diff. +A review child's resume value identifies its selected file; it does not persist a reviewed line range or require exact scroll restoration. Workspace restoration retains child arrangement and last-focused identity, so returning need not focus a review. Keep device presentation separate from semantic workspace contents; refine persistence and sync boundaries before fixing the schema. Per-file review evidence records the immutable comparison/version accepted by the explicit file-review action. A new push may make that file need review again, but must retain the earlier evidence needed to calculate its new edits. Unreviewed files have no reviewed baseline and show the full PR diff. The previous candidate was a serial store actor with version-checked mutations and atomic metadata replacement, separate from evictable source blobs/indexes. Retain it as an option to evaluate after the prototype; do not implement its schema just because it was previously specified. Production identity, errors, migrations, concurrency, and recovery need executable refinement. @@ -38,9 +38,11 @@ flowchart LR Intent["Explicit file-review action"] --> Evidence["Proposed per-file reviewed version"] Evidence --> Policy["Proposed remaining-work policy"] Revisions["Immutable current comparison and coverage"] --> Policy + Model --> Children["Identified children with independent navigation"] Model --> Store["Candidate durable store"] + Children --> Store Evidence --> Store - Store --> Resume["Last review file; reopen at top"] + Store --> Resume["Arrangement and focused child; review file at top"] Policy --> Result["New edits / full unreviewed diff / unavailable"] ``` @@ -62,7 +64,9 @@ struct FileReviewReceipt: Codable, Sendable { let reviewedComparison: FileComparisonIdentity let reviewedRevision: ReviewRevision } -// Workspace owns one ReviewTarget, its documents, resume file, and receipts. +// Workspace owns one ReviewTarget, identified children, drafts, and receipts. +// Each review child retains its own ReviewResumeFile. +// Presentation references workspace/child IDs; native scene IDs are separate. // File identity across renames and comparison context requires refinement. ``` @@ -70,7 +74,7 @@ All named domain types are proposed. Receipt/content identity must distinguish b ## Questions and learning needed -- [01a](01a-workspace-prototype.md) must supply observed navigation and remaining-work behavior plus the user's feedback before the production model is fixed. If feedback changes Q-13–Q-15, revise the affected requirements first. +- [01a](01a-workspace-prototype.md) must supply observed workspace/child navigation, restoration, and remaining-work behavior plus the user's feedback before the production model is fixed. Its first artifact exposed a flattened workspace model; Q-19–Q-21 require another iteration. Integrate further feedback before fixing identities or schema. - Choose the persistence representation, mutation/version contract, migration behavior, and failure recovery from the evaluated model. The earlier atomic-file proposal remains an option. - [Q-09](README.md#q-09) owns distributed merge/account policy. Preserve stable identities and revision evidence; local mutation versions must not be presented as distributed causal clocks. - Keep original errors and accepted user work on failure. Missing storage may initialize an empty store; corrupt or unsupported storage must not be silently replaced with one. @@ -78,10 +82,10 @@ All named domain types are proposed. Receipt/content identity must distinguish b ## Refinement trigger and intended verification - Trigger: 01a's artifact and evaluation are complete, and resulting product decisions are integrated. -- Evidence needed: Accepted workflow, concrete workspace/document/receipt identities, the last-file resume behavior, and the required state transitions demonstrated by the mockup. +- Evidence needed: Accepted workflow, concrete workspace/child/route/receipt identities, local arrangement/focus restoration, per-child review-file resumption, and required state transitions demonstrated by the mockup. - Next action: Expand this file into an executable plan with owned interfaces, implementation steps, schema/recovery details, and a test matrix. Recheck the target graph and relevant repository contracts before readiness. -The eventual checks must demonstrate two independent PR workspaces reopening with their references and drafts; file-top resumption; per-file new-edit/full-diff selection; preserved prior review evidence after a push; no cross-PR progress leakage; explicit baseline advancement; honest incomplete history; and failed/stale saves preserving accepted state. Include real persistence round trips and controlled competing mutations. Use the matching Core tests, architecture checks, and formatting after targets exist; a zero-test pass is not acceptance. +The eventual checks must demonstrate two independent PR workspaces reopening with their children, references, drafts, arrangements, and last-focused child; independent navigation in multiple children of the same kind; file-top review resumption; per-file new-edit/full-diff selection shared within the PR; preserved prior review evidence after a push; no cross-PR progress leakage; explicit baseline advancement; honest incomplete history; and failed/stale saves preserving accepted state. Changing outer presentation must preserve logical identities. Include real persistence round trips and controlled competing mutations. Use the matching Core tests, architecture checks, and formatting after targets exist; a zero-test pass is not acceptance. ## Decisions and revisions @@ -90,6 +94,7 @@ The eventual checks must demonstrate two independent PR workspaces reopening wit | 2026-11-14 | Initially proposed foundation-first delivery with atomic metadata persistence and PR-wide explicit checkpoints. | Initial plan at `d1ee30cc82d110dfac94fecb58fce9762020cb58`; no implementation ran. | | 2026-11-14 | Replace the checkpoint model with per-file reviewed versions; resume from the file top; keep one workspace per PR. | Q-13–Q-15. | | 2026-11-14 | Return this deliverable to outline and refine it after a lightweight, three-layout prototype. | Q-16–Q-18. | +| 2026-11-14 | Distinguish workspace, child-view, route, and presentation identities; restore arrangement and last focus, with a selected file per review child. | First-artifact feedback and [Q-19–Q-21](README.md#q-19). | ## Execution record diff --git a/Plans/2026-11-14-mobius/02-application-workspace.md b/Plans/2026-11-14-mobius/02-application-workspace.md index 4a9132c7d..a6697f168 100644 --- a/Plans/2026-11-14-mobius/02-application-workspace.md +++ b/Plans/2026-11-14-mobius/02-application-workspace.md @@ -6,15 +6,15 @@ ## Intended outcome -Mobius launches on iPhone, iPad, and Mac Catalyst with a persistent workspace per PR. A reviewer switches between independent synthetic PR workspaces, each retaining its reference files and searches. Returning to a review opens its last file from the top. iPad/Mac support multiple windows; iPhone provides usable workspace/document switching within its available scene capabilities. +Mobius launches on iPhone, iPad, and Mac Catalyst with a persistent logical workspace per PR, presentable as a tab or an outer window. Each workspace contains several child windows for review, source, and research, with independent navigation even when two show the same kind of content. Returning restores its arrangement and last-focused child. Resuming a review child opens its selected file from the top. iPad/Mac support native multiple windows; iPhone provides usable workspace/child switching within its available scene capabilities. -Success is a native runtime demonstration with two independent review workspaces and their reference documents, independent window selections, Mac menu/keyboard actions, and file-top resumption. It follows the evaluated browser mockup in [01a](01a-workspace-prototype.md). This is fixture-backed groundwork, not live GitHub or sync delivery. +Success is a native runtime demonstration with two independent PR workspaces, multiple children, retained arrangement/focus across workspace and outer-presentation changes, Mac menu/keyboard actions, and file-top review resumption. It follows the evaluated browser mockup in [01a](01a-workspace-prototype.md). This is fixture-backed groundwork, not live GitHub or sync delivery. Preview/simulation placement may use fixtures; actual host/live capabilities remain in 07. ## User stories and requirements | Story | Requirement | Intended contribution | | --- | --- | --- | -| US-01, US-02 | R-02, R-03 | Independent PR workspaces, document switching, file-top resumption, and scene restoration. | +| US-01, US-02 | R-02, R-03 | Logical PR workspaces, outer tabs/windows, independent child navigation, arrangement/focus restoration, and file-top review resumption. | | US-06 | R-01 | iPhone/iPad app and Mac Catalyst windows, menus, and shortcuts. | | US-01, US-06 | R-10 | Accessible adaptive layout and keyboard/focus behavior. | | Supporting | R-11 | Host/UI targets, docs, unit/image coverage, and Catalyst validation. | @@ -25,28 +25,28 @@ See [definitions and exclusions](README.md#requirements). X-03 and X-07 apply. D Proposed paths: `Mobius/MobiusUI/{Sources,Tests,SnapshotTests,README.md,AGENTS.md}` and `Mobius/Mobius/{Sources,Tests,Resources,README.md,AGENTS.md}`. Add the host and UI products through the root manifests. Give Mobius explicit iPhone/iPad/Catalyst destinations; do not expand Where's destination constant. -Create the Core runtime once in the process composition root. Each scene receives a `WorkspaceModel` for one PR with local presentation and the shared store. Restore scene-to-workspace references; missing or explicitly deleted workspace identity produces a recovery/selection state, not a new random identity. Window closure releases that scene's work; it does not delete the workspace or affect another scene's tasks. PRs remain independent when a stack connection is displayed. +Create the Core runtime once in the process composition root. Scene presentation refers to logical workspace IDs; a scene can host workspace tabs, while a separate native window can present a workspace. Workspace models refer to child IDs and shared PR progress. Do not equate a workspace or child window with a UIKit scene. Restore scene-to-workspace references; missing or explicitly deleted workspace identity produces a recovery/selection state, not a new random identity. Closing a native presentation releases its presentation-owned work; it does not delete the logical workspace or affect another scene's tasks. PRs remain independent when a stack connection is displayed. -Use 01a's evaluated interactions to distinguish switching PR workspaces from switching documents inside one PR. Layouts and labels from the mockup remain candidates until validated natively. Mac windows use system scene APIs, with app-specific menu and shortcut routing to the focused scene. Separate shared document closure from closing a native window. Reopening a review file starts at its top; precise in-file restoration is not required. +Use 01a's evaluated interactions to distinguish switching PR workspaces from selecting, opening, or arranging children inside one PR. Q-20 allows floating, tiling, docking, or tabs where useful; choose native defaults and platform affordances during refinement. Layouts and labels from the mockup remain candidates until validated natively. Mac outer windows use system scene APIs, with app-specific menu and shortcut routing through the focused workspace to its focused child. Separate child closure, closing a native window, and deleting a workspace. Restore arrangement and last-focused child on return; resuming a review child starts its file at the top. Exact review offsets are not required. ```mermaid flowchart LR Root["Proposed Mobius composition root"] --> Runtime["Proposed runtime using 01 store"] - Runtime --> A["Proposed scene A model"] - Runtime --> B["Proposed scene B model"] - A --> ViewA["Proposed workspace view A"] - B --> ViewB["Proposed workspace view B"] - Native["Existing UIKit scene lifecycle"] --> A - Native --> B + Runtime --> Workspace["Logical PR workspace and shared progress"] + Workspace --> Children["Identified review/source/research children"] + Native["Existing UIKit scene lifecycle"] --> Presentation["Proposed outer tabs or workspace windows"] + Presentation -->|references workspace IDs| Workspace + Presentation -->|arrangement and focus by child ID| Children ``` ```swift // Proposed composition sketch; API details await 01. @MainActor -func makeScene(workspaceID: Workspace.ID, runtime: MobiusRuntime) -> WorkspaceModel { +func makeWorkspaceModel(workspaceID: Workspace.ID, runtime: MobiusRuntime) -> WorkspaceModel { WorkspaceModel(workspaceID: workspaceID, runtime: runtime) } -// Each scene owns its model; the process owns runtime and persistence. +// Scene/tab presentation references workspace models; each owns child models. +// The process owns runtime and persistence. Exact sharing/lifetimes await 01. ``` Use the [building-ui skill](../../.agents/skills/building-ui/SKILL.md), Broadway root/stylesheet conventions, and production-shaped injected fixtures. Add `MobiusUITests` to `Stuff-iOS-Tests` and `MobiusUISnapshotTests` to `StuffSnapshotTests`, with no new snapshot scheme. Follow full-content capture rules for scrolling panes and pair them with bounded shell captures. SnapshotKit's iOS renderer does not establish Catalyst window behavior. @@ -57,7 +57,8 @@ Declare Mobius's attribution inputs and bundled report through CreditKit's exist - [Q-10](README.md#q-10): Select the code-text substrate and layout after measuring long lines, many documents, accessibility sizes, selection, and VoiceOver. Identify real latency/memory budgets and fixture sizes before readiness. - [Q-11](README.md#q-11): Specify CLI Catalyst compile coverage and a native window/menu smoke test. Existing `./test` cannot be assumed to target Catalyst. Extend repository tooling only where required, with its public-command tests and owning docs. -- Integrate Q-13–Q-15 and prototype feedback: one workspace per PR, file-top resumption, and clear remaining-work/full-PR navigation. Existing scroll-restoration machinery does not establish a requirement to restore an exact review offset. +- Integrate Q-13–Q-15 and Q-19–Q-21: logical workspaces, multiple identified children, outer presentation independent from contents, last-focus/arrangement restoration, and clear remaining-work/full-PR navigation. Existing scroll-restoration machinery does not establish a requirement to restore an exact review offset. +- Refine close/detach/reopen behavior and any simultaneous presentations of one workspace before implementing them. The bounded mockup need not settle every native scene lifecycle rule. ## Refinement trigger @@ -72,6 +73,7 @@ Declare Mobius's attribution inputs and bundled report through CreditKit's exist | 2026-11-14 | Share UIKit/Broadway through Catalyst, with Mac-specific windows, menus, and shortcuts. | Q-04. | | 2026-11-14 | Keep platform scene presentation local while workspace identity persists. | Overview design proposal. | | 2026-11-14 | Adopt per-PR grouping and file-top resumption after the lightweight mockup is evaluated. | Q-13/Q-14, Q-16–Q-18. | +| 2026-11-14 | Restore logical workspaces with multiple child windows independently of outer tab/window presentation; retain arrangement and last focus. | First-artifact feedback and [Q-19–Q-21](README.md#q-19). | ## Resume point diff --git a/Plans/2026-11-14-mobius/03-github-and-revision-comparison.md b/Plans/2026-11-14-mobius/03-github-and-revision-comparison.md index 07bf0469f..8c5861b5d 100644 --- a/Plans/2026-11-14-mobius/03-github-and-revision-comparison.md +++ b/Plans/2026-11-14-mobius/03-github-and-revision-comparison.md @@ -51,6 +51,8 @@ GitHub PR-file/compare responses have documented limits; see [research](README.m Re-evaluate exact file comparison identities rather than resetting all progress on every new head. Retain prior review evidence when new edits appear. Only the explicit file-review action advances that file's baseline; navigation, full-diff viewing, and refresh do not. Since full caches do not sync, a new device may have to fetch old objects. Deleted/unreachable objects must produce a visible baseline gap with access to the current full PR diff, not fabricated equivalence or a claim that no work remains. +Multiple review children in one workspace share that PR's receipts while retaining their own selected file and comparison view. An action must identify the immutable comparison actually inspected in its originating child. Refinement must cover two children showing different revisions, so advancing progress from one cannot falsely mark unseen content in another reviewed. This follows the workspace/child distinction in [Q-19–Q-21](README.md#q-19). + Fixtures must include binary/non-text and oversized files, missing patches, CRLF/Unicode/long lines, submodules, rename/mode changes, missing pages, permission loss, cancellation, rate limiting, and superseded refreshes. Define supported rendering and indexing limits before readiness. Show unsupported content honestly without marking its review complete. ## Questions and learning needed diff --git a/Plans/2026-11-14-mobius/04-repository-exploration.md b/Plans/2026-11-14-mobius/04-repository-exploration.md index 658c4d337..481e72ced 100644 --- a/Plans/2026-11-14-mobius/04-repository-exploration.md +++ b/Plans/2026-11-14-mobius/04-repository-exploration.md @@ -6,16 +6,16 @@ ## Intended outcome -Browse the repository and search file paths and text while the current review stays open. Results belong to that PR's workspace and open at a stated revision. Switching PRs preserves each workspace's context; resuming the review returns to its last file at the top with progress preserved. +Browse the repository and search file paths and text while review windows stay open. Results belong to that PR's workspace and open in child views at a stated revision. Several source/search children can coexist with independent navigation, including views of the same file. Switching PRs preserves each workspace's arrangement and last-focused child; resuming a review child starts its selected file at the top with progress preserved. -Demonstrate a search from PR A, opening a file outside its diff, switching to PR B, and returning to A unchanged. Repeat at different revisions where the same path has different content. Partial indexing must not look like a complete “no results” response. +Demonstrate two independent searches in PR A, opening a file outside its diff, focusing a source child, switching to PR B, and returning to A with that focus and arrangement preserved. Change outer tab/window presentation without recreating the children. Repeat at different revisions where the same path has different content. Partial indexing must not look like a complete “no results” response. ## User stories and requirements | Story | Requirement | Intended contribution | | --- | --- | --- | | US-01, US-04 | R-02, R-05 | Repository tree, path search, text search, and persistent source/search documents. | -| US-02 | R-03 | Restore semantic queries and the last review file within its PR workspace. | +| US-02 | R-03 | Restore queries/routes per child and preserve workspace arrangement/focus. | | US-07 | R-08, R-09 | Revision/coverage labels, account-isolated caches, and cancellation. | | US-04, US-06 | R-10 | Accessible results and bounded indexing/rendering workloads. | @@ -23,7 +23,7 @@ X-02, X-05, and X-07 apply. Editing code, terminal access, language-server navig ## Known design and assumptions -Use the immutable tree/blob provider from 03 and typed document routes from 01. Put navigation/search policy in focused Core types and the observable interaction in UI. Scope indexes by account, repository, and immutable tree; never silently answer a PR-head search with default-branch results. +Use the immutable tree/blob provider from 03 and typed child identities/document routes from 01. Put navigation/search policy in focused Core types and the observable interaction in UI. Scope each query and result selection to its child; share revision-bound cache/index data without coupling independent views. Scope indexes by account, repository, and immutable tree; never silently answer a PR-head search with default-branch results. Proposed search design: fast path/name matching over the enumerated tree, plus local text indexing of supported fetched blobs. Fetch missing content on a bounded, cancellable schedule, with explicit progress and coverage. Define file-size, storage, network, and indexing limits during Q-10 refinement. Keep useful partial results while distinguishing indexing, complete, incomplete, and failed states. Source/index cache eviction must not delete draft text, receipts, or workspace document identities. @@ -33,9 +33,9 @@ flowchart LR Tree --> Paths["Proposed path search"] Tree --> Blobs["Account-scoped blob cache"] Blobs --> Index["Proposed text index with coverage"] - Paths --> Results["Proposed result document"] + Paths --> Results["Results in an identified search child"] Index --> Results - Results -->|open alongside review| Workspace["Workspace from 02"] + Results -->|open source child alongside review| Workspace["Logical workspace from 02"] ``` ```swift @@ -66,6 +66,7 @@ GitHub's default-branch code-search endpoint is not the implementation of PR-rev | --- | --- | --- | | 2026-11-14 | Repository exploration is part of the review workspace, with path and text search at an explicit revision. | Q-03, R-05. | | 2026-11-14 | Keep exploration documents with their PR when switching to another PR workspace. | Q-13. | +| 2026-11-14 | Support multiple independent research/source children and restore their arrangement/focus on return. | First-artifact feedback and [Q-19–Q-21](README.md#q-19). | ## Resume point diff --git a/Plans/2026-11-14-mobius/05-review-feedback.md b/Plans/2026-11-14-mobius/05-review-feedback.md index fcff7e696..3f1b90be3 100644 --- a/Plans/2026-11-14-mobius/05-review-feedback.md +++ b/Plans/2026-11-14-mobius/05-review-feedback.md @@ -24,6 +24,8 @@ X-02, X-03, and X-05 apply. No automatic review publication on navigation, backg Core owns `ReviewDraft`, anchor mapping, and a proposed `ReviewPublisher`. UI owns composition, confirmation, and recovery presentation. Scope publication by account, PR, and draft revision; one local owner serializes mutations for that draft. Record the original immutable file comparison and anchor when text is authored. +Several children may present the same PR's draft or different code revisions. Child navigation remains independent, while draft identity and publication ownership stay with the workspace. Closing or changing presentation must not implicitly publish or delete authored work. Refine same-draft editing and command routing across children before readiness, using [Q-19–Q-21](README.md#q-19) and Q-09's ownership rules. + Read the current PR state before submission. If the head or comparison context changed, show the change and retain the draft until its target is revalidated. A comment authored while viewing a file's new edits since its reviewed version must map to a valid location in the PR review diff, or remain an unsubmitted draft with a useful explanation. Never attach a comment to the same line number in unrelated content. Submit an explicit commit ID where the API supports it; a preflight read does not make a later API write atomic with branch updates. ```mermaid diff --git a/Plans/2026-11-14-mobius/06-icloud-resume-and-release.md b/Plans/2026-11-14-mobius/06-icloud-resume-and-release.md index 3e585ae9a..3150b6227 100644 --- a/Plans/2026-11-14-mobius/06-icloud-resume-and-release.md +++ b/Plans/2026-11-14-mobius/06-icloud-resume-and-release.md @@ -6,7 +6,7 @@ ## Intended outcome -Start reviews on one device and continue them on another using private iCloud under the same Apple ID. Independent PR workspaces, documents, last review files, per-file reviewed versions, and drafts converge without losing user work or taking over another device's window focus. Reopening a review starts at the top of its last file. Each device authenticates its own GitHub account before retrieving protected source. +Start reviews on one device and continue them on another using private iCloud under the same Apple ID. Independent logical PR workspaces, identified children and their navigation, per-file reviewed versions, and drafts converge without losing user work or taking over another device's window focus. Returning locally restores the workspace's arrangement and last-focused child; resuming a review child starts at the top of its selected file. Each device authenticates its own GitHub account before retrieving protected source. This deliverable is required for the first release. Demonstrate an iPhone-to-iPad-to-Mac handoff, concurrent edits, offline work, reconnect, account transitions, and a complete GitHub review flow. A local-only app or simulator-only sync demonstration does not satisfy it. @@ -25,7 +25,7 @@ X-05 and X-06 apply. No custom workspace-sync backend, different-Apple-ID contin The candidate transport is `CKSyncEngine` over a dedicated private CloudKit database/container. The app owns local atomic persistence, pending record changes, serialized engine state, conflict policy, and account transitions. Keep the Core store's accepted-state interface; measure whether record projection requires a different internal persistence implementation. -Use stable per-entity records instead of a single last-writer-wins workspace blob. Design tombstones and deterministic merge rules for document membership/order, last review file, per-file review evidence, and draft revisions. Preserve competing draft texts. Explicitly distinguish opening a new document from an old offline device replaying a deleted document. Wall-clock order alone must not discard user-authored content. +Use stable per-entity records instead of a single last-writer-wins workspace blob. Design tombstones and deterministic merge rules for child membership, per-child semantic navigation including selected review files, per-file review evidence, and draft revisions. Two views of one file have distinct child IDs. Separate those identities from native scenes, outer presentation mode, and device arrangement. Preserve competing draft texts. Explicitly distinguish opening a new child from an old offline device replaying a deleted child. Wall-clock order alone must not discard user-authored content. ```mermaid flowchart LR @@ -45,7 +45,7 @@ protocol WorkspaceSynchronizing: Sendable { // It does not publish GitHub feedback or copy authentication credentials. ``` -Native window bounds, selected panes, focus, and local scene IDs remain device-local. Restored workspace content must fit the receiving device. Preserve the semantic last-file identity and open a resumed review at its top; exact scroll offsets are not part of the continuity contract. Remote work becomes available without unexpectedly opening windows or closing a focused local document during an edit. +Proposed policy keeps native window bounds, child arrangement, last-focused child, and local scene IDs device-local. Returning to an existing local workspace restores that arrangement/focus under Q-21; a first open on another device needs an adaptive arrangement. Refine initial focus, order, and concurrent child-navigation behavior under Q-09 before fixing the sync schema. Preserve each review child's selected-file identity and resume it at the top; exact review scroll offsets are not part of the continuity contract. Remote work becomes available without unexpectedly opening windows or closing a focused local child during an edit. Account changes must stop the prior sync scope and isolate its files/records before any new scope starts. iCloud sign-out must not silently upload one account's drafts into another account. GitHub sign-out/revocation must prevent protected fetches and display, with an explicit policy for retained private drafts and caches. Preserve recoverable user work while resolving access; never infer fresh access from stale credentials. @@ -65,10 +65,10 @@ Account changes must stop the prior sync scope and isolate its files/records bef The executable refinement must preserve this sequence: -1. Open two independent PR workspaces and their repository context on iPhone; mark a file reviewed in one PR, leave another unreviewed, and save feedback text. -2. Resume on iPad at the top of the last review file; open a second window and follow a search result without losing either PR's context. +1. Open two independent PR workspaces and several source/research/review children on iPhone; mark a file reviewed in one PR, leave another unreviewed, and save feedback text. +2. Make those workspaces and children available on iPad using its receiving-device presentation policy. Resume a review child at its selected file's top; open another child and follow a search result without losing either PR's context. Switch away and back to prove local arrangement and last focus are retained. Present a workspace as a tab or outer window without changing its contents. 3. Change the test PR; on Mac, verify new edits against each reviewed file's baseline, the full PR diff for an unreviewed file, and full-diff access for either. Check menu/keyboard navigation and that the second PR's progress is unaffected. -4. Make competing offline draft edits on two devices; reconnect and recover both texts. Exercise document close/reopen and account switching. +4. Make competing offline draft edits on two devices; reconnect and recover both texts. Exercise child close/reopen, independent navigation in same-kind children, and account switching without remote focus changes. 5. Submit feedback once through an explicit user action; interrupt the response and prove recovery does not blindly replay the write from either device. 6. Verify the same workflow with accessibility text sizes and VoiceOver, and inspect the platform-specific CI/runtime evidence. @@ -81,6 +81,7 @@ This is a planned acceptance flow, not a measured result. Refine exact assertion | 2026-11-14 | Private iCloud continuity is in the first release and uses the same Apple ID. | Q-05/Q-07. | | 2026-11-14 | Sync semantic workspace metadata/drafts, retaining native presentation and source caches locally. | Overview design proposal. | | 2026-11-14 | Sync independent PR workspaces, last-file identity, and per-file reviewed versions; resume at the file top. | Q-13–Q-15. | +| 2026-11-14 | Restore local arrangement/last focus; sync semantic child identity/navigation separately from device presentation. Refine receiving-device defaults and concurrent navigation under Q-09. | [Q-19–Q-21](README.md#q-19), with sync mapping still provisional. | ## Resume point diff --git a/Plans/2026-11-14-mobius/07-embedded-review-experiment.md b/Plans/2026-11-14-mobius/07-embedded-review-experiment.md index a73b216b4..b17c328f6 100644 --- a/Plans/2026-11-14-mobius/07-embedded-review-experiment.md +++ b/Plans/2026-11-14-mobius/07-embedded-review-experiment.md @@ -21,6 +21,8 @@ X-04 applies: no downloaded PR execution, arbitrary native hot loading, or gener Use a synthetic test host with injected Mobius runtime and a precompiled demonstration action, such as opening a known sample screen with chosen fixture data. Reuse the production review presentation rather than copying it into a separate embedded UI. The host owns the action and supplies build identity; the reviewer compares that identity with the selected PR snapshot. +Explore the live-context surface as an identified child inside the same logical PR workspace, beside review and research children. Its view-local navigation and focus must fit the workspace model from [Q-19–Q-21](README.md#q-19). The browser prototype's simulated preview demonstrates placement only; it neither runs the reviewed code nor proves host integration. Q-19 corrected “fork” to “view” and adds no code-copy or editing requirement. + Bound the refined experiment to one host, one precompiled action, and matching/mismatching/unknown build identity cases. Proposed effort bound: two engineering days after prerequisites are ready; refine this bound before execution. Preserve a report and minimal repeatable harness if it proves useful. Remove unused prototype targets and keep experimental controls out of shipping host behavior. ```mermaid @@ -58,6 +60,7 @@ Explore whether a built-in action provides enough context to be valuable. If use | --- | --- | --- | | 2026-11-14 | Investigate embedding/live context later within this series; do not promise it in the first release. | Q-06. | | 2026-11-14 | Use host-supplied compiled capabilities and truthful revision identity as the initial experiment boundary. | R-12 and X-04. | +| 2026-11-14 | Investigate live context within a workspace child; keep browser preview/simulation fixtures separate from actual execution evidence. | First-artifact feedback and [Q-19](README.md#q-19). | ## Resume point diff --git a/Plans/2026-11-14-mobius/README.md b/Plans/2026-11-14-mobius/README.md index 5482ab805..7510c54bb 100644 --- a/Plans/2026-11-14-mobius/README.md +++ b/Plans/2026-11-14-mobius/README.md @@ -2,31 +2,31 @@ ## Planning checkpoint -- Updated: 2026-11-14; repository baseline `b629d56ac44a3f2a5ea59c3d6ae9cd5401f37674`. +- Updated: 2026-11-14; initial repository baseline `b629d56ac44a3f2a5ea59c3d6ae9cd5401f37674`; merged main through `96f5bf0f1685de259d7ff080842b8092f9a950d2` in `68477fe625784a1a1e68c0115d7e42cc63166692`. - Operation: Execute 01a in a background agent while continuing production-plan discussion here. Native implementation is not requested. -- Requested scope and source: The user's 2026-11-14 request, Q-01–Q-07 answers, and Q-13–Q-18 follow-ups on review continuity and prototype priority; see [question history](#questions-and-resolutions). -- Stage: Prototype execution in an isolated worktree; production planning continues separately. -- Completed: Initial research and publication in [PR #497](https://github.com/kyleve/Stuff/pull/497); integrated one workspace per PR, file-top resumption, per-file remaining work, and a lightweight mockup across all three layouts. [STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app) tracks plan delivery. -- Pending: Prototype implementation, browser validation, and user feedback; PR review and merge. Q-08–Q-12 remain at their technical refinement gates. The mockup must supply interaction evidence before the durable model becomes executable. -- Execution authorization: The user subsequently requested background execution of 01a on 2026-11-14. The prototype runs on `codex/mobius-prototype` in `/Users/kve/.codex/worktrees/mobius-prototype/Stuff`, based on `4e70677e7`. Its branch owns the artifact and 01a execution evidence; this branch owns the overview and production-plan discussion. -- Next action: The background agent implements and validates [01a](01a-workspace-prototype.md#resume-point), then returns the artifact for user evaluation. Continue production discovery here without assuming the prototype has already validated its hypotheses. +- Requested scope and source: The user's 2026-11-14 request, Q-01–Q-07 answers, Q-13–Q-18 follow-ups, and first-prototype feedback clarified by Q-19–Q-21; see [question history](#questions-and-resolutions). +- Stage: Workspace/window correction integrated and reviewed; the second prototype iteration is executing in the background. +- Completed: Initial research and publication in [PR #497](https://github.com/kyleve/Stuff/pull/497); first browser artifact in [PR #500](https://github.com/kyleve/Stuff/pull/500) at `2e3653877bf141964805d417eac0b94c03a24c6a`. The user evaluated it and identified a material workspace-model correction. [STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app) tracks plan delivery; [STU-330](https://linear.app/kve/issue/STU-330/prototype-mobius-review-workspaces) tracks the experiment. +- Pending: Validate the revised prototype interaction and obtain user evaluation; PR review and merge. Q-08–Q-12 remain at their technical refinement gates. The first artifact is evidence to retain, not acceptance of the corrected model. +- Execution authorization: The user requested background execution of 01a on 2026-11-14 and then requested the workspace correction. The prototype runs on `codex/mobius-prototype` in `/Users/kve/.codex/worktrees/mobius-prototype/Stuff`; it includes the main merge above. Its branch owns the artifact and 01a execution evidence; this branch owns the overview and production-plan discussion. +- Next action: The background agent implements and validates the [current 01a execution contract](https://github.com/kyleve/Stuff/blob/codex/mobius-prototype/Plans/2026-11-14-mobius/01a-workspace-prototype.md#iteration-2-readiness-and-execution), preserving first-iteration evidence, then returns the revised artifact for user evaluation. The 01a copy on the planning branch is its pre-execution baseline; the implementation branch owns subsequent method revisions and execution status. Native plans remain outlines. ## Outcome and scope -Mobius keeps code review open as ongoing work. Each PR has its own workspace containing its review, reference files, and searches. Reviewers switch between those independent workspaces and resume at the top of the file they left. A remaining-work view shows new edits in previously reviewed files and the full PR diff for unreviewed files; the full PR diff stays available for either. Each reviewed file has its own last-reviewed version. Nobody needs a temporary “got to here” GitHub comment. +Mobius keeps code review open as ongoing work. Each PR has its own logical workspace, which can be presented as a tab or a window. Inside it, reviewers can keep several windows open for review, source, research, and preview context. Returning restores that workspace's arrangement and last-focused window. Resuming a review window starts at the top of its selected file. A remaining-work view shows new edits in previously reviewed files and the full PR diff for unreviewed files; the full PR diff stays available for either. Each reviewed file has its own last-reviewed version. Nobody needs a temporary “got to here” GitHub comment. PRs remain separate even when GitHub connects them in a stack. If a stack connection is shown, it is an informational link; it does not combine progress, drafts, comparison baselines, or submission actions. Stack discovery is not an additional first-release integration requirement. The first release targets **iPhone, iPad, and Mac Catalyst**, including Mac windows, menus, and shortcuts. It supports GitHub PR diffs, comments, approvals, and requests for changes. Private iCloud sync carries workspaces and personal progress between devices using the same Apple ID. These are first-release requirements even though implementation is divided into deliverables. -Embedding the reviewer inside an owning app, with a possible live execution surface, is a **later feasibility experiment** in this series. It is not a first-release capability promise. +Embedding the reviewer inside an owning app, with a possible live execution surface, is a **later feasibility experiment** in this series. Preview and simulation windows in the browser prototype use synthetic content to explore their place in a workspace; they do not establish a first-release execution capability. ## User stories | ID | Story | | --- | --- | -| US-01 | Keep several reviews and reference documents open, so investigating one question does not discard another task. | -| US-02 | Resume my review file from its top, with drafts and progress preserved, without reconstructing my last session. | +| US-01 | Keep independent PR workspaces as tabs or windows, each containing several review and research windows, so investigating one question does not discard another task. | +| US-02 | Restore my workspace arrangement and last-focused window, with drafts and progress preserved; resume a review file from its top. | | US-03 | Distinguish unchanged reviewed work from new PR changes, so I can concentrate on what needs another pass. | | US-04 | Browse and search repository context without leaving the review workspace. | | US-05 | Comment, approve, or request changes against the code I inspected. | @@ -41,12 +41,12 @@ R-01–R-07 and R-12 derive from the user's product choices. R-08–R-11 support | ID | Required behavior or constraint | Story | Implementing plan | | --- | --- | --- | --- | | R-01 | Run on iPhone, iPad, and Mac Catalyst, with Mac windows, menus, and keyboard commands. | US-06 | [02](02-application-workspace.md), [06](06-icloud-resume-and-release.md) | -| R-02 | Keep one independent workspace per PR, with its reference files and searches. Switching PRs preserves each workspace. Stack connections, if shown, are informational. | US-01, US-04 | [01a](01a-workspace-prototype.md) explores interaction; [01](01-review-state-foundation.md), [02](02-application-workspace.md), [04](04-repository-exploration.md) deliver it | -| R-03 | Persist workspace documents, the last review file, per-file reviewed versions, and drafts across relaunch. Resume the file from its top; precise in-file position and reviewed-range tracking are not required. Personal progress and submitted GitHub feedback remain separate facts. | US-02 | [01a](01a-workspace-prototype.md) explores interaction; [01](01-review-state-foundation.md), [02](02-application-workspace.md), [05](05-review-feedback.md) deliver it | +| R-02 | Keep one independent logical workspace per PR, presentable as a tab or window. Each owns multiple child windows for review, source, and research, with room to investigate preview/live context. Support multiple views of the same kind with independent navigation. Switching PRs or outer presentation preserves their contents. Stack connections, if shown, are informational. | US-01, US-04 | [01a](01a-workspace-prototype.md) explores interaction and simulated previews; [01](01-review-state-foundation.md), [02](02-application-workspace.md), [04](04-repository-exploration.md) deliver the workspace; [07](07-embedded-review-experiment.md) investigates live context | +| R-03 | Persist child-window identity/navigation, per-file reviewed versions, and drafts across relaunch. Returning restores the workspace arrangement and last-focused child. Resuming a review child starts at its selected file's top; precise in-file position and reviewed-range tracking are not required. Review progress belongs to the PR workspace; personal progress and submitted GitHub feedback remain separate facts. | US-02 | [01a](01a-workspace-prototype.md) explores interaction; [01](01-review-state-foundation.md), [02](02-application-workspace.md), [05](05-review-feedback.md) deliver it | | R-04 | Within one PR, remaining work combines new edits since each reviewed file's last-reviewed version with the full PR diff for unreviewed files. Let either file open its full PR diff. An explicit file-review action advances that file's baseline; navigation and refresh do not. | US-03 | [01a](01a-workspace-prototype.md) explores interaction; [01](01-review-state-foundation.md), [03](03-github-and-revision-comparison.md) deliver it | -| R-05 | Browse files and search paths and text at an identified repository revision within Mobius. Open results without replacing the review and show search coverage. | US-04 | [04](04-repository-exploration.md) | +| R-05 | Browse files and search paths and text at an identified repository revision within Mobius. Open results in child windows without replacing the review and show search coverage. Independent views may inspect the same file or separate queries. | US-04 | [04](04-repository-exploration.md) | | R-06 | Read review discussion; compose and explicitly submit comments, approvals, and requests for changes with revision validation and recoverable drafts. | US-05 | [03](03-github-and-revision-comparison.md), [05](05-review-feedback.md) | -| R-07 | Resume documents, progress, and draft work through private iCloud sync on the same Apple ID. Keep device window placement local and expose sync state. | US-02, US-06 | [01](01-review-state-foundation.md) supplies identities; [06](06-icloud-resume-and-release.md) delivers sync | +| R-07 | Resume workspace contents, child-view navigation, progress, and draft work through private iCloud sync on the same Apple ID. Keep device window placement local and expose sync state; refine cross-device presentation policy under Q-09. | US-02, US-06 | [01](01-review-state-foundation.md) supplies identities; [06](06-icloud-resume-and-release.md) delivers sync | | R-08 | Preserve original failures, last usable data, and incomplete coverage. Older requests cannot overwrite active state. Missing history cannot imply “reviewed” or “no changes.” | US-07 | [01](01-review-state-foundation.md), [03](03-github-and-revision-comparison.md), [04](04-repository-exploration.md), [05](05-review-feedback.md), [06](06-icloud-resume-and-release.md) | | R-09 | Scope data by account and repository identity. Keep credentials in device-local Keychain; do not sync them or full repository caches. Protect private code and draft text from diagnostic export. | US-07 | [01](01-review-state-foundation.md), [03](03-github-and-revision-comparison.md), [06](06-icloud-resume-and-release.md) | | R-10 | Support touch, keyboard, VoiceOver, accessibility text sizes, long lines, and large diffs. Define measured rendering/indexing budgets before the corresponding plan becomes ready. | US-01, US-04, US-06 | [02](02-application-workspace.md), [03](03-github-and-revision-comparison.md), [04](04-repository-exploration.md) | @@ -94,18 +94,19 @@ Consulted 2026-11-14. External sources establish documented capabilities, not li ### Discovery scenario -PR 42 and PR 43 each have their own workspace. Opening a reference file or search from PR 42 retains it there when switching to PR 43. Returning to PR 42 restores its last review file at the top. A stack link between those PRs does not merge their work. +PR 42 and PR 43 each have their own workspace. Within PR 42, open a review, two source or research windows, and a simulated preview. Each child retains its own navigation and state. Arrange the children, focus a research window, and switch to PR 43. Returning to PR 42 restores its arrangement and the research window's focus. Selecting the review again opens its selected file at the top. Present PR 42 as a workspace tab or an outer window without recreating its children. A stack link between the PRs does not merge their work. Within PR 42, mark `Parser.swift` reviewed at version 1 and leave `Store.swift` unreviewed. A simulated push supplies version 2. Remaining work shows the version-1-to-version-2 edits for `Parser.swift` and the full current PR diff for `Store.swift`. Either can open its full PR diff. Marking `Parser.swift` reviewed again advances only its baseline. These are files within one PR, not three separate reviews. -The first deliverable is a lightweight interactive mockup with phone, tablet, and desktop layouts. It will explore navigation, labels, and layout using synthetic PRs before native implementation or durable storage. See [01a](01a-workspace-prototype.md). A mockup result will not establish native platform, persistence, provider, or sync feasibility. +The first deliverable is a lightweight interactive mockup with phone, tablet, and desktop layouts. The first artifact limited child views by kind and forced review focus on return. The user rejected that flattening; the second iteration explores the corrected hierarchy, multiple view instances, and useful tiled, floating, or compact arrangements. The user allows arrangement modes as needed; exact controls and native platform defaults remain hypotheses. See [01a](01a-workspace-prototype.md). A mockup result will not establish native platform, persistence, provider, sync, or execution feasibility. ### Product concepts -- **Workspace:** one PR's review, source, and search documents. Another PR has a separate workspace, including when the PRs belong to a stack. -- **Document:** a typed route with account/repository identity and an explicit revision policy. Pinned source tabs must not silently follow moving branches. -- **Window presentation:** device-local selection, panes, focus, and scene identity. Synced work becomes available to resume without stealing focus or automatically spawning windows. -- **Resume file:** the last review file within that PR workspace. Reopening starts at its top; an exact scroll position is not durable review progress. +- **Workspace:** the logical owner of one PR's child windows, progress, and drafts. Its identity does not depend on being presented as a workspace tab or outer window. Another PR has a separate workspace, including when the PRs belong to a stack. +- **Child window/view:** an identified instance inside a workspace, with its own navigation and state. Several can show the same kind of content or the same file. Review progress remains shared within the owning PR. A child window is not inherently a native OS scene. +- **Document route:** the content a child shows, with account/repository identity and an explicit revision policy. View identity is separate from route identity; pinned source content must not silently follow moving branches. +- **Presentation:** outer workspace tabs/windows plus each workspace's child arrangement and last-focused child. Returning restores that local arrangement and focus. Tiling, floating, docking, and tabs are available directions to evaluate, not a settled native window-manager specification. Synced work becomes available without stealing focus or automatically spawning windows. +- **Resume file:** each review child's selected file. Resuming that review starts at its top; an exact scroll position is not durable review progress. Returning to a workspace need not focus a review child. - **Review receipt:** explicit evidence for a file comparison, including both sides, paths, modes, and content identities. A new head alone neither invalidates every receipt nor proves any one remains current. - **Per-file baseline:** the version last marked reviewed for that file. Remaining work compares against it; a file with no baseline shows its full PR diff. A separate manually captured PR-wide checkpoint is not required by the selected workflow. - **Draft:** user text with its original revision/anchor. Draft, publishing, uncertain outcome, and confirmed publication remain distinct states. @@ -114,7 +115,7 @@ The first deliverable is a lightweight interactive mockup with phone, tablet, an Start with `MobiusCore`, `MobiusUI`, and a thin `Mobius` app host. These are proposed names, not existing APIs. -Core owns typed values, revision/progress policy, local storage, provider protocols, GitHub transport, and sync policy in focused source directories. UI owns observable presentation, Broadway styling, code-rendering adapters, and navigation. The process composition root creates one runtime and injects it into each scene. Views do not open stores or create shared services. +Core owns typed workspace/child identities, revision/progress policy, local storage, provider protocols, GitHub transport, and sync policy in focused source directories. UI owns observable presentation, Broadway styling, code-rendering adapters, and navigation. Outer scene identity, logical workspace identity, and child-view identity are distinct. The process composition root creates one runtime and injects it into each scene. Views do not open stores or create shared services. The earlier candidate store is a serial actor with an atomically replaced, versioned metadata file, separate from evictable source blobs and indexes. Its concrete model and technology remain provisional until the mockup is evaluated. Stable identities, honest errors, and preservation of accepted user work remain constraints for later refinement. @@ -150,7 +151,9 @@ final class MobiusRuntime { final class WorkspaceModel { let workspaceID: Workspace.ID let runtime: MobiusRuntime - var presentation: WindowPresentation // Device-local. + var presentation: WorkspacePresentation // Local arrangement and focused child. + // Child navigation is keyed by WorkspaceChild.ID, not document kind. + // Outer scenes/tabs refer to this workspace identity. } actor WorkspaceStore { @@ -167,9 +170,9 @@ actor WorkspaceStore { | Order | Plan | Deliverable | | --- | --- | --- | -| 1 | [01a — Workspace prototype](01a-workspace-prototype.md) | Lightweight interactive mockup of separate PR workspaces and remaining work across phone, tablet, and desktop layouts. | +| 1 | [01a — Workspace prototype](01a-workspace-prototype.md) | Lightweight interactive mockup of logical PR workspaces, their child windows, and remaining work across phone, tablet, and desktop layouts. | | 2 | [01 — Review-state foundation](01-review-state-foundation.md) | Durable workspace/progress state informed by prototype evidence. | -| 3 | [02 — Application workspace](02-application-workspace.md) | Native app with tabs, scenes, file-top resumption, and accessible navigation. | +| 3 | [02 — Application workspace](02-application-workspace.md) | Native app with workspace tabs/windows, multiple child views, arrangement/focus restoration, file-top review resumption, and accessible navigation. | | 4 | [03 — GitHub and revision comparison](03-github-and-revision-comparison.md) | Authenticated PR reading and per-file remaining-work comparisons. | | 5 | [04 — Repository exploration](04-repository-exploration.md) | Revision-bound browsing and path/text search alongside each review. | | 6 | [05 — Review feedback](05-review-feedback.md) | Comments and reviews with retained drafts and uncertain-outcome recovery. | @@ -180,7 +183,7 @@ actor WorkspaceStore { ## Planning horizon -- Detail now: [01a](01a-workspace-prototype.md), selected in Q-16–Q-18 to explore all three layouts through a lightweight interactive mockup. +- Detail now: [01a](01a-workspace-prototype.md), selected in Q-16–Q-18 to explore all three layouts through a lightweight interactive mockup; the current iteration addresses the workspace/window feedback and Q-19–Q-21. - Later selected work: 01–07 are outlines. The earlier claim that 01 was ready is superseded; its model must follow prototype learning. - Next horizon review: Record prototype observations and the user's feedback, integrate changed decisions, then refine 01 and reconsider 02/03. Technical decisions Q-08–Q-12 retain their recorded gates. - First-release gate: **01–06 together**, preceded by prototype learning. The mockup does not deliver or waive native platform, GitHub feedback, persistence, or sync requirements. @@ -198,6 +201,9 @@ actor WorkspaceStore { | 2026-11-14 | Resume at the top of the last review file. | Q-14 follow-up. | | 2026-11-14 | Remaining work uses each reviewed file's last-reviewed version and includes the full PR diff for unreviewed files. Full PR diffs remain available. | Q-15 follow-up; replaces the earlier PR-wide explicit-checkpoint proposal. | | 2026-11-14 | Start with a lightweight interactive mockup exploring phone, tablet, and desktop together. | Q-16–Q-18; replaces foundation-first sequencing. | +| 2026-11-14 | Separate a logical PR workspace from its outer tab/window presentation and from its child windows. Allow multiple child views; “fork” was a typo for “view.” | First-artifact feedback, Q-19. | +| 2026-11-14 | Explore floating, tiled, docked, or tabbed arrangements where useful; choose a bounded set for the mockup without fixing every native platform's controls. | Q-20: “All of the above if needed.” | +| 2026-11-14 | Return to the workspace's arrangement and last-focused child. File-top review resumption still applies when a review child is resumed. | Q-21; refines Q-14 without forcing review focus. | | 2026-11-14 | Proposed: sync semantic workspace data and drafts; keep native geometry/focus and full code caches local. | R-07/R-09. | | 2026-11-14 | Proposed: atomic metadata storage, not a bounded journal as the only copy of user work. | JournalKit contract. | @@ -218,13 +224,16 @@ actor WorkspaceStore { | [Q-11](#q-11) | deferred | Catalyst validation and release distribution/signing? | 02, 06 | Specify compile/runtime validation in 02; resolve distribution in 06. | | [Q-12](#q-12) | deferred | What can an embedded reviewer prove about a build and PR? | 07 | Blocks a product promise; choose a synthetic host after standalone delivery. | | [Q-13](#q-13) | closed | How is concurrent review work grouped? | R-02, 01a, 01, 02, 04 | One independent workspace per PR. | -| [Q-14](#q-14) | closed | What should resuming a review restore? | R-03, 01a, 01, 02, 06 | Return to the review file and start at its top. | +| [Q-14](#q-14) | closed | What should resuming a review restore? | R-03, 01a, 01, 02, 06 | Start a resumed review file at its top; workspace focus follows Q-21. | | [Q-15](#q-15) | closed | How should new edits and unfinished work appear within one PR? | R-04, 01a, 01, 03, 05, 06 | Per-file last-reviewed versions; full PR diffs for unreviewed files and as an available alternate view. | | [Q-16](#q-16) | closed | What should the first deliverable validate? | Execution order, 01a, 01, 02 | Interactive prototype with sample PRs before durable state work. | | [Q-17](#q-17) | closed | Which layouts should the prototype explore? | 01a | Phone, tablet, and desktop together. | | [Q-18](#q-18) | closed | What form should the prototype take? | 01a | Lightweight interactive mockup for quick iteration. | +| [Q-19](#q-19) | closed | Does “fork” mean another view or an editable code copy? | R-02/R-05, X-02/X-04, 01a, 01, 02, 04, 07 | It was a typo for “view”; workspace/child distinction integrated without code authoring. | +| [Q-20](#q-20) | closed | How should child windows be arranged? | R-02/R-10, 01a, 02 | All proposed modes may be useful; bounded experiment method reviewed. Native defaults await evidence. | +| [Q-21](#q-21) | closed | Restore arrangement and last focus, or always bring review forward? | R-03/R-07, 01a, 01, 02, 04, 06 | Restore arrangement and last-focused child; file-top behavior applies when resuming a review child. | -User answers came from this chat on 2026-11-14. Q-13–Q-18 refine the original answers without reopening the selected platforms, provider, or iCloud scope. The current horizon is prototype evaluation; detailed navigation and layout are hypotheses to explore through it. +User answers came from this chat on 2026-11-14. Q-13–Q-21 refine the original answers without reopening the selected platforms, provider, or iCloud scope. The current horizon is prototype evaluation; detailed navigation and layout remain hypotheses to explore through it. ### Q-01 @@ -308,12 +317,14 @@ User answers came from this chat on 2026-11-14. Q-13–Q-18 refine the original - Answer/source: The user selected a workspace per PR. The Q-15 clarification also establishes that separate PRs are separate reviews, with a stack connection largely an informational note. - Integration: R-02, product concepts, 01a, and the workspace ownership and navigation in 01/02/04/06. - History: Asked, answered, integrated, and closed after checking that documents and progress do not merge across PRs. This does not require implementing GitHub stack discovery. +- Refinement: First-artifact feedback distinguishes the logical workspace, its outer tab/window presentation, and its child windows; Q-19–Q-21 refine this hierarchy without changing one workspace per PR. ### Q-14 - Answer/source: Initially uncertain between a point in a file and the file reached in order. The follow-up answer was to start from the top of the file. -- Integration: R-03, resume-file concept, 01a/01/02/06. Precise in-file restoration and reviewed-range tracking are not first-release requirements. +- Integration: R-03, resume-file concept, 01a/01/02/06. Precise in-file restoration and reviewed-range tracking are not first-release requirements. With multiple review children, each retains its selected file. - History: Kept open after the tentative answer; closed after the file-top preference was integrated. Reading or returning to a file does not itself mark it reviewed. +- Refinement: Q-21 separates returning to a workspace from resuming a review child. It supersedes the first artifact's forced-review focus; file-top resumption remains the review behavior. ### Q-15 @@ -339,21 +350,40 @@ User answers came from this chat on 2026-11-14. Q-13–Q-18 refine the original - Integration: 01a produces a self-contained browser artifact; native UIKit targets, persistent stores, authentication, and CloudKit remain later work. - History: Asked, answered, integrated, and closed after checking prototype scope and acceptance. Browser technology is an implementation choice for the mockup, not the production app architecture. +### Q-19 + +- Answer/source: After evaluating the first artifact, the user clarified that “fork” was a typo for “view.” The accompanying feedback asks for logical workspaces presentable as tabs or windows, with several windows inside each for research, previews, code review, and simulation context. +- Integration: R-02/R-05, product concepts, 01/02/04/07, and the second iteration of 01a. Child identity and navigation are separate from workspace review progress. X-02/X-04 remain in force; no code-copy/editing feature follows from the typo. +- History: Answered 2026-11-14, integrated and closed after the iteration-2 consistency review below. Preserve the first artifact and its evidence at `2e3653877`; its one-view-per-kind behavior does not satisfy this correction. + +### Q-20 + +- Answer/source: “All of the above if needed” in response to floating/tiling, docked splits/tabs, or tiled arrangements. +- Integration: The user delegates useful arrangement choices to the prototype. 01a will try a bounded set across three viewports; 02 retains native defaults and interaction detail for refinement. This does not require a complete desktop window manager in the browser experiment. +- History: Answered 2026-11-14, integrated and closed after reviewing the bounded experiment method and keeping native defaults provisional. + +### Q-21 + +- Answer/source: Restore arrangement and last-focused window when returning to a workspace. +- Integration: R-03, discovery scenario, product concepts, 01/02/04/06, and 01a. A source, research, or preview child can remain focused on return. Q-14 still applies when the reviewer resumes a review child. Device-specific geometry/focus versus synced semantic state remains subject to Q-09's later policy refinement. +- History: Answered 2026-11-14, integrated and closed after the resume-path consistency review below; no remaining product question blocks the revised browser method. + ## Plan review - Initial review: 2026-11-14 against `b629d56ac44a3f2a5ea59c3d6ae9cd5401f37674`, covering the original eight files. Its readiness finding for 01 is superseded by Q-13–Q-18 and prototype-first sequencing. - Initial findings and disposition (historical): Aligned the overview's store signature with 01's then-proposed version-checked save; corrected 02's runtime ownership claim; added receipt-isolation and persistence-recovery scenarios; assigned app attribution to 02. Brought Q-09's submission-ownership decision forward to 05 and added its definitive rejection transition. No implementation tests ran; 01's detailed design is now deferred until prototype evaluation. - Revision review: Integrated Q-13–Q-18 across the nine-file series, including workspace isolation, file-top resumption, per-file baselines, and prototype-first dependencies. Reviewed 01a for executable experiment detail; 01–07 remain outlines. -- Readiness: 01a is ready for a subsequent execution request. Prototype interaction findings and user feedback are prerequisites to refining 01. A negative prototype result can lead to a revised design; it does not establish production feasibility. -- Verification: All 118 local Markdown links and anchors resolve across nine files; fences are balanced; the eight-plan dependency graph is acyclic; all 12 requirements have implementing owners; `git diff --check` passes. These checks validate the plan, not the proposed app. -- Validation limits: No prototype, device test, product API write, or sync experiment has run. Swift is pseudocode. Mermaid was inspected as source; no local renderer was found. `./test` and `./swiftformat --lint` were skipped because only planning Markdown changed. +- Iteration-2 review: 2026-11-14 against parent `68477fe625` plus this revision and the implementation branch's 01a method at `68926adfd`. Reviewed all affected production outlines and the current experiment method against Q-19–Q-21. Corrected the conflation of workspace, outer presentation, and child identity; moved review-file selection into each child; separated return focus from review resumption; and kept preview execution and cross-device presentation policy at their existing refinement gates. Multiple views share PR review evidence without sharing navigation. No remaining consistency or browser-method readiness finding was identified. +- Readiness: 01a's implementation branch records the material correction as `executing` → `draft`, then a reviewed `ready` → `executing` transition under existing authorization. Its pre-execution copy here is historical. Iteration-2 interaction evidence and user evaluation are still required before refining 01; native plans 01–07 remain outlines. +- Verification: All 129 local Markdown links and anchors resolve across nine planning-branch files; fences are balanced; the eight-plan dependency graph is acyclic; all 12 requirements have implementing owners; `git diff --check` passes. The revised 01a method was also inspected on its owning branch. These checks validate the plan, not the proposed app. +- Validation limits: First-pass browser evidence is retained in PR #500 and does not validate the corrected model. Revised prototype runtime checks are pending. No native device test, product API write, or sync experiment has run. Swift is pseudocode. Mermaid was inspected as source; no local renderer was found. `./test` and `./swiftformat --lint` were skipped for this planning revision because only Markdown changed. ## Review and delivery - Plan review: [PR #497](https://github.com/kyleve/Stuff/pull/497), ready for review. [STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app) remains In Review until merge and acceptance verification. -- Implementation: 01a is authorized and running in an isolated background worktree. Native plans 01–07 have not started. -- Review focus: Independent PR workspaces; per-file remaining work and full-diff access; file-top resumption; prototype learning before the durable model; sync as a release gate. +- Implementation: [PR #500](https://github.com/kyleve/Stuff/pull/500) and [STU-330](https://linear.app/kve/issue/STU-330/prototype-mobius-review-workspaces) own 01a's artifact, current method, and evidence. Its second iteration is authorized and running in an isolated background worktree. Native plans 01–07 have not started. +- Review focus: Logical PR workspaces independent of outer tabs/windows; multiple child views with independent navigation; arrangement/last-focus restoration; per-file remaining work and full-diff access; file-top review resumption; prototype learning before the durable model; sync as a release gate. ## Outcome -The revised series starts with the lightweight, three-layout mockup in 01a, now authorized for background execution. Plans 01–07 remain outlines informed by later evidence and production discussion. +Q-19–Q-21 define the second prototype iteration: logical workspaces own multiple child windows, outer tab/window presentation preserves them, and returning restores arrangement and last focus. The background experiment remains in progress. Plans 01–07 remain outlines informed by its evaluation and further production discussion. From b2e9662a0090f2fa5c17b60f08568e83f01b5097 Mon Sep 17 00:00:00 2001 From: Kyle Van Essen Date: Sat, 14 Nov 2026 20:57:43 -0500 Subject: [PATCH 06/12] Record Mobius content priorities and compact prototype iteration --- .../02-application-workspace.md | 5 ++- Plans/2026-11-14-mobius/README.md | 45 +++++++++++++------ 2 files changed, 36 insertions(+), 14 deletions(-) diff --git a/Plans/2026-11-14-mobius/02-application-workspace.md b/Plans/2026-11-14-mobius/02-application-workspace.md index a6697f168..fa36524d5 100644 --- a/Plans/2026-11-14-mobius/02-application-workspace.md +++ b/Plans/2026-11-14-mobius/02-application-workspace.md @@ -29,6 +29,8 @@ Create the Core runtime once in the process composition root. Scene presentation Use 01a's evaluated interactions to distinguish switching PR workspaces from selecting, opening, or arranging children inside one PR. Q-20 allows floating, tiling, docking, or tabs where useful; choose native defaults and platform affordances during refinement. Layouts and labels from the mockup remain candidates until validated natively. Mac outer windows use system scene APIs, with app-specific menu and shortcut routing through the focused workspace to its focused child. Separate child closure, closing a native window, and deleting a workspace. Restore arrangement and last-focused child on return; resuming a review child starts its file at the top. Exact review offsets are not required. +Apply the accepted [presentation-density decision](README.md#presentation-density): compact workspace identity and view controls, with full PR metadata and less frequent arrangement actions available on demand. Keep the active content title, actual comparison meaning, immediate review actions, and relevant warnings clear. On phone, a child selector can also provide the active view title. Reclaim space through fewer rows and repeated labels while preserving readable text, touch targets, accessible disclosures, keyboard commands, and focus return. Prototype-only Canvas/Reset/Simulate Push controls do not become production chrome. + ```mermaid flowchart LR Root["Proposed Mobius composition root"] --> Runtime["Proposed runtime using 01 store"] @@ -63,7 +65,7 @@ Declare Mobius's attribution inputs and bundled report through CreditKit's exist ## Refinement trigger - Trigger: 01a's feedback is integrated and 01 supplies actual state/persistence interfaces. -- Evidence needed: Working Core types, renderer/layout probe results, dependency closure, an explicit Catalyst build/runtime procedure, and an accessible tab/window interaction specification. +- Evidence needed: Working Core types, renderer/layout probe results, dependency closure, an explicit Catalyst build/runtime procedure, and an accessible tab/window interaction specification. Include usable content-space and moved-control reachability evidence at standard and accessibility layouts; a compact screenshot alone does not prove access to the hidden controls. - Next action: Read the applicable UI/module/tooling contracts, expand this file into executable steps and acceptance criteria, and review it before implementation. Keep the first runtime demo synthetic and repeatable. ## Decisions and revisions @@ -74,6 +76,7 @@ Declare Mobius's attribution inputs and bundled report through CreditKit's exist | 2026-11-14 | Keep platform scene presentation local while workspace identity persists. | Overview design proposal. | | 2026-11-14 | Adopt per-PR grouping and file-top resumption after the lightweight mockup is evaluated. | Q-13/Q-14, Q-16–Q-18. | | 2026-11-14 | Restore logical workspaces with multiple child windows independently of outer tab/window presentation; retain arrangement and last focus. | First-artifact feedback and [Q-19–Q-21](README.md#q-19). | +| 2026-11-14 | Prioritize useful content with compact workspace/view chrome and details on demand, preserving comparison meaning and accessible actions. | Accepted [iteration-2 density feedback](README.md#presentation-density); evaluated controls follow 01a iteration 3. | ## Resume point diff --git a/Plans/2026-11-14-mobius/README.md b/Plans/2026-11-14-mobius/README.md index 7510c54bb..dfb562ece 100644 --- a/Plans/2026-11-14-mobius/README.md +++ b/Plans/2026-11-14-mobius/README.md @@ -4,12 +4,12 @@ - Updated: 2026-11-14; initial repository baseline `b629d56ac44a3f2a5ea59c3d6ae9cd5401f37674`; merged main through `96f5bf0f1685de259d7ff080842b8092f9a950d2` in `68477fe625784a1a1e68c0115d7e42cc63166692`. - Operation: Execute 01a in a background agent while continuing production-plan discussion here. Native implementation is not requested. -- Requested scope and source: The user's 2026-11-14 request, Q-01–Q-07 answers, Q-13–Q-18 follow-ups, and first-prototype feedback clarified by Q-19–Q-21; see [question history](#questions-and-resolutions). -- Stage: Workspace/window correction integrated and reviewed; the second prototype iteration is executing in the background. -- Completed: Initial research and publication in [PR #497](https://github.com/kyleve/Stuff/pull/497); first browser artifact in [PR #500](https://github.com/kyleve/Stuff/pull/500) at `2e3653877bf141964805d417eac0b94c03a24c6a`. The user evaluated it and identified a material workspace-model correction. [STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app) tracks plan delivery; [STU-330](https://linear.app/kve/issue/STU-330/prototype-mobius-review-workspaces) tracks the experiment. -- Pending: Validate the revised prototype interaction and obtain user evaluation; PR review and merge. Q-08–Q-12 remain at their technical refinement gates. The first artifact is evidence to retain, not acceptance of the corrected model. -- Execution authorization: The user requested background execution of 01a on 2026-11-14 and then requested the workspace correction. The prototype runs on `codex/mobius-prototype` in `/Users/kve/.codex/worktrees/mobius-prototype/Stuff`; it includes the main merge above. Its branch owns the artifact and 01a execution evidence; this branch owns the overview and production-plan discussion. -- Next action: The background agent implements and validates the [current 01a execution contract](https://github.com/kyleve/Stuff/blob/codex/mobius-prototype/Plans/2026-11-14-mobius/01a-workspace-prototype.md#iteration-2-readiness-and-execution), preserving first-iteration evidence, then returns the revised artifact for user evaluation. The 01a copy on the planning branch is its pre-execution baseline; the implementation branch owns subsequent method revisions and execution status. Native plans remain outlines. +- Requested scope and source: The user's 2026-11-14 request, Q-01–Q-21 discovery, and accepted feedback to reduce the prototype's headers and subheaders; see [question history](#questions-and-resolutions) and [presentation density](#presentation-density). +- Stage: Third prototype iteration in progress under explicit background-execution authorization. +- Completed: Initial research and publication in [PR #497](https://github.com/kyleve/Stuff/pull/497); second browser artifact in [PR #500](https://github.com/kyleve/Stuff/pull/500), artifact/evidence commit `e1c1059cf28a2954a0513d2514e7d0b7be9c34dd`, publication record `66c7da62331873548f0231c9da666a555bf306fb`. Three-size browser checks and independent review passed; the user evaluated it as improved but found excessive chrome. [STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app) tracks plan delivery; [STU-330](https://linear.app/kve/issue/STU-330/prototype-mobius-review-workspaces) tracks the experiment. +- Pending: Implement and validate compact chrome, publish fresh evidence, notify the user, and collect the next evaluation. Q-08–Q-12 remain at their technical refinement gates. Prior browser evidence is retained; it does not validate the changed controls or density. +- Execution authorization and ownership: The user approved the compact-chrome proposal and explicitly requested a subagent rebuild and completion notice. `/root/mobius_prototype` owns `Prototype/**` and 01a in `/Users/kve/.codex/worktrees/mobius-prototype/Stuff` on `codex/mobius-prototype`; the coordinating agent owns the overview, affected production outlines, and the user-facing completion message. Coordinate shared stack mutations at clean worktree points. Native implementation remains outside scope. +- Next action: Implement and validate the [current 01a execution contract](https://github.com/kyleve/Stuff/blob/codex/mobius-prototype/Plans/2026-11-14-mobius/01a-workspace-prototype.md), preserving previous iteration evidence. The worker returns the artifact, tested/published revision, checks, and remaining limits or blocker; the coordinator reconciles the record and tells the user when the rebuild is ready or cannot finish. The 01a copy on the planning branch is its pre-execution baseline; the implementation branch owns subsequent method revisions and execution status. Native plans remain outlines. ## Outcome and scope @@ -36,7 +36,7 @@ Embedding the reviewer inside an owning app, with a possible live execution surf ## Requirements -R-01–R-07 and R-12 derive from the user's product choices. R-08–R-11 support repository contracts and correctness. Design details are proposals unless identified as user decisions. +R-01–R-07 and R-12 derive from the user's product choices. R-08–R-11 support repository contracts and correctness; R-10 also incorporates the accepted presentation-density direction. Design details are proposals unless identified as user decisions. | ID | Required behavior or constraint | Story | Implementing plan | | --- | --- | --- | --- | @@ -49,7 +49,7 @@ R-01–R-07 and R-12 derive from the user's product choices. R-08–R-11 support | R-07 | Resume workspace contents, child-view navigation, progress, and draft work through private iCloud sync on the same Apple ID. Keep device window placement local and expose sync state; refine cross-device presentation policy under Q-09. | US-02, US-06 | [01](01-review-state-foundation.md) supplies identities; [06](06-icloud-resume-and-release.md) delivers sync | | R-08 | Preserve original failures, last usable data, and incomplete coverage. Older requests cannot overwrite active state. Missing history cannot imply “reviewed” or “no changes.” | US-07 | [01](01-review-state-foundation.md), [03](03-github-and-revision-comparison.md), [04](04-repository-exploration.md), [05](05-review-feedback.md), [06](06-icloud-resume-and-release.md) | | R-09 | Scope data by account and repository identity. Keep credentials in device-local Keychain; do not sync them or full repository caches. Protect private code and draft text from diagnostic export. | US-07 | [01](01-review-state-foundation.md), [03](03-github-and-revision-comparison.md), [06](06-icloud-resume-and-release.md) | -| R-10 | Support touch, keyboard, VoiceOver, accessibility text sizes, long lines, and large diffs. Define measured rendering/indexing budgets before the corresponding plan becomes ready. | US-01, US-04, US-06 | [02](02-application-workspace.md), [03](03-github-and-revision-comparison.md), [04](04-repository-exploration.md) | +| R-10 | Prioritize code and preview content with compact workspace/view controls and details on demand, while keeping identity, comparison meaning, immediate actions, and relevant warnings clear. Preserve readable text and accessible touch/keyboard/VoiceOver interaction, accessibility text sizes, long lines, and large diffs. Define measured rendering/indexing budgets before the corresponding plan becomes ready. | US-01, US-04, US-06 | [01a](01a-workspace-prototype.md) explores density; [02](02-application-workspace.md), [03](03-github-and-revision-comparison.md), [04](04-repository-exploration.md) deliver it | | R-11 | Integrate module docs, manifests, tests, architecture boundaries, attribution, and CI. Release acceptance requires evidence on all three destinations and real cross-device sync. | Supporting constraint | [01](01-review-state-foundation.md), [02](02-application-workspace.md), [06](06-icloud-resume-and-release.md) | | R-12 | Evaluate a host-injected embedded reviewer and bounded live-context action; report feasibility and limitations without promising arbitrary PR execution. | US-08 | [07](07-embedded-review-experiment.md) | @@ -100,6 +100,23 @@ Within PR 42, mark `Parser.swift` reviewed at version 1 and leave `Store.swift` The first deliverable is a lightweight interactive mockup with phone, tablet, and desktop layouts. The first artifact limited child views by kind and forced review focus on return. The user rejected that flattening; the second iteration explores the corrected hierarchy, multiple view instances, and useful tiled, floating, or compact arrangements. The user allows arrangement modes as needed; exact controls and native platform defaults remain hypotheses. See [01a](01a-workspace-prototype.md). A mockup result will not establish native platform, persistence, provider, sync, or execution feasibility. +### Presentation density + +The user evaluated iteration 2 and accepted the following direction on 2026-11-14. Its stacked headings delayed code and preview content until roughly halfway down the inspected captures. Iteration 3 should reclaim that space through fewer rows and less repetition while preserving readable text, touch targets, and the workspace hierarchy. + +| Information | Presentation | +| --- | --- | +| Short workspace name and PR number | Compact workspace bar with access to switching and adding views. | +| Active child/file title | Compact view control; on phone the child selector can also supply the title. Avoid repeating kind/ordinal labels where title and icon suffice. | +| Current comparison and immediate review actions | Keep full PR diff versus new edits since a reviewed version understandable. Keep the explicit review action accessible. | +| Full PR title, author, branches, description, exact revision details | Accessible details/disclosure. Preserve enough repository identity to distinguish ambiguous names. | +| Arrangement and less frequent actions | Menus or disclosures; retain the existing capabilities and keyboard/focus behavior. | +| Prototype Canvas, Reset, and Simulate Push | Collapsible prototype controls with a small persistent sample/simulated indicator. | +| Teaching copy and repeated ownership/status text | Remove from permanent chrome; keep useful guidance in help or the walkthrough. | +| Missing history, stale content, and other consequential conditions | Show when relevant; compact chrome must not conceal a failure or change comparison meaning. | + +The target is a compact workspace bar and view toolbar with useful content immediately below. This is an information-priority decision, not a fixed pixel-height limit for native or accessibility layouts. Record comparable before/after content-space evidence across the three viewport sizes, and recheck reachability and focus for controls moved into disclosures. [02](02-application-workspace.md) carries this into native refinement; the prototype's exact controls remain subject to evaluation. + ### Product concepts - **Workspace:** the logical owner of one PR's child windows, progress, and drafts. Its identity does not depend on being presented as a workspace tab or outer window. Another PR has a separate workspace, including when the PRs belong to a stack. @@ -204,6 +221,7 @@ actor WorkspaceStore { | 2026-11-14 | Separate a logical PR workspace from its outer tab/window presentation and from its child windows. Allow multiple child views; “fork” was a typo for “view.” | First-artifact feedback, Q-19. | | 2026-11-14 | Explore floating, tiled, docked, or tabbed arrangements where useful; choose a bounded set for the mockup without fixing every native platform's controls. | Q-20: “All of the above if needed.” | | 2026-11-14 | Return to the workspace's arrangement and last-focused child. File-top review resumption still applies when a review child is resumed. | Q-21; refines Q-14 without forcing review focus. | +| 2026-11-14 | Use compact workspace/view chrome, details on demand, and collapsible prototype controls; retain comparison meaning, warnings, readable text, and accessible actions. | User's iteration-2 feedback and explicit acceptance of the [presentation-density proposal](#presentation-density). | | 2026-11-14 | Proposed: sync semantic workspace data and drafts; keep native geometry/focus and full code caches local. | R-07/R-09. | | 2026-11-14 | Proposed: atomic metadata storage, not a bounded journal as the only copy of user work. | JournalKit contract. | @@ -374,16 +392,17 @@ User answers came from this chat on 2026-11-14. Q-13–Q-21 refine the original - Initial findings and disposition (historical): Aligned the overview's store signature with 01's then-proposed version-checked save; corrected 02's runtime ownership claim; added receipt-isolation and persistence-recovery scenarios; assigned app attribution to 02. Brought Q-09's submission-ownership decision forward to 05 and added its definitive rejection transition. No implementation tests ran; 01's detailed design is now deferred until prototype evaluation. - Revision review: Integrated Q-13–Q-18 across the nine-file series, including workspace isolation, file-top resumption, per-file baselines, and prototype-first dependencies. Reviewed 01a for executable experiment detail; 01–07 remain outlines. - Iteration-2 review: 2026-11-14 against parent `68477fe625` plus this revision and the implementation branch's 01a method at `68926adfd`. Reviewed all affected production outlines and the current experiment method against Q-19–Q-21. Corrected the conflation of workspace, outer presentation, and child identity; moved review-file selection into each child; separated return focus from review resumption; and kept preview execution and cross-device presentation policy at their existing refinement gates. Multiple views share PR review evidence without sharing navigation. No remaining consistency or browser-method readiness finding was identified. -- Readiness: 01a's implementation branch records the material correction as `executing` → `draft`, then a reviewed `ready` → `executing` transition under existing authorization. Its pre-execution copy here is historical. Iteration-2 interaction evidence and user evaluation are still required before refining 01; native plans 01–07 remain outlines. -- Verification: All 129 local Markdown links and anchors resolve across nine planning-branch files; fences are balanced; the eight-plan dependency graph is acyclic; all 12 requirements have implementing owners; `git diff --check` passes. The revised 01a method was also inspected on its owning branch. These checks validate the plan, not the proposed app. -- Validation limits: First-pass browser evidence is retained in PR #500 and does not validate the corrected model. Revised prototype runtime checks are pending. No native device test, product API write, or sync experiment has run. Swift is pseudocode. Mermaid was inspected as source; no local renderer was found. `./test` and `./swiftformat --lint` were skipped for this planning revision because only Markdown changed. +- Iteration-3 review: 2026-11-14 against parent `fcee86b3b`, iteration-2 artifact `e1c1059cf28`, and the revised 01a method on the implementation branch. The accepted information priorities are integrated into R-10, the shared decision, and 02's native refinement. The method preserves comparison truth and all existing capabilities, repeats moved-control/focus checks, and requires matched content-space evidence. Background ownership and completion reporting are explicit. No remaining consistency or browser-method readiness finding was identified; native implementation and third-round acceptance remain pending. +- Readiness: 01a's implementation branch owns the reviewed iteration methods, status transitions, and evidence; its pre-execution copy here is historical. Iteration-2 checks and user evaluation are recorded. The compact-chrome correction requires another bounded iteration and evaluation before refining 01; native plans 01–07 remain outlines. +- Verification: All 135 local Markdown links and anchors resolve across nine planning-branch files; fences are balanced; the unchanged eight-plan dependency graph is acyclic; all 12 requirements retain implementing owners; `git diff --check` passes. The revised 01a method was also inspected on its owning branch. These checks validate the plan, not the proposed app. +- Validation limits: Earlier browser evidence is retained in PR #500 and does not validate iteration 3's changed chrome or disclosure controls. Its runtime checks are pending. No native device test, product API write, or sync experiment has run. Swift is pseudocode. Mermaid was inspected as source; no local renderer was found. `./test` and `./swiftformat --lint` were skipped for this planning revision because only Markdown changed. ## Review and delivery - Plan review: [PR #497](https://github.com/kyleve/Stuff/pull/497), ready for review. [STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app) remains In Review until merge and acceptance verification. -- Implementation: [PR #500](https://github.com/kyleve/Stuff/pull/500) and [STU-330](https://linear.app/kve/issue/STU-330/prototype-mobius-review-workspaces) own 01a's artifact, current method, and evidence. Its second iteration is authorized and running in an isolated background worktree. Native plans 01–07 have not started. +- Implementation: [PR #500](https://github.com/kyleve/Stuff/pull/500) and [STU-330](https://linear.app/kve/issue/STU-330/prototype-mobius-review-workspaces) own 01a's artifact, current method, and evidence. Its third iteration is authorized in an isolated background worktree, with an explicit completion-reporting handoff. Native plans 01–07 have not started. - Review focus: Logical PR workspaces independent of outer tabs/windows; multiple child views with independent navigation; arrangement/last-focus restoration; per-file remaining work and full-diff access; file-top review resumption; prototype learning before the durable model; sync as a release gate. ## Outcome -Q-19–Q-21 define the second prototype iteration: logical workspaces own multiple child windows, outer tab/window presentation preserves them, and returning restores arrangement and last focus. The background experiment remains in progress. Plans 01–07 remain outlines informed by its evaluation and further production discussion. +The third prototype iteration preserves the logical workspace/child model and reduces permanent chrome according to the accepted presentation-density decision. The background experiment remains in progress. Plans 01–07 remain outlines informed by its evaluation and further production discussion. From 66b6c995e4f787ed364c8c8832a64a104ccaa15e Mon Sep 17 00:00:00 2001 From: Kyle Van Essen Date: Sat, 14 Nov 2026 21:15:20 -0500 Subject: [PATCH 07/12] Record verified compact Mobius prototype handoff --- Plans/2026-11-14-mobius/README.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/Plans/2026-11-14-mobius/README.md b/Plans/2026-11-14-mobius/README.md index dfb562ece..6603dafe7 100644 --- a/Plans/2026-11-14-mobius/README.md +++ b/Plans/2026-11-14-mobius/README.md @@ -5,11 +5,11 @@ - Updated: 2026-11-14; initial repository baseline `b629d56ac44a3f2a5ea59c3d6ae9cd5401f37674`; merged main through `96f5bf0f1685de259d7ff080842b8092f9a950d2` in `68477fe625784a1a1e68c0115d7e42cc63166692`. - Operation: Execute 01a in a background agent while continuing production-plan discussion here. Native implementation is not requested. - Requested scope and source: The user's 2026-11-14 request, Q-01–Q-21 discovery, and accepted feedback to reduce the prototype's headers and subheaders; see [question history](#questions-and-resolutions) and [presentation density](#presentation-density). -- Stage: Third prototype iteration in progress under explicit background-execution authorization. -- Completed: Initial research and publication in [PR #497](https://github.com/kyleve/Stuff/pull/497); second browser artifact in [PR #500](https://github.com/kyleve/Stuff/pull/500), artifact/evidence commit `e1c1059cf28a2954a0513d2514e7d0b7be9c34dd`, publication record `66c7da62331873548f0231c9da666a555bf306fb`. Three-size browser checks and independent review passed; the user evaluated it as improved but found excessive chrome. [STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app) tracks plan delivery; [STU-330](https://linear.app/kve/issue/STU-330/prototype-mobius-review-workspaces) tracks the experiment. -- Pending: Implement and validate compact chrome, publish fresh evidence, notify the user, and collect the next evaluation. Q-08–Q-12 remain at their technical refinement gates. Prior browser evidence is retained; it does not validate the changed controls or density. +- Stage: Third-iteration delivery handoff; user evaluation is the next product decision. +- Completed: The compact-chrome rebuild and matched captures are complete. Final-source browser scenarios pass at phone, tablet, and desktop sizes; fresh independent review has no actionable findings. The coordinator inspected the phone/desktop captures and verification record. [01a's iteration-3 record](https://github.com/kyleve/Stuff/blob/codex/mobius-prototype/Plans/2026-11-14-mobius/01a-workspace-prototype.md#iteration-3-implementation-and-evidence) owns the tested source hash, measurements, corrections, and publication details. Earlier iteration artifacts and evidence remain intact. [PR #497](https://github.com/kyleve/Stuff/pull/497)/[STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app) track plan delivery; [PR #500](https://github.com/kyleve/Stuff/pull/500)/[STU-330](https://linear.app/kve/issue/STU-330/prototype-mobius-review-workspaces) track the experiment. +- Pending: Finish the coordinated publication/reporting handoff recorded in 01a, then collect third-round user evaluation; PR review and merge remain. Q-08–Q-12 retain their technical refinement gates. Browser verification does not establish product acceptance or native feasibility. - Execution authorization and ownership: The user approved the compact-chrome proposal and explicitly requested a subagent rebuild and completion notice. `/root/mobius_prototype` owns `Prototype/**` and 01a in `/Users/kve/.codex/worktrees/mobius-prototype/Stuff` on `codex/mobius-prototype`; the coordinating agent owns the overview, affected production outlines, and the user-facing completion message. Coordinate shared stack mutations at clean worktree points. Native implementation remains outside scope. -- Next action: Implement and validate the [current 01a execution contract](https://github.com/kyleve/Stuff/blob/codex/mobius-prototype/Plans/2026-11-14-mobius/01a-workspace-prototype.md), preserving previous iteration evidence. The worker returns the artifact, tested/published revision, checks, and remaining limits or blocker; the coordinator reconciles the record and tells the user when the rebuild is ready or cannot finish. The 01a copy on the planning branch is its pre-execution baseline; the implementation branch owns subsequent method revisions and execution status. Native plans remain outlines. +- Next action: Complete the [01a delivery handoff](https://github.com/kyleve/Stuff/blob/codex/mobius-prototype/Plans/2026-11-14-mobius/01a-workspace-prototype.md#resume-point) and notify the user with the rebuilt demo and checks, then integrate their evaluation before refining 01. The 01a copy on the planning branch is its pre-execution baseline; the implementation branch owns subsequent method revisions and execution status. Native plans remain outlines. ## Outcome and scope @@ -395,14 +395,15 @@ User answers came from this chat on 2026-11-14. Q-13–Q-21 refine the original - Iteration-3 review: 2026-11-14 against parent `fcee86b3b`, iteration-2 artifact `e1c1059cf28`, and the revised 01a method on the implementation branch. The accepted information priorities are integrated into R-10, the shared decision, and 02's native refinement. The method preserves comparison truth and all existing capabilities, repeats moved-control/focus checks, and requires matched content-space evidence. Background ownership and completion reporting are explicit. No remaining consistency or browser-method readiness finding was identified; native implementation and third-round acceptance remain pending. - Readiness: 01a's implementation branch owns the reviewed iteration methods, status transitions, and evidence; its pre-execution copy here is historical. Iteration-2 checks and user evaluation are recorded. The compact-chrome correction requires another bounded iteration and evaluation before refining 01; native plans 01–07 remain outlines. - Verification: All 135 local Markdown links and anchors resolve across nine planning-branch files; fences are balanced; the unchanged eight-plan dependency graph is acyclic; all 12 requirements retain implementing owners; `git diff --check` passes. The revised 01a method was also inspected on its owning branch. These checks validate the plan, not the proposed app. -- Validation limits: Earlier browser evidence is retained in PR #500 and does not validate iteration 3's changed chrome or disclosure controls. Its runtime checks are pending. No native device test, product API write, or sync experiment has run. Swift is pseudocode. Mermaid was inspected as source; no local renderer was found. `./test` and `./swiftformat --lint` were skipped for this planning revision because only Markdown changed. +- Iteration-3 delivery review: The recorded final HTML hash is `f2adc670df7668d0c99d79f3ac0d9abeea3df701f56a53e1373de331c2eb274f`. Matched review-pane heights increased from 413 to 765 CSS pixels on desktop, 535 to 877 on tablet, and 216 to 648 on phone. Code text increased from 10 to 12 CSS pixels. Browser checks cover the retained review/workspace behavior and newly disclosed controls; independent review rechecked focus, accessible-title, dialog-lifecycle, and stacking corrections. No actionable finding remains. Full evidence stays in 01a rather than being duplicated here. +- Validation limits: Third-round user evaluation remains pending. No native device test, VoiceOver, product API write, real code execution, persistence, or sync experiment has run. Swift is pseudocode. Mermaid was inspected as source; no local renderer was found. `./test` and `./swiftformat --lint` were skipped for this planning revision because only Markdown changed; browser checks belong to the prototype branch. ## Review and delivery - Plan review: [PR #497](https://github.com/kyleve/Stuff/pull/497), ready for review. [STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app) remains In Review until merge and acceptance verification. -- Implementation: [PR #500](https://github.com/kyleve/Stuff/pull/500) and [STU-330](https://linear.app/kve/issue/STU-330/prototype-mobius-review-workspaces) own 01a's artifact, current method, and evidence. Its third iteration is authorized in an isolated background worktree, with an explicit completion-reporting handoff. Native plans 01–07 have not started. +- Implementation: [PR #500](https://github.com/kyleve/Stuff/pull/500) and [STU-330](https://linear.app/kve/issue/STU-330/prototype-mobius-review-workspaces) own 01a's artifact, current method, and evidence. The third iteration is built and verified; its delivery record owns publication and the explicit completion-reporting handoff. Native plans 01–07 have not started. - Review focus: Logical PR workspaces independent of outer tabs/windows; multiple child views with independent navigation; arrangement/last-focus restoration; per-file remaining work and full-diff access; file-top review resumption; prototype learning before the durable model; sync as a release gate. ## Outcome -The third prototype iteration preserves the logical workspace/child model and reduces permanent chrome according to the accepted presentation-density decision. The background experiment remains in progress. Plans 01–07 remain outlines informed by its evaluation and further production discussion. +The third prototype iteration preserves the logical workspace/child model and reduces permanent chrome according to the accepted presentation-density decision. The rebuild passes its browser checks and independent review; the experiment remains open for user evaluation. Plans 01–07 remain outlines informed by that evaluation and further production discussion. From 63a24de21b5f07b1bfd8976cfe621983b9e9bbdd Mon Sep 17 00:00:00 2001 From: Kyle Van Essen Date: Sat, 14 Nov 2026 21:38:57 -0500 Subject: [PATCH 08/12] docs(Mobius): plan grouped diffs and explicit PR skips --- .../01-review-state-foundation.md | 15 ++- .../02-application-workspace.md | 8 +- .../03-github-and-revision-comparison.md | 20 +++- .../04-repository-exploration.md | 5 +- Plans/2026-11-14-mobius/05-review-feedback.md | 7 +- .../06-icloud-resume-and-release.md | 12 ++- Plans/2026-11-14-mobius/README.md | 102 ++++++++++++++---- 7 files changed, 135 insertions(+), 34 deletions(-) diff --git a/Plans/2026-11-14-mobius/01-review-state-foundation.md b/Plans/2026-11-14-mobius/01-review-state-foundation.md index a396d2961..e9964b44c 100644 --- a/Plans/2026-11-14-mobius/01-review-state-foundation.md +++ b/Plans/2026-11-14-mobius/01-review-state-foundation.md @@ -6,7 +6,7 @@ ## Intended outcome -A `MobiusCore` library preserves independent logical PR workspaces, their child-view identities/navigation, per-file reviewed versions, and drafts across relaunch. Returning restores a workspace's arrangement and last-focused child. Resuming a review child starts at the top of its selected file. Remaining-work policy follows Q-15: new edits since each reviewed file's last-reviewed version, and the full PR diff for an unreviewed file, with full PR diffs available for either. +A `MobiusCore` library preserves independent logical PR workspaces, their child-view identities/navigation, per-file reviewed versions, explicit current skips, and drafts across relaunch. Returning restores a workspace's arrangement and last-focused child. Resuming a review child starts at the top of its selected file. Remaining-work policy follows Q-15 and Q-23/Q-24: new edits since each reviewed file's last-reviewed version, and the full PR diff for an unreviewed file, excluding valid current skips while keeping full PR diffs accessible. This is production groundwork after prototype learning. It does not itself deliver a native app, live GitHub integration, or iCloud sync. The earlier ready assessment and detailed implementation sequence are superseded by Q-13–Q-18; the prototype now comes first. @@ -16,6 +16,7 @@ This is production groundwork after prototype learning. It does not itself deliv | --- | --- | --- | | US-01, US-02 | R-02, R-03 | One workspace per PR; identified child views with independent navigation; workspace review progress/drafts and local arrangement/focus restoration. | | US-03 | R-04 | Immutable per-file review evidence and pure remaining-work evaluation. | +| US-10 | R-14 | Separate PR-local skip evidence and undo; changed/new files return without advancing reviewed baselines. | | US-06 | R-07 | Stable identities and versioned data that later sync can address. | | US-07 | R-08, R-09 | Honest failures, isolation by account/repository/PR, and preservation of accepted data. | | Supporting | R-11 | Module documentation, manifests, tests, and dependency guards. | @@ -30,6 +31,8 @@ Each workspace belongs to one typed account/repository/PR target, independent of A review child's resume value identifies its selected file; it does not persist a reviewed line range or require exact scroll restoration. Workspace restoration retains child arrangement and last-focused identity, so returning need not focus a review. Keep device presentation separate from semantic workspace contents; refine persistence and sync boundaries before fixing the schema. Per-file review evidence records the immutable comparison/version accepted by the explicit file-review action. A new push may make that file need review again, but must retain the earlier evidence needed to calculate its new edits. Unreviewed files have no reviewed baseline and show the full PR diff. +Keep [skip evidence](README.md#changes-by-kind-and-explicit-skipping) distinct from reviewed versions. Skipping captures a currently remaining file's comparison; the prototype's group action snapshots the currently remaining files in that group, never a rule excluding future members. Undo removes that skip without altering prior review evidence. Changed/new files return to remaining work while unchanged skips persist. A returning file uses its last actually reviewed baseline, including previously skipped edits, or the full PR diff if never reviewed. Group collapse, kind classification, and rich/source view choice are presentation and must not create review or skip evidence. Refine missing history, renamed files, comparison-context changes, and concurrent skip/undo/review mutations jointly with 03 before fixing identities or storage. + The previous candidate was a serial store actor with version-checked mutations and atomic metadata replacement, separate from evictable source blobs/indexes. Retain it as an option to evaluate after the prototype; do not implement its schema just because it was previously specified. Production identity, errors, migrations, concurrency, and recovery need executable refinement. ```mermaid @@ -37,13 +40,15 @@ flowchart LR Prototype["01a interaction evidence and user feedback"] --> Model["Proposed per-PR workspace model"] Intent["Explicit file-review action"] --> Evidence["Proposed per-file reviewed version"] Evidence --> Policy["Proposed remaining-work policy"] + Skip["Explicit current-comparison skip / undo"] --> Policy Revisions["Immutable current comparison and coverage"] --> Policy Model --> Children["Identified children with independent navigation"] Model --> Store["Candidate durable store"] Children --> Store Evidence --> Store + Skip --> Store Store --> Resume["Arrangement and focused child; review file at top"] - Policy --> Result["New edits / full unreviewed diff / unavailable"] + Policy --> Result["Remaining / reviewed / skipped, with comparison coverage"] ``` ```swift @@ -65,6 +70,7 @@ struct FileReviewReceipt: Codable, Sendable { let reviewedRevision: ReviewRevision } // Workspace owns one ReviewTarget, identified children, drafts, and receipts. +// Separate skip evidence refers to a current file comparison, not a new baseline. // Each review child retains its own ReviewResumeFile. // Presentation references workspace/child IDs; native scene IDs are separate. // File identity across renames and comparison context requires refinement. @@ -74,7 +80,7 @@ All named domain types are proposed. Receipt/content identity must distinguish b ## Questions and learning needed -- [01a](01a-workspace-prototype.md) must supply observed workspace/child navigation, restoration, and remaining-work behavior plus the user's feedback before the production model is fixed. Its first artifact exposed a flattened workspace model; Q-19–Q-21 require another iteration. Integrate further feedback before fixing identities or schema. +- [01a](01a-workspace-prototype.md) must supply evaluated workspace/child navigation, restoration, and remaining-work behavior before the production model is fixed. Its first artifact exposed a flattened workspace model; Q-19–Q-21 corrected that direction. Q-22–Q-24 add grouped changes and explicit skips for the fourth iteration. Integrate that feedback before fixing identities or schema. - Choose the persistence representation, mutation/version contract, migration behavior, and failure recovery from the evaluated model. The earlier atomic-file proposal remains an option. - [Q-09](README.md#q-09) owns distributed merge/account policy. Preserve stable identities and revision evidence; local mutation versions must not be presented as distributed causal clocks. - Keep original errors and accepted user work on failure. Missing storage may initialize an empty store; corrupt or unsupported storage must not be silently replaced with one. @@ -87,6 +93,8 @@ All named domain types are proposed. Receipt/content identity must distinguish b The eventual checks must demonstrate two independent PR workspaces reopening with their children, references, drafts, arrangements, and last-focused child; independent navigation in multiple children of the same kind; file-top review resumption; per-file new-edit/full-diff selection shared within the PR; preserved prior review evidence after a push; no cross-PR progress leakage; explicit baseline advancement; honest incomplete history; and failed/stale saves preserving accepted state. Changing outer presentation must preserve logical identities. Include real persistence round trips and controlled competing mutations. Use the matching Core tests, architecture checks, and formatting after targets exist; a zero-test pass is not acceptance. +Include individual/group skip, undo, relaunch, and a push with changed, unchanged, and newly introduced files. Assert separate remaining/reviewed/skipped counts and unchanged reviewed baselines. Cover stale actions from a child displaying an older comparison and competing skip/undo/review mutations; unavailable evidence must not produce a false reviewed or unchanged result. Classification and collapse alone must leave progress unchanged. + ## Decisions and revisions | Date | Decision | Source | @@ -95,6 +103,7 @@ The eventual checks must demonstrate two independent PR workspaces reopening wit | 2026-11-14 | Replace the checkpoint model with per-file reviewed versions; resume from the file top; keep one workspace per PR. | Q-13–Q-15. | | 2026-11-14 | Return this deliverable to outline and refine it after a lightweight, three-layout prototype. | Q-16–Q-18. | | 2026-11-14 | Distinguish workspace, child-view, route, and presentation identities; restore arrangement and last focus, with a selected file per review child. | First-artifact feedback and [Q-19–Q-21](README.md#q-19). | +| 2026-11-14 | Store current skips independently from reviewed versions; changed/new files return without resetting unrelated skips or advancing review evidence. | [Q-23](README.md#q-23)/[Q-24](README.md#q-24); exact production identities remain provisional. | ## Execution record diff --git a/Plans/2026-11-14-mobius/02-application-workspace.md b/Plans/2026-11-14-mobius/02-application-workspace.md index fa36524d5..33fc37ad7 100644 --- a/Plans/2026-11-14-mobius/02-application-workspace.md +++ b/Plans/2026-11-14-mobius/02-application-workspace.md @@ -17,6 +17,7 @@ Success is a native runtime demonstration with two independent PR workspaces, mu | US-01, US-02 | R-02, R-03 | Logical PR workspaces, outer tabs/windows, independent child navigation, arrangement/focus restoration, and file-top review resumption. | | US-06 | R-01 | iPhone/iPad app and Mac Catalyst windows, menus, and shortcuts. | | US-01, US-06 | R-10 | Accessible adaptive layout and keyboard/focus behavior. | +| US-09, US-10 | R-13, R-14 | Grouped change navigation with quieter groups collapsed, distinct progress counts, and explicit skip/undo using fixtures. | | Supporting | R-11 | Host/UI targets, docs, unit/image coverage, and Catalyst validation. | See [definitions and exclusions](README.md#requirements). X-03 and X-07 apply. Do not build a single disposable PR-detail flow and defer the workspace model; concurrency of reviews is this deliverable's purpose. Do not add live provider or CloudKit behavior here. @@ -31,6 +32,8 @@ Use 01a's evaluated interactions to distinguish switching PR workspaces from sel Apply the accepted [presentation-density decision](README.md#presentation-density): compact workspace identity and view controls, with full PR metadata and less frequent arrangement actions available on demand. Keep the active content title, actual comparison meaning, immediate review actions, and relevant warnings clear. On phone, a child selector can also provide the active view title. Reclaim space through fewer rows and repeated labels while preserving readable text, touch targets, accessible disclosures, keyboard commands, and focus return. Prototype-only Canvas/Reset/Simulate Push controls do not become production chrome. +Integrate the evaluated [changes-by-kind interaction](README.md#changes-by-kind-and-explicit-skipping): group the file list, initially collapse quieter groups, and expose concise remaining/reviewed/skipped counts with reachable files and undo. Collapse never changes progress. Each child retains its own selection and presentation while skip/review evidence belongs to the workspace. The bounded prototype uses “Skip remaining files” for a group's current remaining members; preserve that explicit scope when refining native actions. Typed content views and their source/metadata access must preserve comparison meaning without recreating large teaching headers. Initial native UI may use prepared projections; real format support, classification, and unavailable-content coverage depend on 03/Q-10. + ```mermaid flowchart LR Root["Proposed Mobius composition root"] --> Runtime["Proposed runtime using 01 store"] @@ -57,7 +60,7 @@ Declare Mobius's attribution inputs and bundled report through CreditKit's exist ## Questions and learning needed -- [Q-10](README.md#q-10): Select the code-text substrate and layout after measuring long lines, many documents, accessibility sizes, selection, and VoiceOver. Identify real latency/memory budgets and fixture sizes before readiness. +- [Q-10](README.md#q-10): Select the code-text substrate and layout after measuring long lines, many documents, accessibility sizes, selection, and VoiceOver. Include grouped lists and bounded rich/source projections without committing to the prototype's format catalog. Identify real latency/memory budgets and fixture sizes before readiness. - [Q-11](README.md#q-11): Specify CLI Catalyst compile coverage and a native window/menu smoke test. Existing `./test` cannot be assumed to target Catalyst. Extend repository tooling only where required, with its public-command tests and owning docs. - Integrate Q-13–Q-15 and Q-19–Q-21: logical workspaces, multiple identified children, outer presentation independent from contents, last-focus/arrangement restoration, and clear remaining-work/full-PR navigation. Existing scroll-restoration machinery does not establish a requirement to restore an exact review offset. - Refine close/detach/reopen behavior and any simultaneous presentations of one workspace before implementing them. The bounded mockup need not settle every native scene lifecycle rule. @@ -65,7 +68,7 @@ Declare Mobius's attribution inputs and bundled report through CreditKit's exist ## Refinement trigger - Trigger: 01a's feedback is integrated and 01 supplies actual state/persistence interfaces. -- Evidence needed: Working Core types, renderer/layout probe results, dependency closure, an explicit Catalyst build/runtime procedure, and an accessible tab/window interaction specification. Include usable content-space and moved-control reachability evidence at standard and accessibility layouts; a compact screenshot alone does not prove access to the hidden controls. +- Evidence needed: Working Core types, renderer/layout probe results, dependency closure, an explicit Catalyst build/runtime procedure, and an accessible tab/window interaction specification. Include usable content-space and moved-control reachability evidence at standard and accessibility layouts; a compact screenshot alone does not prove access to the hidden controls. Demonstrate mixed-kind navigation, quiet-group disclosure, skip/undo with distinct counts, unchanged independent child selection, and access to source or honest unavailable metadata. - Next action: Read the applicable UI/module/tooling contracts, expand this file into executable steps and acceptance criteria, and review it before implementation. Keep the first runtime demo synthetic and repeatable. ## Decisions and revisions @@ -77,6 +80,7 @@ Declare Mobius's attribution inputs and bundled report through CreditKit's exist | 2026-11-14 | Adopt per-PR grouping and file-top resumption after the lightweight mockup is evaluated. | Q-13/Q-14, Q-16–Q-18. | | 2026-11-14 | Restore logical workspaces with multiple child windows independently of outer tab/window presentation; retain arrangement and last focus. | First-artifact feedback and [Q-19–Q-21](README.md#q-19). | | 2026-11-14 | Prioritize useful content with compact workspace/view chrome and details on demand, preserving comparison meaning and accessible actions. | Accepted [iteration-2 density feedback](README.md#presentation-density); evaluated controls follow 01a iteration 3. | +| 2026-11-14 | Group changes by kind and keep lower-attention groups collapsed; make skip/undo explicit and separate from reviewed. | [Q-22](README.md#q-22)–[Q-24](README.md#q-24); evaluate concrete views in 01a iteration 4. | ## Resume point diff --git a/Plans/2026-11-14-mobius/03-github-and-revision-comparison.md b/Plans/2026-11-14-mobius/03-github-and-revision-comparison.md index 8c5861b5d..aeccf4374 100644 --- a/Plans/2026-11-14-mobius/03-github-and-revision-comparison.md +++ b/Plans/2026-11-14-mobius/03-github-and-revision-comparison.md @@ -8,6 +8,8 @@ Each workspace opens its own GitHub PR and discussion. A reviewer marks individual files reviewed, leaves, and returns after a push. Remaining work shows new edits since each reviewed file's last-reviewed version and the full PR diff for unreviewed files. Either file can open its full current PR diff. The app shows the revisions and completeness of the comparison it actually loaded. +Changes are grouped by kind with appropriate content views and source/metadata access. Explicit PR-local skips remove current comparisons from remaining work without marking them reviewed. New changes return; unchanged skips persist. Rich views must represent the same revisions and comparison scope as their source view. + Demonstrate ordinary pushes, force-push/rebase, base-branch movement, unchanged files, renamed/deleted files, unavailable old history, and paginated/limited responses. Honest unavailable history is an acceptable state; falsely reporting “nothing changed” is not. ## User stories and requirements @@ -18,6 +20,8 @@ Demonstrate ordinary pushes, force-push/rebase, base-branch movement, unchanged | US-05 | R-06 | Authenticated PR/diff/discussion reading; submission remains in 05. | | US-07 | R-08, R-09 | Credential/account boundaries, immutable snapshots, coverage, and stale-result control. | | US-01, US-06 | R-10 | Bounded diff loading/rendering with measured budgets. | +| US-09 | R-13 | Content classification and supported typed projections over revision-bound comparisons, with honest fallbacks. | +| US-10 | R-14 | Reconcile skip evidence against actual comparison changes while retaining reviewed baselines. | All [exclusions](README.md#not-required-and-explicitly-avoided) apply. Do not introduce Git authoring or treat GitHub's submitted-review/file-viewed state as Mobius's private progress. Support public and private repositories the selected identity can access; authorization failure must remain distinct from an empty PR list. @@ -34,7 +38,10 @@ flowchart LR Snapshot --> Diff["Proposed comparison engine"] Baseline["This PR file's last-reviewed version, if any"] --> Diff Diff --> Progress["ReviewProgress from 01"] - Progress --> UI["Workspace diff documents from 02"] + Skips["Current-comparison skip evidence from 01"] --> Progress + Diff --> Projection["Content-kind projections and source/metadata coverage"] + Progress --> UI["Grouped workspace diff documents from 02"] + Projection --> UI ``` ```swift @@ -49,7 +56,11 @@ protocol ReviewRepository: Sendable { GitHub PR-file/compare responses have documented limits; see [research](README.md#research-and-evidence). Treat them as useful metadata, not guaranteed complete manifests. Resolve immutable trees and blobs, traverse truncated trees by subtree, and retain coverage for every material omission. A refresh must not splice pages from different moving revisions. Bound retries if the PR changes while resolving it. -Re-evaluate exact file comparison identities rather than resetting all progress on every new head. Retain prior review evidence when new edits appear. Only the explicit file-review action advances that file's baseline; navigation, full-diff viewing, and refresh do not. Since full caches do not sync, a new device may have to fetch old objects. Deleted/unreachable objects must produce a visible baseline gap with access to the current full PR diff, not fabricated equivalence or a claim that no work remains. +Re-evaluate exact file comparison identities rather than resetting all progress on every new head. Retain prior review evidence when new edits appear. Only the explicit file-review action advances that file's baseline; navigation, full-diff viewing, grouping, skipping, and refresh do not. Since full caches do not sync, a new device may have to fetch old objects. Deleted/unreachable objects must produce a visible baseline gap with access to the current full PR diff, not fabricated equivalence or a claim that no work remains. + +Evaluate a skip against the current comparison evidence for its PR/file. Changed or newly introduced files become remaining; unrelated pushes preserve unchanged skips. Group skip records the currently remaining members at invocation, never future members of a category. Undo restores eligibility without changing the last-reviewed version. A resurfaced file includes earlier skipped edits when comparing from its last actual review; a never-reviewed file still uses the full PR diff. Refine rename/base-change/missing-history handling jointly with 01 and test stale child actions. Do not substitute a new head SHA or a rendered-view equality check for comparison identity. + +Separate underlying content kind, repository role (such as snapshot), and storage/availability (such as Git LFS). Use [01a's candidate views](README.md#changes-by-kind-and-explicit-skipping) to investigate native support, not as an exhaustive renderer commitment. Classification may use path, attributes, and content evidence; unsupported or ambiguous content needs a clear fallback. Rich/source views must share immutable comparison sides and completeness. Retain access to Markdown link targets/formatting, localization metadata/variants, and image or LFS object metadata. Missing LFS bytes must not display as a clean image diff. Catalog key or locale counts are summaries, not per-key review receipts. Bound decoding/rendering of repository content and preserve original source anchors for 05; rendering a document must not execute its active content. Multiple review children in one workspace share that PR's receipts while retaining their own selected file and comparison view. An action must identify the immutable comparison actually inspected in its originating child. Refinement must cover two children showing different revisions, so advancing progress from one cannot falsely mark unseen content in another reviewed. This follows the workspace/child distinction in [Q-19–Q-21](README.md#q-19). @@ -59,14 +70,14 @@ Fixtures must include binary/non-text and oversized files, missing patches, CRLF - [Q-08](README.md#q-08) blocks readiness: compare GitHub App and OAuth App access/onboarding; verify PKCE/callback/token-refresh behavior and concrete client-credential handling. Decide whether native public-client behavior is acceptable or an authentication broker is required. Do not assume the developer's `gh` credentials can ship in Mobius. - Clarify the first supported GitHub host/organization policies during authentication refinement. Repository-account identity must support safe sign-out and switching regardless of initial account-picker scope. -- [Q-10](README.md#q-10): Choose a bounded line-diff/rendering path using fixtures; distinguish an API-derived patch from a locally computed exact-tree comparison. +- [Q-10](README.md#q-10): Choose a bounded line-diff/rendering path and first supported content projections using fixtures; distinguish an API-derived patch from a locally computed exact-tree comparison. Specify classification, rich/source coverage, safe rendering, LFS retrieval/availability, and format/size limits before implementation; the browser's prepared comparisons prove none of those adapters. - Apply [Q-15](README.md#q-15) and 01a feedback. The comparison model is per file within one PR; stack links do not combine progress. Refine edge cases without replacing the selected workflow with a PR-wide manual checkpoint. - A stale review anchor is retained for 05 to resolve; network refresh must not silently rewrite user draft intent. ## Refinement trigger - Trigger: Core contracts and the fixture workspace are validated. -- Evidence needed: Supported auth registration/flow, permission matrix, concrete GitHub response fixtures, exact comparison semantics, and measured diff budgets. Any required account/app registration is a recorded execution prerequisite. +- Evidence needed: Supported auth registration/flow, permission matrix, concrete GitHub response fixtures, exact comparison semantics, and measured diff budgets. Include mixed-kind fixtures, hidden Markdown attribute changes, localization variants/metadata, available/unavailable assets, and changed/unchanged/new files after group skip. Assert matching rich/source baselines, separate progress counts, and no false “all reviewed” result. Any required account/app registration is a recorded execution prerequisite. - Next action: Research and, when execution is authorized, run a bounded auth/read probe. Integrate its evidence here, resolve Q-08, and write tests/steps/recovery for the selected adapter. No API write is needed for this deliverable. ## Decisions and revisions @@ -75,6 +86,7 @@ Fixtures must include binary/non-text and oversized files, missing patches, CRLF | --- | --- | --- | | 2026-11-14 | Use immutable revisions and explicit coverage; timestamps and a single head SHA are insufficient review evidence. | Q-03, R-04, official API research. | | 2026-11-14 | Replace the earlier PR-wide checkpoint proposal with per-file reviewed versions and remaining work, while keeping full PR diffs accessible. | Q-15. | +| 2026-11-14 | Add grouped content-appropriate views and current-comparison skips; retain actual review baselines and expose unavailable projections honestly. | [Q-22](README.md#q-22)–[Q-24](README.md#q-24); native support is refined under Q-10. | ## Resume point diff --git a/Plans/2026-11-14-mobius/04-repository-exploration.md b/Plans/2026-11-14-mobius/04-repository-exploration.md index 481e72ced..a62473b6f 100644 --- a/Plans/2026-11-14-mobius/04-repository-exploration.md +++ b/Plans/2026-11-14-mobius/04-repository-exploration.md @@ -27,6 +27,8 @@ Use the immutable tree/blob provider from 03 and typed child identities/document Proposed search design: fast path/name matching over the enumerated tree, plus local text indexing of supported fetched blobs. Fetch missing content on a bounded, cancellable schedule, with explicit progress and coverage. Define file-size, storage, network, and indexing limits during Q-10 refinement. Keep useful partial results while distinguishing indexing, complete, incomplete, and failed states. Source/index cache eviction must not delete draft text, receipts, or workspace document identities. +Source access from a [typed diff](README.md#changes-by-kind-and-explicit-skipping) stays inside the owning workspace and retains the requested file/revision. Opening it must not silently switch to current head or change another child's selection. Group collapse and PR-local skip affect review presentation/progress, not repository-search scope; skipped files remain discoverable. Eviction also preserves skip evidence. Native format and comparison coverage remain owned by 03. + ```mermaid flowchart LR Route["Revision-bound repository route"] --> Tree["Provider from 03"] @@ -57,7 +59,7 @@ GitHub's default-branch code-search endpoint is not the implementation of PR-rev ## Refinement trigger - Trigger: 03 supplies a tested revision-bound tree/blob API and 02 supplies document navigation. -- Evidence needed: Representative repository trees, indexing measurements, explicit coverage/cancellation policy, and restored-query behavior. +- Evidence needed: Representative repository trees, indexing measurements, explicit coverage/cancellation policy, and restored-query behavior. Include opening the exact source behind a typed diff without losing review context, and finding a skipped file without altering its disposition. - Next action: Define query/index/result contracts, choose a measured storage/index implementation, then write executable acceptance for same-path/different-revision and interrupted-index scenarios. ## Decisions and revisions @@ -67,6 +69,7 @@ GitHub's default-branch code-search endpoint is not the implementation of PR-rev | 2026-11-14 | Repository exploration is part of the review workspace, with path and text search at an explicit revision. | Q-03, R-05. | | 2026-11-14 | Keep exploration documents with their PR when switching to another PR workspace. | Q-13. | | 2026-11-14 | Support multiple independent research/source children and restore their arrangement/focus on return. | First-artifact feedback and [Q-19–Q-21](README.md#q-19). | +| 2026-11-14 | Keep typed-diff source access revision-bound; review grouping/skipping does not exclude repository search results. | [Q-22](README.md#q-22)/[Q-23](README.md#q-23) integration with R-05. | ## Resume point diff --git a/Plans/2026-11-14-mobius/05-review-feedback.md b/Plans/2026-11-14-mobius/05-review-feedback.md index 3f1b90be3..7790f6166 100644 --- a/Plans/2026-11-14-mobius/05-review-feedback.md +++ b/Plans/2026-11-14-mobius/05-review-feedback.md @@ -18,7 +18,7 @@ Demonstrate a multi-file draft, task switching, relaunch, a PR update while draf | US-03, US-07 | R-04, R-08 | Validate revision/line anchors; reconcile uncertain results without blind retries. | | US-07 | R-09 | Apply the selected account and permission scope; preserve private user text. | -X-02, X-03, and X-05 apply. No automatic review publication on navigation, backgrounding, sync, or a “mark reviewed” action. Code-edit suggestions, merge, dismissal, thread resolution, and broader PR administration are not required for this deliverable. +X-02, X-03, and X-05 apply. No automatic review publication on navigation, grouping, skip/undo, backgrounding, sync, or a “mark reviewed” action. Code-edit suggestions, merge, dismissal, thread resolution, and broader PR administration are not required for this deliverable. ## Known design and assumptions @@ -28,6 +28,8 @@ Several children may present the same PR's draft or different code revisions. Ch Read the current PR state before submission. If the head or comparison context changed, show the change and retain the draft until its target is revalidated. A comment authored while viewing a file's new edits since its reviewed version must map to a valid location in the PR review diff, or remain an unsubmitted draft with a useful explanation. Never attach a comment to the same line number in unrelated content. Submit an explicit commit ID where the API supports it; a preflight read does not make a later API write atomic with branch updates. +The same rule applies to [content-specific projections](README.md#changes-by-kind-and-explicit-skipping): a rendered paragraph, localization key, or image region is not automatically a GitHub line anchor. Retain the underlying PR/file/revision and map supported inline actions to source; otherwise offer the appropriate general-comment path while keeping authored text. Switching rich/source view must not retarget drafts. Skipping a file neither deletes its drafts nor publishes them, and skipped counts cannot imply review approval. + ```mermaid stateDiagram-v2 [*] --> Draft @@ -68,7 +70,7 @@ GitHub review/comment schemas are linked in [research](README.md#research-and-ev ## Refinement trigger - Trigger: 03 has real provider/account/revision contracts and 04 proves exploration preserves review state. -- Evidence needed: Synthetic API fixtures for accepted, rejected, and response-lost writes; a supported remote reconciliation strategy; draft/submission persistence design; planned two-device conflict cases. +- Evidence needed: Synthetic API fixtures for accepted, rejected, and response-lost writes; a supported remote reconciliation strategy; draft/submission persistence design; planned two-device conflict cases. Include rich/source view switching, unsupported inline anchors, and skip/undo preserving draft identity and text without any publication. - Next action: Expand the state machine into executable steps and failure/race tests. Live write verification during execution must use an explicitly selected test PR and account; planning itself posts no product review comments. ## Decisions and revisions @@ -77,6 +79,7 @@ GitHub review/comment schemas are linked in [research](README.md#research-and-ev | --- | --- | --- | | 2026-11-14 | Submission is explicit; personal progress and GitHub review events remain separate. | Q-02/Q-03, R-03/R-06. | | 2026-11-14 | Preserve uncertain publication rather than claiming success or automatically duplicating a write. | R-08 and the external-effect boundary. | +| 2026-11-14 | Typed views retain source-bound draft identity; skip/undo is private progress and never publishes or discards feedback. | [Q-22](README.md#q-22)–[Q-24](README.md#q-24) integration with R-03/R-06. | ## Resume point diff --git a/Plans/2026-11-14-mobius/06-icloud-resume-and-release.md b/Plans/2026-11-14-mobius/06-icloud-resume-and-release.md index 3150b6227..ed190ff83 100644 --- a/Plans/2026-11-14-mobius/06-icloud-resume-and-release.md +++ b/Plans/2026-11-14-mobius/06-icloud-resume-and-release.md @@ -6,7 +6,7 @@ ## Intended outcome -Start reviews on one device and continue them on another using private iCloud under the same Apple ID. Independent logical PR workspaces, identified children and their navigation, per-file reviewed versions, and drafts converge without losing user work or taking over another device's window focus. Returning locally restores the workspace's arrangement and last-focused child; resuming a review child starts at the top of its selected file. Each device authenticates its own GitHub account before retrieving protected source. +Start reviews on one device and continue them on another using private iCloud under the same Apple ID. Independent logical PR workspaces, identified children and their navigation, per-file reviewed versions, explicit current skips, and drafts converge without losing user work or taking over another device's window focus. Returning locally restores the workspace's arrangement and last-focused child; resuming a review child starts at the top of its selected file. Each device authenticates its own GitHub account before retrieving protected source. This deliverable is required for the first release. Demonstrate an iPhone-to-iPad-to-Mac handoff, concurrent edits, offline work, reconnect, account transitions, and a complete GitHub review flow. A local-only app or simulator-only sync demonstration does not satisfy it. @@ -15,6 +15,7 @@ This deliverable is required for the first release. Demonstrate an iPhone-to-iPa | Story | Requirement | Intended contribution | | --- | --- | --- | | US-02, US-06 | R-03, R-07 | Private cross-device continuity of semantic workspace state and drafts. | +| US-10 | R-14 | Sync PR/file skip and undo independently of reviewed versions; preserve changed/new-file eligibility. | | US-07 | R-08, R-09 | Conflict preservation, account isolation, visible sync state, and non-replayed publication intents. | | US-01, US-04, US-06 | R-01, R-10 | Final device/window/input/accessibility acceptance. | | Supporting | R-11 | Platform CI/runtime coverage, signing/distribution decision, and release evidence. | @@ -27,6 +28,8 @@ The candidate transport is `CKSyncEngine` over a dedicated private CloudKit data Use stable per-entity records instead of a single last-writer-wins workspace blob. Design tombstones and deterministic merge rules for child membership, per-child semantic navigation including selected review files, per-file review evidence, and draft revisions. Two views of one file have distinct child IDs. Separate those identities from native scenes, outer presentation mode, and device arrangement. Preserve competing draft texts. Explicitly distinguish opening a new child from an old offline device replaying a deleted child. Wall-clock order alone must not discard user-authored content. +Include [PR-local skip evidence](README.md#changes-by-kind-and-explicit-skipping) and explicit undo in the merge design, separately from reviewed baselines. A group action carries its current remaining files/comparisons, never a future category exclusion. On each device, changed/new files return while unchanged skips remain; stale skip delivery must not suppress newer content. Refine concurrent skip/undo/review and missing comparison history under Q-09 using two-replica cases. No cross-PR exclusion preference is implied. Group collapse and rich/source view preferences are presentation; decide their device/sync ownership during refinement instead of treating them as review evidence. + ```mermaid flowchart LR Local["WorkspaceStore from 01"] <-->|typed records and local commits| Adapter["Proposed WorkspaceSync"] @@ -65,10 +68,10 @@ Account changes must stop the prior sync scope and isolate its files/records bef The executable refinement must preserve this sequence: -1. Open two independent PR workspaces and several source/research/review children on iPhone; mark a file reviewed in one PR, leave another unreviewed, and save feedback text. +1. Open two independent PR workspaces and several source/research/review children on iPhone; mark a file reviewed in one PR, leave another unreviewed, explicitly skip current files in a quieter group, and save feedback text. Confirm collapsed groups alone remain unreviewed. 2. Make those workspaces and children available on iPad using its receiving-device presentation policy. Resume a review child at its selected file's top; open another child and follow a search result without losing either PR's context. Switch away and back to prove local arrangement and last focus are retained. Present a workspace as a tab or outer window without changing its contents. -3. Change the test PR; on Mac, verify new edits against each reviewed file's baseline, the full PR diff for an unreviewed file, and full-diff access for either. Check menu/keyboard navigation and that the second PR's progress is unaffected. -4. Make competing offline draft edits on two devices; reconnect and recover both texts. Exercise child close/reopen, independent navigation in same-kind children, and account switching without remote focus changes. +3. Change the test PR; on Mac, verify new edits against each reviewed file's baseline, the full PR diff for an unreviewed file, and full-diff access for either. Changed/new files return after the skip while unchanged skips persist; separate counts must not claim everything was reviewed. Verify typed and source views use the same comparison. Check menu/keyboard navigation and that the second PR's progress is unaffected. +4. Make competing offline draft edits on two devices; reconnect and recover both texts. Exercise skip/undo/review races without losing true reviewed baselines or suppressing new content, child close/reopen, independent navigation in same-kind children, and account switching without remote focus changes. 5. Submit feedback once through an explicit user action; interrupt the response and prove recovery does not blindly replay the write from either device. 6. Verify the same workflow with accessibility text sizes and VoiceOver, and inspect the platform-specific CI/runtime evidence. @@ -82,6 +85,7 @@ This is a planned acceptance flow, not a measured result. Refine exact assertion | 2026-11-14 | Sync semantic workspace metadata/drafts, retaining native presentation and source caches locally. | Overview design proposal. | | 2026-11-14 | Sync independent PR workspaces, last-file identity, and per-file reviewed versions; resume at the file top. | Q-13–Q-15. | | 2026-11-14 | Restore local arrangement/last focus; sync semantic child identity/navigation separately from device presentation. Refine receiving-device defaults and concurrent navigation under Q-09. | [Q-19–Q-21](README.md#q-19), with sync mapping still provisional. | +| 2026-11-14 | Carry explicit current skips across devices separately from reviewed evidence; stale skips cannot exclude newer changes. | [Q-23](README.md#q-23)/[Q-24](README.md#q-24); conflict/schema policy remains with Q-09. | ## Resume point diff --git a/Plans/2026-11-14-mobius/README.md b/Plans/2026-11-14-mobius/README.md index 6603dafe7..cc86f35a5 100644 --- a/Plans/2026-11-14-mobius/README.md +++ b/Plans/2026-11-14-mobius/README.md @@ -3,18 +3,20 @@ ## Planning checkpoint - Updated: 2026-11-14; initial repository baseline `b629d56ac44a3f2a5ea59c3d6ae9cd5401f37674`; merged main through `96f5bf0f1685de259d7ff080842b8092f9a950d2` in `68477fe625784a1a1e68c0115d7e42cc63166692`. -- Operation: Execute 01a in a background agent while continuing production-plan discussion here. Native implementation is not requested. -- Requested scope and source: The user's 2026-11-14 request, Q-01–Q-21 discovery, and accepted feedback to reduce the prototype's headers and subheaders; see [question history](#questions-and-resolutions) and [presentation density](#presentation-density). -- Stage: Third-iteration delivery handoff; user evaluation is the next product decision. +- Operation: Revise the plan and run a bounded fourth prototype iteration for grouped, type-specific changes and explicit PR-local skipping. Native implementation is not requested. +- Requested scope and source: The user's 2026-11-14 request, Q-01–Q-21 discovery, accepted compact chrome, and new feedback to distinguish localization, Markdown, Git LFS, and code changes; see [question history](#questions-and-resolutions) and [presentation density](#presentation-density). +- Stage: Q-22–Q-24 integrated and reviewed; fourth-iteration method ready for the coordinated stack update and implementation. - Completed: The compact-chrome rebuild and matched captures are complete. Final-source browser scenarios pass at phone, tablet, and desktop sizes; fresh independent review has no actionable findings. The coordinator inspected the phone/desktop captures and verification record. [01a's iteration-3 record](https://github.com/kyleve/Stuff/blob/codex/mobius-prototype/Plans/2026-11-14-mobius/01a-workspace-prototype.md#iteration-3-implementation-and-evidence) owns the tested source hash, measurements, corrections, and publication details. Earlier iteration artifacts and evidence remain intact. [PR #497](https://github.com/kyleve/Stuff/pull/497)/[STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app) track plan delivery; [PR #500](https://github.com/kyleve/Stuff/pull/500)/[STU-330](https://linear.app/kve/issue/STU-330/prototype-mobius-review-workspaces) track the experiment. -- Pending: Finish the coordinated publication/reporting handoff recorded in 01a, then collect third-round user evaluation; PR review and merge remain. Q-08–Q-12 retain their technical refinement gates. Browser verification does not establish product acceptance or native feasibility. -- Execution authorization and ownership: The user approved the compact-chrome proposal and explicitly requested a subagent rebuild and completion notice. `/root/mobius_prototype` owns `Prototype/**` and 01a in `/Users/kve/.codex/worktrees/mobius-prototype/Stuff` on `codex/mobius-prototype`; the coordinating agent owns the overview, affected production outlines, and the user-facing completion message. Coordinate shared stack mutations at clean worktree points. Native implementation remains outside scope. -- Next action: Complete the [01a delivery handoff](https://github.com/kyleve/Stuff/blob/codex/mobius-prototype/Plans/2026-11-14-mobius/01a-workspace-prototype.md#resume-point) and notify the user with the rebuilt demo and checks, then integrate their evaluation before refining 01. The 01a copy on the planning branch is its pre-execution baseline; the implementation branch owns subsequent method revisions and execution status. Native plans remain outlines. +- Pending: Implement/validate the bounded mixed-change prototype and obtain fourth-round user evaluation. PR review and merge remain. Q-08–Q-12 retain their technical refinement gates. Browser verification does not establish product acceptance or native feasibility. +- Execution authorization and ownership: The user's next addition requests type-specific change presentation, refined by Q-22–Q-24, within the ongoing prototype work. `/root/mobius_prototype` owns `Prototype/**` and 01a in `/Users/kve/.codex/worktrees/mobius-prototype/Stuff` on `codex/mobius-prototype`; the coordinating agent owns the overview, affected production outlines, and the requested completion notice. Coordinate shared stack mutations at clean worktree points. Native implementation remains outside scope. +- Next action: Publish the integrated parent and reviewed [01a method](https://github.com/kyleve/Stuff/blob/codex/mobius-prototype/Plans/2026-11-14-mobius/01a-workspace-prototype.md#iteration-4-file-kinds-and-explicit-skip-method), then build and validate its fixture-backed behavior. The worker returns tested/published revisions, evidence, and any blocker; the coordinator verifies delivery and notifies the user. The 01a copy here is the pre-execution baseline; its implementation branch owns current methods/evidence. Native plans remain outlines. ## Outcome and scope Mobius keeps code review open as ongoing work. Each PR has its own logical workspace, which can be presented as a tab or a window. Inside it, reviewers can keep several windows open for review, source, research, and preview context. Returning restores that workspace's arrangement and last-focused window. Resuming a review window starts at the top of its selected file. A remaining-work view shows new edits in previously reviewed files and the full PR diff for unreviewed files; the full PR diff stays available for either. Each reviewed file has its own last-reviewed version. Nobody needs a temporary “got to here” GitHub comment. +Changes are grouped by kind, with quieter groups collapsed and presentations suited to the underlying content. A reviewer can explicitly skip current changes for this PR without marking them reviewed. Skipped changes stay discoverable and undoable; new changes return to remaining work while unchanged skips persist. Skipping never advances the last actually reviewed version. + PRs remain separate even when GitHub connects them in a stack. If a stack connection is shown, it is an informational link; it does not combine progress, drafts, comparison baselines, or submission actions. Stack discovery is not an additional first-release integration requirement. The first release targets **iPhone, iPad, and Mac Catalyst**, including Mac windows, menus, and shortcuts. It supports GitHub PR diffs, comments, approvals, and requests for changes. Private iCloud sync carries workspaces and personal progress between devices using the same Apple ID. These are first-release requirements even though implementation is divided into deliverables. @@ -33,17 +35,19 @@ Embedding the reviewer inside an owning app, with a possible live execution surf | US-06 | Resume the same work on iPhone, iPad, and Mac. | | US-07 | Trust progress and recover from failures without incomplete downloads or interrupted submissions appearing complete. | | US-08 | Learn whether embedding Mobius beside the running app can improve review with live context. | +| US-09 | Scan changes by kind and inspect them in a useful form, so localization, documents, and assets do not overwhelm code review. | +| US-10 | Set aside changes for this PR without claiming to have reviewed them, and see new changes when I return. | ## Requirements -R-01–R-07 and R-12 derive from the user's product choices. R-08–R-11 support repository contracts and correctness; R-10 also incorporates the accepted presentation-density direction. Design details are proposals unless identified as user decisions. +R-01–R-07 and R-12–R-14 derive from the user's product choices. R-08–R-11 support repository contracts and correctness; R-10 also incorporates the accepted presentation-density direction. Design details are proposals unless identified as user decisions. | ID | Required behavior or constraint | Story | Implementing plan | | --- | --- | --- | --- | | R-01 | Run on iPhone, iPad, and Mac Catalyst, with Mac windows, menus, and keyboard commands. | US-06 | [02](02-application-workspace.md), [06](06-icloud-resume-and-release.md) | | R-02 | Keep one independent logical workspace per PR, presentable as a tab or window. Each owns multiple child windows for review, source, and research, with room to investigate preview/live context. Support multiple views of the same kind with independent navigation. Switching PRs or outer presentation preserves their contents. Stack connections, if shown, are informational. | US-01, US-04 | [01a](01a-workspace-prototype.md) explores interaction and simulated previews; [01](01-review-state-foundation.md), [02](02-application-workspace.md), [04](04-repository-exploration.md) deliver the workspace; [07](07-embedded-review-experiment.md) investigates live context | -| R-03 | Persist child-window identity/navigation, per-file reviewed versions, and drafts across relaunch. Returning restores the workspace arrangement and last-focused child. Resuming a review child starts at its selected file's top; precise in-file position and reviewed-range tracking are not required. Review progress belongs to the PR workspace; personal progress and submitted GitHub feedback remain separate facts. | US-02 | [01a](01a-workspace-prototype.md) explores interaction; [01](01-review-state-foundation.md), [02](02-application-workspace.md), [05](05-review-feedback.md) deliver it | -| R-04 | Within one PR, remaining work combines new edits since each reviewed file's last-reviewed version with the full PR diff for unreviewed files. Let either file open its full PR diff. An explicit file-review action advances that file's baseline; navigation and refresh do not. | US-03 | [01a](01a-workspace-prototype.md) explores interaction; [01](01-review-state-foundation.md), [03](03-github-and-revision-comparison.md) deliver it | +| R-03 | Persist child-window identity/navigation, per-file reviewed versions, current skip evidence, and drafts across relaunch. Returning restores the workspace arrangement and last-focused child. Resuming a review child starts at its selected file's top; precise in-file position and reviewed-range tracking are not required. Review progress belongs to the PR workspace; skipped, reviewed, and submitted GitHub feedback remain separate facts. | US-02, US-10 | [01a](01a-workspace-prototype.md) explores interaction; [01](01-review-state-foundation.md), [02](02-application-workspace.md), [05](05-review-feedback.md) deliver it | +| R-04 | Within one PR, remaining work combines new edits since each reviewed file's last-reviewed version with the full PR diff for unreviewed files, excluding current explicit skips under R-14 while keeping them discoverable. Let every file open its full PR diff. An explicit file-review action advances that file's baseline; navigation, grouping, skipping, and refresh do not. | US-03, US-10 | [01a](01a-workspace-prototype.md) explores interaction; [01](01-review-state-foundation.md), [03](03-github-and-revision-comparison.md) deliver it | | R-05 | Browse files and search paths and text at an identified repository revision within Mobius. Open results in child windows without replacing the review and show search coverage. Independent views may inspect the same file or separate queries. | US-04 | [04](04-repository-exploration.md) | | R-06 | Read review discussion; compose and explicitly submit comments, approvals, and requests for changes with revision validation and recoverable drafts. | US-05 | [03](03-github-and-revision-comparison.md), [05](05-review-feedback.md) | | R-07 | Resume workspace contents, child-view navigation, progress, and draft work through private iCloud sync on the same Apple ID. Keep device window placement local and expose sync state; refine cross-device presentation policy under Q-09. | US-02, US-06 | [01](01-review-state-foundation.md) supplies identities; [06](06-icloud-resume-and-release.md) delivers sync | @@ -52,6 +56,8 @@ R-01–R-07 and R-12 derive from the user's product choices. R-08–R-11 support | R-10 | Prioritize code and preview content with compact workspace/view controls and details on demand, while keeping identity, comparison meaning, immediate actions, and relevant warnings clear. Preserve readable text and accessible touch/keyboard/VoiceOver interaction, accessibility text sizes, long lines, and large diffs. Define measured rendering/indexing budgets before the corresponding plan becomes ready. | US-01, US-04, US-06 | [01a](01a-workspace-prototype.md) explores density; [02](02-application-workspace.md), [03](03-github-and-revision-comparison.md), [04](04-repository-exploration.md) deliver it | | R-11 | Integrate module docs, manifests, tests, architecture boundaries, attribution, and CI. Release acceptance requires evidence on all three destinations and real cross-device sync. | Supporting constraint | [01](01-review-state-foundation.md), [02](02-application-workspace.md), [06](06-icloud-resume-and-release.md) | | R-12 | Evaluate a host-injected embedded reviewer and bounded live-context action; report feasibility and limitations without promising arbitrary PR execution. | US-08 | [07](07-embedded-review-experiment.md) | +| R-13 | Group changes by content kind with quieter groups collapsed, and use content-appropriate diff presentations with source/metadata access. Keep counts and changed files discoverable. Rendering limitations must remain explicit; grouping or a rich preview cannot imply review. The initial viewer set is a prototype hypothesis, not an exhaustive native format promise. | US-09 | [01a](01a-workspace-prototype.md) explores grouped mixed fixtures; [02](02-application-workspace.md), [03](03-github-and-revision-comparison.md) deliver the native experience | +| R-14 | Allow explicit skip and undo for current changes within one PR, separately from reviewed. Skipping a group captures its currently remaining files; it does not reclassify reviewed files or exclude that kind from future updates. Changed/new files return to remaining work, unchanged skips persist, and reviewed baselines never advance on skip. Keep skipped counts distinct; zero remaining work must not be labeled all reviewed when skips exist. | US-10 | [01a](01a-workspace-prototype.md) explores interaction; [01](01-review-state-foundation.md), [02](02-application-workspace.md), [03](03-github-and-revision-comparison.md) deliver local behavior; [06](06-icloud-resume-and-release.md) carries personal skip evidence between devices | ## Not required and explicitly avoided @@ -64,6 +70,7 @@ R-01–R-07 and R-12 derive from the user's product choices. R-08–R-11 support | X-05 | Explicitly avoided | Treating truncated data, missing history, ambiguous lineage, failed saves, or uncertain submissions as success. | Progress must remain trustworthy. | | X-06 | Not required | A Mobius service for workspace sync or sync across different Apple IDs. | Q-07 selected private iCloud. Authentication hosting remains an alternative in Q-08. | | X-07 | Explicitly avoided | Importing Where's product models or repurposing InstallerKit's catalog client as a GitHub client. | Mobius owns its domain; shared modules retain their contracts. | +| X-08 | Not required | Remembered type exclusions across PRs, automatic review based on classification, or per-key/per-pixel review receipts. | Q-23 selected PR-local skipping; file-level reviewed evidence remains the model. | ## Context and discovery @@ -89,6 +96,9 @@ Consulted 2026-11-14. External sources establish documented capabilities, not li | What native authentication is supported? | GitHub's [user-token flow](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) documents PKCE and client credentials; [public-client guidance](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/best-practices-for-creating-an-oauth-app) addresses native clients. | Do not assume a secretless exchange or default to pasted personal tokens. Resolve Q-08. | | Can UIKit support the workspace on Mac? | Apple's [Catalyst guidance](https://developer.apple.com/videos/play/wwdc2021/10053/) covers scene-backed windows and menus; [multiple-window guidance](https://developer.apple.com/documentation/uikit/supporting-multiple-windows-on-ipad) separates scenes from shared data. | Share services; keep scene presentation independent. Phone tabs must not require multiple windows. | | Does CloudKit define merge behavior? | Apple's [CKSyncEngine guidance](https://developer.apple.com/videos/play/wwdc2023/10188/) assigns state persistence and conflict handling to the app. Its [sample](https://github.com/apple/sample-cloudkit-sync-engine) documents container, signing, and real-device/Mac prerequisites. | Define merge/account policies and obtain real two-device evidence. | +| Is Git LFS a content kind? | GitHub documents LFS [pointers to separately stored content](https://docs.github.com/en/repositories/working-with-files/managing-large-files/about-git-large-file-storage). This repo's [.gitattributes](../../.gitattributes) assigns LFS to snapshot PNGs. | Classify the underlying asset for presentation and retain LFS as storage/availability metadata. Missing asset bytes do not imply an unchanged image. | +| Can rich views replace all source evidence? | GitHub's [non-code diff guidance](https://docs.github.com/en/repositories/working-with-files/using-files/working-with-non-code-files) describes image comparisons, prose source/rendered views, and less visible attribute changes. | Candidate rich views need source/metadata access and honest coverage. The docs demonstrate precedents, not an implementation Mobius can assume exists. | +| What localization structure exists here? | At `2c0926596`, [WhereUI's catalog](../../Where/WhereUI/Sources/Resources/Localizable.xcstrings) has source-language/string/version fields, 1,033 entries, and eight variation-bearing entries. | Explore key/locale/value changes rather than serialized JSON lines; plural/variation and metadata coverage still need native refinement. | ## Design overview @@ -117,6 +127,25 @@ The user evaluated iteration 2 and accepted the following direction on 2026-11-1 The target is a compact workspace bar and view toolbar with useful content immediately below. This is an information-priority decision, not a fixed pixel-height limit for native or accessibility layouts. Record comparable before/after content-space evidence across the three viewport sizes, and recheck reachability and focus for controls moved into disclosures. [02](02-application-workspace.md) carries this into native refinement; the prototype's exact controls remain subject to evaluation. +### Changes by kind and explicit skipping + +Q-22 selects grouped changes with quieter groups collapsed. Q-23 adds explicit skip for this PR, separate from reviewed. Q-24 requires new changes to return to remaining work. Collapsing is presentation only; skipping records a deliberate choice about the current comparison without creating a review receipt. + +The next bounded mockup will investigate these candidate presentations, using prepared synthetic comparisons rather than claiming real parsers or provider integration: + +| Group | Candidate list summary | Candidate detail | +| --- | --- | --- | +| Code | Files and change counts | Existing line diff. | +| Documents | Files or changed sections | Rendered Markdown/prose changes with source access, including changed link targets. | +| Localization | Changed keys/locales, distinguished from file count | Key/value/locale changes and source access; a catalog remains one reviewable file. | +| Snapshots/assets | Changed assets and thumbnails | Before/after images and dimensions/metadata; an LFS badge where applicable. Unavailable content stays explicit. | + +These are initial experiment defaults. Do not treat the filename extension alone as the whole classification policy, or promise an exhaustive native format catalog. Unknown/unsupported content needs an honest fallback. Exact supported formats and rendering/source coverage remain part of 03 and Q-10 refinement. The compact chrome from iteration 3 remains in force. + +An individual skip captures a currently remaining file's comparison. As a bounded interaction choice, the prototype's group action is “Skip remaining files”: it captures only that group's currently remaining files, leaving reviewed files and future members alone. Skipped files remain reachable through the group's summary/full-change view and can be unskipped. On a later push, only changed files or newly introduced files return; unchanged skipped files retain their disposition. A returning reviewed file still compares from its last actually reviewed version, including earlier skipped edits. A returning never-reviewed file shows its full PR diff. Both follow Q-15 because a skip is not a new baseline. Counts distinguish remaining, reviewed, and skipped; a fully skipped PR is not a fully reviewed PR. + +Each child retains independent selection/view mode; classification and skip/progress evidence refer to the owning PR/file. Opening a rich or source view, expanding a group, or applying a new push never marks content reviewed or submits GitHub feedback. Native refinement must preserve revision-bound source anchors for comments and mark unavailable or partial projections honestly. + ### Product concepts - **Workspace:** the logical owner of one PR's child windows, progress, and drafts. Its identity does not depend on being presented as a workspace tab or outer window. Another PR has a separate workspace, including when the PRs belong to a stack. @@ -126,6 +155,8 @@ The target is a compact workspace bar and view toolbar with useful content immed - **Resume file:** each review child's selected file. Resuming that review starts at its top; an exact scroll position is not durable review progress. Returning to a workspace need not focus a review child. - **Review receipt:** explicit evidence for a file comparison, including both sides, paths, modes, and content identities. A new head alone neither invalidates every receipt nor proves any one remains current. - **Per-file baseline:** the version last marked reviewed for that file. Remaining work compares against it; a file with no baseline shows its full PR diff. A separate manually captured PR-wide checkpoint is not required by the selected workflow. +- **Skip evidence:** a PR-local choice to set aside the current file comparison, distinct from its last-reviewed baseline. A group action applies to currently remaining files. New changes invalidate the affected skip, not unrelated skips; undo restores remaining-work eligibility without advancing review progress. +- **Change presentation:** a content-kind-specific list and diff projection over the same file/revision identity. LFS/storage availability and a snapshot's role are separate from its image format. Native classification and renderer interfaces remain provisional. - **Draft:** user text with its original revision/anchor. Draft, publishing, uncertain outcome, and confirmed publication remain distinct states. ### Proposed ownership @@ -151,7 +182,7 @@ flowchart LR Publish -->|receipt or uncertain result| Store ``` -Credentials come from device-local Keychain and are omitted. Sync carries metadata and draft text, not full source caches. Identity/generation checks precede mutation after asynchronous work. A local save and a GitHub write are not one atomic transaction. +Credentials come from device-local Keychain and are omitted. Sync carries metadata (including separate reviewed and skipped evidence) and draft text, not full source caches. Identity/generation checks precede mutation after asynchronous work. A local save and a GitHub write are not one atomic transaction. ```swift // Proposed ownership only; not compiled code or existing APIs. @@ -200,7 +231,7 @@ actor WorkspaceStore { ## Planning horizon -- Detail now: [01a](01a-workspace-prototype.md), selected in Q-16–Q-18 to explore all three layouts through a lightweight interactive mockup; the current iteration addresses the workspace/window feedback and Q-19–Q-21. +- Detail now: [01a](01a-workspace-prototype.md), selected in Q-16–Q-18 to explore all three layouts through a lightweight interactive mockup. Iteration 4 adds grouped type-specific changes and explicit skip/undo under Q-22–Q-24 while preserving the workspace model and compact chrome from iterations 2/3. - Later selected work: 01–07 are outlines. The earlier claim that 01 was ready is superseded; its model must follow prototype learning. - Next horizon review: Record prototype observations and the user's feedback, integrate changed decisions, then refine 01 and reconsider 02/03. Technical decisions Q-08–Q-12 retain their recorded gates. - First-release gate: **01–06 together**, preceded by prototype learning. The mockup does not deliver or waive native platform, GitHub feedback, persistence, or sync requirements. @@ -222,6 +253,9 @@ actor WorkspaceStore { | 2026-11-14 | Explore floating, tiled, docked, or tabbed arrangements where useful; choose a bounded set for the mockup without fixing every native platform's controls. | Q-20: “All of the above if needed.” | | 2026-11-14 | Return to the workspace's arrangement and last-focused child. File-top review resumption still applies when a review child is resumed. | Q-21; refines Q-14 without forcing review focus. | | 2026-11-14 | Use compact workspace/view chrome, details on demand, and collapsible prototype controls; retain comparison meaning, warnings, readable text, and accessible actions. | User's iteration-2 feedback and explicit acceptance of the [presentation-density proposal](#presentation-density). | +| 2026-11-14 | Group changes by kind with quieter groups collapsed; investigate content-appropriate views in a bounded mixed-change prototype. | Q-22 and the user's type-aware diff request. | +| 2026-11-14 | Skip current changes explicitly within this PR, separately from reviewed; new changes return while unchanged skips persist. Review baselines do not advance. | Q-23/Q-24; refines remaining-work eligibility while preserving Q-15's comparisons. | +| 2026-11-14 | Prototype interaction choice: label group skipping “Skip remaining files” and snapshot only those current members, preserving reviewed files and future additions. | Coordinator's bounded implementation choice within Q-23/Q-24; evaluate alongside the grouped list. | | 2026-11-14 | Proposed: sync semantic workspace data and drafts; keep native geometry/focus and full code caches local. | R-07/R-09. | | 2026-11-14 | Proposed: atomic metadata storage, not a bounded journal as the only copy of user work. | JournalKit contract. | @@ -250,8 +284,11 @@ actor WorkspaceStore { | [Q-19](#q-19) | closed | Does “fork” mean another view or an editable code copy? | R-02/R-05, X-02/X-04, 01a, 01, 02, 04, 07 | It was a typo for “view”; workspace/child distinction integrated without code authoring. | | [Q-20](#q-20) | closed | How should child windows be arranged? | R-02/R-10, 01a, 02 | All proposed modes may be useful; bounded experiment method reviewed. Native defaults await evidence. | | [Q-21](#q-21) | closed | Restore arrangement and last focus, or always bring review forward? | R-03/R-07, 01a, 01, 02, 04, 06 | Restore arrangement and last-focused child; file-top behavior applies when resuming a review child. | +| [Q-22](#q-22) | closed | How should file kinds change the default change list and presentation? | R-10/R-13, 01a, 02, 03 | Group by kind with quieter groups collapsed; bounded typed views are prototype hypotheses, native coverage remains with Q-10. | +| [Q-23](#q-23) | closed | Does lower attention mean collapsed detail, explicit skipping, or remembered exclusions? | R-03/R-04/R-14, 01a, 01–06 | Explicit current skip/undo is separate from reviewed; group action captures currently remaining files, with no cross-PR rule. | +| [Q-24](#q-24) | closed | Do new changes to a skipped kind return to remaining work? | R-03/R-04/R-14, 01a, 01, 03, 06 | Changed/new files return, unchanged skips persist, and actual reviewed baselines remain intact. Integrated and method-reviewed. | -User answers came from this chat on 2026-11-14. Q-13–Q-21 refine the original answers without reopening the selected platforms, provider, or iCloud scope. The current horizon is prototype evaluation; detailed navigation and layout remain hypotheses to explore through it. +User answers came from this chat on 2026-11-14. Q-13–Q-24 refine the original answers without reopening the selected platforms, provider, or iCloud scope. The current horizon is prototype evaluation; concrete views and controls remain hypotheses to explore through it. ### Q-01 @@ -386,6 +423,34 @@ User answers came from this chat on 2026-11-14. Q-13–Q-21 refine the original - Integration: R-03, discovery scenario, product concepts, 01/02/04/06, and 01a. A source, research, or preview child can remain focused on return. Q-14 still applies when the reviewer resumes a review child. Device-specific geometry/focus versus synced semantic state remains subject to Q-09's later policy refinement. - History: Answered 2026-11-14, integrated and closed after the resume-path consistency review below; no remaining product question blocks the revised browser method. +### Q-22 + +- Request/source: On 2026-11-14, after trying the compact prototype, the user asked to differentiate changes by type, naming localization, Git LFS, Markdown, and code, and to list them differently. +- Current proposal: Specialized presentations and concise summaries could accompany grouping by content kind. Localization could show changed keys/translations, Markdown rendered changes, assets visual previews/metadata, and code line diffs. These examples are proposals, not a selected first-release renderer catalog. +- Asked: For a mixed PR, group by kind with quieter groups collapsed, show code first followed by other changes, or retain one file list with specialized previews? +- Blocking impact: Resolve the default organization and a bounded sample set before making a further 01a iteration executable. Later native classification/rendering belongs to 02/03 and Q-10. No new renderer implementation is authorized by this discovery record. +- Answer/source: The user selected grouping by kind, with quieter groups collapsed, on 2026-11-14. +- Integration: US-09/R-13, [candidate views](#changes-by-kind-and-explicit-skipping), 02/03 and dependent source/feedback paths in 04/05. The bounded 01a method covers four groups and prepared views, without selecting a final native format catalog. +- History: Opened, answered, integrated, and closed 2026-11-14 after the iteration-4 consistency/readiness review below. + +### Q-23 + +- Request/source: The user cares less about some change types, but has not specified how that preference changes review progress. +- Asked: Collapse detail while leaving files unreviewed, allow an explicit skip for this PR distinct from reviewed, or remember personal exclusions across PRs? +- Blocking impact: Integrate skip separately from R-03/R-04 review receipts. Visual prominence must not silently imply review. The new PR-local state affects 01/03 and later sync policy in 06. +- Answer/source: The user selected explicit skip for this PR, separate from reviewed, on 2026-11-14. Remembered exclusions across PRs were not selected. +- Integration: US-10/R-14 and R-03/R-04, skip evidence in 01/03, visible group actions/counts in 02, preserved source/drafts in 04/05, and later sync in 06. Group actions are explicitly scoped to currently remaining files as a prototype interaction choice. Q-24 supplies push behavior. +- History: Opened, answered, integrated, and closed 2026-11-14 after the iteration-4 consistency/readiness review below. + +### Q-24 + +- Asked: After skipping localization in one PR, do another push's localization changes return to remaining work, or does that kind stay skipped for the PR until undo? +- Source: Follow-up to the user's Q-23 answer on 2026-11-14. The existing per-file reviewed baseline must remain separate from this new personal skip choice. +- Blocking impact: Needed before fixing skip identities/state transitions or executing another prototype pass. Unrelated grouping/presentation discovery can continue. +- Answer/source: The user selected bringing new changes back into remaining work on 2026-11-14. +- Integration: R-14, [skip semantics](#changes-by-kind-and-explicit-skipping), 01/03/06 state and verification, and 01a's changed/unchanged/new fixture scenario. Skip never advances a reviewed baseline; production identity/conflict details remain at their existing refinement gates. +- History: Opened, answered, integrated, and closed 2026-11-14 after the iteration-4 consistency/readiness review below. + ## Plan review - Initial review: 2026-11-14 against `b629d56ac44a3f2a5ea59c3d6ae9cd5401f37674`, covering the original eight files. Its readiness finding for 01 is superseded by Q-13–Q-18 and prototype-first sequencing. @@ -393,17 +458,18 @@ User answers came from this chat on 2026-11-14. Q-13–Q-21 refine the original - Revision review: Integrated Q-13–Q-18 across the nine-file series, including workspace isolation, file-top resumption, per-file baselines, and prototype-first dependencies. Reviewed 01a for executable experiment detail; 01–07 remain outlines. - Iteration-2 review: 2026-11-14 against parent `68477fe625` plus this revision and the implementation branch's 01a method at `68926adfd`. Reviewed all affected production outlines and the current experiment method against Q-19–Q-21. Corrected the conflation of workspace, outer presentation, and child identity; moved review-file selection into each child; separated return focus from review resumption; and kept preview execution and cross-device presentation policy at their existing refinement gates. Multiple views share PR review evidence without sharing navigation. No remaining consistency or browser-method readiness finding was identified. - Iteration-3 review: 2026-11-14 against parent `fcee86b3b`, iteration-2 artifact `e1c1059cf28`, and the revised 01a method on the implementation branch. The accepted information priorities are integrated into R-10, the shared decision, and 02's native refinement. The method preserves comparison truth and all existing capabilities, repeats moved-control/focus checks, and requires matched content-space evidence. Background ownership and completion reporting are explicit. No remaining consistency or browser-method readiness finding was identified; native implementation and third-round acceptance remain pending. -- Readiness: 01a's implementation branch owns the reviewed iteration methods, status transitions, and evidence; its pre-execution copy here is historical. Iteration-2 checks and user evaluation are recorded. The compact-chrome correction requires another bounded iteration and evaluation before refining 01; native plans 01–07 remain outlines. -- Verification: All 135 local Markdown links and anchors resolve across nine planning-branch files; fences are balanced; the unchanged eight-plan dependency graph is acyclic; all 12 requirements retain implementing owners; `git diff --check` passes. The revised 01a method was also inspected on its owning branch. These checks validate the plan, not the proposed app. +- Iteration-4 review: 2026-11-14 against parent `2c0926596` plus this revision and child method `0ff008a05e668dea373800208d2d7a8fd049a63f`. Traced Q-22–Q-24 through R-13/R-14 and affected 01–06 outlines. Kept kind presentation independent from review/skip evidence; restricted group skip to currently remaining members; retained actual reviewed baselines and independent child navigation; distinguished LFS storage from content kind; and preserved source/metadata coverage and unavailable-state honesty. The method bounds seven v1/eight v2 files per PR, with changed/unchanged/new cases, raw/rich comparison checks, all prior regressions, independent review, and three-size captures. No remaining consistency or method-readiness finding was identified. Native schemas, format support, rendering budgets, and merge policy remain provisional. +- Readiness: 01a's implementation branch owns reviewed methods, status transitions, and evidence; its pre-execution copy here is historical. Iterations 1–3 and their feedback are retained. Iteration 4's bounded method is ready for the authorized browser work; product acceptance and native plans 01–07 remain pending. +- Verification: All 168 local Markdown links/anchors resolve across nine planning-branch files; fences are balanced; all 14 requirements have implementing owners; the eight-plan dependency graph is acyclic; `git diff --check` passes. The revised 01a method was inspected on its owning branch. These checks validate the plan, not the proposed app. - Iteration-3 delivery review: The recorded final HTML hash is `f2adc670df7668d0c99d79f3ac0d9abeea3df701f56a53e1373de331c2eb274f`. Matched review-pane heights increased from 413 to 765 CSS pixels on desktop, 535 to 877 on tablet, and 216 to 648 on phone. Code text increased from 10 to 12 CSS pixels. Browser checks cover the retained review/workspace behavior and newly disclosed controls; independent review rechecked focus, accessible-title, dialog-lifecycle, and stacking corrections. No actionable finding remains. Full evidence stays in 01a rather than being duplicated here. -- Validation limits: Third-round user evaluation remains pending. No native device test, VoiceOver, product API write, real code execution, persistence, or sync experiment has run. Swift is pseudocode. Mermaid was inspected as source; no local renderer was found. `./test` and `./swiftformat --lint` were skipped for this planning revision because only Markdown changed; browser checks belong to the prototype branch. +- Validation limits: Fourth-round implementation/evaluation remain pending. No native device test, VoiceOver, product API write, real code execution, persistence, or sync experiment has run. Swift is pseudocode. Mermaid was inspected as source; no local renderer was found. `./test` and `./swiftformat --lint` were skipped for this planning revision because only Markdown changed; browser checks belong to the prototype branch. ## Review and delivery - Plan review: [PR #497](https://github.com/kyleve/Stuff/pull/497), ready for review. [STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app) remains In Review until merge and acceptance verification. -- Implementation: [PR #500](https://github.com/kyleve/Stuff/pull/500) and [STU-330](https://linear.app/kve/issue/STU-330/prototype-mobius-review-workspaces) own 01a's artifact, current method, and evidence. The third iteration is built and verified; its delivery record owns publication and the explicit completion-reporting handoff. Native plans 01–07 have not started. -- Review focus: Logical PR workspaces independent of outer tabs/windows; multiple child views with independent navigation; arrangement/last-focus restoration; per-file remaining work and full-diff access; file-top review resumption; prototype learning before the durable model; sync as a release gate. +- Implementation: [PR #500](https://github.com/kyleve/Stuff/pull/500) and [STU-330](https://linear.app/kve/issue/STU-330/prototype-mobius-review-workspaces) own 01a's artifact, current method, and evidence. Three iterations are published; the fourth adds grouped typed views and explicit skip/undo. The worker/coordinator handoff includes the requested completion notification. Native plans 01–07 have not started. +- Review focus: Logical PR workspaces independent of outer tabs/windows; multiple child views with independent navigation; arrangement/last-focus restoration; grouped typed comparisons with source access; skip versus reviewed and changed-file resurfacing; per-file remaining work and full-diff access; file-top review resumption; prototype learning before the durable model; sync as a release gate. ## Outcome -The third prototype iteration preserves the logical workspace/child model and reduces permanent chrome according to the accepted presentation-density decision. The rebuild passes its browser checks and independent review; the experiment remains open for user evaluation. Plans 01–07 remain outlines informed by that evaluation and further production discussion. +The plan now includes grouped content-appropriate comparisons and explicit PR-local skipping, with new changes returning to remaining work and actual reviewed baselines preserved. Three prototype iterations are published; a bounded fourth iteration will evaluate these additions while retaining compact chrome and logical workspace/child ownership. Plans 01–07 remain outlines informed by that evaluation and further production discussion. From 625c64dca5c986e58de5de58c43f313de6567204 Mon Sep 17 00:00:00 2001 From: Kyle Van Essen Date: Sat, 14 Nov 2026 22:02:01 -0500 Subject: [PATCH 09/12] docs(Mobius): record grouped-demo verification handoff --- Plans/2026-11-14-mobius/README.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/Plans/2026-11-14-mobius/README.md b/Plans/2026-11-14-mobius/README.md index cc86f35a5..90074fb8b 100644 --- a/Plans/2026-11-14-mobius/README.md +++ b/Plans/2026-11-14-mobius/README.md @@ -5,11 +5,11 @@ - Updated: 2026-11-14; initial repository baseline `b629d56ac44a3f2a5ea59c3d6ae9cd5401f37674`; merged main through `96f5bf0f1685de259d7ff080842b8092f9a950d2` in `68477fe625784a1a1e68c0115d7e42cc63166692`. - Operation: Revise the plan and run a bounded fourth prototype iteration for grouped, type-specific changes and explicit PR-local skipping. Native implementation is not requested. - Requested scope and source: The user's 2026-11-14 request, Q-01–Q-21 discovery, accepted compact chrome, and new feedback to distinguish localization, Markdown, Git LFS, and code changes; see [question history](#questions-and-resolutions) and [presentation density](#presentation-density). -- Stage: Q-22–Q-24 integrated and reviewed; fourth-iteration method ready for the coordinated stack update and implementation. -- Completed: The compact-chrome rebuild and matched captures are complete. Final-source browser scenarios pass at phone, tablet, and desktop sizes; fresh independent review has no actionable findings. The coordinator inspected the phone/desktop captures and verification record. [01a's iteration-3 record](https://github.com/kyleve/Stuff/blob/codex/mobius-prototype/Plans/2026-11-14-mobius/01a-workspace-prototype.md#iteration-3-implementation-and-evidence) owns the tested source hash, measurements, corrections, and publication details. Earlier iteration artifacts and evidence remain intact. [PR #497](https://github.com/kyleve/Stuff/pull/497)/[STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app) track plan delivery; [PR #500](https://github.com/kyleve/Stuff/pull/500)/[STU-330](https://linear.app/kve/issue/STU-330/prototype-mobius-review-workspaces) track the experiment. -- Pending: Implement/validate the bounded mixed-change prototype and obtain fourth-round user evaluation. PR review and merge remain. Q-08–Q-12 retain their technical refinement gates. Browser verification does not establish product acceptance or native feasibility. +- Stage: Fourth-iteration delivery handoff; grouped comparisons and skip behavior are built and browser-verified, with user evaluation next. +- Completed: Q-22–Q-24 and affected production outlines are integrated and reviewed. The fourth prototype iteration is built; the three-size workspace/grouped-change scenarios and fresh independent review pass on the recorded final source. The coordinator inspected representative captures and the review record. Earlier artifacts/evidence remain intact. [01a's execution record](https://github.com/kyleve/Stuff/blob/codex/mobius-prototype/Plans/2026-11-14-mobius/01a-workspace-prototype.md#iteration-4-readiness-and-execution) owns detailed evidence and publication. [PR #497](https://github.com/kyleve/Stuff/pull/497)/[STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app) track the plan; [PR #500](https://github.com/kyleve/Stuff/pull/500)/[STU-330](https://linear.app/kve/issue/STU-330/prototype-mobius-review-workspaces) track the experiment. +- Pending: Finish the coordinated publication/completion-reporting handoff in 01a, then obtain fourth-round user evaluation. PR review and merge remain. Q-08–Q-12 retain their technical refinement gates. Browser verification does not establish product acceptance or native feasibility. - Execution authorization and ownership: The user's next addition requests type-specific change presentation, refined by Q-22–Q-24, within the ongoing prototype work. `/root/mobius_prototype` owns `Prototype/**` and 01a in `/Users/kve/.codex/worktrees/mobius-prototype/Stuff` on `codex/mobius-prototype`; the coordinating agent owns the overview, affected production outlines, and the requested completion notice. Coordinate shared stack mutations at clean worktree points. Native implementation remains outside scope. -- Next action: Publish the integrated parent and reviewed [01a method](https://github.com/kyleve/Stuff/blob/codex/mobius-prototype/Plans/2026-11-14-mobius/01a-workspace-prototype.md#iteration-4-file-kinds-and-explicit-skip-method), then build and validate its fixture-backed behavior. The worker returns tested/published revisions, evidence, and any blocker; the coordinator verifies delivery and notifies the user. The 01a copy here is the pre-execution baseline; its implementation branch owns current methods/evidence. Native plans remain outlines. +- Next action: Complete [01a's delivery handoff](https://github.com/kyleve/Stuff/blob/codex/mobius-prototype/Plans/2026-11-14-mobius/01a-workspace-prototype.md#resume-point), verify published artifact/evidence revisions, and notify the user with the rebuilt demo and checks. Then integrate their evaluation before refining 01. The 01a copy here is the pre-execution baseline; its implementation branch owns current methods/evidence. Native plans remain outlines. ## Outcome and scope @@ -428,7 +428,7 @@ User answers came from this chat on 2026-11-14. Q-13–Q-24 refine the original - Request/source: On 2026-11-14, after trying the compact prototype, the user asked to differentiate changes by type, naming localization, Git LFS, Markdown, and code, and to list them differently. - Current proposal: Specialized presentations and concise summaries could accompany grouping by content kind. Localization could show changed keys/translations, Markdown rendered changes, assets visual previews/metadata, and code line diffs. These examples are proposals, not a selected first-release renderer catalog. - Asked: For a mixed PR, group by kind with quieter groups collapsed, show code first followed by other changes, or retain one file list with specialized previews? -- Blocking impact: Resolve the default organization and a bounded sample set before making a further 01a iteration executable. Later native classification/rendering belongs to 02/03 and Q-10. No new renderer implementation is authorized by this discovery record. +- Blocking impact: Resolve the default organization and a bounded sample set before making a further 01a iteration executable. Later native classification/rendering belongs to 02/03 and Q-10. No production renderer implementation is authorized by this discovery record. - Answer/source: The user selected grouping by kind, with quieter groups collapsed, on 2026-11-14. - Integration: US-09/R-13, [candidate views](#changes-by-kind-and-explicit-skipping), 02/03 and dependent source/feedback paths in 04/05. The bounded 01a method covers four groups and prepared views, without selecting a final native format catalog. - History: Opened, answered, integrated, and closed 2026-11-14 after the iteration-4 consistency/readiness review below. @@ -462,14 +462,15 @@ User answers came from this chat on 2026-11-14. Q-13–Q-24 refine the original - Readiness: 01a's implementation branch owns reviewed methods, status transitions, and evidence; its pre-execution copy here is historical. Iterations 1–3 and their feedback are retained. Iteration 4's bounded method is ready for the authorized browser work; product acceptance and native plans 01–07 remain pending. - Verification: All 168 local Markdown links/anchors resolve across nine planning-branch files; fences are balanced; all 14 requirements have implementing owners; the eight-plan dependency graph is acyclic; `git diff --check` passes. The revised 01a method was inspected on its owning branch. These checks validate the plan, not the proposed app. - Iteration-3 delivery review: The recorded final HTML hash is `f2adc670df7668d0c99d79f3ac0d9abeea3df701f56a53e1373de331c2eb274f`. Matched review-pane heights increased from 413 to 765 CSS pixels on desktop, 535 to 877 on tablet, and 216 to 648 on phone. Code text increased from 10 to 12 CSS pixels. Browser checks cover the retained review/workspace behavior and newly disclosed controls; independent review rechecked focus, accessible-title, dialog-lifecycle, and stacking corrections. No actionable finding remains. Full evidence stays in 01a rather than being duplicated here. -- Validation limits: Fourth-round implementation/evaluation remain pending. No native device test, VoiceOver, product API write, real code execution, persistence, or sync experiment has run. Swift is pseudocode. Mermaid was inspected as source; no local renderer was found. `./test` and `./swiftformat --lint` were skipped for this planning revision because only Markdown changed; browser checks belong to the prototype branch. +- Iteration-4 delivery review: Final HTML hash `fe137ea8e41335bbb0c25a203f6b27aac689bcdb2ce725420a63ab5b50dc8b00` has three-size workspace and grouped-change checks, including skip/undo, changed/new resurfacing, unchanged skips, actual-reviewed-baseline preservation, and rich/source comparison truth. Fresh independent review verified corrections to the individual Skip accessible name, LFS object-size labeling, and the corrected label's tablet layout; no actionable finding remains. A later-head baseline assertion uses seeded policy evidence, not a third UI fixture revision. The coordinator inspected representative renders and the final review record; 01a owns complete source/capture evidence and publication receipts. +- Validation limits: Fourth-round user evaluation remains pending. Browser accessibility checks cover recorded states; existing heading/landmark best-practice notices are recorded separately. No native device test, VoiceOver, product API write, real code execution, persistence, or sync experiment has run. Swift is pseudocode. Mermaid was inspected as source; no local renderer was found. `./test` and `./swiftformat --lint` were skipped for this planning revision because only Markdown changed; browser checks belong to the prototype branch. ## Review and delivery - Plan review: [PR #497](https://github.com/kyleve/Stuff/pull/497), ready for review. [STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app) remains In Review until merge and acceptance verification. -- Implementation: [PR #500](https://github.com/kyleve/Stuff/pull/500) and [STU-330](https://linear.app/kve/issue/STU-330/prototype-mobius-review-workspaces) own 01a's artifact, current method, and evidence. Three iterations are published; the fourth adds grouped typed views and explicit skip/undo. The worker/coordinator handoff includes the requested completion notification. Native plans 01–07 have not started. +- Implementation: [PR #500](https://github.com/kyleve/Stuff/pull/500) and [STU-330](https://linear.app/kve/issue/STU-330/prototype-mobius-review-workspaces) own 01a's artifact, current method, and evidence. The fourth iteration adds grouped typed views and explicit skip/undo and passes its recorded browser checks and independent review. Its execution record owns the publication receipt and requested completion-reporting handoff. Native plans 01–07 have not started. - Review focus: Logical PR workspaces independent of outer tabs/windows; multiple child views with independent navigation; arrangement/last-focus restoration; grouped typed comparisons with source access; skip versus reviewed and changed-file resurfacing; per-file remaining work and full-diff access; file-top review resumption; prototype learning before the durable model; sync as a release gate. ## Outcome -The plan now includes grouped content-appropriate comparisons and explicit PR-local skipping, with new changes returning to remaining work and actual reviewed baselines preserved. Three prototype iterations are published; a bounded fourth iteration will evaluate these additions while retaining compact chrome and logical workspace/child ownership. Plans 01–07 remain outlines informed by that evaluation and further production discussion. +The plan and fourth prototype iteration include grouped content-appropriate comparisons and explicit PR-local skipping, with new changes returning to remaining work and actual reviewed baselines preserved. The rebuilt demo retains compact chrome and logical workspace/child ownership and passes its recorded browser checks and independent review. User evaluation remains open. Plans 01–07 remain outlines informed by that evaluation and further production discussion. From 78f934d169ea7636f3d579d9c6d3df77566216e7 Mon Sep 17 00:00:00 2001 From: Kyle Van Essen Date: Sat, 14 Nov 2026 22:20:49 -0500 Subject: [PATCH 10/12] docs(Mobius): keep selected layouts truthful at every width --- .../02-application-workspace.md | 3 ++ Plans/2026-11-14-mobius/README.md | 37 +++++++++++++------ 2 files changed, 29 insertions(+), 11 deletions(-) diff --git a/Plans/2026-11-14-mobius/02-application-workspace.md b/Plans/2026-11-14-mobius/02-application-workspace.md index 33fc37ad7..a4379a839 100644 --- a/Plans/2026-11-14-mobius/02-application-workspace.md +++ b/Plans/2026-11-14-mobius/02-application-workspace.md @@ -32,6 +32,8 @@ Use 01a's evaluated interactions to distinguish switching PR workspaces from sel Apply the accepted [presentation-density decision](README.md#presentation-density): compact workspace identity and view controls, with full PR metadata and less frequent arrangement actions available on demand. Keep the active content title, actual comparison meaning, immediate review actions, and relevant warnings clear. On phone, a child selector can also provide the active view title. Reclaim space through fewer rows and repeated labels while preserving readable text, touch targets, accessible disclosures, keyboard commands, and focus return. Prototype-only Canvas/Reset/Simulate Push controls do not become production chrome. +Presentation controls must state their scope: how PR workspaces are presented versus how views inside one named PR are arranged. Current selections must match the visible result. [Q-25](README.md#q-25) selects honoring explicit Float at narrow widths; narrowing a workspace must not silently replace the chosen arrangement. Keep view controls reachable and preserve navigation/placement across width and outer-presentation changes. Native refinement must test combined modes against actual geometry and visibility, since outer windows change the available width for their child arrangement. The browser's exact framing/scroll behavior remains a prototype choice to evaluate. + Integrate the evaluated [changes-by-kind interaction](README.md#changes-by-kind-and-explicit-skipping): group the file list, initially collapse quieter groups, and expose concise remaining/reviewed/skipped counts with reachable files and undo. Collapse never changes progress. Each child retains its own selection and presentation while skip/review evidence belongs to the workspace. The bounded prototype uses “Skip remaining files” for a group's current remaining members; preserve that explicit scope when refining native actions. Typed content views and their source/metadata access must preserve comparison meaning without recreating large teaching headers. Initial native UI may use prepared projections; real format support, classification, and unavailable-content coverage depend on 03/Q-10. ```mermaid @@ -81,6 +83,7 @@ Declare Mobius's attribution inputs and bundled report through CreditKit's exist | 2026-11-14 | Restore logical workspaces with multiple child windows independently of outer tab/window presentation; retain arrangement and last focus. | First-artifact feedback and [Q-19–Q-21](README.md#q-19). | | 2026-11-14 | Prioritize useful content with compact workspace/view chrome and details on demand, preserving comparison meaning and accessible actions. | Accepted [iteration-2 density feedback](README.md#presentation-density); evaluated controls follow 01a iteration 3. | | 2026-11-14 | Group changes by kind and keep lower-attention groups collapsed; make skip/undo explicit and separate from reviewed. | [Q-22](README.md#q-22)–[Q-24](README.md#q-24); evaluate concrete views in 01a iteration 4. | +| 2026-11-14 | Keep explicit Float effective at narrow widths and make workspace versus child-view presentation scope clear; verify actual combined layouts. | Fourth-round prototype feedback and [Q-25](README.md#q-25). | ## Resume point diff --git a/Plans/2026-11-14-mobius/README.md b/Plans/2026-11-14-mobius/README.md index 90074fb8b..d7f44062b 100644 --- a/Plans/2026-11-14-mobius/README.md +++ b/Plans/2026-11-14-mobius/README.md @@ -3,13 +3,13 @@ ## Planning checkpoint - Updated: 2026-11-14; initial repository baseline `b629d56ac44a3f2a5ea59c3d6ae9cd5401f37674`; merged main through `96f5bf0f1685de259d7ff080842b8092f9a950d2` in `68477fe625784a1a1e68c0115d7e42cc63166692`. -- Operation: Revise the plan and run a bounded fourth prototype iteration for grouped, type-specific changes and explicit PR-local skipping. Native implementation is not requested. -- Requested scope and source: The user's 2026-11-14 request, Q-01–Q-21 discovery, accepted compact chrome, and new feedback to distinguish localization, Markdown, Git LFS, and code changes; see [question history](#questions-and-resolutions) and [presentation density](#presentation-density). -- Stage: Fourth-iteration delivery handoff; grouped comparisons and skip behavior are built and browser-verified, with user evaluation next. +- Operation: Diagnose and correct the prototype's misleading workspace/child-view presentation options. Native implementation is not requested. +- Requested scope and source: After the fourth prototype delivery on 2026-11-14, the user reports that selected Float/Tabs modes do not match the screen and that Float versus workspace Windows appears redundant. Preserve earlier Q-01–Q-24 decisions; [Q-25](#q-25) resolves narrow-width behavior. +- Stage: Q-25 integrated and closed; the focused correction method is reviewed and ready for the authorized prototype fix. - Completed: Q-22–Q-24 and affected production outlines are integrated and reviewed. The fourth prototype iteration is built; the three-size workspace/grouped-change scenarios and fresh independent review pass on the recorded final source. The coordinator inspected representative captures and the review record. Earlier artifacts/evidence remain intact. [01a's execution record](https://github.com/kyleve/Stuff/blob/codex/mobius-prototype/Plans/2026-11-14-mobius/01a-workspace-prototype.md#iteration-4-readiness-and-execution) owns detailed evidence and publication. [PR #497](https://github.com/kyleve/Stuff/pull/497)/[STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app) track the plan; [PR #500](https://github.com/kyleve/Stuff/pull/500)/[STU-330](https://linear.app/kve/issue/STU-330/prototype-mobius-review-workspaces) track the experiment. -- Pending: Finish the coordinated publication/completion-reporting handoff in 01a, then obtain fourth-round user evaluation. PR review and merge remain. Q-08–Q-12 retain their technical refinement gates. Browser verification does not establish product acceptance or native feasibility. -- Execution authorization and ownership: The user's next addition requests type-specific change presentation, refined by Q-22–Q-24, within the ongoing prototype work. `/root/mobius_prototype` owns `Prototype/**` and 01a in `/Users/kve/.codex/worktrees/mobius-prototype/Stuff` on `codex/mobius-prototype`; the coordinating agent owns the overview, affected production outlines, and the requested completion notice. Coordinate shared stack mutations at clean worktree points. Native implementation remains outside scope. -- Next action: Complete [01a's delivery handoff](https://github.com/kyleve/Stuff/blob/codex/mobius-prototype/Plans/2026-11-14-mobius/01a-workspace-prototype.md#resume-point), verify published artifact/evidence revisions, and notify the user with the rebuilt demo and checks. Then integrate their evaluation before refining 01. The 01a copy here is the pre-execution baseline; its implementation branch owns current methods/evidence. Native plans remain outlines. +- Pending: Fix and verify the option/rendering mismatch, then publish the updated demo and obtain user evaluation. PR review and merge remain. Q-08–Q-12 retain their technical refinement gates. Browser verification does not establish product acceptance or native feasibility. +- Execution authorization and ownership: The user's prototype bug report and Q-25 answer authorize this presentation correction within the ongoing prototype work. `/root/mobius_prototype` owns `Prototype/**` and 01a in `/Users/kve/.codex/worktrees/mobius-prototype/Stuff` on `codex/mobius-prototype`; the coordinating agent owns the overview, affected production outlines, and the completion notice. Coordinate shared stack mutations at clean worktree points. Native implementation remains outside scope. +- Next action: Cascade the reviewed parent/method, then implement explicit narrow Float and clear workspace/view control scope. Verify computed geometry/visibility against selected modes, including the width change caused by outer windows. The 01a copy here is the pre-execution baseline; its implementation branch owns current methods/evidence. Native plans remain outlines. ## Outcome and scope @@ -53,7 +53,7 @@ R-01–R-07 and R-12–R-14 derive from the user's product choices. R-08–R-11 | R-07 | Resume workspace contents, child-view navigation, progress, and draft work through private iCloud sync on the same Apple ID. Keep device window placement local and expose sync state; refine cross-device presentation policy under Q-09. | US-02, US-06 | [01](01-review-state-foundation.md) supplies identities; [06](06-icloud-resume-and-release.md) delivers sync | | R-08 | Preserve original failures, last usable data, and incomplete coverage. Older requests cannot overwrite active state. Missing history cannot imply “reviewed” or “no changes.” | US-07 | [01](01-review-state-foundation.md), [03](03-github-and-revision-comparison.md), [04](04-repository-exploration.md), [05](05-review-feedback.md), [06](06-icloud-resume-and-release.md) | | R-09 | Scope data by account and repository identity. Keep credentials in device-local Keychain; do not sync them or full repository caches. Protect private code and draft text from diagnostic export. | US-07 | [01](01-review-state-foundation.md), [03](03-github-and-revision-comparison.md), [06](06-icloud-resume-and-release.md) | -| R-10 | Prioritize code and preview content with compact workspace/view controls and details on demand, while keeping identity, comparison meaning, immediate actions, and relevant warnings clear. Preserve readable text and accessible touch/keyboard/VoiceOver interaction, accessibility text sizes, long lines, and large diffs. Define measured rendering/indexing budgets before the corresponding plan becomes ready. | US-01, US-04, US-06 | [01a](01a-workspace-prototype.md) explores density; [02](02-application-workspace.md), [03](03-github-and-revision-comparison.md), [04](04-repository-exploration.md) deliver it | +| R-10 | Prioritize code and preview content with compact workspace/view controls and details on demand, while keeping identity, comparison meaning, immediate actions, and relevant warnings clear. Presentation controls identify their PR-workspace or child-view scope and match the visible arrangement; explicit Float remains effective at narrow widths under Q-25. Preserve readable text and accessible touch/keyboard/VoiceOver interaction, accessibility text sizes, long lines, and large diffs. Define measured rendering/indexing budgets before the corresponding plan becomes ready. | US-01, US-04, US-06 | [01a](01a-workspace-prototype.md) explores density and presentation; [02](02-application-workspace.md), [03](03-github-and-revision-comparison.md), [04](04-repository-exploration.md) deliver it | | R-11 | Integrate module docs, manifests, tests, architecture boundaries, attribution, and CI. Release acceptance requires evidence on all three destinations and real cross-device sync. | Supporting constraint | [01](01-review-state-foundation.md), [02](02-application-workspace.md), [06](06-icloud-resume-and-release.md) | | R-12 | Evaluate a host-injected embedded reviewer and bounded live-context action; report feasibility and limitations without promising arbitrary PR execution. | US-08 | [07](07-embedded-review-experiment.md) | | R-13 | Group changes by content kind with quieter groups collapsed, and use content-appropriate diff presentations with source/metadata access. Keep counts and changed files discoverable. Rendering limitations must remain explicit; grouping or a rich preview cannot imply review. The initial viewer set is a prototype hypothesis, not an exhaustive native format promise. | US-09 | [01a](01a-workspace-prototype.md) explores grouped mixed fixtures; [02](02-application-workspace.md), [03](03-github-and-revision-comparison.md) deliver the native experience | @@ -127,6 +127,8 @@ The user evaluated iteration 2 and accepted the following direction on 2026-11-1 The target is a compact workspace bar and view toolbar with useful content immediately below. This is an information-priority decision, not a fixed pixel-height limit for native or accessibility layouts. Record comparable before/after content-space evidence across the three viewport sizes, and recheck reachability and focus for controls moved into disclosures. [02](02-application-workspace.md) carries this into native refinement; the prototype's exact controls remain subject to evaluation. +Fourth-round feedback exposes a separate presentation-control problem: outer workspace windows and floating child views must clearly identify their scope, and selected modes must agree with the actual visible arrangement. The old narrow-width fallback hides all but the focused child while retaining a saved wide-layout choice; showing that saved choice as the current layout is misleading. [Q-25](#q-25) selects honoring explicit Float at narrow widths too. Moving to outer workspace windows must not silently replace Float when each PR becomes narrower. Keep narrow floating views movable and their controls reachable; exact prototype frame/scroll affordances remain implementation choices. Verify actual child/window geometry and visibility when changing either control; checking stored IDs and selected values alone missed this case. + ### Changes by kind and explicit skipping Q-22 selects grouped changes with quieter groups collapsed. Q-23 adds explicit skip for this PR, separate from reviewed. Q-24 requires new changes to return to remaining work. Collapsing is presentation only; skipping records a deliberate choice about the current comparison without creating a review receipt. @@ -256,6 +258,7 @@ actor WorkspaceStore { | 2026-11-14 | Group changes by kind with quieter groups collapsed; investigate content-appropriate views in a bounded mixed-change prototype. | Q-22 and the user's type-aware diff request. | | 2026-11-14 | Skip current changes explicitly within this PR, separately from reviewed; new changes return while unchanged skips persist. Review baselines do not advance. | Q-23/Q-24; refines remaining-work eligibility while preserving Q-15's comparisons. | | 2026-11-14 | Prototype interaction choice: label group skipping “Skip remaining files” and snapshot only those current members, preserving reviewed files and future additions. | Coordinator's bounded implementation choice within Q-23/Q-24; evaluate alongside the grouped list. | +| 2026-11-14 | Honor explicitly selected Float at narrow workspace widths; distinguish PR workspace presentation from arrangements of views within a PR, with selected modes matching rendered behavior. | Fourth-round presentation feedback and [Q-25](#q-25). | | 2026-11-14 | Proposed: sync semantic workspace data and drafts; keep native geometry/focus and full code caches local. | R-07/R-09. | | 2026-11-14 | Proposed: atomic metadata storage, not a bounded journal as the only copy of user work. | JournalKit contract. | @@ -287,6 +290,7 @@ actor WorkspaceStore { | [Q-22](#q-22) | closed | How should file kinds change the default change list and presentation? | R-10/R-13, 01a, 02, 03 | Group by kind with quieter groups collapsed; bounded typed views are prototype hypotheses, native coverage remains with Q-10. | | [Q-23](#q-23) | closed | Does lower attention mean collapsed detail, explicit skipping, or remembered exclusions? | R-03/R-04/R-14, 01a, 01–06 | Explicit current skip/undo is separate from reviewed; group action captures currently remaining files, with no cross-PR rule. | | [Q-24](#q-24) | closed | Do new changes to a skipped kind return to remaining work? | R-03/R-04/R-14, 01a, 01, 03, 06 | Changed/new files return, unchanged skips persist, and actual reviewed baselines remain intact. Integrated and method-reviewed. | +| [Q-25](#q-25) | closed | Should Float work at narrow widths or become explicitly unavailable? | R-02/R-10, 01a, 02 | Honor Float at narrow widths too; integrated into scoped controls, real selected arrangements, and the reviewed correction method. | User answers came from this chat on 2026-11-14. Q-13–Q-24 refine the original answers without reopening the selected platforms, provider, or iCloud scope. The current horizon is prototype evaluation; concrete views and controls remain hypotheses to explore through it. @@ -451,6 +455,16 @@ User answers came from this chat on 2026-11-14. Q-13–Q-24 refine the original - Integration: R-14, [skip semantics](#changes-by-kind-and-explicit-skipping), 01/03/06 state and verification, and 01a's changed/unchanged/new fixture scenario. Skip never advances a reviewed baseline; production identity/conflict details remain at their existing refinement gates. - History: Opened, answered, integrated, and closed 2026-11-14 after the iteration-4 consistency/readiness review below. +### Q-25 + +- Request/source: On 2026-11-14, the user reported selected Float/Tabs options that did not match the visible result and confusion between floating views and workspace windows. +- Evidence: On published artifact `fe137ea8…`, 36 isolated browser combinations confirm that compact container rules override Tile/Float with a focused single view up to 680 CSS pixels, while options select the stored layout. At a 1440px viewport, switching only Tabs → Windows narrows the PR host from 1394px to 679px and changes three absolute-positioned Float children into one relative-positioned child. At 834px, Windows hosts become 430px with the same substitution. Both outer modes retain the same tab-looking strip. These reproduce the defect in fixture browsers; the user's live tab was unavailable to inspection. +- Asked: When a workspace is narrow, honor Float with movable overlapping views, or use one view and clearly disable Float until enough room exists? +- Blocking impact: The choice changes responsive behavior and current-mode reporting in 01a and later native refinement in 02. Keep the two-level workspace/child model from Q-19 and compact-chrome priorities intact. Actual OS windows remain outside the browser experiment. +- Answer/source: The user selected “Honor Float at narrow widths too” on 2026-11-14. +- Integration: R-10, [presentation controls](#presentation-density), 02, and [01a's bounded correction method](https://github.com/kyleve/Stuff/blob/codex/mobius-prototype/Plans/2026-11-14-mobius/01a-workspace-prototype.md#iteration-4-layout-options-correction) retain the two-level model and explicit layout behavior. The prototype's narrow stacked Tile and initial One view default are bounded implementation choices; explicit selected modes remain effective as width changes. +- History: Opened, answered, integrated, and closed 2026-11-14 after the correction-method review below. + ## Plan review - Initial review: 2026-11-14 against `b629d56ac44a3f2a5ea59c3d6ae9cd5401f37674`, covering the original eight files. Its readiness finding for 01 is superseded by Q-13–Q-18 and prototype-first sequencing. @@ -459,11 +473,12 @@ User answers came from this chat on 2026-11-14. Q-13–Q-24 refine the original - Iteration-2 review: 2026-11-14 against parent `68477fe625` plus this revision and the implementation branch's 01a method at `68926adfd`. Reviewed all affected production outlines and the current experiment method against Q-19–Q-21. Corrected the conflation of workspace, outer presentation, and child identity; moved review-file selection into each child; separated return focus from review resumption; and kept preview execution and cross-device presentation policy at their existing refinement gates. Multiple views share PR review evidence without sharing navigation. No remaining consistency or browser-method readiness finding was identified. - Iteration-3 review: 2026-11-14 against parent `fcee86b3b`, iteration-2 artifact `e1c1059cf28`, and the revised 01a method on the implementation branch. The accepted information priorities are integrated into R-10, the shared decision, and 02's native refinement. The method preserves comparison truth and all existing capabilities, repeats moved-control/focus checks, and requires matched content-space evidence. Background ownership and completion reporting are explicit. No remaining consistency or browser-method readiness finding was identified; native implementation and third-round acceptance remain pending. - Iteration-4 review: 2026-11-14 against parent `2c0926596` plus this revision and child method `0ff008a05e668dea373800208d2d7a8fd049a63f`. Traced Q-22–Q-24 through R-13/R-14 and affected 01–06 outlines. Kept kind presentation independent from review/skip evidence; restricted group skip to currently remaining members; retained actual reviewed baselines and independent child navigation; distinguished LFS storage from content kind; and preserved source/metadata coverage and unavailable-state honesty. The method bounds seven v1/eight v2 files per PR, with changed/unchanged/new cases, raw/rich comparison checks, all prior regressions, independent review, and three-size captures. No remaining consistency or method-readiness finding was identified. Native schemas, format support, rendering budgets, and merge policy remain provisional. -- Readiness: 01a's implementation branch owns reviewed methods, status transitions, and evidence; its pre-execution copy here is historical. Iterations 1–3 and their feedback are retained. Iteration 4's bounded method is ready for the authorized browser work; product acceptance and native plans 01–07 remain pending. -- Verification: All 168 local Markdown links/anchors resolve across nine planning-branch files; fences are balanced; all 14 requirements have implementing owners; the eight-plan dependency graph is acyclic; `git diff --check` passes. The revised 01a method was inspected on its owning branch. These checks validate the plan, not the proposed app. +- Layout-correction review: 2026-11-14 against parent `ce886cdab` plus this revision and child method `56a7a5e4795b58ffef95cb71ef23b71d8129e4fe`. Q-25 is integrated into R-10, the presentation contract, 02, and 01a. Reviewed explicit narrow Float, real stacked Tile, One view, scoped options, distinct outer-window navigation, and visible frame projection without rewriting saved placement on host resize. The method checks computed layout and narrow pointer/keyboard handles, including the old visible resize control that rejected narrow hosts. Earlier identity/state-only assertions missed this cross-mode defect. No remaining method-readiness finding; the focused browser correction still needs implementation, rendered checks, and fresh review. +- Readiness: 01a's implementation branch owns reviewed methods, status transitions, and evidence; its pre-execution copy here is historical. Four iterations and their feedback are retained. The focused layout-options correction is ready for authorized browser work; product acceptance and native plans 01–07 remain pending. +- Verification: All 173 local Markdown links/anchors resolve across nine planning-branch files; fences are balanced; all 14 requirements have implementing owners; the eight-plan dependency graph is acyclic; `git diff --check` passes. The revised 01a method was inspected on its owning branch. These checks validate the plan, not the proposed app. - Iteration-3 delivery review: The recorded final HTML hash is `f2adc670df7668d0c99d79f3ac0d9abeea3df701f56a53e1373de331c2eb274f`. Matched review-pane heights increased from 413 to 765 CSS pixels on desktop, 535 to 877 on tablet, and 216 to 648 on phone. Code text increased from 10 to 12 CSS pixels. Browser checks cover the retained review/workspace behavior and newly disclosed controls; independent review rechecked focus, accessible-title, dialog-lifecycle, and stacking corrections. No actionable finding remains. Full evidence stays in 01a rather than being duplicated here. - Iteration-4 delivery review: Final HTML hash `fe137ea8e41335bbb0c25a203f6b27aac689bcdb2ce725420a63ab5b50dc8b00` has three-size workspace and grouped-change checks, including skip/undo, changed/new resurfacing, unchanged skips, actual-reviewed-baseline preservation, and rich/source comparison truth. Fresh independent review verified corrections to the individual Skip accessible name, LFS object-size labeling, and the corrected label's tablet layout; no actionable finding remains. A later-head baseline assertion uses seeded policy evidence, not a third UI fixture revision. The coordinator inspected representative renders and the final review record; 01a owns complete source/capture evidence and publication receipts. -- Validation limits: Fourth-round user evaluation remains pending. Browser accessibility checks cover recorded states; existing heading/landmark best-practice notices are recorded separately. No native device test, VoiceOver, product API write, real code execution, persistence, or sync experiment has run. Swift is pseudocode. Mermaid was inspected as source; no local renderer was found. `./test` and `./swiftformat --lint` were skipped for this planning revision because only Markdown changed; browser checks belong to the prototype branch. +- Validation limits: The layout-options correction needs new runtime evidence and user evaluation; prior browser checks do not establish that fix. Browser accessibility checks cover recorded states; existing heading/landmark best-practice notices are recorded separately. No native device test, VoiceOver, product API write, real code execution, persistence, or sync experiment has run. Swift is pseudocode. Mermaid was inspected as source; no local renderer was found. `./test` and `./swiftformat --lint` were skipped for this planning revision because only Markdown changed; browser checks belong to the prototype branch. ## Review and delivery @@ -473,4 +488,4 @@ User answers came from this chat on 2026-11-14. Q-13–Q-24 refine the original ## Outcome -The plan and fourth prototype iteration include grouped content-appropriate comparisons and explicit PR-local skipping, with new changes returning to remaining work and actual reviewed baselines preserved. The rebuilt demo retains compact chrome and logical workspace/child ownership and passes its recorded browser checks and independent review. User evaluation remains open. Plans 01–07 remain outlines informed by that evaluation and further production discussion. +The plan and fourth prototype iteration include grouped content-appropriate comparisons and explicit PR-local skipping. Fourth-round evaluation exposed misleading presentation choices; Q-25 now requires explicit Float at narrow widths and the focused correction method is reviewed. The earlier browser evidence remains historical and does not validate this correction. Plans 01–07 remain outlines informed by the corrected prototype's evaluation and further production discussion. From dac83a2ab724a49082ef156860bc41737e459514 Mon Sep 17 00:00:00 2001 From: Kyle Van Essen Date: Sat, 14 Nov 2026 22:37:41 -0500 Subject: [PATCH 11/12] docs(Mobius): record verified layout correction handoff --- Plans/2026-11-14-mobius/README.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/Plans/2026-11-14-mobius/README.md b/Plans/2026-11-14-mobius/README.md index d7f44062b..34e80ffb8 100644 --- a/Plans/2026-11-14-mobius/README.md +++ b/Plans/2026-11-14-mobius/README.md @@ -5,11 +5,11 @@ - Updated: 2026-11-14; initial repository baseline `b629d56ac44a3f2a5ea59c3d6ae9cd5401f37674`; merged main through `96f5bf0f1685de259d7ff080842b8092f9a950d2` in `68477fe625784a1a1e68c0115d7e42cc63166692`. - Operation: Diagnose and correct the prototype's misleading workspace/child-view presentation options. Native implementation is not requested. - Requested scope and source: After the fourth prototype delivery on 2026-11-14, the user reports that selected Float/Tabs modes do not match the screen and that Float versus workspace Windows appears redundant. Preserve earlier Q-01–Q-24 decisions; [Q-25](#q-25) resolves narrow-width behavior. -- Stage: Q-25 integrated and closed; the focused correction method is reviewed and ready for the authorized prototype fix. -- Completed: Q-22–Q-24 and affected production outlines are integrated and reviewed. The fourth prototype iteration is built; the three-size workspace/grouped-change scenarios and fresh independent review pass on the recorded final source. The coordinator inspected representative captures and the review record. Earlier artifacts/evidence remain intact. [01a's execution record](https://github.com/kyleve/Stuff/blob/codex/mobius-prototype/Plans/2026-11-14-mobius/01a-workspace-prototype.md#iteration-4-readiness-and-execution) owns detailed evidence and publication. [PR #497](https://github.com/kyleve/Stuff/pull/497)/[STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app) track the plan; [PR #500](https://github.com/kyleve/Stuff/pull/500)/[STU-330](https://linear.app/kve/issue/STU-330/prototype-mobius-review-workspaces) track the experiment. -- Pending: Fix and verify the option/rendering mismatch, then publish the updated demo and obtain user evaluation. PR review and merge remain. Q-08–Q-12 retain their technical refinement gates. Browser verification does not establish product acceptance or native feasibility. +- Stage: Q-25 integrated and closed; the correction is built, browser-verified, and independently reviewed for coordinated delivery and user evaluation. +- Completed: Q-22–Q-25 and affected production outlines are integrated and reviewed. The fourth prototype iteration and its focused layout correction are built. The correction checks actual selected/rendered geometry, narrow movement/resize, and preserved workspace state; fresh independent review has no actionable findings. The coordinator verified the final HTML/capture hashes and inspected representative phone/tablet/desktop captures. Earlier artifacts/evidence remain intact. [01a's execution record](https://github.com/kyleve/Stuff/blob/codex/mobius-prototype/Plans/2026-11-14-mobius/01a-workspace-prototype.md#layout-correction-implementation-and-evidence) owns detailed evidence and publication. [PR #497](https://github.com/kyleve/Stuff/pull/497)/[STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app) track the plan; [PR #500](https://github.com/kyleve/Stuff/pull/500)/[STU-330](https://linear.app/kve/issue/STU-330/prototype-mobius-review-workspaces) track the experiment. +- Pending: Final publication receipts and completion handoff are owned by 01a. User evaluation, PR review, and merge remain. Q-08–Q-12 retain their technical refinement gates. Browser verification does not establish product acceptance or native feasibility. - Execution authorization and ownership: The user's prototype bug report and Q-25 answer authorize this presentation correction within the ongoing prototype work. `/root/mobius_prototype` owns `Prototype/**` and 01a in `/Users/kve/.codex/worktrees/mobius-prototype/Stuff` on `codex/mobius-prototype`; the coordinating agent owns the overview, affected production outlines, and the completion notice. Coordinate shared stack mutations at clean worktree points. Native implementation remains outside scope. -- Next action: Cascade the reviewed parent/method, then implement explicit narrow Float and clear workspace/view control scope. Verify computed geometry/visibility against selected modes, including the width change caused by outer windows. The 01a copy here is the pre-execution baseline; its implementation branch owns current methods/evidence. Native plans remain outlines. +- Next action: Publish the coordinated delivery checkpoint and stable evidence links, then notify the user and evaluate the corrected presentation. The 01a copy here is the pre-execution baseline; its implementation branch owns current methods, evidence, publication receipts, and its resume point. Native plans remain outlines. ## Outcome and scope @@ -292,7 +292,7 @@ actor WorkspaceStore { | [Q-24](#q-24) | closed | Do new changes to a skipped kind return to remaining work? | R-03/R-04/R-14, 01a, 01, 03, 06 | Changed/new files return, unchanged skips persist, and actual reviewed baselines remain intact. Integrated and method-reviewed. | | [Q-25](#q-25) | closed | Should Float work at narrow widths or become explicitly unavailable? | R-02/R-10, 01a, 02 | Honor Float at narrow widths too; integrated into scoped controls, real selected arrangements, and the reviewed correction method. | -User answers came from this chat on 2026-11-14. Q-13–Q-24 refine the original answers without reopening the selected platforms, provider, or iCloud scope. The current horizon is prototype evaluation; concrete views and controls remain hypotheses to explore through it. +User answers came from this chat on 2026-11-14. Q-13–Q-25 refine the original answers without reopening the selected platforms, provider, or iCloud scope. The current horizon is prototype evaluation; concrete views and controls remain hypotheses to explore through it. ### Q-01 @@ -473,19 +473,20 @@ User answers came from this chat on 2026-11-14. Q-13–Q-24 refine the original - Iteration-2 review: 2026-11-14 against parent `68477fe625` plus this revision and the implementation branch's 01a method at `68926adfd`. Reviewed all affected production outlines and the current experiment method against Q-19–Q-21. Corrected the conflation of workspace, outer presentation, and child identity; moved review-file selection into each child; separated return focus from review resumption; and kept preview execution and cross-device presentation policy at their existing refinement gates. Multiple views share PR review evidence without sharing navigation. No remaining consistency or browser-method readiness finding was identified. - Iteration-3 review: 2026-11-14 against parent `fcee86b3b`, iteration-2 artifact `e1c1059cf28`, and the revised 01a method on the implementation branch. The accepted information priorities are integrated into R-10, the shared decision, and 02's native refinement. The method preserves comparison truth and all existing capabilities, repeats moved-control/focus checks, and requires matched content-space evidence. Background ownership and completion reporting are explicit. No remaining consistency or browser-method readiness finding was identified; native implementation and third-round acceptance remain pending. - Iteration-4 review: 2026-11-14 against parent `2c0926596` plus this revision and child method `0ff008a05e668dea373800208d2d7a8fd049a63f`. Traced Q-22–Q-24 through R-13/R-14 and affected 01–06 outlines. Kept kind presentation independent from review/skip evidence; restricted group skip to currently remaining members; retained actual reviewed baselines and independent child navigation; distinguished LFS storage from content kind; and preserved source/metadata coverage and unavailable-state honesty. The method bounds seven v1/eight v2 files per PR, with changed/unchanged/new cases, raw/rich comparison checks, all prior regressions, independent review, and three-size captures. No remaining consistency or method-readiness finding was identified. Native schemas, format support, rendering budgets, and merge policy remain provisional. -- Layout-correction review: 2026-11-14 against parent `ce886cdab` plus this revision and child method `56a7a5e4795b58ffef95cb71ef23b71d8129e4fe`. Q-25 is integrated into R-10, the presentation contract, 02, and 01a. Reviewed explicit narrow Float, real stacked Tile, One view, scoped options, distinct outer-window navigation, and visible frame projection without rewriting saved placement on host resize. The method checks computed layout and narrow pointer/keyboard handles, including the old visible resize control that rejected narrow hosts. Earlier identity/state-only assertions missed this cross-mode defect. No remaining method-readiness finding; the focused browser correction still needs implementation, rendered checks, and fresh review. -- Readiness: 01a's implementation branch owns reviewed methods, status transitions, and evidence; its pre-execution copy here is historical. Four iterations and their feedback are retained. The focused layout-options correction is ready for authorized browser work; product acceptance and native plans 01–07 remain pending. +- Layout-correction method review: 2026-11-14 against parent `ce886cdab` plus readiness revision `56a9a3307` and child method `56a7a5e4795b58ffef95cb71ef23b71d8129e4fe`. Q-25 is integrated into R-10, the presentation contract, 02, and 01a. Reviewed explicit narrow Float, real stacked Tile, One view, scoped options, distinct outer-window navigation, and visible frame projection without rewriting saved placement on host resize. The method checks computed layout and narrow pointer/keyboard handles, including the old visible resize control that rejected narrow hosts. Earlier identity/state-only assertions missed this cross-mode defect. No method-readiness finding remained; the delivery evidence below records the subsequent implementation and checks. +- Readiness: 01a's implementation branch owns reviewed methods, status transitions, and evidence; its pre-execution copy here is historical. Four iterations and their feedback are retained. The focused layout-options correction is built and verified for delivery; user acceptance and native plans 01–07 remain pending. - Verification: All 173 local Markdown links/anchors resolve across nine planning-branch files; fences are balanced; all 14 requirements have implementing owners; the eight-plan dependency graph is acyclic; `git diff --check` passes. The revised 01a method was inspected on its owning branch. These checks validate the plan, not the proposed app. - Iteration-3 delivery review: The recorded final HTML hash is `f2adc670df7668d0c99d79f3ac0d9abeea3df701f56a53e1373de331c2eb274f`. Matched review-pane heights increased from 413 to 765 CSS pixels on desktop, 535 to 877 on tablet, and 216 to 648 on phone. Code text increased from 10 to 12 CSS pixels. Browser checks cover the retained review/workspace behavior and newly disclosed controls; independent review rechecked focus, accessible-title, dialog-lifecycle, and stacking corrections. No actionable finding remains. Full evidence stays in 01a rather than being duplicated here. - Iteration-4 delivery review: Final HTML hash `fe137ea8e41335bbb0c25a203f6b27aac689bcdb2ce725420a63ab5b50dc8b00` has three-size workspace and grouped-change checks, including skip/undo, changed/new resurfacing, unchanged skips, actual-reviewed-baseline preservation, and rich/source comparison truth. Fresh independent review verified corrections to the individual Skip accessible name, LFS object-size labeling, and the corrected label's tablet layout; no actionable finding remains. A later-head baseline assertion uses seeded policy evidence, not a third UI fixture revision. The coordinator inspected representative renders and the final review record; 01a owns complete source/capture evidence and publication receipts. -- Validation limits: The layout-options correction needs new runtime evidence and user evaluation; prior browser checks do not establish that fix. Browser accessibility checks cover recorded states; existing heading/landmark best-practice notices are recorded separately. No native device test, VoiceOver, product API write, real code execution, persistence, or sync experiment has run. Swift is pseudocode. Mermaid was inspected as source; no local renderer was found. `./test` and `./swiftformat --lint` were skipped for this planning revision because only Markdown changed; browser checks belong to the prototype branch. +- Layout-correction delivery review: Clean child checkpoint `af9aa242e81a786bddb27cf6566cdc02ca3f0d08` records HTML hash `93018f2fb35d28edb72daab1089a28dd849727658259bd177aa248f68a2e5f5b`. Thirty-six author and forty-two independent-review combinations check actual geometry and selected modes, including narrow hosts created by outer Windows. Pointer/keyboard move and resize, touch movement, handle reachability, non-overlapping Tile, explicit One view, and workspace/focus/review-state continuity pass. Fifteen author and twelve independent selected WCAG scans report no violations. Fresh review has no actionable findings. The coordinator checked all ten capture hashes, the original iteration-4 archive bytes, and representative rendered screens. Complete measurements and publication receipts stay with 01a. +- Validation limits: User evaluation of the corrected layout remains pending. The new runtime evidence covers isolated Chromium fixtures; the user's live browser was unavailable. Prior iteration-4 checks remain historical, and unchanged type-comparison fixtures were not rerun wholesale. Browser accessibility checks cover recorded states; existing heading/landmark best-practice notices are recorded separately. No native device test, VoiceOver, product API write, real code execution, persistence, or sync experiment has run. Swift is pseudocode. Mermaid was inspected as source; no local renderer was found. `./test` and `./swiftformat --lint` were skipped for this planning revision because only Markdown changed; browser checks belong to the prototype branch. ## Review and delivery - Plan review: [PR #497](https://github.com/kyleve/Stuff/pull/497), ready for review. [STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app) remains In Review until merge and acceptance verification. -- Implementation: [PR #500](https://github.com/kyleve/Stuff/pull/500) and [STU-330](https://linear.app/kve/issue/STU-330/prototype-mobius-review-workspaces) own 01a's artifact, current method, and evidence. The fourth iteration adds grouped typed views and explicit skip/undo and passes its recorded browser checks and independent review. Its execution record owns the publication receipt and requested completion-reporting handoff. Native plans 01–07 have not started. +- Implementation: [PR #500](https://github.com/kyleve/Stuff/pull/500) and [STU-330](https://linear.app/kve/issue/STU-330/prototype-mobius-review-workspaces) own 01a's artifact, current method, and evidence. The fourth iteration adds grouped typed views and explicit skip/undo; its focused correction makes the selected arrangement effective and separates PR-workspace presentation from child-view arrangement. Both have scoped browser evidence and independent review. Its execution record owns the publication receipt and requested completion-reporting handoff. Native plans 01–07 have not started. - Review focus: Logical PR workspaces independent of outer tabs/windows; multiple child views with independent navigation; arrangement/last-focus restoration; grouped typed comparisons with source access; skip versus reviewed and changed-file resurfacing; per-file remaining work and full-diff access; file-top review resumption; prototype learning before the durable model; sync as a release gate. ## Outcome -The plan and fourth prototype iteration include grouped content-appropriate comparisons and explicit PR-local skipping. Fourth-round evaluation exposed misleading presentation choices; Q-25 now requires explicit Float at narrow widths and the focused correction method is reviewed. The earlier browser evidence remains historical and does not validate this correction. Plans 01–07 remain outlines informed by the corrected prototype's evaluation and further production discussion. +The plan and fourth prototype iteration include grouped content-appropriate comparisons and explicit PR-local skipping. Fourth-round evaluation exposed misleading presentation choices; the Q-25 correction now honors explicit Float at narrow widths and makes the two control scopes clear. Focused browser evidence and independent review validate the correction for user evaluation. Plans 01–07 remain outlines informed by that evaluation and further production discussion. From 7de75a58a2ea5f9ee5366303f0664e132ad14c2b Mon Sep 17 00:00:00 2001 From: Kyle Van Essen Date: Sat, 14 Nov 2026 23:31:47 -0500 Subject: [PATCH 12/12] docs(Mobius): plan retained workspace close and reopen --- .../01-review-state-foundation.md | 7 +++ .../02-application-workspace.md | 8 ++- .../06-icloud-resume-and-release.md | 2 + Plans/2026-11-14-mobius/README.md | 51 ++++++++++++------- 4 files changed, 49 insertions(+), 19 deletions(-) diff --git a/Plans/2026-11-14-mobius/01-review-state-foundation.md b/Plans/2026-11-14-mobius/01-review-state-foundation.md index e9964b44c..d9b6647c0 100644 --- a/Plans/2026-11-14-mobius/01-review-state-foundation.md +++ b/Plans/2026-11-14-mobius/01-review-state-foundation.md @@ -31,6 +31,8 @@ Each workspace belongs to one typed account/repository/PR target, independent of A review child's resume value identifies its selected file; it does not persist a reviewed line range or require exact scroll restoration. Workspace restoration retains child arrangement and last-focused identity, so returning need not focus a review. Keep device presentation separate from semantic workspace contents; refine persistence and sync boundaries before fixing the schema. Per-file review evidence records the immutable comparison/version accepted by the explicit file-review action. A new push may make that file need review again, but must retain the earlier evidence needed to calculate its new edits. Unreviewed files have no reviewed baseline and show the full PR diff. +The [close/reopen lifecycle](README.md#closing-and-reopening-workspaces) requires retained workspaces to outlive their open presentation membership. Closing the last presentation does not erase child identities/routes, arrangement/focus, drafts, or review/skip evidence. Reopening refers to the same workspace, including an intentionally empty set of children. Represent an empty presented set and no active workspace explicitly. Refine durable open-state ownership and cross-device behavior under Q-09 before fixing its schema. + Keep [skip evidence](README.md#changes-by-kind-and-explicit-skipping) distinct from reviewed versions. Skipping captures a currently remaining file's comparison; the prototype's group action snapshots the currently remaining files in that group, never a rule excluding future members. Undo removes that skip without altering prior review evidence. Changed/new files return to remaining work while unchanged skips persist. A returning file uses its last actually reviewed baseline, including previously skipped edits, or the full PR diff if never reviewed. Group collapse, kind classification, and rich/source view choice are presentation and must not create review or skip evidence. Refine missing history, renamed files, comparison-context changes, and concurrent skip/undo/review mutations jointly with 03 before fixing identities or storage. The previous candidate was a serial store actor with version-checked mutations and atomic metadata replacement, separate from evictable source blobs/indexes. Retain it as an option to evaluate after the prototype; do not implement its schema just because it was previously specified. Production identity, errors, migrations, concurrency, and recovery need executable refinement. @@ -44,6 +46,7 @@ flowchart LR Revisions["Immutable current comparison and coverage"] --> Policy Model --> Children["Identified children with independent navigation"] Model --> Store["Candidate durable store"] + Presentation["Open workspace references; may be empty"] -->|close/reopen preserves retained identity| Model Children --> Store Evidence --> Store Skip --> Store @@ -73,6 +76,7 @@ struct FileReviewReceipt: Codable, Sendable { // Separate skip evidence refers to a current file comparison, not a new baseline. // Each review child retains its own ReviewResumeFile. // Presentation references workspace/child IDs; native scene IDs are separate. +// Closing presentation retains Workspace and its children for explicit reopening. // File identity across renames and comparison context requires refinement. ``` @@ -93,6 +97,8 @@ All named domain types are proposed. Receipt/content identity must distinguish b The eventual checks must demonstrate two independent PR workspaces reopening with their children, references, drafts, arrangements, and last-focused child; independent navigation in multiple children of the same kind; file-top review resumption; per-file new-edit/full-diff selection shared within the PR; preserved prior review evidence after a push; no cross-PR progress leakage; explicit baseline advancement; honest incomplete history; and failed/stale saves preserving accepted state. Changing outer presentation must preserve logical identities. Include real persistence round trips and controlled competing mutations. Use the matching Core tests, architecture checks, and formatting after targets exist; a zero-test pass is not acceptance. +Include explicit workspace close/reopen, all workspaces closed, repeated open without duplication, and reopening a workspace whose children were intentionally closed. Closing must not mutate review or skip baselines or draft text. Reopen must preserve the existing child identities and selected routes rather than seeding a fresh workspace. + Include individual/group skip, undo, relaunch, and a push with changed, unchanged, and newly introduced files. Assert separate remaining/reviewed/skipped counts and unchanged reviewed baselines. Cover stale actions from a child displaying an older comparison and competing skip/undo/review mutations; unavailable evidence must not produce a false reviewed or unchanged result. Classification and collapse alone must leave progress unchanged. ## Decisions and revisions @@ -104,6 +110,7 @@ Include individual/group skip, undo, relaunch, and a push with changed, unchange | 2026-11-14 | Return this deliverable to outline and refine it after a lightweight, three-layout prototype. | Q-16–Q-18. | | 2026-11-14 | Distinguish workspace, child-view, route, and presentation identities; restore arrangement and last focus, with a selected file per review child. | First-artifact feedback and [Q-19–Q-21](README.md#q-19). | | 2026-11-14 | Store current skips independently from reviewed versions; changed/new files return without resetting unrelated skips or advancing review evidence. | [Q-23](README.md#q-23)/[Q-24](README.md#q-24); exact production identities remain provisional. | +| 2026-11-14 | Separate retained workspace contents from open presentation membership; preserve work through explicit close/reopen and an all-closed state. | User's [workspace lifecycle feedback](README.md#closing-and-reopening-workspaces). | ## Execution record diff --git a/Plans/2026-11-14-mobius/02-application-workspace.md b/Plans/2026-11-14-mobius/02-application-workspace.md index a4379a839..23da6d06e 100644 --- a/Plans/2026-11-14-mobius/02-application-workspace.md +++ b/Plans/2026-11-14-mobius/02-application-workspace.md @@ -30,6 +30,8 @@ Create the Core runtime once in the process composition root. Scene presentation Use 01a's evaluated interactions to distinguish switching PR workspaces from selecting, opening, or arranging children inside one PR. Q-20 allows floating, tiling, docking, or tabs where useful; choose native defaults and platform affordances during refinement. Layouts and labels from the mockup remain candidates until validated natively. Mac outer windows use system scene APIs, with app-specific menu and shortcut routing through the focused workspace to its focused child. Separate child closure, closing a native window, and deleting a workspace. Restore arrangement and last-focused child on return; resuming a review child starts its file at the top. Exact review offsets are not required. +Provide explicit [workspace close and reopen](README.md#closing-and-reopening-workspaces) through the outer navigation and an accessible retained-workspace picker. A closed workspace keeps its contents; reopening restores the same child identities, routes, layout, focus, drafts, and review/skip state. Closing an inactive workspace keeps the current review in place. Closing the active one chooses another open workspace, and closing the last shows an intentional selection state with a reachable reopen action. Repeated opening must not duplicate the workspace. Refine native close/detach behavior when several scenes present one workspace; the browser's single presentation per PR does not settle those scene rules. + Apply the accepted [presentation-density decision](README.md#presentation-density): compact workspace identity and view controls, with full PR metadata and less frequent arrangement actions available on demand. Keep the active content title, actual comparison meaning, immediate review actions, and relevant warnings clear. On phone, a child selector can also provide the active view title. Reclaim space through fewer rows and repeated labels while preserving readable text, touch targets, accessible disclosures, keyboard commands, and focus return. Prototype-only Canvas/Reset/Simulate Push controls do not become production chrome. Presentation controls must state their scope: how PR workspaces are presented versus how views inside one named PR are arranged. Current selections must match the visible result. [Q-25](README.md#q-25) selects honoring explicit Float at narrow widths; narrowing a workspace must not silently replace the chosen arrangement. Keep view controls reachable and preserve navigation/placement across width and outer-presentation changes. Native refinement must test combined modes against actual geometry and visibility, since outer windows change the available width for their child arrangement. The browser's exact framing/scroll behavior remains a prototype choice to evaluate. @@ -43,6 +45,7 @@ flowchart LR Workspace --> Children["Identified review/source/research children"] Native["Existing UIKit scene lifecycle"] --> Presentation["Proposed outer tabs or workspace windows"] Presentation -->|references workspace IDs| Workspace + Picker["Retained workspace picker / empty state"] -->|reopen existing identity| Presentation Presentation -->|arrangement and focus by child ID| Children ``` @@ -65,7 +68,7 @@ Declare Mobius's attribution inputs and bundled report through CreditKit's exist - [Q-10](README.md#q-10): Select the code-text substrate and layout after measuring long lines, many documents, accessibility sizes, selection, and VoiceOver. Include grouped lists and bounded rich/source projections without committing to the prototype's format catalog. Identify real latency/memory budgets and fixture sizes before readiness. - [Q-11](README.md#q-11): Specify CLI Catalyst compile coverage and a native window/menu smoke test. Existing `./test` cannot be assumed to target Catalyst. Extend repository tooling only where required, with its public-command tests and owning docs. - Integrate Q-13–Q-15 and Q-19–Q-21: logical workspaces, multiple identified children, outer presentation independent from contents, last-focus/arrangement restoration, and clear remaining-work/full-PR navigation. Existing scroll-restoration machinery does not establish a requirement to restore an exact review offset. -- Refine close/detach/reopen behavior and any simultaneous presentations of one workspace before implementing them. The bounded mockup need not settle every native scene lifecycle rule. +- Integrate the evaluated close/reopen and all-closed flow. Refine native detach and simultaneous presentations of one workspace before implementation; the bounded mockup need not settle every scene lifecycle rule. Q-09 retains whether open/closed presentation follows other devices. ## Refinement trigger @@ -73,6 +76,8 @@ Declare Mobius's attribution inputs and bundled report through CreditKit's exist - Evidence needed: Working Core types, renderer/layout probe results, dependency closure, an explicit Catalyst build/runtime procedure, and an accessible tab/window interaction specification. Include usable content-space and moved-control reachability evidence at standard and accessibility layouts; a compact screenshot alone does not prove access to the hidden controls. Demonstrate mixed-kind navigation, quiet-group disclosure, skip/undo with distinct counts, unchanged independent child selection, and access to source or honest unavailable metadata. - Next action: Read the applicable UI/module/tooling contracts, expand this file into executable steps and acceptance criteria, and review it before implementation. Keep the first runtime demo synthetic and repeatable. +Verify active/inactive/last-workspace closure in each outer presentation, reopening with retained state and Review-top resumption, no duplicate opens, and keyboard/touch focus recovery. Distinguish a workspace with no children from an app with no open workspaces. A closed workspace must stay absent after layout changes or unrelated data refresh until explicitly reopened. + ## Decisions and revisions | Date | Decision | Source | @@ -84,6 +89,7 @@ Declare Mobius's attribution inputs and bundled report through CreditKit's exist | 2026-11-14 | Prioritize useful content with compact workspace/view chrome and details on demand, preserving comparison meaning and accessible actions. | Accepted [iteration-2 density feedback](README.md#presentation-density); evaluated controls follow 01a iteration 3. | | 2026-11-14 | Group changes by kind and keep lower-attention groups collapsed; make skip/undo explicit and separate from reviewed. | [Q-22](README.md#q-22)–[Q-24](README.md#q-24); evaluate concrete views in 01a iteration 4. | | 2026-11-14 | Keep explicit Float effective at narrow widths and make workspace versus child-view presentation scope clear; verify actual combined layouts. | Fourth-round prototype feedback and [Q-25](README.md#q-25). | +| 2026-11-14 | Expose workspace close/reopen and an all-closed selection state while retaining PR work and independent child state. | User's [workspace lifecycle feedback](README.md#closing-and-reopening-workspaces). | ## Resume point diff --git a/Plans/2026-11-14-mobius/06-icloud-resume-and-release.md b/Plans/2026-11-14-mobius/06-icloud-resume-and-release.md index ed190ff83..745d52eb3 100644 --- a/Plans/2026-11-14-mobius/06-icloud-resume-and-release.md +++ b/Plans/2026-11-14-mobius/06-icloud-resume-and-release.md @@ -50,6 +50,8 @@ protocol WorkspaceSynchronizing: Sendable { Proposed policy keeps native window bounds, child arrangement, last-focused child, and local scene IDs device-local. Returning to an existing local workspace restores that arrangement/focus under Q-21; a first open on another device needs an adaptive arrangement. Refine initial focus, order, and concurrent child-navigation behavior under Q-09 before fixing the sync schema. Preserve each review child's selected-file identity and resume it at the top; exact review scroll offsets are not part of the continuity contract. Remote work becomes available without unexpectedly opening windows or closing a focused local child during an edit. +The [workspace close/reopen flow](README.md#closing-and-reopening-workspaces) preserves semantic contents when presentation closes. Q-09 must decide whether open/closed workspace presentation is device-local or follows the user, including concurrent close/reopen across devices. The session-only prototype is not evidence for either sync policy. Closing presentation must not be encoded as deletion of the retained workspace, children, drafts, or review/skip records. + Account changes must stop the prior sync scope and isolate its files/records before any new scope starts. iCloud sign-out must not silently upload one account's drafts into another account. GitHub sign-out/revocation must prevent protected fetches and display, with an explicit policy for retained private drafts and caches. Preserve recoverable user work while resolving access; never infer fresh access from stale credentials. ## Questions and learning needed diff --git a/Plans/2026-11-14-mobius/README.md b/Plans/2026-11-14-mobius/README.md index 34e80ffb8..422d166d7 100644 --- a/Plans/2026-11-14-mobius/README.md +++ b/Plans/2026-11-14-mobius/README.md @@ -3,18 +3,20 @@ ## Planning checkpoint - Updated: 2026-11-14; initial repository baseline `b629d56ac44a3f2a5ea59c3d6ae9cd5401f37674`; merged main through `96f5bf0f1685de259d7ff080842b8092f9a950d2` in `68477fe625784a1a1e68c0115d7e42cc63166692`. -- Operation: Diagnose and correct the prototype's misleading workspace/child-view presentation options. Native implementation is not requested. -- Requested scope and source: After the fourth prototype delivery on 2026-11-14, the user reports that selected Float/Tabs modes do not match the screen and that Float versus workspace Windows appears redundant. Preserve earlier Q-01–Q-24 decisions; [Q-25](#q-25) resolves narrow-width behavior. -- Stage: Q-25 integrated and closed; the correction is built, browser-verified, and independently reviewed for coordinated delivery and user evaluation. -- Completed: Q-22–Q-25 and affected production outlines are integrated and reviewed. The fourth prototype iteration and its focused layout correction are built. The correction checks actual selected/rendered geometry, narrow movement/resize, and preserved workspace state; fresh independent review has no actionable findings. The coordinator verified the final HTML/capture hashes and inspected representative phone/tablet/desktop captures. Earlier artifacts/evidence remain intact. [01a's execution record](https://github.com/kyleve/Stuff/blob/codex/mobius-prototype/Plans/2026-11-14-mobius/01a-workspace-prototype.md#layout-correction-implementation-and-evidence) owns detailed evidence and publication. [PR #497](https://github.com/kyleve/Stuff/pull/497)/[STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app) track the plan; [PR #500](https://github.com/kyleve/Stuff/pull/500)/[STU-330](https://linear.app/kve/issue/STU-330/prototype-mobius-review-workspaces) track the experiment. -- Pending: Final publication receipts and completion handoff are owned by 01a. User evaluation, PR review, and merge remain. Q-08–Q-12 retain their technical refinement gates. Browser verification does not establish product acceptance or native feasibility. -- Execution authorization and ownership: The user's prototype bug report and Q-25 answer authorize this presentation correction within the ongoing prototype work. `/root/mobius_prototype` owns `Prototype/**` and 01a in `/Users/kve/.codex/worktrees/mobius-prototype/Stuff` on `codex/mobius-prototype`; the coordinating agent owns the overview, affected production outlines, and the completion notice. Coordinate shared stack mutations at clean worktree points. Native implementation remains outside scope. -- Next action: Publish the coordinated delivery checkpoint and stable evidence links, then notify the user and evaluate the corrected presentation. The 01a copy here is the pre-execution baseline; its implementation branch owns current methods, evidence, publication receipts, and its resume point. Native plans remain outlines. +- Operation: Add explicit closing and reopening of PR workspaces to the prototype and record the lifecycle in the production outlines. +- Requested scope and source: On 2026-11-14, the user reports that PR 42 and PR 43 cannot be dismissed and requests closing/reopening workspaces. This extends the existing retained-workspace and restoration decisions; it does not request native implementation. +- Stage: Close/reopen behavior is integrated into the shared contract and native outlines; 01a method `0768b8c0d` is reviewed and ready for the authorized prototype work. +- Completed: The title-bar follow-up is also published at `f21e01fec` with receipt `ac4ac4478`; its focused browser checks, independent review, and scoped Chromium/WebKit check pass. Q-22–Q-25 and affected production outlines are integrated and reviewed. The fourth prototype iteration and its focused layout correction are built. The correction checks actual selected/rendered geometry, narrow movement/resize, and preserved workspace state; fresh independent review has no actionable findings. The coordinator verified the final HTML/capture hashes and inspected representative phone/tablet/desktop captures. Earlier artifacts/evidence remain intact. [01a's execution record](https://github.com/kyleve/Stuff/blob/codex/mobius-prototype/Plans/2026-11-14-mobius/01a-workspace-prototype.md#layout-correction-implementation-and-evidence) owns detailed evidence and publication. [PR #497](https://github.com/kyleve/Stuff/pull/497)/[STU-329](https://linear.app/kve/issue/STU-329/plan-mobius-code-review-app) track the plan; [PR #500](https://github.com/kyleve/Stuff/pull/500)/[STU-330](https://linear.app/kve/issue/STU-330/prototype-mobius-review-workspaces) track the experiment. +- Pending: Cascade this parent revision into the clean method checkpoint, then implement, verify, and publish the demo. The implementation branch owns current 01a execution evidence and its checkpoint. User evaluation, PR review, and merge remain. Q-09 retains cross-device open/closed presentation policy. +- Execution authorization and ownership: The user's request authorizes this bounded prototype change. `/root/mobius_prototype` owns `Prototype/**` and 01a on `codex/mobius-prototype`; the coordinator owns shared requirements/native outlines on `codex/mobius-plan` and the completion notice. Cascade at a clean method checkpoint before UI edits. The implementation branch then owns the current execution checkpoint and publication receipt. Native implementation remains outside scope. +- Next action: Publish the coordinated plan/method and release prototype implementation. Its next evaluation covers active/inactive/last-workspace closure and retained-state reopening. The 01a copy here is the pre-execution baseline; its implementation branch owns current methods, evidence, and resume points. Native plans remain outlines. ## Outcome and scope Mobius keeps code review open as ongoing work. Each PR has its own logical workspace, which can be presented as a tab or a window. Inside it, reviewers can keep several windows open for review, source, research, and preview context. Returning restores that workspace's arrangement and last-focused window. Resuming a review window starts at the top of its selected file. A remaining-work view shows new edits in previously reviewed files and the full PR diff for unreviewed files; the full PR diff stays available for either. Each reviewed file has its own last-reviewed version. Nobody needs a temporary “got to here” GitHub comment. +A reviewer can close a PR workspace and reopen it later with the same children, arrangement, navigation, drafts, and review/skip evidence. Closing removes it from the presented tabs/windows while retaining its logical workspace. Closing the last one leaves a workspace-selection state with an accessible reopen action. + Changes are grouped by kind, with quieter groups collapsed and presentations suited to the underlying content. A reviewer can explicitly skip current changes for this PR without marking them reviewed. Skipped changes stay discoverable and undoable; new changes return to remaining work while unchanged skips persist. Skipping never advances the last actually reviewed version. PRs remain separate even when GitHub connects them in a stack. If a stack connection is shown, it is an informational link; it does not combine progress, drafts, comparison baselines, or submission actions. Stack discovery is not an additional first-release integration requirement. @@ -27,7 +29,7 @@ Embedding the reviewer inside an owning app, with a possible live execution surf | ID | Story | | --- | --- | -| US-01 | Keep independent PR workspaces as tabs or windows, each containing several review and research windows, so investigating one question does not discard another task. | +| US-01 | Open, close, and reopen independent PR workspaces as tabs or windows, each containing several review and research windows, so investigating one question does not discard another task. | | US-02 | Restore my workspace arrangement and last-focused window, with drafts and progress preserved; resume a review file from its top. | | US-03 | Distinguish unchanged reviewed work from new PR changes, so I can concentrate on what needs another pass. | | US-04 | Browse and search repository context without leaving the review workspace. | @@ -45,8 +47,8 @@ R-01–R-07 and R-12–R-14 derive from the user's product choices. R-08–R-11 | ID | Required behavior or constraint | Story | Implementing plan | | --- | --- | --- | --- | | R-01 | Run on iPhone, iPad, and Mac Catalyst, with Mac windows, menus, and keyboard commands. | US-06 | [02](02-application-workspace.md), [06](06-icloud-resume-and-release.md) | -| R-02 | Keep one independent logical workspace per PR, presentable as a tab or window. Each owns multiple child windows for review, source, and research, with room to investigate preview/live context. Support multiple views of the same kind with independent navigation. Switching PRs or outer presentation preserves their contents. Stack connections, if shown, are informational. | US-01, US-04 | [01a](01a-workspace-prototype.md) explores interaction and simulated previews; [01](01-review-state-foundation.md), [02](02-application-workspace.md), [04](04-repository-exploration.md) deliver the workspace; [07](07-embedded-review-experiment.md) investigates live context | -| R-03 | Persist child-window identity/navigation, per-file reviewed versions, current skip evidence, and drafts across relaunch. Returning restores the workspace arrangement and last-focused child. Resuming a review child starts at its selected file's top; precise in-file position and reviewed-range tracking are not required. Review progress belongs to the PR workspace; skipped, reviewed, and submitted GitHub feedback remain separate facts. | US-02, US-10 | [01a](01a-workspace-prototype.md) explores interaction; [01](01-review-state-foundation.md), [02](02-application-workspace.md), [05](05-review-feedback.md) deliver it | +| R-02 | Keep one independent logical workspace per PR, presentable as a tab or window. Each owns multiple child windows for review, source, and research, with room to investigate preview/live context. Support multiple views of the same kind with independent navigation. Switching PRs or outer presentation preserves their contents. Allow closing and reopening retained workspaces, including closing the last one into an explicit selection state. Stack connections, if shown, are informational. | US-01, US-04 | [01a](01a-workspace-prototype.md) explores interaction and simulated previews; [01](01-review-state-foundation.md), [02](02-application-workspace.md), [04](04-repository-exploration.md) deliver the workspace; [07](07-embedded-review-experiment.md) investigates live context | +| R-03 | Persist child-window identity/navigation, per-file reviewed versions, current skip evidence, and drafts across relaunch. Returning, including after explicitly closing and reopening a workspace, restores its children, arrangement, navigation, and last-focused child without losing drafts or review/skip evidence. Resuming a review child starts at its selected file's top; precise in-file position and reviewed-range tracking are not required. Review progress belongs to the PR workspace; skipped, reviewed, and submitted GitHub feedback remain separate facts. | US-02, US-10 | [01a](01a-workspace-prototype.md) explores interaction; [01](01-review-state-foundation.md), [02](02-application-workspace.md), [05](05-review-feedback.md) deliver it | | R-04 | Within one PR, remaining work combines new edits since each reviewed file's last-reviewed version with the full PR diff for unreviewed files, excluding current explicit skips under R-14 while keeping them discoverable. Let every file open its full PR diff. An explicit file-review action advances that file's baseline; navigation, grouping, skipping, and refresh do not. | US-03, US-10 | [01a](01a-workspace-prototype.md) explores interaction; [01](01-review-state-foundation.md), [03](03-github-and-revision-comparison.md) deliver it | | R-05 | Browse files and search paths and text at an identified repository revision within Mobius. Open results in child windows without replacing the review and show search coverage. Independent views may inspect the same file or separate queries. | US-04 | [04](04-repository-exploration.md) | | R-06 | Read review discussion; compose and explicitly submit comments, approvals, and requests for changes with revision validation and recoverable drafts. | US-05 | [03](03-github-and-revision-comparison.md), [05](05-review-feedback.md) | @@ -104,7 +106,7 @@ Consulted 2026-11-14. External sources establish documented capabilities, not li ### Discovery scenario -PR 42 and PR 43 each have their own workspace. Within PR 42, open a review, two source or research windows, and a simulated preview. Each child retains its own navigation and state. Arrange the children, focus a research window, and switch to PR 43. Returning to PR 42 restores its arrangement and the research window's focus. Selecting the review again opens its selected file at the top. Present PR 42 as a workspace tab or an outer window without recreating its children. A stack link between the PRs does not merge their work. +PR 42 and PR 43 each have their own workspace. Within PR 42, open a review, two source or research windows, and a simulated preview. Each child retains its own navigation and state. Arrange the children, focus a research window, and switch to PR 43. Returning to PR 42 restores its arrangement and the research window's focus. Selecting the review again opens its selected file at the top. Present PR 42 as a workspace tab or an outer window without recreating its children. A stack link between the PRs does not merge their work. Close PR 42, continue with PR 43, and reopen PR 42 from the retained-workspace picker with its prior state. Closing PR 43 while PR 42 is active does not switch focus. Closing the last presented workspace leaves an intentional empty state; reopening restores the same logical workspace rather than creating a duplicate. Within PR 42, mark `Parser.swift` reviewed at version 1 and leave `Store.swift` unreviewed. A simulated push supplies version 2. Remaining work shows the version-1-to-version-2 edits for `Parser.swift` and the full current PR diff for `Store.swift`. Either can open its full PR diff. Marking `Parser.swift` reviewed again advances only its baseline. These are files within one PR, not three separate reviews. @@ -129,6 +131,14 @@ The target is a compact workspace bar and view toolbar with useful content immed Fourth-round feedback exposes a separate presentation-control problem: outer workspace windows and floating child views must clearly identify their scope, and selected modes must agree with the actual visible arrangement. The old narrow-width fallback hides all but the focused child while retaining a saved wide-layout choice; showing that saved choice as the current layout is misleading. [Q-25](#q-25) selects honoring explicit Float at narrow widths too. Moving to outer workspace windows must not silently replace Float when each PR becomes narrower. Keep narrow floating views movable and their controls reachable; exact prototype frame/scroll affordances remain implementation choices. Verify actual child/window geometry and visibility when changing either control; checking stored IDs and selected values alone missed this case. +### Closing and reopening workspaces + +The user requested dismissible PR workspaces after evaluating the title-bar correction on 2026-11-14. R-02/R-03 now explicitly separate retained workspace content from the set currently presented. Close removes an outer tab/window; reopen restores the same workspace and its child identities, arrangement, last focus, routes, drafts, and review/skip evidence. File-top review resumption still applies. Closing a child remains a separate operation. The last-workspace empty state must offer a reachable reopen path. + +For the bounded browser experiment, use a close action on each PR tab/window and an always-available workspace picker that can switch to an open workspace or reopen a closed one. Selecting an already-open workspace does not duplicate it. Closing the active workspace selects a remaining neighbor; closing an inactive workspace keeps the active PR and its context. These controls and neighbor choice are prototype implementation choices for evaluation. Retain only the existing two sample workspaces in memory; Reset restores the initial sample session. Closing/reopening needs no new persistence or provider call. + +[01](01-review-state-foundation.md) keeps retained identities and content separate from presentation membership; [02](02-application-workspace.md) owns accessible close/reopen and empty-state behavior. Whether open/closed presentation follows a user across devices remains within [Q-09](#q-09) and [06](06-icloud-resume-and-release.md); the local mockup does not decide that policy. The existing baseline, child, and draft semantics already determine what must survive, so this request introduces no blocking product question for the browser flow. + ### Changes by kind and explicit skipping Q-22 selects grouped changes with quieter groups collapsed. Q-23 adds explicit skip for this PR, separate from reviewed. Q-24 requires new changes to return to remaining work. Collapsing is presentation only; skipping records a deliberate choice about the current comparison without creating a review receipt. @@ -150,7 +160,7 @@ Each child retains independent selection/view mode; classification and skip/prog ### Product concepts -- **Workspace:** the logical owner of one PR's child windows, progress, and drafts. Its identity does not depend on being presented as a workspace tab or outer window. Another PR has a separate workspace, including when the PRs belong to a stack. +- **Workspace:** the logical owner of one PR's child windows, progress, and drafts. Its identity does not depend on being presented as a workspace tab or outer window, or on currently being open. Closing its presentation retains its contents for reopening. Another PR has a separate workspace, including when the PRs belong to a stack. - **Child window/view:** an identified instance inside a workspace, with its own navigation and state. Several can show the same kind of content or the same file. Review progress remains shared within the owning PR. A child window is not inherently a native OS scene. - **Document route:** the content a child shows, with account/repository identity and an explicit revision policy. View identity is separate from route identity; pinned source content must not silently follow moving branches. - **Presentation:** outer workspace tabs/windows plus each workspace's child arrangement and last-focused child. Returning restores that local arrangement and focus. Tiling, floating, docking, and tabs are available directions to evaluate, not a settled native window-manager specification. Synced work becomes available without stealing focus or automatically spawning windows. @@ -165,7 +175,7 @@ Each child retains independent selection/view mode; classification and skip/prog Start with `MobiusCore`, `MobiusUI`, and a thin `Mobius` app host. These are proposed names, not existing APIs. -Core owns typed workspace/child identities, revision/progress policy, local storage, provider protocols, GitHub transport, and sync policy in focused source directories. UI owns observable presentation, Broadway styling, code-rendering adapters, and navigation. Outer scene identity, logical workspace identity, and child-view identity are distinct. The process composition root creates one runtime and injects it into each scene. Views do not open stores or create shared services. +Core owns typed workspace/child identities, revision/progress policy, local storage, provider protocols, GitHub transport, and sync policy in focused source directories. UI owns observable presentation, Broadway styling, code-rendering adapters, and navigation. Outer scene identity, logical workspace identity, and child-view identity are distinct. Presentation membership can be empty while the store retains workspaces for reopening. The process composition root creates one runtime and injects it into each scene. Views do not open stores or create shared services. The earlier candidate store is a serial actor with an atomically replaced, versioned metadata file, separate from evictable source blobs and indexes. Its concrete model and technology remain provisional until the mockup is evaluated. Stable identities, honest errors, and preservation of accepted user work remain constraints for later refinement. @@ -174,6 +184,8 @@ flowchart LR GitHub["GitHub API: existing external"] -->|revision data| Core["MobiusCore: proposed services"] Core -->|snapshots and failures| UI["MobiusUI: proposed scene models"] UI -->|intents| Core + Presented["Proposed open workspace references; may be empty"] --> UI + Store -->|retained workspaces to reopen| UI Core -->|atomic metadata save| Store["WorkspaceStore: proposed actor"] Store -->|durable snapshot| Core Core -->|evictable source objects| Cache["Proposed local cache"] @@ -204,6 +216,7 @@ final class WorkspaceModel { var presentation: WorkspacePresentation // Local arrangement and focused child. // Child navigation is keyed by WorkspaceChild.ID, not document kind. // Outer scenes/tabs refer to this workspace identity. + // Closing presentation removes that reference, not the retained workspace. } actor WorkspaceStore { @@ -259,6 +272,7 @@ actor WorkspaceStore { | 2026-11-14 | Skip current changes explicitly within this PR, separately from reviewed; new changes return while unchanged skips persist. Review baselines do not advance. | Q-23/Q-24; refines remaining-work eligibility while preserving Q-15's comparisons. | | 2026-11-14 | Prototype interaction choice: label group skipping “Skip remaining files” and snapshot only those current members, preserving reviewed files and future additions. | Coordinator's bounded implementation choice within Q-23/Q-24; evaluate alongside the grouped list. | | 2026-11-14 | Honor explicitly selected Float at narrow workspace widths; distinguish PR workspace presentation from arrangements of views within a PR, with selected modes matching rendered behavior. | Fourth-round presentation feedback and [Q-25](#q-25). | +| 2026-11-14 | Close and reopen PR workspaces while retaining their work; support an explicit all-closed selection state. Concrete picker/close controls and neighbor selection remain prototype choices. | User request after the title-bar correction; [workspace lifecycle](#closing-and-reopening-workspaces). | | 2026-11-14 | Proposed: sync semantic workspace data and drafts; keep native geometry/focus and full code caches local. | R-07/R-09. | | 2026-11-14 | Proposed: atomic metadata storage, not a bounded journal as the only copy of user work. | JournalKit contract. | @@ -346,7 +360,7 @@ User answers came from this chat on 2026-11-14. Q-13–Q-25 refine the original ### Q-09 - Answer/source: iCloud transport is selected; record and merge policies remain unresolved. -- Integration: 05 owns publication intent/receipt identity and must settle cross-device submission ownership before readiness. 06 owns engine-state persistence, account partitioning, close/reorder races, and conflicting draft edits. Preserve both texts on concurrent draft conflict. +- Integration: 05 owns publication intent/receipt identity and must settle cross-device submission ownership before readiness. 06 owns engine-state persistence, account partitioning, close/reorder races, and conflicting draft edits. The new local workspace close/reopen flow also requires deciding whether open/closed presentation membership follows another device before fixing its sync representation. Preserve both texts on concurrent draft conflict. - Deferral: Design publication ownership before implementing 05 and the full record/merge policy before 06, using 01's stable IDs. Revise earlier schemas if the evidence requires it. CKSyncEngine is a candidate transport, not a conflict policy. - History: Opened and deferred on 2026-11-14. @@ -474,12 +488,13 @@ User answers came from this chat on 2026-11-14. Q-13–Q-25 refine the original - Iteration-3 review: 2026-11-14 against parent `fcee86b3b`, iteration-2 artifact `e1c1059cf28`, and the revised 01a method on the implementation branch. The accepted information priorities are integrated into R-10, the shared decision, and 02's native refinement. The method preserves comparison truth and all existing capabilities, repeats moved-control/focus checks, and requires matched content-space evidence. Background ownership and completion reporting are explicit. No remaining consistency or browser-method readiness finding was identified; native implementation and third-round acceptance remain pending. - Iteration-4 review: 2026-11-14 against parent `2c0926596` plus this revision and child method `0ff008a05e668dea373800208d2d7a8fd049a63f`. Traced Q-22–Q-24 through R-13/R-14 and affected 01–06 outlines. Kept kind presentation independent from review/skip evidence; restricted group skip to currently remaining members; retained actual reviewed baselines and independent child navigation; distinguished LFS storage from content kind; and preserved source/metadata coverage and unavailable-state honesty. The method bounds seven v1/eight v2 files per PR, with changed/unchanged/new cases, raw/rich comparison checks, all prior regressions, independent review, and three-size captures. No remaining consistency or method-readiness finding was identified. Native schemas, format support, rendering budgets, and merge policy remain provisional. - Layout-correction method review: 2026-11-14 against parent `ce886cdab` plus readiness revision `56a9a3307` and child method `56a7a5e4795b58ffef95cb71ef23b71d8129e4fe`. Q-25 is integrated into R-10, the presentation contract, 02, and 01a. Reviewed explicit narrow Float, real stacked Tile, One view, scoped options, distinct outer-window navigation, and visible frame projection without rewriting saved placement on host resize. The method checks computed layout and narrow pointer/keyboard handles, including the old visible resize control that rejected narrow hosts. Earlier identity/state-only assertions missed this cross-mode defect. No method-readiness finding remained; the delivery evidence below records the subsequent implementation and checks. -- Readiness: 01a's implementation branch owns reviewed methods, status transitions, and evidence; its pre-execution copy here is historical. Four iterations and their feedback are retained. The focused layout-options correction is built and verified for delivery; user acceptance and native plans 01–07 remain pending. -- Verification: All 173 local Markdown links/anchors resolve across nine planning-branch files; fences are balanced; all 14 requirements have implementing owners; the eight-plan dependency graph is acyclic; `git diff --check` passes. The revised 01a method was inspected on its owning branch. These checks validate the plan, not the proposed app. +- Workspace-lifecycle review: 2026-11-14 against parent `8021dc5cc` plus this revision and child method `0768b8c0d2adb8bda2054d57833aa2d2b4580bb0`. Traced explicit close/reopen through R-02/R-03, the discovery scenario, retained versus presented ownership, and outlines 01/02/06. Reviewed active/inactive/last closure, same-identity reopening, empty-child restoration, file-top review return, compact accessible controls, and protection from implicit reopens. The two-PR in-memory experiment remains bounded; Q-09 retains cross-device membership policy. No plan-consistency or method-readiness finding remains. +- Readiness: 01a's implementation branch owns reviewed methods, status transitions, and evidence; its pre-execution copy here is historical. Four iterations and their corrections are retained. The close/reopen method is ready for authorized browser implementation; runtime evidence and user evaluation remain pending. Native plans 01–07 remain outlines. +- Verification: All 182 local Markdown links/anchors resolve across nine planning-branch files; fences are balanced; all 14 requirements have implementing owners; the eight-plan dependency graph is acyclic; `git diff --check` passes. The revised 01a method was inspected on its owning branch. These checks validate the plan, not the proposed app. - Iteration-3 delivery review: The recorded final HTML hash is `f2adc670df7668d0c99d79f3ac0d9abeea3df701f56a53e1373de331c2eb274f`. Matched review-pane heights increased from 413 to 765 CSS pixels on desktop, 535 to 877 on tablet, and 216 to 648 on phone. Code text increased from 10 to 12 CSS pixels. Browser checks cover the retained review/workspace behavior and newly disclosed controls; independent review rechecked focus, accessible-title, dialog-lifecycle, and stacking corrections. No actionable finding remains. Full evidence stays in 01a rather than being duplicated here. - Iteration-4 delivery review: Final HTML hash `fe137ea8e41335bbb0c25a203f6b27aac689bcdb2ce725420a63ab5b50dc8b00` has three-size workspace and grouped-change checks, including skip/undo, changed/new resurfacing, unchanged skips, actual-reviewed-baseline preservation, and rich/source comparison truth. Fresh independent review verified corrections to the individual Skip accessible name, LFS object-size labeling, and the corrected label's tablet layout; no actionable finding remains. A later-head baseline assertion uses seeded policy evidence, not a third UI fixture revision. The coordinator inspected representative renders and the final review record; 01a owns complete source/capture evidence and publication receipts. - Layout-correction delivery review: Clean child checkpoint `af9aa242e81a786bddb27cf6566cdc02ca3f0d08` records HTML hash `93018f2fb35d28edb72daab1089a28dd849727658259bd177aa248f68a2e5f5b`. Thirty-six author and forty-two independent-review combinations check actual geometry and selected modes, including narrow hosts created by outer Windows. Pointer/keyboard move and resize, touch movement, handle reachability, non-overlapping Tile, explicit One view, and workspace/focus/review-state continuity pass. Fifteen author and twelve independent selected WCAG scans report no violations. Fresh review has no actionable findings. The coordinator checked all ten capture hashes, the original iteration-4 archive bytes, and representative rendered screens. Complete measurements and publication receipts stay with 01a. -- Validation limits: User evaluation of the corrected layout remains pending. The new runtime evidence covers isolated Chromium fixtures; the user's live browser was unavailable. Prior iteration-4 checks remain historical, and unchanged type-comparison fixtures were not rerun wholesale. Browser accessibility checks cover recorded states; existing heading/landmark best-practice notices are recorded separately. No native device test, VoiceOver, product API write, real code execution, persistence, or sync experiment has run. Swift is pseudocode. Mermaid was inspected as source; no local renderer was found. `./test` and `./swiftformat --lint` were skipped for this planning revision because only Markdown changed; browser checks belong to the prototype branch. +- Validation limits: Close/reopen runtime verification and user evaluation remain pending; prior layout/title-bar checks do not cover the new lifecycle paths. User evaluation of the corrected layout remains pending. The new runtime evidence covers isolated Chromium fixtures; the user's live browser was unavailable. Prior iteration-4 checks remain historical, and unchanged type-comparison fixtures were not rerun wholesale. Browser accessibility checks cover recorded states; existing heading/landmark best-practice notices are recorded separately. No native device test, VoiceOver, product API write, real code execution, persistence, or sync experiment has run. Swift is pseudocode. Mermaid was inspected as source; no local renderer was found. `./test` and `./swiftformat --lint` were skipped for this planning revision because only Markdown changed; browser checks belong to the prototype branch. ## Review and delivery @@ -489,4 +504,4 @@ User answers came from this chat on 2026-11-14. Q-13–Q-25 refine the original ## Outcome -The plan and fourth prototype iteration include grouped content-appropriate comparisons and explicit PR-local skipping. Fourth-round evaluation exposed misleading presentation choices; the Q-25 correction now honors explicit Float at narrow widths and makes the two control scopes clear. Focused browser evidence and independent review validate the correction for user evaluation. Plans 01–07 remain outlines informed by that evaluation and further production discussion. +The plan now explicitly supports closing and reopening PR workspaces while retaining their contents, including a useful all-closed state. The bounded prototype method is reviewed and implementation is authorized. Earlier grouped-change, layout, and title-bar evidence remains intact; it does not validate the new close/reopen paths. Plans 01–07 remain outlines informed by the updated prototype's evaluation and further production discussion.