@soleri/forge 9.0.1 → 9.3.0

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>" }
 ```
 
@@ -68,13 +72,13 @@ If all vault strategies return nothing, search the web. If web finds something u
 
 ## Quick Reference
 
-| Op | When to Use |
-|----|-------------|
-| `search_intelligent` | Default semantic search |
-| `search` | Structured search with filters |
-| `vault_tags` / `vault_domains` | Browse knowledge landscape |
-| `vault_recent` | Recently modified entries |
-| `vault_age_report` | Stale entries |
-| `memory_cross_project_search` | Cross-project search |
-| `brain_strengths` / `brain_global_patterns` | Proven patterns |
-| `capture_quick` | Capture web findings |
+| Op                                          | When to Use                    |
+| ------------------------------------------- | ------------------------------ |
+| `search_intelligent`                        | Default semantic search        |
+| `search`                                    | Structured search with filters |
+| `vault_tags` / `vault_domains`              | Browse knowledge landscape     |
+| `vault_recent`                              | Recently modified entries      |
+| `vault_age_report`                          | Stale entries                  |
+| `memory_cross_project_search`               | Cross-project search           |
+| `brain_strengths` / `brain_global_patterns` | Proven patterns                |
+| `capture_quick`                             | Capture web findings           |

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

@@ -0,0 +1,259 @@
+---
+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,20 +35,20 @@ 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.
 
 ## Common Failures
 
-| Claim | Requires | Not Sufficient |
-|-------|----------|----------------|
-| Tests pass | Test output: 0 failures | Previous run, "should pass" |
-| Build succeeds | Build command: exit 0 | Linter passing |
-| Bug fixed | Original symptom passes | "Code changed, assumed fixed" |
-| Requirements met | Line-by-line checklist | Tests passing alone |
+| Claim            | Requires                | Not Sufficient                |
+| ---------------- | ----------------------- | ----------------------------- |
+| Tests pass       | Test output: 0 failures | Previous run, "should pass"   |
+| Build succeeds   | Build command: exit 0   | Linter passing                |
+| Bug fixed        | Original symptom passes | "Code changed, assumed fixed" |
+| Requirements met | Line-by-line checklist  | Tests passing alone           |
 
 ## Red Flags — STOP
 
@@ -54,16 +57,16 @@ If any check reports problems, address before claiming completion.
 - About to commit/push/PR without verification
 - Relying on partial verification
 
-| Excuse | Reality |
-|--------|---------|
-| "Should work now" | RUN the verification |
-| "I'm confident" | Confidence is not evidence |
-| "Just this once" | No exceptions |
-| "Partial check is enough" | Partial proves nothing |
+| Excuse                    | Reality                    |
+| ------------------------- | -------------------------- |
+| "Should work now"         | RUN the verification       |
+| "I'm confident"           | Confidence is not evidence |
+| "Just this once"          | No exceptions              |
+| "Partial check is enough" | Partial proves nothing     |
 
 ## 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
 
@@ -74,9 +77,9 @@ Capture session summary: `ernesto_core op:session_capture params: { summary: "<w
 
 ## Quick Reference
 
-| Op | When to Use |
-|----|-------------|
-| `admin_health` | Quick system health check |
-| `admin_diagnostic` | Comprehensive diagnostic |
-| `admin_vault_analytics` | Knowledge quality metrics |
-| `session_capture` | Persist verified completion context |
+| Op                      | When to Use                         |
+| ----------------------- | ----------------------------------- |
+| `admin_health`          | Quick system health check           |
+| `admin_diagnostic`      | Comprehensive diagnostic            |
+| `admin_vault_analytics` | Knowledge quality metrics           |
+| `session_capture`       | Persist verified completion context |

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.
@@ -94,12 +97,12 @@ Offer execution choice: subagent-driven (this session) or parallel session with
 
 ## Quick Reference
 
-| Op | When to Use |
-|----|-------------|
-| `search_intelligent` | Find patterns before planning |
-| `brain_strengths` | Proven approaches |
-| `create_plan` | Create tracked plan |
-| `plan_grade` / `plan_auto_improve` | Grade and improve |
-| `plan_iterate` | Iterate with feedback |
-| `plan_split` | Split into tasks |
-| `approve_plan` | Lock in approved plan |
+| Op                                 | When to Use                   |
+| ---------------------------------- | ----------------------------- |
+| `search_intelligent`               | Find patterns before planning |
+| `brain_strengths`                  | Proven approaches             |
+| `create_plan`                      | Create tracked plan           |
+| `plan_grade` / `plan_auto_improve` | Grade and improve             |
+| `plan_iterate`                     | Iterate with feedback         |
+| `plan_split`                       | Split into tasks              |
+| `approve_plan`                     | Lock in approved plan         |

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} -->`,
 ];