create-pmos 0.52.0 → 0.53.1

package/workspace/lib/engine/plan-items-stage.js

@@ -0,0 +1,271 @@
+'use strict';
+/* plan-items-stage.js — the stage of each plan item, and the Build rule, for the workflow engine (pm-os-absorb Run 4,
+ * PRD R6, map-spec X29).
+ *
+ *   foldStages(text)               → { items: { [id]: { initiative, stage } }, withdrawn: [id…] }
+ *   readFactory(text)              → { items: { [workItemId]: { initiative, plan_item, integrated, withdrawn } } }
+ *   mainTree(root)                 → the main working tree of root's repository (root itself when it is not linked)
+ *   buildRule({ planText, workText, initiative })
+ *                                  → { applies, materialized: [id…], integrated: [id…], pending: [id…] }
+ *   buildRuleFor(root, id)         → the same, read from the repository's two ledgers; { applies: false } when neither
+ *                                    file is there
+ *   planItemsPath(root) · workItemsPath(root)
+ *
+ * THE BUILD RULE (R6). Items never complete a stage, with one exception: a code initiative's Build stage is done when
+ * every MATERIALIZED item under it is integrated. A materialized item is a work item whose `declared` line names a
+ * plan item (`plan_item`, D86 point 1) that sits in the Build stage of the same initiative and is not withdrawn. A
+ * work item that is withdrawn in the factory ledger is not counted. When an initiative has no materialized item under
+ * Build, the rule does not apply and the engine decides the Build step from the commits, as before.
+ *
+ * WHY THIS FILE EXISTS (X29). The engine (scripts/workflow-state.js) is vendored into the workspace bundle and into
+ * the kit, so it cannot require workspace/lib/plan-items.js. This module reads the same ledger with a small pure fold
+ * of its own. workspace/plan-items-stage-parity.test.js holds it to plan-items.js's fold (stage, withdrawn) and to
+ * scripts/work-item.js's fold (integrated, withdrawn) on every fixture, so a rule added to one fold and not the
+ * other fails a test instead of making CI and the workspace disagree.
+ *
+ * DELIBERATELY FLAT in scripts/, not scripts/lib/ (read-jsonl.js has the same note): the kit and the workspace bundle
+ * vendor the engine's require closure by BASENAME into one directory, so a `./lib/` require from the engine would
+ * load in this checkout and break in every vendored copy.
+ *
+ * The factory half is D65's ORDER, restated small: lines sorted by instant (ledger order breaks a tie), the type's
+ * chain (scripts/work-item.js CHAIN, chainFor), and a two-outcome node satisfied by its LATEST outcome (failed revokes
+ * verified, released revokes claimed). A line that skips its predecessor is not counted, the same as deriveItems
+ * discards it, so a hand-appended `integrated` with no `verified` before it never makes the Build step done. It does
+ * not restate the per-field schema: scripts/check-work-items.js fails CI on a schema-invalid line. Restated, not
+ * required, because work-item.js cannot be vendored (its sink guard requires ./lib/sink.js); the parity test holds the
+ * two folds to one answer, on valid and on invalid ledgers.
+ *
+ * BOTH LEDGERS ARE READ FROM THE MAIN WORKING TREE, as lib/plan-items.js, lib/plan-ledgers.js and lib/factory-join.js
+ * read them. From a linked worktree (where every factory agent works) the engine, check-work-items and the workspace
+ * then read the same two files. mainTree is the filesystem-only walk of lib/plan-tree.js mainTree, restated here.
+ *
+ * Pure apart from the two file reads in buildRuleFor. No network, no git, no clock. Zero dependencies, stock Node.
+ */
+const fs = require('fs');
+const path = require('path');
+
+// ── the plan-items schema, as workspace/lib/plan-items.js lineErr states it ──────────────────────────────────────
+// Every line that lib/plan-items.js ignores must be ignored here too, or the two folds disagree about which line of
+// a repeated event id wins. So the whole stored-line schema is restated, not only the stage fields.
+const EVENTS = ['planned', 'set', 'moved', 'flagged', 'withdrawn', 'kept'];
+const STATES = ['todo', 'doing', 'review', 'done'];
+const SET_FIELDS = ['title', 'stage', 'order', 'owner', 'after', 'start', 'due', 'milestone', 'note'];
+const EVIDENCE_KINDS = ['commit', 'pr', 'file', 'session', 'note'];
+const ID_RE = /^(.+)\.([0-9a-z]{10})$/;
+const INIT_RE = /^[A-Za-z0-9][\w.-]{0,119}$/;
+const EID_RE = /^[0-9a-z]{12}$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const AT_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;
+const BY_RE = /^(?:pm:[a-z0-9_-]{1,40}|agent:unknown|agent:sess-\d+\.[0-9a-f]{8})$/;
+
+const isStr = (v) => typeof v === 'string';
+const oneLine = (v, max) => isStr(v) && v.trim().length >= 1 && v.length <= max && !/[\r\n]/.test(v);
+const initiativeOf = (id) => { const m = ID_RE.exec(String(id || '')); return m ? m[1] : null; };
+function ownerOk(v) {
+  if (v === 'you' || v === 'agent') return true;
+  const m = /^(person|tracker):(.+)$/s.exec(String(v));
+  return !!m && m[2].length >= 1 && m[2].length <= 60 && !/[\r\n]/.test(m[2]);
+}
+const dateOk = (v) => v === null || (isStr(v) && DATE_RE.test(v) && (() => {
+  const t = Date.parse(v + 'T00:00:00Z');
+  return Number.isFinite(t) && new Date(t).toISOString().slice(0, 10) === v;
+})());
+function evidenceBad(e) {
+  if (!e || typeof e !== 'object' || Array.isArray(e) || !EVIDENCE_KINDS.includes(e.kind) || !isStr(e.ref)) return true;
+  const ref = e.ref;
+  if (e.kind === 'commit') return !/^[0-9a-f]{7,40}$/i.test(ref);
+  if (e.kind === 'pr') return !/^#?\d+$/.test(ref);
+  if (e.kind === 'file') return !ref || ref.length > 300 || path.isAbsolute(ref) || ref.split(/[\\/]/).includes('..') || /[\r\n]/.test(ref);
+  if (e.kind === 'session') return !/^sess-\d+$/.test(ref);
+  return !oneLine(ref, 200);
+}
+function fieldBad(k, v) {
+  switch (k) {
+    case 'title': return !oneLine(v, 200);
+    case 'stage': return !(isStr(v) && v.trim());
+    case 'order': return !(typeof v === 'number' && Number.isFinite(v));
+    case 'owner': return !ownerOk(v);
+    case 'after': return !(Array.isArray(v) && v.every((x) => isStr(x) && ID_RE.test(x)));
+    case 'start': case 'due': return !dateOk(v);
+    case 'milestone': return typeof v !== 'boolean';
+    case 'note': return !(v === null || (isStr(v) && v.length <= 1000));
+    default: return true;
+  }
+}
+/** true when lib/plan-items.js would ignore this stored line as schema-invalid. */
+function lineBad(r) {
+  if (!r || typeof r !== 'object' || Array.isArray(r)) return true;
+  if (r.v !== 1 || !isStr(r.eid) || !EID_RE.test(r.eid) || !EVENTS.includes(r.ev)) return true;
+  if (!isStr(r.by) || !BY_RE.test(r.by) || (r.via !== 'ui' && r.via !== 'cli')) return true;
+  if (!isStr(r.at) || !AT_RE.test(r.at) || Number.isNaN(Date.parse(r.at))) return true;
+  if (!isStr(r.initiative) || !INIT_RE.test(r.initiative)) return true;
+  if (r.ev !== 'kept' && (!isStr(r.item) || !ID_RE.test(r.item) || initiativeOf(r.item) !== r.initiative)) return true;
+  switch (r.ev) {
+    case 'planned': return SET_FIELDS.some((k) => fieldBad(k, r[k]));
+    case 'set': {
+      const f = r.fields;
+      if (!f || typeof f !== 'object' || Array.isArray(f) || !Object.keys(f).length) return true;
+      return Object.keys(f).some((k) => !SET_FIELDS.includes(k)
+        || (!((k === 'start' || k === 'due' || k === 'note') && f[k] === null) && fieldBad(k, f[k])));
+    }
+    case 'moved':
+      if (!STATES.includes(r.to)) return true;
+      if (r.evidence !== undefined && evidenceBad(r.evidence)) return true;
+      if (r.override !== undefined && (r.override !== true || !String(r.by).startsWith('pm:'))) return true;
+      return false;
+    case 'flagged': return r.blocked === true ? !oneLine(r.reason, 200) : r.blocked !== false;
+    case 'withdrawn': return false;
+    case 'kept':
+      return r.item !== undefined || !isStr(r.batch) || !/^agent:/.test(r.batch)
+        || !Array.isArray(r.items) || !r.items.length || !r.items.every((x) => isStr(x) && ID_RE.test(x));
+    default: return true;
+  }
+}
+
+/**
+ * The plan-items ledger text → each live item's initiative and stage, and the withdrawn ids. The same order-free
+ * fold as lib/plan-items.js: drop byte-identical duplicates, sort by (at, eid, line), keep the first line of an event
+ * id, ignore a second `planned` of one id and every line after a withdraw.
+ */
+function foldStages(text) {
+  const seenRaw = new Set();
+  const lines = [];
+  for (const raw0 of String(text == null ? '' : text).split('\n')) {
+    const raw = raw0.replace(/\r$/, '').trim();
+    if (!raw || seenRaw.has(raw)) continue;
+    let rec;
+    try { rec = JSON.parse(raw); } catch { continue; }
+    if (lineBad(rec)) continue;
+    seenRaw.add(raw);
+    lines.push({ raw, rec });
+  }
+  lines.sort((a, b) => (Date.parse(a.rec.at) - Date.parse(b.rec.at))
+    || (a.rec.eid < b.rec.eid ? -1 : a.rec.eid > b.rec.eid ? 1 : 0)
+    || (a.raw < b.raw ? -1 : a.raw > b.raw ? 1 : 0));
+  const seenEid = new Set();
+  const items = {};
+  const withdrawn = new Set();
+  for (const { rec } of lines) {
+    if (seenEid.has(rec.eid)) continue;
+    seenEid.add(rec.eid);
+    if (rec.ev === 'kept') continue;
+    if (rec.ev === 'planned') {
+      if (items[rec.item] || withdrawn.has(rec.item)) continue;
+      items[rec.item] = { initiative: rec.initiative, stage: rec.stage };
+      continue;
+    }
+    const it = items[rec.item];
+    if (!it || withdrawn.has(rec.item)) continue;
+    if (rec.ev === 'set' && Object.prototype.hasOwnProperty.call(rec.fields, 'stage')) it.stage = rec.fields.stage;
+    if (rec.ev === 'withdrawn') { delete items[rec.item]; withdrawn.add(rec.item); }
+  }
+  return { items, withdrawn: [...withdrawn].sort() };
+}
+
+/* D65(d)'s chain per type (scripts/work-item.js CHAIN, chainFor, NEGATED_BY, standsSatisfied), restated. */
+const FACTORY_EVENTS = ['declared', 'claimed', 'released', 'verified', 'failed', 'integrated', 'shipped', 'withdrawn'];
+const CHAIN_DEFAULT = ['claimed', 'verified', 'integrated', 'shipped'];
+const CHAIN_HOTFIX = ['claimed', 'verified', 'shipped', 'integrated'];
+const chainFor = (type) => (type === 'spike-item' ? CHAIN_DEFAULT.filter((e) => e !== 'verified') : type === 'hotfix' ? CHAIN_HOTFIX : CHAIN_DEFAULT);
+const NEGATED_BY = { verified: 'failed', claimed: 'released' };
+function standsSatisfied(history, need) {
+  const negator = NEGATED_BY[need];
+  if (!negator) return history.includes(need);
+  for (let i = history.length - 1; i >= 0; i -= 1) {
+    if (history[i] === need) return true;
+    if (history[i] === negator) return false;
+  }
+  return false;
+}
+
+/** The factory ledger text → per work item: its initiative, its plan item, and whether it is integrated or withdrawn. */
+function readFactory(text) {
+  const lines = [];
+  String(text == null ? '' : text).split('\n').forEach((raw, idx) => {
+    if (!raw.trim()) return;
+    let rec;
+    try { rec = JSON.parse(raw); } catch { return; }
+    if (!rec || typeof rec !== 'object' || !isStr(rec.item_id) || !isStr(rec.initiative_id) || !FACTORY_EVENTS.includes(rec.event)) return;
+    const t = typeof rec.at === 'string' ? Date.parse(rec.at) : NaN;
+    if (Number.isNaN(t)) return;
+    lines.push({ rec, idx, t });
+  });
+  lines.sort((a, b) => a.t - b.t || a.idx - b.idx);
+  const items = {}; const fold = {};
+  for (const { rec } of lines) {
+    const id = rec.item_id;
+    if (rec.event === 'declared') {
+      if (items[id]) continue;   // declared twice: the fold keeps the first
+      items[id] = { initiative: rec.initiative_id, plan_item: isStr(rec.plan_item) ? rec.plan_item : null, integrated: false, withdrawn: false };
+      fold[id] = { type: rec.type, history: ['declared'] };
+      continue;
+    }
+    const it = items[id];
+    if (!it || it.withdrawn) continue;
+    const chain = chainFor(fold[id].type);
+    const pos = chain.indexOf(rec.event === 'failed' ? 'verified' : rec.event);
+    if (pos > 0 && !standsSatisfied(fold[id].history, chain[pos - 1])) continue;   // out of order: deriveItems discards it
+    fold[id].history.push(rec.event);
+    if (rec.event === 'integrated') it.integrated = true;
+    if (rec.event === 'withdrawn') it.withdrawn = true;
+  }
+  return { items };
+}
+
+/** The Build rule over the two ledgers' text, for one initiative. */
+function buildRule({ planText, workText, initiative }) {
+  const plan = foldStages(planText);
+  const work = readFactory(workText);
+  const materialized = []; const integrated = []; const pending = [];
+  for (const [wid, w] of Object.entries(work.items)) {
+    if (w.initiative !== initiative || w.withdrawn || !w.plan_item) continue;
+    const p = plan.items[w.plan_item];
+    if (!p || p.initiative !== initiative || p.stage !== 'build') continue;
+    materialized.push(wid);
+    (w.integrated ? integrated : pending).push(wid);
+  }
+  const sort = (a) => a.sort();
+  return { applies: materialized.length > 0, materialized: sort(materialized), integrated: sort(integrated), pending: sort(pending) };
+}
+
+/** The main working tree of root's repository: root itself, unless root is a linked worktree. Filesystem only. */
+function mainTree(root) {
+  try {
+    const dotgit = path.join(root, '.git');
+    if (fs.statSync(dotgit).isDirectory()) return root;
+    const m = /^gitdir:\s*(.+)$/m.exec(fs.readFileSync(dotgit, 'utf8'));
+    if (!m) return root;
+    const gitdir = path.resolve(root, m[1].trim());
+    const common = path.resolve(gitdir, fs.readFileSync(path.join(gitdir, 'commondir'), 'utf8').trim());
+    if (path.basename(common) !== '.git') return root;
+    const main = path.dirname(common);
+    return fs.statSync(path.join(main, '.git')).isDirectory() ? main : root;
+  } catch { return root; }
+}
+
+/** The plan-items ledger of a repository: planning/runs/ for PMOS-self, pmos/state/ in a kit (workflow-state layout). */
+function planItemsPath(root) {
+  const main = mainTree(path.resolve(String(root)));
+  const self = path.join(main, 'planning', 'initiatives');
+  const kit = path.join(main, 'pmos', 'state', 'initiatives');
+  const isKit = !fs.existsSync(self) && fs.existsSync(kit);
+  return isKit ? path.join(main, 'pmos', 'state', 'plan-items.jsonl') : path.join(main, 'planning', 'runs', 'plan-items.jsonl');
+}
+/** The D65 factory ledger of a repository (the one scripts/check-work-items.js reads), in the main working tree. */
+const workItemsPath = (root) => path.join(mainTree(path.resolve(String(root))), 'planning', 'work-items.jsonl');
+
+function readText(file) {
+  try { return { ok: true, text: fs.readFileSync(file, 'utf8') }; }
+  catch (e) { return { ok: e && e.code === 'ENOENT', text: '', missing: true, error: e && e.code !== 'ENOENT' ? String(e.message || e) : null }; }
+}
+
+function buildRuleFor(root, initiative) {
+  const work = readText(workItemsPath(root));
+  if (work.missing && work.ok) return { applies: false, materialized: [], integrated: [], pending: [] };
+  if (!work.ok) return { applies: false, unknown: true, reason: `the factory ledger could not be read: ${work.error}`, materialized: [], integrated: [], pending: [] };
+  const plan = readText(planItemsPath(root));
+  if (!plan.ok) return { applies: false, unknown: true, reason: `the plan-items ledger could not be read: ${plan.error}`, materialized: [], integrated: [], pending: [] };
+  return buildRule({ planText: plan.text, workText: work.text, initiative });
+}
+
+module.exports = { foldStages, readFactory, buildRule, buildRuleFor, mainTree, planItemsPath, workItemsPath, lineBad };

package/workspace/lib/engine/workflow-state.js

@@ -1067,8 +1067,24 @@ function computeWorkflowDerived(id, opts) {
    * commits in this range" is a statement about the RANGE, and on a branch level with `main` that
    * range is legitimately empty. A reader who cannot tell those apart calls the second one "never
    * built", which is the console's half of this defect.
+   *
+   * THE BUILD RULE (PRD R6, pm-os-absorb Run 4). Items never complete a stage, with one exception: when plan items
+   * under Build were materialized (a D65 `declared` line names them as `plan_item`, D86 point 1), the step is done
+   * when every one of those work items is integrated, and pending until then, whatever the commits say. With no
+   * materialized item the commits decide, as above. The rule reads both ledgers through plan-items-stage.js, the
+   * engine's own pure fold (X29: the engine cannot require workspace/lib). A broken delivered_by stays blocked first.
    */
-  steps.push(build.unknown
+  const buildRule = require('./plan-items-stage').buildRuleFor(root, id);
+  const ruleStep = build.failedDeclaration || !(buildRule.applies || buildRule.unknown) ? null
+    : buildRule.unknown
+      ? step('build', 'build', 'unknown', buildRule.reason)
+      : buildRule.pending.length === 0
+        ? step('build', 'build', 'done',
+          `every materialized item under Build is integrated (${buildRule.integrated.length} of ${buildRule.materialized.length} in planning/work-items.jsonl)`)
+        : step('build', 'build', 'pending',
+          `${buildRule.integrated.length} of ${buildRule.materialized.length} materialized item(s) under Build integrated — waiting on ${buildRule.pending.join(', ')}`,
+          'merge each work item with a `Work-Item: <id>` trailer on the trunk, then run `pmos verify-work`');
+  steps.push(ruleStep || (build.unknown
     ? step('build', 'build', 'unknown', build.reason || range.reason)
     : build.failedDeclaration
       // REPORTED, never CI-blocking — the same stance R1 takes on an unresolvable anchor. Making a
@@ -1087,7 +1103,7 @@ function computeWorkflowDerived(id, opts) {
             : 'no implementation commits in this range')
           : step('build', 'build', 'done', build.signal
             ? `${build.count} commit(s) on implementation paths — ${delivery.attributionEvidence(build.signal, id, build.declaredSha)}`
-            : `${build.count} commit(s) on implementation paths`));
+            : `${build.count} commit(s) on implementation paths`)));
 
   // ── quality ─ CI's verdict, never this engine's ──────────────────────────────────────────────
   steps.push(step('quality', 'quality', 'unknown', 'CI decides on the PR — this engine never claims a test result it did not run'));
@@ -1325,9 +1341,19 @@ function pmLadder({ id, fm, lane, effLane, knownLane, legacy, steps, root, L, re
   const accepted = cachedJsonl(path.join(L.runsDir, 'acceptances.jsonl'))
     .filter((a) => a && a.initiative_id === id && a.accepted === true);
   const acceptedOn = accepted.length ? (accepted[accepted.length - 1].accepted_at || accepted[accepted.length - 1].at) : null;
+  // D86 point 3 — a report is approved when the PM issues it: an `issued` line in issues.jsonl naming its doc_path.
+  // Its own minimal parse (X29: the vendored engine never requires workspace/lib); a line counts only if the PM wrote it.
+  const norm = (p) => String(p || '').trim().replace(/^\.\//, '');
+  const issued = effLane !== 'report' || !docPath ? []
+    : cachedJsonl(path.join(L.runsDir, 'issues.jsonl')).filter((r) => r && r.ev === 'issued' && norm(r.path) === norm(docPath)
+      && /^pm:/.test(String(r.by || '')) && (r.via === 'ui' || r.via === 'cli') && /^[0-9a-f]{40}$/.test(String(r.sha || '')));
   steps.push(!flows('approved') ? skipped('approved', 'approved')
+    : issued.length
+    ? step('approved', 'approved', 'done', `issued by the PM on ${String(issued[0].at || '').slice(0, 10)} (issues.jsonl)`)
     : accepted.length
     ? step('approved', 'approved', 'done', `accepted by the PM${acceptedOn ? ' on ' + String(acceptedOn).slice(0, 10) : ''}`)
+    : effLane === 'report'
+    ? step('approved', 'approved', 'pending', 'awaiting the PM\'s Issue (D86 point 3)', 'the PM issues the report (pmos report issue, or Issue on Reports) — never automatic')
     : step('approved', 'approved', 'pending', 'awaiting the PM\'s acceptance (D12)', 'the PM accepts the document — never automatic'));
 
   if (!flows('handoff')) steps.push(step('handoff', 'handed off', 'na', `${effLane} — nothing to hand off`));

package/workspace/lib/factory-join.js

@@ -0,0 +1,158 @@
+'use strict';
+/* factory-join.js — THE ONE JOIN of the factory graph's work items onto plan items and initiatives (pm-os-absorb Run 4,
+ * PRD R6, R7, R8, R19; D65, D86 point 1).
+ *
+ *   joinFactory(root, { initiative, fold } = {}) → {
+ *     ok: true,
+ *     byInit: {
+ *       [initiativeId]: {
+ *         items:   [{ id, plan_item, state, pr, integrated, integrated_at }],
+ *                    id = work-item id; plan_item = plan item id | null; state = the work item's folded state
+ *                    (scripts/work-item.js deriveItems: declared, claimed, verified, failed, integrated, shipped,
+ *                    withdrawn); pr = a pull-request reference from its evidence | null; integrated = true once
+ *                    `pmos verify-work` saw its trailer on the default branch; integrated_at = that line's time | null
+ *         batches: [{ id, ready, items: [<work-item id>] }],     a D65 Release batch; ready = every item passed its checks
+ *       }
+ *     },
+ *     flags: [{ kind, id, why }],                                a dangling plan_item, an unreadable line, a missing engine
+ *     unreadable?: why                                           only when the ledger EXISTS but cannot be read or folded
+ *   }
+ *   factoryOf(join, id) → that initiative's entry, or null; when the join is `unreadable`, { items: [], batches: [],
+ *                         unreadable: why } for every id, so a health rule says Unknown (R8) and never "on track"
+ *
+ * `initiative` narrows byInit to that one id. `fold` is an optional lib/plan-items.js fold the caller already holds
+ * (lib/plan-tree.js layout passes its own), so the dangling check does not read the plan-items ledger twice. Readers
+ * never throw; a bad line is a flag.
+ *
+ * THE FOLD IS D65's, NOT A COPY. Work-item state comes from scripts/work-item.js deriveItems, the fold the writer and
+ * the CI checker (scripts/check-work-items.js) use, so this join cannot call an item verified that the gate calls
+ * failed. That module lives in scripts/ and is not vendored into a published workspace (its sink guard requires a
+ * directory the vendoring walk refuses). In an install without it, a repository that HAS a factory ledger gets the
+ * flag `engine-missing` and an empty join; one without a ledger gets an empty join and no flag. Only PMOS-self runs a
+ * factory today.
+ *
+ * WHERE THE LEDGER IS. `planning/work-items.jsonl` of the MAIN working tree of `root`, the same tree the plan-items
+ * ledger resolves to (lib/plan-items.js ledgerRoot), so the two halves of the join are read from one tree.
+ *
+ * A BATCH (D65 Release, D86 point 2) is the work items one materialization declared: one Commit covers the whole batch
+ * (R14), and the materialization writes their `declared` lines with ONE `at`. The ledger has no batch field (D86 point
+ * 1 adds `plan_item` and nothing else), so the batch is that shared `at`. Only materialized items (a `plan_item`) form
+ * batches; a withdrawn or shipped item has left its batch. The batch is keyed on that `at` as an INSTANT, and its id is
+ * `b<UTC digits of that at>` — 14 digits to the second, and the 3 millisecond digits after them when they are not
+ * 000 — so two materializations in one second have two ids, and one Release grant names `<initiative>:<batch id>`. `ready` = every item in it is verified or integrated, and none failed.
+ *
+ * Consumers (all read through this module, never work-items.jsonl directly):
+ *   - health ctx.factory = factoryOf(joinFactory(root), id)   (lib/health-rules-factory.js reads it; 2C's routes and
+ *     5A's drafter assemble it);
+ *   - lib/plan-tree.js layout (a materialized item reads Done once integrated, R7);
+ *   - 4D's Board and work-check-needs (Review and Release rows);
+ *   - 5A's blocks (factory progress when present).
+ *
+ * Nothing is cached (D33). No network, no git.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const WORK_ITEM_PATHS = [path.join(__dirname, '..', '..', 'scripts', 'work-item.js')];
+const READY = new Set(['verified', 'integrated']);
+const PR_RE = /^(?:https?:\/\/\S+\/pull\/\d+\S*|pr:#?\d+)$/i;
+
+function loadWorkItem() {
+  for (const p of WORK_ITEM_PATHS) {
+    if (!fs.existsSync(p)) continue;
+    try { return { ok: true, mod: require(p) }; }
+    catch (e) { return { ok: false, error: `scripts/work-item.js is present but failed to load — ${String((e && e.message) || e).slice(0, 160)}` }; }
+  }
+  return { ok: false, error: 'the work-item fold (scripts/work-item.js) is not in this install, so factory work cannot be read here' };
+}
+
+function mainTreeOf(root) {
+  try { return require('./plan-tree.js').mainTree(path.resolve(String(root))); } catch { return path.resolve(String(root)); }
+}
+
+/** Per work item, from the raw lines: the `at` of its declaration, its last integrated time and its last PR evidence. */
+function lineFacts(text) {
+  const facts = new Map();
+  for (const raw of String(text).split('\n')) {
+    if (!raw.trim()) continue;
+    let r;
+    try { r = JSON.parse(raw); } catch { continue; }
+    if (!r || typeof r !== 'object' || typeof r.item_id !== 'string') continue;
+    const f = facts.get(r.item_id) || { declaredAt: null, integratedAt: null, pr: null };
+    if (r.event === 'declared' && !f.declaredAt && typeof r.at === 'string') f.declaredAt = r.at;
+    if (r.event === 'integrated' && typeof r.at === 'string') f.integratedAt = r.at;
+    if (typeof r.evidence === 'string' && PR_RE.test(r.evidence.trim())) f.pr = r.evidence.trim();
+    facts.set(r.item_id, f);
+  }
+  return facts;
+}
+
+/** The batch id of one declared instant: b + 14 digits, + the milliseconds when they are not 000. Unique per instant. */
+function batchId(at) {
+  const t = Date.parse(at);
+  if (!Number.isFinite(t)) return `b${String(at).replace(/\D/g, '')}`;
+  const digits = new Date(t).toISOString().replace(/\D/g, '');   // YYYYMMDDHHMMSSmmm
+  return `b${digits.endsWith('000') ? digits.slice(0, 14) : digits}`;
+}
+
+function joinFactory(root, { initiative, fold } = {}) {
+  const out = { ok: true, byInit: {}, flags: [] };
+  const unreadable = (kind, why) => { out.flags.push({ kind, id: null, why }); out.unreadable = why; return out; };
+  const file = path.join(mainTreeOf(root), 'planning', 'work-items.jsonl');
+  let text = '';
+  try { text = fs.readFileSync(file, 'utf8'); }
+  catch (e) {
+    if (!(e && e.code === 'ENOENT')) return unreadable('unreadable', `planning/work-items.jsonl cannot be read (${(e && e.code) || e})`);
+    return out;
+  }
+  if (!text.trim()) return out;
+  const W = loadWorkItem();
+  if (!W.ok) return unreadable('engine-missing', W.error);
+
+  let derived;
+  try { derived = W.mod.deriveItems(text, { now: new Date().toISOString() }); }
+  catch (e) { return unreadable('unreadable', `the work-item fold failed: ${String((e && e.message) || e).slice(0, 160)}`); }
+  for (const d of derived.defects) out.flags.push({ kind: d.kind, id: d.item_id || null, why: `line ${d.line}: ${d.detail}` });
+
+  let planFold = fold || null;
+  if (!planFold && derived.items.some((it) => typeof it.plan_item === 'string')) {
+    try { planFold = require('./plan-items.js').readFold(root); }
+    catch (e) { out.flags.push({ kind: 'plan-items-unreadable', id: null, why: `the plan-items ledger cannot be read, so no plan_item is checked: ${String((e && e.message) || e).slice(0, 160)}` }); }
+  }
+  const known = planFold ? new Set([...Object.keys(planFold.items || {}), ...(planFold.withdrawnIds || [])]) : null;
+
+  const facts = lineFacts(text);
+  const batchesOf = new Map();
+  for (const it of derived.items) {
+    if (initiative && it.initiative_id !== initiative) continue;
+    const id = it.item_id;
+    const f = facts.get(id) || {};
+    const planItem = typeof it.plan_item === 'string' ? it.plan_item : null;
+    if (planItem && known && !known.has(planItem)) {
+      out.flags.push({ kind: 'dangling-plan-item', id, why: `plan_item ${planItem} names no plan item` });
+    }
+    const integrated = (it.history || []).includes('integrated');
+    const entry = out.byInit[it.initiative_id] || (out.byInit[it.initiative_id] = { items: [], batches: [] });
+    entry.items.push({ id, plan_item: planItem, state: it.state, pr: f.pr || null, integrated, integrated_at: integrated ? f.integratedAt || null : null });
+    if (planItem && it.state !== 'withdrawn' && it.state !== 'shipped' && f.declaredAt) {
+      const t = Date.parse(f.declaredAt);
+      const key = `${it.initiative_id}\u0000${Number.isFinite(t) ? t : f.declaredAt}`;
+      if (!batchesOf.has(key)) batchesOf.set(key, { init: it.initiative_id, at: f.declaredAt, items: [], states: [] });
+      const b = batchesOf.get(key);
+      b.items.push(id); b.states.push(it.state);
+    }
+  }
+  for (const b of batchesOf.values()) {
+    out.byInit[b.init].batches.push({ id: batchId(b.at), ready: b.states.every((s) => READY.has(s)), items: b.items.slice().sort() });
+  }
+  for (const e of Object.values(out.byInit)) e.batches.sort((a, b) => a.id.localeCompare(b.id));
+  return out;
+}
+
+/** The health ctx.factory value for one initiative: its join entry, or null. */
+function factoryOf(join, id) {
+  if (join && typeof join.unreadable === 'string') return { items: [], batches: [], unreadable: join.unreadable };
+  return (join && join.byInit && Object.prototype.hasOwnProperty.call(join.byInit, id)) ? join.byInit[id] : null;
+}
+
+module.exports = { joinFactory, factoryOf };

package/workspace/lib/goals.js

@@ -0,0 +1,165 @@
+'use strict';
+/* goals.js — the PM's goals for the day, and the plan that joins them to what is known and what is owed (initiative
+ * `today-goals`, PRD G1 and G4).
+ *
+ * Pure: no I/O, no clock of its own, no model, no network. The server reads the goals file, the brief and the Today cards,
+ * passes them with `now`, and writes what `edit` returns.
+ *
+ *   emptyDay(date)                         → { date, goals: [] }
+ *   edit(day, op, { now })                 → { ok:true, day } | { ok:false, error }
+ *        op: { action: 'add', text, initiative_id? } | { action: 'done'|'drop'|'reopen'|'remove', id }
+ *   readDay(raw, date)                     → a checked day record, or an empty day when `raw` is not one
+ *   planDay({ day, brief, cards, now, endOfDay }) → the plan Today and `pmos proactive goals` show
+ *
+ * THE JOIN IS CHECKABLE. A brief item or calendar event belongs to a goal when it names the goal's id (the morning-brief
+ * session sets it). Failing that, an item or Today card belongs to the first open goal tied to the same initiative. There
+ * is no word matching: a link is an id, so the PM can see why a step is under a goal. One step is under one goal only.
+ */
+const crypto = require('crypto');
+
+const MAX_GOALS = 7;
+const MAX_TEXT = 140;
+const STATUSES = ['open', 'done', 'dropped'];
+const ACTIONS = ['add', 'done', 'drop', 'reopen', 'remove'];
+const INI_RE = /^[a-z0-9][a-z0-9._-]*$/i;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const GOAL_ID_RE = /^g-[0-9a-f]{8}$/;
+const START_OF_DAY = '09:00';
+const END_OF_DAY = '18:00';
+const clip = (s, n) => String(s == null ? '' : s).replace(/\s+/g, ' ').trim().slice(0, n);
+
+const emptyDay = (date) => ({ date, goals: [] });
+
+/** A day record read from disk, checked. Anything that is not a day record for `date` reads as an empty day. */
+function readDay(raw, date) {
+  if (!raw || typeof raw !== 'object' || raw.date !== date || !Array.isArray(raw.goals)) return emptyDay(date);
+  const goals = raw.goals.filter((g) => g && typeof g === 'object' && GOAL_ID_RE.test(g.id) && typeof g.text === 'string' && g.text.trim()
+    && STATUSES.includes(g.status)).slice(0, MAX_GOALS).map((g) => ({
+    id: g.id, text: clip(g.text, MAX_TEXT), initiative_id: typeof g.initiative_id === 'string' && INI_RE.test(g.initiative_id) ? g.initiative_id : null,
+    status: g.status, added_at: typeof g.added_at === 'string' ? g.added_at : null, closed_at: typeof g.closed_at === 'string' ? g.closed_at : null,
+  }));
+  return { date, goals };
+}
+
+/** One edit of the day's goals. A refused edit returns the reason and the caller writes nothing. */
+function edit(day, op, { now = Date.now() } = {}) {
+  if (!day || !DATE_RE.test(String(day.date)) || !Array.isArray(day.goals)) return { ok: false, error: 'no day record to edit' };
+  if (!op || typeof op !== 'object' || !ACTIONS.includes(op.action)) return { ok: false, error: `action must be one of ${ACTIONS.join(', ')}` };
+  const at = new Date(now).toISOString();
+  const goals = day.goals.map((g) => ({ ...g }));
+  if (op.action === 'add') {
+    if (typeof op.text !== 'string' || !op.text.trim()) return { ok: false, error: 'a goal needs text' };
+    if (op.text.trim().length > MAX_TEXT) return { ok: false, error: `a goal is at most ${MAX_TEXT} characters` };
+    if (goals.length >= MAX_GOALS) return { ok: false, error: `a day has at most ${MAX_GOALS} goals. Drop or remove one first.` };
+    const ini = op.initiative_id == null || op.initiative_id === '' ? null : op.initiative_id;
+    if (ini !== null && (typeof ini !== 'string' || !INI_RE.test(ini))) return { ok: false, error: 'initiative_id is not an initiative id' };
+    const text = clip(op.text, MAX_TEXT);
+    if (goals.some((g) => g.text.toLowerCase() === text.toLowerCase())) return { ok: false, error: 'that goal is already on the list' };
+    const id = 'g-' + crypto.createHash('sha1').update(`${day.date}|${text}|${at}|${goals.length}`).digest('hex').slice(0, 8);
+    goals.push({ id, text, initiative_id: ini, status: 'open', added_at: at, closed_at: null });
+    return { ok: true, day: { date: day.date, goals }, goal: goals[goals.length - 1] };
+  }
+  const i = goals.findIndex((g) => g.id === op.id);
+  if (i < 0) return { ok: false, error: 'no goal with that id today' };
+  const g = goals[i];
+  if (op.action === 'remove') { goals.splice(i, 1); return { ok: true, day: { date: day.date, goals }, goal: g }; }
+  const to = { done: 'done', drop: 'dropped', reopen: 'open' }[op.action];
+  if (g.status === to) return { ok: false, error: `that goal is already ${to}` };
+  g.status = to; g.closed_at = to === 'open' ? null : at;
+  return { ok: true, day: { date: day.date, goals }, goal: g };
+}
+
+/* ── the plan ──────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+const minutesOf = (hhmm) => { const [h, m] = String(hhmm).split(':').map(Number); return h * 60 + m; };
+
+/** Free minutes of the working day still ahead (from `now`, or 09:00 if earlier, to 18:00 local), and the next event. */
+function freeTime(events, at, endOfDay = END_OF_DAY) {
+  const d = new Date(at);
+  const end = new Date(d.getFullYear(), d.getMonth(), d.getDate(), 0, minutesOf(endOfDay)).getTime();
+  const now = Math.max(at, new Date(d.getFullYear(), d.getMonth(), d.getDate(), 0, minutesOf(START_OF_DAY)).getTime());
+  if (now >= end) return { free_minutes: 0, until: endOfDay, next: null };
+  const spans = [];
+  for (const e of events || []) {
+    const s = Date.parse(e.start); const f = e.end ? Date.parse(e.end) : s + 30 * 60000;
+    if (!Number.isFinite(s) || !Number.isFinite(f) || f <= now || s >= end) continue;
+    spans.push([Math.max(s, now), Math.min(f, end)]);
+  }
+  spans.sort((a, b) => a[0] - b[0]);
+  let busy = 0; let cur = null;
+  for (const sp of spans) {
+    if (!cur || sp[0] > cur[1]) { if (cur) busy += cur[1] - cur[0]; cur = sp.slice(); }
+    else cur[1] = Math.max(cur[1], sp[1]);
+  }
+  if (cur) busy += cur[1] - cur[0];
+  const upcoming = (events || []).filter((e) => Date.parse(e.start) > now).sort((a, b) => Date.parse(a.start) - Date.parse(b.start))[0] || null;
+  return { free_minutes: Math.max(0, Math.round((end - now - busy) / 60000)), until: endOfDay, next: upcoming ? { start: upcoming.start, title: upcoming.title } : null };
+}
+
+const stepOrder = (a, b) => (a.owner === b.owner ? 0 : a.owner === 'pm' ? -1 : 1) || (b.confidence - a.confidence) || a.title.localeCompare(b.title);
+
+function itemStep(x) {
+  return { ref: 'brief:' + x.id, from: 'brief', source: x.source, title: x.title, why: x.why_now, evidence: x.evidence || '', owner: x.owner,
+    effort: x.effort, confidence: x.confidence, initiative_id: x.initiative_id || null, mention: !!x.mention, worth_asking: !!x.worth_asking,
+    prepare: x.owner === 'agent' && !!x.initiative_id };
+}
+function cardStep(c) {
+  return { ref: 'today:' + c.id, from: 'today', source: c.source || 'today', title: c.cause, why: c.cause, evidence: c.evidence || '', owner: 'pm',
+    effort: null, confidence: 1, initiative_id: c.initiative_id || null, kind: c.kind, act: c.act ? c.act.label : null, ws: c.ws || null, mention: false,
+    worth_asking: false, prepare: false };
+}
+
+/**
+ * The day plan.
+ *   day      the goals record for the day (readDay)
+ *   brief    the stored brief (lib/brief.js shape) or null
+ *   cards    Today cards (lib/today.js) across the workspaces read, or []
+ *   now      ms; the clock the server passes
+ * A brief for another day is not joined: it is named as out of date, and only the Today cards plan the goals.
+ */
+function planDay({ day, brief = null, cards = [], now = Date.now(), endOfDay = END_OF_DAY } = {}) {
+  const date = day && day.date;
+  const fresh = !!brief && brief.date === date;
+  const items = fresh ? [...(brief.priorities || []), ...(brief.worth_asking || [])] : [];
+  const events = fresh ? (brief.calendar || []) : [];
+  const goals = (day && day.goals ? day.goals : []).map((g) => ({ ...g, steps: [], context: [] }));
+  const open = goals.filter((g) => g.status === 'open');
+  const byId = new Map(goals.map((g) => [g.id, g]));
+  const byIni = (ini) => (ini ? open.find((g) => g.initiative_id === ini) || null : null);
+  const unplaced = { items: [], cards: [] };
+
+  for (const x of items) {
+    const g = (x.goal && byId.get(x.goal)) || byIni(x.initiative_id);
+    if (g) g.steps.push(itemStep(x)); else unplaced.items.push(x);
+  }
+  for (const c of cards || []) {
+    const g = byIni(c.initiative_id);
+    if (g) g.steps.push(cardStep(c)); else unplaced.cards.push(c);
+  }
+  for (const e of events) {
+    const g = e.goal && byId.get(e.goal);
+    if (g) g.context.push({ start: e.start, end: e.end || null, title: e.title, with: e.with || null });
+  }
+  for (const g of goals) {
+    g.steps.sort(stepOrder);
+    g.coverage = g.status === 'done' ? 'done' : g.status === 'dropped' ? 'dropped' : g.steps.length ? 'planned' : 'needs-plan';
+    g.agent_steps = g.steps.filter((s) => s.prepare).length;
+  }
+  const also = [
+    ...unplaced.items.filter((x) => !x.worth_asking).map(itemStep),
+    ...unplaced.cards.map(cardStep),
+  ].sort(stepOrder);
+  const worthAsking = unplaced.items.filter((x) => x.worth_asking).map(itemStep).sort(stepOrder);
+  const notRead = fresh ? Object.entries(brief.sources || {}).filter(([, v]) => v !== 'read').map(([k, v]) => ({ source: k, state: v })) : [];
+  const counts = { open: open.length, done: goals.filter((g) => g.status === 'done').length, planned: goals.filter((g) => g.coverage === 'planned').length,
+    needs_plan: goals.filter((g) => g.coverage === 'needs-plan').length };
+  return {
+    date, goals, also, worth_asking: worthAsking, counts,
+    brief: brief ? { date: brief.date, fresh, generated_at: brief.generated_at || null } : null,
+    not_read: notRead,
+    time: fresh ? freeTime(events, now, endOfDay) : null,
+    mentions: items.filter((x) => x.mention).length,
+  };
+}
+
+module.exports = { MAX_GOALS, MAX_TEXT, STATUSES, ACTIONS, GOAL_ID_RE, START_OF_DAY, END_OF_DAY, emptyDay, readDay, edit, freeTime, planDay };