@bradheitmann/odin-sentinel 0.4.7 → 0.4.8

package/scripts/audit/verify-pack.mjs

@@ -201,7 +201,13 @@ export function validatePublicProtocolSync({ scpText, bootstrapText, currentVers
   return errors;
 }
 
-export function validatePluginSync({ pluginManifestText, pluginSkillText, pluginReadmeText, currentVersion, minimumCompatibleVersion = MINIMUM_COMPATIBLE_CHILD_MCP_VERSION }) {
+export function extractToolCount(text) {
+  if (typeof text !== "string") return null;
+  const match = text.match(/(\d+)\s+(?:`?odin\.\*`?\s+)?tools\b/i);
+  return match ? Number(match[1]) : null;
+}
+
+export function validatePluginSync({ pluginManifestText, pluginSkillText, pluginReadmeText, currentVersion, minimumCompatibleVersion = MINIMUM_COMPATIBLE_CHILD_MCP_VERSION, expectedToolCount }) {
   const errors = [];
   let manifest;
   try {
@@ -228,8 +234,11 @@ export function validatePluginSync({ pluginManifestText, pluginSkillText, plugin
   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");
+  const pluginToolCount = extractToolCount(pluginReadmeText);
+  if (pluginToolCount === null) {
+    errors.push("Claude plugin README must advertise its odin.* tool count");
+  } else if (typeof expectedToolCount === "number" && pluginToolCount !== expectedToolCount) {
+    errors.push(`Claude plugin README advertises ${pluginToolCount} odin.* tools but package.json describes ${expectedToolCount}`);
   }
 
   return errors;
@@ -304,7 +313,8 @@ export function runVerifyPack({ pack, packageJson, publicVersionFiles, costPriva
       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
+      currentVersion: packageJson.version,
+      expectedToolCount: extractToolCount(packageJson.description)
     }),
     ...validateBootstrapReadiness(publicVersionFiles["protocol/bootstrap-skill.md"]),
     ...validateTelemetryWording(costPrivacyText)

package/scripts/protocol/install-activation-hooks.mjs

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+// scripts/protocol/install-activation-hooks.mjs
+//
+// Install (or preview) the ODIN/SCP activation-gate hook that forces full-instruction-read
+// proof before an activated role begins implementation, QA acceptance, or ACTIVE_WATCH work.
+//
+// The hook is intentionally a small, dependency-free shell wrapper that runs the
+// instruction-read verifier against a declared proof file and refuses to proceed unless the
+// verifier exits 0. This makes "did the agent actually read its instructions?" a
+// machine-checkable gate instead of an honor-system claim.
+//
+// Safety: default mode is a dry-run that prints the plan and the hook body. Files are only
+// written when --install --target <dir> is given explicitly. Zero-secret: no environment
+// values are read or printed.
+
+import { existsSync, mkdirSync, writeFileSync, chmodSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const HOOK_FILENAME = "odin-activation-precheck.sh";
+
+const USAGE = `odin install-activation-hooks
+
+Install or preview the SCP activation-gate precheck hook. The hook runs the
+instruction-read verifier before an activated role acts, and blocks activation unless a
+full-instruction-read proof verifies against local files.
+
+Usage:
+  node scripts/protocol/install-activation-hooks.mjs               # dry-run: print plan + hook
+  node scripts/protocol/install-activation-hooks.mjs --print-hook  # print hook body only
+  node scripts/protocol/install-activation-hooks.mjs --install --target <dir>
+  node scripts/protocol/install-activation-hooks.mjs --help
+
+Options:
+  --install         Write the hook file. Requires --target.
+  --target <dir>    Directory to write ${HOOK_FILENAME} into (created if absent).
+  --print-hook      Print the hook script body to stdout and exit 0.
+  --force           Overwrite an existing hook file when installing.
+  --help, -h        Show this help and exit 0.
+
+Exit codes: 0 = help / dry-run / print / successful install; 2 = usage error;
+3 = refused to overwrite without --force.
+Zero-secret: this installer reads no environment variables and prints no secrets.`;
+
+// The activation precheck hook body. Pure POSIX sh; calls the sibling verifier.
+export function renderHookScript() {
+  return `#!/bin/sh
+# odin-activation-precheck.sh — installed by scripts/protocol/install-activation-hooks.mjs
+#
+# Block an activated SCP role from acting until its full-instruction-read proof verifies.
+# Usage: odin-activation-precheck.sh <proof.json> [--base <dir>]
+#
+# Wire this into a harness pre-activation step, a git pre-commit hook, or a launch runbook
+# so implementation / QA / ACTIVE_WATCH work cannot start on a skimmed instruction set.
+set -eu
+
+PROOF="\${1:-}"
+if [ -z "\$PROOF" ]; then
+  echo "odin-activation-precheck: missing <proof.json> argument" >&2
+  echo "an activated role must declare and verify a full-instruction-read proof first" >&2
+  exit 2
+fi
+shift || true
+
+SCRIPT_DIR=\$(CDPATH= cd -- "\$(dirname -- "\$0")" && pwd)
+VERIFIER="\$SCRIPT_DIR/verify-instruction-read.mjs"
+if [ ! -f "\$VERIFIER" ]; then
+  # Fall back to the repo-relative protocol script location.
+  VERIFIER="scripts/protocol/verify-instruction-read.mjs"
+fi
+
+echo "odin-activation-precheck: verifying full-instruction-read proof \$PROOF"
+if node "\$VERIFIER" "\$PROOF" "\$@"; then
+  echo "odin-activation-precheck: PASS — instruction-read proof verified; activation allowed"
+  exit 0
+else
+  echo "odin-activation-precheck: FAIL — instruction-read proof did not verify; activation blocked" >&2
+  echo "read the declared instruction files in full and regenerate the proof before acting" >&2
+  exit 1
+fi
+`;
+}
+
+export function planInstall(target) {
+  return {
+    action: "install-activation-hooks",
+    hookFile: target ? join(target, HOOK_FILENAME) : `<target>/${HOOK_FILENAME}`,
+    verifier: "scripts/protocol/verify-instruction-read.mjs",
+    gates: [
+      "An activated role must produce a full-instruction-read proof before implementation, QA acceptance, or ACTIVE_WATCH work.",
+      "The precheck hook runs verify-instruction-read.mjs and blocks activation unless it exits 0.",
+      "CMUX dispatch must additionally satisfy delivery proof: submitted=true plus verified processing on the target surface."
+    ],
+    mcp: ["odin.get_activation_gates", "odin.validate_instruction_read_proof", "odin.validate_cmux_delivery_proof"],
+    wiring: [
+      "harness pre-activation step (preferred)",
+      "git pre-commit / pre-push hook",
+      "launch runbook checklist step"
+    ]
+  };
+}
+
+function parseArgs(argv) {
+  const args = { install: false, printHook: false, force: false, help: false, target: undefined };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") args.help = true;
+    else if (a === "--install") args.install = true;
+    else if (a === "--print-hook") args.printHook = true;
+    else if (a === "--force") args.force = true;
+    else if (a === "--target") args.target = argv[++i];
+  }
+  return args;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+
+  if (args.printHook) {
+    process.stdout.write(renderHookScript());
+    process.exit(0);
+  }
+
+  if (!args.install) {
+    // Dry-run: show the plan and the hook body without writing anything.
+    console.log("odin install-activation-hooks (dry-run; no files written)");
+    console.log(JSON.stringify(planInstall(args.target), null, 2));
+    console.log("");
+    console.log(`Run with --install --target <dir> to write ${HOOK_FILENAME}.`);
+    console.log("--- hook body ---");
+    process.stdout.write(renderHookScript());
+    process.exit(0);
+  }
+
+  if (!args.target) {
+    console.error("error: --install requires --target <dir>");
+    console.error("run with --help for usage");
+    process.exit(2);
+  }
+
+  const targetDir = resolve(process.cwd(), args.target);
+  const hookPath = join(targetDir, HOOK_FILENAME);
+  if (existsSync(hookPath) && !args.force) {
+    console.error(`refused: ${hookPath} already exists (use --force to overwrite)`);
+    process.exit(3);
+  }
+
+  mkdirSync(targetDir, { recursive: true });
+  writeFileSync(hookPath, renderHookScript());
+  try {
+    chmodSync(hookPath, 0o755);
+  } catch {
+    // chmod is best-effort on platforms that do not support it.
+  }
+  console.log(`installed activation precheck hook: ${hookPath}`);
+  console.log("wire it into a harness pre-activation step, git hook, or launch runbook.");
+  process.exit(0);
+}
+
+const invokedDirectly = process.argv[1] && resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname);
+if (invokedDirectly) {
+  main();
+}

package/scripts/protocol/verify-instruction-read.mjs

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+// scripts/protocol/verify-instruction-read.mjs
+//
+// Verify an ODIN/SCP full-instruction-read proof against local files.
+//
+// An activated role (DEV, QA, ODIN ACTIVE_WATCH) must read its assigned instruction
+// sources in full before acting. This verifier confirms that every file declared in a
+// read proof still exists and matches its recorded byte count and SHA-256 digest, so a
+// role cannot claim it read instructions it only skimmed (first-screen / `head` / partial)
+// or never opened. A missing, truncated, or checksum-mismatched file fails the gate.
+//
+// Zero-secret: this script reads only the files named in the proof. It never reads
+// environment variables and never prints file contents — only paths, byte counts, line
+// counts, SHA-256 digests, and PASS/FAIL reasons.
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { isAbsolute, join, resolve } from "node:path";
+
+const USAGE = `odin verify-instruction-read
+
+Verify a full-instruction-read proof against local files. Confirms each declared
+instruction file exists and matches its recorded byte count and SHA-256 digest, so an
+activated role cannot claim a full read it did not perform.
+
+Usage:
+  node scripts/protocol/verify-instruction-read.mjs <proof.json> [--base <dir>] [--json]
+  node scripts/protocol/verify-instruction-read.mjs --record <file...> [--base <dir>] [--role <role>]
+  node scripts/protocol/verify-instruction-read.mjs --help
+
+Modes:
+  verify (default)  Read <proof.json> and verify every files[] entry against disk.
+                    Exit 0 only if all entries match. Exit 1 if any file is missing,
+                    truncated, or checksum-mismatched.
+  --record          Compute a fresh proof for the listed files and print it as JSON on
+                    stdout (does not write any file). Useful for an agent generating its
+                    own pre-edit read proof: redirect stdout to a proof file.
+
+Options:
+  --base <dir>      Resolve proof file entry paths against <dir> (default: current dir).
+  --role <role>     Role label embedded when using --record (default: UNDECLARED).
+  --json            Emit a machine-readable JSON result in verify mode.
+  --help, -h        Show this help and exit 0.
+
+Exit codes: 0 = all files verified / help / record; 1 = one or more files failed; 2 = usage error.
+Output is zero-secret: only paths, sizes, and digests are printed (never file contents).`;
+
+function sha256(buf) {
+  return createHash("sha256").update(buf).digest("hex");
+}
+
+function countLines(buf) {
+  return buf.toString("utf8").split("\n").length - 1;
+}
+
+function resolveEntryPath(base, p) {
+  return isAbsolute(p) ? p : join(base, p);
+}
+
+function parseArgs(argv) {
+  const args = { positional: [], base: ".", role: "UNDECLARED", json: false, help: false, record: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") args.help = true;
+    else if (a === "--json") args.json = true;
+    else if (a === "--record") args.record = true;
+    else if (a === "--base") args.base = argv[++i] ?? ".";
+    else if (a === "--role") args.role = argv[++i] ?? "UNDECLARED";
+    else args.positional.push(a);
+  }
+  return args;
+}
+
+export function recordProof(files, base = ".", role = "UNDECLARED") {
+  const entries = files.map((p) => {
+    const buf = readFileSync(resolveEntryPath(base, p));
+    return { path: p, bytes: buf.length, lines: countLines(buf), sha256: sha256(buf), read: "full" };
+  });
+  return {
+    schema: "odin.instruction_read_proof.v1",
+    role,
+    generated_at: new Date().toISOString(),
+    base: ".",
+    file_count: entries.length,
+    files: entries
+  };
+}
+
+// Pure verification core: takes a parsed proof object and a base dir, returns a result.
+// Exported so tests can exercise it without spawning a process.
+export function verifyProof(proof, base = ".") {
+  const files = Array.isArray(proof?.files) ? proof.files : null;
+  if (!files || files.length === 0) {
+    return { ok: false, base, passed: 0, total: 0, results: [], error: "proof has no files[] entries" };
+  }
+
+  const results = files.map((entry) => {
+    const path = entry && typeof entry.path === "string" ? entry.path : "";
+    const reasons = [];
+    if (path.trim() === "") {
+      return { path: path || "<unknown>", status: "FAIL", reasons: ["proof entry is missing a path"] };
+    }
+
+    const abs = resolveEntryPath(base, path);
+    if (!existsSync(abs) || !statSync(abs).isFile()) {
+      return { path, status: "FAIL", reasons: ["file missing"] };
+    }
+
+    const buf = readFileSync(abs);
+    const actualBytes = buf.length;
+    const actualSha = sha256(buf);
+
+    if (typeof entry.sha256 === "string" && entry.sha256.trim() !== "") {
+      if (entry.sha256 !== actualSha) {
+        reasons.push("sha256 mismatch (file changed, truncated, or only partially read)");
+      }
+    } else {
+      reasons.push("proof entry is missing a sha256 digest");
+    }
+    if (typeof entry.bytes === "number" && entry.bytes !== actualBytes) {
+      reasons.push(`byte count mismatch: recorded ${entry.bytes}, actual ${actualBytes}`);
+    }
+
+    return {
+      path,
+      status: reasons.length === 0 ? "PASS" : "FAIL",
+      reasons,
+      recordedBytes: typeof entry.bytes === "number" ? entry.bytes : null,
+      actualBytes,
+      recordedSha256: typeof entry.sha256 === "string" ? entry.sha256 : null,
+      actualSha256: actualSha,
+      recordedLines: typeof entry.lines === "number" ? entry.lines : null,
+      actualLines: countLines(buf)
+    };
+  });
+
+  const passed = results.filter((r) => r.status === "PASS").length;
+  return { ok: passed === results.length, base, passed, total: results.length, results };
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+
+  if (args.record) {
+    if (args.positional.length === 0) {
+      console.error("error: --record requires at least one file path");
+      console.error("run with --help for usage");
+      process.exit(2);
+    }
+    let proof;
+    try {
+      proof = recordProof(args.positional, args.base, args.role);
+    } catch (err) {
+      console.error(`error: ${err instanceof Error ? err.message : String(err)}`);
+      process.exit(2);
+    }
+    console.log(JSON.stringify(proof, null, 2));
+    process.exit(0);
+  }
+
+  const proofPath = args.positional[0];
+  if (!proofPath) {
+    console.error("error: missing <proof.json> argument");
+    console.error("run with --help for usage");
+    process.exit(2);
+  }
+
+  let proof;
+  try {
+    proof = JSON.parse(readFileSync(resolve(process.cwd(), proofPath), "utf8"));
+  } catch (err) {
+    console.error(`error: cannot read or parse proof file: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(2);
+  }
+
+  const result = verifyProof(proof, args.base);
+
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`instruction-read verify (base: ${result.base})`);
+    if (result.error) console.log(`  ! ${result.error}`);
+    for (const r of result.results) {
+      if (r.status === "PASS") {
+        console.log(`  [PASS] ${r.path} (${r.actualBytes} bytes, sha256 ${r.actualSha256.slice(0, 12)}…)`);
+      } else {
+        console.log(`  [FAIL] ${r.path} — ${r.reasons.join("; ")}`);
+      }
+    }
+    console.log(`${result.passed}/${result.total} files verified`);
+  }
+
+  process.exit(result.ok ? 0 : 1);
+}
+
+// Only run the CLI when invoked directly, not when imported by tests.
+const invokedDirectly = process.argv[1] && resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname);
+if (invokedDirectly) {
+  main();
+}

package/templates/dev-slice-template.md

@@ -32,6 +32,14 @@ Use this as a public starter template. Replace every placeholder before launch.
 - Manual checks:
   - `<check>`
 
+## Instruction-Read Proof (before editing)
+
+Before changing any file, read the full reading-list and context sources, then record a
+full-instruction-read proof (each file with a byte or line count and a SHA-256 digest).
+Generate it with `node scripts/protocol/verify-instruction-read.mjs --record <file...>` and
+verify it with `node scripts/protocol/verify-instruction-read.mjs <proof.json>`. First-screen
+or partial reads are insufficient.
+
 ## DEV Report
 
 Return:

package/templates/pm-role-template.md

@@ -37,6 +37,19 @@ Use this as a public starter template for an ODIN Sentinel PM role.
 - 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.`
 
+## Dispatch Delivery Proof
+
+When dispatching to a CMUX role, delivery is not complete until you:
+
+1. Send the text to the target surface.
+2. Submit with Enter (input-bar text is not delivery).
+3. Read the target surface.
+4. Confirm the agent processed or acknowledged the message.
+
+Record `target_surface_locator`, `submitted`, `verification_method`,
+`observed_processing_state`, `timestamp`, and `sender_role`, then validate with
+`odin.validate_cmux_delivery_proof`.
+
 ## Assignments
 
 - `<role slot>` -> `<agent/harness>` -> `<scope>`

package/templates/qa-slice-template.md

@@ -23,6 +23,9 @@ QA starts from the task contract and changed files, not from DEV's confidence.
   - No unsafe permission or auth behavior: PASS/FAIL
 - Regression risk:
   - Relevant tests or manual checks reproduced: PASS/FAIL
+- Activation gates:
+  - DEV provided a full-instruction-read proof and it verifies against local files: PASS/FAIL
+  - Any CMUX delivery proof is submitted and confirmed (not input-bar-only): PASS/FAIL
 - User-defined criteria:
   - `<project-specific criterion>` -> PASS/FAIL