@aitne/daemon 0.1.7 → 0.1.8

package/dist/core/context-validation/_pa_wip_context_validation/today.js

@@ -0,0 +1,162 @@
+import { nowInTimezone } from "@aitne/shared";
+import { extractTodayAgentPlanRows, } from "../today-agent-plan.js";
+/**
+ * Validators and shape helpers for the `today.md` context file.
+ *
+ * `today.md` is the agent's daily working surface. Its line-1 header is
+ * the canonical agent-day date; its `## Agent Plan` rows feed the
+ * scheduler that fires `→DM` / `→notify` / `→check-in` / `→wake` actions
+ * at their listed times. Both halves are parsed by every downstream
+ * event handler, so the schema is enforced server-side at write time
+ * with explicit messages that the agent can self-correct from.
+ */
+/**
+ * Canonical `## ` section headers, in document order. The validator
+ * walks the file once and requires each to appear after the previous
+ * one — extra sections may sit between them but the relative order is
+ * fixed.
+ */
+export const TODAY_REQUIRED_SECTIONS = [
+    "User Schedule",
+    "User Tasks",
+    "Agent Plan",
+    "Agent Notes",
+    "Agent Log",
+    "Handoff",
+];
+/**
+ * Line 1: `# YYYY-MM-DD (day-of-week)`. Date and dashes are ASCII;
+ * only the optional `(...)` weekday may be localized into the user's
+ * primary language. The capture group is consulted to compare against
+ * the current agent-day date when the route handler passes
+ * `expectedAgentDay`.
+ */
+export const TODAY_H1_RE = /^# \d{4}-\d{2}-\d{2}(?: \([^)]+\))?$/;
+/**
+ * Line 2: `> Day type: Weekday|Weekend | Work focus: on|off | …`.
+ * This line is parsed by every event handler — keep the casing,
+ * pipe separators, and `> ` prefix exact ASCII.
+ */
+export const TODAY_DAY_TYPE_RE = /^> Day type: (Weekday|Weekend) \| Work focus: (on|off) \| Study focus: (on|off) \| Personal focus: (on|off)$/;
+/**
+ * Pre-schema legacy form — first line literally `# Today`. Recognized
+ * only when the route handler explicitly opts in via
+ * `allowLegacyToday`; used to bridge old fixtures during reload paths
+ * that don't carry the agent-day context.
+ */
+export function isLegacyTodayContent(content) {
+    const lines = content.split(/\r?\n/);
+    return (lines[0] ?? "").trim() === "# Today";
+}
+/**
+ * Validate a `today.md` payload for the canonical schema.
+ *
+ * Returns a human-readable error message string, or `null` if the
+ * content is valid. The caller maps `null` to 200 and any string to
+ * 400. Messages echo both the expected and observed shape so the
+ * agent gets immediate feedback and can correct the offending line in
+ * the same session — see EXECUTION-MODE-DESIGN follow-up
+ * §morning-routine for the rationale.
+ */
+export 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;
+}
+/**
+ * Project a raw `agent_schedule` row into a `today.md`-reconciliation
+ * candidate: derive the local date/time in the caller's timezone, lift
+ * the task-context blob into an object, and surface the canonical row
+ * id so the route handler can correlate against parsed Agent Plan rows.
+ *
+ * Returns `null` for rows with an unparseable `scheduled_for`, so the
+ * caller can `.filter(Boolean)` past corrupt timestamps without
+ * crashing the reconciliation pass.
+ */
+export 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 {};
+}
+//# sourceMappingURL=today.js.map

package/dist/core/context-validation/_pa_wip_context_validation/today.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"today.js","sourceRoot":"","sources":["../../../../src/core/context-validation/_pa_wip_context_validation/today.ts"],"names":[],"mappings":"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"}

package/dist/core/context-validation/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Context-file write-path validators, extracted from the inline
+ * implementation that used to live in `api/routes/context.ts`.
+ *
+ * Split per `docs/design/appendices/api-route-decomposition.md` §5.3
+ * (PR 3) so the route file holds routing + permission gating only and
+ * each validator gets its own dedicated unit-test file.
+ *
+ * Every export here is a pure function or shape type — no Hono, no
+ * filesystem, no DB. The route handler composes them; consumers
+ * (snapshot restore preflight, future migration tools) can also import
+ * them directly without dragging in route-layer dependencies.
+ */
+export { normalizeSection, findSection, sumLength, getAvailableSections, } from "./section.js";
+export { SNAPSHOT_DEBOUNCE_MS, parseEntryTimestamp, clearEntriesBefore, trimBulletEntries, } from "./snapshot-debounce.js";
+export { validateBuiltInRoutineRulebook, explainCustomRoutineValidationError, extractRoutineFrontmatter, readRoutineFrontmatterScalar, validateBaseYamlSyntax, } from "./routine-rulebook.js";
+export { TODAY_REQUIRED_SECTIONS, TODAY_H1_RE, TODAY_DAY_TYPE_RE, isLegacyTodayContent, validateTodayContent, toTodayScheduleCandidate, type TodayScheduleCandidate, type AgentPlanScheduleCandidate, } from "./today.js";
+export { validateContextContent, prepareContextContentForWrite, type ResolvedContextTarget, type ContentWriteValidationOptions, type ContextContentValidationError, } from "./prepare-write.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/context-validation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/context-validation/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,SAAS,EACT,oBAAoB,GACrB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,8BAA8B,EAC9B,mCAAmC,EACnC,yBAAyB,EACzB,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,uBAAuB,EACvB,WAAW,EACX,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,wBAAwB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,0BAA0B,GAChC,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,sBAAsB,EACtB,6BAA6B,EAC7B,KAAK,qBAAqB,EAC1B,KAAK,6BAA6B,EAClC,KAAK,6BAA6B,GACnC,MAAM,oBAAoB,CAAC"}

package/dist/core/context-validation/index.js

@@ -0,0 +1,19 @@
+/**
+ * Context-file write-path validators, extracted from the inline
+ * implementation that used to live in `api/routes/context.ts`.
+ *
+ * Split per `docs/design/appendices/api-route-decomposition.md` §5.3
+ * (PR 3) so the route file holds routing + permission gating only and
+ * each validator gets its own dedicated unit-test file.
+ *
+ * Every export here is a pure function or shape type — no Hono, no
+ * filesystem, no DB. The route handler composes them; consumers
+ * (snapshot restore preflight, future migration tools) can also import
+ * them directly without dragging in route-layer dependencies.
+ */
+export { normalizeSection, findSection, sumLength, getAvailableSections, } from "./section.js";
+export { SNAPSHOT_DEBOUNCE_MS, parseEntryTimestamp, clearEntriesBefore, trimBulletEntries, } from "./snapshot-debounce.js";
+export { validateBuiltInRoutineRulebook, explainCustomRoutineValidationError, extractRoutineFrontmatter, readRoutineFrontmatterScalar, validateBaseYamlSyntax, } from "./routine-rulebook.js";
+export { TODAY_REQUIRED_SECTIONS, TODAY_H1_RE, TODAY_DAY_TYPE_RE, isLegacyTodayContent, validateTodayContent, toTodayScheduleCandidate, } from "./today.js";
+export { validateContextContent, prepareContextContentForWrite, } from "./prepare-write.js";
+//# sourceMappingURL=index.js.map

package/dist/core/context-validation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/context-validation/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,SAAS,EACT,oBAAoB,GACrB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,8BAA8B,EAC9B,mCAAmC,EACnC,yBAAyB,EACzB,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,uBAAuB,EACvB,WAAW,EACX,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,wBAAwB,GAGzB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,sBAAsB,EACtB,6BAA6B,GAI9B,MAAM,oBAAoB,CAAC"}

package/dist/core/context-validation/prepare-write.d.ts

@@ -0,0 +1,95 @@
+import type { LongTermPlanSource } from "../roadmap-horizon.js";
+/**
+ * Two-stage write-preparation pipeline for the `/api/context` PUT/PATCH
+ * routes.
+ *
+ * `validateContextContent` is the schema check — it dispatches by
+ * resolved target (today.md, roadmap.md, routine rulebooks, `.base`
+ * files, frontmatter-bearing markdown) and returns a typed error with
+ * the appropriate HTTP status (400 for content shape, 422 for
+ * frontmatter shape). It is exposed independently so callers that
+ * need to validate without normalizing (e.g. snapshot restore
+ * preflight) can use it directly.
+ *
+ * `prepareContextContentForWrite` is the full pipeline used by the
+ * write handlers — for `roadmap.md` it additionally normalizes
+ * Long-term Plans (adding default `source:` annotations, etc.) and
+ * runs a transition check against the previous content to enforce
+ * roadmap state-machine invariants. For every other target it
+ * delegates to `validateContextContent`.
+ */
+/**
+ * A user-supplied context path after extension extraction:
+ *
+ *   - `base` is the path without the trailing `.md` / `.base`
+ *   - `ext` records which extension was either supplied or chosen by
+ *     default (`.md`) or required (`.base` for the small set of
+ *     reserved YAML stems).
+ *
+ * Produced by the path-resolve layer (currently still in `context.ts`
+ * until the PR 4 split); referenced here because every validator
+ * dispatches on `target.base`.
+ */
+export interface ResolvedContextTarget {
+    base: string;
+    ext: ".md" | ".base";
+}
+export interface ContentWriteValidationOptions {
+    timezone?: string;
+    disableRoadmapValidation?: boolean;
+    previousRoadmapContent?: string;
+    today?: string;
+    defaultLongTermPlanSource?: LongTermPlanSource;
+    allowLegacyToday?: boolean;
+    skipFrontmatterValidation?: boolean;
+    /**
+     * Expected agent-day date (`YYYY-MM-DD`) for today.md line 1. When set,
+     * `validateTodayContent` returns a 400 with an error message that echoes
+     * both the written and the expected date string, so the agent can correct
+     * in the same session — see EXECUTION-MODE-DESIGN follow-up
+     * §morning-routine.
+     */
+    expectedAgentDay?: string;
+}
+export interface ContextContentValidationError {
+    message: string;
+    status: 400 | 422;
+    path?: string;
+}
+/**
+ * Schema-validate a context-file payload. Dispatches by resolved
+ * target:
+ *
+ *   - `today` → `validateTodayContent` (400)
+ *   - `roadmap` → `validateRoadmap` (400 with path hint)
+ *   - `routines/custom/*` → `parseCustomRoutineSpec` (400)
+ *   - `routines/*` (excluding `_index`) → `validateBuiltInRoutineRulebook` (400)
+ *   - everything else → frontmatter validation (422) + `.base` YAML check (400)
+ *
+ * Returns `null` if the payload is valid. The caller maps `null` to
+ * the success branch and the typed error to the matching HTTP status.
+ */
+export declare function validateContextContent(target: ResolvedContextTarget, content: string, options?: Pick<ContentWriteValidationOptions, "allowLegacyToday" | "skipFrontmatterValidation" | "expectedAgentDay">): ContextContentValidationError | null;
+/**
+ * Full write-pipeline preflight. For roadmap writes, normalizes the
+ * Long-term Plans section first (adding default `source:` annotations
+ * keyed off the caller — manual via DM vs. dashboard form), validates
+ * against the canonical schema, and runs an optional transition check
+ * against the previous content. For every other target, delegates to
+ * `validateContextContent`.
+ *
+ * Returns `{ ok: true, content }` where `content` may be the
+ * roadmap-normalized form (different from the input) or the verbatim
+ * input. On failure, returns `{ ok: false, status, message, path? }`
+ * suitable for the API error response.
+ */
+export declare function prepareContextContentForWrite(target: ResolvedContextTarget, content: string, options?: ContentWriteValidationOptions): {
+    ok: true;
+    content: string;
+} | {
+    ok: false;
+    message: string;
+    status: 400 | 422;
+    path?: string;
+};
+//# sourceMappingURL=prepare-write.d.ts.map

package/dist/core/context-validation/prepare-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepare-write.d.ts","sourceRoot":"","sources":["../../../src/core/context-validation/prepare-write.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAQhE;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,KAAK,GAAG,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yBAAyB,CAAC,EAAE,kBAAkB,CAAC;IAC/C,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,GAAG,GAAG,GAAG,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,qBAAqB,EAC7B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,IAAI,CACZ,6BAA6B,EAC7B,kBAAkB,GAAG,2BAA2B,GAAG,kBAAkB,CACtE,GACA,6BAA6B,GAAG,IAAI,CA8CtC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,qBAAqB,EAC7B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,6BAA6B,GAErC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC7B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,GAAG,GAAG,GAAG,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAuDnE"}

package/dist/core/context-validation/prepare-write.js

@@ -0,0 +1,135 @@
+import { parseCustomRoutineSpec } from "../custom-routine-scheduler.js";
+import { validateContextFileFrontmatter } from "../context-frontmatter.js";
+import { normalizeRoadmapForWrite, validateRoadmap, validateRoadmapTransition, } from "../roadmap-validate.js";
+import { explainCustomRoutineValidationError, validateBaseYamlSyntax, validateBuiltInRoutineRulebook, } from "./routine-rulebook.js";
+import { validateTodayContent } from "./today.js";
+/**
+ * Schema-validate a context-file payload. Dispatches by resolved
+ * target:
+ *
+ *   - `today` → `validateTodayContent` (400)
+ *   - `roadmap` → `validateRoadmap` (400 with path hint)
+ *   - `routines/custom/*` → `parseCustomRoutineSpec` (400)
+ *   - `routines/*` (excluding `_index`) → `validateBuiltInRoutineRulebook` (400)
+ *   - everything else → frontmatter validation (422) + `.base` YAML check (400)
+ *
+ * Returns `null` if the payload is valid. The caller maps `null` to
+ * the success branch and the typed error to the matching HTTP status.
+ */
+export 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;
+}
+/**
+ * Full write-pipeline preflight. For roadmap writes, normalizes the
+ * Long-term Plans section first (adding default `source:` annotations
+ * keyed off the caller — manual via DM vs. dashboard form), validates
+ * against the canonical schema, and runs an optional transition check
+ * against the previous content. For every other target, delegates to
+ * `validateContextContent`.
+ *
+ * Returns `{ ok: true, content }` where `content` may be the
+ * roadmap-normalized form (different from the input) or the verbatim
+ * input. On failure, returns `{ ok: false, status, message, path? }`
+ * suitable for the API error response.
+ */
+export 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) {
+    // `validateRoadmap` always supplies a line number for row-shape failures
+    // the route surfaces; the `error.line` falsy branch fires only for
+    // section-missing structural errors. The HTTP route tests exercise this
+    // indirectly; the dedicated unit-test fan-out is left to roadmap-validate.test.ts.
+    /* c8 ignore next */
+    const line = error.line ? `line ${error.line}: ` : "";
+    return `${line}${error.message}`;
+}
+//# sourceMappingURL=prepare-write.js.map

package/dist/core/context-validation/prepare-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepare-write.js","sourceRoot":"","sources":["../../../src/core/context-validation/prepare-write.ts"],"names":[],"mappings":"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"}

package/dist/core/context-validation/routine-rulebook.d.ts

@@ -0,0 +1,60 @@
+import type { CustomRoutineParseError } from "../custom-routine-scheduler.js";
+/**
+ * Pure validators for routine rulebooks and `.base` YAML files.
+ *
+ * Built-in routine rulebooks (`routines/*.md`, excluding `_index`) drive
+ * the morning / evening / weekly task-flow prompts and must declare the
+ * canonical frontmatter shape so the loader can dispatch by slug + type.
+ *
+ * Custom routines (`routines/custom/*.md`) are user-authored and parsed
+ * by `parseCustomRoutineSpec`; we only translate the structured error
+ * into a human-readable message here so the API can surface a 400
+ * response that the agent can self-correct from in-session.
+ *
+ * `.base` files (today: only `projects/_active.base`) carry the active
+ * project list as inline YAML. Validation is deliberately syntactic
+ * (no schema check) so the file can evolve without a daemon edit; the
+ * loader does the per-row validation when it parses.
+ */
+/**
+ * Validate the canonical built-in routine rulebook shape:
+ *   - YAML frontmatter present
+ *   - `type: rule`
+ *   - `slug` matches the filename (relative to `routines/`)
+ *   - `## Checks` section is present in the body
+ *
+ * Returns a human-readable error message string, or `null` if the file
+ * is valid. The caller maps `null` to 200 and any string to 400.
+ */
+export declare function validateBuiltInRoutineRulebook(path: string, content: string): string | null;
+/**
+ * Translate a structured `CustomRoutineParseError` from
+ * `parseCustomRoutineSpec` into a human-readable string suitable for
+ * the API error response.
+ */
+export declare function explainCustomRoutineValidationError(error: CustomRoutineParseError): string;
+/**
+ * Extract the YAML frontmatter body (without the `---` delimiters)
+ * from a markdown file, or return `null` if no frontmatter block is
+ * present at the start of the file. Accepts both LF and CRLF line
+ * endings on the opening delimiter so Windows-edited files do not
+ * round-trip as "no frontmatter".
+ */
+export declare function extractRoutineFrontmatter(content: string): string | null;
+/**
+ * Read a single top-level scalar field from a routine frontmatter
+ * block. Quoted strings (single or double) have the quotes stripped;
+ * everything else is returned trimmed verbatim. Returns `null` if the
+ * field is absent.
+ */
+export declare function readRoutineFrontmatterScalar(frontmatter: string, field: string): string | null;
+/**
+ * Syntactic gate for `.base` YAML context files.
+ *
+ * Only rejects files that are obviously broken — tabs in indentation,
+ * odd indent counts, non-mapping non-list lines. The schema check (what
+ * fields must be present) belongs in the loader; the API gate exists
+ * so that a malformed PATCH cannot wedge the project-list reader.
+ */
+export declare function validateBaseYamlSyntax(content: string): string | null;
+//# sourceMappingURL=routine-rulebook.d.ts.map

package/dist/core/context-validation/routine-rulebook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routine-rulebook.d.ts","sourceRoot":"","sources":["../../../src/core/context-validation/routine-rulebook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAE9E;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,MAAM,GAAG,IAAI,CA4Bf;AAED;;;;GAIG;AACH,wBAAgB,mCAAmC,CACjD,KAAK,EAAE,uBAAuB,GAC7B,MAAM,CAuBR;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQxE;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,GACZ,MAAM,GAAG,IAAI,CAYf;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAoCrE"}