portable-agent-layer 0.86.0 → 0.86.2

package/README.md

@@ -91,6 +91,7 @@ pal cli status        # check your setup
 | `pal cli timezone [<zone>]` | Show or set your timezone. IANA names only, validated before it is stored |
 | `pal cli knowledge` | Query & manage the knowledge store (search, graph, stats, hubs, find, show, add, ls, ingest) |
 | `pal cli ledger` | Query the action ledger — `log`, `show <id>`, `stats`, filtered by `--project`, `--since`, `--actor`, `--machine`, `--runtime`, `--outcome`, `--tool`, `--target` |
+| `pal cli rule` | Review the rules drafted from your corrections — `list [--all] [--json]`, `approve <id>`, `deny <id>`. A draft steers nothing until approved; a denied one is never drafted again |
 | `pal cli server` | The morning screen: a local page to open before a terminal — three moves for today, an urgent/important grid over every project *and* every stated goal, where you left off, and a drawer holding the signal and the action ledger — `start [--port <n>]`, `stop`, `status`. Loopback only, default port 7250. No model runs on page load |
 | `pal cli skill link <name>` | Link a personal `~/.pal/skills/<name>/` into every installed agent so it is discoverable |
 | `pal cli skill doctor <name>` | Evaluate a skill against the authoring best practices (folder/file-name match, name, description, body length, point-of-view, reference depth) |
@@ -203,7 +204,7 @@ PAL ships with built-in skills that extend your agent's capabilities:
 | `presentation` | Build branded slide decks from outlines |
 | `projects` | Look up, resume, register, or manage tracked projects |
 | `reflect` | Diagnose why a PAL behavior didn't trigger |
-| `telos` | Inspect or update goals, beliefs, strategies, narratives |
+| `rule-review` | Approve or deny the rules PAL drafted from your corrections || `telos` | Inspect or update goals, beliefs, strategies, narratives |
 | `think` | Structured first-pass reasoning on a problem |
 
 ---

package/assets/skills/rule-review/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: rule-review
+license: MIT
+description: "Review the adaptation rule drafts PAL wrote from the user's corrections and record the user's approve-or-deny decision for each via the rule CLI. Use when the user asks what rule drafts are waiting, wants to review pending rules, or says to approve or deny a rule draft. Not for editing the shipped steering hints or for the opinion tracker."
+argument-hint: "[list | approve <id> | deny <id>]"
+metadata:
+  source: portable-agent-layer
+  triggers:
+    - "rule-review"
+    - "rule review"
+    - "rule drafts"
+    - "pending rules"
+    - "review rules"
+    - "approve the rule"
+    - "deny the rule"
+    - "adaptation rules"
+---
+
+# Rule review
+
+An adaptation rule is "when this situation happens (trigger), steer the assistant like this (steering)", backed by evidence from the user's past corrections. PAL drafts them; every rule starts as a draft and steers nothing until the user approves it. A denied draft stays on record so it is never drafted again. A draft can only be approved or denied, never edited.
+
+Your job: show the user the drafts and record their decision. The decision is the user's alone. Never approve or deny a draft the user has not explicitly decided on.
+
+## Workflow
+
+### 1. List the drafts
+
+When the user asks what rule drafts are waiting, wants to review rules, or invokes the skill without an id, run:
+
+```bash
+pal cli rule list
+```
+
+Each draft prints as:
+
+```
+<id>  [draft]  <situation>
+  trigger (<prompt|reply>): <pattern>
+  steering: <steering>
+  evidence: <line>
+```
+
+- If the output is `No drafts waiting.`, tell the user that and stop.
+- Otherwise present every draft in the format under "Output format", then ask the user to approve or deny each one. Keep the ids from this listing; they are what a follow-up decision refers to.
+
+When the user asks about rules already decided (approved, denied, history, all rules), run `pal cli rule list --all` instead and present them the same way, showing each rule's status.
+
+### 2. Resolve which draft the user means
+
+Map the user's decision to exactly one draft id before running anything:
+
+- The user names an id → use that id.
+- The user says "approve it", "deny it", "approve", "deny", "yes approve", or "reject" right after you presented exactly one draft → use that draft's id.
+- The user says "approve them all" or "deny all" after a listing → one command per listed id, in the order listed.
+- The user refers to a draft by its content ("the one about commit messages") and exactly one presented draft matches → use its id.
+- Anything else, including several drafts presented with no id named, or a decision given before any listing in this conversation → do not guess. Run step 1 if there is no listing yet, then ask which id the user means.
+
+A bare "yes", "ok", "fine", or "looks good" is not a decision. Ask "approve or deny <id>?" and wait.
+
+### 3. Record the decision
+
+Run the matching command:
+
+```bash
+pal cli rule approve <id>
+pal cli rule deny <id>
+```
+
+Report the CLI's result line verbatim, e.g. `Rule 3f9a1c2e approved: <situation>`.
+
+If the command exits 1, report its reason verbatim. The reasons are `No rule with id <id>` and `Rule <id> was already <approved|denied>`. On the first, re-run `pal cli rule list` and show the current ids. On the second, say the draft was already decided and leave it.
+
+### 4. Handle requests to change a draft
+
+Editing a draft is not supported, so never offer it and never rewrite a draft's text yourself. When the user wants a different wording, scope, or steering, say so and give the two options: deny the draft, or approve it as is. Then wait for that decision.
+
+## Output format
+
+Present each draft as one compact block, nothing else in between:
+
+```
+Draft <id>
+  When:     <situation>
+  Steer:    <steering>
+  Evidence: <evidence line>
+            <evidence line>
+```
+
+Follow the list with one question, e.g. "Approve or deny each? Reply with the id and your decision." After a single draft, "Approve or deny <id>?" is enough.
+
+After each decision, output the CLI's result line (or error reason) verbatim and nothing more unless the user asked a question.
+
+## When to use
+
+- The user asks what rule drafts are pending, waiting, or need review.
+- The user asks to review, approve, or deny an adaptation rule.
+- The user says "approve it" or "deny it" right after you presented a draft.
+- The user asks which rules have been approved or denied so far.
+
+## Do NOT use
+
+- To change the shipped contextual-steering hints. Those live under the `steering` key in `pal-settings.json`, not in rules.
+- For the opinion tracker (confirming or contradicting a tracked preference). That is the `opinion` skill.
+- To edit, reword, or merge a draft. Editing is not supported; the only outcomes are approve or deny.
+- To approve or deny on the user's behalf because a draft "looks reasonable". Wait for the explicit decision.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.86.0",
+  "version": "0.86.2",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/index.ts

@@ -17,6 +17,7 @@
  *   doctor                            Check prerequisites and system health
  *   usage                             Summarize token usage and cost
  *   ledger <sub> [filters]            Query the action ledger (log · show · stats)
+ *   rule list|approve|deny [id]       Review rules drafted from your corrections
  *   server start|stop|restart|status  The control room, a local page over ~/.pal
  *   <tool> [args]                     Run a built-in agent tool (project, thread, analyze, …)
  *   skill run <skill> <tool> [-- args]  Run a skill's own tool by name, not by path
@@ -202,6 +203,12 @@ async function runCli(command: string | undefined, args: string[]) {
       if (code !== 0) process.exit(code);
       break;
     }
+    case "rule": {
+      const { runRule } = await import("./rule");
+      const code = await runRule(args);
+      if (code !== 0) process.exit(code);
+      break;
+    }
     case "server": {
       const { runServer } = await import("./server");
       const code = await runServer(args);
@@ -298,6 +305,7 @@ function showHelp() {
                                             (search · graph · stats · hubs · find · show · add · ls)
     pal cli ledger <sub> [filters]          Query the action ledger (log · show · stats)
                                             e.g. ledger log --project X --since 7d
+    pal cli rule list|approve|deny [id]     Review rules drafted from your corrections
     pal cli server start|stop|restart|status  The control room: a local page to open before a terminal
     pal cli skill run <skill> <tool> [-- args]  Run ~/.pal/skills/<skill>/tools/<tool> by name
     pal cli skill link <name>               Link a personal ~/.pal/skills/<name>/ into installed agents
@@ -879,7 +887,8 @@ async function update() {
   clearUpdateCache();
 
   log.info("Reinstalling...");
-  process.exit(await install(resolveTargets([]), []));
+  const { reinstallInFreshProcess } = await import("./reinstall");
+  process.exit(reinstallInFreshProcess());
 }
 
 function cliDebug(args: string[]) {

package/src/cli/reinstall.ts

@@ -0,0 +1,13 @@
+import { spawnSync } from "node:child_process";
+
+/**
+ * An update replaces PAL's files under a process that already holds the old
+ * modules in Bun's cache, so a new installer importing a new export would bind
+ * against the stale module and throw. A fresh process loads everything from disk.
+ */
+export function reinstallInFreshProcess(entry: string = process.argv[1]): number {
+  const run = spawnSync(process.execPath, [entry, "cli", "install"], {
+    stdio: "inherit",
+  });
+  return run.status ?? 1;
+}

package/src/cli/rule.ts

@@ -0,0 +1,77 @@
+/**
+ * pal cli rule — review the adaptation rules drafted from the user's corrections.
+ *
+ * Subcommands:
+ *   list [--all] [--json]   Drafts waiting for a decision (--all: every rule)
+ *   approve <id>            Turn a draft into a rule that steers
+ *   deny <id>               Reject a draft; it stays on record so it is not redrafted
+ */
+
+import {
+  type AdaptationRule,
+  decideRule,
+  type RuleStatus,
+  readRules,
+} from "../hooks/lib/adaptation-rules";
+
+const DECISIONS: Record<string, Exclude<RuleStatus, "draft">> = {
+  approve: "approved",
+  deny: "denied",
+};
+
+export async function runRule(args: string[]): Promise<number> {
+  const [sub, ...rest] = args;
+  if (sub === "list") return cmdList(rest);
+  if (sub && sub in DECISIONS) return cmdDecide(rest[0], DECISIONS[sub]);
+  showHelp();
+  return sub === undefined || sub === "help" ? 0 : 1;
+}
+
+function cmdList(args: string[]): number {
+  const all = args.includes("--all");
+  const rules = readRules().filter((r) => all || r.status === "draft");
+  if (args.includes("--json")) {
+    console.log(JSON.stringify(rules, null, 2));
+    return 0;
+  }
+  if (rules.length === 0) {
+    console.log(all ? "No rules yet." : "No drafts waiting.");
+    return 0;
+  }
+  console.log(rules.map(formatRule).join("\n\n"));
+  return 0;
+}
+
+function formatRule(rule: AdaptationRule): string {
+  return [
+    `${rule.id}  [${rule.status}]  ${rule.when}`,
+    `  trigger (${rule.trigger.side}): ${rule.trigger.pattern}`,
+    `  steering: ${rule.steering}`,
+    ...rule.evidence.map((e) => `  evidence: ${e}`),
+  ].join("\n");
+}
+
+function cmdDecide(
+  id: string | undefined,
+  decision: Exclude<RuleStatus, "draft">
+): number {
+  if (!id) {
+    console.error("Give the rule id: pal cli rule approve|deny <id>");
+    return 1;
+  }
+  const result = decideRule(id, decision);
+  if (!result.ok) {
+    console.error(result.reason);
+    return 1;
+  }
+  console.log(`Rule ${id} ${decision}: ${result.rule.when}`);
+  return 0;
+}
+
+function showHelp(): void {
+  console.log(`pal cli rule — review adaptation rules drafted from your corrections
+
+  pal cli rule list [--all] [--json]   Drafts waiting for a decision
+  pal cli rule approve <id>            Approve a draft so it steers
+  pal cli rule deny <id>               Deny a draft; it is not drafted again`);
+}

package/src/hooks/lib/adaptation-rules.ts

@@ -0,0 +1,83 @@
+/**
+ * Adaptation rules: "when this happens, steer like this", learned from the
+ * user's corrections. A rule starts as a draft and only steers once the user
+ * approves it. A denied rule stays on record so the same rule is not drafted again.
+ */
+
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { paths } from "./paths";
+
+export type RuleStatus = "draft" | "approved" | "denied";
+type Decision = Exclude<RuleStatus, "draft">;
+
+interface RuleTrigger {
+  /** Whether the pattern is matched against the user's prompt or the assistant's reply. */
+  side: "prompt" | "reply";
+  pattern: string;
+}
+
+export interface DraftInput {
+  when: string;
+  trigger: RuleTrigger;
+  steering: string;
+  evidence: string[];
+}
+
+export interface AdaptationRule extends DraftInput {
+  id: string;
+  status: RuleStatus;
+  createdAt: string;
+  decidedAt?: string;
+}
+
+type DecideResult = { ok: true; rule: AdaptationRule } | { ok: false; reason: string };
+
+export function rulesPath(): string {
+  return resolve(paths.adaptation(), "rules.json");
+}
+
+export function readRules(): AdaptationRule[] {
+  const path = rulesPath();
+  if (!existsSync(path)) return [];
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8"));
+    return Array.isArray(parsed) ? (parsed as AdaptationRule[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+function writeRules(rules: AdaptationRule[]): void {
+  const path = rulesPath();
+  const pending = `${path}.${process.pid}.tmp`;
+  writeFileSync(pending, `${JSON.stringify(rules, null, 2)}\n`, "utf-8");
+  renameSync(pending, path);
+}
+
+export function addDraft(input: DraftInput): AdaptationRule {
+  const rule: AdaptationRule = {
+    ...input,
+    id: randomUUID().slice(0, 8),
+    status: "draft",
+    createdAt: new Date().toISOString(),
+  };
+  writeRules([...readRules(), rule]);
+  return rule;
+}
+
+export function decideRule(id: string, decision: Decision): DecideResult {
+  const rules = readRules();
+  const rule = rules.find((r) => r.id === id);
+  if (!rule) return { ok: false, reason: `No rule with id ${id}` };
+  if (rule.status !== "draft")
+    return { ok: false, reason: `Rule ${id} was already ${rule.status}` };
+  const decided: AdaptationRule = {
+    ...rule,
+    status: decision,
+    decidedAt: new Date().toISOString(),
+  };
+  writeRules(rules.map((r) => (r.id === id ? decided : r)));
+  return { ok: true, rule: decided };
+}

package/src/hooks/lib/paths.ts

@@ -98,6 +98,7 @@ export const paths = {
   wisdom: () => ensureDir(home("memory", "wisdom", "frames")),
   wisdomState: () => ensureDir(home("memory", "wisdom", "state")),
   relationship: () => ensureDir(home("memory", "relationship")),
+  adaptation: () => ensureDir(home("memory", "adaptation")),
   knowledge: () => ensureDir(home("memory", "knowledge")),
   knowledgeDomain: (d: string) => ensureDir(home("memory", "knowledge", d)),
   failures: () => ensureDir(home("memory", "learning", "failures")),