@popoverai/dotrequirements 0.28.0 → 0.29.0

package/dist/codebase-to-spec/compose.d.ts

@@ -1,8 +1,9 @@
 /**
  * Compose stage: assemble per-area partials into a single composed spec.
  *
- * The composed document has YAML frontmatter (title, defaultPrefix), an H1
- * title, a summary paragraph from the outline, and one H2 section per area.
+ * The composed document has YAML frontmatter (defaultPrefix), an H1 title —
+ * the document's name (SYNC-TITLE-1) — a summary paragraph from the outline,
+ * and one H2 section per area.
  * Each area section contains the partial's content.
  *
  * After assembly, a deterministic renumbering pass rewrites each prefix's

package/dist/codebase-to-spec/compose.js

@@ -1,8 +1,9 @@
 /**
  * Compose stage: assemble per-area partials into a single composed spec.
  *
- * The composed document has YAML frontmatter (title, defaultPrefix), an H1
- * title, a summary paragraph from the outline, and one H2 section per area.
+ * The composed document has YAML frontmatter (defaultPrefix), an H1 title —
+ * the document's name (SYNC-TITLE-1) — a summary paragraph from the outline,
+ * and one H2 section per area.
  * Each area section contains the partial's content.
  *
  * After assembly, a deterministic renumbering pass rewrites each prefix's
@@ -48,7 +49,6 @@ export function assembleComposedDocument(outline, partialPathFor) {
     const parts = [];
     parts.push("---");
     parts.push("document:");
-    parts.push(`  title: "${escapeYamlString(outline.title)}"`);
     parts.push(`  defaultPrefix: ${outline.defaultPrefix}`);
     parts.push("---");
     parts.push("");

package/dist/commands/sync.js

@@ -114,6 +114,11 @@ export async function syncCommand(scope, options) {
     for (const err of outcome.errors) {
         console.log(`  ✗ failed: ${err.name} — ${err.error}`);
     }
+    // SYNC-TITLE-1.3: a push that changed a title is a rename — say so, so an
+    // unintended H1 edit is visible and costs one heading edit to undo.
+    for (const r of outcome.renames) {
+        console.log(`  renamed "${r.from}" → "${r.to}"`);
+    }
     // IMPORT-3: marker failures are loud but never fatal.
     for (const { name, status } of outcome.importWarnings) {
         if (status === "already_used") {

package/dist/push/core.js

@@ -65,6 +65,13 @@ export function mergeMetadataWithRawFrontmatter(metadata, rawFrontmatter) {
             ...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;
 }

package/dist/requirements/index.d.ts

@@ -17,6 +17,8 @@ export interface FlattenedRequirement {
 export interface ParsedRequirementsFile {
     metadata: Metadata;
     requirements: RequirementNode[];
+    /** Markdown body; its leading H1 is the document's title (SYNC-TITLE-1). */
+    body?: string;
 }
 /**
  * Find all *.requirements.md files in the workspace.

package/dist/requirements/index.js

@@ -1,6 +1,7 @@
 import * as path from "node:path";
 import { glob, globSync } from "glob";
 import { buildRequirementMarkdown, getAllRequirements, parseRequirementsFile, parseRequirementsFromFile, } from "../schema/index.js";
+import { splitLeadingH1 } from "../schema/title-markdown.js";
 /**
  * Glob pattern matching *.requirements.md files.
  */
@@ -90,7 +91,11 @@ export function flattenRequirementsFile(file, sourceFile) {
             content: req.content,
             path: idParts.slice(1), // ["0", "1"] for "REQ123.0.1"
             sourceFile: sourceFile,
-            documentTitle: file.metadata.document?.title || rootId,
+            // SYNC-TITLE-1: the body's leading H1 is the title; legacy
+            // frontmatter title as fallback for pre-H1 files
+            documentTitle: splitLeadingH1(file.body ?? "").title ||
+                file.metadata.document?.title ||
+                rootId,
         });
     }
     return results;

package/dist/requirements/style-guide.js

@@ -125,7 +125,7 @@ ${customStyleGuidance.trim()}`;
     }
     const template = `---
 document:
-  title: "Example Requirements"
+  defaultPrefix: EXAMPLE
 ---
 
 # Example Requirements

package/dist/schema/browser.d.ts

@@ -9,6 +9,7 @@ export { buildMetadata, constructKey, convexToRequirements, extractRequirementKe
 export { DELIMITER_PATTERN, extractRequirementBlocks, findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRequirementBlocksFromMarkdown, parseRootLine, ROOT_LABEL_MARKER, } 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 { composeMarkdownWithTitle, 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

@@ -22,6 +22,9 @@ normalizePrefix, ParsedCriterionSchema, parseRequirementKey, REQUIREMENT_KEY_PAT
 REQUIREMENT_PREFIX_PATTERN, RequirementKeySchema, RequirementNodeSchema, RequirementPrefixSchema, RequirementsFileSchema, 
 // Validation
 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";
 // 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

@@ -13,4 +13,5 @@ export type { BuildScenarioOptions, Scenario, ScenarioAssertionSource, ScenarioS
 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 { composeMarkdownWithTitle, type SplitMarkdown, splitLeadingH1, } from "./title-markdown.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/schema/index.js

@@ -23,4 +23,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";
 //# sourceMappingURL=index.js.map

package/dist/schema/parser.d.ts

@@ -15,6 +15,8 @@ export { findRequirementById, flattenRequirementTree, getAllRequirements, parseC
 export declare function parseRequirementsFile(markdownContent: string): {
     metadata: RequirementsFile["_meta"];
     requirements: RequirementNode[];
+    /** The markdown body (frontmatter stripped) — its leading H1 is the document's title (SYNC-TITLE-1). */
+    body: string;
 };
 /**
  * Parse requirements file from disk.
@@ -22,5 +24,6 @@ export declare function parseRequirementsFile(markdownContent: string): {
 export declare function parseRequirementsFromFile(filePath: string): {
     metadata: RequirementsFile["_meta"];
     requirements: RequirementNode[];
+    body: string;
 };
 //# sourceMappingURL=parser.d.ts.map

package/dist/schema/parser.js

@@ -47,7 +47,7 @@ export function parseRequirementsFile(markdownContent) {
     if (requirements.length === 0) {
         throw new ValidationError("No requirement blocks found in document");
     }
-    return { metadata, requirements };
+    return { metadata, requirements, body };
 }
 /**
  * Parse requirements file from disk.

package/dist/schema/schemas.d.ts

@@ -54,8 +54,10 @@ export declare function parseRequirementKey(key: string): {
  */
 export declare function buildRequirementKey(prefix: string, number: number): string;
 /**
- * Metadata block at the top of every requirements file.
- * Only document.title is required for push; everything else is optional or auto-filled.
+ * Metadata block at the top of every requirements file. Everything is
+ * optional or auto-filled; the document's title lives in the BODY as its
+ * leading H1 (SYNC-TITLE-1), with a legacy frontmatter title tolerated as a
+ * fallback for files from before that convention.
  */
 export declare const MetadataSchema: z.ZodObject<{
     version: z.ZodOptional<z.ZodNumber>;
@@ -63,15 +65,15 @@ export declare const MetadataSchema: z.ZodObject<{
     ctsRun: z.ZodOptional<z.ZodString>;
     document: z.ZodOptional<z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
-        title: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
         defaultPrefix: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        title: string;
         id?: string | undefined;
+        title?: string | undefined;
         defaultPrefix?: string | undefined;
     }, {
-        title: string;
         id?: string | undefined;
+        title?: string | undefined;
         defaultPrefix?: string | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
@@ -79,8 +81,8 @@ export declare const MetadataSchema: z.ZodObject<{
     pulledAt?: string | undefined;
     ctsRun?: string | undefined;
     document?: {
-        title: string;
         id?: string | undefined;
+        title?: string | undefined;
         defaultPrefix?: string | undefined;
     } | undefined;
 }, {
@@ -88,8 +90,8 @@ export declare const MetadataSchema: z.ZodObject<{
     pulledAt?: string | undefined;
     ctsRun?: string | undefined;
     document?: {
-        title: string;
         id?: string | undefined;
+        title?: string | undefined;
         defaultPrefix?: string | undefined;
     } | undefined;
 }>;
@@ -152,15 +154,15 @@ export declare const RequirementsFileSchema: z.ZodObject<{
         ctsRun: z.ZodOptional<z.ZodString>;
         document: z.ZodOptional<z.ZodObject<{
             id: z.ZodOptional<z.ZodString>;
-            title: z.ZodString;
+            title: z.ZodOptional<z.ZodString>;
             defaultPrefix: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
-            title: string;
             id?: string | undefined;
+            title?: string | undefined;
             defaultPrefix?: string | undefined;
         }, {
-            title: string;
             id?: string | undefined;
+            title?: string | undefined;
             defaultPrefix?: string | undefined;
         }>>;
     }, "strip", z.ZodTypeAny, {
@@ -168,8 +170,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
         pulledAt?: string | undefined;
         ctsRun?: string | undefined;
         document?: {
-            title: string;
             id?: string | undefined;
+            title?: string | undefined;
             defaultPrefix?: string | undefined;
         } | undefined;
     }, {
@@ -177,8 +179,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
         pulledAt?: string | undefined;
         ctsRun?: string | undefined;
         document?: {
-            title: string;
             id?: string | undefined;
+            title?: string | undefined;
             defaultPrefix?: string | undefined;
         } | undefined;
     }>;
@@ -189,15 +191,15 @@ export declare const RequirementsFileSchema: z.ZodObject<{
         ctsRun: z.ZodOptional<z.ZodString>;
         document: z.ZodOptional<z.ZodObject<{
             id: z.ZodOptional<z.ZodString>;
-            title: z.ZodString;
+            title: z.ZodOptional<z.ZodString>;
             defaultPrefix: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
-            title: string;
             id?: string | undefined;
+            title?: string | undefined;
             defaultPrefix?: string | undefined;
         }, {
-            title: string;
             id?: string | undefined;
+            title?: string | undefined;
             defaultPrefix?: string | undefined;
         }>>;
     }, "strip", z.ZodTypeAny, {
@@ -205,8 +207,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
         pulledAt?: string | undefined;
         ctsRun?: string | undefined;
         document?: {
-            title: string;
             id?: string | undefined;
+            title?: string | undefined;
             defaultPrefix?: string | undefined;
         } | undefined;
     }, {
@@ -214,8 +216,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
         pulledAt?: string | undefined;
         ctsRun?: string | undefined;
         document?: {
-            title: string;
             id?: string | undefined;
+            title?: string | undefined;
             defaultPrefix?: string | undefined;
         } | undefined;
     }>;
@@ -226,15 +228,15 @@ export declare const RequirementsFileSchema: z.ZodObject<{
         ctsRun: z.ZodOptional<z.ZodString>;
         document: z.ZodOptional<z.ZodObject<{
             id: z.ZodOptional<z.ZodString>;
-            title: z.ZodString;
+            title: z.ZodOptional<z.ZodString>;
             defaultPrefix: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
-            title: string;
             id?: string | undefined;
+            title?: string | undefined;
             defaultPrefix?: string | undefined;
         }, {
-            title: string;
             id?: string | undefined;
+            title?: string | undefined;
             defaultPrefix?: string | undefined;
         }>>;
     }, "strip", z.ZodTypeAny, {
@@ -242,8 +244,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
         pulledAt?: string | undefined;
         ctsRun?: string | undefined;
         document?: {
-            title: string;
             id?: string | undefined;
+            title?: string | undefined;
             defaultPrefix?: string | undefined;
         } | undefined;
     }, {
@@ -251,8 +253,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
         pulledAt?: string | undefined;
         ctsRun?: string | undefined;
         document?: {
-            title: string;
             id?: string | undefined;
+            title?: string | undefined;
             defaultPrefix?: string | undefined;
         } | undefined;
     }>;

package/dist/schema/schemas.js

@@ -106,8 +106,10 @@ export function buildRequirementKey(prefix, number) {
 // Metadata Schema
 // =============================================================================
 /**
- * Metadata block at the top of every requirements file.
- * Only document.title is required for push; everything else is optional or auto-filled.
+ * Metadata block at the top of every requirements file. Everything is
+ * optional or auto-filled; the document's title lives in the BODY as its
+ * leading H1 (SYNC-TITLE-1), with a legacy frontmatter title tolerated as a
+ * fallback for files from before that convention.
  */
 export const MetadataSchema = z.object({
     version: z.number().optional(), // Informational - incremented on push
@@ -116,7 +118,7 @@ export const MetadataSchema = z.object({
     document: z
         .object({
         id: z.string().optional(), // Cloud document link - filled by push when creating
-        title: z.string(), // Required for push
+        title: z.string().optional(), // Legacy fallback — the body's leading H1 is the title
         defaultPrefix: z.string().optional(), // Editor hint for new requirement keys
     })
         .optional(),
@@ -136,18 +138,13 @@ export const CONVEX_ID_PATTERN = /^j[a-z0-9]{31}$/;
  * SYNC-CLI-EDIT-1: Files with valid document.id update existing documents
  */
 export function validateForPush(metadata) {
-    // Must have document section
+    // Must have document section. (A title is NOT required — untitled
+    // documents are allowed, and the title is derived from the markdown's
+    // leading H1 anyway; see docs/working/h1-as-title.md.)
     if (!metadata.document) {
         return {
             valid: false,
-            reason: "Missing document section. Add a document section with a title to sync this file.",
-        };
-    }
-    // Must have title
-    if (!metadata.document.title || metadata.document.title.trim() === "") {
-        return {
-            valid: false,
-            reason: "Document section missing required title.",
+            reason: "Missing document section. Add a document section to sync this file.",
         };
     }
     // Check document.id

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

@@ -0,0 +1,30 @@
+/**
+ * The document title and the markdown's leading H1 are the same thing
+ * (DOC-TITLE-3). These helpers hold that contract at the web app's storage
+ * boundary: markdown coming *in* from Convex is split into title + body, and
+ * markdown going *out* is recomposed — so inside the app, `Content.markdown`
+ * is always the body (no leading H1) and `Content.title` carries the title.
+ */
+export interface SplitMarkdown {
+    /** The leading H1's text, or null when the markdown has no leading H1. */
+    title: string | null;
+    /** Everything after the leading H1 (or the whole input when there is none). */
+    body: string;
+}
+/**
+ * Split a leading ATX H1 (`# Title`) off the markdown.
+ *
+ * "Leading" means the first non-blank line (DOC-TITLE-3.0); an H1 further
+ * down is ordinary content and stays in the body (DOC-TITLE-3.4). Markdown
+ * allows up to 3 spaces of heading indentation — 4+ is a code block, so it
+ * is not a title.
+ */
+export declare function splitLeadingH1(markdown: string): SplitMarkdown;
+/**
+ * Compose full-document markdown from a title and a body.
+ *
+ * The title becomes the leading H1 (DOC-TITLE-3.1); an untitled document
+ * gets no empty heading line (DOC-TITLE-3.3).
+ */
+export declare function composeMarkdownWithTitle(title: string, body: string): string;
+//# sourceMappingURL=title-markdown.d.ts.map

package/dist/schema/title-markdown.js

@@ -0,0 +1,38 @@
+/**
+ * The document title and the markdown's leading H1 are the same thing
+ * (DOC-TITLE-3). These helpers hold that contract at the web app's storage
+ * boundary: markdown coming *in* from Convex is split into title + body, and
+ * markdown going *out* is recomposed — so inside the app, `Content.markdown`
+ * is always the body (no leading H1) and `Content.title` carries the title.
+ */
+/**
+ * Split a leading ATX H1 (`# Title`) off the markdown.
+ *
+ * "Leading" means the first non-blank line (DOC-TITLE-3.0); an H1 further
+ * down is ordinary content and stays in the body (DOC-TITLE-3.4). Markdown
+ * allows up to 3 spaces of heading indentation — 4+ is a code block, so it
+ * is not a title.
+ */
+export function splitLeadingH1(markdown) {
+    const match = /^(?:[ \t]*\r?\n)* {0,3}# (.*)(?:\r?\n|$)/.exec(markdown);
+    if (!match) {
+        return { title: null, body: markdown };
+    }
+    const body = markdown.slice(match[0].length).replace(/^(\s*\r?\n)+/, "");
+    return { title: match[1].trim(), body };
+}
+/**
+ * Compose full-document markdown from a title and a body.
+ *
+ * The title becomes the leading H1 (DOC-TITLE-3.1); an untitled document
+ * gets no empty heading line (DOC-TITLE-3.3).
+ */
+export function composeMarkdownWithTitle(title, body) {
+    const trimmedTitle = title.trim();
+    if (!trimmedTitle)
+        return body;
+    if (!body.trim())
+        return `# ${trimmedTitle}\n`;
+    return `# ${trimmedTitle}\n\n${body}`;
+}
+//# sourceMappingURL=title-markdown.js.map

package/dist/sync/execute.d.ts

@@ -38,6 +38,11 @@ export interface SyncOutcome {
         name: string;
         status: string;
     }>;
+    /** SYNC-TITLE-1.3: pushes that changed a document's title. */
+    renames: Array<{
+        from: string;
+        to: string;
+    }>;
 }
 /**
  * Execute a plan. `cloud` provides bodies for local writes (keyed by id). Cloud

package/dist/sync/execute.js

@@ -11,7 +11,7 @@ import { ConvexHttpClient } from "convex/browser";
 import { getConvexUrl } from "../config.js";
 import { api } from "../convex.js";
 import { mergeMetadataWithRawFrontmatter, parseFilesForPushIndividually, WEB_APP_URL, } from "../push/core.js";
-import { buildRequirementsFile } from "../schema/index.js";
+import { buildRequirementsFile, composeMarkdownWithTitle, splitLeadingH1, } from "../schema/index.js";
 import { resolveLocalPath, writeLocalDocument } from "./local-files.js";
 function emptyOutcome() {
     return {
@@ -26,6 +26,7 @@ function emptyOutcome() {
         synced: [],
         writeBackWarnings: [],
         importWarnings: [],
+        renames: [],
     };
 }
 /**
@@ -52,7 +53,7 @@ export async function executePlan(plan, cloud, auth, workspaceRoot) {
                     outcome.invalid.push(doc);
                     break;
                 case "cloud_write":
-                    await cloudWrite(client, auth, doc, outcome);
+                    await cloudWrite(client, auth, doc, cloudById, outcome);
                     break;
                 case "cloud_delete":
                     await cloudDelete(client, auth, doc, outcome);
@@ -82,7 +83,7 @@ function errorDisplayMessage(err) {
         return data.message;
     return err instanceof Error ? err.message : String(err);
 }
-async function cloudWrite(client, auth, doc, outcome) {
+async function cloudWrite(client, auth, doc, cloudById, outcome) {
     if (!auth.projectSlug || !doc.filePath) {
         throw new Error("Cannot write to the cloud without project credentials.");
     }
@@ -91,6 +92,21 @@ async function cloudWrite(client, auth, doc, outcome) {
     if (!parsed)
         throw new Error(`Could not parse ${path.basename(doc.filePath)}`);
     const meta = parsed.metadata.document;
+    // SYNC-TITLE-1.1: a legacy file whose title lives only in frontmatter (no body
+    // H1) must reach the cloud self-describing. Materialize the title as the body's
+    // leading H1 BEFORE the push — so the cloud row carries the H1 on first write
+    // and never lands as an H1-less-but-titled row. Such a row would otherwise be
+    // reachable to a web/MCP edit that untitles it (and is out of reach of the
+    // one-time title backfill, since a legacy checkout mints it on any later sync).
+    // Only the unambiguous case fires: a known frontmatter title with no existing
+    // H1 — never a guess about a content H1.
+    if (meta?.title && splitLeadingH1(parsed.markdownContent).title === null) {
+        parsed.markdownContent = composeMarkdownWithTitle(meta.title, parsed.markdownContent);
+    }
+    // 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,
@@ -98,7 +114,7 @@ async function cloudWrite(client, auth, doc, outcome) {
         },
         target: { type: "project", slug: auth.projectSlug },
         documentId: meta?.id,
-        title: meta?.title ?? path.basename(doc.filePath),
+        title: meta?.title,
         markdownContent: parsed.markdownContent,
         defaultPrefix: meta?.defaultPrefix,
         runMarker: parsed.metadata.ctsRun,
@@ -125,6 +141,24 @@ async function cloudWrite(client, auth, doc, outcome) {
         outcome.cloudCreated++;
     else
         outcome.cloudUpdated++;
+    // SYNC-TITLE-1.3: a push that changes the title is a rename — announce it,
+    // so an unintended H1 edit is visible and costs one heading edit to undo.
+    // The new title is derived from the pushed markdown exactly as the server
+    // derives it (H1, else the legacy frontmatter title, else untitled) — NOT
+    // from doc.title, which the comparator pins to the OLD cloud title for any
+    // id-matched document, so comparing against it never detects a rename.
+    const cloudBefore = meta?.id ? cloudById.get(meta.id) : undefined;
+    if (cloudBefore) {
+        const newTitle = splitLeadingH1(parsed.markdownContent).title ?? meta?.title ?? "";
+        // NAV-TITLE-1.2: the cloud snapshot reports an untitled document's title as
+        // the display fallback "Untitled Document", while newTitle is "" for that
+        // same state. Normalize before comparing so a content-only push of an
+        // untitled doc doesn't report a phantom `"Untitled Document" → ""` rename.
+        const before = cloudBefore.title === "Untitled Document" ? "" : cloudBefore.title;
+        if (before !== newTitle) {
+            outcome.renames.push({ from: before, to: newTitle });
+        }
+    }
     outcome.synced.push({
         name: path.basename(doc.filePath),
         url: `${WEB_APP_URL}/documents/${documentId}`,
@@ -133,8 +167,13 @@ async function cloudWrite(client, auth, doc, outcome) {
     // failure is a warning on a synced document, never a sync failure (which
     // would invite a retry that mints a duplicate).
     try {
-        if (parsed.metadata.document)
+        if (parsed.metadata.document) {
             parsed.metadata.document.id = documentId;
+            // SYNC-TITLE-1.2: drop the legacy frontmatter title — the body already
+            // carries the name as its leading H1 (materialized above, before the
+            // push), so the rewritten file loses the field without losing the title.
+            delete parsed.metadata.document.title;
+        }
         parsed.metadata.pulledAt = new Date().toISOString();
         parsed.metadata.version = (parsed.metadata.version ?? 0) + 1;
         const content = buildRequirementsFile(mergeMetadataWithRawFrontmatter(parsed.metadata, parsed.rawFrontmatter), parsed.markdownContent);

package/dist/sync/local-files.js

@@ -51,13 +51,15 @@ export function readCtsRun(filePath) {
  */
 export function writeLocalDocument(filePath, cloud) {
     const existingCtsRun = readCtsRun(filePath);
+    // SYNC-TITLE-1.2: no `document.title` in frontmatter — the title lives in
+    // the body as its leading H1. A legacy file that gets rewritten loses the
+    // field here, since the metadata is rebuilt from scratch.
     const metadata = {
         pulledAt: new Date().toISOString(),
         version: cloud.version,
         ...(existingCtsRun ? { ctsRun: existingCtsRun } : {}),
         document: {
             id: cloud.documentId,
-            title: cloud.title,
             defaultPrefix: cloud.defaultPrefix,
         },
     };

package/dist/sync/snapshot.js

@@ -9,7 +9,7 @@ import YAML from "yaml";
 import { getConvexUrl } from "../config.js";
 import { api } from "../convex.js";
 import { findRequirementsFiles } from "../requirements/index.js";
-import { validateMetadata } from "../schema/index.js";
+import { splitLeadingH1, validateMetadata } from "../schema/index.js";
 import { parseRequirementBlocksFromMarkdown, splitFrontmatter, stripFrontmatterBlock, } from "../schema/parser-core.js";
 /**
  * Read and classify one requirements file into a LocalDocument. A file whose
@@ -79,7 +79,11 @@ export function readLocalDocument(filePath) {
     catch (err) {
         return { filePath, documentId, title, parseError: err.message };
     }
-    return { filePath, documentId, title, defaultPrefix, body };
+    // SYNC-TITLE-1: the body's leading H1 is the document's title. A legacy
+    // frontmatter title stands only when the body has none (SYNC-TITLE-1.1);
+    // with neither, the document is untitled (SYNC-TITLE-1.4).
+    const derivedTitle = splitLeadingH1(body).title ?? title;
+    return { filePath, documentId, title: derivedTitle, defaultPrefix, body };
 }
 /**
  * Build the local snapshot from the workspace, or from an explicit set of file

package/dist/templates/example-requirements.js

@@ -10,8 +10,6 @@ export function generateExampleRequirements(projectId = "local") {
 projectId: ${projectId}
 pulledAt: ${now}
 version: 1
-document:
-  title: "Example Requirements"
 ---
 
 # Example Requirements

package/dist/templates/example-requirements.ts

@@ -13,8 +13,6 @@ export function generateExampleRequirements(
 projectId: ${projectId}
 pulledAt: ${now}
 version: 1
-document:
-  title: "Example Requirements"
 ---
 
 # Example Requirements

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popoverai/dotrequirements",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "Requirements tracking CLI and test harness",
   "type": "module",
   "bin": {