@ngockhoale/ukit 3.4.72 → 3.4.74
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 +17 -0
- package/manifests/documentation.yaml +11 -0
- package/package.json +1 -1
- package/template_project/.claude/commands/ukit/handoff-fullstack.md +34 -12
- package/template_project/.claude/hooks/handoff-resume.sh +29 -53
- package/template_project/.claude/hooks/skill-router.sh +299 -23
- package/template_project/.claude/hooks/verification-guard.sh +8 -1
- package/template_project/.claude/settings.json +22 -0
- package/template_project/.claude/ukit/index/publication-intent.mjs +7 -2
- package/template_project/.claude/ukit/index/route-task.mjs +77 -18
- package/template_project/.claude/ukit/runtime/block-breaker.mjs +1 -0
- package/template_project/.claude/ukit/runtime/compact-threshold.mjs +8 -1
- package/template_project/.claude/ukit/runtime/cron-operation-adapter.mjs +12 -17
- package/template_project/.claude/ukit/runtime/execution-ledger.mjs +36 -10
- package/template_project/.claude/ukit/runtime/handoff-intent.mjs +5 -0
- package/template_project/.claude/ukit/runtime/handoff-provenance.mjs +277 -0
- package/template_project/.claude/ukit/runtime/loop-state.mjs +23 -4
- package/template_project/.claude/ukit/runtime/operation-evidence.mjs +5 -8
- package/template_project/.claude/ukit/runtime/reinject-context.mjs +10 -0
- package/template_project/.claude/ukit/runtime/stop-coordinator.mjs +126 -26
- package/template_project/.omp/hooks/pre/ukit-bridge.js +34 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,23 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to UKit are documented here.
|
|
4
4
|
|
|
5
|
+
## 3.4.74 - 2026-10-30
|
|
6
|
+
|
|
7
|
+
**Route publication protocol, handoff ownership authority and explicit legacy adoption; no live-host certification beyond the isolated native OMP A/B/C acceptance recorded in `docs/STATUS.md`.**
|
|
8
|
+
|
|
9
|
+
- Route publication: pending sidecar → shared write with UUID revision → final sidecar commit across all route writers/readers (`docs/ROUTE_PUBLICATION.md`); Stop coherence tests and a fault-injection matrix cover torn/concurrent publication.
|
|
10
|
+
- Handoff ownership: immutable run binding plus per-run authority record (generation/history) in `handoff-provenance.mjs`; `resolveCursorApplicability` yields OWNED / NOT_OWNED / UNKNOWN and UNKNOWN is never treated as ownership. Not described as fail-safe beyond what the tests prove.
|
|
11
|
+
- OMP case A: a Stop with unavailable route identity is released as NOT_OWNED only when a bounded transcript intent scan proves the session never targeted the handoff; torn or non-JSON-shaped transcript lines stay unknown. Intent only releases a non-claimant and never grants ownership. Claude/OMP Stop differences are documented and tested (`stopHostSemantics.test.js`); advisory or loop-breaker release is not completion evidence.
|
|
12
|
+
- Legacy adoption: owner-invoked `--adopt-legacy-run=<sha256>` only (never at session start or Stop), validated under lock against the cursor snapshot hash; preserves content and state and never declares a run done.
|
|
13
|
+
- Publication intent: `publicationScope` treats "do not publish until/unless …" as a temporary restriction rather than a task-wide prohibition (it never grants authorization); `evidenceStatement` masks the repo's own release-policy sentence so it is not read as an execution order; `SEMANTIC_ENGINE_VERSION` bumped so cached intent scans are invalidated.
|
|
14
|
+
- Release completion: `releasePublicationMissing` accepts only a task-owned, tool-use-attributed, non-masked publish receipt with a parsed `+ pkg@version` line followed by a later same-scope registry view (registry state alone is not proof); `cron-operation-adapter` reports publish receipts without that line as unproven; background completions apply the masked-exit check.
|
|
15
|
+
- Artifact budget: packed < 3,500,000 and unpacked < 11,300,000 bytes.
|
|
16
|
+
|
|
17
|
+
## 3.4.73 - 2026-10-28
|
|
18
|
+
|
|
19
|
+
- Git history proof tolerates unrelated untracked files; tracked/staged drift and explicit whole-tree clean obligations remain strict. No filename exemptions.
|
|
20
|
+
- Native ledger-to-Stop fixtures cover Claude Code/Codex/omp, repeated Stop and untracked shipped-source publication drift; not live-host certification.
|
|
21
|
+
|
|
5
22
|
## 3.4.72 - 2026-10-28
|
|
6
23
|
|
|
7
24
|
- Native evidence: reject background, masked and test-expression exits as operation/verification proof; retain supported foreground controls across shared Claude Code/Codex/OMP fixtures. No live-host certification.
|
|
@@ -4,6 +4,7 @@ description: >-
|
|
|
4
4
|
Machine-readable ownership/source registry for every documentation surface.
|
|
5
5
|
Hand-authored per SPEC §7; enforced by tests/consistency/docRegistry.test.js.
|
|
6
6
|
entries:
|
|
7
|
+
- {id: post-3472-git, path: docs/analysis/POST-3472-GIT-OPERATION-VERIFICATION.md, class: canonical, audience: [maintainer], owner: release, source_of_truth: docs/analysis/POST-3472-GIT-OPERATION-VERIFICATION.md, merge_strategy: none, load_policy: on-demand, validation: [manual], archive_policy: never}
|
|
7
8
|
- {id: release-3472, path: docs/analysis/RELEASE-3472-EVIDENCE-INTEGRITY.md, class: canonical, audience: [maintainer, agent], owner: release, source_of_truth: docs/analysis/RELEASE-3472-EVIDENCE-INTEGRITY.md, merge_strategy: none, load_policy: on-demand, validation: [manual], archive_policy: never}
|
|
8
9
|
- id: systematic-loop-audit-2026-10-26
|
|
9
10
|
path: docs/analysis/SYSTEMATIC-LOOP-AUDIT-2026-10-26.md
|
|
@@ -276,6 +277,16 @@ entries:
|
|
|
276
277
|
load_policy: on-demand
|
|
277
278
|
validation: [manual]
|
|
278
279
|
archive_policy: never
|
|
280
|
+
- id: docs-route-publication
|
|
281
|
+
path: docs/ROUTE_PUBLICATION.md
|
|
282
|
+
class: canonical
|
|
283
|
+
audience: [agent, maintainer]
|
|
284
|
+
owner: runtime
|
|
285
|
+
source_of_truth: docs/ROUTE_PUBLICATION.md
|
|
286
|
+
merge_strategy: none
|
|
287
|
+
load_policy: on-demand
|
|
288
|
+
validation: [manual]
|
|
289
|
+
archive_policy: never
|
|
279
290
|
- id: docs-release-checklist
|
|
280
291
|
path: docs/RELEASE_CHECKLIST.md
|
|
281
292
|
class: canonical
|
package/package.json
CHANGED
|
@@ -79,10 +79,11 @@ Before dispatching any mutating worker (including blueprint folding), write and
|
|
|
79
79
|
P0/P1 cursor with the actual phase, frozen scope, next action and known job references. Do not
|
|
80
80
|
defer cursor creation until P2; omit ExitPredicate until P2 pins it, never invent a satisfied one.
|
|
81
81
|
Reconcile partial writes and existing jobs from that cursor on interruption; never restart the fold blindly.
|
|
82
|
-
|
|
82
|
+
The invocation's RunId must come from an authoritative UKit invocation binding, not from transcript text or a guessed value. If no binding is available, do not create or rewrite a cursor or claim ownership; report the missing invocation provenance as BLOCKED. On resume, verify that the existing cursor's RunId matches that binding before changing it.
|
|
83
83
|
|
|
84
84
|
```
|
|
85
85
|
Command: handoff-fullstack
|
|
86
|
+
RunId: <exact invocation RunId supplied by the UKit hook; never invent or backfill>
|
|
86
87
|
Goal: <one sentence from the **Problem / feature** section above>
|
|
87
88
|
Base: <BASE branch>
|
|
88
89
|
Phase: <P0|P1|P2|P2.5|P3|I1|I2|I3|I4|R1|R2|R3|R4|R4.5|R5|F|done|blocked>
|
|
@@ -194,31 +195,52 @@ Wherever a step below says **verify the write**, it means this rule.
|
|
|
194
195
|
|
|
195
196
|
### Resume — when the run is re-invoked mid-flight
|
|
196
197
|
|
|
197
|
-
|
|
198
|
-
|
|
198
|
+
An existing cursor is not itself ownership. To resume a bound run from a new task or
|
|
199
|
+
session, the user must explicitly invoke `/ukit:handoff-fullstack --resume-run=<RunId>`
|
|
200
|
+
with its exact RunId; the invocation hook must verify the binding and current route.
|
|
201
|
+
Missing, mismatched or unverified identity means BLOCKED without changing the cursor.
|
|
202
|
+
A bare invocation continues when the current task already owns the cursor. It cannot
|
|
203
|
+
transfer ownership from an earlier task, even if there is only one cursor: the cursor
|
|
204
|
+
is not authorization. This is a compatibility change for older bare cross-task resumes;
|
|
205
|
+
use the exact RunId from the original authoritative invocation with `--resume-run`.
|
|
206
|
+
If that identity or binding is unavailable, stop without rewriting the cursor.
|
|
207
|
+
|
|
208
|
+
If `docs/AI_HANDOFF/RUN.md` exists with `Phase:` not `done` or `blocked` and the
|
|
209
|
+
current route owns its RunId, this is a **continuation, not a new cycle**. Do NOT re-plan, do NOT overwrite `PLAN.md`, do NOT ask
|
|
199
210
|
the human whether to continue. Read the cursor, then jump straight to `Next:` and carry on.
|
|
200
211
|
Tasks already `done` are skipped. `pending_review` tasks are NOT re-implemented — they go to
|
|
201
212
|
the R-phase review (R2–R4). `ready`, `in_progress`, `changes_requested` and `blocked` tasks
|
|
202
213
|
are routed to implementation/fix (I-phase). Any nonterminal state gets a branch; none is
|
|
203
214
|
skipped silently.
|
|
204
215
|
|
|
205
|
-
`Phase: blocked`
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
216
|
+
`Phase: blocked` releases the current run at Stop when no independent work remains,
|
|
217
|
+
but an authorized explicit invocation may continue its frozen scope; it is not a new
|
|
218
|
+
cycle. `Phase: done` is terminal. A nonterminal run may also be paused (`Paused: yes`),
|
|
219
|
+
with backlog and scope retained and no completion minted.
|
|
220
|
+
|
|
221
|
+
### Legacy run without a RunId — explicit adoption
|
|
222
|
+
|
|
223
|
+
A live cursor written before ownership existed has no `RunId:` line, so no session owns it and
|
|
224
|
+
a bare invocation is refused. The refusal prints the exact command; the owner runs
|
|
225
|
+
`/ukit:handoff-fullstack --adopt-legacy-run=<RunId>` where `<RunId>` is the digest of that exact
|
|
226
|
+
cursor. Adoption is never automatic (not at session start, not at Stop, not from the Skill tool).
|
|
227
|
+
It refuses a stale snapshot, a completed run, a cursor that already has a RunId, and any run that
|
|
228
|
+
already has an owner or invalid identity state. It creates the identity through the same ownership
|
|
229
|
+
authority, then adds only a `RunId:` line; phase, scope, queue and ExitPredicate are untouched, and it
|
|
230
|
+
never marks the run done or repairs a malformed ExitPredicate. After an interrupted adoption only the same
|
|
231
|
+
session may re-invoke the same command to finish it.
|
|
209
232
|
|
|
210
233
|
### Explicit invocation reacquires ownership
|
|
211
234
|
|
|
212
|
-
An explicit
|
|
235
|
+
An explicit resume may lift a liveness pause only after the current route's ownership is verified. The rewrite must keep `Phase:`, scope, and the queue untouched and be read back. Ordinary prompts, startup, and clear never lift it.
|
|
213
236
|
|
|
214
237
|
`/ukit:handoff-create` is planning-only and makes a session's handoff intent *planning* — so
|
|
215
238
|
while the human is planning, neither the Stop gate nor the SessionStart compact/resume hook
|
|
216
239
|
forces a paused run back into implementation. This command is the explicit counter-action:
|
|
217
240
|
|
|
218
|
-
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
in `RUN.md` is once more held to completion by the Stop gate.
|
|
241
|
+
- An authorized invocation makes the session's handoff intent *implementation* again.
|
|
242
|
+
Ownership is retained by the current owner or transferred only by a verified explicit
|
|
243
|
+
resume claim; invoking the skill alone does not reacquire a foreign cursor.
|
|
222
244
|
- Work queued by planning is **not lost**: it waits in `INDEX.md`/`PLAN.md` until this
|
|
223
245
|
explicit invocation (or `/ukit:handoff-implement`) claims it.
|
|
224
246
|
|
|
@@ -249,46 +249,6 @@ function boundedTaskScopeLines(all, runCycle, currentTask) {
|
|
|
249
249
|
})();
|
|
250
250
|
const source = typeof payload.source === 'string' ? payload.source : 'startup';
|
|
251
251
|
|
|
252
|
-
// Explicit-pause lift. Only a transcript whose latest handoff intent is `fullstack`
|
|
253
|
-
// may clear `Paused: yes`. The shared classifier does not split the user `<command-name>`
|
|
254
|
-
// tag from the resume banner, so both count as this lift's evidence; a paused run never
|
|
255
|
-
// gets a banner (the pause returns before any banner is written), so a banner in the
|
|
256
|
-
// transcript only comes from an earlier resume. The rewrite changes only the `Paused:`
|
|
257
|
-
// line (atomic tmp+rename) and is read back before it is trusted; any failure returns
|
|
258
|
-
// { ok:false } and the pause stays.
|
|
259
|
-
async function liftExplicitPause(mod, payload, runFile, text) {
|
|
260
|
-
try {
|
|
261
|
-
const transcript = typeof payload.transcript_path === 'string' ? payload.transcript_path : null;
|
|
262
|
-
if (!transcript || typeof mod.transcriptHandoffIntent !== 'function') return { ok: false };
|
|
263
|
-
const { intent, known } = await mod.transcriptHandoffIntent(transcript);
|
|
264
|
-
if (!known || intent !== 'fullstack') return { ok: false };
|
|
265
|
-
// The banner also classifies as fullstack, so require the user's explicit command tag to be
|
|
266
|
-
// the LAST evidence: a `<command-name>` tag for fullstack/implement must appear after the last
|
|
267
|
-
// resume banner. A banner from an earlier resume never lifts a later pause.
|
|
268
|
-
const tail = await fs.promises.readFile(transcript, 'utf8');
|
|
269
|
-
const lastTag = Math.max(
|
|
270
|
-
tail.lastIndexOf('<command-name>/ukit:handoff-fullstack</command-name>'),
|
|
271
|
-
tail.lastIndexOf('<command-name>/ukit:handoff-implement</command-name>'),
|
|
272
|
-
tail.lastIndexOf('<command-name>ukit:handoff-fullstack</command-name>'),
|
|
273
|
-
tail.lastIndexOf('<command-name>ukit:handoff-implement</command-name>'),
|
|
274
|
-
tail.lastIndexOf('<command-name>/handoff-fullstack</command-name>'),
|
|
275
|
-
tail.lastIndexOf('<command-name>/handoff-implement</command-name>'),
|
|
276
|
-
);
|
|
277
|
-
const lastBanner = tail.lastIndexOf('UKIT HANDOFF RESUME');
|
|
278
|
-
if (lastTag < 0 || lastTag < lastBanner) return { ok: false };
|
|
279
|
-
const next = text.replace(/^Paused:.*$/m, 'Paused: no');
|
|
280
|
-
if (next === text) return { ok: false };
|
|
281
|
-
const tmp = `${runFile}.tmp-unpause-${process.pid}-${Date.now()}`;
|
|
282
|
-
await fs.promises.writeFile(tmp, next, 'utf8');
|
|
283
|
-
await fs.promises.rename(tmp, runFile);
|
|
284
|
-
const readBack = await fs.promises.readFile(runFile, 'utf8');
|
|
285
|
-
if (!/^Paused:\s*no\b/m.test(readBack) || /^Paused:\s*yes\b/m.test(readBack)) return { ok: false };
|
|
286
|
-
return { ok: true, text: readBack };
|
|
287
|
-
} catch {
|
|
288
|
-
return { ok: false };
|
|
289
|
-
}
|
|
290
|
-
}
|
|
291
|
-
|
|
292
252
|
// Worktree scoping: the host pins CLAUDE_PROJECT_DIR to the primary checkout, so a
|
|
293
253
|
// session in an independent linked worktree must not be handed the primary's
|
|
294
254
|
// cursor. Only a git-verified worktree of this repo re-scopes the cursor; any
|
|
@@ -314,32 +274,48 @@ async function liftExplicitPause(mod, payload, runFile, text) {
|
|
|
314
274
|
const phase = field('Phase');
|
|
315
275
|
// `done` and `blocked` are both terminal (blocked = closed with instructions, the
|
|
316
276
|
// same posture stop-coordinator.mjs uses). Anything else means a step was in flight.
|
|
317
|
-
|
|
277
|
+
const terminalPhase = /^(done|blocked)\b/i.exec(phase)?.[1]?.toLowerCase() || '';
|
|
278
|
+
if (!phase || terminalPhase === 'done') {
|
|
279
|
+
await emitOrdinaryResume(payload, source);
|
|
280
|
+
process.exit(0);
|
|
281
|
+
}
|
|
282
|
+
|
|
283
|
+
// Transcript intent cannot establish ownership of a cursor. Resolve the current
|
|
284
|
+
// session's durable binding before either injecting a resume or lifting a pause.
|
|
285
|
+
let ownership;
|
|
286
|
+
try {
|
|
287
|
+
const provenance = await import(pathToFileURL(path.join(projectRoot, '.claude', 'ukit', 'runtime', 'handoff-provenance.mjs')).href);
|
|
288
|
+
ownership = await provenance.resolveCursorApplicability({
|
|
289
|
+
projectRoot, runRoot: path.dirname(path.dirname(path.dirname(runPath))),
|
|
290
|
+
sessionId: payload.session_id || payload.sessionId,
|
|
291
|
+
});
|
|
292
|
+
} catch {
|
|
293
|
+
ownership = { status: 'UNKNOWN', reason: 'handoff provenance runtime unavailable' };
|
|
294
|
+
}
|
|
295
|
+
if (terminalPhase === 'blocked' && ownership.status === 'OWNED' && !ownership.claim) {
|
|
318
296
|
await emitOrdinaryResume(payload, source);
|
|
319
297
|
process.exit(0);
|
|
320
298
|
}
|
|
299
|
+
if (ownership.status !== 'OWNED') {
|
|
300
|
+
if (ownership.status === 'UNKNOWN') {
|
|
301
|
+
process.stdout.write(`UKit handoff ownership UNKNOWN (${ownership.reason}); cursor untouched and automatic resume skipped.\n`);
|
|
302
|
+
} else {
|
|
303
|
+
process.stdout.write('UKit note: an unfinished handoff-fullstack run may be present, but this task does not own its cursor; planning or other current work may continue. Cursor untouched.\n');
|
|
304
|
+
}
|
|
305
|
+
process.exit(0);
|
|
306
|
+
}
|
|
321
307
|
|
|
322
|
-
//
|
|
323
|
-
//
|
|
324
|
-
// user `<command-name>` tag, never the banner this hook injects) clears `Paused: yes`
|
|
325
|
-
// back to `Paused: no`, verified by read-back, Phase/scope untouched, then the resume
|
|
326
|
-
// continues below. Startup/clear and non-explicit prompts never lift a pause.
|
|
308
|
+
// Session-start and compaction are not authoritative user invocations. Never
|
|
309
|
+
// lift a pause here, even if a historical transcript contains a command.
|
|
327
310
|
try {
|
|
328
311
|
const mod = await import(pathToFileURL(intentPath).href);
|
|
329
312
|
if (typeof mod.runCursorPaused === 'function' && mod.runCursorPaused(text) === true) {
|
|
330
|
-
const lift = source !== 'startup' && source !== 'clear'
|
|
331
|
-
? await liftExplicitPause(mod, payload, runPath, text)
|
|
332
|
-
: null;
|
|
333
|
-
if (lift?.ok) {
|
|
334
|
-
text = lift.text;
|
|
335
|
-
} else {
|
|
336
313
|
process.stdout.write([
|
|
337
314
|
'UKit note: docs/AI_HANDOFF/RUN.md has a handoff-fullstack run that is PAUSED '
|
|
338
315
|
+ `(Phase: ${phase}; Cursor: ${field('Cursor') || 'not recorded'}).`,
|
|
339
316
|
'Not resumed or spawned; only an explicit user instruction lifts the pause. RUN.md untouched.',
|
|
340
317
|
].join('\n') + '\n');
|
|
341
318
|
process.exit(0);
|
|
342
|
-
}
|
|
343
319
|
}
|
|
344
320
|
} catch {}
|
|
345
321
|
|