feat(hierarchies): multi-repo single-owner ownership + structural prune (M3)

§7 of the groups/project-tool design. A group node is now authoritatively
managed by exactly one project-root; `pic apply --dir` claims, conflicts,
takes over, and (with --prune) structurally reaps owned nodes.

- Migration 0052: `projects(id, key UNIQUE)` + promote the inert
  `groups.owner_project` (0047) to a real FK (ON DELETE SET NULL) + index.
- CLI mints a stable, gitignored project key in `.picloud/project.json`
  (`pic init`, or lazily on first tree plan/apply) and presents it on every
  tree request; `pic apply --dir --takeover` flag.
- Server: prepare_tree resolves ownership read-only (plan surfaces conflicts
  + prune candidates; token folds each group's owner key). apply_tree upserts
  the project in-tx, claims created groups on insert, reconciles existing-group
  ownership under the per-node advisory lock (first-commit-wins), and prunes
  owned-but-undeclared groups leaf-first (delete=RESTRICT, never another repo's
  or a UI-owned node).
- Authz (§7.4, ownership ⟂ RBAC): takeover requires GroupAdmin per contested
  node — enforced in authz_tree (pre-tx) AND re-verified in-tx at the ownership
  decision, so --force (which waives the staleness token) can't open a
  takeover-without-admin window. The attacker-supplied project key is
  length/charset-validated server-side.
- Tests: tests/ownership.rs (claim → conflict → takeover → flip; non-admin
  takeover → 403; prune-owned-only); format_conflicts unit test; schema golden
  reblessed. tree_shape M2 journey updated to reparent in-place (a fresh dir is
  now a distinct project and would correctly conflict).

Closes the M3 milestone; reviewed (4 findings: 1 authz-bypass via --force +
key validation + 2 LOW, all fixed). M4 (trigger/route templates) remains.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

crates/picloud-cli/src/linkstate.rs

@@ -13,6 +13,59 @@ use serde::{Deserialize, Serialize};
 
 const DIR: &str = ".picloud";
 const PLAN_FILE: &str = "plan.json";
+const PROJECT_FILE: &str = "project.json";
+
+/// The repo's stable project identity (§7, M3): a random, opaque key minted on
+/// first need and persisted (gitignored) in `.picloud/`. It is the server-side
+/// ownership handle — the same repo keeps the same project across clones/CI
+/// because the key travels in the working tree, never in a committed file.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ProjectLink {
+    pub key: String,
+}
+
+fn project_path(base: &Path) -> PathBuf {
+    base.join(DIR).join(PROJECT_FILE)
+}
+
+/// Read the project key, if one has been minted under `base/.picloud/`.
+#[must_use]
+pub fn read_project_key(base: &Path) -> Option<String> {
+    let body = fs::read(project_path(base)).ok()?;
+    serde_json::from_slice::<ProjectLink>(&body)
+        .ok()
+        .map(|l| l.key)
+}
+
+/// Read the project key, minting and persisting a fresh one if absent. Used by
+/// the tree `plan`/`apply` paths so a repo that never ran `pic init` still gets
+/// a stable ownership identity on first use. The new key is a random v4 UUID.
+pub fn ensure_project_key(base: &Path) -> Result<String> {
+    if let Some(k) = read_project_key(base) {
+        return Ok(k);
+    }
+    let key = uuid::Uuid::new_v4().to_string();
+    write_project_key(base, &key)?;
+    Ok(key)
+}
+
+/// Persist `key` as the project identity, creating `.picloud/` (self-ignored)
+/// if needed. Idempotent overwrite — callers usually go through
+/// [`ensure_project_key`].
+pub fn write_project_key(base: &Path, key: &str) -> Result<()> {
+    let dir = base.join(DIR);
+    fs::create_dir_all(&dir).with_context(|| format!("creating {}", dir.display()))?;
+    let ignore = dir.join(".gitignore");
+    if !ignore.exists() {
+        fs::write(&ignore, "*\n").context("writing .picloud/.gitignore")?;
+    }
+    let body = serde_json::to_vec_pretty(&ProjectLink {
+        key: key.to_string(),
+    })
+    .context("encoding .picloud/project.json")?;
+    fs::write(project_path(base), body).context("writing .picloud/project.json")?;
+    Ok(())
+}
 
 /// The recorded result of the last `pic plan`, scoped to the app it was for.
 #[derive(Debug, Clone, Serialize, Deserialize)]