create-pmos 0.52.0 → 0.53.0

package/workspace/guide/index.md

@@ -1,7 +1,7 @@
 ---
 type: Guide
 title: "Guide: start here"
-timestamp: 2026-10-04
+timestamp: 2026-10-05
 ---
 
 # Guide: start here
@@ -10,33 +10,43 @@ This guide describes the PMOS workspace as it works today. It ships with the app
 
 ## The screen
 
-The workspace has three columns. [Layout](layout.md) explains where things open.
+On a desktop the workspace is one frame. [Layout](layout.md) explains each part.
 
-1. **Navigation.** The repositories you added, with the list of the current mode under them. The default list is the initiatives of the selected repository. The settings and tools drawer at the bottom opens the other lists here.
-2. **The detail.** The item you selected: an initiative with its status, next steps and artifacts, or a skill, a schedule or a memory item.
-3. **Tabs.** Terminals, documents, conversations and guide pages.
+1. **The top bar.** Repository ▾, the four places, search (⌘K), Sync when the repository is not in sync, and Settings.
+2. **The place.** One of Today, Initiatives, Board or Reports. It fills the screen under the bar.
+3. **The detail.** The item you opened: an initiative with its status, next steps and artifacts, or the profiles. It opens beside the place and closes with ×.
+4. **The agent dock.** Terminals, documents, conversations and web pages. It is open on Today and a thin rail elsewhere.
 
-## The settings and tools drawer
+## Where things are
 
-| Item | What it opens |
+| You want | Go to |
 |---|---|
-| today | What is waiting for you now, with your feedback and the settings of the proactive engine. |
-| memory | What the repository remembers: decisions and notes kept in its memory ledger. |
-| knowledge | The decisions, concepts and skills of the repository. |
-| portfolio | Every initiative of every repository, grouped by domain. |
-| guide | This guide. |
-| validate | Checks that one repository agrees with itself, on your machine. It can also check with TypeSafe, which sends text only after you turn it on. |
-| focus | What is waiting on you, across all repositories. |
-| skills | Built-in and user skills. A built-in is read-only. |
-| scheduled tasks | Skills that run on a schedule. |
+| What is waiting for you now | Today |
+| The initiatives of a repository, or of every repository | Initiatives. Choose **All repositories** in Repository ▾ for every repository. |
+| The items of an initiative | Board, or Breakdown in the initiative detail |
+| Run reports | Reports |
+| Repositories, Profiles, New sessions (the default CLI and model), Validate consent, Theme | Settings |
+| Validate | Settings, under Validate consent: **Open Validate** |
+| A document, a decision record, a memory entry, a page of this guide | ⌘K, with its scope: Knowledge, Memory or Guide |
+| A report across every repository | ⌘K: Portfolio report |
+| A note, or a message to a session | ⌘K |
 
 ## Where to read next
 
-- [Layout](layout.md): the three columns and the rule for where a list or a detail opens.
+- [Layout](layout.md): the frame, the keys and the rule for where a list or a detail opens.
 - [Statuses](statuses.md): what each status means, where it comes from, and what you can change.
 - [Initiatives and next steps](initiatives-and-next-steps.md): the detail, the next steps, and the artifacts.
+- [Breakdown](breakdown.md): an initiative's items in the Tree and on the Board, the item sheet, Undo, Keep, Hand to agent and `pmos item`.
 - [Scheduled tasks and the command line](scheduled-tasks-and-cli.md): how to make, edit and run scheduled tasks.
 - [Validate a repository](validate-with-typesafe.md): what each kind of document is compared with, how to read the verdict, and what leaves your machine.
 - [Today and the proactive engine](proactive-engine.md): what Today finds, what you can do with an item, the settings, the commands and the limits.
 - [Live notes](live-notes.md): take notes in a meeting, confirm each talking point, and what goes to Jev when you turn it on.
 - [Find knowledge without reading whole files](knowledge-graph.md): what `pmos kg` finds, its commands, how to read its numbers, and its limits.
+- [Initiatives: the Roadmap, the List and the initiative sheet](initiatives-screen.md): how to read and order the initiatives of a repository, open the sheet, make a new initiative, and review the cycle.
+- [Initiatives and the Roadmap: Now, Next and Later](initiatives-roadmap.md): what day one shows, how an agent proposes a move, and `pmos initiative` and `pmos measure` from a terminal.
+- [PM-only acts: what only you can do](pm-only-acts.md): which acts are yours, how the workspace checks that a press comes from your page or your terminal, and what to do when one is refused.
+- [PM-only lines: how the workspace checks your acts](pm-only-lines.md): how each act is recorded, what the Today card "A PM-only line is not attested" means, and the grants for a bulk lifecycle change and a Release.
+- [Breakdown › Timeline](timeline.md): an initiative's items on a time axis, split by stage, with milestones, today, and the at-risk flag when an item starts before its predecessor ends.
+- [Initiatives › Timeline](initiatives-timeline.md): when each initiative runs, one row per initiative, and how to reorder rows by their grip.
+- [Board](board.md): one Kanban for the items of every initiative, its filters, Release, and `pmos board`.
+- [Integrated work](integrated-work.md): how `pmos verify-work` turns a merged commit into Done, and what "Done · your call · not merged" means.

package/workspace/guide/initiatives-roadmap.md

@@ -0,0 +1,130 @@
+---
+type: Guide
+title: "Initiatives and the Roadmap: Now, Next and Later"
+description: "How an initiative gets a place in Now, Next or Later, what day one shows, how an agent proposes a move, how to add an initiative, how to record a measurement, and how to use pmos initiative and pmos measure from a terminal."
+timestamp: 2026-10-05
+---
+
+# Initiatives and the Roadmap: Now, Next and Later
+
+The Roadmap puts each initiative of a repository in one of three horizons:
+
+- **Now** — the work that is in progress. Only you put an initiative in Now.
+- **Next** — the work that starts when a place in Now is free.
+- **Later** — the rest. A new initiative starts at the top of Later.
+
+The order in a horizon is your priority order. An initiative can also have a **check-by** date: the day you want to look at it again.
+
+The Roadmap shows work lanes only: feature, discovery, chore, incident, content, prototype and the other lanes of the work group. A document lane (for example strategy) is a file, not a row. It is not on the Roadmap, in the list, in the sheet or in an export.
+
+## Where the Roadmap is kept
+
+The workspace keeps the places in `planning/runs/placements.jsonl` in the repository (`pmos/state/placements.jsonl` in a PM-artifacts repository). Each move adds one line to that file. Nothing is changed or removed. The workspace page and the `pmos initiative` command use the same writer, so they always show the same order.
+
+Each line records who wrote it and from where. You cannot set this yourself. The writer refuses a line that names its own writer.
+
+## Day one
+
+The first time you open the Roadmap, the file has no lines yet. The workspace then places each initiative from its activity:
+
+- An initiative with activity in the last 5 days reads **Now, unconfirmed**. Move it to confirm it, or move it to Next or Later.
+- An initiative with no activity for 45 days reads **dormant**, at the end of Later.
+- Every other initiative is in Later, the most recent activity first.
+- An accepted or stopped initiative is never in Now. It goes to the end of Later.
+
+The two numbers are `stall_days` and `dormant_days` in `planning/plan-rules.json`.
+
+While an initiative reads Now, unconfirmed, the Today list shows one **Review the cycle** row. The same row shows when an agent proposal waits for you and when a check-by date has passed.
+
+## Agent proposals
+
+An agent session can move an initiative to Next or Later, or change the order. The workspace writes each such move as a **proposal**. A proposal does not move anything. It shows on the Roadmap with the name of the agent session.
+
+- **Adopt** a proposal to make the move. Only you adopt a proposal.
+- **Drop** a proposal to close it. You or the agent that made it can drop it.
+
+When you move the same initiative yourself, your move replaces its open proposals.
+
+## Acts only you can do
+
+Two acts are yours only. The workspace refuses them from an agent session.
+
+- **Move to Now**, and any reorder or check-by of an initiative that is in Now.
+- **Adopt** an agent proposal.
+
+On the page, each press does one initiative. The page refuses a request that moves more than one initiative to Now. In a terminal, you type the initiative id (or the proposal id) to confirm. The command refuses with no interactive terminal.
+
+## Add an initiative
+
+Every initiative needs an anchor: a KR of the current period or a health budget `health:<id>` from `planning/okrs/health-budgets.md`. The workspace refuses an initiative with no anchor, from the page, from the terminal and from an agent session.
+
+The writer makes the record in `planning/initiatives/<id>.md` with its type, title, timestamp, lane and anchor. A chore also needs its intent in one paragraph. The new initiative starts at the top of Later. Commit the record to keep it.
+
+The writer refuses:
+
+- a lane that the repository does not have, or a document lane;
+- an anchor that names no KR or health budget;
+- an id that is already a record.
+
+### From a capture
+
+A capture note in `planning/requirements/capture-<date>-<n>.md` (`pmos/state/requirements/` in a PM-artifacts repository; a quick note from the command palette) becomes a **Proposed** row on the Today list: "Proposed: title · lane · anchor". The workspace proposes the title from the first sentence and an anchor when the words match a KR or a health budget.
+
+When the note matches a file in `planning/out-of-scope/`, the row says **matches an earlier rejection** and names that file. Read it before you add the initiative.
+
+Press **Add** to make the initiative, or use `pmos initiative new --from <capture>`. After that, the capture leaves the list.
+
+### No anchor
+
+An old record with no `parent_kr` shows on the Today list as "<title> has no anchor". Add an anchor to its record.
+
+## Break this down
+
+An empty Breakdown offers **Break this down** with a starter list. The list is in `planning/work-starters.md`. Change that file to change the list. See [Breakdown](breakdown.md).
+
+## Export a breakdown
+
+The export gives an initiative's breakdown as markdown: the title and anchor, then one heading per stage, then each item with its state, owner and dates. It writes no file. Two exports of the same breakdown are the same text.
+
+## Measurements
+
+A measurement is the value of a KR or a health budget on a date, with its source. The workspace keeps measurements in `planning/runs/measurements.jsonl`. The List shows the latest measurement next to each anchor.
+
+Every measurement needs a source: the file the value comes from and its commit, as `<path>@<commit sha>`. The writer refuses a measurement with no source. An agent can record a measurement, because a measurement is evidence, not a decision. The `measure` skill tells an agent how to do this.
+
+## From a terminal: pmos initiative
+
+`pmos initiative` uses the same writers as the page. You need no running server.
+
+| Command | What it does |
+|---|---|
+| `pmos initiative new "<title>" --lane <lane> --anchor <anchor> [--intent "<text>"] [--id <id>]` | Makes the record and puts it at the top of Later. |
+| `pmos initiative new --from <capture> [--anchor <anchor>]` | Adds the initiative a capture proposes. |
+| `pmos initiative now <id>` | Moves it to the end of Now. You only: type the id to confirm. |
+| `pmos initiative next <id> [--top]` | Moves it to the end of Next, or to its top. |
+| `pmos initiative later <id> [--top]` | Moves it to the end of Later, or to its top. |
+| `pmos initiative top <id>` | Moves it to the top of its horizon. |
+| `pmos initiative up <id>` | Moves it one place up. |
+| `pmos initiative down <id>` | Moves it one place down. |
+| `pmos initiative check-by <id> <YYYY-MM-DD\|none>` | Sets or clears its check-by date. |
+| `pmos initiative adopt <proposal>` | Makes the move an agent proposed. You only: type the proposal id to confirm. |
+| `pmos initiative drop <proposal>` | Closes a proposal. |
+| `pmos initiative list` | Shows Now, Next and Later in order, with the open proposals. |
+| `pmos initiative export <id>` | Writes the breakdown as markdown to the terminal. |
+
+Every command takes `--json` and `--root <dir>`. In an agent session, `next`, `later`, `top`, `up`, `down` and `check-by` write a proposal. The command does not accept `--by` or `--via`.
+
+The command exits 0 when it is done, 1 when it refuses, and 2 for a usage error.
+
+## From a terminal: pmos measure
+
+| Command | What it does |
+|---|---|
+| `pmos measure add <anchor> <value> --source <path>@<sha> [--target <number>] [--unit <unit>] [--as-of YYYY-MM-DD]` | Records a measurement. With no `--as-of`, the date is today. |
+| `pmos measure list [<anchor>]` | Shows the measurements, oldest first, for each anchor. |
+
+Put an anchor with a space in quotes: `pmos measure add "KR 2.1" 41 --source planning/okrs/q4.md@1a2b3c4`.
+
+## The checks
+
+CI runs `scripts/check-placements.js` and `scripts/check-measurements.js` on each pull request. Each check fails on a line that is not JSON, a line that breaks the format, and one event id with two different lines. It reports, and does not fail on, a line the Roadmap ignores, for example an agent line that adopts a proposal.

package/workspace/guide/initiatives-screen.md

@@ -0,0 +1,89 @@
+---
+type: Guide
+title: "Initiatives: the Roadmap, the List and the initiative sheet"
+description: "How to read and order the initiatives of a repository on the Roadmap and the List, open the initiative sheet, make a new initiative, and review the cycle."
+timestamp: 2026-10-05
+---
+
+# Initiatives: the Roadmap, the List and the initiative sheet
+
+The Initiatives place shows every initiative of the selected repository. Each initiative is in one horizon: Now, Next or Later. A horizon is an order, not a date. The order and the horizon of each initiative are lines in `planning/runs/placements.jsonl`. The workspace page and the `pmos initiative` command write the same lines.
+
+Press **Roadmap** or **List** at the top to change the view. The workspace keeps your choice in this browser.
+
+## The Roadmap
+
+The Roadmap has three columns: Now, Next and Later. Each column is a ranked list of cards. The line at the top reads, for example, "Now · 5 KR · 3 health". It counts the initiatives in Now by what they serve: a key result (KR) or a health budget. When the rules set an advisory cap for Now, the line shows it. The cap only advises. It never stops a move.
+
+A card shows the title, the stage, "7 of 12" for the items done, the check-by date when a card in Now has one, and the reason when the initiative is not on track. An initiative that is on track shows no health text.
+
+### Move a card
+
+- **Drag.** Hold the grip at the start of the card, then drop it in a column. On a touch screen, hold for a moment before you drag.
+- **Keyboard.** Select the card and press Alt and the Up or Down arrow.
+- **The card menu.** The menu has: Open, To top, Up, Down, Move to Now, Move to Next, Move to Later and Set check-by. On a phone, press the three dots on a card. Two presses move a card up one place. On a desk the three dots are not on the card, and a line above the columns says so. Right-click the card, or press the menu key while it has focus. Set check-by is on the cards of Now only. A card that leaves Now loses its check-by date.
+
+Only you can move an initiative into Now. The workspace writes the line as yours. If the server refuses a move, the card goes back and a message tells you why.
+
+### Unconfirmed, proposed and dormant
+
+- **unconfirmed.** An initiative that reads Now only because it is active, with no line from you. Confirm it in the Cycle review.
+- **proposed.** An agent proposed a move. It changes nothing until you keep it in the Cycle review.
+- **Dormant.** An initiative with no activity for a long time. Press the dormant line under Later to show them.
+
+## The List
+
+The List groups the initiatives by objective, and inside each objective by anchor. An anchor is the KR or the health budget that the initiative serves. A group shows its measured value only when the repository has one: for example "41% on 2 Oct → 55%". A group with no measured value shows none.
+
+Press **Select** (or the `x` key) to choose rows. The bar shows what you can do with the choice:
+
+- **Move to Next** and **Move to Later**.
+- **Change lifecycle.** A sheet opens with the state to set: On hold, Closed, Cancelled or Active. It opens on On hold. Press **Confirm** to write it. This is off until the workspace can write one lifecycle line for each initiative on your press. Until then the button is disabled and says that the act arrives in Run 2. You can still change one initiative at a time in its sheet.
+
+You can select 20 initiatives at most. The List never moves several initiatives into Now at once, and never changes an anchor for several. Those are one-at-a-time acts.
+
+## The initiative sheet
+
+Press a card or a row to open its sheet. On a desk the sheet is about 70% of the width. On a phone it fills the screen.
+
+From the top:
+
+1. The horizon, the health reason when there is one, and the More button.
+2. Line 1: the stage and who the initiative waits on. Line 2: the stage steps, as a row of stages.
+3. One line of text: "Waiting on you: approval" with **Open gate**, or "Waiting on agent: build" with **Hand to agent**. When nothing is owed it says so.
+4. Three tabs: **Breakdown**, **Files** and **History**. The Breakdown tab is the same Breakdown as in its own tab, and it shows here too.
+
+An initiative that is finished reads "Accepted". An initiative on hold, closed or cancelled reads that word instead of a stage. After 5 days with no activity, the line adds "idle 5 d".
+
+The More button in the sheet has:
+
+- **Move to Now**, **Move to Next**, **Move to Later**.
+- **Set check-by.** On an initiative in Now. A date by which you want to look again. The Cycle review lists the dates that passed.
+- **Lifecycle.** On hold, Close, Mark cancelled or Reopen. Only you can change it. A sheet asks you to confirm and gives you a field for the reason.
+- **Change anchor.** Only you can change it. Enter a KR id such as KR 2.1, or health: and an id. It rewrites the anchor line in the frontmatter of the initiative record and nothing else.
+- **Copy CLI.** Copies the `pmos initiative` command for the same act.
+- **Export breakdown.** Copies the Breakdown as text.
+
+## Make a new initiative
+
+Press **New initiative**. Give a title, choose a lane and choose an anchor. An initiative with no anchor is refused. The new initiative starts in Later. When it is real work, move it to Now yourself.
+
+The same act from a terminal is `pmos initiative new "<title>" --anchor <kr>`.
+
+### Break this down
+
+An initiative with no items shows **Break this down** in its Breakdown. When the repository has a file `planning/work-starters.md`, its bullet lines show as a starter list, and **Add n items** adds them all. You can also press **Break this down** and type the first item.
+
+## Today: the triage card and the Cycle review
+
+- **Triage.** "Proposed: Partner SSO · new feature · KR 2.1" with **Add**. An agent read a capture and proposed an initiative. One press of Add writes it, in Later.
+- **Cycle review.** The card opens a sheet with three lists. Now, unconfirmed: **Confirm** keeps it in Now, **Move back** puts it in Later. Agent proposals: **Keep** applies the move as your line, **Drop** removes it. Check-by dates passed: set a new date, or move the initiative to Next. Each press acts on one initiative: there is no Confirm all, because Move to Now is never done in bulk.
+- **Monthly kill check.** The same sheet opens from the monthly check of the kill conditions, with the file that the check reads.
+
+## Keys
+
+| Key | What it does |
+|---|---|
+| Alt and Up or Down | Moves the selected card up or down one place. |
+| `x` | Starts and ends Select in the List. |
+| Escape | Closes a menu or a sheet. |

package/workspace/guide/initiatives-timeline.md

@@ -0,0 +1,57 @@
+---
+type: Guide
+title: "Initiatives › Timeline: when each initiative runs"
+description: "How to read the Timeline of Initiatives, what draws a bar, how to reorder rows, and what to do on a phone."
+timestamp: 2026-10-05
+---
+
+# Initiatives › Timeline
+
+The Timeline shows each initiative as a row, with its work laid out by month. Use it to see when work runs and which initiatives have no dates yet.
+
+The Roadmap answers "in what order?". The Timeline answers "when?". The Timeline uses the placement lines that the Roadmap uses. An initiative that no line has placed reads Later. Held, closed and cancelled initiatives have no row here.
+
+## Open the Timeline
+
+1. Open **Initiatives**.
+2. In the View control, press **Timeline**. The other views are **Roadmap** and **List**.
+
+## Read the chart
+
+- **Months.** The months run across the top. The chart starts at the first month that holds a date and ends at the last. It always includes today, and it is at least three months and at most 24 months wide. Today is the date on the machine that runs the workspace. If the dates reach outside 24 months, the chart opens a few months before today, and a note under it says that a date outside those months is cut off. The dates in a row's meta line stay complete.
+- **Groups.** The rows are in three groups: Now, Next and Later. A group shows only when it has a dated initiative. Inside a group the rows follow the placement lines. A row that no line has placed comes after the rows that have one, in id order.
+- **Row.** A row has a grip, a title, and one line with the lane, the number of items done ("7 of 12") and the dates the bar covers.
+- **Bar.** The bar runs from the earliest start date to the latest due date of the initiative's items. It is split by stage, so you can see when Intake ends and when Build starts. A stage with no dated item has no part of the bar.
+- **Diamond.** A milestone item shows as a diamond on its due date.
+- **Today.** One line crosses the chart at today's date. On a chart wider than the screen, the chart opens with today in view.
+- **Stages.** Press the arrow at the start of a row to show one row for each stage. A stage row shows the stage, how many items are done ("Build · 3 of 5") and its own bar. The arrow reads "Show stages of …" or "Hide stages of …" for a screen reader.
+- **Not dated.** An initiative with no dated item has no bar. It sits below the chart, in the heading **Not dated**, in its group. It shows only the order it carries. Give one of its items a start or a due date in the Breakdown and its bar appears.
+
+If no initiative has a dated item, the Timeline says so and shows no chart.
+
+## What the Timeline shows
+
+- **Work lanes only.** An initiative in a document lane (a strategy, a report, a decision record) has no row. You reach those as files.
+- **Held, closed and cancelled initiatives** have no row.
+- **Dates come from items.** Nothing on the Timeline has a date of its own. A date is the start or the due date of an item. You set it on the item, in the Breakdown. See [Breakdown](breakdown.md).
+- **Bars do not move.** You cannot drag a bar to change a date. A drag that starts on a bar writes nothing.
+
+## Reorder a row
+
+A row reorders inside its own group. It never changes horizon here: to move an initiative to Now, Next or Later, use the Roadmap.
+
+- **Grip.** Hold the grip at the start of the row and drag it up or down. On a phone, hold the grip for a moment first, then drag. The row is placed after the row above it.
+- **Keyboard.** Put the focus on the title and press Alt+ArrowUp or Alt+ArrowDown.
+- **Menu.** Press **⋯** on the row. The menu has **Open**, and then **To top**, **Up** and **Down** when the row can move that way. A row alone in its group has only **Open**.
+
+A move writes one line to `planning/runs/placements.jsonl` (`pmos/state/placements.jsonl` in a kit repository). The line says who moved the row: it is you, from the page. A row that no line has placed cannot be named by a line that follows it. When you move a row next to such a row, the move writes one line for each row from the first row it changes to the last row that needs a line, and a message says how many. After that, those rows keep the order you see. If the workspace refuses the move, a message gives the reason and the rows stay in the order the file has.
+
+Moving a row inside Now is a placement into Now. If the workspace asks for your press for it, the message says so.
+
+## On a phone
+
+At 390 px the chart scrolls sideways inside its own box. The page does not scroll sideways. The name of each row stays at the left edge while the months move under it. Every control on a row, the grip, the arrow and the **⋯** button, is at least 44 px high and wide.
+
+## Keep the view current
+
+The Timeline reads again about every ten seconds while the page is visible, and when you return to the page. A change made in a terminal, or by an agent, shows without a reload.

package/workspace/guide/integrated-work.md

@@ -0,0 +1,94 @@
+---
+type: Guide
+title: "Integrated work: from a merged commit to Done"
+description: "How pmos verify-work marks factory work items integrated from the default branch, how a plan item then reads Done, when the Build step is done, why factory work starts only from Now, and the two factory health reasons."
+timestamp: 2026-10-05
+---
+
+# Integrated work: from a merged commit to Done
+
+Some items of a breakdown go to the factory. The factory does the work in the product repository and opens a pull request. This page tells you how a merged pull request makes its item Done, and what the workspace shows on the way.
+
+## Two ledgers, one link
+
+- The breakdown items are in `planning/runs/plan-items.jsonl`. You and the agent write this file. See [Breakdown](breakdown.md).
+- The factory work items are in `planning/work-items.jsonl`. Only the factory writer adds lines to this file.
+- When an item goes to the factory, its work item gets the field `plan_item`. This field holds the id of the breakdown item, for example `checkout.k3m9x2a7qd`. It is the only link between the two files.
+- A breakdown line never goes into `planning/work-items.jsonl`. The checker in CI stops a `plan_item` that names no breakdown item.
+
+## Factory work starts only from Now
+
+An initiative must be in Now before the factory takes work for it. This rule applies to a feature that is anchored to a KR. It does not apply to a chore, an incident or an initiative anchored to a health budget.
+
+If the initiative is in Next or Later, the factory refuses the work and gives the reason. The factory also refuses the work when Initiatives shows "Now, unconfirmed": only a Now that you confirmed counts. To continue:
+
+1. Open Initiatives.
+2. Move the initiative to Now, or confirm it in Now. Only you can do this.
+3. Send the work to the factory again.
+
+## Mark merged work: `pmos verify-work`
+
+A commit can name a work item in a trailer, on its own line at the end of the commit message:
+
+```
+Work-Item: checkout.3
+```
+
+When that commit is on the default branch, the work item is integrated. To record this, run:
+
+```
+pmos verify-work
+```
+
+The command does these steps:
+
+1. It finds the default branch in the local refs: `origin/main`, `main`, `origin/master` or `master`, in that order. It does not fetch. To see new commits, pull first (Sync).
+2. It reads the `Work-Item:` trailers on that branch.
+3. For each work item that is not integrated yet, it adds one `integrated` line to `planning/work-items.jsonl`. The line names the commit.
+
+You can run the command again at any time. A work item that is already integrated is not written again.
+
+Options:
+
+- `--branch <ref>` reads only the commits up to `<ref>`. The ref must be on the default branch. A ref that is not merged is refused, and the command writes nothing.
+- `--dry-run` shows what the command would write, and writes nothing.
+- `--json` prints the result as JSON.
+- `--root <dir>` runs in a different repository.
+
+The command runs the repository's own copy of `scripts/verify-work.js`. A repository with no factory writer has no work items, and the command tells you so.
+
+### What the command does not write
+
+The command reports these cases and writes nothing for them:
+
+- **Refused.** The work item is merged, but the factory writer does not accept `integrated` yet. Usually the work item was not verified, or its last check failed. The line shows the reason from the writer. The command then exits with 1.
+- **Unknown.** A trailer names a work item that is not in the ledger.
+
+A commit that is only on another branch is not read.
+
+## What you see on the item
+
+- **Done.** When its work item is integrated, the breakdown item reads Done. Nobody moves it by hand, and no line is added to `plan-items.jsonl`.
+- **Done · your call · not merged.** You moved the item to Done, but its work item is not integrated yet. The item stays Done because you decided it. The text tells you that the work is not on the default branch.
+
+## When the Build step is done
+
+An item never completes a stage, with one exception. For a code initiative, the Build step is done when every factory work item under Build is integrated. The work items under Build are the ones whose `plan_item` is a breakdown item in the Build stage.
+
+- While one of them is not integrated, the Build step is pending. The step names the work items it waits for.
+- A breakdown item that you move to Done by hand does not complete the Build step.
+- A withdrawn work item, or a withdrawn breakdown item, is not counted.
+- When no work item names a breakdown item under Build, the commits decide the Build step, as before.
+
+CI, the `node scripts/workflow-state.js` command and the workspace use the same rule, so they show the same Build step.
+
+## Factory health
+
+Two health reasons come from the factory. Each shows its reason as text.
+
+- **Off track.** A factory work item failed its check, and nobody fixed it or withdrew it.
+- **At risk.** The initiative is in Next or Later, but the factory claimed work for it, or commits on the trunk are attributed to it. Building starts only from Now. Move the initiative to Now, or stop the work.
+
+## Where to read next
+
+- [Breakdown](breakdown.md): the items of an initiative, the Tree and the Board.

package/workspace/guide/knowledge-graph.md

@@ -68,84 +68,19 @@ The workspace decides the category with local rules only. It uses no model and s
 
 When a later rule disagrees with the rule that decided, the file keeps the earlier answer. A `Reference` or `Research` file with no better evidence has no category. It shows as `undetermined`. That is not the same as `other`: `other` means the file is none of the kinds, and `undetermined` means no rule could tell.
 
-The Knowledge view shows the category after each document name. Point at it to see which rule decided. Press a category above the list to show only those documents, and press it again to show all. The category is advisory. `pmos kg stats` counts the files in each category.
-
-### Ask Jev about undetermined files
-
-Jev can give a category to a file that the local rules leave `undetermined`. This is off until you turn it on. Jev never sees a file that already has a category from a local rule or from your correction. The measured pass below is the one exception for the local rules.
-
-Three things must all be on before anything is sent:
-
-1. A TypeSafe key, saved on the Validate page.
-2. Validation, switched on for this repository.
-3. **Categorize with Jev**, the switch in the Knowledge view.
-
-If one of them is off, the Knowledge view tells you which one.
-
-To start:
-
-1. Turn on **categorize with Jev**.
-2. Press **ask Jev about undetermined files**. The view shows how many requests it will send, about how many characters, and the host. Nothing is sent yet.
-3. Press **confirm and send** to send that number. If the files changed after you looked, even when the number is the same, the send stops and you look again.
-
-After the first confirmed send, the workspace sends only new or changed undetermined files. It does this when it reads the documents of this repository, at most once a minute. It reads them when it starts and when you open the Knowledge view. If more than 25 files wait, it does not send them. It tells you, and you confirm the count again.
-
-What is sent for each file: the title, the headings and the start of the text, at most 3,000 characters. The file path and the whole file are not sent. A file under an excluded path is not sent. A file whose start looks like a password or a key is not sent.
-
-Jev's answer shows as the category with `(jev)` after it. Point at it to see how sure Jev was, in words. If Jev was not sure, the file stays `undetermined` with `(jev unsure)` after it, and the tooltip names the two categories Jev was between. A Jev category is advisory. Each answer is kept on your computer, outside the repository, and the same text is not sent twice. Nothing is written into the repository.
-
-After a pass, the Knowledge view shows what happened to each undetermined file. Files with a problem are at the top of the list:
-
-- **failed**: the request did not succeed. The row gives the reason. The file keeps the local result, and the next pass sends it again.
-- **not asked**: sending stopped before this file. The row gives the reason.
-- **unreadable**: the workspace could not read Jev's answer. The file is not sent again until it changes.
-- **unsure**: Jev was not sure. The row names the two categories, and the file stays `undetermined`.
-- **withheld** or **excluded**: the file was not sent. The row says why.
-- **categorized**: Jev gave a category. The row names it.
-
-A line above the list counts the files in the view: decided by the local rules or your corrections, categorized by Jev, and still `undetermined`.
-
-If the service rejects the key two times, cannot be reached three times in a row, or sends three answers in a row that the workspace cannot read, sending stops for this repository. An answer that cannot be read is not sent again. Press **resume** to start again.
+The Knowledge view is cut, so no screen lists the category of a document. The category is advisory. `pmos kg stats` counts the files in each category, and the Knowledge scope of ⌘K finds a document by its name.
 
 ### Measure how well Jev categorizes
 
 The measured pass sends the files of the labelled set to Jev and compares the answers with the labels. It runs only when you start it in a terminal. The workspace never starts it.
 
-The measured pass also sends labelled files that a local rule already decides, because it measures Jev on them. It does not send a file that you corrected. The three switches, the excluded paths and the password and key check apply as for the Knowledge view.
+The measured pass also sends labelled files that a local rule already decides, because it measures Jev on them. It does not send a file that you corrected. The switches for the repository, the excluded paths and the password and key check apply to it.
 
 1. Run `node workspace/doc-category-bench.js --jev`. It shows how many files it would send, about how many characters, the host, and a `--confirm` value. It sends nothing.
 2. Read which categories the labelled set cannot test. When a category has no label in the set, the result says nothing about that category.
 3. To send, run the command again with `--confirm` and the value it showed, for example `--confirm 40:372a…`. The value holds the count and the files. If the files changed, nothing is sent and you look again.
 
-It uses the key that you saved on the Validate page, or `TYPESAFE_API_KEY` in the terminal. It prints the agreement, each category, how many answers were unsure, how many files were not sent and why, and every disagreement. The labels in the set are not yet confirmed, so the result is provisional. Only one pass at a time runs for a repository. If the workspace is sending, the command stops and sends nothing.
-
-### Correct a category
-
-When a category is wrong, set the correct one. Your correction comes before all five rules.
-
-1. In the Knowledge view, press **fix** at the end of the document row.
-2. Select the category. For a `ticket`, also select the ticket kind.
-3. Press **save correction**.
-
-The category after the document name changes. Point at it: it says `decided by pm correction`. When a rule gives a different category, the text names that rule too.
-
-The workspace keeps your corrections in its runtime state directory, never in the repository. Each repository has its own corrections. A correction does not change a file. To remove a correction, press **fix** and then **clear correction**. The rules then decide again.
-
-### Write the category into the file
-
-You can also write the category into the document, as a `category:` line in its frontmatter. This is a separate step, and it is the only step here that changes a file.
-
-1. Press **fix** and select the category.
-2. Press **write it into the file**. The workspace shows the change. It does not write yet.
-3. Examine the change. Press **apply** to write it, or **cancel**.
-
-The workspace changes one `category:` line in the frontmatter block at the top of the file. For a ticket, it also changes one `ticket_kind:` line. It adds the line when there is none. No other line of the file changes.
-
-The workspace does not write when:
-
-- The file has no frontmatter block at the top. It does not add a block.
-- The frontmatter has two `category:` lines.
-- The file changed after the workspace showed you the change. Press **write it into the file** again to see the new change.
+It uses the key that you saved on the Validate page (Settings › Validate consent › Open Validate), or `TYPESAFE_API_KEY` in the terminal. It prints the agreement, each category, how many answers were unsure, how many files were not sent and why, and every disagreement. The labels in the set are not yet confirmed, so the result is provisional. Only one pass at a time runs for a repository. If the workspace is sending, the command stops and sends nothing.
 
 ## Where the map is kept