create-pmos 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wawan (PMOS)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,30 @@
+# create-pmos
+
+Scaffold the **PMOS portable kit**: run a disciplined, eval-driven product-management workflow —
+initiative → PRD → eval rubric → pre-run contract → build → Quality/Review/Acceptance gates —
+**entirely inside your own repo**. All state is git-versioned files. No database, no account,
+no network calls, no telemetry.
+
+```bash
+npx create-pmos@latest              # vendor a pmos/ kit into the current directory
+npx create-pmos@latest my-product   # ...or into my-product/
+npx create-pmos@latest --update     # refresh the kit kernel (never touches your state)
+```
+
+Then open the folder with your coding agent (e.g. Claude Code) and start at `pmos/AGENTS.md` —
+it is the whole protocol. `pmos/README.md` is the operator guide; `pmos/scripts/metrics.py`
+prints your north-star metrics from the recorded state.
+
+## What's inside
+
+- `pmos/AGENTS.md` — the run protocol + the state adapter (every workflow action is a file convention)
+- `pmos/skills/` — the working skills (PRD, eval rubric, OKR, adversarial evaluator, repo ingest)
+- `pmos/okf/core/` — the concept kernel (the SDLC loop, three-tier gates, watermelon flags, …)
+- `pmos/scripts/` — a fail-closed CI gate for unanchored PRs, metrics, kernel updater
+- `pmos/state/` — your append-only operational record (initiatives, runs, evals, acceptances)
+
+## Scope & support
+
+This package contains only the PMOS workflow **kernel** — it holds no reference to, and never
+contacts, any PMOS backend. Provided **as-is** (MIT); it is a snapshot published from a private
+upstream, updated when the maintainer publishes. Issues/PRs are not currently monitored.

package/bin/create-pmos.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/*
+ * create-pmos — scaffold the PMOS portable kit into a repo (D54/D55).
+ *
+ *   npx create-pmos@latest [target-dir]     vendor a fresh pmos/ kit (default target: cwd)
+ *   npx create-pmos@latest --update [dir]   refresh ONLY the kernel of an existing kit
+ *   npx create-pmos@latest --version        print package version + bundled kernel provenance
+ *
+ * Dependency-free by design. Makes NO network calls, sends NO telemetry — the payload is
+ * bundled in this package (assembled by the canonical kit/build-kit.sh at publish time).
+ * --update never touches state/, planning/ (except check_rubrics.py), or okf/product/.
+ */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+const PAYLOAD = path.join(__dirname, '..', 'payload'); // the assembled pmos/ kit
+const PKG = require(path.join(__dirname, '..', 'package.json'));
+
+// Kernel paths (relative to the kit root) that --update may rewrite. Everything else is state.
+const KERNEL = [
+  'AGENTS.md',
+  'README.md',
+  'KIT-VERSION',
+  'skills',
+  'okf/core',
+  'scripts',
+  'templates',
+  'planning/evals/check_rubrics.py',
+];
+
+function die(msg) { console.error(`create-pmos: ERROR — ${msg}`); process.exit(1); }
+
+function payloadOrDie() {
+  if (!fs.existsSync(path.join(PAYLOAD, 'AGENTS.md'))) {
+    die('bundled payload missing — this package was not assembled by kit/build-kit.sh; refusing.');
+  }
+}
+
+function kitVersion() {
+  try { return fs.readFileSync(path.join(PAYLOAD, 'KIT-VERSION'), 'utf8').trim(); }
+  catch { return '(no KIT-VERSION in payload)'; }
+}
+
+function stampInstall(kitDir, mode) {
+  const stamp = `installed-via: create-pmos@${PKG.version}\ninstall-mode: ${mode}\ninstalled: ${new Date().toISOString().slice(0, 10)}\n`;
+  fs.appendFileSync(path.join(kitDir, 'KIT-VERSION'), stamp);
+}
+
+function vendor(targetRoot) {
+  payloadOrDie();
+  const kit = path.join(targetRoot, 'pmos');
+  if (fs.existsSync(kit)) die(`${kit} already exists — use --update to refresh its kernel.`);
+  fs.mkdirSync(targetRoot, { recursive: true });
+  fs.cpSync(PAYLOAD, kit, { recursive: true });
+  stampInstall(kit, 'vendor');
+  console.log(`✅ PMOS kit vendored at ${kit} (${kitVersion().split('\n')[0]})`);
+  console.log(`
+Next steps in ${targetRoot}:
+  1. If the repo is not git yet:  git init
+  2. If it lives on GitHub:       cp pmos/templates/pmos-gate.yml .github/workflows/pmos-gate.yml
+  3. Add to the repo's CLAUDE.md: "This product is PMOS-managed (file mode) — read pmos/AGENTS.md before any work."
+  4. Commit the pmos/ folder. Then follow pmos/AGENTS.md for every run.`);
+}
+
+function update(dirArg) {
+  payloadOrDie();
+  // Accept either the kit dir itself or its parent repo root.
+  let kit = path.resolve(dirArg || '.');
+  if (path.basename(kit) !== 'pmos' && fs.existsSync(path.join(kit, 'pmos', 'state'))) {
+    kit = path.join(kit, 'pmos');
+  }
+  if (!fs.existsSync(path.join(kit, 'state'))) {
+    die(`${kit} does not look like a vendored kit (no state/) — refusing to update.`);
+  }
+  for (const rel of KERNEL) {
+    const src = path.join(PAYLOAD, rel);
+    if (!fs.existsSync(src)) continue;
+    const dst = path.join(kit, rel);
+    if (fs.statSync(src).isDirectory()) {
+      fs.rmSync(dst, { recursive: true, force: true });
+      fs.cpSync(src, dst, { recursive: true });
+    } else {
+      fs.mkdirSync(path.dirname(dst), { recursive: true });
+      fs.copyFileSync(src, dst);
+    }
+  }
+  stampInstall(kit, 'update');
+  console.log(`✅ kit kernel updated at ${kit} (${kitVersion().split('\n')[0]})`);
+  console.log('state/, planning/ (beyond check_rubrics.py), and okf/product/ were not touched. Review the diff as a normal PR.');
+}
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+  console.log('usage: create-pmos [target-dir] | create-pmos --update [kit-or-repo-dir] | create-pmos --version');
+} else if (args.includes('--version') || args.includes('-v')) {
+  console.log(`create-pmos ${PKG.version}`);
+  console.log(kitVersion());
+} else if (args.includes('--update')) {
+  update(args.filter((a) => !a.startsWith('-'))[0]);
+} else {
+  vendor(path.resolve(args.filter((a) => !a.startsWith('-'))[0] || '.'));
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "create-pmos",
+  "version": "0.1.0",
+  "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → PRD → eval rubric → contract → build → three gates) entirely inside your own repo, with all state as git-versioned files. No database, no network, no telemetry.",
+  "license": "MIT",
+  "bin": {
+    "create-pmos": "bin/create-pmos.js"
+  },
+  "files": [
+    "bin/",
+    "payload/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "pmos",
+    "product-management",
+    "agent-harness",
+    "eval-driven",
+    "scaffold",
+    "create"
+  ]
+}

package/payload/AGENTS.md

@@ -0,0 +1,83 @@
+# AGENTS.md — PMOS Portable Kit (file mode)
+
+> This file must be read at optimal altitude — concrete heuristics that guide behavior, not brittle
+> if-else rules engines, and not vague mandates that assume shared context.
+
+You are working in a product repo that vendors the **PMOS portable kit** (D54). PMOS here is a
+**control plane** for how work is specced, evaluated, and accepted — it generates no application
+code by itself; you build the product, PMOS disciplines the loop.
+
+## The containment rule (non-negotiable)
+
+**This deployment is file-mode. Make NO network call to any PMOS backend — no MCP connection, no
+`get_skill`, no telemetry, nothing.** Every piece of PMOS state lives in this repo, under `pmos/`.
+This boundary exists because this product's data must not leave its own remote. If you find
+yourself wanting an MCP tool, use the state adapter below instead.
+
+## The state adapter — every PMOS tool is a file convention
+
+| Hosted tool (as skills name them) | File-mode equivalent |
+|---|---|
+| `create_initiative` | write `pmos/state/initiatives/<id>.md` (frontmatter: id, title, parent_kr, stage, status, prd_path, rubric_path, created) |
+| `save_spec` | the PRD file itself at `pmos/planning/prd/<id>-prd.md` (set `prd_path` on the initiative file) |
+| `get_spec` / `get_planning_artifact` | read `pmos/planning/…` |
+| `get_skill` | read `pmos/skills/<name>.skill` |
+| `get_okf_concepts` | read `pmos/okf/…` (index-first, then the concept body — progressive disclosure) |
+| `get_eval_rubric` | read `pmos/planning/evals/<id>-eval-rubric.md` |
+| `log_agent_run` | append one JSON line to `pmos/state/runs.jsonl` (`{run_id, initiative_id, pre_run_contract, self_eval, human_corrections, date}`) |
+| `save_eval` | append one JSON line to `pmos/state/evals.jsonl` (`{run_id, initiative_id, rubric_path, score, verdict, dimensions, date}`) |
+| `record_acceptance` | append one JSON line to `pmos/state/acceptances.jsonl` (`{run_id, initiative_id, accepted, pm_label, note, date}`) — **written only on the PM's explicit word** |
+| `save_okf_doc` | write the doc under `pmos/okf/product/…` marked as a DRAFT; the PM approves it via PR review (the file-mode form of draft→approved) |
+| `register_product_repo` | not applicable — this repo IS the product; skip the step |
+| `log_friction` / `log_discovery` | append to `pmos/state/discoveries.md` (ISO date, `#friction` tag where applicable) |
+| `get_agent_runs` / `get_friction` | read those same files (your episodic memory — consult before contracting) |
+
+State files are **append-only**: never rewrite or delete an existing line or initiative record;
+correct by appending. When a vendored skill names a hosted tool, apply this table — the skill
+bodies are single-sourced from the PMOS kernel and are not forked for file mode.
+
+## Agent run protocol (every run, in order)
+
+1. Read this file.
+2. Read the relevant `pmos/skills/*.skill` for the task type (L1 index first; body when relevant).
+   No skill fits → escalate to the PM; do not improvise a procedure.
+3. Retrieve context: `pmos/okf/` for concepts, `pmos/okf/product/` for this product's knowledge,
+   `pmos/state/runs.jsonl` + `discoveries.md` for what prior runs tried (episodic memory).
+4. Anchor: the initiative file must exist at stage `intake`/`spec` with a PRD and rubric authored
+   **before** build (eval-first, D13). Write the **pre-run contract** into the rubric's sprint
+   contract section and get the PM's explicit approval (`PM_approved: true`) before any work.
+5. Branch `initiative/<id>`; execute at control altitude; one commit per artifact.
+6. Self-evaluate against the contract — self-eval is unreliable; it is an input to the gates, never
+   a verdict.
+7. Close the gates: **Quality** = this repo's CI plus the kit gate (`pmos/scripts/gate-initiative.sh`
+   + `pmos/planning/evals/check_rubrics.py`); **Review** = score against the rubric with the evaluator
+   skill (adversarial, outcome-only, default-to-refute) and append to `evals.jsonl`; **Acceptance**
+   = the human PM merges and disposes — final and non-delegable. Never merge your own PR.
+8. Log the run (`runs.jsonl`) and any friction (`discoveries.md`, `#friction`).
+
+## Escalation (stop and ask the PM)
+
+An architectural choice with no recorded decision; a wrong or unsatisfiable contract; scope growth;
+any destructive/irreversible action; anything that would send product data outside this repo's
+remote. Confirm-first regardless of framing.
+
+## Evaluator leniency warning
+
+The evaluator defaults to generous scoring. Treat the Review Gate as **uncalibrated** in this
+deployment until this repo has accumulated its own PM-vs-evaluator record (append overrides to
+`pmos/planning/evals/eval-calibration.md`; the D40 classifier method applies locally).
+`pmos/scripts/metrics.py` computes the north star (human corrections per accepted run), pass rates,
+and the Goodhart tripwire from `pmos/state/`.
+
+## PM protocol (weekly)
+
+Scan `discoveries.md`; a friction theme seen twice with no resolving decision must be promoted to a
+decision. Read run records since last review; log overrides to `eval-calibration.md`. Run
+`pmos/scripts/metrics.py` and read the red first.
+
+## Kit maintenance
+
+`pmos/KIT-VERSION` records the kernel source. Update the kernel with
+`pmos/scripts/kit-update.sh <path-to-pmos-checkout>` — it re-vendors ONLY `skills/`, `okf/core/`,
+`scripts/`, `AGENTS.md`, `README.md` and never touches `state/`, `planning/`, or `okf/product/`.
+Review the update as a normal PR.

package/payload/KIT-VERSION

@@ -0,0 +1,3 @@
+kernel-source: pmos@1740a5e
+assembled: 2026-07-17
+mode: vendor

package/payload/README.md

@@ -0,0 +1,56 @@
+# PMOS Portable Kit (file mode)
+
+Run the PMOS workflow — initiative → PRD → eval rubric → pre-run contract → build →
+Quality/Review/Acceptance gates — **entirely inside this repo**, with every piece of state as
+git-versioned files. No database, no MCP connection, no network calls to any PMOS backend (D54).
+Built for products whose data must not leave their own remote (e.g. company-owned products vs a
+personally-owned PMOS backend).
+
+## What's in the folder
+
+- `AGENTS.md` — the run protocol. **Start here; every agent session reads it first.** Contains the
+  state adapter: the table mapping each hosted PMOS tool to a file convention.
+- `skills/` — the PMOS skill kernel (prd, eval-rubric, okr, evaluator, …). Single-sourced from the
+  PMOS repo; where a skill names a hosted tool, apply the AGENTS.md state adapter.
+- `okf/core/` — kernel concepts (the sdlc loop, the three-tier gate, watermelon flags, …).
+  `okf/product/` — YOUR product's knowledge; drafted by ingest, approved via PR review.
+- `planning/` — okrs, PRDs, rubrics (`agent-run-eval-rubric.md` is the per-initiative template),
+  `eval-calibration.md` (append every PM override of an evaluator verdict).
+- `state/` — the operational record, **append-only**: `initiatives/<id>.md`, `runs.jsonl`,
+  `evals.jsonl`, `acceptances.jsonl`, `discoveries.md`.
+- `scripts/` — `gate-initiative.sh` (the fail-closed CI gate), `metrics.py` (north star +
+  calibration + Goodhart tripwire), `kit-update.sh` (kernel refresh).
+- `templates/pmos-gate.yml` — CI drop-in; copy to `.github/workflows/`.
+- `KIT-VERSION` — which PMOS kernel this was assembled from.
+
+## Install (once)
+
+No PMOS repo access needed (D55): **`npx create-pmos@latest [target-dir]`** — then follow its
+printed next steps (wire the CI workflow, point CLAUDE.md at `pmos/AGENTS.md`, commit).
+From a PMOS checkout the equivalent is `kit/build-kit.sh <this-repo-root>`; the npm package's
+payload is assembled by that same script at publish time, so the two never drift.
+
+## Operate (every piece of work)
+
+1. Create `pmos/state/initiatives/<id>.md` (stage `intake`, anchored to a KR in `planning/okrs/`).
+2. Author the PRD and the rubric **before building** (copy the rubric template); agree the sprint
+   contract; the PM flips `PM_approved: true`.
+3. Branch `initiative/<id>`, build, open a PR — the `pmos-gate` CI check fails any PR that isn't
+   anchored (branch or `Initiative: <id>` in the PR body; `no-initiative` label for genuine chores).
+4. Review Gate: run the evaluator skill against the rubric; append the verdict to
+   `state/evals.jsonl`. The verdict is advisory until locally calibrated.
+5. Acceptance Gate: the **human PM** merges and disposes; append to `state/acceptances.jsonl`
+   (`accepted`, `pm_label`, corrections). Weekly: run `scripts/metrics.py`, read the red first.
+
+## Update the kernel (occasionally)
+
+`npx create-pmos@latest --update` (or `pmos/scripts/kit-update.sh <path-to-pmos-checkout>` from a
+PMOS checkout) — refreshes ONLY the kernel (skills/okf-core/scripts/AGENTS.md/README/templates),
+stamps `KIT-VERSION`, never touches `state/`, `planning/`, or `okf/product/`. Updates flow
+one-way, PMOS → kit; review the diff as a normal PR.
+
+## The containment guarantee
+
+The assembly script greps its own output and fails on any reference to the hosted PMOS backend.
+Nothing in this folder phones home; the AGENTS.md protocol forbids connecting sessions from this
+repo to any personal PMOS MCP. Isolation is the point.

package/payload/okf/core/concepts/agent-harness.md

@@ -0,0 +1,83 @@
+---
+type: Concept
+title: The Agent Harness
+description: Everything wrapping the model that lets it finish work — and the Summary Gate, the input gate that compresses prior-session context into essential state.
+tags: [harness, agent, context, summary-gate, architecture]
+timestamp: 2026-06-28
+---
+
+# The Agent Harness
+
+**Situating context:** PMOS's deliverables are not application code — they are harness. This concept
+names what a harness is and introduces the **Summary Gate**, the pattern that explains why PMOS's
+structured artifacts beat raw context compaction. It informs AGENTS.md, the OKF bundle's role, and
+the [control plane](/okf/core/concepts/control-plane.md) identity.
+
+## Agent = Model + Harness
+
+A model on its own predicts tokens. An **agent** finishes work. The difference is the **harness**:
+everything wrapping the model that lets a run complete.
+
+The harness includes:
+
+- **Instructions / rule files** — CLAUDE.md, AGENTS.md, DECISIONS.md, PRINCIPLES.md.
+- **Knowledge** — the [OKF bundle](/okf/core/concepts/okf-governance.md): concepts, templates,
+  playbooks.
+- **Skills** — procedural competence loaded on demand
+  ([SKILL-FORMAT](/skills/core/SKILL-FORMAT.md)).
+- **Tools / MCP** — the [ACI surface](/build-skills/MCP-SPEC.md) the agent acts through.
+- **Sandboxes** — where work runs safely.
+- **Orchestration** — sequencing, concurrency, routing.
+- **Guardrails** — the [three-tier eval gate](/okf/core/concepts/output-eval.md), kill conditions.
+- **Observability** — `agent_runs`, [discoveries.md](/discoveries.md), transcript review.
+
+**PMOS builds the harness, not the app.** Improving any harness element improves every future run —
+that is the leverage the [control plane](/okf/core/concepts/control-plane.md) exists to capture.
+
+## The Summary Gate
+
+> **Summary Gate:** PMOS's OKF bundle + SKILL.md + AGENTS.md constitute a *Summary Gate* — an input
+> gate that compresses prior-session context into essential state before a new agent session begins.
+
+A model's context window is finite and a project's history is not. Something has to decide what
+crosses from "everything that happened" into "what the next session actually needs." That decider is
+the Summary Gate.
+
+### What it does
+
+- **Compresses** prior-session context into essential state: the decisions, the knowledge, the
+  contracts — not the transcript.
+- **Extracts key decisions and discards intermediate reasoning.** The *conclusion* ("we decided X
+  because Y") crosses the gate; the deliberation that produced it does not.
+- **Prevents context pollution** — stops the next session from inheriting stale, contradictory, or
+  irrelevant intermediate state that would degrade its judgment.
+
+### Why structured handoff beats raw compaction
+
+Raw context compaction (summarizing a transcript) preserves *narrative* — it keeps a lossy trace of
+what was said. A Summary Gate preserves *state* — it keeps the durable decisions and knowledge in
+purpose-built artifacts (OKF concepts, skills, AGENTS.md) that are authored to be read fresh.
+
+A new session reading a hand-authored decision record starts from clean, intentional state. A new
+session reading a compacted transcript starts from a blurry recollection of a conversation. **This
+is why PMOS invests in structured handoff artifacts instead of relying on context compaction** — the
+artifacts *are* the gate, and they are designed to survive the session boundary intact.
+
+## Optimal altitude
+
+Harness instructions must be written at **optimal altitude**: concrete heuristics that guide
+behavior, not a brittle if-else rules engine, and not a vague mandate that assumes shared context.
+Too low and the harness is rigid and breaks on the first unforeseen case; too high and it gives no
+real guidance. AGENTS.md and every skill body are held to this standard.
+
+## Relationship to autonomy and drift
+
+The harness is what makes higher [autonomy](/okf/core/concepts/output-eval.md) safe: the better the
+guardrails, observability, and Summary Gate, the longer an agent can run unattended without producing
+[silent drift](/okf/core/concepts/watermelon-flag.md). Harness quality and safe autonomy rise
+together — which is why the quarterly harness assumption review exists.
+
+The harness also **improves from its own runs**: evals, friction, and calibration data are evidence for
+the next harness edit. See [self-refining-harness](/okf/core/concepts/self-refining-harness.md) — the
+detect → draft → PM-gate loop that turns run evidence into harness edits, bounded at L3 so it never
+becomes L4 self-mutation.

package/payload/okf/core/concepts/control-plane.md

@@ -0,0 +1,61 @@
+---
+type: Concept
+title: The Control Plane
+description: What it means for PMOS to be a control plane — it orchestrates, specs, evaluates, and routes agent work rather than generating production code itself.
+tags: [control-plane, architecture, orchestration, identity]
+timestamp: 2026-06-28
+---
+
+# The Control Plane
+
+**Situating context:** "PMOS is a control plane, not a code generator" is the load-bearing identity
+claim of the whole product, and it is easy to forget mid-build. This concept fixes what that claim
+means so design decisions stay on the right side of the line. It informs every artifact: if a thing
+generates production app code, it is not PMOS's job.
+
+## Control plane vs. data plane
+
+The term is borrowed deliberately. In systems architecture:
+
+- The **data plane** does the work — moves the packets, serves the requests, *generates the code*.
+- The **control plane** decides what the data plane should do — configures, schedules, routes,
+  observes, governs.
+
+**PMOS is the control plane. The coding agents are the data plane.** PMOS orchestrates, specs,
+evaluates, and routes agent work; it does **not** itself generate production application code. The
+thing PMOS controls is the [agent harness](/okf/core/concepts/agent-harness.md), not the end app.
+
+## What the control plane actually does
+
+PMOS's four control-plane functions map onto the [SDLC loop](/okf/core/concepts/sdlc-loop.md):
+
+1. **Spec** — turn intent into a contract: PRDs, pre-run contracts, done-criteria. The control plane
+   says *what* should be built and *why*.
+2. **Evaluate** — judge what came back through the
+   [three-tier gate](/okf/core/concepts/output-eval.md). The control plane decides whether output is
+   acceptable.
+3. **Route** — direct work to the right agent, skill, and OKF context; escalate to the human when
+   needed. The control plane decides *who/what* does the work.
+4. **Orchestrate** — sequence runs, manage concurrency, close the loop by writing knowledge back.
+   The control plane decides *when* and *in what order*.
+
+Notice what is absent: *writing the application*. That is the data plane's job.
+
+## Why the distinction is load-bearing
+
+If PMOS starts generating production code, it stops being a control plane and becomes just another
+code generator — and it loses the leverage that makes it valuable. The control plane's power is that
+it improves the **harness** (instructions, skills, gates, OKF knowledge), and a better harness
+improves *every* agent run, not one feature. Conflating the planes collapses that leverage:
+
+- Keep PMOS's outputs at the control altitude — specs, rubrics, routing decisions, knowledge.
+- Push code generation down to agents operating inside the harness PMOS defines.
+- When a proposed PMOS feature would emit production app code, that is the signal it belongs in the
+  data plane, not here.
+
+## Relationship to the harness
+
+The control plane *controls* the harness; the harness *wraps* the model so a run can finish. PMOS's
+deliverables — OKF bundle, skills, AGENTS.md, eval gates — **are** the harness configuration. See
+[agent-harness](/okf/core/concepts/agent-harness.md) for what the harness contains and the
+**Summary Gate** that compresses context into it between sessions.

package/payload/okf/core/concepts/design-loop.md

@@ -0,0 +1,117 @@
+---
+type: Concept
+title: The Design Loop
+description: How a PM runs UI/UX design as a first-class, repeatable, product-scoped sub-flow of the Build stage — brief → design → reconcile → build → design-sync — gated by the Review Gate, presentation-only, never a data decision. PMOS's own app is one instance.
+tags: [design, ui, workflow, build, reconciliation, watermelon]
+timestamp: 2026-07-01
+---
+
+# The Design Loop
+
+**Situating context:** Any product a PM runs through PMOS may have a user-facing surface that needs UI/UX
+design. That design was an out-of-band activity — a brief handed to claude.ai/design, an ad-hoc
+reconciliation, a build, a sync back — never named as a loop, never made a skill, never gated. This concept
+names that loop **product-agnostically** (PMOS's own `web/` control-plane app is one instance — see
+[Per-product instances](#per-product-instances-pmos-and-tenants) below), so the
+[intake checklist](/planning/prd/initiative-intake-checklist.md), the skills, and [AGENTS.md](/AGENTS.md) all
+refer to one thing. **The load-bearing claim: design is a sub-flow of the
+[Build stage](/okf/core/concepts/sdlc-loop.md) (stage 3), not a new lifecycle stage.** It informs any
+initiative that adds or changes a user-facing surface.
+
+## The loop
+
+An initiative with a user-facing surface runs four legs *inside* Build:
+
+```
+   1. BRIEF ──────► 2. DESIGN ────────► 3. RECONCILE + BUILD ──────► 4. DESIGN-SYNC
+   (design-brief    (claude.ai/design,   (design-reconcile gate,      (/design-sync skill:
+    skill)           external)            then the design-system        export the real web/
+                                          build, web-ci)                library back)
+```
+
+1. **Brief** — the [design-brief skill](/skills/core/design-brief.skill) writes the context handoff: what
+   to design and the hard, presentation-only constraints, each surface tied to a real data source. It is to
+   design what the [PRD](/skills/core/prd.skill) is to build.
+2. **Design** — the design is made in claude.ai/design (external to this repo).
+3. **Reconcile + build** — the [design-reconcile skill](/skills/core/design-reconcile.skill) classifies
+   every surface against **the product's capability ledger** and the PM signs off before any code; then the
+   design is built into the product's app on its design system, verified by the product's CI. (For PMOS's own
+   app the ledger is [web-capability-ledger.md](/planning/web-capability-ledger.md), the system is D38, and
+   CI is `web-ci`.)
+4. **Design-sync** — the external `/design-sync` Claude Code skill exports the now-real component library back
+   to claude.ai/design (for PMOS, see [.design-sync/conventions.md](/.design-sync/conventions.md)), so the
+   next design starts from the product's actual parts.
+
+Legs 2 and 4 are external tools PMOS *references*; legs 1 and 3 are the PMOS skills that make the loop
+repeatable.
+
+## Presentation-only is the load-bearing constraint
+
+Design is **behavior-preserving**: no new views, no new data, no changed flows — presentation only. If a
+design implies a data or feature change, it is **flagged back as a separate decision**, never smuggled into
+the build. This is what keeps design at [control altitude](/okf/core/concepts/control-plane.md) and stops it
+from becoming a backdoor for architecture the PM never decided.
+
+## Reconciliation is the watermelon defense for UI
+
+Leg 3's classification — **Supported** (maps to a real read/write) / **Cosmetic** (pure presentation, free)
+/ **Available-unsurfaced** (data exists, opt-in) / **Unsupported** (no backend) — is the
+[watermelon-flag](/okf/core/concepts/watermelon-flag.md) concept applied to a design. A control that *looks*
+functional with no backend behind it is **watermelon-UI**: green on the surface, hollow underneath. The
+canonical instance is a Routing screen offering provider connections and API-key fields when PMOS has no
+connections table and must never hold API keys client-side. Reconciliation catches these before any code;
+the PM signs off the Unsupported dispositions as an [Acceptance-Gate](/okf/core/concepts/output-eval.md) call.
+
+## Where design meets the three-tier gate
+
+Design is judged by the standard [three-tier gate](/okf/core/concepts/output-eval.md), not a bespoke one:
+
+- **Quality Gate** — the product's CI (build/lint; `web-ci` for PMOS's own app) and token-hygiene checks (no raw hex where a semantic token exists).
+- **Review Gate** — the reusable [design-fidelity rubric](/planning/evals/design-fidelity-eval-rubric.md):
+  weighted dimensions led by *capability-honesty / no-watermelon-UI*, then token-adherence, accessibility
+  (not color alone), information density, interaction clarity, behavior-preservation. The rubric *is* the
+  design spec ([eval-driven PM](/okf/core/concepts/eval-driven-pm.md)).
+- **Acceptance Gate** — the PM confirms visual parity and honors the reconciliation dispositions. Non-delegable.
+
+## Why a sub-flow of Build, not a new stage
+
+Design changes no world-state of an initiative independent of building — by its own presentation-only charter
+it is *how a surface being built looks*. Giving it a board column would imply a parallel lifecycle, force a
+data-model change to the stage machinery, and contradict the charter. PMOS makes a capability first-class by
+making it **retrievable, repeatable, and gated** (this concept + the two skills + the rubric), not by adding a
+swimlane — the same move that self-hosted the eval layer. (If design-approval and build-start ever decouple in
+time such that the board hides real "designed-but-not-built" state, the lighter first step is a `specs` row of
+`kind:'design'` in the board drawer — still no new stage. Recorded as the revisit trigger in D48.)
+
+## Per-product instances (PMOS and tenants)
+
+The loop is a **method**; PMOS's own app is just its first instance. What is **shared** vs **per-product** (D50):
+
+- **Shared, authored once, read by every PM** — this concept, the [design-brief](/skills/core/design-brief.skill)
+  and [design-reconcile](/skills/core/design-reconcile.skill) skills, the
+  [design-brief template](/okf/core/templates/design-brief-template.md), and the **generic dimensions** of the
+  [design-fidelity rubric](/planning/evals/design-fidelity-eval-rubric.md). These live in PMOS-self's knowledge
+  and are already reachable by tenants (repo-managed OKF rows are shared-read, D37; the `skills` table is
+  select-all).
+- **Per-product, authored by each tenant** — its **capability ledger** (reconciliation checks a design against
+  *that* product's real reads/writes), its **design system** (chosen at the product's IRS gate, D46 — not
+  PMOS's D38), and its **brief + fidelity-rubric instance** (the generic dimensions plus the product's own
+  tokens/surfaces).
+- **Where the build runs** — **leg-3 build executes in the product's own repo** (D46): PMOS creates the shell
+  and holds the spec (brief), the reconcile gate, and the rubric; it does not build the tenant's app
+  ([control plane](/okf/core/concepts/control-plane.md), D01).
+
+PMOS's own instance: the `web/` app, the [D38](/okf/products/pmos/adr/d38-design-system.md) design system, and
+[web-capability-ledger.md](/planning/web-capability-ledger.md).
+
+## Relationship to other concepts
+
+- Design is a sub-flow of the [SDLC loop](/okf/core/concepts/sdlc-loop.md)'s Build stage.
+- It is gated by the [three-tier gate](/okf/core/concepts/output-eval.md) and run in an
+  [eval-driven](/okf/core/concepts/eval-driven-pm.md) style (the fidelity rubric before the build).
+- Reconciliation is [watermelon-flag](/okf/core/concepts/watermelon-flag.md) applied to UI.
+- PMOS stays a [control plane](/okf/core/concepts/control-plane.md): it specs and evaluates design; the design
+  itself is made in claude.ai/design and built by a build agent.
+- Formalized by [D48](/okf/products/pmos/adr/d48-design-loop.md); made product-scoped by
+  [D50](/okf/products/pmos/adr/d50-design-loop-product-scoped.md); composes with the design *system* (D38,
+  PMOS's own instance).