portable-agent-layer 0.35.0 → 0.37.0

package/src/tools/agent/project.ts

@@ -1,30 +1,30 @@
 #!/usr/bin/env bun
 /**
- * Project — register and manage user projects via per-project progress JSONs.
+ * Project — register and manage user projects via ISA.md files.
  *
- * Replaces the hand-edited `~/.pal/telos/PROJECTS.md`. The AI is the primary
- * caller (proactive registration on unregistered cwds, append-as-you-go updates);
- * the user is the escape hatch for fine-grained control.
- *
- * State: `~/.pal/memory/state/progress/{slug}.json`. Auto-touched on Stop hook
- * when cwd resolves into a registered project.
+ * Each project is stored at `~/.pal/memory/projects/{slug}/ISA.md`.
+ * Frontmatter holds operational state; body holds ISA spec sections.
  *
  * Usage:
  *   bun ~/.pal/tools/project.ts list
  *   bun ~/.pal/tools/project.ts create [name] [--path PATH] [--objectives "..."]
  *   bun ~/.pal/tools/project.ts resume <name>
  *   bun ~/.pal/tools/project.ts complete | archive | pause | unpause <name>
- *   bun ~/.pal/tools/project.ts add-fact <name> "text"
- *   bun ~/.pal/tools/project.ts add-objective <name> "text"
  *   bun ~/.pal/tools/project.ts add-next <name> "text"
  *   bun ~/.pal/tools/project.ts add-blocker <name> "text"
  *   bun ~/.pal/tools/project.ts add-decision <name> "decision" "rationale"
  *   bun ~/.pal/tools/project.ts add-handoff <name> "text"
- *   bun ~/.pal/tools/project.ts rm-fact | rm-objective | rm-next | rm-blocker <name> <index>
+ *   bun ~/.pal/tools/project.ts rm-next | rm-blocker <name> <index>
+ *   bun ~/.pal/tools/project.ts update-section <name> <section> "content"
+ *   bun ~/.pal/tools/project.ts criteria <name>
+ *   bun ~/.pal/tools/project.ts isa-init <name>
+ *   bun ~/.pal/tools/project.ts migrate
  */
 
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { parseArgs } from "node:util";
+import { paths } from "../../hooks/lib/paths";
 import {
   defaultSlug,
   deleteProject,
@@ -65,8 +65,7 @@ function cmdList(): void {
     path: p.path,
     updated: p.updated,
     stale: isStale(p),
-    objectives: p.objectives?.length ?? 0,
-    next_steps: p.next_steps?.length ?? 0,
+    next: p.next?.length ?? 0,
     blockers: p.blockers?.length ?? 0,
   }));
   ok({ count: all.length, projects: rows });
@@ -100,11 +99,13 @@ function cmdCreate(args: string[]): void {
     );
   }
 
-  const objectives = values.objectives
+  const goalLines = values.objectives
     ? values.objectives
         .split(/[\n;|]/)
         .map((s) => s.trim())
         .filter(Boolean)
+        .map((s) => `- ${s}`)
+        .join("\n")
     : undefined;
 
   const project: ProjectProgress = {
@@ -113,7 +114,7 @@ function cmdCreate(args: string[]): void {
     status: "active",
     created: now(),
     updated: now(),
-    objectives,
+    ...(goalLines ? { goal: goalLines } : {}),
   };
   writeProject(project);
   ok({ created: true, project });
@@ -137,14 +138,10 @@ function setStatus(name: string, status: ProjectStatus): void {
   ok({ updated: true, name, status });
 }
 
-// ── append helpers ────────────────────────────────────────────────
+// ── append/remove for array fields ───────────────────────────────
 
-function appendItem(
-  name: string,
-  field: "facts" | "objectives" | "next_steps" | "blockers",
-  text: string
-): void {
-  if (!text?.trim()) fail(`Empty ${field.replace("_", " ")} text.`);
+function appendItem(name: string, field: "next" | "blockers", text: string): void {
+  if (!text?.trim()) fail(`Empty ${field} text.`);
   const p = requireProject(name);
   const list = p[field] ?? [];
   list.push(text.trim());
@@ -154,11 +151,7 @@ function appendItem(
   ok({ updated: true, name, field, count: list.length });
 }
 
-function removeItem(
-  name: string,
-  field: "facts" | "objectives" | "next_steps" | "blockers",
-  indexArg: string
-): void {
+function removeItem(name: string, field: "next" | "blockers", indexArg: string): void {
   const idx = parseInt(indexArg, 10);
   if (!Number.isInteger(idx) || idx < 0) fail(`Invalid index "${indexArg}".`);
   const p = requireProject(name);
@@ -171,18 +164,22 @@ function removeItem(
   ok({ updated: true, name, field, removed, count: list.length });
 }
 
+// ── decisions (body section append) ──────────────────────────────
+
 function addDecision(name: string, decision: string, rationale: string): void {
   if (!decision?.trim() || !rationale?.trim())
     fail("Usage: add-decision <name> <decision> <rationale>");
   const p = requireProject(name);
-  const list = p.decisions ?? [];
-  list.push({ ts: now(), decision: decision.trim(), rationale: rationale.trim() });
-  p.decisions = list;
+  const date = new Date().toISOString().slice(0, 10);
+  const line = `- ${date}: ${decision.trim()} (${rationale.trim()})`;
+  p.decisions = p.decisions ? `${p.decisions}\n${line}` : line;
   p.updated = now();
   writeProject(p);
-  ok({ updated: true, name, count: list.length });
+  ok({ updated: true, name });
 }
 
+// ── handoff ───────────────────────────────────────────────────────
+
 function addHandoff(name: string, text: string): void {
   if (!text?.trim()) fail("Empty handoff text.");
   const p = requireProject(name);
@@ -192,43 +189,348 @@ function addHandoff(name: string, text: string): void {
   ok({ updated: true, name });
 }
 
+// ── set-path ──────────────────────────────────────────────────────
+
+function cmdSetPath(args: string[]): void {
+  const [name, ...rest] = args;
+  if (!name || rest.length === 0) fail("Usage: set-path <name> <new-path>");
+  const newPath = resolve(rest.join(" ").trim());
+  const p = requireProject(name);
+  p.path = newPath;
+  p.updated = now();
+  writeProject(p);
+  ok({ updated: true, name, path: newPath });
+}
+
+// ── update-section ────────────────────────────────────────────────
+
+const VALID_SECTIONS = [
+  "problem",
+  "goal",
+  "criteria",
+  "vision",
+  "constraints",
+  "out_of_scope",
+  "context",
+  "decisions",
+  "changelog",
+] as const;
+type Section = (typeof VALID_SECTIONS)[number];
+
+function cmdUpdateSection(args: string[]): void {
+  const [name, section, ...rest] = args;
+  if (!name || !section) fail("Usage: update-section <name> <section> <content>");
+  const key = section.toLowerCase().replace(/\s+/g, "_") as Section;
+  if (!(VALID_SECTIONS as readonly string[]).includes(key)) {
+    fail(`Unknown section "${section}". Valid: ${VALID_SECTIONS.join(", ")}`);
+  }
+  const content = rest.join(" ").trim();
+  if (!content) fail("Empty content.");
+  const p = requireProject(name);
+  (p as unknown as Record<string, unknown>)[key] = content;
+  p.updated = now();
+  writeProject(p);
+  ok({ updated: true, name, section: key });
+}
+
+// ── criteria ──────────────────────────────────────────────────────
+
+function cmdCriteria(args: string[]): void {
+  const name = args[0];
+  if (!name) fail("Usage: criteria <name>");
+  const p = requireProject(name);
+  ok({ name, criteria: p.criteria ?? "" });
+}
+
+// ── isa-init ──────────────────────────────────────────────────────
+
+function cmdIsaInit(args: string[]): void {
+  const name = args[0];
+  if (!name) fail("Usage: isa-init <name>");
+  const p = requireProject(name);
+  const sections: Array<keyof ProjectProgress> = [
+    "problem",
+    "goal",
+    "criteria",
+    "vision",
+    "constraints",
+    "out_of_scope",
+    "context",
+  ];
+  let scaffolded = 0;
+  const pr = p as unknown as Record<string, unknown>;
+  for (const s of sections) {
+    if (!pr[s as string]) {
+      pr[s as string] = "";
+      scaffolded++;
+    }
+  }
+  // Remove empty strings so they don't clutter the ISA body
+  for (const s of sections) {
+    if (pr[s as string] === "") pr[s as string] = undefined;
+  }
+  p.updated = now();
+  writeProject(p);
+  ok({ initialized: true, name, scaffolded });
+}
+
+// ── migrate (from old JSON format) ───────────────────────────────
+
+interface LegacyDecision {
+  ts: string;
+  decision: string;
+  rationale: string;
+}
+
+interface LegacyProject {
+  name: string;
+  path: string;
+  status: ProjectStatus;
+  created: string;
+  updated: string;
+  facts?: string[];
+  objectives?: string[];
+  next_steps?: string[];
+  blockers?: string[];
+  handoff?: string;
+  decisions?: LegacyDecision[];
+}
+
+function cmdMigrate(): void {
+  const progressDir = paths.progress();
+  if (!existsSync(progressDir)) {
+    ok({ migrated: 0, skipped: 0, results: [] });
+    return;
+  }
+
+  const files = readdirSync(progressDir).filter((f) => f.endsWith(".json"));
+  if (files.length === 0) {
+    ok({ migrated: 0, skipped: 0, results: [] });
+    return;
+  }
+
+  let migrated = 0;
+  let skipped = 0;
+  const results: string[] = [];
+
+  for (const file of files) {
+    const slug = file.slice(0, -5);
+    const filePath = resolve(progressDir, file);
+
+    if (readProject(slug)) {
+      skipped++;
+      results.push(`${slug}: skipped (ISA.md already exists)`);
+      continue;
+    }
+
+    try {
+      const raw = JSON.parse(readFileSync(filePath, "utf-8")) as LegacyProject;
+      if (!raw?.name || !raw?.path || !raw?.status) {
+        skipped++;
+        results.push(`${slug}: skipped (malformed JSON)`);
+        continue;
+      }
+
+      const p: ProjectProgress = {
+        name: raw.name,
+        path: raw.path,
+        status: raw.status,
+        created: raw.created,
+        updated: raw.updated,
+        ...(raw.handoff ? { handoff: raw.handoff } : {}),
+        ...(raw.next_steps?.length ? { next: raw.next_steps } : {}),
+        ...(raw.blockers?.length ? { blockers: raw.blockers } : {}),
+      };
+
+      if (raw.facts?.length) p.context = raw.facts.join("\n");
+      if (raw.objectives?.length) p.goal = raw.objectives.map((o) => `- ${o}`).join("\n");
+      if (raw.decisions?.length) {
+        p.decisions = raw.decisions
+          .map((d) => `- ${d.ts.slice(0, 10)}: ${d.decision} (${d.rationale})`)
+          .join("\n");
+      }
+
+      writeProject(p);
+      migrated++;
+      results.push(`${slug}: migrated`);
+    } catch {
+      skipped++;
+      results.push(`${slug}: skipped (read/write error)`);
+    }
+  }
+
+  ok({ migrated, skipped, results });
+}
+
 // ── rm (project) ──────────────────────────────────────────────────
 
 function cmdRm(args: string[]): void {
   const name = args[0];
-  if (!name) fail("Usage: rm <name>  (deletes the entire project state file)");
+  if (!name) fail("Usage: rm <name>  (deletes the entire project directory)");
   const removed = deleteProject(name);
   if (!removed) fail(`No project named "${name}".`);
   ok({ deleted: true, name });
 }
 
+// ── ISC helpers ──────────────────────────────────────────────────
+
+interface Isc {
+  id: number;
+  text: string;
+  checked: boolean;
+}
+
+function parseIscs(criteria: string): Isc[] {
+  const out: Isc[] = [];
+  for (const line of criteria.split("\n")) {
+    const m = new RegExp(/^-\s+\[( |x)\]\s+ISC-(\d+):\s+(.+)$/i).exec(line);
+    if (m) out.push({ id: Number(m[2]), text: m[3].trim(), checked: m[1] === "x" });
+  }
+  return out;
+}
+
+function nextIscId(criteria: string): number {
+  const ids = parseIscs(criteria).map((i) => i.id);
+  return ids.length > 0 ? Math.max(...ids) + 1 : 1;
+}
+
+function patchIsc(criteria: string, id: number, checked: boolean): string {
+  const marker = checked ? "[x]" : "[ ]";
+  return criteria.replace(
+    new RegExp(String.raw`^(-\s+)\[[ x]\](\s+ISC-${id}:)`, "m"),
+    `$1${marker}$2`
+  );
+}
+
+function cmdAddIsc(args: string[]): void {
+  const name = args[0] ?? fail("Usage: add-isc <name> <title>");
+  const title = args.slice(1).join(" ").trim();
+  if (!title) fail("Usage: add-isc <name> <title>");
+  const p = requireProject(name);
+  const current = p.criteria ?? "";
+  const id = nextIscId(current);
+  const newLine = `- [ ] ISC-${id}: ${title}`;
+  p.criteria = current ? `${current.trimEnd()}\n${newLine}` : newLine;
+  p.updated = now();
+  writeProject(p);
+  ok({ added: true, id, title });
+}
+
+function cmdCheckIsc(args: string[]): void {
+  const name = args[0] ?? fail("Usage: check-isc <name> <id>");
+  const id = Number(args[1] ?? fail("Usage: check-isc <name> <id>"));
+  if (!Number.isInteger(id) || id < 1) fail("ISC id must be a positive integer");
+  const p = requireProject(name);
+  const current = p.criteria ?? "";
+  const existing = parseIscs(current).find((i) => i.id === id);
+  if (!existing) fail(`ISC-${id} not found in project "${name}"`);
+  if (existing.checked) {
+    ok({ checked: true, id, alreadyDone: true });
+    return;
+  }
+  p.criteria = patchIsc(current, id, true);
+  p.updated = now();
+  writeProject(p);
+  ok({ checked: true, id });
+}
+
+function cmdListIsc(args: string[]): void {
+  const name = args[0] ?? fail("Usage: list-isc <name>");
+  const p = requireProject(name);
+  const iscs = parseIscs(p.criteria ?? "");
+  const open = iscs.filter((i) => !i.checked);
+  const done = iscs.filter((i) => i.checked);
+  ok({ name, total: iscs.length, open: open.length, done: done.length, iscs });
+}
+
+// ── Task ISA (work/) ──────────────────────────────────────────────
+
+function taskSlug(title: string): string {
+  const sanitized = title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40);
+  return `${sanitized}-${Date.now().toString(36)}`;
+}
+
+function taskIsaPath(slug: string): string {
+  const dir = resolve(paths.work(), slug);
+  mkdirSync(dir, { recursive: true });
+  return resolve(dir, "ISA.md");
+}
+
+function cmdScaffoldTaskIsa(args: string[]): void {
+  const title = args.join(" ").trim();
+  if (!title) fail("Usage: scaffold-task-isa <title>");
+  const slug = taskSlug(title);
+  const ts = new Date().toISOString();
+  const content = [
+    "---",
+    `task: "${title}"`,
+    `slug: "${slug}"`,
+    "phase: active",
+    `started: "${ts}"`,
+    `updated: "${ts}"`,
+    "---",
+    "",
+    "## Goal",
+    "",
+    "",
+    "## Criteria",
+    "",
+    "",
+  ].join("\n");
+  const filePath = taskIsaPath(slug);
+  writeFileSync(filePath, content, "utf-8");
+  ok({ created: true, slug, path: filePath });
+}
+
+function cmdCompleteTaskIsa(args: string[]): void {
+  const slug = args[0] ?? fail("Usage: complete-task-isa <slug>");
+  const filePath = resolve(paths.work(), slug, "ISA.md");
+  if (!existsSync(filePath)) fail(`Task ISA not found: ${slug}`);
+  const content = readFileSync(filePath, "utf-8");
+  const updated = content
+    .replace(/^phase: .+$/m, "phase: complete")
+    .replace(/^updated: .+$/m, `updated: "${new Date().toISOString()}"`);
+  writeFileSync(filePath, updated, "utf-8");
+  ok({ completed: true, slug });
+}
+
 // ── dispatch ──────────────────────────────────────────────────────
 
 function help(): void {
-  console.log(`Project — manage PAL project state.
+  console.log(`Project — manage PAL project state (ISA.md backed).
 
 Commands:
   list                                          show all registered projects
-  create [name] [--path PATH] [--objectives X]  register a project (defaults: name=basename(cwd), path=cwd)
-  resume <name>                                 print full project JSON
+  create [name] [--path PATH] [--objectives X]  register a project
+  resume <name>                                 print full project ISA
   complete <name>                               mark complete
   archive <name>                                mark archived
   pause <name> | unpause <name>                 toggle paused/active
-  add-fact <name> "text"                        append a stable fact / reference
-  add-objective <name> "text"                   append objective
+  set-path <name> <new-path>                    update the registered path
   add-next <name> "text"                        append next step
   add-blocker <name> "text"                     append blocker
-  add-decision <name> "decision" "rationale"    log a decision
+  add-decision <name> "decision" "rationale"    log a dated decision entry
   add-handoff <name> "text"                     overwrite handoff field
-  rm-fact <name> <index>                        remove fact by index
-  rm-objective <name> <index>                   remove objective by index
   rm-next <name> <index>                        remove next step by index
   rm-blocker <name> <index>                     remove blocker by index
-  rm <name>                                     delete the entire project file
+  update-section <name> <section> "content"     set an ISA body section
+  criteria <name>                               print the Criteria section
+  add-isc <name> "title"                        append a new open ISC to Criteria
+  check-isc <name> <id>                         mark ISC-N as done
+  list-isc <name>                               list all ISCs with open/done status
+  isa-init <name>                               mark project as ISA-initialized
+  scaffold-task-isa <title>                     create a one-shot task ISA in memory/work/
+  complete-task-isa <slug>                      mark a task ISA as complete
+  migrate                                       migrate old JSON progress files → ISA.md
+  rm <name>                                     delete the entire project
 `);
 }
 
-export function run(): void {
+function run(): void {
   const [cmd, ...rest] = Bun.argv.slice(2);
   if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
     help();
@@ -256,24 +558,10 @@ export function run(): void {
     case "unpause":
       setStatus(rest[0] ?? fail("Usage: unpause <name>"), "active");
       return;
-    case "add-fact":
-      appendItem(
-        rest[0] ?? fail("Usage: add-fact <name> <text>"),
-        "facts",
-        rest.slice(1).join(" ")
-      );
-      return;
-    case "add-objective":
-      appendItem(
-        rest[0] ?? fail("Usage: add-objective <name> <text>"),
-        "objectives",
-        rest.slice(1).join(" ")
-      );
-      return;
     case "add-next":
       appendItem(
         rest[0] ?? fail("Usage: add-next <name> <text>"),
-        "next_steps",
+        "next",
         rest.slice(1).join(" ")
       );
       return;
@@ -297,26 +585,8 @@ export function run(): void {
         rest.slice(1).join(" ")
       );
       return;
-    case "rm-fact":
-      removeItem(
-        rest[0] ?? fail("Usage: rm-fact <name> <index>"),
-        "facts",
-        rest[1] ?? ""
-      );
-      return;
-    case "rm-objective":
-      removeItem(
-        rest[0] ?? fail("Usage: rm-objective <name> <index>"),
-        "objectives",
-        rest[1] ?? ""
-      );
-      return;
     case "rm-next":
-      removeItem(
-        rest[0] ?? fail("Usage: rm-next <name> <index>"),
-        "next_steps",
-        rest[1] ?? ""
-      );
+      removeItem(rest[0] ?? fail("Usage: rm-next <name> <index>"), "next", rest[1] ?? "");
       return;
     case "rm-blocker":
       removeItem(
@@ -325,6 +595,36 @@ export function run(): void {
         rest[1] ?? ""
       );
       return;
+    case "update-section":
+      cmdUpdateSection(rest);
+      return;
+    case "criteria":
+      cmdCriteria(rest);
+      return;
+    case "add-isc":
+      cmdAddIsc(rest);
+      return;
+    case "check-isc":
+      cmdCheckIsc(rest);
+      return;
+    case "list-isc":
+      cmdListIsc(rest);
+      return;
+    case "isa-init":
+      cmdIsaInit(rest);
+      return;
+    case "scaffold-task-isa":
+      cmdScaffoldTaskIsa(rest);
+      return;
+    case "complete-task-isa":
+      cmdCompleteTaskIsa(rest);
+      return;
+    case "migrate":
+      cmdMigrate();
+      return;
+    case "set-path":
+      cmdSetPath(rest);
+      return;
     case "rm":
       cmdRm(rest);
       return;

package/src/tools/agent/relationship-note.ts

@@ -0,0 +1,51 @@
+#!/usr/bin/env bun
+/**
+ * RelationshipNote — Write a B entry to today's relationship log.
+ *
+ * Called in the ALGORITHM LEARN phase. Claude writes the B entry directly
+ * from full session context — no inference call needed.
+ *
+ * Usage:
+ *   bun ~/.pal/tools/relationship-note.ts --b "what I did this session"
+ */
+
+import { parseArgs } from "node:util";
+import { appendNotes } from "../../hooks/lib/relationship";
+
+function run() {
+  const { values } = parseArgs({
+    args: Bun.argv.slice(2),
+    options: {
+      b: { type: "string" },
+      help: { type: "boolean", short: "h" },
+    },
+  });
+
+  if (values.help) {
+    console.log(`
+RelationshipNote — Append a B entry to today's relationship log
+
+Usage:
+  bun ~/.pal/tools/relationship-note.ts --b "description"
+
+Arguments:
+  --b   What happened this session (1-2 sentences, first-person, specific)
+
+Output: appends to memory/relationship/YYYY-MM/YYYY-MM-DD.md
+`);
+    process.exit(0);
+  }
+
+  if (!values.b) {
+    console.error("Required: --b");
+    process.exit(1);
+  }
+
+  appendNotes([{ type: "Session", text: values.b }]);
+
+  console.log(
+    JSON.stringify({ success: true, message: "Relationship note written" }, null, 2)
+  );
+}
+
+if (import.meta.main) run();