@lovehlmmm/primekit 1.0.0

package/skills/worktree/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: pk:worktree
+description: "Create, inspect, and clean isolated git worktrees. Use for feature isolation, worktree health audits, stale cleanup, and monorepo or submodule workflows."
+user-invocable: true
+when_to_use: "Invoke for isolated worktrees, stale cleanup, or worktree audits."
+category: dev-tools
+keywords: [worktree, parallel, monorepo, isolation]
+argument-hint: "[feature-description] OR [project] [feature]"
+metadata:
+  author: primekit
+  version: "1.1.0"
+---
+
+# Git Worktree
+
+Create an isolated git worktree for parallel feature development.
+
+## Workflow
+
+### Step 1: Get Repo Info
+
+```bash
+node scripts/worktree.cjs info --json
+```
+
+Parse JSON response for: `repoType`, `baseBranch`, `projects`, `worktreeRoot`,
+`worktreeRootSource`, `dirtyState`, `dirtyDetails`.
+
+### Step 2: Detect Branch Naming Mode
+
+**Check for exact branch name first:**
+If caller provides a pre-formed branch name (contains uppercase letters, issue tracker keys like `ABC-1234`, forward slashes for multi-segment conventions like `user/type/feature`, or explicitly says "use this exact branch name"):
+→ Use `--no-prefix` flag — skip Step 3, pass name directly as slug.
+Examples:
+- `"ND-1377-cleanup-docs"` → `--no-prefix` → branch `ND-1377-cleanup-docs`
+- `"kai/feat/604-startup-option"` → `--no-prefix` → branch `kai/feat/604-startup-option`
+
+**Otherwise, detect prefix from description:**
+- "fix", "bug", "error", "issue" → `fix`
+- "refactor", "restructure", "rewrite" → `refactor`
+- "docs", "documentation", "readme" → `docs`
+- "test", "spec", "coverage" → `test`
+- "chore", "cleanup", "deps" → `chore`
+- "perf", "performance", "optimize" → `perf`
+- Default → `feat`
+
+### Step 3: Convert to Slug
+
+**Skip if `--no-prefix` was chosen in Step 2.**
+
+"add authentication system" → `add-auth`
+"fix login bug" → `login-bug`
+Max 50 chars, kebab-case.
+
+### Step 4: Handle Monorepo
+
+If `repoType === "monorepo"` and project not specified, use ask_user capability:
+```javascript
+ask_user capability({
+  questions: [{
+    header: "Project",
+    question: "Which project for the worktree?",
+    options: projects.map(p => ({ label: p.name, description: p.path })),
+    multiSelect: false
+  }]
+})
+```
+
+### Step 5: Execute
+
+**Monorepo:**
+```bash
+node scripts/worktree.cjs create "<PROJECT>" "<SLUG>" --prefix <TYPE>
+```
+
+**Standalone:**
+```bash
+node scripts/worktree.cjs create "<SLUG>" --prefix <TYPE>
+```
+
+**Options:**
+- `--prefix` - Branch type: feat|fix|refactor|docs|test|chore|perf
+- `--base <branch>` - Override auto-detected base branch (default: dev→develop→main→master)
+- `--checkout-submodules` - Run `git submodule update --init --checkout --recursive` in the new worktree after create
+- `--no-prefix` - Skip branch prefix and preserve original case and slashes (for Jira keys, multi-segment branches like `user/type/feature`)
+- `--worktree-root <path>` - Override default location (only if needed)
+- `--json` - JSON output
+- `--dry-run` - Preview
+
+### Step 6: Install Dependencies
+
+Based on project context, run in background:
+- `bun.lock` → `bun install`
+- `pnpm-lock.yaml` → `pnpm install`
+- `yarn.lock` → `yarn install`
+- `package-lock.json` → `npm install`
+- `poetry.lock` → `poetry install`
+- `requirements.txt` → `pip install -r requirements.txt`
+- `Cargo.toml` → `cargo build`
+- `go.mod` → `go mod download`
+
+## Commands
+
+| Command | Usage | Description |
+|---------|-------|-------------|
+| `create` | `create [project] <feature>` | Create worktree |
+| `remove` | `remove <name-or-path>` | Remove worktree |
+| `info` | `info` | Repo info with worktree location |
+| `list` | `list` | List worktrees |
+| `status` | `status` | Inspect worktree health, normalized paths, and base-branch divergence |
+| `prune` | `prune` | Clean stale worktree metadata (`--dry-run` supported) |
+
+## JSON Output Fields
+
+When using `--json`, the command surfaces these high-signal fields:
+
+| Field | Description |
+|-------|-------------|
+| `baseBranch` | Branch the worktree is based on |
+| `baseBranchSource` | `"explicit"` (from `--base`) or `"auto-detected"` |
+| `checkoutSubmodules` | Whether create will initialize submodules after checkout |
+| `currentWorktree` | Current worktree health record from `status --json` |
+| `worktrees` | Normalized worktree records from `list --json` or `status --json` |
+| `entries` | Prune output lines from `prune --json` |
+| `worktreePath` | Absolute path to the created worktree |
+| `worktreeRootSource` | How location was determined: `--worktree-root flag`, `primekit project config`, `primekit user config`, `WORKTREE_ROOT env`, `superproject (<name>)`, `monorepo internal`, or `sibling directory` |
+| `warnings` | Non-fatal notices, e.g. an absolute `worktree.root` in project config being skipped |
+
+## Notes
+
+- Script auto-detects superproject, monorepo, and standalone repos
+- Default worktree location, highest priority first: `--worktree-root` flag > `worktree.root` in project `.primekit/config.yaml` > `worktree.root` in user `~/.primekit/config.yaml` > `WORKTREE_ROOT` env var > superproject > monorepo > sibling
+- Use `--worktree-root` only to override defaults
+- Use `--base` for long-lived variant branches (e.g., `main-dsl`) that diverge from auto-detected base
+- `status` normalizes the main checkout path in submodule repos before reporting worktree health
+- `prune --dry-run` is the safe first pass when auditing stale metadata
+- Env templates (`.env*.example`) auto-copied with `.example` suffix removed
+
+## Configuring a default worktree root
+
+Persist a default so `create` never has to pass `--worktree-root` by hand:
+
+```bash
+primekit config prefs set worktree.root ../my-app-worktrees --scope project
+primekit config prefs set worktree.root /Volumes/dev/worktrees --scope user
+primekit config prefs unset worktree.root --scope project
+```
+
+- **Project scope** (`.primekit/config.yaml`, usually committed) only honors a
+  **relative** path, resolved against the project root — never `process.cwd()`.
+  An absolute value there is skipped with a warning and resolution falls
+  through to the next scope, because a committed project config can arrive
+  from an untrusted clone.
+- **User scope** (`~/.primekit/config.yaml`) accepts either a relative path
+  (also resolved against the project root) or an absolute path, which is the
+  right choice for a portable-drive or external-volume worktree layout.
+- The `WORKTREE_ROOT` environment variable still works, but now ranks below
+  both config scopes — set it for a one-off session override, use
+  `worktree.root` for anything you want to persist.
+- `--worktree-root` on the CLI always wins over every other source.
+
+**Editor/host integration:** Claude Code's own `WorktreeCreate` and
+`WorktreeRemove` hooks
+(https://code.claude.com/docs/en/worktrees#non-git-version-control) and
+Codex's Worktree root setting
+(https://learn.chatgpt.com/docs/environments/git-worktrees) manage worktrees
+independently of this skill. `worktree.root` only changes where
+`pk:worktree`'s own `create` command places a new worktree; it has no effect
+on worktrees the host application creates through its native mechanism.
+
+## Workflow Position
+
+**Typically precedes:** `/pk:cook` (implement in worktree), `/pk:fix` (fix in worktree)
+**Setup skill** — creates isolated environment before implementation.

package/skills/worktree/scripts/mini-yaml-parser.cjs

@@ -0,0 +1,232 @@
+/**
+ * Hand-rolled minimal YAML subset parser for `.agentkit/config.yaml`,
+ * shared (by copy, not by reference — this skill has no dependency on
+ * ak-journal) with `kits/core/skills/ak-journal/scripts/mini-yaml-parser.cjs`.
+ *
+ * Supports exactly what the `worktree:` block of `.agentkit/config.yaml` /
+ * `~/.agentkit/config.yaml` needs:
+ *   - nested maps via 2-space indentation
+ *   - scalar values: unquoted, single-quoted, double-quoted strings,
+ *     booleans (true/false), null (null/~/empty), integers/floats
+ *   - lists of scalars (`- value` block style)
+ *   - lists of maps / "array-of-maps" (`- key: value` block style, with
+ *     following indented `key: value` lines belonging to the same list item)
+ *   - inline flow lists of maps: `channels: [{id: x, platform: y}, {...}]`
+ *   - full-line comments (`# ...`) and inline comments after a scalar value
+ *   - blank lines
+ *
+ * Deliberately NOT supported (out of scope for this skill's config shape):
+ *   anchors/aliases, multi-doc streams, block scalars (| / >), tags, dates.
+ */
+
+function stripInlineComment(text) {
+  // Only strip a `#` that starts a new token (preceded by whitespace or at
+  // start) and is not inside quotes.
+  let inSingle = false;
+  let inDouble = false;
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i];
+    if (ch === "'" && !inDouble) inSingle = !inSingle;
+    else if (ch === '"' && !inSingle) inDouble = !inDouble;
+    else if (ch === '#' && !inSingle && !inDouble && (i === 0 || /\s/.test(text[i - 1]))) {
+      return text.slice(0, i);
+    }
+  }
+  return text;
+}
+
+function parseScalar(raw) {
+  const value = raw.trim();
+  if (value === '' || value === '~' || value === 'null' || value === 'Null' || value === 'NULL') {
+    return null;
+  }
+  if (value === 'true' || value === 'True' || value === 'TRUE') return true;
+  if (value === 'false' || value === 'False' || value === 'FALSE') return false;
+  if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+    return value.slice(1, -1).replace(/\\n/g, '\n').replace(/\\t/g, '\t').replace(/\\"/g, '"');
+  }
+  if (value.startsWith("'") && value.endsWith("'") && value.length >= 2) {
+    return value.slice(1, -1).replace(/''/g, "'");
+  }
+  if (value.startsWith('[') && value.endsWith(']')) {
+    return parseFlowList(value);
+  }
+  if (/^-?\d+$/.test(value)) return parseInt(value, 10);
+  if (/^-?\d+\.\d+$/.test(value)) return parseFloat(value);
+  return value;
+}
+
+/** Parse a flow-style list: `[a, b, {k: v}, "c"]`. Minimal, no nested flow maps beyond 1 level. */
+function parseFlowList(text) {
+  const inner = text.slice(1, -1).trim();
+  if (inner === '') return [];
+  const items = splitFlowItems(inner);
+  return items.map((item) => {
+    const trimmed = item.trim();
+    if (trimmed.startsWith('{') && trimmed.endsWith('}')) {
+      return parseFlowMap(trimmed);
+    }
+    return parseScalar(trimmed);
+  });
+}
+
+function parseFlowMap(text) {
+  const inner = text.slice(1, -1).trim();
+  const map = {};
+  if (inner === '') return map;
+  const pairs = splitFlowItems(inner);
+  for (const pair of pairs) {
+    const idx = pair.indexOf(':');
+    if (idx === -1) continue;
+    const key = pair.slice(0, idx).trim().replace(/^["']|["']$/g, '');
+    const value = pair.slice(idx + 1).trim();
+    map[key] = parseScalar(value);
+  }
+  return map;
+}
+
+/** Split top-level comma-separated items in a flow list/map, respecting nesting + quotes. */
+function splitFlowItems(text) {
+  const items = [];
+  let depth = 0;
+  let current = '';
+  let inSingle = false;
+  let inDouble = false;
+  for (const ch of text) {
+    if (ch === "'" && !inDouble) inSingle = !inSingle;
+    else if (ch === '"' && !inSingle) inDouble = !inDouble;
+    if (!inSingle && !inDouble) {
+      if (ch === '{' || ch === '[') depth += 1;
+      if (ch === '}' || ch === ']') depth -= 1;
+      if (ch === ',' && depth === 0) {
+        items.push(current);
+        current = '';
+        continue;
+      }
+    }
+    current += ch;
+  }
+  if (current.trim() !== '') items.push(current);
+  return items;
+}
+
+function indentOf(line) {
+  const match = line.match(/^ */);
+  return match ? match[0].length : 0;
+}
+
+/**
+ * Parse YAML block-style text into a plain JS object.
+ * @param {string} content
+ * @returns {Record<string, unknown>}
+ */
+function parseYaml(content) {
+  const rawLines = content.split('\n');
+  const lines = [];
+  for (const rawLine of rawLines) {
+    if (rawLine.trim() === '' || rawLine.trim().startsWith('#')) continue;
+    const withoutComment = stripInlineComment(rawLine).replace(/\s+$/, '');
+    if (withoutComment.trim() === '') continue;
+    lines.push({ indent: indentOf(rawLine), text: withoutComment.trim() });
+  }
+
+  let pos = 0;
+
+  function parseBlock(indent) {
+    const result = {};
+    while (pos < lines.length && lines[pos].indent >= indent) {
+      const line = lines[pos];
+      if (line.indent > indent) {
+        // Orphaned deeper indent with no owning key — skip defensively.
+        pos += 1;
+        continue;
+      }
+      if (line.text.startsWith('- ') || line.text === '-') {
+        // A bare list at this indent with no key is invalid in our subset; skip.
+        pos += 1;
+        continue;
+      }
+      const colonIdx = line.text.indexOf(':');
+      if (colonIdx === -1) {
+        pos += 1;
+        continue;
+      }
+      const key = line.text.slice(0, colonIdx).trim().replace(/^["']|["']$/g, '');
+      const rest = line.text.slice(colonIdx + 1).trim();
+      pos += 1;
+
+      if (rest !== '') {
+        result[key] = parseScalar(rest);
+        continue;
+      }
+
+      // No inline value: either a nested map or a list follows at deeper indent.
+      if (pos < lines.length && lines[pos].indent > indent && lines[pos].text.startsWith('- ')) {
+        result[key] = parseList(lines[pos].indent);
+      } else if (pos < lines.length && lines[pos].indent > indent) {
+        result[key] = parseBlock(lines[pos].indent);
+      } else {
+        result[key] = null;
+      }
+    }
+    return result;
+  }
+
+  function parseList(indent) {
+    const items = [];
+    while (pos < lines.length && lines[pos].indent === indent && lines[pos].text.startsWith('-')) {
+      const line = lines[pos];
+      const afterDash = line.text.slice(1).trim();
+      pos += 1;
+
+      if (afterDash === '') {
+        // "-" alone on its line, nested map follows more indented.
+        if (pos < lines.length && lines[pos].indent > indent) {
+          items.push(parseBlock(lines[pos].indent));
+        } else {
+          items.push(null);
+        }
+        continue;
+      }
+
+      const colonIdx = afterDash.indexOf(':');
+      if (colonIdx === -1) {
+        // Plain scalar list item (`- value`), possibly a flow list/map.
+        items.push(parseScalar(afterDash));
+        continue;
+      }
+
+      // "- key: value" starts an array-of-maps item; subsequent more-indented
+      // "key: value" lines (indent === indent + 2, i.e. deeper than the dash
+      // column) belong to the same map item.
+      const itemIndent = indent + 2;
+      const firstKey = afterDash.slice(0, colonIdx).trim().replace(/^["']|["']$/g, '');
+      const firstRest = afterDash.slice(colonIdx + 1).trim();
+      const map = { [firstKey]: firstRest === '' ? null : parseScalar(firstRest) };
+
+      while (pos < lines.length && lines[pos].indent === itemIndent) {
+        const innerLine = lines[pos];
+        const innerColon = innerLine.text.indexOf(':');
+        if (innerColon === -1) break;
+        const innerKey = innerLine.text.slice(0, innerColon).trim().replace(/^["']|["']$/g, '');
+        const innerRest = innerLine.text.slice(innerColon + 1).trim();
+        pos += 1;
+        if (innerRest !== '') {
+          map[innerKey] = parseScalar(innerRest);
+        } else if (pos < lines.length && lines[pos].indent > itemIndent && lines[pos].text.startsWith('-')) {
+          map[innerKey] = parseList(lines[pos].indent);
+        } else if (pos < lines.length && lines[pos].indent > itemIndent) {
+          map[innerKey] = parseBlock(lines[pos].indent);
+        } else {
+          map[innerKey] = null;
+        }
+      }
+      items.push(map);
+    }
+    return items;
+  }
+
+  return parseBlock(0);
+}
+
+module.exports = { parseYaml, parseScalar, parseFlowList, parseFlowMap };

package/skills/worktree/scripts/resolve-worktree-root.cjs

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+/**
+ * Resolve the persisted `worktree.root` AgentKit config value for ak:worktree.
+ *
+ * Precedence (highest → lowest), matching `getWorktreeRoot()` in
+ * `worktree.cjs`:
+ *   1. Project `.agentkit/config.yaml` `worktree.root`
+ *   2. User AgentKit home `config.yaml` `worktree.root` (`$AGENTKIT_HOME` when
+ *      set, otherwise `<os-home>/.agentkit`)
+ * (The explicit `--worktree-root` flag outranks both of these and the
+ * `WORKTREE_ROOT` env var ranks below both; `worktree.cjs` checks the flag
+ * before calling here and falls back to the env var only when this module
+ * returns no result.)
+ *
+ * SECURITY: project scope never honors an absolute/rooted value — a
+ * project's `.agentkit/config.yaml` is committed and can arrive from an
+ * untrusted cloned repo. A rooted value there is skipped with a warning
+ * (never a hard error) and resolution falls through to user config. User
+ * scope is the operator's own trusted file, so it may be absolute (the
+ * portable-drive case) or relative. A relative value at either scope
+ * resolves against `gitRoot`, not `process.cwd()`, and is bounded to
+ * `dirname(gitRoot)` so it cannot escape onto the rest of the filesystem
+ * (see resolveRelativeValue below).
+ *
+ * CLI usage:
+ *   node resolve-worktree-root.cjs --git-root <path> [--agentkit-home <path>] [--json]
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { parseArgs } = require('util');
+
+const { parseYaml } = require('./mini-yaml-parser.cjs');
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function readYamlFile(filePath) {
+  try {
+    if (fs.existsSync(filePath) && fs.statSync(filePath).isFile()) {
+      const parsed = parseYaml(fs.readFileSync(filePath, 'utf8'));
+      return isPlainObject(parsed) ? parsed : {};
+    }
+  } catch (error) {
+    if (process.env.DEBUG) {
+      console.error(`[resolve-worktree-root] failed to parse ${filePath}: ${error.message}`);
+    }
+  }
+  return {};
+}
+
+/**
+ * Mirrors the Go `isRootedPlansDirValue` (apps/cli/internal/runtime/ckprefs/plans_dir.go):
+ * reports whether `v` is an absolute or rooted path, evaluated identically on
+ * every OS regardless of the host platform, so a value written on one
+ * platform (e.g. a Windows drive letter) is recognized the same way when this
+ * script runs on another.
+ */
+function isRootedWorktreeRootValue(v) {
+  if (path.isAbsolute(v)) return true;
+  if (v.startsWith('/') || v.startsWith('\\')) return true;
+  if (v.length >= 2 && v[1] === ':') {
+    const c = v[0];
+    if ((c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z')) return true;
+  }
+  return false;
+}
+
+/** Normalize backslashes to forward slashes so a relative value written on
+ * Windows resolves the same way on macOS/Linux (mirrors PlansDirName's
+ * GOOS-independent backslash normalization). */
+function normalizeSeparators(value) {
+  return value.replace(/\\/g, '/');
+}
+
+function resolveRelativeAgainstGitRoot(gitRoot, value) {
+  return path.resolve(gitRoot, normalizeSeparators(value));
+}
+
+/** First `/`-delimited path segment of an already-forward-slash-normalized value. */
+function firstPathSegment(cleanValue) {
+  const idx = cleanValue.indexOf('/');
+  return idx >= 0 ? cleanValue.slice(0, idx) : cleanValue;
+}
+
+/** Reports whether `target` is `boundary` itself or nested somewhere under it. */
+function isWithinBoundary(target, boundary) {
+  const rel = path.relative(boundary, target);
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+/**
+ * Resolve symlinks for the deepest existing ancestor of `p`, then reattach
+ * the remaining (possibly not-yet-created) path segments unresolved.
+ *
+ * SECURITY: `path.resolve`/`path.relative` are purely lexical — they never
+ * consult the filesystem. A symlink committed inside the repo (e.g. a
+ * project-controlled `escape -> /outside`) plus a project-config value like
+ * `escape/wt` would pass the lexical `dirname(gitRoot)` boundary check
+ * (`escape/wt` looks like it's inside the project) while `git worktree add`
+ * follows the symlink to a location entirely outside that boundary — exactly
+ * the untrusted-clone escape this module exists to prevent. `fs.realpathSync`
+ * alone throws for a path that doesn't exist yet (the worktree directory
+ * itself usually doesn't), so only the deepest existing ancestor is
+ * realpath'd; the remaining not-yet-created segments are reattached as-is.
+ */
+function realpathDeepestExisting(p) {
+  const trailing = [];
+  let current = p;
+  for (;;) {
+    try {
+      const real = fs.realpathSync(current);
+      return trailing.length ? path.join(real, ...trailing.reverse()) : real;
+    } catch (error) {
+      if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') throw error;
+      const parent = path.dirname(current);
+      if (parent === current) return p;
+      trailing.push(path.basename(current));
+      current = parent;
+    }
+  }
+}
+
+/**
+ * Resolve a relative `worktree.root` value shared by both scopes, or null
+ * (with a pushed warning) when the value cannot be safely honored.
+ *
+ * SECURITY: a relative value is contained to `dirname(gitRoot)` — the
+ * project root and its immediate parent — so the documented sibling layout
+ * (`../my-app-worktrees`) and an in-project value (`worktrees`) both resolve,
+ * while an unbounded `../../../../etc/cron.d`-style value cannot escape onto
+ * the rest of the filesystem. This mirrors the intent (not the exact rule) of
+ * the Go `isRootedPlansDirValue`/`PlansDirName` precedent
+ * (apps/cli/internal/runtime/ckprefs/plans_dir.go), which rejects any `..`
+ * outright; that stricter rule is not used here because the sibling layout
+ * this project's own issue recommends requires exactly one `..` to work.
+ * A `.agentkit`-first-segment value is rejected outright, matching that same
+ * precedent, since worktree content there would collide with config.
+ */
+function resolveRelativeValue(scope, gitRoot, value, warnings) {
+  const clean = path.posix.normalize(normalizeSeparators(value));
+  const segment = firstPathSegment(clean).toLowerCase();
+  if (segment === '.agentkit') {
+    warnings.push(
+      `worktree.root in ${scope} config points inside the .agentkit directory ("${value}"); that location is reserved for AgentKit configuration, so it is being skipped.`
+    );
+    return null;
+  }
+
+  const resolved = resolveRelativeAgainstGitRoot(gitRoot, value);
+  const boundary = path.dirname(gitRoot);
+  // Compare realpath'd (symlink-resolved) locations, not the lexical paths —
+  // see realpathDeepestExisting's SECURITY note above.
+  const resolvedReal = realpathDeepestExisting(resolved);
+  const boundaryReal = realpathDeepestExisting(boundary);
+  if (!isWithinBoundary(resolvedReal, boundaryReal)) {
+    warnings.push(
+      `worktree.root in ${scope} config ("${value}") resolves outside the project and its parent directory, so it is being skipped as a safety boundary. Use a path no deeper than one level above the project root (e.g. "../my-app-worktrees"), or set an absolute path in user config instead.`
+    );
+    return null;
+  }
+
+  return resolved;
+}
+
+/**
+ * Resolve one scope's raw `worktree.root` value into an absolute directory,
+ * or null (with a pushed warning) when the value cannot be honored at this
+ * scope.
+ */
+function resolveScopeValue(scope, gitRoot, rawValue, warnings) {
+  const value = typeof rawValue === 'string' ? rawValue.trim() : '';
+  if (!value) return null;
+
+  const rooted = isRootedWorktreeRootValue(value);
+  if (scope === 'project') {
+    if (rooted) {
+      warnings.push(
+        `worktree.root in project config is an absolute path ("${value}"); project scope only honors a relative path, so it is being skipped. Set it in your user config (~/.agentkit/config.yaml) instead.`
+      );
+      return null;
+    }
+    return resolveRelativeValue(scope, gitRoot, value, warnings);
+  }
+
+  // User scope: an absolute value (e.g. a portable drive) is honored as-is;
+  // a relative value resolves (and is bounded) the same way as project scope.
+  return rooted ? value : resolveRelativeValue(scope, gitRoot, value, warnings);
+}
+
+/**
+ * @param {object} options
+ * @param {string} options.gitRoot repo root a relative worktree.root resolves from
+ * @param {string} options.agentkitHome the AgentKit home directory holding the
+ *   user-scope config.yaml — `$AGENTKIT_HOME` when set, otherwise
+ *   `<os-home>/.agentkit`. The caller resolves this (mirroring every other
+ *   AGENTKIT_HOME-aware reader in the repo) so this module never guesses at
+ *   an override it cannot see.
+ * @returns {{root: string|null, source: 'project'|'user'|null, warnings: string[]}}
+ */
+function resolveWorktreeRoot({ gitRoot, agentkitHome }) {
+  const warnings = [];
+
+  const projectConfig = readYamlFile(path.join(gitRoot, '.agentkit', 'config.yaml'));
+  const userConfig = readYamlFile(path.join(agentkitHome, 'config.yaml'));
+
+  const projectRaw = isPlainObject(projectConfig.worktree) ? projectConfig.worktree.root : undefined;
+  const projectResolved = resolveScopeValue('project', gitRoot, projectRaw, warnings);
+  if (projectResolved) {
+    return { root: projectResolved, source: 'project', warnings };
+  }
+
+  const userRaw = isPlainObject(userConfig.worktree) ? userConfig.worktree.root : undefined;
+  const userResolved = resolveScopeValue('user', gitRoot, userRaw, warnings);
+  if (userResolved) {
+    return { root: userResolved, source: 'user', warnings };
+  }
+
+  return { root: null, source: null, warnings };
+}
+
+function main() {
+  let values;
+  try {
+    ({ values } = parseArgs({
+      options: {
+        'git-root': { type: 'string' },
+        'agentkit-home': { type: 'string' },
+        json: { type: 'boolean', default: false },
+        help: { type: 'boolean', default: false },
+      },
+      allowPositionals: false,
+    }));
+  } catch (error) {
+    console.error(`[resolve-worktree-root] invalid arguments: ${error.message}`);
+    process.exit(1);
+    return;
+  }
+
+  if (values.help || !values['git-root']) {
+    console.error('Usage: node resolve-worktree-root.cjs --git-root <path> [--agentkit-home <path>] [--json]');
+    process.exit(values.help ? 0 : 1);
+    return;
+  }
+
+  const gitRoot = path.resolve(values['git-root']);
+  const homeDir = process.env.HOME || process.env.USERPROFILE || os.homedir();
+  const agentkitHome = values['agentkit-home']
+    ? path.resolve(values['agentkit-home'])
+    : (process.env.AGENTKIT_HOME || path.join(homeDir, '.agentkit'));
+  const resolved = resolveWorktreeRoot({ gitRoot, agentkitHome });
+  console.log(values.json ? JSON.stringify(resolved, null, 2) : JSON.stringify(resolved));
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (error) {
+    console.error(`[resolve-worktree-root] error: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+module.exports = { resolveWorktreeRoot, isRootedWorktreeRootValue };