# Adopt hardened repo-guard policy-delta gate for library size governance

[netkeep80]

Adopt hardened repo-guard policy-delta gate for library size governance

Problem

PersistMemoryManager already has a repository policy that defines a hard library-size budget for the kernel subtree:

• size_rules[0].id: kernel-subtree-max-bytes
• glob: include/**
• metric: bytes
• max: 270000
• count: all_tracked
• level: blocking

However, the downstream gate is still not strict enough:

1. repo-policy.json currently sets global enforcement to advisory.
2. .github/workflows/repo-guard.yml currently runs the repo-guard PR check with enforcement: advisory.
3. The workflow is pinned to an older repo-guard SHA that predates the new policy-delta hardening from netkeep80/repo-guard#99.
4. This leaves the library-size policy visible but not fully merge-blocking.
5. An AI-authored PR should not be able to grow include/** and relax the size budget / governance policy in the same change.

The goal is to make the library-size budget an actual protected invariant for PRs.

Desired behavior

After this change:

• PRs are evaluated by a repo-guard version that includes policy-delta hardening from netkeep80/repo-guard#99.
• repo-guard runs in blocking mode in CI.
• repo-policy.json uses blocking enforcement.
• A PR that grows include/** beyond the trusted base policy's kernel-subtree-max-bytes limit fails.
• A PR that tries to raise or weaken the size limit in repo-policy.json is detected as policy relaxation.
• Policy relaxation is allowed only as a dedicated trusted governance PR, not together with kernel/generated/product changes.
• PR-body authorization is not enough to authorize governance changes.
• Linked-issue authorization is used only when the issue is trusted by maintainer permission or a trusted maintainer-applied label such as governance-approved.

Proposed changes

Update PersistMemoryManager to consume the hardened repo-guard behavior.

1. Update the repo-guard Action ref

In .github/workflows/repo-guard.yml, replace the current pinned repo-guard SHA with a release tag or immutable SHA that includes netkeep80/repo-guard#99.

Preferred after release:

uses: netkeep80/repo-guard@vX.Y.Z

Temporary pre-release option, only if explicitly accepted by the maintainer:

uses: netkeep80/repo-guard@<merged-commit-sha-containing-policy-delta>

Do not leave this on the old SHA.

2. Make the PR gate blocking

In .github/workflows/repo-guard.yml:

 jobs:
   policy-check:
-    name: repo-guard advisory check
+    name: repo-guard blocking check
...
       with:
         mode: check-pr
-        enforcement: advisory
+        enforcement: blocking

3. Make policy enforcement blocking

In repo-policy.json:

   "enforcement": {
-    "mode": "advisory"
+    "mode": "blocking"
   },

4. Preserve the existing size budget

Do not raise this limit in this PR:

{
  "id": "kernel-subtree-max-bytes",
  "scope": "directory",
  "metric": "bytes",
  "glob": "include/**",
  "max": 270000,
  "count": "all_tracked",
  "level": "blocking"
}

This issue is about enforcing the existing budget, not increasing it.

5. Add or verify repository protection outside code

After the PR lands, configure branch protection / repository ruleset for main:

• require PR before merge;
• require the repo-guard blocking status check;
• require approval for governance files if CODEOWNERS is present;
• do not allow AI/bot users to bypass this gate.

If CODEOWNERS is not present yet, consider adding:

/repo-policy.json @netkeep80
/.github/workflows/repo-guard.yml @netkeep80
/.github/CODEOWNERS @netkeep80

This can be included in the same governance PR if the new-file budget allows it, or split into a follow-up governance PR.

Non-goals

• Do not raise kernel-subtree-max-bytes.
• Do not change files under include/**.
• Do not refresh generated single-header output.
• Do not combine this governance hardening with kernel refactoring.
• Do not weaken any diff_rules, size_rules, paths.forbidden, or paths.governance_paths.

Acceptance criteria

• .github/workflows/repo-guard.yml uses a repo-guard ref that includes policy-delta hardening from netkeep80/repo-guard#99.
• .github/workflows/repo-guard.yml runs mode: check-pr.
• .github/workflows/repo-guard.yml runs enforcement: blocking.
• The job name no longer says advisory; it says blocking or equivalent.
• repo-policy.json has "enforcement": { "mode": "blocking" }.
• The existing kernel-subtree-max-bytes rule remains present.
• The existing size max remains 270000.
• The existing size count remains all_tracked.
• The existing size level remains blocking.
• The PR does not touch include/**.
• The PR does not touch single_include/**.
• The PR does not relax diff_rules, paths.forbidden, paths.governance_paths, or workflow enforcement expectations.
• CI shows repo-guard as a blocking pass/fail gate.
• If branch protection / ruleset is not yet configured, this is documented in the PR checklist as a required maintainer action after merge.

Manual verification

After the PR is opened, verify that repo-guard fails if a test branch tries to do both of these in one PR:

1. increase the tracked size under include/**;
2. raise size_rules[*].max for kernel-subtree-max-bytes.

Expected result:

FAIL: policy-relaxation
PR attempts to relax trusted repository policy

Also verify that a normal kernel PR exceeding the trusted base limit fails through the size rule.

Contract

change_type: governance
scope:
  - repo-policy.json
  - .github/workflows/repo-guard.yml
  - .github/CODEOWNERS
  - scripts/check-repo-guard-rollout.sh
  - docs/index.md
budgets:
  max_new_files: 1
  max_new_docs: 0
  max_net_added_lines: 80
authorized_governance_paths:
  - repo-policy.json
  - .github/workflows/repo-guard.yml
  - .github/CODEOWNERS
  - scripts/check-repo-guard-rollout.sh
anchors:
  affects:
    - repo-guard check-pr trusted policy boundary
    - repo-policy.json policy relaxation
    - PersistMemoryManager library size budget
    - include subtree size governance
    - canonical-docs-sync registry rule
must_touch:
  - repo-policy.json
  - .github/workflows/repo-guard.yml
  - scripts/check-repo-guard-rollout.sh
must_not_touch:
  - include/**
  - single_include/**
expected_effects:
  - PersistMemoryManager uses hardened repo-guard policy-delta behavior
  - repo-guard PR check becomes blocking rather than advisory
  - existing include subtree byte budget becomes a merge-blocking invariant
  - AI-authored PRs cannot self-raise the library size limit in the same change that grows the library
  - repo-guard rollout validator is updated in lockstep with the workflow pin and enforcement mode
  - pre-existing canonical-docs-sync incompatibility in docs/index.md is fixed without changing the canonical document set

[konard]

@netkeep80 — running the PR with the new policy-delta-hardened repo-guard surfaces two blockers that need a maintainer-side decision before #385 can pass. Filing here because resolving them touches either the trusted issue body or a path the issue did not explicitly authorize.

1. scripts/check-repo-guard-rollout.sh is touched but not authorized

The PR has to bump three governance files in lockstep, because the rollout script enforces the previous pin and the previous advisory strings:

• repo-policy.json → enforcement.mode: blocking (authorized)
• .github/workflows/repo-guard.yml → new SHA b1b6756… + enforcement: blocking (authorized)
• scripts/check-repo-guard-rollout.sh → updated to require the new SHA and blocking strings (not in the issue's authorized_governance_paths)

Without the rollout-script update, Docs Consistency → Check repo-guard rollout wiring fails immediately (the script still asserts the old 6c81bb1… SHA and enforcement: advisory).

Repo-guard reports:

FAIL: governance-change-authorization
  touched_governance_paths: .github/workflows/repo-guard.yml, repo-policy.json, scripts/check-repo-guard-rollout.sh
  trusted_authorized_governance_paths: repo-policy.json, .github/workflows/repo-guard.yml, .github/CODEOWNERS
  unauthorized_paths: scripts/check-repo-guard-rollout.sh

Could you add scripts/check-repo-guard-rollout.sh to the issue's authorized_governance_paths block (and to scope: / must_touch:) so this gate authorizes the lockstep update?

2. Pre-existing canonical-docs-sync registry rule failure

The new repo-guard parses every markdown link in the Canonical Documents section of docs/index.md, not just the row-leading link. docs/index.md:13 has:

| [BlockHeader Semantics](block_and_treenode_semantics.md) | … the single physical [BlockHeader](../include/pmm/block_header.h#pmm-blockheader) layout … |

The second link normalizes to include/pmm/block_header.h, which is not in paths.canonical_docs, so registry-rules / canonical-docs-sync fails set_equality with extra in right: include/pmm/block_header.h. This is independent of #384 — it would fire on any PR running this repo-guard ref — but it blocks the blocking-mode flip here.

Two options:

• A. Split it off: pre-merge a tiny docs PR that removes (or escapes) the inline [BlockHeader](../include/pmm/block_header.h#...) reference in docs/index.md. After that lands, [governance/repo-guard] Adopt hardened policy-delta gate; flip enforcement to blocking #385 should reach a clean repo-guard pass.
• B. Allow docs/index.md to be touched in [governance/repo-guard] Adopt hardened policy-delta gate; flip enforcement to blocking #385 as a single-line text fix. Per non-goals (must_not_touch: docs/**) this needs your explicit go-ahead and an updated authorized_governance_paths in the issue body.

Holding #385 until you can update the issue body / decide on the docs path. Everything else (workflow flip to blocking, repo-policy.json enforcement, CODEOWNERS, size-rule preservation) is already in place and bash scripts/check-repo-guard-rollout.sh passes locally.