Summary

Closes the framework primitive deferred from #144.

• portfolio: config block in .claude/project-config.{defaults,}.json for path resolution (registry, projects_dir, ideas_backlog). Defaults preserve today's single-fork behavior; adopters in split-portfolio mode override the keys.
• _lib-portfolio-paths.sh helper library + portfolio_validate() for self-healing. New SessionStart hook surfaces a one-line banner if the resolved paths are broken — silent on success, never blocks.
• 18 SKILL.md files updated with a "Path resolution" callout pointing at the helper. Two skills got deeper bash-block edits: handover (now sources the helper instead of hardcoded apexyard.projects.yaml); setup Step 2b (writes the config block as the first-class path; symlinks remain documented as legacy fallback).
• New /split-portfolio skill — automates the destructive recovery flow with explicit operator-confirmation gates at each destructive step. --verify mode reads-only; --dry-run prints commands without executing. Refuses on already-private fork, paid GitHub plan, dirty working tree, or already-migrated state. Step 9 writes the new config block (not symlinks); Step 9 surfaces the GitHub timeline-API survival caveat verbatim.
• AgDR-0010 captures the design rationale, including the schema-location decision (project-config.json over onboarding.yaml).

Targets dev per the apexyard release-cut model.

What changes

26 files changed, ~1,416 insertions, 18 deletions.

Why "in this PR" (the self-healing scope)

The original ticket #145 only asked for the schema + helper + skill audit. During design, the question came up: "is this usable AND self-healing?" The honest answer was "usable yes, self-healing only partially." The cheapest way to close that gap was four extra hunks landing in this same PR: portfolio_validate() in the helper, the SessionStart banner that uses it, the /setup finalization gate, and --verify mode in /split-portfolio. ~150 extra lines, all separable. The acceptance criteria on #145 were updated before code to make Rex's review mechanical.

Closes vs Refs

This PR closes #145 (per the single-Closes-keyword rule in validate-pr-create.sh). #146 is delivered in the same PR but closed manually post-merge with a "delivered in PR #X" comment — that's the framework's documented pattern when a single PR delivers two coupled tickets.

Testing

Helper unit tests

bash .claude/hooks/tests/test_portfolio_paths.sh — 13 cases, all pass:

• Defaults resolve to fork-rooted absolute paths (registry + projects_dir + ideas_backlog).
• Defaults validate is OK.
• Override with absolute path wins.
• Override with sibling-dir path validates OK.
• Override with relative path resolves against fork root.
• Validate detects: missing registry, registry without projects: key, missing projects_dir, ideas_backlog with missing parent.
• Validate accepts ideas_backlog missing-but-creatable (parent exists).
• portfolio_clear_cache() resets resolver state.

Hook regression sweep

for t in .claude/hooks/tests/test_*.sh; do bash "$t"; done — 8/10 pass. Two pre-existing failures unrelated to this PR (test_single_closes_per_pr, test_validate_pr_required_sections) reference closed issue #114 in their fixtures and trip the network cross-ref check on a clean upstream/dev checkout. Verified pre-existing by running against pristine upstream/dev on a stash.

Live smoke

• Helper runs in this fork's split-portfolio configuration: registry resolves through symlink, validate returns OK.
• SessionStart hook silent on this fork's valid config.
• SessionStart hook prints a clear banner when pointed at a tmpdir with a broken portfolio.registry. Exits 0 (informational, never blocks).

Manual smoke for /split-portfolio

Not run end-to-end against a real public fork — destructive operations, requires throwaway repos. Documented in the skill's AC list as "manual smoke test" rather than CI-tested. The skill's pre-flight refusals + idempotency mean a partial run is recoverable.

Glossary

Closes #145
Refs #146 (closed manually post-merge)