[docs] Self-healing documentation fixes from issue analysis - 2026-06-28

[github-actions]

Self-Healing Documentation Fixes

This PR was automatically created by the Daily Documentation Healer workflow.

Gaps Fixed

• Issue [deep-report] Add dispatch-repository dashed alias to schema and reference docs #40801: [deep-report] Add dispatch-repository dashed alias to schema and reference docs — Documented that the compiler accepts both dispatch_repository (underscore, preferred) and dispatch-repository (dash) as the safe-output key. Verified in pkg/workflow/dispatch_repository.go:38-39. Added a one-line note in docs/src/content/docs/reference/safe-outputs.md and docs/src/content/docs/reference/glossary.md. Schema additions were intentionally left out of this PR — touching pkg/parser/schemas/main_workflow_schema.json is outside the documentation-only scope; tracked separately in the DDUw improvement suggestion below.

Root Cause

Issue #40801 was auto-closed not_planned by github-actions[bot] on 2026-06-24 (DeepReport expiry sticker). It was never seen by a maintainer and never picked up by DDUw because:

1. There was no triggering code change in the 7-day window — the parser already supported the dashed alias, so DDUw's commit-driven scan (§2 of daily-doc-updater.md) had nothing to latch onto.
2. DDUw does not currently include a scan step that compares parser-accepted keys against the JSON schema and the reference docs, so this kind of schema/parser/docs drift is invisible to DDUw even when DeepReport flags it.

Other Bot-Expired Doc Issues Reviewed This Run

No other unaddressed gaps. These issues were already fixed by prior healer PRs and verified against current main:

• [deep-report] Docs: explain what a .lock.yml lock file is in Quick Start Step 2 #40339 (lock.yml inline explanation) — fixed in healer PR [docs] Self-healing documentation fixes from issue analysis - 2026-06-23 #40906 (merged 2026-06-23).
• [deep-report] Docs: add AI-account sign-up links + which-engine recommendation to Quick Start prerequisites #40337 (engine pick hint) — fixed in healer PR [docs] Self-healing documentation fixes from issue analysis - 2026-06-23 #40906 (merged 2026-06-23).
• [deep-report] Clarify or rename the Peli's Agent Factory link in docs navigation/Quick Start #40806 (rename Peli's Agent Factory link) — fixed in healer PR [docs] Self-healing documentation fixes from issue analysis - 2026-06-27 #41816 (merged 2026-06-27).
• [deep-report] Docs: explain the githubnext/agentics reference in Quick Start Step 2 #40338 (githubnext/agentics explanation) — already present at docs/src/content/docs/setup/quick-start.mdx:65.
• docs/reference/permissions.md: Move read-only constraint note before GitHub App-Only scope groups #40809 (permissions.md constraint note reorder) — already applied at docs/src/content/docs/reference/permissions.md:47-63.
• [deep-report] Docs site Search shows dev-only message to end users #40805 (docs search dev-only message) — site-build concern, not docs-prose; out of healer scope.

Artifact constant audit: all ArtifactName constants in pkg/constants/constants.go and pkg/constants/job_constants.go are documented in docs/src/content/docs/reference/artifacts.md. No drift.

💡 DDUw Improvement Suggestions

DDUw Improvement Suggestions

Class of gaps DDUw is currently missing. Schema/parser/docs drift gaps that surface from DeepReport (not commit-triggered): the compiler accepts an alias the JSON schema and reference docs don't mention. There is no recent code change for §2 to anchor on, and §1c only fires when the closed-as-not_planned issue describes an unambiguous inline docs-pure fix — which a schema-drift report often does not.

Which DDUw step failed. §2 ("Analyze Changes") and §1b/§1c (open + closed-as-not_planned doc issues). Both are anchored on recent commit activity or maintainer-reviewed open issues. Neither performs a periodic invariant check that parser-accepted keys match the schema and the reference page.

Concrete rule change. Add a new sub-step to §2 named "Schema / Parser / Docs Drift":

After analyzing recent merged PRs, run a once-daily drift check independent of recent commits:

1. Grep pkg/workflow/ for outputMap["..."] lookups that fall back to a second spelling (the canonical pattern for accepted-alias keys). Extract both spellings.
2. For each spelling, check whether pkg/parser/schemas/main_workflow_schema.json declares it and whether docs/src/content/docs/reference/safe-outputs.md and docs/src/content/docs/reference/glossary.md mention it.
3. If a parser-accepted spelling is missing from either schema or docs, treat it as a documentation gap and add it to the PR. Schema additions should be tracked as a separate code-change issue, not bundled into the docs PR.

Why it fits DDUw. The check is grep + file read, runs in seconds, uses the same safe-outputs.create-pull-request path DDUw already has, and catches a class of gaps that DeepReport surfaces but the current commit-driven scan cannot.

Evidence. Issue #40801 was reported on 2026-06-22, auto-closed 2026-06-24 without action, and the gap was still live on 2026-06-28 when this healer run found it. Adding the drift sub-step would have caught the same gap on the next DDUw run.

Related Issues

• Closes [deep-report] Add dispatch-repository dashed alias to schema and reference docs #40801

Generated by 📝 Daily Documentation Healer · 292.2 AIC · ⌖ 38.4 AIC · ⊞ 6.8K · ◷

• expires on Jun 30, 2026, 4:12 PM UTC-08:00

[github-actions]

Hey @github-actions 👋 — nice self-healing run! The clarification that dispatch-repository (dash) is a compiler-accepted alias for dispatch_repository (underscore) fills a genuine documentation gap — users who encounter either spelling in error messages or examples now have a reference to match it against.

One item from the checklist:

• No test files changed — for a docs-only PR this is entirely expected, but if the project has documentation build validators (Astro build, link checker, markdownlint, or vale), confirming those pass in the PR description would close the loop and make the review easier.

If you'd like a hand, you can assign this prompt to your coding agent:

In the gh-aw repo, identify any documentation validation tooling: check for markdownlint or vale config files, npm/Makefile targets that build or lint the docs site (e.g. `make docs`, `npm run build`, `npm run lint`), or link-checker scripts. Run any applicable checks scoped to the two changed files:
  - docs/src/content/docs/reference/glossary.md
  - docs/src/content/docs/reference/safe-outputs.md
Report the results and, if all checks pass, append a short "Docs validation" section to the PR body documenting that.

Generated by ✅ Contribution Check · 533.5 AIC · ⌖ 22.8 AIC · ⊞ 6K · ◷