@jmylchreest/aide-plugin 0.0.38 → 0.0.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmylchreest/aide-plugin",
-  "version": "0.0.38",
+  "version": "0.0.40",
   "description": "aide plugin for OpenCode — multi-agent orchestration, memory, skills, and persistence",
   "type": "module",
   "main": "./src/opencode/index.ts",

package/skills/code-search/SKILL.md

@@ -60,7 +60,21 @@ What functions are in src/auth.ts?
 → Returns: all functions, classes, types in that file
 ```
 
-### 4. Check Index Status (`mcp__plugin_aide_aide__code_stats`)
+### 4. File Outline (`mcp__plugin_aide_aide__code_outline`)
+
+Get a collapsed structural outline of a file — signatures preserved, bodies replaced with `{ ... }`.
+Uses ~5-15% of the tokens of the full file. **Use this before reading a file** to understand its
+structure, then use `Read` with offset/limit for specific sections.
+
+**Example usage:**
+
+```
+Outline src/auth.ts
+→ Uses code_outline tool
+→ Returns: collapsed view with signatures, line ranges, bodies collapsed
+```
+
+### 5. Check Index Status (`mcp__plugin_aide_aide__code_stats`)
 
 Check if the codebase has been indexed.
 
@@ -72,6 +86,18 @@ Is the code indexed?
 → Returns: file count, symbol count, reference count
 ```
 
+### 6. Search Findings (`mcp__plugin_aide_aide__findings_search`)
+
+Search static analysis findings (complexity hotspots, secrets, code clones, coupling issues).
+
+**Example usage:**
+
+```
+Any complexity issues in src/auth?
+→ Uses findings_search tool with query "auth" or file filter
+→ Returns: findings with file, line, severity, description
+```
+
 ## Workflow
 
 1. **First, check if codebase is indexed:**
@@ -108,6 +134,20 @@ Is the code indexed?
 1. Use `code_references` with symbol "authenticateUser"
 2. Show all call sites grouped by file
 
+## What These Tools Cover
+
+`code_search` and `code_references` work from the tree-sitter symbol index. They find:
+
+- Function, method, class, interface, type definitions by name
+- Symbol signatures (parameter types, return types)
+- Doc comments attached to definitions
+- Call sites for a specific symbol name (via `code_references`)
+
+For anything else — patterns inside function bodies, method call chains, string literals,
+SQL queries, imports, variable declarations — use **Grep**, which searches code content directly.
+
+In short: `code_search` finds _where things are defined_; Grep finds _patterns in code content_.
+
 ## Notes
 
 - Code must be indexed first: `./.aide/bin/aide code index`

package/skills/debug/SKILL.md

@@ -18,6 +18,7 @@ Systematic approach to identifying and fixing bugs.
 ## Prerequisites
 
 Before starting:
+
 - Get the exact error message or unexpected behavior description
 - Identify the entry point or trigger for the bug
 - Note any relevant environment details (Node version, OS, etc.)
@@ -36,12 +37,14 @@ node path/to/script.js
 ```
 
 Document:
+
 - Exact error message
 - Steps to trigger
 - Expected vs actual behavior
 - Is it consistent or intermittent?
 
 **If cannot reproduce:**
+
 - Check environment differences
 - Look for race conditions
 - Check for cached state
@@ -54,6 +57,9 @@ Use tools to find code related to the error:
 # Search for function mentioned in stack trace
 mcp__plugin_aide_aide__code_search query="functionName" kind="function"
 
+# Get a structural overview of the suspect file (signatures + line ranges)
+mcp__plugin_aide_aide__code_outline file="path/to/file.ts"
+
 # Get symbols in suspect file
 mcp__plugin_aide_aide__code_symbols file="path/to/file.ts"
 
@@ -65,23 +71,26 @@ Grep for "error message text"
 
 Follow the code flow from entry to error:
 
-1. Start at the entry point (route handler, event listener, etc.)
-2. Trace through each function call
-3. Use `mcp__plugin_aide_aide__code_references` to find callers
-4. Check type definitions with `mcp__plugin_aide_aide__code_search kind="interface"`
+1. Use `code_outline` on each file in the call chain to understand its structure
+2. Use `code_references` to find callers of the failing function
+3. Use `Read` with offset/limit to read specific functions in the execution path
+   (use line numbers from the outline)
+4. Check type definitions with `code_search kind="interface"`
+
+Outlines help you identify which functions matter, so you can read just those sections.
 
 ### Step 4: Form Hypotheses
 
 Based on the error type, consider these causes:
 
-| Symptom | Likely Causes |
-|---------|---------------|
-| "undefined is not a function" | Variable is null/undefined, wrong import |
-| "Cannot read property of undefined" | Missing null check, async timing issue |
-| "Type error" | Type mismatch, wrong function signature |
-| "Maximum call stack" | Infinite recursion, circular reference |
-| "Network error" | Bad URL, CORS, timeout, server down |
-| "State not updating" | Mutation instead of new object, missing dependency |
+| Symptom                             | Likely Causes                                      |
+| ----------------------------------- | -------------------------------------------------- |
+| "undefined is not a function"       | Variable is null/undefined, wrong import           |
+| "Cannot read property of undefined" | Missing null check, async timing issue             |
+| "Type error"                        | Type mismatch, wrong function signature            |
+| "Maximum call stack"                | Infinite recursion, circular reference             |
+| "Network error"                     | Bad URL, CORS, timeout, server down                |
+| "State not updating"                | Mutation instead of new object, missing dependency |
 
 ### Step 5: Validate Hypotheses
 
@@ -99,6 +108,7 @@ npm test -- --grep "test name"
 ```
 
 **Validation checklist:**
+
 - Check variable values at key points
 - Verify assumptions about input data
 - Test edge cases (null, empty, boundary values)
@@ -107,11 +117,13 @@ npm test -- --grep "test name"
 ### Step 6: Apply the Fix
 
 **Rules:**
+
 - Change only what's necessary to fix the bug
 - Don't refactor unrelated code
 - Match existing code patterns
 
 **Common fixes:**
+
 - Add null/undefined check
 - Fix type annotation
 - Correct async/await usage
@@ -132,24 +144,26 @@ npm test
 ```
 
 **Verification criteria:**
+
 - Original issue no longer occurs
 - Related tests still pass
 - No new errors introduced
 
 ## Failure Handling
 
-| Situation | Action |
-|-----------|--------|
-| Cannot reproduce | Check environment, add logging to narrow down |
-| Multiple bugs intertwined | Fix one at a time, verify after each |
-| Fix causes new failures | Revert, analyze dependencies, try different approach |
-| Root cause is in dependency | Check for updates, file issue, implement workaround |
-| Bug is in async code | Add proper await, check Promise chains |
+| Situation                   | Action                                               |
+| --------------------------- | ---------------------------------------------------- |
+| Cannot reproduce            | Check environment, add logging to narrow down        |
+| Multiple bugs intertwined   | Fix one at a time, verify after each                 |
+| Fix causes new failures     | Revert, analyze dependencies, try different approach |
+| Root cause is in dependency | Check for updates, file issue, implement workaround  |
+| Bug is in async code        | Add proper await, check Promise chains               |
 
 ## MCP Tools
 
+- `mcp__plugin_aide_aide__code_outline` - **Start here.** Get collapsed file skeleton to understand structure before reading
 - `mcp__plugin_aide_aide__code_search` - Find functions, classes, types involved in the bug
-- `mcp__plugin_aide_aide__code_symbols` - Understand file structure
+- `mcp__plugin_aide_aide__code_symbols` - List all symbols in a file
 - `mcp__plugin_aide_aide__code_references` - Find all callers of a function
 - `mcp__plugin_aide_aide__memory_search` - Check for related past issues
 
@@ -159,24 +173,30 @@ npm test
 ## Debug Report: [Issue Title]
 
 ### Problem
+
 [What was happening vs what should happen]
 
 ### Reproduction
+
 [Steps to reproduce the issue]
 
 ### Root Cause
+
 [Identified cause with file:line reference]
 [Why the bug occurred]
 
 ### Fix Applied
+
 [What was changed and why]
 
 ### Verification
+
 - Original issue: FIXED
 - Related tests: PASS
 - Full suite: PASS
 
 ### Prevention
+
 [Optional: How to prevent similar bugs]
 ```
 

package/skills/forget/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: forget
+description: Soft-delete memories by adding/removing the forget tag, or hard-delete outdated memories
+triggers:
+  - forget this
+  - forget that
+  - forget memory
+  - remove memory
+  - delete memory
+  - outdated memory
+  - wrong memory
+  - incorrect memory
+  - supersede memory
+  - obsolete
+  - no longer true
+  - no longer relevant
+  - not true anymore
+  - that was wrong
+  - disregard
+allowed-tools: Bash(./.aide/bin/aide memory *)
+---
+
+# Forget
+
+**Recommended model tier:** balanced (sonnet) - this skill performs straightforward operations
+
+Manage outdated, incorrect, or obsolete memories by soft-deleting (tagging with `forget`) or hard-deleting them.
+
+## Key Concepts
+
+### Soft Delete (Preferred)
+
+Memories tagged with `forget` are **excluded by default** from search, list, and context injection. They remain in the database and can be recovered.
+
+```bash
+./.aide/bin/aide memory tag <MEMORY_ID> --add=forget
+```
+
+### Hard Delete (Permanent)
+
+Permanently removes a memory from the database. Use when the memory is clearly wrong or contains sensitive data.
+
+```bash
+./.aide/bin/aide memory delete <MEMORY_ID>
+```
+
+### Unforget (Recover)
+
+Remove the `forget` tag to restore a soft-deleted memory.
+
+```bash
+./.aide/bin/aide memory tag <MEMORY_ID> --remove=forget
+```
+
+## Workflow
+
+When the user wants to forget, correct, or supersede a memory:
+
+### Step 1: Find the Memory
+
+Search for the memory to identify its ID:
+
+```bash
+# Search by content keywords
+./.aide/bin/aide memory search "<keywords>" --full --limit=10
+
+# If the memory might already be forgotten, include all
+./.aide/bin/aide memory list --all
+```
+
+### Step 2: Confirm with User
+
+Before deleting or forgetting, show the user what was found and confirm which memories to act on. Display the memory ID, content, and tags.
+
+### Step 3: Apply the Appropriate Action
+
+Choose based on the situation:
+
+| Situation                            | Action                                  | Command                                |
+| ------------------------------------ | --------------------------------------- | -------------------------------------- |
+| Memory is outdated but was once true | Soft delete (forget)                    | `aide memory tag <ID> --add=forget`    |
+| Memory is factually wrong            | Hard delete                             | `aide memory delete <ID>`              |
+| Memory is resolved (issue fixed)     | Soft delete + optionally add resolution | See "Superseding" below                |
+| Memory contains sensitive data       | Hard delete                             | `aide memory delete <ID>`              |
+| Memory was accidentally forgotten    | Unforget                                | `aide memory tag <ID> --remove=forget` |
+
+### Step 4: Optionally Add a Replacement
+
+If the memory is being superseded (not just deleted), add a new corrected memory **without** the `forget` tag:
+
+```bash
+# 1. Forget the old memory
+./.aide/bin/aide memory tag <OLD_ID> --add=forget
+
+# 2. Add the corrected memory (NO forget tag)
+./.aide/bin/aide memory add --category=<category> --tags=<relevant,tags> "<corrected content>"
+```
+
+### Step 5: Verify
+
+Confirm the memory is no longer visible in normal searches:
+
+```bash
+# Should NOT appear in normal search
+./.aide/bin/aide memory search "<keywords>"
+
+# Should appear with --all flag
+./.aide/bin/aide memory list --all
+```
+
+## Anti-Patterns (AVOID)
+
+### DO NOT add a new memory with the forget tag to "supersede" an old one
+
+This is the most common mistake. Adding a new memory tagged `forget` does nothing useful:
+
+- The new "superseding" memory is immediately hidden (because it has the `forget` tag)
+- The original incorrect memory remains visible and active
+
+**Wrong:**
+
+```bash
+# BAD - creates a hidden memory, leaves the original untouched
+aide memory add --tags="forget,some-topic" "RESOLVED: the old issue is fixed"
+```
+
+**Correct:**
+
+```bash
+# GOOD - forget the original, add a visible replacement
+aide memory tag <ORIGINAL_ID> --add=forget
+aide memory add --tags="some-topic" "RESOLVED: the old issue is fixed"
+```
+
+### DO NOT guess memory IDs
+
+Always search first to find the exact memory ID. Memory IDs are ULIDs (e.g., `01KJ3X7GMQET613WMPT7JT8GYD`).
+
+### DO NOT forget memories without user confirmation
+
+Always show the user what will be affected and get confirmation before acting, especially for hard deletes.
+
+## Batch Operations
+
+To forget multiple related memories:
+
+```bash
+# Search for all related memories
+./.aide/bin/aide memory search "<topic>" --full --limit=50
+
+# Forget each one (after user confirmation)
+./.aide/bin/aide memory tag <ID1> --add=forget
+./.aide/bin/aide memory tag <ID2> --add=forget
+```
+
+To clear ALL memories (destructive, requires explicit user request):
+
+```bash
+./.aide/bin/aide memory clear
+```
+
+## Examples
+
+### User says "that thing about ESM imports is wrong"
+
+```bash
+# 1. Find the memory
+./.aide/bin/aide memory search "ESM imports" --full
+
+# 2. Show user and confirm
+# "Found memory 01KJ... about ESM imports requiring .js extensions. Delete this?"
+
+# 3. Soft delete
+./.aide/bin/aide memory tag 01KJ3XVFXBFTKKH1M500N6R5 --add=forget
+```
+
+### User says "we changed from JWT to sessions, update the memory"
+
+```bash
+# 1. Find the old memory
+./.aide/bin/aide memory search "JWT auth" --full
+
+# 2. Forget the old one
+./.aide/bin/aide memory tag <OLD_ID> --add=forget
+
+# 3. Add the corrected one
+./.aide/bin/aide memory add --category=decision --tags=auth,sessions,project:myapp "Auth strategy changed from JWT to server-side sessions with Redis store"
+```
+
+### User says "recover that forgotten memory about testing"
+
+```bash
+# 1. Find forgotten memories
+./.aide/bin/aide memory list --all
+
+# 2. Unforget it
+./.aide/bin/aide memory tag <ID> --remove=forget
+```
+
+## Failure Handling
+
+If `aide memory tag` fails:
+
+1. **"memory not found"** - The ID may be wrong. Re-search with `--all` flag to include forgotten memories.
+2. **Panic/crash** - If the tag command panics, fall back to delete + re-add:
+   ```bash
+   # Workaround: get memory content, delete, re-add with forget tag
+   ./.aide/bin/aide memory list --all  # Find the memory content
+   ./.aide/bin/aide memory delete <ID>
+   ./.aide/bin/aide memory add --category=<cat> --tags=<existing-tags>,forget "<content>"
+   ```
+3. **Database locked** - Another process may hold the lock. Wait and retry, or ensure the aide daemon is running (CLI routes through gRPC when daemon is active).
+
+## Verification
+
+After forgetting a memory, verify:
+
+```bash
+# Memory should NOT appear here
+./.aide/bin/aide memory search "<term>"
+
+# Memory SHOULD appear here (with forget tag)
+./.aide/bin/aide memory list --all
+```

package/skills/git/SKILL.md

@@ -156,6 +156,16 @@ git worktree list | grep <worktree-path>
 git branch -a | grep <branch-name>
 ```
 
+## Change Context with Findings
+
+When reviewing diffs or preparing commits, use findings tools to understand the quality context of changed code:
+
+- `mcp__plugin_aide_aide__findings_search` — Search for known issues (complexity, secrets, clones) in changed files
+- `mcp__plugin_aide_aide__findings_list` — List all findings for a specific file to understand its health
+- `mcp__plugin_aide_aide__findings_stats` — Quick overview of finding counts across the project
+
+This helps surface pre-existing issues in files you're touching, and can inform whether a commit should also address nearby problems.
+
 ## Parallel Work Pattern
 
 For swarm mode or parallel features:

package/skills/implement/SKILL.md

@@ -51,10 +51,19 @@ Understand what the tests expect:
 - What edge cases are covered?
 
 ```bash
-# Read the test file
+# For large test files, get the structure first
+mcp__plugin_aide_aide__code_outline file="path/to/feature.test.ts"
+
+# Then read specific test sections with offset/limit
+Read path/to/feature.test.ts offset=<start> limit=<count>
+
+# For small test files (<100 lines), reading the full file is fine
 Read path/to/feature.test.ts
 ```
 
+When implementing, use `code_outline` on adjacent/related source files to understand
+their structure before reading them fully. This preserves context for the implementation work.
+
 ### Step 3: Check Design Decisions
 
 Use `mcp__plugin_aide_aide__decision_get` with the feature topic to review decisions from DESIGN stage.

package/skills/memorise/SKILL.md

@@ -52,25 +52,31 @@ Use the `./.aide/bin/aide memory add` CLI command via Bash:
 ### Simple preference (global - injected at session start)
 
 ```bash
-./.aide/bin/aide memory add --category=learning --tags=preferences,colour,scope:global "User's favourite colour is blue"
+./.aide/bin/aide memory add --category=learning --tags=preferences,colour,scope:global,source:user "User's favourite colour is blue"
 ```
 
-### Technical learning (project-specific)
+### Technical learning (project-specific, verified)
 
 ```bash
-./.aide/bin/aide memory add --category=learning --tags=testing,vitest,project:myapp,session:abc12345 "Vitest requires .js extensions for ESM imports even for .ts files. Configure moduleResolution: NodeNext in tsconfig."
+./.aide/bin/aide memory add --category=learning --tags=testing,vitest,project:myapp,session:abc12345,source:discovered,verified:true "Vitest requires .js extensions for ESM imports even for .ts files. Configure moduleResolution: NodeNext in tsconfig."
 ```
 
 ### Session summary
 
 ```bash
-./.aide/bin/aide memory add --category=session --tags=auth,api,project:myapp,session:abc12345 "Implemented JWT auth with 15min access tokens, 7day refresh tokens in httpOnly cookies. Files: src/auth/jwt.ts, src/middleware/auth.ts, src/routes/auth.ts"
+./.aide/bin/aide memory add --category=session --tags=auth,api,project:myapp,session:abc12345,source:discovered "Implemented JWT auth with 15min access tokens, 7day refresh tokens in httpOnly cookies. Files: src/auth/jwt.ts, src/middleware/auth.ts, src/routes/auth.ts"
 ```
 
 ### Gotcha (global - applies everywhere)
 
 ```bash
-./.aide/bin/aide memory add --category=gotcha --tags=hooks,claude-code,scope:global "Hooks must not write to stderr - Claude Code interprets any stderr as error. Debug logging must go to files only."
+./.aide/bin/aide memory add --category=gotcha --tags=hooks,claude-code,scope:global,source:discovered,verified:true "Hooks must not write to stderr - Claude Code interprets any stderr as error. Debug logging must go to files only."
+```
+
+### Unverified external claim
+
+```bash
+./.aide/bin/aide memory add --category=learning --tags=api,stripe,project:myapp,source:user,verified:false "Stripe webhook signatures use HMAC-SHA256 with the whsec_ prefix."
 ```
 
 ## Instructions
@@ -78,18 +84,90 @@ Use the `./.aide/bin/aide memory add` CLI command via Bash:
 When the user invokes `/aide:memorise <something>`:
 
 1. Parse what they want to remember
-2. Determine the scope:
+2. **Verify factual claims before storing** (see [Verification Before Storage](#verification-before-storage-anti-poison) below)
+3. Determine the scope:
    - **User preference** (colour, style, etc.) → add `scope:global`
    - **Project-specific learning** → add `project:<project-name>,session:${CLAUDE_SESSION_ID:0:8}`
    - **Session summary** → add `project:<project-name>,session:${CLAUDE_SESSION_ID:0:8}`
-3. Choose appropriate category and descriptive tags
-4. Format the content concisely but completely
-5. Call `./.aide/bin/aide memory add` via Bash to store it
-6. **Verify success** - check exit code is 0 and output contains the memory ID
-7. Confirm what was stored
+4. Choose appropriate category and descriptive tags
+5. **Add provenance tags** (see [Provenance Tags](#provenance-tags) below)
+6. Format the content concisely but completely
+7. Call `./.aide/bin/aide memory add` via Bash to store it
+8. **Verify success** - check exit code is 0 and output contains the memory ID
+9. Confirm what was stored, including verification outcome
 
 Keep content concise - aim for 1-3 sentences unless it's a complex session summary.
 
+## Verification Before Storage (Anti-Poison)
+
+Memories persist across sessions and influence future behaviour. Storing incorrect information is **worse than storing nothing** — it creates compounding errors. Before storing any memory, verify its claims.
+
+### What to Verify
+
+| Claim Type                | Verification Method                                   | Example                                        |
+| ------------------------- | ----------------------------------------------------- | ---------------------------------------------- |
+| **File exists**           | Use Glob or Read to confirm                           | "Config is in src/config.ts"                   |
+| **Function/class exists** | Use Grep or code search                               | "Use `parseToken()` from auth.ts"              |
+| **Function signature**    | Read the file, check the actual signature             | "parseToken takes a string and returns Claims" |
+| **API behaviour**         | Check the implementation or tests                     | "The /users endpoint requires auth"            |
+| **Dependency/version**    | Check package.json, go.mod, etc.                      | "Project uses Vitest v2"                       |
+| **Build/test command**    | Confirm the script exists in package.json or Makefile | "Run `npm run test:e2e` for integration tests" |
+
+### What Does NOT Need Verification
+
+- **User preferences** — The user is the authority ("I prefer tabs over spaces")
+- **Session summaries** — Recap of what just happened in the current session
+- **Opinions/decisions** — Architectural choices made by the user ("We chose Postgres")
+- **External facts** — Things not checkable against the codebase ("React 19 uses...")
+
+### Verification Workflow
+
+```
+Is it a codebase claim (file, function, path, command, behaviour)?
+├── No → Store directly with source:user or source:stated
+└── Yes → Can you verify it right now?
+          ├── Yes → Verify it
+          │         ├── Correct → Store with verified:true
+          │         └── Wrong → Inform user, do NOT store. Offer corrected version.
+          └── No (e.g., external service, runtime behaviour)
+                    → Store with verified:false, note unverified
+```
+
+### Verification Rules
+
+1. **NEVER store a codebase claim without checking** — If the user says "the auth middleware is in src/middleware/auth.ts", confirm the file exists before memorising.
+2. **If verification fails, do NOT store** — Tell the user what you found instead and offer to store the corrected version.
+3. **If you cannot verify** (e.g., claim about runtime behaviour, external API), store it but tag with `verified:false`.
+4. **Err on the side of not storing** — A missing memory is recoverable; a wrong memory causes future errors.
+
+### Example: Verified vs Rejected
+
+**User says:** "Remember that the database schema is defined in db/schema.sql"
+
+**Verification steps:**
+
+1. Check: does `db/schema.sql` exist? → Use Glob to search
+2. If yes → Store with `verified:true`
+3. If no → "I checked and `db/schema.sql` doesn't exist. I found `database/migrations/` instead. Would you like me to store that instead?"
+
+## Provenance Tags
+
+Always include provenance tags to track the origin and verification status of memories:
+
+| Tag                 | Meaning                                  | When to Use                                      |
+| ------------------- | ---------------------------------------- | ------------------------------------------------ |
+| `source:user`       | User explicitly stated this              | User preferences, direct instructions            |
+| `source:discovered` | Agent discovered this by examining code  | File paths, function signatures, patterns found  |
+| `source:inferred`   | Agent inferred this from context         | Behaviour deduced from code, not directly stated |
+| `verified:true`     | Codebase claim was checked and confirmed | After successful verification                    |
+| `verified:false`    | Claim could not be verified against code | External facts, runtime behaviour                |
+
+### Provenance Rules
+
+- Every memory MUST have exactly one `source:` tag
+- Codebase claims MUST have a `verified:` tag
+- User preferences and opinions do NOT need `verified:` tags (user is authoritative)
+
 ## Failure Handling
 
 If `./.aide/bin/aide memory add` fails: