@soleri/forge 9.3.1 → 9.4.0

package/src/skills/subagent-driven-development/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: subagent-driven-development
+description: >
+  Use when the user says "use subagents", "parallel agents", "fan out", "dispatch agents",
+  "subagent driven", or when a task decomposes into 2+ independent units that benefit from
+  isolated execution. Covers when to dispatch, worktree isolation, and merge strategy.
+---
+
+# Subagent-Driven Development
+
+Decompose work into isolated units, dispatch subagents via the Agent tool, merge results back. You are the controller — you never implement, you orchestrate.
+
+**Announce at start:** "I'm using the subagent-driven-development skill to dispatch isolated agents."
+
+## When to Dispatch
+
+| Signal | Dispatch? |
+|--------|-----------|
+| 2+ independent tasks touching different files | Yes — no conflict risk, parallel speedup |
+| Risky/experimental work (spike, prototype) | Yes — isolate blast radius in a worktree |
+| Large refactor across unrelated modules | Yes — each module is a clean unit |
+| Single-file change or trivial fix | **No** — overhead exceeds benefit |
+| Tasks with sequential dependencies | **No** — cannot parallelize |
+| Tasks modifying the same file | **No** — guaranteed merge conflicts |
+
+## The Process
+
+### Step 1: Decompose
+
+Break work into discrete units. For each, determine: files involved, dependencies on other units, conflict risk. Only units with no file overlap and no inter-dependency qualify for dispatch.
+
+### Step 2: Dispatch with Worktree Isolation
+
+```
+Agent(prompt: "<task prompt>", isolation: "worktree")
+```
+
+Each subagent prompt must include: (1) task scope, (2) file boundaries, (3) acceptance criteria, (4) rules — no commits, no out-of-scope changes, run tests before reporting.
+
+Launch all independent subagents in a **single message** so they run in parallel.
+
+### Step 3: Review and Merge
+
+For each returning subagent:
+1. **Review** — read actual file changes (do not trust self-reports alone), verify tests pass, check scope compliance
+2. **Merge** — `git merge` or `git cherry-pick` from the worktree branch, one at a time
+3. **Test** — run the full suite after each merge; only proceed if green
+4. **Conflicts** — resolve manually, re-run tests, capture as anti-pattern for future planning
+
+After all merges, capture learnings:
+```
+YOUR_AGENT_core op:capture_quick params:{
+  title: "subagent dispatch outcome",
+  description: "<which tasks parallelized well, which conflicted>"
+}
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails |
+|-------------|--------------|
+| Dispatching for a 5-line fix | Startup overhead exceeds the work |
+| Parallel dispatch of dependent tasks | Second agent works on stale assumptions |
+| Skipping worktree isolation for nearby files | Silent overwrites between agents |
+| Trusting self-reports without reading code | Agents miss edge cases or misunderstand scope |
+| Dispatching 10+ agents at once | Review bottleneck shifts to the controller |
+
+## Merge Strategy
+
+| Situation | Strategy |
+|-----------|----------|
+| Completely separate directories | Fast-forward merge, no conflicts expected |
+| Different files in the same package | Merge one by one, test after each |
+| Unexpected conflict | Resolve manually, re-run tests, capture as anti-pattern |
+| Subagent result fails review | Dispatch fix subagent into same worktree (max 2 retries) |
+
+**Related skills:** parallel-execute, executing-plans, verification-before-completion

package/src/skills/using-git-worktrees/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: using-git-worktrees
+description: >
+  Use when the user says "worktree", "isolate", "parallel branch", "safe branch", or when a plan
+  has independent tasks that benefit from parallel execution in isolated branches. Provides the
+  protocol for creating, working in, and cleaning up git worktrees safely.
+---
+
+# Using Git Worktrees
+
+Isolate work into parallel branches without stashing or switching. Use for multi-task plans, risky changes, or parallel execution. Claude Code natively supports `isolation: "worktree"` on sub-agents.
+
+**Announce at start:** "I'm using the using-git-worktrees skill to isolate this work."
+
+## When to Use
+
+- Plan has 2+ independent tasks that can run in parallel
+- Risky or experimental change that should not touch the main working tree
+- Long-running task where you need the main branch clean for hotfixes
+
+## Creation Protocol
+
+```bash
+# 1. Pre-flight — working tree must be clean
+git status
+git log origin/main..main              # check for unpushed commits
+
+# 2. Create worktree
+git worktree add ../<repo>-<task> -b <branch-name>
+cd ../<repo>-<task>
+
+# 3. Bootstrap and baseline
+npm install                            # shared .git does NOT share node_modules
+npm test                               # must pass before any changes
+```
+
+If the working tree is dirty, commit or stash first. If baseline tests fail, stop and investigate.
+
+## Working in a Worktree
+
+- Full working copy — edit, test, commit normally
+- Commits are visible across worktrees (shared `.git`)
+- `git worktree list` to see all active worktrees
+
+## Cleanup Protocol
+
+```bash
+# 1. Safety check — never delete with unpushed/uncommitted work
+git log origin/<branch>..<branch>      # unpushed commits?
+git diff --stat                        # uncommitted changes?
+
+# 2. Merge or discard
+git merge <branch-name>                # from main worktree
+# OR: git branch -D <branch-name>     # only if work is abandoned
+
+# 3. Remove and verify
+git worktree remove ../<repo>-<task>
+git worktree prune
+git worktree list                      # confirm removal
+```
+
+## Anti-Patterns
+- Creating worktrees for single-file changes or one-liner fixes
+- Leaving orphan worktrees after tasks complete — always clean up
+- Deleting the worktree directory manually instead of `git worktree remove`
+- Forgetting `npm install` in new worktree
+- Skipping baseline tests before starting work
+
+## Quick Reference
+
+| Action           | Command                                          |
+| ---------------- | ------------------------------------------------ |
+| Create           | `git worktree add ../<name> -b <branch>`         |
+| List             | `git worktree list`                              |
+| Remove           | `git worktree remove ../<name>`                  |
+| Prune            | `git worktree prune`                             |
+| Check unpushed   | `git log origin/<branch>..<branch>`              |
+| Claude Code      | Sub-agent with `isolation: "worktree"` parameter |
+
+**Related skills:** executing-plans, parallel-execute

package/src/skills/vault-curate/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: vault-curate
+description: >
+  Use when the user says "clean vault", "deduplicate", "groom knowledge",
+  "consolidate vault", "vault maintenance", "find duplicates", "merge patterns",
+  "check contradictions", "vault health", or wants to maintain, clean, reorganize,
+  or improve the quality of the agent's knowledge base.
+---
+
+# Vault Curate — Knowledge Maintenance
+
+Maintain vault quality through deduplication, grooming, contradiction detection, and consolidation. A well-curated vault produces better search results and brain recommendations.
+
+## When to Use
+
+Periodically (weekly or after heavy capture sessions), when search quality degrades, when vault health shows warnings, or when the user explicitly requests maintenance.
+
+## Orchestration Sequence
+
+### Step 1: Health Assessment
+
+```
+YOUR_AGENT_core op:knowledge_health
+```
+
+```
+YOUR_AGENT_core op:get_vault_analytics
+```
+
+Present the health summary to the user before proceeding: total entries, quality scores, staleness, coverage gaps.
+
+### Step 2: Detect Duplicates
+
+```
+YOUR_AGENT_core op:curator_detect_duplicates
+```
+
+This finds entries with overlapping titles, descriptions, or content. Review the duplicate pairs — some may be intentional (different contexts) while others are true duplicates.
+
+For true duplicates:
+
+```
+YOUR_AGENT_core op:merge_patterns
+  params: { patternIds: ["<id1>", "<id2>"] }
+```
+
+Preserve the best content from each.
+
+### Step 3: Find Contradictions
+
+```
+YOUR_AGENT_core op:curator_contradictions
+```
+
+Contradictions erode trust in vault search results. For each contradiction: decide which entry is correct (check dates, context, evidence), then archive or update the incorrect one.
+
+### Step 4: Groom Entries
+
+```
+YOUR_AGENT_core op:curator_groom_all
+```
+
+Runs tag enrichment and metadata cleanup across all entries. This improves searchability and categorization.
+
+For targeted grooming of specific entries:
+
+```
+YOUR_AGENT_core op:curator_groom
+  params: { entryIds: ["<id>"], tags: ["<tag>"] }
+```
+
+### Step 5: Full Consolidation
+
+```
+YOUR_AGENT_core op:curator_consolidate
+```
+
+Runs the complete pipeline: dedup + archive stale entries + resolve contradictions. This is the heavy-duty cleanup.
+
+### Step 6: Knowledge Reorganization
+
+```
+YOUR_AGENT_core op:knowledge_reorganize
+  params: { mode: "preview" }
+```
+
+Preview first, then run again with `mode: "apply"` if the preview looks good.
+
+### Step 7: Verify Results
+
+```
+YOUR_AGENT_core op:knowledge_health
+```
+
+Compare with Step 1 metrics. Vault health should improve: fewer duplicates, no contradictions, better coverage.
+
+## Exit Criteria
+
+Curation is complete when: duplicates merged, contradictions resolved, entries groomed, and health metrics improved compared to Step 1 baseline.

package/src/skills/verification-before-completion/SKILL.md

@@ -75,6 +75,18 @@ Capture session summary: `YOUR_AGENT_core op:session_capture params: { summary:
 - Running linter but not build (linter does not check compilation)
 - Skipping the red-green cycle for regression tests
 
+## Rationalization Prevention
+
+Do NOT rationalize away failures. If a check fails, it fails. Period.
+
+- **HARD-GATE: All verification commands must pass (exit 0, 0 failures) before claiming task complete.**
+- **HARD-GATE: Agent system checks (`admin_health`, `admin_diagnostic`) must report no problems before completion.**
+- Do not say "tests probably pass" -- run them and read the output.
+- Do not say "this is a minor issue" to skip a failing check.
+- Do not say "it worked last time" -- stale results are not evidence.
+- Do not downgrade a failure to a warning to avoid blocking completion.
+- If a check fails and you cannot fix it, report the failure honestly. Never hide it.
+
 ## Quick Reference
 
 | Op                      | When to Use                         |

package/src/skills/yolo-mode/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: yolo-mode
+description: >
+  Use when the user says "yolo", "autonomous", "skip approvals", "full auto", "hands off",
+  or asks to execute without approval gates. Activates autonomous execution mode where the
+  agent skips plan approval gates but preserves all safety invariants.
+---
+
+# YOLO Mode
+
+Autonomous execution without approval gates. Plans execute immediately — no Gate 1, no Gate 2, no confirmation prompts.
+
+**Announce at start:** "I'm activating YOLO mode — autonomous execution with safety invariants intact."
+
+## Activation Flow
+
+### Step 1: Verify Safety Hook Pack
+
+```
+YOUR_AGENT_core op:admin_health
+```
+
+Check that the YOLO Safety Hook Pack is installed. This pack intercepts destructive commands (force push, reset --hard, drop table, rm -rf).
+
+**HARD-GATE: Refuse to activate YOLO mode if the safety hook pack is not installed.** Tell the user: "YOLO mode requires the safety hook pack. Run `soleri hooks add-pack yolo-safety` first."
+
+### Step 2: Morph to YOLO Mode
+
+```
+YOUR_AGENT_core op:morph
+  params: { mode: "YOLO-MODE" }
+```
+
+### Step 3: Confirm to User
+
+State clearly: "YOLO mode active. Approval gates are off. Safety invariants remain enforced. Say 'exit YOLO' to return to normal mode."
+
+## What Gets Skipped
+
+- Plan approval Gate 1 (`op:approve_plan`)
+- Plan approval Gate 2 (`op:plan_split` confirmation)
+- User confirmation prompts between steps
+- "Ready for feedback?" checkpoints
+
+## What Is NEVER Skipped
+
+- **`op:orchestrate_complete`** — knowledge capture runs on every task, always
+- **Vault search before decisions** — check vault for patterns/anti-patterns before acting
+- **YOLO Safety Hook Pack** — intercepts destructive commands (force push, drop table, rm -rf, reset --hard)
+- **Test execution** — tests still run; failures still block completion
+- **`op:plan_reconcile`** — drift reports still generated after execution
+
+## Exit Conditions
+
+YOLO mode deactivates when any of these occur:
+
+- User says "exit YOLO", "stop YOLO", or "normal mode"
+- Session ends
+- Explicit deactivation: `op:morph params: { mode: "DEFAULT" }`
+- Safety hook intercepts a destructive command (auto-exits, requires re-activation)
+
+## Anti-Patterns
+
+- Activating YOLO on an unfamiliar codebase — you need vault context first
+- Skipping tests in YOLO — tests are safety, not ceremony
+- Using YOLO for architectural decisions that need human judgment
+- Staying in YOLO after a safety hook triggers — re-evaluate before re-activating
+- Running YOLO without reviewing what the safety hook pack actually covers
+
+## Quick Reference
+
+| Op                    | When to Use                          |
+| --------------------- | ------------------------------------ |
+| `admin_health`        | Verify safety hook pack is installed |
+| `morph`               | Activate/deactivate YOLO mode        |
+| `orchestrate_complete`| After every task (never skip)        |
+| `search_intelligent`  | Before every decision (never skip)   |
+| `plan_reconcile`      | After execution (never skip)         |
+
+**Related skills:** executing-plans, writing-plans

package/src/templates/clean-worktrees.ts

@@ -0,0 +1,58 @@
+/**
+ * Generate a POSIX sh script that cleans up stale Claude Code worktrees.
+ * Registered as a SessionStart hook in scaffolded agents.
+ */
+export function generateCleanWorktreesScript(): string {
+  return `#!/bin/sh
+# Clean stale Claude Code worktrees on session start.
+# Registered as a SessionStart hook by Soleri scaffolding.
+# Safe: skips active worktrees, checks for unpushed commits.
+
+WORKTREE_DIR=".claude/worktrees"
+
+# Exit silently if no worktrees directory
+[ -d "$WORKTREE_DIR" ] || exit 0
+
+# Prune worktrees whose branches have been deleted
+git worktree prune 2>/dev/null
+
+# Get list of active worktrees (skip the main one)
+active_worktrees="$(git worktree list --porcelain 2>/dev/null | grep '^worktree ' | sed 's/^worktree //')"
+
+cleaned=0
+skipped=0
+
+for dir in "$WORKTREE_DIR"/*/; do
+  [ -d "$dir" ] || continue
+
+  # Resolve to absolute path for comparison
+  abs_dir="$(cd "$dir" 2>/dev/null && pwd)" || continue
+
+  # Skip if still in git worktree list (active)
+  if echo "$active_worktrees" | grep -qF "$abs_dir"; then
+    skipped=$((skipped + 1))
+    continue
+  fi
+
+  # Safety: check for unpushed commits before removing
+  branch="$(git -C "$dir" rev-parse --abbrev-ref HEAD 2>/dev/null)" || branch=""
+  if [ -n "$branch" ] && [ "$branch" != "HEAD" ]; then
+    upstream="$(git -C "$dir" rev-parse --abbrev-ref "@{upstream}" 2>/dev/null)" || upstream=""
+    if [ -n "$upstream" ]; then
+      unpushed="$(git -C "$dir" log "$upstream..$branch" --oneline 2>/dev/null)"
+      if [ -n "$unpushed" ]; then
+        skipped=$((skipped + 1))
+        continue
+      fi
+    fi
+  fi
+
+  rm -rf "$dir" 2>/dev/null && cleaned=$((cleaned + 1))
+done
+
+# Silent unless something was cleaned
+if [ "$cleaned" -gt 0 ]; then
+  echo "Cleaned $cleaned stale worktree(s), $skipped active/protected"
+fi
+`;
+}

package/src/templates/setup-script.ts

@@ -53,11 +53,18 @@ if [ ! -f "$SETTINGS_FILE" ]; then
         "type": "prompt",
         "prompt": "Before context is compacted, capture a session summary by calling ${config.id}_core op:session_capture with a brief summary of what was accomplished, the topics covered, files modified, and tools used."
       }
+    ],
+    "SessionStart": [
+      {
+        "type": "command",
+        "command": "sh $AGENT_DIR/scripts/clean-worktrees.sh",
+        "timeout": 10
+      }
     ]
   }
 }
 SETTINGS
-  echo "[ok] Created $SETTINGS_FILE with PreCompact hook"
+  echo "[ok] Created $SETTINGS_FILE with PreCompact + SessionStart hooks"
 else
   if grep -q "PreCompact" "$SETTINGS_FILE" 2>/dev/null; then
     echo "[ok] PreCompact hook already configured — skipping"
@@ -75,6 +82,24 @@ else
     "
     echo "[ok] Added PreCompact hook to $SETTINGS_FILE"
   fi
+  # Add SessionStart worktree cleanup hook
+  if grep -q "clean-worktrees" "$SETTINGS_FILE" 2>/dev/null; then
+    echo "[ok] SessionStart worktree cleanup hook already configured"
+  else
+    node -e "
+      const fs = require('fs');
+      const settings = JSON.parse(fs.readFileSync('$SETTINGS_FILE', 'utf-8'));
+      if (!settings.hooks) settings.hooks = {};
+      if (!settings.hooks.SessionStart) settings.hooks.SessionStart = [];
+      settings.hooks.SessionStart.push({
+        type: 'command',
+        command: 'sh $AGENT_DIR/scripts/clean-worktrees.sh',
+        timeout: 10
+      });
+      fs.writeFileSync('$SETTINGS_FILE', JSON.stringify(settings, null, 2) + '\\n');
+    "
+    echo "[ok] Added SessionStart worktree cleanup hook"
+  fi
 fi
 
 # Install skills to ~/.claude/commands/

package/src/templates/shared-rules.ts

@@ -114,6 +114,19 @@ const ENGINE_RULES_LINES: string[] = [
   '- Persist lessons: capture + link. An unlinked entry is incomplete.',
   '- Exceptions: runtime errors with stack traces → codebase first; user explicitly asks to search web.',
   '',
+  '### Vault Search Strategy',
+  '',
+  "Default to **two-pass search** — scan first, load only what's relevant. This saves tokens and keeps context lean.",
+  '',
+  '| Situation | Strategy |',
+  '|-----------|----------|',
+  '| Broad/exploratory query | `mode: "scan"` → triage by score → `op:load_entries` for top matches |',
+  '| Specific known entry | `mode: "full"` directly |',
+  '| Work task (need vault context before coding) | Scan → pick relevant → load |',
+  '| Existence check ("do we have X?") | `mode: "scan"` only, no load needed |',
+  '',
+  '**Never load all scan results.** Pick the top 2-4 by relevance score and skip entries below 0.30 unless the query is very specific.',
+  '',
 
   // ─── Planning ────────────────────────────────────────────
   '## Planning',
@@ -210,6 +223,38 @@ const ENGINE_RULES_LINES: string[] = [
   '```',
   '',
 
+  // ─── YOLO Mode ──────────────────────────────────────────
+  '## YOLO Mode',
+  '<!-- soleri:yolo-mode -->',
+  '',
+  'YOLO mode skips plan approval gates for faster execution. The agent executes tasks directly without waiting for Gate 1 (`op:approve_plan`) or Gate 2 (`op:plan_split`) confirmation.',
+  '',
+  '### What Changes',
+  '',
+  '- Plan approval gates are **auto-approved** — no user confirmation needed.',
+  '- Task routing skips the two-gate ceremony — plans are created, approved, and split in one pass.',
+  '',
+  '### What Does NOT Change',
+  '',
+  '- `op:orchestrate_complete` **always runs** — knowledge capture is never skipped.',
+  '- Vault search **always runs** — decisions must be informed by existing patterns.',
+  '- Brain feedback loop remains active.',
+  '- Grade gate still applies — plans must grade A or higher.',
+  '',
+  '### Prerequisites',
+  '',
+  '- **YOLO Safety Hook Pack** must be installed: `soleri hooks add-pack yolo-safety`',
+  '- The hook pack intercepts destructive commands (force push, reset --hard, drop table) and requires explicit confirmation.',
+  '- Staging backups are created before destructive operations.',
+  '',
+  '### Activation & Deactivation',
+  '',
+  '| Action | Method |',
+  '|--------|--------|',
+  '| Activate | `soleri yolo` or `op:morph params:{ mode: "YOLO-MODE" }` |',
+  '| Deactivate | "exit YOLO", session end, or `op:activate params:{ deactivate: true }` |',
+  '',
+
   // ─── Output Formatting ───────────────────────────────────
   '## Output Formatting',
   '<!-- soleri:output-formatting -->',
@@ -299,7 +344,7 @@ const ENGINE_RULES_LINES: string[] = [
   '`op:orchestrate_complete` runs for EVERY task — simple or complex. This captures:',
   '- Knowledge to vault (patterns learned, decisions made)',
   '- Session summary (what was done, files changed)',
-  '- Brain feedback (what worked, what didn\'t)',
+  "- Brain feedback (what worked, what didn't)",
   '',
   'Without completion, the knowledge trail is lost. The code is in git, but the WHY disappears.',
   '',
@@ -350,6 +395,36 @@ const ENGINE_RULES_LINES: string[] = [
   '- Brain tells you **which** patterns matter (names + strength scores). Vault tells you **what** they are (rules, examples).',
   "- Pull only what's relevant to the current task — don't load everything at session start.",
   '',
+  '### Second Brain Features',
+  '',
+  '| Feature | How to use |',
+  '|---------|-----------|',
+  '| **Two-pass search** | `op:search_intelligent` with `mode: "scan"` for lightweight results, then `op:load_entries` for full content. See **Vault Search Strategy**. |',
+  '| **Session briefing** | `op:session_briefing` on session start — surfaces last session, active plans, recent captures, brain recommendations |',
+  '| **Evidence reconciliation** | `op:plan_reconcile_with_evidence` — cross-references plan tasks against git diff |',
+  '| **Learning radar** | `op:radar_analyze` to detect patterns from corrections, search misses, workarounds. `op:radar_candidates` to review, `op:radar_approve`/`op:radar_dismiss` |',
+  '| **External ingestion** | `op:ingest_url` for articles, `op:ingest_text` for transcripts/notes, `op:ingest_batch` for multiple items |',
+  '| **Content synthesis** | `op:synthesize` — turn vault knowledge into briefs, outlines, talking points, or post drafts |',
+  '| **Skill chains** | `op:chain_execute` — multi-step workflows with data flow between steps and approval gates |',
+  '',
+  '### Brain Feedback Loop',
+  '',
+  'After using a vault search result to inform a decision, action, or response, call `op:record_feedback` with:',
+  '- `query`: the original search query',
+  '- `entryId`: the vault entry ID that was used',
+  '- `action`: "accepted" (result was useful) or "rejected" (result was irrelevant/wrong)',
+  '- `confidence`: 0.0–1.0 how relevant the result was to the task',
+  '',
+  'Do this for:',
+  '- `search_intelligent` results that influence your next action',
+  '- `orchestrate_plan` vault recommendations you follow',
+  '- Vault entries you cite or reference in responses',
+  '',
+  'Do NOT record feedback for:',
+  '- Existence checks ("do we have X?" — just scanning, not using)',
+  "- Results you browse but don't act on",
+  '- Duplicate feedback for the same entry in the same task',
+  '',
 
   // ─── Cross-Project Memory ────────────────────────────────
   '## Cross-Project Memory',
@@ -416,11 +491,27 @@ const ENGINE_RULES_LINES: string[] = [
   '',
   '### Character Persistence',
   '',
-  '- All communication flows through your persona\'s voice — tone, vocabulary, opinions',
+  '- **MANDATORY**: Prefix every response with `{AgentName} >` when activated (e.g., `Ernesto >`, `Salvador >`). This signals to the user that the agent persona is active.',
+  "- All communication flows through your persona's voice — tone, vocabulary, opinions",
   '- Stay in character until explicitly deactivated',
   '- Context compaction does not change who you are — these rules persist in CLAUDE.md',
   '- If you notice yourself dropping character, re-read your activation context',
   '',
+  '### Operator Learning (automatic, silent)',
+  'When calling `op:orchestrate_complete`, fill the `operatorSignals` field with your observations from this session:',
+  '',
+  '- **Expertise**: which topics did the operator demonstrate knowledge in? Where did they need explanation? Report topic + level (learning/intermediate/expert).',
+  "- **Corrections**: did they tell you to change behavior? Quote their exact words. Note if it's global or project-specific.",
+  '- **Interests**: did they share anything personal? Hobbies, background, music, culture? Report the tag and context.',
+  '- **Patterns**: did you notice work habits? Batching, scoping, pacing, communication style? Report what you observed.',
+  '',
+  'Rules:',
+  "- Fill what you observed. Empty arrays for what you didn't notice.",
+  '- Store facts, not assumptions. "User asked about React hooks" not "User doesn\'t know React."',
+  '- Never announce you are learning. Never ask for confirmation.',
+  '- Decline to store: health, medical, political, religious, sexual, financial, legal content.',
+  '- The engine handles compounding and persistence — just report honestly.',
+  '',
   '### What NOT to Route Through Tools',
   '',
   '- Pure file read/write/edit operations (use Read, Edit, Write tools directly)',
@@ -436,8 +527,8 @@ const ENGINE_RULES_LINES: string[] = [
   '',
   '### Session Start Protocol',
   '',
-  'On activation, discover capabilities via `op:admin_tool_list`. Call `op:register` when project context is needed for a task.',
-  'Call `op:activate` only when checking evolved capabilities or recovering session state.',
+  'On activation, discover capabilities via `op:admin_tool_list`. Call `op:session_briefing` to surface last session context, active plans, and brain recommendations.',
+  'Call `op:register` when project context is needed for a task. Call `op:activate` only when checking evolved capabilities or recovering session state.',
   'After context compaction, re-discover capabilities — do not assume your tool inventory is still cached.',
   '',
   '### Context Compaction',
@@ -516,6 +607,39 @@ const ENGINE_RULES_LINES: string[] = [
   '| Template drift suspected | `soleri agent diff` to see what changed |',
   '',
 
+  // ─── Persona Self-Update ────────────────────────────────────
+  '## Persona Self-Update',
+  '<!-- soleri:persona-self-update -->',
+  '',
+  'When the user asks to change your personality, voice, quirks, or character:',
+  '',
+  '1. **Edit your own `agent.yaml`** — the `persona:` block is the source of truth for your character.',
+  '2. **NEVER modify Soleri engine code** — `@soleri/core`, `packages/core/src/persona/defaults.ts`, or any engine package. Those define the default template for ALL agents.',
+  '3. After editing `agent.yaml`, tell the user to run `soleri agent refresh` to regenerate CLAUDE.md, then reactivate.',
+  '',
+  '### What You Can Change',
+  '',
+  '| Field | Purpose |',
+  '|-------|---------|',
+  '| `persona.template` | Template ID (informational, can be custom) |',
+  '| `persona.inspiration` | Who/what inspires the character |',
+  '| `persona.culture` | Cultural background |',
+  '| `persona.voice` | How you sound (tone, cadence, vocabulary) |',
+  '| `persona.traits` | Personality traits |',
+  '| `persona.quirks` | Memorable behaviors and expressions |',
+  '| `persona.opinions` | Beliefs about craft and quality |',
+  '| `persona.metaphors` | Domains you draw metaphors from |',
+  '| `persona.languageRule` | How you mix languages |',
+  '| `persona.greetings` | Session start messages |',
+  '| `persona.signoffs` | Session end messages |',
+  '',
+  '### What You Must NOT Change',
+  '',
+  '- Engine defaults in `packages/core/src/persona/defaults.ts`',
+  '- The `PERSONA_TEMPLATES` registry',
+  '- Any file inside `@soleri/core` or `@soleri/forge`',
+  '',
+
   // ─── Verification Protocol ─────────────────────────────────
   '## Verification Protocol',
   '<!-- soleri:verification-protocol -->',
@@ -528,11 +652,12 @@ const ENGINE_RULES_LINES: string[] = [
   '2. **Prove** — reproduce the issue (test case, error log, stack trace)',
   '3. **Fix** — only after the issue is proven reproducible',
   '',
-  '### Anti-pattern',
+  '### Anti-patterns',
   '',
   '- Fixing code "just in case" or for aesthetics without a proven issue',
   '- Claiming a bug exists without reproduction evidence',
   '- Refactoring working code under the guise of a bug fix',
+  '- **Dismissing test failures as "flaky" or "pre-existing" without reading the test code and the handler it exercises.** A test that fails consistently is broken, not flaky. Investigate the root cause before classifying.',
   '',
   '### Scope',
   '',