@cyning/harness 2.6.0 → 2.8.0

package/lib/cli.js

@@ -41,7 +41,8 @@ function usage(version = 'unknown') {
   npx @cyning/harness check [--target PATH]
   npx @cyning/harness audit [--target PATH] [--task FILE]
   npx @cyning/harness gate-check [--target PATH] [--task FILE] [--graph] [--json]
-  npx @cyning/harness verify [--target PATH] [--task FILE] [--graph] [--json] [--agent-hint] [--workspace-root PATH]
+  npx @cyning/harness verify [--target PATH] [--task FILE | --spec FILE] [--graph] [--json] [--agent-hint] [--workspace-root PATH]
+  npx @cyning/harness lifecycle show [--json]
   npx @cyning/harness sync index [--target PATH]
   npx @cyning/harness task check --file PATH [--no-circular] [--registry DIR]...
   npx @cyning/harness task close --file PATH [--target PATH] [--yes] [--allow-unchecked]
@@ -61,7 +62,8 @@ function usage(version = 'unknown') {
   check       读 manifest.json · 对比当前包版本是否有可升级版本
   audit       ICVO 机械审计：复用 gate-check · D5 测试声明检查 · S5 git-clean 提醒
   gate-check  调用 wizard/gate-check.sh（业务仓无需 clone 即可用）
-  verify      30 前聚合：gate-check + audit D5 + S5 warn + 可选 --graph
+  verify      30 前聚合（--task）或 SPEC→00 审查文闸（--spec · v2.8+）
+  lifecycle   只读展示 harness/lifecycle.yaml（状态/转移/守卫 · v2.7+）
   sync index  生成 .cyning-harness/invoke_index.json
   task check  校验 task.harness.v1.json sidecar · --no-circular 检测 depends_on 环
   task close  受闸归档：5 项机械校验（invoke/自检结论/勾选/slug/状态）后 mv active→done（v2.2+）
@@ -128,6 +130,10 @@ export async function runCli(argv) {
     await cmdVerify(rest);
     return;
   }
+  if (cmd === 'lifecycle') {
+    await cmdLifecycle(rest);
+    return;
+  }
   if (cmd === 'sync') {
     await cmdSync(rest);
     return;
@@ -384,15 +390,21 @@ async function cmdGateCheck(args) {
 
 async function cmdVerify(args) {
   // D3 · implemented in lib/verify.js
-  const { verifyTarget, buildVerifyHandoff, formatAgentHint } = await import('./verify.js');
+  const {
+    verifyTarget,
+    verifySpecTarget,
+    buildVerifyHandoff,
+    buildSpecVerifyHandoff,
+    formatAgentHint,
+  } = await import('./verify.js');
   if (args.includes('--help') || args.includes('-h')) {
-    console.log(`用法: npx @cyning/harness verify [--target PATH] [--task FILE] [--graph] [--json] [--agent-hint] [--workspace-root PATH]
+    console.log(`用法: npx @cyning/harness verify [--target PATH] [--task FILE | --spec FILE] [--graph] [--json] [--agent-hint] [--workspace-root PATH] [--allow-no-review] [--allow-lint-fail] [--allow-no-spec-review]
 
-无 --task 时：扫描 docs/tasks/active/task_*.md 并逐项列出闸表（同 gate-check）。
-任一 task 阻塞则 VERIFY: BLOCKED · exit 2；全部可 30 则 VERIFY: PASS。
---json：输出 Agent handoff JSON（may_start_30 · entry_invoke_30 · review_path 等）。
---agent-hint：人类可读 handoff 摘要（可与 --json 同用）。
---workspace-root：解析 task 中 Projects/ 前缀的 entry_invoke 路径。
+无 --task/--spec：扫描 docs/tasks/active/task_*.md 并逐项列出闸表（同 gate-check）；不跑 task lint。
+--task：30 前聚合（gate + audit + reviews + lint WARN）· --allow-no-review / --allow-lint-fail。
+--spec：SPEC→00 前查审查文存在性（v2.8+ · 与 --task 互斥）· --allow-no-spec-review。
+  推荐：--spec <产品仓 SPEC> --workspace-root <含 docs/harness/reviews 的工作区根>
+--json / --agent-hint：Agent handoff。
 `);
     return;
   }
@@ -402,13 +414,25 @@ async function cmdVerify(args) {
   rest = r1;
   const { value: taskFile, rest: r2 } = takeOption(rest, '--task');
   rest = r2;
-  const { value: workspaceRoot, rest: r3 } = takeOption(rest, '--workspace-root');
+  const { value: specFile, rest: r3 } = takeOption(rest, '--spec');
   rest = r3;
+  const { value: workspaceRoot, rest: r4 } = takeOption(rest, '--workspace-root');
+  rest = r4;
   const graph = rest.includes('--graph');
   const json = rest.includes('--json');
   const agentHint = rest.includes('--agent-hint');
   const allowNoReview = rest.includes('--allow-no-review');
-  rest = rest.filter((a) => a !== '--graph' && a !== '--json' && a !== '--agent-hint' && a !== '--allow-no-review');
+  const allowLintFail = rest.includes('--allow-lint-fail');
+  const allowNoSpecReview = rest.includes('--allow-no-spec-review');
+  rest = rest.filter(
+    (a) =>
+      a !== '--graph' &&
+      a !== '--json' &&
+      a !== '--agent-hint' &&
+      a !== '--allow-no-review' &&
+      a !== '--allow-lint-fail' &&
+      a !== '--allow-no-spec-review',
+  );
 
   if (rest.length > 0) {
     const err = new Error(`verify 未知参数: ${rest.join(' ')}`);
@@ -416,8 +440,37 @@ async function cmdVerify(args) {
     throw err;
   }
 
+  if (taskFile && specFile) {
+    const err = new Error('verify：--task 与 --spec 互斥');
+    err.exitCode = 1;
+    throw err;
+  }
+
   const target = resolveTarget(process.cwd(), targetArg);
-  const result = verifyTarget(target, { taskFile, graph, allowNoReview });
+  const ws = workspaceRoot ? path.resolve(workspaceRoot) : undefined;
+
+  let result;
+  let handoff;
+  let label;
+
+  if (specFile) {
+    result = verifySpecTarget(target, { specFile, workspaceRoot: ws, allowNoSpecReview });
+    handoff = buildSpecVerifyHandoff(target, {
+      specFile,
+      workspaceRoot: ws,
+      allowNoSpecReview,
+    });
+    label = path.basename(specFile);
+  } else {
+    result = verifyTarget(target, { taskFile, graph, allowNoReview, allowLintFail });
+    handoff = buildVerifyHandoff(target, {
+      taskFile,
+      workspaceRoot: ws,
+      allowNoReview,
+      allowLintFail,
+    });
+    label = taskFile ? path.basename(taskFile) : null;
+  }
 
   // forward gate-check/audit/graph stdout if any（--json 时仍透传机械闸表）
   if (result.stdout && !json) {
@@ -427,12 +480,6 @@ async function cmdVerify(args) {
     process.stderr.write(result.stdout);
   }
 
-  const handoff = buildVerifyHandoff(target, {
-    taskFile,
-    workspaceRoot: workspaceRoot ? path.resolve(workspaceRoot) : undefined,
-    allowNoReview,
-  });
-
   if (json) {
     console.log(JSON.stringify(handoff, null, 2));
   }
@@ -440,15 +487,13 @@ async function cmdVerify(args) {
     console.log(formatAgentHint(handoff));
   }
 
+  const summary = label
+    ? `VERIFY: ${result.ok ? 'PASS' : 'BLOCKED'}${result.reason ? ` · ${result.reason}` : ''} · ${label}`
+    : `VERIFY: ${result.ok ? 'PASS' : 'BLOCKED'}${result.reason ? ` · ${result.reason}` : ''}`;
+
   if (!json && !agentHint) {
-    const summary = taskFile
-      ? `VERIFY: ${result.ok ? 'PASS' : 'BLOCKED'}${result.reason ? ` · ${result.reason}` : ''} · ${path.basename(taskFile)}`
-      : `VERIFY: ${result.ok ? 'PASS' : 'BLOCKED'}${result.reason ? ` · ${result.reason}` : ''}`;
     console.log(summary);
   } else if (json || agentHint) {
-    const summary = taskFile
-      ? `VERIFY: ${result.ok ? 'PASS' : 'BLOCKED'}${result.reason ? ` · ${result.reason}` : ''} · ${path.basename(taskFile)}`
-      : `VERIFY: ${result.ok ? 'PASS' : 'BLOCKED'}${result.reason ? ` · ${result.reason}` : ''}`;
     console.error(summary);
   }
 
@@ -458,6 +503,37 @@ async function cmdVerify(args) {
   }
 }
 
+async function cmdLifecycle(args) {
+  const { loadLifecycle, formatLifecycleShow } = await import('./lifecycle.js');
+  const [sub, ...rest] = args;
+  if (!sub || sub === '--help' || sub === '-h' || args.includes('--help') || args.includes('-h')) {
+    console.log(`用法: npx @cyning/harness lifecycle show [--json]
+
+只读展示产品包 harness/lifecycle.yaml（状态 / 转移 / 守卫登记）。
+不做转移执行、不写盘（方向二文档先行 · v2.7+）。
+`);
+    return;
+  }
+  if (sub !== 'show') {
+    const err = new Error(`lifecycle 子命令未知: ${sub}\n用法: lifecycle show [--json]`);
+    err.exitCode = 1;
+    throw err;
+  }
+  const json = rest.includes('--json');
+  const unknown = rest.filter((a) => a !== '--json');
+  if (unknown.length > 0) {
+    const err = new Error(`lifecycle show 未知参数: ${unknown.join(' ')}`);
+    err.exitCode = 1;
+    throw err;
+  }
+  const { data } = loadLifecycle();
+  if (json) {
+    console.log(JSON.stringify(data, null, 2));
+  } else {
+    console.log(formatLifecycleShow(data));
+  }
+}
+
 async function cmdSync(args) {
   if (args.includes('--help') || args.includes('-h')) {
     console.log(`用法: npx @cyning/harness sync index [--target PATH]`);

package/lib/lifecycle.js

@@ -0,0 +1,121 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { resolveHarnessRoot } from './paths.js';
+
+const SEVERITIES = new Set(['block', 'warn']);
+
+/**
+ * 轻量结构校验（不引入 Ajv）：对齐 schema/lifecycle.v1.schema.json 必填约束。
+ * @returns {{ ok: boolean, errors: string[] }}
+ */
+export function validateLifecycle(data) {
+  const errors = [];
+  if (!data || typeof data !== 'object') {
+    return { ok: false, errors: ['lifecycle 根须为 object'] };
+  }
+  if (typeof data.version !== 'string' || !data.version.trim()) {
+    errors.push('缺 version（string）');
+  }
+  if (!Array.isArray(data.states) || data.states.length === 0) {
+    errors.push('缺 states[] 或为空');
+  } else {
+    data.states.forEach((s, i) => {
+      if (!s || typeof s.id !== 'string' || !s.id.trim()) {
+        errors.push(`states[${i}] 缺 id`);
+      }
+    });
+  }
+  if (!Array.isArray(data.transitions) || data.transitions.length === 0) {
+    errors.push('缺 transitions[] 或为空');
+  } else {
+    data.transitions.forEach((t, i) => {
+      if (!t || typeof t.id !== 'string' || !t.id.trim()) {
+        errors.push(`transitions[${i}] 缺 id`);
+      }
+      if (!Array.isArray(t?.from) || t.from.length === 0) {
+        errors.push(`transitions[${i}] 缺 from[]`);
+      }
+      if (typeof t?.to !== 'string' || !t.to.trim()) {
+        errors.push(`transitions[${i}] 缺 to`);
+      }
+      if (!Array.isArray(t?.guards)) {
+        errors.push(`transitions[${i}] 缺 guards[]`);
+      } else {
+        t.guards.forEach((g, j) => {
+          if (!g || typeof g.id !== 'string') {
+            errors.push(`transitions[${i}].guards[${j}] 缺 id`);
+          }
+          if (!g || typeof g.command_or_check !== 'string') {
+            errors.push(`transitions[${i}].guards[${j}] 缺 command_or_check`);
+          }
+          if (!g || !SEVERITIES.has(g.severity)) {
+            errors.push(
+              `transitions[${i}].guards[${j}] severity 须为 block|warn（当前: ${g?.severity}）`,
+            );
+          }
+        });
+      }
+    });
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * 加载并校验 lifecycle.yaml。
+ * @param {{ harnessRoot?: string, filePath?: string }} [options]
+ */
+export function loadLifecycle(options = {}) {
+  const harnessRoot = options.harnessRoot ?? resolveHarnessRoot();
+  const filePath =
+    options.filePath ?? path.join(harnessRoot, 'harness', 'lifecycle.yaml');
+
+  if (!fs.existsSync(filePath)) {
+    const e = new Error(`lifecycle.yaml 不存在: ${filePath}`);
+    e.exitCode = 1;
+    throw e;
+  }
+
+  let data;
+  try {
+    data = yaml.load(fs.readFileSync(filePath, 'utf8'));
+  } catch (err) {
+    const e = new Error(`lifecycle.yaml 解析失败: ${err.message}`);
+    e.exitCode = 1;
+    throw e;
+  }
+
+  const v = validateLifecycle(data);
+  if (!v.ok) {
+    const e = new Error(`lifecycle.yaml 校验失败:\n  - ${v.errors.join('\n  - ')}`);
+    e.exitCode = 1;
+    e.validationErrors = v.errors;
+    throw e;
+  }
+
+  return { data, filePath, harnessRoot };
+}
+
+/**
+ * 人读表。
+ */
+export function formatLifecycleShow(data) {
+  const lines = [
+    `lifecycle v${data.version}`,
+    '',
+    '## states',
+    ...data.states.map((s) => `- ${s.id}${s.note ? ` · ${s.note}` : ''}`),
+    '',
+    '## transitions',
+  ];
+  for (const t of data.transitions) {
+    lines.push(`### ${t.id} · ${t.from.join('|')} → ${t.to}${t.hat ? ` · hat=${t.hat}` : ''}`);
+    if (t.description) lines.push(`  ${t.description}`);
+    for (const g of t.guards) {
+      const allow = g.allow_flag ? ` · allow=${g.allow_flag}` : '';
+      lines.push(`  - [${g.severity}] ${g.id}: ${g.command_or_check}${allow}`);
+    }
+    lines.push('');
+  }
+  return lines.join('\n').trimEnd();
+}

package/lib/task-meta.js

@@ -157,6 +157,107 @@ export function findReviewPath(target, taskFile) {
   return findReview(target, taskFile).latest;
 }
 
+/** 剥离文件名末尾 `_v\d+` */
+function stripVerSuffix(s) {
+  return String(s).replace(/_v\d+$/, '');
+}
+
+/**
+ * 自 SPEC 路径/正文解析 slug（优先表 `spec_slug`）。
+ */
+export function extractSpecSlug(specFile, content) {
+  const meta = content ? parseHarnessMeta(content) : {};
+  if (meta.spec_slug) return meta.spec_slug;
+
+  let base = path.basename(specFile, '.md');
+  base = base.replace(/^SPEC[-_]/i, '');
+  base = stripVerSuffix(base);
+  return base;
+}
+
+/**
+ * bugfix / 显式跳过 10-spec 审计：不要求 SPEC 审查文。
+ * 只认元信息表 / 文首 track 行——避免命中正文里对规则的说明文字。
+ */
+export function shouldSkipSpecAudit(content) {
+  if (!content) return false;
+  const meta = parseHarnessMeta(content);
+  if (String(meta.skip_spec_audit || '').toLowerCase() === 'true') return true;
+  if (String(meta.track || '').toLowerCase() === 'bugfix') return true;
+  if (/^>\s*\*\*track\*\*[：:]\s*`?bugfix\b/im.test(content)) return true;
+  return false;
+}
+
+/**
+ * 查找 SPEC 的 R<n> 审查文（verify --spec · N3）。
+ * 兼容命名：
+ * 1. spec_<slug>_audit_R<n>_*.md（推荐）
+ * 2. spec_<slug>_ACCEPT_R<n>_*.md
+ * 3. task_<slug>_spec_ACCEPT_R<n>_*.md
+ * 在 target 与可选 workspaceRoot 的 docs/harness/reviews/ 下搜索。
+ */
+export function findSpecReview(specFile, options = {}) {
+  const { target = process.cwd(), workspaceRoot } = options;
+  const empty = { found: false, latest: null, rounds: [], matched_pattern: null };
+
+  const absSpec = path.isAbsolute(specFile)
+    ? specFile
+    : path.resolve(target, specFile);
+  if (!fs.existsSync(absSpec)) return empty;
+
+  const content = fs.readFileSync(absSpec, 'utf8');
+  const slugNorm = normalizeSlug(stripVerSuffix(extractSpecSlug(absSpec, content)));
+
+  const roots = [];
+  const pushRoot = (root) => {
+    if (!root) return;
+    const abs = path.resolve(root);
+    if (!roots.includes(abs)) roots.push(abs);
+  };
+  pushRoot(target);
+  pushRoot(workspaceRoot);
+
+  const PATTERNS = [
+    { id: 'spec_audit', re: /^spec_(.+?)_audit_R(\d+)_.*\.md$/i },
+    { id: 'spec_ACCEPT', re: /^spec_(.+?)_ACCEPT_R(\d+)_.*\.md$/i },
+    { id: 'task_spec_ACCEPT', re: /^task_(.+?)_spec_ACCEPT_R(\d+)_.*\.md$/i },
+  ];
+
+  const matches = [];
+  for (const root of roots) {
+    const reviewsDir = path.join(root, 'docs/harness/reviews');
+    if (!fs.existsSync(reviewsDir)) continue;
+    for (const name of fs.readdirSync(reviewsDir)) {
+      for (const pat of PATTERNS) {
+        const m = name.match(pat.re);
+        if (!m) continue;
+        if (normalizeSlug(stripVerSuffix(m[1])) !== slugNorm) continue;
+        matches.push({
+          name,
+          round: parseInt(m[2], 10),
+          mtime: fs.statSync(path.join(reviewsDir, name)).mtimeMs,
+          pattern: pat.id,
+          root,
+          rel: path.join('docs/harness/reviews', name).replace(/\\/g, '/'),
+        });
+        break;
+      }
+    }
+  }
+
+  if (matches.length === 0) return empty;
+
+  matches.sort((a, b) => b.round - a.round || b.mtime - a.mtime);
+  const latest = matches[0];
+  return {
+    found: true,
+    latest: latest.rel,
+    rounds: [...new Set(matches.map((x) => x.round))].sort((a, b) => a - b),
+    matched_pattern: latest.pattern,
+    reviews_root: latest.root,
+  };
+}
+
 /**
  * 聚合单 task 的 Agent handoff 结果。
  */

package/lib/verify.js

@@ -3,13 +3,22 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { resolveHarnessRootForTarget, wizardScript } from './paths.js';
 import { auditTarget } from './audit.js';
-import { buildTaskHandoff, findReview, listActiveTasks } from './task-meta.js';
+import {
+  buildTaskHandoff,
+  extractSpecSlug,
+  findReview,
+  findSpecReview,
+  listActiveTasks,
+  shouldSkipSpecAudit,
+} from './task-meta.js';
+import { lintTaskFile } from './task-lint.js';
 
 /**
- * 30 前聚合验证：gate-check + audit D5（仅 --task）+ reviews 留档闸（仅 --task）+ S5 git-clean warn + 可选 --graph
+ * 30 前聚合验证：gate-check + audit D5（仅 --task）+ reviews 留档闸（仅 --task）
+ * + task lint WARN（仅 --task · v2.7+）+ S5 git-clean warn + 可选 --graph
  */
 export function verifyTarget(target, options = {}) {
-  const { taskFile, graph, allowNoReview = false } = options;
+  const { taskFile, graph, allowNoReview = false, allowLintFail = false } = options;
   const harnessRoot = resolveHarnessRootForTarget(target);
 
   // 1. gate-check（含 --graph）
@@ -49,12 +58,22 @@ export function verifyTarget(target, options = {}) {
         };
       }
     }
+
+    // 3b. task lint（N2 · v2.7+）：severity=warn · 不改 exit / may_start_30
+    const lint = runTaskLintForVerify(target, taskFile);
+    if (!lint.ok) {
+      if (allowLintFail) {
+        gateResult.stdout += `WARN: task lint FAIL suppressed（--allow-lint-fail · 留痕）\n`;
+      } else {
+        const rules = lint.errors.map((e) => e.rule).join(',');
+        gateResult.stdout += `WARN: task lint FAIL · ${rules || 'errors'}（不挡 may_start_30 · 修结构或 --allow-lint-fail）\n`;
+      }
+    }
   }
 
   // 4. S5 git-clean：warn 不挡
   const gitResult = runGitCleanCheck(target);
   if (gitResult.dirty) {
-    // 把 warn 拼到 stdout 里让 CLI 透传
     const warn = `WARN: 工作区未 clean（S5）：建议 commit 后再执行 apply\n`;
     gateResult.stdout += warn;
   }
@@ -66,6 +85,129 @@ export function verifyTarget(target, options = {}) {
   };
 }
 
+function runTaskLintForVerify(target, taskFile) {
+  try {
+    return lintTaskFile(taskFile, { cwd: target });
+  } catch (err) {
+    return {
+      ok: false,
+      errors: [{ rule: 'E_IO', message: err.message }],
+      warnings: [],
+    };
+  }
+}
+
+/**
+ * SPEC→00 前验证（N3 · v2.8+）：仅查 SPEC 审查文存在性。
+ * 不跑 gate-check / audit D5 / task lint（与 --task 模式分离）。
+ */
+export function verifySpecTarget(target, options = {}) {
+  const { specFile, workspaceRoot, allowNoSpecReview = false } = options;
+  let stdout = '';
+
+  if (!specFile) {
+    return {
+      ok: false,
+      exitCode: 1,
+      reason: 'verify --spec 须指定 SPEC 文件路径',
+      stdout,
+    };
+  }
+
+  const absSpec = path.isAbsolute(specFile)
+    ? specFile
+    : path.resolve(target, specFile);
+  if (!fs.existsSync(absSpec)) {
+    return {
+      ok: false,
+      exitCode: 1,
+      reason: `SPEC 文件不存在: ${specFile}`,
+      stdout,
+    };
+  }
+
+  const content = fs.readFileSync(absSpec, 'utf8');
+  if (shouldSkipSpecAudit(content)) {
+    stdout += `INFO: skip SPEC review gate（bugfix / skip_spec_audit）\n`;
+    return { ok: true, exitCode: 0, stdout, skipped: true };
+  }
+
+  const review = findSpecReview(absSpec, { target, workspaceRoot });
+  if (!review.found) {
+    if (allowNoSpecReview) {
+      stdout += `WARN: missing SPEC R<n> review（--allow-no-spec-review 豁免 · 留痕）\n`;
+      return { ok: true, exitCode: 0, stdout, skipped: false };
+    }
+    return {
+      ok: false,
+      exitCode: 2,
+      reason:
+        'missing SPEC R<n> review（docs/harness/reviews/ 无 spec_*_audit_R / *_ACCEPT_R · 20-spec-audit 或 --allow-no-spec-review）',
+      stdout,
+    };
+  }
+
+  return { ok: true, exitCode: 0, stdout, skipped: false };
+}
+
+/** SPEC 模式 handoff（verify --spec --json） */
+export function buildSpecVerifyHandoff(target, options = {}) {
+  const { specFile, workspaceRoot, allowNoSpecReview = false } = options;
+  const absSpec = path.isAbsolute(specFile)
+    ? specFile
+    : path.resolve(target, specFile);
+  const content = fs.existsSync(absSpec) ? fs.readFileSync(absSpec, 'utf8') : '';
+  const skipped = shouldSkipSpecAudit(content);
+  const review = skipped
+    ? { found: false, latest: null, rounds: [], matched_pattern: null }
+    : findSpecReview(absSpec, { target, workspaceRoot });
+
+  const reviewOk = skipped || review.found || allowNoSpecReview;
+  let blocked_reason = null;
+  if (!reviewOk) {
+    blocked_reason = 'missing SPEC R<n> review';
+  }
+
+  return {
+    schema_version: '1',
+    mode: 'spec',
+    verify_ok: reviewOk,
+    may_start_00: reviewOk,
+    spec: path.basename(specFile),
+    spec_path: specFile.replace(/\\/g, '/'),
+    spec_slug: content ? extractSpecSlug(absSpec, content) : null,
+    spec_review_found: Boolean(review.found),
+    spec_review_latest: review.latest,
+    spec_review_rounds: review.rounds ?? [],
+    spec_review_skipped: skipped,
+    spec_review_suppressed: Boolean(allowNoSpecReview && !review.found && !skipped),
+    matched_pattern: review.matched_pattern ?? null,
+    blocked_reason,
+    next_hat: reviewOk ? '00' : null,
+  };
+}
+
+/** 规范化 lint 结果供 handoff */
+export function lintSnapshotForHandoff(target, taskFile, { allowLintFail = false } = {}) {
+  if (!taskFile) return null;
+  let result;
+  try {
+    result = lintTaskFile(taskFile, { cwd: target });
+  } catch (err) {
+    result = {
+      ok: false,
+      errors: [{ rule: 'E_IO', message: err.message }],
+      warnings: [],
+    };
+  }
+  return {
+    ok: result.ok,
+    errors: result.errors ?? [],
+    warnings: result.warnings ?? [],
+    suppressed: Boolean(allowLintFail && !result.ok),
+  };
+}
+
 function runGateCheck(target, taskFile, graph, harnessRoot) {
   const script = wizardScript(harnessRoot, 'gate-check.sh');
   const args = [script, '--target', target];
@@ -171,13 +313,14 @@ function runGitCleanCheck(target) {
  * 构建 verify --json / --agent-hint 的 Agent handoff 载荷。
  */
 export function buildVerifyHandoff(target, options = {}) {
-  const { taskFile, workspaceRoot, allowNoReview = false } = options;
+  const { taskFile, workspaceRoot, allowNoReview = false, allowLintFail = false } = options;
   const handoffOpts = { workspaceRoot };
 
   if (taskFile) {
     const handoff = buildTaskHandoff(target, taskFile, handoffOpts);
     const reviewOk = handoff.review_found || allowNoReview;
     const verifyOk = handoff.may_start_30 && reviewOk;
+    const lint = lintSnapshotForHandoff(target, taskFile, { allowLintFail });
     return {
       schema_version: '1',
       verify_ok: verifyOk,
@@ -185,6 +328,7 @@ export function buildVerifyHandoff(target, options = {}) {
       may_start_30: verifyOk,
       blocked_reason: handoff.blocked_reason ?? (reviewOk ? null : 'missing R<n> review'),
       next_hat: verifyOk ? '30' : null,
+      lint,
     };
   }
 
@@ -212,6 +356,16 @@ export function buildVerifyHandoff(target, options = {}) {
 export function formatAgentHint(payload) {
   const lines = ['=== Harness verify · agent-hint ==='];
 
+  if (payload.mode === 'spec') {
+    lines.push(`spec: ${payload.spec}`);
+    lines.push(`  may_start_00: ${payload.may_start_00}`);
+    if (payload.blocked_reason) lines.push(`  blocked: ${payload.blocked_reason}`);
+    if (payload.spec_review_latest) lines.push(`  review: ${payload.spec_review_latest}`);
+    if (payload.spec_review_skipped) lines.push(`  review: skipped`);
+    if (payload.next_hat) lines.push(`  next_hat: ${payload.next_hat}`);
+    return lines.join('\n').trimEnd();
+  }
+
   const items = payload.tasks ?? [payload];
   for (const item of items) {
     lines.push(`task: ${item.task}`);
@@ -231,6 +385,11 @@ export function formatAgentHint(payload) {
     if (item.next_hat) {
       lines.push(`  next_hat: ${item.next_hat}`);
     }
+    if (item.lint) {
+      const n = item.lint.errors?.length ?? 0;
+      const tag = item.lint.suppressed ? 'suppressed' : item.lint.ok ? 'ok' : `FAIL(${n})`;
+      lines.push(`  lint: ${tag}`);
+    }
     for (const w of item.warnings ?? []) {
       lines.push(`  warn: ${w}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyning/harness",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "description": "cyning-harness discipline package · init / upgrade / check CLI",
   "license": "MIT",
   "type": "module",