portable-agent-layer 0.12.0 → 0.13.0

package/assets/skills/opinion/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: opinion
+description: "Opinion tracker for relationship notes. PROACTIVE: When the user confirms a preference ('yes exactly', 'keep doing that'), contradicts one ('no, don't do that', 'stop'), or you observe a recurring behavioral pattern — invoke this to update opinion confidence."
+---
+
+# Opinion Tracker
+
+Tool: `tools/opinion.ts`
+
+Manage confidence-scored opinions about the user. Opinions are promoted from recurring relationship notes (the W/O/B observations captured at session end). This tool is the fast path to grow opinion confidence — relationship notes feed the slow path (+2% per reflect cycle), while explicit confirmations here jump +10%.
+
+Opinions at ≥85% confidence are automatically injected into every session context.
+
+## When to Use
+
+**Proactively call this tool during conversations when:**
+
+- The user **explicitly confirms** a preference → `--confirmation`
+  - "yes, keep it short" → confirms concise preference
+  - "exactly, that's how I want it" → confirms the approach you used
+  - User accepts an unusual choice without pushback → implicit confirmation
+
+- The user **explicitly contradicts** a preference → `--contradiction`
+  - "no, I actually want more detail here" → contradicts concise preference
+  - "stop doing X" → contradicts a tracked pattern
+
+- You observe a **recurring behavioral pattern** → `--supporting`
+  - User does the same thing for the 2nd+ time in a session
+  - Pattern matches an existing tracked opinion
+
+**Do NOT call when:**
+- The observation is ephemeral or task-specific (not a general preference)
+- You're unsure whether it's a real preference or a one-off request
+- The opinion would be trivially obvious ("user wants correct code")
+
+## Usage
+
+```bash
+# List all tracked opinions
+bun opinion.ts list
+
+# Show details for a specific opinion (fuzzy-matched)
+bun opinion.ts show "keywords"
+
+# Add a new opinion (starts at 50%)
+bun opinion.ts add "statement" [--category workflow]
+
+# Add evidence to an existing opinion
+bun opinion.ts evidence "keywords" --supporting "why"      # +2%
+bun opinion.ts evidence "keywords" --counter "why"         # -5%
+bun opinion.ts evidence "keywords" --confirmation "why"    # +10%
+bun opinion.ts evidence "keywords" --contradiction "why"   # -20%
+```
+
+## Categories
+
+`communication` | `technical` | `workflow` | `general`
+
+## Confidence Lifecycle
+
+```
+New opinion (add) → 50%
+  ├── supporting evidence → +2% each
+  ├── counter evidence → -5% each
+  ├── explicit confirmation → +10% each
+  ├── explicit contradiction → -20% each
+  └── at ≥85% → auto-injected into session context
+```
+
+## Examples
+
+```bash
+# User says "yes keep it concise, I don't need long explanations"
+bun opinion.ts evidence "concise responses" --confirmation "User explicitly said keep it concise"
+
+# User asks for detailed explanation (contradicts concise preference)
+bun opinion.ts evidence "concise responses" --contradiction "User requested detailed explanation for this topic"
+
+# You notice user prefers iterative development for the 3rd time
+bun opinion.ts evidence "iterative development" --supporting "User again chose incremental approach over big-bang change"
+
+# New pattern: user always checks git status before committing
+bun opinion.ts add "User checks git status before every commit" --category workflow
+```

package/{src → assets/skills/opinion}/tools/opinion.ts

@@ -6,13 +6,13 @@
  * contradictions, or new behavioral patterns.
  *
  * Usage:
- *   bun run tool:opinion -- list                                      List all opinions
- *   bun run tool:opinion -- show "statement"                          Show opinion details
- *   bun run tool:opinion -- add "statement" [--category workflow]     Add new opinion
- *   bun run tool:opinion -- evidence "statement" --supporting "why"   Add supporting evidence
- *   bun run tool:opinion -- evidence "statement" --counter "why"      Add counter evidence
- *   bun run tool:opinion -- evidence "statement" --confirmation "why" Explicit user confirmation
- *   bun run tool:opinion -- evidence "statement" --contradiction "why" Explicit user contradiction
+ *   bun opinion.ts list                                      List all opinions
+ *   bun opinion.ts show "statement"                          Show opinion details
+ *   bun opinion.ts add "statement" [--category workflow]     Add new opinion
+ *   bun opinion.ts evidence "statement" --supporting "why"   Add supporting evidence
+ *   bun opinion.ts evidence "statement" --counter "why"      Add counter evidence
+ *   bun opinion.ts evidence "statement" --confirmation "why" Explicit user confirmation
+ *   bun opinion.ts evidence "statement" --contradiction "why" Explicit user contradiction
  */
 
 import {
@@ -23,7 +23,7 @@ import {
   type OpinionCategory,
   readOpinions,
   saveOpinion,
-} from "../hooks/lib/opinions";
+} from "../../../../src/hooks/lib/opinions";
 
 const args = process.argv.slice(2);
 const command = args[0];
@@ -82,7 +82,7 @@ switch (command) {
   case "show": {
     const statement = args[1];
     if (!statement) {
-      console.error('Usage: bun run tool:opinion -- show "statement"');
+      console.error('Usage: bun opinion.ts show "statement"');
       process.exit(1);
     }
 
@@ -128,9 +128,7 @@ switch (command) {
   case "add": {
     const statement = args[1];
     if (!statement) {
-      console.error(
-        'Usage: bun run tool:opinion -- add "statement" [--category workflow]'
-      );
+      console.error('Usage: bun opinion.ts add "statement" [--category workflow]');
       process.exit(1);
     }
 
@@ -156,7 +154,7 @@ switch (command) {
     const statement = args[1];
     if (!statement) {
       console.error(
-        'Usage: bun run tool:opinion -- evidence "statement" --supporting "description"'
+        'Usage: bun opinion.ts evidence "statement" --supporting "description"'
       );
       process.exit(1);
     }
@@ -226,20 +224,6 @@ switch (command) {
     evidence "keywords" --contradiction "why" User explicitly contradicted (-20%)
 
   Categories: communication, technical, workflow, general
-
-  Examples:
-    bun run tool:opinion -- list
-    bun run tool:opinion -- evidence "concise direct responses" --confirmation "User said: keep it short"
-    bun run tool:opinion -- evidence "concise direct responses" --contradiction "User asked for detailed explanation"
-    bun run tool:opinion -- add "User prefers iterative development" --category workflow
-    bun run tool:opinion -- show "iterative development"
-
-  Confidence lifecycle:
-    New opinions start at 50%. Supporting notes from reflect add +2% each.
-    Explicit confirmations jump +10%, contradictions drop -20%.
-    At >=85%, opinions are auto-injected into every session context.
-
-  Usage: bun run tool:opinion -- <command> [args]
 `);
     break;
   }

package/assets/templates/PAL/CONTEXT_ROUTING.md

@@ -6,6 +6,8 @@ Load context on-demand by reading the file at the path listed. Only load what th
 
 | Topic | Path |
 |-------|------|
+| PAL system overview | `~/.agents/PAL/README.md` |
+| System architecture | `~/.agents/PAL/SYSTEM_ARCHITECTURE.md` |
 | Memory format & guidelines | `~/.agents/PAL/MEMORY_SYSTEM.md` |
 | Work tracking (projects, sessions) | `~/.agents/PAL/WORK_TRACKING.md` |
 | Opinion tracking | `~/.agents/PAL/OPINION_TRACKING.md` |

package/assets/templates/PAL/OPINION_TRACKING.md

@@ -1,3 +1,3 @@
 # Opinion Tracking
 
-PAL tracks confidence-scored opinions about the user. When you notice the user confirming or contradicting a behavioral pattern, update it via `bun run tool:opinion`. Run `bun run tool:opinion -- --help` for full usage and examples. Opinions at ≥85% confidence are automatically injected into every session context.
+PAL tracks confidence-scored opinions about the user. When you notice the user confirming or contradicting a behavioral pattern, use the `opinion` skill to update confidence. Opinions at ≥85% confidence are automatically injected into every session context.

package/assets/templates/PAL/README.md

@@ -0,0 +1,127 @@
+# PAL — Portable Agent Layer
+
+PAL is a persistent, cross-platform, cross-agent layer for portable AI workflows, memory, and accumulated knowledge. It runs inside any compatible AI coding agent (Claude Code, opencode) as an interconnected set of skills, hooks, tools, memory, and configuration — all orchestrated by The Algorithm.
+
+## How It Works
+
+**CLAUDE.md** (or the agent equivalent) is the entry point — generated from a template by the CLI installer. It defines execution modes, The Algorithm routing, and the context routing table. The agent loads it natively every session. A SessionStart hook keeps it fresh automatically.
+
+**The PAL home directory (`~/.agents/PAL/`)** contains all system documentation, user context (TELOS), and routing files. The rest of the system lives in the PAL package (`src/`) and the agent's config directory (`~/.claude/` or `~/.config/opencode/`).
+
+## Directory Structure
+
+```
+~/.agents/PAL/                     # PAL home — user context + routing
+  ALGORITHM.md                     # The execution engine (4-phase)
+  CONTEXT_ROUTING.md               # On-demand context routing table
+  MEMORY_SYSTEM.md                 # Memory guidelines
+  OPINION_TRACKING.md              # Opinion system reference
+  STEERING_RULES.md                # Behavioral rules
+  WORK_TRACKING.md                 # Work tracking reference
+  telos/                           # User life context (TELOS)
+    MISSION.md, GOALS.md, PROJECTS.md, BELIEFS.md,
+    CHALLENGES.md, STRATEGIES.md, IDEAS.md, LEARNED.md,
+    MODELS.md, NARRATIVES.md
+
+<PAL package>/                     # The PAL codebase
+  src/
+    cli/                           # CLI entry point (pal command)
+    hooks/                         # Session lifecycle hooks
+      handlers/                    # Individual stop/prompt handlers
+      lib/                         # Shared utilities
+    targets/                       # Agent-specific installers (Claude, opencode)
+    tools/                         # Standalone CLI tools
+  assets/
+    skills/                        # Bundled skills (16+)
+    templates/PAL/                 # Templates for PAL home files
+
+<PAL package>/memory/              # Persistent memory (gitignored)
+  state/                           # Runtime state (sessions, counts, caches)
+  signals/                         # Rating signals (ratings.jsonl)
+  relationship/                    # Daily interaction notes + opinions
+    YYYY-MM/YYYY-MM-DD.md          # Daily relationship notes
+    opinions.json                  # Confidence-tracked opinions
+    reflections/                   # Periodic reflection reports
+  session-learning/                # Per-session learnings
+  failures/                        # Low-rating context dumps
+  wisdom/                          # Crystallized principles (frames)
+  synthesis/                       # Pattern synthesis reports
+```
+
+## Core Subsystems
+
+### The Algorithm (`ALGORITHM.md`)
+The 4-phase execution engine: Observe, Plan, Execute, Verify. Transitions from CURRENT STATE to IDEAL STATE via verifiable criteria. Used for all complex work.
+
+### Three Execution Modes
+Every response uses exactly one mode:
+- **MINIMAL** — Greetings, acknowledgments
+- **NATIVE** — Simple, quick tasks
+- **ALGORITHM** — Multi-step, complex work (invokes the full 4-phase engine)
+
+### Skills (`assets/skills/`)
+Bundled skills installed into the agent's skill directory. Each has a `SKILL.md` defining triggers, workflows, and capabilities. Skills are the primary capability unit — they tell the AI what it can do and when to do it.
+
+### Hooks (`src/hooks/`)
+Event hooks across the session lifecycle:
+- **SessionStart** → `LoadContext.ts` — inject dynamic context, regenerate CLAUDE.md if stale
+- **UserPromptSubmit** → `UserPromptOrchestrator.ts` — rating capture, session naming
+- **PreToolUse** → `SecurityValidator.ts` — block dangerous commands; `SkillGuard.ts` — block false-positive skill matches
+- **Stop** → `StopOrchestrator.ts` — work tracking, relationship capture, learnings, backups, reflect trigger
+
+### Memory (`memory/`)
+Persistent storage across sessions:
+- **signals/** — User satisfaction ratings (explicit + implicit)
+- **relationship/** — Daily interaction notes, confidence-tracked opinions, reflection reports
+- **session-learning/** — Per-session context and learnings
+- **failures/** — Low-rating session context dumps for pattern avoidance
+- **wisdom/** — Crystallized principles that compound over time
+- **synthesis/** — Weekly pattern synthesis reports
+- **state/** — Session registry, counts cache, debug logs
+
+### Tools (`src/tools/`)
+CLI utilities: `tool:opinion` (manage opinions), `tool:reflect` (relationship reflection), `tool:analyze` (learning analysis), `tool:tokens` (usage tracking), `tool:export` / `tool:import` (state portability).
+
+### TELOS (`telos/`)
+Personal context system — mission, goals, projects, beliefs, challenges, strategies, ideas, learnings, mental models, narratives. Managed via the telos skill.
+
+### Security (`SecurityValidator.ts`)
+Hook-based security: validates Bash commands and file operations against dangerous patterns. Fail-open design — blocks known-dangerous operations without breaking legitimate work.
+
+## Startup & Context Loading
+
+At session start, three things happen:
+1. **CLAUDE.md** loads natively (identity, modes, routing table)
+2. **`loadAtStartup` files** from `pal-settings.json` are loaded by `LoadContext.ts`
+3. **Dynamic context** injected by `LoadContext.ts`: crystallized principles, tracked opinions (≥85%), recent interaction notes, learning digest, signal trends, failure patterns, active work summary — each toggleable in `pal-settings.json → dynamicContext`
+
+All other documentation loads on-demand via the routing table in CLAUDE.md.
+
+## CLI
+
+```
+pal                          # Start agent session with auto-summary on exit
+pal cli init                 # Scaffold PAL home + install hooks
+pal cli install [--claude]   # Register hooks/skills for Claude Code
+pal cli install [--opencode] # Register hooks/skills for opencode
+pal cli uninstall            # Remove hooks/skills
+pal cli status               # Show configuration
+pal cli doctor               # Check prerequisites and health
+pal cli export [path]        # Export user state to zip
+pal cli import [path]        # Import state from zip
+pal cli update               # Update PAL
+```
+
+## Cross-Platform & Cross-Agent
+
+PAL is designed to work identically across:
+- **Platforms:** macOS, Linux, Windows
+- **Agents:** Claude Code, opencode (and future tools)
+- **Environment overrides:** `PAL_HOME`, `PAL_PKG`, `PAL_CLAUDE_DIR`, `PAL_OPENCODE_DIR`, `PAL_AGENTS_DIR`
+
+## Extending PAL
+
+- **Add a skill:** Use the `create-skill` skill or manually create `assets/skills/<name>/SKILL.md`
+- **Add startup files:** Append to `pal-settings.json → loadAtStartup.files`
+- **Add user context:** Create files in `~/.agents/PAL/telos/`
+- **Toggle dynamic context:** Set keys in `pal-settings.json → dynamicContext` to `false`

package/assets/templates/PAL/STEERING_RULES.md

@@ -22,9 +22,13 @@ Correct: Read the handler, imports, and patterns first → integrate with what's
 Bad: Page broken → change CSS, API, config, and routes at once. Still broken, now you don't know which change helped or hurt.
 Correct: Dev tools → 404 on API → fix the route → verify → move to next issue.
 
-**Minimal scope.** Only change what was asked. No bonus refactoring, no extra cleanup, no unsolicited improvements.
-Bad: Fix bug on line 42, also refactor the whole file → 200-line diff for a one-line fix.
-Correct: Fix the bug → 1-line diff.
+**Minimal scope.** Only change what was asked. No bonus features, no unsolicited additions.
+Bad: Fix bug on line 42, also add a new logging framework → 200-line diff for a one-line fix.
+Correct: Fix the bug → focused diff.
+
+**Cleanup on touch.** When modifying a file, assess it for dead code, unnecessary complexity, or poor organization. Offer to clean it up — don't silently refactor, flag what you found and ask. This applies to the file being edited, not neighboring files.
+Bad: Editing a handler → silently rewrite the whole file and three others.
+Correct: Editing a handler → notice dead imports and a 200-line function → "This file has dead imports and a function that could be split — want me to clean it up?"
 
 **Ask before destructive actions.** Deletes, force pushes, production deploys — always ask first.
 Bad: "Clean up cruft" → delete 15 files including backups without asking.

package/assets/templates/PAL/SYSTEM_ARCHITECTURE.md

@@ -0,0 +1,471 @@
+# PAL System Architecture
+
+<!--
+SYSTEM ARCHITECTURE TEMPLATE
+=============================
+This file defines the GENERIC architecture patterns for any PAL installation.
+These are the foundational patterns that apply to ALL PAL implementations.
+
+WHAT GOES HERE:
+- The Founding Principles (universal)
+- Generic system patterns (skill structure, hook lifecycle, memory layout)
+- Architecture diagrams showing how components interact
+- Design philosophy and constraints
+
+WHAT DOES NOT GO HERE:
+- User-specific skill counts, configurations, or API keys
+- Personal projects or deployment details
+- Ephemeral state or session-specific information
+-->
+
+**The Founding Principles and Universal Architecture Patterns for the Portable Agent Layer**
+
+---
+
+## Core Philosophy
+
+**PAL is scaffolding for AI, not a replacement for human intelligence.**
+
+AI systems need structure to be reliable. Like physical scaffolding supports construction work, PAL provides the architectural framework that makes AI assistance dependable, maintainable, and effective — regardless of which AI agent runs underneath.
+
+---
+
+## The Founding Principles
+
+### 1. Portability First
+
+**PAL exists so your AI context, memory, and workflows survive any single tool.**
+
+AI agents come and go. Your accumulated knowledge, preferences, and workflows should not be locked into one vendor's tool. PAL abstracts the agent-specific layer so the same skills, hooks, memory, and configuration work across Claude Code, opencode, and future agents.
+
+**What portability means in practice:**
+- No agent-specific assumptions in core logic
+- Agent-specific code isolated in `src/targets/`
+- Skills, memory, and TELOS are agent-agnostic
+- A single `pal cli install --<agent>` registers everything
+
+### 2. Cross-Platform by Default
+
+**Every feature must work identically on macOS, Linux, and Windows.**
+
+No platform-specific code without a portable fallback. Path resolution, shell commands, and file operations use cross-platform abstractions. Environment overrides (`PAL_HOME`, `PAL_PKG`, etc.) let users customize paths without touching code.
+
+### 3. The Continuously Upgrading Algorithm
+
+**The Algorithm is the gravitational center — everything else exists to serve it.**
+
+PAL is built around a universal pattern for accomplishing any task: **Current State → Ideal State** via verifiable criteria. This pattern applies at every scale.
+
+Everything feeds back into improving The Algorithm:
+- The **Memory System** captures signals from every interaction
+- The **Hook System** detects sentiment, ratings, and behavioral patterns
+- The **Learning System** organizes evidence by session
+- The **Wisdom System** crystallizes recurring patterns into principles
+- The **Relationship System** tracks how the user works and what they prefer
+
+### 4. Scaffolding > Model
+
+**The system architecture matters more than the underlying AI model.**
+
+A well-structured system with good scaffolding will outperform a more powerful model with poor structure. PAL's value comes from:
+- Organized workflows that guide AI execution
+- Routing systems that activate the right context
+- Quality gates that verify outputs
+- Memory systems that enable learning
+- Feedback systems that provide awareness
+
+### 5. As Deterministic as Possible
+
+**Favor predictable, repeatable outcomes over flexibility.**
+
+- Same input → Same output
+- Behavior defined by code and hooks, not prompt variations
+- Version control tracks explicit changes
+- Hooks run deterministic TypeScript, not prompt-driven logic
+
+### 6. Code Before Prompts
+
+**Write code to solve problems, use prompts to orchestrate code.**
+
+Prompts should never replicate functionality that code can provide:
+- Hooks are TypeScript, not prompt instructions
+- Tools are CLI programs, not natural language procedures
+- Memory is structured JSON/JSONL, not freeform text
+- Configuration is `pal-settings.json`, not prose in CLAUDE.md
+
+### 7. Clear Thinking + Prompting is King
+
+**The quality of outcomes depends on the quality of thinking and prompts.**
+
+Before any code, before any architecture — there must be clear thinking:
+- Understand the problem deeply before solving it
+- Define success criteria before building
+- Challenge assumptions before accepting them
+- Simplify before optimizing
+
+### 8. UNIX Philosophy
+
+**Do one thing well. Compose tools through standard interfaces.**
+
+- Each hook handler does one thing
+- Each tool is a standalone CLI program
+- Each skill is a self-contained capability
+- Hooks compose via `Promise.allSettled` — independent, parallel, isolated failures
+- Tools compose via `bun run tool:<name>` — standard I/O, exit codes
+
+### 9. CLI as Interface
+
+**Every operation should be accessible via command line.**
+
+- `pal cli <command>` for system management
+- `bun run tool:<name>` for utilities
+- Skills triggered via agent slash commands
+- No hidden operations — everything is scriptable and testable
+
+### 10. Spec / Test First
+
+**Define expected behavior before writing implementation.**
+
+- Write tests before implementation
+- Tests should fail initially
+- Implement until tests pass
+- Run `check-write`, `type-check`, and `test` after every edit
+
+### 11. Custom Skill Management
+
+**Skills are the organizational unit for all domain expertise.**
+
+Skills are active orchestrators, not passive documentation:
+- **Self-activating:** Trigger automatically based on user request
+- **Self-contained:** Package all context, workflows, and tools
+- **Composable:** Can invoke other skills and agents
+- **Evolvable:** Easy to add, modify, or deprecate
+
+### 12. Custom Memory System
+
+**Automatic capture and preservation of valuable work.**
+
+Every session, every insight, every decision — captured automatically:
+- Relationship notes extracted via inference
+- Learnings captured per session
+- Ratings tracked (explicit and implicit)
+- Wisdom crystallized from recurring patterns
+- Failures logged for pattern avoidance
+
+### 13. Permission to Fail
+
+**Explicit permission to say "I don't know" prevents hallucinations.**
+
+The AI has explicit permission to say "I don't know" when:
+- Information isn't available in context
+- Multiple conflicting answers seem equally valid
+- Verification isn't possible
+
+Fabricating an answer is far worse than admitting uncertainty.
+
+---
+
+## Skill System Architecture
+
+### Canonical Skill Structure
+
+```
+assets/skills/<name>/
+├── SKILL.md              # Main skill file (REQUIRED)
+└── tools/                # CLI tools for automation (optional)
+    └── tool-name.ts      # TypeScript CLI tool
+```
+
+### SKILL.md Format
+
+```markdown
+---
+name: skill-name
+description: What it does. Use when [triggers]. Capabilities.
+---
+
+# Skill Name
+
+Brief description.
+
+## Workflow
+[Steps, decision trees, or procedures]
+```
+
+### Key Rules
+
+- **Description**: Used by the agent for skill matching — be specific about triggers
+- **One SKILL.md per skill**: The single entry point
+- **Tools are optional**: Only add when the skill needs CLI automation
+- **Skills are agent-agnostic**: No agent-specific assumptions in SKILL.md
+
+---
+
+## Hook System Architecture
+
+### Lifecycle
+
+```
+┌─────────────────────┐
+│   Session Start     │──► LoadContext.ts
+│                     │    - Regenerate CLAUDE.md if stale
+│                     │    - Inject dynamic context (system-reminder)
+└─────────────────────┘
+
+┌─────────────────────┐
+│  User Prompt Submit │──► UserPromptOrchestrator.ts
+│                     │    - Rating capture (explicit/implicit)
+│                     │    - Session naming (first prompt)
+└─────────────────────┘
+
+┌─────────────────────┐
+│   Pre Tool Use      │──► SecurityValidator.ts
+│                     │    - Bash command validation
+│                     │    - File path validation
+│                     │──► SkillGuard.ts
+│                     │    - Block false-positive skill matches
+└─────────────────────┘
+
+┌─────────────────────┐
+│       Stop          │──► StopOrchestrator.ts
+│                     │    - Work session capture
+│                     │    - Relationship extraction (Haiku inference)
+│                     │    - Work learning capture
+│                     │    - Failure logging
+│                     │    - Reflect trigger check
+│                     │    - Auto-backup
+│                     │    - Count updates
+│                     │    - Tab reset
+└─────────────────────┘
+```
+
+### Design Principles
+
+- **Fail-open**: Hook errors never block the user's session
+- **Parallel execution**: Stop handlers run via `Promise.allSettled` — one failure doesn't block others
+- **Idempotent**: Handlers check for existing state before writing (e.g., session dedup)
+- **Timeout-aware**: Inference calls have hard timeouts (8s default)
+- **Subagent-aware**: `LoadContext.ts` skips heavy context loading for subagent sessions
+
+### Configuration
+
+Hooks are registered in the agent's settings file during `pal cli install`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [{ "type": "command", "command": "bun run <path>/LoadContext.ts" }],
+    "UserPromptSubmit": [{ "type": "command", "command": "bun run <path>/UserPromptOrchestrator.ts" }],
+    "PreToolUse": [
+      { "type": "command", "command": "bun run <path>/SecurityValidator.ts", "matcher": "Bash" },
+      { "type": "command", "command": "bun run <path>/SkillGuard.ts", "matcher": "Skill" }
+    ],
+    "Stop": [{ "type": "command", "command": "bun run <path>/StopOrchestrator.ts" }]
+  }
+}
+```
+
+---
+
+## Memory System Architecture
+
+### Directory Structure
+
+```
+memory/
+├── state/                         # Runtime state
+│   ├── sessions.json              # Session registry (name, cwd, status, summary)
+│   ├── projects.json              # Multi-session project tracking
+│   ├── counts.json                # Cached counts for greeting
+│   ├── last-responses.json        # Cached responses for rating correlation
+│   ├── pending-failure.json       # Deferred failure capture
+│   └── debug.log                  # Hook execution logs
+│
+├── signals/                       # User feedback
+│   └── ratings.jsonl              # Explicit + implicit ratings
+│
+├── relationship/                  # Interaction tracking
+│   ├── YYYY-MM/
+│   │   └── YYYY-MM-DD.md         # Daily notes (W/O/B format)
+│   ├── opinions.json              # Confidence-tracked opinions
+│   └── reflections/               # Periodic reflection reports
+│
+├── session-learning/              # Per-session learnings
+│   └── YYYY-MM/
+│       └── YYYY-MM-DD_title.md    # Session learning with frontmatter
+│
+├── failures/                      # Low-rating context dumps
+│   └── YYYY-MM/
+│       └── YYYY-MM-DD_context.md  # Failed session context for avoidance
+│
+├── wisdom/                        # Crystallized principles
+│   └── frames/
+│       └── domain.md              # Domain-specific principles with confidence
+│
+└── synthesis/                     # Pattern aggregation
+    └── YYYY-MM/
+        └── YYYY-MM-DD_period.md   # Weekly/monthly synthesis reports
+```
+
+### Data Flow
+
+```
+Session interaction
+  │
+  ├─► [Stop] Rating capture ──► signals/ratings.jsonl
+  │
+  ├─► [Stop] Relationship extraction (Haiku) ──► relationship/YYYY-MM/YYYY-MM-DD.md
+  │
+  ├─► [Stop] Work learning capture ──► session-learning/YYYY-MM/...
+  │
+  ├─► [Stop] Failure capture (low ratings) ──► failures/YYYY-MM/...
+  │
+  ├─► [Periodic] Reflect trigger ──► relationship/opinions.json
+  │                                  relationship/reflections/...
+  │
+  ├─► [Periodic] Synthesis ──► synthesis/YYYY-MM/...
+  │
+  └─► [Periodic] Wisdom graduation ──► wisdom/frames/...
+```
+
+### Relationship Note Format
+
+Three note types, captured via Haiku inference at session end:
+
+```
+W — World facts (user's situation, projects, tools)
+O(c=0.85) — Opinions/preferences with confidence
+B(c=0.75) — Beliefs/behavioral patterns with confidence
+```
+
+### Opinion Lifecycle
+
+```
+Relationship notes (O/B types)
+  │
+  ├─► Reflect tool groups similar notes
+  │   ├─► 2+ occurrences → new opinion at 50% confidence
+  │   └─► Matches existing → +2% supporting evidence
+  │
+  ├─► AI confirmation → +10% (via tool:opinion)
+  ├─► AI contradiction → -20% (via tool:opinion)
+  │
+  └─► At ≥85% confidence → auto-injected into session context
+```
+
+---
+
+## Context Loading Architecture
+
+### Two-Layer Design
+
+**Static context** (loaded natively by the agent):
+- CLAUDE.md — identity, modes, context routing table
+- Loaded once at session start, always available
+
+**Dynamic context** (injected by LoadContext hook):
+- Changes per-session, can't live in a static file
+- Injected as `<system-reminder>` block to stdout
+- Each section independently toggleable in `pal-settings.json → dynamicContext`
+
+### Injection Order
+
+```
+LoadContext.ts
+  │
+  ├─► Regenerate CLAUDE.md if template/telos changed
+  │
+  └─► Build system-reminder:
+      1. loadAtStartup files (user-configured)
+      2. Crystallized principles (wisdom frames)
+      3. Tracked opinions (≥85% confidence)
+      4. Recent interaction notes (last 2 days)
+      5. Learning digest (this project + other recent)
+      6. Pattern synthesis recommendations
+      7. Signal trends (today/week/trend)
+      8. Failure patterns (last 5 low-rating contexts)
+      9. Active work summary (sessions + projects)
+```
+
+### On-Demand Context
+
+Everything else loads via the routing table in CLAUDE.md. The AI reads files only when the current task requires that context — no upfront loading of the full system.
+
+---
+
+## Security Architecture
+
+### Fail-Open Design
+
+`SecurityValidator.ts` runs on PreToolUse for Bash commands. It blocks known-dangerous patterns but never prevents legitimate work:
+
+- **Blocked**: `rm -rf /`, `chmod 777`, known secret file paths, command injection patterns
+- **Allowed**: Everything else passes through
+- **On error**: The hook exits silently — a broken security hook never blocks the user
+
+### What's Protected
+
+- Dangerous shell commands (recursive deletes, permission changes)
+- Known secret file paths (.env, credentials, key files)
+- Command injection patterns in arguments
+
+### What's NOT Protected
+
+PAL does not implement:
+- Network-level security (no firewall, no proxy)
+- File encryption (memory is plaintext on disk)
+- Access control (anyone with filesystem access can read memory)
+
+Users are responsible for securing their own machine and API keys.
+
+---
+
+## Cross-Platform Architecture
+
+### Agent Abstraction
+
+```
+src/targets/
+├── claude/          # Claude Code specific
+│   ├── install.ts   # Register hooks + skills in ~/.claude/settings.json
+│   └── uninstall.ts
+├── opencode/        # opencode specific
+│   ├── install.ts   # Register hooks + skills in opencode config
+│   ├── uninstall.ts
+│   └── plugin.ts    # opencode plugin interface
+└── lib.ts           # Shared: JSON read/write, settings merge, TELOS scaffold
+```
+
+### Path Resolution
+
+All paths resolve through `src/hooks/lib/paths.ts`:
+
+| Path | Default | Override |
+|------|---------|----------|
+| PAL home | `~/.agents/PAL` | `PAL_HOME` |
+| PAL package | Auto-detected from source | `PAL_PKG` |
+| Claude config | `~/.claude` | `PAL_CLAUDE_DIR` |
+| opencode config | `~/.config/opencode` | `PAL_OPENCODE_DIR` |
+| Agents dir | `~/.agents` | `PAL_AGENTS_DIR` |
+
+### Portability Contract
+
+- Core logic (`src/hooks/lib/`, `src/tools/`) has zero agent-specific imports
+- Agent-specific code lives only in `src/targets/`
+- Skills reference no agent-specific APIs
+- Memory format is plain JSON/JSONL/Markdown — readable by any tool
+
+---
+
+## File Naming Conventions
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Skill directory | kebab-case | `extract-wisdom/`, `first-principles/` |
+| SKILL.md | Uppercase | `SKILL.md` |
+| Hook files | PascalCase | `LoadContext.ts`, `StopOrchestrator.ts` |
+| Handler files | kebab-case | `session-name.ts`, `work-learning.ts` |
+| Library files | kebab-case | `text-similarity.ts`, `signal-trends.ts` |
+| Tool files | kebab-case | `relationship-reflect.ts`, `token-cost.ts` |
+| Memory files | date-prefixed | `2026-03-24.md`, `2026-03-24_weekly.md` |
+| Template files | UPPER_SNAKE | `ALGORITHM.md`, `CONTEXT_ROUTING.md` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -45,7 +45,6 @@
     "install:all": "bun run src/cli/index.ts cli install",
     "uninstall": "bun run src/cli/index.ts cli uninstall",
     "tool:analyze": "bun run src/tools/analyze.ts",
-    "tool:opinion": "bun run src/tools/opinion.ts",
     "tool:reflect": "bun run src/tools/relationship-reflect.ts",
     "tool:export": "bun run src/tools/export.ts",
     "tool:import": "bun run src/tools/import.ts",

package/src/hooks/handlers/relationship.ts

@@ -22,7 +22,7 @@ const OBSERVATION_SCHEMA = {
             type: "string",
             enum: ["O", "W", "B"],
             description:
-              "O=opinion/preference, W=factual observation, B=belief/behavioral pattern",
+              "O=opinion/preference, W=factual observation, B=biographical (what the AI did this session)",
           },
           text: { type: "string" },
           confidence: { type: "number" },
@@ -74,11 +74,11 @@ export async function captureRelationship(
   logDebug("relationship", "Calling inference...");
   const result = await inference({
     system:
-      "You analyze user messages from an AI coding session to extract relationship observations. " +
-      "Types: O=opinions/preferences (how they like to work, what they want), " +
-      "B=beliefs/behavioral patterns (how they approach problems, decision-making style, recurring habits), " +
-      "W=world facts (their situation, projects, tools they use). " +
-      "Focus on: preferences, corrections, frustrations, positive reactions, communication style, problem-solving approach. " +
+      "You analyze messages from an AI coding session to extract relationship observations. " +
+      "Types: O=opinions/preferences (how the user likes to work, what they want), " +
+      "B=biographical (what the AI accomplished this session, written in first-person), " +
+      "W=world facts (user's situation, projects, tools they use). " +
+      "Focus on: preferences, corrections, frustrations, positive reactions, communication style, and session accomplishments. " +
       "Return 0-3 observations. If nothing notable, return empty observations array. Be concise.",
     user: `User messages from this session:\n${userMessages.map((m, i) => `${i + 1}. ${m}`).join("\n")}`,
     maxTokens: 300,

package/src/hooks/handlers/session-name.ts

@@ -9,7 +9,7 @@
  * This avoids the 1-5s inference latency that previously blocked every first prompt.
  */
 
-// import { spawn } from "node:child_process";
+import { spawn } from "node:child_process";
 import { inference } from "../lib/inference";
 import { logDebug, logError } from "../lib/log";
 import {
@@ -41,25 +41,24 @@ export async function captureSessionName(
   writeSessionName(sessionId, name);
   logDebug("session-name", `Named from prompt: "${name}"`);
 
-  // TODO: re-enable when a consumer exists (tab titles, dashboard)
-  // // 2. Spawn detached background process to upgrade with inference
-  // if (!process.env.ANTHROPIC_API_KEY) return;
-  // try {
-  //   const promptB64 = Buffer.from(message.slice(0, 800)).toString("base64");
-  //   const child = spawn(
-  //     "bun",
-  //     [import.meta.filename, "--upgrade", sessionId, promptB64, fallback],
-  //     {
-  //       detached: true,
-  //       stdio: "ignore",
-  //       env: { ...process.env, CLAUDECODE: undefined },
-  //     }
-  //   );
-  //   child.unref();
-  //   logDebug("session-name", "Spawned background inference upgrade");
-  // } catch {
-  //   // Non-critical — deterministic name is already stored
-  // }
+  // Spawn detached background process to upgrade with Haiku inference
+  if (!process.env.ANTHROPIC_API_KEY) return;
+  try {
+    const promptB64 = Buffer.from(message.slice(0, 800)).toString("base64");
+    const child = spawn(
+      "bun",
+      [import.meta.filename, "--upgrade", sessionId, promptB64, name],
+      {
+        detached: true,
+        stdio: "ignore",
+        env: { ...process.env, CLAUDECODE: undefined },
+      }
+    );
+    child.unref();
+    logDebug("session-name", "Spawned background Haiku upgrade");
+  } catch {
+    // Non-critical — deterministic name is already stored
+  }
 }
 
 /**

package/src/hooks/lib/relationship.ts

@@ -5,7 +5,7 @@
  * Notes live at memory/relationship/YYYY-MM/YYYY-MM-DD.md
  * W = world (facts about user's situation)
  * O = opinion (preference with confidence)
- * B = belief (behavioral pattern with confidence)
+ * B = biographical (what the AI did this session, first-person)
  *
  * Extraction is handled by the relationship handler via Haiku inference.
  * This lib provides storage and reading utilities only.
@@ -80,7 +80,7 @@ export function appendNotes(notes: RelationshipNote[], sessionId?: string): void
   if (sessionId) lines.push(`<!-- session:${sessionId} -->`);
 
   for (const note of fresh) {
-    if ((note.type === "O" || note.type === "B") && note.confidence !== undefined) {
+    if (note.type === "O" && note.confidence !== undefined) {
       lines.push(`- ${note.type}(c=${note.confidence}): ${note.text}`);
     } else {
       lines.push(`- ${note.type}: ${note.text}`);

package/src/tools/relationship-reflect.ts

@@ -3,7 +3,7 @@
  * RelationshipReflect — Periodic reflection on relationship patterns.
  *
  * Reads recent relationship notes and ratings to:
- * - Promote recurring O/B notes into tracked opinions with confidence
+ * - Promote recurring O notes into tracked opinions with confidence
  * - Update confidence on existing opinions via supporting evidence
  * - Generate a summary report
  *
@@ -159,9 +159,9 @@ function promoteToOpinions(notes: ParsedNote[], dryRun: boolean): OpinionChange[
   const opinions = readOpinions();
   const lastReflect = getLastReflectDate();
 
-  // Only O and B notes become opinions, skip already-processed notes
+  // Only O notes become opinions (B=biographical, about the AI, not user preferences)
   const opinionNotes = notes.filter(
-    (n) => (n.type === "O" || n.type === "B") && (!lastReflect || n.date > lastReflect)
+    (n) => n.type === "O" && (!lastReflect || n.date > lastReflect)
   );
 
   // Group similar notes together
@@ -225,7 +225,7 @@ interface OpinionSummary {
 }
 
 function groupNoteOccurrences(notes: ParsedNote[]): OpinionSummary[] {
-  const opNotes = notes.filter((n) => n.type === "O" || n.type === "B");
+  const opNotes = notes.filter((n) => n.type === "O");
   const groups = new Map<
     string,
     { confidences: number[]; dates: string[]; text: string }
@@ -397,7 +397,7 @@ if (values.help) {
 RelationshipReflect — Periodic reflection + opinion promotion
 
 Reads recent relationship notes and ratings. Promotes recurring
-observations (O/B types) into tracked opinions with confidence scoring.
+observations (O type) into tracked opinions with confidence scoring.
 
 Usage:
   bun run tool:reflect              Reflect on last 7 days (default)