@aitne/daemon 0.1.7 → 0.1.9

package/dist/core/morning/parent-audit-emitter.d.ts

@@ -0,0 +1,80 @@
+/**
+ * `emitMorningRoutineParentAuditRow` — INSERT the parent
+ * `agent_actions` row keyed `action_type='routine.morning_routine'`,
+ * `result='success'`, with cost / turn sums across Stage A + Stage B.
+ *
+ * Spec: `docs/design/appendices/morning-routine-optimization.md`
+ * §"Daemon-side modules to add" → parent-audit-emitter (⑥b). This row
+ * is what `morningRoutineRanToday` in `src/bootstrap/schedule-helpers.ts`
+ * reads — the pre-routine gate must keep firing on the exact same
+ * `action_type` string after the pipeline split.
+ *
+ * The orchestrator calls it after Stage A's terminal state lands and
+ * after `diagnoseTodayMdState` returns its verdict.
+ *
+ * Emit gate (the orchestrator could enforce this externally, but the
+ * module owns it so caller paths cannot drift):
+ *   - Stage A row exists AND `result === 'success'`
+ *   - today.md health === 'fresh'
+ *   - Stage B success / failure is recorded in `detail` JSON but does
+ *     NOT block the emit. The day still "opened" when today.md is good.
+ *
+ * Failure modes return `{ emitted: false, reason: <stable string> }` so
+ * the caller can audit the skip path via `pnpm audit` without parsing
+ * a thrown error.
+ */
+import type Database from "better-sqlite3";
+export declare const PARENT_AUDIT_ACTION_TYPE = "routine.morning_routine";
+/** Subset of `agent_actions.result` Stage A / Stage B can land in. */
+export type StageActionResult = "success" | "failed" | "partial" | "skipped" | "in_progress";
+/** Stage row shape the emitter reads — same shape for A and B. */
+export interface StageSummary {
+    cost_usd: number | null;
+    num_turns: number | null;
+    result: StageActionResult;
+}
+/**
+ * today.md health verdict mirrored from `diagnoseTodayMdState`. Kept as a
+ * flat string union so this module stays decoupled from the dispatcher;
+ * the orchestrator (Phase 5 wiring) is expected to project the existing
+ * `TodayMdState = { kind: "fresh" | "missing" | "no_h1_date" | "wrong_date" }`
+ * discriminated union (declared in `src/core/dispatcher-scheduled-tasks.ts`)
+ * into this flat form before calling the emitter — i.e. `state.kind`.
+ * When extending one side, extend the other in the same change.
+ */
+export type TodayMdHealth = "fresh" | "missing" | "no_h1_date" | "wrong_date";
+export interface ParentAuditEmitterInputs {
+    /** Routine event's `correlationId`. Stored in `event_id`. */
+    correlationId: string;
+    /** Stage A action row summary. `null` when the row is missing. */
+    stageA: StageSummary | null;
+    /** Stage B action row summary. `null` when the row is missing. */
+    stageB: StageSummary | null;
+    /** today.md health verdict at parent-emit time. */
+    todayMdHealth: TodayMdHealth;
+    /** Pipeline start time. Stored as `started_at` (UTC ISO). */
+    startedAt: Date;
+    /** Pipeline completion time. Stored as `completed_at` (UTC ISO). */
+    completedAt: Date;
+    /**
+     * Optional explicit backend label. Passes through to the row's
+     * `backend` column so observability tooling can attribute the
+     * routine to a backend. Omit when unknown.
+     */
+    backend?: string;
+}
+export type ParentAuditEmitResult = {
+    emitted: true;
+    insertedId: number;
+} | {
+    emitted: false;
+    reason: ParentAuditSkipReason;
+};
+/**
+ * Stable reasons a parent audit emit can be skipped. The orchestrator
+ * forwards these to its own audit channel; the strings are part of
+ * the public contract so don't rename without coordinating with the
+ * gate-side regression tests.
+ */
+export type ParentAuditSkipReason = "stage_a_row_missing" | "stage_a_not_success" | "today_md_missing" | "today_md_no_h1_date" | "today_md_wrong_date";
+export declare function emitMorningRoutineParentAuditRow(db: Database.Database, inputs: ParentAuditEmitterInputs): ParentAuditEmitResult;

package/dist/core/morning/parent-audit-emitter.js

@@ -0,0 +1,118 @@
+/**
+ * `emitMorningRoutineParentAuditRow` — INSERT the parent
+ * `agent_actions` row keyed `action_type='routine.morning_routine'`,
+ * `result='success'`, with cost / turn sums across Stage A + Stage B.
+ *
+ * Spec: `docs/design/appendices/morning-routine-optimization.md`
+ * §"Daemon-side modules to add" → parent-audit-emitter (⑥b). This row
+ * is what `morningRoutineRanToday` in `src/bootstrap/schedule-helpers.ts`
+ * reads — the pre-routine gate must keep firing on the exact same
+ * `action_type` string after the pipeline split.
+ *
+ * The orchestrator calls it after Stage A's terminal state lands and
+ * after `diagnoseTodayMdState` returns its verdict.
+ *
+ * Emit gate (the orchestrator could enforce this externally, but the
+ * module owns it so caller paths cannot drift):
+ *   - Stage A row exists AND `result === 'success'`
+ *   - today.md health === 'fresh'
+ *   - Stage B success / failure is recorded in `detail` JSON but does
+ *     NOT block the emit. The day still "opened" when today.md is good.
+ *
+ * Failure modes return `{ emitted: false, reason: <stable string> }` so
+ * the caller can audit the skip path via `pnpm audit` without parsing
+ * a thrown error.
+ */
+export const PARENT_AUDIT_ACTION_TYPE = "routine.morning_routine";
+export function emitMorningRoutineParentAuditRow(db, inputs) {
+    if (inputs.stageA === null) {
+        return { emitted: false, reason: "stage_a_row_missing" };
+    }
+    if (inputs.stageA.result !== "success") {
+        return { emitted: false, reason: "stage_a_not_success" };
+    }
+    if (inputs.todayMdHealth !== "fresh") {
+        return { emitted: false, reason: todayMdHealthToReason(inputs.todayMdHealth) };
+    }
+    const stageACost = numericOrZero(inputs.stageA.cost_usd);
+    const stageBCost = numericOrZero(inputs.stageB?.cost_usd);
+    const stageATurns = numericOrZero(inputs.stageA.num_turns);
+    const stageBTurns = numericOrZero(inputs.stageB?.num_turns);
+    const totalCost = round6(stageACost + stageBCost);
+    const totalTurns = stageATurns + stageBTurns;
+    const durationMs = Math.max(0, inputs.completedAt.getTime() - inputs.startedAt.getTime());
+    // The parent row is a roll-up marker — its existence is what the
+    // pre-routine gate reads. The cost / turns the user actually paid live
+    // on the Stage A / Stage B `agent_actions` rows
+    // (`action_type=routine.morning_routine_today` / `..._journal`), which
+    // the orchestrator writes via `processResult` per stage. Carrying the
+    // sum on this row too would double-count against
+    // `autonomousDailyCostCapUsd`'s `SUM(cost_usd)` query — so we ZERO the
+    // numeric columns and keep the per-stage sums + aggregate in `detail`
+    // for observability (`pnpm audit`, dashboard cost-attribution UI).
+    const detail = {
+        stageA: summariseStage(inputs.stageA),
+        stageB: inputs.stageB === null ? null : summariseStage(inputs.stageB),
+        todayMdHealth: inputs.todayMdHealth,
+        totalCostUsd: totalCost,
+        totalNumTurns: totalTurns,
+    };
+    const result = db
+        .prepare(`INSERT INTO agent_actions
+         (event_id, action_type, trigger, result, cost_usd, num_turns,
+          duration_ms, started_at, completed_at, detail, backend)
+       VALUES (?, ?, 'autonomous', 'success', 0, 0, ?, ?, ?, json(?), ?)`)
+        .run(inputs.correlationId, PARENT_AUDIT_ACTION_TYPE, durationMs, toSqliteDatetime(inputs.startedAt), toSqliteDatetime(inputs.completedAt), JSON.stringify(detail), inputs.backend ?? null);
+    const insertedId = Number(result.lastInsertRowid);
+    return { emitted: true, insertedId };
+}
+function todayMdHealthToReason(health) {
+    switch (health) {
+        case "missing":
+            return "today_md_missing";
+        case "no_h1_date":
+            return "today_md_no_h1_date";
+        case "wrong_date":
+            return "today_md_wrong_date";
+        // Exhaustiveness guard. The caller fast-paths `fresh` to the
+        // INSERT branch before this function fires; the `case` exists
+        // only to make TypeScript's exhaustive switch force a compile-
+        // time decision when a new `TodayMdHealth` value lands.
+        /* c8 ignore start */
+        case "fresh":
+            throw new Error("emitMorningRoutineParentAuditRow: 'fresh' should have been gated above");
+        /* c8 ignore stop */
+    }
+}
+function summariseStage(stage) {
+    return {
+        result: stage.result,
+        cost_usd: numericOrZero(stage.cost_usd),
+        num_turns: numericOrZero(stage.num_turns),
+    };
+}
+function numericOrZero(value) {
+    if (value === null || value === undefined)
+        return 0;
+    if (!Number.isFinite(value))
+        return 0;
+    return value;
+}
+/**
+ * Round to 6 decimals so `0.1 + 0.2`-style floating point noise does
+ * not leak into the audit row. Six places is finer than the per-stage
+ * cost precision (~4 places) and survives a JSON round-trip.
+ */
+function round6(value) {
+    return Math.round(value * 1e6) / 1e6;
+}
+/**
+ * Format a Date as the `YYYY-MM-DD HH:MM:SS` shape SQLite's `datetime()`
+ * function produces. Stored in UTC because every other agent_actions
+ * row in the daemon uses `datetime('now')` which is UTC.
+ */
+function toSqliteDatetime(date) {
+    const iso = date.toISOString();
+    // `YYYY-MM-DDTHH:MM:SS.sssZ` → `YYYY-MM-DD HH:MM:SS`.
+    return `${iso.slice(0, 10)} ${iso.slice(11, 19)}`;
+}

package/dist/core/morning/partial-extract-streak.d.ts

@@ -0,0 +1,76 @@
+/**
+ * `partial-extract-streak` — §4.7b operator escalation for the daily
+ * journal's partial-extract shape.
+ *
+ * When Stage B's daily-journal compose lands `ok='partial'` three days
+ * in a row (any mix of `frontmatter_tag_missing` /
+ * `frontmatter_invalid_json` / `frontmatter_schema_invalid`), the
+ * user's wiki link graph is silently degrading even though the diary
+ * body is on disk. The daemon emits a one-shot owner DM the first
+ * time the 3-day streak fires, with 24h dedup so a continuing streak
+ * does not spam and a streak ending + restarting fires a fresh DM.
+ *
+ * Storage:
+ *   - Streak detection reads the last 7 days of `agent_actions` rows
+ *     for `action_type='routine.morning_routine_journal'`, ordered
+ *     newest-first.
+ *   - Dedup state lives in
+ *     `runtime_state.partial_extract_dm_last_notified_at` (ISO
+ *     timestamp). Absent value reads as "never notified" — the first
+ *     repeat streak fires.
+ */
+import type Database from "better-sqlite3";
+export declare const STREAK_THRESHOLD = 3;
+export declare const DEDUP_WINDOW_MS: number;
+export interface PartialExtractStreakNotifier {
+    /**
+     * Emit a one-shot owner DM about the partial-extract streak. The
+     * notifier shape mirrors the existing `sendNotification` chain
+     * (priority + platforms) so the streak detector can plug into the
+     * already-wired notification surface without depending on Hono /
+     * messaging adapters directly.
+     */
+    notify(args: {
+        message: string;
+    }): Promise<void> | void;
+}
+export interface MaybeEmitArgs {
+    db: Database.Database;
+    /** Correlation id for the morning routine; logged for ops grep. */
+    correlationId: string;
+    /** Override `Date.now()` for tests. */
+    now?: () => Date;
+    /** The DM emitter — the orchestrator passes the daemon's
+     *  `sendNotification` proxy. When `null` the streak detector still
+     *  runs (so the SQL aggregator is exercised + audited) but no DM
+     *  is sent. */
+    notifier: PartialExtractStreakNotifier | null;
+}
+export interface MaybeEmitResult {
+    /** Whether the SQL streak check actually fired (3+ recent partials). */
+    streakDetected: boolean;
+    /** Whether a DM was sent on this call. */
+    dmSent: boolean;
+    /**
+     * Reason the DM was suppressed when streakDetected=true but dmSent=false.
+     * Three distinct shapes so operators triaging from telemetry can tell a
+     * configuration gap ("no notifier was supplied") apart from a transient
+     * runtime failure ("notifier threw") apart from the normal dedup path.
+     */
+    suppressedReason?: "dedup_recent" | "no_notifier" | "notify_failed";
+    /** Reasons gathered from the most-recent 3 rows when the streak fires —
+     *  surfaced for tests / ops logging. */
+    reasonsInStreak?: ReadonlyArray<string>;
+}
+/**
+ * Look at the most recent 3 Stage B rows. If all carry
+ * `detail.dailyWrite.ok = 'partial'`, emit an owner DM (subject to
+ * the 24h dedup gate). Returns a structured outcome so callers can
+ * log + tests can assert without re-querying the DB.
+ *
+ * The SELECT is the canonical query from design §4.7b — keyed by
+ * `action_type` + a 7-day window + DESC ordering + LIMIT 3.
+ */
+export declare function maybeEmitPartialExtractStreakDm(args: MaybeEmitArgs): Promise<MaybeEmitResult>;
+/** Exposed for tests — surface the runtime_state key. */
+export declare const PARTIAL_EXTRACT_DEDUP_KEY = "partial_extract_dm_last_notified_at";

package/dist/core/morning/partial-extract-streak.js

@@ -0,0 +1,165 @@
+/**
+ * `partial-extract-streak` — §4.7b operator escalation for the daily
+ * journal's partial-extract shape.
+ *
+ * When Stage B's daily-journal compose lands `ok='partial'` three days
+ * in a row (any mix of `frontmatter_tag_missing` /
+ * `frontmatter_invalid_json` / `frontmatter_schema_invalid`), the
+ * user's wiki link graph is silently degrading even though the diary
+ * body is on disk. The daemon emits a one-shot owner DM the first
+ * time the 3-day streak fires, with 24h dedup so a continuing streak
+ * does not spam and a streak ending + restarting fires a fresh DM.
+ *
+ * Storage:
+ *   - Streak detection reads the last 7 days of `agent_actions` rows
+ *     for `action_type='routine.morning_routine_journal'`, ordered
+ *     newest-first.
+ *   - Dedup state lives in
+ *     `runtime_state.partial_extract_dm_last_notified_at` (ISO
+ *     timestamp). Absent value reads as "never notified" — the first
+ *     repeat streak fires.
+ */
+import { readRuntimeState, writeRuntimeState, } from "../../db/runtime-state.js";
+import { createLogger } from "../../logging.js";
+const logger = createLogger("partial-extract-streak");
+export const STREAK_THRESHOLD = 3;
+export const DEDUP_WINDOW_MS = 24 * 60 * 60 * 1000;
+const STAGE_B_ACTION_TYPE = "routine.morning_routine_journal";
+const RUNTIME_KEY = "partial_extract_dm_last_notified_at";
+/**
+ * Look at the most recent 3 Stage B rows. If all carry
+ * `detail.dailyWrite.ok = 'partial'`, emit an owner DM (subject to
+ * the 24h dedup gate). Returns a structured outcome so callers can
+ * log + tests can assert without re-querying the DB.
+ *
+ * The SELECT is the canonical query from design §4.7b — keyed by
+ * `action_type` + a 7-day window + DESC ordering + LIMIT 3.
+ */
+export async function maybeEmitPartialExtractStreakDm(args) {
+    const rows = readRecentStageBRows(args.db);
+    if (rows.length < STREAK_THRESHOLD) {
+        return { streakDetected: false, dmSent: false };
+    }
+    const top3 = rows.slice(0, STREAK_THRESHOLD);
+    const allPartial = top3.every((row) => row.ok === "partial");
+    if (!allPartial) {
+        return { streakDetected: false, dmSent: false };
+    }
+    const reasons = top3.map((row) => row.partialReason ?? "unknown");
+    if (isWithinDedupWindow(args.db, args.now)) {
+        return {
+            streakDetected: true,
+            dmSent: false,
+            suppressedReason: "dedup_recent",
+            reasonsInStreak: reasons,
+        };
+    }
+    if (args.notifier === null) {
+        return {
+            streakDetected: true,
+            dmSent: false,
+            suppressedReason: "no_notifier",
+            reasonsInStreak: reasons,
+        };
+    }
+    const message = renderDmMessage(top3);
+    try {
+        await args.notifier.notify({ message });
+    }
+    catch (err) {
+        // Don't propagate notifier failures — the orchestrator already
+        // logged Stage B's outcome via `persistStageAuditRows`. A failed
+        // DM is recoverable (next day's streak check fires again with no
+        // dedup state recorded), so we DON'T write the timestamp on this
+        // path. Surfaced as `notify_failed` (distinct from `no_notifier`)
+        // so telemetry can tell "notifier threw" apart from "no notifier
+        // configured" — the two states are operationally different even
+        // though both end in dmSent=false.
+        logger.warn({ err, correlationId: args.correlationId }, "Partial-extract streak DM emit failed");
+        return {
+            streakDetected: true,
+            dmSent: false,
+            suppressedReason: "notify_failed",
+            reasonsInStreak: reasons,
+        };
+    }
+    writeDedupTimestamp(args.db, args.now);
+    logger.info({ correlationId: args.correlationId, reasonsInStreak: reasons }, "Partial-extract streak DM emitted");
+    return {
+        streakDetected: true,
+        dmSent: true,
+        reasonsInStreak: reasons,
+    };
+}
+function readRecentStageBRows(db) {
+    // Pull JSON-extracted fields directly via SQLite's json_extract so we
+    // never have to parse the column twice. `LIMIT 7` matches the 7-day
+    // window design §4.7b specifies; the 3-row check runs in JS over the
+    // result.
+    try {
+        return db
+            .prepare(`SELECT json_extract(detail, '$.dailyWrite.ok')            AS ok,
+                json_extract(detail, '$.dailyWrite.partialReason') AS partialReason,
+                started_at                                           AS startedAt
+           FROM agent_actions
+          WHERE action_type = ?
+            AND started_at >= datetime('now', '-7 days')
+          ORDER BY started_at DESC
+          LIMIT ?`)
+            .all(STAGE_B_ACTION_TYPE, STREAK_THRESHOLD + 4);
+    }
+    catch (err) {
+        logger.warn({ err }, "Partial-extract streak SELECT failed");
+        return [];
+    }
+}
+function isWithinDedupWindow(db, nowFn) {
+    const last = readRuntimeState(db, RUNTIME_KEY);
+    if (typeof last !== "string" || last.length === 0)
+        return false;
+    const lastMs = Date.parse(last);
+    if (!Number.isFinite(lastMs))
+        return false;
+    const nowMs = (nowFn ?? (() => new Date()))().getTime();
+    return nowMs - lastMs < DEDUP_WINDOW_MS;
+}
+function writeDedupTimestamp(db, nowFn) {
+    const iso = (nowFn ?? (() => new Date()))().toISOString();
+    writeRuntimeState(db, RUNTIME_KEY, iso);
+}
+/**
+ * Compose the operator-DM body. Counts each `partialReason` so the
+ * operator sees the distribution at a glance — `(reasons:
+ * frontmatter_tag_missing × 2, frontmatter_invalid_json × 1)`.
+ *
+ * Dates surfaced are the `started_at` UTC dates (YYYY-MM-DD slice).
+ *
+ * Streak-count rendering: derives the "on all N days" suffix from the
+ * actual `rows.length` rather than hardcoding three, so a future
+ * `STREAK_THRESHOLD` bump (or the SQL LIMIT returning fewer rows than
+ * the threshold under an edge case the caller didn't filter) cannot
+ * print a lie like "on all three days" against four-row input.
+ */
+function renderDmMessage(rows) {
+    const dates = rows
+        .map((row) => row.startedAt.slice(0, 10))
+        .filter((value, idx, arr) => arr.indexOf(value) === idx)
+        .join(" / ");
+    const counts = new Map();
+    for (const row of rows) {
+        const reason = row.partialReason ?? "unknown";
+        counts.set(reason, (counts.get(reason) ?? 0) + 1);
+    }
+    const reasonsRendered = [...counts.entries()]
+        .map(([reason, count]) => `${reason} × ${count}`)
+        .join(", ");
+    return [
+        `The daily journal authored OK on ${dates} but the model omitted the`,
+        `plans/projects/people/tags frontmatter on all ${rows.length} days`,
+        `(reasons: ${reasonsRendered}).`,
+        `Inspect agent-assets/task-flows/routine.morning_routine_journal.md`,
+        `or escalate Stage B's tier from lite to medium under /settings/models.`,
+    ].join(" ");
+}
+/** Exposed for tests — surface the runtime_state key. */
+export const PARTIAL_EXTRACT_DEDUP_KEY = RUNTIME_KEY;

package/dist/core/morning/roadmap-skeleton-builder.d.ts

@@ -0,0 +1,158 @@
+/**
+ * `buildRoadmapSkeleton` + `gatherRoadmapSkeletonFacts` — assemble the
+ * `<roadmap_skeleton>` MD body that the morning-routine orchestrator
+ * injects into Stage A's prompt on the **first-run** (no-yesterday)
+ * branch.
+ *
+ * Why this exists — `docs/design/appendices/morning-routine-optimization.md`
+ * retires `routine.morning_routine_initial`'s high-tier session.
+ * On the first run after setup, the wizard-installed `roadmap.md`
+ * carries only the `_(Not yet configured)_` placeholder rows. The
+ * legacy initial routine spent a high-tier (Opus) cold-start session
+ * regenerating every section from scratch — read management rules,
+ * survey active projects, scan calendar, query travel bookings, then
+ * compose the markdown. That last step is template assembly and is
+ * what justified the tier upgrade. By doing the deterministic data
+ * gather here and emitting a pre-shaped `<roadmap_skeleton>` block,
+ * Stage A on medium tier can spot-edit the skeleton into
+ * `roadmap.md` via the same `PATCH` paths the recurring branch uses —
+ * collapsing the variant into a single medium-tier flow.
+ *
+ * The skeleton is **scratch data**. Stage A is the only writer of
+ * `roadmap.md`; the skeleton's role is to amortize the "what should I
+ * even put in `## Annual Goals` / `## Quarterly Focus` / `## Preparation
+ * Timeline`" research over a deterministic SQL+fs pass instead of a
+ * judgment-heavy turn. Stage A may reshape, prune, or reword every
+ * section before its `PUT /api/context/roadmap`. There is no
+ * byte-for-byte preservation contract — unlike the journal skeleton —
+ * because `roadmap.md` is daemon-tracked but has no per-field
+ * validator, and Stage A's judgement (active vs. archived projects,
+ * which calendar events count as preparation, which travel rows are
+ * still relevant) is the load-bearing reason this stays on medium tier.
+ *
+ * Gating: the orchestrator only computes the skeleton when
+ * `yesterday.md` is absent (the first-run signal). The recurring
+ * branch leaves `<roadmap_skeleton>` absent and Stage A falls back to
+ * the truncated `<roadmap>` block ContextBuilder injects today; this is
+ * exactly how the variant collapse is supposed to read.
+ *
+ * Two-layer design mirrors `journal-skeleton-builder.ts`:
+ *   - `gatherRoadmapSkeletonFacts(db, contextDir, ...)` — runs SQLite
+ *     aggregations against `travel_bookings`, walks `context/projects/`
+ *     for active project frontmatter, parses `policies/management.md`
+ *     for the operator-declared goals block, and pulls 7-day calendar
+ *     events for the `## Quarterly Focus` synthesis hints. Pure
+ *     read-only, idempotent.
+ *   - `buildRoadmapSkeleton(inputs, facts)` — pure markdown composer
+ *     that emits one section per roadmap.md heading the template
+ *     expects.
+ *
+ * The split keeps the I/O-bound queries testable independently and
+ * lets the pure builder be exercised with synthesized fixtures.
+ */
+import type Database from "better-sqlite3";
+/** Calendar event filtered to the look-ahead window for Quarterly Focus + Preparation Timeline hints. */
+export interface RoadmapSkeletonCalendarEvent {
+    /** `YYYY-MM-DD` start date in the operator timezone. */
+    date: string;
+    /** Event title. May be empty (rendered as `(untitled)`). */
+    title: string;
+}
+/** Inputs the daemon assembles before invoking the builder. */
+export interface RoadmapSkeletonInputs {
+    /** Today's agent-day date in `YYYY-MM-DD`. Lands in the `updated:` frontmatter. */
+    todayDateStr: string;
+    /**
+     * Forward-looking calendar events spanning the next 7 days. Used as
+     * candidates for ## Quarterly Focus near-term milestones and as
+     * preparation triggers (e.g. an `Onsite` block 3 days out cues a
+     * `Preparation Timeline` row).
+     */
+    calendarEvents: ReadonlyArray<RoadmapSkeletonCalendarEvent>;
+    /**
+     * IANA timezone (e.g. `Asia/Tokyo`) — surfaced in the skeleton's
+     * front-matter comment so Stage A knows which zone the embedded
+     * dates are in. Optional; falls back to "system".
+     */
+    timezone?: string;
+}
+/** Project summary derived from `context/projects/<slug>.md` frontmatter. */
+export interface RoadmapSkeletonProject {
+    slug: string;
+    title: string;
+    state: string;
+    /** ISO date (`YYYY-MM-DD`) parsed from `due:` frontmatter when present. */
+    due: string | null;
+    /** Free-text "what's next" line, parsed from `next_milestone:`. */
+    nextMilestone: string | null;
+}
+/** Travel booking row condensed for the Preparation Timeline. */
+export interface RoadmapSkeletonTravelBooking {
+    type: string;
+    destination: string | null;
+    startDate: string | null;
+    endDate: string | null;
+    status: string | null;
+}
+/** Facts derived from SQLite + fs for the first-run skeleton. */
+export interface RoadmapSkeletonFacts {
+    /**
+     * Active project summaries — every `context/projects/*.md` whose
+     * `state` frontmatter is not `archived`. Stable order: due ascending
+     * (nulls last), then slug ascending — same sort the active-projects
+     * block in ContextBuilder uses so the two blocks read as one
+     * coherent picture in Stage A's prompt.
+     */
+    activeProjects: ReadonlyArray<RoadmapSkeletonProject>;
+    /**
+     * Annual goals — operator-supplied free-text lines extracted from
+     * `policies/management.md` under a `## Annual Goals` heading. Empty
+     * when the heading is absent or the section is empty (the skeleton
+     * then renders an explicit `_(Not yet configured)_` placeholder
+     * Stage A is expected to replace with the operator's intent — same
+     * line the setup wizard wrote).
+     */
+    annualGoals: ReadonlyArray<string>;
+    /**
+     * Upcoming travel rows — `start_date >= today AND status != 'cancelled'`,
+     * ordered by `start_date` ascending. The Preparation Timeline section
+     * cites these as the rows the agent should fan preparation tasks
+     * out from.
+     */
+    upcomingTravel: ReadonlyArray<RoadmapSkeletonTravelBooking>;
+}
+/**
+ * Run the SQLite + fs aggregations that feed the skeleton. Pure
+ * read-only; callers own the timezone math (`todayDateStr` is the
+ * filter the `start_date >= ?` predicate joins against).
+ *
+ * `contextDir` must point at the daemon's runtime context directory
+ * (e.g. `~/.personal-agent/context`). Missing files are silent-skipped
+ * — the skeleton renders explicit placeholders so the failure mode is
+ * "Stage A sees an empty section" rather than "Stage A sees no
+ * skeleton at all", which is what the variant collapse depends on.
+ */
+export declare function gatherRoadmapSkeletonFacts(db: Database.Database, contextDir: string, todayDateStr: string): RoadmapSkeletonFacts;
+/**
+ * Compose the `<roadmap_skeleton>` MD body. Pure — every output byte is
+ * a deterministic function of `inputs` + `facts`. Stage A reads this as
+ * scratch input and authors `roadmap.md` per the operator-visible
+ * template (`## Annual Goals` / `## Quarterly Focus` /
+ * `## Preparation Timeline` / `## Agent Action Plan`).
+ *
+ * The composer NEVER emits the `## Agent Action Plan` section — that
+ * is operationally tightly coupled to today's User Tasks + roadmap-
+ * relevant `agent_schedule` rows, both of which Stage A enumerates
+ * inside its own turn from the live observations table. Including a
+ * stale skeleton plan would invite Stage A to copy it verbatim and
+ * mask schedule-fan-out drift.
+ */
+export declare function buildRoadmapSkeleton(inputs: RoadmapSkeletonInputs, facts: RoadmapSkeletonFacts): string;
+/**
+ * Pull bullet entries under the first `## Annual Goals` heading. Stops
+ * at the next `## ` heading or end-of-file. Bullets are returned with
+ * the `- ` / `* ` marker stripped and surrounding whitespace trimmed.
+ *
+ * Exported for unit testing only.
+ */
+export declare function extractAnnualGoals(rulesBody: string): string[];