[squid-protocol]

Closes #5057. Draft.

Design: the aggregate pages rendered from committed sources are git-ignored. A PR commits its sources only. CI renders the pages (the render must succeed and give the same output twice) and shows the diff. A post-merge job publishes them to generated. This is the pattern of #4825 / #5017.

Class: committed generated files

File	Generator	Churn since 10-06	Decision
docs/language_status/oracle_assumptions.md	register.py render	72	moved (this PR)
docs/language_status/cics_spec_status.md	cics_spec_status.py render	17	moved (this PR); the evidence-refresh bot no longer renders or commits it
docs/language_status/evidence_report/*	evidence_report.py	24 (0 since #5017)	already moved by #5017; the committed copy is the readers' fallback (evidence_report --check, estate_intake)
docs/self_scan/graph_comparison_ledger.json	call_graph_accuracy.py --ledger	7 (bot, last 10-11)	keep: it holds human verdicts that PRs add (a source); the bot's count updates already go to generated (#4847)
cics_field_testing.md + fact_channel_confidence.json	field_testing.py report --write	2/1	keep: one render with a JSON that is read at runtime and shipped (skeleton_export.py); low churn
fresh_estate_trials.md/.svg	trial.py report --write	0	keep: no churn
cics_crucible.md	cics_crucible.py --update-baseline	2	keep: written together with the ratchet baseline.json
docs/signal_contracts.md	signal_contract_audit.py --render	0	keep: no churn
CicsSpec.java, ggcics_spec.h	gitgalaxy.standards.cics regen	4/4	keep: generated source, read at runtime or compiled
docs/gitgalaxy_architecture_brief.md	gitgalaxy.yml self-scan	7 (bot PR)	keep: still open under #4963 (agents read it from the checkout)
ci/requirements/*.txt, templates/requirements/*.txt, ebcdic_dbcs/cp93*.json, det/cvda.py	pin scripts / table generators	≤3	keep: install inputs and runtime tables

cics_command_spec.md, the wiki cookbook pages and register/_parts/* matched the search but are hand-written (the parts are inputs to the register page).

Code

• New tests/tools/generated_docs.py, with PAGES = {path: renderer}:
  • check [--out DIR] renders every page twice. It fails on an exception (e.g. an entry _layout.json does not place) or on two renders that differ.
  • diff BASE NEW prints the markdown diff used in the job summary.
  • render writes the pages into the working tree for local reading.
• The readers use the sources now: cics_spec_status.register_rows() reads register.load_entries(); evidence_report.register() and the Db2 digest test read register.render(). I checked locally that each gives the same result as reading the old page.
• register.py --check and cics_spec_status.py render --check now check only that the page renders; there is no committed page to compare against.
• pr_gates --fast has a new gen-docs gate. It replaces the staleness tests, which ran in the suite; pr_gates itself had no staleness gate for these pages.
• Tests:
  • New test_generated_docs.py:
    • Every page renders deterministically.
    • No page is tracked, and each is ignored.
    • A render error fails the check, a non-deterministic render fails it, and a stray register entry fails it.
    • The diff output is checked.
    • Acceptance: two branches that each add a register entry merge in both orders without conflict, and the merged render has both entries.
  • test_generated_branch.py:
    • generated-docs.yml is added to MOVED.
    • Its render job holds no write token, and publish runs only on main.
    • The PAGES list equals the published paths.
    • evidence-refresh no longer touches cics_spec_status.
  • The staleness tests (test_the_combined_register_page_is_current, test_the_committed_page_is_current, test_check_fails_on_a_stale_page) are replaced by consistency and render tests.
• Links in the docs point at the published copies. CLAUDE.md, the skills (det-port, cics-command-slice, blocker-slice, box-capacity) and the agent files say to commit sources only.

Workflow lines changed

• New generated-docs.yml:
  • Job render runs on pull_request (path-filtered to the render inputs) and on every push to main, so the published copies always match main. Its permissions are contents: read and persist-credentials: false. It runs generated_docs.py check. On a PR it also renders the base and puts the diff in the job summary and the generated-docs-diff artifact. A base from before ci/docs: stop committing generated aggregate docs in PRs (oracle_assumptions.md et al.): render post-merge to the generated branch #5057 falls back to the base's committed pages.
  • Job publish runs only on a push or dispatch on refs/heads/main. It has contents: write, used only for generated_branch.py publish --stamp generated-docs <2 pages>, which is a no-op when nothing changed.
  • Concurrency: main runs queue in order and are never cancelled, so an older render cannot publish over a newer one. PR runs cancel their older runs.
  • First run: merging this PR is a push to main, so it publishes the first copies. workflow_dispatch from main is the fallback.
• evidence-refresh.yml: removed the step "Re-render the CICS spec status page" and the cics_spec_status.md line in add-paths; updated the header comment and the PR body text.
• smoke-test.yml: removed the advisory step "CICS spec status page"; the render job above replaces it.
• No workflow writes to main. test_only_the_listed_workflows_commit_to_main is unchanged and passes.

Cross-repo / in-flight

Open PRs #5015, #5038 and #5041 edit the pages this PR deletes. After this merges, each gets a modify/delete conflict on them. Resolve it by taking the deletion (git rm the page); their register entry files carry the content.

Gates

• pr_gates --fast: 6/6 pass (lint, audits, secrets, xray, gen-docs, gauntlet).
• pr_gates --ratchets: 7 pass, 0 fail, 0 skipped.
• Targeted tests run with plain pytest from /tmp: all pass except test_evidence_report.py::test_the_committed_reports_are_current. That test also fails on unmodified origin/main (evidence_report.py --check: zecs, as bot output to the generated branch: ground-truth history, evidence report, census reader (Part of #4963) #5017 noted), and it is advisory in PR CI.
• No golden-master bless: no parsing change.

🤖 Generated with Claude Code

[github-actions]

🐦‍⬛ Muninn Security Scan

✅ No security issues found.

🐦‍⬛ Powered by Muninn · Skald Lab

[squid-protocol]

No description provided.