hypomnema 1.6.2 → 1.7.1

package/scripts/doctor.mjs

@@ -13,18 +13,26 @@
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
-import { join, relative, extname } from 'path';
+import { join, relative, extname, dirname } from 'path';
 import { homedir } from 'os';
 import { spawnSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
 import { loadHypoIgnore, isScanIgnored } from './lib/hypo-ignore.mjs';
+import { readRenameMarker, renameMarkerPath, RENAME_MARKER_REL } from './lib/rename-marker.mjs';
+import { resolveGitHooksDir } from './lib/git-hooks-dir.mjs';
 import { parseFrontmatter } from './lib/frontmatter.mjs';
 import {
   readSyncState,
+  readSyncLastSuccess,
+  classifySyncOp,
   projectSuggestionsPath,
   collectProjectWorkingDirs,
+  detectSessionCloseArtifact,
+  localAndUtcDates,
+  SESSION_CLOSED_MARKER_STALE_MS,
 } from '../hooks/hypo-shared.mjs';
+import { listProposals } from '../hooks/proposal-store.mjs';
 import {
   discoverExtensions,
   parseManifest,
@@ -35,16 +43,40 @@ import {
   resolveInstallFile,
   buildHookCommand,
   parseExtKey,
+  parseSkillKey,
+  parseSkillShaValue,
+  isFlatShaValue,
   EXT_TYPES,
   CODEX_TYPES,
 } from './lib/extensions.mjs';
 import { sha256, readFileIfRegular, readPkgJson } from './lib/pkg-json.mjs';
 import { resolveCliOnPath, classifyInstall } from '../hooks/version-check.mjs';
+import { isHypomnemaPluginEnabled } from './lib/plugin-detect.mjs';
 
 const HOME = homedir();
 const SCRIPT_DIR = fileURLToPath(new URL('.', import.meta.url));
 const PKG_ROOT = join(SCRIPT_DIR, '..');
 
+// ── install channel ───────────────────────────────────────────────────────────
+//
+// A plugin-channel install registers its 14 core hooks straight out of the
+// package's own hooks/hooks.json (CLAUDE_PLUGIN_ROOT) — Claude Code auto-wires
+// them, they are never copied into ~/.claude/hooks and never listed in
+// ~/.claude/settings.json. checkHooks/checkSettingsJson used to treat that
+// empty state as "missing" and prescribe `/hypo:init`, which then copied +
+// registered the very same hooks a second time (every hook firing twice).
+//
+// `pluginMode` mirrors upgrade.mjs's own detector: this doctor.mjs is itself
+// running from a `.claude/plugins/…` root. `hypomnemaPluginEnabled` catches the
+// dual-install variant — a manual/npm doctor.mjs run while the plugin is ALSO
+// enabled in settings.json (see lib/plugin-detect.mjs; fails open on any
+// uncertainty). Either signal means Claude's core hook surface is
+// plugin-managed, not missing.
+const pluginMode = PKG_ROOT.replace(/\\/g, '/').includes('/.claude/plugins/');
+const hypomnemaPluginEnabled =
+  !pluginMode && isHypomnemaPluginEnabled(join(HOME, '.claude', 'settings.json'));
+const coreManagedByPlugin = pluginMode || hypomnemaPluginEnabled;
+
 // Shown after every fatal package-integrity error. These conditions mean the
 // shipped hooks/hooks.json is missing or malformed — never a user mistake —
 // so the only useful next step is a re-install of the package.
@@ -255,7 +287,17 @@ function checkFiles(hypoDir) {
   }
 }
 
-function checkHooks() {
+// .hyposcanignore is optional (scan-only exclusions, not a privacy boundary),
+// so its absence is info-level — pass either way, never warn/fail.
+function checkScanIgnoreFile(hypoDir) {
+  const present = existsSync(join(hypoDir, '.hyposcanignore'));
+  pass(
+    'File: .hyposcanignore',
+    present ? 'present' : 'optional — not present, no scan-only exclusions configured',
+  );
+}
+
+function checkHooks(coreManagedByPlugin) {
   const claudeHooks = join(HOME, '.claude', 'hooks');
   const allFiles = [...Object.values(HOOK_MAP).flat(), ...SHARED_FILES];
 
@@ -266,6 +308,13 @@ function checkHooks() {
 
   if (missing === 0) {
     pass('Hook files installed', claudeHooks);
+  } else if (coreManagedByPlugin && missing === allFiles.length) {
+    // Plugin channel: an empty ~/.claude/hooks is the expected, healthy state
+    // (the plugin loader provides the hooks), not a missing install.
+    pass(
+      'Hook files installed',
+      `provided by the plugin loader (hooks/hooks.json) — none copied to ${claudeHooks} (expected)`,
+    );
   } else if (missing < allFiles.length) {
     warn('Hook files installed', `${missing}/${allFiles.length} missing in ${claudeHooks}`);
   } else {
@@ -273,10 +322,17 @@ function checkHooks() {
   }
 }
 
-function checkSettingsJson() {
+function checkSettingsJson(coreManagedByPlugin) {
   const settingsPath = join(HOME, '.claude', 'settings.json');
   if (!existsSync(settingsPath)) {
-    warn('settings.json hook registrations', 'settings.json not found');
+    if (coreManagedByPlugin) {
+      pass(
+        'settings.json hook registrations',
+        'provided by the plugin loader (hooks/hooks.json) — settings.json entries not required',
+      );
+    } else {
+      warn('settings.json hook registrations', 'settings.json not found');
+    }
     return;
   }
 
@@ -310,6 +366,13 @@ function checkSettingsJson() {
       'settings.json hook registrations',
       `${registered}/${total} registered — run /hypo:init to merge missing entries`,
     );
+  } else if (coreManagedByPlugin) {
+    // Same reasoning as checkHooks: the plugin loader never touches settings.json,
+    // so 0/total here is the expected plugin-channel state, not a missing install.
+    pass(
+      'settings.json hook registrations',
+      `0/${total} registered in settings.json — provided by the plugin loader (hooks/hooks.json) instead (expected)`,
+    );
   } else {
     fail('settings.json hook registrations', `0/${total} registered — run /hypo:init`);
   }
@@ -394,20 +457,168 @@ function checkGit(hypoDir) {
     warn('Git remote origin', 'No remote configured — wiki will not sync/backup automatically');
   }
 
-  const preCommitPath = join(hypoDir, '.git', 'hooks', 'pre-commit');
+  // Ask git for the ACTIVE hooks dir rather than assuming <repo>/.git/hooks —
+  // that guess is wrong in a linked worktree (`.git` is a file) and whenever
+  // core.hooksPath is set, and reporting "not installed" for either would be a
+  // false negative. Read-side policy differs from the installer's: doctor
+  // reports a hooks dir it would refuse to WRITE into, so the user can see it.
+  const resolved = resolveGitHooksDir(hypoDir);
+  if (!resolved.ok) {
+    const detail =
+      resolved.reason === 'hooks-disabled'
+        ? `Hooks path is not a directory (${resolved.path}) — git runs no hooks, so the .hypoignore guard cannot run`
+        : `Could not resolve the git hooks directory (${resolved.detail || resolved.reason})`;
+    warn('git hooks/pre-commit', detail);
+    return;
+  }
+
+  const preCommitPath = join(resolved.path, 'pre-commit');
+  const label = resolved.owned ? 'git hooks/pre-commit' : `pre-commit (${resolved.path})`;
+  let content = null;
+  let unreadable = null;
   if (existsSync(preCommitPath)) {
-    const content = readFileSync(preCommitPath, 'utf-8');
-    if (content.includes('# hypo-managed:pre-commit:start')) {
-      pass('.git/hooks/pre-commit', 'Hypomnema .hypoignore guard installed');
-    } else {
-      warn(
-        '.git/hooks/pre-commit',
-        'Exists but not managed by Hypomnema — manual git add can bypass .hypoignore',
-      );
+    try {
+      content = readFileSync(preCommitPath, 'utf-8');
+    } catch (e) {
+      unreadable = e.code || e.message;
     }
+  }
+
+  if (unreadable) {
+    warn(label, `Exists but could not be read (${unreadable})`);
+  } else if (content === null) {
+    // Telling the user to run /hypo:init here would contradict the ownership
+    // warning below, which says it will refuse this very path.
+    warn(
+      label,
+      resolved.owned
+        ? 'Not installed — run /hypo:init to install .hypoignore guard'
+        : 'Not installed, and /hypo:init will not install into this path — point core.hooksPath back inside the repository, or install the guard yourself',
+    );
+  } else if (content.includes('# hypo-managed:pre-commit:start')) {
+    pass(label, 'Hypomnema .hypoignore guard installed');
   } else {
-    warn('.git/hooks/pre-commit', 'Not installed — run /hypo:init to install .hypoignore guard');
+    warn(label, 'Exists but not managed by Hypomnema — manual git add can bypass .hypoignore');
+  }
+
+  // Reported even when the hook above was unreadable — an unreadable hook is
+  // exactly when knowing WHERE git looks matters most.
+  if (!resolved.owned) {
+    warn(
+      'core.hooksPath',
+      `Points outside this repository (${resolved.path}) — /hypo:init will not install there`,
+    );
+  }
+}
+
+// rename.mjs --apply writes .cache/rename-in-progress.json before its first
+// inbound-link rewrite and removes it only after the terminal move lands (see
+// rename.mjs's writeRenameMarker/clearRenameMarker). A marker still present
+// means the process died mid-run: some inbound wikilinks may already point at
+// `to` while the page/directory itself still sits at `from`. checkBrokenLinks
+// below would just report those as generic broken links (W4's doctor
+// counterpart) with no clue why — this names the cause and the exact fix.
+// Re-running the SAME command converges on its own (the module docstring's
+// move-last invariant): nothing to merge or roll back by hand.
+// Best-effort: does this vault's git repo leave `markerPath` un-ignored (either
+// already tracked, or plain untracked-and-stageable)? `git check-ignore` answers
+// both at once — a tracked file is also reported "not ignored" by it, since
+// .gitignore rules don't retroactively apply to tracked paths. Fails CLOSED to
+// "don't know, say nothing": no `.git`, no git on PATH, or any non-0/1 exit
+// (128 = not a repo / path outside it / other error) all return false, because
+// this is advisory-only and a wrong guess is worse than silence (codex CONCERN 3
+// — never turn an inconclusive git query into an error of its own).
+function markerNotGitIgnored(hypoDir, markerPath) {
+  if (!existsSync(join(hypoDir, '.git'))) return false;
+  const rel = relative(hypoDir, markerPath);
+  const r = spawnSync('git', ['-C', hypoDir, 'check-ignore', '-q', rel], { encoding: 'utf-8' });
+  if (r.error || r.status === null) return false;
+  if (r.status !== 0 && r.status !== 1) return false; // 128 etc — inconclusive
+  return r.status === 1; // check-ignore's "not ignored" exit code
+}
+
+function checkIncompleteRename(hypoDir) {
+  // "no marker" and "a marker we cannot read" are different answers and must not
+  // collapse. readRenameMarker returns null for both, so ask the filesystem
+  // which one it is: a present-but-unreadable marker still means a rename did
+  // not finish, and reporting that as a pass would make the detector fail open
+  // on exactly the case it exists for.
+  const markerPath = renameMarkerPath(hypoDir);
+  const present = existsSync(markerPath);
+  if (!present) {
+    pass('Incomplete rename', 'No rename-in-progress marker found');
+    return;
+  }
+
+  // codex CONCERN 3: a legacy/custom vault whose .gitignore predates
+  // templates/gitignore's `.cache/` entry (init never edits an existing
+  // .gitignore) can let `git add -A` commit this marker, producing a ghost
+  // warning on another machine that never ran a rename at all. Advisory only —
+  // never turns the rename itself into an error — appended to every branch
+  // below that reports on a present marker.
+  const gitAdvisory = markerNotGitIgnored(hypoDir, markerPath)
+    ? ` This vault's git repo does not ignore ${dirname(RENAME_MARKER_REL)}/ — \`git add -A\` could commit this marker and produce a ghost warning on another machine. Add \`.cache/\` to .gitignore.`
+    : '';
+
+  const marker = readRenameMarker(hypoDir);
+  if (!marker || !marker.from || !marker.to) {
+    warn(
+      'Incomplete rename',
+      `${markerPath} exists but is unreadable or missing its from/to fields, so a rename did not finish and this cannot say which one. Inspect the file, re-run that rename to converge, then delete the marker.${gitAdvisory}`,
+    );
+    return;
+  }
+
+  // codex BLOCKER 2: the marker alone cannot distinguish a genuinely stuck
+  // rename from one that finished right before the process died — rename.mjs's
+  // move (renameSync) is the terminal step, and the marker is only cleared
+  // AFTER it. Cross-check `from`/`to` (vault-root-relative) against the
+  // filesystem to tell the three reachable states apart.
+  const { mode, from, to, started_at } = marker;
+  const label = mode === 'directory' ? 'directory' : 'page';
+  const fromExists = existsSync(join(hypoDir, from));
+  const toExists = existsSync(join(hypoDir, to));
+  const cmd = `node ${join(PKG_ROOT, 'scripts', 'rename.mjs')} --hypo-dir=${hypoDir} --from=${from} --to=${to} --apply`;
+
+  if (fromExists && !toExists) {
+    // The real in-progress case: --from still resolves, so re-running the
+    // IDENTICAL command converges on its own (rename.mjs's move-last invariant).
+    warn(
+      'Incomplete rename',
+      `a ${label} rename from '${from}' to '${to}' did not finish` +
+        (started_at ? ` (started ${started_at})` : '') +
+        ` — some inbound links may already point at the new name while the ${label} itself has not moved. Re-run the identical rename to converge: ${cmd}${gitAdvisory}`,
+    );
+    return;
+  }
+
+  if (!fromExists && toExists) {
+    // The move already landed — renameSync is one syscall, so this can only mean
+    // the process died AFTER it and BEFORE clearRenameMarker ran. Re-running the
+    // same command here would just fail (`--from` no longer resolves — see
+    // rename.mjs's own "did not resolve to a unique existing page" refusal), so
+    // suggesting a re-run (the prior behavior) handed the user a command that
+    // errors. Nothing to converge: the marker is pure leftover.
+    warn(
+      'Incomplete rename',
+      `a ${label} rename from '${from}' to '${to}' already finished (the ${label} moved) but its ` +
+        `in-progress marker was never cleared — the process likely died right after the move landed. ` +
+        `Nothing left to redo; just delete the stale marker: rm ${markerPath}${gitAdvisory}`,
+    );
+    return;
   }
+
+  // Both paths exist, or neither does — the marker's from/to no longer map onto
+  // a determinable state (e.g. something else since recreated one of the two
+  // paths). Refuse to guess in either direction; a human needs to look.
+  warn(
+    'Incomplete rename',
+    `${markerPath} names a ${label} rename from '${from}' to '${to}', but ${
+      fromExists && toExists
+        ? 'BOTH the from and to paths currently exist'
+        : 'NEITHER the from nor the to path currently exists'
+    } — cannot tell whether the rename finished. Inspect both paths by hand, then either re-run the rename or delete the marker: ${markerPath}${gitAdvisory}`,
+  );
 }
 
 function checkBrokenLinks(hypoDir, ignorePatterns = []) {
@@ -588,6 +799,239 @@ function checkProjectIndexAnchors(hypoDir) {
   }
 }
 
+// The project(s) a commit touched, by which projects/<slug>/ paths it
+// changed — a SET, because a merge or a multi-project commit can touch more
+// than one, and `close the session` in that commit's message must then be
+// verified against ALL of them, not silently attributed to just one.
+// Empty when the commit touches no project path, or `git show` itself fails
+// (a corrupt or unreachable object) — both are "can't determine scope", which
+// this returns as *no scope at all*, not "any scope"; see markerCoversArtifact
+// for why that direction matters.
+function deriveCommitProjects(hypoDir, hash) {
+  // --name-status -M (not --name-only): a rename prints ONLY the destination
+  // path under --name-only ("R100 old\tnew" collapses to just "new"), so a
+  // projects/a/hot.md → projects/b/hot.md rename would silently drop project
+  // a from scope — a marker naming only "b" would then wrongly cover the
+  // whole commit. -M's tab-separated `status\told\tnew` line carries both.
+  const show = spawnSync(
+    'git',
+    ['-C', hypoDir, 'show', '--name-status', '-M', '--format=', hash],
+    { encoding: 'utf-8' },
+  );
+  if (show.status !== 0 || !show.stdout) return [];
+  const projects = new Set();
+  for (const line of show.stdout.split('\n')) {
+    if (!line.trim()) continue;
+    // status\tpath (add/modify/delete) or status\told\tnew (rename/copy) —
+    // every field after the status column is a path this commit touched.
+    const [, ...paths] = line.split('\t');
+    for (const path of paths) {
+      const m = /^projects\/([^/]+)\//.exec(path.trim());
+      // _template is the scaffold, never a real project — same exclusion the
+      // file-scan loop above applies, so a commit that happens to touch it
+      // (e.g. an init/upgrade run) doesn't manufacture a phantom project a
+      // marker can never cover.
+      if (m && m[1] !== '_template') projects.add(m[1]);
+    }
+  }
+  return [...projects];
+}
+
+// A marker only vouches for the project(s) it names, PLUS its own calendar
+// day. Two ways that can go wrong if handled loosely, both fixed here:
+//
+//   1. Scope creep: a same-day close in a DIFFERENT project must not silence
+//      this one (the marker was introduced for per-session precision
+//      specifically to prevent one close from vouching for another —
+//      hooks/hypo-shared.mjs SESSION_CLOSED_MARKER_STALE_MS comment).
+//   2. Timezone artifact: closed_at is UTC; a file-content artifact's date is
+//      local (hooks/hypo-shared.mjs localAndUtcDates() accepts both for
+//      exactly this reason).
+//
+// `artifact.scope.kind` is a closed set, not a free-form nullable project —
+// an UNKNOWN scope must never default to "any marker on that date covers
+// it": this is a warning-only, best-effort check, so the cost of a false
+// PASS (the exact failure mode it exists to catch) outweighs the cost of a
+// false WARN (mild noise). Concretely:
+//   • 'root-universal' — root hot.md. The real close procedure updates it on
+//     EVERY close regardless of project (closeFileTargets in
+//     hooks/hypo-shared.mjs), so date-only correlation is legitimate here,
+//     not a gap.
+//   • 'unscoped' — root session-state.md (NOT part of the real close file
+//     set — the same closeFileTargets list proves it), or a commit whose
+//     touched-project set came back empty/ambiguous. No marker can vouch for
+//     an artifact with no verifiable scope, so this never matches, ever.
+//   • 'projects' — a project file, or a commit that touched one or more
+//     identifiable projects/<slug>/ paths. EVERY named project must appear
+//     in the marker's own `projects` list.
+function markerCoversArtifact(marker, artifact) {
+  if (!marker.dates.includes(artifact.date)) return false;
+  switch (artifact.scope.kind) {
+    case 'root-universal':
+      return true;
+    case 'projects':
+      return artifact.scope.projects.every((p) => marker.projects.includes(p));
+    default:
+      return false; // 'unscoped'
+  }
+}
+
+// Post-hoc surface for a session closed BY HAND, without the session-closed
+// marker hard gate ever firing (the gate lives on the marker writer, and a
+// close done by editing files directly never calls it). Warning-only: this
+// cannot tell an actually-approved-but-ungated close from an over-close, it
+// can only say the two signals disagree, so it never blocks.
+//
+// Window: 7 days for the git-log scan, matching SESSION_CLOSED_MARKER_STALE_MS
+// in hooks/hypo-shared.mjs — a marker older than that is already treated as
+// expired everywhere else (enforced below too, when reading the raw marker
+// files), so correlating against a longer window would compare a close
+// artifact against a marker doctor itself considers stale.
+function checkSessionCloseArtifacts(hypoDir) {
+  const artifacts = [];
+
+  const scanFile = (path, scope) => {
+    if (!existsSync(path)) return;
+    let content;
+    try {
+      content = readFileSync(path, 'utf-8');
+    } catch {
+      return;
+    }
+    const result = detectSessionCloseArtifact({ path, content });
+    if (result.matched) {
+      artifacts.push({ date: result.date, scope, where: relative(hypoDir, path) });
+    }
+  };
+
+  // Root hot.md is a real close artifact of every close, project or not — see
+  // markerCoversArtifact's 'root-universal' case. Root session-state.md is
+  // NOT: the real close procedure never touches it (closeFileTargets in
+  // hooks/hypo-shared.mjs lists hot.md/log.md + the ACTIVE project's files
+  // only), so a 마감 heading appearing there has no legitimate close to
+  // attribute it to — 'unscoped' means no marker, however fresh, ever covers it.
+  scanFile(join(hypoDir, 'hot.md'), { kind: 'root-universal' });
+  scanFile(join(hypoDir, 'session-state.md'), { kind: 'unscoped' });
+  const projectsDir = join(hypoDir, 'projects');
+  if (existsSync(projectsDir)) {
+    for (const slug of readdirSync(projectsDir)) {
+      if (slug === '_template') continue;
+      const dir = join(projectsDir, slug);
+      try {
+        if (!statSync(dir).isDirectory()) continue;
+      } catch {
+        continue;
+      }
+      scanFile(join(dir, 'session-state.md'), { kind: 'projects', projects: [slug] });
+      scanFile(join(dir, 'hot.md'), { kind: 'projects', projects: [slug] });
+    }
+  }
+
+  if (existsSync(join(hypoDir, '.git'))) {
+    const log = spawnSync(
+      'git',
+      ['-C', hypoDir, 'log', '--since=7.days.ago', '--format=%H%x1f%ad%x1f%s', '--date=short'],
+      { encoding: 'utf-8' },
+    );
+    if (log.status === 0 && log.stdout) {
+      for (const line of log.stdout.split('\n')) {
+        if (!line.trim()) continue;
+        const [hash, date, subject] = line.split('\x1f');
+        if (detectSessionCloseArtifact({ commitMessage: subject }).matched) {
+          const projects = deriveCommitProjects(hypoDir, hash);
+          artifacts.push({
+            date,
+            scope: projects.length > 0 ? { kind: 'projects', projects } : { kind: 'unscoped' },
+            where: `commit "${subject}"`,
+          });
+        }
+      }
+    }
+  }
+
+  if (artifacts.length === 0) {
+    pass('Session-close artifacts', 'No close artifacts found');
+    return;
+  }
+
+  // Read the raw marker files directly rather than readSessionClosedMarker,
+  // which also DELETES an expired one as a side effect; a health check
+  // should not mutate state to produce a diagnosis. Staleness is still
+  // enforced here (same SESSION_CLOSED_MARKER_STALE_MS window) so an
+  // already-expired marker can't vouch for anything.
+  const cacheDir = join(hypoDir, '.cache');
+  const markers = [];
+  let cacheEntries = [];
+  if (existsSync(cacheDir)) {
+    try {
+      cacheEntries = readdirSync(cacheDir);
+    } catch {
+      // unreadable .cache/ — not this check's job to diagnose that
+    }
+  }
+  for (const file of cacheEntries) {
+    if (!file.startsWith('session-closed-') || !file.endsWith('.marker')) continue;
+    try {
+      const data = JSON.parse(readFileSync(join(cacheDir, file), 'utf-8'));
+      const ts = Date.parse(data?.closed_at || '');
+      if (!Number.isFinite(ts) || Date.now() - ts > SESSION_CLOSED_MARKER_STALE_MS) continue;
+      // ONLY the v4 `projects` array counts as project-scope evidence. A
+      // legacy flat `project` field can be a recency-derived misattribution
+      // (the P1 bug resolveCloseScope's own doc comment describes) — the
+      // runtime scope resolver already refuses to trust it uncorroborated,
+      // and doctor has no corroborating signal of its own to add, so it
+      // must refuse it too rather than re-opening the same hole standalone.
+      const projects = Array.isArray(data?.projects) ? data.projects.filter(Boolean) : [];
+      markers.push({ projects: [...new Set(projects)], dates: localAndUtcDates(new Date(ts)) });
+    } catch {
+      // corrupt marker — not this check's job to clean up
+    }
+  }
+
+  const unmatched = artifacts.filter(
+    (a) => !a.date || !markers.some((m) => markerCoversArtifact(m, a)),
+  );
+  if (unmatched.length === 0) {
+    pass(
+      'Session-close artifacts',
+      `${artifacts.length} close artifact(s), all covered by a session-closed marker`,
+    );
+    return;
+  }
+
+  const sample = unmatched
+    .slice(0, 5)
+    .map((a) => `${a.where}${a.date ? ` (${a.date})` : ''}`)
+    .join(', ');
+  const extra = unmatched.length > 5 ? ` (+${unmatched.length - 5} more)` : '';
+  // Not necessarily UNAPPROVED — an approved log-only marker (deliberately
+  // empty `projects`) or one scoped to a different project would ALSO land
+  // here, since neither covers a specific project's artifact. Both readings
+  // are worth a human look, so the wording covers both instead of asserting
+  // the stronger, sometimes-wrong one.
+  warn(
+    'Session-close artifacts',
+    `${unmatched.length} close artifact(s) with no session-closed marker covering their ` +
+      `date and project scope — may be an unapproved hand-made close, or an approved close ` +
+      `whose marker doesn't attribute this project: ${sample}${extra}`,
+  );
+}
+
+/**
+ * Render a `.cache/sync-last-success.json` record as an absolute-time note.
+ * Deliberately no "recent"/staleness verdict — the failure-state check above
+ * already carries the health signal; this only says what and when.
+ */
+function formatLastSuccess(lastSuccess) {
+  const pull = lastSuccess.pull
+    ? `pull ${lastSuccess.pull.timestamp} (${lastSuccess.pull.host})`
+    : 'pull: none recorded';
+  const push = lastSuccess.push
+    ? `push ${lastSuccess.push.timestamp} (${lastSuccess.push.host})`
+    : 'push: none recorded';
+  return `${pull}; ${push}`;
+}
+
 function checkSyncState(hypoDir) {
   // "open" = file exists with ≥1 entries; session-start clears once
   // sync is healthy again. Schema + parsing live in hooks/hypo-shared.mjs.
@@ -599,20 +1043,96 @@ function checkSyncState(hypoDir) {
   }
 
   if (entries.length === 0) {
-    pass('Sync state', 'No unresolved sync failures');
+    // No unresolved failure — but that alone does not mean sync ever ran.
+    // Read the separate, additive last-success record to tell "never synced"
+    // apart from "healthy" and, when present, from a pull-only/push-only
+    // history. A corrupt success file warns rather than crashing, same as the
+    // sync-state parse-error handling above.
+    const { data: lastSuccess, parseError: successParseError } = readSyncLastSuccess(hypoDir);
+    if (successParseError) {
+      warn('Sync state', 'Cannot parse .cache/sync-last-success.json — inspect manually');
+    } else if (!lastSuccess.pull && !lastSuccess.push) {
+      pass(
+        'Sync state',
+        'No unresolved sync failures — never synced (no recorded pull or push yet)',
+      );
+    } else {
+      // Distinguishes pull-only / push-only / both, since formatLastSuccess
+      // reports "none recorded" for whichever op is absent.
+      pass(
+        'Sync state',
+        `No unresolved sync failures. Last success — ${formatLastSuccess(lastSuccess)}`,
+      );
+    }
   } else {
     const last = entries[entries.length - 1];
-    // A merge conflict needs a real manual merge, not a plain push/pull — give
-    // the same explicit guidance session-start does instead of the generic hint.
-    if (String(last.op || '').startsWith('conflict')) {
+    // An unresolved failure does not mean the OTHER operation never
+    // succeeded — a push failure can sit right next to a healthy pull, and
+    // the last-success record above used to only wire into the healthy/
+    // never-synced branch, leaving this branch silent about it. Append it
+    // here too, best-effort, same as the healthy branch — a corrupt success
+    // file still warns, never crashes.
+    const { data: lastSuccess, parseError: successParseError } = readSyncLastSuccess(hypoDir);
+    // Not "unreadable": readSyncLastSuccess also sets parseError for a file
+    // that reads fine and parses as valid JSON but has the wrong shape (a
+    // malformed pull/push field, or an unrecognized key) — "unreadable" would
+    // misdescribe that case.
+    const successSuffix = successParseError
+      ? ' (.cache/sync-last-success.json is invalid or unreadable — inspect manually)'
+      : lastSuccess.pull || lastSuccess.push
+        ? ` Last success — ${formatLastSuccess(lastSuccess)}.`
+        : '';
+    // More than one open entry means the vault has been failing across
+    // multiple sync attempts without clearing — name each one (op@timestamp),
+    // not just the last, so the user isn't left to open sync-state.json
+    // themselves to see the pattern. Capped like checkBrokenLinks/checkVerifyBy.
+    const unresolvedList =
+      entries.length > 1
+        ? ` Unresolved: ${entries
+            .slice(-5)
+            .map((e) => `${e.op || '?'}@${e.timestamp || '?'}`)
+            .join(', ')}${entries.length > 5 ? ` (+${entries.length - 5} more)` : ''}.`
+        : '';
+    // classifySyncOp (hooks/hypo-shared.mjs) is the single judgment both this
+    // check and hypo-session-start.mjs's syncStateNotice branch on, so the
+    // two surfaces cannot silently diverge on WHICH op gets which treatment.
+    // 'conflict-unresolved' — the merge --abort itself failed — is the more
+    // dangerous of the two conflict ops: the tree may still be
+    // half-merged (unmerged index entries, or an in-progress MERGE_HEAD), so
+    // it gets dedicated guidance rather than the plain-conflict branch below,
+    // which claims "your local work is committed" (not true when the abort
+    // itself failed) and advises `git pull --no-rebase` (git would simply
+    // refuse that mid-merge). Wording mirrors hypo-session-start.mjs's
+    // syncStateNotice so the two surfaces never contradict each other.
+    const cls = classifySyncOp(last.op);
+    if (cls === 'conflict-unresolved') {
       warn(
         'Sync state',
-        `${entries.length} unresolved sync issue(s) — last: remote diverged (merge conflict). Your local work is committed; the other machine's version is on the remote. Resolve with \`git pull --no-rebase\`, fix conflicts, then push.`,
+        `${entries.length} unresolved sync issue(s) — last: remote diverged AND the automatic merge-abort failed; the working tree may still be half-merged (unmerged paths or an in-progress merge). Do NOT commit or push yet. Run \`git status\` first: if a merge is in progress, resolve the conflicts, then \`git add <resolved paths>\` and \`git commit\` (git refuses a commit while unmerged entries remain staged) — or run \`git merge --abort\` to discard it instead, before continuing.${unresolvedList}${successSuffix}`,
+      );
+    } else if (cls === 'conflict') {
+      // A merge conflict needs a real manual merge, not a plain push/pull —
+      // give the same explicit guidance session-start does instead of the
+      // generic hint. This branch is unmerged-index-free by construction (the
+      // abort succeeded), so "committed and safe" is an accurate claim here.
+      warn(
+        'Sync state',
+        `${entries.length} unresolved sync issue(s) — last: remote diverged (merge conflict). Your local work is committed; the other machine's version is on the remote. Resolve with \`git pull --no-rebase\`, fix conflicts, \`git add\` them, then commit and push.${unresolvedList}${successSuffix}`,
+      );
+    } else if (cls === 'unknown-conflict') {
+      // An unrecognized `conflict*` op — a future syncRemote failure mode
+      // this check has no dedicated branch for. Neither the 'conflict'
+      // branch's "committed" claim nor the 'conflict-unresolved' branch's
+      // "abort failed" claim is known to hold here, so assert neither:
+      // report the state as unknown and treat it as unresolved.
+      warn(
+        'Sync state',
+        `${entries.length} unresolved sync issue(s) — last: remote diverged — an unrecognized conflict-related sync failure ('${last.op}') was recorded. Its resolution state cannot be confirmed automatically — treat it as unresolved. Run \`git status\` first to check for unmerged paths or an in-progress merge before committing or pushing.${unresolvedList}${successSuffix}`,
       );
     } else {
       warn(
         'Sync state',
-        `${entries.length} unresolved failure(s) — last: ${last.op || '?'} at ${last.timestamp || '?'}. Inspect .cache/sync-state.json or push/pull manually to clear.`,
+        `${entries.length} unresolved failure(s) — last: ${last.op || '?'} at ${last.timestamp || '?'}. Inspect .cache/sync-state.json or push/pull manually to clear.${unresolvedList}${successSuffix}`,
       );
     }
   }
@@ -669,6 +1189,24 @@ function checkProjectSuggestions(hypoDir) {
   }
 }
 
+function checkProposals(hypoDir) {
+  // Vault-wide count of parked write-proposals (T8). listProposals is the
+  // count source rather than a raw readdir: it already skips malformed and
+  // spoofed-id artifacts, so the number matches exactly what `hypomnema proposal
+  // list/apply/discard` can act on. Surface only: warn (never fail), pass at 0,
+  // because a pending proposal is a normal state awaiting review, not a broken
+  // install, and the check discovers without changing any state.
+  const count = listProposals(hypoDir).length;
+  if (count === 0) {
+    pass('Pending proposals', 'No parked write-proposals');
+  } else {
+    warn(
+      'Pending proposals',
+      `${count} parked write-proposal(s) awaiting review; inspect with \`hypomnema proposal list\``,
+    );
+  }
+}
+
 function checkCodexPaths() {
   const codexHooks = join(HOME, '.codex', 'hooks');
   const allFiles = [...Object.values(HOOK_MAP).flat(), ...SHARED_FILES];
@@ -805,6 +1343,58 @@ function checkExtensions(hypoDir, claudeHome, target = 'claude') {
     // Skip keys outside this target's covered types (defensive: a Claude run records
     // skills/agents that a codex target never installs — don't false-flag them).
     if (!types.includes(key.split('/')[0])) continue;
+
+    // A directory skill records one key whose value is a per-file SHA map. Joining
+    // that key straight onto root would land on the skill DIRECTORY and report it
+    // as "not a regular file" on every run. Check the subtree file by file instead.
+    const skillKey = parseSkillKey(key);
+    if (skillKey) {
+      const nested = parseSkillShaValue(recSHA);
+      if (!nested) {
+        problems.push({
+          severity: 'warn',
+          msg: `${key} has a corrupt ownership record — run upgrade --apply`,
+        });
+        continue;
+      }
+      const skillRoot = join(root, 'skills', skillKey.installDir);
+      for (const [rel, sha] of Object.entries(nested)) {
+        const filePath = join(skillRoot, ...rel.split('/'));
+        const label = `${key}/${rel}`;
+        if (!existsSync(filePath)) {
+          problems.push({
+            severity: 'warn',
+            msg: `${label} recorded but not installed — run upgrade --apply`,
+          });
+          continue;
+        }
+        const buf = readFileIfRegular(filePath);
+        if (buf === null) {
+          problems.push({
+            severity: 'warn',
+            msg: `${label} is not a regular file — left untouched`,
+          });
+          continue;
+        }
+        if (sha256(buf) !== sha) {
+          problems.push({
+            severity: 'warn',
+            msg: `${label} modified since install (drift) — use --force-extensions`,
+          });
+        }
+      }
+      continue;
+    }
+
+    // A flat key must carry a plain hex SHA; a wrong-shaped value is a corrupt
+    // record, not a drifted file.
+    if (!isFlatShaValue(recSHA)) {
+      problems.push({
+        severity: 'warn',
+        msg: `${key} has a corrupt ownership record — run upgrade --apply`,
+      });
+      continue;
+    }
     const destPath = join(root, key);
     if (!existsSync(destPath)) {
       problems.push({
@@ -1129,9 +1719,44 @@ function checkFeedbackProjection(hypoDir, claudeHome, projectId) {
       `${name}: ${reason} — run \`hypomnema feedback-sync --import-target-change\` to reconcile`,
     );
   } else {
-    // 2) build error → WARN
-    const buildErr = targets.find(([, t]) => t.buildError);
-    if (buildErr) {
+    // 2) build error. Split by kind:
+    //
+    //    'build-failed' → FAIL. The target file EXISTS but its
+    //      <learned_behaviors> container is gone, so the projection cannot be
+    //      built: NOT ONE L1 rule is loaded on that machine and every later sync
+    //      is a silent no-op. This was a warn, which made a structurally broken
+    //      projection near-invisible — nothing else reported it either (the
+    //      PreCompact gate classified it as "nothing to do" and failed open), and
+    //      it went unnoticed on a real machine. A projection that cannot be built
+    //      is a failure, not a note.
+    //
+    //    'target-missing' → WARN, as before. No ~/.claude/CLAUDE.md yet is the
+    //      ordinary first-run state, not a broken one; failing here would fail
+    //      every new user's doctor run.
+    //
+    // Select the build-failed target SPECIFICALLY rather than taking the first
+    // buildError of any kind: with more than one container target, a
+    // 'target-missing' one earlier in iteration order would otherwise mask a
+    // structurally broken one behind a warn — the exact invisibility this check
+    // exists to end. Only `claude` carries a container today, so that masking is
+    // latent, not live; the precompact gate filters the same way.
+    const failedErr = targets.find(([, t]) => t.buildErrorKind === 'build-failed');
+    const buildErr = failedErr || targets.find(([, t]) => t.buildError);
+    if (failedErr) {
+      const [name, t] = failedErr;
+      // Name the remedy for THIS cause, not a fixed one. `--ensure-container`
+      // restores a MISSING container; it cannot chmod an unreadable file, cannot
+      // repoint a dangling symlink, and refuses a corrupt container outright — so
+      // printing it for those causes hands the reader a command that does nothing
+      // and teaches them to ignore the next failure too. feedback-sync decides the
+      // remedy where it detects the cause and ships it as `buildErrorRemedy`; this
+      // just prints it (one judgment, several consumers).
+      fail(
+        'Feedback projection',
+        `${name}: ${t.buildError} — the projection cannot be built, so NO rules are loaded from it ` +
+          `and every sync is a silent no-op. ${t.buildErrorRemedy || ''}`.trimEnd(),
+      );
+    } else if (buildErr) {
       warn('Feedback projection', buildErr[1].buildError);
     } else if (targets.find(([, t]) => t.overCap)) {
       warn('Feedback projection', 'projection over cap — demote/archive feedback pages');
@@ -1144,7 +1769,23 @@ function checkFeedbackProjection(hypoDir, claudeHome, projectId) {
     }
   }
 
-  // 3) unresolved project-id is a separate, non-fatal concern (MEMORY skipped)
+  // 3) side-file I/O problems: a WARN, and additive rather than part of the
+  //    if/else chain above — an unreadable feedback_<slug>.md copy is orthogonal
+  //    to the primary target's health. It must not fail: the index line still
+  //    projects, every rule still loads, and the remedy is a permission bit on a
+  //    named path — nothing `--ensure-container` (the build-failed remedy) can
+  //    touch. feedback-sync already put the path in the message.
+  for (const [name, t] of targets) {
+    for (const w of t.sideWarnings || []) {
+      warn(
+        'Feedback projection side file',
+        `${name}: ${w} — fix the permissions on that path; the primary projection still loads ` +
+          `(\`--ensure-container\` does not fix this)`,
+      );
+    }
+  }
+
+  // 4) unresolved project-id is a separate, non-fatal concern (MEMORY skipped)
   if (report.projectIdResolved === false) {
     warn(
       'Feedback projection',
@@ -1187,6 +1828,121 @@ function checkStaleSibling() {
   }
 }
 
+// ── package integrity ─────────────────────────────────────────────────────────
+//
+// ~/.claude/hypo-pkg.json is a snapshot written once by init/upgrade and never
+// re-validated: nothing tracks whether pkgRoot still exists, whether its
+// package.json version still matches the recorded pkgVersion, or whether
+// pkgRoot points at a dev checkout instead of a distributed copy. Command and
+// skill script resolution was unified onto this one pointer, so a stale or
+// dev-pointing pkgRoot means the wiki silently runs uncommitted WIP.
+// All three checks are WARN, never FAIL — a dogfooding maintainer must be
+// able to ignore them on purpose.
+function checkPkgIntegrity(claudeHome) {
+  const pkgPath = join(claudeHome, 'hypo-pkg.json');
+  const meta = readPkgJson(pkgPath);
+  // Distinguish "no metadata file at all" (a fresh install — non-actionable, stay
+  // silent) from "a file is present but has no pkgRoot" (incomplete metadata that
+  // breaks runtime package resolution — warn rather than silently reading as OK).
+  // readPkgJson renames a corrupt file aside and returns {}, so after that the path
+  // no longer exists and this correctly falls into the silent fresh-install branch.
+  if (!existsSync(pkgPath)) return;
+  if (!meta || !meta.pkgRoot) {
+    warn(
+      'hypo-pkg.json pkgRoot',
+      `hypo-pkg.json has no pkgRoot field — metadata is incomplete; re-run /hypo:init or /hypo:upgrade`,
+    );
+    return;
+  }
+
+  const { pkgRoot, pkgVersion } = meta;
+
+  if (!existsSync(pkgRoot)) {
+    warn(
+      'hypo-pkg.json pkgRoot exists',
+      `${pkgRoot} does not exist — metadata is stale; re-run /hypo:init or /hypo:upgrade`,
+    );
+    return;
+  }
+  pass('hypo-pkg.json pkgRoot exists', pkgRoot);
+
+  let actualVersion = null;
+  let pkgJsonReadable = false;
+  try {
+    actualVersion = JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf-8')).version;
+    pkgJsonReadable = true;
+  } catch {
+    warn('hypo-pkg.json version match', `${pkgRoot}/package.json is unreadable — cannot verify`);
+  }
+  // Every reachable state emits exactly one line: a silent skip here would read as
+  // "verified" on the health report when nothing was actually checked.
+  if (actualVersion) {
+    if (pkgVersion && actualVersion !== pkgVersion) {
+      warn(
+        'hypo-pkg.json version match',
+        `recorded pkgVersion is ${pkgVersion}, but pkgRoot's package.json is v${actualVersion} — ` +
+          `stale metadata; re-run /hypo:init or /hypo:upgrade`,
+      );
+    } else if (pkgVersion) {
+      pass('hypo-pkg.json version match', `v${actualVersion}`);
+    } else {
+      warn(
+        'hypo-pkg.json version match',
+        `metadata records no pkgVersion — cannot verify against pkgRoot's v${actualVersion}; ` +
+          `re-run /hypo:init or /hypo:upgrade`,
+      );
+    }
+  } else if (pkgJsonReadable) {
+    warn(
+      'hypo-pkg.json version match',
+      `${pkgRoot}/package.json has no "version" field — cannot verify`,
+    );
+  }
+
+  // dev-repo check: pkgRoot is a git working tree that is dirty or sits on a
+  // commit with no exact release tag. Normal users should point at a
+  // distributed copy (plugin cache or npm install), not a source checkout.
+  if (existsSync(join(pkgRoot, '.git'))) {
+    const status = spawnSync('git', ['-C', pkgRoot, 'status', '--porcelain'], {
+      encoding: 'utf-8',
+    });
+    const tag = spawnSync('git', ['-C', pkgRoot, 'describe', '--tags', '--exact-match'], {
+      encoding: 'utf-8',
+    });
+    // A non-zero `git describe` exit is the real "HEAD is not an exact tag" signal,
+    // but a spawn failure (git not installed, ENOENT) sets `.error` / a null status
+    // too. Treat those as "cannot classify" instead of silently mislabeling the
+    // pkgRoot as an untagged dev checkout. `git status --porcelain` must exit 0 on
+    // any real repo (clean OR dirty), so a non-zero status there means the repo is
+    // corrupt/inaccessible — also "cannot classify", not "untagged". `git describe`
+    // legitimately exits non-zero when HEAD carries no exact tag, so only its spawn
+    // (error/null status) disqualifies it, not a non-zero exit.
+    const gitUsable =
+      status.error == null && status.status === 0 && tag.error == null && tag.status != null;
+    if (!gitUsable) {
+      warn(
+        'hypo-pkg.json pkgRoot install kind',
+        `pkgRoot has a .git directory but git could not be run — cannot classify the install kind`,
+      );
+      return;
+    }
+    const dirty = status.stdout.trim().length > 0; // gitUsable already asserts status 0
+    const untagged = tag.status !== 0;
+    if (dirty || untagged) {
+      const reasons = [];
+      if (dirty) reasons.push('uncommitted changes');
+      if (untagged) reasons.push('HEAD is not an exact release tag');
+      warn(
+        'hypo-pkg.json pkgRoot install kind',
+        `pkgRoot looks like a development checkout (${reasons.join(', ')}) — normal users should ` +
+          `point at a distributed copy (plugin cache or npm install), not a source repo`,
+      );
+    } else {
+      pass('hypo-pkg.json pkgRoot install kind', 'pkgRoot is a clean, tagged checkout');
+    }
+  }
+}
+
 // ── main ─────────────────────────────────────────────────────────────────────
 
 const args = parseArgs(process.argv);
@@ -1197,18 +1953,23 @@ const rootOk = checkHypoRoot(args.hypoDir);
 if (rootOk) {
   checkDirectories(args.hypoDir);
   checkFiles(args.hypoDir);
+  checkScanIgnoreFile(args.hypoDir);
   checkBrokenLinks(args.hypoDir, ignorePatterns);
+  checkIncompleteRename(args.hypoDir);
   checkVerifyBy(args.hypoDir, ignorePatterns);
 }
-checkHooks();
-checkSettingsJson();
+checkHooks(coreManagedByPlugin);
+checkSettingsJson(coreManagedByPlugin);
+checkPkgIntegrity(args.claudeHome);
 checkStaleSibling();
 if (args.codex) checkCodexPaths();
 if (rootOk) checkExtensions(args.hypoDir, args.claudeHome, 'claude');
 if (rootOk && args.codex) checkExtensions(args.hypoDir, args.claudeHome, 'codex');
 if (rootOk) checkProjectIndexAnchors(args.hypoDir);
+if (rootOk) checkSessionCloseArtifacts(args.hypoDir);
 if (rootOk) checkSyncState(args.hypoDir);
 if (rootOk) checkProjectSuggestions(args.hypoDir);
+if (rootOk) checkProposals(args.hypoDir);
 if (rootOk) checkFeedbackProjection(args.hypoDir, args.claudeHome, args.projectId);
 checkGit(args.hypoDir);