@soleri/forge 5.14.0 → 5.14.2

package/src/templates/inject-claude-md.ts

@@ -16,27 +16,27 @@ export function generateInjectClaudeMd(config: AgentConfig): string {
     "import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';",
     "import { homedir } from 'node:os';",
     "import { join } from 'node:path';",
-    "import { getClaudeMdContent, getClaudeMdMarker } from './claude-md-content.js';",
+    "import { getClaudeMdContent, getClaudeMdMarker, getEngineRulesContent, getEngineRulesMarker } from './claude-md-content.js';",
     '',
     'export interface InjectResult {',
     '  injected: boolean;',
     '  path: string;',
     "  action: 'created' | 'updated' | 'appended';",
+    '  engineRules?: boolean;',
     '}',
     '',
     '/**',
-    ' * Inject into a specific CLAUDE.md file path.',
-    ' * Shared logic for both project-level and global injection.',
+    ' * Inject a marker-delimited block into a file.',
+    ' * If the marker already exists, replaces the content between markers.',
+    ' * Otherwise appends (or creates the file).',
     ' */',
-    'function injectIntoFile(filePath: string): InjectResult {',
-    '  const content = getClaudeMdContent();',
-    '  const marker = getClaudeMdMarker();',
+    "function injectBlock(filePath: string, content: string, marker: string): 'created' | 'updated' | 'appended' | 'skipped' {",
     `  const startMarker = '<!-- ' + marker + ' -->';`,
     `  const endMarker = '<!-- /' + marker + ' -->';`,
     '',
     '  if (!existsSync(filePath)) {',
     "    writeFileSync(filePath, content + '\\n', 'utf-8');",
-    "    return { injected: true, path: filePath, action: 'created' };",
+    "    return 'created';",
     '  }',
     '',
     "  const existing = readFileSync(filePath, 'utf-8');",
@@ -47,30 +47,52 @@ export function generateInjectClaudeMd(config: AgentConfig): string {
     '    if (endIdx === -1) {',
     "      const updated = existing.slice(0, startIdx) + content + '\\n' + existing.slice(startIdx + startMarker.length);",
     "      writeFileSync(filePath, updated, 'utf-8');",
-    "      return { injected: true, path: filePath, action: 'updated' };",
+    "      return 'updated';",
     '    }',
     '    const updated = existing.slice(0, startIdx) + content + existing.slice(endIdx + endMarker.length);',
     "    writeFileSync(filePath, updated, 'utf-8');",
-    "    return { injected: true, path: filePath, action: 'updated' };",
+    "    return 'updated';",
     '  }',
     '',
     "  const separator = existing.endsWith('\\n') ? '\\n' : '\\n\\n';",
     "  writeFileSync(filePath, existing + separator + content + '\\n', 'utf-8');",
-    "  return { injected: true, path: filePath, action: 'appended' };",
+    "  return 'appended';",
+    '}',
+    '',
+    '/**',
+    ' * Inject engine rules + agent block into a CLAUDE.md file.',
+    ' *',
+    ' * Engine rules (shared, prefix-free) are injected ONCE under',
+    ' * `<!-- soleri:engine-rules -->`. If already present, they are updated.',
+    ' * Agent block (identity + facade table) is injected under',
+    ` * \`<!-- ${marker} -->\`.`,
+    ' */',
+    'function injectIntoFile(filePath: string): InjectResult {',
+    '  // Step 1: Engine rules — shared across all agents',
+    '  const engineAction = injectBlock(filePath, getEngineRulesContent(), getEngineRulesMarker());',
+    '',
+    '  // Step 2: Agent-specific block',
+    '  const agentAction = injectBlock(filePath, getClaudeMdContent(), getClaudeMdMarker());',
+    '',
+    '  return {',
+    '    injected: true,',
+    '    path: filePath,',
+    "    action: agentAction === 'skipped' ? 'appended' : agentAction,",
+    "    engineRules: engineAction !== 'skipped',",
+    '  };',
     '}',
     '',
     '/**',
     ' * Inject agent CLAUDE.md section into a project.',
-    ' * - If no CLAUDE.md exists: creates one',
-    ' * - If markers found: replaces content between them (update)',
-    ' * - If no markers: appends section to end',
+    ' * - Engine rules: injected once, updated if already present',
+    ' * - Agent block: created, updated, or appended',
     ' */',
     'export function injectClaudeMd(projectPath: string): InjectResult {',
     "  return injectIntoFile(join(projectPath, 'CLAUDE.md'));",
     '}',
     '',
     '/**',
-    ' * Inject agent CLAUDE.md section into the global ~/.claude/CLAUDE.md.',
+    ' * Inject into the global ~/.claude/CLAUDE.md.',
     " * Creates ~/.claude/ directory if it doesn't exist.",
     ' * This makes the activation phrase work in any project.',
     ' */',
@@ -83,39 +105,48 @@ export function generateInjectClaudeMd(config: AgentConfig): string {
     '}',
     '',
     '/**',
-    ' * Remove agent section from a specific CLAUDE.md file.',
-    ' * Returns true if the section was found and removed.',
+    ' * Remove a marker-delimited block from a file.',
     ' */',
-    'function removeFromFile(filePath: string): { removed: boolean; path: string } {',
-    '  if (!existsSync(filePath)) return { removed: false, path: filePath };',
+    'function removeBlock(filePath: string, marker: string): boolean {',
+    '  if (!existsSync(filePath)) return false;',
     "  const existing = readFileSync(filePath, 'utf-8');",
-    '  const marker = getClaudeMdMarker();',
     `  const startMarker = '<!-- ' + marker + ' -->';`,
     `  const endMarker = '<!-- /' + marker + ' -->';`,
     '  const startIdx = existing.indexOf(startMarker);',
-    '  if (startIdx === -1) return { removed: false, path: filePath };',
+    '  if (startIdx === -1) return false;',
     '  const endIdx = existing.indexOf(endMarker);',
-    '  if (endIdx === -1) return { removed: false, path: filePath };',
+    '  if (endIdx === -1) return false;',
     "  const before = existing.slice(0, startIdx).replace(/\\n+$/, '');",
     "  const after = existing.slice(endIdx + endMarker.length).replace(/^\\n+/, '');",
     "  const cleaned = before + (before && after ? '\\n\\n' : '') + after;",
     "  writeFileSync(filePath, cleaned || '', 'utf-8');",
-    '  return { removed: true, path: filePath };',
+    '  return true;',
     '}',
     '',
     '/**',
     ' * Remove agent section from the global ~/.claude/CLAUDE.md.',
-    ' * Called on deactivation to clean up after test agents.',
+    ' * Only removes the agent block, NOT the shared engine rules',
+    ' * (other agents may depend on them).',
     ' */',
     'export function removeClaudeMdGlobal(): { removed: boolean; path: string } {',
-    "  return removeFromFile(join(homedir(), '.claude', 'CLAUDE.md'));",
+    "  const filePath = join(homedir(), '.claude', 'CLAUDE.md');",
+    '  return { removed: removeBlock(filePath, getClaudeMdMarker()), path: filePath };',
     '}',
     '',
     '/**',
     ' * Remove agent section from a project CLAUDE.md.',
     ' */',
     'export function removeClaudeMd(projectPath: string): { removed: boolean; path: string } {',
-    "  return removeFromFile(join(projectPath, 'CLAUDE.md'));",
+    "  const filePath = join(projectPath, 'CLAUDE.md');",
+    '  return { removed: removeBlock(filePath, getClaudeMdMarker()), path: filePath };',
+    '}',
+    '',
+    '/**',
+    ' * Remove shared engine rules from a file.',
+    ' * Use only when NO agents remain in the file.',
+    ' */',
+    'export function removeEngineRules(filePath: string): boolean {',
+    '  return removeBlock(filePath, getEngineRulesMarker());',
     '}',
     '',
     '/**',
@@ -126,5 +157,14 @@ export function generateInjectClaudeMd(config: AgentConfig): string {
     "  const content = readFileSync(filePath, 'utf-8');",
     `  return content.includes('<!-- ${marker} -->');`,
     '}',
+    '',
+    '/**',
+    ' * Check if engine rules are already present in a CLAUDE.md file.',
+    ' */',
+    'export function hasEngineRules(filePath: string): boolean {',
+    '  if (!existsSync(filePath)) return false;',
+    "  const content = readFileSync(filePath, 'utf-8');",
+    "  return content.includes('<!-- ' + getEngineRulesMarker() + ' -->');",
+    '}',
   ].join('\n');
 }

package/src/templates/shared-rules.ts

@@ -1,215 +1,264 @@
 /**
- * Shared behavioral rules that every Soleri agent ships with.
+ * Shared Soleri engine rules — agent-agnostic.
  *
- * Mirrors the structure and quality of Salvador's global CLAUDE.md.
- * Uses HTML comment section markers, MANDATORY keywords, compact
- * formatting, and complete lifecycle documentation.
+ * These rules are injected ONCE into global ~/.claude/CLAUDE.md under
+ * the `<!-- soleri:engine-rules -->` marker. They describe behavioral
+ * rules WITHOUT tool prefixes. The active agent's facade table (in its
+ * own `<!-- agent-id:mode -->` block) maps op names to actual tools.
+ *
+ * Uses op:name syntax — the active agent provides the tool prefix.
  */
 
-/** Returns markdown lines for all shared behavioral sections. */
-export function getSharedRules(toolPrefix: string): string[] {
-  const bt = '`';
-
-  return [
-    // ─── Vault-First Protocol ────────────────────────────────
-    '## Vault as Source of Truth',
-    `<!-- ${toolPrefix}:vault-protocol -->`,
-    '',
-    '- **MANDATORY**: Consult the vault BEFORE every decision — planning, design, architecture, patterns, problem-solving.',
-    `- Lookup order: 1) VAULT (${bt}${toolPrefix}_core op:search_intelligent${bt}) → 2) MEMORY (${bt}${toolPrefix}_core op:memory_search${bt}) → 3) CODEBASE → 4) WEB/TRAINING.`,
-    '- If the vault has a pattern, follow it. If it has an anti-pattern, avoid it.',
-    `- Persist lessons: call ${bt}${toolPrefix}_core op:capture_knowledge${bt} — don't just promise "I will remember this".`,
-    '- Exceptions: runtime errors with stack traces → codebase first; user explicitly asks to search web.',
-    '',
-
-    // ─── Planning ────────────────────────────────────────────
-    '## Planning',
-    `<!-- ${toolPrefix}:planning -->`,
-    '',
-    `- Use ${bt}${toolPrefix}_core op:create_plan${bt} before writing ANY code. Show the plan, wait for approval.`,
-    `- Two-gate approval: Gate 1 (${bt}op:approve_plan${bt}), Gate 2 (${bt}op:plan_split${bt}). Never skip either.`,
-    '- Wait for explicit "yes" / "approve" before proceeding past each gate.',
-    `- After execution: ${bt}op:plan_reconcile${bt} (drift report) then ${bt}op:plan_complete_lifecycle${bt} (knowledge capture, archive).`,
-    '- Never let a plan stay in `executing` or `reconciling` state without reminding the user.',
-    '- On session start: check for plans in `executing`/`reconciling` state and remind.',
-    '- Exceptions: read-only operations, user says "just do it", single-line fixes.',
-    '',
-    '### Lifecycle States',
-    '',
-    '| State | Expires | Next Action |',
-    '|-------|---------|-------------|',
-    `| ${bt}draft${bt} | 30 min | ${bt}${toolPrefix}_core op:create_plan${bt} (iterate) |`,
-    `| ${bt}approved${bt} | 30 min | ${bt}${toolPrefix}_core op:plan_split${bt} |`,
-    `| ${bt}executing${bt} | Never | ${bt}${toolPrefix}_core op:plan_reconcile${bt} |`,
-    `| ${bt}reconciling${bt} | Never | ${bt}${toolPrefix}_core op:plan_complete_lifecycle${bt} |`,
-    `| ${bt}completed${bt} | — | Done |`,
-    '',
-    '### Plan Presentation',
-    '',
-    'Every plan summary MUST include this format:',
-    '',
-    '```',
-    '## Plan: [Short Title]',
-    '',
-    '| Field | Value |',
-    '|-------|-------|',
-    '| **Plan ID** | {planId} |',
-    '| **Check ID** | {checkId} |',
-    '| **Grade** | {grade} ({score}/100) |',
-    '| **Status** | {status} |',
-    '| **Lifecycle** | {lifecycleStatus} |',
-    '',
-    '**Objective:** [One sentence]',
-    '',
-    '**Scope:**',
-    '| Included | Excluded |',
-    '|----------|----------|',
-    '| item 1   | item 1   |',
-    '',
-    '**Approach:**',
-    '| Step | Task |',
-    '|------|------|',
-    '| 1 | Description |',
-    '```',
-    '',
-    'Without visible IDs, users cannot resume, reference, or approve plans.',
-    '',
-    '### Drift Report',
-    '',
-    '```',
-    '| Field | Value |',
-    '|-------|-------|',
-    '| **Accuracy** | {accuracyScore}/100 |',
-    '| **Drift Items** | {count} |',
-    '',
-    '| Type | Description | Impact | Rationale |',
-    '|------|-------------|--------|-----------|',
-    '| skipped | ... | medium | ... |',
-    '```',
-    '',
-
-    // ─── Output Formatting ───────────────────────────────────
-    '## Output Formatting',
-    `<!-- ${toolPrefix}:output-formatting -->`,
-    '',
-    '**MANDATORY**: Present tool outputs in human-readable format, NOT raw JSON.',
-    '',
-    '**Tasks** — show as numbered table:',
-    '```',
-    '| # | Type | Task | Complexity |',
-    '|---|------|------|------------|',
-    '| 1 | Impl | ... | High |',
-    '```',
-    '',
-    '**Completion** — show outcome, knowledge captured count, archive path.',
-    '',
-    '**Status lines** — `Persisted: X plans, Y tasks, Z checks` / `Recovered: X plans, Y tasks`',
-    '',
-
-    // ─── Clean Commits ───────────────────────────────────────
-    '## Clean Commits',
-    `<!-- ${toolPrefix}:clean-commits -->`,
-    '',
-    '**MANDATORY**: No AI attribution in commit messages.',
-    '',
-    'Blocked patterns:',
-    '- `Co-Authored-By: Claude` (any variant)',
-    '- `noreply@anthropic.com`',
-    '- `Generated with Claude`, `AI-generated`',
-    '- Any mention of `Anthropic`, `Claude Opus`, `Claude Sonnet`, `Claude Haiku`',
-    '',
-    'Use conventional commits:',
-    '```',
-    'feat: add user authentication',
-    'fix: resolve login timeout issue',
-    'refactor: simplify data fetching logic',
-    '```',
-    '',
-
-    // ─── Knowledge Capture ───────────────────────────────────
-    '## Knowledge Capture',
-    `<!-- ${toolPrefix}:knowledge-capture -->`,
-    '',
-    "**MANDATORY**: Persist lessons, don't just promise them.",
-    '',
-    'When you learn something that should persist:',
-    '1. **DON\'T** just say "I will remember this"',
-    `2. **DO** call ${bt}${toolPrefix}_core op:capture_knowledge${bt} to persist to vault`,
-    "3. **DO** update relevant files if it's a behavioral change",
-    '',
-    '| Type | Tool | Persists To |',
-    '|------|------|-------------|',
-    `| Patterns/Anti-patterns | ${bt}${toolPrefix}_core op:capture_knowledge${bt} | vault |`,
-    `| Quick capture | ${bt}${toolPrefix}_core op:capture_quick${bt} | vault |`,
-    `| Session summaries | ${bt}${toolPrefix}_core op:session_capture${bt} | memory |`,
-    '',
-
-    // ─── Work Task Routing ───────────────────────────────────
-    '## Work Task Routing',
-    `<!-- ${toolPrefix}:task-routing -->`,
-    '',
-    'Use the orchestration layer for ALL work tasks:',
-    `- ${bt}${toolPrefix}_core op:orchestrate_plan${bt} → vault + brain + structured plan.`,
-    `- ${bt}${toolPrefix}_core op:orchestrate_execute${bt} → execution tracking.`,
-    `- ${bt}${toolPrefix}_core op:orchestrate_complete${bt} → epilogue (vault, session).`,
-    '',
-    'The orchestrator handles vault lookup, brain recommendations, and knowledge capture automatically.',
-    '',
-
-    // ─── Intent Detection ────────────────────────────────────
-    '## Intent Detection',
-    `<!-- ${toolPrefix}:intent-detection -->`,
-    '',
-    `**Semantic-First**: Analyze user MEANING before calling ${bt}route_intent${bt}.`,
-    '',
-    '| Signal | Intent |',
-    '|--------|--------|',
-    '| Problem described ("broken", "janky", "weird") | FIX |',
-    '| Need expressed ("I need", "we should have") | BUILD |',
-    '| Quality questioned ("is this right?") | REVIEW |',
-    '| Advice sought ("how should I", "best way") | PLAN |',
-    '| Improvement requested ("make it faster") | IMPROVE |',
-    '| Ready to ship ("deploy", "release") | DELIVER |',
-    '',
-    `Use ${bt}${toolPrefix}_core op:route_intent${bt} only to CONFIRM your analysis or when meaning is unclear.`,
-    '',
-
-    // ─── Validation Loop ─────────────────────────────────────
-    '## Iterative Validation Loop',
-    `<!-- ${toolPrefix}:validation-loop -->`,
-    '',
-    `- When a user gives a **work task**, start a loop: ${bt}${toolPrefix}_core op:loop_start params:{ prompt: "<task>", mode: "custom" }${bt}`,
-    '- Do NOT start loops for: questions, explanations, status checks, git operations, exploration, simple one-line fixes.',
-    '',
-    '| Mode | Tool | Target | Max Iter |',
-    '|------|------|--------|----------|',
-    `| ${bt}plan-iteration${bt} | ${bt}${toolPrefix}_core op:create_plan${bt} | grade >= A | 10 |`,
-    `| ${bt}custom${bt} | user-defined | promise-based | 20 |`,
-    '',
-
-    // ─── Brain-Informed Work ─────────────────────────────────
-    '## Brain-Informed Work',
-    `<!-- ${toolPrefix}:brain -->`,
-    '',
-    '- Brain patterns surface at session start. For relevant patterns, pull rules just-in-time from the vault.',
-    '- 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.",
-    '',
-
-    // ─── Cross-Project Memory ────────────────────────────────
-    '## Cross-Project Memory',
-    `<!-- ${toolPrefix}:cross-project -->`,
-    '',
-    `- Use ${bt}crossProject: true${bt} in ${bt}${toolPrefix}_core op:memory_search${bt} for patterns across related projects.`,
-    `- Promote universal patterns to global pool with ${bt}${toolPrefix}_core op:memory_promote_to_global${bt}.`,
-    '',
-
-    // ─── Session Lifecycle ───────────────────────────────────
-    '## Session Lifecycle',
-    `<!-- ${toolPrefix}:session -->`,
-    '',
-    'A PreCompact hook calls `session_capture` before context compaction.',
-    `Manual capture: ${bt}${toolPrefix}_core op:session_capture params:{ summary: "..." }${bt}`,
-    '',
-  ];
+const ENGINE_MARKER = 'soleri:engine-rules';
+
+export function getEngineMarker(): string {
+  return ENGINE_MARKER;
 }
+
+/** Returns the full engine rules markdown content (with markers). */
+export function getEngineRulesContent(): string {
+  return ENGINE_RULES_LINES.join('\n');
+}
+
+const ENGINE_RULES_LINES: string[] = [
+  `<!-- ${ENGINE_MARKER} -->`,
+  '',
+  '# Soleri Engine Rules',
+  '',
+  "Shared behavioral rules for all Soleri agents. The active agent's facade table provides tool names.",
+  '',
+
+  // ─── Response Integrity ─────────────────────────────────
+  '## Response Integrity',
+  '<!-- soleri:response-integrity -->',
+  '',
+  '- If you\'re not confident in your answer, say "I\'m not sure" and explain why. Never guess.',
+  '- After every response, rate your confidence from 1 to 10. Anything below 7, flag it.',
+  '',
+
+  // ─── Memory Quality Gate ───────────────────────────────
+  '## Memory Quality Gate',
+  '<!-- soleri:memory-quality -->',
+  '',
+  '**MANDATORY** before writing to auto memory: apply the **"Will I hit this again?"** test.',
+  '',
+  '**SAVE** — recurring bugs, non-obvious gotchas, structural issues, behavioral quirks that will resurface.',
+  "**NEVER SAVE** — one-time config, solved-and-done fixes, values already persisted in files, setup steps that won't repeat, anything where the fix is already in the codebase.",
+  '',
+  "If in doubt, don't save. Less memory with high signal beats more memory with noise.",
+  '',
+
+  // ─── Vault-First Protocol ────────────────────────────────
+  '## Vault as Source of Truth',
+  '<!-- soleri:vault-protocol -->',
+  '',
+  '- **MANDATORY**: Consult the vault BEFORE every decision — planning, design, architecture, patterns, problem-solving.',
+  '- Lookup order: 1) VAULT (`op:search_intelligent`) → 2) MEMORY (`op:memory_search`) → 3) CODEBASE → 4) WEB/TRAINING.',
+  '- If the vault has a pattern, follow it. If it has an anti-pattern, avoid it.',
+  '- Persist lessons: call `op:capture_knowledge` — don\'t just promise "I will remember this".',
+  '- Exceptions: runtime errors with stack traces → codebase first; user explicitly asks to search web.',
+  '',
+
+  // ─── Planning ────────────────────────────────────────────
+  '## Planning',
+  '<!-- soleri:planning -->',
+  '',
+  '- Use `op:create_plan` before writing ANY code. Show the plan, wait for approval.',
+  '- Two-gate approval: Gate 1 (`op:approve_plan`), Gate 2 (`op:plan_split`). Never skip either.',
+  '- Wait for explicit "yes" / "approve" before proceeding past each gate.',
+  '- After execution: `op:plan_reconcile` (drift report) then `op:plan_complete_lifecycle` (knowledge capture, archive).',
+  '- Never let a plan stay in `executing` or `reconciling` state without reminding the user.',
+  '- On session start: check for plans in `executing`/`reconciling` state and remind.',
+  '- Exceptions: read-only operations, user says "just do it", single-line fixes.',
+  '',
+  '### Lifecycle States',
+  '',
+  '| State | Expires | Next Action |',
+  '|-------|---------|-------------|',
+  '| `draft` | 30 min | `op:create_plan` (iterate) |',
+  '| `approved` | 30 min | `op:plan_split` |',
+  '| `executing` | Never | `op:plan_reconcile` |',
+  '| `reconciling` | Never | `op:plan_complete_lifecycle` |',
+  '| `completed` | — | Done |',
+  '',
+  '### Plan Presentation',
+  '',
+  'Every plan summary MUST include this format:',
+  '',
+  '```',
+  '## Plan: [Short Title]',
+  '',
+  '| Field | Value |',
+  '|-------|-------|',
+  '| **Plan ID** | {planId} |',
+  '| **Check ID** | {checkId} |',
+  '| **Grade** | {grade} ({score}/100) |',
+  '| **Status** | {status} |',
+  '| **Lifecycle** | {lifecycleStatus} |',
+  '',
+  '**Objective:** [One sentence]',
+  '',
+  '**Scope:**',
+  '| Included | Excluded |',
+  '|----------|----------|',
+  '| item 1   | item 1   |',
+  '',
+  '**Approach:**',
+  '| Step | Task |',
+  '|------|------|',
+  '| 1 | Description |',
+  '```',
+  '',
+  'Without visible IDs, users cannot resume, reference, or approve plans.',
+  '',
+  '### Drift Report',
+  '',
+  '```',
+  '| Field | Value |',
+  '|-------|-------|',
+  '| **Accuracy** | {accuracyScore}/100 |',
+  '| **Drift Items** | {count} |',
+  '',
+  '| Type | Description | Impact | Rationale |',
+  '|------|-------------|--------|-----------|',
+  '| skipped | ... | medium | ... |',
+  '```',
+  '',
+
+  // ─── Output Formatting ───────────────────────────────────
+  '## Output Formatting',
+  '<!-- soleri:output-formatting -->',
+  '',
+  '**MANDATORY**: Present tool outputs in human-readable format, NOT raw JSON.',
+  '',
+  '**Tasks** — show as numbered table:',
+  '```',
+  '| # | Type | Task | Complexity |',
+  '|---|------|------|------------|',
+  '| 1 | Impl | ... | High |',
+  '```',
+  '',
+  '**Completion** — show outcome, knowledge captured count, archive path.',
+  '',
+  '**Status lines** — `Persisted: X plans, Y tasks, Z checks` / `Recovered: X plans, Y tasks`',
+  '',
+
+  // ─── Clean Commits ───────────────────────────────────────
+  '## Clean Commits',
+  '<!-- soleri:clean-commits -->',
+  '',
+  '**MANDATORY**: No AI attribution in commit messages.',
+  '',
+  'Blocked patterns:',
+  '- `Co-Authored-By: Claude` (any variant)',
+  '- `noreply@anthropic.com`',
+  '- `Generated with Claude`, `AI-generated`',
+  '- Any mention of `Anthropic`, `Claude Opus`, `Claude Sonnet`, `Claude Haiku`',
+  '',
+  'Use conventional commits:',
+  '```',
+  'feat: add user authentication',
+  'fix: resolve login timeout issue',
+  'refactor: simplify data fetching logic',
+  '```',
+  '',
+
+  // ─── Knowledge Capture ───────────────────────────────────
+  '## Knowledge Capture',
+  '<!-- soleri:knowledge-capture -->',
+  '',
+  "**MANDATORY**: Persist lessons, don't just promise them.",
+  '',
+  'When you learn something that should persist:',
+  '1. **DON\'T** just say "I will remember this"',
+  '2. **DO** call `op:capture_knowledge` to persist to vault',
+  "3. **DO** update relevant files if it's a behavioral change",
+  '',
+  '| Type | Op | Persists To |',
+  '|------|-----|-------------|',
+  '| Patterns/Anti-patterns | `op:capture_knowledge` | vault |',
+  '| Quick capture | `op:capture_quick` | vault |',
+  '| Session summaries | `op:session_capture` | memory |',
+  '',
+
+  // ─── Work Task Routing ───────────────────────────────────
+  '## Work Task Routing',
+  '<!-- soleri:task-routing -->',
+  '',
+  'Use the orchestration layer for ALL work tasks:',
+  '- `op:orchestrate_plan` → vault + brain + structured plan.',
+  '- `op:orchestrate_execute` → execution tracking.',
+  '- `op:orchestrate_complete` → epilogue (vault, session).',
+  '',
+  'The orchestrator handles vault lookup, brain recommendations, and knowledge capture automatically.',
+  '',
+
+  // ─── Intent Detection ────────────────────────────────────
+  '## Intent Detection',
+  '<!-- soleri:intent-detection -->',
+  '',
+  '**Semantic-First**: Analyze user MEANING before calling `op:route_intent`.',
+  '',
+  '| Signal | Intent |',
+  '|--------|--------|',
+  '| Problem described ("broken", "janky", "weird") | FIX |',
+  '| Need expressed ("I need", "we should have") | BUILD |',
+  '| Quality questioned ("is this right?") | REVIEW |',
+  '| Advice sought ("how should I", "best way") | PLAN |',
+  '| Improvement requested ("make it faster") | IMPROVE |',
+  '| Ready to ship ("deploy", "release") | DELIVER |',
+  '',
+  'Use `op:route_intent` only to CONFIRM your analysis or when meaning is unclear.',
+  '',
+
+  // ─── Validation Loop ─────────────────────────────────────
+  '## Iterative Validation Loop',
+  '<!-- soleri:validation-loop -->',
+  '',
+  '- When a user gives a **work task**, start a loop: `op:loop_start params:{ prompt: "<task>", mode: "custom" }`',
+  '- Do NOT start loops for: questions, explanations, status checks, git operations, exploration, simple one-line fixes.',
+  '',
+  '| Mode | Op | Target | Max Iter |',
+  '|------|-----|--------|----------|',
+  '| `plan-iteration` | `op:create_plan` | grade >= A | 10 |',
+  '| `custom` | user-defined | promise-based | 20 |',
+  '',
+
+  // ─── Brain-Informed Work ─────────────────────────────────
+  '## Brain-Informed Work',
+  '<!-- soleri:brain -->',
+  '',
+  '- Brain patterns surface at session start. For relevant patterns, pull rules just-in-time from the vault.',
+  '- 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.",
+  '',
+
+  // ─── Cross-Project Memory ────────────────────────────────
+  '## Cross-Project Memory',
+  '<!-- soleri:cross-project -->',
+  '',
+  '- Use `crossProject: true` in `op:memory_search` for patterns across related projects.',
+  '- Promote universal patterns to global pool with `op:memory_promote_to_global`.',
+  '',
+
+  // ─── Session Lifecycle ───────────────────────────────────
+  '## Session Lifecycle',
+  '<!-- soleri:session -->',
+  '',
+  '### Session Start Protocol',
+  '',
+  'On EVERY new session:',
+  '1. Register project: `op:register params:{ projectPath: "." }`',
+  '2. Check activation response for `persistence.status`, `vault.connected`, `project.registered`.',
+  '3. Check for plans awaiting reconciliation via `op:check_persistence`:',
+  '   - `executing` → Remind user to call `op:plan_reconcile`.',
+  '   - `reconciling` → Remind user to call `op:plan_complete_lifecycle`.',
+  '',
+  '### Context Compaction',
+  '',
+  'A PreCompact hook calls `op:session_capture` before context compaction.',
+  'Manual capture: `op:session_capture params:{ summary: "..." }`',
+  '',
+
+  `<!-- /${ENGINE_MARKER} -->`,
+];