Track pai-v5#2 port: AISTEERINGRULES wiring decision (loadAtStartup vs @imports)

[virtualian]

Context

Tracks the marrair-side coordination work for virtualian/pai-v5#2 (Port AISTEERINGRULES.md base + loadAtStartup wiring).

Mirrors the #173 pattern: actual overlay files live on virtualian/pai-v5 (per-issue branch yet to be cut from main); this issue covers the design-doc-side decisions and progress tracking that belong on virtualian/pai.

Decisions to capture in Plans/v5-0-0-plus-port.md

A. Wiring mechanism — loadAtStartup vs @imports

The design doc currently specifies settings.json.overlay adding {path: PAI/AISTEERINGRULES.md} to the loadAtStartup array. But v5's baseline settings.json reads:

"loadAtStartup": {
  "_docs": "v5.0: Static files migrated to @imports in CLAUDE.md.template. Dynamic context via LoadContext.hook.ts.",
  "files": []
},

v5 has explicitly deprecated loadAtStartup.files for static files, moving them to @imports in CLAUDE.md. The fork's planned path re-activates a deprecated mechanism. Two viable resolutions:

• Resurrect loadAtStartup (design doc's current plan): less invasive — single-key Class-B merge in settings.json.overlay; matches v3.7.0 mechanism familiar to /learn extension pipeline. Cost: documented future-incompatibility risk if v5 stops honouring the deprecated key.
• Adopt v5's @imports path: align with v5's stated direction. Cost: requires modifying CLAUDE.md.template (or live CLAUDE.md) via Class B section-append — needs deploy-overlay.sh extension we deferred during pai-v5#1 (Option 2 wiring).

Recommendation TBD until Phase B trial-session probe under each path (or until v5 either follows through on deprecating loadAtStartup.files semantics or quietly leaves the key honoured).

B. AISTEERINGRULES content source — bootstrap snapshot vs fresh runtime

The overlay file Releases/v5.0.0-overlay/PAI/AISTEERINGRULES.md on bootstrap/v5-overlay-and-tooling is the 95-line runtime snapshot captured at 2026-05-08. Marrair's live ~/.pai/PAI/AISTEERINGRULES.md may have been further /learn-extended since the snapshot. Decide:

• Use the bootstrap snapshot verbatim (port-time-frozen baseline; conscious snapshot moment).
• Refresh from marrair runtime at pickup time (captures any /learn additions between 2026-05-08 and pickup).

C. settings.json.overlay co-mingling cleanup

bootstrap/v5-overlay-and-tooling's settings.json.overlay carries THREE concerns intermingled:

1. loadAtStartup entry for AISTEERINGRULES (this issue's concern)
2. voiceEnabled: false (separate fork-posture choice)
3. hooks.PreToolUse → SecurityValidator.hook.ts (the dropped HIGH item; flagged for cleanup in PR Track #166 progress + audit pai-v5 overlay scaffold #171 audit)

The per-issue branch for pai-v5#2 must include ONLY concern (1), per design-doc "branch-as-feature" principle. The other two need separate handling:

• Decide whether (2) and (3) get their own coordination issues now or whether the SecurityValidator-residue follow-up (mentioned in Track #166 progress + audit pai-v5 overlay scaffold #171 audit, still unfiled) covers (3) and a separate "voice posture" issue covers (2).

Progress / Status updates

• Update design doc's "Decisions Locked" table when path A is resolved.
• Update design doc's "Progress / Status" section as pai-v5#2 overlay branch is cut and files committed.
• After deploy + acceptance verify on marrmini, update Progress / Status to mark pai-v5#2 as ported.
• Update "marrair Decommission Criteria" progress line — pai-v5#2 is criterion Diataxis skill: Role-first vs content-type-first structure mismatch #2 of 5.

Out of scope

• The overlay files themselves — those live on virtualian/pai-v5:<NN>-port-aisteeringrules (branch TBD).
• Acceptance verification — happens on marrmini against the live install.
• SecurityValidator-residue cleanup (concern C(3) above) — separate issue if not already filed.
• AISTEERINGRULES content-level review (that's Review: AISTEERINGRULES usage — source of truth, write-pipeline drift, and unresolved #142 items #153, a different concern about /learn-pipeline drift).

References

• Parent migration: Migration: marrair → marrmini, adopt v5.0.0 as baseline, freeze v4.0.3+ #166
• Design doc: Plans/v5-0-0-plus-port.md (sequencing item 2, lines 338–345)
• Port issue: virtualian/pai-v5#2
• Sibling completed: Track pai-v5#1 port: record Option 3 wiring decision (LATEST→6.3.0+local) in design doc #173 (pai-v5#1 coordination, MERGED)
• Related but distinct: Review: AISTEERINGRULES usage — source of truth, write-pipeline drift, and unresolved #142 items #153 (AISTEERINGRULES audit), Investigate v5 Learning Loop integration — port-side curation layer + community research #169 (Learning Loop investigation)
• Convention precedent: vX.Y.Z+local LATEST (from Track pai-v5#1 port: record Option 3 wiring decision (LATEST→6.3.0+local) in design doc #173) — may or may not apply here depending on path A resolution