@aitne/daemon 0.1.7 → 0.1.9

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

@@ -0,0 +1,216 @@
+/**
+ * Frontmatter parser for the six-class vault contract
+ * (CONTEXT_VAULT_REDESIGN_PLAN.md §5).
+ *
+ * Parses the advisory `kind` / `authority` / `mutability` / `slug` / `title`
+ * fields from a Markdown file's YAML frontmatter and returns structured
+ * advisories that the daemon's write-step uses to log warnings.
+ *
+ * **Phase 1 contract (advisory only).** A missing or malformed field logs
+ * a warning and proceeds; nothing rejects the write. The Phase 2 cut-over
+ * is gated behind `runtimeSettings.contextVault.enforceFrontmatter` (not
+ * exposed yet) — when that lands, the same advisory shape will become a
+ * 4xx structured-error response.
+ *
+ * **Coexistence with `context-frontmatter.ts`.** The legacy validator
+ * (`type`, `owner`, `updated`, plus daily-skeleton / policy-file rules)
+ * is unchanged and remains the strict gate for the surfaces it already
+ * covers. The new parser is additive: it reads the new fields without
+ * interpreting the old ones, so a file can carry both shapes during the
+ * Phase 1 → Phase 2 transition. The single YAML extractor is shared via
+ * `readContextFrontmatterValues` so the two paths cannot diverge on what
+ * they consider "frontmatter."
+ */
+import { readContextFrontmatterValues } from "../context-frontmatter-extract.js";
+/** Class — top-level directory class in the six-class layout. */
+export const VAULT_FRONTMATTER_KINDS = [
+    "identity",
+    "state",
+    "plan",
+    "journal",
+    "knowledge",
+    "policy",
+];
+/** Authority — who owns the file. */
+export const VAULT_FRONTMATTER_AUTHORITIES = [
+    "user",
+    "agent",
+    "mixed",
+];
+/** Mutability — how writes are permitted to modify the file. */
+export const VAULT_FRONTMATTER_MUTABILITIES = [
+    "replace",
+    "patch",
+    "append",
+    "readonly",
+];
+const SLUG_RE = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+const SLUG_MAX_LENGTH = 128;
+/**
+ * Map from frontmatter `kind` value to its enforcing top-level directory.
+ * `plan` and `policy` are singular in frontmatter but plural in the path
+ * (`plans/`, `policies/`); the lookup is keyed by the frontmatter value.
+ */
+const KIND_TO_PATH_PREFIX = {
+    identity: "identity/",
+    state: "state/",
+    plan: "plans/",
+    journal: "journal/",
+    knowledge: "knowledge/",
+    policy: "policies/",
+};
+/**
+ * Parse the optional vault frontmatter from a Markdown file. Returns the
+ * parsed values plus a list of advisories that callers (the write-step
+ * chokepoint) translate into structured log warnings.
+ *
+ * `relativePath` is required so a stated `kind` can be cross-checked
+ * against the path's top-level directory. Pass the path the writer is
+ * targeting (e.g. `identity/profile.md`); the helper is a no-op for any
+ * non-`.md` path and for files that are out-of-scope per §5.3.
+ */
+export function parseVaultFrontmatter(content, relativePath) {
+    const result = {
+        values: {},
+        advisories: [],
+    };
+    if (!shouldParseVaultFrontmatter(relativePath))
+        return result;
+    const values = readContextFrontmatterValues(content);
+    if (values === null) {
+        result.advisories.push({
+            code: "missing_frontmatter",
+            message: `${relativePath} has no YAML frontmatter; vault contract requires \`kind\`, \`authority\`, \`mutability\`.`,
+        });
+        return result;
+    }
+    const kindRaw = values.kind;
+    if (!kindRaw) {
+        result.advisories.push({
+            code: "missing_kind",
+            message: `${relativePath} frontmatter missing \`kind\` (one of: ${VAULT_FRONTMATTER_KINDS.join(", ")}).`,
+        });
+    }
+    else if (!isKind(kindRaw)) {
+        result.advisories.push({
+            code: "invalid_kind",
+            message: `${relativePath} frontmatter \`kind: ${kindRaw}\` is not one of: ${VAULT_FRONTMATTER_KINDS.join(", ")}.`,
+        });
+    }
+    else {
+        result.values.kind = kindRaw;
+        const expectedPrefix = KIND_TO_PATH_PREFIX[kindRaw];
+        if (!relativePath.startsWith(expectedPrefix)) {
+            result.advisories.push({
+                code: "kind_path_mismatch",
+                message: `${relativePath} declares \`kind: ${kindRaw}\` but path does not begin with \`${expectedPrefix}\`.`,
+            });
+        }
+    }
+    const authorityRaw = values.authority;
+    if (!authorityRaw) {
+        result.advisories.push({
+            code: "missing_authority",
+            message: `${relativePath} frontmatter missing \`authority\` (one of: ${VAULT_FRONTMATTER_AUTHORITIES.join(", ")}).`,
+        });
+    }
+    else if (!isAuthority(authorityRaw)) {
+        result.advisories.push({
+            code: "invalid_authority",
+            message: `${relativePath} frontmatter \`authority: ${authorityRaw}\` is not one of: ${VAULT_FRONTMATTER_AUTHORITIES.join(", ")}.`,
+        });
+    }
+    else {
+        result.values.authority = authorityRaw;
+    }
+    const mutabilityRaw = values.mutability;
+    if (!mutabilityRaw) {
+        result.advisories.push({
+            code: "missing_mutability",
+            message: `${relativePath} frontmatter missing \`mutability\` (one of: ${VAULT_FRONTMATTER_MUTABILITIES.join(", ")}).`,
+        });
+    }
+    else if (!isMutability(mutabilityRaw)) {
+        result.advisories.push({
+            code: "invalid_mutability",
+            message: `${relativePath} frontmatter \`mutability: ${mutabilityRaw}\` is not one of: ${VAULT_FRONTMATTER_MUTABILITIES.join(", ")}.`,
+        });
+    }
+    else {
+        result.values.mutability = mutabilityRaw;
+    }
+    const slugRaw = values.slug;
+    if (slugRaw) {
+        if (slugRaw.length > SLUG_MAX_LENGTH || !SLUG_RE.test(slugRaw)) {
+            result.advisories.push({
+                code: "invalid_slug",
+                message: `${relativePath} frontmatter \`slug: ${slugRaw}\` must be kebab-case (a-z, 0-9, hyphen), 1-${SLUG_MAX_LENGTH} chars, no leading/trailing hyphen.`,
+            });
+        }
+        else {
+            result.values.slug = slugRaw;
+        }
+    }
+    const titleRaw = values.title;
+    if (titleRaw) {
+        result.values.title = titleRaw;
+    }
+    return result;
+}
+/**
+ * The set of writeable vault paths whose frontmatter the new parser
+ * advises on. Phase 1 scope: any `.md` file under one of the six class
+ * directories OR a legacy top-level path that still maps cleanly under
+ * the upcoming layout (so the alias resolver in PR-3 transparently
+ * routes both). `_index.md` files are excluded — they are
+ * machine-rebuilt or user-curated navigation, not authored content.
+ */
+export function shouldParseVaultFrontmatter(relativePath) {
+    if (!relativePath.endsWith(".md"))
+        return false;
+    if (relativePath.endsWith("/_index.md"))
+        return false;
+    if (relativePath === "_index.md")
+        return false;
+    // New six-class prefixes (the layout PR-3 lands).
+    for (const prefix of Object.values(KIND_TO_PATH_PREFIX)) {
+        if (relativePath.startsWith(prefix))
+            return true;
+    }
+    // Legacy prefixes that map 1:1 under the new layout. The advisory still
+    // applies pre-migration so authors writing new content during the
+    // transition can opt into the new fields early.
+    const legacyPrefixes = [
+        "user/",
+        "rules/",
+        "routines/",
+        "projects/",
+        "daily/",
+        "weekly/",
+        "monthly/",
+        "dossiers/",
+        "inbox/",
+        "agent/",
+        "git/",
+    ];
+    for (const prefix of legacyPrefixes) {
+        if (relativePath.startsWith(prefix))
+            return true;
+    }
+    // Loose top-level files that pass through the rewriter.
+    if (relativePath === "today.md" ||
+        relativePath === "yesterday.md" ||
+        relativePath === "roadmap.md") {
+        return true;
+    }
+    return false;
+}
+function isKind(value) {
+    return VAULT_FRONTMATTER_KINDS.includes(value);
+}
+function isAuthority(value) {
+    return VAULT_FRONTMATTER_AUTHORITIES.includes(value);
+}
+function isMutability(value) {
+    return VAULT_FRONTMATTER_MUTABILITIES.includes(value);
+}

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";
+export { parseVaultFrontmatter, shouldParseVaultFrontmatter, VAULT_FRONTMATTER_AUTHORITIES, VAULT_FRONTMATTER_KINDS, VAULT_FRONTMATTER_MUTABILITIES, type VaultFrontmatter, type VaultFrontmatterAdvisory, type VaultFrontmatterAdvisoryCode, type VaultFrontmatterAuthority, type VaultFrontmatterKind, type VaultFrontmatterMutability, type VaultFrontmatterParseResult, } from "./frontmatter.js";

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";
+export { parseVaultFrontmatter, shouldParseVaultFrontmatter, VAULT_FRONTMATTER_AUTHORITIES, VAULT_FRONTMATTER_KINDS, VAULT_FRONTMATTER_MUTABILITIES, } from "./frontmatter.js";

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

@@ -0,0 +1,94 @@
+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)
+ *   - `policies/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;
+};

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

@@ -0,0 +1,145 @@
+import { parseCustomRoutineSpec } from "../custom-routine-scheduler.js";
+import { validateContextFileFrontmatter } from "../context-frontmatter.js";
+import { isAgentDefinitionPath, validateAgentDefinitionMarkdown, } from "../agents/validate-agent-md.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)
+ *   - `policies/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 === "state/today") {
+        const message = validateTodayContent(content, {
+            allowLegacyToday: options?.allowLegacyToday ?? false,
+            expectedAgentDay: options?.expectedAgentDay,
+        });
+        return message ? { message, status: 400 } : null;
+    }
+    if (target.base === "plans/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("policies/routines/custom/")) {
+        const slug = target.base.slice("policies/routines/custom/".length);
+        const result = parseCustomRoutineSpec(slug, content);
+        if (!result.ok) {
+            return {
+                message: explainCustomRoutineValidationError(result.error),
+                status: 400,
+            };
+        }
+        return null;
+    }
+    if (target.base.startsWith("policies/routines/") && target.base !== "policies/routines/_index") {
+        const message = validateBuiltInRoutineRulebook(target.base, content);
+        return message ? { message, status: 400 } : null;
+    }
+    const relativePath = `${target.base}${target.ext}`;
+    // policies/agents/<slug>/agent.md — user Agent definitions are written
+    // through this same chokepoint (AGENT_DEFINITIONS_DESIGN.md §3.3). Their
+    // frontmatter is the nested `agentDefinitionSchema`, not the context-vault
+    // rule schema, so validate the agent-definition shape here (400 with the
+    // offending fields) instead of falling through to the generic frontmatter
+    // validator — which would wrongly demand `type`/`owner`/`updated`.
+    if (isAgentDefinitionPath(relativePath)) {
+        const message = validateAgentDefinitionMarkdown(relativePath, content);
+        return message ? { message, status: 400 } : null;
+    }
+    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 !== "plans/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}`;
+}

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

@@ -0,0 +1,59 @@
+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 (`policies/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 `plans/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;