create-pmos 0.12.1 → 0.14.0

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",