# Intent Solutions — Mission Control program: full document bundle **For the reader (human or AI):** This single file contains every publicly published document from the Intent OS Mission Control program, concatenated for easy reading. You are reading the complete public record. The Intent OS Mission Control program is being designed in full before it is built. This feed carries the current plan, the constitution, and the supporting standards as plain markdown so tools and agents can read them directly. **Start with the program status report — it is the single digest of where the program stands.** Security-sensitive operational documents (infrastructure topology, dependency and single-point-of-failure maps, the risk register) are not published; the authoritative full versions live in the private intent-os repository, and published copies are redacted of identifiers, addresses, secret names, and credential paths. There are 11 documents below, ordered as a reading path: the **program status report** (the current-state digest) first, then the **roadmap** and the **constitution**, then the supporting standards. Each begins with a `======` banner naming the document, then its full markdown. Read the first three for the complete current picture; the rest are reference. ## Contents 1. Mission Control — Program Status Report (2026-07-11) 2. 037-PP-PLAN — Mission Control program roadmap (post-audit revision) 3. 038-AT-DECR — ADR-000: the Mission Control constitution 4. 043-DR-STND — Mission Control success metrics and KPIs 5. 044-DR-STND — Definitions of Done: bead, epic, phase, program 6. 046-AT-ARCH — Repository and platform layering, and the repo-split decision criteria 7. 047-DR-INDEX — Architecture decision log index 8. 050-DR-STND — Program governance cadence and RACI ownership matrix 9. 039-DR-STND — Epic documentation, AAR, and reporting standard 10. 048-DR-INDEX — Mission Control glossary 11. 049-DR-STND — Mission Control non-goals (what it will NOT do) ============================================================================== ===== DOCUMENT 1 of 11: Mission Control — Program Status Report (2026-07-11) ===== source: https://demos.intentsolutions.io/mission-control/reports/2026-07-11-program-status-report.md ============================================================================== # Mission Control — Program Status Report (2026-07-11) > **What this is and why it matters.** A point-in-time status of the Mission Control program for > technical leadership — written so a CTO can understand exactly where the program stands without > reading the codebase or the backlog. It states plainly what is *documented*, what is *decided*, > what is *planned in beads*, and — honestly — what is *built* (nothing yet, by design). It is a > snapshot; newer snapshots supersede it on top of the reports feed. ## TL;DR Mission Control is being **architected and designed in full before any code is written.** The entire program blueprint is being **hand-rolled as a governed backlog** (beads) — deliberately, one epic at a time, checked against the roadmap — so the build proceeds from an approved design, not from guesses. **Phase 0 (discovery + governance) is documented and complete. Phases 1–3 + a technology-selection gate are the design being laid down now. Platform implementation is 0% — and that is the intended state at this stage.** An independent 12-agent audit has already verified the 0%-built reality and hardened the plan. | Dimension | State | |---|---| | Governing documents | **54** numbered artifacts + **10** decision-log entries | | Constitution | ADR-000 ratified, incl. the new **Article V — Standing Infrastructure Assumption** | | Program backlog (beads) | **182** governed issues; Phase 0 closed, Phase 1 hand-roll in progress (**11 epics, 53 beads**) | | Change tracking | Every bead operation is an atomic **Dolt** commit (git-for-data); git mirrors the portable export | | Platform code shipped | **0%** — deliberate; build begins only after the full blueprint is designed + gate-approved | ## Method — design-first, hand-rolled, gate-reviewed 1. **The whole blueprint is designed before building.** Every phase, epic, and task is hand-authored as a bead with a real objective, testable acceptance criteria, references to the governing docs, and build-order dependencies. No scripted/bulk generation — an early scripted attempt produced drift, was torn down, and is being rebuilt by hand. 2. **Staged gate-reviews.** At each phase boundary the design is reviewed and signed off before the next phase is detailed. Build starts only after the full blueprint clears its final gate. 3. **Everything is governed and auditable.** Decisions land in an append-only decision log + an ADR index; changes are tracked in Dolt's version control; a disclosure gate + secret scan run in CI. ## What is documented (the governing set) - **Roadmap** (`037`) — the full program: Phases 0, 1, 2, **2.5 (technology selection)**, 3, and a standing **Phase X (continuous improvement)**, with dependency order and capacity analysis. - **ADR-000 — the constitution** (`038`) — platform-over-tools, API-first, platform-before-UI, the RBAC portal end-state, the integration contract, and standing Articles I–V (Article V = the Standing Infrastructure Assumption: self-hosted-first, sufficient-resources, estate-awareness). - **Standards** — success metrics + KPIs (`043`), Definitions of Done (`044`), repository architecture (`046`), documentation & AAR standard (`039`), program governance + RACI (`050`). - **Decision log** (`001`–`010`) + **ADR index** (`047`) — every architecture decision, its status, and what superseded it. - **Phase-0 audits** — estate/backups/architecture readiness + the exit checklist (`051`). ## Decisions locked (the ones that shape everything downstream) - **Build the full platform ("glory build")** — the complete authenticated RBAC operational platform is committed, not an opportunistic subset; the build order stays disciplined (data-model-first, contract-first API, hardening-floor-first). - **Phase 2.5 — Technology Selection gate** — no Phase-3 epic hard-codes a technology (auth, event bus, workflow, search, portal framework…) without a formal, scored, multi-candidate ADR first. - **ADR-000 Article V — Standing Infrastructure Assumption** — evaluate self-hosted OSS before SaaS (a 4-rung ladder); assume a dedicated production server with sufficient resources; integrate with the existing estate before adding new tech; no dependency without a long-term operational plan. - **Hand-rolled, not scripted** — the blueprint is authored deliberately so the foundation is sound. ## Independent verification (12-agent audit, 2026-07-11) The program through Epic 3.1 was put through an adversarial multi-agent audit (platform architecture, SRE, security, docs, DevOps, product, repo, OSS governance, program management, red team, plus a beads specialist). Headline verdict, confirmed by every reviewer: **implementation is ~0% — the platform is fully specified and entirely unbuilt.** The audit also found real backlog drift in the first (scripted) pass — which is exactly why the backlog was torn down and is being hand-rolled. The audit's remediation is being actioned as the hand-roll proceeds. ## Program backlog — where the beads stand - **Phase 0 — complete** (closed with evidence): mission alignment, estate audit, program planning, the constitution, the standards, the decision framework. - **Phase 1 — hand-roll in progress (11 of ~18 epics rolled):** the hardening floor (dev-box hardening · off-site + immutable backup · DR game-day + per-engine DB dumps · alert floor + dead-man's-switch), plus GitHub-independent repo mirroring, provisioning-as-code (Ansible), the API-first schema foundation, the incident process, deploy-safety auto-revert, the gated runbook merge, and the verify-and-document pass. Each with testable acceptance and floor-first ordering. - **Phases 2 / 2.5 / 3 / X — designed in the roadmap, to be hand-rolled next**, phase by phase, through the gate-review cadence. ## Where we are, and what's next **We are architecting.** The next milestones are: finish the Phase-1 hand-roll → **Phase-1 gate-review** → hand-roll Phase 2 (observability + platform services) → gate → Phase 2.5 (technology selection ADRs) → gate → Phase 3 (the portal) → gate → Phase X → **final blueprint sign-off**, after which implementation begins against an approved, fully-designed plan. *Snapshot as of 2026-07-11. The reports feed carries the roadmap, the constitution, and the standards in full for deeper reading.* ============================================================================== ===== DOCUMENT 2 of 11: 037-PP-PLAN — Mission Control program roadmap (post-audit revision) ===== source: https://demos.intentsolutions.io/mission-control/reports/2026-07-11-program-roadmap.md ============================================================================== # 037-PP-PLAN — Mission Control program roadmap (post-audit revision) > **What this is and why it matters.** This is the implementation roadmap for turning Intent > OS into the Mission Control platform. It is the **post-audit revision** — a first draft was > deliberately put through a ten-agent adversarial audit (`040-AA-AUDR`), scored 6/10, and > rewritten around what the audit found. The draft's fatal flaw, in the panel's words, was > being "well-argued essays, not an executable plan": it under-specified its two load-bearing > moves (off-site backup, the runbook merge) in exactly the ways they fail under real > conditions, silently dropped two catastrophic single points of failure its own discovery > had ranked, and shipped with no measurable exit criteria. This version reframes the whole > program **from "observe the estate" to "harden the estate,"** carves the one > irreversible-loss fix out as a hotfix that ships before roadmap sign-off, gives every epic a > one-line acceptance test, and answers the audit's structural findings. Phases 1–3 beads are > cut only after Jeremy approves this document (the Phase-0 exit gate). - **Program:** Mission Control (constitution: `038-AT-DECR` / ADR-000) - **Status:** the filed post-audit revision; supersedes the pre-audit draft (`ws6-roadmap-draft`, not filed). **Rev. 2026-07-11 (CTO pass):** Jeremy proposed Phase-1 ops epics (1.14–1.18), Phase-2 platformization (2.6–2.15) forward, and a standing **Phase X**. CTO ruling applied same day — 1.14/1.17/1.18 kept as real work, **1.15 downgraded to a review norm** (gate deferred behind a contributor-count trigger), **1.16** confirmed largely-delivered; of the 10 Phase-2 platform epics only 2.13 + 2.6 were first kept committed. **Rev. 2026-07-11 (glory build — Jeremy's principal call, `decision-log/009`, supersedes the DL-008 D41 trim):** *"we build for glory"* — **all ten platform epics committed** (full data model, full API fleet, event bus, registries, asset graph, search, reporting engine, plugin architecture) **+ tracing (2.16) + central logs (2.3) promoted + a full RBAC portal** (3.6 roles, 3.7 fan-out, 3.8 cost dashboards, 3.9 compliance un-deferred). CTO keeps the *build order* (producer-driven model, contract-first API, hardening-floor-first) as competence, and states the **true bill** in new §9b (dedicated capacity + a second box + floor-first). Phase X adopted. Rationale: `decision-log/008` + `009`. **Rev. 2026-07-11 (Phase 2.5 inserted, `decision-log/010`):** a **Platform Technology Selection & Reference Architecture** phase (§5b, epics 2.5.1–2.5.12) inserted between Phase 2 and Phase 3 as the *final gate before implementation* — every technology (auth, authz, workflow, event bus, search, notifications, reporting, storage, AI agents, portal framework) is formally evaluated (multi-candidate, scored, ADR + rejected-alternatives) before any Phase-3 epic hard-codes it; prefer self-hostable OSS. Inserted as a decimal (no renumber). Dependency graph + Phase-3 gate updated. - **Inputs:** `033`–`036` (discovery), `040` (adversarial audit), `041` (risk register), `031-AA-AACR` (2026-07-10 remediation ground truth), `002-AA-AUDR` (brain readiness) - **Audit corrections folded:** all 26 roadmap corrections in `040` §3; the 16 missing epics (E1–E16) in `040` §4; the risk register (`041`) owns the tracking --- ## 1. What changed — from the brief, and from the pre-audit draft **From Jeremy's original brief (discovery corrections):** 1. "No trusted backup strategy" was stale — borg daily + dev-box replica + a passing monthly restore drill exist. The real gap is narrow: **no off-site copy, and no proof the business databases restore at all.** 2. Most of proposed Phase 1 already exists and is drilled. Phase 1 is **harden + verify + document + fill residual gaps**, not greenfield. 3. Two Phase-2 candidates are rejected on evidence: OneUptime (heavy monolith) and Tempo (nothing emits traces). See `035` Part B. **From the pre-audit draft (audit corrections — the substantive ones):** 4. **Off-site "append-only" is not immutability.** rclone append-only is client-side; the R2 token lives in a file the compromised dev-box key can decrypt. Immutability is now a hard, tested requirement (R2 Object Lock or `borg serve --append-only` on a different provider). 5. **The business databases are backed up as torn live datadir copies and never restore- tested** (the drill only checks SQLite). Per-engine consistent dumps + a Postgres/MariaDB boot-and-query drill are now in scope. 6. **Two ranked SPOFs the draft dropped are back:** Slack as the only alert sink, and the dev box as the correlated-loss keystone. 7. **Identity stops shopping for a heavyweight IdP** — the estate already runs per-user tokens + a write-gate + an actor-audit chain in production (the qmd/INTKB knowledge-base service). We reuse that pattern + Tailscale identity; a real IdP unlocks on a user-count trigger. 8. **Every epic now has a measurable acceptance test and a phase go/no-go gate;** the one irreversible-loss fix is carved out ahead of roadmap sign-off. ## 2. Jeremy's decision points (the roadmap's gates) The audit deduped these across all ten lenses (`040` §7). Recommendation is the panel's; the final call is Jeremy's. | # | Decision | Recommendation | Blocks | |---|---|---|---| | J1 | Merge the VPS runbook into intent-os? | **Merge the docs** (unsquashed subtree under `ops/`), but see J2b for secrets | Epic 1.3 | | J1b | Secrets on merge | **Keep `[encrypted secrets file]` federated** in a tighter-membership boundary (submodule / separate repo + CODEOWNERS), OR accept blast-radius collapse with recorded compensating controls. Jeremy's lean is full merge; the panel's engineering rec is federate | Epic 1.3 | | J2 | Off-site destination **+ immutability mechanism** | R2 with **Object Lock + a delete-incapable token**, OR a **different provider** (B2/Hetzner/`borg serve`) for independence from the brain's R2. Immutability required either way | Epic 1.1 (hotfix) | | J3 | Phase-2 per-tool verdicts | Accept `035` Part B: trio integrate-later, OneUptime skip, Tempo skip, keep borg + off-site, adopt Ansible; **add Watchtower** (J7) | Phase 2 scope | | J4 | RAM/budget appetite | Trio ~0.9–1.5 GiB; re-stated against **committed RSS** (6.0 GiB used, box already 2.2/4.0 GiB into swap — not "17 GiB free margin"); cap Loki/Prometheus retention day one | Phase 2 timing | | J5 | Identity/RBAC direction | **Ratify reuse-INTKB + Tailscale identity**, user-count trigger for a real IdP; kills the IdP-shopping; resolve at Phase-1 exit | Phase 3 | | J6 | Status page wanted at all? | If yes, Gatus (~20 MB); if the real need is incident state, build the incident model (Epic 1.4b) instead | Phase 2 | | J7 | Watchtower | Digest-pin + smoke-gate the 3 stacks, OR a dated ADR-000 §9 exception (note the CLAUDE.md "no custom CI/CD for these three" tension) | Epic 1.4/2 | | J8 | Per-stack RPO targets | Accept ~24h for ERPNext/Twenty/DiagnosticPro-Stripe, OR fund sub-daily WAL/PITR — a single-host+daily choice is fine but must be **stated** | Epic 1.1 | | J9 | Single-host acceptance / standby | Accept the Contabo single-host SPOF explicitly, OR plan a standby — **file the decision either way** | Phase 1/2 | | J10 | Publish the reports feed publicly at all? | **Default-deny**: publish only a separately authored, sanitized executive summary; keep SPOF/topology/deploy internals private, OR gate the whole feed behind the tailnet. **Applied already** (see §9) — Jeremy confirms or overrides | Phase 0 | | J11 | Dev-box SSH hardening | Authorize key-only / tailnet-only SSH — password auth is effective today under active brute-force (verified `sshd -T`) | Epic 1.0 (pre-merge blocker) | | J12 | `~/.env` SOPS-ification timing | Early Phase 1 (panel rec) vs accept-as-is | Epic 1.6 | | J13 | Governance ceremony tiering | Approve the lightweight lane for routine epics vs full AAR for phase-closes/incidents | `039` amendment | | J14 | Carve Epic 1.1 as a pre-roadmap hotfix? | **Yes** — ship off-site + immutability the day J2 is answered, before approving the full roadmap | Epic 1.1 | | J15 | Approve the reframed roadmap as the Phase-0 exit gate | — | Phase 1 beads | ## 3. Epic 1.0 / 1.1 — the pre-roadmap hotfixes (ship before full sign-off) The audit's sharpest structural point: **do not hold the only irreversible-loss fix behind a 15-epic review.** Two epics are authorized by their own decision gate and ship immediately. - **Epic 1.0 — Dev-box hardening (pre-merge blocker, gate J11).** The dev box holds Jeremy's age key, the plaintext `~/.env` keystore, the R2 credentials, the borg replica, and the governed brain; the roadmap later makes it the Ansible control node and the off-site origin, raising its blast radius. Password SSH is effective today under active brute-force (verified `sshd -T`: `passwordauthentication yes`). **Harden to key-only or tailnet-only SSH; back the dev box's critical state off-box; make the VPS able to run the R2 push so off-site survives dev-box loss.** *Acceptance: `sshd -T` shows `passwordauthentication no` (or SSH is tailnet-only); a dev-box-state backup exists off-box and is restore-checked; `033` §1.1 is corrected. Ships before Epics 1.1/1.2/1.3.* - **Epic 1.1 — Off-site + immutable backup (hotfix, gate J2).** Get the last copy off the estate and make it undeletable. **R2 Object Lock + a delete-incapable write token under a separate recipient scope, OR `borg serve --append-only` to a different provider than the brain's R2.** Escrow the borg passphrase + a dedicated restore-only age key off both boxes. Specifics folded in from Jeremy's roadmap notes (2026-07-11): **dedicated per-environment R2 buckets — one Development, one Production — with separate credentials each**; encrypt before upload (already true via age); **automated restore verification** + **backup-health monitoring** wired to the notify spine; and a **second off-site copy on a different provider (Backblaze B2 or Wasabi)** stood up *after* the primary off-site is operational (provider independence answers the R2 correlated-loss risk, `041` R17). The **backup engine itself (keep borg + rclone vs adopt Restic) is an explicit Phase-1 evaluation** — this analysis (`035`) leaned keep-borg for its passing restore drill; Restic's native S3/R2 is the counter- argument; the eval decides. *Acceptance (the test that defines "done"): delete/encrypt the source borg repo, then prove the off-site copy still restores on a clean host — transcript linked. Closes `OPS-lqj` / `OPS-lao.19`.* - **Epic 1.1b — GitHub-independent repository mirroring.** GitHub is a single point of failure in the dependency graph (`036`): it is repo host + CI engine + issue mirror at once. Mirror every repo to a second, independent remote (a self-hosted bare-git on the VPS/off-site, or a second forge) on a schedule, so a GitHub outage or account loss does not lose the code. *Acceptance: a full clone can be reconstructed from the mirror with no GitHub access.* ## 4. Phase 1 — harden the estate (verify, prove, service-shape) Goal: prove the estate survives a real disaster, close the ranked SPOFs, and make the existing fabric documented and machine-readable. Every epic is independently shippable; order within the phase is by risk. **Phase-1 exit gate = every epic's acceptance test green AND a Jeremy go/no-go.** - **Epic 1.2 — Provisioning-as-code (Ansible).** Inventory both hosts; roles codify the seven `OPS-qr2` bootstrap phases. Add a drift-capture step + a recurring `--check` dry-run; name the scratch-VM substrate (libvirt/Multipass/throwaway Contabo — Contabo is not API-provisioned). *Acceptance: a scratch VM converges from the playbooks and passes a config-parity check against the live box.* - **Epic 1.3 — DR game-day + per-engine DB backups.** Join the two DR halves the draft built separately. Add `pg_dumpall`/`mariadb-dump` (consistent dumps) to the daily backup; change the drill to boot a restored Postgres and MariaDB and run a real query. Then a full game-day: throwaway box ← Ansible (1.2) ← off-site restore (1.1) ← boot ≥1 Postgres stack + 1 static site ← smoke. The game-day becomes a **standing quarterly DR exercise** (Jeremy's roadmap note), and the epic produces **backup-architecture diagrams + written disaster-recovery runbooks** as first-class deliverables per `039-DR-STND`. *Acceptance: measured wall-clock RTO recorded as the deliverable; the business databases open and answer a query from the restored copy; the DR runbook + diagrams are filed and a quarterly cadence is scheduled.* - **Epic 1.4 — Service-shape foundations (the API-first down payment).** Land, in a new `schemas/` dir, versioned JSON Schemas with a **canonical Service/Host/Environment entity (schema v0) FIRST** — every leaf schema references its stable ID. Then: NDJSON `notify.log`, a JSON liveness-sweep artifact, a `pnpm mc` JSON snapshot, the alert label schema, an **action-audit event schema** (subject/action/resource/timestamp/actor-type/outcome) with capture beginning in Phase 1, and an **authorization model** dimension (subject/resource/ action) so authz is not a Phase-3 retrofit. *Acceptance: each schema has a CI-wired validator AND its producing script fails the build on non-conforming output; each names an owner and an additive-only evolution rule. No schema lands without an enforcing consumer.* - **Epic 1.4b — Incident process + producer (before the incident schema is "done").** Define severities and a declare/ack/resolve lifecycle on one page; the notify spine (which already classifies severity) opens an incident on high/urgent; a Slack slash-command/emoji acks. *Acceptance: a real alert opens an incident record; an ack transitions it.* - **Epic 1.5 — Alert floor + dead-man's-switch (SPOF #2).** An external dead-man's-switch (healthchecks.io, ~$0) on both liveness sweeps + one Slack-independent floor channel (SMTP/email) the canary escalates to on a Slack non-200. Guarantee the **raw event is delivered verbatim** alongside the LLM-normalized sentence for every high/urgent/security alert. *Acceptance: kill the Slack webhook in a drill; the floor channel + external switch both fire. Closes `OPS-lao.20`.* - **Epic 1.6 — Deploy-safety hardening (the program's own north star).** Build previous-image auto-revert into the VPS deploy wrapper so a smoke failure reverts unaided; make an explicit staging decision for the 3 hand-CI'd customer stacks (or record compensating controls); rename the misleadingly-named smoke step; add `actionlint` + a smoke-of-the-smoke test. *Acceptance: a deliberately-broken deploy auto-reverts and the box serves the prior image.* - **Epic 1.7 — Runbook merge (gated J1/J1b).** Execute `034`'s checklist with the audit's fixes: the **full-history gitleaks scan is a completed hard gate before the subtree choice**; path-scoped markdownlint (keep disclosure + gitleaks repo-wide); a **companion dedup epic** designating one generated canonical topology source (box-info.yaml → JSON); secrets kept federated per J1b. Sequenced **after** Epic 1.0 (dev-box hardening) and 1.1 (off-site). *Acceptance: CI green on the merged tree; the four topology-duplication sites reduced to one generated source; secrets boundary decision recorded.* - **Epic 1.8 — Verify + document the built fabric.** Per `039-DR-STND` (tiered ceremony): each existing capability gets its architecture + operating doc + rollback note; stale docs fixed (port-map ERPNext label, onboarding OPS-b78 note, system-map provenance, both age-key scopes documented, RESTORE.md three-copy reality); the named reliability gaps enumerated (sidecar health probes + pending `daemon-reload`; the chronically-stuck dolt server paging; per-stack uptime probes to cut the 24 h outage-detection latency for 6 of 7 stacks) or each deferred out loud. A **governed Estate Operator Day-1 runbook** is authored. *Acceptance: a competent stranger can operate each capability from its doc; the reliability-gap list is closed or explicitly deferred.* - **Epic 1.9 — Secrets-management evolution.** Finish the SOPS/age propagation; SOPS-ify the dev-box `~/.env` (J12); document both VPS age-key scopes; rotate anything chat-pasted Jeremy hasn't explicitly declined. *Acceptance: `sops-init --check` passes estate-wide; `~/.env` is SOPS-managed or an exception is recorded.* - **Epic 1.10 — Dependency-lifecycle / CVE / EOL / license track (cross-cutting).** Image + dep CVE scanning (Trivy/Grype/renovate) routed through the notify spine; a written patch-cadence SLA; a committed EOL register; a one-page license register (rule: **Grafana/Loki are AGPLv3 — stay unmodified and internal-only; any modification or external offering triggers legal review**). *Acceptance: a CVE in any of the 36 images pages the spine; the license + EOL registers exist.* - **Epic 1.11 — Bus-factor drill.** [the CTO] executes a from-scratch restore + a manual deploy with no Jeremy and no AI, timed, findings filed. *Acceptance: a second human completes recovery; the gaps found become beads.* - **Epic 1.12 — Reports-feed publish gate (default-deny).** Replace the token-blocklist scrub with an allowlist + a hard-fail publish gate; the public feed carries only sanitized executive summaries (SPOF tables, dependency graphs, topology, deploy internals, hostnames, IPs, personal identifiers stay private). *Acceptance: the gate rejects a full discovery doc and passes a sanitized summary. Landed in Phase 0 already (§9) — this epic hardens it.* - **Epic 1.13 — SLI catalog + per-stack RPO decision (J8).** A minimal SLI catalog (per-domain uptime, backup freshness, restore-drill recency, alert-path liveness — most already exist as sweep rows) + a conscious per-stack RPO. *Acceptance: every customer stack has a stated RPO and a "healthy" definition; RPO/RTO + last-drill-date are added to the ADR-000 §7 contract.* **(Merged with Epic 1.14 below — the SLI catalog is the collection half of the metrics implementation.)** ### Phase-1 operationalization epics (Jeremy, 2026-07-11) > **Framing — read this first.** Phase 0's completion round already *defined* the metrics > (`043`), the Definitions of Done (`044`), the repository architecture (`046`), and the > governance calendar + RACI (`050`). These four epics are the **implementation** of those > definitions — turning documents into live collection, enforced gates, and scheduled jobs. > They are scoped as "operationalize/enforce/extend the Phase-0 artifact," not "author it > again," and each cites the document it makes live. Where an item is already delivered by a > Phase-0 doc, that is stated rather than re-scoped as new work. - **Epic 1.14 — Platform success-metrics collection (implements `043`).** Absorbs Epic 1.13's SLI catalog. Build the *collection* the KPI catalog defines: wire each metric to a source (uptime probes, backup logs, incident records, deploy results, coverage scans), emit the metric values as structured data (JSON, alongside the `037` Epic 1.4 schemas), and compute the three **composite scores** added to `043` — a reliability score, a documentation score, and a platform-maturity score. Every metric gets its owner, collection method, review cadence, and success threshold (already tabulated in `043`; this epic makes them true). *Acceptance: each KPI in `043` has a live data source emitting structured values; the three composite scores compute from real inputs; nothing is "manual" that a cheap job could collect.* - **Epic 1.15 — Definition-of-Done as a review norm (implements `044`; gate deferred).** *CTO ruling, 2026-07-11:* the four DoD checklists (`044`) are adopted **now as a review norm** — the closing PR/AAR must show the DoD lines satisfied, checked by the reviewer, not by a built gate. A **machine gate** (a `bd`-close preflight or CI check that blocks close on a missing AAR/sign- off) is real engineering that also fights the bd rapid-write flow, and at two contributors the norm doesn't drift enough to justify it. **Trigger to build the gate:** contributor count crosses ~4, **or** an audit finds ≥2 epics closed out of DoD compliance. *Acceptance now: every epic-closing PR demonstrates its `044` DoD in the AAR; the gate is a backlog item behind the stated trigger, not Phase-1 build work.* - **Epic 1.16 — Repository architecture (largely delivered — `046`).** The layered stack, the future services/packages/repositories/APIs/schemas map, and the repo-split/merge + module/ service-boundary criteria are **already documented in `046-AT-ARCH`**. This epic is therefore a thin standing item: keep `046` current as the estate grows (a governance-calendar review, `050`), and — the one genuinely new piece — extend it with the concrete future-services and future-schemas map produced by the Phase-2 data-model and API epics (2.6/2.13). *Acceptance: `046` reflects the Phase-2 platform structure once those epics land; no fresh authoring needed now — the criteria exist.* - **Epic 1.17 — Program governance, operationalized (implements `050`).** The governance calendar, review schedules (architecture/security/dependency/DR/roadmap/quarterly planning), and RACI matrix are **authored in `050`**. This epic wires the recurring items into actual scheduled jobs/reminders (each with its automations-registry row) so governance is *operational, not ad hoc* — the weekly backup check and page-regen, the monthly dependency and doc-freshness reviews, the quarterly DR/architecture/security reviews. *Acceptance: every recurring `050` activity is a scheduled, registered job or a calendared reminder with an owner; none rely on "when someone remembers."* - **Epic 1.18 — Ownership matrix, extended (implements `050` §2).** `050` already carries a RACI over Jeremy/[the CTO]/agents. This epic **extends** it to per-capability ownership across the ten areas Jeremy named (infrastructure, repositories, documentation, services, runbooks, monitoring, security, backups, incident response, AI agents), and assigns each **critical capability a named owner** at its ADR-000 §7 contract sign-up. RACI stays the default; DACI is offered where a single decider matters more than a single accountable. *Acceptance: every critical capability has one identified owner; the matrix covers all ten areas.* ## 5. Phase 2 — observability, then platformization Gated on Phase 1's schemas existing (tools land on contracts, not ad hoc) and on the RAM budget re-stated against committed RSS (J4). - **Epic 2.1 — Metrics substrate:** Prometheus scraping Netdata's exporter endpoint (keep Netdata as agent); Grafana as the portal's embed target (AGPL: unmodified, internal-only). - **Epic 2.2 — Alert data model:** Alertmanager routing Prometheus alerts; the notify spine stays the delivery sidecar (webhook → spine → Slack), preserving LLM normalization + the secret-guard + guaranteed raw-event delivery. - **Epic 2.3 — Logs (need-gated):** Loki + promtail with a day-one retention policy, only when an incident actually hurts from missing central logs. - **Epic 2.4 — Identity/RBAC substrate (J5 executed):** stand up the reuse-INTKB + Tailscale identity pattern; SSO in front of Grafana/Netdata as first consumers; 3 real roles (admin/operator, on-call/member, scoped-read contractor). - **Epic 2.5 — Watchtower pin-and-gate (J7):** digest-pin the 3 stacks and gate updates (pull → smoke → promote → auto-rollback, reusing the 1.6 wrapper), or a dated exception; Epic 1.4's incident/deploy model ingests Watchtower events. - **Explicitly skipped** (rationale recorded so future phases don't relitigate blind): OneUptime, Tempo, Restic. ### Phase-2 platformization epics — ALL COMMITTED (Jeremy: "we build for glory", 2026-07-11) > **Decision (Jeremy, principal call — supersedes the same-day CTO restraint recommendation).** > The one genuinely-his portfolio question — build Mission Control as a *product-grade platform*, > or keep it operationally-humble and spend the capacity on revenue — is **answered: we build the > full platform.** All ten of Jeremy's platformization epics are **committed Phase-2 work**, not a > demand-triggered backlog. Recorded in `decision-log/009-2026-07-11` (D45); it reverses DL-008 > D41 (the trim), which is now marked superseded. > > **What the CTO keeps even in glory mode — because it is competence, not restraint:** the *order* > below is load-bearing. Building all ten is the mandate; building them in the wrong order is how > a big platform collapses under its own weight. So: the data model is built **producer-order** > (each entity lands as its emitter is built — but every emitter *is* built), and the API is built > **contract-first** (one convention ADR, then the full endpoint fleet conforms to it). These are > sequencing discipline, not scope cuts — the destination is the whole thing. **Dependency-ordered build (the critical path through Phase 2's platform tier):** - **Epic 2.13 — Operational data model [committed, full].** The canonical schemas for **every** platform entity — Service, Host, Environment, Incident, Backup, Deployment, Automation, Agent, Runbook, Metric, Alert, Event, User, Role, Permission — extending the Epic 1.4 entity. Each versioned with a validating consumer (the `035`/`040` anti-drift rule). *Built in producer order (an entity ships when its emitter ships), but all producers are in scope. Acceptance: every platform entity is modelled, versioned, and has a live producer by Phase-2 exit.* - **Epic 2.6 — Internal API platform [committed, full fleet].** The API-convention ADR + skeleton **first** (auth via tailnet + 2.4 RBAC, versioning, error shape, pagination, read/write split, mandatory audit log), then the **full capability API fleet** over the 2.13 model — inventory, monitoring, backups, deployments, incidents, agents, services, schemas, audit. **No UI or automation touches infrastructure directly; everything calls the API.** *Acceptance: every capability exposes a documented, RBAC'd, audited API; the portal is a pure client.* - **Epic 2.7 — Event bus [committed].** Event-driven fabric — deployment-completed, backup-failed, restore-succeeded, incident-opened, service-unhealthy, repository-updated, security-alert, agent-started (Event entity, 2.13). *Automations consume events, not polls; the notify spine and incident producer publish. Acceptance: the estate's automations are event-driven end to end.* - **Epic 2.9 — Service registry [committed].** Every service self-describes from data — identity, owner, health, dependencies, endpoints, version, environment, runbook, SLO (Service entity, 2.13) — retiring the markdown `self-hosted-services.md`. *Acceptance: "what services exist?" is answered from data.* - **Epic 2.10 — Automation registry v2 [committed].** Every automation class in one registry — scheduled, event-driven, AI agents, background workers, hooks, webhooks (Automation/Agent entities, 2.13), extending today's scheduled-only registry. *Acceptance: every automated process in the estate is discoverable in one place.* - **Epic 2.8 — Asset graph [committed].** The relationship graph across hosts, services, containers, repositories, agents, schemas, databases, incidents, dependencies — for real **impact analysis**. *Acceptance: any node's blast radius ("if this dies, what breaks?") is answered from the graph.* - **Epic 2.14 — Search platform [committed].** One query surface over runbooks, services, incidents, AARs, ADRs, docs, schemas, repositories. *Acceptance: "where is the runbook / ADR / incident for X" is one query, not a grep.* - **Epic 2.15 — Executive reporting engine [committed].** Auto-generate the weekly/monthly/ quarterly summaries `039` + `043` define, from the data model, feeding the reports feed. *No human assembles a report by hand. Acceptance: reporting is generated, consistent, scheduled.* - **Epic 2.11 — Plugin architecture [committed].** Products integrate **without patching the core** — registration, versioning, capability discovery, lifecycle, permissions, configuration; the ADR-000 integration contract as a runtime extension point. *For a multi-product platform this is foundational, not deferred. Acceptance: a product joins by registering, not by a patch.* - **Epic 2.16 — Distributed tracing [committed — glory addition].** The audit skipped Tempo because *nothing emits traces*. Glory build reverses that: **instrument the services so traces exist**, then land Tempo + the trace pipeline. *Don't skip the telemetry for lack of data — build the data. Acceptance: request flows across the platform are traceable end to end.* - **Epic 2.3 — Central logs [committed, promoted from need-gated].** Loki + promtail with a day-one retention policy — no longer waiting for an incident to hurt. *Acceptance: central logs exist before the incident that needs them.* **Portal design system (Jeremy's 2.12)** builds with the first portal screens in **Phase 3 (Epic 3.0)** — a UI system is built *with* the UI, which is sequencing, not a cut; the commitment to build it is total. **Scope reality (the true bill — no shortcuts on the honesty either).** This is a **~14-epic Phase 2** plus a full Phase 3 portal. That is a genuine multi-quarter engineering program, and the CTO owes the principal three hard requirements the glory build actually needs — see the new **§9b Capacity & the true bill**. Committing to glory means committing to those, not just to the epic list. ## 5b. Phase 2.5 — Platform Technology Selection & Reference Architecture (Jeremy, 2026-07-11) > **Why this phase exists (and why it's the right call).** The roadmap as written transitions > straight from platform foundations (Phase 2) into implementation (Phase 3), and several Phase-3 > epics quietly *assume* technology choices — an auth system, an event-bus engine, a workflow > runner, a portal framework — that were never formally evaluated. That is precisely what ADR-000's > platform-first / **evaluate-don't-assume** doctrine forbids: never hard-code an implementation > technology before deliberately evaluating it. Phase 2.5 closes that gap. It is inserted as a > **decimal (2.5), not a renumber** — chosen over renumbering Phase 3→4 because renumbering would > break every existing bead ID, ADR reference, and cross-link for zero benefit. **This is not an implementation phase — its output is engineering decisions, not software.** It is the **final gate before implementation.** Every Phase-3 implementation epic must reference an ADR produced here; **no Phase-3 epic may hard-code a technology not selected in Phase 2.5**, and Phase-3 epics *implement previously-approved architecture — they never make technology decisions.* **Deliverables:** ADRs · Technology Evaluation Reports · Reference Architectures · Dependency Inventories · an Open Source Bill of Materials (OSBOM) · SaaS Evaluation Reports · version / upgrade / fork policies · Security Review docs · Compatibility Matrices · Operational Ownership · Lifecycle docs. **Per-evaluation-epic rubric (every 2.5.x epic must produce):** Business objective · functional + non-functional requirements · candidate technologies · a scored comparison matrix (license, community health, release cadence, security history, resource consumption, operational complexity, migration difficulty, vendor lock-in, long-term sustainability, cost) · integration / API / upgrade / rollback / replacement strategy · a **recommendation with every rejected alternative and the reason it was rejected** · an **ADR** · acceptance criteria · future-phase hooks. **Selection principle (binding):** prefer **open-source, self-hostable, internally-governable** software; adopt SaaS only where it delivers a clear operational advantage outweighing cost, vendor dependency, security, and maintenance burden. Mission Control must remain **operable independently of any single commercial vendor** wherever reasonably achievable. **Standing infrastructure assumption — now ADR-000 Article V (Jeremy, 2026-07-11; binding on every phase/epic/tech decision, not just 2.5.x; change only with Jeremy's explicit approval).** Intent Solutions runs a **dedicated production server capable of self-hosting operational infrastructure** — assume it is available to host supporting platform services. Do **not** default to SaaS because it's easier. **Assume sufficient production resources:** never reject a high-quality OSS component for an extra ~500 MB of RAM if the box has capacity — optimize first for maintainability, reliability, and long-term architecture; resource optimization is driven by *measured* constraints, documented, never assumed up front. - **Mandatory evaluation order (self-hosted-first ladder):** (1) an **existing capability already running in the estate**; (2) **existing OSS that can be self-hosted**; (3) **lightweight commercial software with a self-hosted deployment option**; (4) **SaaS — only** when it provides significant operational advantage outweighing vendor lock-in, recurring cost, operational dependency, data-ownership, security, and loss of platform control. **Every SaaS recommendation must explicitly justify why it beats an appropriate self-hosted alternative.** - **Estate awareness (integrate before introducing new tech):** assume the platform already includes the dedicated **production** + **development** servers, **Tailscale** networking, **GitHub**, **Cloudflare** + **Cloudflare R2**, **Slack**, **Dolt**, **Mission Control**, **Intent OS**, the existing **monitoring stack**, **backup platform**, and **CI/CD**. Recommendations integrate with these **before** adding anything new. - **Preferred technology traits:** OSS licensing, active community, long-term sustainability, strong docs, API-first, containerized deployment, health monitoring, backup + upgrade + DR support. - **Managed-service, not standalone-tool:** new OSS components become **managed platform services inside Mission Control**, not isolated tools. - **No adoption without a long-term operational plan.** Every adopted dependency ships with installation automation, configuration management, health monitoring, and a backup / upgrade / rollback / documentation / ownership / lifecycle / AAR plan (this is the 2.5.12 OSBOM row for it). **Sequencing note (a refinement Phase 2.5 forces — CTO, 2026-07-11).** "Between Phase 2 and Phase 3" is right for the *net position*, but a few Phase-2 epics are **engine-dependent**: 2.7 event bus, 2.14 search, 2.15 reporting, 2.10 automation cannot have their *runtime engine* built before it's *selected*. So Phase 2.5 **interleaves**: the vendor-neutral Phase-2 work (2.13 data model, 2.6 API contract, the event *schemas/catalog*, the service *metadata model*) proceeds first and is what 2.5 evaluates against; then 2.5 selects the engines; then the engine-dependent *build* of 2.7/2.10/2.14/ 2.15 completes against its ADR. This is wired in beads (2.7→2.5.5, 2.14→2.5.6, 2.15→2.5.8, 2.10→2.5.4) so no epic builds a runtime before its engine is chosen. **The epics (each produces an ADR):** - **Epic 2.5.1 — Platform Technology Governance [foundational — do first].** The evaluation methodology itself: evaluation criteria, scoring framework, ADR template, technology-lifecycle policy, approval workflow, sunset policy. *Every other 2.5.x epic uses this. Children: 2.5.1a–f.* - **Epic 2.5.2 — Identity & Authentication.** Evaluate Auth.js · Authentik · Keycloak · Zitadel · SuperTokens · Better Auth (+ future). Selects the platform's identity substrate (feeds Phase-2 identity 2.4 + the portal's auth). - **Epic 2.5.3 — Authorization & Policy Engine.** Evaluate built-in RBAC · Cerbos · Open Policy Agent · Permit.io · Casbin. → ADR. - **Epic 2.5.4 — Workflow & Automation Platform.** Evaluate Temporal · Trigger.dev · Windmill · BullMQ · n8n · Inngest · native. Decides what belongs to Mission Control vs an external engine (feeds automation 2.10 + the 3.1 automation framework). - **Epic 2.5.5 — Event Bus.** Evaluate NATS · Redis Streams · RabbitMQ · Kafka · native. → ADR (feeds Phase-2 event bus 2.7). - **Epic 2.5.6 — Search Platform.** Evaluate Meilisearch · Typesense · OpenSearch · Postgres FTS · hybrid (feeds Phase-2 search 2.14). - **Epic 2.5.7 — Notification Platform.** Evaluate Slack · email · future Teams/Discord/SMS/push — delivery providers, SDKs, retry, templates, operational ownership (feeds the 3.1 Slack + email + notification-router frameworks). - **Epic 2.5.8 — Reporting Platform.** Evaluate tech for weekly/monthly/quarterly/annual reports, executive dashboards, PDF generation, email delivery, chart generation, historical reporting (feeds Phase-2 reporting 2.15). - **Epic 2.5.9 — Storage Architecture.** Evaluate Cloudflare R2 · Backblaze B2 · Wasabi · local · Dolt · PostgreSQL · Redis; assign each a responsibility; document backup, DR, and lifecycle (feeds the off-site-backup decision, roadmap Epic 1.1). - **Epic 2.5.10 — AI Agent Platform.** Evaluate OpenAI Agents SDK · LangGraph · CrewAI · AutoGen · Mastra · native orchestration; document where AI agents belong in Mission Control (feeds Phase-3 agent management 3.4). *(Note: Google ADK appears in Jeremy's list; flag it against the standing no-GCP constraint during evaluation.)* - **Epic 2.5.11 — Portal Framework.** Evaluate Next.js · React · shadcn/ui · Tailwind · component libraries · state management · charting · auth integration · admin framework (feeds Phase-3 portal 3.0/3.7). - **Epic 2.5.12 — Open Source Governance / OSBOM [foundational].** For every adopted dependency: upstream repo, fork/mirror, license, version, owner, adoption reason, security-advisory feed, releases monitoring, Dependabot/Renovate policy, upgrade cadence, monthly/quarterly/annual review, compatibility matrix, rollback + replacement strategy, sunset criteria. **Produces the authoritative Mission Control OSBOM** (implements roadmap Epic 1.10 + governance 050). ## 6. Phase 3 — the full portal (vertical-slice-first as method, full surface as destination) **Glory build (Jeremy, 2026-07-11):** the destination is the **complete authenticated RBAC portal** — every surface in the ADR-000 end-state. The audit's "one vertical slice first" is kept as the **build *method*** (prove the pattern end-to-end before fanning out, so the fan-out rides a proven spine) — **not** as a scope cap. The deferred-behind-demand items below are **un-deferred and committed.** Read/embed surfaces still ride Grafana where Grafana is genuinely the better tool (that's leverage, not a shortcut); bespoke build is reserved for write + orchestration surfaces. > **Phase-2.5 gate (binding on every Phase-3 epic).** No Phase-3 epic makes a technology decision. > Each **references the ADR** produced in Phase 2.5 for every technology it uses, and may **not > hard-code** a technology not selected there: identity/auth → 2.5.2/2.5.3, workflow/automation → > 2.5.4, event bus → 2.5.5, search → 2.5.6, notifications → 2.5.7, reporting → 2.5.8, storage → > 2.5.9, AI agents → 2.5.10, portal framework → 2.5.11, and every dependency is entered in the > 2.5.12 OSBOM. A Phase-3 epic that needs a technology with no Phase-2.5 ADR is **blocked** until > that evaluation is done. - **Epic 3.0 — Portal design system (Jeremy's 2.12, relocated here):** layout, navigation, component library, accessibility, responsiveness, color system, notification UX — built as the first portal work so screen one is consistent, **not a phase ahead of any UI**. Precedes 3.1. - **Epic 3.1 — The incident vertical slice (the MVP):** schema (2.13) → **first capability API built on the 2.6 contract** → auth (2.4) → UI (3.0), built end-to-end. This is the portal's first user story, and the first real consumer that any capability API is written against. - **Epic 3.2 — Action Security Model:** the portal **enqueues** actions the existing force-command paths execute — never standing shell creds; every action append-only audited (the 1.4 action-audit schema). Deploy/kill/rollback are designed here or not at all. - **Epic 3.3 — Read surfaces on Grafana:** dashboards/health/metrics as Grafana datasource + panel config, not bespoke code. - **Epic 3.4 — AI-agent management:** agents modeled as a **subtype of the automations registry** (not a parallel system); wrap RemoteTrigger; data model first, control verbs second. - **Epic 3.5 — Service catalog:** the portal surface over the 2.9 service registry, keyed on the canonical Service entity — owner, health, deps, runbook, SLO per service. - **Epic 3.6 — Full RBAC role model [committed, un-deferred].** The complete role hierarchy from the ADR-000 end-state — Executive Leadership → On-Call Engineer → scoped Contractor and the roles between — not the 3-role Phase-2 floor. Every surface authorizes against it. *Acceptance: each portal capability enforces role-scoped access; roles map to the 2.13 Role/Permission model.* - **Epic 3.7 — Horizontal portal fan-out [committed].** Once 3.1 proves the vertical-slice pattern, fan out the remaining surfaces on it — infra/environment status, monitoring, alerts, backup + restore-verification, DR readiness, security posture, deployments, AI-agent management, repo health, CI/CD, service catalog, runbooks, architecture, change management, operational metrics, audit history. *Each surface is a client of a 2.6 API. Acceptance: the ADR-000 surface list is live in the portal.* - **Epic 3.8 — Executive + cost dashboards [committed, real build].** Not the YAML ledger rendered as-is — a real cost + executive-metrics surface over the data model and the 2.15 reporting engine. *Acceptance: leadership reads operational + cost health from a live dashboard.* - **Epic 3.9 — Compliance + audit surface [committed].** Stood up proactively — audit-history browse, change-management records, the append-only action log (3.2) as a queryable compliance view — rather than waiting for a named external obligation. *Acceptance: any privileged action is reconstructable from the portal's audit surface.* ## 6b. Phase X — Continuous Improvement (the standing operational phase) > **What this is (Jeremy, 2026-07-11).** Not an implementation phase — the **standing phase that > begins after Phase 3 and never ends.** It acknowledges that Mission Control is a long-lived > operational platform, not a project with a finish line. Phase X is where the governance > cadence (`050`) actually lives once the platform is built: it *owns* the recurring reviews > rather than each being a one-off. It has no "done" — it has a rhythm. Phase X owns, on the cadence defined in `050`: - Quarterly architecture reviews (is the layering `046` still true?). - Annual roadmap refreshes (this document is re-checked against reality, superseded sections marked). - Dependency modernization + the CVE/EOL pipeline (`037` Epic 1.10 becomes a standing cadence). - Technical-debt and operational-debt reduction (the `043` trend KPIs drive it). - Platform performance optimization and cost optimization. - Security-posture reviews (quarterly, `050`). - Disaster-recovery exercises (quarterly game-day, `037` Epic 1.3 becomes recurring). - AI-assisted codebase audits and documentation-quality audits. - Mission Control **maturity assessments** (the platform-maturity score, `043`, tracked over time). *Acceptance (ongoing, not one-time): each item runs on its `050` cadence with an owner and a logged output; a cycle that produces nothing is either working — say so — or being skipped — fix it. Phase X's health is itself a KPI.* ## 7. Cross-cutting tracks (every phase) - **Brain ingestion + disclosure filter** (`spine-c67`, Gap 2/3 of `002-AA-AUDR`): the capture→propose→review bridge and the **code-enforced** no-comp/no-PII filter at ingest, reusing `ci/disclosure-gate.sh` server-side. Its own epic, scheduled with Phase 1–2. - **Teaching-tool packaging** with the incident/runbook-class exception from `039` (operational docs get a one-line purpose header, not a teaching preamble). - **Documentation law** (`039`, tiered): full 9-section AAR for phase-closes/incident-bearing epics; the lightweight lane (What/Why/Verification/Rollback/Next) for routine epics; the action-audit + RPO/RTO fields required. ## 8. Dependency order and the critical path 1.0 (dev-box hardening) and 1.1 (off-site+immutable) ship first, as hotfixes. 1.2 (Ansible) and 1.4 (schemas, Service entity FIRST) start in parallel. 1.3 (DR game-day) needs 1.1 + 1.2 + key escrow. 1.5 (alert floor), 1.6 (deploy safety), 1.10 (CVE), 1.14 (SLI/RPO + metrics) are independent. 1.7 (merge) is gated J1 and sequenced after 1.0 + 1.1. **Phase 2 (glory build, DL-009 — all epics committed):** the data-model spine is 2.13 (producer-driven, needs 1.4) → 2.6 (API, needs 2.13 + 2.4) → {2.7 events, 2.9 registry, 2.10 automation, 2.14 search, 2.15 reporting}; 2.8 graph needs 2.9; 2.1/2.2 observability + 2.4 identity run alongside. **Phase 2.5 (NEW gate) sits between Phase 2 and Phase 3:** it needs Phase 2's foundation to evaluate against (you evaluate an event-bus engine knowing the 2.7 event model, an auth system knowing the 2.4 identity need), and **2.5.1 governance methodology is done first** because every other 2.5.x evaluation uses its scoring framework + ADR template; 2.5.12 OSBOM runs throughout. **Phase 3 now depends on Phase 2.5** — no Phase-3 epic starts until its technologies have an approved ADR (3.1 core → 2.5.2/2.5.3 auth, 2.5.4 workflow, 2.5.5 events, 2.5.7 notifications, 2.5.11 portal; 3.4 agents → 2.5.10; etc.) — plus 2.13 + 2.6 + 2.4 + 3.2 (action security). J5 (identity) is decided at Phase-1 exit, then *ratified against the 2.5.2 evaluation* before the portal consumes it. ## 9. Solo-operator capacity and ceremony (the reality check) The audit's blunt finding: 15 epics + 3 tracks planned as if a dedicated team existed, on a two-box, roughly-one-operator estate running four other company arms. Two responses, both adopted: 1. **Tiered ceremony** (`039` amendment): full AAR + executive package only for phase-closes and incident-bearing epics; a lightweight lane for routine epics. 2. **Per-epic sizing + a minimum Phase 1.** Each epic below carries a t-shirt size and a "needs-Jeremy vs agent-unattended" flag; the declared **minimum Phase 1** (the non-negotiable floor) is: Epic 1.0, 1.1, 1.3, 1.5 — dev-box hardening, off-site+immutable, DR game-day, and the alert floor. Everything else is valuable but deferrable if capacity is short. | Epic | Size | Autonomy | |---|---|---| | 1.0 dev-box hardening | S | needs Jeremy (SSH lockout risk) | | 1.1 off-site + immutable | M | needs Jeremy (J2) then agent | | 1.2 Ansible | L | agent, Jeremy reviews | | 1.3 DR game-day + DB dumps | L | needs Jeremy (J8/J9) then agent | | 1.4 schemas + Service entity | M | agent | | 1.4b incident process | S | agent | | 1.5 alert floor | S | agent | | 1.6 deploy safety | M | agent | | 1.7 runbook merge | M | needs Jeremy (J1/J1b) then agent | | 1.8 verify+document | L | agent | | 1.9 secrets evolution | M | needs Jeremy (J12) then agent | | 1.10 CVE/EOL/license | M | agent | | 1.11 bus-factor drill | S | needs [the CTO] | | 1.12 publish gate | S | agent (done in Phase 0) | | 1.13 SLI + RPO | S | needs Jeremy (J8) then agent | ## 9b. Capacity & the true bill (glory build — Jeremy, 2026-07-11) The full build is the decision. The CTO's job is not to re-argue it — it is to state, plainly, the three things glory **requires**, so "we build" is a commitment to the bill, not just the epic list. None of these is a reason not to build; each is a thing that must be true for the build to succeed instead of stall. 1. **Dedicated engineering capacity — glory needs people, not slack time.** ~14 Phase-2 epics + a full RBAC portal is a **multi-quarter dedicated program**, not a nights-and-weekends effort on top of four other company arms. This must be resourced one of two ways: (a) protected, scheduled engineering time from Jeremy + [the CTO] + agents, with the revenue opportunity cost accepted **on the record**; or (b) a hire/contractor whose time is *not* fungible with billable work. The single biggest risk to glory is not architecture — it is a full roadmap funded with spare capacity that spare capacity never materializes for. **Decision Jeremy owns:** which of (a)/(b), and the protected-time budget. *(Compensation/hiring terms are Jeremy-private — not this repo; this line only flags that the decision exists.)* 2. **Infrastructure headroom — the full stack needs its own box.** Prometheus + Grafana + Loki + Tempo + Alertmanager + the API platform + event bus + search + the portal do **not** fit comfortably in the VPS's 24 GiB beside the existing 36 prod containers. Glory build assumes a **dedicated Mission Control host** (or a materially larger VPS). This is a real, recurring infrastructure cost and a J4-successor sizing decision — do it deliberately at Phase-2 entry, not by discovering OOM in production. *(The dev box is out — it is dev-only and RAM-pressured; this is net-new infra.)* 3. **The Phase-1 floor still ships first — the one shortcut glory cannot take.** Building for glory does **not** mean building the event bus before the off-site immutable backup exists. The irreversible-loss protections and the hardening floor (Epics **1.0, 1.1, 1.3, 1.5**) precede **all** platform work, non-negotiable. Correct glory sequence: **harden (Phase 1 floor) → foundation (data model + API contract + identity + observability) → platform tier (events, registries, graph, search, reporting, plugins, tracing, logs) → full portal (Phase 3) → Phase X.** Chasing the portal before the estate is safe is the single sequencing mistake that turns an ambitious build into a fragile one. We build big **and** we build in order. **Bottom line:** the vision is fully committed. Its success is gated on (1) resourced capacity and (2) dedicated infra being decided at Phase-2 entry, and on (3) the hardening floor going first. Say yes to the bill, not just the blueprint. ## 10. What this roadmap refuses to do - No tool adoption without a capability owner and an ADR-000 §7 contract signature. - No OneUptime/Tempo/Restic re-litigation without new facts. - No schema without an enforcing consumer (the anti-drift rule applied to itself). - No portal UI before the API layer; no portal write-action without the Action Security Model. - No public feed entry that is not a sanitized executive summary through the default-deny gate. - No Phase 1–3 beads until Jeremy approves this roadmap (Phase-0 exit criterion) — **except** the two carved hotfixes (Epic 1.0, 1.1), which ship on their own gates. ============================================================================== ===== DOCUMENT 3 of 11: 038-AT-DECR — ADR-000: the Mission Control constitution ===== source: https://demos.intentsolutions.io/mission-control/reports/2026-07-11-adr-000-constitution.md ============================================================================== # 038-AT-DECR — ADR-000: the Mission Control constitution > **What this is and why it matters.** This is the founding architecture decision record > (ADR) for the Mission Control program — the document every future epic cites when it > justifies a design choice. It answers, once, the questions that would otherwise be > re-litigated in every phase: why Intent OS exists, what "platform-over-tools" means in > practice, what contract every future product signs up to, which architecture principles > are binding (not advisory), what the end-state looks like, and how this document itself > gets amended. Jeremy Longshore's four program-doctrine sections are preserved below as > standing articles, near-verbatim, so future epics can cite his words rather than a > paraphrase. If a proposed change contradicts this ADR, either the change is wrong or this > ADR must be amended first — silently doing both is forbidden. - **Status:** ADOPTED (Phase-0 deliverable; binding once the Phase-0 PR merges and Jeremy approves the revised roadmap) - **Decision-log pointer:** `decision-log/007-2026-07-10-adr-000-mission-control-constitution.md` - **Companion standard:** `039-DR-STND-epic-documentation-aar-and-reporting-standard.md` (bound by reference — its rules carry ADR-000 authority) - **Supersedes:** nothing; ADR-000 is the root --- ## 1. Why Intent OS exists Intent Solutions runs a real production estate — seven self-hosted application stacks on a single VPS, a dev box, ~138 registered scheduled automations, a governed knowledge base, a fleet of AI agents, and the tracking fabric that mirrors work across beads, GitHub, and Plane. Until now, the operational truth of that estate lived across two repos, several CLAUDE.md files, and drilled-but-scattered scripts. **Intent OS is the single place where the company's operations are organized and governed.** It began as the "home base" repo (doctrine, business plan, system map, decision log). This ADR promotes it to the **permanent Mission Control platform**: the authoritative operational control plane for every Intent Solutions product — infrastructure, deployments, monitoring, incidents, security operations, backups and disaster recovery, and governance. ## 2. The decision 1. **Intent OS is the operational control plane of record.** Operational capabilities, registries, standards, and program records live here (or are explicitly federated with a pointer from here — never duplicated without an owner). 2. **The program is multi-phase by design** (Phase 0 planning → later implementation phases), and each phase is governed by the standing articles in § 6. 3. **The end-state is a product, not a pile of scripts:** an authenticated internal web application — the company's Mission Control — described in § 5. 4. **The architecture principles in § 4 are binding.** A deliverable that violates them must either be reworked or carry an explicit, Jeremy-approved exception recorded in the decision log. ## 3. Platform-over-tools Open-source tools (monitoring agents, backup engines, dashboards, schedulers) are **implementation details behind one operational interface** — never the interface itself. - We adopt a tool because a platform capability needs it, not because the tool is good. Capability first, tool second. - Every capability must survive its tool being swapped. The stable thing is the **service interface and its data model**; the tool behind it is replaceable. - Consequence for evaluations (gap analysis, Phase-2 verdicts): "the tool is excellent" is not sufficient; the question is "which capability does it serve, what interface does it expose to the platform, and what does it cost the estate (RAM, attention, upgrade surface)?" ## 4. Binding architecture principles ### 4.1 API-first Every capability — backups, incidents, deployments, inventory, monitoring, AI agents — exposes a **stable internal service interface** (an API, a queryable data model, or at minimum a documented machine-readable artifact with a stable schema). The future dashboard is largely a UI layer over the existing platform, never a rewrite. In Jeremy's words (2026-07-10): *"design API-first. Every capability should expose a stable internal service interface so the future dashboard is largely a UI layer over the existing platform rather than a rewrite."* ### 4.2 Platform-before-UI Where practical, separate **business logic · automation · APIs · data storage · presentation**, so a future web interface can be added without significant architectural rework. No capability is "done" when it only works as a human-invoked script; it is done when its state is machine-readable by the future portal. ### 4.3 Avoid tight coupling to CLIs and individual components Avoid designing systems tightly coupled to command-line tools or individual infrastructure components. Think in terms of **reusable platform services with clearly defined APIs, data models, and presentation layers.** (Jeremy, 2026-07-10, near-verbatim.) ## 5. The end-state: the Mission Control portal The long-term objective (Jeremy, 2026-07-10, preserved near-verbatim): Intent OS evolves into the central operational Command Center — **an authenticated internal web application that serves as the primary operational interface for the company**, used by Intent Solutions personnel to monitor, manage, and govern the company's products, infrastructure, and AI systems. Every operational capability developed throughout this program is evaluated not only as infrastructure automation but **as a future feature of this internal platform**, including: infrastructure status, environment health, incident management, monitoring dashboards, alert management, backup status, restore verification, disaster-recovery readiness, security posture, deployment management, AI agent management, repository health, CI/CD status, service catalog, operational runbooks, architecture documentation, change management, operational metrics, executive dashboards, cost dashboards, audit history, and compliance reporting. A future phase introduces the authenticated portal with **role-based access control (RBAC)**, providing visibility appropriate to a user's responsibilities. Future roles include: Executive Leadership, Operations, Platform Engineering, Infrastructure Engineering, Security, AI Engineering, Product Engineering, Customer Support, Incident Commanders, On-Call Engineers, and Contractors (limited access). Every feature implemented today is evaluated for how it could eventually appear inside this application. ## 6. Standing articles (Jeremy Longshore, 2026-07-10 — preserved near-verbatim) These four articles are the program's doctrine. Future epics cite them by article number. ### Article I — Multi-Phase Program Awareness > This program is intentionally divided into multiple implementation phases. The current > phase represents only one portion of a much larger long-term architecture. Always assume > additional phases are coming. Do not optimize only for the current phase. Design every > decision so it naturally supports future expansion without requiring major architectural > rewrites. If a short-term implementation would create technical debt or make future > phases more difficult, recommend a better long-term approach instead. Every architectural > decision should consider the complete Mission Control vision. ### Article II — Forward Compatibility (the 12-question rubric) > When making recommendations, continuously ask: > > 1. Will this architecture scale to future phases? > 2. Will this require a rewrite later? > 3. Can this component become a reusable platform service? > 4. Can this eventually power the internal Mission Control dashboard? > 5. Does this support multiple environments? > 6. Does this support additional products? > 7. Does this support additional servers? > 8. Does this support additional AI agents? > 9. Does this support additional engineering teams? > 10. Does this support future automation? > 11. Does this support future APIs? > 12. Does this support future web interfaces? > > Prefer designs that may require slightly more effort today if they significantly reduce > future complexity. This checklist is the roadmap's **per-decision rubric**: every epic-level design choice in the program roadmap (`037-PP-PLAN`) records its answers to these twelve questions, or states in one line why the rubric doesn't apply. ### Article III — Phase Awareness > The current implementation phase is only one milestone in a much larger roadmap. Always > maintain awareness that additional phases will follow. Do not assume that functionality > omitted from the current phase has been forgotten. Instead, identify dependencies that > should be established now to make future implementation straightforward. If you discover > that a future phase should be partially enabled during the current phase (for example, by > defining interfaces, schemas, APIs, data models, extension points, or repository > structure), recommend doing so while keeping implementation appropriately scoped. When in > doubt, optimize for extensibility rather than expediency. Corollary (program rule): partial enablement is **explicit, never silent**. A phase that declines to pre-build an interface for a later phase says so in its AAR; a phase that pre-builds one names the future consumer. ### Article IV — Architectural Responsibility > Your responsibility is not simply to complete the current phase. Your responsibility is > to ensure that each completed phase becomes a stable foundation for every phase that > follows. Treat every architectural decision as if Intent OS will continue evolving for > many years and eventually become the central operational platform used across all Intent > Solutions products, infrastructure, services, and engineering teams. ### Article V — Standing Infrastructure Assumption (Jeremy Longshore, 2026-07-11) > **Binding on every future phase, epic, and technology decision. Change only with Jeremy's > explicit approval.** Design Mission Control around this operating model. > > **Production environment.** Intent Solutions maintains a dedicated production server capable > of self-hosting operational infrastructure. When evaluating technologies, always assume this > server is available to host supporting platform services. Do not default to SaaS because it is > easier — evaluate self-hosted, open-source alternatives first. > > **Sufficient-resources assumption.** Assume sufficient production resources to run supporting > infrastructure. Do **not** reject a high-quality open-source component merely because it uses, > say, an extra 500 MB of RAM if the production server has the capacity. Optimize first for > **maintainability, reliability, and long-term architecture**; resource optimization is driven > by *actual, measured* constraints, never assumed up front. If capacity ever becomes a > constraint, document it with measurements rather than pre-emptively minimizing every service. > > **Evaluation order — for every platform capability, in this order:** (1) an existing capability > already running in the Intent Solutions estate; (2) existing open-source software that can be > self-hosted; (3) lightweight commercial software with a self-hosted deployment option; (4) SaaS > only when it provides significant operational advantage outweighing vendor lock-in, recurring > cost, operational dependency, data-ownership, security, and loss of platform control. Every SaaS > recommendation must explicitly justify why it beats an appropriate self-hosted alternative. > > **Self-hosted-first principle.** Mission Control must be capable of operating independently of > third-party vendors whenever reasonably practical. Prefer technologies with: open-source > licensing, active communities, long-term sustainability, strong documentation, API-first > architecture, containerized deployment, health monitoring, and backup / upgrade / DR support. > > **Existing-infrastructure awareness.** Always assume the platform already includes: the > dedicated production server, the dedicated development server, Tailscale private networking, > GitHub, Cloudflare, Cloudflare R2, Slack, Dolt, Mission Control, Intent OS, the existing > monitoring stack, the existing backup platform, and the existing CI/CD pipelines. Integrate > with these **before** introducing new technologies. > > **Operational philosophy.** Mission Control is the company's long-term operational platform. > New open-source components become **managed platform services inside Mission Control**, not > isolated standalone tools, whenever practical. Every adopted dependency ships with a long-term > operational plan — installation automation, configuration management, health monitoring, backup, > upgrade, rollback, documentation, ownership, lifecycle management, and AAR requirements. **No > technology is introduced without a long-term operational plan.** ## 7. The integration contract Every future product, service, or capability that joins the estate signs up to: 1. **Registered:** its scheduled automations appear in `mission-control/automations.md` before the session that creates them ends (machine-enforced today). 2. **Observable:** it emits liveness (two-marker `.beat`/`.ok` protocol or equivalent) and routes failures through the notify spine — never a private alerting path. 3. **Recoverable:** its backup/restore story is written and drilled, and its rollback procedure exists before it carries production traffic. 4. **Deployable:** it deploys from `origin/main` via CI (never from a mutable working tree), with a smoke test and a rollback path. 5. **Tracked:** its work is beads-tracked and mirrored (bead ↔ GitHub ↔ Plane). 6. **Documented:** it complies with `039-DR-STND` (docs as first-class deliverable; AAR at epic close; executive package to the reports feed). 7. **Service-shaped (rising bar):** it exposes its state machine-readably per § 4.1 — new capabilities from Phase 1 onward must; existing capabilities are brought up to this bar per the roadmap, not all at once. 8. **Secret-safe:** secrets ride SOPS/age in-repo, never plaintext; and its documents obey the disclosure tiers (no compensation/PII anywhere; public surfaces get the public-tier scrub). ## 8. Relationship to doctrine-v1 `doctrine/doctrine-v1.md` governs **conduct** — values, standards, commitments, how the company behaves. ADR-000 governs **operations** — how the estate is built and run. They are siblings under the same roof: doctrine says who we are; ADR-000 says how the machines and programs are organized. Where they touch (disclosure tiers, no-PII-in-the-brain), doctrine wins on conduct and ADR-000 defers to it explicitly. ## 9. Amendment process - ADR-000 is amended by **appending a dated amendment section** (never by silent edit), landed via PR with Jeremy's approval, plus a decision-log entry. - An epic that needs an exception records it in the decision log with its scope and expiry; two exceptions to the same clause trigger a review of the clause itself. - Superseding this ADR entirely requires a successor ADR that names everything it inherits and everything it retires, per `039-DR-STND` § 1. ## 10. References - `037-PP-PLAN-mission-control-program-roadmap` — the revised program roadmap governed by this ADR - `039-DR-STND-epic-documentation-aar-and-reporting-standard` — the documentation law - `031-AA-AACR-estate-automation-remediation-program-2026-07-10` — the estate ground truth at ADR adoption - `003-DR-STND-intent-os-content-schema` + `/doc-filing` v4.4 — where documents live - Mission Control reports feed: `https://demos.intentsolutions.io/mission-control/` (public, scrubbed mirror of program records) ## 11. Alternatives considered (added per audit finding C25) An ADR records the roads not taken. The Phase-0 discovery and audit weighed these: - **Keep the estate as bash + cron + markdown, no platform ambition.** Rejected: it is operationally excellent but cannot become a queryable, authenticated control surface — the service-ability axis (`035` Part A) is where every capability scores low, and no amount of more-bash closes it. - **Adopt an off-the-shelf ops platform (OneUptime, a SaaS status/incident suite).** Rejected on evidence (`035` Part B): OneUptime is a 3–6+ GiB monolith whose two unique features cost ~0.15 GiB elsewhere; SaaS suites re-introduce the vendor lock-in and cost surface the estate just shed with the GCP exodus. - **Federate the VPS runbook and intent-os permanently (no merge).** Rejected for the docs (duplication across ≥4 places was found live-drifting) but **retained for the secrets file** (§ amendment 12, J1b) — the strongest architecture merges the prose and federates the crown jewels. - **Buy/build a heavyweight identity provider now (Keycloak/Authelia/Authentik).** Rejected (`040` C7/D3): the estate already runs per-user tokens + a write-gate + an actor-audit chain in production (the qmd/INTKB knowledge base). Reusing that pattern + Tailscale identity avoids two identity systems and two audit chains. ## 12. Consequences and accepted tradeoffs (added per audit finding C25) Adopting this constitution commits the estate to real, named downsides: - **Ceremony cost.** Documentation-as-first-class-deliverable and the AAR/executive-package discipline cost operator time. Mitigated by the tiered ceremony (`039` §7 amendment) — but the cost is real and accepted. - **Secrets co-location risk (if J1b resolves to full merge).** Merging the runbook's secrets into the agent-touched, public-feed-adjacent repo widens their blast radius. The panel's engineering recommendation is to federate; if Jeremy accepts the merge, the compensating controls (tighter CODEOWNERS, no secret ever reaching the public feed, agent read-scoping) must be recorded here as an exception. - **Single-host acceptance (pending J9).** Until a standby host is funded, the Contabo VPS is a single point of failure for all seven stacks; backups protect data, not uptime. This is an accepted tradeoff only once Jeremy files the decision (Article III forbids silent omission). ## 13. Amendment 2026-07-11 — corrections from the adversarial audit (`040`) 1. **Ninth integration-contract clause (§7).** Add: *"9. Supported — the capability declares its version, its support window, and a named patch owner."* Closes the dependency-lifecycle gap (`040` C12). 2. **RPO/RTO + last-drill-date join the §7 contract.** Every data-bearing capability states its recovery-point and recovery-time objectives and the date of its last restore drill (`040` C2/C3). 3. **Action-audit event schema is a contract requirement.** Any capability that performs privileged actions emits an append-only audit event (subject / action / resource / timestamp / actor-type / outcome); capture begins in Phase 1, not at portal build (`040` C19). 4. **The end-state role model biases to 3 real roles.** Article 5 keeps the 11-role list as illustrative prose; the *implemented* authorization model is 3 roles (admin/operator, on-call/member, scoped-read contractor) until a documented user-count trigger justifies more. Never encode 11 roles as a schema for a ~3-human estate (`040` C7). 5. **Watchtower's contract tension is resolved explicitly, never silently.** Watchtower auto-pulls unpinned images to three customer-facing stacks — in tension with §7.4 (deploy-with-smoke-and-rollback). It is either digest-pinned and gated, or granted a dated §9 exception; silent coexistence of the contract and its violation is forbidden (`040` C8). 6. **Article II's 12-question rubric is enforced in a followable form.** The rubric applies at the *epic* level, answered tersely (one line per applicable question, "n/a" allowed with a reason) — not as a heavyweight block on every decision. An unfollowed enforcement clause is worse than an honest lighter one; the roadmap (`037`) is the reference (`040` C15). 7. **"Never a rewrite" is conditional.** §4.1's promise that the portal is additive over platform services holds *iff* every schema has a validating consumer and an additive-only evolution rule (`040` C9). Schemas without enforcing consumers do not earn the guarantee. 8. **Federate-the-secrets is the panel's engineering recommendation on the merge** (§11); the final call is Jeremy's (J1b) and is recorded either way. ============================================================================== ===== DOCUMENT 4 of 11: 043-DR-STND — Mission Control success metrics and KPIs ===== source: https://demos.intentsolutions.io/mission-control/reports/2026-07-11-success-metrics-and-kpis.md ============================================================================== # 043-DR-STND — Mission Control success metrics and KPIs > **What this is and why it matters.** A roadmap says what will be built; this says **how we > know it worked.** It defines the key performance indicators (KPIs) for the Mission Control > platform — the numbers that tell leadership whether the estate is healthy and whether the > program is making the estate healthier over time. Each metric has a plain-English > definition, how it is measured, a target, and where it will come from once the service-shape > work (`037` Epic 1.4) exists. Until then, several are measured by hand; the metric exists now > so the data model is built to serve it, not retrofitted. This is also the seed list for the > future executive dashboard. - **Program:** Mission Control (constitution: `038-AT-DECR`) - **Status:** the KPI catalog; targets are the panel's proposal, subject to Jeremy's sign-off - **Feeds:** the executive dashboard (`037` Phase 3), the ADR-000 §7 integration contract, the AAR verification section (`039`) --- ## 1. How to read this Every metric has: a **definition** (what it counts), a **source** (where the number comes from — "manual" means no automated feed exists yet), a **target** (the value that counts as healthy), and a **cadence** (how often it is reviewed). Targets are deliberately modest for a solo-operator, single-VPS estate — they are honest floors, not aspirational FAANG numbers, and they ratchet up as the platform matures. ## 2. Reliability KPIs | KPI | Definition | Source | Target | Cadence | |---|---|---|---|---| | **Platform availability** | % of time each customer-facing domain serves a healthy response | uptime probes per stack (`037` Epic 1.13); Netdata | ≥ 99.5% / domain / month | monthly | | **Mean time to detect (MTTD)** | median minutes from a failure occurring to an alert firing | alert-history NDJSON (`037` Epic 1.4) vs incident open | ≤ 15 min (≤ 5 min for customer-facing down) | monthly | | **Mean time to recover (MTTR)** | median minutes from alert to service restored | incident record open→resolved timestamps | ≤ 60 min for a single-stack outage | monthly | | **Incident response time** | median minutes from alert to human acknowledgement | incident record open→ack | ≤ 30 min waking hours | monthly | ## 3. Backup and disaster-recovery KPIs | KPI | Definition | Source | Target | Cadence | |---|---|---|---|---| | **Backup success rate** | % of scheduled backup runs that complete and verify | borg/backup logs + health monitor (`037` Epic 1.1) | 100% (any miss pages) | weekly | | **Restore success rate** | % of restore drills that fully recover and pass an integrity/query check | monthly drill transcripts | 100% | monthly | | **Recovery-drill success %** | % of scheduled DR game-days that hit their RTO target | quarterly DR exercise (`037` Epic 1.3) | 100%, RTO within target | quarterly | | **Recovery point (RPO), per stack** | max data-age lost in a worst-case restore | per-stack backup frequency (`037` J8) | stated per stack; ≤ 24h default | quarterly | | **Recovery time (RTO)** | measured wall-clock to rebuild-from-nothing | DR game-day stopwatch | a stated, decreasing number | quarterly | ## 4. Delivery KPIs | KPI | Definition | Source | Target | Cadence | |---|---|---|---|---| | **Deployment success %** | % of deploys that pass smoke without manual intervention | deploy-workflow results | ≥ 95% | monthly | | **Rollback success %** | % of failed deploys that auto-revert cleanly | deploy wrapper (`037` Epic 1.6) | 100% | monthly | ## 5. Coverage KPIs (the platform's own maturity) | KPI | Definition | Source | Target | Cadence | |---|---|---|---|---| | **Documentation coverage** | % of live capabilities with a current operating doc + rollback note | doc audit vs capability list | 100% of production capabilities | quarterly | | **Automation coverage** | % of registered automations that are observed (liveness + failure alert) | automations registry vs liveness sweep | 100% | monthly | | **Service coverage** | % of estate services present in the canonical Service catalog | Service entity (`037` Epic 1.4) vs `docker ps` | 100% | monthly | ## 6. Trend KPIs (direction, not a single number) | KPI | Definition | Source | Target | Cadence | |---|---|---|---|---| | **Technical debt trend** | count of open technical-debt beads, weighted by severity, over time | beads labelled `tech-debt` | flat or falling | monthly | | **Operational debt trend** | count of open operational-gap beads (unobserved jobs, stale docs, manual toil) | beads labelled `ops-debt` | flat or falling | monthly | ## 6b. Composite scores (added 2026-07-11 — roadmap Epic 1.14) Three roll-up scores compress the tables above into single numbers leadership can track over time. Each is a weighted 0–100 computed from KPIs already defined here — they add no new data source, only a formula. They are computed by the metrics-collection epic (`037` Epic 1.14). | Score | Rolls up | Target | |---|---|---| | **Reliability score** | platform availability, MTTD, MTTR, deployment + rollback success, backup + restore success | ≥ 90 and rising | | **Documentation score** | documentation coverage, doc-freshness (no page past its SLA), % capabilities with a rollback note + AAR | ≥ 90 | | **Platform-maturity score** | service-ability coverage (how many capabilities expose an API/schema), automation + service coverage, % capabilities meeting the ADR-000 §7 contract | rising each quarter | The **platform-maturity score** is the program's headline number: it measures how far the estate has moved from "bash + cron + markers" to "service-shaped platform," and is the metric Phase X (continuous improvement) tracks as the maturity assessment. ## 7. The executive-dashboard metric set The future portal's leadership view renders, at minimum: platform availability (per domain and rolled up), the most recent backup + restore-drill status with dates, open incidents by severity, deployment success % this month, documentation/automation/service coverage, and the two debt trends. Every one of these is defined above, so the dashboard is a rendering of this catalog — not a new specification. ## 8. Governance - These KPIs are reviewed on their stated cadences per the governance calendar (`050`). - A KPI without a data source is a **Phase-1 signal**: build the source (usually a schema in `037` Epic 1.4) rather than dropping the metric. - Targets ratchet: when a target is met three review periods running, propose the next floor. - New capabilities add their KPI here as part of their ADR-000 §7 contract sign-up. ============================================================================== ===== DOCUMENT 5 of 11: 044-DR-STND — Definitions of Done: bead, epic, phase, program ===== source: https://demos.intentsolutions.io/mission-control/reports/2026-07-11-definitions-of-done.md ============================================================================== # 044-DR-STND — Definitions of Done: bead, epic, phase, program > **What this is and why it matters.** "Done" means different things at different altitudes, > and conflating them is how work looks finished when it isn't. A **bead** (one task) is done > when its change works and is documented. An **epic** (a cluster of beads delivering one > capability) is done when the capability is operable, recoverable, and has its after-action > report. A **phase** is done when its epics are done *and* leadership has signed off. The > **program** is done — years from now — when the platform reaches its end-state. This document > writes each level's checklist so a stranger can tell, objectively, whether something is > complete. It pairs with the per-epic acceptance tests in the roadmap (`037`) and the > documentation law (`039`). - **Program:** Mission Control (constitution: `038-AT-DECR`) - **Companion:** `039-DR-STND` (documentation/AAR standard), `037-PP-PLAN` (per-epic acceptance tests) --- ## 1. Definition of Done — a bead (one task) A bead is done when **all** are true: - [ ] The change works, verified by exercising it — not just "it should work." - [ ] Its acceptance criteria (if it has any) are met, with evidence linked (CI run, log, transcript) — "verified" without a link does not count. - [ ] Any doc the change touches is updated in the same change; stale docs are not left behind. - [ ] It passes the repo gates (disclosure, beads-validate, lint, secret scan). - [ ] It is closed via `bd-sync` with an evidence reason, mirroring to its GitHub/Plane issue. - [ ] If it created or changed a scheduled automation, the automations registry row exists. ## 2. Definition of Done — an epic (one capability) An epic is done when **all** are true: - [ ] Every child bead is done (§1) or explicitly deferred with a written reason and a bead. - [ ] The epic's roadmap **acceptance test** (`037`) passes, with the evidence linked. - [ ] The capability is **operable from its documentation** by someone who has not seen it: architecture/design doc, operating guide/runbook, install/upgrade/migration notes, rollback + recovery procedure, security considerations, known limitations (`039` §2). - [ ] It meets the ADR-000 §7 **integration contract**: registered, observable, recoverable, deployable, tracked, documented, service-shaped (for Phase-1-onward capabilities), secret-safe — and declares its version + patch owner + RPO/RTO where applicable. - [ ] Its **KPIs** (`043`) have a data source, or one is filed as a Phase-signal bead. - [ ] A **9-section AAR** is filed (full lane) or the lightweight lane is justified per `039` §7. - [ ] The GitHub cluster issue and Plane issue are settled via `bd-sync`. ## 3. Definition of Done — a phase A phase is done when **all** are true: - [ ] Every epic in the phase is done (§2), or deferred with written justification carried into the next phase's scope. - [ ] The phase's **exit checklist** (Phase 0's is `051`; later phases get their own) is fully ticked. - [ ] The **risk register** (`041`) and **risk heat map** (`045`) are reviewed and updated — risks retired, new risks added, owners current. - [ ] The roadmap (`037`) is updated to reflect what actually shipped vs planned (superseded sections marked, not deleted). - [ ] A **phase-close AAR** + the **10-part executive package** are filed and published to the reports feed (governance/planning layer; security detail held back). - [ ] **Executive (Jeremy) sign-off** is recorded in the decision log — a phase is not done on the engineer's say-so. ## 4. Definition of Done — the program The program is done when **all** are true (this is the far horizon, stated so it is not forgotten): - [ ] The end-state in ADR-000 §5 exists: an authenticated internal web application with role-based access control, over stable platform services — not a pile of scripts. - [ ] Every capability domain in the KPI catalog (`043`) is service-shaped, observed, and meets its target on its cadence. - [ ] Disaster recovery is proven, not asserted: an off-site immutable backup, a measured RTO within target, and a passing recovery drill on the standing quarterly cadence. - [ ] Zero tribal knowledge: any competent engineer or AI can operate, troubleshoot, and extend the estate from Intent OS alone (the documentation law's whole point). - [ ] The governance cadence (`050`) runs on its own rhythm without heroics, and the ADR log (`047`) is current. - [ ] The program can absorb a new product, server, environment, agent, or team member by following the integration contract — no rewrite required (ADR-000 Article IV). ## 5. Why the four are not identical A bead can be done while its epic is not (the capability isn't operable yet). An epic can be done while its phase is not (leadership hasn't signed off, or a sibling epic is open). A phase can be done while the program is decades from done. Keeping the levels distinct is what stops "all the tasks are closed" from being mistaken for "the platform is finished." ============================================================================== ===== DOCUMENT 6 of 11: 046-AT-ARCH — Repository and platform layering, and the repo-split decision criteria ===== source: https://demos.intentsolutions.io/mission-control/reports/2026-07-11-repository-and-platform-layering.md ============================================================================== # 046-AT-ARCH — Repository and platform layering, and the repo-split decision criteria > **What this is and why it matters.** Two things in one document, both about structure. First, > **one picture** of how Mission Control is layered — from the Intent OS repository at the top > down to the AI services at the bottom — so anyone can see how the pieces stack and which > layer a given concern belongs to. Second, a **decision rule for growth**: when a new thing > should become its own repository versus a service, a package, or just a module in what already > exists. Without that rule, a growing platform sprawls into dozens of repos nobody can hold in > their head. This is the anti-sprawl charter. - **Program:** Mission Control (constitution: `038-AT-DECR`) - **Companion:** `034-AA-AUDR` (the runbook-merge recommendation this generalizes), `037` (roadmap) --- ## 1. The layered stack (one picture) Each layer depends only on the layer below it; the portal and AI services sit on top of the platform, never beside it. This is the shape ADR-000's "platform-before-UI" principle produces. ```mermaid graph TD IOS["Intent OS — the repository and control plane of record"] OPS["Operations — deploy, backup, monitoring, incident, security procedures"] MC["Mission Control — the capability layer (each capability = a service)"] SCH["Schemas — the canonical data contracts (Service/Host/Environment, incident, alert, audit)"] RB["Runbooks — how a human or agent operates and recovers each capability"] AUTO["Automation — the scheduled jobs, sweeps, watchdogs, and deploy pipelines"] INFRA["Infrastructure — the VPS, the dev box, the tailnet, the containers, ingress"] PORTAL["Portal — the authenticated RBAC web application (a UI over the services)"] AI["AI Services — governed agents, the brain, LLM-assisted operations"] IOS --> OPS OPS --> MC MC --> SCH SCH --> RB RB --> AUTO AUTO --> INFRA PORTAL -.->|"reads the platform services, never bypasses them"| MC AI -.->|"governed actors that call platform services under the same contract"| MC ``` **What to notice.** The portal and AI services attach with dashed edges *into the capability layer* — they are consumers of the platform, not new foundations. Schemas sit directly under the capabilities because every capability exposes its state through a schema (the API-first principle). Infrastructure is at the bottom: everything above it is how we operate it, not what it is. ## 2. Where a concern belongs (which layer) | If the concern is… | it lives in the… | example | |---|---|---| | how the company is governed / the record of decisions | Intent OS repo (top) | ADR-000, this doc | | a procedure a person/agent follows to run or recover something | Runbooks | RESTORE, break-glass | | a scheduled job that runs unattended | Automation | liveness sweep, backup | | a data contract other things read/write | Schemas | the incident record | | a named capability with an interface | Mission Control | backups, incidents, deploys | | the machines and networks themselves | Infrastructure | the VPS, the tailnet | | a screen a human looks at | Portal | the executive dashboard | | an autonomous actor | AI Services | a governed agent | ## 3. The growth decision: repo vs service vs package vs module When something new needs a home, walk this in order and stop at the first "yes": 1. **A module** (a file/directory inside an existing repo or service) — the default. Choose it when the new thing shares the owner, release cadence, and deployment of its host, and is not independently reusable. *Most new work is a module. Bias here.* 2. **A package** (a versioned library, published or vendored) — choose it when the same code is needed by **two or more** independent consumers and benefits from its own version. A package is not a service; it has no runtime of its own. Example: a shared schema-validation library. 3. **A service** (its own runtime behind an interface, same repo or a new one) — choose it when the thing has an **independent lifecycle at runtime**: it scales, deploys, fails, or is secured separately from its neighbors, and exposes an API. Example: the read-only platform API, the incident service. 4. **A new repository** — the highest bar. Choose it **only** when at least two hold: - a **different access boundary** is required (e.g. secrets that must not co-locate with agent-read or public-adjacent content — the reason `034` federates the secrets file); - a **different owner or contributor set** with different permissions; - a **genuinely independent release cadence and CI** that would fight the host repo's gates; - it is a **shippable external product** (like the platform marketplace) with its own users. If none of those hold, it is a directory in Intent OS, not a repo. Repo count is a cost — every repo needs its own CI, governance, and mental model. ## 4. Applying the rule to today's estate - The VPS runbook **merges into Intent OS** (`034`) — same owner, same cadence, no independent access boundary for the *docs* → a subtree, not a separate repo. Its **secrets file stays federated** — a genuinely different access boundary → the one justified split. - The **schemas** (`037` Epic 1.4) are a directory (module) now; they become a **package** only if a second independent consumer needs them versioned. - The **portal** is a **service** (its own runtime) in Intent OS, not a new repo, until it needs a different contributor set. - The **platform marketplace** (`claude-code-plugins`) stays its **own repository** — a shipped external product with its own users and cadence. Correct by this rule. ## 5. Governance - Any proposal to create a new repository cites this document and states which of §3.4's conditions it meets; if none, it is not a repo. - The layering diagram is updated when a new layer or cross-layer edge appears — never let the picture drift from reality (the same discipline `033` applies to the infrastructure map). ============================================================================== ===== DOCUMENT 7 of 11: 047-DR-INDEX — Architecture decision log index ===== source: https://demos.intentsolutions.io/mission-control/reports/2026-07-11-architecture-decision-index.md ============================================================================== # 047-DR-INDEX — Architecture decision log index > **What this is and why it matters.** Decisions get made, superseded, and forgotten. This is > the **one index** of every architecture decision affecting Mission Control — what was decided, > whether it still stands, when, who owned it, and what replaced it if anything. A reader who > wants "the current rule on X" starts here and follows the pointer to the full record, rather > than reading every document hoping to find the latest word. It spans two decision systems this > repo already runs: the numbered **ADRs** in `000-docs/` (the `AT-DECR` records) and the > append-only **decision-log/** chronicle (the `D##` entries). - **Program:** Mission Control (constitution: `038-AT-DECR`) - **Convention:** a decision is **Accepted** (in force), **Superseded** (replaced — see the successor), or **Proposed** (awaiting sign-off). Superseded decisions are never deleted. --- ## 1. Mission Control ADRs (the `AT-DECR` records) | Decision | Record | Status | Date | Owner | Superseded by | |---|---|---|---|---|---| | ADR-000 — Intent OS is the Mission Control platform; platform-over-tools; API-first + platform-before-UI binding; the RBAC end-state; integration contract | `038-AT-DECR` | Accepted (binding on roadmap approval) | 2026-07-11 | Jeremy | — | | Intendants — proactive-agent platform naming, home, Slice-0 supersession | `030-AT-DECR` | Accepted | 2026-07-10 | ISEDC + CEO | — | | Unify the governed brain — one plugin, two modes | `014-AT-DECR` | Accepted | 2026-06 | Jeremy | — | | Signed-dogfood publication — gated | `023-AT-DECR` | Accepted | 2026-07-05 | Acting CTO | — | ## 2. Program decisions in the append-only chronicle (`decision-log/`) | Decision cluster | Record | Status | Date | |---|---|---|---| | ADR-000 adoption; ops-vs-conduct split; doc standard delivery-to-feed (D35–D38) | `decision-log/007` | Accepted | 2026-07-10 | | Mission-control cockpit — the estate cockpit lands (D31–D34) | `decision-log/006` | Accepted | 2026-07-01 | | Doc-filing disciplined nesting (D5-era) | `decision-log/005` | Accepted | 2026-06-19 | | Brain readiness + CRO kill | `decision-log/004` | Accepted | 2026-06-18 | | Foundation + notifications | `decision-log/003` | Accepted | 2026-06-13 | | Brain-build decisions | `decision-log/002` | Accepted | 2026-06-13 | | Session decisions (initial) | `decision-log/001` | Accepted | 2026-06-13 | ## 3. Decisions pending Jeremy (Proposed — the Phase-0 exit gate) These are recorded so they are not lost; they become Accepted entries when Jeremy rules. | Decision | Where argued | Status | Owner | |---|---|---|---| | Runbook merge (docs) + secrets federation | `034`, `037` J1/J1b | Proposed | Jeremy | | Off-site destination + immutability mechanism | `037` J2, `041` R1 | Proposed | Jeremy | | Per-stack RPO targets | `037` J8, `043` | Proposed | Jeremy | | Single-host acceptance vs standby | `037` J9, `041` R3 | Proposed | Jeremy | | Identity direction (reuse-INTKB + Tailscale) | `037` J5, `040` C7 | Proposed | Jeremy | | Watchtower pin-and-gate vs exception | `037` J7, `040` C8 | Proposed | Jeremy | | Dev-box SSH hardening | `037` J11, `041` R13 | Proposed | Jeremy | | Governance ceremony tiering | `037` J13, `039` §7 | Proposed | Jeremy | | Publish-the-feed posture | `037` J10, `040` C5 | Proposed (default-deny applied) | Jeremy | ## 4. Governance - Every new `AT-DECR` record or `decision-log/` entry adds a row here in the same change — an ADR that isn't indexed is an ADR that will be forgotten. - When a decision is superseded, set its status here and name the successor; do not delete the row (the history is the point). - This index is reviewed on the annual ADR-review cadence (`050`) to catch decisions that have quietly gone stale. ============================================================================== ===== DOCUMENT 8 of 11: 050-DR-STND — Program governance cadence and RACI ownership matrix ===== source: https://demos.intentsolutions.io/mission-control/reports/2026-07-11-governance-cadence-and-raci.md ============================================================================== # 050-DR-STND — Program governance cadence and RACI ownership matrix > **What this is and why it matters.** A platform stays healthy only if certain things happen on > a rhythm — backups get validated, dependencies get patched, the disaster-recovery drill > actually runs, the roadmap gets re-checked against reality. Left to "when someone remembers," > they rot (discovery caught the estate's own status pages nine days stale against a three-day > promise). This document is the **calendar** of recurring governance activities and the **RACI > ownership matrix** that says, for each one, who is Responsible, Accountable, Consulted, and > Informed. It is deliberately sized for a solo operator plus AI agents — light enough to > actually run. - **Program:** Mission Control (constitution: `038-AT-DECR`) - **Companions:** `043` (the KPIs these reviews check), `041`/`045` (risks), `039` (doc law) --- ## 1. The governance calendar Each activity names what happens, why, and where its output goes. "Agent-run" means an AI agent can execute it unattended and surface only exceptions; "Jeremy" means it needs his judgement. ### Weekly | Activity | Purpose | Runner | Output | |---|---|---|---| | Backup-success check | confirm every scheduled backup ran and verified | agent-run | exception → Slack; KPI `043` | | Automation-registry reconcile | catch orphaned/ghost automations (already automated) | agent-run | drift → two-strikes → bead | | Mission-control page regen | keep the generated status pages fresh (kills the stale-page failure) | agent-run | `pnpm mc` | | Roadmap glance | is in-flight work still on the critical path? | Jeremy (5 min) | re-order if needed | ### Monthly | Activity | Purpose | Runner | Output | |---|---|---|---| | Restore drill | prove data restores (not just that backups exist) | agent-run + review | transcript; KPI `043` | | Dependency / CVE review | scan the 36 images + deps; triage CVEs against the patch SLA | agent-run | patch beads; `037` Epic 1.10 | | KPI review | read the reliability/backup/delivery/coverage KPIs; note trends | Jeremy | debt-trend beads | | Documentation freshness | any capability whose doc drifted from reality? | agent-run | fix beads | ### Quarterly | Activity | Purpose | Runner | Output | |---|---|---|---| | **Disaster-recovery game-day** | rebuild-from-nothing, measure RTO | Jeremy + agent | RTO record; `037` Epic 1.3 | | Architecture review | is the layering (`046`) still true? new coupling/drift? | Jeremy | ADR or bead | | Risk-register + heat-map review | retire/add risks, refresh owners and review dates | Jeremy | `041`/`045` update | | Security review | secrets rotation status, access audit, attack-surface changes | Jeremy | security beads | | Bus-factor check | can a second person still recover the estate? | Jeremy + [the CTO] | `037` Epic 1.11 | ### Annual | Activity | Purpose | Runner | Output | |---|---|---|---| | ADR review | walk the ADR index (`047`); retire stale decisions | Jeremy | supersede records | | Glossary + non-goals review | keep the vocabulary and scope honest | Jeremy | amendments | | KPI-target ratchet | raise floors that have been met all year | Jeremy | `043` targets | | Governance-calendar review | is this cadence still right-sized? | Jeremy | amend this doc | ## 2. RACI ownership matrix **R**esponsible (does it) · **A**ccountable (owns the outcome, one per row) · **C**onsulted (input) · **I**nformed (kept in the loop). At today's scale the roles are Jeremy (principal), [the CTO] (CTO/DevOps), and the AI agents; the matrix scales to real roles as the team grows. | Area | Jeremy | [the CTO] | AI agents | Notes | |---|---|---|---|---| | Program direction / roadmap approval | A/R | C | I | the exit-gate authority | | Architecture decisions (ADRs) | A | R/C | C | Jeremy accountable, [the CTO] proposes | | Deploys | A | R | R | agents deploy under CI; [the CTO] owns prod | | Backups + DR | A | R | R | agents run drills; [the CTO] owns recovery | | Monitoring + incidents | A | R | R | agents detect + open incidents | | Security + secrets | A | R | I | Jeremy accountable for secret decisions | | Documentation + AARs | A | C | R | agents draft; Jeremy accountable for truth | | Dependency / CVE patching | A | R | R | agents scan + propose; [the CTO] applies | | Governance cadence execution | A | C | R | agents run the scheduled reviews | | Brain / knowledge governance | A | C | R | the no-comp/no-PII rule is Jeremy's line | | Infrastructure (hosts, tailnet, ingress) | A | R | I | [the CTO] owns the boxes | | Repositories | A | R | R | agents open PRs; [the CTO] owns merge posture | | Services (the running apps) | A | R | R | per-service owner assigned at ADR-000 §7 sign-up | | Runbooks | A | C | R | agents draft; [the CTO] validates operability | | Incident response | A | R | R | [the CTO] is incident commander; agents detect + open | | AI agents | A | C | R | Jeremy owns the governance line; agents self-report | **Per-capability ownership (roadmap Epic 1.18):** the rows above are the *area* owners; every **critical capability** additionally names one owner at its ADR-000 §7 contract sign-up (recorded in the service registry, `037` Epic 2.9). RACI is the default; **DACI** (Driver / Approver / Contributor / Informed) is used instead where a single *decider* matters more than a single *accountable* — e.g. an irreversible one-way-door decision. ## 3. Governance of the governance - Every recurring activity above becomes a scheduled automation as it is built; each gets its **automations registry row** before its session ends (the enforced rule), and its owner in this matrix. - A review that produces no output for two cycles is either working (say so) or being skipped (fix it) — silence is not success. - This document is itself on the annual "governance-calendar review" line — the cadence is allowed to change, but only deliberately. - **These recurring reviews are owned by Phase X — Continuous Improvement** (`037` §6b), the standing operational phase that begins after Phase 3. Until then, the cadence runs as soon as each item's implementing epic lands (roadmap Epic 1.17 wires them into scheduled jobs). ============================================================================== ===== DOCUMENT 9 of 11: 039-DR-STND — Epic documentation, AAR, and reporting standard ===== source: https://demos.intentsolutions.io/mission-control/reports/2026-07-11-documentation-aar-standard.md ============================================================================== # 039-DR-STND — Epic documentation, AAR, and reporting standard > **What this is and why it matters.** This document turns a working habit into program law: > at Intent Solutions, **documentation is a first-class deliverable — an implementation is not > complete until its documentation exists.** It codifies three things every epic and major > milestone must produce: (1) operating documentation another engineer can run the system > from, (2) a formal **after-action report (AAR)** in a fixed 9-section format, and (3) an > **executive reporting package** readable by technical leadership without opening the > codebase. It exists because operational knowledge that lives only in one person's head — or > one chat session's context — is a liability: it cannot be reviewed, handed off, audited, or > taught. This standard is bound into ADR-000 (the Mission Control constitution) and applies > to every phase of the Mission Control program, starting with Phase 0 itself. - **Status:** Standing standard (Phase-0 deliverable; ratified by inclusion in the Phase-0 PR) - **Applies to:** every epic, major milestone, and significant decision in the Mission Control program; recommended for all Intent Solutions repos - **Authority:** Jeremy Longshore's documentation doctrine (2026-07-10), codified here; bound by reference into `038-AT-DECR` (ADR-000) - **Filing:** all documents follow `/doc-filing` v4.4 (`NNN-CC-ABCD-description.md` in the repo's `000-docs/`, flat by default) --- ## 1. The rule **Implementation is not complete until its documentation exists.** "Done" for any epic, bead cluster, or significant decision includes the documentation listed below, written so that another engineer can **operate, troubleshoot, and extend the work without tribal knowledge**. Intent OS is the authoritative source of operational knowledge; a change that isn't documented there hasn't finished landing. Three corollaries: 1. **Docs stay synchronized with implementation.** A follow-up change updates its documents in the same PR, or the PR states explicitly why not (and files a bead). 2. **Superseded documents are explicitly marked** — a banner at the top naming the successor ("Superseded by `NNN-…` on YYYY-MM-DD"), never silently deleted or left ambiguous. 3. **Teaching-tool trait.** Every document opens with a plain-English "what this is and why it matters" paragraph and expands estate shorthand on first use. Documents double as teaching material for the education arm; write for a competent engineer who has never seen this estate. ## 2. What every epic must document Produce the subset that applies — but the decision to skip a row is made out loud (one line in the AAR's "Scope" section), never by omission: | Document | Contents | |---|---| | Architecture & design | what was built, how it fits the existing estate, interfaces exposed | | Operational guide / runbook | how to operate it day-to-day; playbooks for its failure modes | | Install / upgrade / migration | how to stand it up again from nothing; how to move versions | | Rollback & recovery | how to undo it; how to recover its data; validated, not theoretical | | Security considerations | secrets touched, access paths, attack surface added or removed | | Testing & validation results | what was verified and the evidence (linked runs/logs, not "verified") | | Known limitations | what it deliberately does not do | | Future improvements | deferred work, filed as beads and referenced by ID context, not bare IDs | ## 3. The AAR — 9-section template (mandatory at epic close) Every epic and major milestone ends with a formal AAR filed as `NNN-AA-AACR-…` per /doc-filing v4.4. The copy-pasteable canonical skeleton is `000-AA-TMPL-after-action-report.md` (flat root of `000-docs/`, per the v4.4 rule that `000-*` canonical files never nest) — /doc-filing names that file in its canonical tree but ships no content, so the intent-os copy is the canonical source. The nine sections, in order — none optional, "n/a" must be argued: ```markdown # NNN-AA-AACR — after-action report > Plain-English opening: what this epic was and why it mattered. ## 1. Summary and business value What shipped, in two paragraphs. What the company can now do that it could not before. ## 2. Scope — planned, completed, deferred The original scope; what actually completed; what was deferred and WHERE it went (bead/issue references). Explicitly list documentation rows skipped per §2 and why. ## 3. Architecture and tradeoffs What was built and the shape it took. Every real alternative considered and why it lost ("chose X over Y because Z"). Interfaces/schemas exposed for future phases. ## 4. Verification evidence What was tested/drilled and the LINKED evidence — CI runs, drill transcripts, logs, before/after measurements. "Verified" without a link does not count. ## 5. Issues and root causes What went wrong during the work, each traced to a root cause — not the proximate symptom. ## 6. Lessons learned What we'd do differently; which of these became standing rules (and where they now live). ## 7. Operational impact, including cost New/changed automations (with their automations.md registry rows), RAM/disk/runtime footprint, money cost delta, on-call/attention burden delta. ## 8. Rollback procedure and validation How to undo this epic's changes, and the evidence the rollback path was actually exercised or why exercising it is impractical. ## 9. Next steps The recommended follow-on work, dependency-ordered, each with its bead/issue reference. ``` ## 4. The executive reporting package (mandatory at epic close) Every epic/milestone also produces an **executive package** — professional Markdown readable by technical leadership without inspecting the codebase. Ten parts: 1. Executive summary (one page: what, why, outcome) 2. Technical summary (what changed, at the architecture level) 3. Architecture updates (diagrams or deltas, if any) 4. Progress versus roadmap (where the program now stands) 5. Risks (new, changed, retired) 6. Blockers (what is stuck and on whom) 7. Decisions (made this epic; open and waiting, with the owner named) 8. Verification results (the evidence roll-up) 9. The AAR (linked, or inlined if short) 10. Recommended next steps **Delivery (amended 2026-07-10 by Jeremy; hardened 2026-07-11 after the adversarial audit):** the package is **published to the Mission Control reports feed** at `https://demos.intentsolutions.io/mission-control/` — an append-on-top, newest-first documentation feed whose entries are plain markdown, fetchable by third-party LLMs. It is **not emailed** (the original doctrine said email; the feed supersedes it). **The publish gate is default-deny (this is a security control, not a courtesy scrub).** The adversarial audit (`040-AA-AUDR`, finding C5) established that a "scrubbed but complete" operational document is reconnaissance: a public, LLM-crawlable SPOF map, dependency graph, deploy topology, or threat model hands an attacker the estate. Therefore: - **What may be published is an allowlist, not a blocklist.** Only a *separately authored, sanitized executive summary* goes to the public feed. The full discovery documents (SPOF analysis, dependency graphs, deploy internals, infrastructure topology, risk register with live mitigations) stay in the private repo and are **never** published, even scrubbed. - **A hard-fail publish gate** rejects anything that is not an approved summary, and strips hostnames, public and tailnet IPs, secret names, credential paths, and any personal-device or individual identifiers as a backstop — but the primary control is the allowlist, because a blocklist cannot anticipate every sensitive fact. - The authoritative unscrubbed versions stay in `intent-os/000-docs/`; the feed is a sanitized shop window, not a mirror. The feed directory's README carries the procedure. - **Alternative Jeremy may choose (J10):** gate the entire feed behind the tailnet / the future RBAC portal, in which case full documents may be served to authenticated readers and the allowlist relaxes. Until he decides, the default-deny public posture holds. ## 5. Where documents live Per `/doc-filing` v4.4 and this repo's content schema (`003-DR-STND`): - **Dated records** (AARs, audits, plans, decision records, this standard) → `000-docs/`, flat, next free `NNN`. - **Living documents** (runbooks, system maps, registries) → the named topical directory that owns them (`mission-control/`, `system-map/`, or the VPS runbook while it remains a separate repo). - **Decisions** additionally get a `decision-log/` pointer entry (append-only, blessed `NNN-YYYY-MM-DD` scheme). - Any new scheduled automation gets its row in `mission-control/automations.md` **before the session ends** (machine-enforced by the weekly reconcile + drift-check section E). ## 6. Compliance - The PR closing an epic's last bead links the AAR and the executive package; reviewers treat a missing AAR exactly like a failing CI gate. - Phase 0 of the Mission Control program is the first epic bound by this standard; its deliverables (`032`–`041`) and feed publication are the reference implementation. - This standard is amended the same way ADR-000 is amended (see `038-AT-DECR` § amendment process): by a dated superseding section, never by silent edit. ## 7. Amendment 2026-07-11 — corrections from the adversarial audit (`040`) The 10-agent audit produced six corrections to this standard; the default-deny publish rewrite (§4) is the largest and already applied above. The rest: 1. **RPO/RTO/DR-drill clause in the AAR template.** Section 8 (rollback) and a new line in the operational-impact section must state the epic's effect on the estate's recovery-point and recovery-time objectives and cite the last relevant restore-drill date. Backups and DR are not "verified" without a measured RTO and a dated drill. (`040` C3.) 2. **Incident/runbook-class exception to the teaching-tool preamble.** Operational documents read during an incident — runbooks, playbooks, restore procedures — carry a **one-line purpose header**, not a teaching preamble. The teaching-tool trait (§1.3) applies to analysis, plans, and audits; it is a liability in a document someone reads at 02:00 while a stack is down. Author judges by class. (`040` C26.) 3. **Tiered ceremony (capacity control).** The full 9-section AAR + 10-part executive package is mandatory for **phase-closes and incident-bearing epics**. Routine epics use a **lightweight lane**: What · Why · Verification (with evidence) · Rollback · Next. This mirrors the estate's existing lightweight-vs-full PR lanes and prevents documentation-about- the-work from consuming the capacity to do the work on a solo-operator estate. (`040` C15.) 4. **Doc-freshness CI gate.** A blocking check fails when a generated page's snapshot date exceeds its declared SLA (the mission-control pages were 9 days stale against a 3-day SLA during discovery — the anti-drift program drifting on itself). The no-hook rule is amended to permit a scheduled `pnpm mc` regeneration or a CI freshness gate. (`040` C20.) 5. **A governed Estate Operator Day-1 runbook is required.** Onboarding knowledge that lives only in CLAUDE.md files (four of which sit outside intent-os and cannot be merged) becomes *referenced* from a single governed operator runbook, not canonical in scattered files. (`040` C26.) 6. **Every epic's AAR verification section targets its acceptance test.** Because the roadmap (`037`) now gives every epic a one-line measurable acceptance test, the AAR's §4 evidence is checked against that test — not against a prose goal. (`040` C11.) ============================================================================== ===== DOCUMENT 10 of 11: 048-DR-INDEX — Mission Control glossary ===== source: https://demos.intentsolutions.io/mission-control/reports/2026-07-11-glossary.md ============================================================================== # 048-DR-INDEX — Mission Control glossary > **What this is and why it matters.** A small document that becomes priceless later. When > several people and agents work on a platform for years, the same word quietly comes to mean > different things to different readers — and plans built on ambiguous terms drift. This defines > the load-bearing vocabulary of Mission Control once, so every other document and every future > contributor uses the words the same way. Terms are grouped, then listed A–Z within each group; > where a term is a formal data entity it points at the schema that defines it. - **Program:** Mission Control (constitution: `038-AT-DECR`) - **Rule:** if a document uses one of these terms in a different sense, the document is wrong, not the glossary — fix the document or amend the glossary here (never fork the meaning). --- ## Core platform terms - **Intent OS** — the private repository and the operational control plane of record for Intent Solutions. Both the code/docs home and, increasingly, the running platform. (ADR-000 §1.) - **Mission Control** — the platform Intent OS is becoming: the authoritative control plane for running every product, ending in an authenticated web application with role-based access. - **Platform service** — a capability exposed through a stable internal interface (an API or a queryable data model), such that the portal is a UI over it rather than a rewrite. The unit the whole program is organized around. (ADR-000 §4.1.) - **Capability** — a thing the platform can do (backups, incidents, deployments, monitoring, AI-agent management…). A capability is realized as one or more platform services. - **Schema** — a versioned data contract (a JSON Schema) defining the shape of a data entity other components read or write. The canonical anti-drift mechanism. (`037` Epic 1.4.) ## Estate / infrastructure terms - **Estate** — every piece of Intent Solutions infrastructure across every machine, taken together. - **Environment** — a named context a service runs in (Production, Development). A formal entity in the Service/Host/Environment schema. - **Host** — a machine in the estate (the production VPS, the dev box). A formal entity. - **Service** — a running application or component with an interface (a container, a systemd unit, an API). A formal entity keyed by a stable ID that everything else joins on. - **Stack** — one `docker compose` project: a group of containers making up one application. - **Tailnet** — the private Tailscale overlay network the hosts share; the normal path for cross-machine operations, separate from the public internet. ## Operations terms - **Automation** — a scheduled, unattended job (a cron entry, a systemd timer, a CI schedule): a sweep, a watchdog, a backup, a deploy pipeline. Tracked in the automations registry. - **Agent** — an autonomous or semi-autonomous actor (an AI agent / governed background agent, a scheduled Claude routine). An agent is a *governed actor* that calls platform services under the same integration contract as any other capability. A subtype of automation in the data model. - **Runbook** — a document telling a human or agent **how to operate** a capability day-to-day. - **Playbook** — a runbook for a **specific failure mode** (what to do when X breaks). - **Incident** — a formal record of a service disruption, with a lifecycle: open → acknowledge → resolve, plus a timeline. A data entity (`037` Epic 1.4b), distinct from a raw alert. - **Alert** — a single notification that something crossed a threshold. Many alerts may belong to one incident. Delivered through the notify spine. - **Recovery** — restoring a capability or its data after a failure. **Data recovery** (restore from backup) and **host recovery** (rebuild the machine) are distinct; disaster recovery (DR) needs both. - **Action** — a privileged operation the platform performs or enqueues (deploy, kill, rollback, secret-decrypt). Every action emits an append-only audit event. (ADR-000 amendment C19.) ## Program / governance terms - **Program** — the whole multi-phase effort to build Mission Control. - **Phase** — one milestone in the program (Phase 0 planning; Phases 1–3 implementation). A phase is a stable foundation for the next. (ADR-000 Article I.) - **Epic** — a cluster of related work delivering one capability; tracked as a parent bead + a GitHub cluster issue. - **Bead** — one tracked unit of work in the `bd` task system; the source-of-truth task record, mirrored to a GitHub issue and (when applicable) a Plane issue. - **ADR** — Architecture Decision Record: a durable record of a significant decision and why. ADR-000 is the program constitution; the ADR index is `047`. - **AAR** — After-Action Report: the mandatory 9-section record filed at every epic/phase close (`039`, template `000-AA-TMPL`). - **Integration contract** — the eight-plus clauses every capability signs up to (registered, observable, recoverable, deployable, tracked, documented, service-shaped, secret-safe, supported). ADR-000 §7. - **RPO / RTO** — Recovery Point Objective (max data age lost in a restore) / Recovery Time Objective (max time to restore). Stated per stack (`037` J8, `043`). - **MTTD / MTTR** — Mean Time To Detect / Mean Time To Recover. KPIs in `043`. - **The brain / governed knowledge base** — the Compile-Then-Govern knowledge system (governance engine plus search index) that compiles facts into audited memories queried with citations. - **Disclosure tiers** — the rule set governing what content may appear where (public / internal / private); no compensation or personal data anywhere in this repo or the brain. ## Governance rule New load-bearing terms are added here when they first appear in a deliverable; a term used in two senses is a defect to resolve, not a synonym to tolerate. ============================================================================== ===== DOCUMENT 11 of 11: 049-DR-STND — Mission Control non-goals (what it will NOT do) ===== source: https://demos.intentsolutions.io/mission-control/reports/2026-07-11-non-goals.md ============================================================================== # 049-DR-STND — Mission Control non-goals (what it will NOT do) > **What this is and why it matters.** A scope is defined as much by what it excludes as by what > it includes. This one page lists what Mission Control **intentionally will not do** — so that > when someone (a person or an agent) proposes one of these, the answer is a documented "no," > not a fresh debate. Non-goals keep a multi-year platform from sprawling into everything. > Anything here can be revisited, but only by amending this document with a reason — never by > quietly building it. - **Program:** Mission Control (constitution: `038-AT-DECR`) - **Companion:** `046` (repo/service growth criteria), `037` §10 (what the roadmap refuses) --- ## Non-goals 1. **Not a public or multi-tenant product.** Mission Control is Intent Solutions' internal control plane. It is not sold, not offered to other companies, not multi-tenant. (The platform *marketplace* is a separate, external product — a different repo, different users.) 2. **Not a replacement for the tools it governs.** It does not reimplement monitoring, backup, CI, or a database. It orchestrates and exposes best-of-breed tools behind one interface; tools stay swappable implementation details. (ADR-000 §3.) 3. **Not a home for compensation, pay, comp-splits, equity, or personal data.** Ever. These are Jeremy-private or excluded entirely; the disclosure gate enforces it. This is a hard, permanent non-goal. 4. **Not a public exposure of operational internals.** The estate's topology, single-point-of- failure analysis, dependency graph, and risk register are not published. Only sanitized governance/planning documents go to any public surface. 5. **Not a heavyweight, ceremony-for-its-own-sake bureaucracy.** Governance is tiered to the estate's real size (a solo operator plus AI agents). It will not adopt process that costs more than the risk it mitigates. (`039` §7 tiered ceremony.) 6. **Not an always-on, highly-available, multi-region system — yet.** Until a standby host is funded (a Jeremy decision, `037` J9), the platform accepts single-host risk explicitly. Backups protect data, not uptime. HA is a future possibility, not a current promise. 7. **Not a general-purpose developer platform or PaaS.** It manages *this* estate's operations. It is not a place to run arbitrary workloads or a self-service deployment product. 8. **Not an unbounded observability sink.** It will not collect telemetry it has no consumer for (no traces while nothing emits them; no logs without a retention policy). Tools follow observed need, not fashion. (`035` Tempo/Loki verdicts.) 9. **Not a standing privileged robot.** AI agents and the future portal do not hold standing shell credentials on production. Privileged actions are enqueued and executed through the existing force-command paths, append-only audited. (ADR-000 action-audit amendment.) 10. **Not a rewrite of what already works.** The estate's fire-drilled bash-and-cron fabric is hardened and service-wrapped, not thrown away. The program adds interfaces over working capabilities; it does not replace them to feel modern. 11. **Not GCP, and not returning to it.** No `gcloud`, BigQuery, Vertex, Firebase, or Cloud Run. The estate exited GCP; that door is closed. ## Governance A proposal that matches a non-goal is declined by pointing here. To pursue one anyway, amend this document (dated, with a reason, Jeremy's sign-off) — the same discipline as an ADR-000 exception. Silent scope creep past a written non-goal is forbidden. ============================================================================== ===== END OF BUNDLE ==============================================================================