@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 +12 -0
- package/README.md +37 -5
- package/README.zh-CN.md +41 -8
- package/cli/bin/skeinn.js +20 -5
- package/cli/src/protocol.js +72 -7
- package/cli/src/store.js +484 -46
- package/design.md +36 -9
- package/docs/UX_FLOW.md +16 -4
- package/docs/eval/RELAY-001.md +115 -0
- package/package.json +1 -1
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**
|
|
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
|
|
61
|
-
|
|
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
|
-
|
|
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` (
|
|
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 口头宣布“已实现”,实测缺文件、漏边界或改坏上游 |
|
|
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. 确认整体方向 冻结摘要 →
|
|
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.
|
|
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
|
-
| [
|
|
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
|
|
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':
|
package/cli/src/protocol.js
CHANGED
|
@@ -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.
|
|
465
|
-
\`
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
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
|