create-pmos 0.5.0 → 0.6.1

package/README.md

@@ -1,3 +1,9 @@
+---
+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
@@ -51,6 +57,11 @@ Next steps in /home/you/my-product:
 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
@@ -75,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,
@@ -250,6 +333,50 @@ 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.1
+
+A completeness fix: two skills the kit already *pointed at* but didn't *ship*.
+
+- **`strategic-brief` and `source-to-concept` now ride in the kit.** The shipped `pmos-router` and
+  `prd` skills recommend `strategic-brief` (make the go/no-go case before a PRD — D61, optional and
+  router-recommended for new-bet feature work), and `ingest-repo` cites `source-to-concept` as its
+  extraction discipline — but neither skill was in the bundle, so those were dangling references.
+  Both are now included. They're file-mode-clean (no backend, no network).
+
+**Upgrade note:** `npx create-pmos@latest --update` brings both in and never touches your `state/`,
+`planning/`, or `okf/product/` records. Purely additive.
+
+## 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

package/bin/create-pmos.js

@@ -4,17 +4,26 @@
  *
  *   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.
@@ -93,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.5.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.1",
+  "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
@@ -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.

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@917d29e
-assembled: 2026-07-23
+kernel-source: pmos@005408d
+assembled: 2026-07-27
 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 →

package/payload/SECURITY.md

@@ -1,3 +1,9 @@
+---
+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

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

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

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

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

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

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

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

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

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

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