# Personal Chief-of-Staff System — Implementation Design Specification ## 0. Design position This is a scheduled, file-backed personal operations system owned by one person. It is not a conversational assistant that waits to be opened. Its core loop is: scheduled collection → deterministic detection → optional model enrichment → independent verification → immutable artefacts → phone-visible brief → scheduled self-evaluation Three properties are fixed: 1. Deterministic rules establish the minimum visible result. 2. Models may enrich that result but cannot remove, lower, or conceal it. 3. Every valuable output is pushed into the operator's normal attention path on a schedule. Phase one contains one agent: personal email triage. It has no SMTP dependency, no mail-submission protocol, no messaging API, and no function capable of transmitting a draft. The server publishes files only to a local export directory. A phone-side scheduled automation fetches the latest brief over an authenticated private network and raises a local notification. The server never initiates communication. --- # 1. Whole-system architecture ## 1.1 Logical components ### A. Scheduler Responsibilities: - Starts collectors, agents, verifiers, publishers, and evaluators. - Reconciles missed scheduled runs. - Prevents concurrent runs of the same component. - Records an immutable run event for every attempted invocation. - Raises a locally published operational alert when an expected artefact is absent. Implementation: - Fixed: systemd timers on the always-on Linux host. - Fixed: a separate hourly schedule reconciler. - No persistent daemon. No workflow engine. No message broker. Systemd timers are preferred over cron for phase one because Persistent=true runs a missed invocation after reboot. The scheduling model remains periodic jobs rather than resident services. ### B. Provider collectors Collectors are the only components allowed to communicate with external source systems. Examples: Email (IMAP), Voice (phone-uploaded audio files), Calendar (future read-only), Finance (future read-only exports), Health (future file imports). Responsibilities: - Retrieve source material without modifying the source. - Normalize it into a versioned source envelope. - Record provider cursor evidence. - Produce a collection manifest containing counts and hashes. - Never classify, prioritize, summarize, or draft. Collectors run under separate operating-system accounts from model-facing agents. ### C. Domain agents Each agent owns one personal domain. It consumes normalized source envelopes and append-only memory records. Responsibilities: - Apply deterministic rules. - Optionally invoke a configured model for additive enrichment. - Produce candidate briefs, questions, reminders, or drafts. - Cite the source records underlying every assertion. - Never directly publish its own consequential output. - Never access provider credentials. Planned domain agents: Personal email · Voice inbox and personal capture · Personal administration and deadlines · Immigration/legal dates · Finance · Health · Relationships · Learning and hobbies · Journal and decision record. There is no general autonomous "chief" process coordinating agents. The scheduled daily brief composer reads their verified outputs. This avoids a central agent whose failure silences everything. ### D. Independent verifiers A verifier is a different process from its producer, runs with different instructions, and receives no producer reasoning or hidden chain of thought. Responsibilities: - Validate schema and source citations. - Recompute deterministic rules from source envelopes. - Confirm no surfaced deterministic item disappeared or moved to a less-visible section. - Check that generated claims are supported by cited material. - Check that prohibited actions or content are absent. - Produce a verification artefact. A failed verifier does not suppress deterministic results. It causes deterministic findings to remain visible, unverified model text to be withheld, and a visible system-warning line in the next published brief. ### E. Memory ledger Memory is append-only JSON Lines. Store dated facts with provenance. Record contradictions and supersession as new records. Never rewrite an earlier fact. Support scheduled accuracy evaluation. Keep sensitive documents out of model-readable storage. Memory is divided by domain so an agent sees only what it needs. ### F. Brief composer Reads verified agent outputs. Produces a short Markdown and plain-text brief. Preserves deterministic priority. Allows "Nothing changed" as a complete domain result. Does not generate novel factual claims. Publishes operational warnings ahead of personal content. Deterministic formatter in phase one. ### G. Local publisher Atomically writes versioned brief artefacts into a local export directory. Updates local latest.txt and latest.json pointers by atomic replacement. Produces a publication receipt containing the published artefact's hash. Exposes no mutation endpoint. No provider credentials. ### H. Phone delivery edge - The server writes a brief into its local export directory. - A read-only static file endpoint is available only over the operator's private network. - A scheduled phone automation fetches latest.json. - If the publication identifier is new, the phone raises a local notification containing the first lines and a link to the full brief. - If the phone cannot fetch it, the phone raises a local "personal brief unavailable" notification. The phone is pulling; the server cannot address a recipient or initiate contact. The endpoint offers only GET and HEAD. ### I. Self-evaluator Evaluates system performance, never operator behavior. Measures delivery, source coverage, rule recall, verifier disagreement, model contribution, and memory accuracy. Publishes scheduled evaluation artefacts. Surfaces degradation in the next brief. No adherence scores, streaks, productivity scores, or judgments about the operator. ### J. Configuration and feature flags Human-readable TOML. Categories: schedules, enabled agents, provider selection, deterministic rules, model provider, feature flags, retention policy proposals (no automatic removal), local paths. ``` [features] model_labels_observe = true model_labels_visible = false model_summaries_observe = true model_summaries_visible = false draft_generation_observe = false draft_generation_visible = false ``` Flags govern visibility, not whether the system is allowed to start. A missing configuration value produces a visible question in the brief where possible, a diagnostic artefact, and continued operation of unaffected components. ## 1.2 Fixed versus pluggable **Fixed (system invariants, not provider-configurable):** Append-only provenance · Deterministic findings cannot be suppressed or downranked · Separate producer and verifier processes · No provider credentials in agent processes · No deletion, archive, or move · No mail send capability in phase one · Artefact-backed claims · Independent proof for absence claims · Scheduled delivery and scheduled evaluation · Plain-text, Markdown, TOML, JSONL storage · Work-data exclusion · Identity-document content exclusion. **Pluggable:** Source providers behind narrow collector interfaces · Model providers behind an enrichment interface · Speech-to-text provider later · Phone-side retrieval mechanism (server stays passive and read-only) · Domain agents conforming to the agent contract · Deterministic rule sets as versioned configuration. A plugin cannot weaken a fixed invariant. The runner and verifier reject outputs that violate them. --- # 2. Interfaces ## 2.1 Source provider interface ``` probe() collect(previous_cursor, collection_window) normalize(provider_record) describe_capabilities() ``` **probe()** returns evidence the provider was reached and identifies the account without revealing credentials. **collect()** returns normalized records, provider cursor before and after, counts by retrieval method, provider-reported errors, and collection start/end timestamps. Must be read-only. **normalize()** produces versioned source envelopes without classification. **describe_capabilities()** declares read operations implemented, potential provider-side credential permissions, whether attachments are fetched, whether source mutations are implemented. The phase-one IMAP provider must declare: ``` read_messages: true read_headers: true read_flags: true fetch_attachment_bodies: false write_flags: false move: false copy: false delete: false expunge: false send: false ``` The declaration is checked against a static command allowlist and an automated architecture test. ## 2.2 Model provider interface ``` enrich(input_record, permitted_tasks, schema, prompt_version) ``` Returns structured data only: additive labels, proposed summary, proposed draft (when the relevant dark flag is active), claim-to-source mappings, model and prompt identifiers, invocation timestamp. It cannot set priority below the deterministic result and cannot omit source records from downstream processing. Model calls receive no secrets, credentials, identity-document bodies, or unrelated domain memory. ## 2.3 Verified-output interface A verifier produces source artefact identifiers, producer artefact identifier, recomputed deterministic findings, disagreement records, fields permitted for publication, fields withheld and the reason, verifier version, completion time, content hash. The publisher accepts only deterministic findings independently recomputed by the verifier, or model additions explicitly marked publishable by the verifier. If the verifier does not run, the publisher reconstructs a deterministic-only emergency brief directly from the rule artefact. --- # 3. Data model and on-disk layout ## 3.1 Layout ``` personal-cos/ ├── README.md ├── config/ │ ├── system.toml │ ├── schedules.toml │ ├── providers.toml │ ├── features.toml │ ├── domains.toml │ └── rules/email-v1.toml ├── contracts/ │ ├── source-envelope-v1.md │ ├── agent-contract-v1.md │ ├── verification-v1.md │ └── artefact-types-v1.md ├── bin/ ├── agents/email/{manifest.toml,prompts/,tests/} ├── state/ │ ├── cursors/email-personal.json │ ├── locks/ │ └── delivery/phone-observations.jsonl ├── ledger/ │ ├── runs/YYYY/MM/DD.jsonl │ ├── memory/{admin,immigration,finance,health,relationships,learning,hobbies,journal,decisions}.jsonl │ ├── questions.jsonl │ ├── approvals.jsonl │ └── evaluations/YYYY-MM.jsonl ├── artefacts/ │ ├── source/email/YYYY/MM/DD// │ ├── rules/email/YYYY/MM/DD// │ ├── candidates/email/YYYY/MM/DD// │ ├── verification/email/YYYY/MM/DD// │ ├── briefs/YYYY/MM/DD/ │ ├── drafts/YYYY/MM/DD/ │ └── diagnostics/YYYY/MM/DD/ ├── export/{latest.txt,latest.json,briefs/,health/} └── var/ ``` Secrets live outside this tree. No record contains a workflow status field. Readiness is never represented as a state that can block execution. Immutable events may contain a factual result (completed, partial, failed) because observability requires recording what happened. The runner never requires a particular result from a human review event before starting later runs. ## 3.2 Source envelope ```json { "schema": "source-envelope/v1", "source_id": "email:account-alias:uidvalidity:uid", "provider": "imap", "account_alias": "personal", "observed_at": "RFC3339", "source_time": "RFC3339 or null", "source_locator": {"mailbox":"INBOX","uidvalidity":123,"uid":456}, "content": { "from":"...","to_operator":true,"subject":"...","text":"...", "attachment_references":[{"filename":"...","mime_type":"...","provider_locator":"mailbox/uid/part-number"}] }, "content_hash":"sha256:...", "collection_id":"...", "sensitivity":["personal"] } ``` Constraints: attachment bodies not fetched in phase one. If a filename or message indicates an identity or immigration document, only its filename, provider locator, dates explicitly present in permitted message text, and operator-entered notes may be retained. HTML converted to text in memory; active content and remote resources never loaded. Message text on disk protected by host filesystem permissions and excluded from general agents. Logs never contain message bodies. ## 3.3 Rule finding ```json { "schema":"rule-finding/v1","finding_id":"...","source_id":"...", "rule_id":"deadline.explicit-date","rule_version":"email-v1","observed_at":"...", "visibility":"act|review|note", "reason_codes":["explicit_deadline","within_14_days"], "matched_evidence":["subject","normalized date"], "source_citation":"email:...","content_hash":"sha256:..." } ``` Visibility ordering is fixed: `act > review > note`. A model can add a label or recommend a higher visibility. It cannot produce a lower effective visibility. ## 3.4 Memory fact ```json { "schema":"memory-fact/v1","fact_id":"...","domain":"immigration", "recorded_at":"...","effective_at":"...", "statement":"Visa expiry date recorded as YYYY-MM-DD.", "source":{"kind":"operator_statement|email|calendar|derived","source_id":"...","observed_at":"..."}, "confidence_basis":"direct_operator_statement", "supersedes":[],"contradicts":[],"sensitivity":["legal"], "document_references":[{"name":"Passport","location":"home safe"}] } ``` A correction appends another fact with supersedes or contradicts. The earlier record remains. ## 3.5 Approval record Deletion, archive, and move are absent from phase one. The approval ledger exists for later components. Each approval must name exactly one source item and one exact operation. No bulk approvals. No wildcard identifiers. No standing approval. Later executors must consume an unexpired approval atomically and record the resulting provider evidence. Phase one has no executor. ## 3.6 Artefact manifest Every run directory contains manifest.json listing component name and version, invocation identifier, scheduled and actual start time, input and output artefact identifiers and hashes, counts, factual result, error categories, wall-clock duration, configuration and rule hashes, model identifier if used. A process cannot claim completion unless the listed artefacts exist and their hashes verify. --- # 4. Agent contract ## 4.1 Manifest Declares agent name and domain, input/output schema versions, required memory partitions, deterministic rule implementation, optional model tasks, consequential outputs it can propose, independent verifier entry point, schedule recommendation, expected artefacts, source and network permissions, feature flags, maximum source age, tests for prohibitions. ## 4.2 Required operations `probe · collect or consume · apply_rules · enrich · verify · render · evaluate` ## 4.3 Required guarantees 1. Produce useful deterministic output when the model is unavailable. 2. Preserve every deterministic finding at equal or greater visibility. 3. Cite a source for every factual assertion. 4. Mark inference separately from observation. 5. Use a separate verifier process. 6. Produce an artefact for every completion claim. 7. Validate absence with two independent methods. 8. Append memory; never overwrite it. 9. Tolerate missing optional files by producing a question and continuing. 10. Publish on a schedule without operator initiation. 11. Exclude work data. 12. Declare its blast radius. 13. Ship new human-readable model behavior dark. 14. Provide a self-evaluation fixture. 15. Avoid rating the operator. ## 4.4 Absence-proof contract If an agent says "no deadlines," "no new messages," or "nothing changed," it must cite two independent checks. For email: (1) UID-based incremental collection; (2) an IMAP mailbox count/search comparison using a separate command and independently calculated time boundary. If they disagree, the output is not "nothing changed." It is: *Email coverage could not be confirmed; review may be incomplete.* ## 4.5 Guard invocation table | Guard | Caller | Moment | |---|---|---| | Deterministic-floor guard | Email verifier | After candidate generation, before publication | | No-send architecture check | Build/test job and deployment preflight | Every build and installed-version change | | No source mutation | IMAP collector wrapper | Before each IMAP command is issued | | Attachment-body prohibition | IMAP collector | While constructing fetch requests | | Work-boundary filter | Collector and verifier independently | During normalization and before publication | | Secret redaction | Collector logging wrapper | Before any log record is written | | Source-citation requirement | Verifier | For every proposed factual sentence | | Per-item approval | Future mutation executor | Immediately before the exact mutation | | Identity-document exclusion | Normalizer and verifier | At ingestion and before model invocation | | Artefact existence | Run reconciler | At expected completion time | | Absence double-check | Agent verifier | Before publishing an absence claim | | Dark-feature enforcement | Publisher | When selecting candidate fields for publication | A rule without an invoker and firing moment is not accepted into the design. --- # 5. Scheduling and triggering ## 5.1 Cadences Phase-one email schedule, operator local time: - 05:00 morning collection and brief - 17:30 evening collection and brief - 21:30 final collection and brief - Hourly schedule reconciliation and silence detection - Daily 22:00 delivery and collection evaluation - Weekly Sunday 19:00 rule-quality sample and memory evaluation - Monthly first Sunday 19:30 slow-domain review when those domains exist At most three routine email briefs per day. A brief may be two lines. Operational failure is always shown even if personal content is unchanged. ## 5.2 Time handling Schedules defined using an IANA timezone (Australia/Sydney). Artefact timestamps UTC RFC3339. Rendered briefs include local and UTC time. DST delegated to systemd's calendar implementation. Duplicate local times deduplicated by the scheduled UTC instant recorded in the run ledger. ## 5.3 Missed runs Each timer uses persistent catch-up. The hourly reconciler also computes expected invocations from the schedule file. For each expected invocation: valid artefact exists → nothing added; no run record → catch-up run; failed or partial → bounded retry; normal window passed → catch-up starts from last confirmed provider cursor rather than missed wall-clock interval; coverage unprovable → next brief states the uncovered interval. Duplicate source items prevented through stable provider identifiers and content hashes. Retry policy: one normal attempt; transient failure retries after 5 and 30 minutes; continued failure no tight loop, hourly reconciliation continues; authentication failure retry once every six hours plus a published credential question; model failure no retry required, publish deterministic-only; verifier failure publish emergency deterministic-only plus warning. There is no human acknowledgment required to resume. ## 5.4 Starvation prevention Every component claiming operator value must have a schedule, an expected artefact, a publication route, a silence detector, and a defined short unchanged result. Components without all five are not enabled. A folder, dashboard, search page, or conversational agent does not count as delivery. --- # 6. Ranked failure modes and detection **1. The system silently stops running.** Critical. Hourly reconciler calculates expected runs independently of the agent; checks run ledger and expected artefact path/hash. Phone independently checks age of latest.json. If server unreachable or brief stale, phone raises a local notification. *Residual risk: if server and phone automation both fail simultaneously, there is no third delivery path in phase one.* **2. Mail collection silently misses messages.** Critical. UID/UIDVALIDITY incremental collection; independent mailbox search/count comparison; cursor monotonicity checks; periodic overlap collection of prior 48 hours with deduplication; weekly comparison of provider message counts against normalized source counts. If methods disagree, absence is not claimed. **3. Deterministic important mail is hidden by model classification.** Critical. Verifier independently reruns deterministic rules; publisher calculates effective visibility as max of deterministic and model visibility; fixture tests inject known deadlines, legal terms, payment notices, security alerts; weekly evaluation reports any deterministic finding absent from the published brief. Prevented as well as detected: model output has no suppression field. **4. Authentication expires or credentials become invalid.** High. Collector distinguishes authentication rejection from empty results; successful authenticated probe recorded before collection; authentication failures produce diagnostic and visible system warning; phone stale-brief check provides independent signal. Phase one uses app-password IMAP specifically to avoid the seven-day refresh-token behavior of unverified restricted-scope OAuth clients. **5. A model invents a deadline, person, obligation, or draft fact.** High. Every model claim must cite source spans; verifier sees source material and candidate output but not producer reasoning; unsupported claims withheld; model-written summaries and drafts initially dark; weekly evaluation samples visible model claims and records support rates. **6. A brief is produced but never reaches the phone.** High. Publisher writes receipt with content hash; phone records last fetched publication identifier; phone warns when latest server brief older than expected threshold; server-side evaluation distinguishes "published locally" from "observed fetched" when the phone can write a minimal receipt through a separate authenticated endpoint. *For the smallest phase-one build the phone receipt is optional; without it the server can prove publication but not human-visible delivery.* **7. Work email enters the personal system.** High. Phase one connects only to the personal mailbox; configured work domains and known work addresses excluded during normalization; verifier independently rechecks sender, recipients, aliases, configured terms; excluded item counts published without subject or body; weekly random metadata-only sampling. *Residual risk: personal and work content may coexist in one thread; ambiguous items withheld and surfaced as a question using metadata only.* **8. Secrets appear in logs or model inputs.** High. Logs use structured allowlisted fields, not arbitrary exception dumps; log scanner checks configured secret identifiers and common credential patterns before publication and daily; model invocation manifests list included field names and hashes; verifier rejects identity-document content and credential-shaped data. **9. Mailbox source content is mutated.** High. IMAP command wrapper uses explicit read-command allowlist; tests fail if prohibited commands or mail-submission libraries appear; collector captures selected flags before and after collection on a sample and reports unexpected changes; provider audit information reviewed weekly if available. *The credential may still possess provider-level mutation rights; architectural containment prevents normal code paths from using them but cannot make a broadly privileged app password intrinsically read-only.* **10. Disk fills or files become corrupt.** Medium-high. Pre-run disk-space threshold check; atomic writes followed by read-back and hash verification; daily manifest-hash validation; filesystem and backup checks produce visible warnings; no success claim accepted from an unreadable artefact. Because automatic deletion is forbidden, low disk space results in a warning and a per-item cleanup proposal, not silent pruning. **11. Rules become stale.** Medium. Weekly false-negative fixtures; monthly sampling of unflagged mail metadata and permitted text; rule version and last evaluation date appear in evaluation output; verifier disagreement and operator corrections appended as evidence. No rule update silently enabled. **12. The system becomes too noisy and is ignored.** Medium. Measure briefs produced, items repeated unchanged, items emitted without new evidence. Do not measure whether the operator complied. Repeated unchanged items collapse into one line retaining earliest and latest observation dates. Slow-moving domains remain weekly or monthly. *Whether the operator reads notifications cannot be reliably known without invasive tracking; only partially mitigated.* --- # 7. Security model ## 7.1 Credential handling Secrets never stored under personal-cos/, in TOML, JSONL, prompts, artefacts, source envelopes, logs, shell history, or model-readable environment dumps. Phase one uses: a dedicated Linux account for the IMAP collector; a root-owned systemd credential file or equivalent OS secret facility; file permissions limiting the credential to the collector service; credential injection at process start through systemd credentials; a stable secret reference in configuration (e.g. `imap-personal`), never its value; a separate app password used only for this installation. The collector is the only process receiving the IMAP credential. ## 7.2 Process separation | Component | Network | Secrets | Read access | Write access | |---|---|---|---|---| | IMAP collector | IMAP host only | IMAP credential | Cursor, provider config | Source artefacts, collection manifests | | Rule engine | None | None | Source envelopes, rules | Rule findings | | Model enricher | Configured model endpoint only | Model API credential | Redacted source subset | Candidate enrichment | | Verifier | None by default | None | Sources, rules, candidates | Verification artefacts | | Composer | None | None | Verified outputs | Brief staging | | Publisher | None | None | Brief staging | Export directory | | Static file server | Inbound private-network HTTP(S) | Server TLS/auth material | Export directory | None | | Evaluator | None | None | Artefacts and ledgers | Evaluation artefacts | Use separate Unix users where practical for the collector, model enricher, and static server. Other phase-one processes may share a restricted processing user if separate users would materially increase maintenance. ## 7.3 Network controls Collector egress: configured IMAP hostname and port only. Model enricher egress: configured model endpoint only. Verifier, composer, publisher: no outbound network. Static endpoint: inbound only on the private network. No public internet exposure. No SMTP ports permitted through host egress controls. No mail submission libraries installed as application dependencies. Architecture test scans dependency manifests and source imports for SMTP, mail submission, and messaging clients. ## 7.4 Phase-one no-send enforcement Absent: SMTP configuration · SMTP client dependency · Gmail/Graph mail-send API scopes · a send, reply, forward, or submit provider method · network egress from draft-generation and publication processes · any executor consuming draft files. Drafts are inert Markdown files. The IMAP collector supports only an explicit read-command allowlist. It does not use IMAP APPEND to place drafts into provider folders. ## 7.5 Blast radius **IMAP collector compromised.** Attacker obtains read access to collected personal email, potentially the IMAP credential, and whatever permissions the provider inherently gives that app password. Code and network sandbox reduce normal mutation paths, but possession of the credential may let an attacker connect elsewhere and mutate the mailbox — an unmitigated provider-level limitation unless the provider offers a genuinely read-only credential. Does not obtain model credentials, other domain memory, phone private keys, or identity-document contents stored elsewhere. **Model enricher compromised.** Obtains only redacted messages passed for enrichment, model API credential, candidate-output write access. Cannot access IMAP, alter source artefacts, publish directly, suppress deterministic findings, or read identity-document content. **Verifier compromised.** Can approve misleading candidate text or damage verification artefacts. Cannot read provider credentials, modify source mail, or publish without composer and publisher path. **Publisher compromised.** Can replace personal briefs in the export directory. Cannot read mailbox source bodies if filesystem permissions isolate them, access credentials, contact external recipients, or modify provider data. **Static endpoint compromised.** May read exported brief content and observe timing. Read-only filesystem access, no credentials except endpoint authentication material. **Host root compromised.** All local confidentiality and integrity lost. Not contained by application separation. Recovery depends on host hardening, backups, credential rotation, and rebuild documentation. ## 7.6 Data protection Full-disk encryption where operationally viable · encrypted backups · umask 077 · source directories readable only by their domain processor and verifier · export briefs contain minimum information needed for action · no attachment bodies in phase one · identity and immigration documents referenced only by human-readable name and physical or encrypted-storage location · dates and recorded legal facts may be stored with provenance · backups append-oriented and periodically restored in a test directory. --- # 8. Self-evaluation ## 8.1 What is measured **Reliability:** expected runs vs artefact-backed runs · collection coverage intervals · time from scheduled invocation to publication · age of latest successful provider probe · missed-run recovery time · hash or schema failures · phone-visible publication freshness where observable. **Deterministic recall:** detection rate on fixed synthetic fixtures · findings preserved through verification and publication · results from weekly sampled unflagged messages · operator corrections associated with missed rules. **Model quality:** supported vs unsupported model claims · verifier rejection rate by reason · labels added beyond deterministic rules · visible model text requiring later correction · model outage impact on deterministic publication. **Memory quality:** facts with sources and dates · contradictions properly linked rather than overwritten · facts whose sources are no longer locatable · sampled factual agreement with current authoritative sources · age distribution by domain. **Security and boundaries:** prohibited dependency scan · unexpected network attempts · secret-pattern findings · identity-document content findings · work-boundary exclusions and ambiguous cases · unexpected IMAP commands. **Maintainability:** run duration · disk growth · repeated failures · configuration validation findings · backup restore test age · components enabled without a schedule, artefact, publisher, or silence detector. It does not measure operator response time, completion, discipline, habits, or engagement. ## 8.2 Cadence Per run: schema, hash, citation, rule-floor, prohibited-action checks. Daily: scheduling, freshness, collection coverage, disk, publication. Weekly: fixture tests, source-count reconciliation, sampled classification evaluation, memory sampling. Monthly: slow-domain memory accuracy and operational complexity review. After any version change: dark comparison against the previous version. ## 8.3 Output Concise daily example: ``` System: all 3 expected email runs produced verified briefs. Coverage: IMAP confirmed through 21:30; no deterministic findings were lost. ``` Degraded output names evidence: ``` System warning: the 17:30 collection is not proven complete. Evidence: UID collection found 12 messages; independent mailbox search found 13. Artefact: diagnostics/2026/07/29/email-coverage-....json ``` Monthly output contains findings, supporting artefact identifiers, trends, proposed configuration changes, unmitigated risks. It never automatically enables a proposed change. --- # 9. Phase one: personal email agent ## 9.1 Phase-one outcome Within a few evenings, the operator should receive three scheduled phone-visible personal-email briefs per day, even when: the model provider is down · the system was rebooted during a scheduled run · there are no important messages · a configuration file is incomplete · a model produces bad labels · the operator ignores the system for two weeks. The system must require no daily interaction during that period. ## 9.2 Phase-one boundaries **Included:** one personal email account · app-password IMAP · INBOX collection · deterministic action detection · optional dark model labels and summaries · independent verification · plain-text and Markdown briefs · inert local draft files, initially disabled · scheduled phone retrieval · silence detection · daily and weekly evaluation. **Excluded:** mail sending · replying · forwarding · provider draft upload · marking read or unread · applying provider labels · moving, archiving, deleting, copying · attachment body retrieval · public web UI · search · multiple inbox aggregation · work email · automatic calendar insertion · automatic task creation. ## 9.3 IMAP implementation **Authentication.** Provider-supported IMAP over TLS with an app password. Do not build phase one around a self-created OAuth client using restricted mail scopes. The provider interface must allow a later verified connector, but phase one assumes renewable long-lived app-password access rather than unverified OAuth refresh tokens expiring after seven days. **Read command allowlist.** Permitted: CAPABILITY · NOOP · LOGIN (or library equivalent) · SELECT read-only or EXAMINE · STATUS · SEARCH / UID SEARCH · FETCH / UID FETCH · LOGOUT. Prohibited: STORE · UID STORE · COPY · UID COPY · MOVE · UID MOVE · EXPUNGE · CLOSE where it may expunge · APPEND · mail submission of any kind. The wrapper refuses any command not on the allowlist before network transmission. **Collection algorithm.** 1. Acquire a per-account filesystem lock. 2. Validate configuration without requiring review. 3. Load the last cursor if present. 4. If absent, ask in the next brief whether older history is wanted and continue with a safe default: collect messages from the previous seven days. Do not halt. 5. Authenticate and record a provider probe. 6. Open INBOX read-only. 7. Record UIDVALIDITY. 8. If UIDVALIDITY matches the previous cursor, fetch UIDs above the last observed UID. 9. Also search the previous 48 hours and deduplicate by stable source ID and content hash. 10. If UIDVALIDITY changed, perform a seven-day recovery collection and publish a coverage warning. 11. Fetch headers and permitted text body parts. 12. List attachment metadata but do not fetch attachment bodies. 13. Normalize each message. 14. Write source records and the collection manifest atomically. 15. Run an independent count/search query for the collection interval. 16. Advance the cursor only after source artefacts and manifest pass read-back hash verification. 17. Record the run event. The cursor records account alias, mailbox, UIDVALIDITY, last observed UID, last confirmed collection timestamp, last overlap search boundary, hash of the collection manifest supporting the advance. ## 9.4 Deterministic rules Rules are data in `config/rules/email-v1.toml`, evaluated in order. **act findings.** Explicit deadline or expiry date within configured horizon · payment due, overdue, failed payment, collection, arrears, account suspension · immigration, visa, passport, residency, citizenship, legal notice, court, fine, government correspondence · security event (password reset, suspicious login, recovery change, breach, account lock, new-device notice) · health result, appointment change, referral, prescription issue, insurer action · cancellation or material change to travel, accommodation, utilities, insurance, registration, essential service · sender on the operator-maintained critical-sender list · explicit request directed to the operator containing an action verb and a date · repeated follow-up from the same sender/thread after a configured interval. **review findings.** Financial statement, renewal notice, policy change, receipt above a configured amount if deterministically parseable · personal correspondence containing a direct question · upcoming appointment or reservation · account terms or privacy changes · messages with an attachment, metadata only · dates that could not be safely normalized · ambiguous work/personal boundary. **note findings.** Remaining new personal messages, grouped by sender and subject · delivery notices and routine confirmations not matched above. **Date handling.** Retain the original date text · normalize only when parsing is unambiguous · include timezone assumptions · if ambiguous, surface original text under review · never silently choose between day/month and month/day formats · deadline horizons configurable, defaults 7, 14, 30 days. **Rule precedence.** Effective visibility is `max(deterministic visibility, model recommendation)`. No model field can negate a deterministic reason code. ## 9.5 Model enrichment Initial configuration: model labels observe-only · model summaries observe-only · draft generation off. Observe-only output is written to candidate artefacts and evaluated but not published. After at least 14 consecutive days, model labels may become visible only if all scheduled deterministic briefs were still publishable without the model, no deterministic finding was lost, fixture recall remained complete, unsupported label rate is within an operator-chosen tolerance, and the change is recorded as a configuration change rather than a runtime prerequisite. Model summaries and drafts require separate earned transitions. Model input excludes secrets, attachment bodies, identity-document content, work-excluded messages, unrelated memory partitions, provider credentials and cursor data. ## 9.6 Independent verifier Receives normalized source envelopes, rule configuration, deterministic findings, model candidate output, feature flags — and no producer prompt trace or reasoning. It independently: recomputes deterministic matches · compares source identifiers and counts · confirms all recomputed findings present at equal or higher visibility · validates dates against source text · validates every summary claim against cited source material · checks work exclusion · checks identity-document and secret exclusions · checks draft recipient fields are absent because drafts are inert prose, not message objects · produces the verification artefact. If it fails, the emergency composer uses the verifier's own deterministic recomputation. ## 9.7 Brief format ``` PERSONAL BRIEF — Wed 29 Jul, 17:30 ACT 1. Electricity payment failed — action requested by 31 Jul. Source: "Payment unsuccessful", Example Energy, received 16:42. REVIEW 1. Medical appointment moved; new time appears to be 4 Aug at 09:15. Source: "Appointment update", Example Clinic, received 15:08. NEW, NO ACTION FOUND 3 messages: parcel confirmation, bank statement, family update. SYSTEM Email coverage confirmed through 17:30. Model enrichment was unavailable; deterministic checks completed. ``` If nothing changed: ``` Personal email: nothing requiring action changed. Coverage confirmed through 17:30. ``` The brief does not contain a score. ## 9.8 Drafts Draft generation exists only as an optional later phase-one feature after it earns activation. A draft artefact is plain Markdown containing source message reference, purpose, proposed text, factual claims with citations, questions or missing facts, generation and verification timestamps. It contains no executable addressing or transmission structure. There is no mail-provider draft upload. Progression: off → observe-only drafts for fixture messages → observe-only drafts for selected real messages → visible inert local drafts after verification metrics are acceptable. Even at step four, nothing sends. ## 9.9 Phone implementation Required phone automation: run shortly after 05:00, 17:30, 21:30 · connect through the private network · fetch latest.json using read-only credentials · validate publication identifier, expected timestamp freshness, brief hash after downloading latest.txt · if new, raise a local notification with count of act findings, count of system warnings, first actionable line · open the full brief when tapped · if unavailable or stale, raise a local notification saying the personal brief is unavailable. The static server must serve only `export/` · permit only GET and HEAD · disable directory listing · bind only to the private network interface · have no write permission anywhere · have no access to source messages, memory, or credentials. ## 9.10 Installation artefacts System diagram and threat model · configuration examples without secrets · IMAP capability probe · deterministic rule fixtures · sample mail corpus containing known urgent and non-urgent cases · provider contract tests · no-send dependency and command scan · systemd service and timer definitions · backup and restore instructions · phone automation instructions · two-week unattended acceptance test · recovery runbook no longer than one page. ## 9.11 Acceptance criteria 1. A missing cursor results in a seven-day collection and a question, not a halt. 2. A missing optional config file produces a warning and uses documented defaults. 3. A model outage still yields a deterministic brief. 4. A verifier failure still yields a deterministic emergency brief. 5. A reboot across a scheduled run causes catch-up. 6. A deterministic urgent fixture cannot be suppressed by model output. 7. Empty-mail results use two independent checks. 8. No prohibited IMAP command can reach the network. 9. No mail-send dependency, API scope, endpoint, function, or egress path exists. 10. Attachment bodies are not downloaded. 11. No work fixture reaches the brief or model. 12. No identity-document body reaches storage or model input. 13. Every completion claim references an existing hash-verified artefact. 14. Phone automation warns when the server brief is stale. 15. Fourteen simulated days run without manual clearing, ratification, or acknowledgment. 16. Disk-pressure behavior warns without deleting anything. 17. Re-running a collection produces no duplicate source findings. 18. Draft artefacts cannot be transmitted by any installed component. ## 9.12 Build sequence **Evening one.** Create directories and permissions · install configuration · implement IMAP collector and command allowlist · implement source envelopes, cursors, manifests, overlap collection · run against fixture mailbox then the personal mailbox. *Useful result: immutable collected source artefacts.* **Evening two.** Implement deterministic rules · implement independent verifier · implement deterministic composer and local publisher · add systemd schedules and reconciliation · validate catch-up after a simulated missed run. *Useful result: scheduled local briefs without a model.* **Evening three.** Configure read-only private endpoint · configure phone polling and stale detection · add daily evaluator and fixture suite · enable dark model labels only if desired · start the two-week unattended run. *Useful result: unprompted phone-visible operation with silence detection.* --- # 10. Whole-system future domains All later agents follow the same scheduled source → deterministic floor → enrichment → verification → publication pattern. ## 10.1 Voice inbox agent Accept long unstructured dictation containing transcription errors and incomplete thoughts · preserve original audio · produce transcript, uncertain-span markers, extracted candidate facts, decisions, questions, reminders · ask at most a small number of high-impact clarification questions in the next scheduled brief. Input path: phone uploads audio to a private append-only drop directory; a scheduled collector processes new files; the system never requires the operator to open an application. Voice rules: preserve transcript and audio source reference · never silently repair dates, names, amounts, negation, or commitments · mark uncertain phrases · separate quoted speech, possible tasks, facts, reflections, decisions · a model may propose structure but a verifier checks extracted dates and commitments against the transcript · work-related capture excluded without copying into personal memory. Trigger: email phase runs unattended 14 consecutive days · ≥95% of expected briefs published on time or auto-recovered · silence detection proven by a deliberate failed-run exercise · median weekly maintenance under 15 minutes · operator still produces ≥3 personal voice captures per week with no reliable destination. ## 10.2 Personal administration and deadline agent Consolidate verified dates and obligations from email and voice · produce scheduled upcoming-deadline sections · never create obligations without a cited source. Trigger: voice intake reliable for four weeks · ≥10 recurring personal deadlines across sources · manual reconciliation occurring more than once per week. ## 10.3 Immigration and legal dates agent Track verified dates, application milestones, appointments, questions · store document names and locations only · never store document bodies. Cadence: monthly by default; weekly only within configured proximity to a verified deadline. Trigger: an active immigration or legal process with ≥2 time-sensitive milestones · an authoritative-source review procedure defined · a domain-specific verifier implementable without exposing document contents. Supplies reminders and questions, not legal advice. ## 10.4 Finance review agent Read exported statements or a read-only connector · detect bills, duplicate charges, unusual changes, renewals, cash obligations · produce weekly and monthly summaries. Trigger: ≥2 financial accounts providing stable read-only exports or connectors · operator performs repetitive monthly reconciliation taking more than 30 minutes · a category and amount verification strategy exists. No payment initiation is planned. ## 10.5 Health agent Track operator-entered appointments, measurements, medication facts, questions for clinicians · review slowly unless an upcoming event changes cadence · avoid diagnosis and adherence scoring. Trigger: a recurring health dataset or ≥3 monthly health events · operator identifies a concrete decision the summaries would support · sensitive-data isolation and backup restore have passed review. ## 10.6 Relationship reminder agent Surface operator-recorded dates, promised follow-ups, unresolved questions · never score attention, sentiment, or relationship quality · never infer psychological states. Trigger: voice capture reliably records relationship commitments · ≥5 missed or manually reconstructed follow-ups over two months. ## 10.7 Decision and journal agent Preserve decisions, alternatives, assumptions, evidence, later outcomes · append later contradictions and outcome reviews · offer scheduled reflection prompts tied to actual decisions, not generic daily journalling. Trigger: ≥10 decisions captured through voice · operator has twice needed reasoning that could not otherwise be recovered. ## 10.8 Learning and hobbies agent Surface saved material and next practical entry points on slow cadences · never grade study consistency or hobby progress. Trigger: ≥20 relevant captures exist · operator asks for this domain in three separate voice inputs or repeatedly spends time reconstructing where to resume. ## 10.9 Cross-domain personal brief Compose already verified domain outputs · avoid a new general reasoning layer. Trigger: three domain agents independently meet reliability targets for four weeks · combined notification volume requires consolidation · the composer can fail without preventing individual domain publication. --- # 11. Gates deliberately not included Gates were considered in four places and rejected. **Initial goals review.** A conventional design would require the operator to ratify goals or priorities before operation. Excluded because it recreates the exact ceremony gate that killed the prior system. If goals are absent, the system runs scheduled source collection, applies safe deterministic defaults, publishes useful findings, and adds one concise question to a brief. **Rule approval before first collection.** Also excluded. The initial rule set ships with conservative defaults. Ambiguity increases visibility; it does not halt collection. **Model-enrichment approval before operation.** The system does not wait for model configuration. Model features remain dark or unavailable while deterministic operation proceeds. **Domain-memory ratification.** No draft/accepted/verified workflow field exists. Instead: every fact carries source and date · direct operator statements identified as such · conflicts appended · consequential use requires source citation · missing certainty becomes a question, never a boot condition. Feature flags are not approval gates. They control exposure of optional behavior. The deterministic core operates regardless of their setting. --- # 12. Things deliberately not included **No database.** JSONL, JSON, TOML, Markdown and plain text are sufficient for one operator. A database adds migration, backup, recovery and inspection burden without phase-one value. **No vector store or search index.** Too little phase-one data; search is explicitly outside phase one. **No general agent framework.** The required abstraction is a small file contract, not a platform. **No resident orchestration daemon.** Scheduled processes and filesystem locks are enough; a daemon adds lifecycle and silent-death risks. **No web dashboard.** It would wait to be opened and therefore starve. **No chatbot as the primary interface.** Chat waits for a prompt; voice capture and scheduled briefs do not. **No outbound server notification service in phase one.** SMTP, push APIs, SMS, chat bots and notification relays would introduce send capability. Phone-side polling produces local notifications instead. **No provider-side mail organization.** No labels, marks, archive, move, delete or uploaded drafts. **No automatic task or calendar creation.** Mutations in other systems create false commitments when extraction is wrong. **No attachment processing.** Increases malware, privacy, identity-document, storage and model-exposure risk. **No OAuth implementation for restricted mail scopes.** An unverified individual OAuth client is operationally unreliable because refresh credentials expire on the stated seven-day cycle. **No automatic retention deletion.** Cannot delete without explicit per-item approval; disk growth managed through warnings and operator-selected per-item cleanup. **No scores for the operator.** No streaks, productivity rating, inbox-zero score, relationship score, health adherence score or goal-compliance score. **No daily slow-domain prompts.** Immigration, finance, health, relationships, learning and hobbies use cadences justified by their rate of change. --- # 13. Three most likely reasons it is dead in six months **1. It silently stopped, and the operator assumed nothing needed attention.** Prevention: persistent scheduled runs · hourly independent reconciliation · expected artefacts with hashes · phone-side stale-publication detection independent of the server · coverage warnings instead of unsupported "nothing changed" claims · automatic catch-up from the last confirmed source cursor. *Residual weakness: simultaneous failure of server, private network and phone automation has no independent third alarm in phase one.* **2. It produced too much low-value text, so notifications became invisible.** Prevention: deterministic rules establish a small action floor · "nothing changed" may be two lines · repeated unchanged items collapse · slow domains use slow cadences · model-written text ships dark and must demonstrate value before visibility · self-evaluation measures repetition and unsupported additions, not operator engagement. *Residual weakness: cannot guarantee notifications remain salient during unusually busy periods.* **3. Maintenance expanded until one broken dependency required an evening the operator did not have.** Prevention: one phase-one provider · app-password IMAP rather than expiring unverified OAuth · no database, queue, dashboard, agent framework, search index or resident orchestrator · deterministic operation without a model · plain files readable with standard tools · bounded three-evening implementation · a one-page recovery runbook · later phases must earn entry through observed need and proven low maintenance. *Remaining unmitigated risk: provider withdrawal of app-password IMAP.*