hypomnema 1.3.3 → 1.4.0

package/scripts/smoke-plugin.mjs

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+// smoke-plugin.mjs — a cheap, LOCAL structural check that the Claude Code plugin
+// would load, with no network and no Claude CLI dependency (so it runs in CI). It
+// validates the three surfaces Claude Code actually reads:
+//   1. .claude-plugin/plugin.json  — manifest (name, version, commands/skills paths)
+//   2. hooks/hooks.json            — every `${CLAUDE_PLUGIN_ROOT}/...` target must exist
+//   3. component files             — commands/*.md and skills/*/SKILL.md must be REAL
+//      (a .gitkeep alone is not a surface — a plugin with zero commands/skills must fail)
+// plus marketplace↔plugin name parity and that the marketplace `source` resolves to a
+// dir holding .claude-plugin/plugin.json.
+//
+// For a deep, real load check on a dev machine: `claude --plugin-dir . plugin list`.
+// That needs Claude Code installed, so it is NOT used here; this is the CI floor.
+//
+// Usage:
+//   node scripts/smoke-plugin.mjs               # smoke the repo's plugin
+//   node scripts/smoke-plugin.mjs --root <dir>  # point at a fixture (tests)
+//
+// Exit 0 = plugin surfaces are structurally valid. Exit 1 = a load-blocking problem.
+
+import { readFileSync, existsSync, statSync, readdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+function parseArgs(argv) {
+  const args = { root: null };
+  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];
+  }
+  return args;
+}
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+function isDir(p) {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function isFile(p) {
+  try {
+    return statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function smoke(root) {
+  const errors = [];
+  const notes = [];
+  const fail = (msg) => errors.push(msg);
+
+  // 1. plugin.json manifest.
+  let plugin = null;
+  const pluginPath = join(root, '.claude-plugin', 'plugin.json');
+  try {
+    plugin = JSON.parse(readFileSync(pluginPath, 'utf-8'));
+  } catch (err) {
+    fail(`.claude-plugin/plugin.json: ${err?.message ?? err}`);
+  }
+  if (plugin) {
+    if (typeof plugin.name !== 'string' || !plugin.name) fail('plugin.json: missing "name"');
+    if (typeof plugin.version !== 'string' || !plugin.version)
+      fail('plugin.json: missing "version"');
+    // commands/skills are declared as relative dir paths; if declared they must resolve.
+    for (const key of ['commands', 'skills']) {
+      if (plugin[key] != null) {
+        const rel = String(plugin[key]).replace(/^\.\//, '');
+        if (!isDir(join(root, rel)))
+          fail(`plugin.json: "${key}" path "${plugin[key]}" is not a directory`);
+      }
+    }
+  }
+
+  // 2. Component files must be REAL regular files, not just a .gitkeep placeholder
+  // (or a directory that happens to be named like a component — isFile, not exists).
+  const commandsMd = isDir(join(root, 'commands'))
+    ? readdirSync(join(root, 'commands')).filter(
+        (f) => f.endsWith('.md') && isFile(join(root, 'commands', f)),
+      )
+    : [];
+  if (commandsMd.length === 0) fail('commands/: no *.md command files (only a placeholder?)');
+  else notes.push(`commands: ${commandsMd.length}`);
+
+  let skillCount = 0;
+  if (isDir(join(root, 'skills'))) {
+    for (const entry of readdirSync(join(root, 'skills'))) {
+      if (isFile(join(root, 'skills', entry, 'SKILL.md'))) skillCount++;
+    }
+  }
+  if (skillCount === 0) fail('skills/: no */SKILL.md skills (only a placeholder?)');
+  else notes.push(`skills: ${skillCount}`);
+
+  // 3. hooks/hooks.json — every command target AND every `shared` file must be a
+  // real regular file on disk. hooks.json is the hook source of truth, so a missing
+  // hypo-shared.mjs / version-check.mjs would pass a manifest-only check but break
+  // hook imports at runtime.
+  const hooksPath = join(root, 'hooks', 'hooks.json');
+  if (!existsSync(hooksPath)) {
+    fail('hooks/hooks.json: missing');
+  } else {
+    let hooksJson = null;
+    try {
+      hooksJson = JSON.parse(readFileSync(hooksPath, 'utf-8'));
+    } catch (err) {
+      fail(`hooks/hooks.json: ${err?.message ?? err}`);
+    }
+    if (hooksJson) {
+      if (!hooksJson.hooks || typeof hooksJson.hooks !== 'object') {
+        fail('hooks/hooks.json: missing top-level "hooks" object');
+      } else {
+        const targets = new Set();
+        for (const groups of Object.values(hooksJson.hooks)) {
+          for (const group of groups || []) {
+            for (const hk of group?.hooks || []) {
+              if (hk?.command) {
+                // command looks like `node ${CLAUDE_PLUGIN_ROOT}/hooks/foo.mjs [args]`
+                const m = String(hk.command).match(/\$\{CLAUDE_PLUGIN_ROOT\}\/(\S+)/);
+                if (m) targets.add(m[1]);
+              }
+            }
+          }
+        }
+        if (targets.size === 0)
+          fail('hooks/hooks.json: no ${CLAUDE_PLUGIN_ROOT} command targets found');
+        for (const rel of targets) {
+          if (!isFile(join(root, rel))) fail(`hooks/hooks.json: target "${rel}" is not a file`);
+        }
+        notes.push(`hook targets: ${targets.size}`);
+      }
+      // `shared` lists hook-relative support files that the targets import.
+      if (Array.isArray(hooksJson.shared)) {
+        for (const shared of hooksJson.shared) {
+          if (!isFile(join(root, 'hooks', shared)))
+            fail(`hooks/hooks.json: shared file "hooks/${shared}" is not a file`);
+        }
+        notes.push(`shared: ${hooksJson.shared.length}`);
+      }
+    }
+  }
+
+  // 4. marketplace.json — name parity + source resolves.
+  const mpPath = join(root, '.claude-plugin', 'marketplace.json');
+  let mp = null;
+  try {
+    mp = JSON.parse(readFileSync(mpPath, 'utf-8'));
+  } catch (err) {
+    fail(`.claude-plugin/marketplace.json: ${err?.message ?? err}`);
+  }
+  if (mp) {
+    const plugins = Array.isArray(mp.plugins) ? mp.plugins : [];
+    if (plugins.length === 0) fail('marketplace.json: "plugins" is empty');
+    const name = plugin?.name;
+    if (name) {
+      const matches = plugins.filter((p) => p && p.name === name);
+      if (matches.length !== 1) {
+        fail(
+          `marketplace.json: expected exactly one entry named "${name}", found ${matches.length}`,
+        );
+      } else {
+        const src = matches[0].source ?? './';
+        const srcDir = join(root, String(src).replace(/^\.\//, ''));
+        if (!existsSync(join(srcDir, '.claude-plugin', 'plugin.json'))) {
+          fail(
+            `marketplace.json: source "${src}" does not resolve to a dir containing .claude-plugin/plugin.json`,
+          );
+        }
+      }
+    }
+  }
+
+  return { errors, notes };
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const root = args.root || REPO_ROOT;
+  const { errors, notes } = smoke(root);
+
+  if (errors.length) {
+    for (const e of errors) console.error(`  ✗ ${e}`);
+    console.error(`\n✗ plugin smoke failed (${errors.length} problem(s)).`);
+    process.exit(1);
+  }
+  console.log(`✓ plugin surfaces valid (${notes.join(', ')}).`);
+  process.exit(0);
+}
+
+main();

package/scripts/stats.mjs

@@ -16,7 +16,7 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
 import { join, extname } from 'path';
 import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
-import { loadHypoIgnore, isIgnored } from './lib/hypo-ignore.mjs';
+import { loadHypoIgnore, isIgnored, isScanIgnored } from './lib/hypo-ignore.mjs';
 
 // ── arg parsing ──────────────────────────────────────────────────────────────
 
@@ -37,7 +37,7 @@ function collectMdFiles(dir, acc = [], hypoDir = '', ignorePatterns = []) {
   for (const entry of readdirSync(dir)) {
     if (entry.startsWith('.')) continue;
     const full = join(dir, entry);
-    if (hypoDir && isIgnored(full, hypoDir, ignorePatterns)) continue;
+    if (hypoDir && isScanIgnored(full, hypoDir, ignorePatterns)) continue;
     const st = statSync(full);
     if (st.isDirectory()) collectMdFiles(full, acc, hypoDir, ignorePatterns);
     else if (extname(entry) === '.md') acc.push(full);
@@ -45,16 +45,25 @@ function collectMdFiles(dir, acc = [], hypoDir = '', ignorePatterns = []) {
   return acc;
 }
 
+// Local top-level-only extractor, behavior-aligned with lib/frontmatter.mjs:
+// skip indented / list lines, first-wins, strip a trailing `# comment`. Without
+// the comment strip a `failure_type: overreach # note` would aggregate under the
+// literal "overreach # note" key (FEAT-1). Kept local (not the shared import) to
+// hold stats' dependency surface flat per the FEAT-1 scope split.
 function parseFrontmatter(content) {
   const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
   if (!m) return null;
   const fm = {};
-  for (const line of m[1].split('\n')) {
+  for (const line of m[1].split(/\r?\n/)) {
+    if (/^\s/.test(line) || /^-(\s|$)/.test(line)) continue; // nested / list item
     const idx = line.indexOf(':');
     if (idx < 0) continue;
-    fm[line.slice(0, idx).trim()] = line
+    const key = line.slice(0, idx).trim();
+    if (!key || Object.hasOwn(fm, key)) continue; // first-wins
+    fm[key] = line
       .slice(idx + 1)
       .trim()
+      .replace(/\s+#.*$/, '')
       .replace(/^["']|["']$/g, '');
   }
   return fm;
@@ -92,6 +101,7 @@ const sources = existsSync(join(args.hypoDir, 'sources'))
   : [];
 
 const typeCounts = {};
+const failureTypeCounts = {}; // FEAT-1: feedback pages carrying a failure_type
 let missingFrontmatter = 0;
 
 for (const f of pageFiles) {
@@ -108,6 +118,9 @@ for (const f of pageFiles) {
   }
   const t = fm.type || 'unknown';
   typeCounts[t] = (typeCounts[t] || 0) + 1;
+  if (t === 'feedback' && fm.failure_type) {
+    failureTypeCounts[fm.failure_type] = (failureTypeCounts[fm.failure_type] || 0) + 1;
+  }
 }
 
 let adrCount = 0;
@@ -122,6 +135,9 @@ const lastActivity = getLastActivity(args.hypoDir);
 
 const stats = {
   pages: { total: pageFiles.length, byType: typeCounts, missingFrontmatter },
+  // Omit the key entirely when no feedback page is classified (OQ-4: no empty
+  // section noise) so consumers can branch on presence.
+  ...(Object.keys(failureTypeCounts).length ? { failureTypes: failureTypeCounts } : {}),
   projects: projects.length,
   sources: sources.length,
   adrs: adrCount,
@@ -139,6 +155,10 @@ if (args.json) {
   if (missingFrontmatter) {
     console.log(`  missing frontmatter: ${missingFrontmatter}`);
   }
+  const ftEntries = Object.entries(failureTypeCounts).sort((a, b) => b[1] - a[1]);
+  if (ftEntries.length) {
+    console.log(`  failure types: ${ftEntries.map(([t, n]) => `${t} (${n})`).join(', ')}`);
+  }
   console.log(`Projects: ${projects.length}`);
   console.log(`Sources:  ${sources.length}`);
   console.log(`ADRs:     ${adrCount}`);

package/scripts/upgrade.mjs

@@ -42,6 +42,7 @@ import { fileURLToPath } from 'url';
 import { createHash } from 'crypto';
 import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
 import { parseFrontmatter } from './lib/frontmatter.mjs';
+import { templateSchemaVersion } from './lib/template-schema-version.mjs';
 import {
   readPkgJson as readPkgJsonSafe,
   writePkgJsonAtomic,
@@ -477,7 +478,14 @@ function writeMigrationReport(hypoDir, fromVersion, toVersion, { pluginMode = fa
   // right to keep SCHEMA.md as user-owned (Option C); auto-stub of the 9 new
   // fields is rejected because scope/tier/targets/sensitivity/reason/source
   // are semantic decisions whose wrong defaults would project wrong behavior.
-  const isV1ToV2 = fromVersion === '1.0' && toVersion === '2.0';
+  // Fire for any 1.x → 2.x major crossing, not just 1.0 → 2.0 exactly: the ADR
+  // 0031 feedback-field backfill that this body explains was introduced at 2.0
+  // and still applies to a user landing on any later 2.x (e.g. 2.1's additive
+  // failure_type — FEAT-1). Keying on the exact target string would silently
+  // drop this guidance the moment the template minor moves.
+  const fromV = parseVersion(fromVersion);
+  const toV = parseVersion(toVersion);
+  const isV1ToV2 = fromV?.major === 1 && toV?.major === 2;
   const specificBody = isV1ToV2
     ? `## What changed in SCHEMA 2.0
 
@@ -755,7 +763,7 @@ function applyCommands(commandResults, force) {
     ...existing,
     pkgRoot: PKG_ROOT,
     pkgVersion,
-    schemaVersion: '2.0',
+    schemaVersion: templateSchemaVersion(PKG_ROOT) ?? '2.1',
     commands: newSHAs,
   });
   return applied;
@@ -781,7 +789,7 @@ function writePluginModeMetadata() {
     ...existing,
     pkgRoot: PKG_ROOT,
     pkgVersion,
-    schemaVersion: '2.0',
+    schemaVersion: templateSchemaVersion(PKG_ROOT) ?? '2.1',
   });
   return true;
 }

package/scripts/verify.mjs

@@ -18,7 +18,7 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
 import { join, relative, extname } from 'path';
 import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
-import { loadHypoIgnore, isIgnored } from './lib/hypo-ignore.mjs';
+import { loadHypoIgnore, isScanIgnored } from './lib/hypo-ignore.mjs';
 
 // ── arg parsing ──────────────────────────────────────────────────────────────
 
@@ -40,7 +40,7 @@ function collectMdFiles(dir, acc = [], hypoDir = '', ignorePatterns = []) {
   for (const entry of readdirSync(dir)) {
     if (entry.startsWith('.')) continue;
     const full = join(dir, entry);
-    if (hypoDir && isIgnored(full, hypoDir, ignorePatterns)) continue;
+    if (hypoDir && isScanIgnored(full, hypoDir, ignorePatterns)) continue;
     const st = statSync(full);
     if (st.isDirectory()) collectMdFiles(full, acc, hypoDir, ignorePatterns);
     else if (extname(entry) === '.md') acc.push(full);

package/templates/SCHEMA.md

@@ -2,7 +2,7 @@
 title: Wiki Schema
 type: schema
 updated: YYYY-MM-DD
-version: 2.0
+version: 2.1
 ---
 
 # Wiki Schema
@@ -118,11 +118,35 @@ memory_summary: <one line for the MEMORY.md index>
 reason: <why this rule is needed>
 source: session:YYYY-MM-DD | commit:<hash> | pr:<n> | https://...
 
+# optional (2.1) — failure taxonomy for incident-driven corrections:
+failure_type: <enum>                     # one of the 8 values below; OMIT for pure
+                                         # preferences / new conventions ("always do X")
+
 # conditional — required when `targets` includes `claude-learned`:
 global_summary: <one line for the <learned_behaviors> entry>
 promote_to_global: true                  # explicit opt-in to global projection
 ```
 
+`failure_type` (optional, added 2.1) classifies feedback that came from a real
+failure incident so recurring mistake types become machine-aggregatable
+(surfaced by `hypomnema stats`). Leave it off when the page records a preference
+rather than a failure. The eight values, in classification-precedence order
+(most specific first — a failure matching several takes the earliest):
+
+| value | when |
+|-------|------|
+| `hallucination` | fabricated a fact / API / path |
+| `false-completion` | declared "done" without running the required gate or test |
+| `process-stall` | stopped instead of asking / continuing when it should have |
+| `over-caution` | re-asked or re-gated despite standing authority |
+| `overreach` | acted beyond the requested scope |
+| `incompleteness` | started correctly but omitted a required step or scope |
+| `instruction-miss` | ignored an explicit this-session instruction |
+| `convention-violation` | broke a standing documented convention (not restated) |
+
+`lint` rejects any value outside this set; an omitted `failure_type` is always
+allowed.
+
 Edit the feedback page only — never hand-edit the generated
 `<!-- HYPO:FEEDBACK-SYNC:START … -->` managed blocks (sync detects tampering as a conflict).
 

package/templates/hypo-config.md

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