Skip to content

docs(ci-posture): restructure around an executive summary, per-component detail and an archive - #238

Merged
sgort merged 1 commit into
accfrom
docs/ci-posture-restructure
Sep 30, 2026
Merged

sgort merged 1 commit into
accfrom
docs/ci-posture-restructure

Conversation

@sgort

@sgort sgort commented Sep 30, 2026

Copy link
Copy Markdown
Owner

docs/ci-posture-across-repos.md covers all three applications and had grown to 2,387 lines organised by mechanism, with six dated "what changed" sections wedged between the summary table and the first explanation.

That order served whoever wrote it. A reader arriving now had to walk three weeks of chronology before reaching any analysis, and could not answer "where does my component stand" without assembling it from five thematic sections.

Restructured, not rewritten. The analysis in §1–§6 is the value here and is kept almost entirely. What moved is the order; what is new is the two things the old shape could not express.

What is new

An executive summary, stating the one fact worth carrying away — the three are now uniform on everything that can be made uniform, and the differences left are recorded decisions — then the two constraints that bound the whole posture:

  • Every gate now lives in the same layer. All six branches are governed by a ruleset alone, no classic protection anywhere, as of 29–30 September. Before that, classic protection sat beside every ruleset saying allow_force_pushes: true on branches the rulesets were in fact protecting — governing nothing and reading as permissive.
  • What a gate can require is bounded by what actually reports. main requires audit and scan and deliberately not the build or deploy jobs: those are path-filtered on push, and a promotion pull request inherits only the head commit's push runs. Two past RBA promotions genuinely carry no PA Demo check.

The summary table is updated and gains four rows — response-schema conformance, classic protection, merge method, and per-repository pinned-reference counts. The ruleset rows were the most stale: one still said ttl-editor's main was "classic, no checks", which stopped being true this morning.

A section per application, each with its shape, numbers, ruleset ids and accepted gaps — so that question is answered in one place. Each also records what that repository is the reference for: ttl-editor for the content comparison in check-deps.sh, this repository for promotion sequencing and the response-conformance helper, RONL Business API for the published contract and the three checks that keep it true.

An archive, holding the six dated sections plus four new ones for 26, 28, 29 and 30 September. They record what moved and what the previous claim had been — including two of mine from the last two days, both named rather than quietly replaced:

  • that packages/backend/deploy/ no longer exists (it does, at deploy time — the scripts create it)
  • that this repository's check-deps.sh compares modification times (it does not; it is the same content comparison the other two use)

Facts re-verified, not carried over

Node versions each .nvmrc — 24.20.0 / 24.21.0 / 22.23.2
Pinned references each repo's own check-supply-chain — 17 / 31 / 39
Documented operations the built openapi.json — 133
Route test files using the conformance helper the calls themselves — 20
Coverage runners every config declaring a threshold — 1 / 2 / 5
Ruleset ids and check counts GitHub API — 3 / 5 / 6 on acc, 2 / 2 / 2 on main

The App Service runtimes are carried forward with their date — read from Azure on 27 September — because az is not signed in to that tenant today. The page's own convention is that a row carries over unless an archive entry says otherwise, and saying which is which is the point.

One sentence was corrected against the page's own record while writing it. The opening drafted "one repository had an unprotected main, one had never exercised its build id", implying different repositories. §6 says all three were this repository's, closed on 2026-09-09 in that order, and RONL Business API closed the same three on 12 September.

Checks

prettier --check clean · check-supply-chain green · check-rip-bpmn-copies green · deps:check green.

2,387 → 2,758 lines. No content was dropped; the growth is the executive summary, the three component sections and four archive entries.

…ent detail and an archive

The page had grown to 2,387 lines organised by MECHANISM, with six dated "what
changed" sections wedged between the summary table and the analysis. That order
served whoever wrote it. A reader arriving now had to read three weeks of
chronology before reaching the first explanation, and could not answer "where
does MY component stand" without assembling it from five thematic sections.

Restructured, not rewritten. The analysis in §1-§6 is the value here and is kept
almost entirely; what moved is the order, and what is new is the two things the
old shape could not express.

## Executive summary

New, at the top. It states the one fact worth carrying away -- the three are now
uniform on everything that can be made uniform, and the differences left are
recorded decisions -- and then the two things that bound the whole posture:

- Every gate now lives in the same layer. All six branches are governed by a
  ruleset alone, no classic protection anywhere, as of 29-30 September.
- What a gate can require is bounded by what actually reports. `main` requires
  `audit` and `scan` and deliberately not the build or deploy jobs, because those
  are path-filtered on push and a promotion inherits only the head commit's push
  runs. Two past promotions genuinely carry no PA Demo check.

The summary table is updated and gains four rows: response-schema conformance,
classic protection, merge method, and per-repository pinned-reference counts. The
`acc`/`main` ruleset rows were the most stale -- one said ttl-editor's `main` was
"classic, no checks", which stopped being true this morning.

## The three applications

New. One section per repository, each carrying its shape, its numbers, its
ruleset ids, and the gaps it has accepted -- so the question "where does this
component stand" is answered in one place rather than five.

Each also carries what that repository is the reference for: ttl-editor for the
content-comparison in check-deps.sh, Linked Data Explorer for promotion
sequencing and the response-conformance helper, RONL Business API for the
published contract and the three checks that keep it true.

## Archive

The six dated sections moved to the end, newest first, and four were added for
26, 28, 29 and 30 September. They record what moved AND what the previous claim
had been, because a corrected claim is more useful than a silently replaced one --
including two of mine from the last two days: that
`packages/backend/deploy/` no longer exists, and that linked-data-explorer's
check-deps.sh compares modification times. Both were wrong and both are named.

## Facts re-verified rather than carried over

Every number in the new sections was read from source: Node versions from each
`.nvmrc`; pinned-reference counts from each repository's own
`check-supply-chain` (17 / 31 / 39); the 133 operations from the built
`openapi.json`; 20 route test files from the calls themselves; coverage runners
by finding every config that declares a threshold (1 / 2 / 5); ruleset ids and
check counts from the GitHub API (3 / 5 / 6 on `acc`, 2 / 2 / 2 on `main`).

The App Service runtimes are carried forward with their date -- read from Azure
on 27 September -- because `az` is not signed in to that tenant today. The page's
own convention is that a row carries over unless an archive entry says otherwise,
and saying which is which is the point.

One sentence was corrected against the page's own record while writing: the
opening drafted "one repository had an unprotected `main`, one had never
exercised its build id", which implied different repositories. §6 says all three
were Linked Data Explorer's, closed on 2026-09-09 in that order.

prettier clean, check-supply-chain green, check-rip-bpmn-copies green.
@sgort
sgort merged commit e17f24e into acc Sep 30, 2026
10 checks passed
@sgort
sgort deleted the docs/ci-posture-restructure branch September 30, 2026 05:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant