@aitne/daemon 0.1.7 → 0.1.8

package/dist/api/routes/context.js

@@ -2,23 +2,23 @@ import { Hono } from "hono";
 import { readFileSync, existsSync, statSync, readdirSync, unlinkSync, realpathSync, lstatSync, readlinkSync, } from "node:fs";
 import { basename, join, dirname, resolve, relative, isAbsolute } from "node:path";
 import { writeFileAtomically } from "../../core/atomic-write.js";
-import { contextPutSchema, contextPatchSchema, getAgentDayDateStr, localDateStr, nowInTimezone, } from "@aitne/shared";
+import { contextPutSchema, contextPatchSchema, getAgentDayDateStr, localDateStr, } from "@aitne/shared";
 import { getContextDir } from "../../config.js";
 import { getDegradedMode } from "../../db/runtime-state.js";
 import { InMemoryTodayWriteLockManager, getTodayWriteLockTimeoutMs, } from "../../core/today-write-lock.js";
 import { InMemoryRoadmapWriteLockManager, getRoadmapWriteLockTimeoutMs, } from "../../core/roadmap-write-lock.js";
 import { CONTEXT_BASE_FILE_STEMS, CONTEXT_FILE_EXTENSIONS, } from "../../core/context-paths.js";
 import { REPAIRABLE_STUB_TARGETS, buildContextHealthReport, normalizeRepairStubPath, } from "../../core/context-health.js";
-import { validateContextFileFrontmatter } from "../../core/context-frontmatter.js";
+import { validateDailySkeletonFrontmatter } from "../../core/context-frontmatter.js";
 import { classifyContextWriteStaleness } from "../../core/context-staleness.js";
 import { resolveTemplatesRoot } from "../../core/skeleton.js";
-import { parseCustomRoutineSpec, } from "../../core/custom-routine-scheduler.js";
-import { normalizeRoadmapForWrite, validateRoadmap, validateRoadmapTransition, } from "../../core/roadmap-validate.js";
 import { isValidYmd, } from "../../core/roadmap-horizon.js";
 import { extractRoadmapIds, generateRoadmapId, RoadmapIdGenerationError, } from "../../core/roadmap-ids.js";
 import { buildTodayAgentPlanMetadata, extractTodayAgentPlanRows, extractTodayDate, readTodayAgentPlanMetadata, } from "../../core/today-agent-plan.js";
+import { SNAPSHOT_DEBOUNCE_MS, clearEntriesBefore, findSection, getAvailableSections, isLegacyTodayContent, prepareContextContentForWrite, toTodayScheduleCandidate, trimBulletEntries, validateContextContent, validateTodayContent, } from "../../core/context-validation/index.js";
 import { createLogger } from "../../logging.js";
 import { readJsonBody } from "../json-body.js";
+import { composeIssue, respondWithAgentError, } from "../helpers/agent-errors.js";
 const logger = createLogger("context-api");
 const CONTEXT_BASE_FILE_STEM_SET = new Set(CONTEXT_BASE_FILE_STEMS);
 function resolveContextTarget(userPath) {
@@ -311,140 +311,6 @@ function notifyPromptContextChanged(deps, path, reason, input) {
         logger.warn({ err, path, method: input.method }, "Failed to record context_write agent_actions row (Stage C metrics)");
     }
 }
-/**
- * Normalize a section name for matching:
- * lowercase, spaces → underscores, strip leading ##
- */
-function normalizeSection(name) {
-    return name
-        .replace(/^#+\s*/, "")
-        .toLowerCase()
-        .replace(/\s+/g, "_");
-}
-/**
- * Find a section in markdown content and return its boundaries.
- * Returns [startOfBody, endOfBody] where body is between this ## and next ##.
- */
-function findSection(content, sectionName) {
-    const normalized = normalizeSection(sectionName);
-    const lines = content.split("\n");
-    let sectionStart = -1;
-    let headerEnd = -1;
-    for (let i = 0; i < lines.length; i++) {
-        if (lines[i].startsWith("## ")) {
-            const lineNormalized = normalizeSection(lines[i]);
-            if (lineNormalized === normalized) {
-                sectionStart = i;
-                const lineStart = sumLength(lines, i);
-                const nlPos = content.indexOf("\n", lineStart);
-                // Handle file ending without trailing newline
-                headerEnd = nlPos === -1 ? content.length : nlPos + 1;
-                break;
-            }
-        }
-    }
-    if (sectionStart === -1)
-        return null;
-    // Find end: next ## header or EOF
-    let sectionEnd = content.length;
-    for (let i = sectionStart + 1; i < lines.length; i++) {
-        if (lines[i].startsWith("## ")) {
-            sectionEnd = sumLength(lines, i);
-            break;
-        }
-    }
-    return { start: headerEnd, end: sectionEnd, headerEnd };
-}
-function sumLength(lines, upToIndex) {
-    let len = 0;
-    for (let i = 0; i < upToIndex; i++) {
-        len += lines[i].length + 1; // +1 for \n
-    }
-    return len;
-}
-function getAvailableSections(content) {
-    return content
-        .split("\n")
-        .filter((l) => l.startsWith("## "))
-        .map((l) => normalizeSection(l));
-}
-/**
- * Parse a timestamp from a bullet entry like `- [2026-04-10 02:32:59] ...`
- * Returns the timestamp string or null if the line doesn't match.
- */
-const ENTRY_TIMESTAMP_RE = /^- \[(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})\]/;
-function parseEntryTimestamp(line) {
-    const match = ENTRY_TIMESTAMP_RE.exec(line);
-    return match ? match[1] : null;
-}
-/**
- * Remove entries whose `- [YYYY-MM-DD HH:MM:SS]` timestamp is ≤ cutoff.
- * Non-matching lines (blank lines, continuation lines) are preserved.
- * Returns the remaining section body and the count of removed entries.
- */
-function clearEntriesBefore(sectionBody, cutoff) {
-    const lines = sectionBody.split("\n");
-    const kept = [];
-    let removedCount = 0;
-    let skipContinuation = false;
-    for (const line of lines) {
-        const ts = parseEntryTimestamp(line);
-        if (ts !== null) {
-            // This is a timestamped entry
-            if (ts <= cutoff) {
-                removedCount++;
-                skipContinuation = true;
-                continue;
-            }
-            skipContinuation = false;
-            kept.push(line);
-        }
-        else if (skipContinuation && (line.startsWith("  ") || line.trim() === "")) {
-            // Continuation or trailing blank line of a removed entry
-            continue;
-        }
-        else {
-            skipContinuation = false;
-            kept.push(line);
-        }
-    }
-    return { remaining: kept.join("\n"), removedCount };
-}
-/**
- * Trim oldest bullet entries (`- ...` lines) from the top of a section
- * body to keep at most `maxEntries` entries. Non-bullet lines (blank
- * lines, non-`- ` prefixed lines) are preserved.
- */
-function trimBulletEntries(body, maxEntries) {
-    const lines = body.split("\n");
-    // Collect indices of bullet entry start lines
-    const bulletIndices = [];
-    for (let i = 0; i < lines.length; i++) {
-        if (lines[i].startsWith("- ")) {
-            bulletIndices.push(i);
-        }
-    }
-    const excess = bulletIndices.length - maxEntries;
-    if (excess <= 0) {
-        return { body, trimmed: 0 };
-    }
-    // Remove the oldest (topmost) `excess` entries and their continuations.
-    // Also remove blank lines between consecutive removed entries to avoid
-    // orphaned whitespace accumulating over many trim cycles.
-    const removeSet = new Set();
-    for (let i = 0; i < excess; i++) {
-        const start = bulletIndices[i];
-        const end = i + 1 < bulletIndices.length ? bulletIndices[i + 1] : lines.length;
-        for (let j = start; j < end; j++) {
-            if (j === start || lines[j].startsWith("  ") || lines[j].trim() === "") {
-                removeSet.add(j);
-            }
-        }
-    }
-    const kept = lines.filter((_, i) => !removeSet.has(i));
-    return { body: kept.join("\n"), trimmed: excess };
-}
-const SNAPSHOT_DEBOUNCE_MS = 5 * 60 * 1000; // 5 minutes
 /**
  * Cap on the JSON body accepted by the Context PUT/PATCH endpoints.
  *
@@ -494,12 +360,18 @@ export function createContextRoutes(deps) {
     app.use("/context/*", async (c, next) => {
         const state = getDegradedMode(db);
         if (state) {
-            return c.json({
-                error: "primary_vault_unreachable",
-                reason: state.reason,
-                path: state.path,
-                since: state.since,
-            }, 503);
+            return respondWithAgentError(c, 503, [
+                composeIssue("context.vault_unreachable", {
+                    field: "primaryVault",
+                    received: { reason: state.reason, path: state.path, since: state.since },
+                }),
+            ], {
+                legacyFields: {
+                    reason: state.reason,
+                    path: state.path,
+                    since: state.since,
+                },
+            });
         }
         // Phase 2 — global context-write gate engaged during a
         // /api/setup/migrate-context run. Refuses WRITES (not reads)
@@ -508,11 +380,17 @@ export function createContextRoutes(deps) {
         const writeMethods = new Set(["POST", "PUT", "PATCH", "DELETE"]);
         if (deps.contextWriteGate?.isEngaged() && writeMethods.has(c.req.method)) {
             const gateState = deps.contextWriteGate.getState();
-            return c.json({
-                error: "migration_in_progress",
-                reason: gateState.reason,
-                since: gateState.since,
-            }, 503);
+            return respondWithAgentError(c, 503, [
+                composeIssue("context.migration_in_progress", {
+                    field: "method",
+                    received: { method: c.req.method, reason: gateState.reason, since: gateState.since },
+                }),
+            ], {
+                legacyFields: {
+                    reason: gateState.reason,
+                    since: gateState.since,
+                },
+            });
         }
         await next();
     });
@@ -581,10 +459,12 @@ export function createContextRoutes(deps) {
             if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
                 return {
                     ok: false,
-                    response: c.json({
-                        error: "validation_error",
-                        message: "JSON body must be an object.",
-                    }, 400),
+                    response: respondWithAgentError(c, 400, [
+                        composeIssue("context.body_not_object", {
+                            field: "body",
+                            received: parsed === null ? "null" : Array.isArray(parsed) ? "array" : typeof parsed,
+                        }),
+                    ]),
                 };
             }
             return { ok: true, body: parsed };
@@ -594,7 +474,12 @@ export function createContextRoutes(deps) {
             logger.warn({ path: c.req.path, method: c.req.method, detail }, "Request rejected — body is not valid JSON");
             return {
                 ok: false,
-                response: c.json({ error: "invalid_json_body", message: detail }, 400),
+                response: respondWithAgentError(c, 400, [
+                    composeIssue("context.invalid_json_body", {
+                        field: "body",
+                        received: detail,
+                    }),
+                ]),
             };
         }
     }
@@ -603,7 +488,12 @@ export function createContextRoutes(deps) {
     app.post("/context/lock/morning-routine", (c) => {
         const result = morningRoutineLock.acquire();
         if (!result.ok) {
-            return c.json({ error: "lock_held", holder: result.holder }, 409);
+            return respondWithAgentError(c, 409, [
+                composeIssue("context.lock_held", {
+                    field: "morningRoutineLock",
+                    received: { holder: result.holder },
+                }),
+            ]);
         }
         return c.json({ status: "acquired", lockId: result.lockId });
     });
@@ -614,7 +504,12 @@ export function createContextRoutes(deps) {
         if (lockId && morningRoutineLock.release(lockId)) {
             return c.json({ status: "released" });
         }
-        return c.json({ error: "lock_not_held" }, 400);
+        return respondWithAgentError(c, 400, [
+            composeIssue("context.lock_not_held", {
+                field: "lockId",
+                received: lockId ?? "<missing>",
+            }),
+        ]);
     });
     // POST /context/lock/roadmap — Acquire exclusive roadmap write lock
     // Dispatcher auto-acquires this for `routine.roadmap_refresh`; other
@@ -623,7 +518,12 @@ export function createContextRoutes(deps) {
     app.post("/context/lock/roadmap", (c) => {
         const result = roadmapWriteLock.acquire();
         if (!result.ok) {
-            return c.json({ error: "roadmap_write_lock_held", holder: result.holder }, 409);
+            return respondWithAgentError(c, 409, [
+                composeIssue("context.roadmap_write_lock_held", {
+                    field: "roadmapWriteLock",
+                    received: { holder: result.holder },
+                }),
+            ]);
         }
         return c.json({ status: "acquired", lockId: result.lockId });
     });
@@ -634,7 +534,12 @@ export function createContextRoutes(deps) {
         if (lockId && roadmapWriteLock.release(lockId)) {
             return c.json({ status: "released" });
         }
-        return c.json({ error: "lock_not_held" }, 400);
+        return respondWithAgentError(c, 400, [
+            composeIssue("context.lock_not_held", {
+                field: "lockId",
+                received: lockId ?? "<missing>",
+            }),
+        ]);
     });
     // POST /context/roadmap/id — Mint a stable daemon-owned roadmap entry id.
     app.post("/context/roadmap/id", async (c) => {
@@ -642,7 +547,12 @@ export function createContextRoutes(deps) {
             const lockId = c.req.header("X-Lock-Id");
             if (!roadmapWriteLock.isHeldBy(lockId)) {
                 logger.info({ path: "roadmap" }, "Roadmap id mint rejected — roadmap write lock held");
-                return c.json({ error: "roadmap_write_lock_held" }, 409);
+                return respondWithAgentError(c, 409, [
+                    composeIssue("context.roadmap_write_lock_held", {
+                        field: "X-Lock-Id",
+                        received: lockId ?? "<missing>",
+                    }),
+                ]);
             }
         }
         const parsedBody = await readOptionalJsonBody(c);
@@ -653,16 +563,23 @@ export function createContextRoutes(deps) {
             ? requestedDate
             : localDateStr(new Date(), config.timezone || undefined);
         if (!isValidYmd(creationDate)) {
-            return c.json({
-                error: "validation_error",
-                message: "creationDate must be YYYY-MM-DD.",
-            }, 400);
+            return respondWithAgentError(c, 400, [
+                composeIssue("context.creation_date_invalid", {
+                    field: "creationDate",
+                    received: creationDate,
+                }),
+            ]);
         }
         return withWriteLock(() => {
             const contextDir = getCurrentContextDir();
             const fullPath = safePath(contextDir, "roadmap");
             if (!fullPath) {
-                return c.json({ error: "invalid_path", path: "roadmap" }, 400);
+                return respondWithAgentError(c, 400, [
+                    composeIssue("context.path_invalid", {
+                        field: "path",
+                        received: "roadmap",
+                    }),
+                ]);
             }
             const content = existsSync(fullPath)
                 ? readFileSync(fullPath, "utf-8")
@@ -679,7 +596,12 @@ export function createContextRoutes(deps) {
             }
             catch (err) {
                 if (err instanceof RoadmapIdGenerationError) {
-                    return c.json({ error: "roadmap_id_generation_failed" }, 503);
+                    return respondWithAgentError(c, 503, [
+                        composeIssue("context.roadmap_id_generation_failed", {
+                            field: "id",
+                            received: { existingIdCount: existingIds.length, creationDate },
+                        }),
+                    ]);
                 }
                 throw err;
             }
@@ -697,7 +619,12 @@ export function createContextRoutes(deps) {
             const contextDir = getCurrentContextDir();
             const todayPath = join(contextDir, "today.md");
             if (!existsSync(todayPath)) {
-                return c.json({ error: "not_found", path: "today" }, 404);
+                return respondWithAgentError(c, 404, [
+                    composeIssue("context.path_not_found", {
+                        field: "path",
+                        received: "today",
+                    }),
+                ]);
             }
             const content = readFileSync(todayPath, "utf-8");
             const dateStr = content.match(/^#.*(\d{4}-\d{2}-\d{2})/)?.[1] ??
@@ -720,46 +647,87 @@ export function createContextRoutes(deps) {
     // row back onto disk. The current on-disk file (if any) is snapshotted
     // first so the restore itself is reversible from the Knowledge page.
     app.post("/context/restore-snapshot/:id", (c) => {
-        const id = Number(c.req.param("id"));
+        const idRaw = c.req.param("id");
+        const id = Number(idRaw);
         if (!Number.isSafeInteger(id) || id <= 0) {
-            return c.json({ error: "invalid_id" }, 400);
+            return respondWithAgentError(c, 400, [
+                composeIssue("context.snapshot_id_invalid", {
+                    field: "id",
+                    received: idRaw,
+                }),
+            ]);
         }
         const row = db
             .prepare("SELECT id, file_path, content FROM md_file_snapshots WHERE id = ?")
             .get(id);
         if (!row) {
-            return c.json({ error: "not_found" }, 404);
+            return respondWithAgentError(c, 404, [
+                composeIssue("context.snapshot_not_found", {
+                    field: "id",
+                    received: id,
+                }),
+            ]);
         }
         const target = resolveContextTarget(row.file_path);
         const path = target.base;
         const contextDir = getCurrentContextDir();
         const fullPath = safePath(contextDir, row.file_path);
         if (!fullPath) {
-            return c.json({ error: "invalid_path", path }, 400);
+            return respondWithAgentError(c, 400, [
+                composeIssue("context.path_invalid", {
+                    field: "path",
+                    received: path,
+                }),
+            ]);
         }
         if (!isWriteAllowed(path, "PUT") && !isWriteAllowed(path, "PATCH")) {
             logger.warn({ path, method: "RESTORE" }, "Snapshot restore forbidden");
-            return c.json({ error: "forbidden", path, method: "RESTORE" }, 403);
+            return respondWithAgentError(c, 403, [
+                composeIssue("context.write_forbidden", {
+                    field: "path",
+                    received: { path, method: "RESTORE" },
+                }),
+            ]);
         }
         if (morningRoutineLock.getHolder() && path === "today") {
             const lockId = c.req.header("X-Lock-Id");
             if (!morningRoutineLock.isHeldBy(lockId)) {
                 logger.info({ path }, "Snapshot restore rejected — morning routine lock held");
-                return c.json({ error: "morning_routine_lock_held" }, 409);
+                return respondWithAgentError(c, 409, [
+                    composeIssue("context.morning_routine_lock_held", {
+                        field: "X-Lock-Id",
+                        received: lockId ?? "<missing>",
+                    }),
+                ]);
             }
         }
         if (roadmapWriteLock.getHolder() && path === "roadmap") {
             const lockId = c.req.header("X-Lock-Id");
             if (!roadmapWriteLock.isHeldBy(lockId)) {
                 logger.info({ path }, "Snapshot restore rejected — roadmap write lock held");
-                return c.json({ error: "roadmap_write_lock_held" }, 409);
+                return respondWithAgentError(c, 409, [
+                    composeIssue("context.roadmap_write_lock_held", {
+                        field: "X-Lock-Id",
+                        received: lockId ?? "<missing>",
+                    }),
+                ]);
             }
         }
         const contentError = validateContextContent(target, row.content, {
             skipFrontmatterValidation: true,
         });
         if (contentError) {
-            return c.json({ error: "validation_error", message: contentError.message }, contentError.status);
+            return respondWithAgentError(c, contentError.status, [
+                composeIssue("context.content_validation_failed", {
+                    field: contentError.path ?? "content",
+                    received: contentError.message,
+                }),
+            ], {
+                legacyFields: {
+                    message: contentError.message,
+                    path: contentError.path,
+                },
+            });
         }
         return withWriteLock(() => {
             let backupSnapshotId = null;
@@ -811,7 +779,12 @@ export function createContextRoutes(deps) {
             "inbox",
         ];
         if (!allowedDirs.includes(dir)) {
-            return c.json({ error: "invalid_directory", allowed: allowedDirs }, 400);
+            return respondWithAgentError(c, 400, [
+                composeIssue("context.directory_invalid", {
+                    field: "dir",
+                    received: { dir, allowed: allowedDirs },
+                }),
+            ]);
         }
         const contextDir = getCurrentContextDir();
         const dirPath = join(contextDir, dir);
@@ -908,10 +881,20 @@ export function createContextRoutes(deps) {
         const contextDir = getCurrentContextDir();
         const fullPath = safePath(contextDir, "today");
         if (!fullPath) {
-            return c.json({ error: "invalid_path", path: "today" }, 400);
+            return respondWithAgentError(c, 400, [
+                composeIssue("context.path_invalid", {
+                    field: "path",
+                    received: "today",
+                }),
+            ]);
         }
         if (!existsSync(fullPath)) {
-            return c.json({ error: "not_found", path: "today" }, 404);
+            return respondWithAgentError(c, 404, [
+                composeIssue("context.path_not_found", {
+                    field: "path",
+                    received: "today",
+                }),
+            ]);
         }
         const content = readFileSync(fullPath, "utf-8");
         const validationError = validateTodayContent(content);
@@ -1006,41 +989,57 @@ export function createContextRoutes(deps) {
             return parsedBody.response;
         const rawPath = parsedBody.body.path;
         if (typeof rawPath !== "string") {
-            return c.json({
-                error: "validation_error",
-                message: "path must be a string.",
-            }, 400);
+            return respondWithAgentError(c, 400, [
+                composeIssue("context.path_required", {
+                    field: "path",
+                    received: typeof rawPath,
+                }),
+            ], {
+                // repair-stub previously returned `error: "validation_error"` for
+                // the missing-path branch (not `"path_required"`); preserve that
+                // legacy alias so dashboard / older tests don't break.
+                legacyErrorCode: "validation_error",
+            });
         }
         const normalizedPath = normalizeRepairStubPath(rawPath);
         if (!normalizedPath || !REPAIRABLE_STUB_TARGETS.has(normalizedPath)) {
-            return c.json({
-                error: "unsupported_stub_target",
-                message: "Only known context stub targets can be repaired.",
-                path: rawPath,
-            }, 400);
+            return respondWithAgentError(c, 400, [
+                composeIssue("context.stub_target_unsupported", {
+                    field: "path",
+                    received: { path: rawPath, allowed: Array.from(REPAIRABLE_STUB_TARGETS) },
+                }),
+            ]);
         }
         const templatesRoot = resolveTemplatesRoot(config.workspaceDir);
         /* c8 ignore next 9 — resolveTemplatesRoot always succeeds via import.meta.url
          * fallback in tests; the 503 branch requires a broken install where the
          * agent-assets directory is absent from every candidate path. */
         if (!templatesRoot) {
-            return c.json({
-                error: "templates_unavailable",
-                message: "agent-assets/templates could not be located.",
-            }, 503);
+            return respondWithAgentError(c, 503, [
+                composeIssue("context.template_unavailable", {
+                    field: "templatesRoot",
+                    received: "<unresolved>",
+                }),
+            ]);
         }
         const templatePath = join(templatesRoot, normalizedPath);
         if (!existsSync(templatePath)) {
-            return c.json({
-                error: "template_not_found",
-                message: `No template exists for ${normalizedPath}.`,
-                path: normalizedPath,
-            }, 404);
+            return respondWithAgentError(c, 404, [
+                composeIssue("context.template_not_found", {
+                    field: "path",
+                    received: { path: normalizedPath, templatePath },
+                }),
+            ]);
         }
         const contextDir = getCurrentContextDir();
         const fullPath = safePath(contextDir, normalizedPath);
         if (!fullPath) {
-            return c.json({ error: "invalid_path", path: normalizedPath }, 400);
+            return respondWithAgentError(c, 400, [
+                composeIssue("context.path_invalid", {
+                    field: "path",
+                    received: normalizedPath,
+                }),
+            ]);
         }
         return withWriteLock(() => {
             if (existsSync(fullPath)) {
@@ -1077,16 +1076,31 @@ export function createContextRoutes(deps) {
     app.get("/context/*", (c) => {
         const rawPath = c.req.path.replace("/api/context/", "");
         if (!rawPath || rawPath === "list") {
-            return c.json({ error: "path_required" }, 400);
+            return respondWithAgentError(c, 400, [
+                composeIssue("context.path_required", {
+                    field: "path",
+                    received: rawPath === "list" ? "list (route ambiguous with /list/:dir)" : "<empty>",
+                }),
+            ]);
         }
         const path = normalizeContextPath(rawPath);
         const contextDir = getCurrentContextDir();
         const fullPath = safePath(contextDir, rawPath);
         if (!fullPath) {
-            return c.json({ error: "invalid_path", path }, 400);
+            return respondWithAgentError(c, 400, [
+                composeIssue("context.path_invalid", {
+                    field: "path",
+                    received: path,
+                }),
+            ]);
         }
         if (!existsSync(fullPath)) {
-            return c.json({ error: "not_found", path }, 404);
+            return respondWithAgentError(c, 404, [
+                composeIssue("context.path_not_found", {
+                    field: "path",
+                    received: path,
+                }),
+            ]);
         }
         const content = readFileSync(fullPath, "utf-8");
         const stat = statSync(fullPath);
@@ -1123,18 +1137,33 @@ export function createContextRoutes(deps) {
         const contextDir = getCurrentContextDir();
         const fullPath = safePath(contextDir, rawPath);
         if (!fullPath) {
-            return c.json({ error: "invalid_path", path }, 400);
+            return respondWithAgentError(c, 400, [
+                composeIssue("context.path_invalid", {
+                    field: "path",
+                    received: path,
+                }),
+            ]);
         }
         if (!isWriteAllowed(path, "PUT")) {
             logger.warn({ path, method: "PUT" }, "Context write forbidden");
-            return c.json({ error: "forbidden", path, method: "PUT" }, 403);
+            return respondWithAgentError(c, 403, [
+                composeIssue("context.write_forbidden", {
+                    field: "path",
+                    received: { path, method: "PUT" },
+                }),
+            ]);
         }
         // Morning Routine lock: reject writes to today while lock is held
         if (morningRoutineLock.getHolder() && path === "today") {
             const lockId = c.req.header("X-Lock-Id");
             if (!morningRoutineLock.isHeldBy(lockId)) {
                 logger.info({ path }, "Context PUT rejected — morning routine lock held");
-                return c.json({ error: "morning_routine_lock_held" }, 409);
+                return respondWithAgentError(c, 409, [
+                    composeIssue("context.morning_routine_lock_held", {
+                        field: "X-Lock-Id",
+                        received: lockId ?? "<missing>",
+                    }),
+                ]);
             }
         }
         // Roadmap write lock: reject writes to roadmap while another session holds it
@@ -1142,7 +1171,12 @@ export function createContextRoutes(deps) {
             const lockId = c.req.header("X-Lock-Id");
             if (!roadmapWriteLock.isHeldBy(lockId)) {
                 logger.info({ path }, "Context PUT rejected — roadmap write lock held");
-                return c.json({ error: "roadmap_write_lock_held" }, 409);
+                return respondWithAgentError(c, 409, [
+                    composeIssue("context.roadmap_write_lock_held", {
+                        field: "X-Lock-Id",
+                        received: lockId ?? "<missing>",
+                    }),
+                ]);
             }
         }
         const parsedBody = await readJsonBody(c, { maxBytes: CONTEXT_BODY_MAX_BYTES });
@@ -1151,7 +1185,12 @@ export function createContextRoutes(deps) {
         const body = parsedBody.body;
         const parsed = contextPutSchema.safeParse(body);
         if (!parsed.success) {
-            return c.json({ error: "validation_error", details: parsed.error }, 400);
+            return respondWithAgentError(c, 400, [
+                composeIssue("context.body_not_object", {
+                    field: "body",
+                    received: parsed.error.issues.map((i) => i.message).join("; "),
+                }),
+            ]);
         }
         const roadmapValidationOff = isRoadmapValidationDisabled(path, c.req.header("X-Roadmap-Validation"));
         if (roadmapValidationOff) {
@@ -1167,11 +1206,37 @@ export function createContextRoutes(deps) {
             expectedAgentDay,
         });
         if (!preflight.ok) {
-            return c.json({
-                error: "validation_error",
-                message: preflight.message,
-                path: preflight.path,
-            }, preflight.status);
+            return respondWithAgentError(c, preflight.status, [
+                composeIssue("context.content_validation_failed", {
+                    field: preflight.path ?? "content",
+                    received: preflight.message,
+                }),
+            ], {
+                legacyFields: {
+                    message: preflight.message,
+                    path: preflight.path,
+                },
+            });
+        }
+        // morning-routine-optimization.md §"PUT /api/context/daily/<date>
+        // skeleton-preservation validator" — only runs once generic
+        // frontmatter validation (type/owner/updated/H1) has passed.
+        // Returns per-field structured drift errors for the five
+        // skeleton-owned frontmatter fields (date, weekday,
+        // agent_generated, calendar_events, messages_handled) so Stage B
+        // can fix every missing/malformed field in a single retry rather
+        // than discovering them one at a time. Body is NOT validated —
+        // Stage B authors body per rules/journal-format.md.
+        if (target.base.startsWith("daily/")) {
+            const dailyRelativePath = `${target.base}${target.ext}`;
+            const driftErrors = validateDailySkeletonFrontmatter(preflight.content, dailyRelativePath);
+            if (driftErrors.length > 0) {
+                return respondWithAgentError(c, 422, driftErrors.map((drift) => composeIssue("context.daily_skeleton_field_drift", {
+                    field: drift.field,
+                    received: drift.received ?? "<missing>",
+                    expected: drift.expected,
+                })));
+            }
         }
         const sessionId = c.req.header("X-Session-Id");
         return withWriteLock(() => {
@@ -1182,11 +1247,12 @@ export function createContextRoutes(deps) {
             // outer existsSync check and then sequentially overwrite.
             if (CREATE_ONLY_PUT.has(path) && existsSync(fullPath)) {
                 logger.warn({ path }, "Context PUT rejected — file exists, use PATCH to append");
-                return c.json({
-                    error: "append_only",
-                    message: `${path} already exists. Use PATCH to append new sections.`,
-                    path,
-                }, 409);
+                return respondWithAgentError(c, 409, [
+                    composeIssue("context.append_only_violation", {
+                        field: "path",
+                        received: { path, hint: `Use PATCH to append new sections to ${path}.` },
+                    }),
+                ]);
             }
             // Optimistic concurrency check: if client supplied expectedMtime,
             // compare against the current file. On mismatch, return 409 with
@@ -1202,7 +1268,16 @@ export function createContextRoutes(deps) {
                     parsed.data.expectedMtime !== currentMtime) {
                     logger.info({ path, expectedMtime: parsed.data.expectedMtime, currentMtime }, "Context PUT conflict");
                     return c.json({
+                        ok: false,
                         error: "conflict",
+                        summary: `PUT conflict on ${path}: expectedMtime ${parsed.data.expectedMtime} did not match current ${currentMtime}. GET the file, replay your change, and retry.`,
+                        errors: [
+                            composeIssue("context.write_conflict", {
+                                field: "expectedMtime",
+                                received: { expectedMtime: parsed.data.expectedMtime, currentMtime },
+                            }),
+                        ],
+                        retryable: true,
                         currentMtime,
                         currentContent: existing,
                     }, 409);
@@ -1216,11 +1291,17 @@ export function createContextRoutes(deps) {
                     expectedAgentDay,
                 });
                 if (!prepared.ok) {
-                    return c.json({
-                        error: "validation_error",
-                        message: prepared.message,
-                        path: prepared.path,
-                    }, prepared.status);
+                    return respondWithAgentError(c, prepared.status, [
+                        composeIssue("context.content_validation_failed", {
+                            field: prepared.path ?? "content",
+                            received: prepared.message,
+                        }),
+                    ], {
+                        legacyFields: {
+                            message: prepared.message,
+                            path: prepared.path,
+                        },
+                    });
                 }
                 contentToWrite = prepared.content;
                 snapshotId = saveSnapshot(path, existing, "api_put", true, sessionId);
@@ -1228,7 +1309,16 @@ export function createContextRoutes(deps) {
             else if (parsed.data.expectedMtime !== undefined) {
                 // Client expected a specific mtime but the file is gone
                 return c.json({
+                    ok: false,
                     error: "conflict",
+                    summary: `PUT conflict on ${path}: expectedMtime ${parsed.data.expectedMtime} but file no longer exists.`,
+                    errors: [
+                        composeIssue("context.write_conflict", {
+                            field: "expectedMtime",
+                            received: { expectedMtime: parsed.data.expectedMtime, currentMtime: "" },
+                        }),
+                    ],
+                    retryable: true,
                     currentMtime: "",
                     currentContent: "",
                 }, 409);
@@ -1261,18 +1351,33 @@ export function createContextRoutes(deps) {
         const contextDir = getCurrentContextDir();
         const fullPath = safePath(contextDir, rawPath);
         if (!fullPath) {
-            return c.json({ error: "invalid_path", path }, 400);
+            return respondWithAgentError(c, 400, [
+                composeIssue("context.path_invalid", {
+                    field: "path",
+                    received: path,
+                }),
+            ]);
         }
         if (!isWriteAllowed(path, "PATCH")) {
             logger.warn({ path, method: "PATCH" }, "Context write forbidden");
-            return c.json({ error: "forbidden", path, method: "PATCH" }, 403);
+            return respondWithAgentError(c, 403, [
+                composeIssue("context.write_forbidden", {
+                    field: "path",
+                    received: { path, method: "PATCH" },
+                }),
+            ]);
         }
         // Morning Routine lock: reject writes to today while lock is held
         if (morningRoutineLock.getHolder() && path === "today") {
             const lockId = c.req.header("X-Lock-Id");
             if (!morningRoutineLock.isHeldBy(lockId)) {
                 logger.info({ path }, "Context PATCH rejected — morning routine lock held");
-                return c.json({ error: "morning_routine_lock_held" }, 409);
+                return respondWithAgentError(c, 409, [
+                    composeIssue("context.morning_routine_lock_held", {
+                        field: "X-Lock-Id",
+                        received: lockId ?? "<missing>",
+                    }),
+                ]);
             }
         }
         // Roadmap write lock: reject writes to roadmap while another session holds it
@@ -1280,7 +1385,12 @@ export function createContextRoutes(deps) {
             const lockId = c.req.header("X-Lock-Id");
             if (!roadmapWriteLock.isHeldBy(lockId)) {
                 logger.info({ path }, "Context PATCH rejected — roadmap write lock held");
-                return c.json({ error: "roadmap_write_lock_held" }, 409);
+                return respondWithAgentError(c, 409, [
+                    composeIssue("context.roadmap_write_lock_held", {
+                        field: "X-Lock-Id",
+                        received: lockId ?? "<missing>",
+                    }),
+                ]);
             }
         }
         const parsedBody = await readJsonBody(c, { maxBytes: CONTEXT_BODY_MAX_BYTES });
@@ -1289,13 +1399,20 @@ export function createContextRoutes(deps) {
         const body = parsedBody.body;
         const parsed = contextPatchSchema.safeParse(body);
         if (!parsed.success) {
-            return c.json({ error: "validation_error", details: parsed.error }, 400);
+            return respondWithAgentError(c, 400, [
+                composeIssue("context.body_not_object", {
+                    field: "body",
+                    received: parsed.error.issues.map((i) => i.message).join("; "),
+                }),
+            ]);
         }
         if (target.ext === ".base") {
-            return c.json({
-                error: "unsupported_operation",
-                message: "PATCH is not supported for .base files; use PUT to replace the file.",
-            }, 400);
+            return respondWithAgentError(c, 400, [
+                composeIssue("context.unsupported_operation", {
+                    field: "method",
+                    received: { method: "PATCH", ext: ".base", hint: "Use PUT to replace .base files." },
+                }),
+            ]);
         }
         const { section, mode, content: newContent, cutoff, maxEntries } = parsed.data;
         const sessionId = c.req.header("X-Session-Id");
@@ -1308,7 +1425,12 @@ export function createContextRoutes(deps) {
             : undefined;
         return withWriteLock(() => {
             if (!existsSync(fullPath)) {
-                return c.json({ error: "not_found", path }, 404);
+                return respondWithAgentError(c, 404, [
+                    composeIssue("context.path_not_found", {
+                        field: "path",
+                        received: path,
+                    }),
+                ]);
             }
             const fileContent = readFileSync(fullPath, "utf-8");
             // ── append_to_file: append content to end of file (no section lookup) ──
@@ -1329,11 +1451,17 @@ export function createContextRoutes(deps) {
                     expectedAgentDay,
                 });
                 if (!prepared.ok) {
-                    return c.json({
-                        error: "validation_error",
-                        message: prepared.message,
-                        path: prepared.path,
-                    }, prepared.status);
+                    return respondWithAgentError(c, prepared.status, [
+                        composeIssue("context.content_validation_failed", {
+                            field: prepared.path ?? "content",
+                            received: prepared.message,
+                        }),
+                    ], {
+                        legacyFields: {
+                            message: prepared.message,
+                            path: prepared.path,
+                        },
+                    });
                 }
                 saveSnapshot(path, fileContent, "api_patch", false, sessionId);
                 writeFileAtomically(fullPath, prepared.content);
@@ -1358,11 +1486,18 @@ export function createContextRoutes(deps) {
             // ── Section-based modes: require section lookup ──
             const sectionBounds = findSection(fileContent, section);
             if (!sectionBounds) {
-                return c.json({
-                    error: "section_not_found",
-                    section,
-                    availableSections: getAvailableSections(fileContent),
-                }, 400);
+                const availableSections = getAvailableSections(fileContent);
+                return respondWithAgentError(c, 400, [
+                    composeIssue("context.section_not_found", {
+                        field: "section",
+                        received: { section, availableSections },
+                    }),
+                ], {
+                    legacyFields: {
+                        section,
+                        availableSections,
+                    },
+                });
             }
             let updated;
             const before = fileContent.slice(0, sectionBounds.start);
@@ -1394,10 +1529,13 @@ export function createContextRoutes(deps) {
                     // Schema refinements validate format, but defense-in-depth for
                     // direct API callers that bypass schema validation.
                     if (!cutoff || !/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(cutoff)) {
-                        return c.json({
-                            error: "cutoff_required",
-                            message: "clear_before requires cutoff in 'YYYY-MM-DD HH:MM:SS' format (zero-padded)",
-                        }, 400);
+                        return respondWithAgentError(c, 400, [
+                            composeIssue("context.cutoff_required", {
+                                field: "cutoff",
+                                received: cutoff ?? "<missing>",
+                                expected: "'YYYY-MM-DD HH:MM:SS' format (zero-padded)",
+                            }),
+                        ]);
                     }
                     const clearResult = clearEntriesBefore(currentBody, cutoff);
                     updated = before + clearResult.remaining + after;
@@ -1415,11 +1553,17 @@ export function createContextRoutes(deps) {
                 expectedAgentDay,
             });
             if (!prepared.ok) {
-                return c.json({
-                    error: "validation_error",
-                    message: prepared.message,
-                    path: prepared.path,
-                }, prepared.status);
+                return respondWithAgentError(c, prepared.status, [
+                    composeIssue("context.content_validation_failed", {
+                        field: prepared.path ?? "content",
+                        received: prepared.message,
+                    }),
+                ], {
+                    legacyFields: {
+                        message: prepared.message,
+                        path: prepared.path,
+                    },
+                });
             }
             // Force snapshot on replace (bypass debounce) to ensure recovery
             // from accidental overwrites. Other modes use normal debounce.
@@ -1455,15 +1599,30 @@ export function createContextRoutes(deps) {
         const contextDir = getCurrentContextDir();
         const fullPath = safePath(contextDir, path);
         if (!fullPath) {
-            return c.json({ error: "invalid_path", path }, 400);
+            return respondWithAgentError(c, 400, [
+                composeIssue("context.path_invalid", {
+                    field: "path",
+                    received: path,
+                }),
+            ]);
         }
         if (!isWriteAllowed(path, "DELETE")) {
             logger.warn({ path, method: "DELETE" }, "Context delete forbidden");
-            return c.json({ error: "forbidden", path, method: "DELETE" }, 403);
+            return respondWithAgentError(c, 403, [
+                composeIssue("context.write_forbidden", {
+                    field: "path",
+                    received: { path, method: "DELETE" },
+                }),
+            ]);
         }
         return withWriteLock(() => {
             if (!existsSync(fullPath)) {
-                return c.json({ error: "not_found", path }, 404);
+                return respondWithAgentError(c, 404, [
+                    composeIssue("context.path_not_found", {
+                        field: "path",
+                        received: path,
+                    }),
+                ]);
             }
             const existing = readFileSync(fullPath, "utf-8");
             const snapshotId = saveSnapshot(path, existing, "api_delete", true);
@@ -1478,311 +1637,9 @@ export function createContextRoutes(deps) {
     });
     return app;
 }
-function validateContextContent(target, content, options) {
-    if (target.base === "today") {
-        const message = validateTodayContent(content, {
-            allowLegacyToday: options?.allowLegacyToday ?? false,
-            expectedAgentDay: options?.expectedAgentDay,
-        });
-        return message ? { message, status: 400 } : null;
-    }
-    if (target.base === "roadmap") {
-        const result = validateRoadmap(content);
-        if (!result.ok && result.error) {
-            return {
-                message: formatRoadmapValidationError(result.error),
-                status: 400,
-                path: result.error.path,
-            };
-        }
-        return null;
-    }
-    if (target.base.startsWith("routines/custom/")) {
-        const slug = target.base.slice("routines/custom/".length);
-        const result = parseCustomRoutineSpec(slug, content);
-        if (!result.ok) {
-            return {
-                message: explainCustomRoutineValidationError(result.error),
-                status: 400,
-            };
-        }
-        return null;
-    }
-    if (target.base.startsWith("routines/") && target.base !== "routines/_index") {
-        const message = validateBuiltInRoutineRulebook(target.base, content);
-        return message ? { message, status: 400 } : null;
-    }
-    const relativePath = `${target.base}${target.ext}`;
-    if (!options?.skipFrontmatterValidation) {
-        const frontmatterError = validateContextFileFrontmatter(content, relativePath);
-        if (frontmatterError) {
-            return { message: frontmatterError.message, status: 422 };
-        }
-    }
-    if (target.ext !== ".base")
-        return null;
-    const message = validateBaseYamlSyntax(content);
-    return message ? { message, status: 400 } : null;
-}
-const TODAY_REQUIRED_SECTIONS = [
-    "User Schedule",
-    "User Tasks",
-    "Agent Plan",
-    "Agent Notes",
-    "Agent Log",
-    "Handoff",
-];
-const TODAY_H1_RE = /^# \d{4}-\d{2}-\d{2}(?: \([^)]+\))?$/;
-const TODAY_DAY_TYPE_RE = /^> Day type: (Weekday|Weekend) \| Work focus: (on|off) \| Study focus: (on|off) \| Personal focus: (on|off)$/;
-function isLegacyTodayContent(content) {
-    const lines = content.split(/\r?\n/);
-    return (lines[0] ?? "").trim() === "# Today";
-}
-function validateTodayContent(content, options = {}) {
-    if (options.allowLegacyToday && isLegacyTodayContent(content))
-        return null;
-    const lines = content.split(/\r?\n/);
-    const firstLine = (lines[0] ?? "").trim();
-    if (!TODAY_H1_RE.test(firstLine)) {
-        return ("today.md line 1 must be `# YYYY-MM-DD (day-of-week)`. " +
-            "The date and dashes are ASCII English; only the weekday inside " +
-            "`(...)` may be localized. Do NOT translate the literal `# ` prefix " +
-            "or change the date separator. See the today skill for the full " +
-            "skeleton contract.");
-    }
-    if (!TODAY_DAY_TYPE_RE.test((lines[1] ?? "").trim())) {
-        return ("today.md line 2 must be `> Day type: Weekday|Weekend | Work focus: on|off | Study focus: on|off | Personal focus: on|off`. " +
-            "This line is parsed by every downstream event handler — keep it " +
-            "exact English ASCII with the casing, pipe separators (` | `), and " +
-            "leading `> ` shown above. Do NOT translate `Day type` / `Weekday` / " +
-            "`Work focus` / `on` / `off` etc. into the user's primary_language; " +
-            "the `<output_language_policy>` skeleton-precedence rule covers this " +
-            "line. Example: " +
-            "`> Day type: Weekday | Work focus: on | Study focus: on | Personal focus: on`.");
-    }
-    // Agent-day-date check — rejects wrong-date H1 with a clear error echoing
-    // both values. Without this, a wrong-date PUT silently succeeds (regex
-    // passes) and the dispatcher's post-run hasCurrentAgentDayTodayMd() check
-    // schedules a retry while the same session still has the prompt context
-    // loaded, wasting a heavy-tier turn cycle. With this guard the agent gets
-    // immediate feedback and corrects in-session.
-    if (options.expectedAgentDay) {
-        // TODAY_H1_RE already matched, so the YYYY-MM-DD capture is guaranteed.
-        // No optional-chain — the regex precondition guarantees `[1]` is set.
-        const writtenDate = firstLine.match(/^# (\d{4}-\d{2}-\d{2})/)[1];
-        if (writtenDate !== options.expectedAgentDay) {
-            return (`today.md line 1 date '${writtenDate}' does not match the current ` +
-                `agent-day date '${options.expectedAgentDay}'. ` +
-                `Use the date from <current_agent_day date="..."> in your prompt context — ` +
-                `the agent-day differs from calendar today before the day-boundary hour.`);
-        }
-    }
-    let previousSectionIndex = 1;
-    for (const section of TODAY_REQUIRED_SECTIONS) {
-        const index = lines.findIndex((line, lineIndex) => lineIndex > previousSectionIndex && line.trim() === `## ${section}`);
-        if (index < 0) {
-            return `today.md requires \`## ${section}\` in canonical order.`;
-        }
-        previousSectionIndex = index;
-    }
-    const parsed = extractTodayAgentPlanRows(content);
-    if (parsed.invalidRows.length > 0) {
-        const first = parsed.invalidRows[0];
-        return (`today.md Agent Plan line ${first.line} must match ` +
-            `\`- [ ] HH:MM <action> [work|study|personal|home] →DM|→notify|→check-in|→wake\`. ` +
-            `Got: ${JSON.stringify(first.raw)}`);
-    }
-    return null;
-}
-function toTodayScheduleCandidate(row, timezone) {
-    const scheduledAt = parseScheduleDate(row.scheduled_for);
-    if (Number.isNaN(scheduledAt.getTime()))
-        return null;
-    const local = nowInTimezone(timezone, scheduledAt);
-    const localDate = `${local.year}-${String(local.month).padStart(2, "0")}-${String(local.day).padStart(2, "0")}`;
-    const localTime = `${String(local.hours).padStart(2, "0")}:${String(local.minutes).padStart(2, "0")}`;
-    return {
-        id: row.id,
-        scheduledFor: row.scheduled_for,
-        localDate,
-        localTime,
-        taskType: row.task_type,
-        status: row.status,
-        description: row.task_description,
-        taskContext: parseJsonObject(row.task_context),
-    };
-}
-function parseScheduleDate(value) {
-    return new Date(value.includes("T") ? value : value.replace(" ", "T") + "Z");
-}
-function parseJsonObject(raw) {
-    if (!raw)
-        return {};
-    try {
-        const parsed = JSON.parse(raw);
-        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-            return parsed;
-        }
-    }
-    catch {
-        // Ignore corrupt metadata for reconciliation diagnostics.
-    }
-    return {};
-}
-function prepareContextContentForWrite(target, content, options) {
-    if (target.base !== "roadmap") {
-        const contentError = validateContextContent(target, content, {
-            allowLegacyToday: options?.allowLegacyToday,
-            expectedAgentDay: options?.expectedAgentDay,
-        });
-        if (contentError) {
-            return {
-                ok: false,
-                message: contentError.message,
-                status: contentError.status,
-                path: contentError.path,
-            };
-        }
-        return { ok: true, content };
-    }
-    if (options?.disableRoadmapValidation) {
-        return { ok: true, content };
-    }
-    const normalized = normalizeRoadmapForWrite(content, {
-        timezone: options?.timezone,
-        defaultLongTermPlanSource: options?.defaultLongTermPlanSource ?? "manual",
-    });
-    const result = validateRoadmap(normalized.content);
-    if (!result.ok && result.error) {
-        return {
-            ok: false,
-            message: formatRoadmapValidationError(result.error),
-            status: 400,
-            path: result.error.path,
-        };
-    }
-    if (options?.previousRoadmapContent !== undefined) {
-        const transition = validateRoadmapTransition(options.previousRoadmapContent, normalized.content, {
-            today: options.today,
-            timezone: options.timezone,
-        });
-        if (!transition.ok && transition.error) {
-            return {
-                ok: false,
-                message: formatRoadmapValidationError(transition.error),
-                status: 400,
-                path: transition.error.path,
-            };
-        }
-    }
-    return { ok: true, content: normalized.content };
-}
-function formatRoadmapValidationError(error) {
-    const line = error.line ? `line ${error.line}: ` : "";
-    return `${line}${error.message}`;
-}
-function validateBuiltInRoutineRulebook(path, content) {
-    const frontmatter = extractRoutineFrontmatter(content);
-    if (frontmatter === null) {
-        return "Routine rulebooks require YAML frontmatter.";
-    }
-    const expectedSlug = path.slice("routines/".length);
-    const typeRaw = readRoutineFrontmatterScalar(frontmatter, "type");
-    if (!typeRaw) {
-        return "Routine rulebooks require `type: rule` in frontmatter.";
-    }
-    if (typeRaw !== "rule") {
-        return "Routine rulebooks must declare `type: rule`.";
-    }
-    const slugRaw = readRoutineFrontmatterScalar(frontmatter, "slug");
-    if (!slugRaw) {
-        return "Routine rulebooks require a `slug` frontmatter field.";
-    }
-    if (slugRaw !== expectedSlug) {
-        return `Routine rulebook slug must match the filename (${expectedSlug}).`;
-    }
-    if (!/^##\s+Checks\s*$/m.test(content)) {
-        return "Routine rulebooks require a `## Checks` section.";
-    }
-    return null;
-}
-function explainCustomRoutineValidationError(error) {
-    switch (error.kind) {
-        case "missing_field":
-            return `Custom routine files require \`${error.field}\` in frontmatter.`;
-        case "invalid_cron":
-            return `Invalid cron expression: \`${error.value}\`.`;
-        case "invalid_slug":
-            return `Custom routine slug is invalid or does not match the filename: \`${error.value}\`.`;
-        case "invalid_type":
-            return `Custom routines must declare \`type: rule\`, got \`${error.value}\`.`;
-        case "invalid_process_key":
-            return `Custom routine \`process_key\` must match the filename-derived key, got \`${error.value}\`.`;
-        case "invalid_enabled":
-            return `Custom routine \`enabled\` must be \`true\` or \`false\`, got \`${error.value}\`.`;
-        case "invalid_tier":
-            return `Custom routine \`backend_tier\` must be \`light\` or \`heavy\`, got \`${error.value}\`.`;
-        case "invalid_budget":
-            return `Custom routine \`max_budget_usd\` must be a positive number, got \`${error.value}\`.`;
-        case "missing_checks_section":
-            return "Custom routines require a `## Checks` section.";
-        case "no_frontmatter":
-            return "Custom routines require YAML frontmatter.";
-    }
-}
-function extractRoutineFrontmatter(content) {
-    if (!content.startsWith("---\n") && !content.startsWith("---\r\n")) {
-        return null;
-    }
-    const afterOpen = content.startsWith("---\r\n") ? 5 : 4;
-    const endIdx = content.indexOf("\n---", afterOpen - 1);
-    if (endIdx < 0)
-        return null;
-    return content.slice(afterOpen, endIdx);
-}
-function readRoutineFrontmatterScalar(frontmatter, field) {
-    const re = new RegExp(`^${field}\\s*:\\s*(.+?)\\s*$`, "m");
-    const match = frontmatter.match(re);
-    if (!match)
-        return null;
-    let value = match[1].trim();
-    if ((value.startsWith('"') && value.endsWith('"')) ||
-        (value.startsWith("'") && value.endsWith("'"))) {
-        value = value.slice(1, -1);
-    }
-    return value;
-}
-function validateBaseYamlSyntax(content) {
-    if (content.trim().length === 0) {
-        return ".base files must not be empty.";
-    }
-    const lines = content.split("\n");
-    let sawMeaningfulLine = false;
-    for (let index = 0; index < lines.length; index++) {
-        const raw = lines[index];
-        const lineNo = index + 1;
-        if (raw.includes("\t")) {
-            return `.base YAML may not contain tab indentation (line ${lineNo}).`;
-        }
-        const trimmed = raw.trim();
-        if (!trimmed || trimmed.startsWith("#"))
-            continue;
-        sawMeaningfulLine = true;
-        const indent = raw.length - raw.trimStart().length;
-        if (indent % 2 !== 0) {
-            return `.base YAML uses 2-space indentation (line ${lineNo}).`;
-        }
-        const isListItem = /^-\s+\S/.test(trimmed);
-        const isMapping = /^[^:#][^:]*:\s*(?:.*)?$/.test(trimmed);
-        if (!isListItem && !isMapping) {
-            return `Invalid .base YAML structure on line ${lineNo}.`;
-        }
-    }
-    if (!sawMeaningfulLine) {
-        return ".base files must contain at least one mapping entry.";
-    }
-    return null;
-}
-// Export for testing
-export { normalizeSection, findSection, isWriteAllowed, safePath, resolveContextTarget, validateBaseYamlSyntax, validateTodayContent, clearEntriesBefore, trimBulletEntries, parseEntryTimestamp, };
+// Path/permission helpers stay test-exported until PR 4 moves them into
+// `routes/context/{path-resolve,permissions}.ts`. The validator surface
+// previously exported here now lives in `core/context-validation/` and
+// is tested at its source.
+export { isWriteAllowed, safePath, resolveContextTarget };
 //# sourceMappingURL=context.js.map