Review: AISTEERINGRULES usage — source of truth, write-pipeline drift, and unresolved #142 items

[virtualian]

Context

AISTEERINGRULES.md is force-loaded at every session start via .claude/settings.json → loadAtStartup and shapes every Claude response in PAI. Despite its behavioural weight, its origin, maintenance path, and internal consistency have drifted. This issue is a focused review, not a fix — scope: decide what should change, then spin off targeted issues.

Findings to review

1. No source of truth in the working repo

• find . -name AISTEERINGRULES.md -not -path '*/Releases/*' returns zero files.
• Canonical copies exist only under Releases/v4.0.0/, v4.0.1/, v4.0.2/, v4.0.3/, v4.0.3+/ and historical v2.4/v2.5/v3.0 trees (which used a different SYSTEM/+USER/ split).
• The live file at ~/.pai/PAI/AISTEERINGRULES.md is edited in place by the Learning pipeline but is not tracked in the repo.

2. Phantom personal-override path still in loadAtStartup

• settings.json:272-273 loads both PAI/AISTEERINGRULES.md and PAI/USER/AISTEERINGRULES.md.
• ~/.pai/PAI/USER/AISTEERINGRULES.md does not exist on any current install.
• Issue Opus 4.7 prompt audit — remediation backlog #142 item C-1 flagged this and was marked "won't fix — misdiagnosis". The phantom still ships. Decide: remove the line, ship an empty placeholder, or document why loading a missing file is intentional.

3. Automated mutation without HITL

• Packs/Learning/src/Workflows/Apply.md:69,81,166 reads and appends to ~/.pai/PAI/AISTEERINGRULES.md as part of the Learning pipeline's three-target write-back.
• Evidence of live mutation: Plans/2026-04-14-two-root-separation-followups.md:183 records the file growing from 6313 → 11926 bytes mid-investigation ("In active /Learn editing… Do not touch from a Claude conversation").
• Review: should behavioural policy be appendable by an agent pipeline at all, or should Learning produce proposals only, with an explicit human merge step?

4. Unresolved items carried over from closed #142

Issue #142 closed 2026-04-21 with these AISTEERINGRULES-specific items still unchecked:

• H-1/H-2 — ~19 absolutes in 96 lines (~20 % density). Anthropic's Opus 4.7 guidance prefers motivated positives over bare negatives.
• H-6 — Atomic-scope-lock (AISTEERINGRULES:54) vs capability-invocation floor (Algorithm:27) — precedence undocumented.
• M-6 — SKILL.md:33 ("'just' does not reduce depth") vs AISTEERINGRULES:54 (uses "just" as a scope-lock trigger). Opposite weights for the same lexical cue.

5. Stale SYSTEM/ + USER/ references in live docs

• ~/.pai/PAI/SKILL.md:445-446 still describes the v2.5-era split (SYSTEM/AISTEERINGRULES.md, USER/AISTEERINGRULES.md). Neither path exists in v4.0+.
• ~/.pai/PAI/AISTEERINGRULES.md:4 references USER/AISTEERINGRULES.md (missing).

Questions for the review

1. Where should the canonical AISTEERINGRULES.md live in the repo, and what's the install pipeline from source → ~/.pai/PAI/?
2. Is the Learning pipeline permitted to write to it directly, or should writes become proposals gated on human approval?
3. Are the Opus 4.7 prompt audit — remediation backlog #142 items still in scope, or were they deliberately deferred when that issue closed?
4. Is the PAI/USER/AISTEERINGRULES.md override mechanism still a design goal, or is it dead code?

Out of scope

Fixing any of the above. This issue produces a written decision + spin-off issues.