hypomnema 1.7.0 → 1.7.2

package/hooks/version-check.mjs

@@ -385,6 +385,98 @@ export function markSiblingNotified(path, key) {
   }
 }
 
+// ── pkgRoot drift notice ────────────────────────────────────────────────────
+// Same notify-once shape as the sibling banner above, in a field of its own
+// (`pkgRootDriftNotifiedFor`) so the two never suppress each other — they are
+// unrelated tuples that happen to share this cache file.
+
+/** Has this exact (cached → self-location) pkgRoot-drift pair already been surfaced? */
+export function pkgRootDriftAlreadyNotified(cache, key) {
+  return Boolean(cache && cache.pkgRootDriftNotifiedFor === key);
+}
+
+/** Record that the pkgRoot-drift banner for `key` was shown (read-merge-write). */
+export function markPkgRootDriftNotified(path, key) {
+  try {
+    const cache = readCache(path) || {};
+    cache.pkgRootDriftNotifiedFor = key;
+    writeCacheAtomic(path, cache);
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * Clear a previously-recorded pkgRoot-drift mark once the drift is observed
+ * to be resolved (cache catches up with self-location again — status
+ * 'match'). Without this the mark is permanent: the SAME (cached →
+ * self-location) pair recurring later — e.g. hypo-pkg.json catches up, then a
+ * later plugin update or a manual edit drifts it right back to the identical
+ * pair — would stay silently suppressed forever, because only a DIFFERENT
+ * pair would ever produce a new key. Callers must NOT call this on status
+ * 'unknown' (self-location could not be resolved) — that would wrongly wipe a
+ * mark this session had no grounds to judge one way or the other. Read-merge-
+ * write, best-effort (a failure here just means the notice stays suppressed
+ * one extra cycle, never a crash).
+ */
+export function clearPkgRootDriftNotified(path) {
+  try {
+    const cache = readCache(path);
+    if (!cache || !('pkgRootDriftNotifiedFor' in cache)) return;
+    delete cache.pkgRootDriftNotifiedFor;
+    writeCacheAtomic(path, cache);
+  } catch {
+    /* best-effort */
+  }
+}
+
+// ── pkgRoot-null notice ─────────────────────────────────────────────────────
+// A DIFFERENT failure than drift above: drift only ever fires when
+// self-location resolved (PKG_ROOT is non-null, just disagreeing with the
+// cache). This one fires when PKG_ROOT itself resolved to null — self-location
+// failed AND no verified provenance sidecar covered it — the case where
+// PreCompact's lint/feedback calls silently no-op because they have no root to
+// shell scripts through. The two conditions can never both hold in the same
+// session (drift requires a non-null self-location), so there is no "which
+// wins" question in practice, but the two use separate cache fields regardless
+// so neither implementation depends on that being true forever.
+// Boolean (not a pair-key like drift) — the notified state is just "already
+// told them this session's install has no resolvable pkgRoot".
+
+/** Has the PKG_ROOT-null state already been surfaced since it last cleared? */
+export function pkgRootNullAlreadyNotified(cache) {
+  return Boolean(cache && cache.pkgRootNullNotified === true);
+}
+
+/** Record that the PKG_ROOT-null banner was shown (read-merge-write). */
+export function markPkgRootNullNotified(path) {
+  try {
+    const cache = readCache(path) || {};
+    cache.pkgRootNullNotified = true;
+    writeCacheAtomic(path, cache);
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * Clear a previously-recorded PKG_ROOT-null mark once PKG_ROOT resolves again
+ * (self-location or a verified provenance sidecar). Without this, a null state
+ * that resolves and then recurs later (e.g. the provenance sidecar's hash
+ * binding breaks again after a partial re-install) would stay silently
+ * suppressed forever. Read-merge-write, best-effort.
+ */
+export function clearPkgRootNullNotified(path) {
+  try {
+    const cache = readCache(path);
+    if (!cache || !('pkgRootNullNotified' in cache)) return;
+    delete cache.pkgRootNullNotified;
+    writeCacheAtomic(path, cache);
+  } catch {
+    /* best-effort */
+  }
+}
+
 /**
  * Shared one-line message for the init/upgrade downgrade guard (P). `op` is
  * 'init' or 'upgrade'. Kept here so guard text stays identical across both CLIs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hypomnema",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "description": "LLM-native personal wiki system for Claude Code",
   "type": "module",
   "license": "MIT",
@@ -33,12 +33,15 @@
     "scripts/lib/failure-type.mjs",
     "scripts/lib/feedback-scope.mjs",
     "scripts/lib/frontmatter.mjs",
+    "scripts/lib/git-hooks-dir.mjs",
     "scripts/lib/hypo-ignore.mjs",
     "scripts/lib/hypo-root.mjs",
     "scripts/lib/page-usage.mjs",
     "scripts/lib/pkg-json.mjs",
+    "scripts/lib/pkg-provenance.mjs",
     "scripts/lib/plugin-detect.mjs",
     "scripts/lib/project-create.mjs",
+    "scripts/lib/rename-marker.mjs",
     "scripts/lib/schema-vocab.mjs",
     "scripts/lib/template-schema-version.mjs",
     "scripts/lib/wd-match.mjs",

package/scripts/crystallize.mjs

@@ -73,6 +73,9 @@ import {
   mkdirSync,
   renameSync,
   realpathSync,
+  openSync,
+  writeSync,
+  closeSync,
 } from 'fs';
 import { join, dirname } from 'path';
 import { spawnSync } from 'child_process';
@@ -81,7 +84,7 @@ import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
 import { loadHypoIgnore } from './lib/hypo-ignore.mjs';
 import { collectPagesCrystallize, extractWikilinks } from './lib/wikilink.mjs';
 import { aggregateColdCandidates } from './lib/page-usage.mjs';
-import { isValidProjectName } from './lib/project-create.mjs';
+import { isValidProjectName, substituteTokens, TEMPLATE_DIR } from './lib/project-create.mjs';
 import { appendPendingTags, checkForbidden } from './lib/schema-vocab.mjs';
 import {
   sessionCloseFileStatus,
@@ -101,6 +104,7 @@ import {
   resolveTranscriptBySessionId,
   hasUserCloseSignal,
   commitWikiChanges,
+  vaultCommitLockTarget,
   currentDevice,
   scopeVisible,
   readVisibilityScope,
@@ -905,6 +909,70 @@ function verifyCloseAuthority(sessionId) {
   return { ok: true };
 }
 
+// A-1 (project index lifecycle): seed projects/<project>/index.md from the
+// template the first time this project closes without one. SCHEMA.md declares
+// project-index at projects/*/index.md and templates/projects/_template/ ships
+// one, but createProject (the auto-project-offer path) is the only writer of
+// it today — a project directory created any other way (a manual mkdir, an
+// older vault, direct Write tool calls) never gets one. Idempotent: an
+// existing index.md is left untouched; this only fills the gap, and only the
+// three tokens the template defines are substituted — the rest (one-line
+// description, Progress checklist) stays human-authored prose exactly as
+// createProject already leaves it.
+//
+// `working_dir` has no authoritative source in this flow: apply never
+// receives the session's cwd (see hooks/hypo-shared.mjs's precompactGateStatus
+// doc — process.cwd() is explicitly non-authoritative here, since it reflects
+// this script's own launch directory, not the session's). It is left EMPTY,
+// not filled with a placeholder string: hooks/hypo-shared.mjs's collector
+// (collectProjectWorkingDirs) and findBackfillCandidate both treat any truthy
+// `working_dir` as "already anchored" and stop offering to backfill the real
+// cwd — a fake placeholder is truthy, so it would silently and permanently
+// swallow the exact anchor-recovery path a human would otherwise get. Empty
+// stays falsy there, so the project surfaces as a genuine backfill candidate
+// until a person (or the auto-project-offer flow) fills in a real path. The
+// key itself stays present in the frontmatter (substituted to an empty value,
+// not omitted) so the shape matches every other index.md and a human sees
+// exactly where to type the answer.
+// "Never overwrite an existing index" is this feature's explicit contract, so
+// creation uses an EXCLUSIVE create (`wx`), not the existsSync-then-atomicWrite
+// shape every other target in this file uses. atomicWrite's tmp+rename
+// replaces whatever sits at `dest` the instant rename fires — existing or not —
+// so a plain `if (existsSync(dest)) return null` beforehand only narrows the
+// race, it does not close it: another writer (a human, or a concurrent close)
+// can land real bytes at `dest` between that check and this function's rename.
+// `wx` makes the OS do the check-and-create atomically, mirroring
+// hooks/base-store.mjs's snapshotBase (`openSync(path, 'wx')` + EEXIST ==
+// "someone already got there, leave it"). No tmp+rename is needed here: unlike
+// atomicWrite's use case (replacing bytes a reader might already be mid-read
+// of), a `wx` create can never observably tear — the file either doesn't
+// exist yet (nothing to tear) or the open fails outright.
+export function ensureProjectIndex(hypoDir, project, relPath, today) {
+  const dest = join(hypoDir, relPath);
+  const src = join(TEMPLATE_DIR, 'index.md');
+  if (!existsSync(src)) return null; // template missing — nothing to scaffold from
+  const content = substituteTokens(readFileSync(src, 'utf-8'), {
+    name: project,
+    started: today,
+    workingDir: '',
+    today,
+  });
+  mkdirSync(dirname(dest), { recursive: true });
+  let fd;
+  try {
+    fd = openSync(dest, 'wx');
+  } catch (e) {
+    if (e && e.code === 'EEXIST') return null; // another writer already created it
+    throw e;
+  }
+  try {
+    writeSync(fd, content);
+  } finally {
+    closeSync(fd);
+  }
+  return relPath;
+}
+
 function applySessionClose(args) {
   // Option D: early-exit fires only when NO payload was supplied.
   // Rationale: payload presence is explicit close intent and must always run
@@ -1185,6 +1253,11 @@ function applySessionClose(args) {
   // normalization, so it must use the OS-native separator the sibling entries use.
   const sessionLogWriteTarget = join('projects', project, 'session-log', `${date}.md`);
   const sessionLogEvidence = join(...sessionLogScopePath(args.hypoDir, project, date).split('/'));
+  // A-1: known here (read-only check, no write yet) so a freshly-scaffolded
+  // index.md is scoped to THIS close's own payloadScope below, rather than
+  // showing up as an unrelated pre-existing-content notice.
+  const indexRelPath = join('projects', project, 'index.md');
+  const indexMissing = !existsSync(join(args.hypoDir, indexRelPath));
   const payloadScope = new Set([
     join('projects', project, 'session-state.md'),
     join('projects', project, 'hot.md'),
@@ -1193,6 +1266,7 @@ function applySessionClose(args) {
     sessionLogEvidence, // == write target, except a hybrid-month monthly fallback
     'log.md',
     ...(payload.openQuestions ? [join('pages', 'open-questions.md')] : []),
+    ...(indexMissing ? [indexRelPath] : []),
   ]);
 
   let preflightLint;
@@ -1229,6 +1303,12 @@ function applySessionClose(args) {
 
   const applied = [];
   const skipped = [];
+  // The ACTUAL vault-relative paths this apply wrote, kept separate
+  // from `applied` (whose entries are display strings like `key (relPath)`,
+  // not bare paths). This is the scope handed to commitWikiChanges below;
+  // never the broader `payloadScope` above, which also includes lint/evidence
+  // candidates this apply may not have written a byte to.
+  const appliedPaths = [];
   // Overwrite targets this apply refused to write because the page moved under
   // it. T6 turns these into `.cache/proposals/` artifacts; here they are already
   // enough to withhold the bytes and fail the close.
@@ -1286,6 +1366,7 @@ function applySessionClose(args) {
     if (args.sessionId)
       advanceBase(args.hypoDir, args.sessionId, relPath, hashContent(field.content));
     applied.push(`${key} (${relPath})`);
+    appliedPaths.push(relPath);
   };
 
   overwrite('sessionState', join('projects', project, 'session-state.md'), payload.sessionState);
@@ -1293,6 +1374,17 @@ function applySessionClose(args) {
   overwrite('rootHot', 'hot.md', payload.rootHot);
   overwrite('openQuestions', join('pages', 'open-questions.md'), payload.openQuestions);
 
+  // A-1: fill a missing project index as part of this close's writes (after
+  // preflight passed, so an aborted close never leaves a half-applied side
+  // effect on disk).
+  if (indexMissing) {
+    const createdIndex = ensureProjectIndex(args.hypoDir, project, indexRelPath, date);
+    if (createdIndex) {
+      applied.push(`projectIndex (${createdIndex})`);
+      appliedPaths.push(createdIndex);
+    }
+  }
+
   // Append idempotency: dedup by exact-entry presence, not by "any heading
   // dated today". The freshness gate (sessionCloseFileStatus) is what answers
   // "was this file touched today?"; that's a different concern and must not
@@ -1368,6 +1460,7 @@ function applySessionClose(args) {
         { timeoutMs: APPEND_LOCK_TIMEOUT_MS },
       );
       (outcome === 'skipped' ? skipped : applied).push(`sessionLog (${rel})`);
+      if (outcome !== 'skipped') appliedPaths.push(rel);
     } catch (err) {
       // Only a lock-TIMEOUT is withheld as a conflict. A real fn() write error
       // (disk-full, EACCES, mkdir failure) must NOT be masked as a proposal-
@@ -1419,6 +1512,7 @@ function applySessionClose(args) {
         { timeoutMs: APPEND_LOCK_TIMEOUT_MS },
       );
       (wrote ? applied : skipped).push('log (log.md)');
+      if (wrote) appliedPaths.push('log.md');
     } catch (err) {
       if (err?.code !== 'ELOCKTIMEOUT') throw err;
       // proposedContent is append-ready root-log bytes (the custom log line).
@@ -1455,6 +1549,7 @@ function applySessionClose(args) {
         { timeoutMs: APPEND_LOCK_TIMEOUT_MS },
       );
       (wroteAny ? applied : skipped).push('log (log.md, derived)');
+      if (wroteAny) appliedPaths.push('log.md');
     } catch (err) {
       if (err?.code !== 'ELOCKTIMEOUT') throw err;
       // `derived: true` discriminates this from the payload.log conflict above:
@@ -1646,7 +1741,22 @@ function applySessionClose(args) {
     // user-close signal ONLY once the gate passes. planMarkerDecision owns the
     // branch priority + reason strings; the booleans below are computed in that
     // same short-circuiting order so no read runs earlier than it does today.
-    const commitOutcome = commitWikiChanges(args.hypoDir);
+    // Scope this commit to the paths THIS apply actually wrote
+    // (appliedPaths), never the broader payloadScope, which also
+    // names lint/evidence candidates apply may not have touched a byte of.
+    // Locked against the SAME target the auto-commit Stop hook holds, so a
+    // concurrent Stop-chain commit on this vault can't interleave with this
+    // apply's stage+commit. A lock-timeout is treated exactly like any other
+    // commit failure below (skip the marker, surface the reason) rather than
+    // crashing the apply.
+    let commitOutcome;
+    try {
+      commitOutcome = withFileLock(vaultCommitLockTarget(args.hypoDir), () =>
+        commitWikiChanges(args.hypoDir, appliedPaths),
+      );
+    } catch (err) {
+      commitOutcome = { committed: false, reason: `vault-commit-lock: ${err?.message || err}` };
+    }
     let closeTranscript = null;
     let gateOk = false;
     if (commitOutcome.committed) {