KNOWLEDGE.md

# KNOWLEDGE.md

> **agent-p Single Source of Truth** - This file is the master reference for agent-p (TypeScript)
> Previous version: python-expert-agent (Python) at `C:\myfiles\sampleCodes\python-expert-agent\`
>
> Contains: Architecture decisions, project paths, technical references, API configurations
> Version: **0.0.1** | Last Updated: 2026-03-06

---

# Part Z: agent-p Overview (TypeScript Version)

## Z1: Tech Stack

→ See: [BUILD.md Tech Stack](./BUILD.md#tech-stack)

## Z1.1: Why Pure TypeScript?

| Factor              | Hybrid (TS+Python)          | Pure TypeScript                  |
| ------------------- | --------------------------- | -------------------------------- |
| **OpenCode Native** | Hooks in TS, core in Python | Full native integration          |
| **Claude Code**     | Plugin bridge complexity    | Direct Task tool usage           |
| **Distribution**    | Multiple runtimes           | Single Node.js bundle            |
| **Type Safety**     | Interface boundaries        | End-to-end TypeScript            |
| **Memory**          | FFI or subprocess           | Native SQLite via better-sqlite3 |
| **Tool Ecosystem**  | Split between two           | Unified npm ecosystem            |
| **Debugging**       | Cross-language tracing      | Single stack traces              |
| **Deployment**      | Python+Node required        | Node.js only                     |

**Decision**: Pure TypeScript for maximum native platform integration and simplicity.

## Z2: Architecture - Two Separate Modules

> **IMPORTANT**: Memory and Search are **two separate modules**:

| Module     | Purpose                          | Components                             |
| ---------- | -------------------------------- | -------------------------------------- |
| **Memory** | Tiered storage (data retention)  | hot/warm/cold tiers                    |
| **Search** | 4-stage retrieval (data finding) | Ripgrep → Tree-sitter → BM25 → Jaccard |

## Z3: Four-Stage Search Pipeline

```
User Query → Ripgrep (fast filter) → Tree-sitter (AST parse) → BM25 (rank) → Jaccard (skill routing)
```

| Stage | Tool        | Purpose                                                 | Performance            |
| ----- | ----------- | ------------------------------------------------------- | ---------------------- |
| 1     | Ripgrep     | Fast text filter, find candidates                       | <10ms for 10k files    |
| 2     | Tree-sitter | Parse source to AST (multi-language), structural search | <20ms for 10 files     |
| 3     | BM25        | Rank by relevance                                       | <5ms for 10 candidates |
| 4     | Jaccard     | Skill routing                                           | <1ms                   |

### Tree-sitter Integration

> **Why Tree-sitter?** Since agent-p runs on Node.js runtime, it lacks native AST access for target languages. Tree-sitter provides structural code understanding via AST parsing for any supported language.

```typescript
// src/search/tree-sitter.ts
import { Parser } from "web-tree-sitter";

type SupportedLanguage =
  | "python"
  | "typescript"
  | "javascript"
  | "go"
  | "rust"
  | "java"
  | "cpp"
  | "c"
  | "ruby"
  | "php";

interface TreeSitterConfig {
  language: SupportedLanguage;
  query?: string;
}

class TreeSitterSearch {
  private parser: Parser;

  async search(query: string, files: string[]): Promise<ASTMatch[]> {
    // 1. Parse files to AST
    // 2. Run tree-sitter queries for structural patterns
    // 3. Return AST matches (function defs, decorators, imports, etc.)
  }
}

// Example queries:
// - "find all functions with @app.route decorator"
// - "find all classes inheriting from BaseModel"
// - "find all async functions"
```

## Z4: Agent Structure

**Main Agent**: `expert` (orchestrator - coordinates all work)

**5 Subagents** (Pipeline):
| # | Agent | Purpose | Stage |
|---|-------|---------|-------|
| 1 | scout | Finding context | 1st |
| 2 | builder | Code generation | 2nd |
| 3 | tester | Testing | 3rd |
| 4 | reviewer | Code review | 4th |
| 5 | verifier | Verification | 5th |

### Z4.1: Phase 5 Scaffold Contracts (Implemented)

- `ExpertOrchestrator` now emits lifecycle-aware handoffs with:
  - `handoffId`: deterministic role-prefixed identifier (`h-{role}-{digest}`)
  - `parentHandoffId`: optional lineage link for downstream stages
  - `attempt`: bounded retry counter (default `1`)
- Deterministic ID generation strategy uses SHA1 over stable fields:
  - `{sessionId}:{to}:{query}:{timestamp}:{attempt}`
- Verifier trust input typing uses partial input to satisfy strict optional semantics (`exactOptionalPropertyTypes`):
  - `VerifierAssessmentRequest.trustInput?: Partial<VerifierTrustInput>`
  - runtime defaults still come from `verifierTrustInputSchema`

### Z4.2: Phase 6 Quality Path Prep (Implemented)

- Expert orchestration now has a policy-only composition API for quality handoffs:
  - `ExpertQualityCompositionPolicy` with optional flags
  - `includeTester`, `includeReviewer`, `includeVerifier`
- `ExpertOrchestrator.composeQualityPath(...)` builds deterministic handoff chains:
  - default chain: `tester -> reviewer -> verifier`
  - policy-filtered chain support (for example, reviewer+verifier only)
  - lineage propagation via `parentHandoffId` across planned handoffs
- Output stability coverage for CLI agent commands is enforced with golden snapshots:
  - `agents:scout`, `agents:builder`, `agents:tester`, `agents:reviewer`, `agents:verifier`
  - snapshots live in unit tests to detect contract drift early

### Z4.3: Post-Verdict Hardening Rules (Implemented)

- Scout memory retrieval is session-scoped by contract:
  - `ScoutMemoryService.searchSession(term, sessionId, limit?)`
  - no cross-scope scout lookup (`searchAll`) in runtime path
- Runtime checkpoint boundaries are schema-validated before use:
  - checkpoint payload, context analysis, and phase artifacts are parsed/validated
  - phase/artifact compatibility is enforced during load/save flows
- Filesystem/eval telemetry writers enforce identifier/path hardening:
  - sanitized identifiers and root-confined path resolution
  - ripgrep pattern injection ambiguity removed via explicit `-e` arg handling

### TeamMode (agno)

```typescript
enum TeamMode {
  COLLABORATE = "collaborate", // All agents work together
  COORDINATE = "coordinate", // Sequential handoffs
  ROUTE = "route", // Route to single best agent
}
```

### Agent Modes

| Aspect         | Orchestrator                   | Context Helper               |
| -------------- | ------------------------------ | ---------------------------- |
| **Activation** | User selection or auto-detect  | Always available             |
| **Token cost** | Full session                   | Minimal (~200-500 per skill) |
| **Actions**    | Delegates, monitors, validates | Suggests patterns            |
| **State**      | Manages context files          | Read-only                    |
| **Subagents**  | Full delegation                | None                         |
| **Skills**     | Explicit invocation            | Auto-activation              |
| **Platform**   | OpenCode + Claude (selected)   | OpenCode + Claude (any mode) |

### Skills Always Available

> **Skills exist in the platform skills list regardless of whether expert is selected.**

| Platform     | Skills Location     | Activation                                 |
| ------------ | ------------------- | ------------------------------------------ |
| **OpenCode** | `.opencode/skills/` | Auto via triggers OR explicit skill() call |
| **Claude**   | Plugin skills list  | Auto via plugin triggers                   |

### Progressive Disclosure

| Load Level | Token Cost | Content                      |
| ---------- | ---------- | ---------------------------- |
| Minimal    | ~200-500   | Quick Reference tables       |
| Standard   | ~500-1500  | + Common patterns            |
| Full       | ~2000-5000 | Complete skill documentation |

### Agent Data Flow

```
User Query
    │
    ▼
┌─────────────────────────────────────┐
│         EXPERT (Orchestrator)        │
│  - Delegates to subagents            │
│  - Manages context files              │
│  - Quality gate coordination         │
└─────────────────────────────────────┘
    │
    ▼
┌───────────┐    SKILL ACTIVATION     ┌─────────────┐
│   SCOUT   │ ◀──────────────────────▶│   SKILLS    │
│           │     4-stage search       │  (Hybrid    │
│ Context   │     Ripgrep →            │   Triggers) │
│ Finding   │     Tree-sitter →        │             │
│           │     BM25 → Jaccard       │             │
└─────┬─────┘                          └─────────────┘
      │ HandoffPayload
      │ + Memory Access (hot/warm/cold)
      ▼
┌───────────┐    SKILL ACTIVATION     ┌─────────────┐
│   BUILDER  │ ◀──────────────────────▶│   SKILLS    │
│           │                          │             │
│ Code      │ ──▶ Generate code       │             │
│ Generation│     + Skill context     │             │
└─────┬─────┘                          └─────────────┘
      │ HandoffPayload
      │ + Memory Access (hot/warm/cold)
      ▼
┌───────────┐    FAIL    ┌───────────┐
│  TESTER   │ ──────────▶│  BUILDER │ (fix + retry)
│           │             │           │
│ {lang}-test│    PASS     │           │
│ {lang}-lint│ ──────────▶│           │
│ {lang}-type            │             │
└─────┬─────┘
      │ HandoffPayload
      │ + Memory Access (hot/warm/cold)
      ▼
┌───────────┐    FAIL    ┌───────────┐
│ REVIEWER  │ ──────────▶│  BUILDER │ (fix + retry)
│           │             │           │
│ Quality   │    PASS     │           │
│ Analysis  │ ──────────▶│           │
└─────┬─────┘             └─────────────┘
      │ HandoffPayload
      │ + Memory Access (hot/warm/cold)
      ▼
┌───────────┐
│ VERIFIER  │
│           │
│ Trust     │ ──▶ Trust Score Formula
│ Score     │     Rigor×0.30 + Quality×0.25 +
│           │     Verify×0.20 + Complete×0.15 + Method×0.10
└─────┬─────┘
      │
      ▼
┌───────────┐
│  TRUST    │ ──▶ Verify evidence quality
│  GATE     │     Before output delivery
└─────┬─────┘
      │
      ▼
   Output
      │
      ▼
┌───────────┐
│  GOAL     │ ──▶ Verify goal completion
│  GATE     │     Session end
└───────────┘
```

| Stage | Agent        | Primary Action            | Skill Activation                      | Memory Access     | On Failure    |
| ----- | ------------ | ------------------------- | ------------------------------------- | ----------------- | ------------- |
| 1     | **SCOUT**    | Context finding           | Keywords, patterns                    | hot → warm → cold | N/A           |
| 2     | **BUILDER**  | Code generation           | Domain skills                         | hot → warm → cold | N/A           |
| 3     | **TESTER**   | Language-specific testing | {lang}-test, {lang}-lint, {lang}-type | hot → warm → cold | → BUILDER fix |
| 4     | **REVIEWER** | Quality analysis          | Review patterns                       | hot → warm → cold | → BUILDER fix |
| 5     | **VERIFIER** | Trust scoring             | Verification                          | hot → warm        | → TRUST GATE  |

| Quality Gate   | Purpose                 | Trigger                |
| -------------- | ----------------------- | ---------------------- |
| **Trust Gate** | Verify evidence quality | Before output delivery |
| **Goal Gate**  | Verify goal completion  | Session end            |

### Agent Handoff Protocol (openai-agents-python)

```typescript
interface HandoffInputData {
  inputHistory: Message[];
  preHandoffItems: RunItem[];
  newItems: RunItem[];
  inputFilter?: HandoffInputFilter;
}

interface HandoffPayload {
  fromAgent: string;
  toAgent: string;
  sessionId: string;
  context: Message[];
  artifacts: Artifact[];
  memory: MemorySnapshot;
  metadata: {
    handoffReason: string;
    timestamp: number;
    priority: "low" | "normal" | "high";
  };
}

interface Artifact {
  id: string;
  type: "code" | "document" | "test" | "config";
  content: string;
  language?: string;
  path?: string;
}

interface MemorySnapshot {
  hot: Record<string, unknown>[];
  warm: string[]; // keys only
  summary: string;
}
```

## Z5: Project Structure

```
agent-p/
├── src/
│   ├── cli.ts              # CLI entry + command dispatcher
│   ├── index.ts            # Main entry point
│   │
│   ├── memory/             # Memory system (tiered storage)
│   │   ├── store.ts        # SQLite + FTS5
│   │   ├── schema.ts       # Drizzle ORM schema
│   │   ├── manager.ts      # MemoryManager API
│   │   ├── scopes/
│   │   │   ├── session.ts   # Session scope
│   │   │   ├── user.ts      # User scope
│   │   │   ├── shared.ts    # Shared scope
│   │   │   └── private.ts   # Private scope
│   │   └── tiered/
│   │       ├── hot.ts       # lru-cache (fastest)
│   │       ├── warm.ts      # SQLite + FTS5 (medium)
│   │       └── cold.ts      # JSONL files (archive)
│   │
│   ├── search/             # Search system (4-stage)
│   │   ├── ripgrep.ts      # Stage 1: Fast filter
│   │   ├── tree-sitter.ts  # Stage 2: AST parse (best-effort)
│   │   ├── bm25.ts         # Stage 3: Rank results
│   │   ├── jaccard.ts      # Stage 4: Skill routing
│   │   └── index.ts        # SearchEngine API
│   │
│   ├── skills/             # Skill loader + manager
│   │   ├── loader.ts       # YAML frontmatter parser
│   │   ├── activation.ts   # Auto-activation logic
│   │   ├── registry.ts     # Skill registry
│   │   ├── validator.ts    # Skill validator
│   │   ├── skills.json     # Skill metadata
│   │   └── ...
│   │
│   ├── agents/             # 5 Subagents + Orchestrator
│   │   ├── expert.ts       # Orchestrator (main agent)
│   │   ├── scout.ts        # Context finding (Stage 1)
│   │   ├── builder.ts      # Code generation (Stage 2)
│   │   ├── tester.ts       # Testing (Stage 3)
│   │   ├── reviewer.ts     # Code review (Stage 4)
│   │   ├── verifier.ts     # Verification (Stage 5)
│   │   └── handoff.ts      # Agent handoff protocol
│   │
│   ├── hooks/              # Platform hooks (5 hooks)
│   │   ├── session_start.ts
│   │   ├── pre_tool_use.ts
│   │   ├── post_tool_use.ts
│   │   ├── stop.ts
│   │   └── notification.ts
│   │
│   ├── quality/             # Quality Gates
│   │   ├── trust_gate.ts   # Trust score verification
│   │   ├── goal_gate.ts    # Goal completion check
│   │   ├── danger_check.ts # Dangerous pattern detection
│   │   ├── circuit_breaker.ts
│   │   ├── retry.ts
│   │   └── error_recovery.ts
│   │
│   ├── expertise/          # Expertise System (mulch-inspired)
│   │   ├── record.ts       # ExpertiseRecord types
│   │   ├── domains/        # 7 domain JSONL files
│   │   │   ├── general.jsonl
│   │   │   ├── programming.jsonl
│   │   │   ├── testing.jsonl
│   │   │   ├── architecture.jsonl
│   │   │   ├── api.jsonl
│   │   │   ├── database.jsonl
│   │   │   └── devops.jsonl
│   │   └── governance.ts   # Shelf-life & pruning
│   │
│   ├── workflow/           # D3 Workflow Engine
│   │   ├── engine.ts       # Workflow orchestrator
│   │   ├── phases/
│   │   │   ├── understand.ts  # Phase 1
│   │   │   ├── design.ts      # Phase 2
│   │   │   ├── plan.ts        # Phase 3
│   │   │   ├── tdd_red.ts     # Phase 4
│   │   │   ├── tdd_green.ts   # Phase 5
│   │   │   ├── refactor.ts    # Phase 6
│   │   │   ├── review.ts      # Phase 7
│   │   │   ├── verify.ts      # Phase 8A/8B
│   │   │   └── deliver.ts     # Phase 9
│   │   └── cache.ts
│   │
│   └── utils/
│       ├── token_monitor.ts  # Token threshold monitoring
│       ├── validators.ts     # Zod schemas
│       └── config.ts         # Config loading
│
├── skills/                  # Trial catalog (5/40 active via src/skills/skills.json)
│   └── [skill-name]/
│       └── SKILL.md
│
├── .agent-p/               # Agent runtime data
│   ├── config.yaml         # Agent configuration
│   ├── telemetry/          # Observability (tracing, tracking)
│   │   ├── sessions/
│   │   │   └── {run_id}.jsonl
│   │   ├── metrics/
│   │   │   └── {date}.jsonl
│   │   └── traces/
│   │       └── {trace_id}.json
│   │
│   └── evals/              # Evaluations & Scoring
│       ├── agents/
│       │   └── {agent_id}.jsonl
│       ├── subagents/
│       │   └── {subagent_id}.jsonl
│       ├── skills/
│       │   └── {skill_name}.jsonl
│       └── feedback/
│           └── feedback.jsonl
│
├── .claude/                # Claude Code config
├── .opencode/              # OpenCode config
│
├── migrations/             # Drizzle migrations
│   └── 001_initial.ts
│
├── test/                   # vitest tests
│   ├── memory/
│   ├── search/
│   ├── skills/
│   ├── agents/
│   └── workflow/
│
├── package.json
├── tsconfig.json
├── eslint.config.js
├── prettier.config.js
├── vitest.config.ts
└── BUILD.md               # Execution tracker
```

## Z6: Key Design Decisions

| Decision       | Value                           |
| -------------- | ------------------------------- |
| MCP Server     | ❌ NO - platform-native tools   |
| Vector Search  | ❌ NO                           |
| Smart Chunking | ❌ NO                           |
| RRF            | ❌ NO - single search type      |
| Skill router   | Jaccard (10% threshold)         |
| Skill metadata | src/skills/skills.json          |
| Memory scopes  | 4 (session/user/shared/private) |
| Memory tiers   | 3 (hot/warm/cold)               |

## Z7: Token Thresholds

| Token Count | Action                | Reason                       |
| ----------- | --------------------- | ---------------------------- |
| < 13,000    | Peak performance      | Optimal reasoning density    |
| 33,000      | Checkpoint progress   | Stability maintained         |
| 70,000      | Prepare for rotation  | Approaching limits           |
| 100,000+    | Terminate and restart | ~50% performance degradation |

### The Inverse Performance Rule

Reasoning quality is inversely proportional to token count, hitting a critical failure point at 100k tokens.

| Context Threshold      | Performance Impact | Resulting Reasoning Density      |
| ---------------------- | ------------------ | -------------------------------- |
| ~10,000 Tokens         | System Overhead    | Baseline (Fixed by platform)     |
| < 13,000 Tokens        | **Optimal**        | **Peak Performance**             |
| 33,000 – 70,000 Tokens | Moderate Load      | Maintained Stability             |
| 100,000+ Tokens        | **Severe Load**    | **~50% Performance Degradation** |

> **Key Insight**: The more context you load, the worse the reasoning becomes.

### First Message Weight

Due to transformer attention mechanisms, the initial directive exerts a dominant influence on subsequent behavior.

| Implication                            | Best Practice                                     |
| -------------------------------------- | ------------------------------------------------- |
| Concise, targeted initial directives   | "Implement auth using patterns in skills/fastapi" |
| Avoid loading irrelevant context early | Don't include verbose project history upfront     |
| Clear, focused instructions at start   | Prioritize key requirements                       |

### Mitigation Strategies

| Strategy                    | Purpose                       | Token Savings  |
| --------------------------- | ----------------------------- | -------------- |
| **Skill Auto-Activation**   | Only relevant skills loaded   | ~80% reduction |
| **Minimal Context Loading** | Quick Reference tables only   | ~70% reduction |
| **Path-Based References**   | File paths instead of content | ~90% reduction |
| **Session Rotation**        | Fresh context periodically    | Complete reset |

## Z8: Hooks System

| Hook           | Trigger              | Purpose                              |
| -------------- | -------------------- | ------------------------------------ |
| `SessionStart` | Session begins       | Re-inject AGENTS.md after compaction |
| `PreToolUse`   | Before tool executes | Safety validation                    |
| `PostToolUse`  | After tool executes  | Pattern learning                     |
| `Stop`         | Session ends         | Quality gate verification            |
| `Notification` | Alerts/events        | Alert handling                       |

### Z8.1: Hooks Governance Baseline (Implemented)

- Neutral core event contracts are platform-agnostic:
  - `session_start`, `pre_tool_use`, `post_tool_use`, `stop`, `notification`
- Platform translators are boundary-only:
  - Claude input/output adapters in `src/hooks/translators/claude.ts`
  - OpenCode input/output adapters in `src/hooks/translators/opencode.ts`
- Shared policy engine:
  - `HookPolicyEngine` in `src/hooks/policy.ts`
  - Config keys under `hooks.policy.*`
  - Profile model: `strict | balanced | permissive`
  - Scoped policy overrides with deterministic precedence:
    - base profile defaults
    - category override (`hooks.policy.categoryOverrides.<category>`)
    - tool override (`hooks.policy.toolOverrides.<toolName>`)
- Shared observability/audit layer:
  - `HookAuditLogger`, `InMemoryHookAuditSink`, `JsonlHookAuditSink` in `src/hooks/audit.ts`
  - Config keys under `hooks.audit.*`
- Governance diagnostics CLI commands:
  - `agent-p hooks:config`
  - `agent-p hooks:audit-log`
- Backward-compatible policy migration at config load:
  - legacy `strictMode` maps to profile semantics
  - profile-based config backfills `strictMode` for compatibility checks
- CLI output contracts covered by snapshots for both `hooks:config` and `hooks:audit-log`

**Hook Exit Codes**:
| Code | Behavior |
|------|----------|
| 0 | Success - Allow operation |
| 1 | Error - Show stderr to user |
| 2 | Block - Stop operation |

## Z9: Skill Trigger Types

| Trigger Type     | Source        | Example                                                                              |
| ---------------- | ------------- | ------------------------------------------------------------------------------------ |
| Keywords         | User query    | Skill-dependent (e.g., "pytest" for Python, "jest" for JS, "fastapi" for Python API) |
| Intent Patterns  | Regex match   | "(create\|build).\*?api"                                                             |
| File Patterns    | Project paths | Skill-dependent (e.g., `**/*.py` for Python, `**/*.ts` for TypeScript)               |
| Content Patterns | File contents | Skill-dependent (e.g., `from fastapi import` for Python, `import { z }` for TS)      |

## Z10: Context File Protocol

| File      | Purpose            |
| --------- | ------------------ |
| PLAN.md   | Planning decisions |
| AGENTS.md | Project context    |
| .tm files | Session state      |

## Z11: Glossary

| Term                       | Definition                                                                                      |
| -------------------------- | ----------------------------------------------------------------------------------------------- |
| **D3 Workflow**            | Design-Develop-Deliver workflow system with phases for planning, implementation, and validation |
| **Trust Gate**             | Quality checkpoint that validates code meets safety/quality thresholds before proceeding        |
| **Goal Gate**              | Verification that the current goal/objective has been achieved before handoff                   |
| **HandoffPayload**         | Data structure passed between agents containing context, history, and metadata                  |
| **Progressive Disclosure** | UI/UX pattern where complexity is revealed gradually; applied here to skill activation          |
| **Shelf-life**             | Time duration before cached data/memory is considered stale and refreshed                       |
| **Hot/Warm/Cold Tiers**    | Memory tiering system: hot=LRU cache (fastest), warm=SQLite (persistent), cold=archive          |
| **Circuit Breaker**        | Pattern that prevents cascading failures by stopping requests to failing services               |
| **Ripgrep**                | CLI search tool (`rg`) used as primary text search in the 4-stage pipeline                      |
| **BM25**                   | Ranking function used for text search relevance scoring                                         |
| **Jaccard**                | Similarity metric used for skill matching based on keyword overlap                              |
| **FTS5**                   | SQLite Full-Text Search extension for efficient text queries                                    |

## Z12: Testing Strategy

### Z12.1: Test Pyramid

```
       ┌─────────────┐
       │    E2E     │  ← Critical paths only (5-10 tests)
       ├─────────────┤
       │ Integration │  ← Module interactions (20-40 tests)
       ├─────────────┤
       │   Unit      │  ← Per-module (60-80% coverage target)
       └─────────────┘
```

### Z12.2: Test Structure

```
test/
├── unit/
│   ├── memory/
│   │   ├── store.spec.ts
│   │   ├── manager.spec.ts
│   │   └── tiered/
│   │       ├── hot.spec.ts
│   │       ├── warm.spec.ts
│   │       └── cold.spec.ts
│   ├── search/
│   │   ├── ripgrep.spec.ts
│   │   ├── treesitter.spec.ts
│   │   ├── bm25.spec.ts
│   │   └── jaccard.spec.ts
│   ├── skills/
│   │   ├── loader.spec.ts
│   │   ├── activation.spec.ts
│   │   ├── registry.spec.ts
│   │   └── validator.spec.ts
│   ├── agents/
│   │   ├── expert.spec.ts
│   │   ├── scout.spec.ts
│   │   ├── builder.spec.ts
│   │   ├── tester.spec.ts
│   │   ├── reviewer.spec.ts
│   │   └── verifier.spec.ts
│   │
│   │   # Agent coverage exists for all scaffolded agents and quality/runtime paths
│   │
│   ├── quality/
│   │   ├── trust_gate.spec.ts
│   │   ├── goal_gate.spec.ts
│   │   ├── danger_check.spec.ts
│   │   └── circuit_breaker.spec.ts
│   ├── workflow/
│   │   ├── engine.spec.ts
│   │   └── phases/
│   └── utils/
│       ├── config.spec.ts
│       ├── validators.spec.ts
│       └── token_monitor.spec.ts
├── integration/
│   ├── memory-search.spec.ts
│   ├── agent-handoff.spec.ts
│   ├── skill-activation.spec.ts
│   ├── quality-pipeline.spec.ts
│   └── workflow-phases.spec.ts
├── helpers/
│   └── cli-runner.ts
├── setup.ts
└── e2e/
    ├── cli-governance-smoke.e2e-spec.ts
    ├── full-agent-pipeline.spec.ts
    ├── d3-workflow.spec.ts
    └── memory-tiering.spec.ts
```

### Z12.3: Coverage Targets

| Level       | Target         | Description           |
| ----------- | -------------- | --------------------- |
| Unit        | >80%           | Per-module coverage   |
| Integration | 100%           | All module boundaries |
| E2E         | Critical paths | User workflows only   |

### Z12.4: Test Commands

```bash
# Run all tests
pnpm test

# Watch mode
pnpm test:watch

# Coverage report
pnpm test:coverage

# E2E tests only
pnpm test:e2e
```

### Z12.5: Module Test Breakdown

| Module          | Unit Tests                              | Integration Tests               | E2E Tests       |
| --------------- | --------------------------------------- | ------------------------------- | --------------- |
| `src/memory/`   | store, manager, tiered tiers            | cross-tier ops, SQLite backup   | session flow    |
| `src/search/`   | ripgrep, treesitter, bm25, jaccard      | 4-stage pipeline                | full search     |
| `src/skills/`   | loader, activation, registry, validator | skill loading + auto-activation | skill task flow |
| `src/agents/`   | all 6 agents                            | agent handoffs                  | full pipeline   |
| `src/quality/`  | trust_gate, goal_gate, danger_check     | quality pipeline                | E2E quality     |
| `src/workflow/` | engine, all 9 phases                    | phase transitions               | D3 execution    |
| `src/utils/`    | config, validators, token_monitor       | config loading                  | N/A             |

---

## Z13: Documentation Structure

### Z13.1: docs/ Directory

```
docs/
├── architecture/
│   ├── overview.md      # System architecture diagram
│   ├── agents.md       # Agent pipeline & handoffs
│   ├── memory.md       # Memory tiering system
│   ├── search.md       # 4-stage search pipeline
│   ├── skills.md       # Skill system
│   ├── workflow.md     # D3 workflow phases
│   └── quality.md      # Quality gates
├── api/
│   └── reference/      # Auto-generated via TypeDoc
├── guides/
│   ├── contributing.md # Development setup, PR process
│   ├── testing.md       # How to write tests
│   ├── skills.md        # How to create skills
│   └── workflow.md     # D3 workflow usage
└── CHANGELOG.md        # Version history
```

### Z13.2: Build Enforcement

**package.json scripts:**

```json
{
  "scripts": {
    "build": "pnpm run build:check && pnpm run build:compile && pnpm run build:assets",
    "build:check": "pnpm run lint && pnpm run docs:check",
    "build:compile": "tsc",
    "build:assets": "tsx bin/copy-skills-manifest.ts",
    "docs:check": "tsx bin/docs-verify.ts",
    "test": "vitest run",
    "test:watch": "vitest",
    "test:coverage": "vitest --coverage",
    "test:e2e": "vitest run --config vitest.e2e.config.ts",
    "test:contracts": "vitest run test/unit/cli.test.ts test/unit/cli-hooks.test.ts",
    "verify:phase9": "pnpm typecheck && pnpm lint && pnpm test && pnpm test:contracts && pnpm test:e2e && pnpm test:coverage && pnpm build && pnpm docs:check",
    "lint": "eslint src/ test/",
    "typecheck": "tsc --noEmit"
  }
}
```

### Z13.3: docs:verify Script

The `bin/docs-verify.ts` script validates:

- Required architecture docs are present and readable:
  - `docs/architecture/overview.md`
  - `docs/architecture/foundation.md`
  - `docs/architecture/agents.md`
  - `docs/architecture/memory.md`
  - `docs/architecture/search.md`
  - `docs/architecture/skills.md`
  - `docs/architecture/workflow.md`
  - `docs/architecture/quality.md`
- Each required architecture doc is non-empty and includes at least one markdown heading
- Build fails if any check fails

---

# Part A: PROJECT PATHS (agent-p - TypeScript Version)

## A1: Root Directory Structure

→ See: [Z5: Project Structure](#z5-project-structure) for complete directory tree

### Quick Reference

| Path         | Purpose                                                                                       |
| ------------ | --------------------------------------------------------------------------------------------- |
| `src/`       | Source code (cli, memory, search, skills, agents, hooks, quality, expertise, workflow, utils) |
| `skills/`    | 40 domain skills                                                                              |
| `.agent-p/`  | Runtime data (config.yaml, telemetry/, evals/)                                                |
| `.claude/`   | Claude Code config                                                                            |
| `.opencode/` | OpenCode config                                                                               |
| `test/`      | vitest tests                                                                                  |

### Key Files

| File              | Purpose                              |
| ----------------- | ------------------------------------ |
| `src/cli/index.ts` | CLI entry + command dispatcher       |
| `src/index.ts`     | Main entry point                     |
| `src/memory/`      | Memory system (tiered storage)      |
| `src/search/`      | Search system (4-stage)             |
| `src/skills/`      | Skill loader + manager              |
| `src/agents/`      | 5 subagents + orchestrator          |

---

## Z14: Problems and Solutions

This section documents architectural problems identified during development and their chosen solutions.

### Problem A: Search Pipeline Contract Problem

**Issue**: The 4-stage search pipeline (Ripgrep → Tree-sitter → BM25 → Jaccard) has fragile data flow. Each stage expects different input/output types, making the system hard to maintain and test.

**Root Cause**: Implicit data flow between stages with no shared contract.

**Solution**: Define explicit `SearchContext` object passed through entire pipeline.

```typescript
interface SearchContext {
  query: string;
  files: string[];
  results: SearchResult[];
  stage: "init" | "ripgrep" | "treesitter" | "bm25" | "jaccard";
  metadata: {
    startTime: number;
    stageTimings: Record<string, number>;
    tokensUsed: number;
  };
}

interface SearchResult {
  file: string;
  line?: number;
  score: number;
  context: string[];
  stage: string;
}
```

**Implementation**: Added explicit `SearchContext` pipeline contract in `src/search/pipeline.ts` and routed `SearchEngine.query()` orchestration through it.

---

### Problem B: Skill System Chicken-and-Egg Problem

**Issue**: SkillActivator with hybrid triggers is built in isolation (vacuum). Can't test without live agent.

**Root Cause**: Activation logic and skill loading are tightly coupled with no ability to test independently.

**Solution**: Split into two concerns:

1. **Skill Loader** (`load_skill()` tool): Manual skill loading capability
2. **Skill Suggestion Engine** (`suggest_skills()`): Isolated function for automatic recommendations

**Implementation**: Start with hardcoded skill list for testing the trigger engine, then build YAML parser for production.

```typescript
// Phase 1: Hardcoded for testing
const SKILLS = [
  {
    id: "typescript",
    domains: ["frontend", "backend"],
    triggers: [".ts", "tsconfig"],
  },
  { id: "react", domains: ["frontend"], triggers: [".jsx", ".tsx"] },
  // ...
];

// Phase 2: Load from YAML
interface SkillDefinition {
  id: string;
  name: string;
  domains: string[];
  triggers: Trigger[];
  capabilities: string[];
}

interface Trigger {
  type: "file_pattern" | "function_call" | "context";
  pattern: string;
}
```

---

### Problem C: Workflow Engine FSM Problem

**Issue**: 9-phase D3 workflow without state machine pattern. Risk of giant switch/case becoming unmaintainable.

**Root Cause**: No formal state transition logic - phases defined implicitly in code.

**Solution**: Implement as explicit Finite State Machine with defined transitions.

```typescript
type Phase =
  | "understand"
  | "design"
  | "plan"
  | "develop" // TDD RED
  | "build" // TDD GREEN
  | "refactor" // TDD REFACTOR
  | "review"
  | "verify"
  | "deliver";

interface Transition {
  from: Phase;
  to: Phase;
  condition: (context: WorkflowContext) => boolean;
  action?: (context: WorkflowContext) => Promise<void>;
}

const TRANSITIONS: Transition[] = [
  { from: "understand", to: "design", condition: hasRequirements },
  { from: "design", to: "plan", condition: hasSpecs },
  { from: "plan", to: "develop", condition: hasPlan },
  { from: "develop", to: "build", condition: testsFail },
  { from: "build", to: "refactor", condition: testsPass },
  { from: "refactor", to: "review", condition: always },
  { from: "review", to: "verify", condition: reviewApproved },
  { from: "verify", to: "deliver", condition: verificationPassed },
  // ...
];
```

**Recommendation**: Keep explicit transitions (not generic FSM pattern) for 9 phases — allows TypeScript exhaustiveness checking and is more readable.

---

### Summary Table

| Problem                      | Root Cause                                              | Solution                                                                                              | Status   |
| ---------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | -------- |
| A: Search Pipeline           | Implicit data flow                                      | Consolidate into `pipeline.ts` with `SearchContext`                                                   | Done     |
| B: Skill System              | Coupled loading/trigger                                 | Split into `load_skill()` + `suggest_skills()`, start with hardcoded list                             | Done     |
| C: Workflow Engine           | No state machine                                        | Explicit FSM with 9 D3 phases (understand→design→plan→develop→build→refactor→review→verify→deliver)   | Done     |
| D: Runtime & Database        | Bun doesn't support better-sqlite3                      | Use Node.js (>=24) + pnpm + better-sqlite3 + sql.js fallback                                          | Done     |
| E: Native Driver Activation  | pnpm build-script approvals block native module builds  | Approve/rebuild `better-sqlite3`, keep sql.js fallback, validate both modes in CI                     | Done     |
| F: FTS5 Availability         | `sql.js` runtime may not include FTS5 module            | Detect FTS5 at init; use FTS5 when available, otherwise safe `LIKE` fallback search                   | Done     |
| G: ESLint v10 Flat Config    | `eslint.config.*` missing at repository root            | Add root flat config, include `src`+`test`, and fix lint-violating throw-cause handling               | Done     |
| H: package.json Script Drift | Scripts/reference docs diverged from repository state   | Align scripts with actual files and validate declared scripts in CI                                   | Done     |
| I: Coverage Gate Recovery    | Registry `ECONNRESET` blocked coverage provider install | Install `@vitest/coverage-v8`, restore Vitest coverage config, and re-enable coverage in Phase 9 gate | Resolved |
| J: TypeDoc Peer Mismatch     | `typedoc@0.27.x` peer range lagged behind TS `5.9.x`    | Upgrade TypeDoc to `0.28.x` to match current TypeScript toolchain                                     | Done     |

---

### Problem D: Runtime and Database Selection

**Issue**: Need to choose runtime (Node.js vs Bun) and database driver (better-sqlite3 vs sql.js) for cross-platform compatibility.

**Root Cause**: Bun runtime does not support native SQLite modules (better-sqlite3). The module explicitly states: "'better-sqlite3' is not yet supported in Bun" (see https://github.com/oven-sh/bun/issues/4290).

**Options Considered**:

| Runtime     | Database       | Pros                   | Cons                     |
| ----------- | -------------- | ---------------------- | ------------------------ |
| **Bun**     | better-sqlite3 | Native speed           | ❌ Not supported in Bun  |
| **Bun**     | sql.js         | Works in Bun           | ❌ WASM overhead, slower |
| **Node.js** | better-sqlite3 | Native speed, full API | ❌ Node.js only          |
| **Node.js** | sql.js         | Works everywhere       | ❌ Slower                |

**Chosen Solution**:

| Decision              | Value          | Rationale                                   |
| --------------------- | -------------- | ------------------------------------------- |
| **Runtime**           | Node.js (>=24) | better-sqlite3 has full native support      |
| **Package Manager**   | pnpm 10.30.3   | Fast, disk-efficient, modern                |
| **Database Primary**  | better-sqlite3 | Native SQLite, 10-100x faster than sql.js   |
| **Database Fallback** | sql.js         | Safety net if better-sqlite3 fails to build |

**Implementation**:

```typescript
// src/db/manager.ts
export async function createDatabaseManager(
  config: DatabaseConfig,
): Promise<DatabaseManager> {
  const preferredDriver = config.driver ?? "better-sqlite3";

  if (preferredDriver === "better-sqlite3") {
    try {
      return new BetterSqlite3Manager(config);
    } catch (e) {
      console.warn(
        `better-sqlite3 failed (${(e as Error).message}), falling back to sql.js`,
      );
    }
  }

  return SqlJsManager.create(config);
}
```

**Verification Results**:

| Environment    | Database Driver | Status   |
| -------------- | --------------- | -------- |
| Node.js 20+    | better-sqlite3  | ✅ Works |
| Bun (fallback) | sql.js          | ✅ Works |

**Recommendation**: Use Node.js as primary runtime. Keep sql.js fallback for graceful degradation.

---

### Problem E: Native Driver Not Active (pnpm Build Approval)

**Issue**: In some environments, `better-sqlite3` is installed but not active. Runtime falls back to `sql.js`, and `db:check` reports fallback mode.

**Root Cause**: pnpm blocks native build scripts by default unless explicitly approved. Without native build execution, `better-sqlite3` cannot finish install/build in that environment.

**Current Status**:

- **Database is functional** via `sql.js` fallback (`db:check` succeeds).
- **Build-script warning is closed** via explicit pnpm approval policy in `package.json` (`pnpm.onlyBuiltDependencies` includes `better-sqlite3` and `esbuild`).
- **Native path validation remains required** through `db:check` in CI to guarantee non-fallback execution.

**Impact Assessment**:

| Area          | Impact When Native Path Is Inactive            |
| ------------- | ---------------------------------------------- |
| Functionality | ✅ Core DB operations still work via fallback  |
| Performance   | ⚠️ Usually slower than native `better-sqlite3` |
| Confidence    | ⚠️ Primary production path is not exercised    |
| Risk          | ⚠️ Driver-specific behavior can appear late    |

**Decision**: Not a Phase 1 blocker; treat as near-term technical debt that must be resolved before production hardening.

**Solution (Local Environment)**:

```bash
pnpm approve-builds
pnpm install
pnpm rebuild better-sqlite3
```

If needed, ensure scripts are not blocked:

```bash
pnpm config set ignore-scripts false
pnpm install
```

**Windows Build Prerequisites** (when no prebuilt binary is available):

- Python 3
- Visual Studio C++ Build Tools (MSVC)
- Node.js version compatible with `better-sqlite3`

**Verification**:

```bash
pnpm build:compile
node bin/cli.js db:check
```

Expected native mode result:

- `driver: "better-sqlite3"`
- `isFallback: false`

**CI Hardening Plan**:

1. Add a native-required CI job that enables scripts and rebuilds `better-sqlite3`.
2. Run `node bin/cli.js db:check` and fail job if fallback is used.
3. Keep a separate fallback CI job to validate `sql.js` path.
4. Add DB integration tests for both primary and fallback drivers.

**Recommendation**: Continue Phase 2 and Phase 3 in parallel with this hardening work, but complete native-driver activation before production readiness milestones.

**Status**: Done (build-script warning resolved; explicit native-mode CI assertion remains a hardening improvement).

---

### Problem F: FTS5 Not Available in sql.js Fallback

**Issue**: Memory store initialization can fail with `no such module: fts5` when running on fallback SQLite driver (`sql.js`).

**Root Cause**: `sql.js` builds are WASM-based and may not include SQLite FTS5 extension support in the current runtime.

**Impact Assessment**:

| Area          | Impact When FTS5 Is Missing                         |
| ------------- | --------------------------------------------------- |
| Functionality | ✅ Memory CRUD works                                |
| Search        | ⚠️ Full-text `MATCH` unavailable on fallback driver |
| Security      | ✅ Query parameterization still enforced            |
| Reliability   | ✅ Initialization no longer fails                   |

**Implemented Solution**:

1. During `SqliteMemoryStore.initialize()`, try creating the FTS5 table/triggers.
2. If FTS initialization succeeds: enable FTS path (`MATCH` queries).
3. If it fails: continue with warm-tier table/index setup and enable fallback search using parameterized `LIKE` (`lower(key/value) LIKE ?`).

**Behavior Contract**:

- `better-sqlite3` mode: FTS5 expected and used when available.
- `sql.js` fallback mode: FTS5 may be unavailable; search gracefully degrades to substring matching.

**Operational Guidance**:

- If full-text search is required in all environments, enforce native driver usage (`better-sqlite3`) and fail startup/CI when fallback is selected.
- Keep fallback path covered by tests to guarantee baseline search behavior without FTS5.

---

### Problem G: ESLint v10 Flat Config Missing

**Issue**: `pnpm lint` fails with ESLint v10 error: `ESLint couldn't find an eslint.config.(js|mjs|cjs) file`.

**Root Cause**: Project uses ESLint v10 (`package.json`) but repository root does not contain a flat config file.

**Observed Failure**:

```bash
pnpm lint
# ESLint couldn't find an eslint.config.(js|mjs|cjs) file.
```

**Implemented Solution**:

1. Added root flat config file `eslint.config.js`.
2. Configured lint targets for both source and tests via flat-config file patterns (`src/**/*.ts`, `test/**/*.ts`).
3. Installed/used flat-config dependencies:

```bash
pnpm add -D @eslint/js typescript-eslint globals
```

4. Updated lint script to include test directory:

```json
"lint": "eslint src/ test/"
```

5. Re-ran quality checks:

```bash
pnpm typecheck && pnpm lint && pnpm test
```

**Follow-up Fix**:

- Lint introduced stricter rule coverage and surfaced `preserve-caught-error` in `src/db/migration-runner.ts`.
- Updated thrown migration error to preserve the original cause with `{ cause: error }`.

**Verification**:

- `pnpm lint` passes
- `pnpm typecheck` passes
- `pnpm test` passes

**Status**: Done.

---

### Problem H: package.json Script Drift and Missing Config Targets

**Issue**: `package.json` script definitions and docs references had diverged from repository reality.

**Findings from package.json check**:

- `test:e2e` drift was fixed by moving to dedicated E2E config execution (`vitest run --config vitest.e2e.config.ts`) while preserving integration lane coverage.
- `lint` script was expanded to lint both source and tests (`eslint src/ test/`).
- `docs:check` was added (`tsx bin/docs-verify.ts`) to enforce required architecture docs.
- `build:check` now runs both lint and docs validation (`pnpm run lint && pnpm run docs:check`).

**Root Cause**: Documentation and script contracts diverged from actual repository state during phased implementation.

**Solution Implemented**:

1. Standardized on the current authoritative contract in `package.json` (`build`, `build:check`, `build:compile`, `build:assets`, `docs:check`, `lint`, `typecheck`, `test`, `test:e2e`, `test:contracts`, `verify:phase9`).
2. Added lightweight docs verification in `bin/docs-verify.ts` for required architecture files.
3. Verified full quality chain against live scripts.

**Verification**:

- `pnpm typecheck` passes
- `pnpm lint` passes
- `pnpm test` passes
- `pnpm test:e2e` passes
- `pnpm verify:phase9` passes (including `pnpm test:coverage`)

**Status**: Done.

---

### Problem I: Coverage Provider Install Blocked by Registry Connectivity

**Issue**: Initial attempts to install `@vitest/coverage-v8` failed with `ECONNRESET` during npm registry fetch, blocking coverage gating in Phase 9.

**Resolution implemented**:

1. Successfully installed `@vitest/coverage-v8` (`pnpm add -D @vitest/coverage-v8`).
2. Restored active coverage configuration in `vitest.config.ts` with provider `v8` and reporters `text` + `html`.
3. Re-enabled `pnpm test:coverage` as a blocking step inside `verify:phase9`.
4. Preserved the intended gate order: typecheck -> lint -> test -> contracts -> e2e -> coverage -> build -> docs check.

**Verification (final gate set)**:

- `pnpm typecheck` passes
- `pnpm lint` passes
- `pnpm test` passes
- `pnpm test:contracts` passes
- `pnpm test:e2e` passes
- `pnpm test:coverage` passes
- `pnpm build` passes
- `pnpm docs:check` passes

**Status**: Resolved.

---

### Problem J: TypeDoc Peer Dependency Mismatch with TypeScript 5.9

**Issue**: `typedoc@0.27.9` reported unmet peer dependency because it expected TypeScript `<=5.8.x` while project uses `typescript@5.9.3`.

**Resolution implemented**:

1. Upgraded TypeDoc to `0.28.17`.
2. Retained TypeScript at `5.9.3` to avoid regressing compiler/tooling baseline.
3. Re-ran install and verification with updated documentation toolchain.

**Verification**:

- `pnpm add -D typedoc@latest` completed and removed peer mismatch warning.
- `pnpm verify:phase9` passes with the upgraded TypeDoc dependency present.

**Status**: Done.

---

# Part B: MEMORY INFRASTRUCTURE (TypeScript)

## B1: Memory Architecture

### Two Separate Modules

> **IMPORTANT**: Memory and Search are **two separate modules**

| Module     | Purpose                          | Components                                          |
| ---------- | -------------------------------- | --------------------------------------------------- |
| **Memory** | Tiered storage (data retention)  | hot (lru-cache) / warm (SQLite FTS5) / cold (JSONL) |
| **Search** | 4-stage retrieval (data finding) | Ripgrep → Tree-sitter → BM25 → Jaccard              |

### Drizzle ORM

Memory module uses **Drizzle ORM** with better-sqlite3:

- Type-safe schema definitions
- Migration support
- Lightweight (not full ORM - query builder)

```typescript
import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
import { sql } from "drizzle-orm";

export const memoryEntries = sqliteTable("memory_entries", {
  id: text("id").primaryKey(),
  scope: text("scope").notNull(), // session|user|shared|private
  key: text("key").notNull(),
  value: text("value").notNull(), // JSON serialized
  createdAt: integer("created_at", { mode: "timestamp" }).default(
    sql`CURRENT_TIMESTAMP`,
  ),
  updatedAt: integer("updated_at", { mode: "timestamp" }).default(
    sql`CURRENT_TIMESTAMP`,
  ),
});
```

### Memory Scopes

| Scope   | Identifier          | Visibility    | Use Case              |
| ------- | ------------------- | ------------- | --------------------- |
| Session | `run_id`            | Session only  | Temporary task state  |
| User    | `user_id`           | Cross-session | User preferences      |
| Shared  | `app_id`            | All agents    | Project context       |
| Private | `app_id + agent_id` | Single agent  | Agent-specific memory |

### Memory Tiers (3 Tiers - Current Implementation)

> **Note**: 9 temperature levels defined below (extreme_hot → extreme_cold) represent the **future enhancement** when promotion/demotion is implemented. For Phase 2, the 3-tier system (hot/warm/cold) is sufficient.

| Tier     | Level | Name | Backend       | Speed   | Capacity  |
| -------- | ----- | ---- | ------------- | ------- | --------- |
| **HOT**  | 1-3   | hot  | lru-cache     | Fastest | 10 MB     |
| **WARM** | 4-6   | warm | SQLite + FTS5 | Medium  | Unlimited |
| **COLD** | 7-9   | cold | JSONL files   | Slow    | Archive   |

> **Note**: HOT tier uses `lru-cache`. It's an in-memory LRU cache with TTL support.

### Temperature Enum (TypeScript)

> **Future Enhancement**: 9 levels (extreme_hot → extreme_cold) will be used when promotion/demotion is implemented. Currently using 3 tiers.

```typescript
enum Temperature {
  // Hot tier (levels 1-3)
  hot = 0,

  // Warm tier (levels 4-6)
  warm = 1,

  // Cold tier (levels 7-9)
  cold = 2,
}

// Future: Full 9-level enum for promotion/demotion
enum TemperatureFineGrained {
  extreme_hot = 1,
  high_hot = 2,
  low_hot = 3,
  extreme_warm = 4,
  high_warm = 5,
  low_warm = 6,
  low_cold = 7,
  high_cold = 8,
  extreme_cold = 9,
}
```

### Promotion/Demotion Rules

Memory entries use **Importance** and **Stability** scores to determine promotion (hotter) or demotion (colder):

| Factor       | Weight | Description                  |
| ------------ | ------ | ---------------------------- |
| Importance   | 40%    | TRIVIAL (1) → CORE (5)       |
| Stability    | 30%    | VOLATILE (1) → PERMANENT (5) |
| Recency      | 20%    | Days since last access       |
| Access Count | 10%    | Frequency of access          |

```typescript
interface MemoryEntry {
  id: string;
  key: string;
  value: string;
  temperature: Temperature;
  importance: number; // 1-5: TRIVIAL → CORE
  stability: number; // 1-5: VOLATILE → PERMANENT
  lastAccessedAt: number; // Unix timestamp
  accessCount: number;
  createdAt: number;
}

function calculatePromotionScore(entry: MemoryEntry): number {
  const now = Date.now();
  const daysSinceAccess = (now - entry.lastAccessedAt) / (1000 * 60 * 60 * 24);

  const importanceScore = entry.importance * 0.4;
  const stabilityScore = entry.stability * 0.3;
  const recencyScore = Math.max(0, 1 - daysSinceAccess / 30) * 0.2; // Decay over 30 days
  const accessScore = Math.min(1, Math.log10(entry.accessCount + 1) / 3) * 0.1;

  return importanceScore + stabilityScore + recencyScore + accessScore;
}

// Demotion rules: Low importance + Low stability + No access
function shouldDemote(entry: MemoryEntry): boolean {
  const daysSinceAccess =
    (Date.now() - entry.lastAccessedAt) / (1000 * 60 * 60 * 24);

  return (
    entry.importance === 1 && entry.stability === 1 && daysSinceAccess > 30
  );
}

// Promotion rules: High importance + High stability + Recent access
function shouldPromote(entry: MemoryEntry): boolean {
  return (
    entry.importance >= 4 && entry.stability >= 4 && entry.accessCount >= 5
  );
}
```

### MemoryManager API

```typescript
import { MemoryManager } from "./memory";

const mem = new MemoryManager();

// Session state (temporary, session-bound)
mem.session.save("task-123", { step: "writing tests" });
mem.session.load("task-123");

// User preferences (cross-session)
mem.user.set("theme", "dark");
mem.user.get("theme");

// Shared context (all subagents)
mem.shared.add("Project uses FastAPI with async endpoints");
mem.shared.search("framework");

// Private context (single agent only)
mem.privateScope("builder").add("Current task: implement auth");
mem.privateScope("builder").search("task");

// Session-scoped retrieval (recommended for scout/runtime context)
const sessionResults = mem.searchSession("authentication", "default-session");

// Cross-scope search (diagnostics only)
const allResults = mem.searchAll("authentication");
```

### Drizzle Migrations

Memory module uses **Drizzle ORM** with migration support:

```bash
# Run migrations
pnpm run db:migrate

# Create new migration
pnpm run db:generate
```

```typescript
// src/db/migrate.ts
import { migrate } from "drizzle-orm/better-sqlite3/migrator";
import { db } from "./store";

async function main() {
  await migrate(db, { migrationsFolder: "./migrations" });
}

main();
```

```typescript
// migrations/001_add_memory_entries.ts
import { sql } from "drizzle-orm";
import { memoryEntries } from "../src/memory/schema";

export const up = sql`
  CREATE TABLE IF NOT EXISTS memory_entries (
    id TEXT PRIMARY KEY,
    scope TEXT NOT NULL,
    key TEXT NOT NULL,
    value TEXT NOT NULL,
    temperature INTEGER DEFAULT 4,
    importance INTEGER DEFAULT 3,
    stability INTEGER DEFAULT 3,
    created_at INTEGER DEFAULT (strftime('%s', 'now')),
    updated_at INTEGER DEFAULT (strftime('%s', 'now'))
  );
  
  CREATE INDEX IF NOT EXISTS idx_memory_scope ON memory_entries(scope);
  CREATE INDEX IF NOT EXISTS idx_memory_temperature ON memory_entries(temperature);
  CREATE VIRTUAL TABLE IF NOT EXISTS memory_fts USING fts5(key, value, content=memory_entries, content_rowid=rowid);
`;
```

---

# Part B2: EXPERTISE SYSTEM (mulch-inspired)

> Agent-learned knowledge that accumulates over time, stored in `.agent-p/expertise/`, works across sessions

## B2.1: Expertise vs Memory

| Aspect        | Memory             | Expertise            |
| ------------- | ------------------ | -------------------- |
| **What**      | Raw key-value data | Structured learnings |
| **Who**       | System stores      | Agent records        |
| **Format**    | JSON               | Typed JSONL          |
| **Retention** | TTL-based          | Classification-based |
| **Query**     | Exact match        | BM25 search          |

## B2.2: Record Types (6 types)

> Adopted from mulch-main

| Type         | Required Fields           | Use Case                  |
| ------------ | ------------------------- | ------------------------- |
| `convention` | content                   | "Use WAL mode for SQLite" |
| `pattern`    | name, description, files? | Named patterns with refs  |
| `failure`    | description, resolution   | What went wrong           |
| `decision`   | title, rationale          | Architectural decisions   |
| `reference`  | name, description, files? | Key files, endpoints      |
| `guide`      | name, description         | Step-by-step procedures   |

````typescript
interface ExpertiseRecord {
  id: string;           // mx-<hash>
  type: 'convention' | 'pattern' | 'failure' | 'decision' | 'reference' | 'guide';

  // Type-specific fields
  content?: string;           // convention
  name?: string;               // pattern, reference, guide
  description?: string;       // pattern, failure, reference, guide
  resolution?: string;         // failure
  title?: string;              // decision
  rationale?: string;          // decision
  files?: string[];            // pattern, reference

  // Common fields
  classification: 'foundational' | 'tactical' | 'observational';
  recorded_at: string;         // ISO timestamp
  evidence?: {
    commit?: string;
    issue?: string;
    file?: string;
    bead?: string;
  };
  tags?: string[];
  relates_to?: string[];       // domain:mx-<hash>
  supersedes?: string[];
}

## B2.3: Default Expertise Domains

| Domain | Purpose |
|--------|---------|
| **general** | Project-wide conventions |
| **programming** | Programming patterns (language-agnostic) |
| **testing** | Testing conventions |
| **architecture** | Architectural patterns |
| **api** | API patterns |
| **database** | Database conventions |
| **devops** | Deployment, CI/CD, infrastructure |

## B2.4: Classification & Shelf-Life

| Classification | Shelf Life | Use Case |
|---------------|------------|----------|
| `foundational` | Permanent | Core project conventions |
| `tactical` | 14 days | Task-specific learnings |
| `observational` | 30 days | Temporary observations |

> Automatic pruning removes tactical/observational entries after shelf-life expires

## B2.5: Governance

```yaml
# .agent-p/config.yaml
expertise:
  governance:
    max_entries: 100      # Warn after this
    warn_entries: 150    # Hard limit
    hard_limit: 200
  classification_defaults:
    shelf_life:
      tactical: 14
      observational: 30
````

## B2.6: Evidence Linking

Link expertise records to evidence:

```typescript
const record = {
  type: "failure",
  description: "VACUUM inside transaction causes silent corruption",
  resolution: "Always run VACUUM outside transaction boundaries",
  evidence: {
    commit: "abc123",
    issue: "#42",
    file: "src/db.ts",
  },
  relates_to: ["database:mx-abc1"],
  supersedes: ["database:mx-xyz9"],
};
```

## B2.7: Storage Structure

```
.agent-p/
├── expertise/
│   ├── general.jsonl       # Project-wide conventions
│   ├── programming.jsonl   # Language-agnostic patterns
│   ├── testing.jsonl      # Testing conventions
│   ├── architecture.jsonl # Architectural patterns
│   ├── api.jsonl          # API patterns
│   ├── database.jsonl     # Database conventions
│   └── devops.jsonl       # Deployment, CI/CD, infrastructure
└── config.yaml            # Governance settings
```

## B2.8: Concurrency Safety

- **File locking**: Advisory lock with O_CREAT|O_EXCL (50ms retry, 5s timeout)
- **Atomic writes**: Write to temp file, then rename

```typescript
async function record(domain: string, record: ExpertiseRecord): Promise<void> {
  const lockPath = `.agent-p/expertise/${domain}.lock`;
  await acquireLock(lockPath);

  try {
    const tempPath = `.agent-p/expertise/${domain}.tmp`;
    await writeTemp(tempPath, record);
    await rename(tempPath, `.agent-p/expertise/${domain}.jsonl`);
  } finally {
    await releaseLock(lockPath);
  }
}
```

## B2.9: BM25 Search

Tuned for short expertise records:

```typescript
const DEFAULT_BM25_PARAMS = {
  k1: 1.5, // Term frequency saturation
  b: 0.75, // Document length normalization
};
```

---

# Part C: SEARCH MODULE (TypeScript)

## C1: Four-Stage Pipeline

```
User Query → Ripgrep (fast filter) → Tree-sitter (AST parse) → BM25 (rank) → Jaccard (skill routing)
```

| Stage | Tool        | Purpose                                                 | Performance            |
| ----- | ----------- | ------------------------------------------------------- | ---------------------- |
| 1     | Ripgrep     | Fast text filter, find candidates                       | <10ms for 10k files    |
| 2     | Tree-sitter | Parse source to AST (multi-language), structural search | <20ms for 10 files     |
| 3     | BM25        | Rank by relevance                                       | <5ms for 10 candidates |
| 4     | Jaccard     | Skill routing                                           | <1ms                   |

## C2: Stage Details

### Stage 1: Ripgrep (The Mover)

- Pre-filters files to ~10-50 candidates
- Uses keywords and file patterns
- Fast, pattern-based filtering

### Stage 2: Tree-sitter (The Analyzer)

- Parses source files to AST using `web-tree-sitter` (language-agnostic)
- Enables structural code search (not just text)
- Supports: Python, TypeScript, JavaScript, Go, Rust, Java, C++, and more
- Examples:
  - Find all functions with `@app.route` decorator
  - Find all classes inheriting from `BaseModel`
  - Find all async functions
- Compensates for lack of native AST in TypeScript runtime

#### Tree-sitter Configurability

> **Why Optional?** For small projects, Ripgrep + BM25 is sufficient. Tree-sitter adds dependency weight and parsing time.

```yaml
# .agent-p/config.yaml
search:
  stages:
    treesitter:
      mode: optional # required | optional | disabled
      threshold: 20 # files to trigger treesitter (default: 20)
      timeout_ms: 500 # per-file parse timeout (default: 500)
```

| Mode       | Behavior                            |
| ---------- | ----------------------------------- |
| `required` | Fail if Tree-sitter unavailable     |
| `optional` | Skip if >threshold files or timeout |
| `disabled` | Skip Stage 2 entirely               |

### Stage 3: BM25 (The Judge)

- Ranks candidates using TF-IDF-based scoring
- Considers term frequency and document length
- Provides relevance ranking
- Current implementation uses deterministic tie-break ordering (`score desc`, then path/line/column)

### Stage 4: Jaccard (The Router)

- Skill routing based on trigger matching
- 10% similarity threshold
- Final classification

## C3: Search API

```typescript
import { SearchEngine } from "./search";

const search = new SearchEngine({
  workspaceRoot: process.cwd(),
  bm25: { k1: 1.2, b: 0.75, limit: 50 },
});

const results = await search.query({
  query: "fastapi async endpoint",
  root: "src",
  limit: 20,
});

// Returns SearchResponse:
// {
//   query, root, mode, limit,
//   totalCandidates,
//   hits: SearchHit[]
// }
```

**BM25 limit rule:** final ranked hits are capped by `min(request.limit, bm25.limit)` when a BM25 limit is configured; otherwise request `limit` is used.

---

# Part D: SKILL SYSTEM (TypeScript)

## D0: Skills Architecture

### Skills Always Available Model

```
┌─────────────────────────────────────────────────────────────────┐
│              SKILLS ALWAYS AVAILABLE MODEL                       │
├─────────────────────────────────────────────────────────────────┤
  PLATFORM SK│                                                                  │
│ILLS LIST                                            │
│  ├── expert (orchestrator, always available)                    │
│  ├── python-fundamentals (always loaded, critical)              │
│  ├── python-fastapi (loaded on trigger match)                   │
│  ├── python-testing-general (loaded on trigger match)           │
│  └── ... 40 skills total                                        │
│                                                                  │
│  TRIGGER ENGINE                                                  │
│  ├── Monitors: user queries, file operations, content          │
│  ├── Matches: keywords, intent, paths, content patterns        │
│  └── Scores: relevance to determine activation                  │
│                                                                  │
│  CONTEXT INJECTION                                               │
│  ├── Minimal: Quick Ref tables (~200-500 tokens)              │
│  ├── Standard: + Patterns (~500-1500 tokens)                   │
│  └── Full: Complete skill (~2000-5000 tokens)                  │
│                                                                  │
│  RESULT                                                          │
│  ├── Skills help ANY agent/mode                                 │
│  └── Token-efficient context delivery                           │
└─────────────────────────────────────────────────────────────────┘
```

### Skill Trigger Types

| Trigger Type     | Source        | Example                                                    |
| ---------------- | ------------- | ---------------------------------------------------------- |
| Keywords         | User query    | Skill-dependent (e.g., "pytest" for Python, "jest" for JS) |
| Intent Patterns  | Regex match   | "(create\|build).\*?api"                                   |
| File Patterns    | Project paths | Skill-dependent (e.g., `**/*.py`, `**/*.ts`)               |
| Content Patterns | File contents | Skill-dependent (e.g., `from fastapi`, `import { z }`)     |

## D1: 40 Skills by Category

### Category A: Core Python (4)

| Skill                   | Purpose               |
| ----------------------- | --------------------- |
| python-fundamentals     | Core Python patterns  |
| python-fundamentals-313 | Python 3.13+ features |
| python-type-hints       | Type system           |
| python-asyncio          | Async patterns        |

### Category B: Web & API (4)

| Skill             | Purpose                 |
| ----------------- | ----------------------- |
| python-fastapi    | FastAPI production      |
| python-backend    | SQLAlchemy 2.0 async    |
| python-api-client | REST clients            |
| python-websocket  | Real-time communication |

### Category C: Testing & QA (6)

| Skill                  | Purpose                 |
| ---------------------- | ----------------------- |
| python-testing-general | pytest fundamentals     |
| python-testing-deep    | Advanced testing        |
| python-testing-async   | Async test patterns     |
| python-anti-patterns   | Anti-patterns checklist |
| python-error-handling  | Error handling patterns |
| python-tooling         | DevOps/CI-CD            |

### Category D: Package & Project (3)

| Skill                     | Purpose               |
| ------------------------- | --------------------- |
| python-package-management | UV package manager    |
| python-project-structure  | Project organization  |
| python-architecture       | Architecture patterns |

### Category E: Data & Visualization (6)

| Skill                | Purpose             |
| -------------------- | ------------------- |
| python-ocr           | OCR operations      |
| python-scraper       | Web scraping        |
| python-data-cleaning | Data cleaning       |
| python-charts        | Visualization       |
| python-database      | Database operations |
| python-pipeline      | ETL patterns        |

### Category G: Media (1)

| Skill         | Purpose          |
| ------------- | ---------------- |
| python-ffmpeg | Video processing |

### Category H: Cloud & Infra (5)

| Skill             | Purpose                |
| ----------------- | ---------------------- |
| python-modal      | Modal serverless       |
| python-aws        | AWS integration        |
| python-sysmon     | System monitoring      |
| python-deploy     | Deployment             |
| python-cloudflare | Cloudflare integration |

### Category I: Automation (4)

| Skill            | Purpose            |
| ---------------- | ------------------ |
| python-files     | File operations    |
| python-scheduler | Task scheduling    |
| python-alerts    | Notifications      |
| python-browser   | Browser automation |

### Category J: Data Analysis (6)

| Skill          | Purpose          |
| -------------- | ---------------- |
| python-nlp     | NLP operations   |
| python-images  | Image processing |
| python-opencv  | Computer vision  |
| python-sound   | Audio processing |
| python-ml      | Machine learning |
| python-ml-deep | Deep learning    |

## D2: Skill Trigger Configuration

> **Trigger Sources**: Skill activation uses **hybrid triggers** from 3 sources:
>
> 1. **YAML Frontmatter** - Primary metadata in SKILL.md (keywords, intentPatterns, filePatterns)
> 2. **triggers.json** - Fallback for legacy skills (promptTriggers, fileTriggers)
> 3. **Skill Tool Invocation** - Explicit call via `/skill:name` or `skill({ name: "..." })`

### D2.1: Unified Frontmatter Format

```yaml
---
name: python-fastapi
description: Build REST APIs with FastAPI, Pydantic validation, and async endpoints
compatibility: ["claude", "opencode"]
metadata:
  category: web
  language: python
  framework: fastapi
allowed-tools:
  - "read"
  - "edit"
  - "write"
  - "bash"
  - "grep"
  - "glob"
triggers:
  keywords:
    ["fastapi", "pydantic", "endpoint", "api route", "router", "uvicorn"]
  intentPatterns:
    [
      "(create|build|add|implement).*?(api|endpoint|route)",
      "(fastapi|pydantic).*?(validation|schema|model)",
    ]
  filePatterns: ["**/*.py", "**/main.py", "**/routes/**", "**/api/**"]
  contentPatterns:
    [
      "from fastapi import",
      "@app\\.(get|post|put|delete|patch)",
      "from pydantic import",
      "APIRouter",
    ]
priority: high
activation: auto
contextLoad: minimal
permissions:
  default: allow
  agents:
    plan: allow
    implementer: allow
    debug: deny
---
```

> **Note**: `allowed-tools` restricts which tools this skill can use when active (from zai-skills pattern)

### D2.2: Legacy triggers.json (Fallback)

```json
{
  "skill": "python-fastapi",
  "activation": "auto",
  "priority": "high",
  "contextLoad": "minimal",
  "promptTriggers": {
    "keywords": [
      "fastapi",
      "pydantic",
      "endpoint",
      "api route",
      "router",
      "uvicorn"
    ],
    "intentPatterns": [
      "(create|build|add|implement).*?(api|endpoint|route)",
      "(fastapi|pydantic).*?(validation|schema|model)"
    ]
  },
  "fileTriggers": {
    "pathPatterns": ["**/*.py", "**/main.py", "**/routes/**", "**/api/**"],
    "contentPatterns": [
      "from fastapi import",
      "@app\\.(get|post|put|delete|patch)",
      "from pydantic import",
      "APIRouter"
    ]
  }
}
```

### D2.3: Progressive Loading (3 Levels)

| Level                     | When Loaded         | Token Cost  | Content                                            |
| ------------------------- | ------------------- | ----------- | -------------------------------------------------- |
| **Level 1: Metadata**     | Always (at startup) | ~100 tokens | `name`, `description`, `category` from frontmatter |
| **Level 2: Instructions** | When triggered      | < 5k tokens | SKILL.md body with instructions                    |
| **Level 3: Resources**    | As needed           | Free        | Bundled files (scripts, templates, refs)           |

### D2.4: Discovery Paths

| Location                     | Platform             | Priority |
| ---------------------------- | -------------------- | -------- |
| `.claude/skills/<name>/`     | Claude Code          | Low      |
| `.agents/skills/<name>/`     | agent-p custom       | Medium   |
| `.opencode/skills/<name>/`   | OpenCode             | High     |
| `~/.claude/skills/`          | Claude Code (global) | Low      |
| `~/.config/opencode/skills/` | OpenCode (global)    | High     |

### D2.5: Permission Controls

Per-skill, per-agent permissions (OpenCode-style):

```json
{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}
```

| Permission | Behavior                                  |
| ---------- | ----------------------------------------- |
| `allow`    | Skill loads immediately                   |
| `deny`     | Skill hidden from agent, access rejected  |
| `ask`      | User prompted for approval before loading |

Patterns support wildcards: `internal-*` matches `internal-docs`, `internal-tools`.

## D2.6: Skill Lifecycle Tooling

Tools for managing skill development, testing, and distribution:

```typescript
// Skill Validator - Lint skill triggers and metadata
interface SkillValidator {
  validateFrontmatter(skillPath: string): ValidationResult;
  checkTriggerConflicts(): Conflict[];
  verifyAllowedTools(): string[];
}

// Skill Test Harness - Run skill against example tasks
interface SkillTestHarness {
  runTest(skillName: string, task: string): TestResult;
  measureTokens(task: string): TokenUsage;
  captureActivationScore(skillName: string, context: string): number;
}

// Skill Packager - Share skill sets
interface SkillPackager {
  exportSkills(skills: string[], outputPath: string): void;
  importSkills(pkgPath: string): void;
  listExports(): PackageManifest[];
}
```

### D2.6.1: Skill Validator

```bash
# Lint triggers for conflicts
agent-p skill validate python-fastapi

# Check metadata completeness
agent-p skill lint --all

# Verify allowed-tools are valid
agent-p skill check-tools python-fastapi
```

### D2.6.2: Skill Test Harness

```bash
# Run skill against test task
agent-p skill test python-fastapi --task "create api endpoint"

# Capture token usage
agent-p skill benchmark python-fastapi --tasks test-cases/

# Show activation scores
agent-p skill debug-activation "find all functions"
```

### D2.6.3: Skill Packager

```bash
# Export skill set
agent-p skill export web-skills --output ./skills/web.tgz

# Import skill package
agent-p skill import ./skills/web.tgz

# List available packages
agent-p skill list-exports
```

---

# Part E: PLATFORM COMPATIBILITY

## E1: Dual Platform Support

| Platform    | Config Location         | Agent Definition   |
| ----------- | ----------------------- | ------------------ |
| Claude Code | `CLAUDE.md`             | `.claude/agents/`  |
| OpenCode    | `.opencode/config.json` | `.opencode/agent/` |

## E2: Platform Hooks

| Hook           | Trigger              | Purpose                            |
| -------------- | -------------------- | ---------------------------------- |
| `SessionStart` | Session begins       | Re-inject context after compaction |
| `PreToolUse`   | Before tool executes | Safety validation                  |
| `PostToolUse`  | After tool executes  | Pattern learning                   |
| `Stop`         | Session ends         | Quality gate verification          |
| `Notification` | Alerts/events        | Alert handling                     |

### E2.1: Hook Runtime Governance

| Layer           | Implementation                    | Notes                                                                |
| --------------- | --------------------------------- | -------------------------------------------------------------------- |
| Neutral Runtime | `src/hooks/*.ts`                  | Deterministic status/result schema for all hook events               |
| Policy Core     | `src/hooks/policy.ts`             | Centralized decisions for pre/post tool use, stop, and notification  |
| Audit Core      | `src/hooks/audit.ts`              | Structured event logging with redaction and JSONL sink support       |
| CLI Diagnostics | `hooks:config`, `hooks:audit-log` | Read effective hook config and inspect/clear in-memory audit events  |
| Config Contract | `src/config/schema.ts`            | Strict Zod defaults + contradictions guarded via `.superRefine(...)` |

### E2.2: Hook Config Keys

```yaml
hooks:
  policy:
    profile: balanced
    # Legacy compatibility flag; still accepted and migrated.
    strictMode: false
    escalationThreshold: 0.7
    riskyTools: [bash, write, webfetch]
    sensitivePatterns: [api_key, token, password, secret]
    categoryOverrides: {}
    toolOverrides: {}
    preToolUseDefaultDecision: allow
    postToolUseDefaultDecision: allow
    stopDefaultDecision: allow
  audit:
    enabled: true
    redactSensitive: true
    maxPreviewChars: 2000
```

---

# Part E2: Quality Gates & Trust Scoring

## E2.0 Quality Gate Matrix

| Gate         | Check                     | Tool                | Pass Criteria           |
| ------------ | ------------------------- | ------------------- | ----------------------- |
| **Syntax**   | Code blocks compile       | `tsc --noEmit`      | 0 errors                |
| **Types**    | TypeScript types valid    | `tsc --strict`      | 0 errors                |
| **Format**   | Follows SKILL.md template | Schema validation   | All sections present    |
| **Security** | No secrets, safe patterns | Secret scanning     | No credentials detected |
| **Tests**    | Test coverage             | `vitest --coverage` | >80% coverage           |

### Quality Gate Workflow

```
┌─────────────────────────────────────────────────────────────────┐
│                    QUALITY GATE WORKFLOW                        │
├─────────────────────────────────────────────────────────────────┤
  Code Changes                                                    │
       │                                                          │
       ▼                                                          │
  ┌─────────────┐     FAIL                                        │
  │   SYNTAX    │ ───────────────► Fix code errors               │
  │   CHECK     │                                                 │
  └─────┬───────┘                                                 │
        │ PASS                                                    │
        ▼                                                         │
  ┌─────────────┐     FAIL                                        │
  │    TYPE     │ ───────────────► Fix type hints                │
  │   CHECK     │                                                 │
  └─────┬───────┘                                                 │
        │ PASS                                                    │
        ▼                                                         │
  ┌─────────────┐     FAIL                                        │
  │  SECURITY   │ ───────────────► Remove secrets                │
  │   CHECK     │                                                 │
  └─────┬───────┘                                                 │
        │ PASS                                                    │
        ▼                                                         │
  ┌─────────────┐     FAIL                                        │
  │    TEST     │ ───────────────► Add/improve tests            │
  │   CHECK     │                                                 │
  └─────┬───────┘                                                 │
        │ PASS                                                    │
        ▼                                                         │
     DELIVER                                                      │
```

## E2.1 Two-Gate System (My-Jogyo)

| Gate           | Purpose                 | Trigger                |
| -------------- | ----------------------- | ---------------------- |
| **Trust Gate** | Verify evidence quality | Before output delivery |
| **Goal Gate**  | Verify goal completion  | Session end            |

## E2.2 Trust Score Formula

```typescript
interface TrustComponents {
  statisticalRigor: number; // 30%
  evidenceQuality: number; // 25%
  metricVerification: number; // 20%
  completeness: number; // 15%
  methodology: number; // 10%
}

function calculateTrust(c: TrustComponents): number {
  return (
    c.statisticalRigor * 0.3 +
    c.evidenceQuality * 0.25 +
    c.metricVerification * 0.2 +
    c.completeness * 0.15 +
    c.methodology * 0.1
  );
}
```

## E2.3 Importance Levels

| Level    | Score | Description                       |
| -------- | ----- | --------------------------------- |
| TRIVIAL  | 1     | Temp notes, quick reminders       |
| LOW      | 2     | Minor preferences, casual context |
| MODERATE | 3     | Standard working memory           |
| HIGH     | 4     | Key decisions, important context  |
| CORE     | 5     | Critical knowledge, never expires |

## E2.4 Stability Levels

| Level     | Score | Description            |
| --------- | ----- | ---------------------- |
| VOLATILE  | 1     | Changes frequently     |
| LOW       | 2     | Occasional updates     |
| MODERATE  | 3     | Regular updates        |
| HIGH      | 4     | Stable, rarely changes |
| PERMANENT | 5     | Immutable knowledge    |

## E2.5 Dangerous Pattern Detection (overstory)

```typescript
const DANGEROUS_PATTERNS = [
  /rm\s+-rf\s+\//,
  />\s*\/dev\/sd/,
  /curl.*\|\s*bash/,
  /DROP\s+TABLE/i,
  /DELETE\s+FROM/i,
  /format\s*c:/i,
];

function preToolUse(tool: string, input: unknown): boolean {
  const inputStr = JSON.stringify(input);
  return !DANGEROUS_PATTERNS.some((p) => p.test(inputStr));
}
```

## E2.6 Circuit Breaker

```typescript
interface CircuitBreakerConfig {
  failureThreshold: number; // failures before opening (default: 5)
  recoveryTimeout: number; // ms before half-open (default: 30000)
  halfOpenAttempts: number; // attempts in half-open (default: 3)
}

class CircuitBreaker {
  private state: "closed" | "open" | "half-open" = "closed";
  private failures = 0;
  private lastFailureTime = 0;

  constructor(private config: CircuitBreakerConfig = {}) {
    this.config.failureThreshold ??= 5;
    this.config.recoveryTimeout ??= 30000;
    this.config.halfOpenAttempts ??= 3;
  }

  async execute<T>(fn: () => Promise<T>): Promise<T> {
    if (this.state === "open") {
      if (Date.now() - this.lastFailureTime >= this.config.recoveryTimeout) {
        this.state = "half-open";
      } else {
        throw new Error("Circuit breaker open");
      }
    }

    try {
      const result = await fn();
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }

  private onSuccess() {
    this.failures = 0;
    this.state = "closed";
  }

  private onFailure() {
    this.failures++;
    this.lastFailureTime = Date.now();
    if (this.failures >= this.config.failureThreshold) {
      this.state = "open";
    }
  }
}
```

## E2.7 Retry Limits

```typescript
interface RetryConfig {
  maxAttempts: number; // default: 3
  baseDelay: number; // ms, default: 1000
  maxDelay: number; // ms, default: 30000
  backoffMultiplier: number; // default: 2
  retryableErrors: RegExp[]; // patterns that trigger retry
}

const DEFAULT_RETRY_CONFIG: RetryConfig = {
  maxAttempts: 3,
  baseDelay: 1000,
  maxDelay: 30000,
  backoffMultiplier: 2,
  retryableErrors: [/ECONNREFUSED/, /ETIMEDOUT/, /ENOTFOUND/, /timeout/i],
};

async function withRetry<T>(
  fn: () => Promise<T>,
  config: RetryConfig = DEFAULT_RETRY_CONFIG,
): Promise<T> {
  let lastError: Error | undefined;

  for (let attempt = 1; attempt <= config.maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error as Error;

      const isRetryable = config.retryableErrors.some((p) =>
        p.test(lastError!.message),
      );
      if (!isRetryable || attempt === config.maxAttempts) {
        throw lastError;
      }

      const delay = Math.min(
        config.baseDelay * Math.pow(config.backoffMultiplier, attempt - 1),
        config.maxDelay,
      );
      await new Promise((r) => setTimeout(r, delay));
    }
  }

  throw lastError;
}
```

## E2.8 Error Recovery

```typescript
type RecoveryStrategy = "fallback" | "retry" | "degrade" | "escalate";

interface ErrorRecoveryConfig {
  strategy: RecoveryStrategy;
  fallback?: () => unknown;
  maxRetries: number;
  escalateOnFailure: boolean;
}

const ERROR_RECOVERY_STRATEGIES: Record<string, ErrorRecoveryConfig> = {
  memory_full: { strategy: "degrade", maxRetries: 0, escalateOnFailure: true },
  search_timeout: { strategy: "retry", maxRetries: 2, escalateOnFailure: true },
  skill_load_error: {
    strategy: "fallback",
    maxRetries: 1,
    escalateOnFailure: false,
  },
  agent_handoff_failed: {
    strategy: "retry",
    maxRetries: 3,
    escalateOnFailure: true,
  },
};
```

---

# Part F: ARCHITECTURE DECISIONS

## F1: Features NOT Needed

| Feature        | Reason                            |
| -------------- | --------------------------------- |
| MCP Server     | Platform-native tools sufficient  |
| Vector Search  | BM25 sufficient for retrieval     |
| Smart Chunking | Not required for current use case |
| RRF            | Single search type sufficient     |

## F2: Features ADOPTED

| Feature          | Implementation                   |
| ---------------- | -------------------------------- |
| Storage          | SQLite + FTS5                    |
| Memory scopes    | 4 (session/user/shared/private)  |
| Memory tiers     | 3 (hot/warm/cold) × 3 levels = 9 |
| Skill metadata   | skills.json                      |
| Skill routing    | Jaccard (10% threshold)          |
| Platform hooks   | 5 hooks                          |
| Token thresholds | 13k/33k/70k/100k                 |

## F3: Security Integration (Per Phase)

| Phase | Module             | Security Tasks                                                                                           |
| ----- | ------------------ | -------------------------------------------------------------------------------------------------------- |
| 1     | Project Foundation | Input schema validation (Zod), dependency audit, **token threshold monitoring**, **context file linter** |
| 2     | Memory Module      | SQL injection prevention, scope isolation, query parameterization                                        |
| 3     | Search Module      | Search query sanitization, path traversal prevention                                                     |
| 4     | Skills System      | Skill manifest validation, trigger pattern sanitization                                                  |
| 5     | Agents             | Agent message validation, handoff protocol verification                                                  |
| 6     | Quality Gates      | Dangerous pattern detection, rate limiting, circuit breakers, retry limits                               |
| 7     | Hooks Runtime      | Hook input validation, output sanitization                                                               |
| 8A    | Hooks Governance   | Policy config validation, strict-mode/profile migration checks, audit redaction                          |
| 8B    | Skill Catalog      | Skill content sanitization                                                                               |
| 9     | Testing            | Security test cases                                                                                      |

## F3.1: Token Threshold Monitoring

> **Critical**: Context overflow is the primary failure mode. Token monitoring is foundational infrastructure, NOT a quality gate.

```typescript
interface TokenThresholds {
  safe: 13000; // ~65% of 20k window - safe operating range
  caution: 33000; // ~80% of 40k window - trigger cleanup
  warning: 70000; // ~70% of 100k window - force context compression
  critical: 100000; // Near window limit - block new context additions
}

const TOKEN_THRESHOLDS = {
  safe: 13000,
  caution: 33000,
  warning: 70000,
  critical: 100000,
};

function getTokenLevel(
  tokens: number,
): "safe" | "caution" | "warning" | "critical" {
  if (tokens >= TOKEN_THRESHOLDS.critical) return "critical";
  if (tokens >= TOKEN_THRESHOLDS.warning) return "warning";
  if (tokens >= TOKEN_THRESHOLDS.caution) return "caution";
  return "safe";
}

const TOKEN_RECOVERY_STRATEGIES: Record<string, () => Promise<void>> = {
  caution: async () => {
    /* Trigger lightweight cleanup: session state pruning */
  },
  warning: async () => {
    /* Aggressive cleanup: compress memory, summarize older entries */
  },
  critical: async () => {
    /* Emergency: block new context, force summary of all memories */
  },
};
```

## F3.2: Context File Linter

Validates PLAN.md, KNOWLEDGE.md structure on startup to prevent malformed markdown from breaking context engineering:

````typescript
interface ContextFileRule {
  file: string;
  requiredSections: string[];
  validateHeadingDepth: boolean;
  maxLineLength: number;
}

const CONTEXT_FILE_RULES: ContextFileRule[] = [
  { file: 'PLAN.md', requiredSections: ['# Part'], validateHeadingDepth: true, maxLineLength: 120 },
  { file: 'KNOWLEDGE.md', requiredSections: ['# Part'], validateHeadingDepth: true, maxLineLength: 120 },
];

function validateContextFiles(): { valid: boolean; errors: string[] } {
  // Check file exists
  // Validate required sections present
  // Check heading depth (no skipping levels)
  // Check line length limits
  // Validate YAML frontmatter syntax
}
``` |

## F4: Reliability Features

| Feature | Implementation |
|---------|---------------|
| Circuit Breaker | Failure threshold, recovery timeout, half-open attempts |
| Retry Limits | Max attempts, exponential backoff, retryable error patterns |
| Error Recovery | Fallback, retry, degrade, escalate strategies |

## F4.1: Observability & Debug CLI

Structured logging and debugging tools for production troubleshooting:

```typescript
interface LogEntry {
  timestamp: string;
  level: 'debug' | 'info' | 'warn' | 'error';
  runId: string;
  agentId?: string;
  stage?: string;
  message: string;
  data?: Record<string, unknown>;
}

const LOG_LEVELS = {
  DEBUG: 0,
  INFO: 1,
  WARN: 2,
  ERROR: 3,
};

function log(entry: LogEntry): void {
  // Structured JSON logging for machine parsing
  // Optional: OpenTelemetry export
}

const DEBUG_COMMANDS = [
  'agent-p debug memory',           // Show memory state
  'agent-p debug search',           // Show search pipeline results
  'agent-p debug skills',           // Show skill activation scores
  'agent-p debug tokens',           // Show current token usage
  'agent-p debug hooks',            // Show hook execution history
];
````

## F4.2: Enhanced Security

### Expanded Dangerous Patterns

The base 77 patterns are insufficient for production. Add configurable blocklist:

```typescript
const DANGEROUS_PATTERNS = {
  file_destruction: [
    /rm\s+-rf\s+\//, // rm -rf /
    /rm\s+-rf\s+\.\*/, // rm -rf .*
    /del\s+\/[fqs]\s+\//, // Windows del /f /s /q
    /format\s+[a-z]:/i, // format c:
    /shred\s+-u/, // shred -u
  ],
  data_destruction: [
    /DROP\s+TABLE\s+[IF\s+EXISTS]?/i, // DROP TABLE
    /DELETE\s+FROM\s+\w+\s*;?\s*$/i, // DELETE FROM without WHERE
    /TRUNCATE\s+TABLE/i, // TRUNCATE TABLE
    /DROP\s+DATABASE/i, // DROP DATABASE
  ],
  credential_exposure: [
    /--\s*password\s*=\s*['"][^/'"]+['"]/i,
    /api[_-]?key\s*[=:]\s*['"][^/'"]+['"]/i,
    /secret[_-]?key\s*[=:]\s*['"][^/'"]+['"]/i,
    /\.env(?:\.\w+)?\s*$/, // .env files
  ],
  network_exposure: [
    /curl\s+.*\s+http/, // curl http
    /wget\s+.*\s+http/, // wget http
    /nc\s+-[elvp]/, // netcat
    /exec\s*\(\s*['"]rm/i, // exec('rm
  ],
  privilege_escalation: [
    /chmod\s+777/,
    /chown\s+\w+:\w+\s+\//,
    /sudo\s+rm/,
    /:\(\)\{:\|:&\};:/, // Fork bomb
  ],
};

const PATTERN_SETS = {
  minimal: DANGEROUS_PATTERNS.file_destruction,
  standard: ["file_destruction", "data_destruction", "credential_exposure"],
  paranoid: Object.keys(DANGEROUS_PATTERNS),
};
```

### Dry-Run Mode

PreToolUse hook can operate in logging-only mode without blocking:

```typescript
interface HookConfig {
  mode: "enforce" | "dry-run" | "disabled";
  logOnlyOnDryRun: boolean;
}

const HOOK_CONFIG: HookConfig = {
  mode: process.env.AGENT_P_DRY_RUN === "true" ? "dry-run" : "enforce",
  logOnlyOnDryRun: true,
};

function preToolUse(tool: string, args: unknown): HookResult {
  if (HOOK_CONFIG.mode === "disabled") {
    return { allowed: true };
  }

  const blocked = checkDangerousPatterns(tool, args);

  if (blocked) {
    if (HOOK_CONFIG.mode === "dry-run") {
      log({ level: "warn", message: `Would block: ${tool}`, data: { args } });
      return { allowed: true }; // Allow but log
    }
    return { allowed: false, reason: `Dangerous pattern detected: ${blocked}` };
  }

  return { allowed: true };
}
```

## F5: Multi-Agent Orchestration

### Team Roles

| Role            | Purpose                  | From Source |
| --------------- | ------------------------ | ----------- |
| **Lead**        | Coordinates overall task | agents-main |
| **Reviewer**    | Quality analysis         | agents-main |
| **Debugger**    | Issue identification     | agents-main |
| **Implementer** | Code generation          | agents-main |

### Model Routing

> Configurable auto-select model based on task complexity (platform-agnostic)

```typescript
interface ModelProvider {
  name: string; // e.g., 'claude', 'openai', 'gemini'
  apiKey?: string; // optional, can use env var
  baseUrl?: string; // for custom endpoints
}

interface ModelTier {
  id: string; // e.g., 'fast', 'balanced', 'deep'
  model: string; // e.g., 'haiku', 'sonnet', 'opus' or 'gpt-4o-mini'
  maxTokens: number;
  costPer1k: number;
}

interface RoutingRule {
  action: string[]; // e.g., ['lookup', 'read', 'search']
  modelTier: string; // references ModelTier.id
  complexity: "low" | "medium" | "high";
}

interface ModelRoutingConfig {
  provider: ModelProvider;
  tiers: ModelTier[];
  defaultTier: string;
  routing: RoutingRule[];
  complexityDetector?: (task: string) => "low" | "medium" | "high";
}

const defaultConfig: ModelRoutingConfig = {
  provider: { name: "claude" },
  tiers: [
    { id: "fast", model: "haiku", maxTokens: 4096, costPer1k: 0.00025 },
    { id: "balanced", model: "sonnet", maxTokens: 8192, costPer1k: 0.003 },
    { id: "deep", model: "opus", maxTokens: 200000, costPer1k: 0.015 },
  ],
  defaultTier: "balanced",
  routing: [
    {
      action: ["lookup", "read", "search", "list"],
      modelTier: "fast",
      complexity: "low",
    },
    {
      action: ["implement", "refactor", "test", "edit"],
      modelTier: "balanced",
      complexity: "medium",
    },
    {
      action: ["architect", "debug", "review", "plan"],
      modelTier: "deep",
      complexity: "high",
    },
  ],
};
```

**Usage:**

```typescript
const router = new ModelRouter(config);
const selectedModel = router.select("implement"); // returns 'sonnet'
const selectedModel = router.select("architect"); // returns 'opus'
```

### File Ownership

> One agent owns each file for clear accountability

```typescript
interface FileOwnership {
  path: string;
  ownerAgent: string;
  lastModified: number;
}
```

### Checkpoint Workflows

> Human-in-the-loop approval gates

| Checkpoint     | Trigger        | Action                      |
| -------------- | -------------- | --------------------------- |
| Design Review  | After scout    | Human approves design       |
| Implementation | After builder  | Human approves code         |
| Final Review   | After verifier | Human approval for delivery |

---

# Part FB: Dependency Injection Container

> **Purpose**: Decouple modules for testability and runtime swapping

## FB1: Container API

```typescript
interface Container {
  register<T>(token: Token<T>, factory: () => T): void;
  registerSingleton<T>(token: Token<T>, factory: () => T): void;
  resolve<T>(token: Token<T>): T;
  resolveOr<T>(token: Token<T>, fallback: T): T;
}

type Token<T> = string & { __type: T };
```

## FB2: Registered Tokens

| Token            | Implementation        | Purpose                        |
| ---------------- | --------------------- | ------------------------------ |
| `MemoryManager`  | `TieredMemoryManager` | Tiered storage (hot/warm/cold) |
| `SearchEngine`   | `HybridSearchEngine`  | 4-stage search pipeline        |
| `SkillRegistry`  | `SkillRegistry`       | Skill loading & activation     |
| `SkillActivator` | `SkillActivator`      | Skill matching & routing       |
| `EventBus`       | `EventBus`            | Agent communication (optional) |
| `Config`         | `AgentPConfig`        | Runtime configuration          |

## FB2.1: EventBus (Optional)

> **Note**: EventBus is optional for MVP. Direct HandoffPayload is used for sequential D3 workflow. Add EventBus if parallel agent execution or complex async flows are needed.

```typescript
interface AgentEvent {
  type: "task.assigned" | "task.completed" | "task.failed" | "review.requested";
  source: string;
  target: string;
  payload: HandoffPayload;
  timestamp: number;
}

type EventHandler = (event: AgentEvent) => void | Promise<void>;

class EventBus {
  private handlers: Map<string, EventHandler[]> = new Map();

  on(type: string, handler: EventHandler): void {
    const existing = this.handlers.get(type) || [];
    this.handlers.set(type, [...existing, handler]);
  }

  off(type: string, handler: EventHandler): void {
    const existing = this.handlers.get(type) || [];
    this.handlers.set(
      type,
      existing.filter((h) => h !== handler),
    );
  }

  emit(event: AgentEvent): void {
    const handlers = this.handlers.get(event.type) || [];
    handlers.forEach((h) => h(event));
  }
}
```

## FB3: Usage Pattern

```typescript
// Define tokens
const MEMORY_MANAGER = "MemoryManager" as Token<MemoryManager>;
const SEARCH_ENGINE = "SearchEngine" as Token<SearchEngine>;

// Register factories
container.register(MEMORY_MANAGER, () => new TieredMemoryManager(config));
container.registerSingleton(SEARCH_ENGINE, () => new HybridSearchEngine());

// Resolve in modules
class AgentService {
  constructor(
    private memory = container.resolve(MEMORY_MANAGER),
    private search = container.resolve(SEARCH_ENGINE),
  ) {}
}
```

## FB4: Testing with Mocks

```typescript
// Test setup
const mockMemory = createMock<MemoryManager>();
const mockSearch = createMock<SearchEngine>();

container.register(MEMORY_MANAGER, () => mockMemory);
container.register(SEARCH_ENGINE, () => mockSearch);

// Test agent
const agent = container.resolve(AgentService);
await agent.execute(task);

// Assert
expect(mockMemory.save).toHaveBeenCalled();
```

## FB5: Degradation Mode Support

The container supports runtime swapping for graceful degradation:

```typescript
const determineStorageMode = (): Token<MemoryManager> => {
  if (!avail.sqlite) return IN_MEMORY_MANAGER;
  return TIERED_MANAGER;
};

container.register(MEMORY_MANAGER, () => {
  const token = determineStorageMode();
  return container.resolve(token);
});
```

---

# Part FC: Configuration Schema

> **Purpose**: Unified, validated configuration using Zod

## FC1: Zod Schema

```typescript
import { z } from "zod";

const AgentPConfig = z.object({
  expertise: z
    .object({
      governance: z
        .object({
          max_entries: z.number().default(100),
          warn_entries: z.number().default(150),
          hard_limit: z.number().default(200),
        })
        .default({}),
      shelf_life: z
        .object({
          tactical: z.number().default(14),
          observational: z.number().default(30),
        })
        .default({}),
    })
    .default({}),

  search: z
    .object({
      stages: z
        .object({
          treesitter: z
            .object({
              mode: z
                .enum(["required", "optional", "disabled"])
                .default("optional"),
              threshold: z.number().default(20),
              timeout_ms: z.number().default(500),
            })
            .default({}),
          bm25: z
            .object({
              enabled: z.boolean().default(true),
              k1: z.number().default(1.5),
              b: z.number().default(0.75),
            })
            .default({}),
          jaccard: z
            .object({
              enabled: z.boolean().default(true),
              threshold: z.number().default(0.1),
            })
            .default({}),
        })
        .default({}),
    })
    .default({}),

  workflow: z
    .object({
      default: z.enum(["static", "dynamic", "quick"]).default("dynamic"),
      static_override: z.boolean().default(true),
      quick_threshold: z.number().default(3),
    })
    .default({}),

  memory: z
    .object({
      hot: z
        .object({
          maxSize: z.number().default(10 * 1024 * 1024),
          ttlMs: z.number().default(5 * 60 * 1000),
          maxEntries: z.number().default(1000),
        })
        .default({}),
      warm: z
        .object({
          maxEntries: z.number().default(10000),
          vacuumInterval: z.number().default(24 * 60 * 60 * 1000),
        })
        .default({}),
      cold: z
        .object({
          maxAgeDays: z.number().default(30),
          archivePath: z.string().default(".agent-p/archives"),
        })
        .default({}),
    })
    .default({}),

  hooks: z
    .object({
      enabled: z.boolean().default(true),
      preToolUse: z.boolean().default(true),
      postToolUse: z.boolean().default(true),
      sessionStart: z.boolean().default(true),
      stop: z.boolean().default(true),
    })
    .default({}),

  telemetry: z
    .object({
      enabled: z.boolean().default(true),
      traceErrors: z.boolean().default(true),
      sampleRate: z.number().default(1.0),
    })
    .default({}),

  agents: z
    .object({
      expert: z
        .object({
          enabled: z.boolean().default(true),
          maxRetries: z.number().default(3),
          timeoutMs: z.number().default(30000),
        })
        .default({}),
      scout: z
        .object({
          enabled: z.boolean().default(true),
          maxRetries: z.number().default(2),
          timeoutMs: z.number().default(15000),
        })
        .default({}),
      builder: z
        .object({
          enabled: z.boolean().default(true),
          maxRetries: z.number().default(2),
          timeoutMs: z.number().default(30000),
        })
        .default({}),
      tester: z
        .object({
          enabled: z.boolean().default(true),
          maxRetries: z.number().default(2),
          timeoutMs: z.number().default(30000),
        })
        .default({}),
      reviewer: z
        .object({
          enabled: z.boolean().default(true),
          maxRetries: z.number().default(1),
          timeoutMs: z.number().default(15000),
        })
        .default({}),
      verifier: z
        .object({
          enabled: z.boolean().default(true),
          maxRetries: z.number().default(2),
          timeoutMs: z.number().default(20000),
        })
        .default({}),
    })
    .default({}),
});

export type AgentPConfig = z.infer<typeof AgentPConfig>;
```

## FC2: Config File Structure

```yaml
# .agent-p/config.yaml
version: "0.0.1"

expertise:
  governance:
    max_entries: 100
    warn_entries: 150
    hard_limit: 200
  shelf_life:
    tactical: 14
    observational: 30

search:
  stages:
    treesitter:
      mode: optional
      threshold: 20
      timeout_ms: 500
    bm25:
      enabled: true
    jaccard:
      enabled: true
      threshold: 0.1

workflow:
  default: dynamic
  static_override: true
  quick_threshold: 3

memory:
  hot:
    maxSize: 10485760
    ttlMs: 300000
    maxEntries: 1000
  warm:
    maxEntries: 10000
  cold:
    maxAgeDays: 30
    archivePath: .agent-p/archives

hooks:
  enabled: true
  preToolUse: true
  postToolUse: true
  sessionStart: true
  stop: true
  notification: true
  policy:
    profile: balanced
    strictMode: false
    escalationThreshold: 0.7
    riskyTools: [bash, write, webfetch]
    sensitivePatterns: [api_key, token, password, secret]
    categoryOverrides: {}
    toolOverrides: {}
    preToolUseDefaultDecision: allow
    postToolUseDefaultDecision: allow
    stopDefaultDecision: allow
  audit:
    enabled: true
    redactSensitive: true
    maxPreviewChars: 2000

telemetry:
  enabled: true
  traceErrors: true
  sampleRate: 1.0

agents:
  expert:
    enabled: true
    maxRetries: 3
    timeoutMs: 30000
  scout:
    enabled: true
    maxRetries: 2
    timeoutMs: 15000
  builder:
    enabled: true
    maxRetries: 2
    timeoutMs: 30000
  tester:
    enabled: true
    maxRetries: 2
    timeoutMs: 30000
  reviewer:
    enabled: true
    maxRetries: 1
    timeoutMs: 15000
  verifier:
    enabled: true
    maxRetries: 2
    timeoutMs: 20000
```

## FC3: Loading & Validation

```typescript
import { z } from "zod";
import * as yaml from "yaml";
import { readFileSync } from "fs";

const CONFIG_PATH = ".agent-p/config.yaml";

export class ConfigValidationError extends Error {
  constructor(public errors: z.ZodError) {
    super("Config validation failed");
    this.name = "ConfigValidationError";
  }
}

export const loadConfig = (path: string = CONFIG_PATH): AgentPConfig => {
  try {
    const raw = yaml.parse(readFileSync(path, "utf-8"));
    return AgentPConfig.parse(raw);
  } catch (error) {
    if (error instanceof z.ZodError) {
      throw new ConfigValidationError(error);
    }
    console.warn("No config file found, using defaults");
    return AgentPConfig.parse({});
  }
};

export const config = loadConfig();
```

## FC4: Usage in Code

```typescript
import { config } from "./utils/config";

// Access config values
const treesitterMode = config.search.stages.treesitter.mode;
const hotTierSize = config.memory.hot.maxSize;

if (config.search.stages.jaccard.enabled) {
  // Run Jaccard stage
}
```

---

# Part FA: System-Level Error Handling

> **Philosophy**: Graceful degradation over complete failure. The system should remain operational even when subsystems fail.

## FA1: Failure Categories

| Category                  | Examples                                | Default Behavior                      |
| ------------------------- | --------------------------------------- | ------------------------------------- |
| **External Tool Missing** | `rg` not installed, `tree-sitter` fails | Fall back to native FS search         |
| **Storage Failure**       | SQLite corruption, disk full            | Switch to in-memory mode, warn user   |
| **Memory Exhaustion**     | OOM, cache overflow                     | Evict cold tier, reduce hot tier size |
| **Network Failure**       | Remote skill fetch fails                | Use cached/local skills only          |
| **Permission Error**      | Cannot write to project dirs            | Prompt user, use temp directory       |

## FA2: Tool Availability Fallbacks

| Primary Tool   | Fallback 1                     | Fallback 2           |
| -------------- | ------------------------------ | -------------------- |
| `rg` (Ripgrep) | Node.js `fs.readFileSync` glob | Native String.search |
| `tree-sitter`  | Regex-based parsing            | Skip AST analysis    |
| SQLite         | In-memory Map                  | File-based JSON      |

### SQLite Driver Strategy

> **Primary**: `better-sqlite3` (local SQLite)
> **Fallback**: `sql.js` (pure JavaScript, works everywhere)
> **Future**: `@libsql/client` (for Turso/remote support)

#### FA2.4: Cross-Platform SQLite Strategy

better-sqlite3 has native bindings that can fail on some CI/CD environments. Use sql.js as fallback.

**Dependencies:**

```json
{
  "dependencies": {
    "better-sqlite3": "^12.6.2"
  },
  "optionalDependencies": {
    "sql.js": "^1.12.0"
  }
}
```

**Driver Detection & Initialization:**

```typescript
import initSqlJs from "sql.js";
import { existsSync, readFileSync, writeFileSync } from "fs";
import { resolve } from "path";

type SqliteDriver = "better-sqlite3" | "sql.js";

interface SqliteConfig {
  driver: SqliteDriver;
  isFallback: boolean;
}

interface DatabaseAdapter {
  run(sql: string, params?: unknown[]): void;
  get<T>(sql: string, params?: unknown[]): T | undefined;
  all<T>(sql: string, params?: unknown[]): T[];
  close(): void;
}

const DB_PATH = resolve(".agent-p/agent-p.db");

const detectSqliteDriver = async (): Promise<SqliteConfig> => {
  try {
    await import("better-sqlite3");
    return { driver: "better-sqlite3", isFallback: false };
  } catch {
    return { driver: "sql.js", isFallback: true };
  }
};

class DatabaseManager {
  private db: DatabaseAdapter | null = null;
  private config: SqliteConfig | null = null;
  private dbPath: string = DB_PATH;

  async initialize(): Promise<void> {
    this.config = await detectSqliteDriver();

    if (this.config.driver === "better-sqlite3") {
      const Database = (await import("better-sqlite3")).default;
      const db = new Database(this.dbPath);

      this.db = {
        run: (sql, params) => db.prepare(sql).run(params),
        get: (sql, params) => db.prepare(sql).get(params) as T | undefined,
        all: (sql, params) => db.prepare(sql).all(params) as T[],
        close: () => db.close(),
      };
    } else {
      const SQL = await initSqlJs();

      let db: SqlJsDatabase;
      if (existsSync(this.dbPath)) {
        const fileBuffer = readFileSync(this.dbPath);
        db = new SQL.Database(fileBuffer);
      } else {
        db = new SQL.Database();
      }

      this.db = {
        run: (sql, params) => db.run(sql, params),
        get: (sql, params) => {
          const stmt = db.prepare(sql);
          stmt.bind(params);
          if (stmt.step()) {
            const row = stmt.getAsObject();
            stmt.free();
            return row as T;
          }
          stmt.free();
          return undefined;
        },
        all: (sql, params) => {
          const results: T[] = [];
          const stmt = db.prepare(sql);
          stmt.bind(params);
          while (stmt.step()) {
            results.push(stmt.getAsObject() as T);
          }
          stmt.free();
          return results;
        },
        close: () => {
          this.persist();
          db.close();
        },
      };
    }
  }

  persist(): void {
    if (this.config?.driver === "sql.js" && this.db) {
      const sqlJsDb = (this.db as any).db as SqlJsDatabase;
      if (sqlJsDb) {
        const data = sqlJsDb.export();
        const buffer = Buffer.from(data);
        writeFileSync(this.dbPath, buffer);
      }
    }
  }

  getDatabase(): DatabaseAdapter {
    if (!this.db) throw new Error("Database not initialized");
    return this.db;
  }

  async close(): Promise<void> {
    if (this.db) {
      this.persist();
      this.db.close();
      this.db = null;
    }
  }
}
```

**CI/CD Compatibility:**

| OS                  | Native Binding | Works? | Fallback   |
| ------------------- | -------------- | ------ | ---------- |
| Windows (x64)       | better-sqlite3 | ✓      | sql.js     |
| macOS (arm64)       | better-sqlite3 | ✓      | sql.js     |
| macOS (x64)         | better-sqlite3 | ✓      | sql.js     |
| Linux (glibc)       | better-sqlite3 | ✓      | sql.js     |
| Linux (Alpine/musl) | better-sqlite3 | ✗      | **sql.js** |

**Build Script (postinstall):**

```json
{
  "scripts": {
    "postinstall": "pnpm run build:sqlite",
    "build:sqlite": "pnpm bin/build-sqlite.ts"
  }
}
```

**bin/build-sqlite.ts:**

```typescript
import { existsSync } from "fs";
import { execSync } from "child_process";

const rebuildSqlite = () => {
  if (!existsSync("node_modules/better-sqlite3")) return;

  try {
    console.log("Verifying better-sqlite3 bindings...");
    require("better-sqlite3");
    console.log("✓ better-sqlite3 ready");
  } catch (error) {
    console.warn("⚠ better-sqlite3 failed, sql.js will be used as fallback");
  }
};

rebuildSqlite();
```

---

## FA3: Database Corruption Recovery

| Scenario             | Detection           | Recovery                       |
| -------------------- | ------------------- | ------------------------------ |
| SQLite lock timeout  | `SQLITE_BUSY` error | Retry with exponential backoff |
| Corruption detected  | `SQLITE_CORRUPT`    | Restore from SQLite backup     |
| WAL checkpoint fails | `SQLITE_FULL`       | Vacuum DB, warn user           |

### SQLite Backup Strategy

```typescript
interface BackupConfig {
  enabled: boolean;
  intervalMs: number; // Default: 24 hours
  maxBackups: number; // Default: 7
  backupPath: string; // Default: .agent-p/backups/
}

const performBackup = async (
  db: Database,
  config: BackupConfig,
): Promise<void> => {
  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
  const backupFile = `${config.backupPath}/agent-p-${timestamp}.db`;

  // Use SQLite's backup API
  await db.backup(backupFile);

  // Cleanup old backups
  const backups = await fs.readdir(config.backupPath);
  if (backups.length > config.maxBackups) {
    const oldest = backups.sort()[0];
    await fs.remove(`${config.backupPath}/${oldest}`);
  }
};

const restoreFromBackup = async (
  db: Database,
  backupPath: string,
): Promise<void> => {
  await db.close();
  await fs.copy(backupPath, db.path);
  await db.open();
};

const handleDbError = async (error: Error): Promise<void> => {
  if (error.message.includes("SQLITE_CORRUPT")) {
    const backups = await fs.readdir(".agent-p/backups/");
    if (backups.length > 0) {
      const latest = backups.sort().pop();
      await restoreFromBackup(db, `.agent-p/backups/${latest}`);
      logger.warn("Database restored from backup");
    } else {
      logger.error("No backups available, creating fresh database");
    }
  } else if (error.message.includes("SQLITE_FULL")) {
    await vacuumDatabase();
    logger.warn("Database vacuumed");
  }
};
```

## FA4: Memory Pressure Handling

| Threshold      | Action                           |
| -------------- | -------------------------------- |
| >90% heap used | Flush hot tier to warm           |
| >80% heap used | Stop accepting new cache entries |
| >70% heap used | Reduce LRU cache size by 50%     |

```typescript
const checkMemoryPressure = (): void => {
  const used = process.memoryUsage();
  const heapUsedPercent = (used.heapUsed / used.heapTotal) * 100;

  if (heapUsedPercent > 90) {
    flushHotToWarm();
  } else if (heapUsedPercent > 80) {
    disableNewCacheEntries();
  }
};
```

## FA5: Graceful Degradation Modes

| Mode         | Description                                               |
| ------------ | --------------------------------------------------------- |
| **Full**     | All features operational                                  |
| **Minimal**  | Both SQLite and Ripgrep unavailable, basic in-memory only |
| **NoSearch** | Ripgrep/BM25 unavailable, use basic text matching         |
| **InMemory** | SQLite unavailable, use Map-based storage                 |
| **Offline**  | No remote skills, local skills only                       |

```typescript
type DegradationMode = "full" | "minimal" | "noSearch" | "inMemory" | "offline";

const determineMode = (avail: ToolAvailability): DegradationMode => {
  if (!avail.sqlite && !avail.rg) return "minimal";
  if (!avail.sqlite) return "inMemory";
  if (!avail.rg) return "noSearch";
  return "full";
};
```

## FA6: Startup Health Check

Run at CLI startup to determine operational mode:

```typescript
const startupHealthCheck = async (): Promise<StartupReport> => {
  const report: StartupReport = {
    mode: "full",
    issues: [],
    recommendations: [],
  };

  const avail = await checkToolAvailability();
  const platform = process.platform;

  const getInstallCommand = (tool: string): string => {
    switch (platform) {
      case "win32":
        return `winget install ${tool} or scoop install ${tool}`;
      case "darwin":
        return `brew install ${tool}`;
      case "linux":
        return `apt install ${tool} or yum install ${tool}`;
      default:
        return `Install ${tool} using your package manager`;
    }
  };

  if (!avail.rg) {
    report.issues.push("Ripgrep not found - search will use fallback");
    report.recommendations.push(
      `Install ripgrep: ${getInstallCommand("ripgrep")}`,
    );
  }

  if (!avail.treeSitter) {
    report.issues.push("Tree-sitter not available - AST analysis disabled");
  }

  if (avail.diskSpace < 100) {
    report.issues.push("Low disk space - database may fail");
    report.recommendations.push("Free up disk space");
  }

  report.mode = determineMode(avail);
  return report;
};
```

---

## G1: Key References

| Project             | Purpose                 |
| ------------------- | ----------------------- |
| knowledgebase       | Memory infrastructure   |
| python-expert-agent | Legacy Python version   |

---

# Part H: API REFERENCE

## H1: Memory API

```typescript
// Create memory manager
const mem = new MemoryManager({
  appId: "agent-p",
  userId: "user-123",
  runId: "run-456",
});

// Session scope
mem.session.save(key, value);
mem.session.load(key);
mem.session.delete(key);

// User scope
mem.user.set(key, value);
mem.user.get(key);
mem.user.delete(key);

// Shared scope
mem.shared.add(value);
mem.shared.search(query);
mem.shared.list();

// Private scope
mem.private(agentId).add(value);
mem.private(agentId).search(query);
```

## H2: Search API

```typescript
// Create search engine
const search = new SearchEngine();

// Query
const results = await search.query("fastapi async");
// Returns: { files: FileResult[], skills: SkillResult[] }
```

## H3: Skills API

```typescript
// Create skill activator
const activator = new SkillActivator();

// Activate skills for task
const skills = activator.activate("Create a FastAPI endpoint");
// Returns: Skill[]
```

---

# Part I: TOKEN THRESHOLDS

| Token Count | Action                    | Reason                       |
| ----------- | ------------------------- | ---------------------------- |
| < 13,000    | Continue session          | Peak performance             |
| 33,000      | Checkpoint progress       | Stability maintained         |
| 70,000      | Prepare for rotation      | Approaching limits           |
| 100,000+    | **Terminate and restart** | ~50% performance degradation |

---

## Deferred Track Activation Status (2026-03-06)

- Warm/cold memory tiers are active with deterministic lookup order `hot -> warm -> cold` and promotion from colder tiers.
- Search runtime is active as a 4-stage pipeline (`ripgrep -> tree-sitter -> BM25 -> Jaccard`) with best-effort Stage 2 fallback metadata.
- Skill catalog expansion is intentionally partial for this pass (`5/40` trial skills) with permission-aware filtering in suggest/load flows.

---

# Part J: IMPLEMENTATION CHECKLIST

## Phase 1: Project Foundation

- [x] Initialize package.json
- [x] Create tsconfig.json
- [x] Set up CLI entry point
- [x] Create main index.ts
- [x] Set up test directory

## Phase 2: Memory Module

- [x] Create memory store (SQLite + FTS5)
- [x] Implement session scope
- [x] Implement user scope
- [x] Implement shared scope
- [x] Implement private scope
- [x] Implement hot tier
- [x] Implement warm tier
- [x] Implement cold tier
- [x] Create MemoryManager API
- [x] Set up Drizzle migrations
- [x] SQL injection prevention
- [x] Scope isolation validation

## Phase 3: Search Module

- [x] Implement Ripgrep Stage 1
- [x] Implement Tree-sitter Stage 2
- [x] Implement BM25 Stage 3
- [x] Implement Jaccard Stage 4
- [x] Create Search API
- [x] Search query sanitization
- [x] Path traversal prevention

## Phase 4: Skills System

- [x] Create skills.json
- [x] Implement skill loader
- [x] Implement auto-activation
- [x] Implement skill registry
- [x] Add permission-aware agent allowlist filters

## Phase 5: Agents

- [x] Create expert (orchestrator)
- [x] Create scout subagent
- [x] Create builder subagent (scaffold)
- [x] Create tester subagent
- [x] Create reviewer subagent
- [x] Create verifier subagent

## Phase 6: Quality Gates

- [x] Implement Trust Gate
- [x] Implement Goal Gate
- [x] Implement Trust Score Calculator
- [x] Implement Dangerous Pattern Detection
- [x] Implement Rate Limiting
- [x] Implement Circuit Breaker
- [x] Implement Retry Limits
- [x] Implement Error Recovery

## Phase 7 + Phase 8A: Hooks Runtime + Governance

- [x] SessionStart hook
- [x] PreToolUse hook
- [x] PostToolUse hook
- [x] Stop hook
- [x] Notification hook
- [x] Shared HookPolicyEngine core
- [x] Policy profiles (`strict`, `balanced`, `permissive`)
- [x] Tool/category policy overrides
- [x] Backward-compatible `strictMode`/`profile` migration in config loader
- [x] Shared hook audit logger and sinks
- [x] `hooks.policy` config schema and defaults
- [x] `hooks.audit` config schema and defaults
- [x] CLI governance commands (`hooks:config`, `hooks:audit-log`)
- [x] CLI snapshot contracts for `hooks:config` and `hooks:audit-log`
- [x] Integration coverage for ordered JSONL audit lifecycle

## Phase 8B: Skill Catalog Expansion (40 Skills)

- [ ] Create 40 SKILL.md files (deferred)
- [ ] Configure triggers.json for each (in progress)
- [x] Curate and ship 5-skill trial catalog with permissions
- [x] Test auto-activation

## Phase 9: Testing

- [x] Set up Vitest
- [x] Memory module tests
- [x] Search module tests
- [x] Skills tests
- [x] Integration tests
- [x] Security test cases

---

# Part K: STORAGE OPTIONS EVALUATED

> Documents why the current storage stack was chosen over alternatives

## K1: Evaluated and Rejected

| Option                | Reason Rejected                                                                        |
| --------------------- | -------------------------------------------------------------------------------------- |
| **RocksDB**           | Native C++ bindings required; loses SQLite FTS5; overkill for CLI tool                 |
| **KeyV**              | No FTS support; lru-cache v11 is faster for in-memory; adds complexity without benefit |
| **hybrid-disk-cache** | Designed for file/object caching, not structured data with search requirements         |

## K2: Current Stack Rationale

| Component | Choice            | Reason                                            |
| --------- | ----------------- | ------------------------------------------------- |
| Hot tier  | lru-cache v11.2.6 | Fastest for in-memory LRU (not replaced)          |
| Warm tier | SQLite + FTS5     | Full-text search built-in, single source of truth |
| Cold tier | JSONL files       | Simple, portable, no native dependencies          |

---

# Part M: D3 (DESIGN-DEVELOP-DELIVER) WORKFLOW

> Combines best patterns from aura-frog (9-Phase TDD), fuska (3-reviewer panel), and agno (workflow engine)

## M0: Implementation Status (Current)

- Implemented:
  - `src/workflow/engine.ts` typed planning engine for the canonical 9-phase D3 flow
  - workflow mode resolution (`static`, `dynamic`, `quick`) with config-driven dynamic thresholding
  - analysis mode auto-detection (`quick` vs `deep`) using complexity thresholds
  - deterministic transition guard API for sequential phase advancement
  - runtime executor `src/workflow/executor.ts` for deterministic phase execution across subagents
  - checkpoint persistence `src/workflow/checkpoint-store.ts` with resumable session recovery
  - CLI command `agents:workflow [query]` for planning (`contractVersion: 1.0.0`) and execution/resume (`contractVersion: 1.1.0`)
  - cache-aware phase reuse with deterministic ordering and phase provenance (`runtime|cache|reindexed`)
  - cross-session planning artifact lifecycle integration for design-stage cache reuse when plan signatures match
  - planning artifact index hardening with stale-entry cleanup, corruption-safe fallback, and retention limit policy
  - stricter cache reuse validation for partial plan matches (complexity/skipped-phase parity + request hint drift rejection)
  - reindex replay controls from design-stage boundaries via CLI/runtime (`--reindex`)
  - checkpoint/session runtime metadata for cache hit/miss and reindex requested/applied state
  - CLI cache control via `--no-cache` while keeping planning-only behavior unchanged

## M1: Nine-Phase Workflow Overview

```
┌─────────────────────────────────────────────────────────────────────────────────┐
│                        D3 WORKFLOW ARCHITECTURE                                   │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                  │
│  DESIGN (Scout)          DEVELOP (Coder+Tester)       DELIVER (Verifier)       │
│  ═══════════════        ═══════════════════════       ════════════════════      │
│                                                                                  │
│  Phase 1: Understand   Phase 4: Develop (RED)    Phase 7: Review          │
│  Phase 2: Design       Phase 5: Build (GREEN)  Phase 8A/8B: Verify        │
│  Phase 3: Plan        Phase 6: Refactor       Phase 9: Deliver         │
│                                                                                  │
│         │                       │                         │                     │
│         ▼                       ▼                         ▼                     │
│  ┌─────────────┐         ┌─────────────┐          ┌─────────────┐            │
│  │    SCOUT    │────────▶│   BUILDER   │────────▶│  REVIEWER   │            │
│  │             │         │             │          │   PANEL     │            │
│  │  Context    │         │   TDD RED   │          │ (3-reviewer)│            │
│  │  Discovery   │         │             │          │             │            │
│  └─────────────┘         └─────────────┘          └──────┬──────┘            │
│         │                       │                         │                     │
│         │                 ┌─────▼─────┐                  │                     │
│         │                 │  TESTER   │                  │                     │
│         │                 │           │                  │                     │
│         │                 │ TDD GREEN │                  │                     │
│         │                 └─────┬─────┘                  │                     │
│         │                       │                         ▼                     │
│         │                 ┌─────▼─────┐          ┌──────────────┐             │
│         │                 │  BUILDER   │          │   VERIFIER   │             │
│         │                 │           │─────────▶│              │             │
│         │                 │  Refactor  │          │  End-to-End  │             │
│         │                 └─────────────┘          │   Testing    │             │
│         │                                             └──────┬───────┘             │
│         │                                                    │                    │
│         │                                              ┌─────▼──────┐             │
│         └─────────────────────────────────────────────▶│   DELIVER  │             │
│                                                         │            │             │
│                                                         │  Docs +    │             │
│                                                         │  Release   │             │
│                                                         └────────────┘             │
└─────────────────────────────────────────────────────────────────────────────────┘
```

## M2: Phase Details

| Phase | Name                        | Agent(s)                       | Purpose                                                | Output              |
| ----- | --------------------------- | ------------------------------ | ------------------------------------------------------ | ------------------- |
| 1     | **Understand**              | Scout                          | Gather context, analyze requirements, explore codebase | Context Report      |
| 2     | **Design**                  | Scout + Reviewer Panel (light) | Solution architecture, API design, data models         | Design Doc          |
| 3     | **Plan**                    | Scout                          | Create implementation plan, task breakdown, estimates  | PLAN.md update      |
| 4     | **Develop (RED)**           | Builder + Tester               | Write failing tests first                              | Failing test suite  |
| 5     | **Build (GREEN)**           | Builder                        | Implement to pass tests                                | Working code        |
| 6     | **Refactor (TDD REFACTOR)** | Builder + Reviewer             | Optimize code, improve structure                       | Clean code          |
| 7     | **Review**                  | 3-Reviewer Panel               | Multi-perspective validation                           | Review Report       |
| 8     | **Verify**                  | Verifier                       | End-to-end validation, integration testing             | Verification Report |
| 9     | **Deliver**                 | Verifier                       | Documentation, changelog, delivery                     | Release artifacts   |

## M3: Phase 1-3: Design (Scout Agent)

### Phase 1: Understand

```
Input: User request / task description
Actions:
  1. Explore project structure
  2. Analyze existing code patterns
  3. Identify dependencies and constraints
  4. Gather requirements context
  5. Search relevant skills for domain knowledge
Output: Context Report (structured)
```

### Phase 2: Design

```
Input: Context Report
Actions:
  1. Create solution architecture
  2. Design API/data models
  3. Define interfaces and contracts
  4. Light review with 1 reviewer
Output: Design Document
```

### Phase 3: Plan

```
Input: Design Document
Actions:
  1. Break down into implementable tasks
  2. Estimate complexity and time
  3. Identify dependencies
  4. Update PLAN.md with decisions
Output: Implementation Plan
```

## M4: Phase 4-6: Develop (Coder + Tester)

### Phase 4: Implement (TDD RED)

```
Input: Implementation Plan
TDD Approach:
  1. Write failing test FIRST
  2. Verify test fails (RED)
  3. Write minimal code to pass
  4. Verify test passes (GREEN)
  5. Refactor (REFACTOR)
Tools: {lang}-test, {lang}-linter, {lang}-type-checker
```

### Phase 5: Build (TDD GREEN)

```
Input: Failing tests
Actions:
  1. Implement features to pass tests
  2. Run full test suite
  3. Fix any regressions
  4. Ensure type safety ({lang}-type-checker)
Output: Working code that passes tests
```

### Phase 6: Refactor (TDD REFACTOR)

```
Input: Working code
Actions:
  1. Code cleanup and optimization
  2. Remove technical debt
  3. Improve readability
  4. Review with 1 reviewer
Output: Clean, maintainable code
```

## M5: Phase 7-9: Deliver (Reviewer Panel + Verifier)

### Phase 7: Review (3-Reviewer Panel)

> Pattern from fuska: Expert panel with 3 reviewers

```
Reviewers:
  1. Security Reviewer - vulnerability detection
  2. Quality Reviewer - code quality, patterns
  3. Completeness Reviewer - requirements coverage

Actions:
  1. Run security scan
  2. Check code coverage
  3. Verify requirements met
  4. Multi-perspective feedback
Output: Review Report with action items
```

### Phase 8A/8B: Verify

```
Input: Reviewed code
Actions:
  1. End-to-end testing
  2. Integration testing
  3. Performance benchmarking
  4. Trust score calculation
Output: Verification Report
```

### Phase 9: Deliver

```
Input: Verification Report
Actions:
  1. Update documentation
  2. Generate changelog
  3. Version bump
  4. Create release artifacts
Output: Deliverable package
```

## M6: Workflow Configuration

### Default Behavior: Dynamic Mode

> For **fresh products** (no legacy users), Dynamic mode is the default

| Mode        | Trigger             | Behavior                                              |
| ----------- | ------------------- | ----------------------------------------------------- |
| **dynamic** | Default             | Auto-detect complexity, route to appropriate workflow |
| **static**  | `--workflow=static` | Full 9-phase workflow always                          |
| **quick**   | `--workflow=quick`  | Skip phases 2, 6, 7 for simple tasks                  |

```yaml
# .agent-p/config.yaml
workflow:
  default: dynamic # fresh product: dynamic by default
  static_override: true # allow --workflow=static
  quick_threshold: 3 # files < 3 = quick mode
```

### Fresh Product Recommendations

> Based on knowledgebase research for fresh products (no legacy users)

| #   | Question            | Recommendation                  | Rationale                                           |
| --- | ------------------- | ------------------------------- | --------------------------------------------------- |
| 1   | Default vs Opt-in   | **Default = Dynamic**           | No user expectations to break                       |
| 2   | Index Caching       | **Cache by default** (24h TTL)  | Performance for repeated queries                    |
| 3   | Fallback Strategy   | **Silent fallback** to standard | Don't confuse new users with warnings               |
| 4   | Deep Mode Threshold | **Hybrid + Manual Override**    | Conservative auto-detect (15+ files OR 4+ patterns) |
| 5   | Index Type          | **Ripgrep-first + Jaccard**     | Phase 1: Simple, fast; PageIndex as Phase 2         |

### CLI Flags

```bash
# Workflow control
agent-p --workflow=static    # Force full 9-phase
agent-p --workflow=quick     # Quick mode for simple tasks
agent-p --workflow=dynamic   # Auto-detect (default)

# Cache control
agent-p --no-cache          # Disable caching
agent-p --reindex           # Force reindex
agent-p --clear-cache       # Clear cache and exit

# Mode control
agent-p --mode=deep         # Force deep analysis
agent-p --mode=quick       # Quick analysis only
```

## M7: Caching Strategy

### Cache Configuration

| Setting        | Default       | Override          |
| -------------- | ------------- | ----------------- |
| **Enabled**    | true          | `--no-cache`      |
| **TTL**        | 24 hours      | `--cache-ttl=1h`  |
| **Index Type** | Ripgrep-first | `--index=jaccard` |

### Cache Keys

```
cache_key = hash(
  project_path,
  file_patterns,
  index_type,
  timestamp // rounded to hour
)
```

### Cache Invalidation

| Trigger           | Action              |
| ----------------- | ------------------- |
| `--reindex`       | Force rebuild       |
| `--clear-cache`   | Delete and exit     |
| TTL expiry        | Auto-evict          |
| File modification | Invalidate affected |

## M8: Deep Mode vs Quick Mode

### Auto-Detection (Dynamic Mode)

| Condition                   | Mode  |
| --------------------------- | ----- |
| < 15 files AND < 4 patterns | Quick |
| 15+ files OR 4+ patterns    | Deep  |
| Explicit `--mode=deep`      | Deep  |
| Explicit `--mode=quick`     | Quick |

### Mode Characteristics

| Aspect           | Quick         | Deep           |
| ---------------- | ------------- | -------------- |
| **Search**       | Ripgrep only  | Full pipeline  |
| **Analysis**     | Surface level | AST + semantic |
| **Reviewers**    | 1             | 3              |
| **Verification** | Basic         | Full E2E       |

## M9: Knowledgebase References

| Reference               | File                                           | Lines | Purpose                           |
| ----------------------- | ---------------------------------------------- | ----- | --------------------------------- |
| Workflow automation     | `commands-main/workflows/workflow-automate.md` | 1343  | Workflow engine patterns          |
| Fresh project bootstrap | `overstory-main/src/commands/init.ts`          | -     | Ecosystem tools initialization    |
| Caching patterns        | `md files knowledge/KNOWLEDGE.md`              | -     | diskcache + SQLite tiered storage |

---

# Part H: EVALUATION & OBSERVABILITY

## H1: Evaluation Framework

### Agent Evaluation Metrics

| Metric           | What It Measures        | Collection Point       |
| ---------------- | ----------------------- | ---------------------- |
| **Trust Score**  | Output quality          | VERIFIER agent         |
| **Success Rate** | % tasks completed       | Handoff completion     |
| **Token Cost**   | Tokens per agent        | Per execution          |
| **Latency**      | Time per agent stage    | Execution timestamps   |
| **Retry Rate**   | Agent failure frequency | Circuit breaker events |

### Skill Evaluation Metrics

| Metric                  | What It Measures        | Collection Point    |
| ----------------------- | ----------------------- | ------------------- |
| **Activation Accuracy** | Correct trigger matches | Activation logger   |
| **Token Usage**         | Cost per skill          | Per activation      |
| **Helpfulness Score**   | User feedback           | Optional CLI rating |
| **Conflict Detection**  | Overlapping triggers    | Validator tool      |

### Trust Score Formula

From My-Jogyo (existing implementation):

```typescript
interface TrustComponents {
  statisticalRigor: number; // 30%
  evidenceQuality: number; // 25%
  metricVerification: number; // 20%
  completeness: number; // 15%
  methodology: number; // 10%
}

function calculateTrust(c: TrustComponents): number {
  return (
    c.statisticalRigor * 0.3 +
    c.evidenceQuality * 0.25 +
    c.metricVerification * 0.2 +
    c.completeness * 0.15 +
    c.methodology * 0.1
  );
}
```

### Progress Report Format

From awesome-claude-code-subagents:

```typescript
interface ProgressReport {
  agent: string;
  status: "idle" | "running" | "completed" | "failed";
  progress: number; // 0-100
  metrics: {
    tokens: number;
    latency_ms: number;
    retries: number;
  };
}
```

## H2: Observability Infrastructure

### Metrics Categories

| Category   | Metrics                                      |
| ---------- | -------------------------------------------- |
| **Tokens** | Current count, thresholds (13k/33k/70k/100k) |
| **Memory** | Hot/warm/cold tier usage, hit rates          |
| **Search** | Stage latency, result quality                |
| **Agents** | Execution time, success/fail                 |
| **Skills** | Activations, token cost                      |
| **Errors** | Error rates, circuit breaker state           |

### Storage

| Data Type        | Storage               | Retention    |
| ---------------- | --------------------- | ------------ |
| Session metrics  | SQLite (telemetry.db) | Session only |
| Historical stats | JSONL files           | 30 days      |
| Execution traces | JSONL (telemetry/)    | 7 days       |
| Agent evals      | JSONL (evals/)        | Permanent    |
| Skill evals      | JSONL (evals/)        | Permanent    |

### Storage Structure

```
.agent-p/
├── telemetry/              # Observability (tracing, tracking)
│   ├── sessions/
│   │   └── {run_id}.jsonl  # Session events
│   ├── metrics/
│   │   └── {date}.jsonl    # Daily aggregated metrics
│   └── traces/
│       └── {trace_id}.json # Execution traces
│
└── evals/                  # Evaluations & Scoring
    ├── agents/
    │   └── {agent_id}.jsonl    # Agent scores (trust, success)
    ├── subagents/
    │   └── {subagent_id}.jsonl # Subagent scores
    ├── skills/
    │   └── {skill_name}.jsonl  # Skill effectiveness
    └── feedback/
        └── feedback.jsonl      # User feedback
```

| Directory    | Purpose       | What's Tracked                              |
| ------------ | ------------- | ------------------------------------------- |
| `telemetry/` | Observability | Latency, traces, system metrics             |
| `evals/`     | Evaluation    | Trust scores, success rates, skill accuracy |

### Self-Learning Hook

From draft-claude.md - Extract patterns after successful tool calls:

```typescript
class SelfLearningHook {
  async onToolSuccess(
    tool: string,
    args: unknown,
    result: unknown,
    ctx: Context,
  ): Promise<void> {
    const skill = ctx.activeSkill || "general";
    const pattern = this.extractPattern(tool, args, result);
    await this.memory.knowledge.addPattern(skill, pattern);
    await this.metrics.increment(`tool_success.${tool}`);
  }

  async onToolFailure(
    tool: string,
    error: string,
    ctx: Context,
  ): Promise<void> {
    await this.memory.knowledge.addPattern(
      "failures",
      `${tool}: ${error.slice(0, 100)}`,
    );
    await this.metrics.increment(`tool_failure.${tool}`);
  }

  async onReviewFinding(finding: string, severity: string): Promise<void> {
    await this.memory.knowledge.addPattern(
      "anti-patterns",
      `[${severity}] ${finding}`,
    );
  }
}
```

## H3: Cost Tracking

From pydantic-deepagents - Per-run cost tracking:

```typescript
interface CostMetrics {
  runId: string;
  agentId: string;
  tokensIn: number;
  tokensOut: number;
  cost: number;
  duration_ms: number;
}

class CostTracker {
  private costs: CostMetrics[] = [];

  async track(
    agentId: string,
    tokensIn: number,
    tokensOut: number,
  ): Promise<void> {
    const cost = this.calculateCost(tokensIn, tokensOut);
    this.costs.push({
      runId: this.runId,
      agentId,
      tokensIn,
      tokensOut,
      cost,
      duration_ms: Date.now() - this.start,
    });
  }

  private calculateCost(tokensIn: number, tokensOut: number): number {
    const RATE_PER_1K = 0.003; // sonnet pricing
    return ((tokensIn + tokensOut) / 1000) * RATE_PER_1K;
  }

  getTotalCost(): number {
    return this.costs.reduce((sum, c) => sum + c.cost, 0);
  }
}
```

## H4: Debug CLI Commands

| Command                | Purpose                  |
| ---------------------- | ------------------------ |
| `agent-p stats`        | Show session metrics     |
| `agent-p eval`         | Run evaluation           |
| `agent-p debug agents` | Show agent metrics       |
| `agent-p debug skills` | Show skill effectiveness |
| `agent-p debug memory` | Show memory state        |
| `agent-p debug search` | Show search pipeline     |
| `agent-p debug tokens` | Show token usage         |
| `agent-p debug hooks`  | Show hook history        |

### Skill Effectiveness Tracking

From knowledgebase (core/memory/manager.py):

```typescript
interface SkillEffectiveness {
  skillName: string;
  activations: number;
  successes: number;
  failures: number;
  avgLatency_ms: number;
  avgTokens: number;
}

function trackSkillActivation(
  skill: string,
  success: boolean,
  latency_ms: number,
  tokens: number,
): void {
  const stats = skillStats.get(skill) || {
    activations: 0,
    successes: 0,
    failures: 0,
  };
  stats.activations++;
  if (success) stats.successes++;
  else stats.failures++;
  skillStats.set(skill, stats);
}

function getSkillSuccessRate(skill: string): number {
  const stats = skillStats.get(skill);
  if (!stats || stats.activations === 0) return 0;
  return stats.successes / stats.activations;
}
```

## H5: Evaluation Integration Points

| Phase          | What Gets Evaluated | When         |
| -------------- | ------------------- | ------------ |
| After SCOUT    | Context quality     | Post-Stage 1 |
| After BUILDER  | Code quality        | Post-Stage 2 |
| After TESTER   | Test coverage       | Post-Stage 3 |
| After REVIEWER | Review findings     | Post-Stage 4 |
| After VERIFIER | Trust score         | Post-Stage 5 |
| Session End    | Overall success     | STOP hook    |

---

> **Version**: 2.10.0
> **Last Updated**: 2026-03-05
> **Related Documents**:
>
> - [PLAN.md](./PLAN.md) - Master Plan (v4.0.0)
> - [BUILD.md](./BUILD.md) - Build Tracker (v2.1.0)
> - [ROADMAP.md](./ROADMAP.md) - Roadmap (v1.0.0)