@popoverai/dotrequirements 0.26.0 → 0.26.2

package/dist/schema/conversions.d.ts

@@ -1,7 +1,7 @@
 /**
  * Convert between Convex flat representation and hierarchical RequirementNode trees.
  */
-import type { Metadata, RequirementNode } from "./schemas.js";
+import { type Metadata, type RequirementNode } from "./schemas.js";
 /**
  * Convex requirement type (flat structure with position paths).
  * This mirrors the Convex database schema.
@@ -31,7 +31,12 @@ export declare function constructKey(prefix: string, index: number): string;
 /**
  * Parse a requirement key into prefix and index.
  * E.g., "REQ-123" -> { prefix: "REQ", index: 123 }
- * Returns null if key doesn't match expected format.
+ * E.g., "SYNC-CLI-CREATE-1" -> { prefix: "SYNC-CLI-CREATE", index: 1 }
+ * Returns null if key doesn't match REQUIREMENT_KEY_PATTERN, which is the
+ * sole grammar authority here: the split below is mechanical. (Deliberately
+ * NOT delegated to parseRequirementKey — it case-normalizes and enforces a
+ * 30-char prefix cap this pattern doesn't, and pattern-passing keys must
+ * never fall back to the caller's prefix=node.id path.)
  */
 export declare function parseKey(key: string): {
     prefix: string;

package/dist/schema/conversions.js

@@ -1,6 +1,7 @@
 /**
  * Convert between Convex flat representation and hierarchical RequirementNode trees.
  */
+import { REQUIREMENT_KEY_PATTERN, } from "./schemas.js";
 /**
  * Construct a requirement key from prefix and index.
  * E.g., ("REQ", 123) -> "REQ-123"
@@ -11,13 +12,21 @@ export function constructKey(prefix, index) {
 /**
  * Parse a requirement key into prefix and index.
  * E.g., "REQ-123" -> { prefix: "REQ", index: 123 }
- * Returns null if key doesn't match expected format.
+ * E.g., "SYNC-CLI-CREATE-1" -> { prefix: "SYNC-CLI-CREATE", index: 1 }
+ * Returns null if key doesn't match REQUIREMENT_KEY_PATTERN, which is the
+ * sole grammar authority here: the split below is mechanical. (Deliberately
+ * NOT delegated to parseRequirementKey — it case-normalizes and enforces a
+ * 30-char prefix cap this pattern doesn't, and pattern-passing keys must
+ * never fall back to the caller's prefix=node.id path.)
  */
 export function parseKey(key) {
-    const match = key.match(/^([A-Z0-9_]+)-(\d+)$/);
-    if (!match)
+    if (!REQUIREMENT_KEY_PATTERN.test(key))
         return null;
-    return { prefix: match[1], index: parseInt(match[2], 10) };
+    const splitAt = key.lastIndexOf("-");
+    return {
+        prefix: key.slice(0, splitAt),
+        index: parseInt(key.slice(splitAt + 1), 10),
+    };
 }
 /**
  * Build a hierarchical tree from flat Convex requirements.

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

@@ -40,6 +40,34 @@ export declare function extractRequirementBlocks(body: string): Array<{
     key: string;
     blockContent: string;
 }>;
+/**
+ * Split raw file content into its leading YAML frontmatter and body — both
+ * derived from ONE fence match, so the two halves are complementary by
+ * construction and can never disagree about where the fence closes.
+ *
+ * Normalizes CRLF first (SYNC-FORMAT-1): frontmatter isolation must accept
+ * the same line-ending styles the parser does. Callers must use this (or the
+ * wrappers below) instead of hand-rolled regexes so every consumer agrees on
+ * what "has frontmatter" means.
+ *
+ * Returns undefined when the content has no leading frontmatter fence.
+ */
+export declare function splitFrontmatter(content: string): {
+    yaml: string;
+    body: string;
+} | undefined;
+/**
+ * The frontmatter half of splitFrontmatter: the inner YAML text, or
+ * undefined when the file has no leading fence.
+ */
+export declare function extractFrontmatterBlock(content: string): string | undefined;
+/**
+ * The body half of splitFrontmatter: the (CRLF-normalized) content with the
+ * leading frontmatter fence removed, or the whole normalized content when
+ * there is no fence. Blank lines directly after the fence are consumed so
+ * the body starts at its first real line.
+ */
+export declare function stripFrontmatterBlock(content: string): string;
 /**
  * Parse requirement blocks from markdown content (without frontmatter).
  * Use this for web editor content that doesn't have YAML frontmatter.

package/dist/schema/parser-core.js

@@ -95,30 +95,48 @@ export function parseRequirementBlock(key, blockContent) {
         }
         const criterion = parseCriterionLine(line);
         if (!criterion) {
-            // Check if this looks like another requirement key (KEY: content format)
+            // 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 (/^[\w-]+:\s*.+/.test(trimmedLine)) {
+            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);
             }
             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);
         }
+        // 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);
+        }
         criteriaByPosition.set(criterion.position, criterion);
     }
     // Build tree from flat position paths
-    buildTreeFromPositions(root, key, criteriaByPosition);
+    const consumed = new Set();
+    buildTreeFromPositions(root, key, criteriaByPosition, consumed);
+    // SYNC-FORMAT-2.2: any criterion not attached to the tree references a
+    // missing parent position — reject it instead of silently dropping it.
+    for (const position of criteriaByPosition.keys()) {
+        if (!consumed.has(position)) {
+            const parentPosition = position.split(".").slice(0, -1).join(".");
+            throw new ValidationError(`Orphaned criterion position "${position}" — parent position "${parentPosition}" does not exist`, key);
+        }
+    }
     return root;
 }
 /**
  * Build a tree structure from flat position paths.
  * Positions like "0", "1", "1.0", "1.1", "1.1.0" define the hierarchy.
  */
-function buildTreeFromPositions(root, rootKey, criteriaByPosition) {
+function buildTreeFromPositions(root, rootKey, criteriaByPosition, consumed) {
     // Get all top-level children (single digit positions: "0", "1", "2")
     const topLevelPositions = Array.from(criteriaByPosition.keys())
         .filter((pos) => !pos.includes("."))
         .sort((a, b) => parseInt(a, 10) - parseInt(b, 10));
     for (const position of topLevelPositions) {
         const criterion = criteriaByPosition.get(position);
+        consumed.add(position);
         const childNode = {
             id: `${rootKey}.${position}`,
             label: criterion.label,
@@ -126,14 +144,14 @@ function buildTreeFromPositions(root, rootKey, criteriaByPosition) {
             children: [],
         };
         // Recursively build children
-        buildChildrenFromPositions(childNode, position, rootKey, criteriaByPosition);
+        buildChildrenFromPositions(childNode, position, rootKey, criteriaByPosition, consumed);
         root.children.push(childNode);
     }
 }
 /**
  * Recursively build children for a given position.
  */
-function buildChildrenFromPositions(parent, parentPosition, rootKey, criteriaByPosition) {
+function buildChildrenFromPositions(parent, parentPosition, rootKey, criteriaByPosition, consumed) {
     // Find direct children (e.g., if parent is "1", find "1.0", "1.1", etc.)
     const childPositions = Array.from(criteriaByPosition.keys())
         .filter((pos) => {
@@ -158,6 +176,7 @@ function buildChildrenFromPositions(parent, parentPosition, rootKey, criteriaByP
     });
     for (const position of childPositions) {
         const criterion = criteriaByPosition.get(position);
+        consumed.add(position);
         const childNode = {
             id: `${rootKey}.${position}`,
             label: criterion.label,
@@ -165,7 +184,7 @@ function buildChildrenFromPositions(parent, parentPosition, rootKey, criteriaByP
             children: [],
         };
         // Recursively build grandchildren
-        buildChildrenFromPositions(childNode, position, rootKey, criteriaByPosition);
+        buildChildrenFromPositions(childNode, position, rootKey, criteriaByPosition, consumed);
         parent.children.push(childNode);
     }
 }
@@ -175,6 +194,7 @@ function buildChildrenFromPositions(parent, parentPosition, rootKey, criteriaByP
  */
 export function extractRequirementBlocks(body) {
     const blocks = [];
+    const seenKeys = new Set();
     // Find all ```dotrequirements code blocks
     const blockRegex = /```dotrequirements\n([\s\S]*?)```/gm;
     let match = blockRegex.exec(body);
@@ -190,17 +210,65 @@ export function extractRequirementBlocks(body) {
         // 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);
+        }
+        seenKeys.add(key);
         blocks.push({ key, blockContent: blockContent.trim() });
         match = blockRegex.exec(body);
     }
     return blocks;
 }
+/**
+ * Split raw file content into its leading YAML frontmatter and body — both
+ * derived from ONE fence match, so the two halves are complementary by
+ * construction and can never disagree about where the fence closes.
+ *
+ * Normalizes CRLF first (SYNC-FORMAT-1): frontmatter isolation must accept
+ * the same line-ending styles the parser does. Callers must use this (or the
+ * wrappers below) instead of hand-rolled regexes so every consumer agrees on
+ * what "has frontmatter" means.
+ *
+ * Returns undefined when the content has no leading frontmatter fence.
+ */
+export function splitFrontmatter(content) {
+    const normalized = content.replace(/\r\n/g, "\n");
+    const match = normalized.match(/^---\n([\s\S]*?)\n---(?:\n|$)/);
+    if (!match) {
+        return undefined;
+    }
+    return { yaml: match[1], body: normalized.slice(match[0].length) };
+}
+/**
+ * The frontmatter half of splitFrontmatter: the inner YAML text, or
+ * undefined when the file has no leading fence.
+ */
+export function extractFrontmatterBlock(content) {
+    return splitFrontmatter(content)?.yaml;
+}
+/**
+ * The body half of splitFrontmatter: the (CRLF-normalized) content with the
+ * leading frontmatter fence removed, or the whole normalized content when
+ * there is no fence. Blank lines directly after the fence are consumed so
+ * the body starts at its first real line.
+ */
+export function stripFrontmatterBlock(content) {
+    const split = splitFrontmatter(content);
+    if (split === undefined) {
+        return content.replace(/\r\n/g, "\n");
+    }
+    return split.body.replace(/^\n+/, "");
+}
 /**
  * Parse requirement blocks from markdown content (without frontmatter).
  * Use this for web editor content that doesn't have YAML frontmatter.
  */
 export function parseRequirementBlocksFromMarkdown(markdownContent) {
-    const blocks = extractRequirementBlocks(markdownContent);
+    // SYNC-FORMAT-1: normalize Windows (CRLF) line endings so content parses
+    // identically regardless of line-ending style.
+    const blocks = extractRequirementBlocks(markdownContent.replace(/\r\n/g, "\n"));
     const requirements = [];
     for (const { key, blockContent } of blocks) {
         try {
@@ -208,7 +276,10 @@ export function parseRequirementBlocksFromMarkdown(markdownContent) {
             requirements.push(reqNode);
         }
         catch (error) {
-            throw new ValidationError(`Failed to parse requirement ${key}`, key, error);
+            // Include the inner message so structural errors (duplicate position,
+            // orphaned position, ...) stay identifiable at the top level.
+            const detail = error instanceof Error && error.message ? `: ${error.message}` : "";
+            throw new ValidationError(`Failed to parse requirement ${key}${detail}`, key, error);
         }
     }
     return requirements;

package/dist/schema/parser.d.ts

@@ -1,19 +1,14 @@
 /**
  * Parse Markdown requirements files into typed structures.
+ *
+ * File-level concerns only: frontmatter isolation, metadata validation, and
+ * disk IO. All block and criterion parsing delegates to the
+ * environment-agnostic parser-core module, which the web editor and Convex
+ * also consume — one parser, so the CLI and the cloud cannot drift on what a
+ * requirements file means (SYNC-FORMAT-2.3).
  */
-import { type ParsedCriterion, type RequirementNode, type RequirementsFile } from "./schemas.js";
-/**
- * Parse a criterion line in "position. Label → content" format.
- * Example: "0. Given → user has valid credentials"
- * Also supports optional label: "0. → user has valid credentials"
- */
-export declare function parseCriterionLine(line: string, delimiter?: string): ParsedCriterion | null;
-/**
- * Parse a dotrequirements fenced block into a RequirementNode tree.
- * 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;
+import { type RequirementNode, type RequirementsFile } from "./schemas.js";
+export { findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, } from "./parser-core.js";
 /**
  * Parse a complete requirements Markdown file.
  */
@@ -28,17 +23,4 @@ export declare function parseRequirementsFromFile(filePath: string): {
     metadata: RequirementsFile["_meta"];
     requirements: RequirementNode[];
 };
-/**
- * Flatten a requirement tree into a list of all nodes.
- * Useful for searching or displaying all requirements.
- */
-export declare function flattenRequirementTree(node: RequirementNode): RequirementNode[];
-/**
- * Find a requirement by its ID in a tree.
- */
-export declare function findRequirementById(nodes: RequirementNode[], id: string): RequirementNode | undefined;
-/**
- * Get all requirements from multiple files as a flat list.
- */
-export declare function getAllRequirements(requirements: RequirementNode[]): RequirementNode[];
 //# sourceMappingURL=parser.d.ts.map

package/dist/schema/parser.js

@@ -1,245 +1,53 @@
 /**
  * Parse Markdown requirements files into typed structures.
+ *
+ * File-level concerns only: frontmatter isolation, metadata validation, and
+ * disk IO. All block and criterion parsing delegates to the
+ * environment-agnostic parser-core module, which the web editor and Convex
+ * also consume — one parser, so the CLI and the cloud cannot drift on what a
+ * requirements file means (SYNC-FORMAT-2.3).
  */
 import * as fs from "node:fs";
 import YAML from "yaml";
-import { ValidationError, validateKey, validateMetadata, } from "./schemas.js";
-const DELIMITER_PATTERN = "(?:→|->)"; // Non-capturing group for both Unicode and ASCII
-/**
- * Parse a criterion line in "position. Label → content" format.
- * Example: "0. Given → user has valid credentials"
- * Also supports optional label: "0. → user has valid credentials"
- */
-export function parseCriterionLine(line, delimiter = DELIMITER_PATTERN) {
-    // Match: position + period + space + optional(label + space) + delimiter + space + content
-    // Position can be: 0, 1.0, 2.3.1, etc.
-    // Label can contain any characters except the delimiter
-    const pattern = new RegExp(`^\\s*(\\d+(?:\\.\\d+)*)\\.\\s*(?:(.+?)\\s+)?${delimiter}\\s*(.+)$`);
-    const match = line.match(pattern);
-    if (!match) {
-        return null;
-    }
-    return {
-        position: match[1],
-        label: match[2] ? match[2].trim() : "", // Preserve original case, empty if no label
-        content: match[3].trim(),
-    };
-}
-/**
- * Parse the first line of a dotrequirements block (the root requirement).
- * Format: "KEY: content" or "Label → content" or "→ content"
- */
-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*(.+)$/);
-    if (keyMatch) {
-        return {
-            label: "", // Keys use empty string for unlabeled requirements
-            content: keyMatch[2].trim(),
-        };
-    }
-    // Match: optional(label + space) + delimiter + space + content
-    const pattern = new RegExp(`^(?:(.+?)\\s+)?${delimiter}\\s*(.+)$`);
-    const match = trimmed.match(pattern);
-    if (!match) {
-        // If no delimiter found, treat entire line as content with empty label
-        return {
-            label: "",
-            content: trimmed,
-        };
-    }
-    return {
-        label: match[1] ? match[1].trim() : "",
-        content: match[2].trim(),
-    };
-}
-/**
- * Parse a dotrequirements fenced block into a RequirementNode tree.
- * First line is the requirement content (with optional arrow format).
- * Subsequent lines are criteria with position paths.
- */
-export function parseRequirementBlock(key, blockContent) {
-    const lines = blockContent.trim().split("\n");
-    if (lines.length === 0) {
-        throw new ValidationError("Empty requirement block", key);
-    }
-    // First line is the requirement content
-    const rootParsed = parseRootLine(lines[0]);
-    if (!rootParsed.content) {
-        throw new ValidationError("Requirement content (first line) cannot be empty", key);
-    }
-    const root = {
-        id: key,
-        // Root requirements always use "requirementHeader" label for indexing/querying
-        // The markdown format doesn't preserve root labels, but we standardize on this value
-        label: "requirementHeader",
-        content: rootParsed.content,
-        children: [],
-    };
-    // Parse criteria lines
-    const criteriaByPosition = new Map();
-    for (let i = 1; i < lines.length; i++) {
-        const line = lines[i];
-        // Skip empty lines and comments
-        if (!line.trim() || line.trim().startsWith("#")) {
-            continue;
-        }
-        const criterion = parseCriterionLine(line);
-        if (!criterion) {
-            throw new ValidationError(`Invalid criterion format at line ${i + 1}: "${line.trim()}"`, key);
-        }
-        criteriaByPosition.set(criterion.position, criterion);
-    }
-    // Build tree from flat position paths
-    buildTreeFromPositions(root, key, criteriaByPosition);
-    return root;
-}
-/**
- * Build a tree structure from flat position paths.
- * Positions like "0", "1", "1.0", "1.1", "1.1.0" define the hierarchy.
- */
-function buildTreeFromPositions(root, rootKey, criteriaByPosition) {
-    // Get all top-level children (single digit positions: "0", "1", "2")
-    const topLevelPositions = Array.from(criteriaByPosition.keys())
-        .filter((pos) => !pos.includes("."))
-        .sort((a, b) => parseInt(a, 10) - parseInt(b, 10));
-    for (const position of topLevelPositions) {
-        const criterion = criteriaByPosition.get(position);
-        const childNode = {
-            id: `${rootKey}.${position}`,
-            label: criterion.label,
-            content: criterion.content,
-            children: [],
-        };
-        // Recursively build children
-        buildChildrenFromPositions(childNode, position, rootKey, criteriaByPosition);
-        root.children.push(childNode);
-    }
-}
-/**
- * Recursively build children for a given position.
- */
-function buildChildrenFromPositions(parent, parentPosition, rootKey, criteriaByPosition) {
-    // Find direct children (e.g., if parent is "1", find "1.0", "1.1", etc.)
-    const childPositions = Array.from(criteriaByPosition.keys())
-        .filter((pos) => {
-        const parts = pos.split(".");
-        const parentParts = parentPosition.split(".");
-        // Must be exactly one level deeper
-        if (parts.length !== parentParts.length + 1) {
-            return false;
-        }
-        // All parent parts must match
-        for (let i = 0; i < parentParts.length; i++) {
-            if (parts[i] !== parentParts[i]) {
-                return false;
-            }
-        }
-        return true;
-    })
-        .sort((a, b) => {
-        const aLast = parseInt(a.split(".").pop(), 10);
-        const bLast = parseInt(b.split(".").pop(), 10);
-        return aLast - bLast;
-    });
-    for (const position of childPositions) {
-        const criterion = criteriaByPosition.get(position);
-        const childNode = {
-            id: `${rootKey}.${position}`,
-            label: criterion.label,
-            content: criterion.content,
-            children: [],
-        };
-        // Recursively build grandchildren
-        buildChildrenFromPositions(childNode, position, rootKey, criteriaByPosition);
-        parent.children.push(childNode);
-    }
-}
+import { parseRequirementBlocksFromMarkdown, splitFrontmatter, } from "./parser-core.js";
+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, } from "./parser-core.js";
 /**
  * Extract YAML frontmatter from Markdown content.
  * Returns { frontmatter, body } where frontmatter is the parsed YAML object.
  */
 function extractFrontmatter(content) {
-    // Match YAML frontmatter: ---\n...\n---
-    const frontmatterRegex = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/;
-    const match = content.match(frontmatterRegex);
-    if (!match) {
+    // Single fence match: yaml and body come from the same split, so they can
+    // never disagree about where the frontmatter closes.
+    const split = splitFrontmatter(content);
+    if (split === undefined) {
         throw new ValidationError("Missing YAML frontmatter (should start with ---)");
     }
-    const [, frontmatterYaml, body] = match;
     let frontmatter;
     try {
-        frontmatter = YAML.parse(frontmatterYaml);
+        frontmatter = YAML.parse(split.yaml);
     }
     catch (error) {
         throw new ValidationError("Failed to parse YAML frontmatter", undefined, error);
     }
-    return { frontmatter, body: body.trim() };
-}
-/**
- * Extract requirement blocks from Markdown body.
- * Returns a map of requirement key -> { title, blockContent }
- *
- * The KEY is extracted from the first line inside the code block.
- * Headings are optional and only used for human readability.
- */
-function extractRequirementBlocks(body) {
-    const blocks = new Map();
-    // Find all ```dotrequirements code blocks
-    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);
-        // Try to find a heading immediately before this block for the title
-        // Look backwards from the match position to find the nearest heading
-        const textBeforeBlock = body.substring(0, match.index);
-        const headingMatch = textBeforeBlock.match(/^#{2,6}\s+([^\n]+)\s*$/m);
-        const title = headingMatch ? headingMatch[1].trim() : key;
-        blocks.set(key, { title, blockContent: blockContent.trim() });
-        match = blockRegex.exec(body);
-    }
-    return blocks;
+    return { frontmatter, body: split.body.trim() };
 }
 /**
  * Parse a complete requirements Markdown file.
  */
 export function parseRequirementsFile(markdownContent) {
-    // Extract frontmatter and body
+    // CRLF normalization (SYNC-FORMAT-1) happens inside the shared parser-core
+    // helpers (splitFrontmatter / parseRequirementBlocksFromMarkdown), so every
+    // entry point agrees.
     const { frontmatter, body } = extractFrontmatter(markdownContent);
-    // Validate metadata from frontmatter
     const metadata = validateMetadata(frontmatter);
-    // Extract requirement blocks
-    const blocks = extractRequirementBlocks(body);
-    if (blocks.size === 0) {
+    const requirements = parseRequirementBlocksFromMarkdown(body);
+    if (requirements.length === 0) {
         throw new ValidationError("No requirement blocks found in document");
     }
-    // Parse each requirement block
-    const requirements = [];
-    for (const [key, { blockContent }] of blocks) {
-        try {
-            const reqNode = parseRequirementBlock(key, blockContent);
-            requirements.push(reqNode);
-        }
-        catch (error) {
-            throw new ValidationError(`Failed to parse requirement ${key}`, key, error);
-        }
-    }
-    return {
-        metadata,
-        requirements,
-    };
+    return { metadata, requirements };
 }
 /**
  * Parse requirements file from disk.
@@ -256,40 +64,4 @@ export function parseRequirementsFromFile(filePath) {
         throw new ValidationError(`Failed to read file: ${filePath}`, undefined, error);
     }
 }
-/**
- * Flatten a requirement tree into a list of all nodes.
- * Useful for searching or displaying all requirements.
- */
-export function flattenRequirementTree(node) {
-    const result = [node];
-    for (const child of node.children) {
-        result.push(...flattenRequirementTree(child));
-    }
-    return result;
-}
-/**
- * Find a requirement by its ID in a tree.
- */
-export function findRequirementById(nodes, id) {
-    for (const node of nodes) {
-        if (node.id === id) {
-            return node;
-        }
-        const found = findRequirementById(node.children, id);
-        if (found) {
-            return found;
-        }
-    }
-    return undefined;
-}
-/**
- * Get all requirements from multiple files as a flat list.
- */
-export function getAllRequirements(requirements) {
-    const all = [];
-    for (const req of requirements) {
-        all.push(...flattenRequirementTree(req));
-    }
-    return all;
-}
 //# sourceMappingURL=parser.js.map

package/dist/schema/resolver.js

@@ -16,7 +16,9 @@ export function parseRequirementPath(path) {
  * E.g., "given#2" → { label: "given", index: 2 }
  */
 export function parsePathSegment(segment) {
-    const match = segment.match(/^(\w+)(?:#(\d+))?$/);
+    // HARNESS-RESOLVE-2.0: multi-word labels are addressed by their kebab-case
+    // form (e.g. "Edge Case" → "edge-case"), so segments may contain hyphens.
+    const match = segment.match(/^([\w-]+)(?:#(\d+))?$/);
     if (!match) {
         throw new Error(`Invalid path segment: ${segment}`);
     }
@@ -47,10 +49,18 @@ export function findChildrenByLabel(node, label) {
  * Returns the child node and its numeric index.
  */
 export function resolvePathSegment(node, segment) {
-    // Check if segment is numeric (direct index)
+    // Check if segment is numeric (written position)
+    // HARNESS-RESOLVE-1: a numeric segment means the position written in the
+    // file, not the array index. Node ids preserve written positions (which may
+    // have gaps), so match the child whose id's last position segment equals
+    // the requested position. When no child was written at that position,
+    // resolution fails rather than binding to a neighboring criterion.
     if (/^\d+$/.test(segment)) {
-        const index = parseInt(segment, 10);
-        if (index < node.children.length) {
+        const index = node.children.findIndex((child) => {
+            const lastDot = child.id.lastIndexOf(".");
+            return child.id.slice(lastDot + 1) === segment;
+        });
+        if (index !== -1) {
             return {
                 child: node.children[index],
                 index,
@@ -158,13 +168,13 @@ export function checkPathAmbiguity(requirements, path) {
     // Check each segment for ambiguity
     for (let i = 1; i < segments.length; i++) {
         const segment = segments[i];
-        // Numeric segments are never ambiguous
+        // Numeric segments are never ambiguous (resolved by written position)
         if (/^\d+$/.test(segment)) {
-            const index = parseInt(segment, 10);
-            if (index >= currentNode.children.length) {
+            const resolved = resolvePathSegment(currentNode, segment);
+            if (!resolved) {
                 return 0; // Invalid path
             }
-            currentNode = currentNode.children[index];
+            currentNode = resolved.child;
             continue;
         }
         // Check for label disambiguation (#N)