kenaz 0.3.5 → 0.3.7

package/core/.claude/commands/Ansuz.md

@@ -23,6 +23,7 @@ ARGUMENTS 含 `[專案: X]` 或 `--project-path X` → PROJECT_PATH = X，下方
 - 有**對照組**：證明測試在舊程式上會失敗，或修改前後結果不同。
 - subagent 回報「未驗證」的項目，由你補驗或明講仍未驗證。
 - 合併：`git merge` 後跑相關測試（或 `node .specialist/Ansuz/tools/verify-and-land.js`），用這個專案自己的測試指令。
+- 檔案長度：verify-and-land 合併前會跑 `check-file-size`（警告 1000 / 上限 2000 行，既有超長檔只擋「未配套拆分的增長」）；被擋就按職責拆成 module / component / hook。
 - 只在 Kenaz 核心 repo 本身：Rust 測試走 `npm run test:rust` / `dev/scripts/rust-verify-worktree.js`。
 
 ## 回報

package/core/.collaboration/core/reconcile.js

@@ -0,0 +1,193 @@
+'use strict';
+/**
+ * TASK_2404: close cards whose task branches already landed on <remote>/<base>
+ * (cross-node pool merge, external rebase+merge) without running post-complete.
+ *
+ * landed(card) = the card has >=1 task branch (local or remote task/<id>*, or card.branch)
+ * AND every one of them is an ancestor of <remote>/<base> AND each carries >=1 commit of its own
+ * (a freshly forked, still-empty branch is trivially an ancestor of base; it has landed nothing).
+ *
+ * Only local refs are read (the <remote>/<base> remote-tracking ref); nothing here fetches.
+ */
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const TELEMETRY = ['.kenaz/sessions', '.kenaz/specialist', '.formation/.dispatch-branch', '.formation/analytics', '.kenaz/channel_heartbeats.jsonl'];
+const LIVE_PIDLESS_MS = 3600000; // pid-less dispatch entries count as live for 60 min (DISPATCH_LOCK_STALE_MS)
+
+function git(cwd, args) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 64 * 1024 * 1024 }).trim();
+}
+function gitOk(cwd, args) { try { git(cwd, args); return true; } catch { return false; } }
+const norm = (p) => path.resolve(p).replace(/\\/g, '/').toLowerCase();
+const isTelemetry = (rel) => TELEMETRY.some((t) => rel === t || rel.startsWith(t + '/'));
+
+/** Remote-tracking base ref when present, else the local base branch (null when neither exists). */
+function resolveBaseRef(repo, remote, base) {
+  for (const ref of [`refs/remotes/${remote}/${base}`, `refs/heads/${base}`]) {
+    if (gitOk(repo, ['rev-parse', '--verify', '--quiet', ref])) return ref;
+  }
+  return null;
+}
+
+/** Branch refs of a card: local + remote task/<id>* plus card.branch. [{ref, name, sha}] */
+function findCardBranches(repo, card, remote) {
+  const idLower = String(card.id).toLowerCase();
+  const out = git(repo, ['for-each-ref', '--format=%(refname) %(objectname)', 'refs/heads/task', `refs/remotes/${remote}/task`]);
+  const prefixes = [`refs/heads/task/${idLower}`, `refs/remotes/${remote}/task/${idLower}`];
+  const found = [];
+  for (const line of out.split(/\r?\n/).filter(Boolean)) {
+    const [ref, sha] = line.split(' ');
+    // `task/task_12` must not match `task/task_123`: allow only a non-digit after the id.
+    if (prefixes.some((p) => ref === p || (ref.startsWith(p) && !/^\d/.test(ref.slice(p.length))))) found.push({ ref, sha });
+  }
+  if (card.branch) {
+    for (const ref of [`refs/heads/${card.branch}`, `refs/remotes/${remote}/${card.branch}`]) {
+      if (found.some((f) => f.ref === ref)) continue;
+      try { found.push({ ref, sha: git(repo, ['rev-parse', '--verify', '--quiet', ref]) }); } catch { /* absent */ }
+    }
+  }
+  return found.map((f) => ({ ...f, name: f.ref.replace(/^refs\/(heads|remotes\/[^/]+)\//, '') }));
+}
+
+/** True unless the LOCAL branch's reflog proves its tip is still its creation commit (no commits of its own). */
+function hasOwnCommits(repo, b) {
+  if (!b.ref.startsWith('refs/heads/')) return true; // remote-tracking refs carry no reflog
+  try {
+    const lines = git(repo, ['reflog', 'show', '--format=%H', b.ref]).split(/\r?\n/).filter(Boolean);
+    return !(lines.length > 0 && lines[lines.length - 1] === b.sha);
+  } catch { return true; }
+}
+
+/** First commit on base that contains `sha` (one ancestry-path walk); `sha` itself when nothing lies between. */
+function landingCommit(repo, baseRef, sha) {
+  try {
+    const first = git(repo, ['rev-list', '--reverse', '--ancestry-path', `${sha}..${baseRef}`]).split(/\r?\n/)[0];
+    return first || sha;
+  } catch { return null; }
+}
+
+/** @returns {{landed:boolean, branches:object[], landing:string|null, baseRef:string|null, reason?:string}} */
+function assessCard(repo, card, { remote = 'origin', base = 'main' } = {}) {
+  const baseRef = resolveBaseRef(repo, remote, base);
+  if (!baseRef) return { landed: false, branches: [], landing: null, baseRef, reason: `no ${remote}/${base} or ${base} ref` };
+  const branches = findCardBranches(repo, card, remote);
+  if (!branches.length) return { landed: false, branches, landing: null, baseRef, reason: 'no branch' };
+  let reason = null;
+  for (const br of branches) {
+    if (!gitOk(repo, ['merge-base', '--is-ancestor', br.sha, baseRef])) reason = `${br.name} is not an ancestor of base`;
+    else if (!hasOwnCommits(repo, br)) reason = `${br.name} has no commits beyond its fork point (fresh branch, nothing landed)`;
+    if (reason) break;
+  }
+  const landed = !reason;
+  return { landed, branches, landing: landed ? landingCommit(repo, baseRef, branches[0].sha) : null, baseRef, reason };
+}
+
+/** Why a landed card's worktree must be kept; null = safe to remove. */
+function worktreeKeepReason(repo, wt, card, baseRef, activeDispatches, now) {
+  if (!fs.existsSync(wt.path)) return 'path missing';
+  const p = norm(wt.path);
+  const cwd = norm(process.cwd());
+  if (cwd === p || cwd.startsWith(p + '/')) return 'current working directory is inside it';
+  if (wt.locked) return 'locked';
+  if (!wt.branch) return 'detached HEAD';
+  const live = (activeDispatches || []).some((d) => {
+    if (!((d.worktree_path && norm(d.worktree_path) === p) || d.taskId === card.id)) return false;
+    if (d.pid) { try { process.kill(d.pid, 0); return true; } catch (e) { return e.code === 'EPERM'; } }
+    return now - Date.parse(d.startedAt || 0) < LIVE_PIDLESS_MS;
+  });
+  if (live) return 'live dispatch/agent registered for it';
+  if (!gitOk(wt.path, ['merge-base', '--is-ancestor', 'HEAD', baseRef])) return 'HEAD is not an ancestor of base';
+  if (!hasOwnCommits(repo, { ref: `refs/heads/${wt.branch}`, sha: git(wt.path, ['rev-parse', 'HEAD']) })) return 'no commits beyond its fork point (fresh worktree)';
+  const dirty = git(wt.path, ['status', '--porcelain', '--untracked-files=no']).split(/\r?\n/).filter(Boolean)
+    .map((l) => l.slice(3).replace(/^"|"$/g, '')).filter((f) => !isTelemetry(f));
+  if (dirty.length) return `tracked tree dirty: ${dirty.slice(0, 3).join(', ')}`;
+  const stack = [wt.path];
+  while (stack.length) {
+    const dir = stack.pop();
+    let names; try { names = fs.readdirSync(dir); } catch { continue; }
+    for (const n of names) {
+      if (n === '.git') continue;
+      const f = path.join(dir, n);
+      let st; try { st = fs.lstatSync(f); } catch { continue; }
+      // a node_modules link is dispatch-managed and unlinked before removal; any other link blocks
+      if (st.isSymbolicLink()) { if (n !== 'node_modules') return `contains symlink/junction: ${path.relative(wt.path, f)}`; }
+      else if (st.isDirectory()) stack.push(f);
+    }
+  }
+  return null;
+}
+
+function removeWorktree(repo, wt) {
+  require('../../.formation/tools/utils').unlinkNodeModulesBestEffort(wt.path); // `worktree remove` must not traverse the junction
+  git(repo, ['worktree', 'remove', '--force', wt.path]);
+  try { git(repo, ['worktree', 'prune']); } catch { /* non-fatal */ }
+}
+
+const isKeepOpen = (c) => c.keep_open === true || c.keep_open === 'true';
+
+/**
+ * @param {TaskAPI} api
+ * @param {{remote?:string, base?:string, apply?:boolean, worktrees?:boolean, activeDispatches?:object[], now?:number, log?:Function}} opts
+ */
+async function reconcile(api, opts = {}) {
+  const { remote = 'origin', base = 'main', apply = false, worktrees = false } = opts;
+  const log = opts.log || console.log;
+  const repo = api._resolveProjectRoot();
+  const now = opts.now || Date.now();
+  const active = opts.activeDispatches || (() => { try { return require('../../.formation/tools/dispatch-registry').readActiveDispatches(); } catch { return []; } })();
+  const wtList = worktrees ? require('../../.formation/tools/worktree-reclaim').listRegisteredWorktrees(repo).worktrees : [];
+  const rows = [];
+  for (const card of await api.queryTasks({ status: 'active' })) {
+    const a = assessCard(repo, card, { remote, base });
+    const keepOpen = isKeepOpen(card);
+    const mine = wtList.filter((w) => w.branch && a.branches.some((b) => b.name === w.branch));
+    const row = { card: card.id, branches: a.branches.map((b) => b.name), landed: a.landed, landing: a.landing, keepOpen, worktrees: mine.map((w) => w.path), closed: false, notes: [] };
+    if (a.landed && !keepOpen && apply) {
+      await api.completeTask(card.id, { skipPostComplete: true, external: { landing_sha: a.landing, landed_into: a.baseRef.replace(/^refs\/(heads|remotes)\//, '') } });
+      row.closed = true;
+    }
+    if (worktrees) {
+      for (const w of mine) {
+        const why = !a.landed ? `card not landed: ${a.reason}` : keepOpen ? 'card is keep_open' : worktreeKeepReason(repo, w, card, a.baseRef, active, now);
+        if (why) row.notes.push(`KEEP ${w.path}: ${why}`);
+        else if (!apply) row.notes.push(`would remove ${w.path}`);
+        else { try { removeWorktree(repo, w); row.notes.push(`removed ${w.path}`); } catch (e) { row.notes.push(`KEEP ${w.path}: remove failed: ${String(e.message).split('\n')[0]}`); } }
+      }
+    }
+    rows.push(row);
+  }
+  log(`reconcile ${apply ? '(APPLY)' : '(dry-run)'} against ${remote}/${base}: ${rows.length} active card(s)`);
+  for (const r of rows) {
+    const state = r.landed ? (r.keepOpen ? 'landed (keep_open: kept open)' : (r.closed ? 'landed -> closed' : 'landed')) : 'not landed';
+    log(`${r.card}\t${state}\tbranches=${r.branches.join(',') || '-'}\tlanding=${r.landing ? r.landing.slice(0, 10) : '-'}\tworktree=${r.worktrees.join(',') || '-'}`);
+    for (const n of r.notes) log(`    ${n}`);
+  }
+  return rows;
+}
+
+/** The landed assessment, or null when not landed / not decidable (non-git dir, no base ref). */
+function landedAssessment(repo, card, opts) {
+  try { const a = assessCard(repo, card, opts); return a.landed ? a : null; } catch { return null; }
+}
+
+/** Local-only count (no fetch; remote-tracking refs) of active cards already landed and not keep_open. */
+function countLanded(repo, cards, opts) {
+  return cards.filter((c) => !isKeepOpen(c) && landedAssessment(repo, c, opts)).length;
+}
+
+/**
+ * Landed elsewhere = landed AND no registered worktree still has one of its branches checked out.
+ * A worktree on the branch means a local land just merged it (verify-and-land merges, then runs
+ * complete), so post-complete still has a delivery to read and complete must proceed.
+ */
+function externalLanding(repo, card, opts) {
+  const a = landedAssessment(repo, card, opts);
+  if (!a) return null;
+  const names = new Set(a.branches.map((b) => b.name));
+  const wts = require('../../.formation/tools/worktree-reclaim').listRegisteredWorktrees(repo).worktrees;
+  return wts.some((w) => w.branch && names.has(String(w.branch).replace(/^refs\/heads\//, ''))) ? null : a;
+}
+
+module.exports = { reconcile, assessCard, landedAssessment, externalLanding, countLanded };

package/core/.collaboration/core/task-2404-reconcile.test.js

@@ -0,0 +1,135 @@
+// TASK_2404 -- `task-api reconcile` + the plain-complete guard for externally landed cards.
+// Temp git repos under os.tmpdir() only (origin is a local bare repo; nothing fetches, no network).
+// Usage: node .collaboration/core/task-2404-reconcile.test.js
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const cp = require('child_process');
+
+// No network / no side processes: stub task-sync, the pool push (recorded) and the detached health capture.
+const syncPath = require.resolve('../../.formation/tools/task-sync');
+require.cache[syncPath] = { id: syncPath, filename: syncPath, loaded: true, exports: { syncTaskStatus: async () => ({}) } };
+const realSpawn = cp.spawn;
+cp.spawn = function (cmd, argv, opts) {
+  if (Array.isArray(argv) && argv.some(a => typeof a === 'string' && a.includes('const CFG'))) return { unref() {}, on() {} };
+  return realSpawn.apply(this, arguments);
+};
+const { TaskAPI, toYAML, setPoolStatusPush } = require('./task-api.js');
+const pushes = [];
+setPoolStatusPush({ pushPoolStatus: async (a) => { pushes.push(a.task && a.task.id); return { pushed: true }; } });
+
+const SB = fs.mkdtempSync(path.join(os.tmpdir(), 't2404_'));
+const ORIGIN = path.join(SB, 'origin.git');
+const REPO = path.join(SB, 'repo');
+const WT = path.join(SB, 'wts');
+const git = (cwd, ...a) => cp.execFileSync('git', a, { cwd, encoding: 'utf8', windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+let pass = 0, fail = 0;
+const check = (n, c, d) => { console.log((c ? 'PASS' : 'FAIL') + ' | ' + n + (c ? '' : ' | ' + d)); c ? pass++ : fail++; };
+const capture = async (fn) => { const lines = []; const rows = await fn((l) => lines.push(l)); return { rows, out: lines.join('\n') }; };
+
+function setup() {
+  fs.mkdirSync(ORIGIN, { recursive: true });
+  git(ORIGIN, 'init', '-q', '--bare', '-b', 'main');
+  fs.mkdirSync(REPO, { recursive: true });
+  git(REPO, 'init', '-q', '-b', 'main');
+  git(REPO, 'config', 'user.email', 't@example.com'); git(REPO, 'config', 'user.name', 't');
+  git(REPO, 'remote', 'add', 'origin', ORIGIN);
+  fs.writeFileSync(path.join(REPO, 'README.md'), 'base\n');
+  git(REPO, 'add', '-A'); git(REPO, 'commit', '-q', '-m', 'base');
+  git(REPO, 'push', '-q', 'origin', 'main');
+  for (const d of ['backlog', 'active', 'done', 'blocked', 'cancel', 'archived']) fs.mkdirSync(path.join(REPO, '.kenaz', 'tasks', d), { recursive: true });
+}
+// branch task/task_<n> with one commit, optionally in a worktree
+function mkBranch(n, { worktree = false } = {}) {
+  const b = `task/task_${n}`;
+  if (worktree) { fs.mkdirSync(WT, { recursive: true }); git(REPO, 'worktree', 'add', '-q', '-b', b, path.join(WT, `task_${n}`), 'main'); }
+  else git(REPO, 'branch', b, 'main');
+  const dir = worktree ? path.join(WT, `task_${n}`) : null;
+  const work = dir || REPO;
+  if (!dir) git(REPO, 'checkout', '-q', b);
+  fs.writeFileSync(path.join(work, `f${n}.txt`), `work ${n}\n`);
+  git(work, 'add', '-A'); git(work, 'commit', '-q', '-m', `[TASK_${n}] work`);
+  if (!dir) git(REPO, 'checkout', '-q', 'main');
+  return { branch: b, dir };
+}
+const mergeToOriginMain = (b) => { git(REPO, 'merge', '-q', '--no-ff', '-m', `merge ${b}`, b); git(REPO, 'push', '-q', 'origin', 'main'); };
+const card = (n, extra = {}) => fs.writeFileSync(path.join(REPO, '.kenaz', 'tasks', 'active', `TASK_${n}_t.yaml`),
+  toYAML({ id: `TASK_${n}`, title: `t${n}`, priority: 'P2', status: 'in_progress', ...extra }));
+const inDir = (n, d) => fs.readdirSync(path.join(REPO, '.kenaz', 'tasks', d)).some(f => f.startsWith(`TASK_${n}_`));
+
+(async () => {
+  try {
+    setup();
+    // A merged, B unmerged, C merged + keep_open; D clean landed worktree; E dirty landed worktree;
+    // F landed but a dispatch is live; G fresh worktree (no commits); H unmerged worktree
+    mkBranch(9001); mkBranch(9002); mkBranch(9003);
+    const D = mkBranch(9004, { worktree: true }), E = mkBranch(9005, { worktree: true }), F = mkBranch(9006, { worktree: true });
+    mkBranch(9008, { worktree: true });
+    fs.mkdirSync(WT, { recursive: true });
+    git(REPO, 'worktree', 'add', '-q', '-b', 'task/task_9007', path.join(WT, 'task_9007'), 'main'); // G: no commits
+    for (const n of [9001, 9003, 9004, 9005, 9006]) mergeToOriginMain(`task/task_${n}`);
+    fs.writeFileSync(path.join(E.dir, 'f9005.txt'), 'dirty edit\n'); // tracked + modified
+    for (const n of [9001, 9002]) card(n);
+    card(9003, { keep_open: true });
+
+    const api = new TaskAPI({ tasksDir: path.join(REPO, '.kenaz', 'tasks'), projectPath: REPO });
+
+    // dry-run
+    let r = await capture((log) => api.constructor && require('./reconcile').reconcile(api, { log }));
+    const row = (id) => r.rows.find(x => x.card === `TASK_${id}`);
+    check('dry-run: A landed', row(9001).landed === true && !!row(9001).landing, JSON.stringify(row(9001)));
+    check('dry-run: B not landed', row(9002).landed === false);
+    check('dry-run: C landed but kept open', row(9003).landed === true && row(9003).keepOpen === true && /keep_open/.test(r.out));
+    check('dry-run closes nothing', inDir(9001, 'active') && inDir(9003, 'active'));
+
+    // complete guard (new behavior): A refused, nothing written
+    let msg = null;
+    try { await api.completeTask('TASK_9001', {}); } catch (e) { msg = e.message; }
+    check('complete on landed card A is refused and points at reconcile', !!msg && /reconcile/.test(msg), msg);
+    check('refused complete left A active, wrote no outcome', inDir(9001, 'active') && !inDir(9001, 'done'));
+    // verify-and-land merges first, then runs complete while the task worktree still exists: not external
+    const { externalLanding, landedAssessment } = require('./reconcile');
+    const D4 = { id: 'TASK_9004' };
+    check('landed card with its worktree still present is not external (local land proceeds)',
+      !!landedAssessment(REPO, D4, {}) && externalLanding(REPO, D4, {}) === null);
+    check('landed card with no worktree is external', !!externalLanding(REPO, { id: 'TASK_9001' }, {}));
+
+    // --apply
+    pushes.length = 0;
+    r = await capture((log) => require('./reconcile').reconcile(api, { apply: true, log }));
+    check('apply closed A', inDir(9001, 'done') && !inDir(9001, 'active'));
+    check('apply left B active', inDir(9002, 'active'));
+    check('apply left keep_open C active', inDir(9003, 'active') && !inDir(9003, 'done'));
+    const doneFile = fs.readdirSync(path.join(REPO, '.kenaz', 'tasks', 'done')).find(f => f.startsWith('TASK_9001_'));
+    const doneTxt = fs.readFileSync(path.join(REPO, '.kenaz', 'tasks', 'done', doneFile), 'utf8');
+    const mainSha = git(REPO, 'rev-parse', 'origin/main');
+    const sha = (/^landing_sha:\s*(\w+)/m.exec(doneTxt) || [])[1];
+    check('A has integration: external', /^integration:\s*external\s*$/m.test(doneTxt), doneTxt);
+    check('A records the landing SHA (a commit on origin/main containing the branch)', !!sha && git(REPO, 'merge-base', '--is-ancestor', git(REPO, 'rev-parse', 'task/task_9001'), sha) === '' && git(REPO, 'merge-base', '--is-ancestor', sha, mainSha) === '', sha);
+    check('pool status pushed for the closed card', pushes.includes('TASK_9001'), JSON.stringify(pushes));
+
+    // worktree guards (dry-run first: nothing removed); these cards join after the first apply
+    for (const n of [9004, 9005, 9006, 9007, 9008]) card(n);
+    const live = [{ sessionId: 's', taskId: 'TASK_9006', worktree_path: F.dir, pid: process.pid, startedAt: new Date().toISOString() }];
+    r = await capture((log) => require('./reconcile').reconcile(api, { worktrees: true, activeDispatches: live, log }));
+    check('worktrees dry-run removes nothing', fs.existsSync(D.dir) && /would remove/.test(r.out));
+    r = await capture((log) => require('./reconcile').reconcile(api, { apply: true, worktrees: true, activeDispatches: live, log }));
+    check('landed clean worktree removed', !fs.existsSync(D.dir) && /removed .*task_9004/.test(r.out), r.out);
+    check('branch of removed worktree kept', git(REPO, 'branch', '--list', 'task/task_9004') !== '');
+    check('dirty worktree kept with reason', fs.existsSync(E.dir) && /KEEP .*task_9005: tracked tree dirty/.test(r.out), r.out);
+    check('live-dispatch worktree kept with reason', fs.existsSync(F.dir) && /KEEP .*task_9006: live dispatch/.test(r.out), r.out);
+    check('fresh worktree (no commits) kept with reason', fs.existsSync(path.join(WT, 'task_9007')) && /KEEP .*task_9007: .*no commits beyond its fork point/.test(r.out), r.out);
+    check('unlanded worktree kept with reason', fs.existsSync(path.join(WT, 'task_9008')) && /KEEP .*task_9008: card not landed/.test(r.out), r.out);
+
+    // boot-banner count is local-only and counts landed non-keep_open active cards
+    const n = require('./reconcile').countLanded(REPO, [{ id: 'TASK_9005' }, { id: 'TASK_9002' }, { id: 'TASK_9003', keep_open: true }], {});
+    check('countLanded: 1 (9005 landed; 9002 not; 9003 keep_open)', n === 1, String(n));
+  } catch (e) {
+    check('no exception', false, e && e.stack);
+  } finally {
+    cp.spawn = realSpawn;
+    try { fs.rmSync(SB, { recursive: true, force: true }); } catch { /* best effort */ }
+  }
+  console.log(`\n${pass} passed, ${fail} failed`);
+  process.exit(fail ? 1 : 0);
+})();

package/core/.collaboration/core/task-api.js

@@ -2094,6 +2094,17 @@ class TaskAPI {
       throw new Error(`無法從 backlog 直接完成 ${taskId}: move it to active first (node task-api.js move ${taskId} active), then complete.`);
     }
 
+    // TASK_2404: a card whose task branch is already an ancestor of <remote>/<base> landed elsewhere
+    // (cross-node pool, external rebase+merge). Full complete would run post-complete on a tree with
+    // nothing to deliver and write an empty-delivery outcome, so refuse and point at `reconcile`.
+    // Paths that never run post-complete (--skip-post-complete, reconcile --apply) are unaffected.
+    if (!options.skipPostComplete && !options.external) {
+      const landed = require('./reconcile').externalLanding(this._resolveProjectRoot(), task, {});
+      if (landed) {
+        throw new Error(`${taskId}: branch ${landed.branches.map(b => b.name).join(', ')} already landed on ${landed.baseRef.replace(/^refs\/(heads|remotes)\//, '')} (${String(landed.landing).slice(0, 10)}); a full complete would record an empty delivery. Run: node .collaboration/core/task-api.js reconcile --apply (or complete ${taskId} --skip-post-complete).`);
+      }
+    }
+
     const updatedTask = {
       ...task,
       executed_by: {
@@ -2103,6 +2114,13 @@ class TaskAPI {
       }
     };
 
+    // TASK_2404: externally landed card (reconcile): record how and where it landed
+    if (options.external) {
+      updatedTask.integration = 'external';
+      updatedTask.landing_sha = options.external.landing_sha || null;
+      updatedTask.landed_into = options.external.landed_into || null;
+    }
+
     // 設置實際工時（如果提供）
     if (options.actual_hours !== undefined) {
       updatedTask.actual_hours = options.actual_hours;
@@ -2682,6 +2700,7 @@ Commands:
     預設為整組取代（會回顯被移除的既有項目）；加 --append 改為追加到既有項目之後（與既有重複的項目會略過並回顯）
   node task-api.js claim TASK_ID
   node task-api.js complete TASK_ID [--actual-hours HOURS]
+  node task-api.js reconcile [--remote origin] [--base main] [--apply] [--worktrees]   關閉分支已併入 base 的 active 任務（預設 dry-run）
   node task-api.js move TASK_ID STATUS [--force]
   node task-api.js delete TASK_ID              (僅限 backlog 狀態)
   node task-api.js search KEYWORD
@@ -2768,7 +2787,14 @@ Create 選項:
 
       const command = args[0];
 
-      if (command === 'worktrees') {
+      if (command === 'reconcile') {
+        // TASK_2404: close active cards whose branches already landed on <remote>/<base>
+        const argOf = (n, d) => { const i = args.indexOf(n); return i >= 0 && args[i + 1] && !args[i + 1].startsWith('--') ? args[i + 1] : d; };
+        await require('./reconcile').reconcile(api, {
+          remote: argOf('--remote', 'origin'), base: argOf('--base', 'main'),
+          apply: args.includes('--apply'), worktrees: args.includes('--worktrees'),
+        });
+      } else if (command === 'worktrees') {
         // TASK_2297: list worktrees with reclaim eligibility; --reclaim removes eligible ones (manual path).
         const wr = require(path.join(__dirname, '..', '..', '.formation', 'tools', 'worktree-reclaim.js'));
         const wtRepo = path.resolve(cliProjectPath || process.cwd());

package/core/.formation/native/claude/README.md

@@ -51,7 +51,7 @@ no surprise dependencies.
 4. When the user picks an entry, the id is written into
    `.kenaz/dashboard-models.json` via
    `POST /api/dashboard/settings/models` and consumed by
-   `kenaz_dispatch` / `SpecialistPanel.handleLaunch`.
+   `SpecialistPanel.handleLaunch`.
 
 ## Adding a new model
 

package/core/.formation/role-map.yaml

@@ -3,8 +3,8 @@
 # Amelia 判斷 role 時參考此表，dispatch 時用此表解析 --role 路徑
 #
 # Usage:
-#   node .formation/tools/headless-v2.js --base=do --role=developer --task=TASK_XXX
-#   headless-v2 會查此表找到 skill_path → 載入該 YAML 的 role context
+#   node .formation/tools/dispatch.js --skill=do --task=TASK_XXX --dispatch-mode=subagent
+#   （此表僅供 Amelia 判斷 role 參考；dispatch.js 不讀取它。headless-v2 已退役）
 
 version: "2.0"
 
@@ -259,7 +259,7 @@ roles:
       - 新功能開發
 
 # ─────────────────────────────────────────
-# Base Skills（headless-v2 的 --base 選項）
+# Base Skills（歷史：原 headless-v2 的 --base 選項）
 # ─────────────────────────────────────────
 
 bases:

package/core/.formation/spec/task_operations.yaml

@@ -4,7 +4,7 @@
 #
 # Consumers:
 #   A: .collaboration/core/task-api.js       — full lifecycle (create/claim/complete/move/delete/get/list)
-#   B: .formation/tools/headless.js          — dispatch coordinator (no direct state mutation; triggers post-complete)
+#   B: .formation/tools/dispatch.js          — dispatch coordinator (no direct state mutation; triggers post-complete)
 #   C: .formation/tools/post-complete.js     — close-out only (active→done or active→blocked; never creates)
 #   D: dashboard kenaz MCP tools (kenaz.rs)  — CRUD subset only (list/get/create/update/delete via task-api CLI proxy)
 #
@@ -13,7 +13,7 @@
 #   MCP does NOT have standalone claim, complete, or move tools — these are action values in tool_task_update.
 #   task-api.js (consumer A) owns the full state machine and all lifecycle transitions.
 #   post-complete.js (consumer C) is exclusively close-out; it calls task-api complete/move internally.
-#   headless.js (consumer B) coordinates dispatch and triggers post-complete on task completion.
+#   dispatch.js (consumer B) coordinates dispatch and triggers post-complete on task completion.
 #
 # STATUS DUALITY (known divergence):
 #   Filesystem directory names (canonical): backlog, active, done, blocked, cancel, archived
@@ -153,7 +153,7 @@ operations:
     post_complete_trigger: true
     known_asymmetry:
       - "moveTask(taskId, 'done') achieves same filesystem effect but does NOT trigger post-complete"
-      - "Consumer B (headless.js) bypasses via FORMATION_HEADLESS=1 and calls post-complete separately"
+      - "Consumer B (dispatch.js) does not mutate task state itself; post-complete runs separately"
     error_modes:
       - "Task not found → throws"
       - "post-complete failure → logged as warning; task already moved to done (non-atomic)"

package/core/.formation/tools/__tests__/subagent-bifrost-guard.test.js

@@ -95,8 +95,8 @@ setModels({ dispatchModel: 'gpt-5-codex', dispatchFamily: 'bifrost', dispatchAda
   check('reject bifrost+adapter: no agentParams on stdout', !(r.stdout || '').includes('agentParams'), (r.stdout || '').slice(0, 200));
   check('reject bifrost+adapter: invariant wording (refusing to silently dispatch)',
     (r.stderr || '').includes('refusing to silently dispatch with the native Claude CLI'), (r.stderr || '').slice(-400));
-  check('reject bifrost+adapter: remediation points to Formation dispatch (kenaz_dispatch)',
-    (r.stderr || '').includes('kenaz_dispatch'), (r.stderr || '').slice(-400));
+  check('reject bifrost+adapter: remediation tells the user to pick a Claude model',
+    (r.stderr || '').includes('Select a Claude model') && !(r.stderr || '').includes('kenaz_dispatch'), (r.stderr || '').slice(-400));
 }
 
 // ── [3] reject: dispatchFamily=bifrost, adapter missing/empty ───────────────
@@ -175,8 +175,8 @@ setModels({ dispatchModel: 'claude-nova-9', dispatchFamily: 'claude' });
   check('unmappable model: loud stderr (refusing to silently guess)',
     (r.stderr || '').includes("dispatchModel 'claude-nova-9' cannot be mapped") &&
     (r.stderr || '').includes('refusing to silently guess'), (r.stderr || '').slice(-400));
-  check('unmappable model: remediation points to Formation dispatch (kenaz_dispatch)',
-    (r.stderr || '').includes('kenaz_dispatch'), (r.stderr || '').slice(-400));
+  check('unmappable model: remediation points at the model selection, not retired kenaz_dispatch',
+    (r.stderr || '').includes('Fix the model selection') && !(r.stderr || '').includes('kenaz_dispatch'), (r.stderr || '').slice(-400));
 }
 
 // ── [9]-[11] TASK_2032: subagent dispatch activates the card like the ────────

package/core/.formation/tools/dispatch.js

@@ -990,14 +990,14 @@ async function getSubagentDispatchParams(options) {
   }
   if (routing.family === 'bifrost' && !isCodex) {
     if (!routing.adapter) {
-      console.error('❌ dashboard-models.json sets dispatchFamily=bifrost but dispatchAdapter is missing/empty — refusing to silently dispatch with the native Claude CLI. Fix the model selection (Quick Actions → Default Models) or dashboard-models.json, then use Formation dispatch (kenaz_dispatch).');
+      console.error('❌ dashboard-models.json sets dispatchFamily=bifrost but dispatchAdapter is missing/empty — refusing to silently dispatch with the native Claude CLI. Fix the model selection (Quick Actions → Default Models) or dashboard-models.json.');
     } else {
-      console.error(`❌ dashboard-models.json sets dispatchFamily=bifrost (dispatchAdapter '${routing.adapter}') — sub-agent dispatch cannot run non-Claude models (the Agent tool only accepts Claude models); refusing to silently dispatch with the native Claude CLI. Use Formation dispatch (kenaz_dispatch) instead — it routes through the Bifrost adapter.`);
+      console.error(`❌ dashboard-models.json sets dispatchFamily=bifrost (dispatchAdapter '${routing.adapter}') — sub-agent dispatch cannot run non-Claude models (the Agent tool only accepts Claude models); refusing to silently dispatch with the native Claude CLI. Select a Claude model in Default Models.`);
     }
     return null;
   }
   if (!isCodex && routing.family && routing.family !== 'claude') {
-    console.error(`❌ dashboard-models.json sets unsupported dispatchFamily '${routing.family}' (expected 'claude' or 'bifrost') — refusing to silently dispatch with the native Claude CLI. Fix the model selection (Quick Actions → Default Models) or use Formation dispatch (kenaz_dispatch).`);
+    console.error(`❌ dashboard-models.json sets unsupported dispatchFamily '${routing.family}' (expected 'claude' or 'bifrost') — refusing to silently dispatch with the native Claude CLI. Fix the model selection (Quick Actions → Default Models).`);
     return null;
   }
 
@@ -1017,7 +1017,7 @@ async function getSubagentDispatchParams(options) {
   // TASK_2315: Codex inherits the session model — nothing to translate or pass.
   const translated = isCodex ? { model: null, lossless: true } : translateModelForAgentTool(rawModel);
   if (!isCodex && !translated.model) {
-    console.error(`❌ ${resolution.label} '${rawModel}' cannot be mapped to an Agent tool model family (${AGENT_TOOL_MODEL_ENUM.join('|')}) — refusing to silently guess a substitute model. Fix the model selection (Quick Actions → Default Models) or use Formation dispatch (kenaz_dispatch), which accepts full model ids via --dispatch-model.`);
+    console.error(`❌ ${resolution.label} '${rawModel}' cannot be mapped to an Agent tool model family (${AGENT_TOOL_MODEL_ENUM.join('|')}) — refusing to silently guess a substitute model. Fix the model selection (Quick Actions → Default Models).`);
     return null;
   }
   const dispatchModel = translated.model;
@@ -1025,7 +1025,7 @@ async function getSubagentDispatchParams(options) {
     ? { requested: rawModel, inherited: true }
     : { requested: rawModel, agentToolModel: dispatchModel, granularityLoss: !translated.lossless };
   if (!translated.lossless) {
-    process.stderr.write(`[dispatch] model '${rawModel}' → Agent tool family '${dispatchModel}' — the Agent tool only expresses family names (${AGENT_TOOL_MODEL_ENUM.join('|')}); version/speed selections (e.g. 5 vs 4.x, [1m]) are NOT expressible on the subagent path. If the exact version matters, use Formation dispatch (kenaz_dispatch), which passes full model ids.\n`);
+    process.stderr.write(`[dispatch] model '${rawModel}' → Agent tool family '${dispatchModel}' — the Agent tool only expresses family names (${AGENT_TOOL_MODEL_ENUM.join('|')}); version/speed selections (e.g. 5 vs 4.x, [1m]) are NOT expressible on the subagent path. If the exact version matters, choose a model whose family the Agent tool can express.\n`);
   }
   // TASK_1998 R3 (+ two-axis policy): the resolved choice, always printed
   // (unlike the granularity block above, which only fires on lossy translation).

package/core/.formation/tools/prompt.js

@@ -171,6 +171,10 @@ function buildSubagentPrompt(skillDef, taskInput, taskData, options = {}) {
   // Ponytail A/B 2026-10-10: the arm without this line broke an existing fixture test it never ran.
   lines.push('Before editing, grep the callers, tests and fixtures your change reaches; fix what it breaks. Least code that completes the card: reuse existing helpers, no unrequested abstraction, option or duplicate implementation.');
   lines.push('Run the tests the card names (narrow, not the full suite); say what you did not verify.');
+  // The worktree branches off the project's current branch; user projects are not always on `main`.
+  const sizeBase = (require('child_process').spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: options.projectPath || process.cwd(), encoding: 'utf8' }).stdout || '').trim() || 'main';
+  const sizeCorePath = options.corePath || resolveCorePath(options.projectPath) || path.resolve(__dirname, '..', '..');
+  lines.push(`Before reporting run \`node ${sizeCorePath}/dev/scripts/check-file-size.js --base ${sizeBase} --head HEAD\`; if it BLOCKs, split by responsibility (module / component / hook) first.`);
   const onBlocked = skillDef.collaboration && skillDef.collaboration.on_blocked;
   if (onBlocked && onBlocked.run) {
     lines.push(`Blocked: \`${buildTaskApiRewriter(options)(onBlocked.run).replace(/\{task_id\}/g, taskId)}\` and explain.`);

package/core/.formation/unit/do.yaml

@@ -48,10 +48,8 @@ collaboration:
         - 根據 acceptance_criteria 驗證成果
       # TASK_1819: 此處原有的 worktree_path_rule 欄位已移除 — 它是死欄位，
       # prompt.js 的 appendWorkflow 只讀 step/run/note/actions，從未渲染它，
-      # 且其範例路徑早已過時。實際生效的 worktree 路徑規則由 runner.js 在
-      # spawn 時注入（spawnClaude/spawnBifrost 的 "[WORKTREE] All file
-      # operations MUST use paths under: <worktreeDir>" 前綴，含具體路徑），
-      # Agent-tool 派工另由 prompt.js SUBAGENT_PREFIX 規則 11 覆蓋。
+      # 且其範例路徑早已過時。實際生效的 worktree 路徑規則由
+      # prompt.js SUBAGENT_PREFIX 規則 11 覆蓋（原 runner.js 注入已隨 headless 路徑移除）。
 
     # 注意（TASK_1819）：下方 run 的 git add -A 只會在隔離模式（worktree /
     # subagent）原樣渲染；serial 共用工作樹模式下 prompt.js appendWorkflow

package/core/.rule/general/agent-workflow.yaml

@@ -543,15 +543,15 @@ rules:
   - id: "AGT-010"
     title: "Dispatch 後切回 User Branch"
     description: |
-      Formation headless.js dispatch 會在獨立進程中建立 task branch（task/task_XXX），
+      （已退役）Formation headless dispatch 曾在獨立進程中建立 task branch（task/task_XXX），
       完成後 post-complete.js 會 merge 回 user branch。但呼叫者（Ansuz/Agent）的
       working tree 仍停留在 task branch 上。
 
       如果 dispatch 後繼續在同一 session 做其他改動，會意外 commit 到 task branch，
       而不是 user branch。用戶在桌面端會看到 branch 不一致。
     severity: "must"
-    rationale: "headless.js 是獨立進程，不會切換呼叫者的 git working tree"
-    trigger: "Formation dispatch（headless.js）完成後，Ansuz 或 Agent 要做下一個改動之前"
+    rationale: "headless dispatch 是獨立進程（已退役，僅供歷史參照），不會切換呼叫者的 git working tree"
+    trigger: "legacy Formation dispatch 完成後，Ansuz 或 Agent 要做下一個改動之前"
     workflow:
       - step: 1
         action: "確認 dispatch 完成（task status = completed）"
@@ -568,5 +568,5 @@ rules:
       ❌ 多個 task 共用同一個 task branch（每個 task 應有自己的 branch）
     applies_to:
       - "Ansuz（PM dispatch 後繼續做其他工作）"
-      - "任何使用 headless.js 的 Agent"
+      - "任何仍經 legacy Formation dispatch 的 Agent"
       - "用戶手動 dispatch 後"

package/core/.rule/general/file-size-threshold.yaml

@@ -9,8 +9,8 @@ rules:
       Single-file growth is the primary vector for SRP violations in this codebase.
       Enforce line-count thresholds to force extraction before files become unmaintainable.
     thresholds:
-      warn: 2000
-      hard_limit: 4000
+      warn: 1000
+      hard_limit: 2000
     scope:
       include:
         - "**/*.rs"
@@ -22,20 +22,32 @@ rules:
         - "**/target/**"
         - "**/node_modules/**"
         - "**/*.test.*"
+        - "**/*_test.*"
+        - "**/tests/**"
+        - "**/__tests__/**"
+        - "**/*.generated.*"
         - "**/*.spec.*"
         - "**/*.d.ts"
         - "**/generated/**"
     enforcement:
       on_task_design: |
-        When designing a task that adds >50 LOC to a file already above warn threshold (2000 lines):
+        When designing a task that adds >50 LOC to a file already above warn threshold (1000 lines):
         1. Check current file size (wc -l or kenaz_lsp_symbols)
         2. If file > warn: acceptance criteria MUST include "extract [new responsibility] into separate module"
         3. If file > hard_limit: task MUST be split — one task for extraction, one for the new feature
         Ansuz must enforce this at task design time, not defer to the implementing agent.
       on_code_review: |
-        Any PR that increases a file past hard_limit (4000 lines) without a paired extraction
+        Any PR that increases a file past hard_limit (2000 lines) without a paired extraction
         commit is a Blocker-level review finding.
       existing_debt: |
+        Decision 2026-10-10 (user, via Ansuz): warn 1000 / hard_limit 2000 lines for source
+        files; tests and generated files are excluded. Existing over-limit files are
+        GRANDFATHERED: dev/scripts/check-file-size.js only blocks growth of such a file (>50 LOC)
+        without a paired extraction (a new file in the same change), or a file newly crossing
+        hard_limit. Split by responsibility (module / component / hook) when you touch one.
+        Enforced in verify-and-land.js (file-size step, before merge) and the subagent
+        "Verify and report" prompt line. Without this yaml (user project) the script uses the
+        same defaults built in.
         Files currently above hard_limit are tracked as architecture debt.
         Extraction tasks should be created incrementally — do not attempt big-bang refactors.
         Follow the three-stage pattern: build-map → plan-split → minimal-patch.

package/core/.rule/general/rust-verify-target.yaml

@@ -33,7 +33,6 @@ rules:
       file: "dev/scripts/verify-target-dir.js"
       consumers:
         - "dev/scripts/run-rust-tests.js (defaults CARGO_TARGET_DIR when unset)"
-        - ".formation/tools/runner.js (worktree dispatch env, 2 call sites)"
         - ".formation/tools/integration.js (in-lock re-verify env)"
       shell_usage: "CARGO_TARGET_DIR=$(node dev/scripts/verify-target-dir.js) cargo check --lib -p kenaz-dashboard"