@soleri/forge 9.0.1 → 9.2.0

package/src/skills/second-opinion/SKILL.md

@@ -12,7 +12,7 @@ Get an informed recommendation that synthesizes vault knowledge, brain patterns,
 ### 1. Understand the Decision
 
 ```
-ernesto_core op:route_intent
+YOUR_AGENT_core op:route_intent
   params: { prompt: "<user's question>" }
 ```
 
@@ -20,20 +20,20 @@ ernesto_core op:route_intent
 
 **Vault** — previous decisions, patterns, anti-patterns:
 ```
-ernesto_core op:search_intelligent
+YOUR_AGENT_core op:search_intelligent
   params: { query: "<the decision or options>" }
 ```
 
 **Brain** — proven approaches:
 ```
-ernesto_core op:brain_strengths
-ernesto_core op:brain_recommend
+YOUR_AGENT_core op:brain_strengths
+YOUR_AGENT_core op:brain_recommend
   params: { projectName: "<current project>" }
 ```
 
 **Cross-project** — what other projects chose:
 ```
-ernesto_core op:memory_cross_project_search
+YOUR_AGENT_core op:memory_cross_project_search
   params: { query: "<topic>", crossProject: true }
 ```
 
@@ -69,7 +69,7 @@ ernesto_core op:memory_cross_project_search
 ### 4. Capture the Decision
 
 ```
-ernesto_core op:capture_knowledge
+YOUR_AGENT_core op:capture_knowledge
   params: {
     title: "<decision title>",
     description: "<chosen option, rationale, rejected alternatives>",

package/src/skills/systematic-debugging/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: systematic-debugging
-description: Use when encountering any bug, test failure, or unexpected behavior — before proposing fixes.
+description: >
+  Use as the FIRST response when something is broken — "bug", "failing test", "not working",
+  "debug this", "error", "crash", "unexpected behavior", "weird issue". Diagnoses root cause
+  before proposing fixes. After root cause is found, hand off to fix-and-learn for repair and
+  knowledge capture.
 ---
 
 # Systematic Debugging
@@ -12,10 +16,10 @@ description: Use when encountering any bug, test failure, or unexpected behavior
 **BEFORE touching any code:**
 
 ```
-ernesto_core op:search_intelligent
+YOUR_AGENT_core op:search_intelligent
   params: { query: "<bug or error message>" }
-ernesto_core op:brain_strengths
-ernesto_core op:memory_search
+YOUR_AGENT_core op:brain_strengths
+YOUR_AGENT_core op:memory_search
   params: { query: "<error or symptom>" }
 ```
 
@@ -26,7 +30,7 @@ Only if vault and web produce no answer, proceed to Phase 1.
 ## Start a Debug Loop
 
 ```
-ernesto_core op:loop_start
+YOUR_AGENT_core op:loop_start
   params: { prompt: "Debug: <bug>", mode: "custom" }
 ```
 
@@ -60,8 +64,8 @@ Form single hypothesis, test minimally (one variable at a time), verify before c
 ## Phase 5: Capture the Learning
 
 ```
-ernesto_core op:loop_complete
-ernesto_core op:capture_knowledge
+YOUR_AGENT_core op:loop_complete
+YOUR_AGENT_core op:capture_knowledge
   params: {
     title: "<bug>",
     description: "<root cause, solution, what made it hard to find>",
@@ -69,7 +73,7 @@ ernesto_core op:capture_knowledge
     category: "<domain>",
     tags: ["<relevant>"]
   }
-ernesto_core op:session_capture
+YOUR_AGENT_core op:session_capture
 ```
 
 ## Red Flags — STOP and Return to Phase 1

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

@@ -10,9 +10,9 @@ description: Use when implementing any feature or bugfix — write failing tests
 ## Before You Start — Search First
 
 ```
-ernesto_core op:search_intelligent
+YOUR_AGENT_core op:search_intelligent
   params: { query: "<what you're about to test>" }
-ernesto_core op:brain_strengths
+YOUR_AGENT_core op:brain_strengths
 ```
 
 If vault has testing guidance for this domain, follow it.
@@ -20,7 +20,7 @@ If vault has testing guidance for this domain, follow it.
 ## Start a TDD Loop
 
 ```
-ernesto_core op:loop_start
+YOUR_AGENT_core op:loop_start
   params: { prompt: "TDD: <feature>", mode: "custom" }
 ```
 
@@ -63,8 +63,8 @@ Next failing test for next behavior.
 ## After TDD
 
 ```
-ernesto_core op:loop_complete
-ernesto_core op:capture_quick
+YOUR_AGENT_core op:loop_complete
+YOUR_AGENT_core op:capture_quick
   params: { title: "<testing pattern>", description: "<what you learned>" }
 ```
 

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

@@ -1,6 +1,10 @@
 ---
 name: vault-capture
-description: Use when persisting a pattern, anti-pattern, workflow, decision, or principle to the knowledge base — after discovering something worth remembering.
+description: >
+  Use to capture a SINGLE known pattern, anti-pattern, workflow, decision, or principle to the
+  vault. Triggers on "save this", "capture this", "remember this pattern", "add to vault". The
+  user already knows what to capture. For bulk extraction from documents, code, or PRs, use
+  knowledge-harvest instead.
 ---
 
 # Vault Capture — Persist Knowledge
@@ -12,9 +16,9 @@ Capture patterns, anti-patterns, workflows, and principles to the vault. Capture
 ### 1. Check for Duplicates
 
 ```
-ernesto_core op:search_intelligent
+YOUR_AGENT_core op:search_intelligent
   params: { query: "<knowledge title or description>" }
-ernesto_core op:curator_detect_duplicates
+YOUR_AGENT_core op:curator_detect_duplicates
 ```
 
 If similar entry exists, update it instead of creating a duplicate.
@@ -32,7 +36,7 @@ If similar entry exists, update it instead of creating a duplicate.
 ### 3. Capture
 
 ```
-ernesto_core op:capture_knowledge
+YOUR_AGENT_core op:capture_knowledge
   params: {
     title: "<clear, searchable name>",
     description: "<what it is and when it applies>",
@@ -44,7 +48,7 @@ ernesto_core op:capture_knowledge
   }
 ```
 
-For quick captures: `ernesto_core op:capture_quick params: { title: "<name>", description: "<details>" }`
+For quick captures: `YOUR_AGENT_core op:capture_quick params: { title: "<name>", description: "<details>" }`
 
 ### 4. Post-Capture Quality
 

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

@@ -1,6 +1,10 @@
 ---
 name: vault-navigator
-description: Use when querying the knowledge base for existing solutions, patterns, best practices, or prior art before building something new.
+description: >
+  Use when the user asks "search the vault", "find patterns for", "have we seen this before",
+  "what does the vault say about", "best practice for", "check vault", "vault search", or wants
+  to query the knowledge base for existing solutions and prior art. For saving a new entry, use
+  vault-capture instead.
 ---
 
 # Vault Navigator — Knowledge Oracle
@@ -12,7 +16,7 @@ Navigate the vault intelligently. Picks the right search strategy based on what
 ### "Have we seen this?" / "Best practice for X"
 
 ```
-ernesto_core op:search_intelligent
+YOUR_AGENT_core op:search_intelligent
   params: { query: "<question>" }
 ```
 
@@ -21,30 +25,30 @@ If results are weak, fall back to `op:search` with explicit filters (type, categ
 ### "Show me everything about X" (Exploration)
 
 ```
-ernesto_core op:vault_tags
-ernesto_core op:vault_domains
-ernesto_core op:vault_recent
+YOUR_AGENT_core op:vault_tags
+YOUR_AGENT_core op:vault_domains
+YOUR_AGENT_core op:vault_recent
 ```
 
 ### "What's stale?" / "What needs updating?"
 
 ```
-ernesto_core op:vault_age_report
+YOUR_AGENT_core op:vault_age_report
 ```
 
 ### "What do other projects do?"
 
 ```
-ernesto_core op:memory_cross_project_search
+YOUR_AGENT_core op:memory_cross_project_search
   params: { query: "<topic>", crossProject: true }
-ernesto_core op:project_linked_projects
+YOUR_AGENT_core op:project_linked_projects
 ```
 
 ### "Has brain learned about X?"
 
 ```
-ernesto_core op:brain_strengths
-ernesto_core op:brain_global_patterns
+YOUR_AGENT_core op:brain_strengths
+YOUR_AGENT_core op:brain_global_patterns
   params: { domain: "<domain>" }
 ```
 

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

@@ -0,0 +1,251 @@
+---
+name: vault-smells
+description: >
+  Use for deep knowledge quality analysis — finding contradictions, stale patterns, orphaned entries,
+  weak links, knowledge decay, and structural issues in the vault. Triggers on "vault smells",
+  "knowledge quality", "vault analysis", "find contradictions", "stale patterns", "knowledge debt",
+  "vault deep check", "is my vault healthy". Goes deeper than health-check (which is operational).
+  For code review, use deep-review instead.
+---
+
+# Vault Smells — Knowledge Quality Deep Analysis
+
+Detects structural problems in the knowledge base that degrade decision quality over time. Goes beyond operational health (is the DB up?) into knowledge integrity (is the knowledge trustworthy?).
+
+## Smell Categories
+
+### 1. Contradiction Smells
+
+Entries that give conflicting guidance. The most dangerous smell — leads to inconsistent decisions.
+
+```
+YOUR_AGENT_core op:curator_contradictions
+```
+
+**What to look for:**
+- Two patterns that recommend opposite approaches for the same situation
+- An anti-pattern that contradicts an active pattern
+- Entries from different time periods with conflicting advice (the older one may be stale)
+
+**Resolution:** Present contradictions to user. One must win — archive the loser or scope them to different contexts.
+
+### 2. Staleness Smells
+
+Knowledge that was true once but may not be anymore.
+
+```
+YOUR_AGENT_core op:vault_age_report
+```
+
+**Indicators:**
+- Entries >60 days without access or update
+- Patterns referencing APIs, libraries, or versions that have changed
+- Entries tagged with technologies the project no longer uses
+- Confidence scores that haven't been reinforced by brain feedback
+
+**Action:** Flag for review. Don't auto-delete — stale doesn't mean wrong.
+
+### 3. Orphan Smells
+
+Entries with no connections to the rest of the knowledge graph.
+
+```
+YOUR_AGENT_core op:admin_vault_analytics
+YOUR_AGENT_core op:curator_detect_duplicates
+```
+
+**Indicators:**
+- Entries with zero inbound or outbound links
+- Entries never returned in search results (check search insights)
+- Entries with no tags or only generic tags
+- Entries that were captured but never groomed
+
+**Why it matters:** Orphans don't surface when needed. They're knowledge that exists but can't be found. In a Zettelkasten, an unlinked note is a dead note.
+
+**Action:** Link, merge, or archive. Every entry should connect to at least one other.
+
+### 4. Duplication Smells
+
+Multiple entries covering the same ground with slight variations.
+
+```
+YOUR_AGENT_core op:curator_detect_duplicates
+```
+
+**Indicators:**
+- High similarity scores between entries
+- Same tags and category but different titles
+- Entries captured in different sessions about the same topic
+- Parallel entries — one as pattern, one as anti-pattern for the same concept
+
+**Action:** Merge the best parts into one authoritative entry. Archive the rest.
+
+### 5. Shallow Entry Smells
+
+Entries that exist but lack substance — captured in a hurry, never enriched.
+
+```
+YOUR_AGENT_core op:curator_health_audit
+```
+
+**Indicators:**
+- Description under 50 characters
+- No examples or context
+- Missing "why" — only states "what" without rationale
+- No tags beyond the auto-generated ones
+- Quality score below 40
+
+**Action:** Enrich with context, examples, and rationale — or archive if no longer relevant.
+
+### 6. Category Drift Smells
+
+The taxonomy has grown inconsistent over time.
+
+```
+YOUR_AGENT_core op:vault_domains
+YOUR_AGENT_core op:vault_tags
+```
+
+**Indicators:**
+- Near-duplicate categories (e.g., "error-handling" and "errors" and "exception-handling")
+- Categories with only 1-2 entries (too granular)
+- Tags used inconsistently (same concept, different tag names)
+- Entries miscategorized (architecture pattern filed under "testing")
+
+**Action:** Normalize with `op:curator_groom_all`. Merge overlapping categories.
+
+### 7. Confidence Decay Smells
+
+Brain patterns losing strength without reinforcement.
+
+```
+YOUR_AGENT_core op:brain_strengths
+```
+
+**Indicators:**
+- Patterns with high initial strength that have decayed below 0.3
+- Patterns that were strong but haven't received positive feedback in >30 days
+- Patterns with mixed feedback (both positive and negative) — unresolved
+
+**Action:** Review with user. Reinforce valid patterns, retire invalid ones.
+
+### 8. Knowledge Gap Smells
+
+Areas where the vault *should* have knowledge but doesn't.
+
+```
+YOUR_AGENT_core op:admin_search_insights
+```
+
+**Indicators:**
+- Repeated search queries that return no results
+- Domains the project uses but vault has no entries for
+- Anti-patterns captured without corresponding patterns (what to do instead?)
+- Patterns without linked anti-patterns (what to avoid?)
+
+**Action:** Create targeted entries to fill gaps. Use knowledge-harvest skill on relevant docs/code.
+
+## Running the Analysis
+
+### Step 1: Gather Data
+
+```
+YOUR_AGENT_core op:admin_health
+YOUR_AGENT_core op:admin_vault_analytics
+YOUR_AGENT_core op:curator_health_audit
+YOUR_AGENT_core op:curator_contradictions
+YOUR_AGENT_core op:curator_detect_duplicates
+YOUR_AGENT_core op:vault_age_report
+YOUR_AGENT_core op:vault_domains
+YOUR_AGENT_core op:vault_tags
+YOUR_AGENT_core op:brain_strengths
+YOUR_AGENT_core op:admin_search_insights
+```
+
+### Step 2: Classify Smells
+
+For each smell category, assess severity:
+
+| Severity | Meaning |
+|----------|---------|
+| 🟢 Clean | No issues in this category |
+| 🟡 Minor | 1-3 instances, low impact |
+| 🟠 Moderate | Multiple instances, degrading quality |
+| 🔴 Critical | Widespread, actively causing bad decisions |
+
+### Step 3: Present the Report
+
+```
+## Vault Smell Report
+
+### Overview
+| Metric | Value |
+|--------|-------|
+| Total entries | X |
+| Overall health score | X/100 |
+| Smells found | X across Y categories |
+
+### Smell Summary
+| Category | Severity | Count | Impact |
+|----------|----------|-------|--------|
+| Contradictions | 🔴/🟠/🟡/🟢 | X | Inconsistent decisions |
+| Staleness | 🔴/🟠/🟡/🟢 | X | Outdated guidance |
+| Orphans | 🔴/🟠/🟡/🟢 | X | Unfindable knowledge |
+| Duplicates | 🔴/🟠/🟡/🟢 | X | Noise, conflicting versions |
+| Shallow entries | 🔴/🟠/🟡/🟢 | X | Low-value knowledge |
+| Category drift | 🔴/🟠/🟡/🟢 | X | Poor discoverability |
+| Confidence decay | 🔴/🟠/🟡/🟢 | X | Unreliable recommendations |
+| Knowledge gaps | 🔴/🟠/🟡/🟢 | X | Blind spots |
+
+### Critical Findings
+[Top 3 most impactful issues with specific entries/examples]
+
+### Recommended Actions
+| Priority | Action | Effort | Impact |
+|----------|--------|--------|--------|
+| 1 | [most impactful fix] | Low/Med/High | High |
+| 2 | [second] | Low/Med/High | Med |
+| 3 | [third] | Low/Med/High | Med |
+
+### Trend (if prior reports exist)
+| Metric | Last Check | Now | Direction |
+|--------|-----------|-----|-----------|
+| Health score | X | Y | ↑/↓/→ |
+| Smell count | X | Y | ↑/↓/→ |
+```
+
+### Step 4: Fix (with user approval)
+
+Do NOT auto-fix. Present findings, get approval, then:
+
+- Contradictions → `op:curator_resolve_contradiction`
+- Duplicates → `op:curator_groom` (merge)
+- Orphans → link or archive
+- Shallow entries → enrich or archive
+- Category drift → `op:curator_groom_all` (normalize)
+- Gaps → `op:capture_knowledge` (fill)
+
+After fixes: `op:brain_build_intelligence` to rebuild with clean data.
+
+## Common Mistakes
+
+- Auto-fixing without presenting findings first (user may disagree)
+- Treating all smells as equally urgent (contradictions >> orphans)
+- Deleting stale entries without checking if they're still valid
+- Running this too frequently (monthly is usually enough)
+- Not rebuilding brain intelligence after major cleanup
+
+## Quick Reference
+
+| Smell | Detection Op | Fix Op |
+|-------|-------------|--------|
+| Contradictions | `curator_contradictions` | `curator_resolve_contradiction` |
+| Staleness | `vault_age_report` | Review + archive/update |
+| Orphans | `admin_vault_analytics` | Link or archive |
+| Duplicates | `curator_detect_duplicates` | `curator_groom` (merge) |
+| Shallow entries | `curator_health_audit` | Enrich or archive |
+| Category drift | `vault_domains` + `vault_tags` | `curator_groom_all` |
+| Confidence decay | `brain_strengths` | Reinforce or retire |
+| Knowledge gaps | `admin_search_insights` | `capture_knowledge` |
+
+**Related skills:** health-check (operational status), vault-curate (active cleanup), knowledge-harvest (fill gaps)

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

@@ -1,6 +1,9 @@
 ---
 name: verification-before-completion
-description: Use when about to claim work is complete, fixed, or passing — before committing, creating PRs, or moving to the next task.
+description: >
+  Use as an internal quality gate before claiming any task is done — run tests, check output,
+  verify behavior. This is a mid-workflow checkpoint, not a shipping gate. For actual deployment
+  and release workflows, use deliver-and-ship instead.
 ---
 
 # Verification Before Completion
@@ -32,9 +35,9 @@ If you haven't run the verification command in this message, you cannot claim it
 
 After passing verification commands:
 
-- `ernesto_core op:admin_health` — catches vault corruption, stale caches
-- `ernesto_core op:admin_diagnostic` — module status, database integrity, config validity
-- `ernesto_core op:admin_vault_analytics` — knowledge quality metrics
+- `YOUR_AGENT_core op:admin_health` — catches vault corruption, stale caches
+- `YOUR_AGENT_core op:admin_diagnostic` — module status, database integrity, config validity
+- `YOUR_AGENT_core op:admin_vault_analytics` — knowledge quality metrics
 
 If any check reports problems, address before claiming completion.
 
@@ -63,7 +66,7 @@ If any check reports problems, address before claiming completion.
 
 ## After Verification
 
-Capture session summary: `ernesto_core op:session_capture params: { summary: "<what was accomplished>" }`
+Capture session summary: `YOUR_AGENT_core op:session_capture params: { summary: "<what was accomplished>" }`
 
 ## Common Mistakes
 

package/src/skills/writing-plans/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: writing-plans
-description: Use when there is a spec or requirements for a multi-step task and an implementation plan needs to be written before touching code.
+description: >
+  Use when the user has clear requirements or a spec and needs a structured implementation plan —
+  "create a plan", "break this down", "plan the implementation". Requirements are already known.
+  For open-ended exploration when requirements are unclear, use brainstorming instead.
 ---
 
 # Writing Plans
@@ -16,11 +19,11 @@ Write implementation plans assuming the engineer has zero codebase context. Docu
 ### 1. Vault First
 
 ```
-ernesto_core op:search_intelligent
+YOUR_AGENT_core op:search_intelligent
   params: { query: "<feature being planned>" }
-ernesto_core op:brain_strengths
-ernesto_core op:vault_domains
-ernesto_core op:vault_tags
+YOUR_AGENT_core op:brain_strengths
+YOUR_AGENT_core op:vault_domains
+YOUR_AGENT_core op:vault_tags
 ```
 
 ### 2. Web Search Second
@@ -34,7 +37,7 @@ Incorporate vault insights and web findings. Reference specific entries.
 ## Create a Tracked Plan
 
 ```
-ernesto_core op:create_plan
+YOUR_AGENT_core op:create_plan
   params: {
     objective: "<one-sentence goal>",
     scope: { included: [...], excluded: [...] },
@@ -45,16 +48,16 @@ ernesto_core op:create_plan
 ## Grade and Improve
 
 ```
-ernesto_core op:plan_grade params: { planId: "<id>" }
-ernesto_core op:plan_auto_improve params: { planId: "<id>" }
-ernesto_core op:plan_meets_grade params: { planId: "<id>", targetGrade: "A" }
+YOUR_AGENT_core op:plan_grade params: { planId: "<id>" }
+YOUR_AGENT_core op:plan_auto_improve params: { planId: "<id>" }
+YOUR_AGENT_core op:plan_meets_grade params: { planId: "<id>", targetGrade: "A" }
 ```
 
 Iterate with: `op:plan_iterate params: { planId: "<id>", feedback: "<improvement>" }`
 
 ## Split into Tasks
 
-After approval: `ernesto_core op:plan_split params: { planId: "<id>" }`
+After approval: `YOUR_AGENT_core op:plan_split params: { planId: "<id>" }`
 
 ## Task Granularity
 
@@ -80,7 +83,7 @@ Each step is one action (2-5 minutes): write failing test, run it, implement, ru
 ## After Approval
 
 ```
-ernesto_core op:approve_plan params: { planId: "<id>" }
+YOUR_AGENT_core op:approve_plan params: { planId: "<id>" }
 ```
 
 Offer execution choice: subagent-driven (this session) or parallel session with executing-plans.

package/src/templates/agents-md.ts

@@ -61,13 +61,13 @@ When the user asks about your capabilities or you need to check what you've lear
 ## Session Start
 
 Do NOT call any tools automatically on session start. Just greet the user in character.
-Only call ${bt}${tp}_orchestrate op:register${bt} or ${bt}${tp}_core op:activate${bt} when you actually need project context or capability discovery — not on every message.
+Only call ${bt}${tp}_orchestrate op:session_start${bt} or ${bt}${tp}_core op:activate${bt} when you actually need project context or capability discovery — not on every message.
 
 ## Essential Tools
 
 | Facade | Key Ops |
 |--------|---------|
-| ${bt}${tp}_core${bt} | ${bt}health${bt}, ${bt}search${bt}, ${bt}identity${bt}, ${bt}register${bt}, ${bt}activate${bt} |
+| ${bt}${tp}_core${bt} | ${bt}health${bt}, ${bt}search${bt}, ${bt}identity${bt}, ${bt}session_start${bt}, ${bt}activate${bt} |
 ${domainRows}
 | ${bt}${tp}_vault${bt} | ${bt}search_intelligent${bt}, ${bt}capture_knowledge${bt}, ${bt}capture_quick${bt}, ${bt}search_feedback${bt} |
 | ${bt}${tp}_vault${bt} (keeper) | ${bt}knowledge_audit${bt}, ${bt}knowledge_health${bt}, ${bt}knowledge_merge${bt}, ${bt}knowledge_reorganize${bt} |

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

@@ -66,7 +66,7 @@ export function generateClaudeMdTemplate(config: AgentConfig): string {
     // ─── Session Start ─────────────────────────────────────
     '## Session Start',
     '',
-    `On every new session: ${bt}${toolPrefix}_orchestrate op:register params:{ projectPath: "." }${bt}`,
+    `On every new session: ${bt}${toolPrefix}_orchestrate op:session_start params:{ projectPath: "." }${bt}`,
     '',
   ];
 
@@ -77,7 +77,7 @@ export function generateClaudeMdTemplate(config: AgentConfig): string {
     '',
     '| Facade | Key Ops |',
     '|--------|---------|',
-    `| ${bt}${toolPrefix}_core${bt} | ${bt}health${bt}, ${bt}search${bt}, ${bt}identity${bt}, ${bt}register${bt}, ${bt}activate${bt} |`,
+    `| ${bt}${toolPrefix}_core${bt} | ${bt}health${bt}, ${bt}search${bt}, ${bt}identity${bt}, ${bt}session_start${bt}, ${bt}activate${bt} |`,
   );
 
   // Domain facades — one row per domain

package/src/templates/shared-rules.ts

@@ -119,6 +119,7 @@ const ENGINE_RULES_LINES: string[] = [
   '## Planning',
   '<!-- soleri:planning -->',
   '',
+  '- **MANDATORY**: Create a formal plan (`op:create_plan`) for every work task. Memory and vault knowledge alone are not sufficient — plans must be persisted and graded.',
   '- 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.',
@@ -127,6 +128,15 @@ const ENGINE_RULES_LINES: string[] = [
   '- On session start: check for plans in `executing`/`reconciling` state and remind.',
   '- Exceptions: read-only operations, user says "just do it", single-line fixes.',
   '',
+  '### Grade Gate',
+  '',
+  '**MANDATORY**: Plans must grade **A or higher** before approval. The engine enforces this programmatically.',
+  '',
+  '- `op:approve_plan` will **reject** any plan with a latest grade below A (score < 90).',
+  '- If rejected, iterate on the plan (`op:create_plan`) to address the gaps, then re-grade (`op:plan_grade`) before approving.',
+  '- The threshold is configurable per-agent via `engine.minGradeForApproval` in `agent.yaml` (default: `A`).',
+  '- Plans with no grade check are allowed through for backward compatibility.',
+  '',
   '### Lifecycle States',
   '',
   '| State | Expires | Next Action |',
@@ -339,7 +349,7 @@ const ENGINE_RULES_LINES: string[] = [
   '### Session Start Protocol',
   '',
   'Do NOT call tools automatically on session start — just greet the user in character.',
-  'Call `op:register` only when you need project context for a task (not on every message).',
+  'Call `op:session_start` only when you need project context for a task (not on every message).',
   'Call `op:activate` only when checking evolved capabilities or recovering session state.',
   '',
   '### Context Compaction',
@@ -418,5 +428,30 @@ const ENGINE_RULES_LINES: string[] = [
   '| Template drift suspected | `soleri agent diff` to see what changed |',
   '',
 
+  // ─── Verification Protocol ─────────────────────────────────
+  '## Verification Protocol',
+  '<!-- soleri:verification-protocol -->',
+  '',
+  '**MANDATORY** when modifying existing code: prove before you fix.',
+  '',
+  '### The Rule',
+  '',
+  '1. **Find** — identify the issue in existing code',
+  '2. **Prove** — reproduce the issue (test case, error log, stack trace)',
+  '3. **Fix** — only after the issue is proven reproducible',
+  '',
+  '### Anti-pattern',
+  '',
+  '- 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',
+  '',
+  '### Scope',
+  '',
+  '- Applies ONLY to tasks that modify existing code',
+  '- Does NOT apply to new code, new files, or greenfield features',
+  '- Advisory only — flags warnings, never blocks execution',
+  '',
+
   `<!-- /${ENGINE_MARKER} -->`,
 ];