hypomnema 1.6.2 → 1.7.0

package/scripts/upgrade.mjs

@@ -49,9 +49,11 @@ import {
   sha256 as sha256Buf,
   isRegularFile,
   readFileIfRegular,
+  readVersionAtRoot,
+  writeDualSkipProvenance,
 } from './lib/pkg-json.mjs';
 import { syncExtensions } from './lib/extensions.mjs';
-import { isHypomnemaPluginEnabled } from './lib/plugin-detect.mjs';
+import { isHypomnemaPluginEnabled, resolveEnabledPluginRoot } from './lib/plugin-detect.mjs';
 import { classifyInstall, downgradeGuardMessage } from '../hooks/version-check.mjs';
 
 const HOME = homedir();
@@ -213,26 +215,58 @@ const SHARED_FILES = _hookConfig.shared ?? [];
 
 // ── checks ───────────────────────────────────────────────────────────────────
 
-function checkSchemaVersion(hypoDir) {
-  const pkgPath = join(TEMPLATES, 'SCHEMA.md');
-  const hypoPath = join(hypoDir, 'SCHEMA.md');
+// Shared by SCHEMA.md and hypo-guide.md: both templates carry a top-level
+// `version:` frontmatter stamp, and both are compared the same way — installed
+// copy vs. the package's own template — without ever writing to hypoPath. This
+// function is read-only; nothing downstream may use its return value to
+// overwrite the installed file (hand-authored wiki files are never
+// silently clobbered).
+function checkTemplateVersion(hypoDir, filename) {
+  const pkgPath = join(TEMPLATES, filename);
+  const hypoPath = join(hypoDir, filename);
 
   const pkgVersion = existsSync(pkgPath)
     ? parseVersion((parseFrontmatter(readFileSync(pkgPath, 'utf-8')) ?? {}).version)
     : null;
-  const hypoVersion = existsSync(hypoPath)
+
+  const hypoExists = existsSync(hypoPath);
+  const hypoVersion = hypoExists
     ? parseVersion((parseFrontmatter(readFileSync(hypoPath, 'utf-8')) ?? {}).version)
     : null;
 
+  // File present but carries no `version:` frontmatter field at all — a
+  // pre-versioning install (the file predates this stamp existing). This is
+  // deliberately distinguished from "file missing entirely" (still routed to
+  // bumpType's 'unknown' below): a bare `bumpType(null, pkgVersion)` cannot
+  // tell the two apart, and folding this case into plain 'unknown' is exactly
+  // what let an already-installed, unstamped hypo-guide.md report "up to
+  // date" — the file this check exists to catch. The caller decides whether
+  // 'unstamped' counts as drift; this helper only classifies.
+  const unstamped = hypoExists && !hypoVersion && !!pkgVersion;
+
   return {
     installed: hypoVersion?.raw ?? null,
     current: pkgVersion?.raw ?? null,
-    bump: bumpType(hypoVersion, pkgVersion),
+    bump: unstamped ? 'unstamped' : bumpType(hypoVersion, pkgVersion),
     hypoPath,
     pkgPath,
   };
 }
 
+function checkSchemaVersion(hypoDir) {
+  return checkTemplateVersion(hypoDir, 'SCHEMA.md');
+}
+
+// hypo-guide.md had no update channel at all — upgrade.mjs never
+// looked at it, and init.mjs only ever writes it once (skip if present), so an
+// installed vault's copy went permanently stale the moment the shipped template
+// changed, with no signal to the user. This check restores visibility (a warning
+// on drift) without adding a write path: --apply still never touches an
+// installed hypo-guide.md, exactly like SCHEMA.md's existing Option C contract.
+function checkGuideVersion(hypoDir) {
+  return checkTemplateVersion(hypoDir, 'hypo-guide.md');
+}
+
 // 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
 // The function reads only (apply happens in applyHookFiles).
@@ -479,6 +513,11 @@ const GITIGNORE_REQUIRED_ENTRIES = [
     pattern: '.cache/',
     comment: '# Hypomnema runtime cache (page-usage log, session growth metrics)',
   },
+  {
+    pattern: '*.lock',
+    comment:
+      '# Append-lock files (transient <target>.lock; a crashed holder can leave a stale one)',
+  },
 ];
 
 function checkGitignore(hypoDir) {
@@ -836,6 +875,15 @@ function writePluginModeMetadata() {
   return true;
 }
 
+// readVersionAtRoot and writeDualSkipProvenance now live in ./lib/pkg-json.mjs
+// (imported above) — writeDualSkipProvenance is deliberately not
+// writePluginModeMetadata(): that function hardcodes THIS npm run's
+// PKG_ROOT/PKG_VERSION and always drops `commands` — both correct for true
+// plugin mode, both wrong for a dualSkip correction, where the identity being
+// written is the OTHER install's. Moving both into lib/pkg-json.mjs (alongside
+// the other pkgJsonPath-taking helpers already there) also makes the writer's
+// TOCTOU refusal directly unit-testable without spawning the whole script.
+
 // ── main ─────────────────────────────────────────────────────────────────────
 
 const args = parseArgs(process.argv);
@@ -886,9 +934,41 @@ const managesClaudeCore = !pluginMode && (!dualInstallCoreConflict || args.allow
 const dualSkip = dualInstallCoreConflict && !args.allowDualInstall;
 
 const schema = checkSchemaVersion(args.hypoDir);
+const guide = checkGuideVersion(args.hypoDir);
 const hooks = checkHookFiles(claudeHooksDir);
 const settings = checkSettingsJson(claudeSettingsPath, claudeHooksDir);
 const pkgJson = checkPkgJson();
+// dualSkip provenance self-heal: the registry root the enabled plugin key
+// POSITIVELY resolves to (same lookup init.mjs's resolveDurableRoot uses), or
+// null when the registry is absent/unreadable/corrupt or names no usable entry
+// for the enabled key. Computed unconditionally (fail-open on any uncertainty —
+// see lib/plugin-detect.mjs) so both the --apply write below and the read-only
+// report can agree on the same positively-resolved identity without a second
+// registry read racing the first.
+const dualSkipRegistryRoot = dualSkip
+  ? resolveEnabledPluginRoot(
+      claudeSettingsPath,
+      join(HOME, '.claude', 'plugins', 'installed_plugins.json'),
+    )
+  : null;
+// The recorded pkgRoot currently on disk, read non-mutatingly (readPkgJsonSafe
+// would rename aside a corrupt file — a write — before this script has decided
+// whether to touch anything).
+const dualSkipRecordedRoot = (() => {
+  try {
+    const v = JSON.parse(readFileSync(pkgJsonPath(), 'utf-8')).pkgRoot;
+    return typeof v === 'string' ? v : null;
+  } catch {
+    return null;
+  }
+})();
+// A CONDITIONAL self-heal, never an unconditional rewrite: correct only when the
+// registry positively resolves a usable root that DIFFERS from what's already
+// recorded. An unresolvable registry (null) must PRESERVE the existing pointer,
+// not blank it or fall back to this npm PKG_ROOT — a null here is "cannot prove
+// a correction is needed", not "there is nothing to preserve".
+const dualSkipWouldCorrect =
+  dualSkip && dualSkipRegistryRoot !== null && dualSkipRegistryRoot !== dualSkipRecordedRoot;
 const commands = checkCommands();
 const oldHookRefs = checkOldHookNames(claudeSettingsPath);
 const hypoignore = checkHypoignore(args.hypoDir);
@@ -948,15 +1028,41 @@ const missingSettingsCodex = settingsCodex
 const invalidSettingsCodex = settingsCodex
   ? settingsCodex.some((s) => s.status === 'invalid-json')
   : false;
-const schemaDrift = schema.bump !== 'none' && schema.bump !== 'unknown' && schema.bump !== 'ahead';
-// Dual-install: when core is skipped, hypo-pkg.json is deliberately left
-// pointing at the PLUGIN's package root (preserved identity), so checkPkgJson()
-// reports it 'stale' relative to this npm/manual PKG_ROOT. That mismatch is
-// INTENTIONAL — `--apply` will not (and must not) rewrite it — so it must not
-// count as actionable drift, or the user would be nagged to run --apply forever.
-// A genuinely missing/corrupt file (status 'missing') is still surfaced (warning
+// SCHEMA.md keeps its pre-existing behavior: 'unstamped' is deliberately NOT
+// counted as drift here (SCHEMA.md is user-owned vocabulary, Option C — an
+// unstamped SCHEMA.md was already the "cannot compare" case before this
+// classification existed, and no SCHEMA test exercises it as actionable).
+const schemaDrift =
+  schema.bump !== 'none' &&
+  schema.bump !== 'unknown' &&
+  schema.bump !== 'ahead' &&
+  schema.bump !== 'unstamped';
+// hypo-guide.md: 'unstamped' DOES count as drift — this is the exact shape of
+// an already-installed pre-versioning vault, the population this change targets.
+// Excluding it (as the old unknown-only check did) is the bug this fixes.
+const guideDrift = guide.bump !== 'none' && guide.bump !== 'unknown' && guide.bump !== 'ahead';
+// Dual-install: when core is skipped, hypo-pkg.json is normally left pointing
+// at the PLUGIN's package root (preserved identity), so checkPkgJson() reports
+// it 'stale' relative to this npm/manual PKG_ROOT. That mismatch is USUALLY
+// intentional — `--apply` will not rewrite an already-correct plugin pointer
+// — so it must not count as actionable drift by default, or the user would be
+// nagged to run --apply forever. The one exception is dualSkipWouldCorrect: an
+// npm-first divergence where the recorded pointer differs from what the plugin
+// registry POSITIVELY resolves (e.g. `npm init`, enable the plugin, `npm init`
+// again — the npm root stays recorded forever otherwise). THAT case IS
+// actionable — `--apply` corrects it via writeDualSkipProvenance — so it must
+// count as drift, or the user has no signal to ever run --apply. dualSkipWouldCorrect
+// is checked FIRST and unconditionally (not gated behind `pkgJson.status !==
+// 'up-to-date'`): checkPkgJson() compares the recorded pointer only against
+// THIS run's own PKG_ROOT, so an npm-first divergence where the recorded
+// pointer happens to equal PKG_ROOT (but the registry resolves a DIFFERENT
+// plugin root) would read 'up-to-date' and slip past that status check
+// entirely — leaving a correctable divergence permanently unreported. A
+// genuinely missing/corrupt file (status 'missing') is still surfaced (warning
 // below), because the runtime then cannot resolve its package root at all.
-const pkgJsonDrift = pkgJson.status !== 'up-to-date' && !(dualSkip && pkgJson.status === 'stale');
+const pkgJsonDrift =
+  dualSkipWouldCorrect ||
+  (pkgJson.status !== 'up-to-date' && !(dualSkip && pkgJson.status === 'stale'));
 const staleCommands = commands.filter((c) => c.status === 'stale' || c.status === 'missing');
 const userModifiedCommands = commands.filter((c) => c.status === 'user-modified');
 const orphanedCommands = commands.filter((c) => c.status === 'orphaned');
@@ -968,6 +1074,11 @@ let migrationPath = null;
 let appliedHooks = [];
 let appliedSettings = [];
 let appliedPkgJson = false;
+// True only once the dualSkip provenance self-heal actually WROTE a correction
+// this run (a positively-resolved registry root that differed from the
+// recorded one). Distinct from dualSkipWouldCorrect (a pre-apply preview
+// computed above), which stays true even in a dry run.
+let dualSkipCorrected = false;
 let appliedHookNameRenames = [];
 let appliedHooksCodex = [];
 let appliedSettingsCodex = [];
@@ -1054,6 +1165,20 @@ if (args.apply) {
     // user to resolve the dual install.
     if (pkgJson.status === 'missing') {
       appliedPkgJson = writePluginModeMetadata();
+    } else if (dualSkipWouldCorrect) {
+      // npm-first correction: a usable pkgRoot IS already recorded (status
+      // 'stale' or 'up-to-date'), but the registry positively resolves a
+      // DIFFERENT usable root — e.g. `npm init`, then enable the plugin, then
+      // `npm init` again, leaving the npm root recorded forever. Correct the
+      // provenance to the registry's own root/version. When the registry
+      // cannot positively resolve one (dualSkipWouldCorrect is false — null
+      // registry lookup, or it already matches what's recorded), fall through
+      // to preserving the existing pointer untouched; never blank it.
+      // writeDualSkipProvenance can still refuse here (TOCTOU: the registry
+      // root's own package.json became unreadable between resolution and this
+      // write) — dualSkipCorrected only follows an ACTUAL write, never assume it.
+      appliedPkgJson = writeDualSkipProvenance(pkgJsonPath(), dualSkipRegistryRoot);
+      dualSkipCorrected = appliedPkgJson;
     } else {
       appliedPkgJson = false;
     }
@@ -1134,6 +1259,7 @@ const hasDrift =
   (managesClaudeCore && claudeCoreDrift) ||
   pkgJsonDrift ||
   schemaDrift ||
+  guideDrift ||
   hypoignore.status === 'needs-migration' ||
   gitignore.status === 'needs-migration' ||
   extDrift ||
@@ -1150,6 +1276,7 @@ if (args.json) {
         coreManagedBy: managesClaudeCore ? 'self' : pluginMode ? 'plugin' : 'plugin-enabled',
         dualInstallOverride: args.allowDualInstall,
         schema,
+        guide,
         hooks,
         settings,
         pkgJson,
@@ -1249,6 +1376,12 @@ if (schema.bump === 'none') {
   lines.push(
     `⚠ SCHEMA version    ${schema.installed} (installed is ahead of package ${schema.current})`,
   );
+} else if (schema.bump === 'unstamped') {
+  // Not counted as drift for SCHEMA.md (Option C, unchanged) — still surfaced
+  // as advisory-only visibility, same spirit as the pre-existing 'unknown' text.
+  lines.push(
+    `⚠ SCHEMA version    installed has no version stamp (pre-versioning copy), package=${schema.current} (cannot compare automatically)`,
+  );
 } else if (schema.bump === 'major') {
   lines.push(
     `✗ SCHEMA version    ${schema.installed} → ${schema.current}  [MAJOR — --apply writes MIGRATION report; SCHEMA must be merged manually]`,
@@ -1259,6 +1392,33 @@ if (schema.bump === 'none') {
   );
 }
 
+// hypo-guide.md version stamp. Visibility only — a drift warning,
+// never a write: --apply must not overwrite an installed hypo-guide.md, since a
+// user may have customized it (same Option C contract as SCHEMA.md above).
+if (guide.bump === 'none') {
+  lines.push(`✓ hypo-guide.md     v${guide.installed} (up to date)`);
+} else if (guide.bump === 'unknown') {
+  lines.push(
+    `⚠ hypo-guide.md     installed=${guide.installed ?? 'not found (no version stamp)'}, package=${guide.current ?? 'not found'} (cannot compare)`,
+  );
+} else if (guide.bump === 'ahead') {
+  lines.push(
+    `⚠ hypo-guide.md     v${guide.installed} (installed is ahead of package v${guide.current})`,
+  );
+} else if (guide.bump === 'unstamped') {
+  // The target case: the file exists (this is not a fresh/missing
+  // install) but predates the version stamp entirely. Counted as drift above
+  // (guideDrift) — the message must be actionable, not "cannot compare",
+  // since a pre-versioning copy silently reporting "up to date" was the bug.
+  lines.push(
+    `⚠ hypo-guide.md     installed copy has no version stamp (pre-versioning stale copy; package=v${guide.current}) — review templates/hypo-guide.md and update your copy manually; --apply does not overwrite it`,
+  );
+} else {
+  lines.push(
+    `⚠ hypo-guide.md     v${guide.installed} → v${guide.current}  [package template changed — review templates/hypo-guide.md and update your copy manually; --apply does not overwrite it]`,
+  );
+}
+
 // Hook files (target-aware so --codex can mirror the same block).
 function pushHookSummary(hookList, label, targetPath) {
   const colHook = `Hook files${label}`.padEnd(20);
@@ -1318,7 +1478,28 @@ if (managesClaudeCore) {
 if (settingsCodex) pushSettingsSummary(settingsCodex, ' (codex)', invalidSettingsCodex);
 
 // Package metadata
-if (dualSkip && pkgJson.status === 'stale') {
+if (dualSkip && dualSkipCorrected) {
+  // npm-first correction actually WROTE this run: the pre-apply pkgJson
+  // classification above was computed against the running npm PKG_ROOT, so
+  // without this branch a corrected pointer would still be reported as
+  // "preserved — not rewritten" (or "up to date"/"stale") below, contradicting
+  // what --apply just did. Report the explicit outcome instead, with the
+  // registry package's own version — the identity now on disk.
+  const correctedVersion = readVersionAtRoot(dualSkipRegistryRoot);
+  lines.push(
+    `✓ Package metadata  hypo-pkg.json corrected to enabled plugin registry root` +
+      (correctedVersion ? ` (v${correctedVersion})` : ''),
+  );
+} else if (dualSkip && dualSkipWouldCorrect) {
+  // Same divergence, but this was a dry run (no --apply): preview what
+  // --apply would do rather than claiming the identity is already preserved.
+  const previewVersion = readVersionAtRoot(dualSkipRegistryRoot);
+  lines.push(
+    `⚠ Package metadata  hypo-pkg.json points at a stale npm/manual root — \`--apply\` will` +
+      ` correct it to the enabled plugin registry root` +
+      (previewVersion ? ` (v${previewVersion})` : ''),
+  );
+} else if (dualSkip && pkgJson.status === 'stale') {
   // Dual-install: the 'stale' here is the preserved plugin identity (pkgRoot points at
   // the plugin, not this npm/manual copy). That is intentional — not actionable.
   lines.push(
@@ -1572,6 +1753,7 @@ const totalDrift =
   claudeCoreCount +
   (pkgJsonDrift ? 1 : 0) +
   (schemaDrift ? 1 : 0) +
+  (guideDrift ? 1 : 0) +
   (hypoignore.status === 'needs-migration' ? hypoignore.missing.length : 0) +
   (gitignore.status === 'needs-migration' ? gitignore.missing.length : 0) +
   extCheck.actions.filter(

package/skills/crystallize/SKILL.md

@@ -11,7 +11,7 @@ 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 `/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.
+- **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> --session-id=<id>` mode, which runs the lint gate automatically, **scoped to the files it writes** (debt elsewhere is a non-blocking notice). **`--session-id` is required.** Before writing a byte, the apply resolves that session's transcript and refuses the whole close, exit 1 and nothing on disk, unless the **user** asked for it (`session-id-required` / `transcript-unresolved` / `no-user-close-signal`). A refusal is the answer, not an obstacle: ask the user, and re-run only if they say yes. `--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.
 
 ---
@@ -102,15 +102,52 @@ Once it passes, report each item with ✓:
 - ✓ session-log entry
 - ✓ open-questions (or skipped if unchanged)
 - ✓ log.md entry
-- **marker written?** (required, if `--apply-session-close --session-id` was used): check `markerWritten` in the JSON output. If `true`, report "session-close marker written." If `false`, do NOT declare the session closed or complete; recover per the `markerSkipReason` branch below.
+- **marker written?** (required): check `markerWritten` in the JSON output. If `true`, report "session-close marker written." If `false`, do NOT declare the session closed or complete; recover per the branches below.
 
-If `markerWritten: true` (or `--session-id` was not passed), ask: "Session closed. Would you like to also run knowledge synthesis now, or stop here?"
+If `markerWritten: true`, ask: "Session closed. Would you like to also run knowledge synthesis now, or stop here?"
 
-If `markerWritten: false`, do NOT say "session closed." Branch on `markerSkipReason`:
+**If `ok: false` with an authority `reason`, the close did not happen at all.** No file was written, nothing was committed. Do not report a partial close, and do not write the files by hand to get around it.
 
-- `no-user-close-signal`: files applied cleanly and the transcript resolved, but it carries no close phrase the gate recognizes (the user's close wording fell outside the close-signal set, e.g. "세션 마무리까지 진행해줘" / "세션 마무리 진행"). Re-running the same id will not help. Confirm intent once with `AskUserQuestion` (header "세션", one option **세션 마무리**); if the user picks it, that answer is a recognized close signal, so re-run the same `--apply-session-close … --session-id` command (idempotent no-op writes; the marker lands). If the user declines, leave the session unmarked. Do NOT change the close-signal matcher.
-- `transcript-unresolved` (wrong / background id): report "Files applied and verified (ok: true), but the marker was not written (reason: `<markerSkipReason>`). The Stop-chain is still active. Re-run with the correct main-conversation `--session-id`."
-- any other reason (`compact-gate-not-ok`, `commit-failed: …`, `marker-did-not-land`): surface it verbatim and resolve the underlying blocker before re-running.
+- `session-id-required`: `--session-id` was omitted. Pass the main conversation's id and re-run.
+- `transcript-unresolved`: the id resolved no transcript, so it is most likely a background-task or Agent-thread uuid rather than the main conversation's. Get the right one and re-run.
+- `no-user-close-signal`: the transcript is this session's, and the user never asked to close in wording the gate recognizes (e.g. "세션 마무리까지 진행해줘" falls outside the close-signal set). Re-running the same id changes nothing. Confirm intent once with `AskUserQuestion` (header "세션", one option **세션 마무리**); if the user picks it, that answer becomes a recognized close signal, so the same command now applies everything: writes, commit, and marker. If the user declines, the session stays open and nothing is written. Do NOT change the close-signal matcher.
+
+**If `ok: false` with `stage: "session-id-mismatch"`,** the payload carries a `sessionId` that is not the `--session-id` you passed, so this file was authored for a different session (a reused or overwritten temp path). Nothing was written. Do not force it: rebuild the payload for THIS session (write it to a session-scoped path, e.g. `/tmp/hypo-session-close-<session-id>.json`) and re-run.
+
+If the apply succeeded but `markerWritten: false`, branch on `markerSkipReason` (`compact-gate-not-ok`, `commit-failed: …`, `marker-did-not-land`): surface it verbatim and resolve the underlying blocker before re-running.
+
+### If the close came back `ok: false, stage: "proposal-pending"`
+
+A concurrent session wrote one of the pages this close wants to replace, so the close
+withheld the bytes rather than clobber that session's work, and parked them. Nothing is
+lost and nothing is broken. The close is waiting on a decision only the user makes:
+whether to replace the other session's bytes.
+
+Do NOT write the pages with the Write tool and mark the session closed. That path skips
+the store entirely and silently destroys the other session's edits. Drive it out properly:
+
+1. **Look at `proposals`.** If the array is EMPTY, no page was parked. The only conflicts
+   were append-lock timeouts, which the next close re-reads and re-appends by itself. Just
+   re-run the same close command.
+2. **`hypomnema proposal challenge --session-id <id> --ids <id,...>`** with the ids from
+   `proposals`. It re-reads each page from disk and prints the diff between what is there
+   now and what this close wants to write.
+3. **Show the user those diffs** and tell them plainly what would be overwritten. Then give
+   them the approval line the command printed, and ask them to type it:
+
+       apply-proposals <nonce>
+
+   They have to TYPE it. A click on `AskUserQuestion` does not approve an overwrite (you
+   author the option labels, so a click cannot prove they approved this specific write),
+   and the command refuses it. If they would rather keep the other session's page, run
+   `hypomnema proposal discard <id>` instead and re-run the close.
+4. **`hypomnema proposal resolve --session-id <id>`** once they have typed it. It verifies
+   the approval in the transcript, checks the pages have not moved since they saw the diff,
+   and writes them.
+5. **Re-run the close.** `resolve` writes the pages; it does NOT close the session. The
+   re-run skips what already landed and finishes the close.
+6. **Check `markerWritten` again** before you say the session is closed. It is never
+   automatic.
 
 ---
 

package/skills/debate/SKILL.md

@@ -0,0 +1,88 @@
+---
+description: Structured debate to re-verify a wiki knowledge claim before you trust it, or to harden a hard-to-reverse decision into a durable wiki record. Runs a fixed order (interrogate, then verify against code and docs, then synthesize). Use when hypo:verify flags a page as overdue and you need to actually re-check its claim, when a decision is hard to reverse (architecture, refactor, external API integration) and should leave an ADR, or when the user asks to "debate", "stress-test", or "verify this claim". Skip it for reversible or already-obvious calls.
+---
+
+You are running `/hypo:debate`. It formalizes an informal practice (a two-worker adversarial
+review) into a reproducible fixed order, so the same rigor applies every time.
+
+The premise: separate the mind that **generates and interrogates** from the mind that
+**verifies**. Interrogation without verification lets a plausible wrong answer survive;
+verification without interrogation confirms a wrong premise with precision. The order is
+fixed for that reason.
+
+The debate always ends in a durable wiki artifact: a refreshed page, a correction, or an
+ADR. A debate that leaves nothing on disk was just a conversation. This is the producer
+reviewer pattern applied to a single claim; for the orchestration vocabulary it belongs to,
+see [references/orchestration-patterns.md](references/orchestration-patterns.md).
+
+## Two uses
+
+1. **Re-verify a wiki claim (primary).** `/hypo:verify` surfaces pages whose `verify_by_date`
+   is overdue (or that carry no `verify_by` question at all). This skill is the deep re-check
+   behind that prompt: does the page's `verify_by` question still hold against the current
+   code and docs? The outcome updates the page exactly as `/hypo:verify` Step 4 does (see
+   below), with the debate supplying the evidence.
+2. **Harden a hard-to-reverse decision.** Architecture choices, refactor direction, external
+   API or dependency integration, where the first-pass answer is often wrong (concurrency,
+   migrations, security boundaries, distributed state). The decision must land as an ADR or a
+   wiki page; if it would not, it is not big enough for a debate.
+
+## When not to use
+
+- A change whose diff you can state in one sentence. Just do it.
+- A reversible call, an already-obvious choice, or a one-off lookup. The debate's fixed cost
+  exceeds its value.
+
+## Fixed three phases
+
+### Phase 1. Interrogate (do not answer yet)
+
+Attack the claim or decision. Build a list of questions, not conclusions.
+
+- Surface hidden assumptions: "this rests on X being true. What if X is false?"
+- Stand up at least two alternatives (three including the incumbent). Best and worst case of
+  each.
+- List failure modes: how does this decision bite six months from now?
+- Output: a list of **falsifiable claims**. Each must be resolvable to true / false by code,
+  docs, or a command ("p95 under 50ms", not "it will be fast"). For a wiki claim, restate the
+  page's `verify_by` question in a form you can actually check against the current code or
+  docs.
+
+### Phase 2. Verify (against code, docs, and the wiki)
+
+Check each Phase 1 claim, one at a time. Do not invent new claims here.
+
+- Read the code, find the docs, run the command. Judge each claim true / false / unknown.
+- Unknown is unknown. A zero-result grep is not proof of absence.
+- For a wiki claim, check it against the page's own cited sources and the code or docs it
+  describes, not against memory.
+- For genuine independence, hand this phase to a reviewer who did not run the interrogation
+  (a fresh-context subagent, or a second person). Self-review of your own interrogation
+  breeds confirmation bias.
+- Output: a **per-claim verdict table** (claim, verdict, evidence line or command).
+
+### Phase 3. Synthesize
+
+Reconcile Phases 1 and 2 into one outcome, and write it down.
+
+- Build the conclusion only from claims that survived verification. For each rejected
+  alternative, leave one line on why it fell.
+- Name the residual risk (remaining unknowns, fail-open points) alongside the outcome. Do not
+  hide it.
+- Land the durable artifact:
+  - Wiki claim: answer the page's `verify_by` question **yes / no / partially**. On yes,
+    refresh `last_reviewed` to today and push `verify_by_date` forward. On no or partially,
+    edit the page to correct it, then refresh both fields. This is exactly `/hypo:verify`
+    Step 4; the debate is what earns the answer.
+  - Decision: record it as an ADR (or a wiki page) holding the **decision, rationale, and
+    residual risk**. That record, not the discussion, is the deliverable.
+
+## Execution notes
+
+- Run the three phases inline in order, or split only Phase 2 out to an independent reviewer.
+  That independence contributes the most to decision quality (the verifier's fresh context).
+- Keep the boundary between interrogation (1) and verification (2). If a new alternative
+  occurs during verification, note it for Phase 1 and finish verifying the current claims
+  before opening a new round. Mixing the two blurs both.
+- Do not accept a reviewer's verdict uncritically. The final call at synthesis stays with the
+  person running the debate.

package/skills/debate/references/orchestration-patterns.md

@@ -0,0 +1,83 @@
+# Multi-agent orchestration patterns
+
+A shared vocabulary for designing multi-agent work. `/hypo:debate` is one instance of it
+(the producer-reviewer pattern). When you orchestrate several agents around your wiki work,
+name the pattern first, then build.
+
+The one selection rule: **does the next stage need a barrier?** If not, pipeline. If it must
+see everything at once, fan-out / fan-in. If several angles look at the same target, expert
+pool. If one agent must grade another's output, producer-reviewer. If one place must hold the
+decision, supervisor. If delegation spawns more delegation, hierarchical.
+
+## 1. Pipeline
+
+Each item flows through the stages independently. No barrier between stages, so item A can be
+in stage 3 while item B is still in stage 1. With enough parallel capacity, wall-clock trends
+toward the slowest single-item chain rather than the sum of per-stage worsts (setting aside
+pipeline fill and drain). With limited capacity, items queue and it degrades toward the
+barrier case.
+
+- Use when: every item runs the same chain and items do not wait on each other (per-file
+  transforms, a find then fix then verify done per item).
+- Mistake: adding a barrier because you think a stage needs all prior results. That is
+  fan-out / fan-in, not a pipeline. Do any flatten / map / filter inside a stage.
+
+## 2. Fan-out / fan-in
+
+Spread work in parallel (fan-out), then gather all of it at a barrier (fan-in) to merge,
+dedup, or aggregate. Justified only when stage N needs every result of stage N-1 together.
+
+- Use when: dedup across the full set before an expensive downstream step, early-exit when
+  the total is zero, or a result that must be compared against all the others.
+- Mistake: forgetting the barrier's wait cost. Fast workers idle waiting on slow ones. Use it
+  only when you genuinely need all results.
+
+## 3. Expert pool
+
+Several agents look at the same target through **different lenses** at once. Each holds a
+different expertise (correctness, security, performance, reproducibility) or a different
+viewpoint, blind to what the others see.
+
+- Use when: one search angle cannot find everything, or a defect can break in more than one
+  way. The goal is **perspective diversity**, not redundant voting.
+- Mistake: giving N agents the same prompt and calling it an expert pool. That is just
+  redundancy. The lenses must actually differ.
+
+## 4. Producer-reviewer
+
+A producer makes something and an **independent** reviewer verifies it adversarially. Use it
+when the maker should not grade their own work. Prompt the reviewer to find why it is wrong
+first. `/hypo:debate` is this pattern applied to one claim.
+
+- Use when: catching defects in a change, a design, or an artifact from a fresh context.
+- Mistake: handing the reviewer the producer's rationale. The reviewer should see the target,
+  not the conclusion, to stay independent. Do not accept the review uncritically; the final
+  call stays with the orchestrator.
+
+## 5. Supervisor
+
+One orchestrator delegates to workers and integrates the results. The **decision and the
+human gate stay with the orchestrator**; only the heavy execution goes down.
+
+- Use when: keeping the main context for decisions while isolating large raw material or
+  diffs in subagents. When you delegate, hand over everything the main context knows: the
+  goal, the read / write scope, the constraints already confirmed, the verify command, the
+  return schema.
+- Mistake: treating a worker's output as evidence. It is a candidate. Trust it blindly and
+  you get a phantom backlog.
+
+## 6. Hierarchical delegation
+
+A tree of delegation: a higher worker re-delegates to lower ones. Splits a large problem into
+sub-problems handled by depth.
+
+- Use when: a breadth or depth one orchestrator cannot hold (a large migration, a broad
+  audit).
+- Mistake: allowing unbounded nesting depth. Keep the hierarchy to a controlled one or two
+  levels, and do not let a subagent open its own sub-delegation without a reason.
+
+## When not to reach for multi-agent at all
+
+If the main context already holds the material and the task finishes faster than the delegation
+overhead, do it inline. Before picking a pattern, ask whether the work is worth splitting. Most
+single lookups are not.

package/templates/.hyposcanignore

@@ -0,0 +1,10 @@
+# .hyposcanignore — patterns excluded from scan (lint/graph/stats/query/verify/doctor) only
+# One glob per line. Lines starting with # are comments.
+# Matched files are skipped by catalog scans but are still committed and still
+# readable by hooks. For secrets and anything that must never be committed or
+# surfaced by a hook, use .hypoignore instead — this file does NOT block commits.
+# Syntax follows .gitignore glob rules.
+
+# Draft / scratch (uncomment to hide from scans without blocking their commit)
+# drafts/
+# scratch/

package/templates/SCHEMA.md

@@ -91,11 +91,23 @@ Optional fields (add as needed):
 confidence: high | medium | low | speculative
 evidence_strength: direct | inferred | hearsay
 scope: always | project | session
+visibility_scope: shared | machine:<device>
 source: <slug or URL>
 verify_by: <question to re-check at next review>
 verify_by_date: YYYY-MM-DD
 ```
 
+`visibility_scope` is a different axis from `scope`: `scope` is memory lifetime,
+`visibility_scope` is where a page may surface. Omitting it means `shared` (the
+implicit default of every pre-existing page), so lookup/query/injection stay
+unchanged. `machine:<device>` hides the page from every machine except the one
+whose `currentDevice()` output equals `<device>`. Copy that exact string from the
+newest `device` value in `.cache/sessions/index.jsonl`, or from a recent
+session-log shard's `device:` frontmatter (both are `currentDevice()` outputs); a
+hand-typed value that does not match will hide the page on its own machine too.
+An empty owner (`machine:`) hides the page everywhere. `agent:<id>` is a reserved
+forward-compat value that is not filtered yet.
+
 ### 3.1. `feedback` type — projection fields
 
 Feedback pages are the single source of truth for behavior corrections;

package/templates/gitignore

@@ -3,3 +3,8 @@
 
 # Runtime cache: sync-state.json contains hostname() and timestamps
 .cache/
+
+# Append-lock files: transient <target>.lock guards around session-log / log.md
+# writes (crystallize apply, deriveRootLogEntries). Normally deleted immediately;
+# a crashed holder can leave a stale one, which must never be committed.
+*.lock

package/templates/hypo-config.md

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