create-pmos 0.7.3 → 0.9.0

package/workspace/lib/correction-record.js

@@ -1,127 +0,0 @@
-/* correction-record — what a PM disposition leaves behind. (workspace-review-and-edit · R8/R9)
- *
- * The north star is human correction rate per agent run, and its numerator is currently a
- * self-reported integer: all four runs in planning/runs/agent-runs.jsonl carry
- * "human_corrections": 0 with no artifact behind the number. correction-signal-derive.skill
- * explains why the obvious fix does not reach it — "pre-commit conversational steering is
- * git-invisible and stays the self-report's lane."
- *
- * This module builds the artifact for that lane, under one rule that is not negotiable:
- *
- *   ATTRIBUTION IS NEVER INFERRED.
- *
- * A record exists only for text an agent PROPOSED in this review and the PM then disposed of.
- * That is the single case where authorship is known rather than guessed — no git blame, no
- * "the file changed while session X was live" timing heuristic. correction-signal-derive.skill
- * states the rule this upholds: "Never guess an attribution. A commit you cannot confidently
- * classify is ambiguous: flagged to the PM, held OUT of the score." A record that would need
- * inference is not written at all (sprint criterion 7), because a manufactured attribution
- * poisons the exact metric this exists to feed.
- *
- * It stores WHY and BY WHOM. It does not store the diff (R9) — git already holds what changed.
- */
-'use strict';
-(function (root, factory) {
-  const api = factory();
-  if (typeof module !== 'undefined' && module.exports) module.exports = api;
-  else root.CorrectionRecord = api;
-})(typeof self !== 'undefined' ? self : this, function () {
-
-  const DISPOSITIONS = new Set(['apply', 'edit', 'dismiss']);
-
-  /* Reasons the PM taps. Deliberately short — a taxonomy nobody can hold in their head gets
-   * skipped, and a skipped reason is a record that teaches nothing. 'other' carries free text. */
-  const REASONS = new Set(['factually-wrong', 'incomplete', 'wrong-scope', 'style', 'not-now', 'other']);
-
-  /* Required on `edit` (the agent was wrong in a way worth knowing) and on `dismiss` only when
-   * the PM chooses to give one (PRD open question 2: optional on dismiss, required on edit —
-   * the most common action must not carry the most friction). Never required on `apply`:
-   * accepting a proposal unchanged is not a correction and must not inflate the numerator. */
-  function reasonRequired(disposition) {
-    return disposition === 'edit';
-  }
-
-  /** Is this a correction at all? Applying an agent's proposal unchanged is agreement. */
-  function isCorrection(disposition) {
-    return disposition === 'edit' || disposition === 'dismiss';
-  }
-
-  const isStr = (v) => typeof v === 'string' && v.trim().length > 0;
-
-  /**
-   * Build a record from a disposition, or refuse.
-   *   input = { run_id, initiative_id, finding, disposition, pm_text?, reason?, reason_note?, pm, at }
-   * Returns { ok: true, record } or { ok: false, errors[] }. Never throws, never guesses.
-   */
-  function buildRecord(input) {
-    const e = [];
-    const i = input || {};
-
-    if (!DISPOSITIONS.has(i.disposition)) e.push(`disposition must be one of ${[...DISPOSITIONS].join(' | ')}`);
-    if (!i.finding || typeof i.finding !== 'object') e.push('finding is required — the record is anchored to what was proposed');
-    if (!isStr(i.pm)) e.push('pm is required');
-    if (!isStr(i.at)) e.push('at (ISO 8601) is required');
-
-    // ── the attribution rule (R8) ───────────────────────────────────────────────
-    // The agent's text must be present and must have come from THIS review's proposal. Anything
-    // else would mean deriving authorship from git or from timing, which is exactly forbidden.
-    const f = i.finding || {};
-    const agentText = f.proposal && f.proposal.after;
-    if (i.disposition !== 'dismiss' && !isStr(agentText)) {
-      e.push('no agent-proposed text on this finding — attribution would have to be inferred, so no record is written (R8)');
-    }
-    if (f.withheld === true) {
-      // A withheld finding was never applyable, so a disposition other than dismiss is incoherent
-      // and would imply the containment guard leaked.
-      if (i.disposition !== 'dismiss') e.push('a withheld finding can only be dismissed — it never offered a change (R7)');
-    }
-
-    if (i.disposition === 'edit' && !isStr(i.pm_text)) {
-      e.push('pm_text is required on an edit — the record exists to hold what the PM wrote instead');
-    }
-    if (reasonRequired(i.disposition) && !REASONS.has(i.reason)) {
-      e.push(`reason is required on an edit and must be one of ${[...REASONS].join(' | ')}`);
-    }
-    if (i.reason != null && !REASONS.has(i.reason)) e.push(`unknown reason '${i.reason}'`);
-    if (i.reason === 'other' && !isStr(i.reason_note)) e.push("reason 'other' requires reason_note");
-
-    if (e.length) return { ok: false, errors: e };
-
-    return {
-      ok: true,
-      record: {
-        run_id: isStr(i.run_id) ? i.run_id : null,
-        initiative_id: isStr(i.initiative_id) ? i.initiative_id : null,
-        file: f.file || null,
-        finding_title: f.title || null,
-        disposition: i.disposition,
-        is_correction: isCorrection(i.disposition),
-        // attribution: known, because the agent proposed it here and the PM answered it here.
-        attribution: 'proposed-in-review',
-        agent_text: isStr(agentText) ? agentText : null,
-        pm_text: isStr(i.pm_text) ? i.pm_text : null,
-        reason: i.reason || null,
-        reason_note: isStr(i.reason_note) ? i.reason_note : null,
-        pm: i.pm,
-        at: i.at,
-      },
-    };
-  }
-
-  /** Roll records up into the numbers the PRD's success signal names. No manual counting
-   *  (sprint criterion 8): both come straight off the records. */
-  function summarise(records) {
-    const r = Array.isArray(records) ? records : [];
-    const total = r.length;
-    const corrections = r.filter((x) => x && x.is_correction).length;
-    const acted = r.filter((x) => x && (x.disposition === 'apply' || x.disposition === 'edit')).length;
-    return {
-      dispositions: total,
-      corrections,
-      action_rate: total === 0 ? null : acted / total,
-      inferred_attributions: r.filter((x) => x && x.attribution !== 'proposed-in-review').length,
-    };
-  }
-
-  return { DISPOSITIONS, REASONS, reasonRequired, isCorrection, buildRecord, summarise };
-});

package/workspace/lib/finding-contract.js

@@ -1,162 +0,0 @@
-/* finding-contract — what a review finding must be, and what the PM may do with it.
- * (workspace-review-and-edit · R3/R7)
- *
- * Used on BOTH sides, like preview-kind:
- *   - server.js requires it to validate a reviewer skill's output before it reaches the client
- *   - the browser loads it as /lib/finding-contract.js so the renderer asks the SAME question
- * so the contract, the endpoint and the UI can never disagree about what is applyable.
- *
- * The one security-critical function is isApplyable(). It decides whether an Apply control
- * exists at all. R7's rule is that a proposal which would close a recorded open question or
- * overwrite a PM decision is surfaced as CONTEXT with no Apply affordance — the absence of the
- * control is the mechanism, and a warning label is explicitly not a substitute. The rubric makes
- * this a hard floor (dim 2 must = 1: zero Apply controls ever rendered for a withheld finding),
- * so this boolean is the whole containment story and it is unit-tested directly.
- *
- * The second load-bearing rule is self_undetectable (R3). A review that emits lint findings
- * becomes a linter the PM stops reading, and "judgement-grade" is not enforceable by inspecting
- * the finding's text. So the contract inverts it: every finding must NAME what the artifact
- * cannot see about itself. A reviewer that cannot fill that line has not found this class of
- * defect, and the finding is rejected structurally rather than by taste.
- */
-'use strict';
-(function (root, factory) {
-  const api = factory();
-  if (typeof module !== 'undefined' && module.exports) module.exports = api;
-  else root.FindingContract = api;
-})(typeof self !== 'undefined' ? self : this, function () {
-
-  /* Finding kinds the review must NOT emit (R3). These are owned by the Frontmatter Gate and the
-   * linters; re-reporting them here is how counsel decays into noise. Declared by the reviewer
-   * and rejected on sight — a blocklist catches the honest mistake, and self_undetectable below
-   * catches the dishonest one. */
-  const MECHANICAL_KINDS = new Set([
-    'frontmatter', 'schema', 'link', 'broken-link', 'missing-path', 'path',
-    'string-match', 'regex', 'count', 'occurrence', 'spelling', 'typo', 'formatting', 'lint',
-  ]);
-
-  const isStr = (v) => typeof v === 'string' && v.trim().length > 0;
-
-  /** Reject a finding that a linter should have owned (R3). Kind is declared, not sniffed. */
-  function isMechanical(f) {
-    return !!f && isStr(f.kind) && MECHANICAL_KINDS.has(f.kind.trim().toLowerCase());
-  }
-
-  /* THE guardrail (R7). An Apply control may exist only when the finding is not withheld AND
-   * actually carries a change to make. Both halves matter: `withheld` is the PM-decision guard,
-   * and a null proposal is the context class (nothing to apply). Anything unexpected — a missing
-   * field, a malformed proposal, a non-boolean withheld — resolves to NOT applyable. This
-   * function fails closed on purpose; an unparseable finding must never grow a button. */
-  function isApplyable(f) {
-    if (!f || typeof f !== 'object') return false;
-    if (f.withheld === true) return false;
-    if (f.withheld !== false) return false;          // must be explicitly declared, never inferred
-    const p = f.proposal;
-    if (!p || typeof p !== 'object') return false;
-    return isStr(p.before) || isStr(p.after);        // a pure insertion has no `before`
-  }
-
-  /** Validate one finding against the contract. Returns { ok, errors[] } — never throws. */
-  function validateFinding(f) {
-    const e = [];
-    if (!f || typeof f !== 'object') return { ok: false, errors: ['finding is not an object'] };
-
-    if (!isStr(f.title)) e.push('title is required');
-    if (!isStr(f.file)) e.push('file is required');
-    if (!isStr(f.argument)) e.push('argument is required — a finding without reasoning is an assertion');
-
-    // R3: name what the artifact cannot see about itself, or this is not the class of defect
-    // this review exists to surface.
-    if (!isStr(f.self_undetectable)) {
-      e.push('self_undetectable is required — name what this artifact cannot detect about itself (R3)');
-    }
-    if (isMechanical(f)) {
-      e.push(`kind '${f.kind}' is mechanically findable and belongs to lint, not to this review (R3)`);
-    }
-
-    // Evidence is file:line, plural, and cited — an un-sourced finding is a guess.
-    if (!Array.isArray(f.evidence) || f.evidence.length === 0) {
-      e.push('evidence[] is required — at least one file:line citation');
-    } else {
-      f.evidence.forEach((ev, i) => {
-        if (!ev || typeof ev !== 'object') { e.push(`evidence[${i}] is not an object`); return; }
-        if (!isStr(ev.file)) e.push(`evidence[${i}].file is required`);
-        if (!Number.isInteger(ev.line) || ev.line < 1) e.push(`evidence[${i}].line must be a positive integer`);
-      });
-    }
-
-    // withheld is declared, never inferred — the containment guard must be explicit (R7).
-    if (typeof f.withheld !== 'boolean') {
-      e.push('withheld must be an explicit boolean (R7) — it is never inferred');
-    }
-    // A withheld finding carries no proposal at all. Carrying one invites a later refactor to
-    // "just render it disabled", which is exactly the failure dim 2 forbids.
-    if (f.withheld === true && f.proposal != null) {
-      e.push('a withheld finding must carry proposal: null — it has no change to offer (R7)');
-    }
-    if (f.withheld === true && !isStr(f.withheld_reason)) {
-      e.push('withheld_reason is required — say why this is yours to settle (R7)');
-    }
-
-    if (f.proposal != null) {
-      const p = f.proposal;
-      if (typeof p !== 'object') e.push('proposal must be an object or null');
-      else {
-        if (p.before != null && typeof p.before !== 'string') e.push('proposal.before must be a string or absent');
-        if (!isStr(p.after) && !isStr(p.before)) e.push('proposal must change something (before and/or after)');
-      }
-    }
-
-    return { ok: e.length === 0, errors: e };
-  }
-
-  /** Validate a whole review payload. One bad finding fails the review — partial trust is worse
-   *  than none on a surface whose only job is to be believed. */
-  function validateReview(r) {
-    const e = [];
-    if (!r || typeof r !== 'object') return { ok: false, errors: ['review is not an object'] };
-    if (!Array.isArray(r.read) || r.read.length === 0) {
-      e.push('read[] is required — the review states what it actually read (R2)');
-    }
-    if (!Array.isArray(r.findings)) {
-      e.push('findings[] is required (an empty array is a valid, and good, review — R10)');
-    } else {
-      r.findings.forEach((f, i) => {
-        const v = validateFinding(f);
-        if (!v.ok) v.errors.forEach((msg) => e.push(`findings[${i}]: ${msg}`));
-      });
-    }
-    return { ok: e.length === 0, errors: e };
-  }
-
-  /** Quiet-rate over a scored corpus (R10, rubric dim 1). Documents read with zero findings
-   *  against them, divided by documents believed clean. The rubric's binding number. */
-  function quietRate(reviewed, cleanPaths) {
-    const clean = new Set(cleanPaths || []);
-    if (clean.size === 0) return null;                  // no clean class ⇒ no valid precision number
-    let quiet = 0;
-    for (const p of clean) {
-      const noisy = (reviewed || []).some((f) => f && f.file === p);
-      if (!noisy) quiet++;
-    }
-    return quiet / clean.size;
-  }
-
-  /** Action rate (PRD success signal): Apply+Edit ÷ all dispositions. Dismiss-heavy means the
-   *  review is noise the PM is politely declining, whatever it scored. */
-  function actionRate(dispositions) {
-    const d = (dispositions || []).filter((x) => x === 'apply' || x === 'edit' || x === 'dismiss');
-    if (d.length === 0) return null;
-    return d.filter((x) => x !== 'dismiss').length / d.length;
-  }
-
-  return {
-    MECHANICAL_KINDS,
-    isMechanical,
-    isApplyable,
-    validateFinding,
-    validateReview,
-    quietRate,
-    actionRate,
-  };
-});

package/workspace/skills/doc-review.skill

@@ -1,119 +0,0 @@
----
-name: doc-review
-label: "Review documents"
-description: "Read the planning documents you name and report only defects the artifact cannot detect about itself — never lint. Each finding carries its evidence and, where one exists, a proposed change you dispose of."
-run: agent
-agent: claude
-output:
-  - Read
-  - Findings
-  - Withheld
----
-
-You are running the "Review documents" skill in this PMOS workspace (local, file mode). Work only
-from this repository's own files, git, and CLIs — no network (D54).
-
-Goal: surface defects in the named documents that **the artifact cannot detect about itself**, and
-file them as a contract-checked review the PM disposes of one at a time.
-
-## What counts as a finding — and what does not
-
-The whole value of this review is that the PM keeps reading it. A review that reports what a linter
-already reports becomes a linter with manners, and gets ignored by Thursday.
-
-**Report only defects the document cannot detect about itself.** The four kinds that recur:
-
-- **A metric that does not measure its own claim** — a PRD bets on an outcome, then defines success as
-  a capability demo, so it can score full marks and move the outcome not at all.
-- **An anchor that cannot score wrong** — a rubric dimension whose anchors award credit for descoping,
-  or that cannot distinguish a correct implementation from an absent one.
-- **A gate that scripts away its own question** — a rubric prescribing the Acceptance Gate as the same
-  checklist it already scored, turning D12's strategic judgement into a second review pass.
-- **A constraint contradicted elsewhere** — a non-goal or design rule in one shipped document that
-  silently rules out what another document proposes.
-
-**NEVER report** — these belong to lint and the Frontmatter Gate, and emitting them fails the
-contract outright: frontmatter or schema validity · broken links or missing paths · string/regex
-matches · counting occurrences · spelling, typos, formatting.
-
-**Say nothing when there is nothing to say.** An empty findings list is a correct and valued outcome.
-Do not pad a review to look thorough — a false finding costs the PM more than a missed one, because
-they pay for it every time.
-
-## The withheld class — where you must NOT propose a fix
-
-Some defects are not defects. Before proposing any change, ask: **would applying this close a
-question the PM has parked, or overwrite a decision they recorded?** Check `pm-decisions.md`,
-`DECISIONS.md`, and the document's own history.
-
-If yes, the finding is **withheld**: `"withheld": true`, `"proposal": null`, and a
-`"withheld_reason"` saying why it is the PM's to settle. The client renders no Apply control for it —
-the absence of the button is the guard, so a withheld finding carrying a proposal is rejected by the
-contract, not merely discouraged.
-
-The recorded instance: `CLAUDE.md` points file-mode state at `pmos/state/*.jsonl`, which looks stale
-and is not — it is a measured open question (`pm-decisions.md` 491–503).
-
-## Procedure
-
-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
-   that a regex could have found, and every one you cannot evidence to a specific line.
-   *Done when:* each surviving finding names, in one sentence, what the artifact cannot see about
-   itself — the `self_undetectable` field. If you cannot write that sentence, drop the finding.
-
-3. **Propose, or withhold.** Where a change would genuinely fix it, write `proposal.before` as text
-   copied **verbatim** from the file and `proposal.after` as its replacement. `before` must appear in
-   the file **exactly once** — the apply path refuses a stale or ambiguous anchor rather than
-   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>`). 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
-   {
-     "at": "<ISO 8601>",
-     "read": ["planning/prd/example-prd.md"],
-     "findings": [
-       {
-         "title": "One sentence, the defect stated plainly.",
-         "file": "planning/prd/example-prd.md",
-         "kind": "metric-claim-mismatch",
-         "argument": "Why this is a defect — the reasoning, not a restatement.",
-         "self_undetectable": "What this artifact cannot see about itself.",
-         "evidence": [{ "file": "planning/prd/example-prd.md", "line": 17 }],
-         "withheld": false,
-         "proposal": { "before": "<verbatim text from the file>", "after": "<replacement>" }
-       }
-     ]
-   }
-   ```
-
-   `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 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 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"}
-   ```
-   *Done when:* `needs.json` is a valid array containing the new object.
-
-## Output contract — produce EXACTLY these sections
-
-- **Read** — the documents actually read, one per line.
-- **Findings** — one line per finding: the title and its `file:line`. `None this review.` if empty,
-  which is a good outcome, not a failed run.
-- **Withheld** — findings deliberately left for the PM, with the one-line reason. `None this review.`
-  if empty.