create-pmos 0.5.0 → 0.6.0

package/payload/okf/core/templates/prototype-brief-template.md

@@ -1,24 +1,28 @@
 ---
 type: Template
 title: Prototype Brief Template
-description: The scaffold for a QUICK leg-A prototype brief (D60) — the idea, the user, the moment, the feel, draft copy seeds. Deliberately short; if it needs PRD-level detail the flow has failed its purpose. Copy into prototype/<initiative-id>/brief.md and set it as the initiative's prd_path.
+description: The scaffold for a QUICK leg-A prototype brief (D60) — the idea, the judgement it exercises, the user, the moment, the feel, draft copy seeds. Works for any medium, not just UI (2026-07-24 amendment). Deliberately short; if it needs PRD-level detail the flow has failed its purpose. Copy into prototype/<initiative-id>/brief.md and set it as the initiative's prd_path.
 tags: [template, prototype, design, lane]
-timestamp: 2026-07-21
+timestamp: 2026-07-24
 ---
 
 # Prototype Brief Template
 
 **Situating context:** The [prototype lane](/okf/products/pmos/adr/d60-prototype-loop.md)'s contract
-artifact. The PM writes THIS — quick, sketchy, incomplete is fine — and the **design agent does the
-rest**: picks up the product's design system, applies the
-[design-craft layer](/okf/core/concepts/design-craft.md), drafts real copy, and returns divergent
-lookable options. The brief is deliberately NOT a PRD: it exists so the PM can see something *before*
-committing to a spec. If filling it in starts to feel like writing requirements, stop — that detail
-belongs in the PRD that follows a successful prototype, not here.
+artifact. The PM writes THIS — quick, sketchy, incomplete is fine — and the **agent does the rest**:
+picks up the artifact class's conventions (a design system for UI; SKILL-FORMAT, D19 ACI,
+migration/RLS conventions elsewhere), applies that class's craft, drafts real content, and returns
+divergent specimens. The brief is deliberately NOT a PRD: it exists so the PM can examine something
+*before* committing to a spec. If filling it in starts to feel like writing requirements, stop — that
+detail belongs in the PRD that follows a successful prototype, not here.
+
+**Any medium** (2026-07-24 amendment to D60): the lane is not UI-gated. A specimen may be a lookable
+screen, a worked sample output, call/response transcripts, or a schema sketch — whichever is the
+cheapest thing that lets the PM exercise the judgement below.
 
 > Usage: copy into `prototype/<initiative-id>/brief.md`; set it as the initiative's `prd_path`
 > (`create_initiative`, `type: 'prototype'`). Every section may be a single sentence. Only the first
-> two are required.
+> three are required.
 
 ---
 
@@ -35,30 +39,50 @@ belongs in the PRD that follows a successful prototype, not here.
 ## Who it's for, and the moment they'd use it (required)
 <!-- The user and the situation — "a PM opening the board on Monday morning", not a persona doc. -->
 
+## The judgement you need to make (required)
+<!-- One line: what you cannot decide from a description alone, and so need to SEE an instance of.
+     "Whether this actually reads as calm rather than sparse." "Whether this explainer actually
+     teaches someone who's never seen the region." "Whether this API feels right to call."
+     This is the specimen test written down — it steers the format, the grilling, and the
+     disposition. If you can't name such a judgement, this may not be a prototype (see the
+     discovery lane, whose deliverable is a learning, not a validated direction). -->
+
+## Specimen format
+<!-- Leave blank to let the agent propose it and say why. The principle is the CHEAPEST thing that
+     lets you exercise the judgement above: lookable HTML, a worked sample output on real input,
+     call/response transcripts, a schema sketch with example rows, the actual strings. -->
+
 ## How it should feel
 <!-- Adjectives and references beat specification: "calm, dense, fast to scan", "more like a
-     cockpit than a report". Leave blank to let the agent propose. -->
+     cockpit than a report". Applies beyond visuals — an API can feel obvious or fiddly, a
+     sample output can feel patronising or brisk. Leave blank to let the agent propose. -->
 
 ## Copy seeds
-<!-- Any words you already hear: a headline, a button label, the tone. The agent drafts REAL copy
-     (D60 — copy rides the prototype, no lorem); seeds steer it. Blank is fine. -->
+<!-- Any words you already hear: a headline, a button label, an error string, the tone. The agent
+     drafts REAL content (D60 — copy rides the prototype, no lorem, and no fake inputs/outputs for
+     non-visual specimens: placeholders hide the friction the specimen exists to surface). Blank is
+     fine. -->
 
 ## What this is NOT
 <!-- One line if you already know a direction to avoid. -->
 
-## Existing surface?
-<!-- If this improves an existing screen/flow, name it. New idea → leave blank. -->
+## Existing thing?
+<!-- If this improves something that already exists — a screen, a skill, an endpoint — name it.
+     Brand-new idea → leave blank. -->
 ```
 
 ---
 
 ## What the agent does with this (not the PM's job)
 
-1. **Design-system check first (blocking, D60):** no design system on this product → the agent
-   authors one from this same brief and the PM approves it *before* any prototype.
-2. Produces **divergent low-fidelity options** — one safe direction is a weaker outcome than three
-   arguable ones — with **real draft copy**, into `prototype/<initiative-id>/`.
-3. Submits to **designer grilling** (dialogue, never a score — D60): one question at a time, a
-   recommended answer with each.
+1. **Conventions check first (blocking, D60(c) as generalised):** the artifact class has no
+   conventions and no craft to reason from → the agent proposes a minimal set from this same brief
+   and the PM approves it *before* any prototype. For UI that is the design system; for a skill,
+   SKILL-FORMAT; for a tool or API, D19's ACI principle; for a schema, the migration/RLS conventions.
+2. Produces **2–3 divergent low-fidelity specimens** — one safe direction is a weaker outcome than
+   three arguable ones — with **real content**, into `prototype/<initiative-id>/`.
+3. Submits to a **craft-grade grilling** (dialogue, never a score — D60(d)): one question at a time,
+   a recommended answer with each. This holds for non-visual specimens too, where the temptation to
+   score is sharper.
 4. The PM **disposes**: promote (→ a new feature-lane initiative; PRD + rubric derived from the
-   validated option) / iterate / kill.
+   validated specimen) / iterate / kill.

package/payload/planning/evals/agent-run-eval-rubric.md

@@ -1,3 +1,13 @@
+---
+type: Rubric
+title: "Eval Rubric: Agent-run capability baseline (kit seed — copy per initiative)"
+timestamp: 2026-07-19
+eval_type: capability
+initiative_id: (set per initiative)
+pass_threshold: 0.80
+canonical_path: pmos/planning/evals/agent-run-eval-rubric.md
+---
+
 # Eval Rubric: Agent-run capability baseline (kit seed — copy per initiative)
 
 > Kit-seeded generic rubric (D54). Two purposes: (1) it is the TEMPLATE to copy to
@@ -6,13 +16,6 @@
 > meaningful from day one. It scores a generic agent run outcome-only (D14) with weighted partial
 > credit (D15).
 
-## Frontmatter
-- type: Rubric
-- eval_type: capability
-- initiative_id: (set per initiative)
-- pass_threshold: 0.80
-- canonical_path: pmos/planning/evals/agent-run-eval-rubric.md
-
 ## Gate assignment
 - **Quality Gate (deterministic):** repo CI green; `pmos-gate` (anchored + rubrics) green.
 - **Review Gate (adversarial):** the weighted dimensions below — evaluator skill, default-to-refute,

package/payload/scripts/metrics.py

@@ -5,7 +5,7 @@ Reads pmos/state/{runs,evals,acceptances}.jsonl and prints:
   B1  north star  — human corrections per ACCEPTED run (lower is better; D10, counted over
                     accepted runs only so leniency can't deflate it)
   B2  throughput  — accepted runs (guards against winning B1 by doing less)
-  --  eval pass rate — share of evals with verdict PASS / PASS-WITH-FINDINGS
+  --  eval pass rate — share of evals passing the Review-Gate rule (see review_gate_pass)
   B4  calibration — evaluator verdict vs PM label, joined by run_id: raw agreement, TPR, TNR,
                     Cohen's kappa (the D40 classifier method, computed locally). κ is broken out
                     PER evaluator_model, with a mixed-model warning — a κ is a property of the
@@ -14,12 +14,52 @@ Reads pmos/state/{runs,evals,acceptances}.jsonl and prints:
                     pass-happy-judge signal; anti-optimism: read the red first)
 
 No network, no secrets. Exit 0 always (a reporting tool, not a gate). Anti-optimism: reds print first.
+
+Import-safe (D64 Track D1): every helper is module-level and the report runs only under __main__, so
+kit/fixtures/test_parsers.py can import review_gate_pass + leading_frontmatter and prove the Python
+parsers agree with the JavaScript ones in workspace/lib/.
 """
 import datetime, glob, json, os, re, sys
 
 KIT = os.environ.get("KIT_ROOT") or os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 STATE = os.path.join(KIT, "state")
 
+# ── CANONICAL Review-Gate pass rule — the MIRROR of workspace/lib/review-gate.js ──────────────
+# Rule: verdict ILIKE 'pass%' OR score >= 0.85. This is the single source of truth's Python half;
+# the JS half is workspace/lib/review-gate.js. kit/fixtures/test_parsers.py runs BOTH against
+# kit/fixtures/review-gate-pass-rule.json and fails if they ever disagree — the mirror can't drift.
+PASS_VERDICT_PREFIX = "pass"
+SCORE_THRESHOLD = 0.85
+
+
+def review_gate_pass(verdict, score):
+    """A recorded verdict is AUTHORITATIVE (pass iff it starts with "pass"); an explicit FAIL is never
+    overridden by a high score. Only when NO verdict was recorded does the score decide.
+    AMENDED 2026-07-26: was `verdict ILIKE 'pass%' OR score >= 0.85`, which let a FAIL at score 0.93
+    through the gate (blind-plant round 2, specimen be58). Mirror of workspace/lib/review-gate.js
+    isReviewPass; agreement enforced by kit/fixtures/test_parsers.py."""
+    v = str("" if verdict is None else verdict).strip().lower()
+    if v:
+        return v.startswith(PASS_VERDICT_PREFIX)
+    try:
+        return float(score) >= SCORE_THRESHOLD
+    except (TypeError, ValueError):
+        return False
+
+
+def leading_frontmatter(path):
+    """The LEADING frontmatter block only — body text cannot fake a declaration. Mirror of
+    workspace/lib/file-mode-parse.js parseLeadingFrontmatter (agreement enforced by the fixture test)."""
+    fm = {}
+    with open(path, encoding="utf-8") as fh:
+        for line in fh:
+            m = re.match(r"^([a-z_]+):\s*(.+?)\s*$", line.rstrip("\n"))
+            if m:
+                fm.setdefault(m.group(1), m.group(2))
+            elif line.strip() and not line.startswith("---"):
+                break  # frontmatter is the LEADING block only
+    return fm
+
 
 def load(name):
     path = os.path.join(STATE, name)
@@ -36,33 +76,14 @@ def load(name):
     return rows
 
 
-runs = load("runs.jsonl")
-evals = load("evals.jsonl")
-acc = load("acceptances.jsonl")
-
-accepted = [a for a in acc if a.get("accepted") is True]
-corrections_by_run = {r.get("run_id"): int(r.get("human_corrections") or 0) for r in runs}
-acc_corr = [corrections_by_run.get(a.get("run_id"), 0) for a in accepted]
-
-passing = ("PASS", "PASS-WITH-FINDINGS")
-n_pass = sum(1 for e in evals if str(e.get("verdict", "")).upper() in passing)
-pass_rate = (n_pass / len(evals)) if evals else None
-
-# --- B4: verdict-vs-PM-label confusion matrix, joined by run_id (D40) ---
-# Calibration is a property of the EVALUATOR MODEL (harness-model-agnosticism): a κ earned by one
-# model is not inherited by another. Compute the matrix OVERALL and PER evaluator_model, and warn
-# when one aggregate κ silently pools verdicts from more than one model.
-label_by_run = {a.get("run_id"): str(a.get("pm_label", "")).lower() for a in acc if a.get("pm_label")}
-
-
-def confusion(rows):
-    """(tp, tn, fp, fn) over evals joined to a pass/fail PM label by run_id."""
+def confusion(rows, label_by_run):
+    """(tp, tn, fp, fn) over evals joined to a pass/fail PM label by run_id, using the canonical rule."""
     tp = tn = fp = fn = 0
     for e in rows:
         lab = label_by_run.get(e.get("run_id"))
         if lab not in ("pass", "fail"):
             continue
-        pred_pass = str(e.get("verdict", "")).upper() in passing
+        pred_pass = review_gate_pass(e.get("verdict"), e.get("score"))
         if pred_pass and lab == "pass":
             tp += 1
         elif pred_pass and lab == "fail":
@@ -83,102 +104,102 @@ def kappa_of(tp, tn, fp, fn):
     return None if pe == 1 else (po - pe) / (1 - pe)
 
 
-tp, tn, fp, fn = confusion(evals)
-n = tp + tn + fp + fn
-
-
-def kappa():
-    return kappa_of(tp, tn, fp, fn)
-
-
-avg_corr = (sum(corrections_by_run.values()) / len(corrections_by_run)) if corrections_by_run else None
-tripwire = pass_rate is not None and avg_corr is not None and pass_rate >= 0.8 and avg_corr >= 1.5
-
-print(f"PMOS kit metrics — {len(runs)} run(s), {len(evals)} eval(s), {len(acc)} acceptance record(s)\n")
-if tripwire:
-    print("🔴 GOODHART TRIPWIRE FIRED — evaluator passes >=80% while humans average >=1.5 corrections/run.")
-    print("   The north star is being gamed; treat the Review Gate as NOT calibrated (D40).\n")
-if not accepted:
-    print("🔴 B1 north star: UNMEASURABLE — no accepted runs yet (record acceptances to pmos/state/acceptances.jsonl).")
-else:
-    ns = sum(acc_corr) / len(accepted)
-    print(f"B1 north star: {ns:.2f} human corrections per accepted run (over {len(accepted)} accepted run(s); lower is better)")
-print(f"B2 throughput: {len(accepted)} accepted run(s)")
-print(f"   eval pass rate: {'n/a — no evals yet' if pass_rate is None else f'{pass_rate:.0%} ({n_pass}/{len(evals)})'}")
-k = kappa()
-if n == 0:
-    print("🔴 B4 calibration: UNMEASURABLE — no eval joined to a PM-labelled acceptance yet; the Review Gate is uncalibrated.")
-else:
-    tpr = tp / (tp + fn) if (tp + fn) else None
-    tnr = tn / (tn + fp) if (tn + fp) else None
-    print(f"B4 calibration (n={n}): raw agreement {(tp + tn) / n:.0%}, "
-          f"TPR {'n/a' if tpr is None else f'{tpr:.0%}'}, "
-          f"TNR {'n/a — no PM fails seen (leniency blind spot)' if tnr is None else f'{tnr:.0%}'}, "
-          f"kappa {'undefined' if k is None else f'{k:.2f}'} (target >= 0.60 — verdict ADVISORY below it, D40)")
-
-# --- per-evaluator-model calibration (harness-model-agnosticism) -------------
-# κ is a property of (evaluator model × rubric); a model swap does NOT inherit a prior κ. When the
-# labeled evals span >1 evaluator model, the aggregate above is a pool, not a gate — break it out.
-# When no eval records its model, κ silently pools across any swaps: nudge to record provenance.
-labeled_evals = [e for e in evals if label_by_run.get(e.get("run_id")) in ("pass", "fail")]
-by_model = {}
-for e in labeled_evals:
-    by_model.setdefault(e.get("evaluator_model") or "unknown", []).append(e)
-if len(by_model) > 1:
-    print(f"\n🔴 MIXED-MODEL CALIBRATION — labeled evals span {len(by_model)} evaluator models; the "
-          "aggregate κ above POOLS them and is not any single evaluator's calibration (κ is per "
-          "evaluator model, D40). Per model:")
-    for m in sorted(by_model):
-        c = confusion(by_model[m])
-        km = kappa_of(*c)
-        print(f"   - {m}: n={sum(c)}, kappa {'undefined' if km is None else f'{km:.2f}'} "
-              f"(tp{c[0]} tn{c[1]} fp{c[2]} fn{c[3]})")
-elif by_model and set(by_model) == {"unknown"}:
-    print("\n⚠ evaluator_model unrecorded on every labeled eval — κ cannot be attributed to a model "
-          "and silently pools across any model swaps. Pass the evaluator model as the last arg to "
-          "`pmos-log.sh eval` (harness-model-agnosticism).")
-
-# --- D57 outcome checks (accepted-but-unvalidated; due prints red) -----------
-# Declarations live in initiative frontmatter (outcome_metric / outcome_horizon); dispositions are
-# appended to state/outcome_checks.jsonl ({initiative_id, disposition, evidence, date}). The latest
-# line per initiative wins; history is never rewritten. Auto-validation is prohibited (D57) — this
-# section only REPORTS; recording a disposition is always the PM's word.
-checks = load("outcome_checks.jsonl")
-latest_disp = {}
-for c in checks:
-    if c.get("initiative_id"):
-        latest_disp[c["initiative_id"]] = str(c.get("disposition", "")).lower()
-
-declared = []
-for path in sorted(glob.glob(os.path.join(STATE, "initiatives", "*.md"))):
-    fm = {}
-    for line in open(path, encoding="utf-8"):
-        m = re.match(r"^([a-z_]+):\s*(.+?)\s*$", line)
-        if m:
-            fm.setdefault(m.group(1), m.group(2))
-        elif line.strip() and not line.startswith("---"):
-            break  # frontmatter is the LEADING block only — body text cannot fake a declaration
-    if not fm.get("id"):
+def main():
+    runs = load("runs.jsonl")
+    evals = load("evals.jsonl")
+    acc = load("acceptances.jsonl")
+
+    accepted = [a for a in acc if a.get("accepted") is True]
+    corrections_by_run = {r.get("run_id"): int(r.get("human_corrections") or 0) for r in runs}
+    acc_corr = [corrections_by_run.get(a.get("run_id"), 0) for a in accepted]
+
+    n_pass = sum(1 for e in evals if review_gate_pass(e.get("verdict"), e.get("score")))
+    pass_rate = (n_pass / len(evals)) if evals else None
+
+    # --- B4: verdict-vs-PM-label confusion matrix, joined by run_id (D40) ---
+    label_by_run = {a.get("run_id"): str(a.get("pm_label", "")).lower() for a in acc if a.get("pm_label")}
+    tp, tn, fp, fn = confusion(evals, label_by_run)
+    n = tp + tn + fp + fn
+    k = kappa_of(tp, tn, fp, fn)
+
+    avg_corr = (sum(corrections_by_run.values()) / len(corrections_by_run)) if corrections_by_run else None
+    tripwire = pass_rate is not None and avg_corr is not None and pass_rate >= 0.8 and avg_corr >= 1.5
+
+    print(f"PMOS kit metrics — {len(runs)} run(s), {len(evals)} eval(s), {len(acc)} acceptance record(s)\n")
+    if tripwire:
+        print("🔴 GOODHART TRIPWIRE FIRED — evaluator passes >=80% while humans average >=1.5 corrections/run.")
+        print("   The north star is being gamed; treat the Review Gate as NOT calibrated (D40).\n")
+    if not accepted:
+        print("🔴 B1 north star: UNMEASURABLE — no accepted runs yet (record acceptances to pmos/state/acceptances.jsonl).")
+    else:
+        ns = sum(acc_corr) / len(accepted)
+        print(f"B1 north star: {ns:.2f} human corrections per accepted run (over {len(accepted)} accepted run(s); lower is better)")
+    print(f"B2 throughput: {len(accepted)} accepted run(s)")
+    print(f"   eval pass rate: {'n/a — no evals yet' if pass_rate is None else f'{pass_rate:.0%} ({n_pass}/{len(evals)})'}")
+    if n == 0:
+        print("🔴 B4 calibration: UNMEASURABLE — no eval joined to a PM-labelled acceptance yet; the Review Gate is uncalibrated.")
+    else:
+        tpr = tp / (tp + fn) if (tp + fn) else None
+        tnr = tn / (tn + fp) if (tn + fp) else None
+        print(f"B4 calibration (n={n}): raw agreement {(tp + tn) / n:.0%}, "
+              f"TPR {'n/a' if tpr is None else f'{tpr:.0%}'}, "
+              f"TNR {'n/a — no PM fails seen (leniency blind spot)' if tnr is None else f'{tnr:.0%}'}, "
+              f"kappa {'undefined' if k is None else f'{k:.2f}'} (target >= 0.60 — verdict ADVISORY below it, D40)")
+
+    # --- per-evaluator-model calibration (harness-model-agnosticism) -------------
+    labeled_evals = [e for e in evals if label_by_run.get(e.get("run_id")) in ("pass", "fail")]
+    by_model = {}
+    for e in labeled_evals:
+        by_model.setdefault(e.get("evaluator_model") or "unknown", []).append(e)
+    if len(by_model) > 1:
+        print(f"\n🔴 MIXED-MODEL CALIBRATION — labeled evals span {len(by_model)} evaluator models; the "
+              "aggregate κ above POOLS them and is not any single evaluator's calibration (κ is per "
+              "evaluator model, D40). Per model:")
+        for m in sorted(by_model):
+            c = confusion(by_model[m], label_by_run)
+            km = kappa_of(*c)
+            print(f"   - {m}: n={sum(c)}, kappa {'undefined' if km is None else f'{km:.2f}'} "
+                  f"(tp{c[0]} tn{c[1]} fp{c[2]} fn{c[3]})")
+    elif by_model and set(by_model) == {"unknown"}:
+        print("\n⚠ evaluator_model unrecorded on every labeled eval — κ cannot be attributed to a model "
+              "and silently pools across any model swaps. Pass the evaluator model as the last arg to "
+              "`pmos-log.sh eval` (harness-model-agnosticism).")
+
+    # --- D57 outcome checks (accepted-but-unvalidated; due prints red) -----------
+    checks = load("outcome_checks.jsonl")
+    latest_disp = {}
+    for c in checks:
+        if c.get("initiative_id"):
+            latest_disp[c["initiative_id"]] = str(c.get("disposition", "")).lower()
+
+    declared = []
+    for path in sorted(glob.glob(os.path.join(STATE, "initiatives", "*.md"))):
+        fm = leading_frontmatter(path)
+        if not fm.get("id"):
+            if fm.get("outcome_metric"):
+                print(f"⚠ {os.path.basename(path)} declares an outcome but has no id: — it can never be disposed; fix the frontmatter")
+            continue
         if fm.get("outcome_metric"):
-            print(f"⚠ {os.path.basename(path)} declares an outcome but has no id: — it can never be disposed; fix the frontmatter")
-        continue
-    if fm.get("outcome_metric"):
-        declared.append(fm)
-
-if declared:
-    today = datetime.date.today().isoformat()
-    undisposed = [f for f in declared if f.get("id") not in latest_disp]
-    # a missing horizon errs RED (counts as due): a bet with no judgment date can never come due
-    # by itself — horizon-gaming-by-omission (mirrors the hosted CHECK requiring a horizon).
-    due = [f for f in undisposed if str(f.get("outcome_horizon", "0000-00-00")) < today]
-    pending = [f for f in undisposed if f not in due]
-    print()
-    if due:
-        print(f"🔴 D57 outcome checks DUE ({len(due)}) — accepted bets past horizon, never validated:")
-        for f in due:
-            print(f"   - {f.get('id')}: \"{f.get('outcome_metric')}\" (horizon {f.get('outcome_horizon', '?')})"
-                  " -> dispose validated|refuted|inconclusive to state/outcome_checks.jsonl")
-    refuted = sum(1 for v in latest_disp.values() if v == "refuted")
-    print(f"D57 outcomes: {len(declared)} declared — {len(pending)} pending, {len(due)} due, "
-          f"{len(latest_disp)} disposed"
-          + (f" ({refuted} refuted — recorded, not hidden)" if refuted else ""))
+            declared.append(fm)
+
+    if declared:
+        today = datetime.date.today().isoformat()
+        undisposed = [f for f in declared if f.get("id") not in latest_disp]
+        # a missing horizon errs RED (counts as due): a bet with no judgment date can never come due
+        # by itself — horizon-gaming-by-omission (mirrors the hosted CHECK requiring a horizon).
+        due = [f for f in undisposed if str(f.get("outcome_horizon", "0000-00-00")) < today]
+        pending = [f for f in undisposed if f not in due]
+        print()
+        if due:
+            print(f"🔴 D57 outcome checks DUE ({len(due)}) — accepted bets past horizon, never validated:")
+            for f in due:
+                print(f"   - {f.get('id')}: \"{f.get('outcome_metric')}\" (horizon {f.get('outcome_horizon', '?')})"
+                      " -> dispose validated|refuted|inconclusive to state/outcome_checks.jsonl")
+        refuted = sum(1 for v in latest_disp.values() if v == "refuted")
+        print(f"D57 outcomes: {len(declared)} declared — {len(pending)} pending, {len(due)} due, "
+              f"{len(latest_disp)} disposed"
+              + (f" ({refuted} refuted — recorded, not hidden)" if refuted else ""))
+
+
+if __name__ == "__main__":
+    main()

package/payload/skills/SKILL-FORMAT.md

@@ -1,3 +1,9 @@
+---
+type: Reference
+title: "SKILL-FORMAT.md — Required Format for PMOS Skills"
+timestamp: 2026-07-23
+---
+
 # SKILL-FORMAT.md — Required Format for PMOS Skills
 
 This document defines the **required** structure for every `.skill` file in PMOS. It is the

package/payload/skills/discovery.skill

@@ -35,6 +35,10 @@ fake rubric, or escaped the record entirely.
 1. **Anchor and create the initiative** with `type: discovery`
    (`create_initiative({id, title, parent_kr, type: 'discovery'})`; file mode: `type: discovery`
    in the initiative frontmatter).
+1b. **Existing surface? Understand it first.** If answering the question honestly requires reading
+   code that already exists, run an [explain-surface](/build-skills/explain-surface.skill) pass on
+   that region — in a fresh context, **before** writing the brief. A spike aimed at a system the PM
+   does not understand produces a learning they cannot act on. Greenfield → skip.
 2. **Write the spike brief** from
    [spike-brief-template](/okf/core/templates/spike-brief-template.md) into
    `/planning/prd/<id>-spike.md`; set it as the initiative's `prd_path`. The Initiative Gate

package/payload/skills/eval-rubric.skill

@@ -43,7 +43,7 @@ Acceptance Gate is the PM's and is not graded by the rubric.
 
 Every rubric document carries, at minimum:
 
-- `type: Rubric` (or as the bundle/planning convention requires)
+- **OKF frontmatter** — the file opens with `type: Rubric`, `title`, `timestamp` (repo-wide convention, D63; [frontmatter-format](/okf/core/concepts/frontmatter-format.md)).
 - **`eval_type: capability | regression`** —
   - `capability` — tests whether the agent can do something new / harder. Used to push the frontier.
   - `regression` — guards an already-passing capability against backsliding. Saturated capability