hypomnema 1.6.2 → 1.7.1

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,12 @@
 
 # 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
+# The lock is published by linking a staged sibling into place. `*.lock` does not
+# match the staging name, and a crash between the link and its cleanup leaves one
+# behind — where `git add -A` would happily pick it up.
+*.lock.*.tmp

package/templates/hypo-config.md

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

package/templates/hypo-guide.md

@@ -2,6 +2,7 @@
 title: Wiki Operations Guide
 type: reference
 updated: YYYY-MM-DD
+version: 1
 tags: [wiki, guide, operations]
 ---
 
@@ -108,6 +109,11 @@ Ask: *"이 작업이 마무리되었나요? 세션을 정리(crystallize)할까
    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"**.
+   `--session-id` is not optional on the apply path. Before it writes anything, the
+   apply reads that session's transcript for evidence the **user** asked to close, and
+   refuses the whole close (exit 1, nothing on disk, nothing committed) when the id is
+   missing, resolves to no transcript, or the user never asked. A refusal means the
+   close should not happen: ask, then re-run.
 
 Skip session close for: single bug fix, single-file edit, Q&A only.
 

package/scripts/check-bilingual.mjs

@@ -1,153 +0,0 @@
-#!/usr/bin/env node
-/**
- * check-bilingual.mjs — CLI gate for the bilingual release-doc rule.
- *
- * Modes:
- *   --changelog [version]   Validate CHANGELOG.md section for given version.
- *                           Defaults to package.json's "version" field.
- *                           Wired into npm `prepublishOnly` so publishes fail
- *                           when the Korean summary is missing.
- *
- *   --tag <ref>             Validate annotated tag body for given ref.
- *                           Wired into .github/workflows/release.yml so a
- *                           lightweight tag or a missing Korean section
- *                           blocks the npm publish step.
- *
- * Exits 0 on pass, 1 on fail with a stderr diagnostic.
- */
-
-import { readFileSync } from 'fs';
-import { spawnSync } from 'child_process';
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
-import {
-  validateChangelog,
-  validateTagBody,
-  listChangelogVersions,
-  meetsKoreanCutoff,
-} from './lib/check-bilingual.mjs';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const REPO_ROOT = join(__dirname, '..');
-
-const RULE_REF =
-  'Rule source: CLAUDE.md learned_behaviors (release-doc-bilingual, 2026-05-24). ' +
-  'OSS Hypomnema ships must carry English body + Korean summary in both CHANGELOG section and git tag annotation.';
-
-function fail(msg) {
-  process.stderr.write(`[check-bilingual] FAIL: ${msg}\n${RULE_REF}\n`);
-  process.exit(1);
-}
-
-function ok(msg) {
-  process.stdout.write(`[check-bilingual] OK: ${msg}\n`);
-  process.exit(0);
-}
-
-function usage(exitCode) {
-  process.stdout.write(
-    `Usage:\n` +
-      `  node scripts/check-bilingual.mjs --changelog [version]\n` +
-      `      Validate one CHANGELOG.md "## [<version>]" section (section model).\n` +
-      `      Default version: package.json.\n` +
-      `  node scripts/check-bilingual.mjs --changelog --all\n` +
-      `      Validate EVERY documented version (Korean enforced at >= 1.2.0,\n` +
-      `      English-only versions below the cutoff pass).\n` +
-      `  node scripts/check-bilingual.mjs --tag <ref>\n` +
-      `      Validate annotated tag body (lightweight tags are rejected).\n`,
-  );
-  process.exit(exitCode);
-}
-
-const args = process.argv.slice(2);
-const mode = args[0];
-const wantAll = args.includes('--all');
-
-if (mode === '--help' || mode === '-h') usage(0);
-if (!mode) usage(1);
-
-if (mode === '--changelog') {
-  let content;
-  try {
-    content = readFileSync(join(REPO_ROOT, 'CHANGELOG.md'), 'utf-8');
-  } catch (err) {
-    fail(`cannot read CHANGELOG.md: ${err.message}`);
-  }
-
-  if (wantAll) {
-    // Validate every documented version. Korean is enforced only at/after the
-    // cutoff; pre-cutoff versions pass on English presence (format.md §9). This
-    // is the migration gate — it must not green-pass a half-migrated file.
-    const versions = listChangelogVersions(content);
-    if (versions.length === 0) fail('no "## [<version>]" sections found in CHANGELOG.md');
-    const failures = [];
-    let enforced = 0;
-    for (const v of versions) {
-      const r = validateChangelog(content, v);
-      if (meetsKoreanCutoff(v)) enforced++;
-      if (!r.ok) failures.push(`  [${v}] ${r.reason}`);
-    }
-    if (failures.length) {
-      fail(`${failures.length}/${versions.length} version(s) failed:\n${failures.join('\n')}`);
-    }
-    ok(
-      `CHANGELOG.md --all: ${versions.length} versions conform ` +
-        `(${enforced} Korean-enforced at >= 1.2.0, ${versions.length - enforced} English-only below cutoff).`,
-    );
-  }
-
-  // single-version path (kept: prepublishOnly and release.yml call --changelog
-  // with no version, defaulting to package.json's).
-  let version = args[1] && !args[1].startsWith('--') ? args[1] : undefined;
-  if (!version) {
-    try {
-      const pkg = JSON.parse(readFileSync(join(REPO_ROOT, 'package.json'), 'utf-8'));
-      version = pkg.version;
-    } catch (err) {
-      fail(`cannot read package.json: ${err.message}`);
-    }
-  }
-  if (!version) fail('no version (arg empty, package.json has no "version" field)');
-
-  const result = validateChangelog(content, version);
-  if (!result.ok) fail(result.reason);
-  if (result.koreanExempt) {
-    ok(`CHANGELOG.md [${version}] — pre-cutoff version, English-only (Korean exempt).`);
-  } else {
-    ok(`CHANGELOG.md [${version}] — ${result.hangulCount} Hangul chars across "#### 한국어" sub-blocks.`);
-  }
-} else if (mode === '--tag') {
-  const ref = args[1];
-  if (!ref) fail('--tag requires a ref argument (e.g. v1.2.1)');
-
-  // Reject lightweight tags. `git rev-parse <ref>^{tag}` succeeds ONLY for
-  // annotated tags. For lightweight tags the ^{tag} peel fails because there
-  // is no tag object — the ref points straight at a commit.
-  const tagObj = spawnSync('git', ['rev-parse', '--verify', '--quiet', `${ref}^{tag}`], {
-    encoding: 'utf-8',
-    cwd: REPO_ROOT,
-  });
-  if (tagObj.status !== 0) {
-    const exists = spawnSync('git', ['rev-parse', '--verify', '--quiet', ref], {
-      encoding: 'utf-8',
-      cwd: REPO_ROOT,
-    });
-    if (exists.status !== 0) fail(`tag ${ref} not found`);
-    fail(
-      `tag ${ref} is a lightweight tag, not annotated. ` +
-        `Re-create with: git tag -a ${ref} -m "<English body>\n\n---\n\n<Korean summary>"`,
-    );
-  }
-
-  const tagBody = spawnSync('git', ['tag', '-l', `--format=%(contents)`, ref], {
-    encoding: 'utf-8',
-    cwd: REPO_ROOT,
-  });
-  if (tagBody.status !== 0) fail(`failed to read tag ${ref}: ${tagBody.stderr}`);
-
-  const result = validateTagBody(tagBody.stdout || '');
-  if (!result.ok) fail(`tag ${ref} — ${result.reason}`);
-  ok(`tag ${ref} annotation — ${result.hangulCount} Hangul chars after last "---" separator.`);
-} else {
-  fail(`unknown mode: ${mode}. Use --changelog or --tag (see --help).`);
-}

package/scripts/check-readme-version.mjs

@@ -1,126 +0,0 @@
-#!/usr/bin/env node
-// check-readme-version.mjs — assert the release version string is present in BOTH
-// README.md and README.ko.md. This is the machine FLOOR for the README-reconcile
-// step that was dropped three times (v1.2 / v1.3.0 / v1.3.1): a publish of vX.Y.Z
-// must not go out unless vX.Y.Z is written into both READMEs' version narrative.
-//
-// SCOPE (honest): this catches the GROSS drop — shipping a version whose sentence
-// was never added to the README at all. It does NOT verify the narrative is
-// accurate or that the first-viewport "current release" pointer was updated; that
-// stays a judgment step owned by the release checklist (docs/CONTRIBUTING.md
-// "Cutting a release"). README/CHANGELOG carry
-// prose version HISTORY (every past vX.Y.Z), so check-versions.mjs intentionally
-// excludes them — this script is their complement, not a duplicate.
-//
-// Usage:
-//   node scripts/check-readme-version.mjs                 # version from package.json
-//   node scripts/check-readme-version.mjs --version 1.4.0 # explicit version
-//   node scripts/check-readme-version.mjs --root <dir>    # point at a fixture (tests)
-//   node scripts/check-readme-version.mjs --json
-//
-// Exit 0 = both READMEs mention the version. Exit 1 = missing in one/both, or unreadable.
-
-import { readFileSync } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
-
-function parseArgs(argv) {
-  const args = { root: null, version: null, json: false };
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a.startsWith('--root=')) args.root = a.slice(7);
-    else if (a === '--root') args.root = argv[++i];
-    else if (a.startsWith('--version=')) args.version = a.slice(10);
-    else if (a === '--version') args.version = argv[++i];
-    else if (a === '--json') args.json = true;
-  }
-  return args;
-}
-
-const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
-
-const README_FILES = ['README.md', 'README.ko.md'];
-
-// Build a boundary-aware matcher so a version does not spuriously match inside a
-// LONGER version token yet still matches at a sentence boundary. The checked
-// version must be a standalone token, NOT a prefix of another version:
-//   - "1.3.40", "v11.3.4"      → reject (digit continuation)
-//   - "1.3.4.5"                → reject (dot-then-digit continuation)
-//   - "1.3.4-rc.1", "1.3.4+b"  → reject (a stable check must NOT pass on a
-//                                 prerelease/build string — that defeats the floor)
-//   - "1.3.0-rc.1a", "1.3.0-rc.10", "1.3.0-rc.1.alpha" → a prerelease check must
-//                                 reject these continuation tokens too
-//   - "shipped v1.3.4." / "v1.3.4**" / "(v1.3.4)" → match (sentence/markup boundary)
-// Leading: no digit/dot immediately before (an optional "v" is fine — it is
-// neither). Trailing: not a semver-continuation char ([0-9A-Za-z+-]) and not a
-// dot-then-alphanumeric (".5" / ".alpha" continuation); a sentence period
-// (dot followed by space / punctuation / end) is allowed.
-function versionPresent(text, version) {
-  const escaped = version.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  return new RegExp(`(?<![\\d.])${escaped}(?![\\dA-Za-z+-])(?!\\.[\\dA-Za-z])`).test(text);
-}
-
-function checkReadmeVersions(root, version) {
-  const results = README_FILES.map((file) => {
-    const abs = join(root, file);
-    try {
-      const text = readFileSync(abs, 'utf-8');
-      return { file, present: versionPresent(text, version) };
-    } catch (err) {
-      return { file, present: false, error: err?.message ?? String(err) };
-    }
-  });
-  const ok = results.every((r) => r.present);
-  return { ok, version, results };
-}
-
-function main() {
-  const args = parseArgs(process.argv.slice(2));
-  const root = args.root || REPO_ROOT;
-
-  let version = args.version;
-  if (!version) {
-    try {
-      version = JSON.parse(readFileSync(join(root, 'package.json'), 'utf-8')).version;
-    } catch (err) {
-      const msg = `cannot read package.json for version: ${err?.message ?? err}`;
-      if (args.json) console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
-      else console.error(`✗ ${msg}`);
-      process.exit(1);
-    }
-  }
-  if (typeof version !== 'string' || !version) {
-    const msg = 'no version (—version empty and package.json has no "version" field)';
-    if (args.json) console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
-    else console.error(`✗ ${msg}`);
-    process.exit(1);
-  }
-
-  const report = checkReadmeVersions(root, version);
-
-  if (args.json) {
-    console.log(JSON.stringify(report, null, 2));
-  } else {
-    for (const r of report.results) {
-      const mark = r.error ? `ERROR: ${r.error}` : r.present ? 'found' : 'MISSING';
-      console.log(`  ${r.file.padEnd(13)}  ${mark}`);
-    }
-    if (report.ok) {
-      console.log(`\n✓ both READMEs mention version ${version}`);
-    } else {
-      const missing = report.results
-        .filter((r) => !r.present)
-        .map((r) => (r.error ? `${r.file} (unreadable)` : r.file))
-        .join(', ');
-      console.error(
-        `\n✗ version ${version} missing from: ${missing}\n` +
-          `  Reconcile the version narrative in both READMEs before releasing ` +
-          `(the README reconcile step — see docs/CONTRIBUTING.md "Cutting a release").`,
-      );
-    }
-  }
-
-  process.exit(report.ok ? 0 : 1);
-}
-
-main();