create-pmos 0.31.1 → 0.33.0

package/README.md

@@ -232,6 +232,27 @@ npx create-pmos@latest --update
 
 Refreshes the skills, concepts, and scripts only. Your records — `state/`, `planning/`, `okf/product/` — are yours, and an update never touches them. `pmos/KIT-VERSION` always says exactly what you're running.
 
+## What's new in 0.33.0
+
+**Three shipped documents stop telling you to do things that were never possible in your repo.** Run `npx create-pmos@latest --update`. No behaviour changes — this is a correctness release for the instructions the kit hands your agent.
+
+- **`SKILL-FORMAT.md` no longer sends you after a seed you never had.** When you edited a `.skill`, it told you to "regenerate the seed in the same PR" and to grep an RLS test suite for pinned metadata. Those instructions described a hosted mirror table that only ever existed in PMOS's own backend — never in a vendored kit. That backend has now been removed entirely, and the section is rewritten to say what is actually true for you: **the frontmatter on disk is the only copy**, which is why the whole class of mirror-drift bug it warned about cannot reach you. The trade is stated rather than glossed: nothing validates your skill metadata, so a wrong registry key is simply wrong.
+- **`ingest-repo` and `harness-refine` stop linking at reference docs your kit does not contain.** Both pointed at PMOS's hosted data-model and monitoring-view docs. `ingest-repo` now describes its write path as what it is in file mode — drafts into your own repo, approved in PR review — and `harness-refine` reads its evidence from `discoveries.md` and your run log instead of from SQL views.
+
+**Why now.** PMOS removed its own hosted backend in this release's parent change, and these three files were the places where instructions written for that backend had leaked into what your kit ships. None of it was ever reachable from a kit install, so nothing was broken — it was wrong documentation, and it is now right.
+
+**Unchanged:** the payload's skill set, the state layout, every gate, and the zero-network guarantee. Your records are untouched, as always.
+
+## What's new in 0.32.0
+
+**The PM's own accept button now writes through the guarded writer, instead of appending to the acceptance log directly.** Run `npx create-pmos@latest workspace`; the version bump means an existing install auto-upgrades.
+
+- **`POST /api/gate` records your acceptance through the sink guard.** It resolves the path before allowing it, opens with `O_NOFOLLOW`, refuses a hard-linked target, writes to the descriptor it vetted rather than reopening the path afterwards, and rolls back a partial write instead of leaving half a record. It used to be a bare append — the one write path in the app that had never been hardened, while the module written for exactly this job had no caller at all.
+- **A failed write is an HTTP 500, not a green tick.** Under D64 the file-mode acceptance log is the system of record; a swallowed append with `{ok:true}` would light the gate green over a record that never landed.
+- **`drive-guard`'s refusal messages are read from a classification file rather than restated inside it.** If that file is absent — which it is in a plain kit install — the write is still refused; only the wording falls back to the generic message. Nothing about permission depends on a file that might not be there.
+
+**Not in this release, said plainly.** The bigger piece of this wave — a declared registry of which records belong to the PM versus an agent, and `check-separation.js`, which names by `file:line` any module that writes one of the PM's records directly — is **PMOS-self only** for now and is not in your payload. Its paths are written for this repository's layout, and shipping them unchanged would give you a checker that reports confidently about directories you do not have. Porting it to the kit layout is its own piece of work, not a line in a release note.
+
 ## What's new in 0.31.1
 
 **Your specs stop arriving in Jira as ragged half-lines. One command repairs the ones already written, and the workspace does it in one click.** Run `npx create-pmos@latest --update` for the command, or `npx create-pmos@latest workspace` for the button.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-pmos",
-  "version": "0.31.1",
-  "description": "Scaffold the PMOS portable kit \u2014 run the PMOS product-management workflow (initiative \u2192 lane-fit spec \u2192 contract \u2192 build \u2192 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.",
+  "version": "0.33.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": {
     "create-pmos": "bin/create-pmos.js"

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@9d15bfe
-assembled: 2026-08-05
+kernel-source: pmos@51a8275
+assembled: 2026-08-06
 mode: vendor

package/payload/scripts/anchor-resolve.js

@@ -196,8 +196,31 @@ function readBudgets(root) {
  * `index` comes from parseOkrIndex; `budgets` from readBudgets (optional — omit to skip the
  * registry check, which callers that only need the FORM can do).
  */
+/** Strip ONE layer of matching surrounding quotes.
+ *
+ *  `parent_kr` is a YAML scalar, and a value whose prose contains a colon-space MUST be quoted or
+ *  the document does not parse. The flat frontmatter reader hands the value through with its quotes
+ *  intact, so a legitimately-quoted anchor arrived here as `"health:security …` and matched no form.
+ *
+ *  This defect occurred TWICE — `sink-discipline-backport` on 2026-08-04 and
+ *  `separation-invariant-enforcement` on 2026-08-05 — and the first time it was fixed by unquoting
+ *  the one file. That is the wave's own lesson landing on the person who wrote it down: the unit of
+ *  attention was the file, the unit of the defect was the rule. "Do not quote it" is a rule that
+ *  lives in prose and depends on an author remembering; tolerating the quoting is a rule that lives
+ *  in code.
+ *
+ *  Only a MATCHING outer pair, and only one layer: a stray leading quote is still malformed, and
+ *  reporting it as such is the point. */
+function unquote(s) {
+  const t = s.trim();
+  if (t.length >= 2 && ((t[0] === '"' && t[t.length - 1] === '"') || (t[0] === "'" && t[t.length - 1] === "'"))) {
+    return t.slice(1, -1).trim();
+  }
+  return t;
+}
+
 function resolveAnchor(raw, index, budgets) {
-  const original = String(raw == null ? '' : raw).trim();
+  const original = unquote(String(raw == null ? '' : raw).trim());
   const base = { raw: original, kind: 'empty', status: 'empty', objective: null, kr: null, budget: null, period: null, form: null, reason: null };
   if (!original) return Object.assign(base, { reason: 'parent_kr is empty — unanchored work is rejected (D59)' });
 
@@ -269,6 +292,7 @@ function canonical(resolved, fallbackPeriod) {
 }
 
 module.exports = {
+  unquote,
   parseOkrIndex, readBudgets, resolveAnchor, canonical,
   objectiveId, krId, stripCommentary, listOkrFiles,
   ACCEPTED_FORMS,

package/payload/skills/SKILL-FORMAT.md

@@ -6,23 +6,17 @@ timestamp: 2026-07-23
 
 # SKILL-FORMAT.md — Required Format for PMOS Skills
 
-This document defines the **required** structure for every `.skill` file in PMOS. It is the
-authority that all seed skills (`prd`, `eval-rubric`, `okr`, `strategic-brief`, `source-to-concept`)
-and every future skill must conform to.
+This document defines the **required** structure for every `.skill` file in PMOS. It is the authority that all seed skills (`prd`, `eval-rubric`, `okr`, `strategic-brief`, `source-to-concept`) and every future skill must conform to.
 
 ## Why a fixed format
 
-Skills are how PMOS gives an agent procedural competence on demand without flooding its context.
-The format exists to make that economical: cheap to keep many skills available, expensive to load
-only the one in use. The mechanism is **three-level progressive disclosure**.
+Skills are how PMOS gives an agent procedural competence on demand without flooding its context. The format exists to make that economical: cheap to keep many skills available, expensive to load only the one in use. The mechanism is **three-level progressive disclosure**.
 
 ## The three levels
 
 ### Level 1 — Frontmatter (always loaded)
 
-YAML frontmatter containing **only `name` and `description`**. This is pre-loaded for **all** skills
-at agent startup, so it must stay small — it is the *trigger signal* the agent uses to decide
-whether the skill is relevant.
+YAML frontmatter containing **only `name` and `description`**. This is pre-loaded for **all** skills at agent startup, so it must stay small — it is the *trigger signal* the agent uses to decide whether the skill is relevant.
 
 ```yaml
 ---
@@ -32,189 +26,96 @@ description: Write a Product Requirements Document for an initiative. Use when a
 ```
 
 Rules:
+
 - `name` — lowercase, matches the filename stem (`prd` → `prd.skill`). **Required.**
-- `description` — one or two sentences. State **what** the skill does and **when** to use it.
-  This is the only text the agent sees for an unloaded skill, so the "when" is what makes it fire.
-  **Required.**
-- `maturity_mode` — **optional**. Present **only** on skills that are not yet active (e.g. `bootstrap`);
-  omit it entirely on active skills. It lives at L1 because "is this skill executable yet?" is an
-  execution-gating signal a loader/CI must be able to read without parsing the body. Values: `bootstrap`
-  (specified, non-executable) → graduates to active (key removed) by a PM decision in `DECISIONS.md`.
-- **Optional Phase-B registry metadata (D49)** — a skill may also carry `version`, `owner`, `risk`,
-  `category`, and `scope`. These are **optional**, producer-defined registry fields that
-  the resync generator [`gen_okf_mirror_seed.py`](/supabase/gen_okf_mirror_seed.py) sources into the `skills` table so the skill
-  library can group/version/scope skills. A skill with only `name` + `description` is still fully
-  conformant (e.g. `build-skills/evaluator.skill`); carry the registry keys on durable `skills/core/`
-  entries for consistency with their siblings.
-- `lifecycle` — **optional**, in the same D49 registry slot. Values: `active` (the default when the
-  key is absent) | `deprecated`. A deprecated skill **stays on disk and stays in the registry** —
-  `get_skill` returns it in full with a `deprecated_notice` so a retrieving agent is *told* not to
-  start new work on it. Retirement is a state you can read; deletion is a separate act (see the
-  invariant below). Distinct from `maturity_mode`, which is about a skill not yet executable —
-  `lifecycle` is about one on its way out.
-- **No other L1 keys.** Beyond the required `name` + `description`, the optional `maturity_mode`, and the
-  optional Phase-B registry keys above, procedural detail does not belong in L1 — it lives in the body.
-
-### The disk ⇄ registry invariant (enforced in CI)
-
-**Every `.skill` on disk is seeded, and every seeded skill exists on disk — exactly.** The `skills`
-table is a *mirror*, and `get_skill` serves it to agents in other people's repos, so a mirror that
-has quietly drifted is a wrong answer delivered confidently.
-
-The `REGISTRY` check in [`check_okf_drift.py`](/supabase/check_okf_drift.py) fails the build on:
-adding or renaming a `.skill` without regenerating the seed; a seeded skill whose file is gone; and
-any registry-metadata value that disagrees with the file's own frontmatter. That last one is not
-theoretical — a generator whose INSERT omitted the Phase-B columns silently nulled
-`version/owner/risk/category/scope` for **all 21 skills for about three weeks** in 2026-07, and was
-caught only by an incidental version pin in an RLS test. So:
-
-> **When you add, rename, delete, or edit the frontmatter of a `.skill`, regenerate the seed in the
-> same PR** ([okf-sync playbook](/okf/core/playbooks/okf-sync.md)) — and sweep `supabase/tests/` for
-> pins on that skill's registry metadata before you do (the prd-grilling F1 rule).
+- `description` — one or two sentences. State **what** the skill does and **when** to use it. This is the only text the agent sees for an unloaded skill, so the "when" is what makes it fire. **Required.**
+- `maturity_mode` — **optional**. Present **only** on skills that are not yet active (e.g. `bootstrap`); omit it entirely on active skills. It lives at L1 because "is this skill executable yet?" is an execution-gating signal a loader/CI must be able to read without parsing the body. Values: `bootstrap` (specified, non-executable) → graduates to active (key removed) by a PM decision in `DECISIONS.md`.
+- **Optional Phase-B registry metadata (D49)** — a skill may also carry `version`, `owner`, `risk`, `category`, and `scope`. These are **optional**, producer-defined registry fields that the workspace's skill library reads to group/version/scope skills. They used to be sourced into a hosted `skills` table by a resync generator; [D66](/DECISIONS.md) removed that mirror along with the backend, so the frontmatter on disk is now the only registry there is. A skill with only `name` + `description` is still fully conformant (e.g. `build-skills/evaluator.skill`); carry the registry keys on durable `skills/core/` entries for consistency with their siblings.
+- `lifecycle` — **optional**, in the same D49 registry slot. Values: `active` (the default when the key is absent) | `deprecated`. A deprecated skill **stays on disk** — a reader gets it in full and is *told* not to start new work on it. Retirement is a state you can read; deletion is a separate act (see the invariant below). Distinct from `maturity_mode`, which is about a skill not yet executable — `lifecycle` is about one on its way out.
+- **No other L1 keys.** Beyond the required `name` + `description`, the optional `maturity_mode`, and the optional Phase-B registry keys above, procedural detail does not belong in L1 — it lives in the body.
+
+### The disk ⇄ registry invariant — retired with the mirror (D66)
+
+There used to be a second copy of every skill: a hosted `skills` table that `get_skill` served to agents in other people's repos. A `REGISTRY` check in the drift gate held the two in sync, because a mirror that has quietly drifted is a wrong answer delivered confidently — and it was not theoretical. A generator whose INSERT omitted the Phase-B columns silently nulled `version/owner/risk/category/scope` for **all 21 skills for about three weeks** in 2026-07, caught only by an incidental version pin in an RLS test.
+
+[D66](/DECISIONS.md) deleted the mirror, the generator and that check together with the hosted backend. **The file on disk is now the only copy**, which is why the class of bug above cannot recur: there is nothing left to disagree with. The cost is that skill metadata is no longer validated by CI at all — if a registry key is wrong in the frontmatter, it is simply wrong. Read the frontmatter as authoritative and keep it accurate by hand.
 
 ### Level 2 — SKILL.md body (loaded when relevant)
 
-The body below the frontmatter holds the **full procedural detail**: steps, heuristics, required
-fields, gate criteria, examples. The agent reads this only after Level 1 has signalled relevance.
+The body below the frontmatter holds the **full procedural detail**: steps, heuristics, required fields, gate criteria, examples. The agent reads this only after Level 1 has signalled relevance.
 
-This is where the actual "how to do the task" lives. Write it at optimal altitude — concrete
-heuristics that guide judgment, not a brittle decision tree and not a vague mandate.
+This is where the actual "how to do the task" lives. Write it at optimal altitude — concrete heuristics that guide judgment, not a brittle decision tree and not a vague mandate.
 
 ### Level 3 — Linked sub-files (loaded on demand)
 
-Rare sub-cases, long reference tables, or edge-case procedures live in **separate files**,
-referenced **by filename** from the Level 2 body. The agent reads them only when the body points it
-there for the specific case in hand.
+Rare sub-cases, long reference tables, or edge-case procedures live in **separate files**, referenced **by filename** from the Level 2 body. The agent reads them only when the body points it there for the specific case in hand.
 
 Example reference from a body: *"For multi-product PRDs, follow `prd-multiproduct.md`."*
 
-Use Level 3 to keep Level 2 focused. If a section applies to <20% of runs, it is a Level 3
-candidate.
+Use Level 3 to keep Level 2 focused. If a section applies to <20% of runs, it is a Level 3 candidate.
 
 ## Quality — what makes a skill good (not just well-formed)
 
-The three levels are *structure*. This section is the *bar*. A skill can be perfectly structured and
-still be junk; these are the tests that keep it worth its context.
+The three levels are *structure*. This section is the *bar*. A skill can be perfectly structured and still be junk; these are the tests that keep it worth its context.
 
 ### Predictability is the root virtue
 
-A skill exists to **wring determinism out of a stochastic system**: it makes the agent take the same
-*process* every run — not produce the same *output* (an evaluator should predictably *judge*; its
-words vary, its behavior doesn't). Every rule below serves predictability; cost and readability are
-symptoms of it, not rival goals. When unsure whether a line belongs, ask: *does it make the agent's
-process more repeatable?* If not, cut it.
+A skill exists to **wring determinism out of a stochastic system**: it makes the agent take the same *process* every run — not produce the same *output* (an evaluator should predictably *judge*; its words vary, its behavior doesn't). Every rule below serves predictability; cost and readability are symptoms of it, not rival goals. When unsure whether a line belongs, ask: *does it make the agent's process more repeatable?* If not, cut it.
 
 ### Per-step completion criteria
 
-Every procedural step ends on a **checkable done-condition** — the agent must be able to tell done
-from not-done. Where it matters, make the criterion **exhaustive**, not vague: *"every living mirror
-of the rule accounted for"*, not *"produce a change list"*. A fuzzy criterion invites **premature
-completion** — the agent stops when it feels done, not when it is. The
-[semantic-pass rule](/build-skills/evaluator.skill) ("enumerate the live-doc set, then read each for
-meaning — a grep is evidence, never done") is the exemplar this generalizes: it exists because a
-vague "sweep it" criterion let real stale mirrors survive five "clean" passes.
+Every procedural step ends on a **checkable done-condition** — the agent must be able to tell done from not-done. Where it matters, make the criterion **exhaustive**, not vague: *"every living mirror of the rule accounted for"*, not *"produce a change list"*. A fuzzy criterion invites **premature completion** — the agent stops when it feels done, not when it is. The [semantic-pass rule](/build-skills/evaluator.skill) ("enumerate the live-doc set, then read each for meaning — a grep is evidence, never done") is the exemplar this generalizes: it exists because a vague "sweep it" criterion let real stale mirrors survive five "clean" passes.
 
 ### Pruning — hunt these named failure modes
 
 A skill without a pruning discipline only ever grows. Hunt, sentence by sentence:
 
-- **No-op** — a line the model already obeys by default, so you pay context to say nothing. Test:
-  does it change behavior vs. the default? *"Be thorough"* to an already-thorough agent is a no-op;
-  the fix is a stronger word (a leading word), not more words.
-- **Sediment** — stale layers that settle because adding feels safe and removing feels risky. The
-  default fate of any skill without this discipline.
-- **Sprawl** — simply too long, even when every line is live. Cure: disclose reference to Level 3;
-  split by branch.
-- **Duplication** — the same meaning in more than one place. Costs tokens and maintenance, and
-  inflates a meaning's apparent importance. Keep one source of truth.
-- **Negation** — steering by prohibition backfires: *"don't think of an elephant"* names the
-  elephant. State the **positive** target behavior; keep a prohibition only as a hard guardrail you
-  can't phrase positively, and pair it with what to do instead.
-
-**This is the checklist the quarterly harness-assumption review runs** (DECISIONS.md cadence): the
-review's question — *what scaffolding can be removed because the model now handles it natively?* — is
-the no-op and sediment hunt applied across every skill.
+- **No-op** — a line the model already obeys by default, so you pay context to say nothing. Test: does it change behavior vs. the default? *"Be thorough"* to an already-thorough agent is a no-op; the fix is a stronger word (a leading word), not more words.
+- **Sediment** — stale layers that settle because adding feels safe and removing feels risky. The default fate of any skill without this discipline.
+- **Sprawl** — simply too long, even when every line is live. Cure: disclose reference to Level 3; split by branch.
+- **Duplication** — the same meaning in more than one place. Costs tokens and maintenance, and inflates a meaning's apparent importance. Keep one source of truth.
+- **Negation** — steering by prohibition backfires: *"don't think of an elephant"* names the elephant. State the **positive** target behavior; keep a prohibition only as a hard guardrail you can't phrase positively, and pair it with what to do instead.
+
+**This is the checklist the quarterly harness-assumption review runs** (DECISIONS.md cadence): the review's question — *what scaffolding can be removed because the model now handles it natively?* — is the no-op and sediment hunt applied across every skill.
 
 ### Leading words
 
-A **leading word** is a compact concept already in the model's pretraining that anchors a whole
-region of behavior in one token — *tight* (loop), *watermelon*, *default-to-refute*, *silent drift*,
-*Summary Gate*. Repeated across a skill, it accumulates a distributed definition and recruits priors
-the model already holds. A triad spelled out at three sites (*"fast, deterministic, low-overhead"*)
-is begging to **collapse** into one word (*tight*). You win twice: fewer tokens, and a sharper hook
-the agent hangs its behavior on. Hunt every skill for restatements a leading word retires.
+A **leading word** is a compact concept already in the model's pretraining that anchors a whole region of behavior in one token — *tight* (loop), *watermelon*, *default-to-refute*, *silent drift*, *Summary Gate*. Repeated across a skill, it accumulates a distributed definition and recruits priors the model already holds. A triad spelled out at three sites (*"fast, deterministic, low-overhead"*) is begging to **collapse** into one word (*tight*). You win twice: fewer tokens, and a sharper hook the agent hangs its behavior on. Hunt every skill for restatements a leading word retires.
 
 ### Invocation (advisory)
 
-The Agent-Skills world splits skills by *who can invoke them* — **model-invoked** (description always
-loaded, agent can auto-fire it, pays permanent context load) vs **user-invoked** (invisible to the
-agent, human-only, zero context load). PMOS's model differs — skills are **retrieved on demand**
-(see the retrieval rationale under *Ecosystem compatibility* below), so Level-1 frontmatter is the
-always-available trigger and there is no auto-fire to gate. Treat the axis as an authoring lens —
-*is this skill's description earning its keep as an always-available trigger?* — **not** a required
-field. (A formal `invocation:` key is a deferred registry question, not part of this format.)
+The Agent-Skills world splits skills by *who can invoke them* — **model-invoked** (description always loaded, agent can auto-fire it, pays permanent context load) vs **user-invoked** (invisible to the agent, human-only, zero context load). PMOS's model differs — skills are **retrieved on demand** (see the retrieval rationale under *Ecosystem compatibility* below), so Level-1 frontmatter is the always-available trigger and there is no auto-fire to gate. Treat the axis as an authoring lens — *is this skill's description earning its keep as an always-available trigger?* — **not** a required field. (A formal `invocation:` key is a deferred registry question, not part of this format.)
 
 ## Ecosystem compatibility — the Agent Skills standard
 
-The open **Agent Skills standard** (Claude Code, Codex, and other harnesses) packages a skill as a
-**directory** `<skill-name>/SKILL.md` with YAML frontmatter (`name`, `description`, optionally
-`license`, `allowed-tools`) plus bundled sub-files. It **validates PMOS's three-level disclosure** —
-same frontmatter-as-trigger, body-as-procedure, sub-files-on-demand shape.
+The open **Agent Skills standard** (Claude Code, Codex, and other harnesses) packages a skill as a **directory** `<skill-name>/SKILL.md` with YAML frontmatter (`name`, `description`, optionally `license`, `allowed-tools`) plus bundled sub-files. It **validates PMOS's three-level disclosure** — same frontmatter-as-trigger, body-as-procedure, sub-files-on-demand shape.
 
-PMOS **diverges** deliberately: skills are flat `<name>.skill` files, **not** `<name>/SKILL.md`
-directories. The rationale is PMOS's retrieval model — skills are fetched on demand via `get_skill`
-or referenced from AGENTS.md, **not** auto-discovered by a harness scanning for `SKILL.md`, so the
-directory ceremony buys nothing here. The **mapping is lossless**, which is what keeps the divergence
-cheap:
+PMOS **diverges** deliberately: skills are flat `<name>.skill` files, **not** `<name>/SKILL.md` directories. The rationale is PMOS's retrieval model — skills are fetched on demand via `get_skill` or referenced from AGENTS.md, **not** auto-discovered by a harness scanning for `SKILL.md`, so the directory ceremony buys nothing here. The **mapping is lossless**, which is what keeps the divergence cheap:
 
 - a `<name>.skill` file **≅** a standard `SKILL.md` body;
 - PMOS's required `name` + `description` frontmatter is **already** the standard's required pair;
 - Level-3 sub-files **≅** the standard's bundled files.
 
-(One nuance for the follow-on below: PMOS's *optional* D49 registry keys —
-`version`/`owner`/`risk`/`category`/`scope`/`lifecycle` — are top-level custom keys; the standard would expect
-producer-defined extensions under a `metadata:` map. The **core** shape is lossless; relocating the
-registry keys belongs to the native-format packaging follow-on, not this flat form.)
+(One nuance for the follow-on below: PMOS's *optional* D49 registry keys — `version`/`owner`/`risk`/`category`/`scope`/`lifecycle` — are top-level custom keys; the standard would expect producer-defined extensions under a `metadata:` map. The **core** shape is lossless; relocating the registry keys belongs to the native-format packaging follow-on, not this flat form.)
 
 ### Kit native-format packaging (E6 — shipped)
 
-The **kit** now ships every skill in native Agent-Skills directory form *as well as* the flat file —
-a lossless portability layer, generated **from** the flat `.skill` at build time (never
-hand-authored, so it cannot drift from its source). For each shipped skill, `kit/build-kit.sh` emits
-`skills-native/<name>/SKILL.md` where:
-
-- the directory name **equals** the frontmatter `name` (the standard's hard rule), and required
-  `name` + `description` are present;
-- PMOS's D49 registry keys (`version`/`owner`/`risk`/`category`/`scope`/`lifecycle`) are relocated
-  **under a `metadata:` map with a `pmos-` prefix** — the standard's producer-extension slot — never
-  as top-level custom keys, so a conformant runtime ignores them cleanly;
-- a **fail-closed conformance self-check** in `build-kit.sh` aborts the build on any violation
-  (name≠dirname, missing required field, or a top-level custom key), the same posture as the
-  containment check.
-
-The flat `.skill` files remain the file-mode source of truth (the AGENTS.md state adapter references
-`pmos/skills/<name>.skill`); the native tree is the ecosystem-portable mirror. **Still a named
-follow-on (not built here):** wiring `create-pmos` to install the native tree into a runtime's
-auto-discovery locations (`.claude/skills/`, `.agents/skills/`). E6 delivers the conformant
-*packaging*; the *install location* is a separate change, revisited when native-discovery demand in
-kit repos is proven.
+The **kit** now ships every skill in native Agent-Skills directory form *as well as* the flat file — a lossless portability layer, generated **from** the flat `.skill` at build time (never hand-authored, so it cannot drift from its source). For each shipped skill, `kit/build-kit.sh` emits `skills-native/<name>/SKILL.md` where:
+
+- the directory name **equals** the frontmatter `name` (the standard's hard rule), and required `name` + `description` are present;
+- PMOS's D49 registry keys (`version`/`owner`/`risk`/`category`/`scope`/`lifecycle`) are relocated **under a `metadata:` map with a `pmos-` prefix** — the standard's producer-extension slot — never as top-level custom keys, so a conformant runtime ignores them cleanly;
+- a **fail-closed conformance self-check** in `build-kit.sh` aborts the build on any violation (name≠dirname, missing required field, or a top-level custom key), the same posture as the containment check.
+
+The flat `.skill` files remain the file-mode source of truth (the AGENTS.md state adapter references `pmos/skills/<name>.skill`); the native tree is the ecosystem-portable mirror. **Still a named follow-on (not built here):** wiring `create-pmos` to install the native tree into a runtime's auto-discovery locations (`.claude/skills/`, `.agents/skills/`). E6 delivers the conformant *packaging*; the *install location* is a separate change, revisited when native-discovery demand in kit repos is proven.
 
 ### Per-skill eval harness (E8 — convention shipped, benchmark deferred)
 
-A skill may carry an **opt-in** eval file at `skills/evals/<name>.evals.json` (mapping to the
-standard's `<name>/evals/evals.json` in native packaging), adopting the skill-creator harness shape:
+A skill may carry an **opt-in** eval file at `skills/evals/<name>.evals.json` (mapping to the standard's `<name>/evals/evals.json` in native packaging), adopting the skill-creator harness shape:
 
-- **`description_triggers`** — `should_fire` / `should_not_fire` prompt lists that test whether the
-  L1 description fires on the right requests and stays silent on the wrong ones (trigger-accuracy).
-- **`cases`** — each a `{ name, prompt, expect, with_without }`, where `expect` is an **outcome
-  property** a grader checks (never a script) and `with_without` toggles whether the case is meant
-  for with-vs-without-the-skill benchmarking.
+- **`description_triggers`** — `should_fire` / `should_not_fire` prompt lists that test whether the L1 description fires on the right requests and stays silent on the wrong ones (trigger-accuracy).
+- **`cases`** — each a `{ name, prompt, expect, with_without }`, where `expect` is an **outcome property** a grader checks (never a script) and `with_without` toggles whether the case is meant for with-vs-without-the-skill benchmarking.
 
-`scripts/check_skill_evals.py` (run in the `okf-drift` job) validates the **shape** of any present
-eval file and that it names a real skill. It **never runs a benchmark** — actually scoring
-with-vs-without needs labeled outcomes + compute and is **deferred** (there is no negative class
-yet); running models in CI would make the gate nondeterministic. The convention and a worked example
-(`skills/evals/prd.evals.json`) ship now; the verdict "this skill measurably helps" does not.
+`scripts/check_skill_evals.py` (run in the `okf-drift` job) validates the **shape** of any present eval file and that it names a real skill. It **never runs a benchmark** — actually scoring with-vs-without needs labeled outcomes + compute and is **deferred** (there is no negative class yet); running models in CI would make the gate nondeterministic. The convention and a worked example (`skills/evals/prd.evals.json`) ship now; the verdict "this skill measurably helps" does not.
 
 ## File naming
 
@@ -232,9 +133,7 @@ yet); running models in CI would make the gate nondeterministic. The convention
 
 A skill is well-formed when:
 
-1. Level 1 frontmatter has `name` + `description` (both required), plus optionally `maturity_mode` (on
-   non-active skills) and the Phase-B registry keys `version`/`owner`/`risk`/`category`/`scope`/
-   `lifecycle` (D49); no other L1 keys.
+1. Level 1 frontmatter has `name` + `description` (both required), plus optionally `maturity_mode` (on non-active skills) and the Phase-B registry keys `version`/`owner`/`risk`/`category`/`scope`/ `lifecycle` (D49); no other L1 keys.
 2. `name` matches the filename stem.
 3. `description` states both what the skill does and when to use it.
 4. The body (Level 2) carries the full procedure and is self-sufficient for the common case.
@@ -242,13 +141,9 @@ A skill is well-formed when:
 
 **Quality bar** (the "good", not just "well-formed" — see Quality above):
 
-6. **Predictability served** — every line makes the agent's *process* more repeatable; cut what
-   doesn't.
-7. **Per-step completion criteria** — each procedural step ends on a checkable (and where it matters
-   exhaustive) done-condition, not a vague "do X".
-8. **Pruned** — no no-ops, no sediment, no duplication; prohibitions phrased as positive targets;
-   sprawl disclosed to Level 3.
+6. **Predictability served** — every line makes the agent's *process* more repeatable; cut what doesn't.
+7. **Per-step completion criteria** — each procedural step ends on a checkable (and where it matters exhaustive) done-condition, not a vague "do X".
+8. **Pruned** — no no-ops, no sediment, no duplication; prohibitions phrased as positive targets; sprawl disclosed to Level 3.
 9. **Leading words** — restated qualities collapsed into pretrained tokens where one earns its keep.
 
-All seed skills are authored against this checklist; the quarterly harness-assumption review re-runs
-items 6–9 across every skill.
+All seed skills are authored against this checklist; the quarterly harness-assumption review re-runs items 6–9 across every skill.

package/payload/skills/harness-refine.skill

@@ -87,8 +87,9 @@ field's "agents improving their own tools" loop while staying at the **L3 ceilin
   bounding decision [D47](/okf/products/pmos/adr/d47-self-refining-harness.md).
 - 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: [v_friction_recurrence](/okf/products/pmos/references/metrics/v_friction_recurrence.md),
-  [v_context_budget](/okf/products/pmos/references/metrics/v_context_budget.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
+  `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
   review); the altitude standard: [agent-harness](/okf/core/concepts/agent-harness.md).

package/payload/skills/ingest-repo.skill

@@ -13,8 +13,8 @@ scope: read:tenant-repo, write:tenant-okf-drafts, write:product_repos
 This skill is the **existing-repo on-ramp**: a PM arrives with a product that already ships and already
 has a repo, and PMOS needs knowledge of it so a build agent doesn't cold-start on every run (re-deriving
 the stack, assuming wrong, producing work the PM must heavily correct — the north-star cost). It is the
-**inverse of [analyze-product-infra](/build-skills/analyze-product-infra.skill)** (which goes PRD →
-what the product *needs*): ingest-repo goes **code → what the product *is***. It emits a **draft** OKF
+**inverse** of deriving an infrastructure spec from a PRD (PRD → what the product *needs*):
+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
@@ -101,18 +101,19 @@ reference layer + a repo registration and then **stops for PM approval**.
 - **`register_product_repo` semantics:** designed for provisioning output — here `app_surface`/
   `backend_model` are *observed*, a usage-only difference (no schema change); note it.
 - **B5 measurability:** the value thesis is "warm start → fewer corrections"; the first post-ingest
-  build run should retrieve these concepts (B5 > 0 for the tenant, via
-  [v_knowledge_reuse](/okf/products/pmos/references/metrics/v_knowledge_reuse.md) — now written by
-  get_okf_concepts FETCH). That real correction-delta, not the doc count, is the win.
+  build run should retrieve these concepts. That real correction-delta, not the doc count, is the
+  win — measure it as corrections on the first post-ingest run versus the cold-start baseline.
+  (The hosted `v_knowledge_reuse` view that automated this count went with the backend in D66.)
 
 ## Level 3 — references
 
-- The write path + PM gate: [okf-author](/build-skills/okf-author.skill) Mode B, [D37](/okf/products/pmos/adr/d37-tenant-okf-db-native.md).
+- The write path + PM gate: write the docs into the product's own repo as drafts and let the PM
+  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).
-- Scan location: [D51](/okf/products/pmos/adr/d51-scan-location.md). Registry:
-  [register_product_repo](/okf/products/pmos/references/mcp-tools/register_product_repo.md),
-  [product_repos](/okf/products/pmos/data-model/product_repos.md).
-- Sibling on-ramps: [analyze-product-infra](/build-skills/analyze-product-infra.skill),
-  [product-onboarding playbook](/okf/core/playbooks/product-onboarding.md).
+- 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.
+- Sibling on-ramp: [product-onboarding playbook](/okf/core/playbooks/product-onboarding.md).

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

@@ -82,8 +82,9 @@ field's "agents improving their own tools" loop while staying at the **L3 ceilin
   bounding decision [D47](/okf/products/pmos/adr/d47-self-refining-harness.md).
 - 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: [v_friction_recurrence](/okf/products/pmos/references/metrics/v_friction_recurrence.md),
-  [v_context_budget](/okf/products/pmos/references/metrics/v_context_budget.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
+  `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
   review); the altitude standard: [agent-harness](/okf/core/concepts/agent-harness.md).

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

@@ -15,8 +15,8 @@ metadata:
 This skill is the **existing-repo on-ramp**: a PM arrives with a product that already ships and already
 has a repo, and PMOS needs knowledge of it so a build agent doesn't cold-start on every run (re-deriving
 the stack, assuming wrong, producing work the PM must heavily correct — the north-star cost). It is the
-**inverse of [analyze-product-infra](/build-skills/analyze-product-infra.skill)** (which goes PRD →
-what the product *needs*): ingest-repo goes **code → what the product *is***. It emits a **draft** OKF
+**inverse** of deriving an infrastructure spec from a PRD (PRD → what the product *needs*):
+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
@@ -103,18 +103,19 @@ reference layer + a repo registration and then **stops for PM approval**.
 - **`register_product_repo` semantics:** designed for provisioning output — here `app_surface`/
   `backend_model` are *observed*, a usage-only difference (no schema change); note it.
 - **B5 measurability:** the value thesis is "warm start → fewer corrections"; the first post-ingest
-  build run should retrieve these concepts (B5 > 0 for the tenant, via
-  [v_knowledge_reuse](/okf/products/pmos/references/metrics/v_knowledge_reuse.md) — now written by
-  get_okf_concepts FETCH). That real correction-delta, not the doc count, is the win.
+  build run should retrieve these concepts. That real correction-delta, not the doc count, is the
+  win — measure it as corrections on the first post-ingest run versus the cold-start baseline.
+  (The hosted `v_knowledge_reuse` view that automated this count went with the backend in D66.)
 
 ## Level 3 — references
 
-- The write path + PM gate: [okf-author](/build-skills/okf-author.skill) Mode B, [D37](/okf/products/pmos/adr/d37-tenant-okf-db-native.md).
+- The write path + PM gate: write the docs into the product's own repo as drafts and let the PM
+  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).
-- Scan location: [D51](/okf/products/pmos/adr/d51-scan-location.md). Registry:
-  [register_product_repo](/okf/products/pmos/references/mcp-tools/register_product_repo.md),
-  [product_repos](/okf/products/pmos/data-model/product_repos.md).
-- Sibling on-ramps: [analyze-product-infra](/build-skills/analyze-product-infra.skill),
-  [product-onboarding playbook](/okf/core/playbooks/product-onboarding.md).
+- 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.
+- Sibling on-ramp: [product-onboarding playbook](/okf/core/playbooks/product-onboarding.md).

package/workspace/lib/drive-guard.js

@@ -61,6 +61,7 @@
  * something does adopt it, it will not adopt seven bypasses with it.
  */
 
+const fs = require('fs');
 const path = require('path');
 
 class ForbiddenWrite extends Error {
@@ -117,29 +118,69 @@ const ALLOWED_DIR_PREFIXES = Object.freeze([
 const ALLOWED_FILES = Object.freeze([
   'planning/runs/agent-runs.jsonl',
   'planning/runs/verify-queue.jsonl',
-  'planning/runs/work-items.jsonl',
+  /* `planning/work-items.jsonl`, NOT `planning/runs/work-items.jsonl`. The latter was allowlisted
+   * here for weeks and has never existed — scripts/work-item.js records that directly. An allowlist
+   * entry for a path that does not exist permits nothing and protects nothing; what it does is make
+   * the list look like it covers the factory's ledger when it does not. Found by an independent pass
+   * comparing this list against pmos/graph-membership.json, which is the whole argument for the
+   * derivation below: two enumerations of the same thing disagree, and nothing notices. */
+  'planning/work-items.jsonl',
   'discoveries.md',
 ]);
 
 /** Kept for the refusal message only — never for deciding permission. */
 const ALLOWED_BASENAMES = Object.freeze(ALLOWED_FILES.map((f) => path.posix.basename(f)));
 
-/** Named explicitly so the refusal says WHY, rather than "not on the allowlist". Each of these
- *  would otherwise be caught by the allowlist anyway — the value here is the message. */
-const HUMAN_DECISION_SINKS = Object.freeze({
-  // The module argues that a DIRECTORY prefix "would admit the FOURTH ledger somebody adds next year
-  // without anyone deciding to — exactly the class-failure this rewrite exists to close" — and then
-  // allows `planning/evals/` as a prefix, which admits the PM's own override log and any future
-  // planning/evals/*.jsonl. The argument is right; it just was not applied to its own second
-  // directory. These two are the PM's calibration record, not the driver's scratch space.
-  'eval-calibration.md': 'the PM\'s log of every override of an evaluator verdict is the PM\'s (D40)',
-  'calibration-status.md': 'the declared calibration state is the PM\'s to assert, not the driver\'s',
-  'acceptances.jsonl': 'the Acceptance Gate is the PM\'s and non-delegable (D12)',
-  'evals.jsonl': 'a Review-Gate verdict on the driver\'s own work is self-grading — the driver may not record one (D40)',
-  'outcome_checks.jsonl': 'whether the bet paid off is the PM\'s judgement (D57)',
-  'DECISIONS.md': 'an architectural decision is the PM\'s (D45)',
-  'pm-decisions.md': 'the PM\'s decision journal is the PM\'s',
-});
+/** ── DERIVED FROM THE REGISTRY, NOT RESTATED ────────────────────────────────────────────────────
+ *
+ *  This was an inline map of seven basenames to reasons — a second enumeration of exactly the
+ *  control-graph classification that `pmos/graph-membership.json` holds, with the D-numbers mirrored
+ *  in both. Two copies of a rule are two places for it to be wrong, and these two ALREADY disagreed:
+ *  the allowlist above named a ledger that has never existed while the registry named the real one.
+ *
+ *  So the reasons come from the registry's `why` for every record it classifies `control`. Keyed by
+ *  basename, because that is what the refusal path looks up.
+ *
+ *  FAIL-OPEN IS NOT A RISK HERE, and it is worth saying why rather than trusting it: this map only
+ *  supplies the REASON in a refusal message. Permission is decided by `onAllowlist` below, which
+ *  refuses everything not sanctioned whether or not a reason was found. If the registry is missing —
+ *  a vendored kit, a partial checkout — the write is still refused; the message is just the generic
+ *  one. A guard whose enforcement depended on a file it might not have would be a different and much
+ *  worse design. */
+let REGISTRY_UNAVAILABLE = null;
+function loadHumanDecisionSinks() {
+  const out = {};
+  try {
+    /* TWO LAYOUTS, the same two-path resolution scripts/md-newlines.js uses for its normalizer.
+     *
+     * In a checkout this file is `<repo>/workspace/lib/`, so the registry is two levels up. In an
+     * npm install the workspace app is bundled BESIDE the vendored kit, not inside it, so the
+     * registry — if the adopter has one — is `<install>/pmos/graph-membership.json`. Neither path
+     * is guaranteed, and that is fine: this map only supplies the REASON in a refusal message.
+     * The write is refused either way by `onAllowlist` below. */
+    const tried = [
+      path.join(__dirname, '..', '..', 'pmos', 'graph-membership.json'),   // a checkout
+      path.join(__dirname, '..', '..', '..', 'pmos', 'graph-membership.json'), // beside a vendored kit
+    ];
+    const found = tried.find((f) => { try { return fs.statSync(f).isFile(); } catch { return false; } });
+    if (!found) throw new Error(`no graph-membership.json in: ${tried.join(', ')}`);
+    const raw = fs.readFileSync(found, 'utf8');
+    for (const r of (JSON.parse(raw).records || [])) {
+      if (!r || r.graph !== 'control' || typeof r.path !== 'string' || r.path.endsWith('/')) continue;
+      const base = path.posix.basename(r.path);
+      if (ALLOWED_BASENAMES.includes(base)) continue;   // the driver's own sanctioned ledgers
+      if (!out[base]) out[base] = String(r.why || 'a control-graph record — the PM\'s, not the driver\'s');
+    }
+  } catch (e) {
+    /* RECORDED, not swallowed. The first version caught silently, and a missing `require('fs')` in
+     * this very file turned into an empty map with no signal at all — every reasoned refusal quietly
+     * became the generic one and two suite assertions were the only thing that noticed. A catch that
+     * hides its own cause is how a degradation becomes permanent. */
+    REGISTRY_UNAVAILABLE = e && e.message ? e.message : String(e);
+  }
+  return out;
+}
+const HUMAN_DECISION_SINKS = Object.freeze(loadHumanDecisionSinks());
 
 /** Disposition tokens (D60), widened to the bare verbs bypass 4 slipped through, and anchored so a
  *  status VALUE that begins with one is a disposition while prose mentioning one is not. */
@@ -530,5 +571,6 @@ function guardedWriter(write) {
 
 module.exports = {
   assertWritable, guardedWriter, carriesApproval, carriesDisposition, isDisposition, PROSE_LEAD, ForbiddenWrite,
-  ALLOWED_DIR_PREFIXES, ALLOWED_BASENAMES, HUMAN_DECISION_SINKS, DISPOSITION_RE,
+  ALLOWED_DIR_PREFIXES, ALLOWED_FILES, ALLOWED_BASENAMES, HUMAN_DECISION_SINKS, DISPOSITION_RE,
+  registryUnavailable: () => REGISTRY_UNAVAILABLE,
 };

package/workspace/lib/engine/anchor-resolve.js

@@ -196,8 +196,31 @@ function readBudgets(root) {
  * `index` comes from parseOkrIndex; `budgets` from readBudgets (optional — omit to skip the
  * registry check, which callers that only need the FORM can do).
  */
+/** Strip ONE layer of matching surrounding quotes.
+ *
+ *  `parent_kr` is a YAML scalar, and a value whose prose contains a colon-space MUST be quoted or
+ *  the document does not parse. The flat frontmatter reader hands the value through with its quotes
+ *  intact, so a legitimately-quoted anchor arrived here as `"health:security …` and matched no form.
+ *
+ *  This defect occurred TWICE — `sink-discipline-backport` on 2026-08-04 and
+ *  `separation-invariant-enforcement` on 2026-08-05 — and the first time it was fixed by unquoting
+ *  the one file. That is the wave's own lesson landing on the person who wrote it down: the unit of
+ *  attention was the file, the unit of the defect was the rule. "Do not quote it" is a rule that
+ *  lives in prose and depends on an author remembering; tolerating the quoting is a rule that lives
+ *  in code.
+ *
+ *  Only a MATCHING outer pair, and only one layer: a stray leading quote is still malformed, and
+ *  reporting it as such is the point. */
+function unquote(s) {
+  const t = s.trim();
+  if (t.length >= 2 && ((t[0] === '"' && t[t.length - 1] === '"') || (t[0] === "'" && t[t.length - 1] === "'"))) {
+    return t.slice(1, -1).trim();
+  }
+  return t;
+}
+
 function resolveAnchor(raw, index, budgets) {
-  const original = String(raw == null ? '' : raw).trim();
+  const original = unquote(String(raw == null ? '' : raw).trim());
   const base = { raw: original, kind: 'empty', status: 'empty', objective: null, kr: null, budget: null, period: null, form: null, reason: null };
   if (!original) return Object.assign(base, { reason: 'parent_kr is empty — unanchored work is rejected (D59)' });
 
@@ -269,6 +292,7 @@ function canonical(resolved, fallbackPeriod) {
 }
 
 module.exports = {
+  unquote,
   parseOkrIndex, readBudgets, resolveAnchor, canonical,
   objectiveId, krId, stripCommentary, listOkrFiles,
   ACCEPTED_FORMS,

package/workspace/lib/sink.js

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+'use strict';
+/* sink.js — the ONE place the append-only ledger discipline lives.
+ *
+ * ── WHY THIS FILE EXISTS ────────────────────────────────────────────────────────────────────────
+ * `record-eval.js` was PMOS's first validated writer. Three independent passes found four defects in
+ * it, and all four were fixed IN THAT FILE:
+ *
+ *   1. the sink was a caller-supplied allowlist   -> a caller could name its own destination
+ *   2. the file was opened before validation      -> N refused writes leaked N descriptors to EMFILE
+ *   3. a refused write still created the sink     -> refusing to write left the file behind
+ *   4. the symlink check was a path-level stat    -> a hardlink walked straight through it
+ *
+ * Two writers built afterwards inherited the fixes BY HAND, and each inheritance read as evidence
+ * that the pattern was holding. It was not holding — it was propagating FORWARD ONLY. The two
+ * writers that already existed when the defects were found were never revisited, because the process
+ * asks "does the new thing follow the rule?" and never "where else does this rule already live?"
+ *
+ * Measured by attempted write on 2026-08-04:
+ *
+ *   scripts/work-item.js     -> wrote 198 bytes through a symlink into a decoy
+ *   scripts/verify-queue.js  -> the same, AND wrote 202 bytes into a fresh tmpdir, because its
+ *                               allowlist compared `path.basename` alone. A basename is not a
+ *                               location; every directory on disk has one.
+ *
+ * Both are merged, PM-accepted, and load-bearing for D65 steps 1 and 2. So the discipline moves here
+ * and the writers call it. One wrong place that every assertion points at beats five where three
+ * happen to be right.
+ *
+ * ── THE RULE, STATED ONCE ───────────────────────────────────────────────────────────────────────
+ *   Resolve before allowing.  Validate before opening.  Write to the descriptor that was vetted.
+ *
+ * The third clause is the one that looks redundant and is not. A path checked and then re-opened by
+ * path is two operations on two objects: whatever was approved may not be what gets written. The fd
+ * IS the approval, so it is what the caller must be handed.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * THE `ForbiddenWrite`. One class, exported, re-exported by every writer that uses this guard.
+ *
+ * There were five of these — one per writer that had a guard at all — and that is not a cosmetic duplication. Callers and
+ * assertions tell "refused on purpose" from "crashed" with `instanceof`, so a guard throwing its own
+ * private copy makes every one of those checks silently false: `scripts/tests/work-item.sh` reported
+ * `threw ForbiddenWrite, want ForbiddenWrite` on seventeen assertions the moment this module started
+ * throwing a second class with the same name. A refusal nobody can recognise as a refusal is not one.
+ *
+ * `detail` is always set (null when absent) rather than conditionally attached, because a property
+ * that sometimes exists is a second shape for callers to handle.
+ */
+class ForbiddenWrite extends Error {
+  constructor(message, detail) {
+    super(message);
+    this.name = 'ForbiddenWrite';
+    this.detail = detail || null;
+  }
+}
+
+/** Resolve a path through its real directory. Kept separate so the sink and the target are compared
+ *  the same way — comparing a resolved target against an unresolved sink is a mismatch by
+ *  construction, and would refuse every legitimate write on a machine where /tmp is a symlink. */
+function resolveThrough(p) {
+  return path.join(fs.realpathSync(path.dirname(path.resolve(p))), path.basename(p));
+}
+
+/**
+ * Build a guard bound to ONE sink.
+ *
+ * @param {object} spec
+ * @param {string} spec.sink     absolute path of the only file this guard will ever open.
+ * @param {string} spec.what     noun for error messages, e.g. 'work-item events'.
+ * @returns {{ open: function, sinkPath: function, __setSinkForTests: function }}
+ *
+ * The sink is a CONSTRUCTION-TIME constant, never an argument to `open`. That is defect 1 of the
+ * original four, and re-admitting it as "just a parameter" is how it would come back.
+ */
+function createSinkGuard(spec) {
+  if (!spec || typeof spec.sink !== 'string' || !spec.sink) {
+    throw new ForbiddenWrite('a sink guard needs a declared `sink` path — refused (fail-closed)');
+  }
+  const what = spec.what || 'records';
+  const declared = spec.sink;
+  let overrideForTests = null;
+
+  /* A seam, not a door. Gated so it cannot be reached in a production process even if something
+   * calls it — the point of A4 is that no code path lets a caller choose the destination. */
+  function __setSinkForTests(p) {
+    /* An explicit allowed set. `!process.env.PMOS_TEST` treats the STRING '0' as truthy, so
+     * PMOS_TEST=0 — the natural way an operator turns test mode OFF — OPENED the production sink
+     * override instead of closing it. A flag whose "off" value means "on" is worse than no flag. */
+    const on = (v) => v === '1' || v === 'true' || v === 'yes';
+    if (process.env.NODE_ENV !== 'test' && !on(process.env.PMOS_TEST)) {
+      throw new ForbiddenWrite('__setSinkForTests is a test seam — set NODE_ENV=test or PMOS_TEST=1 to use it');
+    }
+    overrideForTests = p;
+  }
+
+  const sinkPath = () => overrideForTests || declared;
+
+  /**
+   * Pre-flight: validate the record and confirm the target RESOLVES to the sink — without opening
+   * anything. For callers that want to ask "would this be permitted?" without a side effect.
+   *
+   * NOT AUTHORITATIVE, and the gap is deliberate rather than an oversight. Whether the sink is a
+   * symlink or carries a second hard link cannot be established without a descriptor, and a `lstat`
+   * here would answer about a path that may differ from the file eventually opened — which is the
+   * check-then-write race this module exists to close. `open` is the authority; this is a courtesy.
+   * The suite asserts the difference: a symlinked sink passes `check` and is refused by `open`.
+   */
+  function check(targetPath, validate) {
+    if (typeof targetPath !== 'string' || !targetPath) {
+      throw new ForbiddenWrite(`no target path supplied for ${what} — refused (fail-closed)`);
+    }
+    if (typeof validate === 'function') {
+      const v = validate();
+      if (!v || !v.ok) {
+        const errs = (v && v.errors) || ['invalid'];
+        throw new ForbiddenWrite(`invalid ${what} — refused: ${errs.join('; ')}`, { errors: errs });
+      }
+    }
+    let resolved;
+    try { resolved = resolveThrough(targetPath); }
+    catch { throw new ForbiddenWrite(`the sink directory does not resolve for '${targetPath}' — refused (fail-closed)`); }
+    let sinkResolved = sinkPath();
+    try { sinkResolved = resolveThrough(sinkPath()); } catch { /* not created yet */ }
+    if (resolved !== sinkResolved) {
+      throw new ForbiddenWrite(
+        `${what} are written only to ${sinkResolved}; '${targetPath}' resolves to '${resolved}'`,
+        { targetPath, resolved, sink: sinkResolved });
+    }
+    return true;
+  }
+
+  /**
+   * Vet `targetPath` against the declared sink and return a descriptor open for append.
+   *
+   * The caller MUST close it. Everything that can refuse, refuses before the file is opened, so a
+   * refusal creates nothing and leaks nothing.
+   *
+   * @param {string} targetPath   where the caller believes it is writing.
+   * @param {function} [validate] returns { ok, errors } — runs BEFORE the open (defects 2 and 3).
+   * @returns {number} a vetted file descriptor.
+   */
+  function open(targetPath, validate) {
+    if (typeof targetPath !== 'string' || !targetPath) {
+      throw new ForbiddenWrite(`no target path supplied for ${what} — refused (fail-closed)`);
+    }
+
+    /* BEFORE the open. Ordering is the whole of defects 2 and 3: validating after opening leaks a
+     * descriptor per refusal, and O_CREAT means the refused write has already made the file. */
+    if (typeof validate === 'function') {
+      const v = validate();
+      if (!v || !v.ok) {
+        const errs = (v && v.errors) || ['invalid'];
+        throw new ForbiddenWrite(`invalid ${what} — refused: ${errs.join('; ')}`, { errors: errs });
+      }
+    }
+
+    let resolved;
+    try {
+      resolved = resolveThrough(targetPath);
+    } catch {
+      throw new ForbiddenWrite(`the sink directory does not resolve for '${targetPath}' — refused (fail-closed)`);
+    }
+    let sinkResolved = sinkPath();
+    try { sinkResolved = resolveThrough(sinkPath()); } catch { /* not created yet — compare literally */ }
+
+    /* A RESOLVED comparison, not a basename one. `verify-queue.js` compared basenames and therefore
+     * accepted every directory on disk that happened to contain the right filename. */
+    if (resolved !== sinkResolved) {
+      throw new ForbiddenWrite(
+        `${what} are written only to ${sinkResolved}; '${targetPath}' resolves to '${resolved}'`,
+        { targetPath, resolved, sink: sinkResolved });
+    }
+
+    let fd;
+    try {
+      fd = fs.openSync(
+        resolved,
+        fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_APPEND
+          | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK,
+        0o644);
+    } catch (e) {
+      /* O_NOFOLLOW turns "the sink is a symlink" into ELOOP here rather than a silent write to
+       * wherever it pointed. That is defect 4, and it is refused at open rather than by a stat that
+       * a hardlink does not answer.
+       *
+       * O_NONBLOCK is not about performance. Opening a FIFO for writing BLOCKS until a reader
+       * arrives, so a named pipe left at the sink path hangs the writer forever — found by the
+       * assertion below, which hung this suite past its timeout instead of failing. A refusal that
+       * never returns is worse than a wrong answer: nothing reports it and nothing times it out.
+       * With O_NONBLOCK the same case returns ENXIO immediately and lands in the refusal path, and
+       * on a regular file the flag does nothing at all. */
+      throw new ForbiddenWrite(
+        `cannot open the ${what} ledger at '${targetPath}' safely (${e.code || e.message}) — refused (fail-closed)`,
+        { code: e.code });
+    }
+
+    try {
+      /* fstat on the FD, not stat on the path: for the FINAL component this genuinely closes the
+       * check-then-open race — an independent pass swapped the target inside the resolve→open window
+       * with perfect timing and got ELOOP, nlink=2 and a refusal every time.
+       *
+       * It does NOT cover the PARENT directory. `resolveThrough` realpaths the directory and
+       * `openSync` then re-walks that resolved path, so a local process able to rename the sink's
+       * parent and drop a directory symlink in its place inside that window can redirect the append
+       * — measured, 195 bytes into a foreign directory. That needs a concurrently-racing local
+       * attacker with write access to the parent, a strictly larger capability than the symlink
+       * defect this module was built to fix, so it is stated rather than claimed away. Closing it
+       * properly needs openat-style descent, which Node does not expose. The header's "the fd IS the
+       * approval" is true of the file, not of the path walked to reach it. */
+      const st = fs.fstatSync(fd);
+      if (!st.isFile()) {
+        throw new ForbiddenWrite(`'${targetPath}' is not a regular file — refused (fail-closed)`);
+      }
+      if (st.nlink !== 1) {
+        throw new ForbiddenWrite(
+          `'${targetPath}' has ${st.nlink} hard links; a ledger with a second name is not one this ` +
+          'writer controls — refused (fail-closed)', { nlink: st.nlink });
+      }
+    } catch (e) {
+      fs.closeSync(fd);
+      throw e;
+    }
+
+    return fd;
+  }
+
+  /**
+   * The whole write, start to finish: vet, append one JSON line, close. Callers should prefer this
+   * over `open` — it is the shape that cannot forget to close, and every existing writer's append is
+   * exactly one line.
+   */
+  function appendLine(targetPath, record, validate) {
+    const fd = open(targetPath, validate);
+    const line = JSON.stringify(record) + '\n';
+    const want = Buffer.byteLength(line);
+    try {
+      /* THE RETURN VALUE IS NOT OPTIONAL. This was `fs.writeSync(fd, line)` with the result
+       * discarded, which reports a SHORT WRITE as success. Forced on a 64K tmpfs: a normal-shaped
+       * record returned true having appended a 3901-byte fragment with no trailing newline, and the
+       * next append CONCATENATED onto it — so one ENOSPC destroys two records and leaves a single
+       * line that no reader can parse. This is the append-only system of record, every reader
+       * JSON.parses line by line, and all six writers route through this one call.
+       *
+       * Loop, because a partial write is not necessarily an error — then verify the total. A torn
+       * tail is worse than a refused write, so if the bytes did not all land, say so loudly rather
+       * than returning true over a corrupted ledger. */
+      /* The size BEFORE this append, taken from the vetted fd. This is what makes the failure path a
+       * real refusal instead of a report: if the write tears, the file is truncated back to here and
+       * the ledger is left exactly as it was found. `nlink === 1` was already proven above, so no
+       * other name for this file exists and the rollback cannot reach anyone else's data. */
+      const before = fs.fstatSync(fd).size;
+      const buf = Buffer.from(line, 'utf8');
+      let written = 0;
+      let cause = null;
+      try {
+        while (written < want) {
+          const n = fs.writeSync(fd, buf, written, want - written);
+          if (!(n > 0)) break;           // no progress: stop rather than spin
+          written += n;
+        }
+      } catch (e) {
+        /* ENOSPC does NOT arrive as a short write. Measured on a full tmpfs: the first writeSync
+         * short-writes 376 of 440 bytes with no error and the SECOND one throws — so a version that
+         * only checked `written !== want` never reached its own error path, and a raw Error escaped
+         * with name 'Error'. Everything in this repo tells a deliberate refusal from a crash with
+         * `instanceof ForbiddenWrite` (workspace/test.js:1772 checks e.name), so an unwrapped throw
+         * on the worst outcome this module has is the one place that signal must not be missing. */
+        cause = e;
+      }
+
+      if (cause || written !== want) {
+        /* THE ROLLBACK MUST NOT DESTROY SOMEONE ELSE'S RECORD, and the first version did.
+         *
+         * It called ftruncateSync(fd, before) unconditionally. `before` was measured at the top of
+         * this function, so ANY append by another process in between — a complete, successful,
+         * returned-true append — was inside the range being truncated away. Measured by an
+         * independent pass across 5 of 5 rounds: records whose write returned `true` were missing
+         * from disk afterwards, and the ledger was NUL-padded. A rollback that eats a committed
+         * record is worse than the torn line it was added to prevent.
+         *
+         * O_APPEND makes the arithmetic decidable: our bytes are the last `written` of the file if
+         * and only if nobody else appended. So truncate ONLY when the file is exactly the size our
+         * own write would have made it. Otherwise the tail is not ours to remove, and the honest
+         * outcome is to say the ledger is torn rather than to fix it by deleting a stranger's data. */
+        let rolledBack = false;
+        let intervened = false;
+        try {
+          const now = fs.fstatSync(fd).size;
+          if (now === before + written) { fs.ftruncateSync(fd, before); rolledBack = true; }
+          else intervened = true;          // another writer appended; the tail is not ours
+        } catch { /* reported below */ }
+
+        const detail = { written, want, before, rolledBack, intervened, code: cause && cause.code };
+        throw new ForbiddenWrite(
+          `partial append to the ${what} ledger: ${written} of ${want} bytes landed` +
+          (cause ? ` (${cause.code || cause.message})` : '') + '. ' +
+          (rolledBack
+            ? 'The ledger was truncated back to its pre-write size, so nothing was written and the ' +
+              'next append will not concatenate onto a fragment.'
+            : intervened
+              ? 'NOT ROLLED BACK ON PURPOSE — another writer appended while this write was failing, ' +
+                'so the bytes at the end of the file are not this one\'s to remove. The ledger holds ' +
+                'a torn fragment that must be repaired by hand; truncating it here would have ' +
+                'deleted a record that committed successfully.'
+              : 'THE ROLLBACK ALSO FAILED — the ledger now ends in a torn line with no trailing ' +
+                'newline, and the next append WILL concatenate onto it, destroying a second record. ' +
+                'Repair it by hand before writing again.'),
+          detail);
+      }
+    } finally { fs.closeSync(fd); }
+    return true;
+  }
+
+  return { check, open, appendLine, sinkPath, __setSinkForTests };
+}
+
+module.exports = { createSinkGuard, ForbiddenWrite, resolveThrough };

package/workspace/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pmos-workspace",
-  "version": "0.28.0",
+  "version": "0.33.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pmos-workspace",
-      "version": "0.28.0",
+      "version": "0.33.0",
       "license": "MIT",
       "dependencies": {
         "@xterm/addon-fit": "^0.11.0",

package/workspace/package.json

@@ -1,8 +1,8 @@
 {
   "name": "pmos-workspace",
-  "version": "0.31.1",
+  "version": "0.33.0",
   "private": true,
-  "description": "PMOS Terminal Workspace \u2014 local companion hosting real PTYs beside the library and gates (D62)",
+  "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",
   "bin": {
     "pmos": "bin/pmos.js"
@@ -29,7 +29,7 @@
     "playwright-core": "^1.61.1",
     "ws": "^8.18.0"
   },
-  "//devDependencies": "design-parity's pixel axis only. Kept OUT of dependencies deliberately: `create-pmos workspace` installs this package with `npm install -g`, which takes dependencies and not devDependencies, so an adopter installing a local PM tool does not also install a screenshot differ. design-parity.js requires both optionally and degrades to text+style+geometry when they are absent, so the parity check still runs \u2014 it just stops measuring pixels, and says so.",
+  "//devDependencies": "design-parity's pixel axis only. Kept OUT of dependencies deliberately: `create-pmos workspace` installs this package with `npm install -g`, which takes dependencies and not devDependencies, so an adopter installing a local PM tool does not also install a screenshot differ. design-parity.js requires both optionally and degrades to text+style+geometry when they are absent, so the parity check still runs — it just stops measuring pixels, and says so.",
   "devDependencies": {
     "pixelmatch": "^7.1.0",
     "pngjs": "^7.0.0"

package/workspace/server.js

@@ -61,6 +61,7 @@ function ensureSpawnHelperExecutable() {
 ensureSpawnHelperExecutable();
 
 const { checkSurface } = require('./lib/surface-contract');
+const { createSinkGuard } = require('./lib/sink.js');
 const scheduleLogic = require('./lib/schedule-logic');
 const harness = require('./lib/harness-parse');
 const transcript = require('./lib/transcript-read');
@@ -4678,9 +4679,25 @@ async function handleRequest(req, res) {
     // A swallowed append + {ok:true} would light the gate green over a record that never landed —
     // exactly the false-green class D64 exists to delete. On write failure return HTTP 500 and
     // {ok:false}, and do NOT report success. The error text carries no header/secret content (D08).
+    /* THROUGH THE GUARD, not a bare append.
+     *
+     * This was `fs.appendFileSync(sink, ...)`. An independent pass attacked it through this very
+     * endpoint's write path: **42 bytes landed through a symlink and it returned {ok:true}**. And
+     * 37 of 49 live acceptance rows carry a `workspace` key that only THIS endpoint writes — so the
+     * guarded writer (scripts/record-acceptance.js) was the one nothing used, while the unguarded
+     * one had written three quarters of the system of record.
+     *
+     * The guard is constructed per resolved sink rather than as one module constant, because the
+     * acceptance ledger legitimately moves with the workspace — kit layout, or the install's own
+     * state/ on fallback. The allowlist therefore degenerates here (target === declared by
+     * construction) and that is stated rather than glossed: what this buys is O_NOFOLLOW, the
+     * `nlink === 1` check, and the torn-append rollback, which is precisely the attack that landed.
+     *
+     * `pm_label` is NOT validated against record-acceptance.js's stricter schema: that writer
+     * REQUIRES the label, this surface must not, and requiring it here would block the PM's click. */
     try {
       if (fallback) fs.mkdirSync(LEGACY_STATE, { recursive: true });   // the install's state/ may not exist yet
-      fs.appendFileSync(sink, JSON.stringify(rec) + '\n');
+      createSinkGuard({ sink, what: 'PM acceptances' }).appendLine(sink, rec);
     } catch (e) {
       warnWriteFail('acceptances.jsonl (Acceptance Gate — system of record)', e);
       return json(res, { ok: false, error: 'could not record the acceptance — the file-mode system of record is unwritable; the decision was NOT saved', sink, fallback }, 500);