Adopt Project Scope Migration

Adopt Project Scope — In-Place Migration to Project Scoping

Take an existing, unscoped database (many depth-0 roots, no project anchor) and migrate it in place to the project-scoping convention: one type=project root that owns the workspace's work trees, with its UUID written back to .taskorchestrator/config.yaml under a project: block. Global containers (retrospectives, observations) stay at depth 0; test artifacts are flagged for cleanup, never moved or deleted.

This is a destructive-by-execution skill: the EXECUTE step re-parents real items. It defaults to a dry run and never mutates anything without an explicit confirmation. The only thing it ever deletes is its own throwaway server-probe tree.

For a fresh workspace with no existing unscoped work, use /task-orchestrator:init instead; this skill is for databases that already hold unscoped work trees.

Non-goals: cross-DB consolidation (merging items from a second database); merging multiple existing project anchors into one; any server-side enforcement of scope. This skill adopts a single workspace's single database.

Step 0 — Parse Arguments

• Project name — the first non-flag token(s) in $ARGUMENTS. If absent, do not guess; ask for it in Step 3 (the dry-run plan) via AskUserQuestion before any mutation.
• --dry-run — if present, the skill stops after Step 3 (the plan) and performs zero mutations regardless of confirmation. The dry run is ALSO always rendered before execution even without the flag; the flag only forces an early exit.

Step 1 — Preflight (abort gates)

Run these checks in order. Each abort prints a clear, user-facing reason and stops.

1a — Already adopted?

Read .taskorchestrator/config.yaml. If it contains a project: block with a non-empty rootId:, the workspace is already scoped:

◆ Workspace already adopted — config.yaml already points at project root <rootId>.
  Nothing to do. Use /work-summary to inspect the existing project tree.

Stop. (If the file is missing entirely, that is fine — a fresh unscoped DB has no config project: block. Continue.)

1b — Existing anchor already in the DB?

query_items(operation="search", type="project", depth=0)

(list mode — query omitted, filtering by type and depth.) Drop any result tagged personal-root: a personal root is not a project anchor and must never be adopted as one.

• No results → continue to 1c.

• One or more results → do NOT silently create a second anchor. Offer, via AskUserQuestion:

  1. Attach to existing — write the existing anchor's UUID into config.yaml (skip anchor creation in EXECUTE; still re-parent MOVE roots under it) and continue.
  2. Abort — stop and let the user resolve the ambiguity manually.

  If the user picks "attach", record the existing anchor UUID as ANCHOR_ID and note that EXECUTE step (a) is skipped.

1c — Server capability probe (the depth-sweep fix)

Bulk re-parenting is exactly the scenario that a pre-fix server corrupts: on a pre-#219/#220 server, re-parenting a subtree does NOT recompute descendant depths (bug 99a3e642), so this skill would silently leave the moved trees with wrong depths. Verify the fix is deployed with a disposable probe, then delete it.

Build a probe where a grandchild's depth MUST change when a middle node is re-parented deeper:

1. Create a throwaway root and a two-level branch under it in one call:

   manage_items(operation="create", items=[
     { title: "zzprobe-root",  type: "container", priority: "low" }
   ])

   Capture its UUID as P.
2. Create the branch (sequential parentage, small tree). manage_items create has no ref/parentRef mechanism (only create_work_tree does), so a sibling's UUID does not exist until its own create call returns — M and G cannot be created in the same batch since G's parentId needs M's real UUID:

   manage_items(operation="create", items=[
     { title: "zzprobe-A",   parentId: P,  priority: "low" }     → capture as A (depth 1)
   ])

   manage_items(operation="create", items=[
     { title: "zzprobe-M",   parentId: P,  priority: "low" }     → capture as M (depth 1, sibling of A)
   ])

   Capture M's returned UUID, then create G referencing it:

   manage_items(operation="create", items=[
     { title: "zzprobe-G",   parentId: "<M's real UUID>",  priority: "low" }     → capture as G (depth 2, child of M)
   ])

3. Re-parent the middle node M under A (making it deeper):

   manage_items(operation="update", items=[{ itemId: M, parentId: A }])

   Post-fix, M becomes depth 2 and G becomes depth 3.
4. Read the grandchild's depth and capture it:

   query_items(operation="get", itemId=G)

5. Delete the probe immediately, before acting on the result — this runs on every path, pass or fail:

   manage_items(operation="delete", itemIds=[P], recursive=true)

6. Now evaluate the captured depth:
   • depth == 3 → fix is present. Continue.
   • depth == 2 (stale) → abort (probe already deleted):

     ⊘ Server is missing the reparent depth-sweep fix (bug 99a3e642).
       Bulk re-parenting on this server would corrupt subtree depths.
       Upgrade the Task Orchestrator server (PR #219/#220 or later) and retry.

--dry-run skips this probe entirely — no execution will happen, so the capability check is unnecessary and the dry run stays genuinely mutation-free. The probe runs only on the real-execution path, after the user confirms in Step 3.

1d — Config-push capability (tolerant)

manage_project_config may be absent on older servers. Do not probe it destructively here — just remember to attempt the push in EXECUTE step (d) and, if the tool is unavailable, skip it with a note rather than failing the whole adoption. The local config.yaml write (step c) is the source of truth; the server push is a convenience sync.

Step 2 — Inventory & Classify

Full depth-0 census:

query_items(operation="overview", excludeTerminal=false, includeChildren=true, limit=<total>)

If the response reports truncated: true, re-issue with limit set to the reported total so no root is missed.

Classify every depth-0 root into exactly one bucket:

Ambiguous roots (no clear rule match — e.g., an untagged standalone item that could be work or a stray container): do NOT guess. Collect them and present via AskUserQuestion (multiSelect) asking which should MOVE vs stay KEEP-GLOBAL. Test-artifact-looking items always go to CLEANUP-CANDIDATE without asking.