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..d9b6647c0 --- /dev/null +++ b/Plans/2026-11-14-mobius/01-review-state-foundation.md @@ -0,0 +1,125 @@ +# 01 — Review-state foundation + +- Status: outline +- Depends on: [01a — Workspace prototype](01a-workspace-prototype.md). +- Shared context: [Overview](README.md). + +## Intended outcome + +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. + +## User stories and requirements + +| Story | Requirement | Intended contribution | +| --- | --- | --- | +| 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. | + +[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. + +## Known boundaries and candidate design + +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, 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 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. + +```mermaid +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"] + Presentation["Open workspace references; may be empty"] -->|close/reopen preserves retained identity| Model + Children --> Store + Evidence --> Store + Skip --> Store + Store --> Resume["Arrangement and focused child; review file at top"] + Policy --> Result["Remaining / reviewed / skipped, with comparison coverage"] +``` + +```swift +// 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 +} + +struct ReviewResumeFile: Codable, Sendable { + let file: ReviewFile.ID +} + +struct FileReviewReceipt: Codable, Sendable { + let target: ReviewTarget + let file: ReviewFile.ID + let reviewedComparison: FileComparisonIdentity + 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. +// Closing presentation retains Workspace and its children for explicit reopening. +// File identity across renames and comparison context requires refinement. +``` + +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. + +## Questions and learning needed + +- [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. + +## 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/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 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 + +| Date | Decision | Source | +| --- | --- | --- | +| 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). | +| 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 + +Not started. No module, schema, Xcode project generation, or implementation test was produced by planning. + +## Resume point + +Await 01a evidence, integrate it, then refine this outline and repeat review before execution. + +## Outcome + +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 new file mode 100644 index 000000000..23da6d06e --- /dev/null +++ b/Plans/2026-11-14-mobius/02-application-workspace.md @@ -0,0 +1,96 @@ +# 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 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 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 | 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. + +## 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. 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 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. + +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"] + 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 + Picker["Retained workspace picker / empty state"] -->|reopen existing identity| Presentation + Presentation -->|arrangement and focus by child ID| Children +``` + +```swift +// Proposed composition sketch; API details await 01. +@MainActor +func makeWorkspaceModel(workspaceID: Workspace.ID, runtime: MobiusRuntime) -> WorkspaceModel { + WorkspaceModel(workspaceID: workspaceID, runtime: runtime) +} +// 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. + +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. 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. +- 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 + +- 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. 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 | +| --- | --- | --- | +| 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). | +| 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 + +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..aeccf4374 --- /dev/null +++ b/Plans/2026-11-14-mobius/03-github-and-revision-comparison.md @@ -0,0 +1,93 @@ +# 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 + +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 + +| Story | Requirement | Intended contribution | +| --- | --- | --- | +| 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. | +| 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. + +## 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. 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"] + Baseline["This PR file's last-reviewed version, if any"] --> Diff + Diff --> Progress["ReviewProgress from 01"] + 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 +// 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. 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). + +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 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. 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 + +| 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 | 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 + +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..a62473b6f --- /dev/null +++ b/Plans/2026-11-14-mobius/04-repository-exploration.md @@ -0,0 +1,76 @@ +# 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 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 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 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. | + +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 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. + +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"] + Tree --> Paths["Proposed path search"] + Tree --> Blobs["Account-scoped blob cache"] + Blobs --> Index["Proposed text index with coverage"] + Paths --> Results["Results in an identified search child"] + Index --> Results + Results -->|open source child alongside review| Workspace["Logical 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. 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 + +| 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. | +| 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 + +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..7790f6166 --- /dev/null +++ b/Plans/2026-11-14-mobius/05-review-feedback.md @@ -0,0 +1,86 @@ +# 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, 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 + +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. + +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 + 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. +- 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 + +- 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. 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 + +| 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. | +| 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 + +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..745d52eb3 --- /dev/null +++ b/Plans/2026-11-14-mobius/06-icloud-resume-and-release.md @@ -0,0 +1,94 @@ +# 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. 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. + +## 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-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. | + +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 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"] + 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. +``` + +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 + +- [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 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. 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. + +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. | +| 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 + +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..b17c328f6 --- /dev/null +++ b/Plans/2026-11-14-mobius/07-embedded-review-experiment.md @@ -0,0 +1,67 @@ +# 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. + +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 +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. | +| 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 + +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..422d166d7 --- /dev/null +++ b/Plans/2026-11-14-mobius/README.md @@ -0,0 +1,507 @@ +# Mobius: a persistent code-review workspace + +## Planning checkpoint + +- Updated: 2026-11-14; initial repository baseline `b629d56ac44a3f2a5ea59c3d6ae9cd5401f37674`; merged main through `96f5bf0f1685de259d7ff080842b8092f9a950d2` in `68477fe625784a1a1e68c0115d7e42cc63166692`. +- 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. + +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. 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 | 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. | +| 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. | +| 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–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. 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) | +| 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. 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 | +| 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 + +| ID | Category | Exclusion | Reason | +| --- | --- | --- | --- | +| 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. | +| 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 + +- 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. | +| 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 + +### 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. 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. + +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. + +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. + +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, 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. +- **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 + +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. 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. + +```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 + 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"] + 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 (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. +@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: 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 { + 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) 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 | [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 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. | +| 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: [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. + +## 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 | 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 | 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 | 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 | 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. | + +## 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. | +| [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 | 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. | +| [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-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 + +- 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. 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. + +### 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. + +### 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. +- 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. 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 + +- 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. + +### 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. + +### 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 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. + +### 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. + +### 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. +- 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. +- 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. +- 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: 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 + +- 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; 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 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.