create-pmos 0.4.0 → 0.6.0

package/README.md

@@ -1,10 +1,17 @@
+---
+type: Reference
+title: "create-pmos"
+timestamp: 2026-07-23
+---
+
 # create-pmos
 
 **A product manager's operating system you can adopt in five minutes — no coding expertise
 required.** One command puts a disciplined, eval-driven PM workflow inside your own repo:
-initiative → PRD → eval rubric → agreed contract → build → three gates. Your AI coding agent
-(e.g. Claude Code) does the building. You do the judging. Everything stays in your folder — no
-database, no account, no network calls, no telemetry.
+initiative → PRD → eval rubric → agreed contract → build → three gates. **Any capable coding
+agent** does the building — Claude Code, Codex/ChatGPT, Cursor, Gemini, Copilot; PMOS is
+provider- and model-agnostic. You do the judging. Everything stays in your folder — no database,
+no account, no network calls, no telemetry.
 
 ## Whose task is what
 
@@ -43,13 +50,18 @@ What you'll see:
 
 Next steps in /home/you/my-product:
   1. cp pmos/templates/pmos-gate.yml .github/workflows/pmos-gate.yml   (only if on GitHub)
-  2. Add to the repo's CLAUDE.md: "This product is PMOS-managed (file mode) — read pmos/AGENTS.md before any work."
+  2. Wire PMOS into your agent's instruction file (CLAUDE.md, AGENTS.md, .cursorrules, GEMINI.md, or copilot-instructions): "This product is PMOS-managed (file mode) — read pmos/AGENTS.md before any work."
   3. Commit the pmos/ folder. Then follow pmos/AGENTS.md for every run.
 ```
 
 Do those three lines and setup is over. A fresh kit with zero history is not behind — it is
 exactly where every product starts.
 
+> **Prefer a GUI to a folder of files?** One more command gives you the **Terminal Workspace** — a
+> local app that runs your agent sessions as real terminals with the library and gates beside them.
+> See [The Terminal Workspace](#the-terminal-workspace-gui-optional) below. It's optional; the
+> file-mode workflow above needs nothing but your editor and your agent.
+
 ### Behind a corporate proxy? (403 on install)
 
 On many work laptops, npm goes through a company registry mirror — and a brand-new public package
@@ -74,6 +86,78 @@ ways through:
    Same result, byte-identical kit, no proxy involved. (Which is fitting — keeping your work
    inside your own boundary is the whole point of this kit.)
 
+## The Terminal Workspace (GUI) — optional
+
+The kit above is files-and-your-agent. If you'd rather **see** the whole loop — your agent sessions
+running as real terminals, the library and the gates in the same window — activate the **Terminal
+Workspace**: a local companion app that lives entirely on your machine (localhost only, never a
+public endpoint).
+
+### Activate it — one command
+
+```bash
+npx create-pmos@latest workspace
+```
+
+That single command does everything:
+
+1. **Installs the app + puts `pmos` on your PATH.** The workspace hosts real terminal sessions, so
+   it has one native dependency (`node-pty`) — this is the one step in the whole kit that builds
+   something. It takes ~20 seconds, once.
+2. **Launches the GUI** — it starts a small localhost server and opens your browser on the current
+   repo as a workspace.
+
+From then on, the daily driver is just one word, from any repo folder:
+
+```bash
+pmos                 # open THIS repo as a workspace (starts the server if it isn't up)
+pmos ../other-repo   # open a different repo — one server hosts many, they never disturb each other
+pmos status          # is it running? which repos, which sessions?
+pmos stop            # shut the server down (scrollback is kept; sessions re-attach next launch)
+pmos doctor          # diagnose the environment (node build tools, PTY spawn test)
+```
+
+Close the terminal and your sessions keep running — the server is persistent; `pmos stop` is the
+only thing that ends it.
+
+### If `pmos` doesn't land on your PATH
+
+Some machines lock down npm's global folder. If the activation prints a warning instead of putting
+`pmos` on your PATH, it still opens the GUI — and it tells you the one line to run for the bare
+`pmos` command next time (usually `sudo npm install -g …`, or
+[point npm's global prefix somewhere you own](https://docs.npmjs.com/resolving-eacces-permissions-errors)
+so no `sudo` is ever needed).
+
+### What to expect
+
+- **Requirements:** Node 18+. macOS, Linux, and Windows. Activation (`create-pmos workspace`) builds
+  `node-pty` once with a C toolchain — most dev machines already have one; `pmos doctor` names the
+  exact fix if not.
+- **It's local and private.** The server binds `127.0.0.1` and is never exposed to the network. Your
+  agent CLI (Claude Code, Codex, a plain shell) runs **untouched** — its own login, slash commands,
+  and keybindings all work; the workspace is the terminal, not a wrapper.
+- **The gates are the same gates.** `approve` / `return` / `accept` in the GUI write the exact
+  file-mode records (`state/acceptances.jsonl`) this kit already uses — only ever on your click.
+  Nothing is recorded automatically.
+- **Works with or without the kit.** Best in a repo you've run `create-pmos` in (it reads and writes
+  `pmos/state/`), but it opens any repo — a plain project just records into the server's own state.
+
+> **Why this is a separate opt-in.** Vendoring the file-mode kit stays dependency-free and
+> proxy-safe — no native builds, no install scripts, nothing fetched. The workspace is the one
+> place a native module is unavoidable, so it only ever installs when you explicitly ask for the
+> GUI. The app itself ships inside this package; `workspace` builds it, it doesn't download it.
+
+<details><summary>Running it from a PMOS checkout instead (no npx)</summary>
+
+If you have the PMOS source, the workspace is a normal Node app:
+
+```bash
+cd workspace
+npm install -g .     # installs the `pmos` command
+pmos                 # from any folder
+```
+</details>
+
 ## Your first conversation
 
 Open the folder with your coding agent and talk to it like a colleague — clear about the goal,
@@ -249,6 +333,67 @@ Refreshes the skills, concepts, and scripts only. Your records — `state/`, `pl
 `okf/product/` — are yours, and an update never touches them. `pmos/KIT-VERSION` always says
 exactly what you're running.
 
+## What's new in 0.6.0
+
+0.5.0 made the kit provider- and model-agnostic. 0.6.0 adds a **face** to the file-mode loop: the
+**Terminal Workspace GUI**, activated by one command.
+
+- **`npx create-pmos@latest workspace` — install and launch the GUI in one step.** The workspace is
+  a local companion app that runs your agent sessions as real terminals, with the library and the
+  gates in the same window (D62). The command installs it, puts a one-word `pmos` launcher on your
+  PATH, and opens your browser on the current repo. After that, `pmos` (plus `pmos status`,
+  `pmos stop`, `pmos doctor`) is the daily driver from any folder. The server is localhost-only and
+  persistent — close the terminal and your sessions keep running.
+
+  > See it before you wire it: `npx create-pmos@latest workspace` in any repo. The gates in the GUI
+  > write the same `state/acceptances.jsonl` records the file-mode kit already uses — only on your
+  > click, never automatically.
+
+- **The scaffolder is still dependency-free — on purpose.** Vendoring or updating the file-mode kit
+  builds nothing, fetches nothing, and stays proxy-safe exactly as before. The workspace is the one
+  place a native module (`node-pty`, for real terminals) is unavoidable, so it installs **only** when
+  you explicitly ask for the GUI. The app is bundled in this package — `workspace` builds it locally,
+  it is never downloaded.
+
+- **Graceful when the global install is locked down.** On machines where npm's global folder needs
+  elevation, activation doesn't fail — it opens the GUI from the bundled copy and prints the single
+  line to get the bare `pmos` command for next time.
+
+**Upgrade note:** `npx create-pmos@latest --update` is unchanged and never touches your `state/`,
+`planning/`, or `okf/product/` records. The GUI is purely additive and entirely optional — if you
+never run `create-pmos workspace`, nothing native is ever installed and the file-mode workflow is
+exactly what it was.
+
+## What's new in 0.5.0
+
+0.4.0 opened the front of the loop. 0.5.0 makes explicit what was always the intent: **the kit is
+provider- and model-agnostic**, and the harness kernel now says so in its own words.
+
+- **Any capable coding agent runs the loop — not just Claude Code.** The runtime amendment
+  (D09/D34, ratified 2026-07-23) generalizes the evaluator, ingest, and design skills from
+  "runs in Claude Code" to "runs in the interactive agent runtime — any capable coding agent;
+  PMOS-self happens to use Claude Code, but the runtime is not Claude-specific." Point Codex,
+  Cursor, Gemini, or Copilot at `pmos/AGENTS.md` and the same protocol holds.
+
+  > Works the same in any of them: open your product folder in the agent, then
+  > "Read pmos/AGENTS.md and follow it." The gates, records, and metrics don't care which model
+  > wrote the code.
+
+- **Per-model calibration.** When you log a run or an eval you can now name the model that did the
+  work (`model`) or the judging (`evaluator_model`), so the evaluator's calibration is read *per
+  model* instead of silently pooling providers — `scripts/metrics.py` warns when labeled evals span
+  more than one evaluator model, because a trust score one model earned isn't inherited by another.
+  The design surface is documented as pluggable too (any surface that can take a brief and export a
+  component library), not tied to one vendor.
+
+- **A stated security posture that travels with the kit** (`pmos/SECURITY.md`), a `frontier.sh`
+  metrics helper, a file-mode `ticket-template.md`, and a sharper `SKILL-FORMAT.md` — all now part
+  of the vendored kernel.
+
+**Upgrade note:** `npx create-pmos@latest --update` brings all of this in and never touches your
+`state/`, `planning/`, or `okf/product/` records. Purely additive — no change to how the gate
+behaves on your existing initiatives.
+
 ## What's new in 0.4.0
 
 0.3.0 sharpened the judging. 0.4.0 adds the **front of the loop** — deciding *what* to build and

package/bin/create-pmos.js

@@ -4,25 +4,36 @@
  *
  *   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 workspace [dir]  install + launch the Terminal Workspace GUI (D62)
  *   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/.
+ * The SCAFFOLDER is dependency-free by design: vendoring/updating the file-mode kit makes NO
+ * network calls, sends NO telemetry, and builds NOTHING native — the kit 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/.
+ *
+ * The `workspace` subcommand is the one OPT-IN exception: the Terminal Workspace is a local
+ * companion app with a native dependency (node-pty), so activating it runs `npm install`. Nothing
+ * native is fetched unless the user explicitly asks for the GUI — the proxy-safe scaffolder path
+ * is unchanged. The workspace app itself is bundled in this package, not downloaded.
  */
 'use strict';
 const fs = require('fs');
 const path = require('path');
+const { spawnSync } = require('child_process');
 
-const PAYLOAD = path.join(__dirname, '..', 'payload'); // the assembled pmos/ kit
+const PAYLOAD = path.join(__dirname, '..', 'payload');       // the assembled pmos/ kit (file-mode)
+const WORKSPACE = path.join(__dirname, '..', 'workspace');   // the bundled Terminal Workspace app (D62)
 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',
+  'SECURITY.md',
   'KIT-VERSION',
   'skills',
+  'skills-native',
   'okf/core',
   'scripts',
   'templates',
@@ -59,7 +70,8 @@ function vendor(targetRoot) {
 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."
+  3. Wire PMOS into your agent's instruction file (CLAUDE.md, AGENTS.md, .cursorrules, GEMINI.md, or
+     .github/copilot-instructions.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.`);
 }
 
@@ -90,14 +102,91 @@ function update(dirArg) {
   console.log('state/, planning/ (beyond check_rubrics.py), and okf/product/ were not touched. Review the diff as a normal PR.');
 }
 
+// ── workspace ────────────────────────────────────────────────────────────────
+// Activate the Terminal Workspace GUI (D62). This is the one command that installs — the workspace
+// hosts real agent-CLI terminals (PTYs), so it needs the native node-pty module. We do it in two
+// honest steps so the failure mode of each is legible:
+//   1. put the `pmos` command on PATH  (npm install -g the bundled app → builds node-pty once)
+//   2. launch it                       (`pmos <dir>` starts the localhost server + opens the GUI)
+// After this one-time activation, the daily driver is just `pmos` from any repo folder. If the
+// global install can't run (locked-down npm prefix), we DON'T fail — we launch straight from the
+// bundled copy (its own bin/pmos.js installs runtime deps on first run) and print the one manual
+// line to get the bare `pmos` word for next time.
+function onPath(cmd) {
+  // `command -v` (POSIX) and `where` (Windows) are shell BUILTINS — neither has a standalone binary on
+  // Linux, so the probe MUST run through a shell or it ENOENTs and always reports "not found" (which,
+  // after a successful install, prints a false PATH warning and defeats the idempotent fast path). cmd
+  // is always a literal, so the string form is injection-safe.
+  const probe = process.platform === 'win32' ? `where ${cmd}` : `command -v ${cmd}`;
+  try { return spawnSync(probe, { stdio: 'ignore', shell: true }).status === 0; }
+  catch { return false; }
+}
+
+function workspaceOrDie() {
+  if (!fs.existsSync(path.join(WORKSPACE, 'bin', 'pmos.js'))) {
+    die('this build does not bundle the Terminal Workspace — reinstall with `npx create-pmos@latest`, '
+      + 'or install it from a PMOS checkout: `cd workspace && npm install -g .`');
+  }
+}
+
+function launchWorkspace(targetDir, viaGlobal) {
+  if (viaGlobal && onPath('pmos')) {
+    // `pmos` owns the whole lifecycle: start the server detached, open the browser on this repo.
+    return spawnSync('pmos', [targetDir], { stdio: 'inherit', shell: process.platform === 'win32' }).status || 0;
+  }
+  // Fallback: run the bundled launcher directly. Its ensureInstalled() pulls runtime deps on first run.
+  console.log('Launching from the bundled copy (the `pmos` command is not on PATH).');
+  return spawnSync(process.execPath, [path.join(WORKSPACE, 'bin', 'pmos.js'), targetDir],
+    { stdio: 'inherit', env: process.env }).status || 0;
+}
+
+function workspace(targetArg) {
+  workspaceOrDie();
+  const targetDir = path.resolve(targetArg || '.');
+
+  // Already activated? Then this is just a launch — fast path, no reinstall.
+  if (onPath('pmos')) {
+    console.log('✅ workspace already activated — launching. (Type `pmos` directly next time.)');
+    process.exit(launchWorkspace(targetDir, true));
+  }
+
+  console.log('Activating the PMOS Terminal Workspace (one-time). Installing node-pty (native) + putting `pmos` on PATH…');
+  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const g = spawnSync(npmCmd, ['install', '-g', WORKSPACE, '--no-audit', '--no-fund'],
+    { stdio: 'inherit', shell: process.platform === 'win32' });
+
+  if (g.status === 0 && onPath('pmos')) {
+    console.log('\n✅ `pmos` is now on your PATH. From any repo folder, just type:  pmos');
+    console.log('   pmos status · pmos stop · pmos doctor');
+    process.exit(launchWorkspace(targetDir, true));
+  }
+
+  // Global install refused (common on system-owned npm prefixes) — don't fail, still open the GUI.
+  console.log('\n⚠  Could not put `pmos` on your PATH automatically (your npm global prefix may be locked down).');
+  console.log('   To get the bare `pmos` command for next time, run ONE of:');
+  console.log(`     npm install -g "${WORKSPACE}"                 # then: pmos`);
+  console.log(`     sudo npm install -g "${WORKSPACE}"            # if your node is system-owned`);
+  console.log(`   Docs: npm prefix without sudo → https://docs.npmjs.com/resolving-eacces-permissions-errors`);
+  console.log('   Opening the GUI now from the bundled copy…\n');
+  process.exit(launchWorkspace(targetDir, false));
+}
+
 const args = process.argv.slice(2);
+const positional = args.filter((a) => !a.startsWith('-'));
 if (args.includes('--help') || args.includes('-h')) {
-  console.log('usage: create-pmos [target-dir] | create-pmos --update [kit-or-repo-dir] | create-pmos --version');
+  console.log('usage:');
+  console.log('  create-pmos [target-dir]              vendor the file-mode kit into a repo');
+  console.log('  create-pmos --update [kit-or-repo]    refresh only the kit kernel');
+  console.log('  create-pmos workspace [repo-dir]      install + launch the Terminal Workspace GUI');
+  console.log('  create-pmos --version                 print version + bundled kernel provenance');
 } else if (args.includes('--version') || args.includes('-v')) {
   console.log(`create-pmos ${PKG.version}`);
   console.log(kitVersion());
+  console.log(`workspace bundled: ${fs.existsSync(path.join(WORKSPACE, 'bin', 'pmos.js')) ? 'yes' : 'no'}`);
+} else if (positional[0] === 'workspace') {
+  workspace(positional[1]);
 } else if (args.includes('--update')) {
-  update(args.filter((a) => !a.startsWith('-'))[0]);
+  update(positional[0]);
 } else {
-  vendor(path.resolve(args.filter((a) => !a.startsWith('-'))[0] || '.'));
+  vendor(path.resolve(positional[0] || '.'));
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-pmos",
-  "version": "0.4.0",
-  "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → lane-fit spec → contract → build → three gates, with work-type lanes for features, research, maintenance, incidents, and content) entirely inside your own repo, with all state as git-versioned files. No database, no network, no telemetry.",
+  "version": "0.6.0",
+  "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → lane-fit spec → contract → build → three gates, with work-type lanes for features, research, maintenance, incidents, and content) entirely inside your own repo, with all state as git-versioned files. `create-pmos workspace` also installs + launches the local Terminal Workspace GUI. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {
     "create-pmos": "bin/create-pmos.js"
@@ -9,6 +9,7 @@
   "files": [
     "bin/",
     "payload/",
+    "workspace/",
     "README.md",
     "LICENSE"
   ],
@@ -21,6 +22,9 @@
     "agent-harness",
     "eval-driven",
     "scaffold",
-    "create"
+    "create",
+    "workspace",
+    "terminal",
+    "gui"
   ]
 }

package/payload/AGENTS-HUMAN.md

@@ -1,3 +1,9 @@
+---
+type: Reference
+title: "AGENTS-HUMAN.md — the PMOS kit for a human builder (D58)"
+timestamp: 2026-07-18
+---
+
 # AGENTS-HUMAN.md — the PMOS kit for a human builder (D58)
 
 You're a person, not an agent — same loop, plain terms, one helper. The full protocol lives in

package/payload/AGENTS.md

@@ -1,3 +1,9 @@
+---
+type: Reference
+title: "AGENTS.md — PMOS Portable Kit (file mode)"
+timestamp: 2026-07-22
+---
+
 # AGENTS.md — PMOS Portable Kit (file mode)
 
 > This file must be read at optimal altitude — concrete heuristics that guide behavior, not brittle
@@ -24,8 +30,8 @@ yourself wanting an MCP tool, use the state adapter below instead.
 | `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}`) |
+| `log_agent_run` | append one JSON line to `pmos/state/runs.jsonl` (`{run_id, initiative_id, pre_run_contract, self_eval, human_corrections, date, model}`) — record `model` = the model that produced the run so metrics stay honest across model switches |
+| `save_eval` | append one JSON line to `pmos/state/evals.jsonl` (`{run_id, initiative_id, rubric_path, score, verdict, dimensions, date, evaluator_model}`) — record `evaluator_model` = the model that rendered the verdict; κ is calibrated **per evaluator model** (a model swap does not inherit a prior κ) |
 | `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** |
 | `record_outcome_check` | append one JSON line to `pmos/state/outcome_checks.jsonl` (`{initiative_id, disposition, evidence, date}`) — the D57 post-acceptance outcome verdict (`validated | refuted | inconclusive`; evidence required for the first two). **PM's word only — never auto-dispose from metrics**; a re-judgment is a new line |
 | `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) |
@@ -52,6 +58,26 @@ never invent a lane; a work shape with no lane escalates to the PM.
 | `chore` | a one-paragraph `intent:` in the initiative file | repo CI + PM spot-check at merge |
 | `incident` | incident record at `prd_path`, **post-hoc within 48h** (template in `okf/core/templates/`) — the one sanctioned inversion of eval-first | retro in the record; follow-ups become their own initiatives |
 | `content` | content brief at `prd_path` (audience, message, claims + sources — `skills/copywriting.skill`, template in `okf/core/templates/`) | copy rubric recommended, not required (D58); PM judges at the gate otherwise |
+| `prototype` | quick prototype brief at `prd_path` (the judgement exercised + the specimen format — `skills/prototype.skill`, template in `okf/core/templates/`), **before** the PRD | **NO rubric, BY DESIGN** — grilled as dialogue, never scored (D60(d)); closes on a PM disposition: promote / iterate / kill |
+
+> **Known gap in this kit build:** `scripts/gate-initiative.sh` does not yet parameterise the
+> `prototype` lane — a prototype initiative falls through to the `feature` branch and is asked for a
+> `rubric_path` it must not have. Until that is fixed, set the lane's `type: prototype` in the
+> initiative file as normal and expect to carry the gate failure knowingly, or run the prototype
+> before opening the record. Tracked upstream; not a licence to invent a rubric for leg A.
+
+**Routing rule (D60, as amended 2026-07-24) — an idea the PM cannot judge from a DESCRIPTION goes to
+the `prototype` lane BEFORE anyone writes a PRD.** The entry rule is the **specimen test**: *can the
+PM judge this from a description, or do they need an instance of it in front of them?* It is **not
+gated on the work having a user interface** — *does this skill's output actually teach?* and *does
+this API feel right to call?* qualify exactly as an unseen screen does. The PM briefs; an agent
+produces **2–3 divergent specimens in whatever format fits** (lookable UI, a worked sample output,
+call/response transcripts, a schema sketch); a craft-grade grilling sharpens them as **dialogue,
+never a score**; a promote-disposition derives the feature-lane PRD + rubric from what was validated.
+The test must discriminate **both ways** — most work (a tool, a migration, a CI gate) *is*
+description-judgeable and routes straight to its PRD untaxed. Contrast `discovery`, which holds a
+**question** and delivers a **learning**; this lane holds a **candidate** and delivers a **validated
+direction**. Prototypes live in `prototype/` and never ship.
 
 `no-initiative` label = anchor-free trivia ONLY (a typo, a broken link). A chore, spike,
 incident, or piece of content is real work and takes its lane — that is what keeps the record
@@ -64,12 +90,20 @@ honest.
    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).
+   - **Existing surface → the PM needs the understanding too.** That retrieval warms *you*. When the
+     work touches something that already exists — the test is *would specifying this honestly require
+     reading code that already exists?* — run `skills/explain-surface.skill` on that region **before**
+     the brief/PRD is authored, in a fresh context and **not** by the agent that will write it.
+     Standard for existing surfaces, skipped for greenfield. Without it, the agent acquires the
+     understanding and the **PM approves a spec built on facts they never saw**.
 4. Anchor: the initiative file must exist at stage `intake`/`spec` with its **lane's** spec/eval
    artifacts authored **before** build (eval-first, D13, generalized per lane — see the lane table
    above; `feature` = PRD + rubric; the incident lane alone records post-hoc). Contract per lane:
    `feature` = the rubric's sprint-contract section with the PM's explicit `PM_approved: true`;
    `discovery` = the PM-approved spike brief (question + timebox); `chore` = the stated intent;
-   `content` = the PM-approved content brief. No work before the lane's approval. Feature-lane
+   `content` = the PM-approved content brief; `prototype` = the PM-approved quick brief (the
+   judgement exercised + the specimen format) — and **no rubric**, which is the decision, not an
+   omission. No work before the lane's approval. Feature-lane
    `test_method`s SHOULD be executable checks written before build (D58) — wire
    `templates/product-ci-starter.yml` so tier 1 is never silently empty.
 5. Branch `initiative/<id>`; execute at control altitude; one commit per artifact.
@@ -93,6 +127,22 @@ honest.
   not install the pmos gate, or mirror the initiative file locally** — a vendored sibling gate
   fails closed on a missing local record by design (S5 Review Gate finding).
 
+## Decomposing an initiative into tickets (file mode has no board)
+
+When an initiative is bigger than one run, break it into **tickets** — the plain-file equivalent of
+the hosted product's SDLC board. One file per ticket in `pmos/state/tickets/NNN-slug.md`, numbered
+in **dependency order**, from [templates/ticket-template.md](templates/ticket-template.md):
+
+- Frontmatter: `id` (the NNN), `title`, `status` (`todo | doing | done`), and `blocked_by` — an
+  explicit list of the ticket ids that must be `done` first. Blocking edges are **text**, not a
+  hidden graph.
+- **Work the frontier.** `pmos/scripts/frontier.sh` lists exactly the tickets that are not done and
+  whose every blocker is done — the workable set. Start only from there. If it reports the frontier
+  is *blocked*, there is a cycle or an undone blocker to resolve before more work is startable.
+- Each ticket names **one deliverable**, behaviorally (interfaces/types/contracts, never file paths
+  or line numbers — they stale while the ticket waits). Tickets decompose an initiative; they do not
+  replace it — the initiative record, PRD, rubric, and the three gates are unchanged.
+
 ## New agent paths — the lethal-trifecta audit
 
 Before creating any new agent path or widening a tool grant, verify it does **not** hold all three
@@ -117,6 +167,15 @@ deployment until this repo has accumulated its own PM-vs-evaluator record (appen
 `pmos/scripts/metrics.py` computes the north star (human corrections per accepted run), pass rates,
 and the Goodhart tripwire from `pmos/state/`.
 
+**Model-awareness (any provider).** PMOS is provider/model-agnostic — any capable coding agent can
+run this loop — but calibration is a property of the **evaluator model**, not of "the Review Gate"
+abstractly. Record the model on every run/eval (the `model` / `evaluator_model` fields above); a
+model swap **forks** the calibration record — you do not inherit a κ another model earned, and
+`metrics.py` warns when labeled evals pool more than one evaluator model. The high-judgment roles
+(the adversarial evaluator, `explain-run`) assume a **frontier-tier reasoner**: a weaker model
+degrades *silently* to leniency and grep-clean while its output still looks well-formed — the
+per-model κ is what makes that degradation visible.
+
 ## PM protocol (weekly)
 
 Scan `discoveries.md`; a friction theme seen twice with no resolving decision must be promoted to a

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@1687768
-assembled: 2026-07-21
+kernel-source: pmos@58bb72a
+assembled: 2026-07-26
 mode: vendor

package/payload/README.md

@@ -1,3 +1,9 @@
+---
+type: Reference
+title: "PMOS Portable Kit (file mode)"
+timestamp: 2026-07-23
+---
+
 # PMOS Portable Kit (file mode)
 
 Run the PMOS workflow — initiative → PRD → eval rubric → pre-run contract → build →
@@ -13,16 +19,24 @@ personally-owned PMOS backend).
 - `AGENTS-HUMAN.md` — the same loop for a **human** builder (D58): plain terms + the
   `scripts/pmos-log.sh` helper that appends validated state records in one command. Mixed
   human+agent teams share the same state.
+- `SECURITY.md` — the kit's **security posture**: skills are executable instructions, what the kit
+  does structurally to be safe to install, and what stays your responsibility. Read it before you
+  install skills into your agent.
 - `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.
+- `skills-native/` — the same skills in **Agent-Skills standard** form (`<name>/SKILL.md`
+  directories), generated from `skills/` so a Claude Code / Codex / skills.sh harness can load them.
+  The flat `skills/` files stay the source of truth; this is the portable mirror.
 - `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`.
+  `evals.jsonl`, `acceptances.jsonl`, `discoveries.md`. `tickets/NNN-slug.md` decompose an
+  initiative into ordered, dependency-numbered work (file-mode's board — see AGENTS.md).
 - `scripts/` — `gate-initiative.sh` (the fail-closed CI gate), `metrics.py` (north star +
-  calibration + Goodhart tripwire), `kit-update.sh` (kernel refresh).
+  calibration + Goodhart tripwire), `kit-update.sh` (kernel refresh), `frontier.sh` (lists the
+  workable tickets — those not done whose blockers are all done).
 - `templates/pmos-gate.yml` — CI drop-in; copy to `.github/workflows/`.
 - `KIT-VERSION` — which PMOS kernel this was assembled from.
 

package/payload/SECURITY.md

@@ -0,0 +1,59 @@
+---
+type: Reference
+title: "PMOS kit — security posture"
+timestamp: 2026-07-23
+---
+
+# PMOS kit — security posture
+
+A skill is not a document. It is **instructions that run inside your agent**, with your agent's
+tools and your agent's access. Anything the kit ships into your repo can shape what your agent does.
+This file states, concretely, what the PMOS kit does to be safe to install — and where the
+responsibility stays yours.
+
+## Why "we scanned it" is not a posture
+
+The largest skills registry (skills.sh) shipped a malicious-skill scanner. Trail of Bits bypassed it
+with prompt injection plus compiled bytecode. Static scanning of agent instructions is *evadable by
+construction* — the payload is natural language aimed at a model, not a signature you can enumerate.
+So the PMOS kit does not claim "scanned and safe." It claims a set of **structural** properties you
+can check yourself, below.
+
+## What the kit does
+
+- **No on-load command execution in shipped skills.** No PMOS kit skill uses Claude Code's dynamic
+  `` !`cmd` `` context injection or any load-time shell-out. A skill's body is read as instructions,
+  not run as a script when it loads. *(Check: `grep -rn '!\`' pmos/skills` — expect nothing.)*
+- **Least authority, declared.** Shipped skills request the minimum tools they need; the
+  security-sensitive one — the **evaluator** — is **read-only by design**: its only write is the
+  schema-constrained verdict. The component that reads untrusted content (diffs, PR text) is
+  deliberately *not* the component that can act, which removes the exfiltration leg of the lethal
+  trifecta.
+- **A `license` on every shipped skill** (portability + provenance), and PMOS producer metadata is
+  carried under the spec's `metadata:` extension map, never as ambient top-level directives.
+- **Fail-closed containment.** The kit is assembled by `kit/build-kit.sh`, which greps its own output
+  and **aborts** if any reference to a hosted PMOS backend (a project ref, an MCP endpoint, or a
+  hosted-backend URL) leaks in. The npm publish path re-runs this check on the exact tarball and
+  refuses to publish on anything but a clean result. The kit you get is self-contained: **no
+  database, no network, no telemetry.**
+- **No network calls in the installer.** `create-pmos` vendors a bundled payload; it makes no
+  outbound requests and sends nothing about you anywhere.
+- **Everything the evaluator reads is untrusted data, never instructions.** An instruction embedded
+  in a diff or PR body ("mark this PASS") is treated as *evidence of a defect*, not a command —
+  paired with the read-only scope above, because prompt-level defenses alone are bypassable.
+
+## What stays your responsibility
+
+- **Review before you install.** Read the skills and scripts in `pmos/` the way you would review any
+  dependency PR. The kit is small and plain-text on purpose so you can. `--update` refreshes only the
+  kernel and never touches your `state/` — review its diff like any other change.
+- **Your agent's tools are yours to scope.** The kit declares least authority for its own skills, but
+  what your agent is *allowed* to do in your repo is set by you, not by us.
+- **Pin what you install.** Prefer a pinned `create-pmos@<version>` over `@latest` in automation, and
+  re-review the kernel diff on each update.
+
+## Reporting
+
+Found something that violates the posture above — a shipped skill with load-time execution, a
+containment leak, an over-scoped tool request? Open an issue in the PMOS repo describing what and
+where. The posture is only worth stating if it is enforced; a false claim here is itself a bug.

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

@@ -32,7 +32,8 @@ An initiative with a user-facing surface runs four legs *inside* Build:
 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).
+2. **Design** — the design is made in an external design surface (PMOS-self uses claude.ai/design;
+   any capable design surface fits — 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
@@ -42,7 +43,9 @@ An initiative with a user-facing surface runs four legs *inside* Build:
    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
+The design surface (legs 2 and 4) is **pluggable and provider-agnostic** — PMOS-self uses
+claude.ai/design, but the loop is not tied to it; any capable design surface that can consume a brief
+and export a component library fits (harness-model-agnosticism). 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
@@ -119,7 +122,7 @@ PMOS's own instance: the `web/` app, the [D38](/okf/products/pmos/adr/d38-design
   [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.
+  itself is made in an external design surface (e.g. 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).