…21 § H copy-onboarding semantics (#350)

PR #335 (closes #317) refined the v1→v2 migration semantics: onboarding.yaml
now uses **copy** (cp -p + git rm --cached + .gitignore add) while
workspace/ keeps **move** semantics. The framework spec (split-portfolio
skill, update skill, AgDR-0021 § H, test_split_portfolio_v2_migration.sh)
landed aligned. This doc — the user-facing migration guide — was
deliberately left out of #335 to keep that PR's scope tight; the manual
recipe still described mv semantics for onboarding.yaml. Today every
adopter who follows the by-hand recipe gets a 4-day-stale shape.

Aligns 3 specific places per AgDR-0021 § H:

- The /update example prompt (line 533) — "Move onboarding.yaml" →
  "Copy onboarding.yaml (sibling becomes canonical; public fork keeps a
  gitignored snapshot for legacy tooling)". The "Files MOVED, not copied
  — destructive" tagline replaced with a mixed-semantics explanation.
- The per-file-class confirmation prose (line 544) — "(move
  onboarding.yaml? Y/N; move workspace/? Y/N)" → "(copy onboarding.yaml?
  Y/N; move workspace/? Y/N)". Adds an inline reference to AgDR-0021 § H
  for the rationale.
- The by-hand recipe (line 562) — replaces "mv onboarding.yaml ..." with
  "cp -p onboarding.yaml ... + git rm --cached" per the canonical pattern.
  Adds an inline note that .gitignore must include onboarding.yaml so
  the kept-snapshot doesn't get committed.

Untouched: the high-level intent paragraphs (lines 180, 528) use "moves"
as conceptual language (v2 layout puts portfolio data in the private
repo) with the per-file-class semantics specified immediately below.
Reading the whole section, no ambiguity.

Closes #336

Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com>

…ntics (#335)

* fix(#317): /split-portfolio — produce v2 layout (copy onboarding, move workspace)

`/split-portfolio` previously landed adopters on the split-portfolio v1
layout (registry + projects/ in the sibling repo, but onboarding.yaml +
workspace/ still in the public fork). Adopters then had to run `/update`
to reach v2 — a two-step migration where one is sufficient.

Add Steps 9a–9d that produce the v2 layout in the same skill invocation:

- 9a: Copy onboarding.yaml to the sibling (not move) — sibling becomes
  canonical, public-fork copy stays as a gitignored snapshot for the
  legacy ops-root walk-up fallback. `cp -p` + `git rm --cached`.
- 9b: Move workspace/<name>/ contents to the sibling (mv — clones are
  gigabytes, doubling disk has no benefit). workspace/README.md kept.
- 9c: Extend .gitignore with onboarding.yaml + workspace.
- 9d: Write .apexyard-fork marker + four v2 config-block keys
  (portfolio.{onboarding,workspace_dir,custom_skills_dir,custom_handbooks_dir}).

Each sub-step is independently idempotent and per-file-class confirmable,
so an operator can copy onboarding.yaml now and defer workspace/ (or vice
versa). The pre-flight checklist + idempotency table are updated to
surface the new behaviour.

Refs #317 / AgDR-0021 § H.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(#317): /update step 8a — switch onboarding.yaml from mv to cp

The v1→v2 migration in /update step 8a moves onboarding.yaml and
workspace/ from the public fork to the sibling private repo. v2's
initial implementation used `mv` for both — but onboarding.yaml is
small, doubles as a legacy ops-root walk-up fallback anchor, and
benefits from staying on disk as a gitignored snapshot.

Switch onboarding.yaml from `mv` to `cp -p` + `git rm --cached`. The
sibling-repo copy becomes the canonical source of truth; the public-
fork copy is untracked (so commits don't ship it) and gitignored (so
it can't drift back in). workspace/ stays as `mv` — clones are
gigabytes, doubling disk has no benefit.

The conflict branch (both copies present pre-migration) is now
idempotent: it untracks the public-fork copy via `git rm --cached ||
true` instead of failing. Adopters re-running /update after a partial
migration land on the same v2 layout.

Confirmation prose updated: "Copy onboarding.yaml? [Y/n]" / "Move
workspace/? [Y/n]" surfaces the per-file-class verb.

Refs #317 / AgDR-0021 § H.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(#317): AgDR-0021 — v1→v2 migration semantics (copy vs move per file class)

Add section H "v1→v2 migration semantics" that codifies the refined per-
file-class verbs. The earlier `mv`-for-both design had two failure modes
observed in practice: it broke the legacy ops-root walk-up fallback when
the `.apexyard-fork` marker was accidentally removed, and it left
`/split-portfolio` producing a v1 layout (requiring a follow-up `/update`).

The refined decision:

- `onboarding.yaml` → COPY (`cp -p`) + `git rm --cached` + `.gitignore`.
  Sibling becomes canonical; public-fork copy stays as a gitignored
  snapshot for the legacy ops-root fallback. KB-scale so doubling disk
  is free.
- `workspace/<name>/` → MOVE (`mv`). Gigabytes of clones; doubling disk
  has no compensating benefit. workspace/README.md stays in public per § G.

Option-D table updated to surface the per-file-class choice as the
chosen path (with the initial design retained as a "superseded" entry
for posterity). Section H includes the post-state ASCII diagram, the
list of files where the refinement lands, and an explicit "what we are
NOT doing" section to pre-empt follow-up questions.

Refs #317.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test(#317): extend v1→v2 migration test for copy-onboarding semantics

The migration recipe now copies `onboarding.yaml` to the sibling private
repo (instead of moving it) so the public-fork copy remains as a
gitignored snapshot that the legacy ops-root walk-up can still find.
Pin that contract with tests.

Changes:

- run_migration: switch from `mv onboarding.yaml` to `cp -p` +
  `git rm --cached`. Add an idempotence branch that untracks even when
  the sibling-repo copy is already present.
- Case 1 assertions: invert the public-fork check (file must STILL be
  present, not absent). Add three new assertions — content identity
  via `cmp -s`, untracked status via `git ls-files`, snapshot-retained
  prose.
- Case 2 (idempotence): unchanged in shape; still asserts the file
  listing is stable on re-run. Now exercises the copy + untrack path.
- Case 4 (new): explicit copy-not-move semantics check. Modifies the
  public-fork snapshot AFTER migration and asserts the sibling-repo
  copy is unaffected — proves the two are independent files, not hard
  links or move-with-symlink artefacts. Also asserts `.gitignore`
  carries `onboarding.yaml`.

Test counts: 13 → 18 passes (5 new assertions; meets the ≥ 5 contract
in the ticket).

Refs #317 / AgDR-0021 § H.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…21 § H copy-onboarding semantics (#350)

PR #335 (closes #317) refined the v1→v2 migration semantics: onboarding.yaml
now uses **copy** (cp -p + git rm --cached + .gitignore add) while
workspace/ keeps **move** semantics. The framework spec (split-portfolio
skill, update skill, AgDR-0021 § H, test_split_portfolio_v2_migration.sh)
landed aligned. This doc — the user-facing migration guide — was
deliberately left out of #335 to keep that PR's scope tight; the manual
recipe still described mv semantics for onboarding.yaml. Today every
adopter who follows the by-hand recipe gets a 4-day-stale shape.

Aligns 3 specific places per AgDR-0021 § H:

- The /update example prompt (line 533) — "Move onboarding.yaml" →
  "Copy onboarding.yaml (sibling becomes canonical; public fork keeps a
  gitignored snapshot for legacy tooling)". The "Files MOVED, not copied
  — destructive" tagline replaced with a mixed-semantics explanation.
- The per-file-class confirmation prose (line 544) — "(move
  onboarding.yaml? Y/N; move workspace/? Y/N)" → "(copy onboarding.yaml?
  Y/N; move workspace/? Y/N)". Adds an inline reference to AgDR-0021 § H
  for the rationale.
- The by-hand recipe (line 562) — replaces "mv onboarding.yaml ..." with
  "cp -p onboarding.yaml ... + git rm --cached" per the canonical pattern.
  Adds an inline note that .gitignore must include onboarding.yaml so
  the kept-snapshot doesn't get committed.

Untouched: the high-level intent paragraphs (lines 180, 528) use "moves"
as conceptual language (v2 layout puts portfolio data in the private
repo) with the per-file-class semantics specified immediately below.
Reading the whole section, no ambiguity.

Closes #336

Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com>