create-pmos 0.13.0 → 0.15.0

package/workspace/handoff.test.js

@@ -0,0 +1,443 @@
+#!/usr/bin/env node
+/* Unit suite for lib/handoff.js — the handoff links model.
+ *
+ * No framework, no mocks. Records are REAL markdown files on disk, parsed by the REAL
+ * `parseLeadingFrontmatter` (lib/file-mode-parse.js) — the same function the server and the kit's
+ * metrics.py agree on. A test double for the parser would agree with whatever this file assumed,
+ * and the frontmatter format's sharp edge (section A5) is precisely a thing a double would hide.
+ *
+ * The suite is organised around the one invariant the module exists to hold:
+ *
+ *   A · the five record fields, through the real parser — and the format's truncation trap
+ *   B · every link is NOT-CONNECTED, per row, naming its own system
+ *   C · absence and emptiness are stated, never implied
+ *   D · a malformed declaration is a problem with its value verbatim — never dropped, never rendered
+ *   E · the URL admission table: clickable only as an absolute http(s) URL
+ *   F · STRUCTURAL IMPOSSIBILITY — the section that matters
+ *   G · the real repository, as a corpus check
+ *
+ * Section F is the point of this file. Anyone can write a test showing that today's code did not
+ * fabricate a story count; that test passes again the day after someone adds one somewhere else.
+ * F asserts that the module CANNOT: it imports nothing, so no reading can enter it; it returns no
+ * number anywhere, so a count has no field to live in; its key sets are compared for equality, so a
+ * `synced_at` cannot be added quietly; its result is frozen, so `connected` cannot be flipped
+ * downstream; and every string it emits is either copied verbatim out of the record file or is one
+ * of ten enumerated fixed sentences.
+ *
+ * Exits non-zero if any check fails.
+ */
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const assert = require('assert');
+
+const H = require('./lib/handoff');
+const { parseLeadingFrontmatter } = require('./lib/file-mode-parse');
+
+const results = [];
+const ok = (name, cond, extra = '') => { results.push({ name, cond }); console.log(`${cond ? '✓' : '✗'} ${name}${extra ? ' — ' + extra : ''}`); };
+
+const TMP = fs.mkdtempSync(path.join(os.tmpdir(), 'pmos-handoff-'));
+/** An initiative record file with whatever frontmatter the case needs. */
+function record(fm, body = 'Body prose, which must never be able to fake a declaration.\n') {
+  return `---\n${Object.entries(fm).map(([k, v]) => `${k}: ${v}`).join('\n')}\n---\n\n${body}`;
+}
+function writeRecord(name, fm, body) {
+  const full = path.join(TMP, name);
+  fs.writeFileSync(full, record(fm, body));
+  return full;
+}
+/** The whole path a real record takes: file → real parser → model. */
+const modelOf = (file) => H.readLinks(parseLeadingFrontmatter(fs.readFileSync(file, 'utf8')));
+const linkById = (m, id) => m.links.find((l) => l.id === id) || null;
+const problemById = (m, id) => m.problems.find((p) => p.id === id) || null;
+
+/** Every string anywhere in a value — the basis of the whitelist and the fabrication checks. */
+function collectStrings(v, out = []) {
+  if (typeof v === 'string') out.push(v);
+  else if (Array.isArray(v)) v.forEach((x) => collectStrings(x, out));
+  else if (v && typeof v === 'object') Object.keys(v).forEach((k) => collectStrings(v[k], out));
+  return out;
+}
+/** Every non-string primitive anywhere — used to prove there is not one number in the model. */
+function collectPrimitives(v, out = []) {
+  if (v === null || typeof v !== 'object') out.push(v);
+  else if (Array.isArray(v)) v.forEach((x) => collectPrimitives(x, out));
+  else Object.keys(v).forEach((k) => collectPrimitives(v[k], out));
+  return out;
+}
+const uniqSorted = (a) => [...new Set(a)].sort();
+
+try {
+  // ── A · the five record fields, through the real parser (R1) ────────────────────────────────
+  const allFile = writeRecord('all-five.md', {
+    type: 'Initiative', title: '"crm import wizard"', timestamp: '2026-07-20',
+    id: 'crm-import-wizard', lane: 'feature', parent_kr: 'q3-2026:o1:kr2',
+    flow: 'adlc-handoff',
+    handoff_to: 'atlas app team — the ATL board',
+    handoff_epic: 'ATL-482',
+    handoff_page: 'https://example.atlassian.net/wiki/spaces/PM/crm-import-wizard-prd',
+    handoff_at: '2026-07-20',
+  });
+  const allText = fs.readFileSync(allFile, 'utf8');
+  const all = modelOf(allFile);
+
+  ok('A1: the five R1 keys round-trip through the REAL parser into the model',
+    all.handoff === true && all.flow === 'adlc-handoff' && all.to === 'atlas app team — the ATL board'
+      && all.at === '2026-07-20' && all.links.length === 2,
+    JSON.stringify({ flow: all.flow, at: all.at, links: all.links.length }));
+
+  ok('A2: every declared value is carried VERBATIM — nothing is normalised, prettified or re-cased',
+    linkById(all, 'handoff_epic').declared === 'ATL-482'
+      && linkById(all, 'handoff_page').declared === 'https://example.atlassian.net/wiki/spaces/PM/crm-import-wizard-prd',
+    linkById(all, 'handoff_epic').declared);
+
+  ok('A3: `systems` names both systems, from which keys are declared — not from any reading',
+    JSON.stringify(all.systems) === JSON.stringify(['Jira', 'Confluence']), JSON.stringify(all.systems));
+
+  // Link order is fixed by the module, not by the record, so the section cannot re-order itself when
+  // a PM happens to type the page key above the epic key.
+  const flippedFile = writeRecord('flipped.md', {
+    type: 'Initiative', title: '"flipped"', timestamp: '2026-07-20', id: 'flipped',
+    handoff_page: 'https://example.atlassian.net/wiki/x', handoff_epic: 'ATL-9',
+  });
+  ok('A4: link order is the module\'s, not the record\'s — frontmatter order cannot reshuffle the section',
+    JSON.stringify(modelOf(flippedFile).links.map((l) => l.id)) === JSON.stringify(['handoff_epic', 'handoff_page']),
+    JSON.stringify(modelOf(flippedFile).links.map((l) => l.id)));
+
+  /* A5 — the truncation trap (PRD R2). This is here so that a later author who reaches for
+   * `links:` as a YAML list finds a FAILING TEST explaining what it costs, rather than discovering
+   * it through an initiative that silently reads as unanchored. The list does not partially parse:
+   * the `links:` line ends the frontmatter block, and every key below it — including `lane` and
+   * `parent_kr`, the two the Initiative Gate rejects work for lacking — is dropped without a word. */
+  const listFile = path.join(TMP, 'yaml-list.md');
+  fs.writeFileSync(listFile,
+    '---\ntype: Initiative\ntitle: "listy"\ntimestamp: 2026-07-29\nid: listy\n'
+    + 'links:\n  - ATL-482\n  - https://example.atlassian.net/wiki/x\n'
+    + 'lane: feature\nparent_kr: q3-2026:o1:kr2\n---\n\nBody.\n');
+  const truncated = parseLeadingFrontmatter(fs.readFileSync(listFile, 'utf8'));
+  ok('A5: a YAML list TERMINATES the frontmatter block — `lane` and `parent_kr` below it vanish, '
+    + 'which is why the handoff fields are flat and single-line and must stay that way',
+    truncated.id === 'listy' && !('links' in truncated) && !('lane' in truncated) && !('parent_kr' in truncated),
+    JSON.stringify(Object.keys(truncated)));
+
+  // ── B · every link is NOT-CONNECTED, per row, naming its own system (R4) ────────────────────
+  const epic = linkById(all, 'handoff_epic');
+  const page = linkById(all, 'handoff_page');
+
+  ok('B1: the epic row carries the state, the clause and the full sentence — on the ROW, not once per section',
+    epic.state === 'not-connected' && epic.why === 'no Jira credential is configured'
+      && epic.state_text === 'not connected — no Jira credential is configured; this is what the record declares, not a reading',
+    epic.state_text);
+
+  ok('B2: a Confluence row says Confluence — the state names the system this row points at, not a generic one',
+    page.state === 'not-connected' && page.why === 'no Confluence credential is configured'
+      && page.state_text.includes('no Confluence credential is configured') && !page.state_text.includes('Jira'),
+    page.state_text);
+
+  ok('B3: the state is text, so it can be a row\'s accessible name — never colour, never a tooltip alone',
+    all.links.every((l) => typeof l.state_text === 'string' && l.state_text.length > 60
+      && typeof l.why === 'string' && l.why.length > 20),
+    JSON.stringify(all.links.map((l) => l.state_text.length)));
+
+  ok('B4: `kind` is a marker for WHICH system, and is the only field that could ever be a badge',
+    epic.kind === 'jira' && page.kind === 'confluence', `${epic.kind} / ${page.kind}`);
+
+  ok('B5: `id` is the RECORD KEY, so a renderer keying rows on it never prints it as the epic',
+    epic.id === 'handoff_epic' && page.id === 'handoff_page' && epic.id !== epic.declared,
+    `${epic.id} vs ${epic.declared}`);
+
+  // ── C · absence and emptiness are stated, never implied ─────────────────────────────────────
+  const absent = H.readLinks(undefined);
+  ok('C1: no argument at all is a successful read of nothing — calm, not an error, not a claim',
+    absent.handoff === false && absent.links.length === 0 && absent.problems.length === 0
+      && absent.empty === false && absent.flow === null && absent.to === null && absent.at === null,
+    JSON.stringify(absent));
+
+  ok('C2: null is answered identically — an initiative with no record is not a fault',
+    JSON.stringify(H.readLinks(null)) === JSON.stringify(absent));
+
+  const plainFile = writeRecord('plain.md', {
+    type: 'Initiative', title: '"plain"', timestamp: '2026-07-29', id: 'plain',
+    lane: 'feature', parent_kr: 'q3-2026:o1:kr2',
+  });
+  const plain = modelOf(plainFile);
+  ok('C3: a record that was never handed off claims nothing — the panel is unchanged for it',
+    plain.handoff === false && plain.empty === false && plain.links.length === 0
+      && plain.problems.length === 0 && plain.systems.length === 0,
+    JSON.stringify({ handoff: plain.handoff, empty: plain.empty }));
+
+  const flowOnlyFile = writeRecord('flow-only.md', {
+    type: 'Initiative', title: '"flow only"', timestamp: '2026-07-29', id: 'flow-only', flow: 'adlc-handoff',
+  });
+  const flowOnly = modelOf(flowOnlyFile);
+  ok('C4: `flow:` declared with no references is a VERIFIED EMPTY (R6) — a stated absence, not a hidden section',
+    flowOnly.handoff === true && flowOnly.empty === true && flowOnly.flow === 'adlc-handoff'
+      && flowOnly.links.length === 0 && flowOnly.problems.length === 0,
+    JSON.stringify({ handoff: flowOnly.handoff, empty: flowOnly.empty }));
+
+  const toOnlyFile = writeRecord('to-only.md', {
+    type: 'Initiative', title: '"to only"', timestamp: '2026-07-29', id: 'to-only', handoff_to: 'atlas app team',
+  });
+  ok('C5: a recipient with no references is the same verified empty — the section still renders',
+    modelOf(toOnlyFile).empty === true && modelOf(toOnlyFile).to === 'atlas app team');
+
+  ok('C6: a declared reference is NOT empty — `empty` means nothing to show, never nothing to say',
+    all.empty === false, String(all.empty));
+
+  // ── D · a malformed declaration is red, with its value verbatim (R7) ────────────────────────
+  const badFile = writeRecord('malformed.md', {
+    type: 'Initiative', title: '"malformed"', timestamp: '2026-07-29', id: 'malformed',
+    flow: '../../../etc/passwd',
+    handoff_epic: 'ATL-482 import wizard epic 3 of 7 done',
+    handoff_at: 'soonish',
+  });
+  const bad = modelOf(badFile);
+
+  ok('D1: `handoff_at: soonish` is a problem with the offending value VERBATIM, and never reaches `at`',
+    bad.at === null && !!problemById(bad, 'handoff_at') && problemById(bad, 'handoff_at').declared === 'soonish'
+      && problemById(bad, 'handoff_at').why.includes('will not guess'),
+    JSON.stringify(problemById(bad, 'handoff_at')));
+
+  ok('D2: an epic carrying whitespace-separated prose is a problem, NOT a link — junk is never dressed as a reference',
+    bad.links.length === 0 && problemById(bad, 'handoff_epic').declared === 'ATL-482 import wizard epic 3 of 7 done',
+    JSON.stringify(bad.links.map((l) => l.declared)));
+
+  ok('D3: a `flow:` that is a path rather than a template name is refused — the "open the file" affordance stays honest',
+    !!problemById(bad, 'flow') && problemById(bad, 'flow').declared === '../../../etc/passwd' && bad.flow === null,
+    JSON.stringify(problemById(bad, 'flow')));
+
+  ok('D4: a malformed reference still names its system, so the ladder can still say what PMOS cannot read',
+    JSON.stringify(bad.systems) === JSON.stringify(['Jira']), JSON.stringify(bad.systems));
+
+  ok('D5: a record that is only malformed is NOT a verified empty — red wins over calm',
+    bad.handoff === true && bad.empty === false && bad.problems.length === 3,
+    JSON.stringify({ empty: bad.empty, problems: bad.problems.length }));
+
+  const emptyVal = H.readLinks({ handoff_epic: '   ', handoff_to: '' });
+  ok('D6: present-but-empty is reported as present-and-empty, not as absent',
+    emptyVal.problems.length === 2 && emptyVal.problems.every((p) => p.why.includes('present but empty'))
+      && emptyVal.problems.every((p) => p.declared === null),
+    JSON.stringify(emptyVal.problems.map((p) => p.id)));
+
+  const nonString = H.readLinks({ handoff_at: 20260720, handoff_epic: ['ATL-1'], handoff_to: { team: 'atlas' } });
+  ok('D7: a value that was never text yields a problem naming the TYPE and a null value — nothing is invented to print',
+    nonString.problems.length === 3 && nonString.problems.every((p) => p.declared === null)
+      && problemById(nonString, 'handoff_at').why.includes('a number')
+      && problemById(nonString, 'handoff_epic').why.includes('an array'),
+    JSON.stringify(nonString.problems.map((p) => `${p.id}=${p.declared}`)));
+
+  const ctrl = H.readLinks({ handoff_epic: 'ATL-\u0007482' });
+  ok('D8: a control character is refused rather than rendered — what it would print is not what the record shows',
+    ctrl.links.length === 0 && !!problemById(ctrl, 'handoff_epic')
+      && problemById(ctrl, 'handoff_epic').why.includes('control character'));
+
+  const wrongShape = H.readLinks(allText);
+  ok('D9: handed the record TEXT instead of its parsed frontmatter, the model states a fault — not a silent empty',
+    wrongShape.handoff === false && wrongShape.problems.length === 1
+      && wrongShape.problems[0].id === 'record' && wrongShape.problems[0].why.includes('a string'),
+    wrongShape.problems[0].why.slice(0, 60));
+
+  ok('D10: a problem carries exactly PROBLEM_FIELDS — no room for a "last checked" beside the reason',
+    [bad, emptyVal, nonString, wrongShape].every((m) => m.problems.every(
+      (p) => JSON.stringify(Object.keys(p)) === JSON.stringify(H.PROBLEM_FIELDS))),
+    JSON.stringify(H.PROBLEM_FIELDS));
+
+  ok('D11: no problem message embeds the offending value — the value is printed once, by `declared`',
+    problemById(bad, 'handoff_at').why.indexOf('soonish') === -1
+      && problemById(bad, 'flow').why.indexOf('passwd') === -1,
+    problemById(bad, 'handoff_at').why.slice(0, 50));
+
+  // ── E · the URL admission table (R5, PRD test 3) ────────────────────────────────────────────
+  const TABLE = [
+    ['https://example.atlassian.net/browse/ATL-482', true, 'an absolute https URL'],
+    ['http://jira.internal/browse/ATL-482', true, 'an absolute http URL'],
+    ['HTTPS://EXAMPLE.ATLASSIAN.NET/browse/ATL-482', true, 'scheme case does not matter'],
+    ['ATL-482', false, 'a bare reference'],
+    ['jira://ATL-482', false, 'a non-http scheme'],
+    ['//evil.example.com/browse/ATL-482', false, 'protocol-relative — inherits whatever scheme the page is on'],
+    ['javascript:alert(1)', false, 'a script URL'],
+    ['data:text/html,<h1>hi</h1>', false, 'a data URL'],
+    ['/planning/prd/thing.md', false, 'a repo-relative path'],
+    ['https://', false, 'a scheme with no host'],
+  ];
+  const admitted = TABLE.map(([v, want]) => {
+    const l = H.readLinks({ handoff_epic: v }).links[0];
+    return !!(l && l.href) === want && (l ? (want ? l.href === v : l.href === null) : false);
+  });
+  ok('E1: the admission table holds — a value is clickable only as an absolute http(s) URL',
+    admitted.every(Boolean),
+    TABLE.filter((_, i) => !admitted[i]).map(([v]) => v).join(' | ') || 'all 10 rows as specified');
+
+  const dangerous = ['javascript:alert(1)', 'data:text/html,<h1>hi</h1>', '//evil.example.com'];
+  ok('E2: a `javascript:`/`data:`/protocol-relative value NEVER reaches an href — it survives only as `declared`',
+    dangerous.every((v) => {
+      const l = H.readLinks({ handoff_epic: v }).links[0];
+      return l.href === null && l.declared === v && collectStrings(l).filter((s) => s === v).length === 1;
+    }));
+
+  const inert = H.readLinks({ handoff_epic: 'ATL-482' }).links[0];
+  ok('E3: a refused value is inert WITH ITS REASON — never silently dropped, never silently dead',
+    inert.href === null && inert.inert_why === H.INERT_WHY && inert.declared === 'ATL-482'
+      && inert.inert_why.includes('will not construct one it was not given'),
+    inert.inert_why);
+
+  ok('E4: an admitted href is byte-identical to the declared value — PMOS links what it was given, nothing else',
+    page.href === page.declared && page.inert_why === null, page.href);
+
+  const rawish = H.readLinks({ handoff_page: 'https://x.example/<script>&"' });
+  ok('E5: values are returned UNESCAPED and verbatim — escaping belongs at the interpolation site, and '
+    + 'a model that pre-escaped could not be checked against the record file',
+    rawish.links[0].declared === 'https://x.example/<script>&"'
+      && rawish.links[0].href === 'https://x.example/<script>&"',
+    rawish.links[0].declared);
+
+  // ── F · STRUCTURAL IMPOSSIBILITY ────────────────────────────────────────────────────────────
+  // A corpus wide enough that the properties below are claims about the module, not about one case.
+  const CORPUS = [
+    ['absent', undefined], ['null', null], ['plain', parseLeadingFrontmatter(fs.readFileSync(plainFile, 'utf8'))],
+    ['all five', parseLeadingFrontmatter(allText)], ['flow only', { flow: 'adlc-handoff' }],
+    ['malformed', parseLeadingFrontmatter(fs.readFileSync(badFile, 'utf8'))],
+    ['empty values', { handoff_epic: '   ', handoff_to: '' }],
+    ['non-string values', { handoff_at: 20260720, handoff_epic: ['ATL-1'] }],
+    ['wrong shape', allText], ['an array', ['handoff_epic']], ['a number', 7], ['a function', () => 1],
+    // The hostile record: a PM (or a well-meaning agent) writes into the record the very things PMOS
+    // cannot know. None of it may reach the model, because none of it is a field the model has.
+    ['hostile', {
+      flow: 'adlc-handoff', handoff_epic: 'ATL-482', handoff_to: 'atlas app team', handoff_at: '2026-07-20',
+      connected: 'true', story_count: '7', stories_done: '3 of 7', synced_at: '12:38',
+      last_checked: '2026-07-29T12:38:00Z', jira_status: 'In Progress', progress: '43%',
+    }],
+    ...TABLE.map(([v]) => [`url:${v}`, { handoff_epic: v }]),
+  ];
+  const MODELS = CORPUS.map(([name, input]) => [name, H.readLinks(input)]);
+
+  const src = fs.readFileSync(path.join(__dirname, 'lib', 'handoff.js'), 'utf8');
+  ok('F1: the module imports NOTHING — with no `require(` there is no fs, no socket and no clock, '
+    + 'so there is no path by which a reading of an external system could enter it',
+    !/\brequire\s*\(/.test(src) && !/\bimport\s*\(/.test(src) && !/^\s*import\s/m.test(src),
+    (src.match(/\brequire\s*\([^)]*\)/g) || []).join(', ') || 'no imports of any kind');
+
+  const CLOCK_OR_IO = [/\bDate\b/, /\bMath\b/, /\bprocess\b/, /\bfetch\s*\(/, /\bsetTimeout\b/,
+    /\bsetInterval\b/, /\bXMLHttpRequest\b/, /\bWebSocket\b/, /\bglobalThis\b/];
+  ok('F2: no clock and no I/O identifier appears in the source — a sync time cannot be formatted by '
+    + 'code that cannot read the time',
+    CLOCK_OR_IO.every((re) => !re.test(src)),
+    CLOCK_OR_IO.filter((re) => re.test(src)).map(String).join(', ') || 'none present');
+
+  const numbers = MODELS.flatMap(([name, m]) => collectPrimitives(m).filter((p) => typeof p === 'number').map((p) => `${name}:${p}`));
+  ok('F3: there is not ONE number anywhere in the model, for any input — a story count, an issue '
+    + 'tally and a progress percentage have no field they could occupy',
+    numbers.length === 0, numbers.join(', ') || `${MODELS.length} inputs, 0 numeric values`);
+
+  const exportedOutputs = [H.whyFor('Jira'), H.stateTextFor('Confluence'), H.NOT_CONNECTED, H.INERT_WHY,
+    H.HANDOFF_KEYS, H.REFERENCE_KEYS, H.LINK_FIELDS, H.PROBLEM_FIELDS, H.RESULT_FIELDS];
+  ok('F4: no export returns a number about anything, external or otherwise',
+    exportedOutputs.every((v) => collectPrimitives(v).every((p) => typeof p !== 'number')),
+    Object.keys(H).join(', '));
+
+  const linkKeys = MODELS.flatMap(([name, m]) => m.links.map((l) => [name, JSON.stringify(Object.keys(l))]));
+  ok('F5: every link carries EXACTLY LINK_FIELDS, in order — a `story_count` or a `synced_at` cannot '
+    + 'be added to a row without failing here',
+    linkKeys.length > 0 && linkKeys.every(([, k]) => k === JSON.stringify(H.LINK_FIELDS)),
+    `${linkKeys.length} links checked against ${JSON.stringify(H.LINK_FIELDS)}`);
+
+  ok('F6: every result carries EXACTLY RESULT_FIELDS, in order — the same lock on the model itself',
+    MODELS.every(([, m]) => JSON.stringify(Object.keys(m)) === JSON.stringify(H.RESULT_FIELDS)),
+    JSON.stringify(H.RESULT_FIELDS));
+
+  ok('F7: every link in every model is `not-connected` — there is no second state and no input reaches one',
+    MODELS.every(([, m]) => m.links.every((l) => l.state === H.NOT_CONNECTED && l.state === 'not-connected')),
+    `${MODELS.reduce((n, [, m]) => n + m.links.length, 0)} links, one state`);
+
+  ok('F8: `connected` is false for every input — including a record that flatly declares it true',
+    MODELS.every(([, m]) => m.connected === false),
+    `${MODELS.length} inputs`);
+
+  // Frozen, so a consumer that would rather the answer were different cannot make it so after the
+  // fact. In strict mode the assignment throws; the assertion is on the value either way.
+  const frozen = MODELS.find(([n]) => n === 'all five')[1];
+  let threw = 0;
+  try { frozen.connected = true; } catch { threw++; }
+  try { frozen.synced_at = '12:38'; } catch { threw++; }
+  try { frozen.links[0].story_count = '3 of 7'; } catch { threw++; }
+  try { frozen.links.push({ kind: 'jira' }); } catch { threw++; }
+  ok('F9: the model is deep-frozen — `connected` cannot be flipped and no fabricated field can be '
+    + 'bolted on downstream',
+    threw === 4 && frozen.connected === false && !('synced_at' in frozen)
+      && !('story_count' in frozen.links[0]) && frozen.links.length === 2,
+    `${threw}/4 mutations refused`);
+
+  /* F10 — THE ANTI-FABRICATION WHITELIST (PRD test 8), and the check the rest of this file exists
+   * to support. Not a denylist of "3 of 7" and "synced": those ban today's fabrication and license
+   * tomorrow's. Every string the model emits for a real record is partitioned against THE RECORD
+   * FILE ITSELF. Whatever is not in the file must be one of the fixed sentences enumerated below —
+   * compared for EQUALITY, so a value that is computed, estimated, tallied or formatted relative to
+   * now lands in that pile and fails immediately, whatever it is and however plausible it looks. */
+  const FIXED_VOCABULARY = [
+    'Jira', 'Confluence', 'jira', 'confluence', 'not-connected',
+    'no Jira credential is configured',
+    'no Confluence credential is configured',
+    'not connected — no Jira credential is configured; this is what the record declares, not a reading',
+    'not connected — no Confluence credential is configured; this is what the record declares, not a reading',
+    'PMOS was given a reference, not a URL, and will not construct one it was not given',
+  ];
+  const notInFile = uniqSorted(collectStrings(all).filter((s) => allText.indexOf(s) === -1));
+  ok('F10: every string the model emits is either VERBATIM from the record file or one of ten fixed '
+    + 'sentences — a value nobody typed has nowhere to hide',
+    JSON.stringify(notInFile) === JSON.stringify(uniqSorted(FIXED_VOCABULARY)),
+    notInFile.filter((s) => FIXED_VOCABULARY.indexOf(s) === -1).map((s) => JSON.stringify(s)).join(', ')
+      || `${collectStrings(all).length} strings, all accounted for`);
+
+  // F10 is only worth anything if it can fail. This proves the partition has teeth before it is
+  // trusted: a fabricated value put through the same computation is caught by it.
+  const fabricated = { links: [{ declared: 'ATL-482', summary: '3 of 7 stories done', synced: 'synced 12:38' }] };
+  ok('F11: the F10 partition demonstrably CATCHES a fabrication — the check has teeth, not just a pass',
+    collectStrings(fabricated).filter((s) => allText.indexOf(s) === -1).sort().join('|') === '3 of 7 stories done|synced 12:38');
+
+  const hostile = MODELS.find(([n]) => n === 'hostile')[1];
+  const hostileStrings = collectStrings(hostile).join('');
+  ok('F12: the hostile record\'s fabricated keys and values reach the model NOWHERE — belt beside '
+    + 'F10\'s braces, and the one denylist in this file, named as one',
+    ['3 of 7', '12:38', '43%', 'In Progress', 'story_count', 'synced_at', 'last_checked']
+      .every((s) => hostileStrings.indexOf(s) === -1)
+      && hostile.connected === false && hostile.links.length === 1,
+    JSON.stringify(hostile.links.map((l) => l.declared)));
+
+  ok('F13: the model is a pure function of its input — two calls are deep-equal, so nothing in it '
+    + 'varies with when it was called',
+    (() => { try { assert.deepStrictEqual(H.readLinks(parseLeadingFrontmatter(allText)), all); return true; } catch { return false; } })());
+
+  ok('F14: no export name suggests an action or a reading PMOS cannot perform',
+    Object.keys(H).every((k) => !/sync|refresh|fetch|poll|count|progress|connect(?!ed)/i.test(k)),
+    Object.keys(H).join(', '));
+
+  // ── G · the real repository, as a corpus check ──────────────────────────────────────────────
+  // The fixtures above were written by this file and agree with it by construction. These records
+  // were written by people who had never heard of this module.
+  const initDir = path.join(__dirname, '..', 'planning', 'initiatives');
+  const realFiles = fs.readdirSync(initDir).filter((f) => f.endsWith('.md') && f !== 'index.md' && f !== 'log.md')
+    .map((f) => path.join(initDir, f));
+  const realModels = realFiles.map((f) => [path.basename(f), modelOf(f)]);
+
+  ok('G1: every real initiative record yields a well-shaped model — no throw, no missing field',
+    realModels.length > 50 && realModels.every(([, m]) => JSON.stringify(Object.keys(m)) === JSON.stringify(H.RESULT_FIELDS)),
+    `${realModels.length} records`);
+
+  ok('G2: not one of them declares a handoff today, so the panel is UNCHANGED for every initiative '
+    + 'in this repository — the feature is additive or it is nothing',
+    realModels.every(([, m]) => m.handoff === false && m.links.length === 0 && m.problems.length === 0 && m.empty === false),
+    realModels.filter(([, m]) => m.handoff).map(([n]) => n).join(', ') || 'none handed off');
+
+  ok('G3: on the real corpus there is still no number, no connection and no unexpected field',
+    realModels.every(([, m]) => m.connected === false && collectPrimitives(m).every((p) => typeof p !== 'number')),
+    `${realModels.length} records, 0 numeric values`);
+} catch (e) {
+  ok('no exceptions during suite', false, e && e.stack ? e.stack.split('\n').slice(0, 2).join(' @ ') : String(e));
+} finally {
+  try { fs.rmSync(TMP, { recursive: true, force: true }); } catch {}
+  const failed = results.filter((r) => !r.cond);
+  console.log(`\n${results.length - failed.length}/${results.length} passed${failed.length ? ' — FAILURES: ' + failed.map((f) => f.name).join('; ') : ''}`);
+  process.exit(failed.length ? 1 : 0);
+}

package/workspace/lib/console-state.js

@@ -222,4 +222,51 @@ function workflow({ root }) {
 
 // ENGINE_PATHS/loadEngine are exported for the packaging guard in workspace/test.js: the incident
 // that made them a list was invisible to every unit test precisely because resolution was inline.
-module.exports = { metrics, radar, workflow, computeMetricsFromRuns, loadJson, loadJsonl, ENGINE_PATHS, loadEngine };
+/* ONE initiative's ladder, derived on demand.
+ *
+ * WHY THIS IS SEPARATE FROM `workflow`. The board caps what it returns (`inFlight`) and reports the
+ * remainder as `hidden` — 12 shown against 93 hidden in this repository. That cap is right for a
+ * board, which is a list of what is in flight. It is wrong for a PANEL, which is asked about one
+ * initiative the PM picked by name: reading the capped list and finding nothing there means "not in
+ * the top twelve", and a panel that renders that as "no initiative record" states something false
+ * about 93 of 105 records. This derives the one that was asked for, so the answer is about the
+ * initiative rather than about its rank.
+ *
+ * It is safe on the request path for the same reason the board is not: this shells git once for the
+ * commit range and runs the engine ONCE, rather than 105 times. `workflow` still owns the board.
+ */
+function ladder({ root, id }) {
+  if (!root) return { ok: false, error: 'no workspace root resolved for the ladder' };
+  if (!id) return { ok: false, error: 'no initiative id given' };
+  const loaded = loadEngine();
+  if (!loaded.ok) return { ok: false, error: loaded.error };
+  const engine = loaded.engine;
+  // ABSENT and BROKEN are different facts and must not share an answer. The engine returns
+  // `ok:false` for BOTH "there is no record with this id" and "the record is there and unreadable",
+  // and collapsing them makes the panel paint a red "read failed" over an initiative that simply
+  // does not exist — overstating a missing file as a fault. The initiative list is the arbiter:
+  // an id the repository does not know is an empty read, and only an id it DOES know can fail one.
+  let known = null;
+  try { known = engine.listInitiatives(root); } catch { known = null; }
+  if (Array.isArray(known) && !known.includes(id)) return { ok: true, empty: true, row: null };
+  let range, row;
+  try { range = engine.commitRange(root); }
+  catch (e) { return { ok: false, error: 'could not resolve the commit range: ' + String((e && e.message) || 'error').slice(0, 120) }; }
+  try { row = engine.computeWorkflow(id, { root, range }); }
+  catch (e) { return { ok: false, error: `could not derive the ladder for ${id}: ` + String((e && e.message) || 'error').slice(0, 160) }; }
+  if (row && row.ok === false) return { ok: false, error: row.error || `the record for ${id} could not be read` };
+  const bi = gitInfo.branchInfo(root);
+  return {
+    ok: true,
+    empty: !row,                        // no such record — distinct from a read that failed
+    row: row || null,
+    scope: {
+      branch: bi.ok ? (bi.current || 'a detached HEAD') : null,
+      branch_error: bi.ok ? null : (bi.error || 'branch could not be read'),
+      commits: range.ok ? range.shas.length : null,
+      empty_range: range.ok ? range.shas.length === 0 : null,
+    },
+  };
+}
+
+module.exports = { metrics, radar, workflow, ladder, computeMetricsFromRuns, loadJson, loadJsonl, ENGINE_PATHS, loadEngine };

package/workspace/lib/drive-guard.js

@@ -0,0 +1,98 @@
+'use strict';
+/* drive-guard — the driver's ONLY write path (pmos-autonomous-drive-build, R9).
+ *
+ * THE PROBLEM THIS EXISTS FOR, stated plainly because it is easy to under-rate:
+ * nothing in PMOS checks an identity. `/api/gate` sets `pm: true` unconditionally
+ * (workspace/server.js). Every gate the corpus calls "the PM's" — D16's contract approval, D12's
+ * acceptance, D60's disposition — is, mechanically, A FILE WITH THE RIGHT WORDS IN IT. An
+ * autonomous writer can satisfy all of them by writing. If it can, the PM's gate structure is
+ * decorative and the whole three-tier eval gate is theatre.
+ *
+ * The harness already knows how to make a declaration falsifiable and did not apply it here: O7
+ * validates `priors` ids against the corpus, so a fabricated citation FAILS — while O5's
+ * `PM_approved` is a bare boolean, so a fabricated approval PASSES. This module is the smallest
+ * honest answer available to code: the driver cannot write those records because the only writer it
+ * has REFUSES them.
+ *
+ * WHY REFUSAL AND NOT OMISSION. A driver that simply never calls the acceptance writer is one
+ * prompt away from calling it. The rubric's veto dimension asks for structural incapability and
+ * says so: "a code path that merely omits them fails this dimension". So the guard is a chokepoint
+ * that throws, and the tests ATTEMPT each forbidden write and assert the throw. A rule the driver
+ * is trusted to follow is exactly what leg A showed cannot be trusted.
+ *
+ * SCOPE, honestly. This binds the DRIVER, not the repo: a human, another agent, or a careless
+ * `fs.writeFileSync` elsewhere is unaffected. It is a seatbelt on one vehicle, not a law of
+ * physics — and that limit is the argument for making O5's boolean falsifiable at the engine, which
+ * is a separate initiative this one does not pretend to have done.
+ */
+
+const path = require('path');
+
+class ForbiddenWrite extends Error {
+  constructor(what, detail) {
+    super(`drive-guard: refused to write ${what} — ${detail}`);
+    this.name = 'ForbiddenWrite';
+    this.what = what;
+  }
+}
+
+/** Ledgers that record a human decision. The driver may never append to these. */
+const FORBIDDEN_FILES = Object.freeze(['acceptances.jsonl']);
+
+/** Disposition tokens (D60). Case-insensitive; a status carrying one is a PM act. */
+const DISPOSITION_RE = /\b(PROMOTED|ITERATE[D]?|KILLED)\b/i;
+
+/** True when `value` contains a truthy PM_approved anywhere in its object graph. */
+function carriesApproval(value, depth = 0) {
+  if (depth > 8 || value === null || typeof value !== 'object') return false;
+  for (const [k, v] of Object.entries(value)) {
+    if (k === 'PM_approved' && v === true) return true;
+    if (k === 'pre_run_contract' && v && typeof v === 'object' && v.PM_approved === true) return true;
+    if (carriesApproval(v, depth + 1)) return true;
+  }
+  return false;
+}
+
+/**
+ * The chokepoint. Every driver write goes through here or does not happen.
+ * @param {{file:string, payload?:any, text?:string}} req
+ * @throws {ForbiddenWrite}
+ */
+function assertWritable(req) {
+  const file = (req && req.file) || '';
+  const base = path.basename(file);
+
+  if (FORBIDDEN_FILES.includes(base)) {
+    throw new ForbiddenWrite('an acceptance', 'the Acceptance Gate is the PM\'s and non-delegable (D12)');
+  }
+  if (req && req.payload !== undefined && carriesApproval(req.payload)) {
+    throw new ForbiddenWrite('pre_run_contract.PM_approved',
+      'the contract is the PM\'s to approve before any build (D16, AGENTS.md §4)');
+  }
+  if (req && typeof req.text === 'string' && /PM_approved\s*[:=]\s*true/i.test(req.text)) {
+    throw new ForbiddenWrite('pre_run_contract.PM_approved',
+      'the contract is the PM\'s to approve before any build (D16) — caught in raw text');
+  }
+
+  // A disposition is a PM act (D60) wherever it lands: the record's `status:` is where it is
+  // conventionally written, so both the structured and the raw-text shapes are refused.
+  const status = req && req.payload && typeof req.payload === 'object' ? req.payload.status : null;
+  if (typeof status === 'string' && DISPOSITION_RE.test(status)) {
+    throw new ForbiddenWrite('a disposition', 'promote/iterate/kill is the PM\'s (D60 step 7)');
+  }
+  if (req && typeof req.text === 'string' && /^status:.*$/im.test(req.text)
+      && DISPOSITION_RE.test(req.text.match(/^status:.*$/im)[0])) {
+    throw new ForbiddenWrite('a disposition', 'promote/iterate/kill is the PM\'s (D60 step 7)');
+  }
+  return true;
+}
+
+/** Wrap a writer so it cannot be called with a forbidden payload. The driver is given ONLY this. */
+function guardedWriter(write) {
+  return function guarded(req) {
+    assertWritable(req);
+    return write(req);
+  };
+}
+
+module.exports = { assertWritable, guardedWriter, carriesApproval, ForbiddenWrite, FORBIDDEN_FILES };