@cr1992/agentkit 1.0.0

package/domains/worktree/worktree-trace.mjs

@@ -0,0 +1,478 @@
+#!/usr/bin/env node
+// @ts-check
+
+import { randomUUID } from 'node:crypto';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { hostname } from 'node:os';
+import { join } from 'node:path';
+
+import { ensureRepositoryIdentity, readRepositoryIdentity } from './worktree-profile.mjs';
+
+export const TRACE_SCHEMA_VERSION = 1;
+export const LOCK_STALE_AFTER_MS = 5 * 60 * 1000;
+export const LOCK_WAIT_TIMEOUT_MS = 10 * 1000;
+export const LOCK_RETRY_MS = 10;
+const MALFORMED_LOCK_GRACE_MS = 250;
+const SLEEP_CELL = new Int32Array(new SharedArrayBuffer(4));
+
+export class WorktreeTraceError extends Error {
+  /** @param {string} code @param {string} message */
+  constructor(code, message) {
+    super(message);
+    this.name = 'WorktreeTraceError';
+    this.code = code;
+  }
+}
+
+/** @param {string} commonDir */
+export function traceLayout(commonDir) {
+  const root = join(commonDir, 'worktree-trace', 'v1');
+  return {
+    root,
+    records: join(root, 'records'),
+    events: join(root, 'events'),
+    locks: join(root, 'locks'),
+    repository: join(root, 'repository.json'),
+  };
+}
+
+/** @param {{common_dir:string}} context */
+export function initializeTraceStore(context) {
+  const repository = ensureRepositoryIdentity(context);
+  const layout = traceLayout(context.common_dir);
+  mkdirSync(layout.records, { recursive: true });
+  mkdirSync(layout.events, { recursive: true });
+  mkdirSync(layout.locks, { recursive: true });
+  return { layout, repository };
+}
+
+/** @param {number} milliseconds */
+function sleep(milliseconds) {
+  Atomics.wait(SLEEP_CELL, 0, 0, milliseconds);
+}
+
+/** @param {number} pid */
+function processIsAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error && typeof error === 'object' && 'code' in error && error.code === 'EPERM';
+  }
+}
+
+/** @param {string} commonDir @param {string} worktreeId */
+export function inspectRecordLock(commonDir, worktreeId) {
+  const lockDir = join(traceLayout(commonDir).locks, `${worktreeId}.lock`);
+  if (!existsSync(lockDir)) return { state: 'absent', lock_dir: lockDir };
+  let ageMs = Number.POSITIVE_INFINITY;
+  try {
+    ageMs = Math.max(0, Date.now() - statSync(lockDir).mtimeMs);
+  } catch {
+    return { state: 'raced', lock_dir: lockDir };
+  }
+  const ownerPath = join(lockDir, 'owner.json');
+  if (!existsSync(ownerPath)) return { state: 'malformed', lock_dir: lockDir, age_ms: ageMs };
+  try {
+    const owner = JSON.parse(readFileSync(ownerPath, 'utf8'));
+    if (
+      !owner ||
+      typeof owner !== 'object' ||
+      !Number.isInteger(owner.pid) ||
+      typeof owner.hostname !== 'string' ||
+      typeof owner.created_at !== 'string' ||
+      typeof owner.token !== 'string'
+    ) {
+      return { state: 'malformed', lock_dir: lockDir, age_ms: ageMs, owner };
+    }
+    const sameHost = owner.hostname === hostname();
+    const alive = sameHost ? processIsAlive(owner.pid) : null;
+    const stale = sameHost ? !alive : ageMs > LOCK_STALE_AFTER_MS;
+    return {
+      state: stale ? 'stale' : 'held',
+      lock_dir: lockDir,
+      age_ms: ageMs,
+      owner,
+      same_host: sameHost,
+      pid_alive: alive,
+    };
+  } catch {
+    return { state: 'malformed', lock_dir: lockDir, age_ms: ageMs };
+  }
+}
+
+/**
+ * @param {string} commonDir
+ * @param {string} worktreeId
+ * @param {{waitTimeoutMs?:number, command?:string}} [options]
+ */
+function acquireRecordLock(commonDir, worktreeId, options = {}) {
+  const layout = traceLayout(commonDir);
+  mkdirSync(layout.locks, { recursive: true });
+  const lockDir = join(layout.locks, `${worktreeId}.lock`);
+  const startedAt = Date.now();
+  const waitTimeoutMs = options.waitTimeoutMs ?? LOCK_WAIT_TIMEOUT_MS;
+  let recoveredOwner = null;
+
+  for (;;) {
+    const token = randomUUID();
+    try {
+      mkdirSync(lockDir);
+      const owner = {
+        pid: process.pid,
+        hostname: hostname(),
+        created_at: new Date().toISOString(),
+        command: options.command ?? process.argv.join(' '),
+        token,
+      };
+      writeFileSync(join(lockDir, 'owner.json'), `${JSON.stringify(owner, null, 2)}\n`, {
+        encoding: 'utf8',
+        flag: 'wx',
+      });
+      return { lock_dir: lockDir, owner, recovered_owner: recoveredOwner };
+    } catch (error) {
+      const code = error && typeof error === 'object' && 'code' in error ? error.code : null;
+      if (code !== 'EEXIST') {
+        if (existsSync(lockDir) && !existsSync(join(lockDir, 'owner.json'))) {
+          // mkdir 成功、owner 写入失败：由显式 recover 处理，避免误删未知锁。
+        }
+        throw new WorktreeTraceError('LOCK_ACQUIRE_FAILED', `无法创建 record lock ${lockDir}: ${String(error)}`);
+      }
+    }
+
+    const finding = inspectRecordLock(commonDir, worktreeId);
+    if (finding.state === 'stale') {
+      const quarantine = `${lockDir}.stale.${randomUUID()}`;
+      try {
+        renameSync(lockDir, quarantine);
+        recoveredOwner = finding.owner ?? null;
+        rmSync(quarantine, { recursive: true, force: true });
+        continue;
+      } catch {
+        // 另一进程可能先完成接管，重新观察。
+      }
+    } else if (finding.state === 'malformed' && (finding.age_ms ?? 0) > MALFORMED_LOCK_GRACE_MS) {
+      throw new WorktreeTraceError(
+        'LOCK_MALFORMED',
+        `record lock 缺少有效 owner.json: ${lockDir}；请 doctor 后显式 recover。`,
+      );
+    }
+
+    if (Date.now() - startedAt >= waitTimeoutMs) {
+      throw new WorktreeTraceError('LOCK_BUSY', `record lock 等待超时: ${lockDir}`);
+    }
+    sleep(LOCK_RETRY_MS);
+  }
+}
+
+/** @param {{lock_dir:string, owner:{token:string}}} lock */
+function releaseRecordLock(lock) {
+  const ownerPath = join(lock.lock_dir, 'owner.json');
+  try {
+    const current = JSON.parse(readFileSync(ownerPath, 'utf8'));
+    if (current.token !== lock.owner.token) {
+      throw new WorktreeTraceError('LOCK_OWNERSHIP_LOST', `record lock token 已变化: ${lock.lock_dir}`);
+    }
+    rmSync(lock.lock_dir, { recursive: true });
+  } catch (error) {
+    if (error instanceof WorktreeTraceError) throw error;
+    if (existsSync(lock.lock_dir)) {
+      throw new WorktreeTraceError('LOCK_RELEASE_FAILED', `无法释放 record lock: ${lock.lock_dir}`);
+    }
+  }
+}
+
+/** @param {string} commonDir @param {string} worktreeId @param {{forceMalformed?:boolean}} [options] */
+export function recoverRecordLock(commonDir, worktreeId, options = {}) {
+  const finding = inspectRecordLock(commonDir, worktreeId);
+  if (finding.state === 'absent' || finding.state === 'raced') return finding;
+  if (finding.state === 'held') {
+    throw new WorktreeTraceError('LOCK_STILL_HELD', `lock 仍由存活进程持有: ${finding.lock_dir}`);
+  }
+  if (finding.state === 'malformed' && !options.forceMalformed) {
+    throw new WorktreeTraceError('LOCK_MALFORMED', 'malformed lock 需要显式 forceMalformed。');
+  }
+  const quarantine = `${finding.lock_dir}.recovered.${randomUUID()}`;
+  renameSync(finding.lock_dir, quarantine);
+  rmSync(quarantine, { recursive: true, force: true });
+  return { ...finding, recovered: true };
+}
+
+/** @param {string} commonDir @param {string} worktreeId */
+function eventDirectory(commonDir, worktreeId) {
+  return join(traceLayout(commonDir).events, worktreeId);
+}
+
+/** @param {unknown} event @param {string} source */
+function validateEvent(event, source) {
+  if (
+    !event ||
+    typeof event !== 'object' ||
+    event.schema_version !== TRACE_SCHEMA_VERSION ||
+    typeof event.event_id !== 'string' ||
+    typeof event.worktree_id !== 'string' ||
+    typeof event.event_type !== 'string' ||
+    typeof event.occurred_at !== 'string' ||
+    !(event.previous_event_id === null || typeof event.previous_event_id === 'string')
+  ) {
+    throw new WorktreeTraceError('EVENT_INVALID', `event 格式无效: ${source}`);
+  }
+  return event;
+}
+
+/** @param {string} commonDir @param {string} worktreeId */
+export function readEventChain(commonDir, worktreeId) {
+  const dir = eventDirectory(commonDir, worktreeId);
+  if (!existsSync(dir)) return [];
+  const events = [];
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith('.json')) continue;
+    const path = join(dir, name);
+    let parsed;
+    try {
+      parsed = JSON.parse(readFileSync(path, 'utf8'));
+    } catch {
+      throw new WorktreeTraceError('EVENT_INVALID', `event JSON 损坏: ${path}`);
+    }
+    const event = validateEvent(parsed, path);
+    if (event.worktree_id !== worktreeId) {
+      throw new WorktreeTraceError('EVENT_WRONG_RECORD', `event worktree_id 与目录不符: ${path}`);
+    }
+    events.push(event);
+  }
+  if (events.length === 0) return [];
+
+  const byPrevious = new Map();
+  for (const event of events) {
+    const previous = event.previous_event_id ?? '__GENESIS__';
+    const followers = byPrevious.get(previous) ?? [];
+    followers.push(event);
+    byPrevious.set(previous, followers);
+  }
+  const genesis = byPrevious.get('__GENESIS__') ?? [];
+  if (genesis.length !== 1) {
+    throw new WorktreeTraceError('EVENT_CHAIN_FORKED', `event chain genesis 数量=${genesis.length}，应为 1。`);
+  }
+
+  const chain = [];
+  const visited = new Set();
+  let current = genesis[0];
+  for (;;) {
+    if (visited.has(current.event_id)) {
+      throw new WorktreeTraceError('EVENT_CHAIN_CYCLE', `event chain 出现环: ${current.event_id}`);
+    }
+    visited.add(current.event_id);
+    chain.push(current);
+    const followers = byPrevious.get(current.event_id) ?? [];
+    if (followers.length > 1) {
+      throw new WorktreeTraceError('EVENT_CHAIN_FORKED', `event ${current.event_id} 有多个后继。`);
+    }
+    if (followers.length === 0) break;
+    current = followers[0];
+  }
+  if (chain.length !== events.length) {
+    throw new WorktreeTraceError('EVENT_CHAIN_DISCONNECTED', '存在不属于权威 chain 的 event。');
+  }
+  return chain;
+}
+
+/** @param {string} commonDir @param {string} worktreeId */
+export function readRecordCache(commonDir, worktreeId) {
+  const path = join(traceLayout(commonDir).records, `${worktreeId}.json`);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    throw new WorktreeTraceError('RECORD_CACHE_INVALID', `record cache 损坏: ${path}`);
+  }
+}
+
+/** @param {string} commonDir */
+export function listRecordCacheEntries(commonDir) {
+  const recordsDir = traceLayout(commonDir).records;
+  if (!existsSync(recordsDir)) return [];
+  return readdirSync(recordsDir)
+    .filter((name) => name.endsWith('.json'))
+    .map((name) => {
+      const path = join(recordsDir, name);
+      try {
+        return { path, record: JSON.parse(readFileSync(path, 'utf8')), error: null };
+      } catch (error) {
+        return {
+          path,
+          record: null,
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    });
+}
+
+/** @param {string} commonDir @param {string} worktreeId @param {unknown} snapshot @param {unknown} tail @param {number} count */
+function writeRecordCache(commonDir, worktreeId, snapshot, tail, count) {
+  const layout = traceLayout(commonDir);
+  mkdirSync(layout.records, { recursive: true });
+  const target = join(layout.records, `${worktreeId}.json`);
+  const temp = `${target}.${process.pid}.${randomUUID()}.tmp`;
+  const cache = {
+    ...structuredClone(snapshot),
+    last_event_id: tail.event_id,
+    event_count: count,
+    materialized_at: new Date().toISOString(),
+  };
+  writeFileSync(temp, `${JSON.stringify(cache, null, 2)}\n`, { encoding: 'utf8', flag: 'wx' });
+  try {
+    renameSync(temp, target);
+  } finally {
+    if (existsSync(temp)) unlinkSync(temp);
+  }
+  return cache;
+}
+
+/**
+ * @param {string} commonDir
+ * @param {string} repositoryId
+ * @param {string} worktreeId
+ * @param {string} eventType
+ * @param {{host:string,id:string}|null} actor
+ * @param {unknown} snapshot
+ * @param {Record<string, unknown>} details
+ * @param {string|null} previousEventId
+ */
+function appendEventFile(
+  commonDir,
+  repositoryId,
+  worktreeId,
+  eventType,
+  actor,
+  snapshot,
+  details,
+  previousEventId,
+) {
+  const dir = eventDirectory(commonDir, worktreeId);
+  mkdirSync(dir, { recursive: true });
+  const eventId = randomUUID();
+  const occurredAt = new Date().toISOString();
+  const event = {
+    schema_version: TRACE_SCHEMA_VERSION,
+    repository_id: repositoryId,
+    event_id: eventId,
+    worktree_id: worktreeId,
+    event_type: eventType,
+    occurred_at: occurredAt,
+    previous_event_id: previousEventId,
+    actor: actor ? structuredClone(actor) : null,
+    details: structuredClone(details),
+    snapshot: snapshot === null ? null : structuredClone(snapshot),
+  };
+  const filename = `${occurredAt.replaceAll(':', '-')}-${eventId}.json`;
+  writeFileSync(join(dir, filename), `${JSON.stringify(event, null, 2)}\n`, {
+    encoding: 'utf8',
+    flag: 'wx',
+  });
+  return event;
+}
+
+/**
+ * @param {{
+ *   commonDir:string,
+ *   worktreeId:string,
+ *   eventType:string,
+ *   actor?:{host:string,id:string}|null,
+ *   details?:Record<string, unknown>,
+ *   mutate:(current:Record<string, unknown>|null)=>Record<string, unknown>,
+ *   waitTimeoutMs?:number,
+ * }} options
+ */
+export function appendTraceEvent(options) {
+  if (!/^[0-9a-f-]{36}$/i.test(options.worktreeId)) {
+    throw new WorktreeTraceError('WORKTREE_ID_INVALID', `worktreeId 不是 UUID: ${options.worktreeId}`);
+  }
+  if (!/^[a-z][a-z0-9_]*$/.test(options.eventType)) {
+    throw new WorktreeTraceError('EVENT_TYPE_INVALID', `eventType 非法: ${options.eventType}`);
+  }
+  if (
+    options.actor &&
+    (typeof options.actor.host !== 'string' ||
+      options.actor.host.trim() === '' ||
+      typeof options.actor.id !== 'string' ||
+      options.actor.id.trim() === '')
+  ) {
+    throw new WorktreeTraceError('ACTOR_INVALID', 'actor.host / actor.id 必须是非空字符串。');
+  }
+
+  const repository = readRepositoryIdentity({ common_dir: options.commonDir });
+  if (!repository) {
+    throw new WorktreeTraceError('TRACE_STORE_UNINITIALIZED', 'trace store 尚未初始化。');
+  }
+  const lock = acquireRecordLock(options.commonDir, options.worktreeId, {
+    waitTimeoutMs: options.waitTimeoutMs,
+    command: `append:${options.eventType}`,
+  });
+  try {
+    let chain = readEventChain(options.commonDir, options.worktreeId);
+    let tail = chain.at(-1) ?? null;
+    const current = tail?.snapshot ? structuredClone(tail.snapshot) : null;
+
+    if (lock.recovered_owner) {
+      tail = appendEventFile(
+        options.commonDir,
+        repository.repository_id,
+        options.worktreeId,
+        'stale_lock_recovered',
+        options.actor ?? null,
+        current,
+        { recovered_owner: lock.recovered_owner },
+        tail?.event_id ?? null,
+      );
+      chain = [...chain, tail];
+    }
+
+    const next = options.mutate(current);
+    if (!next || typeof next !== 'object' || Array.isArray(next)) {
+      throw new WorktreeTraceError('SNAPSHOT_INVALID', 'mutate 必须返回 record snapshot object。');
+    }
+    if (next.worktree_id !== options.worktreeId) {
+      throw new WorktreeTraceError('SNAPSHOT_INVALID', 'snapshot.worktree_id 必须等于目标 UUID。');
+    }
+    const event = appendEventFile(
+      options.commonDir,
+      repository.repository_id,
+      options.worktreeId,
+      options.eventType,
+      options.actor ?? null,
+      next,
+      options.details ?? {},
+      tail?.event_id ?? null,
+    );
+    const cache = writeRecordCache(options.commonDir, options.worktreeId, next, event, chain.length + 1);
+    return { event, record: cache };
+  } finally {
+    releaseRecordLock(lock);
+  }
+}
+
+/** @param {string} commonDir @param {string} worktreeId */
+export function rebuildRecordCache(commonDir, worktreeId) {
+  const lock = acquireRecordLock(commonDir, worktreeId, { command: 'rebuild' });
+  try {
+    const chain = readEventChain(commonDir, worktreeId);
+    const tail = chain.at(-1);
+    if (!tail || !tail.snapshot) {
+      throw new WorktreeTraceError('REBUILD_NO_SNAPSHOT', `record ${worktreeId} 没有可物化 snapshot。`);
+    }
+    return writeRecordCache(commonDir, worktreeId, tail.snapshot, tail, chain.length);
+  } finally {
+    releaseRecordLock(lock);
+  }
+}

package/manage-worktrees/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: manage-worktrees
+description: "管理 Git worktree 隔离与生命周期，包括碰撞扫描、创建或接管、堆叠分支、批量集成候选、交接和回收。仅在明确需要 worktree，或同仓多写入者存在覆盖风险时使用；只读并行和普通单写入者不适用。"
+metadata:
+  requires:
+    bins: ["agentkit"]
+---
+
+# manage-worktrees：Git Worktree 隔离与生命周期
+
+在改文件之前选择最小安全隔离，并让每棵 worktree 都能回答：谁创建、为何创建、正在做什么、谁接手、哪些提交属于谁、为何尚未回收。
+
+## 组合位置
+
+本 skill 是环境适配层，不决定是否派生 Agent，也不判断全局任务是否完成：
+
+- 由 `orchestrate-subagents` 调用时，接收已确认的写入者和并发关系，或已裁决的归属不明 / 路径相交风险；只负责返回目标仓的隔离位置与生命周期记录。
+- `run-agent-verify-loop` 中只有 implementer 写、verifier 只读时不需要 worktree；多个 implementer 并行写或 controller 同时写时才使用本 skill。
+- 用户可以直接要求创建、接管、审计或回收 worktree，此时无需加载其他 skill。
+- 与 `verify-agent-output` 组合时，由本 Skill 输出 Artifact Ref；verifier 只消费冻结身份，不接管 worktree 生命周期。
+
+运行时是 `PATH` 上的 `agentkit` 命令（`agentkit worktree <command>`），要求 `git` 可执行。
+下文多行示例采用 POSIX 续行语法；PowerShell/cmd 保留相同 argv 即可。不要把 `python3`、`bash`、
+`~` 展开或 `/tmp` 视为跨平台常量。
+
+不要假设目标仓库有同名脚本。仓库可以通过根目录 `.worktree-trace.json` 提供 Profile，但 portable core 不执行 Profile 中的任意 shell command。配置 schema 和项目适配边界见 [Profile 配置](../docs/worktree/profile.md)。
+
+所有命令都必须从**目标 Git 仓库的任意 worktree 内**执行：manager 以当前工作目录解析 repository
+identity、primary worktree 和 Profile。
+
+### 跨 Skill 稳定产物
+
+需要交给 verifier 或 orchestrator 时，不手抄 SHA 和 owner：
+
+```bash
+agentkit worktree capabilities --json
+agentkit worktree binding <selector> --json
+agentkit worktree artifact <selector> --json
+agentkit worktree verify-artifact <artifact.json> --json
+```
+
+`artifact` 只接受存在、clean 的 worktree，绑定 repository identity、完整 commit、worktree ID 和
+ownership epoch。`verify-artifact` 重算 object format、commit ancestry、owner epoch 与 live HEAD；
+任何漂移都要求重新冻结 Artifact，不能沿用旧验证结果。Binding 只表达隔离与归属，`task_status:
+done` 不代表验证通过或全局任务完成。
+
+碰撞、漂移、交接或回收异常可用 `incident <selector> --input <json>` 记录带 trace event 摘要的
+Reflection，再用 `propose-improvement --reflection <uuid> --input <json>` 形成 `proposed` 候选。
+这些文件写入 Git common-dir 下的运行状态，不进入业务源码，也不自动修改 Profile 或 Skill。
+
+manager 的 trace/common-dir 状态只应由受信 operator/controller 与 runtime 写入。event digest 链用于
+发现部分、追加、乱序和意外损坏，不是签名或外部不可变审计锚；拥有该状态完整写权限的进程可重写
+一条自洽历史。Artifact/owner epoch 的机械保证以诚实 runtime 和受信状态 writer 为权限边界。
+
+## 强制流程
+
+按下表顺序执行；只在进入对应阶段时读取链接文档：
+
+| 阶段 | 最小命令面 | 硬门禁与按需文档 |
+|---|---|---|
+| 恢复/盘点 | `resume-all` → `list` → `doctor` | `list/doctor` 只读；`UNTRACKED` 不等于无人使用；`EPHEMERAL` 优先 commit+push；任何 error 都暂停 `spawn/adopt` |
+| 碰撞扫描 | `scan --target <paths>` | `COLLIDE`、范围不确定或重做昂贵时隔离；`CLEAR` 仅在 owner 明确且改动小时共享；低置信后缀匹配先人工核对路径基准 |
+| 交付身份 | 选择复用/并存/替代 | branch、MR 或目录名不同不能单独证明独立交付；同一 agent 有存量树或需要替代时读[交付身份](../docs/worktree/delivery-identity.md) |
+| 创建/接管 | `spawn <semantic-slug>` / `adopt <path>` | 使用真实 agent-id，不猜身份；task 至少两个 lowercase 语义分词；base、root、堆叠、rebase/retarget 读[创建与堆叠](../docs/worktree/spawn-and-stack.md) |
+| 更新/交接 | `touch` / `handoff` / `refresh-review` | `ready_for_review` 默认武装冻结 HEAD；handoff 只接受 clean、已 push 边界，禁止 stash 搬运；读[评审生命周期](../docs/worktree/review-lifecycle.md) |
+| 审计/提交 | `audit` / `submit` | portable core 不决定 MR/PR 或直推策略；先服从目标仓规则，再原子登记 change request 与 watcher target |
+| 批量集成 | `plan-batch` → `batch-integrate` → `batch-step` → `batch-result` | 同仓同 target：≥3 默认聚合，2 个仅在碰撞时；只合成冻结 SHA，不代跑门禁；合同/顺序/target 变化即重规划；读[批量集成](../docs/worktree/batch-integration.md) |
+| 回收 | `reclaim` / `archive` | 必须有远端/其他 ref 可达证明或明确 archive evidence；dirty、stash、submodule、权限或 branch-tip 异常一律 `KEEP`；替代树默认先归档，`--discard` 需人工明确授权；读[回收与看护](../docs/worktree/reclaim-and-watch.md) |
+
+不得按目录年龄、名称或“看起来干净”删除。禁止 `rm -rf`、`git worktree remove --force`、`branch -D`
+和 feature owner 手工 rebase。watcher 的 `merge-tree` 结果只是目标前进后的只读成本预判，不保证逐
+commit rebase 成功；`batch-result` 只冻结 controller 已完成的验收结论，不替代验证。
+
+## 并发安全底线
+
+- 当前树并发时只改明确归属文件，提交必须带 pathspec：`git commit -m "type(scope): message" -- <owned-files...>`。
+- 小步 commit、频繁 push；worktree 只隔离 working directory/index，仍共享 refs、objects 和 stash。
+- feature owner 禁止自行 stash、清理、重置、合并或 rebase；历史刷新只走 manager 的 `rebase` / `refresh-review`。批次候选仅当前 owner 可执行 `batch-integrate`。跨会话先 handoff，非干净树拒绝改写。
+- manager 只拥有它创建或接管的 worktree、branch 和 trace metadata，不拥有项目凭证、SDK license、个人 token 或共享运行态。
+- 秘密放在仓库外的 credential store；不得复制、软链或写入 trace。
+- event 是真源，record 是可重建缓存；`doctor` 永远只报告，不自动修复或删除。
+- trace 是本机审计，不替代跨机器任务看板、代码评审或文件锁。
+
+所有命令支持 `--config <path>`，默认只读取 Git primary worktree 的 Profile，linked worktree 副本不能
+改变仓库约定。使用 `capabilities --json` 发现 provider 与协议；命令按上述操作场景读取对应 reference。
+
+显式 `--config` 是人工核对后的恢复出口：它不会刷新 primary `default_base` 或执行 drift gate，只使用本地已有 ref。离线使用前，调用者必须自行确认 Profile 与 base ref 已同步。

package/manage-worktrees/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Manage Worktrees"
+  short_description: "隔离、批量集成并审计 Git worktree 生命周期"
+  default_prompt: "Use $manage-worktrees to plan a reproducible multi-feature integration batch and manage its auditable worktree lifecycle."

package/manage-worktrees/scripts/worktree-mgr.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// 1.x 兼容入口。本 Skill 的运行时已迁入 domains/worktree/，此处只做固定转发，不含实现。
+// 直接执行时行为与 domains/worktree/worktree-mgr.mjs 逐字节一致；被 import 时只透传导出。
+import { forwardLegacyEntry } from '../../core/legacy-entry.mjs';
+import { runCli } from '../../domains/worktree/worktree-mgr.mjs';
+
+export * from '../../domains/worktree/worktree-mgr.mjs';
+
+const status = forwardLegacyEntry(import.meta.url, runCli);
+if (status !== undefined) process.exitCode = status;

package/manage-worktrees/scripts/worktree-scan.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// 1.x 兼容入口。本 Skill 的运行时已迁入 domains/worktree/，此处只做固定转发，不含实现。
+// 直接执行时行为与 domains/worktree/worktree-scan.mjs 逐字节一致；被 import 时只透传导出。
+import { forwardLegacyEntry } from '../../core/legacy-entry.mjs';
+import { runCli } from '../../domains/worktree/worktree-scan.mjs';
+
+export * from '../../domains/worktree/worktree-scan.mjs';
+
+const status = forwardLegacyEntry(import.meta.url, runCli);
+if (status !== undefined) process.exitCode = status;