Files
ersatztv/docs
timothy b21cd79d60 fix(803,664): round 2 — the guard-inventory row, two shared-walk fail-opens, and a false measurement
Two independent cold reviews (Codex/GPT-5.6 cross-family, and an isolated Opus reviewer).
Both returned BLOCKED. Every finding below was reproduced before being acted on.

BLOCKER — the new test file had no `docs/guard-inventory.md` row, so
`test_the_inventory_covers_exactly_the_guards_that_exist` failed and took all 22
`test_mutation_harness.py` parametrisations down with it at fixture setup: the whole
`script-tests` CI context was red. Reproduced locally (1 failed, 22 errors). The row is
added, and the hand-maintained summary count with it (21 -> 22 proof files) — that
summary is itself asserted against the table, which is the second half of the same trap.

BLOCKER (Codex), VERIFIED AGAINST THE v1.27.1 SOURCE, not fixed here — the timeline
walk's `null` terminator does not prove exhaustion.
`ListIssueCommentsAndTimeline` applies LIMIT/OFFSET in `FindComments` and filters
AFTERWARDS, dropping `CommentTypeCode` rows and inaccessible xrefs into a NIL slice that
serializes as bare `null`. So a page of inline review comments — which a PR author can
create — reads as the end of the list while later pages still hold events, and rows are
ASCENDING so the events a fence wants are furthest from page 1. This predates #803 and
defeats the BASE fence identically, and closing it is a redesign of a walk both axes
share. Filed as #870 with the source evidence; the fence is now documented as closing the
ABA on a timeline with no such truncating block, NOT the ABA outright. Adding a fourth
overclaiming contract to the change that removed three is the one outcome not acceptable
here.

Two fail-opens in that shared walk, both pre-existing, both fixed:
* an empty ARRAY first page was trusted on ANY page while the `null` arm required
  `page > 1` — so `[]` on page 1 certified "nothing retargeted, nothing pushed" from a
  response the walk cannot explain. The comment three lines above already asserted the
  safe behaviour, so the code contradicted its own stated rule for one of the two empty
  shapes this server produces.
* no row was validated before `.type` was selected on, so a page of rows with no readable
  `.type` certified a zero count. `pr-changed-files.sh` has applied
  validate-what-you-consume to every row it extracts since #643.

FALSE MEASUREMENT — "PR #761 carries five, three of them `true`" is wrong; it is FOUR
true and one false (ids 20485/21341/21450/21452 true, 21451 false). Re-measured and
corrected in both copies.

The self-trigger stall is REFUTED FROM THE SOURCE rather than from my 20-sample margin:
v1.27.1 creates the push comment BEFORE emitting the synchronize notification, so a run
always sees its own causative event. The measurement is kept for the margin and corrected
— `started_at` is a LOWER bound, since the job runs a checkout and several steps before
counting; timed end to end on run 2385 (PR #868) the real margin is 69s, 16.7s of it
in-job. A second, DIFFERENT inversion route is now named: a PR's first push is recorded
~1s after creation and fires no `synchronize`, so an `opened` run landing in that window
would abstain with no successor. Unreachable at 26s+ queue latency; recorded, not fixed.

Three tests were passing for the wrong reason, all found by review, all now mutation-proved:
* the unreadable-head hook test asserted only that SOME `ask` happened, and this fixture
  asks anyway for an unrelated reason — so a mutation reading an unreadable head as
  unchanged left all 107 merge-consent tests green.
* every synthetic `pull_push` row carried `is_force_push: true`, making "every push is
  counted, the boolean is not read" untestable: narrowing the tally to force-pushes passed
  the whole suite. The flag now alternates.
* every fence test terminated on the default `null`, so deleting the head count from the
  empty-ARRAY arm left the head fence silently dead for `[]` timelines. Now parameterised.
And my own `.type` test passed for the wrong reason on first writing — the mode served
untyped rows on every page, running the walk into its page cap, which withholds anyway.

The overclaim sweep was incomplete: grepping the retracted WORDING missed four
paraphrases ("at one head" twice, "bound to ONE head" in the other caller of the same
script, "bound to BOTH the given sha" in a record's machine-readable mechanics line, which
left frontmatter contradicting its own body). The record no longer states a count.

New coverage: cross-page accumulation (the double could not serve a multi-page timeline at
all, so a page-1-only walk passed everything), both terminator shapes, the head arm's
trust guard, and row validation. Mutations verified to redden: delete the head arm (4),
value-not-movement (1), fold the tallies (1), page-1-only walk (3), restore the `[]`
fail-open (1), drop row validation (1), count force-pushes only (2), drop the head count
from the `[]` arm (1), drop the head arm's trust guard (1), and Codex's named hook
mutation (1).

Verification: 1117 passed, 2 skipped; ruff clean; decisions-validate OK; YAML + `bash -n`
clean. No `.cs` touched, so the BOM/format gate does not apply.

Refs #870
Decisions-Edit: yes
2026-08-28 23:22:08 +02:00
..

docs/ — task-signal map

Purpose: route a fresh contributor/agent to the minimal set of docs for the task at hand, instead of a mandatory front-to-back read. Update this doc in the same PR that adds, removes, or retitles a doc below, or that changes which sections a task signal points to.

Start here, always

  • CLAUDE.md (repo root) — project intro: architecture, layout, dev commands, conventions, Task Completion Protocol.
  • docs/contributing.md — established code patterns (CQRS/MediatR, LanguageExt, the ChicoryTV SPA, EF Core dual-provider migrations, FFmpeg pipeline, analyzers, testing). Read before any non-trivial change.

Task signal → minimal sections

Signal Read
Session startup / "what's next" (no issue named) docs/handoffs/chicorytv-issue-queue.md (standing kickoff — two concurrent tracks: orientation ‖ scripts/select-queue.sh 5)
Named-issue pickup Skip queue selection; go straight to focused retrieval — see "Knowledge retrieval" below, then the issue body
Adding/changing a /api/* endpoint docs/api-conventions.md checklist + docs/endpoint-index.md
Adding a ChicoryTV SPA screen docs/spa-conventions.md
Explaining a consequential settings field in the SPA (summary → hover/tap panel → docs link) docs/spa-conventions.md §15 — use the shared FieldHelp trigger and put the copy in the screen's own FIELD_HELP record; the icon, the gesture and the a11y contract are fixed
Graphics element / overlay work (text bug, On Now / Next, watermark-vs-[vge]) docs/graphics-elements.md, then decisions catalog rows keyed graphics.*
Scheduling / playout engine work docs/domain-model.md + decisions catalog rows keyed sched.* (docs/decisions/README.md)
Adding or changing a paged list handler (a page plus a TotalCount) Resolve api.paged-count-matches-page-query via docs/decisions/README.md — for an EF-backed filtered list, count the SAME query you page, with includes appended to the page chain only; where the count and the page are separate methods, a test pins their agreement. Then api.paging-zero-based for the pageNum/pageSize contract
Concurrency / optimistic-locking work docs/api-conventions.md §7a/b/c + docs/decisions/optimistic-concurrency.md
Auth / security-surface work docs/decisions/api-auth-security.md
CI / release pipeline work docs/ci-cd.md + docs/decisions/release-ci-governance.md
Proposing a new guard / CI check / regression test convention docs/defect-shapes-773.md §4 (detector menu + the classes where no detector is plausible), then the rules every guard must satisfy: docs/decisions/records/testing/guard-derives-population-from-source.md, …/guard-ships-with-mutation-proof.md and …/mutation-claims-are-executed.md (a MUTATION grade carries a DECLARED clause mutation that is re-run every suite) — plus …/verification-code-needs-its-own-proof.md, which extends the same obligation BEYOND guards to the harness, wrapper or checker doing the checking, and says where its proof lives when the checker holds no row
Adding or bounding a consequential numeric config field (an FFmpeg profile tunable, a pipeline knob) docs/api-conventions.md §3d — reject out of range with a 422 naming the bound and its consequence, never accept-then-rewrite; validate against the constants the renderer reads, keep the render-time clamp for pre-existing rows, and let an UNCHANGED legacy value through on update. Then api.ffmpeg-profile-numeric-bounds
Testing a surface gated by config / an env var / a credential docs/decisions/records/testing/deny-path-at-production-config-value.md — cover the setting absent, at its production value, and each opt-out, and assert the DENY branch
Touching a full-replace write path or a hand-built request object docs/decisions/records/testing/full-replace-asserts-field-list.md — derive the field list from the DTO and assert set equality; reconcile by id where child state exists. In the SPA the same rule is enforced by the type system: docs/spa-conventions.md §4b — build the body as Complete<T>, annotating BOTH the wrapper parameter and every construction site
Writing or editing any doc, or answering a review finding in prose docs/decisions/records/docs/no-session-narrative.md — the doc records the END STATE; the path to it goes in the commit message. Apply the who-benefits test, and read the carve-out before you cut (dated measurements, stated snapshot boundaries and tested-and-rejected results stay)
Adding, renaming or removing a workflow JOB docs/ci-cd.md → "Per-job declarations" — every job declares env.CI_JOB_ROLE (and, in docker-build.yml, env.CI_EXECUTION_CLASS); a missing or unknown value fails scripts/tests/test_workflow_job_guards.py / …/test_ci_image_pin_population.py, and a guard or report-only job also needs a row in docs/guard-inventory.md → "Workflow-job guards". Rationale: docs/decisions/records/testing/workflow-declares-its-own-job-metadata.md
Adding / changing / deleting a guard file docs/guard-inventory.md — every guard's row is machine-checked by scripts/tests/test_guard_inventory.py, so a new guard must acquire a row before the suite goes green, and a row graded MUTATION must also acquire a declared clause in scripts/tests/mutation_manifest.py
Writing code that reads live Gitea/remote state and then acts on it docs/decisions/records/process/check-and-use-pins-a-version.md, then docs/remote-state-inventory.md — a new executable under scripts/ (excluding scripts/tests/), .claude/hooks/, .husky/ or .gitea/workflows/ must acquire a row there before scripts/tests/test_remote_state_inventory.py goes green
Finding every site that references a symbol (multi-site fix/sweep) docs/local-lsp-tooling.md — which of the three surfaces answers, and why a delegated agent must be pointed at an MCP server (csharp-lsp, or serena after an activate_project) rather than the LSP tool, which no subagent has been observed to reach
Live local run / Playwright-MCP verification docs/e2e-local.md + scripts/e2e-local.sh
Adding/changing a UI-E2E browser flow docs/e2e-local.md → "UI-E2E harness" + scripts/e2e-ui.sh
What does a test suite cover docs/testing.md
Legacy Blazor route lookup docs/blazor-route-parity.md (historical #91 phase (b) inventory)
"Why do we do X this way" / challenging a convention Catalog-first: docs/decisions/README.md (active rows) → follow the row's link to docs/decisions/records/<area>/<topic>.md for full rationale. docs/decisions/archive/<area>/ only for "what did the rule used to be."

Knowledge retrieval (MemPalace + catalog + Gitea)

These four rules are the seam agreed with server-management#642 (the Gitea→MemPalace exporter). They apply whether the question comes up via MemPalace, a grep, or a stale comment:

  1. Current conventions/decisions → catalog-first. Start at docs/decisions/README.md; discover via the ErsatzTV-Decisions wing (active) / ErsatzTV-Decisions-Archive (superseded/retired). Resolve by topic/key, never by chasing a file path.
  2. Issue history → evidence, not authority. The Gitea-ErsatzTV wing is historical narrative that may be stale; it never overrides current Markdown.
  3. The breadcrumb rule (the crux behavior change). A file path named inside a historical issue comment (e.g. "grep docs/decisions.md 2026-07-17", "see …") is a breadcrumb, not a live pointer. Find the current rule via the catalog / active wing by concept; do not treat the named path as current. (Why it's safe: still-current → in the active wing, breadcrumb resolves; superseded → the active wing returns the successor and a literal follow lands on a record that announces its own status: superseded; retired → the active wing returns nothing, which is itself the signal. The validator-enforced move-to-archive/ is what prevents the catastrophic "superseded rule read as current" case.)
  4. Fallback when MemPalace is stale/down: docs/decisions/README.md catalog, then rg '^`key: <dotted.key>`' docs/decisions/. MemPalace is never authority nor sole fallback.

MemPalace is candidate discovery only — every passage is verified against its cited Markdown/Gitea source before use. Never derive live queue state from MemPalace, #237, or historical comments; queue state is live Gitea state, retrieved via scripts/select-queue.sh (see docs/handoffs/chicorytv-issue-queue.md). Full retrieval contract (altitude/precedence, staleness bounds, what's mined per issue): docs/handoffs/chicorytv-issue-queue.md → "Knowledge retrieval".

Also present in docs/

  • docs/domain-model.md — what the app IS: entity glossary, channel→playout→schedule/block concept map, where each concept is edited in the SPA.
  • docs/api-conventions.md — checklist for adding/changing a /api/* endpoint (controllers, DTOs, error mapping, auth, OpenAPI regen, tests).
  • docs/spa-conventions.md — playbook for adding a screen to the ChicoryTV React SPA.
  • docs/e2e-local.md (+ scripts/e2e-local.sh) — how to run a live local instance for manual or Playwright-MCP verification.
  • docs/local-lsp-tooling.md — the code-intelligence surfaces (the LSP tool's three servers, the csharp-lsp MCP server, and serena): how each is configured, which ones a subagent can actually reach, the traps (a cold server answers the first query with a confidently partial result; serena needs an activate_project per directory), and scripts/check-local-lsp.sh to verify the preconditions. Read before briefing an agent to find every site referencing a symbol.
  • docs/testing.md — testing map: what each *.Tests project / web suite covers, golden-file nets, the timezone-independence rule, how to run subsets, the per-PR verification gate.
  • docs/blazor-route-parity.md — historical record of the completed #91 phase (b) cutover: the Blazor Server UI is removed and every legacy route now 302-redirects to its SPA equivalent (or falls through to the catch-all → /app). Read it for the full legacy→SPA route inventory.
  • docs/decisions/records/<area>/<topic>.md — one active decision record per file, YAML frontmatter (key/title/status/since/supersedes/superseded-by, plus optional stale-after/sources — ersatztv#603), rationale prose in the body. The filename is the key, so one-active-record-per-key is a filesystem property (ersatztv#610). docs/decisions.md and the topic files remain as the lifecycle-schema narrative plus a "Records formerly in this file" index, which is what keeps older date-based pointers resolvable. Generated active view: docs/decisions/README.md (catalog / task router) — start there. Superseded/retired records live in docs/decisions/archive/ and are read only for history, never for "what is the current rule."
  • docs/ci-cd.md — build/test/release pipeline, versioning, dependency management.
  • docs/rest-api.md — REST API design doc for ersatztv#2 (goals, conventions, per-slice plan). Largely superseded day-to-day by docs/api-conventions.md; read this for the original rationale.
  • docs/mcp.md — the ErsatzTV.Mcp stdio JSON-RPC MCP server (#58): how it wraps /api/v1 as read + cautious-write tools, its config/env vars, auth, security posture, and the tool catalog.
  • docs/graphics-elements.md — graphics element (overlay) schema reference: how elements are discovered and attached, the YAML parsing traps (an unknown key disables the element outright), the full text-element field table including the #732 background box, and why [vge] in a filter graph does not imply a graphics element is bound.
  • docs/channels.md — Channel entity field reference.
  • docs/m3u-xmltv.md — M3U/XMLTV generation overview (ChannelPlaylist, GetChannelGuideHandler).
  • docs/fork-strategy.md — divergence policy vs upstream ErsatzTV.
  • docs/design-sync.md — Claude Design ↔ repo screen workflow (#92).
  • docs/endpoint-index.md — generated REST endpoint index (method/path/operationId/summary per OpenAPI tag). Do not edit by hand; regenerated by scripts/generate-endpoint-index.py / scripts/update-openapi.sh.
  • docs/handoffs/chicorytv-issue-queue.md — static session kickoff prompt + workflow lore. Queue state is live Gitea state, retrieved each session via scripts/select-queue.sh — see that file's standing kickoff for the two concurrent tracks (orientation ‖ selection). ersatztv#237 is a closed, archival historical tracker (superseded by startup.parallel-orientation in docs/decisions.md) — not a live pointer.
  • docs/defect-shapes-773.md — root-cause analysis of the recurring defect shapes across the whole closed-issue corpus (#773): the measured class ranking, the four families they consolidate into, the cheapest mechanical detector per class, the classes where no detector is plausible, and an audit of which configured hooks/MCP servers/LSPs are actually invoked. Read it before proposing a new guard or CI check — §4 is the detector menu, and it argues against enumerating cases one incident at a time.
  • docs/remote-state-inventory.md — every executable in scripts/ (excluding scripts/tests/), .claude/hooks/, .husky/ and .gitea/workflows/ that reads live remote state and acts on that read, classified PINNED / CAS / UNSAFE-KNOWN / N/A with the window and what bounds it. Code outside those directories — C#/TypeScript guards, web/, and the test suites themselves — is out of scope, and the doc states that rather than implying coverage. The population is derived from git ls-files and compared for set equality by scripts/tests/test_remote_state_inventory.py, so a new script that talks to a remote service cannot ship unclassified. Read it with process.check-and-use-pins-a-version; it is that record's detector, since the class has no plausible linter (docs/defect-shapes-773.md §4 detector D).
  • docs/guard-inventory.md — every executable guard file, what it blocks, whether it is a GUARD or TOOLING, and whether it ships a mutation proof (MUTATION / BEHAVIOUR-ONLY / NONE) with a file::function ref. The population is derived from the filesystem and the workflow/hook call sites and compared for set equality by scripts/tests/test_guard_inventory.py, so a new guard cannot ship unclassified and a renamed test cannot leave a row claiming coverage it has lost. Guards implemented inline in workflow YAML are deliberately outside that population — the doc states the limit rather than implying coverage.
  • docs/tracker-retrofit-triage-237.md — audit trail for the #524 triage of ersatztv#237's 111 comments (method, per-comment classification, totals). Evidence for the docs.tracker-comment-retrofit decision; read it only when triaging another over-cap tracker.
  • docs/handoffs/rest-api.md — original handoff prompt for kicking off the REST API work (#2).