@haaaiawd/skeinn 2.4.0 → 2.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,17 @@
1
1
  # Changelog
2
2
 
3
+ ## 2.5.0
4
+
5
+ - Redesigned Keeper around **two minimal primitives** (`reviewed_digests` per-artifact hash map + unified `scope`-pinned `findings` ledger) and exact topological horizon calculation (`activeHorizon(depth=2)`):
6
+ - **`passed_with_advisories`**: Minor-only items no longer force another full Keeper round; they pass Launch immediately and pin to their `TASK-ID` or `.skeinn/design/<doc>.md` scope.
7
+ - **Automatic `task start` surfacing & gating**: Starting any Task automatically surfaces all open findings pinned to that Task OR its `reads`/`implements` docs (blocking severity gates start until resolved via `skeinn keeper resolve <FND-ID> --evidence "<proof>"`; minor severity surfaces as an active advisory).
8
+ - **Scope-bounded Delta Re-check (Round 2+)**: Follow-up Keeper rounds automatically inject only `dirty` modified artifacts and open blocking findings rather than the full corpus, eliminating fresh-eyes nitpicking spirals.
9
+ - **Non-convergence (`>=`) ping-pong guard**: If blocking findings fail to strictly decrease across two consecutive rounds, `skeinn project ready` halts blind looping without dumping internal chores on the human (unlockable via `--force-round --reason`).
10
+ - **In-Flight Checkpoints & Late-Entering Horizon Review**: Launch pass is a one-time birth certificate (`launch_completed`); distant design docs entering the horizon or designs updated mid-flight via `decision` automatically appear as `dirty` for lightweight `skeinn keeper checkpoint prompt|record` and `skeinn context --checkpoint`.
11
+ - **Empirical Spike tasks (`kind: "spike"`)**: Can start in `shaping` before Launch without `implements` to resolve physical/empirical unknowns with real evidence. Delivery Tasks cannot `depends_on` a spike (enforced in `validateTasks`, covering both `task plan` and `task update`) — distill findings into Design/Capability or `skeinn record` instead.
12
+ - **Silent-drift watchdog**: Completing 5 delivery Tasks since the last clean review/checkpoint raises a warning in `skeinn check` and a watch line in `skeinn context` — derived purely from timestamps, no new state; `drift_detected` verdicts deliberately do not reset it, only `clean` does. Checkpoint prompt/context inject the recent delivery Tasks' `touches` so an empty `dirty` set never leaves the reviewer a blank page.
13
+ - **Relaunch escape hatch**: `skeinn keeper reset --reason <text>` clears `reviewed_digests` and logs a decision for genuine full-direction pivots.
14
+
3
15
  ## 2.4.0
4
16
 
5
17
  - Upgraded Evil Eval (`skeinn eval scaffold`) to a 3-tier budget-aware pyramid (`probe` ¥2–5, default 3-baton zero-memory `relay` ~¥20, and `full`), adding per-baton prompts, `hidden-oracle.mjs`, `telemetry-template.json`, and Pairwise Forced-Choice (`X_CLEAR_WIN | TIE | Y_CLEAR_WIN`) blind judging.
package/README.md CHANGED
@@ -36,7 +36,7 @@ AI coding feels effortless on small scripts, yet multi-day, multi-module project
36
36
  | **Context amnesia** | Compaction or a new session wipes out architecture, boundaries, and earlier corrections | Project truth, decisions, progress, and proof live on disk; a fresh Agent resumes directly |
37
37
  | **Generic average output** | Models default to safe statistical averages that look templated and amateur | Targets 1–3 bottleneck domains, **researches how real practitioners operate**, and reflects on project constraints |
38
38
  | **First-draft lock-in** | Codes the first plausible idea immediately, hiding expensive rework | Core designs force **at least 2 genuinely viable alternatives** (including a simpler or unconventional angle) |
39
- | **False-green completion** | Claims "done" while missing files, skipping edge cases, or breaking upstream work | A **fresh independent Keeper** audits build-readiness once; every Task closes with reproducible evidence |
39
+ | **False-green completion** | Claims "done" while missing files, skipping edge cases, or breaking upstream work | A **fresh independent Keeper** gates launch on the active horizon — minors pass as advisories pinned to their Task/doc and surface at `task start` — while per-artifact digests drive delta re-checks and in-flight drift checkpoints; every Task closes with reproducible evidence |
40
40
 
41
41
  > **Core rule: Skeinn is for the Agent, not the human.**
42
42
  > Multilingual by default — talk naturally in English, Chinese, Japanese, or any language you prefer. The Agent operates the `skeinn` CLI silently in the background.
@@ -57,12 +57,12 @@ You (natural chat in any language) Agent (silent skeinn CLI on disk)
57
57
  → reflection → Design delta)
58
58
 
59
59
  3. Confirm the whole Freeze digest → fresh zero-memory
60
- Keeper audits startability, fake
61
- research, strawmen, and guardrails
60
+ Keeper gates launch on the active
61
+ horizon; minors pin to scope
62
62
 
63
63
  4. See working slices, steer anytime Execute one restartable Task at a
64
64
  time with guardrails & exact proof;
65
- direction shifts flag stale work
65
+ drift checkpoints & stale-work flags
66
66
  ```
67
67
 
68
68
  ---
@@ -151,6 +151,11 @@ skeinn deliverable add cli-core --title "CLI core" --kind module
151
151
  skeinn task plan --json-file work-map.json
152
152
  skeinn project ready
153
153
  skeinn keeper record --json-file keeper-result.json
154
+ skeinn keeper resolve FND-001 --evidence "<closure proof>" # close a pinned finding
155
+ skeinn keeper checkpoint prompt --milestone M1 # in-flight drift audit
156
+ skeinn keeper checkpoint record --json-file checkpoint-result.json
157
+ skeinn context --checkpoint # checkpoint-scoped slice
158
+ # kind: "spike" tasks may start during shaping for empirical unknowns
154
159
  skeinn task next && skeinn task start TASK-001
155
160
  skeinn task done TASK-001 --json-file evidence.json
156
161
  skeinn check
@@ -162,4 +167,31 @@ skeinn check
162
167
 
163
168
  ## Verify it actually helps
164
169
 
165
- Run `npm test` (31 end-to-end contract tests), or use `skeinn eval scaffold` to run controlled **Evil Eval** comparisons (equal model, tools, workspace, user facts, forced resets, and blind order-swapped judging). See [EVIL_EVAL.md](EVIL_EVAL.md).
170
+ Run `npm test` (38 end-to-end contract tests), or use `skeinn eval scaffold` to run controlled **Evil Eval** comparisons (equal model, tools, workspace, user facts, forced resets, and blind order-swapped judging). See [EVIL_EVAL.md](EVIL_EVAL.md).
171
+
172
+ ### A real measured run
173
+
174
+ We ran the full L2 relay on **DeepSeek-V4.1-Flash** — a cheap model where framework gains should be most visible. Same harness (opencode), same workspace rules, same brief: build the single-file offline 3-minute retro tool above, across **3 batons with hard memory resets**, with a mid-project pivot to encrypted export/import. Then a hidden oracle, and two independent blind judges scoring sealed X/Y packets in swapped order.
175
+
176
+ ```text
177
+ Hidden oracle (8 objective checks) baseline 8/8 skeinn 8/8 ← parity
178
+
179
+ Total cost baseline ¥0.42 █████ skeinn ¥0.82 ██████████
180
+ Wall time baseline 35 m █████ skeinn 60 m █████████
181
+ Tokens (in+out+reason) baseline 330 k ████ skeinn 741 k █████████
182
+ Tests shipped baseline 43 ██████████ skeinn 44 ██████████
183
+ (pytest + Playwright) (zero-dep `node --test`,
184
+ real headless Chrome)
185
+ ```
186
+
187
+ | Dimension (forced choice) | Judge pass 1 | Judge pass 2 |
188
+ | :--- | :--- | :--- |
189
+ | Intent fidelity & pivot survival | **Skeinn** | Tie |
190
+ | Specialist capability & craft | **Skeinn** | **Skeinn** |
191
+ | Cold-handoff continuity | Tie | Tie |
192
+ | Oracle & proof honesty | Tie | Tie |
193
+ | User burden & ceremony | **Skeinn** | **Skeinn** |
194
+ | Net value per RMB | **Baseline** | **Baseline** |
195
+ | **Overall** | **Skeinn** | **Skeinn** |
196
+
197
+ *Caveats we keep honest: single run, single scenario, n=2 judges. The evidence judges cited, baseline's cost-efficiency win, and one packet-metadata leak we found and fixed-forward are in the full log: [docs/eval/RELAY-001.md](docs/eval/RELAY-001.md).*
package/README.zh-CN.md CHANGED
@@ -36,7 +36,7 @@
36
36
  | **聊久就失忆** | 上下文压缩或新开会话后,架构决策、边界和偏好全丢,越改越散 | 项目全貌、设计、任务进度与证据全部落盘,换新 Agent 直接续接 |
37
37
  | **方案平庸、像外行** | 默认收敛到“互联网统计学平均解”,界面与架构一看就是模板拼凑 | 锁定 1–3 个瓶颈专业域,**调研真实一线从业者怎么干**并反思转化为项目规则 |
38
38
  | **一稿过、后期返工** | 想到第一个可行方案就开写,隐患全部埋在实现阶段 | 核心设计强制**至少 2 个真实可行方案对撞**(含更简或非常规视角),写清取舍 |
39
- | **假绿灯完成** | Agent 口头宣布“已实现”,实测缺文件、漏边界或改坏上游 | 开工前由**全新无记忆 Keeper** 独立验盘;每个 Task 凭可复现证据逐条关闭 |
39
+ | **假绿灯完成** | Agent 口头宣布“已实现”,实测缺文件、漏边界或改坏上游 | **全新无记忆 Keeper** 对拓扑前沿独立验盘起跑,minor 钉到具体 Task/文档并在 task start 自动浮出;施工中由逐工件摘要比对驱动轻量漂移巡检;每个 Task 凭可复现证据逐条关闭 |
40
40
 
41
41
  > **核心原则:Skeinn 是给 Agent 用的,不是给人学的新框架。**
42
42
  > 它天然支持多语言协作——你用中文、英文、日文或任何语言自然聊天即可;Agent 在后台静默调用 `skeinn` CLI 维护 `.skeinn/` 状态,你永远不需要手动敲这些命令。
@@ -55,13 +55,13 @@
55
55
  与 1–3 个瓶颈 Capability(查一线
56
56
  实操 → 项目反思 → 写回 Design Delta)
57
57
 
58
- 3. 确认整体方向 冻结摘要 → 拉起全新无记忆 Keeper
59
- 审查:能否直接开工?有无伪调研、
60
- 稻草人对比或漏掉的防呆红线?
58
+ 3. 确认整体方向 冻结摘要 → 全新 Keeper 验盘前沿:
59
+ 能否开工?伪调研/稻草人/红线?
60
+ minor 钉到具体任务,不再空转
61
61
 
62
62
  4. 陆续看到可运行成果,随时提新想法 一次只做 1 个可恢复 Task(自带
63
63
  guardrails 红线),逐条填实证闭环;
64
- 中途改方向则暂停并标出受影响的旧任务
64
+ 巡检对账漂移,改方向标出受影响任务
65
65
  ```
66
66
 
67
67
  ---
@@ -128,7 +128,7 @@
128
128
 
129
129
  1. **单文件 Capability(真调研 + 真反思 + Design Delta)**:聚焦 1–3 个决定上限的瓶颈域,1 条命令创建 `.skeinn/capabilities/<field>.md`。禁止静默跳过(纯常规工程必须显式 `skeinn capability exempt` 并接受 Keeper 审计);`external_researched` 直接拦截 `agent-authored` 自造来源;无网时诚实标 `offline_reflection`。
130
130
  2. **方案对撞型 Design**:核心设计(`product` / `experience` / `system` / `contract`)强制对比至少 2 个真实可行方案(含更简或非常规视角),把 Capability 判准编译进机制,并提前写清假阳性失败面。
131
- 3. **一次性独立 Keeper**:开工前由全新无记忆 Agent 只读磁盘试跑,并执行四项反敷衍核查(豁免合理性、伪调研、稻草人备选、红线是否落地)。通过后退场,不打扰日常施工。
131
+ 3. **前沿起跑 + 行进间巡检 Keeper**:开工前由全新无记忆 Agent 只对当前拓扑前沿(可执行任务及其 1–2 跳后继、关联设计文档)做独立验盘,四项反敷衍核查不变;仅余 minor 项时按 `passed_with_advisories` 放行并钉到具体 Task/文档,`task start` 时自动浮出,第 2 轮起只对变更文件做 Delta 复核;施工中由逐工件 `reviewed_digests` 差集驱动轻量 checkpoint 漂移巡检,出生证明一次签发不再重跑。
132
132
  4. **可恢复 Task + 防呆红线**:广度 Work Map 留盘,每次只注入当前唯一活跃 Task、精确 `reads` 与 1–3 条 `guardrails`;完成校验产出存在与逐条实证,上游重开自动标出需要复核的下游任务。
133
133
 
134
134
  ---
@@ -192,8 +192,13 @@ skeinn task plan --json-file work-map.json
192
192
  skeinn project ready
193
193
  # 新开无继承上下文的 Agent 运行 skeinn keeper prompt,并提交含 review.mode: "independent" 的结果
194
194
  skeinn keeper record --json-file keeper-result.json
195
+ # 钉在 Task/文档上的 finding 凭证据核销;施工中巡检漂移与迟到前沿工件:
196
+ skeinn keeper resolve FND-001 --evidence "<核销证明>"
197
+ skeinn keeper checkpoint prompt --milestone M1
198
+ skeinn keeper checkpoint record --json-file checkpoint-result.json
199
+ skeinn context --checkpoint
195
200
 
196
- # 单任务实证施工与变更演化
201
+ # 单任务实证施工与变更演化(kind: "spike" 任务可在起跑前做经验性试跑)
197
202
  skeinn task next
198
203
  skeinn task start TASK-001
199
204
  skeinn task done TASK-001 --json-file evidence.json # 详见 skeinn task done --help
@@ -216,6 +221,33 @@ skeinn check
216
221
  npm test
217
222
  ```
218
223
 
224
+ ### 一次真实实测
225
+
226
+ 我们在 **DeepSeek-V4.1-Flash** 上跑完了完整的 L2 接力实验——便宜模型上框架增益最容易拉开差距。同一 harness(opencode)、同一工作区规则、同一题目(上面的单文件离线 3 分钟复盘工具),**3 棒之间硬性清零记忆**,中途塞入加密导入导出需求反转;跑完后由隐藏 oracle 验收,再由两名互不知情的裁判对密封 X/Y 工件包做顺序交换盲评。
227
+
228
+ ```text
229
+ 隐藏 oracle(8 项客观断言) baseline 8/8 skeinn 8/8 ← 持平
230
+
231
+ 总成本 baseline ¥0.42 █████ skeinn ¥0.82 ██████████
232
+ 耗时 baseline 35 m █████ skeinn 60 m █████████
233
+ Token(输入+输出+推理) baseline 330 k ████ skeinn 741 k █████████
234
+ 交付测试数 baseline 43 ██████████ skeinn 44 ██████████
235
+ (pytest + Playwright) (零依赖 `node --test`,
236
+ 真实无头 Chrome)
237
+ ```
238
+
239
+ | 维度(强制二选一) | 裁判 1(X→Y) | 裁判 2(Y→X) |
240
+ | :--- | :--- | :--- |
241
+ | 意图保真与反转存活 | **Skeinn** | 平 |
242
+ | 专业能力深度 | **Skeinn** | **Skeinn** |
243
+ | 冷交接连续性 | 平 | 平 |
244
+ | Oracle 与实证诚实度 | 平 | 平 |
245
+ | 用户负担与仪式感 | **Skeinn** | **Skeinn** |
246
+ | 性价比 | **Baseline** | **Baseline** |
247
+ | **总判** | **Skeinn** | **Skeinn** |
248
+
249
+ *诚实的边界:单次实验、单一场景、n=2 裁判。裁判引用的具体证据、baseline 的性价比胜利、以及我们发现的一处工件包元数据泄漏,见完整遥测与判决日志:[docs/eval/RELAY-001.md](docs/eval/RELAY-001.md)。*
250
+
219
251
  ---
220
252
 
221
253
  ## 文档导航
@@ -226,4 +258,5 @@ npm test
226
258
  | [UX 与闭环规范](docs/UX_FLOW.md) | 人、Agent、Keeper 与 Task 的完整转换 |
227
259
  | [提示词目录](docs/PROMPT_CATALOG.md) | 注入给 Agent 的全部认知层与模板 |
228
260
  | [Evil Eval 协议](EVIL_EVAL.md) | 有无框架的受控对照实验规范 |
229
- | [更新日志](CHANGELOG.md) | v2.4.0 及历次演进记录 |
261
+ | [RELAY-001 实测日志](docs/eval/RELAY-001.md) | DS-Flash 三棒接力的完整遥测与盲评判决 |
262
+ | [更新日志](CHANGELOG.md) | v2.5.0 及历次演进记录 |
package/cli/bin/skeinn.js CHANGED
@@ -17,10 +17,14 @@ import {
17
17
  createCapability,
18
18
  createDesign,
19
19
  exemptCapabilities,
20
+ recordCheckpoint,
20
21
  recordDecision,
22
+ resetKeeper,
23
+ resolveFinding,
21
24
  getCapability,
22
25
  getCapabilityStatus,
23
26
  getDesign,
27
+ getCheckpointPrompt,
24
28
  getKeeperPrompt,
25
29
  getTask,
26
30
  importTasks,
@@ -252,7 +256,8 @@ Required: outcome + acceptance[criterion/verify_by/evidence] + boundaries + exac
252
256
  implements|design_exemption + covers + depends_on. Recommended: guardrails[] (1–3 specialist red
253
257
  lines carried forward from capability/design). Canonical payload: skeinn task plan --help.
254
258
  Completion needs one acceptance_results entry per criterion; start/done refuse unclassified Tasks
255
- and missing declared outputs.`,
259
+ and missing declared outputs. Use kind: "spike" for pre-Launch empirical prototypes (delivery Tasks
260
+ cannot depend_on a spike; distill findings back into Design/Capability).`,
256
261
 
257
262
  deliverable: `skeinn deliverable — the delivery surface, decomposed
258
263
 
@@ -349,7 +354,7 @@ try {
349
354
  break;
350
355
  case 'context':
351
356
  case 'resume':
352
- output(compileContext({ taskId: option('--task'), keeper: argv.includes('--keeper'), full: argv.includes('--full'), humanChannel: humanChannel || 'available' }));
357
+ output(compileContext({ taskId: option('--task'), keeper: argv.includes('--keeper'), checkpoint: argv.includes('--checkpoint'), full: argv.includes('--full'), humanChannel: humanChannel || 'available' }));
353
358
  break;
354
359
  case 'prompts':
355
360
  output(promptCatalog());
@@ -377,8 +382,8 @@ try {
377
382
  break;
378
383
  }
379
384
  case 'project':
380
- if (subcommand !== 'ready') throw new Error('Usage: skeinn project ready');
381
- output(markReady());
385
+ if (subcommand !== 'ready') throw new Error('Usage: skeinn project ready [--force-round --reason <text>]');
386
+ output(markReady(undefined, { forceRound: argv.includes('--force-round'), reason: option('--reason') }));
382
387
  break;
383
388
  case 'design': {
384
389
  if (argv.includes('--help')) output(conceptHelp('design'));
@@ -477,7 +482,17 @@ try {
477
482
  else if (subcommand === 'prompt') output(getKeeperPrompt());
478
483
  else if (subcommand === 'record') output(recordKeeper(jsonFile()));
479
484
  else if (subcommand === 'skip') output(skipKeeper(option('--reason')));
480
- else throw new Error('Usage: skeinn keeper prompt|record|skip');
485
+ else if (subcommand === 'resolve') {
486
+ if (!rest[0]) throw new Error('Usage: skeinn keeper resolve <FND-ID> --evidence <proof>');
487
+ output(resolveFinding(rest[0], { evidence: option('--evidence') }));
488
+ } else if (subcommand === 'reset') {
489
+ output(resetKeeper(option('--reason')));
490
+ } else if (subcommand === 'checkpoint') {
491
+ const action = rest[0];
492
+ if (action === 'prompt') output(getCheckpointPrompt({ milestone: option('--milestone') }));
493
+ else if (action === 'record') output(recordCheckpoint(jsonFile()));
494
+ else throw new Error('Usage: skeinn keeper checkpoint prompt [--milestone <name>] | record --json-file <result.json>');
495
+ } else throw new Error('Usage: skeinn keeper prompt|record|skip|resolve|reset|checkpoint');
481
496
  break;
482
497
  }
483
498
  case 'eval':
@@ -355,13 +355,26 @@ ${assumptions.length ? `### Active assumptions\n\n${assumptions.map((item) => `-
355
355
  ${keeperFeedback}`;
356
356
  }
357
357
 
358
- export function keeperProtocol({ attemptNumber, preparedDigest } = {}) {
358
+ export function keeperProtocol({ attemptNumber, preparedDigest, deltaMode = false, dirtyArtifacts = [], horizonTaskIds = [] } = {}) {
359
359
  return `# Skeinn independent Keeper handoff
360
360
 
361
361
  You are a fresh Agent with no access to the shaping conversation. Do not repair the project and do not
362
362
  edit implementation. Use only this workspace and the Skeinn CLI. Run \`skeinn context --keeper\`, inspect
363
363
  the referenced files, and attempt a real handoff from disk.
364
364
 
365
+ ${deltaMode
366
+ ? `## DELTA RE-CHECK MODE (Attempt ${attemptNumber})
367
+
368
+ This is a follow-up verification round. Audit ONLY:
369
+ 1. Whether prior open blocking findings are genuinely closed with evidence, and
370
+ 2. Whether the artifacts modified in this repair (${dirtyArtifacts.length ? dirtyArtifacts.join(', ') : 'changed artifacts'}) introduced any new blocking contradiction.
371
+
372
+ Do NOT re-litigate unchanged sections outside the changed set. Any out-of-scope observation must be recorded as \`severity: "minor"\` with its concrete \`scope\` so it becomes a pinned advisory rather than reopening the loop.`
373
+ : `## PROGRESSIVE HORIZON SCOPE (Attempt ${attemptNumber || 1})
374
+
375
+ Focus blocking scrutiny on the active topological horizon (${horizonTaskIds.length ? horizonTaskIds.join(', ') : 'immediately executable tasks and their 1–2 hop successors'}) and the Design/Capability files they depend on. Do not demand distant future details upfront — issues affecting tasks outside the current horizon belong as \`severity: "minor"\` pinned to their target \`scope\` (e.g. \`TASK-055\` or \`.skeinn/design/auth.md\`).`
376
+ }
377
+
365
378
  Your job is a Crux review: check that the chain from responsible intent to verifiable behavior is intact.
366
379
  Do not judge document polish or count. Judge whether a fresh Agent could start from disk and still
367
380
  produce what the human actually wants — at specialist quality, not generic AI average.
@@ -438,7 +451,7 @@ does not block the first Task). Every revision requires fresh verification befor
438
451
  {
439
452
  "run_id": "<unique-id>",
440
453
  "prepared_digest": "<digest-above>",
441
- "verdict": "passed | needs_revision | blocked",
454
+ "verdict": "passed | passed_with_advisories | needs_revision | blocked",
442
455
  "review": {
443
456
  "mode": "independent | self",
444
457
  "reviewer_id": "<fresh Agent or current Agent identity>",
@@ -448,6 +461,7 @@ does not block the first Task). Every revision requires fresh verification befor
448
461
  "gaps": [
449
462
  {
450
463
  "gap": "<missing or contradictory truth>",
464
+ "scope": "<TASK-ID, .skeinn/design/<doc>.md, or project>",
451
465
  "severity": "blocking | minor",
452
466
  "why_it_blocks_start": "<concrete consequence for a fresh Agent>",
453
467
  "evidence_to_close": "<observable condition that would close it>"
@@ -461,16 +475,67 @@ Record the result with \`skeinn keeper record --json-file <result.json>\`. Use \
461
475
  a genuinely fresh Agent, could responsibly begin the first Task, and can record \`review.mode\` as
462
476
  \`independent\` with concrete isolation evidence.
463
477
  If you shaped this project, do not review your own work as independent; ask the host for a fresh Agent,
464
- or use \`skeinn keeper skip --reason <concrete limitation>\` when isolation is unavailable. Otherwise use
465
- \`needs_revision\` with concrete gaps and the
466
- observable evidence that would close each one, or \`blocked\` when progress requires unavailable
467
- authority or external state. A failed attempt returns the project to shaping; revision requires a
468
- changed digest and another fresh Keeper, including for minor gaps. Verify each prior finding
478
+ or use \`skeinn keeper skip --reason <concrete limitation>\` when isolation is unavailable. Use \`passed_with_advisories\` when ZERO blocking gaps remain in the active horizon and only \`minor\`
479
+ advisories exist — those advisories are pinned to their \`scope\` and surfaced automatically when the
480
+ affected Task starts, without wasting another full review round. Use \`needs_revision\` ONLY when at
481
+ least one \`blocking\` gap remains in the active horizon (or changed repair zone), or \`blocked\` when
482
+ progress requires unavailable authority or external state. Revision requires a changed digest and
483
+ another fresh Keeper. Verify each prior finding
469
484
  against its requested closure evidence before issuing a pass. For a revised pass, include
470
485
  \`closure_results: [{ "gap": "<exact prior gap text>", "evidence": "<observed closure proof>" }]\`
471
486
  covering every prior gap. These records are retained with the review.`;
472
487
  }
473
488
 
489
+
490
+ export function checkpointProtocol({ milestone = 'in-flight', dirtyArtifacts = [], openFindings = [], recentDoneTasks = [], preparedDigest = '' } = {}) {
491
+ return `# Skeinn independent In-Flight Checkpoint
492
+
493
+ You are a fresh Agent auditing an active build at milestone \`${milestone}\`. Do NOT rewrite code or
494
+ re-run full Launch review. Run \`skeinn context --checkpoint\` and inspect ONLY the incremental slice:
495
+
496
+ - Dirty / newly-entering horizon artifacts: ${dirtyArtifacts.length ? dirtyArtifacts.join(', ') : 'none (audit open findings & git diff)'}
497
+ - Delivery Tasks completed since last clean review (diff their touches against spec): ${recentDoneTasks.length ? recentDoneTasks.map((t) => `${t.id} "${t.title}"${t.implements ? ` implements ${t.implements}` : ''} → touches: ${t.touches.join(', ')}`).join(' | ') : 'none'}
498
+ - Open pinned findings in scope: ${openFindings.length ? openFindings.map((f) => `${f.id} [${f.scope}]: ${f.text}`).join(' | ') : 'none'}
499
+ - Snapshot digest: \`${preparedDigest || '<computed at record>'}\`
500
+
501
+ ## Checkpoint audit (3 focused checks)
502
+
503
+ 1. **Spec-to-Code drift**: Compare recent implementation changes against the referenced Design docs
504
+ and Capability guardrails. If code drifted from spec, require an explicit choice: fix the code OR
505
+ record \`skeinn decision\` to update the spec — never allow silent drift.
506
+ 2. **Newly entering horizon**: For any distant design/capability/task that just entered the active
507
+ horizon without prior review, verify it is buildable and contradiction-free.
508
+ 3. **Evidence & advisory closure**: Verify that claimed acceptance evidence is real (not false green)
509
+ and check whether open pinned findings have reproducible closure evidence.
510
+
511
+ Record your verdict with \`skeinn keeper checkpoint record --json-file <result.json>\`:
512
+
513
+ \`\`\`json
514
+ {
515
+ "run_id": "<unique-id>",
516
+ "milestone": "${milestone}",
517
+ "verdict": "clean | drift_detected | blocked",
518
+ "review": {
519
+ "mode": "independent",
520
+ "reviewer_id": "<fresh Agent identity>",
521
+ "evidence": "<how the host isolated this checkpoint review>"
522
+ },
523
+ "summary": "<concise in-flight audit judgment>",
524
+ "findings": [
525
+ {
526
+ "gap": "<concrete drift or newly discovered gap>",
527
+ "scope": "<TASK-ID or .skeinn/design/<doc>.md>",
528
+ "severity": "blocking | minor"
529
+ }
530
+ ],
531
+ "closure_results": [
532
+ { "id": "FND-001", "evidence": "<observed closure proof>" }
533
+ ],
534
+ "evidence": ["<file, diff, or test command supporting the verdict>"]
535
+ }
536
+ \`\`\``;
537
+ }
538
+
474
539
  export const PROJECT_TEMPLATE = `# Project Whole and Document Map
475
540
 
476
541
  > This is the concise entry point, not the container for every design decision. Describe the whole and