Skip to content

Scenario atlas: system map

Argus as a set of annotated flowcharts, one page per real control-flow scenario (ADR 0003, ARGUS-632). Each page below is a diffable Mermaid diagram plus per-node annotations naming the exact file and function that implements each step -- when an agent changes a flow, it maintains the matching page in the same PR.

flowchart LR
    TL["Task lifecycle\n(filed to verified)"]
    DC["Dispatch, claim-lease\nand heartbeats"]
    LQ["Landing queue"]
    AR["Agent runs and\nskills registry"]
    MP["Memory pipeline"]
    NA["Native alert pipeline"]
    NF["Notification/push\nfan-out"]
    DO["App deploy /\nOTA path"]

    TL -->|"ready\ntask"| DC
    DC -->|"skill executes"| AR
    TL -->|"PR opened"| LQ
    LQ -->|"AttachPREvidence\n+ VerifySweep"| TL
    LQ -->|"CI-red /\npost-merge-break"| NA
    LQ -->|"deploy-hook enqueue"| DO
    DO -->|"deploy_fail /\nOTA update"| NF
    NA -->|"push after\nrouting decision"| NF
    AR -.->|"skill invocation\nmid-run"| AR
    MP -.->|"capture from every\nrun and chat turn"| MP

The system map above shows only the cross-scenario edges; each linked page has its own detailed diagram of the scenario's internal flow.

Pages

Scenario What it covers
Task lifecycle Filed -> backlog -> ready -> in_progress -> (blocked/cancelled) -> verified/done, and the deterministic-checker rule that only evidence can set verified.
Dispatch, claim-lease and heartbeats How a ready task becomes a claimed, heartbeating agent_runs row, and the two independent watchdogs (ReapStale, ClaimLeaseSweeper) that recover a stuck one.
Landing queue Rebase -> migration-renumber -> CI -> merge -> evidence, the queue's failure-surfacing, and the separate post-merge-break net.
Native alert pipeline Signal builders -> the pure AlertEngine (dedup/escalate/debounce/storm) -> severity-routed push -> human ack/dismiss or auto-resolve.
Memory pipeline Capture -> segment -> distill (gated) -> embed -> dedup -> two independent recall paths -> effectiveness grading (observational, not auto-tuning).
Agent runs and skills registry How the skills registry is populated and gated, backend selection (Claude vs Codex), budget gates, completion cross-checks, and cross-backend failover.
App deploy and OTA path Two distinct mechanisms: container deploy-on-land (gates task verification on a health check) and iOS/mac OTA distribution (capability-token-gated itms-services install).
Notification/push fan-out The shared fanOut/APNs delivery mechanism every other page's pushes ultimately go through, plus Telegram/app-transport channel selection and coalescing sweeps.

How these pages stay accurate

Every fenced ```mermaid block on this site is compiled by the strict docs CI gate (ARGUS-630) -- a diagram that stops parsing fails the PR, the same as a broken internal link. There is no separate "keep the diagrams in sync" step: the diagram and its annotations live in the same Markdown file as the code they describe is reviewed alongside, so a PR that changes a flow is the natural place to update its page.

Accuracy spot-check (ARGUS-632)

Each diagram above was produced by tracing the actual code (not the design docs) for its scenario, then cross-checked against the relevant existing doc where one exists (docs/runbook/landing-runbook.md, docs/reference/MEMORY-PIPELINE.md). Findings recorded against this task:

  • Landing queue: the acceptance text's "renumber" step is real but is a migration-filename collision fixup (renumberMigrations, post-rebase, pre-CI) -- not a task-renumbering step, and unrelated to supersession.go despite the similar name. The landing queue page documents the real sequence.
  • Landing runbook (docs/runbook/landing-runbook.md): its four failed: reason strings match the code's exact detail strings verbatim -- no drift found there.
  • Memory pipeline: docs/reference/MEMORY-PIPELINE.md's constants table says promptHookMaxNotes = 5; code has raised this to 12 (prompt_hook.go, ARGUS-37/75). Recorded as stale in the memory pipeline page rather than silently corrected, since fixing the reference doc is separate scope.
  • Native alert pipeline: confirmed as a genuine first-class subsystem (alert_detectors.go / alert_engine.go / alert_store.go / notification_router.go) matching docs/explanation/REQUIREMENTS.md US-11/US-36 almost exactly, distinct from the legacy Grafana-relay path it is superseding.
  • App deploy / OTA: confirmed as two unrelated, both-real mechanisms (container deploy-on-land vs iOS/mac OTA distribution) rather than one concept under two names; no Komodo reference exists anywhere in this repo for either path.
  • Every other page's node list was verified against the named file:function by direct code read during construction of this atlas, not inferred from naming alone.