@raishin/vanguard-frontier-agentic 3.15.0 → 3.17.0

package/scripts/mods/common.mjs

@@ -0,0 +1,213 @@
+// Shared helpers for the mods under mods/. scripts/generate-mods.mjs copies this file
+// byte-for-byte to mods/<id>/lib/common.mjs, so edit it here and run `npm run mods:write`.
+//
+// Pure on purpose: no imports, no environment, no I/O. Claude Code's native mod runtime
+// imports it and has no Node, and every harness must reach the same verdict on the same
+// input. Regexes compile without the `u` flag so Node and Python `re.ASCII`
+// (tests/validate-mods.py) read them the same way.
+
+export const LIMITS = Object.freeze({
+  // A redaction that still changes after this many passes is withheld as a whole.
+  maxPasses: 8,
+  // A guard candidate longer than this is not evaluated and counts as a hit.
+  maxCandidateChars: 65536,
+  // Guard candidates are not evaluated past this combined length; the call counts as a hit.
+  maxTotalChars: 262144,
+  // Only the tail of a leaf's context (key or previous sibling) is prefixed to it.
+  maxContextChars: 256,
+})
+
+const MARKER_PREFIX = '[REDACTED:'
+export const OVERFLOW_MARKER = '[REDACTED:overflow]'
+const OVERFLOW_HIT = Object.freeze({ id: 'overflow', name: 'redaction did not converge' })
+export const TOO_LARGE_HIT = Object.freeze({ id: 'too-large', name: 'input too large to evaluate' })
+
+const ID_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/
+const PATTERN_KEYS = new Set(['id', 'name', 'description', 'regex', 'flags', 'context', 'severity', 'agents'])
+const isStringArray = (v) => Array.isArray(v) && v.every((s) => typeof s === 'string' && s !== '')
+
+// Parser diagnostics can quote credential-bearing data; never expose it in hook logs.
+export function parseJson(text, source) {
+  try {
+    return JSON.parse(text)
+  } catch {
+    throw new Error(`${source}: invalid JSON`)
+  }
+}
+
+// Validates a patterns.json-shaped list and compiles it. Throws on anything malformed so a
+// bad extension file fails closed in the caller instead of silently matching nothing.
+export function compilePatterns(list, source = 'patterns') {
+  if (!Array.isArray(list)) throw new Error(`${source}: expected an array of patterns`)
+  const seen = new Set()
+  return list.map((p, i) => {
+    const where = `${source}[${i}]`
+    if (p === null || typeof p !== 'object' || Array.isArray(p)) throw new Error(`${where}: expected an object`)
+    for (const k of Object.keys(p)) if (!PATTERN_KEYS.has(k)) throw new Error(`${where}: unknown key ${k}`)
+    if (typeof p.id !== 'string' || !ID_RE.test(p.id)) throw new Error(`${where}: id must be kebab-case`)
+    if (seen.has(p.id)) throw new Error(`${where}: duplicate id ${p.id}`)
+    seen.add(p.id)
+    if (typeof p.name !== 'string' || p.name === '') throw new Error(`${where}: name must be a non-empty string`)
+    if (typeof p.regex !== 'string' || p.regex === '') throw new Error(`${where}: regex must be a non-empty string`)
+    if (p.flags !== '' && p.flags !== 'i') throw new Error(`${where}: flags must be "" or "i"`)
+    if (!isStringArray(p.context) || p.context.length === 0) throw new Error(`${where}: context must be a non-empty string array`)
+    for (const k of ['description', 'severity']) {
+      if (p[k] !== undefined && typeof p[k] !== 'string') throw new Error(`${where}: ${k} must be a string`)
+    }
+    if (p.agents !== undefined && !isStringArray(p.agents)) throw new Error(`${where}: agents must be a string array`)
+    let rx, rxg
+    try {
+      rx = new RegExp(p.regex, p.flags)
+      rxg = new RegExp(p.regex, 'g' + p.flags)
+    } catch {
+      throw new Error(`${where}: regex does not compile`)
+    }
+    return Object.freeze({
+      id: p.id,
+      name: p.name,
+      severity: p.severity,
+      context: Object.freeze([...p.context]),
+      agents: p.agents ? Object.freeze([...p.agents]) : undefined,
+      rx,
+      rxg,
+      marker: `${MARKER_PREFIX}${p.id}]`,
+    })
+  })
+}
+
+// Every string value (not key) in depth-first order. The order follows the input, so the
+// same payload always yields the same list.
+export function stringLeaves(value, out = []) {
+  if (typeof value === 'string') out.push(value)
+  else if (Array.isArray(value)) for (const v of value) stringLeaves(v, out)
+  else if (value !== null && typeof value === 'object') for (const v of Object.values(value)) stringLeaves(v, out)
+  return out
+}
+
+// Guard candidates: every string leaf, plus every all-string array joined with spaces so
+// an argv-style command (["rm", "-rf", "/"]) reads like the shell line it runs.
+export function candidates(value) {
+  const out = stringLeaves(value)
+  const joinArrays = (v) => {
+    if (Array.isArray(v)) {
+      if (v.length > 1 && v.every((s) => typeof s === 'string')) out.push(v.join(' '))
+      v.forEach(joinArrays)
+    } else if (v !== null && typeof v === 'object') {
+      Object.values(v).forEach(joinArrays)
+    }
+  }
+  joinArrays(value)
+  return out
+}
+
+// The patterns tagged with `context` that match any text, in catalog order. Oversized input
+// is not evaluated (regex cost is unbounded there) and reports TOO_LARGE_HIT instead.
+export function matchPatterns(patterns, texts, context) {
+  let total = 0
+  for (const t of texts) {
+    total += t.length
+    if (t.length > LIMITS.maxCandidateChars || total > LIMITS.maxTotalChars) return [TOO_LARGE_HIT]
+  }
+  return patterns.filter((p) => p.context.includes(context) && texts.some((t) => p.rx.test(t)))
+}
+
+// One pattern pass after another until the text stops changing. Each pass can expose a new
+// match (password-in-url can swallow an earlier marker), so a single pass is not enough.
+function fixedPoint(text, patterns, hits) {
+  let x = text
+  for (let pass = 0; pass <= LIMITS.maxPasses; pass++) {
+    let y = x
+    for (const p of patterns) {
+      y = y.replace(p.rxg, (m) => {
+        if (m === '') return m
+        hits.add(p)
+        return p.marker
+      })
+    }
+    if (y === x) return x
+    x = y
+  }
+  hits.add(OVERFLOW_HIT)
+  return OVERFLOW_MARKER
+}
+
+// Redacts `s` with `ctx` in front so a secret split across a key and its value, or across
+// argv elements ("Bearer", "<token>"), still matches; then strips the context back off.
+function redactLeaf(s, ctx, patterns, hits) {
+  if (ctx === '') return fixedPoint(s, patterns, hits)
+  const pre = ctx.slice(-LIMITS.maxContextChars) + ' '
+  const y = fixedPoint(pre + s, patterns, hits)
+  if (y === OVERFLOW_MARKER) return y
+  const r = fixedPoint(pre, patterns, new Set())
+  if (y.startsWith(r)) return fixedPoint(y.slice(r.length), patterns, hits)
+  // A match spans the boundary: keep from the marker that covers it. Slicing changes
+  // anchors and boundaries, so also check the standalone leaf after contextual matching.
+  let d = 0
+  while (d < r.length && y[d] === r[d]) d++
+  const i = y.lastIndexOf(MARKER_PREFIX, d)
+  return fixedPoint(i >= 0 ? y.slice(i) : y, patterns, hits)
+}
+
+function walk(v, ctx, patterns, hits) {
+  if (typeof v === 'string') {
+    const local = new Set()
+    const out = redactLeaf(v, ctx, patterns, local)
+    if (out !== v) for (const h of local) hits.add(h)
+    return out
+  }
+  if (Array.isArray(v)) {
+    let prev = null
+    return v.map((el) => {
+      const out = walk(el, typeof prev === 'string' ? prev : ctx, patterns, hits)
+      prev = el
+      return out
+    })
+  }
+  if (v !== null && typeof v === 'object') {
+    const named = typeof v.name === 'string' ? v.name : typeof v.key === 'string' ? v.key : null
+    // fromEntries, not assignment: `out[k] = v` would drop an own "__proto__" key.
+    return Object.fromEntries(
+      Object.entries(v).map(([k, x]) => [
+        walk(k, '', patterns, hits),
+        walk(x, k === 'value' && named !== null ? named : k, patterns, hits),
+      ]),
+    )
+  }
+  return v
+}
+
+// Returns a copy of `value` with every match replaced by `[REDACTED:<id>]`, plus the
+// patterns that fired (catalog order, unique). Keys are redacted too; two keys that redact
+// to the same marker collapse into one, which loses data but never leaks it.
+export function redactValue(value, patterns) {
+  const hits = new Set()
+  const out = walk(value, '', patterns, hits)
+  const order = [...patterns, OVERFLOW_HIT]
+  return { value: out, hits: order.filter((p) => hits.has(p)) }
+}
+
+// Same shape as `value`, every string replaced by `text`. The fallback when redaction
+// itself failed: withhold everything rather than pass anything through.
+export function maskValue(value, text) {
+  if (typeof value === 'string') return text
+  if (Array.isArray(value)) return value.map((v) => maskValue(v, text))
+  if (value !== null && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, maskValue(v, text)]))
+  }
+  return value
+}
+
+// JSON with object keys sorted at every level, so equal values hash equally.
+export function canonicalJson(value) {
+  if (Array.isArray(value)) return '[' + value.map((v) => (v === undefined ? 'null' : canonicalJson(v))).join(',') + ']'
+  if (value !== null && typeof value === 'object') {
+    const keys = Object.keys(value).filter((k) => value[k] !== undefined).sort()
+    return '{' + keys.map((k) => JSON.stringify(k) + ':' + canonicalJson(value[k])).join(',') + '}'
+  }
+  return JSON.stringify(value) ?? 'null'
+}
+
+export async function sha256Hex(text) {
+  const digest = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(text))
+  return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, '0')).join('')
+}

package/scripts/mods/runtime.mjs

@@ -0,0 +1,140 @@
+// Command-hook runtime for the mods under mods/. scripts/generate-mods.mjs copies this file
+// byte-for-byte to mods/<id>/lib/runtime.mjs, so edit it here and run `npm run mods:write`.
+//
+// A mod's bin/hook.mjs hands its handlers to runHook, which reads the harness payload from
+// stdin and renders the handler's decision in that harness's protocol. It writes no files
+// and reads no environment; Claude Code's native runtime never imports it.
+import { readFileSync } from 'node:fs'
+import { isAbsolute, resolve, sep } from 'node:path'
+
+const HARNESSES = new Set(['claude-code', 'kiro', 'codex'])
+const EVENTS = new Set(['PreToolUse', 'PostToolUse', 'SessionStart'])
+const DECISIONS = new Set(['allow', 'deny', 'ask', 'replace', 'context'])
+
+const nodeIo = () => ({
+  argv: process.argv.slice(2),
+  readStdin: () => readFileSync(0, 'utf8'),
+  out: (s) => process.stdout.write(s),
+  err: (s) => process.stderr.write(s),
+})
+
+const message = (err) => (err instanceof Error ? err.message : String(err))
+
+// JSON.parse errors quote the text they failed on, and stdin can carry a tool's input or
+// output: report the failure without echoing any of it.
+function parseStdin(text) {
+  try {
+    return JSON.parse(text)
+  } catch {
+    throw new Error('stdin is not valid JSON')
+  }
+}
+
+export function parseArgs(argv) {
+  const usage = 'usage: hook.mjs --harness <claude-code|kiro|codex> --event <PreToolUse|PostToolUse|SessionStart>'
+  if (argv.length !== 4) throw new Error(usage)
+  const args = {}
+  for (let i = 0; i < 4; i += 2) {
+    const key = { '--harness': 'harness', '--event': 'event' }[argv[i]]
+    if (!key || key in args) throw new Error(usage)
+    args[key] = argv[i + 1]
+  }
+  if (!HARNESSES.has(args.harness)) throw new Error(`unknown harness ${args.harness}; ${usage}`)
+  if (!EVENTS.has(args.event)) throw new Error(`unknown event ${args.event}; ${usage}`)
+  return args
+}
+
+// Where an observer writes `path`. A relative path resolves against the project root when
+// the hook runs from its install location <root>/.<harness dir>/vanguard-mods/<id>/bin/,
+// otherwise against the working directory. Never CLAUDE_PROJECT_DIR: mods read only their
+// own VANGUARD_<ID>_* variables.
+export function projectPath(path, harness, binDir) {
+  if (isAbsolute(path)) return path
+  const parts = resolve(binDir).split(sep)
+  const n = parts.length
+  const dir = { 'claude-code': '.claude', kiro: '.kiro', codex: '.codex' }[harness]
+  const installed = n >= 5 && parts[n - 1] === 'bin' && parts[n - 3] === 'vanguard-mods' && parts[n - 4] === dir
+  return resolve(installed ? parts.slice(0, n - 4).join(sep) || sep : process.cwd(), path)
+}
+
+// Rejects decisions the harness cannot express, so a handler bug surfaces as an error
+// instead of a silently dropped verdict.
+function normalize(d, { harness, event }) {
+  if (d === undefined) return { decision: 'allow', log: [] }
+  if (d === null || typeof d !== 'object' || !DECISIONS.has(d.decision)) {
+    throw new Error(`handler returned an invalid decision: ${JSON.stringify(d)}`)
+  }
+  const log = d.log ?? []
+  if (!Array.isArray(log) || !log.every((l) => typeof l === 'string')) throw new Error('decision log must be a string array')
+  const needs = { deny: 'reason', ask: 'reason', context: 'text' }[d.decision]
+  if (needs && (typeof d[needs] !== 'string' || d[needs] === '')) throw new Error(`${d.decision} needs a ${needs}`)
+  if ((d.decision === 'deny' || d.decision === 'ask') && event !== 'PreToolUse') {
+    throw new Error(`${d.decision} is only valid for PreToolUse, not ${event}`)
+  }
+  if (d.decision === 'replace' && (harness !== 'claude-code' || event !== 'PostToolUse')) {
+    throw new Error(`replace is only valid for claude-code PostToolUse, not ${harness} ${event}`)
+  }
+  return { ...d, log }
+}
+
+function render(d, { harness, event }, io) {
+  const json = (hookSpecificOutput) => io.out(JSON.stringify({ hookSpecificOutput: { hookEventName: event, ...hookSpecificOutput } }) + '\n')
+  for (const line of d.log) io.err(line + '\n')
+  switch (d.decision) {
+    case 'allow':
+      return 0
+    case 'deny':
+    case 'ask':
+      if (harness === 'claude-code') {
+        json({ permissionDecision: d.decision, permissionDecisionReason: d.reason })
+        return 0
+      }
+      // Kiro and Codex have no confirmation step; exit 2 blocks the call in both.
+      io.err(d.decision === 'ask' ? `${d.reason} (confirmation unsupported on ${harness}; denied)\n` : `${d.reason}\n`)
+      return 2
+    case 'replace':
+      json({ updatedToolOutput: d.output })
+      return 0
+    case 'context':
+      if (harness === 'kiro') io.err(d.text + '\n')
+      else json({ additionalContext: d.text })
+      return 0
+  }
+}
+
+// Runs one hook invocation and returns the exit code; bin/hook.mjs sets process.exitCode
+// with it rather than calling process.exit, so buffered stdout is never cut short.
+//
+// - Bad arguments, or an event this mod has no handler for: exit 2, which blocks a
+//   PreToolUse call in every harness (a broken install must not allow silently).
+// - Invalid stdin or a throwing handler: `onError(err, payload, ctx)` supplies the decision
+//   (guards deny, the redactor withholds). Without onError: stderr and exit 1, which is
+//   loud but does not block.
+// - An onError that throws or returns an invalid decision: exit 2.
+export async function runHook({ name, handlers, onError }, io = nodeIo()) {
+  let ctx
+  try {
+    ctx = parseArgs(io.argv)
+    if (!Object.hasOwn(handlers, ctx.event)) throw new Error(`no handler for ${ctx.event}`)
+  } catch (err) {
+    io.err(`${name}: ${message(err)}\n`)
+    return 2
+  }
+  let payload
+  let decision
+  try {
+    payload = parseStdin(io.readStdin())
+    if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) throw new Error('stdin is not a JSON object')
+    decision = normalize(await handlers[ctx.event](payload, ctx), ctx)
+  } catch (err) {
+    io.err(`${name}: ${message(err)}\n`)
+    if (typeof onError !== 'function') return 1
+    try {
+      decision = normalize(await onError(err, payload, ctx), ctx)
+    } catch (err2) {
+      io.err(`${name}: error handler failed: ${message(err2)}\n`)
+      return 2
+    }
+  }
+  return render(decision, ctx, io)
+}

package/scripts/typescript_data/agents/00-typescript-maestro-agent.json

@@ -18,7 +18,7 @@
     "HIGH — Distinguish, before routing: the type model of shared or published code versus a frontend application diff; module resolution and emit versus runtime execution; fleet enforcement policy versus the soundness of one construct; the TypeScript program graph versus the monorepo task graph; publication authority versus dependency intake; contract fidelity versus exploitation; advisory review versus live operation.",
     "HIGH — Detect missing version evidence (compiler version, every relevant `tsconfig.json`, Node version, the exact run command, lint configuration) and refuse-and-ask for the smallest sufficient artifact set rather than guessing. This repository contains no TypeScript program of its own, so no version may ever be assumed from it.",
     "HIGH — Detect production-mutation requests (publish, deploy, migrate, backfill, rotate a credential) and refuse to dispatch: this board is static-review only. Hand such requests to the named human owner together with the rollback and approval requirements. A request to *review* a mutating script is not a mutation request and routes to `typescript-business-critical-automation-governance-agent`.",
-    "HIGH — Route cross-domain work out of the board rather than inventing an agent for it: frontend application and framework work to `frontend-maestro-agent`; dependency intake and lockfile policy to `package-governance-agent`; the monorepo task graph to `monorepo-dx-agent`; cluster, image, and cloud runtime to the kubernetes and provider boards; artifact signing to the sigstore board; organization-wide secrets, identity, and MCP trust policy to the security board and the `mcp/` references.",
+    "HIGH — Route cross-domain work out of the board rather than inventing an agent for it: frontend application and framework work to `frontend-maestro-agent`; dependency intake and lockfile policy to `package-governance-agent`; the monorepo task graph to `monorepo-dx-agent`; cluster, image, and cloud runtime to the kubernetes and provider boards; artifact signing to the sigstore board; organization-wide secrets and identity to the security board; per-server MCP trust review to `agentic-security-review-agent`; organization MCP trust policy to its named human policy owner with the `mcp/` references.",
     "HIGH — Decline non-TypeScript tasks (Python, Java, .NET, Kotlin, PHP, Go) and name the correct board. Do not route them through a TypeScript specialist.",
     "MEDIUM — When two dispatched specialists disagree, return both verdicts with their evidence labels and name the escalation path. Never pick a winner the router has no basis to pick, and never suppress the disagreement.",
     "MEDIUM — Label any reasoning offered as `documentation-based` or `inference`, and never invent a specialist that is not in the routing table.",
@@ -82,7 +82,7 @@
           "`build-graph-performance` owns the TypeScript program graph measured with evidence; `monorepo-dx-agent` on the frontend board owns the task graph and remote caching. A request to speed something up without a measurement is a refuse-and-ask, not a dispatch.",
           "`static-enforcement-policy` owns what the toolchain must prove and at what cost across packages; `type-soundness` owns whether one construct is sound. A question about which flags or lint rules the fleet must run routes to enforcement; a question about whether a specific predicate lies routes to soundness.",
           "`package-publication-integrity` owns publish authority, provenance, and what ships in the tarball; dependency intake, lockfile policy, and install-time scripts belong to `package-governance-agent` on the frontend board.",
-          "`mcp-tool-contract` owns whether a declared MCP tool contract matches its TypeScript handler; transport, hosting, and organization MCP trust policy belong to the security board and the `mcp/` references, and vendor connectors to their own agents.",
+          "`mcp-tool-contract` owns whether a declared MCP tool contract matches its TypeScript handler; whether to trust a specific third-party MCP server belongs to `agentic-security-review-agent`; transport and hosting belong to the `mcp/` references; organization MCP trust policy belongs to its named human policy owner; vendor connectors belong to their own agents.",
           "`engineering-economics` is never dispatched first: it consumes measurements another specialist produced and refuses to originate one. A cost question with no supplied measurements routes to the specialist who can measure it, not to economics."
         ],
         "table": {

package/scripts/typescript_data/agents/11-typescript-mcp-tool-contract-agent.json

@@ -25,7 +25,7 @@
   ],
   "focus_not_owns": [
     "Server hosting, transport selection, and network posture → the `mcp/` references and the security board.",
-    "Organization-wide MCP trust policy → the security board.",
+    "Organization-wide MCP trust policy → its named human policy owner, with the `mcp/` references; per-server trust review → `agentic-security-review-agent`.",
     "Vendor-specific connector governance → `netsuite-ai-connector-mcp-agent` and `nvidia-agentic-ai-platform-review-agent` for their respective connectors.",
     "Application-side input validation unrelated to a declared MCP tool schema → `typescript-runtime-boundary-contract-agent`.",
     "Tool-contract versioning mechanics considered as a general semver/declaration question → `typescript-public-api-and-declaration-governance-agent`."
@@ -55,12 +55,12 @@
   "refusal_triggers": [
     "A request to host, deploy, or run an MCP server — this agent is static review only.",
     "A request about where to host the server or which transport to choose — route to the `mcp/` references and the security board.",
-    "A request about whether to trust a third-party MCP server at all — route to the security board.",
+    "A request about whether to trust a third-party MCP server at all — route to `agentic-security-review-agent`.",
     "The connector is a vendor-specific product with its own agent — route to that agent instead of reviewing it here.",
     "A request for secrets, credentials, or a live connection to an MCP server."
   ],
   "escalation_triggers": [
-    "The question is trust or transport rather than schema fidelity → the `mcp/` references and the security board.",
+    "The question is trust rather than schema fidelity → `agentic-security-review-agent`; transport → the `mcp/` references.",
     "The connector is vendor-specific → `netsuite-ai-connector-mcp-agent` or `nvidia-agentic-ai-platform-review-agent`.",
     "The question is application-side validation unrelated to a declared MCP tool schema → `typescript-runtime-boundary-contract-agent`.",
     "The question is general declaration-surface versioning mechanics → `typescript-public-api-and-declaration-governance-agent`."
@@ -77,7 +77,7 @@
     ],
     "when_not": [
       "The question is where to host the server or which transport to use — route to the `mcp/` references and the security board.",
-      "The question is whether to trust a third-party MCP server — route to the security board.",
+      "The question is whether to trust a third-party MCP server — route to `agentic-security-review-agent`.",
       "The connector is a vendor-specific product with its own agent — route to that agent.",
       "The question is application-side validation unrelated to a declared MCP tool schema — route to `typescript-runtime-boundary-contract-agent`.",
       "The task requires actually running or hosting the server — this skill is static-review only."

package/skills/cross-functional/agentic-board-protocol/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: agentic-board-protocol
+description: Use this skill for any handoff between agentic-board agents and accountable human principals, any decision request about an agentic system's architecture, security posture or automation investment, any stop condition (depth, deadline, budget, blocking missing evidence, mutation intent, instruction bait, routing loop, challenge rounds), any R0-R5 risk-tier crosswalk or candidate framework mapping, and any value case for an automation investment. It defines the versioned handoff envelope, computed stop conditions, the adversarial decision process with designated challengers and HARD gates, and the value-case contract, each checked offline by a deterministic gate. It is a data and process contract that authorizes nothing: it does not authenticate senders, enforce access or store records, and a valid envelope is not proof that an approval happened.
+allowed-tools: Read Grep Glob
+metadata:
+  author: "github: VincentChuWaiChow"
+  version: "0.1.0"
+  updated: "2026-10-30"
+  category: compliance
+  lifecycle: experimental
+---
+
+# Agentic Board Protocol
+
+## Purpose
+
+Give the agentic board one shared, checkable contract for how work moves between its agents and the humans who own the decision: a versioned handoff envelope, computed stop conditions, an adversarial decision process, a risk-tier crosswalk and a value case. The envelope is defined in `schemas/agentic-handoff.schema.json` (shape only); every cross-field rule is checked offline by `tests/agentic-board-suite/agentic_board_rules.py`.
+
+This repository ships role contracts, skills, a JSON Schema and offline gates. It is not an orchestration runtime: nothing here authenticates senders, enforces authorization at runtime or stores audit records. This skill's `allowed-tools` line pre-approves Read, Grep and Glob; it does not restrict other tools. Tool limits come from the board agents' harness adapters: copilot, codex, cursor and claude-code carry read-only grants, while gemini, kiro-ide and kiro-cli carry none here, so their limits are prompt-level only.
+
+## When to use
+
+Use this skill when:
+
+- an agent delegates, returns, challenges or escalates, or a principal records a decision,
+- someone asks for a decision on an agentic system's architecture, security posture or automation investment,
+- a task meets a stop condition, or an objective reads as a mutation request or claims a prior approval,
+- you must express risk as R0 to R5, translate another risk scale, or draft a candidate NIST AI RMF mapping,
+- an automation investment needs a value case, counterfactuals or a promotion decision.
+
+## When not to use
+
+- Single-vendor platform work: use that vendor's agent or maestro (for example aws-agentcore-agent).
+- Runtime authorization, identity enforcement or audit storage: use the deploying runtime, or the python-live governance control-plane pattern (python-live-governance-maestro-agent).
+- Live mutation: use the owning provider's gated live-guard path in `docs/execution-tiers.md`. The board has no execute verb.
+- Certification or compliance conclusions: mappings here are candidate review aids that an accountable owner confirms.
+
+## Core rules
+
+- The envelope is the only inter-agent channel. No free-form side channel, no credentials, no secrets.
+- Agents never decide. Every decision-request is addressed to a principal.
+- Only a principal-sourced decision-record carries approved or rejected, bound to the request by the sha256 of its canonical JSON. Agent messages carry not-required or pending-human-review.
+- There is no execute verb. Authorized actions are read, analyze, recommend, challenge and escalate. R3+ live work escalates to a principal with a route hint.
+- Monotonic attenuation down a chain: tier, classification, materiality flags and prohibitions never shrink; deadline and max_hops never extend; actions and budget limits only narrow.
+- Stop conditions are computed from envelope fields, never the wall clock: depth, deadline, budget, blocking missing evidence, mutation intent, instruction bait, routing loop, challenge rounds.
+- Challengers are designated by decision class. The proposer never challenges its own proposal; independence is procedural, not epistemic.
+- HARD gate: a security challenge with hard_gate true that is open (sustained or unresolved, or stopped whatever outcome it records) forbids recommending approve or conditional-approve. Only a principal decision-record with a risk acceptance reference may approve over it.
+- subject_risk_tier is the canonical R0 to R5 tier of the decision under review. The board's own work is static review. Materiality flags force full-depth review and never remap the tier.
+- Value-case promotion rule: beyond pilot needs measured confidence and a net annual value low above every counterfactual's low. Synthetic records never exceed pilot.
+- Frameworks are candidate mappings, never certification or a claim of compliance.
+- Validate record sets offline with `python3 tests/agentic-board-suite/agentic_board_rules.py <record-set.json>`. A pass proves form and consistency, not truth or that anyone approved anything.
+
+## One owner per concept
+
+| Concept | Owning asset |
+|---|---|
+| Cascading-failure containment; pattern selection (deterministic workflow, single agent, multi-agent); durable execution, state and memory lifecycle | `agentic-system-architecture-review-agent` |
+| Agent identity, delegated authorization, MCP audience binding and token passthrough, A2A security schemes and card signatures; tool, skill and MCP-server provenance; memory and context poisoning | `agentic-security-review-agent` |
+| MCP tool-schema fidelity and protocol version | `typescript-mcp-tool-contract-agent` (existing) |
+| Evaluation design | `llm-ai-pipeline-test-review-agent` (existing) |
+| Model and token unit prices | `finops-ai-economist-agent` (existing) |
+| Value-case challenge | `finance-capital-allocation-advisor-agent` (existing) |
+| Regulatory classification, including the EU AI Act | `legal-regulatory-compliance-agent` (existing) |
+| Business automation ladder rungs (eliminate, redesign, conventional automation), value case, stop conditions | This protocol |
+
+## References
+
+Load these only when needed:
+
+- [Handoff envelope](references/handoff-envelope.md) — message types, field-by-field purpose, principal subjects, what a valid envelope does not prove, a synthetic example and the envelope rules.
+- [Stop conditions](references/stop-conditions.md) — each computed stop, what to declare and do next, why, and the fixture-oracle limits.
+- [Decision record](references/decision-record.md) — the ten-step adversarial process, depth by risk, designated challengers, HARD gate, dissent and the principal's record.
+- [Risk-tier crosswalk](references/risk-tier-crosswalk.md) — canonical R0 to R5, the owner's scale, execution tiers, candidate NIST AI RMF mapping and EU AI Act routing.
+- [Value case](references/value-case.md) — automation ladder, net annual value, unit economics, counterfactuals, promotion and the finance attack checklist.
+
+## Response minimum
+
+Return, at minimum:
+
+- the message type and, for a decision, the decision class, the subject_risk_tier and any materiality flags,
+- the designated challenger and each challenge outcome, or why none was required,
+- open dissent and any HARD gate, carried unchanged to the principal,
+- stop conditions declared, with the route hint for each,
+- for investments, the net annual value range, counterfactuals, confidence and promotion state,
+- evidence labels and missing evidence, and an explicit statement that nothing here approves or executes anything.

package/skills/cross-functional/agentic-board-protocol/metadata.json

@@ -0,0 +1,28 @@
+{
+  "id": "agentic-board-protocol",
+  "name": "Agentic Board Protocol",
+  "type": "skill",
+  "provider": "generic",
+  "harnesses": [
+    "codex",
+    "claude-code",
+    "cursor",
+    "gemini",
+    "kiro",
+    "other"
+  ],
+  "summary": "Shared Layer-3 contract for the agentic board: the versioned handoff envelope (schemas/agentic-handoff.schema.json), computed stop conditions, the adversarial decision process and designated challengers, the R0-R5 risk-tier crosswalk, and the value-case contract — each rule checked deterministically by validate:agentic-board.",
+  "source_type": "original",
+  "official_docs": [
+    "https://airc.nist.gov/airmf-resources/airmf/5-sec-core/",
+    "https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/",
+    "https://www.finops.org/framework/capabilities/unit-economics/",
+    "https://www.finops.org/wg/finops-for-ai-overview/",
+    "https://json-schema.org/draft/2020-12"
+  ],
+  "security_notes": "A data and process contract, not an access-control mechanism: it authorizes nothing, and a valid envelope is not proof that an approval happened. Principals are opaque pseudonymous subjects; envelopes never carry credentials or secrets. Runtime authentication, authorization and append-only storage are the deploying organization's responsibility.",
+  "last_verified": "2026-10-30",
+  "path": "skills/cross-functional/agentic-board-protocol",
+  "author": "github: VincentChuWaiChow",
+  "version": "0.1.0"
+}