brand-gen-phase-contract-audit

For Sage brand work in Pi, use the paste-ready prompt at docs/prompts/pi-sage-brand-gen-full-pipeline.md. Keep this link instead of copying the full prompt into skill bodies.

Brand-Gen Phase Contract Audit

Risk addressed: the in-process contract between pipeline phases is argparse.Namespace. There are 426 getattr(args, ...) call sites across 16 modules. PipelineRequest.build_scratchpad_namespace (pipeline_request.py:332) hand-builds a Namespace with ~30 fields just to pass typed data between in-process stages. getattr(args, "field", None) swallows typos, so renames silently zero out values. New fields require parallel updates in PIPELINE_MCP_PROPERTIES, PipelineRequest, from_mapping, build_scratchpad_namespace, the CLI builder, and per-phase getattr calls. Tests pass argparse.Namespace() so phantom fields slip through.

PlanDraft and GenerationScratchpad dataclasses exist but _run_scratchpad operates on the dict payload and converts at the end via scratchpad_from_dict. The _filter_fields helper (pipeline_types.py:386) silently drops unknown keys.

What this skill produces

{
  "summary": {
    "total_getattr_sites": 426,
    "phantom_fields": 17,
    "phases_with_drift": 4,
    "fields_declared_but_unused": 8,
    "namespace_fields_total": 73,
    "typed_request_fields_total": 41
  },
  "phases": [
    {
      "phase": "route",
      "consumed_fields": ["route_brief", "material_type", "render_backend", ...],
      "declared_in": ["PipelineRequest"],
      "phantom_in_phase": [],
      "untyped_via_namespace_only": ["route_force"]
    },
    {
      "phase": "plan",
      "consumed_fields": [...],
      "declared_in": ["MaterialPlan", "PipelineRequest"],
      "phantom_in_phase": ["legacy_inspiration_seed"],
      "untyped_via_namespace_only": ["accept_inspiration_recommendations"]
    }
    /* ... per-phase ... */
  ],
  "phantom_fields_detail": [
    {
      "field": "legacy_inspiration_seed",
      "read_at": ["plan_builder.py:412"],
      "never_written_at": "no PipelineRequest entry, no Namespace builder line",
      "default_returned": "None",
      "blast_radius": "silent — production has never set this; renames break nothing but the field is dead"
    }
  ],
  "filter_fields_drift": [
    {
      "field": "branch_id",
      "declared_in": "MaterialPlan, GenerationScratchpad",
      "missing_from": "scratchpad_from_dict input shape",
      "behavior": "silently dropped at deserialization"
    }
  ],
  "duplicate_field_routing": [
    {
      "field": "design_variance",
      "paths": ["PipelineRequest.design_variance", "Namespace.design_variance", "scratchpad payload.design_variance"],
      "consistency": "ok"
    }
  ]
}