Scope documentation freshness checks to changed sources

[sirdeggen]

An unrelated PR currently fails when any documentation page passes its review deadline. For example, the wallet-relay change in #530 is blocked by the expired Chaintracks, WAB, wallet UTXO lifecycle, and generated service-operations pages.

This change enforces review expiry for edited pages and documentation associated with directly changed source paths. Package/shared-source and service associations come from the existing inventories; other page relationships are declared in the documentation policy. GitHub PRs use their merge-base diff, pushes use their before/after range, and local checks include branch and working-tree changes. Structural checks remain global, and an explicit --all command retains the full maintenance audit. The four unrelated expired pages retain their existing dates.

Draft blocker: current main has an unrelated expired nanoid-postcss-advisory-override exception (2026-09-13). It still fails repository health. This PR does not change dependency exceptions, extend their dates, or claim a green merge gate.

Program and scope

• Tracker or issue: Regression demonstrated by Tolerate a missed heartbeat and report socket closes in @bsv/wallet-relay #530, Add opt-in Mongo admission commit on Engine submit #525, and Harden BASM protocol validation and Merkle path offsets #520; documentation policy introduced in chore: enforce stack documentation and package coherence #374.
• Program gate(s) advanced: Change-scoped documentation review expiry.
• Why this change is needed: Elapsed deadlines for unrelated documentation must not prevent a contributor's code from reaching build/test CI.
• Explicitly out of scope: Dependency exception remediation, package or service changes, publication, and deployment.
• Exact head SHA reviewed: cae88a0.

Impact

• No public package source or manifest changed
• Public package source or manifest changed; affected packages are listed below
• Infrastructure source, dependency, image, or deployment configuration changed
• Public API, exports, types, runtime targets, or browser/mobile behavior changed
• Security-sensitive boundary changed
• Documentation or examples changed

Affected packages/services and intended patch versions: None. This changes repository CI policy, its documentation, and generated stack-facts review metadata. No published bytes or package manifests change; no SemVer bump or consumer migration is required.

Verification

• Local commands and results:
  • node --test scripts/documentation-freshness.test.mjs scripts/generated-documentation.test.mjs: 15 tests passed, covering unrelated and affected pages, shared sources, explicit full audits, deadline boundaries, invalid comparisons, PR divergence, pushes, renames, and local staged/unstaged/untracked files.
  • pnpm health:check: fails solely on the pre-existing expired nanoid-postcss-advisory-override; the documentation policy and other script tests pass. The remaining health commands were also run directly: contributor policy, generated operations, resource profiles, browser artifacts, compiler governance, licenses, and synchronized service policies pass; the final repository-health command reports the same expired exception.
  • pnpm lint, pnpm format:check, pnpm build, and pnpm typecheck: passed. Typecheck was rerun successfully after generating the workspace build outputs required by VeriFast's self-importing browser examples.
  • pnpm docs:facts:check, pnpm --filter docs-site test (7 tests), pnpm --filter docs-site validate, and pnpm docs:build: passed; 122 source pages validated and 127 rendered pages passed link checks.
  • pnpm audit:security: passed with the existing governed audit configuration; no dependency configuration changed.
  • node scripts/ci-affected-scope.mjs --base origin/main --head HEAD: selects documentation, with no affected packages or infrastructure.
  • node scripts/documentation-policy.mjs --base origin/main --head HEAD: 34 public READMEs, 45 package pages, 102 date records, only 3 affected pages checked for expiry, zero findings.
• Hosted CI run: CI for the exact head is terminal. The documentation test passes; repository health fails only on the existing dependency exception, causing downstream gates to fail/skip. The exact-head zero-new-Sonar-findings gate passes. Both CodeQL analyses and hosted conformance pass; the PR ref has zero open code-scanning alerts. This is not a successful complete merge gate; draft status retained.
• Conformance evidence: pnpm conformance passed structural validation of 77 files / 6,694 vectors; no protocol behavior changes.
• Coverage delta: Focused policy regression tests added; no package coverage changes.
• Lint/typecheck delta: No new warnings or errors after the workspace build.
• Browser/mobile/packed-consumer evidence: No package or consumer behavior changes; docs-site tests and build passed.
• Performance or bundle-size delta: Local Git path selection and source association checks only; no shipped bundle changes.
• I self-reviewed the complete diff for correctness, security,
  compatibility, public API, artifacts, dependencies, docs, and operations
• All applicable checks are terminal and successful on the exact head; any
  scope-based skip is expected and validated by the merge gate

Security and dependencies

• No dependency or lockfile change
• Changelog, runtime relevance, peer compatibility, transitive graph, and
  audit results were reviewed
• CodeQL/negative tests cover any changed trust boundary
• The exact-head CodeQL analysis has no new alert
• The exact-head repository quality gate reports zero new Sonar findings
  (including accepted or false-positive issue states) and zero unreviewed hotspots;
  Sonar's aggregate Quality Gate passed verdict alone is not merge evidence
• No new override, advisory dismissal, quality suppression, or skipped test
• Any temporary exception is registered with owner, evidence, review date,
  and removal condition
• Workflow permissions and lifecycle-script behavior remain least privilege

Git runs through /usr/bin/git with an argument array and no shell. Revision inputs are restricted to commit IDs/named refs with optional ancestry suffixes, then resolved with --verify --end-of-options. Invalid or unavailable comparisons fail explicitly. Tests cover invalid references, source-directory boundaries, and filenames containing whitespace/newlines. No workflow credentials or permissions change.

Dependency evidence

• Release notes and necessity: Not applicable; no dependency changes.
• Runtime, build, and peer compatibility: No supported runtime or peer contract changes.
• Deduplicated lockfile: Unchanged; frozen installation completed with lifecycle scripts disabled.
• Audit and CodeQL: Local audit and both hosted CodeQL analyses passed; zero open code-scanning alerts on the PR ref.
• Package and consumer tests: No packages selected by affected scope; workspace build/typecheck passed.
• Bundle and performance impact: No shipped package changes.
• Affected public package versions: None.

Release and operations

• No npm publication was performed from a workstation or from this PR
• Required npm patch bumps are included or intentionally deferred by the
  controlling program
• Image/SBOM/provenance/deployment/rollback impact is documented
• Documentation, changelog, migration, and operational guidance are current

No image, publication, or deployment changes. Contributor migration: default checks enforce elapsed review deadlines only for affected documentation; --base <ref> [--head <ref>] selects an explicit comparison and --all runs the full maintenance audit. Policy and maintenance guidance are updated together.

Completion evidence

• The linked tracker is updated only for work fully proved by merged code,
  passing checks, resolved alerts, measurements, or an approved exception
• Review conversations are resolved
• Documentation, changelog, migration notes, release notes, and operator
  guidance are current or concretely not applicable
• No pending, failed, stale, cancelled, or unexpectedly skipped check is
  being handed to another contributor as “complete”
• One qualified maintainer approval is sufficient; no last-pusher
  restriction is assumed

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud