@haaaiawd/skeinn 0.0.0-stage → 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.
@@ -0,0 +1,512 @@
1
+ #!/usr/bin/env node
2
+
3
+ import { readFileSync } from 'node:fs';
4
+ import { dirname, resolve } from 'node:path';
5
+ import { fileURLToPath } from 'node:url';
6
+ import {
7
+ addDeliverable,
8
+ blockTask,
9
+ checkProject,
10
+ checkDeliverableCoverage,
11
+ clarifyStatus,
12
+ closeClarify,
13
+ compileContext,
14
+ completeTask,
15
+ confirmCapability,
16
+ configureRuntime,
17
+ createCapability,
18
+ createDesign,
19
+ exemptCapabilities,
20
+ recordCheckpoint,
21
+ recordDecision,
22
+ resetKeeper,
23
+ resolveFinding,
24
+ getCapability,
25
+ getCapabilityStatus,
26
+ getDesign,
27
+ getCheckpointPrompt,
28
+ getKeeperPrompt,
29
+ getTask,
30
+ importTasks,
31
+ initProject,
32
+ listCapabilities,
33
+ listDeliverables,
34
+ listDesigns,
35
+ loadProject,
36
+ markReady,
37
+ recordKeeper,
38
+ recordUnderstanding,
39
+ reopenTask,
40
+ researchCapability,
41
+ resolveClarify,
42
+ scaffoldEval,
43
+ synthesizeCapability,
44
+ skipKeeper,
45
+ startClarify,
46
+ startTask,
47
+ taskSummary,
48
+ updateTask,
49
+ } from '../src/store.js';
50
+ import { promptCatalog } from '../src/protocol.js';
51
+
52
+ const argv = process.argv.slice(2);
53
+ const [command, subcommand, ...rest] = argv;
54
+
55
+ function output(value) {
56
+ console.log(typeof value === 'string' ? value : JSON.stringify(value, null, 2));
57
+ }
58
+
59
+ function fail(message) {
60
+ console.error(`Error: ${message}`);
61
+ process.exitCode = 1;
62
+ }
63
+
64
+ function option(name) {
65
+ const index = argv.indexOf(name);
66
+ return index === -1 ? undefined : argv[index + 1];
67
+ }
68
+
69
+ function jsonFile() {
70
+ const path = option('--json-file');
71
+ if (!path) throw new Error('This command requires --json-file <path>');
72
+ try {
73
+ return JSON.parse(readFileSync(resolve(path), 'utf8'));
74
+ } catch (error) {
75
+ throw new Error(`Cannot read JSON file ${path}: ${error.message}`);
76
+ }
77
+ }
78
+
79
+ function help() {
80
+ return `skeinn — continuity infrastructure for Agents
81
+
82
+ The human talks naturally to the Agent. The Agent uses these commands silently.
83
+
84
+ Typical flow (first pass):
85
+ 1. skeinn init — create .skeinn/ skeleton
86
+ 2. skeinn record — confirm facts, assumptions, open questions
87
+ 3. skeinn design add — one document per consequential decision surface,
88
+ comparing at least two viable alternatives; skipping
89
+ this makes PROJECT.md an unresumable monolith
90
+ 4. skeinn capability add — 1–3 single-file bottleneck domain specs (real
91
+ practitioner research + project reflection + Design
92
+ delta); skipping without skeinn capability exempt fails
93
+ ready and produces generic output
94
+ 5. skeinn deliverable add — decompose the delivery surface
95
+ 6. skeinn task plan — write Tasks with guardrails and acceptance criteria
96
+ 7. skeinn project ready — freeze a digest for Keeper review
97
+ 8. skeinn keeper prompt → record — fresh Agent runs integrity & anti-laziness audit
98
+ 9. skeinn task start → done — execute one Task at a time, fill acceptance evidence
99
+ 10. skeinn check — verify health, coverage, stale dependents, and drift
100
+
101
+ Steps 3–6 iterate together: Design surfaces hard decisions; Capability researches how real
102
+ practitioners solve them and feeds operational rules + Design delta back into Design. Run
103
+ \`skeinn help <concept>\` for purpose and quality bar: shaping, design, capability, task, deliverable.
104
+
105
+ When a new idea changes an existing decision:
106
+ skeinn decision --json-file <decision.json> — record what changed and affected tasks
107
+ then update the design document directly; skeinn check warns which done tasks need reopening.
108
+
109
+ When the human changes direction, requests a redesign, or contradicts project truth:
110
+ skeinn clarify start --reason <what changed> — pause work, open an inquiry round
111
+ ask ONE batch of material questions in conversation, then:
112
+ skeinn clarify resolve --json-file <round.json> — record answers/decisions/new questions
113
+ skeinn clarify close — close once every round question is resolved
114
+ or skipped, then cascade the answers into design documents and Tasks.
115
+
116
+ Start and resume
117
+ skeinn init
118
+ skeinn context [--task TASK-001] [--keeper] [--full] [--human-channel available|unavailable]
119
+ (default returns state + Task context; --full restores the complete protocol)
120
+ skeinn check
121
+ skeinn prompts
122
+
123
+ Preserve understanding
124
+ skeinn record --json-file <update.json>
125
+ skeinn decision --json-file <decision.json>
126
+ skeinn project ready
127
+ skeinn design add <slug> --title <text> --kind <product|experience|system|contract|verification|operations|research>
128
+ skeinn design list|get <slug>
129
+ skeinn capability add <slug> --title <professional-field> [--mode external_researched|codebase_grounded|offline_reflection]
130
+ skeinn capability list|get|status <slug>
131
+ skeinn capability confirm <slug> --scenario <text> --source human|agent
132
+ — optional authority upgrade (human_confirmed vs agent_provisional)
133
+ skeinn capability exempt --reason <text>
134
+ — explicit exemption when standard engineering suffices (audited by Keeper)
135
+
136
+ Map the delivery surface
137
+ skeinn deliverable add <slug> --title <text> --kind <module|feature|behavior|interface|artifact|operational|verification|other>
138
+ skeinn deliverable list
139
+ skeinn deliverable coverage
140
+
141
+ Maintain the work map
142
+ skeinn task plan --json-file <tasks.json>
143
+ skeinn task status|next|get <id>
144
+ skeinn task start <id>
145
+ skeinn task update <id> --json-file <patch.json>
146
+ skeinn task block <id> --json-file <block.json>
147
+ skeinn task reopen <id> [--reason <reason>]
148
+ skeinn task done <id> --json-file <evidence.json>
149
+
150
+ Each Task should produce one verifiable unit of real work. Use acceptance[] with criterion,
151
+ verify_by, and evidence fields, plus guardrails[] for key specialist red lines. Task completion
152
+ fills in each acceptance condition's evidence with the actual result (for acceptance tasks) or
153
+ quotes each done_when criterion (for legacy tasks).
154
+
155
+ One-time independent handoff
156
+ skeinn review [--help] — Keeper handoff and stage-review guide
157
+ skeinn keeper --help — read-only guide in any project state
158
+ skeinn keeper prompt
159
+ skeinn keeper record --json-file <result.json>
160
+ skeinn keeper skip --reason <reason>
161
+
162
+ Evaluate Skeinn itself
163
+ skeinn eval scaffold --json-file <scenario.json>
164
+
165
+ Use \`--state-dir <outside-workspace-dir>\` on every command to keep Skeinn state in an isolated sidecar
166
+ (for example, a benchmark runner's per-run state directory). Sidecar initialization never edits AGENTS.md.
167
+
168
+ Use \`skeinn <command> --help\` or \`skeinn help <topic>\` for canonical JSON payloads. Topics:
169
+ record, decision, task-plan, task-update, task-block, task-done, keeper-record, eval-scaffold
170
+ Conceptual guidance topics: shaping, design, capability, task, deliverable, clarify
171
+
172
+ Use JSON files for structured writes so long content and shell quoting remain auditable.
173
+ Task completion JSON includes evidence plus either acceptance_results[] (one per acceptance criterion,
174
+ each with concrete evidence) or checks[] (one per done_when criterion, for legacy tasks).`;
175
+ }
176
+
177
+ const STRUCTURED_HELP = {
178
+ record: {
179
+ usage: 'skeinn record --json-file <update.json>',
180
+ example: {
181
+ confirmed: ['A fact confirmed by the human or workspace.'],
182
+ assumptions: [{ text: 'A bounded, reversible Agent assumption.', source: 'agent' }],
183
+ unresolved: [{ question: 'A consequential question still open?', impact: 'high' }],
184
+ resolved: [{ id: 'Q-001', status: 'resolved' }],
185
+ retire_assumptions: ['A-001'],
186
+ decisions: [{ title: 'Decision title', decision: 'Current decision.', rationale: 'Why it follows.', supersedes: [], affects: ['.skeinn/PROJECT.md'] }],
187
+ },
188
+ },
189
+ decision: {
190
+ usage: 'skeinn decision --json-file <decision.json>',
191
+ example: { summary: 'What changed and why.', changes: ['.skeinn/design/system.md', 'src/system.js'], affected_tasks: ['TASK-001'] },
192
+ },
193
+ 'task-plan': {
194
+ usage: 'skeinn task plan --json-file <tasks.json>',
195
+ example: { tasks: [{ title: 'Create one verifiable result', outcome: 'A concrete artifact behaves as specified.', acceptance: [{ criterion: 'Observable condition', verify_by: 'Exact command or review method', evidence: '' }], boundaries: ['Does not change unrelated behavior'], guardrails: ['Concrete specialist red line inherited from capability/design'], depends_on: [], reads: ['.skeinn/PROJECT.md', '.skeinn/design/system.md'], touches: ['src/result.js'], implements: '.skeinn/design/system.md#Responsibility', covers: ['DLV-001'] }] },
196
+ },
197
+ 'task-update': {
198
+ usage: 'skeinn task update <id> --json-file <patch.json>',
199
+ example: { progress: { completed: ['Finished checkpoint'], current: 'Verifying behavior', next: 'Run the named acceptance check' } },
200
+ },
201
+ 'task-block': {
202
+ usage: 'skeinn task block <id> --json-file <block.json>',
203
+ example: { reason: 'A concrete dependency or authority is unavailable.', recovery_conditions: ['Observable condition that permits resuming'], evidence: ['Inspection or command output showing the block'] },
204
+ },
205
+ 'task-done': {
206
+ usage: 'skeinn task done <id> --json-file <evidence.json>',
207
+ example: { evidence: ['Overall reproducible verification result'], acceptance_results: [{ criterion: 'Exact acceptance criterion from the Task', evidence: 'Concrete command, artifact, or observation' }] },
208
+ },
209
+ 'keeper-record': {
210
+ usage: 'skeinn keeper record --json-file <result.json>',
211
+ example: { run_id: 'fresh-agent-run-001', prepared_digest: '<digest from skeinn project ready>', verdict: 'passed', review: { mode: 'independent', reviewer_id: 'fresh-agent-001', evidence: 'Host opened a separate Agent without the shaping conversation.' }, summary: 'Build-readiness judgment.', gaps: [], evidence: ['Files and observations supporting the verdict'] },
212
+ },
213
+ 'eval-scaffold': {
214
+ usage: 'skeinn eval scaffold --json-file <scenario.json>',
215
+ example: { id: 'EVAL-001', title: 'Offline tool 3-baton relay', mode: 'relay', budget_cny: 20, brief: 'Identical brief for both conditions.', pivot: 'Mid-flight requirement change injected at Baton 2.', hidden_user_facts: ['Fact revealed by the same answer script'], hidden_checks: ['Zero external network calls', 'Reload restores state'], human_channel: 'unavailable', success_criteria: ['Fresh Agent finishes Baton 2 and Baton 3 without regressions'], repetitions: 1 },
216
+ },
217
+ 'clarify-resolve': {
218
+ usage: 'skeinn clarify resolve --json-file <round.json>',
219
+ example: { answers: [{ id: 'Q-001', resolution: 'User confirmed the new direction' }, { question: 'Inline question', resolution: 'Answer recorded as a confirmed fact' }], confirmed: ['New confirmed fact'], retire_assumptions: ['A-001'], decisions: [{ title: 'Decision title', decision: 'Current decision.', rationale: 'Why it follows.', supersedes: [], affects: ['.skeinn/design/x.md'] }], new_questions: [{ question: 'Still open?', recommendation: 'Your recommended answer', impact: 'high' }] },
220
+ },
221
+ };
222
+
223
+ const CONCEPT_HELP = {
224
+ shaping: `skeinn shaping — the iterative loop that makes a project resumable and strong
225
+
226
+ record → iterate Design & 1–3 bottleneck Capabilities → deliverable → task plan → project ready.
227
+ Design surfaces the hard decisions; Capabilities research how real practitioners solve them and feed
228
+ operational rules + Before -> After Design delta back into Design. No silent Capability skips: add
229
+ 1–3 bottleneck domains or explicitly record skeinn capability exempt --reason.
230
+ Per-layer details: skeinn help capability | design | deliverable | task`,
231
+
232
+ design: `skeinn design — one document per consequential decision surface
233
+
234
+ Owns the decisions a fresh Agent must verify independently; skipping it makes PROJECT.md an
235
+ unresumable monolith, and template text fails skeinn project ready. Core design docs (product,
236
+ experience, system, contract) compare at least two genuinely viable alternatives (no strawmen),
237
+ compile applied capability rules into mechanisms, and name how the work could look done yet fail.
238
+ skeinn design add <slug> --title <text> --kind <product|experience|system|contract|verification|operations|research>
239
+ Tasks link to it via implements or a concrete design_exemption.`,
240
+
241
+ capability: `skeinn capability — real practitioner research + project reflection, in one file
242
+
243
+ One single .md file per recognizable field (focus on the 1–3 bottleneck domains that truly raise the
244
+ project's ceiling). Three sections:
245
+ 1. How real practitioners operate (verifiable external sources; never agent-authored filler)
246
+ 2. Reflection for this project (what fits, what to adapt/refuse, where ordinary AI feels amateur)
247
+ 3. Operational rules and Design delta (quality bar, tradeoffs & flip conditions, anti-patterns,
248
+ verification probes, and Before -> After Design delta)
249
+ Commands: skeinn capability add <slug> --title <field> [--mode external_researched|codebase_grounded|offline_reflection]
250
+ Optional authority upgrade: skeinn capability confirm <slug> --scenario <text> --source human|agent
251
+ Explicit skip when standard engineering suffices: skeinn capability exempt --reason <text>`,
252
+
253
+ task: `skeinn task — one verifiable unit of real work
254
+
255
+ Required: outcome + acceptance[criterion/verify_by/evidence] + boundaries + exact reads/touches +
256
+ implements|design_exemption + covers + depends_on. Recommended: guardrails[] (1–3 specialist red
257
+ lines carried forward from capability/design). Canonical payload: skeinn task plan --help.
258
+ Completion needs one acceptance_results entry per criterion; start/done refuse unclassified Tasks
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).`,
261
+
262
+ deliverable: `skeinn deliverable — the delivery surface, decomposed
263
+
264
+ One deliverable is one observable thing the project must produce. Tasks claim coverage
265
+ via covers; skeinn deliverable coverage separates planned from delivered.
266
+ Commands: skeinn deliverable add|list|coverage.`,
267
+
268
+ clarify: `skeinn clarify — frontier inquiry for direction changes
269
+
270
+ Open when the human changes direction, requests a redesign, or contradicts project
271
+ truth. Pause material work, ask the current frontier in one batch (each question with
272
+ a recommended answer; look facts up, don't ask them), then skeinn clarify resolve
273
+ records it and skeinn clarify close refuses while any round question stays open.
274
+ Payload: skeinn clarify resolve --help. Small feedback needs no round — fix directly.`,
275
+ };
276
+
277
+ function conceptHelp(topic) {
278
+ const entry = CONCEPT_HELP[topic];
279
+ if (!entry) return null;
280
+ return entry;
281
+ }
282
+
283
+ function structuredHelp(topic) {
284
+ if (['keeper', 'review', 'keeper-prompt'].includes(topic)) return reviewHelp();
285
+ if (topic === 'keeper-record') return `${STRUCTURED_HELP[topic].usage}\n\nCanonical JSON payload:\n${JSON.stringify(STRUCTURED_HELP[topic].example, null, 2)}\n\nFor a revised pass, add closure_results: [{"gap":"<exact prior gap text>","evidence":"<observed closure proof>"}] for every prior gap. Minor gaps require fresh verification too.`;
286
+ const entry = STRUCTURED_HELP[topic];
287
+ if (!entry) {
288
+ const concept = conceptHelp(topic);
289
+ if (concept) return concept;
290
+ throw new Error(`Unknown help topic: ${topic}. Payload topics: ${Object.keys(STRUCTURED_HELP).join(', ')}. Concept topics: ${Object.keys(CONCEPT_HELP).join(', ')}`);
291
+ }
292
+ return `${entry.usage}\n\nCanonical JSON payload:\n${JSON.stringify(entry.example, null, 2)}`;
293
+ }
294
+
295
+ function reviewHelp() {
296
+ return `Skeinn review guide
297
+
298
+ Keeper is the first build-readiness handoff. Stage reviews use ordinary Tasks.
299
+ This guide is read-only and available before initialization or project readiness.
300
+
301
+ Keeper handoff:
302
+ 1. The shaping Agent runs skeinn project ready after preparing project truth.
303
+ 2. The host opens a fresh Agent without inherited conversation. Give it the workspace
304
+ path, the CLI location (absolute path in source checkouts), and this instruction:
305
+ Run skeinn keeper prompt, then skeinn context --keeper, and inspect the referenced files.
306
+ 3. The fresh Agent records its verdict with skeinn keeper record --json-file <result.json>.
307
+ See skeinn keeper record --help for the payload and independent review provenance.
308
+ 4. The parent waits for the result, then runs skeinn context. On needs_revision or blocked,
309
+ repair the named sources, prepare again, and obtain a fresh review, including minor gaps.
310
+ 5. On passed, resume with skeinn task next and skeinn task start <id>.
311
+ If isolation is unavailable, explicitly record skeinn keeper skip --reason <limitation>.
312
+ The CLI prints instructions and records state; it does not launch Agents itself.
313
+
314
+ Stage review:
315
+ Use skeinn task plan --help to create a review Task naming the implementation, design,
316
+ and verification artifacts in reads. Record each finding as a repair Task with concrete
317
+ acceptance criteria and evidence. Block the review Task with skeinn task block until repairs
318
+ are ready; reopen it and re-run verification before skeinn task done. A completed repair
319
+ alone is not a completed review. No findings: close the review Task with inspection evidence.
320
+ Do not rerun first-time Keeper just to review every implementation Task.`;
321
+ }
322
+
323
+ function activeStructuredHelpTopic() {
324
+ if (command === 'record' || command === 'decision') return command;
325
+ if (command === 'clarify' && subcommand === 'resolve') return 'clarify-resolve';
326
+ if (command === 'task' && ['plan', 'update', 'block', 'done'].includes(subcommand)) return `task-${subcommand}`;
327
+ if (command === 'keeper' && subcommand === 'record') return 'keeper-record';
328
+ if (command === 'eval' && subcommand === 'scaffold') return 'eval-scaffold';
329
+ return '';
330
+ }
331
+
332
+ try {
333
+ configureRuntime({ stateDir: option('--state-dir') });
334
+ const humanChannel = option('--human-channel');
335
+ if (humanChannel && !['available', 'unavailable'].includes(humanChannel)) throw new Error('--human-channel must be available or unavailable');
336
+ switch (command) {
337
+ case '--version':
338
+ case '-v': {
339
+ const here = dirname(fileURLToPath(import.meta.url));
340
+ const pkg = JSON.parse(readFileSync(resolve(here, '..', '..', 'package.json'), 'utf8'));
341
+ output(`skeinn ${pkg.version}`);
342
+ break;
343
+ }
344
+ case '--help':
345
+ case '-h':
346
+ case undefined:
347
+ output(help());
348
+ break;
349
+ case 'help':
350
+ output(subcommand ? structuredHelp(subcommand) : help());
351
+ break;
352
+ case 'init':
353
+ output(initProject());
354
+ break;
355
+ case 'context':
356
+ case 'resume':
357
+ output(compileContext({ taskId: option('--task'), keeper: argv.includes('--keeper'), checkpoint: argv.includes('--checkpoint'), full: argv.includes('--full'), humanChannel: humanChannel || 'available' }));
358
+ break;
359
+ case 'prompts':
360
+ output(promptCatalog());
361
+ break;
362
+ case 'record':
363
+ output(subcommand === '--help' ? structuredHelp('record') : recordUnderstanding(jsonFile()));
364
+ break;
365
+ case 'clarify': {
366
+ if (argv.includes('--help') && subcommand === 'resolve') output(structuredHelp('clarify-resolve'));
367
+ else if (subcommand === '--help' || (argv.includes('--help') && !subcommand)) output(conceptHelp('clarify'));
368
+ else if (subcommand === 'start') output(startClarify({ reason: option('--reason') }));
369
+ else if (subcommand === 'resolve') output(resolveClarify(jsonFile()));
370
+ else if (subcommand === 'close') output(closeClarify());
371
+ else if (!subcommand || subcommand === 'status') output(clarifyStatus());
372
+ else throw new Error('Usage: skeinn clarify start|resolve|close|status');
373
+ break;
374
+ }
375
+ case 'decision':
376
+ output(subcommand === '--help' ? structuredHelp('decision') : recordDecision(jsonFile()));
377
+ break;
378
+ case 'check': {
379
+ const result = checkProject();
380
+ output(result);
381
+ if (!result.healthy) process.exitCode = 1;
382
+ break;
383
+ }
384
+ case 'project':
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') }));
387
+ break;
388
+ case 'design': {
389
+ if (argv.includes('--help')) output(conceptHelp('design'));
390
+ else if (subcommand === 'add') {
391
+ const slug = rest[0];
392
+ const title = option('--title');
393
+ const kind = option('--kind');
394
+ if (!slug) throw new Error('Usage: skeinn design add <slug> --title <text> --kind <kind>');
395
+ output(createDesign(slug, { title, kind }));
396
+ } else if (subcommand === 'list') output(listDesigns());
397
+ else if (subcommand === 'get') {
398
+ if (!rest[0]) throw new Error('Usage: skeinn design get <slug>');
399
+ output(getDesign(rest[0]));
400
+ } else if (!subcommand) output(conceptHelp('design'));
401
+ else throw new Error('Usage: skeinn design add|list|get');
402
+ break;
403
+ }
404
+ case 'capability': {
405
+ if (argv.includes('--help')) output(conceptHelp('capability'));
406
+ else if (subcommand === 'add') {
407
+ const slug = rest[0];
408
+ const title = option('--title');
409
+ const mode = option('--mode');
410
+ if (!slug) throw new Error('Usage: skeinn capability add <slug> --title <text> [--mode external_researched|codebase_grounded|offline_reflection]');
411
+ output(createCapability(slug, { title, mode }));
412
+ } else if (subcommand === 'exempt') {
413
+ output(exemptCapabilities(option('--reason')));
414
+ } else if (subcommand === 'list') output(listCapabilities());
415
+ else if (subcommand === 'get') {
416
+ if (!rest[0]) throw new Error('Usage: skeinn capability get <slug>');
417
+ output(getCapability(rest[0]));
418
+ } else if (subcommand === 'research') {
419
+ if (!rest[0]) throw new Error('Usage: skeinn capability research <slug> --field <text>');
420
+ output(researchCapability(rest[0], { field: option('--field') }));
421
+ } else if (subcommand === 'synthesize') {
422
+ if (!rest[0]) throw new Error('Usage: skeinn capability synthesize <slug>');
423
+ output(synthesizeCapability(rest[0]));
424
+ } else if (subcommand === 'confirm') {
425
+ if (!rest[0]) throw new Error('Usage: skeinn capability confirm <slug> --scenario <text> --source human|agent');
426
+ output(confirmCapability(rest[0], { scenario: option('--scenario'), source: option('--source') }));
427
+ } else if (subcommand === 'status') {
428
+ if (!rest[0]) throw new Error('Usage: skeinn capability status <slug>');
429
+ output(getCapabilityStatus(rest[0]));
430
+ } else if (!subcommand) output(conceptHelp('capability'));
431
+ else throw new Error('Usage: skeinn capability add|exempt|list|get|status|confirm');
432
+ break;
433
+ }
434
+ case 'deliverable': {
435
+ if (argv.includes('--help')) output(conceptHelp('deliverable'));
436
+ else if (subcommand === 'add') {
437
+ const slug = rest[0];
438
+ const title = option('--title');
439
+ const kind = option('--kind');
440
+ if (!slug) throw new Error('Usage: skeinn deliverable add <slug> --title <text> --kind <module|feature|behavior|interface|artifact|operational|verification|other>');
441
+ output(addDeliverable(slug, { title, kind, notes: option('--notes') }));
442
+ } else if (subcommand === 'list') output(listDeliverables());
443
+ else if (subcommand === 'coverage') output(checkDeliverableCoverage());
444
+ else if (!subcommand) output(conceptHelp('deliverable'));
445
+ else throw new Error('Usage: skeinn deliverable add|list|coverage');
446
+ break;
447
+ }
448
+ case 'task': {
449
+ if (argv.includes('--help') && ['plan', 'update', 'block', 'done'].includes(subcommand)) output(structuredHelp(`task-${subcommand}`));
450
+ else if (subcommand === 'plan') output(importTasks(jsonFile()));
451
+ else if (subcommand === 'status') output(taskSummary(loadProject().taskStore.tasks));
452
+ else if (subcommand === 'next') output(getTask());
453
+ else if (subcommand === 'get') {
454
+ if (!rest[0]) throw new Error('Usage: skeinn task get <id>');
455
+ output(getTask(rest[0]));
456
+ } else if (subcommand === 'start') {
457
+ if (!rest[0]) throw new Error('Usage: skeinn task start <id>');
458
+ output(startTask(rest[0]));
459
+ } else if (subcommand === 'update') {
460
+ if (!rest[0]) throw new Error('Usage: skeinn task update <id> --json-file <patch.json>');
461
+ output(updateTask(rest[0], jsonFile()));
462
+ } else if (subcommand === 'block') {
463
+ if (!rest[0]) throw new Error('Usage: skeinn task block <id> --json-file <block.json>');
464
+ output(blockTask(rest[0], jsonFile()));
465
+ } else if (subcommand === 'reopen') {
466
+ if (!rest[0]) throw new Error('Usage: skeinn task reopen <id>');
467
+ output(reopenTask(rest[0], { reason: option('--reason') }));
468
+ } else if (subcommand === 'done') {
469
+ if (!rest[0]) throw new Error('Usage: skeinn task done <id> --json-file <evidence.json>');
470
+ output(completeTask(rest[0], jsonFile()));
471
+ } else if (!subcommand || argv.includes('--help')) output(conceptHelp('task'));
472
+ else throw new Error('Usage: skeinn task plan|status|next|get|start|update|block|reopen|done');
473
+ break;
474
+ }
475
+ case 'review':
476
+ if (subcommand && subcommand !== '--help') throw new Error('Usage: skeinn review [--help]');
477
+ output(reviewHelp());
478
+ break;
479
+ case 'keeper': {
480
+ if (argv.includes('--help') && subcommand === 'record') output(structuredHelp('keeper-record'));
481
+ else if (!subcommand || argv.includes('--help')) output(reviewHelp());
482
+ else if (subcommand === 'prompt') output(getKeeperPrompt());
483
+ else if (subcommand === 'record') output(recordKeeper(jsonFile()));
484
+ else if (subcommand === 'skip') output(skipKeeper(option('--reason')));
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');
496
+ break;
497
+ }
498
+ case 'eval':
499
+ if (argv.includes('--help') && subcommand === 'scaffold') output(structuredHelp('eval-scaffold'));
500
+ else {
501
+ if (subcommand !== 'scaffold') throw new Error('Usage: skeinn eval scaffold --json-file <scenario.json>');
502
+ output(scaffoldEval(jsonFile()));
503
+ }
504
+ break;
505
+ default:
506
+ throw new Error(`Unknown command: ${command}\n\n${help()}`);
507
+ }
508
+ } catch (error) {
509
+ const topic = activeStructuredHelpTopic();
510
+ const pointer = topic && !argv.includes('--help') ? `\nRun ${STRUCTURED_HELP[topic].usage.replace(/ --json-file .+$/, ' --help').replace(/ <id>/, '')} for a canonical payload.` : '';
511
+ fail(`${error.message}${pointer}`);
512
+ }