create-pmos 0.1.2 → 0.3.0

package/payload/okf/core/templates/incident-record-template.md

@@ -0,0 +1,66 @@
+---
+type: Template
+title: Incident Record Template
+description: The scaffold for an incident-lane record (D56) — timeline, impact, root cause, learnings, follow-ups. Authored post-hoc (within 48h of resolution), copied into /planning/prd/ as <id>-incident.md and set as the initiative's prd_path.
+tags: [template, incident, lanes, learning]
+timestamp: 2026-07-17
+---
+
+# Incident Record Template
+
+**Situating context:** Authored with [D56](/okf/products/pmos/adr/d56-initiative-lanes.md) to give
+incidents an honest lane: before lanes existed, urgent fixes took the `no-initiative` bypass and
+PMOS's most learning-rich events left **no record at all**. The incident lane inverts eval-first
+by design — fix first, record within 48h — the one sanctioned inversion. Copy the block below into
+`/planning/prd/<id>-incident.md` and fill; set it as the initiative's `prd_path`.
+
+> Usage: create the incident initiative (`type: incident`) as soon as work starts — the record may
+> follow the fix, the anchor may not. The 48h window is protocol (AGENTS.md), not CI-enforced:
+> honoring it is what keeps the lane honest.
+
+---
+
+```markdown
+# Incident Record: <short title>
+
+## Identity
+- initiative_id: <id>
+- type: incident
+- product_slug: <product_slug>
+- pm_slug: <pm_slug>
+- parent_KR: <objective/KR reference OR health:<id> (D59)>   <!-- REQUIRED — incidents often anchor health:ops. -->
+- severity: critical | major | minor
+- detected: <YYYY-MM-DD HH:MM UTC>
+- resolved: <YYYY-MM-DD HH:MM UTC>
+- recorded: <YYYY-MM-DD>                <!-- within 48h of resolution -->
+
+## What happened (timeline)
+<!-- Detection → diagnosis → mitigation → resolution, timestamped. Terse; facts over narrative. -->
+
+## Impact
+<!-- Who/what was affected, for how long, what it cost. -->
+
+## Root cause
+<!-- The actual cause, not the trigger. "Five whys" depth without the ceremony. -->
+
+## Resolution
+<!-- What fixed it — link the PR(s)/commits on branch initiative/<id>. -->
+
+## Learnings
+<!-- What this taught us about the system or the harness. Also append to discoveries.md
+     (#friction where applicable) — this section is the retro; discoveries is the searchable log. -->
+
+## Follow-ups
+<!-- Each REAL follow-up is its own lane initiative (usually feature or chore) — listed here by id,
+     not silently absorbed into the incident. Empty is honest if the fix is complete. -->
+- <initiative id or "none">
+```
+
+---
+
+## Authoring checklist
+
+- [ ] Recorded within 48h of resolution (the lane's honesty rule).
+- [ ] `parent_KR` present — incidents anchor like everything else.
+- [ ] Root cause is a cause, not a symptom or a person.
+- [ ] Learnings mirrored to discoveries.md; follow-ups are their own initiatives.

package/payload/okf/core/templates/index.md

@@ -5,4 +5,7 @@ to pick concepts, then fetch the file(s) you need.
 
 - [design-brief-template](design-brief-template.md) — The scaffold for a design brief instance — the context handoff from Claude Code to claude.ai/design (leg 1 of the design loop). Copy into /planning/design/ and fill; presentation-only.
 - [eval-rubric-template](eval-rubric-template.md) — The scaffold for an evaluation rubric instance, including weighted dimensions, partial credit, and the sprint contract. Copy into /planning/evals/ and fill.
+- [incident-record-template](incident-record-template.md) — The incident-lane post-hoc record (D56): timeline, impact, root cause, learnings, follow-ups. Copy into /planning/prd/ as `<id>-incident.md` within 48h of resolution.
 - [prd-template](prd-template.md) — The scaffold for a Product Requirements Document instance. Copy into /planning/prd/ and fill; do not author PRDs from scratch.
+- [spike-brief-template](spike-brief-template.md) — The discovery-lane spec artifact (D56): question + timebox + spend cap + disposition (learned/promoted/discarded). Copy into /planning/prd/ as `<id>-spike.md`.
+- [content-brief-template](content-brief-template.md) — The content-lane spec artifact (D58): audience, message, voice, sourced claims, deliverables + an optional weighted copy rubric. Copy into /planning/prd/ as `<id>-content-brief.md`.

package/payload/okf/core/templates/prd-template.md

@@ -14,7 +14,8 @@ same anchoring discipline. Copy the block below into `/planning/prd/<slug>-prd.m
 copy is an operational instance and does not live in the OKF bundle.
 
 > Usage: replace every `<…>` placeholder. Delete guidance comments (`<!-- … -->`) once filled.
-> Keep section order. An empty out-of-scope list or a missing parent KR means the PRD is not ready.
+> Keep section order. An empty out-of-scope list or a missing anchor (parent KR, or `health:<id>`
+> per D59) means the PRD is not ready.
 
 ---
 
@@ -25,7 +26,7 @@ copy is an operational instance and does not live in the OKF bundle.
 - initiative_id: <id>
 - product_slug: <product_slug>
 - pm_slug: <pm_slug>
-- parent_KR: <objective.kr reference>   <!-- REQUIRED. No parent KR = unanchored work, do not proceed. -->
+- parent_KR: <objective.kr reference OR health:<id> (D59)>   <!-- REQUIRED. Unanchored work does not proceed. -->
 - status: draft | approved
 - date: <YYYY-MM-DD>
 
@@ -47,6 +48,9 @@ copy is an operational instance and does not live in the OKF bundle.
 
 ## Success criteria (outcomes, not output)
 <!-- Tied to the parent KR. A change in the world, not a list of artifacts produced. -->
+<!-- D57: if a criterion is measurable only AFTER ship, declare it on the initiative as
+     outcome_metric + outcome_horizon (create_initiative / initiative frontmatter) — acceptance
+     at merge will then NOT be the last word; an Outcome Check disposes it at the horizon. -->
 - <outcome criterion>
 - <outcome criterion>
 
@@ -59,8 +63,12 @@ copy is an operational instance and does not live in the OKF bundle.
 - rubric: <link to /planning/evals/<slug>-eval-rubric.md>
 
 ## Links
-- parent KR: <link>
-- relevant OKF concepts: <links>
+<!-- Dual-audience rule (D58): ONE situating sentence per link — what it is and why it matters
+     here — and quote the parent KR's TEXT, not just its id (health-anchored: name the budget and
+     why this work fits its coverage). A stakeholder without the OKF bundle
+     must be able to follow every reference. -->
+- parent KR: <link> — *"<the KR text, quoted>"; <why this initiative advances it>*
+- relevant OKF concepts: <link> — *<one situating sentence>*
 ```
 
 ---
@@ -72,4 +80,5 @@ copy is an operational instance and does not live in the OKF bundle.
 - [ ] Non-goals non-empty.
 - [ ] Success criteria are outcomes tied to the KR, not output counts.
 - [ ] Paired eval rubric queued to be written first.
+- [ ] Every link carries one situating sentence; parent-KR text quoted (dual-audience, D58).
 - [ ] Stays at control altitude — specs *what/why*, not application code or the agent's path.

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

@@ -0,0 +1,68 @@
+---
+type: Template
+title: Spike Brief Template
+description: The scaffold for a discovery-lane spike brief (D56) — question, timebox, spend cap, disposition. Copy into /planning/prd/ as <id>-spike.md and set it as the initiative's prd_path; the lighter spec artifact the discovery lane requires instead of a PRD.
+tags: [template, discovery, spike, lanes]
+timestamp: 2026-07-17
+---
+
+# Spike Brief Template
+
+**Situating context:** Authored with [D56](/okf/products/pmos/adr/d56-initiative-lanes.md) as the
+discovery lane's spec artifact, resolving the eval-first paradox the SDLC stress test named: a
+prototype exists to *discover* its own done-criteria, so the lane contracts on a **question and a
+timebox**, not on requirements. The [discovery skill](/skills/core/discovery.skill) instantiates
+this template. Copy the block below into `/planning/prd/<id>-spike.md` and fill; the copy is an
+operational instance, not OKF knowledge.
+
+> Usage: replace every `<…>` placeholder. An empty question or a missing timebox means the brief is
+> not ready. The disposition section stays open until the spike closes — closing it is mandatory.
+
+---
+
+```markdown
+# Spike Brief: <initiative title>
+
+## Identity
+- initiative_id: <id>
+- type: discovery
+- product_slug: <product_slug>
+- pm_slug: <pm_slug>
+- parent_KR: <objective/KR reference OR health:<id> (D59)>   <!-- REQUIRED — anchoring holds in every lane. -->
+- status: open | closed
+- date: <YYYY-MM-DD>
+
+## Question
+<!-- The ONE question this spike answers. If you can write done-criteria instead, it is not a
+     spike — take the feature lane. -->
+
+## Why now
+<!-- What decision or initiative is blocked on this answer. -->
+
+## Timebox & spend cap
+- timebox: <e.g. 2 days / 3 runs>       <!-- REQUIRED. The spike ends when the box ends, answered or not. -->
+- spend_cap: <e.g. token/infra budget, if relevant>
+
+## Method sketch
+<!-- How you'll attack it — rough is fine; the path is not graded (D14). Throwaway code is
+     expected and stays on the initiative branch. -->
+
+## Out of scope
+<!-- What this spike deliberately does NOT try to answer or build. -->
+
+## Disposition (fill at close — mandatory)
+- disposition: learned | promoted | discarded
+- evidence: <what was learned, one paragraph — link artifacts/branch>
+- follow-up: <for `promoted`: link the NEW feature-lane initiative + PRD; a spike never silently
+  becomes the product. For `discarded`: one line on why.>
+```
+
+---
+
+## Authoring checklist
+
+- [ ] `parent_KR` present — discovery is anchored work, not free exploration.
+- [ ] The question is singular and answerable inside the timebox.
+- [ ] Timebox stated; the spike ends when it ends (inconclusive is a valid, recordable outcome).
+- [ ] Disposition closed before the initiative leaves the board — `promoted` links a real
+      feature-lane PRD; prototype code is deleted or explicitly quarantined, never shipped as-is.

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

@@ -20,7 +20,11 @@
 - **Acceptance Gate (PM):** the human PM merges and disposes — final and non-delegable (D12).
 
 ## Weighted dimensions (Review Gate)
-Outcome-only (D14); partial credit (D15); anchors 0 / 0.5 / 1.0.
+Outcome-only (D14); partial credit (D15); anchors 0 / 0.5 / 1.0. **Evidence rule:** the verdict
+must cite, per scored dimension, a short verbatim quote or precise pointer (file+line, command
+output) from the evaluated artifact; a dimension without evidence is marked `unverified` and
+scored conservatively (≤ 0.5) — never high on trust (evidence-anchored scoring,
+llm-judge-calibration research).
 
 | Dimension | Weight | Score | Wtd |
 |---|---:|---:|---:|

package/payload/planning/okrs/health-budgets.md

@@ -0,0 +1,7 @@
+# Health budgets (D59) — closed registry, PM-edited only. parent_kr: health:<id>
+
+| id | covers | quarterly cap | review trigger |
+|---|---|---:|---|
+| health:tech | refactors, debt, tooling | 20% | over cap / recurring debt theme |
+| health:security | hardening, rotations, audits | 10% | over cap / security work misfiled under a KR |
+| health:ops | pipelines, deploys, monitoring upkeep | 10% | over cap / an ops gap recurring after its fix |

package/payload/scripts/gate-initiative.sh

@@ -4,9 +4,15 @@
 # "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.
+#   3. the file satisfies its LANE's artifact requirements (D56) — `type:` frontmatter picks it:
+#        feature (default) -> prd_path + rubric_path set and both files exist (the original contract)
+#        discovery         -> prd_path = the spike brief, set and exists; rubric optional
+#        chore             -> a non-empty `intent:` line in the initiative file; no PRD/rubric
+#        incident          -> prd_path = the incident record, set and exists (post-hoc is sanctioned)
+#        content           -> prd_path = the content brief, set and exists; rubric recommended (D58)
+#      Unknown/missing type = feature: the strictest lane. Lane variation is never a skip.
+# Escape hatch (explicit, logged): the `no-initiative` label — anchor-free trivia ONLY, real work
+# takes a lane (D56).
 # Inputs via env: HEAD_REF, PR_BODY, PR_LABELS. Optional: KIT_ROOT (default: pmos).
 set -euo pipefail
 
@@ -14,9 +20,9 @@ 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 ------------
+# ---- escape hatch (anchor-free trivia only — real work takes a lane) --------
 case " ${PR_LABELS:-} " in
-  *" no-initiative "*) note "PR labelled 'no-initiative' — gate skipped (sanctioned chore path)."; exit 0 ;;
+  *" no-initiative "*) note "PR labelled 'no-initiative' — gate skipped (anchor-free trivia only; a chore/incident/discovery belongs in its lane, D56)."; exit 0 ;;
 esac
 
 # ---- fail closed if the state layer is missing ------------------------------
@@ -32,7 +38,7 @@ if [ -z "$id" ]; then
   # 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."
+[ -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 anchor-free trivia. 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._-]*$)."
@@ -47,10 +53,43 @@ frontval() { # frontval <key> — first 'key: value' line in the file, value tri
 }
 prd="$(frontval prd_path)"
 rubric="$(frontval rubric_path)"
+lane="$(frontval type)"
+intent="$(frontval intent)"
+anchor="$(frontval parent_kr)"
+[ -n "$lane" ] || lane="feature"
 
-[ -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."
+# ---- kernel invariant: an initiative anchors (D21/D59) -----------------------
+# Hosted parity: create_initiative rejects a missing parent_kr at row creation; in the kit the
+# file IS the row, so the gate is where the same rule lands. A KR or health:<id> — never blank.
+[ -n "$anchor" ] || fail "initiative '$id' has no parent_kr in $init_file — anchor it to a KR, or to a declared health budget (parent_kr: health:<id> from $KIT_ROOT/planning/okrs/health-budgets.md, D59). Unanchored work is rejected (D21)."
 
-echo "✅ initiative gate PASSED — '$id' is anchored: $init_file exists, PRD ($prd) and rubric ($rubric) present."
+# ---- lane-parameterized artifact checks (D56) --------------------------------
+# The kernel invariants already held above (anchored record; the human merge stays the Acceptance
+# Gate); what varies per lane is the spec/eval artifact. In EVERY lane a rubric_path that is set
+# must point at a real file — optional never means dangling.
+case "$lane" in
+  discovery|incident|content)
+    # if-form, not `[ … ] && …`: under set -e a false test as a bare && would kill the script.
+    what="spike brief"
+    if [ "$lane" = incident ]; then what="incident record (post-hoc within 48h is the sanctioned lane rule)"; fi
+    if [ "$lane" = content ]; then what="content brief (rubric recommended, not required — D58)"; fi
+    [ -n "$prd" ] || fail "initiative '$id' (type $lane) has no prd_path in $init_file — set it to the $what (see $KIT_ROOT/okf/core/templates/)."
+    [ -f "$prd" ] || fail "prd_path '$prd' (from $init_file, type $lane) does not exist in the repo."
+    [ -z "$rubric" ] || [ -f "$rubric" ] || fail "rubric_path '$rubric' (from $init_file) does not exist in the repo (a rubric is optional in the $lane lane — set the path only to a real file)."
+    echo "✅ initiative gate PASSED — '$id' ($lane lane): $init_file exists, $what ($prd) present."
+    ;;
+  chore)
+    [ -n "$intent" ] || fail "initiative '$id' (type chore) has no intent in $init_file — the chore lane requires a one-paragraph 'intent:' line. Anchor-free trivia takes the no-initiative label; real work states its intent."
+    [ -z "$prd" ]    || [ -f "$prd" ]    || fail "prd_path '$prd' (from $init_file) does not exist in the repo (not required in the chore lane — set the path only to a real file)."
+    [ -z "$rubric" ] || [ -f "$rubric" ] || fail "rubric_path '$rubric' (from $init_file) does not exist in the repo (not required in the chore lane — set the path only to a real file)."
+    echo "✅ initiative gate PASSED — '$id' (chore lane): $init_file exists, intent stated."
+    ;;
+  *)
+    [ "$lane" = "feature" ] || note "unknown initiative type '$lane' on '$id' — enforcing the feature lane (strictest, fail-closed). The enum widens only with a ratified lane decision (D56)."
+    [ -n "$prd" ]    || fail "initiative '$id' has no prd_path in $init_file. Author a PRD and set prd_path. Feature lane: PRD + rubric before build (eval-first, D13); other work shapes take their lane (D56)."
+    [ -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' (feature lane): $init_file exists, PRD ($prd) and rubric ($rubric) present."
+    ;;
+esac

package/payload/scripts/metrics.py

@@ -13,7 +13,7 @@ Reads pmos/state/{runs,evals,acceptances}.jsonl and prints:
 
 No network, no secrets. Exit 0 always (a reporting tool, not a gate). Anti-optimism: reds print first.
 """
-import json, os, sys
+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")
@@ -97,3 +97,48 @@ else:
           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)")
+
+# --- 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"):
+        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 ""))

package/payload/scripts/pmos-log.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# PMOS portable kit — pmos-log.sh (D58): the human builder's one-command state writer.
+# Appends ONE validated JSON line to the right pmos/state/ file. Mirrors the hosted rules:
+# verdict enum (save_eval), pm_label enum (record_acceptance), disposition enum + the D57
+# evidence-required-for-terminal rule (record_outcome_check). Append-only by construction — this
+# script only ever `>>`s; a correction is a NEW record. No dependencies beyond POSIX + python3
+# (used solely for safe JSON string escaping).
+#
+#   pmos-log.sh run      <run_id> <initiative_id> [human_corrections]
+#   pmos-log.sh eval     <run_id> <initiative_id> <score 0..1> <PASS|PASS-WITH-FINDINGS|FAIL> <rubric_path>
+#   pmos-log.sh accept   <run_id> <initiative_id> <pass|fail> [note]
+#   pmos-log.sh outcome  <initiative_id> <validated|refuted|inconclusive> [evidence]
+#   pmos-log.sh friction <note...>
+set -euo pipefail
+
+KIT="${KIT_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+STATE="$KIT/state"
+fail() { echo "pmos-log: ERROR — $*" >&2; exit 1; }
+[ -d "$STATE" ] || fail "state dir not found at $STATE (run from a vendored kit, or set KIT_ROOT)."
+
+js() { python3 -c 'import json,sys; print(json.dumps(sys.argv[1]))' "$1"; }  # safe JSON string
+nonempty() { # nonempty <label> <value> — ids must not be blank (hosted tools reject them too)
+  [ -n "$(printf '%s' "$2" | tr -d '[:space:]')" ] || fail "$1 must not be empty."
+}
+today="$(date -u +%Y-%m-%d)"
+
+append() { # append <file> <json-line>
+  printf '%s\n' "$2" >> "$STATE/$1"
+  echo "✅ appended to state/$1:"
+  echo "   $2"
+}
+
+cmd="${1:-}"; shift || true
+case "$cmd" in
+  run)
+    [ $# -ge 2 ] || fail "usage: run <run_id> <initiative_id> [human_corrections]"
+    nonempty run_id "$1"; nonempty initiative_id "$2"
+    corr="${3:-0}"
+    printf '%s' "$corr" | grep -qE '^[0-9]+$' || fail "human_corrections must be a non-negative integer, got '$corr'."
+    append runs.jsonl "{\"run_id\":$(js "$1"),\"initiative_id\":$(js "$2"),\"human_corrections\":$corr,\"date\":\"$today\"}"
+    ;;
+  eval)
+    [ $# -ge 5 ] || fail "usage: eval <run_id> <initiative_id> <score 0..1> <PASS|PASS-WITH-FINDINGS|FAIL> <rubric_path>"
+    nonempty run_id "$1"; nonempty initiative_id "$2"
+    printf '%s' "$3" | grep -qE '^(0?\.[0-9]+|0|1(\.0+)?)$' || fail "score must be 0..1 written as 0, 1, N.N or .N — got '$3'."
+    case "$4" in PASS|PASS-WITH-FINDINGS|FAIL) ;; *) fail "verdict must be PASS | PASS-WITH-FINDINGS | FAIL, got '$4'." ;; esac
+    score="$3"; case "$score" in .*) score="0$score" ;; esac  # ".5" -> "0.5": bare .5 is not valid JSON
+    [ -f "$KIT/$5" ] || [ -f "$5" ] || fail "rubric_path '$5' not found (relative to the kit or the repo)."
+    append evals.jsonl "{\"run_id\":$(js "$1"),\"initiative_id\":$(js "$2"),\"score\":$score,\"verdict\":$(js "$4"),\"rubric_path\":$(js "$5"),\"date\":\"$today\"}"
+    ;;
+  accept)
+    [ $# -ge 3 ] || fail "usage: accept <run_id> <initiative_id> <pass|fail> [note]"
+    nonempty run_id "$1"; nonempty initiative_id "$2"
+    case "$3" in pass|fail) ;; *) fail "pm_label must be pass | fail, got '$3'." ;; esac
+    acc=true; [ "$3" = fail ] && acc=false
+    append acceptances.jsonl "{\"run_id\":$(js "$1"),\"initiative_id\":$(js "$2"),\"accepted\":$acc,\"pm_label\":$(js "$3"),\"note\":$(js "${4:-}"),\"date\":\"$today\"}"
+    ;;
+  outcome)
+    [ $# -ge 2 ] || fail "usage: outcome <initiative_id> <validated|refuted|inconclusive> [evidence]"
+    nonempty initiative_id "$1"
+    case "$2" in validated|refuted|inconclusive) ;; *) fail "disposition must be validated | refuted | inconclusive, got '$2'." ;; esac
+    ev="${3:-}"
+    if [ "$2" != "inconclusive" ] && [ -z "$(printf '%s' "$ev" | tr -d '[:space:]')" ]; then
+      fail "evidence is REQUIRED for a validated/refuted disposition (D57: no rubber-stamps; use 'inconclusive' for an honest non-answer)."
+    fi
+    append outcome_checks.jsonl "{\"initiative_id\":$(js "$1"),\"disposition\":$(js "$2"),\"evidence\":$(js "$ev"),\"date\":\"$today\"}"
+    ;;
+  friction)
+    [ $# -ge 1 ] || fail "usage: friction <note...>"
+    printf -- '- %s %s #friction\n' "$today" "$*" >> "$STATE/discoveries.md"
+    echo "✅ appended to state/discoveries.md: - $today $* #friction"
+    ;;
+  *)
+    fail "unknown command '${cmd:-}' — one of: run | eval | accept | outcome | friction (see AGENTS-HUMAN.md)."
+    ;;
+esac

package/payload/skills/SKILL-FORMAT.md

@@ -62,6 +62,97 @@ Example reference from a body: *"For multi-product PRDs, follow `prd-multiproduc
 Use Level 3 to keep Level 2 focused. If a section applies to <20% of runs, it is a Level 3
 candidate.
 
+## Quality — what makes a skill good (not just well-formed)
+
+The three levels are *structure*. This section is the *bar*. A skill can be perfectly structured and
+still be junk; these are the tests that keep it worth its context.
+
+### Predictability is the root virtue
+
+A skill exists to **wring determinism out of a stochastic system**: it makes the agent take the same
+*process* every run — not produce the same *output* (an evaluator should predictably *judge*; its
+words vary, its behavior doesn't). Every rule below serves predictability; cost and readability are
+symptoms of it, not rival goals. When unsure whether a line belongs, ask: *does it make the agent's
+process more repeatable?* If not, cut it.
+
+### Per-step completion criteria
+
+Every procedural step ends on a **checkable done-condition** — the agent must be able to tell done
+from not-done. Where it matters, make the criterion **exhaustive**, not vague: *"every living mirror
+of the rule accounted for"*, not *"produce a change list"*. A fuzzy criterion invites **premature
+completion** — the agent stops when it feels done, not when it is. The
+[semantic-pass rule](/build-skills/evaluator.skill) ("enumerate the live-doc set, then read each for
+meaning — a grep is evidence, never done") is the exemplar this generalizes: it exists because a
+vague "sweep it" criterion let real stale mirrors survive five "clean" passes.
+
+### Pruning — hunt these named failure modes
+
+A skill without a pruning discipline only ever grows. Hunt, sentence by sentence:
+
+- **No-op** — a line the model already obeys by default, so you pay context to say nothing. Test:
+  does it change behavior vs. the default? *"Be thorough"* to an already-thorough agent is a no-op;
+  the fix is a stronger word (a leading word), not more words.
+- **Sediment** — stale layers that settle because adding feels safe and removing feels risky. The
+  default fate of any skill without this discipline.
+- **Sprawl** — simply too long, even when every line is live. Cure: disclose reference to Level 3;
+  split by branch.
+- **Duplication** — the same meaning in more than one place. Costs tokens and maintenance, and
+  inflates a meaning's apparent importance. Keep one source of truth.
+- **Negation** — steering by prohibition backfires: *"don't think of an elephant"* names the
+  elephant. State the **positive** target behavior; keep a prohibition only as a hard guardrail you
+  can't phrase positively, and pair it with what to do instead.
+
+**This is the checklist the quarterly harness-assumption review runs** (DECISIONS.md cadence): the
+review's question — *what scaffolding can be removed because the model now handles it natively?* — is
+the no-op and sediment hunt applied across every skill.
+
+### Leading words
+
+A **leading word** is a compact concept already in the model's pretraining that anchors a whole
+region of behavior in one token — *tight* (loop), *watermelon*, *default-to-refute*, *silent drift*,
+*Summary Gate*. Repeated across a skill, it accumulates a distributed definition and recruits priors
+the model already holds. A triad spelled out at three sites (*"fast, deterministic, low-overhead"*)
+is begging to **collapse** into one word (*tight*). You win twice: fewer tokens, and a sharper hook
+the agent hangs its behavior on. Hunt every skill for restatements a leading word retires.
+
+### Invocation (advisory)
+
+The Agent-Skills world splits skills by *who can invoke them* — **model-invoked** (description always
+loaded, agent can auto-fire it, pays permanent context load) vs **user-invoked** (invisible to the
+agent, human-only, zero context load). PMOS's model differs — skills are **retrieved on demand**
+(see the retrieval rationale under *Ecosystem compatibility* below), so Level-1 frontmatter is the
+always-available trigger and there is no auto-fire to gate. Treat the axis as an authoring lens —
+*is this skill's description earning its keep as an always-available trigger?* — **not** a required
+field. (A formal `invocation:` key is a deferred registry question, not part of this format.)
+
+## Ecosystem compatibility — the Agent Skills standard
+
+The open **Agent Skills standard** (Claude Code, Codex, and other harnesses) packages a skill as a
+**directory** `<skill-name>/SKILL.md` with YAML frontmatter (`name`, `description`, optionally
+`license`, `allowed-tools`) plus bundled sub-files. It **validates PMOS's three-level disclosure** —
+same frontmatter-as-trigger, body-as-procedure, sub-files-on-demand shape.
+
+PMOS **diverges** deliberately: skills are flat `<name>.skill` files, **not** `<name>/SKILL.md`
+directories. The rationale is PMOS's retrieval model — skills are fetched on demand via `get_skill`
+or referenced from AGENTS.md, **not** auto-discovered by a harness scanning for `SKILL.md`, so the
+directory ceremony buys nothing here. The **mapping is lossless**, which is what keeps the divergence
+cheap:
+
+- a `<name>.skill` file **≅** a standard `SKILL.md` body;
+- PMOS's required `name` + `description` frontmatter is **already** the standard's required pair;
+- Level-3 sub-files **≅** the standard's bundled files.
+
+(One nuance for the follow-on below: PMOS's *optional* D49 registry keys —
+`version`/`owner`/`risk`/`category`/`scope` — are top-level custom keys; the standard would expect
+producer-defined extensions under a `metadata:` map. The **core** shape is lossless; relocating the
+registry keys belongs to the native-format packaging follow-on, not this flat form.)
+
+**Named follow-on (not built here):** shipping the **kit** in native Agent-Skills directory format so
+a stranger's Claude Code / Codex harness auto-discovers PMOS skills. It touches `build-kit.sh`,
+`get_skill`, `gen_skills_seed.sh`, and every skill path, so it is its own initiative — revisit when
+native-discovery demand in kit repos is proven. (This mirrors the mattpocock/skills plugin decision:
+keep the editable flat-file form, add a native-package path only when the demand is real.)
+
 ## File naming
 
 - Skill files use the `.skill` extension: `prd.skill`, `eval-rubric.skill`.
@@ -86,4 +177,15 @@ A skill is well-formed when:
 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.
+**Quality bar** (the "good", not just "well-formed" — see Quality above):
+
+6. **Predictability served** — every line makes the agent's *process* more repeatable; cut what
+   doesn't.
+7. **Per-step completion criteria** — each procedural step ends on a checkable (and where it matters
+   exhaustive) done-condition, not a vague "do X".
+8. **Pruned** — no no-ops, no sediment, no duplication; prohibitions phrased as positive targets;
+   sprawl disclosed to Level 3.
+9. **Leading words** — restated qualities collapsed into pretrained tokens where one earns its keep.
+
+All seed skills are authored against this checklist; the quarterly harness-assumption review re-runs
+items 6–9 across every skill.

package/payload/skills/copywriting.skill

@@ -0,0 +1,55 @@
+---
+name: copywriting
+description: Produce marketing/UX/product copy through the content lane (D58) — content brief first, then draft against audience/message/voice, judged on audience-fit, clarity, voice, and claim accuracy. Use for landing pages, UX microcopy, release notes, docs intros, campaign text; the first domain skill.
+version: 1.0.0
+owner: wawan
+risk: low
+category: domain
+scope: read:okf, write:planning/prd
+---
+
+# copywriting — Produce copy through the content lane
+
+The first `/skills/domains/` skill: how copy work runs through PMOS's **content lane**
+([D58](/okf/products/pmos/adr/d58-builder-profiles.md), on the
+[D56](/okf/products/pmos/adr/d56-initiative-lanes.md) lane substrate). Copy is real, anchored work
+— never the `no-initiative` hatch — but it iterates fast, so the lane contracts on a **brief**,
+and a rubric is *recommended, not required* (a required one recreates fake-rubric pressure).
+
+> **Format:** three-level progressive disclosure ([SKILL-FORMAT](/skills/core/SKILL-FORMAT.md)).
+
+## When to use vs. not
+
+- **Use** for deliverable text: landing/marketing pages, UX microcopy, release notes, docs
+  introductions, campaign/launch copy.
+- **Do not use** for PRDs/specs (prd skill), OKF knowledge (source-to-concept), or code comments.
+- Strategy-of-the-message questions ("should we even say this?") belong to the PM/strategic-brief
+  altitude — the brief records the answer; this skill executes it.
+
+## Procedure
+
+1. **Open a content initiative** (`type: content`, anchored like everything else — a KR, or a
+   declared health budget `health:<id>` (D59)).
+2. **Write the content brief** from
+   [content-brief-template](/okf/core/templates/content-brief-template.md) into
+   `/planning/prd/<id>-content-brief.md`; set it as `prd_path` (the gate requires it). The PM
+   approves the brief — that approval is the lane's contract.
+3. **Draft against the brief**: one variant per stated audience/placement; every factual claim
+   traceable to a source named in the brief (claim accuracy is the non-negotiable dimension —
+   wrong claims in public copy are incidents, not nits).
+4. **Judge it.** Recommended: a small weighted rubric (template section in the brief) scoring
+   **audience-fit / clarity / voice / claim accuracy**; minimum bar without one: the PM reads the
+   draft against the brief line-by-line at the Acceptance Gate.
+5. **Ship and record** as usual (run log; merge = Acceptance). Reusable phrasing/voice learnings
+   go to discoveries; a durable voice guide graduates into OKF as a concept.
+
+## Quality bar
+
+Brief approved before drafting; every claim sourced; each audience/placement served by a variant
+(or its absence stated); no invented product facts; the voice section of the brief is followed or
+the deviation is argued in the PR.
+
+## Level 3 sub-cases
+
+- None yet. (Localization campaigns and A/B copy variants: author `copywriting-variants.md` on
+  first need — variant outcomes belong to D57 outcome checks.)