@openrig/cli 0.5.4 → 0.5.6

package/daemon/assets/plugins/openrig-core/hooks/scripts/refocus.cjs

@@ -1,152 +1,299 @@
 #!/usr/bin/env node
 "use strict";
-// openrig-core REFOCUS hook (OPR.0.5.3.6 — promoted from the lab where it ran
-// live on 6+ seats; the mechanism ships, the CONTENT is configurable).
-//
-// WHY: the moment an agent most needs to reorient is the moment it is least
-// able to choose to. Drift does not feel like drift — it feels like work. So
-// refocus FIRES rather than waits to be invoked.
-//
-// THIS IS ALSO HOW TOPOLOGY CHAIN FILES REACH A RUNNING SEAT. Editing a file
-// under topology.root is not delivery — a running seat reads its config at
-// session start and its context never re-reads disk on its own. This hook is
-// the delivery channel: Stop / PostCompact observations retain due-state,
-// then inject orientation content at the seat's next context-visible boundary
-// (SessionStart / UserPromptSubmit), so a shipped or updated chain file becomes
-// live doctrine without a relaunch.
-//
-// SIGNAL = TRANSCRIPT GROWTH, not turns and not wall-clock. A "turn" is one
-// prompt submission; an agent can burn 200k tokens across fifty tool calls
-// inside ONE turn, so a turn counter is blind to exactly the drift that
-// matters. The JSONL grows monotonically with work done (measured ~8.9 bytes
-// per context token, so ~300k tokens ≈ 2.6MB — rough on purpose; it needs to
-// be monotonic, not exact). Tune with OPENRIG_REFOCUS_BYTES.
-//
-// CONTENT IS CONFIGURABLE, NEVER PROJECT-SPECIFIC IN SOURCE. Resolution:
-//   1. OPENRIG_REFOCUS_CONTENT_REF env — resolved by `rig context get`.
-//   2. OPENRIG_REFOCUS_CONTENT_FILE env — an operator-authored file.
-//   3. $OPENRIG_HOME/refocus/REFOCUS.md — the instance's standing content.
-//   4. The generic three-question orientation below (project-neutral).
-// Project- or mission-specific refocus text belongs in those FILES, on the
-// instance that needs it — it must never be committed here.
-//
-// Observes: SessionStart (fresh orientation), Stop (catches the long single
-// turn), UserPromptSubmit, and PostCompact on Claude (post-compaction
-// re-orientation; Codex exposes no compact hook — growth+Stop is the coverage
-// there). Emits only at context-visible boundaries and stays silent unless due.
-// A configured REF failure degrades loudly inside the delivered payload; every
-// failure remains non-blocking because a refocus hook must never break a turn.
+
+// Refocus is deliberately a long-session feature, not startup orientation.
+// Claude observes transcript growth; both runtimes observe their exact
+// PostCompact event; either accepts an explicit request. Stop/PostCompact
+// retain due-state; context is consumed exclusively at a UserPromptSubmit
+// boundary where the harness can actually deliver additionalContext.
 
 const fs = require("node:fs");
 const path = require("node:path");
+const crypto = require("node:crypto");
 const { spawnSync } = require("node:child_process");
-const THRESH = Number(process.env.OPENRIG_REFOCUS_BYTES || 2_600_000);
 
-const readStdin = () => new Promise((r) => { let d = ""; process.stdin.setEncoding("utf8");
-  process.stdin.on("data", (c) => d += c); process.stdin.on("end", () => r(d)); process.stdin.on("error", () => r("")); });
+const DEFAULT_THRESHOLD = 2_600_000;
+const FALSE_VALUES = new Set(["0", "false", "off", "no"]);
 
-(async () => {
-  let input = {}; try { input = JSON.parse((await readStdin()) || "{}") || {}; } catch {}
-  const ev = input.hook_event_name || "UserPromptSubmit";
-  const seat = process.env.OPENRIG_SESSION_NAME || "unknown-seat";
-  const home = process.env.OPENRIG_HOME || path.join(process.env.HOME || "/tmp", ".openrig");
-  const tpath = input.transcript_path || input.transcriptPath || "";
+function runtime() {
+  const index = process.argv.indexOf("--runtime");
+  return index >= 0 && process.argv[index + 1] === "codex" ? "codex" : "claude";
+}
 
-  let size = 0; try { size = fs.statSync(tpath).size; } catch {}
+function enabled(value, fallback = true) {
+  if (value === undefined || value === "") return fallback;
+  return !FALSE_VALUES.has(String(value).trim().toLowerCase());
+}
 
-  const dir = path.join(home, "refocus");
-  const file = path.join(dir, `${seat.replace(/[^A-Za-z0-9@._-]/g, "_")}.json`);
-  let st = { lastBytes: 0 };
-  try { st = JSON.parse(fs.readFileSync(file, "utf8")) || st; } catch {}
-  const writeState = () => {
-    try { fs.mkdirSync(dir, { recursive: true }); fs.writeFileSync(file, JSON.stringify(st)); } catch {}
-  };
+function threshold() {
+  const value = Number(process.env.OPENRIG_REFOCUS_BYTES || DEFAULT_THRESHOLD);
+  return Number.isFinite(value) && value > 0 ? value : DEFAULT_THRESHOLD;
+}
 
-  const grown = size > 0 ? size - (st.lastBytes || 0) : 0;
-  const due = ev === "SessionStart" || ev === "PostCompact" || Boolean(st.pendingOn) || grown >= THRESH;
-  if (!due) { process.exit(0); } // silent no-op — the common path
-
-  // Stop and PostCompact do not expose hook output to the agent's next context.
-  // Remember that delivery is due, but do not consume transcript growth until a
-  // context-visible boundary actually accepts the payload.
-  const contextVisible = ev === "SessionStart" || ev === "UserPromptSubmit";
-  if (!contextVisible) {
-    st.pendingOn ||= ev;
-    st.pendingAt ||= new Date().toISOString();
-    writeState();
-    process.exit(0);
-  }
+const readStdin = () => new Promise((resolve) => {
+  let data = "";
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (chunk) => { data += chunk; });
+  process.stdin.on("end", () => resolve(data));
+  process.stdin.on("error", () => resolve(""));
+});
 
-  // A library ref wins over file configuration and reuses the public assembler instead of
-  // growing a second resolver inside this hook. REF failures stay visible without blocking
-  // the session boundary; REF-unset follows the folded FILE/default path byte-for-byte.
+function readConfiguredContent(home) {
   const contentRef = process.env.OPENRIG_REFOCUS_CONTENT_REF || "";
-  let configured = null;
-  let refFailure = null;
   if (contentRef) {
     const result = spawnSync("rig", ["context", "get", contentRef], {
       encoding: "utf8",
       env: process.env,
-      timeout: 4_000,
+      timeout: 2_000,
       maxBuffer: 16 * 1024 * 1024,
     });
     if (!result.error && result.status === 0 && result.stdout.trim()) {
-      configured = result.stdout;
-    } else {
-      refFailure = result.error?.message
-        || result.stderr?.trim()
-        || result.stdout?.trim()
-        || `rig context get exited ${result.status ?? "without a status"}`;
-      refFailure = String(refFailure).replace(/\s+/g, " ").trim();
-    }
-  } else {
-    // Configurable content: operator file beats instance file beats the generic default.
-    const contentFile = [
-      process.env.OPENRIG_REFOCUS_CONTENT_FILE,
-      path.join(home, "refocus", "REFOCUS.md"),
-    ].filter(Boolean).find((p) => { try { return fs.existsSync(p); } catch { return false; } });
-    if (contentFile) {
-      try { configured = fs.readFileSync(contentFile, "utf8").trim() || null; } catch {}
+      return { content: result.stdout, contentRef, failure: null };
     }
+    const failure = result.error?.message
+      || result.stderr?.trim()
+      || result.stdout?.trim()
+      || `rig context get exited ${result.status ?? "without a status"}`;
+    return {
+      content: null,
+      contentRef,
+      failure: String(failure).replace(/\s+/g, " ").trim(),
+    };
   }
 
-  const why = ev === "SessionStart" ? "fresh session"
-            : st.pendingOn === "PostCompact" ? "just compacted — your picture is lossy"
-            : `${Math.round(grown / 1e6 * 10) / 10}MB of work since your last refocus`;
-
-  const generic = [
-    `1. What is the person actually trying to get? Not your current task — the outcome.`,
-    `2. Does what you are doing RIGHT NOW move that? If you cannot say what a user gets, stop and say so.`,
-    `3. What have you concluded without opening the file or running the thing?`,
-    ``,
-    `Discomfort on any of these IS the signal — drift feels like work.`,
-    ``,
-    `Your topology context (instance/rig/seat craft and this seat's LEARNED) is one walk away:`,
-    `rig context trace --rig <rig> --seat <seat> --name CRAFT.md — read it, do not recall it.`,
-    `A seat's LEARNED.md is written by previous occupants in the first person: it is evidence`,
-    `about the SEAT, never your own memory.`,
-  ];
+  const configuredFile = [
+    process.env.OPENRIG_REFOCUS_CONTENT_FILE,
+    path.join(home, "refocus", "REFOCUS.md"),
+  ].filter(Boolean).find((candidate) => {
+    try { return fs.existsSync(candidate); } catch { return false; }
+  });
+  if (configuredFile) {
+    try {
+      const content = fs.readFileSync(configuredFile, "utf8").trim();
+      if (content) return { content, contentRef: "", failure: null };
+    } catch {}
+  }
+
+  const shippedDefault = path.resolve(__dirname, "../../skills/refocusing/references/refocus.md");
+  try {
+    const content = fs.readFileSync(shippedDefault, "utf8").trim();
+    if (content) return { content, contentRef: "", failure: null };
+  } catch {}
 
-  const payload = refFailure ? [
-    `REFOCUS CONTENT REF FAILED: ${contentRef} — ${refFailure}`,
-    ``,
-    `REFOCUS (${why}). Answer briefly, out loud, before your next move:`,
-    ``,
-    ...generic,
-  ] : [
-    `REFOCUS (${why}). Answer briefly, out loud, before your next move:`,
-    ``,
-    ...(contentRef
-      ? [`REFOCUS CONTENT SOURCE: OPENRIG_REFOCUS_CONTENT_REF=${contentRef}`, ``, configured]
-      : configured ? [configured] : generic),
+  return {
+    content: [
+      "1. What is the person actually trying to get? Not your current task — the outcome.",
+      "2. Does what you are doing RIGHT NOW move that? If you cannot say what a user gets, stop and say so.",
+      "3. What have you concluded without opening the file or running the thing?",
+    ].join("\n"),
+    contentRef: "",
+    failure: null,
+  };
+}
+
+function renderTrace() {
+  const script = path.resolve(__dirname, "../../skills/refocusing/scripts/trace-to-root.py");
+  const args = [
+    script,
+    "--trees", process.env.OPENRIG_REFOCUS_TREES || "both",
+    "--depth", process.env.OPENRIG_REFOCUS_DEPTH || "light",
   ];
-  const output = JSON.stringify({ hookSpecificOutput: { hookEventName: ev, additionalContext: payload.join("\n") } });
+  if (process.env.OPENRIG_REFOCUS_TOPOLOGY_NODE) {
+    args.push("--topology-start", process.env.OPENRIG_REFOCUS_TOPOLOGY_NODE);
+  }
+  if (process.env.OPENRIG_REFOCUS_WORK_NODE) {
+    args.push("--work-start", process.env.OPENRIG_REFOCUS_WORK_NODE);
+  }
+  const result = spawnSync(process.env.PYTHON || "python3", args, {
+    encoding: "utf8",
+    env: process.env,
+    timeout: 2_000,
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  if (!result.error && result.status === 0 && result.stdout.trim()) return result.stdout.trim();
+  const reason = result.error?.message || result.stderr?.trim() || `trace exited ${result.status ?? "without a status"}`;
+  return `TRACE GAP — ${String(reason).replace(/\s+/g, " ").trim()}`;
+}
+
+(async () => {
+  if (!enabled(process.env.OPENRIG_REFOCUS_ENABLED)) process.exit(0);
+
+  let input = {};
+  try { input = JSON.parse((await readStdin()) || "{}") || {}; } catch {}
+  const event = input.hook_event_name || "UserPromptSubmit";
+  const harness = runtime();
+
+  // Fresh-session orientation is the default onboarding pack's job. Even a manually invoked hook must
+  // no-op here, so a stale registration cannot corrupt the world install.
+  if (event === "SessionStart") process.exit(0);
+
+  const seat = process.env.OPENRIG_SESSION_NAME || "unknown-seat";
+  const home = process.env.OPENRIG_HOME || path.join(process.env.HOME || "/tmp", ".openrig");
+  const transcriptPath = input.transcript_path || input.transcriptPath || "";
+  let size = 0;
+  try { size = fs.statSync(transcriptPath).size; } catch {}
+
+  const stateDir = path.join(home, "refocus");
+
+  // OPR.0.5.6.25 — state keys to the OCCUPANT, not the seat. A seat-keyed file made
+  // a fresh occupant inherit its predecessor's lastBytes (permanently zero growth on
+  // exactly the seats that swap) and its pending delivery. Identity derives from the
+  // hook family's own fields; the guarded expression never evaluates basename on an
+  // absent value. The legacy `${seat}.json` is NEVER read, imported, or rewritten —
+  // it stays on disk as diagnosis/migration material only.
+  const sanitize = (raw) => String(raw).replace(/[^A-Za-z0-9@._-]/g, "_");
+  const seatKey = sanitize(seat);
+  const firstString = (...vals) => {
+    for (const v of vals) if (typeof v === "string" && v.trim()) return v.trim();
+    return null;
+  };
+  const transcriptIdentity = input.transcript_path
+    ? path.basename(input.transcript_path, ".jsonl")
+    : input.transcriptPath
+      ? path.basename(input.transcriptPath, ".jsonl")
+      : null;
+  const identity = firstString(input.session_id, input.sessionId, transcriptIdentity);
+
+  // Bounded, deterministic, collision-stable key: lossy sanitization or truncation
+  // appends a stable short hash of the full pre-sanitization identity, so distinct
+  // identities stay distinct and every path stays inside the state directory.
+  const KEY_MAX = 64;
+  const keyFor = (raw) => {
+    const bounded = sanitize(raw).slice(0, KEY_MAX);
+    if (bounded === String(raw)) return bounded;
+    const suffix = crypto.createHash("sha256").update(String(raw)).digest("hex").slice(0, 8);
+    return `${bounded}__${suffix}`;
+  };
+
+  // No-identity diagnostic sentinel: an ACTIVE-EPISODE marker only — never a
+  // baseline, growth claim, pending, or fire. "#" is outside the key character
+  // class, so no derived identity path can ever collide with it. First missing
+  // event records and surfaces once; repeats stay silent; a valid-identity event
+  // clears the marker so a later distinct episode surfaces once again.
+  const sentinelFile = path.join(stateDir, `${seatKey}#no-identity-sentinel.json`);
+  if (identity === null) {
+    let sentinel = null;
+    try { sentinel = JSON.parse(fs.readFileSync(sentinelFile, "utf8")); } catch {}
+    if (!sentinel || sentinel.activeEpisode !== true) {
+      try {
+        fs.mkdirSync(stateDir, { recursive: true });
+        fs.writeFileSync(sentinelFile, JSON.stringify({ activeEpisode: true, recordedAt: new Date().toISOString() }));
+      } catch {}
+      process.stderr.write(`refocus: no session identity and no transcript path for ${seat} — measurement unavailable this episode\n`);
+    }
+    process.exit(0);
+  }
+  try {
+    const sentinel = JSON.parse(fs.readFileSync(sentinelFile, "utf8"));
+    if (sentinel && sentinel.activeEpisode === true) {
+      fs.writeFileSync(sentinelFile, JSON.stringify({ activeEpisode: false, clearedAt: new Date().toISOString() }));
+    }
+  } catch {}
+
+  const stateFile = path.join(stateDir, `${seatKey}__${keyFor(identity)}.json`);
+  let state = null;
+  try { state = JSON.parse(fs.readFileSync(stateFile, "utf8")) || null; } catch {}
+  const persist = () => {
+    try {
+      fs.mkdirSync(stateDir, { recursive: true });
+      fs.writeFileSync(stateFile, JSON.stringify(state));
+    } catch {}
+  };
+
+  if (state === null) {
+    // First observation for this occupant: the baseline is its OWN current size —
+    // growth accumulates from here; nothing is inherited. A zero-size read means
+    // the transcript is absent/unreadable, which is instrument absence, not a
+    // baseline: record zero only when that is what was genuinely measured.
+    state = { lastBytes: size, baselineAt: new Date().toISOString() };
+    persist();
+  } else if (size > 0 && size < Number(state.lastBytes || 0)) {
+    // Shrink clears pending and resets the baseline BEFORE due computation. The
+    // reset itself emits no refocus, and a stale pending can never ride through a
+    // reset into a delivery. Advisory once per reset episode: the reset moment is
+    // the dedupe (afterwards lastBytes === size), and the marker records in state.
+    delete state.pendingOn;
+    delete state.pendingAt;
+    state.lastReset = { at: new Date().toISOString(), fromBytes: Number(state.lastBytes || 0), toBytes: size };
+    state.lastBytes = size;
+    persist();
+    process.stderr.write(`refocus: transcript shrank for ${seat} — baseline reset, pending cleared\n`);
+  }
+
+  const lastBytes = Number(state.lastBytes || 0);
+  const grown = size > lastBytes ? size - lastBytes : 0;
+  const onDemand = enabled(process.env.OPENRIG_REFOCUS_NOW, false);
+  const thresholdDue = harness === "claude" && grown >= threshold();
+  const due = onDemand
+    || event === "PostCompact"
+    || Boolean(state.pendingOn)
+    || thresholdDue;
+  if (!due) process.exit(0);
+
+  if (event !== "UserPromptSubmit") {
+    if (event === "PostCompact" || !state.pendingOn) state.pendingOn = event;
+    state.pendingAt ||= new Date().toISOString();
+    persist();
+    process.exit(0);
+  }
+
+  // Run the public trace before resolving a context ref. Besides keeping the
+  // content ladder untouched, this makes `rig context get` the last resolver
+  // call and preserves the existing observable ref contract.
+  const trace = renderTrace();
+  const configured = readConfiguredContent(home);
+  const why = onDemand
+    ? "on demand"
+    : state.pendingOn === "PostCompact"
+      ? "just compacted — your picture is lossy"
+      : `${Math.round(grown / 1e6 * 10) / 10}MB of work since your last refocus`;
+
+  const body = configured.failure
+    ? [
+        `REFOCUS CONTENT REF FAILED: ${configured.contentRef} — ${configured.failure}`,
+        "",
+        "The configured source failed; use the shipped default below for this turn.",
+        "",
+        "",
+      ]
+    : configured.contentRef
+      ? [`REFOCUS CONTENT SOURCE: OPENRIG_REFOCUS_CONTENT_REF=${configured.contentRef}`, "", configured.content]
+      : [configured.content];
+
+  // A ref failure must still carry the generic default. Avoid recursing through
+  // the failed ref by reading the shipped file directly.
+  if (configured.failure) {
+    try {
+      body[4] = fs.readFileSync(
+        path.resolve(__dirname, "../../skills/refocusing/references/refocus.md"),
+        "utf8",
+      ).trim();
+    } catch {
+      body[4] = "1. What is the person actually trying to get?\n2. Does the current action move that outcome?\n3. What claim has not been checked at source?";
+    }
+  }
+
+  const payload = (configured.failure
+    ? [...body, "", trace]
+    : [
+        `REFOCUS (${why}). Answer briefly, out loud, before your next move:`,
+        "",
+        trace,
+        "",
+        ...body,
+      ]).join("\n");
+  const output = JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "UserPromptSubmit",
+      additionalContext: payload,
+    },
+  });
   process.stdout.write(output, () => {
-    st.lastBytes = size;
-    st.firedAt = new Date().toISOString();
-    st.firedOn = ev;
-    delete st.pendingOn;
-    delete st.pendingAt;
-    writeState();
+    if (size > 0) state.lastBytes = size;
+    state.firedAt = new Date().toISOString();
+    state.firedOn = event;
+    delete state.pendingOn;
+    delete state.pendingAt;
+    persist();
   });
 })();

package/daemon/assets/plugins/openrig-core/skills/applying-a-permission-policy/SKILL.md

@@ -3,12 +3,12 @@ name: applying-a-permission-policy
 description: "Use when a permission policy is attached to a rig/seat (rig.yaml permission_policy:), or a user asks you to apply one, and you must translate that harness-neutral policy into the target harness's LIVE permission config — Claude settings.json / Codex config.toml / Pi run flags. Agent-driven and interactive: you read the policy, ground yourself in YOUR harness version, show the diff, and ask before writing. NOT for defining policies (that's the policy spec) and NOT a set-and-forget updater."
 metadata:
   openrig:
-    stage: established             # config cells VM-verified + cold-transfer PASSING (rerun #2, 627abbb6) + built-in SPEC FILES landed → skill translates FROM the spec (POINT-not-COPY). The two established criteria met 2026-08-04. Reviewed at push.
+    stage: established             # config cells VM-verified + cold-transfer PASSING (rerun #2) + built-in SPEC FILES landed → skill translates FROM the spec (POINT-not-COPY). The two established criteria met 2026-08-04. Reviewed at push.
     tested_against:                # VERSION STAMP — the whole point; re-verify at every harness bump
       claude_code: "2.1.220 — VM-CONFIRMED 2026-08-03 (all cells)"
       codex: "0.120.0 — VM-CONFIRMED 2026-08-03 (sandbox_mode/approval_policy; on-failure deprecated-but-accepted)"
       pi: "0.83.0 — VM-CONFIRMED 2026-08-03: --approve/--no-approve govern PROJECT-RESOURCE TRUST, NOT tool permissions; Pi has NO permission surface (see Pi leg)"
-    verification_status: "Live-verified 2026-08-03/04 (dev-qa @ v-openrig-build). Claude 2.1.220 + Codex 0.120.0 config cells CONFIRMED live. Pi 0.83.0 divergence folded (flags = project-resource trust, not a permission gate). Cold-transfer rerun #1 blocked on the force_push/push_to_remote prefix collision → added the PREFIX-COLLISION rule. Cold-transfer rerun #2 (qitem 001c95fd, verdict SHA 627abbb6bf08ad2f350e2101f11438975def7b193b8da8bbcb747647239afc358): TRANSFERS — all 5 gate checks pass (collision resolved deterministically without asking; single ordinary write confirmation; defaultMode floor written; Codex workspace-write/on-request; Pi compute-nothing). Blocking collision/floor defect CLOSED → gate cleared, 4.8-shippable (provisional-with-passing-cold-transfer). Non-blocking seam closed: the built-in SPEC FILES landed (arch-accepted, source:builtin) → skill translates FROM the spec, interim in-skill pinned summary retired (POINT-not-COPY). stage:ESTABLISHED 2026-08-04 — both criteria met."
+    verification_status: "Live-verified 2026-08-03/04. Claude 2.1.220 + Codex 0.120.0 config cells CONFIRMED live. Pi 0.83.0 divergence folded (flags = project-resource trust, not a permission gate). Cold-transfer rerun #1 blocked on the force_push/push_to_remote prefix collision → added the PREFIX-COLLISION rule. Cold-transfer rerun #2: TRANSFERS — all 5 gate checks pass (collision resolved deterministically without asking; single ordinary write confirmation; defaultMode floor written; Codex workspace-write/on-request; Pi compute-nothing). Blocking collision/floor defect CLOSED → gate cleared, 4.8-shippable (provisional-with-passing-cold-transfer). Non-blocking seam closed: the built-in SPEC FILES landed (arch-accepted, source:builtin) → skill translates FROM the spec, interim in-skill pinned summary retired (POINT-not-COPY). stage:ESTABLISHED 2026-08-04 — both criteria met."
 ---
 
 # Applying a permission policy
@@ -117,4 +117,4 @@ Built-ins ship read-only in the package (canonical names); copy-to-customize int
 This skill TRANSLATES + APPLIES only. It does **not** define policies (the policy spec does) and does **not** enforce at the daemon (OpenRig is agnostic). Spec = *what* (neutral intent); this skill = *how, on this harness version* (the caveated, version-stamped translation).
 
 ---
-*Stage: ESTABLISHED (2026-08-04) — both criteria met: (1) cold-transfer PASSING (rerun #2, verdict SHA 627abbb6, all 5 gate checks TRANSFER); (2) the built-in policy SPEC FILES landed (`source: builtin`, arch-accepted) as the authoritative source — the skill now translates FROM the spec and the interim in-skill pinned summary is retired (POINT-not-COPY). Config cells VM-CONFIRMED (Claude 2.1.220 / Codex 0.120.0); Pi has no permission surface (compute-nothing). Reviewed at push. feedback.md maintained.*
+*Stage: ESTABLISHED (2026-08-04) — both criteria met: (1) cold-transfer PASSING (rerun #2, all 5 gate checks TRANSFER); (2) the built-in policy SPEC FILES landed (`source: builtin`, arch-accepted) as the authoritative source — the skill now translates FROM the spec and the interim in-skill pinned summary is retired (POINT-not-COPY). Config cells VM-CONFIRMED (Claude 2.1.220 / Codex 0.120.0); Pi has no permission surface (compute-nothing). Reviewed at push. feedback.md maintained.*

package/daemon/assets/plugins/openrig-core/skills/forming-an-openrig-mental-model/SKILL.md

@@ -263,17 +263,12 @@ For real depth, these are the load-bearing canonical docs:
 | `openrig/docs/reference/agent-spec.md` | The AgentSpec YAML format — resources, profiles, imports |
 | `openrig/docs/reference/agent-startup-guide.md` | The 7-layer startup layering model; delivery hints |
 | the product taxonomy | Canonical vocabulary (read literally) |
-| `substrate/shared-docs/HOST-TOPOLOGY.md` | Host-level doctrine — rig classes, context patterns, lifecycle, authoring SOP |
-| `substrate/shared-docs/SUBSTRATE-CONVENTIONS.md` | Filesystem layout doctrine for substrate |
+| `openrig-operating-model` skill | Placement and operating-model guidance — topology and work trees, context altitude |
+| `openrig-architect` skill | Rig and topology authoring |
 | `https://agentskills.io/specification` | The cross-runtime skill standard |
 
-If you're going to be authoring rigs, read `HOST-TOPOLOGY.md` §7 (the
-authoring SOP) before touching YAML.
-
-If you're going to be doing skill work, read
-the factory-design reference and the
-`operating-the-skill-library` skill that lives in
-`substrate/shared-docs/rigs/skill-library/agents/shared/skills/`.
+If you're going to be authoring rigs, use the `openrig-architect` skill before
+touching YAML.
 
 ---