create-pmos 0.7.2 → 0.7.3

package/README.md

@@ -333,6 +333,45 @@ 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.7.3
+
+**A fix — read this if you ran a document review on 0.7.1 or 0.7.2, and especially if you have more
+than one repository open in the workspace.**
+
+Reviews were filed into the **workspace app's own install directory** rather than into the repository
+being reviewed. Two consequences, and the first is the one that matters:
+
+- **Reviews from different repositories were pooled together.** Open two repos and the review you
+  filed against one appeared when you opened the review surface in the other. A review names the
+  documents it read and quotes their contents, so this put one project's material in front of
+  another — including in front of an agent session working in that second repo.
+- **In a product repo using this kit, reviews were written nowhere useful.** The review skill was
+  written against PMOS's own layout and told the agent to write to `workspace/state/reviews/` and
+  read `workspace/state/needs.json`. **A product repo has no `workspace/` folder**, so the agent
+  either created a stray one or filed the review where nothing would ever read it.
+
+**Both are fixed.** Reviews now resolve through the same per-workspace state directory that
+`needs.json` and `acceptances.jsonl` already used — your repo's own `pmos/state/reviews/`. The skill
+no longer assumes any layout: the paths it needs are passed to it as absolute facts.
+
+**If you reviewed anything on 0.7.1 or 0.7.2**, look in the workspace app's install directory under
+`workspace/state/reviews/` for reviews that belong to your repositories, and delete any you would
+rather not have sitting there. Nothing was sent anywhere — this is local files in the wrong folder —
+but if you had two repos open, they saw each other.
+
+**And the reason you probably never ran one: there was no way to say what to review.** The skill could
+only be launched from the scheduled lens, and a schedule carries no scope — so its own instruction to
+read exactly the documents you named had nothing behind it.
+
+- **A `review` control now sits on the open document.** You are reading a document; you click
+  `review`; an agent reviews *that* document. Nothing to type, no schedule to create. The scope is
+  the thing in front of you.
+
+**The standing disclosure is unchanged**, and it still matters more than any of the above: the review
+surface has **not** been through its own review gate, and its false-positive rate is unmeasured. The
+guard that withholds any proposal which would close a recorded open question or overwrite a decision
+is tested, including in a real browser. How often its findings are simply *wrong* is not yet known.
+
 ## What's new in 0.7.2
 
 **A fix — read this if you use the Terminal Workspace on a machine with `tmux` installed.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "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@bd8056d
+kernel-source: pmos@56ab797
 assembled: 2026-07-28
 mode: vendor

package/workspace/public/app.js

@@ -883,6 +883,8 @@ async function openDoc(pth, kind) {
   body.querySelectorAll('[data-doc]').forEach((a) => a.onclick = (e) => { e.preventDefault(); openDoc(a.dataset.doc); });
   wireImgFallback(body);
   markActiveDoc(pth);
+  // Only a markdown document can be reviewed, and only a document — never a summoned surface.
+  $('docReview').hidden = !(state.docPath && /\.(md|markdown|mdown|mkd|mdx|skill)$/i.test(state.docPath));
   refit();
 }
 function markActiveDoc(pth) {
@@ -929,6 +931,7 @@ function renderHtmlDoc(body, text) {
 }
 function closeDoc() {
   state.docPath = null; state.surface = null;
+  $('docReview').hidden = true;
   $('paneDoc').hidden = true;
   $('railSplit').hidden = true;
   $('docBody').innerHTML = '';
@@ -1807,6 +1810,25 @@ $('themeBtn').onclick = () => {
 };
 $('closeDoc').onclick = closeDoc;
 
+// "review" on an open document. The whole point of putting it HERE is that the scope needs no
+// naming — the thing to review is the thing you are reading. The server assembles the prompt
+// (skill body + resolved paths) because a tenant repo has no workspace/ folder to point at.
+$('docReview').onclick = async () => {
+  const pth = state.docPath;
+  if (!pth) return;
+  const btn = $('docReview');
+  btn.disabled = true; btn.textContent = 'starting…';
+  let out = {};
+  try {
+    out = await (await fetch('/api/review/start', { method: 'POST', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ ws: state.wsId, path: pth }) })).json();
+  } catch { out = { ok: false, error: 'could not reach the workspace server' }; }
+  btn.disabled = false; btn.textContent = 'review';
+  if (!out.ok) { flash(out.error || 'could not start the review'); return; }
+  flash('reviewing ' + pth.split('/').pop() + ' — watch the session');
+  if (out.sessionId) selectSession(out.sessionId);
+};
+
 // ── ⌘K / Ctrl-K jump palette (client-side: workspaces + sessions + initiatives + docs) ──
 // ── on-demand surfaces (Plan · Deliver · Measure · Report) ─────────────────────────────────────
 // Summoned from ⌘K, rendered in the reader, derived through the server's local state adapter and
@@ -1834,6 +1856,7 @@ async function openSurface(name) {
   showRail();
   $('paneDoc').hidden = false; $('railSplit').hidden = false; foldPane('doc', true);
   state.surface = name; state.docPath = null;
+  $('docReview').hidden = true;
   document.querySelectorAll('.doc').forEach((b) => b.classList.remove('on'));
   $('crumb').innerHTML = `<bdi>surface · ${esc(name)}</bdi>`;
   $('docBody').scrollTop = 0;

package/workspace/public/index.html

@@ -187,6 +187,7 @@
         <div class="cap">
           <button class="fold" id="docFold" aria-expanded="true" title="Hide the document"><span class="chev" aria-hidden="true">▾</span>document</button>
           <span class="crumb" id="crumb"></span>
+          <button class="mini docrev" id="docReview" hidden title="Have an agent review this document">review</button>
           <button class="x" id="closeDoc" aria-label="Close document">✕</button>
         </div>
         <div class="pane-body doc-body" id="docBody" tabindex="0"></div>

package/workspace/server.js

@@ -603,7 +603,15 @@ const DELIV_DIR = path.join(STATE, 'deliverables');
 // Reviews the doc-review skill files (workspace-review-and-edit). One JSON per run, written by the
 // skill session, read back by /api/review. Runtime, not the record: the durable artifact of a review
 // is the correction records its dispositions produce, which live in planning/runs/ and are tracked.
-const REVIEW_DIR = path.join(STATE, 'reviews');
+// PER WORKSPACE, like every other piece of state here. An earlier build put this in the SERVER's own
+// state/ — which meant two open repos shared one review pile, and a tenant repo (which has no
+// workspace/ folder at all) had the reviews written into the installed app instead of into the repo
+// being reviewed. Reviews name documents and quote their contents, so that was a cross-workspace leak,
+// not just untidy filing. stateDirFor() is the same resolver needs.json and acceptances.jsonl use.
+function reviewDirFor(w, opts) {
+  const d = stateDirFor(w, opts);
+  return d ? path.join(d, 'reviews') : null;
+}
 // Skills are file-driven (workspace-skill-authoring): built-ins ship committed under workspace/skills/,
 // user-authored ones are scaffolded into state/skills/ by the New Skill flow. There is ONE user-facing
 // concept — a skill — so the picker never exposes the internal `run`/`kind`; how a skill runs (server
@@ -1910,13 +1918,14 @@ async function handleRequest(req, res) {
     if (!w) return json(res, { ok: false, error: 'no workspace' }, 404);
     const want = url.searchParams.get('id');
     let files = [];
-    try { files = fs.readdirSync(REVIEW_DIR).filter((f) => f.endsWith('.json')).sort(); } catch {}
+    const rdir = reviewDirFor(w);
+    try { files = rdir ? fs.readdirSync(rdir).filter((f) => f.endsWith('.json')).sort() : []; } catch {}
     if (want && !/^[A-Za-z0-9._-]+$/.test(want)) return json(res, { ok: false, error: 'bad review id' }, 400);
     const pick = want ? `${want}.json` : files[files.length - 1];
     if (!pick || !files.includes(pick)) return json(res, { ok: true, empty: true, reviews: files.length });
 
     let review;
-    try { review = JSON.parse(fs.readFileSync(path.join(REVIEW_DIR, pick), 'utf8')); }
+    try { review = JSON.parse(fs.readFileSync(path.join(rdir, pick), 'utf8')); }
     catch { return json(res, { ok: false, error: `review '${pick}' is unreadable or not valid JSON` }, 500); }
 
     // The SAME contract the write path enforces (R3/R7). A review that fails it is surfaced as an
@@ -1953,6 +1962,60 @@ async function handleRequest(req, res) {
     }));
     return json(res, { ok: true, id: pick.replace(/\.json$/, ''), read: review.read, at: review.at || null, findings, reviews: files.length, stats, reasons: [...correctionRecord.REASONS] });
   }
+  if (p === '/api/review/start' && req.method === 'POST') {
+    // Review THIS document — the trigger that makes the scope implicit instead of typed. The PM is
+    // reading a document; the thing they want reviewed is the thing in front of them.
+    //
+    // The prompt is assembled HERE, not in the browser, for one reason that matters beyond tidiness:
+    // a tenant product repo has no workspace/ folder. Pointing the agent at
+    // `workspace/skills/doc-review.skill` works in PMOS-self and breaks everywhere else, and so does
+    // telling it to write to `workspace/state/reviews/`. The server knows the skill body and the
+    // resolved state directory for THIS workspace, so both travel in the prompt as absolute facts.
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+
+    const w = getWs(body.ws);
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 404);
+    const rel = String(body.path || '').trim();
+    if (!rel) return json(res, { ok: false, error: 'no document named' }, 400);
+    const full = path.resolve(w.root, rel);
+    if (!insideRoot(w.root, full)) return json(res, { ok: false, error: 'outside workspace' }, 404);
+    if (preview.previewKind(path.basename(full)) !== 'markdown') {
+      return json(res, { ok: false, error: 'only markdown documents can be reviewed' }, 400);
+    }
+    if (!fs.existsSync(full)) return json(res, { ok: false, error: 'no such document' }, 404);
+
+    const task = loadTasks().find((t) => t.id === 'doc-review');
+    if (!task || !task.prompt) return json(res, { ok: false, error: 'the doc-review skill is not installed' }, 500);
+
+    const rdir = reviewDirFor(w, { create: true });
+    if (!rdir) return json(res, { ok: false, error: 'this workspace has no state directory to file a review into' }, 500);
+    try { fs.mkdirSync(rdir, { recursive: true }); }
+    catch (e) { warnWriteFail('reviews directory', e); return json(res, { ok: false, error: 'could not create the reviews directory' }, 500); }
+
+    // Scope first, so it is the last thing the agent reads before the procedure — and stated as
+    // paths, because "the documents the PM named" is only a rule if something names them.
+    const extra = Array.isArray(body.also) ? body.also.filter((x) => typeof x === 'string').slice(0, 9) : [];
+    const scope = [rel, ...extra];
+    const preamble = [
+      'Review these documents, and only these:',
+      ...scope.map((s) => `  - ${s}`),
+      '',
+      `File the review as JSON into: ${rdir}`,
+      `The needs-you queue for this workspace is: ${needsFileFor(w) || '(none — skip the needs step)'}`,
+      'Both paths are absolute and already exist. Use them exactly; do not guess a workspace/ path.',
+      '',
+      '--- the skill ---',
+      '',
+    ].join('\n');
+
+    const s = spawnSession({ name: 'review: ' + path.basename(rel), agent: task.agent || 'claude',
+      ws: w.id, origin: 'review:' + rel, initialInput: preamble + task.prompt + '\r' });
+    const started = !!(s && s.pty);
+    return json(res, { ok: started, sessionId: s && s.id, scope, sink: rdir,
+      error: started ? undefined : ((s && s.note) || 'could not start the session') });
+  }
   if (p === '/api/review/dispose' && req.method === 'POST') {
     // The ONLY write path this surface has (workspace-review-and-edit R6/R8/R11). The reader was
     // designed around there being none, so every guard here is load-bearing rather than ceremony.

package/workspace/skills/doc-review.skill

@@ -56,7 +56,8 @@ and is not — it is a measured open question (`pm-decisions.md` 491–503).
 
 ## Procedure
 
-1. **Take the scope.** Read exactly the documents the PM named. Do not widen it.
+1. **Take the scope.** The documents are listed at the top of this prompt. Read exactly those and
+   do not widen the set — the PM chose them by opening one, not by describing a filter.
    *Done when:* every named path has been read in full, and you can list them.
 
 2. **Find, then cut.** For each document, ask the four questions above. Then remove every candidate
@@ -70,8 +71,10 @@ and is not — it is a measured open question (`pm-decisions.md` 491–503).
    guessing. Where the withheld test fires, propose nothing.
    *Done when:* every finding either carries an exact-match proposal or is explicitly withheld.
 
-4. **File the review.** Pick a run id (`doc-review-<UTC-timestamp>`), then write
-   `workspace/state/reviews/<run-id>.json` with exactly this shape:
+4. **File the review.** Pick a run id (`doc-review-<UTC-timestamp>`). Write it to the reviews
+   directory **named at the top of this prompt** — an absolute path that already exists. Do not
+   guess a `workspace/…` path: a product repo using the PMOS kit has no `workspace/` folder, and
+   inventing one files the review where nothing will read it. The shape:
 
    ```json
    {
@@ -94,11 +97,13 @@ and is not — it is a measured open question (`pm-decisions.md` 491–503).
 
    `withheld` is a required boolean on every finding and is never inferred. A withheld finding sets
    `"proposal": null` and adds `"withheld_reason"`.
-   *Done when:* the file is valid JSON and `GET /api/review` returns `ok: true` for it. If it returns
-   `422`, the contract rejected a finding — fix it; do not file it anyway.
+   *Done when:* the file is valid JSON in the directory the prompt named, and `GET /api/review`
+   returns `ok: true` for it. If it returns `422`, the contract rejected a finding — fix it; do not
+   file it anyway.
 
-5. **Tell the PM it is ready.** Read `workspace/state/needs.json` (a missing file is `[]`), append
-   exactly this object, and write the whole array back — it must stay a valid JSON array:
+5. **Tell the PM it is ready.** Read the needs-you queue **named at the top of this prompt** (a
+   missing file is `[]`), append exactly this object, and write the whole array back — it must stay
+   a valid JSON array. If the prompt said there is none, skip this step:
 
    ```json
    {"run_id":"<run-id>","kind":"review","initiative_id":"workspace-review-and-edit","question":"Document review — <n> findings"}