docs(#336): align docs/multi-project.md v1→v2 manual recipe with AgDR-0021 § H copy-onboarding semantics#350
Conversation
…21 § H copy-onboarding semantics 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
atlas-apex
left a comment
There was a problem hiding this comment.
Code Review: PR #350
Commit: 8b5b7cad826707e09602132ec582a073d7925430
Summary
Pure docs PR — single file changed (docs/multi-project.md, +17 / -7). Closes #336 (filed as the deferred prose-alignment follow-up from PR #335). Realigns the v1→v2 manual migration recipe with the per-file-class semantics canonicalised in AgDR-0021 § H: onboarding.yaml uses copy (cp -p + git rm --cached + .gitignore add), workspace/ keeps move.
Checklist Results
- Architecture & Design: N/A (docs-only)
- Code Quality: N/A (docs-only)
- Testing: PASS (3 verification steps listed; appropriate for prose)
- Security: N/A (docs-only)
- Performance: N/A (docs-only)
- PR Description & Glossary: PASS (4 narrative bullets, 6-term glossary, ticket link, testing instructions)
- Technical Decisions (AgDR):N/A (
<!-- agdr: not-applicable -->marker is legitimate — the underlying call lives in AgDR-0021 § H, landed via #335; this PR realigns prose to that already-shipped decision) - Adopter Handbooks: PASS (3 always-load handbooks; none triggered)
Issues Found
None.
Verification
-
Edits match AgDR-0021 § H verbatim — confirmed. The recipe block at lines 568-595 produces the same end-state as AgDR-0021 § H's table:
cp -p onboarding.yaml→git rm --cached onboarding.yaml→.gitignoreextends withonboarding.yaml+workspace. The specificgit add .gitignore .apexyard-fork .claude/project-config.jsonat line 607 (note: noonboarding.yamlin this add list) makes the untrack persist atomically with the gitignore landing — safe ordering. -
Zero stale
mv onboardingreferences — confirmed viagrep -n -i "mv.*onboarding\|move.*onboarding"against the file at the PR HEAD. The 3 matches that remain (lines 180, 528, 548) are all intent-language paragraphs that use "moves" as a conceptual descriptor for v2 layout, with implementation semantics specified immediately below. -
Mixed-semantics wording is honest — the prompt block (lines 540-543), the inline AgDR-0021 § H link at line 548, the recipe-section comments at lines 573-574 and 578-579, and the
.gitignoreblock comment at lines 588-589 all explain WHY onboarding is copied (small + sibling-canonical + legacy fallback safety net) and WHY workspace is moved (size constraint). -
High-level intent paragraphs (lines 180, 528) scan correctly in context — both are immediately followed by the per-file-class block (lines 180 → 184 onwards; 528 → 533-543) that specifies COPY vs MOVED. Sequential read produces no ambiguity.
-
PR body quality — Glossary has 6 well-defined terms (Copy semantics, Move semantics, Per-file-class confirmable, Manual fallback recipe, AgDR-0021 § H, v2 ops-fork anchor). Summary bullets are narrative (each answers what + why).
Closes #336present. -
<!-- agdr: not-applicable -->marker is legitimate — diff is single-filedocs/multi-project.mdonly (confirmed viagh pr diff --name-only). The topology /extract-subpacks-on-release.ymlfiles the hook flagged are noise from already-merged PRs #346 + #344 that appear in diff-vs-main but aren't in this PR's diff-vs-dev.
Suggestions
None. The PR is tightly scoped, accurately drafted, and the inline AgDR-0021 § H references give future-readers a clear breadcrumb back to the design rationale.
Verdict
APPROVED
Reviewed by Rex (Code Reviewer Agent)
Reviewed commit: 8b5b7cad826707e09602132ec582a073d7925430
…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>
Summary
onboarding.yamlfrommvtocp -p+git rm --cached+ gitignore add (sibling becomes canonical; public fork keeps a gitignored snapshot). The framework spec landed aligned in fix(#317): /split-portfolio produces v2 layout + copy-onboarding semantics #335; this doc was deliberately deferred to keep that PR tight. Every adopter following the by-hand recipe between fix(#317): /split-portfolio produces v2 layout + copy-onboarding semantics #335 landing and today would get the oldermvshape and end up with a different state than the/updateskill produces. This PR closes that drift./updateexample prompt (line 533), the per-file-class confirmation prose (line 544), the by-hand recipecp -p+git rm --cachedblock (line 562). Each carries an inline reference to AgDR-0021 § H so future-readers see the rationale (onboarding.yamlis small + sibling-canonical + snapshot-friendly;workspace/is too big to duplicate, hencemv).Testing
npx markdownlint-cli2@0.13.0 docs/multi-project.md→ 0 errorsgrep -n -i "mv.*onboarding\.yaml" docs/multi-project.md→ 0 matches (only acceptable form iscp -pnow)Closes #336
Glossary
cp -pto sibling +git rm --cachedin public fork + add to.gitignore. Sibling holds canonical source of truth; public fork keeps a gitignored snapshot for legacy toolingmvto sibling. Size constraint — clones are potentially gigabytes; duplicating them would waste disk/updateasks Y/N per file class (copy onboarding? Y/N; move workspace? Y/N), so operator can defer one and migrate the other/update's automatic v1→v2 step 8a. Should match AgDR-0021 § H.apexyard-forkmarker file at the public-fork root — replaces the legacyonboarding.yaml + apexyard.projects.yamlpair for v2 detectionRefs #335 (the spec landing that this doc PR now matches) / Rex review suggestion #1 on #335
AgDR not applicable. Doc-only PR. The trigger-path files the hook flags (
topologies/*,.github/workflows/extract-subpacks-on-release.yml) all landed via already-merged PRs #346 + #344 and are NOT touched by this PR. The diff-vs-main reports them; the actual diff-vs-dev is the single-filedocs/multi-project.mdchange shown above. No new architecture decision; the underlying call lives in AgDR-0021 § H (referenced in the body).