create-pmos 0.26.0 → 0.28.0

package/README.md

@@ -333,6 +333,32 @@ 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.28.0
+
+**`search everything…` now searches every file in the folder, and any file it finds opens in a tab.**
+Run `npx create-pmos@latest workspace`; the version bump means an existing install auto-upgrades.
+
+- **The box searched three lists, and the folder was not one of them.** It matched initiative slugs,
+  paths *declared on* an initiative record, and session names — so a file PMOS had never been told
+  about could not be found by typing its exact name. Worse, the miss read *"nothing matches — a
+  successful read of nothing"*, which is the phrase for *we looked and there was nothing there*,
+  printed after a search that never opened the folder.
+- **Type any part of a name or a path.** Every file under the workspace root now matches, at any
+  depth, whether or not any record mentions it — `README.md`, a script, a CSV you dropped in
+  yesterday. `node_modules/`, `dist/`, `.git/` and the other junk directories are skipped, exactly as
+  the folder lens already skips them, so search and the file tree agree about what is in there.
+- **Type a phrase that is *inside* a file.** Text files are searched by content too, and the result
+  names the file **and the line**, so you can see the match before you open anything.
+- **Click a result and it opens in a document tab** — the same reader you already use, with `view` ·
+  `raw` · `edit` · `diff`. A file the reader cannot show (an image, a binary) is still listed, greyed,
+  and says so, instead of opening a tab onto a failure.
+- **It works in every mode.** The search box was rendered in all seven and did something in exactly
+  one — including doing nothing in the library lens, the one screen that lists files.
+- **It tells you what it did not look at.** The walk is bounded so a huge folder can never hang the
+  box, and any bound that actually bit is stated in the heading. `11 of 1424 searched` is a
+  different sentence from `BOUNDED — files beyond the walk limit were not looked at`, and you get
+  whichever one is true. Nothing leaves your machine, as ever.
+
 ## What's new in 0.26.0
 
 **Your sessions now know which initiative they belong to — whatever branch you are on — and each

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.26.0",
+  "version": "0.28.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@d333cd5
+assembled: 2026-08-04
 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).
@@ -146,6 +156,28 @@ tokens, JWTs, `Authorization:` values, api keys): scrollback holds whatever the
 so D08's never-log-headers discipline applies to what this hands back. Matching runs against
 the *scrubbed* text, so the endpoint cannot be used to grep a secret out.
 
+## `search everything…` searches the folder (the file lens)
+The search box shipped matching three derived lists — initiative slugs, paths **declared on** an
+initiative record, and session names — so a file PMOS had never been told about could not be found
+by typing its exact name, and the miss printed *"nothing matches — a successful read of nothing"*
+after a search that had never opened the folder.
+
+`GET /api/search/files?q=…&ws=…&limit=…` is the folder corpus: every file under the workspace root,
+matched by **path** and by **content**, with the matching line and its number. Clicking a hit opens
+it in the ordinary document tab. It is a **different corpus** from `/api/search` above — that one is
+scrollback, this one is disk — and they are deliberately separate endpoints, because their hits
+share no field and one payload would have to lie about what it looked at.
+
+Three guarantees. The walk uses the **folder lens's own rules** (`node_modules`, `dist`, `.git` and
+the rest skipped, dotted names excluded), so search and the file tree can never disagree about what
+is in the folder. There is **no path parameter** — the query is a needle, not a location — and the
+walk starts at the root and never follows a symlink out of it, so nothing becomes reachable that
+`/api/doc` would refuse; `openable` on each hit reports whether the reader can actually show it.
+And it is **bounded, out loud**: `truncated` means files were never looked at, `content_truncated`
+means every file was named but not every body was read, `scanned`/`content_scanned` give the counts.
+Two caps, two flags — merged into one, the serious flag would light on any repository with a lock
+file in it, which is the same as retiring it.
+
 ## Branches: a new one doesn't move the others
 
 Starting a session, the branch control is **optional** — the default is "stay on current" and it

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/drive-guard.js

@@ -1,5 +1,6 @@
 'use strict';
-/* drive-guard — the driver's ONLY write path (pmos-autonomous-drive-build, R9).
+/* drive-guard — the driver's ONLY write path (pmos-autonomous-drive-build, R9;
+ * hardened from a denylist to an allowlist by `guard-and-ledger-hardening`, 2026-08-04).
  *
  * 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
@@ -20,10 +21,44 @@
  * 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
+ * ── WHY THIS IS NOW AN ALLOWLIST ────────────────────────────────────────────────────────────────
+ * The first version was a denylist, and its suite DID attempt each forbidden write and assert the
+ * throw — six attempts, six assertions, exactly as the paragraph above claims. It still shipped
+ * SEVEN bypasses, each measured by an independent pass
+ * (planning/explainers/work-item-entity-surface-explainer.md) by running it against this module:
+ *
+ *   1. `PM_approved` nested 11 deep      — recursion capped at `depth > 8`
+ *   2. `PM_approved: "true"` or `: 1`    — strict `v === true`
+ *   3. the payload JSON.stringify'd      — the `"` defeated /PM_approved\s*[:=]\s*true/
+ *   4. `status: 'PROMOTE'` / `'KILL'`    — the regex required -D / -ED
+ *   5. `payload.frontmatter.status`      — the structured status check was top-level only
+ *   6. `assertWritable({})`              — FAILED OPEN: no file, no payload, no text → returned true
+ *   7. `parent_kr`, an evals verdict,
+ *      `DECISIONS.md`                    — never named at all
+ *
+ * Plus a FALSE POSITIVE the other way: a legitimate initiative record was refused because its
+ * `status:` prose contained the word "promoted".
+ *
+ * The suite probed THE LIST. Nothing probed THE SHAPE OF THE LIST — and a denylist's shape is
+ * "everything somebody thought of". So:
+ *
+ *   - sinks are ALLOWLISTED, closing (7) as a class rather than as three strings;
+ *   - the content guard reads the SERIALIZED request, closing (1), (2) and (3) together — depth,
+ *     type-looseness and stringification all vanish when you look at the text the write would
+ *     actually produce;
+ *   - an unreadable request THROWS, closing (6), the worst of the seven;
+ *   - the disposition match is widened (4), recurses (5), and is anchored to the status value's
+ *     LEADING TOKEN, so a real disposition is refused and prose that merely says "promoted" is not.
+ *
+ * SCOPE, honestly, and unchanged: 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.
+ *
+ * AND THE LIMIT WORTH SAYING OUT LOUD: **nothing imports this module** — only workspace/test.js.
+ * The live acceptance writer at `POST /api/gate` appends directly and never calls it. This hardening
+ * makes the boundary correct; it does not make it load-bearing. Its whole value is that when
+ * something does adopt it, it will not adopt seven bypasses with it.
  */
 
 const path = require('path');
@@ -36,53 +71,150 @@ class ForbiddenWrite extends Error {
   }
 }
 
-/** Ledgers that record a human decision. The driver may never append to these. */
-const FORBIDDEN_FILES = Object.freeze(['acceptances.jsonl']);
+/**
+ * The sinks the driver's own free-zone policy sanctions (pmos-autonomous-drive, round 2): research,
+ * routing, the surface explainer, a disposable prototype, and DRAFT specs. Anything not here is
+ * refused — including every ledger, decision log and record nobody thought to enumerate.
+ *
+ * Directory prefixes rather than basenames, because these artifact classes name their files per
+ * initiative. `planning/evals/` admits a draft rubric and NOT `evals.jsonl`, which lives in
+ * `planning/runs/` and is refused with a reason below.
+ */
+const ALLOWED_DIR_PREFIXES = Object.freeze([
+  'planning/prd/',
+  'planning/evals/',
+  'planning/explainers/',
+  'planning/research/',
+  'planning/briefs/',
+  'prototype/',
+]);
+
+/**
+ * Machine ledgers the driver legitimately appends to: its own run record, the verification it owes,
+ * the work-items it declares, and the friction it hits.
+ *
+ * These are BASENAMES rather than a `planning/runs/` prefix, deliberately. Allowing the directory
+ * would admit `acceptances.jsonl`, `evals.jsonl` and `outcome_checks.jsonl` by default, and would
+ * admit the FOURTH ledger somebody adds next year without anyone deciding to — which is exactly the
+ * class-failure this rewrite exists to close. A new ledger is refused until it is named here.
+ *
+ * `agent-runs.jsonl` is on this list even though it carries `pre_run_contract`: the driver logging
+ * its own run is the free zone working as designed, and a fabricated `PM_approved` INSIDE that write
+ * is caught by the content guard below, not by refusing the file.
+ */
+const ALLOWED_BASENAMES = Object.freeze([
+  'agent-runs.jsonl',
+  'verify-queue.jsonl',
+  'work-items.jsonl',
+  'discoveries.md',
+]);
+
+/** Named explicitly so the refusal says WHY, rather than "not on the allowlist". Each of these
+ *  would otherwise be caught by the allowlist anyway — the value here is the message. */
+const HUMAN_DECISION_SINKS = Object.freeze({
+  'acceptances.jsonl': 'the Acceptance Gate is the PM\'s and non-delegable (D12)',
+  'evals.jsonl': 'a Review-Gate verdict on the driver\'s own work is self-grading — the driver may not record one (D40)',
+  'outcome_checks.jsonl': 'whether the bet paid off is the PM\'s judgement (D57)',
+  'DECISIONS.md': 'an architectural decision is the PM\'s (D45)',
+  'pm-decisions.md': 'the PM\'s decision journal is the PM\'s',
+});
+
+/** Disposition tokens (D60), widened to the bare verbs bypass 4 slipped through, and anchored so a
+ *  status VALUE that begins with one is a disposition while prose mentioning one is not. */
+/* Explicit groups, not a trailing `?` on the last letter. The first attempt at this widening wrote
+ * `KILLED?`, which is "KILLE" plus an optional "D" and therefore does NOT match the bare `KILL` —
+ * reintroducing bypass 4 while appearing to fix it. Caught only because every bypass is attempted
+ * individually, which is the whole argument for the suite below. */
+const DISPOSITION_RE = /^\s*"?\s*(PROMOTE(D)?|ITERATE(D)?|KILL(ED)?)\b/i;
 
-/** Disposition tokens (D60). Case-insensitive; a status carrying one is a PM act. */
-const DISPOSITION_RE = /\b(PROMOTED|ITERATE[D]?|KILLED)\b/i;
+/** Truthy-tolerant: an approval the PM never gave is what is being refused; its JSON type is not the
+ *  point. Closes bypass 2. */
+const TRUTHY = new Set([true, 1, 'true', 'TRUE', 'True', 'yes', 'YES', '1']);
 
-/** 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;
+const isObj = (v) => !!v && typeof v === 'object';
+
+/** True when `value` carries a truthy PM_approved anywhere. No depth cap (bypass 1); cycle-safe. */
+function carriesApproval(value, seen) {
+  const s = seen || new Set();
+  if (!isObj(value) || s.has(value)) return false;
+  s.add(value);
+  for (const [k, v] of Object.entries(value)) {
+    if (k === 'PM_approved' && TRUTHY.has(v)) return true;
+    if (carriesApproval(v, s)) return true;
+  }
+  return false;
+}
+
+/** True when a `status`/`disposition` key ANYWHERE carries a leading disposition token (bypass 5). */
+function carriesDisposition(value, seen) {
+  const s = seen || new Set();
+  if (!isObj(value) || s.has(value)) return false;
+  s.add(value);
   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;
+    if ((k === 'status' || k === 'disposition') && typeof v === 'string' && DISPOSITION_RE.test(v)) return true;
+    if (carriesDisposition(v, s)) return true;
   }
   return false;
 }
 
+function onAllowlist(file) {
+  const norm = String(file).replace(/\\/g, '/').replace(/^\.\//, '');
+  if (norm.includes('..')) return false;                 // no traversal out of an allowed directory
+  if (ALLOWED_BASENAMES.includes(path.basename(norm))) return true;
+  return ALLOWED_DIR_PREFIXES.some((p) => norm.startsWith(p));
+}
+
 /**
  * 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);
+  // (6) FAIL CLOSED. The predecessor returned `true` here, which is the worst of the seven: a
+  // request this function cannot understand is precisely the one it must not wave through.
+  if (!isObj(req) || Array.isArray(req)) {
+    throw new ForbiddenWrite('an unreadable request', 'a write request must be an object — refused (fail-closed)');
+  }
+  if (typeof req.file !== 'string' || !req.file.trim()) {
+    throw new ForbiddenWrite('a request with no target', 'a write request must name its `file` — refused (fail-closed)');
+  }
 
-  if (FORBIDDEN_FILES.includes(base)) {
-    throw new ForbiddenWrite('an acceptance', 'the Acceptance Gate is the PM\'s and non-delegable (D12)');
+  const why = HUMAN_DECISION_SINKS[path.basename(req.file)];
+  if (why) throw new ForbiddenWrite(path.basename(req.file), why);
+
+  // (7) closed as a CLASS: anything not sanctioned is refused, named or not.
+  if (!onAllowlist(req.file)) {
+    throw new ForbiddenWrite(req.file,
+      `not on the driver's allowlist — it may write ${ALLOWED_DIR_PREFIXES.join(', ')} or ${ALLOWED_BASENAMES.join(', ')}`);
   }
-  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)');
+
+  // (1)(2)(3) closed together by one look at the text the write would actually produce. A
+  // stringified payload, a "true", and an 11-deep nesting are all plainly visible here.
+  let serialized;
+  try {
+    serialized = JSON.stringify({ p: req.payload === undefined ? null : req.payload, t: req.text || '' });
+  } catch {
+    throw new ForbiddenWrite('an unserialisable payload',
+      'a payload that cannot be inspected cannot be permitted — refused (fail-closed)');
   }
-  if (req && typeof req.text === 'string' && /PM_approved\s*[:=]\s*true/i.test(req.text)) {
+  if (/PM_approved\W{0,4}(true|1|yes)/i.test(serialized) || carriesApproval(req.payload)) {
     throw new ForbiddenWrite('pre_run_contract.PM_approved',
-      'the contract is the PM\'s to approve before any build (D16) — caught in raw text');
+      'the contract is the PM\'s to approve before any build (D16, AGENTS.md §4)');
   }
 
-  // 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)) {
+  // (4)(5) and the false positive: matched on a status VALUE's leading token, structured or raw, so
+  // `status: "PROMOTED by PM wawan"` is refused and `status: "derived from the promoted prototype"`
+  // is not. Prose that mentions a disposition is not a disposition.
+  if (carriesDisposition(req.payload)) {
     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)');
+  if (typeof req.text === 'string') {
+    for (const line of req.text.split('\n')) {
+      const m = /^\s*(?:status|disposition)\s*:\s*(.*)$/i.exec(line);
+      if (m && DISPOSITION_RE.test(m[1])) {
+        throw new ForbiddenWrite('a disposition', 'promote/iterate/kill is the PM\'s (D60 step 7)');
+      }
+    }
   }
   return true;
 }
@@ -95,4 +227,7 @@ function guardedWriter(write) {
   };
 }
 
-module.exports = { assertWritable, guardedWriter, carriesApproval, ForbiddenWrite, FORBIDDEN_FILES };
+module.exports = {
+  assertWritable, guardedWriter, carriesApproval, carriesDisposition, ForbiddenWrite,
+  ALLOWED_DIR_PREFIXES, ALLOWED_BASENAMES, HUMAN_DECISION_SINKS, DISPOSITION_RE,
+};

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