create-pmos 0.39.0 → 0.40.0

package/workspace/lib/doc-profiles.js

@@ -0,0 +1,74 @@
+'use strict';
+/* doc-profiles.js — what KIND of document is this, and what must it agree with? (claims-ledger C1)
+ *
+ * A checker that treats every file the same compares things that have nothing to say about each other. So a file
+ * is classified FIRST, and the class decides what it is checked against. Order of evidence, strongest first:
+ *   1. its frontmatter `type`;
+ *   2. an initiative record that names it (prd_path, rubric_path, explainer_path, brief_path, doc_path);
+ *   3. its filename convention (<id>-prd.md, <id>-eval-rubric.md, <id>-user-stories.md, dNN-*.md …);
+ *   4. a heading signature, only for the two kinds with a distinctive one (PRD, rubric).
+ * A markdown file that matches none is UNCLASSIFIED. It still gets internal checks (its own links, its own
+ * `stale_after`) and is NEVER compared with another file. "Not classified" is an honest answer; guessing is not.
+ *
+ * `REFERENCES` states, per type, which roles the type is compared with. The extraction and the checks live in
+ * lib/claims.js and read this table, so what a type "must agree with" is written down once.
+ */
+const path = require('path');
+
+const IN_SCOPE_EXT = new Set(['md', 'json', 'yaml', 'yml', 'toml']);
+
+/* Types that have a cross-reference set. Any other `type` value is classified (it has a name) but is checked
+ * internally only. */
+const REFERENCES = {
+  Initiative: ['PRD', 'Rubric', 'Reference (explainer)', 'brief or document'],
+  PRD: ['Initiative', 'Rubric', 'decisions it cites'],
+  Rubric: ['PRD', 'Initiative'],
+  Story: ['PRD'],
+  ADR: ['the decisions file'],
+};
+
+const extOf = (rel) => { const b = path.posix.basename(rel).toLowerCase(); const i = b.lastIndexOf('.'); return i > 0 ? b.slice(i + 1) : ''; };
+
+/** Which role does an initiative record give a path? `refs` maps path → [{role, id}]. */
+const ROLE_TYPE = { prd_path: 'PRD', rubric_path: 'Rubric', explainer_path: 'Reference', brief_path: 'Reference', doc_path: 'Reference' };
+
+const NAME_RULES = [
+  [/-eval-rubric\.md$/i, 'Rubric'],
+  [/-prd\.md$/i, 'PRD'],
+  [/-user-stories\.md$/i, 'Story'],
+  [/-surface-explainer\.md$/i, 'Reference'],
+  [/(^|\/)d\d{1,3}-[^/]+\.md$/i, 'ADR'],
+];
+
+function headings(text) {
+  const out = [];
+  for (const m of String(text).matchAll(/^#{1,6}\s+(.+?)\s*$/gm)) out.push(m[1].toLowerCase());
+  return out;
+}
+
+/**
+ * Classify one file.
+ * @param {object} a
+ * @param {string} a.rel        repo-relative path with forward slashes
+ * @param {object} a.fm         parsed frontmatter ({} when none)
+ * @param {string} a.text       file text
+ * @param {Map}    [a.named]    path → [{role, id}] from initiative records
+ * @returns {{type:string|null, via:string, classified:boolean}}
+ */
+function classify({ rel, fm = {}, text = '', named = new Map() }) {
+  const ext = extOf(rel);
+  if (ext !== 'md') return { type: 'Config', via: 'extension', classified: true };
+  // A template is a scaffold with placeholders, not a document that can agree or disagree with anything.
+  if (/(^|\/)templates?\//i.test(rel) || /-template\.md$/i.test(rel)) return { type: 'Template', via: 'path', classified: true };
+  if (fm.type) return { type: String(fm.type), via: 'frontmatter type', classified: true };
+  const roles = named.get(rel);
+  if (roles && roles.length) return { type: ROLE_TYPE[roles[0].role] || 'Reference', via: 'named by initiative ' + roles[0].id, classified: true };
+  for (const [re, type] of NAME_RULES) if (re.test(rel)) return { type, via: 'file name', classified: true };
+  const h = headings(text);
+  const has = (s) => h.some((x) => x.includes(s));
+  if (has('requirements') && has('identity')) return { type: 'PRD', via: 'headings', classified: true };
+  if (has('dimensions') && has('sprint contract')) return { type: 'Rubric', via: 'headings', classified: true };
+  return { type: null, via: 'no evidence', classified: false };
+}
+
+module.exports = { classify, extOf, headings, IN_SCOPE_EXT, REFERENCES, ROLE_TYPE };

package/workspace/lib/initiative-files.js

@@ -12,7 +12,8 @@
 const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
-const { previewKind } = require('./preview-kind');
+const PK = require('./preview-kind');
+const { previewKind } = PK;
 
 const MAX_FILES = 200;
 const cache = new Map();   // root|id → {head, at, result}
@@ -123,12 +124,19 @@ function readAtRef(root, ref, rel) {
   const p = String(rel || '');
   if (!p || p.startsWith('/') || p.split('/').some((seg) => seg === '..' || seg === '')) return { ok: false, reason: 'not a path inside the repository' };
   const kind = previewKind(p);
-  if (kind !== 'markdown' && kind !== 'text' && kind !== 'html') return { ok: false, reason: 'this kind of file cannot be previewed from a branch' };
+  // A type that is binary by nature, or opened another way (image, PDF, workbook), is refused with its reason; any
+  // other file is tried as text, like a read from the working tree (file-viewer-any-text).
+  if (kind === 'image' || kind === 'pdf' || kind === 'sheet') return { ok: false, reason: 'this kind of file is opened another way, not as text' };
+  const known = kind === 'markdown' || kind === 'text' || kind === 'html';
+  if (!known && PK.isKnownBinary(p)) return { ok: false, reason: 'this is a binary file (.' + PK.extOf(p) + ') and cannot be shown as text' };
   const r = spawnSync('git', ['-C', root, 'show', ref + ':' + p], { encoding: 'buffer', maxBuffer: MAX_BYTES + 1024, timeout: 20000 });
   if (r.error || r.status !== 0) return { ok: false, reason: 'git has no such file on ' + ref };
   if (r.stdout.length > MAX_BYTES) return { ok: false, reason: 'the file is larger than 2 MB' };
   if (r.stdout.indexOf(0) !== -1) return { ok: false, reason: 'the file is binary' };
-  return { ok: true, kind, text: r.stdout.toString('utf8') };
+  let text;
+  try { text = new TextDecoder('utf-8', { fatal: true }).decode(r.stdout); }
+  catch { if (!known) return { ok: false, reason: 'the file is not valid UTF-8 text' }; text = r.stdout.toString('utf8'); }
+  return { ok: true, kind: known ? kind : 'text', text };
 }
 
 module.exports = { filesFor, groupOf, namesId, readAtRef };

package/workspace/lib/preview-kind.js

@@ -24,7 +24,7 @@
   // Textual formats shown as ESCAPED source (never executed, R2). Broad on purpose — every entry
   // is escaped text, so breadth adds no risk (PRD open-question resolved: broad allowlist).
   const TEXT_EXT = new Set([
-    'txt', 'text', 'log', 'csv', 'tsv', 'json', 'jsonc', 'json5', 'ndjson',
+    'txt', 'text', 'log', 'csv', 'tsv', 'json', 'jsonc', 'json5', 'ndjson', 'jsonl', 'jsonlines', 'ldjson',
     'yaml', 'yml', 'toml', 'ini', 'cfg', 'conf', 'config', 'properties', 'env', 'example',
     'xml', 'rss', 'atom', // NB: .svg is classified 'image' (IMAGE_MIME, checked first) — it renders, not source
     'sh', 'bash', 'zsh', 'fish', 'ps1', 'bat',
@@ -45,6 +45,18 @@
     ico: 'image/x-icon', apng: 'image/apng',
   };
 
+  // File types that are binary by nature. The reader refuses these as binary WITHOUT reading them, so a
+  // type that is not on any list can still be tried as text (file-viewer-any-text) while these never are.
+  // An unlisted extension that turns out to be binary is still caught by the NUL and UTF-8 checks.
+  const BINARY_EXT = new Set([
+    'doc', 'docx', 'dot', 'dotx', 'ppt', 'pptx', 'potx', 'xls', 'xlsm', 'xltx', 'odt', 'ods', 'odp', 'pages', 'numbers', 'key',
+    'zip', 'gz', 'tgz', 'bz2', 'xz', 'zst', 'tar', '7z', 'rar', 'jar', 'war', 'apk', 'iso', 'dmg', 'pkg', 'deb', 'rpm',
+    'exe', 'dll', 'so', 'dylib', 'bin', 'o', 'a', 'class', 'pyc', 'wasm', 'node',
+    'woff', 'woff2', 'ttf', 'otf', 'eot',
+    'mp3', 'mp4', 'm4a', 'mov', 'wav', 'avi', 'mkv', 'webm', 'ogg', 'flac', 'aac',
+    'sqlite', 'sqlite3', 'db', 'mdb', 'psd', 'ai', 'heic', 'tif', 'tiff', 'raw',
+  ]);
+
   // Extension-less files that are really text (open as source).
   const TEXT_BASENAMES = new Set(['dockerfile', 'makefile', 'license', 'licence', 'authors',
     'notice', 'copying', 'changelog', 'procfile', 'brewfile', 'gemfile', 'rakefile', 'vagrantfile']);
@@ -77,6 +89,9 @@
     return 'inert';
   }
 
+  /** true when the extension names a type that is binary by nature (see BINARY_EXT). */
+  function isKnownBinary(name) { return BINARY_EXT.has(extOf(name)); }
+
   /** image MIME for /api/asset, or null when the extension is not an allowlisted image. */
   function imageMime(name) {
     return IMAGE_MIME[extOf(name)] || null;
@@ -105,5 +120,5 @@
   }
 
   return { previewKind, imageMime, assetMime, isTextSource, isRepoRelativeSrc, extOf,
-    MARKDOWN_EXT, TEXT_EXT, HTML_EXT, IMAGE_MIME };
+    isKnownBinary, MARKDOWN_EXT, TEXT_EXT, HTML_EXT, BINARY_EXT, IMAGE_MIME };
 });

package/workspace/lib/proactive-cli.js

@@ -0,0 +1,137 @@
+'use strict';
+/* proactive-cli.js — `pmos proactive …`: the terminal face of Today.
+ *
+ * A thin client of the running workspace server's own routes, like schedule-cli.js: one computation, one
+ * feedback ledger, one settings file. Nothing here writes a file itself, and nothing here starts a session,
+ * sends anything or changes an initiative. With no server running the command says so and exits 1.
+ *
+ *   pmos proactive today
+ *   pmos proactive scan
+ *   pmos proactive settings [--enabled on|off] [--trigger NAME=on|off] [--stalled-days N] [--quiet HH:MM-HH:MM|none] [--pause-learning on|off]
+ *   pmos proactive feedback <id> useful|not-useful|wrong-priority|opened|dismissed [--note TEXT]
+ *   pmos proactive feedback --missed TEXT
+ *   pmos proactive brief [show]
+ *   pmos proactive brief submit --file PATH
+ *   pmos proactive brief schedule [--repo PATH]
+ */
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { parseArgs } = require('./schedule-cli');
+
+const COMMANDS = { proactive: ['today', 'scan', 'settings', 'feedback', 'brief'] };
+const BRIEF_SOURCES = ['calendar', 'wispr', 'mail', 'jira', 'confluence'];
+const onOff = (v, what) => (v === 'on' || v === 'true' ? true : v === 'off' || v === 'false' ? false : { err: `${what} takes on or off` });
+
+async function run(argv, { call, say, cwd = process.cwd() }) {
+  const [group, verb, ...rest] = argv;
+  const { pos, flags } = parseArgs(rest);
+  const fail = (m) => { say('✗ ' + m); return 1; };
+  if (group !== 'proactive' || !verb || flags.help || verb === 'help') { say(`usage: pmos proactive <${COMMANDS.proactive.join('|')}> …`); return verb ? 0 : 1; }
+  if (!COMMANDS.proactive.includes(verb)) return fail(`unknown command "${verb}" — use ${COMMANDS.proactive.join(', ')}`);
+  const probe = await call('GET', '/api/proactive/settings');
+  if (!probe) return fail('the workspace server is not running — start it with: pmos');
+
+  if (verb === 'today') {
+    const t = await call('GET', '/api/proactive/today');
+    if (!t || t.ok === false) return fail((t && t.error) || 'the server did not answer');
+    if (t.off) say('The engine is off. Nothing is scanned automatically.');
+    if (t.quiet) say('Quiet hours: no automatic scans now.');
+    for (const u of t.unreadable || []) say(`not read — ${u.name || u.repo}: ${u.error}`);
+    if (t.empty) say('Nothing is waiting on any repository that was read.');
+    for (const c of t.candidates || []) {
+      say(`${c.id}  ${c.kind}  ${c.owner === 'pm' ? 'yours' : "the agent's"}  ${c.title}`);
+      say(`    ${c.why}${c.evidence ? ' — ' + c.evidence : ''}`);
+    }
+    if (t.dismissed) say(`${t.dismissed} dismissed item(s) hidden for 7 days.`);
+    say(t.note);
+    return 0;
+  }
+  if (verb === 'scan') {
+    const r = await call('POST', '/api/proactive/scan', {});
+    if (!r || r.ok === false) return fail((r && r.error) || 'the scan failed');
+    say(`scanned — ${r.found} waiting, ${r.appended} new${(r.unreadable || []).length ? ', ' + r.unreadable.length + ' repository not read' : ''}`);
+    return 0;
+  }
+  if (verb === 'settings') {
+    const patch = {};
+    if ('enabled' in flags) { const v = onOff(flags.enabled, '--enabled'); if (v.err) return fail(v.err); patch.enabled = v; }
+    if ('pause-learning' in flags) { const v = onOff(flags['pause-learning'], '--pause-learning'); if (v.err) return fail(v.err); patch.pauseLearning = v; }
+    if ('trigger' in flags) {
+      const m = /^([a-z]+)=(on|off)$/.exec(flags.trigger);
+      if (!m) return fail('--trigger takes NAME=on or NAME=off, for example needs=off');
+      patch.triggers = { [m[1]]: m[2] === 'on' };
+    }
+    if ('name' in flags) patch.name = flags.name;
+    if ('brief-scoring' in flags) { const v = onOff(flags['brief-scoring'], '--brief-scoring'); if (v.err) return fail(v.err); patch.briefScoring = v; }
+    if ('brief-source' in flags) {
+      const m = /^([a-z]+)=(on|off)$/.exec(flags['brief-source']);
+      if (!m) return fail(`--brief-source takes NAME=on or NAME=off, where NAME is one of ${BRIEF_SOURCES.join(', ')}`);
+      patch.briefSources = { [m[1]]: m[2] === 'on' };
+    }
+    if ('stalled-days' in flags) patch.stalledDays = Number(flags['stalled-days']);
+    if ('quiet' in flags) {
+      if (flags.quiet === 'none') patch.quiet = null;
+      else { const m = /^(\d\d:\d\d)-(\d\d:\d\d)$/.exec(flags.quiet); if (!m) return fail('--quiet takes HH:MM-HH:MM, or none'); patch.quiet = { start: m[1], end: m[2] }; }
+    }
+    let s = probe.settings;
+    if (Object.keys(patch).length) {
+      const r = await call('POST', '/api/proactive/settings', patch);
+      if (!r || r.ok === false) return fail(`refused — ${(r && r.error) || 'the server did not answer'}. Nothing was changed.`);
+      s = r.settings;
+    }
+    say(`engine ${s.enabled ? 'on' : 'off'} · stalled after ${s.stalledDays} days · quiet ${s.quiet ? s.quiet.start + '-' + s.quiet.end : 'none'} · learning ${s.pauseLearning ? 'paused' : 'on'}`);
+    say('brief sources: ' + BRIEF_SOURCES.map((k) => `${k} ${s.briefSources && s.briefSources[k] ? 'on' : 'off'}`).join(', ') + ' · scoring ' + (s.briefScoring ? 'on' : 'off') + (s.name ? ' · name ' + s.name : ''));
+    say('watching: ' + Object.entries(s.triggers).map(([k, v]) => `${k} ${v ? 'on' : 'off'}`).join(', '));
+    return 0;
+  }
+  if (verb === 'brief') {
+    const sub = pos[0] || 'show';
+    if (sub === 'submit') {
+      if (!flags.file) return fail('usage: pmos proactive brief submit --file PATH');
+      let raw; try { raw = JSON.parse(fs.readFileSync(path.resolve(cwd, flags.file), 'utf8')); } catch (e) { return fail(`could not read ${flags.file} as JSON — ${e.message}`); }
+      const r = await call('POST', '/api/proactive/brief', raw);
+      if (!r || r.ok === false) return fail(`refused — ${(r && r.error) || 'the server did not answer'}. Nothing was stored.`);
+      say(`stored the brief for ${r.brief.date} — ${r.brief.priorities.length} priorities, ${r.brief.worth_asking.length} worth asking`);
+      return 0;
+    }
+    if (sub === 'schedule') {
+      let root; try { root = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: flags.repo ? path.resolve(cwd, flags.repo) : cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return fail('this is not inside a git repository — use --repo PATH'); }
+      const wl = await call('GET', '/api/workspaces');
+      const hit = ((wl && wl.workspaces) || []).find((w) => path.resolve(w.root) === path.resolve(root));
+      if (!hit) return fail(`${root} is not a registered workspace — open it with pmos first`);
+      const r = await call('POST', '/api/schedules/seed', { ws: hit.id, set: 'brief' });
+      if (!r || r.ok === false) return fail(`refused — ${(r && r.error) || 'the server did not answer'}`);
+      if (r.created.length) say(`scheduled: ${r.created[0].name} (${r.created[0].cadence} ${r.created[0].time}) — it runs only while the workspace server runs`);
+      else say(`nothing to add — ${r.kept.map((k) => k.skill + ': ' + k.why).join('; ')}`);
+      return 0;
+    }
+    if (sub !== 'show') return fail('usage: pmos proactive brief [show|submit --file PATH|schedule]');
+    const r = await call('GET', '/api/proactive/brief');
+    if (!r || r.ok === false) return fail((r && r.error) || 'the server did not answer');
+    say(r.greeting);
+    if (!r.brief) { say('No brief yet. Schedule one with: pmos proactive brief schedule'); return 0; }
+    if (r.stale) say(`This brief is for ${r.brief.date}, not today (${r.today}). It is out of date.`);
+    say('sources: ' + Object.entries(r.brief.sources).map(([k, v]) => `${k} ${v}`).join(', '));
+    for (const e of r.brief.calendar) say(`${e.start}  ${e.title}${e.with ? ' — ' + e.with : ''}`);
+    for (const x of r.brief.priorities) say(`${x.id}  priority  ${x.owner === 'pm' ? 'yours' : "the agent's"}  ${x.title}  (${x.confidence})\n    ${x.why_now}`);
+    for (const x of r.brief.worth_asking) say(`${x.id}  worth asking  ${x.title}  (${x.confidence})\n    ${x.why_now}`);
+    return 0;
+  }
+  // feedback
+  const body = {};
+  if (flags.note) body.note = flags.note;
+  if (flags.missed) { body.verdict = 'missed'; body.note = flags.missed; }
+  else {
+    const [id, what] = pos;
+    if (!id || !what) return fail('usage: pmos proactive feedback <id> useful|not-useful|wrong-priority|opened|dismissed [--note TEXT]   or   --missed TEXT');
+    body.candidate_id = id;
+    if (['opened', 'dismissed', 'acted', 'ignored'].includes(what)) body.event = what; else body.verdict = what;
+  }
+  const r = await call('POST', '/api/proactive/feedback', body);
+  if (!r || r.ok === false) return fail(`refused — ${(r && r.error) || 'the server did not answer'}. Nothing was recorded.`);
+  say('recorded');
+  return 0;
+}
+
+module.exports = { run, COMMANDS };

package/workspace/lib/proactive.js

@@ -0,0 +1,208 @@
+'use strict';
+/* proactive.js — the proactive engine's pure core (initiative `proactive-engine`, slice D1).
+ *
+ * The workspace used to wait to be asked. This module notices what needs the PM, from facts the repositories already
+ * hold, ranks it, and validates the feedback the PM gives about it. It is pure: no I/O, no clock, no model, no network.
+ * The server gathers the facts (ledgers and git) and persists the records; this decides.
+ *
+ *   detect(ctx)              the candidates that are true NOW — a condition that has ended is simply not returned
+ *   rank(cands)              the fixed, stated order
+ *   newSignals(...)          which candidates have not been appended to signals.jsonl inside the dedupe window
+ *   dismissedIds(...)        which candidates the PM dismissed within the last seven days
+ *   validateFeedback(body)   the four verdicts, the implicit events, an optional one-line note
+ *   normalizeSettings(raw)   off, per-trigger off, quiet hours, the stall threshold, pause learning
+ *   inQuietHours(now, quiet) whether automatic scans are held
+ *
+ * A candidate is never a status. Nothing here changes an initiative, a lifecycle line or an acceptance.
+ */
+const crypto = require('crypto');
+
+const TRIGGERS = ['needs', 'returned', 'review', 'schedule', 'stalled'];
+const VERDICTS = ['useful', 'not-useful', 'wrong-priority', 'missed'];
+const EVENTS = ['opened', 'acted', 'dismissed', 'ignored'];
+const DAY = 86400000;
+const DEDUPE_MS = DAY;
+const DISMISS_MS = 7 * DAY;
+
+// The fixed ranking, stated to the PM: what blocks on them first, then an unreviewed session, then a failed schedule,
+// then a stalled initiative. Within a kind, older first (age in days, capped at 30).
+const BASE = { needs: 100, returned: 100, review: 80, schedule: 60, stalled: 40 };
+const OWNER = { needs: 'pm', returned: 'pm', review: 'pm', schedule: 'pm', stalled: 'agent' };
+
+const BRIEF_SOURCES = ['calendar', 'wispr', 'mail', 'jira', 'confluence'];
+// Mail is off by default: a brief reads titles and metadata of the other sources, and the PM turns mail on.
+const BRIEF_DEFAULT = Object.freeze({ calendar: true, wispr: true, mail: false, jira: true, confluence: true });
+const DEFAULTS = Object.freeze({ name: '', briefSources: BRIEF_DEFAULT, briefScoring: false, enabled: true, triggers: Object.freeze(Object.fromEntries(TRIGGERS.map((t) => [t, true]))), stalledDays: 5, quiet: null, pauseLearning: false });
+
+const idOf = (key) => crypto.createHash('sha1').update(String(key)).digest('hex').slice(0, 12);
+const clip = (s, n) => String(s == null ? '' : s).replace(/\s+/g, ' ').trim().slice(0, n);
+const days = (ms) => Math.floor(ms / DAY);
+
+function cand(kind, key, p) {
+  return { id: idOf(key), key, kind, owner: OWNER[kind], initiative_id: p.initiative_id || null, ws: p.ws || null, repo: p.repo || null,
+    title: clip(p.title, 120), why: clip(p.why, 200), evidence: clip(p.evidence, 240), confidence: p.confidence, since: p.since == null ? null : p.since,
+    open: p.open || null };
+}
+
+/**
+ * @param {{now:number, settings:object, repos:Array, nextStepRuns:Array}} ctx
+ *   repos[]: {name, ws, error?, initiatives:[{id,title,active,lastRun,hasRuns}], needs:[{initiative_id,question,run_id}],
+ *            returned:[{initiative_id,note,at}], schedules:[{id,name,lastStatus,lastRun}]}
+ *   nextStepRuns[]: {session_id, initiative_id, ws, key, ended, reviewed, at}
+ * @returns {{candidates:Array, unreadable:Array<{repo:string,error:string}>}}
+ */
+function detect(ctx) {
+  const now = ctx.now; const st = ctx.settings || DEFAULTS; const on = (t) => st.triggers ? st.triggers[t] !== false : true;
+  const out = []; const unreadable = [];
+  for (const r of ctx.repos || []) {
+    if (r.error) { unreadable.push({ repo: r.name, error: clip(r.error, 200) }); continue; }
+    const byId = new Map((r.initiatives || []).map((i) => [i.id, i]));
+    if (on('needs')) {
+      for (const n of r.needs || []) {
+        const ini = byId.get(n.initiative_id);
+        out.push(cand('needs', `needs:${r.ws}:${n.run_id || n.initiative_id + ':' + clip(n.question, 60)}`, {
+          initiative_id: n.initiative_id, ws: r.ws, repo: r.name, title: ini ? ini.title || ini.id : (n.initiative_id || 'an open item'),
+          why: 'An open item is waiting on you.', evidence: n.question, confidence: 0.95, since: null,
+          open: n.initiative_id ? { type: 'initiative', initiative_id: n.initiative_id, ws: r.ws } : null }));
+      }
+    }
+    if (on('returned')) {
+      for (const x of r.returned || []) {
+        const ini = byId.get(x.initiative_id);
+        if (ini && !ini.active) continue;
+        out.push(cand('returned', `returned:${r.ws}:${x.initiative_id}:${x.at || ''}`, {
+          initiative_id: x.initiative_id, ws: r.ws, repo: r.name, title: ini ? ini.title || ini.id : x.initiative_id,
+          why: 'You returned this at the Acceptance Gate and it has not been accepted since.', evidence: x.note || 'returned', confidence: 0.95, since: x.at ? Date.parse(x.at) || null : null,
+          open: { type: 'initiative', initiative_id: x.initiative_id, ws: r.ws } }));
+      }
+    }
+    if (on('schedule')) {
+      for (const s of r.schedules || []) {
+        if (s.lastStatus !== 'fail') continue;
+        out.push(cand('schedule', `schedule:${s.id}:${s.lastRun || ''}`, {
+          ws: r.ws, repo: r.name, title: s.name || s.id, why: 'A scheduled task failed on its last run.',
+          evidence: `${s.name || s.id} — last run ${s.lastRun ? new Date(s.lastRun).toISOString().slice(0, 16).replace('T', ' ') : 'unknown'} reported fail`,
+          confidence: 0.9, since: s.lastRun ? Date.parse(s.lastRun) || null : null, open: { type: 'schedule', id: s.id, ws: r.ws } }));
+      }
+    }
+    if (on('stalled')) {
+      const limit = (st.stalledDays || DEFAULTS.stalledDays) * DAY;
+      for (const i of r.initiatives || []) {
+        if (!i.active || !i.hasRuns || i.lastRun == null) continue;
+        const idle = now - i.lastRun;
+        if (idle < limit) continue;
+        const d = days(idle);
+        out.push(cand('stalled', `stalled:${r.ws}:${i.id}`, {
+          initiative_id: i.id, ws: r.ws, repo: r.name, title: i.title || i.id,
+          why: `In progress, with no agent run for ${d} days.`, evidence: `last run ${new Date(i.lastRun).toISOString().slice(0, 10)}; the threshold is ${st.stalledDays || DEFAULTS.stalledDays} days`,
+          confidence: Math.min(0.85, +(0.5 + 0.05 * (d - (st.stalledDays || DEFAULTS.stalledDays))).toFixed(2)), since: i.lastRun,
+          open: { type: 'initiative', initiative_id: i.id, ws: r.ws } }));
+      }
+    }
+  }
+  if (on('review')) {
+    for (const x of ctx.nextStepRuns || []) {
+      if (!x.ended || x.reviewed) continue;
+      out.push(cand('review', `review:${x.session_id}`, {
+        initiative_id: x.initiative_id, ws: x.ws, repo: null, title: `${x.key || 'a step'} · ${x.initiative_id}`,
+        why: 'A session started from a next step has ended and has no verdict from you.', evidence: `session ${x.session_id}`, confidence: 0.9, since: x.at ? Date.parse(x.at) || null : null,
+        open: { type: 'review', initiative_id: x.initiative_id, ws: x.ws, session_id: x.session_id } }));
+    }
+  }
+  return { candidates: out, unreadable };
+}
+
+function rank(cands, now) {
+  const score = (c) => BASE[c.kind] + (c.since != null && now != null ? Math.min(30, Math.max(0, days(now - c.since))) : 0);
+  return cands.map((c) => ({ ...c, rank: score(c) })).sort((a, b) => b.rank - a.rank || (a.id < b.id ? -1 : 1))
+    .map((c, i) => ({ ...c, n: i + 1 }));
+}
+
+/** Candidates whose key was not already appended within the dedupe window. `recent` = signals.jsonl rows `{key, at}`. */
+function newSignals(cands, recent, now) {
+  const seen = new Set();
+  for (const r of recent || []) { const t = Date.parse(r && r.at); if (r && r.key && Number.isFinite(t) && now - t < DEDUPE_MS) seen.add(r.key); }
+  return cands.filter((c) => !seen.has(c.key));
+}
+
+/** The ids the PM dismissed inside the dismissal window. `feedback` = proactive-feedback.jsonl rows. */
+function dismissedIds(feedback, now) {
+  const out = new Set();
+  for (const f of feedback || []) {
+    if (!f || f.event !== 'dismissed' || !f.candidate_id) continue;
+    const t = Date.parse(f.at);
+    if (Number.isFinite(t) && now - t < DISMISS_MS) out.add(f.candidate_id);
+  }
+  return out;
+}
+
+const ID_RE = /^[0-9a-f]{12}$/;
+/** @returns {{ok:true, record:object}|{ok:false, error:string}} — a verdict, or an implicit event, never both. */
+function validateFeedback(body) {
+  const b = body && typeof body === 'object' ? body : {};
+  const note = clip(b.note, 300);
+  const hasVerdict = b.verdict !== undefined && b.verdict !== null && b.verdict !== '';
+  const hasEvent = b.event !== undefined && b.event !== null && b.event !== '';
+  if (hasVerdict === hasEvent) return { ok: false, error: `give a verdict (${VERDICTS.join(', ')}) or an event (${EVENTS.join(', ')}), not both and not neither` };
+  if (hasVerdict) {
+    if (!VERDICTS.includes(b.verdict)) return { ok: false, error: `verdict must be one of ${VERDICTS.join(', ')}` };
+    if (b.verdict === 'missed') {
+      if (!note) return { ok: false, error: 'say what was missed: a "missed" verdict needs a note' };
+      if (b.candidate_id !== undefined && b.candidate_id !== null && b.candidate_id !== '' && !ID_RE.test(String(b.candidate_id))) return { ok: false, error: 'candidate_id is not a candidate id' };
+      return { ok: true, record: { kind: 'verdict', candidate_id: b.candidate_id || null, verdict: 'missed', note } };
+    }
+  } else if (!EVENTS.includes(b.event)) return { ok: false, error: `event must be one of ${EVENTS.join(', ')}` };
+  if (!ID_RE.test(String(b.candidate_id || ''))) return { ok: false, error: 'candidate_id is required and must be a candidate id' };
+  return hasVerdict ? { ok: true, record: { kind: 'verdict', candidate_id: b.candidate_id, verdict: b.verdict, note } }
+    : { ok: true, record: { kind: 'event', candidate_id: b.candidate_id, event: b.event, note } };
+}
+
+const HHMM = /^([01]\d|2[0-3]):([0-5]\d)$/;
+/** @returns {{ok:true, settings:object}|{ok:false, error:string}} — `raw` is merged over the defaults; nothing is partly applied. */
+function normalizeSettings(raw) {
+  const r = raw && typeof raw === 'object' ? raw : {};
+  const s = { name: DEFAULTS.name, briefSources: { ...BRIEF_DEFAULT }, briefScoring: DEFAULTS.briefScoring, enabled: DEFAULTS.enabled, triggers: { ...DEFAULTS.triggers }, stalledDays: DEFAULTS.stalledDays, quiet: DEFAULTS.quiet, pauseLearning: DEFAULTS.pauseLearning };
+  if (r.enabled !== undefined) { if (typeof r.enabled !== 'boolean') return { ok: false, error: 'enabled must be true or false' }; s.enabled = r.enabled; }
+  if (r.name !== undefined) { if (typeof r.name !== 'string' || r.name.length > 40) return { ok: false, error: 'name must be text of at most 40 characters' }; s.name = r.name.replace(/\s+/g, ' ').trim(); }
+  if (r.briefScoring !== undefined) { if (typeof r.briefScoring !== 'boolean') return { ok: false, error: 'briefScoring must be true or false' }; s.briefScoring = r.briefScoring; }
+  if (r.briefSources !== undefined) {
+    if (!r.briefSources || typeof r.briefSources !== 'object' || Array.isArray(r.briefSources)) return { ok: false, error: `briefSources must be an object of ${BRIEF_SOURCES.join(', ')} → true or false` };
+    for (const [k, v] of Object.entries(r.briefSources)) {
+      if (!BRIEF_SOURCES.includes(k)) return { ok: false, error: `unknown brief source "${k}" — one of ${BRIEF_SOURCES.join(', ')}` };
+      if (typeof v !== 'boolean') return { ok: false, error: `brief source "${k}" must be true or false` };
+      s.briefSources[k] = v;
+    }
+  }
+  if (r.pauseLearning !== undefined) { if (typeof r.pauseLearning !== 'boolean') return { ok: false, error: 'pauseLearning must be true or false' }; s.pauseLearning = r.pauseLearning; }
+  if (r.triggers !== undefined) {
+    if (!r.triggers || typeof r.triggers !== 'object' || Array.isArray(r.triggers)) return { ok: false, error: `triggers must be an object of ${TRIGGERS.join(', ')} → true or false` };
+    for (const [k, v] of Object.entries(r.triggers)) {
+      if (!TRIGGERS.includes(k)) return { ok: false, error: `unknown trigger "${k}" — one of ${TRIGGERS.join(', ')}` };
+      if (typeof v !== 'boolean') return { ok: false, error: `trigger "${k}" must be true or false` };
+      s.triggers[k] = v;
+    }
+  }
+  if (r.stalledDays !== undefined) {
+    const n = Number(r.stalledDays);
+    if (!Number.isInteger(n) || n < 1 || n > 90) return { ok: false, error: 'stalledDays must be a whole number from 1 to 90' };
+    s.stalledDays = n;
+  }
+  if (r.quiet !== undefined) {
+    if (r.quiet === null) s.quiet = null;
+    else if (!r.quiet || typeof r.quiet !== 'object' || !HHMM.test(String(r.quiet.start)) || !HHMM.test(String(r.quiet.end)) || r.quiet.start === r.quiet.end) {
+      return { ok: false, error: 'quiet must be null, or {start, end} as HH:MM (24-hour, local), different from each other' };
+    } else s.quiet = { start: r.quiet.start, end: r.quiet.end };
+  }
+  return { ok: true, settings: s };
+}
+
+/** Local time of day against a quiet window; a window that wraps midnight (22:00–07:00) is handled. */
+function inQuietHours(nowMs, quiet) {
+  if (!quiet) return false;
+  const d = new Date(nowMs); const m = d.getHours() * 60 + d.getMinutes();
+  const p = (s) => { const [h, mm] = s.split(':').map(Number); return h * 60 + mm; };
+  const a = p(quiet.start); const b = p(quiet.end);
+  return a < b ? m >= a && m < b : m >= a || m < b;
+}
+
+module.exports = { BRIEF_SOURCES, TRIGGERS, VERDICTS, EVENTS, DEFAULTS, DEDUPE_MS, DISMISS_MS, BASE, detect, rank, newSignals, dismissedIds, validateFeedback, normalizeSettings, inQuietHours };

package/workspace/lib/repo-watch.js

@@ -0,0 +1,120 @@
+'use strict';
+/* repo-watch.js — notice that files in a repository changed, and ask for one check (claims-ledger C8).
+ *
+ * WHY A POLL AND NOT fs.watch. A recursive watch needs Node 20 on Linux and can hit the inotify limit on a big tree,
+ * and it still would not see a `git checkout` or a `git pull`. The signature below changes for all of them: an edit in
+ * the editor, a write by an agent in a terminal, a checkout, a pull.
+ *
+ * THE SIGNATURE. `git rev-parse HEAD`, plus the porcelain status, plus the mtime and size of each dirty file — a file
+ * edited twice shows the same status line twice, so the status alone would miss the second edit. A folder that is not
+ * a git checkout uses the mtime and size of its in-scope files.
+ *
+ * DEBOUNCE. An agent writes many files in a burst. A change starts the clock; the check runs once the signature has
+ * stayed the same for `stableMs`. A burst that keeps changing keeps postponing, and ends as ONE run.
+ *
+ * WHAT IT NEVER DOES. It runs async git only, with read-only verbs. It opens no network connection and calls no git
+ * network verb. It never runs a second check for a repository while one is in flight. It checks only repositories
+ * `enabled(root)` says to, and the PM can switch that off per repository.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execFile } = require('child_process');
+
+const sha = (s) => crypto.createHash('sha1').update(s).digest('hex');
+const DIRTY_STAT_CAP = 500;
+
+function git(root, args) {
+  return new Promise((resolve) => {
+    execFile('git', args, { cwd: root, maxBuffer: 32 << 20, timeout: 15000, encoding: 'utf8' }, (err, out) => resolve(err ? null : out));
+  });
+}
+
+/** One string that changes whenever the repository's files change. `null` when the folder cannot be read at all. */
+async function signature(root, listFiles) {
+  const head = await git(root, ['rev-parse', 'HEAD']);
+  const status = head == null ? null : await git(root, ['status', '--porcelain=v1', '-z', '--untracked-files=all']);
+  const parts = [];
+  if (head != null && status != null) {
+    parts.push(head.trim(), sha(status));
+    const dirty = status.split('\0').filter((e) => e.length > 3).map((e) => e.slice(3)).slice(0, DIRTY_STAT_CAP);
+    for (const rel of dirty) {
+      try { const st = fs.statSync(path.join(root, rel)); parts.push(rel + ':' + st.mtimeMs + ':' + st.size); } catch { parts.push(rel + ':gone'); }
+    }
+    return sha(parts.join('\n'));
+  }
+  // not a git checkout: the mtime and size of every in-scope file
+  let files = [];
+  try { files = (await listFiles(root)).files; } catch { return null; }
+  for (const rel of files) {
+    try { const st = fs.statSync(path.join(root, rel)); parts.push(rel + ':' + st.mtimeMs + ':' + st.size); } catch { parts.push(rel + ':gone'); }
+  }
+  return sha(parts.join('\n'));
+}
+
+/**
+ * @param {object} o
+ * @param {function} o.repos            () => [{ id, root }]  the repositories that exist
+ * @param {function} o.enabled          (root) => boolean     whether to watch this one
+ * @param {function} o.check            async ({ root, sweep }) => result   one check
+ * @param {function} [o.signature]      async (root) => string|null
+ * @param {function} [o.onResult]       ({ id, root, ok, result|error, sweep })
+ * @param {function} [o.now]            () => ms
+ * @param {number}   [o.pollMs]         how often the timer ticks
+ * @param {number}   [o.stableMs]       how long the signature must hold still before a check
+ * @param {number}   [o.sweepEveryMs]   how often the periodic time-rule pass runs
+ */
+function createWatcher(o) {
+  const now = o.now || Date.now;
+  const pollMs = o.pollMs || 10000;
+  const stableMs = o.stableMs == null ? 8000 : o.stableMs;
+  const sweepEveryMs = o.sweepEveryMs || 6 * 3600 * 1000;
+  const sigOf = o.signature || ((root) => signature(root, o.listFiles || (async () => ({ files: [] }))));
+  const state = new Map();                       // root → { sig, changedAt, pending, running, lastSweep, checked }
+  let timer = null;
+  let ticking = false;
+
+  async function run(id, root, st, sweep) {
+    st.running = true;
+    try {
+      const result = await o.check({ root, sweep });
+      if (o.onResult) o.onResult({ id, root, ok: !!(result && result.ok !== false), result, sweep });
+    } catch (e) {
+      if (o.onResult) o.onResult({ id, root, ok: false, error: String((e && e.message) || e).slice(0, 200), sweep });
+    } finally { st.running = false; st.checked = true; if (sweep) st.lastSweep = now(); }
+  }
+
+  /** One pass over every repository. Exposed so a test can drive it with a fake clock. */
+  async function tick() {
+    if (ticking) return;
+    ticking = true;
+    try {
+      const live = new Set();
+      for (const r of o.repos()) {
+        if (!o.enabled(r.root)) { state.delete(r.root); continue; }
+        live.add(r.root);
+        let st = state.get(r.root);
+        if (!st) { st = { sig: null, changedAt: null, pending: false, running: false, lastSweep: now(), checked: false }; state.set(r.root, st); }
+        if (st.running) continue;                                    // never two checks at once for one repository
+        const sig = await sigOf(r.root);
+        if (sig == null) continue;
+        if (!st.checked && !st.pending && st.sig == null) { st.sig = sig; await run(r.id, r.root, st, false); continue; }   // first look: one check
+        if (sig !== st.sig) { st.sig = sig; st.changedAt = now(); st.pending = true; continue; }
+        if (st.pending && now() - st.changedAt >= stableMs) { st.pending = false; await run(r.id, r.root, st, false); continue; }
+        if (!st.pending && now() - st.lastSweep >= sweepEveryMs) await run(r.id, r.root, st, true);
+      }
+      for (const root of Array.from(state.keys())) if (!live.has(root)) state.delete(root);
+    } finally { ticking = false; }
+  }
+
+  function start() {
+    if (timer) return stop;
+    timer = setInterval(() => { tick().catch(() => { /* a failed tick is retried on the next one */ }); }, pollMs);
+    if (timer.unref) timer.unref();
+    return stop;
+  }
+  function stop() { if (timer) { clearInterval(timer); timer = null; } }
+  return { tick, start, stop, _state: state };
+}
+
+module.exports = { createWatcher, signature };

package/workspace/lib/typesafe-settings.js

@@ -91,16 +91,19 @@ function getRepo(stateDir, root) {
   return {
     consent: !!(r && r.consent === true),
     exclude: r && Array.isArray(r.exclude) ? r.exclude.filter((x) => typeof x === 'string') : [],
+    // claims-ledger: keep this repository checked as its files change. Default OFF — switching it on makes the
+    // workspace append to the repository's claims.jsonl, so it is the PM's press and never a surprise.
+    watch: !!(r && r.watch === true),
   };
 }
 
-function setRepo(stateDir, root, { consent, exclude }) {
+function setRepo(stateDir, root, { consent, exclude, watch }) {
   const cur = read(stateDir);
   const prev = getRepo(stateDir, root);
   const ex = Array.isArray(exclude)
     ? exclude.map((x) => String(x).trim().replace(/^\/+/, '')).filter((x) => x && !x.includes('..') && x.length <= 200).slice(0, MAX_EXCLUDES)
     : prev.exclude;
-  const repos = { ...cur.repos, [root]: { consent: typeof consent === 'boolean' ? consent : prev.consent, exclude: ex } };
+  const repos = { ...cur.repos, [root]: { consent: typeof consent === 'boolean' ? consent : prev.consent, exclude: ex, watch: typeof watch === 'boolean' ? watch : prev.watch } };
   return write(stateDir, { key: cur.key, repos });
 }