portable-agent-layer 0.34.0 → 0.36.0

package/README.md

@@ -102,7 +102,7 @@ pal cli install               # all available (default)
 | Claude Code | Full | Yes | Yes | Yes | Yes |
 | opencode | Full | Yes | Yes (plugin) | Yes | Yes |
 | Cursor | Full | Yes | Yes | Yes (injected via hook) | Yes |
-| GitHub Copilot | Full | Yes | Yes | Yes (via copilot-instructions.md) | Yes |
+| GitHub Copilot | Full | Yes | Yes | Yes (via `~/.copilot/instructions/*.instructions.md`) | Yes |
 | Codex | Partial | Yes | No | Yes | No |
 
 ---

package/assets/skills/presentation/SKILL.md

@@ -103,6 +103,8 @@ Exit codes: `0` = clean, `1` = errors found (or warnings under `--strict`), `2`
 
 Open `<out>/<deck-name>/<deck-name>.html` in your browser. Iterate by editing a slide, re-running the build, and refreshing the tab. Reveal shortcuts: `F` = fullscreen, `S` = speaker notes window, `?` = keyboard shortcuts, `Esc` = overview.
 
+**Print / PDF view with trainer notes.** Open the built HTML in your browser and press Cmd/Ctrl-P (no special URL param needed). The print stream interleaves trainer notes between slides — `[Slide 1][Notes 1][Slide 2][Notes 2]…` — so flipping pages reads in delivery order. Long notes flow across multiple pages. Slides without a `Note:` block produce no extra page. Each notes page carries a header identifying the source slide. Limitation: a single fenced code block inside notes cannot break across pages — the doctor warns at 30 lines (`notes-code-too-long`); split the block or shorten the example.
+
 ## Deck folder layout
 
 ```

package/assets/skills/presentation/demo/slides/004-content.md

@@ -9,4 +9,30 @@ The default. Title at top, body below.
   - And this
 - **Bold**, *italic*, `inline code`, [links](https://example.com)
 
-Note: If you don't add a `data-layout` directive, this is what you get.
+Note:
+- [Reveal.js print docs](https://revealjs.com/pdf-export/)
+- Why this slide demonstrates print-with-notes
+  - Long enough to cross a page break in the trainer print-out
+  - Mixes link, bullet hierarchy, blockquote, inline code
+  - Lets you verify the multi-page flow without authoring a fixture deck
+- Default layout — when to leave it off
+  - You want title + body, no special shape
+  - You want the layout-agnostic spacing rules to kick in
+  - You want the doctor to skip layout-shape checks
+- Bullet hygiene reminder (per SKILL.md)
+  - 2–15 words at top level, 2–10 at sub
+  - No prose paragraphs — the `prose-paragraph-in-body` rule will warn
+  - Em-dash continuation in bullets is also flagged
+- Quote example
+  > Slides are a delivery surface, not a document. Prose belongs in notes.
+- Anticipated questions
+  - "Why a 30-line cap on notes code blocks?" — single `<pre>` blocks don't break across printed pages; longer blocks clip
+  - "Can I disable the trainer-notes printout?" — yes, remove the notes injection block from the `.then()` in skeleton.html in your local override
+  - "Does the speaker view (S key) still work?" — yes, the injection only affects print, not the speaker view path
+- Forward references
+  - more on layout-specific rules in the `code` and `table` slides
+  - more on print-view polish in `base.css` under "Trainer notes in print"
+- Closing beats
+  - The print-with-notes feature exists so a trainer can hand a delegate a printed deck and a printed prep packet at once
+  - Ordering is `[Slide 1][Notes 1][Slide 2][Notes 2]…` so flipping pages reads in delivery order
+  - Slides without a `Note:` block produce zero extra pages — title cards stay clean

package/assets/skills/presentation/theme-base/base.css

@@ -436,3 +436,209 @@ html.print-pdf .reveal .slides .pdf-page {
     margin: 16px auto !important;
   }
 }
+
+/* ── Trainer notes in print (Cmd+P on the regular URL)
+ * skeleton.html injects a `.print-notes-page` div after each slide section that
+ * has speaker notes. On screen they are invisible; Cmd+P produces the ordering
+ * [Slide N][Notes N][Slide N+1][Notes N+1]…. Long notes flow across multiple
+ * pages. Slides with no Note: block produce no extra page.
+ *
+ * Key mechanics:
+ *   • `page-break-after: always` on sections forces each slide to end at a page
+ *     boundary even if its content is shorter than the page height.
+ *   • `page-break-before/after: always` on .print-notes-page ensures the notes
+ *     block starts on a fresh page and the next slide starts on a fresh page.
+ *   • `break-inside: auto` lets long notes flow across pages naturally. */
+@media print {
+  html:not(.print-pdf) .reveal .slides > section {
+    page-break-after: always !important;
+    break-after: always !important;
+  }
+
+  html:not(.print-pdf) .reveal .slides > .print-notes-page {
+    display: block !important;
+    page-break-before: always !important;
+    break-before: always !important;
+    page-break-after: always !important;
+    break-after: always !important;
+    page-break-inside: auto;
+    break-inside: auto;
+    overflow: visible !important;
+    position: static !important;
+    min-height: 0 !important;
+    padding: 36px 56px 56px 56px;
+    box-sizing: border-box;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
+      "Helvetica Neue", Arial, sans-serif;
+    font-size: 13pt;
+    line-height: 1.5;
+    color: #111;
+    background: #fff;
+  }
+
+  html:not(.print-pdf) .reveal .slides > .print-notes-page ul,
+  html:not(.print-pdf) .reveal .slides > .print-notes-page ol {
+    margin: 0.4em 0 0.8em 0;
+    padding-left: 1.4em;
+  }
+  html:not(.print-pdf) .reveal .slides > .print-notes-page li {
+    margin: 0.15em 0;
+  }
+  html:not(.print-pdf) .reveal .slides > .print-notes-page a {
+    color: var(--brand-primary, #0040c2);
+    text-decoration: underline;
+  }
+  html:not(.print-pdf) .reveal .slides > .print-notes-page code {
+    font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+    font-size: 0.92em;
+    background: #f4f4f4;
+    padding: 1px 4px;
+    border-radius: 3px;
+  }
+  html:not(.print-pdf) .reveal .slides > .print-notes-page pre {
+    font-size: 0.92em;
+    line-height: 1.4;
+    background: #f4f4f4;
+    padding: 8px 12px;
+    border-radius: 4px;
+    white-space: pre-wrap;
+    overflow: visible;
+  }
+  html:not(.print-pdf) .reveal .slides > .print-notes-page blockquote {
+    margin: 0.6em 0 0.6em 1em;
+    padding-left: 0.8em;
+    border-left: 2px solid #a0a0a0;
+    color: #444;
+    font-style: italic;
+  }
+
+  /* Slide-context header: "Notes — slide N  <slide title>" */
+  html:not(.print-pdf) .reveal .slides > .print-notes-page .print-notes-header {
+    display: flex;
+    align-items: baseline;
+    gap: 0.8em;
+    margin: 0 0 24px 0;
+    padding: 0 0 10px 0;
+    border-bottom: 1.5pt solid var(--brand-primary, #0040c2);
+    -webkit-print-color-adjust: exact;
+    print-color-adjust: exact;
+  }
+  html:not(.print-pdf) .reveal .slides > .print-notes-page .print-notes-label {
+    font-size: 11pt;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    color: var(--brand-primary, #0040c2);
+    white-space: nowrap;
+  }
+  html:not(.print-pdf) .reveal .slides > .print-notes-page .print-notes-title {
+    font-size: 13pt;
+    font-weight: 500;
+    color: #222;
+  }
+}
+
+/* ── Per-slide print chrome (logo + slide number)
+ * skeleton.html injects `.print-logo` and `.print-slide-number` into every
+ * section. On screen: invisible. In Cmd+P print: positioned at the same
+ * bottom corners as the screen-mode chrome, once per slide page.
+ *
+ * The screen-mode equivalents (.slides::after logo and .slides > .slide-number)
+ * are suppressed in print because they are positioned relative to .slides — a
+ * container that spans all pages in Cmd+P mode, putting them at the very end
+ * of the document rather than on each individual slide. */
+@media print {
+  /* Suppress the screen-mode global chrome */
+  html:not(.print-pdf) .reveal .slides::after,
+  html:not(.print-pdf) .reveal .slides > .slide-number {
+    display: none !important;
+  }
+
+  /* Sections must be position:relative so absolute children anchor to the
+   * slide page, not to the full-document .slides container. */
+  html:not(.print-pdf) .reveal .slides > section {
+    position: relative !important;
+    /* Ensure background images (logos) print on all browsers. */
+    -webkit-print-color-adjust: exact !important;
+    print-color-adjust: exact !important;
+  }
+
+  html:not(.print-pdf) .reveal .slides > section .print-logo {
+    display: block !important;
+    position: absolute;
+    bottom: 1.5rem;
+    right: 1.5rem;
+    width: 90px;
+    height: 28px;
+    background: var(--brand-logo) no-repeat right bottom / contain;
+    opacity: 0.55;
+    pointer-events: none;
+    -webkit-print-color-adjust: exact;
+    print-color-adjust: exact;
+  }
+
+  html:not(.print-pdf) .reveal .slides > section .print-slide-number {
+    display: block !important;
+    position: absolute;
+    bottom: 1.5rem;
+    left: 1.5rem;
+    font-family: var(--font-body, sans-serif);
+    font-size: 9pt;
+    font-weight: 400;
+    line-height: 28px;
+    color: #71717A;
+    letter-spacing: 0.05em;
+    pointer-events: none;
+  }
+}
+
+/* ── Layout-specific print overrides
+ * Reveal's vendored print CSS forces several properties with !important on
+ * heading and paragraph elements, which clobbers layout-specific design intent:
+ *   • h1-h6: font-size (28–20pt), color (#000), text-align (left),
+ *             letter-spacing (normal), line-height (normal)
+ *   • p, li, td: font-size (20pt), color (#000)
+ *
+ * We beat these by pairing higher-specificity selectors with !important.
+ * Reveal's rules are scoped to `html:not(.print-pdf) .reveal h1` — specificity
+ * (0,2,1). Our layout-scoped rules use `html:not(.print-pdf) .reveal
+ * section[data-layout="…"] h1` — specificity (0,3,2), which wins. */
+@media print {
+  /* big-stat — restore the dominant number that Reveal shrinks to 28pt */
+  html:not(.print-pdf) .reveal section[data-layout="big-stat"] h1 {
+    font-size: 96pt !important;
+    color: var(--brand-primary, #0E1335) !important;
+    text-align: center !important;
+    letter-spacing: -0.025em !important;
+    line-height: 0.9 !important;
+    font-weight: 800 !important;
+    -webkit-print-color-adjust: exact !important;
+    print-color-adjust: exact !important;
+  }
+  html:not(.print-pdf) .reveal section[data-layout="big-stat"] h2,
+  html:not(.print-pdf) .reveal section[data-layout="big-stat"] p {
+    color: #71717A !important;
+    text-align: center !important;
+    font-weight: 400 !important;
+  }
+
+  /* quote / pull-quote — Reveal forces p { font-size: 20pt !important }, but
+   * blockquote text lives in p elements. `inherit` re-derives the size from the
+   * blockquote element (var(--text-xl) / var(--text-2xl)), restoring design intent. */
+  html:not(.print-pdf) .reveal section[data-layout="quote"] blockquote p,
+  html:not(.print-pdf) .reveal section[data-layout="pull-quote"] blockquote p {
+    font-size: inherit !important;
+    color: inherit !important;
+  }
+}
+
+/* Screen: injected notes pages are invisible. The `@media print` block above
+ * restores display:block. Using !important because Reveal may globally set
+ * visibility rules on .slides children. */
+@media screen {
+  .reveal .slides > .print-notes-page,
+  .reveal .slides > section .print-logo,
+  .reveal .slides > section .print-slide-number {
+    display: none !important;
+  }
+}

package/assets/skills/presentation/theme-base/skeleton.html

@@ -47,6 +47,55 @@ Reveal.initialize({
   const sn = document.querySelector('.reveal > .slide-number');
   const slides = document.querySelector('.reveal .slides');
   if (sn && slides) slides.appendChild(sn);
+
+  // Inject print-only chrome (logo + slide number) into every section, and a
+  // `.print-notes-page` after each section that has notes. All injected elements
+  // are display:none on screen; Cmd+P produces [Slide N][Notes N]… ordering.
+  const sections = document.querySelectorAll('.reveal .slides > section');
+  const totalSlides = sections.length;
+  let slideNum = 0;
+  for (const section of sections) {
+    slideNum++;
+
+    const logoEl = document.createElement('div');
+    logoEl.className = 'print-logo';
+    section.appendChild(logoEl);
+
+    const numEl = document.createElement('div');
+    numEl.className = 'print-slide-number';
+    numEl.textContent = `${slideNum} / ${totalSlides}`;
+    section.appendChild(numEl);
+
+    const notesEl = section.querySelector('aside.notes');
+    if (!notesEl?.innerHTML.trim()) continue;
+
+    const heading = section.querySelector('h1, h2, h3');
+    const title = heading ? heading.textContent.trim() : '';
+
+    const page = document.createElement('div');
+    page.className = 'print-notes-page';
+
+    const hdr = document.createElement('header');
+    hdr.className = 'print-notes-header';
+    const label = document.createElement('span');
+    label.className = 'print-notes-label';
+    label.textContent = `Notes — slide ${slideNum}`;
+    hdr.appendChild(label);
+    if (title) {
+      const titleSpan = document.createElement('span');
+      titleSpan.className = 'print-notes-title';
+      titleSpan.textContent = title;
+      hdr.appendChild(titleSpan);
+    }
+    page.appendChild(hdr);
+
+    const body = document.createElement('div');
+    body.className = 'print-notes-content';
+    body.innerHTML = notesEl.innerHTML;
+    page.appendChild(body);
+
+    section.insertAdjacentElement('afterend', page);
+  }
 });
 </script>
 </body>

package/assets/skills/presentation/tools/lib/lint-rules.ts

@@ -632,6 +632,31 @@ export const RULES: Rule[] = [
     },
   },
 
+  {
+    // Notes get printed as separate pages with `showNotes: 'separate-page'`.
+    // Browsers split long *list* content across pages cleanly, but a single
+    // fenced code block inside notes is one indivisible element — if it runs
+    // longer than one printed page it gets clipped. Warn at 30 lines so the
+    // author can split or shorten before the trainer discovers it on paper.
+    name: "notes-code-too-long",
+    scope: "slide",
+    check: (ctx) => {
+      const notes = extractNotes(ctx.body);
+      if (!notes.trim()) return [];
+      const findings: Finding[] = [];
+      for (const n of codeBlockLineCounts(notes)) {
+        if (n > 30) {
+          findings.push({
+            rule: "notes-code-too-long",
+            severity: "W",
+            msg: `notes code block has ${n} lines — won't break across printed pages cleanly (limit 30)`,
+          });
+        }
+      }
+      return findings;
+    },
+  },
+
   // ── Deck-scope rules (Tier 3) ───────────────────────────────────────────
 
   {

package/assets/skills/projects/SKILL.md

@@ -101,7 +101,6 @@ User: "mark <project> as complete"
 - **Don't dump the full JSON.** Summarize. The user can ask for the raw payload.
 - **Don't write without confirming the field choice on ambiguous "store" requests.** A "fact" sticks forever; a "next step" implies follow-up — these are different commitments.
 - **Don't edit the JSON files directly.** Always use the CLI — it timestamps `updated` and keeps the schema valid.
-- **Don't re-introduce `~/.pal/telos/PROJECTS.md`.** That file and its `update-projects.ts` tool are deprecated. The legacy `telos` skill carries a deprecation notice for this reason.
 - **Don't confuse `add-fact` with the `telos` skill's `LEARNED.md` or `IDEAS.md`.** Project facts are scoped to one project; TELOS lessons are cross-cutting.
 
 ## Rules

package/assets/skills/telos/SKILL.md

@@ -1,12 +1,9 @@
 ---
 name: telos
-description: Personal context management. Use when discussing goals, beliefs, challenges, identity, updating telos, life context, changing a goal, priorities, what do I believe, current obstacles, mission, or strategies.
+description: Personal context management. Use when discussing goals, beliefs, challenges, identity, updating telos, life context, changing a goal, what do I believe, current obstacles, mission, or strategies.
 argument-hint: [area to view or update]
 ---
 
-> ⚠️ **DEPRECATION NOTICE — Project management has moved.**
-> Project tracking is now handled by the `projects` skill, backed by `~/.pal/tools/project.ts` and per-project state in `~/.pal/memory/state/progress/`. **Do not use this skill for projects.** The `PROJECTS.md` references and `update-projects.ts` tool below are legacy and slated for removal — they remain only because the initial setup wizard (`src/cli/setup-telos.ts`) still depends on them. For anything project-related, invoke the `projects` skill.
-
 Manage the user's TELOS files — the persistent personal context that drives PAL.
 
 ## TELOS Files
@@ -16,7 +13,6 @@ All files live in `~/.pal/telos/`:
 | File | Contains |
 |------|----------|
 | `GOALS.md` | Short/medium/long-term goals |
-| `PROJECTS.md` | Active projects, status, priority |
 | `BELIEFS.md` | Core principles and values |
 | `CHALLENGES.md` | Current obstacles |
 | `MISSION.md` | Purpose and direction |
@@ -32,33 +28,18 @@ Read the file directly from `~/.pal/telos/` when the user asks about any area. S
 
 ## Updating
 
-### General TELOS files (append)
-
-For all files except PROJECTS.md — appends content, creates backup, logs the change:
+Appends content, creates backup, logs the change:
 
 ```bash
 bun ~/.pal/skills/telos/tools/update-telos.ts <FILE> "<content>" "<description>"
 ```
 
-### Projects (upsert by ID)
-
-For PROJECTS.md — upserts a row by the ID column. Replaces if the ID exists, appends if new:
-
-```bash
-bun ~/.pal/skills/telos/tools/update-projects.ts <id> "<row>" "<description>"
-```
-
-The ID is the first column of the table. Use short, lowercase, kebab-case slugs (e.g., `my-project`, `side-gig`).
-
 ## Routing
 
 | Intent | Action |
 |--------|--------|
-| "what am I working on", "my projects", "priorities" | Read `PROJECTS.md`, summarize active work |
 | "my goals", "what are my goals" | Read `GOALS.md`, present current state |
-| "update goals/projects/beliefs/challenges" | Read the target file, discuss changes with user, then run update tool |
-| "add a project", "new project" | Read `PROJECTS.md`, confirm with user, run update tool |
-| "complete/remove a project" | Read `PROJECTS.md`, confirm with user, update status via tool |
+| "update goals/beliefs/challenges" | Read the target file, discuss changes with user, then run update tool |
 | "what do I believe", "my principles" | Read `BELIEFS.md` |
 | "current obstacles", "challenges" | Read `CHALLENGES.md` |
 | "I learned something", "lesson" | Discuss, then append to `LEARNED.md` via tool |
@@ -67,38 +48,12 @@ The ID is the first column of the table. Use short, lowercase, kebab-case slugs
 
 ## Examples
 
-**Example 1: Checking projects**
-```
-User: "what am I working on?"
-→ Read PROJECTS.md
-→ Summarize active work by priority — don't list every column
-→ Highlight status changes, blockers, what needs attention
-```
-
-**Example 2: Adding a project**
-```
-User: "add my new side project"
-→ Ask: "What's the project name, status, and priority?"
-→ User provides details
-→ Show the row you'll add, confirm
-→ Run: bun ~/.pal/skills/telos/tools/update-projects.ts side-project "| side-project | Side Project | In progress | Medium | Description |" "Added Side Project"
-```
-
-**Example 3: Updating a project**
-```
-User: "mark X as complete"
-→ Read PROJECTS.md, find the entry and its ID
-→ Show updated row, confirm
-→ Run: bun ~/.pal/skills/telos/tools/update-projects.ts some-id "| some-id | Project Name | Complete | High | ... |" "Marked project as complete"
-→ The existing row is replaced, not duplicated
-```
-
-**Example 4: Updating goals**
+**Updating goals**
 ```
 User: "I finished the migration, update my goals"
 → Read GOALS.md to see current state
 → Discuss what changed — what's done, what's next
-→ Run tool with --id to update existing goal entry
+→ Run tool with updated content
 → Remind: CLAUDE.md regenerates next session
 ```
 
@@ -106,8 +61,8 @@ User: "I finished the migration, update my goals"
 
 - **Don't dump raw file contents.** Summarize what's relevant to the user's question. They can ask for the full file if needed.
 - **Don't update without confirming.** Always show what you'll change and get a "yes" before running the tool.
-- **Don't create new TELOS files.** Only the 10 listed files are valid. If something doesn't fit, suggest the closest match.
-- **Don't mix TELOS with identity.** AI/principal identity lives in `pal-settings.json`, not TELOS. TELOS is personal context — goals, beliefs, projects.
+- **Don't create new TELOS files.** Only the 9 listed files are valid. If something doesn't fit, suggest the closest match.
+- **Don't mix TELOS with identity.** AI/principal identity lives in `pal-settings.json`, not TELOS. TELOS is personal context — goals, beliefs, challenges.
 - **Don't reference stale data.** If TELOS was loaded earlier in the session via context routing, re-read the file before updating — it may have changed.
 
 ## Rules

package/assets/templates/AGENTS.md.template

@@ -55,6 +55,7 @@ Start your response with the following header in this mode:
 
 - **Mandatory output format** — Every response MUST use exactly one of the output formats above (ALGORITHM, NATIVE, or MINIMAL). No freeform output.
 - **Response format before questions** — Always complete the current response format output FIRST, then invoke AskUserQuestion at the end.
+- **Named project → resume first** — Whenever the user references a project by name in ANY mode, run `bun ~/.pal/tools/project.ts resume <slug>` before any file search or task execution. The project record has paths, context, and handoff notes that make manual searching unnecessary.
 
 ---
 
@@ -73,7 +74,7 @@ Load context on-demand by reading the file at the path listed. Only load what th
 | Opinion tracking | `~/.pal/docs/OPINION_TRACKING.md` |
 | Steering rules | `~/.pal/docs/STEERING_RULES.md` |
 | Algorithm (complex work phases) | `~/.pal/docs/ALGORITHM.md` |
-| Project lifecycle (when/how to register and manage user projects) | `~/.pal/skills/projects/SKILL.md` |
+| Project lookup AND lifecycle (find paths, resume state, register, manage) | `~/.pal/skills/projects/SKILL.md` |
 
 ### User Context (TELOS)
 

package/assets/templates/PAL/ALGORITHM.md

@@ -206,7 +206,32 @@ 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/relationship-note.ts --b "description"
+```
+
+- 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 Threads** — for each unresolved question, decision, or follow-up that came up during this session:
 
 ```bash
 bun ~/.pal/tools/thread.ts --add --title "brief title" --context "why it matters, what needs to happen"
@@ -218,7 +243,7 @@ Only add threads that genuinely need follow-up. Resolve existing threads if this
 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 +262,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.