@hunter-harness/workflow-harness 0.3.1 → 0.4.1

package/harness/bundles/general/pi/harness-test/scripts/runtime-helpers.mjs

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+// runtime-helpers.mjs — BOM-safe JSON I/O + test-identifier sanitizer + runner payload validation + credential scan.
+// 变更簇 5 (spec §3.4): BOM-safe Runner, identifier sanitizer, 凭据边界.
+//
+// 设计目标:
+//  - readJsonUtf8BomSafe: 容忍 UTF-8 BOM (U+FEFF), credential-cache.json 等文件可能被 PS5.1 写入 BOM
+//  - writeJsonUtf8NoBom: 原子写 (temp+rename), UTF-8 no BOM, LF — 结果/报告文件字节稳定
+//  - sanitizeTestIdentifier: 按 pattern/maxLength/prefix 生成稳定标识; 超长截断 + 原文名短 hash 防碰撞
+//  - validateRunnerPayload: Runner 生成前本地校验 payload schema/必填/identifier, 测试脚本错误不得请求服务后才发现
+//  - findCredentialValues: 扫描 profile/Markdown/docs 中的凭据明文值 (sensitive-info-protocol §1)
+//
+// Node ≥18 ESM, stdlib only. 输出 JSON 内容确定性 (不含 Math.random); 仅临时文件名用 randomBytes.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const BOM = 0xfeff;
+export const DEFAULT_IDENTIFIER_PATTERN = '^[A-Za-z][A-Za-z0-9_-]*$';
+export const DEFAULT_IDENTIFIER_MAX_LENGTH = 64;
+const HASH_LEN = 8;
+
+// ---------------------------------------------------------------------------
+// BOM-safe JSON I/O
+// ---------------------------------------------------------------------------
+
+/** Strip a single leading UTF-8 BOM (U+FEFF) from text. No-op if absent. */
+export function stripBom(text) {
+  return text.codePointAt(0) === BOM ? text.slice(1) : text;
+}
+
+/** Read a JSON file, tolerating a leading UTF-8 BOM. Throws on invalid JSON. */
+export function readJsonUtf8BomSafe(filePath) {
+  const raw = fs.readFileSync(filePath, 'utf8');
+  return JSON.parse(stripBom(raw));
+}
+
+/** Atomically write JSON as UTF-8 (no BOM), LF, 2-space indent, trailing newline.
+ *  Writes to a temp file then renames — readers never see a half-written file. */
+export function writeJsonUtf8NoBom(filePath, value) {
+  const json = JSON.stringify(value, null, 2) + '\n';
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = `${filePath}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`;
+  fs.writeFileSync(tmp, json, 'utf8');
+  try {
+    fs.renameSync(tmp, filePath);
+  } catch (err) {
+    try {
+      fs.unlinkSync(tmp);
+    } catch {
+      /* best-effort cleanup */
+    }
+    throw err;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// sanitizeTestIdentifier
+// ---------------------------------------------------------------------------
+
+/**
+ * Sanitize a change/test name into a stable identifier matching the default
+ * pattern `^[A-Za-z][A-Za-z0-9_-]*$`.
+ *
+ * - runs of chars outside [A-Za-z0-9_-] → '_'
+ * - prepend `prefix_` when prefix given; ensure leading letter (prepend 'T')
+ * - if over maxLength: truncate and append a short sha256 hash of the ORIGINAL
+ *   name, so two near-identical long names that collide after truncation stay
+ *   distinct (UT-023). Hash is deterministic — no Math.random.
+ *
+ * @returns {string} identifier matching the default pattern, length ≤ maxLength.
+ */
+export function sanitizeTestIdentifier({
+  name,
+  pattern = DEFAULT_IDENTIFIER_PATTERN,
+  maxLength = DEFAULT_IDENTIFIER_MAX_LENGTH,
+  prefix = '',
+}) {
+  const raw = String(name ?? '');
+  let base = prefix ? `${prefix}_` : '';
+  base += raw.replace(/[^A-Za-z0-9_-]+/g, '_');
+  // leading letter (pattern ^[A-Za-z]); prepend 'T' if first char is _ or digit
+  if (!/^[A-Za-z]/.test(base)) base = `T${base}`;
+  if (base.length <= maxLength) return base;
+  const hash = crypto.createHash('sha256').update(raw, 'utf8').digest('hex').slice(0, HASH_LEN);
+  const reserve = HASH_LEN + 1; // '_' + hash
+  const cap = Math.max(1, maxLength - reserve);
+  let truncated = base.slice(0, cap).replace(/_+$/, '');
+  // if truncation removed the leading letter guarantee, restore it
+  if (!/^[A-Za-z]/.test(truncated)) truncated = `T${truncated}`;
+  return `${truncated}_${hash}`;
+}
+
+/** Compile a pattern safely; returns null if invalid. */
+function safeRegex(pattern) {
+  try {
+    return new RegExp(`^(?:${pattern})$`);
+  } catch {
+    return null;
+  }
+}
+
+/** True if id matches pattern. Invalid pattern → false. */
+export function matchesPattern(id, pattern = DEFAULT_IDENTIFIER_PATTERN) {
+  const re = safeRegex(pattern);
+  return re ? re.test(String(id)) : false;
+}
+
+// ---------------------------------------------------------------------------
+// validateRunnerPayload — Runner 生成前本地校验
+// ---------------------------------------------------------------------------
+
+const HTTP_METHODS = /^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)$/i;
+
+/**
+ * Validate a runner payload (array of API test scenarios) BEFORE generating or
+ * executing the runner. Catches script/schema errors locally so they don't
+ * surface only after a service request (spec §3.4 point 3).
+ *
+ * Scenario required fields: id, method, url. id must match identifierPattern
+ * and be unique. method must be a known HTTP method.
+ *
+ * @returns {{ ok: boolean, errors: Array<{code: string, field: string, message: string}> }}
+ */
+export function validateRunnerPayload(payload, opts = {}) {
+  const errors = [];
+  const pattern = opts.identifierPattern || DEFAULT_IDENTIFIER_PATTERN;
+  const re = safeRegex(pattern);
+
+  if (!Array.isArray(payload)) {
+    return {
+      ok: false,
+      errors: [{ code: 'PAYLOAD_NOT_ARRAY', field: 'payload', message: 'payload must be an array of scenarios' }],
+    };
+  }
+  if (payload.length === 0) {
+    errors.push({ code: 'PAYLOAD_EMPTY', field: 'payload', message: 'payload has no scenarios' });
+  }
+
+  const seenIds = new Set();
+  payload.forEach((scn, i) => {
+    const where = `scenarios[${i}]`;
+    if (!scn || typeof scn !== 'object' || Array.isArray(scn)) {
+      errors.push({ code: 'SCENARIO_NOT_OBJECT', field: where, message: 'scenario must be an object' });
+      return;
+    }
+    for (const f of ['id', 'method', 'url']) {
+      if (scn[f] === undefined || scn[f] === null || scn[f] === '') {
+        errors.push({ code: 'MISSING_FIELD', field: `${where}.${f}`, message: `required field '${f}' missing or empty` });
+      }
+    }
+    if (scn.id !== undefined && scn.id !== null && scn.id !== '') {
+      const idStr = String(scn.id);
+      if (re && !re.test(idStr)) {
+        errors.push({ code: 'INVALID_IDENTIFIER', field: `${where}.id`, message: `id '${idStr}' does not match pattern ${pattern}` });
+      }
+      if (seenIds.has(idStr)) {
+        errors.push({ code: 'DUPLICATE_ID', field: `${where}.id`, message: `duplicate id '${idStr}'` });
+      } else {
+        seenIds.add(idStr);
+      }
+    }
+    if (scn.method !== undefined && scn.method !== null && scn.method !== '') {
+      if (!HTTP_METHODS.test(String(scn.method))) {
+        errors.push({ code: 'INVALID_METHOD', field: `${where}.method`, message: `unknown HTTP method '${scn.method}'` });
+      }
+    }
+  });
+
+  return { ok: errors.length === 0, errors };
+}
+
+// ---------------------------------------------------------------------------
+// findCredentialValues — 凭据明文扫描 (sensitive-info-protocol §1)
+// ---------------------------------------------------------------------------
+
+// 值占位符或 env 引用 (不会被当作凭据明文): <*_REDACTED> / ${ENV} / $ENV
+// 前缀匹配 ${ENV (无需闭合 }) — value 正则在 } 处停止, 仍应识别为 env 引用。
+const SAFE_VALUE = /<\w+_REDACTED>|\$\{[A-Z0-9_]+|\$[A-Z][A-Z0-9_]*\b/;
+
+const CRED_PATTERNS = [
+  // password / passwd / pwd = 或 : 后跟值 (字段名可带 JSON/YAML 引号)
+  { code: 'PASSWORD_VALUE', re: /"?password"?\s*[:=]\s*(['"]?)([^'"\s,;)}\n]+)\1/i, group: 2 },
+  // token / access_token / api_key / apikey / secret / accessKey / secretAccessKey
+  { code: 'SECRET_VALUE', re: /(?:"?(?:access_token|apikey|api_key|secretAccessKey|accessKey|secret|token)"?)\s*[:=]\s*(['"]?)([^'"\s,;)}\n]+)\1/i, group: 2 },
+  // Authorization: Bearer <jwt-ish>
+  { code: 'AUTH_HEADER', re: /Authorization\s*:\s*Bearer\s+([A-Za-z0-9_.-]{10,})/i, group: 1 },
+  // jdbc url with password=
+  { code: 'DB_PASSWORD', re: /jdbc:[^\s?]*[?&]password=([^&\s]+)/i, group: 1 },
+];
+
+/**
+ * Scan text for credential VALUES per sensitive-info-protocol §1.
+ * Placeholders (`<TOKEN_REDACTED>`) and env refs (`${DB_PASSWORD}` / `$DB_PASSWORD`)
+ * are NOT flagged — credential config may carry env keys, not values (spec §3.4 point 4).
+ *
+ * @returns {Array<{ line: number, code: string, snippet: string }>}
+ */
+export function findCredentialValues(text) {
+  const findings = [];
+  const lines = String(text ?? '').split(/\r?\n/);
+  lines.forEach((line, idx) => {
+    for (const { code, re, group } of CRED_PATTERNS) {
+      const m = line.match(re);
+      if (!m) continue;
+      const value = m[group] || '';
+      if (SAFE_VALUE.test(value)) continue; // placeholder / env ref — safe
+      // Redact the captured credential value in the snippet so reports/logs
+      // never leak it; field name + line number remain for locating the finding.
+      const snippet = (value ? line.replace(value, '<REDACTED>') : line).trim().slice(0, 80);
+      findings.push({ line: idx + 1, code, snippet });
+    }
+  });
+  return findings;
+}

package/harness/bundles/general/pi/protocols/archive-report-protocol.md

@@ -0,0 +1,196 @@
+---
+description: harness-archive 的结构化归档与 summary-data 校验协议。用于减少重复产物、提升数据准确性和平台展示一致性。
+---
+
+# Archive Report Protocol
+
+## 原则
+
+归档不应维护与平台重复的展示文件。常规入口是 `harness_archive.py execute`：它一次性完成状态采集与自动门禁，再复用预检结果调用 finalize。finalize 执行 cleanup → **freeze（事件 cutoff）** → collect → source consistency → summary validate → archive-meta。模型仅通过 events 写入维护结论。`meta/archive-meta.md` 由 finalize 生成，禁止手写。历史 archive 回放用 `harness_archive.py replay`（只读，不写 archive-meta / 不跑 cleanup）。
+
+`knownRisks` 仅收录 severity∈{warning,error,critical} 的 issue 事件；无 severity 的 issue 进入 `maintenanceNotes`。`finalStatusReasons` 解释 CONDITIONAL_OK/WARN/FAIL 原因。finalize 在 before-manifest 前 cleanup：删除 lock/pid/launcher/credential，截断超大日志。
+
+详见 `report-pipeline-protocol.md`。本协议保留 archive final report 的维度要求，report pipeline 负责把这些维度程序化生成和校验。
+
+## 必备产物
+
+归档目录必须包含：
+
+```text
+archive-meta.md
+archive-manifest-before.json
+archive-manifest-after.json
+summary-data.json
+events.ndjson（新流程推荐；历史 archive 可缺失）
+```
+
+## summary-data.json
+
+结构来源为 `harness-archive/templates/summary-data-template.json`（schemaVersion 2.3）。默认由 `harness_archive.py finalize` 生成；历史回放用 `harness_archive.py replay`。
+
+```json
+{
+  "schemaVersion": "2.3",
+  "changeName": "...",
+  "businessGoal": "本次变更为了做什么",
+  "finalCommit": "...",
+  "finalCommitBranch": "origin/...",
+  "baseCommit": "...",
+  "diffStat": {"filesChanged": 0, "insertions": 0, "deletions": 0, "range": "<base>..<head>"},
+  "stageStatus": {
+    "plan": "OK/FAIL",
+    "run": "WARN/OK/FAIL",
+    "test": "OK/PARTIAL/BLOCKED/FAIL",
+    "review": "ADVISORY",
+    "submit": "OK/WARN/FAIL",
+    "archive": "OK/FAIL"
+  },
+  "durations": {
+    "totalLabel": "约 N 分",
+    "totalMinutes": 0,
+    "stages": [{"stage":"plan","skill":"harness-plan","startedAt":"...","endedAt":"...","minutes":0,"result":"OK"}]
+  },
+  "skillCalls": [{"skill":"harness-plan","count":1,"result":"OK"}],
+  "verification": {
+    "unitTests": {"run": 0, "failures": 0, "errors": 0, "skipped": 0, "passRate": "183/185"},
+    "apiTests": {"total": 0, "passed": 0, "failed": 0, "blocked": 0, "passRate": "34/35"},
+    "coverageDisplay": "29/29"
+  },
+  "timeline": [],
+  "changedFiles": [{"path":"...","summary":"...","insertions":0,"deletions":0}],
+  "artifacts": [],
+  "reviewSummary": {"status":"ADVISORY","red":0,"yellow":0,"redFixed":0,"redConfirmed":0,"yellowFixed":0,"yellowDeferred":0,"summary":""},
+  "archiveManifest": {},
+  "uncommittedTestEvidence": [],
+  "maintenanceNotes": [],
+  "knownRisks": [],
+  "manualActions": [],
+  "reportPipeline": {
+    "schema_version": 1,
+    "generated_at": "...",
+    "event_count": 0,
+    "sources": [],
+    "phases": {},
+    "commands": [],
+    "verificationChecks": [],
+    "artifacts": [],
+    "validationIssues": [],
+    "sourceConsistency": {"ok": true, "issues": []}
+  }
+}
+```
+
+`summary-data.json` 的数字必须全部来自 events、ledger 或 manifest，不得手写另一套统计。
+
+### 数据采集来源（禁止手写统计）
+
+- `diffStat` / `changedFiles[].insertions`/`deletions`：来自 `git diff --numstat <base>..<head>` 与 `git diff --stat <base>..<head>`，不得手写。
+- `durations`：从 `logs/execution-log.md` 各 `[N] harness-<skill>` 小节的 `开始`/`结束`/`耗时` 解析；`totalMinutes` 为各 stage `minutes` 之和。含用户确认等待的阶段须在该 stage 的 `result` 或 `maintenanceNotes` 注明，不得把等待时间伪装成纯执行时间。
+- `skillCalls`：从 execution-log 统计每个 `harness-<skill>` 小节出现次数（含重入）及结果。
+- `verification` 各项及 `passRate`：来自 `evidence/verification-ledger.json`，不得手写通过率。
+- `reviewSummary.redFixed`/`redConfirmed`/`yellowFixed`/`yellowDeferred`：从 review 报告清单 + 后续修复提交 diff 比对得出，不得手写。
+- `artifacts[]`：本次变更构建出的可分发 package 产物（如 `.jar`/`.war`/`.zip`/`.tar`/`.gz`/`.dll`/`.exe`/`.whl`/`.nupkg` 等）。来自项目构建输出目录扫描（按构建工具识别产物路径，如 Maven `target/*.jar`、Gradle `build/libs/*`、npm `dist/*`、.NET `bin/Release/*`），每项记录 `name`（basename）、`path`（相对仓库根）、`size`、`sha256`（`Get-FileHash -Algorithm SHA256` 计算），不得手写。无构建产物时留空数组，平台不展示空卡片。注意：归档 manifest（`archive-manifest-after.json`）记录的是 `.harness/archive/` 目录文件，不包含项目构建产物，两者不可混用。
+- `reportPipeline.commands[]` / `verificationChecks[]` / `validationIssues[]`：来自 `events.ndjson`、ledger、validate 结果。旧 archive 无 events 时可从 ledger/log/manifest 回放，不得编造。
+
+## manifest/checksum
+
+archive 前后生成文件清单，包含 path、size、sha256。before/after 统计不一致时，不得删除原目录。
+
+manifest 必须使用固定脚本生成，禁止内联包含 `$`、`$_`、`@{}`、script block、管道 JSON 输出的 PowerShell：
+
+```powershell
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File "harness-skills/harness-archive/scripts/gen-manifest.ps1" -RootPath ".harness/changes/<change>" -OutputPath ".harness/changes/<change>/evidence/archive-manifest-before.json"
+```
+
+最终报告必须区分：
+
+- movedFiles：实际移动的文件数；
+- generatedFiles：archive 过程中生成的文件数；
+- totalArchiveFiles：归档目录最终文件总数。
+
+## Durable archive
+
+同一工作区内从 `changes/` move 到 `archive/` 只属于 local archive。需要抗工作区删除时，finalize 必须配置独立 `--durable-root`：
+
+- payload 以整树 digest 写入 `<durable-root>/objects/sha256/<digest>/payload/`，对象不可变且可内容寻址；
+- `<durable-root>/receipts/<archive-id>.json` 记录 digest、来源 identity、保留策略与验证时间；
+- durable 写入采用 staging → hash/readback verify → atomic publish；失败时保留原 change，且不得留下可被误认成功的 local archive；
+- `restore-durable` 先验证 receipt 与对象 digest，只恢复到不存在的目标，完成后再次比对整树 digest；
+- 成功状态区分 `ARCHIVED_DURABLE` 与 `ARCHIVED_LOCAL_ONLY`，后者必须进入 knownRisks。
+
+## 页面内容
+
+平台归档摘要必须突出：
+
+1. 本次变更业务目标；
+2. 代码变更统计（diffStat：文件数 / insertions / deletions）；
+3. 各阶段耗时与 Skill 调用统计（durations / skillCalls）；
+4. 验证结果与复用/重测来源（含通过率）；
+5. review advisory 摘要（含修复进度：已修复 / 已确认 / 留后续）；
+6. 给后续维护者的结论；
+7. 已知风险或人工确认项。
+
+禁止出现顶部 `N/A`、正文 `100%` 这类互相矛盾的数据。
+
+
+## summary-data 信息密度要求
+
+`summary-data.json` 至少包含 `verification`、`artifacts`、`reviewSummary`、`archiveManifest`、`maintenanceNotes`、`knownRisks`、`manualActions`。平台只读取该 JSON，不重新推理或维护第二套统计。
+
+`artifacts` 与 `uncommittedTestEvidence` 为空数组时，平台不展示对应卡片，避免空态噪音；非空时才展示。字段在 JSON 中始终保留，仅控制界面展示。
+
+## 数据校验
+
+`validate` 是 finalize 的内嵌同进程步骤（不存在独立 `report validate` CLI）。validate error 存在时，finalize 恢复原 changes 目录并 exit 非 0，绝不删除原 changes 目录。warning 保留在报告中，但不会被误判为 validate error。Hunter Platform 直接读取已校验的 `summary-data.json`。
+
+正常完成时，`baseCommit` 与产品 tip 相同属于 `ARCHIVE_BASE_EQUALS_FEATURE_TIP`，必须在暂存前阻断。不得手工改 ledger 或 state snapshot。已有提交确属本变更时，使用 `adopt-existing-range` 生成绑定仓库、ownership 和 diffHash 的不可变收据；主动废弃或被替代时允许零产品增量，但必须记录中文原因，且固定 `releaseEligible=false`。
+
+候选收据缺失时，`execute` 可以复用身份一致、范围完整的 `unitTestFull` ledger 自动生成本地候选认证。提交只改变 commit 身份而产品树和验证输入未变化时，允许安全重绑定到当前 HEAD；该过程不得执行测试。门禁策略未声明数据库能力且未要求 `dbCompatibility` 时，数据库投影为带原因的 `NOT_APPLICABLE`，不得把缺少无关数据库证据升级为归档错误。
+
+## 冻结优先 finalize 与两层一致性（schemaVersion 2.3 起）
+
+finalize 在 collect 之前**冻结事件事实**：所有 archive-fact 事件落盘并 fsync 后，写入唯一的 `phase.end` 与 `evidence/evidence-cutoff.json`（`eventCount` + `sha256` + `frozenAt`）。cutoff 之后**禁止再向归档 events.ndjson 追加任何事件**；后续校验结果与 manifest 比对只写入 finalize JSON payload 与 maintenance outbox，不回写事件流。collect 是纯函数：stage/timeline/durations 全部由冻结事件推导，**不存在选择性 patch 步骤**。
+
+两层 validator 顺序执行，任何一层失败都恢复原 change 目录并非零退出：
+
+1. **source consistency**（`validate_source_consistency`）：summary 事实对照冻结来源——`event_count` 对 cutoff、verification 对 ledger typed metrics projection、review 计数对 sidecars。结果写入 `reportPipeline.sourceConsistency = {ok, issues}`；`ok=false` 时 issue code 含 `event-count-mismatch` / `verification-mismatch`。
+2. **summary consistency**（`validate_summary_data`）：检查最终状态与验证结果是否矛盾，以及结构化字段是否满足归档要求。
+
+## versioned repair（不改写原归档）
+
+`replay` 保持只读。归档后发现不一致时，用显式修复：
+
+```powershell
+python harness/scripts/harness_archive.py repair --archive-dir ".harness/archive/<archive-id>" --json
+```
+
+repair 先在 archive 外生成候选 derived version。来源校验与数据校验均通过后，才以不可变新版本写入 `derived/v<N>/{summary-data.json, repair-record.json}`，并把 `derived/authoritative.json` pointer 指向该版本；**原 summary-data.json 与 manifest 永不覆盖**。知识层只从 authoritative pointer 指向且 hash 校验通过的版本提取条目。
+
+## 归档包与服务端知识 ingest（§8）
+
+archive close 的破坏性事务只执行确定性 close：
+
+```text
+execute(one-shot status + gate) -> manifest -> move -> collect -> validate -> compare
+-> 生成确定性核心 ZIP -> 上传并等待服务端持久化/ingest 收据 -> stop AI service -> return
+```
+
+close 不再运行 `harness_knowledge.py`，也不写本地 outbox/index。服务端先保存原 ZIP，再安全
+解包发布核心文件并重建项目语义索引；客户端以 package hash 与 `knowledge_status` 作为收据。
+失败时本地归档保持有效，待上传 ZIP 保留供同包重试，不允许改走散文件 push 或本地索引。
+
+## 最终状态
+
+当 `apiTests.status=USER_SKIPPED` 或 `dbCompatibility=BLOCKED_BY_DBA` 时，最终状态不得写纯 `OK`，必须写：
+
+```text
+CONDITIONAL_OK
+```
+
+并在 `knownRisks` / `manualActions` 中说明风险接受和后续人工动作。
+
+## 未提交测试证据
+
+run/test 本轮新增、更新或安全修复且被 `.gitignore` 忽略的测试，必须先由 `test-tracking.json` + `harness_test_guard.py stage` 精确提交；这类测试不得继续作为“未提交证据”收尾，也不得计入可复用 P0 验证后随 worktree 删除。
+
+`uncommittedTestEvidence` 只兼容历史归档或明确只读的外部证据：归档到 `backups/uncommitted-tests/`，记录文件名、验证范围与未提交原因，并在 `summary-data.json` 中记录风险。若它是本轮可修改的回归测试，则 archive 必须阻断并要求先走精确跟踪流程。

package/harness/bundles/general/pi/protocols/ci-layering-protocol.md

@@ -0,0 +1,22 @@
+# CI 分层与构建产物复用协议
+
+所有项目将远端验证拆成四层，触发条件和产物身份必须彼此独立：
+
+| 层 | 默认触发 | 工作内容 |
+|---|---|---|
+| `fast` | push / pull request | 影响选择后的格式、合同和单元门禁；分钟级反馈 |
+| `candidate` | 冻结产品 identity 后手动触发 | 完整测试、真实栈、安全扫描、SBOM；每个 identity 最多一次 |
+| `evidence-only` | 证据路径变化或候选证据续跑 | 校验 schema、hash、identity；禁止重新构建产品镜像 |
+| `release` | 已通过候选的受控发布 | 校验既有 artifact/digest，附加发布标签并部署；禁止再次构建 |
+
+## 必需控制
+
+- 同分支同层启用 concurrency cancellation，取消过时运行；
+- `candidate` 构建的镜像和制品以提交、产品树和环境 identity 命名并记录 digest；
+- 产品路径冻结后，候选通过前不得夹带证据提交；候选通过后只允许 evidence-only 路径变化；
+- 未知路径或影响图无法证明边界时扩大验证，不能缩小；
+- Linux、Docker、shell 权限等行为先在受控 Linux 环境运行 canary；
+- 发布层只消费候选产物，不执行源码构建；
+- runner minutes、缓存命中和关键路径耗时写入周期报告，以实际基线评价优化。
+
+项目可用自身 CI 语法实现该协议，但层名、身份和收据语义保持一致。

package/harness/bundles/general/pi/protocols/evidence-based-reporting-protocol.md

@@ -0,0 +1,134 @@
+---
+description: harness 全流程的证据化报告协议。所有 skill 输出必须区分 ✅真实成功 / 🟡静态验证或跳过 / ❌失败或被拒绝。由原 harness-plan/evidence-based-reporting.md 迁移。
+---
+
+# Evidence-Based Reporting Protocol
+
+> 本协议适用于所有 harness-skills 的最终输出。禁止把"静态验证"写成"测试通过"，禁止把"命令被拒绝"写成"成功"。
+
+## 状态分类
+
+所有 skill 的最终输出必须使用以下三类状态标记：
+
+| 标记 | 含义 | 使用场景 |
+|:----:|------|----------|
+| ✅ | **已真实执行并成功** | 有构建成功证据（Java=`BUILD SUCCESS`；前端/Python 按各自工具成功标志） / git 成功信息 / 文件实际存在 / exit code 0 等明确证据 |
+| 🟡 | **静态验证 / 用户确认跳过 / 证据不足** | 1. TDD 降级：仅做静态逻辑验证，未执行真实单元测试<br>2. 用户明确跳过 test/review<br>3. 命令执行但证据不充分<br>4. 需部署后验证的场景 |
+| ❌ | **执行失败 / 被 hook 拒绝 / 未验证** | 1. 命令被 hook 拒绝（Denied / PreToolUse:Bash hook error）<br>2. exit code 非 0<br>3. 输出无有效 stdout<br>4. 场景未覆盖且未验证 |
+
+## 禁止的表述
+
+| 禁止表述 | 正确表述 | 原因 |
+|----------|----------|------|
+| "测试全部通过" | 🟡 静态逻辑验证通过，未执行真实单元测试 | TDD 降级时没有真实测试 |
+| "编译成功" | ❌ 编译命令被 hook 拒绝 | 命令没有成功执行 |
+| "打包成功" | ❌ 打包命令输出不包含构建成功证据 | 没有明确证据 |
+| "拉取成功" | ❌ git pull 命令被 Denied | 命令被 hook 拦截 |
+| "推送成功" | ❌ git push 返回非 0 exit code | 推送实际失败 |
+| "覆盖率 100%" | 🟡 静态验证覆盖率 100%，未运行真实测试 | 覆盖率来源不实 |
+
+## 编译验证状态映射
+
+| 构建工具输出 | 状态标记 |
+|-----------|:--------:|
+| 包含构建成功证据（Java=`BUILD SUCCESS`；前端/Python 按各自工具成功标志） | ✅ 编译成功 |
+| 包含构建失败标志（Java=`BUILD FAILURE`；前端/Python 按各自工具失败标志） | ❌ 编译失败 |
+| 命令被 hook 拒绝 | ❌ 编译命令被拒绝 |
+| 无输出 / 超时 | ❌ 编译状态未知 |
+| 仅部分模块编译（跳过无关模块） | ✅ 目标模块编译成功 |
+
+## 测试验证状态映射
+
+| 情况 | 状态标记 | 报告表述 |
+|------|:--------:|----------|
+| 测试命令输出包含测试通过证据（Java=`Tests run: N, Failures: 0`；前端/Python 按各自工具） | ✅ | ✅ 已测试通过：N 个用例，0 失败 |
+| TDD 降级（无测试基础设施） | 🟡 | 🟡 静态验证通过，未执行真实单元测试，待测试基础设施补齐后运行 harness-test |
+| 测试命令被 hook 拒绝 | ❌ | ❌ 测试命令被拒绝，无法确认测试结果 |
+| 测试失败（有 Failures > 0） | ❌ | ❌ 测试失败：N 个用例，M 个失败 |
+| 用户确认跳过测试 | 🟡 | 🟡 用户确认跳过测试 |
+
+## 场景覆盖状态映射
+
+| 情况 | 状态标记 |
+|------|:--------:|
+| 有对应测试方法且测试通过 | ✅ 已测试通过 |
+| 代码逻辑已覆盖但未执行测试 | 🟡 静态验证通过，未真实测试 |
+| 代码逻辑未覆盖 | ❌ 未覆盖 |
+| 需要端到端部署验证 | 🟡 待部署后验证 |
+| 用户确认跳过 | 🟡 用户确认跳过 |
+
+## Git 操作状态映射
+
+| git 输出 | 状态标记 |
+|----------|:--------:|
+| `Already up to date.` 或实际更新记录 | ✅ 拉取成功 |
+| `Denied: non-ASCII path in Bash` | ❌ 命令被 hook 拒绝 |
+| `To <remote>` + 推送范围 | ✅ 推送成功 |
+| 无输出 | ❌ 状态未知 |
+
+## summary-data.json 状态映射
+
+平台监控直接读取 `summary-data.json`。本地归档不再生成重复的 HTML 报告。
+
+归档前必须执行 `harness_archive.py finalize` 内嵌 validate，或使用 `harness_archive.py replay` 做等价校验。只有 validate 无 error 时，才能宣称报告数据有效；validate error 不得被写成 WARN 或「已完成」。
+
+| 数据来源 | 无报告时 |
+|----------|----------|
+| `summary-data.validations.unit/api` | 标记 `NOT_RUN` / `STATIC_ONLY`，不得显示 100% |
+| `summary-data.review` | 标记 `ADVISORY_NOT_RUN`，不得显示 100% |
+| `summary-data.package` | 缺失时标记 `WARN`，不得伪造 package 成功 |
+| `summary-data.stageStatus` | 必须真实展示 ✅OK / 🟡WARN / 🔁REUSED / 📝ADVISORY 等状态 |
+
+## 执行日志状态标注
+
+所有 skill 的 execution-log.md 中，结果字段必须使用以下格式：
+
+```markdown
+- **结果**: ✅OK成功 / 🟡WARN(降级原因) / ❌FAIL(失败原因)
+```
+
+禁止使用模糊表述如"OK"、"成功"、"完成"，必须包含状态标记和具体原因。
+
+## 两维度术语表
+
+本协议的状态标记与 review 的发现严重级是**两个独立维度**，不得混用。下表统一登记各态的边界与关系，避免散落未对齐。
+
+### 维度一：skill 执行状态三态
+
+任何 skill 的最终执行结果必须落到以下三态之一：
+
+| 标记 | 含义 | 适用场景 |
+|:----:|------|----------|
+| ✅OK | 已真实执行并成功 | 有构建成功证据 / git 成功信息 / 文件实际存在 / exit code 0 等明确证据 |
+| 🟡WARN(原因) | 静态验证 / 用户确认跳过 / 证据不足 / 降级 | TDD 降级仅静态验证、用户跳过 test/review、命令执行但证据不充分、需部署后验证、远端有新提交需 pull/rebase、用户选择仅本地 commit |
+| ❌FAIL(原因) | 执行失败 / 被 hook 拒绝 / 未验证 | 命令被 hook 拒绝、exit code 非 0、输出无有效 stdout、push 失败/被拒绝、commit 失败、hook 拒绝、场景未覆盖且未验证 |
+
+### 维度二：review 发现严重级（审查发现维度，不等于 skill 执行状态）
+
+harness-review 对代码/变更的审查发现按风险分级，反映的是**被审查对象的问题严重度**，而非 review 这个 skill 本身是否执行成功：
+
+| 标记 | 含义 | 适用场景 |
+|:----:|------|----------|
+| RED | 高风险建议 | 存在安全/数据/契约级高风险问题，建议阻塞合并 |
+| YELLOW | 中低风险 | 存在中低风险改进项，建议处理但不阻塞 |
+| OK | 无问题 | 审查通过，未发现需处理项 |
+
+> 注意：review skill 执行成功（✅OK）不等于发现严重级为 OK；review 发现 RED 时，review skill 本身仍可能是 ✅OK（执行成功并产出了 RED 发现）。
+
+### 条件态 / 跳过态（特殊最终状态）
+
+以下状态用于特定条件下的最终状态表达，不属于上述两个主维度的常规三态：
+
+| 标记 | 含义 | 适用场景 |
+|:----:|------|----------|
+| CONDITIONAL_OK | 条件性通过 | API 测试 `USER_SKIPPED` 或 DB 兼容性 `BLOCKED_BY_DBA` 时的归档最终状态，不得写纯 OK，必须在 knownRisks/manualActions 说明风险接受与后续人工动作 |
+| 🔁REUSED | 复用前阶段结果 | 复用了前一阶段验证结果，summary-data 必须显式标记，不得伪装成重新执行 |
+| 📝ADVISORY | 参考性未运行 | review 参考性意见，未作为门禁执行 |
+| ⏭️ | 用户选择跳过 | 用户主动选择跳过某步骤（如仅本地 commit 不 push、跳过 test/review） |
+
+### 两维度关系
+
+- skill 执行状态回答"这个步骤跑没跑、成没成"；
+- review 发现严重级回答"被审查的东西有没有问题、问题多大"；
+- 条件态/跳过态回答"这个步骤的最终结论是什么特殊情况"。
+- 三者独立：例如 test skill 可 ✅OK 执行成功，但 review 发现其覆盖的代码存在 RED 问题；又如 archive 可因 `USER_SKIPPED` 给出 CONDITIONAL_OK，同时 review 发现为 YELLOW。summary-data 必须分别记录，不得用一个维度覆盖另一个。

package/harness/bundles/general/pi/protocols/execution-session-protocol.md

@@ -0,0 +1,52 @@
+---
+description: 长时命令、验证调度、环境复用与 fixback 的可恢复执行协议。
+---
+
+# Execution Session Protocol
+
+## 受管运行会话
+
+可能超过交互窗口的命令必须通过 `harness_runtime.py run-start` 创建受管会话，而不是依赖调用方进程持续在线。会话状态位于：
+
+```text
+runtime/run-sessions/<session-id>/
+├── session.json
+├── stdout.log
+├── stderr.log
+└── worker.log
+```
+
+`session.json` 只持久化脱敏身份：命令哈希、环境哈希、产品身份、验证目标、阶段、资源锁、进程身份、心跳、进度、超时和原因码。原始环境变量和敏感 argv 不得写入回执。
+
+- `run-status` 可由新进程重连；心跳丢失超过 grace period 才标记 `INCOMPLETE`。
+- `run-log --cursor` 按字节游标增量读取 UTF-8 日志，返回下一游标。
+- `run-cancel` 只终止身份完全匹配的进程树；身份不确定时 fail closed。
+- launcher 尚未启动子进程时失败，状态为 `INCOMPLETE/LAUNCHER_FAILED`；子进程非零退出为 `FAIL/CHILD_EXIT_NONZERO`；超时为 `CANCELLED/TIMEOUT`。
+- `resourceLocks` 通过 `runtime/resource-locks/<lock-hash>.json` 原子独占；冲突会在启动测试进程前返回 `INCOMPLETE/RESOURCE_LOCK_BUSY`，终态写入前必须释放持有的锁。
+- Windows 使用 shell-free argv 和 kill-on-close Job Object；Job Object 绑定失败时必须终止已验证的子进程并返回 `PROCESS_TREE_ISOLATION_UNAVAILABLE`，不得降级为无隔离运行。
+
+## 验证调度
+
+`harness_verification.py plan` 对验证 DAG 做拓扑调度。每个目标声明 `dependsOn`、`resourceLocks`、identity 与复用策略。
+
+- 只有资源锁不相交的 ready 目标可进入同一 wave。
+- 未声明资源锁且预计大于等于 60 秒的目标自动使用 `harness:unclassified-heavy`，因此默认串行。
+- 冻结后的产品 identity 发生变化时返回 `FROZEN_IDENTITY_DRIFT`，禁止继续执行或复用。
+- 复用和跳过必须记录 `decision`、`reasonCode` 与人类可读 `explanation`；无证据不得返回 `REUSE`。
+
+## 环境会话
+
+环境租约支持两种模式：
+
+- `change-session`：同一 change、stack、内容指纹和通过的 canary 可复用。
+- `ephemeral`：每次 acquire 都创建新 session；替换既有 session 前必须提供匹配 stack/environment identity 的 provider reset 回执。
+
+租约获取通过注册锁原子串行化，跨 change 的 writable volume 永不共享。`change-session` 只有在内容指纹非空、environment hash、owner identity、expiry、mode、volume 和 canary 全部匹配时才可复用。内容指纹漂移标记 `STALE_CONTENT`；过期租约不可写。prepare/reuse 写入事实回执；reset/cleanup 只有在 provider operation evidence 为 `OK` 时才可如此命名。单纯释放租约只能记录 `release`，不得声称已清理外部环境。回执写入 change 的 `runtime/environment-receipts/`，文件名使用 stack hash，且不包含凭据明文。
+
+## Fixback 批次
+
+Review/Test 回灌通过 `harness_fixback.py` 形成批次。一个批次可包含多条相关问题，但每条问题必须保留可读取的 JSON RED/GREEN 证据。证据必须位于项目或 change state 内，包含 evidence id、状态和产品 identity，并在批次中固定 SHA-256；RED 必须为 `FAIL`，GREEN 必须为 `PASS/OK`。affected verification 与 review 回执必须绑定最终产品 identity，其 `passedGates` 合集覆盖风险扩展后的全部门禁。`freeze-readiness` 会重新校验证据摘要；开放问题、证据漂移或缺门禁均阻止 code freeze。
+
+## 效率摘要
+
+`harness_efficiency.py summary` 从运行会话、环境回执和失效回执生成事实型指标：墙钟区间并集、累计活动/资源等待、execution/launcher/verification 尝试、失败分类、环境 prepare/reuse/reset/cleanup、重复且没有新 result digest 的命令和人工 wrapper 数。reset/cleanup 只统计带有效 provider evidence 的回执。归档摘要自动包含该结构；指标不得归责个人，也不得在历史样本不足时虚构 ETA。

package/harness/bundles/general/pi/protocols/external-platform-protocol.md

@@ -0,0 +1,27 @@
+# 外部平台最终一致性协议
+
+用于 CI、镜像仓库、部署控制面、证据回传等异步外部系统。目标是让网络传输、远端业务状态和本地观察新鲜度彼此独立，避免把“请求成功”误判为“业务成功”。
+
+## 统一观察合同
+
+每次观察至少包含：
+
+- `subjectIdentity`：不可变业务对象身份，如提交、镜像 digest、运行 ID 与环境身份的规范化组合；
+- `businessState`：`PENDING/RUNNING/SUCCEEDED/FAILED/CANCELLED/UNKNOWN`；
+- `observationState`：`PENDING/TERMINAL/UNKNOWN`；
+- `freshness`：`FRESH/STALE/UNKNOWN`；
+- `retryable`、`reasonCode`、`observedAt`；
+- 写操作还应携带稳定 `idempotencyKey`。
+
+JSON 合同见 `contracts/external-platform-observation.schema.json`。
+
+## 收敛规则
+
+1. 只有身份一致、`freshness=FRESH` 且观察到权威终态，才能宣称完成。
+2. `TERMINAL + SUCCEEDED` 才是成功；`FAILED/CANCELLED` 必须保留为业务失败，不能被 HTTP 2xx、回调成功或旧缓存覆盖。
+3. 仅重试 retryable 的传输失败、陈旧观察或非终态；鉴权、参数、身份不匹配与权威失败不得重试成成功。
+4. 重试必须同时受最大次数、总耗时和退避表约束；预算耗尽输出结构化失败收据。
+5. 每次轮询继续使用同一 `subjectIdentity`/`idempotencyKey`，身份漂移立即 fail closed。
+6. 回调只是触发再次观察的信号，最终结论仍以权威读取接口为准。
+
+通用执行内核为 `@hunter-harness/core` 的 `convergeAuthoritativeState`。