feat(s53): --dimension-config/--outbox-dir/--run-id CLI flags + full-run structured refusal

main() single-project path now parses --dimension-config (fail-fast via load_dimension),
--outbox-dir, and --run-id (deliberate 7th companion flag: determinism invariant forbids a
wall-clock run_id default). All three threaded into BOTH run_project call sites. Full-run
branch wrapped in a structured-refusal (catch ValueError/FileNotFoundError/ValidationError ->
'run refused: {exc}' on stderr, rc 1, no traceback); the EXISTING dry-run handler widened to
the same tuple (pydantic ValidationError is not a ValueError subclass; load_dimension's
FileNotFoundError would otherwise traceback — Pass-2 #1). --outbox-dir carries a loud help=
note it must differ from --verdict-dir (self-contamination footgun; documented, not enforced).
RED-first: 4 CLI tests failed on unrecognized args, green after. 7 passed (incl. live-dry-run
regression). ruff + mypy clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KNNiJRk1sSwxgVLS5AobT1

src/portfolio_optimiser/run.py

@@ -31,6 +31,7 @@ from decimal import ROUND_HALF_UP, Decimal
 from typing import Any, Literal, cast
 
 from agent_framework import BaseChatClient, SessionContext
+from pydantic import ValidationError
 
 from portfolio_optimiser.backends import Profile, get_backend, resolve_model
 from portfolio_optimiser.budget import Budget, BudgetMiddleware, TokenMeter
@@ -42,7 +43,7 @@ from portfolio_optimiser.datasource import (
     make_retrieval_tool,
     retrieve_chunks,
 )
-from portfolio_optimiser.dimension import Dimension, admits
+from portfolio_optimiser.dimension import Dimension, admits, load_dimension
 from portfolio_optimiser.generate import generate_via_llm
 from portfolio_optimiser.ir import SavingsProposal
 from portfolio_optimiser.provenance import ProvenanceStamp
@@ -625,6 +626,26 @@ def main(argv: list[str] | None = None) -> int:
         help="async verdict inbox: a folder of dropped expert verdicts, ingested before generation "
         "(the long loop — a verdict that landed after an earlier run is consumed by this run)",
     )
+    parser.add_argument(
+        "--dimension-config",
+        default=None,
+        help="fail-fast dimension scope config (JSON): scopes the run to one cost axis; a "
+        "missing or malformed file refuses the run (authoritative startup config, not a RAW inbox)",
+    )
+    parser.add_argument(
+        "--outbox-dir",
+        default=None,
+        help="RAW outbox dir for the run's proposal/outcome artefacts (REQUIRES --run-id). MUST "
+        "differ from --verdict-dir: writing the outbox into a folder later read as an inbox "
+        "re-ingests raw agent output past the Step-8 promotion gate (self-contamination) — "
+        "documented, deliberately NOT CLI-enforced",
+    )
+    parser.add_argument(
+        "--run-id",
+        default=None,
+        help="stable run id for --outbox-dir artefacts (required when --outbox-dir is set; no "
+        "wall-clock/uuid default — the outbox artefacts are byte-deterministic)",
+    )
     parser.add_argument("--decision", default="approved", choices=["approved", "rejected"])
     parser.add_argument("--rationale", default="reviewed by expert")
     parser.add_argument(
@@ -647,11 +668,16 @@ def main(argv: list[str] | None = None) -> int:
                     docs_dir=args.docs_dir,
                     bundle_dir=args.bundle_dir,
                     verdict_dir=args.verdict_dir,
+                    dimension=(
+                        load_dimension(args.dimension_config) if args.dimension_config else None
+                    ),
+                    outbox_dir=args.outbox_dir,
+                    run_id=args.run_id,
                     verdict_input={"decision": args.decision, "rationale": args.rationale},
                     live_dry_run=True,
                 )
             )
-        except ValueError as exc:
+        except (ValueError, FileNotFoundError, ValidationError) as exc:
             # Structured refusal (rc 1, no traceback) for ANY offline-path ValueError. The
             # azure-preflight remediation is only meaningful for the AZURE config gate (S4.1), so
             # scope it to that profile — a LOCAL-profile ValueError (unknown project_id, empty
@@ -673,19 +699,30 @@ def main(argv: list[str] | None = None) -> int:
         )
         return 0
 
-    result = cast(
-        RunResult,
-        asyncio.run(
-            run_project(
-                args.project_id,
-                args.profile,
-                docs_dir=args.docs_dir,
-                bundle_dir=args.bundle_dir,
-                verdict_dir=args.verdict_dir,
-                verdict_input={"decision": args.decision, "rationale": args.rationale},
-            )
-        ),
-    )
+    try:
+        result = cast(
+            RunResult,
+            asyncio.run(
+                run_project(
+                    args.project_id,
+                    args.profile,
+                    docs_dir=args.docs_dir,
+                    bundle_dir=args.bundle_dir,
+                    verdict_dir=args.verdict_dir,
+                    dimension=(
+                        load_dimension(args.dimension_config) if args.dimension_config else None
+                    ),
+                    outbox_dir=args.outbox_dir,
+                    run_id=args.run_id,
+                    verdict_input={"decision": args.decision, "rationale": args.rationale},
+                )
+            ),
+        )
+    except (ValueError, FileNotFoundError, ValidationError) as exc:
+        # Structured refusal (rc 1, no traceback) for the full-run path: run_project's fail-fast
+        # loaders (contracts, load_dimension, outbox run_id guard) surface here as one clean line.
+        print(f"run refused: {exc}", file=sys.stderr)
+        return 1
     kind = type(result.outcome).__name__
     print(f"{args.project_id}: {kind} (verdict id={result.verdict.id}, decision={args.decision})")
     return 0