memex/.opencode/AGENTS.md

# OpenCortex Agent Mandate

This file defines the operating policies and engineering guidelines that all autonomous agents MUST follow.

## Vision

- **Pure Lisp + Org-mode**: All intelligence implemented in Lisp, all documentation in Org-mode
- **No JSON, No YAML**: Thin harness, fat skills
- **Constraint**: No temporary scripts in opencortex repo - use `/home/user/memex/system/` instead

## Current Goal

- **v0.2.0**: Self-Improvement + Local LLMs
  - org-skill-self-edit (self-modification)
  - org-skill-emacs-edit (full org-mode manipulation)
  - Local vector search (Ollama embeddings)
  - Tool permission tiers (ask/allow/deny)
  - Skill hot-reload ✅ DONE
  - Engineering Standards skill ✅ DONE
  - Literate Programming skill ✅ DONE

## Wake-Up Protocol

When this agent starts, it MUST:

1. **Read this file** (`~/.opencode/AGENTS.md`)
2. **Query the skill catalog**: Before any analysis, check if a skill covers the problem domain
   - `(list-skills)` to see all loaded skills
   - `(find-skill :keyword)` to check for a specific domain
   - Read the skill's org file if found
3. **Verify git status**: Working tree MUST be clean before modification
4. **Read `gtd.org`**: Load current task context from the roadmap
5. **Enter lifecycle**: Follow the Engineering Standards lifecycle (Phase 0 → A → B → C → D → E)

Rationale: Raw LLM reasoning is a fallback, not a starting point. The skill layer encodes the system's accumulated wisdom. Ignoring skills creates drift.

## Engineering Standards

The Engineering Standards skill (`opencortex.skills.org-skill-engineering-standards`) defines the full lifecycle. The summaries below are reminders; the skill org file is authoritative.

### Phase 0: Before You Think

**Skill-First Query Rule**: Before analysis, debugging, or implementation, query the skill catalog. If a relevant skill exists, follow its mandates. Do not duplicate logic.

### Phase A: Design (Test-First)

1. **Define success criteria first** — Write the test or PROTOCOL that proves the feature works
2. **Break the design with chaos** — Three tiers of adversarial testing:
   - *Deterministic chaos*: Scripted regression tests on every change
   - *Probabilistic chaos*: Randomized fuzzing on every major release
   - *Stress chaos*: Load and resource starvation during hardening sprints

### Phase B: Commit (Recovery Point)

3. **Commit Before Modify** — Commit and push (if network available) before any file changes

### Phase C: Build (Implementation)

4. **Literate Programming** — All logic in Org files; generated `.lisp` is derived, not authored
5. **Function-Block Granularity** — One function per `#+begin_src lisp` block
6. **Tangle Mandate** — Edit Org only; never touch generated `.lisp`
7. **Configuration Externalization** — No hardcoded values; use `.env.example`
8. **Org as Thinking Medium** — Document investigation before fixing

### Phase D: Validate (Proof)

9. **Test Verification** — Run the full suite. A change that breaks tests is damage, not a fix.

### Phase E: Document (Audit Trail)

10. **Decision Audit Trail** — Document root cause, options, tradeoffs, and rationale
11. **Stop-and-Wait** — For major changes, propose strategy, state "Waiting for user feedback," yield turn
12. **GTD Synchronization** — Update `gtd.org` with TODO headlines before marking complete

## Literate Programming Rules

The Literate Programming skill (`opencortex.skills.org-skill-literate-programming`) enforces Org discipline:

1. **One Function, One Block** — No bundling multiple definitions
2. **Org-Mode Evaluation Gate** — `C-c C-c` after every block change
3. **Pre-Tangle Structural Check** — Verify paren balance before tangling
4. **No Direct `.lisp` Edits** — All changes flow through Org
5. **Code and Prose Together** — Every block preceded by explanatory text

Violating these rules corrupts the skill loader and causes boot failure (as seen in the 2026-04-25 incident).

## Agent Workflow

- **Boot Sequence**: Read AGENTS.md → query skills → verify git → read gtd.org
- **Before Any Modification**: Commit first (Commit Before Modify rule)
- **Plan Mode**: Draft PROTOCOL.md before complex implementations
- **Testing**: Run FiveAM test suite + chaos tests before marking task complete
- **Completion**: Update gtd.org, commit, sync with user

## Self-Enforcement Checklist

This agent MUST verify these conditions before, during, and after each task. Violation is a bug, not a suggestion.

### Before Any Task (Gate)

- [ ] **Git clean** — Working tree must be clean before modification
- [ ] **Skill query** — Check if relevant skill exists in `/home/user/memex/projects/opencortex/skills/`
- [ ] **Skill read** — If found, read the skill's org file before proceeding
- [ ] **GTD read** — Check `gtd.org` for current task context

### During Task (Literate Programming)

- [ ] **REPL-first workflow** — Explore in REPL before writing code
- [ ] **Utils-lisp for structural ops** — Use these functions for any .lisp work:
  - `utils-lisp-structural-extract` — Extract function definitions
  - `utils-lisp-structural-inject` — Inject forms into definitions
  - `utils-lisp-structural-wrap` — Wrap code in let/progn
  - `utils-lisp-validate` — Validate code before commit
  - `repl-eval` — Test code in REPL
  - `repl-inspect` — Inspect variables/functions
- [ ] **Never use edit tool on .lisp** — Only edit .org files; never touch generated .lisp directly
- [ ] **One function per block** — Each `#+begin_src` block contains exactly one definition
- [ ] **Prose before code** — Every block preceded by explanatory text
- [ ] **Prose includes**: What the function does, arguments, return value, rationale
- [ ] **Evaluate each block** — Verify the block compiles/evaluates correctly
- [ ] **Paren balance** — Check balanced parentheses before tangling

### After Task (Validation)

- [ ] **REPL verified** — Code tested in REPL before commit (not just text edit)
- [ ] **Utils-lisp used** — Confirmed structural operations went through utils-lisp
- [ ] **Tests pass** — Run full test suite; 100% pass required
- [ ] **Chaos tier 1** — Deterministic regression tests pass
- [ ] **No artifacts** — No orphaned `.bak`, `.log`, `.tmp`, or untracked test files
- [ ] **Commit** — Stage and commit changes with descriptive message
- [ ] **GTD update** — Update `gtd.org` with completed task state

### For OpenCortex Work Specifically

Reference authoritative skill files:
- Engineering Standards: `projects/opencortex/skills/org-skill-engineering-standards.org`
- Literate Programming: `projects/opencortex/skills/org-skill-literate-programming.org`
- Policy: `projects/opencortex/skills/org-skill-policy.org`

The summaries in this file are reminders; the skill org files are authoritative.

## References

- opencortex repo: `/home/user/memex/projects/opencortex`
- Engineering Standards: `/home/user/memex/projects/opencortex/skills/org-skill-engineering-standards.org`
- Literate Programming: `/home/user/memex/projects/opencortex/skills/org-skill-literate-programming.org`
- Policy Skill: `/home/user/memex/projects/opencortex/skills/org-skill-policy.org`
- Roadmap: `/home/user/memex/gtd.org`
- README: `/home/user/memex/projects/opencortex/README.org`