@forwardimpact/libwiki 0.2.27 → 0.2.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libwiki",
-  "version": "0.2.27",
+  "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/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 };
+}

package/src/commands/refresh.js

@@ -4,7 +4,12 @@ import { createLogger } from "@forwardimpact/libtelemetry";
 import { createScriptConfig } from "@forwardimpact/libconfig";
 import { scanMarkers } from "../marker-scanner.js";
 import { renderBlock, BlockRenderError } from "../block-renderer.js";
-import { renderIssueList, parseRepoSlug } from "../issue-list-renderer.js";
+import {
+  renderIssueList,
+  renderAgentExperiments,
+  TrackerQueryError,
+  parseRepoSlug,
+} from "../issue-list-renderer.js";
 import { currentDayIso } from "../util/clock.js";
 import { resolveProjectRoot } from "../util/wiki-dir.js";
 
@@ -22,7 +27,33 @@ async function deriveParentRepo(gitClient, parentDir, env) {
   }
 }
 
-async function renderForBlock(block, projectRoot, ghContext, runtime) {
+// Compose the agent-experiments block body. On a successful tracker query the
+// body is a fresh last-successful-sync stamp followed by freshly rendered,
+// label-re-checked, sanitized item lines. On a tracker failure the previously
+// materialized body (stamp + items) is preserved verbatim so boot keeps serving
+// the last good routing surface instead of an empty one, and the timestamp is
+// not advanced, so staleness stays auditable from the stamp.
+async function renderAgentExperimentsBlock(block, lines, ghContext, runtime) {
+  const priorBody = lines.slice(block.openLine + 1, block.closeLine);
+  try {
+    const items = await renderAgentExperiments({
+      cwd: ghContext.cwd,
+      repo: ghContext.repo,
+      token: ghContext.token,
+      runtime,
+    });
+    const today = currentDayIso(runtime);
+    return [`<!-- last-successful-sync: ${today} -->`, ...items];
+  } catch (err) {
+    if (!(err instanceof TrackerQueryError)) throw err;
+    runtime.proc.stderr.write(
+      "refresh: gh issue list failed for agent-experiments; keeping previous materialized items\n",
+    );
+    return priorBody;
+  }
+}
+
+async function renderForBlock(block, lines, projectRoot, ghContext, runtime) {
   if (block.kind === "xmr") {
     return renderBlock({
       metric: block.metric,
@@ -44,6 +75,9 @@ async function renderForBlock(block, projectRoot, ghContext, runtime) {
       runtime,
     });
   }
+  if (block.kind === "agent-experiments") {
+    return renderAgentExperimentsBlock(block, lines, ghContext, runtime);
+  }
   return null;
 }
 
@@ -116,6 +150,7 @@ export async function runRefreshCommand(ctx) {
     try {
       const rendered = await renderForBlock(
         block,
+        lines,
         projectRoot,
         ghContext,
         runtime,

package/src/commands/sync.js

@@ -1,6 +1,10 @@
 import { createLogger } from "@forwardimpact/libtelemetry";
 import { refusalEnvelope } from "../secret-gate.js";
-import { AncestryRefusal, WikiPullConflict } from "../wiki-sync.js";
+import {
+  AncestryRefusal,
+  WikiPullConflict,
+  WikiPushFailure,
+} from "../wiki-sync.js";
 import { sweepTier2, renderDetections } from "../integrity.js";
 import { resolveWikiRoot } from "../util/wiki-dir.js";
 
@@ -19,7 +23,10 @@ export async function runPushCommand(ctx) {
   try {
     result = await wikiSync.commitAndPush("wiki: update from session");
   } catch (err) {
-    if (err instanceof AncestryRefusal) {
+    // Honest CLI contract (the honest-CLI contract): non-zero on any non-land push
+    // failure, and on the ancestry guard's refusal (the ancestry guard). The Stop-hook
+    // recipe maps this to a stop-blocking exit; CI steps see a loud failure.
+    if (err instanceof WikiPushFailure || err instanceof AncestryRefusal) {
       runtime.proc.stderr.write(`${err.message}\n`);
       return { ok: false, code: 1 };
     }
@@ -29,7 +36,7 @@ export async function runPushCommand(ctx) {
   // unavailable); a clean push falls through to the normal reporting below.
   const refusal = refusalEnvelope(runtime, result);
   if (refusal) return refusal;
-  if (result.pushed) {
+  if (result.landed) {
     runtime.proc.stdout.write("push: committed and pushed\n");
   } else {
     runtime.proc.stdout.write("push: nothing to push\n");

package/src/constants.js

@@ -94,3 +94,21 @@ export const ISSUE_OPEN_RE =
   /^<!--\s*(obstacles|experiments):(open|closed)(?::(\d+d))?(?:\s+[^>]*?)?\s*-->\s*$/;
 export const ISSUE_CLOSE_RE =
   /^<!--\s*\/(obstacles|experiments)(?:\s+[^>]*?)?\s*-->\s*$/;
+
+// Materialized per-agent experiments surface. A distinct marker
+// kind from `experiments:open` — it carries attributed, sanitized items plus a
+// last-successful-sync stamp, and is read offline by `fit-wiki boot`. One home
+// so the scanner (marker-scanner.js), the refresh renderer (commands/refresh.js),
+// the boot parser (boot.js), and the audit balance check (audit/rules.js) cannot
+// drift on the syntax.
+export const AGENT_EXPERIMENTS_OPEN_RE =
+  /^<!--\s*agent-experiments(?:\s+[^>]*?)?\s*-->\s*$/;
+export const AGENT_EXPERIMENTS_CLOSE_RE =
+  /^<!--\s*\/agent-experiments(?:\s+[^>]*?)?\s*-->\s*$/;
+export const LAST_SYNC_RE =
+  /^<!--\s*last-successful-sync:\s*(\d{4}-\d{2}-\d{2})\s*-->\s*$/;
+// Attributed item line: `- #<n> [<agent>] <title> (by <author>)`. The author
+// suffix is mandatory and anchored at end; the title group is greedy, which is
+// unambiguous because sanitizeTitle defuses any embedded ` (by ` token.
+export const AGENT_EXPERIMENT_ITEM_RE =
+  /^- #(\d+) \[([a-z][a-z-]*)\] (.*) \(by (.+)\)$/;