autodev-cli 1.4.97 → 1.4.101

package/media/profile/17-issue-tracking.md

@@ -1,19 +1,14 @@
 ## 0.7 Issue Tracking — `.autodev/issues/ISSUE-NNN-kebab-title.md`
 
-**Each issue gets its own living document.** Create before any work. It is the single record from description through decisions, work log, artifacts, and resolution — readable alone, no external lookups needed.
-
-**Create when:** Jira/GitHub issue assigned · email with issue number · multi-session problem needs stable reference.
-
-**Naming:** `ISSUE-{NUMBER}-{kebab-case-title}.md` (use `0` if no external number). Example: `ISSUE-123-user-login-timeout.md`.
-
-**Sections:** Status · Created/Updated · Owner · Link · User Story & Goal · Acceptance Criteria · Related Issues · Technical Approach (prepend, never overwrite) · Work Log (append-only) · Artifacts · Resolution.
-*(Full skeleton: skill `issue-tracking-reference`)*
+Each issue is its own living document, created **before any work**; a self-contained record from description → decisions → work log → artifacts → resolution.
+**Create when:** an issue is assigned (Jira/GitHub) · an email carries an issue number · a multi-session problem needs a stable reference. **Name:** `ISSUE-{NUMBER}-{kebab-title}.md` (`0` if no external number).
+**Sections:** Status · Created/Updated · Owner · Link · User Story & Goal · Acceptance Criteria · Related Issues · Technical Approach · Work Log · Artifacts · Resolution.
 
 **Update rules:**
-- Starting work → `Status: In Progress` + Work Log entry.
-- New finding → prepend to Technical Approach; never overwrite.
-- Artifact produced → add to Artifacts immediately (screenshots, logs, diffs, test output).
-- Blocker → `Status: Blocked` + email relevant agent per `CONTRACTS.md`.
-- Resolved → fill Resolution + `Status: Resolved` + attach verification artifacts.
+- Start work → `Status: In Progress` + Work Log entry.
+- New finding → prepend to Technical Approach (never overwrite).
+- Artifact produced → add to Artifacts immediately.
+- Blocker → `Status: Blocked` + email the relevant agent per `CONTRACTS.md`.
+- Resolved → fill Resolution + `Status: Resolved` + attach 1+ verification artifact.
 
-**Rules:** Create before working · Append-only log and artifacts · One file per issue (cross-reference, never merge) · Self-contained · Every resolved issue needs 1+ artifact · Cross-references bidirectional · Never delete.
+Append-only log/artifacts · one file per issue (cross-reference bidirectionally, never merge or delete). Full skeleton: skill `issue-tracking-reference`.

package/media/profile/18-knowledgebase.md

@@ -1,13 +1,10 @@
 ## 0.8 Knowledge Base — `.autodev/knowledgebase/KB-NNN-kebab-title.md`
 
-**Evergreen reference material** — architectural decisions, domain rules, patterns, integration quirks, gotchas. Outlive any individual task. Written when insight is confirmed, never when "there's time later."
+Evergreen reference (architectural decisions, domain rules, patterns, integration quirks, gotchas) that outlives any task — written the moment an insight is confirmed, not "later".
+**Create when:** an architectural decision is made · a pattern applies in 2+ places · an integration quirk is confirmed · a recurring question is definitively answered · a JOURNAL `keep` yields a transferable insight · a TROUBLESHOOTING entry generalises to a class of problem.
+**Name:** `KB-{NUMBER}-{kebab-title}.md` (sequential; `0` for local).
+**Sections:** Status · Created/Updated · Summary (≤3 sentences) · Context · Detail · Examples · Caveats · References · Change History.
 
-**Create when:** Architectural decision made · pattern applies in 2+ places · integration quirk confirmed · recurring question definitively answered · JOURNAL.md `keep` produces transferable insight · TROUBLESHOOTING.md entry generalises to class of problem.
+**Rules:** update Detail in place + append Change History as knowledge evolves; superseded → `Status: Deprecated` + `Superseded by:` link; cross-reference bidirectionally with issues; one concept per entry; self-contained; never delete.
 
-**Naming:** `KB-{NUMBER}-{kebab-case-title}.md` Sequential number (check existing). Use `0` for local. Example: `KB-001-auth-token-refresh-flow.md`
-
-**Sections:** Status · Created/Updated · Summary (≤3 sentences) · Context · Detail · Examples · Caveats · References · Change History (append-only).
-
-**Rules:** Update Detail in place + append Change History when knowledge evolves. Superseded entry → `Status: Deprecated` + `Superseded by:` link. Cross-ref bidirectionally with issues. Never delete. One concept per entry. Self-contained.
-
-**Complete skeleton, all sections, update rules:** skill `kb-reference`
+Full skeleton + update rules: skill `kb-reference`.

package/media/profile/19-subagent-context-management.md

@@ -5,506 +5,21 @@ description: "When and how to spawn subagents; how to maintain context during de
 
 # Subagent Context Management
 
-## Critical Principle: You Own Context
+**Full decision tree, CONTEXT.md template, and briefing template: skill `subagent-context`.**
 
-**YOU (the Orchestrator) manage your own context.** Subagents are NOT for:
-- Compacting your context (they compact theirs, not yours = infinite loop)
-- Figuring out what to do next (you decide, then hand off)
-- Running commands (tests, lints, builds)
-- Reading files or parsing output
+**You own your context.** Subagents are NOT for compacting your context (they compact their own empty context — infinite loop), deciding what to do next, running commands (tests/lints/builds), or reading/parsing files. Those are all YOU.
 
-**Subagents ARE for:**
-- Scoped implementation work with clean context
-- Complex creative tasks that benefit from fresh context
-- Parallel specialist work (Code, QA, Reviewer)
+**Subagents ARE for:** scoped implementation (Code), writing new tests (QA), diff review (Reviewer), architectural design (Architect), or a context handoff when your own context is unwieldy AND you have already made the decisions.
 
----
-
-## When to Spawn a Subagent: Decision Tree
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ IS THE TASK...                                              │
-└─────────────────────────────────────────────────────────────┘
-          │
-          ▼
-     ┌────────────────────────────────────┐
-     │ A shell command that returns text? │  → YES → YOU RUN IT (no subagent)
-     └────────────────────────────────────┘
-          │ NO
-          ▼
-     ┌────────────────────────────────────┐
-     │ Reading/parsing files or output?   │  → YES → YOU DO IT (no subagent)
-     └────────────────────────────────────┘
-          │ NO
-          ▼
-     ┌────────────────────────────────────┐
-     │ A judgment call or decision?       │  → YES → YOU DECIDE (no subagent)
-     └────────────────────────────────────┘
-          │ NO
-          ▼
-     ┌────────────────────────────────────┐
-     │ "Manage my context" or "compact"?  │  → YES → YOU HANDLE (never subagent!)
-     └────────────────────────────────────┘
-          │ NO
-          ▼
-     ┌────────────────────────────────────┐
-     │ Implementation (editing files)?    │  → YES → Spawn Code Agent
-     └────────────────────────────────────┘
-          │ NO
-          ▼
-     ┌────────────────────────────────────┐
-     │ Writing new test files?            │  → YES → Spawn QA Agent
-     └────────────────────────────────────┘
-          │ NO
-          ▼
-     ┌────────────────────────────────────┐
-     │ Reviewing code/diff?               │  → YES → Spawn Reviewer Agent
-     └────────────────────────────────────┘
-          │ NO
-          ▼
-     ┌────────────────────────────────────┐
-     │ Architectural design?              │  → YES → Spawn Architect Agent
-     └────────────────────────────────────┘
-          │ NO
-          ▼
-     ┌──────────────────────────────────────────────────────────┐
-     │ Deep multi-step implementation requiring fresh context?  │
-     │ (your context is unwieldy/circular)                      │  → YES → See "Context Handoff" below
-     └──────────────────────────────────────────────────────────┘
-          │ NO
-          ▼
-     [YOU DO IT DIRECTLY]
-```
-
----
-
-## Context Handoff: When Your Context Is Unwieldy
-
-### Signs You Need a Context Handoff
-
-- ✅ You've been working on the same task for 20+ exchanges
-- ✅ You're going in circles (repeating same analysis)
-- ✅ Your context is full of irrelevant exploration from earlier
-- ✅ You need to implement a complex multi-file change
-- ✅ You've made the key decisions and need clean context to execute
-
-### Signs You DON'T Need a Context Handoff
-
-- ❌ You just need to run a test (`npm test` → run it yourself)
-- ❌ You need to decide what to do next (you decide, don't delegate)
-- ❌ You want to "compact" your context (manage it yourself)
-- ❌ The task is 1-3 simple file edits (do it yourself or use Code Agent)
-- ❌ You haven't decided on the approach yet (decide first, then hand off)
-
-### How to Do a Context Handoff
-
-**BEFORE spawning subagent:**
-
-1. **Update CONTEXT.md** (see template below) with:
-   - Main task goal
-   - Key decisions made
-   - Files/modules involved
-   - Current status
-   - What remains
-
-2. **Decide the EXACT next action** — never hand off "figure out what to do"
-
-3. **Write a detailed subagent brief** (see "Briefing Template" below)
-
-4. **Spawn subagent with scoped task** — not "do everything" but "implement X using Y"
-
-**AFTER subagent returns:**
-
-1. **Update CONTEXT.md** with what was completed
-2. **Verify the result yourself** (run tests, check diffs)
-3. **Continue to next step** or mark task [x]
-
----
-
-## CONTEXT.md Template
-
-Create `CONTEXT.md` in your workspace root when starting complex multi-step tasks:
-
-```markdown
-# CONTEXT.md — Main Task Tracking
-
-> **Purpose:** Keep track of the main task goal and prevent getting lost in deep subtasks.
-> **Update:** After every major decision, subagent spawn, or context shift.
-
----
-
-## Main Task
-
-**Goal:** [One-sentence description of the main task]
-
-**Status:** [Not Started / In Progress / Blocked / Completed]
-
-**TODO.md Task Line:** 
-```
-- [~] feat: implement user authentication system
-```
-
----
-
-## Key Decisions Made
-
-1. **[Date/Time]** Decision: [What was decided]
-   - Reasoning: [Why this choice]
-   - Alternative considered: [What was rejected and why]
-
-2. **[Date/Time]** Decision: ...
-
----
-
-## Architecture/Approach
-
-[High-level description of the chosen approach]
-
-**Files/Modules Involved:**
-- `src/auth/login.ts` — handles login flow
-- `src/auth/session.ts` — manages session state
-- `src/api/auth-routes.ts` — API endpoints
-
-**Key Patterns/Conventions:**
-- Using JWT for tokens
-- Sessions stored in Redis
-- Following existing error handling pattern from `src/errors/`
-
----
-
-## Progress Tracker
-
-### Completed
-- [x] 2026-05-25  Researched existing auth patterns in codebase
-- [x] 2026-05-25  Decided on JWT + Redis approach
-- [x] 2026-05-25  Spawned Code Agent to implement login.ts
-
-### In Progress
-- [~] Verify login.ts implementation
-- [~] Run integration tests
-
-### Remaining
-- [ ] Implement session.ts
-- [ ] Implement auth-routes.ts
-- [ ] Add integration tests
-- [ ] Update documentation
-
----
-
-## Subagent Spawns
-
-### Spawn 1: Code Agent — Implement login.ts
-**When:** 2026-05-25 14:30
-**Brief:** [See full brief below]
-**Result:** Implemented login.ts with JWT generation
-**Verified:** ✅ Tests pass, linter clean
-
-### Spawn 2: QA Agent — Write integration tests
-**When:** 2026-05-25 15:00
-**Brief:** [See full brief below]
-**Result:** [Pending]
-**Verified:** [Pending]
-
----
-
-## Blockers / Issues
-
-- **[Date]** Blocker: [Description]
-  - Status: [Open / Resolved]
-  - Resolution: [How it was resolved]
-
----
-
-## Context Checkpoints
-
-Use these checkpoints to verify you're still on track:
-
-1. **Can you state the main goal in one sentence?** [Yes/No - if no, re-read above]
-2. **Do you know the next concrete action?** [Yes/No - if no, review Progress Tracker]
-3. **Have you strayed into unrelated work?** [Yes/No - if yes, refocus on main goal]
-4. **Is there a clearer path than current approach?** [Yes/No - if yes, update Decisions]
-
----
-
-## Notes / Learnings
-
-[Add any important discoveries, gotchas, or learnings that should be remembered]
-
-```
-
----
-
-## Subagent Briefing Template
-
-When spawning a subagent for a complex task, use this template:
-
-```markdown
-# Subagent Brief: [Agent Type] — [Task Summary]
-
-## MISSION (one sentence)
-[Exactly what this subagent must accomplish]
-
-## CONTEXT
-[Only the relevant context — not your entire history]
-
-**Main Task:** [Link back to the overall goal]
-
-**Decisions Already Made:**
-- [Key decision 1]
-- [Key decision 2]
-
-**Files/Modules Relevant to This Subtask:**
-- `path/to/file.ts` — [why relevant]
-- `path/to/test.ts` — [why relevant]
-
-## WHAT TO IMPLEMENT
-
-**Goal:** [Specific implementation goal]
-
-**Approach:** [The exact approach to use — no ambiguity]
-- Step 1: [Concrete action]
-- Step 2: [Concrete action]
-- Step 3: [Concrete action]
-
-**Files to Edit:**
-1. `path/to/file1.ts`
-   - Add: [specific functionality]
-   - Modify: [specific section]
-   - Use pattern: [reference to existing pattern]
-
-2. `path/to/file2.ts`
-   - Add: [specific functionality]
-   
-**Patterns to Follow:**
-- Error handling: Use `src/errors/AppError.ts` pattern
-- Testing: Follow `__tests__/example.test.ts` structure
-- Imports: Use absolute paths from `src/`
-
-**DO:**
-- Follow existing code style in the files
-- Add JSDoc comments for public functions
-- Write type-safe TypeScript (no `any`)
-- Handle errors explicitly
-
-**DON'T:**
-- Change unrelated code
-- Add libraries without checking existing stack
-- Skip edge case handling
-- Leave TODOs in production code
-
-## DONE CRITERIA
-
-This subtask is complete when:
-1. [Specific criterion 1]
-2. [Specific criterion 2]
-3. [Specific criterion 3]
-4. All edits are syntactically valid (no compilation errors)
-
-## AFTER YOU'RE DONE
-
-Return:
-1. **Files changed:** List of file paths
-2. **Summary:** What was implemented (2-3 sentences)
-3. **Any issues:** Blockers, ambiguities, or decisions made
-
-DO NOT:
-- Run tests (orchestrator does this)
-- Run linters (orchestrator does this)
-- Verify the full feature (orchestrator does this)
-- Update TODO.md (orchestrator does this)
-```
-
----
-
-## Anti-Patterns: NEVER Do These
-
-### ❌ WRONG: Spawning subagent to compact context
-
-```
-❌ "My context is full. Let me spawn a subagent to continue."
-```
-
-**Why wrong:** The subagent starts with EMPTY context. It will compact its own empty context, not yours. Infinite loop.
-
-**✅ RIGHT:** YOU decide what to keep. Update CONTEXT.md. Summarize decisions. THEN spawn subagent with scoped task.
-
----
-
-### ❌ WRONG: Spawning subagent to decide next step
-
-```
-❌ "I'm not sure what to do next. Let me spawn a subagent to figure it out."
-```
-
-**Why wrong:** YOU are the orchestrator. YOU make decisions. Subagents execute scoped tasks.
-
-**✅ RIGHT:** Re-read CONTEXT.md. Review Progress Tracker. Decide next action. THEN spawn subagent with specific task.
-
----
-
-### ❌ WRONG: Spawning subagent to run tests
-
-```
-❌ "Let me spawn a subagent to run `npm test` and tell me the results."
-```
-
-**Why wrong:** Running tests is a deterministic shell command. You run it directly.
-
-**✅ RIGHT:** Run `npm test` yourself. Analyze output yourself. Decide on fix. THEN spawn Code Agent to implement fix.
-
----
-
-### ❌ WRONG: Vague subagent brief
-
-```
-❌ "Implement the authentication feature. Figure out the best approach."
-```
-
-**Why wrong:** Subagent doesn't have your context. It will re-explore everything you already researched. Wastes tokens and time.
-
-**✅ RIGHT:** 
-- YOU decide the approach (JWT + Redis)
-- YOU identify files to edit (`login.ts`, `session.ts`)
-- YOU specify the pattern to follow (existing error handling)
-- THEN spawn subagent with detailed brief (see template above)
-
----
-
-## Workflow: Managing Context in Complex Tasks
-
-```
-┌────────────────────────────────────────────────────────────────┐
-│ START: Complex multi-step task                                 │
-└────────────────────────────────────────────────────────────────┘
-           │
-           ▼
-┌────────────────────────────────────────────────────────────────┐
-│ 1. CREATE CONTEXT.md                                           │
-│    - Write main goal                                           │
-│    - Set up Progress Tracker                                   │
-└────────────────────────────────────────────────────────────────┘
-           │
-           ▼
-┌────────────────────────────────────────────────────────────────┐
-│ 2. RESEARCH & DECIDE                                           │
-│    - Read relevant files                                       │
-│    - Explore codebase                                          │
-│    - Make key decisions                                        │
-│    - UPDATE CONTEXT.md with decisions                          │
-└────────────────────────────────────────────────────────────────┘
-           │
-           ▼
-┌────────────────────────────────────────────────────────────────┐
-│ 3. BREAK DOWN INTO SUBTASKS                                    │
-│    - Write subtasks in TODO.md                                 │
-│    - Update CONTEXT.md Progress Tracker                        │
-└────────────────────────────────────────────────────────────────┘
-           │
-           ▼
-┌────────────────────────────────────────────────────────────────┐
-│ 4. FOR EACH SUBTASK:                                           │
-│    ┌─────────────────────────────────────────────────────┐    │
-│    │ 4a. Check: Can I do this directly? (1-3 file edits) │    │
-│    │     → YES: Do it yourself                            │    │
-│    │     → NO: Continue to 4b                             │    │
-│    └─────────────────────────────────────────────────────┘    │
-│    ┌─────────────────────────────────────────────────────┐    │
-│    │ 4b. Write detailed subagent brief (use template)    │    │
-│    └─────────────────────────────────────────────────────┘    │
-│    ┌─────────────────────────────────────────────────────┐    │
-│    │ 4c. Spawn subagent with scoped task                 │    │
-│    └─────────────────────────────────────────────────────┘    │
-│    ┌─────────────────────────────────────────────────────┐    │
-│    │ 4d. UPDATE CONTEXT.md with spawn details           │    │
-│    └─────────────────────────────────────────────────────┘    │
-│    ┌─────────────────────────────────────────────────────┐    │
-│    │ 4e. Receive result from subagent                    │    │
-│    └─────────────────────────────────────────────────────┘    │
-│    ┌─────────────────────────────────────────────────────┐    │
-│    │ 4f. YOU verify (tests, lint, build)                 │    │
-│    └─────────────────────────────────────────────────────┘    │
-│    ┌─────────────────────────────────────────────────────┐    │
-│    │ 4g. UPDATE CONTEXT.md Progress Tracker              │    │
-│    └─────────────────────────────────────────────────────┘    │
-└────────────────────────────────────────────────────────────────┘
-           │
-           ▼
-┌────────────────────────────────────────────────────────────────┐
-│ 5. CHECKPOINT: Review CONTEXT.md                               │
-│    - Am I still on track for main goal?                        │
-│    - Have I strayed into unrelated work?                       │
-│    - Is the approach still valid?                              │
-└────────────────────────────────────────────────────────────────┘
-           │
-           ▼
-┌────────────────────────────────────────────────────────────────┐
-│ 6. COMPLETE: All subtasks done                                 │
-│    - Mark main task [x]                                        │
-│    - Archive CONTEXT.md → DONE_CONTEXT_YYYY-MM-DD.md          │
-│    - Commit                                                    │
-└────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Quick Reference: Subagent Dispatch Rules
-
-| Task Type | Who Does It | Notes |
-|-----------|-------------|-------|
-| Run `npm test` | **YOU** | Never spawn subagent for shell commands |
-| Run `eslint` | **YOU** | Never spawn subagent for linters |
-| Run `npm run build` | **YOU** | Never spawn subagent for builds |
-| Read files | **YOU** | Never spawn subagent to read/parse |
-| Grep/search codebase | **YOU** | Use grep_search/semantic_search directly |
-| Analyze test output | **YOU** | Never spawn subagent to interpret output |
-| Decide what to do next | **YOU** | Never spawn subagent to make decisions |
-| Manage context | **YOU** | Never spawn subagent to compact YOUR context |
-| Edit 1-3 files (simple) | **YOU** | Direct edits faster than subagent |
-| Edit 5+ files (complex) | **Code Agent** | Spawn with detailed brief |
-| Multi-file refactor | **Code Agent** | One file at a time, or spawn with full context |
-| Write new test files | **QA Agent** | Spawn with spec and patterns to follow |
-| Review code/diff | **Reviewer Agent** | Spawn after changes complete |
-| Architectural design | **Architect Agent** | Spawn with requirements and constraints |
-| Context handoff | **Code Agent** | When YOUR context unwieldy + decisions made |
-
----
-
-## Success Metrics
-
-You're using subagents correctly when:
-
-✅ Subagents receive detailed, specific briefs (not "figure it out")  
-✅ You update CONTEXT.md before and after subagent spawns  
-✅ You never spawn subagents to run commands or read files  
-✅ You verify all subagent work yourself (tests, lint, diff review)  
-✅ You stay on track with the main goal (no context drift)  
-✅ Subagents work on scoped tasks with clean context  
-✅ You make all decisions; subagents execute decisions  
-
-You're doing it WRONG when:
-
-❌ Spawning subagent to "compact my context"  
-❌ Spawning subagent to "figure out what to do"  
-❌ Spawning subagent to run tests or linters  
-❌ Giving vague briefs like "implement feature X"  
-❌ Losing track of main goal after deep subtasks  
-❌ Forgetting to update CONTEXT.md  
-❌ Repeating research that you already did  
-
----
-
-## Integration with Core Loop
-
-This skill integrates with the **autodev-core-loop** skill:
+**Before spawning any subagent:**
+1. Decide the EXACT next action yourself — never hand off "figure out what to do".
+2. Write a detailed brief: MISSION (one sentence) · CONTEXT (only what's relevant: main goal, decisions already made, relevant files + why) · WHAT TO IMPLEMENT (exact approach, files to edit, patterns to follow, DO/DON'T) · DONE CRITERIA.
+3. Tell the subagent NOT to run tests/lints/builds or update `TODO.md` — the Orchestrator does that.
 
-- **Before Step 4 (THINK & PLAN):** Check if this is a context-heavy task → create CONTEXT.md
-- **During Step 4 (THINK & PLAN):** Make decisions, update CONTEXT.md
-- **During Step 5 (DISPATCH):** Use briefing template for complex tasks
-- **After Step 6 (RECEIVE):** Update CONTEXT.md with result
-- **During Step 7 (VERIFY):** Reference CONTEXT.md to ensure main goal still on track
-- **After Step 8 (RE-READ TODO.md):** Check CONTEXT.md before picking next task
+**After it returns:** YOU verify (tests, lint, diff review) and update state.
 
-**Never let subagent management override the core loop. The loop is primary.**
+**Context handoff** — spawn only when: 20+ exchanges on one task · going in circles · context full of stale exploration · a complex multi-file change with decisions already made. NOT for: running a test, deciding the next step, "compacting", or 1–3 simple edits (do those yourself).
 
+**CONTEXT.md** — for complex multi-step tasks create `CONTEXT.md` (main goal · key decisions · files/approach · progress tracker · subagent spawns · blockers) to avoid losing the main goal during deep work. Update it before/after every spawn; checkpoint against it (can I state the goal in one sentence? do I know the next action? have I strayed?). Archive to `DONE_CONTEXT_YYYY-MM-DD.md` when done.
 
+Integrates with skill `autodev-core-loop` — the loop stays primary; never let subagent management override it.

package/media/profile/20-project-graph.md

@@ -1,56 +1,30 @@
 ## 0.20 Project Graph — Durable Shared Memory (`.autodev/graph/`)
 
-**The agent forgets, the graph does not.** The project graph is a typed, queryable
-graph of the project's facts and work, persisted at `.autodev/graph/graph.jsonl`
-**relative to the project dir**. It survives your session and is **shared by every
-agent** in the workspace — what one agent learns, the swarm can read.
-
-> **Graph ≠ memory.** The file memory (`.autodev/memories/`, §0.2) is prose recall
-> for *you*. The graph is *structured, sourced, versioned* facts for *everyone*,
-> across sessions. Use both: memory for narrative, the graph for the shared world model.
-
-### Tools (in the mcp-operate tool list — available to every provider)
-
-| Tool | Use it to |
-|---|---|
-| `graph_neighbors` | **At task start** — resolve an entity/node by id or name and expand 1–3 hops to recall what's already known *before* acting. This is context construction, not a dump. |
-| `graph_query` | Search nodes by type and/or text; returns ids to expand or link. |
-| `graph_add_node` | Record a typed fact and get its id. |
-| `graph_add_edge` | Link two nodes with a typed, sourced relationship. |
-| `graph_supersede` | Version a fact that changed (old node stays addressable). |
-| `graph_stats` | Health check — gaps, isolated nodes, contradictions, open questions. |
+**The agent forgets, the graph does not.** A typed, sourced, versioned graph of the
+project's facts/work at `.autodev/graph/graph.jsonl` — **shared by every agent**,
+surviving sessions. **Graph ≠ memory** (§0.2): memory is prose recall for *you*; the
+graph is the structured world model for *everyone*. Full tool docs live in each tool's
+own description — this is the when/why.
+
+### Tools (mcp-operate — every provider)
+- `graph_map` — **cold start, no id in hand.** Pinned core + top hubs + open questions + fresh decisions + live contradictions. "Where do I start."
+- `graph_toc` — navigable table-of-contents tree (spine = `parent_of`, auto-built from `file:line` sources); `root=<id>` drills a branch.
+- `graph_search` — reasoning-based, citable retrieval: give an `intent`, get a ranked bundle each citing `[id]` + why. *You* reason over the summaries.
+- `graph_neighbors` — at task start, expand an id/name 1–3 hops (ranked, token-budgeted, contradictions flagged). `summarize:true` returns a branch's rollup.
+- `graph_query` — relevance-ranked search by type/text (vectorless; `mode:'recent'` for pure recency).
+- `graph_add_node` — record a typed fact; **pass a one-line `summary`** on substantial nodes; cite a `file:line` `source` (auto-builds the tree); `pinned:true`/`props.area` optional.
+- `graph_add_edge` — typed, sourced link (validated against the edge ontology).
+- `graph_supersede` — version a changed fact (old stays addressable). `graph_rollup` — summary node for a cluster. `graph_pin` — mark a core invariant. `graph_stats` — health/telemetry.
 
 ### Schema
+Nodes: entity · claim · source · artifact · agent_run · evaluation · task · commit · metric · note · question · decision. Entities dedupe by a canonical token-set key (`UsageService` = `usage-service` = `usage service`). Edges: mentions · supports · contradicts · derived_from · produced · evaluates · revises · supersedes · depends_on · parent_of · resolved_to · relates_to.
 
-**Node types:** `entity` · `claim` · `source` · `artifact` · `agent_run` ·
-`evaluation` · `task` · `commit` · `metric` · `note` · `question` · `decision`.
-Entities dedupe by name (idempotent — re-adding merges aliases), so resolve real
-things (services, files, people, modules) as entities.
-
-**Edge types:** `mentions` · `supports` · `contradicts` · `derived_from` ·
-`produced` · `evaluates` · `revises` · `supersedes` · `depends_on` · `parent_of` ·
-`resolved_to` · `relates_to`.
-
-### Invariants (enforced on write — a rejected write tells you what to add)
-
-1. Every **claim** has a `source` (`"file:line"` / url / source-node id) **or** `inference: true`.
-2. Every **artifact** has a `version`.
-3. Every **evaluation** names the `rubric` it judged against.
-4. **Superseded nodes are never deleted** — they stay addressable; `graph_supersede` links the replacement with a `supersedes` edge.
-
-Provenance (your run id + agent id + timestamp) is attached to every write automatically.
-
-### How it folds into the core loop
+### Invariants (enforced on write)
+1. A **claim** needs a `source` (`file:line`/url/id) or `inference:true`. 2. An **artifact** needs a `version`. 3. An **evaluation** needs a `rubric`. 4. Superseded nodes are **never deleted** (stay addressable). Provenance (run+agent+ts) is auto-attached.
 
-- **Start of a non-trivial task:** `graph_neighbors` on the entities in the task to
-  load prior claims, decisions, and artifacts. Don't rebuild the world from scratch.
-- **While working:** record what you learn as you learn it —
-  `claim`s (with a source), `decision`s (what/why), `artifact`s (with version),
-  `evaluation`s (with rubric), and the `entity`s/`task`s they concern. Link them
-  (`supports`, `contradicts`, `depends_on`, `produced`, `derived_from`, …).
-- **When a fact changes:** `graph_supersede` rather than overwrite — keep the history.
-- **Open questions & conflicts:** add a `question` node, or a `contradicts` edge, so
-  the next agent picks it up. Run `graph_stats` to find isolated/unlinked facts.
+### Loop-fold
+- **Task start:** know the entity → `graph_neighbors`; don't → `graph_map` or `graph_search <intent>`. Recall before acting.
+- **While working:** record facts as you learn them — claims (with source), decisions (what/why), artifacts (with version), evaluations (with rubric) — and link them. Cite `file:line` so the tree fills itself; pass a `summary`.
+- **Changed fact:** `graph_supersede`, don't overwrite. **Conflicts/unknowns:** add a `question` node or a `contradicts` edge. Pin a *few* core invariants.
 
-**Goal:** every important output is traceable to an objective, a source, a graph path,
-an evaluation, and a run. When that holds, the swarm's memory compounds instead of resetting.
+**Goal:** every important output traces to an objective, a source, a graph path, an evaluation, and a run — so the swarm's memory compounds instead of resetting.