@forwardimpact/libwiki 0.2.26 → 0.2.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libwiki",
-  "version": "0.2.26",
+  "version": "0.2.28",
   "description": "Wiki lifecycle primitives — stable memory for agent teams so coordination persists across sessions.",
   "keywords": [
     "wiki",

package/src/audit/rules.js

@@ -3,6 +3,8 @@ import {
   ACTIVE_CLAIMS_HEADING,
   ACTIVE_CLAIMS_SEPARATOR_RE,
   ACTIVE_CLAIMS_TABLE_HEADER,
+  AGENT_EXPERIMENTS_CLOSE_RE,
+  AGENT_EXPERIMENTS_OPEN_RE,
   DECISION_HEADING,
   ISSUE_CLOSE_RE,
   ISSUE_OPEN_RE,
@@ -544,6 +546,20 @@ export const RULES = [
       `${r.reason} issue-list marker${r.label ? ` (${r.label})` : ""}`,
     hint: "every '<!-- obstacles:* -->' or '<!-- experiments:* -->' needs a matching close marker",
   },
+  {
+    id: "storyboard.markers-balanced.agent-experiments",
+    scope: "storyboard",
+    severity: "fail",
+    when: storyboardExists,
+    check: markersBalanced({
+      openRe: AGENT_EXPERIMENTS_OPEN_RE,
+      closeRe: AGENT_EXPERIMENTS_CLOSE_RE,
+      label: "agent-experiments",
+    }),
+    message: (_s, r) =>
+      `${r.reason} agent-experiments marker${r.label ? ` (${r.label})` : ""}`,
+    hint: "every '<!-- agent-experiments -->' needs a matching '<!-- /agent-experiments -->'",
+  },
 
   // -- Metrics CSVs (union merge keeps both sides on concurrent appends;
   // exact-duplicate rows are surfaced here, never silently removed) --

package/src/audit/scopes.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import { yearMonth } from "@forwardimpact/libutil";
 import { parseClaims } from "../active-claims.js";
 import { countLines, countWords } from "../budget.js";
+import { parseStatusRowId } from "../status.js";
 import {
   PRIORITY_INDEX_HEADING,
   WEEKLY_LOG_NAME_RE,
@@ -120,9 +121,12 @@ function readOptional(filePath, fs) {
 
 /**
  * Parse the rows inside STATUS.md's fenced block into audit subjects. Lines
- * outside the ``` fence (header prose) and blank lines are skipped.
+ * outside the ``` fence (header prose) and blank lines are skipped. Each row
+ * carries a `kind` from {@link parseStatusRowId} (`"spec"`, `"experiment"`, or
+ * `null` for an unrecognized id); spec-shaped rules read the positional
+ * `id`/`phase`/`status` fields, experiment rules read `cells`.
  * @param {string} statusText - The full STATUS.md contents.
- * @returns {Array<{lineNo: number, text: string, cells: string[], id: string, phase: string, status: string}>}
+ * @returns {Array<{lineNo: number, text: string, cells: string[], id: string, phase: string, status: string, kind: string|null}>}
  */
 function parseStatusRows(statusText) {
   const lines = statusText.split("\n");
@@ -136,6 +140,12 @@ function parseStatusRows(statusText) {
     }
     if (!inFence || line.trim() === "") continue;
     const cells = line.split("\t");
+    // Classify by id prefix so a malformed `exp:` row (e.g. wrong cell count)
+    // is still routed to the experiment rules, which flag it — rather than
+    // slipping through the spec-shaped rules. parseStatusRowId returns the
+    // structured fields only for a well-formed row; the rules read `cells`.
+    const isExp = typeof cells[0] === "string" && cells[0].startsWith("exp:");
+    const parsed = parseStatusRowId(cells[0], cells);
     rows.push({
       lineNo: i + 1,
       text: line,
@@ -143,6 +153,7 @@ function parseStatusRows(statusText) {
       id: cells[0],
       phase: cells[1],
       status: cells[2],
+      kind: isExp ? "experiment" : parsed ? parsed.kind : null,
     });
   }
   return rows;

package/src/audit/status-row.js

@@ -1,24 +1,37 @@
 import { STATUS_ID_REGEX } from "../status.js";
 
-// Validate every row inside wiki/STATUS.md's code fence against the
-// `{id}<TAB>{phase}<TAB>{status}` shape. Rows are resolved by the `status-row`
-// scope in scopes.js; each subject carries `{ cells, id, phase, status, text }`.
+// Validate every row inside wiki/STATUS.md's code fence. Rows are resolved by
+// the `status-row` scope in scopes.js; each subject carries
+// `{ cells, id, phase, status, kind, text }`. Two row kinds share the fence:
+//
+//   spec        `{id}<TAB>{phase}<TAB>{status}` — three cells
+//   experiment  `exp:{issue}<TAB>{state}<TAB>{pin}<TAB>{plan-ref}` — four cells
+//
+// Spec-shaped rules run for every non-experiment row (`kind !== "experiment"`,
+// which includes an unrecognized id so a malformed id still flags). Experiment
+// rules run only for `kind === "experiment"`.
 
 const PHASES = new Set(["spec", "design", "plan"]);
 const STATUSES = new Set(["draft", "approved", "implemented", "cancelled"]);
+const EXP_STATES = new Set(["registered", "approved", "cancelled"]);
+const PIN_RE = /^[0-9a-f]{40}$/;
 
-const hasThreeCells = (s) => s.cells.length === 3;
+const isSpecShaped = (s) => s.kind !== "experiment";
+const isExperiment = (s) => s.kind === "experiment";
+const hasThreeCells = (s) => isSpecShaped(s) && s.cells.length === 3;
+const hasFourCells = (s) => isExperiment(s) && s.cells.length === 4;
 
 export const STATUS_ROW_RULES = [
   {
     id: "status-row.shape",
     scope: "status-row",
     severity: "fail",
+    when: isSpecShaped,
     check: (s) =>
-      hasThreeCells(s) ? null : { actual: s.cells.length, text: s.text },
+      s.cells.length === 3 ? null : { actual: s.cells.length, text: s.text },
     message: (_s, r) =>
       `${r.actual} tab-separated field(s), expected 3: "${r.text}"`,
-    hint: "each STATUS row is `{id}<TAB>{phase}<TAB>{status}`",
+    hint: "each spec STATUS row is `{id}<TAB>{phase}<TAB>{status}`",
   },
   {
     id: "status-row.id-format",
@@ -48,4 +61,76 @@ export const STATUS_ROW_RULES = [
       `Bad status '${r.status}' (expected draft|approved|implemented|cancelled)`,
     hint: "status is one of draft, approved, implemented, cancelled",
   },
+  {
+    id: "status-row.exp-shape",
+    scope: "status-row",
+    severity: "fail",
+    when: isExperiment,
+    check: (s) =>
+      s.cells.length === 4 ? null : { actual: s.cells.length, text: s.text },
+    message: (_s, r) =>
+      `${r.actual} tab-separated field(s), expected 4: "${r.text}"`,
+    hint: "each experiment row is `exp:{issue}<TAB>{state}<TAB>{pin}<TAB>{plan-ref}`",
+  },
+  {
+    // An experiment-kind row is classified by its `exp:` id prefix
+    // (scopes.js), so the spec `id-format` rule is skipped for it; this rule
+    // enforces the `exp:\d+` id so a non-numeric issue (e.g. `exp:abc`) flags
+    // rather than auditing clean — keeping the audit aligned with
+    // STATUS_ID_REGEX / parseStatusRowId.
+    id: "status-row.exp-id-format",
+    scope: "status-row",
+    severity: "fail",
+    when: isExperiment,
+    check: (s) => (/^exp:\d+$/.test(s.id) ? null : { id: s.id }),
+    message: (_s, r) => `Bad experiment id '${r.id}' (expected exp:NNN)`,
+    hint: "an experiment id is `exp:` followed by the issue number",
+  },
+  {
+    id: "status-row.exp-state",
+    scope: "status-row",
+    severity: "fail",
+    when: hasFourCells,
+    check: (s) => (EXP_STATES.has(s.cells[1]) ? null : { state: s.cells[1] }),
+    message: (_s, r) =>
+      `Bad experiment state '${r.state}' (expected registered|approved|cancelled)`,
+    hint: "experiment state is one of registered, approved, cancelled",
+  },
+  {
+    id: "status-row.exp-pin",
+    scope: "status-row",
+    severity: "fail",
+    when: hasFourCells,
+    // The pin is decidable per state, with no "ever approved" inference: a
+    // `registered` row has no pin (`-`); an `approved` row pins the 40-hex
+    // head; a `cancelled` row may carry the retained pin or `-` (it may or may
+    // not have been approved before cancellation), so both are accepted.
+    check: (s) => {
+      const [, state, pin] = s.cells;
+      if (state === "registered") {
+        return pin === "-" ? null : { state, pin, want: "-" };
+      }
+      if (state === "approved") {
+        return PIN_RE.test(pin) ? null : { state, pin, want: "a 40-hex SHA" };
+      }
+      if (state === "cancelled") {
+        return pin === "-" || PIN_RE.test(pin)
+          ? null
+          : { state, pin, want: "`-` or a 40-hex SHA" };
+      }
+      return null; // bad state already flagged by exp-state
+    },
+    message: (_s, r) =>
+      `Bad pin '${r.pin}' for state '${r.state}' (expected ${r.want})`,
+    hint: "registered pins `-`; approved pins a 40-hex SHA; cancelled pins either",
+  },
+  {
+    id: "status-row.exp-planref",
+    scope: "status-row",
+    severity: "fail",
+    when: hasFourCells,
+    check: (s) => (/^#\d+$/.test(s.cells[3]) ? null : { planRef: s.cells[3] }),
+    message: (_s, r) => `Bad plan-ref '${r.planRef}' (expected #NNN)`,
+    hint: "the plan-ref names the issue carrying the execution plan, e.g. #NNN",
+  },
 ];

package/src/boot.js

@@ -3,6 +3,9 @@ import { yearMonth } from "@forwardimpact/libutil";
 import { parseClaims, filterExpired } from "./active-claims.js";
 import { countLines, countWords } from "./budget.js";
 import {
+  AGENT_EXPERIMENTS_CLOSE_RE,
+  AGENT_EXPERIMENTS_OPEN_RE,
+  AGENT_EXPERIMENT_ITEM_RE,
   MEMO_INBOX_MARKER,
   PRIORITY_INDEX_HEADING,
   SUMMARY_LINE_BUDGET,
@@ -12,6 +15,8 @@ import {
 } from "./constants.js";
 import { weeklyLogPath } from "./weekly-log.js";
 
+const STANDING_CARRIES_HEADING = "## Standing Carries";
+
 function readIfExists(fs, filePath) {
   if (!fs.existsSync(filePath)) return null;
   return fs.readFileSync(filePath, "utf-8");
@@ -96,35 +101,89 @@ function splitPriorities(rows, agent) {
   return { owned, cross };
 }
 
+// Parse an attributed item line from the materialized block for `agent`.
+// Returns the unified item shape or null (wrong agent / not an item line).
+function parseBlockItem(line, agent) {
+  const m = line.match(AGENT_EXPERIMENT_ITEM_RE);
+  if (!m || m[2] !== agent) return null;
+  return {
+    dim: agent,
+    threshold: m[3],
+    status: "open",
+    link: null,
+    issue: Number(m[1]),
+    author: m[4],
+    source: "experiment",
+  };
+}
+
+function bulletItem(threshold, agent) {
+  return {
+    dim: agent,
+    threshold,
+    status: "open",
+    link: null,
+    issue: null,
+    author: null,
+    source: "bullet",
+  };
+}
+
+// Advance the agent-section scan for one storyboard line that is NOT inside the
+// materialized block. Returns the next `inAgent` state and pushes an h3-bullet
+// item for the booting agent when one is found. An h2 ends the agent-section
+// scan (team-wide sections follow the last agent h3 — without this the scan
+// would run past the agent sections and misattribute team-wide bullets).
+function scanAgentLine(line, agent, inAgent, items) {
+  if (/^## /.test(line)) return false;
+  const h3Match = line.match(/^### (.+)$/);
+  if (h3Match) {
+    return h3Match[1].toLowerCase().startsWith(agent.toLowerCase());
+  }
+  const bullet = inAgent && line.match(/^[-*]\s+(.+)$/);
+  if (bullet) items.push(bulletItem(bullet[1], agent));
+  return inAgent;
+}
+
 function parseStoryboardItems(text, agent) {
   if (!text) return [];
-  const lines = text.split("\n");
   const items = [];
   let inAgent = false;
-  for (const line of lines) {
-    const h3Match = line.match(/^### (.+)$/);
-    if (h3Match) {
-      inAgent = h3Match[1].toLowerCase().startsWith(agent.toLowerCase());
-      continue;
-    }
-    if (/^#{1,2} /.test(line)) {
+  let inBlock = false;
+  for (const line of text.split("\n")) {
+    // The materialized block carries `- #N [agent] …` bullets that the agent
+    // scan must never capture; track it so the bullet loop skips inside it.
+    // (Without it the legacy scan double-counted these as the last agent's bullets.)
+    if (AGENT_EXPERIMENTS_OPEN_RE.test(line)) {
+      inBlock = true;
       inAgent = false;
-      continue;
-    }
-    if (!inAgent) continue;
-    const bullet = line.match(/^[-*]\s+(.+)$/);
-    if (bullet) {
-      items.push({
-        dim: agent,
-        threshold: bullet[1],
-        status: "open",
-        link: null,
-      });
+    } else if (AGENT_EXPERIMENTS_CLOSE_RE.test(line)) {
+      inBlock = false;
+    } else if (inBlock) {
+      const item = parseBlockItem(line, agent);
+      if (item) items.push(item);
+    } else {
+      inAgent = scanAgentLine(line, agent, inAgent, items);
     }
   }
   return items;
 }
 
+function extractStandingCarries(text) {
+  if (!text) return [];
+  const lines = text.split("\n");
+  const start = lines.findIndex((l) => l.trim() === STANDING_CARRIES_HEADING);
+  if (start === -1) return [];
+  const carries = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^## /.test(line)) break;
+    const bullet = line.match(/^[-*] (.*)$/);
+    if (bullet) carries.push(bullet[1]);
+  }
+  return carries;
+}
+
 function countInbox(text) {
   if (!text) return 0;
   const lines = text.split("\n");
@@ -203,6 +262,7 @@ export function buildDigest({ wikiRoot, agent, today, fs }) {
     cross_cutting: cross.map(mapPriority),
     claims: active.map(mapClaim),
     storyboard_items: parseStoryboardItems(storyboardText ?? "", agent),
+    standing_carries: extractStandingCarries(summaryText),
     inbox_count: countInbox(summaryText),
     summary_headroom: headroom(
       summaryText ?? "",

package/src/cli-definition.js

@@ -1,5 +1,6 @@
 import { runMemoCommand } from "./commands/memo.js";
 import { runRefreshCommand } from "./commands/refresh.js";
+import { runProductMixCommand } from "./commands/product-mix.js";
 import { runInitCommand } from "./commands/init.js";
 import { runPushCommand, runPullCommand } from "./commands/sync.js";
 import { runBootCommand } from "./commands/boot.js";
@@ -218,6 +219,31 @@ export function createDefinition() {
           },
         },
       },
+      {
+        name: "product-mix",
+        description:
+          "Emit the product-vs-internal mix of merged PRs as a `product_share` metric row",
+        handler: runProductMixCommand,
+        options: {
+          until: {
+            type: "string",
+            description: "Window end ISO date (default: today)",
+          },
+          since: {
+            type: "string",
+            description: "Window start ISO date (default: until − 7 days)",
+          },
+          run: {
+            type: "string",
+            description: "Run id recorded on the metric row (default: gh-live)",
+          },
+          repo: {
+            type: "string",
+            description: "owner/repo slug (default: origin remote)",
+          },
+          ...wikiRootOpt,
+        },
+      },
       {
         name: "init",
         description: "Bootstrap a wiki working tree and scaffold Active Claims",
@@ -262,6 +288,7 @@ export function createDefinition() {
       "fit-wiki fix",
       'fit-wiki memo --from staff-engineer --to security-engineer --message "audit d642ff0c"',
       "fit-wiki refresh",
+      "fit-wiki product-mix",
       "fit-wiki init",
       "fit-wiki push",
       "fit-wiki pull",

package/src/commands/claim.js

@@ -11,7 +11,11 @@ import { currentDayIso } from "../util/clock.js";
 import { requireAgentFlag } from "../util/agent-flag.js";
 import { resolveWikiRoot } from "../util/wiki-dir.js";
 import { refusalEnvelope } from "../secret-gate.js";
-import { AncestryRefusal } from "../wiki-sync.js";
+import {
+  AncestryRefusal,
+  PUSH_REASONS,
+  WikiPushFailure,
+} from "../wiki-sync.js";
 
 /** Non-zero envelope returned when the ancestry guard refused publication. */
 const NOT_PUBLISHED = {
@@ -19,6 +23,16 @@ const NOT_PUBLISHED = {
   code: 1,
 };
 
+// Failure reasons that, on the claim/release surfaces, are an unsafe-state
+// refusal (D7/D9 family) rather than a saved-locally success (D1): the refusal
+// fires before the local write is publishable, or leaves the tree unsafe for a
+// later whole-tree sweep, so the surface must exit non-zero.
+const UNSAFE_STATE_REASONS = new Set([
+  PUSH_REASONS.PRECONDITION,
+  PUSH_REASONS.RESIDUE_CONFLICT,
+  PUSH_REASONS.CONSERVATION,
+]);
+
 /** Build the not-published refusal message for the given guard refusal. */
 function notPublishedMessage(err) {
   return (
@@ -38,17 +52,23 @@ function memoryPath(runtime, options) {
 }
 
 /**
- * Push the claim/release MEMORY.md change through the secret-gated push path
- * and translate the result into a command envelope. A secret block fails the
- * command closed (`{ ok: false, code: 1 }`) and names the finding or the
- * scanner absence on stderr — distinct from a *network* push failure, which
- * still degrades to "saved locally" and succeeds (`{ ok: true }`).
+ * Push the claim/release MEMORY.md change and translate the honest outcome
+ * (the honest-CLI contract) into a command envelope, composed with the singleton merge
+ * discipline (the singleton merge discipline) and the secret/ancestry guards:
+ * - landed (grounded or re-applied) ⇒ `{ ok: true }`, success message printed;
+ * - `rejected`/`transport` ⇒ `{ ok: true }` with a saved-locally warning (the
+ *   landed-locally row is complete; the session-end push is its retry);
+ * - `precondition`/`residue-conflict`/`conservation` ⇒ `{ ok: false, code: 1 }`
+ *   (D7/D9 unsafe-state family — the row is not published and the tree may be
+ *   left unsafe for a later whole-tree sweep);
+ * - a secret-gate refusal ⇒ `{ ok: false, code: 1 }` ({@link refusalEnvelope});
+ * - an {@link AncestryRefusal} is rethrown so `pushRowOrRefuse` maps it to the
+ *   not-published non-zero envelope;
+ * - any other thrown error is a network/credential failure that degrades to
+ *   "saved locally" (`{ ok: true }`).
  *
  * The `reapply` closure re-derives this row against the fresh tip if the
- * landing contends, so a parallel writer's row is never erased. An
- * ancestry-guard refusal ({@link AncestryRefusal}) is rethrown so the caller's
- * `pushRowOrRefuse` can map it to the not-published non-zero envelope; every
- * other throw is a network/credential failure that degrades to "saved locally".
+ * landing contends, so a parallel writer's row is never erased.
  *
  * @param {object} wikiSync - The WikiSync collaborator (may be absent in tests).
  * @param {object} runtime - The runtime bag (for stdout/stderr).
@@ -65,37 +85,54 @@ async function pushWiki(wikiSync, runtime, message, reapply) {
     // claim/release contract is a 1-line MEMORY.md change; the pathspec keeps
     // foreign uncommitted files from parallel writers out of the commit. The
     // `reapply` closure re-derives this row against the fresh tip if the landing
-    // contends, so a parallel writer's row is never erased.
+    // contends (the singleton merge discipline), so a parallel writer's row is never erased.
     result = await wikiSync.commitAndPush(message, ["MEMORY.md"], { reapply });
   } catch (err) {
-    // An ancestry-guard refusal pierces the saved-locally degradation: it must
-    // reach a non-zero exit so the session stops rather than scroll past. Every
-    // other failure is a network/credential failure: preserve fire-and-forget
-    // "saved locally" — the change is on disk and the command still succeeds.
+    // An ancestry-guard refusal pierces the saved-locally degradation: rethrow
+    // so pushRowOrRefuse maps it to the not-published non-zero envelope.
     if (err instanceof AncestryRefusal) throw err;
+    if (err instanceof WikiPushFailure) {
+      // D7/D9 unsafe-state family: the row is not published and the tree may be
+      // left unsafe for a later sweep — fail the command closed (non-zero).
+      if (UNSAFE_STATE_REASONS.has(err.reason)) {
+        runtime.proc.stderr.write(`${err.message}\n`);
+        return { ok: false, code: 1 };
+      }
+      // rejected / transport: the local row landed; warn and keep zero exit.
+      runtime.proc.stderr.write(
+        `saved locally — not yet visible to parallel sessions (${err.reason}): ${err.message}\n`,
+      );
+      return { ok: true };
+    }
+    // Any other failure: preserve fire-and-forget "saved locally" — the change
+    // is on disk and the command still succeeds.
     createLogger("wiki", runtime).warn(
       "claim",
       `push failed (saved locally): ${err.message}`,
     );
     return { ok: true };
   }
+  // A secret-gate refusal fails the command closed; a grounded-landed or a
+  // re-applied push reports success.
   const refusal = refusalEnvelope(runtime, result);
   if (refusal) return refusal;
-  if (result.pushed) runtime.proc.stdout.write("push: committed and pushed\n");
+  if (result.landed || result.pushed) {
+    runtime.proc.stdout.write("push: committed and pushed\n");
+  }
   return { ok: true };
 }
 
 /**
  * Push a written claim/release row, mapping an ancestry-guard refusal to the
- * not-published non-zero envelope and any other outcome to `{ ok: true }`. The
- * row is already written to MEMORY.md; on refusal it stays as an uncommitted
- * working-tree change. The `reapply` closure re-derives the same row against
- * the fresh tip when the landing contends.
+ * not-published non-zero envelope and any other outcome to `pushWiki`'s
+ * envelope. The row is already written to MEMORY.md; on refusal it stays as an
+ * uncommitted working-tree change. The `reapply` closure re-derives the same
+ * row against the fresh tip when the landing contends.
  */
 async function pushRowOrRefuse(wikiSync, runtime, message, reapply) {
   try {
-    // Propagate pushWiki's envelope so a secret-gate refusal ({ ok: false })
-    // fails the command closed; a clean push returns { ok: true }.
+    // Propagate pushWiki's envelope so a secret-gate or unsafe-state refusal
+    // ({ ok: false }) fails the command closed; a clean push returns { ok: true }.
     return await pushWiki(wikiSync, runtime, message, reapply);
   } catch (err) {
     if (err instanceof AncestryRefusal) {

package/src/commands/product-mix.js

@@ -0,0 +1,148 @@
+import { addDays } from "@forwardimpact/libutil";
+import { createLogger } from "@forwardimpact/libtelemetry";
+import { createScriptConfig } from "@forwardimpact/libconfig";
+import { parseRepoSlug } from "../issue-list-renderer.js";
+import { currentDayIso } from "../util/clock.js";
+import { resolveProjectRoot } from "../util/wiki-dir.js";
+
+// Resolve the monorepo's `owner/repo` slug the way `refresh.js` does: an
+// explicit `FIT_GH_REPO` env override (sandbox proxy URLs), else the origin
+// remote parsed via the injected git client. Returns null when nothing
+// parseable is found, in which case `gh` falls back to its own cwd resolution.
+async function deriveRepo(gitClient, cwd, env) {
+  if (env.FIT_GH_REPO) return env.FIT_GH_REPO;
+  if (!gitClient) return null;
+  try {
+    const url = await gitClient.remoteGetUrl("origin", { cwd });
+    return parseRepoSlug(url);
+  } catch {
+    return null;
+  }
+}
+
+// A missing token is non-fatal: `gh` may still resolve ambient auth, and a
+// hard fetch failure downstream collapses to a logged warning and no row.
+async function resolveToken() {
+  try {
+    return (await createScriptConfig("wiki")).ghToken();
+  } catch {
+    return null;
+  }
+}
+
+// `gh pr list` returns at most this many PRs; a window that hits the cap is
+// truncated, so the caller warns rather than silently undercounting.
+const FETCH_LIMIT = 200;
+
+// Fetch merged PRs in `[since, until]` and return their parsed JSON, or null on
+// any failure (non-zero exit or unparseable stdout) so the caller emits no row.
+async function fetchMergedPrs({ runtime, cwd, repo, since, until, token }) {
+  const args = ["pr", "list", "--base", "main"];
+  if (repo) args.push("--repo", repo);
+  args.push(
+    "--json",
+    "number,labels,mergedAt",
+    "--search",
+    `merged:${since}..${until}`,
+    "--limit",
+    String(FETCH_LIMIT),
+  );
+  const env = token
+    ? { ...runtime.proc.env, GH_TOKEN: token }
+    : runtime.proc.env;
+  const result = await runtime.subprocess.run("gh", args, { cwd, env });
+  if (result.exitCode !== 0) return null;
+  try {
+    return JSON.parse(result.stdout || "[]");
+  } catch {
+    return null;
+  }
+}
+
+// Tally merged PRs by their classification label. A PR with neither label is
+// unlabeled; `product` wins if both are somehow present.
+function countByLabel(prs) {
+  const counts = { product: 0, internal: 0, unlabeled: 0 };
+  for (const pr of prs) {
+    const names = (pr.labels || []).map((l) => l.name);
+    if (names.includes("product")) counts.product++;
+    else if (names.includes("internal")) counts.internal++;
+    else counts.unlabeled++;
+  }
+  return counts;
+}
+
+/**
+ * Emit the product-vs-internal mix of merged PRs as a `product_share` metric
+ * row. Counts PRs merged in `[since, until]` by their `product` / `internal`
+ * label and appends `product_share = round(product / (product + internal) *
+ * 100)` to `wiki/metrics/product-mix/<YYYY>.csv` via the `fit-xmr record` write
+ * path. Deterministic — re-running over the same merged PRs yields the same
+ * value. A window with no labeled merged PRs emits no row (avoids a 0/0 ratio).
+ */
+export async function runProductMixCommand(ctx) {
+  const { runtime, gitClient } = ctx.deps;
+  const options = ctx.options;
+  const logger = createLogger("wiki", runtime);
+  const cwd = resolveProjectRoot(runtime);
+
+  const until = options.until || currentDayIso(runtime);
+  const since = options.since || addDays(until, -7);
+  const run = options.run || "gh-live";
+  const repo =
+    options.repo || (await deriveRepo(gitClient, cwd, runtime.proc.env));
+  const token = await resolveToken();
+
+  const prs = await fetchMergedPrs({ runtime, cwd, repo, since, until, token });
+  if (prs === null) {
+    logger.warn("product-mix", `gh pr list failed for ${since}..${until}`);
+    return { ok: true };
+  }
+  if (prs.length >= FETCH_LIMIT) {
+    logger.warn(
+      "product-mix",
+      `window ${since}..${until} hit the ${FETCH_LIMIT}-PR fetch cap; product_share may undercount`,
+    );
+  }
+
+  const { product, internal, unlabeled } = countByLabel(prs);
+  const total = product + internal;
+  if (total === 0) {
+    logger.info(
+      "product-mix",
+      `no labeled merged PRs in ${since}..${until}; emitting no row`,
+    );
+    return { ok: true };
+  }
+
+  const share = Math.round((product / total) * 100);
+  const recordArgs = [
+    "fit-xmr",
+    "record",
+    "--skill",
+    "product-mix",
+    "--metric",
+    "product_share",
+    "--value",
+    String(share),
+    "--unit",
+    "pct",
+    "--date",
+    until,
+    "--run",
+    run,
+    "--note",
+    `product=${product} internal=${internal} unlabeled=${unlabeled} window=${since}..${until}`,
+    "--event-type",
+    "kata-shift",
+  ];
+  if (options["wiki-root"]) {
+    recordArgs.push("--wiki-root", options["wiki-root"]);
+  }
+
+  const recordResult = await runtime.subprocess.run("npx", recordArgs, { cwd });
+  if (recordResult.exitCode !== 0) {
+    logger.warn("product-mix", "fit-xmr record failed");
+  }
+  return { ok: true };
+}