@inetafrica/open-claudia 2.6.59 → 2.7.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## v2.7.0
+- **Tools become memory objects (tool-first architecture, Phase 1).** A tool is no longer a flat script — it's a directory: `tools/<name>/tool` (the executable), `TOOL.md` (Interface · Known issues · State · Journal — the curated, human-readable condition of the tool), and `state.json` (machine telemetry, runtime-written, gitignored). The tools dir is now a **git repository**: every add, metadata change, note, and removal auto-commits (with a per-invocation identity, never touching git config), so `git log` *is* the upgrade history and any change is one revert from undone. `tool show` is tiered disclosure: header metadata, live telemetry, TOOL.md, and the recent commit log — the source only with `--source`, so reading about a tool no longer costs its whole body in context.
+- **Risk tiers + run gate.** Every tool declares `risk: read-only | write | destructive` in its header (absent = treated as write, fail-safe). `tool run` now enforces the ask-first rule mechanically: read-only runs freely; write requires `--yes`; destructive requires `--yes-destructive` — and a plain `--yes` does **not** unlock a destructive tool. Refusals exit 3 with a clear message. The flags pass through to the tool unstripped, so tools with their own confirmation gates (e.g. prod-k8s) keep working. `tool add`/`tool set` accept `--risk`; adding without it defaults to write and says so.
+- **Run telemetry stamped at the point of use.** `tool run` itself records every execution into the tool's `state.json`: run count, last used, last exit, last success/failure, per-verb health (first non-flag arg), and a rolling history of the last 20 invocations with timing. A failing run prints a nudge to journal the defect (`tool note <name> --issue "..."`). This is the v1.2 health doctrine in code: no smoke tests, no health crons — health is verified by use, and breakage is captured automatically where it happens.
+- **`tool scaffold`, `tool note`, `tool migrate`.** `scaffold <name>` creates a ready-to-extend verb-dispatch stub (node or bash) with full header, TOOL.md skeleton, and initial telemetry — and refuses if the tool exists ("extend it instead"). `note <name> --issue|--state|--journal` maintains TOOL.md from the CLI: issues and journal lines insert newest-first; `--state` rewrites the State section (it describes *now*, not history). `migrate` converts legacy flat-file tools into directories — one commit each, sidecar telemetry carried over, TOOL.md generated — and runs automatically on first CLI use, so existing tools arrive in the new layout with their memory intact.
+- **Secrets can no longer be saved into a tool.** The add-time secret lint is now **blocking** (was advisory): `tool add`, `tool set`, and `tool note` refuse content matching credential patterns, because the git-backed dir would remember the secret forever. Other lints (requires mismatch, syntax check, dangling pack) stay advisory. Extends `test-tools.js` end to end: layout, risk gate matrix, per-verb telemetry, secret refusal, migration, scaffold, git history.
+
 ## v2.6.58
 - **Tiered recall gate — stop paying 15 seconds for "thanks".** Measured over 700+ live turns, the old discoverer pre-gate returned true whenever *any* seed matched, so it gated just 0.4% of turns — a bare "ok" with an incidental keyword hit still paid the full seed → graph → walker pass (p50 ~15s). A new `recallTier()` classifies each turn into three tiers: **skip** (pleasantries/acks up to 4 words *regardless of seeds*, emoji-only, or ≤2 words with no seeds — no recall at all), **seeds** (short command-like turns ≤4 words — user-origin keyword seeds inject directly with no graph expansion, no walker, no excerpts; the classic-engine baseline at ~ms cost), and **full** (substantive turns — the whole pipeline). The tier is logged per turn and the metrics summary now tracks the seeds-only share alongside the gated share.
 - **Walker candidate cap.** The latency deep-dive showed the walk itself dominates, not process spawn: 15–40 candidates × 600-char excerpts = 10–25KB prompts to the haiku judge on every substantive turn. Full-tier candidates are now priority-ordered — user-origin seeds by match score, then context seeds, then graph-activated nodes by activation — and capped at `RECALL_WALKER_MAX_CANDIDATES` (default 14), so the judge reads the strongest few instead of everything the graph touched.

package/bin/cli.js

@@ -374,7 +374,7 @@ Memory tools:
   open-claudia transcript-window <pattern>   Search project transcript, show hits with context
                                              (alias: tw; --help for options)
   open-claudia pack list|show|match|archive|restore|archived  Context packs: living topic docs (skills + memory)
-  open-claudia tool list|search|show|add|set|edit|run|remove Reusable tools: executable scripts the agent saves & re-runs (keyring preauth)
+  open-claudia tool list|search|show|scaffold|add|set|note|edit|run|migrate|remove  Reusable tools: git-tracked dirs (exec + TOOL.md + telemetry), risk-gated runs
   open-claudia entity list|show|match|note   Entity notes: people/places/projects memory
   open-claudia lessons list|add|remove|show  Always-loaded learned rules (cross-cutting, promoted after a miss)
   open-claudia ideas list|add|remove|show    Self-improvement backlog (captured by the nightly dream)

package/bin/tool.js

@@ -1,23 +1,38 @@
-// CLI: manage and run reusable tools — executable scripts the agent saves so a
-// procedure it worked out once becomes a re-runnable command, not a re-typed
-// heredoc. The executable sibling of context packs (`open-claudia pack`).
+// CLI: manage and run reusable tools — the interface operational work happens
+// through. Tool-first loop: search → exists: use it → missing a verb: extend →
+// nothing: scaffold, then work through the tool.
 //
 //   open-claudia tool list                       — index (name — description [skill])
 //   open-claudia tool search <query>             — lexical match (find before adding a dup)
-//   open-claudia tool show <name>                — full docs, path, keyring status
-//   open-claudia tool add <path> [--name n]      — register a script as a tool
-//       [--pack <dir>] [--desc "..."] [--requires "k1,k2"] [--usage "..."]
+//   open-claudia tool show <name> [--source]     — TOOL.md, telemetry, history (source with --source)
+//   open-claudia tool scaffold <name>            — create a new tool skeleton (dir + stub + TOOL.md)
+//       [--pack <dir>] [--desc "..."] [--risk read-only|write|destructive]
+//       [--requires "k1,k2"] [--usage "..."] [--lang node|bash]
+//   open-claudia tool add <path> [--name n]      — register an existing script as a tool
+//       [--pack <dir>] [--desc "..."] [--risk tier] [--requires "k1,k2"] [--usage "..."]
 //   open-claudia tool set <name> [--desc ...]    — fix a tool's metadata in place
-//       [--pack <dir>] [--requires "k1,k2"] [--usage "..."]
+//       [--pack <dir>] [--risk tier] [--requires "k1,k2"] [--usage "..."]
+//   open-claudia tool note <name>                — append to TOOL.md (auto-committed)
+//       [--issue "..."] [--state "..."] [--journal "..."]
 //   open-claudia tool edit <name>                — print the file path to open & edit
-//   open-claudia tool run <name> [args...]       — run it with keyring pre-loaded
+//   open-claudia tool run <name> [args...]       — run it (keyring pre-loaded, risk-gated)
+//   open-claudia tool migrate                    — convert legacy flat-file tools to directories
 //   open-claudia tool remove <name>              — delete one
 //   open-claudia tool path                       — print the tools directory
 //
-// Fix before fork: when a tool is wrong, prefer `tool set` (metadata) or `tool
-// edit` (open the file) over adding a near-duplicate. `add` lints the source on
-// save — flags hardcoded secrets, requires/keyring mismatches, syntax errors,
-// and dangling pack links — all advisory, never blocking.
+// A tool is a directory: executable + TOOL.md (Interface · Known issues ·
+// State · Journal) + state.json (runtime telemetry). The dir is git-tracked;
+// every change commits, so `git -C $(open-claudia tool path) log` is the
+// upgrade history.
+//
+// Risk tiers gate `tool run`: write-tier needs --yes, destructive-tier needs
+// --yes-destructive — get the user's approval first; the flag records that
+// deliberate step. Read-only tools run freely.
+//
+// Fix before fork: when a tool is wrong, prefer `tool set` (metadata), `tool
+// note` (docs), or `tool edit` (body) over adding a near-duplicate. Hardcoded
+// secrets BLOCK a save; other lints (requires/keyring mismatch, syntax,
+// dangling pack link) stay advisory.
 //
 // Credentials: a tool runs with the operational keyring merged into its env, so
 // reference creds as $NAME inside the script. `open-claudia keyring list` shows
@@ -25,6 +40,7 @@
 
 const { spawnSync } = require("child_process");
 const tools = require("../core/tools");
+const repo = require("../core/tool-repo");
 
 // Minimal flag parser: pulls --key value (and --key=value) out of argv, returns
 // { positional, flags }.
@@ -88,6 +104,17 @@ function run(args) {
   const cmd = (args[0] || "list").toLowerCase();
   const rest = args.slice(1);
 
+  // Auto-migrate legacy flat-file tools to the directory layout on first use
+  // (idempotent, one git commit per tool, telemetry carried over).
+  if (cmd !== "path") {
+    try {
+      if (repo.hasLegacyTools()) {
+        const { migrated } = repo.migrateLegacyTools();
+        if (migrated.length) console.error(`(migrated ${migrated.length} tool(s) to directory layout: ${migrated.join(", ")})`);
+      }
+    } catch (e) { /* best-effort */ }
+  }
+
   switch (cmd) {
     case "list":
     case "ls": {
@@ -98,7 +125,8 @@ function run(args) {
       console.log(`${all.length} reusable tool(s) — run via 'open-claudia tool run <name>':\n`);
       for (const t of all) {
         const skill = t.pack ? `  [skill: ${t.pack}]` : "";
-        console.log(`• ${t.name} — ${t.description || "(no description)"}${skill}`);
+        const risk = t.risk === "read-only" ? "" : `  [${t.risk || "write?"}]`;
+        console.log(`• ${t.name} — ${t.description || "(no description)"}${skill}${risk}`);
       }
       console.log(`\nDocs: open-claudia tool show <name>   ·   Dir: ${tools.TOOLS_DIR}`);
       break;
@@ -125,13 +153,15 @@ function run(args) {
 
     case "show":
     case "cat": {
-      const name = rest[0];
-      if (!name) { console.error("Usage: tool show <name>"); process.exitCode = 1; return; }
+      const { positional, flags } = parseFlags(rest);
+      const name = positional[0];
+      if (!name) { console.error("Usage: tool show <name> [--source]"); process.exitCode = 1; return; }
       const t = tools.findTool(name);
       if (!t) { console.error(`No tool named "${name}". Run: open-claudia tool list`); process.exitCode = 1; return; }
       console.log(`Tool: ${t.name}`);
       if (t.description) console.log(`Description: ${t.description}`);
       if (t.pack) console.log(`Skill pack: ${t.pack}  (open-claudia pack show ${t.pack})`);
+      console.log(`Risk: ${t.risk || "(undeclared — treated as write)"}`);
       console.log(`Usage: open-claudia tool run ${t.name}${t.usage ? "   (" + t.usage + ")" : ""}`);
       if (t.requires.length) {
         const missing = tools.missingRequires(t);
@@ -139,6 +169,22 @@ function run(args) {
         console.log(`Requires keyring keys: ${t.requires.join(", ")}  (${status})`);
       }
       console.log(`File: ${t.file}${t.executable ? "" : "  (not executable!)"}`);
+
+      // Telemetry: overall + per-verb health from state.json.
+      if (t.runCount || t.lastUsed) {
+        const exit = t.lastExit === undefined ? "" : ` · last exit ${t.lastExit}`;
+        console.log(`Runs: ${t.runCount}${t.lastUsed ? ` · last used ${t.lastUsed.slice(0, 16).replace("T", " ")}` : ""}${exit}`);
+      }
+      if (t.verbs && Object.keys(t.verbs).length) {
+        const rows = Object.entries(t.verbs).map(([v, s]) =>
+          `  • ${v}: ${s.runs} run(s), last exit ${s.lastExit}${s.lastSuccess ? `, last success ${s.lastSuccess.slice(0, 10)}` : ""}`);
+        console.log("Verbs:\n" + rows.join("\n"));
+      }
+      try {
+        const log = repo.toolLog(t.name, 5);
+        if (log.length) console.log("Recent changes:\n" + log.map((l) => "  " + l).join("\n"));
+      } catch (e) { /* git optional */ }
+
       // Directed tool-graph: what tends to run right after / before this one.
       try {
         const graph = require("../core/tool-graph");
@@ -156,7 +202,13 @@ function run(args) {
           }
         }
       } catch (e) { /* graph optional (old node) */ }
-      console.log(`\n----- source -----\n${t.content}`);
+
+      // Tiered disclosure: TOOL.md is the manual; source only when modifying.
+      const doc = tools.readToolDoc(t.name);
+      if (doc) console.log(`\n----- TOOL.md -----\n${doc.trim()}`);
+      if (flags.source) console.log(`\n----- source -----\n${t.content}`);
+      else if (!doc) console.log(`\n----- source (no TOOL.md yet) -----\n${t.content}`);
+      else console.log(`\n(source: open-claudia tool show ${t.name} --source)`);
       break;
     }
 
@@ -173,10 +225,14 @@ function run(args) {
           name: typeof flags.name === "string" ? flags.name : undefined,
           pack: typeof flags.pack === "string" ? flags.pack : undefined,
           description: typeof flags.desc === "string" ? flags.desc : (typeof flags.description === "string" ? flags.description : undefined),
+          risk: typeof flags.risk === "string" ? flags.risk : undefined,
           requires: typeof flags.requires === "string" ? flags.requires.split(/[,\s]+/).filter(Boolean) : undefined,
           usage: typeof flags.usage === "string" ? flags.usage : undefined,
         });
-        console.log(`Saved tool "${t.name}"${t.pack ? ` (skill: ${t.pack})` : ""}.`);
+        console.log(`Saved tool "${t.name}"${t.pack ? ` (skill: ${t.pack})` : ""} — risk: ${t.risk}.`);
+        if (t.defaultedRisk) {
+          console.log(`  No --risk given → defaulted to "write" (runs will demand --yes). If it only reads, fix: open-claudia tool set ${t.name} --risk read-only`);
+        }
         console.log(`Run it: open-claudia tool run ${t.name}`);
         if (t.requires.length) {
           const missing = tools.missingRequires(t);
@@ -217,17 +273,21 @@ function run(args) {
       if (typeof flags.desc === "string") patch.description = flags.desc;
       else if (typeof flags.description === "string") patch.description = flags.description;
       if (typeof flags.pack === "string") patch.pack = flags.pack;
+      if (typeof flags.risk === "string") patch.risk = flags.risk;
       if (typeof flags.requires === "string") patch.requires = flags.requires.split(/[,\s]+/).filter(Boolean);
       if (typeof flags.usage === "string") patch.usage = flags.usage;
       if (Object.keys(patch).length === 0) {
-        console.error('Nothing to set. Pass at least one of --desc / --pack / --requires / --usage. Body edits: open-claudia tool edit ' + name);
+        console.error('Nothing to set. Pass at least one of --desc / --pack / --risk / --requires / --usage. Body edits: open-claudia tool edit ' + name);
         process.exitCode = 1; return;
       }
-      const updated = tools.updateToolHeader(name, patch);
+      let updated;
+      try { updated = tools.updateToolHeader(name, patch); }
+      catch (e) { console.error(`Could not update "${name}": ${e.message}`); process.exitCode = 1; return; }
       if (!updated) { console.error(`Could not update "${name}".`); process.exitCode = 1; return; }
       console.log(`Updated tool "${updated.name}".`);
       console.log(`  Description: ${updated.description || "(none)"}`);
       if (updated.pack) console.log(`  Skill pack:  ${updated.pack}`);
+      console.log(`  Risk:        ${updated.risk || "(undeclared — treated as write)"}`);
       if (updated.requires.length) console.log(`  Requires:    ${updated.requires.join(", ")}`);
       if (updated.usage) console.log(`  Usage:       ${updated.usage}`);
       reportSafety(updated);
@@ -252,14 +312,108 @@ function run(args) {
       if (!name) { console.error("Usage: tool run <name> [args...]"); process.exitCode = 1; return; }
       const t = tools.findTool(name);
       if (!t) { console.error(`No tool named "${name}". Run: open-claudia tool list`); process.exitCode = 1; return; }
+      const toolArgs = rest.slice(1);
+
+      // Risk-tier gate: write needs --yes, destructive needs --yes-destructive.
+      // The flag is passed through to the tool (which may have its own gate).
+      const gate = tools.runGate(t, toolArgs);
+      if (!gate.ok) { console.error(gate.message); process.exitCode = 3; return; }
+
       const missing = tools.missingRequires(t);
       if (missing.length) {
         console.error(`Cannot run ${t.name}: missing keyring keys ${missing.join(", ")}. Set them with 'open-claudia keyring set <name> <value>'.`);
         process.exitCode = 1; return;
       }
-      const r = spawnSync(t.file, rest.slice(1), { stdio: "inherit", env: tools.runEnv() });
-      if (r.error) { console.error(`Failed to run ${t.name}: ${r.error.message}`); process.exitCode = 1; return; }
-      process.exitCode = typeof r.status === "number" ? r.status : 1;
+      const started = Date.now();
+      const r = spawnSync(t.file, toolArgs, { stdio: "inherit", env: tools.runEnv() });
+      const ms = Date.now() - started;
+      if (r.error) {
+        tools.recordRunResult(t.name, { args: toolArgs, exit: -1, ms });
+        console.error(`Failed to run ${t.name}: ${r.error.message}`);
+        process.exitCode = 1; return;
+      }
+      const exit = typeof r.status === "number" ? r.status : 1;
+      tools.recordRunResult(t.name, { args: toolArgs, exit, ms });
+      if (exit !== 0) {
+        console.error(`(exit ${exit} recorded in ${t.name} telemetry — if this is a real defect, journal it: ` +
+          `open-claudia tool note ${t.name} --issue "<what broke>")`);
+      }
+      process.exitCode = exit;
+      break;
+    }
+
+    case "scaffold":
+    case "new": {
+      const { positional, flags } = parseFlags(rest);
+      const name = positional[0];
+      if (!name) {
+        console.error('Usage: tool scaffold <name> [--pack dir] [--desc "..."] [--risk read-only|write|destructive] [--requires "k1,k2"] [--usage "..."] [--lang node|bash]');
+        process.exitCode = 1; return;
+      }
+      try {
+        const t = repo.scaffoldTool(name, {
+          pack: typeof flags.pack === "string" ? flags.pack : undefined,
+          description: typeof flags.desc === "string" ? flags.desc : (typeof flags.description === "string" ? flags.description : undefined),
+          risk: typeof flags.risk === "string" ? flags.risk : undefined,
+          requires: typeof flags.requires === "string" ? flags.requires.split(/[,\s]+/).filter(Boolean) : [],
+          usage: typeof flags.usage === "string" ? flags.usage : undefined,
+          lang: typeof flags.lang === "string" ? flags.lang : "node",
+        });
+        console.log(`Scaffolded tool "${t.name}" (risk: ${t.risk}).`);
+        console.log(`  Executable: ${t.file}`);
+        console.log(`  Docs:       ${t.docFile}`);
+        console.log(`Fill in the verbs, then work through it: open-claudia tool run ${t.name} <verb>`);
+      } catch (e) {
+        console.error(`Could not scaffold: ${e.message}`); process.exitCode = 1;
+      }
+      break;
+    }
+
+    case "note": {
+      const { positional, flags } = parseFlags(rest);
+      const name = positional[0];
+      const issue = typeof flags.issue === "string" ? flags.issue : null;
+      const state = typeof flags.state === "string" ? flags.state : null;
+      const journal = typeof flags.journal === "string" ? flags.journal : null;
+      if (!name || (!issue && !state && !journal)) {
+        console.error('Usage: tool note <name> [--issue "..."] [--state "..."] [--journal "..."]');
+        process.exitCode = 1; return;
+      }
+      const t = tools.findTool(name);
+      if (!t) { console.error(`No tool named "${name}". Run: open-claudia tool list`); process.exitCode = 1; return; }
+      if (!t.docFile) { console.error(`"${t.name}" is a legacy flat tool — run any tool command to migrate it first.`); process.exitCode = 1; return; }
+      try {
+        tools.assertNoSecrets([issue, state, journal].filter(Boolean).join("\n"), "note");
+        const fs = require("fs");
+        let doc = tools.readToolDoc(t.name) || repo.toolMdSkeleton(t);
+        const date = new Date().toISOString().slice(0, 10);
+        const appendUnder = (heading, line) => {
+          const re = new RegExp(`(##\\s*${heading}[^\\n]*\\n)`, "i");
+          if (re.test(doc)) doc = doc.replace(re, `$1${line}\n`);
+          else doc += `\n## ${heading}\n${line}\n`;
+        };
+        if (issue) appendUnder("Known issues", `- [${date}] ${issue}`);
+        if (state) {
+          // State is a rewrite, not an append — it describes NOW.
+          const re = /(##\s*State[^\n]*\n)([\s\S]*?)(?=\n##\s|$)/i;
+          if (re.test(doc)) doc = doc.replace(re, `$1${state}\n\n`);
+          else doc += `\n## State\n${state}\n`;
+        }
+        if (journal) appendUnder("Journal", `- [${date}] ${journal}`);
+        fs.writeFileSync(t.docFile, doc, { mode: 0o600 });
+        repo.commitTool(t.name, `note ${t.name}: ${(issue || state || journal).slice(0, 60)}`);
+        console.log(`Noted in ${t.name}/TOOL.md${issue ? " (known issue)" : ""}${state ? " (state)" : ""}${journal ? " (journal)" : ""}.`);
+      } catch (e) {
+        console.error(`Could not note: ${e.message}`); process.exitCode = 1;
+      }
+      break;
+    }
+
+    case "migrate": {
+      const { migrated, skipped } = repo.migrateLegacyTools();
+      if (!migrated.length && !skipped.length) console.log("Nothing to migrate — all tools already use the directory layout.");
+      if (migrated.length) console.log(`Migrated: ${migrated.join(", ")}`);
+      if (skipped.length) console.log(`Skipped (no tool header — left untouched): ${skipped.join(", ")}`);
       break;
     }
 
@@ -277,7 +431,7 @@ function run(args) {
       break;
 
     default:
-      console.log('Usage: open-claudia tool [list | search <query> | show <name> | add <path> [flags] | set <name> [flags] | edit <name> | run <name> [args] | remove <name> | path]');
+      console.log('Usage: open-claudia tool [list | search <query> | show <name> [--source] | scaffold <name> [flags] | add <path> [flags] | set <name> [flags] | note <name> [flags] | edit <name> | run <name> [args] | migrate | remove <name> | path]');
   }
 }
 

package/core/tool-repo.js

@@ -0,0 +1,270 @@
+// Git-backed tool repository: every tool is a directory (executable + TOOL.md +
+// state.json) inside a git-initialised TOOLS_DIR, so `git log` IS the upgrade
+// history and any change is one revert from undone.
+//
+// Split from core/tools.js so the registry (read/parse/match) stays pure fs;
+// this module owns everything that shells out to git, plus the scaffold and
+// legacy-migration machinery that writes whole tool directories. Requires
+// between the two modules are lazy to tolerate the natural circularity.
+//
+// state.json is deliberately gitignored: it is runtime telemetry stamped on
+// every run — committing it would bury real code/doc changes in noise. The
+// curated, human-readable condition of a tool lives in TOOL.md's State section.
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const GIT_IDENT = ["-c", "user.name=open-claudia", "-c", "user.email=tools@open-claudia.local"];
+const GITIGNORE = ["*/state.json", ".usage.json", "__pycache__/", ".DS_Store", ""].join("\n");
+
+function toolsDir() {
+  return require("./tools").TOOLS_DIR;
+}
+
+function git(args, { ident = false } = {}) {
+  try {
+    const full = ["-C", toolsDir(), ...(ident ? GIT_IDENT : []), ...args];
+    const r = spawnSync("git", full, { encoding: "utf-8" });
+    if (r.error) return { ok: false, status: -1, stdout: "", stderr: String(r.error.message || r.error) };
+    return { ok: r.status === 0, status: r.status, stdout: (r.stdout || "").trim(), stderr: (r.stderr || "").trim() };
+  } catch (e) {
+    return { ok: false, status: -1, stdout: "", stderr: String(e.message || e) };
+  }
+}
+
+function gitAvailable() {
+  try { return !spawnSync("git", ["--version"], { encoding: "utf-8" }).error; }
+  catch (e) { return false; }
+}
+
+// Initialise the tools dir as a git repo (idempotent). Best-effort: on a box
+// without git everything else still works, there's just no history.
+function ensureRepo() {
+  const dir = toolsDir();
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const ignoreFile = path.join(dir, ".gitignore");
+  if (!fs.existsSync(ignoreFile)) { try { fs.writeFileSync(ignoreFile, GITIGNORE, { mode: 0o600 }); } catch (e) {} }
+  if (fs.existsSync(path.join(dir, ".git"))) return true;
+  if (!gitAvailable()) return false;
+  if (!git(["init", "-q"]).ok) return false;
+  git(["add", "-A"]);
+  git(["commit", "-q", "-m", "init tool repository"], { ident: true });
+  return true;
+}
+
+// Stage + commit one tool's paths (or everything with "."). No-op when the tree
+// is clean or git is unavailable. Every add/change/remove funnels through here.
+function commitTool(name, message) {
+  if (!ensureRepo()) return false;
+  const target = name ? require("./tools").sanitizeName(name) : ".";
+  if (!git(["add", "-A", "--", target || "."]).ok) return false;
+  const staged = git(["diff", "--cached", "--quiet"]);
+  if (staged.status === 0) return false; // nothing to commit
+  return git(["commit", "-q", "-m", message], { ident: true }).ok;
+}
+
+// Recent history for one tool — surfaced by `tool show` as the upgrade log.
+function toolLog(name, limit = 5) {
+  const n = require("./tools").sanitizeName(name);
+  if (!n || !fs.existsSync(path.join(toolsDir(), ".git"))) return [];
+  const r = git(["log", "--date=short", `--pretty=%ad %s`, "-n", String(limit), "--", n]);
+  return r.ok && r.stdout ? r.stdout.split("\n").filter(Boolean) : [];
+}
+
+// ── Scaffold ─────────────────────────────────────────────────────────────────
+
+function today() { return new Date().toISOString().slice(0, 10); }
+
+function toolMdSkeleton({ name, description, usage, risk, requires, pack, stateLine, journalLine }) {
+  return [
+    `# ${name}`,
+    "",
+    "## Interface",
+    description || "(describe what system this tool fronts)",
+    "",
+    `Usage: \`open-claudia tool run ${name}${usage ? " " + usage.replace(new RegExp("^" + name + "\\s*"), "") : " <verb> [args]"}\``,
+    `Risk: ${risk || "write"}${requires && requires.length ? ` · Requires: ${requires.join(", ")}` : ""}${pack ? ` · Pack: ${pack}` : ""}`,
+    "",
+    "## Known issues",
+    "(none yet)",
+    "",
+    "## State",
+    stateLine || `Scaffolded ${today()} — not yet proven against the live system.`,
+    "",
+    "## Journal",
+    `- [${today()}] ${journalLine || "Scaffolded."}`,
+    "",
+  ].join("\n");
+}
+
+function nodeStub({ name, description, pack, risk, requires, usage }) {
+  const req = requires && requires.length ? `// requires: ${requires.join(", ")}\n` : "";
+  return `#!/usr/bin/env node
+// open-claudia-tool: ${name}
+// description: ${description || ""}
+${pack ? `// pack: ${pack}\n` : ""}// risk: ${risk}
+${req}// usage: ${usage || `${name} <verb> [args]`}
+//
+// One CLI per system, verbs as subcommands. Add a function per verb below.
+// Confirmation flags (--yes / --yes-destructive) are enforced by the tool
+// runner and may appear in argv — ignore them unless you need them.
+
+const args = process.argv.slice(2).filter((a) => a !== "--yes" && a !== "--yes-destructive");
+const verb = args[0] || "help";
+
+const HANDLERS = {
+  help() {
+    console.log("${name} — ${(description || "").replace(/"/g, '\\"')}");
+    console.log("verbs: " + Object.keys(HANDLERS).join(", "));
+  },
+  // example(rest) { ... },
+};
+
+const fn = HANDLERS[verb] || (verb === "--help" ? HANDLERS.help : null);
+if (!fn) { console.error("unknown verb: " + verb); HANDLERS.help(); process.exit(1); }
+Promise.resolve(fn(args.slice(1))).catch((e) => { console.error(e.message || e); process.exit(1); });
+`;
+}
+
+function bashStub({ name, description, pack, risk, requires, usage }) {
+  const req = requires && requires.length ? `# requires: ${requires.join(", ")}\n` : "";
+  return `#!/usr/bin/env bash
+# open-claudia-tool: ${name}
+# description: ${description || ""}
+${pack ? `# pack: ${pack}\n` : ""}# risk: ${risk}
+${req}# usage: ${usage || `${name} <verb> [args]`}
+#
+# One CLI per system, verbs as subcommands: add a case per verb below.
+# Confirmation flags (--yes / --yes-destructive) are enforced by the tool
+# runner and may appear in "$@" — ignore them unless you need them.
+set -euo pipefail
+
+verb="\${1:-help}"; shift || true
+
+case "$verb" in
+  help|--help)
+    echo "${name} — ${description || ""}"
+    echo "verbs: help" ;;
+  *)
+    echo "unknown verb: $verb" >&2; exit 1 ;;
+esac
+`;
+}
+
+// Create a new tool directory with an executable stub, TOOL.md skeleton, and
+// initial state.json — then commit. The generated stub already carries the full
+// header (name, desc, pack, risk, requires, usage) so the tool is registered
+// and runnable the moment it exists.
+function scaffoldTool(name, opts = {}) {
+  const tools = require("./tools");
+  const n = tools.sanitizeName(name);
+  if (!n) throw new Error("scaffold needs a tool name");
+  if (tools.findTool(n)) throw new Error(`tool "${n}" already exists — extend it (tool edit ${n}) instead of re-scaffolding`);
+  const risk = tools.normalizeRisk(opts.risk) || "write";
+  const requires = [].concat(opts.requires || []).filter(Boolean);
+  const spec = { name: n, description: opts.description || "", pack: opts.pack || "", risk, requires, usage: opts.usage || "" };
+
+  ensureRepo();
+  const dir = path.join(toolsDir(), n);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const stub = (opts.lang === "bash" || opts.lang === "sh") ? bashStub(spec) : nodeStub(spec);
+  fs.writeFileSync(path.join(dir, "tool"), stub, { mode: 0o700 });
+  try { fs.chmodSync(path.join(dir, "tool"), 0o700); } catch (e) {}
+  fs.writeFileSync(path.join(dir, "TOOL.md"), toolMdSkeleton(spec), { mode: 0o600 });
+  tools.writeState(n, { createdAt: new Date().toISOString(), runCount: 0 });
+  commitTool(n, `scaffold ${n}`);
+  return tools.findTool(n);
+}
+
+// ── Legacy migration ─────────────────────────────────────────────────────────
+// Convert flat-file tools (pre-2.7 layout) into directories, one commit each.
+// Seeds each tool's state.json from the old .usage.json sidecar and generates a
+// TOOL.md so every migrated tool arrives with its memory intact. Files in the
+// tools dir that don't parse as tools are left untouched.
+function migrateLegacyTools() {
+  const tools = require("./tools");
+  const dir = toolsDir();
+  let entries;
+  try { entries = fs.readdirSync(dir); } catch (e) { return { migrated: [], skipped: [] }; }
+
+  const legacy = [];
+  for (const name of entries) {
+    if (name.startsWith(".")) continue;
+    const p = path.join(dir, name);
+    try { if (!fs.statSync(p).isFile()) continue; } catch (e) { continue; }
+    legacy.push(name);
+  }
+  if (!legacy.length) return { migrated: [], skipped: [] };
+
+  ensureRepo();
+  const usage = tools.readUsage();
+  const migrated = [], skipped = [];
+
+  for (const fileName of legacy) {
+    const src = path.join(dir, fileName);
+    let content;
+    try { content = fs.readFileSync(src, "utf-8"); } catch (e) { skipped.push(fileName); continue; }
+    const header = tools.parseHeader(content);
+    if (!header) { skipped.push(fileName); continue; } // not a registered tool — leave it alone
+
+    const n = header.name || tools.sanitizeName(fileName);
+    const tmp = path.join(dir, `.migrating-${n}`);
+    try {
+      fs.renameSync(src, tmp);
+      const toolDir = path.join(dir, n);
+      fs.mkdirSync(toolDir, { recursive: true, mode: 0o700 });
+      fs.renameSync(tmp, path.join(toolDir, "tool"));
+      try { fs.chmodSync(path.join(toolDir, "tool"), 0o700); } catch (e) {}
+
+      const u = usage[n] || {};
+      tools.writeState(n, {
+        createdAt: u.createdAt || new Date().toISOString(),
+        lastUsed: u.lastUsed || "",
+        runCount: u.runCount || 0,
+      });
+      if (!fs.existsSync(path.join(toolDir, "TOOL.md"))) {
+        fs.writeFileSync(path.join(toolDir, "TOOL.md"), toolMdSkeleton({
+          ...header,
+          risk: header.risk || "",
+          stateLine: `Migrated from flat layout ${today()}. Risk tier ${header.risk ? `"${header.risk}"` : "not yet classified — treated as write (fail-safe) until set"}.`,
+          journalLine: "Migrated from flat file layout; telemetry carried over from .usage.json.",
+        }), { mode: 0o600 });
+      }
+      delete usage[n];
+      commitTool(n, `migrate ${n} to directory layout`);
+      migrated.push(n);
+    } catch (e) {
+      // Roll the file back if anything failed mid-move.
+      try { if (fs.existsSync(tmp)) fs.renameSync(tmp, src); } catch (e2) {}
+      skipped.push(fileName);
+    }
+  }
+
+  if (migrated.length) {
+    try {
+      if (Object.keys(usage).length) fs.writeFileSync(tools.USAGE_FILE, JSON.stringify(usage), { mode: 0o600 });
+      else fs.rmSync(tools.USAGE_FILE, { force: true });
+    } catch (e) {}
+  }
+  return { migrated, skipped };
+}
+
+// True when flat-file tools still exist (cheap check used to auto-trigger
+// migration from the CLI entry point).
+function hasLegacyTools() {
+  const tools = require("./tools");
+  let entries;
+  try { entries = fs.readdirSync(toolsDir()); } catch (e) { return false; }
+  for (const name of entries) {
+    if (name.startsWith(".")) continue;
+    const p = path.join(toolsDir(), name);
+    try {
+      if (!fs.statSync(p).isFile()) continue;
+      if (tools.parseHeader(fs.readFileSync(p, "utf-8"))) return true;
+    } catch (e) {}
+  }
+  return false;
+}
+
+module.exports = { ensureRepo, commitTool, toolLog, scaffoldTool, migrateLegacyTools, hasLegacyTools, toolMdSkeleton };