[miroslavpojer]

Overview

This PR adds two maintainer pages and a check that keeps the second one true.

• Decision archive (docs/_archive/decisions.md):
  • ## Purpose says what the page is: append-only and not canon. ## Contents follows, then one table | No. | Date | Decision | Why | Rule lives in |.
  • It has 107 rows with one sentence per cell. Each row keeps its original number.
  • A row explains current code or binds planned work. Decisions on task order, drafting, gate scheduling and replaced choices are left out, and the table's lead-in says so.
  • "Rule lives in" links one of three things: a tracked page here, a component page at master, or the epic or issue a planned-work decision binds.
  • The page is about 33 KB. The owner dropped the issue's 20 KB limit (see the comment on Keep the design decisions in docs/_archive/ and an overview of open debt in docs/_backlog/ #137).
• Debt overview (docs/_backlog/debt-overview.md):
  • It has Purpose, Contents and Rules (facts only), then Topics (22) and Wakes on (17), each tag with a one-line meaning.
  • Open debt has 55 rows, one per open tech-debt or epic issue. Each row has four cells, and rows are sorted by repository, then number.
  • Rows per repository: living-doc 27, living-doc-utilities 13, living-doc-toolkit 7, living-doc-collector-gh 5, living-doc-generator-markdown 3.
• Drift check (tests/docs/debt_overview_check.py):
  • It reads the page, then the open issues of the seven repositories that carry type:tech-debt, type:epic, tech debt or epic. It uses the REST API, paginated, with GITHUB_TOKEN or GH_TOKEN when set.
  • It prints one line per finding:
    • an open issue without a row;
    • a row whose issue is closed, no longer labelled, or missing;
    • a tag on neither list;
    • a duplicate row;
    • a row out of order;
    • a malformed row.
  • Exit codes: 0 for no finding, 1 for drift, 2 when the page or GitHub cannot be read.
• Its tests (tests/docs/test_debt_overview_check.py) run offline: one test per finding kind, a clean case, pagination, malformed GitHub answers, and a parse of the real page.
• Workflow (.github/workflows/debt-overview.yml):
  • It runs on a PR that changes the page, the check or the workflow, by hand, and weekly.
  • The check job has contents: read only.
  • The report job runs only on a scheduled run that finds drift, and it alone has issues: write. It opens the one type:documentation issue titled "Bring the debt overview in line with the open issues", or comments on it if it is already open.
  • Nothing is committed. Actions are pinned by SHA.
• Agents: AGENTS.md § This project, in a new § Open debt, and CONTEXT.md § Conventions say: before changing code in any of the seven repositories, search the overview. On a hit, say in the PR whether the change fixes the debt, makes it worse or leaves it. The § Commands Check now runs the drift check.
• Pages:
  • Both pages are in PAGES in tests/docs/pages.py.
  • CONTRIBUTING.md § Writing documentation puts both folders at level D. CONTRIBUTING.md links both pages, so each is two links from README.md.
  • docs/CONTEXT.md § Layout states both folders' rules.
  • The retired-names check found no hit, so no allow-list entry was needed.

A disagreement with the canon was raised on #137 before it was coded. The issue lists module.py::symbol as an anchor form, which flow rule 6 forbids on every page. The owner decided to exempt the debt overview: rule 6's text names it, and ANCHOR_PAGES in tests/docs/pages.py leaves it out of the no-anchor test.

Acceptance criteria:

1. Archive. It has the five columns, one sentence per cell, and every link resolves. The size limit was dropped by the owner. No row is about task order or drafting.
2. Overview. It has Purpose, Rules, the two lists and 55 rows of four cells, and every tag is on its list. test_the_page_parses_and_uses_only_listed_tags and the live check show it.
3. Drift check. It passes on this branch against GitHub (exit 0), and each finding kind has a test. The workflow triggers and the report job are as described above.
4. Agent pointers. They are in AGENTS.md § Open debt, CONTEXT.md § Conventions and docs/CONTEXT.md § Layout.
5. Checks. Each item of AGENTS.md § Check:
   • pytest tests/examples tests/docs tests/integration: 382 passed.
   • examples_check.py: OK at living-doc-utilities 0.8.1.
   • retired_names_check.py --strict over the pinned components: no hit.
   • sync-canon-copies.sh and regen-collector-snapshots.sh: no change.
   • Testbed stage: passed.
   • Agentic script tests: passed.
   • lychee: 1432 links, 0 errors.
   • agentskills validate was not run, because no skill changed.
6. Canon rules this change relies on:
   • CONTRIBUTING.md § Writing documentation:
     • the levels (level D);
     • flow rule 1 (Purpose, then Contents);
     • flow rule 3 (a reference fact is linked, never restated);
     • flow rule 5 (within three links of README.md);
     • flow rule 6 (no path::symbol anchor, now with the debt overview's exception);
     • the page anatomy (fact and option lists, one line per item).
   • docs/CONTEXT.md § Conventions: a new page goes into PAGES, and component links point at master.
7. Framework. The change stays inside the frame: it adds maintainer pages and tooling, and no part's responsibility changes.

Not covered:

• The check does not verify that an epic's wake cell is — or that a tech-debt row has a wake tag; the issue does not ask for it.
• A scheduled run that cannot read GitHub fails and files no issue.

Release Notes

• Decision archive docs/_archive/decisions.md: why the ecosystem is designed as it is, one row per decision with the page that holds its rule.
• Debt overview docs/_backlog/debt-overview.md: every open tech-debt and epic issue of the seven repositories, findable by path, symbol or error code.
• A weekly check keeps the debt overview in line with GitHub and opens a documentation task when it drifts.

Framework

• Stays inside the frame (F1–F7)
• Bends frame row F_ — exception E_ added to docs/introduction/principles.md in this PR

Related

Closes #137