@popoverai/dotrequirements 0.29.3 → 0.30.0

package/dist/commands/sync.js

@@ -7,7 +7,7 @@
 import * as path from "node:path";
 import * as readline from "node:readline";
 import { executePlan } from "../sync/execute.js";
-import { acquireCloudSnapshot, acquireLocalSnapshot, compareSnapshots, duplicateLocalDocumentIds, filterByScope, resolutionHint, } from "../sync/index.js";
+import { acquireCloudSnapshot, acquireLocalSnapshot, compareSnapshots, duplicateIdAbortMessage, filterByScope, resolutionHint, } from "../sync/index.js";
 import { buildPlan, resolveMode, } from "../sync/plan.js";
 import { brand } from "../utils/brand.js";
 import { resolveCloudAuth } from "./sync-common.js";
@@ -60,13 +60,11 @@ export async function syncCommand(scope, options) {
         console.log(`Project: "${cloud.projectName}"`);
     }
     // SYNC-FAIL-3: two files claiming one document id would both write it — abort
-    // before any write, naming both files and the shared id.
-    const dupes = duplicateLocalDocumentIds(local);
-    if (dupes.length > 0) {
-        const d = dupes[0];
-        throw new Error(`Two files claim the same document ID "${d.documentId}":\n` +
-            d.filePaths.map((p) => `  ${p}`).join("\n") +
-            `\nEach file must map to its own cloud document. Remove the "id:" line from the copy's frontmatter, then sync again.`);
+    // before any write, naming both files and the shared id, plus any invalid
+    // files (SYNC-FAIL-3.2) so one run reports every problem.
+    const abortMessage = duplicateIdAbortMessage(local);
+    if (abortMessage) {
+        throw new Error(abortMessage);
     }
     const comparison = compareSnapshots(local, cloud);
     const { documents, unmatched } = filterByScope(comparison, scope, workspaceRoot);
@@ -134,6 +132,22 @@ export async function syncCommand(scope, options) {
             console.log(`  ⚠ ${name}: this file's import marker was not recognized — your CLI may need updating. Its requirements were saved as natively authored (they count toward your plan's requirement limit).`);
         }
     }
+    // The publish landed but something after it did not. The server's own words,
+    // because it knows what was left undone and whether it repairs itself.
+    for (const { name, warning } of outcome.publishWarnings) {
+        console.log(`  ⚠ ${name}: ${warning}`);
+    }
+    // SYNC-CLI-EDIT-3.1: the cloud stores the web editor's notation, and files
+    // written another way converge to it on push. Each file NAMED, not counted —
+    // a count leaves Jaime to find out which files changed from `git diff`,
+    // which is exactly what this report exists to prevent.
+    if (outcome.normalized.length > 0) {
+        const n = outcome.normalized.length;
+        console.log(`  ${n} document${n === 1 ? "" : "s"} normalized to web-compatible notation:`);
+        for (const { name } of outcome.normalized) {
+            console.log(`    ${name}`);
+        }
+    }
     // SYNC-FAIL-2.1: saved to cloud, but the local file couldn't be updated —
     // give the re-link recovery step so a retry doesn't mint a duplicate.
     for (const w of outcome.writeBackWarnings) {

package/dist/harness/cache.d.ts

@@ -6,7 +6,7 @@
  * - tracking.jsonl: Append-only tracking of requirement() calls (cross-process safe)
  * - coverage.json: Deduplication cache for cloud reporting
  */
-import type { RequirementNode } from "../schema/index.js";
+import { type RequirementNode } from "../schema/index.js";
 /**
  * Tracking entry for a single requirement() call.
  * Stored as one JSON object per line in tracking.jsonl

package/dist/harness/cache.js

@@ -9,6 +9,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { findRequirementsFilesSync } from "../requirements/index.js";
+import { canonicalRequirementPath, } from "../schema/index.js";
 // Cache directory structure
 const CACHE_DIR = ".cache";
 const LOOKUP_FILE = "lookup.json";
@@ -80,6 +81,19 @@ export function writeLookupCache(requirementsDir, requirements) {
         if (labelPath && labelPath !== node.id) {
             lookup.requirements[labelPath] = { ...entry, isAlias: true };
         }
+        // HARNESS-RESOLVE-2.3: when the file spells the root key non-canonically
+        // (e.g. "login-01"), also index every path under the canonical spelling
+        // ("LOGIN-1"), so a lookup by the spelling other surfaces display resolves
+        // here too — including for the Python/Java helpers, whose only resolution
+        // medium is this cache. The entry's id keeps the authored spelling.
+        for (const authored of [node.id, labelPath]) {
+            if (!authored)
+                continue;
+            const canonicalPath = canonicalRequirementPath(authored);
+            if (canonicalPath !== authored && !lookup.requirements[canonicalPath]) {
+                lookup.requirements[canonicalPath] = { ...entry, isAlias: true };
+            }
+        }
         // Track label occurrences for disambiguation (e.g. given#0, given#1)
         const labelCounts = new Map();
         for (const child of node.children) {

package/dist/harness/finalize.js

@@ -11,6 +11,7 @@
  */
 import { execSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
+import { canonicalRequirementPath } from "../schema/index.js";
 import { getProjectInfo } from "../utils/project-settings.js";
 import { cleanupTestRunId, clearCoverageReportFailure, deleteTrackingFile, findProjectRoot, findRequirementsDir, getTestRunId, needsReporting, readCoverageCache, readLookupCache, readTrackingEntries, recordCoverageReplayed, recordCoverageReported, recordCoverageReportFailure, updateCoverageCache, } from "./cache.js";
 import { formatFailureNotice, formatUnrecordedNotice, refusalReason, } from "./reportingStatus.js";
@@ -478,17 +479,17 @@ export async function finalize(options = {}) {
     // We resolve those to their canonical numeric key (e.g. "AUTH-LOGIN-1.0") so that
     // coverage counting, display, and cloud reporting all use consistent keys.
     if (lookup) {
-        // HARNESS-RESOLVE-2.1: label paths resolve case-insensitively, but
-        // tracking preserves the test's original casing while the cache stores
-        // alias keys lowercased. Fold unmatched keys onto their lowercased-label
-        // alias first, so a ref like "REQ-1.Given" isn't dropped as foreign below.
+        // HARNESS-RESOLVE-2.1/2.3: label paths resolve case-insensitively and
+        // root keys resolve across spellings (casing, leading zeros), but
+        // tracking preserves the test's original spelling while the cache stores
+        // label aliases lowercased and key aliases canonically spelled. Fold
+        // unmatched keys onto their normalized form first, so a ref like
+        // "REQ-1.Given" or "LOGIN-1.0" (for a file that writes "login-01") isn't
+        // dropped as foreign below.
         for (const [key, trackingEntries] of Array.from(aggregated.entries())) {
             if (lookup.requirements[key])
                 continue;
-            const m = /^([A-Z][A-Z0-9_-]*-\d+)(\..+)$/.exec(key);
-            if (!m)
-                continue;
-            const folded = m[1] + m[2].toLowerCase();
+            const folded = canonicalRequirementPath(key);
             if (folded !== key && lookup.requirements[folded]) {
                 const existing = aggregated.get(folded) || [];
                 aggregated.set(folded, [...existing, ...trackingEntries]);

package/dist/harness/requirementsLoader.js

@@ -10,7 +10,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { findRequirementsFilesSync } from "../requirements/index.js";
-import { parseRequirementsFromFile, resolveRequirementPath, } from "../schema/index.js";
+import { canonicalRequirementPath, parseRequirementsFromFile, resolveRequirementPath, } from "../schema/index.js";
 import { findProjectRoot as findProjectRootByWalkUp, readLookupCache, } from "./cache.js";
 // Cache: Maps full requirement IDs (e.g., "REQ-123.0.1") to RequirementNode
 export const loadedRequirements = new Map();
@@ -64,8 +64,10 @@ function tryLoadFromCache(projectRoot) {
             children: [], // Children are loaded separately by ID
         };
         loadedRequirements.set(id, node);
-        // If this is a root node (no dot in ID), add to trees cache
-        if (!id.includes(".")) {
+        // If this is a root node (no dot in ID), add to trees cache. Aliases
+        // (label paths, canonical key spellings) stay out: the trees map holds
+        // one entry per authored root.
+        if (!id.includes(".") && !req.isAlias) {
             requirementTrees.set(id, node);
         }
     }
@@ -163,6 +165,15 @@ export function getRequirement(reqId) {
             return aliased;
         }
     }
+    // HARNESS-RESOLVE-2.3: root-key spelling is authoring latitude, so retry
+    // under the canonical spelling. The lookup cache stores a canonical-key
+    // alias for every node whose authored root spelling isn't already
+    // canonical, so in cache mode this get lands whatever spelling the file
+    // used; the fallback resolver below handles the no-cache mode.
+    const canonical = loadedRequirements.get(canonicalRequirementPath(reqId));
+    if (canonical) {
+        return canonical;
+    }
     // If not found, try resolving label-based paths
     // resolveRequirementPath expects an array of root requirements and the full path
     const allTrees = Array.from(requirementTrees.values());

package/dist/requirements/coverage.js

@@ -9,6 +9,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { findRequirementsDir, isCacheStale, readTrackingEntries, } from "../harness/cache.js";
+import { canonicalRequirementPath } from "../schema/index.js";
 export class LocalReportCacheMissingError extends Error {
     constructor(message) {
         super(message);
@@ -70,37 +71,42 @@ export function buildLocalReport(opts) {
     };
 }
 function buildCoverageEntries(lookup, entries, filterKey) {
-    const locationsByKey = new Map();
+    // Assign each tracked reference to the requirement that owns it: the exact
+    // spelling (primary or alias key) when the project writes it, else the
+    // canonical fold — the same preference order getRequirement uses
+    // (REPORT-LOCAL-1.5). Exact first matters: duplicate detection is
+    // per-document, so a project can legitimately hold distinct requirements
+    // whose keys differ only in spelling, and a test that referenced one must
+    // never count toward the other (HARNESS-RESOLVE-3.0). Locations group
+    // under the owner's node id, which alias entries share with their primary.
+    const locationsById = new Map();
     for (const entry of entries) {
-        if (!locationsByKey.has(entry.requirementKey)) {
-            locationsByKey.set(entry.requirementKey, new Set());
+        const owner = lookup.requirements[entry.requirementKey] ??
+            lookup.requirements[canonicalRequirementPath(entry.requirementKey)];
+        if (!owner)
+            continue;
+        if (!locationsById.has(owner.id)) {
+            locationsById.set(owner.id, new Set());
         }
-        locationsByKey.get(entry.requirementKey).add(entry.callerLocation);
+        locationsById.get(owner.id).add(entry.callerLocation);
+    }
+    // The filter names one requirement; resolve it with the same preference
+    // order, then scope by the owner's node id (REPORT-LOCAL-1.3). A filter
+    // that resolves to nothing matches nothing, as before.
+    let filterId;
+    if (filterKey) {
+        const owner = lookup.requirements[filterKey] ??
+            lookup.requirements[canonicalRequirementPath(filterKey)];
+        filterId = owner?.id ?? filterKey;
     }
     const results = [];
     for (const [key, req] of Object.entries(lookup.requirements)) {
         if (req.isAlias)
             continue;
-        if (filterKey && key !== filterKey && !key.startsWith(`${filterKey}.`)) {
+        if (filterId && key !== filterId && !key.startsWith(`${filterId}.`)) {
             continue;
         }
-        const locations = new Set();
-        const keyLocations = locationsByKey.get(key);
-        if (keyLocations) {
-            keyLocations.forEach((l) => {
-                locations.add(l);
-            });
-        }
-        for (const [aliasKey, aliasReq] of Object.entries(lookup.requirements)) {
-            if (aliasReq.isAlias && aliasReq.id === req.id) {
-                const aliasLocations = locationsByKey.get(aliasKey);
-                if (aliasLocations) {
-                    aliasLocations.forEach((l) => {
-                        locations.add(l);
-                    });
-                }
-            }
-        }
+        const locations = locationsById.get(req.id) ?? new Set();
         results.push({
             key,
             label: req.label || null,

package/dist/schema/browser.d.ts

@@ -9,7 +9,7 @@ export { buildMetadata, constructKey, convexToRequirements, extractRequirementKe
 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, 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 { composeMarkdownWithTitle, effectiveTitle, type SplitMarkdown, splitLeadingH1, } from "./title-markdown.js";
 export type { BuildScenarioOptions, Scenario, ScenarioAssertionSource, ScenarioStep, } from "./scenario.js";
 export { buildScenarioFromRequirements, requirementTreeToScenario, } from "./scenario.js";
 //# sourceMappingURL=browser.d.ts.map

package/dist/schema/browser.js

@@ -24,7 +24,7 @@ REQUIREMENT_PREFIX_PATTERN, RequirementKeySchema, RequirementNodeSchema, Require
 ValidationError, validateKey, validateMetadata, validatePrefix, validateRequirementNode, validateRequirementsFile, } from "./schemas.js";
 // Title semantics (pure TypeScript - browser-safe): the document title and
 // the markdown's leading H1 are the same thing (DOC-TITLE-3)
-export { composeMarkdownWithTitle, splitLeadingH1, } from "./title-markdown.js";
+export { composeMarkdownWithTitle, effectiveTitle, splitLeadingH1, } from "./title-markdown.js";
 // Scenario building (pure TypeScript - browser-safe, used by Convex Node actions)
 export { buildScenarioFromRequirements, requirementTreeToScenario, } from "./scenario.js";
 //# sourceMappingURL=browser.js.map

package/dist/schema/index.d.ts

@@ -15,6 +15,6 @@ export { checkPathAmbiguity, findChildrenByLabel, getAllLabelPaths, parsePathSeg
 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, 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";
+export { buildRequirementKey, CONVEX_ID_PATTERN, canonicalRequirementKey, canonicalRequirementPath, 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, effectiveTitle, type SplitMarkdown, splitLeadingH1, } from "./title-markdown.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/schema/index.js

@@ -15,7 +15,7 @@ export { checkPathAmbiguity, findChildrenByLabel, getAllLabelPaths, parsePathSeg
 // Scenario building (for browser-automation / runScenario)
 export { buildScenarioFromRequirements, requirementTreeToScenario, } from "./scenario.js";
 // Schemas and types
-export { buildRequirementKey, CONVEX_ID_PATTERN, canonicalRequirementKey, 
+export { buildRequirementKey, CONVEX_ID_PATTERN, canonicalRequirementKey, canonicalRequirementPath, 
 // Zod schemas
 MetadataSchema, 
 // Prefix/key utilities
@@ -24,5 +24,5 @@ normalizePrefix, ParsedCriterionSchema, parseRequirementKey, REQUIREMENT_KEY_PAT
 REQUIREMENT_PREFIX_PATTERN, RequirementKeySchema, RequirementNodeSchema, RequirementPrefixSchema, RequirementsFileSchema, 
 // Validation
 ValidationError, validateForPush, validateKey, validateMetadata, validatePrefix, validateRequirementNode, validateRequirementsFile, } from "./schemas.js";
-export { composeMarkdownWithTitle, splitLeadingH1, } from "./title-markdown.js";
+export { composeMarkdownWithTitle, effectiveTitle, splitLeadingH1, } from "./title-markdown.js";
 //# sourceMappingURL=index.js.map

package/dist/schema/resolver.d.ts

@@ -2,7 +2,7 @@
  * Resolve label-based requirement paths to numeric paths.
  * Supports: REQ123.given, REQ123.when.then, REQ123.given#1
  */
-import type { RequirementNode } from "./schemas.js";
+import { type RequirementNode } from "./schemas.js";
 /**
  * Parse a requirement path into segments.
  * E.g., "REQ123.given.then" → ["REQ123", "given", "then"]

package/dist/schema/resolver.js

@@ -2,6 +2,24 @@
  * Resolve label-based requirement paths to numeric paths.
  * Supports: REQ123.given, REQ123.when.then, REQ123.given#1
  */
+import { canonicalRequirementKey } from "./schemas.js";
+/**
+ * Match a path's root segment against the loaded roots: the exact spelling
+ * when a root writes it, else canonically — casing and leading zeros are
+ * authoring latitude, so `LOGIN-1` finds a root written `login-01` and vice
+ * versa (HARNESS-RESOLVE-2.3). Exact first matters: duplicate detection is
+ * per-document, so a project can legitimately hold distinct roots whose keys
+ * differ only in spelling, and each path must bind to the root that writes
+ * it exactly (HARNESS-RESOLVE-3.0).
+ */
+function findRoot(requirements, rootId) {
+    const exact = requirements.find((r) => r.id === rootId);
+    if (exact) {
+        return exact;
+    }
+    const canonical = canonicalRequirementKey(rootId);
+    return requirements.find((r) => canonicalRequirementKey(r.id) === canonical);
+}
 /**
  * Parse a requirement path into segments.
  * E.g., "REQ123.given.then" → ["REQ123", "given", "then"]
@@ -104,7 +122,7 @@ export function resolveRequirementPath(requirements, path) {
     }
     // First segment should be the root requirement ID
     const rootId = segments[0];
-    let currentNode = requirements.find((r) => r.id === rootId);
+    let currentNode = findRoot(requirements, rootId);
     if (!currentNode) {
         return null;
     }
@@ -158,7 +176,7 @@ export function checkPathAmbiguity(requirements, path) {
         return 0;
     }
     const rootId = segments[0];
-    let currentNode = requirements.find((r) => r.id === rootId);
+    let currentNode = findRoot(requirements, rootId);
     if (!currentNode) {
         return 0;
     }

package/dist/schema/schemas.d.ts

@@ -60,6 +60,14 @@ export declare function parseRequirementKey(key: string): {
  * legacy malformed key rather than losing it.
  */
 export declare function canonicalRequirementKey(key: string): string;
+/**
+ * Normalize a full requirement path for comparison: canonical root key plus
+ * the path tail lowercased (label matching is case-insensitive,
+ * HARNESS-RESOLVE-2.1; root spelling is authoring latitude,
+ * HARNESS-RESOLVE-2.3). Comparison only — never a spelling to display or
+ * store in place of what the author wrote.
+ */
+export declare function canonicalRequirementPath(path: string): string;
 /**
  * Build a requirement key from prefix and number.
  */

package/dist/schema/schemas.js

@@ -103,6 +103,19 @@ export function canonicalRequirementKey(key) {
     const parsed = parseRequirementKey(key);
     return parsed ? `${parsed.prefix}-${parsed.number}` : key.toUpperCase();
 }
+/**
+ * Normalize a full requirement path for comparison: canonical root key plus
+ * the path tail lowercased (label matching is case-insensitive,
+ * HARNESS-RESOLVE-2.1; root spelling is authoring latitude,
+ * HARNESS-RESOLVE-2.3). Comparison only — never a spelling to display or
+ * store in place of what the author wrote.
+ */
+export function canonicalRequirementPath(path) {
+    const dot = path.indexOf(".");
+    if (dot === -1)
+        return canonicalRequirementKey(path);
+    return (canonicalRequirementKey(path.slice(0, dot)) + path.slice(dot).toLowerCase());
+}
 /**
  * Build a requirement key from prefix and number.
  */

package/dist/schema/title-markdown.d.ts

@@ -27,4 +27,22 @@ export declare function splitLeadingH1(markdown: string): SplitMarkdown;
  * gets no empty heading line (DOC-TITLE-3.3).
  */
 export declare function composeMarkdownWithTitle(title: string, body: string): string;
+/**
+ * The title a document currently answers to, from its row and published copy.
+ *
+ * One precedence, exported: the working title wins; else the published
+ * markdown's leading H1; else the stored title column; else untitled. The
+ * middle term is the one that keeps getting dropped when this rule is
+ * hand-copied — legacy web-authored documents carry their title only in the
+ * column, H1-authored ones only in the markdown, and every surface that
+ * composes or matches markdown (the edit path's `old_string`, the assistant's
+ * read, publish) must answer identically or a rename lands as a duplicate
+ * body heading. This was the FOURTH hand-written copy of the rule when it was
+ * extracted; the count is the argument for calling this instead of writing a
+ * fifth.
+ */
+export declare function effectiveTitle(workingTitle: string | undefined, published: {
+    markdownContent: string;
+    title?: string;
+} | null | undefined): string;
 //# sourceMappingURL=title-markdown.d.ts.map

package/dist/schema/title-markdown.js

@@ -35,4 +35,24 @@ export function composeMarkdownWithTitle(title, body) {
         return `# ${trimmedTitle}\n`;
     return `# ${trimmedTitle}\n\n${body}`;
 }
+/**
+ * The title a document currently answers to, from its row and published copy.
+ *
+ * One precedence, exported: the working title wins; else the published
+ * markdown's leading H1; else the stored title column; else untitled. The
+ * middle term is the one that keeps getting dropped when this rule is
+ * hand-copied — legacy web-authored documents carry their title only in the
+ * column, H1-authored ones only in the markdown, and every surface that
+ * composes or matches markdown (the edit path's `old_string`, the assistant's
+ * read, publish) must answer identically or a rename lands as a duplicate
+ * body heading. This was the FOURTH hand-written copy of the rule when it was
+ * extracted; the count is the argument for calling this instead of writing a
+ * fifth.
+ */
+export function effectiveTitle(workingTitle, published) {
+    return (workingTitle ??
+        splitLeadingH1(published?.markdownContent ?? "").title ??
+        published?.title ??
+        "");
+}
 //# sourceMappingURL=title-markdown.js.map

package/dist/sync/compare.d.ts

@@ -14,6 +14,14 @@ export declare function duplicateLocalDocumentIds(local: LocalSnapshot): Array<{
     documentId: string;
     filePaths: string[];
 }>;
+/**
+ * The message for the duplicate-id abort, or null when there is nothing to
+ * abort over. Built here, beside the detector, so the abort also names the
+ * snapshot's invalid files (SYNC-FAIL-3.2) — a caller that throws on the
+ * duplicate would otherwise sit on that knowledge until the next run, when
+ * the user has fixed the id and syncs again only to hit the second problem.
+ */
+export declare function duplicateIdAbortMessage(local: LocalSnapshot): string | null;
 /**
  * Compare the whole repo against the whole cloud, pairing documents by id.
  */

package/dist/sync/compare.js

@@ -247,6 +247,35 @@ export function duplicateLocalDocumentIds(local) {
         .filter(([, paths]) => paths.length > 1)
         .map(([documentId, filePaths]) => ({ documentId, filePaths }));
 }
+/**
+ * The message for the duplicate-id abort, or null when there is nothing to
+ * abort over. Built here, beside the detector, so the abort also names the
+ * snapshot's invalid files (SYNC-FAIL-3.2) — a caller that throws on the
+ * duplicate would otherwise sit on that knowledge until the next run, when
+ * the user has fixed the id and syncs again only to hit the second problem.
+ */
+export function duplicateIdAbortMessage(local) {
+    const dupes = duplicateLocalDocumentIds(local);
+    if (dupes.length === 0)
+        return null;
+    const lines = [];
+    for (const d of dupes) {
+        // Copying a starter spec twice leaves three claimants, so count them.
+        lines.push(`${d.filePaths.length} files claim the same document ID "${d.documentId}":`);
+        for (const p of d.filePaths)
+            lines.push(`  ${p}`);
+    }
+    lines.push(`Each file must map to its own cloud document. Remove the "id:" line from all but one file's frontmatter, then sync again.`);
+    const invalid = local.documents.filter((doc) => doc.parseError);
+    if (invalid.length > 0) {
+        lines.push("");
+        lines.push("These files are also invalid — fix them in the same pass:");
+        for (const doc of invalid) {
+            lines.push(`  ${doc.filePath} — ${doc.parseError}`);
+        }
+    }
+    return lines.join("\n");
+}
 /**
  * Compare the whole repo against the whole cloud, pairing documents by id.
  */

package/dist/sync/execute.d.ts

@@ -1,9 +1,11 @@
 /**
  * Executing a sync plan: cloud writes/deletes and local writes/deletes.
  *
- * Cloud writes reuse the push machinery (parse → saveWithRequirements →
- * frontmatter write-back) so document-header/import-provenance fidelity is
- * identical to a repo→cloud push. Local writes reuse local-files.ts.
+ * Cloud writes reuse the push machinery (parse → publish → frontmatter
+ * write-back) so document-header/import-provenance fidelity is identical to a
+ * repo→cloud push. Local writes reuse local-files.ts. Deletes still go straight
+ * to Convex: removing a document needs no conversion, so it has no reason to
+ * take the web-app hop that publishing does.
  */
 import type { PlannedAction, SyncMode } from "./plan.js";
 import type { CloudAuth } from "./snapshot.js";
@@ -38,6 +40,21 @@ export interface SyncOutcome {
         name: string;
         status: string;
     }>;
+    /** Pushes the server accepted while telling us something about them did not
+     * finish. It answers 200 for these on purpose — the publish landed, and
+     * failing the push would send Jaime to retry a thing that already happened —
+     * so the only way they reach anyone is by being reported here. */
+    publishWarnings: Array<{
+        name: string;
+        warning: string;
+    }>;
+    /** SYNC-CLI-EDIT-3.1: files whose notation the cloud changed on storing —
+     * list markers, emphasis characters, spacing. Counted so the sync can say
+     * the reformatting happened and why, instead of leaving Jaime to discover
+     * rewritten files in `git diff`. */
+    normalized: Array<{
+        name: string;
+    }>;
     /** SYNC-TITLE-1.3: pushes that changed a document's title. */
     renames: Array<{
         from: string;

package/dist/sync/execute.js

@@ -1,9 +1,11 @@
 /**
  * Executing a sync plan: cloud writes/deletes and local writes/deletes.
  *
- * Cloud writes reuse the push machinery (parse → saveWithRequirements →
- * frontmatter write-back) so document-header/import-provenance fidelity is
- * identical to a repo→cloud push. Local writes reuse local-files.ts.
+ * Cloud writes reuse the push machinery (parse → publish → frontmatter
+ * write-back) so document-header/import-provenance fidelity is identical to a
+ * repo→cloud push. Local writes reuse local-files.ts. Deletes still go straight
+ * to Convex: removing a document needs no conversion, so it has no reason to
+ * take the web-app hop that publishing does.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -13,6 +15,7 @@ import { api } from "../convex.js";
 import { parseFilesForPushIndividually, WEB_APP_URL } from "../push/core.js";
 import { composeMarkdownWithTitle, splitLeadingH1, writeRequirementsFile, } from "../schema/index.js";
 import { resolveLocalPath } from "./local-files.js";
+import { publishToCloud } from "./publish.js";
 function emptyOutcome() {
     return {
         cloudCreated: 0,
@@ -26,6 +29,8 @@ function emptyOutcome() {
         synced: [],
         writeBackWarnings: [],
         importWarnings: [],
+        publishWarnings: [],
+        normalized: [],
         renames: [],
         inferredPrefixes: [],
     };
@@ -54,7 +59,7 @@ export async function executePlan(plan, cloud, auth, workspaceRoot, mode) {
                     outcome.invalid.push(doc);
                     break;
                 case "cloud_write":
-                    await cloudWrite(client, auth, doc, cloudById, outcome);
+                    await cloudWrite(auth, doc, cloudById, outcome);
                     break;
                 case "cloud_delete":
                     await cloudDelete(client, auth, doc, outcome);
@@ -84,7 +89,7 @@ function errorDisplayMessage(err) {
         return data.message;
     return err instanceof Error ? err.message : String(err);
 }
-async function cloudWrite(client, auth, doc, cloudById, outcome) {
+async function cloudWrite(auth, doc, cloudById, outcome) {
     if (!auth.projectSlug || !doc.filePath) {
         throw new Error("Cannot write to the cloud without project credentials.");
     }
@@ -104,27 +109,36 @@ async function cloudWrite(client, auth, doc, cloudById, outcome) {
     if (meta?.title && splitLeadingH1(parsed.markdownContent).title === null) {
         parsed.markdownContent = composeMarkdownWithTitle(meta.title, parsed.markdownContent);
     }
+    // SYNC-CLI-EDIT-2: the push goes to the web app, which writes it into the
+    // working document Quinn may have open and publishes a copy printed from it.
+    // Convex cannot do that job — the conversion needs the BlockNote schema.
+    //
     // SYNC-TITLE-1: the server derives the title from the body's leading H1.
     // A legacy frontmatter title rides along only as the server's fallback for
     // H1-less bodies (SYNC-TITLE-1.1); the filename is never a title
     // (SYNC-TITLE-1.0).
-    const saveResult = (await client.mutation(api.documents.saveWithRequirements.saveWithRequirements, {
-        projectAuth: {
-            projectSlug: auth.projectSlug,
-            projectSecret: auth.projectSecret,
-        },
-        target: { type: "project", slug: auth.projectSlug },
+    const saveResult = await publishToCloud({
+        projectId: auth.projectSlug,
+        projectSecret: auth.projectSecret,
         documentId: meta?.id,
         title: meta?.title,
         markdownContent: parsed.markdownContent,
         defaultPrefix: meta?.defaultPrefix,
         runMarker: parsed.metadata.ctsRun,
-        dryRun: false,
-    }));
-    const documentId = typeof saveResult === "string" ? saveResult : saveResult.documentId;
+    });
+    const documentId = saveResult.documentId;
+    // The server accepted the publish and told us something after it did not
+    // finish. Reported rather than dropped: the push DID land, so this is not a
+    // failure, but "synced" on its own would claim more than happened.
+    if (saveResult.warning) {
+        outcome.publishWarnings.push({
+            name: path.basename(doc.filePath),
+            warning: saveResult.warning,
+        });
+    }
     // IMPORT-3.3: marker failure is never silent — surface the statuses the
     // server reports as warnings.
-    if (typeof saveResult !== "string" && saveResult.importStatus) {
+    if (saveResult.importStatus) {
         const status = saveResult.importStatus;
         if (status === "invalid_marker" ||
             status === "unsupported_version" ||
@@ -174,6 +188,20 @@ async function cloudWrite(client, auth, doc, cloudById, outcome) {
         name: path.basename(doc.filePath),
         url: `${WEB_APP_URL}/documents/${documentId}`,
     });
+    // SYNC-CLI-EDIT-3: the file adopts what the cloud stored — the web editor's
+    // notation — so the repo and the cloud agree byte-for-byte and the next
+    // `dotreq diff` has nothing to say. Writing back the LOCAL bytes here left
+    // the two permanently disagreeing about spelling, which the comparator
+    // reports as a conflict on a document nobody touched. An older server does
+    // not return its stored copy; the local bytes are then exactly what it
+    // stored, so the fallback is the same agreement.
+    //
+    // `.trim()` on both sides, matching the writer's own treatment of the body —
+    // a looser comparison here reported files as normalized that the write then
+    // left untouched.
+    const contentToWriteBack = saveResult.storedMarkdown ?? parsed.markdownContent;
+    const wasNormalized = saveResult.storedMarkdown !== undefined &&
+        saveResult.storedMarkdown.trim() !== parsed.markdownContent.trim();
     // SYNC-FAIL-2: the cloud document already exists at this point. A write-back
     // failure is a warning on a synced document, never a sync failure (which
     // would invite a retry that mints a duplicate).
@@ -190,7 +218,12 @@ async function cloudWrite(client, auth, doc, cloudById, outcome) {
                 ? { set: meta.defaultPrefix }
                 : "keep",
             version: (parsed.metadata.version ?? 0) + 1,
-        }, parsed.markdownContent);
+        }, contentToWriteBack);
+        // Counted only once the rewrite actually happened: reporting it before a
+        // write that then failed produced two contradicting lines about one file.
+        if (wasNormalized) {
+            outcome.normalized.push({ name: path.basename(doc.filePath) });
+        }
     }
     catch (writeErr) {
         outcome.writeBackWarnings.push({

package/dist/sync/index.d.ts

@@ -3,7 +3,7 @@
  * (snapshot.ts), consumed by `dotreq diff` and `dotreq sync`.
  */
 import type { ComparisonResult, DocumentComparison } from "./types.js";
-export { compareSnapshots, duplicateLocalDocumentIds } from "./compare.js";
+export { compareSnapshots, duplicateIdAbortMessage, duplicateLocalDocumentIds, } from "./compare.js";
 export { displayName, formatUnitDetail, formatVerdictLine, resolutionHint, scopeToken, } from "./render.js";
 export { segmentBody } from "./segment.js";
 export { acquireCloudSnapshot, acquireLocalSnapshot, type CloudAuth, readLocalDocument, } from "./snapshot.js";

package/dist/sync/index.js

@@ -3,7 +3,7 @@
  * (snapshot.ts), consumed by `dotreq diff` and `dotreq sync`.
  */
 import * as path from "node:path";
-export { compareSnapshots, duplicateLocalDocumentIds } from "./compare.js";
+export { compareSnapshots, duplicateIdAbortMessage, duplicateLocalDocumentIds, } from "./compare.js";
 export { displayName, formatUnitDetail, formatVerdictLine, resolutionHint, scopeToken, } from "./render.js";
 export { segmentBody } from "./segment.js";
 export { acquireCloudSnapshot, acquireLocalSnapshot, readLocalDocument, } from "./snapshot.js";

package/dist/sync/publish.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The push half of `dotreq sync`, posted to the web app rather than to Convex.
+ *
+ * Publishing prints the working document — the shared body the web editor is
+ * editing live — so a push has to land there first, and turning the repo's
+ * markdown into that body needs the BlockNote schema, which only the web app's
+ * runtime can build. The payload is the same one `saveWithRequirements` always
+ * took; only its destination moved.
+ *
+ * The cost is a web-app dependency in the push path: an outage there leaves the
+ * repo unable to push. Recoverable rather than lossy — see
+ * docs/working/publishing-and-unpublished-changes.md.
+ */
+export interface PublishParams {
+    /** Project slug or id — whichever `dotreq link` wrote into settings. */
+    projectId: string;
+    projectSecret: string;
+    /** Absent for a file that has never been pushed; the server mints the id. */
+    documentId?: string;
+    markdownContent: string;
+    /** Legacy frontmatter title, used only as the server's H1-less fallback. */
+    title?: string;
+    defaultPrefix?: string;
+    runMarker?: string;
+}
+/**
+ * What the server reports back: the document, any run-marker complaint, and any
+ * partial success.
+ *
+ * `warning` is the server saying the publish landed but something after it did
+ * not — today, seeding a new document's working copy. It answers 200 on purpose,
+ * because the publish itself succeeded and failing the push would send Jaime to
+ * retry a thing that already happened. Dropping the warning here turned that
+ * deliberate partial success back into an unqualified one.
+ */
+export type PublishResult = {
+    documentId: string;
+    importStatus?: string;
+    warning?: string;
+    /**
+     * The markdown the cloud actually stored — the web editor's notation
+     * (SYNC-CLI-EDIT-3). The write-back adopts it so the file and the cloud
+     * agree byte-for-byte; without it the next `dotreq diff` reports a conflict
+     * on a document nobody touched. Absent from older servers, in which case the
+     * write-back falls back to the local bytes, which is exactly the old
+     * behaviour.
+     */
+    storedMarkdown?: string;
+};
+/**
+ * POST to `/api/publish`. Returns the saved document; throws with the server's
+ * own message on failure, which is what Jaime reads in the sync output.
+ *
+ * SYNC-CLI-EDIT-2.3: a document somebody is typing in continuously is the one
+ * refusal that is not a mistake — the message says so, and says the sync will
+ * apply next time.
+ */
+export declare function publishToCloud(params: PublishParams): Promise<PublishResult>;
+//# sourceMappingURL=publish.d.ts.map

package/dist/sync/publish.js

@@ -0,0 +1,45 @@
+/**
+ * The push half of `dotreq sync`, posted to the web app rather than to Convex.
+ *
+ * Publishing prints the working document — the shared body the web editor is
+ * editing live — so a push has to land there first, and turning the repo's
+ * markdown into that body needs the BlockNote schema, which only the web app's
+ * runtime can build. The payload is the same one `saveWithRequirements` always
+ * took; only its destination moved.
+ *
+ * The cost is a web-app dependency in the push path: an outage there leaves the
+ * repo unable to push. Recoverable rather than lossy — see
+ * docs/working/publishing-and-unpublished-changes.md.
+ */
+import { DEFAULT_API_BASE_URL } from "../requirements/cloud-ai.js";
+/**
+ * POST to `/api/publish`. Returns the saved document; throws with the server's
+ * own message on failure, which is what Jaime reads in the sync output.
+ *
+ * SYNC-CLI-EDIT-2.3: a document somebody is typing in continuously is the one
+ * refusal that is not a mistake — the message says so, and says the sync will
+ * apply next time.
+ */
+export async function publishToCloud(params) {
+    const apiBaseUrl = process.env.DOTREQUIREMENTS_API_URL ?? DEFAULT_API_BASE_URL;
+    const response = await fetch(`${apiBaseUrl}/api/publish`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(params),
+    });
+    if (!response.ok) {
+        const body = (await response.json().catch(() => ({})));
+        throw new Error(body.error || response.statusText);
+    }
+    const { result, warning, storedMarkdown } = (await response.json());
+    const published = typeof result === "string" ? { documentId: result } : { ...result };
+    // The server's warning and stored markdown sit beside `result`, not inside
+    // it, so they have to be carried across deliberately — the warning was once
+    // destructured away here.
+    return {
+        ...published,
+        ...(warning !== undefined ? { warning } : {}),
+        ...(storedMarkdown !== undefined ? { storedMarkdown } : {}),
+    };
+}
+//# sourceMappingURL=publish.js.map

package/dist/sync/segment.js

@@ -6,19 +6,7 @@
  * normalized text (prose has no stable id, so a reworded passage reads as a
  * removal-plus-addition — a conflict, per DIFF-4.3).
  */
-import { canonicalRequirementKey, getAllRequirements, parseRequirementBlock, splitRequirementFenceContent, } from "../schema/index.js";
-/**
- * A node's comparison id: the canonical root key plus its position tail, so the
- * two sides agree on identity even when they spell the key differently
- * (DIFF-3.3). Splitting on the first "." keeps the tail untouched — position
- * paths are already canonical.
- */
-function canonicalNodeId(id) {
-    const dot = id.indexOf(".");
-    if (dot === -1)
-        return canonicalRequirementKey(id);
-    return `${canonicalRequirementKey(id.slice(0, dot))}${id.slice(dot)}`;
-}
+import { canonicalRequirementKey, canonicalRequirementPath, getAllRequirements, parseRequirementBlock, splitRequirementFenceContent, } from "../schema/index.js";
 /** Matches a fenced dotrequirements block; group 1 is its inner content. */
 const FENCE = /```dotrequirements\n([\s\S]*?)```/gm;
 /**
@@ -103,7 +91,10 @@ export function requirementUnitMap(blockContent) {
     const map = new Map();
     for (const node of getAllRequirements([tree])) {
         // A NUL (\u0000) separates the label from content so a label change reads as a change.
-        map.set(canonicalNodeId(node.id), `${node.label}\u0000${node.content}`);
+        // The comparison id is the canonical root key plus the numeric position
+        // tail, so both sides agree on identity even when they spell the key
+        // differently (DIFF-3.3).
+        map.set(canonicalRequirementPath(node.id), `${node.label}\u0000${node.content}`);
     }
     return map;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@popoverai/dotrequirements",
-  "version": "0.29.3",
-  "description": "Requirements tracking CLI and test harness",
+  "version": "0.30.0",
+  "description": "Requirements as testable, human-readable data — CLI and test harness for spec-driven development with AI coding agents",
   "type": "module",
   "bin": {
     "dotrequirements": "./dist/cli.js",
@@ -30,11 +30,17 @@
   },
   "keywords": [
     "requirements",
+    "specifications",
+    "spec-driven-development",
     "testing",
     "test-coverage",
+    "acceptance-criteria",
     "bdd",
     "tdd",
-    "ai-assistant"
+    "ai-assistant",
+    "ai-agents",
+    "claude-code",
+    "mcp"
   ],
   "author": "Will Raymer @Popover",
   "license": "MIT",
@@ -49,9 +55,7 @@
     "@babel/parser": "^7.28.5",
     "@babel/traverse": "^7.28.5",
     "@babel/types": "^7.28.5",
-    "@modelcontextprotocol/sdk": "^1.0.0",
     "@types/prompts": "^2.4.9",
-    "@workos-inc/node": "^7.77.0",
     "chalk": "^5.6.2",
     "commander": "^12.1.0",
     "convex": "^1.42.3",
@@ -70,7 +74,7 @@
     "@types/node": "^20",
     "@types/uuid": "^11.0.0",
     "typescript": "^5",
-    "vitest": "^4.1.8"
+    "vitest": "^4.1.10"
   },
   "files": [
     "dist",