Skip to content

docs(exemptions): add Layer 5 census scope for the 23 vendored workflow copies - #1039

Merged
hyperpolymath merged 1 commit into
mainfrom
docs/layer5-census-scope
Sep 23, 2026
Merged

hyperpolymath merged 1 commit into
mainfrom
docs/layer5-census-scope

Conversation

@hyperpolymath

Copy link
Copy Markdown
Owner

What

Adds Layer 5: Census scope to docs/EXEMPTION-MECHANISMS.adoc, documenting the 23
vendored workflow copies that the standards#1005 codeql-action re-pin census surfaced, and
records the basis on which they are out of scope.

Also corrects the preamble, which said "Three concentric exemption layers" while Layer 4
already existed. Adding Layer 5 would have made that miscount worse, so it is fixed here
rather than left.

Why this is a different kind of exemption

Layers 1–4 all answer "this finding is real, and we are choosing not to act on it."
Layer 5 answers "is this file in scope at all?" — a question the existing document had no
home for, which is why the population had no recorded disposition.

An estate census walks paths, not runtimes. GitHub Actions dispatches a workflow only from
.github/workflows/ at the repository root. A file at
stubs/cpt/.github/workflows/scorecard.yml is an ordinary file in the tree: never
registered, never dispatched.

The population, measured 2026-09-23

23 copies across 5 repositories. 0 at a repository root; 23 under a directory prefix.

repo prefixes copies
ssg-collection stubs/{cpt,dei,reliquary,tiamat,tripos,tyrano,ultimatum,vladik}/, ssg-fixes/jtv-playground/, variants/befunge/ 10
polystack poly-ssg/satellites/{…}-ssg/ 8
wordpress-tools journal-theme/ (2), resurrect/ 3
jtv-lang playground/ 1
reposystem total-upgrade/ 1

A stale pin in one of these cannot produce a startup_failure, cannot pull a vulnerable
action, and cannot consume a runner. Re-pinning them is churn against files that cannot run.

The condition, which is the part worth reviewing

The exemption is conditional on the directory staying vendored, and the re-check trigger is
promotion, not a date.
stubs/ and satellites/ exist precisely so a skeleton can become a
repository of its own. The moment one is extracted, its .github/workflows/ becomes live and
every pin this exemption excused becomes a real defect — silently, with no gate firing and no
census entry changing. The section states that any PR extracting a skeleton must re-pin it as
part of the extraction.

A rationale I am retracting rather than carrying forward

The earlier statement of this exemption also claimed that some copies are "compared
byte-for-byte by tests"
, implying a second independent justification. That is false.
ssg-collection/tests contains only fuzz/; no such comparison exists anywhere in the estate.
It is recorded in the document as withdrawn, because the difference matters to whoever
revisits this: the exemption is narrow and rests on non-execution alone, not doubly justified.

What the section explicitly refuses

  • Not a reason to skip a census — the right output is "23 found, 23 out of scope, here is
    why"
    , never "0 found". An exemption you cannot see is one you cannot audit.
  • Not transferable to a file that merely looks inert. A disabled workflow at the root is
    still registered, or one edit from it, and stays in scope. The discriminator is the path.
  • Not a licence to let the copies drift, since they seed future repositories.

Acceptance criteria

  • AC1 — population measured, not asserted: 23 paths, 0 at root, 5 repos; table sums to 23.
  • AC2 — basis is non-execution only; the refuted tests rationale is recorded as withdrawn.
  • AC3 — promotion risk documented with a named trigger rather than a review date.
  • AC4 — decision-tree entry and cross-reference added so the layer is reachable.
  • AC5 — asciidoctor renders clean (rc=0, no warnings); both table blocks balanced.

Follow-up, deliberately not in this PR: the document still references
bot_exclusion_registry.a2ml and Debtfile.a2ml, and A2ML is retired. That is an
estate-wide rename tracked separately; doing it here would bury a 23-path scope decision
inside a doctrine migration.

🤖 Generated with Claude Code

https://claude.ai/code/session_01X3hgXxWm6umMgZkjYyHnnm

An estate census walks paths, not runtimes. Repositories that vendor a
complete project skeleton into a subdirectory — a stub, a satellite, a
scaffolding template — carry that skeleton's .github/workflows/*.yml as
ordinary files, and every path-based census finds them. GitHub Actions
dispatches a workflow only from .github/workflows/ at the repository
ROOT, so these copies are never registered and never run.

Measured 2026-09-23: 23 vendored copies across 5 repositories, each
carrying a github/codeql-action pin that the standards#1005 re-pin
census flagged. Of the 23 paths, 0 are at a repository root and 23 sit
under a directory prefix. A stale pin in one cannot produce a
startup_failure, cannot pull a vulnerable action, and cannot consume a
runner; repairing them is churn against files that cannot execute.

  ssg-collection  10   stubs/{8}, ssg-fixes/jtv-playground, variants/befunge
  polystack        8   poly-ssg/satellites/{8}-ssg
  wordpress-tools  3   journal-theme (2), resurrect
  jtv-lang         1   playground
  reposystem       1   total-upgrade

The exemption is conditional on the directory staying vendored, and the
re-check trigger is PROMOTION, not a date. stubs/ and satellites/ exist
so a skeleton can become a repository of its own; the moment one is
extracted, its workflows become live and every excused pin becomes a
real defect, silently, with no gate firing. Any PR extracting a skeleton
must re-pin it as part of the extraction.

Retracts one rationale rather than carrying it forward: the earlier
statement of this exemption claimed some copies are "compared
byte-for-byte by tests". That is false — ssg-collection/tests contains
only fuzz/ — so it is recorded as withdrawn. The exemption rests on
non-execution alone.

Also corrects the preamble, which said "Three concentric exemption
layers" while Layer 4 already existed; adding Layer 5 would have made
the miscount worse.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X3hgXxWm6umMgZkjYyHnnm
@coderabbitai

coderabbitai Bot commented Sep 23, 2026

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

Next included review available in 15 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 82c54589-0ede-45fb-9439-3a22d4cadc4a

📥 Commits

Reviewing files that changed from the base of the PR and between 779d8a9 and f37a427.

📒 Files selected for processing (1)
  • docs/EXEMPTION-MECHANISMS.adoc

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@sonarqubecloud

Copy link
Copy Markdown

@hyperpolymath
hyperpolymath merged commit 30815fa into main Sep 23, 2026
45 checks passed
@hyperpolymath
hyperpolymath deleted the docs/layer5-census-scope branch September 23, 2026 09:06
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