[doc-healer] DDUw improvement: antigravity engine-doc drift re-escalation (13 re-files in 7 days, prior escalation #46688 expire [Content truncated due to length]

[github-actions]

Overview

The antigravity engine drift loop is accelerating, not resolving. In the last 7 days alone, 13 documentation issues were closed that re-file the same "add antigravity to engines.md" gap (search: label:documentation Antigravity engines.md closed:>=2026-07-18). The engine remains intentionally absent from docs/src/content/docs/reference/engines.md (confirmed still missing today), yet every drift detector keeps re-discovering it.

This re-escalates prior doc-healer issue #46688, which correctly diagnosed the root cause but was auto-closed (expired) by github-actions[bot] on 2026-07-23 without a maintainer decision — so the loop was never closed. Per doc-healer rules, the docs fix was not re-attempted this run; the fix direction has been repeatedly rejected by a maintainer.

Why this keeps recurring

The antigravity engine is registered and used in production (.github/workflows/smoke-antigravity.md, pkg/constants/engine_constants.go) but deliberately excluded from user-facing engine docs. That exclusion intent is social (repeated maintainer PR closures) rather than machine-readable, so DDUw and its companion detectors — which reconcile engines.md against the full registered-engine set — always read it as a missing row.

Prior rejection evidence (from #46688): PRs #42294, #45451, #44480 (docs direction) and #42848 (code direction) were all closed unmerged. Both fix directions have been rejected, so neither a docs PR nor the previously-proposed code change should be re-attempted without a fresh maintainer call.

Which DDUw step fails

• Step 2 (Analyze Changes) and Step 4 (Identify Documentation Gaps) in .github/workflows/daily-doc-updater.md treat every registered engine as documentable. grep -in "antigravity\|undocumented\|exclusion\|skip.list\|documented.engine\|rejection" over that file returns zero matches — DDUw has no notion of an intentionally-undocumented engine and no rejection-awareness.
• Step 1c (Scan Recently Closed Documentation Issues) re-opens the gap analysis for not_planned issues without checking whether the same fix direction was already closed unmerged.

Proposed next step — maintainer decision needed

@pelikhan — this will not stop until the exclusion intent is encoded where automation reads it. Same two options as #46688, still your call:

1. Record the exclusion in code (revive the Add undocumented marker to BaseEngine; record antigravity exclusion decision in code #42848 approach): add an undocumented flag to the antigravity engine definition; have detectors reconcile engines.md against a GetDocumentedEngines() set rather than the full registry. Silences all detectors at once.
2. Maintain an explicit skip-list that DDUw and the task-miner consult (e.g. an undocumented-engines config entry), if you prefer to leave engine definitions untouched.

If neither is desired and antigravity should be documented, say so and the docs PR can be re-opened. Escalating the uncertainty here rather than suppressing retries silently, since the prior escalation expired unanswered.

💡 Concrete changes to .github/workflows/daily-doc-updater.md

• Undocumented-engine guard (Step 4): Before flagging a registered engine as a missing engines.md row, reconcile against a documented-engines set, not the full registry. Call GetDocumentedEngines() if option 1 lands; otherwise consult the skip-list (option 2).
• Rejection-awareness rule (Step 1c / Step 4): Before opening or re-attempting any docs fix, search for a prior closed-unmerged PR touching the same file + feature term. If one exists and was closed by a repo collaborator with directional review comments, do not re-attempt; record it in Skipped Issues and stop.
• Escalation durability: When a doc-healer improvement issue about the same recurring drift has already been auto-expired without a maintainer response, DDUw should not silently re-file the underlying gap; instead surface the still-open escalation so it is not lost to expiry.

Related

• Re-escalates [doc-healer] DDUw improvement: record intentional engine-doc exclusions so antigravity drift stops recurring #46688 (auto-expired without decision)
• Representative re-files this window: [Code Quality] Add Antigravity engine to engines reference documentation #47655, [Code Quality] Add antigravity engine to engines reference documentation #47579, [Code Quality] Add Antigravity engine to user-facing docs and schema built-in engine catalog #47521, [Code Quality] Add antigravity engine to schema built-in engine catalog and engine reference docs #47388, [Code Quality] Add antigravity engine to docs and JSON schema engine catalog #47306, [Code Quality] Add antigravity engine to schema examples and engines.md documentation #47014, [Code Quality] Add antigravity engine to docs and schema built-in engine catalog #46915, [Code Quality] Add antigravity engine to schema built-in engine catalog and reference docs #46842
• Rejected fix PRs: Document Antigravity engine support in reference docs and schema guidance #42294, Add Antigravity to workflow schema and engine docs #45451, [WIP] Document antigravity engine in engines.md and fix stale built-in engine comments #44480, Add undocumented marker to BaseEngine; record antigravity exclusion decision in code #42848

Generated by 📝 Daily Documentation Healer · haiku45 · 209.5 AIC · ⌖ 40.4 AIC · ⊞ 8.2K · ◷

• expires on Jul 27, 2026, 4:08 PM UTC-08:00

[github-actions]

This issue was automatically closed because it expired on 2026-07-28T00:08:33.716Z.

Closed by Workflow