@wipcomputer/wip-ai-devops-toolbox 1.9.25 → 1.9.27

package/CHANGELOG.md

@@ -31,6 +31,39 @@
 
 
 
+
+## 1.9.27 (2026-03-15)
+
+# Release Notes Quality Gate
+
+**Date:** 2026-03-15
+
+## What changed
+
+wip-release now blocks ALL releases (patch, minor, major) if the release notes are bad. Previously, patch releases only warned. Now they block.
+
+The gate checks:
+- Notes must be at least 50 characters
+- Notes can't look like a changelog entry ("fix: ...", "add: ...", "update: ...")
+- Minor/major still require a file (not --notes flag)
+
+If the gate blocks, it tells you exactly how to fix it: write a RELEASE-NOTES file, write a dev update, or use --notes with at least 50 chars of real description.
+
+## Why
+
+Release notes were consistently garbage. One-liner --notes flags like "Fix bug" or "Update docs" sailed through on patch releases. The warnings were ignored by both humans and agents. Every release page on GitHub had thin, useless notes that didn't explain what changed or why.
+
+## Also in this release
+
+- wip-repo-init templates renamed from ai/ to templates/ so they ship with npm install (deploy-public.sh was stripping them)
+- SKILL.md restart notice after install (hooks need session restart)
+- SPEC.md and TECHNICAL.md updated with all 17 tools and LDM OS links
+- Branch guard matcher fix (catches Bash + NotebookEdit)
+- Forced Git Worktrees and Branch Guard sections added to SKILL.md
+
+## 1.9.26 (2026-03-15)
+
+Add restart notice after install/update. Hooks need session restart to take effect.
 
 ## 1.9.25 (2026-03-14)
 

package/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 interface: [cli, module, mcp, skill, hook, plugin]
 metadata:
   display-name: "WIP AI DevOps Toolbox"
-  version: "1.9.25"
+  version: "1.9.27"
   homepage: "https://github.com/wipcomputer/wip-ai-devops-toolbox"
   author: "Parker Todd Brooks"
   category: dev-tools
@@ -204,6 +204,10 @@ wip-release --version
 
 Tell the user: "AI DevOps Toolbox is installed. Your AI now knows how to release software, check license compliance, protect identity files, guard repo visibility, and manage repo manifests. These tools run automatically ... you don't need to invoke them manually."
 
+**Important: tell the user they need to restart their AI agents for hooks to take effect.** Claude Code hooks are loaded when a session starts. Any running session still has the old hooks. Tell them:
+
+> "The install updated your Claude Code hooks (branch guard, file guard, repo permissions). Any AI session that was already running needs to be restarted to pick up the new hooks. Exit and reopen each Claude Code session. New sessions will work automatically."
+
 ### Update
 
 If AI DevOps Toolbox is already installed and a new version is available:
@@ -213,6 +217,8 @@ ldm install wipcomputer/wip-ai-devops-toolbox
 ldm doctor
 ```
 
+After updating, remind the user to restart running AI sessions so they pick up any new or changed hooks.
+
 Updates deploy new code without touching data or configuration.
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wipcomputer/wip-ai-devops-toolbox",
-  "version": "1.9.25",
+  "version": "1.9.27",
   "type": "module",
   "description": "The complete AI DevOps toolkit for AI-assisted development teams.",
   "license": "MIT",

package/tools/deploy-public/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wipcomputer/deploy-public",
-  "version": "1.9.25",
+  "version": "1.9.27",
   "description": "Private-to-public repo sync. Excludes ai/ folder, creates PR, merges, cleans up branches.",
   "bin": {
     "deploy-public": "./deploy-public.sh"

package/tools/post-merge-rename/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wipcomputer/post-merge-rename",
-  "version": "1.9.25",
+  "version": "1.9.27",
   "description": "Post-merge branch renaming. Appends --merged-YYYY-MM-DD to preserve history.",
   "bin": {
     "post-merge-rename": "./post-merge-rename.sh"

package/tools/wip-branch-guard/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wipcomputer/wip-branch-guard",
-  "version": "1.9.25",
+  "version": "1.9.27",
   "description": "PreToolUse hook that blocks all writes on main branch. Forces agents to work on branches or worktrees.",
   "type": "module",
   "main": "guard.mjs",

package/tools/wip-file-guard/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wipcomputer/wip-file-guard",
-  "version": "1.9.25",
+  "version": "1.9.27",
   "type": "module",
   "description": "Hook that blocks destructive edits to protected identity files. For Claude Code CLI and OpenClaw.",
   "main": "guard.mjs",

package/tools/wip-license-guard/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wipcomputer/wip-license-guard",
-  "version": "1.9.25",
+  "version": "1.9.27",
   "description": "License compliance for your own repos. Ensures correct copyright, dual-license blocks, and LICENSE files.",
   "type": "module",
   "bin": {

package/tools/wip-license-hook/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wipcomputer/wip-license-hook",
-  "version": "1.9.25",
+  "version": "1.9.27",
   "description": "License rug-pull detection and dependency license compliance for open source projects",
   "type": "module",
   "main": "dist/cli/index.js",

package/tools/wip-readme-format/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wipcomputer/wip-readme-format",
-  "version": "1.9.25",
+  "version": "1.9.27",
   "description": "Reformat any repo's README to follow the WIP Computer standard. Agent-first, human-readable.",
   "type": "module",
   "bin": {

package/tools/wip-release/core.mjs

@@ -225,32 +225,31 @@ function categorizeCommit(subject) {
  */
 function checkReleaseNotes(notes, notesSource, level) {
   const issues = [];
-  const isMinorOrMajor = level === 'minor' || level === 'major';
 
   if (!notes) {
-    issues.push('No release notes provided. Write a RELEASE-NOTES-v{version}.md file.');
-    return { ok: false, issues };
+    issues.push('No release notes provided. Write a RELEASE-NOTES-v{version}.md or ai/dev-updates/ file.');
+    return { ok: false, issues, block: true };
   }
 
-  // Bare --notes flag is not acceptable for minor/major.
-  // Agents must write a file, not pass a one-liner.
-  if (notesSource === 'flag') {
-    if (isMinorOrMajor) {
-      issues.push('Release notes came from --notes flag, not a file.');
-      issues.push('Write RELEASE-NOTES-v{version}.md (dashes not dots) and commit it.');
-      issues.push('wip-release auto-detects the file. No --notes flag needed.');
-    } else if (notes.length < 50) {
-      issues.push('Release notes are very short. Consider writing a RELEASE-NOTES file.');
-    }
+  // Notes too short. All levels blocked.
+  if (notes.length < 50) {
+    issues.push('Release notes are too short (under 50 chars). Explain what changed and why.');
+    issues.push('Write a RELEASE-NOTES-v{version}.md or ai/dev-updates/ file.');
+  }
+
+  // Bare --notes flag for minor/major is never acceptable.
+  if (notesSource === 'flag' && (level === 'minor' || level === 'major')) {
+    issues.push('Minor/major releases require a file, not --notes flag.');
+    issues.push('Write RELEASE-NOTES-v{version}.md (dashes not dots) and commit it.');
   }
 
   // Check for changelog-style one-liners regardless of source
   const looksLikeChangelog = /^(fix|add|update|remove|bump|chore|refactor|docs?)[\s:]/i.test(notes);
   if (looksLikeChangelog && notes.length < 100) {
-    issues.push('Notes look like a changelog entry, not a narrative.');
+    issues.push('Notes look like a changelog entry, not a narrative. Explain the impact.');
   }
 
-  return { ok: issues.length === 0, issues };
+  return { ok: issues.length === 0, issues, block: issues.length > 0 };
 }
 
 /**
@@ -781,17 +780,16 @@ export async function release({ repoPath, level, notes, notesSource, dryRun, noP
       const sourceLabel = notesSource === 'file' ? 'from file' : notesSource === 'dev-update' ? 'from dev update' : 'from --notes';
       console.log(`  ✓ Release notes OK (${sourceLabel})`);
     } else {
-      const isMinorOrMajor = level === 'minor' || level === 'major';
-      const prefix = isMinorOrMajor ? '✗' : '!';
-      console.log(`  ${prefix} Release notes need attention:`);
+      console.log(`  ✗ Release notes blocked:`);
       for (const issue of notesCheck.issues) console.log(`    - ${issue}`);
-      if (isMinorOrMajor) {
-        console.log('');
-        console.log('  Minor/major releases require a RELEASE-NOTES file, not a --notes one-liner.');
-        console.log('  Write RELEASE-NOTES-v{version}.md (dashes not dots), commit it, then release.');
-        console.log('');
-        return { currentVersion, newVersion, dryRun: false, failed: true };
-      }
+      console.log('');
+      console.log('  Release notes must explain what changed and why.');
+      console.log('  Options:');
+      console.log('    1. Write RELEASE-NOTES-v{version}.md (dashes not dots) and commit it');
+      console.log('    2. Write ai/dev-updates/YYYY-MM-DD--description.md and commit it');
+      console.log('    3. Use --notes="at least 50 chars explaining the change and its impact"');
+      console.log('');
+      return { currentVersion, newVersion, dryRun: false, failed: true };
     }
   }
 

package/tools/wip-release/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wipcomputer/wip-release",
-  "version": "1.9.25",
+  "version": "1.9.27",
   "type": "module",
   "description": "One-command release pipeline. Bumps version, updates changelog + SKILL.md, publishes to npm + GitHub.",
   "main": "core.mjs",

package/tools/wip-repo-init/init.mjs

@@ -15,7 +15,7 @@ import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const TEMPLATE = join(__dirname, 'ai');
+const TEMPLATE = join(__dirname, 'templates');
 
 const targetRepo = resolve(process.argv[2] || process.cwd());
 const aiDir = join(targetRepo, 'ai');

package/tools/wip-repo-init/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wipcomputer/wip-repo-init",
-  "version": "1.9.25",
+  "version": "1.9.27",
   "description": "Scaffold the standard ai/ directory structure in any repo",
   "type": "module",
   "bin": {

package/tools/wip-repo-init/templates/_sort/README.md

@@ -0,0 +1,15 @@
+# _sort/
+
+The holding pen. Files that need to be looked at and filed somewhere.
+
+## What Goes Here
+
+- iCloud duplicates or randomly placed files that need sorting
+- Files you're not sure where to put yet
+- Anything that needs a human to look at it and decide where it belongs
+
+## Rules
+
+- **Not trash.** `_sort/` is for files you want to review. `_trash/` is for files you're done with.
+- **Don't let it pile up.** Check this folder periodically. File things or trash them.
+- **Agents:** If you don't know where a file goes, put it in `_sort/`. A human will sort it later.

package/tools/wip-repo-init/templates/_trash/README.md

@@ -0,0 +1,16 @@
+# _trash/
+
+The archive. Files that are done, replaced, or consumed. Never delete anything. Move it here.
+
+## What Goes Here
+
+- Superseded plans (replaced by a newer version)
+- Consumed release notes (already used by `wip-release`)
+- Abandoned drafts
+- Anything you're done with but might need to reference later
+
+## Rules
+
+- **This is not garbage.** It's the archive. Everything in git history is recoverable, but `_trash/` keeps things findable without digging through commits.
+- **Subfolders have their own `_trash/`.** Use the nearest one. `dev-updates/_trash/` for old dev updates, `product/notes/_trash/` for old notes, etc.
+- **Never delete files from the repo.** Move them to `_trash/` instead.

package/tools/wip-repo-init/templates/dev-updates/README.md

@@ -0,0 +1,50 @@
+# dev-updates/
+
+One file per significant change. Written as you work, auto-detected by `wip-release`.
+
+## What This Folder Is
+
+Dev updates are the engineering changelog. Every time you do significant work (ship a feature, fix a bug, change architecture), write a dev update. `wip-release` picks up today's dev updates and uses them as release notes.
+
+This is not a place for plans or ideas. It's a record of what was built and why.
+
+## Naming Convention
+
+```
+YYYY-MM-DD--HH-MM--agent--description.md
+```
+
+Examples:
+- `2026-03-11--09-30--cc-mini--fix-hook-duplicates.md`
+- `2026-03-10--14-00--lesa-mini--add-voice-call-support.md`
+
+## File Format
+
+```markdown
+# Short title of what changed
+
+**Date:** YYYY-MM-DD HH:MM TZ
+**Author:** Agent Name (agent-id)
+
+## Problem
+
+What was broken or missing.
+
+## Fix / What Changed
+
+What you did and why.
+
+## Files changed
+
+- `path/to/file.js` ... what changed in it
+
+Closes #issue-number (if applicable)
+```
+
+## Rules
+
+- **Write them as you work.** Don't batch them at the end. Each significant change gets its own file.
+- **One file per change.** Not one file per day. If you fix two unrelated bugs, write two files.
+- **Include the "why."** "Fixed X" is a commit message. A dev update explains why it was broken and why the fix works.
+- **Reference issues.** If there's a GitHub issue, add `Closes #N` at the bottom.
+- **Consumed files go to `_trash/`.** `wip-release` doesn't move them automatically, but the release notes files it generates do get trashed after release.

package/tools/wip-repo-init/templates/product/notes/README.md

@@ -0,0 +1,26 @@
+# notes/
+
+Freeform notes, research, and observations. Anything that's useful context but isn't a plan, idea, or dev update.
+
+## What Goes Here
+
+- Research notes ("I looked into X and found...")
+- Meeting notes or conversation summaries
+- Technical investigations
+- Context that multiple plans reference
+- Anything that doesn't fit in `plans-prds/` or `product-ideas/`
+
+## Naming
+
+No strict convention. Use descriptive names:
+
+```
+YYYY-MM-DD--agent--topic.md
+```
+
+Example: `2026-03-10--cc-mini--readme-standard-and-universal-installer-vision.md`
+
+## Rules
+
+- **Not a plan?** Put it here, not in `plans-prds/`.
+- **Done with it?** Move to `_trash/`. Don't delete.

package/tools/wip-repo-init/templates/product/plans-prds/roadmap.md

@@ -0,0 +1,77 @@
+# [Product Name] ... Roadmap
+
+**Last updated:** YYYY-MM-DD
+**Current version:** vX.Y.Z
+
+Items are either **Upcoming**, **Done**, or **Deprecated**. Never delete. Always move.
+
+---
+
+## What This File Is
+
+The prioritized roadmap for this product. Three sections:
+
+- **Upcoming** ... work that's planned, ordered by priority. Top = most important.
+- **Done** ... shipped work. Moved here with a date when it's released.
+- **Deprecated** ... planned work that's no longer needed. Strikethrough, add the reason and date. Not the same as Done. Done means it shipped. Deprecated means the plan changed.
+
+**Keep it honest.** If something isn't going to happen, deprecate it. Don't leave dead items in Upcoming.
+
+**Keep it prioritized.** Upcoming items have priority numbers. When priorities shift, renumber them. The order is the strategy.
+
+---
+
+## Vision
+
+_One paragraph. Where is this product going? Not the feature list. The north star._
+
+---
+
+## Upcoming
+
+### Priority 1 ... [Feature/Epic Name]
+
+_What it is and why it matters in 1-2 sentences._
+
+- [ ] Task one
+- [ ] Task two
+- [ ] Task three
+
+### Priority 2 ... [Feature/Epic Name]
+
+_What it is and why it matters._
+
+- [ ] Task one
+- [ ] Task two
+
+_Add more priorities as needed. Number them. The number is the priority._
+
+---
+
+## Done
+
+### [Feature Name] (YYYY-MM-DD)
+
+- [x] What shipped
+- [x] What shipped
+
+_Move items here when they're released. Include the date. Keep the checkbox format so it's clear what was planned vs what actually shipped._
+
+---
+
+## Deprecated
+
+- ~~[Feature that was planned]~~ ... reason it was dropped. (YYYY-MM-DD)
+
+_Deprecated is not a graveyard. It's a record of decisions. When someone asks "why didn't we build X?" the answer is here._
+
+---
+
+## How to Update This File
+
+- **Shipped a feature?** Move it from Upcoming to Done. Add the date. Check the boxes.
+- **Dropped a plan?** Move it to Deprecated. Strikethrough, add the reason and date.
+- **New idea that's ready to plan?** Add to Upcoming with a priority number. Renumber if needed.
+- **Idea that's NOT ready to plan?** Put it in `../product-ideas/` instead. The roadmap is for committed work.
+- **Priorities shifted?** Renumber the Upcoming section. The order matters.
+- **Always update** "Last updated" and "Current version" at the top.

package/tools/wip-repo-init/templates/product/plans-prds/todos/README 2.md

@@ -0,0 +1,63 @@
+# todos/
+
+One todo file per person or agent. Three sections per file: To Do, Done, Deprecated.
+
+## What This Folder Is
+
+Todos that are specific to this repo. Each person or agent who works on this repo gets one file. The file tracks what they need to do, what they've done, and what got dropped.
+
+For cross-repo work or bigger items, use GitHub Issues. Todos here are for repo-scoped tasks that don't need the overhead of an issue.
+
+## Files
+
+One file per person/agent. Name it `[Name]-todo.md`.
+
+Example:
+
+| File | Who |
+|------|-----|
+| `Parker-todo.md` | Parker (human tasks: reviews, credentials, approvals) |
+| `CC-Mini-todo.md` | Claude Code on Mac Mini (code, builds, deploys) |
+
+Create the file when that person/agent first has work to do. No empty placeholder files.
+
+## File Format
+
+```markdown
+# [Name] Todos
+
+**Last updated:** YYYY-MM-DD
+
+## To Do
+
+- [ ] Task description
+- [ ] Task description (blocked by: reason)
+
+## Done
+
+- [x] Task description (YYYY-MM-DD)
+- [x] Task description (YYYY-MM-DD)
+
+## Deprecated
+
+- ~~Task description~~ ... reason. (YYYY-MM-DD)
+```
+
+## Rules
+
+- **Never delete anything.** Items move between sections, never off the page.
+- **To Do** ... work that needs to happen.
+- **Done** ... completed work. Check the box, add the date.
+- **Deprecated** ... planned but no longer needed. Strikethrough, add the reason and date. Not the same as Done. Done means it shipped. Deprecated means the requirement changed.
+- **Update the date** at the top of the file every time you edit it.
+- **One file per person/agent.** No dated files, no subfolders, no inboxes.
+- **Blocked items** stay in To Do with a `(blocked by: reason)` note. Don't move them to a separate section.
+
+## When to Use Todos vs GitHub Issues
+
+| Use | When |
+|-----|------|
+| **Todo file** | Quick tasks, repo-scoped work, things you'll do this session or this week |
+| **GitHub Issue** | Bugs, feature requests, cross-repo work, things that need tracking or discussion |
+
+Both is fine. File an issue AND add a todo that references it. The todo is your personal checklist. The issue is the team's record.

package/tools/wip-repo-init/templates/product/plans-prds/todos/README.md

@@ -0,0 +1,63 @@
+# todos/
+
+One todo file per person or agent. Three sections per file: To Do, Done, Deprecated.
+
+## What This Folder Is
+
+Todos that are specific to this repo. Each person or agent who works on this repo gets one file. The file tracks what they need to do, what they've done, and what got dropped.
+
+For cross-repo work or bigger items, use GitHub Issues. Todos here are for repo-scoped tasks that don't need the overhead of an issue.
+
+## Files
+
+One file per person/agent. Name it `[Name]-todo.md`.
+
+Example:
+
+| File | Who |
+|------|-----|
+| `Parker-todo.md` | Parker (human tasks: reviews, credentials, approvals) |
+| `CC-Mini-todo.md` | Claude Code on Mac Mini (code, builds, deploys) |
+
+Create the file when that person/agent first has work to do. No empty placeholder files.
+
+## File Format
+
+```markdown
+# [Name] Todos
+
+**Last updated:** YYYY-MM-DD
+
+## To Do
+
+- [ ] Task description
+- [ ] Task description (blocked by: reason)
+
+## Done
+
+- [x] Task description (YYYY-MM-DD)
+- [x] Task description (YYYY-MM-DD)
+
+## Deprecated
+
+- ~~Task description~~ ... reason. (YYYY-MM-DD)
+```
+
+## Rules
+
+- **Never delete anything.** Items move between sections, never off the page.
+- **To Do** ... work that needs to happen.
+- **Done** ... completed work. Check the box, add the date.
+- **Deprecated** ... planned but no longer needed. Strikethrough, add the reason and date. Not the same as Done. Done means it shipped. Deprecated means the requirement changed.
+- **Update the date** at the top of the file every time you edit it.
+- **One file per person/agent.** No dated files, no subfolders, no inboxes.
+- **Blocked items** stay in To Do with a `(blocked by: reason)` note. Don't move them to a separate section.
+
+## When to Use Todos vs GitHub Issues
+
+| Use | When |
+|-----|------|
+| **Todo file** | Quick tasks, repo-scoped work, things you'll do this session or this week |
+| **GitHub Issue** | Bugs, feature requests, cross-repo work, things that need tracking or discussion |
+
+Both is fine. File an issue AND add a todo that references it. The todo is your personal checklist. The issue is the team's record.

package/tools/wip-repo-init/templates/product/product-ideas/README.md

@@ -0,0 +1,24 @@
+# product-ideas/
+
+Ideas that aren't plans yet. The incubator.
+
+## What Goes Here
+
+An idea is something you want to build but haven't committed to. It doesn't have tasks, timelines, or priorities. It's a "what if" or "we should."
+
+When an idea is ready to become a plan, move it to `../plans-prds/upcoming/` and flesh it out with tasks and priorities.
+
+## Format
+
+No strict format. But a good idea file usually has:
+
+- **What it is** (one paragraph)
+- **Why it matters** (what problem it solves)
+- **Open questions** (what you'd need to figure out)
+- **External references** (links, reviews, research)
+
+## Rules
+
+- **Not ready to plan?** It stays here.
+- **Ready to plan?** Move to `../plans-prds/upcoming/`.
+- **Killed?** Move to `_trash/` with a note about why.

package/tools/wip-repo-init/templates/product/readme-first-product.md

@@ -0,0 +1,128 @@
+# [Product Name] ... Read Me First
+
+**Last updated:** YYYY-MM-DD
+**Status:** Living document. Read this before any plan, build, or PR.
+
+---
+
+## What This File Is
+
+This is the product bible for this repo. It answers: what is this thing, why does it exist, how does it work, and what's the current state. Every person and agent working on this repo reads this first.
+
+**Keep it current.** Update it when the architecture changes, when major features ship, when the mental model shifts. If this file is stale, the team is working from bad context.
+
+**Keep it honest.** Don't describe the aspirational version. Describe what's built and what's missing. Plans go in `plans-prds/`. This file is ground truth.
+
+---
+
+## This Folder
+
+```
+product/
+  readme-first-product.md   <- you're here (the product bible)
+  _trash/
+  notes/                    <- freeform notes, research, observations
+  plans-prds/               <- plans with lifecycle stages
+    roadmap.md              <- the prioritized roadmap
+    current/                <- plans being built right now
+    upcoming/               <- plans that are next
+    archive-complete/       <- plans that shipped
+    todos/                  <- per-agent task lists
+    _sort/                  <- plans that need categorizing
+    _trash/
+  product-ideas/            <- ideas that aren't plans yet
+```
+
+**Navigate:**
+- **Want to know what's planned?** Read `plans-prds/roadmap.md`.
+- **Want to know what's being built right now?** Look in `plans-prds/current/`.
+- **Have an idea?** Write it up in `product-ideas/`.
+- **Ready to turn an idea into a plan?** Move it from `product-ideas/` to `plans-prds/upcoming/` (or `current/` if starting now).
+
+**Plan lifecycle:**
+```
+product-ideas/  ->  upcoming/  ->  current/  ->  archive-complete/
+   (idea)          (planned)     (building)       (shipped)
+```
+
+---
+
+## What [Product Name] Is
+
+_One paragraph. What it does in human words. Not what it is technically. What problem it solves and for whom._
+
+---
+
+## Core Concepts
+
+_The 3-5 mental models someone needs to understand this product. Not implementation details. The "aha" moments that make everything else make sense._
+
+_Example: "Raw files are ground truth. Databases are indexes. If anything breaks, rebuild from raw files."_
+
+_Example: "One agent per harness per machine. That's the identity unit."_
+
+---
+
+## How It Works
+
+_The architecture at a level a new contributor can follow. Diagrams are fine. ASCII art is fine. The goal is: someone reads this section and can navigate the codebase without asking questions._
+
+_Include:_
+- _High-level data flow_
+- _Key components and what they do_
+- _Where state lives (databases, config files, etc.)_
+- _What talks to what_
+
+---
+
+## Key Source Files
+
+_Table of the important files and what they do. Not every file. The ones a new contributor needs to find their way._
+
+| File | What It Does |
+|------|-------------|
+| `src/core.ts` | _description_ |
+| `src/cli.ts` | _description_ |
+
+---
+
+## What's Built (as of vX.Y.Z)
+
+_Bullet list of what actually works right now. Update the version and date when this section changes._
+
+---
+
+## What's Missing
+
+_Bullet list of known gaps, limitations, and unfinished work. This is not the roadmap (that's in `plans-prds/roadmap.md`). This is the honest answer to "what doesn't work yet?"_
+
+---
+
+## Key Documents
+
+_Links to the important plans, PRDs, and references. Relative paths within `ai/product/`._
+
+| Document | Location |
+|----------|----------|
+| **This file** | `readme-first-product.md` |
+| **Roadmap** | `plans-prds/roadmap.md` |
+
+---
+
+## Principles
+
+_The non-negotiable rules for this product. The things that override convenience. 5-10 max._
+
+1. _Principle one._
+2. _Principle two._
+
+---
+
+## How to Update This File
+
+- **New major feature shipped?** Update "What's Built" and "What's Missing."
+- **Architecture changed?** Update "How It Works" and "Key Source Files."
+- **New mental model?** Update "Core Concepts."
+- **New principle?** Add to "Principles."
+- **Always update** the "Last updated" date at the top.
+- **Never delete sections.** If a section is empty, leave the heading. It reminds the team to fill it in.

package/tools/wip-repo-init/templates/read-me-first.md

@@ -0,0 +1,80 @@
+# ai/ ... Read Me First
+
+This is the working folder for the team. Plans, notes, ideas, dev updates, todos. Everything that isn't code lives here.
+
+This folder only exists in `-private` repos. It never ships to public.
+
+## Structure
+
+```
+ai/
+  read-me-first.md                          <- you're here
+  _sort/                                    <- stuff that hasn't been filed yet
+  _trash/                                   <- stuff that's done or replaced (never delete, move here)
+  dev-updates/                              <- one file per significant change, auto-detected by wip-release
+    _trash/
+  product/
+    readme-first-product.md                 <- the product bible (read this before anything else)
+    _trash/
+    notes/                                  <- freeform notes, research, observations
+      _trash/
+    plans-prds/                             <- plans and PRDs with lifecycle stages
+      roadmap.md                            <- prioritized roadmap (Upcoming / Done / Deprecated)
+      _sort/                                <- plans that haven't been categorized yet
+      _trash/
+      upcoming/                             <- planned work (next up after current)
+      current/                              <- active plans being implemented right now
+      archive-complete/                     <- finished plans (moved here when done)
+      todos/                                <- per-agent todo files
+    product-ideas/                          <- ideas that aren't plans yet
+      _trash/
+```
+
+## What's In Each Section
+
+| Location | What It Is | Read More |
+|----------|-----------|-----------|
+| [_sort/](_sort/README.md) | Holding pen. Files that need to be looked at and filed somewhere. iCloud duplicates, randomly placed files, things you're not sure about. | [_sort/README.md](_sort/README.md) |
+| [_trash/](_trash/README.md) | The archive. Files that are done, replaced, or consumed. Never delete anything, move it here. | [_trash/README.md](_trash/README.md) |
+| [dev-updates/](dev-updates/README.md) | Engineering changelog. One file per significant change. Auto-detected by `wip-release` for release notes. | [dev-updates/README.md](dev-updates/README.md) |
+| [product/readme-first-product.md](product/readme-first-product.md) | The product bible. What this product is, how it works, what's built, what's missing. Read before any plan, build, or PR. | [product/readme-first-product.md](product/readme-first-product.md) |
+| [product/notes/](product/notes/README.md) | Freeform notes, research, observations. Anything useful that isn't a plan or idea. | [product/notes/README.md](product/notes/README.md) |
+| [product/plans-prds/roadmap.md](product/plans-prds/roadmap.md) | Prioritized roadmap. Upcoming (ordered by priority), Done (with dates), Deprecated (with reasons). | [product/plans-prds/roadmap.md](product/plans-prds/roadmap.md) |
+| [product/plans-prds/todos/](product/plans-prds/todos/README.md) | Per-agent todo files. One file per person/agent. Three sections: To Do, Done, Deprecated. | [product/plans-prds/todos/README.md](product/plans-prds/todos/README.md) |
+| [product/product-ideas/](product/product-ideas/README.md) | Ideas that aren't plans yet. The incubator. Move to `plans-prds/upcoming/` when ready to commit. | [product/product-ideas/README.md](product/product-ideas/README.md) |
+
+## Rules
+
+**Never delete anything.** Move to `_trash/` in the nearest parent folder. Files in `_trash/` stay in git history and can always be recovered.
+
+**`_sort/` is the holding pen.** When something doesn't have an obvious home yet, or iCloud duplicated something, put it in `_sort/`. File it properly when you know where it goes.
+
+**`_trash/` is not garbage.** It's the archive. Completed plans go to `archive-complete/`. But notes, drafts, and superseded files go to `_trash/`. The difference: `archive-complete/` is work that shipped. `_trash/` is work that was replaced, abandoned, or consumed.
+
+## How to Use This
+
+**Starting a new feature?**
+1. Write a plan in [product/plans-prds/current/](product/plans-prds/current/)
+2. Write dev updates as you work in [dev-updates/](dev-updates/)
+3. When the plan ships, move it to [archive-complete/](product/plans-prds/archive-complete/)
+
+**Got an idea but not ready to plan?**
+Put it in [product/product-ideas/](product/product-ideas/)
+
+**Found something interesting but don't know where it goes?**
+Put it in [_sort/](_sort/) or [product/notes/](product/notes/)
+
+**Tracking work across agents?**
+Use [product/plans-prds/todos/](product/plans-prds/todos/) (one file per person/agent) or GitHub Issues
+
+## Dev Updates
+
+Dev updates go in [dev-updates/](dev-updates/) with the naming convention:
+
+```
+YYYY-MM-DD--HH-MM--agent--description.md
+```
+
+Example: `2026-03-11--09-30--cc-mini--fix-hook-duplicates.md`
+
+`wip-release` auto-detects today's dev updates and uses them as release notes. Write them as you work. They're the changelog that writes itself.

package/tools/wip-repo-permissions-hook/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wipcomputer/wip-repo-permissions-hook",
-  "version": "1.9.25",
+  "version": "1.9.27",
   "type": "module",
   "description": "Repo visibility guard. Blocks repos from going public without a -private counterpart.",
   "main": "core.mjs",

package/tools/wip-repos/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wipcomputer/wip-repos",
-  "version": "1.9.25",
+  "version": "1.9.27",
   "type": "module",
   "description": "Repo manifest reconciler. Single source of truth for repo organization. Like prettier for folder structure.",
   "main": "core.mjs",

package/tools/wip-universal-installer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wipcomputer/universal-installer",
-  "version": "1.9.25",
+  "version": "1.9.27",
   "type": "module",
   "description": "The Universal Interface specification for agent-native software. Teaches your AI how to build repos with every interface: CLI, Module, MCP Server, OpenClaw Plugin, Skill, Claude Code Hook.",
   "main": "detect.mjs",