portable-agent-layer 0.35.0 → 0.37.0

package/assets/templates/PAL/ALGORITHM.md

@@ -35,6 +35,20 @@ Thinking-only. No tool calls except context recovery (Grep/Glob/Read).
 ⏱️ EFFORT: [Standard | Extended | Advanced | Deep] — [one-line reason]
 ```
 
+**0.5. ISA context** — before reverse engineering, orient against the ISA:
+
+```bash
+# If cwd matches a registered project — read its open ISCs:
+bun ~/.pal/tools/project.ts list-isc <project-name>
+
+# If this is ad-hoc work with no registered project — scaffold a task ISA:
+bun ~/.pal/tools/project.ts scaffold-task-isa "<task title>"
+```
+
+Surface any open ISCs as live context: they are unfinished criteria from prior sessions. New criteria defined in this session extend them (use `add-isc`), not replace them.
+
+**Off-topic detection:** if the task description references a different registered project than the cwd project (e.g., working on project-a while inside project-b's directory), use `AskUserQuestion` to ask which project the ISC belongs to before writing anything. `add-isc` takes a project name as its first argument, so routing to any project is a one-word change.
+
 **1. Reverse engineer the request:**
 
 🔎 REVERSE ENGINEERING:
@@ -206,19 +220,54 @@ bun ~/.pal/tools/algorithm-reflect.ts --task "description" --criteria N --passed
   --q1 "self reflection" --q2 "algorithm reflection" --q3 "AI reflection"
 ```
 
-**3. Open Threads** — for each unresolved question, decision, or follow-up that came up during this session:
+**3. Relationship note** — write one Session entry capturing what was done this session:
 
 ```bash
-bun ~/.pal/tools/thread.ts --add --title "brief title" --context "why it matters, what needs to happen"
+bun ~/.pal/tools/relationship-note.ts --b "description"
 ```
 
-Only add threads that genuinely need follow-up. Resolve existing threads if this session closed them:
+- 1-2 sentences, first-person, specific — name the actual system/file/concept worked on
+- ✓ "Debugged the React Query cache split logic and resolved stuck message state in the onFinish callback"
+- ✗ "Helped with memory improvements" — too vague, no system named
+- Skip only if the session was a trivial lookup or typo fix (same rule as step 2)
+
+**4. Handoff note** — if work is unfinished, write what remains so the next session can pick up immediately:
 
 ```bash
+# Work still in progress:
+bun ~/.pal/tools/handoff-note.ts --title "what we were doing" --text "what remains, decisions made, next steps"
+
+# Work finished — clear any previous in-progress handoff:
+bun ~/.pal/tools/handoff-note.ts --done --title "what we completed"
+```
+
+- Write if anything is left mid-flight: unfinished implementation, open decision, partially debugged issue
+- Skip if the session fully resolved everything it set out to do
+- `--text` should answer: what's next, what was decided, what to watch out for
+
+**5. Open work** — close what this session finished; open what it didn't:
+
+**Project work** — use ISCs, not threads:
+```bash
+# Close completed ISCs:
+bun ~/.pal/tools/project.ts check-isc <project-name> <id>
+
+# Open new ISCs for unfinished work:
+bun ~/.pal/tools/project.ts add-isc <project-name> "what remains"
+```
+
+**Task ISA (one-shot work)** — mark complete when done:
+```bash
+bun ~/.pal/tools/project.ts complete-task-isa <slug>
+```
+
+**Cross-project or non-project follow-ups** — use threads:
+```bash
+bun ~/.pal/tools/thread.ts --add --title "brief title" --context "why it matters, what needs to happen"
 bun ~/.pal/tools/thread.ts --resolve --id <id>
 ```
 
-**4. Opinion capture** — scan the conversation for moments where the user:
+**6. Opinion capture** — scan the conversation for moments where the user:
 - Confirmed something you did: "yes exactly", "keep doing that", "10 rated", accepted without pushback
 - Corrected something you did: "no", "don't do that", "stop", "that's not what I meant"
 - Revealed a preference by repeating a pattern (asked for concise answers twice, always checked PAI first, etc.)
@@ -237,7 +286,7 @@ bun ~/.pal/skills/opinion/tools/opinion.ts add "the preference" --category commu
 
 Skip if nothing in the conversation touched preferences or working style.
 
-**5. Wisdom Frame** (Extended+ only) — if the session produced a genuine, reusable insight:
+**7. Wisdom Frame** (Extended+ only) — if the session produced a genuine, reusable insight:
 
 ```bash
 bun ~/.pal/tools/wisdom-frame.ts --domain <domain> --observation "insight" [--type principle|contextual-rule|anti-pattern|evolution]

package/assets/templates/PAL/PROJECT_LIFECYCLE.md

@@ -0,0 +1,48 @@
+# Project Lifecycle
+
+You (the AI) own the project lifecycle. Project state lives in `~/.pal/memory/state/progress/{slug}.json`, one file per project, managed via `bun ~/.pal/tools/project.ts`. Active projects are auto-injected into every SessionStart context regardless of cwd.
+
+## When to invoke the CLI
+
+**Proactive registration.** When SessionStart context says `💡 cwd <path> is not yet registered; suggest registering if substantive work begins`, AND the user starts substantive work (not just "hi"), surface the suggestion conversationally before the second tool call: *"I see we're in `<basename>` and it's not registered yet — want me to add it as a project?"*
+
+- **Default name** = the FULL last path segment of `cwd`, lowercased. For `/repos/portable-agent-layer` the default is `portable-agent-layer`. Never split on `-`.
+- **Confirm before creating.** Never auto-create without explicit user approval ("yes", "do it", "register").
+- **Capture objectives in conversation.** If the user accepts but doesn't volunteer objectives, ask one short question; or infer from the last few messages and confirm.
+
+**Append as you go.** When the user describes plans, blockers, or decisions during normal work, invoke the relevant subcommand to keep state current — that's the dynamism this system is built for.
+
+| user says | you call |
+|---|---|
+| "let's also add X" / "we should handle Y next" | `add-next <name> "..."` |
+| "we're blocked on Z" / "Z is blocking this" | `add-blocker <name> "..."` |
+| "the objective here is to ship X by Y" | `add-objective <name> "..."` |
+| "the API base is at Z" / "tech stack is Bun + TS" — stable, reference-flavored facts | `add-fact <name> "..."` |
+| "we decided to use A because B" | `add-decision <name> "A" "B"` |
+| "let's pause this" / "shelve it" | `pause <name>` |
+| "we shipped" / "this is done" | `complete <name>` |
+
+**Don't** invoke for fleeting comments, hypotheticals, or things the user is just thinking through. Wait for a clear declarative ("let's add X", "Z is blocking us"), not a question or musing.
+
+## When NOT to suggest registration
+
+- cwd has no project marker (`.git`, `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, etc.) — it's a notes folder, not a project.
+- The user is clearly browsing or doing a one-off task.
+- An ancestor of multiple registered projects is the cwd (e.g. `~/Development/git/`) — that's browse mode by design.
+- You're unsure. Err toward not registering.
+
+## CLI cheat sheet
+
+```
+list                                          show all projects
+create [name] [--path PATH] [--objectives X]  register (defaults: name=basename(cwd), path=cwd)
+resume <name>                                 print full project JSON
+complete | archive | pause | unpause <name>   change status
+add-fact | add-objective | add-next | add-blocker <name> "text"
+add-decision <name> "decision" "rationale"
+add-handoff <name> "text"
+rm-fact | rm-objective | rm-next | rm-blocker <name> <index>
+rm <name>                                     delete the project file (rare; prefer archive)
+```
+
+The Stop hook auto-touches `updated` (and optionally writes a `handoff`) whenever cwd resolves to an active project — you don't need to refresh timestamps manually.

package/assets/templates/PAL/README.md

@@ -21,7 +21,7 @@ PAL is a persistent, cross-platform, cross-agent layer for portable AI workflows
   tools/                           # Agent CLI tools (symlink → repo src/tools/agent/)
   skills/                          # Installed skills (symlinks → assets/skills/)
   telos/                           # User life context (TELOS)
-    MISSION.md, GOALS.md, PROJECTS.md, BELIEFS.md,
+    MISSION.md, GOALS.md, BELIEFS.md,
     CHALLENGES.md, STRATEGIES.md, IDEAS.md, LEARNED.md,
     MODELS.md, NARRATIVES.md
 

package/assets/templates/PAL/STEERING_RULES.md

@@ -45,3 +45,7 @@ Correct: Review your recent actions → find the mistake → fix it → explain
 **Act on what you know.** When tracked opinions or relationship notes reveal user preferences, apply them to your behavior. If you know the user prefers concise responses, be concise. If they prefer manual commits, never offer to commit.
 Bad: Memory says user dislikes verbose summaries → you write a 3-paragraph recap after every change.
 Correct: Memory says user dislikes verbose summaries → you keep the summary to one line.
+
+**Don't trust, verify.** When adding a test or asserting a change works, prove it by making it fail first. A test that passes without ever being broken demonstrates nothing — it may be testing the wrong thing or nothing at all. Break it intentionally, confirm it fails for the right reason, then restore it.
+Bad: Add a test, see it green, move on. The test may pass vacuously.
+Correct: Add the test → run it green → break the code it covers → confirm it goes red → restore → now it's a real test.

package/assets/templates/PAL/SYSTEM_ARCHITECTURE.md

@@ -233,6 +233,7 @@ Brief description.
 │                     │    - Work learning capture
 │                     │    - Failure logging
 │                     │    - Reflect trigger check
+│                     │    - Write context digests (semi-static sources)
 │                     │    - Auto-backup
 │                     │    - Count updates
 │                     │    - Tab reset
@@ -357,34 +358,44 @@ Relationship notes (O/B types)
 
 ## Context Loading Architecture
 
-### Two-Layer Design
+### Three-Tier Design
 
-**Static context** (loaded natively by the agent):
-- CLAUDE.md — identity, modes, context routing table
-- Loaded once at session start, always available
+**Tier 1 — Operational** (loaded natively at agent startup):
+- CLAUDE.md / AGENTS.md — identity, modes, context routing table
+- Loaded once per session, always available, never re-fetched
 
-**Dynamic context** (injected by LoadContext hook):
-- Changes per-session, can't live in a static file
-- Injected as `<system-reminder>` block to stdout
+**Tier 2 — Semi-static** (pre-compiled at previous session stop, loaded natively):
+- Self-model, wisdom, opinions, synthesis, failures, steering rules
+- Written to disk by `writeContextDigests()` at Stop time
+- Loaded natively per-agent: `@imports` in CLAUDE.md (Claude Code), `instructions[]` in opencode config, `.mdc` rules in `~/.cursor/rules/` (Cursor), `.instructions.md` in `~/.copilot/instructions/` (Copilot)
+- Content is global/user-level — safe to pre-compile (not project-scoped)
+
+**Tier 3 — Dynamic** (injected fresh each session by LoadContext hook):
+- Handoff notes, session intelligence, open threads, relationship notes, project history
+- Changes per-session or is project-scoped — can't be pre-compiled
+- Injected as `<system-reminder>` block via stdout
 - Each section independently toggleable in `pal-settings.json → dynamicContext`
 
-### Injection Order
+### Semi-Static Registry
+
+All semi-static sources are defined in `src/hooks/lib/semi-static.ts` via `getSemiStaticSources()`. Adding one entry there propagates automatically to every consumer — no other files need to change.
+
+### Dynamic Injection Order
 
 ```
 LoadContext.ts
   │
   ├─► Regenerate CLAUDE.md if template/telos changed
   │
-  └─► Build system-reminder:
+  └─► Build system-reminder (dynamic sections only):
       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)
+      2. Handoff note (in-progress work from last session)
+      3. Session intelligence (rating trend, algorithm performance)
+      4. Open threads (current project only)
+      5. Recent interaction notes (last 2 days)
+      6. Active projects
+      7. Project session history (this project)
+      8. Signal trends (today/week/trend)
 ```
 
 ### On-Demand Context
@@ -436,6 +447,9 @@ src/targets/
 ├── cursor/          # Cursor specific
 │   ├── install.ts   # Register hooks + skills in ~/.cursor/
 │   └── uninstall.ts
+├── copilot/         # GitHub Copilot specific
+│   ├── install.ts   # Write instruction files + update VS Code settings
+│   └── uninstall.ts
 └── lib.ts           # Shared: JSON read/write, settings merge, TELOS scaffold
 ```
 
@@ -452,6 +466,7 @@ All paths resolve through `src/hooks/lib/paths.ts`:
 | Claude config | `~/.claude` | `PAL_CLAUDE_DIR` |
 | opencode config | `~/.config/opencode` | `PAL_OPENCODE_DIR` |
 | Cursor config | `~/.cursor` | `PAL_CURSOR_DIR` |
+| Copilot config | `~/.copilot` | `PAL_COPILOT_DIR` |
 | Codex config | `~/.codex` | `PAL_CODEX_DIR` |
 | Agents dir | `~/.agents` | `PAL_AGENTS_DIR` |
 

package/assets/templates/PAL/WORK_TRACKING.md

@@ -4,4 +4,4 @@ PAL tracks your work across sessions in `memory/state/sessions.json` (auto-captu
 
 ## Projects
 
-Projects are managed in `telos/PROJECTS.md` and force-loaded at session startup via `pal-settings.json → loadAtStartup.files`.
+Projects are managed via the `/projects` skill. State lives in `~/.pal/memory/state/progress/{slug}.json`, one file per project. Inspect with `bun ~/.pal/tools/project.ts list`; manage via `~/.pal/docs/PROJECT_LIFECYCLE.md`.

package/assets/templates/hooks.codex.json

@@ -0,0 +1,44 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "PAL_AGENT=codex bun run {{PKG_ROOT}}/src/hooks/LoadContext.ts"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "PAL_AGENT=codex bun run {{PKG_ROOT}}/src/hooks/UserPromptOrchestrator.ts"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "PAL_AGENT=codex bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "PAL_AGENT=codex bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts"
+          }
+        ]
+      }
+    ]
+  }
+}

package/assets/templates/hooks.cursor.json

@@ -4,29 +4,35 @@
     "sessionStart": [
       {
         "type": "command",
-        "command": "bun run {{PKG_ROOT}}/src/hooks/LoadContext.ts"
+        "command": "PAL_AGENT=cursor bun run {{PKG_ROOT}}/src/hooks/LoadContext.ts"
       }
     ],
     "beforeSubmitPrompt": [
       {
         "type": "command",
-        "command": "bun run {{PKG_ROOT}}/src/hooks/UserPromptOrchestrator.ts"
+        "command": "PAL_AGENT=cursor bun run {{PKG_ROOT}}/src/hooks/UserPromptOrchestrator.ts"
       }
     ],
     "preToolUse": [
       {
         "type": "command",
-        "command": "bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts"
+        "command": "PAL_AGENT=cursor bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts"
       },
       {
         "type": "command",
-        "command": "bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts"
+        "command": "PAL_AGENT=cursor bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts"
+      }
+    ],
+    "beforeShellExecution": [
+      {
+        "type": "command",
+        "command": "PAL_AGENT=cursor bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts"
       }
     ],
     "stop": [
       {
         "type": "command",
-        "command": "bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts"
+        "command": "PAL_AGENT=cursor bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts"
       }
     ]
   }

package/assets/templates/pal-settings.json

@@ -13,9 +13,7 @@
   },
   "loadAtStartup": {
     "_docs": "Files force-loaded into session context at startup. Injected as <system-reminder> blocks.",
-    "files": [
-      "~/.pal/docs/STEERING_RULES.md"
-    ]
+    "files": []
   },
   "dynamicContext": {
     "_docs": "Dynamic context sections injected at session start. Set to false to disable.",

package/assets/templates/settings.claude.json

@@ -97,5 +97,6 @@
         ]
       }
     ]
-  }
+  },
+  "autoMemoryEnabled": false
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.35.0",
+  "version": "0.37.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -41,6 +41,7 @@
     "check": "biome check",
     "check-write": "biome check --write",
     "knip": "knip-bun",
+    "arch-check": "bun flint/cli.ts",
     "lint-staged": "lint-staged",
     "prepare": "bun .husky/install.mjs",
     "install:all": "bun run src/cli/index.ts cli install",