@bradheitmann/odin-sentinel 0.4.4 → 0.4.6

package/scripts/audit/verify-pack.mjs

@@ -1,21 +1,8 @@
 import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
 
-const output = execFileSync("pnpm", ["pack", "--dry-run", "--json"], {
-  encoding: "utf8",
-  stdio: ["ignore", "pipe", "pipe"]
-});
-
-// pnpm 11 writes JSON directly to stdout (no preamble); pnpm <=10 prefixed
-// it with lifecycle logs. Handle both shapes: take from "\n{" if present, or
-// from the start if output already begins with "{".
-const newlineBrace = output.lastIndexOf("\n{");
-const jsonStart = newlineBrace !== -1 ? newlineBrace + 1 : (output.trimStart().startsWith("{") ? output.indexOf("{") : -1);
-if (jsonStart === -1) {
-  throw new Error("pnpm pack did not return JSON metadata");
-}
-
-const pack = JSON.parse(output.slice(jsonStart));
-const paths = new Set(pack.files.map((file) => file.path));
+export const MINIMUM_COMPATIBLE_CHILD_MCP_VERSION = "0.4.5";
 
 const requiredProtocolFiles = [
   "protocol/SCP.md",
@@ -29,7 +16,14 @@ const requiredProtocolFiles = [
   "protocol/bootstrap-skill.md"
 ];
 
-const requiredFiles = [
+const requiredTemplateFiles = [
+  "templates/dev-slice-template.md",
+  "templates/qa-slice-template.md",
+  "templates/pm-role-template.md",
+  "templates/team-manifest-template.yaml"
+];
+
+export const requiredPackageFiles = [
   "dist/src/bin/index.js",
   "dist/src/mcp/server.js",
   "dist/src/protocol/index.js",
@@ -39,34 +33,307 @@ const requiredFiles = [
   "dist/src/protocol/validators.js",
   "dist/src/protocol/version.js",
   "docs/guides/quick-start.md",
+  "docs/guides/quickstart-prompts.md",
   "docs/guides/recommended-starter-team.md",
   "docs/reference/client-compatibility.md",
   "docs/reference/cost-and-privacy.md",
   "docs/reference/distribution.md",
   "docs/reference/public-surface-audit.md",
   ...requiredProtocolFiles,
+  ...requiredTemplateFiles,
   "scripts/audit/public-surface.mjs",
   "scripts/audit/verify-pack.mjs",
+  "AGENTS.md",
+  "CLAUDE.md",
   "README.md",
   "LICENSE",
   "package.json"
 ];
 
-const missing = requiredFiles.filter((file) => !paths.has(file));
-if (missing.length > 0) {
-  throw new Error(`Package is missing required files: ${missing.join(", ")}`);
-}
-
-const staleFiles = [
+const staleBuildFiles = [
   "dist/src/index.js",
   "dist/src/server.js",
   "dist/src/protocol.js",
   "dist/src/protocol-repository.js",
   "dist/src/validators.js"
-].filter((file) => paths.has(file));
+];
+
+const protocolResourceVersionLockedFiles = new Set([
+  "protocol/SCP.md",
+  "protocol/closeout.yaml",
+  "protocol/delegation.yaml",
+  "protocol/model-profiles.yaml",
+  "protocol/roles.yaml",
+  "protocol/topology.yaml"
+]);
+
+const forbiddenPackagePrefixes = ["project/" + "planning" + "/", "." + "edge-" + "agentic" + "/local/"];
+const forbiddenPackagedContentRules = [
+  { name: "local evidence path", pattern: new RegExp(`\\.${"edge-" + "agentic"}/local`, "i") },
+  { name: "local ODIN audit path", pattern: /\.odin\/local\//i },
+  { name: "private planning path", pattern: new RegExp(`project/${"planning"}/`, "i") },
+  { name: "macOS home path", pattern: new RegExp(`/${"Users"}/[A-Za-z0-9._-]+/`) },
+  { name: "Linux home path", pattern: /\/home\/[A-Za-z0-9._-]+\// },
+  { name: "secret-looking assignment", pattern: /(api[_-]?key|secret|token|password)\s*[:=]\s*["'][^"']+["']/i }
+];
+
+function asPathSet(paths) {
+  return new Set(Array.from(paths));
+}
+
+export function validatePackageMetadata(packageJson) {
+  const errors = [];
+  if (!packageJson.repository?.url) errors.push("package.json missing repository.url");
+  if (!packageJson.homepage) errors.push("package.json missing homepage");
+  if (!packageJson.bugs?.url) errors.push("package.json missing bugs.url");
+  if (!packageJson.license) errors.push("package.json missing license");
+  if (!packageJson.engines?.node) errors.push("package.json missing engines.node");
+  if (!Array.isArray(packageJson.files) || packageJson.files.length === 0) errors.push("package.json missing files allowlist");
+  for (const file of ["docs", "protocol", "templates", "AGENTS.md", "CLAUDE.md", "README.md", "LICENSE"]) {
+    if (!packageJson.files?.includes(file)) errors.push(`package.json files allowlist missing ${file}`);
+  }
+  if (packageJson.odin?.publicVersion !== packageJson.version) {
+    errors.push("package.json odin.publicVersion must match package version");
+  }
+  if (packageJson.odin?.minimumCompatibleChildMcpVersion !== MINIMUM_COMPATIBLE_CHILD_MCP_VERSION) {
+    errors.push("package.json odin.minimumCompatibleChildMcpVersion drifted");
+  }
+  for (const [name, version] of Object.entries(packageJson.dependencies ?? {})) {
+    if (typeof version !== "string" || /^[~^]/.test(version) || /[<>=*x|]/i.test(version)) {
+      errors.push(`package.json runtime dependency ${name} must be pinned exactly`);
+    }
+  }
+  return errors;
+}
+
+export function validatePackFileList(pathsInput) {
+  const paths = asPathSet(pathsInput);
+  const errors = [];
+  const missing = requiredPackageFiles.filter((file) => !paths.has(file));
+  if (missing.length > 0) errors.push(`Package is missing required files: ${missing.join(", ")}`);
+
+  const stale = staleBuildFiles.filter((file) => paths.has(file));
+  if (stale.length > 0) errors.push(`Package includes stale build files: ${stale.join(", ")}`);
+
+  const privatePaths = Array.from(paths).filter((file) => forbiddenPackagePrefixes.some((prefix) => file.startsWith(prefix)));
+  if (privatePaths.length > 0) errors.push(`Package includes private local paths: ${privatePaths.join(", ")}`);
 
-if (staleFiles.length > 0) {
-  throw new Error(`Package includes stale build files: ${staleFiles.join(", ")}`);
+  return errors;
 }
 
-console.log(`Package smoke PASS: ${pack.files.length} files included in ${pack.filename}`);
+export function validatePackFileContents(fileTextByPath) {
+  const findings = [];
+  for (const [file, text] of Object.entries(fileTextByPath)) {
+    for (const rule of forbiddenPackagedContentRules) {
+      if (rule.pattern.test(text)) findings.push(`${file}: ${rule.name}`);
+    }
+  }
+  return findings;
+}
+
+function isTextPackageFile(file) {
+  return /\.(js|mjs|cjs|ts|json|md|ya?ml|txt|html|css|sh)$/.test(file) || !file.includes(".");
+}
+
+function readPackFileTexts(paths) {
+  return Object.fromEntries(
+    paths
+      .filter(isTextPackageFile)
+      .flatMap((file) => {
+        try {
+          return [[file, readFileSync(file, "utf8")]];
+        } catch {
+          return [];
+        }
+      })
+  );
+}
+
+export function findStaleVersionReferences(fileTextByPath, currentVersion, minimumCompatibleVersion = MINIMUM_COMPATIBLE_CHILD_MCP_VERSION) {
+  const allowed = new Set([currentVersion, minimumCompatibleVersion]);
+  const findings = [];
+  const versionPattern = /\b\d+\.\d+\.\d+\b/g;
+  const relevantVersionLine = (line) => {
+    const lower = line.toLowerCase();
+    if (/\bnode\.?js\b/.test(lower) || /\bengines?\b/.test(lower)) return false;
+    if (/^version:\s*\d+\.\d+\.\d+\s*$/.test(line.trim())) return false;
+    return [
+      "odin-sentinel",
+      "serverinfo",
+      "package/server",
+      "public version",
+      "minimum compatible",
+      "compatible child mcp",
+      "mcp version",
+      "server version",
+      "expected version",
+      "stale mcp version",
+      "confirm >=",
+      "server "
+    ].some((marker) => lower.includes(marker));
+  };
+
+  for (const [file, text] of Object.entries(fileTextByPath)) {
+    for (const line of text.split("\n")) {
+      if (!relevantVersionLine(line)) continue;
+      const matches = line.match(versionPattern) ?? [];
+      for (const version of matches) {
+        if (!allowed.has(version)) findings.push(`${file}: stale version reference ${version}`);
+      }
+    }
+  }
+
+  return findings;
+}
+
+export function validatePublicProtocolSync({ scpText, bootstrapText, currentVersion, minimumCompatibleVersion = MINIMUM_COMPATIBLE_CHILD_MCP_VERSION }) {
+  const errors = [];
+  const requiredMarkers = [
+    `SCP_PUBLIC_VERSION: ${currentVersion}`,
+    `MIN_COMPATIBLE_CHILD_MCP: ${minimumCompatibleVersion}`
+  ];
+
+  for (const marker of requiredMarkers) {
+    if (!scpText.includes(marker)) errors.push(`protocol/SCP.md missing ${marker}`);
+    if (!bootstrapText.includes(marker)) errors.push(`protocol/bootstrap-skill.md missing ${marker}`);
+  }
+
+  return errors;
+}
+
+export function validatePluginSync({ pluginManifestText, pluginSkillText, pluginReadmeText, currentVersion, minimumCompatibleVersion = MINIMUM_COMPATIBLE_CHILD_MCP_VERSION }) {
+  const errors = [];
+  let manifest;
+  try {
+    manifest = JSON.parse(pluginManifestText);
+  } catch {
+    errors.push("Claude plugin manifest must be valid JSON");
+    manifest = {};
+  }
+
+  if (manifest.version !== currentVersion) {
+    errors.push(`Claude plugin manifest version ${manifest.version ?? "<missing>"} must match package version ${currentVersion}`);
+  }
+  const server = manifest.mcpServers?.["odin-sentinel"];
+  if (!server) {
+    errors.push("Claude plugin manifest missing odin-sentinel MCP server");
+  } else {
+    if (server.command !== "npx") errors.push("Claude plugin odin-sentinel server must use npx");
+    const args = Array.isArray(server.args) ? server.args : [];
+    for (const requiredArg of ["-y", "-p", "@bradheitmann/odin-sentinel", "odin-sentinel-mcp"]) {
+      if (!args.includes(requiredArg)) errors.push(`Claude plugin odin-sentinel args missing ${requiredArg}`);
+    }
+  }
+
+  for (const marker of [`SCP_PUBLIC_VERSION: ${currentVersion}`, `MIN_COMPATIBLE_CHILD_MCP: ${minimumCompatibleVersion}`]) {
+    if (!pluginSkillText.includes(marker)) errors.push(`Claude plugin skill missing ${marker}`);
+  }
+  if (!/23\s+`?odin\.\*`?\s+tools/i.test(pluginReadmeText)) {
+    errors.push("Claude plugin README must advertise 23 odin.* tools");
+  }
+
+  return errors;
+}
+
+export function validatePackagedProtocolVersions(fileTextByPath, currentVersion) {
+  const errors = [];
+  for (const [file, text] of Object.entries(fileTextByPath)) {
+    if (!protocolResourceVersionLockedFiles.has(file)) continue;
+    const firstVersion = text.match(/^(?:version|Version):\s*([0-9]+\.[0-9]+\.[0-9]+)\s*$/m);
+    if (firstVersion && firstVersion[1] !== currentVersion) {
+      errors.push(`${file}: protocol resource version ${firstVersion[1]} must match package version ${currentVersion}`);
+    }
+  }
+  return errors;
+}
+
+export function validateBootstrapReadiness(bootstrapText) {
+  const required = ["MCP server", "native skill", "full prompt fallback", "CMUX", "auth/account readiness", "local inference", "role compatibility"];
+  return required.filter((term) => !bootstrapText.toLowerCase().includes(term.toLowerCase())).map((term) => `protocol/bootstrap-skill.md missing readiness term: ${term}`);
+}
+
+export function validateTelemetryWording(costPrivacyText) {
+  const errors = [];
+  if (/does not .*telemetry/i.test(costPrivacyText) && !/optional|user-invoked|not automatic/i.test(costPrivacyText)) {
+    errors.push("Telemetry wording must explain optional/user-invoked behavior");
+  }
+  if (!/optional telemetry/i.test(costPrivacyText) || !/user-invoked/i.test(costPrivacyText)) {
+    errors.push("Cost/privacy docs must describe optional user-invoked telemetry");
+  }
+  return errors;
+}
+
+function readPublicVersionFiles() {
+  return Object.fromEntries([
+    "README.md",
+    "docs/guides/quick-start.md",
+    "docs/guides/quickstart-prompts.md",
+    "docs/reference/client-compatibility.md",
+    "docs/reference/distribution.md",
+    "docs/reference/public-surface-audit.md",
+    "protocol/SCP.md",
+    "protocol/bootstrap-skill.md",
+    "plugins/sentinel-coordination-protocol/.claude-plugin/plugin.json",
+    "plugins/sentinel-coordination-protocol/skills/sentinel-coordination-protocol/SKILL.md",
+    "plugins/sentinel-coordination-protocol/README.md"
+  ].map((file) => [file, readFileSync(file, "utf8")]));
+}
+
+function parsePackOutput(output) {
+  const newlineBrace = output.lastIndexOf("\n{");
+  const jsonStart = newlineBrace !== -1 ? newlineBrace + 1 : (output.trimStart().startsWith("{") ? output.indexOf("{") : -1);
+  if (jsonStart === -1) throw new Error("pnpm pack did not return JSON metadata");
+  return JSON.parse(output.slice(jsonStart));
+}
+
+export function runVerifyPack({ pack, packageJson, publicVersionFiles, costPrivacyText, packFileTextByPath }) {
+  const packPaths = pack.files.map((file) => file.path);
+  const packFileTexts = packFileTextByPath ?? readPackFileTexts(packPaths);
+  const errors = [
+    ...validatePackageMetadata(packageJson),
+    ...validatePackFileList(packPaths),
+    ...validatePackFileContents(packFileTexts),
+    ...validatePackagedProtocolVersions(packFileTexts, packageJson.version),
+    ...findStaleVersionReferences(publicVersionFiles, packageJson.version),
+    ...validatePublicProtocolSync({
+      scpText: publicVersionFiles["protocol/SCP.md"],
+      bootstrapText: publicVersionFiles["protocol/bootstrap-skill.md"],
+      currentVersion: packageJson.version
+    }),
+    ...validatePluginSync({
+      pluginManifestText: publicVersionFiles["plugins/sentinel-coordination-protocol/.claude-plugin/plugin.json"],
+      pluginSkillText: publicVersionFiles["plugins/sentinel-coordination-protocol/skills/sentinel-coordination-protocol/SKILL.md"],
+      pluginReadmeText: publicVersionFiles["plugins/sentinel-coordination-protocol/README.md"],
+      currentVersion: packageJson.version
+    }),
+    ...validateBootstrapReadiness(publicVersionFiles["protocol/bootstrap-skill.md"]),
+    ...validateTelemetryWording(costPrivacyText)
+  ];
+
+  if (errors.length > 0) throw new Error(`Package release sync failed:\n${errors.join("\n")}`);
+  return {
+    fileCount: pack.files.length,
+    filename: pack.filename,
+    version: packageJson.version,
+    minimumCompatibleChildMcpVersion: MINIMUM_COMPATIBLE_CHILD_MCP_VERSION
+  };
+}
+
+export function main() {
+  const output = execFileSync("pnpm", ["pack", "--dry-run", "--json"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  const pack = parsePackOutput(output);
+  const packageJson = JSON.parse(readFileSync("package.json", "utf8"));
+  const publicVersionFiles = readPublicVersionFiles();
+  const costPrivacyText = readFileSync("docs/reference/cost-and-privacy.md", "utf8");
+  const result = runVerifyPack({ pack, packageJson, publicVersionFiles, costPrivacyText });
+
+  console.log(`Package smoke PASS: ${result.fileCount} files included in ${result.filename}`);
+  console.log(`Release sync PASS: public version ${result.version}; minimum compatible child MCP ${result.minimumCompatibleChildMcpVersion}`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main();
+}

package/templates/dev-slice-template.md

@@ -0,0 +1,56 @@
+# DEV Slice Template
+
+Use this as a public starter template. Replace every placeholder before launch.
+
+## Goal
+
+- Task: `<what to build or change>`
+- Owner: `<DEV role slot or agent>`
+- PM contact: `<PM role slot or human>`
+
+## Scope
+
+- Write-allowed files:
+  - `<path>`
+- Read-only context:
+  - `<path or doc>`
+- Out of scope:
+  - `<explicit non-goals>`
+
+## Requirements
+
+- Functional acceptance criteria:
+  - `<criterion 1>`
+  - `<criterion 2>`
+- User-defined criteria:
+  - `<project-specific criterion>`
+
+## Verification
+
+- Required commands:
+  - `<command>` -> expected `<result>`
+- Manual checks:
+  - `<check>`
+
+## DEV Report
+
+Return:
+
+- files changed
+- summary of implementation
+- verification commands and results
+- unmet criteria or blockers
+- risks for QA/integration
+
+## Boundaries
+
+DEV implements only the assigned scope and does not QA-accept its own work.
+
+## Minimal Filled Example
+
+- Task: `Update one README paragraph to clarify install steps`
+- Owner: `B/DEV-1`
+- Write-allowed files: `README.md`
+- Out of scope: `package code, release scripts, unrelated docs`
+- Required command: `pnpm test` -> expected `passes`
+- DEV report: `changed README.md; tests passed or blocker reported`

package/templates/pm-role-template.md

@@ -0,0 +1,61 @@
+# PM Role Template
+
+Use this as a public starter template for an ODIN Sentinel PM role.
+
+## Team Objective
+
+- Outcome: `<desired result>`
+- Deadline or session boundary: `<timebox>`
+- Human operator: `<name or role>`
+
+## Roles
+
+- EXEC PM: owns launch/activation, readiness waivers or substitutions, CMUX
+  topology, staffing, final claim framing, and escalation.
+- TEAM PM: owns routing and worker activation inside an assigned team after EXEC
+  PM launch. TEAM PM cannot staff new occupants, waive launch readiness, mutate
+  CMUX topology, or close lifecycle unless EXEC PM explicitly delegates it.
+- ODIN: monitors health, scope, delivery, and drift; intervenes or escalates.
+- DEV: implements assigned write scope only.
+- QA: verifies independently and reports PASS/FAIL.
+
+## Readiness Gates
+
+- Node.js version satisfies package metadata: `<status>`
+- ODIN MCP server configured and smoke-tested: `<status>`
+- Native skill or prompt fallback available: `<status>`
+- CMUX workspace and role slots ready: `<status>`
+- Harness auth/account readiness checked: `<status>`
+- Local inference smoke-tested if used: `<status>`
+- Role compatibility smoke test passed: `<status>`
+- Launch/waiver authority holder: `A/EXEC-PM`
+
+## Operator-Friendly Status
+
+- Plain-language summary: `<what is happening in one sentence>`
+- Current blocker, if any: `<sign-in | permission prompt | API/account setup | local model smoke test | none>`
+- Safe next choice for the human operator: `<approve | sign in | choose fallback harness | keep slot vacant | ask for help>`
+- Secret-handling reminder: `Do not paste API keys or tokens into chat.`
+
+## Assignments
+
+- `<role slot>` -> `<agent/harness>` -> `<scope>`
+
+## Blockers And Escalation
+
+- Blocker: `<description>`
+- Owner: `<role>`
+- Escalate to human when: `<condition>`
+
+## User-Defined Criteria
+
+- `<project-specific criterion>`
+
+## Minimal Filled Example
+
+- Outcome: `Clarify install documentation for first-time users`
+- Human operator: `project maintainer`
+- Readiness summary: `MCP smoke test passes; Claude Code sign-in still needed`
+- Safe next choice: `sign in to Claude Code, choose another harness, or keep that slot vacant`
+- Assignment: `B/DEV-1 -> Codex -> README.md only`
+- User-defined criterion: `Do not ask the operator to paste API keys`

package/templates/qa-slice-template.md

@@ -0,0 +1,46 @@
+# QA Slice Template
+
+Use this as a public starter template. Replace every placeholder before launch.
+
+## Parent DEV Reference
+
+- DEV task: `<task id or title>`
+- DEV changed files: `<list supplied by DEV>`
+- Expected verification: `<commands or checks>`
+
+## Fresh-Context Review
+
+QA starts from the task contract and changed files, not from DEV's confidence.
+
+## Checks
+
+- Acceptance criteria:
+  - `<criterion>` -> PASS/FAIL
+- Scope compliance:
+  - Only declared write-allowed files changed: PASS/FAIL
+- Security/privacy:
+  - No secrets printed or committed: PASS/FAIL
+  - No unsafe permission or auth behavior: PASS/FAIL
+- Regression risk:
+  - Relevant tests or manual checks reproduced: PASS/FAIL
+- User-defined criteria:
+  - `<project-specific criterion>` -> PASS/FAIL
+
+## QA Verdict
+
+Return one verdict:
+
+- PASS: all required checks passed.
+- FAIL: one or more required checks failed.
+- BLOCKED: QA could not verify because required evidence, access, or commands are missing.
+
+QA reports issues. QA does not fix code during the QA pass.
+
+## Minimal Filled Example
+
+- DEV task: `Update one README paragraph to clarify install steps`
+- DEV changed files: `README.md`
+- Expected verification: `pnpm test`
+- Acceptance criterion: `README explains global and zero-install paths`
+- Scope compliance: `Only README.md changed`
+- Verdict: `PASS`, `FAIL`, or `BLOCKED` with one-sentence evidence

package/templates/team-manifest-template.yaml

@@ -0,0 +1,163 @@
+session_id: "<session-id>"
+topology:
+  mode: "governed-team"
+  cmux_required: true
+  cmux_workspace: "<workspace-ref>"
+  layout: "human-readable spatial/pod organization"
+executive_office:
+  - "A/EXEC-PM"
+  - "A/EXEC-ODIN"
+  - "A/EXEC-ASST"
+development_pods:
+  - "B"
+odin_mesh:
+  cadence_seconds: 30
+  executive_odin: "A/EXEC-ODIN"
+  team_odins:
+    - "B/ODIN"
+model_profile:
+  minimum_compatible_child_mcp_version: "0.4.5"
+  inference_provider_inventory: []
+handoff_sources:
+  - "<handoff path or none>"
+startup_objectives:
+  - "<plain-language objective>"
+role_slots:
+  - role_slot: "A/EXEC-PM"
+    harness: "<harness>"
+    readiness_status: "PASS"
+    layout_locator:
+      workspace: "<workspace-ref>"
+      pane: "<pane-ref>"
+      surface: "<surface-ref>"
+    scp_context_source: "native sentinel-coordination-protocol skill"
+    mcp_available: true
+    mcp_version: "0.4.5"
+    scp_skill_available: true
+    full_protocol_text_injected: false
+    watcher: "A/EXEC-ODIN"
+  - role_slot: "A/EXEC-ODIN"
+    harness: "<harness>"
+    readiness_status: "PASS"
+    layout_locator:
+      workspace: "<workspace-ref>"
+      pane: "<pane-ref>"
+      surface: "<surface-ref>"
+    scp_context_source: "native sentinel-coordination-protocol skill"
+    mcp_available: true
+    mcp_version: "0.4.5"
+    scp_skill_available: true
+    full_protocol_text_injected: false
+    watches:
+      - "A/EXEC-PM"
+      - "B/ODIN"
+  - role_slot: "B/ODIN"
+    harness: "<harness>"
+    readiness_status: "PASS"
+    layout_locator:
+      workspace: "<workspace-ref>"
+      pane: "<pane-ref>"
+      surface: "<surface-ref>"
+    scp_context_source: "native sentinel-coordination-protocol skill"
+    mcp_available: true
+    mcp_version: "0.4.5"
+    scp_skill_available: true
+    full_protocol_text_injected: false
+    watches:
+      - "B/TEAM-PM"
+      - "B/DEV-1"
+  - role_slot: "B/DEV-1"
+    harness: "<harness>"
+    readiness_status: "PASS"
+    layout_locator:
+      workspace: "<workspace-ref>"
+      pane: "<pane-ref>"
+      surface: "<surface-ref>"
+    scp_context_source: "native sentinel-coordination-protocol skill"
+    mcp_available: true
+    mcp_version: "0.4.5"
+    scp_skill_available: true
+    full_protocol_text_injected: false
+    watcher: "B/ODIN"
+fallback_policy:
+  non_governed_one_shot_only: "Allowed only for bounded, non-persistent help when MCP/skill/protocol proof is absent. Not suitable for a persistent governed role."
+operator_friendly_status:
+  summary: "<what is happening in one sentence>"
+  current_blocker: "<sign-in | permission prompt | API/account setup | local model smoke test | none>"
+  safe_next_choice: "<approve | sign in | choose fallback harness | keep slot vacant | ask for help>"
+user_defined_criteria:
+  - "<project-specific criterion>"
+
+# Minimal filled example
+#
+# session_id: "example-session"
+# topology:
+#   mode: "governed-team"
+#   cmux_required: true
+#   cmux_workspace: "workspace:1"
+#   layout: "A executive office plus B development pod"
+# executive_office:
+#   - "A/EXEC-PM"
+#   - "A/EXEC-ODIN"
+# development_pods:
+#   - "B"
+# odin_mesh:
+#   cadence_seconds: 30
+#   executive_odin: "A/EXEC-ODIN"
+#   team_odins:
+#     - "B/ODIN"
+# model_profile:
+#   minimum_compatible_child_mcp_version: "0.4.5"
+#   inference_provider_inventory: []
+# handoff_sources:
+#   - "none"
+# startup_objectives:
+#   - "Clarify install documentation for first-time users"
+# role_slots:
+#   - role_slot: "A/EXEC-PM"
+#     harness: "Codex"
+#     readiness_status: "PASS"
+#     layout_locator:
+#       workspace: "workspace:1"
+#       pane: "pane:1"
+#       surface: "surface:1"
+#     scp_context_source: "native sentinel-coordination-protocol skill"
+#     mcp_available: true
+#     mcp_version: "0.4.5"
+#     scp_skill_available: true
+#     full_protocol_text_injected: false
+#     watcher: "A/EXEC-ODIN"
+#   - role_slot: "B/ODIN"
+#     harness: "Codex"
+#     readiness_status: "PASS"
+#     layout_locator:
+#       workspace: "workspace:1"
+#       pane: "pane:2"
+#       surface: "surface:2"
+#     scp_context_source: "native sentinel-coordination-protocol skill"
+#     mcp_available: true
+#     mcp_version: "0.4.5"
+#     scp_skill_available: true
+#     full_protocol_text_injected: false
+#     watches:
+#       - "B/TEAM-PM"
+#       - "B/DEV-1"
+#   - role_slot: "B/DEV-1"
+#     harness: "Codex"
+#     readiness_status: "PASS"
+#     layout_locator:
+#       workspace: "workspace:1"
+#       pane: "pane:2"
+#       surface: "surface:3"
+#     scp_context_source: "odin-sentinel MCP at or above minimum version"
+#     mcp_available: true
+#     mcp_version: "0.4.5"
+#     scp_skill_available: false
+#     full_protocol_text_injected: false
+#     watcher: "B/ODIN"
+# operator_friendly_status:
+#   summary: "Docs update is ready to dispatch."
+#   current_blocker: "none"
+#   safe_next_choice: "launch B/DEV-1"
+# user_defined_criteria:
+#   - "Do not ask the operator to paste API keys."