@wipcomputer/wip-ldm-os 0.4.73-alpha.9 → 0.4.75-alpha.1

package/docs/doc-pipeline/TECHNICAL.md

@@ -0,0 +1,79 @@
+# Documentation Pipeline: Technical Details
+
+## File Paths
+
+### Repo doc templates (in the LDM OS repo)
+
+```
+shared/docs/*.md.tmpl           Templates for home docs
+shared/rules/*.md               Source for agent rules
+shared/boot/                    Boot sequence config
+```
+
+Templates use placeholders from `~/.ldm/config.json` (workspace path, agent names, org name, etc.).
+
+### Installed locations
+
+```
+~/.ldm/config.json                       Org config (agents, paths, co-authors)
+~/.ldm/shared/rules/*.md                 Agent rules (source for ~/.claude/rules/)
+~/.ldm/shared/dev-guide-*.md             Org dev guide
+~/.ldm/shared/boot/                      Boot sequence config
+~/.ldm/shared/prompts/                   Cron prompts
+~/.ldm/templates/                        CLAUDE.md templates, install prompt, etc.
+~/wipcomputerinc/library/documentation/  Personalized human docs (from templates)
+~/.claude/rules/                         Deployed rules (copied from ~/.ldm/shared/rules/)
+~/.claude/CLAUDE.md                      Level 1 global (generated from template + config)
+```
+
+### What ldm install deploys
+
+| Source | Destination | When |
+|--------|------------|------|
+| `shared/rules/*.md` | `~/.ldm/shared/rules/` then `~/.claude/rules/` | Every install |
+| `shared/docs/*.md.tmpl` | `~/wipcomputerinc/library/documentation/` | Every install |
+| `shared/boot/` | `~/.ldm/shared/boot/` | Every install |
+| `shared/prompts/` | `~/.ldm/shared/prompts/` | Every install |
+| `shared/templates/` | `~/.ldm/templates/` | Every install |
+
+**Known bug (April 2026):** The installer currently deploys shared rules on `ldm init` (first install) but not on every `ldm install`. This means rule updates in new versions don't propagate until the user re-initializes. This needs to be fixed so rules deploy on every install.
+
+**Known bug (April 2026):** The installer previously deployed home docs to `settings/docs/`. This path was renamed to `library/documentation/` on March 28, 2026. The installer must deploy to the correct path.
+
+## How templates work
+
+Home doc templates at `shared/docs/*.md.tmpl` contain placeholders:
+
+```
+Workspace: {{workspace}}
+Agents: {{agents}}
+```
+
+The installer reads `~/.ldm/config.json`, substitutes the placeholders, and writes the personalized docs to `~/wipcomputerinc/library/documentation/`.
+
+## CLAUDE.md cascade
+
+Three levels. Claude Code reads all of them, walking up from CWD:
+
+```
+Level 1: ~/.claude/CLAUDE.md              Global. ~30 lines. Universal rules.
+Level 2: ~/wipcomputerinc/CLAUDE.md       Workspace. ~150 lines. Org context.
+Level 3: <repo>/CLAUDE.md                 Per-repo. ~50-86 lines. Repo-specific.
+```
+
+After context compaction, CWD may shift to a repo. Without Level 3, all context is lost. Every repo must have a CLAUDE.md.
+
+## Config paths (correct as of April 2026)
+
+References in CLAUDE.md and rules must use absolute paths:
+
+| Reference | Correct path |
+|-----------|-------------|
+| Org config | `~/.ldm/config.json` |
+| Dev guide | `~/.ldm/shared/dev-guide-wipcomputerinc.md` |
+| Human docs | `~/wipcomputerinc/library/documentation/` |
+| Agent rules | `~/.ldm/shared/rules/` (source) or `~/.claude/rules/` (deployed) |
+| Workspace CLAUDE.md | `~/wipcomputerinc/CLAUDE.md` |
+| Global CLAUDE.md | `~/.claude/CLAUDE.md` |
+
+NOT `settings/config.json`. NOT `settings/docs/`. Those paths are from before the March 28 rename.

package/lib/deploy.mjs

@@ -394,14 +394,38 @@ function runBuildIfNeeded(repoPath) {
 
 function compareSemver(a, b) {
   if (!a || !b) return 0;
-  const pa = a.replace(/-.*$/, '').split('.').map(Number);
-  const pb = b.replace(/-.*$/, '').split('.').map(Number);
+  if (a === b) return 0;
+  const [aBase, aPre] = a.split('-', 2);
+  const [bBase, bPre] = b.split('-', 2);
+  const pa = aBase.split('.').map(Number);
+  const pb = bBase.split('.').map(Number);
   for (let i = 0; i < 3; i++) {
     const na = pa[i] || 0;
     const nb = pb[i] || 0;
     if (na > nb) return 1;
     if (na < nb) return -1;
   }
+  // Base versions equal. Stable > prerelease.
+  if (!aPre && bPre) return 1;   // a is stable, b is prerelease -> a is newer
+  if (aPre && !bPre) return -1;  // a is prerelease, b is stable -> b is newer
+  // Both have prereleases. Compare segments.
+  if (aPre && bPre) {
+    const aSegs = aPre.split('.');
+    const bSegs = bPre.split('.');
+    for (let i = 0; i < Math.max(aSegs.length, bSegs.length); i++) {
+      const as = aSegs[i] || '';
+      const bs = bSegs[i] || '';
+      const an = Number(as);
+      const bn = Number(bs);
+      if (!isNaN(an) && !isNaN(bn)) {
+        if (an > bn) return 1;
+        if (an < bn) return -1;
+      } else {
+        if (as > bs) return 1;
+        if (as < bs) return -1;
+      }
+    }
+  }
   return 0;
 }
 
@@ -508,6 +532,81 @@ function safeDeployDir(repoPath, destDir, name) {
   }
 }
 
+/**
+ * Update tools.allow in openclaw.json to include a newly deployed plugin.
+ * OpenClaw 2026.4.8+ enforces tools.allow as an exclusive allowlist.
+ * Without this, newly installed plugins are blocked from running.
+ *
+ * This function MUST remain at module top level. Nesting it inside another
+ * function puts it out of scope for its call sites in the install handlers
+ * and produces a ReferenceError at runtime. See:
+ *   ai/product/bugs/installer/2026-04-11--cc-mini--update-tools-allow-reference-error.md
+ */
+function updateToolsAllow(pluginName) {
+  const ocConfigPath = join(OC_ROOT, 'openclaw.json');
+  if (!existsSync(ocConfigPath)) return;
+  try {
+    const raw = readFileSync(ocConfigPath, 'utf8');
+    const config = JSON.parse(raw);
+    if (!config.tools?.allow || !Array.isArray(config.tools.allow)) return;
+    if (config.tools.allow.includes(pluginName)) return;
+    config.tools.allow.push(pluginName);
+    writeFileSync(ocConfigPath, JSON.stringify(config, null, 2) + '\n');
+    log(`Added "${pluginName}" to openclaw.json tools.allow`);
+  } catch (e) {
+    log(`Warning: failed to update tools.allow for ${pluginName}: ${e.message}`);
+  }
+}
+
+/**
+ * Reconcile tools.allow against plugins.entries in ~/.openclaw/openclaw.json.
+ *
+ * In OpenClaw 2026.4.8+, any plugin registered in plugins.entries but missing
+ * from tools.allow is silently blocked at runtime. Each blocked tool call
+ * spawns a root-key approval prompt to the user, flooding iMessage with
+ * approve-ids. This was observed on 2026-04-11 for model-provider plugins
+ * (anthropic, openai, xai) and imessage, which were enabled in plugins.entries
+ * but never added to tools.allow, because the per-plugin updateToolsAllow path
+ * only runs during new plugin deploys and the alpha.27/28 ReferenceError had
+ * silently dropped those entries anyway.
+ *
+ * This function is the self-healing step: at install time, walk plugins.entries,
+ * find any enabled plugin whose name is not already in tools.allow, and add it.
+ * Idempotent. Disabled plugins are skipped. Runs at both ends of installFromPath
+ * so a single `ldm install` repairs existing broken state without requiring a
+ * new plugin deploy.
+ *
+ * Background:
+ *   ai/product/bugs/code-fka-devopstoolkit/2026-04-11--cc-mini--update-tools-allow-reference-error.md
+ *
+ * This function MUST remain at module top level, same as updateToolsAllow.
+ */
+function reconcileToolsAllow() {
+  const ocConfigPath = join(OC_ROOT, 'openclaw.json');
+  if (!existsSync(ocConfigPath)) return;
+  try {
+    const raw = readFileSync(ocConfigPath, 'utf8');
+    const config = JSON.parse(raw);
+    if (!config.plugins?.entries || typeof config.plugins.entries !== 'object') return;
+    if (!config.tools?.allow || !Array.isArray(config.tools.allow)) return;
+
+    const enabledPlugins = Object.entries(config.plugins.entries)
+      .filter(([, entry]) => entry && entry.enabled !== false)
+      .map(([name]) => name);
+
+    const allow = config.tools.allow;
+    const missing = enabledPlugins.filter(name => !allow.includes(name));
+
+    if (missing.length === 0) return;
+
+    for (const name of missing) allow.push(name);
+    writeFileSync(ocConfigPath, JSON.stringify(config, null, 2) + '\n');
+    log(`Reconciled openclaw.json tools.allow: added ${missing.join(', ')}`);
+  } catch (e) {
+    log(`Warning: failed to reconcile tools.allow: ${e.message}`);
+  }
+}
+
 // ── OpenClaw plugin naming (fix #8) ──
 
 function resolveOcPluginName(repoPath, toolName) {
@@ -768,7 +867,6 @@ function registerMCP(repoPath, door, toolName) {
     const envFlag = existsSync(OC_ROOT) ? ` -e OPENCLAW_HOME="${OC_ROOT}"` : '';
     execSync(`claude mcp add --scope user ${name}${envFlag} -- node "${mcpPath}"`, { stdio: 'pipe' });
     ok(`MCP: registered ${name} at user scope`);
-    return true;
   } catch (e) {
     // Fallback: write to ~/.claude.json directly
     try {
@@ -780,15 +878,53 @@ function registerMCP(repoPath, door, toolName) {
       };
       writeJSON(ccUserPath, mcpConfig);
       ok(`MCP: registered ${name} in ~/.claude.json (fallback)`);
-      return true;
     } catch (e2) {
       fail(`MCP: registration failed. ${e.message}`);
       return false;
     }
   }
+
+  // Also register with OpenClaw so the MCP tools are available to all
+  // OpenClaw agents (e.g. Lēsa) without exec-approval gates. CC
+  // registration alone only gives tools to Claude Code sessions, not
+  // to OpenClaw's agent pipeline. Discovered 2026-04-11 when Lēsa
+  // lost xAI image gen tools after switching from Grok to Claude CLI.
+  try {
+    const ocMcpConfig = JSON.stringify({ command: 'node', args: [mcpPath] });
+    execSync(`openclaw mcp set ${name} '${ocMcpConfig}'`, { stdio: 'pipe' });
+    ok(`MCP: registered ${name} with OpenClaw`);
+  } catch {
+    // Non-fatal: OpenClaw may not be installed on all machines
+  }
+
+  // Add to OpenClaw tools.allow so the MCP tools are pre-authorized
+  updateToolsAllow(name);
+
+  return true;
+}
+
+/**
+ * Install Claude Code hook(s) for an extension.
+ *
+ * Accepts either a single door object (legacy) or an array of door objects
+ * (new in 2026-04-05 for wip-branch-guard 1.9.73 which registers on both
+ * PreToolUse and SessionStart). Normalizes to an array and installs each
+ * door independently.
+ *
+ * Returns true if at least one door installed successfully.
+ */
+function installClaudeCodeHook(repoPath, doorOrDoors) {
+  const doors = Array.isArray(doorOrDoors) ? doorOrDoors : [doorOrDoors];
+  let anyOk = false;
+  for (const door of doors) {
+    if (installClaudeCodeHookEvent(repoPath, door)) {
+      anyOk = true;
+    }
+  }
+  return anyOk;
 }
 
-function installClaudeCodeHook(repoPath, door) {
+function installClaudeCodeHookEvent(repoPath, door) {
   const settingsPath = join(HOME, '.claude', 'settings.json');
   let settings = readJSON(settingsPath);
 
@@ -802,6 +938,8 @@ function installClaudeCodeHook(repoPath, door) {
   const installedGuard = join(extDir, 'guard.mjs');
 
   // Deploy guard.mjs to ~/.ldm/extensions/{toolName}/ (#85: always update, not just when missing)
+  // Idempotent across multi-door invocations: two doors on the same repo
+  // will both trigger this copy, which is a filesystem no-op after the first.
   const srcGuard = join(repoPath, 'guard.mjs');
   if (existsSync(srcGuard)) {
     try {
@@ -819,21 +957,30 @@ function installClaudeCodeHook(repoPath, door) {
     ? `node ${installedGuard}`
     : (door.command || `node "${srcGuard}"`);
 
+  const event = door.event || 'PreToolUse';
+
   if (DRY_RUN) {
-    ok(`Claude Code: would add ${door.event || 'PreToolUse'} hook (dry run)`);
+    ok(`Claude Code: would add ${event} hook (dry run)`);
     return true;
   }
 
   if (!settings.hooks) settings.hooks = {};
-  const event = door.event || 'PreToolUse';
   if (!settings.hooks[event]) settings.hooks[event] = [];
 
-  const existingIdx = settings.hooks[event].findIndex(entry =>
-    entry.hooks?.some(h => {
+  // Match existing entries by the guard command path + the matcher, so that
+  // a single extension registering on multiple events (each with its own
+  // matcher) creates one entry per event rather than all entries colliding
+  // on the same hook slot. Before this change the existing-entry check was
+  // per-extension, not per-extension-per-event.
+  const doorMatcher = door.matcher || undefined;
+  const existingIdx = settings.hooks[event].findIndex(entry => {
+    const sameMatcher = (entry.matcher || undefined) === doorMatcher;
+    if (!sameMatcher) return false;
+    return entry.hooks?.some(h => {
       const cmd = h.command || '';
       return cmd.includes(`/${toolName}/`) || cmd === hookCommand;
-    })
-  );
+    });
+  });
 
   if (existingIdx !== -1) {
     const existingCmd = settings.hooks[event][existingIdx].hooks?.[0]?.command || '';
@@ -854,7 +1001,7 @@ function installClaudeCodeHook(repoPath, door) {
   }
 
   settings.hooks[event].push({
-    matcher: door.matcher || undefined,
+    matcher: doorMatcher,
     hooks: [{
       type: 'command',
       command: hookCommand,
@@ -1016,6 +1163,8 @@ export function installSingleTool(toolPath) {
       installed++;
       registryInfo.ldmPath = join(LDM_EXTENSIONS, toolName);
       registryInfo.ocPath = join(OC_EXTENSIONS, toolName);
+      // Update tools.allow in openclaw.json so OC 2026.4.8+ doesn't block the plugin
+      updateToolsAllow(toolName);
     }
   } else if (interfaces.mcp) {
     const extName = basename(toolPath);
@@ -1115,10 +1264,19 @@ export function installToolbox(repoPath) {
 // ── Full install pipeline ──
 
 export async function installFromPath(repoPath) {
+  // Heal tools.allow before any install runs, so the current session picks up
+  // any drift left by earlier broken installs (alpha.27/28 ReferenceError).
+  // Idempotent: no-op if plugins.entries and tools.allow are already in sync.
+  reconcileToolsAllow();
+
   const subTools = detectToolbox(repoPath);
 
   if (subTools.length > 0) {
-    return installToolbox(repoPath);
+    const result = installToolbox(repoPath);
+    // Heal again after toolbox install in case any plugin was newly registered
+    // in plugins.entries but never added to tools.allow by its deploy path.
+    reconcileToolsAllow();
+    return result;
   }
 
   const installed = installSingleTool(repoPath);
@@ -1135,6 +1293,10 @@ export async function installFromPath(repoPath) {
     console.log('');
   }
 
+  // Final reconcile pass after single-tool install, for the same reason as
+  // the toolbox branch above.
+  reconcileToolsAllow();
+
   return { tools: 1, interfaces: installed };
 }
 

package/lib/detect.mjs

@@ -53,16 +53,27 @@ export function detectInterfaces(repoPath) {
     interfaces.skill = { path: join(repoPath, 'SKILL.md') };
   }
 
-  // 6. Claude Code Hook: guard.mjs or claudeCode.hook in package.json
-  if (pkg?.claudeCode?.hook) {
-    interfaces.claudeCodeHook = pkg.claudeCode.hook;
+  // 6. Claude Code Hook: guard.mjs or claudeCode.hook(s) in package.json
+  //
+  // Supports three shapes:
+  //   - Legacy singular: pkg.claudeCode.hook = { event, matcher, ... }
+  //   - New plural array: pkg.claudeCode.hooks = [{ event, matcher, ... }, ...]
+  //     (one extension can register on multiple events, e.g. both PreToolUse
+  //     and SessionStart. Added 2026-04-05 for wip-branch-guard 1.9.73.)
+  //   - Implicit: a bare guard.mjs file with no package.json declaration.
+  //
+  // Normalized to an array internally so deploy.mjs has one code path.
+  if (Array.isArray(pkg?.claudeCode?.hooks)) {
+    interfaces.claudeCodeHook = pkg.claudeCode.hooks;
+  } else if (pkg?.claudeCode?.hook) {
+    interfaces.claudeCodeHook = [pkg.claudeCode.hook];
   } else if (existsSync(join(repoPath, 'guard.mjs'))) {
-    interfaces.claudeCodeHook = {
+    interfaces.claudeCodeHook = [{
       event: 'PreToolUse',
       matcher: 'Edit|Write',
       command: `node "${join(repoPath, 'guard.mjs')}"`,
       timeout: 5,
-    };
+    }];
   }
 
   // 7. Claude Code Plugin: .claude-plugin/plugin.json
@@ -93,7 +104,10 @@ export function describeInterfaces(interfaces) {
   if (interfaces.mcp) lines.push(`MCP Server: ${interfaces.mcp.file}`);
   if (interfaces.openclaw) lines.push(`OpenClaw Plugin: ${interfaces.openclaw.config?.name || 'detected'}`);
   if (interfaces.skill) lines.push(`Skill: SKILL.md`);
-  if (interfaces.claudeCodeHook) lines.push(`Claude Code Hook: ${interfaces.claudeCodeHook.event || 'PreToolUse'}`);
+  if (interfaces.claudeCodeHook) {
+    const events = interfaces.claudeCodeHook.map(h => h.event || 'PreToolUse');
+    lines.push(`Claude Code Hook: ${events.join(', ')}`);
+  }
   if (interfaces.claudeCodePlugin) lines.push(`Claude Code Plugin: ${interfaces.claudeCodePlugin.manifest?.name || 'detected'}`);
 
   return `${names.length} interface(s): ${names.join(', ')}\n${lines.map(l => `  ${l}`).join('\n')}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wipcomputer/wip-ldm-os",
-  "version": "0.4.73-alpha.9",
+  "version": "0.4.75-alpha.1",
   "type": "module",
   "description": "LDM OS: identity, memory, and sovereignty infrastructure for AI agents",
   "engines": {
@@ -16,7 +16,7 @@
     "lesa": "dist/bridge/cli.js"
   },
   "scripts": {
-    "build:bridge": "cd src/bridge && npm install && npx tsup core.ts mcp-server.ts cli.ts --format esm --dts --clean --outDir ../../dist/bridge",
+    "build:bridge": "cd src/bridge && npm install && npx tsup core.ts mcp-server.ts cli.ts openclaw.ts --format esm --dts --clean --outDir ../../dist/bridge",
     "build": "npm run build:bridge",
     "prepublishOnly": "npm run build:bridge",
     "fmt": "npx prettier --write 'src/**/*.{ts,mjs}' 'lib/**/*.mjs' 'bin/**/*.js'",

package/shared/docs/README.md.tmpl

@@ -6,7 +6,7 @@ Updates come from two sources:
 - **config.json** ... when you change your org settings, the "Your System" sections regenerate
 - **System hooks** ... when tools are installed, updated, or reconfigured, the relevant docs update automatically
 
-If something is wrong, update `settings/config.json` or run `ldm install`. The docs will follow.
+If something is wrong, update `~/.ldm/config.json` or run `ldm install`. The docs will follow.
 
 ## What's Here
 
@@ -32,4 +32,4 @@ Each doc has two sections:
 1. **Universal** ... how the feature works for everyone (top of file)
 2. **Your System** ... your specific configuration (bottom, after the `---` separator)
 
-Universal content comes from the LDM OS repo. "Your System" content is generated from your `settings/config.json`.
+Universal content comes from the LDM OS repo. "Your System" content is generated from your `~/.ldm/config.json`.