_build_combined_for_ref drops user flags (e.g. --allow-railroad-failure) when constructing ref_args

[asluk]

Summary

DocBuilder._build_combined_for_ref constructs ref_args as a fresh types.SimpleNamespace populated with a hardcoded set of fields (output, no_draft, only, exclude). Any other argparse flag set on the top-level args is silently dropped before reaching the worktree builder. Most visibly, this means --allow-railroad-failure does not propagate, even when explicitly set by the user.

Why it matters

If <from_ref> pre-dates a PEG fix that subsequently landed on <to_ref> (e.g. a railroad PEG that has since been corrected), the build of the from ref still fails fatally despite the user passing the opt-out flag.

Concretely, this blocks pixi run main build --allow-railroad-failure --diff e98ceb3 <newer-tip> in aousd/core-spec-wg because e98ceb3 (1.1.0 voting open) pre-dates aousd/core-spec-wg#494's schemas-PEG fix.

Where it happens

doc_build/doc_builder.py, around the _build_combined_for_ref body:

ref_args = types.SimpleNamespace(
    output=output_dir,
    no_draft=getattr(args, "no_draft", False),
    only=getattr(args, "only", []),
    exclude=getattr(args, "exclude", []),
)
output_dir.mkdir(parents=True, exist_ok=True)
return builder._setup_and_preprocess(ref_args)

The hardcoded list misses allow_railroad_failure (and would miss any other flag a downstream subclass adds via make_build_parser).

Suggested fix

Option A (explicit, minimal): add the one missing flag:

ref_args = types.SimpleNamespace(
    output=output_dir,
    no_draft=getattr(args, "no_draft", False),
    only=getattr(args, "only", []),
    exclude=getattr(args, "exclude", []),
    allow_railroad_failure=getattr(args, "allow_railroad_failure", False),
)

Option B (extensible): expose a hook so downstream subclasses can extend ref_args without re-overriding _build_combined_for_ref. For example a _ref_args_overrides(args) -> dict method whose return value is merged into the SimpleNamespace. This handles future / downstream flags too.

I'd lean Option B because the same problem can recur: any downstream make_build_parser add can fall through this gap.

Workaround in place downstream

aousd/core-spec-wg#499 overrides _build_combined_for_ref in CoreSpecBuilder to forward the flag, duplicating ~22 lines of the upstream method body. We'd like to drop that override once upstream forwards the flag.

[pmolodo]

This should already be fixed by:

#85

...which has been merged into doc_build main, but core_spec_wg hasn't been updated to use it yet.

[asluk]

ok great we'll mark fixed after wg is updated -- no rush, not a 1.1 blocker