boardx / boardx/workspacex

fix(harness): 验证凭证跨调用复用失效 —— verify 自己改 PROGRESS.md 时间戳,指纹每次都变

Open
#1,341 0 comments 0 reactions 0 assignees View on GitHub
area:harness
Dominant language
TypeScript
Stars
0
Forks
0
Avg merge
1h 7m
Merged PRs (30d)
969

Description

## 实测证据

`verify` 每跑一次都会重写 `.harness/state/PROGRESS.md`,内容里嵌着运行时刻的时间戳:

```
-_最近聚合:2026-08-15T10:37:36.290Z_
+_最近聚合:2026-08-15T11:25:20.228Z_
```

`PROGRESS.md` 是 **tracked 文件** → 进 `git diff HEAD --` → 而 `computeFingerprint` 把整个 `git diff HEAD` 纳入指纹 → **每跑一次 verify,下一次的指纹必然不同**。

实测:同一 SHA、工作树无任何人为改动,连跑 3 次 `pnpm harness verify`,产生 **3 条缓存记录、0 次命中**。

## 影响范围(精确,不夸大)

| 场景 | 现状 |
|---|---|
| **单次 verify 调用内跑多个 feature** | ✅ **正常工作**,feature 2..N 命中缓存。这是本机制最高价值的场景(3-feature sprint 以 `verify:release` 29min 计,87min → 29min),已实测确认 |
| **跨 verify 调用**(先跑一次,改完别的再跑) | ❌ 必然 miss |
| pre-push / CI | 本来就没接(见 #1334,已明确决定不接/达不到) |

所以不是"缓存完全失效",是**跨调用那一半失效**。而原始提案 item 4 要的恰恰是跨调用/跨工具复用(「`harness verify`、pre-push 和 CI 遇到相同 SHA、相同验证配置时复用结果」)。

## 根因

指纹的设计意图是「覆盖会影响验证结果的输入」,但实现是「整个工作树的 diff」——把 **harness 自己产出的派生物**(PROGRESS.md 时间戳、evidence 日志、active-features.json 派生视图)也算成了"输入变化"。这些是验证的**输出**,不是输入,它们变化不代表代码变了。

## 修法与风险

排除 harness 自身写入的派生路径。候选清单(需要逐条论证,**不能一把梭排除**):

- `.harness/state/**`(PROGRESS.md、派生视图等)
- `phases/*/sprints/*/evidence/**`(证据日志)
- `phases/*/feature_list.json` / `active-features.json`(verify 会写 status)

⚠ **假绿风险**:排除范围一旦过宽,真实的输入变化会被忽略 → 缓存误命中 → 跳过本该跑的验证。这正是本 issue 必须单独立项、单独 review 的原因,不适合顺手塞进别的 PR。

⚠ 注意 `.harness/config/harness.config.yaml` **必须留在指纹里**(它定义了 profile 映射,改它就是改验证行为)。它在 `config/` 不在 `state/`,按上面的清单不会被误排除,但实现时要确认。

## 验收(端到端,不能只测函数)

- [ ] 跑一次 `pnpm harness verify`,不做任何人为改动再跑一次 → **第二次命中缓存**
- [ ] 反证:真改一行**源码**后再跑 → **不命中**,重新执行
- [ ] 反证:改 `harness.config.yaml` 的 profile 映射后再跑 → **不命中**(否则改了验证策略却复用旧结果)
- [ ] 反证:确认单次调用内多 feature 的既有正确行为没被破坏(回归)

关联:ADR-106、#1275、#1334、PR #1340

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by locating computeFingerprint and the harness verify entry point, then inspect how git diff HEAD is collected and how paths such as .harness/state/**, evidence/**, feature_list.json, and harness.config.yaml are treated. Run pnpm harness verify twice without changes, then repeat after changing source and the profile mapping. Done means unchanged inputs hit the cache while both real code and configuration changes miss, without breaking multi-feature caching.

Written by the indexing model from the issue text.

Assessment

Tech stack
git, typescript
Domain
testing, tooling
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.