[doc-healer] Decision needed: antigravity engine docs-fix direction was rejected — record exclusion in code

[github-actions]

Context

The Daily Documentation Healer surfaced #42282 ([deep-report] [quick-win] "Document the antigravity engine in engines.md"), a DeepReport-filed docs issue auto-closed not_planned by github-actions[bot] on 2026-07-01 via its expiry sticker. It reports a real gap: the antigravity engine is registered (pkg/workflow/agentic_engine.go:494 -> NewAntigravityEngine()) and used in production (.github/workflows/smoke-antigravity.md sets engine.id: antigravity), but docs/src/content/docs/reference/engines.md has 0 mentions of it.

Rejection signal

The healer would normally fix this by editing engines.md. But that exact docs fix was already attempted and rejected:

PR #42294 (Copilot) — "Document Antigravity engine support in reference docs and schema guidance" — added Antigravity to the engines.md supported-engine table, a focused Antigravity section, the version/feature matrices, main_workflow_schema.json $defs.engine_config, and ANTIGRAVITY_API_KEY to auth.mdx. It was closed unmerged by @pelikhan at 2026-06-29T18:14:20Z (repository admin collaborator, verified via collaborators/pelikhan/permission -> admin). No rejection comment or review was left. Per healer rules, a closed-unmerged [docs] PR from an admin is a strong rejection signal for the docs-only direction, so the healer will not re-attempt the engines.md change.

Why this is not a normal "experimental engine" gap

Antigravity carries experimental: true (pkg/workflow/antigravity_engine.go:25) — but so do crush, opencode, and pi, and all three are documented in engines.md (lines 20-22, tagged "(experimental)"). So "experimental" does not explain the exclusion. Antigravity is the only registered engine deliberately kept out of the reference, which indicates an intentional maintainer decision that is not recorded anywhere in code or docs.

Unresolved drift (verified against main, 2026-07-02)

$ grep -ci antigravity docs/src/content/docs/reference/engines.md
0

$ grep -n 'NewAntigravityEngine' pkg/workflow/agentic_engine.go
494:  NewAntigravityEngine(),

$ grep -n 'experimental:' pkg/workflow/antigravity_engine.go
25:  experimental:     true,

Because nothing in code marks antigravity as intentionally undocumented, automated drift detectors keep re-filing the same reconciliation request. This is not a one-off: the companion schema issue #42787 ("Add antigravity to built-in engine list in main_workflow_schema.json") is still open, filing the identical drift against the schema surface. Left as-is, DeepReport / schema-consistency will regenerate this pair indefinitely, and each cycle costs a healer/DDUw investigation to re-derive the same rejected conclusion.

Proposed inverse fix direction

Since expanding the docs/schema to include antigravity was rejected, the inverse direction is a code change that records the exclusion as intent, so detectors stop flagging it:

1. Add an undocumented (or hidden) boolean to the engine's BaseEngine config, defaulting false, and set it true in NewAntigravityEngine().
2. Have the DeepReport / schema-consistency drift checks that compare "registered engines" against "engines listed in engines.md / main_workflow_schema.json" skip engines where undocumented == true. This turns the current false-positive into a no-op instead of a recurring issue.
3. No engines.md or schema change is required — the exclusion becomes the documented, enforced expectation.

This aligns the detectors with the maintainer's decision rather than re-expanding the doc surface that was just rejected.

Decision needed

@pelikhan — your call on direction for the antigravity engine visibility:

• Option A (code change, default per rejection signal): add an undocumented: true marker to the antigravity engine and teach the drift detectors to skip marked engines. Healer/DDUw will not re-attempt the docs fix, and [deep-report] [quick-win] Document the antigravity engine in engines.md #42282 / [deep-report] [quick-win] Add antigravity to built-in engine list in main_workflow_schema.json #42787-class issues stop regenerating.
• Option B (docs change after all): the close of PR Document Antigravity engine support in reference docs and schema guidance #42294 was accidental — antigravity should be documented like the other experimental engines. Re-affirm and the fix can be refiled (this also resolves open [deep-report] [quick-win] Add antigravity to built-in engine list in main_workflow_schema.json #42787).
• Option C (something else): antigravity is on its way out / internal-only for a reason not captured here — say so and we'll scope accordingly.

Replying A/B/C is enough. Whichever path, it should drive a follow-up change rather than letting the drift regenerate every DeepReport cycle. Note: open schema issue #42787 should be resolved by the same decision.

Other closed documentation issues reviewed in this run

The other 21 documentation-labeled issues closed in the last 7 days are all automated recurring reports ([cli-consistency], [Daily Report], [PR Triage], [agentic-token-audit], prior [doc-healer] meta-issues) or multi-device testing reports — none carry a doc-content fix path.

Artifact constant audit: all 11 ArtifactName constants in pkg/constants/constants.go and pkg/constants/job_constants.go (firewall-audit-logs, safe-output, agent-output, agent, detection, threat-detection.log, activation, experiment, usage, safe-outputs-items, code-scanning-sarif) are documented in docs/src/content/docs/reference/artifacts.md. No drift.

No site-build/UI issues were encountered this run.

DDUw improvement

DDUw does not currently detect that a drift issue's fix direction was already rejected via a closed-unmerged [docs] PR before it re-attempts the same edit. Concretely, add a pre-fix sub-step: for each candidate drift, search for prior PRs touching the same file/keyword (is:pr is:closed is:unmerged, authors github-actions[bot] / Copilot / copilot-swe-agent) closed by a repository collaborator; if found, treat the docs-only direction as rejected and escalate an inverse-fix decision issue instead of editing. This prevents both DDUw and the healer from burning a run re-deriving a rejected conclusion, and would have caught the antigravity case directly.

Generated by 📝 Daily Documentation Healer · 304.5 AIC · ⌖ 38.6 AIC · ⊞ 7.6K · ◷

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

[github-actions]

This issue was automatically closed because it expired on 2026-07-05T00:14:43.666Z.

Closed by Workflow