Repository navigation
feat: Add doc-drift program (scanner, fixer, release assist) #12
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
jimcadden
wants to merge
6
commits into
rossoctl:main
Choose a base branch
from
jimcadden:cursor/doc-drift-v1
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
8d187ae
feat: Add doc-drift program (scanner, fixer, release assist)
jimcadden 19c75d1
fix: Vendor doc-drift review fixes from automation
jimcadden 2dff532
fix: Vendor doc-drift dead-code cleanup from automation
jimcadden 657d4f2
fix: Vendor the doc-drift engine from automation fa619090
jimcadden e37cb75
docs: Name doc-drift in the entrypoint allowlist
jimcadden 84ac95e
docs: Require a persistent doc-drift precheck worklist
jimcadden File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| name: shellcheck | ||
|
|
||
| on: | ||
| pull_request: | ||
| push: | ||
| branches: [main] | ||
|
|
||
| permissions: {} | ||
|
|
||
| jobs: | ||
| shellcheck: | ||
| runs-on: ubuntu-latest | ||
| permissions: | ||
| contents: read | ||
| steps: | ||
| - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 | ||
| - name: Install shellcheck | ||
| run: sudo apt-get update && sudo apt-get install -y shellcheck | ||
| - name: shellcheck (vendor tooling) | ||
| # Explicit paths — never a glob. Do not lint skills/repoman/scripts/ | ||
| # here; the engine is linted in rossoctl/automation. | ||
| run: shellcheck --severity=warning scripts/vendor-engine.sh tests/test-vendor-engine.sh |
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
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,63 @@ | ||
| --- | ||
| name: doc-drift-fixer | ||
| description: >- | ||
| Re-verify doc-drift scanner findings and open mechanical documentation fix | ||
| PRs. Corrections get their own docs: fix PR; additions fold into one rolling | ||
| update/doc-drift PR per repo. Never edits code to match docs, never merges, | ||
| never publishes a GitHub release. Use after a doc-drift scan. | ||
| license: Complete terms in LICENSE.txt | ||
| --- | ||
|
|
||
| # Doc Drift Fixer | ||
|
|
||
| Re-verify findings from the doc-drift scanner. Applies mechanical documentation | ||
| fixes on a fork and opens PRs. Non-mechanical findings stay on the rollup issue | ||
| checklist for a human. | ||
|
|
||
| **Run scripts with `--help` first.** Engine scripts live under the RepoMan | ||
| plugin scripts dir. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| - `bash` 3.2+ | ||
| - `python3` 3.8+ | ||
| - `gh` (authenticated; needs fork create + PR create) | ||
| - `jq` | ||
| - A prior scanner run that wrote `$HOME/reports/doc-drift/latest.json` | ||
| - `fork_owner` set in `~/.repoman/config.json` | ||
|
|
||
| ### Requirements (machine-readable) | ||
|
|
||
| - pat_scopes: [repo] | ||
| - labels_required: [doc-drift] | ||
| - labels_applied: [] | ||
| - programs: [fixer] | ||
|
|
||
| ## Running | ||
|
|
||
| Default is dry-run (preview only): | ||
|
|
||
| ```bash | ||
| bash "${CLAUDE_PLUGIN_ROOT}/skills/repoman/scripts/doc-drift-fixer.sh" --dry-run --issue-limit 5 | ||
| ``` | ||
|
|
||
| Live (opens PRs): | ||
|
|
||
| ```bash | ||
| bash "${CLAUDE_PLUGIN_ROOT}/skills/repoman/scripts/doc-drift-fixer.sh" --live | ||
| ``` | ||
|
|
||
| ## PR shapes | ||
|
|
||
| | Finding | Action | | ||
| |---------|--------| | ||
| | Mechanical correction (unique replacement) | Own PR: `docs: fix …` | | ||
| | Mechanical addition (enum gap, release draft) | Single rolling `update/doc-drift` PR per repo | | ||
| | Non-mechanical (absence-claim prose, retired name without replacement) | Rollup issue checklist only | | ||
| | Release date mismatch | Changelog heading PR only — does **not** edit the published GitHub release | | ||
| | Release draft | Rolling PR body includes paste-ready Keep a Changelog markdown | | ||
|
|
||
| ## Related | ||
|
|
||
| - Scanner skill: `doc-drift-scanner` | ||
| - Friendly name: **Doc-Drift-Manager** (`doc-drift`) |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,99 @@ | ||
| --- | ||
| name: doc-drift-scanner | ||
| description: >- | ||
| Scan enrolled repos for documentation drift against a pinned git boundary: | ||
| missing paths, flag/subcommand parity, configured enumerations, retired names, | ||
| version strings, absence claims, and changelog-vs-GitHub-release dates. Creates | ||
| one rollup issue per repo and writes structured JSON reports. Use when docs | ||
| may no longer match the code, or when drafting release notes from merged PRs. | ||
| license: Complete terms in LICENSE.txt | ||
| --- | ||
|
|
||
| # Doc Drift Scanner | ||
|
|
||
| Scan enrolled repositories for documentation that disagrees with the code at a | ||
| pinned git ref. Creates or updates one rollup `[doc-drift]` issue per repo and | ||
| writes `latest.json` / `history.json`. | ||
|
|
||
| **Run scripts with `--help` first** to see full usage and options. The engine | ||
| lives in the RepoMan plugin scripts dir — do not copy it into this skill. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| - `bash` 3.2+ (works with the macOS system default; no bash-4 features used) | ||
| - `python3` 3.8+ (stdlib only; no PyYAML) | ||
| - `gh` (GitHub CLI, authenticated with repo access) | ||
| - `jq` (JSON processor) | ||
| - RepoMan config at `~/.repoman/config.json` with enrolled clones under `repos_dir` | ||
|
|
||
| ### Requirements (machine-readable) | ||
|
|
||
| - pat_scopes: [repo] | ||
| - labels_required: [] | ||
| - labels_applied: [doc-drift] | ||
| - programs: [scanner] | ||
|
|
||
| ## Before Running | ||
|
|
||
| ### 1. Verify authentication | ||
|
|
||
| ```bash | ||
| gh auth status | ||
| ``` | ||
|
|
||
| ### 2. Ensure clones are current | ||
|
|
||
| Prefer `repoman run repo-sync` (or enable `repo-sync`) so scanners read fresh | ||
| trees. The run orchestrator refreshes clones for this program automatically. | ||
|
|
||
| ### 3. Confirm report location | ||
|
|
||
| Reports default to `$HOME/reports/doc-drift`. Override with `REPORTS_DIR`. | ||
|
|
||
| ## Running the Scanner | ||
|
|
||
| Always dry-run first: | ||
|
|
||
| ```bash | ||
| bash "${CLAUDE_PLUGIN_ROOT}/skills/repoman/scripts/doc-drift-scanner.sh" --dry-run | ||
| ``` | ||
|
|
||
| Live run (creates/updates/closes rollup issues): | ||
|
|
||
| ```bash | ||
| bash "${CLAUDE_PLUGIN_ROOT}/skills/repoman/scripts/doc-drift-scanner.sh" --issue-limit 5 | ||
| ``` | ||
|
|
||
| Or via the orchestrator: | ||
|
|
||
| ```bash | ||
| bash "${CLAUDE_PLUGIN_ROOT}/skills/repoman/scripts/repoman-run.sh" doc-drift --dry-run | ||
| ``` | ||
|
|
||
| ## Optional per-repo config | ||
|
|
||
| Repos may commit `.repoman/doc-drift.yaml` at the boundary ref to opt into | ||
| enumeration parity, retired-name denylists, and a custom changelog path. Without | ||
| it, only generic checks run (paths, flags, versions, absence claims, release | ||
| date/draft when GitHub metadata is supplied). | ||
|
|
||
| ## Precheck (DAM schedules) | ||
|
|
||
| `--worklist` is required. Pass a persistent path. The script's default path | ||
| sits in a temp directory that is removed on exit, so a bare run prints a | ||
| `worklist:` path that is already gone. | ||
|
|
||
| ```bash | ||
| mkdir -p "${REPORTS_DIR:-$HOME/reports/doc-drift}" | ||
| bash "${CLAUDE_PLUGIN_ROOT}/skills/repoman/scripts/doc-drift-precheck.sh" \ | ||
| --worklist "${REPORTS_DIR:-$HOME/reports/doc-drift}/worklist.json" | ||
| ``` | ||
|
|
||
| Exit `1` when the worklist is empty (skip the model turn). Exit `0` and print | ||
| `worklist: <path>` when there is work. Any other exit is fail-open. Read the | ||
| file at the `--worklist` path you passed; do not use the script's default. | ||
|
|
||
| ## Related | ||
|
|
||
| - Fixer skill: `doc-drift-fixer` | ||
| - Friendly name: **Doc-Drift-Manager** (`doc-drift`) | ||
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
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
Oops, something went wrong.
Oops, something went wrong.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
nit: "required" is accurate as a rule for callers, but nothing enforces it — the flag is optional and silently falls back to
$PROGRAM_TMPDIR/worklist.json, which theEXITtrap insetup_workspacedeletes. Verified: a bare run printsworklist: /tmp/doc-drift-precheck-XXXXXX/worklist.json, and that file is gone once the script returns; with--worklist "$REPORTS_DIR/worklist.json"the file survives with{count, findings[]}.So this doc is the right guardrail for now. The durable fix is upstream in
doc-drift-precheck.sh: default the worklist to$REPORTS_DIR(or exit non-zero instead of printing a path it is about to delete), otherwise the next caller that omits the flag hits the same silent dead end.