fullstackgtm 0.23.2 → 0.25.0

package/dist/schedule.d.ts

@@ -0,0 +1,143 @@
+/**
+ * The schedule layer (spec: docs/schedule.md in the monorepo): declare once
+ * that a fullstackgtm command should run on a cadence, materialize the timers
+ * through a provider (MVP: the user crontab), and keep an append-only run
+ * history. Horizontal on purpose — no feature namespace owns cron logic.
+ *
+ * The governance invariant: **scheduling never auto-approves.** Schedulable
+ * commands are read/plan-side; `apply` is schedulable only as
+ * `apply --plan-id <id>` and the plan's approved status is re-checked at
+ * every firing. Unattended runs accumulate proposals, never surprise writes.
+ */
+export type ScheduleProvider = "local";
+export type ScheduleEntry = {
+    id: string;
+    label: string;
+    /** Fullstackgtm command argv (no binary name, no --profile) — never shell. */
+    argv: string[];
+    /** 5-field cron expression (minute hour day-of-month month day-of-week). */
+    cron: string;
+    provider: ScheduleProvider;
+    enabled: boolean;
+    createdAt: string;
+};
+export type ScheduleRunTrigger = "cron" | "manual";
+export type ScheduleRunRecord = {
+    scheduleId: string;
+    firedAt: string;
+    completedAt: string;
+    trigger: ScheduleRunTrigger;
+    exitCode: number;
+    /** Last ~50 lines of the command's stdout+stderr. */
+    outputTail: string;
+    /** Plan ids / enrich run labels the firing produced (store-diffed). */
+    artifacts: {
+        planIds: string[];
+        runLabels: string[];
+    };
+    /**
+     * Set when a governance gate refused to execute the command: the firing is
+     * recorded for visibility but nothing ran. Reasons: "plan_not_approved"
+     * (scheduled apply against a plan that is not approved — there is no flag
+     * that relaxes this), "not_schedulable" (the stored argv no longer passes
+     * the allowlist, e.g. after a hand edit of schedules.json).
+     */
+    noopReason?: "plan_not_approved" | "not_schedulable";
+};
+export declare function scheduleId(label: string, cron: string, argv: string[], createdAt: string): string;
+/**
+ * Validate that an argv resolves to a schedulable fullstackgtm command.
+ * Enforced at `schedule add` time AND re-checked at `schedule run` time (the
+ * store is a user-editable JSON file). Throws with the full allowlist on
+ * rejection; arbitrary shell is structurally impossible anyway (runs dispatch
+ * in-process into the CLI router, never through a shell).
+ */
+export declare function validateSchedulableArgv(argv: string[]): void;
+/**
+ * Split a `schedule add "<command>"` string into argv, honoring single and
+ * double quotes (no escapes, no expansion — this is tokenization, not shell).
+ */
+export declare function tokenizeCommand(text: string): string[];
+export type CronExpression = {
+    source: string;
+    minute: number[];
+    hour: number[];
+    dayOfMonth: number[];
+    month: number[];
+    /** 0–6, Sunday = 0 (an input 7 normalizes to 0). */
+    dayOfWeek: number[];
+    /** Vixie-cron day semantics: when BOTH are restricted, either may match. */
+    dayOfMonthRestricted: boolean;
+    dayOfWeekRestricted: boolean;
+};
+export declare function parseCron(expression: string): CronExpression;
+/** True when the expression fires in `date`'s minute (local time, like cron). */
+export declare function cronMatches(cron: CronExpression, date: Date): boolean;
+/**
+ * The next firing strictly after `after` (local time). Throws when the
+ * expression never fires (e.g. "0 0 31 2 *") — `schedule add` calls this once
+ * so impossible expressions are rejected up front with a clear error.
+ */
+export declare function nextCronFiring(cron: CronExpression, after: Date): Date;
+/**
+ * Expected firings strictly inside (fromExclusive, toExclusive), capped — the
+ * input to missed-firing detection, never to catch-up execution.
+ */
+export declare function expectedFirings(cron: CronExpression, fromExclusive: Date, toExclusive: Date, cap?: number): Date[];
+/**
+ * Missed firings since the last run record (or the entry's creation when no
+ * run has ever fired): expected firings with no run record in their minute.
+ * Local cron has no catch-up — a laptop asleep at firing time skips the run —
+ * so this is visibility only; nothing is re-executed.
+ */
+export declare function computeMissedFirings(entry: Pick<ScheduleEntry, "cron" | "createdAt">, runs: ScheduleRunRecord[], now?: Date, cap?: number): {
+    missed: Date[];
+    capped: boolean;
+};
+export declare function schedulesPath(baseDir?: string): string;
+export declare function scheduleRunsDir(baseDir?: string): string;
+export interface ScheduleStore {
+    add(entry: ScheduleEntry): Promise<ScheduleEntry>;
+    list(): Promise<ScheduleEntry[]>;
+    get(id: string): Promise<ScheduleEntry | null>;
+    remove(id: string): Promise<boolean>;
+    setEnabled(id: string, enabled: boolean): Promise<ScheduleEntry>;
+}
+/**
+ * Schedule entries as one small JSON file per profile, sibling to plans and
+ * enrich runs. `directory` overrides the profile home (tests).
+ */
+export declare function createFileScheduleStore(directory?: string): ScheduleStore;
+export interface ScheduleRunStore {
+    record(run: ScheduleRunRecord): Promise<ScheduleRunRecord>;
+    /** Run records for one schedule, oldest first; `limit` keeps the newest N. */
+    list(scheduleId: string, limit?: number): Promise<ScheduleRunRecord[]>;
+}
+export declare function createFileScheduleRunStore(directory?: string): ScheduleRunStore;
+export type CrontabIo = {
+    /** Current crontab content; "" when the user has none. */
+    read(): string;
+    write(content: string): void;
+};
+/**
+ * The real user crontab via `crontab -l` / `crontab -`. Everything above this
+ * function takes a CrontabIo so tests inject fakes and never touch it.
+ */
+export declare function systemCrontabIo(): CrontabIo;
+export declare function crontabSentinels(profile: string): {
+    open: string;
+    close: string;
+};
+/**
+ * Render the managed block for one profile. Every line invokes
+ * `... schedule run <id> --profile <profile> --trigger cron` — the single
+ * provider entry point — so the crontab a user audits never contains anything
+ * but fullstackgtm dispatch (no arbitrary shell, ever).
+ */
+export declare function renderManagedBlock(profile: string, entries: ScheduleEntry[], cliInvocation: string): string;
+/**
+ * Replace (or with `block: null`, remove) the profile's managed block in the
+ * crontab content, byte-for-byte preserving everything outside the sentinels.
+ * Idempotent: re-applying the same block yields identical content.
+ */
+export declare function replaceManagedBlock(existing: string, profile: string, block: string | null): string;

package/dist/schedule.js

@@ -0,0 +1,485 @@
+import { spawnSync } from "node:child_process";
+import { mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { credentialsDir, ensureSecureHomeDir, writeSecureFile } from "./credentials.js";
+// Mirrors stableHash in rules.ts (FNV-1a); duplicated to keep schedule.ts
+// importable without pulling the audit engine (the market/enrich precedent).
+function fnv1a(value) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < value.length; i += 1) {
+        hash ^= value.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, "0");
+}
+export function scheduleId(label, cron, argv, createdAt) {
+    return `sch_${fnv1a(`${label}|${cron}|${argv.join(" ")}|${createdAt}`)}`;
+}
+// ---------------------------------------------------------------------------
+// Governance: the schedulable allowlist
+/**
+ * Read/plan-side commands only. Their unattended output is plans in the
+ * queue, run records, and reports — never CRM writes. `apply` is the single
+ * exception, allowed only as `apply --plan-id <id>` (the plan store's
+ * approval status is re-checked at run time; see docs/schedule.md).
+ */
+const SCHEDULABLE = {
+    audit: null,
+    snapshot: null,
+    suggest: null,
+    report: null,
+    doctor: null,
+    enrich: ["append", "refresh"],
+    market: ["capture", "refresh"],
+};
+const ALLOWLIST_SUMMARY = "audit, snapshot, enrich append|refresh, market capture|refresh, suggest, report, doctor — " +
+    "plus apply --plan-id <id> (re-checked approved at every firing)";
+/**
+ * Validate that an argv resolves to a schedulable fullstackgtm command.
+ * Enforced at `schedule add` time AND re-checked at `schedule run` time (the
+ * store is a user-editable JSON file). Throws with the full allowlist on
+ * rejection; arbitrary shell is structurally impossible anyway (runs dispatch
+ * in-process into the CLI router, never through a shell).
+ */
+export function validateSchedulableArgv(argv) {
+    const head = argv[0];
+    if (!head)
+        throw new Error("Nothing to schedule: the command is empty.");
+    if (argv.includes("--profile")) {
+        throw new Error("Do not embed --profile in the scheduled command — schedules are already profile-scoped. " +
+            "Pass --profile <name> to `schedule add` itself instead.");
+    }
+    if (head === "apply") {
+        const planIdIndex = argv.indexOf("--plan-id");
+        const planId = planIdIndex === -1 ? undefined : argv[planIdIndex + 1];
+        if (!planId || planId.startsWith("--")) {
+            throw new Error("apply is schedulable ONLY as `apply --plan-id <id> ...`: the plan must already exist in " +
+                "the plan store, and its status is re-checked as approved at every firing. " +
+                "Scheduling never auto-approves.");
+        }
+        if (argv.includes("--plan") || argv.includes("--approve")) {
+            throw new Error("A scheduled apply cannot take --plan/--approve — file-based approval would bypass the " +
+                "plan store's approval state. Use `apply --plan-id <id>` and approve via `plans approve`.");
+        }
+        return;
+    }
+    if (!Object.hasOwn(SCHEDULABLE, head)) {
+        throw new Error(`"${head}" is not schedulable. Schedulable commands are read/plan-side only: ${ALLOWLIST_SUMMARY}. ` +
+            "Unattended runs accumulate proposals, never writes.");
+    }
+    const subcommands = SCHEDULABLE[head];
+    if (subcommands) {
+        const sub = argv[1];
+        if (!sub || !subcommands.includes(sub)) {
+            throw new Error(`"${head}${sub ? ` ${sub}` : ""}" is not schedulable — only: ${subcommands
+                .map((name) => `${head} ${name}`)
+                .join(", ")}.`);
+        }
+    }
+}
+/**
+ * Split a `schedule add "<command>"` string into argv, honoring single and
+ * double quotes (no escapes, no expansion — this is tokenization, not shell).
+ */
+export function tokenizeCommand(text) {
+    const tokens = [];
+    let current = "";
+    let quote = null;
+    let inToken = false;
+    for (const char of text) {
+        if (quote) {
+            if (char === quote)
+                quote = null;
+            else
+                current += char;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            inToken = true;
+            continue;
+        }
+        if (/\s/.test(char)) {
+            if (inToken) {
+                tokens.push(current);
+                current = "";
+                inToken = false;
+            }
+            continue;
+        }
+        current += char;
+        inToken = true;
+    }
+    if (quote)
+        throw new Error(`Unclosed ${quote} quote in the scheduled command.`);
+    if (inToken)
+        tokens.push(current);
+    return tokens;
+}
+const CRON_FIELD_SPECS = [
+    { name: "minute", min: 0, max: 59 },
+    { name: "hour", min: 0, max: 23 },
+    { name: "day-of-month", min: 1, max: 31 },
+    { name: "month", min: 1, max: 12 },
+    { name: "day-of-week", min: 0, max: 7 },
+];
+export function parseCron(expression) {
+    const fields = expression.trim().split(/\s+/);
+    if (fields.length !== 5) {
+        throw new Error(`Invalid cron expression "${expression}": expected 5 fields ` +
+            `(minute hour day-of-month month day-of-week), got ${fields.length}.`);
+    }
+    const [minute, hour, dayOfMonth, month, dayOfWeekRaw] = fields.map((field, index) => parseCronField(field, CRON_FIELD_SPECS[index], expression));
+    // 7 is an accepted alias for Sunday; normalize so matching uses 0–6.
+    const dayOfWeek = Array.from(new Set(dayOfWeekRaw.map((value) => (value === 7 ? 0 : value)))).sort((a, b) => a - b);
+    return {
+        source: expression.trim(),
+        minute,
+        hour,
+        dayOfMonth,
+        month,
+        dayOfWeek,
+        dayOfMonthRestricted: fields[2] !== "*",
+        dayOfWeekRestricted: fields[4] !== "*",
+    };
+}
+function parseCronField(field, spec, expression) {
+    const values = new Set();
+    const fail = (problem) => {
+        throw new Error(`Invalid cron expression "${expression}": ${spec.name} field "${field}" ${problem}.`);
+    };
+    if (field === "")
+        fail("is empty");
+    for (const part of field.split(",")) {
+        const slashed = part.split("/");
+        if (slashed.length > 2)
+            fail(`has more than one "/" in "${part}"`);
+        const [rangeText, stepText] = slashed;
+        let step = 1;
+        if (stepText !== undefined) {
+            if (!/^\d+$/.test(stepText) || Number(stepText) < 1) {
+                fail(`has an invalid step "/${stepText}" (steps are positive integers)`);
+            }
+            step = Number(stepText);
+        }
+        let low;
+        let high;
+        if (rangeText === "*") {
+            low = spec.min;
+            high = spec.max;
+        }
+        else if (/^\d+$/.test(rangeText)) {
+            low = Number(rangeText);
+            // Vixie semantics: "N/step" means N through the field max, stepped.
+            high = stepText !== undefined ? spec.max : low;
+        }
+        else {
+            const range = /^(\d+)-(\d+)$/.exec(rangeText);
+            if (!range)
+                return fail(`has an unsupported token "${part}" (use *, numbers, lists, ranges, steps)`);
+            low = Number(range[1]);
+            high = Number(range[2]);
+            if (low > high)
+                fail(`has a range "${rangeText}" that starts after it ends`);
+        }
+        if (low < spec.min || high > spec.max) {
+            fail(`is out of range (${spec.min}–${spec.max})`);
+        }
+        for (let value = low; value <= high; value += step)
+            values.add(value);
+    }
+    return Array.from(values).sort((a, b) => a - b);
+}
+function cronDayMatches(cron, date) {
+    if (!cron.month.includes(date.getMonth() + 1))
+        return false;
+    const domMatch = cron.dayOfMonth.includes(date.getDate());
+    const dowMatch = cron.dayOfWeek.includes(date.getDay());
+    if (cron.dayOfMonthRestricted && cron.dayOfWeekRestricted)
+        return domMatch || dowMatch;
+    if (cron.dayOfMonthRestricted)
+        return domMatch;
+    if (cron.dayOfWeekRestricted)
+        return dowMatch;
+    return true;
+}
+/** True when the expression fires in `date`'s minute (local time, like cron). */
+export function cronMatches(cron, date) {
+    return (cron.minute.includes(date.getMinutes()) &&
+        cron.hour.includes(date.getHours()) &&
+        cronDayMatches(cron, date));
+}
+/**
+ * The next firing strictly after `after` (local time). Throws when the
+ * expression never fires (e.g. "0 0 31 2 *") — `schedule add` calls this once
+ * so impossible expressions are rejected up front with a clear error.
+ */
+export function nextCronFiring(cron, after) {
+    const start = new Date(after.getTime());
+    start.setSeconds(0, 0);
+    start.setMinutes(start.getMinutes() + 1);
+    // Day-level iteration; 4 years + 1 day covers schedules that only fire on
+    // a leap day. Hour/minute lists are sorted, so the first hit is the answer.
+    for (let dayOffset = 0; dayOffset <= 1462; dayOffset += 1) {
+        const day = new Date(start.getFullYear(), start.getMonth(), start.getDate() + dayOffset);
+        if (!cronDayMatches(cron, day))
+            continue;
+        const sameDay = dayOffset === 0;
+        for (const hour of cron.hour) {
+            if (sameDay && hour < start.getHours())
+                continue;
+            for (const minute of cron.minute) {
+                if (sameDay && hour === start.getHours() && minute < start.getMinutes())
+                    continue;
+                return new Date(day.getFullYear(), day.getMonth(), day.getDate(), hour, minute);
+            }
+        }
+    }
+    throw new Error(`Cron expression "${cron.source}" never fires (no matching date within 4 years).`);
+}
+/**
+ * Expected firings strictly inside (fromExclusive, toExclusive), capped — the
+ * input to missed-firing detection, never to catch-up execution.
+ */
+export function expectedFirings(cron, fromExclusive, toExclusive, cap = 100) {
+    const firings = [];
+    let cursor = fromExclusive;
+    while (firings.length < cap) {
+        let next;
+        try {
+            next = nextCronFiring(cron, cursor);
+        }
+        catch {
+            break; // an expression that never fires has nothing to miss
+        }
+        if (next.getTime() >= toExclusive.getTime())
+            break;
+        firings.push(next);
+        cursor = next;
+    }
+    return firings;
+}
+/**
+ * Missed firings since the last run record (or the entry's creation when no
+ * run has ever fired): expected firings with no run record in their minute.
+ * Local cron has no catch-up — a laptop asleep at firing time skips the run —
+ * so this is visibility only; nothing is re-executed.
+ */
+export function computeMissedFirings(entry, runs, now = new Date(), cap = 100) {
+    const cron = parseCron(entry.cron);
+    const lastRun = runs.length > 0 ? runs[runs.length - 1] : null;
+    const baseline = new Date(lastRun ? lastRun.firedAt : entry.createdAt);
+    const expected = expectedFirings(cron, baseline, now, cap);
+    const firedMinutes = new Set(runs.map((run) => {
+        const fired = new Date(run.firedAt);
+        fired.setSeconds(0, 0);
+        return fired.getTime();
+    }));
+    const missed = expected.filter((firing) => !firedMinutes.has(firing.getTime()));
+    return { missed, capped: expected.length >= cap };
+}
+// ---------------------------------------------------------------------------
+// Stores: schedules.json + schedule/runs/<id>/<timestamp>.json
+export function schedulesPath(baseDir) {
+    return join(baseDir ?? credentialsDir(), "schedules.json");
+}
+export function scheduleRunsDir(baseDir) {
+    return join(baseDir ?? credentialsDir(), "schedule", "runs");
+}
+/**
+ * Schedule entries as one small JSON file per profile, sibling to plans and
+ * enrich runs. `directory` overrides the profile home (tests).
+ */
+export function createFileScheduleStore(directory) {
+    const path = () => schedulesPath(directory);
+    function read() {
+        try {
+            const parsed = JSON.parse(readFileSync(path(), "utf8"));
+            if (parsed && typeof parsed === "object" && parsed.version === 1 && Array.isArray(parsed.schedules)) {
+                return parsed;
+            }
+        }
+        catch {
+            // Missing or unreadable file falls through to an empty store.
+        }
+        return { version: 1, schedules: [] };
+    }
+    function write(file) {
+        if (directory)
+            mkdirSync(directory, { recursive: true, mode: 0o700 });
+        else
+            ensureSecureHomeDir();
+        writeSecureFile(path(), `${JSON.stringify(file, null, 2)}\n`);
+    }
+    function mustFind(file, id) {
+        const entry = file.schedules.find((candidate) => candidate.id === id);
+        if (!entry)
+            throw new Error(`No schedule with id ${id}. List entries with \`fullstackgtm schedule list\`.`);
+        return entry;
+    }
+    return {
+        async add(entry) {
+            const file = read();
+            if (file.schedules.some((candidate) => candidate.id === entry.id)) {
+                throw new Error(`Schedule ${entry.id} already exists.`);
+            }
+            file.schedules.push(entry);
+            write(file);
+            return entry;
+        },
+        async list() {
+            return read().schedules;
+        },
+        async get(id) {
+            return read().schedules.find((candidate) => candidate.id === id) ?? null;
+        },
+        async remove(id) {
+            const file = read();
+            const remaining = file.schedules.filter((candidate) => candidate.id !== id);
+            if (remaining.length === file.schedules.length)
+                return false;
+            write({ ...file, schedules: remaining });
+            return true;
+        },
+        async setEnabled(id, enabled) {
+            const file = read();
+            const entry = mustFind(file, id);
+            entry.enabled = enabled;
+            write(file);
+            return entry;
+        },
+    };
+}
+export function createFileScheduleRunStore(directory) {
+    const baseDir = () => directory ?? scheduleRunsDir();
+    function dirFor(scheduleId) {
+        if (!/^[\w.-]+$/.test(scheduleId))
+            throw new Error(`Invalid schedule id: ${scheduleId}`);
+        return join(baseDir(), scheduleId);
+    }
+    return {
+        async record(run) {
+            const dir = dirFor(run.scheduleId);
+            if (!directory)
+                ensureSecureHomeDir();
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+            // ISO timestamps carry ":" — sanitize for the filename, keep the record verbatim.
+            const fileName = `${run.firedAt.replace(/[:.]/g, "-")}.json`;
+            writeSecureFile(join(dir, fileName), `${JSON.stringify(run, null, 2)}\n`);
+            return run;
+        },
+        async list(scheduleId, limit) {
+            let names = [];
+            try {
+                names = readdirSync(dirFor(scheduleId)).filter((name) => name.endsWith(".json"));
+            }
+            catch {
+                return [];
+            }
+            const runs = names
+                .sort()
+                .map((name) => {
+                try {
+                    return JSON.parse(readFileSync(join(dirFor(scheduleId), name), "utf8"));
+                }
+                catch {
+                    return null;
+                }
+            })
+                .filter((run) => run !== null);
+            return limit !== undefined && limit >= 0 ? runs.slice(-limit) : runs;
+        },
+    };
+}
+/**
+ * The real user crontab via `crontab -l` / `crontab -`. Everything above this
+ * function takes a CrontabIo so tests inject fakes and never touch it.
+ */
+export function systemCrontabIo() {
+    return {
+        read() {
+            const result = spawnSync("crontab", ["-l"], { encoding: "utf8" });
+            if (result.error)
+                throw new Error(`Cannot run \`crontab\`: ${result.error.message}`);
+            if (result.status !== 0) {
+                // "no crontab for <user>" exits 1: an empty crontab, not a failure.
+                if (/no crontab/i.test(result.stderr ?? ""))
+                    return "";
+                throw new Error(`\`crontab -l\` failed: ${(result.stderr ?? "").trim()}`);
+            }
+            return result.stdout ?? "";
+        },
+        write(content) {
+            const result = spawnSync("crontab", ["-"], { input: content, encoding: "utf8" });
+            if (result.error)
+                throw new Error(`Cannot run \`crontab\`: ${result.error.message}`);
+            if (result.status !== 0) {
+                throw new Error(`crontab rejected the rendered block: ${(result.stderr ?? "").trim()}`);
+            }
+        },
+    };
+}
+export function crontabSentinels(profile) {
+    return {
+        open: `# >>> fullstackgtm ${profile} >>>`,
+        close: `# <<< fullstackgtm ${profile} <<<`,
+    };
+}
+/**
+ * Render the managed block for one profile. Every line invokes
+ * `... schedule run <id> --profile <profile> --trigger cron` — the single
+ * provider entry point — so the crontab a user audits never contains anything
+ * but fullstackgtm dispatch (no arbitrary shell, ever).
+ */
+export function renderManagedBlock(profile, entries, cliInvocation) {
+    const { open, close } = crontabSentinels(profile);
+    const lines = [
+        open,
+        "# Managed by `fullstackgtm schedule install` — replaced wholesale on re-install; do not edit.",
+    ];
+    for (const entry of entries) {
+        lines.push(`# ${entry.label} (${entry.id}): ${entry.argv.join(" ")}`);
+        lines.push(`${entry.cron} ${cliInvocation} schedule run ${entry.id} --profile ${profile} --trigger cron`);
+    }
+    lines.push(close);
+    return lines.join("\n");
+}
+/**
+ * Replace (or with `block: null`, remove) the profile's managed block in the
+ * crontab content, byte-for-byte preserving everything outside the sentinels.
+ * Idempotent: re-applying the same block yields identical content.
+ */
+export function replaceManagedBlock(existing, profile, block) {
+    const { open, close } = crontabSentinels(profile);
+    const lines = existing.split("\n");
+    const start = lines.indexOf(open);
+    const end = lines.indexOf(close);
+    let before;
+    let after;
+    if (start !== -1 && end !== -1 && end > start) {
+        before = lines.slice(0, start);
+        after = lines.slice(end + 1);
+    }
+    else if (start !== -1 || end !== -1) {
+        throw new Error(`The crontab contains a damaged fullstackgtm block for profile "${profile}" ` +
+            "(one sentinel without its pair). Repair it by hand, then re-run install.");
+    }
+    else {
+        before = lines;
+        after = [];
+    }
+    const merged = [...before];
+    if (block !== null) {
+        if (merged.length > 0 && merged[merged.length - 1].trim() !== "")
+            merged.push("");
+        merged.push(...block.split("\n"));
+    }
+    merged.push(...after);
+    while (merged.length > 0 && merged[0].trim() === "")
+        merged.shift();
+    while (merged.length > 0 && merged[merged.length - 1].trim() === "")
+        merged.pop();
+    if (merged.length === 0)
+        return "";
+    return `${merged.join("\n")}\n`;
+}

package/llms.txt

@@ -14,6 +14,7 @@ at/above `--fail-on`.
 
 - [README](https://github.com/fullstackgtm/core/blob/main/README.md): install, five-minute loop, auth ladder, MCP setup, programmatic use
 - [INSTALL_FOR_AGENTS](https://github.com/fullstackgtm/core/blob/main/INSTALL_FOR_AGENTS.md): deterministic install-and-verify steps with expected outputs
+- [Agent skill](https://github.com/fullstackgtm/core/blob/main/skills/fullstackgtm/SKILL.md): compact operating guide, installable via `npx skills add fullstackgtm/core`
 - [API reference](https://github.com/fullstackgtm/core/blob/main/docs/api.md): semver-covered surfaces — canonical model, rule interface, plan/apply contract, connector contract, config, CLI, MCP tools
 - [CRM-health lifecycle](https://github.com/fullstackgtm/core/blob/main/docs/crm-health-lifecycle.md): the Prevent → Detect → Remediate → Verify/Attribute model; no-new-dupes design
 - [CHANGELOG](https://github.com/fullstackgtm/core/blob/main/CHANGELOG.md): release history
@@ -87,6 +88,25 @@ CAS). Conflict policy MVP is `never`; `system-only`/`always` are phase 2 and
 refused explicitly. Run store (checkpoint + staleness ledger + `status`) is
 profile-scoped under `<home>/enrich/runs`. No cron — scheduling is horizontal.
 
+## Key invariants (schedule)
+
+`fullstackgtm schedule` is the horizontal scheduler — no feature namespace
+owns cron logic. `add "<command>" --cron "<expr>"` validates the command
+against the read/plan-side allowlist (audit, snapshot, enrich append|refresh,
+market capture|refresh, suggest, report, doctor) and the 5-field cron
+expression, but touches no crontab; `install` materializes enabled entries
+into a sentinel-delimited managed block (`# >>> fullstackgtm <profile> >>>`)
+replaced wholesale on re-install, lines outside it untouched; `uninstall`
+removes only the block. Scheduling never auto-approves: `apply` is
+schedulable ONLY as `apply --plan-id <id>` and every firing re-checks the
+plan is approved — unapproved plans record a `plan_not_approved` no-op run,
+no flag relaxes this. `schedule run <id>` is the single provider entry point
+(in-process dispatch, never shell); run records (exit code, output tail,
+artifacts: plan ids / enrich run labels, trigger cron|manual) land under
+`<home>/schedule/runs/<id>/`. `status` shows next firing and surfaces missed
+firings (visibility only — local cron has no catch-up). Providers beyond
+`local` are not yet implemented (future: codegen scaffolds, same contract).
+
 ## Key invariants
 
 - Reads are safe by default; nothing is written without explicit `--approve`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.23.2",
+  "version": "0.25.0",
   "description": "Open-source agentic GTM ops framework: canonical GTM data model, pluggable deterministic audits, reviewable dry-run patch plans, approval-gated write-back with conflict detection, and cross-system entity resolution. HubSpot, Salesforce, and Stripe connectors included.",
   "license": "Apache-2.0",
   "author": "Full Stack GTM",
@@ -30,6 +30,7 @@
     "CHANGELOG.md",
     "INSTALL_FOR_AGENTS.md",
     "llms.txt",
+    "skills",
     "LICENSE"
   ],
   "scripts": {