@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 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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ngockhoale/ukit",
3
- "version": "3.4.72",
3
+ "version": "3.4.74",
4
4
  "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -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
- If `docs/AI_HANDOFF/RUN.md` exists with `Phase:` not `done` or `blocked`, this is a
198
- **continuation, not a new cycle**. Do NOT re-plan, do NOT overwrite `PLAN.md`, do NOT ask
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` is terminal for the run — the machinery (Stop gate, hooks, stop-coordinator)
206
- all treats it as closed. It is *paused*, not abandoned: an explicit `/ukit:handoff-fullstack`
207
- re-invocation resumes it as a continuation; `ukit handoff-clear` pauses it (`Paused: yes`, backlog and scope kept, no completion minted). Only when
208
- `RUN.md` is absent or `Phase: done` does a new request start a fresh cycle.
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 `/ukit:handoff-fullstack` also lifts a liveness pause: the resume hook rewrites `Paused: yes` to `Paused: no` in `RUN.md`, reads it back, and keeps `Phase:`, scope, and the queue untouched. Ordinary prompts, startup, and clear never lift it.
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
- - Invoking `/ukit:handoff-fullstack` (or running the `handoff-fullstack` skill) makes the
219
- session's handoff intent *implementation* again — ownership is reacquired, the queued
220
- `ready` tasks from the create phase are picked up, and a `Phase:` outside `done`/`blocked`
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
- if (!phase || /^(done|blocked)\b/i.test(phase)) {
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
- // Structured PAUSED (C100 P1): never inject a resume for a paused run, on any source.
323
- // The one lift: an EXPLICIT /ukit:handoff-fullstack in this session's transcript (a
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