[docs] Self-healing documentation fixes from issue analysis - 2026-05-19

[github-actions]

Self-Healing Documentation Fixes

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

Gaps Fixed

• Issue #33081: Reconcile schema/parser/compiler drift: tools.serena and engine.bare — the tools.serena half was already resolved (pkg/parser/mcp.go:237 now returns an error), but the engine.bare half was still drifting. The Engine Feature Comparison table in docs/src/content/docs/reference/engines.md:43 claimed engine.bare was supported (✅) for Codex and Gemini. The compiler only honors bare mode for Copilot and Claude — see validateBareModeSupport at pkg/workflow/agent_validation.go:229 and TestSupportsBareMode at pkg/workflow/engine_config_test.go:934-967, which assert that Codex and Gemini return BareMode: false and therefore receive a compile-time warning with no behavioral effect. The companion "Bare Mode" effects table at lines 329-334 also listed --no-system-prompt for Codex and GEMINI_SYSTEM_MD=/dev/null for Gemini, which are never injected (verified by TestBareMode_UnsupportedEngineWarningIntegration at pkg/workflow/engine_args_integration_test.go:345).

Changes

• docs/src/content/docs/reference/engines.md
  • Feature matrix row: changed Codex and Gemini cells for engine.bare from ✅ to ❌ to match pkg/workflow/copilot_engine.go:46 and pkg/workflow/claude_engine.go:34 (the only two engines with BareMode: true).
  • Bare Mode effects table: removed the Codex and Gemini rows (those flag injections never occur) and replaced them with a NOTE callout explaining that engine.bare is honored only for copilot and claude.

Root Cause

DDUw never compared the engine feature matrix in docs/src/content/docs/reference/engines.md against the in-code Capabilities declarations in pkg/workflow/*_engine.go. Step 2's "Removed Features in Docs" check targets schema-driven removals (frontmatter properties that no longer exist), not capability/support-matrix entries. Step 1c saw issue #33081 closed as not_planned but the daily-doc-updater rules only require cross-referencing not_planned issues against recent commits — and there were no recent commits on the bare-mode surface, so the drift fell through. Net effect: the docs/code disagreement persisted across five consecutive daily passes.

💡 DDUw Improvement Suggestions

DDUw Improvement Suggestions

Add a new sub-step (proposed: Step 1e — Engine Capability Matrix Audit) to .github/workflows/daily-doc-updater.md:

1. Parse docs/src/content/docs/reference/engines.md and extract the Engine Feature Comparison table.
2. For each capability column (BareMode, WebSearch, MaxTurns, NativeAgentFile, etc.) read the value from each *_engine.go file in pkg/workflow/ (look for Capabilities{...} blocks at the top of NewXxxEngine).
3. Flag any row where the docs table ✅/❌ does not match the in-code capability flag — these are confirmed drift entries to fix in the same PR.
4. Add pkg/workflow/*_engine.go to DDUw's bash allow-list so the agent can grep capability declarations directly: "grep -n 'BareMode\\|MaxTurns\\|WebSearch\\|NativeAgentFile' pkg/workflow/*_engine.go".

Additionally, broaden the not_planned cross-reference (Step 1c) so that closed-as-not_planned issues whose body cites specific source-file line numbers (e.g. pkg/workflow/agent_validation.go:229) are verified by re-reading those lines directly, not only by checking for recent commits on the surface. Schema/parser/compiler drift items frequently sit unfixed for weeks without any new commits.

Related Issues

• Closes [deep-report] Reconcile schema/parser/compiler drift: tools.serena (x-removed but accepted) and engine.bare (docs claim ✅, compiler warns [Content truncated due to length] #33081

Generated by 📝 Daily Documentation Healer · ● 17.1M · ◷

• expires on May 22, 2026, 12:11 AM UTC