create-pmos 0.8.0 → 0.10.0

package/README.md

@@ -333,6 +333,95 @@ 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.10.0
+
+**Editing a document now does something for the rest of them.**
+
+0.8.0 gave you an editor: change a markdown document in the workspace, see the diff as you type, and
+have the change logged. This release adds the two halves that make that log worth keeping.
+
+### After you save, you are offered what your change puts out of step
+
+Not a scan of your repository — a list built from **your change**. A document only appears if it has a
+concrete tie to what you edited:
+
+- it links to the document you changed, or names it in frontmatter (`prd_path`, `rubric_path`, …)
+- it shares that document's `initiative_id`
+- it **quotes text your change altered** — the strongest signal, because it is now asserting something
+  the source no longer says
+
+Each candidate says which of those it is, so you can judge the suggestion before spending anything on
+it. **"Seems related" is deliberately not a rule.** It would widen this to your whole repository and
+put you back in front of a queue of an agent's opinions.
+
+You tick which documents an agent may read. It drafts the edit that brings each back in line, and each
+draft comes back as a diff to apply or skip. Applying uses the same guard as every other write here:
+the text being replaced must appear exactly once, or the write is refused rather than guessed at.
+
+**It never blocks.** The save completed before any of this. Dismiss the offer and nothing is queued,
+nothing badges, nothing waits for you.
+
+### Your change log is now something an agent reads
+
+Every save regenerates `change-context.md` in your repository's own state directory: the documents you
+change most, the recent changes, and — the part that matters — **your own stated reasons**, in your
+words. An agent reading it before working in your repo knows what you keep rewriting and why, so it
+can stop producing the thing that provoked the rewrite.
+
+That is why the editor asks for a reason at all. A reason nobody reads is just friction at save time.
+
+Edits made by applying an alignment record **what they were aligned with**, so the log reads as a
+chain rather than as unexplained changes appearing in files you did not open.
+
+### Also carried: the 0.9.1 upgrade fix
+
+**0.9.1 was never published.** Its fix — `create-pmos workspace` self-upgrading instead of quietly
+launching your old installed app — is in this release. If the workspace has looked unchanged across
+recent versions, that is why; run `npx create-pmos@latest workspace` once and it will self-heal onto
+the current app. Hard-refresh the browser afterwards to drop the cached stylesheet.
+
+## What's new in 0.9.1
+
+**A fix so workspace upgrades actually reach you.** If you activated the Terminal Workspace in an
+earlier version, `npx create-pmos@latest workspace` was quietly launching your *old* installed app —
+so 0.9.0's restyle and whose-turn view never showed up. That was the bug, not a missing feature.
+
+- **`create-pmos workspace` now self-upgrades.** It compares the bundled app's version against what
+  you have installed and **reinstalls when the bundle is newer** (then restarts the persistent server
+  so the new code actually serves). A same-version install still fast-launches — no needless
+  ~20-second native rebuild.
+- **`create-pmos workspace --reinstall`** — force it any time.
+- **`pmos upgrade`** — the same, straight from the installed command.
+- If the UI still looks unchanged right after an upgrade, **hard-refresh the browser**
+  (Cmd/Ctrl+Shift+R) to drop the cached stylesheet.
+
+So if 0.9.0 looked like "not much changed," this is why: the code shipped, but your old install kept
+running. Run `npx create-pmos@latest workspace` once and it will self-heal onto the current app.
+
+## What's new in 0.9.0
+
+**The Terminal Workspace now tells you whose turn it is.** The optional GUI got this release's real
+work: it reads each session's transcript and shows, per session, whether the agent is still working
+or **waiting on you** — so a wall of terminals becomes a queue you can triage at a glance instead of
+a grid you have to click through.
+
+- **Whose-turn, read from the actual transcript.** Each session row and tab carries its state —
+  agent-working vs waiting-on-you — derived from the real conversation, not a guess. The sessions
+  that need a decision surface; the ones still running recede.
+- **A real design system, not a dev-tool skin.** The workspace was reskinned on a proper palette
+  with its own typography, and the fonts ship *inside* the package — nothing is fetched at runtime,
+  so it looks the same offline and behind a proxy.
+- **Your git branch is in the frame.** Each session shows the branch it is on and lets you switch,
+  so `initiative/<id>` work and its worktree are visible where you are working, not a `git status`
+  away.
+- **The router now makes you write the answers down.** `pmos-router` gained a step: the intake
+  answers (does this need its own instance? has this been rejected before?) get recorded on the
+  initiative, so a routing decision is enforceable later instead of evaporating the moment it's made.
+
+All of this rides in `npx create-pmos@latest workspace`. The file-mode kit itself is unchanged and
+still dependency-free; `npx create-pmos@latest --update` brings the router change into an existing
+kit and never touches your `state/`, `planning/`, or `okf/product/` records.
+
 ## What's new in 0.8.0
 
 **The document review is gone. There is a document editor instead.**

package/bin/create-pmos.js

@@ -140,24 +140,81 @@ function launchWorkspace(targetDir, viaGlobal) {
     { stdio: 'inherit', env: process.env }).status || 0;
 }
 
-function workspace(targetArg) {
+// Compare two dotted numeric versions. Returns -1 if a<b, 0 if equal, 1 if a>b. Missing/non-numeric
+// segments count as 0, so 'unknown' sorts oldest — the safe default (reinstall rather than run stale).
+function cmpVer(a, b) {
+  const pa = String(a || '0').split('.').map((n) => parseInt(n, 10) || 0);
+  const pb = String(b || '0').split('.').map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+// Version of the workspace app bundled in THIS package. It is kept in lockstep with the create-pmos
+// release version in workspace/package.json, so a newer package means a newer bundled app.
+function bundledWorkspaceVersion() {
+  try { return require(path.join(WORKSPACE, 'package.json')).version || null; }
+  catch { return null; }
+}
+// Version of the globally-installed `pmos-workspace`, or null if absent/unreadable. Read from the
+// npm global root rather than the app's CLI — no dependency on the old binary supporting --version.
+function installedWorkspaceVersion() {
+  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const r = spawnSync(npmCmd, ['root', '-g'], { encoding: 'utf8', shell: process.platform === 'win32' });
+  if (r.status !== 0 || !r.stdout) return null;
+  try { return require(path.join(r.stdout.trim(), 'pmos-workspace', 'package.json')).version || null; }
+  catch { return null; }
+}
+function installWorkspaceGlobal() {
+  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  return spawnSync(npmCmd, ['install', '-g', WORKSPACE, '--no-audit', '--no-fund'],
+    { stdio: 'inherit', shell: process.platform === 'win32' }).status;
+}
+// A persistent server started by the OLD code keeps serving OLD assets after an upgrade — stop it so
+// the next launch brings the server up on the freshly installed code. Best-effort; ignore failures.
+function stopWorkspaceServer() {
+  try { spawnSync('pmos', ['stop'], { stdio: 'ignore', shell: process.platform === 'win32' }); }
+  catch { /* no server running, or pmos not launchable — nothing to stop */ }
+}
+
+function workspace(targetArg, opts) {
   workspaceOrDie();
   const targetDir = path.resolve(targetArg || '.');
+  const forceReinstall = !!(opts && opts.reinstall);
 
-  // Already activated? Then this is just a launch — fast path, no reinstall.
+  // Already activated? Decide launch-vs-reinstall by VERSION, not merely by presence. The old
+  // behaviour fast-launched whenever `pmos` was on PATH, so every workspace improvement was invisible
+  // to anyone who had activated once — the installed app never advanced. Now: reinstall when forced,
+  // when the installed version can't be read, or when the bundled app is newer; otherwise fast-launch
+  // (no ~20s native rebuild for an already-current install).
   if (onPath('pmos')) {
-    console.log('✅ workspace already activated — launching. (Type `pmos` directly next time.)');
+    const bundled = bundledWorkspaceVersion();
+    const installed = installedWorkspaceVersion();
+    const stale = forceReinstall || installed === null || (bundled != null && cmpVer(installed, bundled) < 0);
+    if (!stale) {
+      console.log(`✅ workspace already current (pmos-workspace ${installed}) — launching. (Type \`pmos\` directly next time.)`);
+      process.exit(launchWorkspace(targetDir, true));
+    }
+    console.log(forceReinstall
+      ? 'Reinstalling the Terminal Workspace app (--reinstall)…'
+      : `Upgrading the Terminal Workspace app (installed ${installed || 'unknown'} → bundled ${bundled})…`);
+    const status = installWorkspaceGlobal();
+    if (status === 0) {
+      stopWorkspaceServer();   // restart the persistent server on the new code
+      console.log(`\n✅ pmos-workspace is now ${bundled}. Launching — if the UI still looks unchanged, hard-refresh the browser (Cmd/Ctrl+Shift+R) to drop the cached stylesheet.`);
+    } else {
+      console.log('\n⚠  Reinstall did not complete cleanly — launching the previously installed copy.');
+    }
     process.exit(launchWorkspace(targetDir, true));
   }
 
+  // First-time activation (pmos not on PATH).
   console.log('Activating the PMOS Terminal Workspace (one-time). Installing node-pty (native) + putting `pmos` on PATH…');
-  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-  const g = spawnSync(npmCmd, ['install', '-g', WORKSPACE, '--no-audit', '--no-fund'],
-    { stdio: 'inherit', shell: process.platform === 'win32' });
-
-  if (g.status === 0 && onPath('pmos')) {
+  const status = installWorkspaceGlobal();
+  if (status === 0 && onPath('pmos')) {
     console.log('\n✅ `pmos` is now on your PATH. From any repo folder, just type:  pmos');
-    console.log('   pmos status · pmos stop · pmos doctor');
+    console.log('   pmos status · pmos stop · pmos doctor · pmos upgrade');
     process.exit(launchWorkspace(targetDir, true));
   }
 
@@ -177,14 +234,15 @@ if (args.includes('--help') || args.includes('-h')) {
   console.log('usage:');
   console.log('  create-pmos [target-dir]              vendor the file-mode kit into a repo');
   console.log('  create-pmos --update [kit-or-repo]    refresh only the kit kernel');
-  console.log('  create-pmos workspace [repo-dir]      install + launch the Terminal Workspace GUI');
+  console.log('  create-pmos workspace [repo-dir]      install/upgrade + launch the Terminal Workspace GUI');
+  console.log('  create-pmos workspace --reinstall     force-reinstall the workspace app (drop a stale global copy)');
   console.log('  create-pmos --version                 print version + bundled kernel provenance');
 } else if (args.includes('--version') || args.includes('-v')) {
   console.log(`create-pmos ${PKG.version}`);
   console.log(kitVersion());
   console.log(`workspace bundled: ${fs.existsSync(path.join(WORKSPACE, 'bin', 'pmos.js')) ? 'yes' : 'no'}`);
 } else if (positional[0] === 'workspace') {
-  workspace(positional[1]);
+  workspace(positional[1], { reinstall: args.includes('--reinstall') });
 } else if (args.includes('--update')) {
   update(positional[0]);
 } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.8.0",
+  "version": "0.10.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@f56d5eb
+kernel-source: pmos@1771814
 assembled: 2026-07-28
 mode: vendor

package/payload/skills/pmos-router.skill

@@ -68,6 +68,28 @@ router is the bug (fix it via the weekly harness scan).
 branch `initiative/<id>`, and the human Acceptance Gate at the end (D12) — the router never bypasses
 [working-in-pmos](/okf/core/playbooks/working-in-pmos.md).
 
+## Step 5 — WRITE THE ANSWERS DOWN (this is what makes any of it enforceable)
+
+Steps 0.3 and 0.4 used to be asked aloud and then discarded, and the cost was exactly what you would
+predict: nothing could check that a *needs-an-instance* answer was followed by a prototype, or that
+an *existing surface* was explained before it was specified. An unrecorded answer is an
+unenforceable one. So both land on the initiative record, as a **leading token plus your reasoning**:
+
+```yaml
+specimen_test: "needs-instance — no description settles whether …"       # or "description-judgeable — …"
+predecessor: <prototype-initiative-id>       # required when the answer is needs-instance
+surface_check: "existing — the Initiative Gate"                          # or "greenfield — …"
+explainer_path: planning/explainers/<surface>-explainer.md               # required when it is existing
+```
+
+The gate ([`scripts/workflow-state.js`](/scripts/workflow-state.js)) reads the **token** and the
+**ordering of the paths it implies** — the prose is for the PM. It fails a PR whose PRD first
+appeared before its prototype brief (**O3**) or before its surface explainer (**O4**). It does not
+judge whether the answer was *right*: no deterministic check can decide that, and over-firing the
+specimen test twice running stays a D41 tripwire on the test's wording, not a gate condition.
+
+Check your position at any time with `node scripts/workflow-state.js <id>`.
+
 ## Edge rules
 
 - **Two shapes at once** (an idea that is also a bet): sharpness first, then the brief-offer, then

package/payload/skills-native/pmos-router/SKILL.md

@@ -70,6 +70,28 @@ router is the bug (fix it via the weekly harness scan).
 branch `initiative/<id>`, and the human Acceptance Gate at the end (D12) — the router never bypasses
 [working-in-pmos](/okf/core/playbooks/working-in-pmos.md).
 
+## Step 5 — WRITE THE ANSWERS DOWN (this is what makes any of it enforceable)
+
+Steps 0.3 and 0.4 used to be asked aloud and then discarded, and the cost was exactly what you would
+predict: nothing could check that a *needs-an-instance* answer was followed by a prototype, or that
+an *existing surface* was explained before it was specified. An unrecorded answer is an
+unenforceable one. So both land on the initiative record, as a **leading token plus your reasoning**:
+
+```yaml
+specimen_test: "needs-instance — no description settles whether …"       # or "description-judgeable — …"
+predecessor: <prototype-initiative-id>       # required when the answer is needs-instance
+surface_check: "existing — the Initiative Gate"                          # or "greenfield — …"
+explainer_path: planning/explainers/<surface>-explainer.md               # required when it is existing
+```
+
+The gate ([`scripts/workflow-state.js`](/scripts/workflow-state.js)) reads the **token** and the
+**ordering of the paths it implies** — the prose is for the PM. It fails a PR whose PRD first
+appeared before its prototype brief (**O3**) or before its surface explainer (**O4**). It does not
+judge whether the answer was *right*: no deterministic check can decide that, and over-firing the
+specimen test twice running stays a D41 tripwire on the test's wording, not a gate condition.
+
+Check your position at any time with `node scripts/workflow-state.js <id>`.
+
 ## Edge rules
 
 - **Two shapes at once** (an idea that is also a bet): sharpness first, then the brief-offer, then

package/workspace/README.md

@@ -94,6 +94,34 @@ 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.
 
+## 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
+performs no git operation at all. When you do pick one:
+
+- **`+ new branch…`** can give that branch its **own working tree**, at
+  `../<repo>-worktrees/<branch>` (a sibling of the repo — nothing appears inside it, nothing for
+  `.gitignore` to chase), registered as its own workspace. Every session already running stays
+  exactly where it was. The folder is named in the form before you commit to it, and again in the
+  footer once it exists.
+- **That's the default only when there are sessions to protect.** Alone in a workspace a plain
+  checkout disturbs nobody, so no folder is made. The checkbox is yours to flip either way.
+- **Unchecking "give it its own folder"** is the shared-tree checkout: this repo moves, and so does
+  every session in it. The hint counts them, and only warns when something really would move.
+- A branch can live in **one** working tree at a time. One already open elsewhere is labelled with
+  its location in the picker, rather than failing later.
+
+**⑂ worktrees** in the sidebar lists every working tree the repo has, and removes the ones that are
+safe to remove. A removal is refused — with the reason — when the tree has sessions running in it,
+uncommitted changes, or commits that no other branch, remote or tag holds. Removing one reclaims
+the folder and **keeps the branch**; nothing is ever removed automatically. Git history is shared
+between worktrees, so what a folder costs is a checkout of tracked files, not a second copy of the
+repo.
+
+A workspace anywhere **inside** a repo knows its branch — a subdirectory (`repo/packages/app`)
+counts, which matters for a product repo added by path. A folder with **no git** simply says so and
+starts the session; nothing about git can block work in a repo that doesn't use it.
+
 ## Boundaries (honest v1 seams)
 - **Server binds 127.0.0.1** — the D62 hosted-PTY-bridge rejection stands; a tailnet/phone client
   attaches to the same local server, never a public endpoint.

package/workspace/bin/pmos.js

@@ -211,10 +211,17 @@ function doctor() {
   else if (cmd === 'ls' || cmd === 'list') code = await ls();
   else if (cmd === 'stop') code = await stop();
   else if (cmd === 'doctor') code = doctor();
-  else if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
-    say('usage: pmos [<path>|status|ls|stop|doctor]');
+  else if (cmd === 'upgrade') {
+    // Escape hatch: pull the latest bundled app and force-reinstall over this global copy. Delegates
+    // to the scaffolder (which owns the install path) rather than reinstalling itself in place.
+    const npx = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+    code = spawnSync(npx, ['-y', 'create-pmos@latest', 'workspace', '--reinstall', process.cwd()],
+      { stdio: 'inherit', shell: process.platform === 'win32' }).status || 0;
+  } else if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    say('usage: pmos [<path>|status|ls|stop|doctor|upgrade]');
     say('  pmos          open the current repo as a workspace (starts the server if needed)');
     say('  pmos <path>   open another repo as a workspace');
+    say('  pmos upgrade  reinstall the workspace app from the latest published create-pmos');
     code = 0;
   } else if (cmd === 'up' || cmd === 'start' || cmd === 'open') {
     // `pmos open ../other-repo` — the path is the argument AFTER the verb

package/workspace/lib/console-state.js

@@ -114,4 +114,59 @@ function radar({ stateDir, snapshotDir }) {
   } };
 }
 
-module.exports = { metrics, radar, computeMetricsFromRuns, loadJson, loadJsonl };
+/*
+ * ── workflow: where each initiative is, what is next, what is blocking ────────────────────────
+ *
+ * The one surface that answers "where am I in the loop" without the PM reconstructing it from
+ * files. It renders the SAME ladder the CLI and the Initiative Gate print, from the same engine —
+ * `scripts/workflow-state.js` — so the panel can never disagree with what CI is about to say.
+ *
+ * The engine is the one BUNDLED WITH THE WORKSPACE, pointed at the opened repo via its `root`
+ * option. It is deliberately not `require`d out of the opened directory: the engine only reads
+ * files and runs `git -C <root> log`, so no code from a workspace the PM merely opened is ever
+ * executed. An install that does not carry the engine gets an honest error, never a blank panel.
+ */
+function workflow({ root }) {
+  if (!root) return { ok: false, error: 'no workspace root resolved for the workflow surface' };
+  let engine;
+  try { engine = require(path.join(__dirname, '..', '..', 'scripts', 'workflow-state.js')); }
+  catch {
+    return { ok: false, error: 'the workflow engine (scripts/workflow-state.js) is not present in this install — the ladder cannot be derived here' };
+  }
+  let ids;
+  try { ids = engine.listInitiatives(root); }
+  catch (e) { return { ok: false, error: 'could not list initiative records: ' + String((e && e.message) || 'error').slice(0, 120) }; }
+  if (!ids.length) return { ok: true, empty: true, source: 'file-mode' };
+
+  // One commit range for the whole board — resolving it per initiative would re-shell git for each.
+  const range = engine.commitRange(root);
+  const rows = ids.map((id) => {
+    try { return engine.computeWorkflow(id, { root, range }); }
+    catch (e) { return { ok: false, id, error: String((e && e.message) || 'derivation failed').slice(0, 160) }; }
+  });
+  // Same `inFlight` the CLI and the gate use — the panel must not invent its own idea of what is
+  // open. Filtering by `legacy` here was a real bug: on main every record is legacy, so the panel
+  // read "0 in flight" against 93 initiatives, blank at exactly the moment someone opens it.
+  const { shown, hidden, total } = engine.inFlight(rows);
+  const shape = (r) => (r.ok ? {
+    id: r.id, title: r.title, lane: r.lane, stage: r.stage, legacy: r.legacy,
+    in_change: r.in_change, anchor: r.anchor,
+    record: r.record, blockers: r.blockers, next: r.next,
+    steps: r.steps.map((s) => ({ key: s.key, status: s.status, evidence: s.evidence, next: s.next, blocking: s.blocking, rule: s.rule })),
+  } : { id: r.id, error: r.error });
+  return {
+    ok: true, empty: false, source: 'file-mode',
+    data: {
+      live: shown.map(shape),
+      hidden,                       // reported on the client — a silent cap reads as "that is all"
+      total,
+      accepted: rows.filter((r) => r.ok && r.accepted).length,
+      unreadable: rows.filter((r) => !r.ok).map(shape),
+      blocked: shown.filter((r) => r.ok && r.blockers.length).length,
+      degraded: range.ok ? null : range.reason,
+      enforced_from: engine.ENFORCED_FROM,
+    },
+  };
+}
+
+module.exports = { metrics, radar, workflow, computeMetricsFromRuns, loadJson, loadJsonl };