hypomnema 1.4.2 → 1.5.0

package/scripts/resume.mjs

@@ -26,10 +26,10 @@
  *   --json                Output as JSON
  */
 
-import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { existsSync, readFileSync, readdirSync, statSync, realpathSync } from 'fs';
 import { join } from 'path';
-import { homedir } from 'os';
 import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
+import { pickProjectByCwd, collectProjectWorkingDirs } from './lib/wd-match.mjs';
 
 // ── arg parsing ──────────────────────────────────────────────────────────────
 
@@ -60,27 +60,25 @@ function parseFrontmatterField(content, key) {
     .replace(/^['"]|['"]$/g, '');
 }
 
-// Among `slugs`, return the one whose projects/<slug>/index.md `working_dir`
-// is the LONGEST prefix of cwd (so /repo/sub wins over /repo). Returns null
-// when cwd is falsy or matches none. resume gives this authority OVER recency
-// (ADR 0044): a cwd↔working_dir match wins regardless of which row is newest.
+// Return the project (among `slugs`) that owns cwd: a longest-prefix
+// working_dir match, or — when no absolute path matches because the vault was
+// synced from another machine — a cwd ancestor whose directory name is a
+// globally-unique project basename. Uniqueness is judged over EVERY project on
+// disk (not just `slugs`), so a shared dirname declines and falls back to
+// recency. resume gives this authority over recency: a cwd↔project match wins
+// regardless of which hot.md row is newest.
 function pickByCwd(hypoDir, slugs, cwd) {
   if (!cwd) return null;
-  let best = null;
-  let bestLen = -1;
-  for (const slug of slugs) {
-    const indexPath = join(hypoDir, 'projects', slug, 'index.md');
-    if (!existsSync(indexPath)) continue;
-    const wd = parseFrontmatterField(readFileSync(indexPath, 'utf-8'), 'working_dir');
-    if (!wd) continue;
-    let resolved = wd.startsWith('~/') ? join(homedir(), wd.slice(2)) : wd;
-    resolved = resolved.replace(/\/+$/, ''); // trailing-slash normalize
-    if ((cwd === resolved || cwd.startsWith(resolved + '/')) && resolved.length > bestLen) {
-      bestLen = resolved.length;
-      best = slug;
-    }
+  let realpathCwd = null;
+  try {
+    realpathCwd = realpathSync(cwd);
+  } catch {
+    realpathCwd = null;
   }
-  return best;
+  return pickProjectByCwd(collectProjectWorkingDirs(hypoDir), cwd, {
+    eligible: slugs,
+    realpathCwd,
+  });
 }
 
 // When cwd is set but no project's working_dir matches it, resume falls back to
@@ -125,11 +123,11 @@ function resolveActiveProject(hypoDir, cwd = null) {
     ),
   ].map((m) => ({ name: m[1].trim(), date: m[2] || '', slug: m[3] }));
   if (wikiRows.length > 0) {
-    // cwd-first (ADR 0044): a cwd↔working_dir match wins over recency, across
+    // cwd-first: a cwd↔working_dir match wins over recency, across
     // ALL rows (not just a same-date tie). The user is physically in that
     // project, so cwd is a stronger intent signal than "some other project was
     // touched more recently". This reverses the earlier tie-breaker-only
-    // semantics now that resume=cwd-positive (ADR 0043). Tradeoff: a stale cwd
+    // semantics now that resume=cwd-positive. Tradeoff: a stale cwd
     // match can mask a genuinely newer project; `--project` overrides. close
     // callers pass null → recency path below (resume=cwd-positive / close=no-pick).
     if (cwd) {

package/scripts/session-audit.mjs

@@ -6,7 +6,7 @@
  * (search count, ingest count, URLs mentioned, feedback count) so the
  * weekly observability report (Lane E) can compute autonomy scores.
  *
- * Transcript dual-source (ADR 0019):
+ * Transcript dual-source:
  *   1) Primary: <hypo-dir>/.cache/sessions/index.jsonl
  *      Written by hooks/hypo-session-record.mjs (Stop hook).
  *   2) Fallback: ~/.claude/projects/<encoded>/*.jsonl

package/scripts/stats.mjs

@@ -48,8 +48,8 @@ function collectMdFiles(dir, acc = [], hypoDir = '', ignorePatterns = []) {
 // Local top-level-only extractor, behavior-aligned with lib/frontmatter.mjs:
 // skip indented / list lines, first-wins, strip a trailing `# comment`. Without
 // the comment strip a `failure_type: overreach # note` would aggregate under the
-// literal "overreach # note" key (FEAT-1). Kept local (not the shared import) to
-// hold stats' dependency surface flat per the FEAT-1 scope split.
+// literal "overreach # note" key. Kept local (not the shared import) to
+// hold stats' dependency surface flat per the scope split.
 function parseFrontmatter(content) {
   const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
   if (!m) return null;
@@ -101,7 +101,7 @@ const sources = existsSync(join(args.hypoDir, 'sources'))
   : [];
 
 const typeCounts = {};
-const failureTypeCounts = {}; // FEAT-1: feedback pages carrying a failure_type
+const failureTypeCounts = {}; // feedback pages carrying a failure_type
 let missingFrontmatter = 0;
 
 for (const f of pageFiles) {

package/scripts/uninstall.mjs

@@ -15,7 +15,7 @@
  *   --force-extensions   Remove user-modified extension files (hypo-ext-*) instead of preserving them
  *   --hooks-dir=<path>   Override Claude hooks directory (default: ~/.claude/hooks)
  *
- * Extensions (ADR 0024): hypo-ext-* hard-copies under
+ * Extensions: hypo-ext-* hard-copies under
  * ~/.claude/{hooks,commands,skills,agents}/ and ~/.codex/{hooks,commands}/ (with
  * --codex) are removed when their on-disk SHA matches the recorded one in
  * ~/.claude/hypo-pkg.json#extensions.<target>. User-modified copies are preserved
@@ -94,7 +94,7 @@ function removeCommands(apply, force) {
   return { removed, skippedUserModified, skippedNonRegular };
 }
 
-// ── extensions removal (ADR 0024) ───────────────────────────────────
+// ── extensions removal ───────────────────────────────────
 
 // Strip per-target extension SHA records from ~/.claude/hypo-pkg.json. Surgical:
 // we only touch the entries for keys we actually removed, so a `--force-extensions`
@@ -424,7 +424,7 @@ const hookResult = removeHookFiles(claudeHooksDir, hookFiles, args.apply);
 const settingsResult = stripSettingsJson(claudeSettings, claudeHooksDir, hookMap, args.apply);
 const commandResult = removeCommands(args.apply, args.forceCommands);
 
-// Extensions (ADR 0024). Order matters: remove files first, then strip
+// Extensions. Order matters: remove files first, then strip
 // settings, then surgically clear the per-target SHA map. The SHA strip uses
 // removedKeys so a user-modified file we left in place keeps its recorded SHA
 // (doctor still has a baseline next run). Settings are path-based and run even

package/scripts/upgrade.mjs

@@ -20,7 +20,7 @@
  *                       the user-extensions companion sync (E4).
  *   --json              Output results as JSON
  *   --allow-downgrade   Override the guard that refuses to overwrite a NEWER
- *                       active install with an older package (ADR 0038)
+ *                       active install with an older package
  *   --allow-dual-install  Override the dual-install guard: register the Claude core
  *                       surface even though the Hypomnema plugin is also enabled
  *                       (knowingly accept the double-registration risk)
@@ -235,7 +235,7 @@ function checkSchemaVersion(hypoDir) {
 
 // Target-aware: the same core-hook integrity check runs against ~/.claude/hooks/
 // for the default claude target, and against ~/.codex/hooks/ when --codex is set
-// (ADR 0024). The function reads only — apply happens in applyHookFiles.
+// The function reads only (apply happens in applyHookFiles).
 function checkHookFiles(hooksDir) {
   const results = [];
 
@@ -473,15 +473,15 @@ function writeMigrationReport(hypoDir, fromVersion, toVersion, { pluginMode = fa
   // Don't overwrite an existing report
   if (existsSync(dest)) return dest;
 
-  // v1 → v2 specific guidance for the ADR 0031 feedback classification bump.
-  // Other major jumps fall back to the generic body. ADR 0034 reserves the
-  // right to keep SCHEMA.md as user-owned (Option C); auto-stub of the 9 new
-  // fields is rejected because scope/tier/targets/sensitivity/reason/source
-  // are semantic decisions whose wrong defaults would project wrong behavior.
-  // Fire for any 1.x → 2.x major crossing, not just 1.0 → 2.0 exactly: the ADR
-  // 0031 feedback-field backfill that this body explains was introduced at 2.0
+  // v1 → v2 specific guidance for the feedback classification bump. Other major
+  // jumps fall back to the generic body. The schema deliberately keeps SCHEMA.md
+  // user-owned (Option C); auto-stub of the 9 new fields is rejected because
+  // scope/tier/targets/sensitivity/reason/source are semantic decisions whose
+  // wrong defaults would project wrong behavior.
+  // Fire for any 1.x → 2.x major crossing, not just 1.0 → 2.0 exactly: the
+  // feedback-field backfill that this body explains was introduced at 2.0
   // and still applies to a user landing on any later 2.x (e.g. 2.1's additive
-  // failure_type — FEAT-1). Keying on the exact target string would silently
+  // failure_type). Keying on the exact target string would silently
   // drop this guidance the moment the template minor moves.
   const fromV = parseVersion(fromVersion);
   const toV = parseVersion(toVersion);
@@ -489,8 +489,7 @@ function writeMigrationReport(hypoDir, fromVersion, toVersion, { pluginMode = fa
   const specificBody = isV1ToV2
     ? `## What changed in SCHEMA 2.0
 
-ADR 0031 (\`projects/hypomnema/decisions/0031-feedback-as-sot-external-memory-projection.md\`)
-made \`feedback\` pages the single source of truth for behavior corrections and added
+This release made \`feedback\` pages the single source of truth for behavior corrections and added
 **9 hard-required frontmatter fields** for every \`feedback\` page:
 
 - \`status\` (active | superseded | archived)
@@ -510,8 +509,8 @@ that does not satisfy all four is rejected by both \`hypomnema lint\` and
 \`hypomnema feedback\` (see \`scripts/lint.mjs\` and \`scripts/feedback.mjs\`
 enforcement).
 
-ADR 0034 records this schema bump and the reasoning (semver-major because
-existing feedback pages without these fields now fail \`hypomnema lint\`).
+This schema bump is semver-major because existing feedback pages without these
+fields now fail \`hypomnema lint\`.
 
 ## Action items — existing wiki
 
@@ -799,7 +798,7 @@ function writePluginModeMetadata() {
 const args = parseArgs(process.argv);
 
 // Target paths. Claude is always checked; codex is checked only when --codex is set
-// (ADR 0024) so users without codex installed see no false drift.
+// so users without codex installed see no false drift.
 const claudeHooksDir = join(HOME, '.claude', 'hooks');
 const claudeSettingsPath = join(HOME, '.claude', 'settings.json');
 const codexHooksDir = join(HOME, '.codex', 'hooks');
@@ -858,7 +857,7 @@ const hooksCodex = args.codex ? checkHookFiles(codexHooksDir) : null;
 const settingsCodex = args.codex ? checkSettingsJson(codexSettingsPath, codexHooksDir) : null;
 const oldHookRefsCodex = args.codex ? checkOldHookNames(codexSettingsPath) : null;
 
-// Extensions companion (ADR 0024). Read-only check; the apply
+// Extensions companion. Read-only check; the apply
 // happens below, AFTER applyCommands, so the per-target SHA map merges into the
 // hypo-pkg.json that applyCommands writes (rather than being clobbered by it).
 const extSettingsPath = claudeSettingsPath;
@@ -935,7 +934,7 @@ let appliedExtensions = null;
 let appliedExtensionsCodex = null;
 
 if (args.apply) {
-  // Downgrade guard (ADR 0038, P): an `--apply` from an OLDER package than the
+  // Downgrade guard: an `--apply` from an OLDER package than the
   // active install would overwrite newer hooks (upgrade.mjs:287 copyFileSync) and
   // rewrite hypo-pkg.json to the older version. Refuse before the first mutation.
   // A dev workspace re-running its own --apply (incl. the post-commit sync hook)
@@ -1370,7 +1369,7 @@ if (hypoignore.status === 'no-file') {
   for (const e of hypoignore.missing) lines.push(`    + ${e.pattern}`);
 }
 
-// Extensions companion (ADR 0024; conflict/drift gating E3, #31). Shared by the
+// Extensions companion (conflict/drift gating E3, #31). Shared by the
 // claude target and, under --codex, the codex target (E4, #32) — the label keeps
 // the two blocks distinguishable in the report.
 function pushExtSummary(check, label) {

package/skills/crystallize/SKILL.md

@@ -11,14 +11,14 @@ When invoked to close a session — via an explicit close signal ("세션 종료
 
 ## What this does
 
-- **Close mode**: walks the checklist (session-state, project hot.md, root hot.md, session-log, open-questions(변경 시), log.md) plus a lint step, then writes via `crystallize.mjs --apply-session-close --payload=<path>` — which runs the lint gate automatically, **scoped to the files it writes** (debt elsewhere is a non-blocking notice). `--check-session-close` is a read-only dry-run of the **full** PreCompact gate (ADR 0046) — close files + scoped lint + design-history + feedback projection — sharing one function (`precompactGateStatus`) with the gate. A green check means no gate blocker needs a human fix, so it is the signal to declare the session closed (pass `--transcript-path` to widen the lint scope to this session's edited files exactly as the interactive hook does). It is not a hard guarantee: the live `/compact` can still differ on a context-≥70% prompt, `HYPO_SKIP_GATE`, or a transcript-scoped lint error the check did not see.
+- **Close mode**: walks the checklist (session-state, project hot.md, root hot.md, session-log, open-questions(변경 시), log.md) plus a lint step, then writes via `/hypo:crystallize` in `--apply-session-close --payload=<path>` mode — which runs the lint gate automatically, **scoped to the files it writes** (debt elsewhere is a non-blocking notice). `--check-session-close` is a read-only dry-run of the **full** PreCompact gate: close files + scoped lint + design-history + feedback projection, sharing one function (`precompactGateStatus`) with the gate. A green check means no gate blocker needs a human fix, so it is the signal to declare the session closed (pass `--transcript-path` to widen the lint scope to this session's edited files exactly as the interactive hook does). It is not a hard guarantee: the live `/compact` can still differ on a context-≥70% prompt, `HYPO_SKIP_GATE`, or a transcript-scoped lint error the check did not see.
 - **Synthesis mode**: finds tag clusters (≥ N pages), orphan pages (no outbound `[[wikilinks]]`), and draft / stub pages, then guides consolidation into `pages/syntheses/<topic>.md` with back-links and `index.md` updates.
 
 ---
 
 ## Step 1 — Locate package root
 
-Locate the Hypomnema package root (the directory two levels above this file (`skills/<name>/SKILL.md` → package root)).
+Bundled scripts here run via `${CLAUDE_PLUGIN_ROOT}/scripts/`. To resolve that package root: if `${CLAUDE_PLUGIN_ROOT}` is already an absolute path, use it; otherwise read `pkgRoot` from `~/.claude/hypo-pkg.json` (only when non-empty and the target script exists under it); otherwise use the `hypo@hypomnema` (or legacy `hypomnema@hypomnema`) installPath in `~/.claude/plugins/installed_plugins.json`; if none resolve, stop and tell the user to run `hypomnema upgrade --apply` or reinstall instead of guessing the cache layout.
 
 If the user specified a wiki directory, pass it as `--wiki-dir="<path>"`. Otherwise omit the flag and the script resolves the wiki root automatically via `HYPO_DIR` → `hypo-config.md` scan → `~/hypomnema`.
 
@@ -27,7 +27,7 @@ If the user specified a wiki directory, pass it as `--wiki-dir="<path>"`. Otherw
 ## Step 2 — Run crystallize scan
 
 ```bash
-node <package-root>/scripts/crystallize.mjs \
+node ${CLAUDE_PLUGIN_ROOT}/scripts/crystallize.mjs \
   [--wiki-dir="<path>"] \
   [--min-group=<n>] \
   [--json]
@@ -47,7 +47,7 @@ If `/hypo:crystallize` was invoked as a session-close action, run through this c
 
 ### Advisory reflections (run before the checklist below — advisory only)
 
-Surface each of these four to the user first. Every one is **advisory** (ADR 0029 identity guard): the user confirms or declines, and none performs an automatic action, writes a file on its own, or bypasses the mandatory gate.
+Surface each of these four to the user first. Every one is **advisory** (identity guard): the user confirms or declines, and none performs an automatic action, writes a file on its own, or bypasses the mandatory gate.
 
 - **Trivial-session check (#44)** — Was this session trivial (a single bug fix, a single-file edit, or Q&A with no durable artifact)? If so, recommend skipping session-close: *"이 세션은 trivial해 보입니다 — session-close를 건너뛸까요?"* A trivial skip is a recommendation, **not** a bypass: it must not mark the session closed, must not run `--mark-session-closed`, and must not claim `/compact` can pass. Any real close still requires all 5 mandatory files.
 - **ADR-candidate check (#41)** — Did this session make an architectural or design decision (a new pattern, a tradeoff, a convention)? If yes, ask whether it warrants an ADR and capture that intent in the session-log entry. If nothing rose to ADR level, you may record the literal marker `ADR 없음 — <one-line reason>` in that same session-log entry — but gate it on #42's bar, not this one: the marker is machine-read and W8 treats a session-log entry carrying `ADR 없음` (and no ADR reference) as a *no-design* session, excluding it from the design-history staleness check. So write `ADR 없음` only when the session had no design change at all. If it had a sub-ADR design shift (background / tradeoff / differentiation), append to design-history (#42a) instead — writing the marker there would suppress the W8 nudge that shift needs. **Never auto-write an ADR file** — the session-log note is the only action here.
@@ -67,11 +67,11 @@ When uncertain, surface the question rather than skip it. None of the four block
 After completing the checklist, verify it before reporting:
 
 ```bash
-node <package-root>/scripts/crystallize.mjs --check-session-close [--hypo-dir="<path>"]
+node ${CLAUDE_PLUGIN_ROOT}/scripts/crystallize.mjs --check-session-close [--hypo-dir="<path>"]
 ```
 
-This runs the **full** PreCompact gate via the shared `precompactGateStatus`
-(ADR 0046): close files (`missing` / `stale`) plus lint blockers, stale
+This runs the **full** PreCompact gate via the shared `precompactGateStatus`:
+close files (`missing` / `stale`) plus lint blockers, stale
 design-history, and feedback projection over-cap/conflict. Fix every `✗` it
 reports and re-run until it prints **"Compact-ready"** — that is the signal the
 session is closed. A close-files-only pass is not enough; the real `/compact`

package/skills/graph/SKILL.md

@@ -14,7 +14,7 @@ You are running `/hypo:graph`. Build a wikilink dependency graph from all pages
 
 ## Step 1 — Locate package root
 
-Locate the Hypomnema package root (the directory two levels above this file (`skills/<name>/SKILL.md` → package root)).
+Bundled scripts here run via `${CLAUDE_PLUGIN_ROOT}/scripts/`. To resolve that package root: if `${CLAUDE_PLUGIN_ROOT}` is already an absolute path, use it; otherwise read `pkgRoot` from `~/.claude/hypo-pkg.json` (only when non-empty and the target script exists under it); otherwise use the `hypo@hypomnema` (or legacy `hypomnema@hypomnema`) installPath in `~/.claude/plugins/installed_plugins.json`; if none resolve, stop and tell the user to run `hypomnema upgrade --apply` or reinstall instead of guessing the cache layout.
 
 If the user specified a wiki directory, pass it as `--wiki-dir="<path>"`. Otherwise omit the flag and the script resolves the wiki root automatically via `HYPO_DIR` → `hypo-config.md` scan → `~/hypomnema`.
 
@@ -37,7 +37,7 @@ Optionally ask:
 ## Step 3 — Run graph
 
 ```bash
-node <package-root>/scripts/graph.mjs \
+node ${CLAUDE_PLUGIN_ROOT}/scripts/graph.mjs \
   [--wiki-dir="<path>"] \
   [--format=json|mermaid|dot] \
   [--min-edges=<n>]

package/skills/ingest/SKILL.md

@@ -14,7 +14,7 @@ You are running `/hypo:ingest`. Add a new source document to `sources/` and crea
 
 ## Step 1 — Locate package root
 
-Locate the Hypomnema package root (the directory two levels above this file (`skills/<name>/SKILL.md` → package root)).
+Bundled scripts here run via `${CLAUDE_PLUGIN_ROOT}/scripts/`. To resolve that package root: if `${CLAUDE_PLUGIN_ROOT}` is already an absolute path, use it; otherwise read `pkgRoot` from `~/.claude/hypo-pkg.json` (only when non-empty and the target script exists under it); otherwise use the `hypo@hypomnema` (or legacy `hypomnema@hypomnema`) installPath in `~/.claude/plugins/installed_plugins.json`; if none resolve, stop and tell the user to run `hypomnema upgrade --apply` or reinstall instead of guessing the cache layout.
 
 If the user specified a wiki directory, pass it as `--hypo-dir="<path>"`. Otherwise omit the flag and the script resolves the wiki root automatically via `HYPO_DIR` → `hypo-config.md` scan → `~/hypomnema`.
 
@@ -23,7 +23,7 @@ If the user specified a wiki directory, pass it as `--hypo-dir="<path>"`. Otherw
 ## Step 2 — Run ingest status check
 
 ```bash
-node <package-root>/scripts/ingest.mjs [--hypo-dir="<path>"] [--json]
+node ${CLAUDE_PLUGIN_ROOT}/scripts/ingest.mjs [--hypo-dir="<path>"] [--json]
 ```
 
 Options:
@@ -40,13 +40,13 @@ Before touching any source content, refuse to ingest secrets (`.env`, SSH keys,
 1. **If the user provided a file path**, check it (use an absolute path):
 
    ```bash
-   node <package-root>/scripts/ingest.mjs [--hypo-dir="<path>"] --check="<absolute-input-path>"
+   node ${CLAUDE_PLUGIN_ROOT}/scripts/ingest.mjs [--hypo-dir="<path>"] --check="<absolute-input-path>"
    ```
 
 2. **Always** check the destination `sources/<slug>.<ext>`:
 
    ```bash
-   node <package-root>/scripts/ingest.mjs [--hypo-dir="<path>"] --check="sources/<slug>.<ext>"
+   node ${CLAUDE_PLUGIN_ROOT}/scripts/ingest.mjs [--hypo-dir="<path>"] --check="sources/<slug>.<ext>"
    ```
 
 If either command exits non-zero, **stop**: surface the `Refused: ...` message to the user and do not download, read, or save the source. The slug check matters because a user could rename a `.env` to an innocuous slug — the destination must still be blocked.

package/skills/lint/SKILL.md

@@ -16,7 +16,7 @@ You are running `/hypo:lint`. Validate all wiki pages for frontmatter correctnes
 
 ## Step 1 — Locate package root
 
-Locate the Hypomnema package root (the directory two levels above this file (`skills/<name>/SKILL.md` → package root)).
+Bundled scripts here run via `${CLAUDE_PLUGIN_ROOT}/scripts/`. To resolve that package root: if `${CLAUDE_PLUGIN_ROOT}` is already an absolute path, use it; otherwise read `pkgRoot` from `~/.claude/hypo-pkg.json` (only when non-empty and the target script exists under it); otherwise use the `hypo@hypomnema` (or legacy `hypomnema@hypomnema`) installPath in `~/.claude/plugins/installed_plugins.json`; if none resolve, stop and tell the user to run `hypomnema upgrade --apply` or reinstall instead of guessing the cache layout.
 
 If the user specified a wiki directory, pass it as `--wiki-dir="<path>"`. Otherwise omit the flag and the script resolves the wiki root automatically via `HYPO_DIR` → `hypo-config.md` scan → `~/hypomnema`.
 
@@ -25,7 +25,7 @@ If the user specified a wiki directory, pass it as `--wiki-dir="<path>"`. Otherw
 ## Step 2 — Run lint
 
 ```bash
-node <package-root>/scripts/lint.mjs [--wiki-dir="<path>"] [--json] [--fix]
+node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.mjs [--wiki-dir="<path>"] [--json] [--fix]
 ```
 
 Options:

package/skills/query/SKILL.md

@@ -14,7 +14,7 @@ You are running `/hypo:query`. Full-text search across all wiki pages and projec
 
 ## Step 1 — Locate package root
 
-Locate the Hypomnema package root (the directory two levels above this file (`skills/<name>/SKILL.md` → package root)).
+Bundled scripts here run via `${CLAUDE_PLUGIN_ROOT}/scripts/`. To resolve that package root: if `${CLAUDE_PLUGIN_ROOT}` is already an absolute path, use it; otherwise read `pkgRoot` from `~/.claude/hypo-pkg.json` (only when non-empty and the target script exists under it); otherwise use the `hypo@hypomnema` (or legacy `hypomnema@hypomnema`) installPath in `~/.claude/plugins/installed_plugins.json`; if none resolve, stop and tell the user to run `hypomnema upgrade --apply` or reinstall instead of guessing the cache layout.
 
 If the user specified a wiki directory, pass it as `--wiki-dir="<path>"`. Otherwise omit the flag and the script resolves the wiki root automatically via `HYPO_DIR` → `hypo-config.md` scan → `~/hypomnema`.
 
@@ -31,7 +31,7 @@ Use the search terms from the user's message. If no query was provided, ask:
 ## Step 3 — Run query
 
 ```bash
-node <package-root>/scripts/query.mjs \
+node ${CLAUDE_PLUGIN_ROOT}/scripts/query.mjs \
   --q="<search terms>" \
   [--wiki-dir="<path>"] \
   [--limit=<n>] \

package/skills/verify/SKILL.md

@@ -14,7 +14,7 @@ You are running `/hypo:verify`. Check all wiki pages for `verify_by` and `verify
 
 ## Step 1 — Locate package root
 
-Locate the Hypomnema package root (the directory two levels above this file (`skills/<name>/SKILL.md` → package root)).
+Bundled scripts here run via `${CLAUDE_PLUGIN_ROOT}/scripts/`. To resolve that package root: if `${CLAUDE_PLUGIN_ROOT}` is already an absolute path, use it; otherwise read `pkgRoot` from `~/.claude/hypo-pkg.json` (only when non-empty and the target script exists under it); otherwise use the `hypo@hypomnema` (or legacy `hypomnema@hypomnema`) installPath in `~/.claude/plugins/installed_plugins.json`; if none resolve, stop and tell the user to run `hypomnema upgrade --apply` or reinstall instead of guessing the cache layout.
 
 If the user specified a wiki directory, pass it as `--wiki-dir="<path>"`. Otherwise omit the flag and the script resolves the wiki root automatically via `HYPO_DIR` → `hypo-config.md` scan → `~/hypomnema`.
 
@@ -23,7 +23,7 @@ If the user specified a wiki directory, pass it as `--wiki-dir="<path>"`. Otherw
 ## Step 2 — Run verify
 
 ```bash
-node <package-root>/scripts/verify.mjs \
+node ${CLAUDE_PLUGIN_ROOT}/scripts/verify.mjs \
   [--wiki-dir="<path>"] \
   [--file="<path>"] \
   [--json]

package/templates/SCHEMA.md

@@ -96,7 +96,7 @@ verify_by: <question to re-check at next review>
 verify_by_date: YYYY-MM-DD
 ```
 
-### 3.1. `feedback` type — projection fields (ADR 0031)
+### 3.1. `feedback` type — projection fields
 
 Feedback pages are the single source of truth for behavior corrections;
 `hypomnema feedback-sync` projects them one-way into Claude Code's `MEMORY.md`

package/templates/hypo-config.md

@@ -1,7 +1,7 @@
 ---
 title: Hypomnema Config
 type: config
-version: "1.4.2"
+version: "1.5.0"
 created: YYYY-MM-DD
 ---
 

package/templates/hypo-guide.md

@@ -67,7 +67,7 @@ Trigger: explicit close mention, `/compact` request, or context limit approachin
 
 **Auto-trigger rule**: when the user sends a natural-language close signal — "세션 마무리하자", "오늘 여기까지", "이만 종료", "wrap up", "signing off", or equivalent — run the session close checklist immediately without waiting for an explicit `/compact` or `/hypo:crystallize`. If the intent is ambiguous, confirm with a single question before proceeding.
 
-**Proactive close offer** (ADR 0022 Layer 1): even when the user gives no close signal, offer to wrap up once a task is truly done — don't make them remember to. Fire `AskUserQuestion` **at the end of the assistant turn in which you report a task complete or verified**, when both hold:
+**Proactive close offer** (Layer 1): even when the user gives no close signal, offer to wrap up once a task is truly done — don't make them remember to. Fire `AskUserQuestion` **at the end of the assistant turn in which you report a task complete or verified**, when both hold:
 
 1. The session did substantial work — file mutations or multi-step changes, not Q&A only.
 2. The current user request did not already include a next task or tell you not to close.
@@ -82,13 +82,13 @@ Ask: *"이 작업이 마무리되었나요? 세션을 정리(crystallize)할까
 2. Update `projects/<name>/hot.md` (what was done, ≤500 words, overwrite)
 3. Append to `projects/<name>/session-log/YYYY-MM-DD.md` (daily shard, narrative entry, append-only)
 4. Update root `hot.md` pointer table + date
-5. Run `scripts/lint.mjs` and fix errors in files **you** touched — debt in other
+5. Run `/hypo:lint` and fix errors in files **you** touched — debt in other
    projects / shared pages you did not author is reported as a non-blocking
-   notice, not a gate. (The documented `crystallize.mjs --apply-session-close`
-   path runs this lint automatically, scoped to the files it writes.)
-6. Verify with `scripts/crystallize.mjs --check-session-close`: a dry-run of the
+   notice, not a gate. (The documented `/hypo:crystallize` session-close path
+   runs this lint automatically, scoped to the files it writes.)
+6. Verify with `/hypo:crystallize` in its `--check-session-close` mode: a dry-run of the
    **full** PreCompact gate (close files + lint + design-history + feedback
-   projection, ADR 0046), sharing one function with the gate. Only declare the
+   projection), sharing one function with the gate. Only declare the
    session closed once it prints **"Compact-ready"**. A "close files updated"
    check alone is not enough — the real `/compact` gate also blocks on a lint
    error in a close file or a feedback projection over-cap. (Not a hard
@@ -99,13 +99,13 @@ Ask: *"이 작업이 마무리되었나요? 세션을 정리(crystallize)할까
    diagnostic, JSON `scope: "project"`): green there means only that slug is
    close-complete, **not** that `/compact` is globally unblocked. Use the plain
    check for the go/no-go signal.
-7. Record the session-closed marker (ADR 0047). The Stop hook blocks until this
+7. Record the session-closed marker. The Stop hook blocks until this
    session's per-session marker exists, and a hand-edit close (writing the files
    directly + committing) never writes it; the marker is written only by the
-   crystallize writer, never by the hook (ADR 0022 bypass guard). Normal path:
-   close via `crystallize.mjs --apply-session-close --session-id=<id> --transcript-path=<path>`,
+   crystallize writer, never by the hook (bypass guard). Normal path:
+   close via `/hypo:crystallize` (`--apply-session-close --session-id=<id> --transcript-path=<path>`),
    which writes the marker once the gate is green. Hand-edit recovery: after
-   committing the files, run `crystallize.mjs --mark-session-closed --session-id=<id> --transcript-path=<path>`.
+   committing the files, run `/hypo:crystallize` (`--mark-session-closed --session-id=<id> --transcript-path=<path>`).
    Both writers gate the marker on the SAME `precompactGateStatus` as `/compact`,
    so the marker only lands when step 6 would print **"Compact-ready"**.
 
@@ -153,7 +153,7 @@ projects/<name>/
 
 Add to root `hot.md` active projects table.
 
-#### Auto-project offer (ADR 0023)
+#### Auto-project offer
 
 When SessionStart / CwdChanged injects a line like
 `[WIKI: cwd '<name>'에 매칭되는 프로젝트가 없습니다. 자동 생성할까요? (Y/n)]`,
@@ -166,8 +166,14 @@ ignore it:**
 2. **On Yes** — run the scaffold helper once (it substitutes tokens, creates
    the project files, adds the root `hot.md` row, and logs the entry):
    ```
-   node <pkg-root>/scripts/lib/project-create.mjs --name <slug> --working-dir "$(pwd)"
+   node ${CLAUDE_PLUGIN_ROOT}/scripts/lib/project-create.mjs --name <slug> --working-dir "$(pwd)"
    ```
+   To resolve that package root from this guide: if `${CLAUDE_PLUGIN_ROOT}` is
+   already an absolute path, use it; otherwise read `pkgRoot` from
+   `~/.claude/hypo-pkg.json` (only when non-empty and the script exists under it);
+   otherwise use the `hypo@hypomnema` (or legacy `hypomnema@hypomnema`) installPath
+   in `~/.claude/plugins/installed_plugins.json`; if none resolve, stop and tell the
+   user to run `hypomnema upgrade --apply` or reinstall instead of guessing.
    Then tell the user: "Created project `<name>` at
    `~/hypomnema/projects/<name>/`. Edit `index.md` to refine." Do **not** hand-write
    the five files — the helper keeps substitution and registration consistent.
@@ -229,8 +235,8 @@ Hypomnema v1.1.0 ships an **autonomy score** so you can see whether the wiki is
   - `staleness-skip` — session older than the audit window (default 30d)
 - **Where it lives:**
   - Per-session transcript index: `<hypo-root>/.cache/sessions/index.jsonl` (written by the Stop hook `hypo-session-record.mjs`).
-  - Fallback source: `~/.claude/projects/<encoded>/*.jsonl` (used when the index is empty — see ADR 0019 if present in your wiki).
-  - Reports: `journal/weekly/<YYYY-Www>.md` (spec §6.4 SoT), generated by `node scripts/weekly-report.mjs --write`.
+  - Fallback source: `~/.claude/projects/<encoded>/*.jsonl` (used when the index is empty).
+  - Reports: `journal/weekly/<YYYY-Www>.md` (spec §6.4 SoT), generated by the `/hypo:audit` weekly report flow.
 - **Definitions:** the 0% / 100% endpoints, the formal score sketch, and open questions live in `pages/observability/_index.md`.
 
 Use `/hypo:audit` for a quick read of recent sessions; pass `--write` to commit the weekly report into the wiki.

package/templates/projects/_template/hot.md

@@ -21,7 +21,7 @@ tags: [hot-cache, project]
 ## Key Decisions
 
 <!-- Brief pointers to important ADRs or design choices -->
-<!-- [[decisions/0001-topic]] — decision summary -->
+<!-- [[decisions/NNNN-topic]] — decision summary -->
 
 ## Blockers / Open Questions