docs: promote CLAUDE.md nullable-gate divergence to #522 and record epic-planner lessons

[drmoisan]

Suggested title

docs: promote CLAUDE.md nullable-gate divergence to #522 and record epic-planner lessons

Summary

• Records the promoted potential-bug entry for Bug: claudemd-nullable-gate-diverges-from-ci #522: the C# type-check command documented in CLAUDE.md and two other governance files passes /p:Nullable=enable, but CI deliberately omits it, so the documented gate can never pass on a clean main.
• Adds two epic-planner agent-memory entries from the gate-failed 505/506/507/508 planning run.
• Documentation only. No production, test, or build-configuration files are touched.
• This PR records the defect; it does not fix it. The six divergent command occurrences remain unchanged and are tracked by Bug: claudemd-nullable-gate-diverges-from-ci #522.

Why

Two deliveries on 2026-08-08 (issues #507 and #508) each independently hit the same false blocker: a subagent running the CLAUDE.md type-check command verbatim reported a blocking CS8603 on work that was in fact clean. In both cases the error only appeared under /p:Nullable=enable, a flag .github/workflows/ci.yml intentionally does not pass.

The workflow states the reasoning inline — enforcement relies on each file's own #nullable enable pragma, because UtilitiesCS.csproj and SVGControl.csproj carry no project-level <Nullable> element. Solution-wide /p:Nullable=enable opts in every file at once, including the majority never written for it, producing 200-414 errors that are red on main regardless of any local change.

That decision was never propagated back into the governance layer, so the documentation instructs every agent to run a gate that cannot pass. Left uncorrected, the cost recurs on every C#-touching run.

The epic-planner entries capture a separate finding from the same day: bugs promoted out of another feature's review are usually located in the exact code that feature is refactoring, so decomposition must check unmerged branches rather than only origin/main.

What Changed

Docs — potential-entry promotion

• docs/features/potential/promoted/2026-08-08-claudemd-nullable-gate-diverges-from-ci.md (+95) — full bug report: reproduction steps, the ci.yml excerpt with its rationale comment, the six affected occurrences across three files, severity assessment, and proposed fix criteria.

Docs — agent memory

• .claude/agent-memory/epic-planner/feedback_check_inflight_branches_before_decomposition.md (+46) — new: check in-flight branches and their orchestrator checkpoints before computing an epic decomposition; includes the two decomposition rules the run confirmed.
• .claude/agent-memory/epic-planner/feedback_epic_planner_state_required_fields.md (+12/-1) — records the exact enum values the checkpoint validator enforces for epic_worthiness.verdict and next_step.
• .claude/agent-memory/epic-planner/MEMORY.md (+2/-1) — index entries for the above.

Architecture / How It Fits Together

No runtime wiring. The promoted entry sits in the standard docs/features/potential/promoted/ location consumed by the feature-promotion lifecycle. The agent-memory files are read by the epic-planner agent at session start via its MEMORY.md index.

Verification

Completed

• git status clean on the branch; all four files committed across two commits.
• Changed-file set verified against git diff --numstat origin/main...HEAD.
• The divergence claim was verified directly: .github/workflows/ci.yml lines 103-116 omit /p:Nullable=enable, and the six divergent occurrences were located at CLAUDE.md:206, CLAUDE.md:383, CLAUDE.md:401, .claude/rules/csharp.md:16, .claude/rules/csharp.md:83, and .claude/skills/csharp-qa-gate/SKILL.md:32.

Recommended

• No build or test run applies to this change. CI's standard checks (actionlint, Format, build, analyze, and test) will run unchanged; a docs-only diff should not affect them.

Backward Compatibility / Migration Notes

None. No API, command, or configuration behavior changes. The defective commands are documented but deliberately left in place for #522 to fix.

Risks and Mitigations

• Risk: a reader treats the promoted entry as the fix and assumes the toolchain docs are corrected. Mitigation: the entry's Next Step checklist leaves "Move to active fix folder / branch" unchecked, and this PR body states explicitly that Bug: claudemd-nullable-gate-diverges-from-ci #522 is not fixed here.
• Rollback: revert the two commits; no dependent state.

Review Guide

Small diff, suggested order:

1. docs/features/potential/promoted/2026-08-08-claudemd-nullable-gate-diverges-from-ci.md — the substantive content; check the reproduction steps and the ci.yml excerpt against the workflow.
2. The three agent-memory files — mechanical index plus prose.

Follow-ups

• Bug: claudemd-nullable-gate-diverges-from-ci #522 — correct all six occurrences to match CI's command, and relocate the ci.yml rationale into .claude/rules/csharp.md so the per-file-pragma convention lives in the governance layer. Verify the corrected command still fails on a genuine regression in a file that does carry #nullable enable, so the gate is fixed rather than merely weakened.

GitHub Auto-close

None. This PR records the promoted entry for #522 but does not fix it. The context bundle's author-asserted autoclose list contained #522, which is a text scan of the commit message rather than author intent; it is deliberately not emitted as a Closes bullet.