Skip to content

feat(workflow): doc-orphan-detector cron backstop (doc-sweep §4.7)#45

Merged
ArchonVII merged 3 commits into
mainfrom
agent/claude/44-doc-orphan-detector
Jun 5, 2026
Merged

feat(workflow): doc-orphan-detector cron backstop (doc-sweep §4.7)#45
ArchonVII merged 3 commits into
mainfrom
agent/claude/44-doc-orphan-detector

Conversation

@ArchonVII

@ArchonVII ArchonVII commented Jun 5, 2026

Copy link
Copy Markdown
Owner

Summary

New reusable workflow .github/workflows/doc-orphan-detector.yml — the doc-sweep
gh-cron backstop (spec §4.7). on: workflow_call, least-privilege (contents: read,
issues: write). For every branch with no open PR, it diffs origin/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 idempotent Doc orphans: <branch> tracking
issue. Detection-only: never commits/pushes, paths only — file contents are never read.

Consumers schedule it via a thin caller (on: schedule) — archon-setup ships that as the
doc-orphan-detector cron opt-in once v1 is force-moved.

Hardening from adversarial review (this PR)

  • Classifier now mirrors the canonical runner (scripts/doc-sweep/lib.mjs isSweepable):
    the original only excluded docs/process/docs/architecture. It now applies the full §4.1
    hard-exclude (src/**, scripts/**, .github/**, .githooks/**, .claude|.codex|.gemini/**,
    .agent/schema/**, governance *.md, package*.json, code/config exts, Docusaurus docs/src|static/**),
    with exclude winning ties — so e.g. src/logo.png or .github/banner.svg are no longer
    falsely flagged as doc orphans.
  • Test coverage added (scripts/doc-orphan-detector.test.mjs): extracts the actual shipped
    inline classifier
    (the classify-block) and exercises it against spec §7 fixtures, plus
    structural invariants (workflow_call, least-priv permissions, detection-only). Because it lives
    under scripts/, self-test.yml now runs it in CI on this PR.

Verification

  • vitest suite (full repo) green
$ npm test
 Test Files  6 passed (6)
      Tests  104 passed (104)
  • actionlint clean on the workflow
$ actionlint .github/workflows/doc-orphan-detector.yml
(exit 0, no output)

Verification Notes

scripts/doc-orphan-detector.test.mjs (27 of the 104 tests) loads the workflow YAML, extracts the
// classify-block:start … :end region, builds the real isSweepableDoc via new Function, and
asserts: 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: write only
(no contents: write/pull-requests: write), and that git is never invoked with a mutating
subcommand 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: v1 is 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

ArchonVII and others added 3 commits June 4, 2026 21:48
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
ArchonVII marked this pull request as ready for review June 5, 2026 03:00
@ArchonVII
ArchonVII merged commit 00bec97 into main Jun 5, 2026
1 check passed
@ArchonVII
ArchonVII deleted the agent/claude/44-doc-orphan-detector branch June 5, 2026 04:10
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.

feat(workflow): doc-orphan-detector cron backstop (doc-sweep §4.7)

1 participant