@ngockhoale/ukit 3.5.3 → 3.5.5

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.
Files changed (70) hide show
  1. package/CHANGELOG.md +36 -0
  2. package/manifests/documentation.yaml +12 -1
  3. package/manifests/platform.full.yaml +12 -0
  4. package/package.json +29 -2
  5. package/src/cli/commands/doctor.js +41 -0
  6. package/src/cli/commands/indexTools.js +10 -4
  7. package/src/cli/commands/memory.js +88 -6
  8. package/src/core/memory/episodes.js +106 -7
  9. package/src/core/memory/memoryCheck.js +241 -0
  10. package/src/core/memory/memoryCheckRun.js +39 -0
  11. package/src/core/memory/memoryHit.js +31 -15
  12. package/src/core/memory/mutateMemory.js +37 -1
  13. package/src/core/memory/observations.js +192 -0
  14. package/src/core/memory/recallEngine.js +159 -10
  15. package/src/core/memory/recallLanes.js +182 -0
  16. package/src/core/memory/records.js +23 -0
  17. package/src/core/memory/retrieval.js +13 -1
  18. package/src/core/memory/topicCommand.js +75 -0
  19. package/src/core/memory/topicPages.js +545 -0
  20. package/src/core/memory/writeGate.js +137 -0
  21. package/src/core/runtimeConfig.js +56 -1
  22. package/src/decision/registry.js +17 -0
  23. package/src/index/buildIndex.js +312 -5
  24. package/src/index/languageTools.js +100 -0
  25. package/src/index/paths.js +4 -1
  26. package/src/index/queryIndex.js +356 -14
  27. package/src/index/resolveContext.js +1 -1
  28. package/template_project/.claude/hooks/edit-hint.mjs +64 -17
  29. package/template_project/.claude/hooks/session-episode-start.mjs +35 -0
  30. package/template_project/.claude/hooks/session-episode.sh +9 -4
  31. package/template_project/.claude/settings.json +2 -2
  32. package/template_project/.claude/ukit/index/lib/index-core.mjs +769 -18
  33. package/template_project/.claude/ukit/index/query-index.mjs +14 -3
  34. package/template_project/.claude/ukit/index/refresh-index.mjs +11 -0
  35. package/template_project/.claude/ukit/index/route-task.mjs +4 -1
  36. package/template_project/.claude/ukit/runtime/memory-check.mjs +241 -0
  37. package/template_project/.claude/ukit/runtime/memory-lanes.mjs +9 -2
  38. package/template_project/.claude/ukit/runtime/memory-recall.mjs +159 -10
  39. package/template_project/.claude/ukit/runtime/memory-topics.mjs +545 -0
  40. package/template_project/.claude/ukit/runtime/memory-validity.mjs +28 -1
  41. package/template_project/.claude/ukit/runtime/self-improve-trigger.mjs +212 -5
  42. package/template_project/.omp/hooks/pre/ukit-bridge.js +2 -1
  43. package/template_project/ukit/storage/config.json +21 -2
  44. package/manifests/instructionRules.yaml +0 -442
  45. package/src/core/agentRuntime/completionGate.js +0 -179
  46. package/src/core/agentRuntime/context.js +0 -571
  47. package/src/core/agentRuntime/qualityComparison.js +0 -112
  48. package/src/core/agentRuntime/resourcePolicy.js +0 -78
  49. package/src/core/agentRuntime/runtimeSupport.js +0 -255
  50. package/src/core/codeintel/manifest.js +0 -176
  51. package/src/core/experiments/deliberation.js +0 -327
  52. package/src/core/experiments/dynamicWorkflow.js +0 -507
  53. package/src/core/handoffDocValidator.js +0 -154
  54. package/src/core/memory/deltaOverlays.js +0 -493
  55. package/src/core/memory/learningCandidates.js +0 -347
  56. package/src/core/observability/emit/sessionBoot.js +0 -407
  57. package/src/core/observability/evaluation/replay.js +0 -149
  58. package/src/core/observability/evaluation/scorecard.js +0 -465
  59. package/src/core/observability/schema/compatibility.js +0 -180
  60. package/src/core/observability/support/renderer.js +0 -130
  61. package/src/core/reviewPanelAggregate.js +0 -204
  62. package/src/core/taskBudgetValidator.js +0 -251
  63. package/src/core/taskProgressGuard.js +0 -227
  64. package/src/decision/reviewVerdict.js +0 -339
  65. package/src/decision/runtimeFilter.js +0 -150
  66. package/src/decision/runtimeScheduler.js +0 -239
  67. package/src/index/contextPack.js +0 -285
  68. package/src/index/impactContext.js +0 -360
  69. package/src/index/reviewPolicy.js +0 -368
  70. package/src/index/sensitivePath.js +0 -21
@@ -1,442 +0,0 @@
1
- version: 1
2
- generated: false
3
- description: >-
4
- Canonical rule-ID catalog for the root instruction contracts. Marker comments
5
- <!-- RULE: ID --> tag normative behavior; semantic tests prove delivery.
6
- # marker_in values are drawn from the fixed set of the four marker-bearing
7
- # contract files {template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md}.
8
- # template_project/.omp/RULES.md and .omp/RULES.md are marker-free by SPEC §7.1 policy
9
- # and must never appear here.
10
- # DEVIATION from SPEC §7.2 table: OWN-01 is marker_in: AGENTS set only (not
11
- # SHARED) — its anchor `PROJECT_IMPORTANT.md` does not exist in the CLAUDE
12
- # files, and markers are comment-only (no prose edits allowed). AGENTS-set
13
- # coverage matches the HOST-OC-01/HOST-OWN-01 rows that tag the same overlay.
14
- # paths (optional, DOC-302): list of repo-relative glob strings naming the
15
- # work-tree scope a rule applies to. `**` = any depth, `*` = one segment,
16
- # `?` = one char; `/`-separated, no leading `/`, no `..`, no backslashes.
17
- # Absent = file-scoped only (marker_in governs rendered coverage; paths is
18
- # metadata for future router/doc tooling, consumed by rulesForPath).
19
- rules:
20
- - id: CORE-01
21
- title: One remembered command — ukit install
22
- kind: critical
23
- statement: >-
24
- Human-facing UKit workflow collapses to one remembered command:
25
- `ukit install`; after install, work in natural language inside the
26
- supported harnesses.
27
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
28
- anchor: 'ukit install'
29
- - id: CORE-02
30
- title: Quality first, then speed, then token discipline
31
- kind: supporting
32
- statement: >-
33
- Ordering of priorities for all work: quality first, then speed, then
34
- token discipline.
35
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
36
- - id: CLS-01
37
- title: Trivial lane acts directly
38
- kind: critical
39
- statement: >-
40
- Trivial tasks (typo, label, small rename, spacing, toggle flag, obvious
41
- config change) act directly — no doc reads, planning, index, or agents.
42
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
43
- anchor: 'Act directly'
44
- - id: CLS-02
45
- title: Simple lane pulls smallest useful context
46
- kind: critical
47
- statement: >-
48
- Simple tasks (1-2 files, clear scope, existing pattern) are handled
49
- directly, pulling only the smallest useful context.
50
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
51
- anchor: 'smallest useful context'
52
- - id: CLS-03
53
- title: Non-trivial lane verifies harder
54
- kind: supporting
55
- statement: >-
56
- Non-trivial/risky tasks read deeper, verify harder, and use the
57
- index-first loop then skill activation then targeted verification.
58
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
59
- - id: EXEC-01
60
- title: Continue until write evidence or blocker
61
- kind: critical
62
- statement: >-
63
- For explicit implement/apply/fix requests, continue until the actual edit
64
- is made or a real blocker is found; never stop after read-only steps.
65
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
66
- anchor: 'actual edit is made'
67
- - id: EXEC-02
68
- title: No done-claims without Edit/Write evidence
69
- kind: critical
70
- statement: >-
71
- Completion wording requires concrete Edit/Write evidence in the current
72
- turn, plus verification when the scope is risky.
73
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
74
- anchor: 'concrete Edit/Write evidence'
75
- - id: EXEC-03
76
- title: Routed continuation is not a stopping point
77
- kind: supporting
78
- statement: >-
79
- Routed states like pull-indexed-context or continuation-required are
80
- internal continuation steps; finish the named milestone before widening.
81
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
82
- - id: EXEC-04
83
- title: Every stop names its reason
84
- kind: critical
85
- statement: >-
86
- When a turn ends on a user-only action, open the reply with a
87
- `WAITING ON YOU:` line and schedule a one-shot wakeup when available.
88
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
89
- anchor: 'WAITING ON YOU'
90
- - id: STALL-01
91
- title: Announce waits, verbatim errors, never blame UKit
92
- kind: critical
93
- statement: >-
94
- Long waits must be announced as they happen, any API/tool error surfaced
95
- verbatim in the same turn, and network/API named as the suspect on long
96
- stalls — never blaming UKit.
97
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
98
- anchor: 'never blame UKit'
99
- - id: STALL-02
100
- title: Stall rules extend every-stop-says-why
101
- kind: supporting
102
- statement: >-
103
- The stall/wait reporting rules extend the existing every-stop-names-its-
104
- reason contract (EXEC-04); they do not replace it.
105
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
106
- - id: STALL-03
107
- title: One-tool-call workaround is conditional only
108
- kind: critical
109
- statement: >-
110
- Falling back to one tool call per assistant message is a conditional
111
- workaround that fires only when malformed/concatenated tool-input errors
112
- are observed or the harness version is known-affected — healthy hosts
113
- keep using legitimate parallel calls.
114
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
115
- anchor: 'one tool call per assistant message'
116
- - id: UNATTENDED-01
117
- title: Unattended mode runs the completion loop without a human
118
- kind: critical
119
- statement: >-
120
- Under orchestration.permissionMode: unattended there is no human in the
121
- loop — the loop is UNDERSTAND → PLAN → IMPLEMENT → VERIFY → FIX →
122
- REVERIFY → COMPLETE, and a turn ends only on COMPLETE evidence, a real
123
- external blocker, or a deny decision. Workflow phases do not authorize
124
- changing the user-owned host permission mode: internal PLAN is not host
125
- Plan Mode. Honor managed policy, newer user choices, and parent/subagent
126
- and session boundaries.
127
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
128
- anchor: 'no human in the loop'
129
- - id: UNATTENDED-02
130
- title: Bounded attempts and recovery strategies in unattended mode
131
- kind: supporting
132
- statement: >-
133
- maxAttemptsPerFailure: 2 per failing verification and
134
- maxRecoveryStrategies: 2 distinct fix strategies before reassessing —
135
- do not loop one strategy.
136
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
137
- - id: UNATTENDED-03
138
- title: BLOCKED only on true external blockers
139
- kind: critical
140
- statement: >-
141
- Test failures, lint errors, review findings, and ambiguity are NOT
142
- blockers — they feed FIX; BLOCKED is reserved for missing credentials,
143
- dead services, and unreachable network/API.
144
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
145
- anchor: 'NOT blockers'
146
- - id: UNATTENDED-04
147
- title: A deny becomes the next safer alternative, never a question
148
- kind: critical
149
- statement: >-
150
- A deny (hook/gate/permission) never becomes a question — pick the next
151
- safer alternative that satisfies the intent and record the substitution;
152
- never emit "do you want me to…".
153
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
154
- anchor: 'next safer alternative'
155
- - id: LONG-01
156
- title: LAND one thing, DEFER the rest, DELEGATE broad work
157
- kind: supporting
158
- statement: >-
159
- Near token-cap, land one in-flight item end-to-end, defer the rest into
160
- docs/STATUS.md or bounded handoff tasks, delegate broad work to subagents.
161
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
162
- - id: LONG-02
163
- title: Post-compact continuity from disk state
164
- kind: supporting
165
- statement: >-
166
- After any compact or handoff, continue from persisted disk state without
167
- rereading pre-compact context; delegate and keep replies short.
168
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
169
- - id: IDX-01
170
- title: Check index freshness before code context
171
- kind: critical
172
- statement: >-
173
- For tasks needing code context, check the index is fresh and refresh it
174
- when stale or missing.
175
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
176
- anchor: 'index is fresh'
177
- - id: IDX-02
178
- title: Open top 1-3 suspect files first
179
- kind: critical
180
- statement: >-
181
- Open only the top 1-3 suspect files first, then widen if needed; use the
182
- outline block to jump straight to the relevant region.
183
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
184
- anchor: 'top 1-3 suspect files'
185
- - id: IDX-03
186
- title: Outlines locate code; code to be changed must still be read
187
- kind: critical
188
- statement: >-
189
- The outline locates code but does not describe behaviour; any code about
190
- to be changed must still be read.
191
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
192
- anchor: 'must still be read'
193
- - id: SKILL-01
194
- title: Auto-activate the matching skill
195
- kind: critical
196
- statement: >-
197
- On every non-trivial task, inspect installed project-local skills and
198
- auto-activate the matching skill immediately; end users should not need
199
- to know skill names.
200
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
201
- anchor: 'auto-activate the matching skill'
202
- - id: SKILL-02
203
- title: Smallest effective skill set
204
- kind: supporting
205
- statement: >-
206
- Use the smallest effective set of skills, usually 1-2.
207
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
208
- - id: SKILL-03
209
- title: Upgrade skill choice on sharper evidence
210
- kind: supporting
211
- statement: >-
212
- If evidence becomes more specific than the original prompt, upgrade the
213
- active skill choice immediately.
214
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
215
- - id: HELP-01
216
- title: Prefer internal helper commands for routing/context/verify
217
- kind: supporting
218
- statement: >-
219
- Prefer the index helper scripts (route-task, resolve-context,
220
- verify-context) for routing, related-file context, and verification.
221
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
222
- - id: HELP-02
223
- title: Never ask contributors to run internal helpers
224
- kind: critical
225
- statement: >-
226
- Do not ask normal contributors to run internal helper commands or
227
- memorize maintainer commands; run them yourself or tell them to rerun
228
- `ukit install`.
229
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
230
- anchor: 'Do not ask normal contributors'
231
- - id: OWN-01
232
- title: PROJECT_IMPORTANT.md is the canonical owner-instruction source
233
- kind: critical
234
- statement: >-
235
- Read and follow the root PROJECT_IMPORTANT.md before project work; it is
236
- the canonical project-owner instruction source.
237
- marker_in: [template_project/AGENTS.md, AGENTS.md]
238
- anchor: 'PROJECT_IMPORTANT.md'
239
- - id: SAFE-01
240
- title: Preserve byte-level file details on edit
241
- kind: critical
242
- statement: >-
243
- Preserve UTF-8 BOM/no-BOM and LF/CRLF for existing multilingual or
244
- user-authored files.
245
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
246
- anchor: 'BOM/no-BOM'
247
- - id: SAFE-02
248
- title: Prefer unique current-file anchors for risky edits
249
- kind: critical
250
- statement: >-
251
- For risky/shared/large edits, prefer unique current-file anchors over
252
- line numbers or stale pasted blocks.
253
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
254
- anchor: 'unique current-file anchors'
255
- - id: SAFE-03
256
- title: Ask on missing or ambiguous stale specs
257
- kind: supporting
258
- statement: >-
259
- Do not silently merge stale specs: if old_string is missing or ambiguous,
260
- re-read current source and ask whether to apply, adapt, or skip.
261
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
262
- - id: CTX-01
263
- title: Deterministic segment bytes
264
- kind: critical
265
- statement: >-
266
- Keep prompt-segment bytes deterministic so provider prompt prefixes can
267
- be reused.
268
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
269
- anchor: 'CTX-01'
270
- - id: CTX-02
271
- title: Keep roles and order
272
- kind: critical
273
- statement: >-
274
- Keep message roles and order stable across calls.
275
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
276
- anchor: 'CTX-02'
277
- - id: CTX-03
278
- title: Keep tool IDs and continuation state
279
- kind: critical
280
- statement: >-
281
- Keep tool IDs and continuation state stable for prefix reuse.
282
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
283
- anchor: 'CTX-03'
284
- - id: CTX-04
285
- title: No clock/random IDs in static blocks
286
- kind: critical
287
- statement: >-
288
- Static prompt blocks must not contain clock values or random IDs.
289
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
290
- anchor: 'CTX-04'
291
- - id: CTX-05
292
- title: Compaction starts a new epoch
293
- kind: critical
294
- statement: >-
295
- Compaction starts a new cache epoch; do not expect prefix reuse across it.
296
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
297
- anchor: 'CTX-05'
298
- - id: CTX-06
299
- title: Never change data to match a cache
300
- kind: critical
301
- statement: >-
302
- Never mutate data to make it match a cache entry.
303
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
304
- anchor: 'CTX-06'
305
- - id: CTX-07
306
- title: No unconfirmed cache fields
307
- kind: critical
308
- statement: >-
309
- Do not rely on cache fields that have not been confirmed for the route in
310
- use.
311
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
312
- anchor: 'CTX-07'
313
- - id: CTX-08
314
- title: Tool-result reuse needs valid freshness
315
- kind: critical
316
- statement: >-
317
- Reuse of tool results requires valid freshness.
318
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
319
- anchor: 'CTX-08'
320
- - id: CTX-09
321
- title: Missing usage is unknown, not zero
322
- kind: critical
323
- statement: >-
324
- Missing cache-usage reporting means unknown, not zero savings.
325
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
326
- anchor: 'CTX-09'
327
- - id: CTX-10
328
- title: Never cut a required check to reduce calls
329
- kind: critical
330
- statement: >-
331
- Never skip a required verification or check just to reduce call count.
332
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
333
- anchor: 'CTX-10'
334
- - id: HAND-01
335
- title: Handoff Quality Gate is opt-in via docs/AI_HANDOFF
336
- kind: supporting
337
- statement: >-
338
- The handoff quality gate activates only when a task goes through
339
- docs/AI_HANDOFF; daily prompts keep the old flow.
340
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
341
- paths: [docs/AI_HANDOFF/**]
342
- - id: HAND-02
343
- title: RUN.md is the authoritative handoff run cursor
344
- kind: critical
345
- statement: >-
346
- docs/AI_HANDOFF/RUN.md is the authoritative run cursor; only the
347
- HANDOFF FULLSTACK COMPLETE/BLOCKED markers after Phase done/blocked end
348
- a run.
349
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
350
- anchor: 'RUN.md'
351
- paths: [docs/AI_HANDOFF/**]
352
- - id: HAND-03
353
- title: Handoff planning gates are mechanical and read from disk
354
- kind: supporting
355
- statement: >-
356
- Tasks flip needs_breakdown to ready only on a recorded validator VERDICT ok
357
- plus PLAN_REVIEW Approved; ready-gate.mjs must print READY_GATE ok before
358
- any flip; owner docs persist through source-snapshot.mjs; work lands
359
- through land-worktree.mjs; rewrites need an amendments/rev copy
360
- (amend-guard.mjs) — all bare single node commands.
361
- marker_in: [template_project/AGENTS.md, AGENTS.md]
362
- - id: BUDGET-01
363
- title: Context budget per task class
364
- kind: critical
365
- statement: >-
366
- Context + verification budget rows: Trivial reads no docs, Simple reads
367
- MEMORY only, Non-trivial adds PROJECT and CODE_MAP.
368
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
369
- anchor: '**Trivial**: no docs'
370
- - id: BUDGET-02
371
- title: STATUS.md only for open-ended or continuation prompts
372
- kind: supporting
373
- statement: >-
374
- docs/STATUS.md is used for open-ended status/continue prompts or
375
- meaningful continuation context; stale status is orientation only.
376
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
377
- - id: BUDGET-03
378
- title: WORKLOG recent entries only
379
- kind: supporting
380
- statement: >-
381
- docs/WORKLOG.md is read for recent relevant entries only; archive oldest
382
- entries when over limits.
383
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
384
- - id: STATUS-01
385
- title: STATUS.md is not source truth
386
- kind: supporting
387
- statement: >-
388
- docs/STATUS.md captures compact current state; it is not source truth and
389
- must not replace source/index-first investigation.
390
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
391
- - id: SUBAG-01
392
- title: Delegate only on meaningful context or parallel gains
393
- kind: supporting
394
- statement: >-
395
- Keep direct execution as default for trivial/simple work; delegate only
396
- when it shrinks context or enables useful parallel progress.
397
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
398
- - id: SUBAG-02
399
- title: Small-task maintainer is a sidecar lane
400
- kind: supporting
401
- statement: >-
402
- The ukit-small-task-maintainer subagent handles safe/reversible UKit
403
- chores as a sidecar lane and hands risky work back to the main model.
404
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
405
- - id: AUTO-01
406
- title: autonomy.level controls how much UKit acts without asking
407
- kind: supporting
408
- statement: >-
409
- autonomy.level in .ukit/storage/config.json controls how much UKit acts
410
- without asking first; end users should not need to change it.
411
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
412
- - id: TIER-01
413
- title: Tiers bind through agent definitions
414
- kind: critical
415
- statement: >-
416
- A model tier takes effect only when work is handed to an agent whose own
417
- definition binds that model; the main session model never changes
418
- mid-turn.
419
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
420
- anchor: 'model:'
421
- - id: TIER-02
422
- title: Escalate one tier after repeated failure
423
- kind: supporting
424
- statement: >-
425
- When the same file or symbol fails debugLoopThreshold times in one
426
- session, route the next attempt one tier higher, capped at smart.
427
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
428
- - id: DURA-01
429
- title: DuraOne skill activates only when installed
430
- kind: supporting
431
- statement: >-
432
- The DuraOne skill is active only when the duraone pack is installed or
433
- .claude/skills/duraone/SKILL.md exists; otherwise use generic standards.
434
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
435
- - id: FALLBACK-01
436
- title: Missing/corrupt runtime → rerun ukit install
437
- kind: critical
438
- statement: >-
439
- If the workspace needs a refresh or runtime files are missing or corrupt,
440
- tell maintainers to rerun `ukit install`.
441
- marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
442
- anchor: 'rerun `ukit install`'
@@ -1,179 +0,0 @@
1
- // Deterministic completion-evidence evaluator (G5 / TASK-003).
2
- // Pure module: no I/O, no runtimeConfig reads, no adapter/context imports.
3
- // Maps requirements × checks × operationRefs (+ optional G4 vmStatus,
4
- // optional modelJudgment) to a frozen CompletionVerdict with precedence
5
- // FAILED > FIX_REQUIRED > MORE_EVIDENCE > PASS.
6
- //
7
- // The installed execution-ledger.mjs remains the completion authority —
8
- // its evaluateCompletion result shape may be fed here as a fixture, but it
9
- // is never imported and never edited. A model-review layer may only ask for
10
- // more evidence: `modelJudgment` is recorded on the verdict and can
11
- // *downgrade* a PASS to MORE_EVIDENCE, but never converts FAIL→PASS.
12
-
13
- import { isTerminal } from './contract.js';
14
-
15
- export const COMPLETION_VERDICTS = Object.freeze([
16
- 'PASS',
17
- 'MORE_EVIDENCE',
18
- 'FIX_REQUIRED',
19
- 'FAILED',
20
- ]);
21
-
22
- // vm terminal states that mean the run itself failed — not merely unproven.
23
- const VM_FAILED_STATES = new Set(['failed', 'cancelled']);
24
- // vm states that mean evidence is unusable until recovery completes.
25
- const VM_FIX_STATES = new Set(['recovery_required']);
26
-
27
- const PASS_STATUSES = new Set(['passed', 'pass', 'ok', 'success']);
28
- const FAIL_STATUSES = new Set(['failed', 'fail', 'error']);
29
- const WARN_STATUSES = new Set(['warning', 'warn', 'skipped', 'indeterminate']);
30
-
31
- function normStatus(status) {
32
- const s = typeof status === 'string' ? status.toLowerCase() : '';
33
- if (PASS_STATUSES.has(s)) return 'passed';
34
- if (FAIL_STATUSES.has(s)) return 'failed';
35
- if (WARN_STATUSES.has(s)) return 'warning';
36
- return 'unproven';
37
- }
38
-
39
- // A check proves a requirement when ids match: check.requirementId → req.id,
40
- // or req.checkId → check.checkId. Either direction is accepted so callers may
41
- // key evidence from whichever side they own.
42
- function checkFor(req, checks) {
43
- return checks.find(
44
- (c) =>
45
- c != null
46
- && typeof c === 'object'
47
- && ((typeof c.requirementId === 'string' && c.requirementId === req.id)
48
- || (typeof req.checkId === 'string' && c.checkId === req.checkId)),
49
- );
50
- }
51
-
52
- // Evidence is stale when it was produced against a different patch/head than
53
- // the operation now carries. Stale ≠ missing: the work must be re-verified,
54
- // which is rework (FIX_REQUIRED), not just more evidence.
55
- function isStale(check, operationRefs) {
56
- if (!check || !operationRefs || typeof operationRefs !== 'object') return false;
57
- if (operationRefs.patchId != null && check.patchId != null
58
- && check.patchId !== operationRefs.patchId) return true;
59
- if (operationRefs.head != null && check.head != null
60
- && check.head !== operationRefs.head) return true;
61
- return false;
62
- }
63
-
64
- export function evaluateCompletionEvidence({
65
- requirements,
66
- checks,
67
- operationRefs,
68
- vmStatus,
69
- modelJudgment,
70
- now,
71
- } = {}) {
72
- const nowMs = typeof now === 'number' ? now : Date.now();
73
- const reqs = Array.isArray(requirements) ? requirements : [];
74
- const checkList = Array.isArray(checks) ? checks : [];
75
- const refs = operationRefs != null && typeof operationRefs === 'object'
76
- ? operationRefs
77
- : null;
78
-
79
- const satisfied = [];
80
- const missing = [];
81
- const unprovenRequirements = [];
82
- const failedChecks = [];
83
- const staleEvidence = [];
84
- const warnings = [];
85
-
86
- for (const req of reqs) {
87
- const reqId = req != null && req.id != null ? String(req.id) : 'unknown';
88
- const check = checkFor(req, checkList);
89
-
90
- if (!check) {
91
- missing.push(reqId);
92
- unprovenRequirements.push(reqId);
93
- continue;
94
- }
95
-
96
- const status = normStatus(check.status);
97
- const stale = isStale(check, refs);
98
-
99
- if (stale) {
100
- staleEvidence.push(Object.freeze({
101
- checkId: check.checkId != null ? String(check.checkId) : reqId,
102
- evidenceRef: check.evidenceRef != null ? String(check.evidenceRef) : null,
103
- patchId: check.patchId != null ? check.patchId : null,
104
- }));
105
- unprovenRequirements.push(reqId);
106
- continue;
107
- }
108
-
109
- if (status === 'failed') {
110
- failedChecks.push(Object.freeze({
111
- checkId: check.checkId != null ? String(check.checkId) : reqId,
112
- evidenceRef: check.evidenceRef != null ? String(check.evidenceRef) : null,
113
- }));
114
- continue;
115
- }
116
-
117
- if (status === 'warning') {
118
- warnings.push(reqId);
119
- unprovenRequirements.push(reqId);
120
- continue;
121
- }
122
-
123
- if (status === 'passed') {
124
- satisfied.push(reqId);
125
- continue;
126
- }
127
-
128
- unprovenRequirements.push(reqId);
129
- }
130
-
131
- // vm state never permits PASS: terminal failure → FAILED, recovery →
132
- // rework, any other non-terminal state → the operation is still in flight
133
- // so evidence cannot yet prove completion.
134
- const vmFailed = typeof vmStatus === 'string' && VM_FAILED_STATES.has(vmStatus);
135
- const vmRecovery = typeof vmStatus === 'string' && VM_FIX_STATES.has(vmStatus);
136
- const vmInFlight = typeof vmStatus === 'string'
137
- && !vmFailed && !vmRecovery && !isTerminal(vmStatus) && vmStatus !== 'completed';
138
-
139
- // Non-zero exit status = failed verification run → rework required.
140
- const exitFailed = refs != null
141
- && typeof refs.exitStatus === 'number'
142
- && refs.exitStatus !== 0;
143
-
144
- let verdict = 'PASS';
145
- if (missing.length > 0 || unprovenRequirements.length > 0 || vmInFlight) {
146
- verdict = 'MORE_EVIDENCE';
147
- }
148
- if (staleEvidence.length > 0 || exitFailed || vmRecovery) {
149
- verdict = 'FIX_REQUIRED';
150
- }
151
- if (failedChecks.length > 0 || vmFailed) {
152
- verdict = 'FAILED';
153
- }
154
-
155
- // modelJudgment may only request more evidence, never promote (enforced
156
- // below: a judgment can downgrade PASS → MORE_EVIDENCE, nothing else). When
157
- // model-backed, the judgment MUST originate from the decision plane
158
- // (unic-decision, a bounded verdict question) — never a general LLM call.
159
- const judgment = modelJudgment != null
160
- ? (typeof modelJudgment === 'string' ? modelJudgment : String(modelJudgment))
161
- : null;
162
- if (verdict === 'PASS' && judgment != null && judgment !== 'pass') {
163
- verdict = 'MORE_EVIDENCE';
164
- }
165
-
166
- return Object.freeze({
167
- verdict,
168
- satisfied: Object.freeze(satisfied),
169
- missing: Object.freeze(missing),
170
- failedChecks: Object.freeze(failedChecks),
171
- unprovenRequirements: Object.freeze(unprovenRequirements),
172
- staleEvidence: Object.freeze(staleEvidence),
173
- warnings: Object.freeze(warnings),
174
- patchId: refs != null && refs.patchId != null ? refs.patchId : undefined,
175
- vmStatus: typeof vmStatus === 'string' ? vmStatus : undefined,
176
- modelJudgment: judgment != null ? judgment : undefined,
177
- evaluatedAt: nowMs,
178
- });
179
- }