create-pmos 0.38.7 → 0.39.0

package/workspace/lib/judgment.js

@@ -0,0 +1,65 @@
+'use strict';
+/* judgment.js — typed answers to classify, score and yes-or-no questions.
+ *
+ * The workspace makes no network call and runs no model. When the PM turns judgment on for a run, the PROMPT tells the
+ * session to use the Typesafe skill (https://docs.typesafe.ai/agent-skill; needs TYPESAFE_API_KEY) for these three kinds
+ * of decision, and to print each answer on one line as `JUDGMENT {json}`. This module owns the fragment that says so and
+ * the check of the shape that comes back. An answer in any other shape is rejected, never repaired.
+ *
+ * Off, or without a key, the session is asked for the SAME shape from plain judgment, and the fragment says so — the
+ * PM never gets a different answer format depending on a setting.
+ */
+const KINDS = ['classify', 'score', 'yesno'];
+const LINE = /^JUDGMENT\s+(\{.*\})\s*$/;
+const clip = (s, n) => String(s).slice(0, n);
+
+function fragment(on) {
+  const shape = [
+    'When a step needs you to categorise, score, or decide yes or no, give the answer on its own line, exactly like this, one JSON object per line:',
+    // The examples start with "e.g." so a transcript that echoes this prompt is never read as an answer.
+    '  e.g. JUDGMENT {"kind":"classify","question":"…","label":"<one of your labels>","labels":["…","…"],"confidence":0.0-1.0}',
+    '  e.g. JUDGMENT {"kind":"score","question":"…","score":0.0-1.0,"reason":"…"}',
+    '  e.g. JUDGMENT {"kind":"yesno","question":"…","answer":true|false,"confidence":0.0-1.0,"reason":"…"}',
+  ];
+  if (on) return ['Use the Typesafe skill (/typesafe:typesafe-ai) for those decisions. The question text you send leaves this machine for the Typesafe service and needs TYPESAFE_API_KEY. If the skill or the key is missing, say so and decide yourself.', ...shape].join('\n');
+  return ['Decide those yourself; no outside service is used for this run.', ...shape].join('\n');
+}
+
+const unit = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= 1;
+
+/** @returns {{ok:true,value:object}|{ok:false,error:string}} */
+function validate(o) {
+  if (!o || typeof o !== 'object' || Array.isArray(o)) return { ok: false, error: 'not an object' };
+  if (!KINDS.includes(o.kind)) return { ok: false, error: `kind must be one of ${KINDS.join(', ')}` };
+  if (typeof o.question !== 'string' || !o.question.trim()) return { ok: false, error: 'question is required' };
+  const base = { kind: o.kind, question: clip(o.question.trim(), 300) };
+  if (o.kind === 'classify') {
+    if (!Array.isArray(o.labels) || o.labels.length < 2 || o.labels.some((l) => typeof l !== 'string' || !l.trim())) return { ok: false, error: 'labels must be a list of at least two strings' };
+    if (typeof o.label !== 'string' || !o.labels.includes(o.label)) return { ok: false, error: 'label must be one of labels' };
+    if (!unit(o.confidence)) return { ok: false, error: 'confidence must be a number from 0 to 1' };
+    return { ok: true, value: { ...base, label: o.label, labels: o.labels.map((l) => clip(l, 60)), confidence: o.confidence } };
+  }
+  if (o.kind === 'score') {
+    if (!unit(o.score)) return { ok: false, error: 'score must be a number from 0 to 1' };
+    if (typeof o.reason !== 'string' || !o.reason.trim()) return { ok: false, error: 'reason is required' };
+    return { ok: true, value: { ...base, score: o.score, reason: clip(o.reason.trim(), 300) } };
+  }
+  if (typeof o.answer !== 'boolean') return { ok: false, error: 'answer must be true or false' };
+  if (!unit(o.confidence)) return { ok: false, error: 'confidence must be a number from 0 to 1' };
+  return { ok: true, value: { ...base, answer: o.answer, confidence: o.confidence, ...(typeof o.reason === 'string' ? { reason: clip(o.reason.trim(), 300) } : {}) } };
+}
+
+/** Every `JUDGMENT {json}` line in a transcript, checked. Returns { valid:[…], invalid:[{line,error}] }. */
+function extract(text) {
+  const valid = []; const invalid = [];
+  for (const raw of String(text == null ? '' : text).split(/\r?\n/)) {
+    const m = LINE.exec(raw.trim());
+    if (!m) continue;
+    let o; try { o = JSON.parse(m[1]); } catch { invalid.push({ line: clip(raw.trim(), 200), error: 'not valid JSON' }); continue; }
+    const v = validate(o);
+    if (v.ok) valid.push(v.value); else invalid.push({ line: clip(raw.trim(), 200), error: v.error });
+  }
+  return { valid, invalid };
+}
+
+module.exports = { KINDS, fragment, validate, extract };

package/workspace/lib/mobile-nav.js

@@ -49,7 +49,7 @@
 // silently renders a key where a title belongs.
 const MODE_TITLE = {
   product: 'initiatives', scheduled: 'scheduled tasks', workflow: 'workflows', skills: 'skills',
-  knowledge: 'knowledge', agent: 'agents', memory: 'memory',
+  knowledge: 'knowledge', agent: 'agents', memory: 'memory', portfolio: 'portfolio', guide: 'guide',
 };
 // What a DETAIL screen is called. It moved here with the reducer, for the same reason.
 // The second block is the four-panel surface's `detail.kind` vocabulary (pm/app.js's DETAIL_TITLE).

package/workspace/lib/next-step-actions.js

@@ -0,0 +1,139 @@
+'use strict';
+/* next-step-actions.js — what a next step can DO, whether it may be started yet, and the prompt a session would get.
+ *
+ * Pure: no I/O, no clock, no model. The server supplies facts (does a file exist, which sources a profile declares) and
+ * this module decides. Three questions, each answered in one place so no panel and no route re-decides them:
+ *
+ *   actFor(item)        what kind of act the step is: open · session · work · gate · lifecycle · none
+ *   refusal(item, ns)   why a `work` step may NOT be started yet, or null when it may
+ *   buildPrompt(...)    the exact first input a session would receive — what the PM is shown before pressing go
+ *
+ * THE BOUNDARY (D12 and the control/factory invariant). A session started from here PROPOSES: it commits to a local
+ * initiative branch or writes draft files. It never accepts, approves a contract, merges, pushes, sends or posts. Acceptance
+ * and the contract approval are `gate` acts and are never turned into `work`.
+ */
+const crypto = require('crypto');
+
+// Ladder steps an agent session can do. `contract`, `accept`, `approved`, `outcome` and `handoff` are the PM's own act.
+const WORK_KEYS = new Set(['route', 'anchor', 'prototype', 'understand', 'spec', 'priors', 'build', 'quality', 'review', 'explain', 'brief', 'draft']);
+const GATE_KEYS = new Set(['contract', 'accept', 'approved', 'outcome', 'handoff']);
+const KNOWN_KEYS = [...WORK_KEYS, ...GATE_KEYS];
+// The act types a step can have (`none` means no action is defined, and is not offered). The user guide names each one.
+const ACT_TYPES = ['open', 'session', 'work', 'gate', 'lifecycle'];
+
+const GATE_WHY = {
+  contract: 'The contract is yours to approve. An agent may draft it; the approval is recorded by you, never by a session.',
+  accept: 'Acceptance is yours and cannot be delegated (D12).',
+  approved: 'Approval is yours.',
+  outcome: 'The outcome check is yours to record.',
+  handoff: 'Handing work to another system is outward-facing, so it is yours to press.',
+};
+
+/** @returns {{type:'open'|'session'|'work'|'gate'|'lifecycle'|'none', why:string, path?:string, sessionId?:string}} */
+function actFor(item) {
+  if (!item || typeof item !== 'object') return { type: 'none', why: 'no step' };
+  const path = typeof item.path === 'string' && item.path ? item.path : null;
+  const withPath = (a) => (path ? { ...a, path } : a);
+  switch (item.kind) {
+    case 'reopen': return { type: 'lifecycle', why: 'Reopen it to put it back on the board.' };
+    case 'session': return item.sid ? { type: 'session', why: 'Switch to the running session.', sessionId: item.sid } : { type: 'none', why: 'the session is not identified' };
+    case 'accept': return withPath({ type: path ? 'open' : 'gate', why: GATE_WHY.accept });
+    case 'needs': return withPath({ type: 'gate', why: 'An open item only you can answer.' });
+    case 'returned': return { type: 'work', why: 'Address the return, then ask for acceptance again.' };
+    case 'step': {
+      if (WORK_KEYS.has(item.key)) return withPath({ type: 'work', why: 'An agent session can do this step.' });
+      if (GATE_KEYS.has(item.key)) return withPath({ type: path ? 'open' : 'gate', why: GATE_WHY[item.key] });
+      return { type: 'none', why: `no action is defined for the step "${item.key}"` };
+    }
+    default: return { type: 'none', why: 'no action is defined for this item' };
+  }
+}
+
+/** Set `act` on every item of a derived next-steps result. Mutates and returns it. */
+function annotate(ns, pathOf) {
+  if (!ns || !Array.isArray(ns.items)) return ns;
+  for (const it of ns.items) {
+    if (typeof pathOf === 'function') { const p = pathOf(it); if (p) it.path = p; }
+    it.act = actFor(it);
+  }
+  return ns;
+}
+
+/** Why this item may not be started as work yet; null when it may. `ns` is the whole derived result. */
+function refusal(item, ns) {
+  if (!item) return { code: 'no-step', why: 'no such step' };
+  const act = item.act || actFor(item);
+  if (ns && ns.state === 'stopped' && item.kind !== 'reopen') {
+    return { code: 'stopped', why: 'This initiative is stopped (held, closed or cancelled). Reopen it first.', first: 'reopen' };
+  }
+  if (ns && ns.state === 'accepted') return { code: 'accepted', why: 'This initiative is accepted. Nothing remains.' };
+  if (act.type !== 'work') return { code: 'not-work', why: act.type === 'gate' ? act.why : `This is not work an agent session can start (${act.type}).` };
+  const items = (ns && ns.items) || [];
+  if (item.kind === 'returned') return null;                      // addressing a return is always the next thing
+  if (item.status === 'blocked') return { code: 'blocked', why: `This step is blocked${item.why ? ' — ' + item.why : ''}.`, first: item.key };
+  if (item.key === 'build') {
+    const contract = items.find((x) => x.kind === 'step' && x.key === 'contract');
+    if (contract) return { code: 'no-contract', why: 'The build cannot start before you approve the pre-run contract. An agent may draft it; you approve it.', first: 'contract' };
+  }
+  if (item.first || item.status === 'current') return null;
+  const first = items.find((x) => x.first) || items[0];
+  return { code: 'not-reached', why: `Not reached yet: step ${first ? first.n : 1} (${first ? first.key : 'the first step'}) comes first.`, first: first ? first.key : null };
+}
+
+// Which read-only sources suit which step. Names are the keys of SOURCE_MCP below.
+const STEP_SOURCES = {
+  route: ['jira', 'slack'], understand: ['wispr', 'confluence', 'jira', 'slack'], spec: ['wispr', 'confluence', 'jira', 'gmail'],
+  priors: ['confluence'], prototype: ['wispr', 'slack'], build: ['jira', 'confluence'], returned: ['wispr', 'slack', 'gmail'],
+  brief: ['wispr', 'calendar', 'gmail'], draft: ['wispr', 'confluence', 'gmail'],
+};
+// MCP server names a profile may declare, per source. A name outside this table names nothing.
+const SOURCE_MCP = {
+  wispr: ['wispr', 'wispr-flow', 'wisprflow'], gmail: ['gmail', 'google-mail'], calendar: ['google-calendar', 'gcal', 'calendar'],
+  confluence: ['confluence', 'atlassian'], jira: ['jira', 'atlassian'], slack: ['slack'],
+};
+const SOURCE_LABEL = { wispr: 'Wispr Flow notes and meetings', gmail: 'Gmail', calendar: 'Google Calendar', confluence: 'Confluence', jira: 'Jira', slack: 'Slack' };
+
+/** The sources the prompt may name: suited to the step AND declared by the chosen profile's `mcp` list. */
+function sourcesFor(item, mcpDeclared) {
+  const declared = new Set((Array.isArray(mcpDeclared) ? mcpDeclared : []).map((s) => String(s).toLowerCase()));
+  const want = STEP_SOURCES[item && item.kind === 'returned' ? 'returned' : item && item.key] || [];
+  return want.filter((s) => (SOURCE_MCP[s] || []).some((n) => declared.has(n))).map((s) => ({ id: s, label: SOURCE_LABEL[s] }));
+}
+
+const RULES = [
+  'Commit only to this local branch, or write draft files in the repository.',
+  'Do not push, open a pull request, send or post anything, create a ticket, record an acceptance, approve a contract, or merge. Those are the PM\'s.',
+  'Do only this step. If you find another problem, write it down and stop.',
+  'When you finish, stop and write a short summary: what you changed, and what you could not verify.',
+];
+
+/**
+ * The exact first input a session would receive.
+ * @param {{initiative:string, title?:string, item:object, branch:string|null, sources:Array, judgment:string}} p
+ */
+function buildPrompt(p) {
+  const it = p.item || {};
+  const lines = [];
+  lines.push(`Work on initiative ${p.initiative}${p.title ? ' — ' + p.title : ''}.`);
+  lines.push(`Step: ${it.key || it.kind}${it.text && it.text !== it.key ? ' — ' + it.text : ''}.`);
+  if (it.action) lines.push(`What is needed: ${it.action}`);
+  if (it.why && it.why !== it.action) lines.push(`Why this step is open: ${it.why}`);
+  lines.push(`You are on ${p.branch ? 'branch ' + p.branch : 'the current branch'}. Read AGENTS.md, then this initiative's record, PRD and rubric in planning/ before you act.`);
+  lines.push('');
+  lines.push('Rules that do not bend:');
+  for (const r of RULES) lines.push('- ' + r);
+  if (p.sources && p.sources.length) {
+    lines.push('');
+    lines.push('You may read these sources for context. They are read-only: look, do not write.');
+    for (const s of p.sources) lines.push('- ' + s.label);
+  }
+  if (p.judgment) { lines.push(''); lines.push(p.judgment); }
+  return lines.join('\n');
+}
+
+/** A short fingerprint of what the PM is shown. Go must carry it back; if anything changed, the start is refused. */
+function planHash(parts) {
+  return crypto.createHash('sha256').update(JSON.stringify([parts.prompt, parts.branch || null, parts.wsId || null, parts.plan || null, !!parts.judgment])).digest('hex').slice(0, 16);
+}
+
+module.exports = { actFor, annotate, refusal, sourcesFor, buildPrompt, planHash, ACT_TYPES, KNOWN_KEYS, WORK_KEYS, GATE_KEYS, RULES, SOURCE_LABEL };

package/workspace/lib/next-steps.js

@@ -0,0 +1,133 @@
+'use strict';
+/* next-steps.js — what is left between an initiative's present position and "accepted".
+ *
+ * The workflow engine already derives a ladder: each step is done, current, blocked, pending, na or
+ * unknown, and carries the action that would move it. The detail view used to show the one `next`
+ * action. This module lists the WHOLE remaining path, in order, from the facts the repository already
+ * holds — and invents nothing: every item names the fact it was read from, and a step the engine does
+ * not require never appears. Pure: no I/O, no clock, no model. A list a person can check against the
+ * ladder is the point; generated advice would be a second opinion about a derived fact.
+ *
+ * Order (PRD R4): the remaining ladder steps, then open needs items, a returned acceptance, the
+ * running sessions, and the PM acceptance. The item the engine names as `next` is marked `first`;
+ * with none named, the first item is.
+ *
+ * Input: { id, status, lifecycle:{state,reason,at}|null, accepted, returned, ladder:{ok,row}|null,
+ *          needs:[{question,kind}], sessions:[{id,name,state}] }
+ * Output: { state: 'accepted'|'stopped'|'open'|'unreadable', summary, items:[…] }
+ */
+
+const REMAINING = new Set(['blocked', 'current', 'pending', 'unknown']);
+
+// Who acts on a step. Acceptance, the contract approval, a document's approval and an outcome check are the PM's;
+// every other ladder step is the agent's. This is the one place that is decided: later work reads `owner`, it
+// does not re-decide it.
+const PM_STEPS = new Set(['accept', 'contract', 'approved', 'outcome']);
+const slug = (t) => String(t == null ? '' : t).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 40);
+
+const clip = (s, n = 200) => String(s == null ? '' : s).replace(/\s+/g, ' ').trim().slice(0, n);
+
+function stepItem(s) {
+  const unread = s.status === 'unknown';
+  return {
+    kind: 'step', key: s.key, status: s.status, owner: PM_STEPS.has(s.key) ? 'pm' : 'agent', act: null,
+    text: unread ? `${s.key} could not be read` : s.key,
+    action: clip(s.next || s.evidence || (unread ? 'the workflow engine could not decide this step' : 'no action recorded for this step')),
+    why: clip(s.evidence),
+    blocking: !!s.blocking,
+    source: 'workflow ladder' + (s.rule ? ` — ${clip(s.rule, 120)}` : ''),
+  };
+}
+
+// A stable id: initiative + kind + the thing it is about (the step key, the session id, the words of an open item).
+function withIds(id, items) {
+  const seen = new Map();
+  for (const it of items) {
+    const tail = it.kind === 'session' ? (it.sid || slug(it.text)) : it.kind === 'needs' ? slug(it.text) : it.key;
+    const base = `${id || 'initiative'}:${it.kind}:${tail}`;
+    const n = (seen.get(base) || 0) + 1; seen.set(base, n);
+    it.id = n > 1 ? `${base}:${n}` : base;
+  }
+  return items;
+}
+
+function deriveNextSteps(input) {
+  const i = input || {};
+  const row = i.ladder && i.ladder.ok && i.ladder.row ? i.ladder.row : null;
+  const steps = row && Array.isArray(row.steps) ? row.steps : [];
+  const remaining = steps.filter((s) => REMAINING.has(s.status));
+  // blocked first (the engine's own choice of `next`), the rest in ladder order
+  const ordered = [...remaining.filter((s) => s.status === 'blocked'), ...remaining.filter((s) => s.status !== 'blocked')];
+  const live = (i.sessions || []).filter((s) => s && s.state !== 'exited');
+
+  if (i.accepted) {
+    return { state: 'accepted', summary: 'Accepted by the PM — nothing remains.', items: [] };
+  }
+
+  const stopped = i.lifecycle && i.lifecycle.state && i.lifecycle.state !== 'active' ? i.lifecycle : null;
+  if (stopped) {
+    const items = [{
+      kind: 'reopen', key: 'reopen', status: 'pending', owner: 'pm', act: null,
+      text: `Reopen — it is ${stopped.state}`,
+      action: 'Reopen it to put it back on the board and have its steps gate again. Nothing below is required while it is stopped.',
+      why: clip(stopped.reason), source: 'lifecycle.jsonl (D70)',
+    }, ...ordered.map((s) => ({ ...stepItem(s), held: true }))];
+    items.forEach((it, n) => { it.n = n + 1; it.first = n === 0; });
+    withIds(i.id, items);
+    return {
+      state: 'stopped',
+      summary: `Stopped (${stopped.state})${stopped.reason ? ' — ' + clip(stopped.reason, 120) : ''}. It is off the board and not gating. Reopen to continue; the steps it would then owe are listed after.`,
+      items,
+    };
+  }
+
+  if (!row) {
+    const why = i.ladder && i.ladder.error ? clip(i.ladder.error, 160) : 'no initiative record, so no loop position can be derived';
+    return { state: 'unreadable', summary: `No next steps can be listed — ${why}.`, items: [] };
+  }
+
+  // The ladder's own `accept` step is the acceptance: it goes last, after everything the PM would want settled first.
+  const acceptStep = ordered.find((s) => s.key === 'accept') || null;
+  const items = ordered.filter((s) => s.key !== 'accept').map(stepItem);
+  const hasAcceptStep = steps.some((s) => s.key === 'accept');
+  for (const n of (i.needs || [])) {
+    items.push({
+      kind: 'needs', key: 'needs', status: 'pending', owner: 'pm', act: null, text: clip(n.question || '(unstated)', 160),
+      action: 'Answer or clear this open item.', why: '', source: 'needs queue',
+    });
+  }
+  if (i.returned) {
+    items.push({
+      kind: 'returned', key: 'returned', status: 'blocked', owner: 'pm', act: null, text: 'The PM returned this at the Acceptance Gate',
+      action: 'Address the return, then request acceptance again.', why: '', source: 'acceptances.jsonl',
+    });
+  }
+  for (const s of live) {
+    items.push({
+      kind: 'session', key: 'session', status: 'current', owner: 'agent', act: null, sid: s.id || null, text: `Session “${clip(s.name, 60)}” is running on it`,
+      action: 'Let it finish, or end it before accepting.', why: '', source: 'live sessions',
+    });
+  }
+  if (acceptStep) items.push({ ...stepItem(acceptStep), kind: 'accept', owner: 'pm', text: 'PM Acceptance' });
+  else if (!hasAcceptStep) {
+    items.push({
+      kind: 'accept', key: 'accept', status: 'pending', owner: 'pm', act: null, text: 'PM Acceptance',
+      action: 'The PM names one thing verified by hand, then records the acceptance (D12). It is the PM’s and cannot be delegated.',
+      why: '', source: 'Acceptance Gate (D12)',
+    });
+  }
+
+  const engineNext = row.next && row.next.step ? row.next.step : null;
+  const firstIdx = engineNext ? Math.max(0, items.findIndex((x) => x.kind === 'step' && x.key === engineNext)) : 0;
+  items.forEach((it, n) => { it.n = n + 1; it.first = n === firstIdx; });
+  withIds(i.id, items);
+  if (!items.length) return { state: 'open', summary: 'No step is outstanding — the ladder shows every required step done. Acceptance is the PM’s.', items: [] };
+  const blockedN = items.filter((x) => x.status === 'blocked').length;
+  return {
+    state: 'open',
+    summary: `${items.length} thing${items.length === 1 ? '' : 's'} left to reach acceptance${blockedN ? `, ${blockedN} blocked` : ''}. Start with step ${firstIdx + 1}.`,
+    items,
+  };
+}
+
+module.exports = { deriveNextSteps };

package/workspace/lib/prompt-input.js

@@ -0,0 +1,18 @@
+'use strict';
+/* prompt-input.js — what the workspace types into an agent session as its first input.
+ *
+ * Claude Code reads input that begins with `/` as a slash command. Every agent skill body opens
+ * `/<skill-name> — …`, so a scheduled run of `skill-discover` was answered "Unknown command:
+ * /skill-discover" and the session did no work, while the schedule recorded `started`. The skill
+ * files keep their wording; the fix is here, at the one point where a body becomes typed input.
+ * A text that does not begin with `/` is returned unchanged. Pure: no I/O.
+ */
+const LEADING_SLASH = /^\s*\//;
+const PREFIX = 'Follow this skill: ';
+
+function safeFirstInput(text) {
+  const s = String(text == null ? '' : text);
+  return LEADING_SLASH.test(s) ? PREFIX + s.replace(/^\s+/, '') : s;
+}
+
+module.exports = { safeFirstInput, PREFIX };

package/workspace/lib/schedule-cli.js

@@ -0,0 +1,259 @@
+'use strict';
+/* schedule-cli.js — `pmos schedule …` and `pmos skill …`: the terminal face of the scheduler.
+ *
+ * Every command is a thin client of the running workspace server's own routes, so the terminal and the
+ * workspace can never disagree about a schedule: one store, one validator, one fire path. Nothing here
+ * writes a file itself. A refused value is reported with the allowed values and nothing is changed,
+ * because the server checks before it writes. With no server running the command says so and exits 1.
+ *
+ *   pmos schedule list [--all]
+ *   pmos schedule show <id|name>
+ *   pmos schedule add --skill S --cadence C [fields]       fields: --name --day --day-of-month --time --date
+ *   pmos schedule add --from-session ID|--from-file PATH --skill-name N [--output "A,B"] [--description T] [fields]
+ *   pmos schedule edit <id|name> [fields] [--skill S]      fields also: --until --max-runs  ('none' clears one)
+ *   pmos schedule run|enable|disable|rm <id|name>
+ *   pmos skill list | show <name> | new --name N --description T [--output "A,B"] [--body-file F]
+ *   pmos skill edit <name> --file F | copy <name>
+ *
+ * Pure of sockets: the caller passes `call` (an HTTP client) and `say`, so the whole thing is testable.
+ */
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const FLAG_FIELDS = {
+  name: 'name', skill: 'skill', cadence: 'cadence', day: 'day', 'day-of-month': 'dayOfMonth', time: 'time',
+  date: 'date', args: 'args', tier: 'tier', profile: 'profile', until: 'until', 'max-runs': 'max_runs',
+};
+const BOOLEAN_FLAGS = new Set(['all', 'help']);
+
+function parseArgs(argv) {
+  const pos = []; const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      const key = eq > 0 ? a.slice(2, eq) : a.slice(2);
+      if (BOOLEAN_FLAGS.has(key)) { flags[key] = true; continue; }
+      if (eq > 0) { flags[key] = a.slice(eq + 1); continue; }
+      const next = argv[i + 1];
+      if (next === undefined || (next.startsWith('--') && next.length > 2)) { flags[key] = ''; continue; }
+      flags[key] = next; i++;
+    } else pos.push(a);
+  }
+  return { pos, flags };
+}
+
+// The fields a command sets, as the server names them. 'none' clears until/max_runs/tier/profile/args.
+function fieldsFrom(flags) {
+  const out = {};
+  for (const [flag, key] of Object.entries(FLAG_FIELDS)) {
+    if (!(flag in flags)) continue;
+    const v = flags[flag];
+    const clearable = ['until', 'max_runs', 'tier', 'profile', 'args'].includes(key);
+    out[key] = clearable && (v === 'none' || v === '') ? null : v;
+  }
+  if (out.max_runs != null && /^\d+$/.test(String(out.max_runs))) out.max_runs = +out.max_runs;
+  if (out.dayOfMonth != null && /^\d+$/.test(String(out.dayOfMonth))) out.dayOfMonth = +out.dayOfMonth;
+  return out;
+}
+
+function gitRoot(dir) {
+  try { return execFileSync('git', ['-C', dir, 'rev-parse', '--show-toplevel'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); }
+  catch { return path.resolve(dir); }
+}
+
+function describe(s) {
+  const when = s.cadence === 'once' ? `once, ${s.date || '?'} at ${s.time || '09:00'}`
+    : s.cadence === 'weekly' ? `every ${s.day || 'Mon'} at ${s.time}`
+      : s.cadence === 'bi-weekly' ? `every other ${s.day || 'Mon'} at ${s.time}`
+        : s.cadence === 'monthly' ? `monthly on day ${s.dayOfMonth || 1} at ${s.time}`
+          : `every day at ${s.time}`;
+  return when;
+}
+
+function showLines(s) {
+  const lines = [
+    `${s.name}  (${s.id})`,
+    `  skill     ${s.skill}`,
+    `  when      ${describe(s)}  ·  ${s.enabled ? 'enabled' : 'disabled'}${s.endedReason ? ' — ended: ' + s.endedReason : ''}`,
+    `  next run  ${s.enabled && s.next ? new Date(s.next).toLocaleString() : '—'}`,
+    `  last run  ${s.lastRun ? new Date(s.lastRun).toLocaleString() + '  [' + (s.lastStatus || '?') + ']' : 'never'}`,
+    `  runs      ${+s.runs || 0}${s.max_runs ? ' of ' + s.max_runs : ''}${s.until ? '  ·  until ' + s.until + ' (that day included)' : ''}`,
+  ];
+  if (s.args) lines.push(`  args      ${s.args}`);
+  if (s.tier) lines.push(`  tier      ${s.tier}`);
+  if (s.profile) lines.push(`  profile   ${s.profile}`);
+  lines.push('  note      this schedule fires only while the workspace server is running; a slot missed while it is stopped is skipped, not caught up.');
+  return lines;
+}
+
+async function run(argv, { call, say, cwd = process.cwd() }) {
+  const [group, verb, ...rest] = argv;
+  const { pos, flags } = parseArgs(rest);
+  if (!group || flags.help || group === 'help') { usage(say); return group ? 0 : 1; }
+  if (!['schedule', 'skill'].includes(group)) { say(`✗ unknown command "${group}" — use schedule or skill`); return 1; }
+
+  // The server first: with none running, every command is the same one honest sentence.
+  const probe = await call('GET', '/api/schedules?all=1');
+  if (!probe) { say('✗ the workspace server is not running — start it with: pmos'); return 1; }
+
+  const fail = (msg) => { say('✗ ' + msg); return 1; };
+  const refused = (r, what) => fail(`${what} refused — ${(r && r.error) || 'the server did not answer'}. Nothing was changed.`);
+
+  async function repoWs() {
+    const root = gitRoot(flags.repo ? path.resolve(flags.repo) : cwd);
+    const wl = await call('GET', '/api/workspaces');
+    const hit = ((wl && wl.workspaces) || []).find((w) => path.resolve(w.root) === root);
+    return hit ? { id: hit.id, name: hit.name, root } : { missing: root };
+  }
+  async function pick(ref) {
+    if (!ref) return { err: 'say which schedule: its id or its name (pmos schedule list)' };
+    const all = ((await call('GET', '/api/schedules?all=1')) || {}).schedules || [];
+    const byId = all.filter((s) => s.id === ref || s.id.startsWith(ref));
+    const hits = byId.length ? byId : all.filter((s) => s.name.toLowerCase() === ref.toLowerCase());
+    if (hits.length === 1) return { s: hits[0] };
+    return { err: hits.length ? `"${ref}" matches ${hits.length} schedules — use the id` : `no schedule "${ref}" (pmos schedule list)` };
+  }
+
+  if (group === 'schedule') {
+    if (verb === 'list' || !verb) {
+      let list = probe.schedules || [];
+      if (!flags.all) {
+        const w = await repoWs();
+        if (!w.missing) list = list.filter((s) => s.ws === w.id);
+      }
+      if (!list.length) { say('no scheduled tasks here (pmos schedule add …, or --all for every repository)'); return 0; }
+      for (const s of list) say(`${s.enabled ? '●' : '○'} ${s.id}  ${s.name}  ·  ${s.skill}  ·  ${describe(s)}${s.endedReason ? '  ·  ended: ' + s.endedReason : ''}`);
+      return 0;
+    }
+    if (verb === 'show') {
+      const { s, err } = await pick(pos[0]); if (err) return fail(err);
+      showLines(s).forEach((l) => say(l)); return 0;
+    }
+    if (verb === 'add') {
+      const w = await repoWs();
+      if (w.missing) return fail(`${w.missing} is not a registered workspace — run \`pmos\` in it once, or pass --repo of one that is`);
+      const f = fieldsFrom(flags);
+      let created = null;
+      if (flags['from-session'] || flags['from-file']) {
+        const skillName = flags['skill-name'];
+        if (!skillName) return fail('--from-session and --from-file need --skill-name, the name for the new skill');
+        let work = '';
+        if (flags['from-file']) { try { work = fs.readFileSync(path.resolve(cwd, flags['from-file']), 'utf8'); } catch { return fail(`cannot read ${flags['from-file']}`); } }
+        else {
+          const t = await call('GET', '/api/sessions/transcript?id=' + encodeURIComponent(flags['from-session']) + '&max=6000');
+          if (!t || !t.ok) return refused(t, 'reading the session');
+          work = t.text;
+        }
+        if (!work.trim()) return fail('the source is empty — there is nothing to turn into a skill');
+        const out = flags.output || '';
+        const sk = await call('POST', '/api/skills', { name: skillName, description: flags.description || `Repeat: ${skillName}`, output: out, work, ws: w.id });
+        if (!sk || !sk.ok) return refused(sk, 'creating the skill');
+        created = sk.skill.id;
+        f.skill = created;
+        say(`✓ skill "${created}" written (user skill). Review it: pmos skill show ${created}`);
+      }
+      if (!f.skill) return fail('say which skill: --skill <name> (pmos skill list), or --from-session / --from-file');
+      if (!f.cadence) return fail('say when: --cadence daily|weekly|bi-weekly|monthly|once (with --time HH:MM, --day, --day-of-month or --date)');
+      f.name = f.name || (created ? `${created}` : f.skill);
+      f.task = f.skill;
+      const r = await call('POST', '/api/schedules', { ...f, ws: w.id });
+      if (!r || !r.ok) return refused(r, 'adding the schedule');
+      const s = r.schedule;
+      say(`✓ scheduled "${s.name}" (${s.id}) in ${w.name}: ${describe(s)}`);
+      say(`  next run ${s.nextRun ? new Date(s.nextRun).toLocaleString() : '—'} — fires only while the workspace server is running`);
+      return 0;
+    }
+    if (verb === 'edit') {
+      const { s, err } = await pick(pos[0]); if (err) return fail(err);
+      const f = fieldsFrom(flags);
+      if (f.skill) f.task = f.skill;
+      if (!Object.keys(f).length) return fail('nothing to change — pass a field, e.g. --time 08:00 or --max-runs 10');
+      const r = await call('POST', '/api/schedules/update', { id: s.id, ...f });
+      if (!r || !r.ok) return refused(r, 'the edit');
+      say(`✓ saved "${r.schedule.name}": ${describe(r.schedule)}`);
+      return 0;
+    }
+    if (verb === 'enable' || verb === 'disable') {
+      const { s, err } = await pick(pos[0]); if (err) return fail(err);
+      const r = await call('POST', '/api/schedules/update', { id: s.id, enabled: verb === 'enable' });
+      if (!r || !r.ok) return refused(r, verb);
+      say(`✓ "${r.schedule.name}" is ${r.schedule.enabled ? 'enabled' : 'disabled'}`);
+      return 0;
+    }
+    if (verb === 'run') {
+      const { s, err } = await pick(pos[0]); if (err) return fail(err);
+      const r = await call('POST', '/api/schedules/run', { id: s.id });
+      const res = r && r.result;
+      if (!r || !r.ok || !res || res.ok === false) return fail(`"${s.name}" did not start — ${(res && res.reason) || (r && r.error) || 'no answer'}`);
+      say(res.sessionId ? `✓ started session ${res.sessionId} for "${s.name}"` : `✓ ran "${s.name}"`);
+      return 0;
+    }
+    if (verb === 'rm' || verb === 'remove' || verb === 'delete') {
+      const { s, err } = await pick(pos[0]); if (err) return fail(err);
+      const r = await call('POST', '/api/schedules/delete', { id: s.id });
+      if (!r || !r.ok) return refused(r, 'removing');
+      say(`✓ removed "${s.name}"`);
+      return 0;
+    }
+    return fail(`unknown schedule command "${verb}" — list, show, add, edit, run, enable, disable, rm`);
+  }
+
+  // skill
+  const w = await repoWs();
+  const wsq = w.missing ? '' : '&ws=' + encodeURIComponent(w.id);
+  if (verb === 'list' || !verb) {
+    const r = await call('GET', '/api/skills' + (wsq ? '?' + wsq.slice(1) : ''));
+    for (const k of (r && r.skills) || []) say(`${k.source === 'user' ? '✎' : '·'} ${k.id}  [${k.source}]  ${k.description}`);
+    return 0;
+  }
+  if (verb === 'show') {
+    if (!pos[0]) return fail('say which skill: pmos skill show <name>');
+    const r = await call('GET', '/api/skills/read?id=' + encodeURIComponent(pos[0]) + wsq);
+    if (!r || !r.ok) return refused(r, 'reading the skill');
+    say(`# ${r.id} — ${r.source}${r.editable ? ' (yours — edit with: pmos skill edit ' + r.id + ' --file <path>)' : ' (read-only — pmos skill copy ' + r.id + ')'}`);
+    say(r.text);
+    return 0;
+  }
+  if (verb === 'new') {
+    if (!flags.name) return fail('--name is required');
+    let body = '';
+    if (flags['body-file']) { try { body = fs.readFileSync(path.resolve(cwd, flags['body-file']), 'utf8'); } catch { return fail(`cannot read ${flags['body-file']}`); } }
+    const r = await call('POST', '/api/skills', { name: flags.name, description: flags.description || '', output: flags.output || '', body, ws: w.missing ? undefined : w.id });
+    if (!r || !r.ok) return refused(r, 'creating the skill');
+    say(`✓ skill "${r.skill.id}" written. Edit it: pmos skill edit ${r.skill.id} --file <path>`);
+    return 0;
+  }
+  if (verb === 'edit') {
+    if (!pos[0] || !flags.file) return fail('usage: pmos skill edit <name> --file <path>   (the whole new skill text; "-" reads stdin)');
+    let text;
+    try { text = flags.file === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(path.resolve(cwd, flags.file), 'utf8'); } catch { return fail(`cannot read ${flags.file}`); }
+    const r = await call('POST', '/api/skills/save', { id: pos[0], text });
+    if (!r || !r.ok) return refused(r, 'saving the skill');
+    say(`✓ saved "${r.id}"`);
+    return 0;
+  }
+  if (verb === 'copy') {
+    if (!pos[0]) return fail('say which skill: pmos skill copy <name>');
+    const r = await call('POST', '/api/skills/copy', { id: pos[0], ws: w.missing ? undefined : w.id });
+    if (!r || !r.ok) return refused(r, 'copying');
+    say(`✓ copied as "${r.id}" — yours to edit`);
+    return 0;
+  }
+  return fail(`unknown skill command "${verb}" — list, show, new, edit, copy`);
+}
+
+function usage(say) {
+  say(`usage: pmos schedule <${COMMANDS.schedule.join('|')}> …   |   pmos skill <${COMMANDS.skill.join('|')}> …`);
+  say('  pmos schedule add --skill gather-requirements --cadence daily --time 07:30 [--until 2026-12-31] [--max-runs 20]');
+  say('  pmos schedule add --from-session <id> --skill-name my-check --cadence weekly --day Fri --time 16:00');
+  say('  pmos schedule edit <id|name> --time 08:00 --args "focus on the billing initiative" --tier deep --until none');
+  say('  fields: --name --skill --cadence --day --day-of-month --time --date --args --tier --profile --until --max-runs --repo');
+  say('  schedules fire only while the workspace server is running.');
+}
+
+// The commands this module answers, in one place: the usage line below and the user guide's drift test both read it.
+const COMMANDS = { schedule: ['list', 'show', 'add', 'edit', 'run', 'enable', 'disable', 'rm'], skill: ['list', 'show', 'new', 'edit', 'copy'] };
+
+module.exports = { run, parseArgs, fieldsFrom, COMMANDS };