[doc-healer] DDUw improvement: auto-expired `not_planned` doc issues bypass both DDUw and doc-healer

[github-actions]

Context

The Daily Documentation Healer scan (2026-06-22) surfaced a recurring failure mode where persistent documentation deficits get auto-closed as not_planned by github-actions[bot] (expiry), and DDUw's 1c. Scan Recently Closed Documentation Issues step never acts on them because the spec only routes not_planned issues through code-change cross-referencing (Step 2).

When the gap is a pure documentation deficit (no triggering code change in the window), the issue effectively disappears.

Issues auto-expired as not_planned in the last 7 days where the gap is still real

Issue	Title	Gap status today
#39812	Add engine.extensions to engine-config schema + document (Pi engine)	Schema branch still lacks extensions; reference docs do not mention it
#39414	Add package doc comments to pkg/github and pkg/gitutil	No doc.go in either package
#39412	Port pkg/agentdrain/README.md into a doc.go	No pkg/agentdrain/doc.go
#39418	Document the WASM console API exports	Exports in pkg/console/console_wasm.go still lack doc comments
#39601	Quick-start: note CLAUDE_CODE_OAUTH_TOKEN unsupported + surface gh aw init --engine claude	quick-start.mdx still has neither line
#40337	Add AI-account sign-up links + which-engine recommendation to Quick Start prerequisites	Sign-up links present, no engine recommendation
#40321	CLI Consistency Issues - 2026-06-19	Already covered by the cookie rejection pattern in #39930

Rejection signal — do NOT auto-fix

The previous doc-healer run already attempted the docs-only fix direction for one of these gaps:

• PR #40171 (2026-06-19) targeted #40096 (the beginner-hostile < /path/to/token.txt snippet in Quick Start).
• @pelikhan closed PR [docs] Self-healing documentation fixes from issue analysis - 2026-06-19 #40171 without merging the same day.
• Issue [deep-report] Docs: replace beginner-hostile < /path/to/token.txt with an echo-pipe in Quick Start #40096 was closed as completed by @pelikhan, yet the broken docs lines remain on docs/src/content/docs/setup/quick-start.mdx:81 and :87 today.

This is a strong rejection signal for the docs-only fix direction on auto-expired persona/onboarding docs issues. Per the doc-healer spec, this run is not re-attempting any of the gaps above — escalating to maintainer instead.

Why DDUw missed this class of issues

.github/workflows/daily-doc-updater.md step 1c handles not_planned issues like this:

closed as not_planned: Do not create documentation based solely on this issue. Instead, cross-reference the issue's subject matter against commits from the same 7-day window (Step 2). If a related code change is found, treat it as a new documentation gap...

This correctly avoids acting on rejected fix directions, but it leaves a blind spot: standalone documentation-coverage deficits (godoc package comments, undocumented features, persona-onboarding gaps) that have no triggering code change are simply dropped.

Proposed direction (maintainer decision needed)

@pelikhan — please pick one:

1. Accept docs-only fixes for these deficits — confirm that future doc-healer / DDUw runs may open PRs for auto-expired not_planned issues that describe pure documentation gaps with an unambiguous fix direction (e.g., add a missing doc.go).
2. Reject docs-only fixes for these deficits — confirm these classes of issues are intentionally being auto-expired without action. In that case, DDUw step 1c should be tightened to explicitly skip auto-expired not_planned issues from the scan output entirely so doc-healer doesn't keep re-surfacing them.
3. Code-side fix preferred — for [deep-report] Add engine.extensions to engine-config schema + document (Pi engine) #39812 in particular, the inverse direction is to update pkg/parser/schemas/main_workflow_schema.json to allow extensions in engine-config branches; that is a code/schema change, not docs. Confirm whether the schema fix should be opened by a different agent.

Suggested DDUw rule additions (after maintainer direction)

If option 1 is selected, add a new sub-step to DDUw 1c for not_planned issues:

If the issue describes a pure documentation-coverage deficit (missing doc.go, undocumented exported symbols, missing reference page for a documented feature) and the fix direction is unambiguous (the issue body names the exact file and the missing content), apply the fix and reference the issue with Closes #NNN. Skip if the issue is a persona / onboarding gap (those go through doc-healer maintainer escalation, per the #40171 rejection).

If option 2 is selected, add to DDUw 1c:

Skip not_planned issues closed by github-actions[bot] (expiry auto-close) entirely — do not cross-reference against commits, do not include in scan output. They are intentionally expired by the workflow system, not signals of work to do.

References

• Rejected docs-only PR: #40171
• Prior maintainer-decision issue (CLI consistency pattern): #39930
• DDUw workflow: .github/workflows/daily-doc-updater.md

Generated by 📝 Daily Documentation Healer · 379.3 AIC · ⊞ 6.9K · ◷

• expires on Jun 24, 2026, 4:16 PM UTC-08:00