@popoverai/dotrequirements 0.29.0 → 0.29.2

package/dist/schema/parser-core.js

@@ -4,7 +4,7 @@
  * This module contains pure parsing functions with no Node.js dependencies,
  * making it safe to import in Convex runtime or browser environments.
  */
-import { ValidationError, validateKey, } from "./schemas.js";
+import { REQUIREMENT_KEY_PATTERN, ValidationError, validateKey, } from "./schemas.js";
 /**
  * The label stamped on every requirement's root, for indexing and querying.
  *
@@ -78,7 +78,7 @@ export function parseRootLine(line, delimiter = DELIMITER_PATTERN) {
     const trimmed = line.trim();
     // Try to match: KEY + colon + content (explicit key format)
     // KEY must be followed by colon (not arrow) to distinguish from "Label → content"
-    const keyMatch = trimmed.match(/^([\w-]+):\s*(.+)$/);
+    const keyMatch = trimmed.match(/^([\w-]+):\s*(.*)$/);
     if (keyMatch) {
         return {
             key: keyMatch[1],
@@ -106,7 +106,13 @@ export function parseRootLine(line, delimiter = DELIMITER_PATTERN) {
  * First line is the requirement content (with optional arrow format).
  * Subsequent lines are criteria with position paths.
  */
-export function parseRequirementBlock(key, blockContent) {
+export function parseRequirementBlock(key, blockContent, 
+/**
+ * Zero-based line index of this block within its fence. A fence may group
+ * several roots, so without it every root's diagnostics would count from its
+ * own first line and "at line 3" would occur once per root.
+ */
+lineOffset = 0) {
     const lines = blockContent.trim().split("\n");
     if (lines.length === 0) {
         throw new ValidationError("Empty requirement block", key);
@@ -134,20 +140,27 @@ export function parseRequirementBlock(key, blockContent) {
         }
         const criterion = parseCriterionLine(line);
         if (!criterion) {
-            // Only a line whose prefix is shaped like a requirement KEY (uppercase
-            // prefix + "-<digits>", per REQUIREMENT_KEY_PATTERN) suggests a second
-            // requirement in the block; a stray "https://..." must not be
-            // misdiagnosed as one.
             const trimmedLine = line.trim();
-            if (/^[A-Z][A-Z-]*-\d+:\s*.+/.test(trimmedLine)) {
-                throw new ValidationError(`Multiple requirements in single block. Found "${trimmedLine.split(":")[0]}" at line ${i + 1}, but each requirement must have its own \`\`\`dotrequirements code block.`, key);
+            // SYNC-KEY-1.5: a line written as "KEY: content" is someone starting
+            // another requirement, not writing a criterion. Blame the key so the
+            // error teaches key format rather than criterion format.
+            const rootAttempt = trimmedLine.match(ROOT_ATTEMPT_PATTERN);
+            if (rootAttempt) {
+                try {
+                    validateKey(rootAttempt[1]);
+                }
+                catch (err) {
+                    // validateKey has no line context, and in a grouped fence naming the
+                    // key without naming where it is makes the author hunt for it.
+                    throw new ValidationError(`${err instanceof Error ? err.message : String(err)} (at line ${i + 1 + lineOffset})`, key, err);
+                }
             }
-            throw new ValidationError(`Invalid criterion format at line ${i + 1}: "${trimmedLine}". Expected format: "N. Label → content" (e.g., "0. Given → user is logged in")`, key);
+            throw new ValidationError(`Invalid criterion format at line ${i + 1 + lineOffset}: "${trimmedLine}". Expected format: "N. Label → content" (e.g., "0. Given → user is logged in")`, key);
         }
         // SYNC-FORMAT-2.1: a duplicate position is structural ambiguity — reject
         // it instead of silently dropping the earlier criterion.
         if (criteriaByPosition.has(criterion.position)) {
-            throw new ValidationError(`Duplicate criterion position "${criterion.position}" at line ${i + 1} — each position may appear only once per requirement`, key);
+            throw new ValidationError(`Duplicate criterion position "${criterion.position}" at line ${i + 1 + lineOffset} — each position may appear only once per requirement`, key);
         }
         criteriaByPosition.set(criterion.position, criterion);
     }
@@ -227,9 +240,104 @@ function buildChildrenFromPositions(parent, parentPosition, rootKey, criteriaByP
         parent.children.push(childNode);
     }
 }
+const EXPLICIT_ROOT_LINE_PATTERN = /^([\w-]+):\s*(.*)$/;
+/**
+ * A line someone plainly meant as a root requirement: "KEY: content", where the
+ * candidate was reaching for the `PREFIX-<number>` shape — it starts with a
+ * letter and either contains a digit or trails off at the hyphen where the
+ * number belongs.
+ *
+ * Used only to pick the right diagnostic (SYNC-KEY-1.5), so it is deliberately
+ * narrower than the root grammar. Every exclusion earns its keep by keeping a
+ * line that is really a fumbled *criterion* on criterion advice:
+ *   - leading letter        — a mistyped position ("0:" for "0.")
+ *   - space-or-EOL          — a bare "https://…" line, not a key named "https"
+ *   - digit-or-trailing "-" — "Given:", "Note:", "TODO:", and this project's
+ *                             hyphenated labels ("edit-mode:", "view-mode:").
+ *                             "Given:" for "Given →" is the likeliest fumble of
+ *                             all, since the format itself teaches that word.
+ * It catches "LOGIN_2:", "LOGIN2:", "OAUTH2-2:", and "LOGIN-:".
+ */
+const ROOT_ATTEMPT_PATTERN = /^([A-Za-z][\w-]*(?:\d[\w-]*|-)):(?:\s|$)/;
+/**
+ * Strip the indentation the whole fence shares, so a fence nested inside a
+ * Markdown list item still has its roots at column zero. Trimming the body as a
+ * whole would de-indent only the first line, leaving every later root indented
+ * and therefore invisible as a root.
+ */
+function dedentFenceBody(content) {
+    const all = content.replace(/\r\n/g, "\n").split("\n");
+    let start = 0;
+    let end = all.length;
+    while (start < end && !all[start].trim())
+        start++;
+    while (end > start && !all[end - 1].trim())
+        end--;
+    const lines = all.slice(start, end);
+    const indents = lines
+        .filter((l) => l.trim())
+        .map((l) => l.match(/^[ \t]*/)?.[0].length ?? 0);
+    const common = indents.length ? Math.min(...indents) : 0;
+    return {
+        lines: lines.map((l) => (l.trim() ? l.slice(common) : l)),
+        offset: start,
+    };
+}
+/**
+ * Split one dotrequirements fence into its independent root requirements.
+ *
+ * A fence marks a contiguous structured region; each unindented, well-formed
+ * KEY: content line starts a new root. The shared key pattern is tested against
+ * an uppercase candidate because key validation is case-insensitive
+ * (SYNC-KEY-1.3). Authored casing remains untouched in the returned block.
+ *
+ * Splitting is structural, not a grammar check: it rejects content that is not
+ * shaped like a requirement block at all, but a *malformed key* is passed
+ * through for the caller to judge. Validating keys here made every reader as
+ * strict as the authoring path — a legacy "LOGIN_1" in the cloud took down a
+ * whole `dotreq diff` run and rendered as raw markdown in the chat document
+ * view. Key grammar is enforced in extractRequirementBlocks (SYNC-KEY-1),
+ * on the authoring and save paths.
+ */
+export function splitRequirementFenceContent(content) {
+    const { lines, offset } = dedentFenceBody(content);
+    const firstRoot = lines[0]?.match(EXPLICIT_ROOT_LINE_PATTERN);
+    if (!firstRoot) {
+        throw new ValidationError(`Invalid requirement block format - first line must be "KEY: content"`, content.substring(0, 50));
+    }
+    const blocks = [];
+    let currentKey = firstRoot[1];
+    let currentLines = [lines[0]];
+    let currentStart = 0;
+    const flushCurrent = () => {
+        blocks.push({
+            key: currentKey,
+            blockContent: currentLines.join("\n").trim(),
+            startLine: currentStart + offset,
+        });
+    };
+    for (let i = 1; i < lines.length; i++) {
+        const rootMatch = lines[i].match(EXPLICIT_ROOT_LINE_PATTERN);
+        const nextKey = rootMatch && REQUIREMENT_KEY_PATTERN.test(rootMatch[1].toUpperCase())
+            ? rootMatch[1]
+            : undefined;
+        if (nextKey !== undefined) {
+            flushCurrent();
+            currentKey = nextKey;
+            currentLines = [lines[i]];
+            currentStart = i;
+        }
+        else {
+            currentLines.push(lines[i]);
+        }
+    }
+    flushCurrent();
+    return blocks;
+}
 /**
  * Extract requirement blocks from Markdown body (no frontmatter).
- * Returns an array of { key, blockContent } for each dotrequirements block found.
+ * A fence may contain multiple adjacent root requirements; each root is
+ * returned as its own logical block.
  */
 export function extractRequirementBlocks(body) {
     const blocks = [];
@@ -238,24 +346,21 @@ export function extractRequirementBlocks(body) {
     const blockRegex = /```dotrequirements\n([\s\S]*?)```/gm;
     let match = blockRegex.exec(body);
     while (match !== null) {
-        const blockContent = match[1];
-        // Extract key from first line of block (format: "KEY: content")
-        const firstLineMatch = blockContent.match(/^([\w-]+):\s*(.+)/);
-        if (!firstLineMatch) {
-            throw new ValidationError(`Invalid requirement block format - first line must be "KEY: content"`, blockContent.substring(0, 50));
-        }
-        const key = firstLineMatch[1];
-        // SYNC-KEY-1: reject malformed keys at parse time so push/validate fail
-        // locally instead of erroring server-side. Validation only — the original
-        // key is preserved (normalization happens downstream).
-        validateKey(key);
-        // SYNC-FORMAT-2.0: a duplicate key is structural ambiguity — reject it
-        // instead of producing two requirements with the same key.
-        if (seenKeys.has(key)) {
-            throw new ValidationError(`Duplicate requirement key "${key}" — each requirement key may appear in only one block`, key);
+        const fenceBlocks = splitRequirementFenceContent(match[1]);
+        for (const block of fenceBlocks) {
+            // SYNC-KEY-1: reject malformed keys at parse time so push/validate fail
+            // locally instead of erroring server-side. The original key is preserved
+            // in parsed content; normalizedKey is identity-only.
+            const normalizedKey = validateKey(block.key);
+            // SYNC-FORMAT-2.0: duplicate canonical keys are structural ambiguity,
+            // whether they share a fence, use separate fences, or differ by casing
+            // or leading zeros.
+            if (seenKeys.has(normalizedKey)) {
+                throw new ValidationError(`Duplicate requirement key "${block.key}" — each requirement key may appear only once in a document`, block.key);
+            }
+            seenKeys.add(normalizedKey);
+            blocks.push(block);
         }
-        seenKeys.add(key);
-        blocks.push({ key, blockContent: blockContent.trim() });
         match = blockRegex.exec(body);
     }
     return blocks;
@@ -309,9 +414,9 @@ export function parseRequirementBlocksFromMarkdown(markdownContent) {
     // identically regardless of line-ending style.
     const blocks = extractRequirementBlocks(markdownContent.replace(/\r\n/g, "\n"));
     const requirements = [];
-    for (const { key, blockContent } of blocks) {
+    for (const { key, blockContent, startLine } of blocks) {
         try {
-            const reqNode = parseRequirementBlock(key, blockContent);
+            const reqNode = parseRequirementBlock(key, blockContent, startLine);
             requirements.push(reqNode);
         }
         catch (error) {

package/dist/schema/parser.d.ts

@@ -8,7 +8,8 @@
  * requirements file means (SYNC-FORMAT-2.3).
  */
 import { type RequirementNode, type RequirementsFile } from "./schemas.js";
-export { findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRootLine, } from "./parser-core.js";
+export type { ExtractedRequirementBlock } from "./parser-core.js";
+export { findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRootLine, splitRequirementFenceContent, } from "./parser-core.js";
 /**
  * Parse a complete requirements Markdown file.
  */

package/dist/schema/parser.js

@@ -13,7 +13,7 @@ import { parseRequirementBlocksFromMarkdown, splitFrontmatter, } from "./parser-
 import { ValidationError, validateMetadata, } from "./schemas.js";
 // Block/criterion parsing and tree utilities live in parser-core; re-exported
 // here so the schema module's public surface is unchanged.
-export { findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRootLine, } from "./parser-core.js";
+export { findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRootLine, splitRequirementFenceContent, } from "./parser-core.js";
 /**
  * Extract YAML frontmatter from Markdown content.
  * Returns { frontmatter, body } where frontmatter is the parsed YAML object.

package/dist/schema/schemas.d.ts

@@ -49,6 +49,17 @@ export declare function parseRequirementKey(key: string): {
     prefix: string;
     number: number;
 } | null;
+/**
+ * The canonical spelling of a key, for deciding whether two keys name the same
+ * requirement. Casing and leading zeros are authoring latitude (SYNC-KEY-1.3)
+ * and the cloud stores the canonical form, so "login-02" and "LOGIN-2" must
+ * compare equal (DIFF-3.3).
+ *
+ * A key that doesn't parse has no canonical form; it uppercases instead, so
+ * callers that must stay total (sync segmentation) keep a usable identity for a
+ * legacy malformed key rather than losing it.
+ */
+export declare function canonicalRequirementKey(key: string): string;
 /**
  * Build a requirement key from prefix and number.
  */

package/dist/schema/schemas.js

@@ -89,6 +89,20 @@ export function parseRequirementKey(key) {
         return null;
     return { prefix, number: parseInt(numStr, 10) };
 }
+/**
+ * The canonical spelling of a key, for deciding whether two keys name the same
+ * requirement. Casing and leading zeros are authoring latitude (SYNC-KEY-1.3)
+ * and the cloud stores the canonical form, so "login-02" and "LOGIN-2" must
+ * compare equal (DIFF-3.3).
+ *
+ * A key that doesn't parse has no canonical form; it uppercases instead, so
+ * callers that must stay total (sync segmentation) keep a usable identity for a
+ * legacy malformed key rather than losing it.
+ */
+export function canonicalRequirementKey(key) {
+    const parsed = parseRequirementKey(key);
+    return parsed ? `${parsed.prefix}-${parsed.number}` : key.toUpperCase();
+}
 /**
  * Build a requirement key from prefix and number.
  */

package/dist/sync/compare.js

@@ -198,7 +198,22 @@ function compareDocument(local, cloud) {
     if (!diverges && normalizeBody(body) === normalizeBody(cloud.body)) {
         return { ...base, verdict: "in_sync" };
     }
-    const { verdict: bodyVerdict, details } = classifyBodies(body, cloud.body);
+    // SYNC-FAIL-4.2: cloud bodies reach the snapshot as stored markdown, never
+    // re-parsed, so a document saved before today's grammar can still be
+    // unreadable. Segmentation is total, so this is a backstop — and it resolves
+    // to "conflict", never "invalid_file": invalid_file maps to "skip" in every
+    // sync mode including --repo-wins, which would leave the document permanently
+    // unrepairable, and it names the local file for a problem in the cloud copy.
+    // Conflict is both honest (we cannot show the change is additive) and
+    // actionable (`--repo-wins` overwrites the bad cloud body).
+    let classified;
+    try {
+        classified = classifyBodies(body, cloud.body);
+    }
+    catch {
+        return { ...base, verdict: "conflict" };
+    }
+    const { verdict: bodyVerdict, details } = classified;
     let verdict;
     if (diverges) {
         // A changed single-valued attribute is never additive → conflict.

package/dist/sync/execute.d.ts

@@ -5,7 +5,7 @@
  * frontmatter write-back) so document-header/import-provenance fidelity is
  * identical to a repo→cloud push. Local writes reuse local-files.ts.
  */
-import type { PlannedAction } from "./plan.js";
+import type { PlannedAction, SyncMode } from "./plan.js";
 import type { CloudAuth } from "./snapshot.js";
 import type { CloudSnapshot, DocumentComparison } from "./types.js";
 export interface SyncOutcome {
@@ -43,11 +43,19 @@ export interface SyncOutcome {
         from: string;
         to: string;
     }>;
+    /** DOC-HEADER-11.4: documents whose prefix was inferred from their first
+     * requirement key rather than read from frontmatter. The sync writes that
+     * prefix into the file and sends it to the cloud, so it is never a value
+     * Jaime has to discover by diffing afterwards. */
+    inferredPrefixes: Array<{
+        name: string;
+        prefix: string;
+    }>;
 }
 /**
  * Execute a plan. `cloud` provides bodies for local writes (keyed by id). Cloud
  * writes require a project slug in `auth`; a read-only share run has none and
  * its plan carries no cloud-writing actions.
  */
-export declare function executePlan(plan: PlannedAction[], cloud: CloudSnapshot, auth: CloudAuth, workspaceRoot: string): Promise<SyncOutcome>;
+export declare function executePlan(plan: PlannedAction[], cloud: CloudSnapshot, auth: CloudAuth, workspaceRoot: string, mode: SyncMode): Promise<SyncOutcome>;
 //# sourceMappingURL=execute.d.ts.map

package/dist/sync/execute.js

@@ -10,9 +10,9 @@ import * as path from "node:path";
 import { ConvexHttpClient } from "convex/browser";
 import { getConvexUrl } from "../config.js";
 import { api } from "../convex.js";
-import { mergeMetadataWithRawFrontmatter, parseFilesForPushIndividually, WEB_APP_URL, } from "../push/core.js";
-import { buildRequirementsFile, composeMarkdownWithTitle, splitLeadingH1, } from "../schema/index.js";
-import { resolveLocalPath, writeLocalDocument } from "./local-files.js";
+import { parseFilesForPushIndividually, WEB_APP_URL } from "../push/core.js";
+import { composeMarkdownWithTitle, splitLeadingH1, writeRequirementsFile, } from "../schema/index.js";
+import { resolveLocalPath } from "./local-files.js";
 function emptyOutcome() {
     return {
         cloudCreated: 0,
@@ -27,6 +27,7 @@ function emptyOutcome() {
         writeBackWarnings: [],
         importWarnings: [],
         renames: [],
+        inferredPrefixes: [],
     };
 }
 /**
@@ -34,7 +35,7 @@ function emptyOutcome() {
  * writes require a project slug in `auth`; a read-only share run has none and
  * its plan carries no cloud-writing actions.
  */
-export async function executePlan(plan, cloud, auth, workspaceRoot) {
+export async function executePlan(plan, cloud, auth, workspaceRoot, mode) {
     const outcome = emptyOutcome();
     const client = new ConvexHttpClient(getConvexUrl());
     const cloudById = new Map(cloud.documents.map((d) => [d.documentId, d]));
@@ -59,7 +60,7 @@ export async function executePlan(plan, cloud, auth, workspaceRoot) {
                     await cloudDelete(client, auth, doc, outcome);
                     break;
                 case "local_write":
-                    localWrite(doc, cloudById, usedPaths, requirementsDir, outcome);
+                    localWrite(doc, cloudById, usedPaths, requirementsDir, outcome, mode);
                     break;
                 case "local_delete":
                     localDelete(doc, outcome);
@@ -141,6 +142,16 @@ async function cloudWrite(client, auth, doc, cloudById, outcome) {
         outcome.cloudCreated++;
     else
         outcome.cloudUpdated++;
+    // DOC-HEADER-11.4: the prefix that just went to the cloud was read off the
+    // first requirement key, not authored — say which one, so it is never a
+    // value Jaime finds out about by diffing. Reported only now that the save
+    // has succeeded: a prefix from a push that failed was never used.
+    if (parsed.inferredDefaultPrefix && meta?.defaultPrefix) {
+        outcome.inferredPrefixes.push({
+            name: path.basename(doc.filePath),
+            prefix: meta.defaultPrefix,
+        });
+    }
     // SYNC-TITLE-1.3: a push that changes the title is a rename — announce it,
     // so an unintended H1 edit is visible and costs one heading edit to undo.
     // The new title is derived from the pushed markdown exactly as the server
@@ -167,17 +178,19 @@ async function cloudWrite(client, auth, doc, cloudById, outcome) {
     // failure is a warning on a synced document, never a sync failure (which
     // would invite a retry that mints a duplicate).
     try {
-        if (parsed.metadata.document) {
-            parsed.metadata.document.id = documentId;
-            // SYNC-TITLE-1.2: drop the legacy frontmatter title — the body already
-            // carries the name as its leading H1 (materialized above, before the
-            // push), so the rewritten file loses the field without losing the title.
-            delete parsed.metadata.document.title;
-        }
-        parsed.metadata.pulledAt = new Date().toISOString();
-        parsed.metadata.version = (parsed.metadata.version ?? 0) + 1;
-        const content = buildRequirementsFile(mergeMetadataWithRawFrontmatter(parsed.metadata, parsed.rawFrontmatter), parsed.markdownContent);
-        fs.writeFileSync(doc.filePath, content, "utf-8");
+        // The legacy frontmatter title is not carried over (SYNC-TITLE-1.2) — the
+        // body already carries the name as its leading H1 (materialized above,
+        // before the push), so the rewritten file loses the field without losing
+        // the title.
+        writeRequirementsFile(doc.filePath, {
+            documentId,
+            // The prefix just pushed is the file's own (or the one inferred from
+            // its first key, DOC-HEADER-11.4, which the write-back materializes).
+            defaultPrefix: meta?.defaultPrefix
+                ? { set: meta.defaultPrefix }
+                : "keep",
+            version: (parsed.metadata.version ?? 0) + 1,
+        }, parsed.markdownContent);
     }
     catch (writeErr) {
         outcome.writeBackWarnings.push({
@@ -202,7 +215,7 @@ async function cloudDelete(client, auth, doc, outcome) {
     });
     outcome.cloudDeleted++;
 }
-function localWrite(doc, cloudById, usedPaths, requirementsDir, outcome) {
+function localWrite(doc, cloudById, usedPaths, requirementsDir, outcome, mode) {
     const cloudDoc = doc.documentId ? cloudById.get(doc.documentId) : undefined;
     if (!cloudDoc)
         throw new Error(`No cloud content for ${doc.title}`);
@@ -210,7 +223,20 @@ function localWrite(doc, cloudById, usedPaths, requirementsDir, outcome) {
         fs.mkdirSync(requirementsDir, { recursive: true });
     const filePath = resolveLocalPath(cloudDoc, doc.filePath, usedPaths, requirementsDir);
     usedPaths.add(filePath);
-    const changed = writeLocalDocument(filePath, cloudDoc);
+    // DOC-HEADER-11.6/11.7: a cloud document with no prefix means "nothing to
+    // impose" under an additive sync and "no prefix" under cloud-wins authority
+    // — so a prefix Jaime wrote is only ever removed by the mode they ran to
+    // make the repo match the cloud.
+    const defaultPrefix = cloudDoc.defaultPrefix
+        ? { set: cloudDoc.defaultPrefix }
+        : mode === "cloud_wins"
+            ? "clear"
+            : "keep";
+    const changed = writeRequirementsFile(filePath, {
+        documentId: cloudDoc.documentId,
+        defaultPrefix,
+        version: cloudDoc.version,
+    }, cloudDoc.body);
     if (changed)
         outcome.localWritten++;
 }

package/dist/sync/local-files.d.ts

@@ -1,7 +1,6 @@
 /**
- * Writing cloud content into local `.requirements/` files — the local half of
- * sync. Shared filename/collision logic (SYNC-WEB-CREATE-2) and the frontmatter
- * build (SYNC-WRITE-1) live here so pull and sync agree.
+ * Choosing where cloud content lands in `.requirements/` — the local half of
+ * sync. The bytes themselves are written by `writeRequirementsFile`.
  */
 import type { CloudDocument } from "./types.js";
 /** Sanitize a document title into a filename stem. */
@@ -14,13 +13,4 @@ export declare function sanitizeFileName(title: string): string;
  * (SYNC-WEB-CREATE-2).
  */
 export declare function resolveLocalPath(cloud: CloudDocument, existingPath: string | undefined, usedPaths: Set<string>, requirementsDir: string): string;
-/** Read the ctsRun marker from an existing file's frontmatter, if any (IMPORT-1). */
-export declare function readCtsRun(filePath: string): string | undefined;
-/**
- * Write a cloud document to a local file. `pulledAt` records when this content
- * arrived (SYNC-WRITE-1.1); an existing ctsRun marker is carried forward
- * (IMPORT-1). Returns true when the file's bytes actually changed — sync only
- * touches files whose content changed (SYNC-WRITE-1.0).
- */
-export declare function writeLocalDocument(filePath: string, cloud: CloudDocument): boolean;
 //# sourceMappingURL=local-files.d.ts.map

package/dist/sync/local-files.js

@@ -1,12 +1,9 @@
 /**
- * Writing cloud content into local `.requirements/` files — the local half of
- * sync. Shared filename/collision logic (SYNC-WEB-CREATE-2) and the frontmatter
- * build (SYNC-WRITE-1) live here so pull and sync agree.
+ * Choosing where cloud content lands in `.requirements/` — the local half of
+ * sync. The bytes themselves are written by `writeRequirementsFile`.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { buildRequirementsFile } from "../schema/index.js";
-import { extractFrontmatterBlock } from "../schema/parser-core.js";
 /** Sanitize a document title into a filename stem. */
 export function sanitizeFileName(title) {
     return title
@@ -33,61 +30,4 @@ export function resolveLocalPath(cloud, existingPath, usedPaths, requirementsDir
     }
     return candidate;
 }
-/** Read the ctsRun marker from an existing file's frontmatter, if any (IMPORT-1). */
-export function readCtsRun(filePath) {
-    if (!fs.existsSync(filePath))
-        return undefined;
-    // Search only the frontmatter block — a body line starting "ctsRun:" must
-    // not be mistaken for the marker.
-    const yaml = extractFrontmatterBlock(fs.readFileSync(filePath, "utf-8"));
-    const match = yaml?.match(/^ctsRun: (.+)$/m);
-    return match?.[1].trim();
-}
-/**
- * Write a cloud document to a local file. `pulledAt` records when this content
- * arrived (SYNC-WRITE-1.1); an existing ctsRun marker is carried forward
- * (IMPORT-1). Returns true when the file's bytes actually changed — sync only
- * touches files whose content changed (SYNC-WRITE-1.0).
- */
-export function writeLocalDocument(filePath, cloud) {
-    const existingCtsRun = readCtsRun(filePath);
-    // SYNC-TITLE-1.2: no `document.title` in frontmatter — the title lives in
-    // the body as its leading H1. A legacy file that gets rewritten loses the
-    // field here, since the metadata is rebuilt from scratch.
-    const metadata = {
-        pulledAt: new Date().toISOString(),
-        version: cloud.version,
-        ...(existingCtsRun ? { ctsRun: existingCtsRun } : {}),
-        document: {
-            id: cloud.documentId,
-            defaultPrefix: cloud.defaultPrefix,
-        },
-    };
-    const content = buildRequirementsFile(metadata, cloud.body);
-    // SYNC-WRITE-1.0: skip the write when the body+identity are unchanged, so a
-    // no-op sync leaves the working tree clean. Compare ignoring the volatile
-    // pulledAt line, which would otherwise force a rewrite every run.
-    if (fs.existsSync(filePath)) {
-        const current = fs.readFileSync(filePath, "utf-8");
-        if (withoutPulledAt(current) === withoutPulledAt(content))
-            return false;
-    }
-    fs.writeFileSync(filePath, content, "utf-8");
-    return true;
-}
-/**
- * Normalize the volatile pulledAt line for equality comparison — within the
- * frontmatter only, so a body line that happens to start "pulledAt:" can never
- * mask a genuine content change (which would silently skip the write).
- */
-function withoutPulledAt(fileContent) {
-    // CRLF-normalize first: extractFrontmatterBlock returns LF-normalized yaml,
-    // so the replace below must operate on LF content to find it.
-    const normalized = fileContent.replace(/\r\n/g, "\n");
-    const yaml = extractFrontmatterBlock(normalized);
-    if (yaml === undefined)
-        return normalized;
-    const normalizedYaml = yaml.replace(/^pulledAt: .*$/m, "pulledAt: <normalized>");
-    return normalized.replace(yaml, normalizedYaml);
-}
 //# sourceMappingURL=local-files.js.map

package/dist/sync/segment.d.ts

@@ -23,8 +23,8 @@ export type Unit = {
 export declare function normalizeProse(text: string): string;
 /**
  * Split a body into its ordered units. Prose between (and around) fences
- * becomes prose units when non-empty after normalization; each fence becomes a
- * requirement unit keyed by its first-line KEY.
+ * becomes prose units when non-empty after normalization; every root inside a
+ * fence becomes a requirement unit keyed by its KEY.
  */
 export declare function segmentBody(body: string): Unit[];
 /**