youmd 0.10.0 → 0.10.2

package/dist/lib/tasksFile.js

@@ -1,17 +1,7 @@
 "use strict";
 /**
- * Canonical per-project task files: project-context/tasks.json + tasks.md.
- *
- * tasks.json is the machine truth (schema you-md/tasks/v1, fields aligned
- * with the Convex portfolioTasks table so rows round-trip losslessly).
- * tasks.md is the human/agent view, regenerated from tasks.json on every
- * write. Checkbox edits made directly in tasks.md are reconciled back into
- * tasks.json on the next read — tick a box in either file and both agree.
- * Freeform prose in tasks.md between the notes markers is preserved verbatim
- * across regenerations, so watchpoints and context never get clobbered.
- *
- * Legacy freeform tasks.md files (plain checklists with no id comments) are
- * imported automatically on first read: bullets become tasks, nothing is lost.
+ * Canonical task ledger: strict project-context/tasks.json plus a deterministic
+ * generated tasks.md companion. tasks.json is the only editable truth.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -47,13 +37,16 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TASK_PRIORITIES = exports.TASK_STATUSES = exports.TASKS_SCHEMA = void 0;
+exports.TasksFileError = exports.TASK_PRIORITIES = exports.TASK_STATUSES = exports.TASKS_SCHEMA = void 0;
 exports.generateTaskId = generateTaskId;
 exports.tasksJsonPath = tasksJsonPath;
 exports.tasksMdPath = tasksMdPath;
+exports.parseTasksJson = parseTasksJson;
 exports.parseLegacyTasksMd = parseLegacyTasksMd;
 exports.renderTasksMd = renderTasksMd;
+exports.assertTasksMdMatches = assertTasksMdMatches;
 exports.reconcileMdCheckboxes = reconcileMdCheckboxes;
+exports.resolveTaskWriteGrant = resolveTaskWriteGrant;
 exports.readTasksDoc = readTasksDoc;
 exports.writeTasksDoc = writeTasksDoc;
 exports.addTask = addTask;
@@ -65,52 +58,146 @@ const crypto = __importStar(require("crypto"));
 exports.TASKS_SCHEMA = "you-md/tasks/v1";
 exports.TASK_STATUSES = ["proposed", "open", "in_progress", "done", "snoozed", "cancelled"];
 exports.TASK_PRIORITIES = ["low", "normal", "high", "urgent"];
+class TasksFileError extends Error {
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.code = code;
+        this.name = "TasksFileError";
+    }
+}
+exports.TasksFileError = TasksFileError;
 const NOTES_START = "<!-- notes:start -->";
 const NOTES_END = "<!-- notes:end -->";
+const GENERATED_MARKER = "<!-- generated from tasks.json (you-md/tasks/v1). Do not edit;";
 const ID_COMMENT = /<!--\s*id:([A-Za-z0-9_-]+)\s*-->/;
+const TASK_ID = /^t-[A-Za-z0-9][A-Za-z0-9_-]{0,94}$/;
+const PROJECT_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+const PROJECT_REF = /^project:[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
+const ARTIFACT_REF = /^artifact:[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?\/[a-z0-9][a-z0-9._-]{0,95}$/;
+const SAFE_RELATIVE_PATH = /^(?!\/)(?![A-Za-z]:)(?!.*\\)(?!.*\/\/)(?!.*(?:^|\/)(?:\.{1,2})(?:\/|$))(?!.*[\u0000-\u001f\u007f])(?!.*\/$)[^/]+(?:\/[^/]+)*$/;
 const OPEN_STATUSES = ["proposed", "open", "in_progress", "snoozed"];
-function generateTaskId(now = new Date()) {
-    const stamp = now.toISOString().slice(0, 10).replace(/-/g, "");
-    return `t-${stamp}-${crypto.randomBytes(3).toString("hex")}`;
+const DOC_KEYS = new Set(["$schema", "project", "updatedAt", "tasks", "notes"]);
+const TASK_KEYS = new Set([
+    "id", "title", "description", "status", "priority", "owner", "ownerLabel", "tags",
+    "source", "verify", "createdAt", "updatedAt", "completedAt",
+]);
+function nowIso(now = new Date()) { return now.toISOString(); }
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
-function tasksJsonPath(contextDir) {
-    return path.join(contextDir, "tasks.json");
+function exactIso(value) {
+    return typeof value === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(value)
+        && Number.isFinite(Date.parse(value));
 }
-function tasksMdPath(contextDir) {
-    return path.join(contextDir, "tasks.md");
+function boundedText(value, max, optional = false) {
+    if (value === undefined && optional)
+        return undefined;
+    if (typeof value !== "string" || !value.trim() || value.length > max || /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(value))
+        return undefined;
+    return value;
 }
-function nowIso() {
-    return new Date().toISOString();
+function assertNoUnknown(record, allowed, code, where) {
+    const unknown = Object.keys(record).filter((key) => !allowed.has(key));
+    if (unknown.includes("remoteId"))
+        throw new TasksFileError("TASKS_REMOTE_ID_FORBIDDEN", `${where} contains remoteId`);
+    if (unknown.length)
+        throw new TasksFileError(code, `${where} contains unknown fields: ${unknown.join(", ")}`);
 }
-function normalizeStatus(raw) {
-    return exports.TASK_STATUSES.includes(raw) ? raw : "open";
+function generateTaskId(now = new Date()) {
+    return `t-${now.toISOString().slice(0, 10).replace(/-/g, "")}-${crypto.randomBytes(3).toString("hex")}`;
 }
-function normalizePriority(raw) {
-    return exports.TASK_PRIORITIES.includes(raw) ? raw : "normal";
+function tasksJsonPath(contextDir) { return path.join(contextDir, "tasks.json"); }
+function tasksMdPath(contextDir) { return path.join(contextDir, "tasks.md"); }
+function parseTask(value, index) {
+    if (!isRecord(value))
+        throw new TasksFileError("TASKS_INVALID_TASK", `tasks[${index}] must be an object`);
+    assertNoUnknown(value, TASK_KEYS, "TASKS_INVALID_TASK", `tasks[${index}]`);
+    if (typeof value.id !== "string" || !TASK_ID.test(value.id))
+        throw new TasksFileError("TASKS_INVALID_TASK", `tasks[${index}].id is invalid`);
+    const title = boundedText(value.title, 240);
+    if (!title)
+        throw new TasksFileError("TASKS_INVALID_TASK", `tasks[${index}].title is invalid`);
+    if (!exports.TASK_STATUSES.includes(value.status))
+        throw new TasksFileError("TASKS_INVALID_TASK", `tasks[${index}].status is invalid`);
+    if (!exports.TASK_PRIORITIES.includes(value.priority))
+        throw new TasksFileError("TASKS_INVALID_TASK", `tasks[${index}].priority is invalid`);
+    if (value.owner !== "human" && value.owner !== "agent")
+        throw new TasksFileError("TASKS_INVALID_TASK", `tasks[${index}].owner is invalid`);
+    if (!Array.isArray(value.tags) || value.tags.length > 32 || value.tags.some((tag) => typeof tag !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(tag))) {
+        throw new TasksFileError("TASKS_INVALID_TASK", `tasks[${index}].tags are invalid`);
+    }
+    if (new Set(value.tags).size !== value.tags.length)
+        throw new TasksFileError("TASKS_INVALID_TASK", `tasks[${index}].tags must be unique`);
+    if (!exactIso(value.createdAt) || !exactIso(value.updatedAt))
+        throw new TasksFileError("TASKS_INVALID_TASK", `tasks[${index}] timestamps are invalid`);
+    if (value.completedAt !== undefined && !exactIso(value.completedAt))
+        throw new TasksFileError("TASKS_INVALID_TASK", `tasks[${index}].completedAt is invalid`);
+    if (value.status === "done" && value.completedAt === undefined)
+        throw new TasksFileError("TASKS_INVALID_TASK", `tasks[${index}] done status requires completedAt`);
+    if (value.status !== "done" && value.completedAt !== undefined)
+        throw new TasksFileError("TASKS_INVALID_TASK", `tasks[${index}] non-done status forbids completedAt`);
+    for (const [field, max] of [["description", 10000], ["ownerLabel", 120], ["source", 120], ["verify", 2000]]) {
+        if (value[field] !== undefined && !boundedText(value[field], max, true))
+            throw new TasksFileError("TASKS_INVALID_TASK", `tasks[${index}].${field} is invalid`);
+    }
+    return {
+        id: value.id,
+        title,
+        ...(value.description !== undefined ? { description: value.description } : {}),
+        status: value.status,
+        priority: value.priority,
+        owner: value.owner,
+        ...(value.ownerLabel !== undefined ? { ownerLabel: value.ownerLabel } : {}),
+        tags: [...value.tags],
+        ...(value.source !== undefined ? { source: value.source } : {}),
+        ...(value.verify !== undefined ? { verify: value.verify } : {}),
+        createdAt: value.createdAt,
+        updatedAt: value.updatedAt,
+        ...(value.completedAt !== undefined ? { completedAt: value.completedAt } : {}),
+    };
 }
-function normalizeTask(raw) {
-    const created = typeof raw.createdAt === "string" ? raw.createdAt : nowIso();
+function parseTasksJson(content, expectedProject) {
+    let value;
+    try {
+        value = JSON.parse(content);
+    }
+    catch {
+        throw new TasksFileError("TASKS_INVALID_JSON", "tasks.json is not valid JSON");
+    }
+    if (!isRecord(value))
+        throw new TasksFileError("TASKS_INVALID_DOCUMENT", "tasks.json must be an object");
+    assertNoUnknown(value, DOC_KEYS, "TASKS_INVALID_DOCUMENT", "tasks.json");
+    if (value.$schema !== exports.TASKS_SCHEMA)
+        throw new TasksFileError("TASKS_INVALID_SCHEMA", `expected ${exports.TASKS_SCHEMA}`);
+    if (typeof value.project !== "string" || !PROJECT_NAME.test(value.project))
+        throw new TasksFileError("TASKS_INVALID_DOCUMENT", "project is invalid");
+    if (expectedProject && value.project !== expectedProject)
+        throw new TasksFileError("TASKS_INVALID_DOCUMENT", `project must equal ${expectedProject}`);
+    if (!exactIso(value.updatedAt))
+        throw new TasksFileError("TASKS_INVALID_DOCUMENT", "updatedAt is invalid");
+    if (!Array.isArray(value.tasks) || value.tasks.length > 10000)
+        throw new TasksFileError("TASKS_INVALID_DOCUMENT", "tasks must be an array with at most 10000 rows");
+    if (value.notes !== undefined && !boundedText(value.notes, 100000, true))
+        throw new TasksFileError("TASKS_INVALID_DOCUMENT", "notes is invalid");
+    const tasks = value.tasks.map(parseTask);
+    const ids = tasks.map((task) => task.id);
+    if (new Set(ids).size !== ids.length)
+        throw new TasksFileError("TASKS_DUPLICATE_ID", "task ids must be unique");
     return {
-        id: typeof raw.id === "string" && raw.id ? raw.id : generateTaskId(),
-        title: String(raw.title || "").trim() || "(untitled)",
-        description: typeof raw.description === "string" ? raw.description : undefined,
-        status: normalizeStatus(raw.status),
-        priority: normalizePriority(raw.priority),
-        owner: raw.owner === "agent" ? "agent" : "human",
-        ownerLabel: typeof raw.ownerLabel === "string" ? raw.ownerLabel : undefined,
-        tags: Array.isArray(raw.tags) ? raw.tags.map(String) : [],
-        source: typeof raw.source === "string" ? raw.source : undefined,
-        verify: typeof raw.verify === "string" ? raw.verify : undefined,
-        createdAt: created,
-        updatedAt: typeof raw.updatedAt === "string" ? raw.updatedAt : created,
-        completedAt: typeof raw.completedAt === "string" ? raw.completedAt : undefined,
-        remoteId: typeof raw.remoteId === "string" ? raw.remoteId : undefined,
+        $schema: exports.TASKS_SCHEMA,
+        project: value.project,
+        updatedAt: value.updatedAt,
+        tasks,
+        ...(value.notes !== undefined ? { notes: value.notes } : {}),
     };
 }
-/** Parse a legacy freeform tasks.md checklist into task entries. */
+/** Legacy import is reviewable in memory; persistence still requires task_write. */
 function parseLegacyTasksMd(content, project) {
+    if (content.includes(GENERATED_MARKER) || ID_COMMENT.test(content)) {
+        throw new TasksFileError("TASKS_JSON_MISSING", "generated tasks.md exists without canonical tasks.json");
+    }
     const tasks = [];
-    const now = nowIso();
+    const timestamp = nowIso();
     const notes = [];
     let inNotes = false;
     for (const line of content.split(/\r?\n/)) {
@@ -126,32 +213,23 @@ function parseLegacyTasksMd(content, project) {
                 notes.push(line);
             continue;
         }
-        const bullet = line.match(/^\s*-\s*\[([ xX])\]\s+(.*)$/);
+        const bullet = line.match(/^\s*-\s*\[([ xX])\]\s+(.+)$/);
         if (!bullet)
             continue;
         const done = bullet[1].toLowerCase() === "x";
-        // Legacy entries are often paragraph-length; keep the first sentence as
-        // the title and the rest as description so nothing is lost.
         const text = bullet[2].trim();
         const splitAt = text.length > 160 ? text.indexOf(". ") : -1;
-        const title = splitAt > 0 ? text.slice(0, splitAt + 1) : text;
-        const description = splitAt > 0 ? text.slice(splitAt + 2) : undefined;
-        tasks.push(normalizeTask({
-            title,
-            description,
-            status: done ? "done" : "open",
-            source: "legacy-md",
-            createdAt: now,
-            completedAt: done ? now : undefined,
-        }));
+        tasks.push({
+            id: generateTaskId(), title: splitAt > 0 ? text.slice(0, splitAt + 1) : text,
+            ...(splitAt > 0 ? { description: text.slice(splitAt + 2) } : {}),
+            status: done ? "done" : "open", priority: "normal", owner: "human", tags: [], source: "legacy-md",
+            createdAt: timestamp, updatedAt: timestamp, ...(done ? { completedAt: timestamp } : {}),
+        });
     }
-    return {
-        $schema: exports.TASKS_SCHEMA,
-        project,
-        updatedAt: now,
-        tasks,
-        notes: notes.length ? notes.join("\n") : undefined,
-    };
+    return { $schema: exports.TASKS_SCHEMA, project, updatedAt: timestamp, tasks, ...(notes.length ? { notes: notes.join("\n") } : {}) };
+}
+function compareTask(a, b) {
+    return a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id);
 }
 function statusLabel(task) {
     const bits = [task.status];
@@ -160,147 +238,265 @@ function statusLabel(task) {
     if (task.owner === "agent")
         bits.push(task.ownerLabel ? `agent:${task.ownerLabel}` : "agent");
     if (task.tags.length)
-        bits.push(task.tags.map((t) => `#${t}`).join(" "));
+        bits.push(task.tags.map((tag) => `#${tag}`).join(" "));
     return bits.join(" · ");
 }
-/** Render tasks.md from the doc. Deterministic; safe to regenerate. */
 function renderTasksMd(doc) {
-    const active = doc.tasks.filter((t) => OPEN_STATUSES.includes(t.status));
-    const closed = doc.tasks.filter((t) => !OPEN_STATUSES.includes(t.status));
-    const lines = [
-        `# Tasks — ${doc.project}`,
-        "",
-        "<!-- generated from tasks.json (you-md/tasks/v1). Checkbox edits here sync back on next read;",
-        "     everything else regenerates. Freeform notes live between the notes markers below. -->",
-        "",
-        `## Active (${active.length})`,
-        "",
-    ];
-    for (const t of active) {
-        lines.push(`- [ ] ${t.title} <!-- id:${t.id} -->`);
-        lines.push(`      ${statusLabel(t)}`);
-        if (t.verify)
-            lines.push(`      verify: ${t.verify}`);
-        if (t.description)
-            lines.push(`      ${t.description}`);
+    const active = doc.tasks.filter((task) => OPEN_STATUSES.includes(task.status)).sort(compareTask);
+    const closed = doc.tasks.filter((task) => !OPEN_STATUSES.includes(task.status)).sort(compareTask);
+    const lines = [`# Tasks — ${doc.project}`, "", GENERATED_MARKER, "     regenerate with `you tasks`; manual changes are rejected. -->", "", `## Active (${active.length})`, ""];
+    for (const task of active) {
+        lines.push(`- [ ] ${task.title} <!-- id:${task.id} -->`, `      ${statusLabel(task)}`);
+        if (task.verify)
+            lines.push(`      verify: ${task.verify}`);
+        if (task.description)
+            lines.push(`      ${task.description}`);
     }
     lines.push("", `## Done (${closed.length})`, "");
-    for (const t of closed) {
-        const box = t.status === "done" ? "x" : " ";
-        const suffix = t.status === "done" ? "" : ` (${t.status})`;
-        lines.push(`- [${box}] ${t.title}${suffix} <!-- id:${t.id} -->`);
-    }
+    for (const task of closed)
+        lines.push(`- [${task.status === "done" ? "x" : " "}] ${task.title}${task.status === "done" ? "" : ` (${task.status})`} <!-- id:${task.id} -->`);
     lines.push("", NOTES_START, doc.notes || "", NOTES_END, "");
     return lines.join("\n");
 }
+function assertTasksMdMatches(doc, content) {
+    if (content !== renderTasksMd(doc))
+        throw new TasksFileError("TASKS_MD_DRIFT", "tasks.md differs from deterministic tasks.json rendering");
+}
 /**
- * Reconcile checkbox states in tasks.md back into the doc. Only the checkbox
- * is authoritative in md — a ticked box marks done, an unticked box on a
- * done/cancelled task reopens it. Returns the number of changed tasks.
+ * Pure migration utility retained for callers that explicitly review a legacy
+ * checkbox diff. Canonical reads never call this automatically: generated
+ * tasks.md drift is rejected until an approved tasks.json change is written.
  */
-function reconcileMdCheckboxes(doc, mdContent) {
-    const byId = new Map(doc.tasks.map((t) => [t.id, t]));
+function reconcileMdCheckboxes(doc, mdContent, now = new Date()) {
+    const byId = new Map(doc.tasks.map((task) => [task.id, task]));
     let changed = 0;
     for (const line of mdContent.split(/\r?\n/)) {
-        const bullet = line.match(/^\s*-\s*\[([ xX])\]\s+(.*)$/);
-        if (!bullet)
-            continue;
-        const idMatch = bullet[2].match(ID_COMMENT);
-        if (!idMatch)
-            continue;
-        const task = byId.get(idMatch[1]);
-        if (!task)
+        const bullet = line.match(/^\s*-\s*\[([ xX])\]\s+(.+)$/);
+        const id = bullet?.[2].match(ID_COMMENT)?.[1];
+        const task = id ? byId.get(id) : undefined;
+        if (!bullet || !task)
             continue;
         const checked = bullet[1].toLowerCase() === "x";
-        const isOpen = OPEN_STATUSES.includes(task.status);
-        if (checked && isOpen) {
+        if (checked && OPEN_STATUSES.includes(task.status)) {
             task.status = "done";
-            task.completedAt = nowIso();
-            task.updatedAt = nowIso();
+            task.completedAt = nowIso(now);
+            task.updatedAt = nowIso(now);
             changed += 1;
         }
         else if (!checked && task.status === "done") {
             task.status = "open";
             task.completedAt = undefined;
-            task.updatedAt = nowIso();
+            task.updatedAt = nowIso(now);
             changed += 1;
         }
     }
     return changed;
 }
-function extractNotes(mdContent) {
-    const start = mdContent.indexOf(NOTES_START);
-    const end = mdContent.indexOf(NOTES_END);
-    if (start === -1 || end === -1 || end <= start)
-        return undefined;
-    const notes = mdContent.slice(start + NOTES_START.length, end).trim();
-    return notes || undefined;
+function findGitRoot(start) {
+    let current = path.resolve(start);
+    while (true) {
+        const marker = path.join(current, ".git");
+        if (fs.existsSync(marker))
+            return current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+function assertNoSymlink(root, candidate) {
+    const relative = path.relative(root, candidate);
+    if (relative.startsWith("..") || path.isAbsolute(relative))
+        throw new TasksFileError("TASKS_SYMLINK_REFUSED", "path escapes repository root");
+    let current = root;
+    for (const segment of relative.split(path.sep).filter(Boolean)) {
+        current = path.join(current, segment);
+        let stat;
+        try {
+            stat = fs.lstatSync(current);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                continue;
+            throw error;
+        }
+        if (stat.isSymbolicLink())
+            throw new TasksFileError("TASKS_SYMLINK_REFUSED", `${path.relative(root, current)} is a symlink`);
+    }
+}
+function resolveTaskWriteGrant(contextDir) {
+    const repoRoot = findGitRoot(contextDir);
+    if (!repoRoot)
+        throw new TasksFileError("TASKS_WRITE_NOT_GRANTED", "task writes require a Git repository");
+    assertNoSymlink(repoRoot, contextDir);
+    const descriptorPath = path.join(repoRoot, ".you-project");
+    assertNoSymlink(repoRoot, descriptorPath);
+    let descriptor;
+    try {
+        descriptor = JSON.parse(fs.readFileSync(descriptorPath, "utf8"));
+    }
+    catch {
+        throw new TasksFileError("TASKS_WRITE_NOT_GRANTED", "a valid .you-project descriptor is required");
+    }
+    const writePolicy = isRecord(descriptor) && isRecord(descriptor.writePolicy) ? descriptor.writePolicy : null;
+    const taskWrite = writePolicy && isRecord(writePolicy.taskWrite) ? writePolicy.taskWrite : null;
+    if (!isRecord(descriptor) || descriptor.schemaVersion !== "you-md/project-brain/v1" || descriptor.kind !== "project"
+        || typeof descriptor.projectRef !== "string" || !PROJECT_REF.test(descriptor.projectRef)
+        || !taskWrite || taskWrite.enabled !== true || typeof taskWrite.artifactRef !== "string"
+        || !ARTIFACT_REF.test(taskWrite.artifactRef) || !Array.isArray(descriptor.artifacts)) {
+        throw new TasksFileError("TASKS_WRITE_NOT_GRANTED", ".you-project does not grant task_write");
+    }
+    const artifact = descriptor.artifacts.find((item) => isRecord(item) && item.artifactRef === taskWrite.artifactRef);
+    const artifactPath = path.relative(repoRoot, tasksJsonPath(contextDir)).split(path.sep).join("/");
+    if (!isRecord(artifact) || artifact.kind !== "tasks" || artifact.path !== artifactPath || artifact.writePolicy !== "task_write"
+        || artifact.owner !== "repository" || artifact.authority !== "canonical" || !SAFE_RELATIVE_PATH.test(artifactPath)) {
+        throw new TasksFileError("TASKS_WRITE_NOT_GRANTED", "task_write is not bound to this canonical tasks.json artifact");
+    }
+    return { projectRef: descriptor.projectRef, artifactRef: artifact.artifactRef, artifactPath, repoRoot };
+}
+function assertRegularOrMissing(root, filePath) {
+    assertNoSymlink(root, filePath);
+    try {
+        if (!fs.lstatSync(filePath).isFile())
+            throw new TasksFileError("TASKS_SYMLINK_REFUSED", `${path.basename(filePath)} is not a regular file`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+function writeSynced(filePath, content) {
+    const fd = fs.openSync(filePath, "wx", 0o600);
+    try {
+        fs.writeFileSync(fd, content, "utf8");
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
 }
-/**
- * Load the canonical task doc for a project-context directory.
- *
- * - tasks.json exists → parse it, then reconcile tasks.md checkbox edits.
- * - only a legacy tasks.md exists → import it (one-time migration).
- * - neither exists → fresh empty doc.
- */
 function readTasksDoc(contextDir, project) {
     const jsonPath = tasksJsonPath(contextDir);
     const mdPath = tasksMdPath(contextDir);
+    const repoRoot = findGitRoot(contextDir) ?? path.resolve(contextDir);
+    assertNoSymlink(repoRoot, contextDir);
+    assertRegularOrMissing(repoRoot, jsonPath);
+    assertRegularOrMissing(repoRoot, mdPath);
+    const tmpRoot = path.join(contextDir, ".tmp");
+    if (fs.existsSync(tmpRoot) && fs.readdirSync(tmpRoot).some((name) => name.startsWith("youmd-tasks-"))) {
+        throw new TasksFileError("TASKS_WRITE_INCOMPLETE", "an interrupted task-ledger transaction requires recovery by the next granted write");
+    }
     if (fs.existsSync(jsonPath)) {
-        let parsed;
+        const doc = parseTasksJson(fs.readFileSync(jsonPath, "utf8"), project);
+        if (!fs.existsSync(mdPath))
+            throw new TasksFileError("TASKS_MD_MISSING", "tasks.md is missing");
+        assertTasksMdMatches(doc, fs.readFileSync(mdPath, "utf8"));
+        return { doc, migrated: false, reconciled: 0 };
+    }
+    if (fs.existsSync(mdPath))
+        return { doc: parseLegacyTasksMd(fs.readFileSync(mdPath, "utf8"), project), migrated: true, reconciled: 0 };
+    return { doc: { $schema: exports.TASKS_SCHEMA, project, updatedAt: nowIso(), tasks: [] }, migrated: false, reconciled: 0 };
+}
+function writeTasksDoc(contextDir, input, options = {}) {
+    const grant = resolveTaskWriteGrant(contextDir);
+    fs.mkdirSync(contextDir, { recursive: true, mode: 0o755 });
+    assertNoSymlink(grant.repoRoot, contextDir);
+    const jsonPath = tasksJsonPath(contextDir);
+    const mdPath = tasksMdPath(contextDir);
+    assertRegularOrMissing(grant.repoRoot, jsonPath);
+    assertRegularOrMissing(grant.repoRoot, mdPath);
+    const doc = { ...input, updatedAt: nowIso(options.now), tasks: input.tasks.map((task) => ({ ...task, tags: [...task.tags] })) };
+    const json = JSON.stringify(doc, null, 2) + "\n";
+    const validated = parseTasksJson(json, input.project);
+    const markdown = renderTasksMd(validated);
+    const tmpRoot = path.join(contextDir, ".tmp");
+    assertNoSymlink(grant.repoRoot, tmpRoot);
+    fs.mkdirSync(tmpRoot, { recursive: true, mode: 0o700 });
+    const lockPath = path.join(tmpRoot, "youmd-tasks-write.lock");
+    let lockFd;
+    try {
+        lockFd = fs.openSync(lockPath, "wx", 0o600);
+    }
+    catch {
+        throw new TasksFileError("TASKS_WRITE_BUSY", "another task-ledger write is active");
+    }
+    const txn = path.join(tmpRoot, `youmd-tasks-${crypto.randomBytes(8).toString("hex")}`);
+    fs.mkdirSync(txn, { mode: 0o700 });
+    const newJson = path.join(txn, "tasks.json.new");
+    const newMd = path.join(txn, "tasks.md.new");
+    const oldJson = path.join(txn, "tasks.json.old");
+    const oldMd = path.join(txn, "tasks.md.old");
+    const hadJson = fs.existsSync(jsonPath);
+    const hadMd = fs.existsSync(mdPath);
+    try {
+        writeSynced(newJson, json);
+        writeSynced(newMd, markdown);
+        if (hadJson)
+            fs.copyFileSync(jsonPath, oldJson, fs.constants.COPYFILE_EXCL);
+        if (hadMd)
+            fs.copyFileSync(mdPath, oldMd, fs.constants.COPYFILE_EXCL);
+        assertRegularOrMissing(grant.repoRoot, jsonPath);
+        assertRegularOrMissing(grant.repoRoot, mdPath);
+        fs.renameSync(newJson, jsonPath);
+        if (options.faultAfterJson)
+            throw new Error("faultAfterJson");
+        fs.renameSync(newMd, mdPath);
+        fs.chmodSync(jsonPath, 0o644);
+        fs.chmodSync(mdPath, 0o644);
+        input.updatedAt = validated.updatedAt;
+    }
+    catch (error) {
         try {
-            parsed = JSON.parse(fs.readFileSync(jsonPath, "utf-8"));
+            if (hadJson && fs.existsSync(oldJson))
+                fs.copyFileSync(oldJson, jsonPath);
+            else if (!hadJson && fs.existsSync(jsonPath))
+                fs.unlinkSync(jsonPath);
+            if (hadMd && fs.existsSync(oldMd))
+                fs.copyFileSync(oldMd, mdPath);
+            else if (!hadMd && fs.existsSync(mdPath))
+                fs.unlinkSync(mdPath);
         }
         catch {
-            parsed = {};
-        }
-        const rawTasks = Array.isArray(parsed.tasks) ? parsed.tasks : [];
-        const doc = {
-            $schema: exports.TASKS_SCHEMA,
-            project: typeof parsed.project === "string" && parsed.project ? parsed.project : project,
-            updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : nowIso(),
-            tasks: rawTasks.map(normalizeTask),
-            notes: typeof parsed.notes === "string" ? parsed.notes : undefined,
-        };
-        let reconciled = 0;
-        if (fs.existsSync(mdPath)) {
-            const md = fs.readFileSync(mdPath, "utf-8");
-            reconciled = reconcileMdCheckboxes(doc, md);
-            const notes = extractNotes(md);
-            if (notes !== undefined)
-                doc.notes = notes;
+            throw new TasksFileError("TASKS_WRITE_INCOMPLETE", "task-ledger rollback failed; manual recovery required");
         }
-        return { doc, migrated: false, reconciled };
+        throw error;
     }
-    if (fs.existsSync(mdPath)) {
-        const doc = parseLegacyTasksMd(fs.readFileSync(mdPath, "utf-8"), project);
-        return { doc, migrated: true, reconciled: 0 };
+    finally {
+        try {
+            fs.rmSync(txn, { recursive: true, force: true });
+        }
+        catch { /* surfaced on next read */ }
+        try {
+            fs.closeSync(lockFd);
+        }
+        catch { /* no-op */ }
+        try {
+            fs.unlinkSync(lockPath);
+        }
+        catch { /* no-op */ }
     }
-    return {
-        doc: { $schema: exports.TASKS_SCHEMA, project, updatedAt: nowIso(), tasks: [] },
-        migrated: false,
-        reconciled: 0,
-    };
-}
-/** Write both files atomically-ish: json first (truth), then the md render. */
-function writeTasksDoc(contextDir, doc) {
-    fs.mkdirSync(contextDir, { recursive: true });
-    doc.updatedAt = nowIso();
-    fs.writeFileSync(tasksJsonPath(contextDir), JSON.stringify(doc, null, 2) + "\n", "utf-8");
-    fs.writeFileSync(tasksMdPath(contextDir), renderTasksMd(doc), "utf-8");
 }
 function addTask(doc, input) {
-    const task = normalizeTask({ ...input, createdAt: nowIso() });
+    const timestamp = nowIso();
+    const status = input.status ?? "open";
+    const task = {
+        id: input.id ?? generateTaskId(), title: input.title.trim(), ...(input.description ? { description: input.description } : {}),
+        status, priority: input.priority ?? "normal", owner: input.owner ?? "human", ...(input.ownerLabel ? { ownerLabel: input.ownerLabel } : {}),
+        tags: [...(input.tags ?? [])], ...(input.source ? { source: input.source } : {}), ...(input.verify ? { verify: input.verify } : {}),
+        createdAt: input.createdAt ?? timestamp, updatedAt: timestamp,
+        ...(status === "done" ? { completedAt: input.completedAt ?? timestamp } : {}),
+    };
+    parseTask(task, doc.tasks.length);
+    if (doc.tasks.some((existing) => existing.id === task.id))
+        throw new TasksFileError("TASKS_DUPLICATE_ID", `duplicate task id ${task.id}`);
     doc.tasks.push(task);
     return task;
 }
 function findTask(doc, idOrTitle) {
     const needle = idOrTitle.trim().toLowerCase();
-    return (doc.tasks.find((t) => t.id.toLowerCase() === needle) ||
-        doc.tasks.find((t) => t.title.toLowerCase() === needle) ||
-        doc.tasks.find((t) => t.title.toLowerCase().includes(needle)));
-}
-function openTasks(doc) {
-    return doc.tasks.filter((t) => OPEN_STATUSES.includes(t.status));
+    return doc.tasks.find((task) => task.id.toLowerCase() === needle)
+        || doc.tasks.find((task) => task.title.toLowerCase() === needle)
+        || doc.tasks.find((task) => task.title.toLowerCase().includes(needle));
 }
+function openTasks(doc) { return doc.tasks.filter((task) => OPEN_STATUSES.includes(task.status)); }
 //# sourceMappingURL=tasksFile.js.map