feat(workflow): doc-orphan-detector cron backstop (doc-sweep §4.7)#45
Merged
Conversation
Reusable workflow implementing the doc-sweep gh-cron backstop (doc-sweep spec §4.7). For every branch with no open PR, diffs origin/main...<branch>, collects changed paths matching the sweepable-docs allow-list (§4.1, case-insensitive, exclude wins ties), and — when the newest commit touching those paths is older than `stale-hours` (default 12; owner decision 2026-06-02, spec §4.3) — opens or updates a single idempotent tracking issue per branch listing the orphaned paths. Detection only: never commits, never pushes, reports paths only (file contents are never read). Mirrors anomaly-to-issue.yml structure: workflow_call with typed inputs, single job, least-privilege permissions (contents: read, issues: write), checkout@v4 fetch-depth: 0, github-script@v7. Closes #44 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
ArchonVII
marked this pull request as ready for review
June 5, 2026 03:00
This was referenced Jun 5, 2026
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
New reusable workflow
.github/workflows/doc-orphan-detector.yml— the doc-sweepgh-cron backstop (spec §4.7).
on: workflow_call, least-privilege (contents: read,issues: write). For every branch with no open PR, it diffsorigin/main...<branch>,keeps the §4.1 allow-list doc paths, and if their newest touching commit is older than
stale-hours(default 12) it opens/updates one idempotentDoc orphans: <branch>trackingissue. Detection-only: never commits/pushes, paths only — file contents are never read.
Consumers schedule it via a thin caller (
on: schedule) —archon-setupships that as thedoc-orphan-detectorcron opt-in oncev1is force-moved.Hardening from adversarial review (this PR)
scripts/doc-sweep/lib.mjs isSweepable):the original only excluded
docs/process/docs/architecture. It now applies the full §4.1hard-exclude (
src/**,scripts/**,.github/**,.githooks/**,.claude|.codex|.gemini/**,.agent/schema/**, governance*.md,package*.json, code/config exts, Docusaurusdocs/src|static/**),with exclude winning ties — so e.g.
src/logo.pngor.github/banner.svgare no longerfalsely flagged as doc orphans.
scripts/doc-orphan-detector.test.mjs): extracts the actual shippedinline classifier (the
classify-block) and exercises it against spec §7 fixtures, plusstructural invariants (workflow_call, least-priv permissions, detection-only). Because it lives
under
scripts/,self-test.ymlnow runs it in CI on this PR.Verification
Verification Notes
scripts/doc-orphan-detector.test.mjs(27 of the 104 tests) loads the workflow YAML, extracts the// classify-block:start … :endregion, builds the realisSweepableDocvianew Function, andasserts: docs/.changelog/.html-artifacts/images sweep;
docs/process,docs/architecture, code,governance, manifests, and images under hard-excluded roots do NOT; case-insensitive with exclude
winning ties. Structural tests assert
on: workflow_call,contents: read+issues: writeonly(no
contents: write/pull-requests: write), and that git is never invoked with a mutatingsubcommand and no content-reading API is used. The classifier is byte-faithful to the merged
runner so the cron detector and the local sweep agree path-for-path.
Note:
v1is intentionally not moved here — that owner force-move is the next rollout step,after which the detector is consumable at
@v1.Docs / Changelog
Detection-only reusable workflow; behavior documented inline + in the doc-sweep spec §4.7.
Closes #44