create-pmos 0.95.0 → 0.96.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.95.0",
+  "version": "0.96.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. 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@1e39390
+kernel-source: pmos@a11a7a5
 assembled: 2026-10-07
 mode: vendor

package/payload/planning/evals/eval-calibration.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Eval calibration log"
 description: "Append-only record of every PM override of an evaluator verdict."
-generated: {by: process:create-pmos, at: "2026-10-07T23:23:47Z"}
+generated: {by: process:create-pmos, at: "2026-10-07T23:35:56Z"}
 status: stable
 ---
 

package/payload/planning/okrs/health-budgets.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Health budgets"
 description: "Closed registry of health-budget anchors (D59), edited only by the PM."
-generated: {by: process:create-pmos, at: "2026-10-07T23:23:47Z"}
+generated: {by: process:create-pmos, at: "2026-10-07T23:35:56Z"}
 status: stable
 ---
 

package/payload/state/discoveries.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Discoveries and friction log"
 description: "Append-only record of what runs discovered and where the process rubbed."
-generated: {by: process:create-pmos, at: "2026-10-07T23:23:47Z"}
+generated: {by: process:create-pmos, at: "2026-10-07T23:35:56Z"}
 status: stable
 ---
 

package/workspace/guide/layout.md

@@ -39,6 +39,7 @@ Settings holds settings only, in eight sections. On a wide screen they are cards
 - **Updates**: the version of the workspace app and the version of the kit in the current repository. Press **Check for updates** at the top of the page to compare them with the latest published version of PMOS. This is the only time the workspace asks the internet for a version, and it asks only when you press. When a newer version is available, one button shows: **Update to** and the version. It updates every part that is older, in this order:
   - **The kit** in the current repository, when it is older. This does what `npx create-pmos@latest --update` does in a terminal. It changes only the kit's own files under `pmos/` (skills, scripts, templates and guides). Your records in `state/`, `planning/` and `okf/product/` do not change. The last lines of the output show under the button. The changed files are under `pmos/`, which Sync treats as records, so Sync (or automatic sync) sends them with your other records. To read them first, look at `git diff pmos/` before you sync.
   - **The workspace app**, when it is older. This does what `pmos upgrade` does in a terminal. The button asks you first. The workspace stops, installs the new version and starts again, and the page reloads when the new version starts. The reloaded page runs the new version's code: each start gives the page files a new address, so neither the browser nor the Online address's tunnel can keep the old ones. You do not need a terminal or a hard refresh. Sessions keep running in tmux. It works on the computer that runs the workspace and at its Online address, because the page comes back there after the restart. It also works on a phone or public address that signs in with a token set in `PMOS_TOKEN`, which the workspace keeps. When the workspace made its own token at start, the token changes on the restart, so the page refuses and says where to press it. When the workspace runs from a PMOS checkout, update it with `git pull` instead.
+  - **Testing an update before it is published.** Set `PMOS_UPDATE_SOURCE` to a built create-pmos package on the same computer: its folder, or the `.tgz` that `npm pack` makes. Then **Check for updates** reads that package's version and does not ask npm, and both updates install that package. The Updates card names the package it checks. A checkout may update the app this way. When the path is wrong, the card says why and does not fall back to npm. Unset the variable, or set it to `npm`, to use the registry again.
 
   A new screen or a renamed menu comes with the workspace app, not with the kit.
 

package/workspace/lib/kit-update.js

@@ -3,7 +3,8 @@
  *
  *   readKit(root)                           → { present:false } | { present:true, version, kernelSource, installed, mode }
  *   status({ root, appVersion, appDir })    → { app: { version, fromCheckout }, kit }       local only, no network
- *   latest({ exec })                        → Promise<{ ok, version } | { ok:false, error }>   npm view create-pmos version
+ *   source(env)                             → { kind:'npm' } | { kind:'local', path } | { kind:'local', path, error }
+ *   latest({ exec, source })                → Promise<{ ok, version } | { ok:false, error }>   npm view create-pmos version
  *   compare(st, latestVersion)              → { appBehind, kitBehind }
  *   updateKit(root, { version, exec })      → Promise<{ ok, output, kit } | { ok:false, error, output }>
  *   upgradeApp(root, { version, logFile, spawn, env }) → { ok, log } | { ok:false, error }
@@ -14,6 +15,10 @@
  *   check        npm view create-pmos version
  *   kit          npx -y create-pmos@<version> --update <repo>            (the kernel only; state/ and planning/ untouched)
  *   app          npx -y create-pmos@<version> workspace --reinstall <repo> (what `pmos upgrade` runs)
+ * LOCAL SOURCE. PMOS_UPDATE_SOURCE names a built create-pmos package on this computer: its folder (with package.json, bin/
+ * and payload/ or workspace/) or its .tgz from `npm pack`. The check then reads that package's version instead of asking
+ * the registry, and the update runs `npx -y <that path> ...` in place of `npx -y create-pmos@<version> ...`. Nothing
+ * reaches the network, so an update can be tried before it is published. Unset means npm (the default).
  * The version is the one the check found, so what is installed is what the PM was shown, not whatever `latest` is a
  * minute later. The app upgrade stops this server (create-pmos runs `pmos stop`), so it runs DETACHED, writes its output
  * to a log file, and the page waits for the server to come back.
@@ -81,8 +86,34 @@ function fromCheckout(appDir) {
   try { return fs.existsSync(path.join(String(appDir), '..', '.git')); } catch { return false; }
 }
 
-function status({ root, appVersion, appDir }) {
-  return { app: { version: appVersion || null, fromCheckout: fromCheckout(appDir) }, kit: readKit(root) };
+/**
+ * Where "latest" comes from. Unset or "npm" is the registry. Anything else is a path to a built create-pmos package: a
+ * folder or a .tgz. `error` names what is wrong with it, so the page can say so instead of silently using npm.
+ */
+function source(env = process.env) {
+  const raw = String((env && env.PMOS_UPDATE_SOURCE) || '').trim();
+  if (!raw || raw.toLowerCase() === 'npm') return { kind: 'npm' };
+  const p = path.resolve(raw);
+  let st;
+  try { st = fs.statSync(p); } catch { return { kind: 'local', path: p, error: `PMOS_UPDATE_SOURCE points to ${p}, which does not exist` }; }
+  if (st.isDirectory()) {
+    let pkg;
+    try { pkg = JSON.parse(fs.readFileSync(path.join(p, 'package.json'), 'utf8')); } catch { pkg = null; }
+    if (!pkg || pkg.name !== PKG_NAME) return { kind: 'local', path: p, error: `${p} is not a ${PKG_NAME} package folder (no package.json named ${PKG_NAME})` };
+    if (!fs.existsSync(path.join(p, 'payload')) && !fs.existsSync(path.join(p, 'workspace'))) return { kind: 'local', path: p, error: `${p} is not a built package: it has no payload/ or workspace/ folder. Point PMOS_UPDATE_SOURCE at the .tgz from \`npm pack\` instead` };
+    return { kind: 'local', path: p, version: validVersion(pkg.version) ? pkg.version : null };
+  }
+  const m = /^create-pmos-(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)\.tgz$/.exec(path.basename(p));
+  if (!m) return { kind: 'local', path: p, error: `${p} is not a create-pmos-<version>.tgz file` };
+  return { kind: 'local', path: p, version: m[1] };
+}
+
+/** What npx installs: the registry package at a version, or the local path. */
+const specOf = (src, version) => (src && src.kind === 'local' ? src.path : `${PKG_NAME}@${version}`);
+
+function status({ root, appVersion, appDir, env }) {
+  const src = source(env);
+  return { app: { version: appVersion || null, fromCheckout: fromCheckout(appDir) }, kit: readKit(root), source: src.kind === 'local' ? { kind: 'local', path: src.path, error: src.error || null } : { kind: 'npm' } };
 }
 
 function compare(st, latestVersion) {
@@ -115,7 +146,12 @@ function why(r, what) {
   return `${what} did not finish${said ? ': ' + said : ''}`;
 }
 
-async function latest({ exec = cp.execFile } = {}) {
+async function latest({ exec = cp.execFile, source: src = source() } = {}) {
+  if (src.kind === 'local') {
+    if (src.error) return { ok: false, error: src.error };
+    if (!src.version) return { ok: false, error: `${src.path} has no version number` };
+    return { ok: true, version: src.version, source: 'local' };
+  }
   const r = await run(exec, NPM, ['view', PKG_NAME, 'version', '--json'], { timeout: CHECK_TIMEOUT_MS });
   const bad = why(r, 'The check');
   if (bad) return { ok: false, error: bad };
@@ -135,10 +171,11 @@ function notServedYet(text, version) {
 }
 const notServedYetError = (version) => `npm lists ${PKG_NAME} ${version}, but its download is not available yet. A version this new can take up to five minutes to reach every npm server. Press Update again in five minutes`;
 
-async function updateKit(root, { version, exec = cp.execFile } = {}) {
+async function updateKit(root, { version, exec = cp.execFile, source: src = source() } = {}) {
   if (!validVersion(version)) return { ok: false, error: 'Check for updates first' };
+  if (src.kind === 'local' && src.error) return { ok: false, error: src.error };
   if (!readKit(root).present) return { ok: false, error: 'This repository has no PMOS kit folder (pmos/KIT-VERSION)' };
-  const r = await run(exec, NPX, ['-y', `${PKG_NAME}@${version}`, '--update', String(root)], { timeout: UPDATE_TIMEOUT_MS, cwd: String(root) });
+  const r = await run(exec, NPX, ['-y', specOf(src, version), '--update', String(root)], { timeout: UPDATE_TIMEOUT_MS, cwd: String(root) });
   const output = tail(r.stdout + (r.stderr ? '\n' + r.stderr : ''));
   if (r.err && notServedYet(r.stdout + r.stderr, version)) return { ok: false, error: notServedYetError(version), output };
   const bad = why(r, 'The kit update');
@@ -175,15 +212,16 @@ function updateEnv(env = process.env, nodePath = process.execPath) {
   return parts.includes(dir) ? { ...env } : { ...env, [key]: [...parts, dir].join(path.delimiter) };
 }
 
-function upgradeApp(root, { version, logFile, spawn = cp.spawn, env = updateEnv() } = {}) {
+function upgradeApp(root, { version, logFile, spawn = cp.spawn, env = updateEnv(), source: src = source() } = {}) {
   if (!validVersion(version)) return { ok: false, error: 'Check for updates first' };
+  if (src.kind === 'local' && src.error) return { ok: false, error: src.error };
   let fd;
   try {
     fs.mkdirSync(path.dirname(logFile), { recursive: true });
     fd = fs.openSync(logFile, 'w');
     fs.writeSync(fd, `${new Date().toISOString()} clearing npm cache…\n`);
     fs.writeSync(fd, `${new Date().toISOString()} ${NPM} cache clean --force\n`);
-    fs.writeSync(fd, `${new Date().toISOString()} ${NPX} -y ${PKG_NAME}@${version} workspace --reinstall ${root}\n`);
+    fs.writeSync(fd, `${new Date().toISOString()} ${NPX} -y ${specOf(src, version)} workspace --reinstall ${root}\n`);
   } catch (e) { return { ok: false, error: `Could not write the log file: ${e.message}` }; }
   try {
     // Clear npm cache synchronously before spawning the update, so npx downloads the fresh version
@@ -192,7 +230,7 @@ function upgradeApp(root, { version, logFile, spawn = cp.spawn, env = updateEnv(
     try { fs.appendFileSync(logFile, `Note: cache clear had an issue, but continuing: ${e.message}\n`); } catch { /* silent */ }
   }
   try {
-    const child = spawn(NPX, ['-y', `${PKG_NAME}@${version}`, 'workspace', '--reinstall', String(root)],
+    const child = spawn(NPX, ['-y', specOf(src, version), 'workspace', '--reinstall', String(root)],
       { cwd: String(root), env, detached: true, stdio: ['ignore', fd, fd], windowsHide: true, shell: IS_WIN });
     // A child that could not start writes nothing itself: say why in the log, which the page names when it gives up.
     if (child && typeof child.on === 'function') {
@@ -207,4 +245,4 @@ function upgradeApp(root, { version, logFile, spawn = cp.spawn, env = updateEnv(
   }
 }
 
-module.exports = { PKG_NAME, cmpVer, notServedYet, validVersion, readKit, fromCheckout, status, compare, latest, updateKit, updateEnv, upgradeApp, whereFrom };
+module.exports = { PKG_NAME, cmpVer, notServedYet, validVersion, source, specOf, readKit, fromCheckout, status, compare, latest, updateKit, updateEnv, upgradeApp, whereFrom };

package/workspace/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pmos-workspace",
-  "version": "0.95.0",
+  "version": "0.96.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pmos-workspace",
-      "version": "0.95.0",
+      "version": "0.96.0",
       "license": "MIT",
       "dependencies": {
         "@xterm/addon-fit": "^0.11.0",

package/workspace/package.json

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

package/workspace/public/pm/dest-settings.js

@@ -341,7 +341,9 @@ async function waitForRestart(from, log) {
  * server, installs the new version, starts it again, and this page reloads on it. A kit update alone changes no page.
  */
 async function updateAll(ws, app, cmp) {
-  const appToo = !!cmp.appBehind && !app.fromCheckout;
+  const cur = kitByWs.get(ws);
+  const local = !!(cur && cur.st && cur.st.source && cur.st.source.kind === 'local');
+  const appToo = !!cmp.appBehind && (!app.fromCheckout || local);
   if (appToo) {
     const yes = await askConfirm({ title: P.updateAppTitle, body: P.updateAppBody(app.version || '?', upd.latest), confirmLabel: P.updateAll });
     if (!yes) return;
@@ -368,9 +370,11 @@ function updatesSection(scope) {
   const cmp = upd.compare || {};
   const kids = [];
   const kitPresent = !!(kit && kit.present);
-  const canUpdate = (cmp.appBehind && !app.fromCheckout) || (cmp.kitBehind && kitPresent);
+  const canUpdate = (cmp.appBehind && (!app.fromCheckout || (st && st.source && st.source.kind === 'local'))) || (cmp.kitBehind && kitPresent);
   kids.push(el('div', { class: 'fr-set__line fr-set__line--box' }, icon('panel-top'), el('span', { 'data-fr': 'app-version' }, P.updatesApp(app.version))));
-  if (cmp.appBehind && app.fromCheckout) kids.push(el('p', { class: 'fr-set__note', 'data-fr': 'app-checkout' }, P.updatesCheckout));
+  const src = st && st.source;
+  if (src && src.kind === 'local') kids.push(el('p', { class: 'fr-set__note' + (src.error ? ' fr-set__error' : ''), 'data-fr': 'update-source' }, src.error ? P.updatesLocalBad(src.error) : P.updatesLocal(src.path)));
+  if (cmp.appBehind && app.fromCheckout && !(src && src.kind === 'local')) kids.push(el('p', { class: 'fr-set__note', 'data-fr': 'app-checkout' }, P.updatesCheckout));
   const kitText = scope === 'all' || !ws ? P.updatesNoRepo : !kit ? '' : kit.present ? P.updatesKit(kit.version) : P.updatesNoKit;
   kids.push(el('div', { class: 'fr-set__line fr-set__line--box' }, icon('cloud'), el('span', { 'data-fr': 'kit-version' }, kitText)));
   if (canUpdate) {

package/workspace/public/pm/frame-copy.js

@@ -223,6 +223,8 @@ export const COPY = {
     updatesNever: 'Press Check for updates to compare with the latest published version.',
     updatesLatest: (v) => 'Latest published version: ' + v + '.',
     updatesCurrent: (v) => 'Up to date. The latest published version is ' + v + '.',
+    updatesLocal: (p) => 'Checking against the local package ' + p + ', not npm. Set PMOS_UPDATE_SOURCE to change this.',
+    updatesLocalBad: (e) => e,
     updatesCheckout: 'This workspace runs from a PMOS checkout. Update it with git pull.',
     updatesNote: 'Updating the kit changes only its own files (skills, scripts, templates and guides). Your records in state/, planning/ and okf/product/ do not change.',
     updateKitBusy: 'Updating the kit…',

package/workspace/server.js

@@ -7261,7 +7261,7 @@ async function handleRequest(req, res) {
     if (!w) return json(res, { ok: false, error: 'no such workspace' }, 400);
     const st = () => kitUpdate.status({ root: w.root, appVersion: APP_VERSION, appDir: __dirname });
     if (p === '/api/kit/check') {
-      const r = await kitUpdate.latest();
+      const r = await kitUpdate.latest({ source: kitUpdate.source() });
       const now = st();
       if (!r.ok) return json(res, { ok: false, error: r.error, ws: w.id, ...now }, 502);
       return json(res, { ok: true, ws: w.id, ...now, latest: r.version, ...kitUpdate.compare(now, r.version) });
@@ -7283,7 +7283,8 @@ async function handleRequest(req, res) {
       tokenKept: !!TOKEN && !BIND.generated,
     });
     if (!where.ok) return json(res, { ok: false, error: where.error }, 403);
-    if (st().app.fromCheckout) return json(res, { ok: false, error: 'This workspace runs from a PMOS checkout. Update it with git pull' }, 409);
+    // A local source (PMOS_UPDATE_SOURCE) is how a checkout tries an update, so only the npm source is refused there.
+    if (st().app.fromCheckout && st().source.kind !== 'local') return json(res, { ok: false, error: 'This workspace runs from a PMOS checkout. Update it with git pull' }, 409);
     const r = kitUpdate.upgradeApp(w.root, { version: body.version, logFile: path.join(STATE, 'app-update.log') });
     if (!r.ok) return json(res, { ok: false, error: r.error }, 400);
     kitBusy = 'app';

package/workspace/test-files.json

@@ -8,6 +8,7 @@
     "test.js"
   ],
   "modules": [
+    "report-template-cadence.test.js",
     "proactive.test.js",
     "goals.test.js",
     "agenda.test.js",
@@ -100,6 +101,7 @@
     "pm-r29-skills-scheduled-test.js",
     "pm-r29-validate-guide-test.js",
     "pm-r29-reports-addrepo-test.js",
+    "pm-report-tab-test.js",
     "pm-r29-filespad-test.js",
     "pm-r29-newsession-alignment-test.js",
     "pm-live-notes-test.js",
@@ -199,6 +201,8 @@
     "pm-r29-skills-scheduled-test.js": 6,
     "pm-r29-validate-guide-test.js": 20,
     "pm-r29-reports-addrepo-test.js": 4,
+    "pm-report-tab-test.js": 10,
+    "report-template-cadence.test.js": 1,
     "pm-r29-filespad-test.js": 5,
     "pm-r29-newsession-alignment-test.js": 8,
     "pm-live-notes-test.js": 24,