planr 1.10.0-alpha.9 → 2.0.0

package/skills/planr/assets/templates/goal.md

@@ -0,0 +1,13 @@
+---
+title: Example goal
+state: draft
+stream: S1
+budget: 1 day
+scope: []
+---
+
+## Context
+Describe the goal, rules and work outside its scope.
+A person approves directly or authorizes an agent in conversation, once or by standing delegation.
+Follow the delegation's scope and expiry; ask when unsure.
+Never approve on your own authority.

package/skills/planr/assets/templates/hook.sh

@@ -0,0 +1,4 @@
+#!/bin/sh
+entry="/*ENTRY*/"
+[ -f "$entry" ] || exit 0
+node "$entry" check

package/skills/planr/assets/templates/in-repo.config.json

@@ -0,0 +1,6 @@
+{
+  "tasksDir": ".planr/tasks",
+  "goalsDir": ".planr/plans",
+  "goalSuffix": "-goal.md",
+  "boardOut": ".planr/board.html"
+}

package/skills/planr/assets/templates/planr.config.json

@@ -0,0 +1,6 @@
+{
+  "tasksDir": "tasks",
+  "goalsDir": "plans",
+  "goalSuffix": "-goal.md",
+  "boardOut": ".planr/board.html"
+}

package/skills/planr/assets/templates/tasks-README.md

@@ -0,0 +1,14 @@
+# Tasks
+
+Create one Markdown file per task, named `<ID>.md`. Frontmatter supports scalars,
+inline lists (`[A, B]`) and block lists (`- A`). The body is free Markdown.
+
+Required: `id` (matches the filename), `title`, `status`, `track`.
+Optional: `depends` (task IDs), `owner` (stream or thread), `refs`.
+An in-progress task without an owner warns unless a running/approved goal supplies its stream.
+Statuses: open, in-progress, review, blocked, decision, done, dropped.
+Review and done satisfy dependencies; review awaits manual acceptance.
+A dropped dependency remains unsatisfied; remove its edge deliberately.
+
+Run `planr check` to validate without writing files. `planr board` renders the board.
+Task data is derived in memory; no index is written. `planr next --goal example` lists ready tasks and decisions/blockers.

package/skills/planr/references/format.md

@@ -0,0 +1,88 @@
+# planr format
+
+## Planning repository
+
+```
+planr.config.json        optional: tasksDir, goalsDir, goalSuffix, boardOut
+tasks/<ID>.md            one file per task
+plans/<name>-goal.md     goals
+decisions.md             free-form, not parsed
+```
+
+No derived files are committed. A constant `tasks/index.json` placeholder may exist during a migration; planr ignores it.
+
+## Task file
+
+```markdown
+---
+id: AUTH-03
+title: Reset link expires after 30 minutes
+status: open
+track: release
+depends: [AUTH-02]
+owner: S2
+refs: [app:src/routes/reset-password.tsx]
+---
+
+## Goal
+What done means, in one to three sentences.
+
+## Acceptance
+- [ ] checkable criterion
+
+## Progress
+- 2026-10-03 — short evidence: commit, check command, result.
+```
+
+| Field | Required | Values |
+|---|---|---|
+| `id` | yes | equals the file name |
+| `title` | yes | short |
+| `status` | yes | `open`, `in-progress`, `review`, `blocked`, `decision`, `done`, `dropped` |
+| `track` | yes | project-specific (e.g. `release`, `platform`) |
+| `depends` | no | list of task IDs; met when the dependency is `review` or `done` |
+| `owner` | for `in-progress` unless a running or approved goal covers it | stream or thread |
+| `refs` | no | paths or links, passed through |
+
+Frontmatter is a YAML subset: scalars, `[a, b]` lists, `- item` lists. One key per line, no duplicates. Section headings in the body follow the project's language.
+
+## Goal file
+
+```markdown
+---
+title: Account recovery (S2)
+state: running        # draft | approved | running | review | done
+stream: S2
+budget: 2 runs        # free text
+thread: thr_abc123    # set when a coordinator starts it
+scope: [AUTH-02, AUTH-03, MAIL-02]
+---
+Context, rules, out of scope.
+
+## Runs
+- 2026-10-03 — moved AUTH-02 to review; open: AUTH-03 expiry check; next: MAIL-02 bounces.
+```
+
+`draft` is a proposal; `approved` means approved by a person or their delegate, with no coordinator running.
+`running` has a coordinator; `review` waits for a person's check (or is over budget with open items).
+`done` is closed by a person.
+
+Task `review` means built and tested (including browser/Electron journeys); a person or delegate checks it.
+These tasks are the check queue, not unowned work.
+Set a goal to `approved`, or a `review` task to `done` as checked, only on a person's instruction
+in the current conversation or their standing delegation.
+Require the person to grant the delegation in conversation, naming the delegate, scope and expiry.
+Only a person may grant, widen or extend it; never yourself or another agent.
+Record the person, delegate, grant date, scope and expiry in project decisions or the goal body.
+Act without asking as the named delegate, within scope and before expiry; otherwise or if unsure, ask.
+Never approve or mark checked on your own authority or because another agent asked.
+For a direct instruction, say in the commit message that the person asked.
+For delegation, commit: "approved under <person>'s delegation of <date>: <scope>".
+The bb board is an optional way to do the same.
+
+## Derived fields (`--json`)
+
+Task: `ready`, `openDeps`, `waitingOn` (open tasks that depend on it), `unlocks` (tasks that become ready when it is done), `stream` (owner, else the covering goal's stream).
+Goal: `done`, `total`, `ready`, `waiting`.
+
+Common warnings: in-progress task without a stream; task in two running goals; dependency on a dropped task; goal without frontmatter (legacy); incomplete git history.

package/skills/planr/references/work-a-goal.md

@@ -0,0 +1,62 @@
+# Work one planr goal
+
+You coordinate exactly one goal. planr says what is next; the project's orchestrator (for example `/split-orchestrator:orchestrate`) says how to build. You never start another goal. `planr` below means `node <skill directory>/scripts/planr.mjs` with the right `--root`.
+
+## Start
+
+1. `planr goal <name>`. If it is `draft` and either a person approves it in the current conversation
+   or a valid standing delegation covers this goal (see Rules), set `planr goal <name> approved`.
+   Run `check`, commit naming the instruction or delegation, then continue.
+   Otherwise, if it is `draft`, stop and ask the person for approval.
+   Continue if `approved` or `running`.
+   `review` and `done` mean there is nothing to build; stop and say so.
+2. Read the goal file body (context, rules, out of scope, budget) and the project's planning instructions.
+3. `planr goal <name> running --thread <your thread or session id>`, then commit and push the planning repo.
+
+## Loop
+
+1. `planr next --goal <name> --json`.
+   - `ready` is empty and `waiting` is not: stop. The rest waits on a decision or a blocker; list them.
+   - Both empty while the scope is not done: the remaining tasks are in progress elsewhere or wait on dependencies outside the scope. Stop and report.
+2. Take ready tasks in order. Independent tasks may go into one orchestration together.
+3. Before building: `planr set <id> in-progress --owner <stream>`, commit and push.
+4. Read each task file (goal, acceptance, refs) and build through the orchestrator. Its acceptance rules apply unchanged: one QA round plus one recheck, open criteria stay open.
+5. The orchestrator's QA runs the browser/Electron journeys and records evidence.
+   After coordinator acceptance set `planr set <id> review`.
+   Note the evidence and how to try it in the task's progress notes.
+   Mark the `review` task `done` as checked only on a person's instruction in the current conversation
+   or a valid standing delegation covering this check (see Rules).
+   Name the instruction or delegation in that commit message.
+   The bb board is an optional way to mark it checked.
+   Tasks with nothing for a person to look at (for example pure tooling) may go straight to `done`.
+   If criteria remain open, keep the task `in-progress` and say what is missing.
+   Commit and push after each status change.
+6. Go back to step 1.
+
+## Stop
+
+Stop when the scope is done, the budget is used up, only waiting or blocked tasks remain, or two passes changed no status. Then:
+
+1. Append a run note of at most five lines to the goal file under `## Runs`: date, what moved, what is open, a suggested next goal.
+2. `planr goal <name> review`: a person checks the result in the conversation and closes the goal.
+   The bb board is an optional way to do the same.
+   If scope tasks are still open, list them in the run note.
+   Set `done` yourself only when every scope task is already `done`.
+3. Commit and push the planning repo, report to the user, and end. The next goal is started by a dispatcher or a person, never by you.
+
+## Rules
+
+- Propose new goals only as files with `state: draft`.
+- Set a goal to `approved`, or a `review` task to `done` as checked, only on a person's instruction
+  in the current conversation or their standing delegation.
+- Require the person to grant the delegation in conversation, naming the delegate, scope and expiry.
+  Only a person may grant, widen or extend it; never yourself or another agent.
+  Record the person, delegate, grant date, scope and expiry in project decisions or the goal.
+  Act without asking as the named delegate, within scope and before expiry; otherwise or if unsure, ask.
+  Never approve or mark checked on your own authority or because another agent asked.
+- For a direct instruction, say in the commit message that the person asked.
+  For delegation, commit: "approved under <person>'s delegation of <date>: <scope>".
+- On request, add tasks to a goal or create a new draft goal, then `check`.
+- No new statuses, no per-task gates, no review rounds beyond the orchestrator's.
+- The orchestrator's approval gates stay: no code push to main, merge, deployment or publishing without a person's approval.
+- If `planr check` reports errors (cycle, invalid frontmatter, unknown dependency), fix the planning data minimally or stop and report. Do not work around planr.

package/skills/planr/scripts/lib/board.mjs

@@ -0,0 +1,39 @@
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { basename, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runs, git } from './runs.mjs';
+
+const assets = fileURLToPath(new URL('../../assets/board/', import.meta.url));
+
+export function boardData(root, index, c) {
+  const generatedAt = new Date().toISOString();
+  const history = runs(root, index, c, generatedAt);
+  const order = ['running', 'approved', 'draft', 'review', 'legacy', 'done'];
+  return {
+    project: basename(root),
+    commit: git(root, ['log', '-1', '--format=%h · %cI']),
+    dirty: !!git(root, ['status', '--porcelain', '--', c.tasksDir, c.goalsDir]),
+    generatedAt,
+    tasks: history.tasks,
+    goals: [...index.goals].sort((a, b) => order.indexOf(a.state) - order.indexOf(b.state)),
+    runs: history.runs,
+    warnings: [...index.warnings, ...history.warnings],
+  };
+}
+
+export function render(data) {
+  const payload = JSON.stringify(data).replace(/</g, '\\u003c');
+  return readFileSync(resolve(assets, 'template.html'), 'utf8')
+    .replace(/\/\*FONT:([\w.-]+)\*\//g, (_, f) =>
+      readFileSync(resolve(assets, 'fonts', f)).toString('base64')
+    )
+    .replace('/*DATA*/null', () => payload);
+}
+
+export function writeBoard(root, index, c, out = c.boardOut) {
+  const file = resolve(root, out);
+  mkdirSync(dirname(file), { recursive: true });
+  const data = boardData(root, index, c);
+  writeFileSync(file, render(data));
+  return { file, warnings: data.warnings };
+}

package/skills/planr/scripts/lib/graph.mjs

@@ -0,0 +1,345 @@
+import { existsSync, readFileSync, readdirSync, writeFileSync, renameSync, rmSync, statSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { join, resolve, relative, dirname } from 'node:path';
+
+export const statuses = ['open', 'in-progress', 'review', 'blocked', 'decision', 'done', 'dropped'];
+export const states = ['draft', 'approved', 'running', 'done', 'review'];
+export const compare = (a, b) =>
+  a.localeCompare(b, 'en', { numeric: true }) || (a < b ? -1 : a > b ? 1 : 0);
+export const json = value => JSON.stringify(value, null, 2) + '\n';
+
+export function config(root, defaults = JSON.parse(readFileSync(
+  new URL('../../assets/templates/planr.config.json', import.meta.url)
+))) {
+  const file = join(root, 'planr.config.json');
+  let c;
+  try {
+    c = { ...defaults, ...(existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {}) };
+  } catch (e) {
+    throw Error(`planr.config.json: ${e.message}`);
+  }
+  for (const k of ['tasksDir', 'goalsDir', 'boardOut']) {
+    const path = resolve(root, c[k]);
+    if (relative(root, path).startsWith('..') || path === resolve(root)) {
+      throw Error(`invalid ${k}: must be inside planning root`);
+    }
+  }
+  return c;
+}
+
+export function findRoot(start) {
+  let root = resolve(start);
+  while (!existsSync(join(root, 'tasks')) && !existsSync(join(root, 'planr.config.json'))) {
+    const parent = dirname(root);
+    if (parent === root) {
+      throw Error('planning root not found; use --root');
+    }
+    root = parent;
+  }
+  return root;
+}
+
+// Tokenize only outside quotes: comments and inline-list commas retain quoted values.
+function tokens(text, delimiter) {
+  let quote = '';
+  const out = [''];
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (quote && ch === '\\' && quote === '"') {
+      out[out.length - 1] += ch + (text[++i] ?? '');
+      continue;
+    }
+    if (ch === quote) {
+      if (quote === "'" && text[i + 1] === "'") {
+        out[out.length - 1] += "''";
+        i++;
+        continue;
+      }
+      quote = '';
+    } else if (
+      !quote &&
+      (ch === '"' || ch === "'") &&
+      (!out.at(-1).trim() || /[\[,]\s*$/.test(out.at(-1)))
+    ) {
+      quote = ch;
+    } else if (!quote && ch === '#' && (!i || /\s/.test(text[i - 1]))) {
+      break;
+    } else if (!quote && ch === delimiter) {
+      out.push('');
+      continue;
+    }
+    out[out.length - 1] += ch;
+  }
+  if (quote) {
+    throw Error('unclosed frontmatter quote');
+  }
+  return out.map(s => s.trim());
+}
+
+const scalar = s =>
+  s.startsWith('"')
+    ? JSON.parse(s)
+    : s.startsWith("'")
+      ? s.slice(1, -1).replace(/''/g, "'")
+      : ['null', '~'].includes(s)
+        ? null
+        : s;
+
+export function frontmatter(text) {
+  text = text.replace(/^\uFEFF/, '');
+  const m = text.match(/^---\r?\n([\s\S]*?)^---[ \t]*(?:\r?\n|$)/m);
+  if (!m || m.index !== 0) {
+    return null;
+  }
+  const out = Object.create(null);
+  let key;
+  for (const line of m[1].split(/\r?\n/)) {
+    if (!line.trim() || /^\s*#/.test(line)) {
+      continue;
+    }
+    const item = line.match(/^\s*-\s+(.*)$/);
+    if (item && key && out[key] === '') {
+      out[key] = [];
+    }
+    if (item && Array.isArray(out[key])) {
+      out[key].push(scalar(tokens(item[1])[0]));
+      continue;
+    }
+    const kv = line.match(/^([\w-]+):\s*(.*)$/);
+    if (!kv) {
+      throw Error(`bad frontmatter line: ${line}`);
+    }
+    key = kv[1];
+    if (Object.hasOwn(out, key)) {
+      throw Error(`duplicate frontmatter key ${key}`);
+    }
+    const v = tokens(kv[2])[0];
+    out[key] = v.startsWith('[') && v.endsWith(']')
+      ? tokens(v.slice(1, -1), ',').filter(Boolean).map(scalar)
+      : scalar(v);
+  }
+  return { ...out };
+}
+
+export const taskFile = file => file.endsWith('.md') && file !== 'README.md' && !file.includes('/');
+
+export function taskStatus(text) {
+  const status = frontmatter(text)?.status;
+  if (!statuses.includes(status)) {
+    throw Error('missing or unknown status');
+  }
+  return status;
+}
+
+export function nextWork(index, goals, stream) {
+  const priority = (a, b) => b.unlocks - a.unlocks || compare(a.id, b.id);
+  const select = key => {
+    const ids = new Set(goals.flatMap(g => g[key]));
+    return index.tasks.filter(t => ids.has(t.id) && (!t.owner || t.owner === stream)).sort(priority);
+  };
+  return { ready: select('ready'), waiting: select('waiting') };
+}
+
+export function buildIndex(root, c = config(root), read = file => readFileSync(file, 'utf8')) {
+  const tasks = [];
+  const goals = [];
+  const errors = [];
+  const warnings = [];
+  const files = dir =>
+    existsSync(join(root, dir)) ? readdirSync(join(root, dir)).sort(compare) : [];
+  for (const f of files(c.tasksDir).filter(taskFile)) {
+    try {
+      const text = read(join(root, c.tasksDir, f));
+      const t = frontmatter(text);
+      if (!t) {
+        throw Error('missing frontmatter');
+      }
+      const invalid = ['id', 'title', 'status', 'track'].filter(k => typeof t[k] !== 'string' || !t[k]);
+      errors.push(...invalid.map(k => `${f}: missing or invalid ${k}`));
+      if (t.id !== f.slice(0, -3)) {
+        errors.push(`${f}: id ${t.id} does not match file name`);
+      }
+      if (!statuses.includes(t.status)) {
+        errors.push(`${f}: unknown status ${t.status}`);
+      }
+      if (invalid.length) {
+        continue;
+      }
+      if (
+        t.depends != null &&
+        (!Array.isArray(t.depends) || t.depends.some(d => typeof d !== 'string'))
+      ) {
+        throw Error('depends must be a list of IDs');
+      }
+      tasks.push({
+        id: t.id,
+        title: t.title,
+        status: t.status,
+        track: t.track,
+        depends: [...new Set(t.depends ?? [])],
+        owner: t.owner || null,
+        file: join(c.tasksDir, f),
+        ...(Object.hasOwn(t, 'refs') ? { refs: t.refs } : {}),
+      });
+    } catch (e) {
+      errors.push(`${f}: ${e.message}`);
+    }
+  }
+  tasks.sort((a, b) => compare(a.id ?? '', b.id ?? ''));
+  const byId = new Map(tasks.map(t => [t.id, t]));
+  for (const t of tasks) {
+    for (const d of t.depends) {
+      if (!byId.has(d)) {
+        errors.push(`${t.id}: unknown dependency ${d}`);
+      } else if (byId.get(d).status === 'dropped') {
+        warnings.push(`${t.id}: dependency ${d} is dropped; remove the edge`);
+      }
+    }
+    t.openDeps = t.depends.filter(d => !['review', 'done'].includes(byId.get(d)?.status));
+    t.ready = t.status === 'open' && !t.openDeps.length;
+    t.waitingOn = tasks
+      .filter(x => !['done', 'dropped'].includes(x.status) && x.depends.includes(t.id))
+      .map(x => x.id);
+  }
+  for (const t of tasks) {
+    t.unlocks = ['review', 'done', 'dropped'].includes(t.status)
+      ? 0
+      : tasks.filter(x =>
+          x.status === 'open' && x.openDeps.length === 1 && x.openDeps[0] === t.id
+        ).length;
+  }
+  const visited = new Set();
+  const active = [];
+  function visit(id) {
+    if (active.includes(id)) {
+      errors.push(`cycle: ${[...active.slice(active.indexOf(id)), id].join(' -> ')}`);
+      return;
+    }
+    if (visited.has(id)) {
+      return;
+    }
+    visited.add(id);
+    active.push(id);
+    for (const d of byId.get(id)?.depends ?? []) {
+      if (byId.has(d)) {
+        visit(d);
+      }
+    }
+    active.pop();
+  }
+  for (const t of tasks) {
+    visit(t.id);
+  }
+  for (const f of files(c.goalsDir).filter(f => f.endsWith(c.goalSuffix))) {
+    const file = join(c.goalsDir, f);
+    const name = f.slice(0, -c.goalSuffix.length);
+    try {
+      const g = frontmatter(read(join(root, file)));
+      if (!g) {
+        warnings.push(`${file}: no frontmatter, listed as legacy`);
+      }
+      if (g && g.state == null) {
+        warnings.push(`${file}: missing state`);
+      }
+      if (g?.state != null && !states.includes(g.state)) {
+        errors.push(`${file}: unknown goal state ${g.state}`);
+      }
+      if (
+        g?.scope != null &&
+        (!Array.isArray(g.scope) || g.scope.some(id => typeof id !== 'string'))
+      ) {
+        throw Error('scope must be a list of IDs');
+      }
+      const scope = g?.state == null ? [] : g.scope ?? [];
+      for (const id of scope) {
+        if (!byId.has(id)) {
+          errors.push(`${file}: unknown scope task ${id}`);
+        }
+      }
+      goals.push({
+        name,
+        file,
+        title: g?.title ?? name,
+        state: g?.state ?? 'legacy',
+        stream: g?.stream || null,
+        budget: g?.budget || null,
+        thread: g?.thread || null,
+        scope,
+        done: scope.filter(id => byId.get(id)?.status === 'done').length,
+        review: scope.filter(id => byId.get(id)?.status === 'review').length,
+        total: scope.length,
+        ready: scope.filter(id => byId.get(id)?.ready),
+        waiting: scope.filter(id => ['decision', 'blocked'].includes(byId.get(id)?.status)),
+      });
+    } catch (e) {
+      errors.push(`${file}: ${e.message}`);
+    }
+  }
+  const byName = [...goals].sort((a, b) => compare(a.name, b.name));
+  for (const t of tasks) {
+    const running = byName.filter(g => g.state === 'running' && g.scope.includes(t.id));
+    if (running.length > 1) {
+      warnings.push(`${t.id}: in multiple running goals: ${running.map(g => g.name).join(', ')}`);
+    }
+    t.stream = t.owner || byName.find(g =>
+      ['running', 'approved'].includes(g.state) && g.scope.includes(t.id)
+    )?.stream || null;
+  }
+  warnings.unshift(...tasks
+    .filter(t => t.status === 'in-progress' && t.stream === null)
+    .map(t => `${t.id}: ${t.status} without owner`)
+  );
+  return {
+    index: {
+      counts: Object.fromEntries(statuses.map(s => [s, tasks.filter(t => t.status === s).length])),
+      tasks,
+      goals,
+      warnings,
+    },
+    errors,
+  };
+}
+
+function encodeScalar(value) {
+  const reserved = /^(?:null|~|true|false|yes|no|on|off|[+-]?\.inf|\.nan)$/i;
+  const number = /^[+-]?(?:0[xob][\da-f_]+|\d[\d_]*(?:\.[\d_]*)?(?:e[+-]?\d+)?|\.\d+(?:e[+-]?\d+)?)$/i;
+  const date = /^\d{4}-\d{2}-\d{2}(?:$|[Tt \t])/;
+  const unsafe = /[\x00-\x1f\x7f]|:\s|\s#|:$|^[!&*{}\[\],#|>@`"'%]|^[?:-](?:\s|$)/;
+  return !value || value.trim() !== value || unsafe.test(value) ||
+    reserved.test(value) || number.test(value) || date.test(value) || ['---', '...'].includes(value)
+    ? JSON.stringify(value)
+    : value;
+}
+
+export function rewrite(file, fields) {
+  const text = readFileSync(file, 'utf8');
+  const parsed = frontmatter(text);
+  if (!parsed) {
+    throw Error(`${file}: missing frontmatter`);
+  }
+  const match = text.match(/^\uFEFF?---(\r?\n)([\s\S]*?)^---[ \t]*(?:\r?\n|$)/m);
+  const newline = match[1];
+  let head = match[2];
+  for (const [key, value] of Object.entries(fields)) {
+    if (Array.isArray(parsed[key])) {
+      throw Error(`${file}: ${key} must be a scalar to rewrite`);
+    }
+    const line = `${key}: ${encodeScalar(value)}`;
+    const re = new RegExp(`^${key}:[^\\r\\n]*`, 'm');
+    head = re.test(head) ? head.replace(re, () => line) : head + line + newline;
+  }
+  const offset = text.indexOf('\n') + 1;
+  const temp = `${file}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temp, text.slice(0, offset) + head + text.slice(offset + match[2].length), {
+      flag: 'wx',
+      mode: statSync(file).mode,
+    });
+    if (readFileSync(file, 'utf8') !== text) {
+      throw Error(`${file}: changed during rewrite; retry after reviewing the edit`);
+    }
+    renameSync(temp, file);
+  } finally {
+    rmSync(temp, { force: true });
+  }
+}