@mrsf/cli 0.1.0 → 0.2.1

package/README.md

@@ -336,6 +336,60 @@ With this config, the sidecar for `docs/architecture.md` is resolved as `.review
 
 See [§3.2 Alternate Sidecar Location](../MRSF-v1.0.md) in the spec for details.
 
+## Extension Fields (`x_*`)
+
+MRSF reserves the `x_` prefix for tool-specific, non-standard extension properties (see [§10 Extension Fields](../MRSF-v1.0.md)). These fields may appear on the top-level document object or on individual comments. The CLI preserves them during round-trip writes and exposes them through the catch-all index signature on both `MrsfDocument` and `Comment`.
+
+### Built-in `x_` fields
+
+The CLI and Sidemark VS Code extension use the following extension fields:
+
+| Field | Scope | Type | Set by | Description |
+|---|---|---|---|---|
+| `x_reanchor_status` | comment | `"anchored"` \| `"shifted"` \| `"fuzzy"` \| `"orphaned"` | `mrsf reanchor` | Result of the most recent reanchor pass. `orphaned` means the anchor text could not be found in the current document. |
+| `x_reanchor_score` | comment | `number` (0–1) | `mrsf reanchor` | Confidence score from the reanchor algorithm. `1.0` = exact match, lower values indicate fuzzy or shifted matches. |
+
+### Adding your own fields
+
+Any property whose key starts with `x_` is valid on both the document root and on each comment. The CLI and Sidemark will silently preserve these fields through all operations (validate, add, resolve, reanchor, etc.).
+
+```yaml
+comments:
+  - id: abc123
+    author: ci-bot
+    timestamp: "2025-01-15T10:00:00Z"
+    text: Possible security concern
+    resolved: false
+    line: 42
+    # Custom extension fields
+    x_ai_confidence: 0.92
+    x_tool_name: security-scanner
+    x_category: injection
+```
+
+**Rules** (from the spec):
+
+- Keys MUST start with `x_` (underscore, not hyphen).
+- Implementations MUST NOT assign semantic meaning to `x_` fields defined by other tools.
+- Future MRSF spec versions will never introduce normative fields with the `x_` prefix.
+- Unknown `x_` fields are preserved by the CLI's round-trip writer and never stripped or modified.
+
+### Programmatic access
+
+```typescript
+import { parseSidecar } from "@mrsf/cli";
+
+const doc = await parseSidecar("file.md.review.yaml");
+for (const comment of doc.comments) {
+  // Access built-in x_ fields
+  if (comment.x_reanchor_status === "orphaned") {
+    console.log(`Comment ${comment.id} is orphaned`);
+  }
+  // Access custom x_ fields
+  const confidence = comment.x_ai_confidence as number | undefined;
+}
+```
+
 ## Requirements
 
 - Node.js 18 or later

package/dist/bin.js

@@ -63,7 +63,8 @@ program
     .option("--cwd <dir>", "Working directory")
     .option("--config <path>", "Path to .mrsf.yaml")
     .option("--no-color", "Disable colour output")
-    .option("-q, --quiet", "Suppress non-essential output");
+    .option("-q, --quiet", "Suppress non-essential output")
+    .option("-v, --verbose", "Show detailed diagnostic output");
 registerValidate(program);
 registerReanchor(program);
 registerAdd(program);

package/dist/commands/add.js

@@ -26,6 +26,7 @@ export function registerAdd(program) {
         const parentOpts = program.opts();
         const cwd = parentOpts.cwd ?? process.cwd();
         const quiet = parentOpts.quiet ?? false;
+        const verbose = parentOpts.verbose ?? false;
         const docPath = path.resolve(cwd, document);
         const root = await findWorkspaceRoot(cwd);
         const sidecarPath = await discoverSidecar(docPath, { cwd: root ?? cwd });
@@ -72,6 +73,14 @@ export function registerAdd(program) {
             }
         }
         await writeSidecar(sidecarPath, doc);
+        if (verbose) {
+            console.log(chalk.dim(`  sidecar: ${sidecarPath}`));
+            console.log(chalk.dim(`  id: ${comment.id}`));
+            if (comment.line)
+                console.log(chalk.dim(`  line: ${comment.line}`));
+            if (comment.selected_text)
+                console.log(chalk.dim(`  selected_text: ${comment.selected_text.slice(0, 80)}${comment.selected_text.length > 80 ? "…" : ""}`));
+        }
         if (!quiet) {
             console.log(chalk.green(`Added comment ${comment.id}`) +
                 (comment.line ? ` at line ${comment.line}` : "") +

package/dist/commands/init.js

@@ -15,6 +15,7 @@ export function registerInit(program) {
         const parentOpts = program.opts();
         const cwd = parentOpts.cwd ?? process.cwd();
         const quiet = parentOpts.quiet ?? false;
+        const verbose = parentOpts.verbose ?? false;
         const docPath = path.resolve(cwd, document);
         // Verify the document exists
         try {
@@ -47,6 +48,10 @@ export function registerInit(program) {
         if (!quiet) {
             console.log(chalk.green(`Created ${sidecarPath}`));
         }
+        if (verbose) {
+            console.log(chalk.dim(`  document: ${doc.document}`));
+            console.log(chalk.dim(`  sidecar: ${sidecarPath}`));
+        }
     });
 }
 //# sourceMappingURL=init.js.map

package/dist/commands/reanchor.js

@@ -8,7 +8,7 @@ import { readDocumentLines } from "../lib/parser.js";
 import { sidecarToDocument } from "../lib/discovery.js";
 import { resolveSidecarPaths } from "../lib/resolve-files.js";
 import { writeSidecar } from "../lib/writer.js";
-import { findRepoRoot, getStagedFiles } from "../lib/git.js";
+import { findRepoRoot, getStagedFiles, getCurrentCommit } from "../lib/git.js";
 import { reanchorDocument, applyReanchorResults, } from "../lib/reanchor.js";
 export function registerReanchor(program) {
     program
@@ -20,10 +20,12 @@ export function registerReanchor(program) {
         .option("--no-git", "Disable git integration")
         .option("--from <commit>", "Override from-commit for all comments")
         .option("--update-text", "Also update selected_text to match current document text")
+        .option("-f, --force", "Firmly anchor high-confidence results (update commit to HEAD, clear audit fields)")
         .action(async (files, opts) => {
         const parentOpts = program.opts();
         const cwd = parentOpts.cwd ?? process.cwd();
         const quiet = parentOpts.quiet ?? false;
+        const verbose = parentOpts.verbose ?? false;
         const threshold = parseFloat(opts.threshold);
         const noGit = !opts.git;
         let sidecarPaths;
@@ -55,6 +57,12 @@ export function registerReanchor(program) {
                 console.log("No sidecar files found.");
             return;
         }
+        if (verbose) {
+            console.log(chalk.dim(`threshold: ${threshold}`));
+            console.log(chalk.dim(`sidecars: ${sidecarPaths.length}`));
+            if (opts.dryRun)
+                console.log(chalk.dim("mode: dry-run"));
+        }
         let totalChanged = 0;
         let totalOrphaned = 0;
         for (const sp of sidecarPaths) {
@@ -63,6 +71,7 @@ export function registerReanchor(program) {
                 const docPath = sidecarToDocument(sp);
                 const lines = await readDocumentLines(docPath);
                 const repoRoot = !noGit ? await findRepoRoot(cwd) : null;
+                const headCommit = repoRoot ? await getCurrentCommit(repoRoot) : undefined;
                 const results = await reanchorDocument(doc, lines, {
                     threshold,
                     noGit,
@@ -75,14 +84,25 @@ export function registerReanchor(program) {
                 if (!opts.dryRun) {
                     const changed = applyReanchorResults(doc, results, {
                         updateText: opts.updateText,
+                        force: opts.force,
+                        headCommit: headCommit ?? undefined,
                     });
                     totalChanged += changed;
                     if (changed > 0) {
                         await writeSidecar(sp, doc);
                     }
                 }
+                else {
+                    // Dry-run: compute change count on a clone so we don't mutate
+                    const clone = structuredClone(doc);
+                    totalChanged += applyReanchorResults(clone, results, {
+                        updateText: opts.updateText,
+                        force: opts.force,
+                        headCommit: headCommit ?? undefined,
+                    });
+                }
                 if (!quiet) {
-                    printResults(sp, results, opts.dryRun);
+                    printResults(sp, results, opts.dryRun, verbose);
                 }
             }
             catch (err) {
@@ -99,13 +119,21 @@ export function registerReanchor(program) {
             process.exit(1);
     });
 }
-function printResults(sidecarPath, results, dryRun) {
+function printResults(sidecarPath, results, dryRun, verbose) {
     const prefix = dryRun ? "[dry-run] " : "";
     console.log(`${prefix}${sidecarPath}:`);
     for (const r of results) {
         const icon = statusIcon(r.status);
         const line = r.newLine != null ? `:${r.newLine}` : "";
         console.log(`  ${icon} ${r.commentId}${line} — ${r.reason}`);
+        if (verbose) {
+            if (r.newLine != null)
+                console.log(`      new line: ${r.newLine}`);
+            if (r.score != null)
+                console.log(`      score: ${r.score.toFixed(3)}`);
+            if (r.status !== "anchored")
+                console.log(`      status: ${r.status}`);
+        }
     }
 }
 function statusIcon(status) {

package/dist/commands/rename.js

@@ -15,6 +15,7 @@ export function registerRename(program) {
         const parentOpts = program.opts();
         const cwd = parentOpts.cwd ?? process.cwd();
         const quiet = parentOpts.quiet ?? false;
+        const verbose = parentOpts.verbose ?? false;
         const oldDocPath = path.resolve(cwd, oldDoc);
         const newDocPath = path.resolve(cwd, newDoc);
         const root = await findWorkspaceRoot(cwd);
@@ -48,6 +49,10 @@ export function registerRename(program) {
         if (!quiet) {
             console.log(chalk.green(`Renamed: ${oldSidecarPath} → ${newSidecarPath}`));
         }
+        if (verbose) {
+            console.log(chalk.dim(`  document: ${doc.document}`));
+            console.log(chalk.dim(`  comments: ${doc.comments.length}`));
+        }
     });
 }
 //# sourceMappingURL=rename.js.map

package/dist/commands/resolve.js

@@ -16,6 +16,7 @@ export function registerResolve(program) {
         const parentOpts = program.opts();
         const cwd = parentOpts.cwd ?? process.cwd();
         const quiet = parentOpts.quiet ?? false;
+        const verbose = parentOpts.verbose ?? false;
         const sp = path.resolve(cwd, sidecar);
         const doc = await parseSidecar(sp);
         const ok = opts.undo
@@ -30,6 +31,9 @@ export function registerResolve(program) {
             const action = opts.undo ? "Unresolved" : "Resolved";
             console.log(chalk.green(`${action} ${id} in ${sidecar}.`));
         }
+        if (verbose) {
+            console.log(chalk.dim(`  sidecar: ${sp}`));
+        }
     });
 }
 //# sourceMappingURL=resolve.js.map

package/dist/commands/status.js

@@ -16,6 +16,7 @@ export function registerStatus(program) {
         const parentOpts = program.opts();
         const cwd = parentOpts.cwd ?? process.cwd();
         const quiet = parentOpts.quiet ?? false;
+        const verbose = parentOpts.verbose ?? false;
         const sidecarPaths = await resolveSidecarPaths(files, cwd);
         if (sidecarPaths.length === 0) {
             if (!quiet)
@@ -57,6 +58,11 @@ export function registerStatus(program) {
             console.log(JSON.stringify(allResults, null, 2));
             return;
         }
+        if (verbose) {
+            for (const sp of sidecarPaths) {
+                console.log(chalk.dim(`  sidecar: ${sp}`));
+            }
+        }
         for (const r of allResults) {
             const icon = healthIcon(r.health);
             console.log(`${icon} ${r.commentId}: ${r.reason}`);

package/dist/commands/validate.js

@@ -13,6 +13,7 @@ export function registerValidate(program) {
         const parentOpts = program.opts();
         const cwd = parentOpts.cwd ?? process.cwd();
         const quiet = parentOpts.quiet ?? false;
+        const verbose = parentOpts.verbose ?? false;
         const sidecarPaths = await resolveSidecarPaths(files, cwd);
         if (sidecarPaths.length === 0) {
             if (!quiet)
@@ -47,6 +48,9 @@ export function registerValidate(program) {
                 const fn = opts.strict ? chalk.red : chalk.yellow;
                 console.log(fn(`  ${opts.strict ? "error" : "warn"}: ${w.message}${w.path ? ` (${w.path})` : ""}`));
             }
+            if (verbose) {
+                console.log(chalk.dim(`  ${result.errors.length} error(s), ${result.warnings.length} warning(s)`));
+            }
         }
         if (hasErrors)
             process.exit(1);

package/dist/lib/reanchor.d.ts

@@ -33,6 +33,8 @@ export declare function reanchorDocument(doc: MrsfDocument, documentLines: strin
  */
 export declare function applyReanchorResults(doc: MrsfDocument, results: ReanchorResult[], opts?: {
     updateText?: boolean;
+    force?: boolean;
+    headCommit?: string;
 }): number;
 /**
  * High-level re-anchor for a single sidecar file path.

package/dist/lib/reanchor.js

@@ -45,8 +45,24 @@ export function reanchorComment(comment, documentLines, opts = {}) {
     // -----------------------------------------------------------------------
     // Step 0: Diff-based shift
     // -----------------------------------------------------------------------
-    if (selectedText && comment.line != null && opts.diffHunks?.length) {
+    if (comment.line != null && opts.diffHunks?.length) {
         const { shift, modified } = getLineShift(opts.diffHunks, comment.line);
+        // For line-only comments (no selected_text), apply the diff shift directly
+        if (!selectedText) {
+            const shiftedLine = comment.line + shift;
+            const lineSpan = comment.end_line != null ? comment.end_line - comment.line : 0;
+            const shiftedEndLine = comment.end_line != null ? shiftedLine + lineSpan : undefined;
+            return {
+                commentId,
+                status: shift === 0 ? "anchored" : "shifted",
+                score: 1.0,
+                newLine: shiftedLine,
+                newEndLine: shiftedEndLine,
+                reason: shift === 0
+                    ? "Line-only comment unchanged (diff confirms position)."
+                    : `Line-only comment shifted by ${shift > 0 ? "+" : ""}${shift} line(s) via diff.`,
+            };
+        }
         if (!modified) {
             const shiftedLine = comment.line + shift;
             const lineSpan = comment.end_line != null ? comment.end_line - comment.line : 0;
@@ -167,13 +183,18 @@ export function reanchorComment(comment, documentLines, opts = {}) {
                 }
             }
             // Pure line fallback
+            // If there's no selected_text, the comment is purely line-anchored.
+            // A commit change alone doesn't make it ambiguous — we accept it as-is.
+            const isLineOnly = !selectedText;
             return {
                 commentId,
-                status: opts.commitIsStale ? "ambiguous" : "anchored",
-                score: opts.commitIsStale ? 0.5 : 0.8,
+                status: isLineOnly ? "anchored" : (opts.commitIsStale ? "ambiguous" : "anchored"),
+                score: isLineOnly ? 1.0 : (opts.commitIsStale ? 0.5 : 0.8),
                 newLine: comment.line,
                 newEndLine: comment.end_line,
-                reason: `Line/column fallback${qualifier}.`,
+                reason: isLineOnly
+                    ? "Line-only comment (no selected_text to verify)."
+                    : `Line/column fallback${qualifier}.`,
             };
         }
     }
@@ -320,6 +341,22 @@ export function applyReanchorResults(doc, results, opts = {}) {
             comment.x_reanchor_status = result.status;
             comment.x_reanchor_score = result.score;
         }
+        // --force: firmly anchor high-confidence results
+        // Update commit to HEAD and clear audit fields so the comment
+        // won't be re-evaluated on the next reanchor run.
+        if (opts.force &&
+            opts.headCommit &&
+            (result.status === "anchored" || result.status === "shifted") &&
+            result.score >= HIGH_THRESHOLD) {
+            comment.commit = opts.headCommit;
+            delete comment.x_reanchor_status;
+            delete comment.x_reanchor_score;
+            // Clear stale anchored_text since anchor is now confirmed
+            if (comment.anchored_text && comment.anchored_text === comment.selected_text) {
+                delete comment.anchored_text;
+            }
+            isChanged = true;
+        }
         if (isChanged)
             changed++;
     }
@@ -333,6 +370,7 @@ export async function reanchorFile(sidecarPath, opts = {}) {
     const docPath = sidecarToDocument(sidecarPath);
     const documentLines = await readDocumentLines(docPath);
     const repoRoot = !opts.noGit ? await findRepoRoot(opts.cwd) : null;
+    const headCommit = repoRoot ? await getCurrentCommit(repoRoot) : undefined;
     const results = await reanchorDocument(doc, documentLines, {
         ...opts,
         documentPath: docPath,
@@ -341,7 +379,11 @@ export async function reanchorFile(sidecarPath, opts = {}) {
     let changed = 0;
     let written = false;
     if (!opts.dryRun) {
-        changed = applyReanchorResults(doc, results, { updateText: opts.updateText });
+        changed = applyReanchorResults(doc, results, {
+            updateText: opts.updateText,
+            force: opts.force,
+            headCommit: headCommit ?? undefined,
+        });
         if (changed > 0 || opts.autoUpdate) {
             await writeSidecar(sidecarPath, doc);
             written = true;

package/dist/lib/types.d.ts

@@ -143,6 +143,8 @@ export interface ReanchorOptions extends BaseOptions {
     fromCommit?: string;
     /** Update selected_text to match anchored_text (opt-in per §6.2). */
     updateText?: boolean;
+    /** Force-anchor: update commit to HEAD and clear audit fields for high-confidence results. */
+    force?: boolean;
 }
 export interface ValidateOptions extends BaseOptions {
     /** Treat warnings as errors. */

package/dist/lib/writer.d.ts

@@ -1,7 +1,13 @@
 /**
  * MRSF Writer — serialize MrsfDocument back to YAML or JSON.
  *
- * Preserves comment order per §10.1.
+ * Uses CST-level (Concrete Syntax Tree) round-trip editing via the `yaml`
+ * library so that unchanged content is byte-identical to the original file.
+ *   - Preserves YAML comments (#)
+ *   - Preserves scalar styles (>, |, quotes)
+ *   - Preserves key ordering and whitespace
+ *   - Only modifies values that actually changed
+ *
  * Auto-computes selected_text_hash when selected_text changes.
  */
 import type { MrsfDocument, Comment } from "./types.js";
@@ -16,7 +22,7 @@ export declare function computeHash(text: string): string;
  */
 export declare function syncHash(comment: Comment): Comment;
 /**
- * Serialize an MrsfDocument to YAML.
+ * Serialize an MrsfDocument to YAML (for new files / non-round-trip use).
  */
 export declare function toYaml(doc: MrsfDocument): string;
 /**
@@ -24,7 +30,13 @@ export declare function toYaml(doc: MrsfDocument): string;
  */
 export declare function toJson(doc: MrsfDocument): string;
 /**
- * Write an MrsfDocument to disk. Detects format from file extension.
+ * Write an MrsfDocument to disk.
+ *
+ * When a YAML file already exists on disk, performs a **CST-level** round-trip
+ * merge that preserves YAML comments, scalar styles, key ordering, and
+ * whitespace byte-for-byte for unchanged content.
+ *
+ * For new files or JSON, writes from scratch.
  */
 export declare function writeSidecar(filePath: string, doc: MrsfDocument): Promise<void>;
 //# sourceMappingURL=writer.d.ts.map

package/dist/lib/writer.js

@@ -1,13 +1,23 @@
 /**
  * MRSF Writer — serialize MrsfDocument back to YAML or JSON.
  *
- * Preserves comment order per §10.1.
+ * Uses CST-level (Concrete Syntax Tree) round-trip editing via the `yaml`
+ * library so that unchanged content is byte-identical to the original file.
+ *   - Preserves YAML comments (#)
+ *   - Preserves scalar styles (>, |, quotes)
+ *   - Preserves key ordering and whitespace
+ *   - Only modifies values that actually changed
+ *
  * Auto-computes selected_text_hash when selected_text changes.
  */
-import { writeFile } from "node:fs/promises";
+import { readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
 import { createHash } from "node:crypto";
 import path from "node:path";
-import yaml from "js-yaml";
+import { Document, Parser, CST, parse as yamlParse } from "yaml";
+/* ------------------------------------------------------------------ */
+/*  Hash helpers                                                       */
+/* ------------------------------------------------------------------ */
 /**
  * Compute SHA-256 hex hash of a string (UTF-8).
  */
@@ -29,16 +39,214 @@ export function syncHash(comment) {
     return comment;
 }
 /**
- * Serialize an MrsfDocument to YAML.
+ * Known comment field keys in preferred output order (for new comments).
+ */
+const COMMENT_KEY_ORDER = [
+    "id", "author", "timestamp", "text", "type", "severity",
+    "resolved", "reply_to", "line", "end_line", "start_column", "end_column",
+    "selected_text", "selected_text_hash", "anchored_text", "commit",
+];
+/* ·· value serialisation ·············································· */
+/**
+ * Convert a JS value to its YAML source text representation.
+ * Strings that require quoting get double-quoted; numbers and booleans
+ * are plain scalars.
+ */
+function valueToSource(v) {
+    if (typeof v === "number" || typeof v === "boolean")
+        return String(v);
+    if (typeof v === "string") {
+        // Strings that need quoting
+        if (/[:\n"{}[\],&#*?|><!%@`]/.test(v) ||
+            v.includes(" #") ||
+            v === "" ||
+            v === "true" ||
+            v === "false" ||
+            v === "null" ||
+            /^\d/.test(v)) {
+            return JSON.stringify(v);
+        }
+        return v;
+    }
+    return String(v);
+}
+/** Return the CST scalar type for a value. */
+function valueType(v) {
+    return valueToSource(v).startsWith('"') ? "double-quoted-scalar" : "scalar";
+}
+/* ·· CST node construction ············································ */
+const NL = "\n";
+/**
+ * Build a CST map-item (key: value\n) suitable for insertion into a
+ * block-map's `items` array.
+ *
+ * @param isFirst  If true, omit leading indent (first item in a block-map
+ *                 inherits indent from the parent seq-item-ind).
+ */
+function makeCstMapItem(key, value, indent, isFirst) {
+    const start = isFirst
+        ? []
+        : [{ type: "space", offset: 0, indent: 0, source: " ".repeat(indent) }];
+    return {
+        start,
+        key: { type: "scalar", offset: 0, indent, source: key },
+        sep: [
+            { type: "map-value-ind", offset: 0, indent, source: ":" },
+            { type: "space", offset: 0, indent, source: " " },
+        ],
+        value: {
+            type: valueType(value),
+            offset: 0,
+            indent,
+            source: valueToSource(value),
+            end: [{ type: "newline", offset: 0, indent, source: NL }],
+        },
+    };
+}
+/**
+ * Build a complete CST seq-item for a brand-new Comment (block-map inside
+ * a block-seq).
+ */
+function makeCstSeqItem(comment, seqIndent) {
+    const mapIndent = seqIndent + 2;
+    const items = [];
+    // Preferred key order first
+    for (const key of COMMENT_KEY_ORDER) {
+        const val = comment[key];
+        if (val !== undefined) {
+            items.push(makeCstMapItem(key, val, mapIndent, items.length === 0));
+        }
+    }
+    // Extension / extra fields
+    for (const key of Object.keys(comment)) {
+        if (!COMMENT_KEY_ORDER.includes(key) &&
+            comment[key] !== undefined) {
+            items.push(makeCstMapItem(key, comment[key], mapIndent, items.length === 0));
+        }
+    }
+    return {
+        start: [
+            { type: "newline", offset: 0, indent: 0, source: NL },
+            { type: "space", offset: 0, indent: 0, source: " ".repeat(seqIndent) },
+            { type: "seq-item-ind", offset: 0, indent: seqIndent, source: "-" },
+            { type: "space", offset: 0, indent: seqIndent, source: " " },
+        ],
+        value: { type: "block-map", offset: 0, indent: mapIndent, items },
+    };
+}
+/* ·· CST navigation ··················································· */
+/** Find the document token in a CST token stream. */
+function findCstDocument(tokens) {
+    return tokens.find((t) => t.type === "document") ?? null;
+}
+/** Find an item in a block-map by key source text. */
+function findCstMapEntry(blockMap, keyName) {
+    return (blockMap.items?.find((item) => item.key?.source === keyName) ?? null);
+}
+/** Get the index of a map entry by key source text (−1 if missing). */
+function findCstMapIndex(blockMap, keyName) {
+    return (blockMap.items?.findIndex((item) => item.key?.source === keyName) ?? -1);
+}
+/** Read the plain-text id from a CST block-map (comment). */
+function cstCommentId(blockMap) {
+    const entry = findCstMapEntry(blockMap, "id");
+    if (!entry?.value?.source)
+        return null;
+    const src = entry.value.source;
+    // Strip quotes if present
+    if (src.startsWith('"') && src.endsWith('"')) {
+        return src.slice(1, -1);
+    }
+    return src;
+}
+/* ·· CST mutation ····················································· */
+/**
+ * Update an existing scalar CST value's source text.
+ * Returns true if the source was actually changed.
+ */
+function updateCstScalar(entry, newValue) {
+    const newSrc = valueToSource(newValue);
+    if (entry.value?.source === newSrc)
+        return false;
+    entry.value.source = newSrc;
+    // If type changed (e.g. plain → quoted), update it too
+    entry.value.type = valueType(newValue);
+    return true;
+}
+/**
+ * Synchronize a plain Comment object into a CST block-map, preserving
+ * untouched scalars byte-for-byte.
+ *
+ * @param blockMap   CST block-map node for the comment
+ * @param comment    New model values to write
+ * @param currentValues  Already-parsed values from the existing YAML
+ *                       (used to detect real changes vs source-format
+ *                       differences like quoted vs folded scalars)
+ */
+function syncCommentToCst(blockMap, comment, currentValues) {
+    const commentRec = comment;
+    // Collect existing key names
+    const existingKeys = new Set();
+    for (const item of blockMap.items ?? []) {
+        if (item.key?.source)
+            existingKeys.add(item.key.source);
+    }
+    const allKeys = new Set([...existingKeys, ...Object.keys(comment)]);
+    const indent = blockMap.indent ?? 4;
+    for (const key of allKeys) {
+        const newVal = commentRec[key];
+        if (newVal === undefined) {
+            // Removed from model → delete from CST
+            if (existingKeys.has(key)) {
+                const idx = findCstMapIndex(blockMap, key);
+                if (idx >= 0)
+                    blockMap.items.splice(idx, 1);
+            }
+            continue;
+        }
+        const entry = findCstMapEntry(blockMap, key);
+        if (entry) {
+            // Existing key — compare PARSED values (not source text) to detect
+            // real semantic changes.  This avoids touching block scalars, quoted
+            // strings, etc. whose source representation differs but whose parsed
+            // value is identical.
+            const currentVal = currentValues[key];
+            if (deepEqual(currentVal, newVal)) {
+                // Value unchanged — leave the CST node byte-for-byte
+                continue;
+            }
+            // Value really changed — update source
+            updateCstScalar(entry, newVal);
+        }
+        else {
+            // New key — insert at end
+            blockMap.items.push(makeCstMapItem(key, newVal, indent, false));
+        }
+    }
+}
+/**
+ * Simple deep-equal for scalars and basic types (sufficient for MRSF
+ * Comment field values which are strings, numbers, and booleans).
+ */
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    // Handle number comparison with potential string/number mismatch from YAML
+    if (typeof a === "number" && typeof b === "number")
+        return a === b;
+    return false;
+}
+/* ------------------------------------------------------------------ */
+/*  Public API                                                         */
+/* ------------------------------------------------------------------ */
+/**
+ * Serialize an MrsfDocument to YAML (for new files / non-round-trip use).
  */
 export function toYaml(doc) {
-    return yaml.dump(doc, {
-        lineWidth: -1, // no wrapping
-        quotingType: '"',
-        forceQuotes: false,
-        noRefs: true,
-        sortKeys: false, // preserve insertion order
-    });
+    const yamlDoc = new Document(doc);
+    return yamlDoc.toString({ lineWidth: 0 });
 }
 /**
  * Serialize an MrsfDocument to JSON.
@@ -47,16 +255,146 @@ export function toJson(doc) {
     return JSON.stringify(doc, null, 2) + "\n";
 }
 /**
- * Write an MrsfDocument to disk. Detects format from file extension.
+ * Write an MrsfDocument to disk.
+ *
+ * When a YAML file already exists on disk, performs a **CST-level** round-trip
+ * merge that preserves YAML comments, scalar styles, key ordering, and
+ * whitespace byte-for-byte for unchanged content.
+ *
+ * For new files or JSON, writes from scratch.
  */
 export async function writeSidecar(filePath, doc) {
     const abs = path.resolve(filePath);
     const isJson = abs.endsWith(".review.json");
-    // Sync hashes for all comments before writing
+    if (isJson) {
+        // For JSON, always sync hashes and write fresh
+        for (const comment of doc.comments)
+            syncHash(comment);
+        await writeFile(abs, toJson(doc), "utf-8");
+        return;
+    }
+    // ── YAML round-trip path ──────────────────────────────────────────
+    if (!existsSync(abs)) {
+        for (const comment of doc.comments)
+            syncHash(comment);
+        await writeFile(abs, toYaml(doc), "utf-8");
+        return;
+    }
+    let raw;
+    try {
+        raw = await readFile(abs, "utf-8");
+    }
+    catch {
+        await writeFile(abs, toYaml(doc), "utf-8");
+        return;
+    }
+    // Parse to CST tokens
+    let tokens;
+    try {
+        tokens = [...new Parser().parse(raw)];
+    }
+    catch {
+        // Unparseable — write fresh
+        await writeFile(abs, toYaml(doc), "utf-8");
+        return;
+    }
+    // Also parse to plain JS object for value comparison (so we compare
+    // parsed values, not source-text representations)
+    let currentDoc = null;
+    try {
+        currentDoc = yamlParse(raw);
+    }
+    catch {
+        // ignore — we'll fall through to source-level comparison
+    }
+    // Build lookup of current parsed values by comment id
+    const currentById = new Map();
+    if (currentDoc?.comments) {
+        for (const c of currentDoc.comments) {
+            if (c.id)
+                currentById.set(c.id, c);
+        }
+    }
+    // Sync hashes: for existing comments, only add selected_text_hash
+    // if selected_text actually changed or hash was already present.
+    // For new comments, always sync.
+    for (const comment of doc.comments) {
+        const cur = currentById.get(comment.id);
+        if (!cur) {
+            // New comment — always sync hash
+            syncHash(comment);
+        }
+        else {
+            // Existing comment — only sync hash if text changed or hash
+            // was already tracked in the original
+            const textChanged = !deepEqual(cur.selected_text, comment.selected_text);
+            const hadHash = cur.selected_text_hash !== undefined;
+            if (textChanged || hadHash) {
+                syncHash(comment);
+            }
+            else {
+                // Don't inject a hash that wasn't there before
+                delete comment.selected_text_hash;
+            }
+        }
+    }
+    const docToken = findCstDocument(tokens);
+    if (!docToken?.value || docToken.value.type !== "block-map") {
+        await writeFile(abs, toYaml(doc), "utf-8");
+        return;
+    }
+    const body = docToken.value;
+    // ── Update top-level scalars ──────────────────────────────────────
+    const versionEntry = findCstMapEntry(body, "mrsf_version");
+    if (versionEntry && !deepEqual(currentDoc?.mrsf_version, doc.mrsf_version)) {
+        updateCstScalar(versionEntry, doc.mrsf_version);
+    }
+    const documentEntry = findCstMapEntry(body, "document");
+    if (documentEntry && !deepEqual(currentDoc?.document, doc.document)) {
+        updateCstScalar(documentEntry, doc.document);
+    }
+    // ── Merge comments ────────────────────────────────────────────────
+    const commentsEntry = findCstMapEntry(body, "comments");
+    if (!commentsEntry?.value || commentsEntry.value.type !== "block-seq") {
+        // No existing comments seq — write fresh
+        await writeFile(abs, toYaml(doc), "utf-8");
+        return;
+    }
+    const seq = commentsEntry.value;
+    const seqIndent = seq.indent ?? 2;
+    // Index existing CST comments by id
+    const existingById = new Map();
+    for (let i = 0; i < seq.items.length; i++) {
+        const item = seq.items[i];
+        const map = item.value;
+        if (map?.type === "block-map") {
+            const id = cstCommentId(map);
+            if (id)
+                existingById.set(id, { index: i, map });
+        }
+    }
+    // Build new seq items list, preserving existing CST nodes (and their
+    // YAML comments / formatting) for comments that still exist.
+    const idsInDoc = new Set(doc.comments.map((c) => c.id));
+    const newSeqItems = [];
     for (const comment of doc.comments) {
-        syncHash(comment);
+        const existing = existingById.get(comment.id);
+        if (existing) {
+            // Round-trip: sync changes into the existing CST block-map
+            const currentValues = currentById.get(comment.id) ?? {};
+            syncCommentToCst(existing.map, comment, currentValues);
+            // Re-use the original seq item (preserves preceding YAML comments
+            // in the item's `start` tokens)
+            newSeqItems.push(seq.items[existing.index]);
+        }
+        else {
+            // Brand new comment — construct CST from scratch
+            newSeqItems.push(makeCstSeqItem(comment, seqIndent));
+        }
     }
-    const content = isJson ? toJson(doc) : toYaml(doc);
-    await writeFile(abs, content, "utf-8");
+    seq.items = newSeqItems;
+    // ── Stringify via CST (byte-identical for untouched content) ───────
+    const result = tokens.map((t) => CST.stringify(t)).join("");
+    await writeFile(abs, result, "utf-8");
 }
 //# sourceMappingURL=writer.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrsf/cli",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "CLI and library for the Markdown Review Sidecar Format (MRSF)",
   "type": "module",
   "main": "./dist/index.js",
@@ -58,7 +58,8 @@
     "commander": "^13.1.0",
     "fastest-levenshtein": "^1.0.16",
     "js-yaml": "^4.1.0",
-    "uuid": "^11.1.0"
+    "uuid": "^11.1.0",
+    "yaml": "^2.8.2"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",