@dzhechkov/harness-core 0.3.23 → 0.3.24

package/dist/reconcile.js

@@ -0,0 +1,134 @@
+/**
+ * `dz mcp-scan --reconcile` — static capability reconciliation (Phase 3).
+ *
+ * Joins two things `dz` can read deterministically:
+ *  - the project's GRANT surface (`scanMcp` of `.claude/settings*.json` + `.mcp.json`), and
+ *  - the aggregate DECLARED capabilities of the installed skills (`.claude/skills/<id>/SKILL.md`),
+ * then REPORTS the gaps (under-grant / over-grant) and, optionally, EMITS a
+ * least-privilege advisory policy artifact for a host to consume.
+ *
+ * HONESTY: `dz` is build-time / static. It does NOT run agents and CANNOT block,
+ * time out, or rate-limit a tool call. The HOST (Claude Code enforcing
+ * settings.json allow/deny; or an MCP server consuming a policy.json) is the only
+ * thing that enforces at call time. Verbs here are REPORT / RECONCILE / EMIT /
+ * CANDIDATE — never BLOCK / DENIED / ENFORCED.
+ *
+ * @packageDocumentation
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseDeclaredCapabilities, parseDeclaredLimits } from './capability-vocab.js';
+/** The honesty banner — repeated in --help, the report header, and the artifact $comment. */
+export const RECONCILE_BANNER = 'dz is build-time/static: it REPORTS the grant-vs-declaration gap and may EMIT an advisory policy, ' +
+    'but does NOT block, time out, or rate-limit anything. The HOST (Claude Code settings.json; or an MCP ' +
+    'server consuming policy.json) is the only thing that enforces at call time.';
+const AXES = ['shell', 'network', 'file-write'];
+function readInstalled(skillsDir) {
+    if (!existsSync(skillsDir))
+        return [];
+    let entries;
+    try {
+        entries = readdirSync(skillsDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const e of entries) {
+        if (!e.isDirectory())
+            continue;
+        const md = join(skillsDir, e.name, 'SKILL.md');
+        if (!existsSync(md))
+            continue;
+        let content;
+        try {
+            content = readFileSync(md, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        out.push({ id: e.name, caps: parseDeclaredCapabilities(content), limits: parseDeclaredLimits(content) });
+    }
+    return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+function grantFor(report, axis) {
+    const c = report.capabilities;
+    return axis === 'shell' ? c.shell : axis === 'network' ? c.network : c.fileWrite;
+}
+/**
+ * Statically reconcile a project's GRANT surface against the DECLARED needs of
+ * its installed skills. Pure: same inputs → same report. No execution, no writes.
+ */
+export function reconcileCapabilities(report, skillsDir) {
+    const installed = readInstalled(skillsDir);
+    const axes = [];
+    const findings = [];
+    const allow = {};
+    const grants = {};
+    const declaredNeed = {};
+    const skillsByAxis = {};
+    for (const axis of AXES) {
+        const grant = grantFor(report, axis);
+        const needSkills = installed.filter((s) => s.caps[axis] === true).map((s) => s.id);
+        const need = needSkills.length > 0;
+        const silentCount = installed.filter((s) => s.caps[axis] === undefined).length;
+        axes.push({ axis, grant, need, needSkills, silentCount });
+        grants[axis] = grant;
+        declaredNeed[axis] = need;
+        if (need) {
+            skillsByAxis[axis] = needSkills;
+            allow[axis] = true;
+        }
+        if (need && !grant) {
+            findings.push({
+                id: `MS-UNDERGRANT-${axis.toUpperCase()}`,
+                kind: 'under-grant',
+                severity: 'medium',
+                axis,
+                detail: `${needSkills.length} installed skill(s) declare needing ${axis}, but the grant surface does not permit it — the host will starve them at runtime. Add the grant or remove the skill(s).`,
+                skills: needSkills,
+            });
+        }
+        else if (grant && !need) {
+            // over-grant is ALWAYS advisory; downgrade to info when any skill is silent
+            // (it may genuinely need the grant but didn't declare), or when there are
+            // no installed skills at all.
+            const downgrade = silentCount > 0 || installed.length === 0;
+            findings.push({
+                id: `MS-OVERGRANT-${axis.toUpperCase()}`,
+                kind: 'over-grant',
+                severity: downgrade ? 'info' : 'low',
+                axis,
+                detail: `The project permits ${axis} but no installed skill declares needing it${silentCount > 0 ? ` (${silentCount} skill(s) silent on ${axis})` : ''} — least-privilege CANDIDATE to revoke; may be for the operator or a non-skill MCP server.`,
+                skills: [],
+            });
+        }
+    }
+    // limits roll-up (tightest values) — INERT, never a gate
+    const withLimits = installed.filter((s) => Object.keys(s.limits).length > 0);
+    let limits = null;
+    if (withLimits.length > 0) {
+        const tts = withLimits.map((s) => s.limits.toolTimeoutMs).filter((n) => typeof n === 'number');
+        const mcs = withLimits.map((s) => s.limits.maxToolCallsPerTurn).filter((n) => typeof n === 'number');
+        const ras = withLimits.some((s) => s.limits.requireApprovalForDangerous === true);
+        limits = {
+            declaredBy: withLimits.length,
+            ...(tts.length > 0 ? { toolTimeoutMs: Math.min(...tts) } : {}),
+            ...(mcs.length > 0 ? { maxToolCallsPerTurn: Math.min(...mcs) } : {}),
+            ...(ras ? { requireApprovalForDangerous: true } : {}),
+        };
+    }
+    const policy = {
+        $comment: `ADVISORY. ${RECONCILE_BANNER} A host MUST consume this; dz does not.`,
+        version: 1,
+        defaultDeny: true,
+        allow,
+        ...(limits ? { limits } : {}),
+        derivedFrom: { grants, declaredNeed, skillsByAxis },
+    };
+    // stable ordering: under-grant (medium) first, then over-grant
+    const order = { medium: 0, low: 1, info: 2 };
+    findings.sort((a, b) => order[a.severity] - order[b.severity] || a.axis.localeCompare(b.axis));
+    return { skillsDir, installedCount: installed.length, axes, findings, limits, policy };
+}
+//# sourceMappingURL=reconcile.js.map

package/dist/reconcile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.js","sourceRoot":"","sources":["../src/reconcile.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-core",
-  "version": "0.3.23",
+  "version": "0.3.24",
   "description": "Shared harness logic - skill loading, additive apply, and the init/sync/verify/doctor operations.",
   "type": "module",
   "license": "MIT",

package/src/benchmark.ts

@@ -11,6 +11,7 @@
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 
+import { detectScriptCapabilities, parseDeclaredCapabilities } from './capability-vocab.js';
 import { estimateSkillCost, type CostEstimate } from './cost-scoring.js';
 
 /** A single benchmark check result. */
@@ -19,6 +20,12 @@ export interface BenchmarkCheck {
   readonly name: string;
   readonly passed: boolean;
   readonly detail?: string | undefined;
+  /**
+   * When true this check is informational ONLY — it is excluded from the
+   * pass-rate / grade math (so it can ship without regressing existing grades).
+   * Surfaced as a warning in output. Used by S16 (capability-declaration nudge).
+   */
+  readonly advisory?: boolean;
 }
 
 /** Score for a single skill benchmark. */
@@ -160,11 +167,52 @@ export function benchmarkSkill(skillDir: string, skillId: string): BenchmarkScor
     || /\*\*\s*PROHIBITED/i.test(content);
   checks.push({ id: 'S14', name: 'anti-patterns or self-check', passed: hasAntiPatterns });
 
-  const passed = checks.filter((c) => c.passed).length;
-  const passRate = Math.round((passed / checks.length) * 100);
+  // S15: capability declaration matches usage (advisory, contradiction-only).
+  // Phase 1 auto-detects network + shell from scripts/ only (never SKILL.md prose).
+  // PASS unless a declared `capabilities.<cap>: false` is contradicted by detected
+  // usage. Absent block, or under-declaration (uses it, declares nothing), PASS —
+  // so the ~all skills that declare nothing today stay green.
+  const declaredCaps = parseDeclaredCapabilities(content);
+  const detectedCaps = detectScriptCapabilities(skillDir);
+  const contradictions: string[] = [];
+  if (detectedCaps.network && declaredCaps.network === false) contradictions.push('network');
+  if (detectedCaps.shell && declaredCaps.shell === false) contradictions.push('shell');
+  checks.push({
+    id: 'S15',
+    name: 'capability declaration matches usage',
+    passed: contradictions.length === 0,
+    detail:
+      contradictions.length > 0
+        ? `scripts use ${contradictions.join(' + ')} but capabilities declare it false`
+        : undefined,
+  });
+
+  // S16: side-effecting skills should declare their capabilities (ADVISORY — not
+  // graded). Warns when scripts use network/shell but the capability is not
+  // declared at all (neither true nor false). The adoption nudge for the manifest;
+  // excluded from the grade so it never regresses an existing skill.
+  const undeclaredUsed: string[] = [];
+  if (detectedCaps.network && declaredCaps.network === undefined) undeclaredUsed.push('network');
+  if (detectedCaps.shell && declaredCaps.shell === undefined) undeclaredUsed.push('shell');
+  checks.push({
+    id: 'S16',
+    name: 'side-effects declared (advisory)',
+    passed: undeclaredUsed.length === 0,
+    advisory: true,
+    detail:
+      undeclaredUsed.length > 0
+        ? `scripts use ${undeclaredUsed.join(' + ')} — add a capabilities: block declaring it`
+        : undefined,
+  });
+
+  // grade math is over GRADED checks only — advisory checks (S16) are excluded
+  // so they ship without changing any existing grade.
+  const graded = checks.filter((c) => !c.advisory);
+  const passed = graded.filter((c) => c.passed).length;
+  const passRate = graded.length > 0 ? Math.round((passed / graded.length) * 100) : 0;
 
   return {
-    skillId, skillDir, checks, passed, total: checks.length,
+    skillId, skillDir, checks, passed, total: graded.length,
     passRate, grade: gradeFromRate(passRate), cost: estimateSkillCost(content),
   };
 }
@@ -190,8 +238,12 @@ export function compareSkills(
   const skillA = benchmarkSkill(skillADir, skillAId);
   const skillB = benchmarkSkill(skillBDir, skillBId);
 
+  // deltaChecks is GRADED-ONLY — advisory checks (e.g. S16) never touch the grade,
+  // so surfacing them in the A/B diff would misrepresent an adoption nudge as a
+  // quality difference. Mirrors the graded filter in the grade math above.
   const deltaChecks: { id: string; aPass: boolean; bPass: boolean }[] = [];
   for (const checkA of skillA.checks) {
+    if (checkA.advisory) continue;
     const checkB = skillB.checks.find((c) => c.id === checkA.id);
     if (checkB && checkA.passed !== checkB.passed) {
       deltaChecks.push({ id: checkA.id, aPass: checkA.passed, bPass: checkB.passed });

package/src/capability-vocab.ts

@@ -0,0 +1,307 @@
+/**
+ * Shared capability vocabulary — the single source of truth for how the harness
+ * classifies agent capabilities, used by BOTH `mcp-scan` (project settings audit)
+ * and `benchmark` (per-skill S15 capability-declaration check).
+ *
+ * Keeping these regexes/sets here (rather than private to mcp-scan) guarantees the
+ * project-level scan and the per-skill manifest speak ONE diffable vocabulary.
+ *
+ * @packageDocumentation
+ */
+
+import { existsSync, lstatSync, readdirSync, readFileSync } from 'node:fs';
+import { extname, join } from 'node:path';
+
+/** The capability classes the harness recognises. */
+export type CapabilityClass = 'shell' | 'network' | 'file-write' | 'secrets' | 'mcp' | 'policy';
+
+// --- Claude permission-grammar tool sets (lowercase for case-insensitive tests) ---
+export const SHELL_TOOLS = new Set(['bash', 'powershell', 'shell']);
+export const NETWORK_TOOLS = new Set(['webfetch', 'websearch']);
+export const WRITE_TOOLS = new Set(['write', 'edit', 'multiedit', 'notebookedit']);
+export const READ_TOOLS = new Set(['read']);
+/** Recognised + benign tools (so they aren't flagged "unknown"). */
+export const SAFE_TOOLS = new Set([
+  'glob', 'grep', 'task', 'bashoutput', 'killbash', 'todowrite',
+  'notebookread', 'slashcommand', 'exitplanmode', 'ls',
+]);
+
+/** Interpreter binaries that can run arbitrary code. */
+export const INTERPRETER_RE = /^(bash|sh|zsh|fish|node|nodejs|python\d?|deno|ruby|perl|php)$/i;
+/** Package runners that fetch + execute arbitrary remote code. */
+export const PACKAGE_RUNNERS = new Set(['npx', 'npm', 'pnpm', 'yarn', 'uvx', 'uv', 'pipx', 'bunx', 'bun', 'deno']);
+/** Inline-code argument flags. */
+export const INLINE_CODE_ARGS = new Set(['-c', '-e', '-eval', '--eval', '-p']);
+
+/** Binaries that imply outbound network. */
+export const SHELL_NET_RE = /\b(curl|wget|nc|ncat|netcat|ssh|scp|sftp|telnet|ftp)\b/i;
+/** Binaries / redirects that imply filesystem writes. */
+export const SHELL_WRITE_RE = /\b(rm|mv|cp|tee|dd|truncate|chmod|chown|mkfifo)\b|>>?/;
+/** Concrete secret-file location patterns (not bare "secret"/"credential" substrings). */
+export const SECRET_FILE_RE =
+  /\.env\b|\.env\.|id_rsa|id_ed25519|id_ecdsa|\.ssh\/|\.aws\/|\.config\/gcloud|application_default_credentials|\.npmrc|\.netrc|\.git-credentials|\.kube\/config|\.pem\b|\.p12\b|\.pfx\b|\.key\b/i;
+
+export const MAX_FILE_BYTES = 5 * 1024 * 1024;
+
+// ---------------------------------------------------------------------------
+// permission-grammar helpers
+// ---------------------------------------------------------------------------
+
+/** Parse a Claude permission grant like `Bash(git *)` → `{ tool, arg }`. Never throws. */
+export function parseGrant(grant: unknown): { tool: string; arg: string | null } {
+  if (typeof grant !== 'string') return { tool: '', arg: null };
+  const s = grant.trim();
+  const m = /^([A-Za-z_][\w-]*)\s*\((.*)\)\s*$/.exec(s);
+  if (m) return { tool: m[1] ?? s, arg: m[2] ?? null };
+  const id = /^([A-Za-z_][\w-]*|\*)/.exec(s);
+  return { tool: id ? (id[1] ?? s) : s, arg: null };
+}
+
+export function isWildcard(arg: string | null): boolean {
+  return arg === null || arg.trim() === '' || arg.includes('*');
+}
+
+export function toolKind(tool: string): CapabilityClass | 'read' | 'safe' | 'unknown' {
+  const t = tool.toLowerCase();
+  if (t === '*') return 'shell';
+  if (SHELL_TOOLS.has(t)) return 'shell';
+  if (NETWORK_TOOLS.has(t)) return 'network';
+  if (WRITE_TOOLS.has(t)) return 'file-write';
+  if (READ_TOOLS.has(t)) return 'read';
+  if (t.startsWith('mcp__')) return 'mcp';
+  if (SAFE_TOOLS.has(t)) return 'safe';
+  return 'unknown';
+}
+
+// ---------------------------------------------------------------------------
+// script capability detection (for the per-skill S15 check)
+// ---------------------------------------------------------------------------
+
+/** Self-declared capability surface parsed from a skill's `capabilities:` block. */
+export interface DeclaredCapabilities {
+  network?: boolean;
+  shell?: boolean;
+  'file-write'?: boolean;
+  dangerous?: boolean;
+}
+
+/** Capabilities statically detected in a skill's `scripts/`. P1: network + shell only. */
+export interface DetectedCapabilities {
+  network: boolean;
+  shell: boolean;
+}
+
+/** Strip heredoc bodies (`<<EOF … EOF`, incl. `<<-'EOF'`) — unquoted free text. */
+function stripHeredocs(text: string): string {
+  return text.replace(/<<-?\s*(['"]?)(\w+)\1[\s\S]*?\n[ \t]*\2\b/g, ' ');
+}
+
+/** Strip comments + heredocs (keeps string literals — curl inside an arg string is real). */
+export function stripComments(text: string): string {
+  return stripHeredocs(text)
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')        // /* paired block */
+    .replace(/\/\*[\s\S]*$/g, ' ')            // unterminated block → EOF
+    .replace(/(^|[^:])\/\/[^\n]*/g, '$1 ')    // // line (not http://)
+    .replace(/(^|\s)#[^\n]*/g, '$1 ');        // # shell/py
+}
+
+/**
+ * Strip comments, heredocs AND quoted string literals. Used for the IDENTIFIER
+ * pass (fetch/axios/execSync/http modules) where the token is real code, never a
+ * quoted search pattern — this is what kills FPs like `grep "writeFileSync"`.
+ */
+export function stripCodeNoise(text: string): string {
+  return stripComments(text)
+    .replace(/'(?:[^'\\]|\\.)*'/g, ' ')
+    .replace(/"(?:[^"\\]|\\.)*"/g, ' ')
+    .replace(/`(?:[^`\\]|\\.)*`/g, ' ');
+}
+
+const SCRIPT_EXTS = new Set(['.sh', '.bash', '.zsh', '.js', '.mjs', '.cjs', '.ts', '.py', '.rb', '.pl', '.php']);
+
+// command position = line start, after a shell separator, after `sudo`/`do`/`then`,
+// inside `$( )`, or right after an opening quote (covers subprocess.run("curl …")).
+const CMD_PREFIX = `(?:^|[;&|(\\n]|&&|\\|\\||\\$\\(|\\bsudo\\s+|\\bthen\\s+|\\bdo\\s+|["'\`])\\s*`;
+// the next token must look like an argument/subcommand (a word/path/flag), not an
+// operator — so `uv = coord` / `ssh = cfg` (assignments) and `grep "curl"` don't match.
+const ARG_FOLLOWS = `(?=\\s+[\\w./~-])`;
+// a network binary AT command position, followed by an argument.
+const CMD_NET_RE = new RegExp(`${CMD_PREFIX}(curl|wget|nc|ncat|netcat|ssh|scp|sftp|telnet|ftp)\\b${ARG_FOLLOWS}`, 'i');
+// a package-runner / interpreter AT command position, followed by an argument → shell.
+const CMD_SHELL_RE = new RegExp(
+  `${CMD_PREFIX}(${[...PACKAGE_RUNNERS].join('|')}|python\\d?|node|nodejs|bash|sh|zsh|ruby|perl|php)\\b${ARG_FOLLOWS}`,
+  'i',
+);
+// network via library identifiers (matched on noise-stripped code — never in a quote).
+const NETWORK_CALL_RE =
+  /\bfetch\s*\(|\baxios\b|WebFetch\s*\(|\bWebSearch\b|\brequests\.|\burllib3?\b|\bhttpx\b|\baiohttp\b|\bparamiko\b|\bsmtplib\b|\bftplib\b|\bhttp\.client\b|\bsocket\.(?:socket|create_connection)\s*\(|\b(?:https?|net|dgram|tls|dns)\.(?:get|request|createConnection|connect|createSocket|resolve\w*)\s*\(|\bnew\s+WebSocket\b|(?:require\(|from\s+)['"](?:node:)?(?:http|https|net|dgram|tls|ws|node-fetch|got|undici)['"]/;
+// shell exec via library identifiers (language-agnostic).
+const EXEC_CALL_RE =
+  /child_process|execSync|execFileSync|spawnSync|\bspawn\s*\(|\bexec(?:File)?\s*\(|\bsubprocess\b|\bos\.system\b|\bos\.popen\b|\bPopen\b|\bOpen3\b|\bcommands\.get(?:status)?output\b|%x[([{]|(?:^|[^.\w])system\s*\(/m;
+
+function isProbablyBinary(buf: string): boolean {
+  return /[\x00-\x08\x0E-\x1F]/.test(buf);
+}
+
+function collectScriptFiles(dir: string, depth: number, acc: string[]): void {
+  if (depth > 3 || acc.length >= 200) return;
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const name of entries) {
+    if (acc.length >= 200) return;
+    const abs = join(dir, name);
+    let st;
+    try {
+      st = lstatSync(abs);
+    } catch {
+      continue;
+    }
+    if (st.isSymbolicLink()) continue;
+    if (st.isDirectory()) {
+      collectScriptFiles(abs, depth + 1, acc);
+    } else if (st.isFile() && st.size <= 256 * 1024) {
+      acc.push(abs);
+    }
+  }
+}
+
+/**
+ * Statically detect network + shell capability usage in a skill's `scripts/`.
+ * Reads only `scripts/` (never SKILL.md prose), recursively (bounded), skipping
+ * binary / symlinked / oversized files. Deterministic, no execution.
+ *
+ * Known scope (Phase 1, by design — documented, not bugs): file-write and
+ * `dangerous` are not auto-detected; dynamically-assembled commands
+ * (`$RUNNER install`, eval'd strings) and indirected calls evade static regexes.
+ * S15 is a best-effort self-consistency LINT, not a sandbox.
+ */
+export function detectScriptCapabilities(skillDir: string): DetectedCapabilities {
+  const out: DetectedCapabilities = { network: false, shell: false };
+  const scriptsDir = join(skillDir, 'scripts');
+  if (!existsSync(scriptsDir)) return out;
+
+  const files: string[] = [];
+  collectScriptFiles(scriptsDir, 0, files);
+
+  for (const abs of files) {
+    const ext = extname(abs).toLowerCase();
+    let raw: string;
+    try {
+      raw = readFileSync(abs, 'utf-8');
+    } catch {
+      continue;
+    }
+    if (isProbablyBinary(raw)) continue;
+
+    const hasShebang = /^#!/.test(raw);
+    const isShellExt = ext === '.sh' || ext === '.bash' || ext === '.zsh';
+    // shell scripts (by extension, or extensionless with a shell shebang) ARE shell usage
+    if (isShellExt || (ext === '' && /^#![^\n]*\b(bash|sh|zsh)\b/.test(raw))) out.shell = true;
+    if (!SCRIPT_EXTS.has(ext) && !hasShebang) continue;
+
+    const commentless = stripComments(raw); // strings kept → curl in an arg string survives
+    const noiseless = stripCodeNoise(raw); // strings gone → identifier pass
+
+    if (CMD_NET_RE.test(commentless) || NETWORK_CALL_RE.test(noiseless)) out.network = true;
+    if (out.shell || CMD_SHELL_RE.test(commentless) || EXEC_CALL_RE.test(noiseless)) out.shell = true;
+  }
+  return out;
+}
+
+/**
+ * Parse the `capabilities:` block from a SKILL.md document. Reads only the
+ * frontmatter region (the first `---`-fenced block) and only DIRECT children of
+ * `capabilities:` (so a nested `limits.network` is never mistaken for a top-level
+ * declaration). Absent block or absent key → `undefined` ("not asserted").
+ */
+export function parseDeclaredCapabilities(skillMd: string): DeclaredCapabilities {
+  const fmMatch = /^---\r?\n([\s\S]*?)\r?\n---/.exec(skillMd);
+  const fm = fmMatch ? (fmMatch[1] ?? '') : '';
+  const block = /^capabilities:[ \t]*\r?\n((?:[ \t]+.*\r?\n?)*)/m.exec(fm);
+  if (!block) return {};
+  const lines = (block[1] ?? '').split('\n');
+  const firstReal = lines.find((l) => l.trim() !== '');
+  if (!firstReal) return {};
+  const childIndent = (/^[ \t]*/.exec(firstReal)?.[0]) ?? '';
+
+  const out: DeclaredCapabilities = {};
+  const read = (key: string): boolean | undefined => {
+    const re = new RegExp(`^${childIndent}${key.replace('-', '\\-')}:[ \\t]*(true|false)\\b`);
+    for (const l of lines) {
+      const m = re.exec(l);
+      if (m) return m[1] === 'true';
+    }
+    return undefined;
+  };
+  const network = read('network');
+  const shell = read('shell');
+  const fileWrite = read('file-write');
+  const dangerous = read('dangerous');
+  if (network !== undefined) out.network = network;
+  if (shell !== undefined) out.shell = shell;
+  if (fileWrite !== undefined) out['file-write'] = fileWrite;
+  if (dangerous !== undefined) out.dangerous = dangerous;
+  return out;
+}
+
+/** Declared runtime limits (inert today — no enforcement home in Claude Code settings). */
+export interface DeclaredLimits {
+  toolTimeoutMs?: number;
+  maxToolCallsPerTurn?: number;
+  requireApprovalForDangerous?: boolean;
+}
+
+/**
+ * Parse the nested `capabilities.limits` block from a SKILL.md frontmatter.
+ * Fail-open: a malformed/absent block yields `{}` (never throws). These values
+ * are INERT — Claude Code settings.json has no timeout/rate-limit field; they are
+ * only machine-actionable in an MCP host's policy.json.
+ */
+export function parseDeclaredLimits(skillMd: string): DeclaredLimits {
+  const fmMatch = /^---\r?\n([\s\S]*?)\r?\n---/.exec(skillMd);
+  const fm = fmMatch ? (fmMatch[1] ?? '') : '';
+  // Anchor under capabilities: — only a `limits:` that is a DIRECT child of
+  // capabilities counts (not some unrelated indented `limits:` elsewhere).
+  const capBlock = /^capabilities:[ \t]*\r?\n((?:[ \t]+.*\r?\n?)*)/m.exec(fm);
+  if (!capBlock) return {};
+  const capLines = (capBlock[1] ?? '').split('\n');
+  const firstReal = capLines.find((l) => l.trim() !== '');
+  if (!firstReal) return {};
+  const childIndent = (/^[ \t]*/.exec(firstReal)?.[0]) ?? '';
+
+  // find the `limits:` line at the capabilities-child indent, then capture only
+  // its strictly-deeper-indented children.
+  const limitsIdx = capLines.findIndex((l) => new RegExp(`^${childIndent}limits:[ \\t]*$`).test(l));
+  if (limitsIdx === -1) return {};
+  const body: string[] = [];
+  for (let i = limitsIdx + 1; i < capLines.length; i++) {
+    const l = capLines[i] ?? '';
+    if (l.trim() === '') continue;
+    const indent = (/^[ \t]*/.exec(l)?.[0]) ?? '';
+    if (indent.length <= childIndent.length) break; // back to a sibling → end of limits
+    body.push(l);
+  }
+  const text = body.join('\n');
+  const out: DeclaredLimits = {};
+  const num = (key: string): number | undefined => {
+    const m = new RegExp(`^[ \\t]+${key}:[ \\t]*(\\d+)\\b`, 'm').exec(text);
+    if (!m) return undefined;
+    const n = Number(m[1]);
+    return Number.isSafeInteger(n) && n >= 0 ? n : undefined; // fail-open on absurd values
+  };
+  const bool = (key: string): boolean | undefined => {
+    const m = new RegExp(`^[ \\t]+${key}:[ \\t]*(true|false)\\b`, 'm').exec(text);
+    return m ? m[1] === 'true' : undefined;
+  };
+  const tt = num('toolTimeoutMs');
+  const mc = num('maxToolCallsPerTurn');
+  const ra = bool('requireApprovalForDangerous');
+  if (tt !== undefined) out.toolTimeoutMs = tt;
+  if (mc !== undefined) out.maxToolCallsPerTurn = mc;
+  if (ra !== undefined) out.requireApprovalForDangerous = ra;
+  return out;
+}

package/src/index.ts

@@ -56,5 +56,30 @@ export type {
 } from './cost-scoring.js';
 export { importEcc } from './import-ecc.js';
 export type { ImportEccReport, ImportEccOptions, ImportedSkill } from './import-ecc.js';
+export { scanMcp, parseGrant } from './mcp-scan.js';
+export {
+  detectScriptCapabilities,
+  parseDeclaredCapabilities,
+  parseDeclaredLimits,
+  stripCodeNoise,
+  toolKind,
+} from './capability-vocab.js';
+export type { CapabilityClass, DeclaredCapabilities, DetectedCapabilities, DeclaredLimits } from './capability-vocab.js';
+export { reconcileCapabilities, RECONCILE_BANNER } from './reconcile.js';
+export type {
+  ReconcileReport,
+  ReconcileFinding,
+  ReconcileAxis,
+  AxisState,
+  LimitsRollup,
+  PolicyArtifact,
+} from './reconcile.js';
+export type {
+  McpFinding,
+  McpScanReport,
+  McpVerdict,
+  McpSeverity,
+  McpCapability,
+} from './mcp-scan.js';
 export type { RegistryEntry, Registry } from './registry.js';
 export type { BenchmarkCheck, BenchmarkScore, BenchmarkReport, CompareResult } from './benchmark.js';