@wipcomputer/wip-ldm-os 0.4.73-alpha.2 → 0.4.73-alpha.21

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.split('.').map(Number);
-  const pb = b.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;
 }
 
@@ -788,7 +812,28 @@ function registerMCP(repoPath, door, toolName) {
   }
 }
 
-function installClaudeCodeHook(repoPath, door) {
+/**
+ * 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 installClaudeCodeHookEvent(repoPath, door) {
   const settingsPath = join(HOME, '.claude', 'settings.json');
   let settings = readJSON(settingsPath);
 
@@ -802,6 +847,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 +866,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 +910,7 @@ function installClaudeCodeHook(repoPath, door) {
   }
 
   settings.hooks[event].push({
-    matcher: door.matcher || undefined,
+    matcher: doorMatcher,
     hooks: [{
       type: 'command',
       command: hookCommand,

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.2",
+  "version": "0.4.73-alpha.21",
   "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/how-install-works.md.tmpl

@@ -16,11 +16,31 @@ Your AI reads the spec, explains what LDM OS is, checks if it's already installe
 1. **Self-update.** Checks npm for a newer version of itself. Updates first, then re-runs with new code.
 2. **System scan.** Reads `~/.ldm/extensions/`, `~/.openclaw/extensions/`, Claude Code MCP config, CLI binaries on PATH.
 3. **Catalog check.** Matches installed extensions against the catalog. Shows what's available, what's behind.
-4. **npm version check.** Checks every installed extension against npm for newer versions.
-5. **Update.** Clones from GitHub, builds if needed, deploys to extensions dirs, registers MCP/hooks/skills.
+4. **npm version check.** Checks every installed extension against npm for newer versions (uses dist-tags for alpha/beta).
+5. **Update.** Resolves the install source (see Source Resolution below), deploys to extensions dirs, registers MCP/hooks/skills.
 6. **Health check.** Verifies CLIs exist, no broken symlinks, no stale configs.
 7. **Cleanup.** Removes staging dirs, prunes ghost entries from registry.
 
+## Release Tracks
+
+```bash
+ldm install              # stable (npm @latest)
+ldm install --alpha      # alpha track (npm @alpha)
+ldm install --beta       # beta track (npm @beta)
+```
+
+Each track overwrites whatever is installed. Alpha, beta, and stable all use the same install path. The flag only changes which npm dist-tag is checked for updates.
+
+## Source Resolution
+
+When updating, the installer finds the package in priority order:
+
+1. **npm** (when `--alpha` or `--beta`): downloads from npm dist-tag. Works on any machine.
+2. **Local private repo** (developer machine): finds the repo at `~/wipcomputerinc/repos/ldm-os/`. Works offline, no npm or internet needed.
+3. **GitHub clone** (fallback): clones the public repo. Existing behavior.
+
+Alpha/beta installs never require `deploy-public`. Merge to private main, `wip-release alpha`, `ldm install --alpha`, done.
+
 ## Dry Run
 
 Always preview first:

package/shared/docs/how-releases-work.md.tmpl

@@ -1,77 +1,91 @@
 # How Releases Work
 
-## The Pipeline
+## Four Release Tracks
 
-Every release follows these steps. No shortcuts.
+| Track | npm tag | Who | Purpose |
+|-------|---------|-----|---------|
+| **Alpha** | `@alpha` | Developer | Moving fast. Fix, test, iterate. No deploy-public needed. |
+| **Beta** | `@beta` | Testers | Testing the distribution pipeline. npm + installer verified. |
+| **Hotfix** | `@latest` | Everyone | Emergency fix. Goes straight to stable. No deploy-public. |
+| **Stable** | `@latest` | Everyone | Full release. deploy-public syncs the public repo. |
 
-### 1. Branch and Code
+## The Alpha Flow (Development)
 
-Create a worktree, make your changes, commit:
-```bash
-ldm worktree add my-prefix/feature-name
-cd _worktrees/repo--my-prefix--feature-name/
-# edit files
-git add <files>
-git commit -m "description"
-```
-
-### 2. Write Release Notes
-
-Create `RELEASE-NOTES-v{version}.md` (dashes, not dots) in the repo root. Commit it on the branch with the code. It gets reviewed in the PR.
-
-### 3. Push and PR
+This is the fast path. Most work happens here.
 
 ```bash
-git push -u origin my-prefix/feature-name
-gh pr create --title "..." --body "..."
-gh pr merge --merge --delete-branch
-```
+# 1. Branch and code
+git worktree add .worktrees/repo--my-prefix--feature -b my-prefix/feature
+cd .worktrees/repo--my-prefix--feature/
+# edit, commit
 
-Never squash merge. Always `--merge`.
+# 2. Push, PR, merge
+git push -u origin my-prefix/feature
+gh pr create && gh pr merge --merge
 
-### 4. Release
+# 3. Alpha release
+cd /path/to/repo && git checkout main && git pull
+wip-release alpha --notes="what changed"
 
-```bash
-cd /path/to/repo    # main working tree, not worktree
-git checkout main && git pull
-wip-release patch   # auto-detects the release notes file
+# 4. Install and test
+ldm install --alpha
 ```
 
-`wip-release` handles: version bump, CHANGELOG.md, SKILL.md version sync, npm publish, GitHub release, website skill publish.
+Done. No deploy-public. No public repo sync. The installer pulls from npm @alpha (or finds the local private repo if offline).
 
-### 5. Deploy to Public
+**Sub-tool versions:** If you changed a sub-tool's code, bump its `package.json` version in the PR. Same version = same code. `wip-release` warns if files changed without a version bump.
+
+## The Stable Flow (Public Release)
 
 ```bash
-bash deploy-public.sh /path/to/private-repo org/public-repo
-```
+# 1-3. Same as alpha: branch, PR, merge
 
-Syncs everything except `ai/` to the public repo. Creates matching release with notes.
+# 4. Write release notes on the branch
+# RELEASE-NOTES-v{version}.md in repo root, committed with the code
 
-### 6. Install (Dogfood)
+# 5. Stable release
+git checkout main && git pull
+wip-release patch   # auto-detects release notes
 
-Open a new AI session and paste:
-```
-Read https://wip.computer/install/wip-ldm-os.txt
+# 6. Deploy to public
+deploy-public /path/to/private-repo org/public-repo
+
+# 7. Dogfood
+ldm install
 ```
 
-The AI walks through: explain, dry run, install. Never `npm install -g` directly.
+`wip-release` handles: version bump, CHANGELOG.md, SKILL.md sync, npm publish, GitHub release.
+
+`deploy-public` syncs everything except `ai/` to the public repo. Creates a matching release.
 
 ## Quality Gates
 
-`wip-release` enforces before publishing:
+`wip-release` enforces before publishing (stable only):
 - Release notes must be a file (not a flag)
-- Must reference a GitHub issue
 - Product docs must be updated
-- Technical docs must be updated if source changed
 - No stale merged branches
 - Must run from main working tree (not worktree)
 
+Alpha/beta skip most gates for speed.
+
+## Source Resolution
+
+The installer resolves sources in priority order:
+
+1. **npm** (with dist-tag for alpha/beta): works on any machine with internet
+2. **Local private repo**: works offline on developer machines
+3. **GitHub clone**: fallback for stable installs and third-party tools
+
+## Version Immutability
+
+Same version = same code. Always. If code changed, the version must change. The installer uses version comparison to decide whether to deploy. `wip-release` validates that sub-tools with changed files have bumped versions.
+
 ## Three Separate Steps
 
 | Step | What happens | What it means |
 |------|-------------|---------------|
 | Merge | PR merged to main | Code lands. Nothing else changes. |
-| Deploy | wip-release + deploy-public | Published to npm + GitHub. Not on your machine yet. |
-| Install | Run the install prompt | Extensions updated on your machine. |
+| Release | `wip-release alpha/beta/patch` | Published to npm. Available for install. |
+| Install | `ldm install [--alpha/--beta]` | Extensions updated on your machine. |
 
-After Deploy, stop. Don't copy files. Don't npm install. Dogfood the install prompt.
+For stable releases, add a fourth step: `deploy-public` to sync the public GitHub repo.

package/shared/rules/git-conventions.md

@@ -14,11 +14,11 @@ Always use a branch and PR.
 
 ## Co-authors on every commit
 
-List all contributors. Read co-author lines from `settings/config.json` in your workspace.
+List all contributors. Read co-author lines from `~/.ldm/config.json` coAuthors field.
 
 ## Branch prefixes
 
-Each agent uses a prefix from `settings/config.json` agents section. Prevents collisions.
+Each agent uses a prefix from `~/.ldm/config.json` agents section. Prevents collisions.
 
 ## Worktrees
 
@@ -30,4 +30,4 @@ For private/public repo pairs, all issues go on the public repo.
 
 ## On-demand reference
 
-Before doing repo work, read `~/wipcomputerinc/settings/docs/how-worktrees-work.md` for the full worktree workflow with commands.
+Before doing repo work, read `~/wipcomputerinc/library/documentation/how-worktrees-work.md` for the full worktree workflow with commands.

package/shared/rules/release-pipeline.md

@@ -39,4 +39,4 @@ Installed tools are for execution. Repo clones are for development. Use the inst
 
 ## On-demand reference
 
-Before releasing, read `~/wipcomputerinc/settings/docs/how-releases-work.md` for the full pipeline with commands.
+Before releasing, read `~/wipcomputerinc/library/documentation/how-releases-work.md` for the full pipeline with commands.

package/shared/rules/security.md

@@ -2,7 +2,7 @@
 
 ## Secret management
 
-Use your org's secret management tool (configured in settings/config.json). Never hardcode API keys, tokens, or credentials.
+Use your org's secret management tool (configured in `~/.ldm/config.json`). Never hardcode API keys, tokens, or credentials.
 
 ## Security audit before installing anything
 

package/shared/rules/workspace-boundaries.md

@@ -22,4 +22,4 @@ Installed tools are for execution. Repo clones are for development. Use the inst
 
 ## On-demand reference
 
-For the full directory map, read `~/wipcomputerinc/settings/docs/system-directories.md`.
+For the full directory map, read `~/wipcomputerinc/library/documentation/system-directories.md`.

package/shared/rules/writing-style.md

@@ -1,5 +1,5 @@
 # Writing Style
 
-Read writing conventions from your org's `settings/config.json` writingStyle section.
+Read writing conventions from `~/.ldm/config.json` writingStyle section.
 
 **Full paths in documentation.** Never truncate paths. Always show the complete path so there's no ambiguity.