feat(first-hour): do_first_hour_of_work tool + 7 persona plans + Slack DM renderer (Slice 15a) (#122)

The agent's first action on a fresh tenant is now do_first_hour_of_work,
a single-Sonnet-turn scaffold-driven runner that fires from main()
after the intro DM lands. By the time the user finishes setup, their
named persona has already pulled their morning, drafted their replies,
and DMed them with one click to approve.

Architect: phantom-cloud-deploy/local/2026-05-03-slice-15-first-hour-
of-work-architect.md.

What ships in this PR:

- src/persona/work-plans.ts: code-vendored TypeScript mirror of the
  canonical persona-work-plans.json fixture (slice 15d-fixture, PR
  #22 on phantom-cloud-deploy). Seven personas locked: sdr-lilian,
  eng-cos-marcus, am-sloane, bdr-theo, sales-vp-priya, gtm-eng-ryan,
  founder-asst-adrian. Byte-equal with the canonical for persona_id
  literals and required_integrations arrays.
- src/persona/types.ts: FirstHourOfWorkInput/Output, DraftKind,
  ReasonCode (11-code taxonomy locked at architect §7.2).
- src/persona/scaffold-prompt.ts: the verbatim 4-step prompt from
  architect §1.4 with persona-driven substitutions.
- src/persona/runner.ts: end-to-end orchestrator. Resolves grants
  via the env reader, filters required-integrations against the
  resolved set, builds the prompt scaffold, races the LLM call
  against a 60s AbortController, parses the JSON envelope, persists
  drafts, sends the Block Kit DM, emits the five audit events.
- src/persona/llm-caller.ts: production LlmTurnCaller wrapping
  runtime.handleMessage with a first-hour: session id prefix and
  the JSON envelope parser.
- src/persona/failure-modes.ts: per-persona DM bodies for the six
  failure modes (no_integrations_granted, all_pulls_zero_data,
  llm_error_mid_flow, zero_drafts_from_nonzero_data, integration_
  auth_expired, sixty_second_cap_hit). Verbatim from architect §6.
- src/persona/draft-store.ts: SQLite helpers for the firstboot ledger
  and phantom_drafts table. Status transitions pending -> approved
  -> sent.
- src/persona/firstboot-hook.ts: the index.ts entry point. NO-OP
  when PHANTOM_PERSONA_ID is unset; idempotent on the firstboot
  ledger.
- src/integrations/grants.ts: env-based reader of PHANTOM_GRANTED_
  INTEGRATIONS with slack always granted (the wizard's slot 10
  install is firstboot-baked).
- src/channels/slack/render-first-hour-dm.ts: Block Kit renderer
  for the standard, fallback, and partial DM variants. Action_id
  pattern phantom:draft:{draft_id}:{action} per architect §5.4.
- src/channels/slack/edit-modal.ts: views.open payload for the
  draft edit modal.
- src/db/schema.ts: additive migrations (52-58) for firstboot_state
  ledger columns and the new phantom_drafts table. Idempotent per
  the migration-safety contract.
- src/channels/slack-actions.ts: Bolt regex handler for the
  phantom:draft:{id}:{action} action_id pattern; per-draft buttons
  flip to context blocks on click.
- src/channels/slack.ts: extends sendDm to accept optional Block Kit
  blocks (the HTTP transport already accepted them; Socket Mode
  catches up).
- src/index.ts: fires the firstboot hook after the intro DM lands.
- .github/workflows/ci.yml: persona-work-plans drift verifier step.
  Runs the cross-repo guard from phantom-cloud-deploy in strict mode
  once the canonical fixture lands on main.
- CLAUDE.md: First hour of work invariant section covering the
  contract, idempotency, the action_id wire pattern, and the 60s
  hard cap.

Coverage:

- 111 new tests across work-plans, scaffold-prompt, runner, failure-
  modes, llm-caller, render-first-hour-dm, edit-modal, draft-store,
  firstboot-hook, grants. Snapshot pins on the Block Kit JSON for
  Lilian's full DM and the per-persona header/footer text shape.
- Happy path: drafts persist, DM lands, all five audit events fire
  in order (start, pulls, drafts, dm, finish).
- Each of the six failure modes covered by its own runner test:
  no_integrations_granted, all_pulls_zero_data, llm_error_mid_flow,
  zero_drafts_from_nonzero_data, integration_auth_expired, sixty_
  second_cap_hit. Plus slack_post_failed and persona_unknown.
- Defense-in-depth: a happy-path cycle across all seven personas
  pinning that none degrades to a fallback DM.

Pre-push gate: bun typecheck clean, bun test 2537 pass / 0 fail
(+111 from this slice), bun lint clean.

Author: mcheemaa

.github/workflows/ci.yml

@@ -34,6 +34,24 @@ jobs:
       - name: Test
         run: bun test
 
+      # Slice 15a: persona-work-plans drift guard. The in-VM phantom
+      # mirror at src/persona/work-plans.ts must stay byte-equal with
+      # the canonical fixture at scripts/shared/persona-work-plans.json
+      # in phantom-cloud-deploy. The verifier parses persona_id and
+      # required_integrations literals out of the TS file and diffs
+      # them against the canonical JSON. Strict mode flips on once the
+      # phantom-cloud-deploy fixture lands on main; until then this
+      # step skips on a missing fixture (the slice 15d-fixture PR is
+      # already open at #22).
+      - name: verify persona-work-plans drift
+        run: |
+          git clone --depth 1 https://github.com/ghostwright/phantom-cloud-deploy.git /tmp/pcd || true
+          if [ -f /tmp/pcd/scripts/shared/verify-persona-work-plans.sh ]; then
+            PERSONA_WORK_PLANS_VERIFY_STRICT=1 /tmp/pcd/scripts/shared/verify-persona-work-plans.sh
+          else
+            echo "phantom-cloud-deploy fixture not yet on main; skipping drift verification"
+          fi
+
       - name: Install Chat UI Dependencies
         working-directory: chat-ui
         run: bun install --frozen-lockfile

CLAUDE.md

@@ -291,6 +291,18 @@ The file is read at request-time and never cached in process memory, so an in-pl
 
 **Migration-safety CI gate.** Phantom tenants survive a snapshot-replace upgrade by rsyncing `/app/data/` (which contains `phantom.sqlite`) from the old ZFS clone to the new clone. Migrations therefore must be **additive** (no `DROP TABLE`, `DROP COLUMN`, `DROP CONSTRAINT`, `DROP INDEX`, no `RENAME`) and **idempotent** (`CREATE TABLE IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS`). `ALTER TABLE ... ADD COLUMN` is allowed because the runner's `_migrations` index gates re-execution. The gate runs in CI on every PR via `bun run src/db/check-migrations.ts`, fails closed on any violation, and rejects the PR. The full architectural argument lives in the Phase 18 architect doc §5.2.
 
+## First hour of work (Slice 15a)
+
+The agent's first action on every fresh tenant is `do_first_hour_of_work`, a single-Sonnet-turn scaffold-driven runner that fires from `src/index.ts::main()` after the intro DM lands. The architect doc is `phantom-cloud-deploy/local/2026-05-03-slice-15-first-hour-of-work-architect.md`.
+
+**The contract.** ONE turn, ONE prompt-pinned 4-step structure (PULL, IDENTIFY, DRAFT, DM), ONE 60 second hard cap enforced by `AbortController` in `src/persona/runner.ts`. The runner reads `PHANTOM_PERSONA_ID`, `PHANTOM_TENANT_SLUG`, `PHANTOM_OWNER_NAME`, `PHANTOM_OWNER_EMAIL`, `PHANTOM_GRANTED_INTEGRATIONS` from the env, builds the system-prompt scaffold from `src/persona/scaffold-prompt.ts`, runs the LLM via `src/persona/llm-caller.ts` (which wraps `runtime.handleMessage` with a `first-hour:` session id prefix), parses the JSON envelope from the model's final text, persists drafts to the local SQLite `phantom_drafts` table, sends the Block Kit DM via `src/channels/slack/render-first-hour-dm.ts`, and emits five audit events (start, pulls, drafts, dm, finish) per the architect's §7 reason-code taxonomy (11 codes locked).
+
+**The wire.** Action_id pattern for the DM buttons is `phantom:draft:{draft_id}:{action}` where action is one of `send | edit | skip | skip_all | save_only`. The Bolt action dispatcher at `src/channels/slack-actions.ts` parses the action_id and forwards to the registered draft action recorder; phantom-control's `agent_drafts` table (slice 15b) is the cross-host record. Idempotency is layered: in-VM SQLite `firstboot_state.first_hour_of_work_completed_at` is layer 1; phantom-control's `agents.first_hour_of_work_completed_at` is layer 2 (slice 15b); the per-fire ULID is layer 3.
+
+**Persona work-plans cross-repo invariant.** `src/persona/work-plans.ts` is the in-VM mirror of `phantom-cloud-deploy/scripts/shared/persona-work-plans.json`. Both files MUST stay byte-equal for the seven `persona_id` literals AND the `required_integrations` arrays per persona. The cross-repo verifier at `phantom-cloud-deploy/scripts/shared/verify-persona-work-plans.sh` runs in this repo's CI on every PR; strict mode flips on once the canonical fixture lands on `phantom-cloud-deploy:main`. The seven locked ids are `sdr-lilian`, `eng-cos-marcus`, `am-sloane`, `bdr-theo`, `sales-vp-priya`, `gtm-eng-ryan`, `founder-asst-adrian`. The architect doc §2.5 carried `sales-leader-priya` as a typo; the canonical wins.
+
+**The 60 second hard cap.** Architect §6.6 names this as the partial-DM affordance, NOT a bonus. The runner's `Promise.race` between the LLM call and a `setTimeout(hard_cap_ms)` enforces wall-clock cutoff; on timeout the partial DM ships with the `Reply MORE for the rest` affordance and reason_code `sixty_second_cap_hit`. The `phantom/src/persona/__tests__/runner.test.ts::"sixty_second_cap_hit"` test exercises the AbortController path with a 50ms cap stub.
+
 ## Key Design Decisions
 
 **Qdrant over LanceDB:** WAL durability with crash recovery. Native hybrid search (dense + BM25 sparse vectors). Named vectors for separate embedding spaces. Mmap mode for low memory. TypeScript REST client works with Bun (no NAPI addon risk).

src/channels/slack-actions.ts

@@ -52,6 +52,31 @@ export function setMorningBriefPreferenceRecorder(recorder: MorningBriefPreferen
 	morningBriefRecorder = recorder;
 }
 
+/**
+ * First-hour-of-work draft action handler (architect §5.4). The user
+ * clicks Send / Edit / Skip / Skip-All / Save-Only on the Block Kit
+ * DM that the runner posted at firstboot; the Bolt action handler
+ * parses the action_id (phantom:draft:{draft_id}:{action}), looks up
+ * the draft via this recorder, and the recorder updates the local
+ * SQLite row + (slice 15b) POSTs to phantom-control.
+ */
+export type FirstHourDraftAction = "send" | "edit" | "skip" | "skip_all" | "save_only";
+
+export type FirstHourDraftActionRecorder = (params: {
+	draftId: string;
+	action: FirstHourDraftAction;
+	userId: string;
+	channelId: string;
+	messageTs: string;
+	clickedAt: number;
+}) => Promise<void> | void;
+
+let firstHourDraftRecorder: FirstHourDraftActionRecorder | null = null;
+
+export function setFirstHourDraftActionRecorder(recorder: FirstHourDraftActionRecorder): void {
+	firstHourDraftRecorder = recorder;
+}
+
 /** Extract a typed value from the Bolt body object */
 function bodyField<T>(body: unknown, ...keys: string[]): T | undefined {
 	let obj = body as Record<string, unknown> | undefined;
@@ -255,4 +280,89 @@ export function registerSlackActions(app: App): void {
 			}
 		});
 	}
+
+	// Slice 15a first-hour-of-work draft buttons. Pattern:
+	// phantom:draft:{draft_id}:{action} where action is send | edit |
+	// skip | skip_all | save_only. The handler parses the action_id,
+	// hands off to the draft recorder (slice 15a wires the local
+	// SQLite update; slice 15b POSTs to phantom-control).
+	app.action(/^phantom:draft:[^:]+:(send|edit|skip|skip_all|save_only)$/, async ({ ack, body, client }) => {
+		await ack();
+
+		const b = body as unknown as Record<string, unknown>;
+		const actions = b.actions as Array<{ action_id: string; value?: string }> | undefined;
+		if (!actions?.[0]) return;
+
+		const actionId = actions[0].action_id;
+		const parts = actionId.split(":");
+		if (parts.length !== 4) return;
+		const draftId = parts[2];
+		const action = parts[3] as FirstHourDraftAction;
+
+		const channelId = bodyField<string>(b, "channel", "id");
+		const messageTs = bodyField<string>(b, "message", "ts");
+		const userId = bodyField<string>(b, "user", "id");
+		if (!channelId || !messageTs || !userId) return;
+
+		if (firstHourDraftRecorder) {
+			try {
+				await firstHourDraftRecorder({
+					draftId,
+					action,
+					userId,
+					channelId,
+					messageTs,
+					clickedAt: Date.now(),
+				});
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				console.warn(`[slack] first-hour draft recorder failed: ${msg}`);
+			}
+		} else {
+			console.log(`[slack] first_hour_draft_action draft=${draftId} action=${action} user=${userId}`);
+		}
+
+		// Update the message: replace the draft's own actions block with a
+		// context block reflecting the click. The skip-all and save_only
+		// surfaces follow the same shape; the send/edit/skip variants
+		// flip just the per-draft actions row, leaving other drafts in the
+		// same DM untouched.
+		const existingBlocks = bodyField<Array<{ type: string; block_id?: string }>>(b, "message", "blocks") ?? [];
+		const replacementText = ackTextForAction(action, draftId);
+		const targetBlockId = action === "skip_all" ? "phantom_first_hour_skip_all" : `draft_${draftId}`;
+		const updatedBlocks = existingBlocks.map((block) => {
+			if (block.block_id !== targetBlockId) return block;
+			return {
+				type: "context",
+				elements: [{ type: "mrkdwn", text: replacementText }],
+			};
+		});
+		const messageText = bodyField<string>(b, "message", "text") ?? "";
+		try {
+			await client.chat.update({
+				channel: channelId,
+				ts: messageTs,
+				text: messageText,
+				blocks: updatedBlocks,
+			} as unknown as Parameters<typeof client.chat.update>[0]);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			console.warn(`[slack] Failed to update first-hour draft buttons: ${msg}`);
+		}
+	});
+}
+
+function ackTextForAction(action: FirstHourDraftAction, draftId: string): string {
+	switch (action) {
+		case "send":
+			return `_Sent. (draft ${draftId})_`;
+		case "edit":
+			return `_Edit modal opened. (draft ${draftId})_`;
+		case "skip":
+			return `_Skipped. (draft ${draftId})_`;
+		case "skip_all":
+			return "_All drafts skipped. Reply MORE to surface them again._";
+		case "save_only":
+			return `_Saved. (draft ${draftId})_`;
+	}
 }

src/channels/slack.ts

@@ -290,8 +290,8 @@ export class SlackChannel implements Channel {
 		return egressPostToChannel(this.egressContext(), channelId, text);
 	}
 
-	async sendDm(userId: string, text: string): Promise<string | null> {
-		return egressSendDm(this.egressContext(), userId, text);
+	async sendDm(userId: string, text: string, blocks?: SlackBlock[]): Promise<string | null> {
+		return egressSendDm(this.egressContext(), userId, text, blocks);
 	}
 
 	async postThinking(channel: string, threadTs: string): Promise<string | null> {

src/channels/slack/__tests__/__snapshots__/edit-modal.test.ts.snap

@@ -0,0 +1,68 @@
+// Bun Snapshot v1, https://bun.sh/docs/test/snapshots
+
+exports[`buildEditModalView snapshot of the modal payload 1`] = `
+{
+  "blocks": [
+    {
+      "text": {
+        "text": 
+"*Draft kind:* Slack reply
+*Edit hints from Lilian here:* tighten the ask"
+,
+        "type": "mrkdwn",
+      },
+      "type": "section",
+    },
+    {
+      "block_id": "draft_body_block",
+      "element": {
+        "action_id": "draft_body_input",
+        "initial_value": "Hi Sarah, here is the v3 quote.",
+        "max_length": 4000,
+        "multiline": true,
+        "type": "plain_text_input",
+      },
+      "label": {
+        "emoji": false,
+        "text": "Draft body",
+        "type": "plain_text",
+      },
+      "type": "input",
+    },
+    {
+      "block_id": "edit_save_only",
+      "elements": [
+        {
+          "action_id": "phantom:draft:dft_01J:save_only",
+          "text": {
+            "emoji": false,
+            "text": "Save without sending",
+            "type": "plain_text",
+          },
+          "type": "button",
+          "value": "dft_01J",
+        },
+      ],
+      "type": "actions",
+    },
+  ],
+  "callback_id": "phantom_draft_edit_modal",
+  "close": {
+    "emoji": false,
+    "text": "Cancel",
+    "type": "plain_text",
+  },
+  "private_metadata": "dft_01J",
+  "submit": {
+    "emoji": false,
+    "text": "Save and send",
+    "type": "plain_text",
+  },
+  "title": {
+    "emoji": false,
+    "text": "Edit draft",
+    "type": "plain_text",
+  },
+  "type": "modal",
+}
+`;