@ngockhoale/ukit 2.4.2 → 2.5.0

package/CHANGELOG.md

@@ -2,6 +2,63 @@
 
 All notable changes to UKit are documented here.
 
+## 2.5.0 - 2026-09-18
+
+C20 feature release (14 handoff tasks + 3-lane review): project-owner instructions via a
+seeded root `PROJECT_IMPORTANT.md`, delivered once per context epoch on every supported
+host.
+
+- **`PROJECT_IMPORTANT.md` seed-once ownership**: `ukit install` creates the file only
+  when missing (`mergeStrategy: skip`, exclusive `'wx'` create, `lstat`-based existence);
+  it is never rewritten, merged, chmodded, tracked in `install.json.files`, or deleted —
+  reinstalls preserve it byte-for-byte, and delete + reinstall re-seeds.
+- **Once-per-epoch injection**: Claude Code `SessionStart` (including
+  `source:'compact'` post-compact) and omp `session_start`/`session_compact` (steer only
+  — exactly one copy per epoch) render the file into advisory context; Codex and OpenCode
+  get a static read-the-file pointer in `AGENTS.md` (pointer, not runtime delivery).
+- **Bounded deterministic render** (`src/core/projectImportant.js` + installed-runtime
+  mirror): 6,000-Unicode-code-point limit with an explicit oversized warning, strict
+  UTF-8 decode (malformed input is never injected), BOM excluded from count and body,
+  `O_NOFOLLOW`/`O_NONBLOCK` open so symlinks/FIFOs/devices are never followed or hung on,
+  and a byte-identical envelope (no volatile metadata) for identical input.
+- **Fail-closed secret gate** (`src/core/sensitiveValueScanner.js`): the exact body to
+  be injected is scanned for high-confidence secret shapes; blocks report labels only —
+  never a value, excerpt, or hash.
+- **Uninstall backup**: `ukit uninstall` backs the file up to a sibling
+  `PROJECT_IMPORTANT.md.ukit-backup[.n]` at project root (`COPYFILE_EXCL`, bounded suffix
+  walk, byte-identical reuse, dry-run plans only) and aborts before any managed deletion
+  if the backup cannot be made.
+- **Honest-status surface**: `ukit status`/`ukit doctor` report per-check remediation
+  classes (`owner-action`/`install-repairable`/`advisory-host-limit`) and label local
+  prompt-cache stats as `Local p-cache` — provider telemetry is reported `unknown`, never
+  zero.
+
+## 2.4.3 - 2026-09-18
+
+C19 liveness-hardening release (23 handoff tasks): a full sweep of the shipped hook and
+runtime surface against the freeze/stall/orphan classes behind the recurring "session
+stands still mid-turn" reports, plus the regression instruments that keep them closed.
+
+- **Bounded hook stdin staging (H01)**: `hook-input.sh`/`hook-input.mjs` runtime helpers
+  plus bounded-staging fallback blocks in all 16 hook wrapper templates — a producer that
+  never closes the pipe can no longer hold a hook open (SIGKILL at the staging bound).
+- **Deadline-aware hot-hook filesystem work**: hook runtime modules self-arm on
+  `UKIT_HOOK_DEADLINE_MS` so a wedged read or lock wait exits inside the hook budget
+  instead of orphaning a node child.
+- **Process-tree + lock containment**: bounded process-tree kill when a descendant escapes
+  its group, atomic quarantine of validated stale lock generations, owner-stamp failure
+  no longer runs the callback under an ownerless lock, and deep-freeze + containment
+  fail-closed for discovery snapshot reuse.
+- **Liveness suite + classifier**: `src/diagnostics/classifyHang.js`, `tests/liveness/`,
+  and the `test:liveness` script — evidence-only hang classification (an external signal
+  is not a TERM→KILL leak) with regression scenarios pinned in tests.
+- **Execution-ledger hardening**: bounded route-scoped ledger journal, overflow guard on
+  drain commits, journal-local locking, and the Stop coordinator
+  (`stop-coordinator.mjs`) with its extracted watchdog path.
+- **Runtime shipping fix**: the install pipeline ships every packaged
+  `.claude/ukit/runtime` module via the `ukit-runtime-scripts` directory item (TASK-035),
+  closing the class where a new runtime module shipped to npm but never installed.
+
 ## 2.4.2 - 2026-09-16
 
 Fix: the gateway resilience posture disabled the only recovery path a buffering gateway

package/README.md

@@ -69,6 +69,26 @@ If maintainers roll out a newer CLI build, the in-project workflow still stays t
 - `.claude/ukit/.ukit/` — installer manifests, metadata, backups
 - `.ukit/` — hidden shared runtime storage for config, cache, and cross-agent memory
 - `docs/` — PROJECT / MEMORY / AI_HANDOFF / WORKLOG baseline
+- `PROJECT_IMPORTANT.md` — your project-owner instruction file (see below)
+
+## `PROJECT_IMPORTANT.md` — project-owner instructions
+
+`ukit install` seeds a root `PROJECT_IMPORTANT.md` **once**. After that the file is
+yours: UKit never rewrites, merges, formats, chmods, tracks, or deletes it — edits
+survive every `ukit install` rerun byte-for-byte, and deleting it + reinstalling
+seeds a fresh copy. It is also excluded from `ukit uninstall` deletion; uninstall
+backs it up to a sibling `PROJECT_IMPORTANT.md.ukit-backup[.n]` file at project
+root (never overwritten — a new suffix is chosen, and dry-run creates nothing).
+
+Put your non-negotiable project rules there. On each session start your AI tool
+receives its contents as advisory project-owner context — Claude Code and omp via
+their session hooks (and once more after a compaction, which starts a new context
+epoch), Codex and OpenCode via a static pointer in `AGENTS.md` (read-the-file
+instructions, not a runtime hook). Keep the file at or below **6,000 Unicode code
+points** — anything past that is truncated with an explicit warning, and the fix is
+to shorten the file, not rerun `ukit install`. Do not put credentials or secrets in
+it: a fail-closed sensitive-value scan runs on the exact body before injection and
+blocks anything that looks like a key or token.
 
 ## UKit v1.3.1 Runtime
 

package/manifests/platform.full.yaml

@@ -19,6 +19,20 @@ items:
     packs:
       - core
 
+  # Owner-instruction seed. `mergeStrategy: skip` gives seed-once semantics: UKit writes it
+  # only when the path is truly absent (exclusive 'wx' create in applyPlan), never rewrites,
+  # merges, formats, chmods or tracks it in install.json afterwards.
+  - id: project-important
+    type: config
+    sourceTemplate: PROJECT_IMPORTANT.md
+    targetPath: PROJECT_IMPORTANT.md
+    requires: []
+    mergeStrategy: skip
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: docs-memory
     type: config
     sourceTemplate: docs/MEMORY.md
@@ -987,6 +1001,7 @@ items:
       - hook-block-dangerous
       - hook-handoff-model-guard
       - hook-auto-prune-bash
+      - hook-project-important
     # Env block is post-merged by applyGatewayResilienceEnv (TASK-011) to add managed
     # gateway-resilience defaults without clobbering user values, so the diff ignores
     # the env block — byte-equality on the rest of the file is enough to flag an update.
@@ -1059,7 +1074,7 @@ items:
     sourceTemplate: .claude/hooks/record-execution.sh
     targetPath: .claude/hooks/record-execution.sh
     requires:
-      - ukit-runtime-execution-ledger-script
+      - ukit-runtime-scripts
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -1071,7 +1086,7 @@ items:
     sourceTemplate: .claude/hooks/completion-gate.sh
     targetPath: .claude/hooks/completion-gate.sh
     requires:
-      - ukit-runtime-execution-ledger-script
+      - ukit-runtime-scripts
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -1111,11 +1126,15 @@ items:
     packs:
       - core
 
+  # requires: [ukit-runtime-scripts] is forward-declared for the shared sensitive-value
+  # scanner (consumed by the guard once TASK-039 wires it). The guard is fail-closed, so
+  # its runtime dependency must be installed first — keeps the ordering posture explicit.
   - id: hook-sensitive-data-guard
     type: hook
     sourceTemplate: .claude/hooks/sensitive-data-guard.sh
     targetPath: .claude/hooks/sensitive-data-guard.sh
-    requires: []
+    requires:
+      - ukit-runtime-scripts
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -1139,7 +1158,7 @@ items:
     targetPath: .claude/hooks/skill-router.sh
     requires:
       - ukit-index-route-catalog-script
-      - ukit-runtime-compact-threshold-script
+      - ukit-runtime-scripts
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -1164,7 +1183,7 @@ items:
     sourceTemplate: .claude/hooks/context-hardcap-gate.sh
     targetPath: .claude/hooks/context-hardcap-gate.sh
     requires:
-      - ukit-runtime-compact-threshold-script
+      - ukit-runtime-scripts
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -1204,10 +1223,16 @@ items:
     packs:
       - core
 
-  - id: ukit-runtime-task-watchdog-script
+  # One directory item ships the whole runtime dir. autoDiscoverTemplates:false silently
+  # skips any template file without an explicit item, which is exactly how later-wave
+  # runtime modules (async-lock.mjs, hook-process.mjs, transcript-tail.mjs, hook-input.*)
+  # never reached installed projects and broke execution-ledger.mjs imports at hook time.
+  # A directory scan keeps every new runtime module shipping without a manifest edit; the
+  # walker preserves per-file modes (hook-input.sh keeps its exec bit).
+  - id: ukit-runtime-scripts
     type: config
-    sourceTemplate: .claude/ukit/runtime/task-watchdog.mjs
-    targetPath: .claude/ukit/runtime/task-watchdog.mjs
+    sourceTemplate: .claude/ukit/runtime
+    targetPath: .claude/ukit/runtime
     requires: []
     mergeStrategy: overwrite_with_backup
     variables: []
@@ -1231,7 +1256,7 @@ items:
     sourceTemplate: .claude/hooks/compress-output.sh
     targetPath: .claude/hooks/compress-output.sh
     requires:
-      - ukit-runtime-output-compression-script
+      - ukit-runtime-scripts
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -1249,6 +1274,18 @@ items:
     packs:
       - core
 
+  - id: hook-project-important
+    type: hook
+    sourceTemplate: .claude/hooks/project-important.sh
+    targetPath: .claude/hooks/project-important.sh
+    requires:
+      - ukit-runtime-scripts
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: hook-worklog-session-start
     type: hook
     sourceTemplate: .claude/hooks/session-start.md
@@ -1273,58 +1310,12 @@ items:
     packs:
       - core
 
-  - id: ukit-runtime-text-profile-script
-    type: config
-    sourceTemplate: .claude/ukit/runtime/text-profile.mjs
-    targetPath: .claude/ukit/runtime/text-profile.mjs
-    requires: []
-    mergeStrategy: overwrite_with_backup
-    variables: []
-    enabledByDefault: true
-    packs:
-      - core
-
-  - id: ukit-runtime-execution-ledger-script
-    type: config
-    sourceTemplate: .claude/ukit/runtime/execution-ledger.mjs
-    targetPath: .claude/ukit/runtime/execution-ledger.mjs
-    requires: []
-    mergeStrategy: overwrite_with_backup
-    variables: []
-    enabledByDefault: true
-    packs:
-      - core
-
-  - id: ukit-runtime-hook-chain-runner-script
-    type: config
-    sourceTemplate: .claude/ukit/runtime/hook-chain-runner.mjs
-    targetPath: .claude/ukit/runtime/hook-chain-runner.mjs
-    requires: []
-    mergeStrategy: overwrite_with_backup
-    variables: []
-    enabledByDefault: true
-    packs:
-      - core
-
-  - id: ukit-runtime-safe-patch-core-script
-    type: config
-    sourceTemplate: .claude/ukit/runtime/safe-patch-core.mjs
-    targetPath: .claude/ukit/runtime/safe-patch-core.mjs
-    requires:
-      - ukit-runtime-text-profile-script
-    mergeStrategy: overwrite_with_backup
-    variables: []
-    enabledByDefault: true
-    packs:
-      - core
-
   - id: ukit-index-anchor-search-script
     type: config
     sourceTemplate: .claude/ukit/index/anchor-search.mjs
     targetPath: .claude/ukit/index/anchor-search.mjs
     requires:
-      - ukit-runtime-text-profile-script
-      - ukit-runtime-safe-patch-core-script
+      - ukit-runtime-scripts
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -1348,8 +1339,7 @@ items:
     sourceTemplate: .claude/ukit/index/provision-worktree.mjs
     targetPath: .claude/ukit/index/provision-worktree.mjs
     requires:
-      - ukit-runtime-text-profile-script
-      - ukit-runtime-safe-patch-core-script
+      - ukit-runtime-scripts
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -1361,8 +1351,7 @@ items:
     sourceTemplate: .claude/ukit/index/stale-spec-check.mjs
     targetPath: .claude/ukit/index/stale-spec-check.mjs
     requires:
-      - ukit-runtime-text-profile-script
-      - ukit-runtime-safe-patch-core-script
+      - ukit-runtime-scripts
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -1374,8 +1363,7 @@ items:
     sourceTemplate: .claude/ukit/index/pre-edit-backup.mjs
     targetPath: .claude/ukit/index/pre-edit-backup.mjs
     requires:
-      - ukit-runtime-text-profile-script
-      - ukit-runtime-safe-patch-core-script
+      - ukit-runtime-scripts
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -1387,8 +1375,7 @@ items:
     sourceTemplate: .claude/ukit/index/post-edit-verify.mjs
     targetPath: .claude/ukit/index/post-edit-verify.mjs
     requires:
-      - ukit-runtime-text-profile-script
-      - ukit-runtime-safe-patch-core-script
+      - ukit-runtime-scripts
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -1549,54 +1536,6 @@ items:
     packs:
       - core
 
-  - id: ukit-runtime-token-utils-script
-    type: config
-    sourceTemplate: .claude/ukit/runtime/token-utils.mjs
-    targetPath: .claude/ukit/runtime/token-utils.mjs
-    mergeStrategy: overwrite_with_backup
-    variables: []
-    enabledByDefault: true
-    packs:
-      - core
-
-  - id: ukit-runtime-compact-threshold-script
-    type: config
-    sourceTemplate: .claude/ukit/runtime/compact-threshold.mjs
-    targetPath: .claude/ukit/runtime/compact-threshold.mjs
-    requires:
-      - ukit-runtime-token-utils-script
-    mergeStrategy: overwrite_with_backup
-    variables: []
-    enabledByDefault: true
-    packs:
-      - core
-
-  - id: ukit-runtime-reinject-context-script
-    type: config
-    sourceTemplate: .claude/ukit/runtime/reinject-context.mjs
-    targetPath: .claude/ukit/runtime/reinject-context.mjs
-    requires:
-      - ukit-runtime-token-utils-script
-      - ukit-runtime-compact-threshold-script
-    mergeStrategy: overwrite_with_backup
-    variables: []
-    enabledByDefault: true
-    packs:
-      - core
-
-  - id: ukit-runtime-output-compression-script
-    type: config
-    sourceTemplate: .claude/ukit/runtime/output-compression.mjs
-    targetPath: .claude/ukit/runtime/output-compression.mjs
-    requires:
-      - ukit-runtime-token-utils-script
-      - ukit-runtime-compact-threshold-script
-    mergeStrategy: overwrite_with_backup
-    variables: []
-    enabledByDefault: true
-    packs:
-      - core
-
   - id: ukit-index-reset-auto-permissions-script
     type: config
     sourceTemplate: .claude/ukit/index/reset-auto-permissions.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.4.2",
+  "version": "2.5.0",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex, OpenCode, and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",
@@ -59,6 +59,7 @@
     "test:release-core": "vitest run --exclude tests/integration/packageArtifact.test.js",
     "release:verify": "node ./scripts/release/verify-release.mjs",
     "test": "vitest run",
+    "test:liveness": "vitest run tests/liveness/",
     "test:watch": "vitest"
   },
   "engines": {

package/scripts/index/refresh-index.mjs

@@ -19,39 +19,64 @@ const changedFiles = changedArg
 
 const force = readBooleanFlag(args, '--force');
 const lastRefreshMs = await getLastRefreshTime(rootDir);
-const staleness = force
-  ? null
-  : await inspectIndexStaleness({ rootDir, maxAgeMs: DEFAULT_INDEX_CACHE_MAX_AGE_MS });
-const stale = force || staleness.stale;
 
-if (!stale) {
-  console.log('[index:refresh] skipped (cache fresh)');
-  if (lastRefreshMs !== null) {
-    console.log(`lastRefresh: ${new Date(lastRefreshMs).toISOString()}`);
-  }
-  if (changedFiles.length > 0) {
-    console.log(`changed-files-hint: ${changedFiles.join(', ')}`);
-  }
-  console.log(`root: ${rootDir}`);
-} else {
-  // Reuse the staleness check's discovery snapshot: one enumeration per refresh.
-  const summary = await buildCodeIndex({
-    rootDir,
-    discoverySnapshot: staleness ? staleness.snapshot : null,
-  });
+if (changedFiles.length > 0 && !force) {
+  // Hints carry the change set, so no staleness enumeration is needed:
+  // buildCodeIndex merges the hinted paths into the existing artifacts and
+  // falls back to the bounded full discovery path on its own when the hints
+  // are unsafe or the previous artifacts cannot be merged (TASK-023).
+  const summary = await buildCodeIndex({ rootDir, changedFiles });
 
   console.log('[index:refresh] completed');
+  console.log(`mode: ${summary.mode}`);
   if (lastRefreshMs !== null) {
     console.log(`lastRefreshBefore: ${new Date(lastRefreshMs).toISOString()}`);
   }
-  if (changedFiles.length > 0) {
-    console.log(`changed-files-hint: ${changedFiles.join(', ')}`);
-  }
+  console.log(`changed-files-hint: ${changedFiles.join(', ')}`);
   console.log(`root: ${rootDir}`);
   console.log(`files: ${summary.fileCount}`);
   console.log(`parsed: ${summary.parsedCodeFileCount}`);
   console.log(`reused: ${summary.reusedCodeFileCount}`);
+  if (summary.removedFiles.length > 0) {
+    console.log(`removed: ${summary.removedFiles.length}`);
+  }
   console.log(`indexDir: ${summary.indexDir}`);
+} else {
+  const staleness = force
+    ? null
+    : await inspectIndexStaleness({ rootDir, maxAgeMs: DEFAULT_INDEX_CACHE_MAX_AGE_MS });
+  const stale = force || staleness.stale;
+
+  if (!stale) {
+    console.log('[index:refresh] skipped (cache fresh)');
+    if (lastRefreshMs !== null) {
+      console.log(`lastRefresh: ${new Date(lastRefreshMs).toISOString()}`);
+    }
+    if (changedFiles.length > 0) {
+      console.log(`changed-files-hint: ${changedFiles.join(', ')}`);
+    }
+    console.log(`root: ${rootDir}`);
+  } else {
+    // Reuse the staleness check's discovery snapshot: one enumeration per refresh.
+    const summary = await buildCodeIndex({
+      rootDir,
+      discoverySnapshot: staleness ? staleness.snapshot : null,
+    });
+
+    console.log('[index:refresh] completed');
+    console.log(`mode: ${summary.mode}`);
+    if (lastRefreshMs !== null) {
+      console.log(`lastRefreshBefore: ${new Date(lastRefreshMs).toISOString()}`);
+    }
+    if (changedFiles.length > 0) {
+      console.log(`changed-files-hint: ${changedFiles.join(', ')}`);
+    }
+    console.log(`root: ${rootDir}`);
+    console.log(`files: ${summary.fileCount}`);
+    console.log(`parsed: ${summary.parsedCodeFileCount}`);
+    console.log(`reused: ${summary.reusedCodeFileCount}`);
+    console.log(`indexDir: ${summary.indexDir}`);
+  }
 }
 
 function readFlagValue(argv, flag) {

package/src/cli/commands/doctor.js

@@ -18,6 +18,10 @@ import {
   GATEWAY_RESILIENCE_ENV_DEFAULTS,
   scanProfileResilienceEnv,
 } from '../../core/gatewayResilienceEnv.js';
+import {
+  inspectProjectImportant,
+  inspectProjectImportantWiring,
+} from '../../core/projectImportant.js';
 
 export const DOCTOR_HELP_FLAGS = new Set(['--help', '-h']);
 const KNOWN_FLAGS = new Set([...DOCTOR_HELP_FLAGS, '--skills', '--gateway']);
@@ -103,6 +107,109 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir =
 
   const ok = (v) => (v ? '✓' : '✗');
 
+  // TASK-044 — typed PROJECT_IMPORTANT.md checks (spec §14). Each failure
+  // carries a class: install-repairable | owner-action | advisory-host-limit.
+  const INSTALL_REPAIR = 'Run ukit install';
+  const piInspection = await inspectProjectImportant({
+    projectRoot,
+    config: runtimeConfigInspection.config,
+  });
+  const piWiring = await inspectProjectImportantWiring(projectRoot, { trackedPaths });
+  const piState = piInspection.state;
+
+  const contentCheck = (failedState, label, remedy) => ({
+    label,
+    passed: piState !== failedState && piState !== 'missing' && piState !== 'unsafe-type' && piState !== 'unreadable',
+    applicable: piState !== 'missing' && piState !== 'unsafe-type' && piState !== 'unreadable',
+    failed: piState === failedState,
+    remediationClass: 'owner-action',
+    remedy,
+  });
+
+  const projectChecks = [
+    {
+      label: 'PROJECT_IMPORTANT.md exists',
+      passed: piState !== 'missing',
+      failed: piState === 'missing',
+      remediationClass: 'install-repairable',
+      remedy: INSTALL_REPAIR,
+    },
+    {
+      label: 'PROJECT_IMPORTANT.md is a regular non-symlink file',
+      passed: piState !== 'unsafe-type' && piState !== 'missing',
+      failed: piState === 'unsafe-type',
+      applicable: piState !== 'missing',
+      remediationClass: 'owner-action',
+      remedy: 'Replace PROJECT_IMPORTANT.md with a regular file at the project root.',
+    },
+    {
+      label: 'PROJECT_IMPORTANT.md is readable',
+      passed: piState !== 'unreadable' && piState !== 'missing' && piState !== 'unsafe-type',
+      failed: piState === 'unreadable',
+      applicable: piState !== 'missing' && piState !== 'unsafe-type',
+      remediationClass: 'advisory-host-limit',
+      remedy: 'Check PROJECT_IMPORTANT.md file permissions; the host cannot read it.',
+    },
+    contentCheck('invalid-utf8', 'PROJECT_IMPORTANT.md is valid UTF-8',
+      'Save PROJECT_IMPORTANT.md as valid UTF-8 without changing its intended content.'),
+    contentCheck('unsafe-control', 'PROJECT_IMPORTANT.md free of unsupported control characters',
+      'Remove unsupported control characters from PROJECT_IMPORTANT.md.'),
+    contentCheck('empty', 'PROJECT_IMPORTANT.md is not empty',
+      'Add project-owner instructions to PROJECT_IMPORTANT.md.'),
+    contentCheck('oversized', 'PROJECT_IMPORTANT.md within 6,000 code points',
+      'Shorten PROJECT_IMPORTANT.md to 6,000 Unicode code points or fewer.'),
+    contentCheck('secret-blocked', 'PROJECT_IMPORTANT.md free of unallowlisted secrets',
+      'Redact the secret or explicitly allowlist it.'),
+    {
+      label: 'Runtime module .claude/ukit/runtime/project-important.mjs',
+      passed: piWiring.claude.runtimeModule,
+      failed: !piWiring.claude.runtimeModule,
+      remediationClass: 'install-repairable',
+      remedy: INSTALL_REPAIR,
+    },
+    {
+      label: 'Hook wrapper .claude/hooks/project-important.sh installed and executable',
+      passed: piWiring.claude.hookInstalled && piWiring.claude.hookExecutable,
+      failed: !(piWiring.claude.hookInstalled && piWiring.claude.hookExecutable),
+      remediationClass: 'install-repairable',
+      remedy: INSTALL_REPAIR,
+    },
+    {
+      label: 'Claude settings SessionStart order (project-important.sh first)',
+      passed: piWiring.claude.settingsWired,
+      failed: !piWiring.claude.settingsWired,
+      remediationClass: 'install-repairable',
+      remedy: INSTALL_REPAIR,
+    },
+  ];
+  if (piWiring.omp.installed) {
+    projectChecks.push({
+      label: 'omp bridge session_start order (project-important.sh first)',
+      passed: piWiring.omp.wired,
+      failed: !piWiring.omp.wired,
+      remediationClass: 'install-repairable',
+      remedy: INSTALL_REPAIR,
+    });
+  }
+  if (piWiring.codex.installed) {
+    projectChecks.push({
+      label: 'Codex fallback present (AGENTS.md owner-instructions section)',
+      passed: piWiring.codex.wired,
+      failed: !piWiring.codex.wired,
+      remediationClass: 'install-repairable',
+      remedy: INSTALL_REPAIR,
+    });
+  }
+  if (piWiring.opencode.installed) {
+    projectChecks.push({
+      label: 'OpenCode fallback present (AGENTS.md owner-instructions section)',
+      passed: piWiring.opencode.wired,
+      failed: !piWiring.opencode.wired,
+      remediationClass: 'install-repairable',
+      remedy: INSTALL_REPAIR,
+    });
+  }
+
   const providerNames = Object.keys(providers.providers);
   const providerStatus = providerNames
     .map((name) => `${name}=${ok(providers.providers[name].supported)}`)
@@ -139,6 +246,12 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir =
   }
   console.log(`[UKit]   ${ok(checks.allProvidersConfigured)}  All providers configured`);
 
+  console.log('[UKit] Project rules checks:');
+  for (const check of projectChecks) {
+    if (check.applicable === false) continue;
+    console.log(`[UKit]   ${ok(check.passed)}  ${check.label}`);
+  }
+
   if (runtimeConfigInspection.errors.length > 0) {
     console.log(`[UKit] Runtime config issues: ${runtimeConfigInspection.errors.join(' | ')}`);
   }
@@ -254,8 +367,25 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir =
   }
 
   const allPassed = Object.values(checks).every(Boolean);
-  if (!allPassed) {
-    console.log('[UKit] Some checks failed. Run `ukit install` to fix missing files.');
+  const failedProjectChecks = projectChecks.filter(
+    (check) => check.applicable !== false && !check.passed,
+  );
+  const blockingFailures = failedProjectChecks.filter(
+    (check) => check.remediationClass === 'install-repairable' || check.remediationClass === 'owner-action',
+  );
+
+  if (failedProjectChecks.length > 0) {
+    console.log('[UKit] Remedies:');
+    for (const check of failedProjectChecks) {
+      console.log(`[UKit]   - [${check.remediationClass}] ${check.remedy}`);
+    }
+  }
+
+  if (!allPassed || blockingFailures.length > 0) {
+    console.log('[UKit] Some checks failed.');
+    if (!allPassed && blockingFailures.length === 0) {
+      console.log('[UKit] Re-run `ukit install` to repair install-managed files.');
+    }
     process.exitCode = 1;
   } else {
     console.log('[UKit] All checks passed.');

package/src/cli/commands/uninstall.js

@@ -42,10 +42,28 @@ export async function runUninstall({ projectRoot, argv = [] }) {
     for (const p of result.wouldRemove) {
       console.log(`  - ${path.relative(projectRoot, p)}`);
     }
+    for (const p of result.preservedPaths ?? []) {
+      console.log(`[UKit] Preserved ${path.basename(p)}.`);
+    }
+    if (result.wouldBackup && (result.backupPaths ?? []).length > 0) {
+      console.log(`[UKit] Would back up to ${path.basename(result.backupPaths[0])}.`);
+    }
+    for (const warning of result.backupWarnings ?? []) {
+      console.log(warning);
+    }
     console.log(`[UKit] Would remove ${result.wouldRemove.length} path(s). Run without --dry-run to actually uninstall.`);
     return;
   }
 
+  for (const p of result.preservedPaths ?? []) {
+    console.log(`[UKit] Preserved ${path.basename(p)}.`);
+  }
+  for (const p of result.backupPaths ?? []) {
+    console.log(`[UKit] Backup: ${path.basename(p)}`);
+  }
+  for (const warning of result.backupWarnings ?? []) {
+    console.log(warning);
+  }
   console.log(`[UKit] Uninstall complete. Removed ${result.removed}/${result.attempted} managed paths.`);
   console.log('[UKit] Note: docs/PROJECT.md, docs/MEMORY.md, docs/AI_HANDOFF/, docs/WORKLOG.md contain user content and were preserved. Delete manually if needed.');
 }