create-pmos 0.52.0 → 0.53.1

package/workspace/lib/grant-mint.js

@@ -0,0 +1,113 @@
+'use strict';
+/* grant-mint.js — a PM press in the workspace mints ONE D81 grant through the repository's own grant writer
+ * (pm-os-absorb, D86 point 2; PRD R25; map-spec X5, X6, X25).
+ *
+ *   PRESS_SCOPES                                                   ['release', 'lifecycle-bulk']
+ *   mintFromPress(root, { scope, target, ids, state, instruction, initiative }, { actor })
+ *     → { ok: true, grant_id, scope, target } | { ok: false, status, error }
+ *   bulkTarget({ target, ids, state })                             → '<state>:<id>,<id>,…' | null
+ *
+ * Two presses mint a grant, and only after pm-guard.js requirePmPress has passed, so `actor` is the guard's actor:
+ *   - Release on a batch of factory items (Run 4, slice 4D: POST /api/board/release). Scope 'release', target
+ *     '<initiative>:<batch-id>'. One grant for each batch.
+ *   - A bulk lifecycle change (Run 2, slice 2A: the bulk body of POST /api/lifecycle). Scope 'lifecycle-bulk', target the
+ *     explicit ids (20 at most) and one state. Each lifecycle line that the press writes cites grant_id (X6).
+ *     The writers spell the target '<state>:<id>,<id>,…'. This file builds that spelling, so a caller cannot get it
+ *     wrong: pass { ids, state } (preferred), or a target in either order ('<state>:<ids>' or '<ids>:<state>'). Any
+ *     other target goes to the writer unchanged, and the writer refuses it with 400.
+ *
+ * The grant is written by the repository's OWN writer, run as a child process with an argv and no shell, resolved the
+ * way the cockpit mod resolves it (kit/mods/pmos-cockpit/hooks/lib/commands.mjs writerOf): PMOS-self runs
+ * `node scripts/record-grant.js grant …`, and a kit install runs `bash pmos/scripts/pmos-log.sh grant …`. The workspace
+ * never requires scripts/ (the engine is vendored, X29) and never writes grants.jsonl itself. So each scope has one
+ * rule, kept in the writers (grants.mjs, record-grant.js, pmos-log.sh) and compared by scripts/tests/record-grant.test.js.
+ *
+ * Refusals that hold before and after the fill: a scope a press cannot mint is 400; an actor that is not the PM is 403
+ * (a grant is the person's permission, D81).
+ *
+ * Filled by Run 2 (slice 2B). The repository is the MAIN working tree of `root` (lib/plan-ledgers.js), so the grant lands
+ * in the same runs directory as the lifecycle lines that cite it. The child gets a minimal environment: no
+ * PMOS_STATE_DIR or KIT_ROOT from this process can point the writer at another folder, and nothing of the server's own
+ * environment reaches it. A refusal by the writer (a target the scope rule does not allow) is 400 with the writer's
+ * reason; a writer that is missing or fails in another way is 500. Nothing is retried, and nothing is written here.
+ */
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const actor = require('./actor.js');
+const planTree = require('./plan-tree.js');
+
+const PRESS_SCOPES = Object.freeze(['release', 'lifecycle-bulk']);
+const TTL_MINUTES = '120';
+const isDir = (p) => { try { return fs.statSync(p).isDirectory(); } catch { return false; } };
+const isFile = (p) => { try { return fs.statSync(p).isFile(); } catch { return false; } };
+
+/**
+ * The grants writer of the repository at `repo`, as commands.mjs writerOf resolves it: PMOS-self (planning/initiatives)
+ * runs scripts/record-grant.js; a kit (pmos/state/initiatives and no planning/initiatives) runs pmos/scripts/pmos-log.sh.
+ * Returns { argv } or null.
+ */
+function writerOf(repo) {
+  const self = isDir(path.join(repo, 'planning', 'initiatives'));
+  const kit = !self && isDir(path.join(repo, 'pmos', 'state', 'initiatives'));
+  if (self && isFile(path.join(repo, 'scripts', 'record-grant.js'))) return { argv: [process.execPath, path.join(repo, 'scripts', 'record-grant.js')] };
+  if (kit && isFile(path.join(repo, 'pmos', 'scripts', 'pmos-log.sh'))) return { argv: ['bash', path.join(repo, 'pmos', 'scripts', 'pmos-log.sh')] };
+  return null;
+}
+
+/** The row a writer printed after it appended: the last line of its output that holds a JSON object. */
+function rowFrom(stdout) {
+  const lines = String(stdout || '').split('\n').filter((l) => l.includes('{'));
+  for (let i = lines.length - 1; i >= 0; i--) {
+    try { const r = JSON.parse(lines[i].slice(lines[i].indexOf('{'))); if (r && r.type === 'grant' && typeof r.id === 'string') return r; } catch { /* the next one */ }
+  }
+  return null;
+}
+
+const BULK_STATES = Object.freeze(['active', 'closed', 'on-hold', 'cancelled']);
+/**
+ * The one spelling of a lifecycle-bulk target: '<state>:<id>,<id>,…'. From { ids, state }, or from a target in either
+ * order. Null when neither gives one state and a list of ids; the writer then judges the target as it was given.
+ */
+function bulkTarget({ target, ids, state } = {}) {
+  if (Array.isArray(ids) && ids.length && typeof state === 'string' && BULK_STATES.includes(state)) return state + ':' + ids.map(String).join(',');
+  if (typeof target !== 'string') return null;
+  const t = target.trim();
+  const head = t.slice(0, t.indexOf(':'));
+  const tail = t.slice(t.lastIndexOf(':') + 1);
+  if (BULK_STATES.includes(head)) return t;
+  if (t.includes(':') && BULK_STATES.includes(tail)) return tail + ':' + t.slice(0, t.lastIndexOf(':'));
+  return null;
+}
+
+function mintFromPress(root, { scope, target, ids, state, instruction, initiative } = {}, { actor: who } = {}) {
+  if (!PRESS_SCOPES.includes(scope)) return { ok: false, status: 400, error: 'a press cannot mint a grant of scope ' + JSON.stringify(scope) };
+  if (!actor.isPm(who)) return { ok: false, status: 403, error: 'only the PM mints a grant' };
+  if (scope === 'lifecycle-bulk') target = bulkTarget({ target, ids, state }) ?? target;
+  if (typeof target !== 'string' || !target.trim()) return { ok: false, status: 400, error: 'a ' + scope + ' grant names its target' };
+  const repo = planTree.mainTree(path.resolve(String(root)));
+  const w = writerOf(repo);
+  if (!w) return { ok: false, status: 500, error: 'this repository has no grants writer (scripts/record-grant.js or pmos/scripts/pmos-log.sh)' };
+  const words = typeof instruction === 'string' && instruction.trim() ? instruction.trim() : 'the PM pressed ' + scope + ' in the workspace';
+  const argv = [...w.argv, 'grant', scope + ':' + target, who.by.slice('pm:'.length), words, TTL_MINUTES];
+  if (typeof initiative === 'string' && initiative) argv.push(initiative);
+  const env = { PATH: process.env.PATH || '/usr/bin:/bin', HOME: process.env.HOME || repo, LANG: 'C.UTF-8' };
+  const r = spawnSync(argv[0], argv.slice(1), { cwd: repo, env, encoding: 'utf8', timeout: 20000, shell: false });
+  if (r.error) return { ok: false, status: 500, error: 'the grants writer did not run: ' + String(r.error.message || r.error).slice(0, 160) };
+  const said = String(r.stderr || '').trim().replace(/^(record-grant|pmos-log): ERROR — /, '').slice(0, 400);
+  if (r.status !== 0) {
+    const refused = /invalid grant|is not a single|unknown scope|has no record|not a plain lowercase slug|must not be empty|ttl_minutes/.test(said);
+    return { ok: false, status: refused ? 400 : 500, error: said || 'the grants writer exited ' + r.status };
+  }
+  const row = rowFrom(r.stdout);
+  if (!row) return { ok: false, status: 500, error: 'the grants writer wrote no row it could name' };
+  return { ok: true, grant_id: row.id, scope: row.scope, target: row.target };
+}
+
+/**
+ * The scopes a press can mint NOW: PRESS_SCOPES, since 2B filled mintFromPress. The page reads it as /api/pm-modules
+ * `grantScopes`, so 2D shows the bulk lifecycle act enabled.
+ */
+function mintableScopes() { return PRESS_SCOPES.slice(); }
+
+module.exports = { PRESS_SCOPES, mintFromPress, mintableScopes, bulkTarget };

package/workspace/lib/health-rules-factory.js

@@ -0,0 +1,92 @@
+'use strict';
+/* health-rules-factory.js — the factory's health rules (pm-os-absorb Run 4, PRD R8). lib/health.js loads this file from
+ * its RULE_FILES slot; each rule answers null (nothing to say) or { level, code, text, source }.
+ *
+ *   factory-failed       OFF TRACK — a factory item failed its check and nobody resolved it. "Resolved" is the fold's
+ *                        word: a later `verified` revokes the failure (D65(d)), and a `withdrawn` ends the item. So an
+ *                        item whose folded state is `failed` is unresolved. UNKNOWN (code factory-unreadable) when the
+ *                        factory ledger exists but cannot be read or folded (the join's `unreadable`, R8): a failure
+ *                        the rule cannot see must not read as on track.
+ *   factory-outside-now  AT RISK — building outside Now: a factory item is claimed (a live claim) while the initiative
+ *                        is in Next or Later, or the trunk holds commits that scripts/delivery-index.js attributes to
+ *                        it while it is in Next or Later and it is not accepted. An initiative with no placement is in
+ *                        Later (lib/placements.js horizonOf).
+ *
+ * What a rule reads (lib/health.js ctx): `factory` = lib/factory-join.js factoryOf(joinFactory(root), id), `placement`
+ * = lib/placements.js byInit[id], `row` = the workflow row (scripts/workflow-state.js). A rule whose input is missing
+ * says nothing: a missing factory join is "no factory work", never a failure. An UNREADABLE join is not missing.
+ *
+ * THE COMMIT SIGNAL is the engine's own. The workflow row's Build step says why it is done; when the reason is
+ * delivery-index's attribution sentence (a merged initiative/<id> branch, or a trunk commit that names the initiative
+ * and changes build files), the commits are attributed. The sentences come from delivery-index.attributionEvidence,
+ * not from a copy here, so a change of wording there cannot silence this rule (factory-join.test.js holds it).
+ *
+ * Pure. No clock, no file reads after the first load of delivery-index.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const SOURCE = 'planning/work-items.jsonl';
+const HORIZON_WORD = { next: 'Next', later: 'Later' };
+const DELIVERY_PATHS = [
+  path.join(__dirname, '..', '..', 'scripts', 'delivery-index.js'),
+  path.join(__dirname, 'engine', 'delivery-index.js'),
+];
+let delivery;
+function attributionSentences(id) {
+  if (delivery === undefined) {
+    delivery = null;
+    for (const p of DELIVERY_PATHS) { if (fs.existsSync(p)) { try { delivery = require(p); } catch { delivery = null; } break; } }
+  }
+  if (!delivery || typeof delivery.attributionEvidence !== 'function') return [];
+  return ['branch', 'mention'].map((s) => delivery.attributionEvidence(s, id));
+}
+
+const horizonOf = (ctx) => (ctx && ctx.placement && ctx.placement.horizon) || 'later';
+const list = (ids) => (ids.length > 3 ? `${ids.slice(0, 3).join(', ')} and ${ids.length - 3} more` : ids.join(', '));
+
+module.exports = [
+  {
+    id: 'factory-failed',
+    check(ctx) {
+      if (ctx && ctx.factory && typeof ctx.factory.unreadable === 'string') {
+        return {
+          level: 'unknown', code: 'factory-unreadable', source: SOURCE,
+          text: `The factory ledger cannot be read, so the state of factory work is not known. ${ctx.factory.unreadable}`,
+        };
+      }
+      const items = (ctx && ctx.factory && Array.isArray(ctx.factory.items)) ? ctx.factory.items : [];
+      const failed = items.filter((it) => it && it.state === 'failed').map((it) => it.id);
+      if (!failed.length) return null;
+      return {
+        level: 'off', code: 'factory-failed', source: SOURCE,
+        text: `${failed.length === 1 ? 'Factory item' : 'Factory items'} ${list(failed)} failed ${failed.length === 1 ? 'its check' : 'their checks'}. Fix or withdraw ${failed.length === 1 ? 'it' : 'them'}.`,
+      };
+    },
+  },
+  {
+    id: 'factory-outside-now',
+    check(ctx) {
+      const horizon = horizonOf(ctx);
+      if (horizon === 'now' || !HORIZON_WORD[horizon]) return null;
+      const where = HORIZON_WORD[horizon];
+      const items = (ctx && ctx.factory && Array.isArray(ctx.factory.items)) ? ctx.factory.items : [];
+      const claimed = items.filter((it) => it && it.state === 'claimed').map((it) => it.id);
+      if (claimed.length) {
+        return {
+          level: 'at-risk', code: 'factory-outside-now', source: SOURCE,
+          text: `Factory work is claimed (${list(claimed)}), but the initiative is in ${where}. Factory work starts only from Now.`,
+        };
+      }
+      const row = ctx && ctx.row;
+      if (!row || row.accepted || !Array.isArray(row.steps)) return null;
+      const build = row.steps.find((s) => s && s.key === 'build');
+      const said = build && build.status === 'done' ? String(build.evidence || '') : '';
+      if (!said || !attributionSentences(ctx.id || row.id).some((s) => said.includes(s))) return null;
+      return {
+        level: 'at-risk', code: 'factory-outside-now', source: 'git (scripts/delivery-index.js)',
+        text: `Commits on the trunk are attributed to this initiative, but it is in ${where}. Building starts only from Now.`,
+      };
+    },
+  },
+];

package/workspace/lib/health-rules-plan.js

@@ -0,0 +1,164 @@
+'use strict';
+/* health-rules-plan.js — the health rules of the plan: items, placements and the ladder (pm-os-absorb, PRD R8, slice 2D).
+ *
+ * lib/health.js loads this file (RULE_FILES) and folds each rule's answer: the worst level wins and on track shows
+ * nothing. Each rule is `{ id, check(ctx) }` and answers null or `{ level, code, text, source }`, where `text` is the
+ * reason a person reads next to the dot. ctx is `{ id, row, fold, placement, measurement, factory, rules, now }`
+ * (seams §5.4). A field a rule needs and ctx does not carry makes that rule say nothing.
+ *
+ *   off track   an overdue milestone; a predecessor from another initiative that was withdrawn
+ *   at risk     a Now initiative idle for stall_days; a PM step owed longer than that; a passed check-by date; an
+ *               overdue item; an item that starts before an open predecessor ends
+ *   unknown     a source could not be read (the workflow row, or lines of plan-items.jsonl)
+ *
+ * Not here: an unresolved failed factory item and building outside Now (Run 4, health-rules-factory.js). A finished
+ * initiative (Accepted, Handed off) has no health: every rule here says nothing for it. A PM step's age is the age of the
+ * initiative's last evidence, because the ladder does not record when a step became owed. A stopped initiative (On hold, Closed,
+ * Cancelled) has none either: it is off the board. A check-by date belongs to Now, so one that a card keeps in Next or Later is
+ * not read.
+ *
+ * Pure: no I/O, no clock beyond ctx.now, no cache.
+ */
+const display = require('./initiative-display.js');
+
+const DAY = 86400000;
+const MON = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+const ITEMS = 'planning/runs/plan-items.jsonl';
+const PLACEMENTS = 'planning/runs/placements.jsonl';
+
+const nowOf = (ctx) => (typeof ctx.now === 'number' ? ctx.now : Date.now());
+const todayOf = (ctx) => new Date(nowOf(ctx)).toISOString().slice(0, 10);
+/** '2026-10-01' -> '1 Oct' (a calendar day, never shifted by the time zone). */
+function shortDate(ymd) {
+  const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(String(ymd || ''));
+  return m ? `${Number(m[3])} ${MON[Number(m[2]) - 1]}` : '';
+}
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+const recordOf = (ctx) => (ctx.row && ctx.row.record) || (ctx.id ? `planning/initiatives/${ctx.id}.md` : 'planning/initiatives');
+
+/** The live items of this initiative in ctx.fold (an object map or a list), proposals and withdrawn items left out. */
+function itemsOf(ctx) {
+  const raw = ctx.fold && ctx.fold.items;
+  const all = Array.isArray(raw) ? raw : raw && typeof raw === 'object' ? Object.values(raw) : [];
+  return all.filter((it) => it && (!ctx.id || !it.initiative || it.initiative === ctx.id) && it.state !== 'withdrawn' && !it.proposed);
+}
+const open = (it) => it.state !== 'done';
+
+const displayCtx = (ctx) => ({ fold: ctx.fold, placement: ctx.placement, rules: ctx.rules, now: nowOf(ctx) });
+/** The state of a stopped initiative (on-hold, closed or cancelled): ctx.lifecycle when the caller passes one, else the workflow row's `stopped`. */
+function stoppedState(ctx) {
+  const s = (ctx.lifecycle && ctx.lifecycle.state) || (ctx.row && ctx.row.stopped && ctx.row.stopped.state);
+  return typeof s === 'string' && s && s !== 'active' ? s : null;
+}
+/** A finished initiative (Accepted, Handed off) and a stopped one (On hold, Closed, Cancelled: off the board, D70) have no health. */
+function finishedWord(ctx) {
+  if (stoppedState(ctx)) return true;
+  if (!ctx.row) return false;
+  const w = display.displayOf(ctx.row, displayCtx(ctx)).word;
+  return w === 'Accepted' || w === 'Handed off';
+}
+const stallDays = (ctx) => (ctx.rules && Number.isInteger(ctx.rules.stall_days) && ctx.rules.stall_days > 0 ? ctx.rules.stall_days : 5);
+
+const RULES = [
+  {
+    id: 'milestone-overdue',
+    check(ctx) {
+      if (!ctx.fold || finishedWord(ctx)) return null;
+      const today = todayOf(ctx);
+      const late = itemsOf(ctx).filter((it) => it.milestone && it.due && it.due < today && open(it)).sort((a, b) => (a.due < b.due ? -1 : 1));
+      if (!late.length) return null;
+      return {
+        level: 'off', code: 'milestone-overdue', source: ITEMS,
+        text: late.length === 1 ? `Milestone "${late[0].title}" was due ${shortDate(late[0].due)}` : `${late.length} milestones are overdue, the first due ${shortDate(late[0].due)}`,
+      };
+    },
+  },
+  {
+    id: 'withdrawn-predecessor',
+    check(ctx) {
+      if (!ctx.fold || !ctx.id || finishedWord(ctx)) return null;
+      const gone = new Set(Array.isArray(ctx.fold.withdrawnIds) ? ctx.fold.withdrawnIds : []);
+      if (!gone.size) return null;
+      const foreign = (id) => { const k = String(id).lastIndexOf('.'); return k > 0 && String(id).slice(0, k) !== ctx.id; };
+      const hit = itemsOf(ctx).find((it) => open(it) && (it.after || []).some((p) => gone.has(p) && foreign(p)));
+      if (!hit) return null;
+      return { level: 'off', code: 'withdrawn-predecessor', source: ITEMS, text: `"${hit.title}" waits on an item of another initiative that was withdrawn` };
+    },
+  },
+  {
+    id: 'idle-in-now',
+    check(ctx) {
+      if (!ctx.row || !ctx.placement || ctx.placement.horizon !== 'now' || finishedWord(ctx)) return null;
+      const label = display.idleLabel(ctx.row, displayCtx(ctx));
+      if (!label) return null;
+      return { level: 'at-risk', code: 'idle', text: label, source: recordOf(ctx) };
+    },
+  },
+  {
+    id: 'pm-step-owed',
+    check(ctx) {
+      if (!ctx.row || finishedWord(ctx)) return null;
+      const d = display.displayOf(ctx.row, displayCtx(ctx));
+      if (d.waitingOn !== 'pm') return null;
+      const ev = display.evidenceOf(ctx.row, displayCtx(ctx));
+      if (ev.moving || ev.at === null) return null;
+      const days = Math.floor((nowOf(ctx) - ev.at) / DAY);
+      if (days < stallDays(ctx)) return null;
+      return { level: 'at-risk', code: 'pm-step-owed', text: `Your ${d.act} is owed. The last evidence is ${days} d old`, source: recordOf(ctx) };
+    },
+  },
+  {
+    id: 'check-by-passed',
+    check(ctx) {
+      const by = ctx.placement && ctx.placement.horizon === 'now' && ctx.placement.check_by;
+      if (!by || by >= todayOf(ctx) || finishedWord(ctx)) return null;
+      return { level: 'at-risk', code: 'check-by-passed', text: `check-by ${shortDate(by)} passed`, source: PLACEMENTS };
+    },
+  },
+  {
+    id: 'item-overdue',
+    check(ctx) {
+      if (!ctx.fold || finishedWord(ctx)) return null;
+      const today = todayOf(ctx);
+      const late = itemsOf(ctx).filter((it) => !it.milestone && it.due && it.due < today && open(it)).sort((a, b) => (a.due < b.due ? -1 : 1));
+      if (!late.length) return null;
+      return {
+        level: 'at-risk', code: 'item-overdue', source: ITEMS,
+        text: late.length === 1 ? `"${late[0].title}" was due ${shortDate(late[0].due)}` : `${plural(late.length, 'item is', 'items are')} overdue, the first due ${shortDate(late[0].due)}`,
+      };
+    },
+  },
+  {
+    id: 'starts-before-predecessor',
+    check(ctx) {
+      if (!ctx.fold || finishedWord(ctx)) return null;
+      const mine = itemsOf(ctx);
+      const byId = new Map(mine.map((it) => [it.id, it]));
+      const all = ctx.fold.items;
+      const lookup = (id) => byId.get(id) || (all && !Array.isArray(all) ? all[id] : null);
+      for (const it of mine) {
+        if (!it.start || !open(it)) continue;
+        for (const pid of it.after || []) {
+          const p = lookup(pid);
+          if (p && p.due && p.due > it.start && p.state !== 'withdrawn' && open(p)) {
+            return { level: 'at-risk', code: 'starts-before-predecessor', source: ITEMS, text: `"${it.title}" starts ${shortDate(it.start)}, before "${p.title}" ends ${shortDate(p.due)}` };
+          }
+        }
+      }
+      return null;
+    },
+  },
+  {
+    id: 'source-unreadable',
+    check(ctx) {
+      if (ctx.row && ctx.row.ok === false) {
+        return { level: 'unknown', code: 'workflow-unreadable', text: 'The workflow could not be read for this initiative', source: recordOf(ctx) };
+      }
+      const bad = ((ctx.fold && ctx.fold.flags) || []).filter((f) => f && f.kind === 'unparseable');
+      if (!bad.length) return null;
+      return { level: 'unknown', code: 'items-unreadable', text: `plan-items.jsonl has ${plural(bad.length, 'line', 'lines')} that could not be read`, source: ITEMS };
+    },
+  },
+];
+
+module.exports = RULES;

package/workspace/lib/health.js

@@ -0,0 +1,79 @@
+'use strict';
+/* health.js — ONE definition of an initiative's health: on track, at risk, off track or unknown, each with its reason
+ * (pm-os-absorb, PRD R8).
+ *
+ *   healthOf(ctx) → { level: 'on'|'at-risk'|'off'|'unknown', reasons: [{ level, code, text, source }] }
+ *   LEVELS · RULE_FILES · rules() · loadErrors()
+ *
+ * `ctx` is what a rule may read, assembled by the caller; any field may be missing and a rule that needs it says
+ * nothing:
+ *   { id, row, fold, placement, measurement, factory, rules, now }
+ *   row          the workflow row of the initiative (scripts/workflow-state.js computeWorkflow)
+ *   fold         lib/plan-items.js readFold of the repository, or null
+ *   placement    lib/placements.js byInit[id], or null
+ *   measurement  lib/measurements.js latest(…, anchor), or null
+ *   factory      the factory join (Run 4), or null
+ *   rules        lib/plan-rules.js readRules(root)
+ *   now          ms since the epoch
+ *
+ * RULES LIVE IN THEIR OWN FILES, not here, so the runs that add them never edit this one. Each file in RULE_FILES
+ * exports an array of `{ id, check(ctx) }`; `check` returns null (nothing to say) or `{ level, code, text, source }`.
+ * A file that is not on disk yet is skipped. A file that fails to load, or a rule that throws, gives an `unknown`
+ * reason that names it: a broken rule must not read as on track.
+ *
+ * The worst level wins: off, then at-risk, then unknown, then on. On track shows no reason. Pure; nothing is cached
+ * except the loaded rule list (D33 applies to data, and rules are code).
+ */
+const path = require('path');
+
+const LEVELS = Object.freeze(['on', 'unknown', 'at-risk', 'off']);   // ascending severity
+const RULE_FILES = Object.freeze([
+  'health-rules-plan.js',      // Run 2 (slice 2D): items, placements, the ladder
+  'health-rules-factory.js',   // Run 4 (slice 4A): factory items, building outside Now
+]);
+
+let loaded = null;
+function load() {
+  if (loaded) return loaded;
+  const list = [];
+  const errors = [];
+  for (const f of RULE_FILES) {
+    const full = path.join(__dirname, f);
+    let mod;
+    try { mod = require(full); }
+    catch (e) {
+      if (e && e.code === 'MODULE_NOT_FOUND' && String(e.message).includes(full)) continue;   // not built yet
+      errors.push({ file: f, error: String((e && e.message) || e).slice(0, 200) });
+      continue;
+    }
+    if (!Array.isArray(mod)) { errors.push({ file: f, error: 'does not export an array of rules' }); continue; }
+    for (const r of mod) {
+      if (r && typeof r.id === 'string' && typeof r.check === 'function') list.push({ ...r, file: f });
+      else errors.push({ file: f, error: 'a rule needs an id and a check function' });
+    }
+  }
+  loaded = { list, errors };
+  return loaded;
+}
+
+const rules = () => load().list.map((r) => ({ id: r.id, file: r.file }));
+const loadErrors = () => load().errors.slice();
+const rank = (level) => LEVELS.indexOf(level);
+
+function healthOf(ctx = {}) {
+  const { list, errors } = load();
+  const reasons = errors.map((e) => ({ level: 'unknown', code: 'rule-file', text: `The health rules in ${e.file} could not be read: ${e.error}`, source: `workspace/lib/${e.file}` }));
+  for (const r of list) {
+    let out;
+    try { out = r.check(ctx); }
+    catch (e) { out = { level: 'unknown', code: 'rule-error', text: `The health rule ${r.id} failed: ${String((e && e.message) || e).slice(0, 160)}`, source: `workspace/lib/${r.file}` }; }
+    if (!out) continue;
+    const level = LEVELS.includes(out.level) && out.level !== 'on' ? out.level : 'unknown';
+    reasons.push({ level, code: String(out.code || r.id), text: String(out.text || r.id), source: String(out.source || `workspace/lib/${r.file}`) });
+  }
+  reasons.sort((a, b) => rank(b.level) - rank(a.level));
+  const level = reasons.length ? reasons[0].level : 'on';
+  return { level, reasons };
+}
+
+module.exports = { LEVELS, RULE_FILES, healthOf, rules, loadErrors };