create-pmos 0.1.0

package/payload/okf/core/concepts/eval-driven-pm.md

@@ -0,0 +1,71 @@
+---
+type: Concept
+title: Eval-Driven Product Management
+description: 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.
+tags: [evaluation, method, product-management, eval-driven]
+timestamp: 2026-06-28
+---
+
+# Eval-Driven Product Management
+
+**Situating context:** This concept names PMOS's central operating method — the thing that makes it a
+distinct way to do product management rather than just a folder of skills. It ties together the
+[SDLC loop](/okf/core/concepts/sdlc-loop.md), the [eval gate](/okf/core/concepts/output-eval.md), and
+[pre-run contracts](/okf/core/concepts/sdlc-loop.md). It informs why the eval-rubric skill exists and
+why contracts come before builds.
+
+## The core move: write the eval first
+
+Eval-driven PM is test-driven development lifted to the product altitude: **define how you will judge
+the output before any output exists.** The eval rubric is written, and the pre-run contract agreed,
+*before* the agent builds anything.
+
+This inverts the default. The default is: build, then ask "is this good?" Eval-driven PM is: decide
+what "good" means, then build to it. The rubric **is** the spec; building is the act of satisfying a
+spec that was made measurable in advance.
+
+## Why before, not after
+
+Writing the eval after the build corrupts the judgment in three ways:
+
+1. **The output anchors the standard.** Once you have seen what the agent produced, your idea of
+   "good enough" silently bends to match it. A rubric written in ignorance of the output is the only
+   honest one.
+2. **There is nothing to fail against.** Without a prior standard, evaluation degenerates into "does
+   this look fine?" — which is exactly the [evaluator leniency](/okf/core/concepts/output-eval.md)
+   failure, made structural.
+3. **Drift has no tripwire.** A pre-committed standard is what lets you notice
+   [silent drift](/okf/core/concepts/watermelon-flag.md): the output meets the rubric or it does
+   not, and you defined the rubric back when you still remembered the intent.
+
+## The PM manages by defining "good," not by inspecting work
+
+In eval-driven PM, the PM's primary leverage is *upstream*: authoring the rubric, agreeing the
+contract, setting the threshold. By the time work comes back, most of the management has already
+happened — it lives in the standard the work is measured against.
+
+This is why the PM's end-of-run role is the [Acceptance Gate](/okf/core/concepts/output-eval.md), not
+line-by-line inspection. The Quality and Review gates check the work against the pre-written rubric
+mechanically; the PM's scarce attention is spent on the one question the rubric cannot answer — *is
+this the right thing?* — and on whether the rubric itself was right.
+
+## How it shapes the loop
+
+- **Spec stage** authors the rubric alongside the PRD — the
+  [eval-rubric skill](/skills/core/eval-rubric.skill) and [prd skill](/skills/core/prd.skill) are
+  paired for this reason.
+- **Contract stage** turns the rubric into agreed, testable done-criteria the generator and evaluator
+  both sign off on before work starts.
+- **Evaluate stage** runs the output against the pre-committed rubric — outcome-only, weighted,
+  partial-credit.
+- **Learn stage** feeds rubric calibration back into
+  [eval-calibration.md](/planning/evals/eval-calibration.md): when the PM and evaluator disagree, the
+  rubric or the evaluator prompt — not the memory of what happened — gets fixed.
+
+## Calibration is part of the method
+
+An eval-driven system is only as trustworthy as its evals, and PMOS's evals start
+**uncalibrated** (evaluator leniency). Eval-driven PM therefore includes a calibration discipline:
+treat early P1 runs as calibration cycles, log PM overrides, and patch the evaluator until PM and
+evaluator agree. The method is not "trust the eval" — it is "make the eval trustworthy, then manage
+through it."

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

@@ -0,0 +1,17 @@
+# core/concepts — Index
+
+OKF reserved file (no frontmatter). Directory listing for progressive disclosure — read this
+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-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.
+- [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.
+- [okr-tree](okr-tree.md) — How PMOS structures Objectives and Key Results as a tree that links strategy to initiatives and to the agent runs that move them.
+- [output-eval](output-eval.md) — How PMOS evaluates agent output through three escalating gates — Quality, Review, Acceptance — and why the PM owns only the last one.
+- [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.
+- [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

@@ -0,0 +1,6 @@
+# core/concepts — Log
+
+OKF reserved file (no frontmatter). Change history, newest first, ISO 8601 dates.
+
+## 2026-06-29
+- Creation — per-folder index/log added (OKF recursive progressive disclosure; D29 reversal direction).

package/payload/okf/core/concepts/okf-governance.md

@@ -0,0 +1,159 @@
+---
+type: Concept
+title: OKF Namespace Structure & Governance Model
+description: How PMOS organizes its Open Knowledge Format bundle and the governance rules that keep it spec-conformant.
+tags: [okf, governance, knowledge-management, namespace, reference-layer]
+timestamp: 2026-06-29
+---
+
+# OKF Namespace Structure & Governance Model
+
+**Situating context:** This is the first OKF concept authored in PMOS. It exists because every
+other concept, template, and playbook in the bundle needs a shared, unambiguous answer to two
+questions: *what is OKF here* and *how do we keep the bundle from drifting into a bespoke schema*.
+It informs every authoring decision for files under `/okf/`.
+
+## What OKF is
+
+OKF stands for **Open Knowledge Format** — the Google Cloud open spec (v0.1 draft) at
+<https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md>.
+
+It is **not** "Organizational Knowledge Fabric" or any other expansion. Do not invent one.
+
+OKF is a deliberately minimal format: **a directory of Markdown files with YAML frontmatter.**
+There is no schema registry, no central authority, and no required tooling. PMOS conforms strictly
+to this spec rather than layering a custom schema on top of it.
+
+## What lives in OKF (and what does not)
+
+OKF holds **timeless, curated knowledge** — the things that stay true across sessions and remain
+useful as reference:
+
+- Concepts (mental models, definitions, principles)
+- ADRs (architecture decision records)
+- Templates (PRD template, eval-rubric template)
+- Playbooks (repeatable procedures)
+
+OKF does **not** hold operational records. PRDs instances, eval-rubric instances, OKR instances,
+and agent run traces are operational state — they live in Supabase (P1+) and under `/planning/`
+(P0), **not** in the OKF bundle. The test: if it is a dated instance of work, it is operational;
+if it is reusable knowledge, it belongs in OKF.
+
+### Two layers: concepts and references
+
+The bundle holds two kinds of curated knowledge that age differently:
+
+- **Concept layer** (`core/`) — timeless mental models, definitions, principles, templates,
+  playbooks. Changes by insight, rarely.
+- **Reference layer** (`products/<product_slug>/`) — a **catalog of the system's concrete assets**:
+  one small, individually-retrievable doc per Supabase table (its schema + RLS shape), per derived
+  view/metric, per MCP tool (the ACI), and per locked decision (an `ADR` view of `DECISIONS.md`).
+  This is exactly how upstream OKF bundles work — they catalog every table, metric, and join — and
+  it is the layer that **must track the backbone**: it changes whenever the system changes.
+
+Both layers are still *knowledge about the system*, not operational rows. A `data-model` doc
+describes a table's **shape and rules**; it never contains the table's data. An `ADR` doc is a
+curated **view** of a decision; `DECISIONS.md` stays the single source of truth. The reference layer
+is kept in sync by the [okf-sync playbook](/okf/core/playbooks/okf-sync.md) — the standing cadence
+that stops the bundle freezing while the product evolves.
+
+## The bundle
+
+A **Knowledge Bundle** is a self-contained hierarchical collection of OKF concept documents — the
+unit of distribution. PMOS's `/okf/` tree is one bundle:
+
+```
+okf/                      ← the bundle root
+├── index.md              ← reserved: directory listing (progressive disclosure)
+├── log.md                ← reserved: chronological update history, newest first
+├── core/                 ← canonical, cross-cutting knowledge
+│   ├── concepts/         ← mental models and definitions (this file lives here)
+│   ├── templates/        ← reusable document templates
+│   └── playbooks/        ← repeatable procedures
+├── products/
+│   └── pmos/             ← product-scoped knowledge namespace
+├── shared/               ← concepts promoted for cross-PM reuse
+└── sources/              ← raw ingested artifacts (immutable)
+```
+
+**Concept ID = the file path within the bundle, minus the `.md` suffix.** For example, this
+document's concept ID is `core/concepts/okf-governance`.
+
+### Namespace intent
+
+- `core/` — knowledge that is canonical to PMOS and cuts across products.
+- `products/<product_slug>/` — knowledge scoped to one product (e.g. `products/pmos/`).
+- `shared/` — concepts promoted out of a product or PM namespace because they generalize across
+  PMs. Promotion is deliberate, not automatic.
+- `sources/` — raw ingested artifacts kept **immutable** as provenance. Concepts are extracted
+  *from* sources into `core/`/`products/`; sources themselves are never edited in place.
+
+## Frontmatter rules (spec-conformant)
+
+The **only required** frontmatter field is **`type`** — a short, self-explanatory string. Examples:
+`Concept`, `Playbook`, `ADR`, `Reference`, `Template`.
+
+**Recommended** fields, in priority order:
+
+1. `title` — human-readable name.
+2. `description` — one-line summary; used for relevance decisions during retrieval.
+3. `resource` — canonical URI for the concept. **Omit** for abstract concepts that have no
+   canonical external URI.
+4. `tags` — list of short topic labels.
+5. `timestamp` — ISO 8601 last-modified date.
+
+### Fields we explicitly dropped
+
+Earlier PMOS design drafts referenced custom required fields: `status`, `confidence`,
+`last_validated`, `namespace`, `owner`, `knowledge_type`, `enrichment_cadence`. **These are not
+required and default to absent.** Conforming to the open spec means not reinventing its schema.
+
+- Map `knowledge_type` → spec `type`.
+- Map `last_validated` → spec `timestamp`.
+- If any other field is genuinely needed, it may appear **only** as an optional, producer-defined
+  extension key — but the default is to **not** add it.
+
+## Reserved filenames
+
+Two filenames are reserved and **must not** be used as concept documents:
+
+- **`index.md`** — a directory listing that supports progressive disclosure (an agent reads the
+  index to decide what else to load). It has **no frontmatter**.
+- **`log.md`** — a chronological update history, **newest first**, using ISO dates.
+
+## Cross-linking
+
+Link concepts with standard Markdown links. **Absolute bundle-relative links** (beginning with `/`)
+are preferred, e.g. `[OKR tree](/okf/core/concepts/okr-tree.md)`. Broken links are **tolerated** —
+they may point at knowledge that has not been written yet, which is a feature, not an error.
+
+## Governance: permissive conformance
+
+PMOS governance is intentionally permissive. Tooling and reviewers **must tolerate**:
+
+- Unknown `type` values.
+- Missing optional (recommended) fields.
+- Unknown extra producer-defined keys.
+- Broken cross-links.
+- Missing `index.md` files.
+
+CI frontmatter linting **may enforce** the presence of the `type` field, but **must not** reject a
+document for missing optional fields or for carrying extra keys. The bias is toward accepting
+knowledge and improving it in place, not gatekeeping it out.
+
+## Lifecycle
+
+1. **Ingest** — raw artifacts land immutably in `/okf/sources/`.
+2. **Extract** — concepts are distilled from sources into `core/concepts/` or
+   `products/<product_slug>/`, each with situating context (where it came from, why, what decision
+   it informs).
+3. **Sync** — when the live backbone changes (a new table, view, MCP tool, or decision), the matching
+   **reference doc** is authored or refreshed in the same change, per the
+   [okf-sync playbook](/okf/core/playbooks/okf-sync.md). This is what keeps the reference layer from
+   freezing behind the product.
+4. **Promote** — concepts that generalize across PMs move to `/okf/shared/`.
+5. **Record** — every meaningful change is appended to `/okf/log.md` (newest first), and to the
+   namespace `log.md` for product-scoped changes.
+
+This lifecycle keeps provenance immutable, knowledge curated, the reference layer current, and the
+bundle spec-conformant.

package/payload/okf/core/concepts/okr-anti-optimism.md

@@ -0,0 +1,54 @@
+---
+type: Concept
+title: OKR Anti-Optimism Reporting
+description: Why PMOS biases status reporting toward pessimism — surfacing the red underneath green metrics — to keep KR self-reporting honest.
+tags: [okr, reporting, governance, drift, honesty]
+timestamp: 2026-06-28
+---
+
+# OKR Anti-Optimism Reporting
+
+**Situating context:** OKRs are self-reported, and self-reported progress drifts optimistic —
+especially when an agent is grading its own work. This concept defines the anti-optimism stance that
+keeps [OKR](/okf/core/concepts/okr-tree.md) reporting honest. It is one of the two structural
+defenses against [silent drift](/okf/core/concepts/watermelon-flag.md) and it informs how every
+status report in PMOS is written.
+
+## The default is optimism; the rule is anti-optimism
+
+Left alone, status reporting rounds up. A KR at 60% gets reported as "on track." An evaluator unsure
+of an output scores it generously ([evaluator leniency](/okf/core/concepts/output-eval.md)). An agent
+summarizing its own run emphasizes what worked. Each rounding is small; together they manufacture a
+[watermelon flag](/okf/core/concepts/watermelon-flag.md).
+
+PMOS counters with a standing rule: **report the red, not the rounded-up green.** When in doubt,
+report the more pessimistic reading and make the uncertainty explicit.
+
+## What anti-optimism reporting requires
+
+1. **Lead with what is off-track.** A status report names the red and amber items first; green is the
+   short tail, not the headline.
+2. **Confidence, not just status.** "KR at 60%, *low confidence* it reaches target" carries more
+   information than "on track." State how sure you are, separately from where you are.
+3. **No green without evidence of strategic alignment.** A metric being green is not permission to
+   call the initiative green. Automated-green is necessary, not sufficient — the
+   [Acceptance Gate](/okf/core/concepts/output-eval.md) confirms strategic green.
+4. **Name the gap to intent.** Where the work has bent away from the parent objective, say so
+   explicitly, even if every individual run passed.
+5. **Surface friction.** Anything that fought the harness goes to
+   [discoveries.md](/discoveries.md) tagged `#friction`, not buried in a success summary.
+
+## Why this is structural, not cultural
+
+"Be honest in reports" is a vague mandate; PMOS makes it a structural requirement because the system
+depends on it. Anti-optimism reporting is what makes a watermelon **visible while it is still green
+on the skin** — early enough for the PM to re-anchor the initiative before accumulated drift becomes
+expensive. Pair it with the Acceptance Gate: the gate is the human check, anti-optimism reporting is
+the input that gives the human something true to check.
+
+## Anti-optimism is not pessimism for its own sake
+
+The goal is *calibration*, not gloom. Over-reporting red is also a failure — it trains the PM to
+ignore reports. The discipline is: report the honest reading, weight uncertainty toward the
+downside, and always separate "where we are" from "how confident we are." A well-calibrated amber is
+worth more than a confident green or a reflexive red.

package/payload/okf/core/concepts/okr-tree.md

@@ -0,0 +1,67 @@
+---
+type: Concept
+title: OKR Tree Structure
+description: How PMOS structures Objectives and Key Results as a tree that links strategy to initiatives and to the agent runs that move them.
+tags: [okr, strategy, planning, measurement]
+timestamp: 2026-06-28
+---
+
+# OKR Tree Structure
+
+**Situating context:** PMOS routes agent work, and work without a strategic anchor is how silent
+drift starts. This concept defines the OKR tree so every initiative — and ultimately every agent run
+— can be traced to a measurable objective. It informs the `okr` skill, OKR instance files under
+`/planning/okrs/`, and how the Acceptance Gate judges strategic fit.
+
+## The tree
+
+PMOS models strategy as a tree, not a flat list:
+
+```
+Objective (qualitative, directional — the "what we want to be true")
+└── Key Result (quantitative, measurable — the "how we'll know")
+    └── Initiative (a unit of work — owns a PRD + eval rubric)
+        └── Agent run (a single execution against the initiative's contract)
+```
+
+- **Objective** — a qualitative, time-boxed statement of intent. Inspirational and directional;
+  carries no number itself. *"PMOS agent output is trustworthy enough to ship without rework."*
+- **Key Result** — a quantitative, measurable outcome that proves the objective is being met.
+  Each objective has 2–5 KRs. *"Human correction rate per agent run < 0.5 by end of Q3."*
+- **Initiative** — a concrete body of work expected to move one or more KRs. Each initiative owns a
+  PRD ([prd skill](/skills/core/prd.skill)) and an eval rubric
+  ([eval-rubric skill](/skills/core/eval-rubric.skill)).
+- **Agent run** — the leaf: one execution against an initiative's pre-run contract, logged to
+  `agent_runs`.
+
+## Edges carry meaning
+
+The value of the tree is in its edges. Every node must answer "what is my parent?":
+
+- A KR with no parent objective is an orphan metric — measuring something nobody decided matters.
+- An initiative with no parent KR is **unanchored work** — the structural seed of silent drift.
+  PMOS treats unanchored initiatives as a red flag at intake, not a detail to fill in later.
+- An agent run inherits its strategic justification from its initiative's KR. This is what lets the
+  Acceptance Gate ask "is this the *right* thing?" with a concrete reference.
+
+## Key Results measure outcomes, not output
+
+A KR measures a **change in the world**, not a count of work done. "Ship 5 features" is output;
+"reduce human correction rate to < 0.5" is an outcome. Output-based KRs invite the watermelon-flag
+failure: green activity numbers hiding red strategic reality. Pair this concept with
+[anti-optimism reporting](/okf/core/concepts/okr-anti-optimism.md) and the
+[watermelon flag](/okf/core/concepts/watermelon-flag.md) — they are the defenses that keep KR
+self-reporting honest.
+
+## The north star sits above the tree
+
+PMOS's north-star metric — **human correction rate per agent run** (lower is better) — is the
+standing measure the tree exists to move. Quarterly objectives change; the north star persists.
+Individual KRs should ladder toward it, directly or indirectly.
+
+## Cadence
+
+- OKRs are set per planning period (PMOS's first set: `okrs-q3-2026.md` under `/planning/okrs/`).
+- KRs are reviewed on the PM's regular cadence; objectives are reset each period.
+- The OKR file is an **operational instance** — it lives under `/planning/`, not in OKF. This
+  concept is the timeless *structure*; the quarterly file is the dated *content*.

package/payload/okf/core/concepts/output-eval.md

@@ -0,0 +1,81 @@
+---
+type: Concept
+title: Output Evaluation — The Three-Tier Gate
+description: How PMOS evaluates agent output through three escalating gates — Quality, Review, Acceptance — and why the PM owns only the last one.
+tags: [evaluation, gates, quality, acceptance, governance]
+timestamp: 2026-06-28
+---
+
+# Output Evaluation — The Three-Tier Gate
+
+**Situating context:** Every turn of the [SDLC loop](/okf/core/concepts/sdlc-loop.md) ends by
+judging what an agent produced. This concept defines the three-tier gate that judgment runs through,
+so the [eval-rubric skill](/skills/core/eval-rubric.skill), AGENTS.md, and the PM all use the same
+vocabulary. It informs where automation stops and human judgment begins.
+
+## The three tiers
+
+Output passes through three escalating gates. Each answers a different question, with a different
+nature and a different owner.
+
+### 1. Quality Gate — *does it work?*
+
+- **Nature:** deterministic, automated.
+- **Checks:** compile, lint, unit tests — toolchain-enforced pass/fail.
+- **Owner:** the toolchain. No judgment involved; either the tests pass or they do not.
+- A failure here never reaches a human; it bounces back to the agent.
+
+### 2. Review Gate — *does it satisfy the rubric?*
+
+- **Nature:** probabilistic, adversarial.
+- **Checks:** does the output meet the rubric criteria for this initiative? Applied by a separate
+  **evaluator agent** or by the PM acting as critic.
+- **Owner:** evaluator agent (or PM-as-critic).
+- This gate is **uncalibrated** until 5–10 P1 cycles are validated — the evaluator defaults to
+  generous scoring (**evaluator leniency**). Treat its verdict as advisory until calibrated against
+  [eval-calibration.md](/planning/evals/eval-calibration.md).
+
+### 3. Acceptance Gate — *is it the right thing?*
+
+- **Nature:** subjective, strategic.
+- **Checks:** strategic fit. Is this what the product actually needs right now? Does it move the
+  parent KR? **This is NOT a re-check of the rubric.**
+- **Owner:** the **human PM only**. Non-delegable.
+- The PM's role at the end of every agent run **is** the Acceptance Gate.
+
+## Why three, and why the order
+
+The gates escalate from cheap-and-certain to expensive-and-strategic:
+
+- Quality is **cheap and certain** — run it first, fail fast, never spend human attention on broken
+  output.
+- Review is **mid-cost and probabilistic** — it filters rubric misses before they reach the PM, but
+  its judgment is fallible.
+- Acceptance is **expensive and irreducibly human** — it is the only gate that asks whether the work
+  *should* exist, not whether it was done correctly.
+
+Running them out of order wastes the scarce resource (PM attention) on problems the cheap gates
+would have caught.
+
+## The Acceptance Gate is not the Review Gate
+
+The most important distinction in this concept: **passing the rubric is not the same as being
+right.** An output can satisfy every rubric criterion and still be the wrong thing to build — that
+is exactly the [silent drift](/okf/core/concepts/watermelon-flag.md) failure. The Acceptance Gate
+exists *because* rubric satisfaction is not strategic correctness. Collapsing the two — letting a
+green Review Gate auto-accept — removes the only structural defense against drift.
+
+## Grading discipline
+
+- **Outcome-only:** gates check what the agent *produced*, not the path it took. Do not grade tool
+  call sequences.
+- **Weighted, with partial credit:** the Review Gate scores weighted dimensions and totals against a
+  threshold; it is not all-or-nothing. (See the
+  [eval-rubric skill](/skills/core/eval-rubric.skill) and
+  [template](/okf/core/templates/eval-rubric-template.md).)
+
+## Relationship to autonomy
+
+As PMOS moves L2 → L3, more of the Quality and Review gates run unattended. The Acceptance Gate
+stays human at every autonomy level up to the declared L3 ceiling. Keeping that gate human is what
+makes higher autonomy safe rather than reckless.

package/payload/okf/core/concepts/pm-identity.md

@@ -0,0 +1,68 @@
+---
+type: Concept
+title: PM Identity Model
+description: How PMOS models a product manager — the pm_slug identifier, the PM's authority as the human in the loop, and PM-scoped namespaces.
+tags: [identity, pm, governance, namespace]
+timestamp: 2026-06-28
+---
+
+# PM Identity Model
+
+**Situating context:** PMOS is a PM control plane, so "who is the PM" is a primitive the whole
+system is built around — paths, records, and the final human gate all reference it. This concept
+fixes that model so skills, OKF namespaces, and agent records resolve a PM the same way. It informs
+every place a `pm_slug` appears and every decision about who holds authority.
+
+## The PM is the human in the loop
+
+PMOS does not replace the product manager — it gives the PM a control surface over agent work. The
+PM is the single accountable human. Agents generate; the PM **decides**. This is structural, not
+advisory: the end of every agent run is an **Acceptance Gate** (a subjective, strategic "is this
+the *right* thing?" judgment) that **only the human PM** can clear. See
+[/okf/core/concepts/output-eval.md](/okf/core/concepts/output-eval.md) for the three-tier gate
+model the Acceptance Gate sits in.
+
+## `pm_slug` — the stable identifier
+
+Every PM has a **`pm_slug`**: a stable, lowercase, URL-safe identifier. It is the canonical
+reference to a PM across paths, records, and skill namespaces.
+
+- Rules: lowercase, no spaces, stable for the life of the PM's participation. Treat it like a
+  primary key — never rename casually, because paths and records point at it.
+- For this instance, **`pm_slug: wawan`**.
+- It pairs with `product_slug` (see
+  [/okf/core/concepts/product-slug-convention.md](/okf/core/concepts/product-slug-convention.md))
+  to fully scope work: *which PM*, *which product*.
+
+## PM-scoped namespaces
+
+The `pm_slug` carves out PM-specific space where a PM can hold variant knowledge and skills without
+disturbing the canonical core:
+
+- **`/skills/pm/<pm_slug>/`** — PM-specific skill variants. A PM may override or specialize a core
+  skill here (e.g. `/skills/pm/wawan/`). The core skill in `/skills/core/` remains canonical;
+  the PM variant is a deliberate, scoped divergence.
+- **PM-promoted concepts** — knowledge a PM develops that generalizes across PMs is promoted into
+  [/okf/shared/](/okf/shared/), per the OKF governance lifecycle. Promotion is deliberate; a PM's
+  private working knowledge does not auto-publish to `shared/`.
+
+## PM authority and responsibilities
+
+The PM's authority is bounded and explicit:
+
+- **Owns acceptance.** Clears (or rejects) the Acceptance Gate at the end of each run. This is a
+  strategic-fit decision, **not** a re-check of the eval rubric.
+- **Owns architectural decisions.** All locked decisions live in `DECISIONS.md`; agents never make
+  architectural calls. The PM is the author and amender of those decisions.
+- **Owns calibration.** The PM validates the evaluator against
+  [eval-calibration.md](/planning/evals/eval-calibration.md) over the first P1 run cycles, because
+  the eval gate is uncalibrated until then (evaluator leniency).
+- **Owns the cadence.** Weekly transcript review, monthly kill-condition checks, quarterly harness
+  assumption review — the anti-atrophy mechanisms that defend against the Paradox of Supervision.
+
+## Why model identity explicitly
+
+Modelling the PM as a first-class, slug-addressable identity is what lets PMOS scope work
+unambiguously (which PM, which product), keep PM-specific variants isolated from canonical core, and
+attribute the north-star metric — **human correction rate per agent run** — to a specific human's
+judgment. Identity is the anchor the control plane hangs accountability on.

package/payload/okf/core/concepts/product-slug-convention.md

@@ -0,0 +1,64 @@
+---
+type: Concept
+title: product_slug Convention
+description: The rules for product_slug — the stable lowercase identifier that scopes products across OKF namespaces, planning artifacts, and agent records.
+tags: [identity, product, namespace, convention]
+timestamp: 2026-06-28
+---
+
+# product_slug Convention
+
+**Situating context:** PMOS is built to run many products through one control plane, so it needs a
+stable way to say "this knowledge / this work belongs to *that* product." This concept fixes the
+`product_slug` convention so paths and records resolve a product unambiguously. It pairs with the
+[PM identity model](/okf/core/concepts/pm-identity.md): together `pm_slug` + `product_slug` fully
+scope any unit of work — which PM, which product.
+
+## What `product_slug` is
+
+A **`product_slug`** is a stable, lowercase, URL-safe identifier for one product. It is the
+canonical reference to that product everywhere PMOS records or routes work.
+
+For this instance: **`product_slug: pmos`** (PMOS is the first product, building itself).
+
+## Rules
+
+1. **Lowercase only.** No uppercase, no spaces.
+2. **URL- and path-safe.** Letters, digits, hyphens. No slashes, dots, or underscores that would
+   collide with path or frontmatter parsing. Prefer hyphens for multi-word slugs.
+3. **Stable.** Treat it as a primary key. Renaming a `product_slug` orphans every path and record
+   that points at it, so it changes only by deliberate PM decision with a migration.
+4. **Unique** within the PMOS instance.
+5. **Short and recognizable.** It appears in paths constantly; favour the obvious short form.
+
+## Where it appears
+
+- **OKF namespace:** `/okf/products/<product_slug>/` holds knowledge scoped to one product
+  (e.g. `/okf/products/pmos/`). Core, cross-product knowledge stays in `/okf/core/`; product-scoped
+  knowledge lives under its slug.
+- **Planning artifacts:** PRD, OKR, and eval instances under `/planning/` reference the product by
+  its slug so each dated artifact resolves to a product.
+- **Agent records:** `agent_runs` and initiative records carry the `product_slug` (P1) so the
+  north-star metric can be sliced per product.
+
+## Scoping with `pm_slug`
+
+`product_slug` answers *which product*; `pm_slug` answers *which PM*. Together they scope work
+completely:
+
+- `pm_slug: wawan` + `product_slug: pmos` → Wawan's work on PMOS.
+- This pairing is what lets PMOS attribute outcomes and isolate variant knowledge without ambiguity
+  as more PMs and products come online.
+
+## Core vs. product-scoped knowledge
+
+A recurring authoring decision: does this concept go in `/okf/core/` or
+`/okf/products/<product_slug>/`?
+
+- **Core** — true across products; part of the PMOS method itself (e.g. the OKR tree, the eval gate
+  model). Most P0 seed concepts are core.
+- **Product-scoped** — true only for one product's domain or constraints. Place under the product's
+  slug.
+
+When unsure, default to core only if the knowledge would still be correct for a second, unrelated
+product; otherwise scope it to the product.