feat(520,521): full decision-corpus migration + parallel-orientation startup rewrite (PR2 of 2) #527

2026-07-21T12:09:16+02:00

timothy commented

2026-07-21 12:09:16 +02:00

PR2 of 2 — full decision migration + #520 startup rewrite — `fixes #520 #521`

Completes the knowledge-retrieval arc. PR1 (#526) shipped the machinery; this migrates the whole corpus and rewires startup so agents actually reach for it.

What this delivers

Full corpus migration → 0 legacy. All 108 active decision records now carry the lifecycle metadata block (key/status/since/supersedes/superseded-by + Rule/Signals/Mechanics), fanned out across topic-file + decisions.md batches, gap-filled, de-duplicated, and quality-reviewed (28/108 sampled SOLID). docs/decisions/migration-map.md records the non-trivial mappings.
#520 startup rewrite (docs/handoffs/chicorytv-issue-queue.md, docs/README.md, CLAUDE.md, scripts/select-queue.sh): two concurrent tracks when no issue named (orientation ‖ scripts/select-queue.sh 5), named-issue-skips-selection, the ## Closing record template, and the four server-management#642 orientation bullets verbatim (catalog-first; Gitea-ErsatzTV = evidence-not-authority; the breadcrumb rule — a file path in a historical comment is a breadcrumb not a live pointer, resolve by concept; catalog→rg fallback, MemPalace never authority). Still-valid workflow lore preserved; pre-script selector lore demoted to a clearly-labeled archival section.
#237 retired as live state: reduced to an archival line; the decision docs.queue-state-gitea-tracker flipped to status: superseded and moved to docs/decisions/archive/startup.md, superseded by the new active startup.parallel-orientation (reciprocal links; rationale preserved verbatim).
scripts/check-kickoff-guard.sh — blocks any regression to treating #237 as live state; wired into the decisions lifecycle CI job (non-vacuity proven: failed on pre-rewrite docs, passes after).
Two new validator guards (with non-vacuous tests): archive↔archive reciprocity, and duplicate-metadata-block detection — both caught real defects during this PR. retrieval-eval.md excluded from parsing; budget re-baselined to 4800 post-migration.
docs/decisions/retrieval-eval.md — the active-vs-superseded retrieval benchmark (includes the #390→ci.runner-placement and #237→startup.parallel-orientation traps).

Verification (all local, pre-push)

decisions_validate.py OK, 0 legacy, 108 active; --base origin/main --head HEAD exit 0; catalog --check in sync; check-kickoff-guard.sh OK; 31 pytest pass; up to date with origin/main.
Startup cold-agent sim: fresh agent went catalog-first, never read #237 (cited the doc lines), ran select-queue.sh, understood the breadcrumb rule.
Retrieval cold-agent sim: 6/6 correct active records, zero superseded returned; nailed both active-vs-superseded traps.
Whole-branch adversarial review (SOUND-WITH-FIXES → all folded): confirmed the #520 rewrite complete+correct and the #237 supersession lifecycle-correct.

server-management#642 (MemPalace exporter)

On merge I'll post "ready to mine — decisions lifecycle green on <main-sha>" to #642; its 283-issue export is live + tiered and becomes reachable once this orientation block lands.

fixes #520 #521

## PR2 of 2 — full decision migration + #520 startup rewrite — `fixes #520 #521` Completes the knowledge-retrieval arc. PR1 (#526) shipped the machinery; this migrates the whole corpus and rewires startup so agents actually reach for it. ### What this delivers - **Full corpus migration → 0 legacy.** All 108 active decision records now carry the lifecycle metadata block (`key`/`status`/`since`/`supersedes`/`superseded-by` + `Rule`/`Signals`/`Mechanics`), fanned out across topic-file + `decisions.md` batches, gap-filled, de-duplicated, and quality-reviewed (28/108 sampled SOLID). `docs/decisions/migration-map.md` records the non-trivial mappings. - **#520 startup rewrite** (`docs/handoffs/chicorytv-issue-queue.md`, `docs/README.md`, `CLAUDE.md`, `scripts/select-queue.sh`): two concurrent tracks when no issue named (orientation ‖ `scripts/select-queue.sh 5`), named-issue-skips-selection, the `## Closing record` template, and the **four server-management#642 orientation bullets verbatim** (catalog-first; `Gitea-ErsatzTV` = evidence-not-authority; the **breadcrumb rule** — a file path in a historical comment is a breadcrumb not a live pointer, resolve by concept; catalog→`rg` fallback, MemPalace never authority). Still-valid workflow lore preserved; pre-script selector lore demoted to a clearly-labeled archival section. - **#237 retired as live state**: reduced to an archival line; the decision `docs.queue-state-gitea-tracker` flipped to `status: superseded` and moved to `docs/decisions/archive/startup.md`, superseded by the new active `startup.parallel-orientation` (reciprocal links; rationale preserved verbatim). - **`scripts/check-kickoff-guard.sh`** — blocks any regression to treating #237 as live state; wired into the `decisions lifecycle` CI job (non-vacuity proven: failed on pre-rewrite docs, passes after). - **Two new validator guards** (with non-vacuous tests): archive↔archive reciprocity, and duplicate-metadata-block detection — both caught real defects during this PR. `retrieval-eval.md` excluded from parsing; budget re-baselined to 4800 post-migration. - **`docs/decisions/retrieval-eval.md`** — the active-vs-superseded retrieval benchmark (includes the #390→`ci.runner-placement` and #237→`startup.parallel-orientation` traps). ### Verification (all local, pre-push) - `decisions_validate.py` OK, **0 legacy, 108 active**; `--base origin/main --head HEAD` exit 0; catalog `--check` in sync; `check-kickoff-guard.sh` OK; 31 pytest pass; up to date with origin/main. - **Startup cold-agent sim**: fresh agent went catalog-first, **never read #237** (cited the doc lines), ran `select-queue.sh`, understood the breadcrumb rule. - **Retrieval cold-agent sim**: 6/6 correct active records, zero superseded returned; nailed both active-vs-superseded traps. - **Whole-branch adversarial review** (SOUND-WITH-FIXES → all folded): confirmed the #520 rewrite complete+correct and the #237 supersession lifecycle-correct. ### server-management#642 (MemPalace exporter) On merge I'll post "ready to mine — `decisions lifecycle` green on `<main-sha>`" to #642; its 283-issue export is live + tiered and becomes reachable once this orientation block lands. fixes #520 #521

timothy added 17 commits 2026-07-21 12:09:16 +02:00

docs(520): carry #642 orientation bullets into PR2 plan (from a814dd16) 7bdb83fb16

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

fix(521): reciprocity covers archive<->archive pairs; skip topic-file Contents heading ab2d80b47a

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

feat(521): migrate decisions.md range C: tail #488+/#350/#58/#511 decision records to lifecycle schema [decisions-edit] 97062cc439

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

feat(521): migrate topic-file decision records to lifecycle schema [decisions-edit] 63a6fe80fb

Adds metadata blocks (key/status/since/supersedes/superseded-by + Rule/Signals/Mechanics)
to all 26 legacy-unmigrated ## records across optimistic-concurrency.md (7, concurrency.*),
api-auth-security.md (9, security.*), release-ci-governance.md (7 remaining legacy records,
release.*), and spa-modularization.md (3, spa.*). Heading text and rationale prose are
byte-identical; only metadata was inserted, per the key-table assignments.

security.session-auth-dual-credential (#295 PR1) gets a one-line cross-reference noting it
narrows the OIDC-inert sub-claim of security.blazor-removal-auth-posture (#206), per
orchestrator adjudication — both stay status: active with supersedes/superseded-by: none.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

feat(521): migrate decisions.md range A: through #340 decision records to lifecycle schema [decisions-edit] aae2c418ad

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

feat(521): migrate decisions.md range B: #385 through #502 decision records to lifecycle schema [decisions-edit] 2e34d9c47b

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

merge(521): migrate 4 topic files [decisions-edit] f66c9b5c4b

merge(521): migrate decisions.md range A [decisions-edit] 4d6ab394cd

merge(521): migrate decisions.md range B [decisions-edit] ad814fec40

merge(521): migrate decisions.md range C tail [decisions-edit] dbf842f8fb

feat(521): migrate final 11 scheduling/CI gap records; corpus fully migrated [decisions-edit] 1e79f62402

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs(521): retrieval-eval question bank (active-record selection + citation) c3b2b4d4bd

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

feat(520): parallel orientation+selection startup; retire #237 as live state; #642 retrieval bullets [decisions-edit] 962dc2a31a

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

merge(521): retrieval-eval bank 4a07dd4373

merge(520): parallel-orientation startup + #237 retirement [decisions-edit] 4ac18e06bc

fix(521): de-dup 6 overlapped records; guard duplicate metadata blocks; exclude retrieval-eval; complete eval bank [decisions-edit] fb6720ea27

- Exclude docs/decisions/retrieval-eval.md from active decision parsing
  (_NON_DECISION_FILES); its `## N.` eval-question headings were being
  miscounted as 7 legacy-unmigrated records.
- Add decisions_lib.metadata_line_count() + a decisions_validate guard
  that fails a record with more than one `key:` metadata line, so a
  stacked-metadata-block migration bug (which the parser silently
  tolerated by reading only the first block) can't recur unnoticed.
  TDD: test_duplicate_metadata_block_fails / test_single_metadata_block_passes.
- De-duplicate the 6 docs/decisions.md records left with two stacked
  metadata blocks (scan.getoraddfolder-db-lookup #488,
  scan.musicvideo-reconciliation #494, scan.jellyfin-mixed-content-library
  #489, iptv.logo-drives-bug-preset #67, ffmpeg.qsv-decode-encode-split
  #498, ci.small-lane-git-only server-management#639), merging the union
  of Signals/paths/issues/Mechanics from both blocks and keeping the
  richer Rule wording; rationale prose untouched.
- Fill in the deferred Q6b row in docs/decisions/retrieval-eval.md now
  that startup.parallel-orientation is active in docs/decisions.md,
  scoring it as a real active-vs-superseded question against the
  archived docs.queue-state-gitea-tracker.
- Regenerate docs/decisions/README.md via build_decisions_catalog.py.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

fix(520,521): clear stale migration-map + narrow convention-docs-session-start rule to the task-map protocol [decisions-edit]

Build ErsatzTV Image / CI image pin matches docker/ci (pull_request) Successful in 13s

Details

Build ErsatzTV Image / Docs update reminder (pull_request) Successful in 16s

Details

Build ErsatzTV Image / decisions lifecycle (pull_request) Successful in 37s

Details

Build ErsatzTV Image / API docs in sync (OpenAPI + endpoint index) (pull_request) Successful in 1m22s

Details

Build ErsatzTV Image / Formatting (changed .cs conform to .editorconfig) (pull_request) Successful in 1m20s

Details

Build ErsatzTV Image / Build & test (.NET) (pull_request) Successful in 7m19s

Details

Build ErsatzTV Image / Functional E2E (curl contracts) (pull_request) Successful in 14m47s

Details

Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Successful in 18m22s

Details

Build ErsatzTV Image / Build & push image (amd64) (pull_request) Has been skipped

Details

1b207db87c

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

timothy commented

2026-07-21 12:29:08 +02:00

Review-verdict: MERGEABLE @ 1b207db87c

Independent whole-branch adversarial review (SOUND-WITH-FIXES → all folded) + two cold-agent simulations, all against this head:

Startup sim: fresh agent went catalog-first, ran select-queue.sh, and never read #237 (cited the doc lines) — satisfies #520's cold-agent + no-#237 boxes.
Retrieval sim: 6/6 correct active-record selections, zero superseded returned; passed the #390→ci.runner-placement and #237→startup.parallel-orientation active-vs-superseded traps — satisfies #521's benchmark box.
Whole-branch review: confirmed the #520 startup rewrite complete+correct and the #237 supersession lifecycle-correct; its two SHOULD-FIX findings (stale migration-map header, conflicting session-start rule) folded in 1b207db8.
Local gates: 0 legacy / 108 active, decisions_validate --base origin/main PASS, catalog --check in sync, check-kickoff-guard OK, 31 pytest.

Review-verdict: MERGEABLE @ 1b207db87ce1246f5c46e0d820f94db494153396 Independent whole-branch adversarial review (SOUND-WITH-FIXES → all folded) + two cold-agent simulations, all against this head: - **Startup sim**: fresh agent went catalog-first, ran select-queue.sh, and never read #237 (cited the doc lines) — satisfies #520's cold-agent + no-#237 boxes. - **Retrieval sim**: 6/6 correct active-record selections, zero superseded returned; passed the #390→ci.runner-placement and #237→startup.parallel-orientation active-vs-superseded traps — satisfies #521's benchmark box. - **Whole-branch review**: confirmed the #520 startup rewrite complete+correct and the #237 supersession lifecycle-correct; its two SHOULD-FIX findings (stale migration-map header, conflicting session-start rule) folded in 1b207db8. - Local gates: 0 legacy / 108 active, decisions_validate --base origin/main PASS, catalog --check in sync, check-kickoff-guard OK, 31 pytest.

timothy merged commit 063017584d into main

2026-07-21 12:29:19 +02:00

timothy deleted branch feat/520-521-migration-kickoff

2026-07-21 12:29:19 +02:00

timothy referenced this issue from a commit

2026-07-21 12:29:20 +02:00

Merge pull request 'feat(520,521): full decision-corpus migration + parallel-orientation startup rewrite (PR2 of 2)' (#527) from feat/520-521-migration-kickoff into main

timothy referenced this pull request

2026-07-21 12:30:18 +02:00

Make decision knowledge lifecycle-addressable and retrieval-efficient #521

timothy referenced this pull request

2026-07-21 12:30:20 +02:00