@popoverai/dotrequirements 0.29.0 → 0.29.2

package/dist/push/core.js

@@ -5,9 +5,8 @@
  * `push` command (its behavior now lives in the sync executor).
  */
 import * as fs from "node:fs";
-import YAML from "yaml";
 import { getAllRequirements, parseRequirementKey, parseRequirementsFromFile, } from "../schema/index.js";
-import { extractFrontmatterBlock, stripFrontmatterBlock, } from "../schema/parser-core.js";
+import { stripFrontmatterBlock } from "../schema/parser-core.js";
 /** Base URL of the web app, where synced documents are reviewed. */
 export const WEB_APP_URL = "https://app.dotrequirements.io";
 // ============================================================================
@@ -23,58 +22,6 @@ export function extractMarkdownContent(rawContent) {
     // body.
     return stripFrontmatterBlock(rawContent);
 }
-/**
- * DOC-HEADER-14: parse the frontmatter block as the user wrote it, keeping
- * keys the schema doesn't recognize (Zod strip-mode parsing discards them).
- */
-function extractRawFrontmatter(rawContent) {
-    // Shared helper normalizes CRLF (SYNC-FORMAT-1) so a Windows-saved file's
-    // custom keys survive the rewrite too (DOC-HEADER-14).
-    const frontmatterBlock = extractFrontmatterBlock(rawContent);
-    if (frontmatterBlock === undefined) {
-        return undefined;
-    }
-    try {
-        const parsed = YAML.parse(frontmatterBlock);
-        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-            return parsed;
-        }
-    }
-    catch {
-        // Unparseable frontmatter would have failed schema parsing already;
-        // treat as no extra keys to preserve.
-    }
-    return undefined;
-}
-/**
- * DOC-HEADER-14: merge the validated (and sync-updated) metadata over the raw
- * frontmatter so unrecognized keys survive the rewrite while the fields the
- * sync owns (document ID, pulledAt, defaultPrefix, version) stay updated.
- */
-export function mergeMetadataWithRawFrontmatter(metadata, rawFrontmatter) {
-    if (!rawFrontmatter) {
-        return metadata;
-    }
-    const merged = { ...rawFrontmatter, ...metadata };
-    const rawDocument = rawFrontmatter.document;
-    if (metadata.document &&
-        rawDocument &&
-        typeof rawDocument === "object" &&
-        !Array.isArray(rawDocument)) {
-        merged.document = {
-            ...rawDocument,
-            ...metadata.document,
-        };
-        // SYNC-TITLE-1.2: `document.title` is a recognized-but-retired field —
-        // the title lives in the body as its leading H1 — so a rewrite drops it
-        // rather than preserving it as if it were a user's custom field
-        // (DOC-HEADER-14 protects unrecognized fields, not this one).
-        if (!("title" in metadata.document)) {
-            delete merged.document.title;
-        }
-    }
-    return merged;
-}
 /**
  * Parse files for sync. Returns parsed files with metadata and content.
  *
@@ -93,10 +40,15 @@ export function parseFilesForPush(filePaths) {
         const flatRequirements = getAllRequirements(parsed.requirements);
         // Extract markdown content (everything after frontmatter)
         const markdownContent = extractMarkdownContent(rawContent);
-        // DOC-HEADER-11.1/11.2: Infer prefix from first requirement if not specified
+        // DOC-HEADER-11.1/11.2: Infer prefix from first requirement if not specified.
+        // A file with no `document:` section at all still gets one — such files sync
+        // like any other, so gating inference on the section's presence would deny
+        // them a prefix for a reason Jaime never sees.
+        if (!parsed.metadata.document)
+            parsed.metadata.document = {};
         const doc = parsed.metadata.document;
         let inferredDefaultPrefix = false;
-        if (doc && !doc.defaultPrefix && flatRequirements.length > 0) {
+        if (!doc.defaultPrefix && flatRequirements.length > 0) {
             const firstReq = flatRequirements[0];
             if (firstReq) {
                 const parsedKey = parseRequirementKey(firstReq.id);
@@ -113,8 +65,6 @@ export function parseFilesForPush(filePaths) {
             metadata: parsed.metadata,
             markdownContent,
             requirementCount: flatRequirements.length,
-            // DOC-HEADER-14: keep the user's frontmatter (unrecognized keys included)
-            rawFrontmatter: extractRawFrontmatter(rawContent),
             inferredDefaultPrefix,
         });
         totalRequirements += flatRequirements.length;

package/dist/push/index.d.ts

@@ -4,5 +4,5 @@
  * Shared parse-and-write-back primitives for syncing local requirements files
  * to the cloud, consumed by the comparator-driven sync path.
  */
-export { assertNoDuplicateDocumentIds, extractMarkdownContent, mergeMetadataWithRawFrontmatter, type ParsedFile, type ParseFailure, parseFilesForPush, parseFilesForPushIndividually, WEB_APP_URL, } from "./core.js";
+export { assertNoDuplicateDocumentIds, extractMarkdownContent, type ParsedFile, type ParseFailure, parseFilesForPush, parseFilesForPushIndividually, WEB_APP_URL, } from "./core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/push/index.js

@@ -6,5 +6,5 @@
  */
 export { assertNoDuplicateDocumentIds, 
 // Functions
-extractMarkdownContent, mergeMetadataWithRawFrontmatter, parseFilesForPush, parseFilesForPushIndividually, WEB_APP_URL, } from "./core.js";
+extractMarkdownContent, parseFilesForPush, parseFilesForPushIndividually, WEB_APP_URL, } from "./core.js";
 //# sourceMappingURL=index.js.map

package/dist/requirements/cloud-coverage.js

@@ -3,6 +3,7 @@
  * coverage from dot•requirements cloud. Shared between the MCP `report`
  * tool and the CLI `report` verb's `--source cloud` mode.
  */
+import { refusalReason } from "../harness/reportingStatus.js";
 /**
  * Query cloud for coverage on a single requirement, optionally filtered by
  * branch or recorded-since timestamp.
@@ -32,7 +33,9 @@ export async function getRequirementCoverage(requirementKey, projectId, projectS
     }
     const json = (await response.json());
     if (json.status === "error") {
-        throw new Error(`Convex query failed: ${json.errorMessage}`);
+        // COVERAGE-REPORT-1.2: the reason lives in errorData; errorMessage is the
+        // string production redacts to "[Request ID: …] Server Error".
+        throw new Error(`Could not read cloud coverage: ${refusalReason(json)}`);
     }
     const record = json.value;
     const { branch, sinceTimestamp } = options ?? {};
@@ -80,7 +83,9 @@ export async function getProjectCoverage(projectId, projectSecret, convexUrl, op
     }
     const json = (await response.json());
     if (json.status === "error") {
-        throw new Error(`Convex query failed: ${json.errorMessage}`);
+        // COVERAGE-REPORT-1.2: the reason lives in errorData; errorMessage is the
+        // string production redacts to "[Request ID: …] Server Error".
+        throw new Error(`Could not read cloud coverage: ${refusalReason(json)}`);
     }
     return json.value;
 }

package/dist/schema/browser.d.ts

@@ -6,9 +6,9 @@
 export { buildRequirementMarkdown, buildRequirementsMarkdown, DEFAULT_DELIMITER, } from "./builder.js";
 export type { ConvexRequirement } from "./conversions.js";
 export { buildMetadata, constructKey, convexToRequirements, extractRequirementKeys, groupByRoot, parseKey, requirementsToConvex, } from "./conversions.js";
-export { DELIMITER_PATTERN, extractRequirementBlocks, findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRequirementBlocksFromMarkdown, parseRootLine, ROOT_LABEL_MARKER, } from "./parser-core.js";
+export { DELIMITER_PATTERN, type ExtractedRequirementBlock, extractRequirementBlocks, findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRequirementBlocksFromMarkdown, parseRootLine, ROOT_LABEL_MARKER, splitRequirementFenceContent, } from "./parser-core.js";
 export type { Metadata, ParsedCriterion, RequirementKey, RequirementNode, RequirementPrefix, RequirementsFile, } from "./schemas.js";
-export { buildRequirementKey, MetadataSchema, normalizePrefix, ParsedCriterionSchema, parseRequirementKey, REQUIREMENT_KEY_PATTERN, REQUIREMENT_PREFIX_PATTERN, RequirementKeySchema, RequirementNodeSchema, RequirementPrefixSchema, RequirementsFileSchema, ValidationError, validateKey, validateMetadata, validatePrefix, validateRequirementNode, validateRequirementsFile, } from "./schemas.js";
+export { buildRequirementKey, canonicalRequirementKey, MetadataSchema, normalizePrefix, ParsedCriterionSchema, parseRequirementKey, REQUIREMENT_KEY_PATTERN, REQUIREMENT_PREFIX_PATTERN, RequirementKeySchema, RequirementNodeSchema, RequirementPrefixSchema, RequirementsFileSchema, ValidationError, validateKey, validateMetadata, validatePrefix, validateRequirementNode, validateRequirementsFile, } from "./schemas.js";
 export { composeMarkdownWithTitle, type SplitMarkdown, splitLeadingH1, } from "./title-markdown.js";
 export type { BuildScenarioOptions, Scenario, ScenarioAssertionSource, ScenarioStep, } from "./scenario.js";
 export { buildScenarioFromRequirements, requirementTreeToScenario, } from "./scenario.js";

package/dist/schema/browser.js

@@ -11,9 +11,9 @@ export { buildMetadata, constructKey, convexToRequirements, extractRequirementKe
 export { DELIMITER_PATTERN, extractRequirementBlocks, findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRequirementBlocksFromMarkdown, parseRootLine, 
 // The web reaches parser-core only through this entry point, so without this
 // its readers have no way to import the marker and must hard-code it.
-ROOT_LABEL_MARKER, } from "./parser-core.js";
+ROOT_LABEL_MARKER, splitRequirementFenceContent, } from "./parser-core.js";
 // Schemas and types (uses zod - browser-safe)
-export { buildRequirementKey, 
+export { buildRequirementKey, canonicalRequirementKey, 
 // Zod schemas
 MetadataSchema, 
 // Prefix/key utilities

package/dist/schema/builder.d.ts

@@ -17,7 +17,12 @@ export declare function buildRequirementsMarkdown(metadata: Metadata, requiremen
 export declare function buildRequirementMarkdown(node: RequirementNode): string;
 /**
  * Build a complete requirements file from metadata and raw markdown content.
- * Used by CLI pull to combine frontmatter with cloud-sourced markdown.
+ *
+ * Builds frontmatter from the recognized subset only, so it is for composing a
+ * file from scratch — NOT for rewriting one that exists. Rewriting through here
+ * drops the fields, comments and formatting its author added; sync rewrites go
+ * through `writeRequirementsFile`, which edits the file's own frontmatter
+ * (DOC-HEADER-14).
  *
  * SYNC-ARCH-1: markdownContent is the source of truth from the cloud.
  */

package/dist/schema/builder.js

@@ -96,7 +96,12 @@ export function buildRequirementMarkdown(node) {
 }
 /**
  * Build a complete requirements file from metadata and raw markdown content.
- * Used by CLI pull to combine frontmatter with cloud-sourced markdown.
+ *
+ * Builds frontmatter from the recognized subset only, so it is for composing a
+ * file from scratch — NOT for rewriting one that exists. Rewriting through here
+ * drops the fields, comments and formatting its author added; sync rewrites go
+ * through `writeRequirementsFile`, which edits the file's own frontmatter
+ * (DOC-HEADER-14).
  *
  * SYNC-ARCH-1: markdownContent is the source of truth from the cloud.
  */

package/dist/schema/conversions.js

@@ -1,7 +1,7 @@
 /**
  * Convert between Convex flat representation and hierarchical RequirementNode trees.
  */
-import { REQUIREMENT_KEY_PATTERN, } from "./schemas.js";
+import { canonicalRequirementKey, REQUIREMENT_KEY_PATTERN, } from "./schemas.js";
 /**
  * Construct a requirement key from prefix and index.
  * E.g., ("REQ", 123) -> "REQ-123"
@@ -140,8 +140,17 @@ function flattenNode(node, projectId, rootId, position, result, documentId) {
         index = node.metadata.index;
     }
     else {
-        // Parse from node.id (e.g., "REQ-123" -> { prefix: "REQ", index: 123 })
-        const parsed = parseKey(node.id);
+        // Parse from node.id (e.g., "REQ-123" -> { prefix: "REQ", index: 123 }).
+        // Only a root's id is a key, so only a root's id is normalized, so authored
+        // case and leading zeros reach the cloud canonically (SYNC-KEY-1.3). A
+        // child's id is a position path ("REQ-123.0"), which is not a key.
+        //
+        // Normalize without validating: this is exported API handed trees from
+        // YAML-era files and cloud rows, so an id that cannot be canonicalized must
+        // degrade to the prefix=node.id path below, not throw.
+        const parsed = isRoot
+            ? parseKey(canonicalRequirementKey(node.id))
+            : parseKey(node.id);
         if (parsed) {
             prefix = parsed.prefix;
             index = parsed.index;

package/dist/schema/file-writer.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The one place a sync replaces the bytes of a `.requirements.md` file.
+ * (codebase-to-spec authors files of its own; it does not write through here.)
+ *
+ * Both sync directions write through this, so the frontmatter a user authored
+ * survives whichever side won the reconciliation (DOC-HEADER-14). The write
+ * edits the file's own frontmatter in place and overwrites only the fields sync
+ * owns — which is why this takes an `OwnedFrontmatter` and not a `Metadata`.
+ * `Metadata` means "the recognized subset", so building one to write is
+ * silently the act of discarding everything else.
+ */
+/**
+ * What this write does to the file's `defaultPrefix`.
+ *
+ * A cloud document with no prefix is not self-interpreting, so the caller says
+ * which reading applies rather than passing an absent value and letting the
+ * write guess: under an additive sync the cloud has no prefix to impose
+ * (DOC-HEADER-11.6), while under `--cloud-wins` the cloud is the authority and
+ * its silence is the answer (DOC-HEADER-11.7).
+ */
+export type PrefixDirective = 
+/** The cloud has a prefix; the file takes it. */
+{
+    set: string;
+}
+/** Leave whatever the file says — the prefix is Jaime's until the cloud has one. */
+ | "keep"
+/** Remove it — the authoritative side has no prefix. */
+ | "clear";
+/**
+ * The frontmatter fields sync owns and rewrites on every write
+ * (DOC-HEADER-14.1). `pulledAt` is owned too but never passed: it always
+ * records this write (SYNC-WRITE-1.1).
+ */
+export interface OwnedFrontmatter {
+    /** The cloud document this file is linked to. */
+    documentId: string;
+    /** Editor hint for new requirement keys — see PrefixDirective. */
+    defaultPrefix: PrefixDirective;
+    /** The cloud version this content is at. */
+    version: number;
+}
+/**
+ * Write `body` to `filePath` under the file's own frontmatter, with the owned
+ * fields updated. Returns true when the bytes actually changed — sync only
+ * touches files whose content changed (SYNC-WRITE-1.0).
+ */
+export declare function writeRequirementsFile(filePath: string, owned: OwnedFrontmatter, body: string): boolean;
+//# sourceMappingURL=file-writer.d.ts.map

package/dist/schema/file-writer.js

@@ -0,0 +1,138 @@
+/**
+ * The one place a sync replaces the bytes of a `.requirements.md` file.
+ * (codebase-to-spec authors files of its own; it does not write through here.)
+ *
+ * Both sync directions write through this, so the frontmatter a user authored
+ * survives whichever side won the reconciliation (DOC-HEADER-14). The write
+ * edits the file's own frontmatter in place and overwrites only the fields sync
+ * owns — which is why this takes an `OwnedFrontmatter` and not a `Metadata`.
+ * `Metadata` means "the recognized subset", so building one to write is
+ * silently the act of discarding everything else.
+ */
+import * as fs from "node:fs";
+import YAML from "yaml";
+import { extractFrontmatterBlock } from "./parser-core.js";
+/**
+ * `lineWidth`/`minContentWidth`: never fold a long value onto continuation
+ * lines. `flowCollectionPadding`: re-render `tags: [auth, login]` as written,
+ * rather than respacing the author's line to `[ auth, login ]`.
+ */
+const RENDER_OPTIONS = {
+    lineWidth: 0,
+    minContentWidth: 0,
+    flowCollectionPadding: false,
+};
+/**
+ * Write `body` to `filePath` under the file's own frontmatter, with the owned
+ * fields updated. Returns true when the bytes actually changed — sync only
+ * touches files whose content changed (SYNC-WRITE-1.0).
+ */
+export function writeRequirementsFile(filePath, owned, body) {
+    const current = fs.existsSync(filePath)
+        ? fs.readFileSync(filePath, "utf-8")
+        : undefined;
+    const frontmatter = readFrontmatter(current);
+    // On a file being created there is nothing to compare against, so stamp it
+    // now and let `pulledAt` lead the frontmatter as it does everywhere else.
+    if (current === undefined)
+        frontmatter.setIn(["pulledAt"], nowStamp());
+    frontmatter.setIn(["version"], owned.version);
+    ensureDocumentMap(frontmatter);
+    frontmatter.setIn(["document", "id"], owned.documentId);
+    if (owned.defaultPrefix === "clear")
+        frontmatter.deleteIn(["document", "defaultPrefix"]);
+    else if (owned.defaultPrefix !== "keep")
+        frontmatter.setIn(["document", "defaultPrefix"], owned.defaultPrefix.set);
+    // SYNC-TITLE-1.2: `document.title` is a recognized-but-retired field — the
+    // title lives in the body as its leading H1 — so a rewrite drops it rather
+    // than carrying it forward as if it were one of the user's own fields.
+    frontmatter.deleteIn(["document", "title"]);
+    // SYNC-WRITE-1.0: render with the file's OWN `pulledAt` still in place. If
+    // that already matches the file, the only thing this write would change is
+    // the stamp — and `pulledAt` records when content arrived, not when a sync
+    // ran (SYNC-WRITE-1.1) — so leave the file alone.
+    //
+    // Comparing two rendered files, rather than patching the stamp out of the
+    // text, is what makes this hold for any style the author used: a flow-style
+    // mapping (`{owner: alice, document: {...}}`) puts every key on one line, so
+    // a line-anchored "ignore the pulledAt line" match finds nothing and every
+    // sync rewrites the file.
+    const unstamped = compose(frontmatter, body);
+    // CRLF-normalize the comparison only: a Windows-authored file that hasn't
+    // changed keeps its line endings rather than being converted on sight.
+    if (current !== undefined && current.replace(/\r\n/g, "\n") === unstamped)
+        return false;
+    if (current !== undefined)
+        frontmatter.setIn(["pulledAt"], nowStamp());
+    fs.writeFileSync(filePath, compose(frontmatter, body), "utf-8");
+    return true;
+}
+const nowStamp = () => new Date().toISOString();
+function compose(frontmatter, body) {
+    return `---\n${frontmatter.toString(RENDER_OPTIONS).trim()}\n---\n\n${body.trim()}\n`;
+}
+/**
+ * Guarantee `document:` is a mapping this write can set `id` on.
+ *
+ * A YAML alias (`document: *defaults`) parses as a valid, normally linked
+ * document — but editing *through* the alias would rewrite whatever its anchor
+ * is shared with, and a scalar or sequence cannot hold an id at all. Replace
+ * the node with a concrete mapping, seeded from the alias's target so nothing
+ * it carried is lost.
+ */
+function ensureDocumentMap(frontmatter) {
+    const existing = frontmatter.getIn(["document"], true);
+    if (existing === undefined || YAML.isMap(existing))
+        return;
+    const resolved = YAML.isAlias(existing)
+        ? existing.resolve(frontmatter)
+        : undefined;
+    // `toJS(doc)`, NOT `toJSON()`: only the former resolves aliases nested INSIDE
+    // the target. `base: &base {owner: *n}` seeded via toJSON turns the author's
+    // `owner: alice` into `{source: "n"}` — silent, permanent loss of a field,
+    // and the write after it no-ops so the corruption becomes the stable state.
+    const seed = YAML.isMap(resolved) ? resolved.toJS(frontmatter) : {};
+    const replacement = frontmatter.createNode(seed);
+    // Carry any anchor the replaced node held. `document: &d hello` with a
+    // sibling `audit: *d` would otherwise leave that alias unresolvable and
+    // every render of the file would throw — a file that could never be written
+    // again. `*d` now resolves to the repaired mapping instead of the old
+    // scalar: the alias's value changes, which is the lesser loss.
+    const anchor = YAML.isScalar(existing) || YAML.isCollection(existing)
+        ? existing.anchor
+        : undefined;
+    if (anchor && YAML.isCollection(replacement))
+        replacement.anchor = anchor;
+    frontmatter.setIn(["document"], replacement);
+}
+/**
+ * The file's frontmatter as the user wrote it — unrecognized keys, comments and
+ * flow style included (DOC-HEADER-14.0). Editing this document in place, rather
+ * than rebuilding one from a parsed object, is what lets `owner: alice # rota`
+ * come back with its comment attached.
+ *
+ * Frontmatter that isn't a YAML mapping yields an empty document: the file is
+ * unparseable as a requirements file anyway, and rewriting it is the repair.
+ * A mapping whose `document:` key holds something unusable is repaired in
+ * place instead — see `ensureDocumentMap`.
+ */
+function readFrontmatter(current) {
+    const empty = () => new YAML.Document({});
+    if (current === undefined)
+        return empty();
+    const yaml = extractFrontmatterBlock(current);
+    if (yaml === undefined)
+        return empty();
+    try {
+        // `uniqueKeys: false`: a repeated key (`owner: alice` / `owner: bob`) is
+        // an error by default, which would send this file down the empty-document
+        // path and delete every field its author wrote. Duplicates are the
+        // author's to resolve; losing both is not a repair.
+        const doc = YAML.parseDocument(yaml, { uniqueKeys: false });
+        return doc.errors.length === 0 && YAML.isMap(doc.contents) ? doc : empty();
+    }
+    catch {
+        return empty();
+    }
+}
+//# sourceMappingURL=file-writer.js.map

package/dist/schema/index.d.ts

@@ -7,11 +7,14 @@
 export { buildRequirementMarkdown, buildRequirementsFile, buildRequirementsMarkdown, } from "./builder.js";
 export type { ConvexRequirement } from "./conversions.js";
 export { buildMetadata, constructKey, convexToRequirements, extractRequirementKeys, groupByRoot, parseKey, requirementsToConvex, } from "./conversions.js";
-export { findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRequirementsFile, parseRequirementsFromFile, parseRootLine, } from "./parser.js";
+export type { OwnedFrontmatter, PrefixDirective } from "./file-writer.js";
+export { writeRequirementsFile } from "./file-writer.js";
+export type { ExtractedRequirementBlock } from "./parser.js";
+export { findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRequirementsFile, parseRequirementsFromFile, parseRootLine, splitRequirementFenceContent, } from "./parser.js";
 export { checkPathAmbiguity, findChildrenByLabel, getAllLabelPaths, parsePathSegment, parseRequirementPath, resolvePathSegment, resolveRequirementPath, resolveToNumericPath, } from "./resolver.js";
 export type { BuildScenarioOptions, Scenario, ScenarioAssertionSource, ScenarioStep, } from "./scenario.js";
 export { buildScenarioFromRequirements, requirementTreeToScenario, } from "./scenario.js";
 export type { Metadata, ParsedCriterion, PushValidationResult, RequirementKey, RequirementNode, RequirementPrefix, RequirementsFile, } from "./schemas.js";
-export { buildRequirementKey, CONVEX_ID_PATTERN, MetadataSchema, normalizePrefix, ParsedCriterionSchema, parseRequirementKey, REQUIREMENT_KEY_PATTERN, REQUIREMENT_PREFIX_PATTERN, RequirementKeySchema, RequirementNodeSchema, RequirementPrefixSchema, RequirementsFileSchema, ValidationError, validateForPush, validateKey, validateMetadata, validatePrefix, validateRequirementNode, validateRequirementsFile, } from "./schemas.js";
+export { buildRequirementKey, CONVEX_ID_PATTERN, canonicalRequirementKey, MetadataSchema, normalizePrefix, ParsedCriterionSchema, parseRequirementKey, REQUIREMENT_KEY_PATTERN, REQUIREMENT_PREFIX_PATTERN, RequirementKeySchema, RequirementNodeSchema, RequirementPrefixSchema, RequirementsFileSchema, ValidationError, validateForPush, validateKey, validateMetadata, validatePrefix, validateRequirementNode, validateRequirementsFile, } from "./schemas.js";
 export { composeMarkdownWithTitle, type SplitMarkdown, splitLeadingH1, } from "./title-markdown.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/schema/index.js

@@ -7,14 +7,15 @@
 // Building
 export { buildRequirementMarkdown, buildRequirementsFile, buildRequirementsMarkdown, } from "./builder.js";
 export { buildMetadata, constructKey, convexToRequirements, extractRequirementKeys, groupByRoot, parseKey, requirementsToConvex, } from "./conversions.js";
+export { writeRequirementsFile } from "./file-writer.js";
 // Parsing
-export { findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRequirementsFile, parseRequirementsFromFile, parseRootLine, } from "./parser.js";
+export { findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRequirementsFile, parseRequirementsFromFile, parseRootLine, splitRequirementFenceContent, } from "./parser.js";
 // Path resolution
 export { checkPathAmbiguity, findChildrenByLabel, getAllLabelPaths, parsePathSegment, parseRequirementPath, resolvePathSegment, resolveRequirementPath, resolveToNumericPath, } from "./resolver.js";
 // Scenario building (for browser-automation / runScenario)
 export { buildScenarioFromRequirements, requirementTreeToScenario, } from "./scenario.js";
 // Schemas and types
-export { buildRequirementKey, CONVEX_ID_PATTERN, 
+export { buildRequirementKey, CONVEX_ID_PATTERN, canonicalRequirementKey, 
 // Zod schemas
 MetadataSchema, 
 // Prefix/key utilities

package/dist/schema/parser-core.d.ts

@@ -59,15 +59,42 @@ export declare function parseRootLine(line: string, delimiter?: string): {
  * First line is the requirement content (with optional arrow format).
  * Subsequent lines are criteria with position paths.
  */
-export declare function parseRequirementBlock(key: string, blockContent: string): RequirementNode;
+export declare function parseRequirementBlock(key: string, blockContent: string, 
 /**
- * Extract requirement blocks from Markdown body (no frontmatter).
- * Returns an array of { key, blockContent } for each dotrequirements block found.
+ * 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.
  */
-export declare function extractRequirementBlocks(body: string): Array<{
+lineOffset?: number): RequirementNode;
+export type ExtractedRequirementBlock = {
     key: string;
     blockContent: string;
-}>;
+    /** Zero-based line index of this root within its fence, for diagnostics. */
+    startLine: number;
+};
+/**
+ * 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 declare function splitRequirementFenceContent(content: string): ExtractedRequirementBlock[];
+/**
+ * Extract requirement blocks from Markdown body (no frontmatter).
+ * A fence may contain multiple adjacent root requirements; each root is
+ * returned as its own logical block.
+ */
+export declare function extractRequirementBlocks(body: string): ExtractedRequirementBlock[];
 /**
  * Split raw file content into its leading YAML frontmatter and body — both
  * derived from ONE fence match, so the two halves are complementary by