create-pmos 0.1.0

package/payload/scripts/gate-initiative.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# PMOS portable kit — file-backed Initiative Gate (D54). Fail-closed enforcement of the loop,
+# same contract as the hosted gate but reading pmos/state/ instead of a database. A PR is
+# "anchored" only when:
+#   1. the branch is initiative/<id>  (or the PR body declares 'Initiative: <id>'), and
+#   2. pmos/state/initiatives/<id>.md EXISTS in the checkout, and
+#   3. its prd_path is set and that file exists, and
+#   4. its rubric_path is set and that file exists.
+# Escape hatch (explicit, logged): the `no-initiative` label skips the gate.
+# Inputs via env: HEAD_REF, PR_BODY, PR_LABELS. Optional: KIT_ROOT (default: pmos).
+set -euo pipefail
+
+KIT_ROOT="${KIT_ROOT:-pmos}"
+fail() { echo "::error::initiative-gate: $*"; echo "❌ initiative gate FAILED — $*"; exit 1; }
+note() { echo "::notice::initiative-gate: $*"; echo "ℹ️  $*"; }
+
+# ---- escape hatch (genuine chores) — exact label, space-bounded ------------
+case " ${PR_LABELS:-} " in
+  *" no-initiative "*) note "PR labelled 'no-initiative' — gate skipped (sanctioned chore path)."; exit 0 ;;
+esac
+
+# ---- fail closed if the state layer is missing ------------------------------
+[ -d "$KIT_ROOT/state/initiatives" ] || fail "$KIT_ROOT/state/initiatives/ not found — the kit state layer is required and the gate fails closed (a hard gate must not be silently disableable)."
+
+# ---- derive the initiative id ----------------------------------------------
+id=""
+case "${HEAD_REF:-}" in
+  initiative/*) id="${HEAD_REF#initiative/}" ;;
+esac
+if [ -z "$id" ]; then
+  # `|| true`: a no-match grep exits 1, which under set -e would abort BEFORE the fail() guidance
+  # below ever prints (silent exit 1 on the most common failure path).
+  id="$(printf '%s' "${PR_BODY:-}" | { grep -ioE 'Initiative:[[:space:]]*[A-Za-z0-9._-]+' || true; } | head -1 | sed -E 's/.*:[[:space:]]*//')"
+fi
+[ -n "$id" ] || fail "Not anchored. Name the branch 'initiative/<id>' or add 'Initiative: <id>' to the PR body, or label the PR 'no-initiative' for a genuine chore. See $KIT_ROOT/AGENTS.md."
+
+# ---- validate the id (also guards the path interpolation below) -------------
+printf '%s' "$id" | grep -qE '^[a-z0-9][a-z0-9._-]*$' || fail "Initiative id '$id' is malformed (expected ^[a-z0-9][a-z0-9._-]*$)."
+
+# ---- read the initiative file ------------------------------------------------
+init_file="$KIT_ROOT/state/initiatives/$id.md"
+[ -f "$init_file" ] || fail "No initiative file at $init_file. Create it first — an initiative must exist before its PR. This is the loop rule the gate enforces."
+
+frontval() { # frontval <key> — first 'key: value' line in the file, value trimmed.
+  # `|| true`: an absent key must fall through to the explicit fail() below, not abort silently.
+  { grep -m1 -E "^$1:[[:space:]]*" "$init_file" || true; } | sed -E "s/^$1:[[:space:]]*//" | tr -d '\r' | sed -E 's/[[:space:]]+$//'
+}
+prd="$(frontval prd_path)"
+rubric="$(frontval rubric_path)"
+
+[ -n "$prd" ]    || fail "initiative '$id' has no prd_path in $init_file. Author a PRD and set prd_path (eval-first: PRD + rubric before build)."
+[ -f "$prd" ]    || fail "prd_path '$prd' (from $init_file) does not exist in the repo."
+[ -n "$rubric" ] || fail "initiative '$id' has no rubric_path in $init_file. Author an eval rubric and set rubric_path."
+[ -f "$rubric" ] || fail "rubric_path '$rubric' (from $init_file) does not exist in the repo."
+
+echo "✅ initiative gate PASSED — '$id' is anchored: $init_file exists, PRD ($prd) and rubric ($rubric) present."

package/payload/scripts/kit-update.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# PMOS portable kit — kernel update (D54). Runs FROM the vendored kit inside a target repo:
+#
+#   pmos/scripts/kit-update.sh <path-to-pmos-checkout>
+#
+# Re-vendors ONLY the kernel (skills/, okf/core/, scripts/, check_rubrics.py, AGENTS.md, README.md,
+# templates/) from the given PMOS checkout, stamps KIT-VERSION, and never touches state/,
+# planning/ (beyond check_rubrics.py), or okf/product/. Updates flow one-way, PMOS -> kit.
+# Review the resulting diff as a normal PR.
+set -euo pipefail
+
+[ -n "${1:-}" ] || { echo "usage: kit-update.sh <path-to-pmos-checkout>" >&2; exit 1; }
+SRC="$1"
+KIT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+[ -x "$SRC/kit/build-kit.sh" ] || { echo "kit-update: ERROR — $SRC is not a PMOS checkout (no kit/build-kit.sh)" >&2; exit 1; }
+exec "$SRC/kit/build-kit.sh" --update "$KIT"

package/payload/scripts/metrics.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""PMOS portable kit — balanced metrics over the file-mode state layer (D54, D39).
+
+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
+  B4  calibration — evaluator verdict vs PM label, joined by run_id: raw agreement, TPR, TNR,
+                    Cohen's kappa (the D40 classifier method, computed locally)
+  --  Goodhart tripwire — fires when eval_pass_rate >= 0.8 while avg corrections >= 1.5 (the
+                    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 json, os, 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")
+
+
+def load(name):
+    path = os.path.join(STATE, name)
+    rows = []
+    if os.path.exists(path):
+        for i, line in enumerate(open(path, encoding="utf-8"), 1):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                rows.append(json.loads(line))
+            except json.JSONDecodeError:
+                print(f"⚠ {name}:{i} is not valid JSON — skipped (append-only files must hold one JSON object per line)")
+    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) ---
+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 = 0
+for e in evals:
+    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
+    if pred_pass and lab == "pass":
+        tp += 1
+    elif pred_pass and lab == "fail":
+        fp += 1
+    elif not pred_pass and lab == "fail":
+        tn += 1
+    else:
+        fn += 1
+n = tp + tn + fp + fn
+
+
+def kappa():
+    if n == 0:
+        return None
+    po = (tp + tn) / n
+    pe = (((tp + fp) * (tp + fn)) + ((fn + tn) * (fp + tn))) / (n * n)
+    return None if pe == 1 else (po - pe) / (1 - pe)
+
+
+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)")

package/payload/skills/SKILL-FORMAT.md

@@ -0,0 +1,89 @@
+# SKILL-FORMAT.md — Required Format for PMOS Skills
+
+This document defines the **required** structure for every `.skill` file in PMOS. It is the
+authority that all seed skills (`prd`, `eval-rubric`, `okr`, `strategic-brief`, `source-to-concept`)
+and every future skill must conform to.
+
+## Why a fixed format
+
+Skills are how PMOS gives an agent procedural competence on demand without flooding its context.
+The format exists to make that economical: cheap to keep many skills available, expensive to load
+only the one in use. The mechanism is **three-level progressive disclosure**.
+
+## The three levels
+
+### Level 1 — Frontmatter (always loaded)
+
+YAML frontmatter containing **only `name` and `description`**. This is pre-loaded for **all** skills
+at agent startup, so it must stay small — it is the *trigger signal* the agent uses to decide
+whether the skill is relevant.
+
+```yaml
+---
+name: prd
+description: Write a Product Requirements Document for an initiative. Use when an initiative needs a spec before build work begins.
+---
+```
+
+Rules:
+- `name` — lowercase, matches the filename stem (`prd` → `prd.skill`). **Required.**
+- `description` — one or two sentences. State **what** the skill does and **when** to use it.
+  This is the only text the agent sees for an unloaded skill, so the "when" is what makes it fire.
+  **Required.**
+- `maturity_mode` — **optional**. Present **only** on skills that are not yet active (e.g. `bootstrap`);
+  omit it entirely on active skills. It lives at L1 because "is this skill executable yet?" is an
+  execution-gating signal a loader/CI must be able to read without parsing the body. Values: `bootstrap`
+  (specified, non-executable) → graduates to active (key removed) by a PM decision in `DECISIONS.md`.
+- **Optional Phase-B registry metadata (D49)** — a skill may also carry `version`, `owner`, `risk`,
+  `category`, and `scope`. These are **optional**, producer-defined registry fields that
+  [`gen_skills_seed.sh`](/supabase/seed/gen_skills_seed.sh) sources into the `skills` table so the skill
+  library can group/version/scope skills. A skill with only `name` + `description` is still fully
+  conformant (e.g. `build-skills/evaluator.skill`); carry the registry keys on durable `skills/core/`
+  entries for consistency with their siblings.
+- **No other L1 keys.** Beyond the required `name` + `description`, the optional `maturity_mode`, and the
+  optional Phase-B registry keys above, procedural detail does not belong in L1 — it lives in the body.
+
+### Level 2 — SKILL.md body (loaded when relevant)
+
+The body below the frontmatter holds the **full procedural detail**: steps, heuristics, required
+fields, gate criteria, examples. The agent reads this only after Level 1 has signalled relevance.
+
+This is where the actual "how to do the task" lives. Write it at optimal altitude — concrete
+heuristics that guide judgment, not a brittle decision tree and not a vague mandate.
+
+### Level 3 — Linked sub-files (loaded on demand)
+
+Rare sub-cases, long reference tables, or edge-case procedures live in **separate files**,
+referenced **by filename** from the Level 2 body. The agent reads them only when the body points it
+there for the specific case in hand.
+
+Example reference from a body: *"For multi-product PRDs, follow `prd-multiproduct.md`."*
+
+Use Level 3 to keep Level 2 focused. If a section applies to <20% of runs, it is a Level 3
+candidate.
+
+## File naming
+
+- Skill files use the `.skill` extension: `prd.skill`, `eval-rubric.skill`.
+- Level 3 sub-files are plain `.md` and live alongside the skill or in a named subfolder.
+
+## Skill namespaces
+
+- `/skills/core/` — seed skills, canonical across PMOS.
+- `/skills/domains/` — domain-specific variants (P1).
+- `/skills/pm/<pm_slug>/` — PM-specific variants (e.g. `/skills/pm/wawan/`).
+- `/build-skills/` — skills for the coding agents that build PMOS itself (distinct from PM skills).
+
+## Conformance checklist
+
+A skill is well-formed when:
+
+1. Level 1 frontmatter has `name` + `description` (both required), plus optionally `maturity_mode` (on
+   non-active skills) and the Phase-B registry keys `version`/`owner`/`risk`/`category`/`scope` (D49);
+   no other L1 keys.
+2. `name` matches the filename stem.
+3. `description` states both what the skill does and when to use it.
+4. The body (Level 2) carries the full procedure and is self-sufficient for the common case.
+5. Edge cases are pushed to Level 3 sub-files and referenced by filename.
+
+All five seed skills are authored against this checklist.

package/payload/skills/eval-rubric.skill

@@ -0,0 +1,122 @@
+---
+name: eval-rubric
+description: Author an evaluation rubric for an initiative — the measurable definition of "good" used to judge agent output. Use before any build starts; the eval is written first, paired with the PRD.
+version: 1.0.0
+owner: wawan
+risk: low
+category: eval
+scope: read:okf, write:planning/evals
+---
+
+# eval-rubric — Author an Evaluation Rubric
+
+This skill produces an eval rubric instance for one initiative. In eval-driven PM the rubric **is the
+spec made measurable** ([eval-driven-pm](/okf/core/concepts/eval-driven-pm.md)): it is authored
+*before* the build, alongside the [PRD](/skills/core/prd.skill), and it defines how output will pass
+through the [three-tier gate](/okf/core/concepts/output-eval.md).
+
+> **Format note:** three-level progressive disclosure
+> ([SKILL-FORMAT](/skills/core/SKILL-FORMAT.md)). Level 1 frontmatter above is the trigger and
+> carries only `name` + `description`. Note: the *rubric instances* this skill produces carry their
+> own frontmatter (including `eval_type`, below) — that is the rubric's frontmatter, not this skill
+> file's.
+
+## The three-tier gate vocabulary
+
+A rubric is written with the gate it serves in mind. Name the tiers explicitly; they are not
+interchangeable:
+
+- **Quality Gate** — *deterministic, automated.* Compile, lint, unit tests. Toolchain-enforced
+  pass/fail. No human judgment. A rubric's Quality-Gate criteria must be machine-checkable.
+- **Review Gate** — *probabilistic, adversarial.* Does the output satisfy the rubric's criteria?
+  Applied by a separate evaluator agent or by the PM as critic. This is where the weighted dimensions
+  below are scored. Treat its verdict as **uncalibrated** until validated
+  ([evaluator leniency](/okf/core/concepts/output-eval.md)).
+- **Acceptance Gate** — *subjective, strategic.* Is this the **right** thing? Human PM only. **This
+  is NOT a re-check of the rubric.** The PM's role at the end of every agent run **is** the
+  Acceptance Gate — a strategic-fit decision, not a re-scoring of dimensions.
+
+Make this explicit in every rubric: state which criteria belong to which gate, and state that the
+Acceptance Gate is the PM's and is not graded by the rubric.
+
+## Required frontmatter on the rubric instance
+
+Every rubric document carries, at minimum:
+
+- `type: Rubric` (or as the bundle/planning convention requires)
+- **`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
+    rubrics retire into the regression suite.
+- `initiative_id`, `product_slug`, `pm_slug`, parent `KR`.
+
+## Grading rules
+
+1. **Outcome-only grading.** Criteria check **what the agent produced**, not the path it took. **Do
+   not grade tool call sequences**, intermediate reasoning, or how many steps were taken. A correct
+   outcome by an unexpected route still passes.
+2. **Weighted dimensions with partial credit.** Each rubric dimension gets a **weight**. Each is
+   scored (not just pass/fail), the weighted scores are **summed to a total**, and the total is
+   compared against a **pass threshold**. **Partial credit is required** — a rubric that is
+   all-or-nothing per dimension is malformed. See
+   [eval-rubric-template](/okf/core/templates/eval-rubric-template.md) for the scoring math.
+3. **Pre-commit the threshold.** The pass threshold is set when the rubric is written, before output
+   exists — not tuned afterward to match what came back.
+
+### Worked shape
+
+| Dimension | Weight | Score (0–1) | Weighted |
+|-----------|-------:|------------:|---------:|
+| Correctness | 0.40 | … | … |
+| Completeness vs PRD | 0.30 | … | … |
+| Conformance (format/spec) | 0.20 | … | … |
+| Clarity | 0.10 | … | … |
+| **Total** | **1.00** | | **vs threshold** |
+
+## Sprint contract (pre-run contract)
+
+Before any work begins, the generator and evaluator **agree on done-criteria** — this is the
+contract stage of the [SDLC loop](/okf/core/concepts/sdlc-loop.md). A rubric is incomplete without
+one.
+
+**Format:**
+
+```
+initiative_id: <id>
+run_id: <id>
+done_criteria:
+  1. <testable criterion>
+  2. <testable criterion>
+  ...
+test_method:
+  1. <how criterion 1 is verified>
+  2. <how criterion 2 is verified>
+  ...
+PM_approved: true | false
+```
+
+- **P0 (manual):** write the contract to a temp file and get explicit **PM approval** before work
+  starts. `PM_approved` must be `true` to proceed.
+- **P1+:** the contract is stored in `agent_runs.pre_run_contract`.
+
+The contract and the rubric are consistent by construction: every `done_criterion` maps to rubric
+dimensions, and `test_method` states the gate (Quality/Review) that checks it.
+
+## Output and placement
+
+- Rubric instances are **operational** — they live under `/planning/evals/`, not in the OKF bundle.
+- Filename: slugged to the initiative, e.g. `p0-eval-rubric.md`.
+
+## Quality bar
+
+Before handoff: `eval_type` set; every dimension weighted; weights sum to 1.0; partial credit
+possible; threshold pre-committed; gate assignment stated per criterion; Acceptance Gate marked as
+PM-owned and not rubric-graded; sprint contract present with `PM_approved`.
+
+## Level 3 sub-cases
+
+- Calibrating a leniency-prone evaluator against
+  [eval-calibration.md](/planning/evals/eval-calibration.md): see `eval-calibration-procedure.md`
+  (author on first need).
+- Rubrics for non-code deliverables (docs, strategy): see `eval-rubric-nontext.md`
+  (author on first need).

package/payload/skills/evaluator.skill

@@ -0,0 +1,82 @@
+---
+name: evaluator
+description: Adversarially evaluate an agent run's output against its rubric and persist the verdict (the self-hosted Review Gate). Use after any build run, before the PM Acceptance Gate.
+---
+
+# evaluator — The Self-Hosted Review Gate
+
+This skill is PMOS's **Review Gate** made a first-class, repeatable capability (P4). It formalizes the
+adversarial independent evaluator run by hand through P1–P3: judge what an agent run produced against a
+rubric, write a structured verdict to the `evals` table, and surface it on the radar/board. It runs in
+**Claude Code** (heavy judgment), not an Edge Function ([D34](/DECISIONS.md)).
+
+> **Format:** three-level progressive disclosure ([SKILL-FORMAT](/skills/core/SKILL-FORMAT.md)). Level 1
+> frontmatter above is the trigger. This Level 2 body is the full procedure.
+
+## Non-negotiable stance
+
+- **Independent.** Evaluate in a fresh context, separate from the builder. Never rubber-stamp.
+- **Adversarial / default-to-refute.** For each claimed property, try to *refute* it. Assume a defect
+  exists until you've looked. The builder's self-eval is **lenient** by default
+  ([evaluator leniency](/okf/core/concepts/output-eval.md), [D20](/DECISIONS.md)) — your job is to catch
+  what it overstated.
+- **Outcome-only ([D14](/DECISIONS.md)).** Grade what the run *produced* — the artifact, the diff, the
+  live behavior — **not** the tool-call sequence or the path taken. A right answer reached "the wrong
+  way" still passes; a wrong answer reached tidily still fails.
+- **Self-preference bias — distrust your own praise.** You are a **Claude evaluator judging
+  Claude-built work**, so you carry a built-in bias to over-reward outputs in your own family's style
+  ([D40](/DECISIONS.md)). Counter it: **default to skeptical**, and when a pass feels easy or you are
+  uncertain, **say so explicitly** and flag the run for the cross-family spot-check / minority-veto jury
+  ([calibration-method](/planning/evals/calibration-method.md)). Do not let stylistic familiarity read as
+  quality.
+- **Advisory, not final.** Your verdict informs; it does not decide. The human PM **Acceptance Gate**
+  ([D12](/DECISIONS.md)) is the final authority, and this gate is **uncalibrated** until it clears the
+  calibration threshold. Calibration is now measured like a classifier — **Cohen's kappa ≥ 0.60 against
+  PM labels** (TPR/TNR, not a streak) per [D40](/DECISIONS.md), which **supersedes** D20's "3 consecutive
+  agreements" standard. Say in the verdict that the gate is advisory until that kappa threshold is met.
+
+## Procedure
+
+1. **Read [AGENTS.md](/AGENTS.md)** and the run's `pre_run_contract` (the agreed done-criteria).
+2. **Get the rubric** — `get_eval_rubric` (or the `rubric_path`). If none fits, use the reusable
+   [agent-run rubric](/planning/evals/agent-run-eval-rubric.md). Note its weighted dimensions + pass
+   threshold ([D15](/DECISIONS.md)).
+3. **Read the actual output** — the committed diff, the migration/function/UI, and where possible the
+   **live behavior** (run the query, hit the endpoint, read the CI result). Verify, don't trust the
+   summary. The highest-value findings come from checking claims against reality. Three probes catch the
+   defect classes builder self-eval reliably misses (from `eval-calibration.md`):
+   - **Does the gate actually gate?** Check the enforcement's own teeth — a *required*-check /
+     branch-protection / applied config, not just the script logic. A gate that isn't a required check
+     doesn't gate. *(workflow-enforcement-gate.)*
+   - **Does defensive code HIDE a failure?** A blank/empty/`allSettled`/error-swallowing fallback that
+     renders green instead of surfacing red is a false-confidence defect. *(p2-monitoring blank north-star
+     tile / radar-blanking throw.)*
+   - **Documented ≠ in-effect.** A criterion written down but not actually applied live (a raised TTL, a
+     revoked grant) is a FAIL. *(p1-mcp-connect JWT-TTL.)*
+4. **Grade each contract criterion reference-guided BINARY pass/fail** — not vibes. The **reference** is
+   the run's `pre_run_contract` ([D16](/DECISIONS.md)): for each `done_criteria` item, did the produced
+   outcome satisfy it, judged against its `test_method` and **outcome-only** (D14)? Emit a crisp PASS or
+   FAIL per criterion (no "mostly met"). These binary verdicts are what feed the PM-label confusion matrix
+   (D40); be conservative — an unverified criterion is a FAIL, not a pass.
+5. **Score each weighted dimension** 0..1 with a one-line justification grounded in what you observed.
+   Compute the weighted total (partial credit, D15) and compare to the pass threshold. The dimension score
+   is the numeric aggregate; the per-criterion binary grades above are the honest pass/fail backbone.
+6. **Enumerate defects** — each with `severity` (critical / must-fix / should-fix / low / nit), the
+   specific file+line or behavior, why it's a problem, and a concrete fix. Lead with the single most
+   important finding.
+7. **Decide a verdict**: `PASS` / `PASS-WITH-FINDINGS` / `FAIL`. PASS-WITH-FINDINGS is correct when the
+   work is acceptable but carries non-blocking defects.
+8. **Persist it** — `save_eval({ initiative_id, run_id, rubric_path, score, verdict, dimensions })`,
+   where `dimensions` is `{ <name>: { score, weight, note } }`. This is what makes the gate self-hosting
+   — the verdict lands in `evals` and surfaces on `v_eval_gate_status` (radar/board).
+9. **Hand to the PM.** The Acceptance Gate is theirs, and the PM records the ground-truth `pm_label` to
+   `acceptances` — paired against your verdict by `v_calibration` to compute the kappa that calibrates this
+   gate ([D40](/DECISIONS.md), [calibration-method](/planning/evals/calibration-method.md)). If the PM
+   overrides your verdict, that override is logged to
+   [eval-calibration.md](/planning/evals/eval-calibration.md) and the calibration loop patches this skill.
+
+## Output shape
+
+A short report: **most important finding first**, then VERDICT (score vs threshold), the numbered
+defects, and the per-dimension scores — followed by the `save_eval` call. Be concrete; cite specifics;
+if it is genuinely solid, say so — but only after a real refutation attempt.

package/payload/skills/ingest-repo.skill

@@ -0,0 +1,117 @@
+---
+name: ingest-repo
+description: Scan an existing product repository read-only and emit a DRAFT OKF reference layer (architecture, per-table, capability ledger, integrations, conventions, ADR seeds) + register the repo, so a build agent starts warm. Use when a PM brings a product that already ships and has a repo. Never writes the tenant repo; never emits secrets.
+version: 1.0.0
+owner: wawan
+risk: medium
+category: onboarding
+scope: read:tenant-repo, write:tenant-okf-drafts, write:product_repos
+---
+
+# ingest-repo — Warm-start an existing product from its code
+
+This skill is the **existing-repo on-ramp**: a PM arrives with a product that already ships and already
+has a repo, and PMOS needs knowledge of it so a build agent doesn't cold-start on every run (re-deriving
+the stack, assuming wrong, producing work the PM must heavily correct — the north-star cost). It is the
+**inverse of [analyze-product-infra](/build-skills/analyze-product-infra.skill)** (which goes PRD →
+what the product *needs*): ingest-repo goes **code → what the product *is***. It emits a **draft** OKF
+reference layer + a repo registration and then **stops for PM approval**.
+
+> **Format:** three-level progressive disclosure ([SKILL-FORMAT](/skills/core/SKILL-FORMAT.md)). L1
+> frontmatter above is the trigger; this L2 body is the full procedure.
+> **Where it runs:** in **Claude Code**, in the tenant's own conversation, read-only — never a
+> server-side scanner ([D51](/okf/products/pmos/adr/d51-scan-location.md); heavy reasoning runs in Code
+> per [D09](/okf/products/pmos/adr/d09-skills-execute-in-claude-code.md)).
+
+## Non-negotiable stance
+
+- **Read-only, at control altitude ([D01](/okf/products/pmos/adr/d01-control-plane.md)).** Zero writes
+  to the tenant repo — no files, no branches, no commits. If `git status` is not clean after the run,
+  that is a defect.
+- **No secrets, ever ([D08](/okf/products/pmos/adr/d08-never-log-request-headers.md)).** Read only env
+  var *names* (`.env.example`, config keys). **Secret-scan the repo content AND git history** (real
+  repos leak keys in committed code/history); if a secret value is found, **never** place it in a doc,
+  a log, or the registry — note only that a leak exists and where, by path, so the PM can rotate it.
+- **Default-to-refute on capability** (the [design-reconcile](/skills/core/design-reconcile.skill)
+  stance applied to code): a control/route is **watermelon** until a concrete backend read/write path
+  is found in the code. Unbacked controls land in **§D**, not invented as capability.
+- **Everything is a DRAFT ([D37](/okf/products/pmos/adr/d37-tenant-okf-db-native.md)/[D12](/okf/products/pmos/adr/d12-three-tier-eval-gate.md)).**
+  `save_okf_doc(... status:'draft')`. The agent proposes; the **PM approves in-app**. Retrieval note:
+  a PM's own build agent *can* read its own tenant drafts (get_okf_concepts returns owner-scoped drafts,
+  the ratified 2026-07-02 draft-visible-to-own-agent stance), so warm-start works immediately; approval
+  governs promotion/trust, not visibility to the owner's own agent.
+- **Tenant-only.** `save_okf_doc` rejects `pmos`; this never writes the PMOS-self git bundle.
+- **Idempotent.** Re-running upserts docs (on `id`) and reconciles the registry (on `product_slug`) —
+  no duplicates.
+
+## Procedure
+
+1. **Read [AGENTS.md](/AGENTS.md)** and confirm the target `product_slug` (owner-scoped; one product).
+2. **Read-only scan** of the tenant repo, gathering *cited* evidence (every claim will carry the repo
+   path it came from):
+   - **Stack & app surface** — manifests/lockfiles (`package.json`, `pyproject.toml`, `go.mod`, …),
+     framework config, entrypoints.
+   - **Architecture** — directory tree, entrypoints, module boundaries.
+   - **Data model** — migrations / schema / ORM models: one asset per table/model (columns + RLS/perm
+     shape where expressed).
+   - **Capability map** — trace **routes ↔ handlers ↔ queries**: which UI control/route reaches which
+     backend read/write. This is the raw material for the ledger.
+   - **Integrations** — config + SDK imports + `.env.example` **names only** (maps, transcription,
+     push, payments, storage, …).
+   - **Decisions & conventions** — README / ADRs / CHANGELOG / commit history (existing decisions);
+     CI config, lint rules, observed patterns (conventions).
+3. **Secret-scan** repo content + git history (e.g. high-entropy strings, known key prefixes). Emit
+   **no** value; record only "possible secret at `<path>`" for the PM.
+4. **Emit the reference layer** — via `save_okf_doc(..., status:'draft', product_slug:<slug>)`,
+   namespaced `products/<slug>/...`, **each body carrying situating context + the exact repo path(s)**
+   it was derived from (the [source-to-concept](/skills/core/source-to-concept.skill) rule + the
+   analyze-product-infra cited-line bar, applied to code). Minimum six kinds:
+
+   | Doc | OKF `type` | id (under `products/<slug>/`) | derived from |
+   |---|---|---|---|
+   | Architecture / stack overview | `Concept` | `concepts/architecture` | manifests + tree + entrypoints |
+   | Per-table/model schema (one each) | `Reference` | `data-model/<table>` | migrations / ORM models |
+   | **Capability ledger** | `Reference` | `references/capability-ledger` | routes ↔ handlers ↔ queries |
+   | Integration map | `Reference` | `references/integrations` | config + SDK imports + .env.example names |
+   | Conventions | `Concept` | `concepts/conventions` | CI/lint config + observed patterns |
+   | ADR seed(s) | `ADR` | `adr/<slug>-<n>-<topic>` | README / ADRs / commit history |
+
+5. **Bootstrap the per-tenant capability ledger** (the artifact
+   [design-reconcile](/skills/core/design-reconcile.skill) consumes, [D50](/okf/products/pmos/adr/d50-design-loop-product-scoped.md)
+   pattern — generic method, per-tenant instance). Classify **every** user-facing control/route into
+   exactly one bucket; each §A/§B entry **names the concrete read/write path** in the code:
+   - **§A — read-backed:** maps to a real backend read (query/endpoint) — cite it.
+   - **§B — write-backed:** maps to a real backend write (mutation/endpoint) — cite it.
+   - **§C — data-exists-unsurfaced:** the data exists but no control surfaces it (opt-in opportunity).
+   - **§D — no-backing (watermelon):** a control with no backend path found — flagged, not invented.
+6. **Register the repo** — `register_product_repo({ product_slug, repo:'owner/name',
+   app_surface:<observed>, backend_model:<observed>, status:'active', irs_ref:<repo-profile doc id>,
+   webhook_secret_ref: <name-or-null> })`. Fields are **observed** here (not IRS-derived); pass **no
+   secret value**. Add an "observed, not IRS-derived" provenance note.
+7. **STOP for PM approval.** Present the drafted layer + the ledger's §D watermelon list + any secret
+   findings. The PM approves docs in-app; you do not self-approve. Log the run + friction.
+
+## Guardrails
+
+- **Provenance is a hard gate.** An emitted doc with an un-sourced assertion is a defect — the
+  evaluator's provenance dimension hunts for exactly this ([rubric](/planning/evals/ingest-repo-eval-rubric.md)).
+- **Large/polyglot monorepos:** flag scope to the PM and do a per-package pass; do **not** emit a
+  shallow single profile.
+- **`register_product_repo` semantics:** designed for provisioning output — here `app_surface`/
+  `backend_model` are *observed*, a usage-only difference (no schema change); note it.
+- **B5 measurability:** the value thesis is "warm start → fewer corrections"; the first post-ingest
+  build run should retrieve these concepts (B5 > 0 for the tenant, via
+  [v_knowledge_reuse](/okf/products/pmos/references/metrics/v_knowledge_reuse.md) — now written by
+  get_okf_concepts FETCH). That real correction-delta, not the doc count, is the win.
+
+## Level 3 — references
+
+- The write path + PM gate: [okf-author](/build-skills/okf-author.skill) Mode B, [D37](/okf/products/pmos/adr/d37-tenant-okf-db-native.md).
+- The ledger method: [design-loop concept](/okf/core/concepts/design-loop.md),
+  [design-reconcile](/skills/core/design-reconcile.skill), [watermelon-flag](/okf/core/concepts/watermelon-flag.md).
+- Extraction discipline: [source-to-concept](/skills/core/source-to-concept.skill).
+- Scan location: [D51](/okf/products/pmos/adr/d51-scan-location.md). Registry:
+  [register_product_repo](/okf/products/pmos/references/mcp-tools/register_product_repo.md),
+  [product_repos](/okf/products/pmos/data-model/product_repos.md).
+- Sibling on-ramps: [analyze-product-infra](/build-skills/analyze-product-infra.skill),
+  [product-onboarding playbook](/okf/core/playbooks/product-onboarding.md).

package/payload/skills/okr.skill

@@ -0,0 +1,68 @@
+---
+name: okr
+description: Draft or revise an OKR set for a planning period — objectives with measurable key results that initiatives ladder up to. Use when setting quarterly strategy or re-anchoring drifting work.
+version: 1.0.0
+owner: wawan
+risk: low
+category: planning
+scope: read:okf, write:planning/okrs
+---
+
+# okr — Draft or Revise an OKR Set
+
+This skill produces an OKR instance for a planning period: a small set of objectives, each with
+measurable key results, structured as a tree that initiatives and agent runs ladder up to. It
+operationalizes the [okr-tree](/okf/core/concepts/okr-tree.md) concept.
+
+> **Format note:** three-level progressive disclosure
+> ([SKILL-FORMAT](/skills/core/SKILL-FORMAT.md)). Level 1 above is the trigger; this body is the
+> procedure; rare variants go to Level 3 sub-files.
+
+## When to use vs. not
+
+- **Use** to set strategy for a planning period, or to re-anchor an initiative that has drifted from
+  its parent KR.
+- **Do not use** to spec a single piece of work — that is the [PRD skill](/skills/core/prd.skill).
+  OKRs sit one level above initiatives.
+
+## Procedure
+
+1. **Objectives: qualitative and few.** 2–4 objectives for the period. Each is directional and
+   inspirational, carries no number itself, and states a "what we want to be true."
+2. **Key results: measurable outcomes.** 2–5 KRs per objective. Each is a **change in the world**,
+   not a count of work done — "reduce human correction rate to < 0.5", not "ship 5 features". KRs
+   that measure output invite the [watermelon flag](/okf/core/concepts/watermelon-flag.md).
+3. **Ladder to the north star.** Every KR should move, directly or indirectly, the north-star metric
+   — **human correction rate per agent run** (lower is better). If a KR ladders to nothing, cut it.
+4. **Baseline and target.** Each KR states current baseline, target, and the measurement source.
+   "From X to Y, measured by Z."
+5. **Leave room for initiatives.** OKRs are parents; do not pre-assign every initiative. The tree is
+   filled in as work is chosen.
+6. **Set the review cadence.** State when KRs are checked and that reporting follows
+   [anti-optimism](/okf/core/concepts/okr-anti-optimism.md): report the red, separate confidence
+   from status.
+
+## Required content
+
+- **Period & identity** — planning period, `product_slug`, `pm_slug`.
+- **Objectives** — numbered, qualitative.
+- **Key results** — per objective: baseline → target, measurement source, confidence.
+- **North-star linkage** — how the set ladders to human correction rate.
+- **Cadence** — review rhythm and reporting stance.
+
+## Output and placement
+
+- OKR instances are **operational** — under `/planning/okrs/`, not in the OKF bundle.
+- Filename: period-slugged, e.g. `okrs-q3-2026.md`.
+
+## Quality bar
+
+Before handoff: objectives are qualitative; KRs are outcomes with baseline+target+source; every KR
+ladders toward the north star; reporting stance is anti-optimist; no initiative is smuggled in as a
+KR.
+
+## Level 3 sub-cases
+
+- Mid-period KR revision / re-baselining without resetting objectives: see `okr-rebaseline.md`
+  (author on first need).
+- Multi-product objective rollups: see `okr-rollup.md` (author on first need).