create-pmos 0.13.0 → 0.14.0

package/README.md

@@ -333,6 +333,26 @@ Refreshes the skills, concepts, and scripts only. Your records — `state/`, `pl
 `okf/product/` — are yours, and an update never touches them. `pmos/KIT-VERSION` always says
 exactly what you're running.
 
+## What's new in 0.14.0
+
+**The foundation of an autonomous workflow driver lands in the workspace.** Two new libraries
+(`workspace/lib/drive-plan.js` + `drive-guard.js`) give the workflow loop a head and a conscience:
+
+- **A planner that knows when to stop.** The workflow ladder never returns "nothing left to do" —
+  it always names a next honest action, so a naive `while (next)` loop never exits. The planner
+  decides `dispatch` vs `stop` on three explicit triggers: **human-gate** (the next step is a PM
+  decision — a contract or an acceptance), **no-progress** (the same next action twice running means
+  the last dispatch moved nothing — a stop, not a retry), and **budget** (a hard ceiling so an
+  unforeseen case still terminates).
+- **A guard that can't sign the PM's name.** A gate in PMOS is "a file with the right words in it,"
+  which an autonomous writer could satisfy. The guard is the driver's *only* write path and refuses
+  to write acceptances, a `PM_approved` flag (at any nesting depth, or smuggled as raw text), or a
+  disposition token — so the loop can advance work but can never self-approve past a human gate.
+
+This is the planner + guard (14 tests cover them); the return path, an independent verify pass, and
+a live board run are the next increments under the same contract. Run `npx create-pmos@latest
+workspace` to pick it up — the workspace version bump means an existing install auto-upgrades.
+
 ## What's new in 0.13.0
 
 **Six more skills now travel with the kit** — the allowlist had been shipping dangling references to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → lane-fit spec → contract → build → three gates, with work-type lanes for features, research, maintenance, incidents, and content) entirely inside your own repo, with all state as git-versioned files. `create-pmos workspace` also installs + launches the local Terminal Workspace GUI. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@2374d99
+kernel-source: pmos@e847ceb
 assembled: 2026-07-29
 mode: vendor

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 };

package/workspace/lib/drive-plan.js

@@ -0,0 +1,97 @@
+'use strict';
+/* drive-plan — the autonomous drive's decision function (pmos-autonomous-drive-build, R1/R2/R10).
+ *
+ * PURE. Given a ladder (scripts/workflow-state.js `<id> --json`) and the loop's own memory, decide
+ * whether to dispatch the next step or stop. No I/O, no clock, no spawning — so every rule below is
+ * testable without a PTY, which is the point: the rules are the risky part, not the plumbing.
+ *
+ * WHY A TERMINATION RULE EXISTS AT ALL. The engine's `next` is NEVER null — measured across the
+ * board, 0 of 25 sampled initiatives return one. It always names something, because there is always
+ * a next honest action even on finished work. So `while (next) dispatch()` never exits. The counter
+ * cannot tell the driver when to stop, and the driver must decide for itself. That is R2, and it is
+ * the difference between a loop and a runaway.
+ *
+ * THE THREE STOPS (R2), in the order they are checked:
+ *   1. human-gate  — the next action is a decision, not work. D16 contract, D12 acceptance.
+ *   2. no-progress — the same next action twice running. A step that did not move the ladder will
+ *                    not move it by being run again; retrying is how a loop burns a budget looking
+ *                    busy. NO PROGRESS IS A STOP, NOT A RETRY.
+ *   3. budget      — a hard ceiling, so a case nobody predicted still terminates.
+ *
+ * The driver never writes anything from here. Deciding and writing are separate on purpose — see
+ * drive-guard.js, which is what makes the human-gate stop structural rather than merely intended.
+ */
+
+/** Ladder steps whose next action is a HUMAN decision the driver may never take (R9/R10).
+ *  `contract` is D16 (no build begins without PM approval); `accept` is D12 (non-delegable).
+ *  Deliberately NOT here: `review` (an evaluator agent scores it) and `quality` (CI decides). */
+const HUMAN_GATES = Object.freeze(['contract', 'accept']);
+
+/** A disposition is the PM's (D60) and is recorded on the initiative record rather than as a
+ *  ladder step, so it cannot appear as `next.step`. Named for the guard, which does enforce it. */
+const HUMAN_RECORDS = Object.freeze(['disposition', 'acceptance', 'pre_run_contract.PM_approved']);
+
+const DEFAULT_BUDGET = 12;
+
+/**
+ * @param {object} ladder  parsed `workflow-state.js <id> --json`
+ * @param {object} memory  { steps: number, lastKey: string|null }  the loop's own history
+ * @param {object} [opts]  { budget?: number }
+ * @returns {{action:'dispatch'|'stop', reason:string, step?:string, why?:string, detail:string}}
+ */
+function plan(ladder, memory, opts) {
+  const budget = (opts && Number.isFinite(opts.budget)) ? opts.budget : DEFAULT_BUDGET;
+  const mem = memory || { steps: 0, lastKey: null };
+
+  // An unreadable ladder is a stop, never a guess. The engine reports `ok:false` when it cannot
+  // derive; proceeding on that would be inventing state, which R1 forbids.
+  if (!ladder || ladder.ok === false) {
+    return { action: 'stop', reason: 'unreadable',
+      detail: 'the ladder could not be derived — the driver never invents state (R1)' };
+  }
+
+  // Accepted work is finished work. Checked before `next`, which still names an action even here.
+  if (ladder.accepted) {
+    return { action: 'stop', reason: 'complete',
+      detail: `${ladder.id} has a recorded acceptance — nothing further is owed` };
+  }
+
+  const next = ladder.next;
+  if (!next || !next.step) {
+    return { action: 'stop', reason: 'no-next',
+      detail: 'the ladder named no next step (unexpected — `next` is normally never null)' };
+  }
+
+  // 1. HUMAN GATE. The decision is the PM's; the driver stops and names what is owed.
+  if (HUMAN_GATES.includes(next.step)) {
+    return { action: 'stop', reason: 'human-gate', step: next.step, why: next.why,
+      detail: `${next.step} is the PM's decision — ${next.why || 'no reason given'}` };
+  }
+
+  // 2. NO PROGRESS. Same step + same reason as last iteration means the previous dispatch changed
+  //    nothing the engine can see. Running it again is not a retry, it is the same failure twice.
+  const key = `${next.step}::${next.why || ''}`;
+  if (mem.lastKey && mem.lastKey === key) {
+    return { action: 'stop', reason: 'no-progress', step: next.step, why: next.why,
+      detail: `'${next.step}' is unchanged after a dispatch — stopping rather than retrying` };
+  }
+
+  // 3. BUDGET. Checked last so a genuine human-gate or no-progress stop is reported as itself
+  //    rather than masked by an exhausted counter.
+  if (mem.steps >= budget) {
+    return { action: 'stop', reason: 'budget', step: next.step,
+      detail: `step budget of ${budget} exhausted — refusing to continue silently (R13)` };
+  }
+
+  return { action: 'dispatch', reason: 'next-action', step: next.step, why: next.why,
+    detail: next.action || `advance '${next.step}'` };
+}
+
+/** Fold a decision into the loop's memory. Pure; the caller owns the value. */
+function remember(memory, decision) {
+  const mem = memory || { steps: 0, lastKey: null };
+  if (!decision || decision.action !== 'dispatch') return mem;
+  return { steps: mem.steps + 1, lastKey: `${decision.step}::${decision.why || ''}` };
+}
+
+module.exports = { plan, remember, HUMAN_GATES, HUMAN_RECORDS, DEFAULT_BUDGET };

package/workspace/package.json

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