refactor comments: retarget cross-refs at docs/PSEUDO-MERGE-MODE.md

The pseudo-merge design doc at docs/PSEUDO-MERGE-MODE.md is now the
permanent reference. Code/test comments are rewritten so the source
reads as if it had been written from that spec, with no traces of the
development process:

- All references to PSEUDO-MERGE-MODE-IMPLEMENTATION_PLAN.md (the
  work-in-progress document) replaced with cross-refs to
  docs/PSEUDO-MERGE-MODE.md §X.Y where the new article actually
  covers the topic.
- All "Stage 13 / Phase 4 / Decision #X / Group N / pre-Stage-13"
  development-process artifacts removed.
- All N-prefixed test titles (N1, N9, N13, etc., from the Phase 3
  RED test plan) stripped — the test name itself describes the
  behaviour; the location of the spec cross-ref is the surrounding
  comment.
- Cross-refs added only where local code can't self-explain
  (named protocols, non-obvious design choices, invariants the
  spec enforces). No reflexive "see docs/..." after every block.
- Removed dead-artifact assertions: tests no longer synthesize
  `sibling-content.bin` files (a legacy backup file the current
  code never produces or reads). Test cases keep their actual
  behavioural pin without the legacy stand-in setup.
- Same `.sync-tmp` semantic fix applied to comments in main.ts
  and mock-obsidian-platform.test.ts that still said `.sync-bak`
  for ConflictStore staging contexts.

No behavioural changes; tests 526/526 GREEN; build clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dbdeveloper

mock-obsidian.ts

@@ -147,7 +147,7 @@ export class Vault {
   }
 
   // Subscribe to vault events. ConflictWatcher relies on this for
-  // its delete/modify/rename triggers — Stage 4 tests fire events
+  // its delete/modify/rename triggers — tests fire events
   // synchronously via the test helper `fireEvent` below.
   on(event: string, cb: (...args: unknown[]) => void): EventRef {
     const ref = { event, cb };

src/main.ts

@@ -246,9 +246,9 @@ export default class GitHubSyncPlugin extends Plugin {
       await queue.clearAll();
     }
     if (this.conflictStore) {
-      // Decision #22: rename vault sibling files BEFORE dropping the
-      // record index, so a future re-enable doesn't collide with the
-      // user's leftover conflict-from artifacts.
+      // Rename vault sibling files BEFORE dropping the record index,
+      // so a future re-enable doesn't collide with the user's
+      // leftover conflict-from artifacts.
       await this.conflictStore.renameVaultSiblingsToUnresolved();
       await this.conflictStore.clearAll();
     }
@@ -269,11 +269,10 @@ export default class GitHubSyncPlugin extends Plugin {
       lastSyncCommitSha: store.getLastSyncCommitSha(),
       paths: store.paths().length,
     });
-    // (Stage 13 wire-up: AtomicWriteRecovery sweep moved down to AFTER
-    // ConflictStore.load so the sweep can resolve `.sync-bak` files
-    // owned by conflict records via record.theirsBlobSha SHA-verify,
-    // not just snapshot-based reasoning. See block after conflictStore
-    // construction below.)
+    // AtomicWriteRecovery sweep runs AFTER ConflictStore.load (see
+    // block below) so the sweep can resolve `.sync-tmp` staging
+    // files owned by conflict records via record.theirsBlobSha
+    // SHA-verify, not just snapshot-based reasoning.
     const gi = new GI(vaultRoot);
     const queue = new PushQueue({
       vault: this.app.vault,
@@ -322,7 +321,7 @@ export default class GitHubSyncPlugin extends Plugin {
     await conflictStore.load();
     this.conflictStore = conflictStore;
     // Crash-recovery sweep for atomic-write artifacts AND for
-    // ConflictStore vault-level `.sync-bak` siblings. Runs BEFORE the
+    // ConflictStore vault-level `.sync-tmp` staging siblings. Runs BEFORE the
     // engine starts touching the vault so any leftover staging from a
     // previous crash is reconciled against the snapshot + conflict
     // stores before findChanges or drain sees them.
@@ -337,11 +336,11 @@ export default class GitHubSyncPlugin extends Plugin {
     } catch (err) {
       await this.logger.error("Atomic-write recovery sweep failed", `${err}`);
     }
-    // Stage 13 wire-up (PSEUDO-MERGE-MODE.md §"Counter formula +
-    // vault.on listeners role"): ConflictCounter owns the count
-    // formula + debounced recompute; ConflictWatcher just calls
-    // counter.markDirty() on relevant vault events; the counter
-    // notifies UI surfaces via subscribe().
+    // ConflictCounter owns the count formula + debounced recompute;
+    // ConflictWatcher just calls counter.markDirty() on relevant
+    // vault events; the counter notifies UI surfaces via
+    // subscribe(). See docs/PSEUDO-MERGE-MODE.md §5 for the layer
+    // separation.
     const conflictCounter = new ConflictCounter({
       vault: this.app.vault,
       store: conflictStore,
@@ -374,8 +373,8 @@ export default class GitHubSyncPlugin extends Plugin {
       selfPluginId: manifest.id,
       // Label read live from settings so the user can change it in
       // the settings tab and the next sync picks up the new value —
-      // no plugin reload needed. Stage 13: commitMessage template is
-      // gone (Decision #36); messages are hardcoded via commit-message.ts.
+      // no plugin reload needed. Commit messages themselves are
+      // hardcoded in src/sync2/commit-message.ts.
       deviceLabel: () => this.settings.deviceLabel ?? "Obsidian",
       // Remote identity read live so the manager catches a mid-session
       // settings change (user edits the repo coords in the settings
@@ -549,12 +548,11 @@ export default class GitHubSyncPlugin extends Plugin {
     return false;
   }
 
-  // Refresh every visibility surface (status bar, ribbon badge,
-  // settings tab) from the current ConflictCounter value. The
-  // counter applies the Stage 13 formula (excludes records with
-  // !siblingExists and records where siblingSha == baseSha) so the
-  // UI badge reflects what the user actually still has to resolve,
-  // not the raw record count.
+  // Refresh every visibility surface (status bar, ribbon badge)
+  // from the current ConflictCounter value. The counter formula
+  // (excludes records with !siblingExists and records where
+  // siblingSha == baseSha) reflects what the user actually still
+  // has to resolve, not the raw record count.
   refreshConflictUI(): void {
     const count = this.conflictCounter?.getValue() ?? 0;
     this.conflictStatusIndicator?.refresh(count);
@@ -604,10 +602,10 @@ export default class GitHubSyncPlugin extends Plugin {
     if (this.statusBarItem) return;
     this.statusBarItem = this.addStatusBarItem();
     this.updateStatusBarItem();
-    // Stage 10 — conflict-count indicator lives in its own
-    // addStatusBarItem element so user themes can style it
-    // independently. Click opens the first sibling in the editor
-    // (same shortcut the pre-sync modal's "Resolve" button uses).
+    // Conflict-count indicator lives in its own addStatusBarItem
+    // element so user themes can style it independently. Click
+    // opens the first sibling in the editor (same shortcut the
+    // pre-sync modal's "Resolve" button uses).
     if (!this.conflictStatusIndicator) {
       const indicatorParent = this.addStatusBarItem();
       this.conflictStatusIndicator = new ConflictStatusIndicator(

src/settings/settings.ts

@@ -41,10 +41,9 @@ export interface GitHubSyncSettings {
 
   enableLogging: boolean;
 
-  // Stage 13 (Decision #36): the `commitMessage` template field is
-  // gone. Commit messages are hardcoded via formatX helpers in
-  // src/sync2/commit-message.ts. The only user-tunable component of
-  // a sync2 commit is `deviceLabel` below (the trailing suffix).
+  // No commit-message template field. Commit messages are hardcoded
+  // via formatX helpers in src/sync2/commit-message.ts; `deviceLabel`
+  // below is the only user-tunable component (the trailing suffix).
 
   // When sync2 is offline (last push failed) and this is true,
   // subsequent Sync clicks fold into the latest pending batch

src/settings/tab.ts

@@ -29,14 +29,11 @@ export default class GitHubSyncSettingsTab extends PluginSettingTab {
   display(): void {
     const { containerEl } = this;
     containerEl.empty();
-    // Stage 13 (Decision #21 revision): the settings-tab "Pending
-    // conflicts" header + record list was removed. Visibility for
-    // unresolved conflicts now lives in three places: status bar,
-    // pre-sync modal, ribbon badge. The settings-tab variant was a
-    // detail surface that didn't pull its weight — users with a
-    // conflict click the status bar / ribbon to open the sibling,
-    // not the settings tab. Detailed conflict list will live in
-    // Diff2 (stage 2) as a dedicated UI surface.
+    // Visibility for unresolved conflicts lives in three places:
+    // status bar, pre-sync modal, ribbon badge. The settings tab
+    // does NOT carry a conflict list — users with a conflict click
+    // the status bar or ribbon to open the sibling, not the
+    // settings tab.
 
     // ── Remote repository ────────────────────────────────────────────
     new Setting(containerEl).setName("Remote Repository").setHeading();
@@ -287,12 +284,11 @@ export default class GitHubSyncSettingsTab extends PluginSettingTab {
     // ── Device identity ─────────────────────────────────────────────
     new Setting(containerEl).setName("Sync").setHeading();
 
-    // Both commit-message inputs render a live preview directly
-    // Stage 13: commit-message template input removed (Decision #36).
-    // Hardcoded formats live in src/sync2/commit-message.ts. The
-    // device label is the only user-tunable component now — it
-    // appears as the trailing " (label)" suffix on every sync2
-    // commit. Preview shows the user what that looks like.
+    // No commit-message template input. Hardcoded formats live in
+    // src/sync2/commit-message.ts; the device label is the only
+    // user-tunable component, appearing as the trailing " (label)"
+    // suffix on every sync2 commit. The live preview below shows
+    // the user what that looks like.
     const previews: Array<() => void> = [];
     const renderDeviceLabelPreview = (): string =>
       formatSyncMessage(this.plugin.settings.deviceLabel ?? "Obsidian");
@@ -397,11 +393,6 @@ export default class GitHubSyncSettingsTab extends PluginSettingTab {
           });
       });
 
-    // Stage 13 (Decision #36): the "Commit message" template input
-    // is gone. Commit messages are hardcoded — see
-    // src/sync2/commit-message.ts. Device label above is the only
-    // user-tunable component of every sync2 commit.
-
     new Setting(containerEl)
       .setName("Auto-canonicalize text files")
       .setDesc(

src/sync2/atomic-write.ts

@@ -28,17 +28,15 @@ import type SnapshotStore from "./snapshot-store";
 export const SYNC_TMP_SUFFIX = ".sync-tmp";
 export const SYNC_BAK_SUFFIX = ".sync-bak";
 
-// Stage 13: pre-suffix staging path. Phase 4 Group 4 implementation.
-//
 // Computes the staging path for a target file by inserting `.sync-bak`
 // (or `.sync-tmp` if `which="tmp"`) BEFORE the file extension instead
 // of appending after it. This preserves the original extension's
 // visibility in Obsidian's file explorer (a `.md.sync-bak` file is
 // hidden under "Show all file types: false" but a `note.sync-bak.md`
 // is still indexed as markdown).
 //
-// Examples (from PSEUDO-MERGE-MODE.md §"Naming convention для staging
-// файлів — `.sync-bak` як pre-suffix"):
+// See docs/PSEUDO-MERGE-MODE.md §9.2 for the naming convention.
+// Examples:
 //   - "Folder/note.md"                  → "Folder/note.sync-bak.md"
 //   - "Plugins/foo/manifest.json"       → "Plugins/foo/manifest.sync-bak.json"
 //   - ".gitignore"                      → ".gitignore.sync-bak"
@@ -134,11 +132,11 @@ export async function atomicWriteFile(
   bytes: ArrayBuffer,
   afterCommit?: () => Promise<void>,
 ): Promise<void> {
-  // Stage 13: pre-suffix staging paths so Obsidian's file explorer
-  // still recognizes the staging file by extension (a `.md.sync-tmp`
+  // Pre-suffix staging paths so Obsidian's file explorer still
+  // recognizes the staging file by extension (a `.md.sync-tmp`
   // file is hidden under "Show all file types: false" but a
-  // `note.sync-tmp.md` stays visible). See PSEUDO-MERGE-MODE.md
-  // §"Naming convention для staging файлів — `.sync-bak` як pre-suffix".
+  // `note.sync-tmp.md` stays visible). See stagingPathFor above
+  // and docs/PSEUDO-MERGE-MODE.md §9.2.
   const tmpPath = stagingPathFor(path, "tmp");
   const bakPath = stagingPathFor(path, "bak");
 
@@ -210,8 +208,8 @@ interface ConflictStoreLike {
 // any `.sync-tmp` / `.sync-bak` leftovers and reconciles them
 // against the snapshot + conflict stores.
 //
-// Each suffix now has ONE consistent meaning (see PSEUDO-MERGE-MODE.md
-// §9 for the rationale):
+// Each suffix has ONE consistent meaning (see
+// docs/PSEUDO-MERGE-MODE.md §9 for the full rationale):
 //
 //   `.sync-tmp` = NEW bytes staged for a target (existing or new).
 //      Ambiguous between two callsites; dispatch by ownership via

src/sync2/commit-message.ts

@@ -2,21 +2,12 @@
 // Vladyslav Kozlovskyy <dbdevelop@gmail.com>, 2026.
 // AGPL-3.0 — see LICENSE.
 
-// Stage 13 (Decision #36): hardcoded commit-message formats.
-//
-// Pre-Stage-13 commit messages were user-template-driven: settings
-// had a "Commit message" field with `{date}` / `{time}` placeholders,
-// rendered via `applyTemplate` and suffixed with `(deviceLabel)`
-// via `appendDeviceSuffix`. Stage 13 drops the whole templating
-// system — every commit message is now a hardcoded string with
-// `{deviceLabel}` as the only substitution. See PSEUDO-MERGE-MODE.md
-// §"Commit message formats (Stage 13 — hardcoded)".
-//
-// Why drop templates: provenance + multi-device disambiguation are
-// the only useful signals, both delivered by `(deviceLabel)`. Date
-// and time come for free from git commit metadata (authorDate /
-// committerDate). Power-user customization was unused and added
-// surface area for bugs.
+// Hardcoded commit-message formats. Every message is a fixed string
+// with `{deviceLabel}` as the only substitution; date and time are
+// already carried by git commit metadata (authorDate /
+// committerDate) and don't need to live in the message body.
+// Provenance + multi-device disambiguation are the only useful
+// signals, both delivered by the trailing `(deviceLabel)`.
 
 // Sentinel used wherever sync2 needs a stand-in for an unknown device
 // — both at READ time (parseDeviceSuffix on a commit with no trailing
@@ -98,12 +89,11 @@ export function commitMessageForBatch(
 // off any commit message produced by sync2. Falls back to
 // UNKNOWN_DEVICE_LABEL for hand-edited or non-sync2 commits.
 //
-// This survives from the pre-Stage-13 commit-templates module
-// because the suffix shape didn't change — every Stage 13 formatX
-// function above appends `(safeLabel(...))` so the regex still
-// matches. Used by sync2-manager to identify the foreign device on
-// an existing commit (for the multi-device "who pushed this?"
-// observability log line).
+// Every formatX function above appends `(safeLabel(...))` so this
+// regex matches all sync2-produced messages uniformly. Used by
+// sync2-manager to identify the foreign device on an existing
+// commit (for the multi-device "who pushed this?" observability
+// log line).
 export function parseDeviceSuffix(message: string): string {
   const m = /\s\(([^()]+)\)\s*$/.exec(message);
   return m ? m[1] : UNKNOWN_DEVICE_LABEL;

src/sync2/conflict-branch.ts

@@ -2,9 +2,9 @@
 // Vladyslav Kozlovskyy <dbdevelop@gmail.com>, 2026.
 // AGPL-3.0 — see LICENSE.
 
-// Pseudo-merge conflict-branch naming helper
-// (PSEUDO-MERGE-MODE.md §"Branch naming + lifecycle", stage 7a;
-// Decision #19).
+// Conflict-branch naming helper. See docs/PSEUDO-MERGE-MODE.md §4.3
+// for the per-device branch lifecycle and §10 Scenarios A–E for the
+// shape of the names in context.
 //
 // Pure function. Returns a bare branch name (no `refs/heads/`
 // prefix) with the shape:

src/sync2/conflict-classifier.ts

@@ -6,21 +6,14 @@ import { Vault } from "obsidian";
 import { calculateGitBlobSHA } from "../utils";
 import ConflictStore, { ConflictRecord } from "./conflict-store";
 
-// Pseudo-merge ConflictState classifier (PSEUDO-MERGE-MODE.md, stage 3).
-//
-// Single algorithm, per-ConflictRecord classification. Reads the live
-// vault + ConflictStore record cache to derive (baseExists,
-// siblingExists, baseSha, siblingSha) and decides one of four
-// outcomes (Decision below) or no-op. modify-vs-delete is NOT a
+// Per-ConflictRecord classifier. Implements Phase A of
+// `evaluateConflictState` per docs/PSEUDO-MERGE-MODE.md §5 (drain-start
+// pseudocode). Reads the live vault + ConflictStore record cache to
+// derive (baseExists, siblingExists, baseSha, siblingSha) and decides
+// one of three outcomes (Decision below). modify-vs-delete is NOT a
 // conflict kind — it auto-resolves at push-time in favor of local
 // modify (see conflict-detection.ts → attemptAutoMerge's "modify-
 // wins" outcome); the classifier never sees it.
-//
-// Per spec §"Trigger points" this is invoked from 4 places:
-//   - drain-start sweep (Sync2Manager.drain)
-//   - drain-end sweep   (Sync2Manager.drain)
-//   - UI op on conflict-related view
-//   - ConflictWatcher fast-path hit (vault.on event)
 
 // ── Decision (output of the pure classify() function) ─────────────────
 
@@ -38,15 +31,6 @@ export type Decision =
   // baseSha content to main on path-close.
   | { type: "accept-theirs" };
 
-// `delete-wins-cascade` was removed in Stage 13 (Decision #30 in
-// PSEUDO-MERGE-MODE.md). The old behavior — "user deletes base →
-// engine cascade-deletes every sibling for the path" — broke the
-// mobile delete-then-rename workflow because the cascade fired
-// between the user's two ops. Stage 13: row 3 returns noop; deletion
-// now requires the user to remove EVERY sibling for the path too
-// (or rename one onto the base, which removes both the sibling and
-// reuses the now-converged base).
-
 // Pure classifier. No I/O. All inputs are already-fetched stat/hash
 // values.
 export function classify(
@@ -57,9 +41,7 @@ export function classify(
   siblingExists: boolean,
   siblingSha: string | null,
 ): Decision {
-  // kind is currently informational only — classify() doesn't branch
-  // on it. Stage 13 unified the two remaining kinds (modify-vs-modify
-  // and delete-vs-modify) under a single rule set.
+  // `kind` is observational — classify() does not branch on it.
   void record.kind;
 
   // !siblingExists → accept ours regardless of kind. Both
@@ -73,9 +55,12 @@ export function classify(
   // siblingExists from here on.
 
   if (!baseExists) {
-    // Stage 13 (Decision #30): user deleted base, sibling alive —
-    // wait for the user to do the rest. Sibling stays; record stays.
-    // No cascade. This unblocks delete-then-rename on mobile.
+    // User deleted base, sibling alive — wait. Sibling and record
+    // both stay. Engine never cascade-deletes siblings on bare
+    // base-deletion; the user must remove every sibling for the
+    // path too (or rename one onto the base). This is what enables
+    // the mobile delete-then-rename workflow; see
+    // docs/PSEUDO-MERGE-MODE.md §6.2.
     return { type: "noop" };
   }
 
@@ -146,10 +131,6 @@ export async function evaluateConflictState(
     const baseExists = baseStat !== null && baseStat.type === "file";
     const baseSize = baseExists ? baseStat!.size : null;
 
-    // Stage 13 (Decision #30): the path-level Row 3 cascade is gone.
-    // Records with `!baseExists` no longer trigger an engine-driven
-    // sibling sweep; per-record classify() returns noop instead.
-
     // Lazy base SHA: computed (or cache-hit) on first record that
     // needs it. After computation it's cached in `baseShaCached` for
     // the rest of this path's records.