@ngockhoale/ukit 3.4.69 → 3.4.70

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to UKit are documented here.
 
+## 3.4.70 - 2026-10-26
+
+**Task-owned completion evidence and bounded reminder recovery; no native-host certification.**
+
+- Classification: configuration comparisons, read-only output specifications and owner-approval reminders do not inherit mutation or verification debt. Explicit verification and publication orders retain their own obligations; private Git scope and later affirmative orders remain distinct. Descriptive acceptance-review prose — subordinator continuation fragments ("…, including source fixes F-3") and non-imperative goal/acceptance lines ("Final product goal: … normal ukit update pass") — no longer routes read-only reviews as implementation orders; any imperative fragment inside such a line still enforces write+verification.
+- Completion: preserve truthful blocked outcomes, scoped exhausted-denial reconciliation and native Git/remote evidence. Launch acknowledgements, missing exit proof, masked commands, foreign receipts and stale parity cannot prove success. Docs-only Handoff creation honors the owner's explicit Git publication scope.
+- Reminder recovery: reapply classified evidence obligations even when the task-kind signature is unchanged. Repeated read-only reminders need no artificial checkpoint verification; owned external blockers remain blocked rather than successful. No permission reset, receipt bypass or safety relaxation.
+- Release verification: bind mandatory phases to candidate bytes and fail on drift; run existing live-documentation checks before expensive gates and retain external per-run result metadata. Mandatory lanes, artifact budgets and timeouts are unchanged.
+- Evidence limits: targeted regressions and independent reviews cover shared Claude/OMP sources and fixtures; Codex remains advisory where no native hook exists. Historical failed verifier runs remain failed. The review integration fixture now has a measured, first-case-only 15s allowance after bounded child-latency reproduction; global/runtime timeouts are unchanged. Discovery deadline testing waits for the intended filesystem phase instead of racing startup I/O. No speculative performance fix or exact historical slowdown attribution is claimed.
+
 ## 3.4.69 - 2026-10-25
 
 **Narrow shared-lock cancellation repair; no new unattended-Handoff certification.**

package/manifests/documentation.yaml

@@ -4,6 +4,17 @@ description: >-
   Machine-readable ownership/source registry for every documentation surface.
   Hand-authored per SPEC §7; enforced by tests/consistency/docRegistry.test.js.
 entries:
+  - id: systematic-loop-audit-2026-10-26
+    path: docs/analysis/SYSTEMATIC-LOOP-AUDIT-2026-10-26.md
+    class: canonical
+    audience: [maintainer, agent]
+    owner: release
+    source_of_truth: docs/analysis/SYSTEMATIC-LOOP-AUDIT-2026-10-26.md
+    merge_strategy: none
+    load_policy: on-demand
+    validation: [manual]
+    archive_policy: never
+    notes: bounded audit inventory and repair-round ledger; no additional full-verifier allowance
   # ── Repo root ────────────────────────────────────────────────────────────
   - id: root-claude-md
     path: CLAUDE.md
@@ -451,6 +462,72 @@ entries:
     validation: [manual]
     archive_policy: replace-with-snapshot
     notes: Phase A read-only concurrency audit; provisional metrics labelled, pilot not run
+  - id: docs-status-history-2026-10-25
+    path: docs/STATUS-HISTORY-2026-10-25.md
+    class: archive
+    audience: [maintainer]
+    owner: release
+    source_of_truth: docs/STATUS-HISTORY-2026-10-25.md
+    merge_strategy: none
+    load_policy: on-demand
+    validation: [manual]
+    archive_policy: never
+    notes: Superseded STATUS checkpoints moved verbatim from docs/STATUS.md (Round4)
+  - id: docs-analysis-round4-defect-closure
+    path: docs/analysis/ROUND4-DEFECT-CLOSURE.md
+    class: canonical
+    audience: [maintainer]
+    owner: release
+    source_of_truth: docs/analysis/ROUND4-DEFECT-CLOSURE.md
+    merge_strategy: none
+    load_policy: on-demand
+    validation: [manual]
+    archive_policy: never
+    notes: Round4 working defect-closure register; not an acceptance packet
+  - id: docs-analysis-round4-reviewer-failures
+    path: docs/analysis/ROUND4-REVIEWER-FAILURES.md
+    class: canonical
+    audience: [maintainer]
+    owner: release
+    source_of_truth: docs/analysis/ROUND4-REVIEWER-FAILURES.md
+    merge_strategy: none
+    load_policy: on-demand
+    validation: [manual]
+    archive_policy: never
+    notes: All 95 original reviewer failures with candidate-assessed dispositions; independent acceptance still required
+  - id: docs-analysis-round4-systemic-intent
+    path: docs/analysis/ROUND4-SYSTEMIC-INTENT.md
+    class: canonical
+    audience: [maintainer]
+    owner: release
+    source_of_truth: docs/analysis/ROUND4-SYSTEMIC-INTENT.md
+    merge_strategy: none
+    load_policy: on-demand
+    validation: [manual]
+    archive_policy: never
+    notes: Round4 systemic intent model and acceptance scope
+  - id: docs-analysis-round4-terminal-core-diagnostics
+    path: docs/analysis/ROUND4-TERMINAL-CORE-DIAGNOSTICS.md
+    class: archive
+    audience: [maintainer]
+    owner: release
+    source_of_truth: docs/analysis/ROUND4-TERMINAL-CORE-DIAGNOSTICS.md
+    merge_strategy: none
+    load_policy: on-demand
+    validation: [manual]
+    archive_policy: never
+    notes: Round4 terminal Core diagnostics evidence
+  - id: docs-debug-ukit-3431-debug-audit
+    path: docs/debug/UKIT-3.4.31-DEBUG-AUDIT.md
+    class: archive
+    audience: [maintainer]
+    owner: release
+    source_of_truth: docs/debug/UKIT-3.4.31-DEBUG-AUDIT.md
+    merge_strategy: none
+    load_policy: on-demand
+    validation: [manual]
+    archive_policy: never
+    notes: Unreleased 3.4.31 debug audit (2026-10-11); untracked file of unrecorded provenance, registered so the coverage gate sees it
   - id: docs-analysis-concurrency-checkpoint
     path: docs/analysis/CONCURRENCY-CHECKPOINT-2026-10-22.md
     class: canonical
@@ -660,6 +737,17 @@ entries:
     validation: [manual]
     archive_policy: never
     notes: Native planning Write permission evidence, authorized configuration provenance and unresolved live acceptance boundaries
+  - id: docs-analysis-handoff-create-git-completion
+    path: docs/analysis/HANDOFF-CREATE-GIT-COMPLETION.md
+    class: canonical
+    audience: [maintainer]
+    owner: product
+    source_of_truth: docs/analysis/HANDOFF-CREATE-GIT-COMPLETION.md
+    merge_strategy: none
+    load_policy: on-demand
+    validation: [manual]
+    archive_policy: never
+    notes: Create-scope Git authorization, operation evidence, task-owned denial reconciliation and release verification boundaries
   - id: docs-analysis-orchestration-final-verification
     path: docs/analysis/ORCHESTRATION-FINAL-VERIFICATION.md
     class: archive

package/manifests/platform.full.yaml

@@ -1535,7 +1535,8 @@ items:
     type: config
     sourceTemplate: .claude/ukit/runtime
     targetPath: .claude/ukit/runtime
-    requires: []
+    requires:
+      - ukit-index-publication-intent-script
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -1856,11 +1857,22 @@ items:
     packs:
       - core
 
+  - id: ukit-index-publication-intent-script
+    type: config
+    sourceTemplate: .claude/ukit/index/publication-intent.mjs
+    targetPath: .claude/ukit/index/publication-intent.mjs
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: ukit-index-route-resolver-script
     type: config
     sourceTemplate: .claude/ukit/index/route-resolver.mjs
     targetPath: .claude/ukit/index/route-resolver.mjs
     requires:
+      - ukit-index-publication-intent-script
       - ukit-index-core-lib
       - ukit-index-cache-utils-script
       - ukit-index-route-catalog-script

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.69",
+  "version": "3.4.70",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",
@@ -30,6 +30,10 @@
     "bin/",
     "src/",
     "scripts/",
+    "!scripts/dev/benchmark-verification-currency.mjs",
+    "!scripts/dev/capture-omp-stall.mjs",
+    "!scripts/install/generate-semantic-engine.mjs",
+    "!scripts/release/progress-reporter.mjs",
     "!scripts/audit/c100/attribution-gap.mjs",
     "!scripts/audit/c100/implementer-attribution.mjs",
     "!scripts/audit/c100/trees-lifetimes.mjs",

package/scripts/install/module-dependency-closure.mjs

@@ -0,0 +1,53 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Static specifiers plus URL-resolved dynamic imports (`new URL('./x.mjs', import.meta.url)`), which runtimes use for
+// lazy safety modules. Only literal module-file URLs are edges: assets (.json) and computed specifiers are not.
+function relativeModuleDependencies(text) {
+  const imports = /(?:\b(?:import|export)\s+(?:[^;'"\n]*?\s+from\s*)?|\bimport\s*\(\s*)['"](\.{1,2}\/[^'"\n]+)['"]/g;
+  const urls = /\bnew\s+URL\(\s*['"](\.{1,2}\/[^'"\n]+\.[cm]?js)['"]\s*,\s*import\.meta\.url/g;
+  return [...new Set([...text.matchAll(imports), ...text.matchAll(urls)].map((match) => match[1]))];
+}
+
+export function validateModuleClosureSync(entries) {
+  const targets = new Map(entries.filter((entry) => entry.sourcePath)
+    .map((entry) => [path.resolve(entry.targetPath), path.resolve(entry.sourcePath)]));
+  for (const entry of entries) {
+    if (!entry.sourcePath || !/\.[cm]?js$/.test(entry.sourcePath)) continue;
+    const text = fs.readFileSync(entry.sourcePath, 'utf8');
+    for (const dependency of relativeModuleDependencies(text)) {
+      const source = path.resolve(path.dirname(entry.sourcePath), dependency);
+      const target = path.resolve(path.dirname(entry.targetPath), dependency);
+      if (targets.get(target) !== source) {
+        throw new Error(`Runtime dependency missing or misrelocated: ${entry.sourcePath} -> ${dependency} (expected ${target})`);
+      }
+    }
+  }
+}
+
+// Relocation preserves relative module topology. Missing declared dependencies
+// are packaging errors, never an excuse to disable a runtime safety check.
+export function copyModuleClosureSync(source, destination, visited = new Set()) {
+  source = path.resolve(source);
+  destination = path.resolve(destination);
+  const key = `${source}\0${destination}`;
+  if (visited.has(key)) return;
+  visited.add(key);
+  const bytes = fs.readFileSync(source);
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.writeFileSync(destination, bytes);
+  if (!/\.[cm]?js$/.test(source)) return;
+  const text = bytes.toString('utf8');
+  for (const dependency of relativeModuleDependencies(text)) {
+    copyModuleClosureSync(path.resolve(path.dirname(source), dependency),
+      path.resolve(path.dirname(destination), dependency), visited);
+  }
+}
+
+export function copyRuntimeClosureSync(sourceDirectory, destinationDirectory) {
+  const visited = new Set();
+  for (const entry of fs.readdirSync(sourceDirectory, { withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+    copyModuleClosureSync(path.join(sourceDirectory, entry.name), path.join(destinationDirectory, entry.name), visited);
+  }
+}

package/scripts/install/sync-installed-mirror.mjs

@@ -140,6 +140,15 @@ async function collectMirrorOnlyPaths({ plan, projectRoot, templatesRoot }) {
   return [...new Set(mirrorOnly)].sort();
 }
 
+// Hooks write their own state under `<managed dir>/.ukit/storage/` (stop-coordinator, task-watchdog,
+// observability). That is protected runtime state, not template drift: it is reported for transparency but never
+// fails the check, is never rewritten, and is never offered for deletion. Any other unshipped file stays mirror-only.
+const RUNTIME_STATE_SEGMENT = '/.ukit/storage/';
+function splitRuntimeState(paths) {
+  const runtimeState = paths.filter((p) => `/${p}`.includes(RUNTIME_STATE_SEGMENT));
+  return { mirrorOnly: paths.filter((p) => !runtimeState.includes(p)), runtimeState };
+}
+
 async function main() {
   const args = process.argv.slice(2);
   const unknown = args.filter((arg) => arg !== '--check');
@@ -192,11 +201,11 @@ async function main() {
     .map((entry) => ({ entry, relativePath: toRelative(projectRoot, entry.targetPath) }))
     .sort((a, b) => a.relativePath.localeCompare(b.relativePath));
 
-  const mirrorOnly = await collectMirrorOnlyPaths({
+  const { mirrorOnly, runtimeState } = splitRuntimeState(await collectMirrorOnlyPaths({
     plan,
     projectRoot,
     templatesRoot: pathConfig.templatesRoot,
-  });
+  }));
 
   if (checkOnly) {
     for (const { entry, relativePath } of drift) {
@@ -205,15 +214,19 @@ async function main() {
     for (const relativePath of mirrorOnly) {
       console.log(`MIRROR-ONLY ${relativePath}`);
     }
+    for (const relativePath of runtimeState) {
+      console.log(`RUNTIME-STATE ${relativePath} (protected; not drift)`);
+    }
 
+    const stateNote = runtimeState.length ? `, ${runtimeState.length} protected runtime-state file(s) ignored` : '';
     if (drift.length === 0 && mirrorOnly.length === 0) {
-      console.log(`ukit mirror check: clean (${managedRelativePaths.size} scoped targets)`);
+      console.log(`ukit mirror check: clean (${managedRelativePaths.size} scoped targets${stateNote})`);
       return 0;
     }
 
     console.log(
       `ukit mirror check: ${drift.length} drifted, ${mirrorOnly.length} mirror-only `
-        + `(${managedRelativePaths.size} scoped targets)`,
+        + `(${managedRelativePaths.size} scoped targets${stateNote})`,
     );
     return 1;
   }

package/scripts/release/candidate-state.mjs

@@ -0,0 +1,31 @@
+import { execFileSync } from 'node:child_process';
+import { lstatSync, readFileSync, readlinkSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+
+// Runtime receipts are outputs of verification, not release candidate inputs.
+// Canonical template_project runtime sources are deliberately NOT excluded.
+const mutable = /^(?:\.ukit\/storage\/|\.claude\/ukit\/runtime\/\.ukit\/storage\/|\.cache\/|node_modules\/)/;
+
+export function candidateFingerprint(root) {
+  const files = execFileSync('git', ['ls-files', '-z', '--cached', '--others', '--exclude-standard'], {
+    cwd: root, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024, timeout: 30_000,
+  }).split('\0').filter((file) => file && !mutable.test(file));
+  const hash = createHash('sha256');
+  for (const file of [...new Set(files)].sort()) {
+    hash.update(JSON.stringify(file));
+    const absolute = path.join(root, file);
+    let stat;
+    try { stat = lstatSync(absolute); } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      hash.update('\0deleted\0');
+      continue;
+    }
+    hash.update(`\0${stat.mode}\0`);
+    if (stat.isSymbolicLink()) hash.update(`link\0${readlinkSync(absolute)}`);
+    else if (stat.isFile()) hash.update(readFileSync(absolute));
+    else throw new Error(`Unsupported candidate entry: ${file}`);
+    hash.update('\0');
+  }
+  return hash.digest('hex');
+}

package/scripts/release/verify-release.mjs

@@ -1,8 +1,9 @@
-import { spawn } from 'node:child_process';
-import { readFileSync, writeFileSync, unlinkSync, existsSync } from 'node:fs';
+import { spawn, execFileSync } from 'node:child_process';
+import { readFileSync, writeFileSync, unlinkSync, existsSync, mkdtempSync } from 'node:fs';
 import crypto from 'node:crypto';
 import os from 'node:os';
 import path from 'node:path';
+import { candidateFingerprint } from './candidate-state.mjs';
 
 const rootDir = process.cwd();
 const npmCacheDir = path.join(os.tmpdir(), 'ukit-npm-cache');
@@ -75,6 +76,12 @@ const steps = [
     args: ['docs:render:check'],
     env: process.env,
   },
+  {
+    label: 'Live documentation preflight (headers, budgets, current status)',
+    command: 'yarn',
+    args: ['vitest', 'run', 'tests/consistency/liveStateDocs.test.js', 'tests/consistency/advisorStatusDocs.test.js'],
+    env: process.env,
+  },
   {
     label: 'Consistency suite (template<->active sync, watchdog coverage, render parity)',
     command: 'yarn',
@@ -117,17 +124,46 @@ const steps = [
   },
 ];
 
+const runDirectory = mkdtempSync(path.join(os.tmpdir(), 'ukit-release-run-'));
+const candidate = candidateFingerprint(rootDir);
+const run = { pid: process.pid, candidate, startedAt: new Date().toISOString(), phase: null, result: 'running', exitCode: null };
+const persistRun = () => writeFileSync(path.join(runDirectory, 'result.json'), `${JSON.stringify(run, null, 2)}\n`);
+persistRun();
+console.log(`[release:verify] Candidate ${candidate}; run evidence ${runDirectory}`);
+process.on('exit', (code) => {
+  run.exitCode = code;
+  if (run.result === 'running') run.result = 'failed';
+  run.finishedAt = new Date().toISOString();
+  persistRun();
+});
+function assertCandidate() {
+  if (candidateFingerprint(rootDir) !== candidate) {
+    console.error('[release:verify] FAILED: candidate changed during verification; no PASS applies to the current bytes.');
+    process.exit(1);
+  }
+}
+
 for (const step of steps) {
+  assertCandidate();
+  run.phase = step.label;
+  run.phaseStartedAt = new Date().toISOString();
+  run.phaseResult = null;
+  step.env = { ...step.env, UKIT_VERIFY_PROGRESS_FILE: path.join(runDirectory, `phase-${steps.indexOf(step)}-progress.json`) };
+  persistRun();
   console.log(`\n[release:verify] ${step.label}`);
   console.log(`[release:verify] > ${step.command} ${step.args.join(' ')}`);
 
   const exitCode = await runStep(step);
+  assertCandidate();
   if (exitCode !== 0) {
     console.error(`[release:verify] FAILED at step: ${step.label}`);
     process.exit(exitCode ?? 1);
   }
 }
 
+assertCandidate();
+run.result = 'passed';
+persistRun();
 console.log('\n[release:verify] All release checks passed.');
 
 // BUG-C22-20: bounded spawn — an armed watchdog SIGKILLs the child's whole
@@ -138,6 +174,16 @@ function spawnBounded(command, args, opts, timeoutMs) {
   child.ukitTimedOut = false;
   const watchdog = setTimeout(() => {
     child.ukitTimedOut = true;
+    // One bounded native snapshot before termination, never a polling watcher.
+    // ps contains no argv/environment (credentials); unsupported hosts record the error.
+    if (!postPublish && opts.env?.UKIT_VERIFY_PROGRESS_FILE) try {
+      const snapshot = execFileSync('ps', ['-axo', 'pid,ppid,pgid,stat,etime,time,comm'], {
+        encoding: 'utf8', timeout: 1000, maxBuffer: 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'],
+      });
+      writeFileSync(path.join(runDirectory, 'deadline-processes.txt'), snapshot);
+    } catch (error) {
+      writeFileSync(path.join(runDirectory, 'deadline-processes.txt'), `unavailable: ${error.code || error.message}\n`);
+    }
     try {
       process.kill(-child.pid, 'SIGKILL'); // kill the whole tree
     } catch {
@@ -157,13 +203,21 @@ function runStep({ command, args, env }) {
       stdio: 'inherit',
     }, STEP_TIMEOUT_MS);
 
-    child.on('exit', (code) => {
+    child.on('exit', (code, signal) => {
+      run.phaseResult = { pid: child.pid, nativeExitCode: code, signal,
+        terminationReason: child.ukitTimedOut ? 'phase-deadline' : signal ? 'signal' : 'native-exit',
+        elapsedMs: Date.now() - Date.parse(run.phaseStartedAt) };
+      persistRun();
       if (child.ukitTimedOut) {
-        console.error(`[release:verify] step timed out after ${STEP_TIMEOUT_MS}ms — child killed (check for a wedged ${command}/network)`);
+        console.error(`[release:verify] step timed out after ${STEP_TIMEOUT_MS}ms — child killed; phase progress: ${env.UKIT_VERIFY_PROGRESS_FILE}`);
       }
-      resolve(code ?? 1);
+      resolve(child.ukitTimedOut ? 1 : (code ?? 1));
+    });
+    child.on('error', (error) => {
+      run.phaseResult = { pid: child.pid ?? null, nativeExitCode: null, terminationReason: 'spawn-error', error: error.message };
+      persistRun();
+      resolve(1);
     });
-    child.on('error', () => resolve(1));
   });
 }
 

package/src/core/buildPlan.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { selectManifestItems } from '../manifest/selectItems.js';
 import { renderTemplateString } from '../render/renderTemplate.js';
 import { UKIT_PACKAGE_NAME } from './update.js';
+import { validateModuleClosureSync } from '../../scripts/install/module-dependency-closure.mjs';
 
 const BINARY_TEMPLATE_EXTENSIONS = new Set([
   '.ttf',
@@ -325,6 +326,7 @@ export async function buildInstallPlan({
     }
   }
 
+  validateModuleClosureSync(planEntries);
   await downgradeSelfInstallDocOverwrites(planEntries, { templatesRoot, projectRoot });
 
   return {