create-pmos 0.34.0 → 0.37.0

package/payload/skills-native/evaluator/SKILL.md

@@ -13,7 +13,7 @@ the **interactive agent runtime** — any capable coding agent; heavy judgment b
 an Edge Function ([D09](/DECISIONS.md)/[D34](/DECISIONS.md), amended 2026-07-23). PMOS-self runs it in
 Claude Code, but the runtime is not Claude-specific.
 
-> **Format:** three-level progressive disclosure ([SKILL-FORMAT](/skills/core/SKILL-FORMAT.md)). Level 1
+> **Format:** three-level progressive disclosure ([SKILL-FORMAT](/skills/SKILL-FORMAT.md)). Level 1
 > frontmatter above is the trigger. This Level 2 body is the full procedure.
 
 ## Non-negotiable stance

package/payload/skills-native/explain-run/SKILL.md

@@ -23,7 +23,7 @@ accrues **cognitive debt** and makes the non-delegable Acceptance Gate ([D12](/D
 *formally* human — the PM as their own [watermelon](/okf/core/concepts/watermelon-flag.md)
 ([skills-and-understanding](/planning/research/skills-and-understanding-research.md)).
 
-> **Format:** three-level progressive disclosure ([SKILL-FORMAT](/skills/core/SKILL-FORMAT.md)).
+> **Format:** three-level progressive disclosure ([SKILL-FORMAT](/skills/SKILL-FORMAT.md)).
 > Level 1 frontmatter above is the trigger; this Level 2 body is the full procedure.
 
 ## Non-negotiable stance

package/payload/skills-native/explain-surface/SKILL.md

@@ -19,13 +19,13 @@ and it costs more there. A misread at acceptance costs one rejected run; a misre
 inherited by the contract, the build, the rubric and the evaluator, and **every gate passes over it**.
 A [watermelon](/okf/core/concepts/watermelon-flag.md) planted at the root.
 
-The gap is sharpest in the [prd skill](/skills/core/prd.skill)'s own grilling rule — *"if a fact can
+The gap is sharpest in the [prd skill](/skills/prd.skill)'s own grilling rule — *"if a fact can
 be found by exploring the environment, look it up rather than asking."* That rule is right, and its
 side effect is that **the agent acquires the understanding and the PM does not.**
 
-> **Format:** three-level progressive disclosure ([SKILL-FORMAT](/skills/core/SKILL-FORMAT.md)).
+> **Format:** three-level progressive disclosure ([SKILL-FORMAT](/skills/SKILL-FORMAT.md)).
 > L1 above is the trigger; this L2 body is the procedure.
-> **Not [`ingest-repo`](/build-skills/ingest-repo.skill).** That builds an *agent-facing*,
+> **Not [`ingest-repo`](/skills/ingest-repo.skill).** That builds an *agent-facing*,
 > whole-repo, one-time OKF reference layer — a capability ledger is a lookup table, not a teaching
 > artifact. This is PM-facing, one region, per-initiative, and pedagogically ordered. Read whatever
 > layer `ingest-repo` produced as substrate; **treat the code as ground truth.**
@@ -76,8 +76,8 @@ explainer output decayed to *never* by the second run.
 
    | Subject shape | Organise by | Reuse |
    |---|---|---|
-   | A **user-facing surface** | the surface: views, states, controls, current copy | [design-reconcile](/skills/core/design-reconcile.skill)'s capability ledger §A–D — every control **backed vs. watermelon** — and the product's design system ([D38](/DECISIONS.md), D60(c)) |
-   | A **subsystem / flow** | execution and logical flow, never file order | the [explain-run](/build-skills/explain-run.skill) convention |
+   | A **user-facing surface** | the surface: views, states, controls, current copy | [design-reconcile](/skills/design-reconcile.skill)'s capability ledger §A–D — every control **backed vs. watermelon** — and the product's design system ([D38](/DECISIONS.md), D60(c)) |
+   | A **subsystem / flow** | execution and logical flow, never file order | the [explain-run](/skills/explain-run.skill) convention |
    | A **data model** | entities, their invariants, what a migration must preserve | `ingest-repo`'s per-table `Reference` docs |
    | A **gate / policy surface** | the decision it makes, its fail-closed behaviour, its escape hatches | the gate's scripts + the decisions locking it |
    | A **harness surface** (skill, protocol) | trigger → procedure → stance, and what depends on it | SKILL-FORMAT's three levels |
@@ -96,7 +96,7 @@ explainer output decayed to *never* by the second run.
    - **Constraints** — what will **bite a change here**: coupling, invariants, gates, migrations,
      backfill, fail-closed behaviour. The cheapest possible place to learn these.
    - **Open questions** — what you **could not determine from the code**. Genuine unknowns, never
-     rhetorical ones. This section feeds the [prd skill](/skills/core/prd.skill)'s grilling directly
+     rhetorical ones. This section feeds the [prd skill](/skills/prd.skill)'s grilling directly
      and is the honest alternative to a confident guess.
    - **Quiz** — five questions (rules below), then a `---` divider, then **Answers**.
 4. **Force counterfactuals in the BODY, not only in the quiz.** As you walk the region, repeatedly

package/payload/skills-native/harness-refine/SKILL.md

@@ -83,7 +83,7 @@ field's "agents improving their own tools" loop while staying at the **L3 ceilin
 - The sibling detect→draft→PR loop: [okf-author](/build-skills/okf-author.skill),
   [D42](/okf/products/pmos/adr/d42-okf-author-on-demand.md).
 - The evidence surfaces: recurring friction themes and self-reported context pressure, read from
-  file-mode state ([discoveries.md](/discoveries.md) and `runs.jsonl`; the hosted
+  file-mode state ([discoveries.md](/state/discoveries.md) and `runs.jsonl`; the hosted
   `v_friction_recurrence` / `v_context_budget` views went with the backend in D66) plus
   [eval-calibration.md](/planning/evals/eval-calibration.md).
 - The cadence it serves: [D23](/okf/products/pmos/adr/d23-quarterly-cadence.md) (harness-assumption

package/payload/skills-native/ingest-repo/SKILL.md

@@ -19,7 +19,7 @@ the stack, assuming wrong, producing work the PM must heavily correct — the no
 ingest-repo goes **code → what the product *is***. It emits a **draft** OKF
 reference layer + a repo registration and then **stops for PM approval**.
 
-> **Format:** three-level progressive disclosure ([SKILL-FORMAT](/skills/core/SKILL-FORMAT.md)). L1
+> **Format:** three-level progressive disclosure ([SKILL-FORMAT](/skills/SKILL-FORMAT.md)). L1
 > frontmatter above is the trigger; this L2 body is the full procedure.
 > **Where it runs:** in **the interactive agent runtime** (any capable coding agent; PMOS-self uses
 > Claude Code), in the tenant's own conversation, read-only — never a server-side scanner
@@ -35,7 +35,7 @@ reference layer + a repo registration and then **stops for PM approval**.
   var *names* (`.env.example`, config keys). **Secret-scan the repo content AND git history** (real
   repos leak keys in committed code/history); if a secret value is found, **never** place it in a doc,
   a log, or the registry — note only that a leak exists and where, by path, so the PM can rotate it.
-- **Default-to-refute on capability** (the [design-reconcile](/skills/core/design-reconcile.skill)
+- **Default-to-refute on capability** (the [design-reconcile](/skills/design-reconcile.skill)
   stance applied to code): a control/route is **watermelon** until a concrete backend read/write path
   is found in the code. Unbacked controls land in **§D**, not invented as capability.
 - **Everything is a DRAFT ([D37](/okf/products/pmos/adr/d37-tenant-okf-db-native.md)/[D12](/okf/products/pmos/adr/d12-three-tier-eval-gate.md)).**
@@ -67,7 +67,7 @@ reference layer + a repo registration and then **stops for PM approval**.
    **no** value; record only "possible secret at `<path>`" for the PM.
 4. **Emit the reference layer** — via `save_okf_doc(..., status:'draft', product_slug:<slug>)`,
    namespaced `products/<slug>/...`, **each body carrying situating context + the exact repo path(s)**
-   it was derived from (the [source-to-concept](/skills/core/source-to-concept.skill) rule + the
+   it was derived from (the [source-to-concept](/skills/source-to-concept.skill) rule + the
    analyze-product-infra cited-line bar, applied to code). Minimum six kinds:
 
    | Doc | OKF `type` | id (under `products/<slug>/`) | derived from |
@@ -80,7 +80,7 @@ reference layer + a repo registration and then **stops for PM approval**.
    | ADR seed(s) | `ADR` | `adr/<slug>-<n>-<topic>` | README / ADRs / commit history |
 
 5. **Bootstrap the per-tenant capability ledger** (the artifact
-   [design-reconcile](/skills/core/design-reconcile.skill) consumes, [D50](/okf/products/pmos/adr/d50-design-loop-product-scoped.md)
+   [design-reconcile](/skills/design-reconcile.skill) consumes, [D50](/okf/products/pmos/adr/d50-design-loop-product-scoped.md)
    pattern — generic method, per-tenant instance). Classify **every** user-facing control/route into
    exactly one bucket; each §A/§B entry **names the concrete read/write path** in the code:
    - **§A — read-backed:** maps to a real backend read (query/endpoint) — cite it.
@@ -113,8 +113,8 @@ reference layer + a repo registration and then **stops for PM approval**.
   approve them in PR review — the file-mode form of draft→approved. (D37's database-native tenant OKF
   and its `save_okf_doc` tool were retired by [D66](/DECISIONS.md).)
 - The ledger method: [design-loop concept](/okf/core/concepts/design-loop.md),
-  [design-reconcile](/skills/core/design-reconcile.skill), [watermelon-flag](/okf/core/concepts/watermelon-flag.md).
-- Extraction discipline: [source-to-concept](/skills/core/source-to-concept.skill).
+  [design-reconcile](/skills/design-reconcile.skill), [watermelon-flag](/okf/core/concepts/watermelon-flag.md).
+- Extraction discipline: [source-to-concept](/skills/source-to-concept.skill).
 - Scan location: [D51](/okf/products/pmos/adr/d51-scan-location.md). There is no longer a central
   registry to register into — the hosted `product_repos` table and `register_product_repo` went with
   the backend (D66); the product repo that carries the kit IS the registration.

package/payload/skills-native/okr/SKILL.md

@@ -17,14 +17,14 @@ measurable key results, structured as a tree that initiatives and agent runs lad
 operationalizes the [okr-tree](/okf/core/concepts/okr-tree.md) concept.
 
 > **Format note:** three-level progressive disclosure
-> ([SKILL-FORMAT](/skills/core/SKILL-FORMAT.md)). Level 1 above is the trigger; this body is the
+> ([SKILL-FORMAT](/skills/SKILL-FORMAT.md)). Level 1 above is the trigger; this body is the
 > procedure; rare variants go to Level 3 sub-files.
 
 ## When to use vs. not
 
 - **Use** to set strategy for a planning period, or to re-anchor an initiative that has drifted from
   its parent KR.
-- **Do not use** to spec a single piece of work — that is the [PRD skill](/skills/core/prd.skill).
+- **Do not use** to spec a single piece of work — that is the [PRD skill](/skills/prd.skill).
   OKRs sit one level above initiatives.
 
 ## Procedure

package/payload/skills-native/pmos-router/SKILL.md

@@ -20,7 +20,7 @@ whose pieces half-existed). This skill performs the mapping. **It decides nothin
 lanes and gates that already exist; where it and an authority disagree, the authority wins and the
 router is the bug (fix it via the weekly harness scan).
 
-> **Format note:** three-level progressive disclosure ([SKILL-FORMAT](/skills/core/SKILL-FORMAT.md)).
+> **Format note:** three-level progressive disclosure ([SKILL-FORMAT](/skills/SKILL-FORMAT.md)).
 > Sources of truth: the AGENTS.md lane list, the initiative gate (PMOS-self: `.github/scripts/initiative-gate.sh`; a vendored kit: `pmos/scripts/gate-initiative.sh`), D56/D58/D60.
 
 ## Step 0 — three checks before any route
@@ -28,7 +28,7 @@ router is the bug (fix it via the weekly harness scan).
 1. **Sharpness (the fog/ticket test):** *can the PM state the question or idea precisely now — not
    answer it, state it?* If not, it is **fog**: not ready for intake. Name what would sharpen it
    (a conversation, a datum, a spike) and stop — do not open an initiative to hold fog.
-2. **Prior rejection:** check [planning/out-of-scope/](/planning/out-of-scope/README.md) for the
+2. **Prior rejection:** check [planning/out-of-scope/](/README.md) for the
    concept. If a file exists, **read it first** and surface it to the PM — the concept returns only
    if the PM overrides the recorded reasoning, and the file is updated either way.
 3. **The specimen test — ASK it, do not wait to be told** (D60 as amended 2026-07-24):
@@ -48,7 +48,7 @@ router is the bug (fix it via the weekly harness scan).
 
    > **Would specifying this honestly require reading code that already exists?**
 
-   Yes → an [explain-surface](/build-skills/explain-surface.skill) pass runs **first**, before the
+   Yes → an [explain-surface](/skills/explain-surface.skill) pass runs **first**, before the
    spike brief / prototype brief / PRD is authored, in a fresh context. Greenfield → skip it. This is
    standard, not optional: the PRD skill's own rule ("look it up rather than asking") means the
    *agent* acquires the understanding and the PM does not, and a spec built on facts the PM never saw
@@ -58,12 +58,12 @@ router is the bug (fix it via the weekly harness scan).
 
 | The PM says… | Route | Lane / artifacts / next skill | Gates to expect |
 |---|---|---|---|
-| "I have an idea" the PM **can't judge from a description** — they need an **instance** in front of them (a UI not yet seen; equally *does this skill's output teach?*, *does this API feel right to call?*) | **Prototype first — before any PRD** | `type: prototype`; quick brief at `prd_path` declaring **the judgement exercised + the specimen format** (**no rubric BY DESIGN** — grilled, never scored); [prototype skill](/skills/core/prototype.skill). Format fits the work: lookable UI, a worked sample output, call/response transcripts, a schema sketch. **The class's conventions are a BLOCKING precondition** (design system for UI; SKILL-FORMAT, D19 ACI, migration/RLS conventions elsewhere) — absent → the agent authors them from the same brief, PM approves, first. | Initiative Gate (brief exists); web-ci quarantine; PM disposition (promote/iterate/kill) |
-| A **new bet** — new product/capability/direction whose *whether* is unargued | **Offer the strategic brief** (recommended, skippable — D61) | [strategic-brief skill](/skills/core/strategic-brief.skill) → `planning/briefs/<id>-brief.md`; go → feature route below; no-go → file in out-of-scope/ | none (the brief is never a gate) |
-| A **validated direction or known feature** (incl. a promoted prototype) | **Feature lane** | `type: feature`; PRD + eval rubric ([prd](/skills/core/prd.skill) + [eval-rubric](/skills/core/eval-rubric.skill) skills), rubric authored alongside (D13); contract before build (D16). A promoted prototype's PRD is **derived from the validated option**. New surface → leg B: [design-brief](/skills/core/design-brief.skill) as the build's reference, held to the [design-reference rubric](/planning/evals/design-reference-eval-rubric.md) | Initiative Gate (PRD+rubric); full three-tier gate |
-| "**Is this feasible / should we / how would we…?**" — a **question** with an unknown answer, findable by investigation | **Discovery lane** | `type: discovery`; spike brief at `prd_path` ([discovery skill](/skills/core/discovery.skill)); question + timebox + disposition. Deliverable is a **learning**, and it closes on the **timebox** ("inconclusive" is a recordable outcome). Contrast the row above: that one holds a **candidate** whose rightness no description settles, delivers a **validated direction**, and closes on a **disposition against a specimen**. Widening this lane to cover that was considered and **rejected** in D60 | Initiative Gate (spike brief) |
+| "I have an idea" the PM **can't judge from a description** — they need an **instance** in front of them (a UI not yet seen; equally *does this skill's output teach?*, *does this API feel right to call?*) | **Prototype first — before any PRD** | `type: prototype`; quick brief at `prd_path` declaring **the judgement exercised + the specimen format** (**no rubric BY DESIGN** — grilled, never scored); [prototype skill](/skills/prototype.skill). Format fits the work: lookable UI, a worked sample output, call/response transcripts, a schema sketch. **The class's conventions are a BLOCKING precondition** (design system for UI; SKILL-FORMAT, D19 ACI, migration/RLS conventions elsewhere) — absent → the agent authors them from the same brief, PM approves, first. | Initiative Gate (brief exists); web-ci quarantine; PM disposition (promote/iterate/kill) |
+| A **new bet** — new product/capability/direction whose *whether* is unargued | **Offer the strategic brief** (recommended, skippable — D61) | [strategic-brief skill](/skills/strategic-brief.skill) → `planning/briefs/<id>-brief.md`; go → feature route below; no-go → file in out-of-scope/ | none (the brief is never a gate) |
+| A **validated direction or known feature** (incl. a promoted prototype) | **Feature lane** | `type: feature`; PRD + eval rubric ([prd](/skills/prd.skill) + [eval-rubric](/skills/eval-rubric.skill) skills), rubric authored alongside (D13); contract before build (D16). A promoted prototype's PRD is **derived from the validated option**. New surface → leg B: [design-brief](/skills/design-brief.skill) as the build's reference, held to the [design-reference rubric](/planning/evals/design-reference-eval-rubric.md) | Initiative Gate (PRD+rubric); full three-tier gate |
+| "**Is this feasible / should we / how would we…?**" — a **question** with an unknown answer, findable by investigation | **Discovery lane** | `type: discovery`; spike brief at `prd_path` ([discovery skill](/skills/discovery.skill)); question + timebox + disposition. Deliverable is a **learning**, and it closes on the **timebox** ("inconclusive" is a recordable outcome). Contrast the row above: that one holds a **candidate** whose rightness no description settles, delivers a **validated direction**, and closes on a **disposition against a specimen**. Widening this lane to cover that was considered and **rejected** in D60 | Initiative Gate (spike brief) |
 | "**Production is broken**" | **Incident lane** | `type: incident`; fix now, record post-hoc within 48h at `prd_path` (the one sanctioned inversion; [incident template](/okf/core/templates/incident-record-template.md)) | Initiative Gate (record, post-hoc) |
-| A **text deliverable** (landing page, microcopy, release notes, campaign) | **Content lane** | `type: content`; content brief at `prd_path`, rubric recommended not required (D58); [copywriting skill](/skills/domains/copywriting.skill). Copy for a prototype rides the prototype instead (D60) | Initiative Gate (content brief) |
+| A **text deliverable** (landing page, microcopy, release notes, campaign) | **Content lane** | `type: content`; content brief at `prd_path`, rubric recommended not required (D58); [copywriting skill](/skills/copywriting.skill). Copy for a prototype rides the prototype instead (D60) | Initiative Gate (content brief) |
 | **Upkeep** — refactor/ops/security with no honest KR | **Chore lane, health-anchored** | `type: chore`; one-paragraph intent in `status`; anchor `health:<id>` from [health-budgets](/planning/okrs/health-budgets.md) (D59) — never a faked KR | Initiative Gate (intent + anchor) |
 
 **Every route** still takes the universal steps: anchored initiative row (`create_initiative`),

package/payload/skills-native/prd/SKILL.md

@@ -18,7 +18,7 @@ strategy, so a generator agent and the PM share one definition of the work befor
 agreed.
 
 > **Format note:** this skill follows three-level progressive disclosure
-> ([SKILL-FORMAT](/skills/core/SKILL-FORMAT.md)). Level 1 above is the trigger; this body is Level 2;
+> ([SKILL-FORMAT](/skills/SKILL-FORMAT.md)). Level 1 above is the trigger; this body is Level 2;
 > rare variants are pushed to Level 3 sub-files referenced by name.
 
 ## When to use vs. not
@@ -27,13 +27,13 @@ agreed.
 - **Do not use** to make the strategic case for *whether* to do the initiative — that is the
   `strategic-brief` skill. The PRD assumes the initiative is already chosen.
 - **Do not use** to define how output is judged — that is the
-  [eval-rubric skill](/skills/core/eval-rubric.skill). PRD and rubric are authored together (see
+  [eval-rubric skill](/skills/eval-rubric.skill). PRD and rubric are authored together (see
   [eval-driven-pm](/okf/core/concepts/eval-driven-pm.md)) but are separate artifacts.
 
 ## Procedure
 
 0a. **Existing surface? Understand it first — before grilling.** If specifying this honestly
-   requires reading code that already exists, an [explain-surface](/build-skills/explain-surface.skill)
+   requires reading code that already exists, an [explain-surface](/skills/explain-surface.skill)
    pass runs on that region **first**, in a fresh context and **not by you**. Its *Open questions*
    section is a declared input to the grilling below: those are the things that could not be
    determined from the code, and they must be resolved with the PM or carried explicitly into the
@@ -64,7 +64,7 @@ agreed.
 5. **State success as outcomes, not output.** Success criteria describe a change in the world tied
    to the anchor — the parent KR, or the declared budget's purpose (D59) — not a list of artifacts
    produced.
-6. **Pair with a rubric.** Flag that the [eval-rubric](/skills/core/eval-rubric.skill) must be
+6. **Pair with a rubric.** Flag that the [eval-rubric](/skills/eval-rubric.skill) must be
    authored before the build starts — the eval is written first.
 7. **Write for durability.** The PRD (and the contract derived from it) waits while work is
    scheduled, so write what stays true: name **interfaces, types, and behavioral contracts — never
@@ -113,5 +113,5 @@ its situating sentence (D58); the eval rubric is queued to be written first.
   (author on first need).
 - Spike / discovery work where the deliverable is a learning, not a feature, is **not a PRD
   case** — take the discovery lane ([D56](/okf/products/pmos/adr/d56-initiative-lanes.md)):
-  [discovery skill](/skills/core/discovery.skill) +
+  [discovery skill](/skills/discovery.skill) +
   [spike-brief template](/okf/core/templates/spike-brief-template.md).

package/payload/skills-native/prototype/SKILL.md

@@ -16,7 +16,7 @@ The [D60](/okf/products/pmos/adr/d60-prototype-loop.md) lane skill. The division
 point: **the PM briefs; the agent builds the specimen.** The PM should never have to author a design
 system, a convention set, or a prototype to validate an idea.
 
-> **Format note:** three-level progressive disclosure ([SKILL-FORMAT](/skills/core/SKILL-FORMAT.md)).
+> **Format note:** three-level progressive disclosure ([SKILL-FORMAT](/skills/SKILL-FORMAT.md)).
 > Level 1 above is the trigger; this body is Level 2.
 > **Scope note (2026-07-24 amendment):** this lane is **no longer gated on the work being a user
 > interface**. D60's mechanism — *make it examinable, then grill it, before committing to a spec* —
@@ -43,7 +43,7 @@ system, a convention set, or a prototype to validate an idea.
   [design loop](/okf/core/concepts/design-loop.md): design-brief → design → reconcile, open to new
   surfaces per D60's D48 amendment).
 - **Do not use** when you hold a *question* rather than a *candidate* — that is the
-  [discovery lane](/skills/core/discovery.skill):
+  [discovery lane](/skills/discovery.skill):
 
   | | You hold | Deliverable | Closes on |
   |---|---|---|---|
@@ -59,7 +59,7 @@ system, a convention set, or a prototype to validate an idea.
 1. **Open the lane.** `create_initiative({id, title, parent_kr, type:'prototype', stage:'intake'})` —
    anchored like all work (D21/D59). Branch `initiative/<id>`.
 1b. **Improving something that already exists? Understand it first.** If the specimen will replace
-   or alter an existing surface, run an [explain-surface](/build-skills/explain-surface.skill) pass on
+   or alter an existing surface, run an [explain-surface](/skills/explain-surface.skill) pass on
    it — fresh context, **before** the brief. Divergent options against a surface nobody has
    characterised diverge from a guess, and the PM cannot grill them honestly. Brand-new → skip.
 2. **Take the quick brief.** The PM fills the
@@ -75,7 +75,7 @@ system, a convention set, or a prototype to validate an idea.
    | Class | Its conventions live in |
    |---|---|
    | A user interface | the product's **design system** — tokens, type scale, components (PMOS's own app: [D38](/DECISIONS.md); tenants checked at onboarding) |
-   | A skill | [SKILL-FORMAT](/skills/core/SKILL-FORMAT.md) — three-level progressive disclosure |
+   | A skill | [SKILL-FORMAT](/skills/SKILL-FORMAT.md) — three-level progressive disclosure |
    | A tool or API | [D19](/okf/products/pmos/adr/d19-aci-design.md)'s ACI principle |
    | A knowledge doc | the OKF spec + [frontmatter-format](/okf/core/concepts/frontmatter-format.md) |
    | A schema | the repo's migration + RLS conventions |
@@ -107,12 +107,12 @@ system, a convention set, or a prototype to validate an idea.
 5. **Produce divergent specimens** into `prototype/<id>/` — low-fidelity, self-contained, examinable
    (whatever renders or reads fastest). **2–3 genuinely different directions, not one safe one with
    variants** — divergence is the point in any medium. **Real draft content, never placeholder**
-   (D60: copy rides the prototype — [copywriting.skill](/skills/domains/copywriting.skill) craft
+   (D60: copy rides the prototype — [copywriting.skill](/skills/copywriting.skill) craft
    applies in-loop; claim-sourcing waits for the content lane at production). The non-visual analogue
    is the same rule: real inputs and real outputs, because fake ones hide exactly the friction the
    specimen exists to surface. Respect the accessibility floors even at low fidelity.
 6. **Grill — dialogue, never a score. Dispatch
-   [`prototype-grill`](/build-skills/prototype-grill.skill).** A craft-grade critic (fresh context,
+   [`prototype-grill`](/skills/prototype-grill.skill).** A craft-grade critic (fresh context,
    default-to-refute stance, the class's craft loaded) interrogates each specimen: *why this
    structure? what job does the focal element serve? what would the best practitioner in this class
    say is wrong? what was NOT tried?* It writes `prototype/<id>/grilling.md`. Sharpen the specimens
@@ -133,7 +133,7 @@ system, a convention set, or a prototype to validate an idea.
      work has a surface, then runs inside that initiative's Build.
    - **iterate** → back to step 5 with the PM's reaction folded in.
    - **kill** → record one honest line on the initiative, **file the concept into
-     [planning/out-of-scope/](/planning/out-of-scope/README.md)** (decision, reasoning, what would
+     [planning/out-of-scope/](/README.md)** (decision, reasoning, what would
      reopen it) so it is not re-prototyped from scratch, and close. A cheap kill is this lane
      *succeeding*.
 8. **Log.** `log_agent_run` with the disposition; friction to discoveries.md (`#friction`).

package/payload/skills-native/prototype-grill/SKILL.md

@@ -13,16 +13,16 @@ metadata:
 # prototype-grill — The second party in D60's dialogue
 
 [D60](/okf/products/pmos/adr/d60-prototype-loop.md) clause (d) makes leg A **grilled as dialogue,
-never scored**, and [`prototype.skill`](/skills/core/prototype.skill) step 6 has always described the
+never scored**, and [`prototype.skill`](/skills/prototype.skill) step 6 has always described the
 critic correctly. What it never had was a way to *dispatch* one — so the cheapest path was to grill
 your own specimens, and **a dialogue with one party is a monologue with extra steps**. This skill is
-step 6 made dispatchable, the way [`evaluator`](/build-skills/evaluator.skill) made the Review Gate
-first-class and [`explain-surface`](/build-skills/explain-surface.skill) made the understanding pass
+step 6 made dispatchable, the way [`evaluator`](/skills/evaluator.skill) made the Review Gate
+first-class and [`explain-surface`](/skills/explain-surface.skill) made the understanding pass
 standard.
 
-> **Format:** three-level progressive disclosure ([SKILL-FORMAT](/skills/core/SKILL-FORMAT.md)).
+> **Format:** three-level progressive disclosure ([SKILL-FORMAT](/skills/SKILL-FORMAT.md)).
 > L1 above is the trigger; this L2 body is the procedure.
-> **Not [`evaluator`](/build-skills/evaluator.skill).** That one *scores a finished diff against a
+> **Not [`evaluator`](/skills/evaluator.skill).** That one *scores a finished diff against a
 > rubric* and writes a verdict. This one **never scores anything** and writes no verdict. They share
 > only the adversarial stance. Confusing them is the single most likely way to violate D60 here.
 
@@ -51,7 +51,7 @@ standard.
 - **Use** at `prototype.skill` **step 6** — specimens exist in `prototype/<id>/`, the PM has not yet
   disposed. Also on **iterate**: a second round earns a second grilling, not a re-read of the first.
 - **Do not use** to compare finished implementations (that is `evaluator`), to judge a design against
-  a design system (that is [`design-reconcile`](/skills/core/design-reconcile.skill)), or on a lane
+  a design system (that is [`design-reconcile`](/skills/design-reconcile.skill)), or on a lane
   that is not `prototype`. No other lane is ungraded, so this skill's no-score rule would be wrong
   everywhere else.
 
@@ -60,7 +60,7 @@ standard.
 1. **Load the ground.** The initiative record, the quick brief at `prd_path` — specifically **the
    judgement being exercised** and **the specimen format**, which are what the grilling hangs on —
    and every specimen in `prototype/<id>/`. Then load the **artifact class's craft**: the design
-   system for UI, [SKILL-FORMAT](/skills/core/SKILL-FORMAT.md) for a skill,
+   system for UI, [SKILL-FORMAT](/skills/SKILL-FORMAT.md) for a skill,
    [D19](/okf/products/pmos/adr/d19-aci-design.md)'s ACI principle for a tool or API, the OKF spec for
    a knowledge doc, the migration/RLS conventions for a schema. **A critic without the class's craft
    produces taste, not a grilling.**
@@ -96,7 +96,7 @@ standard.
    not a griller pre-empting it. Volunteering it is the violation.
 8. **Log.** Append the run (`log_agent_run`; file-mode `planning/runs/agent-runs.jsonl`) with
    `self_eval` recorded as **unscored by design**, so the absence reads as deliberate rather than as
-   a skipped gate. Friction to [discoveries.md](/discoveries.md) tagged `#friction`.
+   a skipped gate. Friction to [discoveries.md](/state/discoveries.md) tagged `#friction`.
 
 ## Hard rules
 

package/payload/skills-native/skill-creator/SKILL.md

@@ -12,7 +12,7 @@ metadata:
 (for AI-draft) spawns a local session to sharpen it. This skill is that session's procedure. It exists
 because a scheduler skill runs **unattended on a cadence** — a body that is vague or mis-grounded fails
 silently, at 2am, into a corrupted queue. The authority for body quality is
-[SKILL-FORMAT](/skills/core/SKILL-FORMAT.md); do not restate its rules here, apply them.
+[SKILL-FORMAT](/skills/SKILL-FORMAT.md); do not restate its rules here, apply them.
 
 A workspace `.skill` differs from a `skills/core/` skill in one way: it keeps **runtime frontmatter**
 the scheduler reads (`label`, `run: agent`, `agent: claude`, `output:` list = the consistency contract).

package/payload/skills-native/source-to-concept/SKILL.md

@@ -22,7 +22,7 @@ into a curated OKF concept in `core/concepts/` or `products/<product_slug>/`, pr
 and conforming to the [OKF spec](/okf/core/concepts/okf-governance.md).
 
 > **Format note:** three-level progressive disclosure
-> ([SKILL-FORMAT](/skills/core/SKILL-FORMAT.md)). Level 1 is the trigger; this body is the spec of
+> ([SKILL-FORMAT](/skills/SKILL-FORMAT.md)). Level 1 is the trigger; this body is the spec of
 > the procedure; Level 3 holds rare extraction variants.
 
 ## Intended procedure (specification)

package/payload/skills-native/strategic-brief/SKILL.md

@@ -13,18 +13,18 @@ metadata:
 # strategic-brief — Make the Strategic Case
 
 Produces a strategic brief: the argument for *whether* an initiative should exist, made **before** a
-[PRD](/skills/core/prd.skill) specs *what and why in detail*. The PRD assumes the bet is already
+[PRD](/skills/prd.skill) specs *what and why in detail*. The PRD assumes the bet is already
 chosen; the brief is where that choice is argued. **Activated by [D61](/DECISIONS.md)** (2026-07-21)
 after being spec-only since P0 — its own activation criteria (OKRs on a regular cadence; initiative
 volume where informal prioritization strains) are now met.
 
 > **Format note:** three-level progressive disclosure
-> ([SKILL-FORMAT](/skills/core/SKILL-FORMAT.md)). Level 1 above is the trigger; this body is Level 2.
+> ([SKILL-FORMAT](/skills/SKILL-FORMAT.md)). Level 1 above is the trigger; this body is Level 2.
 
 ## When to use vs. not (D61 — optional, router-recommended)
 
 - **Use** when the work is a **new bet** — a new product, capability, or direction whose "whether"
-  has not been argued — typically on the [pmos-router](/skills/core/pmos-router.skill)'s
+  has not been argued — typically on the [pmos-router](/skills/pmos-router.skill)'s
   recommendation at intake. The PM may always demand one.
 - **Skippable by design.** The brief is never a gate. Skipping it on a new bet is the PM's call;
   the router recommends, it does not require. (Mandatory briefs recreate the ceremony-pressure
@@ -51,7 +51,7 @@ volume where informal prioritization strains) are now met.
 
 - `planning/briefs/<initiative-id>-brief.md` — operational instance, never in the OKF bundle.
 - An accepted brief becomes the PRD's parent rationale (the PRD links it). A **no-go** files the
-  concept into [planning/out-of-scope/](/planning/out-of-scope/README.md) so it is not re-litigated.
+  concept into [planning/out-of-scope/](/README.md) so it is not re-litigated.
 
 ## Level 3 sub-cases
 

package/payload/skills-native/technical-writing-ste/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: technical-writing-ste
+description: Apply the PMOS-STE writing profile — the ASD-STE100 writing rules, scoped by register — when you write or rewrite text a reader must act on: a skill body, a gate or CI failure message, an MCP tool description, workspace copy, an explainer, an OKF concept, a README. Do NOT use it on argumentative text (ADRs, PRD rationale, briefs, eval verdicts, PR bodies), where graded confidence is the payload and the profile deliberately does not apply.
+license: MIT
+metadata:
+  pmos-version: 1.0.0
+  pmos-owner: wawan
+  pmos-risk: low
+  pmos-category: domain
+  pmos-scope: read:okf, write:any-prose
+---
+
+# technical-writing-ste — Write text a reader can act on once
+
+PMOS's output is read under load: an agent parsing a skill body, a PM reading a red CI line. This
+skill carries the **PMOS-STE profile** — the [ASD-STE100](/okf/core/concepts/simplified-technical-english.md)
+writing rules, bound by **register** instead of repo-wide. The scoping is the whole design. That
+concept's *one-meaning trade* section is why: applied uniformly, STE deletes the graded confidence
+that eval verdicts and decision records are made of.
+
+> **Format:** three-level progressive disclosure (`SKILL-FORMAT.md`).
+> **This file demonstrates the profile it defines.** The procedure below is Class A. The rationale is
+> Class B. Read the two registers against each other — that contrast teaches faster than the rules do.
+
+## Two things to know before you apply it
+
+**PMOS adopts the writing rules, not the vocabulary control.** ASD owns the ~900-word dictionary and
+grants free reproduction only to named aerospace and defense categories. PMOS is in none of them, so
+the word list is neither vendored nor checkable here. **Never write that PMOS output is
+"STE-compliant."** Write "PMOS-STE" and mean the writing rules only. The stronger claim is false.
+
+**Nothing mechanical enforces this profile.** No lint runs, and no gate reads it. An advisory
+`ste_lint.py` is a named follow-on, not a shipped thing. The only mechanism is that you read this and
+comply, and the only check is a human at the Acceptance Gate. Treat availability as availability. A
+standard that reads as enforced when it is not is a [watermelon](/okf/core/concepts/watermelon-flag.md).
+
+## Step 1 — Classify the text. Do this first.
+
+Ask what the reader must do with it. Derive the class from the path, not from feel.
+
+| Class | What the reader must do | Where it lives |
+|---|---|---|
+| **A — instructional** | **Act**, correctly, on one reading | `skills/**` · playbooks and runbooks · gate and CI failure strings · UI copy and microcopy · tool descriptions · template usage notes |
+| **B — descriptive** | **Understand**, not obey | `okf/**` concepts and references · explainers · `**/README.md` · design and data-model docs |
+| **C — argumentative** | **Weigh a judgement under uncertainty** | ADRs and decision records · `planning/prd/**` · briefs · the discoveries log · eval verdicts · PR bodies |
+
+The three classes are the rule. **The paths are your repo's, so write them down once.** In PMOS they
+also cover `build-skills/**` and `okf/core/playbooks/**` (A), `planning/explainers/**` and
+`planning/design/**` (B), and `pm-decisions.md` and `discoveries.md` (C). In a product repo they
+cover your CLI output, your error strings and your component copy (A), and your architecture notes
+(B). When a path is not on your list, ask the question in column two and add the answer to the list.
+
+Two boundary rules. **Text the PM wrote is Class C**, whatever it is about. And the profile binds
+**new and modified text only** — never rewrite an existing corpus to satisfy it.
+
+**Done when:** you can name the class and the row that put it there.
+
+## Step 2 — If the text is Class C, stop here.
+
+Class C keeps four things and nothing else:
+
+- Short sentences, where they fit.
+- One topic per sentence.
+- Active voice by default.
+- **One term per concept** (1.11, 9.4). This is the one hard rule that binds in every class.
+
+Then write freely.
+
+**Why this exemption exists — read it, because the reason is the rule.** Class C's payload *is* the
+hedge. "Confidence: medium", "probably", "this should be re-run before the number is quoted" — these
+carry the actual content. STE has no approved way to write them: its recurring-errors list replaces
+`should` and `may` with `MUST`. Apply it here and a recommendation becomes an obligation, an estimate
+becomes a certainty. The text ends up **more certain than its author was**. That inverts the
+[anti-optimism](/okf/core/concepts/okr-anti-optimism.md) stance PMOS reports by. The exemption is not
+leniency for hard-to-constrain prose. It is the profile refusing to damage its own repo.
+
+**Done when:** you have applied the four principles and stopped.
+
+## Step 3 — For Class A, write to act on.
+
+Apply these. Rule numbers point into the standard.
+
+- **≤20 words per sentence** (5.1). Count under 8.4–8.7. Each of these counts as **one word**:
+    - a number, or a number with its unit
+    - an abbreviation, or an alphanumeric identifier
+    - a parenthetical
+    - a hyphenated word
+- **One instruction per sentence** (5.2), unless the actions happen at the same time.
+- **Imperative form** (5.3). Say "Run the gate", not "the gate should be run".
+- **Condition first, then a comma, then the command** (5.4). "If the branch is `claude/*`, name the
+  initiative in the PR body."
+- **Notes inform. Notes never instruct** (5.5).
+- **Active voice** (3.6). Simple verb forms only (3.2). Keep `-ing` inside a technical noun (3.5).
+- **Noun clusters: three words maximum** (2.1).
+- **Keep every word** (4.2). No contractions, no dropped articles.
+- **Vertical lists for anything complex** (4.3).
+- **No semicolons** (8.1).
+- **Every pronoun resolves to one antecedent** (GR-3, GR-4). This one earns its place in agent
+  instructions: an unresolvable "it" is where a run silently guesses.
+- **Inclusive language** (GR-7). Use they/them when a person's pronouns are not stated.
+- **Warnings carry three parts** (7.1–7.3): the risk level, the command, the consequence. Use this for
+  every destructive or irreversible action.
+- **One term per concept** (1.11, 9.4). Pick the term, then use only that term.
+
+**Done when:** every sentence is ≤20 words, every instruction stands alone, and every pronoun resolves.
+
+### A worked pair — a real gate message
+
+From PMOS's own workflow gate (`scripts/workflow-state.js`), the `how` line for rule O4:
+
+> **Before:** `run build-skills/explain-surface.skill in a FRESH context (not the agent that will
+> write the spec), then set explainer_path:`
+>
+> **After:** `Run build-skills/explain-surface.skill in a fresh context. Do not use the agent that
+> will write the spec. Then set explainer_path.`
+
+One command with a prohibition buried in a parenthetical becomes three short commands. The
+prohibition is now impossible to skim past. Nothing was lost.
+
+## Step 4 — For Class B, write to be understood.
+
+- **≤25 words per sentence** (6.3), counted the same way.
+- **One topic per paragraph** (6.5). **Six sentences maximum** (6.6).
+- **Give information gradually** (6.1). Let key words carry the structure (6.2).
+- Carried over from Class A, unchanged:
+    - **active voice** (3.6) and **≤3-word noun clusters** (2.1)
+    - **no semicolons** (8.1) and **keep every word** (4.2)
+    - **pronouns resolve** (GR-3, GR-4) and **inclusive language** (GR-7)
+    - **one term per concept** (1.11, 9.4)
+- **The imperative stays out.** Description is not instruction (section 6).
+
+**Done when:** no sentence passes 25 words, no paragraph holds two topics or seven sentences.
+
+### A worked pair — a real concept sentence
+
+From [eval-driven-pm](/okf/core/concepts/eval-driven-pm.md) — 42 words, one semicolon, a nested aside:
+
+> **Before:** "The Quality and Review gates check the work against the pre-written rubric
+> mechanically; the PM's scarce attention is spent on the one question the rubric cannot answer —
+> *is this the right thing?* — and on whether the rubric itself was right."
+>
+> **After:** "The Quality and Review gates check the work against the pre-written rubric
+> mechanically. The rubric cannot answer one question: is this the right thing? The PM spends their
+> scarce attention there, and on whether the rubric itself was right."
+
+14, 13 and 18 words. The passive is gone. **State the trade honestly:** the original's aside had more
+bite, and the rewrite is flatter. For reference text that price is worth paying. For an argument it is
+not — which is why Class C exists.
+
+## Step 5 — Check the register held.
+
+Read the finished text once more and ask the one question the word counts cannot answer:
+
+> **Did an instruction leak into descriptive text, or a hedge get flattened out of an argument?**
+
+Two shapes answer yes. A Class B passage has turned imperative. Or a Class C sentence's "probably"
+has become "must". Either one is the failure this profile exists to prevent. Fix it there.
+
+**Done when:** the text reads in the register its class names.
+
+## Quality bar
+
+Before you call the text done, confirm each of these:
+
+- The class is derived from the table, not felt.
+- Class A sentences are ≤20 words. Class B sentences are ≤25. Both counted under 8.4–8.7.
+- One term per concept, throughout.
+- Every pronoun resolves to one antecedent.
+- Class C kept its hedges.
+- Nothing claims "STE compliance".
+
+## Level 3 sub-cases
+
+- `ste-term-map.md` — the one-term-per-concept register (1.11,
+  9.4). Read it when you name a concept in **any** register, including Class C. It holds the known
+  drift with its evidence, and it proposes canonical terms rather than ruling on them.
+- `ste-safety-instructions.md` — not yet written. Author it on first need, mapping section 7 onto
+  destructive-action warnings and confirmation copy.

package/workspace/bin/pmos.js

@@ -357,7 +357,9 @@ async function stop() {
 
 function doctor() {
   const r = spawnSync(process.execPath, [path.join(WS, 'doctor.js')], { stdio: 'inherit' });
-  return r.status || 0;
+  // A child that never ran (or died to a signal) has status null — `null || 0` reported success.
+  if (r.error) { say('✗ could not run doctor — ' + r.error.message); return 1; }
+  return r.status === null ? 1 : r.status;
 }
 
 (async () => {
@@ -372,8 +374,12 @@ function doctor() {
     // Escape hatch: pull the latest bundled app and force-reinstall over this global copy. Delegates
     // to the scaffolder (which owns the install path) rather than reinstalling itself in place.
     const npx = process.platform === 'win32' ? 'npx.cmd' : 'npx';
-    code = spawnSync(npx, ['-y', 'create-pmos@latest', 'workspace', '--reinstall', process.cwd()],
-      { stdio: 'inherit', shell: process.platform === 'win32' }).status || 0;
+    const r = spawnSync(npx, ['-y', 'create-pmos@latest', 'workspace', '--reinstall', process.cwd()],
+      { stdio: 'inherit', shell: process.platform === 'win32' });
+    // `npx` missing from PATH left status null — `null || 0` reported a successful upgrade that
+    // reinstalled nothing. A launch failure and a signal-killed child both exit nonzero, and say so.
+    if (r.error) { say('✗ could not run ' + npx + ' — ' + r.error.message); code = 1; }
+    else code = r.status === null ? 1 : r.status;
   } else if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
     say('usage: pmos [<path>|status|ls|stop|doctor|upgrade]');
     say('  pmos          open the current repo as a workspace (starts the server if needed)');