create-pmos 0.4.0 → 0.6.0

package/payload/okf/core/concepts/frontmatter-format.md

@@ -0,0 +1,75 @@
+---
+type: Concept
+title: Repo-wide frontmatter format
+description: The PMOS house convention — every tracked .md carries OKF-format YAML frontmatter with a required type + title + timestamp, so agents and the harness classify and route a file by reading it, not by guessing from its path.
+tags: [frontmatter, okf, format, harness, aci, convention]
+timestamp: 2026-07-24
+---
+
+# Repo-wide frontmatter format
+
+**Situating context:** authored for the `repo-wide-md-frontmatter` initiative (proposed D63, amends
+D03). The PM's framing — *"OKF is the format, not the folder"* — decouples the OKF **format** (which
+this makes universal) from the `okf/` **bundle** (curated knowledge, unchanged) and from a file's
+**location** (D04, unchanged). This concept is the reference for what the frontmatter lint enforces.
+
+## The rule
+
+Every **tracked** markdown file MUST open with a YAML frontmatter block declaring three **required**
+keys:
+
+| key | meaning | rule |
+|---|---|---|
+| `type` | what the file *is* | one of the registry values (below); enforced |
+| `title` | human-readable name | non-empty string |
+| `timestamp` | last-modified | valid ISO 8601 date (`YYYY-MM-DD`) or datetime |
+
+Recommended-but-optional (OKF): `description`, `tags`, `resource`. Any pre-existing producer keys
+(`initiative_id`, `eval_type`, `parent_KR`, `pass_threshold`, …) are preserved as optional extension
+keys — never stripped.
+
+```yaml
+---
+type: Concept
+title: Repo-wide frontmatter format
+timestamp: 2026-07-24
+---
+```
+
+## Relationship to OKF and D03
+
+OKF requires only `type`. PMOS layers `title` + `timestamp` as **required house keys**, applied
+**repo-wide** (not just the `okf/` bundle). This is stricter than OKF's minimum but still
+OKF-**conformant** — the spec is permissive about extra keys. It is the deliberate amendment D03
+carries (type-only → richer set, repo-wide). The guardrail against required-key creep is this
+registry: the enforced list of `type` values is closed and versioned.
+
+## Reserved files (exempt)
+
+OKF's reserved filenames carry **no** frontmatter and are skipped by both the migration and the lint:
+
+- `index.md` — a directory listing for progressive disclosure
+- `log.md` — a chronological update history
+
+## The `type` registry
+
+The enforced list lives in [`scripts/frontmatter_registry.txt`](/scripts/frontmatter_registry.txt) —
+the single source `frontmatter_lint.py` reads. A `type:` value not in it fails CI (this catches typos).
+
+- **OKF core:** `Concept`, `ADR`, `Template`, `Playbook`, `Reference`
+- **Planning:** `PRD`, `Rubric`, `OKR`, `Radar`, `Checklist`, `Calibration`, `Research`, `Design`, `Prototype`
+- **Root governance:** `Decision`, `Principle`, `Debt`, `Discovery`, `Guide`
+
+### Extending the vocabulary
+
+Add **one line** to `scripts/frontmatter_registry.txt` and a matching row above. A new `type` is a
+visible, reviewable diff — never an ad-hoc value invented in a single file.
+
+## Enforcement
+
+- [`scripts/frontmatter_lint.py`](/scripts/frontmatter_lint.py) — deterministic, no secrets; asserts
+  the three required keys (and `type` ∈ registry) on every non-reserved tracked `.md`. Run in
+  `.github/workflows/frontmatter-ci.yml`.
+- [`scripts/backfill_frontmatter.py`](/scripts/backfill_frontmatter.py) — the one-time migration:
+  prepend-only, idempotent; reuses a file's already-declared `type`/`date` when present, else infers
+  from path (`type`), the first H1 (`title`), and the last git-commit date (`timestamp`).

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

@@ -5,8 +5,10 @@ to pick concepts, then fetch the file(s) you need.
 
 - [agent-harness](agent-harness.md) — Everything wrapping the model that lets it finish work — and the Summary Gate, the input gate that compresses prior-session context into essential state.
 - [control-plane](control-plane.md) — What it means for PMOS to be a control plane — it orchestrates, specs, evaluates, and routes agent work rather than generating production code itself.
+- [design-craft](design-craft.md) — The UI/UX practice a design agent applies: perception/cognition evidence, craft moves, accessibility floors, and recorded anti-patterns (D60).
 - [design-loop](design-loop.md) — How PMOS makes UI/UX design a first-class, repeatable sub-flow of the Build stage — brief → design → reconcile → build → design-sync — gated by the Review Gate, presentation-only, and never a data decision.
 - [eval-driven-pm](eval-driven-pm.md) — PMOS's core method — write the eval before the build. The rubric is the spec; the PM manages by defining what "good" means, not by inspecting work after the fact.
+- [frontmatter-format](frontmatter-format.md) — The repo-wide house frontmatter (`type` + `title` + `timestamp` on every tracked `.md`) and the Frontmatter Gate + registry that enforce it (D63); machine-readable classification by reading, not path-guessing.
 - [health-anchors](health-anchors.md) — The second anchor class (D59): work anchors to a KR or a declared, capped, PM-reviewed health budget, so refactor/ops/security work anchors honestly.
 - [okf-governance](okf-governance.md) — How PMOS organizes its Open Knowledge Format bundle and the governance rules that keep it spec-conformant.
 - [okr-anti-optimism](okr-anti-optimism.md) — Why PMOS biases status reporting toward pessimism — surfacing the red underneath green metrics — to keep KR self-reporting honest.
@@ -15,4 +17,5 @@ to pick concepts, then fetch the file(s) you need.
 - [pm-identity](pm-identity.md) — How PMOS models a product manager — the pm_slug identifier, the PM's authority as the human in the loop, and PM-scoped namespaces.
 - [product-slug-convention](product-slug-convention.md) — The rules for product_slug — the stable lowercase identifier that scopes products across OKF namespaces, planning artifacts, and agent records.
 - [sdlc-loop](sdlc-loop.md) — The closed agent-driven software development lifecycle PMOS orchestrates — spec, contract, build, evaluate, accept, learn — and how it loops.
+- [self-refining-harness](self-refining-harness.md) — The pattern where the harness improves from its own run evidence (evals, friction, calibration) via a detect → draft → PM-gate loop, bounded at the L3 ceiling — never L4 self-mutation.
 - [watermelon-flag](watermelon-flag.md) — A status that reads green on automated metrics but is red underneath on strategic alignment — and silent drift, the L4 failure mode it signals.

package/payload/okf/core/concepts/log.md

@@ -2,5 +2,18 @@
 
 OKF reserved file (no frontmatter). Change history, newest first, ISO 8601 dates.
 
+## 2026-07-24
+- Added [frontmatter-format](frontmatter-format.md) — the repo-wide house frontmatter (`type` + `title` + `timestamp` on every tracked `.md`) + the Frontmatter Gate and registry (D63). Indexed.
+
+## 2026-07-21
+- Added [design-craft](design-craft.md) — the UI/UX practice a design agent applies (perception/cognition evidence, craft moves, accessibility floors, recorded anti-patterns); promoted from `planning/design/attention-research.md` (D60). Indexed.
+
+## 2026-07-18
+- Added [health-anchors](health-anchors.md) — the second anchor class: work anchors to a KR or a declared, capped, PM-reviewed health budget (D59). Indexed.
+
+## 2026-07-01
+- Added [design-loop](design-loop.md) — UI/UX design as a Review-Gate-gated, presentation-only sub-flow of Build (brief → design → reconcile → build → design-sync); D48. Indexed.
+- Added [self-refining-harness](self-refining-harness.md) — the harness improves from its own run evidence via detect → draft → PM-gate, bounded at L3 (D47). Indexed.
+
 ## 2026-06-29
 - Creation — per-folder index/log added (OKF recursive progressive disclosure; D29 reversal direction).

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

@@ -1,7 +1,7 @@
 ---
 type: Template
 title: Design Brief Template
-description: The scaffold for a design brief instance — the context handoff from Claude Code to claude.ai/design. Copy into /planning/design/ and fill; presentation-only.
+description: The scaffold for a design brief instance — the context handoff from the interactive agent to an external design surface (e.g. claude.ai/design). Copy into /planning/design/ and fill; presentation-only.
 tags: [template, design, brief, planning]
 timestamp: 2026-07-01
 ---

package/payload/okf/core/templates/eval-rubric-template.md

@@ -20,17 +20,19 @@ OKF bundle.
 ---
 
 ```markdown
-# Eval Rubric: <initiative title>
+---
+type: Rubric
+title: <initiative title>
+eval_type: capability | regression   # capability = push frontier; regression = guard against backslide
+initiative_id: <id>
+product_slug: <product_slug>
+pm_slug: <pm_slug>
+parent_KR: <reference OR health:<id> (D59)>
+pass_threshold: <0.00–1.00>          # pre-committed, before output exists
+timestamp: <YYYY-MM-DD>
+---
 
-## Frontmatter
-- type: Rubric
-- eval_type: capability | regression   <!-- capability = push frontier; regression = guard against backslide -->
-- initiative_id: <id>
-- product_slug: <product_slug>
-- pm_slug: <pm_slug>
-- parent_KR: <reference OR health:<id> (D59)>
-- pass_threshold: <0.00–1.00>          <!-- pre-committed, before output exists -->
-- date: <YYYY-MM-DD>
+# Eval Rubric: <initiative title>
 
 ## Gate assignment
 <!-- State which gate each criterion serves. Acceptance Gate is PM-only and NOT rubric-graded. -->

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

@@ -20,6 +20,12 @@ copy is an operational instance and does not live in the OKF bundle.
 ---
 
 ```markdown
+---
+type: PRD
+title: <initiative title>
+timestamp: <YYYY-MM-DD>
+---
+
 # PRD: <initiative title>
 
 ## Identity

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/frontier.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# frontier.sh — list the workable tickets in a file-mode PMOS kit (E9).
+#
+# "Work the frontier": a ticket is workable when it is NOT done and EVERY ticket it is blocked_by is
+# done. This is the plain-file equivalent of a board's dependency structure — one file per ticket in
+# state/tickets/NNN-slug.md, numbered in dependency order, blocking edges as text.
+#
+#   scripts/frontier.sh              # from the kit root; lists workable tickets
+#   scripts/frontier.sh state/tickets   # explicit tickets dir
+#
+# Dependency-free and portable: POSIX-ish bash, no associative arrays (runs on bash 3.2, e.g. stock
+# macOS). No network, no board. Reads only the YAML frontmatter fields id / status / blocked_by.
+set -euo pipefail
+
+DIR="${1:-state/tickets}"
+[ -d "$DIR" ] || { echo "frontier: no tickets dir at '$DIR' (nothing to do)"; exit 0; }
+
+# --- field readers (frontmatter only: stop at the closing --- fence) ----------------------------
+fm() { awk 'NR>1 && /^---[[:space:]]*$/{exit} {print}' "$1"; }   # lines between the opening and closing ---
+field() { printf '%s\n' "$1" | sed -n "s/^$2:[[:space:]]*//p" | head -1 | sed 's/^["'\'']//;s/["'\'']$//;s/[[:space:]]*$//'; }
+# blocked_by is an inline list "[\"002\", \"005\"]"; extract the bare ids (digits) in order.
+blockers() { printf '%s\n' "$1" | sed -n 's/^blocked_by:[[:space:]]*//p' | head -1 | grep -oE '[0-9]+' || true; }
+# derive an id: explicit `id:` field, else the leading NNN of the filename.
+idof() { local i; i="$(field "$1" id)"; [ -n "$i" ] && { printf '%s' "$i"; return; }; basename "$2" | grep -oE '^[0-9]+' || basename "$2" .md; }
+
+shopt -s nullglob
+files=("$DIR"/*.md)
+[ ${#files[@]} -eq 0 ] && { echo "frontier: no tickets in '$DIR' (nothing to do)"; exit 0; }
+
+# --- pass 1: collect the done ids (newline-delimited; no associative arrays for bash-3.2 portability)
+DONE_IDS=""
+OPEN=0
+for f in "${files[@]}"; do
+  meta="$(fm "$f")"; id="$(idof "$meta" "$f")"; st="$(field "$meta" status)"
+  if [ "$st" = "done" ]; then DONE_IDS="$DONE_IDS$id
+"; else OPEN=$((OPEN+1)); fi
+done
+is_done() { printf '%s' "$DONE_IDS" | grep -qx "$1"; }
+
+# --- pass 2: a ticket is on the frontier when not done and every blocker is done -----------------
+found=0
+for f in "${files[@]}"; do
+  meta="$(fm "$f")"; id="$(idof "$meta" "$f")"; st="$(field "$meta" status)"; st="${st:-todo}"
+  [ "$st" = "done" ] && continue
+  workable=1
+  while IFS= read -r b; do
+    [ -z "$b" ] && continue
+    is_done "$b" || workable=0
+  done < <(blockers "$meta")
+  if [ "$workable" -eq 1 ]; then
+    printf '  ▸ %-5s %-8s %s\n' "$id" "[$st]" "$(field "$meta" title)"
+    found=$((found+1))
+  fi
+done
+
+if [ "$found" -eq 0 ]; then
+  # distinguish "all done" from "everything is blocked" — a stuck frontier is a real signal.
+  if [ "$OPEN" -eq 0 ]; then echo "frontier: all tickets done ✓"
+  else echo "frontier: $OPEN open ticket(s), NONE workable — the frontier is blocked (check for a cycle or an undone blocker)."; fi
+fi