wizz-method 2.0.0 → 2.1.0

package/tools/lib/sync-targets.mjs

@@ -0,0 +1,49 @@
+// sync-targets.mjs — fonte única da lista de sincronização repo → ~/.claude.
+//
+// Usado por tools/sync-global.mjs (escreve: repo → ~/.claude) e
+// tools/sync-check.mjs (só lê: compara hash repo vs ~/.claude, sem escrever).
+// Mudou o que sincroniza? Mude só aqui — os dois scripts leem a mesma lista,
+// então não podem driftar entre si (essa era exatamente a lacuna que gerou
+// a tarefa 2.7 da auditoria: o M10 aponta sync manual e esquecível).
+//
+// O que sincroniza hoje:
+//   1. Hooks:  tools/hooks/*.js e *.sh     → ~/.claude/hooks/
+//   2. Skills: src/skills-lib/<id>/        → ~/.claude/skills/<id>/
+//      (apenas skills que JÁ existem no destino — sync-global não instala
+//       skill nova, e sync-check só compara o que já está instalado)
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Diretório de origem dos hooks, dentro do repo. */
+export function hooksSrcDir(repoRoot) {
+  return path.join(repoRoot, 'tools', 'hooks');
+}
+
+/** Diretório de origem das skills, dentro do repo. */
+export function skillsSrcDir(repoRoot) {
+  return path.join(repoRoot, 'src', 'skills-lib');
+}
+
+/**
+ * Lista os arquivos de hook na origem (tools/hooks/*.js e *.sh).
+ * Retorna nomes de arquivo (não paths completos).
+ */
+export function listHookFiles(repoRoot) {
+  const src = hooksSrcDir(repoRoot);
+  if (!fs.existsSync(src)) return [];
+  return fs.readdirSync(src).filter((f) => f.endsWith('.js') || f.endsWith('.sh'));
+}
+
+/**
+ * Lista os ids de skill na origem (src/skills-lib/<id>/ com SKILL.md —
+ * exclui pastas auxiliares como references/ que não são skills em si).
+ */
+export function listSkillIds(repoRoot) {
+  const src = skillsSrcDir(repoRoot);
+  if (!fs.existsSync(src)) return [];
+  return fs.readdirSync(src).filter((id) => {
+    const dir = path.join(src, id);
+    return fs.statSync(dir).isDirectory() && fs.existsSync(path.join(dir, 'SKILL.md'));
+  });
+}

package/tools/lib/walk.js

@@ -0,0 +1,93 @@
+// Walk de arquivos/diretórios compartilhado pelos validadores do repo.
+//
+// M15 (auditoria 2026-07-07): `walkFiles` + skip-dirs estava reimplementado
+// de forma divergente em validate-method-refs.js e validate-file-refs.js, e
+// validate-skills.js tinha dois walks próprios (um de diretórios de skill,
+// outro de arquivos dentro de uma skill). Esta lib extrai o padrão comum
+// (recursão + skip-dirs) sem impor um comportamento único: cada chamador
+// passa as opções (`skipDirs`, `extensions`) que preservam o que já tinha.
+//
+// Uso: `require('../tools/lib/walk')` a partir de qualquer validador em
+// tools/*.js (CommonJS, igual aos validadores).
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DEFAULT_SKIP_DIRS = new Set(['node_modules', '.git']);
+
+/**
+ * Coleta recursivamente os caminhos de arquivo sob `root`.
+ *
+ * - Se `root` for um arquivo (não diretório), devolve `[root]` (respeitando
+ *   o filtro de extensão) — permite tratar um arquivo solto e um diretório
+ *   pela mesma chamada (comportamento herdado de
+ *   validate-method-refs.js:walkFiles, que recebe tanto `README.md` quanto
+ *   `docs/` na mesma lista `SCAN_ROOTS`).
+ * - `skipDirs`: nomes de diretório a pular, comparados com `entry.name`
+ *   (não é path completo). Default: `{node_modules, .git}`.
+ * - `extensions`: `Set<string>` de extensões (com ponto, ex: `.md`) a
+ *   incluir. Omitido/null = todos os arquivos (comportamento herdado de
+ *   validate-skills.js:collectSkillFiles, que não filtra por extensão).
+ *
+ * @param {string} root - Caminho absoluto (arquivo ou diretório)
+ * @param {{skipDirs?: Set<string>, extensions?: Set<string>|null}} [opts]
+ * @returns {string[]} Caminhos absolutos, em ordem de descoberta (não ordenado)
+ */
+function walkFiles(root, opts = {}) {
+  const skipDirs = opts.skipDirs || DEFAULT_SKIP_DIRS;
+  const extensions = opts.extensions || null;
+  if (!fs.existsSync(root)) return [];
+
+  const matches = (file) => !extensions || extensions.has(path.extname(file));
+
+  const stat = fs.statSync(root);
+  if (stat.isFile()) return matches(root) ? [root] : [];
+
+  const files = [];
+  const walk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (skipDirs.has(entry.name)) continue;
+        walk(path.join(dir, entry.name));
+      } else if (entry.isFile()) {
+        const full = path.join(dir, entry.name);
+        if (matches(full)) files.push(full);
+      }
+    }
+  };
+  walk(root);
+  return files;
+}
+
+/**
+ * Encontra, recursivamente sob cada diretório em `rootDirs`, os diretórios
+ * que contêm diretamente o arquivo `markerFile` (ex.: `SKILL.md`). Continua
+ * descendo mesmo depois de achar um marcador (skills podem estar aninhadas).
+ *
+ * Usado por validate-skills.js:discoverSkillDirs para descobrir skills sem
+ * reimplementar o walk de novo.
+ *
+ * @param {string[]} rootDirs - Diretórios raiz onde procurar
+ * @param {string} markerFile - Nome do arquivo marcador (ex.: 'SKILL.md')
+ * @param {{skipDirs?: Set<string>}} [opts]
+ * @returns {string[]} Diretórios (absolutos) que contêm o marcador, ordenados
+ */
+function findDirsWithFile(rootDirs, markerFile, opts = {}) {
+  const skipDirs = opts.skipDirs || DEFAULT_SKIP_DIRS;
+  const found = [];
+
+  const walk = (dir) => {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isDirectory() || skipDirs.has(entry.name)) continue;
+      const full = path.join(dir, entry.name);
+      if (fs.existsSync(path.join(full, markerFile))) found.push(full);
+      walk(full);
+    }
+  };
+
+  for (const rootDir of rootDirs) walk(rootDir);
+  return found.sort();
+}
+
+module.exports = { walkFiles, findDirsWithFile, DEFAULT_SKIP_DIRS };

package/wizz-modules.yaml

@@ -41,6 +41,15 @@
 # An existing install recorded under an alias resolves to this entry instead of
 # being orphaned as "no source available" when the code changes.
 #
+# interface_version (optional, in the MODULE's own module.yaml, not in this
+# file) — the version of the module.yaml contract the module was written
+# against (auditoria 2026-09-11, item 25; see
+# tools/installer/modules/module-interface.js). Omit it and the installer
+# treats the module as interface_version 1 (every module written before this
+# contract existed). The installer refuses to install a module declaring an
+# interface_version higher than it supports, with a message telling the user
+# to update wizz-method or use a compatible module version.
+#
 # ─────────────────────────────────────────────────────────────────────────────
 # NOT LISTED HERE: bundled local modules.
 # ─────────────────────────────────────────────────────────────────────────────

package/src/scripts/memlog.py

@@ -1,233 +0,0 @@
-#!/usr/bin/env python3
-# /// script
-# requires-python = ">=3.8"
-# ///
-"""memlog — an append-only memory log: LLM-optimal working memory for a skill.
-
-A memlog is the dense, chronological record of everything that mattered in a piece of
-work — every item the user generated or accepted — kept minimal like human memory: only
-what's important, never bloated. It persists ACROSS sessions, so a fresh session can
-load it and continue. It is NOT a deliverable; downstream artifacts (a brief, a PRD, a
-deck, a report) are *derived* from it on demand. The host skill supplies the vocabulary
-by how it calls `append` — the tool stays neutral.
-
-It is a FLAT log: there are no sections or grouping. Every entry is one line, recorded
-at the END in the order it happened. The chronology itself is the structure — an event
-like "started technique X" is just another entry, same as an idea or an insight.
-
-Three invariants make it trustworthy:
-
-  1. Append-only, chronological. Entries land at the end, in the order they happen.
-     Nothing is ever inserted backward, reordered, edited, or removed. There is no
-     edit or delete subcommand by design; history is never rewritten.
-  2. Write-only / blind. Every command is an atomic, context-free write and echoes the
-     new state as one line of JSON, so the caller never re-reads the file mid-session.
-     The one time the file is read is on resume — and the caller reads it itself, not
-     via this script.
-  3. No lifecycle status. A memory log has no "complete" flag. Whether the work is done,
-     blocked, or paused is itself a fact that happened, so it is recorded as an entry
-     (e.g. `append --type event --text "session complete"`), never as frontmatter the
-     log would have to mutate. The chronology stays the single source of truth, and a
-     resume learns the state by reading the last entries — the same way it learns
-     everything else.
-
-Atomicity: every write goes to a temp file, is flushed and fsync'd, then atomically
-renamed over the target, so a crash never leaves a half-written entry.
-
-Known limitation (by design, not a bug): there is no compaction, archival, or size
-cap. Append-only + no lifecycle status (invariant 3 above) means a `.memlog.md` grows
-without bound for the life of the workspace — fine for a single brainstorm/spec/
-architecture session (dozens to low hundreds of entries), but a caller resuming a very
-long-running or repeatedly-reused workspace pays an ever-larger read on every resume.
-If that ever becomes a real problem, the fix is a new host-skill-driven step (e.g.
-"archive entries older than the last milestone to a sibling file"), not a change to
-this script's invariants — memlog stays a dumb, trustworthy, append-only primitive.
-
-The file shape (.memlog.md):
-
-    ---
-    topic: Onboarding flow for a budgeting app
-    goal: lift week-1 retention
-    updated: 2026-06-07T14:22
-    ---
-
-    - (note) user picked techniques: SCAMPER, then Six Thinking Hats
-    - (technique) started SCAMPER
-    - (idea) skip the signup wall: let people try with sample data first
-    - (idea) auto-import one bank account so the first screen shows real numbers
-    - (question) is open-banking consent too heavy for step one?
-    - (insight) the "scary numbers" risk and the "real numbers" idea are one lever: show real data, pre-categorized
-    - (direction) optimize for the anxious first-timer, not the power user
-    - (decision) lead with one pre-categorized account; defer multi-account import
-    - (event) session complete
-
-Each entry may carry an optional `--type` — what KIND it is (idea, insight, question,
-decision, direction, assumption, gap, note, event, …) — and an optional `--by` naming
-who it came from (e.g. `user`, `coach`), for sessions where authorship matters. Both
-render into one short inline tag: `(idea)`, `(idea by user)`, `(by coach)`. Omit them
-for a plain note. The host skill names the vocabulary; the script does not enforce one.
-
-Commands:
-  init   (--workspace DIR | --path FILE) [--field k=v ...]    create the memlog (errors if it exists)
-  append (--workspace DIR | --path FILE) --text STR [--type T] [--by W]  append one entry at the end
-  set    (--workspace DIR | --path FILE) --key K --value V    set/replace a descriptive frontmatter field
-
-Addressing: `--workspace` is the run folder, and the memlog is always {workspace}/.memlog.md.
-`--path` points straight at the memlog file instead, for callers that already hold the path.
-"""
-from __future__ import annotations  # keep type-hint syntax lazy so the script runs on 3.8+
-
-import argparse
-import json
-import os
-import sys
-from datetime import datetime
-from pathlib import Path
-
-MEMLOG = ".memlog.md"
-
-
-def now() -> str:
-    return datetime.now().strftime("%Y-%m-%dT%H:%M")
-
-
-def resolve(args) -> Path:
-    """The memlog file, from either addressing mode: {workspace}/.memlog.md or an explicit --path."""
-    return Path(args.path) if args.path else Path(args.workspace) / MEMLOG
-
-
-def split(text: str) -> tuple[dict, str]:
-    """Return (frontmatter dict in source order, body str). Frontmatter is plain key: value.
-
-    The closing fence is the first line that is *exactly* `---`, so a `---` inside a
-    field value (topic/goal are free user text) never truncates the frontmatter.
-    """
-    lines = text.splitlines()
-    if not lines or lines[0] != "---":
-        raise ValueError(".memlog.md has no frontmatter")
-    end = next((i for i in range(1, len(lines)) if lines[i] == "---"), None)
-    if end is None:
-        raise ValueError(".memlog.md frontmatter is not terminated")
-    meta: dict[str, str] = {}
-    for line in lines[1:end]:
-        if ":" in line:
-            k, v = line.split(":", 1)
-            meta[k.strip()] = v.strip()
-    return meta, "\n".join(lines[end + 1:]).lstrip("\n")
-
-
-def render(meta: dict, body: str) -> str:
-    # Neutralize newlines in values so a multi-line field can't break the fence on re-read.
-    fm = "\n".join(f"{k}: {' '.join(str(v).splitlines())}" for k, v in meta.items())
-    return "---\n" + fm + "\n---\n\n" + body.rstrip("\n") + "\n"
-
-
-def touch(meta: dict) -> None:
-    """Stamp `updated` and keep it last so the field order stays predictable."""
-    meta.pop("updated", None)
-    meta["updated"] = now()
-
-
-def write_atomic(path: Path, text: str) -> None:
-    """Temp + flush + fsync + atomic rename, so a crash never half-writes an entry."""
-    tmp = path.with_suffix(path.suffix + ".tmp")
-    with open(tmp, "w", encoding="utf-8") as f:
-        f.write(text)
-        f.flush()
-        os.fsync(f.fileno())
-    os.replace(tmp, path)
-
-
-def entry_count(body: str) -> int:
-    return sum(1 for ln in body.splitlines() if ln.startswith("- "))
-
-
-def ack(path: Path, body: str) -> None:
-    """Echo new state so the caller never re-reads the file to know where it stands."""
-    print(json.dumps({
-        "ok": True,
-        "memlog": str(path),
-        "entries": entry_count(body),
-    }))
-
-
-def cmd_init(args) -> int:
-    path = resolve(args)
-    if path.exists():
-        print(f"error: {path} already exists; use append/set to update it", file=sys.stderr)
-        return 2
-    path.parent.mkdir(parents=True, exist_ok=True)
-    meta: dict[str, str] = {}
-    for pair in args.field or []:
-        if "=" not in pair:
-            print(f"error: --field expects key=value, got {pair!r}", file=sys.stderr)
-            return 2
-        k, v = pair.split("=", 1)
-        meta[k.strip()] = v.strip()
-    touch(meta)
-    write_atomic(path, render(meta, ""))
-    ack(path, "")
-    return 0
-
-
-def cmd_append(args) -> int:
-    path = resolve(args)
-    meta, body = split(path.read_text(encoding="utf-8"))
-    text = " ".join(args.text.split())  # collapse newlines/runs → one-line entry, no prose bloat
-    label = args.type or ""
-    if args.by:
-        label = f"{label} by {args.by}".strip()  # attribution: "(idea by user)" / "(by coach)"
-    tag = f"({label}) " if label else ""
-    entry = f"- {tag}{text}"
-    body = (body.rstrip("\n") + "\n" + entry) if body.strip() else entry  # always at the end
-    touch(meta)
-    write_atomic(path, render(meta, body))
-    ack(path, body)
-    return 0
-
-
-def cmd_set(args) -> int:
-    path = resolve(args)
-    meta, body = split(path.read_text(encoding="utf-8"))
-    meta[args.key] = args.value
-    touch(meta)
-    write_atomic(path, render(meta, body))
-    ack(path, body)
-    return 0
-
-
-def add_target(sp) -> None:
-    """Every command addresses the memlog the same way: a run folder or an explicit path."""
-    g = sp.add_mutually_exclusive_group(required=True)
-    g.add_argument("--workspace", help="run folder; the memlog is {workspace}/.memlog.md")
-    g.add_argument("--path", help="explicit memlog file path (alternative to --workspace)")
-
-
-def main(argv: list[str] | None = None) -> int:
-    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
-    sub = p.add_subparsers(dest="cmd", required=True)
-
-    pi = sub.add_parser("init", help="create the memlog")
-    add_target(pi)
-    pi.add_argument("--field", action="append", metavar="KEY=VALUE", help="frontmatter field (repeatable)")
-    pi.set_defaults(func=cmd_init)
-
-    pa = sub.add_parser("append", help="append one entry at the end")
-    add_target(pa)
-    pa.add_argument("--text", required=True)
-    pa.add_argument("--type", help="entry kind, rendered as an inline tag")
-    pa.add_argument("--by", help="who the entry came from (e.g. user, coach); rendered into the tag")
-    pa.set_defaults(func=cmd_append)
-
-    pset = sub.add_parser("set", help="set a descriptive frontmatter field")
-    add_target(pset)
-    pset.add_argument("--key", required=True)
-    pset.add_argument("--value", required=True)
-    pset.set_defaults(func=cmd_set)
-
-    args = p.parse_args(argv)
-    return args.func(args)
-
-
-if __name__ == "__main__":
-    sys.exit(main())