[doc-healer] DDUw improvement: record intentional engine-doc exclusions so antigravity drift stops recurring

[github-actions]

Overview

A class of documentation "gaps" keeps getting re-filed and re-attempted even though a maintainer has intentionally rejected the fix. The antigravity engine is registered and used in production (.github/workflows/smoke-antigravity.md, pkg/constants/engine_constants.go) but is deliberately absent from docs/src/content/docs/reference/engines.md. Because that intent lives nowhere in code, every drift detector (DeepReport, schema-consistency, discussion-task-miner, DDUw, and this doc-healer) keeps re-discovering the same "gap."

This run detected closed documentation issue #46434 ("Add Antigravity engine to engines.md", closed NOT_PLANNED) and confirmed the gap still exists in the tree — but the fix direction has been repeatedly rejected. Per doc-healer rules, the docs fix was not re-attempted.

Rejection evidence

@pelikhan (repo admin) has closed every attempt at both fix directions, unmerged:

PR	Direction	Closed by
#42294	docs: add antigravity to engines.md	pelikhan
#45451	docs: add antigravity to schema + engine docs	(bot PR, closed unmerged)
#44480	docs: add antigravity rows/columns to engines.md	(bot PR, closed unmerged)
#42848	code: record exclusion via IsUndocumented() / GetDocumentedEngines()	pelikhan

PR #42848's own description states it plainly: "a docs PR (#42294) adding it was closed unmerged by a maintainer. Because nothing in code recorded this intent, drift detectors kept re-filing the same reconciliation issues each cycle." That code fix was also closed unmerged, so the loop continues. To date, 22 issues match Antigravity engine engines.md.

Root cause

DDUw (and its companion detectors) reconcile engines.md against the full set of registered engines (GetSupportedEngines() / AgenticEngines). There is no notion of an intentionally undocumented engine, so antigravity always reads as missing. The exclusion decision is social (a maintainer's repeated PR closures) rather than machine-readable, so automation cannot see it.

Proposed next step (maintainer decision needed)

@pelikhan — the recurring drift will not stop until the exclusion intent is encoded somewhere automation reads. Two options, 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 and have drift detectors compare engines.md against documented engines only. This makes the exclusion the enforced expectation and silences all detectors at once.
2. Maintain an explicit skip-list that DDUw and the task-miner read (e.g. an undocumented-engines entry in a config the detectors consult), if you prefer to keep the engine definitions untouched.

Either closes the loop; without one, this issue will keep recurring. If neither is desired and antigravity should in fact be documented, say so and the docs PR can be re-opened.

DDUw improvement suggestions

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

DDUw's Step 2 ("Analyze Changes") and Step 4 ("Identify Documentation Gaps") treat every registered engine/schema field as documentable. Add a guard so intentional exclusions are respected:

• New scan rule under "Removed Features in Docs" / gap identification: Before flagging a registered engine as a missing engines.md row, check whether it is marked undocumented. Reconcile engines.md against a documented-engines set, not the full registry. If the code exposes GetDocumentedEngines() (per option 1 above), call that; otherwise consult the skip-list (option 2).
• Rejection-awareness rule: 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, treat the direction as rejected and open a maintainer-decision issue instead of editing — mirroring the guidance already at line 168 of the workflow, but extended to cover cross-run rejection signals, not just in-run convention ambiguity.
• Wording to add near the engine-example guidance (lines 373-374): "Some registered engines are intentionally undocumented (e.g. antigravity). Never add a registered engine to engines.md solely because it appears in the engine registry; confirm it belongs to the documented set first."

Next actions

• @pelikhan to choose option 1 (code flag) or option 2 (skip-list) — or confirm antigravity should be documented after all.
• Apply the chosen mechanism so engines.md reconciliation uses the documented-engine set.
• Add the DDUw guard wording above so the detector stops re-filing.

References:

• Rejected code fix: Add undocumented marker to BaseEngine; record antigravity exclusion decision in code #42848
• Rejected docs fixes: 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
• Latest recurrence: [Code Quality] Add Antigravity engine to docs/src/content/docs/reference/engines.md #46434
• §29708758202

Generated by 📝 Daily Documentation Healer · 234.1 AIC · ⌖ 37.4 AIC · ⊞ 8.2K · ◷

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