Authoring diagnostics: identify the failed proposal decision

[noeltock]

Problem

A rejected proposal should identify the decision its caller needs to correct. The current report can lead with a CSS-grid error for a Group containing direct Button children, or retain a Custom HTML warning from the intermediate rules conversion even though the proposal replaces that structure. These messages describe different stages but arrive in the same item list.

This is a focused follow-up to #64. Preserve the existing report API and its safety checks; make the supported correction and the stage of each finding clear.

Observed cases

Input / proposal	Current result	Required distinction
CTA wrapper mapped to Group with direct Button children; wrapper CSS includes display:flex	Native-style ownership error labelled as grid-container work	Identify the required Buttons parent at the proposal boundary; do not imply the source authored a grid merely because display is present.
Figure bound to a layout Column	Binding rejection	Identify the source reference, selected node/block and supported image ownership; a synthetic layout wrapper does not consume the figure.
Figure correctly bound to Image, but a separate authored grid is bound to Columns	Real grid ownership rejection plus intermediate caption Custom HTML warning	Keep the grid rejection; identify the caption message as intermediate conversion evidence, not proof of final generated caption loss.

These cases were observed against PR #69 at 9680c5cc66bf17a3f803cf2eff4ddd75d41bdbf5. The last case produced no package, so no final-output caption defect is established. Build small local regression inputs; no paid model run is necessary to investigate these paths.

Existing flow and code pointers

source → convert() findings
       → proposal binding / replacement structure
       → native style + source-content validation
       → existing report: stage-qualified findings + actual compile outcome

• src/author/proposal.ts: bindAuthoringProposal, its binding checks and validateProposalSourceContent already own source references and consumption. Some failures still throw plain Error. Add only independently knowable proposal checks here; do not build another full native-block validator.
• src/author/plan.ts: adaptNativeSourceStyles gives Group/Columns a grid-container target, and its gridProperties includes display. The actual CSS value and chosen block must inform the explanation. Keep the unsupported authored-grid-to-Columns rejection intact.
• src/author/index.ts: proposal compilation passes structureOverride, validates coverage and source content, and clears tentative output on failure. Around line 596, the returned items concatenate conversion.items with generation and dependency findings. ok comes from actual compilation. Preserve those distinctions.
• src/author/diagnostics.ts already provides AuthorDiagnosticError/authorDiagnostic. ReportItem in src/types.ts already supports code, source, reason and details; Authoring: return actionable source-located decisions for unresolved mappings #64 uses structured source/node/action details. Reuse that shape instead of adding a parallel result envelope.
• test/author.diagnostics.test.ts already checks deterministic output, stale references, coverage differences, unmatched selectors and correction behaviour. Add the bounded cases there and use test/author.proposal.test.ts / test/author.native-style-adapters.test.ts for regression coverage.

Minimal behaviour change

Return a stable code, verified source location/reference, selected node/block, observed versus required relationship, and supported action or explicit unsupported reason where known. A direct Button under Group should point to its parent relationship before unrelated CSS ownership work. Do not silently insert wrappers or replace Columns with Group.

Keep intermediate findings visible, but qualify their origin in the existing report so JSON and text readers can distinguish source analysis from the final proposed artifact. Do not suppress warnings wholesale, downgrade genuine unsafe input, or report an intermediate fallback as a confirmed final fallback. Source paths should continue to point to authored input.

Only add batching if the controlled #65 result demonstrates that serial independently detectable errors remain the obstacle. That would be a separate, bounded extension of current diagnostics, not a retry controller.

Acceptance criteria

• The direct Button/Group case returns an actionable parent diagnostic with node and source context before a misleading grid error; a supported corrected parent changes or resolves that diagnostic.
• Invalid figure ownership identifies the actual bound element and supported correction. A wrapper without a reference does not excuse omitted figure content.
• Ordinary display:flex is not described as authored grid evidence. Truly unsupported native mappings still fail explicitly.
• A caption warning from intermediate conversion remains visible and stage-qualified; tests distinguish it from final proposal content validation and do not assume every conversion warning has been resolved.
• Identical inputs produce identical diagnostic ordering and structured details. Existing text/JSON consumers retain reason, status and source information.
• Rejections still return no executable package; required source/content/asset/style and unsafe-input failures remain enforced.
• No automatic native-tree correction, warning suppression, new response API or model-specific repair advice is introduced.

Sequence and checks

Keep these runtime changes out of #65's instruction-only compiler baseline until that comparison is recorded. Use its result to prioritise the already-observed diagnostic gaps rather than starting another general diagnostics rewrite.

Expected ownership is src/author/proposal.ts, src/author/plan.ts, src/author/index.ts and test/author.diagnostics.test.ts, reusing the existing helper and report types. If the minimal correction requires a broader API change, separate that proposal before implementing it. Run npm test -- test/author.diagnostics.test.ts test/author.proposal.test.ts test/author.native-style-adapters.test.ts and npm run typecheck, then required integration checks once stable. No paid model run or publication.