fullstackgtm 0.23.1 → 0.24.0

package/CHANGELOG.md

@@ -5,6 +5,70 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project adheres to [Semantic Versioning](https://semver.org/).
 The path to 1.0 is planned in [docs/roadmap-to-1.0.md](./docs/roadmap-to-1.0.md).
 
+## [0.24.0] — 2026-06-12
+
+### Added
+
+- **The schedule layer (MVP)** — the horizontal scheduler (spec:
+  docs/schedule.md in the monorepo): declare once that a CLI command should
+  run on a cadence, materialize the timers through a provider, and keep an
+  append-only run history. No feature namespace owns cron logic.
+  - The governance invariant: **scheduling never auto-approves.** The
+    schedulable allowlist is read/plan-side only (`audit`, `snapshot`,
+    `enrich append|refresh`, `market capture|refresh`, `suggest`, `report`,
+    `doctor`) — unattended runs accumulate proposals, never CRM writes.
+    `apply` is schedulable ONLY as `apply --plan-id <id>`, and every firing
+    re-checks the plan's status is `approved`: an unapproved plan records a
+    `plan_not_approved` no-op run instead of executing, with no relaxing
+    flag. Argv must resolve to a known fullstackgtm command — validated at
+    `add` time AND re-checked at run time; arbitrary shell is not
+    schedulable (execution dispatches in-process, never through a shell).
+  - `schedule add "<command>" --cron "<expr>" [--label <name>]
+    [--provider local]` — allowlist + cron validation, then a declarative
+    entry in `~/.fullstackgtm/profiles/<profile>/schedules.json`; nothing
+    touches the crontab until `install` (the plan/apply split: declare,
+    then deliberately activate). Plus `list`, `remove`, `enable|disable`.
+  - `schedule run <id>` — the single entry point every provider's timer
+    calls (and a human can call: `trigger: manual` vs `cron`). Executes the
+    command in-process, records exit code, ~50-line output tail, and
+    artifacts (plan ids / enrich run labels, attributed by store diff)
+    under `<profile>/schedule/runs/<id>/`, and propagates the exit code.
+  - `schedule install|uninstall [--provider local]` — renders enabled
+    entries into a sentinel-delimited managed crontab block
+    (`# >>> fullstackgtm <profile> >>>` … `# <<< fullstackgtm <profile> <<<`);
+    re-install replaces the block wholesale and never touches lines outside
+    the sentinels; uninstall removes only the block. Crontab access is an
+    injected seam (`CrontabIo`) — tests never read or write a real crontab.
+    Providers beyond `local` (`modal`, `aws`) are refused as "not yet
+    implemented"; they arrive later as scaffold generators calling the same
+    `schedule run <id>` contract.
+  - `schedule status [<id>] [--runs <n>]` — next firing per the cron
+    expression, last run + success/failure streak + artifacts, and missed
+    firings (expected-vs-actual since the last run record; visibility only,
+    no catch-up — local cron skips silently when the laptop sleeps).
+  - Minimal dependency-free 5-field cron parser: `*`, lists, ranges, steps,
+    day-of-week 7=Sunday, vixie day-of-month/day-of-week OR semantics;
+    clear validation errors at `add` time (including expressions that never
+    fire), next-firing computation for `status`.
+
+## [0.23.2] — 2026-06-12
+
+Documentation catch-up: the README, llms.txt, and docs/api.md now cover
+everything that shipped 0.19–0.23. (No code changes.)
+
+### Fixed
+
+- README: new "Routine maintenance as governed verbs" section (`bulk-update`,
+  `dedupe`, `reassign`, `fix`) and a market-map paragraph for `market overlay`
+  (directives from your own ground truth) and `market scale` (citable,
+  calibrated size estimates).
+- llms.txt: governed-write-verbs invariants block; overlay/scale invariants
+  added to the market-map block.
+- docs/api.md: CLI command list completed (write verbs, `enrich`, market
+  `overlay`/`scale`); new "Governed write verbs" and "Enrich" export
+  sections; market-map section updated for 0.16–0.23 exports incl.
+  `computeDirectives`/`directivesToPlan` and `computeScaleIndex`.
+
 ## [0.23.1] — 2026-06-12
 
 ### Fixed

package/README.md

@@ -109,6 +109,22 @@ npx fullstackgtm report --provider hubspot --client "Acme" --out acme-health.htm
 
 `report` renders the same audit as a deliverable — severity counts up front, a prose summary, per-rule detail with example records, and next steps — as markdown or self-contained HTML (printable, emailable, no external assets).
 
+## Routine maintenance as governed verbs: bulk-update, dedupe, reassign, fix
+
+The maintenance work RevOps actually does in bulk — backfills, book transfers, duplicate sweeps, "just fix everything that rule found" — gets first-class verbs. Each one *builds a plan*; nothing executes without the same approve → apply gauntlet as everything else.
+
+```bash
+fullstackgtm bulk-update deal --where "stage=closedwon" --where "amount:empty" \
+  --set amount=from:account.annualrevenue --save     # per-record derived values; empty sources skipped, never guessed
+fullstackgtm dedupe account --key domain --keep richest --save   # one merge_records op per duplicate group
+fullstackgtm reassign --from 411 --to 902 --except-deal-stage closing --save   # ownership handoff playbook
+fullstackgtm fix --rule missing-deal-owner --provider hubspot --yes  # audit one rule → suggest → approve → apply, one command
+```
+
+`bulk-update` filters the snapshot (`=`, `!=`, `~` substring, `:empty`/`:notempty`, `|` any-of, relational pseudo-fields like `account.domain` or `openDealStages`) into a dry-run patch plan — and **the full filter is re-verified per record at apply time**, with mid-apply rechecks, so a record that stopped matching between audit and apply is skipped, not clobbered. Equality filters double as preconditions; `--require` adds explicit ones; `--guard` asserts cross-record conditions; `--max-operations` caps blast radius. `--set field=from:<sourceField>` derives values per record; `--archive` refuses records whose identity key (account domain, contact email) is shared with another record — that's a duplicate, and duplicates are merged with `dedupe`, not archived around.
+
+`dedupe` finds duplicate groups by normalized identity key and emits one `merge_records` operation per group with a deterministic survivor (`richest` = most populated fields, ties to lowest id; `oldest`). Merges stay irreversible-and-therefore-low-confidence-capped on approval, exactly like merge suggestions from the audit. `reassign` is the ownership-handoff playbook: one plan per object type, extra scoping account-lifted to deals and contacts, and `--except-deal-stage` excludes both deals in that stage and every record whose account has an open deal in it. `fix` is the one-shot composite for a single rule: audit → save → suggest → approve suggestion-backed operations at the confidence bar → with `--yes`, apply and print the stage-by-stage summary; without it, stop after approval and print the apply command.
+
 ## The market map: the category, observed
 
 Your CRM records what happened in your own deals; nothing records the shape of the category you sell into. The **market map** does: vendors and a claim taxonomy live in a reviewable `market.config.json`, vendor pages are captured into a content-addressed cache, every vendor × claim cell gets a messaging-intensity reading (LOUD / QUIET / ABSENT — with UNOBSERVABLE for failed captures, never a fake absence), and deterministic front states fall out per claim: open, contested, owned, saturated.
@@ -126,6 +142,8 @@ The discipline matches the rest of the tool. Intensity readings are *proposals*
 
 `market axes` is for earning a strategic 2×2 instead of asserting one: PCA over the intensity matrix (PC1 = the category's own primary axis, PC2 = the most differentiating direction orthogonal to it), triangulation of your configured axes against the data, and an orthogonality screen that flags two axes that are secretly one. Axes are claim-scoring rubrics in the config; the report renders the primary pair as the strategic map. Captures and observations are profile-scoped (`~/.fullstackgtm/market/<category>`), so one client's category intel never bleeds into another's.
 
+Two more derivations close the loop from map to action. `market overlay --snapshot <crm.json> [--calls <files>]` joins the observation store against your own ground truth — which claims and vendors actually come up in your deals and call transcripts (deterministic word-boundary matching, no LLM) — and emits OCCUPY / PROMOTE / URGENT / RETREAT directives, each carrying at least one observation and one CRM stat with its sample size; below the evidence thresholds the honest answer is *no directive*. `--save` turns directives into approval-gated `create_task` operations through the normal plan chain. `market scale` estimates each vendor's size from **citable** signals you record in the config (G2 review counts, LinkedIn headcount, revenue claims — each with source URL, verbatim quote, and caveat): every signal is converted into revenue space first, calibrated within the vendor set and stratified by ACV band, then combined as a weighted geometric mean with the uncertainty spread and calibration table disclosed. The report's strategic-map bubbles become area-proportional to estimated revenue share — captioned "citable but NOT audited" — and without signals, dots are uniform and the caption says size carries no meaning.
+
 ## Governed enrichment: a diff you approve before third-party data touches your CRM
 
 Every enrichment vendor ships fire-and-forget writeback. The **enrich layer** inverts that: declare once which fields come from which source under which conflict policy (`enrich.config.json` — sources, ordered match keys, field mappings, policy), then `enrich append` fills the gaps and `enrich refresh` keeps them current — with every write passing through the normal dry-run → approval → apply contract, and every value traceable to the source payload that produced it.
@@ -141,6 +159,24 @@ fullstackgtm enrich status --runs                           # last run per sourc
 
 Matching is deterministic: ordered keys, unique hit wins, zero hits falls through to the next key, and multiple hits are never guessed away — they skip (recorded with candidate ids) or flow into the existing `suggest` → `plans approve` chain as `requires_human_record_selection` placeholders. The MVP conflict policy is `never`: enrich only fills blank fields, and `refresh` only re-touches fields its own run-store ledger proves it stamped (per-record/per-field `enrichedAt`, profile-scoped, never written into your portal as custom properties). The `system-only` and `always` rungs of the ladder are phase 2 and are refused explicitly, not silently accepted. Recurring execution belongs to the scheduler — enrich owns no cron logic.
 
+## Schedules: declare a cadence once, keep the governance contract under automation
+
+Everything the CLI produces is accurate the moment it runs and silently stale afterward. The **schedule layer** is the horizontal fix — any read/plan-side command on a cron cadence, one component, every verb (no feature owns its own cron logic):
+
+```bash
+fullstackgtm schedule add "enrich refresh --source apollo --save" --cron "0 6 * * 1" --label weekly-apollo
+fullstackgtm schedule add "audit --provider hubspot --save" --cron "0 2 * * *"   # nightly drift baseline
+fullstackgtm schedule list                       # declarative entries; nothing runs yet
+fullstackgtm schedule install                    # materialize enabled entries into a managed crontab block
+fullstackgtm schedule run <id>                   # execute now; same run record a cron firing produces
+fullstackgtm schedule status --runs 5            # last runs, exit codes, artifacts, next + missed firings
+fullstackgtm schedule uninstall                  # remove the managed block, touch nothing else
+```
+
+**Scheduling never auto-approves.** Schedulable commands are read/plan-side only — `audit`, `snapshot`, `enrich append|refresh`, `market capture|refresh`, `suggest`, `report`, `doctor` — so unattended runs accumulate *proposals* (plans in the queue, run records, reports), never CRM writes. `apply` is schedulable only as `apply --plan-id <id>`, and every firing re-checks the plan's status is approved: an unapproved plan records a `plan_not_approved` no-op run instead of executing, and no flag relaxes this. Arbitrary shell is not schedulable — an entry's argv must resolve to a known fullstackgtm command (validated at `add` time and re-checked at run time), and the crontab line you audit is always `fullstackgtm schedule run <id>` and nothing else.
+
+`install` renders enabled entries into a sentinel-delimited block (`# >>> fullstackgtm <profile> >>>` … `# <<< fullstackgtm <profile> <<<`) in your user crontab; re-install replaces the block wholesale and never touches lines outside it. Honest limitation: local cron has no catch-up — a laptop asleep at firing time means a missed run. `schedule status` surfaces missed firings by comparing expected-vs-actual run history, so the gap is at least visible. Entries are provider-agnostic; cloud providers (Modal, AWS) arrive as scaffold generators that call the same `schedule run <id>` contract, and are refused as "not yet implemented" until then.
+
 ### Working across organizations
 
 Consultants and fractional operators hold credentials for several CRMs at once. A profile scopes stored logins *and* stored plans to one organization:

package/dist/cli.js

@@ -27,6 +27,7 @@ import { marketMapToHtml, marketMapToMarkdown } from "./marketReport.js";
 import { DEFAULT_RUBRIC, detectProviderFromKey, extractInsightsLlm, parseRubric, resolveLlmCredential, scoreCallLlm, validateLlmKey, } from "./llm.js";
 import { buildEnrichPlan, createFileEnrichRunStore, DEFAULT_STALE_DAYS, ENRICH_CONFIG_FILE_NAME, enrichRunId, inferIngestObjectType, latestStamps, loadEnrichConfig, parseCsv, resolveCrmField, selectStaleWork, stagedSourceRecords, staleDaysFor, } from "./enrich.js";
 import { apolloPullKeysForAppend, apolloPullKeysForRefresh, createApolloClient, pullApolloRecords, } from "./enrichApollo.js";
+import { computeMissedFirings, createFileScheduleRunStore, createFileScheduleStore, nextCronFiring, parseCron, renderManagedBlock, replaceManagedBlock, scheduleId, systemCrontabIo, tokenizeCommand, validateSchedulableArgv, } from "./schedule.js";
 import { resolveRecord } from "./resolve.js";
 import { buildBulkUpdatePlan } from "./bulkUpdate.js";
 import { buildDedupePlan } from "./dedupe.js";
@@ -134,6 +135,16 @@ Usage:
                                                value) → with --yes, apply through the provider and print a
                                                stage-by-stage summary. Without --yes it stops after
                                                approval and prints the apply command.
+  fullstackgtm schedule add "<command>" --cron "<expr>" [--label <name>] [--provider local]
+  fullstackgtm schedule list | remove <id> | enable <id> | disable <id> | run <id>
+  fullstackgtm schedule install | uninstall [--provider local]
+  fullstackgtm schedule status [<id>] [--runs <n>]
+                                               declare a cadence for any read/plan-side command (audit,
+                                               snapshot, enrich append|refresh, market capture|refresh,
+                                               suggest, report, doctor); install materializes enabled
+                                               entries into a sentinel-delimited managed crontab block.
+                                               Scheduling never auto-approves: apply is schedulable only
+                                               as apply --plan-id <id>, re-checked approved at run time.
   fullstackgtm suggest --plan-id <id> | --plan <path>  [source options] [--json] [--out <path>]
                                                derive values for requires_human_* placeholders
                                                from snapshot evidence, with confidence + reasons
@@ -1532,6 +1543,388 @@ async function enrichStatus(store, rest, configFile) {
         }
     }
 }
+/**
+ * The schedule layer: declarative cadences for read/plan-side commands,
+ * materialized through a provider (MVP: the user crontab), with an
+ * append-only run history. The governance invariant — scheduling never
+ * auto-approves — is enforced at `add` time and re-checked at `run` time.
+ * Spec: docs/schedule.md (monorepo).
+ */
+async function scheduleCommand(args) {
+    const [subcommand, ...rest] = args;
+    // Catch --help BEFORE any store read, credential access, or crontab
+    // round-trip (the enrich/market early-catch pattern — `schedule install
+    // --help` must never touch the crontab).
+    if (!subcommand || subcommand === "--help" || subcommand === "-h" || rest.includes("--help") || rest.includes("-h")) {
+        console.log(`Usage:
+schedule add "<fullstackgtm command>" --cron "<expr>" [--label <name>] [--provider local]
+schedule list [--json]
+schedule remove <id>
+schedule enable <id> | disable <id>
+schedule run <id>                     execute now; the single entry point every provider's timer calls
+schedule install [--provider local]   render enabled entries into the managed crontab block
+schedule uninstall [--provider local] remove the managed block (nothing else)
+schedule status [<id>] [--runs <n>] [--json]
+
+add validates the command against the schedulable allowlist — read/plan-side
+only: audit, snapshot, enrich append|refresh, market capture|refresh,
+suggest, report, doctor — and parses the 5-field cron expression (*, lists,
+ranges, steps), but touches NO crontab: entries are declarative until install
+materializes them (the plan/apply split — declare, then deliberately
+activate).
+
+Scheduling never auto-approves. apply is schedulable ONLY as
+\`apply --plan-id <id>\`, and every firing re-checks the plan's status is
+approved — an unapproved plan records a plan_not_approved no-op run instead
+of executing. There is no flag that relaxes this. Unattended runs accumulate
+proposals (plans, run records, reports), never surprise CRM writes.
+
+install renders all enabled entries into a sentinel-delimited block
+(# >>> fullstackgtm <profile> >>> ... # <<< fullstackgtm <profile> <<<) in
+the user crontab; each line invokes \`schedule run <id> --profile <profile>\`
+and nothing else. Re-install replaces the block wholesale and never touches
+lines outside the sentinels. Providers other than local (modal, aws) are not
+yet implemented — they will be scaffold generators calling the same
+\`schedule run\` contract.
+
+run executes the command in-process and records the outcome (exit code,
+output tail, artifacts: plan ids / enrich run labels) under the profile's
+schedule/runs/<id>/; the exit code propagates. Manual runs record
+trigger: manual. status shows next firing and surfaces missed firings
+(laptop asleep = cron skips silently; visibility only, no catch-up).`);
+        return;
+    }
+    const store = createFileScheduleStore();
+    const runStore = createFileScheduleRunStore();
+    if (subcommand === "add") {
+        const commandText = rest.find((arg) => !arg.startsWith("--") && !isOptionValue(rest, arg));
+        if (!commandText) {
+            throw new Error('Usage: fullstackgtm schedule add "<fullstackgtm command>" --cron "<expr>" [--label <name>] [--provider local]');
+        }
+        const cronText = option(rest, "--cron");
+        if (!cronText)
+            throw new Error('schedule add requires --cron "<minute hour day-of-month month day-of-week>"');
+        requireLocalScheduleProvider(option(rest, "--provider") ?? "local");
+        let argv = tokenizeCommand(commandText);
+        if (argv[0] === "fullstackgtm")
+            argv = argv.slice(1);
+        validateSchedulableArgv(argv);
+        const cron = parseCron(cronText);
+        const next = nextCronFiring(cron, new Date()); // also rejects never-firing expressions
+        const createdAt = new Date().toISOString();
+        const label = option(rest, "--label") ??
+            argv.filter((arg) => !arg.startsWith("--")).slice(0, 2).join("-").replace(/[^\w.-]+/g, "-");
+        const entry = {
+            id: scheduleId(label, cron.source, argv, createdAt),
+            label,
+            argv,
+            cron: cron.source,
+            provider: "local",
+            enabled: true,
+            createdAt,
+        };
+        await store.add(entry);
+        console.log(`Added ${entry.id} "${label}": \`${argv.join(" ")}\` at \`${cron.source}\` (next firing: ${next.toISOString()}).`);
+        console.log("Declarative until materialized — activate with `fullstackgtm schedule install`.");
+        return;
+    }
+    if (subcommand === "list") {
+        const entries = await store.list();
+        const now = new Date();
+        const withNext = entries.map((entry) => ({
+            ...entry,
+            nextFiring: entry.enabled ? safeNextFiring(entry.cron, now) : null,
+        }));
+        if (rest.includes("--json")) {
+            console.log(JSON.stringify(withNext, null, 2));
+            return;
+        }
+        if (entries.length === 0) {
+            console.log('No schedules. Add one with `fullstackgtm schedule add "<command>" --cron "<expr>"`.');
+            return;
+        }
+        for (const entry of withNext) {
+            console.log(`${entry.id}  ${entry.enabled ? "on " : "off"}  ${entry.cron.padEnd(14)} next ${entry.nextFiring ?? "—"}  ${entry.label}: ${entry.argv.join(" ")}`);
+        }
+        console.log("\nEntries are declarative — `schedule install` materializes enabled ones into the crontab.");
+        return;
+    }
+    if (subcommand === "remove") {
+        const id = positionalArg(rest, "Usage: fullstackgtm schedule remove <id>");
+        if (!(await store.remove(id)))
+            throw new Error(`No schedule with id ${id}.`);
+        console.log(`Removed ${id}. Run \`fullstackgtm schedule install\` to update the crontab block.`);
+        return;
+    }
+    if (subcommand === "enable" || subcommand === "disable") {
+        const id = positionalArg(rest, `Usage: fullstackgtm schedule ${subcommand} <id>`);
+        const entry = await store.setEnabled(id, subcommand === "enable");
+        console.log(`${subcommand === "enable" ? "Enabled" : "Disabled"} ${entry.id} "${entry.label}". ` +
+            "Run `fullstackgtm schedule install` to update the crontab block.");
+        return;
+    }
+    if (subcommand === "run") {
+        const id = positionalArg(rest, "Usage: fullstackgtm schedule run <id>");
+        const entry = await store.get(id);
+        if (!entry)
+            throw new Error(`No schedule with id ${id} in profile "${activeProfile()}".`);
+        if (!entry.enabled) {
+            throw new Error(`Schedule ${id} is disabled — enable it with \`fullstackgtm schedule enable ${id}\`.`);
+        }
+        const trigger = (option(rest, "--trigger") ?? "manual");
+        if (trigger !== "cron" && trigger !== "manual") {
+            throw new Error("--trigger must be cron or manual");
+        }
+        const run = await executeScheduledRun(entry, trigger);
+        if (run.exitCode !== 0)
+            process.exitCode = run.exitCode;
+        return;
+    }
+    if (subcommand === "install" || subcommand === "uninstall") {
+        requireLocalScheduleProvider(option(rest, "--provider") ?? "local");
+        const profile = activeProfile();
+        const io = systemCrontabIo();
+        const existing = io.read();
+        if (subcommand === "uninstall") {
+            io.write(replaceManagedBlock(existing, profile, null));
+            console.log(`Removed the fullstackgtm managed crontab block for profile "${profile}" (lines outside the sentinels untouched).`);
+            return;
+        }
+        const enabled = (await store.list()).filter((entry) => entry.enabled && entry.provider === "local");
+        if (enabled.length === 0) {
+            io.write(replaceManagedBlock(existing, profile, null));
+            console.log(`No enabled schedules for profile "${profile}" — removed the managed block.`);
+            return;
+        }
+        const block = renderManagedBlock(profile, enabled, scheduleCliInvocation());
+        io.write(replaceManagedBlock(existing, profile, block));
+        console.log(`Installed ${enabled.length} schedule(s) into the managed crontab block for profile "${profile}". ` +
+            "Re-running install replaces the block wholesale; `schedule uninstall` removes it.");
+        return;
+    }
+    if (subcommand === "status") {
+        const id = rest.find((arg) => !arg.startsWith("--") && !isOptionValue(rest, arg));
+        const entries = await store.list();
+        const selected = id ? entries.filter((entry) => entry.id === id) : entries;
+        if (id && selected.length === 0)
+            throw new Error(`No schedule with id ${id}.`);
+        if (selected.length === 0) {
+            console.log('No schedules. Add one with `fullstackgtm schedule add "<command>" --cron "<expr>"`.');
+            return;
+        }
+        const showRuns = numericOption(rest, "--runs");
+        const now = new Date();
+        const report = [];
+        for (const entry of selected) {
+            const runs = await runStore.list(entry.id);
+            const last = runs.length > 0 ? runs[runs.length - 1] : null;
+            let streak = 0;
+            for (let index = runs.length - 1; index >= 0; index -= 1) {
+                if ((runs[index].exitCode === 0) !== (last.exitCode === 0))
+                    break;
+                streak += 1;
+            }
+            const missed = computeMissedFirings(entry, runs, now);
+            report.push({
+                id: entry.id,
+                label: entry.label,
+                argv: entry.argv,
+                cron: entry.cron,
+                enabled: entry.enabled,
+                nextFiring: entry.enabled ? safeNextFiring(entry.cron, now) : null,
+                lastRun: last
+                    ? {
+                        firedAt: last.firedAt,
+                        trigger: last.trigger,
+                        exitCode: last.exitCode,
+                        noopReason: last.noopReason,
+                        artifacts: last.artifacts,
+                    }
+                    : null,
+                streak: last ? { outcome: last.exitCode === 0 ? "success" : "failure", length: streak } : null,
+                missedFirings: missed.missed.map((firing) => firing.toISOString()),
+                missedFiringsCapped: missed.capped,
+                runs: showRuns !== undefined ? runs.slice(-showRuns) : undefined,
+            });
+        }
+        if (rest.includes("--json")) {
+            console.log(JSON.stringify(report, null, 2));
+            return;
+        }
+        for (const entry of report) {
+            const last = entry.lastRun;
+            const streak = entry.streak;
+            const missed = entry.missedFirings;
+            console.log(`${entry.id}  ${entry.enabled ? "on " : "off"}  ${entry.cron}  ${entry.label}: ${entry.argv.join(" ")}`);
+            console.log(`  next: ${entry.nextFiring ?? "— (disabled)"}`);
+            if (last) {
+                const artifacts = [
+                    ...last.artifacts.planIds.map((planId) => `plan ${planId}`),
+                    ...last.artifacts.runLabels.map((runLabel) => `run ${runLabel}`),
+                ];
+                console.log(`  last: ${last.firedAt} (${last.trigger}) exit ${last.exitCode}` +
+                    (last.noopReason ? ` — no-op: ${last.noopReason}` : "") +
+                    (artifacts.length ? ` — ${artifacts.join(", ")}` : ""));
+                console.log(`  streak: ${streak.length} ${streak.outcome}(s)`);
+            }
+            else {
+                console.log("  last: never fired");
+            }
+            if (missed.length > 0) {
+                console.log(`  missed: ${missed.length}${entry.missedFiringsCapped ? "+" : ""} expected firing(s) with no run record ` +
+                    `(latest: ${missed[missed.length - 1]}) — local cron has no catch-up; this is visibility only`);
+            }
+            const runs = entry.runs;
+            if (runs) {
+                for (const run of runs) {
+                    console.log(`    ${run.firedAt}  ${run.trigger.padEnd(6)} exit ${run.exitCode}${run.noopReason ? `  no-op: ${run.noopReason}` : ""}`);
+                }
+            }
+        }
+        return;
+    }
+    throw new Error(`Unknown schedule subcommand: ${subcommand} (try: add, list, remove, enable, disable, run, install, uninstall, status)`);
+}
+function positionalArg(rest, usage) {
+    const value = rest.find((arg) => !arg.startsWith("--") && !isOptionValue(rest, arg));
+    if (!value)
+        throw new Error(usage);
+    return value;
+}
+function safeNextFiring(cron, now) {
+    try {
+        return nextCronFiring(parseCron(cron), now).toISOString();
+    }
+    catch {
+        return null;
+    }
+}
+/** The provider seam: local ships now; modal/aws arrive as scaffold generators. */
+function requireLocalScheduleProvider(provider) {
+    if (provider === "local")
+        return;
+    if (provider === "modal" || provider === "aws") {
+        throw new Error(`Provider "${provider}" is not yet implemented — it will be a scaffold generator that emits a ` +
+            "deploy-ready artifact whose runner calls the same `schedule run <id>` contract. MVP provider: local.");
+    }
+    throw new Error(`Unknown provider "${provider}" — not yet implemented. MVP provider: local.`);
+}
+/**
+ * Resolve how cron should invoke this CLI: the current node binary plus the
+ * entry script (source checkouts need --experimental-strip-types), with
+ * FSGTM_HOME pinned when set so the cron environment sees the same store.
+ */
+function scheduleCliInvocation() {
+    const script = process.argv[1] ? resolve(process.argv[1]) : null;
+    if (!script || !existsSync(script)) {
+        throw new Error("Cannot resolve the fullstackgtm entry point for crontab lines (process.argv[1] is missing).");
+    }
+    const quote = (value) => `'${value.replace(/'/g, `'\\''`)}'`;
+    const parts = [quote(process.execPath)];
+    if (script.endsWith(".ts"))
+        parts.push("--experimental-strip-types");
+    parts.push(quote(script));
+    const home = process.env.FSGTM_HOME ? `FSGTM_HOME=${quote(process.env.FSGTM_HOME)} ` : "";
+    return home + parts.join(" ");
+}
+/**
+ * The single provider entry point: execute the scheduled command in-process
+ * (dispatch into the CLI router — never a shell), capture the output tail and
+ * exit code as a run record, and hand the exit code back to the caller. Cron
+ * calls it, cloud providers will call it, and a human running it manually
+ * produces the same record (trigger: manual).
+ *
+ * Governance re-checks happen here, not just at `add` time: the allowlist is
+ * re-validated (schedules.json is user-editable), and a scheduled apply
+ * hard-checks the plan is approved — an unapproved plan records a
+ * plan_not_approved no-op run and does NOT execute. Scheduling never
+ * auto-approves.
+ */
+async function executeScheduledRun(entry, trigger) {
+    const runStore = createFileScheduleRunStore();
+    const firedAt = new Date().toISOString();
+    const noop = async (reason, exitCode, message) => {
+        const run = {
+            scheduleId: entry.id,
+            firedAt,
+            completedAt: new Date().toISOString(),
+            trigger,
+            exitCode,
+            outputTail: message,
+            artifacts: { planIds: [], runLabels: [] },
+            noopReason: reason,
+        };
+        await runStore.record(run);
+        console.error(message);
+        return run;
+    };
+    try {
+        validateSchedulableArgv(entry.argv);
+    }
+    catch (error) {
+        return noop("not_schedulable", 1, error instanceof Error ? error.message : String(error));
+    }
+    if (entry.argv[0] === "apply") {
+        const planId = option(entry.argv.slice(1), "--plan-id");
+        const stored = await createFilePlanStore().get(planId);
+        const status = stored ? stored.status : "missing";
+        if (status !== "approved") {
+            // The governance gate holding is not a machinery failure: exit 0, with
+            // the refusal recorded on the run for `schedule status` to surface.
+            return noop("plan_not_approved", 0, `Plan ${planId} is ${status}, not approved — scheduled apply refuses to execute. ` +
+                `Scheduling never auto-approves; review and approve with \`fullstackgtm plans approve ${planId} --operations <ids|all>\`.`);
+        }
+    }
+    // Artifact attribution by store diff: anything new in the plan store or the
+    // enrich run store after the command ran was produced by this firing.
+    const planStore = createFilePlanStore();
+    const plansBefore = new Set((await planStore.list()).map((stored) => stored.plan.id));
+    const enrichStore = createFileEnrichRunStore();
+    const enrichBefore = new Set((await enrichStore.list()).map((run) => run.runLabel));
+    const lines = [];
+    const originalLog = console.log;
+    const originalError = console.error;
+    const tee = (original) => (...args) => {
+        for (const line of args.map(String).join(" ").split("\n"))
+            lines.push(line);
+        original(...args);
+    };
+    console.log = tee(originalLog);
+    console.error = tee(originalError);
+    const priorExitCode = process.exitCode;
+    process.exitCode = undefined;
+    let exitCode = 0;
+    try {
+        await runCli([...entry.argv]);
+        exitCode = typeof process.exitCode === "number" ? process.exitCode : 0;
+    }
+    catch (error) {
+        exitCode = 1;
+        lines.push(error instanceof Error ? error.message : String(error));
+    }
+    finally {
+        console.log = originalLog;
+        console.error = originalError;
+        process.exitCode = priorExitCode;
+    }
+    const planIds = (await planStore.list())
+        .map((stored) => stored.plan.id)
+        .filter((planId) => !plansBefore.has(planId));
+    const runLabels = (await enrichStore.list())
+        .map((run) => run.runLabel)
+        .filter((runLabel) => !enrichBefore.has(runLabel));
+    const run = {
+        scheduleId: entry.id,
+        firedAt,
+        completedAt: new Date().toISOString(),
+        trigger,
+        exitCode,
+        outputTail: lines.slice(-50).join("\n"),
+        artifacts: { planIds, runLabels },
+    };
+    await runStore.record(run);
+    return run;
+}
 /**
  * The resolve gate: exit 0 = safe to create, exit 2 = match found (exists or
  * ambiguous — do NOT blind-create), exit 1 = error. Built for sync jobs and
@@ -2506,8 +2899,8 @@ export async function runCli(argv) {
     }
     // Commands without bespoke help fall back to the top-level usage on --help
     // instead of executing (audit used to silently run the sample audit).
-    // call/market/enrich/bulk-update print their own richer help.
-    if (!["call", "market", "enrich", "bulk-update"].includes(command) && (args.includes("--help") || args.includes("-h"))) {
+    // call/market/enrich/bulk-update/schedule print their own richer help.
+    if (!["call", "market", "enrich", "bulk-update", "schedule"].includes(command) && (args.includes("--help") || args.includes("-h"))) {
         console.log(usage());
         return;
     }
@@ -2575,6 +2968,10 @@ export async function runCli(argv) {
         await enrichCommand(args);
         return;
     }
+    if (command === "schedule") {
+        await scheduleCommand(args);
+        return;
+    }
     if (command === "profiles") {
         profilesCommand(args);
         return;

package/dist/index.d.ts

@@ -30,5 +30,6 @@ export { buildWorksheet, classifyMarket, type ClassifyMarketOptions, type Classi
 export { computeDirectives, computeOverlayStats, directivesToPlan, overlayToMarkdown, type CallDocument, type ClaimMentionStats, type DirectiveStat, type DirectiveType, type MarketDirective, type OverlayOptions, type OverlayStats, type VendorMentionStats, } from "./marketOverlay.ts";
 export { computeScaleIndex, dimensionForMetric, scaleReportToText, type ScaleDimension, type ScaleReport, type SignalEstimate, type VendorScale, } from "./marketScale.ts";
 export { marketMapToHtml, marketMapToMarkdown } from "./marketReport.ts";
+export { computeMissedFirings, createFileScheduleRunStore, createFileScheduleStore, cronMatches, crontabSentinels, expectedFirings, nextCronFiring, parseCron, renderManagedBlock, replaceManagedBlock, scheduleId, scheduleRunsDir, schedulesPath, systemCrontabIo, tokenizeCommand, validateSchedulableArgv, type CronExpression, type CrontabIo, type ScheduleEntry, type ScheduleProvider, type ScheduleRunRecord, type ScheduleRunStore, type ScheduleRunTrigger, type ScheduleStore, } from "./schedule.ts";
 export { suggestValues, type SuggestionConfidence, type ValueSuggestion } from "./suggest.ts";
 export type { ApprovalStatus, AuditFinding, AuditFindingSeverity, CanonicalAccount, CanonicalActivity, CanonicalContact, CanonicalDeal, CanonicalGtmSnapshot, CanonicalUser, CrmProvider, GtmAuditRule, GtmConnector, GtmEvidence, GtmEvidenceSourceSystem, GtmObjectType, GtmPolicy, GtmRuleContext, GtmRuleResult, GtmSnapshotIndex, PatchOperation, PatchOperationResult, PatchOperationType, PatchPlan, PatchPlanRun, PatchPlanRunStatus, PatchVerification, PipelineFinding, PipelineFindingStatus, PipelineFindingType, ProviderIdentity, RiskLevel, SourceFreshness, } from "./types.ts";

package/dist/index.js

@@ -30,4 +30,5 @@ export { buildWorksheet, classifyMarket, } from "./marketClassify.js";
 export { computeDirectives, computeOverlayStats, directivesToPlan, overlayToMarkdown, } from "./marketOverlay.js";
 export { computeScaleIndex, dimensionForMetric, scaleReportToText, } from "./marketScale.js";
 export { marketMapToHtml, marketMapToMarkdown } from "./marketReport.js";
+export { computeMissedFirings, createFileScheduleRunStore, createFileScheduleStore, cronMatches, crontabSentinels, expectedFirings, nextCronFiring, parseCron, renderManagedBlock, replaceManagedBlock, scheduleId, scheduleRunsDir, schedulesPath, systemCrontabIo, tokenizeCommand, validateSchedulableArgv, } from "./schedule.js";
 export { suggestValues } from "./suggest.js";