@titan-design/brain 0.6.1 → 0.7.0

package/dist/templates/validation-gates.md

@@ -0,0 +1,84 @@
+# Validation Gates
+
+Deterministic verification steps used across the planning and implementation lifecycle. Each gate is a CLI command or script — not agent judgment.
+
+## Implementation Verification Pipeline
+
+Run in order. All must pass before commit.
+
+| # | Gate | Command | Pass Criteria |
+|---|------|---------|---------------|
+| 1 | Typecheck | `{{TYPECHECK_CMD}}` | Exit code 0, no errors |
+| 2 | Tests | `{{TEST_CMD}}` | Exit code 0, all tests pass |
+| 3 | Lint | `{{LINT_CMD}}` | Exit code 0, no errors/warnings |
+| 4 | Format | `npx prettier --check .` | Exit code 0 (fix: `npx prettier --write .`) |
+| 5 | Build | `{{BUILD_CMD}}` | Exit code 0, no errors |
+
+**Retry policy:** If any gate fails, fix and retry. Try at least twice before escalating.
+
+## Planning Phase Gates
+
+### Research Gate
+- **Check:** `.plans/<planId>/research-brief.md` exists and is non-empty
+- **Pass:** File has at least the 4 required sections (Existing Code, External Findings, Knowledge Gaps, Recommendations)
+- **Command:** `test -s .plans/<planId>/research-brief.md && grep -c "^## " .plans/<planId>/research-brief.md`
+
+### Design Gate
+- **Check:** All 3 artifacts exist
+- **Pass:** `spec.md`, `design.md`, and `acceptance-criteria.md` all exist in `.plans/<planId>/`
+- **Command:**
+  ```bash
+  for f in spec.md design.md acceptance-criteria.md; do
+    test -s ".plans/<planId>/$f" || echo "MISSING: $f"
+  done
+  ```
+
+### Critic Gate
+- **Check:** Critic report exists with verdict
+- **Pass:** `critic-report.md` exists and contains `## Verdict: READY`
+- **Fail:** Contains `## Verdict: NEEDS REVISION` — route back to design agent
+- **Command:** `grep "^## Verdict:" .plans/<planId>/critic-report.md`
+
+### Spec Test Gate
+- **Check:** Tests are stashed
+- **Pass:** `git stash list` contains an entry matching `spec-tests-<planId>`
+- **Command:** `git stash list | grep "spec-tests-<planId>"`
+
+### Decompose Gate
+- **Check:** PM tasks created and briefings exist
+- **Pass:** `brain pm task list --project <PREFIX>` shows new tasks with matching planId metadata, and briefing files exist
+- **Command:**
+  ```bash
+  ls .plans/<planId>/briefings/task-*.md | wc -l
+  brain pm task list --project <PREFIX> | grep "<planId>"
+  ```
+
+## Wave Gates
+
+Between implementation waves, verify:
+
+| Gate | Command | Purpose |
+|------|---------|---------|
+| All wave N tests pass | `{{TEST_CMD}}` | No regressions from parallel work |
+| Typecheck clean | `{{TYPECHECK_CMD}}` | Type compatibility across wave outputs |
+| Lint clean | `{{LINT_CMD}}` | Code quality maintained |
+| No file ownership conflicts | `git diff --name-only <wave-start>..HEAD` | Verify no unexpected file overlaps |
+
+## Review Gates
+
+After implementation, before merge:
+
+| Gate | Command | Purpose |
+|------|---------|---------|
+| Risk assessment | `review-route.sh <PREFIX> <RISK> <VERDICT>` | Route review based on risk |
+| MERGE threshold | Risk < `reviewThreshold` AND verdict PASS | Auto-merge eligible |
+| HUMAN_REVIEW threshold | Risk >= `reviewThreshold` | Requires human review task |
+
+## Gate Failure Escalation
+
+| Failure | Action |
+|---------|--------|
+| Implementation gate fails 2x | Agent reports diagnostics, orchestrator decides: resume, re-design, or escalate |
+| Critic verdict NEEDS REVISION 3x | Escalate to human walkthrough |
+| Wave gate fails | Identify which task's output broke it, resume that agent |
+| Review NEEDS WORK | Dispatch fixup agent via `review-fixup.md` |

package/dist/templates/writing-plans.md

@@ -0,0 +1,48 @@
+# Writing Plans
+
+Agent-mode phase. Create a structured implementation plan from the approved design.
+
+---
+
+## Context
+
+- Topic: `{{TASK_DESCRIPTION}}`
+- Project: `{{PROJECT_PREFIX}}`
+- Location: `{{REPO_PATH}}`
+- Plan ID: `{{PLAN_ID}}`
+
+## Instructions
+
+Create the plan directory at `.claude/plans/{{PLAN_ID}}/` with:
+
+### 1. plan.md (<200 lines)
+- Goal (one sentence)
+- Architecture (2-3 sentences)
+- Dependency graph
+- Wave plan (parallel groups)
+- Task table (name, files, wave, depends-on)
+
+### 2. manifest.json
+- planId, createdAt, goal
+- tasks array: id, name, briefing path, wave, dependsOn, fileOwnership, status
+- waves array: id, tasks, gate
+
+### 3. briefings/task-NN.md (per task)
+- Exact file paths
+- Complete code (not "add validation")
+- Exact commands with expected output
+- File ownership allowlist
+- Success criteria (runnable commands)
+- Under 50 lines of meaningful content
+
+## Rules
+
+- DRY: no duplicated logic across tasks
+- YAGNI: only what's needed for the current feature
+- TDD: write failing test → implement → pass
+- Frequent commits: one per logical step
+- Bite-sized steps: each step is one action (2-5 minutes)
+
+## Output
+
+The complete plan directory, ready for execution.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@titan-design/brain",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "type": "module",
   "description": "Developer second brain with hybrid RAG search",
   "license": "MIT",
@@ -18,7 +18,7 @@
   },
   "scripts": {
     "dev": "tsx src/cli.ts",
-    "build": "tsup",
+    "build": "tsup && mkdir -p dist/templates && cp src/modules/workflow/templates/*.md dist/templates/",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:unit": "vitest run --project unit",
@@ -30,7 +30,8 @@
     "format:check": "prettier --check \"src/**/*.ts\" \"__tests__/**/*.ts\"",
     "test:coverage": "vitest run --coverage",
     "postinstall": "node scripts/postinstall.js",
-    "preuninstall": "node scripts/preuninstall.js"
+    "preuninstall": "node scripts/preuninstall.js",
+    "lint:staged": "lint-staged"
   },
   "dependencies": {
     "@commander-js/extra-typings": "^13.1.0",
@@ -55,6 +56,7 @@
     "@types/turndown": "^5.0.6",
     "@vitest/coverage-v8": "^3.2.4",
     "eslint": "^9.20.0",
+    "lint-staged": "^16.3.2",
     "prettier": "^3.8.1",
     "tsup": "^8.3.6",
     "tsx": "^4.19.2",
@@ -66,6 +68,12 @@
     "access": "public",
     "provenance": true
   },
+  "lint-staged": {
+    "*.ts": [
+      "eslint --fix --no-error-on-unmatched-pattern",
+      "prettier --write"
+    ]
+  },
   "engines": {
     "node": ">=22"
   }

package/skill/SKILL.md

@@ -16,39 +16,54 @@ A CLI for managing a developer second brain with hybrid BM25 + vector search, LL
 - User wants to capture a quick thought or link
 - User asks about extracted memories or facts
 
+## Prerequisites
+
+Brain CLI requires **Node 22+**. If using nvm, run `nvm use 22` first.
+
 ## Commands
 
 Use `--json` flag on all commands when processing output programmatically.
 
-| Command | Purpose | Example |
-|---------|---------|---------|
-| `brain search "<query>" --json` | Hybrid search (BM25 + vector) | `brain search "authentication patterns" --json --limit 5` |
-| `brain search "<query>" --memories --json` | Search notes + extracted memories | `brain search "auth" --memories --json` |
-| `brain search "<query>" --rerank --json` | Search with cross-encoder reranking | `brain search "auth" --rerank --json` |
-| `brain search "<query>" --expand --json` | Search with graph-connected notes | `brain search "auth" --json --expand` |
-| `brain add <file>` | Add a note from file | `brain add ~/draft.md --type research --tier slow` |
-| `brain add --title "X" --type note` | Add from stdin | `echo "content" \| brain add --title "My Note" --type note` |
-| `brain quick "thought"` | Zero-friction capture to inbox | `brain quick "look into WebSockets vs SSE"` |
-| `brain inbox --json` | View inbox items | `brain inbox --status pending --json` |
-| `brain extract --all` | Extract memories from all notes | Requires Ollama running locally |
-| `brain extract --note <id>` | Extract memories from one note | `brain extract --note my-note-id` |
-| `brain memories list --json` | List active memories | `brain memories list --container default --json` |
-| `brain memories history <id>` | Show memory version chain | `brain memories history mem-abc123` |
-| `brain memories stats` | Memory count + expiry sweep | Shows active count, runs auto-forget |
-| `brain context <id> --json` | Note context (relations + memories) | `brain context my-note --json` |
-| `brain profile --format json` | Agent context profile | `brain profile --container default --format json` |
-| `brain status --json` | Database stats | Shows note count, embeddings, staleness |
-| `brain stale --json` | Notes needing review | `brain stale --tier slow --json` |
-| `brain index` | Re-index all notes | Only run when user asks -- this is slow |
-| `brain graph <note-id> --json` | Show note relations | `brain graph my-note --json` |
-| `brain doctor --json` | System health checks | Shows DB, embedder, LLM, inbox, stale status |
-| `brain doctor --fix` | Auto-repair issues | Pulls missing models, resets failed inbox |
-| `brain config get` | Show config | `brain config get` |
+| Command                                    | Purpose                             | Example                                                     |
+| ------------------------------------------ | ----------------------------------- | ----------------------------------------------------------- |
+| `brain search "<query>" --json`            | Hybrid search (BM25 + vector)       | `brain search "authentication patterns" --json --limit 5`   |
+| `brain search "<query>" --memories --json` | Search notes + extracted memories   | `brain search "auth" --memories --json`                     |
+| `brain search "<query>" --rerank --json`   | Search with cross-encoder reranking | `brain search "auth" --rerank --json`                       |
+| `brain search "<query>" --expand --json`   | Search with graph-connected notes   | `brain search "auth" --json --expand`                       |
+| `brain add <file>`                         | Add a note from file                | `brain add ~/draft.md --type research --tier slow`          |
+| `brain add --title "X" --type note`        | Add from stdin                      | `echo "content" \| brain add --title "My Note" --type note` |
+| `brain quick "thought"`                    | Zero-friction capture to inbox      | `brain quick "look into WebSockets vs SSE"`                 |
+| `brain inbox --json`                       | View inbox items                    | `brain inbox --status pending --json`                       |
+| `brain extract --all`                      | Extract memories from all notes     | Requires Ollama running locally                             |
+| `brain extract --note <id>`                | Extract memories from one note      | `brain extract --note my-note-id`                           |
+| `brain memories list --json`               | List active memories                | `brain memories list --container default --json`            |
+| `brain memories history <id>`              | Show memory version chain           | `brain memories history mem-abc123`                         |
+| `brain memories stats`                     | Memory count + expiry sweep         | Shows active count, runs auto-forget                        |
+| `brain context <id> --json`                | Note context (relations + memories) | `brain context my-note --json`                              |
+| `brain profile --format json`              | Agent context profile               | `brain profile --container default --format json`           |
+| `brain status --json`                      | Database stats                      | Shows note count, embeddings, staleness                     |
+| `brain stale --json`                       | Notes needing review                | `brain stale --tier slow --json`                            |
+| `brain index`                              | Re-index all notes                  | Only run when user asks -- this is slow                     |
+| `brain graph <note-id> --json`             | Show note relations                 | `brain graph my-note --json`                                |
+| `brain doctor --json`                      | System health checks                | Shows DB, embedder, LLM, inbox, stale status                |
+| `brain doctor --fix`                       | Auto-repair issues                  | Pulls missing models, resets failed inbox                   |
+| `brain config get`                         | Show config                         | `brain config get`                                          |
 
 ## Search Filters
 
+Filter results by metadata fields — all filters are optional and combinable:
+
 ```bash
-brain search "query" --tier slow --tags "typescript,patterns" --confidence high --since 2025-01-01 --json
+brain search "query" --tier slow                    # Filter by note tier
+brain search "query" --category research            # Filter by category
+brain search "query" --tags "typescript,patterns"    # Filter by tags
+brain search "query" --confidence high               # Filter by confidence level
+brain search "query" --type decision                 # Filter by note type
+brain search "query" --since 2025-01-01              # Filter by date
+brain search "query" --module pm                     # Filter by module
+brain search "query" --expand                        # Include graph-connected notes
+brain search "query" --rerank                        # Cross-encoder reranking
+brain search "query" --memories                      # Include extracted memories
 ```
 
 ## Note Conventions
@@ -56,15 +71,28 @@ brain search "query" --tier slow --tags "typescript,patterns" --confidence high
 **Types:** `note`, `decision`, `pattern`, `research`, `meeting`, `session-log`, `guide`
 
 **Tiers:**
+
 - `slow` -- permanent knowledge (notes, decisions, patterns, research). Has review intervals.
 - `fast` -- ephemeral (meetings, session logs). Has expiry dates. Auto-archived.
 
 **Key frontmatter fields:** `title`, `type`, `tier`, `tags`, `summary`, `confidence` (high/medium/low/speculative), `status` (current/outdated/deprecated/draft), `review-interval`, `related`
 
+## Knowledge Graph
+
+Notes can be linked via the `related` frontmatter field. Use `brain graph` to traverse and `--expand` in search to include connected notes.
+
+```bash
+brain graph <note-id> --depth 2 --json    # Traverse 2-hop connections
+brain search "query" --expand --json       # Search with graph expansion
+```
+
+After adding or updating `related` fields in frontmatter, run `brain index` to rebuild connections.
+
 ## Rules
 
 - Always use `--json` when you need to parse output
 - Search before claiming information isn't in the knowledge base
 - Do NOT run `brain index` unless the user explicitly asks -- it processes all files and is slow
+- DO run `brain index` after bulk frontmatter changes (e.g., adding `related` fields) -- graph connections won't update until re-indexed
 - When adding notes, include frontmatter with at minimum: title, type, tier
 - Present search results with score, file path, and excerpt