create-pmos 0.518.0 → 0.520.0

package/workspace/lib/description-props.js

@@ -0,0 +1,214 @@
+'use strict';
+/* description-props.js — every initiative has its own description, drafted by Claude and kept by the PM (initiative initiative-description-field).
+ *
+ *   drafts(S, { only? })   PURE-ISH (reads files) → { drafts, ask: [{ id, title }] }   S is lib/outcomes.js scan(root)
+ *       new     an initiative with no `description:` line: the PRD's paragraph (the first under Problem, Why, Background, Context, Summary or
+ *               Overview, else its first prose paragraph), else the record's own first paragraph with the record boilerplate left out
+ *               ("Feature lane.", "Repo-native initiative record", the gate notes). Nothing readable: no draft, the id is listed in `ask`.
+ *       enrich  a description exists and the PRD's paragraph is fuller and not in it yet: the PRD's paragraph replaces it once the PM keeps it.
+ *   Each draft is the ai-guard shape { id, title, say, confidence, claims: [{ text, sources: [{ label, ref, quote }] }], data: { kind,
+ *   initiative, text, from? } }, ref path:line from the repository root and quote that line's text. No model: the sources' own words.
+ *   paragraphOf(lines, { prd }) → { text, n } | null      the paragraph and the 1-based line it starts on
+ *   create(deps) → { tick({ now }), runProduct(w, { now }) }   once a day per product, at most PER_DAY drafts under the initiative's ✦
+ *       (lib/proposals.js group `description`, section Check these), through lib/ai-guard.js file() (job `descriptions`, replay per product).
+ *       A dropped draft is not filed again; an open `new` draft goes once the record has a description. It never writes a record: only ✓.
+ *   deps: as lib/outcome-props.js { workspaces(), isLead(w), stateDirFor(w), boardOf(w, id), runtime(), open(now), env, every, mayRun(), warn() }
+ *   Off: PMOS_DESCRIPTIONS=off, or `pmos ai off descriptions`. */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const O = require('./outcomes.js');
+const PR = require('./proposals.js');
+
+const JOB = 'descriptions';
+const VERSION = 'descriptions-1';
+const PER_DAY = 3;
+const MAX = 700;
+const MIN = 60;
+const HEAD = /^#{1,3}\s*(problem|why|background|context|summary|overview)\b/i;
+const SKIP = /^\s*([-*+]|\d+[.)])\s|^\s*>|^\s*\||^\s*```|^\s*<!--|^\*\*[^*]+:\*\*/;
+// record boilerplate: a sentence that speaks about the record, the lane or the gates, not about the work
+const META = /\blane\b|\(D\d+[^)]*\)|done-criteria|Initiative Gate|frontmatter|front matter|Repo-native|^Anchored to\b|^Batch \d+ item \d+\.?$|\bno PRD\b|\bno rubric\b/i;
+
+const flagOff = (v) => /^(off|0|false|no)$/i.test(String(v == null ? '' : v).trim());
+const off = (env) => flagOff((env || process.env).PMOS_DESCRIPTIONS);
+const rel = (root, f) => path.relative(root, f).split(path.sep).join('/');
+const linesOf = (f) => { try { return fs.readFileSync(f, 'utf8').replace(/\r\n?/g, '\n').split('\n'); } catch { return null; } };
+const plain = (s) => String(s).replace(/!\[[^\]]*\]\([^)]*\)/g, '').replace(/\[([^\]]+)\]\([^)]*\)/g, '$1').replace(/[*`]+/g, '').replace(/(^|\W)_+(?=\w)|(?<=\w)_+(?=\W|$)/g, '$1').replace(/<[^>]+>/g, '').replace(/\s+/g, ' ').trim();
+const cut = (t) => (t.length > MAX ? t.slice(0, MAX - 1).replace(/\s+\S*$/, '') + '…' : t);
+const norm = (s) => String(s || '').toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+const clip = (s, n) => { const t = String(s || ''); return t.length > n ? t.slice(0, n - 1).replace(/\s+\S*$/, '') + '…' : t; };
+const localDay = (ms) => { const d = new Date(ms); return d.getFullYear() + '-' + String(d.getMonth() + 1).padStart(2, '0') + '-' + String(d.getDate()).padStart(2, '0'); };
+
+/** The body's paragraphs after the front matter: [{ n (1-based), lines: [text] }] */
+function paragraphs(L) {
+  let i = 0;
+  if (/^---\s*$/.test(L[0] || '')) { i = 1; while (i < L.length && !/^---\s*$/.test(L[i])) i++; i++; }
+  const out = [];
+  let cur = null;
+  for (; i < L.length; i++) {
+    const l = L[i];
+    if (!l.trim() || /^#{1,6}\s/.test(l)) { if (cur) out.push(cur); cur = null; if (/^#{1,6}\s/.test(l)) out.push({ n: i + 1, head: l }); continue; }
+    if (!cur) { if (SKIP.test(l)) continue; cur = { n: i + 1, lines: [] }; }
+    else if (SKIP.test(l)) { out.push(cur); cur = null; continue; }
+    cur.lines.push(l.trim());
+  }
+  if (cur) out.push(cur);
+  return out;
+}
+/** The paragraph a PRD (prd: true) or a record gives, boilerplate left out of a record's. → { text, n } | null */
+function paragraphOf(L, { prd = false } = {}) {
+  if (!L) return null;
+  const P = paragraphs(L);
+  if (prd) {
+    const h = P.findIndex((p) => p.head && HEAD.test(p.head));
+    const after = h >= 0 ? P.slice(h + 1).find((p) => p.head || p.lines) : null;
+    if (after && after.lines) { const t = plain(after.lines.join(' ')); if (t.length >= MIN) return { text: cut(t), n: after.n }; }
+    const first = P.find((p) => p.lines && plain(p.lines.join(' ')).length >= MIN);
+    return first ? { text: cut(plain(first.lines.join(' '))), n: first.n } : null;
+  }
+  // a record: the first paragraph before any section heading that is about the work. A paragraph with any sentence about the record, its
+  // lane or the gates is boilerplate and is skipped whole (precision first: a weak draft costs the PM a ✕).
+  for (const p of P) {
+    if (p.head) { if (/^#{2,6}\s/.test(p.head)) break; continue; }
+    const t = plain(p.lines.join(' '));
+    if (t.split(/(?<=[.!?:])\s+/).some((x) => META.test(x))) continue;
+    if (!/^[A-Z“"]/.test(t) || /^[\w ]{1,24}:\s/.test(t)) continue;   // a cut-off continuation or a labelled note ("Rollback: …") is not a description
+    if (t.length >= MIN && !/:$/.test(t)) return { text: cut(t), n: p.n };
+  }
+  return null;
+}
+
+function prdFile(root, it) {
+  const cands = [];
+  if (it.prd) cands.push(path.join(root, it.prd), path.join(root, 'pmos', it.prd));
+  cands.push(path.join(root, 'planning', 'prd', it.id + '-prd.md'), path.join(root, 'pmos', 'planning', 'prd', it.id + '-prd.md'));
+  for (const f of cands) {
+    const abs = path.resolve(f);
+    if (abs !== root && !abs.startsWith(root + path.sep)) continue;
+    try { if (fs.statSync(abs).isFile()) return abs; } catch { /* next */ }
+  }
+  return null;
+}
+const srcOf = (root, file, L, n, label) => ({ label, ref: rel(root, file) + ':' + n, quote: String(L[n - 1] || '').trim().slice(0, 400) });
+
+/** What a PRD says (the source and text), or null. */
+function fromPrd(S, it) {
+  const f = prdFile(S.root, it); if (!f) return null;
+  const L = linesOf(f), p = paragraphOf(L, { prd: true });
+  return p ? { text: p.text, source: srcOf(S.root, f, L, p.n, 'PRD') } : null;
+}
+function fromRecord(S, it) {
+  const f = path.join(S.root, it.record), L = linesOf(f), p = paragraphOf(L);
+  return p ? { text: p.text, source: srcOf(S.root, f, L, p.n, 'Its record') } : null;
+}
+/** The PRD says more: not already in the description, and fuller. */
+const saysMore = (desc, prd) => { const d = norm(desc), q = norm(prd); return !!q && !d.includes(q.slice(0, 60)) && !q.includes(d) ? q.length > d.length + 40 : false; };
+
+/** The ✦ drafts of one repository. */
+function drafts(S, { only = null } = {}) {
+  const out = [], ask = [];
+  for (const it of S.subjects) {
+    if (only && it.id !== only) continue;
+    const desc = it.fm.description ? String(it.fm.description.value || '').trim() : '';
+    const prd = fromPrd(S, it);
+    if (!desc) {
+      const d = prd || fromRecord(S, it);
+      if (!d) { ask.push({ id: it.id, title: it.title }); continue; }
+      out.push({ id: `description-new:${it.id}`, title: `Description for ${clip(it.title, 80)}`, confidence: 'medium',
+        claims: [{ text: clip(`${d.source.label === 'PRD' ? 'Its PRD' : 'Its record'} says: ${d.text}`, 240), sources: [d.source] }],
+        say: `It has no description yet. I suggest: "${d.text}"`, data: { kind: 'new', initiative: it.id, text: d.text } });
+    } else if (prd && saysMore(desc, prd.text)) {
+      out.push({ id: `description-enrich:${it.id}`, title: `A fuller description for ${clip(it.title, 80)}`, confidence: 'medium',
+        claims: [{ text: clip('Its PRD says: ' + prd.text, 240), sources: [prd.source] }],
+        say: `Its PRD says more than its description now. I suggest: "${prd.text}"`, data: { kind: 'enrich', initiative: it.id, text: prd.text, from: desc } });
+    }
+  }
+  return { drafts: out, ask };
+}
+
+/** The proposals line a draft becomes. */
+function lineOf(d, board, run) {
+  const type = d.data.kind === 'enrich' ? 'enrich' : 'new', ini = d.data.initiative;
+  const c = PR.clean('description', type, { title: type === 'enrich' ? 'A fuller description from the PRD' : 'What this initiative is', why: d.say,
+    sources: d.claims.flatMap((x) => x.sources).map((s) => ({ label: s.label, ref: s.ref })), items: [{ id: 'description', title: d.data.text }],
+    data: { text: d.data.text, ...(d.data.from ? { from: d.data.from } : {}) } });
+  if (c.error) return null;
+  return { kind: 'propose', ini, board, run, id: PR.idOf(ini, 'description', type, ''), ...c.prop };
+}
+
+/** One product's replay cases: its own drafts must all pass, and an initiative with nothing readable gets no draft. */
+function cases(S, list) {
+  return [{ name: 'the drafts of ' + String(S.root).split(/[\\/]/).pop(), run: async () => list.slice(0, PER_DAY), expect: { filed: Math.min(PER_DAY, list.length) } },
+    { name: 'nothing readable, no draft', run: async () => drafts({ ...S, subjects: [{ id: 'zz-no-source', title: 'No source', fm: {}, prd: '', record: 'zz-none/zz-no-source.md' }] }).drafts, expect: { none: true } }];
+}
+
+function create(deps) {
+  const warn = deps.warn || (() => {});
+  const lastDay = new Map();
+  let busy = false;
+  const guardLib = () => { try { return require('./ai-guard.js'); } catch { return null; } };
+
+  async function runProduct(w, { now = Date.now() } = {}) {
+    const dir = deps.stateDirFor(w); if (!dir) return { ws: w.id, filed: 0, why: 'no state folder' };
+    const rt = deps.runtime && deps.runtime();
+    const S = O.scan(w.root, { today: localDay(now) });
+    const F = PR.read(dir), kept = PR.keptIds(F);
+    // a record that has its description now: its open draft goes (zero is silence)
+    const has = new Map(S.subjects.map((it) => [it.id, it]));
+    for (const p of F.props.values()) {
+      if (p.group !== 'description' || kept.has(p.id)) continue;
+      const it = has.get(p.ini), sig = PR.sigOf(p);
+      if (F.drops.has(sig)) continue;
+      const desc = it && it.fm.description ? String(it.fm.description.value || '') : '';
+      if (!it || (p.type === 'new' && desc) || (p.type === 'enrich' && p.data && norm(desc) === norm(p.data.text))) PR.append(dir, { by: 'pmos:descriptions' }, { kind: 'drop', ini: p.ini, sig });
+    }
+    const fresh = [];
+    for (const d of drafts(S).drafts) {
+      const board = deps.boardOf(w, d.data.initiative); if (!board) continue;
+      const l = lineOf(d, board, ''); if (!l) continue;
+      const prev = F.props.get(l.id);
+      if (kept.has(l.id)) continue;
+      if (prev && (F.drops.has(PR.sigOf(prev)) || (prev.data && prev.data.text === l.data.text))) continue;   // dropped for good, or filed already
+      fresh.push({ d, board });
+      if (fresh.length >= PER_DAY) break;
+    }
+    if (!fresh.length) return { ws: w.id, filed: 0 };
+    const AG = guardLib(); if (!AG) return { ws: w.id, filed: 0, why: 'the shared guard is not installed' };
+    const version = VERSION + ':' + w.id, run = 'ds' + now.toString(36) + crypto.randomBytes(3).toString('hex');
+    if (!AG.off(JOB, { env: deps.env || process.env, settingsDir: rt }) && !AG.ready(rt, JOB, version)) {
+      const rep = await AG.replay(JOB, version, cases(S, fresh.map((x) => x.d)), { root: w.root, stateDir: rt, max: PER_DAY });
+      if (!rep.ok) { warn('descriptions replay ' + w.id, new Error(rep.failed.map((f) => f.name + ': ' + f.why).join('; '))); return { ws: w.id, filed: 0, replay: rep }; }
+    }
+    const byId = new Map(fresh.map((x) => [x.d.id, x]));
+    const r = await AG.file({ job: JOB, version, run, root: w.root, stateDir: rt, settingsDir: rt, env: deps.env || process.env, max: PER_DAY }, fresh.map((x) => x.d),
+      async (acc) => { for (const p of acc) { const x = byId.get(p.id); const l = x && lineOf(x.d, x.board, run); if (l) PR.append(dir, { by: 'agent:descriptions' }, l); } });
+    return { ws: w.id, filed: (r.filed || []).length, held: !!r.held, off: r.off || null };
+  }
+
+  async function tick({ now = Date.now() } = {}) {
+    if (off(deps.env) || busy) return { off: off(deps.env), running: busy };
+    let open = true;
+    try { open = deps.open ? !!deps.open(now) : true; } catch { open = true; }
+    if (!open) return { closed: true };
+    busy = true;
+    const out = [];
+    try {
+      const day = localDay(now);
+      for (const w of deps.workspaces()) {
+        if (lastDay.get(w.id) === day) continue;
+        try { if (deps.isLead && !deps.isLead(w)) continue; } catch { continue; }
+        lastDay.set(w.id, day);
+        try { out.push(await runProduct(w, { now })); } catch (e) { warn('descriptions ' + w.id, e); }
+      }
+    } finally { busy = false; }
+    return { ran: out };
+  }
+  if (deps.every > 0) {
+    const t = setInterval(() => { try { if (deps.mayRun && !deps.mayRun()) return; } catch { /* no lock: run */ } tick({}).catch((e) => warn('descriptions tick', e)); }, deps.every);
+    if (t.unref) t.unref();
+  }
+  return { tick, runProduct };
+}
+
+module.exports = { JOB, VERSION, PER_DAY, drafts, paragraphOf, lineOf, cases, create, off, fromPrd, fromRecord };

package/workspace/lib/headless.js

@@ -250,7 +250,17 @@ function initTools(line) {
   return o.tools.filter((t) => typeof t === 'string' && t.startsWith('mcp__'));
 }
 // The one line every run gets about a refused tool (fix 2026-11-02: a Jira refresh called the same denied tool again and again).
-const DENIED_RULE = 'A tool call that is refused in this run stays refused: never call that tool again. Carry on with the tools you have, and say in your answer what you could not read.';
+const DENIED_RULE = 'A tool call that is refused in this run stays refused: never call that tool again. Carry on with the tools you have, and say in your answer what you could not read. When a tool result is too long and is saved to a file, open that file with Read, and use offset and limit for a long file. Never read it with a shell command: that is refused.';
+// Hotfix 2026-11-04: a Jira search on the Mac returned more than Claude Code keeps inline, so its result went to a tool-results file; the run then
+// tried `Bash F=<file> …` to parse it, Bash was refused, and the run failed. A background run keeps connector results inline up to this limit,
+// and the rule above sends a saved result to Read. The PM's own MAX_MCP_OUTPUT_TOKENS, when set, wins.
+const HEADLESS_ENV = Object.freeze({ MAX_MCP_OUTPUT_TOKENS: '100000' });
+/** The run's environment with HEADLESS_ENV added where the PM has not set the variable. */
+function headlessEnv(env) {
+  const out = { ...(env || {}) };
+  for (const [k, v] of Object.entries(HEADLESS_ENV)) if (!out[k]) out[k] = v;
+  return out;
+}
 const DENIED_RE = /Permission to use ([\w.-]+) has been denied|requested permissions to use ([\w.-]+)/;
 /** Follows a run's stream and says when it calls a refused tool a second time: → { see(line) → tool name | null, denied: Map }. */
 function denialGuard(limit = 2) {
@@ -488,4 +498,4 @@ function runEnvOf(extra) {
   return out;
 }
 
-module.exports = { CONNECTOR_READ_KINDS, CONNECTOR_READ_SEED, DENIED_RULE, connectorReads, initTools, denialGuard, HEADLESS_SKILLS, HEADLESS_ORIGINS, ASK_ORIGINS, DRIVE_ORIGINS, SCAN_WEB_ORIGINS, SCAN_REPO_ORIGINS, SCAN_RESEARCH_WEB_ORIGINS, SCAN_RESEARCH_REPO_ORIGINS, WEB_KINDS, REPORT_SETUP_ORIGINS, REPORT_FIND_ORIGINS, CORE_DOC_ORIGINS, REPORT_DESIGN_ORIGINS, REPORT_SAMPLE_FETCH_ORIGINS, REPORT_STRUCTURE_ORIGINS, REPORT_STRUCTURE_DRY_ORIGINS, METRIC_DRAFT_ORIGINS, IMPACT_ORIGINS, TOOLS, SKILL_WRITE_DIRS, DEFAULT_TIMEOUT_MS, kindFor, argsFor, skillWriteDirs, timeoutMs, parseResult, streamLines, outcomeOf, signedOut, SIGNED_OUT_WHY, logLines, switchedOff, RUN_ENV, runEnvOf };
+module.exports = { CONNECTOR_READ_KINDS, CONNECTOR_READ_SEED, DENIED_RULE, HEADLESS_ENV, headlessEnv, connectorReads, initTools, denialGuard, HEADLESS_SKILLS, HEADLESS_ORIGINS, ASK_ORIGINS, DRIVE_ORIGINS, SCAN_WEB_ORIGINS, SCAN_REPO_ORIGINS, SCAN_RESEARCH_WEB_ORIGINS, SCAN_RESEARCH_REPO_ORIGINS, WEB_KINDS, REPORT_SETUP_ORIGINS, REPORT_FIND_ORIGINS, CORE_DOC_ORIGINS, REPORT_DESIGN_ORIGINS, REPORT_SAMPLE_FETCH_ORIGINS, REPORT_STRUCTURE_ORIGINS, REPORT_STRUCTURE_DRY_ORIGINS, METRIC_DRAFT_ORIGINS, IMPACT_ORIGINS, TOOLS, SKILL_WRITE_DIRS, DEFAULT_TIMEOUT_MS, kindFor, argsFor, skillWriteDirs, timeoutMs, parseResult, streamLines, outcomeOf, signedOut, SIGNED_OUT_WHY, logLines, switchedOff, RUN_ENV, runEnvOf };

package/workspace/lib/initiative-cli.js

@@ -11,6 +11,8 @@
  *   pmos initiative drop <proposal-eid>
  *   pmos initiative list
  *   pmos initiative export <id>                  the breakdown as markdown on stdout; nothing is written
+ *   pmos initiative describe <id> ["<text>"]     no text: its description and the cited lines Claude can draft it from; with text: write
+ *                                                its `description:` line (initiative-description-field). An agent writes only after the PM's yes
  *   every command: [--json] [--root <dir>]
  *
  * The SAME writers the workspace page uses (lib/initiative-writer.js, lib/placements.js) — no server is needed. Who
@@ -59,11 +61,11 @@ function docNote(docs) {
   return `Not on the Roadmap · ${docs.length} on a document lane: ${names}. A document lane does not show on Home or the Board. If it is work, set lane: in its record to ${WORK_LANES}.`;
 }
 
-const COMMANDS = { initiative: ['new', 'top', 'up', 'down', 'bottom', 'after', 'check-by', 'adopt', 'drop', 'list', 'export'] };
+const COMMANDS = { initiative: ['new', 'top', 'up', 'down', 'bottom', 'after', 'check-by', 'adopt', 'drop', 'list', 'export', 'describe'] };
 /** The horizon verbs D105 retired: they answer with what to use instead. */
 const RETIRED = Object.freeze(['now', 'next', 'later']);
 const USAGE = [
-  'usage: pmos initiative new|top|up|down|bottom|after|check-by|adopt|drop|list|export — initiatives on the Roadmap',
+  'usage: pmos initiative new|top|up|down|bottom|after|check-by|adopt|drop|list|export|describe — initiatives on the Roadmap',
   '  pmos initiative new "<title>" --lane <lane> --anchor <KR|health:id> [--intent "<text>"] [--id <id>]',
   '  pmos initiative new --from capture-YYYY-MM-DD-<n> [--anchor <anchor>] [--lane <lane>] [--title "<title>"]',
   '  pmos initiative top|up|down|bottom <id>  reorder it on the Roadmap',
@@ -73,6 +75,7 @@ const USAGE = [
   '  pmos initiative drop <proposal>          close an open proposal',
   '  pmos initiative list                     the Roadmap, ranked, with each lifecycle stage',
   '  pmos initiative export <id>              the breakdown as markdown on stdout',
+  '  pmos initiative describe <id> ["<text>"]  read its description and what to draft it from; with text, save it (after the PM\'s yes)',
   '  every command: [--json] [--root <dir>]',
   'An agent session\'s move applies at once and names the agent. A new initiative lands at the end of the Roadmap.',
   'Now, Next and Later are retired (D105): the rank says what comes first, the lifecycle stage says where it is.',
@@ -205,6 +208,29 @@ async function run(argv, { say = (s) => console.log(s), cwd = process.cwd(), isT
     return done({ written: r.written }, `✓ proposal ${eid} ${verb === 'adopt' ? 'kept' : 'dropped'}`);
   }
 
+  if (verb === 'describe') {
+    // initiative-description-field: the record's own description. Read with no text; write with text, only after the PM said yes.
+    const did = pos[0];
+    if (!did || pos.length > 2) { say('usage: pmos initiative describe <id> ["<text>"]'); return 2; }
+    if (pos.length === 2) {
+      const r = writer.setDescription(root, did, pos[1], { actor: actorLib.fromCli(who) });
+      if (!r.ok) return fail(r.error, r.status === 400 ? 2 : 1);
+      return done({ id: did, description: r.text, from: r.from, same: !!r.same }, r.same ? `${did} says that already.` : `✓ ${did}: description saved. About shows it now. Commit the record to keep it.`);
+    }
+    const O = require('./outcomes.js'), DP = require('./description-props.js');
+    const S = O.scan(root);
+    const it = S.subjects.find((x) => x.id === did);
+    if (!it) return fail(`no initiative ${did} here (or it is stopped, or on a document lane)`);
+    const cur = it.fm.description ? String(it.fm.description.value || '') : '';
+    const srcs = [DP.fromPrd(S, it), DP.fromRecord(S, it)].filter(Boolean);
+    if (json) { say(JSON.stringify({ ok: true, id: did, description: cur || null, sources: srcs.map((x) => ({ label: x.source.label, ref: x.source.ref, text: x.text })) })); return 0; }
+    say(cur ? `${did}: ${cur}` : `${did} has no description yet.`);
+    if (srcs.length) say('Draft it from:\n' + srcs.map((x) => `  · ${x.source.label} [${x.source.ref}]: ${x.text}`).join('\n'));
+    else say('Nothing readable to draft it from (no PRD paragraph, no paragraph in its record): ask the PM what it is.');
+    say(`Show the draft to the PM; after a yes: pmos initiative describe ${did} "<text>"`);
+    return 0;
+  }
+
   const id = pos[0];
   if (!id) { say(`usage: pmos initiative ${verb} <id>${verb === 'check-by' ? ' <YYYY-MM-DD|none>' : ''}`); return 2; }
 

package/workspace/lib/initiative-writer.js

@@ -298,6 +298,46 @@ function restoreOutcome(root, id, from = {}, to = {}, { actor } = {}) {
   return { ok: true, id };
 }
 
+/** The record's own description (initiative-description-field): one `description:` line in the front matter, one paragraph of at most
+ *  DESC_MAX characters. About shows it before the PRD's paragraph (pm/ini-about.js). The PM's ✓ on a ✦ draft (lib/routes-proposals.js) and
+ *  `pmos initiative describe <id> "<text>"` after the PM's yes reach here. → { ok: true, id, from, text, same? } | refusal */
+const DESC_MAX = 700;
+const frontOfText = (text) => /^---\r?\n([\s\S]*?)\r?\n---(\r?\n|$)/.exec(text);
+const descLine = (lines) => { const at = lines.findIndex((l) => l.startsWith('description:')); return { at, val: at >= 0 ? unquote(lines[at].slice(12)) : '' }; };
+function setDescription(root, id, text0, { actor } = {}) {
+  if (!actorLib.valid(actor)) return refuse(500, 'initiative-writer: the caller must pass the actor from pm-guard.js or actor.js');
+  const t = typeof text0 === 'string' ? text0.replace(/\s+/g, ' ').trim() : '';
+  if (t.length < 12 || t.length > DESC_MAX) return refuse(400, `say what the initiative is in one paragraph of 12 to ${DESC_MAX} characters`, 'description');
+  const f = recordFile(root, id);
+  if (!f.ok) return f;
+  const text = fs.readFileSync(f.file, 'utf8');
+  const fm = frontOfText(text);
+  if (!fm) return refuse(409, `the record of ${id} has no front matter — nothing was saved`, 'id');
+  const lines = fm[1].split(/\r?\n/);
+  const { at, val: from } = descLine(lines);
+  if (from === t) return { ok: true, id, from, text: t, same: true };
+  const line = 'description: ' + q(t);
+  if (at >= 0) lines[at] = line; else lines.push(line);
+  try { fs.writeFileSync(f.file, '---\n' + lines.join('\n') + '\n---' + fm[2] + text.slice(fm[0].length), { flag: 'w' }); } catch { return refuse(500, 'the record could not be written — nothing was saved'); }
+  return { ok: true, id, from, text: t };
+}
+/** The Undo of a ✓ on a description ✦: the line back to `from` (removed when there was none), only while it still says `to`.
+ *  A record the PM edited since keeps its edit (→ { ok: true, kept: true }). */
+function restoreDescription(root, id, from, to, { actor } = {}) {
+  if (!actorLib.valid(actor)) return refuse(500, 'initiative-writer: the caller must pass the actor from pm-guard.js or actor.js');
+  const f = recordFile(root, id);
+  if (!f.ok) return f;
+  const text = fs.readFileSync(f.file, 'utf8');
+  const fm = frontOfText(text);
+  if (!fm) return refuse(409, `the record of ${id} has no front matter — nothing was saved`, 'id');
+  const lines = fm[1].split(/\r?\n/);
+  const { at, val } = descLine(lines);
+  if (val !== String(to || '')) return { ok: true, id, kept: true };
+  if (from) { const line = 'description: ' + q(from); if (at >= 0) lines[at] = line; else lines.push(line); } else if (at >= 0) lines.splice(at, 1);
+  try { fs.writeFileSync(f.file, '---\n' + lines.join('\n') + '\n---' + fm[2] + text.slice(fm[0].length), { flag: 'w' }); } catch { return refuse(500, 'the record could not be written — nothing was saved'); }
+  return { ok: true, id };
+}
+
 function withdrawSplit(root, id, want, { actor } = {}) {
   if (!actorLib.valid(actor)) return refuse(500, 'initiative-writer: the caller must pass the actor from pm-guard.js or actor.js');
   const f = recordFile(root, id);
@@ -309,4 +349,4 @@ function withdrawSplit(root, id, want, { actor } = {}) {
   return { ok: true, removed: true };
 }
 
-module.exports = { setOutcome, restoreOutcome, createInitiative, renameInitiative, setAnchor, restoreAnchor, withdrawSplit, recordSha, slugOf, ID_RE, INPUT_KEYS };
+module.exports = { setDescription, restoreDescription, DESC_MAX, setOutcome, restoreOutcome, createInitiative, renameInitiative, setAnchor, restoreAnchor, withdrawSplit, recordSha, slugOf, ID_RE, INPUT_KEYS };

package/workspace/lib/proposals.js

@@ -18,6 +18,9 @@
  *   outcome the expected outcome and its check date (D57; lib/outcomes.js, filed by lib/outcome-props.js): type new (no outcome yet) or date
  *           (an outcome with no date). data { metric, horizon }; one item { id: 'outcome', title: the metric, due: the date }. Always section
  *           'check': its own ✓, never Keep all. ✓ writes the record's outcome_metric and outcome_horizon lines (lib/initiative-writer.js)
+ *   description the record's own description (initiative-description-field; filed by lib/description-props.js): type new (none yet) or
+ *           enrich (the PRD says more). data { text, from? }; one item { id: 'description', title: the text cut }. Always section 'check'.
+ *           ✓ writes the record's description line (lib/initiative-writer.js setDescription)
  *   grill   what Claude found when it grilled the initiative by itself (lib/grill.js): type = the angle, no items, a next step in data.next;
  *           always section 'check' (its own ✓, never Keep all). 3 show, best rank first; the group's `more` counts the rest
  *
@@ -56,8 +59,8 @@ const crypto = require('crypto');
 
 const LEDGER = 'proposals.jsonl';
 const KINDS = new Set(['epoch', 'look', 'src', 'end', 'propose', 'drop', 'keep', 'undo']);
-const GROUPS = ['found', 'dates', 'status', 'names', 'outcome'];
-const TYPES = { found: ['stage', 'docs', 'tasks', 'link', 'maybe', 'unplaced'], dates: ['stage', 'task'], status: ['done'], names: ['tidy'], outcome: ['new', 'date'] };
+const GROUPS = ['found', 'dates', 'status', 'names', 'outcome', 'description'];
+const TYPES = { found: ['stage', 'docs', 'tasks', 'link', 'maybe', 'unplaced'], dates: ['stage', 'task'], status: ['done'], names: ['tidy'], outcome: ['new', 'date'], description: ['new', 'enrich'] };
 const SOURCES = ['drive', 'docs', 'sheets', 'slides', 'jira', 'calendar', 'notes', 'mail', 'slack', 'confluence', 'chat', 'repo'];
 const SOURCE_NAMES = { drive: 'Drive and Slides', docs: 'Docs', sheets: 'Sheets', slides: 'Slides', jira: 'Jira', calendar: 'Calendar and meeting notes', notes: 'Meeting notes',
   mail: 'Gmail', slack: 'Slack', confluence: 'Confluence', chat: 'Chat', repo: 'This repository' };
@@ -155,7 +158,13 @@ function clean(group, type, input) {
     if (!DAY_RE.test(horizon)) return { error: 'data.horizon is the check date, YYYY-MM-DD' };
     data.metric = metric; data.horizon = horizon;
   }
-  return { prop: { group, type, section: group === 'outcome' ? 'check' : section, title: one(input.title, LIM.title) || null, why, sources: s.v, items, data } };
+  if (group === 'description') {
+    const d = isObj(input.data) ? input.data : {};
+    const text = one(d.text, 700);
+    if (text.length < 12) return { error: 'data.text is the description, one paragraph of 12 to 700 characters' };
+    data.text = text; if (str(d.from)) data.from = one(d.from, 700);
+  }
+  return { prop: { group, type, section: group === 'outcome' || group === 'description' ? 'check' : section, title: one(input.title, LIM.title) || null, why, sources: s.v, items, data } };
 }
 /** The proposal's own id: one per initiative, group, type and key, so a newer run files over the older one. */
 const idOf = (ini, group, type, key) => 'pr-' + hash([ini, group, type, key || ''].join('|'));
@@ -323,7 +332,7 @@ function datesOf(ini, T, o = {}) {
 }
 
 /* ── what r.props carries ── */
-const ORDER = { outcome: -1, found: 0, dates: 1, status: 2, names: 3, links: 4, grill: 5 };
+const ORDER = { description: -2, outcome: -1, found: 0, dates: 1, status: 2, names: 3, links: 4, grill: 5 };
 const GRILL_SHOWN = 3;
 /**
  * One initiative's proposals, as the ✦ and the Viewer draw them, or null when there is nothing to show.

package/workspace/lib/routes-next-prompt.js

@@ -2,16 +2,17 @@
 /* routes-next-prompt.js — the chat's suggested next prompt and its Sharper card over HTTP (batch 26 item 2, design B; lib/next-prompt.js).
  *
  *   GET  /api/next-prompt/prefs                    → { ok, next, sharpen, sharpenSet, style, rules, api }
- *        next: suggestions after a reply are on. sharpen: Sharpen as I type is on now ('auto' is on when Claude's runs go to the API, where a
- *        call takes about 2 s; a background `claude -p` run takes 10 s or more, too slow to follow typing). sharpenSet: 'auto'|'on'|'off'.
- *        style: 'polish'|'engineer'|'own'. rules: whether Your own rules are written. api: a key for the Claude API is set.
+ *        next: suggestions after a reply are on. sharpen: Sharpen as I type is on now (on unless the PM turned it off; 'auto' is off only
+ *        while an opted-in API path is failing). sharpenSet: 'auto'|'on'|'off'. style: 'polish'|'engineer'|'own'. rules: whether Your own
+ *        rules are written. api: the opted-in API path is in use (PMOS_NEXT_PROMPT_API=on and a key). apiDown: { why, auth } while it fails.
  *   POST /api/next-prompt/prefs   { key: 'next'|'sharpen'|'style'|'rules', value }          → { ok } (saved in <runtime>/next-prompt/prefs.json)
  *   POST /api/next-prompt/next    { key, asked, reply, initiative?, stage?, product?, title? }  → { ok, on, cards: [{ text, move, rec }] }
  *   POST /api/next-prompt/sharpen { key, text, reply?, initiative?, title? }                  → { ok, on, text | null }
  *
  * Both POSTs are page presses (lib/pm-guard.js requirePagePress; an agent session header is refused) and run ONE short Claude call:
- * on the API with the PM's key when one is set (lib/anthropic-key.js, model PMOS_NEXT_PROMPT_MODEL or claude-sonnet-5-5), else a headless
- * read-only run (lib/headless.js kind 'ask', origin briefing-ask:next-prompt:…). The answer goes through the shared door, lib/ai-guard.js file():
+ * a background read-only `claude -p` run on the PM's own Claude login (lib/headless.js kind 'ask', origin briefing-ask:next-prompt:…), the
+ * default (Wawan 2026-11-04). Only with PMOS_NEXT_PROMPT_API=on does it go to the API with the PM's key (lib/anthropic-key.js, model
+ * PMOS_NEXT_PROMPT_MODEL or claude-sonnet-5-5), and a failed API call then falls back to the background run. The answer goes through the shared door, lib/ai-guard.js file():
  * the kill switch (`pmos ai off next-prompt`, `pmos ai off sharpen-prompt`, PMOS_AI=off), the replay gate (fixtures/next-prompt-replay.json,
  * recorded answers, never a model), the citation check and the audit (<runtime>/ai-audit.jsonl). A card with no verified source is never
  * shown. The reply and the typed text a card cites are kept in <runtime>/next-prompt/ (the newest 30 files), outside every repository.
@@ -61,14 +62,29 @@ function setPref(runtimeDir, key, value) {
 const get = (ctx, k) => { const v = readPrefs(ctx.runtimeDir)[k]; return PREFS[k](v) ? v : undefined; };
 const envOf = (ctx) => ctx.env || process.env;
 
+/* Wawan 2026-11-04: "just default to normal claude session with -p". Both calls run as a background `claude -p` on the PM's own Claude login.
+ * The API key is used only when PMOS_NEXT_PROMPT_API=on opts in. */
 function apiKey(ctx) {
   const env = envOf(ctx);
-  if (/^(off|0|false|no)$/i.test(String(env.PMOS_NEXT_PROMPT_API || ''))) return null;
+  if (!/^(on|1|true|yes)$/i.test(String(env.PMOS_NEXT_PROMPT_API || ''))) return null;
   try { return require('./anthropic-key.js').getKey(ctx.runtimeDir, env); } catch { return null; }
 }
+/* The API's health, per state folder, in memory: after a failed call PMOS stops calling the API for DOWN_MS and uses the background run,
+ * so a spent balance or a refused key does not fail every reply again. A server restart, or a new key saved, tries the API again. */
+const DOWN_MS = 15 * 60 * 1000;
+const apiDown = new Map();   // runtimeDir → { until, why, auth, key }
+function downOf(ctx, key) {
+  const d = apiDown.get(ctx.runtimeDir);
+  if (!d) return null;
+  if (d.until <= Date.now() || d.key !== keyId(key)) { apiDown.delete(ctx.runtimeDir); return null; }
+  return d;
+}
+const keyId = (k) => (k ? crypto.createHash('sha1').update(String(k)).digest('hex').slice(0, 12) : '');
 function prefs(ctx) {
-  const set = get(ctx, 'sharpen') || 'auto', api = !!apiKey(ctx), style = get(ctx, 'style') || 'engineer', rules = String(get(ctx, 'rules') || '');
-  return { next: get(ctx, 'next') !== false, sharpen: set === 'on' || (set === 'auto' && api), sharpenSet: set, style, rules: !!rules.trim(), rulesText: rules, api };
+  const set = get(ctx, 'sharpen') || 'auto', k = apiKey(ctx), down = k ? downOf(ctx, k) : null, api = !!k && !down;
+  const style = get(ctx, 'style') || 'engineer', rules = String(get(ctx, 'rules') || '');
+  return { next: get(ctx, 'next') !== false, sharpen: set !== 'off' && !(set === 'auto' && k && down), sharpenSet: set, style, rules: !!rules.trim(), rulesText: rules, api,
+    ...(down ? { apiDown: { why: down.why, auth: down.auth } } : {}) };
 }
 function offWhy(ctx, job) {
   const why = AG.off(job, { env: envOf(ctx), settingsDir: ctx.runtimeDir });
@@ -81,31 +97,55 @@ function offWhy(ctx, job) {
 
 /* ── the call ────────────────────────────────────────────────────────────────────────────── */
 
-async function viaApi(key, prompt, env) {
-  const Anthropic = require('@anthropic-ai/sdk');
-  const api = new Anthropic({ apiKey: key });
-  const res = await api.messages.create({ model: String(env.PMOS_NEXT_PROMPT_MODEL || '').trim() || DEFAULT_MODEL, max_tokens: 800, messages: [{ role: 'user', content: prompt }] });
-  return (res.content || []).filter((b) => b.type === 'text').map((b) => b.text).join('\n');
+// A model the account cannot use (404) tries the next one before the call counts as failed.
+const MODELS = ['claude-sonnet-5-5', 'claude-sonnet-5', 'claude-haiku-5-5'];
+async function viaApi(key, prompt, env, create = null) {
+  const make = create || ((o) => { const Anthropic = require('@anthropic-ai/sdk'); return new Anthropic({ apiKey: key }).messages.create(o); });
+  const want = String(env.PMOS_NEXT_PROMPT_MODEL || '').trim();
+  const models = want ? [want] : MODELS;
+  for (let i = 0; i < models.length; i++) {
+    try {
+      const res = await make({ model: models[i], max_tokens: 800, messages: [{ role: 'user', content: prompt }] });
+      return (res.content || []).filter((b) => b.type === 'text').map((b) => b.text).join('\n');
+    } catch (e) { if (!(e && e.status === 404) || i === models.length - 1) throw e; }
+  }
+  return null;
 }
-function viaHeadless(ctx, prompt, origin) {
+/** A background read-only Claude run → its answer text, or null after `fail(why)` says why it gave none. */
+function viaHeadless(ctx, prompt, origin, fail = () => {}) {
   const headless = require('./headless.js');
-  if (typeof ctx.spawnSession !== 'function' || headless.kindFor({ agent: 'claude', origin }) !== 'ask') return Promise.resolve(null);
+  if (typeof ctx.spawnSession !== 'function') { fail('no background run here'); return Promise.resolve(null); }
+  if (headless.kindFor({ agent: 'claude', origin }) !== 'ask') { fail('the run would not be read-only'); return Promise.resolve(null); }
   return new Promise((resolve) => {
-    let settled = false; const done = (v) => { if (!settled) { settled = true; clearTimeout(t); resolve(v); } };
-    const t = setTimeout(() => done(null), TIMEOUT_MS);
+    let settled = false; const done = (v, why) => { if (settled) return; settled = true; clearTimeout(t); if (v == null) fail(why); resolve(v); };
+    const t = setTimeout(() => done(null, 'the run took longer than ' + Math.round(TIMEOUT_MS / 1000) + ' s'), TIMEOUT_MS);
     let s = null;
     try {
       s = ctx.spawnSession({ name: 'chat: next prompt', agent: 'claude', origin, initialInput: prompt,
-        onDone: (d) => { const r = d && d.result; done(r && r.ok && !r.isError ? String(r.text || '') : null); } });
-    } catch { s = null; }
-    if (!s || s.state === 'exited') done(null);
+        onDone: (d) => { const r = d && d.result; done(r && r.ok && !r.isError ? String(r.text || '') : null, 'the run ended without an answer' + (d && d.note ? ': ' + String(d.note).slice(0, 80) : '')); } });
+    } catch (e) { s = null; }
+    if (!s || s.state === 'exited') done(null, 'the run did not start' + (s && s.note ? ': ' + String(s.note).slice(0, 80) : ''));
   });
 }
-async function ask(ctx, prompt, { job, key }) {
+/** Why an API call failed, in words fit for the audit: the HTTP status and the error's type, never the prompt or the answer. */
+function apiWhy(e) {
+  const st = e && (e.status || (e.response && e.response.status));
+  const kind = e && ((e.error && e.error.error && e.error.error.type) || e.name || e.code);
+  return ['api', st ? String(st) : null, kind ? String(kind).slice(0, 60) : null].filter(Boolean).join(' ');
+}
+/* One short Claude call. With a key it goes to the API; when that call fails (a spent balance, a model the account cannot use, no network),
+ * it does not end in silence: the same prompt goes to a background read-only Claude run, and the audit records why the API failed
+ * (`pmos ai log next-prompt`); for 15 minutes after, PMOS goes straight to the background run. `ctx.createMessage` replaces the SDK in tests. */
+async function ask(ctx, prompt, { job, key, run }) {
   if (typeof ctx.askClaude === 'function') return ctx.askClaude(prompt, { job, key });
   const k = apiKey(ctx);
-  if (k) { try { return await viaApi(k, prompt, envOf(ctx)); } catch { return null; } }
-  return viaHeadless(ctx, prompt, `briefing-ask:next-prompt:${job}:${crypto.createHash('sha1').update(String(key)).digest('hex').slice(0, 10)}`);
+  if (k && !downOf(ctx, k)) {
+    const failed = (why, auth) => { apiDown.set(ctx.runtimeDir, { until: Date.now() + DOWN_MS, why, auth: !!auth, key: keyId(k) }); AG.audit(ctx.runtimeDir, { job, version: VERSION, run, event: 'api-error', error: why }); };
+    try { const t = await viaApi(k, prompt, envOf(ctx), ctx.createMessage || null); if (t && String(t).trim()) return t; failed('api empty answer', false); }
+    catch (e) { failed(apiWhy(e), e && (e.status === 401 || e.status === 403)); }
+  }
+  return viaHeadless(ctx, prompt, `briefing-ask:next-prompt:${job}:${crypto.createHash('sha1').update(String(key)).digest('hex').slice(0, 10)}`,
+    (why) => AG.audit(ctx.runtimeDir, { job, version: VERSION, run, event: 'run-error', error: String(why).slice(0, 160) }));
 }
 
 /* ── what a card cites ───────────────────────────────────────────────────────────────────── */
@@ -182,7 +222,7 @@ async function next(ctx, b) {
   const k = 'n:' + key + ':' + crypto.createHash('sha1').update(reply + '\n' + P.style + '\n' + P.rulesText).digest('hex');
   return once(k, async () => {
     AG.audit(ctx.runtimeDir, { job, version: VERSION, run, event: 'start' });
-    const answer = await ask(ctx, NP.nextPrompt({ pm: text(b.asked, 2000), reply, place, style: P.style, rules: P.rulesText, moves }), { job, key });
+    const answer = await ask(ctx, NP.nextPrompt({ pm: text(b.asked, 2000), reply, place, style: P.style, rules: P.rulesText, moves }), { job, key, run });
     const cards = NP.parseNext(answer, { moves, place });
     if (!cards.length) { AG.audit(ctx.runtimeDir, { job, version: VERSION, run, event: 'end', filed: 0, dropped: 0, ...(answer == null ? { error: 'no answer' } : {}) }); return { ok: true, on: true, cards: [] }; }
     const rel = keep(ctx.runtimeDir, 'reply', reply);
@@ -200,7 +240,7 @@ async function sharpen(ctx, b) {
   const k = 's:' + key + ':' + crypto.createHash('sha1').update(typed + '\n' + P.style + '\n' + P.rulesText).digest('hex');
   return once(k, async () => {
     AG.audit(ctx.runtimeDir, { job, version: VERSION, run, event: 'start' });
-    const answer = await ask(ctx, NP.sharpenPrompt({ text: typed, reply: text(b.reply, 3000), place: placeOf(b), style: P.style, rules: P.rulesText }), { job, key });
+    const answer = await ask(ctx, NP.sharpenPrompt({ text: typed, reply: text(b.reply, 3000), place: placeOf(b), style: P.style, rules: P.rulesText }), { job, key, run });
     const out = NP.parseSharpen(answer, typed);
     if (!out) { AG.audit(ctx.runtimeDir, { job, version: VERSION, run, event: 'end', filed: 0, dropped: 0, ...(answer == null ? { error: 'no answer' } : { same: true }) }); return { ok: true, on: true, text: null }; }
     const first = typed.split('\n')[0], rel = keep(ctx.runtimeDir, 'typed', typed);
@@ -227,7 +267,7 @@ async function handle(req, res, url, ctx) {
     if (req.method !== 'GET') return send(bad(405, 'GET or POST only'));
     const P = prefs(ctx), env = envOf(ctx);
     const next = P.next && !AG.off(NP.JOB_NEXT, { env, settingsDir: ctx.runtimeDir }), sh = P.sharpen && !AG.off(NP.JOB_SHARPEN, { env, settingsDir: ctx.runtimeDir });
-    return send({ status: 200, body: { ok: true, next, nextSet: P.next, sharpen: sh, sharpenSet: P.sharpenSet, style: P.style, rules: P.rules, rulesText: P.rulesText, api: P.api } });
+    return send({ status: 200, body: { ok: true, next, nextSet: P.next, sharpen: sh, sharpenSet: P.sharpenSet, style: P.style, rules: P.rules, rulesText: P.rulesText, api: P.api, ...(P.apiDown ? { apiDown: P.apiDown } : {}) } });
   }
   if (what !== 'next' && what !== 'sharpen') return send(bad(404, 'no such next-prompt route'));
   if (req.method !== 'POST') return send(bad(405, 'POST only'));
@@ -245,4 +285,4 @@ async function handle(req, res, url, ctx) {
   catch (e) { return send(bad(500, 'The suggestion failed: ' + String((e && e.message) || e).slice(0, 200))); }
 }
 
-module.exports = { prefixes: ['/api/next-prompt'], handle, VERSION, FIXTURE, prefs, setPref, lineRef, replayCases, next, sharpen };
+module.exports = { prefixes: ['/api/next-prompt'], handle, VERSION, FIXTURE, MODELS, prefs, setPref, lineRef, replayCases, next, sharpen };

package/workspace/lib/routes-proposals.js

@@ -138,6 +138,10 @@ function applyOne(ctx, p, g, f, ini, x, choices, outbox) {
     const d = x.data || {};
     const r = require('./initiative-writer.js').setOutcome(p.w.root, ini, { metric: d.metric, horizon: d.horizon }, { actor: g.actor });
     if (r.ok && !r.same) add({ op: 'outcome', from: r.from, to: { metric: r.metric, horizon: r.horizon } });
+  } else if (x.group === 'description') {
+    // the record's own description (initiative-description-field): ✓ writes its description line, Undo puts back what was there
+    const r = require('./initiative-writer.js').setDescription(p.w.root, ini, (x.data || {}).text, { actor: g.actor });
+    if (r.ok && !r.same) add({ op: 'description', from: r.from, to: r.text });
   } else if (x.group === 'grill') {
     // a grill finding (lib/grill.js): ✓ adds its next step as a task, with the finding and its sources in the notes
     // ✎ on the finding: the PM's own words for the next step (choices[id]) replace Claude's
@@ -301,6 +305,7 @@ const WRITES = {
       else if (w.op === 'prd') { try { const file = path.resolve(p.w.root, w.file), text = fs.readFileSync(file, 'utf8'); if (text.includes(w.to)) { fs.writeFileSync(file, text.split(w.to).join(w.from)); back++; } else kept++; } catch { kept++; } continue; }
       else if (w.op === 'doc' || w.op === 'linked' || w.op === 'ran') { back++; continue; }   // the fold leaves an undone batch out
       else if (w.op === 'outbox') { kept++; continue; }   // a drafted comment waits in the outbox, where the PM drops it
+      else if (w.op === 'description') { const r2 = require('./initiative-writer.js').restoreDescription(p.w.root, k.ini, w.from || '', w.to || '', { actor: g.actor }); if (r2.ok && !r2.kept) back++; else kept++; continue; }   // a record edited since keeps its edit
       else if (w.op === 'outcome') { const r2 = require('./initiative-writer.js').restoreOutcome(p.w.root, k.ini, w.from || {}, w.to || {}, { actor: g.actor }); if (r2.ok && !r2.kept) back++; else kept++; continue; }   // a record edited since keeps its edit
       if (r && r.body && r.body.ok) back++; else kept++;
     }

package/workspace/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pmos-workspace",
-  "version": "0.518.0",
+  "version": "0.520.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pmos-workspace",
-      "version": "0.518.0",
+      "version": "0.520.0",
       "license": "MIT",
       "dependencies": {
         "@anthropic-ai/sdk": "^1.3.0",

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.518.0",
+  "version": "0.520.0",
   "private": true,
   "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",