docs(6207): the remaining migrations state their rationale in terms of the data

Record, milestone, phase and plan citations go from every migration header;
the "end before start" fix (0043) and the suppressed-count column (0095)
state the condition they prevent rather than the incident. 0053 and 0055
pointed at design specs under docs/superpowers that are not in the repo;
those pointers are removed.

Kept: alembic's generated "Create Date:" headers (template metadata, not
rationale), 0121's ARM_BORN justification beside the constant, and 0051's
illustrative "update task 42" format example.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

alembic/versions/0043_event_duration_replaces_end_dt.py

@@ -1,13 +1,11 @@
-"""replace events.end_dt with duration_minutes (Fable #160)
+"""replace events.end_dt with duration_minutes
 
 Revision ID: 0043
 Revises: 0042
 Create Date: 2026-04-29
 
-Structural fix for the "end before start" bug class observed on prod
+Structural fix for the "end before start" bug class: an event whose end_dt
-2026-04-29: an event landed with end_dt 32 days before start_dt due
+precedes its start_dt disappears from upcoming-list filters. Storing duration instead of end_dt makes the invalid state
-to a tool-call mishap, then disappeared from upcoming-list filters.
-Storing duration instead of end_dt makes the invalid state
 inexpressible at the schema level (duration_minutes >= 0).
 
 Backfill rules:

alembic/versions/0044_add_note_description_and_consolidated_at.py

@@ -5,7 +5,7 @@ Revises: 0043
 Create Date: 2026-05-13
 
 Adds two columns to the ``notes`` table to support the task-as-durable-record
-design (spec 2026-05-13):
+design:
 
 - ``description``: user-stated goal / initial context. Meaningful when
   ``is_task=true``; left NULL on knowledge notes.

alembic/versions/0048_conversation_last_curator_run.py

@@ -4,7 +4,7 @@ Revision ID: 0048
 Revises: 0047
 Create Date: 2026-05-22
 
-Phase 2 of the conversation+curator architecture (Fable #172). The
+Part of the conversation+curator architecture. The
 scheduler runs every 15 minutes and processes any journal conversation
 with messages newer than its `last_curator_run_at` timestamp. NULL
 means "never run; process all of today on first sweep."

alembic/versions/0049_conversation_curator_summary.py

@@ -4,7 +4,7 @@ Revision ID: 0049
 Revises: 0048
 Create Date: 2026-05-22
 
-Phase 3 of the conversation+curator architecture (Fable #172). The
+Part of the conversation+curator architecture. The
 curator's final summary line (≤ 240 chars) is persisted here so the
 NEXT chat turn can include it in the system prompt. This is the
 feedback loop that closes the architecture — without it, the chat

alembic/versions/0053_drop_chat_journal_push_curator_tables.py

@@ -4,13 +4,11 @@ Revision ID: 0053
 Revises: 0052
 Create Date: 2026-05-27
 
-Phase 9 of the MCP-first pivot. The Python models for these tables were
+Part of the MCP-first pivot. The Python models for these tables are gone;
-deleted in Phase 8 (commit 91bafb6); this migration drops the orphan
+this migration drops the orphan
 SQL tables and cleans up dead per-user setting rows.
 
-Hard-cutover: existing rows in these tables are discarded. The
+Hard-cutover: existing rows in these tables are discarded, deliberately.
-accompanying spec at docs/superpowers/specs/2026-05-26-mcp-first-pivot-design.md
-explicitly accepted this loss.
 """
 from alembic import op
 

alembic/versions/0054_drop_image_cache.py

@@ -4,7 +4,7 @@ Revision ID: 0054
 Revises: 0053
 Create Date: 2026-05-27
 
-The image cache was wired into the LLM image-search tool (removed in Phase 8).
+The image cache was wired into the LLM image-search tool, which is gone.
 With no producer or consumer left, the table is dropped here.
 """
 from alembic import op

alembic/versions/0055_rulebook_tables.py

@@ -6,8 +6,8 @@ Create Date: 2026-05-27
 
 Adds the Scribe Rulebook hierarchy as a fourth top-level entity, sibling
 to Project. Rules carry a structural (statement, why, how_to_apply)
-triple. Projects subscribe to Rulebooks (many-to-many). See the design
+triple. Projects subscribe to Rulebooks (many-to-many; migration 0101
-doc at docs/superpowers/specs/2026-05-27-scribe-rulebook-design.md.
+later drops subscriptions).
 """
 from alembic import op
 import sqlalchemy as sa

alembic/versions/0066_milestone_body.py

@@ -4,7 +4,7 @@ Revision ID: 0066
 Revises: 0065
 Create Date: 2026-06-14
 
-T3 of plan #819. The milestone becomes the plan container: its `body` holds
+The milestone becomes the plan container: its `body` holds
 the design/intent/purpose (markdown), `description` stays the one-liner, and
 individual steps live as first-class child tasks (milestone_id) instead of
 checkboxes crammed into a kind=plan task body. start_planning is reworked to

alembic/versions/0074_design_prose.py

@@ -4,8 +4,7 @@ Revision ID: 0074
 Revises: 0073
 Create Date: 2026-07-31
 
-The operator's shape for #254: prose doesn't live as one-offs, it lives centrally
+Prose doesn't live as one-offs; it lives centrally on the system. Two fields rather than one per category:
-on the system. Two fields rather than one per category:
 
   design_systems.guidance   the narrative a token table cannot hold — aesthetic,
                             voice and tone, what is deliberately out of scope.
@@ -17,7 +16,7 @@ on the system. Two fields rather than one per category:
 
 Free-form rather than a column per category on purpose. A schema with `voice`,
 `aesthetic` and `scope` columns would bake one rulebook's table of contents into
-every install (rule #115), and the next install's design system would have three
+every install, and the next install's design system would have three
 empty columns and nowhere to put what it actually cares about.
 
 Both nullable: a design system with no prose at all is complete, not a draft.

alembic/versions/0076_note_supersessions.py

@@ -4,7 +4,7 @@ Revision ID: 0076
 Revises: 0075
 Create Date: 2026-08-07
 
-Step 1 of milestone #278. Structure only — nothing reads or writes the new
+Structure only — nothing reads or writes the new
 table yet, and nothing behaves differently after this runs.
 
 ## What the table is for
@@ -39,7 +39,7 @@ and not for notes, so the column looked like the notes-side half of that
 feature, modelled and abandoned.
 
 It is dropped rather than repurposed for supersession, and the distinction is
-the point (#2483): consolidation folds several records into one survivor and
+the point: consolidation folds several records into one survivor and
 destroys the originals. Merging two snippets is lossless — one helper, several
 call sites. Folding two dev-logs means writing a summary and losing what each
 actually said. Supersession is the opposite act: both records survive, and the

alembic/versions/0077_chunked_embeddings.py

@@ -1,4 +1,4 @@
-"""Chunked embeddings: one note_embeddings row per chunk (#280)
+"""Chunked embeddings: one note_embeddings row per chunk
 
 Revision ID: 0077
 Revises: 0076

alembic/versions/0078_forge_connections.py

@@ -1,4 +1,4 @@
-"""Forge connections move to the user level (#2778)
+"""Forge connections move to the user level
 
 Revision ID: 0078
 Revises: 0077
@@ -12,7 +12,7 @@ keyring, with an optional per-project pin (projects.forge_connection_id).
 
 The data move carries the existing admin config into a connection row for the
 first admin user (host parsed from the base URL), then deletes the old
-setting keys outright — no legacy dual-read (rule #22). The env-var channel
+setting keys outright — no legacy dual-read. The env-var channel
 (FORGE_KIND/FORGE_BASE_URL/FORGE_TOKEN) is untouched by this migration; it
 survives as an implicit keyring entry for admin users only.
 """

alembic/versions/0080_code_shape_proposals.py

@@ -1,4 +1,4 @@
-"""Shape fingerprints + the mechanical proposer's columns (#2792, milestone 294)
+"""Shape fingerprints + the mechanical proposer's columns
 
 Revision ID: 0080
 Revises: 0079

alembic/versions/0081_shape_history_and_divergence.py

@@ -1,4 +1,4 @@
-"""Shape history, recheck, and the divergence flag (#2793, milestone 294)
+"""Shape history, recheck, and the divergence flag
 
 Revision ID: 0081
 Revises: 0080

alembic/versions/0083_code_shape_reason_code.py

@@ -1,4 +1,4 @@
-"""Exempt/variant reason codes — a small fixed catalogue beside the prose (#2874, milestone 294)
+"""Exempt/variant reason codes — a small fixed catalogue beside the prose
 
 Revision ID: 0083
 Revises: 0082

alembic/versions/0084_code_shape_uses.py

@@ -1,4 +1,4 @@
-"""code_shape_uses — consumption edges, separate from conformance (#2870, milestone 294)
+"""code_shape_uses — consumption edges, separate from conformance
 
 Revision ID: 0084
 Revises: 0083

alembic/versions/0085_project_inception.py

@@ -1,4 +1,4 @@
-"""Project inception: the decision record + always-on rulebook exclusions (milestone 297)
+"""Project inception: the decision record + always-on rulebook exclusions
 
 Revision ID: 0085
 Revises: 0084

alembic/versions/0086_code_shape_consumers.py

@@ -1,4 +1,4 @@
-"""code_shape_consumers — the CSS consumer map (milestone 302, note 2917)
+"""code_shape_consumers — the CSS consumer map
 
 Revision ID: 0086
 Revises: 0085

alembic/versions/0089_rule_embeddings.py

@@ -1,5 +1,4 @@
-"""rule_embeddings — rules become findable by meaning (milestone 307 step 4,
+"""rule_embeddings — rules become findable by meaning
-decision note 3026)
 
 Revision ID: 0089
 Revises: 0088

alembic/versions/0095_retrieval_log_suppressed_count.py

@@ -1,4 +1,4 @@
-"""add retrieval_logs.suppressed_count — tell a ranker decline from a repeat (#3497)
+"""add retrieval_logs.suppressed_count — tell a ranker decline from a repeat
 
 Revision ID: 0095
 Revises: 0094
@@ -20,9 +20,8 @@ the dropped rows never come back and there is nothing to count.
 NULLABLE, AND THE NULL IS THE POINT. A surface that does not measure
 suppression stores NULL, not 0, and the readout renders it as "not measured"
 rather than "none". Defaulting to 0 would make an unmeasured surface look like
-a perfectly clean one — the exact substitution of an artifact for a
+a perfectly clean one — the substitution of an artifact for a measurement
-measurement that #3311 made and that #3497 exists to correct. Doing it again,
+that this column exists to prevent.
-in the migration that fixes it, would be its own small joke.
 
 No backfill for the same reason: existing rows genuinely do not know, and
 saying so is the honest state. `retrieval_logs` is not restored from backup,

alembic/versions/0096_retrieval_log_best_available_score.py

@@ -1,4 +1,4 @@
-"""add retrieval_logs.best_available_score — the score the bar rejected (#3670)
+"""add retrieval_logs.best_available_score — the score the bar rejected
 
 Revision ID: 0096
 Revises: 0095
@@ -34,7 +34,7 @@ NULLABLE, AND UNBACKFILLED, for the reason 0095 spells out: a row written
 before this shipped genuinely does not know what its best rejected candidate
 scored, and saying so is the honest state. A 0.0 default would read as "the
 corpus had nothing remotely relevant" — an artifact standing in for a
-measurement, which is the whole defect this milestone corrects.
+measurement, which is the defect this column corrects.
 
 `retrieval_logs` is not restored from backup, so no importer changes.
 

alembic/versions/0097_retrieval_log_best_available_id.py

@@ -1,4 +1,4 @@
-"""add retrieval_logs.best_available_id — WHICH record the bar refused (#3807)
+"""add retrieval_logs.best_available_id — WHICH record the bar refused
 
 Revision ID: 0097
 Revises: 0096

alembic/versions/0098_rule_kind.py

@@ -1,4 +1,4 @@
-"""rules gain a `kind` — a preference is a rule that does not bind (#3849)
+"""rules gain a `kind` — a preference is a rule that does not bind
 
 Revision ID: 0098
 Revises: 0097
@@ -37,7 +37,7 @@ install upgrades and every existing row keeps the force it had. That is the
 same reasoning 0088 used for `tier`, and it is the reason both are safe to
 apply without reading the data first.
 
-The CHECK is created with the column (rule 36: there is no prior constraint,
+The CHECK is created with the column (there is no prior constraint,
 so the pair is created together — a value added to it LATER does DROP + ADD
 in one migration).
 

alembic/versions/0099_scrub_secrets_from_retrieval_logs.py

@@ -7,7 +7,7 @@ Create Date: 2026-09-11
 `pre_tool_rule` retrieves against the RAW COMMAND TEXT and `write_path_rule`
 against the code being written, so whatever was on the command line or in the
 buffer is what `record_retrieval` wrote into `retrieval_logs.query`. A command
-that exported a token stored the token (#3925).
+that exported a token stored the token.
 
 `services/retrieval_telemetry.scrub_secrets` closes that going forward — the
 value never reaches the column. It cannot reach BACKWARDS, and this does: it

alembic/versions/0100_drop_always_on_tier.py

@@ -4,14 +4,14 @@ Revision ID: 0100
 Revises: 0099
 Create Date: 2026-09-11
 
-Milestone 394. Every rule now reaches a session by retrieval — because
+Every rule reaches a session by retrieval — because
 something it is about to do made the rule relevant — and the machinery that
 delivered rules unconditionally goes with it.
 
 WHAT GOES, AND WHERE IT CAME FROM
 
   - ``rules.tier`` and its ``ck_rules_tier`` CHECK (migration 0088). Dropping
-    the column takes the constraint with it. Rule 36 is about ADDING a value to
+    the column takes the constraint with it. DROP + ADD is about ADDING a value to
     a live whitelist, which needs DROP + ADD in the same migration; it does not
     speak to removing the column outright, and saying so here is cheaper than
     the next reader wondering whether it was forgotten.

alembic/versions/0102_milestone_embeddings.py

@@ -1,4 +1,4 @@
-"""milestone_embeddings — a plan becomes findable by meaning (milestone 415)
+"""milestone_embeddings — a plan becomes findable by meaning
 
 Revision ID: 0102
 Revises: 0101
@@ -9,8 +9,8 @@ lives in — could not be found at all. So "is there already a plan for this?"
 had no tool, and a project whose roadmap was written as milestones had every
 later plan opened as a new milestone beside the one that already described it.
 
-The sibling of rule_embeddings (0089), for the reasons its model docstring and
+The sibling of rule_embeddings (0089), for the reasons its model docstring
-note 3163 give. The vectors are DERIVED: nothing is backfilled here, the startup
+gives. The vectors are DERIVED: nothing is backfilled here, the startup
 backfill writes them.
 """
 import sqlalchemy as sa

alembic/versions/0103_retrieval_tuning_events.py

@@ -1,16 +1,12 @@
-"""retrieval_tuning_events — why a floor is where it is (#4102)
+"""retrieval_tuning_events — why a floor is where it is
 
 Revision ID: 0103
 Revises: 0102
 Create Date: 2026-09-17
 
-Milestone 416 stops shipping similarity thresholds as values somebody has to
+Similarity thresholds are not values somebody has to defend: the model that
-defend, and hands the adjustment to the model that reads the surface's own
+reads the surface's own telemetry adjusts them, and the operator can still
-telemetry. The operator's decision:
+touch them.
-
-    "the floor should be chosen and adjusted by the model using it… the user
-    should be able to touch it but the model should be the thing handling it 9
-    times out of 10."
 
 The number itself already has a home — the generic settings table. What has no
 home is the ARGUMENT, and once the values move on their own the argument is the

alembic/versions/0106_rule_usage_events_carry_an_outcome.py

@@ -12,9 +12,7 @@ sessions leave identical telemetry:
   - a rule surfaced, opened, and silently ignored.
 
 The second is the more urgent by a distance, and it is the one the readout
-cannot name. That is the whole of what this milestone is about, measured on a
+cannot name, and it is what an outcome column is for.
-session where three of seven misses were caught by the operator and none by
-the system.
 
 TWO NEW EVENT VALUES, AND NO CHECK MIGRATION. `event` was created in 0094 as
 plain `sa.Text()` with no constraint — checked in the migration itself, not

alembic/versions/0107_system_embeddings.py

@@ -1,4 +1,4 @@
-"""system_embeddings — a charter becomes an ANSWER, not just a filter (#4251)
+"""system_embeddings — a charter becomes an ANSWER, not just a filter
 
 Revision ID: 0107
 Revises: 0106
@@ -13,8 +13,7 @@ to one, and an agent asking where a record belonged had to read every charter
 or guess.
 
 The fourth sibling of note_embeddings (0067), rule_embeddings (0089) and
-milestone_embeddings (0102), and for the same reason note 3163 gives about the
+milestone_embeddings (0102), and for the same reason as the third: the row could be shared, the search cannot. "Where does this belong?"
-third: the row could be shared, the search cannot. "Where does this belong?"
 is a different question from "what prior art is there?", and no note or rule
 search can answer it, because a charter is not a note.
 

alembic/versions/0109_embeddings_record_their_model.py

@@ -1,4 +1,4 @@
-"""embeddings_record_their_model — a vector says whose space it lives in (#4132)
+"""embeddings_record_their_model — a vector says whose space it lives in
 
 Revision ID: 0109
 Revises: 0108

alembic/versions/0110_task_claims.py

@@ -1,4 +1,4 @@
-"""task_claims — a task can say a session is working it (milestone 381 step 2)
+"""task_claims — a task can say a session is working it
 
 Revision ID: 0110
 Revises: 0109

alembic/versions/0113_system_path_patterns.py

@@ -1,5 +1,4 @@
 """system_path_patterns — a System names the files that are its area
-(milestone 444 step 3, #4756)
 
 Revision ID: 0113
 Revises: 0112

alembic/versions/0114_system_usage_events.py

@@ -1,5 +1,5 @@
 """system_usage_events — were an area's rulings read once its files were
-touched? (milestone 444 step 4, #4757)
+touched?
 
 Revision ID: 0114
 Revises: 0113

alembic/versions/0115_retrieval_judgments.py

@@ -1,5 +1,4 @@
 """retrieval_judgments — a reviewer's verdict on each line of a logged menu
-(#4772)
 
 Revision ID: 0115
 Revises: 0114

alembic/versions/0119_rule_moment_misfires.py

@@ -1,5 +1,5 @@
 """rule_moment_judgments.misfire — a mount reported as arriving where it does
-not apply (milestone 458 step 7b, #4955)
+not apply
 
 Revision ID: 0119
 Revises: 0118

alembic/versions/0122_seal_forge_tokens.py

@@ -1,4 +1,4 @@
-"""Seal forge-connection tokens at rest (milestone 523)
+"""Seal forge-connection tokens at rest
 
 Revision ID: 0122
 Revises: 0121