feat(603): adopt OKF's optional stale-after and Sources: decision-record metadata #605

Merged
timothy merged 4 commits from worktree-603-decisions-stale-after-sources into main 2026-07-25 16:16:00 +02:00
11 changed files with 323 additions and 4 deletions
+2 -1
View File
@@ -73,7 +73,8 @@ bounds, what's mined per issue): `docs/handoffs/chicorytv-issue-queue.md` → "K
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.md`** + **`docs/decisions/*.md`** — active decision records (lifecycle schema:
key/status/since/supersedes/superseded-by). **Generated active view**: `docs/decisions/README.md`
key/status/since/supersedes/superseded-by, plus optional `stale-after`/`Sources:` —
ersatztv#603). **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.
+52 -2
View File
@@ -29,6 +29,16 @@ one of:
(An H2 with no metadata block is `legacy-unmigrated` — not yet ported to this schema. The validator
tolerates these and reports a count; they trend to zero over time, not required to hit zero at once.)
**Two optional fields (ersatztv#603).** `` `stale-after: YYYY-MM-DD` `` on the metadata line marks a
record that asserts a fact about the *outside world* as due for re-confirmation once that date
passes — an absolute date, no TTL. A **`Sources:`** line in the metadata block cites the evidence the
record rests on (a CI run, a measurement, a log line), as distinct from `Signals:`, which is recall
keywords. Both are optional and never required; a malformed `stale-after` is a blocking error (it
would silently never fire), but a *past-due* record is only a non-blocking notice — going stale is
the passage of time, not a defect in whatever commit happens to be under test. Dated records are
listed in the catalog's **Review due** section, which renders the date only and never a
clock-derived verdict.
**Supersession is same-PR, not a later consolidation pass**: add the new active record, then relocate
the predecessor's file (or section) into `docs/decisions/archive/` with the metadata above rewritten
to `status: superseded` (or `retired`) and the reciprocal `supersedes`/`superseded-by` links filled
@@ -1479,10 +1489,11 @@ weights) and SPA child #386 remain open under the #383 milestone.
---
## 2026-07-17 — No persistent compiler servers in CI; every `services:` container gets an explicit cap; #390's small-lane move reversed (#406)
`key: ci.runner-placement` · `status: active` · `since: 2026-07-17` · `supersedes: none` · `superseded-by: none`
`key: ci.runner-placement` · `status: active` · `since: 2026-07-17` · `supersedes: none` · `superseded-by: none` · `stale-after: 2027-01-15`
**Rule:** No persistent Roslyn compiler server survives a CI build (`UseSharedCompilation=false` etc., runner env + Dockerfile `ENV`); every `services:` container gets its own explicit `--memory`/`--memory-swap`/`--cpus` cap (it does not inherit the job container's).
**Signals:** CI memory/swap thrash · paths: `.gitea/workflows/*.yml`, `docker/Dockerfile` · issues: #406, #390 (prose-reversed, no standalone record), server-management#604, server-management#570
**Mechanics:** `docs/ci-cd.md` → CI build memory; `scripts/ci-peak-anon.sh`
**Sources:** the 2026-07-17 bumblebee incident — load 340, 21 GiB swapped, ~238 MiB free, prod down until reboot (server-management#604) · host sizing at the time: 25 GiB / 12 cores
Three CI changes, all downstream of one incident: on 2026-07-17 bumblebee (the **prod media** Docker
host, 25 GiB / 12 cores) hit load **340** with **21 GiB swapped** and ~238 MiB free, taking prod
@@ -2291,10 +2302,11 @@ The blocking `format` CI job (and the matching Husky pre-commit hook) verify cha
server-management capacity call — deliberately out of scope here.
## 2026-07-19 — CI `test` job reports a sampled true peak-anon, not cache-inflated `memory.peak` (#412)
`key: ci.peak-anon-measurement` · `status: active` · `since: 2026-07-19` · `supersedes: none` · `superseded-by: none`
`key: ci.peak-anon-measurement` · `status: active` · `since: 2026-07-19` · `supersedes: none` · `superseded-by: none` · `stale-after: 2027-03-15`
**Rule:** The `test` job's headline memory figure is a sampled high-water mark of cgroup `anon`, produced by `scripts/ci-peak-anon.sh`; `memory.peak` and the end-of-job `anon`/`file` split are kept only as a cache-inflated reference.
**Signals:** CI memory measurement · paths: `scripts/ci-peak-anon.sh`, `.gitea/workflows/*.yml` · issues: #412, #411 (prose-only predecessor, no standalone record — its `memory.peak`-headline approach is superseded by this record)
**Mechanics:** `scripts/ci-peak-anon.sh` header; `docs/ci-cd.md` → CI build memory
**Sources:** `scripts/ci-peak-anon.sh` (the sampler itself) · cgroup v2 `memory.peak` vs `memory.stat` `anon` accounting, measured on the bumblebee runners #412
**Decision.** The `test` job's memory instrument (added in #411) now reports a **sampled high-water
mark of the cgroup's `anon` memory** as the headline figure, produced by `scripts/ci-peak-anon.sh`
@@ -3727,3 +3739,41 @@ ownership instead of proving it. (b) Re-raise signals, so a cancelled run cannot
`if ! cmd; then status=$?` — under `!` bash sets `$?` to the logical negation, so it reads 0 and a
FAILING run exits 0, silently passing CI. (d) `exec` the app inside the backgrounded subshell, or `$!`
is the SUBSHELL on bash 3.2 (stock macOS) and every PID-based kill targets the wrong process.
## 2026-07-25 — OKF evaluated and rejected as a replacement; two of its optional fields adopted (#603)
`key: docs.decision-optional-provenance` · `status: active` · `since: 2026-07-25` · `supersedes: none` · `superseded-by: none`
**Rule:** Decision records gain two OPTIONAL fields — `stale-after: YYYY-MM-DD` on the metadata line and a `**Sources:**` line in the metadata block; the Open Knowledge Format (OKF) itself is NOT adopted as the record format.
**Signals:** OKF, Open Knowledge Format, knowledge-catalog, okf-skills, stale-after, staleness, Sources, provenance, re-confirmation, review due · paths: scripts/decisions_lib.py scripts/decisions_validate.py scripts/build_decisions_catalog.py · issues: #603
**Mechanics:** docs/decisions.md → header schema; docs/decisions/README.md → Review due
**Sources:** https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf (SPEC.md v0.2) · https://github.com/scaccogatto/okf-skills
**OKF is not a replacement for this system, and the reason is structural, not stylistic.** Its
conformance rules are deliberately permissive exactly where ours are deliberately strict: a consumer
MUST NOT reject a bundle for broken cross-links, unknown `type` values, or missing optional fields,
and its `status: deprecated` is a bare flag with nothing pointing at the successor. The single
catastrophic failure this corpus exists to prevent is *a superseded rule read as current*, and what
prevents it is the validator — one active record per key, reciprocal `supersedes`/`superseded-by`,
no record vanishing from the active set without an archive copy, catalog-drift detection. OKF has no
equivalent of any of those. It also has no `key`: its stable identity is the file *path*, which is
precisely what the breadcrumb rule tells agents not to trust. Adopting it would additionally mean a
second ingestion format alongside MemPalace for the same corpus.
**What it does have that we lacked is lifecycle and provenance metadata.** Records that encode
measured facts about hosts, runners or upstream behavior drift silently — nothing marked them due for
re-confirmation. `stale-after` fixes that, and `Sources:` gives the *evidence* a record rests on a
home other than buried prose. Both are additive: no format migration, and nothing changes for a
record that adopts neither. Adopt them opportunistically, on records that actually assert an external
fact — the three seeded here (`ci.runner-placement`, `ci.infra-shaped-red-under-load`,
`ci.peak-anon-measurement`) are the ones encoding measured host behavior, with dates staggered so
they don't all come due in the same week.
**The staleness check is non-blocking, and the generated catalog is clock-free — both on purpose.**
A calendar date turning an unrelated PR red, or silently drifting `docs/decisions/README.md` into a
`--check` failure with no commit touching the corpus, is a self-inflicted CI outage. So evaluating
`today >= stale-after` lives only on the validator's `::notice::` path, and the catalog's Review-due
section renders the date itself, never a stale/fresh verdict.
**OKF's `verified: {by, at}` trust tiers were considered and deferred**, not rejected. Given how
much of this corpus is agent-authored, distinguishing agent-inferred from human-confirmed-after-
measuring is real signal; it just needs its own actor convention and wasn't worth coupling to this
change.
+13
View File
@@ -62,6 +62,7 @@ the link for rationale. Superseded/retired history lives in `archive/`. Regenera
| `concurrency.schedule-item-child-identity` | `PUT /api/schedules/{id}/items` reconciles by an optional round-tripped child `Id` (null/absent/0 ⇒ new item), never by array position, so fill-group/shuffle state follows the logical item across reorders; an unknown or duplicate id is rejected 422 (checked after the §7a `CheckVersion`, so 412 precedes 422). | 2026-07-11 | [link](optimistic-concurrency.md#2026-07-11--stable-child-identity-for-schedule-item-replace-259-split-from-252253) |
| `docs.convention-docs-session-start` | Docs-first, not source-first: conventions (api-conventions, spa-conventions, e2e-local, blazor-route-parity, domain-model, decisions, README) are read from docs, not reverse-engineered from code, via `docs/README.md`'s task-signal map — only the sections it points to for the task at hand, not the whole set. Each doc is updated in the same PR that changes what it documents, replacing deferred/follow-up doc updates. | 2026-07-07 | [link](../decisions.md#2026-07-07--convention-docs-read-at-session-start-updated-in-pr) |
| `docs.decision-lifecycle` | every decision `##` record (active or archived) carries a 5-field metadata block (`key`, `status`, `since`, `supersedes`, `superseded-by`) checked by `scripts/decisions_validate.py`; a record is never deleted or line-edited to reverse a call — it is moved to `docs/decisions/archive/` with `status: superseded`/`retired` and a reciprocal `superseded-by`/`supersedes` key pair to its replacement. | 2026-07-21 | [link](../decisions.md#2026-07-21--decision-records-carry-a-lifecycle-schema-validated-by-a-script-append-only-by-diff-is-retired-521) |
| `docs.decision-optional-provenance` | Decision records gain two OPTIONAL fields — `stale-after: YYYY-MM-DD` on the metadata line and a `**Sources:**` line in the metadata block; the Open Knowledge Format (OKF) itself is NOT adopted as the record format. | 2026-07-25 | [link](../decisions.md#2026-07-25--okf-evaluated-and-rejected-as-a-replacement-two-of-its-optional-fields-adopted-603) |
| `docs.tracker-comment-retrofit` | When the knowledge exporter flags an over-cap tracker issue and excludes it from ingestion, triage its comments instead of assuming a retrofit is owed — and for each decision-shaped item check the **worked issue first**, because a tracker session comment is by construction a précis of the fuller closing record posted on the issue it narrates. Applied to #237 (111 comments) this yielded **zero** records, so server-management#642's "a fact found only in a #237 comment" retrieval row has no valid subject and its interim target (an already-migrated record) is permanent. | 2026-07-21 | [link](../decisions.md#2026-07-21--check-the-worked-issue-before-the-decision-corpus-a-closed-trackers-comments-need-no-retrofit-524) |
| `ffmpeg.external-logo-graphics-engine` | External-URL channel logos pass through to the graphics engine like any other watermark source; `WatermarkSelector` must never gate them on `File.Exists` (always false for a URL) and never route them through the ffmpeg-native overlay shortcut. | 2026-07-20 | [link](../decisions.md#2026-07-20--external-url-channel-logos-pass-through-to-the-graphics-engine-never-fileexists-gated-never-ffmpeg-native-502) |
| `ffmpeg.hls-cold-start-burst` | HLS cold-start latency is fixed with a bounded `-readrate_initial_burst` (gated on FFmpeg ≥6.1 capability detection), not by raising `work_ahead_limit`, which would remove the concurrency guarantee it exists for. | 2026-07-20 | [link](../decisions.md#2026-07-20--hls-cold-start-is-fixed-with--readrate_initial_burst-not-by-raising-the-work-ahead-limit-350) |
@@ -168,3 +169,15 @@ the link for rationale. Superseded/retired history lives in `archive/`. Regenera
| `testing.playwright-mcp-download-and-recovery` | In Playwright-MCP E2E, fetch file-download endpoints with curl — never a browser tab or `window.open` — and if browser tools stall repeatedly, `pkill -f ms-playwright-mcp` and drive a fresh session. | 2026-07-21 | [link](workflow-process.md#2026-07-21--playwright-mcp-curl-download-endpoints-never-open-a-tab-or-windowopen-542) |
| `testing.scripted-playout-golden-deferred` | The `PlayoutBuildGoldenTests` in-memory golden net covers Sequential (YAML) as of #381. Scripted's *end-to-end pipeline* is excluded — `ScriptedPlayoutBuilder` runs a user-authored external program that drives the engine over HTTP loopback, which the in-memory harness can't pin — so that full-pipeline (integration) harness is deferred to #563. But the scheduling *behavior* those scripts drive lives entirely in the in-process `SchedulingEngine` (the `ScriptedScheduleController` is a 1:1 pass-through to it), which IS directly unit/golden-testable; the earlier "Scripted is un-golden-able by construction" framing overstated the constraint by conflating transport with engine. #395 extracts that shared switch to `ContentEnumeratorBuilder` and adds a direct regression net (`ContentEnumeratorBuilderTests`) over it. | 2026-07-22 | [link](../decisions.md#2026-07-22--sequential-yaml-playout-gets-a-golden-scripted-is-excluded-from-the-golden-net-by-construction-381) |
| `testing.troubleshoot-path-cannot-test-branding` | Verify logo/watermark/bug changes through a real channel playout — a green troubleshoot run proves nothing about branding. | 2026-07-21 | [link](workflow-process.md#2026-07-21--channel-branding-is-not-testable-through-the-troubleshooting-playback-api-542) |
## Review due
Active records that assert facts about the outside world and carry a `stale-after` date.
Once that date passes, re-confirm the fact and either extend the date or supersede the
record. Sorted soonest-first.
| Stale after | Key | Record |
| --- | --- | --- |
| 2027-01-15 | `ci.runner-placement` | [link](../decisions.md#2026-07-17--no-persistent-compiler-servers-in-ci-every-services-container-gets-an-explicit-cap-390s-small-lane-move-reversed-406) |
| 2027-02-15 | `ci.infra-shaped-red-under-load` | [link](workflow-process.md#2026-07-21--an-infra-shaped-red-under-host-load-is-not-a-code-failure-542) |
| 2027-03-15 | `ci.peak-anon-measurement` | [link](../decisions.md#2026-07-19--ci-test-job-reports-a-sampled-true-peak-anon-not-cache-inflated-memorypeak-412) |
+2 -1
View File
@@ -56,10 +56,11 @@ next session debugging a phantom. Split the two counts explicitly.
## 2026-07-21 — An infra-shaped red under host load is not a code failure (#542)
`key: ci.infra-shaped-red-under-load` · `status: active` · `since: 2026-07-21` · `supersedes: none` · `superseded-by: none`
`key: ci.infra-shaped-red-under-load` · `status: active` · `since: 2026-07-21` · `supersedes: none` · `superseded-by: none` · `stale-after: 2027-02-15`
**Rule:** When a job dies inside a setup/cache step before your code compiles, check the runner host's load before diagnosing the diff, and never file a CI bug off one sample under pressure.
**Signals:** load average 243 · `Setup .NET` 11ms failure · `remove /root/.cache/act/…/.gitignore: no such file or directory` · buildx `DeadlineExceeded: failed to compute cache key` · `Build & push image` · `EF migration integrity` · `FactoryServer-L` game server · phantom CI bug · paths: n/a · issues: #542
**Mechanics:** `uptime` on the runner host (bumblebee); Gitea Actions job step logs.
**Sources:** 2026-07-17, bumblebee at load average 243 — `EF migration integrity` dead in ~11ms inside `Setup .NET`, main's `Build & push image` dead on buildx `DeadlineExceeded`; both green on re-run at normal load (#542)
On 2026-07-17, with bumblebee at load average **243**, two unrelated jobs died in ways that look like
code bugs but weren't: `EF migration integrity` failed in ~11ms inside **`Setup .NET`** with
+20
View File
@@ -62,6 +62,26 @@ def render_catalog(records) -> str:
rule = (r.rule or "").replace("|", "\\|")
lines.append(f"| `{r.key}` | {rule} | {r.since or ''} | [link]({_rel(r)}) |")
lines.append("")
# Review-due section (ersatztv#603). Renders the DATE only — never "today", never a computed
# stale/fresh verdict. This file is checked with --check in CI, so anything time-dependent here
# would drift it red on a calendar boundary with no commit touching the corpus. Evaluating
# today >= stale-after is the validator's job, on its non-blocking notice path.
due = sorted([r for r in active if r.stale_after], key=lambda r: (r.stale_after or "", r.key or ""))
if due:
lines += [
"## Review due",
"",
"Active records that assert facts about the outside world and carry a `stale-after` date.",
"Once that date passes, re-confirm the fact and either extend the date or supersede the",
"record. Sorted soonest-first.",
"",
"| Stale after | Key | Record |",
"| --- | --- | --- |",
]
for r in due:
lines.append(f"| {r.stale_after} | `{r.key}` | [link]({_rel(r)}) |")
lines.append("")
return "\n".join(lines)
+15
View File
@@ -12,6 +12,10 @@ block as its first non-blank content:
<rationale prose …>
An H2 with no metadata line is treated as status `legacy-unmigrated` (migration target).
Two OPTIONAL fields (ersatztv#603, adopted from OKF v0.2's lifecycle/provenance families) may also
appear — `stale-after: YYYY-MM-DD` on the metadata line, and a `**Sources:**` line in the metadata
block. Absence is never an error; see decisions_validate for how they are checked.
"""
from __future__ import annotations
@@ -44,6 +48,10 @@ class Record:
rule: str | None = None
signals: str | None = None
mechanics: str | None = None
# Optional (ersatztv#603). `stale_after` is an absolute date, no TTL — the record is due for
# re-confirmation once today >= it. `sources` cites the evidence the record rests on.
stale_after: str | None = None
sources: str | None = None
body: str = ""
@@ -76,6 +84,11 @@ def parse_text(text: str, source: Path) -> list[Record]:
rec.since = meta.get("since") or None
rec.supersedes = meta.get("supersedes") or None
rec.superseded_by = meta.get("superseded-by") or None
# NOT `or None`: a present-but-empty `stale-after:` must stay "" so the validator can
# tell it from an absent field and reject it. Collapsing the two would let a blank or
# truncated value through as "absent" — a field that silently never fires, which is
# exactly what the blocking format check exists to prevent.
rec.stale_after = meta.get("stale-after")
# The metadata block is contiguous: scan only until the first blank line, so a
# bolded **Rule:** appearing later inside rationale prose can't overwrite the real one.
for bl2 in body_lines[k + 1 :]:
@@ -87,6 +100,8 @@ def parse_text(text: str, source: Path) -> list[Record]:
rec.signals = bl2[len("**Signals:**") :].strip()
elif bl2.startswith("**Mechanics:**"):
rec.mechanics = bl2[len("**Mechanics:**") :].strip()
elif bl2.startswith("**Sources:**"):
rec.sources = bl2[len("**Sources:**") :].strip()
break
rec.body = "\n".join(body_lines).strip()
records.append(rec)
+59
View File
@@ -11,8 +11,10 @@ parse issues), matching the old guard.
from __future__ import annotations
import argparse
import re
import subprocess
import sys
from datetime import date
from pathlib import Path
import scripts.decisions_lib as dl # noqa: E402 (run with PYTHONPATH=. or as module)
@@ -26,6 +28,46 @@ REQUIRED_META = ("key", "status", "since", "supersedes", "superseded_by", "signa
EDIT_TOKEN = "[decisions-edit]" # noqa: S105 (a commit-message marker, not a credential)
# `date.fromisoformat` is NOT a YYYY-MM-DD validator: on Python >= 3.11 it also accepts ISO basic
# format ("20270101") and week dates ("2027-W01-1"), and which of those parse depends on the
# interpreter version — so the same corpus could validate differently on a dev machine and on the
# runner (pr-checks.yml pins only `python-version: '3.x'`). Gate on the extended calendar form first.
# The catalog's Review-due section additionally sorts on the raw STRING, which is only equivalent to
# sorting by date because this regex forces a fixed-width zero-padded form.
_STALE_AFTER_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
def _parse_stale_after(value: str | None) -> date | None:
"""`stale-after` as a date, or None if absent, empty, or malformed.
Callers must NOT use a None return to mean "absent" — an empty or malformed value returns None
too. Distinguish on the raw field with `is not None` (absent stays None; present-but-empty is "").
"""
if not value or not _STALE_AFTER_RE.match(value.strip()):
return None
try:
return date.fromisoformat(value.strip())
except ValueError:
return None # e.g. 2027-02-30 — well-shaped but not a real date
def stale_records(records, today: date) -> list[tuple[str, str]]:
"""(heading, stale-after) for ACTIVE records that are past due — today >= stale-after.
OKF v0.2 semantics: an absolute date, no TTL. Deliberately NOT part of `validate()` — a record
going stale is the passage of time, not a defect in the commit under test, so it must never fail
a PR that didn't touch it. main() reports these as a non-blocking notice.
"""
out = []
for r in records:
if r.status != "active":
continue
d = _parse_stale_after(r.stale_after)
if d is not None and today >= d:
out.append((r.heading, r.stale_after))
return sorted(out)
def _key_of(ref: str | None) -> str | None:
if not ref or ref == "none":
return None
@@ -59,6 +101,10 @@ def validate(
for f in REQUIRED_META:
if getattr(r, f) in (None, ""):
errs.append(f"{r.heading}: missing required metadata {f}")
# `stale-after` is OPTIONAL, but a malformed one is a defect in the commit that wrote it —
# it would silently never fire. Absent is fine; unparseable is not.
if r.stale_after is not None and _parse_stale_after(r.stale_after) is None:
errs.append(f"{r.heading}: stale-after {r.stale_after!r} is not a YYYY-MM-DD date")
if r.status == "active":
active_by_key[r.key] = active_by_key.get(r.key, 0) + 1
if r.status in ("superseded", "retired"):
@@ -72,6 +118,10 @@ def validate(
for r in archive_records:
if r.status == "active":
errs.append(f"{r.heading}: active record must not live under docs/decisions/archive/")
# An archived record's staleness is moot, but a malformed date there is still a typo worth
# catching — and checking both wings keeps the field's contract symmetric.
if r.stale_after is not None and _parse_stale_after(r.stale_after) is None:
errs.append(f"{r.heading}: stale-after {r.stale_after!r} is not a YYYY-MM-DD date")
for key, n in active_by_key.items():
if n > 1:
@@ -328,6 +378,15 @@ def main(argv=None) -> int:
file=sys.stderr,
)
stale = stale_records(records, date.today())
if stale:
listed = "; ".join(f"{h} (stale-after {d})" for h, d in stale)
print(
f"::notice::decisions-validate: {len(stale)} active record(s) past their stale-after date "
f"— re-confirm or extend: {listed}",
file=sys.stderr,
)
unmigrated = [r for r in records if r.status == "legacy-unmigrated" and r.heading not in SKIP_HEADINGS]
if unmigrated:
print(f"::notice::{len(unmigrated)} legacy-unmigrated decision record(s) remain (must trend to 0).")
+9
View File
@@ -11,5 +11,14 @@
Rationale prose here.
## 2026-07-19 — Optional stale-after / Sources example (#603)
`key: ci.peak-anon-measurement` · `status: active` · `since: 2026-07-19` · `supersedes: none` · `superseded-by: none` · `stale-after: 2027-01-15`
**Rule:** The test job reports a sampled true peak anon.
**Signals:** ci, memory · paths: scripts/ci-peak-anon.sh · issues: #412
**Mechanics:** docs/ci-cd.md → CI lanes
**Sources:** gitea run 4471 (measured) · scripts/ci-peak-anon.sh
Rationale prose here.
## 2026-07-11 — Legacy unmigrated example (#231)
Some prose with no metadata line at all.
+57
View File
@@ -1,4 +1,5 @@
from pathlib import Path
from typing import Any
import scripts.build_decisions_catalog as bc
import scripts.decisions_lib as dl
@@ -49,3 +50,59 @@ def test_anchor_matches_gitea_double_hyphen_slug():
b = bc._anchor("2026-07-16 — Optional advertised IPTV base URL (`iptv.base_url`)…")
assert "iptvbase_url" in b
def _r(key: str, **kw: Any) -> dl.Record:
base: dict[str, Any] = dict(
heading=f"H {key}",
source=Path("decisions.md"),
lineno=1,
key=key,
status="active",
rule="r",
)
base.update(kw)
return dl.Record(**base)
def test_review_due_section_lists_dated_records_soonest_first():
out = bc.render_catalog(
[
_r("b.later", stale_after="2027-03-01"),
_r("a.sooner", stale_after="2026-09-01"),
_r("c.undated"),
]
)
assert "## Review due" in out
assert out.index("2026-09-01") < out.index("2027-03-01")
assert "c.undated" not in out.split("## Review due")[1]
def test_review_due_section_omitted_when_no_record_is_dated():
assert "## Review due" not in bc.render_catalog([_r("a.b")])
def test_catalog_is_date_independent():
"""The generated file must never bake in 'today' — CI checks it with --check, so a
time-dependent render would drift red on a calendar boundary with no commit touching it."""
past = bc.render_catalog([_r("a.b", stale_after="2020-01-01")])
future = bc.render_catalog([_r("a.b", stale_after="2099-01-01")])
# Guard against vacuity: without this the assertion below passes trivially on a renderer that
# emits no dates at all (i.e. with the whole feature deleted).
assert "2020-01-01" in past and "2099-01-01" in future
# A long-past and a far-future date must produce byte-identical output apart from the date
# itself: no stale/fresh verdict, no marker, nothing derived from the clock.
assert past.replace("2020-01-01", "D") == future.replace("2099-01-01", "D")
def test_review_due_row_links_correctly_from_a_topic_file():
"""Review-due rows reuse _rel(), so a topic-file record must not get decisions.md's `../` form."""
out = bc.render_catalog(
[
_r("t.opic", source=Path("docs/decisions/workflow-process.md"), stale_after="2027-01-01"),
_r("m.ain", source=Path("docs/decisions.md"), stale_after="2027-01-02"),
]
)
due = out.split("## Review due")[1]
assert "(workflow-process.md#" in due
assert "(../decisions.md#" in due
+27
View File
@@ -32,3 +32,30 @@ def test_legacy_record_is_unmigrated():
def test_index_section_parses_as_heading():
recs = dl.parse_file(FIX)
assert any(r.heading == "Index" for r in recs)
def test_parses_optional_stale_after_and_sources():
recs = dl.parse_file(FIX)
r = next(r for r in recs if r.key == "ci.peak-anon-measurement")
assert r.stale_after == "2027-01-15"
assert r.sources is not None
assert "gitea run 4471" in r.sources
def test_optional_fields_default_to_none_when_absent():
recs = dl.parse_file(FIX)
r = next(r for r in recs if r.key == "ci.runner-placement")
assert r.stale_after is None
assert r.sources is None
def test_empty_stale_after_parses_as_empty_string_not_none():
"""Absent vs present-but-empty must stay distinguishable for the validator."""
text = (
"## H\n"
"`key: a.b` · `status: active` · `since: 2026-01-01` · `stale-after:` "
"· `supersedes: none` · `superseded-by: none`\n"
"**Rule:** r\n"
)
r = dl.parse_text(text, Path("fake.md"))[0]
assert r.stale_after == ""
+67
View File
@@ -411,3 +411,70 @@ def test_diff_engine_demoted_migrated_to_legacy_unmigrated(tmp_path, monkeypatch
_removed, _rewritten, demoted = dv._diff_findings("HEAD~1", "HEAD")
assert "2026-01-01 — Some decision (#1)" in demoted
# ---- optional stale-after / Sources metadata (ersatztv#603) ----
def test_stale_after_absent_is_not_an_error():
assert _v([_rec(key="a.b")]) == []
def test_wellformed_stale_after_is_not_an_error():
assert _v([_rec(key="a.b", stale_after="2027-01-01")]) == []
def test_malformed_stale_after_fails():
for bad in ("2027-13-01", "01-01-2027", "soon", "2027-02-30"):
errs = _v([_rec(key="a.b", stale_after=bad)])
assert any("not a YYYY-MM-DD date" in e for e in errs), bad
def test_past_due_record_does_not_fail_validation():
"""A record going stale is the passage of time, not a defect in the commit under test."""
errs = _v([_rec(key="a.b", stale_after="2020-01-01")])
assert errs == []
def test_stale_records_reports_only_past_due_active():
today = dv.date(2026, 7, 25)
recs = [
_rec(key="past.due", heading="Past", stale_after="2026-07-24"),
_rec(key="due.today", heading="Today", stale_after="2026-07-25"), # today >= date → stale
_rec(key="not.yet", heading="Future", stale_after="2026-07-26"),
_rec(key="no.date", heading="Undated"),
_rec(key="arch.ived", heading="Archived", status="superseded", stale_after="2020-01-01"),
]
assert dv.stale_records(recs, today) == [("Past", "2026-07-24"), ("Today", "2026-07-25")]
def test_stale_records_ignores_malformed_date():
"""A malformed date is caught as a blocking format error; it must not also crash the notice path."""
assert dv.stale_records([_rec(key="a.b", stale_after="whenever")], dv.date(2026, 7, 25)) == []
def test_sources_is_optional_and_never_required():
assert _v([_rec(key="a.b")]) == []
assert _v([_rec(key="a.b", sources="ci run 1234 · docs/ci-cd.md")]) == []
def test_empty_stale_after_is_malformed_not_absent():
"""A blank/truncated value must not pass as 'absent' — it would silently never fire."""
errs = _v([_rec(key="a.b", stale_after="")])
assert any("not a YYYY-MM-DD date" in e for e in errs)
def test_noncanonical_iso_forms_are_rejected():
"""date.fromisoformat accepts these on py>=3.11; the field's contract is YYYY-MM-DD only.
Accepting them would also break the catalog's Review-due sort, which orders on the raw string.
"""
for bad in ("20270101", "2027-W01-1", "2027-01-01T00:00:00", " 2027-01-01 extra"):
errs = _v([_rec(key="a.b", stale_after=bad)])
assert any("not a YYYY-MM-DD date" in e for e in errs), bad
def test_malformed_stale_after_on_an_archive_record_is_caught():
arch = _rec(key="a.old", status="superseded", superseded_by="a.b", stale_after="soon")
errs = _v([_rec(key="a.b", supersedes="a.old")], archive_records=[arch], archive_keys={"a.old"})
assert any("not a YYYY-MM-DD date" in e for e in errs)