create-pmos 0.7.0 → 0.7.1

package/README.md

@@ -333,6 +333,37 @@ 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.1
+
+**A correction to 0.7.0 — read this if you used the review surface.**
+
+0.7.0 shipped the summoned document review with a defect in the part that records *why* you changed
+an agent's proposal. The client sent a fixed reason — `incomplete` — on **every** edit, whatever the
+actual reason was. So any correction record written by 0.7.0 carries a reason that is very likely
+false, in the one file whose whole purpose is to make the human-correction rate trustworthy.
+
+If you ran a review on 0.7.0, treat the `reason` field in `planning/runs/correction-records.jsonl` as
+unreliable. Everything else in those records — the agent's text, your text, the attribution — is
+sound.
+
+- **You pick the reason now.** Applying an edit asks *what was wrong with it?* and offers
+  `factually wrong · incomplete · wrong scope · style · other…`. It **nudges rather than defaulting**,
+  and `other` asks for a few words. Dismiss is still one click — friction belongs on the action that
+  teaches something, not the common one.
+- **A half-applied state is now impossible.** The record was validated *after* the document was
+  written, so a missing reason could leave your file changed with nothing recorded. Validation runs
+  first: every refusal leaves the repository byte-identical.
+- **The counters are on the surface, and honest.** Dispositions, corrections and the action rate are
+  derived from the records themselves. Quiet-on-clean reads **`not measured`** rather than a
+  flattering zero — measuring it needs a corpus of documents known to be clean, which does not exist
+  yet.
+
+**The disclosure from 0.7.0 still stands**, and it matters more than this release note: the review
+surface has **not** been through its own review gate. Its false-positive rate is unmeasured. It
+withholds any proposal that would close a recorded open question or overwrite a decision — that guard
+is tested, including in a real browser — but nothing yet tells you how often its findings are simply
+wrong. Use it on documents you are willing to read carefully.
+
 ## What's new in 0.7.0
 
 **The workspace GUI has layouts.** Until now it had exactly one arrangement: a fixed sidebar, the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "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@a2227ff
+kernel-source: pmos@0c57593
 assembled: 2026-07-28
 mode: vendor

package/workspace/public/app.js

@@ -1905,9 +1905,27 @@ function reviewBody(p) {
     <div class="rv-lede">${esc(lede)}</div>
     <div class="rv-sub">Read ${p.read.map((r) => `<span class="mono">${esc(r)}</span>`).join(', ')}.</div>
     ${p.findings.map((f, i) => rvFinding(f, i)).join('')}
-    <div class="rv-tail">Read ${p.read.length} document${p.read.length === 1 ? '' : 's'}. <b>Nothing written.</b></div>
+    <div class="rv-tail">Read ${p.read.length} document${p.read.length === 1 ? '' : 's'}. <b>Nothing written.</b>${rvStats(p.stats)}</div>
   </div>`;
 }
+// The PRD's success signal, on the face of the surface. Action rate comes straight off the correction
+// records. Quiet-rate CANNOT — it needs a corpus with a labelled clean class, which does not exist —
+// so it says "not measured" rather than rendering a flattering zero. An unmeasured number shown as a
+// number is the watermelon this whole surface exists to catch.
+function rvStats(s) {
+  if (!s || !s.dispositions) return '';
+  const pct = (v) => (v == null ? null : `${Math.round(v * 100)}%`);
+  const bits = [
+    `${s.dispositions} disposition${s.dispositions === 1 ? '' : 's'}`,
+    `${s.corrections} correction${s.corrections === 1 ? '' : 's'}`,
+    `acted on ${pct(s.action_rate)}`,
+    `quiet on clean <i>not measured</i>`,
+  ];
+  const warn = s.inferred_attributions
+    ? ` <b class="rv-bad">${s.inferred_attributions} inferred attribution${s.inferred_attributions === 1 ? '' : 's'}</b>`
+    : '';
+  return `<div class="rv-stats">${bits.join(' · ')}${warn}</div>`;
+}
 function rvFinding(f, i) {
   const ev = (f.evidence || []).map((e) => `${e.file}:${e.line}`).join(' · ');
   // Three states, and only one of them offers a write. `settled` is terminal for this review.
@@ -1930,6 +1948,13 @@ function rvFinding(f, i) {
 // The edit surface: opens IN PLACE under the finding — no modal, no mode switch, no navigation.
 // Gutter change bars are the VS Code cue; the replaced lines sit struck through above the new ones.
 // Cancel needs no write path at all — it just closes, which is the whole of "Cancel writes nothing".
+// The reason taxonomy, deliberately short. A vocabulary nobody can hold in their head gets skipped,
+// and a skipped reason is a record that teaches nothing. Values match correction-record.js's REASONS;
+// the server rejects anything outside it, so this list can never drift into inventing one.
+const RV_REASONS = [
+  ['factually-wrong', 'factually wrong'], ['incomplete', 'incomplete'],
+  ['wrong-scope', 'wrong scope'], ['style', 'style'], ['other', 'other…'],
+];
 function rvEditor(f, i) {
   const before = (f.proposal && f.proposal.before) || '';
   const after = (f.proposal && f.proposal.after) || '';
@@ -1940,6 +1965,11 @@ function rvEditor(f, i) {
       ${before.split('\n').map((l) => `<div class="rv-l was"><span class="g"></span><span class="t">${esc(l)}</span></div>`).join('')}
     </div>
     <textarea class="rv-ta" data-rv-ta="${i}" spellcheck="false" rows="${Math.min(12, Math.max(3, nl(after) + 1))}">${esc(after)}</textarea>
+    <div class="rv-reason" data-rv-reason="${i}">
+      <span class="rv-only">What was wrong with it?</span>
+      ${RV_REASONS.map((r) => `<button class="rv-rz" data-rv-rz="${i}" data-val="${r[0]}">${esc(r[1])}</button>`).join('')}
+    </div>
+    <input class="rv-note" data-rv-note="${i}" hidden placeholder="in a few words…" aria-label="Why" autocomplete="off" />
     <div class="rv-acts">
       <button data-rv-save="${i}">Apply</button>
       <button class="q" data-rv-cancel="${i}">Cancel</button>
@@ -1972,13 +2002,40 @@ function wireReview() {
   });
   $('docBody').querySelectorAll('[data-rv-apply]').forEach((b) => b.onclick = () => rvDispose(F(b.dataset.rvApply), 'apply'));
   $('docBody').querySelectorAll('[data-rv-dismiss]').forEach((b) => b.onclick = () => rvDispose(F(b.dataset.rvDismiss), 'dismiss'));
+  // The reason tap. Required on an edit (R8 / correction-record.js) — an edit is where the agent was
+  // wrong in a way worth knowing, and a record that cannot say HOW is the self-report this feature
+  // exists to replace. Dismiss stays one click: friction belongs on the informative action, not the
+  // common one (PRD open question 2).
+  $('docBody').querySelectorAll('[data-rv-rz]').forEach((b) => b.onclick = () => {
+    const n = b.dataset.rvRz;
+    const row = $('docBody').querySelector(`[data-rv-reason="${n}"]`);
+    row.querySelectorAll('.rv-rz').forEach((x) => x.classList.toggle('on', x === b));
+    row.dataset.picked = b.dataset.val;
+    const note = $('docBody').querySelector(`[data-rv-note="${n}"]`);
+    note.hidden = b.dataset.val !== 'other';                 // 'other' is only useful with words
+    if (b.dataset.val === 'other') note.focus();
+    const nudge = row.querySelector('.rv-nudge'); if (nudge) nudge.remove();
+  });
   $('docBody').querySelectorAll('[data-rv-save]').forEach((b) => b.onclick = () => {
     const n = b.dataset.rvSave;
+    const row = $('docBody').querySelector(`[data-rv-reason="${n}"]`);
+    const picked = row && row.dataset.picked;
+    if (!picked) {
+      // An inline nudge, not a modal and not a silent default. Defaulting is what produced the bug
+      // this replaces: every edit recorded "incomplete" whether or not it was.
+      if (!row.querySelector('.rv-nudge')) {
+        const s = document.createElement('span');
+        s.className = 'rv-nudge'; s.textContent = 'Pick one — the record is worth nothing without it.';
+        row.appendChild(s);
+      }
+      return;
+    }
+    const note = $('docBody').querySelector(`[data-rv-note="${n}"]`);
     const ta = $('docBody').querySelector(`[data-rv-ta="${n}"]`);
-    rvDispose(F(n), 'edit', ta ? ta.value : '');
+    rvDispose(F(n), 'edit', ta ? ta.value : '', picked, note && !note.hidden ? note.value : undefined);
   });
 }
-async function rvDispose(f, disposition, pmText) {
+async function rvDispose(f, disposition, pmText, reason, reasonNote) {
   if (!f) return;
   const rv = state.review || {};
   // The client sends back the exact text it rendered; the server re-derives the diff and refuses if
@@ -1995,7 +2052,7 @@ async function rvDispose(f, disposition, pmText) {
   const body = {
     ws: state.wsId, disposition, finding: f, rendered_after: renderedAfter,
     pm_text: disposition === 'edit' ? pmText : undefined,
-    reason: disposition === 'edit' ? 'incomplete' : undefined,   // TODO: the reason tap (PRD open q2)
+    reason, reason_note: reasonNote,          // the PM's own word — never defaulted, never inferred
     run_id: rv.id, initiative_id: 'workspace-review-and-edit',
   };
   let out = {};

package/workspace/public/styles.css

@@ -986,3 +986,22 @@ details.tree>summary:hover{color:var(--text-2)}
   padding:8px 11px;background:rgba(72,213,151,.06);color:var(--text-2);
   font-family:var(--mono);font-size:11.5px;line-height:1.8;outline:none}
 .rv-ta:focus{border-color:var(--accent);border-left-color:var(--ok)}
+
+/* the reason tap — required on an edit, and never defaulted. The nudge is inline, not a modal:
+   a silent default is exactly the bug this replaced (every edit recorded "incomplete"). */
+.rv-reason{display:flex;gap:7px;align-items:center;flex-wrap:wrap;margin-top:10px}
+.rv-rz{padding:0 9px;height:28px;border-radius:999px;border:1px solid var(--border-strong);
+  background:var(--chip);font-size:11.5px;color:var(--text-3)}
+.rv-rz:hover{background:var(--card-hover);color:var(--text)}
+/* Selected reads as accent TEXT on a wash, not a filled pill: nothing else on this surface carries
+   a solid fill, and no token exists for text-on-accent because no component here needed one. */
+.rv-rz.on{background:var(--accent-wash);border-color:var(--accent);color:var(--accent-text);font-weight:600}
+.rv-nudge{font-size:11.5px;color:var(--warn-text);flex-basis:100%}
+.rv-note{width:100%;box-sizing:border-box;margin-top:8px;border:1px solid var(--border);
+  border-radius:7px;padding:7px 10px;background:var(--chip);color:var(--text-2);
+  font-family:var(--sans);font-size:12px;outline:none}
+.rv-note:focus{border-color:var(--accent)}
+/* the success-signal counters — one quiet line, and an unmeasured number says so */
+.rv-stats{margin-top:6px;font-family:var(--mono);font-size:10.5px;color:var(--text-dim);line-height:1.7}
+.rv-stats i{font-style:normal;color:var(--warn-text)}
+.rv-stats .rv-bad{color:var(--bad);font-weight:600}

package/workspace/server.js

@@ -1904,19 +1904,30 @@ async function handleRequest(req, res) {
     // Merge in what the PM has already settled, so a disposed finding renders as settled rather than
     // being offered twice. Read-only: dispositions live in the correction records, not in the review.
     const settled = {};
+    const records = [];
     try {
       const txt = fs.readFileSync(path.join(w.root, 'planning', 'runs', 'correction-records.jsonl'), 'utf8');
       for (const line of txt.split('\n')) {
         if (!line.trim()) continue;
-        try { const r = JSON.parse(line); if (r && r.finding_title) settled[r.finding_title] = r.disposition; } catch {}
+        try {
+          const r = JSON.parse(line);
+          if (!r) continue;
+          records.push(r);
+          if (r.finding_title) settled[r.finding_title] = r.disposition;
+        } catch {}
       }
     } catch {}
+    // The PRD's success signal is explicit that the counters are part of the build, not a follow-up:
+    // action rate must be derivable off the records with no manual counting. quiet-rate is NOT
+    // derivable here — it needs a corpus with a labelled CLEAN class, which does not exist — so it is
+    // reported as null and rendered as "not measured" rather than as a flattering zero.
+    const stats = { ...correctionRecord.summarise(records), quiet_rate: findingContract.quietRate(null, null) };
     const findings = review.findings.map((f) => ({
       ...f,
       applyable: findingContract.isApplyable(f),      // the client asks the contract, never re-derives it
       settled: settled[f.title] || null,
     }));
-    return json(res, { ok: true, id: pick.replace(/\.json$/, ''), read: review.read, at: review.at || null, findings, reviews: files.length });
+    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/dispose' && req.method === 'POST') {
     // The ONLY write path this surface has (workspace-review-and-edit R6/R8/R11). The reader was
@@ -1949,6 +1960,19 @@ async function handleRequest(req, res) {
       return json(res, { ok: false, error: 'this finding offers nothing to apply — it is context, and yours to settle' }, 400);
     }
 
+    // R8, and it must happen BEFORE the write. buildRecord depends on nothing the write produces, and
+    // validating it after would let a missing reason leave the document changed with no record behind
+    // it — a half-applied state whose whole point was to be impossible. Refuse first, touch the file
+    // second: every rejection below this line leaves the repository byte-identical.
+    const built = correctionRecord.buildRecord({
+      run_id: body.run_id, initiative_id: body.initiative_id, finding: f, disposition,
+      pm_text: body.pm_text, reason: body.reason, reason_note: body.reason_note,
+      pm: body.pm || 'wawan', at: nowISO(),
+    });
+    if (!built.ok) {
+      return json(res, { ok: false, error: 'no correction record could be written, so nothing was changed', errors: built.errors }, 400);
+    }
+
     let wrote = null;
     if (writes) {
       // Path guard, identical to every read on this surface (R12): traversal and cross-workspace
@@ -1983,18 +2007,6 @@ async function handleRequest(req, res) {
       wrote = f.file;
     }
 
-    // R8: the record is built only where attribution is KNOWN. buildRecord refuses anything that
-    // would need inference, and a refusal here means no record is written at all — never a guess.
-    const built = correctionRecord.buildRecord({
-      run_id: body.run_id, initiative_id: body.initiative_id, finding: f, disposition,
-      pm_text: body.pm_text, reason: body.reason, reason_note: body.reason_note,
-      pm: body.pm || 'wawan', at: nowISO(),
-    });
-    if (!built.ok) {
-      // The document may already have been written — say so rather than imply a clean failure.
-      return json(res, { ok: false, error: 'no correction record written (attribution would have to be inferred)', errors: built.errors, wrote }, 400);
-    }
-
     // Curated record, tracked and append-only — deliberately NOT stateDirFor()'s runtime directory
     // (PRD open question 1; pm-decisions.md 491–503 keeps that boundary the PM's to settle).
     const sink = path.join(w.root, 'planning', 'runs', 'correction-records.jsonl');