diff --git a/backlog/012-archive-the-briefing-product.md b/backlog/012-archive-the-briefing-product.md new file mode 100644 index 0000000..3b19871 --- /dev/null +++ b/backlog/012-archive-the-briefing-product.md @@ -0,0 +1,43 @@ +# Delete the briefing product -- beats, questions, predictions, frames, synthesis, rendering -- porting only five modules whose mechanics the new tiers need. +REPO: InsightWeaver +STATUS: QUEUED # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED +SIZE: large +ACCEPTANCE: `make check` passes, plus: roughly 8,900 lines of source are **deleted, not archived** -- `src/render/`, `src/prompts/`, `src/config/beats.py`, the beat/question/prediction/standing-agenda/institutional-activity/frame/synthesis modules in `src/context/`, and every CLI command except what the new pipeline needs; their tests are deleted with them; **`src/render/email.py`'s `smtplib` send path goes with the rest**, closing the standing violation of invariant 1; the five modules named below are **moved and kept**, with their tests, because the new tiers need their mechanics; a migration drops the tables belonging to deleted concepts; `insightweaver --help` lists only surviving commands; and the deletion lands as **one commit** with a message naming what went and why, so `git log` is the record rather than an `archive/` directory. +OUT OF SCOPE: An `archive/` directory. Superseded on 2026-08-31: the operator's call is that git history is the rollback path and a directory of dead code in the tree is a liability, not documentation. Deleting `src/sources/`, `SOURCES.md`, `src/database/connection.py`, `src/config/feed_matcher.py`, `src/config/settings.py`, `src/rss/`, or the five ported modules. Building any part of the new pipeline. Dropping the `articles` table -- that is task 014's decision. +LANDMINES: **Five modules encode findings that cost real debugging and must be ported, not rewritten.** `src/context/entity_matcher.py` (168) carries word-boundary matching: across the live corpus, 5,364 titles contain the substring `nist` and 73 match at a word boundary, and its boundary test was found to pass with the anchors deleted from the codebase because case-sensitivity rejected the collisions first -- a rewrite reintroduces both. `src/context/claude_client.py` (212) carries the retired-model outage of 2026-06-15 and the `ThinkingBlock` parsing failure, each of which cost a live run. `src/context/coverage_probe.py` (488) is a "did anything match this in N days" engine, which is what task 018's staleness check is. `src/utils/cadence.py` (117) is interval parsing for task 013. `src/processors/deduplicator.py` (433) is an explicit keep. **Do not delete a module because its concept died if its mechanics are load-bearing downstream** -- name each ported module in the PR with the task that needs it. **The database still holds 55,249 articles, 46 questions, 33 predictions and 42 frames**; dropping tables is destructive and irreversible against that data, so back up before the migration and say in the PR that you did. `main` is protected -- open a PR. +--- +Rewritten 2026-08-31 after the operator's decision: beats and questions are removed, Position +replaces them, and the old code is deleted rather than archived because git already holds it. + +## What goes + +| area | lines | +|---|---| +| `src/context/` -- synthesis, topics, curation, frames, questions, predictions, standing agenda, beat scope, institutional activity, decision routing | ~3,900 | +| `src/cli/` -- brief, frames, diet, questions, predictions, forecast, decisions, beat, stake, scope | ~3,000 | +| `src/render/` -- terminal, markdown, html, email, document | 1,834 | +| `src/config/beats.py` | 665 | +| `src/prompts/` | 508 | + +Plus most of 844 tests. This is a deletion of roughly the whole product built to date. + +## What is ported, and why it is not sentiment + +Five modules whose concepts die and whose mechanics the new tiers need: + +- **`entity_matcher.py` -> Tier 1 routing.** Word boundaries are the difference between 73 and + 5,364 matches on one term in this corpus. Its test class was also found to pass with anchoring + removed, because shouted terms were rejected by case-sensitivity before the anchors ran. Both + findings are encoded here and a blank-file rewrite loses them. +- **`claude_client.py` -> Tier 2.** Encodes a retired model that failed silently for ten weeks and + a response-shape change that discarded a completed synthesis. +- **`coverage_probe.py` -> task 018.** A staleness check is "did anything match this in N days", + which is what this already is. +- **`cadence.py` -> task 013.** Interval parsing and next-review arithmetic. +- **`deduplicator.py` -> Tier 0.** Explicit keep in the brief. + +## Why one commit and no `archive/` + +A directory of dead code is read as current by every future reader and every agent, and it drags +the old product's shape forward -- which is the outcome the rewrite exists to avoid. `git log` is +the rollback path, and the commit message is where the reasoning lives. diff --git a/backlog/013-position-and-watch.md b/backlog/013-position-and-watch.md new file mode 100644 index 0000000..64a6ec5 --- /dev/null +++ b/backlog/013-position-and-watch.md @@ -0,0 +1,37 @@ +# Introduce Position and Watch as the system's atomic units, with so_what enforced in the schema. +REPO: InsightWeaver +STATUS: QUEUED # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED +SIZE: medium +ACCEPTANCE: `make check` passes, plus: `position.yaml` is loaded from git, hand-authored, and validated -- decisions carry a deadline, and a Position over two pages **warns loudly rather than failing**, naming the drift from stakes into interests; a `watches` table and loader exist carrying `id`, `claim`, `belief`, `so_what`, `triggers`, `expires`, `staleness_alert_days`; **a Watch with an empty, whitespace-only, or absent `so_what` is rejected at load with a clear error and is not stored**, with a test that bites; a Watch whose `so_what` names no decision present in the Position is rejected the same way; `belief` outside 0.0-1.0, an `expires` in the past, and a `staleness_alert_days` under 1 are each rejected; `insightweaver watch list` shows each watch, its belief, its decision, and days to expiry; and no command can create a Watch except from the checked-in files. +OUT OF SCOPE: Routing, adjudication, state transitions, alerts, or notification -- this task defines the units and nothing that acts on them. Migrating existing Questions, Predictions, Decisions or Beats onto the new model; that is task 014's decision to make once Observations exist. Any LLM call. Proposing candidate watches. A web or TUI editor for `position.yaml` -- it is human-edited in git, deliberately. +LANDMINES: **The system never authors its own watches (invariant 6), so every write path here must be closed, not merely unused.** A `watch add` CLI command would satisfy no acceptance criterion and would be the seam through which auto-generation later arrives; do not build one. **`so_what` enforcement must reject rather than default.** Task 011 established this pattern for a different field and its landmine applies verbatim: the ledger accumulated 25 unfalsifiable predictions precisely because a missing field was tolerated. **The existing schema already contains most of this and it is empty.** `decision_factors` has columns `name`, `what_would_update_me`, `current_state_note` -- which is a trigger, a belief state, and a decision link under different names -- and `decisions` and `decision_evidence` both hold **0 rows** as of 2026-08-31. Read `docs/CONCEPTS.md` ยง "Decisions, Factors, and Evidence" before designing a new table; if Watch is better expressed as an evolution of Decision+Factor than as a parallel structure, say so in the PR rather than building both. `main` is protected -- open a PR. +--- +Written 2026-08-31. + +## The finding the implementer needs before touching the schema + +The brief describes Watch as a new atomic unit. The audit found the repository already models +something very close, and never populated it: + +| brief's concept | existing column | rows | +|---|---|---| +| `so_what` naming a decision | `decision_evidence.decision_id` -> `decisions.name` | 0 | +| trigger | `decision_factors.what_would_update_me` | 0 | +| belief state | `decision_factors.current_state_note` | 0 | +| evidence direction | `decision_evidence.direction` | 0 | +| trigger predicate | `predictions.trigger_condition` | 33 rows, 25 unfalsifiable | + +That is not an argument for reusing the tables as they stand -- `current_state_note` is prose where +`belief` is a float, and the 33 predictions demonstrate what happens when a trigger field accepts +prose. It **is** an argument that the implementer should decide deliberately between evolving +Decision+Factor and creating Watch alongside it, and record the reasoning. Two overlapping models +for the same idea is the outcome to avoid; the repository already has that problem between +`README.md` and `CLAUDE.md` and this task should not add a third instance of it. + +## Why the Position size check warns rather than fails + +The brief says a Position over two pages "has drifted into describing interests rather than stakes; +flag that, do not silently accept it." A hard length limit would be enforcing a proxy: a +three-page Position full of genuine deadlines is better than a one-page Position of vague +interests. The check names the drift and lets the human judge, which is the same reason +`coverage_probes` reports INCONCLUSIVE rather than dropping a probe. diff --git a/backlog/014-observations-immutable-and-replayable.md b/backlog/014-observations-immutable-and-replayable.md new file mode 100644 index 0000000..9ab32cb --- /dev/null +++ b/backlog/014-observations-immutable-and-replayable.md @@ -0,0 +1,27 @@ +# Make Observations immutable and content-addressed, and Evidence derived, so the corpus can be replayed against a changed prompt and the diff inspected. +REPO: InsightWeaver +STATUS: QUEUED # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED +SIZE: medium +ACCEPTANCE: `make check` passes, plus: an `observations` table stores normalized adapter output keyed by content hash, with the raw payload retained verbatim and never mutated after write; a write attempting to change a stored observation **fails loudly** rather than updating; adapters in `src/sources/` emit Observations through one path; near-duplicate detection by MinHash groups items that differ only in boilerplate, with the threshold recorded in config and a test showing two real near-duplicates grouping and two distinct items not; an `evidence` table links (observation, watch) with direction and magnitude, and every row records the prompt version that produced it; `insightweaver replay --prompt-version X` rebuilds Evidence from Observations alone and **prints a diff against the stored Evidence without writing**, with `--commit` required to persist; and a test proves replay is deterministic given the same prompt version. +OUT OF SCOPE: The adjudication prompt itself and its content -- this task builds the replay harness, task 016 writes what runs inside it. Routing. State transitions. Deleting or migrating the 55,249 existing `articles` rows; decide whether Observations supersede, wrap, or coexist with that table and record the reasoning, but do not perform a destructive migration in this task. Any change to `SOURCES.md`'s recorded-basis rule. +LANDMINES: **This invariant is the one that makes a stochastic component testable, and it is worthless if replay is not byte-reproducible.** A prompt version that is not recorded per row, or an adapter that normalizes with a timestamp in the payload, silently breaks it -- and it breaks in the direction of looking fine. **`src/sources/base.py` already has `content_hash()` and `ARTICLE_FIELDS`** from task 005; extend that seam rather than introducing a second hashing scheme. **The `articles` table is 55,249 rows and is what every existing query reads**; a parallel `observations` table that only new adapters write leaves the system with two corpora and no rule for which is authoritative. State the rule in the PR. Content-addressing means the hash **is** the identity: an adapter that includes a fetch timestamp or a session ID in the hashed payload will store the same article repeatedly and the dedup will look broken when the hashing is what is wrong. Test that first. `main` is protected -- open a PR. +--- +Written 2026-08-31. + +Invariant 3 is the one that makes the LLM tier reviewable. Everything downstream of adjudication is +deterministic and unit-testable; adjudication itself is not, and the only way to test it is to hold +the inputs fixed and inspect what a prompt change does to the outputs. That requires Observations +to be immutable and Evidence to be a pure function of (Observations, prompt version). + +**Why `--commit` is required rather than default.** A replay that writes by default makes the +before-state unrecoverable at exactly the moment you wanted to compare against it. Printing the +diff and requiring an explicit commit costs one flag and preserves the thing the invariant exists +to provide. + +**The open question this task must answer, not assume.** The repository has 55,249 `articles` rows +written by the RSS path and the Federal Register adapter. Observations may supersede that table, +wrap it, or run alongside it during a transition. Each has a real cost -- superseding means a +migration of 55k rows, wrapping means two shapes for one concept, coexisting means a rule nobody +will remember in six months. The implementer picks and writes down why; what is not acceptable is +two corpora with no stated rule, because the audit found exactly that pattern already exists in +this repository between `migrations/` and `src/database/migrations/`. diff --git a/backlog/015-tier1-deterministic-routing.md b/backlog/015-tier1-deterministic-routing.md new file mode 100644 index 0000000..7e4a2f1 --- /dev/null +++ b/backlog/015-tier1-deterministic-routing.md @@ -0,0 +1,17 @@ +# Route Observations to Watches with compiled deterministic predicates, so the model never sees the bulk of the corpus. +REPO: InsightWeaver +STATUS: QUEUED # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED +SIZE: medium +ACCEPTANCE: `make check` passes, plus: each Watch's triggers compile to a deterministic predicate over entities, terms and source allowlists, with **no LLM call anywhere in this tier** -- proved by a test that removes the Anthropic client and drives the full routing path; word-boundary matching is used throughout and reuses `src/context/entity_matcher.py`'s primitives rather than a second implementation; `insightweaver route --dry-run` reports, per watch, how many of the last N observations would route, and reports the **unrouted count and its clusters**; routing is idempotent -- the same observation routed twice produces one link; a test asserts that a corpus of 1,000 observations against 5 watches routes fewer than a stated ceiling, so a regression that widens routing fails rather than merely costing money; and the unrouted cluster output is written somewhere task 021 can consume it. +OUT OF SCOPE: Adjudication -- routing decides *candidacy*, not whether something is evidence. Any change to what the adjudication prompt says. Proposing watches from unrouted clusters; that is task 021, and this task only has to make the signal available. Tuning the shipped watches' triggers. Belief updates or state transitions. +LANDMINES: **This tier is the cost control, and a routing predicate that is too loose does not fail -- it bills.** The ceiling test exists because "most observations match nothing and die here" is an architectural claim that needs a number attached or it decays silently. **Word boundaries are load-bearing and the repository has already been bitten**: of 55,249 articles, 5,364 contain the substring `nist` and 73 match it at a word boundary; `mail` is 1,842 versus 339. Task 010 also found that a boundary test can pass for the wrong reason -- its shouted-term cases were rejected by case-sensitivity before the anchors were consulted, so the class passed with anchoring deleted from the codebase. Any boundary test written here must be verified by stripping `LEFT_BOUNDARY`/`RIGHT_BOUNDARY` and confirming it fails. **The unrouted count is the coverage-gap signal and is the only place a missing sensor becomes visible before a staleness alert fires**; logging it as a bare integer with no clustering makes it useless. `main` is protected -- open a PR. +--- +Written 2026-08-31. + +Tier 1 is where the rewrite's central property -- notification volume scaling with live watches +rather than news volume -- is actually enforced. Tiers 2 through 4 can only preserve it. + +**Why a ceiling test rather than a dashboard.** An architectural property that is only observable +in production metrics is one that regresses between releases and is noticed at the invoice. A test +asserting that N observations against M watches routes fewer than K makes the property a gate. +Pick K from a measured baseline, not from intuition, and record how it was measured. diff --git a/backlog/016-tier2-adjudication.md b/backlog/016-tier2-adjudication.md new file mode 100644 index 0000000..129c757 --- /dev/null +++ b/backlog/016-tier2-adjudication.md @@ -0,0 +1,21 @@ +# Adjudicate routed (observation, watch) pairs in the single LLM tier, with structured output and a versioned prompt. +REPO: InsightWeaver +STATUS: QUEUED # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED +SIZE: medium +ACCEPTANCE: `make check` passes, plus: one prompt, versioned and stored with every Evidence row it produces, runs only on pairs Tier 1 routed; output is structured and validated -- is-evidence, direction, magnitude, satisfies-which-trigger, confidence -- and a response failing validation is **recorded as a failed adjudication rather than silently dropped or retried into a different answer**; the tier is the only place in the codebase that constructs a model request, proved by a test asserting no other module imports the client; `insightweaver adjudicate --dry-run` prints what would be sent and its token estimate without calling; replay from task 014 reproduces Evidence for a given prompt version; and per-run token and cost are recorded, because the repository currently has **no token accounting at all** and a cost-controlled architecture that cannot measure its own cost is asserting the property, not holding it. +OUT OF SCOPE: Belief updates, trigger firing, hysteresis, state transitions -- adjudication reports what an observation *is*, and task 017 decides what it *does*. Batching or Bedrock migration; get the semantics right at one-call-per-pair first and optimise once volume is known. Prompt tuning beyond a first version that passes replay. Multiple prompts or a prompt per watch type. +LANDMINES: **The model has been retired underneath this repository once already.** `claude-sonnet-4-20250514` reached end of life on 2026-06-15 and every synthesis failed for ten weeks while the CLI printed a duration and exited 0, because the exception was caught and logged. Any adjudication path must make an API failure loud at the tier boundary. **The response shape changed too**: `content[0].text` was correct when the model did not think and returns a `ThinkingBlock` now; `src/context/claude_client.py` selects text blocks by type and raises on a refusal -- reuse it, do not reimplement the extraction. **Do not add fallbacks**; `CLAUDE.md` forbids concealing problems behind them, and an adjudication that silently degrades to a default verdict is the worst possible instance -- it writes wrong Evidence that the state machine then acts on. Structured output is a request parameter, not a parsing convention. `main` is protected -- open a PR. +--- +Written 2026-08-31. + +Invariant 4 puts exactly one stochastic component in the system. That is what makes the other four +tiers unit-testable, and it means this tier's contract has to be narrow enough to validate: a +verdict object, not prose. + +**Why a failed adjudication is recorded rather than retried.** A retry that produces a different +answer to the same input breaks task 014's replay determinism, which is the only mechanism for +reviewing a prompt change. Record the failure, leave the pair unadjudicated, and let it be visible. + +**Why token accounting lands here.** The audit found the repository has none. Every cost claim in +this architecture -- "Tier 1 is the cost control", "the model must never see the bulk of the +corpus" -- is currently unfalsifiable. This is the tier where a number can be attached. diff --git a/backlog/017-tier3-state-machine.md b/backlog/017-tier3-state-machine.md new file mode 100644 index 0000000..7a7a004 --- /dev/null +++ b/backlog/017-tier3-state-machine.md @@ -0,0 +1,23 @@ +# Apply Evidence to Watches deterministically, with hysteresis and debouncing, so one story across twelve outlets produces one transition. +REPO: InsightWeaver +STATUS: QUEUED # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED +SIZE: large +ACCEPTANCE: `make check` passes, plus: belief updates and trigger evaluation are deterministic with **no LLM call**, proved the same way as Tier 1; hysteresis requires N independent sources or one source on a per-watch pre-declared authoritative list, and `N` is per-watch configuration, not a global constant; a debounce window collapses the same story arriving from many outlets into **one** transition, with a test driving twelve near-duplicate observations through and asserting exactly one Alert; a belief drift of 0.35 to 0.41 produces **no** Alert, asserted directly as the brief specifies; an Alert is created only on a state transition, never on evidence arrival; transitions are append-only and a Watch's belief history is reconstructable; and a test asserts that replaying the same Evidence twice produces the same transitions and no duplicate Alerts. +OUT OF SCOPE: Sending anything -- Alerts are created here and delivered by task 019. Silencing or grouping UI. Resolution scoring; that is task 021. Auto-adjusting hysteresis from observed alert volume, which would let the system tune away its own noise complaint. Belief models more elaborate than what the acceptance requires -- no Bayesian update framework unless a specific watch demonstrably needs one, and if one does, park and say so. +LANDMINES: **This is the task where the rewrite's whole property lives or dies, and every failure mode here is silent.** Hysteresis too weak floods; too strong means the system never fires and looks identical to a broken pipeline -- which is why task 018 must land alongside, not after. **"N independent sources" needs a definition of independent that survives contact with reality**: three outlets syndicating one wire story are not three sources, and the near-duplicate grouping from task 014 is what makes the distinction available -- if it is not wired in here, "independent" degrades to "distinct feed URL" and the debounce is defeated by exactly the case it exists for. **The state machine must be a pure function of (prior state, evidence) or the append-only history is not reconstructable.** Reading current belief from a mutable column and writing back in place will pass tests and lose the audit trail. `main` is protected -- open a PR. +--- +Written 2026-08-31. **The largest and most load-bearing task in this plan.** + +Everything before this tier decides what the system knows. This tier decides what it says, and it +is the only place where the difference between a monitoring system and a firehose is enforced. + +**Why hysteresis is per-watch.** A global N would force one threshold across a Federal Register +publication trigger, where a single authoritative source is sufficient, and a market-sentiment +trigger, where three sources is barely a signal. Watches carry their own; the schema from task 013 +already has the shape for it. + +**On the belief model.** The brief specifies belief as a float and gives one transition example. +Nothing in the acceptance requires a principled update rule, and the temptation here is to build a +Bayesian framework because the data model suggests one. Resist it until a watch exists that needs +it. The 33 predictions in the ledger are a standing demonstration of what happens when machinery is +built ahead of a use for it: 25 of them cannot be graded and none ever was. diff --git a/backlog/018-silence-must-be-distinguishable.md b/backlog/018-silence-must-be-distinguishable.md new file mode 100644 index 0000000..d7f1a3c --- /dev/null +++ b/backlog/018-silence-must-be-distinguishable.md @@ -0,0 +1,34 @@ +# Make silence distinguishable from breakage: staleness alerts, a dead-man's switch off the mail path, and a weekly receipt. +REPO: InsightWeaver +STATUS: QUEUED # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED +SIZE: medium +ACCEPTANCE: `make check` passes, plus: a Watch routing zero Observations for `staleness_alert_days` fires its own Alert naming the watch and the decision it serves; a **heartbeat and DLQ-depth alarm reach the operator through a channel that is not SES**, so a notification-path failure is reported by a path that did not fail -- the channel is named in the PR and its failure mode stated; a weekly receipt is emitted on a fixed schedule stating watches live, alerts fired, alerts suppressed **and why**, calibration by domain, and sources that contributed nothing; the receipt is emitted **even when every count is zero**, because that is precisely when it carries information; and a test drives a fully-silent week and asserts the receipt still goes out with its zeros intact. +OUT OF SCOPE: Making the receipt interesting. It is a liveness proof and an audit surface, and every feature that makes it engaging moves it back toward being a briefing -- which is the product being replaced. No summarization, no highlights, no LLM call anywhere in the receipt path. Alert grouping or silencing UI. Adapter retry policy beyond what the DLQ requires. +LANDMINES: **The brief names this as the requirement most likely to be quietly dropped under schedule pressure, and it is right, because nothing breaks when it is missing.** A system with no staleness alerting works perfectly on every test and fails only by saying nothing while the operator assumes it is watching. **Sequence this alongside task 017, not after it.** The moment hysteresis exists, silence becomes ambiguous; shipping the state machine without this is the window where the failure is live. **The dead-man's switch must not route through SES.** If SES is misconfigured, suspended, or the domain's DKIM breaks, an SES-delivered "SES is broken" alert is an empty inbox -- which is indistinguishable from a quiet week, which is the exact ambiguity this task exists to remove. **The receipt must stay dull on purpose** and this will be the hardest instruction in the plan to follow, because a boring weekly email is the thing everyone wants to improve. `main` is protected -- open a PR. +--- +Written 2026-08-31. + +## Why this is not the last task + +The natural instinct is to build the pipeline and then add observability. Invariant 5 makes that +wrong: in a silence-default system, the observability *is* part of the output contract. "I am blind +here" is frequently the most valuable thing the system produces, and it is only producible if the +staleness path exists at the same time as the path that produces silence. + +The repository has a direct precedent. Task 005 shipped a source-adapter layer with a silent-zero +watchdog because a deploy `notify` job had previously reported success through twelve consecutive +failed nights. Then in task 009 five feeds were configured, CI went green, and the corpus stayed +empty of all of them -- caught only because task 010's coverage command happened to exist by then. +Both were the same failure: a component that succeeded at doing nothing. This task is the general +form of the fix. + +## The receipt's four sections and why each is there + +- **Watches live** -- proves the config loaded. +- **Alerts fired, and suppressed with reasons** -- proves the state machine ran, and makes + hysteresis auditable. A week with 40 suppressions is tuning information; a week with zero + suppressions and zero alerts might be silence or might be a dead router. +- **Calibration by domain** -- the only place the system's own accuracy is visible. +- **Sources that contributed nothing** -- the coverage gap, from the opposite direction to the + staleness alert. A source ingesting steadily and never routing is a feed that costs money and + earns nothing. diff --git a/backlog/019-tier4-notification.md b/backlog/019-tier4-notification.md new file mode 100644 index 0000000..8266b0b --- /dev/null +++ b/backlog/019-tier4-notification.md @@ -0,0 +1,19 @@ +# Deliver Alerts by email, one per firing batch, each naming the decision it bears on. +REPO: InsightWeaver +STATUS: QUEUED # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED +SIZE: medium +ACCEPTANCE: `make check` passes, plus: **only an Alert can cause mail to be sent**, enforced by a single send function that takes an Alert and by a test asserting no other module can reach the transport; Alerts are grouped by watch into one email per firing batch; the body states what changed, what it does to the named decision, **what would have to be true for this to be wrong**, and a link to resolve or adjust the watch; SES domain verification, DKIM, and a custom MAIL FROM are configured and verified against live AWS, with the verification output in the PR rather than asserted; a dry-run mode renders the exact body without sending; and a send failure is loud and lands in the DLQ from task 018, never swallowed. +OUT OF SCOPE: HTML templating beyond what is needed for a readable message; this is not a newsletter. Unsubscribe or preference management at one-user scale. Retry policy beyond DLQ. Alert silencing. Any content the model authors beyond what Tier 2 already produced -- the body is assembled deterministically from Alert fields, with no LLM call. +LANDMINES: **The repository already contains a live `smtplib` send path** at `src/render/email.py:124`, reachable from `brief --format email`. Task 012 deletes it; if 012 has not landed, this task inherits an existing invariant-1 violation and must not add a second transport beside it. **"What would have to be true for this to be wrong" is the field that makes the email worth reading**, and it is the one most likely to degrade into boilerplate. It must come from the Watch's own trigger conditions -- what would move the belief the other way -- not from a template sentence. If it cannot be derived from Watch state, say so rather than shipping a constant string. **SES has a sandbox.** A new SES identity can only send to verified addresses until production access is granted, which is a support request with a turnaround -- start it early or v0 delivery blocks on it. `main` is protected -- open a PR. +--- +Written 2026-08-31. + +Invariant 1 is the narrowest invariant in the brief and the easiest to satisfy structurally: one +function, one caller, one test asserting nothing else reaches the transport. Doing it any other way +-- a notification service, a mailer class with several entry points -- reintroduces the question +this invariant exists to close. + +**On the "what would have to be true for this to be wrong" field.** This is the epistemic +discipline from the old product's `ANALYSIS_RULES.md` surviving into the new one in a much smaller +form. In the briefing generator it was a labelling rule applied to prose. Here it is a field +derived from the watch's own triggers, which makes it checkable rather than stylistic. diff --git a/backlog/020-v0-deployment.md b/backlog/020-v0-deployment.md new file mode 100644 index 0000000..38fa162 --- /dev/null +++ b/backlog/020-v0-deployment.md @@ -0,0 +1,29 @@ +# Deploy v0: one scheduled Lambda, SQLite in S3, five watches, two adapters, SES delivery. +REPO: InsightWeaver +STATUS: QUEUED # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED +SIZE: large +PERSISTENCE: SQLite in S3, single-writer Lambda -- chosen on shape, not price (see backlog/022 Q1). Revisitable before deploy; the cost comparison is unverified and recorded as such. +ACCEPTANCE: `make check` passes, plus: one Lambda runs the full pipeline on an EventBridge daily schedule; persistence is whatever the operator chose (see BLOCKED-ON) and the choice is recorded in the PR with its cost; **five hand-authored watches** drawn from decisions falling inside 90 days are live; two adapters run -- Federal Register API and one existing RSS set; secrets are in SSM Parameter Store, never in the image or environment; the dead-man's switch from task 018 is live and its non-SES channel verified by **deliberately breaking the mail path and confirming the alarm arrives**; and after three weeks of operation the PR is updated with the observed email count against the acceptance bar of **fewer than two per week, every one naming a decision**. +OUT OF SCOPE: Multi-tier Lambda decomposition, SQS between tiers, or per-tier DLQs -- v0 is one Lambda, and the tier boundaries are enforced in code rather than infrastructure until volume justifies otherwise. Bedrock migration or batch mode. IaC beyond what one Lambda and a schedule require. Any sixth watch. Any third adapter. +LANDMINES: **The acceptance bar is a measurement over three weeks of real operation, not a property of the code**, so this task cannot be marked DONE at merge -- it opens, ships, and is updated with the observed number. If v0 emits more than two emails a week the fix is watch tightening or hysteresis, **not features**; if it emits nothing for three weeks *and* staleness alerts are also quiet, the sources do not cover the stakes and adapter work is the real project. Say which of the three outcomes occurred rather than declaring success. **SES production access is a support request with a turnaround** -- see task 019. **The audit found that adding a feed to `config/feeds/` does not add it to the database**: `FeedManager.load_feeds_to_database()` syncs config into `rss_feeds` and the fetcher reads the table, so a deployment that ships config without running the sync fetches nothing while every test passes. That exact failure happened on 2026-08-28. `main` is protected -- open a PR. +--- +Written 2026-08-31. + +v0 exists to answer one question: does notification volume track live watches rather than news +volume? Everything in the acceptance is instrumentation for that question, and the three-week +observation window is not padding -- it is the measurement. + +**Why one Lambda rather than the tier-per-Lambda target shape.** The tier boundaries are semantic +and are already enforced by tasks 015 through 019 in code. Splitting them across Lambdas with SQS +between adds five failure surfaces and a distributed-debugging problem in exchange for scaling +headroom that one user does not need. Take the decomposition when a tier's runtime or failure +profile demands it, and let the DLQ requirement in task 018 be satisfied by the single queue until +then. + +**The three outcomes, stated in advance so the result cannot be reinterpreted afterwards:** + +| observed | means | do | +|---|---|---| +| fewer than 2/week, each naming a decision | the property holds | stop; run it | +| more than that | watches too loose or hysteresis too weak | tighten, do not add features | +| nothing for 3 weeks, staleness also quiet | sources do not cover the stakes | adapter work is the real project | diff --git a/backlog/021-tier5-slow-loops.md b/backlog/021-tier5-slow-loops.md new file mode 100644 index 0000000..d1ea215 --- /dev/null +++ b/backlog/021-tier5-slow-loops.md @@ -0,0 +1,16 @@ +# Weekly slow loops: resolve due watches, score calibration and source contribution, propose candidate watches for human acceptance. +REPO: InsightWeaver +STATUS: QUEUED # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED +SIZE: medium +ACCEPTANCE: `make check` passes, plus: watches past `expires` surface for resolution with a score attached, and resolution is a **human action** with no auto-resolve path; Brier score is computed by domain over resolved watches and appears in the weekly receipt; source contribution is scored along the chain routed -> adjudicated as evidence -> contributed to a resolved watch, so a source that routes heavily and never contributes is visible; unrouted observation clusters from task 015 are surfaced as **candidate** watches that a human accepts or rejects, and **no code path creates a Watch from a candidate without an explicit human accept**; and a test asserts that accepting a candidate requires a distinct operator action and that rejection is recorded rather than discarded. +OUT OF SCOPE: Auto-accepting candidates under any confidence threshold -- invariant 6, and a threshold is just a slower path to the same place. Auto-resolving a watch from coverage. Scoring models beyond Brier until there is enough resolved data to justify one. Retiring sources automatically on low contribution; surface it and let the human cut. +LANDMINES: **Invariant 6 is enforced here or nowhere.** The candidate-proposal feature is the exact seam through which auto-authored watches arrive, and it will arrive as a convenience -- an accept-all flag, a confidence threshold, a "just create the obvious ones" shortcut. The acceptance criterion is written as "no code path creates a Watch without an explicit human accept" rather than "candidates require approval" for that reason. **Calibration needs resolved watches and there will be almost none for months.** A Brier score over two resolutions is noise presented as measurement; the receipt must state the denominator and suppress the figure below a stated minimum rather than printing a number that looks authoritative. The repository has a standing example of the failure this avoids: 33 predictions, zero graded, and a `track-record` command that would have happily printed a rate. `main` is protected -- open a PR. +--- +Written 2026-08-31. Not required for v0; the weekly receipt shell from task 018 is. + +**Why source contribution is scored along a chain rather than by volume.** A source that routes +into many watches and never produces evidence that contributes to a resolution is expensive and +useless, and it looks identical to a valuable source on any volume metric. The audit found the +repository has already made this mistake in the other direction: task 005 reported "469 documents +narrowed to 24" as evidence the beat covered its domain, and the beat then missed the largest event +in that domain because document volume was never the thing to measure. diff --git a/backlog/022-open-questions.md b/backlog/022-open-questions.md new file mode 100644 index 0000000..332f36e --- /dev/null +++ b/backlog/022-open-questions.md @@ -0,0 +1,110 @@ +# Parked questions from the monitoring re-architecture Stage 0. Answer before the tasks that name them. +REPO: InsightWeaver +STATUS: PARKED # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED +SIZE: n/a +ACCEPTANCE: not a work item. Each question below is answered by the operator, the answer is recorded here, and the task that names it is unblocked. +OUT OF SCOPE: guessing any of them. +--- +Written 2026-08-31. + +## ANSWERED 2026-08-31 + +**Position lives in a separate private repository.** Not primarily for safety -- a gitignore +mostly holds -- but because Position must be under version control and cannot be public. The +quarterly review's value is the diff: what did I believe last quarter, which decisions closed, +which watches stopped mattering. Gitignoring the file means no history, and the outermost loop +loses the thing that makes it a loop. The public repo carries the schema and an example, matching +how `user_profile.json` is already handled. + +**Quarterly review degrades visibly rather than suppressing alerts** (task 024, unchanged). + +**Beats and questions are removed; Position replaces them.** Q5 below is answered: none of the +beat, question, prediction, standing-agenda or institutional-activity machinery ports as a concept. +Five modules port as *mechanics* -- see task 012 -- because they encode findings that cost real +debugging, not because their concepts survive. + +**The old code is deleted, not archived.** Git history is the rollback path; a directory of dead +code in the tree reads as current to every future reader and drags the old product's shape forward. +Task 012 is rewritten accordingly and is now sized **large**: ~8,900 lines of source plus most of +844 tests. + +**Persistence is no longer blocking.** The operator's call is to proceed and settle it later. +**Working assumption: SQLite in S3 behind the single-writer Lambda**, on shape rather than price -- +one user, one daily invocation, and the concurrency it cannot handle is concurrency this system +does not have. Task 020's BLOCKED-ON is cleared; the choice is revisitable before deployment and +the cost comparison remains unverified, which is recorded rather than resolved. + +--- + +## Q1 -- ANSWERED 2026-08-31: not blocking; SQLite in S3 as the working assumption, revisitable. + +### Original question, kept because the pricing is still unverified + +The brief asks for the trade-off with current pricing verified. I could not obtain it: +`https://aws.amazon.com/rds/postgresql/pricing/` renders its figures in interactive elements that +do not survive extraction, and the pricing API is unavailable to this account -- +`pricing:GetProducts` returns `AccessDeniedException` for `arn:aws:iam::975050324277:user/saydlette-dev`. + +I am not supplying remembered figures. What I can state without pricing: + +| option | shape | operational cost | +|---|---|---| +| SQLite in S3, single-writer Lambda | one file, read-modify-write per run, no server | no idle cost; concurrency is the risk and one daily Lambda has none | +| RDS `t4g.micro` | managed Postgres, always on | bills hourly whether or not the pipeline runs; needs a VPC, subnet group and security group | +| Aurora Serverless v2 | scales to a floor, not to zero | most expensive of the three at this shape | + +At one user, one daily invocation, and a corpus currently 55,249 rows, **SQLite in S3 is the shape +that matches the workload** -- the concurrency it cannot handle is concurrency this system does not +have. The counter-argument is that a read-modify-write of a growing file per run gets slower and +has no partial-failure story, and that migrating off it later is real work. + +**To answer:** either grant `pricing:GetProducts` and I will produce the figures, or choose on +shape and accept that the cost comparison is unverified. + +## Q2 -- Watch versus the existing Decision + Factor model. Blocks task 013. + +The audit found the repository already models most of Watch, and has never used it: +`decision_factors.what_would_update_me` is a trigger, `.current_state_note` is a belief state, +`decisions.name` is what `so_what` points at, `decision_evidence.direction` is evidence direction. +All of it holds **0 rows**. + +Evolving Decision+Factor avoids a second overlapping model; creating Watch alongside avoids +inheriting a prose-shaped schema where the new one needs floats and structured triggers. **My +recommendation is to evolve rather than add**, because this repository already carries one +unresolved duplication -- see the reconciliation note -- and a second would be worse than either +choice on its merits. But it is a schema decision with migration consequences and it is yours. + +## Q3 -- Observations versus the existing `articles` table. Blocks task 014. + +55,249 rows exist and every current query reads them. Observations can supersede that table +(migration of 55k rows), wrap it (two shapes for one concept), or coexist (a rule nobody remembers +in six months). I have no recommendation strong enough to make silently; the task file requires the +implementer to state the rule, but if you have a preference it belongs here first. + +## Q4 -- The `so_what` -> decision link. Blocks task 013. + +Invariant 2 requires every Watch to name a specific decision. Should that be a **free-text +`so_what` string**, or a **foreign key into the Position's decisions** with the prose as an +annotation? The key makes the invariant machine-checkable and makes "which watches serve this +decision" a query; the string is faster to author and does not force Position structure. The +acceptance in task 013 currently assumes the key, because an invariant enforced only by prose is +the pattern this repository has been correcting all week. Confirm or overrule. + +## Q5 -- ANSWERED 2026-08-31: removed. Position replaces them. See the block above. + +### Original question, kept for the reasoning + +Tasks 004-011 shipped beats, standing questions, institutional activity, coverage probes and the +operator calibration loop -- roughly 2,400 lines with 844 tests behind them. Some maps onto the new +model cleanly: `coverage_probes` is a staleness check by another name, and the operator calibration +loop is watch resolution scoring. Some does not: institutional activity is a briefing feature. + +The plan above does **not** archive any of it, and does not port it either. That is a deliberate +gap, not an oversight -- deciding it needs your view on whether the compliance beat continues to +exist as a concept under the new architecture, or whether Position + Watches replaces it entirely. + +## Q6 -- Dead-man's switch channel. Blocks task 018. + +It must not be SES. SNS to SMS, a CloudWatch alarm to a phone push, or a third-party healthcheck +service that alarms on a missed heartbeat are the obvious candidates, each with a different failure +mode and cost. Which do you want, and to what endpoint? diff --git a/backlog/023-the-state-feed.md b/backlog/023-the-state-feed.md new file mode 100644 index 0000000..0da537a --- /dev/null +++ b/backlog/023-the-state-feed.md @@ -0,0 +1,33 @@ +# A password-protected feed showing current state of every live watch, so email carries transitions and the feed carries state. +REPO: InsightWeaver +STATUS: QUEUED # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED +SIZE: medium +ACCEPTANCE: `make check` passes, plus: the weekly Lambda writes a JSON state snapshot to S3 containing every live watch with its claim, current belief, date and direction of last change, the decision it serves, days to expiry, staleness state, and its last three evidence items; a static page renders one card per watch behind an auth gate that **fails closed** -- no credential configured returns 503, never open. `silk-reeling-mirror` replaced Basic Auth with Cognito JWT in its PRs #1-#4 and **carried its fail-open fallback forward into the new implementation**, fixed in its PR #5; reuse the corrected Cognito pattern, and confirm which it is at implementation time rather than trusting this line; the page has **no scroll beyond the card list, no counts, no badges, no history stream, and no infinite anything**; a week in which nothing changed renders every card reading "no change since " and that is a complete and correct view; belief can be adjusted and a watch resolved from the page, writing back through the same path the CLI uses; and the page renders correctly with zero live watches rather than erroring. +OUT OF SCOPE: Any content the feed shows that the email does not. This is the constraint that keeps it from becoming a place to browse, and browsing is the addictive property. No article text beyond the evidence items already attached to a watch. No search, no archive, no "explore", no related-watch suggestions. No engagement metrics of any kind -- not view counts, not streaks, not "3 new since your last visit". No LLM call in the render path. No server: a JSON file and a static page, nothing to compromise beyond the bucket. No mobile app. +LANDMINES: **Every feature that makes this more engaging moves it back toward being a briefing, which is the product being replaced.** The pressure will not arrive as "let's make it addictive"; it will arrive as "it would be useful to also see...". The acceptance criterion "shows nothing the email does not" is the line, and it is written that way so a proposed addition has to justify itself against the email first. **Auth must fail closed and this is not theoretical**: `silk-reeling-mirror` shipped fail-open under Basic Auth, then **re-implemented auth entirely with Cognito and preserved the same hole**, because a local-dev passthrough reads as a feature rather than as a config typo away from open. Both were fixed on 2026-08-31. A rewrite is not a fix; verify this gate behaviourally with the config absent. **The snapshot contains Position-derived data** -- decisions, deadlines, beliefs -- which is more sensitive than anything currently on samaydlette.com. The S3 object must not be public-read, and the bucket must not be the site's public bucket. `main` is protected -- open a PR. +--- +Written 2026-08-31. + +## Why this is not scope creep + +Email is good at transitions and bad at state. *"Belief on FedRAMP 20x moved to 0.62"* is an email. +*"What do I currently believe across nine watches, and which are stale?"* is not -- answering that +from an inbox means reconstructing state from a sequence of deltas, which is the wrong tool. + +**Email carries transitions. The feed carries state.** Each does one job. + +## What makes it non-addictive is structural, not restraint + +- **Bounded.** N watches, one card each. There is no scroll. Nine cards read is *done*, and done is + a real state that a social feed deliberately never has. +- **State, not stream.** Cards update in place. There is no accumulating history to graze. +- **Boring when nothing happened**, the same discipline as the weekly receipt. +- **Nothing appears because it is new.** Things appear because a watch was registered on them. +- **No numbers except belief**, which the operator sets themselves. + +## The highest-value interaction + +Adjusting belief and resolving from the page. That is the calibration loop with the friction +removed -- and friction is the reason the existing ledger holds 33 predictions and zero verdicts. +A card with the claim, the date it last moved, and two buttons is a materially lower bar than +remembering a CLI command. diff --git a/backlog/024-setup-interview-and-quarterly-review.md b/backlog/024-setup-interview-and-quarterly-review.md new file mode 100644 index 0000000..1be9e42 --- /dev/null +++ b/backlog/024-setup-interview-and-quarterly-review.md @@ -0,0 +1,59 @@ +# An interview that drafts Position, and a quarterly review loop that degrades visibly when it lapses -- the outermost loop, which sets the thresholds every inner loop steers against. +REPO: InsightWeaver +STATUS: QUEUED # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED +SIZE: medium +ACCEPTANCE: `make check` passes, plus: `insightweaver setup` runs a question-and-answer interview that **writes a draft `position.yaml` to a scratch path and prints it for the operator to edit and commit** -- it never writes to the live Position and never creates a Watch, so invariant 6 holds; the interview elicits decisions with deadlines, refuses to record a decision with no date, and asks for each what evidence would change it; `insightweaver review` opens the quarterly loop, showing each decision, whether it is still live, each watch derived from it with its belief history since last review, and every watch that expired or went stale in the period; completing a review stamps `position.reviewed` and **records what changed, including "nothing"**; the weekly receipt shows days since last review; past 90 days every alert email and every feed card carries a visible staleness banner naming the review date; and a test drives a review with no changes and asserts it still stamps and still records. +OUT OF SCOPE: The interview authoring watches, ranking decisions, or suggesting beliefs. It elicits and transcribes; the operator decides. Suppressing alerts when review lapses -- see the reasoning below. Auto-extending expiry dates. Any calendar integration, reminder service, or notification outside the receipt and the banner. Auto-retiring a decision because its deadline passed; surface it in the review and let the human close it. +LANDMINES: **The interview is the seam through which the system starts authoring its own watches.** It will arrive as convenience -- "it already knows the decision, why not draft the watch too". Invariant 6 exists because auto-generated watches are the path back to a firehose with extra steps, and a drafting interview is one commit from being a generator. The acceptance says it writes a draft Position to a **scratch path**, not the live file, for that reason. **A review that can be completed by pressing return teaches nothing**; requiring a recorded outcome, including an explicit "nothing changed", is what makes the loop a loop rather than a checkbox. **Do not make review a hard gate on alerting.** See below -- it is the one place in this plan where "mandatory" is the wrong mechanism. `main` is protected -- open a PR. +--- +Written 2026-08-31, answering the setup-and-maintenance question directly. + +## Why this is the outermost loop, not just a chore + +The system now runs several loops at different periods. Listed by speed: + +| loop | period | corrects | +|---|---|---| +| ingest -> alert | daily | did anything change | +| watch cadence | 7d - 1y, per watch | is this still worth watching at this rate | +| weekly receipt | 7d | is the system alive | +| resolution | at expiry | was I right | +| **Position review** | **90d** | **are these still my stakes** | + +The quarterly loop is outermost, and it is the only one that corrects the *inputs* to all the +others. Every inner loop steers against thresholds this one sets. If it stops, nothing breaks -- +the daily loop keeps running, alerts keep firing, the receipt keeps arriving. They just gradually +stop being about anything that matters, and **nothing in the system can detect that from inside**. +That is precisely why it needs a mechanism rather than an intention. + +## Why review is not a hard gate on alerting + +The instinct is to make it mandatory by suppressing alerts when review lapses. That is wrong here, +and the reasoning is the same one that governs the rest of this architecture. + +The cost of a stale Position is a **wrongly-prioritised** alert -- a watch serving a decision +already made. The cost of suppression is a **missed** alert. Those are not symmetric, and a system +that goes silent because you were busy for a quarter is a system that punishes you at the moment +you have least attention to spare. Worse, it reintroduces the ambiguity invariant 5 exists to +remove: suppressed-for-staleness looks exactly like nothing-happened. + +So the mechanism is **visible degradation, not suppression**: the receipt leads with the review +date, and past 90 days every alert and every feed card is banded with it. The alert still arrives. +You just cannot read one without being told the frame it was judged against is out of date. + +## What the interview is and is not + +It is a **transcription aid for a hard authoring task**, which is the actual barrier to this system +existing. Writing `position.yaml` from a blank file is the kind of task that does not get done, and +five watches with real deadlines is a real morning's work. + +It is not a drafting assistant with opinions. It asks: + +- What decisions are you carrying that have a date on them? +- What is the date, and what happens if you get it wrong? +- What would change your mind? +- Where would you find out? + +Then it writes what you said into the schema, to a scratch path, for you to edit and commit. The +last question is the one that most often reveals there is no sensor -- which is a finding worth +having before the watch is registered rather than 45 days later when its staleness alert fires. diff --git a/docs/RECONCILIATION.md b/docs/RECONCILIATION.md new file mode 100644 index 0000000..d2cd15f --- /dev/null +++ b/docs/RECONCILIATION.md @@ -0,0 +1,53 @@ +# Reconciliation: which product is this? + +Written 2026-08-31, at the start of the monitoring re-architecture. + +## The contradiction + +`README.md` describes a briefing generator: situations, frame analysis, three synthesis passes, a +document you read each morning. `CLAUDE.md`'s North Star describes a persistent commitment graph +where *"the brief is the update event; the graph is the artifact."* + +Both are checked in. Both are honest descriptions of something. They are not descriptions of the +same thing, and the disagreement is not cosmetic -- it decides what the selection function selects +against. A briefing selects the most notable items from the corpus. A monitoring system selects +state transitions on pre-registered watches. The first scales with news volume, the second with the +number of live watches, and no amount of better synthesis converts one into the other. + +**`CLAUDE.md` is closer to correct and the re-architecture resolves in its favour.** The graph is +the artifact; the notification is the update event. The briefing framing goes to `archive/`. + +## The stale claim, and it is now stale twice over + +`CLAUDE.md` was corrected on 2026-08-26 to say input arrives through the adapter layer in +`src/sources/` rather than RSS alone. That correction is accurate. What is now stale is the +sentence around it describing the pipeline's purpose -- clustering, frames and synthesis are +described as being *"unaware adapters exist"*, which was the right seam for a briefing generator +and is the wrong description of a system whose downstream is a state machine. + +`README.md` is stale more broadly. It opens on narrative framing and dominant-narrative analysis, +which is a coherent thesis about news consumption and is not what the system will do. + +## What the docs should say after the rewrite + +**`README.md`** -- lead with the monitoring claim and its measurable property: notification volume +tracks live watches, not news volume. State the invariants. Keep the `Current state` section added +on 2026-08-27, which already carries known limitations honestly and should carry the rewrite's +status the same way. Delete the frame-analysis thesis; it belongs to the archived product. + +**`CLAUDE.md`** -- keep the North Star's commitment-graph framing, which survives intact. Replace +the pipeline description with the five tiers and the four invariants that constrain them. Keep the +unattended-work rules unchanged; they are product-independent and have earned their place. + +**`docs/CONCEPTS.md`** -- currently 11 sections describing Questions, Predictions, Decisions, +Frames, Meta-fractures, Beats, Institutional activity and how a daily brief flows through the +graph. Sections describing the briefing flow are archived. Whether Beats, Questions and +Institutional activity survive as concepts depends on Q5 in `backlog/022`, which is parked. + +## One thing worth saying plainly + +The old product was not wrong because it was badly built. It has 1,006 tests, a real gate, and +several genuinely careful pieces of engineering -- the offline render path, the coverage probes, +the person-tracking boundary. It was wrong because a document of constant length emitted on a fixed +schedule cannot carry information about whether anything happened. That is a property of the shape, +not of the implementation quality, which is exactly why better synthesis was never going to fix it.