create-pmos 0.7.2 → 0.8.0

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,114 +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.** Read exactly the documents the PM named. Do not widen it.
-   *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>`), then write
-   `workspace/state/reviews/<run-id>.json` with exactly this 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 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:
-
-   ```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.