Merge pull request #533 from bsv-blockchain/codex/backlog-ci-scope-20260915

fix(ci): keep elapsed review deadlines out of ordinary merge gates

Author: ty-everett

.github/SECURITY.md

@@ -107,8 +107,9 @@ last-pusher-independent approval is not an unconditional requirement.
 Do not dismiss a finding or add an override merely to make CI green. A genuine
 false positive or unavoidable temporary compatibility substitution must be
 registered in `governance/repository-health/exceptions.json` with an owner,
-rationale, evidence, review deadline, and objective removal condition. Expired
-exceptions fail CI.
+rationale, evidence, review deadline, and objective removal condition. Elapsed review deadlines are maintenance reminders in ordinary source CI.
+The separate weekly Maintenance review deadlines workflow enforces them;
+malformed, unowned, or unregistered exceptions still fail ordinary CI.
 
 Public services such as Overlay, Wallet Storage, WAB, Message Box, and Wallet
 Relay may need to accept clients from previously unknown domains. Their public

.github/workflows/maintenance-review.yml

@@ -0,0 +1,31 @@
+name: Maintenance review deadlines
+
+on:
+  schedule:
+    - cron: '23 15 * * 1'
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: maintenance-review
+  cancel-in-progress: false
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24.x
+      - name: Review exception deadlines
+        run: node scripts/repository-health.mjs --maintenance --summary-file "$GITHUB_STEP_SUMMARY"
+      - name: Review documentation deadlines
+        if: ${{ !cancelled() }}
+        run: node scripts/documentation-policy.mjs --all

CONTRIBUTING.md

@@ -181,7 +181,10 @@ container migrations are coordinated programs, not routine bumps.
 Do not introduce a broad override or suppression. If no compatible upstream
 fix exists, register the narrowest temporary exception with an owner, evidence,
 review date, objective removal condition, and tests. Rehearse removal after
-relevant upstream releases.
+relevant upstream releases. Elapsed documentation and exception review dates
+are maintenance warnings in source CI, enforced by the separate weekly
+Maintenance review deadlines workflow. Passing time alone must not block a PR;
+structural errors, generated drift, security audits, and code checks still do.
 
 ## Versions, changelogs, and migrations
 

docs/about/doc-agent.md

@@ -3,8 +3,8 @@ id: about-doc-agent
 title: 'Documentation Maintenance'
 kind: meta
 version: '2.1.0'
-last_updated: '2026-09-14'
-last_verified: '2026-09-14'
+last_updated: '2026-09-15'
+last_verified: '2026-09-15'
 review_cadence_days: 30
 status: stable
 tags: [about, documentation, maintenance, automation]
@@ -51,8 +51,8 @@ id: unique-slug
 title: 'Page title'
 kind: spec
 version: '1.0.0'
-last_updated: '2026-07-27'
-last_verified: '2026-07-27'
+last_updated: '2026-09-15'
+last_verified: '2026-09-15'
 review_cadence_days: 30
 status: stable
 tags: [protocol, reference]
@@ -78,7 +78,7 @@ tags: [protocol, reference]
 pnpm docs:facts
 
 # Verify generated facts, parity metadata, package README contracts,
-# package-doc versions, and review cadence for affected pages
+# package-doc versions, and advisory review reminders for affected pages
 pnpm docs:facts:check
 
 # Validate frontmatter and source links
@@ -119,9 +119,10 @@ revision expressions outside that syntax.
 Release, scheduled, and manual GitHub runs have no change scope unless one is
 provided explicitly. All invocations still enforce package documentation,
 generated-content consistency through `docs:facts:check`, and date consistency
-(verification cannot predate an update or be in the future). Only review expiry
-is scoped. The full audit is an opt-in maintenance command, not an unrelated
-PR's merge requirement. Re-verify an affected expired page against its source
+(verification cannot predate an update or be in the future). Only review-expiry reminders
+are scoped; they are warnings in ordinary source checks. The full audit is an opt-in maintenance command, not an unrelated
+PR's merge requirement. The weekly Maintenance review deadlines workflow
+runs this audit independently and fails on overdue reviews. Re-verify an affected expired page against its source
 before updating its date; do not bulk-advance unrelated verification dates.
 
 The package README contract covers every public package and requires registry

docs/reference/dependency-policy.md

@@ -3,8 +3,8 @@ id: dependency-release-policy
 title: 'Dependency and Release Policy'
 kind: reference
 version: '1.3.1'
-last_updated: '2026-08-30'
-last_verified: '2026-08-30'
+last_updated: '2026-09-15'
+last_verified: '2026-09-15'
 review_cadence_days: 30
 status: stable
 tags: [reference, dependencies, security, releases]
@@ -145,7 +145,9 @@ temporary `gaxios` substitutions, and Message Box plus UHRP cloud storage need
 `uuid`; the Wave 37 review removed every substitution from a service where the
 frozen graph stayed clean without it. The machine-readable registry now maps
 every remaining selector and exact value to its exception. CI rejects a new,
-changed, stale, expired, unowned, or upstream-unlinked override.
+changed, stale, unowned, or upstream-unlinked override. Elapsed review dates
+produce maintenance reminders in source CI and fail the separate weekly
+maintenance audit (`node scripts/repository-health.mjs --maintenance`).
 
 Wave 40 rechecked the prior 20 selectors against the frozen graphs, current
 upstream manifests, and the advisory audit. The 2026-09-04 security review

docs/reference/repository-health.md

@@ -3,8 +3,8 @@ id: repository-health
 title: 'Repository Health Controls'
 kind: reference
 version: '1.4.1'
-last_updated: '2026-09-14'
-last_verified: '2026-09-14'
+last_updated: '2026-09-15'
+last_verified: '2026-09-15'
 review_cadence_days: 30
 status: stable
 tags: [reference, governance, quality, security, releases]
@@ -56,8 +56,10 @@ package READMEs that do not identify, install, demonstrate, and license the
 registry artifact, and missing, duplicated, version-drifted, or
 pre-consolidation public package pages.
 
-Documentation review expiry applies only to edited pages and pages associated
-with directly changed sources. Package and service inventories supply their
+Documentation review reminders apply only to edited pages and pages associated
+with directly changed sources. Elapsed dates are warnings, including on affected
+pages, so an ordinary code change is never blocked just because time passed.
+The separate weekly Maintenance review deadlines workflow enforces all dates. Package and service inventories supply their
 page relationships; `freshness.sourcePaths` in the documentation policy maps
 other pages to source files or directories. The check uses the PR merge-base
 diff, the push before/after diff, or local changes against `origin/main`.
@@ -224,7 +226,8 @@ checks:
 3. generated artifact boundaries have valid owners, sources, generators, narrow
    review/analysis policies, and exact CodeQL exclusion coverage;
 4. published package versions match the recorded baseline;
-5. exception records are owned, structurally valid, and unexpired;
+5. exception records are owned and structurally valid; elapsed review dates
+   are maintenance warnings in source CI and errors with `--maintenance`;
 6. current package-contract findings exactly match the ratcheted snapshot; and
 7. generated stack/conformance facts, all 33 public package README contracts,
    and one current consolidated package page per public package are current;

governance/documentation-policy.json

@@ -28,7 +28,7 @@
   },
   "freshness": {
     "scope": "changed-pages-and-direct-sources",
-    "rationale": "Review expiry blocks only pages edited in the change or documenting its directly changed sources. Package pages use the project inventory (including shared sourceRoots), service pages use the service inventory, and other source relationships are declared below. Unrelated review deadlines never block a PR. Structural and generated-content checks remain repository-wide.",
+    "rationale": "Ordinary source checks report elapsed review deadlines as maintenance warnings for changed pages and directly changed sources. The separate maintenance workflow enforces every review deadline. Structural, date-consistency, and generated-content checks remain blocking; passing time alone never blocks an ordinary PR.",
     "sourcePaths": {
       "docs/about/contributing.md": ["CONTRIBUTING.md"],
       "docs/about/doc-agent.md": [

governance/repository-health/exceptions.json

@@ -163,13 +163,13 @@
       "category": "override",
       "target": "pnpm-workspace.yaml override nanoid releases below 3.3.18",
       "owner": "ts-stack-maintainers",
-      "reason": "Vite's current PostCSS dependency range can select nanoid releases affected by GHSA-2v37-7h3g-55p8, whose patched 3.x boundary was raised to 3.3.18 on 2026-08-13. Selecting 3.3.18 is the narrowest compatible remediation and leaves runtime application packages unchanged.",
+      "reason": "Vite's current PostCSS dependency range can select nanoid releases affected by GHSA-2v37-7h3g-55p8, whose patched 3.x boundary was raised to 3.3.18 on 2026-08-13. Selecting 3.3.18 is the narrowest compatible remediation and leaves runtime application packages unchanged. Reviewed 2026-09-15: installed PostCSS 8.5.23 still declares nanoid ^3.3.16, which permits versions below the fixed 3.3.18 boundary; retain the narrow constraint. Calendar renewal is now maintenance-owned and cannot block unrelated source CI.",
       "evidence": [
         "pnpm-workspace.yaml#overrides",
         "https://github.com/advisories/GHSA-2v37-7h3g-55p8"
       ],
       "created": "2026-08-09",
-      "reviewBy": "2026-09-13",
+      "reviewBy": "2026-10-15",
       "removeWhen": "Remove when the supported Vite and PostCSS dependency graph naturally resolves nanoid 3.3.18 or newer and the frozen audit remains green."
     },
     {

scripts/dependency-release-governance.mjs

@@ -194,9 +194,8 @@ function validateOverrideRegistry(policy, exceptions, errors) {
   }
 
   const byId = new Map(exceptions.exceptions.map(exception => [exception.id, exception]))
-  const today = new Date().toISOString().slice(0, 10)
   for (const registration of policy.overrideRegistry) {
-    validateOverrideException(registration, byId, policy.owner, today, errors)
+    validateOverrideException(registration, byId, policy.owner, errors)
   }
   const review = policy.overrideRemovalReview
   if (
@@ -255,7 +254,7 @@ function validateDirectInventoryPolicy(policy, errors) {
   }
 }
 
-function validateOverrideException(registration, exceptionsById, owner, today, errors) {
+function validateOverrideException(registration, exceptionsById, owner, errors) {
   const exception = exceptionsById.get(registration.exceptionId)
   if (exception?.category !== 'override') {
     errors.push(
@@ -264,7 +263,6 @@ function validateOverrideException(registration, exceptionsById, owner, today, e
     return
   }
   if (exception.owner !== owner) errors.push(`${exception.id} must be owned by ${owner}`)
-  if (exception.reviewBy < today) errors.push(`${exception.id} expired on ${exception.reviewBy}`)
   const hasExternalEvidence = (exception.evidence ?? []).some(
     item =>
       item.startsWith('https://github.com/') &&

scripts/documentation-freshness.mjs

@@ -110,3 +110,13 @@ export function documentationDateFindings(updated, verified, cadence, today, aff
   if (verifiedDate > today) findings.push('last_verified cannot be in the future')
   return findings
 }
+
+// Calendar reminders do not determine whether a source change is correct.
+// The full maintenance audit enforces deadlines independently of merge CI.
+export function documentationDateReport(updated, verified, cadence, today, affected, fullAudit) {
+  const findings = documentationDateFindings(updated, verified, cadence, today, affected)
+  const warnings = fullAudit
+    ? []
+    : findings.filter(item => item.startsWith('verification expired '))
+  return { errors: findings.filter(item => !warnings.includes(item)), warnings }
+}