agentic-flow-kit 1.8.7 → 2.1.0

package/templates/engine/.agents/skills/session-resume/scripts/worktree-audit.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// worktree-audit — 盘点 git worktree，分类 主区 / 活跃 / 可清理 / 失效。
+// 默认只读（不删除、不清理、不 prune）；`--execute` 只删「可清理」（干净且已合入主分支），
+// 失效走 `git worktree prune`；活跃/主区永不删。删除动作仍须显式 `--execute`。
+// 用法：node .agents/skills/session-resume/scripts/worktree-audit.mjs [--root <dir>] [--json] [--execute]
+// 判据：脏（含未跟踪）或未合入主分支 = 活跃；干净且已合入 = 可清理；目录缺失 / prunable = 失效。
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const argv = process.argv.slice(2);
+const asJson = argv.includes('--json');
+const execute = argv.includes('--execute');
+const root = path.resolve(argv.includes('--root') ? argv[argv.indexOf('--root') + 1] : process.cwd());
+
+const git = (args, cwd) => spawnSync('git', args, { cwd, encoding: 'utf8' });
+const out = (args, cwd) => {
+  const r = git(args, cwd);
+  return r.status === 0 ? r.stdout.trim() : null;
+};
+
+const porcelain = out(['worktree', 'list', '--porcelain'], root);
+if (porcelain === null) {
+  console.error('worktree-audit: 不是 git 仓库（或 git 不可用）');
+  process.exit(2);
+}
+
+// 主分支锚：origin/main > main > master；都没有则不判「已合入」
+const mainRef = ['origin/main', 'main', 'master'].find((ref) => git(['rev-parse', '--verify', '--quiet', ref], root).status === 0) || null;
+
+const blocks = porcelain.split(/\r?\n\r?\n/).map((b) => b.split(/\r?\n/)).filter((ls) => ls.some((l) => l.startsWith('worktree ')));
+const primary = (blocks[0] || []).find((l) => l.startsWith('worktree '))?.slice('worktree '.length) || '';
+
+const rows = blocks.map((lines) => {
+  const field = (name) => lines.find((l) => l.startsWith(`${name} `))?.slice(name.length + 1) || '';
+  const wt = field('worktree');
+  const head = field('HEAD');
+  const branchRef = field('branch');
+  const prunable = field('prunable');
+  const branch = branchRef ? branchRef.replace(/^refs\/heads\//, '') : '(detached)';
+  const exists = fs.existsSync(wt);
+
+  let dirty = null;
+  let upstream = null;
+  let ahead = null;
+  let behind = null;
+  let merged = null;
+  let lastDate = null;
+
+  if (exists) {
+    dirty = (out(['status', '--porcelain', '-uall'], wt) || '') !== '';
+    upstream = out(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'], wt);
+    if (upstream) {
+      const lr = out(['rev-list', '--left-right', '--count', '@{u}...HEAD'], wt);
+      if (lr) { const [b, a] = lr.split(/\s+/).map(Number); behind = b; ahead = a; }
+    }
+    if (mainRef) merged = git(['merge-base', '--is-ancestor', 'HEAD', mainRef], wt).status === 0;
+    lastDate = out(['log', '-1', '--format=%cs'], wt);
+  }
+
+  let kind;
+  if (!exists || prunable) kind = '失效';
+  else if (path.resolve(wt) === path.resolve(primary)) kind = '主区';
+  else if (dirty) kind = '活跃(未提交)';
+  else if (merged === false || (ahead !== null && ahead > 0)) kind = '活跃(未合并)';
+  else if (merged === true) kind = '可清理';
+  else kind = '未知';
+
+  return { path: wt, branch, head, dirty, upstream, ahead, behind, merged, lastDate, kind, prunable };
+});
+
+if (asJson) {
+  console.log(JSON.stringify({ mainRef, worktrees: rows }, null, 2));
+  process.exit(0);
+}
+
+const pad = (s, n) => {
+  const clip = (v) => ([...String(v)].length > n ? [...String(v)].slice(0, n - 1).join('') + '…' : String(v));
+  const t = clip(s);
+  const w = [...t].reduce((acc, ch) => acc + (ch.charCodeAt(0) > 255 ? 2 : 1), 0);
+  return t + ' '.repeat(Math.max(0, n - w));
+};
+
+console.log(`主分支锚: ${mainRef || '（无）'}｜worktree ${rows.length} 个`);
+console.log(`${pad('分类', 14)}${pad('分支', 34)}${pad('HEAD', 10)}${pad('领先/落后', 12)}${pad('最后提交', 12)}路径`);
+for (const r of rows) {
+  const ab = r.ahead === null ? '—' : `${r.ahead}/${r.behind}`;
+  console.log(`${pad(r.kind, 14)}${pad(r.branch, 34)}${pad(r.head.slice(0, 8), 10)}${pad(ab, 12)}${pad(r.lastDate || '—', 12)}${r.path}`);
+}
+
+const stale = rows.filter((r) => r.kind === '可清理' || r.kind === '失效');
+if (execute) {
+  const removable = rows.filter((r) => r.kind === '可清理');
+  const invalid = rows.filter((r) => r.kind === '失效');
+  let removed = 0;
+  for (const r of removable) {
+    const res = git(['worktree', 'remove', r.path], root);
+    if (res.status === 0) { console.log(`✅ 已删除 ${r.path}`); removed++; }
+    else console.error(`❌ 删除失败 ${r.path}：${(res.stderr || '').trim()}`);
+  }
+  if (invalid.length) {
+    const res = git(['worktree', 'prune'], root);
+    if (res.status === 0) console.log(`✅ 已 prune ${invalid.length} 个失效 worktree`);
+    else console.error(`❌ prune 失败：${(res.stderr || '').trim()}`);
+  }
+  console.log(`\n--execute：删除 ${removed} 个可清理 worktree；活跃/主区未动。`);
+  process.exit(0);
+}
+console.log(`\n可清理/失效 ${stale.length} 个。默认只读；确认后加 --execute 删除（只删可清理，失效走 prune）：`);
+for (const r of stale) console.log(`  git worktree remove ${r.kind === '失效' ? '--force ' : ''}"${r.path}"`);

package/templates/engine/.agents/skills/shipyard-workflow-closeout/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: shipyard-workflow-closeout
+description: Shipyard.Material 关单序列：verify --scope、验收勾验、closeout.mjs 落终态/索引/提交、机器门与失败恢复。用于把 workflow 文档收到 done/closed。
+---
+
+# Shipyard.Material 关单确认门操作序列
+
+## 目标
+把已批准的 workflow 文档收到终态，并留下可对账的验证凭证、确认分片和索引。
+
+## 触发条件
+- `workflow/{intents,specs,plans,incidents}` 文档要进入 `done` 或 `closed`。
+
+## 前置
+`approved`（incident 为 `fixed`）已经在当前分支的 git 历史里。还是 `draft` 或 `open` 时，先 `confirm-doc` 到 `approved` / `fixed` 并单独提交，再走下面的关单。
+
+**L1 单笔提交例外（2026-11-08 档 2-D 起，`new-task.md` 快速道第 6 步）**：L1 的 approved→done 连续两跳后，plan(done) + 代码 + 确认分片 + verify 凭证**同笔入库**——approved 不必单独先行入库，也**不走本技能与 closeout.mjs**（其候选路径清单不含产品代码，外来路径护栏会拒），直接 git 提交。同一份文档两跳可用同一次放行原话；跨文档禁复用。本技能仅剩「plan 独立关单」（代码已在前笔入库）与 L2/L3 / incident 场景。
+
+状态行只由 `confirm-doc.mjs` 改。代录使用用户对话里的原话。提交不用 `--no-verify`。自做 L1 不往 `workflow/delegations.md` 写结果行；委派任务和 L2/L3 自做仍按 `stages.md` Test §5 留痕。**承诺面被改写时的出路**：`confirm-doc.mjs <doc> --reconfirm --delegated "<用户原话>"`——重录指纹与承诺面指纹，状态仍为 approved（状态行仍由脚本写，不手改 frontmatter）。
+
+## 执行序列
+
+### 0. 关单自核（原 check-loop §1/§3x hard 职责下沉，2026-10-21 门禁极小化第 2 批）
+对要关的文档族核对四项，缺任一 → 先补齐再关单，禁带着缺口写 done。其中 1（L2/L3）、2、3（L2/L3 intent）已前移到 `confirm-doc.mjs` 关单动作时刻机器执法（2026-11-08 closeout-skill-hardening）——人只补存量与特长外情形，脚本拒绝时按报错补齐：
+
+1. **配对自核**：同族同名件齐否——L2/L3 intent 须有同名 spec 与 plan（confirm-doc 的 `specConfirmed` / `planConfirmedFor` 硬门）；intent（含存量 L1）须有同名 plan；incident 须有同名 plan（L2/L3 另须同名 spec）。L1 配对仍是自核：2026-10-21 门禁极小化已把配对硬门降为 WARN，不在此重硬。
+2. **incident 三件套**（关 incident 时）：`## 复盘三件套` 节内 `1. 结构性修复 / 2. 防复发验证 / 3. 规范条目` 三节齐 +「是否需要新 intent」行；选「是」→ 引用的 intent 路径存在。判据单源 `stage-gates.mjs / incidentTrioGate`，由 confirm-doc 对 →fixed/→closed 硬拦；2026-11-09 首加锚前的存量件与 `流程: legacy` / `存量确认态豁免（` 声明件仍人工自核（判据同上）。
+3. **L2/L3 复核上下文必填**：落盘行格式 `- 独立复核：…（复核上下文：<会话/子代理 id>）`，以 `- 独立复核：` 起行且含「复核上下文：」；L2/L3 intent→done 由 confirm-doc 的 `reviewLineFor` 硬拦，spec/plan 与 L1 仍自核。缺则 **HALT**：回 `.agents/commands/stages.md` Test §4 补独立复核并落盘该行后再关。
+4. **承诺面未被改写（2026-10-27 新增）**：approved 之后若改过**承诺面**（判据文本 / 红线 / 目标 / 改动方案），须先让用户**重新点头**再关单——跑 `node .agents/scripts/confirm-doc.mjs <doc> --reconfirm --delegated "<用户原话>"` 重录承诺面指纹（不推进状态）。**勾验收 + 证据回填 / `确认结果` / 复核行改锚不算改承诺**（已归一，正常关单不受影响）。
+
+完成标准：四项通过；机器门以 confirm-doc 的拒绝信息为准，人工自核项逐条核对。
+
+### 1. 验证
+跑 `node .agents/scripts/verify.mjs --scope`。快速道第 5 步刚刚跑过可沿用，判据不再靠记忆：全绿行落账时记 `dirty`（当时 `backend/` `frontend/` 脏路径快照），关单时 confirm-doc 比对当前业务脏路径——verify 之后新出现的业务改动即判凭证过期（24h 窗口照旧）。存量绿行（无 dirty 字段）维持原口径。
+
+完成标准：有一次退出码 0，且关单时未被判「凭证过期」（被判则重跑 verify 刷新快照）。scope 判定要全量时脚本自己回落，不手改 `workflow/verify-evidence.md`。时序：verify 绿行须**先于** done 跳转产生（dirty 快照记录当时业务脏路径；L1 单笔提交同批的代码在 verify 时已在工作区、属绿行已见路径，不判过期）。
+
+范围对账（advisory，2026-11-11 dev-tour 接线）：跑 `node .agents/scripts/gen-dev-tour.mjs workflow/plans/<name>.md --scope-report`——「文档外实际改动」非空时先解释或回填 plan 再关单（口径同 dev-tour 触发条件；与 `check-scope.mjs` 越界硬门互补，此处只提示不拦，恒 exit 0）。
+
+### 2. 勾验收
+在文档里逐条勾上验收项并写上证据，格式固定：`- [x] 验收项` 同行或紧随续行写「证据：<命令输出 / 路径 / 实测记录>」。判据单源 `stage-gates.mjs / acceptanceEvidenceGate`（关单格式门）：未勾项、缺「证据：」标注的勾选项、L2/L3 spec 无「验收判据」数据行都会在 confirm-doc 处被拒。L1 勾 plan。L2/L3 新需求勾 intent。修复勾 incident，路径是 `open` → `fixed` → `closed`。
+
+完成标准：每一条验收都能指到证据（命令输出、路径或实测记录）；L1 单笔提交时勾验与证据回填须在**提交前**完成（勾选进同笔的 plan(done) blob）。
+
+**勾选语义（口径声明，2026-11-10）**：文档勾选分三类，done 与勾选总数无关——① 任务拆解勾选＝过程留痕 / 会话重入锚（如 `stages.md` §1 捷径检查读勾选态对齐进度），未全勾≠未完成，不构成不关单理由；② 入口红线问卷为否定声明，L1 全不勾即「未触达」的正确态；③ done 的唯一勾选判据＝验收标准节逐条 `[x]` 清零＋证据行（本节 acceptanceEvidenceGate）。禁为「齐整」伪造回填勾选。
+
+### 3. 代录终态
+首选一次调用 `node .agents/scripts/closeout.mjs <doc> --delegated "<用户原话>"`（串接 §3–§5，用法与失败恢复见 §5.1）；下面三步是手工等价路径。
+
+手工代录：`node .agents/scripts/confirm-doc.mjs <doc> --delegated "<用户原话>"`。
+
+incident 从 `fixed` 到 `closed` 再跑一次。spec 标 `done` 时，第 1 步的全绿凭证已经存在。
+
+完成标准：目标文档状态已是 `done` 或 `closed`，正文在这次代录之后保持不动。
+
+### 4. 索引
+跑 `node .agents/scripts/gen-workflow-index.mjs`。
+
+完成标准：`workflow/INDEX.md` 已按磁盘重生成。
+
+### 5. 提交
+`git add` 这些路径：`.agents/confirmations.d/<文档基名>.jsonl`、`workflow/INDEX.md`、`workflow/verify-evidence.md`，以及被关的文档。`.agents/confirmations.jsonl` 只有这次 diff 碰到它才加入。
+
+提交前看该分片的 `git diff`，只保留这次会话的确认行。`closeout.mjs` 已按此清单自动 add 并核对暂存区只有候选路径（夹带其它在途改动即拒），提交不用 `--no-verify`。
+
+提交信息：`docs(workflow): <批次> 关单`。
+
+完成标准：上述路径已入库，钩子通过。
+
+### 5.1 一次调用与失败恢复（重入）
+
+`node .agents/scripts/closeout.mjs <doc> --delegated "<用户对话原话>" [--msg "<提交主题>"] [--dry-run]`
+
+串接顺序：confirm-doc 落终态 → gen-workflow-index 重生成 → git add 固定路径清单 → git commit。incident 两跳各跑一次（`fixed` 与 `closed`）。`--dry-run` 只报当前状态 / 下一跳 / 候选路径变更，不落态、不写盘、不提交。
+
+任一步失败即停，修因后**重跑同一命令**（幂等：终态跳过代录、索引生成幂等、无暂存改动跳过 commit）：
+
+- confirm-doc 拒：该份未落账、未写盘；按报错补齐（配对 / 三件套 / 复核行 / 验收证据 / 委派台账）后重跑。
+- 凭证过期：重跑 `verify.mjs --scope` 刷新 dirty 快照后重跑。
+- 承诺面指纹不符：先 `confirm-doc.mjs <doc> --reconfirm --delegated "<用户原话>"` 重新点头，再关单。
+- 暂存区夹带外来路径：脚本拒绝提交并列出；单独提交或撤销这些路径后重跑（代录与索引已完成，重跑只提交）。
+- 钩子拒绝提交：修钩子原因后重跑，不要 `--no-verify`。
+
+> L1 单笔提交不走本入口（见「前置」例外段）——那条路径只有一笔 git 提交，无独立关单提交。
+
+### 6. 回填特性文档
+
+本次行为变化写进对应活文档，并在 plan / incident 留指针；同一特性只保留一个文档：
+
+| 变化类型 | 回填目标 |
+|---|---|
+| 用户可见交互 / 路径 | `.agents/skills/verify-ui/features/<feature>.md` |
+| 契约 / 规则 / 数据口径 | 原 spec 原地修订（`workflow/README.md` spec 生命周期） |
+| 防复发断言 | `workflow/regression-checklist.md` 对应模块节 |
+| 架构 / 方案 | `wiki/开发方案/` |
+
+只追加变化事实与证据指针，不复制整篇；回填随关单提交。没有对应文档时新建一个，topic 带特性键。
+
+### 7. 配方回收（长任务 / 绕路，非事故）
+
+判据（任一）：同一动作在本次会话重复 $\ge 2$ 次；同一处返工 $\ge 2$ 次；为定位入口或环境试探 $\ge 2$ 轮。
+
+动作：把配方写回权威文件一处——优先改现有命令 / 技能 / 角色正文，不新立技能。落点层级按 `.agents/skills/papercut-fix/SKILL.md` §0 阶梯，本回路通常落第 5 层（文本）。
+
+写法：一句触发条件 + 一步动作 + 一个可指认的验证；引用本次卡点，禁写泛泛建议。
+
+不做：一次性环境故障（进 `.agents/notes/runtime-env.local.md` 或 papercuts `[env]`）；事故走 `.agents/commands/maintain.md` 三件套。
+
+提交：`docs(engine)` 单独提交，不夹带业务代码。

package/templates/engine/.agents/skills/show-me-your-work/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: show-me-your-work
+description: 长跑/无人值守的决策轨迹——append-only TSV，一行一个决策（what/why/evidence/result），证据是指针不是段落；供过夜、多阶段、用户离开后复核时使用。
+---
+
+# show-me-your-work — 决策轨迹
+
+## 触发
+
+- 无人值守 / 过夜 / 多阶段长跑（`autonomous-run`、`pipeline-run`）。
+- 用户说「我走了 / 回来再信你 / 跑完给我看」。
+- 改动跨多个单元，事后需要一条可复核的决策链。
+
+## 格式
+
+单个 TSV，一行一个决策。单元格保持单行；证据是指针，不是段落。
+
+```
+ts	phase	decision	why	evidence	result
+```
+
+- **ts**：ISO8601。
+- **phase**：阶段或工作流。
+- **decision**：选了什么/做了什么，一行。
+- **why**：理由，用大白话；原则驱动就直说，不要堆术语。
+- **evidence**：能证明的指针——commit SHA、PR 号、`file:line`、artifact/trace/截图路径。禁段落。
+- **result**：结果或谓词状态——`tests green` / `reverted` / `pixel-diff 0` / `INCONCLUSIVE` / `open`。
+
+模板：`.agents/skills/show-me-your-work/references/decision-log-template.tsv`。
+
+## 记录规则
+
+- **append-only**：错行不删，追加一行 supersede；永不编辑/删除历史。
+- 只记决策点与检查点：选了哪个分叉、单元完成及其验证结果、pivot/revert 及触发、暴露的阻塞、修好的门。琐碎动作不记。
+- 循环跑：一轮一行。
+- 一次 run = 一个 agent 会话（含后续轮次）。接手/换会话/新 chat = 新 run；新 run 的第一行 phase 写 `start`，并在 evidence 里点名本 run（如 agent id）。
+- 证据优先用**已提交脚本**产出的，而不是手搓一次性命令（「先升层再写文」）。
+
+## 存放
+
+- 默认是工作产物，不提交：`decisions.tsv` 或 `.audit/<task-slug>.tsv`，留在 git 外。
+- 只有「复核者需要这条轨迹才敢信结果」时才提交（大改 / 无人值守 / 跨多 PR）。
+
+## 收尾审计
+
+交回前，用本 run 的 transcript 对账：每行是否对应真实决策/动作；evidence 是否能解析并证明该行；影响过工作但没记的分叉/pivot 是缺口，补上。审计不改故事——错行用新行 supersede。
+
+## 经验日志（给 dreaming 的输入）
+
+`decisions.tsv` 是审计轨迹；`.agents/cache/session-logs/` 是**经验**——dreaming 用它
+对照原始记录纠错。收尾时只把真正值得下次复用的点写进去，不要复制整份 TSV：
+
+```bash
+node .agents/scripts/session-log.mjs append --type failure --text "第一次假设错了：缓存不是瓶颈" --ref <file:line> --tag perf
+node .agents/scripts/session-log.mjs append --type correction --text "测试必须先在 HEAD 上复现失败，再改实现" --tag verify
+```
+
+- `type` 闭集：`decision / failure / correction / refusal / note`。
+- `--tag` 用来让 `memory-tier suggest` 发现重复模式（同类 ≥3 次才考虑上浮为规则）。
+- 日志是运行态（gitignore），删除后可从审计轨迹与 git 重建；不要当权威。
+
+## 跨模型复核
+
+交回前，用**不同模型档**的子代理读轨迹 + transcript，标出用户该注意的点：证据弱/缺失、验证跳过或只在口头上、事后看有风险的决策、用户随手扫会漏的缺口。回复末尾给 `Attention` 段，首行 `reviewed by <model>`；`No flags` 是合法值。
+
+## 本仓落点
+
+- `autonomous-run`：立约时加一条「决策留痕」。
+- `pipeline-run`：每个工单签收记一行。
+- `workflow/delegations.md`：委派结果仍记台账；本 TSV 是 per-run 的决策链，不替代台账。
+- 追加一行：`node .agents/skills/show-me-your-work/scripts/decision-log.mjs <logfile> <phase> <decision> <why> <evidence> <result>`（自动 ts、首用表头、清洗 tab/换行、转义 `=+-@` 开头）。

package/templates/engine/.agents/skills/show-me-your-work/references/decision-log-template.tsv

@@ -0,0 +1 @@
+ts	phase	decision	why	evidence	result

package/templates/engine/.agents/skills/show-me-your-work/scripts/decision-log.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// decision-log.mjs — 决策 TSV 追加器（show-me-your-work 2026-10-22，pstack 借鉴）
+// 用法：node .agents/skills/show-me-your-work/scripts/decision-log.mjs <logfile> <phase> <decision> <why> <evidence> <result>
+// 行为：首用写表头；ts 自动；单元格去 tab/换行；以 = + - @ 开头的单元格加单引号（防表格注入）。
+// 口径：append-only——错行不删，追加一行 supersede；证据是指针（commit/file:line/artifact），不是段落。
+import fs from 'node:fs';
+import path from 'node:path';
+
+const HEADER = 'ts\tphase\tdecision\twhy\tevidence\tresult';
+const [logfile, phase, decision, why, evidence, result] = process.argv.slice(2);
+if (!logfile || !phase || !decision) {
+  console.error('用法：node .agents/skills/show-me-your-work/scripts/decision-log.mjs <logfile> <phase> <decision> <why> <evidence> <result>');
+  process.exit(2);
+}
+const cell = (v) => {
+  const s = String(v ?? '').replace(/[\t\r\n]+/g, ' ').trim();
+  return /^[=+\-@]/.test(s) ? `'${s}` : s;
+};
+const row = [new Date().toISOString(), phase, decision, why, evidence, result].map(cell).join('\t');
+const abs = path.resolve(logfile);
+fs.mkdirSync(path.dirname(abs), { recursive: true });
+if (!fs.existsSync(abs) || fs.statSync(abs).size === 0) fs.writeFileSync(abs, `${HEADER}\n`);
+fs.appendFileSync(abs, `${row}\n`);
+console.log(`✅ 决策已记 ${logfile}`);

package/templates/engine/.agents/skills/tfs-pr/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: tfs-pr
+description: 内网自托管 TFS / Azure DevOps Server PR 技能，项目无关：自动识别 git 仓库与远端推导 collection/project/repo，PAT 缺失时引导创建并保存环境变量；查 PR / 建 PR（context 拉 diff 提炼标题与描述）/ 改 PR 描述 / 冲突预检与 worktree 隔离解决，走 REST API + PAT（az devops 扩展拒 http 组织 URL，az 不可用）。命令入口 .agents/skills/tfs-pr/scripts/tfs-pr.mjs。
+---
+
+# tfs-pr — 内网 TFS / Azure DevOps Server PR（项目无关）
+
+零项目假设：远端是 TFS / Azure DevOps 形态（路径含 `_git`），或能给出 collection URL，即可用。技能目录自包含。宿主侧只放指针壳（本仓仅 `.codebuddy` 一处；`.trae` 壳 2026-11-08 移除），主本变更无同步义务。下文 `tfs-pr` 代指 `node .agents/skills/tfs-pr/scripts/tfs-pr.mjs`。
+
+## 触发 / 不触发
+- 触发：「查 PR / 有没有冲突」「补 / 改 PR 描述」「解决 PR 冲突」等内网 TFS 事务；`az devops login` 报 "Refusing to attach credentials to an invalid Azure DevOps organization URL" → 转本技能，禁再试 az。
+- 触发（建 PR 类）：宿主有 PR 唯一入口约定时（如 Shipyard.Material 的 `pr-create.mjs`），「建 PR / 推送并建 PR」**不直接触发本技能**——建 PR 只走宿主唯一入口 `node .agents/scripts/pr-create.mjs`（内部调 `tfs-pr create`）；agent 禁止绕过宿主入口直接调 `tfs-pr create`。无此约定的宿主可保留直接触发。（本仓原评审前置已于 2026-11-09 退役为手动工具：面板评审按需手动跑，见 `.agents/commands/pr-review.md`。）
+- 不触发：GitHub / GitLab 等公网托管 PR；普通代码评审、commit 消息。
+
+## 0. 前置探测
+```bash
+git rev-parse --is-inside-work-tree   # 非 0 → 不是 git 仓库，停止告知
+tfs-pr target                          # base/project/repo/tokenUrl/prPage，零请求、无需 PAT
+```
+- `target` 报错自带补救：让用户给 collection URL（形如 `http://<host>:<port>/tfs/<collection>`），按 `--base`（单次）/ `TFS_BASE`（环境变量）/ `git config tfs-pr.base`（仓库级）落位；project / repo 用 `--project` / `--repo` 覆盖；非 origin 远端用 `--remote` / `TFS_REMOTE`。
+- 认得的远端形态：`ssh://host:22/tfs/COLL/PROJ/_git/R`、`git@host:tfs/...`（scp 式）、`https://host/tfs/COLL/PROJ/_git/R`、根挂载（无 /tfs）、短形态（project==collection）、`dev.azure.com` / `*.visualstudio.com`。
+- ssh 远程 web base 默认 `http://<host>:8080`，`TFS_WEB_SCHEME` / `TFS_WEB_PORT` 覆盖；老 TFS 设 `TFS_API_VERSION=4.1`（默认 6.0）；目标分支可固化 `git config tfs-pr.target <branch>`。
+
+## 1. PAT：读 → 引导 → 用
+只存环境变量（禁进 argv / 对话 / 打印）：单台服务器用全局 `TFS_PAT`；多台按 base 主机名分存 `TFS_PAT_<HOST>`（非字母数字转 `_` 大写，如 `TFS_PAT_10_0_0_1`，命中优先）。
+- 探测与引导一条命令：`tfs-pr setup`——打印两变量的进程/用户级状态、动态门户 `<base>/_usersSettings/tokens`（禁写死站点 IP）、setx 命令、whoami 自检。未配置 → 把 setup 输出的三步给用户：门户生成（scopes 勾 Code Read&Write + Pull Request Read&Write + **Work Items Read**——建后核对关联工作项必需，缺了该 scope 核对步会 401）→ `setx <变量> "<PAT>"`（新开终端生效）→ `tfs-pr whoami` 真验证（长度非空 ≠ PAT 有效）。
+- setx 后当前进程未继承：从注册表取值喂脚本，命令行不得出现值：`TFS_PAT="$(powershell -NoProfile -Command "[Environment]::GetEnvironmentVariable('TFS_PAT','User')")" tfs-pr …`（分存变量同理）。
+- 兜底 `--pat-file` 仅限用户明确不用环境变量，收尾 `rm -f`；PAT 泄入对话/日志/历史 → 收尾必须提醒门户撤销重建。
+
+## 2. 命令
+| 动作 | 命令 | 说明 |
+|---|---|---|
+| 识别目标 | `tfs-pr target` | base/project/repo/tokenUrl/prPage |
+| PAT 指引 | `tfs-pr setup` | 门户地址 + 持久化 + 自检命令 |
+| 验证 PAT | `tfs-pr whoami` | 当前身份 + base/project/repo + PR 页 |
+| 查 PR | `tfs-pr list [--source <b>] [--target <b>] [--status active\|all] [--json]` | `#12 [active/succeeded] feat/x → develop <title>` |
+| 查单个 | `tfs-pr get <id> [--json]` | status/mergeStatus + PR 页 URL；JSON 含完整描述 |
+| 建前上下文 | `tfs-pr context [--source <b>] [--target <b>] [--no-fetch] [--patch] [--json]` | commits/files/stat/overlap/conflicts/push/dirty 一把梭 |
+| 建 PR | `tfs-pr create [--source <b>] [--target <b>] --title <t> --body-file <f\|-> [--dry-run] [--json]` | `CREATED #id …` 或幂等 `EXISTING #id` |
+| 改描述 | `tfs-pr desc <id> --body-file <f\|-> [--dry-run] [--json]` | `UPDATED #id …`（已回读比对） |
+| 冲突预检 | `tfs-pr conflicts <id> [--no-fetch] [--json]` | 按 PR 分支取 conflicts/overlap/mergeBase |
+| 本地冲突预检 | `tfs-pr conflicts --source <b> --target <b> [--no-fetch] [--json]` | 无需 PAT、无需 PR id |
+
+- source 默认当前分支（detached HEAD 需 `--source`）；target 默认 `--target` / `TFS_TARGET` / `git config tfs-pr.target` / 远端 HEAD；分支名无需 `refs/heads/` 前缀。
+- `--body-file -` 从 stdin 读正文免临时文件；正文 UTF-8（BOM 自动剥），中文与换行原样。
+- `--dry-run` 零请求且无需 PAT；退出码 0 成功（含 EXISTING）/ 1 HTTP·API·网络错误 / 2 用法·配置错误。
+
+## 3. 建 PR：从 diff 提炼标题与描述
+1. `tfs-pr context --target <目标分支> --json`（默认自动 fetch；`--no-fetch` 仅离线或 refs 已新鲜）。产出：commits、files、stat/shortstat、overlap（双方都改过）、conflicts（merge-tree；`conflictsSupported=false` 表示 git 不支持预检，勿当无冲突）、push（未推送/远端无分支）、dirty（未提交改动）。
+2. 建前检查：`push.unpushed` 或远端无分支 → 先正常 `git push`（被门禁拦修根因，禁 `--no-verify` / force push）；`dirty` → 确认未提交改动是否入 PR，勿静默忽略；`conflicts.files` 非空 → 先按 §5 解；`overlap` 非空但无文本冲突 → 人工过双方改动确认语义。
+3. 需要看具体改动再读关键文件或 `git diff origin/<目标分支>...HEAD`（`--patch` 可附完整 diff）。
+4. **标题**：Conventional Commits 中文 `feat(scope): 摘要`（复合主题 `+` 串联，约 70 字符内，禁空标题 / 带 PR 号）；scope 取主要模块/目录，主题从 diff 主要变更 + commits 归纳，非复述 commit message。
+   - **`#数字` 禁令（2026-10-26 实证）**：commit message / PR 标题 / PR 描述里**引用 PR 号一律写「PR 720」，禁写 `#720`**——`#N` 是工作项关联语法，推送即自动把工作项 N 挂到提交与 PR 上；PR 号与工作项 ID 同数值空间，必撞无关工作项（PR #719 曾因此错挂）。`#N` 仅在真实要关联某工作项时使用。**PR 描述里引用其他 PR 用 markdown 链接**（`[PR 720](<prPage>/<id>)`，`prPage` 见 `target` 输出，单页 URL 为 `pullrequest/<id>`）；首个 PR 号出现处链接即可，其余纯文本。
+5. **描述**（`create` / `desc` 都是整段替换，必须给完整正文；模板为**缺省值**——宿主仓库已有自己的 PR body 约定时以宿主约定为准，查宿主的评审/合并文档，本模板仅兜底）：
+   ```markdown
+   ## Summary
+   - 为什么改、改了什么（1-4 条，指向关键模块/文件；必须来自实际 diff）
+
+   ## Evidence
+   - 实际运行的测试/构建/手工验证；没运行就明确写「未运行」及原因，禁编造
+
+   ## Merge Danger
+   - Door: 影响面（API / DB / 配置 / 权限 / 兼容性）；无风险写「无」，禁省略
+   - Blast Radius: 局部 / 模块 / 全局
+   - Rollback: 回滚方式与风险
+   ```
+   diff 大、overlap 非空或不可逆变更 → 追加 `## Tradeoffs`：引用 shortstat 真实规模 + 为什么仍这样做。
+6. 先 `--dry-run` 验 URL 与正文，再正式 create；`mergeStatus=queued` 用 `get` 轮询，`conflicts` 转 §5；PR 页 URL 返回用户。
+
+## 4. 改 PR 描述
+`get <id> --json` 读现有 → 判断替换还是补充（补充 = 把新内容合并进现有，保留有用三节）→ `desc <id> --body-file -`（stdin）或文件。**desc 是整段替换不是追加**，禁用增量片段覆盖原文。源分支又有新提交 → 先重跑 context 再更新描述，防 Summary 与实际 diff 脱节。
+
+## 5. 解决 PR 冲突
+定位：`tfs-pr conflicts <id> --json`（从 PR 取分支 → fetch → merge-tree + overlap + mergeBase）。服务端 conflicts 但本地空 → refs 过期/服务端未刷新，重新 fetch 后 `get` 确认，**禁直接断言无冲突**。
+
+解决（worktree 隔离，不动用户当前工作区，不 stash/reset 用户未提交改动）：
+```bash
+git fetch <remote> <src> <tgt>
+git worktree add <tmp>/pr-<id> -b tfs-pr/<id>-resolve refs/remotes/<remote>/<src>
+cd <tmp>/pr-<id> && git merge refs/remotes/<remote>/<tgt>
+# 逐文件解决、保留双方意图，禁盲目 --ours/--theirs；overlap 自动合并成功的也要过语义（调用方/配置/迁移/契约）
+# 跑项目测试/构建；只 stage 已解决文件；提交信息说明解决了哪些冲突——PR 号禁写 #N（同 §3 步骤 4 禁令：#N 会错挂无关工作项，写「PR 720」）
+git push <remote> HEAD:<src>
+```
+- 禁 force push（含 `--force-with-lease`，除非用户明确确认）；push 被拦 = 门禁执法，修根因，禁 `--no-verify`；分支策略禁直接推 → 停下报告选项，不绕过。
+- fork 源分支本地 fetch 失败 → 请用户提供源仓库或在源仓解决，不猜；PR 已 completed/abandoned → 不解冲突，报告状态。
+- 收尾只删本技能建的 worktree/分支：`git worktree remove <tmp>/pr-<id> && git branch -D tfs-pr/<id>-resolve`，不动用户任何分支/worktree。
+- 复查：`get <id>` → mergeStatus 离开 conflicts（queued 轮询到收敛）才算完成。
+
+## 6. 错误判读
+- **响应三判**（脚本已内建，手工排查同序）：先判 `status` → 再判 `content-type`（`401 + text/html` = 没带/带错凭据，常见 `TF400813`；直接 `JSON.parse` 只会得到误导的 `Unexpected token '<'`，禁硬 parse）→ 确认 JSON 再 parse。
+- `401 JSON` = PAT 无效/过期/scope 不足（门户重建）；`404 JSON` = base 指错站点/端口（如 API 在 8080 而 base 指 80）或 project/repo 拼错（`target` 核对）；`EXISTING` = 同 source→target 已有 active PR（改走 `desc` 或先 abandon）；网络/TLS 错误查 VPN/代理/证书（`--verbose` 只打 URL 不打 PAT）。
+
+## 7. 收尾判据
+查/建/改后 status/mergeStatus 与预期一致（desc 已回读比对）；**关联工作项已核对**（`curl -s -u ":$TFS_PAT" "<base>/<project>/_apis/git/repositories/<repo>/pullrequests/<id>/workitems?api-version=6.0"` 列出后逐条核对是否为预期工作项——本仓默认无工作项关联，非空即须解释；错挂须在门户移除后复核为空，PAT 无 Work Items Read scope 时该步 401、需门户人工核对）；PR 页 URL 已返回用户；解冲突后推送成功且不再 conflicts；临时正文/凭据文件已删；PAT 未进仓库/日志/对话，泄露已提醒撤销；汇报 PR 号、URL、status/mergeStatus 与实际做过的验证，没跑测试就明说。