docs(specs): Iskra mail consumer v0 prebuild (#235) #346

Merged

pdurlej merged 1 commit from claude/iskra/mail-consumer-v0 into main

2026-05-23 10:31:19 +02:00

claude commented

2026-05-17 21:09:58 +02:00

Collaborator

Summary

Operator-emotional priority. Prebuild for #235 — wire VPS1000 OpenClaw to consume mail events from existing healthy RS2000 mail-infra-x4 gateway, add first-class reply action with threading.

Mail infra is 60% done per Apr 12 audit — three threads flagged the gap since early April. This v0 closes the gap to operator's #1 promised Iskra value: "reads my email + replies as me, with context."

What's in this PR

6-file Spec Kit + companion execution prompt:

docs/specs/iskra-mail-consumer-v0/00-constitution.md — 8 principles:
- P1 mail-infra-x4 unchanged (sacred per evidence)
- P2 reply is first-class action, NOT workaround
- P3 Threading headers preserved (In-Reply-To + References)
- P4 Voice approval for every reply (existing assistant.send UX)
- P5 Operator-only target during v0 (family tier in #179)
- P6 Visible telemetry from day 1 (lastInboundAt + lastOutboundAt)
- P7 No new mail provider integrations
- P8 Secrets pattern (no plaintext in module.yaml)
01-specify.md — problem (3 threads open since April), scope, acceptance, success metrics
02-plan.md — 5-slice architecture (recon, dispatch wiring, intake handler, reply action, telemetry+runbook+retro) with Q1-Q5 open questions
03-tasks.md — per-slice tasks with adversarial cases
04-implement-notes.md — assistant.send handler reference pattern, RFC 5322 threading chain construction, sacred-path discipline, gotchas G1-G7
prompts/codex-iskra-mail-consumer.md — execution prompt with Safety / production boundary + per-slice instructions + stop conditions

Slices (forthcoming PRs)

(a) Recon — Lite — read-only investigation; recon doc resolves Q1-Q5; blocks Slice (b)
(b) Dispatch endpoint + token — Full — secret wiring (no plaintext); stub handler accepts payload
(c) Intake handler — Full — mirrors assistant.send pattern; operator-validated smoke
(d) reply action — Full — most operator-emotional slice; schema + handler + threading + operator-validated Gmail threading test
(e) Telemetry + runbook + retrospective — Lite — final wiring; 1-week soak feeds RETRO

Operator coordination points

Slice (a) Recon requires SSH to VPS1000 (operator on duty)
Slice (d) threading test = operator verifies in own Gmail/Inbox
Voice approval primitive owner = operator (reused from assistant.send)

Tier

Trivial per ADR-0007 (docs-only prebuild, no runtime mutation).

Operator action

Draft for review. After merge: paste prompts/codex-iskra-mail-consumer.md to fresh codex session to begin Slice (a) recon.

Refs #235 (related: #236 Phase 1.0 bundle for HUMAN-DECISION-POLICY alignment; #179 family tier explicitly OUT; #76 Agent Access Plane future v0.1)

## Summary **Operator-emotional priority.** Prebuild for #235 — wire VPS1000 OpenClaw to consume mail events from existing healthy RS2000 mail-infra-x4 gateway, add first-class `reply` action with threading. Mail infra is **60% done per Apr 12 audit** — three threads flagged the gap since early April. This v0 closes the gap to operator's #1 promised Iskra value: *"reads my email + replies as me, with context."* ## What's in this PR 6-file Spec Kit + companion execution prompt: - `docs/specs/iskra-mail-consumer-v0/00-constitution.md` — 8 principles: - **P1** mail-infra-x4 unchanged (sacred per evidence) - **P2** `reply` is first-class action, NOT workaround - **P3** Threading headers preserved (In-Reply-To + References) - **P4** Voice approval for every reply (existing assistant.send UX) - **P5** Operator-only target during v0 (family tier in #179) - **P6** Visible telemetry from day 1 (lastInboundAt + lastOutboundAt) - **P7** No new mail provider integrations - **P8** Secrets pattern (no plaintext in module.yaml) - `01-specify.md` — problem (3 threads open since April), scope, acceptance, success metrics - `02-plan.md` — 5-slice architecture (recon, dispatch wiring, intake handler, reply action, telemetry+runbook+retro) with Q1-Q5 open questions - `03-tasks.md` — per-slice tasks with adversarial cases - `04-implement-notes.md` — assistant.send handler reference pattern, RFC 5322 threading chain construction, sacred-path discipline, gotchas G1-G7 - `prompts/codex-iskra-mail-consumer.md` — execution prompt with Safety / production boundary + per-slice instructions + stop conditions ## Slices (forthcoming PRs) - **(a) Recon** — Lite — read-only investigation; recon doc resolves Q1-Q5; blocks Slice (b) - **(b) Dispatch endpoint + token** — Full — secret wiring (no plaintext); stub handler accepts payload - **(c) Intake handler** — Full — mirrors assistant.send pattern; operator-validated smoke - **(d) `reply` action** — Full — most operator-emotional slice; schema + handler + threading + operator-validated Gmail threading test - **(e) Telemetry + runbook + retrospective** — Lite — final wiring; 1-week soak feeds RETRO ## Operator coordination points - Slice (a) Recon requires SSH to VPS1000 (operator on duty) - Slice (d) threading test = operator verifies in own Gmail/Inbox - Voice approval primitive owner = operator (reused from `assistant.send`) ## Tier Trivial per ADR-0007 (docs-only prebuild, no runtime mutation). ## Operator action Draft for review. After merge: paste `prompts/codex-iskra-mail-consumer.md` to fresh codex session to begin Slice (a) recon. Refs #235 (related: #236 Phase 1.0 bundle for HUMAN-DECISION-POLICY alignment; #179 family tier explicitly OUT; #76 Agent Access Plane future v0.1)

claude added 1 commit

2026-05-17 21:09:58 +02:00

docs(specs): Iskra mail consumer v0 prebuild for #235

base-is-main / guard (pull_request) Successful in 2s

Details

canary-required / collect-diff (pull_request) Successful in 4s

Details

patchwarden-pr-sanity / collect-diff (pull_request) Successful in 4s

Details

canary-required / canary (pull_request) Successful in 13s

Details

patchwarden-pr-sanity / sanity (pull_request) Successful in 20s

Details

99a4b00810

Operator-emotional priority. Wire VPS1000 OpenClaw to consume mail events
from existing healthy RS2000 mail-infra-x4 gateway, add first-class
`reply` action with threading. Mail infra is "60% done" per Apr 12 audit
— this v0 closes the gap to operator's #1 promised Iskra value:
"reads my email + replies as me, with context."

Spec Kit:
- 00-constitution.md: 8 principles (mail-infra-x4 unchanged sacred,
  `reply` first-class not workaround, threading headers preserved,
  voice approval for every reply, operator-only target during v0,
  visible telemetry from day 1, no new mail provider integrations,
  secrets pattern enforced)
- 01-specify.md: problem (3 threads open since April), scope, acceptance,
  success metrics
- 02-plan.md: 5-slice architecture (recon, dispatch wiring, intake handler,
  reply action, telemetry+runbook+retro) with Q1-Q5
- 03-tasks.md: per-slice tasks with adversarial test cases
- 04-implement-notes.md: assistant.send handler pattern (reference),
  RFC 5322 threading chain construction, sacred-path discipline,
  gotchas G1-G7

Companion execution prompt: prompts/codex-iskra-mail-consumer.md with
explicit Safety / production boundary + per-slice instructions + stop
conditions (P3 threading + P4 voice approval + P8 plaintext secret =
automatic STOP triggers).

Slice (d) `reply` action is the most operator-emotional slice; threading
correctness verified by operator in own Gmail before Slice (e).

Tier: Trivial per ADR-0007 (docs-only prebuild).

Refs #235 (related: #236 Phase 1.0 bundle, #179 family tier excluded,
#76 Agent Access Plane future v0.1 onboarding)