v2 reset: realign product plan around settings-folder sync

[shpoont]

Why

The v2 product direction has been reset after review. The previous v2 docs and issues treated backup/restore, repository terminology, v1 migration, and save/apply as central concepts. That is no longer the intended product.

Source of truth

• Project charter / parent issue: this issue (v2 reset: realign product plan around settings-folder sync #209).
• Repo-editable execution record: docs/internal/project/v2-reset-execution-record.md.
• Transformation plan: docs/internal/project/v2-project-execution-standards-transformation-plan.md.
• Project-specific standards tailoring: docs/internal/process/v2-execution-standards-tailoring.md.

Future v2 work should follow the execution record and issue-level contracts rather than chat history or superseded branches.

Product direction

• The product manages settings between two sides: live app settings and a settings storage folder.
• The storage folder may be tracked with Git, but it is not necessarily a Git repository and must not be called a repo in the core UX.
• The primary UX is status, diff, and sync: see what changed, understand direction, and sync all or selected changes in the correct direction.
• save and apply are retained as public compatibility aliases for directional sync, not the primary mental model:
  • save = sync live settings to stored settings.
  • apply = sync stored settings to live settings.
• Smart sync should detect when only one side changed and guide the user toward the safe direction.
• Backup/restore is out of scope for v2; safety should come from preview, diff, confirmation, and optional versioned storage.
• There are no users or v1 migrations in the current v2 product plan; v1 is historical reference only.
• The dotfiles-manager official catalog is preconfigured by the app, but it is not presented as baked into the app. catalog list should show useful state such as catalog version and updated time. Official-catalog download/update behavior and additional remote catalogs/taps are the intended extension path for additional support; local catalog lifecycle is not part of the normal v2 user path.
• New-computer setup should be simple: install apps first, for example with Homebrew Bundle, then apply settings from the storage folder.

Standards state

• v2 process: adopt Project Execution Standards scaffold #217 — install Project Execution Standards scaffold. PR Adopt v2 Project Execution Standards scaffold #218 merged.
• v2 process: audit current implementation against reset model #219 — audit current implementation/docs/tests/tracker against the reset model. PR Add v2 reset audit #220 merged; follow-up splits/edits recorded. This marks Phase 2 audit/discovery closed for sequencing, not every product gate complete.
• v2 reset: revise product concept and vocabulary around settings storage #210 — revise product concept and vocabulary around settings storage.
• v2 process: reconcile standards records after sync work #238 — reconcile standards records after sync work. PR Reconcile v2 standards records #239 merged; source-of-truth drift is closed.
• v2 reset: remove v1 migration from the v2 roadmap #213/v2 legacy: decide v1 public CLI surface policy #226 — remove v1 migration from the v2 roadmap and decide the legacy v1 public CLI surface policy. PR [codex] Hide legacy v1 public commands from v2 help #247 merged; retained legacy v1 commands are hidden from normal v2 help and separated from v2 product acceptance.
• v2 catalogs: specify catalog/tap trust and origin model #227 — specify catalog/tap trust and origin model. PR Specify v2 catalog trust and origin model #250 merged; accepted and closed on 2026-06-26. This accepts the design/handoff model only, not remote runtime behavior.
• v2 catalogs: implement official catalog discovery baseline #228 — implement the official-catalog discovery baseline. PR [codex] Implement official catalog discovery runtime #260 merged; accepted and closed on 2026-07-04. This accepts read-only discovery only, not catalog update/add/download, additional catalogs, network fetching, or settings writes.

The project is scaffold-adopted and current work follows the standards. #211, #227, and #228 are complete. #228 completed recontract/design evidence through PR #258 and runtime implementation through PR #260, which was squash-merged as 45b7c8b6d9ec9124b36a7b09c4e4d7397fdd52d1; Project Owner accepted #228 closure on 2026-07-04. The combined v2 product is not fully accepted until remaining product gates are completed or explicitly deferred.

Current execution sequence

• v2 process: adopt Project Execution Standards scaffold #217 — install Project Execution Standards scaffold.
• v2 process: audit current implementation against reset model #219 — audit current implementation/docs/tests/tracker against the reset model.
• v2 reset: revise product concept and vocabulary around settings storage #210 — revise product concept and vocabulary around settings storage.
• v2 reset: redesign status, diff, and sync as the primary UX #211 — redesign status, diff, and sync as the primary UX. Parent accepted and closed on 2026-06-26 after v2 sync: define status and diff read-only contract #221-v2 sync: decide save/apply alias or deprecation policy #225, v2 reset: remove backup and restore from product scope #212, and v2 reset: remove v1 migration from the v2 roadmap #213/v2 legacy: decide v1 public CLI surface policy #226 completed.
  • v2 sync: define status and diff read-only contract #221 — define status and diff read-only contract.
  • v2 sync: design smart-sync planning and conflict UX #222 — design smart-sync planning and conflict UX.
  • v2 sync: implement mutating sync execution and confirmations #223 — implement mutating sync execution and confirmations.
  • v2 sync: specify partial and many-app UX fixtures #224 — specify partial and many-app UX fixtures.
  • v2 sync: decide save/apply alias or deprecation policy #225 — decide save/apply alias or deprecation policy.
• v2 reset: remove backup and restore from product scope #212 — remove backup and restore from product scope. PR Remove public backup and restore workflow #243 merged and issue closed on 2026-06-25; public backup/restore workflow is removed from v2 surface.
• v2 reset: remove v1 migration from the v2 roadmap #213 — remove v1 migration from the v2 roadmap. PR [codex] Hide legacy v1 public commands from v2 help #247 merged and issue closed on 2026-06-26.
  • v2 legacy: decide v1 public CLI surface policy #226 — decide v1 public CLI surface policy. PR [codex] Hide legacy v1 public commands from v2 help #247 merged and issue closed on 2026-06-26; retained legacy v1 commands are hidden from normal help and remain callable only as compatibility.
• v2 reset: design recipe catalog and tap support #214 — design recipe catalog and tap support. Parent remains open.
  • v2 catalogs: specify catalog/tap trust and origin model #227 — specify catalog/tap trust and origin model. PR Specify v2 catalog trust and origin model #250 merged and issue closed on 2026-06-26 after Project Owner acceptance.
  • v2 catalogs: implement official catalog discovery baseline #228 — implement the official-catalog discovery baseline against the accepted v2 catalogs: specify catalog/tap trust and origin model #227 model. PR [codex] Implement official catalog discovery runtime #260 merged and issue closed on 2026-07-04 after Project Owner acceptance. This does not include catalog update/add/download, additional catalogs, network fetching, or settings writes.
  • v2 catalogs: implement official and remote catalog management with write gates #229 — implement official-catalog updates and additional remote catalog management with write gates against the accepted v2 catalogs: specify catalog/tap trust and origin model #227 model.
• v2 reset: define new-computer bootstrap flow #215 — define new-computer bootstrap flow. Parent remains open.
  • v2 bootstrap: specify new-computer UX and output #230 — specify new-computer UX and output.
  • v2 bootstrap: implement apply-from-storage flow after sync model #231 — implement apply-from-storage flow after sync model.
• v2 docs: rewrite end-user documentation after product reset #216 — rewrite end-user documentation after product reset. Waits for accepted behavior/examples from remaining gates.

Open parent rationale

• v2 reset: realign product plan around settings-folder sync #209 remains open because it is the project charter and closes only when the combined reset outcome is accepted.
• v2 reset: design recipe catalog and tap support #214 remains open because v2 catalogs: implement official and remote catalog management with write gates #229 remains open for official-catalog update/download behavior and additional remote catalog management with write gates. v2 catalogs: specify catalog/tap trust and origin model #227 settled the trust/origin/write-authority design input, and v2 catalogs: implement official catalog discovery baseline #228 completed the official-catalog discovery baseline.
• v2 reset: define new-computer bootstrap flow #215 remains open because bootstrap UX and apply-from-storage implementation children remain open.
• v2 docs: rewrite end-user documentation after product reset #216 remains open because production end-user documentation depends on accepted behavior and examples from the remaining gates.

Acceptance criteria

• The old v2 docs PR is closed and cannot be accidentally treated as production-ready.
• Obsolete open v1 backlog issues are removed from the active tracker; retained legacy v1 compatibility is explicitly separated from v2 acceptance by v2 reset: remove v1 migration from the v2 roadmap #213/v2 legacy: decide v1 public CLI surface policy #226 and PR [codex] Hide legacy v1 public commands from v2 help #247.
• Focused v2 reset issues exist for concept/vocabulary, sync UX, backup removal, v1 migration/legacy surface removal, recipe catalogs, new-computer setup, and documentation rewrite.
• The GitHub Project contains the new issue set with clear statuses.
• The next implementation/doc work starts from the revised sync-first product model.
• Product-scope gate v2 reset: remove v1 migration from the v2 roadmap #213/v2 legacy: decide v1 public CLI surface policy #226 is complete. v2 reset: remove backup and restore from product scope #212 is complete.
• Status/diff/sync parent gate v2 reset: redesign status, diff, and sync as the primary UX #211 is accepted and closed.
• Catalog trust/origin design gate v2 catalogs: specify catalog/tap trust and origin model #227 is accepted and closed.
• Remaining catalog update/remote lifecycle, bootstrap, and production documentation gates are completed or explicitly deferred.
• The combined v2 reset outcome is accepted with evidence in the execution record.

Project Execution Standards alignment

Latest standard read for this update: /Users/shpoont/Work/shpoont/project-execution-standards/project-execution-standard.md, last-updated 2026-06-29.

Project record / source of truth: this issue plus docs/internal/project/v2-reset-execution-record.md.

Role of this issue: project charter / roadmap, not a direct implementation work item.

Scope: coordinate the v2 reset work items, dependencies, active gates, evidence links, and final project acceptance state.

Risk tier: project-level mixed Tier 1/Tier 2. Child work items carry exact risk tiers; remote catalog writes and live-settings writes are Tier 2 by default.

Current lifecycle state:

• The project is decomposed into work items and parent areas.
• Individual work items must carry their own risk tier, contract, design/documentation evidence, implementation-start gate, real-result verification, validation, acceptance, and closure records.
• Broad agreement on this parent issue does not approve implementation, merge, release, acceptance, or closure for child issues.

Current next gate:

• v2 catalogs: implement official catalog discovery baseline #228 official-catalog discovery runtime implementation was completed by PR [codex] Implement official catalog discovery runtime #260, squash-merged on 2026-07-03 as 45b7c8b6d9ec9124b36a7b09c4e4d7397fdd52d1, and closed after Project Owner approval on 2026-07-04.
• The project must now select the next work item through its own gate. Likely candidates are v2 catalogs: implement official and remote catalog management with write gates #229 for official-catalog update/download and additional remote catalog management with write gates, or v2 bootstrap: specify new-computer UX and output #230 for new-computer UX/output.

Change rule:

• Changes to project sequence, product scope, completion criteria, risk tier defaults, or acceptance/closure requirements must be recorded here and in docs/internal/project/v2-reset-execution-record.md where durable repo state changes.

No-go actions:

• Do not treat mock/storyboard evidence as real-result verification.
• Do not implement future catalog lifecycle (v2 catalogs: implement official and remote catalog management with write gates #229), bootstrap apply (v2 bootstrap: implement apply-from-storage flow after sync model #231), or production docs (v2 docs: rewrite end-user documentation after product reset #216) without their own documentation/mock-first and implementation-start gates.
• Do not close v2 reset: realign product plan around settings-folder sync #209 until the combined v2 outcome is accepted or remaining gates are explicitly deferred with recorded owner decisions.

[shpoont]

Started Phase 1 of the Project Execution Standards transformation in #217.

Scope for this first slice:

• add the written transformation plan;
• add the v2 reset execution record;
• add repo-specific tailoring rules;
• add issue/PR evidence templates;
• keep this scaffold product-behavior-neutral.

The intended source-of-truth decision for acceptance is: #209 remains the v2 reset project charter, and docs/internal/project/v2-reset-execution-record.md becomes the repo-editable project execution record.

[shpoont]

Phase 1 standards scaffold is complete.

• PR Adopt v2 Project Execution Standards scaffold #218 was squash-merged: Adopt v2 Project Execution Standards scaffold #218
• Merge commit: 1bbb484
• Accepted execution record: https://github.com/shpoont/dotfiles-manager/blob/main/docs/internal/project/v2-reset-execution-record.md
• Project-specific tailoring: https://github.com/shpoont/dotfiles-manager/blob/main/docs/internal/process/v2-execution-standards-tailoring.md
• Phase 1 issue v2 process: adopt Project Execution Standards scaffold #217 is closed with validation and acceptance evidence.

Next active work item:

• v2 process: audit current implementation against reset model #219 — Phase 2 reset audit of current implementation/docs/tests/tracker against the accepted reset model.

Until #219 is accepted, current v2 runtime behavior remains prototype baseline and should not be treated as production-aligned with the reset model.