@yeaft/webchat-agent 1.0.496 → 1.0.498

package/skills/review-merge-tag/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: review-merge-tag
+description: 用 RepoWorkflow 在任意 GitHub 仓库执行开发 worktree、精确 PR review snapshot、base-ref CAS landing、数字 tag 与 workflow 验证；避免重复手工 git/gh 检查。
+---
+
+# Repository Workflow
+
+不要逐条调用 `git fetch`、`git worktree list`、`gh pr view`、`git ls-remote` 和 `gh run watch` 来发现同一批事实。Session 内使用 `RepoWorkflow` 工具。非 Yeaft 环境可用 `yeaft-repo` CLI 执行 `prepare` 和 `review-prep`，这两个阶段返回与工具相同的紧凑 JSON；CLI 不能执行 `land`。
+
+## 三个边界
+
+### 1. 开发准备
+
+```json
+{
+  "phase": "prepare",
+  "name": "fix-short-description"
+}
+```
+
+它会在当前仓库中确定远端默认分支、拉取最新精确基线、检查 worktree/branch/path 冲突，并创建或安全复用 `yeaft-wt/<name>`。后续开发只使用返回的 `worktree.path`。
+
+### 2. 独立 review 准备
+
+Reviewer 调用：
+
+```json
+{
+  "phase": "review-prep",
+  "pr": 123
+}
+```
+
+它会一次冻结 GitHub PR 的 base branch/base SHA/head/merge snapshot、检查 draft/conflict/checks，并创建 detached exact-snapshot review worktree。Reviewer 必须审查返回的 `reviewWorktree.path`，并把明确结论、`pullRequest.baseBranch`、`pullRequest.baseSha`、`pullRequest.headSha` 和 `pullRequest.snapshotSha` 交回开发者。
+
+工具只冻结事实，不替代代码审查。
+
+### 3. Review 通过后的落地
+
+只有收到独立 reviewer 的明确批准后才能调用。Reviewer 必须用 `RouteForward` 把绑定仓库、PR、exact base branch/base SHA/head/merge snapshot 的结构化批准交回 landing VP；宿主会随该 handoff 铸造不可序列化、一次性的 approval capability。随后 landing VP 才能在处理该 handoff 的同一 turn 调用：
+
+```json
+{
+  "phase": "land",
+  "pr": 123,
+  "baseBranch": "main",
+  "baseSha": "<exact 40-char base SHA>",
+  "reviewedHead": "<exact 40-char head SHA>",
+  "reviewedSnapshot": "<exact 40-char merge snapshot SHA>",
+  "tagPrefix": "v1.0.",
+  "workflow": "Dev Release"
+}
+```
+
+`approvedBy` 等普通字符串没有授权语义。`land` 只接受宿主 capability，并重新冻结 PR；任何 repo、PR、recipient、base branch、base SHA、head 或 snapshot 不匹配都会停止。Reviewed snapshot 必须以批准的 base SHA/head 为两个父提交；landing 的目标 ref 只从批准的 base branch 推导，并在任何写入前拒绝 PR retarget。之后它通过单次 receive-pack 更新，用 `--force-with-lease=<base-ref>:<approved-base>` 将该 exact snapshot 安装到批准的远端 base。若 base 在最后冻结与 receive 之间前进，lease 会拒绝更新，并且不会创建 tag。若要求 tag，它只在 base CAS 成功后从远端 tags 数值计算下一版，用 create-only lease 推送并复核 base 与 tag。若要求 workflow，它等待匹配 tag 与 reviewed snapshot SHA 的 run 完成。
+
+Worktree cleanup 不属于 landing。`land` 会在任何仓库或远端副作用前拒绝 cleanup 请求，包括 active `repoRoot`；需要 cleanup 时必须在 landing 完成后走独立操作，cleanup 失败不能改变 landing 结果。
+
+## 通用性与边界
+
+- 适用于 Agent 可访问的任意本地 GitHub 仓库，不包含项目路径或固定 `main` 假设。
+- 需要 `git` 和已认证的 `gh` CLI；不依赖 Python，也不通过 shell 拼接命令。
+- 当前不支持 GitLab/Bitbucket；不要把 GitHub 成功误报为 forge-agnostic。
+- 自动化只消除重复事实核对，不消除独立 review、测试选择、代码判断或用户授权。
+- `land` 后若 workflow 失败，merge/tag 可能已经完成；读取错误 JSON 的 `details.remoteEffects`，不要盲目重试或重打 tag。
+
+## CLI
+
+Yeaft 外部或人工终端只可运行准备阶段：
+
+```bash
+yeaft-repo prepare --name fix-short-description
+yeaft-repo review-prep --pr 123
+```
+
+独立 CLI 不能执行 `land`。Landing 必须在 Session 中通过 `RepoWorkflow` 工具执行，并携带当前 handoff 由宿主签发、绑定 exact review 的 approval capability；普通参数或 `approvedBy` 字符串不能替代该 capability。
+
+每条可用命令 stdout 只输出一个成功 JSON；失败时 stderr 输出一个带稳定 `code` 和副作用状态的 JSON。

package/yeaft/cli-session-runner.js

@@ -250,7 +250,10 @@ export function createCliSessionRunner({
       sessionMembers: meta.roster.slice(),
       sessionAnnouncement: meta.announcement || '',
       vpPersona: personaFactory(vpId, loaded),
-      router: createRouter({ coordinator: scopedCoordinator, guard: routeForwardGuard }),
+      router: createRouter({
+        coordinator: scopedCoordinator,
+        guard: routeForwardGuard,
+      }),
       inboundEnvelope: envelope,
       userAlreadyPersisted: true,
       causalRootId,

package/yeaft/debug-trace.js

@@ -211,6 +211,9 @@ function buildInitialRawRequestDelta(value) {
     delta.set[key] = cloneRawValue(item);
   }
   const body = isPlainObject(value.body) ? value.body : null;
+  if (body && ['input', 'messages'].some(key => Object.hasOwn(body, key) && !Array.isArray(body[key]))) {
+    return { replacement: cloneRawValue(value) };
+  }
   if (body) {
     for (const [key, bodyValue] of Object.entries(body)) {
       if (key === 'messages' || key === 'input') continue;
@@ -261,6 +264,10 @@ function buildRawRequestDelta(previous, next) {
 
   const prevBody = isPlainObject(comparablePrevious.body) ? comparablePrevious.body : null;
   const nextBody = isPlainObject(comparableNext.body) ? comparableNext.body : null;
+  if (prevBody && nextBody && (rawRequestMessageKey(prevBody) !== rawRequestMessageKey(nextBody)
+      || [prevBody, nextBody].some(body => ['input', 'messages'].some(key => Object.hasOwn(body, key) && !Array.isArray(body[key]))))) {
+    return stableEqual(comparablePrevious, comparableNext) ? null : { replacement: cloneRawValue(comparableNext) };
+  }
   if (prevBody && nextBody) {
     for (const key of Object.keys(nextBody)) {
       if (key === 'messages' || key === 'input') continue;
@@ -601,12 +608,12 @@ function summarizeTrace(trace, detailsLoaded = false) {
       callId: t.toolCallId || t.id || null,
       traceToolId: t.id || null,
       name: t.toolName || t.name || '?',
+      toolInput: t.toolInput == null ? null : String(t.toolInput),
       toolOutput: t.toolOutput == null ? null : String(t.toolOutput),
       durationMs: t.durationMs || 0,
       isError: !!t.isError,
     })) : [],
     detailsLoaded,
-    requestBase: trace?.baseRequest || null,
   };
 }
 
@@ -626,8 +633,10 @@ function expandTrace(trace) {
       loopInstanceId: loop.loopInstanceId || loop.turnRowId || null,
       loopNumber: loop.loopNumber || 0,
       model: loop.model || null,
-      systemPrompt: snapshot.systemPrompt || '',
-      messages: Array.isArray(snapshot.messages) ? snapshot.messages : [],
+      // Request snapshots are attached only to the latest loop below. Earlier
+      // loops retain their responses, calls and timing, not repeated history.
+      systemPrompt: '',
+      messages: [],
       response: loop.response || '',
       toolCalls: Array.isArray(loop.toolCalls) ? loop.toolCalls : [],
       usage,
@@ -635,15 +644,19 @@ function expandTrace(trace) {
       ttfbMs: loop.ttfbMs || null,
       stopReason: loop.stopReason || null,
       at: loop.at || null,
-      rawRequest,
+      rawRequest: null,
       rawResponse: loop.rawResponse ?? null,
-      requestDelta: loop.requestDelta || {},
-      requestBase: trace.baseRequest || null,
       sessionId: trace.sessionId || null,
       vpId: trace.vpId || null,
       threadId: trace.threadId || null,
     });
   }
+  const latest = loops.at(-1);
+  if (latest && snapshot) {
+    latest.systemPrompt = snapshot.systemPrompt || '';
+    latest.messages = Array.isArray(snapshot.messages) ? snapshot.messages : [];
+    latest.rawRequest = rawRequest;
+  }
   return { loops, turns: Array.from(turnsById.values()) };
 }
 

package/yeaft/engine.js

@@ -1416,6 +1416,7 @@ export class Engine {
         ? vpCtx.projectSessionIds.slice()
         : [],
       threadId: vpCtx?.threadId || this.#currentThreadId || MAIN_THREAD_ID,
+      turnId: vpCtx?.turnId || null,
       currentVpId: vpCtx?.senderVpId || this.#vpId || null,
       // task-704b: per-tool-result hard cap derives from this. Threaded
       // from the live model (resolveModel(currentModel)) every turn so
@@ -3847,6 +3848,7 @@ export class Engine {
         projectInstruction,
         projectLabel,
         threadId: runtimeThreadId,
+        turnId: vpTurnId,
         inboundEnvelope,
         taskId,
         taskMembers,

package/yeaft/init.js

@@ -15,7 +15,7 @@ import { mutateAgentConfig } from './config-store.js';
 // layout AND rewrites pre-rename per-message frontmatter (groupId → sessionId).
 // Idempotent via the `.yeaft-migration.done` sentinel file.
 import { migrateSessions } from './migrate/sessions.js';
-import { bundledYeaftSkillsDir } from './skills.js';
+import { bundledYeaftSkillsDirs } from './skills.js';
 
 /**
  * Check if an error is a permission error (EACCES or EPERM).
@@ -353,7 +353,10 @@ function readManifest(filePath) {
  * @returns {{ copied: number, updated: number, preserved: number, skipped: number }}
  */
 export function seedBundledSkills(userSkillsDir, warnings = []) {
-  const bundled = bundledYeaftSkillsDir();
+  // Seed only the highest-priority root. Runtime loading still scans every
+  // bundled root; flattening lower-priority roots into the user tier here
+  // would erase bundled provenance and conflict ordering.
+  const bundled = bundledYeaftSkillsDirs().at(-1);
   if (!bundled) {
     return { copied: 0, updated: 0, preserved: 0, skipped: 0 };
   }

package/yeaft/routing/router.js

@@ -28,6 +28,122 @@
 import { resolveMemberId } from '../sessions/roster.js';
 import { createLoopGuard, extendCausedBy } from './loop-guard.js';
 
+const repoApprovals = new WeakMap();
+const REPO_APPROVAL_ISSUER_IDS = new Set(['martin']);
+export const REPO_APPROVAL_TTL_MS = 2 * 60 * 1000;
+
+function normalizeId(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function normalizeSha(value) {
+  const sha = normalizeId(value).toLowerCase();
+  return /^[0-9a-f]{40}$/.test(sha) ? sha : '';
+}
+
+function normalizeApprovalRepository(value) {
+  const repository = normalizeId(value).replace(/\.git$/i, '');
+  const segments = repository.split('/');
+  if (segments.length === 2) segments.unshift('github.com');
+  if (segments.length !== 3) return '';
+  const [host, owner, name] = segments;
+  const safePart = part => /^[a-z0-9_.-]+$/i.test(part) && part !== '.' && part !== '..';
+  if (!safePart(host) || !safePart(owner) || !safePart(name) || !host.includes('.')) return '';
+  return `${host}/${owner}/${name}`.toLowerCase();
+}
+
+function isRepoApprovalIssuer(vpId) {
+  return REPO_APPROVAL_ISSUER_IDS.has(normalizeId(vpId));
+}
+
+/**
+ * Mint authority only inside the canonical Router path after roster identity
+ * resolution. Keeping this function module-private prevents callers from
+ * turning a claimed issuer string into landing authority.
+ */
+function issueRepoApprovalCapability(input = {}, { now = Date.now } = {}) {
+  const sessionId = normalizeId(input.sessionId);
+  const issuerVpId = normalizeId(input.issuerVpId);
+  const recipientVpId = normalizeId(input.recipientVpId);
+  const repository = normalizeApprovalRepository(input.repository);
+  const pr = Number(input.pr);
+  const baseBranch = normalizeId(input.baseBranch);
+  const baseSha = normalizeSha(input.baseSha);
+  const reviewedHead = normalizeSha(input.reviewedHead);
+  const reviewedSnapshot = normalizeSha(input.reviewedSnapshot);
+  const issuedAt = Number(now());
+  if (!sessionId || !isRepoApprovalIssuer(issuerVpId) || !recipientVpId || issuerVpId === recipientVpId
+    || !repository || !Number.isSafeInteger(pr) || pr <= 0 || !baseBranch || !baseSha
+    || !reviewedHead || !reviewedSnapshot || !Number.isFinite(issuedAt)) {
+    return null;
+  }
+  const capability = Object.freeze(Object.create(null));
+  repoApprovals.set(capability, {
+    sessionId,
+    issuerVpId,
+    recipientVpId,
+    repository,
+    pr,
+    baseBranch,
+    baseSha,
+    reviewedHead,
+    reviewedSnapshot,
+    issuedAt,
+    expiresAt: issuedAt + REPO_APPROVAL_TTL_MS,
+    turnId: null,
+  });
+  return capability;
+}
+
+export function isRepoApprovalCapability(capability) {
+  return Boolean(capability && typeof capability === 'object' && repoApprovals.has(capability));
+}
+
+/** Bind a freshly issued capability to the exact Web execution that received it. */
+export function bindRepoApprovalCapability(capability, expected = {}, { now = Date.now } = {}) {
+  if (!capability || typeof capability !== 'object') return false;
+  const grant = repoApprovals.get(capability);
+  const turnId = normalizeId(expected.turnId);
+  const currentTime = Number(now());
+  if (!grant || !turnId || !Number.isFinite(currentTime)) return false;
+  if (currentTime > grant.expiresAt
+    || grant.turnId
+    || grant.sessionId !== normalizeId(expected.sessionId)
+    || grant.recipientVpId !== normalizeId(expected.recipientVpId)) {
+    repoApprovals.delete(capability);
+    return false;
+  }
+  grant.turnId = turnId;
+  return true;
+}
+
+export function revokeRepoApprovalCapability(capability) {
+  if (!capability || typeof capability !== 'object') return false;
+  return repoApprovals.delete(capability);
+}
+
+/** Consume a capability exactly once and verify its complete landing tuple. */
+export function consumeRepoApprovalCapability(capability, expected = {}, { now = Date.now } = {}) {
+  if (!capability || typeof capability !== 'object') return null;
+  const grant = repoApprovals.get(capability);
+  repoApprovals.delete(capability);
+  if (!grant) return null;
+  const currentTime = Number(now());
+  const matches = Number.isFinite(currentTime)
+    && currentTime <= grant.expiresAt
+    && grant.turnId
+    && grant.turnId === normalizeId(expected.turnId)
+    && grant.sessionId === normalizeId(expected.sessionId)
+    && grant.recipientVpId === normalizeId(expected.recipientVpId)
+    && grant.repository === normalizeApprovalRepository(expected.repository)
+    && grant.pr === Number(expected.pr)
+    && grant.baseBranch === normalizeId(expected.baseBranch)
+    && grant.baseSha === normalizeSha(expected.baseSha)
+    && grant.reviewedHead === normalizeSha(expected.reviewedHead)
+    && grant.reviewedSnapshot === normalizeSha(expected.reviewedSnapshot);
+  return matches ? Object.freeze({ ...grant }) : null;
+}
+
 function routeForwardParentFromEnvelope(envelope) {
   const msg = envelope?.msg;
   const meta = msg?.meta;
@@ -75,7 +191,8 @@ export function createRouter(deps = {}) {
   if (!coordinator || typeof coordinator.ingest !== 'function') {
     throw new Error('createRouter: coordinator (with ingest()) is required');
   }
-  const guard = deps.guard || createLoopGuard({ now: deps.now });
+  const now = typeof deps.now === 'function' ? deps.now : Date.now;
+  const guard = deps.guard || createLoopGuard({ now });
 
   /**
    * Forward a message from a VP to another VP (or @all). Routes through
@@ -122,6 +239,8 @@ export function createRouter(deps = {}) {
     }
     const meta = coordinator.group.getMeta();
     if (!meta) return { ok: false, error: 'group_not_initialised' };
+    const senderVpId = resolveMemberId(meta, from);
+    if (!senderVpId) return { ok: false, error: 'sender_not_in_roster' };
     const claimedVpIds = args.inboundEnvelope?._cliTurnContext?.claimedVpIds;
 
     // Roster membership — `all` is reserved broadcast sentinel handled by
@@ -132,7 +251,7 @@ export function createRouter(deps = {}) {
     if (targetVpId !== 'all' && !targetVpId) {
       return { ok: false, error: 'target_not_in_roster' };
     }
-    if (targetVpId === from) {
+    if (targetVpId === senderVpId) {
       return { ok: false, error: 'self_forward_rejected' };
     }
     if (targetVpId !== 'all' && claimedVpIds?.has?.(targetVpId)) {
@@ -146,6 +265,24 @@ export function createRouter(deps = {}) {
     // spec's intent ("depth of forwards already taken").
     const chain = extendCausedBy(args.inboundEnvelope || null, null);
     const routeForwardParent = routeForwardParentFromEnvelope(args.inboundEnvelope);
+    let repoApproval = null;
+    if (args.repoApproval !== undefined) {
+      if (targetVpId === 'all') {
+        return { ok: false, error: 'repo_approval_requires_single_target' };
+      }
+      if (!isRepoApprovalIssuer(senderVpId)) {
+        return { ok: false, error: 'repo_approval_issuer_forbidden' };
+      }
+      repoApproval = issueRepoApprovalCapability({
+        ...args.repoApproval,
+        sessionId: meta.id,
+        issuerVpId: senderVpId,
+        recipientVpId: targetVpId,
+      }, { now });
+      if (!repoApproval) {
+        return { ok: false, error: 'invalid_repo_approval' };
+      }
+    }
 
     // Loop guard: for broadcast, use 'all' as the target key so one VP
     // spamming @all still gets throttled even if each cycle hits different
@@ -182,6 +319,7 @@ export function createRouter(deps = {}) {
         // of UI replay and future visible history so it doesn't render as a
         // second assistant/user block after the target VP answers.
         internal: true,
+        ...(repoApproval ? { _repoApproval: repoApproval } : {}),
         meta: {
           synthetic: true,
           injectedBy: 'route_forward',

package/yeaft/skills.js

@@ -28,9 +28,10 @@
  *
  * The standard tier order set up by `createSkillManager` is:
  *
- *   tier 1 (bundled): wherever yeaft-skills is installed on disk — typically
- *           ~/.claude/skills/yeaft-skills/skills/. Read-only — `save()` and
- *           `remove()` never target this tier.
+ *   tier 1 (bundled): all available external yeaft-skills roots plus the Agent
+ *           package's own skills. External roots load first; Agent built-ins
+ *           win bundled-name conflicts. Read-only — `save()` and `remove()`
+ *           never target this tier.
  *   tier 2 (user):    <yeaftDir>/skills (e.g. ~/.yeaft/skills). User edits
  *           land here. `save()` writes here. `init.js` seeds it from tier 1
  *           on first boot so users start with the bundled Yeaft skills.
@@ -1197,8 +1198,9 @@ export class SkillManager {
  * Create a SkillManager wired with the standard layered tier list and load it.
  *
  * Tier order (lowest → highest priority):
- *   1. bundled        — the yeaft-skills package on disk, located via
- *      `bundledYeaftSkillsDir()` (typically ~/.claude/skills/yeaft-skills/skills/).
+ *   1. bundled        — every available bundled root returned by
+ *      `bundledYeaftSkillsDirs()`. External packages add skills, while the
+ *      Agent package loads last so its built-in skills win bundled conflicts.
  *   2. user           — `<yeaftDir>/skills` (e.g. ~/.yeaft/skills). User edits + saves.
  *   3. project-claude — `<workDir>/.claude/skills` when a workDir is provided.
  *      Claude Code project assets, loaded so a project that integrates Claude
@@ -1218,7 +1220,7 @@ export class SkillManager {
  * @returns {SkillManager}
  */
 export function createSkillManager(yeaftDir, workDir, options = {}) {
-  const bundled = bundledYeaftSkillsDir();
+  const bundledDirs = bundledYeaftSkillsDirs();
   const userDir = join(yeaftDir, 'skills');
   const projectRoots = [...new Set(String(workDir || '')
     .split(delimiter)
@@ -1228,9 +1230,9 @@ export function createSkillManager(yeaftDir, workDir, options = {}) {
   const codexProjectDirs = projectRoots.map(root => join(root, '.agents', 'skills'));
   const projectDirs = projectRoots.map(root => join(root, '.yeaft', 'skills'));
 
-  const dirs = [bundled, userDir, ...claudeProjectDirs, ...codexProjectDirs, ...projectDirs].filter(Boolean);
+  const dirs = [...bundledDirs, userDir, ...claudeProjectDirs, ...codexProjectDirs, ...projectDirs];
   const tierByDir = {};
-  if (bundled) tierByDir[bundled] = 'bundled';
+  for (const dir of bundledDirs) tierByDir[dir] = 'bundled';
   tierByDir[userDir] = 'user';
   for (const dir of claudeProjectDirs) tierByDir[dir] = 'project-claude';
   for (const dir of codexProjectDirs) tierByDir[dir] = 'project-codex';
@@ -1256,56 +1258,75 @@ export function createSkillManager(yeaftDir, workDir, options = {}) {
 // ─── Bundled-skills resolver ──────────────────────────────
 
 /**
- * Locate the bundled `yeaft-skills` package on disk.
+ * Locate every available bundled Skill root on disk.
  *
- * Resolution order (first existing directory wins):
- *   1. $YEAFT_SKILLS_BUNDLED_DIR — explicit env override (testing / packaging)
- *   2. ~/.claude/skills/yeaft-skills/skills/    — standard Claude Code plugin layout
- *   3. ~/.claude/plugins/yeaft-skills/skills/   — alternate plugin layout
- *   4. <agent-pkg>/skills/                       — bundled-with-agent fallback so
- *      a future npm release can ship its own skills directory
+ * The returned array is ordered from lowest to highest priority, matching the
+ * `SkillManager` layered-load contract:
+ *   1. ~/.claude/plugins/yeaft-skills/skills/   — alternate plugin layout
+ *   2. ~/.claude/skills/yeaft-skills/skills/    — standard Claude Code layout
+ *   3. $YEAFT_SKILLS_BUNDLED_DIR                 — explicit additional root
+ *   4. <agent-pkg>/skills/                       — authoritative Agent built-ins
  *
- * Returns `null` when none exist — callers must tolerate this (Yeaft still
- * runs; the user just sees no pre-installed bundled skills). Co-located here
- * (rather than in init.js) so both `createSkillManager()` and init.js's seed
- * step can call it without a module cycle.
+ * All existing roots coexist. The Agent package is deliberately last so an
+ * external package or env override cannot shadow safety-critical built-ins.
+ * User and project tiers still load after these roots and retain their existing
+ * higher-priority customization semantics.
  *
- * @returns {string|null}
+ * @returns {string[]}
  */
-export function bundledYeaftSkillsDir() {
+export function bundledYeaftSkillsDirs() {
   const candidates = [];
+  const home = homedir();
+  if (home) {
+    candidates.push(join(home, '.claude', 'plugins', 'yeaft-skills', 'skills'));
+    candidates.push(join(home, '.claude', 'skills', 'yeaft-skills', 'skills'));
+  }
 
   const envOverride = process.env.YEAFT_SKILLS_BUNDLED_DIR;
   if (envOverride && typeof envOverride === 'string' && envOverride.length > 0) {
     candidates.push(envOverride);
   }
 
-  const home = homedir();
-  if (home) {
-    candidates.push(join(home, '.claude', 'skills', 'yeaft-skills', 'skills'));
-    candidates.push(join(home, '.claude', 'plugins', 'yeaft-skills', 'skills'));
-  }
-
-  // Bundled-with-agent fallback: <agent-pkg-root>/skills. The package root is
-  // the directory containing agent/, so we walk up from this file.
+  // Bundled-with-agent root: <agent-pkg>/skills. The package root is the
+  // directory containing yeaft/, so walk up from this file.
   try {
     const here = dirname(fileURLToPath(import.meta.url));
-    // here = .../agent/yeaft
-    const agentRoot = join(here, '..', '..');
-    candidates.push(join(agentRoot, 'skills'));
+    candidates.push(join(here, '..', 'skills'));
   } catch {
     // fileURLToPath can throw on exotic loaders — non-fatal.
   }
 
-  for (const c of candidates) {
+  const roots = [];
+  for (const candidate of candidates) {
+    if (!candidate || roots.includes(candidate)) continue;
     try {
-      if (c && existsSync(c) && statSync(c).isDirectory()) {
-        return c;
+      if (existsSync(candidate) && statSync(candidate).isDirectory()) {
+        roots.push(candidate);
       }
     } catch {
-      // permission errors etc. — try the next candidate.
+      // Permission errors etc. make this candidate unavailable.
     }
   }
+  return roots;
+}
 
-  return null;
+/**
+ * Back-compatible singular resolver with the original first-existing order.
+ * New callers that load Skills must use `bundledYeaftSkillsDirs()` so all
+ * roots coexist.
+ *
+ * @returns {string|null}
+ */
+export function bundledYeaftSkillsDir() {
+  const roots = bundledYeaftSkillsDirs();
+  const envOverride = process.env.YEAFT_SKILLS_BUNDLED_DIR;
+  const home = homedir();
+  const legacyOrder = [
+    envOverride,
+    home ? join(home, '.claude', 'skills', 'yeaft-skills', 'skills') : null,
+    home ? join(home, '.claude', 'plugins', 'yeaft-skills', 'skills') : null,
+  ];
+  return legacyOrder.find(candidate => candidate && roots.includes(candidate))
+    || roots.at(-1)
+    || null;
 }

package/yeaft/tools/activation.js

@@ -59,6 +59,7 @@ export const CONDITIONAL_BUILTIN_TOOL_NAMES = new Set([
   'JsRepl',
   'NotebookEdit',
   'ImageGeneration',
+  'RepoWorkflow',
 ]);
 
 const HISTORY_INTENT_RE = /(?:\bhistory\b|\b(?:prior|previous) (?:chat|conversation|discussion)\b|\bprevious(?:ly)? discussed\b|\bwhat did we (?:decide|discuss|say|agree)\b|\b(?:our|the) (?:earlier|last) decision\b|历史|之前(?:的)?(?:对话|讨论|会话|决定)|过去(?:的)?会话|我们(?:之前|上次)(?:决定|讨论|说)了什么)/iu;
@@ -70,6 +71,7 @@ const WORK_ITEM_INTENT_RE = /(?:\bwork ?center\b|\bwork ?item\b|\bdurable tracki
 const REPL_INTENT_RE = /(?:\bjs ?repl\b|\bjavascript (?:calculation|experiment|evaluation)\b|\bcalculate\b|\bdata transform\b|JavaScript (?:计算|实验|求值)|数据转换|快速计算)/iu;
 const NOTEBOOK_INTENT_RE = /(?:\.ipynb\b|\bjupyter\b|\bnotebook (?:cell|file)\b|Jupyter|笔记本单元格)/iu;
 const IMAGE_GENERATION_INTENT_RE = /(?:\b(?:generate|make|design|draw) (?:me |us )?(?:an? |the )?(?:image|picture|logo|icon|illustration|graphic)\b|\bcreate (?:me |us )?(?:an? |the )?(?:illustration|image|picture|logo|icon|graphic)\b|生成(?:一张)?(?:图片|图像|标志|图标|插图)|创建(?:一张)?(?:插图|图片|图像|标志|图标)|画(?:一张)?(?:图|图片|图标))/iu;
+const REPO_WORKFLOW_INTENT_RE = /(?:\b(?:git |github )?(?:worktree|pull request|pr) (?:workflow|review|merge|landing|prepare)\b|\b(?:review|merge|land|prepare) (?:a |the )?(?:github )?(?:pull request|pr)\b|\bhead[- ]match(?:ed)? merge\b|\bmerge (?:and|\+) tag\b|\breview[- ]prep\b|\bye?aft-repo\b|仓库(?:工作流|流程)|准备(?:开发|审查|review) worktree|(?:审查|评审|合并|准备) ?(?:github )?(?:pr|pull request|拉取请求)|合并(?:并|和)?打 tag|精确 head 合并)/iu;
 const MCP_INTENT_RE = /(?:\bmcp\b|model context protocol|模型上下文协议)/iu;
 
 function messageText(message) {
@@ -161,6 +163,7 @@ export function resolveActiveToolNames({
   if (REPL_INTENT_RE.test(intentText)) active.add('JsRepl');
   if (NOTEBOOK_INTENT_RE.test(intentText)) active.add('NotebookEdit');
   if (imageGenerationConfigured && IMAGE_GENERATION_INTENT_RE.test(intentText)) active.add('ImageGeneration');
+  if (REPO_WORKFLOW_INTENT_RE.test(intentText)) active.add('RepoWorkflow');
 
   for (const name of matchedMcpTools(intentText, toolNames)) active.add(name);
 

package/yeaft/tools/index.js

@@ -22,6 +22,7 @@ import { ToolRegistry } from './registry.js';
 import skillTool from './skill.js';
 import enterWorktree from './enter-worktree.js';
 import exitWorktree from './exit-worktree.js';
+import repoWorkflow from './repo-workflow.js';
 
 // --- P0 Core tools ---
 import askUser from './ask-user.js';
@@ -89,6 +90,7 @@ export const allTools = [
   skillTool,
   enterWorktree,
   exitWorktree,
+  repoWorkflow,
 
   // P0 Core
   askUser,

package/yeaft/tools/repo-workflow.js

@@ -0,0 +1,80 @@
+import { defineTool } from './types.js';
+import {
+  formatRepoWorkflowError,
+  landRepoWorkflow,
+  prepareRepoReview,
+  prepareRepoWorkflow,
+} from '../../repo-workflow.js';
+
+const repoWorkflow = defineTool({
+  name: 'RepoWorkflow',
+  description: {
+    en: `Run one deterministic GitHub repository workflow phase and return compact structured evidence.
+
+Use this instead of repeatedly issuing git/gh shell commands:
+- prepare: fetch the remote default branch and create/reuse an exact-base development worktree.
+- review-prep: freeze a PR's exact base/head/GitHub merge snapshot and create/reuse a clean detached review worktree.
+- land: re-freeze an independently approved exact base branch/base SHA/head/snapshot and atomically install that exact snapshot on the approved remote base with an expected-old lease, then optionally create the next numeric tag and wait for a workflow. Worktree cleanup is deliberately separate.
+
+This tool does not review code and never infers approval. The land phase requires the reviewer identity and exact SHAs returned by review-prep. Supports any local GitHub repository available to the Agent; git and authenticated gh CLIs are required.`,
+    zh: `执行一个确定性的 GitHub 仓库工作流阶段，并返回紧凑的结构化证据。
+
+应使用此工具代替反复执行 git/gh shell 命令：
+- prepare：拉取远端默认分支，并创建或复用精确基线的开发 worktree。
+- review-prep：冻结 PR 的精确 base/head/GitHub merge snapshot，并创建或复用干净的 detached review worktree。
+- land：重新冻结已经独立批准的 exact base branch/base SHA/head/snapshot，以 expected-old lease 在已批准的远端 base 上原子安装该 exact snapshot，随后可选创建下一个数字 tag 并等待 workflow。Worktree cleanup 刻意与 landing 分离。
+
+此工具不做代码审查，也不会推断 review 已通过。land 必须提供 reviewer 身份以及 review-prep 返回的精确 SHA。适用于 Agent 可访问的任意本地 GitHub 仓库；需要 git 和已认证的 gh CLI。`,
+  },
+  parameters: {
+    type: 'object',
+    properties: {
+      phase: { type: 'string', enum: ['prepare', 'review-prep', 'land'] },
+      cwd: { type: 'string', description: 'Repository or worktree path; defaults to the current engine cwd' },
+      remote: { type: 'string', description: 'Git remote name (default: origin)' },
+      baseBranch: { type: 'string', description: 'Explicit base branch for prepare, or exact approved destination branch for land' },
+      baseSha: { type: 'string', description: 'Exact independently approved base SHA for land' },
+      name: { type: 'string', description: 'Development or review worktree name' },
+      worktreePath: { type: 'string', description: 'Explicit worktree path' },
+      pr: { type: 'integer', description: 'GitHub pull request number' },
+      reviewedHead: { type: 'string', description: 'Exact independently approved PR head SHA' },
+      reviewedSnapshot: { type: 'string', description: 'Exact independently approved GitHub merge snapshot SHA' },
+      tagPrefix: { type: 'string', description: 'Optional numeric tag prefix, for example v1.0.' },
+      tagStart: { type: 'integer', minimum: 0 },
+      workflow: { type: 'string', description: 'Optional GitHub Actions workflow name to wait for' },
+      waitTimeoutMs: { type: 'integer', minimum: 1 },
+      pollIntervalMs: { type: 'integer', minimum: 1 },
+    },
+    required: ['phase'],
+  },
+  timeoutMs: 0,
+  isConcurrencySafe: () => false,
+  isReadOnly: () => false,
+  isDestructive: input => input?.phase === 'land',
+  async execute(input, ctx) {
+    const options = { ...input, cwd: input.cwd || ctx?.cwd || process.cwd() };
+    try {
+      const dependencies = input.phase === 'land'
+        ? {
+          signal: ctx?.signal,
+          approvalCapability: ctx?.inboundEnvelope?._repoApproval,
+          approvalContext: {
+            sessionId: ctx?.sessionId,
+            recipientVpId: ctx?.senderVpId,
+            turnId: ctx?.turnId,
+          },
+        }
+        : { signal: ctx?.signal };
+      const result = input.phase === 'prepare'
+        ? await prepareRepoWorkflow(options, dependencies)
+        : input.phase === 'review-prep'
+          ? await prepareRepoReview(options, dependencies)
+          : await landRepoWorkflow(options, dependencies);
+      return JSON.stringify(result);
+    } catch (error) {
+      return JSON.stringify(formatRepoWorkflowError(error));
+    }
+  },
+});
+
+export default repoWorkflow;