dsh-harness-kit 0.1.5 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/README.md +30 -15
  2. package/README.zh-CN.md +29 -18
  3. package/client.js +108 -11
  4. package/docs/DETAIL.en.md +30 -10
  5. package/docs/DETAIL.md +15 -5
  6. package/kernel/advance.js +3 -3
  7. package/kernel/bindings.js +11 -6
  8. package/kernel/commands.js +257 -20
  9. package/kernel/local-files.js +175 -0
  10. package/kernel/metrics.js +280 -0
  11. package/kernel/panel.js +141 -7
  12. package/kernel/paths.js +62 -1
  13. package/kernel/setup.js +20 -19
  14. package/kernel/te.js +4 -4
  15. package/kernel/worktree.js +164 -20
  16. package/package.json +1 -1
  17. package/packs/ai-coding/agents/business-analyst.md +4 -4
  18. package/packs/ai-coding/agents/code-reviewer.md +6 -6
  19. package/packs/ai-coding/agents/developer.md +5 -5
  20. package/packs/ai-coding/agents/solution-architect.md +2 -2
  21. package/packs/ai-coding/assets/scripts/codebase_guide_init.py +70 -48
  22. package/packs/ai-coding/assets/scripts/harness_init.py +30 -11
  23. package/packs/ai-coding/assets/scripts/te_lease.py +106 -0
  24. package/packs/ai-coding/assets/scripts/update_board.py +30 -0
  25. package/packs/ai-coding/assets/scripts/verify.py +3 -3
  26. package/packs/ai-coding/assets/templates/dotnet/dotnet-multimodule/{app-CLAUDE.tmpl → app-AGENTS.tmpl} +5 -5
  27. package/packs/ai-coding/assets/templates/dotnet/dotnet-multimodule/{module-CLAUDE.tmpl → module-AGENTS.tmpl} +5 -5
  28. package/packs/ai-coding/assets/templates/dotnet/dotnet-multimodule/{root-CLAUDE.tmpl → root-AGENTS.tmpl} +3 -3
  29. package/packs/ai-coding/assets/templates/java/maven/{root-CLAUDE.tmpl → root-AGENTS.tmpl} +3 -3
  30. package/packs/ai-coding/assets/templates/java/maven-multimodule/{module-CLAUDE.tmpl → module-AGENTS.tmpl} +5 -5
  31. package/packs/ai-coding/assets/templates/java/maven-multimodule/{root-CLAUDE.tmpl → root-AGENTS.tmpl} +3 -3
  32. package/packs/ai-coding/assets/templates/javascript/mobile-app/{root-CLAUDE.tmpl → root-AGENTS.tmpl} +3 -3
  33. package/packs/ai-coding/assets/templates/javascript/uniapp/{root-CLAUDE.tmpl → root-AGENTS.tmpl} +3 -3
  34. package/packs/ai-coding/assets/templates/javascript/vue-multimodule/{app-CLAUDE.tmpl → app-AGENTS.tmpl} +4 -4
  35. package/packs/ai-coding/assets/templates/javascript/vue-multimodule/{root-CLAUDE.tmpl → root-AGENTS.tmpl} +3 -3
  36. package/packs/ai-coding/flows/init.yml +7 -7
package/kernel/te.js CHANGED
@@ -1,7 +1,7 @@
1
1
  // TE 环境串行排队(M3 一期,2026-11-15 定):测试环境全局只有一个
2
2
  // (起服务/连 TDengine/jmeter 不可多任务并发),TE 阶段按租约串行:
3
3
  //
4
- // - 租约台账 .harness/tasks/test-env.json(本机状态,不进资产 git):
4
+ // - 租约台账 .harness/local/test-env.json(本机状态,不进资产 git):
5
5
  // { "holder": "task-x", "since": "ISO", "queue": ["task-y"] }
6
6
  // - PM 派发 TE Worker 前必须先 `/hk-te acquire <任务>`:
7
7
  // 空闲 → 授权;自己持有 → 已持有;别人持有 → 排队并暂停 TE 阶段(内核不可抢占运行中的 Worker,门在派发前)
@@ -10,10 +10,10 @@
10
10
  // - grace:holder 已授权但看板链还没标 TE▶(PM 先 acquire 后写板的时序窗口)不释放
11
11
  import fs from 'node:fs';
12
12
  import path from 'node:path';
13
- import { harnessDir } from './paths.js';
13
+ import { localStatePath } from './paths.js';
14
14
  import { keepLedgerLocal } from './worktree.js';
15
15
 
16
- const envPath = (ws) => path.join(harnessDir(ws), 'tasks', 'test-env.json');
16
+ const envPath = (ws) => localStatePath(ws, 'test-env.json', 'tasks/test-env.json');
17
17
 
18
18
  export function readTestEnv(ws) {
19
19
  try {
@@ -29,7 +29,7 @@ export function readTestEnv(ws) {
29
29
  function writeTestEnv(ws, env) {
30
30
  fs.mkdirSync(path.dirname(envPath(ws)), { recursive: true });
31
31
  fs.writeFileSync(envPath(ws), `${JSON.stringify(env, null, 2)}\n`, 'utf8');
32
- keepLedgerLocal(ws, 'tasks/test-env.json');
32
+ keepLedgerLocal(ws);
33
33
  }
34
34
 
35
35
  /** 看板链中 TE 阶段的标记(✅ 完成 / — 跳过 → 不再需要环境;▶/…/⛔/缺 → 仍可能需要)。 */
@@ -13,7 +13,7 @@
13
13
  // - 卫生纪律:分配给新任务前 slot 必须干净(git status 空),脏 slot 拒绝分配并给清理指引
14
14
  // (不自动 stash——残留可能是有价值的工作,由人裁决)。
15
15
  //
16
- // 台账 .harness/tasks/worktrees.json(v2):
16
+ // 台账 .harness/local/worktrees.json(v2):
17
17
  // {
18
18
  // "version": 2,
19
19
  // "slots": { "<repo>": { "slot-1": { "task": "…", "branch": "…", "since": "ISO", "state": "bound" | "stale-unmerged" } } },
@@ -23,10 +23,11 @@
23
23
  // M1 刚上线即改为池化,野外无 v1 数据需要迁移。
24
24
  import fs from 'node:fs';
25
25
  import path from 'node:path';
26
- import { harnessDir } from './paths.js';
26
+ import { harnessDir, localStatePath } from './paths.js';
27
27
  import { runGit } from './exec.js';
28
+ import { provisionLocalFiles } from './local-files.js';
28
29
 
29
- const ledgerPath = (ws) => path.join(harnessDir(ws), 'tasks', 'worktrees.json');
30
+ const ledgerPath = (ws) => localStatePath(ws, 'worktrees.json', 'tasks/worktrees.json');
30
31
  const worktreeRoot = (ws, repo) => path.join(ws, '.worktrees', repo);
31
32
 
32
33
  // --------------------------------------------------------------- 台账读写
@@ -46,19 +47,19 @@ function writeWorkspaces(ws, { slots, tasks }) {
46
47
  keepLedgerLocal(ws);
47
48
  }
48
49
 
49
- /** 台账本地化:.gitignore 排除 + 已追踪的旧文件摘除追踪(保留本地文件)。失败容忍。 */
50
- export function keepLedgerLocal(ws, entry = 'tasks/worktrees.json') {
50
+ /** 本机状态本地化:.gitignore 排除整个 .harness/local/;旧 tasks/*.json 行保留不影响。 */
51
+ export function keepLedgerLocal(ws, _entry = null) {
51
52
  try {
52
53
  const hd = harnessDir(ws);
53
54
  const gi = path.join(hd, '.gitignore');
54
55
  const cur = fs.existsSync(gi) ? fs.readFileSync(gi, 'utf8') : '';
55
- if (!cur.split('\n').some((l) => l.trim() === entry)) {
56
- fs.appendFileSync(gi, `${cur.endsWith('\n') || cur === '' ? '' : '\n'}# 本机工作区/环境台账(机器本地状态,不共享、勿提交)\n${entry}\n`, 'utf8');
56
+ if (!cur.split('\n').some((l) => l.trim() === 'local/')) {
57
+ fs.appendFileSync(gi, `${cur.endsWith('\n') || cur === '' ? '' : '\n'}# 本机状态(机器本地,不共享、勿提交)\nlocal/\n`, 'utf8');
57
58
  }
58
59
  if (fs.existsSync(path.join(hd, '.git'))) {
59
- runGit(['rm', '--cached', '--quiet', '--ignore-unmatch', entry], { cwd: hd });
60
+ runGit(['rm', '-r', '--cached', '--quiet', '--ignore-unmatch', 'local'], { cwd: hd });
60
61
  }
61
- } catch { /* 容忍:最坏结果是台账被同步,跨用户挡路问题复现 */ }
62
+ } catch { /* 容忍:最坏结果是本机状态被同步 */ }
62
63
  }
63
64
 
64
65
  // 兼容旧测试与外部引用
@@ -211,7 +212,7 @@ async function mergedStatus(repoDir, branch, base) {
211
212
 
212
213
  // --------------------------------------------------------------- 决策点(需人裁决的结构性阻塞)
213
214
 
214
- const decisionsPath = (ws) => path.join(harnessDir(ws), 'tasks', 'decisions.json');
215
+ const decisionsPath = (ws) => localStatePath(ws, 'decisions.json', 'tasks/decisions.json');
215
216
 
216
217
  /** 待裁决决策点(本机状态):{ <task>: { code, text, options, at } }。 */
217
218
  export function readDecisions(ws) {
@@ -224,7 +225,7 @@ export function readDecisions(ws) {
224
225
  function writeDecisions(ws, decisions) {
225
226
  fs.mkdirSync(path.dirname(decisionsPath(ws)), { recursive: true });
226
227
  fs.writeFileSync(decisionsPath(ws), `${JSON.stringify(decisions, null, 2)}\n`, 'utf8');
227
- keepLedgerLocal(ws, 'tasks/decisions.json');
228
+ keepLedgerLocal(ws);
228
229
  }
229
230
 
230
231
  /** 记录决策点(工作区分配拒绝等);重复记录覆盖(保持最新文本)。 */
@@ -256,20 +257,144 @@ export async function describeMainWorktree(ws, source, { maxLines = 10 } = {}) {
256
257
  ].join('\n');
257
258
  }
258
259
 
260
+ /** 判断 ancestor 是否为 descendant 的祖先(git 退出码 0 = 是)。 */
261
+ async function isAncestor(repoDir, ancestor, descendant) {
262
+ return (await runGit(['merge-base', '--is-ancestor', ancestor, descendant], { cwd: repoDir })).code === 0;
263
+ }
264
+
265
+ /** 把目标本地分支的上游设为 origin/<target>(远端分支存在时;失败不阻断)。 */
266
+ async function setTargetUpstream(repoDir, target) {
267
+ const remote = await runGit(['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${target}`], { cwd: repoDir });
268
+ if (remote.code !== 0) return;
269
+ await runGit(['branch', '--set-upstream-to', `origin/${target}`, target], { cwd: repoDir });
270
+ }
271
+
272
+ /** 把 origin/<target> 干净地并入本地目标(仅本地,不推送);冲突中止回滚。 */
273
+ async function mergeRemoteIntoTarget(ws, repoDir, name, target, remoteRev, out) {
274
+ const localRev = (await runGit(['rev-parse', 'refs/heads/' + target], { cwd: repoDir })).stdout.trim();
275
+ const holder = await worktreeOnBranch(repoDir, target);
276
+ let cwd = holder;
277
+ let tempDir = null;
278
+ if (!cwd) {
279
+ tempDir = path.join(worktreeRoot(ws, name), '_sync');
280
+ fs.rmSync(tempDir, { recursive: true, force: true });
281
+ fs.mkdirSync(path.dirname(tempDir), { recursive: true });
282
+ const add = await runGit(['worktree', 'add', tempDir, target], { cwd: repoDir });
283
+ if (add.code !== 0) {
284
+ out.refused.push({ repo: name, reason: `目标 ${target} 同步工作树创建失败:${(add.stderr || '').trim().split('\n')[0]}` });
285
+ return false;
286
+ }
287
+ cwd = tempDir;
288
+ }
289
+ if (await isDirty(cwd)) {
290
+ if (tempDir) await runGit(['worktree', 'remove', '--force', tempDir], { cwd: repoDir });
291
+ out.refused.push({ repo: name, reason: `目标分支 ${target} 所在工作树有未提交改动,无法并入远端:${cwd}` });
292
+ return false;
293
+ }
294
+ const mg = await runGit(['merge', '--no-edit', `origin/${target}`], { cwd });
295
+ if (mg.code !== 0) {
296
+ const files = (await runGit(['diff', '--name-only', '--diff-filter=U'], { cwd })).stdout.trim().split('\n').filter(Boolean);
297
+ await runGit(['merge', '--abort'], { cwd });
298
+ if (tempDir) { await runGit(['worktree', 'remove', '--force', tempDir], { cwd: repoDir }); fs.rmSync(tempDir, { recursive: true, force: true }); }
299
+ out.refused.push({ repo: name, reason: `目标 ${target} 与 origin/${target} 分叉且自动并入冲突(已回滚):${files.slice(0, 6).join('、') || '见 git status'}` });
300
+ return false;
301
+ }
302
+ if (tempDir) { await runGit(['worktree', 'remove', '--force', tempDir], { cwd: repoDir }); fs.rmSync(tempDir, { recursive: true, force: true }); }
303
+ await setTargetUpstream(repoDir, target);
304
+ out.synced.push({ repo: name, target, from: localRev.slice(0, 12), to: remoteRev.slice(0, 12), merged: true });
305
+ return true;
306
+ }
307
+
308
+ /**
309
+ * 合并前把本地目标与 origin/<target> 对齐。
310
+ * - safe(默认):落后 → 快进;领先 → 保留;分叉 → 干净地并入 origin(冲突回滚)。
311
+ * - ff-only:落后 → 快进;领先/分叉 → 停止。
312
+ * - off:不同步。
313
+ * 返回 true = 可以继续;false = 已写入 out.refused。
314
+ * 不做 rebase、不强制更新、不推送。
315
+ */
316
+ async function syncTargetBranch(ws, repoDir, name, target, out, mode = 'safe') {
317
+ const hasOrigin = (await runGit(['remote', 'get-url', 'origin'], { cwd: repoDir })).code === 0;
318
+ if (!hasOrigin) return true;
319
+ const remoteRef = `refs/remotes/origin/${target}`;
320
+ const hadRemoteRef = (await runGit(['rev-parse', '--verify', '--quiet', remoteRef], { cwd: repoDir })).code === 0;
321
+ // fetch 是只读远端操作;失败时若有已知远端分支则停止,避免在旧目标上合入。
322
+ const fetched = await runGit(['fetch', 'origin', target], { cwd: repoDir, timeoutMs: 30_000 });
323
+ if (fetched.code !== 0) {
324
+ if (hadRemoteRef) {
325
+ out.refused.push({
326
+ repo: name,
327
+ reason: `目标 ${target} 远端拉取失败(${(fetched.stderr || '').trim().split('\n')[0] || '网络/权限'});修复后重试,或加 --no-merge 仅归档`,
328
+ });
329
+ return false;
330
+ }
331
+ // 远端还没有同名分支:按纯本地目标处理。
332
+ return true;
333
+ }
334
+ const remoteRev = (await runGit(['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${target}`], { cwd: repoDir })).stdout.trim();
335
+ if (!remoteRev) return true;
336
+ const localRev = (await runGit(['rev-parse', '--verify', '--quiet', `refs/heads/${target}`], { cwd: repoDir })).stdout.trim();
337
+ if (!localRev) return true;
338
+ if (localRev === remoteRev) {
339
+ await setTargetUpstream(repoDir, target);
340
+ return true;
341
+ }
342
+ if (await isAncestor(repoDir, localRev, remoteRev)) {
343
+ // 本地目标落后远端:优先在 checkout 它的干净工作树里快进;否则直接更新 ref。
344
+ const holder = await worktreeOnBranch(repoDir, target);
345
+ if (holder) {
346
+ if (await isDirty(holder)) {
347
+ out.refused.push({ repo: name, reason: `目标分支 ${target} 所在工作树有未提交改动,无法快进:${holder}` });
348
+ return false;
349
+ }
350
+ const ff = await runGit(['merge', '--ff-only', `origin/${target}`], { cwd: holder });
351
+ if (ff.code !== 0) {
352
+ out.refused.push({ repo: name, reason: `目标 ${target} 快进失败:${(ff.stderr || '').trim().split('\n')[0]}` });
353
+ return false;
354
+ }
355
+ } else {
356
+ const ur = await runGit(['update-ref', `refs/heads/${target}`, remoteRev], { cwd: repoDir });
357
+ if (ur.code !== 0) {
358
+ out.refused.push({ repo: name, reason: `目标 ${target} 本地 ref 快进失败` });
359
+ return false;
360
+ }
361
+ }
362
+ await setTargetUpstream(repoDir, target);
363
+ out.synced.push({ repo: name, target, from: localRev.slice(0, 12), to: remoteRev.slice(0, 12) });
364
+ return true;
365
+ }
366
+ if (await isAncestor(repoDir, remoteRev, localRev)) {
367
+ // 本地目标领先远端:这是 autoClose 未推送合并提交后的常态,safe 模式不应阻止下一次收尾。
368
+ if (mode === 'ff-only') {
369
+ out.refused.push({ repo: name, reason: `目标 ${target} 有未推送的本地提交(领先 origin/${target});ff-only 模式停止,改用 safe 或先推送` });
370
+ return false;
371
+ }
372
+ await setTargetUpstream(repoDir, target);
373
+ return true;
374
+ }
375
+ if (mode !== 'safe') {
376
+ out.refused.push({ repo: name, reason: `目标 ${target} 与 origin/${target} 已分叉;ff-only 模式停止,改用 safe 或先人工合并` });
377
+ return false;
378
+ }
379
+ return mergeRemoteIntoTarget(ws, repoDir, name, target, remoteRev, out);
380
+ }
381
+
259
382
  /**
260
383
  * 本地合入任务分支到目标基线(B 方案,2026-11-17 定):不推送,推送仍归人。
261
- * 人通过 /hk-archive <任务> --merge(可带 repo:branch 覆盖)显式确认目标分支——
262
- * 确认即触发本次调用。合并提交留在目标分支上;冲突则中止并报告,不污染基线。
263
384
  *
385
+ * 2026-11-22(0.2.0):合并前先把本地目标快进到 origin/<target>(只 ff),
386
+ * 已合入(本地或远端)不再重复 merge;冲突/目标脏/目标分叉全部在归档前停止。
264
387
  * 合并位置:目标分支若被某工作树 checkout 且干净 → 就地合并;否则建临时工作树
265
388
  * (.worktrees/<仓>/_merge)合并后删除。主工作树脏 → 拒绝该仓。
266
- * 返回 { merged: [{repo,target,commit}], conflicts: [{repo,target,files}], refused: [{repo,reason}] }。
389
+ *
390
+ * 返回 { merged, conflicts, refused, alreadyMerged, synced, planned, dryRun }。
267
391
  */
268
- export async function mergeTaskBranches(ws, kit, task, overrides = {}) {
269
- const out = { merged: [], conflicts: [], refused: [] };
392
+ export async function mergeTaskBranches(ws, kit, task, overrides = {}, { syncTarget = 'safe', dryRun = false } = {}) {
393
+ const out = { merged: [], conflicts: [], refused: [], alreadyMerged: [], synced: [], planned: [], dryRun: dryRun === true };
270
394
  const ledger = readWorkspaces(ws);
271
395
  const entry = ledger.tasks?.[task];
272
- if (!entry) { out.refused.push({ repo: '-', reason: `台账无任务 ${task} 的工作区记录` }); return out; }
396
+ // 无台账 = 本任务没有分配过代码工作区(纯文档任务),不是错误;直接跳过合入。
397
+ if (!entry) { out.noWorkspace = true; return out; }
273
398
 
274
399
  for (const [name, info] of Object.entries(entry.repos ?? {})) {
275
400
  if (!info || !info.branch) continue; // 无分支记录(非 git 仓)跳过;main/slot 两种放置都可合入
@@ -289,6 +414,7 @@ export async function mergeTaskBranches(ws, kit, task, overrides = {}) {
289
414
  const cb = await runGit(['branch', local, target], { cwd: repoDir });
290
415
  if (cb.code !== 0) { out.refused.push({ repo: name, reason: `目标 ${target} 无法建立本地分支` }); continue; }
291
416
  }
417
+ await setTargetUpstream(repoDir, local);
292
418
  target = local;
293
419
  }
294
420
  if ((await runGit(['rev-parse', '--verify', `refs/heads/${target}`], { cwd: repoDir })).code !== 0) {
@@ -301,6 +427,21 @@ export async function mergeTaskBranches(ws, kit, task, overrides = {}) {
301
427
  continue;
302
428
  }
303
429
 
430
+ // 已合入本地目标:无需同步/合并,直接释放。远端 MR 合入的情况在 sync 后再判一次。
431
+ if (await mergedLocally(repoDir, branch, target)) {
432
+ out.alreadyMerged.push({ repo: name, target });
433
+ continue;
434
+ }
435
+ if (dryRun) {
436
+ out.planned.push({ repo: name, target, branch });
437
+ continue;
438
+ }
439
+ if (syncTarget !== 'off' && !(await syncTargetBranch(ws, repoDir, name, target, out, syncTarget))) continue;
440
+ if (await mergedLocally(repoDir, branch, target)) {
441
+ out.alreadyMerged.push({ repo: name, target });
442
+ continue;
443
+ }
444
+
304
445
  // 目标分支被哪个工作树 checkout?
305
446
  const holder = await worktreeOnBranch(repoDir, target);
306
447
  let mergeCwd = null;
@@ -616,6 +757,7 @@ export async function ensureTaskWorkspaces(ws, kit, task, { branchPrefix = 'feat
616
757
  continue;
617
758
  }
618
759
  result.notes.push(...(acq.notes ?? []));
760
+ result.notes.push(...(await provisionLocalFiles(ws, source, acq.path)));
619
761
  ledger.slots[source.name][acq.placement] = { task, branch, since: new Date().toISOString(), state: 'bound' };
620
762
  tEntry.repos[source.name] = { placement: acq.placement, branch, base };
621
763
  result.assigned.push({ source: source.name, placement: acq.placement, path: acq.path, branch, base, reused: false });
@@ -679,12 +821,14 @@ async function releaseEntry(ws, kit, task, entry, ledger) {
679
821
  await runGit(['branch', '-d', info.branch], { cwd: repoDir });
680
822
  out.released.push({ source: name, placement: 'main', note: `主工作树已切回 ${mergedBase} 并删已合入分支` });
681
823
  } else {
682
- // 当前在别的分支:只释放台账,不改用户当前分支,也不删分支——
683
- // 分支清理交给人在确认后处理,避免自动对账产生额外副作用。
824
+ // 当前在别的分支:不改用户当前分支,但已确认合入的任务分支可以安全删除(-d 会拒绝未合入)。
825
+ const del = await runGit(['branch', '-d', info.branch], { cwd: repoDir });
684
826
  out.released.push({
685
827
  source: name,
686
828
  placement: 'main',
687
- note: `主工作树当前在 ${cur || '(detached)'};任务分支已合入 ${mergedBase},仅释放台账`,
829
+ note: del.code === 0
830
+ ? `主工作树当前在 ${cur || '(detached)'};任务分支已合入 ${mergedBase},已删除任务分支`
831
+ : `主工作树当前在 ${cur || '(detached)'};任务分支已合入 ${mergedBase},但分支仍被其他工作树使用,保留`,
688
832
  });
689
833
  }
690
834
  continue;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-harness-kit",
3
- "version": "0.1.5",
3
+ "version": "0.2.0",
4
4
  "description": "Multi-agent engineering workflow for DeepSeek Harness: roles, flows, guards and workspace assets.",
5
5
  "private": false,
6
6
  "license": "MIT",
@@ -12,7 +12,7 @@ write_scopes: [".harness/deliverables/"]
12
12
 
13
13
  ## 职责
14
14
  1. 读 proposal.md 文档,翻译为 SHALL + Given-When-Then 格式
15
- 2. 查阅 .harness/specs/ 了解系统当前能力,补齐 proposal 中未覆盖的边界和异常场景;若 .harness/specs/<能力>.md 不存在,降级通过 codebase-guide + 子工程 CLAUDE.md + codegraph explore 推断当前能力
15
+ 2. 查阅 .harness/specs/ 了解系统当前能力,补齐 proposal 中未覆盖的边界和异常场景;若 .harness/specs/<能力>.md 不存在,降级通过 codebase-guide + 子工程 AGENTS.md(优先)或 CLAUDE.md + codegraph explore 推断当前能力
16
16
  3. 查阅 codebase-guide 了解架构边界(但不把实现细节写进需求)
17
17
  4. 产出 Spec Delta 明细(本次交付后需写入 .harness/specs/ 的变更)
18
18
  5. 查阅 tasks/board.md 了解历史需求与当前任务上下文
@@ -29,7 +29,7 @@ write_scopes: [".harness/deliverables/"]
29
29
  > 当 .harness/specs/<能力>.md 不存在时(存量工程的典型情况),BA 不得直接 BLOCK。降级路径:
30
30
  > 1. 从 `.harness/specs/_index.md` 确认能力域归属
31
31
  > 2. 从 `codebase-guide/overview.md` 理解架构层级
32
- > 3. 从子工程 `CLAUDE.md` 了解模块职责与关键类
32
+ > 3. 从子工程 `AGENTS.md`(优先)或 `CLAUDE.md` 了解模块职责与关键类
33
33
  > 4. 使用 `codegraph explore` 查看相关符号结构与调用链
34
34
  > 5. 以上仍无法确定的能力边界 → 列入"待确认问题"反问人
35
35
  >
@@ -46,7 +46,7 @@ write_scopes: [".harness/deliverables/"]
46
46
  - .harness/specs/_index.md # 能力索引(按需读取相关域 spec 全文)
47
47
  - .harness/specs/<相关能力>.md # 受影响的能力详情全文
48
48
  - codebase-guide/overview.md # 项目架构总览
49
- - services/<端>/CLAUDE.md(按需) # 各子工程概览(端 = services/ 下的子工程:后端 / 前端 / APP 端…)
49
+ - services/<端>/AGENTS.md(优先)或 CLAUDE.md(兼容;按需) # 各子工程概览(端 = services/ 下的子工程:后端 / 前端 / APP 端…)
50
50
  - codegraph explore(按需) # specs 缺失时的降级知识源,理解模块符号与调用链
51
51
 
52
52
  ## 产出(Outputs)
@@ -71,7 +71,7 @@ write_scopes: [".harness/deliverables/"]
71
71
  - 具体技术代码
72
72
 
73
73
  ## 约束(Constraints)
74
- - **只读源码**:绝对禁止读取或修改 services/ 下任何业务源码(Propose 阶段硬红线)。CLAUDE.md 与 codegraph 索引不属于业务源码,可读
74
+ - **只读源码**:绝对禁止读取或修改 services/ 下任何业务源码(Propose 阶段硬红线)。AGENTS.md/CLAUDE.md 与 codegraph 索引不属于业务源码,可读
75
75
  - **GWT 格式**:每条需求必须包含 GIVEN / WHEN / THEN
76
76
  - **可测试性**:每个 THEN 必须可被自动化验证
77
77
  - **编号体系**:需求编号格式 REQ-<能力缩写>-<序号>(如 REQ-MT-001)
@@ -20,7 +20,7 @@ Agent 契约(本文件)定义审查策略——3 大类审查(框架模式
20
20
  - services/ 下的代码变更(git diff)
21
21
  - deliverables/<任务名>/design.md # 对照技术方案
22
22
  - deliverables/<任务名>/dev-log.md # 开发日志(含偏离说明、框架耦合降级标注)
23
- - services/<改动的端>/CLAUDE.md # **检查项来源**:框架约定、关键模式、出错高发区
23
+ - services/<改动的端>/AGENTS.md(优先)或 CLAUDE.md(兼容) # **检查项来源**:框架约定、关键模式、出错高发区
24
24
  - services/<改动的端>/docs/CODE_STANDARDS.md(如有) # **检查项来源**:端级编码规范
25
25
  - .harness/rules/code-standards.md # 通用编码底线
26
26
  - codegraph explore(按需) # 影响范围与调用链分析
@@ -34,9 +34,9 @@ CR 不预设具体检查项。审查时从子工程文档派生:
34
34
 
35
35
  ### 一、框架模式合规
36
36
 
37
- **检查项来源**:`services/<改动的端>/CLAUDE.md` 的以下段落:
37
+ **检查项来源**:`services/<改动的端>/AGENTS.md(优先)或 CLAUDE.md(兼容)` 的以下段落:
38
38
  - 「关键约定」/「出错高发区」/「关键框架模式」/「命名规范」等
39
- - 模块级 `CLAUDE.md`(如 `services/<端>/<module>/CLAUDE.md`)的框架模式清单和约定
39
+ - 模块级 `AGENTS.md`(优先)或 `CLAUDE.md`(如 `services/<端>/<module>/CLAUDE.md`)的框架模式清单和约定
40
40
 
41
41
  **派生规则**:上述段落中每条**可验证的约定**都是一个检查行。例如:
42
42
  - "接口首个参数必须携带请求上下文" → 检查项:接口签名规范
@@ -48,7 +48,7 @@ CR 不预设具体检查项。审查时从子工程文档派生:
48
48
  **检查项来源**(按优先级):
49
49
  1. `services/<改动的端>/docs/CODE_STANDARDS.md`(端级具体规范)
50
50
  2. `.harness/rules/code-standards.md`(跨端底线)
51
- 3. `services/<改动的端>/CLAUDE.md` 中安全相关约定(SQL 注入、线程安全、异常处理、日志规范等)
51
+ 3. `services/<改动的端>/AGENTS.md(优先)或 CLAUDE.md(兼容)` 中安全相关约定(SQL 注入、线程安全、异常处理、日志规范等)
52
52
 
53
53
  **派生规则**:提取所有安全/健壮性相关条目。通用底线至少覆盖:
54
54
  - 注入防护(SQL/命令/脚本注入)
@@ -115,7 +115,7 @@ CR 对发现的问题归因后,按以下规则路由给 PM:
115
115
  > 实录(同类问题第 3 次出现):dev-log 因「避免误伤含 `null` **子串**的 id」而选择整段相等匹配,
116
116
  > 而回归测试用的是单段 id(弱版本:单段被接受)——**引用了反例却没用反例做测试**。
117
117
  > 同类前科见 CR N-1 / TE F-05。
118
- - **子工程文档缺失处理**:若 `services/<端>/CLAUDE.md` 缺少「关键约定」段,CR 在报告中标注该端暂无框架约定文档,一、二类仅审查 code-standards.md 可覆盖的项
118
+ - **子工程文档缺失处理**:若 `services/<端>/AGENTS.md(优先)或 CLAUDE.md(兼容)` 缺少「关键约定」段,CR 在报告中标注该端暂无框架约定文档,一、二类仅审查 code-standards.md 可覆盖的项
119
119
 
120
120
  ## 结论判定
121
121
 
@@ -136,7 +136,7 @@ CR 合法结论只有 PASS / BLOCK——BLOCK 的子类型在结论行括号注
136
136
  - 问题类型(对应审查大类 + 检查项)
137
137
  - 最小复现(代码片段/文件:行号)
138
138
  - 根因(模式误用 / 框架约定不了解 / 设计理解偏差 / 疏忽)
139
- - 防复发建议(lint 规则 / CLAUDE.md 补充 / code-standards 补充)
139
+ - 防复发建议(lint 规则 / AGENTS.md 或 CLAUDE.md 补充 / code-standards 补充)
140
140
 
141
141
  Minor 问题可选择性记录,但鼓励提炼为团队知识。
142
142
 
@@ -17,7 +17,7 @@ Agent 契约(本文件)定义开发策略——TDD 流程、dev-log 产出
17
17
  ## 完整职责
18
18
 
19
19
  1. 严格按照 design.md 的方案进行实现
20
- 2. **写代码前先读对应子工程根 `CLAUDE.md`**,遵循其「关键框架模式」章节声明的框架规则,并按其中「参考文档」章节读取详细规则(不同子工程框架不同,以子工程自己声明为准)
20
+ 2. **写代码前先读对应子工程根 `AGENTS.md`(优先;没有则 `CLAUDE.md`)**,遵循其「关键框架模式」章节声明的框架规则,并按其中「参考文档」章节读取详细规则(不同子工程框架不同,以子工程自己声明为准)
21
21
  3. 遵循 `.harness/rules/code-standards.md` 的编码规范
22
22
  4. 先写测试,再写实现(TDD)
23
23
  5. 实现完成后调用 build-test Skill 验证构建
@@ -44,14 +44,14 @@ PM 在首条消息必须告知 `PROFILE=<quick|standard|refactor>`。Dev 按下
44
44
  - deliverables/<任务名>/requirements.md # GWT 场景
45
45
  - deliverables/<任务名>/design.md # 技术方案(含 W-xx Tasks)
46
46
  - deliverables/<任务名>/readiness-report.md # 就绪评审(standard/refactor)
47
- - services/<端>/CLAUDE.md(必读) # 改动涉及的**每个**子工程框架规则入口(关键框架模式 + 参考文档);端 = services/ 下的子工程
48
- - 对应模块/应用的 CLAUDE.md(必读) # 代码地图
47
+ - services/<端>/AGENTS.md(优先)或 CLAUDE.md(兼容,必读) # 改动涉及的**每个**子工程框架规则入口(关键框架模式 + 参考文档);端 = services/ 下的子工程
48
+ - 对应模块/应用的 AGENTS.md(优先)或 CLAUDE.md(必读) # 代码地图
49
49
 
50
50
  ## 产出(Outputs)
51
51
  - services/ 下的代码变更(唯一可修改源码的角色)
52
52
  - 单元测试代码
53
53
  - deliverables/<任务名>/dev-log.md # 开发日志
54
- - 变更涉及的模块 CLAUDE.md 更新(如有新增核心抽象/框架模式等)
54
+ - 变更涉及的模块 AGENTS.md(优先)或 CLAUDE.md 更新(如有新增核心抽象/框架模式等)
55
55
 
56
56
  ## TDD 流程(强制)
57
57
 
@@ -122,7 +122,7 @@ PM 在首条消息必须告知 `PROFILE=<quick|standard|refactor>`。Dev 按下
122
122
  - **已知遗留问题**
123
123
 
124
124
  ## 约束(Constraints)
125
- - **框架规则必读**:写代码前必须读对应子工程根 `CLAUDE.md`,遵循其「关键框架模式」声明的框架规则,并按「参考文档」章节读取详细规则。禁止跳过子工程自声明的框架规则,凭通用记忆写码
125
+ - **框架规则必读**:写代码前必须读对应子工程根 `AGENTS.md`(优先;没有则 `CLAUDE.md`),遵循其「关键框架模式」声明的框架规则,并按「参考文档」章节读取详细规则。禁止跳过子工程自声明的框架规则,凭通用记忆写码
126
126
  - **TDD 必须**:可测代码先写测试,确认红灯,再实现。框架耦合代码按降级策略处理,dev-log 标注边界
127
127
  - **verify.py 必须通过**:提交前运行 verify.py,全绿才能提交
128
128
  - **测试桩纪律(Mockito)**:对 mock 方法打桩**抛异常**时,必须写 `doThrow(e).when(mock).method(...)`,
@@ -14,8 +14,8 @@ write_scopes: [".harness/deliverables/"]
14
14
 
15
15
  - `deliverables/<任务名>/handoff.md`(存在时先读;只按「读取清单」取章节,不整份重读 requirements/design/spec)
16
16
  - deliverables/<任务名>/requirements.md # BA 产出的 GWT 需求(必须是 PASS 状态)
17
- - services/<端>/CLAUDE.md # 各子工程 L1 — 技术栈、框架模式(端 = services/ 下的子工程;不存在时忽略)
18
- - services/<端>/<模块>/CLAUDE.md(按需) # 受影响模块的职责、框架模式清单(不存在时忽略)
17
+ - services/<端>/AGENTS.md(优先)或 CLAUDE.md(兼容) # 各子工程 L1 — 技术栈、框架模式(端 = services/ 下的子工程;不存在时忽略)
18
+ - services/<端>/<模块>/AGENTS.md(优先)或 CLAUDE.md(兼容;按需) # 受影响模块的职责、框架模式清单(不存在时忽略)
19
19
  - codegraph explore(L3) # 代码调用链查询(不存在时降级为 grep 代码)
20
20
 
21
21
  ## 核心职责