docs(.shared): centralize shell portability guidance

[thewrz]

This was written agentically; verify its assertions:

Why

Agent-composed multi-line recipes run in the harness shell, which may be zsh, while the existing portability guidance lived only in one review reference and did not cover common Bash-only constructs.

What

• Add one shared shell-portability reference covering explicit Bash boundaries, Bash/zsh differences, nested quoting, and stdin hazards.
• Route every recipe-bearing skill and the reference manifest to that shared policy.
• Move the existing provider-rule pitfalls by reference instead of duplicating them.
• Pin the shared content and skill routing in recipe-safety tests.

Decisions

• Keep shipped .sh helpers unchanged because their Bash shebangs are the correct boundary.
• Use an explicit bash -c boundary only for agent-composed multi-line recipes.
• Preserve the bootstrap exception: onboarding wraps Step 0 before it can resolve and read the shared reference.

Stacked on #436; merge #436 first, then merge its updated base down and retarget this PR to main before merge.

base=origin/feat/issue-427
files=8
total.insertions=96
total.deletions=7
total.lines=103
operational.files=8
operational.insertions=96
operational.deletions=7
operational.lines=103
generated.files=0
generated.insertions=0
generated.deletions=0
generated.lines=0
lockfile.files=0
lockfile.insertions=0
lockfile.deletions=0
lockfile.lines=0
fixture.files=0
fixture.insertions=0
fixture.deletions=0
fixture.lines=0
non_operational.files=0
non_operational.insertions=0
non_operational.deletions=0
non_operational.lines=0

Testing

• Recipe safety, reference manifest, skill invocation/size, contract, and autonomy suites passed: .agent/logs/20260824T152018Z-test.log.
• Full suite is blocked by the six pre-existing test-agent-preflight.sh cache assertions reproduced in .agent/logs/20260824T151752Z-test.log.

🤖 Co-authored by Codex gpt-5.6-sol.

Closes #428

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 6b57770a-6401-4bc5-b1ed-b69a5060257b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[thewrz]

This was written agentically; verify its assertions:

Adversarial review receipt

• Reviewer: provider=anthropic; model=claude-opus-5; effort=high; mode=cross-provider (reason: peer CLI present; root auto-review consent)
• Counts: P1=0; P2=2; total=2
• Confirmed finding: Escape the pipe in the rendered Markdown hazard table — verdict=fixed; fix commit SHA(s)=f7b3634ea1b8664630ef60e05a86ab1c199eb983
• Confirmed finding: Use a literal pipe in the duplicate-guidance assertion — verdict=fixed; fix commit SHA(s)=f7b3634ea1b8664630ef60e05a86ab1c199eb983

🤖 Co-authored by Codex gpt-5.6-sol.