litclaude-ai 0.3.32 → 0.3.33

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.3.33 - 2026-07-24 — update notice and installed catalog verification
+
+- Add a nonblocking npm update notice for interactive `install`, `update`, and
+  `doctor`, backed by a strict product cache, atomic concurrent reservation,
+  and bounded official registry refresh. Attempt timestamps throttle successful,
+  offline, failed, and interrupted checks for 24 hours without discarding the
+  last trusted result; stale trusted results may still notify, while future or
+  noncanonical timestamps fail safe. Transition/recovery mutex ownership and
+  per-attempt generation fencing prevent stale takeover or late-worker cache
+  overwrite. CI/JSON/dry-run/non-TTY and environment opt-outs remain authoritative.
+- Preserve the installed permission mode and HUD accent during an optionless
+  reinstall while retaining explicit overrides.
+- Make source doctor, install verification, installed doctor, and Claude plugin
+  details share the exact canonical skill catalog. Missing installed skill
+  payloads now fail with `DOCTOR_FAIL`, and packed-install corruption coverage
+  proves the user-facing doctor cannot report success for an incomplete catalog.
+- Add a narrow native `/goal` capability matrix for user/Remote Control,
+  SDK-owned, separate print, and already-open TUI session boundaries without a
+  plugin runtime bridge, including minimum client, workspace trust, policy/hook,
+  and SDK-advertised command prerequisites.
+
 ## 0.3.32 - 2026-07-23 — bounded-authority start-work lifecycle
 
 - Added a code-owned schema-3 start-work runtime with canonical authority roots,

package/README.md

@@ -9,7 +9,7 @@
 </p>
 <p align="center">
   <img src="https://img.shields.io/badge/npm-litclaude--ai-cb3837" />
-  <img src="https://img.shields.io/badge/version-0.3.32-2ea44f" />
+  <img src="https://img.shields.io/badge/version-0.3.33-2ea44f" />
   <img src="https://img.shields.io/badge/Claude%20Code-plugin-blueviolet" />
   <img src="https://img.shields.io/badge/license-MIT-blue" />
 </p>
@@ -22,10 +22,10 @@
 > `litclaude@litclaude-ai`, so normal `claude` launches can load the
 > LitClaude skills and hooks without a long `--plugin-dir` command.
 
-This checkout is prepared as `litclaude-ai@0.3.32` for personal install
+This checkout is prepared as `litclaude-ai@0.3.33` for personal install
 convenience. The repo can remain quiet; preparing npm package metadata here does
 not imply public repo promotion, marketplace publication, or advertisement.
-Future package releases still require explicit user approval. The v0.3.32 release material adds the code-owned schema-3 start-work lifecycle with canonical bounded authority, explicit single-use resume grants, PreToolUse enforcement, root/subagent lane identity, progress-bound Stop continuation receipts, and fail-closed release boundaries. The v0.3.31 release material hardens litgoal creation, replacement, completion, and autoloop receipts while making visual QA browser ownership, bounded waits, blocked states, and cleanup evidence explicit. The v0.3.30 release material strengthens LitResearch with root-owned scientific evidence records, DOI/PDF lifecycle receipts, bounded route coverage, and a connection-pinned public-source reader with inert-content and secret-redaction guarantees. The v0.3.29 release material bundles exact-source `lit-handoff` and `lit-scientific-visualization` skills with Claude-native commands, exact-bare hook invocation, visible LITBURN banners, installed-payload integrity checks, and read-only scientific dependency diagnostics. The v0.3.28 release material requires explicit leading start-work invocations so diagnostic or copied mentions remain inert. The v0.3.27 release material adds a structured, animated five-stage installer with a success or failure receipt while preserving deterministic automation output. The v0.3.26 release material adds adaptive objective-achievable planning, draft-plan review, and orchestration readiness hardening. The v0.3.25 release material aligns portable details, public-read, litgoal status JSON, and evidence wording. The v0.3.24 release material aligns auxiliary skill inventories and advisory probes. The v0.3.23
+Future package releases still require explicit user approval. The v0.3.33 release material adds a quiet nonblocking npm update notice with strict cache, concurrency, timestamp, opt-out, and official-registry boundaries; preserves the installed permission mode and HUD accent on optionless updates; and makes source, install, installed-doctor, and Claude-details checks share the exact canonical skill catalog so missing packaged skills fail with `DOCTOR_FAIL`. The v0.3.32 release material adds the code-owned schema-3 start-work lifecycle with canonical bounded authority, explicit single-use resume grants, PreToolUse enforcement, root/subagent lane identity, progress-bound Stop continuation receipts, and fail-closed release boundaries. The v0.3.31 release material hardens litgoal creation, replacement, completion, and autoloop receipts while making visual QA browser ownership, bounded waits, blocked states, and cleanup evidence explicit. The v0.3.30 release material strengthens LitResearch with root-owned scientific evidence records, DOI/PDF lifecycle receipts, bounded route coverage, and a connection-pinned public-source reader with inert-content and secret-redaction guarantees. The v0.3.29 release material bundles exact-source `lit-handoff` and `lit-scientific-visualization` skills with Claude-native commands, exact-bare hook invocation, visible LITBURN banners, installed-payload integrity checks, and read-only scientific dependency diagnostics. The v0.3.28 release material requires explicit leading start-work invocations so diagnostic or copied mentions remain inert. The v0.3.27 release material adds a structured, animated five-stage installer with a success or failure receipt while preserving deterministic automation output. The v0.3.26 release material adds adaptive objective-achievable planning, draft-plan review, and orchestration readiness hardening. The v0.3.25 release material aligns portable details, public-read, litgoal status JSON, and evidence wording. The v0.3.24 release material aligns auxiliary skill inventories and advisory probes. The v0.3.23
 release materials inject the bundled skill bodies for bare `hyperplan`,
 `litresearch`, `lit research`, `init-deep`, and explicit `$start-work` prompt-hook routes while
 preserving the v0.3.19 adversarial planning skill, the v0.3.18 read-only `lit-recap` session recap surface, the v0.3.17 separate-worker native `/goal` launcher, the v0.3.16
@@ -131,7 +131,7 @@ directory, the normal install command works:
 
 ```bash
 cd /tmp
-npx --yes litclaude-ai@0.3.32 install
+npx --yes litclaude-ai@0.3.33 install
 ```
 
 Validate the installed plugin:
@@ -140,11 +140,26 @@ Validate the installed plugin:
 npx --yes litclaude-ai doctor
 ```
 
+Interactive `install`, `update`, and `doctor` runs may show a quiet update notice
+on stderr from LitClaude's own cache. A strictly validated last successful
+version may still be shown after it becomes stale. At most one new attempt is
+reserved per 24 hours across concurrent parents; that reservation remains after
+offline, failed, or interrupted refreshes while preserving the last successful
+version and check time. A transition/recovery mutex and per-attempt ownership
+generation serialize stale takeover and completion, so an old worker cannot
+remove a newer reservation or overwrite its result. The refresh is a detached, three-second request to the
+official npm registry, so the management command does not wait. Noncanonical or
+future cache timestamps are not trusted. The notice is disabled for CI, JSON,
+dry-run, or non-TTY use and by either `NO_UPDATE_NOTIFIER` or
+`LITCLAUDE_NO_UPDATE_CHECK`. It never reads npm credentials or installs an
+update. Follow the version-pinned `npx --yes litclaude-ai@<version> install`
+command shown in the notice, then restart Claude Code.
+
 The installer also sets Claude Code's `statusLine` command to the packaged
 LitClaude HUD. A typical no-color render starts like:
 
 ```text
-[🔥LITCLAUDE v0.3.32] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
+[🔥LITCLAUDE v0.3.33] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
 ```
 
 The `↻` suffix is a compact rate-limit reset countdown. It is separated from
@@ -159,6 +174,10 @@ To override the accent without the picker, set `LITCLAUDE_HUD_ACCENT` to one
 of `cyan`, `blue`, `teal`, `green`, `lavender`, `rose`, `gold`, `orange`,
 `slate`, or `gray` before installing.
 
+An optionless `litclaude update` preserves the installed permission mode and
+HUD accent. An explicit `--permission-mode` / `--yolo` choice or
+`LITCLAUDE_HUD_ACCENT` value still overrides the saved choice.
+
 Launch Claude Code normally:
 
 ```bash
@@ -294,6 +313,9 @@ litclaude litgoal native-worker --condition "<completion condition>" --mode bg -
 `native-worker` starts a separate print/background Claude Code worker whose first
 prompt begins with `/goal`; it does not arm the already-open TUI, does not use
 tmux keystroke injection, and does not mutate private transcript metadata.
+See the clean-room [native `/goal` surface matrix](./docs/native-goal-surface.md)
+for the separate User / Remote Control, SDK-owned, `claude -p`, and already-open
+TUI capability boundaries plus a ready-to-paste ledger-backed condition.
 For large independent work, LitClaude applies the same principle to Claude
 Code's available orchestration surfaces: `lit workflow`, `lit dynamic workflow`,
 and `lit ultracode` prefer current `ultracode` or explicit “run a workflow” /

package/README_ko-KR.md

@@ -9,7 +9,7 @@
 </p>
 <p align="center">
   <img src="https://img.shields.io/badge/npm-litclaude--ai-cb3837" />
-  <img src="https://img.shields.io/badge/version-0.3.32-2ea44f" />
+  <img src="https://img.shields.io/badge/version-0.3.33-2ea44f" />
   <img src="https://img.shields.io/badge/Claude%20Code-plugin-blueviolet" />
   <img src="https://img.shields.io/badge/license-MIT-blue" />
 </p>
@@ -26,11 +26,11 @@
 > 설치되므로, 매번 긴 `--plugin-dir` 없이 일반 `claude` 실행에서
 > LitClaude skill과 hook을 불러올 수 있습니다.
 
-현재 checkout은 `litclaude-ai@0.3.32` 배포 준비용으로 정리되어 있습니다. 목적은
+현재 checkout은 `litclaude-ai@0.3.33` 배포 준비용으로 정리되어 있습니다. 목적은
 다른 PC에서도 빠르게 설치하기 위한 개인용 package metadata를 갖추는 것입니다.
 npm package metadata를 준비했다고 해서 홍보, 공개 저장소 운영, Claude
 marketplace 등록을 의미하지는 않습니다. 새 버전 배포는 항상 별도의 명시적
-승인 후에 진행합니다. v0.3.32 release material은 canonical bounded authority, single-use resume grant, PreToolUse enforcement, root/subagent lane identity, progress-bound Stop continuation receipt, fail-closed release boundary를 갖춘 code-owned schema-3 start-work lifecycle을 추가합니다. v0.3.31 release material은 litgoal 생성·교체·완료와 autoloop receipt를 강화하고 visual QA의 browser ownership, bounded wait, blocked state, cleanup evidence를 명확히 합니다. v0.3.30 release material은 root-owned scientific evidence record, DOI/PDF lifecycle receipt, bounded route coverage, connection-pinned public-source reader, inert-content 및 secret-redaction 보장을 포함하는 LitResearch 강화판입니다. v0.3.29 release material은 exact-source `lit-handoff`와 `lit-scientific-visualization` skill, Claude-native command, exact-bare hook invocation, visible LITBURN banner, installed-payload integrity check, read-only scientific dependency diagnostic을 함께 포함합니다. v0.3.28 release material은 start-work 호출을 prompt 선두의 명시적 invocation으로 제한해 진단문이나 복사된 언급을 비활성 상태로 유지합니다. v0.3.27 release material은 success/failure receipt와 deterministic automation output을 갖춘 5-stage animated installer를 추가합니다. v0.3.26 release material은 adaptive objective-achievable planning, draft-plan review, orchestration readiness hardening을 추가합니다. v0.3.25 release material은 portable details, public-read, litgoal status JSON, evidence wording을 정렬합니다. v0.3.24 release material은 auxiliary skill inventory와 advisory probe를 정렬합니다. v0.3.23 release material은 bare `hyperplan`,
+승인 후에 진행합니다. v0.3.33 release material은 strict cache, concurrency, timestamp, opt-out, official-registry boundary를 갖춘 조용한 nonblocking npm update notice를 추가하고, optionless update에서 기존 permission mode와 HUD accent를 보존하며, source/install/installed doctor/Claude details가 정확한 canonical skill catalog를 공유해 packaged skill 누락 시 `DOCTOR_FAIL`로 실패하도록 합니다. v0.3.32 release material은 canonical bounded authority, single-use resume grant, PreToolUse enforcement, root/subagent lane identity, progress-bound Stop continuation receipt, fail-closed release boundary를 갖춘 code-owned schema-3 start-work lifecycle을 추가합니다. v0.3.31 release material은 litgoal 생성·교체·완료와 autoloop receipt를 강화하고 visual QA의 browser ownership, bounded wait, blocked state, cleanup evidence를 명확히 합니다. v0.3.30 release material은 root-owned scientific evidence record, DOI/PDF lifecycle receipt, bounded route coverage, connection-pinned public-source reader, inert-content 및 secret-redaction 보장을 포함하는 LitResearch 강화판입니다. v0.3.29 release material은 exact-source `lit-handoff`와 `lit-scientific-visualization` skill, Claude-native command, exact-bare hook invocation, visible LITBURN banner, installed-payload integrity check, read-only scientific dependency diagnostic을 함께 포함합니다. v0.3.28 release material은 start-work 호출을 prompt 선두의 명시적 invocation으로 제한해 진단문이나 복사된 언급을 비활성 상태로 유지합니다. v0.3.27 release material은 success/failure receipt와 deterministic automation output을 갖춘 5-stage animated installer를 추가합니다. v0.3.26 release material은 adaptive objective-achievable planning, draft-plan review, orchestration readiness hardening을 추가합니다. v0.3.25 release material은 portable details, public-read, litgoal status JSON, evidence wording을 정렬합니다. v0.3.24 release material은 auxiliary skill inventory와 advisory probe를 정렬합니다. v0.3.23 release material은 bare `hyperplan`,
 `litresearch`, `lit research`, `init-deep`, explicit `$start-work` prompt-hook route에
 bundled skill body를 주입하면서, v0.3.19 adversarial planning
 skill, v0.3.18 read-only `lit-recap` session recap surface, v0.3.17 별도 worker 기반 native `/goal`
@@ -131,7 +131,7 @@ checkout을 먼저 해석해서 `sh: litclaude-ai: command not found`로 실패
 
 ```bash
 cd /tmp
-npx --yes litclaude-ai@0.3.32 install
+npx --yes litclaude-ai@0.3.33 install
 ```
 
 설치 상태를 확인합니다.
@@ -140,11 +140,26 @@ npx --yes litclaude-ai@0.3.32 install
 npx --yes litclaude-ai doctor
 ```
 
+interactive `install`, `update`, `doctor`에서는 LitClaude가 소유하는 cache의
+마지막으로 검증된 성공 버전이 오래되었더라도 조용한 update notice를 stderr에
+표시할 수 있습니다. 여러 parent가 동시에 실행되어도 atomic reservation으로
+24시간에 한 번만 새 조회를 예약합니다. offline, 실패, 중단된 조회도 attempted
+time을 남겨 24시간 동안 재시도를 제한하되 마지막 성공 version/check time은
+보존합니다. transition/recovery mutex와 attempt별 ownership generation이 stale
+takeover와 completion을 직렬화하므로 이전 worker가 새 reservation을 지우거나 새
+결과를 덮어쓸 수 없습니다. refresh는 official npm registry를 최대 3초 동안 조회하는 detached
+process이므로 management command는 기다리지 않습니다. canonical하지 않거나
+미래인 cache timestamp는 신뢰하지 않습니다. CI, JSON, dry-run, non-TTY에서는
+동작하지 않으며 `NO_UPDATE_NOTIFIER` 또는 `LITCLAUDE_NO_UPDATE_CHECK`로 끌 수
+있습니다. npm credential을 읽거나 update를 자동 설치하지 않습니다. notice가 제시한
+`npx --yes litclaude-ai@<version> install`을 실행한 뒤 Claude Code를 다시
+시작하세요.
+
 installer는 Claude Code의 `statusLine` command도 packaged LitClaude HUD로
 설정합니다. 색상을 제거한 예시는 다음처럼 시작합니다.
 
 ```text
-[🔥LITCLAUDE v0.3.32] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
+[🔥LITCLAUDE v0.3.33] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
 ```
 
 `↻` 표시는 rate-limit reset까지 남은 시간을 짧게 보여주는 countdown입니다.
@@ -158,6 +173,10 @@ picker 없이 색상을 지정하려면 설치 전에 `LITCLAUDE_HUD_ACCENT`를
 `cyan`, `blue`, `teal`, `green`, `lavender`, `rose`, `gold`, `orange`,
 `slate`, `gray` 중 하나로 설정하세요.
 
+option을 생략한 `litclaude update`는 기존 permission mode와 HUD accent를
+보존합니다. 명시적인 `--permission-mode` / `--yolo` 선택 또는
+`LITCLAUDE_HUD_ACCENT` 값은 저장된 선택을 계속 override합니다.
+
 설치 후에는 일반적인 `claude` 명령으로 Claude Code를 실행합니다.
 
 ```bash
@@ -284,6 +303,9 @@ litclaude litgoal native-worker --condition "<completion condition>" --mode bg -
 `native-worker`는 첫 prompt가 `/goal`로 시작하는 별도 print/background Claude
 Code worker를 시작합니다. 이미 열린 TUI를 arm하지 않고, tmux keystroke
 injection이나 private transcript metadata 변경도 사용하지 않습니다.
+User / Remote Control, SDK-owned session, 별도 `claude -p`, 이미 열린 TUI의
+capability boundary와 ledger 기반 ready-to-paste condition은 clean-room
+[native `/goal` surface matrix](./docs/native-goal-surface.md)에 정리되어 있습니다.
 `Workflow`가 노출되면 먼저 제안하고 사용자 opt-in 또는 이미 허용된 orchestration
 상태에서만 `Workflow` tool을 호출합니다. isolated edit lane이 model-facing
 worktree를 필요로 하면 `EnterWorktree`를 사용합니다. CLI surface만 가능한 새 격리

package/RELEASE_CHECKLIST.md

@@ -1,9 +1,14 @@
 # LitClaude Release Checklist
 
-Status: `litclaude-ai@0.3.32` is the current release candidate — a code-owned
-schema-3 start-work lifecycle with canonical bounded authority, single-use
-resume grants, PreToolUse enforcement, root/subagent lane identity, bounded Stop
-continuation receipts, and fail-closed release boundaries, plus guarded litgoal
+Status: `litclaude-ai@0.3.33` is the current release candidate — a quiet
+nonblocking npm update notice with strict cache, concurrency, timestamp,
+opt-out, and official-registry boundaries; optionless update preservation for
+the installed permission mode and HUD accent; and a shared canonical skill
+catalog enforced by source, install, installed-doctor, and Claude-details
+checks, with `DOCTOR_FAIL` on missing installed skills. It also carries the
+code-owned schema-3 start-work lifecycle with canonical bounded authority,
+single-use resume grants, PreToolUse enforcement, root/subagent lane identity,
+bounded Stop continuation receipts, and fail-closed release boundaries, plus guarded litgoal
 creation and replacement, durable idempotent autoloop completion, and explicit
 visual QA backend ownership, bounded waits, blocked states, and cleanup receipts,
 plus root-owned scientific evidence records, DOI/PDF lifecycle receipts, bounded route coverage,
@@ -28,9 +33,9 @@ side-effect-free, the launcher starts only a separate Claude Code
 print/background worker, and the release preserves the Korean polishing
 command, strict multi-agent review pipeline, fidelity guardrails, package
 hygiene checks, native route gates, and safe start-work handoff behavior.
-`package.json` is aligned to `0.3.32`,
-`plugins/litclaude/.claude-plugin/plugin.json` is aligned to `0.3.32`, and the
-plugin-local MCP server reports `0.3.32`.
+`package.json` is aligned to `0.3.33`,
+`plugins/litclaude/.claude-plugin/plugin.json` is aligned to `0.3.33`, and the
+plugin-local MCP server reports `0.3.33`.
 
 This release carries the v0.2.2 Dynamic workflow hardening surfaces:
 `/dynamic-workflow`, `workflow-check --json`, native `/goal` fallback guidance,
@@ -57,6 +62,10 @@ behavior.
 
 - `npm test`
 - `npm run validate:plugin`
+- `npm run doctor`
+- `npm run check:version`
+- `npm run scan:legacy-tokens`
+- `npm run pack:payload-guard`
 - `npm run qa:tmux`
 - `npm run qa:portable`
 - `npm run pack:dry-run`
@@ -74,6 +83,21 @@ Use this track when testing from the current checkout:
 
 No npm publication is required for this track.
 
+## v0.3.33 Update Notice and Canonical Catalog Gates
+
+Before requesting publication approval, confirm interactive `install`, `update`,
+and `doctor` can show only the quiet stderr update notice while CI, JSON,
+dry-run, non-TTY, `NO_UPDATE_NOTIFIER`, and `LITCLAUDE_NO_UPDATE_CHECK` remain
+authoritative opt-outs. Confirm the cache accepts only stable official-package
+metadata, preserves the last trusted result across failed refreshes, throttles
+attempts for 24 hours, and fences stale owners from newer reservations.
+
+Confirm source doctor, installation verification, installed doctor, and
+`claude plugin details` consume the same exact canonical skill catalog. A
+packed isolated install must emit `SKILL_CATALOG_PASS` and `DOCTOR_PASS`; after
+one canonical `SKILL.md` is moved aside, doctor must exit nonzero with
+`DOCTOR_FAIL` and must not print `DOCTOR_PASS`.
+
 ## v0.3.32 Bounded-Authority Start-Work Gates
 
 Before requesting publication approval, confirm schema-3 state remains
@@ -138,9 +162,9 @@ checkout and from an isolated install of the packed tarball:
 Before requesting publication approval, confirm these artifacts from the current
 checkout:
 
-- `package.json` version is `0.3.32`.
-- `plugins/litclaude/.claude-plugin/plugin.json` version is `0.3.32`.
-- `plugins/litclaude/bin/litclaude-mcp.js` reports server version `0.3.32`.
+- `package.json` version is `0.3.33`.
+- `plugins/litclaude/.claude-plugin/plugin.json` version is `0.3.33`.
+- `plugins/litclaude/bin/litclaude-mcp.js` reports server version `0.3.33`.
 - Prompt-hook tests cover bundled `SKILL.md` body injection for bare `hyperplan`, `litresearch`, `lit research`, `init-deep`, and explicit leading `$start-work`; diagnostic/copy mentions stay inert while leading natural-language `lit start work` stays BLOCKED.
 - `lit search` and `lit query` route to `/litclaude:litresearch` without activating on slash mentions, code spans, or non-lit prompts.
 - Litresearch web lanes require public API/feed preference, validator-first checks, route traces, prompt-injection quarantine, and honest auth/paywall/private-data stop reasons.

package/bin/litclaude-ai.js

@@ -15,6 +15,10 @@ import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
+import {
+  canonicalSkillFiles,
+  canonicalSkillIds,
+} from "../plugins/litclaude/lib/canonical-skill-catalog.mjs";
 import { HUD_ACCENT_THEMES, normalizeHudAccent, themeForAccent } from "../plugins/litclaude/lib/hud-accent-palette.mjs";
 import { readPublicSource } from "../plugins/litclaude/lib/public-source-reader/reader.mjs";
 import { verifyBundledSkillsIntegrity } from "../plugins/litclaude/lib/bundled-skills-integrity.mjs";
@@ -22,6 +26,7 @@ import { runStartWorkContinuationCli } from "../plugins/litclaude/lib/start-work
 import { runStartWorkCli } from "../plugins/litclaude/lib/start-work-cli.mjs";
 import { runLitgoalCli } from "../plugins/litclaude/lib/litgoal/cli.mjs";
 import { runWorkflowCheckCli } from "../plugins/litclaude/lib/workflow-check.mjs";
+import { runUpdateNotifier } from "./update-notifier.mjs";
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const packageJson = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
@@ -67,6 +72,7 @@ const parseArgs = (argv) => {
 
 const litHome = () => resolve(process.env.LITCLAUDE_HOME ?? join(homedir(), ".litclaude"));
 const claudeHome = () => resolve(process.env.CLAUDE_CONFIG_DIR ?? process.env.CLAUDE_HOME ?? join(homedir(), ".claude"));
+const updateNotifierCachePath = (home = litHome()) => join(home, "update-notifier", "latest.json");
 const versionRoot = (home = litHome()) => join(home, "litclaude-ai", version);
 const currentRoot = (home = litHome()) => join(home, "current");
 const pluginPathForRoot = (installRoot) => join(installRoot, "plugins", "litclaude");
@@ -96,8 +102,9 @@ const parsePermissionMode = (value) => {
   return value;
 };
 
-const parseInstallOptions = (rest) => {
-  let permissionMode = parsePermissionMode(process.env.LITCLAUDE_PERMISSION_MODE || "safe");
+const parseInstallOptions = (rest, existingPermissionMode = "safe") => {
+  const preservedMode = permissionModes.has(existingPermissionMode) ? existingPermissionMode : "safe";
+  let permissionMode = parsePermissionMode(process.env.LITCLAUDE_PERMISSION_MODE || preservedMode);
   let permissionExplicit = Boolean(process.env.LITCLAUDE_PERMISSION_MODE);
 
   for (let index = 0; index < rest.length; index += 1) {
@@ -308,12 +315,13 @@ const shouldPromptHudAccent = () => {
   return Boolean(process.stdin.isTTY && process.stdout.isTTY && !process.env.CI);
 };
 
-const chooseHudAccent = async () => {
+const chooseHudAccent = async (existingAccent = "cyan") => {
+  const preservedAccent = normalizeHudAccent(existingAccent);
   const envAccent = process.env.LITCLAUDE_HUD_ACCENT;
   if (envAccent && process.env.LITCLAUDE_HUD_ACCENT_PROMPT !== "1") {
     return normalizeHudAccent(envAccent);
   }
-  if (!shouldPromptHudAccent()) return normalizeHudAccent(envAccent);
+  if (!shouldPromptHudAccent()) return envAccent ? normalizeHudAccent(envAccent) : preservedAccent;
 
   process.stdout.write("Choose LitClaude HUD brand color:\n");
   for (const [index, theme] of hudAccentThemes.entries()) {
@@ -322,10 +330,10 @@ const chooseHudAccent = async () => {
 
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   try {
-    const answer = await rl.question("Color 1-10 or name [cyan]: ");
+    const answer = await rl.question(`Color 1-10 or name [${preservedAccent}]: `);
     const trimmed = answer.trim().toLowerCase();
     const byIndex = hudAccentThemes[Number.parseInt(trimmed, 10) - 1]?.name;
-    const selected = byIndex ?? normalizeHudAccent(trimmed);
+    const selected = byIndex ?? (trimmed ? normalizeHudAccent(trimmed) : preservedAccent);
     if (trimmed && selected === "cyan" && trimmed !== "cyan" && byIndex === undefined) {
       process.stdout.write("HUD_COLOR_WARNING: unknown color; using cyan\n");
     }
@@ -563,6 +571,8 @@ const commandExists = (command) => {
 };
 
 const escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+const exactInventoryToken = (value) =>
+  new RegExp(`(?<![A-Za-z0-9_-])${escapeRegex(value)}(?![A-Za-z0-9_-])`, "u");
 
 const assertCurrentPluginDetails = (detailsOutput) => {
   const missing = [];
@@ -586,11 +596,11 @@ const assertCurrentPluginDetails = (detailsOutput) => {
     missing.push("expected nonzero Agents inventory with prometheus-planner");
   }
 
-  if (!/\blit-loop\b/u.test(skillsInventory) || !/\blit-plan\b/u.test(skillsInventory)) {
-    missing.push("expected lit-loop and lit-plan skills");
-  }
-  if (!/\blit-handoff\b/u.test(skillsInventory) || !/\blit-scientific-visualization\b/u.test(skillsInventory)) {
-    missing.push("expected lit-handoff and lit-scientific-visualization skills");
+  const missingSkills = canonicalSkillIds.filter(
+    (skillId) => !exactInventoryToken(skillId).test(skillsInventory),
+  );
+  if (missingSkills.length > 0) {
+    missing.push(`expected canonical skills: ${missingSkills.join(", ")}`);
   }
 
   if (missing.length > 0) {
@@ -642,13 +652,11 @@ const verifyInstalledPayload = ({ home, litClaudeHome, targetPlugin }) => {
     "bin/litclaude-hook.js",
     "lib/start-work-lifecycle.mjs",
     "lib/start-work-cli.mjs",
-    "skills/start-work/SKILL.md",
+    ...canonicalSkillFiles,
     "commands/start-work.md",
     "bin/litclaude-scientific-visualization-doctor.js",
-    "skills/lit-handoff/SKILL.md",
     "commands/lit-handoff.md",
     "vendor/022_handoff/SKILL.md",
-    "skills/lit-scientific-visualization/SKILL.md",
     "commands/lit-scientific-visualization.md",
     "vendor/045_scientific-visualization/SKILL.md",
     "vendor/045_scientific-visualization/scripts/style_presets.py",
@@ -670,9 +678,14 @@ const verifyInstalledPayload = ({ home, litClaudeHome, targetPlugin }) => {
 };
 
 const install = async ({ dryRun, rest }) => {
-  const { permissionMode, permissionExplicit } = parseInstallOptions(rest);
   const home = claudeHome();
   const litClaudeHome = litHome();
+  const existingLitClaude = readClaudeSettings(home)[litClaudeSettingsKey] ?? {};
+  const { permissionMode, permissionExplicit } = parseInstallOptions(rest, existingLitClaude.permissionMode);
+  const existingHudAccent = normalizeHudAccent(existingLitClaude.hudAccent);
+  const requestedHudAccent = process.env.LITCLAUDE_HUD_ACCENT
+    ? normalizeHudAccent(process.env.LITCLAUDE_HUD_ACCENT)
+    : existingHudAccent;
   const targetPlugin = claudePluginRoot(home);
   const sourcePlugin = sourcePluginPath();
   const targetMarketplace = marketplaceRoot(litClaudeHome);
@@ -683,8 +696,11 @@ const install = async ({ dryRun, rest }) => {
     process.stdout.write(`Would copy: ${sourcePlugin} -> ${targetPlugin}\n`);
     process.stdout.write(`Would create local marketplace: ${targetMarketplace}\n`);
     process.stdout.write(`Would register Claude plugin: ${pluginKey}\n`);
-    process.stdout.write(`Would set Claude statusLine HUD: ${hudCommandForPlugin(targetPlugin)}\n`);
-    process.stdout.write(`Would record permission preference: ${permissionMode}${permissionExplicit ? " (explicit)" : " (default)"}\n`);
+    process.stdout.write(`Would set Claude statusLine HUD: ${hudCommandForPlugin(targetPlugin, requestedHudAccent)}\n`);
+    const permissionSource = permissionExplicit
+      ? "explicit"
+      : permissionModes.has(existingLitClaude.permissionMode) ? "preserved" : "default";
+    process.stdout.write(`Would record permission preference: ${permissionMode} (${permissionSource})\n`);
     process.stdout.write(`Permission profile: ${permissionProfile(permissionMode).description}\n`);
     process.stdout.write("Launch with: claude\n");
     return;
@@ -694,7 +710,7 @@ const install = async ({ dryRun, rest }) => {
     fail(`Packaged LitClaude plugin payload is missing: ${sourcePlugin}`);
   }
 
-  const hudAccent = await chooseHudAccent();
+  const hudAccent = await chooseHudAccent(existingHudAccent);
   progress.prepare({ claudeTarget: home, litTarget: litClaudeHome });
   await progress.run(
     {
@@ -801,17 +817,12 @@ const doctor = ({ dryRun }) => {
     "bin/litclaude-mcp.js",
     "lib/start-work-lifecycle.mjs",
     "lib/start-work-cli.mjs",
-    "skills/start-work/SKILL.md",
     "commands/start-work.md",
-    "skills/lit-loop/SKILL.md",
-    "skills/lit-plan/SKILL.md",
-    "skills/lit-handoff/SKILL.md",
     "commands/lit-handoff.md",
     "vendor/022_handoff/SKILL.md",
     "vendor/022_handoff/evals/evals.json",
     "vendor/022_handoff/examples/HANDOFF-example-generic-auth-refactor.md",
     "vendor/022_handoff/templates/HANDOFF.md",
-    "skills/lit-scientific-visualization/SKILL.md",
     "commands/lit-scientific-visualization.md",
     "bin/litclaude-scientific-visualization-doctor.js",
     "vendor/045_scientific-visualization/SKILL.md",
@@ -828,6 +839,13 @@ const doctor = ({ dryRun }) => {
     const path = join(pluginPath, file);
     if (!existsSync(path)) fail(`LitClaude install is missing ${file}. Run \`litclaude install\` again.`);
   }
+  for (const file of canonicalSkillFiles) {
+    const path = join(pluginPath, file);
+    if (!existsSync(path)) {
+      fail(`DOCTOR_FAIL: LitClaude install is missing ${file}. Run \`litclaude install\` again.`);
+    }
+  }
+  process.stdout.write("SKILL_CATALOG_PASS\n");
 
   printLspDiagnostics(pluginPath, registry);
 
@@ -931,13 +949,15 @@ const runClaude = ({ dryRun, rest }) => {
 const uninstall = ({ dryRun }) => {
   const home = litHome();
   const pluginCacheRoot = join(claudeHome(), "plugins", "cache", "litclaude-ai");
+  const updateNotifierRoot = dirname(updateNotifierCachePath(home));
   if (dryRun) {
-    process.stdout.write(`DRY_RUN: remove ${join(home, "litclaude-ai")}, ${currentRoot(home)}, ${marketplaceRoot(home)}, ${pluginCacheRoot}, ${pluginKey}, and its marketplace/settings entries\n`);
+    process.stdout.write(`DRY_RUN: remove ${join(home, "litclaude-ai")}, ${currentRoot(home)}, ${marketplaceRoot(home)}, ${updateNotifierRoot}, ${pluginCacheRoot}, ${pluginKey}, and its marketplace/settings entries\n`);
     return;
   }
   rmSync(currentRoot(home), { recursive: true, force: true });
   rmSync(join(home, "litclaude-ai"), { recursive: true, force: true });
   rmSync(marketplaceRoot(home), { recursive: true, force: true });
+  rmSync(updateNotifierRoot, { recursive: true, force: true });
   unregisterClaudePlugin();
   unregisterMarketplace();
   uninstallHudStatusLine();
@@ -993,6 +1013,14 @@ const main = async () => {
       printUsage();
       fail(`Unknown command: ${command}`, 64);
   }
+
+  if (command === "install" || command === "update" || command === "doctor") {
+    runUpdateNotifier({
+      ...parsed,
+      currentVersion: version,
+      cachePath: updateNotifierCachePath(),
+    });
+  }
 };
 
 main().catch((error) => fail(error.message));

package/bin/update-notifier-refresh.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+import { refreshUpdateCache } from "./update-notifier.mjs";
+
+const cachePath = process.argv[2];
+const generation = process.argv[3];
+if (cachePath && generation) await refreshUpdateCache(cachePath, { generation }).catch(() => {});

package/bin/update-notifier.mjs

@@ -0,0 +1,504 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { get as httpsGet } from "node:https";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const CACHE_TTL_MS = 24 * 60 * 60 * 1_000;
+export const MAX_RESPONSE_BYTES = 64 * 1_024;
+export const REGISTRY_URL = "https://registry.npmjs.org/litclaude-ai/latest";
+const PACKAGE_NAME = "litclaude-ai";
+const REQUEST_TIMEOUT_MS = 3_000;
+const RESERVATION_STALE_MS = 30_000;
+const RESERVATION_CLOCK_SKEW_MS = 5_000;
+const stableSemverPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/u;
+const generationPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+
+const parseStableSemver = (value) => {
+  const match = typeof value === "string" ? value.match(stableSemverPattern) : null;
+  if (!match) throw new Error("version is not strict stable semver");
+  return match.slice(1).map((part) => BigInt(part));
+};
+
+export const compareStableSemver = (left, right) => {
+  const leftParts = parseStableSemver(left);
+  const rightParts = parseStableSemver(right);
+  for (let index = 0; index < leftParts.length; index += 1) {
+    if (leftParts[index] > rightParts[index]) return 1;
+    if (leftParts[index] < rightParts[index]) return -1;
+  }
+  return 0;
+};
+
+const contentTypeIsJson = (value) =>
+  typeof value === "string" && /^application\/json(?:\s*;\s*charset=(?:utf-8|utf8))?$/iu.test(value.trim());
+
+export const parseRegistryResponse = ({ statusCode, headers = {}, body }) => {
+  if (statusCode !== 200) throw new Error("registry response status is not 200");
+  if (!contentTypeIsJson(headers["content-type"])) throw new Error("registry response is not application/json");
+
+  const contentLength = headers["content-length"];
+  if (contentLength !== undefined) {
+    if (!/^(0|[1-9]\d*)$/u.test(String(contentLength))) throw new Error("registry content-length is invalid");
+    if (BigInt(contentLength) > BigInt(MAX_RESPONSE_BYTES)) throw new Error("registry response is too large");
+  }
+
+  const bytes = Buffer.isBuffer(body) ? body : Buffer.from(body ?? "");
+  if (bytes.length > MAX_RESPONSE_BYTES) throw new Error("registry response is too large");
+
+  let parsed;
+  try {
+    parsed = JSON.parse(bytes.toString("utf8"));
+  } catch {
+    throw new Error("registry response JSON is invalid");
+  }
+  if (!parsed || Array.isArray(parsed) || typeof parsed !== "object") throw new Error("registry response is not an object");
+  if (parsed.name !== PACKAGE_NAME) throw new Error("registry package name does not match");
+  parseStableSemver(parsed.version);
+  return { packageName: PACKAGE_NAME, latestVersion: parsed.version };
+};
+
+const canonicalTimestamp = (value, now) => {
+  if (typeof value !== "string") return false;
+  const timestamp = Date.parse(value);
+  return Number.isFinite(timestamp) && timestamp <= now && new Date(timestamp).toISOString() === value;
+};
+
+const validCacheRecord = (value, now) => {
+  if (!value || Array.isArray(value) || typeof value !== "object") return false;
+  if (value.schema !== 3 || value.packageName !== PACKAGE_NAME) return false;
+  if (Object.keys(value).sort().join(",") !== "attemptedAt,checkedAt,generation,latestVersion,packageName,schema") return false;
+  if (typeof value.generation !== "string" || !generationPattern.test(value.generation)) return false;
+  if (!canonicalTimestamp(value.attemptedAt, now)) return false;
+  if (value.latestVersion === null || value.checkedAt === null) {
+    return value.latestVersion === null && value.checkedAt === null;
+  }
+  try {
+    parseStableSemver(value.latestVersion);
+  } catch {
+    return false;
+  }
+  return canonicalTimestamp(value.checkedAt, now);
+};
+
+export const readUpdateCache = (cachePath, { now = Date.now() } = {}) => {
+  try {
+    const parsed = JSON.parse(readFileSync(cachePath, "utf8"));
+    return validCacheRecord(parsed, now) ? parsed : null;
+  } catch {
+    return null;
+  }
+};
+
+export const writeUpdateCache = (
+  cachePath,
+  { packageName, latestVersion, checkedAt, attemptedAt, generation },
+  { now = Date.now() } = {},
+) => {
+  const record = { schema: 3, packageName, latestVersion, checkedAt, attemptedAt, generation };
+  if (!validCacheRecord(record, now)) throw new Error("refusing to write invalid update cache");
+  const directory = dirname(cachePath);
+  mkdirSync(directory, { recursive: true });
+  const temporaryPath = `${cachePath}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temporaryPath, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600 });
+    renameSync(temporaryPath, cachePath);
+  } finally {
+    rmSync(temporaryPath, { force: true });
+  }
+};
+
+export const fetchLatestVersion = ({ request = httpsGet } = {}) =>
+  new Promise((resolve, reject) => {
+    let settled = false;
+    let deadline;
+    const settle = (operation, value) => {
+      if (settled) return;
+      settled = true;
+      if (deadline) clearTimeout(deadline);
+      operation(value);
+    };
+    const req = request(
+      REGISTRY_URL,
+      {
+        method: "GET",
+        headers: {
+          accept: "application/json",
+          "user-agent": "litclaude-ai-update-notifier",
+        },
+      },
+      (response) => {
+        const chunks = [];
+        let size = 0;
+        response.on("data", (chunk) => {
+          const bytes = Buffer.from(chunk);
+          size += bytes.length;
+          if (size > MAX_RESPONSE_BYTES) {
+            response.destroy(new Error("registry response is too large"));
+            settle(reject, new Error("registry response is too large"));
+            return;
+          }
+          chunks.push(bytes);
+        });
+        response.once("error", (error) => settle(reject, error));
+        response.once("end", () => {
+          try {
+            settle(resolve, parseRegistryResponse({
+              statusCode: response.statusCode,
+              headers: response.headers,
+              body: Buffer.concat(chunks),
+            }));
+          } catch (error) {
+            settle(reject, error);
+          }
+        });
+      },
+    );
+    req.once("error", (error) => settle(reject, error));
+    req.setTimeout(REQUEST_TIMEOUT_MS, () => req.destroy(new Error("registry request timed out")));
+    deadline = setTimeout(() => req.destroy(new Error("registry request deadline exceeded")), REQUEST_TIMEOUT_MS);
+    deadline.unref();
+  });
+
+export const refreshUpdateCache = async (
+  cachePath,
+  { fetch = fetchLatestVersion, now = () => Date.now(), generation } = {},
+) => {
+  const result = await fetch();
+  let transition;
+  for (let attempt = 0; attempt < 50 && !transition; attempt += 1) {
+    const transitionAt = now();
+    transition = acquireTransition(cachePath, transitionAt);
+    if (!transition) await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+  if (!transition) return false;
+  try {
+    const completedAt = now();
+    const previous = readUpdateCache(cachePath, { now: completedAt });
+    const expectedGeneration = generation ?? previous?.generation;
+    if (!previous || previous.generation !== expectedGeneration) return false;
+    if (!continuesToOwnLock(transition)) return false;
+    writeUpdateCache(
+      cachePath,
+      {
+        ...result,
+        checkedAt: new Date(completedAt).toISOString(),
+        attemptedAt: previous.attemptedAt,
+        generation: previous.generation,
+      },
+      { now: completedAt },
+    );
+    return true;
+  } finally {
+    releaseOwnedLock(transition);
+  }
+};
+
+const hasOptOut = (env, name) => Object.hasOwn(env, name);
+
+export const shouldRunUpdateNotifier = ({ command, rest, dryRun, env, stdin, stdout, stderr }) => {
+  if (!new Set(["install", "update", "doctor"]).has(command)) return false;
+  if (dryRun || rest.some((arg) => arg === "--json" || arg.startsWith("--json="))) return false;
+  if (!stdin.isTTY || !stdout.isTTY || !stderr.isTTY) return false;
+  if (hasOptOut(env, "CI") || hasOptOut(env, "NO_UPDATE_NOTIFIER") || hasOptOut(env, "LITCLAUDE_NO_UPDATE_CHECK")) return false;
+  return true;
+};
+
+export const formatUpdateNotice = (currentVersion, latestVersion) =>
+  `\nLitClaude update available: ${currentVersion} → ${latestVersion}\n` +
+  `Run: npx --yes litclaude-ai@${latestVersion} install\n` +
+  "Then restart Claude Code.\n\n";
+
+const detachedRefreshEnvKeys = [
+  "PATH",
+  "HOME",
+  "USERPROFILE",
+  "HOMEDRIVE",
+  "HOMEPATH",
+  "TMPDIR",
+  "TMP",
+  "TEMP",
+  "SystemRoot",
+  "WINDIR",
+  "ComSpec",
+  "PATHEXT",
+  "SSL_CERT_FILE",
+  "SSL_CERT_DIR",
+  "NODE_EXTRA_CA_CERTS",
+  "HTTP_PROXY",
+  "HTTPS_PROXY",
+  "ALL_PROXY",
+  "NO_PROXY",
+  "http_proxy",
+  "https_proxy",
+  "all_proxy",
+  "no_proxy",
+  "LANG",
+  "LC_ALL",
+  "LC_CTYPE",
+  "TZ",
+];
+
+const proxyUrlEnvKeys = new Set([
+  "HTTP_PROXY",
+  "HTTPS_PROXY",
+  "ALL_PROXY",
+  "http_proxy",
+  "https_proxy",
+  "all_proxy",
+]);
+
+const detachedRefreshEnvValueIsSafe = (name, value) => {
+  if (!proxyUrlEnvKeys.has(name)) return true;
+  try {
+    const proxy = new URL(value.includes("://") ? value : `http://${value}`);
+    return proxy.username === "" && proxy.password === "";
+  } catch {
+    return false;
+  }
+};
+
+const detachedRefreshEnv = (env) => Object.fromEntries(
+  detachedRefreshEnvKeys
+    .filter((name) => typeof env[name] === "string" && detachedRefreshEnvValueIsSafe(name, env[name]))
+    .map((name) => [name, env[name]]),
+);
+
+export const spawnDetachedRefresh = (
+  cachePath,
+  generation,
+  continuesToOwnTransition = () => true,
+  spawnProcess = spawn,
+  env = process.env,
+) => {
+  if (!continuesToOwnTransition()) return false;
+  const child = spawnProcess(
+    process.execPath,
+    [fileURLToPath(new URL("./update-notifier-refresh.mjs", import.meta.url)), cachePath, generation],
+    { detached: true, stdio: "ignore", windowsHide: true, env: detachedRefreshEnv(env) },
+  );
+  child.once("error", () => {});
+  child.unref();
+  return true;
+};
+
+const reservationLockPath = (cachePath) => `${cachePath}.reservation.lock`;
+const transitionLockPath = (cachePath) => `${cachePath}.transition.lock`;
+const recoveryLockPath = (cachePath) => `${cachePath}.transition-recovery.lock`;
+const ownerPath = (lockPath) => join(lockPath, "owner.json");
+
+const readLockOwner = (lockPath) => {
+  try {
+    const owner = JSON.parse(readFileSync(ownerPath(lockPath), "utf8"));
+    if (!owner || Object.keys(owner).sort().join(",") !== "acquiredAt,generation,pid,schema") return null;
+    if (owner.schema !== 2 || !generationPattern.test(owner.generation)) return null;
+    if (!Number.isSafeInteger(owner.pid) || owner.pid <= 0) return null;
+    const acquiredAt = Date.parse(owner.acquiredAt);
+    if (!Number.isFinite(acquiredAt) || new Date(acquiredAt).toISOString() !== owner.acquiredAt) return null;
+    return owner;
+  } catch {
+    return null;
+  }
+};
+
+const processIsLive = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code !== "ESRCH";
+  }
+};
+
+const createOwnedLock = (lockPath, now, generation = randomUUID()) => {
+  mkdirSync(dirname(lockPath), { recursive: true });
+  try {
+    mkdirSync(lockPath);
+  } catch (error) {
+    if (error?.code === "EEXIST") return null;
+    throw error;
+  }
+  const lease = { path: lockPath, generation };
+  try {
+    writeFileSync(ownerPath(lockPath), `${JSON.stringify({
+      schema: 2,
+      generation,
+      pid: process.pid,
+      acquiredAt: new Date(now).toISOString(),
+    })}\n`, { encoding: "utf8", mode: 0o600 });
+    return lease;
+  } catch (error) {
+    releaseOwnedLock(lease);
+    throw error;
+  }
+};
+
+const inspectOwnedLock = (lockPath, now) => {
+  try {
+    const stats = statSync(lockPath);
+    const owner = readLockOwner(lockPath);
+    const age = now - stats.mtimeMs;
+    const ownerLive = owner ? processIsLive(owner.pid) : null;
+    const stale = owner
+      ? ownerLive === false && (age < -RESERVATION_CLOCK_SKEW_MS || age >= RESERVATION_STALE_MS)
+      : age >= RESERVATION_STALE_MS;
+    return {
+      exists: true,
+      generation: owner?.generation ?? null,
+      inode: String(stats.ino),
+      mtimeMs: stats.mtimeMs,
+      stale,
+    };
+  } catch {
+    return { exists: false, generation: null, inode: null, mtimeMs: null, stale: false };
+  }
+};
+
+const sameLockGeneration = (left, right) =>
+  left?.exists === true && right?.exists === true &&
+  left.generation === right.generation && left.inode === right.inode && left.mtimeMs === right.mtimeMs;
+
+const continuesToOwnLock = (lease) => {
+  if (!lease) return false;
+  const owner = readLockOwner(lease.path);
+  return owner?.generation === lease.generation && owner.pid === process.pid;
+};
+
+const recoverObservedLock = (lockPath, observed, now) => {
+  if (!observed?.stale) return false;
+  const current = inspectOwnedLock(lockPath, now);
+  if (!current.stale || !sameLockGeneration(observed, current)) return false;
+  rmSync(lockPath, { recursive: true, force: true });
+  return true;
+};
+
+const releaseOwnedLock = (lease) => {
+  if (!lease) return false;
+  if (!continuesToOwnLock(lease)) return false;
+  rmSync(lease.path, { recursive: true, force: true });
+  return true;
+};
+
+export const inspectUpdateReservation = (cachePath, now = Date.now()) =>
+  inspectOwnedLock(reservationLockPath(cachePath), now);
+
+export const recoverObservedReservation = (cachePath, observed, now = Date.now()) =>
+  recoverObservedLock(reservationLockPath(cachePath), observed, now);
+
+const acquireRecovery = (cachePath, now) => {
+  const path = recoveryLockPath(cachePath);
+  let lease = createOwnedLock(path, now);
+  if (lease) return lease;
+  const observed = inspectOwnedLock(path, now);
+  if (!recoverObservedLock(path, observed, now)) return null;
+  lease = createOwnedLock(path, now);
+  return lease;
+};
+
+const acquireTransition = (cachePath, now) => {
+  const path = transitionLockPath(cachePath);
+  const observedRecovery = inspectOwnedLock(recoveryLockPath(cachePath), now);
+  if (observedRecovery.exists) {
+    if (!observedRecovery.stale) return null;
+    if (!recoverObservedLock(recoveryLockPath(cachePath), observedRecovery, now)) return null;
+  }
+  let lease = createOwnedLock(path, now);
+  if (lease) return lease;
+
+  const observed = inspectOwnedLock(path, now);
+  if (!observed.stale) return null;
+  const recovery = acquireRecovery(cachePath, now);
+  if (!recovery) return null;
+  try {
+    if (!recoverObservedLock(path, observed, now)) return null;
+    lease = createOwnedLock(path, now);
+    return lease;
+  } finally {
+    releaseOwnedLock(recovery);
+  }
+};
+
+const scheduleRefresh = ({ cachePath, now, spawnRefresh }) => {
+  const transition = acquireTransition(cachePath, now);
+  if (!transition) return "coalesced";
+  try {
+    const current = readUpdateCache(cachePath, { now });
+    if (current) {
+      const attemptAge = now - Date.parse(current.attemptedAt);
+      if (attemptAge >= 0 && attemptAge < CACHE_TTL_MS) return "throttled";
+    }
+
+    const observedReservation = inspectUpdateReservation(cachePath, now);
+    if (observedReservation.exists) {
+      if (!observedReservation.stale) return "coalesced";
+      if (!recoverObservedReservation(cachePath, observedReservation, now)) return "coalesced";
+    }
+
+    const generation = randomUUID();
+    const reservation = createOwnedLock(reservationLockPath(cachePath), now, generation);
+    if (!reservation) return "coalesced";
+    try {
+      if (!continuesToOwnLock(transition)) return "coalesced";
+      writeUpdateCache(
+        cachePath,
+        {
+          packageName: PACKAGE_NAME,
+          latestVersion: current?.latestVersion ?? null,
+          checkedAt: current?.checkedAt ?? null,
+          attemptedAt: new Date(now).toISOString(),
+          generation,
+        },
+        { now },
+      );
+      if (!continuesToOwnLock(transition)) return "coalesced";
+      const spawned = spawnRefresh(cachePath, generation, () => continuesToOwnLock(transition));
+      if (spawned === false) return "coalesced";
+      return "scheduled";
+    } catch {
+      return "spawn-error";
+    } finally {
+      releaseOwnedLock(reservation);
+    }
+  } finally {
+    releaseOwnedLock(transition);
+  }
+};
+
+export const runUpdateNotifier = ({
+  command,
+  rest,
+  dryRun,
+  currentVersion,
+  cachePath,
+  env = process.env,
+  stdin = process.stdin,
+  stdout = process.stdout,
+  stderr = process.stderr,
+  now = Date.now(),
+  spawnRefresh = spawnDetachedRefresh,
+}) => {
+  try {
+    if (!shouldRunUpdateNotifier({ command, rest, dryRun, env, stdin, stdout, stderr })) return "gated";
+    const cached = readUpdateCache(cachePath, { now });
+    const noticeAvailable = cached?.latestVersion
+      ? compareStableSemver(cached.latestVersion, currentVersion) > 0
+      : false;
+    const attemptAge = cached ? now - Date.parse(cached.attemptedAt) : Number.POSITIVE_INFINITY;
+    const refreshDue = !cached || attemptAge < 0 || attemptAge >= CACHE_TTL_MS;
+    const refreshStatus = refreshDue
+      ? scheduleRefresh({ cachePath, now, spawnRefresh })
+      : "throttled";
+
+    if (noticeAvailable) {
+      stderr.write(formatUpdateNotice(currentVersion, cached.latestVersion));
+    }
+    if (noticeAvailable && refreshStatus === "scheduled") return "noticed-refreshing";
+    if (noticeAvailable) return "noticed";
+    if (refreshStatus === "scheduled") return "refreshing";
+    if (refreshStatus === "spawn-error") return "silent-error";
+    return refreshStatus === "coalesced" ? "coalesced" : "current";
+  } catch {
+    return "silent-error";
+  }
+};

package/docs/native-goal-surface.md

@@ -0,0 +1,41 @@
+# Native `/goal` Surface Matrix
+
+This matrix separates who owns a Claude Code session from what the LitClaude
+plugin can do. It is capability guidance only: there is no runtime bridge from
+LitClaude into another session.
+
+## Prerequisites
+
+- Use Claude Code >=2.1.139; older clients do not provide the native `/goal`
+  surface described here.
+- Complete workspace trust before relying on project-local plugin behavior.
+- Confirm hooks are enabled and that user, project, organization, and managed policy
+  do not block the session or command surface. Hook context is still not
+  slash-command dispatch.
+- For an SDK-owned session, inspect the system/init `slash_commands` list and
+  submit `/goal` only when that initialized session advertises the command. The
+  SDK client must own the target session and its input channel.
+
+| Surface owner | Can submit `/goal`? | Which session changes? | LitClaude boundary |
+| --- | --- | --- | --- |
+| User / Remote Control | Yes, by submitting `/goal <condition>` through that user-controlled input surface. | The session receiving that input. | LitClaude may provide a condition, but does not submit it for the user. |
+| SDK-owned session | Yes, when the SDK client submits `/goal <condition>` to the session it created and owns. | That SDK-owned session only. | The SDK client is the submitter; the installed plugin is not a cross-session controller. |
+| Separate `claude -p` session | Yes, by starting a separate print session whose prompt begins with `/goal`. | The new print session, not an arbitrary already-open TUI. | `litclaude litgoal native-worker` can build or launch this separate process explicitly. |
+| LitClaude plugin in an arbitrary already-open TUI | No supported binding path. | None. | A skill, command body, MCP server, or hook cannot claim that it armed the open TUI. |
+
+## Ready to paste
+
+After creating and reviewing the durable criteria, the user or owner of the
+target session can paste this condition there:
+
+```text
+/goal Finish only when every criterion in .litclaude/litgoal/goals.json is pass, required evidence is recorded in .litclaude/litgoal/ledger.jsonl, targeted verification passes, and .litclaude/litgoal contains no unresolved review blocker.
+```
+
+Adapt filenames only when the local ledger reports a different authoritative
+path. The condition does not make the ledger self-validating; recorded evidence
+still needs the normal LitClaude review gates.
+
+This documentation does not add a fake command, MCP method, or hook dispatch.
+It also does not auto-install anything, mutate a transcript, inject keystrokes,
+or claim success based on prompt context alone.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "litclaude-ai",
-  "version": "0.3.32",
+  "version": "0.3.33",
   "description": "Claude Code-native workflow distribution.",
   "type": "module",
   "bin": {
@@ -13,6 +13,7 @@
     "docs/hooks.md",
     "docs/lsp.md",
     "docs/migration.md",
+    "docs/native-goal-surface.md",
     "docs/workflow-compatibility-audit.md",
     "plugins",
     "scripts",

package/plugins/litclaude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "litclaude",
   "description": "Claude Code-native workflow plugin with a bounded-authority start-work lifecycle.",
-  "version": "0.3.32",
+  "version": "0.3.33",
   "author": {
     "name": "LitClaude contributors"
   },

package/plugins/litclaude/bin/litclaude-mcp.js

@@ -3,7 +3,7 @@
 import { readPublicSource } from "../lib/public-source-reader/reader.mjs";
 
 const protocolVersion = "2024-11-05";
-const serverVersion = "0.3.32";
+const serverVersion = "0.3.33";
 
 const publicSourceReadTool = {
   name: "public_source_read",

package/plugins/litclaude/lib/canonical-skill-catalog.mjs

@@ -0,0 +1,31 @@
+export const canonicalSkillIds = Object.freeze([
+  "ai-slop-remover",
+  "comment-checker",
+  "debugging",
+  "deep-interview",
+  "frontend-ui-ux",
+  "git-master",
+  "hyperplan",
+  "init-deep",
+  "korean-ai-slop-remover",
+  "lit-handoff",
+  "lit-loop",
+  "lit-plan",
+  "lit-recap",
+  "lit-scientific-visualization",
+  "litgoal",
+  "litresearch",
+  "lsp",
+  "lsp-setup",
+  "programming",
+  "refactor",
+  "remove-ai-slops",
+  "review-work",
+  "rules",
+  "start-work",
+  "visual-qa",
+]);
+
+export const canonicalSkillFiles = Object.freeze(
+  canonicalSkillIds.map((skillId) => `skills/${skillId}/SKILL.md`),
+);

package/scripts/doctor.mjs

@@ -3,6 +3,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { canonicalSkillFiles } from "../plugins/litclaude/lib/canonical-skill-catalog.mjs";
 
 const root = resolve(fileURLToPath(new URL("..", import.meta.url)));
 
@@ -35,15 +36,12 @@ for (const file of [
   "plugins/litclaude/lib/litgoal/cli.mjs",
   "plugins/litclaude/lib/start-work-lifecycle.mjs",
   "plugins/litclaude/lib/start-work-cli.mjs",
-  "plugins/litclaude/skills/start-work/SKILL.md",
   "plugins/litclaude/commands/start-work.md",
-  "plugins/litclaude/skills/lit-handoff/SKILL.md",
   "plugins/litclaude/commands/lit-handoff.md",
   "plugins/litclaude/vendor/022_handoff/SKILL.md",
   "plugins/litclaude/vendor/022_handoff/evals/evals.json",
   "plugins/litclaude/vendor/022_handoff/examples/HANDOFF-example-generic-auth-refactor.md",
   "plugins/litclaude/vendor/022_handoff/templates/HANDOFF.md",
-  "plugins/litclaude/skills/lit-scientific-visualization/SKILL.md",
   "plugins/litclaude/commands/lit-scientific-visualization.md",
   "plugins/litclaude/vendor/045_scientific-visualization/SKILL.md",
   "plugins/litclaude/vendor/045_scientific-visualization/scripts/style_presets.py",
@@ -59,6 +57,16 @@ for (const file of [
     process.exit(1);
   }
 }
+
+for (const file of canonicalSkillFiles) {
+  const relativePath = `plugins/litclaude/${file}`;
+  if (!existsSync(join(root, relativePath))) {
+    process.stderr.write(`Runtime payload missing: ${relativePath}\n`);
+    process.exit(1);
+  }
+}
+process.stdout.write("\nSKILL_CATALOG_PASS\n");
+
 process.stdout.write("\nLITGOAL_RUNTIME_PASS\n");
 process.stdout.write("START_WORK_LIFECYCLE_PASS: schema-3 bounded-authority runtime enrolled\n");
 process.stdout.write("START_WORK_HOST_HOOKS_PASS: PreToolUse, SubagentStart, SubagentStop, SessionEnd, and Stop enrolled\n");