create-pmos 0.34.0 → 0.36.0

package/payload/scripts/workflow-state.js

@@ -58,18 +58,43 @@ const delivery = require('./delivery-index');
 // The OKR documents and the budget registry are read once per root, not once per initiative: the
 // board derives ~100 ladders in a single pass and re-reading the same three files each time is the
 // same waste the shared commit-range exists to avoid.
-const _okrCache = new Map();
-const _budCache = new Map();
+//
+// KEYED BY WHAT THE FILES ARE, never by where they live alone. The workspace server requires this
+// module in-process and holds it for days, so a root-only key kept serving the ladder yesterday's
+// anchor index after the PM fixed the OKR document — the OKR panel (which reads fresh) and the
+// anchor rung disagreed about one field until a restart, the exact two-readers defect
+// anchor-resolve was extracted to end. The stamp is mtime+size over the documents and their
+// directories (the directory catches a file added or removed); the stats cost microseconds against
+// the parse they guard. delivery-index keys its cache on the trunk head sha for the same reason.
+// One stated limit: an `okrs/` directory born at a location no prior read has seen is picked up on
+// the next change to a watched path or the next process, not instantly.
+const _okrCache = new Map();      // root -> { stamp, files, index }
+const _budCache = new Map();      // root -> { stamp, value }
+function statStamp(p) {
+  try { const s = fs.statSync(p); return `${s.mtimeMs}:${s.size}`; } catch { return 'absent'; }
+}
+function okrStamp(files) {
+  const dirs = [...new Set(files.map((f) => path.dirname(f)))];
+  return files.concat(dirs).map((p) => `${p}=${statStamp(p)}`).join('|');
+}
 function okrIndexFor(root) {
-  if (!_okrCache.has(root)) _okrCache.set(root, anchors.parseOkrIndex(root));
-  return _okrCache.get(root);
+  const hit = _okrCache.get(root);
+  if (hit && hit.files.length && okrStamp(hit.files) === hit.stamp) return hit.index;
+  const files = anchors.listOkrFiles(root);
+  const entry = { stamp: okrStamp(files), files, index: anchors.parseOkrIndex(root) };
+  _okrCache.set(root, entry);
+  return entry.index;
 }
 function budgetsFor(root, L) {
-  if (!_budCache.has(root)) {
-    try { _budCache.set(root, { ok: true, text: fs.readFileSync(L.budgets, 'utf8'), path: path.relative(root, L.budgets) }); }
-    catch { _budCache.set(root, { ok: false, text: '', path: path.relative(root, L.budgets) }); }
+  const stamp = statStamp(L.budgets);
+  const hit = _budCache.get(root);
+  if (!hit || hit.stamp !== stamp) {
+    let value;
+    try { value = { ok: true, text: fs.readFileSync(L.budgets, 'utf8'), path: path.relative(root, L.budgets) }; }
+    catch { value = { ok: false, text: '', path: path.relative(root, L.budgets) }; }
+    _budCache.set(root, { stamp, value });
   }
-  return _budCache.get(root);
+  return _budCache.get(root).value;
 }
 
 /*
@@ -105,18 +130,31 @@ function isBuildPath(p, lane) {
 }
 
 // ── Frontmatter ────────────────────────────────────────────────────────────────────────────────
-// The LEADING block only — body text must never be able to fake a declaration. Mirrors
-// workspace/lib/file-mode-parse.js and kit/scripts/metrics.py, plus the surrounding-quote strip the
-// bash gate does, so all four readers agree on what a record declared.
+// The LEADING block only — body text must never be able to fake a declaration. The closing ---
+// fence is TERMINAL, never skipped: the fence used to be stepped over, so a key-shaped FIRST body
+// line was absorbed into the block and could fake a declaration at the fence boundary (the one
+// shape the gamma prose-then-keys fixture never exercised). Fenceless files keep parsing from line
+// 1 and stop at the first non-key line — the kit's smoke fixtures carry no fences and must keep
+// parsing. Mirrors workspace/lib/file-mode-parse.js, kit/scripts/metrics.py and the two bash gates'
+// readers — first value wins, one pair of surrounding double quotes stripped — so all the readers
+// agree on what a record declared (kit/fixtures/test_parsers.py + workspace/fixture-parity.test.mjs
+// hold the agreement).
 function parseLeadingFrontmatter(text) {
   const fm = {};
+  let fenceOpen = false;
   for (const line of String(text == null ? '' : text).split('\n')) {
+    if (line.startsWith('---')) {
+      // Only the FIRST ---, before any key, opens the block; every later --- ends it.
+      if (fenceOpen || Object.keys(fm).length) break;
+      fenceOpen = true;
+      continue;
+    }
     const m = line.match(/^([a-z_]+):\s*(.*?)\s*$/);
     if (m) {
       if (!(m[1] in fm)) fm[m[1]] = m[2].replace(/^"(.*)"$/s, '$1');
       continue;
     }
-    if (line.trim() && !line.startsWith('---')) break;
+    if (line.trim()) break;
   }
   return fm;
 }
@@ -136,23 +174,32 @@ function readFrontmatter(file) {
  * changed return type, because every existing call site wants the rows and only the sweep wants the
  * damage. Changing the shape would have made ~six callers handle a case none of them can act on.
  */
+// The implementation lives in scripts/read-jsonl.js now — this contract became the shared one after
+// six hand-rolled readers each re-decided the torn-line question (and two got it wrong). The thin
+// wrapper keeps this file's call sites and the out-of-band defects channel unchanged.
+const jsonl = require('./read-jsonl');
 function readJsonl(file, defects) {
-  let text;
-  try { text = fs.readFileSync(file, 'utf8'); } catch { return []; }
-  const out = [];
-  const lines = text.split('\n');
-  for (let i = 0; i < lines.length; i++) {
-    const t = lines[i].trim();
-    if (!t) continue;
-    try { out.push(JSON.parse(t)); }
-    catch (e) {
-      // Dropped, never guessed — and now said out loud to anyone who asked to hear it.
-      if (Array.isArray(defects)) {
-        defects.push({ file, line: i + 1, reason: String((e && e.message) || 'not valid JSON').slice(0, 120), text: t.slice(0, 120) });
-      }
-    }
-  }
-  return out;
+  const r = jsonl.readJsonl(file);
+  // Dropped, never guessed — and said out loud to anyone who asked to hear it.
+  if (Array.isArray(defects)) defects.push(...r.defects);
+  return r.rows;
+}
+
+// The ledgers are read once per VERSION OF THE FILE, not once per initiative — the same per-root
+// rule the OKR cache above states, applied to the other four per-root inputs it was skipping. The
+// board filters ~665 KB of parsed rows once per ladder; re-reading and re-parsing the files each
+// time was ~145 MB of work per board. The stamp is mtime+size for the same reason as the OKR
+// cache's: the workspace server holds this module in-process, and a run or acceptance appended
+// between requests must be visible on the next derivation, not after a restart. Callers filter the
+// shared rows and never mutate them.
+const _ledgerCache = new Map();   // absolute path -> { stamp, rows }
+function cachedJsonl(file) {
+  const stamp = statStamp(file);
+  const hit = _ledgerCache.get(file);
+  if (hit && hit.stamp === stamp) return hit.rows;
+  const rows = readJsonl(file);
+  _ledgerCache.set(file, { stamp, rows });
+  return rows;
 }
 
 // ── Repo layout — pmos-self and the kit disagree on where state lives, so detect rather than assume
@@ -308,6 +355,39 @@ function firstAppearance(root, range, rel) {
   return range.index.has(sha) ? range.index.get(sha) : -1;
 }
 
+/*
+ * When was each path last touched, answered from the range's OWN single pass. A `git log -1
+ * --format=%ct -- <paths>` per initiative was one subprocess per board row — ~85% of the board's
+ * runtime spent re-reading history buildRange had already captured (see the single-pass note
+ * above). Built lazily, memoised on the range object, so every ladder on the board shares one map.
+ */
+function touchIndex(range) {
+  if (!range._touch) {
+    const m = new Map();
+    for (let i = 0; i < range.shas.length; i++) {
+      const t = range.dates[i];
+      if (!Number.isFinite(t)) continue;
+      for (const f of (range.changed[i] || [])) {
+        const prev = m.get(f);
+        if (prev === undefined || t > prev) m.set(f, t);
+      }
+    }
+    range._touch = m;
+  }
+  return range._touch;
+}
+
+// The set of paths git tracks, one `ls-files` shared across the board via the range object. Used
+// only where a range is EMPTY — see the note at the chgIdx computation. `null` = git could not
+// answer, which callers must treat as "fall back", never as "nothing is tracked".
+function trackedIn(root, range) {
+  if (range._tracked === undefined) {
+    const out = git(root, ['ls-files', '-z']);
+    range._tracked = out == null ? null : new Set(out.split('\0').filter(Boolean));
+  }
+  return range._tracked;
+}
+
 /*
  * The earliest position in the range at which this initiative's implementation was touched, plus a
  * count. A docs-only PR has no build commits, which makes every "before the build" rule vacuous —
@@ -510,10 +590,38 @@ function computeWorkflow(id, opts) {
   // that is true of everything, which makes the marker noise — so the board passes the GATE's range
   // separately and the marker is answered from that, or dropped when there is no such range.
   const changeRange = (opts && opts.changeRange) || (range.wholeHistory ? null : range);
-  const chgIdx = changeRange ? firstAppearance(root, changeRange, recRel) : null;
+  // A ZERO-COMMIT range contains nothing, so firstAppearance's per-path fallback — a full-history
+  // `git log --diff-filter=A`, once per initiative on any full clone whose base..HEAD is empty
+  // (HEAD level with main) — can only conclude what one shared `ls-files` already says: a tracked
+  // record predates the range (-1), an on-disk-untracked one is uncommitted (Infinity). The gate's
+  // range — non-empty — keeps the fallback, which is what tells "added before the range" from
+  // "never committed" for O1/O2.
+  const emptyChange = !!changeRange && changeRange.ok && changeRange.shas.length === 0;
+  const tracked = emptyChange ? trackedIn(root, changeRange) : null;
+  const chgIdx = !changeRange ? null
+    : tracked ? (tracked.has(recRel) ? -1 : fs.existsSync(recAbs) ? Infinity : null)
+      : firstAppearance(root, changeRange, recRel);
   const inChange = !!changeRange && chgIdx !== -1 && chgIdx !== null && chgIdx !== undefined;
   const lastActivity = (() => {
     const paths = [recRel, fm.prd_path, fm.rubric_path].filter(Boolean);
+    // The board supplies the trunk range, whose single pass already holds every commit's paths and
+    // dates — so the answer is a map lookup, not a subprocess. The trunk alone would demote
+    // branch-fresh work (`git log -1` reads from HEAD, which sees branch-local commits the trunk
+    // range excludes), so the gate's base..HEAD range is overlaid, max date per path. The
+    // subprocess survives only where no whole-history range was supplied — the single-ladder call.
+    // One deliberate difference from the per-path subprocess: a true merge lists no files in the
+    // single pass, so a merge that merely reconciles histories no longer counts as activity on the
+    // paths it carried — the date it stamped was the sync's, not the work's.
+    if (opts && opts.range && range.ok && range.wholeHistory) {
+      const trunk = touchIndex(range);
+      const branch = changeRange && changeRange.ok ? touchIndex(changeRange) : null;
+      let best = null;
+      for (const p of paths) {
+        const t = Math.max(trunk.get(p) || 0, (branch && branch.get(p)) || 0);
+        if (t > 0 && (best === null || t > best)) best = t;
+      }
+      return best;
+    }
     const out = git(root, ['log', '-1', '--format=%ct', '--', ...paths]);
     const t = out && parseInt(out.trim(), 10);
     return Number.isFinite(t) ? t : null;
@@ -589,8 +697,9 @@ function computeWorkflow(id, opts) {
   const build = buildCommits(root, range, effLane, {
     id,
     // Where this initiative's own record first appears in the range — the earliest commit that could
-    // possibly be its build. See the note in buildCommits' attribution loop.
-    recordIdx: firstAppearance(root, range, recRel),
+    // possibly be its build. Already computed above as `recIdx`, from identical arguments.
+    // See the note in buildCommits' attribution loop.
+    recordIdx: recIdx,
     deliveryIndex: opts && opts.deliveryIndex,
     declaredDelivery: fm.delivered_by,
   });
@@ -748,7 +857,7 @@ function computeWorkflow(id, opts) {
     }
   }
 
-  const runs = readJsonl(path.join(L.runsDir, L.runsFile)).filter((r) => r && r.initiative_id === id);
+  const runs = cachedJsonl(path.join(L.runsDir, L.runsFile)).filter((r) => r && r.initiative_id === id);
   const runsRel = path.relative(root, path.join(L.runsDir, L.runsFile));
 
   // ── priors ─ O7: the episodic read is CITED, and the citation is checked ─────────────────────
@@ -874,7 +983,7 @@ function computeWorkflow(id, opts) {
   steps.push(step('quality', 'quality', 'unknown', 'CI decides on the PR — this engine never claims a test result it did not run'));
 
   // ── review ─ the Review Gate's verdict, where the lane has a rubric ──────────────────────────
-  const evals = readJsonl(path.join(L.runsDir, 'evals.jsonl')).filter((e) => e && e.initiative_id === id);
+  const evals = cachedJsonl(path.join(L.runsDir, 'evals.jsonl')).filter((e) => e && e.initiative_id === id);
   {
     /* The rung reads the RUBRIC, not the lane.
      *
@@ -946,7 +1055,7 @@ function computeWorkflow(id, opts) {
   }
 
   // ── accept ─ the human PM, final and non-delegable (D12) ─────────────────────────────────────
-  const accepted = readJsonl(path.join(L.runsDir, 'acceptances.jsonl'))
+  const accepted = cachedJsonl(path.join(L.runsDir, 'acceptances.jsonl'))
     .filter((a) => a && a.initiative_id === id && a.accepted === true);
   {
     const blockers = steps.filter((s) => s.status === 'blocked').map((s) => s.key);
@@ -974,7 +1083,7 @@ function computeWorkflow(id, opts) {
   {
     const metric = String(fm.outcome_metric || '').trim();
     const horizon = String(fm.outcome_horizon || '').trim();
-    const checks = readJsonl(path.join(L.runsDir, 'outcome_checks.jsonl'))
+    const checks = cachedJsonl(path.join(L.runsDir, 'outcome_checks.jsonl'))
       .filter((c) => c && c.initiative_id === id && ['validated', 'refuted', 'inconclusive'].includes(c.disposition));
     const latest = checks.length ? checks[checks.length - 1] : null;
     const today = new Date().toISOString().slice(0, 10);

package/payload/scripts/workflow-sweep.js

@@ -364,16 +364,16 @@ function sweep(opts) {
       }
     }
 
-    // a declared delivery that does not check out
-    {
-      const dd = delivery.declaredDelivery(root, fm.delivered_by);
-      if (dd.declared && !dd.ok && !dd.unknown) {
-        findings.push(finding('unverifiable-delivery', {
-          id, file: recRel,
-          what: dd.reason,
-          evidence: `delivered_by: ${String(fm.delivered_by).slice(0, 100)}`,
-        }));
-      }
+    // a declared delivery that does not check out — read ONCE, the owed gate below reuses it: a
+    // second declaredDelivery call on the same inputs paid its git subprocesses twice per record
+    // for the same answer.
+    const dd = delivery.declaredDelivery(root, fm.delivered_by);
+    if (dd.declared && !dd.ok && !dd.unknown) {
+      findings.push(finding('unverifiable-delivery', {
+        id, file: recRel,
+        what: dd.reason,
+        evidence: `delivered_by: ${String(fm.delivered_by).slice(0, 100)}`,
+      }));
     }
 
     // ── owed ────────────────────────────────────────────────────────────────────────────────────
@@ -381,7 +381,7 @@ function sweep(opts) {
     // the reason is written on each finding rather than only in this file's header — the person
     // reading the output is the one who needs to know why the tool stopped.
     const signal = del.ok ? delivery.attribution(del, id) : 'unknown';
-    const declaredOk = delivery.declaredDelivery(root, fm.delivered_by).ok === true;
+    const declaredOk = dd.ok === true;
     const delivered = del.ok && (!!signal || declaredOk);
     const runs = runsBy.get(id) || [];
 
@@ -436,19 +436,38 @@ function sweep(opts) {
   };
 }
 
-// Cached the same way the engine caches them — the sweep derives over every record in one pass.
-const _okr = new Map();
+// Cached the same way the engine caches them — the sweep derives over every record in one pass —
+// and keyed the same way too: mtime+size over the documents (plus their directories, so a file
+// added or removed re-lists), never the root alone. The sweep is CLI-today, but a copy of the
+// engine's cache with a weaker key is exactly the two-places-one-rule drift this file exists to
+// sweep for.
+const _okr = new Map();           // root -> { stamp, files, index }
+const _bud = new Map();           // root -> { stamp, value }
+function statStamp(p) {
+  try { const s = fs.statSync(p); return `${s.mtimeMs}:${s.size}`; } catch { return 'absent'; }
+}
+function okrStamp(files) {
+  const dirs = [...new Set(files.map((f) => path.dirname(f)))];
+  return files.concat(dirs).map((p) => `${p}=${statStamp(p)}`).join('|');
+}
 function engineOkrIndex(root) {
-  if (!_okr.has(root)) _okr.set(root, anchors.parseOkrIndex(root));
-  return _okr.get(root);
+  const hit = _okr.get(root);
+  if (hit && hit.files.length && okrStamp(hit.files) === hit.stamp) return hit.index;
+  const files = anchors.listOkrFiles(root);
+  const entry = { stamp: okrStamp(files), files, index: anchors.parseOkrIndex(root) };
+  _okr.set(root, entry);
+  return entry.index;
 }
-const _bud = new Map();
 function budgetsFor(root, L) {
-  if (!_bud.has(root)) {
-    try { _bud.set(root, { ok: true, text: fs.readFileSync(L.budgets, 'utf8'), path: path.relative(root, L.budgets) }); }
-    catch { _bud.set(root, { ok: false, text: '', path: path.relative(root, L.budgets) }); }
+  const stamp = statStamp(L.budgets);
+  const hit = _bud.get(root);
+  if (!hit || hit.stamp !== stamp) {
+    let value;
+    try { value = { ok: true, text: fs.readFileSync(L.budgets, 'utf8'), path: path.relative(root, L.budgets) }; }
+    catch { value = { ok: false, text: '', path: path.relative(root, L.budgets) }; }
+    _bud.set(root, { stamp, value });
   }
-  return _bud.get(root);
+  return _bud.get(root).value;
 }
 
 /*
@@ -740,8 +759,6 @@ function main(argv) {
 
   if (json) {
     process.stdout.write(JSON.stringify({ ...res, repairs }, null, 2) + '\n');
-  } else if (!fix || owedOnly || defectsOnly) {
-    process.stdout.write(render(res, { owedOnly, defectsOnly, all }));
   } else {
     process.stdout.write(render(res, { owedOnly, defectsOnly, all }));
   }

package/payload/skills/SKILL-FORMAT.md

@@ -64,7 +64,7 @@ A skill exists to **wring determinism out of a stochastic system**: it makes the
 
 ### 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](/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
 

package/payload/skills/copywriting.skill

@@ -16,7 +16,7 @@ The first `/skills/domains/` skill: how copy work runs through PMOS's **content
 — never the `no-initiative` hatch — but it iterates fast, so the lane contracts on a **brief**,
 and a rubric is *recommended, not required* (a required one recreates fake-rubric pressure).
 
-> **Format:** three-level progressive disclosure ([SKILL-FORMAT](/skills/core/SKILL-FORMAT.md)).
+> **Format:** three-level progressive disclosure ([SKILL-FORMAT](/skills/SKILL-FORMAT.md)).
 
 ## When to use vs. not
 

package/payload/skills/correction-signal-derive.skill

@@ -13,7 +13,7 @@ self-report (`agent_runs.human_corrections`) — pre-commit conversational steer
 git-invisible and stays the self-report's lane; the **delta** between the two is the point
 (KR-B consumes it).
 
-> **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/design-brief.skill

@@ -12,10 +12,10 @@ scope: read:okf, write:planning/design
 
 This skill produces a design brief instance for one initiative. It is **leg 1** of the
 [design loop](/okf/core/concepts/design-loop.md): the context handoff from Claude Code to
-claude.ai/design. The brief is to design what the [PRD](/skills/core/prd.skill) is to build — the shared
+claude.ai/design. The brief is to design what the [PRD](/skills/prd.skill) is to build — the shared
 definition of *what to design* and the hard constraints, agreed before any design or build starts.
 
-> **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; rare variants go to Level 3 sub-files by name.
 
 ## When to use vs. not
@@ -34,11 +34,11 @@ definition of *what to design* and the hard constraints, agreed before any desig
     [design-reference grilling rubric](/planning/evals/design-reference-eval-rubric.md). Anything beyond
     what the PRD decided is still flagged back.
 - **Do not use** for the reconciliation gate — classifying a returned design against real capability is the
-  [design-reconcile skill](/skills/core/design-reconcile.skill) (leg 3).
+  [design-reconcile skill](/skills/design-reconcile.skill) (leg 3).
 
 ## Procedure
 
-0. **Grill before you brief** (the [prd skill](/skills/core/prd.skill)'s step-0 discipline, applied
+0. **Grill before you brief** (the [prd skill](/skills/prd.skill)'s step-0 discipline, applied
    to design intent): where the PM's aesthetic or structural intent is ambiguous, ask **one question
    at a time with a recommended answer**, stop at unambiguous — no cap; a batch questionnaire is not
    compliant. Look up what the environment answers (the capability ledger, the design system, the

package/payload/skills/design-reconcile.skill

@@ -17,7 +17,7 @@ realizes the reconciliation rule captured in the product's capability ledger (PM
 [watermelon-flag](/okf/core/concepts/watermelon-flag.md) defense applied to UI — it catches a design that
 *looks* functional but has no backend, before it becomes hollow, green-on-the-surface code.
 
-> **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.
 
 ## Non-negotiable stance

package/payload/skills/discovery.skill

@@ -17,7 +17,7 @@ and a timebox**, not requirements, and closes with a mandatory **disposition** i
 verdict. It resolves the stress-test finding that pre-certainty work either got blocked, got a
 fake rubric, or escaped the record entirely.
 
-> **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 above is the trigger; this body is Level 2.
 
 ## When to use vs. not
@@ -25,7 +25,7 @@ fake rubric, or escaped the record entirely.
 - **Use** when the deliverable is an answer: "is X feasible?", "which approach?", "what should the
   PRD even say?" — and you could not write honest done-criteria today.
 - **Do not use** when you *can* write done-criteria — that is a `feature` initiative
-  ([prd skill](/skills/core/prd.skill)). A spike that is secretly a small feature corrupts the lane.
+  ([prd skill](/skills/prd.skill)). A spike that is secretly a small feature corrupts the lane.
 - **Do not use** for urgent production fixes — that is the `incident` lane.
 - A spike is still **anchored work** (D21): no anchor — a parent KR, or a declared health budget
   `health:<id>` (D59) — no spike.
@@ -38,7 +38,7 @@ fake rubric, or escaped the record entirely.
    - Tool form: `create_initiative({id, title, parent_kr, type: 'discovery'})`. The argument keeps
      its name. Read it as "record the equivalent in file-mode state" (AGENTS.md).
 1b. **Existing surface? Understand it first.** If answering the question honestly requires reading
-   code that already exists, run an [explain-surface](/build-skills/explain-surface.skill) pass on
+   code that already exists, run an [explain-surface](/skills/explain-surface.skill) pass on
    that region — in a fresh context, **before** writing the brief. A spike aimed at a system the PM
    does not understand produces a learning they cannot act on. Greenfield → skip.
 2. **Write the spike brief** from

package/payload/skills/eval-rubric.skill

@@ -12,11 +12,11 @@ scope: read:okf, write:planning/evals
 
 This skill produces an eval rubric instance for one initiative. In eval-driven PM the rubric **is the
 spec made measurable** ([eval-driven-pm](/okf/core/concepts/eval-driven-pm.md)): it is authored
-*before* the build, alongside the [PRD](/skills/core/prd.skill), and it defines how output will pass
+*before* the build, alongside the [PRD](/skills/prd.skill), and it defines how output will pass
 through the [three-tier gate](/okf/core/concepts/output-eval.md).
 
 > **Format note:** three-level progressive disclosure
-> ([SKILL-FORMAT](/skills/core/SKILL-FORMAT.md)). Level 1 frontmatter above is the trigger and
+> ([SKILL-FORMAT](/skills/SKILL-FORMAT.md)). Level 1 frontmatter above is the trigger and
 > carries only `name` + `description`. Note: the *rubric instances* this skill produces carry their
 > own frontmatter (including `eval_type`, below) — that is the rubric's frontmatter, not this skill
 > file's.
@@ -79,7 +79,7 @@ Before any work begins, the generator and evaluator **agree on done-criteria**
 contract stage of the [SDLC loop](/okf/core/concepts/sdlc-loop.md). A rubric is incomplete without
 one.
 
-**Reach the criteria by grilling, not assumption** (the [prd skill](/skills/core/prd.skill)'s step-0
+**Reach the criteria by grilling, not assumption** (the [prd skill](/skills/prd.skill)'s step-0
 discipline applies here too): where the PM's intent is ambiguous, ask **one question at a time with a
 recommended answer**, stop at unambiguous — no cap, and a batch questionnaire is not compliant. If a
 fact can be found by exploring the environment, look it up rather than asking — the decisions are the
@@ -129,7 +129,7 @@ construction; no per-contract justification needed beyond naming the doc set.
 
 **Dimensions must be evidence-citable.** The Review Gate scores each dimension with a verbatim
 quote or precise pointer from the artifact as evidence (an unevidenced dimension is `unverified`,
-scored ≤ 0.5 — see [evaluator.skill](/build-skills/evaluator.skill)). Write every dimension as an
+scored ≤ 0.5 — see [evaluator.skill](/skills/evaluator.skill)). Write every dimension as an
 **observable outcome a quote can prove** — "the dry-run verdict names its exemplars" — never an
 impression ("the verdict feels thorough"). If you cannot imagine the evidence quote for a
 dimension, rewrite the dimension

package/payload/skills/evaluator.skill

@@ -12,7 +12,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/explain-run.skill

@@ -21,7 +21,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/explain-surface.skill

@@ -17,13 +17,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.**
@@ -74,8 +74,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 |
@@ -94,7 +94,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/harness-refine.skill

@@ -88,7 +88,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/ingest-repo.skill

@@ -17,7 +17,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
@@ -33,7 +33,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)).**
@@ -65,7 +65,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 |
@@ -78,7 +78,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.
@@ -111,8 +111,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/okr.skill

@@ -15,14 +15,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