---
type: Reference
title: "create-pmos"
timestamp: 2026-07-27
---

# 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. **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

This kit is built on a simple separation of tasks:

- **Your task** is direction and judgment: choose the goals, say what "good" means *before* the work starts, and accept or return what comes back. That's it — and no one else can do it.
- **The agent's task** is the building: code, documents, analysis, following the written protocol.
- **The kit's task** is keeping both of you honest: gates that can't be sweet-talked, records that don't rely on memory, and metrics that show the red first.

You never need to write code. You need the courage to say what you want, and the final word on whether you got it — which you already have.

## Getting started (5 minutes)

**Have an existing project?**

```bash
cd my-product
npx create-pmos@latest
```

**Starting from nothing but an idea?**

```bash
mkdir my-product && cd my-product
git init          # git is required (its branches/merges ARE the workflow); GitHub is optional
npx create-pmos@latest
```

What you'll see:

```
✅ PMOS kit vendored at /home/you/my-product/pmos (kernel-source: pmos@1740a5e)

Next steps in /home/you/my-product:
  1. cp pmos/templates/pmos-gate.yml .github/workflows/pmos-gate.yml   (only if on GitHub)
  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 gets **403 Forbidden** until it's been vetted (a sandboxed AI session's network proxy can do the same). That's your environment being careful, not something broken — and there are three clean ways through:

1. **Try a plain terminal first** — if the 403 came from inside an AI-session sandbox, the normal terminal may just work.
2. **Ask IT to allowlist `create-pmos`** — a routine request, and an easy one: public npm, MIT, zero dependencies, no install scripts, no network code.
3. **The registry-free install** — the package is just a file, so skip the registry entirely. From any allowed network, download `https://registry.npmjs.org/create-pmos/-/create-pmos-<version>.tgz`, move it to the work machine, then:

   ```bash
   tar xzf create-pmos-*.tgz
   node package/bin/create-pmos.js my-product
   ```

   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, open about what you don't know. Copy-paste starters:

**You have an existing product** (let the agent learn it first):

> Read pmos/AGENTS.md. Then follow pmos/skills/ingest-repo.skill: scan this repository read-only and draft what you learn under pmos/okf/product/ for my review. Don't change any product code.

**You have only an idea:**

> Read pmos/AGENTS.md. This is a new product: [two sentences on what it is and who it serves]. Help me seed pmos/planning/okrs/ with one objective and 2–3 key results, then propose one small first initiative — optimized for a fast first win, not for completeness.

**You know exactly what you want built:**

> Read pmos/AGENTS.md. I want: [describe the outcome]. Create the initiative file, then draft the PRD and the eval rubric for my approval before you build anything.

## The rhythm (every piece of work)

1. **Name the work.** An initiative file is created in `pmos/state/initiatives/` — anchored to one of your goals (or, for honest maintenance with no goal, a declared health budget), so nothing exists "just because."
2. **Define "good" first.** The agent drafts the spec artifact that fits the work's lane — a PRD + scoring rubric for a feature (the default), a spike brief for research (`discovery`), a stated intent for maintenance (`chore`), a content brief for copy (`content`). For a feature you approve the contract (`PM_approved: true`) before any building — and spike/content briefs get your sign-off before work starts too; a chore needs only its stated intent, and an `incident` is the one sanctioned inversion — fix first, record within 48 hours. Deciding the standard in advance is your task — it is also what makes the agent's verdicts mean something later.
3. **The agent builds** on its own branch and opens the work for review. A gate checks that every change is anchored. If someone (including the agent) skips the protocol, you'll see:

   ```
   ❌ initiative gate FAILED — Not anchored. Name the branch 'initiative/<id>' or add
      'Initiative: <id>' to the PR body ... See pmos/AGENTS.md.
   ```

   The gate isn't scolding anyone — it's protecting your standard when you're not looking. (No GitHub? Run it yourself before merging: `HEAD_REF=$(git branch --show-current) bash pmos/scripts/gate-initiative.sh`)

4. **An evaluator scores the work** against your rubric — adversarial by design, and advisory:

   > Read pmos/AGENTS.md, then follow pmos/skills/evaluator.skill: score the work on branch initiative/[id] against its rubric. Be skeptical — try to refute it. Append your verdict to pmos/state/evals.jsonl.

   Each dimension of that verdict has to cite a verbatim quote or a file+line from the work itself. A dimension the evaluator can't evidence is marked `unverified` and scored low — it never gets a high score on trust.

5. **You understand it before you judge it.** The same evaluator writes you a plain-language explainer of what the run actually did — including what it got wrong — ending in a short quiz you can self-check against. Read that instead of the raw transcript:

   > Follow pmos/skills/explain-run.skill: write the explainer + quiz for run [id] to pmos/planning/evals/explainers/.

   Worth the two minutes on anything that touches a gate. Accepting work you couldn't explain to someone else is the one watermelon no gate can catch for you.

6. **You accept — or return it.** Your merge is the final gate. Returning imperfect work is not conflict; it's the job. Record your call:

   > I accept this run. Append the acceptance to pmos/state/acceptances.jsonl with pm_label "pass" and corrections: [how many things you had to fix].

   Or record it yourself, no agent needed — the helper validates and appends in one command (`pmos/AGENTS-HUMAN.md` is the whole protocol on one page for humans):

   ```bash
   pmos/scripts/pmos-log.sh accept <run_id> <initiative_id> pass "one wording fix"
   ```

## Your weekly ten minutes

```bash
python3 pmos/scripts/metrics.py
```

What you'll see:

```
PMOS kit metrics — 4 run(s), 4 eval(s), 3 acceptance record(s)

B1 north star: 0.33 human corrections per accepted run (over 3 accepted run(s); lower is better)
B2 throughput: 3 accepted run(s)
   eval pass rate: 75% (3/4)
B4 calibration (n=3): raw agreement 100%, TPR 100%, TNR n/a — no PM fails seen (leniency blind spot), ...
```

Reds print first, on purpose — facing facts without flinching is how the numbers stay honest. On day one it says `UNMEASURABLE — no accepted runs yet`. That's not failure; that's a truthful starting line. And if the evaluator starts passing everything while you keep fixing things, a tripwire fires and tells you the judge has gone soft. A weekly prompt, if you'd rather talk than read:

> Read pmos/state/discoveries.md and run pmos/scripts/metrics.py. Tell me: what's red, what friction appeared more than once, and what one improvement you'd propose. Don't change anything yet.

## How it guardrails the SDLC

Each stage of the loop has a mechanism behind it — not a promise, a mechanism:

| Without the kit | With the kit |
|---|---|
| Work starts because someone felt like it | **Nothing exists without an initiative** anchored to a goal — or a declared health budget for honest maintenance — the gate rejects unanchored work, automatically on GitHub, by one command locally |
| "Good" gets defined after seeing the output (so everything looks fine) | **The lane's spec artifact is written first** — a feature is blocked until you've flipped `PM_approved: true`; every lane's requirement is gate-enforced (the one sanctioned inversion: an incident is fixed first, recorded within 48h) |
| The builder grades their own homework | **A separate adversarial evaluator scores against your rubric** — and even its verdict is advisory; the merge is yours alone |
| History gets quietly rewritten | **State files are append-only** — corrections are added, never erased; git keeps the audit trail |
| Metrics flatter you | **Reds print first**, and a tripwire fires if the evaluator passes everything while you keep fixing things — a green that hides red gets caught |
| Tool updates overwrite your data | **Kernel updates never touch your records** — `state/`, `planning/`, `okf/product/` are structurally off-limits to `--update` |

Notice none of these guardrails restrict *you* — they restrict the process, so your judgment is exercised at the two moments it matters: defining "good" and accepting the result.

## Staying on the path (drift protection)

Drift never announces itself — it's always "just this once, it's small." The kit assumes that and defends structurally rather than relying on discipline:

- **The protocol is re-taught, not remembered.** The `CLAUDE.md` line makes every fresh agent session read `pmos/AGENTS.md` before working — so a new session, a new model, or a new teammate starts on-protocol by default instead of drifting from a stale memory.
- **The gate makes skipping visible.** On GitHub it's a failing check nobody can miss; locally it's the one command before a merge. The `no-initiative` escape hatch is for anchor-free trivia only (a typo, a broken link) — real maintenance takes the `chore` lane with a stated intent, and if you find yourself reaching for the hatch weekly, that's a signal, not a shortcut.
- **The weekly ten minutes is the ritual.** Put `metrics.py` + the discoveries scan on your calendar. A friction that shows up twice with no decision gets promoted to a rule — that's how the process improves instead of eroding.
- **Ask the agent to audit itself.** Any time you feel drift:

  > List every merge in the last two weeks. For each: which initiative anchors it, did the rubric exist before the build, and is there an acceptance record? Report gaps without fixing them.

- **A lapse is data, not a verdict.** If you skipped the ritual for a month, the files show exactly where the record stops — restart from there. The kit never shames a gap; it just makes the gap visible enough that you can choose to close it.

## See your workflow — build your own dashboard

The entire state is plain, open files (`state/*.jsonl`, `state/initiatives/*.md`) — which means **any AI platform can turn it into a dashboard on demand.** No product to buy, no service to connect. In Claude (or Claude Code) in your product folder, paste:

> Read pmos/state/initiatives/*.md, pmos/state/runs.jsonl, evals.jsonl, acceptances.jsonl, and pmos/state/discoveries.md. Generate a single, self-contained HTML file at pmos/dashboard.html — no external scripts or network calls — showing: (1) a board with initiatives as cards in columns by stage (intake / spec / build / eval / accepted); (2) the north star (corrections per accepted run) and eval pass rate as stat tiles; (3) a recent-runs timeline with verdicts; (4) open frictions. Reds and gaps first, then greens.

Open `pmos/dashboard.html` in a browser. Regenerate it whenever you want a fresh view (or ask for it weekly as part of the ritual) — it's disposable by design. On other platforms the same works: upload or paste the state files to ChatGPT/Gemini and ask for the same artifact. Two rules keep this safe: the dashboard is a **read-only view, never the system of record** (the files stay the truth), and if your product is confidential, generate it with a tool that runs where the files live rather than uploading them elsewhere.

## Keeping the kit fresh

```bash
npx create-pmos@latest --update
```

Refreshes the skills, concepts, and scripts only. Your records — `state/`, `planning/`, `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.34.0

**A feature this README advertised for fifteen releases and never shipped.** Run `npx create-pmos@latest workspace`; the version bump means an existing install auto-upgrades.

- **The session chooser now shows the agent's last words.** It has been listed under "What's new in 0.19.0" since that release and never rendered once. The chooser read `doing` off each session row; the rows carry `lastWords`, and the server mapped between the two only on the path the *pane* uses, not the path the *chooser* uses. So the line was always blank. If you are on 0.19.0 through 0.33.0, that one line was missing from the chooser and nothing else on that list was affected.
- **How it was found, and why that matters more than the fix.** An independent evaluation of the original run — commissioned because that run had been merged and published without ever passing a Review Gate — drove a real browser against the shipped code and measured the field. The test that was supposed to cover this passed the whole time: it handed the function a hand-written row with a literal `doing` key that no real row has, so it tested a passthrough rather than the feature. The new test uses the wire shape and asserts the key is absent, so a rename on the server cannot quietly re-break it while the suite stays green.
- **Known broken, and not fixed here: `end it` in the chooser.** In a freshly opened window with no terminal tab yet, the chooser is populated over HTTP while the terminal socket is still closed, so clicking `end it` **silently does nothing** — the button disarms as though it worked and the session keeps running. It has no test coverage anywhere. It is named here rather than left for you to discover. `open it` and `＋ start another session here anyway` are unaffected.

## What's new in 0.33.0

**Three shipped documents stop telling you to do things that were never possible in your repo.** Run `npx create-pmos@latest --update`. No behaviour changes — this is a correctness release for the instructions the kit hands your agent.

- **`SKILL-FORMAT.md` no longer sends you after a seed you never had.** When you edited a `.skill`, it told you to "regenerate the seed in the same PR" and to grep an RLS test suite for pinned metadata. Those instructions described a hosted mirror table that only ever existed in PMOS's own backend — never in a vendored kit. That backend has now been removed entirely, and the section is rewritten to say what is actually true for you: **the frontmatter on disk is the only copy**, which is why the whole class of mirror-drift bug it warned about cannot reach you. The trade is stated rather than glossed: nothing validates your skill metadata, so a wrong registry key is simply wrong.
- **`ingest-repo` and `harness-refine` stop linking at reference docs your kit does not contain.** Both pointed at PMOS's hosted data-model and monitoring-view docs. `ingest-repo` now describes its write path as what it is in file mode — drafts into your own repo, approved in PR review — and `harness-refine` reads its evidence from `discoveries.md` and your run log instead of from SQL views.

**Why now.** PMOS removed its own hosted backend in this release's parent change, and these three files were the places where instructions written for that backend had leaked into what your kit ships. None of it was ever reachable from a kit install, so nothing was broken — it was wrong documentation, and it is now right.

**Unchanged:** the payload's skill set, the state layout, every gate, and the zero-network guarantee. Your records are untouched, as always.

## What's new in 0.32.0

**The PM's own accept button now writes through the guarded writer, instead of appending to the acceptance log directly.** Run `npx create-pmos@latest workspace`; the version bump means an existing install auto-upgrades.

- **`POST /api/gate` records your acceptance through the sink guard.** It resolves the path before allowing it, opens with `O_NOFOLLOW`, refuses a hard-linked target, writes to the descriptor it vetted rather than reopening the path afterwards, and rolls back a partial write instead of leaving half a record. It used to be a bare append — the one write path in the app that had never been hardened, while the module written for exactly this job had no caller at all.
- **A failed write is an HTTP 500, not a green tick.** Under D64 the file-mode acceptance log is the system of record; a swallowed append with `{ok:true}` would light the gate green over a record that never landed.
- **`drive-guard`'s refusal messages are read from a classification file rather than restated inside it.** If that file is absent — which it is in a plain kit install — the write is still refused; only the wording falls back to the generic message. Nothing about permission depends on a file that might not be there.

**Not in this release, said plainly.** The bigger piece of this wave — a declared registry of which records belong to the PM versus an agent, and `check-separation.js`, which names by `file:line` any module that writes one of the PM's records directly — is **PMOS-self only** for now and is not in your payload. Its paths are written for this repository's layout, and shipping them unchanged would give you a checker that reports confidently about directories you do not have. Porting it to the kit layout is its own piece of work, not a line in a release note.

## What's new in 0.31.1

**Your specs stop arriving in Jira as ragged half-lines. One command repairs the ones already written, and the workspace does it in one click.** Run `npx create-pmos@latest --update` for the command, or `npx create-pmos@latest workspace` for the button.

- **Why a wrapped document breaks when you publish it.** A newline inside a paragraph is invisible in markdown — CommonMark joins the lines, GitHub joins them, the workspace joins them — and it is a **line break** in Jira wiki markup, in a Google Doc, and in the markdown→ADF converters an agent uses to publish. If your specs are hard-wrapped at 80 or 100 columns, that is what your tracker receives. Nothing on the far side can undo it, because an accidental wrap and a deliberate break are the same byte in the source.
- **`node pmos/scripts/md-newlines.js --fix <path>`** joins paragraphs, list items and quoted paragraphs back into one line each, and gives a list, table, fence or heading under prose the blank line it needs. It refuses frontmatter, fenced and indented code, table rows, headings, deliberate two-space hard breaks and setext underlines — and it is idempotent, so running it twice changes nothing the second time. Check first with no flag, or read the change with `--diff`.
- **The workspace has a `normalize` button** in the document tab. It fills the buffer, not the file: the pane goes dirty, `diff` shows you exactly which lines were joined, and `save` is the same write path as always. A document that is already clean says so instead of going dirty for nothing.
- **The rule is now in `pmos/AGENTS.md`**, so agents authoring in your repo write one paragraph per line from the start.
- **Not in this release, said plainly:** nothing repairs your existing files behind your back. The command only touches paths you name, and there is no repo-wide gate — a check that failed on a corpus written before the rule existed would be a check you would have to turn off.

## What's new in 0.31.0

**Recording an acceptance can now carry the one field the calibration metric was missing — and the Review Gate's own writers stopped writing where they were told not to.** Run `npx create-pmos@latest workspace`; the version bump means an existing install auto-upgrades.

- **The Acceptance gate carries `pm_label`.** Accepting work answers "is this going in?" (D12). Whether the *evaluator* was right about it (D40) is a different question, and there was nowhere to put the answer — so every acceptance recorded through the workspace was unlabeled, and Cohen's κ had nothing to compute against. `POST /api/gate` now accepts `pm_label: pass | fail` when you state it, refuses anything else rather than silently dropping it, and still never *derives* one from the fact that you accepted. A label nobody typed is not a label.
- **`accepted: true` with `pm_label: fail` is deliberately legal.** You can accept work whose gate correctly failed — that is not a contradiction, and forbidding it would erase a whole cell of the matrix the metric needs.
- **The response tells you whether the label landed**, so a surface can show the gap instead of you having to know it exists.

## What's new in 0.30.1

**Open a markdown file in the workspace and you get the document, not its source. And scrolling down stays scrolled down.** Run `npx create-pmos@latest workspace`; the version bump means an existing install auto-upgrades.

- **The document pane renders markdown properly.** Bold was asterisks, inline code was backticks, a table was one paragraph per row with the pipes still in it, and a numbered procedure was a single run-on paragraph. An indented sub-bullet was worse than unstyled — it escaped the list it belonged inside and reappeared underneath it. `view` now renders headings 1–6, soft-wrapped paragraphs, ordered / nested / task lists, GFM tables with per-column alignment, fenced code, blockquotes and rules, plus bold, italic, inline code, strikethrough, links and images. Rubrics and skills — the documents this workflow is written in — are readable in the pane for the first time.
- **A `.md` link opens that document.** Click a link to another file in your repo and it opens as a tab, resolved against the document you are reading (or the repo root for a `/planning/…` path). A link to something the pane cannot open stays as plain text rather than becoming a dead link.
- **Nothing is fetched because you opened a file.** A repo-relative image is streamed by your own local workspace; a remote or `data:` image stays as its alt text and is never requested. The renderer builds DOM nodes and never assigns HTML, so a `<script>` in a markdown file is characters on the screen, not a script.
- **Scrolling a document survives a repaint.** The pane rebuilt its scrolling element on every redraw, so anything that changed state anywhere — including the four-second session poll, which fires whenever an agent beside you is working — took a half-read document back to line 1. The scroll element is now kept, per tab and per mode, the same way the edit box keeps your caret. Holds for `view`, `raw` and `diff`.
- **Not in this release, said plainly:** this is a workspace-app fix. The file-mode kit — skills, scripts, state layout — is unchanged, so `--update` has nothing new to give you. Syntax highlighting inside code fences, footnotes and rendered inline HTML are deliberately not included.

## What's new in 0.30.0

**Your user stories are on the board, and a story can name the Jira issue, Confluence page or Google Doc it corresponds to — in the file itself. The scratchpad drags up and down.** Run `npx create-pmos@latest workspace`; the version bump means an existing install auto-upgrades.

- **User stories show up on an initiative's artifacts list, in the right place.** The index has recognised `*-user-stories.md` for a while and nothing downstream used it: stories sorted *below* the PRD and the rubric they decompose, and the role label was twelve characters in a box built for eight, so it ran under the file path beside it. Stories now sort directly after the PRD, and the chip fits. A file in a `planning/stories/` folder counts as a story too, with no suffix needed in its name.
- **A story can carry its own destination.** Put `jira: ABC-123`, `confluence: SPACE / page` or `google_doc: <url>` in a story's frontmatter and the workspace draws the ⇄ pill on its row — no clicking, no re-typing on a second machine, and the tie is in git where an agent reading the file can see it. It works for any planning document, not only stories.
- **It says what it knows, which is nothing.** That pill reads *declared in the file · nothing has been checked*. PMOS holds no credential, makes no request, and cannot mark a reference resolved — only a session carrying your own MCP can do that. A link you record in the panel still wins over the one in the file, and `unlink` now survives a reload instead of the file quietly putting the pill back.
- **The scratchpad resizes.** Drag the handle along its top edge — up for taller, down for shorter. It cannot be dragged shut, it cannot take more than 70% of the panel (the pane above is often a live terminal), the size sticks across reloads, and `↑`/`↓` work when the handle is focused with `Home` to reset. Resizing never touches what you have staged in the pad.
- **Not in this release, said plainly:** the `Story` frontmatter type, the gate rule that enforces it and the `--fix` repair are PMOS-self only and are **not** in this payload. The registry they enforce is PMOS's own vocabulary, and running it inside your repository would fail files written to your conventions. The workspace half above works whatever `type:` your story files declare. Nothing here reads status back from a tracker — there is no "3 of 7 done", and the surface does not imply there is.

## What's new in 0.29.1

**0.29.0 could not reach an existing install. This is that release, delivered.** Run `npx create-pmos@latest workspace`.

- **If you are on 0.28.0, 0.29.0 never upgraded you.** The launcher decides whether to reinstall by comparing the bundled workspace-app version against the installed one, and 0.29.0 shipped with the app version left at `0.28.0` — so the comparison came out equal and the upgrade was silently skipped. Everything listed below was in the 0.29.0 tarball and unreachable from an existing install. 0.29.1 bumps both versions together, which is what actually delivers it.
- **The check that catches this already existed and did not run.** An assertion pins the two versions in lockstep; CI only ran it when `workspace/**` changed, and a release PR touches `npm-pkg/package.json`. The path filter now includes it, so the guard runs on the diff that breaks it. This is the second time a version bump has shipped without reaching adopters (0.9.1 was the first), and the first time the repo could have known.

**What 0.29.0 carried, now actually delivered:**

- **A skipped Review Gate no longer shows as a green tick.** `workflow-state.js` rendered a `SKIPPED` verdict — a row that says *judging did not happen* — with the same ✓ it uses for a real pass, and a `FAIL` likewise. A skip is now `pending` and a fail is `blocked`. If your board looked greener than your ledger, this is why.
- **A chore that carries a rubric now shows its Review Gate.** The rung decided from the initiative's **lane**, so any lane that *may* skip a rubric could never surface a verdict it actually had — the ladder printed *"chore lane carries no rubric"* while a verdict sat unread. It reads the rubric now, in every lane. This is how a real initiative reached `accept` with its gate never run.
- **`evaluator.skill`'s final step is runnable.** It told you to persist the verdict through `save_eval` — a hosted-backend tool that **does not exist in file mode**, which is the mode the kit runs in. The last instruction of the Review Gate could not be followed. It now names the writer for your context: `pmos/scripts/pmos-log.sh eval …`.
- **`pmos-log.sh` can record a skipped gate.** Its verdict enum was `PASS|PASS-WITH-FINDINGS|FAIL`, while `AGENTS.md` tells you *"a gate that was skipped is recorded as skipped — never leave a missing eval to be read as a pass."* Following that instruction hit an error, and the only compliant option was to edit the ledger by hand. Now: `pmos-log.sh eval <run> <initiative> SKIPPED "<reason>"`, which requires the reason and records `score: null`.
- **The kit build now refuses to ship a skill that names a tool you do not have.** That class had already shipped twice in the same sentence of the same skill. The check runs at build time and fails the build; its one bound (per-reference, not per-line) is documented in `build-kit.sh`.

*Not in this release, stated so you do not go looking:* the same upstream round hardened two modules that the kit does not run — `drive-guard.js` ships inside the workspace bundle but nothing requires it, and `record-eval.js` is not in the payload at all. Those fixes are real, and they are not something your kit was relying on.

## What's new in 0.28.0

**`search everything…` now searches every file in the folder, and any file it finds opens in a tab.** Run `npx create-pmos@latest workspace`; the version bump means an existing install auto-upgrades.

- **The box searched three lists, and the folder was not one of them.** It matched initiative slugs, paths *declared on* an initiative record, and session names — so a file PMOS had never been told about could not be found by typing its exact name. Worse, the miss read *"nothing matches — a successful read of nothing"*, which is the phrase for *we looked and there was nothing there*, printed after a search that never opened the folder.
- **Type any part of a name or a path.** Every file under the workspace root now matches, at any depth, whether or not any record mentions it — `README.md`, a script, a CSV you dropped in yesterday. `node_modules/`, `dist/`, `.git/` and the other junk directories are skipped, exactly as the folder lens already skips them, so search and the file tree agree about what is in there.
- **Type a phrase that is *inside* a file.** Text files are searched by content too, and the result names the file **and the line**, so you can see the match before you open anything.
- **Click a result and it opens in a document tab** — the same reader you already use, with `view` · `raw` · `edit` · `diff`. A file the reader cannot show (an image, a binary) is still listed, greyed, and says so, instead of opening a tab onto a failure.
- **It works in every mode.** The search box was rendered in all seven and did something in exactly one — including doing nothing in the library lens, the one screen that lists files.
- **It tells you what it did not look at.** The walk is bounded so a huge folder can never hang the box, and any bound that actually bit is stated in the heading. `11 of 1424 searched` is a different sentence from `BOUNDED — files beyond the walk limit were not looked at`, and you get whichever one is true. Nothing leaves your machine, as ever.

## What's new in 0.26.0

**Your sessions now know which initiative they belong to — whatever branch you are on — and each initiative shows the agents running on it.** Run `npx create-pmos@latest workspace`; the version bump means an existing install auto-upgrades.

- **`NOW · working on` stopped missing sessions.** It could only recognise a session by the *branch* its folder was on — `initiative/<id>` — which is true of almost no real checkout. Work on `main`, or on a branch your agent harness named, and the board could not see the agent you had running. A session now **records** which initiative it is for when you start it from one, so it is attributed whatever branch you are on, and that survives restarting the workspace.
- **Nothing is guessed, and nothing is hidden.** Where no initiative was recorded, the `initiative/<id>` branch still answers — and the row tells you when the attribution is only a branch reading rather than something PMOS was told. A session it genuinely cannot place is listed under **not on an initiative** instead of vanishing: an agent that is running should never be invisible on the screen whose job is to tell you what is running.
- **Bind a session that is already running.** `＋ bind` records what a session is for — including every session that was running before this shipped, and any you started outside PMOS. It is stored as **your declaration**, kept distinct from what PMOS was told first-hand, and re-binding tells you what it replaced. Binding never touches the process: same session, same folder, still running.
- **The initiative panel lists its live sessions.** Select an initiative and you see the agents on it, each with the same word the sidebar uses — `needs you` · `working` · `quiet 12m` · `maybe blocked` — and its profile.
- **Click one to get to it.** If its tab is already open, you go to that tab. If not, a tab opens **attached** to the running session, scrollback and all. It never starts a second agent — the row says which of the two will happen before you click.

## What's new in 0.24.0

**The initiative board says which work is yours, and which of it has an agent running.** Run `npx create-pmos@latest workspace`; the version bump means an existing install auto-upgrades.

- **A `NOW · working on` group is pinned at the top of the board.** With a few dozen initiatives filed by objective, the list is in the right *filing* order and the wrong *attention* order — the one you have an agent running on sits wherever its KR happens to fall. This group collects what you are actually on, ordered so whatever is **waiting on you** is the first row on the screen.
- **Three signals, ranked and told apart.** An initiative is in the group because a session is live on its `initiative/<id>` branch, or a working tree is checked out on that branch with nothing running in it, or you have a tab open on it in this window. They are never merged into one vague "active" badge — each row's tooltip says which one put it there, and the two weaker ones say plainly that nothing is running.
- **A live session shows on its own row.** The `#` beside an initiative becomes that session's own glyph — `◆ needs you`, `● working`, `◇ maybe blocked`, `◼ quiet` — in the same vocabulary the session sidebar uses. Hovering names **every** session on that initiative with its state, rather than counting them: the status bar already says how many and never which. Several sessions fold to the one that most wants you, and `maybe blocked` outranks `working`.
- **The glyphs differ in shape, not just colour**, so the board still reads in greyscale and for a colour-blind reader.
- **Nothing is re-homed and nothing is invented.** An initiative still appears under its own objective and KR — the group is a shortcut, not a second filing system — and it disappears entirely when there is nothing to say. A session PMOS cannot place on an initiative is not placed on one.
- **Searching for a session name now finds it.** It only ever matched initiatives you had already opened in that window, and returned nothing for the rest without saying it had not looked.

## What's new in 0.21.0

**The workspace terminal's lines are no longer double-spaced.** Run `npx create-pmos@latest workspace`; the version bump means an existing install auto-upgrades.

- **A terminal row is 20px instead of 26px.** Agent output in the terminal panel was rendering with 13.5px of empty space around a 12.5px character — and because agent CLIs print blank lines between blocks, and those were 26px too, the whole transcript read as nearly double-spaced. It now matches the spacing the workspace was designed with.
- **Your agent gets more terminal.** This was never only cosmetic: the workspace divides the panel's height by the row height to decide how many lines to tell the shell it has. The same panel that reported 21 lines now reports 28, so full-screen agent interfaces have a third more room to draw into.
- *(If you are curious: the number `1.65` appeared twice in one file and meant two different things. As a CSS rule it multiplies the font size — 12.5 × 1.65 = 20.6px, which is the design. Handed to the terminal engine, the same number multiplies the font's own already-leaded box, which is 16px — giving 26px. A comment in the file asserted the two agreed, which is how it survived.)*

## What's new in 0.20.1

**An HTML document opens rendered, not as its own source.** Opening an `.html` file in the workspace's document viewer showed you the markup instead of the page.

## What's new in 0.20.0

**External links name a real record instead of inventing one.** The Jira/Confluence/Docs link controls used to fabricate every identifier they recorded. A `＋` button now opens a form and records nothing until you supply the reference or a session resolves it — and `resolved` cannot be asserted, only evidenced: a row claiming it without naming the profile that resolved it is refused. PMOS still holds no credential and makes no outbound request; the lookup runs in an agent session carrying your own MCP.

## What's new in 0.19.0

**A long document scrolls its own panel, and starting a session asks what is already running.** Run `npx create-pmos@latest workspace`; the version bump means an existing install auto-upgrades.

- **Opening a long document no longer scrolls the whole window.** Scrolling a document in the right panel moved the entire interface — the top bar slid away, the status bar rose from below — while the panel's own scrollbar never engaged. Every panel now scrolls inside itself and the app frame never moves. (If you are curious: the shell's middle row was written `1fr`, which is `minmax(auto, 1fr)`, so a tall document enlarged the row rather than overflowing it. Every style involved read as correct, which is why it survived review.)
- **`＋ session` now asks before it starts one, when the checkout is already busy.** It used to start the session and *then* tell you how many others were in there — a count arriving after the decision, naming something you cannot act on. Now you get a chooser first, listing every session in that checkout.
- **It says what each one is.** Its name, its agent, the same word the sidebar uses (`working` · `quiet 12m` · `needs you` · `maybe blocked`), the agent's own last words, and who holds the writer claim.
  - **Correction (0.34.0):** the last-words line was advertised here from 0.19.0 and **never rendered** — the chooser read a field name the session rows do not carry, so it was always blank. Fixed in 0.34.0; if you are on any version from 0.19.0 to 0.33.0, that one line was missing and nothing else on this list was affected.
- **…and what ending it would cost, without over-claiming.** Only `needs you` reads as settled — its turn finished and it is waiting on you. `working` says output is arriving right now. `quiet` and `maybe blocked` say, in as many words, that the workspace *cannot tell* a finished turn from a permission prompt from a stuck tool. A confident "safe to end" that discarded a running turn would be worse than no reading at all.
- **You can take the running session instead of making another.** `open it` attaches a tab to it and starts nothing. `end it` is there too — the first click arms it and names what it will end, the second does it. `＋ start another session here anyway` is always one click: being told is never being blocked, and no session is ever refused because another is there.
  - **Correction (0.34.0):** `end it` does not work reliably and is being repaired. In a freshly opened window with no terminal tab yet, the chooser is populated over HTTP while the terminal socket is still closed, so the click **silently does nothing** — the button disarms as though it had worked and the session keeps running. If you use it, confirm in the sidebar that the session actually ended. `open it` and `start another anyway` are unaffected.
- **The same detail is written into the new session's scrollback**, so scrolling back tomorrow answers the same question the chooser did.

## What's new in 0.18.1

**Three fixes to the workspace terminal, all of them about what the window knew about a session.** Run `npx create-pmos@latest workspace`; the version bump means an existing install auto-upgrades.

- **Your terminal now uses its whole width.** Nothing ever told the shell how wide the browser was. A session starts at 80 columns; the server stated its own size on attach rather than adopting yours, and the browser only spoke up when a resize *changed* its grid — which happened once, while the connection was still opening and there was no session to tell. So the process on the other end kept wrapping at 80 columns inside a window three times that wide, and a full-screen agent CLI painted into a box that was not there.
- **The window stops rebuilding itself while you type.** It repainted every panel every four seconds whether or not anything had changed — on a project with a hundred-odd initiatives that is a real stall, on a timer, next to a terminal you are typing into. It now repaints when something it shows actually moves. Separately, the server rewrote every session's scrollback file to disk every five seconds, synchronously, whether or not a byte had changed; it now writes only what moved.
- **The scratchpad belongs to a session again.** It had become one shared buffer for the whole page, so every terminal — in every repository — showed and overwrote the same text, and none of it outlived the tab. Each session has its own pad again, saved on your machine, and it comes back with the session.
- **Reopening the workspace brings your sessions back.** Open tabs are remembered and re-attach to the exact session they were on, named on the tab so you can tell which one it is. Previously they were forgotten on reload and had to be re-found by hand — and the re-finding matched on a session *name*, which is not unique between repositories, so a tab in one project could silently attach to a shell running in another. `＋ session` also always starts a new session now, instead of sometimes adopting one that was already running.
## What's new in 0.18.0

**Several sessions in one folder now say so.** Run `npx create-pmos@latest workspace`; the version bump means an existing install auto-upgrades.

- **Starting a session where others are already running tells you what you are sharing.** Sessions in one checkout share one branch, one index and one set of files — that was true before and nothing said it. The new session's pane now names the sessions already there and points at the alternative (a new branch in its own folder). It appears on the ordinary "＋ session" path too, where no git operation runs at all: the server had already worked out that other sessions would be disturbed, and was throwing the answer away unless you happened to pick a branch.
- **It counts the right thing.** A repository registered at two paths — the project root and a subdirectory of it, the ordinary shape when you add a product repo by path — is **one** checkout, and its sessions are now told about each other; before, each was told it was alone. Two *worktrees* of one repository are **two** checkouts and are deliberately not warned about, because those are the sessions that isolation already made safe. A folder with no git says nothing, since there is no index to collide over.
- **One session is the declared writer; the rest read.** The first live session in a checkout holds the claim, and you can hand it to another (`POST /api/tree/claim`); `GET /api/tree/peers` reports who holds it and who else is there. It moves only when you move it — never on a timer or an exit — and when its holder exits the checkout reads *vacant* rather than promoting somebody at random.
- **Be clear about what that is: a declaration, not a lock.** The workspace hosts your agent's terminal; it does not sit between the agent and the files, so nothing here prevents a write, a checkout or a commit, and no session is ever refused because another one is there. It makes a shared checkout visible. The discipline stays yours.
- **A folder you are working in can no longer be reclaimed out from under you.** Removing a worktree already refused when sessions were running in it — but it counted only sessions in the workspace registered at that exact folder, so a session running in a subdirectory of it was invisible. It is counted now, and named in the refusal.

## What's new in 0.17.0

**Your board stops calling shipped work unstarted.** Run `npx create-pmos@latest workspace`; the version bump means an existing install auto-upgrades.

- **An initiative's status is now read from what happened, not from what someone typed.** The workspace took each initiative's state from a `status:` line written by hand into a PRD and matched it against a list of words. In the repo this was built in, that one field held 23 different values, 33 initiatives had none at all, and several were cut off mid-sentence by a stray comma. The plainest value of the lot — `build complete, PR #138` — matched the word "build" first and displayed as *in progress*. Status is now derived from your acceptance records, your logged runs, your open items, and your repository's own merge history, and each row states which of those it was read from. Nothing you type can move it.
- **`delivered` and `accepted` are no longer the same thing.** Work that merged and work you actually signed off are now separate states. That gap is usually the interesting number: in the repo this was built in, 62 of 63 delivered initiatives had no acceptance recorded — invisible while both wore one label.
- **The board reads your whole project history, not just the branch you are standing on.** It shared a commit range with the CI gate, and that range is *empty* when your branch is level with `main` — so every initiative reported "no implementation commits" and fell back to its earliest stage. Work finished weeks ago looked identical to work never begun. The gate still reads only the pull request, which is correct for judging whether a spec came before its build.
- **A history it cannot read is now said out loud.** In a shallow clone (some CI checkouts) the delivery history genuinely is not there. The board reports that, with the reason, instead of quietly showing everything as unstarted — which would look exactly like a project where nothing has happened.

Unchanged where it matters: **no database, no network at runtime, no telemetry.** The server still binds `127.0.0.1` only. The file-mode kit itself is unchanged and still dependency-free.

## What's new in 0.16.1

**Two fixes on the Terminal Workspace's entry path — how a repository reaches a running workspace.** Run `npx create-pmos@latest workspace`; the version bump means an existing install auto-upgrades.

- **`pmos` finds the workspace you already have open, on whatever port it is on.** The launcher used to assume one port (7433, or whatever `PMOS_WS_PORT` said in that shell). So if another program held 7433 and you moved the workspace to a different port, the next `pmos` — in a fresh terminal, in a second repo — looked at 7433, found nothing, and started a *second* server. Your repo was registered, with a workspace you were not looking at, and nothing anywhere reported an error. The server now records the port it is serving and every `pmos` command discovers it, so a second repo joins the workspace on screen. `PMOS_WS_PORT` still pins a port when you want one.
- **A taken port is no longer a dead end.** If something else holds 7433, `pmos` starts on the next free port and says so, instead of failing with `port 7433 is already in use`. `pmos stop` now stops every workspace server it can find — which is how you collapse two back into one — and `pmos doctor` reports which servers are running and, when none is, who holds the port. A failed start also prints only that attempt's log, so one conflict is reported once rather than three times.
- **The folder chooser is back in "add a product".** Picking a local folder had regressed to a bare text field in the four-panel surface, so adding a repository meant typing its absolute path. The `choose…` button opens your machine's own folder dialog again, with an in-app folder browser standing in on machines that have none. Typing a path still works, and registration is unchanged: a local folder is registered where it is, and nothing is imported from it.

Unchanged where it matters: **no database, no network at runtime, no telemetry.** The server still binds `127.0.0.1` only. The file-mode kit itself is unchanged and still dependency-free — everything above is in the optional Terminal Workspace GUI.

## What's new in 0.16.0

**The Terminal Workspace is now a four-panel surface.** The three-column layout is retired and replaced by one built to a PM-authored design: repositories, initiatives, initiative detail, and a tab strip. Run `npx create-pmos@latest workspace`; the version bump means an existing install auto-upgrades.

- **Panel 1 — repositories.** Every repo you've added, with its kind (`⎇` github / `▤` local) and its initiative count, plus a settings & tools drawer holding the secondary modes — `agents`, `memory`, `knowledge` for the current repository, and `focus`, `skills`, `connections`, `scheduled` across all of them.
- **Panel 2 — initiatives, as a channel list.** Collapsible objective/KR groups over `#slug` rows, one search box that forces the groups open and reports matches elsewhere, and an add form. Initiatives with no anchor are filed and shown as rejected (D59) rather than quietly hidden.
- **Panel 3 — initiative detail.** The record's pills and derived footer, **task phases** whose status is derived from the workflow ladder rather than declared, a **links** section for references that are not repo files, and the artifact list. A record that fails to parse renders red with the parse error — never a blank panel.
- **Panel 4 — tabs, scoped per repository.** Three kinds side by side: **term** (a real PTY running your agent CLI untouched), **doc** (view/raw/edit/diff with save, revert and a dirty flag), and **task** (the task spec view). New session, close, and split.
- **A phone surface.** The same four panels collapse into a mobile navigation model, so triage from a phone is a first-class path and not a scaled-down desktop.
- **Artifact links are declarations, not integrations.** Linking an artifact to an external destination appends `{artifact_path, kind, target}` to `pmos/state/artifact-links.jsonl`. The sync panel is rendered, but with no connector configured its summary line says exactly that — *no connector configured — nothing was read, and nothing will be written* — and the approval buttons are disabled. It will not show you a difference it never read.
- **`?fixture=proto`** renders the whole surface from a bundled fixture with no repository at all, which is also how the design comparison is run. It is never the default path.

Unchanged where it matters: **no database, no network at runtime, no telemetry.** The front end loads only same-origin assets — fonts and the terminal emulator are served from the install, never from a CDN — the server binds `127.0.0.1`, and the only outbound paths remain the ones you invoke yourself (`git clone` on repo ingest, `pmos upgrade`, and the one-time `npm install` that builds node-pty). No new runtime dependency was added. The file-mode kit itself is unchanged and still dependency-free.

## What's new in 0.15.0

**A major Terminal Workspace rebuild** (#242) — the PM spine, a Claude Design refresh, and a proper viewer column, plus five new capabilities. Run `npx create-pmos@latest workspace`; the version bump means an existing install auto-upgrades.

- **A Focus queue** — the workspace surfaces what actually needs you, as a queue to work down rather than a grid to scan.
- **A phone surface** — the workspace now has a real mobile navigation model, so you can triage from a phone, not only a desktop.
- **Claude profiles** — per-session profile descriptors, so different agent setups are legible at a glance.
- **Multi-product repo-scan** — the ingest pipeline can scan across more than one product repo.
- **A Jira handoff model** — a links model for handing an initiative off to an external tracker from the workspace (opt-in; the file-mode kit still needs no network).

The file-mode kit itself is unchanged and still dependency-free — all of the above lives in the optional Terminal Workspace GUI.

## What's new in 0.14.0

**The foundation of an autonomous workflow driver lands in the workspace.** Two new libraries (`workspace/lib/drive-plan.js` + `drive-guard.js`) give the workflow loop a head and a conscience:

- **A planner that knows when to stop.** The workflow ladder never returns "nothing left to do" — it always names a next honest action, so a naive `while (next)` loop never exits. The planner decides `dispatch` vs `stop` on three explicit triggers: **human-gate** (the next step is a PM decision — a contract or an acceptance), **no-progress** (the same next action twice running means the last dispatch moved nothing — a stop, not a retry), and **budget** (a hard ceiling so an unforeseen case still terminates).
- **A guard that can't sign the PM's name.** A gate in PMOS is "a file with the right words in it," which an autonomous writer could satisfy. The guard is the driver's *only* write path and refuses to write acceptances, a `PM_approved` flag (at any nesting depth, or smuggled as raw text), or a disposition token — so the loop can advance work but can never self-approve past a human gate.

This is the planner + guard (14 tests cover them); the return path, an independent verify pass, and a live board run are the next increments under the same contract. Run `npx create-pmos@latest workspace` to pick it up — the workspace version bump means an existing install auto-upgrades.

## What's new in 0.13.0

**Six more skills now travel with the kit** — the allowlist had been shipping dangling references to skills that lived only in the hosted repo. This closes them and adds genuinely useful file-mode capabilities. `npx create-pmos@latest --update` brings them all in.

- **`prototype-grill`** — the independent critic the `prototype` skill's step 6 already pointed at. Now it's actually here: a fresh-context second party that grills your lookable specimens (dialogue, never a score) and writes `prototype/<id>/grilling.md`. The dead link is gone.
- **`design-brief` + `design-reconcile`** — the two PMOS skills of the design loop. `design-brief` writes the presentation-only design brief; `design-reconcile` classifies a returned design against your capability ledger before any code. The design surface itself stays external and provider-agnostic (e.g. claude.ai/design) — these are the file-mode bookends around it.
- **`correction-signal-derive`** — derive the north-star signal (what a run got corrected on) from your own git/PR/CI after a merge.
- **`harness-refine`** — read your accumulated friction + eval evidence and draft harness-improvement proposals as a normal PR. The kit refining itself, on your terms.
- **`skill-creator`** — author and sharpen your own `.skill` files, grounded only in your repo (no network).

Nothing hosted came along: skills that stand up a backend, provision tenants, or sync an external tracker are deliberately still excluded, and the assembly's containment check enforces it. The Terminal Workspace app is unchanged, so a current `pmos` install won't reinstall.

## What's new in 0.12.1

A small kernel refresh: the **`prototype` skill's grilling step** (leg A of the D60 prototype loop) now dispatches an **independent griller** as a distinct, fresh-context critic — the specimens are sharpened by a genuine second party, not the same agent reviewing its own work. Update an existing kit with `npx create-pmos@latest --update`. (The Terminal Workspace app is unchanged in this release, so an already-current `pmos` install won't reinstall.)

## What's new in 0.12.0

**The sidebar says what is actually true.** 0.11.x told you things were *unreadable* when they were simply *not there* — and used the same red for both.

If you pointed the workspace at an ordinary folder or a repository that isn't a PMOS repo, almost everything read as an error. None of it was.

- **A folder that isn't a git repository** now says so, quietly. It used to say `branch unreadable`, which is an alarm about a completely ordinary directory.
- **A repository with no initiative records** reads **no initiatives yet** — a fact about the repository, calmly stated. Pointing the workspace at any repo you like is a supported thing to do.
- **A shell session** no longer reports its non-existent transcript as a failed identification. A shell is a prompt, not an agent narrating itself.
- **A row keeps its name.** Previously a plain folder rendered as a row titled `branch unreadable` — a row with no name at all, unfindable in a tree of them.

Red still means red: a corrupt state queue, a genuine git failure, or an engine that is installed but throws all still draw the alarm. The point is that they no longer share it with the normal case.

Three controls also stopped being ambiguous:

- **`＋ new session — run an agent here`** now names the repository and branch it will start in. "Here" meant the selected tree all along; with every repository on screen at once, nothing said which that was.
- **`＋ session here`** starts a session. It used to select the tree and stop.
- **A row with no sessions no longer expands** just because something needs your attention — that count is already shown on the row, and opening an empty container to "reveal" it taught you to distrust the tree.

And the pane is called **repos & sessions** rather than `work`.

> **One disclosure.** The Review Gate for this work was not scored before release. Its rubric makes the honesty checks *runnable* precisely so they cannot be satisfied by reading the code, and they were not run by an independent evaluator. Everything above was verified by the automated suites (412 checks) and by hand; none of it was independently reviewed.

## What's new in 0.11.1

**Fixes: the ladder never actually worked.** If you installed 0.11.0 and every row in the new sidebar read `ladder unreadable` in red — that was us, not your repository.

The engine that derives an initiative's stage, next step and blockers was **not included in any published package**. It lives at `scripts/workflow-state.js` in the PMOS repo, and the workspace looked for it two directories above itself — a path that exists in a development checkout and in no install. The surface 0.11.0 was released for could not run for anyone who installed it.

0.11.1 bundles the engine with the app, and adds the check that would have caught this: publishing now **derives a ladder from the packed tarball** and fails if it cannot, rather than only confirming that files are present.

So rows now show what 0.11.0 described: lane, derived stage, and the next step or the blocker — each one naming the branch it was derived from.

A repository with no `planning/initiatives/` records is no longer an error; it simply has no initiatives, and reads calmly. Some of the wording around that is still terser than it should be (a folder that is not a git repository currently reports an unreadable branch rather than saying it is not a repository) — that is being fixed separately and is a label, not a failure.

## What's new in 0.11.0

**The workspace navigates by initiative instead of by folder.** If you upgrade and the left column looks unfamiliar, this is why.

- **One tree instead of two panes.** The sidebar was a list of working trees named after directories, plus a separate list of running agents. It is now a single tree: your repository, the working trees under it, and each tree's sessions beneath that. A branch called `initiative/<id>` is labelled with the initiative, not the folder — and the folder name stays on the row, because switching a branch moves every session in that tree and a row that renamed itself would look like a row that vanished.

- **Each row says where the work is and what is next** — its lane, its derived stage, and either the next step or what is blocking it. Nothing here is a status anyone types; it is derived from your records and git, by the same engine the gate runs.

- **Every stage names the branch it was derived from.** This one matters more than it sounds. Stage is computed over `merge-base(main, HEAD)..HEAD` — *this branch's* commits — so an initiative you shipped months ago legitimately reads "spec" on a branch that did not build it. The surface now says which branch produced the answer instead of implying it is absolute.

- **The rail follows your selection.** The four lenses (initiatives · folders · scheduled · history) are replaced by one detail: pick a repository and you get its folder map, schedules and history; pick an initiative and you get its dossier — where it is, what it still owes, and every artifact it owns, grouped by what the *lane* asks for. A chore is not shown as a feature missing a PRD. Opening a dossier is a read: it never switches your working tree.

- **The workflow panel no longer freezes the app.** Deriving the board shells `git` once per initiative — around 30 seconds on a large repo — and it used to run on the request path, locking the server and every terminal session with it. It now runs in a separate process and every answer is stamped with when it was derived. On a big repository the first read says "deriving" rather than showing nothing.

- **Prototypes, user stories and copywriting are visible to the library.** Specimens in `prototype/<id>/` were outside the scanned tree, so a D60 prototype never appeared on the initiative that produced it. They do now, and `-user-stories`, `-copy-brief` and `-copy` are recognised artifact roles.

Honest note on what this release did *not* get: the 30-second derivation is **cached, not fixed** — the underlying per-file git lookups are still unbatched. And the Review Gate for this work was never scored; it was accepted on green CI and PM judgement, without an independent adversarial pass.

## What's new in 0.10.1

**Two fixes found by installing 0.10.0 and using it, rather than by reading the code.**

- **Upgrades will keep reaching you.** The launcher decides whether to reinstall the workspace by comparing the app version it bundles against the one you have. 0.10.0 shipped the *kit* at 0.10.0 but the bundled app still labelled **0.9.1** — so the next release would have compared equal, decided you were current, and **silently skipped the upgrade**. Which is precisely the failure 0.9.1 existed to fix. The two versions are now checked against each other by the test suite, so it cannot drift again unnoticed.
- **Alignment no longer offers to edit its own notes.** The change-context digest quotes every change you make, so it matched the "quotes text this change altered" rule on the very first save in any repository — and topped the list of documents to realign. A generated file proposing to realign itself. Machine-written state is now excluded from alignment entirely.

If you installed 0.10.0, run `npx create-pmos@latest workspace` once. Nothing was damaged by either bug; the first would have cost you a future upgrade, and the second a confusing first suggestion.

## What's new in 0.10.0

**Editing a document now does something for the rest of them.**

0.8.0 gave you an editor: change a markdown document in the workspace, see the diff as you type, and have the change logged. This release adds the two halves that make that log worth keeping.

### After you save, you are offered what your change puts out of step

Not a scan of your repository — a list built from **your change**. A document only appears if it has a concrete tie to what you edited:

- it links to the document you changed, or names it in frontmatter (`prd_path`, `rubric_path`, …)
- it shares that document's `initiative_id`
- it **quotes text your change altered** — the strongest signal, because it is now asserting something the source no longer says

Each candidate says which of those it is, so you can judge the suggestion before spending anything on it. **"Seems related" is deliberately not a rule.** It would widen this to your whole repository and put you back in front of a queue of an agent's opinions.

You tick which documents an agent may read. It drafts the edit that brings each back in line, and each draft comes back as a diff to apply or skip. Applying uses the same guard as every other write here: the text being replaced must appear exactly once, or the write is refused rather than guessed at.

**It never blocks.** The save completed before any of this. Dismiss the offer and nothing is queued, nothing badges, nothing waits for you.

### Your change log is now something an agent reads

Every save regenerates `change-context.md` in your repository's own state directory: the documents you change most, the recent changes, and — the part that matters — **your own stated reasons**, in your words. An agent reading it before working in your repo knows what you keep rewriting and why, so it can stop producing the thing that provoked the rewrite.

That is why the editor asks for a reason at all. A reason nobody reads is just friction at save time.

Edits made by applying an alignment record **what they were aligned with**, so the log reads as a chain rather than as unexplained changes appearing in files you did not open.

### Also carried: the 0.9.1 upgrade fix

**0.9.1 was never published.** Its fix — `create-pmos workspace` self-upgrading instead of quietly launching your old installed app — is in this release. If the workspace has looked unchanged across recent versions, that is why; run `npx create-pmos@latest workspace` once and it will self-heal onto the current app. Hard-refresh the browser afterwards to drop the cached stylesheet.

## What's new in 0.9.1

**A fix so workspace upgrades actually reach you.** If you activated the Terminal Workspace in an earlier version, `npx create-pmos@latest workspace` was quietly launching your *old* installed app — so 0.9.0's restyle and whose-turn view never showed up. That was the bug, not a missing feature.

- **`create-pmos workspace` now self-upgrades.** It compares the bundled app's version against what you have installed and **reinstalls when the bundle is newer** (then restarts the persistent server so the new code actually serves). A same-version install still fast-launches — no needless ~20-second native rebuild.
- **`create-pmos workspace --reinstall`** — force it any time.
- **`pmos upgrade`** — the same, straight from the installed command.
- If the UI still looks unchanged right after an upgrade, **hard-refresh the browser** (Cmd/Ctrl+Shift+R) to drop the cached stylesheet.

So if 0.9.0 looked like "not much changed," this is why: the code shipped, but your old install kept running. Run `npx create-pmos@latest workspace` once and it will self-heal onto the current app.

## What's new in 0.9.0

**The Terminal Workspace now tells you whose turn it is.** The optional GUI got this release's real work: it reads each session's transcript and shows, per session, whether the agent is still working or **waiting on you** — so a wall of terminals becomes a queue you can triage at a glance instead of a grid you have to click through.

- **Whose-turn, read from the actual transcript.** Each session row and tab carries its state — agent-working vs waiting-on-you — derived from the real conversation, not a guess. The sessions that need a decision surface; the ones still running recede.
- **A real design system, not a dev-tool skin.** The workspace was reskinned on a proper palette with its own typography, and the fonts ship *inside* the package — nothing is fetched at runtime, so it looks the same offline and behind a proxy.
- **Your git branch is in the frame.** Each session shows the branch it is on and lets you switch, so `initiative/<id>` work and its worktree are visible where you are working, not a `git status` away.
- **The router now makes you write the answers down.** `pmos-router` gained a step: the intake answers (does this need its own instance? has this been rejected before?) get recorded on the initiative, so a routing decision is enforceable later instead of evaporating the moment it's made.

All of this rides in `npx create-pmos@latest workspace`. The file-mode kit itself is unchanged and still dependency-free; `npx create-pmos@latest --update` brings the router change into an existing kit and never touches your `state/`, `planning/`, or `okf/product/` records.

## What's new in 0.8.0

**The document review is gone. There is a document editor instead.**

Minor, not patch: a feature that shipped in 0.7.0–0.7.3 has been **removed**, and what replaces it is a different thing with a different point. If you were using the review surface, it is not there any more — read on.

### Why it went

It answered a question nobody asked. An agent read your planning documents and told you what it thought was wrong with them, before you had touched anything. What was actually wanted was the opposite direction: **you** edit a document, and the tooling reacts to *your* change.

**It also never fully worked.** The browser's Edit → Apply path depended on a script the server was never configured to serve, so it 404'd silently in every version that shipped it. The tests that covered it went straight to the endpoint and never exercised the path a person takes. If you tried to edit a proposal and apply it and nothing happened, that was why, and it was our bug.

### What replaces it

- **Edit any markdown document in the reader.** `edit` in the document header; `save`, `cancel` and `history` while you are in it. ⌘S saves.
- **The diff is beside you as you type** — the replaced lines struck through, the new ones marked, with a running `+n −n` and the line the change starts at. Nothing to summon; it appears when the document differs from what you opened.
- **A save that refuses rather than clobbers.** If the file changed on disk since you opened it, the save fails and says so, and **your text stays in the editor** so you can copy it out. It will not merge over whoever changed it.
- **Every save is logged, per repository.** What changed, where, and — if you write one — why. It lands in your repo's own state directory, never in the installed app. `history` in the document header shows that document's own log.

The log records the changed region and your reason, **not a parallel history of your repository**. `git log` remains the record of what your files contain; this records what you changed and why, which git has no place to put.

### Not built yet, and named so you are not waiting for it

Two halves of the intended feature are **not** in this release: using a save to work out which *other* documents are now out of step and drafting the edits that would realign them, and feeding the accumulated change log to agents as context. The editor, the diff and the log are here; the propagation is not.

## What's new in 0.7.3

**A fix — read this if you ran a document review on 0.7.1 or 0.7.2, and especially if you have more than one repository open in the workspace.**

Reviews were filed into the **workspace app's own install directory** rather than into the repository being reviewed. Two consequences, and the first is the one that matters:

- **Reviews from different repositories were pooled together.** Open two repos and the review you filed against one appeared when you opened the review surface in the other. A review names the documents it read and quotes their contents, so this put one project's material in front of another — including in front of an agent session working in that second repo.
- **In a product repo using this kit, reviews were written nowhere useful.** The review skill was written against PMOS's own layout and told the agent to write to `workspace/state/reviews/` and read `workspace/state/needs.json`. **A product repo has no `workspace/` folder**, so the agent either created a stray one or filed the review where nothing would ever read it.

**Both are fixed.** Reviews now resolve through the same per-workspace state directory that `needs.json` and `acceptances.jsonl` already used — your repo's own `pmos/state/reviews/`. The skill no longer assumes any layout: the paths it needs are passed to it as absolute facts.

**If you reviewed anything on 0.7.1 or 0.7.2**, look in the workspace app's install directory under `workspace/state/reviews/` for reviews that belong to your repositories, and delete any you would rather not have sitting there. Nothing was sent anywhere — this is local files in the wrong folder — but if you had two repos open, they saw each other.

**And the reason you probably never ran one: there was no way to say what to review.** The skill could only be launched from the scheduled lens, and a schedule carries no scope — so its own instruction to read exactly the documents you named had nothing behind it.

- **A `review` control now sits on the open document.** You are reading a document; you click `review`; an agent reviews *that* document. Nothing to type, no schedule to create. The scope is the thing in front of you.

**The standing disclosure is unchanged**, and it still matters more than any of the above: the review surface has **not** been through its own review gate, and its false-positive rate is unmeasured. The guard that withholds any proposal which would close a recorded open question or overwrite a decision is tested, including in a real browser. How often its findings are simply *wrong* is not yet known.

## What's new in 0.7.2

**A fix — read this if you use the Terminal Workspace on a machine with `tmux` installed.**

0.7.0 and 0.7.1 both shipped a workspace terminal that renders **gibberish** there. Box-drawing characters, check marks, spinners, emoji and accented letters all arrived damaged, and the output lost its structure — which matters because agent CLIs print those constantly, so in practice most frames were affected. If your terminal has looked broken since 0.7.0, this is why, and it was our bug, not your setup.

The cause: the workspace drives `tmux` in control mode, and that stream is **bytes**. `tmux` escapes only the control characters and the backslash — every byte of a UTF-8 character passes through raw. The workspace decoded that stream as text and then narrowed it back to bytes, which does not merely lose characters, it *manufactures* control codes out of the wreckage. `┌` became a **form feed**, which is why the layout collapsed and not just the glyphs.

- **Fixed.** The control stream is now handled as bytes end to end, with a single UTF-8 decode in one place. A character split across two `tmux` frames still survives.
- **A second, smaller source of the same symptom, also fixed.** The scrollback ring trims from the front once it fills, and it used to cut at an arbitrary offset — routinely *inside* an escape sequence, so the leftover fragment replayed as literal rubble like `5;203m` when you reattached. It now cuts at a line boundary.
- **Nothing else changed.** 0.7.2 carries this fix and only this fix.

**You were only affected if `tmux` is on your PATH.** The workspace falls back to a direct terminal when it is not, and that path never had the defect — which is exactly why this survived two releases. The regression test now reports which of the two transports it exercised, so a green run on a machine without `tmux` can no longer read as if it had covered the one that broke.

## What's new in 0.7.1

**A correction to 0.7.0 — read this if you used the review surface.**

0.7.0 shipped the summoned document review with a defect in the part that records *why* you changed an agent's proposal. The client sent a fixed reason — `incomplete` — on **every** edit, whatever the actual reason was. So any correction record written by 0.7.0 carries a reason that is very likely false, in the one file whose whole purpose is to make the human-correction rate trustworthy.

If you ran a review on 0.7.0, treat the `reason` field in `planning/runs/correction-records.jsonl` as unreliable. Everything else in those records — the agent's text, your text, the attribution — is sound.

- **You pick the reason now.** Applying an edit asks *what was wrong with it?* and offers `factually wrong · incomplete · wrong scope · style · other…`. It **nudges rather than defaulting**, and `other` asks for a few words. Dismiss is still one click — friction belongs on the action that teaches something, not the common one.
- **A half-applied state is now impossible.** The record was validated *after* the document was written, so a missing reason could leave your file changed with nothing recorded. Validation runs first: every refusal leaves the repository byte-identical.
- **The counters are on the surface, and honest.** Dispositions, corrections and the action rate are derived from the records themselves. Quiet-on-clean reads **`not measured`** rather than a flattering zero — measuring it needs a corpus of documents known to be clean, which does not exist yet.

**The disclosure from 0.7.0 still stands**, and it matters more than this release note: the review surface has **not** been through its own review gate. Its false-positive rate is unmeasured. It withholds any proposal that would close a recorded open question or overwrite a decision — that guard is tested, including in a real browser — but nothing yet tells you how often its findings are simply wrong. Use it on documents you are willing to read carefully.

## What's new in 0.7.0

**The workspace GUI has layouts.** Until now it had exactly one arrangement: a fixed sidebar, the terminal, and a right rail. Now it has four you can name, switch between in one act, and then change however you like.

- **Named layouts — `focus` · `read` · `compare` · `review`.** Switch from the header or with ⌃1–⌃4. `focus` gives the terminal the window; `read` makes the document the primary column instead of a 400px strip; `compare` puts two sessions side by side; `review` is the arrangement you already had.
- **Adjust anything, and it's kept.** Drag a pane by its ⠿ grip to a different edge, drag a column's edge to resize it, fold a pane away — whatever you change is written back into the layout you're in. There is no save button, no "unsaved changes", and nothing to manage. Each stock layout has a **restore** in the list for when you want the original back.
- **Two terminals at once.** `compare` (or the layout menu) splits the terminal into two groups, each with its own tab strip and its own live session — so you can watch two agents work instead of alternating tabs from memory. Closing the split doesn't kill anything; the second session goes back to being a tab.
- **Make your own.** `＋ new layout from this arrangement` names what you've built; custom layouts can be renamed and deleted.
- **Layouts belong to the repo you opened.** Each workspace remembers its own, on your machine (`workspace/state/layouts/`) — nothing is sent anywhere.
- **The sidebar caught up.** Its panes now fold and its width now drags, which only the right rail could do before.

**Upgrade note:** the workspace app ships inside the package; `npx create-pmos@latest workspace` installs the new build. If you had already dragged your rail width or hidden it, that carries into this workspace's `review` layout on first run — you keep what you had. Your `state/`, `planning/`, and `okf/` records are untouched. Phones are unchanged: the single-column switcher still owns the layout there, and the layout control is hidden.

**Also in this build, and not yet finished:** a **summoned document review** surface (ask for a review of a document, dispose of each finding by Apply / Edit / Dismiss, with every disposition recorded as an attributed correction). It rides along because the package bundles the whole workspace app — its own build is still open and it has not been through its review gate. Treat it as a preview, not a finished feature.

## What's new in 0.6.4

Workspace GUI session controls — two things the PM asked for while working in real terminals.

- **Branch awareness + pick/create at session start.** The header now shows the active repo's current git branch (dirty-marked), and the new-session form lets you start a session on an existing branch or create a new one. It's honest about the shared working tree: switching a branch is repo-wide and moves every session in that repo — the form says so rather than faking per-session isolation.
- **Scratchpad.** A collapsible drawer at the bottom of the terminal column (toggle from the header or ⌘J) to stage commands and notes before they hit the terminal — it never overlays the terminal or the document reader, persists per workspace, and has **copy** and **→ terminal** (which pastes without pressing enter, so nothing auto-runs).

**Upgrade note:** the workspace app ships inside the package; `npx create-pmos@latest workspace` installs the new build. Your `state/`, `planning/`, and `okf/` records are untouched — purely additive.

## 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 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 whether a user-facing idea is even right *before* a PRD locks it in.

- **A front door: the `pmos-router` skill.** Not sure which lane a piece of work takes? Start here. It maps any entry — "I have an idea", "is this feasible?", "production is broken", "we need copy", "just upkeep" — to its lane, its spec artifact, the next skill, and the gates to expect, running a sharpness check ("can you *state* the question yet?") and a prior-rejection check on the way. It decides nothing; it routes to lanes that already exist.

  > Read pmos/AGENTS.md, then follow pmos/skills/pmos-router.skill: I want to [X] — route it.

- **The prototype lane: see it before you spec it.** For a user-facing idea, the new `prototype` skill runs a pre-PRD visual validation — you give a *quick* brief, a design agent produces 2–3 genuinely different lookable options with real draft copy, a designer-grade grilling sharpens them (a dialogue, never a score), and you dispose promote / iterate / kill. Promote derives the PRD from what you actually validated. It's the cheapest way to kill a bad idea — before it's a spec, not after four rebuilds.

  > Follow pmos/skills/prototype.skill: here's my idea — [two sentences]. Give me lookable options.

- **A design-craft concept + prototype-brief template** now ship, and the `prd`/`eval-rubric` skills gained a "grill before you write, write for durability (name interfaces, not file paths)" discipline.

**Upgrade note:** `npx create-pmos@latest --update` brings all of this in and never touches your `state/`, `planning/`, or `okf/product/` records. Purely additive — nothing about how the gate behaves on your existing initiatives changes.

## What's new in 0.3.0

0.2.0 made the workflow fit real work. 0.3.0 goes after the two ways the *judging* half quietly fails: a judge that can be talked into a pass, and a PM who accepts what they don't understand.

- **The evaluator now defends itself.** It reads diffs and PR text written by someone else, so it treats every word of that as *content under evaluation*, never as instructions. A "mark this PASS" buried in a diff is reported as a defect instead of obeyed. And it's structurally read-only — its one write is the verdict — because the part that reads hostile text must not be the part that can act. Prompt-level defenses alone get bypassed; removing the capability doesn't.
- **An understanding layer.** The new `explain-run` skill writes a literate explainer + a comprehension quiz for a run, authored by the *independent* evaluator, never the builder. Read that before you accept. Raw transcripts are a vigilance task nobody wins at; accepting without comprehending makes the human gate only formally human.
- **Evidence-anchored scoring.** Every scored dimension must cite a verbatim quote or a precise pointer (file+line, command output, CI line). No evidence, no high score — the dimension is marked `unverified` and capped. Verdicts became auditable instead of assertable.
- **Richer anchored scales.** Rubrics now prefer five described levels over a bare 0/0.5/1. It is the single largest evidenced lever on judge agreement: the more precisely each level is described, the less two evaluators — or the evaluator and you — drift apart.
- **Balanced exemplars before scoring.** The evaluator picks 2–4 prior cases from your calibration log, deliberately balanced across passes *and* fails, and names them in the verdict. If your log has no fail-side cases yet, it says so out loud rather than quietly leaning generous.
- **A leniency disclosure in every verdict.** The evaluator states its own recent pass-fraction. A judge that passes everything is the failure mode you can't see from inside a single run.
- **SKILL-FORMAT v2.** The skill format is now compatible with the broader Agent Skills ecosystem, with the quality bar for writing one made explicit.

**Upgrade note:** `npx create-pmos@latest --update` brings all of this in — it refreshes skills, concepts, templates, and scripts and never touches your `state/`, `planning/`, or `okf/product/` records. One consequence to expect: because unevidenced dimensions are now capped, verdicts on work the evaluator can't directly observe will score *lower* than they did on 0.2.0. That's the change working, not a regression — it was scoring on trust before.

## What's new in 0.2.0

The kernel grew four capabilities, each born from real dogfooding of 0.1.x:

- **Work-type lanes.** `type: feature | discovery | chore | incident | content` on the initiative file — each lane has a fitting spec artifact (spike brief, stated intent, post-hoc incident record, content brief) and the gate enforces per lane. Research, maintenance, fires, and copy no longer have to cosplay as features.
- **Human builders, first-class.** `pmos/AGENTS-HUMAN.md` is the whole protocol on one page for a person, and `pmos/scripts/pmos-log.sh` writes validated state records with one command — mixed human/agent teams share the same files and metrics.
- **Health budgets.** Maintenance with no honest goal anchors to a declared budget (`parent_kr: health:<id>` from `pmos/planning/okrs/health-budgets.md`, seeded with capped tech/security/ops lines) instead of forcing a fake goal link. A fake anchor is worse than an honest budget.
- **Test-first Quality Gate.** `templates/product-ci-starter.yml` ships failing-until-wired, so a fresh repo's CI is loud until you give it real tests — never silently empty.

**Upgrade note:** the gate now rejects an initiative file with **no `parent_kr`**. If `--update` makes an old initiative fail the gate, that file was always unanchored — add a real goal, or a health budget id if it's honest maintenance. The gate failing is the fix working. (One caveat for upgraders: `--update` never touches `planning/`, so it won't create `pmos/planning/okrs/health-budgets.md` — declare your budgets by writing that small table yourself or copying it from a fresh vendor; the gate accepts the `health:<id>` string either way, but an undeclared budget id is exactly the fake-anchor problem in new clothes.)

## Scope & support

This package contains only the PMOS workflow kernel. It holds no reference to, and never contacts, any external backend — the publish pipeline verifies that on every release. MIT, provided as-is: a snapshot from a private upstream, updated when the maintainer publishes. Issues/PRs are not currently monitored — the kit is deliberately self-sufficient; everything it needs to teach you is in `pmos/AGENTS.md` and `pmos/README.md`.