hypomnema 1.7.2 → 1.7.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hypomnema",
-  "version": "1.7.2",
+  "version": "1.7.4",
   "description": "LLM-native personal wiki system for Claude Code",
   "type": "module",
   "license": "MIT",
@@ -43,6 +43,7 @@
     "scripts/lib/project-create.mjs",
     "scripts/lib/rename-marker.mjs",
     "scripts/lib/schema-vocab.mjs",
+    "scripts/lib/slug-resolver.mjs",
     "scripts/lib/template-schema-version.mjs",
     "scripts/lib/wd-match.mjs",
     "scripts/lib/wikilink.mjs",

package/scripts/capture.mjs

@@ -42,9 +42,11 @@ import {
   unlinkSync,
   renameSync,
   realpathSync,
-  lstatSync,
   openSync,
   closeSync,
+  statSync,
+  fstatSync,
+  fchmodSync,
 } from 'fs';
 import { randomBytes } from 'crypto';
 import { join, dirname, relative, sep } from 'path';
@@ -76,6 +78,7 @@ import {
   HOOK_EVENT_ALLOWLIST,
   SKILL_ROOT_FILE,
   EXT_PREFIX,
+  withSrcExecBits,
 } from './lib/extensions.mjs';
 import { readCoreHooksConfig, deriveCoreHookBasenames } from './lib/core-hooks.mjs';
 
@@ -582,11 +585,29 @@ function log(msg) {
 // `${dest}.tmp.${pid}` name was predictable, and writeFileSync on a path someone had
 // already planted a symlink at would follow it straight out of the wiki. O_EXCL fails
 // on an existing path of any kind, symlink included.
-function writeAtomic(dest, buf) {
+// `srcMode`, when given, carries the source file's execute bit onto the wiki
+// copy (openSync's own mode argument is clipped by umask same as writeFileSync,
+// so this still has to be a separate chmod). Omitted for a manifest write: that
+// content is JSON we generated, not a copy of something with a mode worth
+// keeping.
+//
+// The mode is set on the open FD (`fchmodSync`), before the FD is closed, the
+// same ordering the forward writer (extensions.mjs's writeFreshAtomic) already
+// uses. A pathname-based `chmodSync(tmp, ...)` run after `closeSync` reopens
+// `tmp` by name, and a competing process racing this write could have already
+// deleted `tmp` and planted a symlink at that name in the gap between close
+// and chmod — `wx` only protects the file's creation, not everything after it.
+// Chmod-ing the FD closes that window: it always addresses the file this
+// process itself just created, never whatever a symlink at the same name
+// might point to by the time the pathname is looked up again.
+function writeAtomic(dest, buf, srcMode) {
   const tmp = `${dest}.tmp.${process.pid}.${randomBytes(6).toString('hex')}`;
   const fd = openSync(tmp, 'wx');
   try {
     writeFileSync(fd, buf);
+    if (srcMode != null) {
+      fchmodSync(fd, withSrcExecBits(fstatSync(fd).mode, srcMode));
+    }
   } finally {
     closeSync(fd);
   }
@@ -719,7 +740,8 @@ function writeSkill({ rec, skillRoot, manifestPath, manifest, files, guard, wiki
         madeDirs.add(cur);
       }
     }
-    writeAtomic(destPath, readFileSync(f.srcPath));
+    const buf = readFileSync(f.srcPath);
+    writeAtomic(destPath, buf, statSync(f.srcPath).mode);
     rec.createdFiles.push(destPath);
   }
 }
@@ -814,22 +836,6 @@ function captureOneSkill({ c, extDir, guard, wikiRoot, args, captured, skipped,
     return;
   }
 
-  // Content round-trips; the executable bit does not (forward-sync writes with the
-  // default mode). Say so rather than let a captured `scripts/run.sh` arrive
-  // non-executable on the far machine without a word.
-  const execFiles = c.files.filter((f) => {
-    try {
-      return (lstatSync(f.srcPath).mode & 0o111) !== 0;
-    } catch {
-      return false;
-    }
-  });
-  if (execFiles.length > 0) {
-    log(
-      `! ${label}: ${execFiles.length} executable file(s) — content is captured, but the executable bit is not carried by sync`,
-    );
-  }
-
   if (!args.dryRun) {
     // The ledger is owned by the caller so a throw MID-write is still recoverable: the
     // paths created before the failure are already recorded in it.
@@ -1055,7 +1061,7 @@ function run(args, { claudeHome = join(HOME, '.claude') } = {}) {
         manifestPrevBuf: existingManifestBuf,
       };
       writeAtomic(manifestPath, JSON.stringify(plan.manifest, null, 2) + '\n');
-      writeAtomic(filePath, srcBuf);
+      writeAtomic(filePath, srcBuf, statSync(c.srcPath).mode);
       created.push(rec);
     }
     captured.push({ ...c, installFile, requiredKeys, status: 'ready' });

package/scripts/crystallize.mjs

@@ -102,16 +102,18 @@ import {
   hasSessionLogHeading,
   hasLogEntry,
   resolveTranscriptBySessionId,
-  hasUserCloseSignal,
+  isCloseGateOpen,
   commitWikiChanges,
   vaultCommitLockTarget,
   currentDevice,
   scopeVisible,
   readVisibilityScope,
   withFileLock,
+  extractTouchedWikiFilesWithTrust,
 } from '../hooks/hypo-shared.mjs';
 import { hashContent, readBaseEntry, advanceBase } from '../hooks/base-store.mjs';
 import { writeProposal } from '../hooks/proposal-store.mjs';
+import { recordGateClosed, resolutionStamp, closeGateStatus } from '../hooks/close-gate-store.mjs';
 
 // This script's own absolute path. Used to print copy-pasteable recovery
 // commands as `node <SELF_SCRIPT> ...` rather than a bare `crystallize` bin,
@@ -225,6 +227,35 @@ function requireProjectDir(args, slug) {
   }
 }
 
+// When the global gate's own discovery (hot.md pointer table + today
+// close-activity scan, both in hypo-shared.mjs) comes back with NO project at
+// all, a real apply never hits that dead end: it is handed `payload.project`
+// directly and never infers. --check-session-close has no payload, so its one
+// remaining authoritative signal is the same session's own transcript — which
+// project's files did THIS session actually touch. Reusing the exact
+// evidence-resolution helper the widened-lint-scope path already trusts here
+// keeps this a single inference vocabulary (touched wiki files), not a second
+// one: the difference is only which project-shaped question gets asked of it.
+// Never guessed: a transcript touching zero or more than one project's files
+// leaves the check exactly as unresolved as it was before this fallback.
+function deriveTouchedProject(hypoDir, transcriptPath) {
+  if (!transcriptPath) return null;
+  const { files, trusted } = extractTouchedWikiFilesWithTrust(transcriptPath, hypoDir);
+  // `trusted:false` means the walk itself may be incomplete (a missing/unreadable
+  // transcript, or a line that failed to parse). A truncated line could have named
+  // a SECOND project the walk never saw, so treating this Set as "the whole
+  // truth" would resolve a single-project reading off a scope that is only
+  // single-project because part of it is missing, exactly the ambiguity this
+  // fallback exists to refuse rather than guess through.
+  if (!trusted) return null;
+  const slugs = new Set();
+  for (const f of files) {
+    const m = /^projects\/([^/]+)\//.exec(f);
+    if (m && existsSync(join(hypoDir, 'projects', m[1]))) slugs.add(m[1]);
+  }
+  return slugs.size === 1 ? [...slugs][0] : null;
+}
+
 // ── session-close check (spec §5.2.7 / §8.3) ────────────────────────
 // Mirrors the hard gate in hypo-personal-check.mjs so the /hypo:crystallize
 // flow can self-verify before /compact triggers PreCompact.
@@ -261,7 +292,7 @@ function runSessionCloseCheck(args) {
     args.transcriptPath ||
     (args.sessionId ? resolveTranscriptBySessionId(args.sessionId) : null) ||
     null;
-  const status = precompactGateStatus(args.hypoDir, {
+  let status = precompactGateStatus(args.hypoDir, {
     ...(args.project
       ? { projectOverride: args.project }
       : checkTranscript
@@ -276,7 +307,30 @@ function runSessionCloseCheck(args) {
     // enforcement lives in the PreCompact/Stop hooks, which carry payload.cwd).
     ...(args.sessionCwd && !args.project ? { sessionCwd: args.sessionCwd } : {}),
   });
+
+  // check/apply divergence (2026-08-25 QA): a real apply never hits discovery
+  // dead-ends because payload.project is required input, not an inference. This
+  // check has no payload, so when discovery finds NO project at all (not even
+  // the recency fallback), it retries scoped to whatever single project this
+  // session's own transcript shows it touching. This is a diagnostic estimate,
+  // not a preview of what a real apply will do: a payload's `project` field is
+  // whatever the caller puts there and can legitimately name a project the
+  // transcript never mentions. Only fires on a fully unresolved global result,
+  // and only on a TRUSTED single-project reading (see deriveTouchedProject): an
+  // already-successful discovery, an ambiguous/empty transcript, or one the walk
+  // could not fully read is left untouched rather than guessed at.
+  let inferredProject = null;
+  if (!args.project && !status.close.project) {
+    inferredProject = deriveTouchedProject(args.hypoDir, checkTranscript);
+    if (inferredProject) {
+      status = precompactGateStatus(args.hypoDir, {
+        projectOverride: inferredProject,
+        ...(args.sessionId ? { sessionId: args.sessionId } : {}),
+      });
+    }
+  }
   const close = status.close;
+  const scopedProject = args.project || inferredProject;
 
   // When a --session-id is supplied, report whether THIS session's
   // per-session marker (the Stop-chain completion signal) exists. This is a
@@ -301,8 +355,8 @@ function runSessionCloseCheck(args) {
   // log-only marker governs the session, the gate runs in log-only mode and the
   // --project override is IGNORED — surface that rather than implying X was
   // checked (it was not).
-  const logOnlyWon = args.project != null && markerObj?.scope === 'log-only';
-  const scope = args.project ? (logOnlyWon ? 'log-only' : 'project') : 'global';
+  const logOnlyWon = scopedProject != null && markerObj?.scope === 'log-only';
+  const scope = scopedProject ? (logOnlyWon ? 'log-only' : 'project') : 'global';
 
   if (args.json) {
     console.log(
@@ -325,9 +379,13 @@ function runSessionCloseCheck(args) {
           skipped: status.skipped,
           // scope is additive; `global` keeps prior semantics for existing readers
           scope,
-          ...(args.project
+          ...(scopedProject
             ? {
-                scoped_project: args.project,
+                scoped_project: scopedProject,
+                // Distinguishes a user-typed --project from this check picking one
+                // for itself off the transcript — a reader should not mistake the
+                // latter for an explicit ask (see deriveTouchedProject above).
+                ...(inferredProject ? { project_inferred_from_transcript: true } : {}),
                 ...(logOnlyWon ? { project_override_ignored: true } : {}),
               }
             : {}),
@@ -340,13 +398,20 @@ function runSessionCloseCheck(args) {
     process.exit(status.ok ? 0 : 1);
   }
 
+  // Label the scoped project by how it was chosen — an explicit --project reads
+  // as a flag the caller typed; an inferred one reads as this check's own guess
+  // off the transcript, so a reader does not credit the caller with an ask
+  // nobody made.
+  const scopedProjectLabel = args.project
+    ? `--project=${args.project}`
+    : `project=${scopedProject} (inferred from the session transcript, no --project given)`;
   if (logOnlyWon) {
     console.log(
-      `Note: a log-only session-closed marker governs session ${args.sessionId}, so the gate ran in log-only mode and --project=${args.project} was IGNORED (no project was checked).\n`,
+      `Note: a log-only session-closed marker governs session ${args.sessionId}, so the gate ran in log-only mode and ${scopedProjectLabel} was IGNORED (no project was checked).\n`,
     );
   } else if (scope === 'project') {
     console.log(
-      `Note: --project=${args.project} — this is a PROJECT-SCOPED diagnostic, not the global /compact gate. A green result means only ${args.project} is close-complete; another project can still block /compact.\n`,
+      `Note: ${scopedProjectLabel} — this is a PROJECT-SCOPED diagnostic, not the global /compact gate. A green result means only ${scopedProject} is close-complete; another project can still block /compact.\n`,
     );
   }
 
@@ -398,8 +463,8 @@ function runSessionCloseCheck(args) {
     // Do NOT claim global compact-readiness (the whole point of the narrow).
     console.log(
       status.ok
-        ? `✓ ${args.project} is close-complete (project-scoped). This is NOT a global /compact guarantee — run \`--check-session-close\` without --project for that.`
-        : `✗ ${args.project} is not close-complete — resolve the ✗ items above.`,
+        ? `✓ ${scopedProject} is close-complete (project-scoped). This is NOT a global /compact guarantee — run \`--check-session-close\` without --project for that.`
+        : `✗ ${scopedProject} is not close-complete — resolve the ✗ items above.`,
     );
   } else {
     console.log(
@@ -686,7 +751,7 @@ function runMarkSessionClosed(args) {
   // /compact, or an AskUserQuestion close answer). This is the hard backstop for
   // model over-close, where prose guidance lost to a conflicting global rule.
   // Fail-closed when the transcript can't be resolved.
-  if (!closeTranscript || !hasUserCloseSignal(closeTranscript)) {
+  if (!closeTranscript || !isCloseGateOpen(closeTranscript)) {
     const reason = !closeTranscript
       ? `cannot resolve a transcript for session ${args.sessionId} — the session-closed marker requires a verifiable user close signal`
       : "no user close signal in this session's transcript — marker refused (the user did not signal session close)";
@@ -874,7 +939,7 @@ const CLOSE_REFUSAL_HELP = [
  *   { ok: false, reason, error }   reason: session-id-required | transcript-unresolved
  *                                          | no-user-close-signal
  */
-function verifyCloseAuthority(sessionId) {
+function verifyCloseAuthority(sessionId, hypoDir) {
   if (!sessionId) {
     return {
       ok: false,
@@ -897,13 +962,15 @@ function verifyCloseAuthority(sessionId) {
         `authority here.`,
     };
   }
-  if (!hasUserCloseSignal(transcript)) {
+  const gateStatus = closeGateStatus({ transcriptPath: transcript, hypoDir, sessionId });
+  if (!gateStatus.ok) {
     return {
       ok: false,
       reason: 'no-user-close-signal',
       error:
         "session-close apply refused before any wiki write or commit: this session's transcript " +
-        'carries no user close signal. The user did not ask to close.',
+        'carries no user close signal. The user did not ask to close. ' +
+        `Gate detail: ${gateStatus.reason}`,
     };
   }
   return { ok: true };
@@ -1036,14 +1103,19 @@ function applySessionClose(args) {
   // Only a payload-bearing call can write. A payload-less one falls through to the
   // "payload is required" error below without touching a byte, so gating it here
   // would just replace one refusal with a less accurate one.
-  const closeAuth = args.payload ? verifyCloseAuthority(args.sessionId) : { ok: true };
+  const closeAuth = args.payload
+    ? verifyCloseAuthority(args.sessionId, args.hypoDir)
+    : { ok: true };
   if (!closeAuth.ok) {
     const out = {
       ok: false,
       stage: 'no-user-close-signal',
       reason: closeAuth.reason,
       applied: [],
-      committed: false,
+      // `null`, not `false`: this refusal fires before the commit step is ever
+      // reached (see the general result's own `committed` contract below).
+      // `false` is reserved for a commit that actually ran and failed.
+      committed: null,
       error: closeAuth.error,
     };
     console.log(
@@ -1103,7 +1175,9 @@ function applySessionClose(args) {
       stage: 'session-id-mismatch',
       error: msg,
       applied: [],
-      committed: false,
+      // `null`, not `false` — refused before the commit step, same contract as
+      // the `no-user-close-signal` refusal above.
+      committed: null,
     };
     console.log(args.json ? JSON.stringify(out, null, 2) : `✗ ${msg}`);
     process.exit(1);
@@ -1734,7 +1808,44 @@ function applySessionClose(args) {
   // but silently.
   let markerWritten = false;
   let markerSkipReason = null;
+  // Hoisted so the result JSON below can report it: `null` when this apply never
+  // reached the commit step at all (ok:false before the writes were even
+  // verified), distinct from a commit that ran and reported `committed:false`.
+  let commitOutcome = null;
   if (ok && args.sessionId) {
+    // Close-gate resolution: apply succeeding (`ok`) IS the resolution, not
+    // whether the per-session marker below happens to land. The marker can
+    // be withheld for reasons that have nothing to do with whether this
+    // apply's own writes were valid (a stale git tree, a feedback-projection
+    // cap, W8 design-history staleness) — none of that should leave the
+    // resolution unrecorded, because the wiki writes already happened, and
+    // re-running the SAME apply with no fresh user close signal is exactly
+    // what this record exists to block. So this sits OUTSIDE and ahead of
+    // the marker's own commit-gated logic below, resolving its own
+    // transcript rather than sharing the marker's `closeTranscript` (which
+    // stays null whenever the commit fails) — a commit failure withholds
+    // the marker but must not also withhold the resolution.
+    //
+    // Best-effort like every other write in this store: resolutionStamp
+    // returns null on anything it cannot read as a Buffer, recordGateClosed
+    // refuses a null stamp, and both fail silently, so a transcript that
+    // vanishes mid-read (or a cache-write failure) can never turn an
+    // otherwise-successful apply into a failure.
+    try {
+      const resolutionTranscriptPath = resolveTranscriptBySessionId(args.sessionId);
+      if (resolutionTranscriptPath) {
+        recordGateClosed(
+          args.hypoDir,
+          args.sessionId,
+          resolutionStamp(readFileSync(resolutionTranscriptPath)),
+        );
+      }
+    } catch {
+      // Unreadable at the moment of a successful close is not this apply's
+      // problem to surface — the resolution just stays unrecorded, same as
+      // if this session had never resolved at all (NO_CONSTRAINT).
+    }
+
     // IO stays lazy so this preserves the exact side-effect order (codex design
     // review): commit first (the only mutation), then resolve the
     // transcript, then run the compact gate with that transcript, then scan the
@@ -1749,7 +1860,6 @@ function applySessionClose(args) {
     // 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),
@@ -1779,8 +1889,18 @@ function applySessionClose(args) {
       gateOk,
       transcriptResolved: !!closeTranscript,
       // Scan the signal only when the gate passed AND a transcript resolved —
-      // hasUserCloseSignal never runs earlier than the original nested `else if`.
-      hasUserSignal: gateOk && !!closeTranscript && hasUserCloseSignal(closeTranscript),
+      // isCloseGateOpen never runs earlier than the original nested `else if`.
+      // Reads the raw walkCloseGate open, not closeGateStatus: this apply's
+      // OWN recordGateClosed call above already ran with this transcript's
+      // full record count as closedAtIndex, and openedAtIndex can never reach
+      // or pass a count taken from the very same transcript (see
+      // closeGateStatus's doc comment) — so gating this diagnostic on .ok
+      // would read false on every apply, unconditionally, not just a stale
+      // one. This field asks a narrower question than closeGateStatus
+      // answers: "did the transcript carry a close signal", not "is this
+      // apply itself still authorized" (verifyCloseAuthority already settled
+      // that, before any byte was written).
+      hasUserSignal: gateOk && !!closeTranscript && isCloseGateOpen(closeTranscript),
     });
     markerSkipReason = decision.skipReason;
     if (decision.write) {
@@ -1843,6 +1963,19 @@ function applySessionClose(args) {
     date,
     applied,
     skipped,
+    // Was the general-shape sibling of the two early-refusal `committed:null`
+    // fields (no-user-close-signal / session-id-mismatch), which this path never
+    // carried before: a reader of `applied:[]` on a no-op re-run had no
+    // `committed` value to check against and no way to tell it apart from a run
+    // that never reached the commit step. `null` here means exactly that: `ok`
+    // came back false before the commit ever ran (see `stage` for which check
+    // failed: post-apply-verification, post-apply-lint, or proposal-pending). It
+    // does NOT mean nothing was written — an overwrite/append can already be on
+    // disk (see `applied` / `appliedUncommitted`) while `committed` stays `null`.
+    // `true` covers both an actual commit and the legitimate "nothing to stage"
+    // no-op (commitWikiChanges' own contract, see hooks/hypo-shared.mjs); `false`
+    // is a real commit failure, surfaced together with markerSkipReason below.
+    committed: commitOutcome ? commitOutcome.committed : null,
     // Targets withheld: an overwrite drifted from this session's observed base, or
     // an append could not take the file lock in time (`kind: 'append'`). Two
     // channels resolve these, and `proposals` vs `conflicts[].kind` are the sole

package/scripts/doctor.mjs

@@ -20,7 +20,7 @@ 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 { resolveGitHooksDir, WIKI_PRE_COMMIT_MARKER_START } from './lib/git-hooks-dir.mjs';
 import { parseFrontmatter } from './lib/frontmatter.mjs';
 import {
   readSyncState,
@@ -506,7 +506,7 @@ function checkGit(hypoDir) {
         ? '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')) {
+  } else if (content.includes(WIKI_PRE_COMMIT_MARKER_START)) {
     pass(label, 'Hypomnema .hypoignore guard installed');
   } else {
     warn(label, 'Exists but not managed by Hypomnema — manual git add can bypass .hypoignore');

package/scripts/init.mjs

@@ -38,7 +38,16 @@ import { execSync, spawnSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { createHash } from 'crypto';
 import { expandHome, resolveHypoRoot } from './lib/hypo-root.mjs';
-import { hooksDirForInstall, unsafeHookTargetReason } from './lib/git-hooks-dir.mjs';
+import {
+  hooksDirForInstall,
+  unsafeHookTargetReason,
+  findMarkerSpan,
+  WIKI_PRE_COMMIT_MARKER_START,
+  WIKI_PRE_COMMIT_MARKER_END,
+  SHELL_MARKER_START,
+  SHELL_MARKER_END,
+  SHELL_FUNCTION_BODY,
+} from './lib/git-hooks-dir.mjs';
 import { readCoreHooksConfig } from './lib/core-hooks.mjs';
 import {
   readPkgJson as readPkgJsonSafe,
@@ -748,9 +757,6 @@ function installPkgGitHook(dryRun) {
 
 // ── wiki pre-commit hook ─────────────────────────────────────────────────────
 
-const WIKI_PRE_COMMIT_MARKER_START = '# hypo-managed:pre-commit:start';
-const WIKI_PRE_COMMIT_MARKER_END = '# hypo-managed:pre-commit:end';
-
 // Single-quote escaping prevents shell expansion of special chars (e.g. $HOME, backticks) in path
 function shellSingleQuote(p) {
   return `'${p.replace(/'/g, "'\\''")}'`;
@@ -859,16 +865,13 @@ function installWikiPreCommitHook(hypoDir, dryRun, force, root, lintStrict) {
 
 // ── shell function setup ─────────────────────────────────────────────────────
 
-const SHELL_MARKER_START = '# hypo-managed:shell-setup:start';
-const SHELL_MARKER_END = '# hypo-managed:shell-setup:end';
-
+// Built FROM SHELL_FUNCTION_BODY (./lib/git-hooks-dir.mjs), not a second copy
+// of the same literal: uninstall's isOwnedShellFunctionBody() compares an
+// existing marker span's body against that same constant byte-for-byte, so
+// this and that check can never drift apart the way two independent string
+// literals could.
 function shellFunctionBlock() {
-  return `${SHELL_MARKER_START}
-function claude() {
-  echo "{\\"cwd\\":\\"$(pwd)\\"}" | node "$HOME/.claude/hooks/hypo-session-start.mjs" > /dev/null 2>&1
-  command claude "$@"
-}
-${SHELL_MARKER_END}`;
+  return `${SHELL_MARKER_START}${SHELL_FUNCTION_BODY}${SHELL_MARKER_END}`;
 }
 
 function detectShellConfig(customPath) {
@@ -891,19 +894,32 @@ function installShellFunction(shellConfigPath, dryRun) {
   }
 
   const content = readFileSync(shellConfigPath, 'utf-8');
-  const startIdx = content.indexOf(SHELL_MARKER_START);
-  const endIdx = content.indexOf(SHELL_MARKER_END);
 
-  if (startIdx !== -1 && endIdx !== -1) {
+  if (content.includes(SHELL_MARKER_START) || content.includes(SHELL_MARKER_END)) {
+    // A block-shaped span is claimed here: validate it the same way uninstall
+    // does before touching a single byte. Two bare indexOf() calls cannot tell
+    // "well-formed" apart from "duplicated" (only the FIRST end is found, so a
+    // second full copy's body gets stranded in the untouched tail) or "swapped"
+    // (end before start silently duplicates whatever sits between them into the
+    // "replaced" span instead of raising anything). Neither corruption is
+    // something this script can safely repair, so a malformed span is left
+    // completely alone, the same contract uninstall.mjs holds for removal.
+    const span = findMarkerSpan(content, SHELL_MARKER_START, SHELL_MARKER_END);
+    if (!span.ok) {
+      log('skipped', `${shellConfigPath} (${span.reason}, leaving the file untouched)`);
+      return;
+    }
     // Block exists — check if already up to date
-    const existing = content.slice(startIdx, endIdx + SHELL_MARKER_END.length);
+    const existing = content.slice(span.startIdx, span.endIdx + SHELL_MARKER_END.length);
     if (existing === block) {
       log('skipped', `${shellConfigPath} (shell function up to date)`);
       return;
     }
     // Replace stale block
     const updated =
-      content.slice(0, startIdx) + block + content.slice(endIdx + SHELL_MARKER_END.length);
+      content.slice(0, span.startIdx) +
+      block +
+      content.slice(span.endIdx + SHELL_MARKER_END.length);
     if (!dryRun) writeFileSync(shellConfigPath, updated);
     log('merged', `${shellConfigPath} (shell function updated)`);
     return;

package/scripts/lib/design-history-stale.mjs

@@ -69,9 +69,10 @@ function maxDate(dates) {
   return dates.reduce((a, b) => (a > b ? a : b));
 }
 
-// Returns stale findings: { project, lastSession, lastDesignHistory, diffDays }
-// Only includes projects where design-history.md exists AND is stale relative
-// to the latest session-log entry. Date source is body section headings
+// Returns findings: { project, kind, lastSession, lastDesignHistory, diffDays }.
+// `kind` is 'stale' (the file exists but session-log has moved past it) or
+// 'missing' (the file does not exist at all, yet session-log carries at least
+// one design-relevant entry). Date source is body section headings
 // (## YYYY-MM-DD), not frontmatter `updated:` — auto-stage hooks bump the
 // frontmatter on unrelated edits, so it can't signal staleness on its own.
 export function findDesignHistoryStale(hypoDir) {
@@ -81,17 +82,19 @@ export function findDesignHistoryStale(hypoDir) {
   if (!existsSync(projectsDir)) return stale;
 
   for (const name of readdirSync(projectsDir)) {
+    if (name.startsWith('_')) continue; // e.g. templates/projects/_template — not a real project
     const projectDir = join(projectsDir, name);
     if (!statSync(projectDir).isDirectory()) continue;
 
     const dhPath = join(projectDir, 'design-history.md');
-    if (!existsSync(dhPath)) continue;
 
     // session-log can live as a flat `session-log.md` (legacy) or a directory of
     // daily shards `session-log/YYYY-MM-DD.md` (canonical; legacy
     // monthly `YYYY-MM.md` files still appear pre-cutover). This globs every
     // `.md` in the directory, so daily and monthly shapes are both aggregated —
-    // the staleness check needs to see all of them.
+    // the staleness check needs to see all of them. Gathered before the
+    // existsSync(dhPath) branch below, since a project with zero design-history
+    // file still needs this to decide whether it has a design-relevant entry.
     const sessionDates = [];
     const flatSlPath = join(projectDir, 'session-log.md');
     if (existsSync(flatSlPath)) {
@@ -107,16 +110,32 @@ export function findDesignHistoryStale(hypoDir) {
     }
     if (sessionDates.length === 0) continue;
 
+    if (!existsSync(dhPath)) {
+      // The file was never created, so there is nothing to compare dates
+      // against — but parseSessionDates already excluded pure "ADR 없음"
+      // entries, so a non-empty sessionDates here means at least one entry
+      // recorded (or implied) a design change with nowhere to land. This is a
+      // bootstrap gap, not a staleness gap: `lastDesignHistory`/`diffDays` stay
+      // null and callers must key off `kind` to avoid conflating the two.
+      stale.push({
+        project: name,
+        kind: 'missing',
+        lastSession: maxDate(sessionDates).toISOString().slice(0, 10),
+        lastDesignHistory: null,
+        diffDays: null,
+      });
+      continue;
+    }
+
     const dhText = readFileSync(dhPath, 'utf-8');
     const lastSession = maxDate(sessionDates);
     const lastDH = maxDate(parseDates(dhText, DESIGN_HISTORY_DATE_RE));
 
-    if (!lastSession) continue;
-
     if (!lastDH || lastSession > lastDH) {
       const diffDays = lastDH ? Math.round((lastSession - lastDH) / (1000 * 60 * 60 * 24)) : null;
       stale.push({
         project: name,
+        kind: 'stale',
         lastSession: lastSession.toISOString().slice(0, 10),
         lastDesignHistory: lastDH ? lastDH.toISOString().slice(0, 10) : '(없음)',
         diffDays,