feat(603): adopt OKF's optional stale-after and Sources: decision-record metadata
#605
+2
-1
@@ -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
@@ -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.
|
||||
|
||||
@@ -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) |
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 == ""
|
||||
|
||||
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user