create-pmos 0.26.0 → 0.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Scaffold the PMOS portable kit \u2014 run the PMOS product-management workflow (initiative \u2192 lane-fit spec \u2192 contract \u2192 build \u2192 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. Includes `workflow-sweep`, which audits the state every board derives from and separates real defects from work you simply have not done. `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@6f4c86b
-assembled: 2026-07-31
+kernel-source: pmos@86ae610
+assembled: 2026-08-02
 mode: vendor

package/workspace/README.md

@@ -17,7 +17,13 @@ true terminal emulator on the other end. The CLI runs **untouched** — its own
 subscription included), slash commands, keybindings. The workspace is the terminal, not a wrapper.
 
 ## Everything survives a session
-The server holds PTYs in memory and mirrors each session's scrollback + metadata to `state/`.
+The server holds PTYs in memory and mirrors each session's scrollback + metadata to the runtime
+state directory — **`~/Library/Application Support/pmos` on macOS**, `$XDG_STATE_HOME/pmos` or
+`~/.local/state/pmos` elsewhere, `PMOS_STATE_DIR` overriding both. It is deliberately OUTSIDE the
+app directory: sessions, the workspace registry, layouts, scratchpads, schedules and your authored
+skills used to live at `workspace/state/`, inside the directory the test suite runs from, and were
+twice destroyed by a test. An existing in-repo `state/` is moved there once, on first run; two
+populated directories are never merged (you get told, and nothing moves).
 Close/reload the client → re-attach replays scrollback and the run continues (detach, not kill).
 Restart the server → prior sessions reload as `exited` with full history and one-click respawn.
 
@@ -123,12 +129,16 @@ would be the watermelon this repo has a word for.
 clear the matching needs entry — only ever on your click.
 
 **The record lands in the repo that earned it.** Each workspace resolves its own state dir —
-`pmos/state/` (the kit's layout, D54), then `state/`, then `.pmos/`; the home workspace uses the
-server's own `state/`. A PMOS-shaped repo with no state dir yet gets the kit layout on first
-write. That path matters: `scripts/metrics.py` reads `pmos/state/acceptances.jsonl` for the north
-star and κ, so an acceptance recorded anywhere else is a green click over an empty record. A
-plain (non-PMOS) repo has no layout to invent — the gate records into the server's `state/` and
-the response says `fallback: true` rather than guessing.
+`pmos/state/` (the kit's layout, D54), then `state/`, then `.pmos/`; an embedded PMOS-self checkout
+with none of those yet uses the install's own `workspace/state/`. A PMOS-shaped repo with no state
+dir yet gets the kit layout on first write. That path matters: `scripts/metrics.py` reads
+`pmos/state/acceptances.jsonl` for the north star and κ, so an acceptance recorded anywhere else is
+a green click over an empty record. A plain (non-PMOS) repo has no layout to invent — the gate
+records into `workspace/state/` and the response says `fallback: true` rather than guessing.
+
+This is D64's **system of record** and it did **not** follow the runtime state out to the per-user
+directory above. A record belongs to the repository that earned it; only the churny, machine-written
+runtime moved.
 
 Records carry the kit's `accepted` field (`accept` → true, `return` → false) so file-mode metrics
 count them. `pm_label` is **never** derived from a click — κ labels are the PM's own word (D40).

package/workspace/bin/pmos.js

@@ -28,9 +28,13 @@ const fs = require('fs');
 const path = require('path');
 const { spawn, spawnSync } = require('child_process');
 const D = require('../lib/server-discovery');
+const stateRoot = require('../lib/state-root');
 
 const WS = path.resolve(__dirname, '..');              // workspace/
-const STATE = path.join(WS, 'state');
+// The launcher and the server must agree on WHERE state is, or the launcher looks for pid files in
+// a directory nothing writes to and starts a second server every time. Same resolver, same answer
+// — including the one-time migration out of the app directory (lib/state-root.js).
+const STATE = stateRoot.resolveStateRoot({ env: process.env, legacy: path.join(WS, 'state') }).root;
 // An explicit PMOS_WS_PORT is a PIN: this launcher then talks to that port and no other. Without
 // one, the port comes from discovery — the default first, then whatever the running servers
 // recorded for themselves.

package/workspace/doctor.js

@@ -124,7 +124,11 @@ function binaryArch(file) {
   //    when none is running, whether the port it would use is free and who holds it if not.
   {
     const D = require('./lib/server-discovery');
-    const STATE = path.join(__dirname, 'state');
+    const stateRoot = require('./lib/state-root');
+    // The same resolver the server and the launcher use — a doctor that looked in the app
+    // directory would report "not running" over a live workspace (lib/state-root.js). No migration
+    // is triggered from here: a diagnostic must not move the PM's files.
+    const STATE = stateRoot.defaultRoot({ env: process.env });
     const pinned = process.env.PMOS_WS_PORT ? Number(process.env.PMOS_WS_PORT) : null;
     const ports = D.candidatePorts({ stateDir: STATE, pinned });
     const probe = (port) => new Promise((res) => {

package/workspace/lib/skill-store.js

@@ -96,10 +96,173 @@ function loadSkills(dirs) {
   return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
 }
 
+/* ── THE FILING CONTRACT OF A SKILL THAT ALREADY EXISTS ────────────────────────────────────────
+ *
+ * Every skill scaffolded before the runtime state moved out of the application directory says, in
+ * its body, "write the deliverable to `workspace/state/deliverables/<run-id>.md` and append to
+ * `workspace/state/needs.json`". After the move those are two paths nothing reads. An agent that
+ * follows them succeeds, reports success, and the deliverable never appears in the needs-you queue
+ * — a REPORT THAT SILENTLY NEVER ARRIVES, which is the exact failure this initiative exists to
+ * end. The PM has eleven such skills (draft-me, release-notes and nine idpf-*), all authored
+ * against the old contract.
+ *
+ * Injecting the paths into the SCAFFOLD only fixes skills that do not exist yet. So the retarget
+ * also happens at FIRE TIME, to the prompt as it is handed to the session — which covers the
+ * eleven, covers a skill hand-copied from an old machine, and covers a file the PM edits back to
+ * the old wording. It also has to be per-fire rather than a one-off rewrite of the files, because
+ * `needs.json` is resolved PER WORKSPACE (server.js#needsFileFor): one skill fired against two
+ * repos files into two different queues, and a path baked into the file could only ever name one.
+ *
+ * ── WHAT COUNTS AS "THE OLD STATE ROOT" ───────────────────────────────────────────────────────
+ *
+ * The first cut of this matched on the CHARACTER BEFORE the path — start-of-line, whitespace, a
+ * quote, a backtick, a paren or a bracket — and that covered 2 of the PM's 11 skills. The other
+ * nine (every idpf-*) do not spell the path relatively at all; they spell it ABSOLUTELY:
+ *
+ *     /Users/…/pmos/workspace/state/deliverables/<run-id>.md
+ *
+ * The character before `workspace/state/` there is `/`, which was not in the class, so nothing
+ * matched and nothing was rewritten. That is not an edge case: every one of the PM's 45 schedules
+ * fires an idpf-* skill, and the two skills the old rule DID repair have zero schedules between
+ * them. A near-miss on a character class was therefore 0% coverage of the real workload.
+ *
+ * So the question is no longer "what character precedes this" but "IS THIS PATH'S PARENT THE OLD
+ * RUNTIME STATE ROOT". We answer it by recovering the whole path token and asking about its
+ * DIRECTORY, which is decidable regardless of how the author chose to spell it:
+ *
+ *   `state/…`  `./state/…`                     — relative to the app directory
+ *   `workspace/state/…`  `./workspace/state/…`  — relative to a repository root
+ *   `/any/abs/path/workspace/state/…`           — absolute, any install (the nine idpf-*)
+ *   `<filing.legacy>/…`                         — the app directory's OWN state dir, derived by the
+ *                                                 caller from __dirname, whatever it is named
+ *
+ * And it must still leave `pmos/state/…` alone — D64's file-mode system of record, which did NOT
+ * move. That now falls out STRUCTURALLY rather than from a character class: `pmos/` is a directory
+ * segment that is neither `workspace/` nor the derived legacy root, so it is refused by the same
+ * test that accepts the others. `sched-state/deliverables` is refused for the same reason — the
+ * `state` we rewrite has to be a whole path segment, not the tail of a longer name.
+ */
+
+/* ── WHY THE WALK-BACK HAS TO KNOW ABOUT SCHEMES AND BOUNDARIES ────────────────────────────────
+ *
+ * The rule above ("is this path's parent the old runtime state root") is answered by recovering the
+ * whole path token and asking about its directory. Recovering it by walking LEFT through path
+ * characters is right, but a walk-back that stops at the first non-path character does not know
+ * WHAT it stopped at — and three of the things it can stop at mean the text to the right is not a
+ * path token at all but the tail of something larger:
+ *
+ *     https://example.com/workspace/state/deliverables/x.md   stops at `:` → `https:` + the rewrite
+ *     C:/Users/x/workspace/state/deliverables/x.md            stops at `:` → `C:` + the rewrite
+ *     C:\Users\x\workspace/state/deliverables/x.md            stops at `\`
+ *
+ * In each of those the URL or the drive path is DESTROYED, not merely over-rewritten — and this is
+ * not confined to fire time: POST /api/skills and /api/skills/draft run scaffoldSkill, which
+ * retargets the body and PERSISTS it, so a PM pasting a body containing such a URL gets it mangled
+ * on disk. So the character that STOPPED the walk-back is itself part of the decision: the token is
+ * only a path when what precedes it is a real boundary (start of text, whitespace, a quote, a
+ * bracket, a comma). A `:`, a `\`, a `?`, a `&`, an `=` or an `@` means we are inside a larger
+ * token whose grammar this module does not know, and the only safe answer is to leave it alone.
+ *
+ * The same defect in the other direction is the TAIL: `needs.json` carried no trailing boundary
+ * where `deliverables` did, so `workspace/state/needs.jsonl` matched `…needs.json` and left a
+ * dangling `l` on the rewritten path. Both alternatives now end on the same boundary class.
+ *
+ * ── AND: A `workspace/` DIRECTORY IS NOT AUTOMATICALLY A PMOS INSTALL ─────────────────────────
+ *
+ * `…/notes/workspace/state/deliverables/` has the same SHAPE as the old root and is not it. For an
+ * ABSOLUTE path we can simply look, and the three answers are all different:
+ *
+ *   absent from this machine  → ACCEPT. A path that no longer exists is the case the retarget was
+ *                               written for: a skill authored on an older checkout or another
+ *                               machine, naming a directory that has since moved. Refusing here
+ *                               would restore the silent no-show for exactly the bodies that need
+ *                               the rewrite most.
+ *   present and a PMOS workspace → ACCEPT. Another checkout of this application; its `state/` is
+ *                               the old root by construction.
+ *   present and something else  → REFUSE. Somebody's `workspace/` folder, not ours.
+ *
+ * A RELATIVE path cannot be resolved without a working directory, so only the two spellings the
+ * scaffold and the PM's skills actually use are accepted (`workspace/state/…`, `./workspace/…`).
+ * A deeper relative prefix (`example.com/workspace/`, `../workspace/`) is refused: it is either not
+ * a path at all or not one this module can judge.
+ */
+
+// The tail: `state/deliverables` or `state/needs.json`. Everything to its LEFT is recovered by
+// walking back through path characters, not by a lookbehind — a path token can be arbitrarily long
+// and we need the whole of it to judge the directory. BOTH alternatives end on the boundary class:
+// without it `state/needs.jsonl` rewrote to `<needs>l`.
+const TAIL_END = "(?=$|[/`'\")\\],\\s])";
+const LEGACY_TAIL = new RegExp(`state\\/(?:needs\\.json${TAIL_END}|deliverables${TAIL_END})`, 'g');
+const PATH_CHAR = /[A-Za-z0-9_.~/-]/;
+// What may sit immediately LEFT of a whole path token. Deliberately an allow-list: `:` (a URL
+// scheme, a Windows drive), `\`, `?`, `&`, `=`, `@`, `#` and every other character are refused,
+// because they mean the walk-back stopped inside a larger token rather than at its start.
+const TOKEN_BOUNDARY = /[\s`'"([{<,;|>]/;
+
+/** Absent → true (unknowable, and the stale-path case this rewrite exists for); else: is it ours? */
+function isPmosWorkspaceDir(dir) {
+  try {
+    if (!fs.existsSync(dir)) return true;
+    let name = '';
+    try { name = String((JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')) || {}).name || ''); }
+    catch { /* no package.json, or not JSON — fall through to the shape check */ }
+    if (name === 'pmos-workspace') return true;
+    return fs.existsSync(path.join(dir, 'server.js')) && fs.existsSync(path.join(dir, 'lib', 'skill-store.js'));
+  } catch { return true; }   // a directory we cannot even stat is not evidence AGAINST the rewrite
+}
+
+/** Is `prefix` (the text immediately left of `state/…`, up to a non-path character) the old root? */
+function isLegacyStateParent(prefix, legacyRoot) {
+  // `state` must be a WHOLE segment: either the token starts here, or its parent ends in a slash.
+  if (prefix !== '' && !prefix.endsWith('/')) return false;
+  if (prefix === '' || prefix === './') return true;                   // state/… · ./state/…
+  if (prefix === 'workspace/' || prefix === './workspace/') return true;   // the relative spelling
+  // The app directory's own state dir, derived by the caller from __dirname. Covers an install
+  // that does not sit under a directory literally named `workspace`. Checked BEFORE the probe, so
+  // the install we are running inside is never subject to it.
+  if (legacyRoot) {
+    const parent = legacyRoot.slice(0, legacyRoot.lastIndexOf('/') + 1);
+    const name = legacyRoot.slice(legacyRoot.lastIndexOf('/') + 1);
+    if (name === 'state' && parent && (prefix === parent || prefix === '.' + parent)) return true;
+  }
+  // …/workspace/state/… — absolute only (`//host/…` is an authority, not a path), and only when
+  // that `workspace` is, or plausibly was, a PMOS install.
+  if (prefix.startsWith('/') && !prefix.startsWith('//') && prefix.endsWith('/workspace/')) {
+    return isPmosWorkspaceDir(prefix.slice(0, -1));
+  }
+  return false;
+}
+
+/**
+ * Rewrite every reference to the OLD runtime state root onto the paths this fire actually files to.
+ * `filing` is `{ deliverables, needs, legacy? }`; `legacy` is the application directory's own
+ * `state/` (server.js#LEGACY_STATE) and is optional — the segment rules above stand without it.
+ */
+function retargetFiling(text, filing) {
+  if (!text || !filing) return text;
+  const legacyRoot = filing.legacy ? String(filing.legacy).replace(/\/+$/, '') : '';
+  const src = String(text);
+  let out = ''; let cursor = 0; let m;
+  LEGACY_TAIL.lastIndex = 0;
+  while ((m = LEGACY_TAIL.exec(src))) {
+    let start = m.index;
+    while (start > 0 && PATH_CHAR.test(src[start - 1])) start--;
+    if (start < cursor) continue;                       // overlaps a rewrite already emitted
+    // The character that STOPPED the walk-back decides whether we recovered a whole path token or
+    // the tail of a URL / a drive path / a query parameter. See the block comment above.
+    if (start > 0 && !TOKEN_BOUNDARY.test(src[start - 1])) continue;
+    const target = m[0].startsWith('state/needs') ? filing.needs : filing.deliverables;
+    if (!target || !isLegacyStateParent(src.slice(start, m.index), legacyRoot)) continue;
+    out += src.slice(cursor, start) + target;
+    cursor = m.index + m[0].length;
+  }
+  return out + src.slice(cursor);
+}
+
 // Scaffold a well-formed user skill file from the New Skill flow's fields. Returns { ok, slug, content }
 // or { ok:false, error }. User skills default to run:agent — a user-authored skill reasons through a
 // claude session (the existing agent path); the deterministic fast-path is reserved for the built-ins.
-function scaffoldSkill({ name, description, output, body } = {}) {
+function scaffoldSkill({ name, description, output, body, filing } = {}) {
   const slug = slugify(name);
   if (!NAME_RE.test(slug)) return { ok: false, error: 'name must be a short slug (letters, digits, hyphens)' };
   const label = titleCase(name) || slug;
@@ -107,7 +270,9 @@ function scaffoldSkill({ name, description, output, body } = {}) {
   let out = Array.isArray(output) ? output : String(output || '').split(/[\n,]/);
   out = out.map((x) => String(x).replace(/\s+/g, ' ').trim()).filter(Boolean).slice(0, MAX_OUTPUT);
   if (!out.length) out = ['Summary', 'Findings', 'Next steps'];   // always a valid contract
-  const proc = String(body || '').trim() || defaultBody(label, desc, out, slug);
+  // A hand-written body is retargeted too: a PM pasting the old contract text in gets a skill that
+  // files where the console reads, not one that quietly writes into a directory nobody opens.
+  const proc = retargetFiling(String(body || '').trim(), filing) || defaultBody(label, desc, out, slug, filing);
   const content = [
     '---',
     `name: ${slug}`,
@@ -131,8 +296,16 @@ function scaffoldSkill({ name, description, output, body } = {}) {
 // write the deliverable and append a STRUCTURED needs.json object, or the console reds the queue
 // (needsResult treats a non-array queue as corrupt). No prose "note to needs-you", ever. This is a
 // starting shape a PM or the AI-draft session then sharpens with the task's real steps.
-function defaultBody(label, desc, out, slug) {
+// `filing` names the two paths the run must write to. They are INJECTED, not hard-coded, because
+// the workspace's runtime state no longer lives at a path that can be spelled relative to a
+// repository — it moved out of the application directory (lib/state-root.js) precisely so the test
+// suite could not reach it. A scaffold that still said "workspace/state/deliverables/" would send
+// every scheduled agent's report to a directory the console never reads: a silent, permanent
+// no-show in the needs-you queue. The defaults keep this module usable standalone.
+function defaultBody(label, desc, out, slug, filing) {
   const id = slug || slugify(label) || 'run';
+  const deliverables = (filing && filing.deliverables) || 'workspace/state/deliverables';
+  const needs = (filing && filing.needs) || 'workspace/state/needs.json';
   return [
     `You are running the "${label}" skill in this PMOS workspace (local, file mode). Work only from`,
     "this repository's own files, git, and CLIs — no network (D54).",
@@ -148,8 +321,8 @@ function defaultBody(label, desc, out, slug) {
     '   An empty section is the literal line "None this period." — never a dropped heading, never invented content.',
     '   Done when: every contract section is filled or explicitly "None this period.".',
     `3. File the result so the PM sees it. Pick a unique run id (e.g. \`${id}-<UTC-timestamp>\`), then:`,
-    '   a. Write the deliverable Markdown to `workspace/state/deliverables/<run-id>.md`.',
-    '   b. Read `workspace/state/needs.json` (treat a missing file as `[]`), append EXACTLY this object,',
+    `   a. Write the deliverable Markdown to \`${deliverables}/<run-id>.md\`.`,
+    `   b. Read \`${needs}\` (treat a missing file as \`[]\`), append EXACTLY this object,`,
     '      and write the whole array back — it MUST stay a valid JSON array or the console reds the queue:',
     `      {"run_id":"<run-id>","kind":"report","initiative_id":"${id}","question":"${label} — ready","deliverable":"<run-id>"}`,
     '   Done when: the deliverable file exists and needs.json is a valid array containing the new object.',
@@ -159,4 +332,5 @@ function defaultBody(label, desc, out, slug) {
   ].join('\n');
 }
 
-module.exports = { NAME_RE, slugify, titleCase, parseSkill, loadDir, loadSkills, scaffoldSkill };
+module.exports = { NAME_RE, slugify, titleCase, parseSkill, loadDir, loadSkills, scaffoldSkill,
+  retargetFiling, isLegacyStateParent };