create-pmos 0.38.8 → 0.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.38.8",
+  "version": "0.39.0",
   "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → lane-fit spec → contract → build → three gates, with work-type lanes for features, research, maintenance, incidents, and content) entirely inside your own repo, with all state as git-versioned files. Includes `workflow-sweep`, which audits the state every board derives from and separates real defects from work you simply have not done. `create-pmos workspace` also installs + launches the local Terminal Workspace GUI. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@6e5901f
+kernel-source: pmos@063ee3c
 assembled: 2026-10-03
 mode: vendor

package/payload/planning/evals/eval-calibration.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Eval calibration log"
 description: "Append-only record of every PM override of an evaluator verdict."
-generated: {by: process:create-pmos, at: "2026-10-03T03:25:22Z"}
+generated: {by: process:create-pmos, at: "2026-10-03T07:05:43Z"}
 status: stable
 ---
 

package/payload/planning/okrs/health-budgets.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Health budgets"
 description: "Closed registry of health-budget anchors (D59), edited only by the PM."
-generated: {by: process:create-pmos, at: "2026-10-03T03:25:22Z"}
+generated: {by: process:create-pmos, at: "2026-10-03T07:05:43Z"}
 status: stable
 ---
 

package/payload/state/discoveries.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Discoveries and friction log"
 description: "Append-only record of what runs discovered and where the process rubbed."
-generated: {by: process:create-pmos, at: "2026-10-03T03:25:22Z"}
+generated: {by: process:create-pmos, at: "2026-10-03T07:05:43Z"}
 status: stable
 ---
 

package/workspace/README.md

@@ -46,6 +46,34 @@ npm run test:ui      # browser checks: terminal geometry, reader scroll, markdow
 ```
 </details>
 
+## Status clarity and the user guide (`status-clarity`)
+
+The initiative list can say what each status means. Choose **status**, then **what do these mean?**: one row per group with what it means, the fact it is read from, who acts, what moves it and what you can do. The text comes from `lib/status-groups.js`, the table that also files the rows, so the legend and the grouping cannot disagree.
+
+The initiative detail opens with a **status banner**: the group, why (the evidence the server derived, for example the open item in its own words), who acts, the next thing to do, and what changes the status. Next steps are split into **yours** and **mine**; each item has an `id`, an `owner` (`pm` or `agent`) and `act` (`null` for now). Hold, close, cancel and reopen are explained under the control and every change is listed. No other status can be set by hand: they are read from git and the ledgers. Acceptance is the PM's and is recorded in a session, so the banner says how and the workspace never records one.
+
+Files listed under **files from git** open in a read-only tab. A file that exists only on the initiative's branch is read from that branch through `GET /api/doc?ref=initiative/<id>` (an initiative branch only, text under 2 MB). A binary file says it cannot be previewed.
+
+The user guide is `workspace/guide/*.md`. The **guide** item in the settings and tools drawer opens its pages in a read-only tab (`GET /api/guide`). A change to `workspace/public/pm/**` must change the guide in the same pull request (a workspace CI step), and `guide.test.js` fails when a status group, a drawer item or a `pmos` command is not mentioned.
+
+## Three columns (`column-layout`)
+
+The desktop has three columns: **navigation**, **detail** and **tabs**. Navigation is the repository list with the list of the current mode under it (the initiatives of the selected repository, or memory, skills, knowledge, scheduled tasks, focus, portfolio, the guide). The repository list is capped at 42% of the height and scrolls inside its cap, so the list under it stays on screen. The detail column shows an initiative. The tabs column holds terminals, documents, conversations and guide pages and is never rebuilt by a layout change.
+
+The DOM still holds four hosts in the same order (repositories, list, detail, tabs); `placeHosts` in `public/pm/app.js` puts the list host under the repositories by grid placement. About a hundred test assertions and the phone layout depend on that order, so it is not changed. The list folds to a one-line bar, the navigation column folds to a 36px rail (the list folds with it), and the detail column folds to its own rail. Drag the navigation column's right edge to resize it (220 to 560px); a double click restores 280px. `state.js` no longer stores `col1W`; an old stored layout loads and keeps its tabs.
+
+`MODE_PLACE` in `public/pm/modes.js` is the rule for where things open, and `ROW_OPENS` says what a row in each list opens: an initiative opens in the detail column, a skill, a knowledge note or a guide page opens in a tab, and a schedule or a memory entry is used inside the list. A list or a detail kind missing from these tables fails `pm-r19-test.js`.
+
+## Next-step actions (`next-step-actions`)
+
+Each next step carries an `act` (`open`, `session`, `work`, `gate`, `lifecycle`; `lib/next-step-actions.js`). For a `work` step the PM presses **prepare**, which returns a plan and creates nothing (`POST /api/next-step/prepare`): the branch and tree (`startPreview`: an existing `initiative/<id>` worktree is reused, otherwise one is created on go), the sessions already running on the initiative, the read-only sources the chosen profile declares and that suit the step, whether the typed-judgment helper is on, the session budget, and the exact first input with its hash. **Go** (`POST /api/next-step/go`, `confirm: true`, the hash) re-prepares, refuses if anything differs from what was shown, and starts the session through `startWork` with `origin: next-step` and the prompt as `initialInput`. The socket's `start` message still cannot carry a prompt.
+
+Only the step the ladder has reached can be prepared; the build is refused until the pre-run contract is PM-approved; the contract, acceptance and open items are `gate` acts and have no start control; a stopped initiative must be reopened. The prompt states the propose-only boundary (`RULES`): commit to the local branch or write drafts; no push, pull request, send, post, ticket, acceptance, contract approval or merge. `lib/session-budget.js` limits sessions started from steps (3 at once, 8 a day, `GET`/`POST /api/next-step/settings`); sessions started by hand are never counted.
+
+`lib/judgment.js` owns the instruction that tells a session to use the Typesafe skill (off by default, per run; it needs `TYPESAFE_API_KEY` and sends the question text to an outside service) and the shape check for `JUDGMENT {json}` lines (classify, score, yes or no). The next-step routes and modules make no model or network call (the one named egress in the workspace is D79's repository validation, a separate feature).
+
+After the session ends, `GET /api/next-step/summary` returns the files the branch changed against trunk, the end of the conversation and the judgments, checked; `POST /api/next-step/review` records the PM's verdict (`accept` or `send-back` with a note). Runs and verdicts are `next-step-runs.jsonl` and `step-reviews.jsonl` in the runtime state directory. A verdict never changes the initiative's status.
+
 ## Scheduled tasks from the terminal (`schedule-cli`)
 
 `pmos schedule` and `pmos skill` talk to the running workspace server, so the terminal and the workspace share one schedule store and one validator. Every change is saved the moment the command succeeds. A refused value names what is allowed and changes nothing. With no server running the command says so and exits 1.
@@ -99,7 +127,7 @@ The three-column layout is retired. The surface is now **four collapsible panels
 **Fixture mode.** `?fixture=proto` renders the whole surface from a bundled seed file, with the server unable to read any repository — that is how the design comparison is run (`npm run test:parity`), and it is never the default.
 
 ## Artifact links are declarations, not integrations
-The PMOS server makes no outbound request and holds no credential, and the workspace makes no request you did not ask for. Its git network verbs are named and press-only: `Sync` runs `fetch`, a fast-forward or an own-commit rebase, a commit of record paths, and `push` — only when you press it, never on a timer or on load, never forced ([D70](/okf/products/pmos/adr/d70-stopped-initiatives-and-sync.md)). A web page opens in a tab only when you type or click its address, and a restored web tab loads only when you press "load this page" ([D69](/okf/products/pmos/adr/d69-web-tab.md)). Linking an artifact to an external destination therefore records a **declaration** — `{artifact_path, kind, target}` appended to `pmos/state/artifact-links.jsonl`. The sync panel renders as designed, and with no connector configured its summary line says exactly that: *no connector configured — nothing was read, and nothing will be written*, with the approval buttons disabled. A difference summary it never read would be the watermelon this repo has a word for.
+The PMOS server makes no outbound request and holds no credential, with one named exception ([D79](/okf/products/pmos/adr/d79-typesafe-validation-egress.md)): when you save a TypeSafe key and turn validation on for a repository, the **validate** page sends that repository's document text to `api.typesafe.ai`, from one module, only after you confirm the plan. With no key, nothing is sent. The key stays on this machine, is never shown again, and is never given to a terminal. The workspace makes no request you did not ask for. Its git network verbs are named and press-only: `Sync` runs `fetch`, a fast-forward or an own-commit rebase, a commit of record paths, and `push` — only when you press it, never on a timer or on load, never forced ([D70](/okf/products/pmos/adr/d70-stopped-initiatives-and-sync.md)). A web page opens in a tab only when you type or click its address, and a restored web tab loads only when you press "load this page" ([D69](/okf/products/pmos/adr/d69-web-tab.md)). Linking an artifact to an external destination therefore records a **declaration** — `{artifact_path, kind, target}` appended to `pmos/state/artifact-links.jsonl`. The sync panel renders as designed, and with no connector configured its summary line says exactly that: *no connector configured — nothing was read, and nothing will be written*, with the approval buttons disabled. A difference summary it never read would be the watermelon this repo has a word for.
 
 ## The gates are real, never automatic (R5)
 `approve` / `return` / `accept` write the PMOS file-mode vocabulary to `acceptances.jsonl` and clear the matching needs entry — only ever on your click.

package/workspace/guide/index.md

@@ -0,0 +1,38 @@
+---
+type: Guide
+title: "Guide: start here"
+timestamp: 2026-10-03
+---
+
+# Guide: start here
+
+This guide describes the PMOS workspace as it works today. It ships with the app. When a change alters how the workspace looks or behaves, the same change updates this guide.
+
+## The screen
+
+The workspace has three columns. [Layout](layout.md) explains where things open.
+
+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.
+
+## The settings and tools drawer
+
+| Item | What it opens |
+|---|---|
+| 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 one repository's documents with TypeSafe. It 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. |
+
+## Where to read next
+
+- [Layout](layout.md): the three columns 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.
+- [Scheduled tasks and the command line](scheduled-tasks-and-cli.md): how to make, edit and run scheduled tasks.
+- [Validate a repository with TypeSafe](validate-with-typesafe.md): what leaves your machine, how to run a validation, and how to read the findings.

package/workspace/guide/initiatives-and-next-steps.md

@@ -0,0 +1,72 @@
+---
+type: Guide
+title: "Guide: initiatives and next steps"
+timestamp: 2026-10-03
+---
+
+# Guide: initiatives and next steps
+
+Select an initiative in the list. The detail opens in the detail column.
+
+## What the detail shows, top to bottom
+
+1. **Status.** The status, why it has that status, who acts now, the next thing to do, and when the status changes. If the status is Needs you, each open item is listed in its own words. If the status cannot be read, the detail says so and shows no status.
+2. **Lifecycle control.** Hold, close, cancel or reopen. Beneath it, the history of every change.
+3. **Next steps to done.** Everything between now and acceptance, in order. See below.
+4. **Phases and links.** The workflow phases and the external links.
+5. **Artifacts.** Documents, conversations and files.
+
+## Next steps
+
+The list comes from the workflow ladder, the ledgers and the running sessions. The workspace does not write it with a model. Every step names the fact it came from.
+
+The list has two parts:
+
+- **Yours.** Steps only you can do. Acceptance, approval of the contract and answers to open items belong here.
+- **Mine.** Steps the agent does.
+
+The numbers run along the whole path. The step marked **next** is the one the workflow names first. A stopped initiative lists a reopen step first. An accepted initiative has none.
+
+## Acting on a step
+
+Each step says what you can do with it. The control sits under the step.
+
+| Act | What it is | The control |
+|---|---|---|
+| `work` | An agent session can do this step. | **prepare**, then **go** |
+| `open` | The step is yours, and it points at a file you should read. | **open** the file |
+| `session` | A session is already running on it. | **switch to it** |
+| `gate` | The step is yours alone: accepting the initiative, approving the contract, answering an open item. | Words only. There is no start button. |
+| `lifecycle` | The initiative is stopped. | **reopen** |
+
+### Prepare, then go
+
+**Prepare** shows a plan and starts nothing. The plan names the branch and the folder, says whether the initiative's branch already exists (it is reused) or would be created, lists the sessions already running on the initiative, names the read-only sources the session may use, and shows the budget. It also shows the exact first input the session would receive. Preparing creates no branch, folder or session.
+
+**Go** starts one session with exactly that input. The workspace refuses if the plan changed after you read it. In that case, prepare again.
+
+A step the workflow has not reached cannot be prepared. The build cannot be prepared until you approve the contract. A stopped initiative must be reopened first. The workspace says which step comes first.
+
+### What the session may do
+
+The session proposes. It commits to the local initiative branch or writes draft files. It does not push, open a pull request, send or post anything, create a ticket, record an acceptance, approve a contract or merge. Those are yours.
+
+### The budget
+
+At most 3 prepared sessions run at once and 8 start each day. Go refuses a start over either limit and says the number. Sessions you start by hand are never counted or blocked. Change the limits with `POST /api/next-step/settings`.
+
+### Sources and the typed judgment option
+
+Choose a profile in the plan. The session may read only the sources that profile declares and that suit the step: Wispr Flow notes, Gmail, Google Calendar, Confluence, Jira and Slack. They are read-only.
+
+You can turn on the Typesafe skill for a run. It helps the session categorise, score and decide yes or no with a typed answer. It sends the question text to an outside service and needs `TYPESAFE_API_KEY` in the session. It is off by default. The session prints each answer as a `JUDGMENT` line, and the review checks its shape.
+
+### Review
+
+After the session ends, the step offers **review what it did**. The review lists the files the branch changed against trunk, shows the end of the conversation, and lists any judgments the session reported, with those that failed the shape check marked. Then choose **accept the step** or **send it back**. A send-back needs a note. Your verdict is recorded in the runtime state folder. Accepting a step does not accept the initiative. Acceptance stays at the Acceptance Gate.
+
+## Artifacts
+
+- **Documents** open in a tab. You can edit them.
+- **Conversations** are sessions bound to the initiative. A conversation is saved when its session ends. It opens read-only. It stays on this computer, in the runtime state folder. It is not in the repository.
+- **Files from git** are the files changed for the initiative. They open read-only in a tab. A file that exists only on the initiative branch opens from that branch. A file that cannot be previewed, such as a binary file, says so.

package/workspace/guide/layout.md

@@ -0,0 +1,59 @@
+---
+type: Guide
+title: "Guide: layout"
+timestamp: 2026-10-03
+---
+
+# Guide: layout
+
+The workspace has three columns. They are, from left to right, navigation, detail and tabs.
+
+## Navigation
+
+The first column holds the list of repositories. Under it is the list for the current mode. When you choose a repository, its initiatives appear there. When you choose an item in the settings and tools drawer, its list replaces the initiatives. Choose a repository again to return to its initiatives.
+
+If you have many repositories, the repository list scrolls inside its own space. The list under it stays on screen.
+
+Drag the right edge of the column to change its width. Double-click the edge to restore the default width.
+
+## Detail
+
+The second column shows one item in full. Choose an initiative, a skill, a schedule or a memory item, and its detail opens here.
+
+## Tabs
+
+The third column holds your terminals, documents, conversations and guide pages. Folding or resizing the other columns does not touch your terminals.
+
+## The rule for where things open
+
+A list or a directory opens in the navigation column, under the repository list. A detail opens in the detail column. A file-like row opens in a tab, as any document does.
+
+| Item | Kind | Opens in |
+|---|---|---|
+| Initiatives | list | navigation |
+| Memory | list | navigation |
+| Knowledge | list | navigation |
+| Portfolio | list | navigation |
+| Guide | list | navigation |
+| Validate | list | navigation |
+| Focus | list | navigation |
+| Skills | list | navigation |
+| Scheduled tasks | list | navigation |
+
+What a row in a list opens:
+
+- A row in Initiatives, Portfolio or Focus opens the initiative in the detail column.
+- A row in Skills, Knowledge, Guide or Validate opens the file in a tab, beside your terminals.
+- Scheduled tasks and Memory are used inside the list. They have no separate detail.
+
+## Folding
+
+- Choose the arrow in the header of the list to fold it to one line under the repositories. Choose the line to open it again.
+- Fold the navigation column to a thin strip. The list folds with it. Choose the strip to open it again.
+- Fold the detail column to its strip in the same way.
+
+The workspace remembers which columns are open and how wide the navigation column is.
+
+## On a phone
+
+A phone shows one panel at a time. The bottom bar moves between them.

package/workspace/guide/scheduled-tasks-and-cli.md

@@ -0,0 +1,41 @@
+---
+type: Guide
+title: "Guide: scheduled tasks and the command line"
+timestamp: 2026-10-03
+---
+
+# Guide: scheduled tasks and the command line
+
+A scheduled task runs a skill at a set time. The workspace starts a terminal session in the repository and types the skill into it.
+
+## Limits
+
+A schedule fires only while the workspace server runs. If the server is stopped, the workspace skips the missed slot. It does not catch up later. A one-time task has a 15-minute grace window.
+
+## The commands
+
+The commands talk to the running server. A change is saved when the command succeeds. A refused value names what is allowed and changes nothing. If no server runs, the command says so and exits with code 1.
+
+- `pmos schedule list` shows the schedules. Add `--all` for every repository.
+- `pmos schedule show <id|name>` shows one schedule, its next run, its last run and its status.
+- `pmos schedule add` makes a schedule. Use `--skill` and `--cadence`. Add `--from-session` or `--from-file` to make a new user skill from your work and schedule it.
+- `pmos schedule edit <id|name>` changes any field.
+- `pmos schedule run <id|name>` runs it now.
+- `pmos schedule enable <id|name>` and `pmos schedule disable <id|name>` turn it on and off.
+- `pmos schedule rm <id|name>` deletes it.
+- `pmos skill list` shows the skills.
+- `pmos skill show <name>` shows one skill.
+- `pmos skill new` makes a user skill.
+- `pmos skill edit <name> --file F` replaces a user skill's text.
+- `pmos skill copy <name>` makes an editable copy of a built-in skill.
+
+## The fields
+
+| Field | Meaning |
+|---|---|
+| `--cadence`, `--day`, `--day-of-month`, `--time`, `--date` | When it runs. Times are local to the computer. |
+| `--until`, `--max-runs` | When it stops. The schedule turns itself off when either is reached and records why. `none` clears one. |
+| `--args` | Extra instructions added to the skill. |
+| `--tier`, `--profile` | How it runs. |
+
+A skill's text never starts a session with `/`, because Claude Code would read that as a command. The workspace puts a short sentence before it.

package/workspace/guide/statuses.md

@@ -0,0 +1,53 @@
+---
+type: Guide
+title: "Guide: statuses"
+timestamp: 2026-10-03
+---
+
+# Guide: statuses
+
+Nobody types a status. The workspace works it out again each time you look. It reads the ledgers in the repository and git. Because of this, a status cannot become stale. It also means you cannot edit most statuses by hand.
+
+## The nine statuses
+
+| Status | Who acts | What it means |
+|---|---|---|
+| Needs you | You | Work is stopped on a decision or an answer only you can give. |
+| In progress | The agent | An agent run is logged and nothing is merged yet. |
+| Planning | The agent | The initiative is recorded and no run has started. |
+| Awaiting acceptance | You | The work is delivered. It waits for your acceptance. |
+| Accepted | Nobody | You accepted it. Nothing remains. |
+| On hold | You | You paused it. It is off the board. |
+| Closed | You | You closed it. It is off the board. |
+| Cancelled | You | You cancelled it. It is off the board. |
+| Unknown | Nobody | The status could not be worked out, so none is shown. |
+
+The first four are the active statuses. Choose **active only** in the list to hide the others.
+
+To read the same table in the app, choose **status** in the list, then **what do these mean?**. The app shows, for each status, the fact it is read from, what moves an initiative out of it, and what you can do.
+
+## Where each status comes from
+
+- **Needs you** comes from your latest acceptance row (a return), or from an open item in the needs queue that names the initiative.
+- **In progress** comes from `agent-runs.jsonl`: at least one run, and no merged `initiative/<id>` branch.
+- **Planning** means the record exists and `agent-runs.jsonl` has no run for it.
+- **Awaiting acceptance** comes from git: an `initiative/<id>` branch was merged, or a trunk commit names the initiative and changes build files. No acceptance row exists yet.
+- **Accepted** comes from your latest acceptance row.
+- **On hold**, **Closed** and **Cancelled** come from your latest line in `lifecycle.jsonl`.
+- **Unknown** appears when the trunk history or a ledger cannot be read. The detail gives the reason.
+
+## What you can change by hand
+
+You can hold, close, cancel or reopen an initiative. Each action writes one line to `lifecycle.jsonl` with your reason. A held, closed or cancelled initiative leaves the board and stops gating. Reopen puts it back. The detail lists every change.
+
+You cannot set any other status. To move an initiative from Awaiting acceptance to Accepted, record an acceptance. Acceptance is yours and nobody can do it for you. Tell the session that holds the initiative to record it, or run `scripts/record-acceptance.js`. The workspace never records an acceptance for you.
+
+## How a status changes
+
+A status changes when a fact changes:
+
+1. An agent logs its first run: Planning becomes In progress.
+2. A branch is merged: In progress becomes Awaiting acceptance.
+3. You return the work at acceptance: it becomes Needs you.
+4. You accept: it becomes Accepted.
+5. You hold, close or cancel: it moves to that status, whatever it was. Reopen returns it to the status its facts give.

package/workspace/guide/validate-with-typesafe.md

@@ -0,0 +1,47 @@
+---
+type: Guide
+title: "Guide: validate a repository with TypeSafe"
+timestamp: 2026-10-03
+---
+
+# Guide: validate a repository with TypeSafe
+
+The validate item checks the documents of one repository. It looks for documents that are unreliable, that disagree with each other, or that are out of date. It uses TypeSafe's Jev model for the checks that need judgement.
+
+## What leaves your machine
+
+Validation is off until you turn it on. Until then, the workspace sends nothing.
+
+When you turn it on, the workspace sends document text to `api.typesafe.ai`. It sends nothing else. It does not send binary files. It does not send a document that you excluded. It does not send a document that matches a credential pattern, such as a private key or a token. It lists that document as withheld.
+
+The workspace reads the TypeSafe key only on this machine. After you save the key, the screen does not show it again. The workspace does not give the key to a terminal or to an agent.
+
+## Set it up
+
+1. Open **validate** in the settings and tools drawer.
+2. Under **TypeSafe key**, paste the key and press **save**. Press **remove** to delete a saved key.
+3. Under **this repository**, press **turn on**. This choice applies to the selected repository only.
+4. Enter the paths that the workspace must never send, one for each line. A path ends with `/` for a folder. A `*` matches any characters. Press **save excluded paths**.
+
+## Run a validation
+
+1. Press **show what would be sent**. The workspace shows the number of requests, the number of characters, and the documents it withholds. It sends nothing at this step.
+2. Press **confirm and send**. If the repository changed since the plan, the workspace refuses and asks you to read the plan again.
+
+The workspace does the local checks first. It finds links that point to a file that does not exist. It finds documents whose `stale_after` date has passed. It reads the workflow sweep. These checks send nothing.
+
+Then it asks Jev these questions about each document: Does the document contradict itself? Can a reader tell what it is for? Is the writing succinct? For an old document, it also asks if the document is out of date. For documents that link to each other, it asks if they state conflicting facts. For a document that names its sources, it asks if the source supports the claims.
+
+## Read the findings
+
+A finding has a severity, a rule, a confidence and the files it concerns. Press a finding to open the first file.
+
+- **Confidence** shows how sure the answer is. For a yes-or-no question, the workspace derives it from the probability that Jev returns. A finding with low confidence says **for your judgement**.
+- **Coverage** is the first line under **findings**. Read it first. It shows how many requests Jev answered, and how many documents were withheld, too large, excluded or failed. A short list of findings does not mean the repository is clean.
+- A finding is advice. It does not change a file. It is not an acceptance. You decide what to do.
+
+The workspace keeps the findings in `validation-findings.jsonl`. In a PMOS repository, this file is in the runs folder. In another repository, it is in the runtime folder of this machine. The file holds the answers. It does not hold document text.
+
+## Limits
+
+Jev's verdicts are advice until a person compares them with real decisions. The workspace does not yet measure how often Jev is right. Treat a high-confidence finding as a reason to look, not as proof.

package/workspace/lib/initiative-files.js

@@ -12,6 +12,7 @@
 const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
+const { previewKind } = require('./preview-kind');
 
 const MAX_FILES = 200;
 const cache = new Map();   // root|id → {head, at, result}
@@ -86,13 +87,13 @@ function filesFor(root, id, opts) {
     }
     // What still exists: the checked-out tree plus the initiative's own branch tip, so a file that lives only on an
     // unmerged branch is listed, and a file deleted since is not. `ls-tree` once per ref, never one spawn per file.
-    const present = new Set();
+    const present = new Set(); const onHead = new Set();
     let treeOk = false;
     for (const ref of ['HEAD', branch].filter(Boolean)) {
       const t = git(root, ['ls-tree', '-r', '--name-only', '-z', ref]);
-      if (t.ok) { treeOk = true; for (const f of t.out.split('\0')) if (f) present.add(f); }
+      if (t.ok) { treeOk = true; for (const f of t.out.split('\0')) if (f) { present.add(f); if (ref === 'HEAD') onHead.add(f); } }
     }
-    base = { commits, via, present: treeOk ? present : null };
+    base = { commits, via, branch: branch || null, present: treeOk ? present : null, onHead: treeOk ? onHead : null };
     cache.set(key, { head, at: Date.now(), result: base });
   }
   const seen = new Map();
@@ -103,9 +104,31 @@ function filesFor(root, id, opts) {
   }
   const exists = (f) => { if (base.present) return base.present.has(f); try { return fs.existsSync(path.join(root, f)); } catch { return false; } };
   const items = [...seen.values()].filter((x) => exists(x.path))
-    .map((x) => ({ path: x.path, group: groupOf(x.path), commits: x.shas.length, last: x.shas[0].slice(0, 7) }))
+    // `where` says which copy a reader gets: `head` is in the checked-out tree; `branch` exists only on the
+    // initiative's own branch tip, so it has to be read from git, not from the working tree.
+    .map((x) => ({ path: x.path, group: groupOf(x.path), commits: x.shas.length, last: x.shas[0].slice(0, 7),
+      where: base.onHead ? (base.onHead.has(x.path) ? 'head' : 'branch') : 'head', kind: previewKind(x.path) }))
     .sort((a, b) => (a.group + a.path).localeCompare(b.group + b.path));
-  return { ok: true, total: items.length, truncated: items.length > MAX_FILES, items: items.slice(0, MAX_FILES), via: base.via };
+  return { ok: true, total: items.length, truncated: items.length > MAX_FILES, items: items.slice(0, MAX_FILES), via: base.via, branch: base.branch };
 }
 
-module.exports = { filesFor, groupOf, namesId };
+/**
+ * Read one file as it is at `ref` (the initiative's own branch), for a file that is not in the checked-out tree.
+ * Only `initiative/<id>` and `origin/initiative/<id>` are readable, and only text under 2 MB; anything else is a
+ * reason, never a guess.
+ */
+const MAX_BYTES = 2 * 1024 * 1024;
+function readAtRef(root, ref, rel) {
+  if (!/^(origin\/)?initiative\/[A-Za-z0-9][\w.-]*$/.test(String(ref || ''))) return { ok: false, reason: 'only an initiative branch can be read this way' };
+  const p = String(rel || '');
+  if (!p || p.startsWith('/') || p.split('/').some((seg) => seg === '..' || seg === '')) return { ok: false, reason: 'not a path inside the repository' };
+  const kind = previewKind(p);
+  if (kind !== 'markdown' && kind !== 'text' && kind !== 'html') return { ok: false, reason: 'this kind of file cannot be previewed from a branch' };
+  const r = spawnSync('git', ['-C', root, 'show', ref + ':' + p], { encoding: 'buffer', maxBuffer: MAX_BYTES + 1024, timeout: 20000 });
+  if (r.error || r.status !== 0) return { ok: false, reason: 'git has no such file on ' + ref };
+  if (r.stdout.length > MAX_BYTES) return { ok: false, reason: 'the file is larger than 2 MB' };
+  if (r.stdout.indexOf(0) !== -1) return { ok: false, reason: 'the file is binary' };
+  return { ok: true, kind, text: r.stdout.toString('utf8') };
+}
+
+module.exports = { filesFor, groupOf, namesId, readAtRef };

package/workspace/lib/judgment.js

@@ -0,0 +1,65 @@
+'use strict';
+/* judgment.js — typed answers to classify, score and yes-or-no questions.
+ *
+ * The workspace makes no network call and runs no model. When the PM turns judgment on for a run, the PROMPT tells the
+ * session to use the Typesafe skill (https://docs.typesafe.ai/agent-skill; needs TYPESAFE_API_KEY) for these three kinds
+ * of decision, and to print each answer on one line as `JUDGMENT {json}`. This module owns the fragment that says so and
+ * the check of the shape that comes back. An answer in any other shape is rejected, never repaired.
+ *
+ * Off, or without a key, the session is asked for the SAME shape from plain judgment, and the fragment says so — the
+ * PM never gets a different answer format depending on a setting.
+ */
+const KINDS = ['classify', 'score', 'yesno'];
+const LINE = /^JUDGMENT\s+(\{.*\})\s*$/;
+const clip = (s, n) => String(s).slice(0, n);
+
+function fragment(on) {
+  const shape = [
+    'When a step needs you to categorise, score, or decide yes or no, give the answer on its own line, exactly like this, one JSON object per line:',
+    // The examples start with "e.g." so a transcript that echoes this prompt is never read as an answer.
+    '  e.g. JUDGMENT {"kind":"classify","question":"…","label":"<one of your labels>","labels":["…","…"],"confidence":0.0-1.0}',
+    '  e.g. JUDGMENT {"kind":"score","question":"…","score":0.0-1.0,"reason":"…"}',
+    '  e.g. JUDGMENT {"kind":"yesno","question":"…","answer":true|false,"confidence":0.0-1.0,"reason":"…"}',
+  ];
+  if (on) return ['Use the Typesafe skill (/typesafe:typesafe-ai) for those decisions. The question text you send leaves this machine for the Typesafe service and needs TYPESAFE_API_KEY. If the skill or the key is missing, say so and decide yourself.', ...shape].join('\n');
+  return ['Decide those yourself; no outside service is used for this run.', ...shape].join('\n');
+}
+
+const unit = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= 1;
+
+/** @returns {{ok:true,value:object}|{ok:false,error:string}} */
+function validate(o) {
+  if (!o || typeof o !== 'object' || Array.isArray(o)) return { ok: false, error: 'not an object' };
+  if (!KINDS.includes(o.kind)) return { ok: false, error: `kind must be one of ${KINDS.join(', ')}` };
+  if (typeof o.question !== 'string' || !o.question.trim()) return { ok: false, error: 'question is required' };
+  const base = { kind: o.kind, question: clip(o.question.trim(), 300) };
+  if (o.kind === 'classify') {
+    if (!Array.isArray(o.labels) || o.labels.length < 2 || o.labels.some((l) => typeof l !== 'string' || !l.trim())) return { ok: false, error: 'labels must be a list of at least two strings' };
+    if (typeof o.label !== 'string' || !o.labels.includes(o.label)) return { ok: false, error: 'label must be one of labels' };
+    if (!unit(o.confidence)) return { ok: false, error: 'confidence must be a number from 0 to 1' };
+    return { ok: true, value: { ...base, label: o.label, labels: o.labels.map((l) => clip(l, 60)), confidence: o.confidence } };
+  }
+  if (o.kind === 'score') {
+    if (!unit(o.score)) return { ok: false, error: 'score must be a number from 0 to 1' };
+    if (typeof o.reason !== 'string' || !o.reason.trim()) return { ok: false, error: 'reason is required' };
+    return { ok: true, value: { ...base, score: o.score, reason: clip(o.reason.trim(), 300) } };
+  }
+  if (typeof o.answer !== 'boolean') return { ok: false, error: 'answer must be true or false' };
+  if (!unit(o.confidence)) return { ok: false, error: 'confidence must be a number from 0 to 1' };
+  return { ok: true, value: { ...base, answer: o.answer, confidence: o.confidence, ...(typeof o.reason === 'string' ? { reason: clip(o.reason.trim(), 300) } : {}) } };
+}
+
+/** Every `JUDGMENT {json}` line in a transcript, checked. Returns { valid:[…], invalid:[{line,error}] }. */
+function extract(text) {
+  const valid = []; const invalid = [];
+  for (const raw of String(text == null ? '' : text).split(/\r?\n/)) {
+    const m = LINE.exec(raw.trim());
+    if (!m) continue;
+    let o; try { o = JSON.parse(m[1]); } catch { invalid.push({ line: clip(raw.trim(), 200), error: 'not valid JSON' }); continue; }
+    const v = validate(o);
+    if (v.ok) valid.push(v.value); else invalid.push({ line: clip(raw.trim(), 200), error: v.error });
+  }
+  return { valid, invalid };
+}
+
+module.exports = { KINDS, fragment, validate, extract };

package/workspace/lib/mobile-nav.js

@@ -49,7 +49,7 @@
 // silently renders a key where a title belongs.
 const MODE_TITLE = {
   product: 'initiatives', scheduled: 'scheduled tasks', workflow: 'workflows', skills: 'skills',
-  knowledge: 'knowledge', agent: 'agents', memory: 'memory',
+  knowledge: 'knowledge', agent: 'agents', memory: 'memory', portfolio: 'portfolio', guide: 'guide',
 };
 // What a DETAIL screen is called. It moved here with the reducer, for the same reason.
 // The second block is the four-panel surface's `detail.kind` vocabulary (pm/app.js's DETAIL_TITLE).