feat: add doc-freshness agentic workflow#190
Open
EMaher wants to merge 12 commits into
Open
Conversation
Adds a weekly GitHub agentic workflow that detects documentation drift by comparing recent source changes against documentation. The agent: - Reads commits from the last 7 days on main - Compares CLI --help output against README/docs - Files up to 3 advisory [Doc Drift] issues (deduplicated by title) - Labels: type:documentation, squad:docwriter - Fire-and-forget: no auto-assign, no reminders, no auto-close Human gate is post-hoc: maintainer reviews each filed issue and either creates a docs-update PR or closes with docs:no-action-needed. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Instead of hard-coding 'last 7 days', the workflow now queries for the most recent [Doc Drift] issue creation date and uses that as the lookback window. Falls back to 7 days if no prior issues exist. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Adds timeout-minutes: 10 to frontmatter and tightens agent instructions: - Limit to 20 most recent commits - Stop after finding 3 drift items - Exit immediately if no drift apparent Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Instead of one issue per drift finding (max 3), issues are now grouped: - Source drift: all undocumented src/ changes consolidated into 1 issue - Docs drift: all stale doc references consolidated into 1 issue Max 2 issues per run, each covering all findings for its group. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Temporarily adds a push trigger on emaher-doc-freshness-workflow to test the agentic workflow before merge. WILL BE REVERTED before merge. Also fixes gh aw compile errors so the workflow builds: - remove invalid 'add-comment: max: 0' (omitting disables comments) - 'issues: write' -> 'issues: read' (safe-outputs handles issue creation) - switch cron to fuzzy schedule 'weekly on monday' - move since_date into env to avoid shell-injection auto-rewrite
Adds 'copilot-requests: write' so the Copilot engine uses the built-in GITHUB_TOKEN instead of a COPILOT_GITHUB_TOKEN PAT secret. Requires org centralized Copilot billing. Temporary push trigger still active for testing.
The gh-aw agent job checks out only the triggering ref, so 'git log origin/main' failed with exit 128 (unknown revision). Explicitly fetch main into refs/remotes/origin/main first. Temporary push trigger still active.
Copilot stopped work on behalf of
EMaher due to an error
June 27, 2026 00:52
Reverts the test-only push trigger now that the agentic workflow run succeeded end-to-end. Workflow runs on schedule (weekly on monday) and workflow_dispatch, using Actions token-based inference (no PAT).
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new GitHub Agentic Workflow to proactively detect documentation drift by inspecting recent commits, capturing CLI --help output, and filing advisory issues when docs appear out of date.
Changes:
- Introduces the doc-freshness agent workflow definition and prompt (
doc-freshness.md). - Adds the compiled/pinned workflow lock file (
doc-freshness.lock.yml) produced bygh aw compile. - Updates repo metadata to treat workflow lock files as generated and resolve merge conflicts predictably.
Reviewed changes
Copilot reviewed 3 out of 4 changed files in this pull request and generated 7 comments.
| File | Description |
|---|---|
| .github/workflows/doc-freshness.md | Source agentic workflow: schedule, safe-outputs policy, context preparation steps, and the agent prompt. |
| .github/workflows/doc-freshness.lock.yml | Compiled workflow with pinned actions/containers and safe-outputs enforcement. |
| .github/aw/actions-lock.json | Pins the github/gh-aw-actions/setup action version/SHA for compilation/runtime consistency. |
| .gitattributes | Marks *.lock.yml as generated and configures merge strategy for those files. |
- Pin Node to 22 via runtimes.node.version (comment 6) - Remove '|| true' masking in CLI help step so failures surface (comment 5) - Migrate housekeeping safe-outputs to new gh-aw schema: missing-tool/missing-data/report-incomplete use create-issue: false, add report-failure-as-issue: false (old report-as-issue syntax now invalid) - TEMP push trigger to validate run before merge (revert before merge)
…hness The 'Gather CLI help output' step ran 'npm ci --ignore-scripts', which skips the prebuild/prelint/pretest hooks that generate src/templates/generated/ embedded-markdown.js. Without it the CLI aborts with ERR_MODULE_NOT_FOUND, so 'npx tsx src/cli/index.ts --help' exited non-zero. Previously '|| true' masked this and fed the agent empty CLI context (the issue comment 5 flagged). Add an explicit 'node scripts/embed-markdown-templates.mjs' step after npm ci so the CLI loads correctly and the help step fails loudly on real breakage.
Revert the test-only push trigger now that the workflow run validated the comment 5/6 fixes (Node 22, fail-loud CLI help, embedded-template generation). Restores schedule + workflow_dispatch only.
Contributor
Author
|
related to #90 |
petehauge
approved these changes
Jun 29, 2026
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
Adds a weekly GitHub agentic workflow (
.github/workflows/doc-freshness.md) that detects documentation drift by comparing recent source changes against documentation.What it does
The agent runs every Monday at 09:00 UTC and:
main--helpoutput for all commandsdocs/*, andspecs/*[Doc Drift]issues (deduplicated by title)Safe outputs
create-issue: title prefix[Doc Drift], labelstype:documentation, max 2, deduplicate by titleHuman gate (post-hoc)
Issues are filed automatically. Maintainer reviews each and either:
docs:no-action-needed, comments rationale, closesExclusions (agent will NOT flag)
Prerequisites
The following labels must exist before the first run:
type:documentationRelated
Fire-and-forget model: once issues are filed, no further automation touches them.