agent-gov-core 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,56 @@
 
 All notable changes to this project will be documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Under v1.0, minor versions may include breaking changes — see [CONTRIBUTING.md](./CONTRIBUTING.md#backwards-compatibility) for the rules.
 
+## [0.7.0] — 2026-05-22
+
+**The pre-v1.0 consolidation release.** Bundles everything that was queued for v0.6.0 (report envelope + merge layer + OTel GenAI interop) plus two universal detectors promoted from consumer repos: `matchSecret` (from PolicyMesh) and `applyExceptions` (unifying PolicyMesh's `subject` and TaskBound's `allow_paths` shapes).
+
+No breaking changes to the v0.5.0 surface — additive minor bump. One npm publish covers all of it.
+
+This is the last release before v1.0 freeze. The remaining gate is consumer-side: at least one tool wiring `generateWorkflowSummary` end-to-end, then v1.0 with semver guarantees on the contract pinned by the golden tests.
+
+### Added — Report envelope
+- `Report` interface — canonical multi-tool envelope with `schemaVersion`, `tool`, `rating`, optional `toolVersion`/`runId`/`conversationId`/`baseRef`/`headRef`, `findings: Finding[]`, and tool-specific extension `data`.
+- `Report.conversationId` (optional) — agent session / PR review / thread identifier. Matches OpenTelemetry's `gen_ai.conversation.id` semantic convention so a consumer can pass the same string into both governance reports and OTel traces, then correlate them downstream.
+- `REPORT_SCHEMA_VERSION` const (`'1.0'`).
+- `schemas/report.schema.json` — JSON schema for the envelope, exposed via the package's `./schemas/report.schema.json` export.
+- `createReport({tool, findings, ...})` — convenience constructor; sets `schemaVersion` and computes `rating` from max finding severity (unless overridden).
+- `maxSeverity(findings)` — helper that returns `'none' | Severity` across a finding list.
+- `validateReport(value)` — strict envelope check that also validates each contained finding and flags cross-field inconsistencies (e.g. rating below implied max).
+
+### Added — Merge layer
+- `mergeFindings(reports, opts?)` — combine N tool reports into one normalized `MergedReport`:
+  - Deduplicates by `Finding.fingerprint`. Default policy: keep highest severity; `duplicatePolicy: 'first'` keeps the first occurrence.
+  - Optional severity `threshold` drops findings below the requested level into a counted `droppedBelowThreshold` field.
+  - Aggregates rating from the surviving findings, not source ratings — so threshold filtering correctly demotes the merged rating.
+  - Sorts findings by severity, highest first.
+  - Propagates `conversationId` to the merged report iff every source agrees. Cross-conversation mixing leaves the field intentionally empty so a meta-reviewer can detect misuse.
+  - **Never silently drops bad data**: malformed envelopes go to `invalidReports[]`, individual malformed findings go to `invalidFindings[]`. A single bad finding in a tool's report doesn't poison the rest of that report.
+- `MergeOptions`, `MergeSource` (with optional `conversationId`), `MergedReport` (with optional `conversationId`), `InvalidReport`, `InvalidFinding` types.
+
+### Added — OpenTelemetry GenAI interop
+- `docs/INTEROP-OTEL.md` — explicit cross-walk between `agent-gov-core` types and OTel's [`gen_ai.*` semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/). Maps `Report.conversationId` ↔ `gen_ai.conversation.id`, documents why we adopt one bridge field and not the whole namespace, and shows a paired-emission pattern for orgs running OTel-instrumented agents alongside governance tools.
+
+### Added — Hardcoded secret detection (promoted from PolicyMesh)
+- `matchSecret(value, options?)` — scans a string for provider-prefix credentials and returns `{ provider }` (never the literal credential). Built-in patterns: Anthropic, OpenAI (sk- + sk-proj-), GitHub (PAT + classic), Slack, AWS, Google, GitLab, npm, Docker, Stripe, plus a length-restricted hex token pattern gated to env/header context to avoid commit-SHA false positives.
+- `MatchSecretOptions.envOrHeaderContext` — opt-in flag for the hex token pattern.
+- `SECRET_PATTERNS` — exported read-only constant table; golden-tested so additions are non-breaking but removals require a major bump.
+- `SecretMatch` type.
+- `env:VAR` references are never flagged (Codex notation for env-var lookups).
+
+### Added — Exception baselines (promoted + unified from PolicyMesh + TaskBound)
+- `applyExceptions(findings, exceptions, now?)` — suppress (or downgrade-on-expiry) findings matched by `kind` + optional `salientKey` + optional `pathPrefix`. PolicyMesh's `.policymesh-exceptions.json` shape and TaskBound's `.taskbound.yml` `ignore_kinds`/`allow_paths` shape both map cleanly onto this unified primitive.
+- Expired exceptions don't silently drop — they re-surface with severity downgraded to `'low'` and an `[EXPIRED WHITELIST]` message prefix so stale baselines stay visible. Reason text propagates to `finding.data.exceptionReason`.
+- `validateException(value)` — runtime check for well-formed exception entries.
+- `Exception`, `ApplyExceptionsResult` types.
+
+### Tests
+- 57 new cases. 220 total (up from 163). Breakdown:
+  - Report: 17 (schemaVersion pinning, rating derivation, explicit-rating override, validateReport accepting/rejecting envelope-level errors, finding-tool consistency, unknown property rejection, downgrade-allowed/upgrade-flagged rating consistency, conversationId passthrough + type check).
+  - Merge: 14 (empty input, cross-tool combine, fingerprint dedup with `highest_severity` and `first` policies, salientKey-disambiguated findings stay separate, threshold filtering, malformed report → invalidReports, malformed finding → invalidFindings, severity-sorted output, aggregate-rating-reflects-survivors, source provenance, conversationId agreement/disagreement/partial-coverage propagation).
+  - Secrets: 11 (each provider class detected, env: refs never flagged, empty/short input ignored, hex token gated to env/header context, non-hex 40-char string rejected, never-leak-literal contract, golden-pinned `SECRET_PATTERNS` provider set).
+  - Exceptions: 15 (empty input identity, suppress by kind/salientKey/pathPrefix, perpetual-active when no expires, expired surfacing with downgrade/prefix/reason, non-matching kind/salientKey passthrough, pathPrefix without location.file safely non-matches, malformed expires treated as never-expires, future expires stays active, validateException accept/reject paths).
+
 ## [0.5.0] — 2026-05-22
 
 Three additive features completing the queue from Gemini's third inspection round, plus five correctness fixes from a deep code-level inspection done before publish. No breaking changes — existing exports and call signatures unchanged.

package/README.md

@@ -33,7 +33,7 @@ const finding = createFinding({
 // finding.fingerprint === '<stable 16-char hex>'
 ```
 
-`createFinding` calls `kind()` to build the namespaced kind, validates the slug shape, and computes a stable `fingerprintFinding(finding)` hash of `(kind, file, line, column)`.
+`createFinding` calls `kind()` to build the namespaced kind, validates the slug shape, and computes a stable `fingerprintFinding(finding)` hash of `(kind, file, line, column, salientKey?)`. Pass `salientKey` when two distinct findings can legitimately fire at the same `(kind, file, line)` site (e.g. two suspicious imports on one line) so the meta-reviewer doesn't collapse them into one.
 
 ### Validate findings from disk
 
@@ -54,6 +54,28 @@ for (const f of report.findings) {
 }
 ```
 
+### Merge reports across tools (the meta-reviewer pipeline)
+
+A cross-tool meta-reviewer ingests JSON reports from N tools, dedupes findings by fingerprint, applies a severity threshold, and rolls up an aggregate rating. The library ships this as `mergeFindings`:
+
+```ts
+import { mergeFindings } from 'agent-gov-core';
+import { readFileSync } from 'node:fs';
+
+const reports = [
+  JSON.parse(readFileSync('scopetrail-report.json', 'utf8')),
+  JSON.parse(readFileSync('policymesh-report.json', 'utf8')),
+  JSON.parse(readFileSync('capabilityecho-report.json', 'utf8')),
+];
+
+const merged = mergeFindings(reports, { threshold: 'medium' });
+console.log(`Merged rating: ${merged.rating}`);
+console.log(`${merged.findings.length} unique findings across ${merged.sources.length} tools`);
+console.log(`Dropped ${merged.droppedBelowThreshold} below threshold; collapsed ${merged.duplicateCollapsed} duplicates`);
+```
+
+Malformed reports go to `merged.invalidReports`; malformed individual findings go to `merged.invalidFindings` — neither is silently dropped, so a meta-reviewer can surface what went wrong.
+
 ### Schema is the contract
 
 The JSON schema at [`schemas/finding.schema.json`](./schemas/finding.schema.json) is the single source of truth for the dotted-kind shape, the closed `tool` enum, and the location fields. Any tool emitting unprefixed kinds will fail validation. See [CONTRIBUTING.md](./CONTRIBUTING.md#the-finding-schema-is-the-contract) for how the TypeScript types and JSON schema are kept in lockstep.
@@ -69,6 +91,23 @@ The JSON schema at [`schemas/finding.schema.json`](./schemas/finding.schema.json
 - `fingerprintFinding(finding)` — 16-character hex hash of `(kind, file, line, column, salientKey?)`. Stable across runs and message rewordings, so a meta-reviewer can dedupe. Pass `salientKey` (since v0.4.3) when multiple distinct findings can fire at the same site
 - `validateFinding(value)` — runtime check against `schemas/finding.schema.json`, returns `{ ok, errors[] }`
 
+### Hardcoded secret detection (since v0.7.0)
+- `matchSecret(value, options?)` — scans for provider-prefix credentials (Anthropic, OpenAI, GitHub, AWS, Slack, Google, GitLab, npm, Docker, Stripe, plus env/header-gated hex tokens). Returns `{ provider }` — **never the literal credential**. Pass `envOrHeaderContext: true` only when scanning env/header values.
+- `SECRET_PATTERNS` — read-only constant; the active provider set is pinned by golden tests so additions stay non-breaking.
+
+### Exception baselines (since v0.7.0)
+- `applyExceptions(findings, exceptions, now?)` — suppress findings matched by `kind` + optional `salientKey` + optional `pathPrefix`. Expired exceptions re-surface the finding with severity downgraded to `'low'` and an `[EXPIRED WHITELIST]` prefix so stale baselines stay visible.
+- `validateException(value)` — runtime check for well-formed exception entries loaded from JSON/YAML.
+
+### Report envelope and merge (since v0.6.0)
+- `Report` — canonical multi-tool envelope wrapping a `Finding[]` with `schemaVersion`, `tool`, `rating`, optional `toolVersion`/`runId`/`conversationId`/`baseRef`/`headRef`, and tool-specific extension data in `data`
+- `Report.conversationId` — opt-in session identifier matching OpenTelemetry's [`gen_ai.conversation.id`](https://opentelemetry.io/docs/specs/semconv/gen-ai/) so governance findings and runtime traces can correlate by the same string. See [docs/INTEROP-OTEL.md](./docs/INTEROP-OTEL.md) for the full cross-walk.
+- `REPORT_SCHEMA_VERSION` — current envelope version (`'1.0'`)
+- `createReport({tool, findings, ...})` — sets `schemaVersion` and derives `rating` from max finding severity
+- `maxSeverity(findings)` — returns `'none' | Severity`, used by `createReport`
+- `validateReport(value)` — strict envelope check including each finding; returns `{ ok, errors[] }`
+- `mergeFindings(reports, opts?)` — combine N tool reports, dedupe by fingerprint, apply threshold, roll up rating; preserves both invalid envelopes and invalid findings separately so nothing is silently dropped. Propagates `conversationId` to the merged report iff every source agrees on it.
+
 ### Config readers
 - `readJsonObjectWithSource(path)` — JSONC reader, string-aware comment + trailing-comma stripping, position-preserving. Returns `{ value, json, text, parseError? }`. When the underlying parser provides a byte offset, `parseError` is a `ConfigParseError` carrying `line`/`column`/`rawOffset` instead of a raw `Error`.
 - `stripJsonComments(text)` — same logic exposed for in-memory text
@@ -83,7 +122,12 @@ The JSON schema at [`schemas/finding.schema.json`](./schemas/finding.schema.json
 - `lineOfTomlKey(text, dottedKey, scope?)` — 1-based line of a TOML key, optionally scoped to a byte range. Use scope to disambiguate `[[array]]`-of-tables entries that share the same leaf key.
 
 ### MCP command normalization
-- `normalizeMcpCommand({ command, args, url, env, cwd })` — canonical identity string for an MCP server entry. Drops neutral confirm flags (`-y`, `--yes`), strips Windows executable suffixes (`.cmd`, `.exe`, `.bat`, `.ps1`), sorts non-neutral flags alphabetically, preserves positional argument order, and includes env + cwd in the identity. Used to dedupe `mcp_command_mismatch` false positives when servers are equivalent but syntactically different (`npx -y foo@1.2.3` vs `npx foo@1.2.3`). Does not interpret what npx/uvx invocations resolve to at runtime — that's outside the substrate's scope.
+- `normalizeMcpCommand({ command, args, url, env, cwd })` — canonical identity string for an MCP server entry. Used to dedupe `mcp_command_mismatch` false positives when servers are equivalent but syntactically different across machines / config files. Does not interpret what npx/uvx invocations resolve to at runtime — that's outside the substrate's scope.
+  - Drops neutral confirm flags (`-y`, `--yes`) so `npx -y foo` and `npx foo` collapse to the same identity.
+  - Strips Windows executable suffixes (`.cmd`, `.exe`, `.bat`, `.ps1`) and case-folds Windows-shaped paths — `NPX.CMD`, `npx.cmd`, and `npx` are all the same executable on Windows.
+  - For known runtimes (`node`, `npx`, `python`, `bash`, etc.), drops the directory portion of absolute paths so `/usr/bin/node`, `/usr/local/bin/node`, and `node` produce identical identity. Custom scripts at absolute paths keep their full path.
+  - Treats common boolean flags (`--verbose`, `--quiet`, `--debug`, `--help`, `--version`, `--force`, `--dry-run`, `--json`, etc.) as standalone instead of greedily pairing them with the next positional argument.
+  - Sorts non-neutral `--key value` flag pairs alphabetically, preserves positional argument order, includes env + cwd in the identity.
 
 ### Shell tokenization
 - `tokenizeShell(command)` — quote-aware split on `;`, `|`, `&&`, `||` plus trivial obfuscation neutralization (`c""url` → `curl`, `c\\url` → `curl`)

package/dist/exceptions.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Exception baselines — the "we know about this, suppress it for now" mechanism
+ * that PolicyMesh (`.policymesh-exceptions.json`) and TaskBound (`.taskbound.yml`
+ * `ignore_kinds` / `allow_paths`) both invented separately. Lifted into the
+ * substrate so all five tools share one shape and one expiry contract.
+ *
+ * Two design choices worth flagging:
+ *
+ * 1. Expired exceptions DON'T silently drop. They re-surface the original
+ *    finding with severity downgraded to `'low'` and an `[EXPIRED WHITELIST]`
+ *    prefix on the message. The point of exception baselines is to make stale
+ *    suppression visible, not to grow a graveyard of permanent ignores.
+ *
+ * 2. Match keys are `kind` (required) plus optional `salientKey` and
+ *    `pathPrefix` narrowing. Subject/path matching from the two consumers
+ *    maps cleanly: PolicyMesh's `subject` is now `salientKey`; TaskBound's
+ *    `allow_paths` entries map to `pathPrefix` exceptions on the relevant
+ *    finding kind.
+ */
+import type { Finding } from './finding.js';
+/**
+ * A single exception rule. Suppresses (or downgrades, when expired) findings
+ * whose `kind` matches and — if either narrower is set — whose `salientKey`
+ * or `location.file` prefix also matches.
+ */
+export interface Exception {
+    /** Required: exact match against `Finding.kind`. */
+    kind: string;
+    /**
+     * Optional: exact match against `Finding.salientKey`. Use this to scope an
+     * exception to one specific finding instance at a site that produces
+     * multiple distinct findings (e.g. one of several suspicious packages on
+     * the same import line).
+     */
+    salientKey?: string;
+    /**
+     * Optional: only match findings whose `location.file` starts with this
+     * string. Use to scope an exception to a directory subtree without listing
+     * every file individually (TaskBound's `allow_paths` use case).
+     */
+    pathPrefix?: string;
+    /**
+     * Optional ISO 8601 date (YYYY-MM-DD or full timestamp). When the current
+     * date is past `expires`, matched findings re-surface with severity
+     * downgraded to `'low'` and an `[EXPIRED WHITELIST]` message prefix.
+     */
+    expires?: string;
+    /** Optional free-text rationale, preserved on expired findings via `data.exceptionReason`. */
+    reason?: string;
+}
+export interface ApplyExceptionsResult {
+    /** Findings after exceptions applied: survivors + downgraded expired entries. */
+    findings: Finding[];
+    /** Count of findings suppressed by an active (non-expired) exception. */
+    suppressed: number;
+    /** Count of findings surfaced as expired (downgraded + prefixed). */
+    expired: number;
+}
+/**
+ * Apply a set of exceptions to a finding list. Returns the post-filter
+ * list along with counts so a meta-reviewer can report how many findings
+ * the baseline suppressed.
+ *
+ * @example
+ * import { applyExceptions } from 'agent-gov-core';
+ *
+ * const result = applyExceptions(findings, [
+ *   { kind: 'capability_echo.high_capability_dep_added', salientKey: 'puppeteer', expires: '2026-06-01', reason: 'browser-tests rollout' },
+ *   { kind: 'task_bound.out_of_scope_file', pathPrefix: 'tools/internal/', reason: 'internal tooling refactor' },
+ * ]);
+ * console.log(`${result.suppressed} suppressed, ${result.expired} expired`);
+ */
+export declare function applyExceptions(findings: readonly Finding[], exceptions: readonly Exception[], now?: Date): ApplyExceptionsResult;
+/**
+ * Validate that an unknown value is a well-formed `Exception` shape. Useful
+ * when consumers load exceptions from JSON/YAML and want to surface parse-
+ * level errors as findings rather than crash.
+ */
+export declare function validateException(value: unknown): {
+    ok: boolean;
+    errors: string[];
+};
+//# sourceMappingURL=exceptions.d.ts.map

package/dist/exceptions.js

@@ -0,0 +1,129 @@
+/**
+ * Exception baselines — the "we know about this, suppress it for now" mechanism
+ * that PolicyMesh (`.policymesh-exceptions.json`) and TaskBound (`.taskbound.yml`
+ * `ignore_kinds` / `allow_paths`) both invented separately. Lifted into the
+ * substrate so all five tools share one shape and one expiry contract.
+ *
+ * Two design choices worth flagging:
+ *
+ * 1. Expired exceptions DON'T silently drop. They re-surface the original
+ *    finding with severity downgraded to `'low'` and an `[EXPIRED WHITELIST]`
+ *    prefix on the message. The point of exception baselines is to make stale
+ *    suppression visible, not to grow a graveyard of permanent ignores.
+ *
+ * 2. Match keys are `kind` (required) plus optional `salientKey` and
+ *    `pathPrefix` narrowing. Subject/path matching from the two consumers
+ *    maps cleanly: PolicyMesh's `subject` is now `salientKey`; TaskBound's
+ *    `allow_paths` entries map to `pathPrefix` exceptions on the relevant
+ *    finding kind.
+ */
+const EXPIRED_PREFIX = '[EXPIRED WHITELIST] ';
+const EXPIRED_DOWNGRADE = 'low';
+/**
+ * Apply a set of exceptions to a finding list. Returns the post-filter
+ * list along with counts so a meta-reviewer can report how many findings
+ * the baseline suppressed.
+ *
+ * @example
+ * import { applyExceptions } from 'agent-gov-core';
+ *
+ * const result = applyExceptions(findings, [
+ *   { kind: 'capability_echo.high_capability_dep_added', salientKey: 'puppeteer', expires: '2026-06-01', reason: 'browser-tests rollout' },
+ *   { kind: 'task_bound.out_of_scope_file', pathPrefix: 'tools/internal/', reason: 'internal tooling refactor' },
+ * ]);
+ * console.log(`${result.suppressed} suppressed, ${result.expired} expired`);
+ */
+export function applyExceptions(findings, exceptions, now = new Date()) {
+    if (exceptions.length === 0) {
+        return { findings: [...findings], suppressed: 0, expired: 0 };
+    }
+    const result = [];
+    let suppressed = 0;
+    let expired = 0;
+    for (const finding of findings) {
+        const match = findMatchingException(finding, exceptions);
+        if (!match) {
+            result.push(finding);
+            continue;
+        }
+        if (match.expires && isExpired(match.expires, now)) {
+            result.push(downgradeExpired(finding, match));
+            expired++;
+        }
+        else {
+            suppressed++;
+        }
+    }
+    return { findings: result, suppressed, expired };
+}
+function findMatchingException(finding, exceptions) {
+    for (const exc of exceptions) {
+        if (exc.kind !== finding.kind)
+            continue;
+        if (exc.salientKey !== undefined && exc.salientKey !== finding.salientKey)
+            continue;
+        if (exc.pathPrefix !== undefined) {
+            const file = finding.location?.file;
+            if (!file || !file.startsWith(exc.pathPrefix))
+                continue;
+        }
+        return exc;
+    }
+    return undefined;
+}
+function isExpired(expires, now) {
+    const parsed = new Date(expires);
+    if (Number.isNaN(parsed.getTime()))
+        return false;
+    return parsed.getTime() < now.getTime();
+}
+function downgradeExpired(finding, exc) {
+    const downgraded = {
+        ...finding,
+        severity: EXPIRED_DOWNGRADE,
+        message: EXPIRED_PREFIX + finding.message,
+    };
+    if (exc.reason !== undefined) {
+        downgraded.data = { ...(finding.data ?? {}), exceptionReason: exc.reason };
+    }
+    return downgraded;
+}
+/**
+ * Validate that an unknown value is a well-formed `Exception` shape. Useful
+ * when consumers load exceptions from JSON/YAML and want to surface parse-
+ * level errors as findings rather than crash.
+ */
+export function validateException(value) {
+    const errors = [];
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return { ok: false, errors: ['exception must be a plain object'] };
+    }
+    const v = value;
+    if (typeof v.kind !== 'string' || v.kind.length === 0) {
+        errors.push('kind must be a non-empty string');
+    }
+    if (v.salientKey !== undefined && typeof v.salientKey !== 'string') {
+        errors.push('salientKey must be a string when present');
+    }
+    if (v.pathPrefix !== undefined && typeof v.pathPrefix !== 'string') {
+        errors.push('pathPrefix must be a string when present');
+    }
+    if (v.expires !== undefined) {
+        if (typeof v.expires !== 'string') {
+            errors.push('expires must be an ISO 8601 string when present');
+        }
+        else if (Number.isNaN(new Date(v.expires).getTime())) {
+            errors.push('expires must be a parseable date (e.g. "2026-12-31" or full ISO timestamp)');
+        }
+    }
+    if (v.reason !== undefined && typeof v.reason !== 'string') {
+        errors.push('reason must be a string when present');
+    }
+    const allowed = new Set(['kind', 'salientKey', 'pathPrefix', 'expires', 'reason']);
+    for (const key of Object.keys(v)) {
+        if (!allowed.has(key))
+            errors.push(`unknown property: ${key}`);
+    }
+    return { ok: errors.length === 0, errors };
+}
+//# sourceMappingURL=exceptions.js.map

package/dist/index.d.ts

@@ -5,6 +5,14 @@ export { readJsonObjectWithSource, stripJsonComments } from './jsonc.js';
 export type { TomlObjectWithSource } from './toml.js';
 export { readTomlObject, parseToml } from './toml.js';
 export { ConfigParseError, lineColumnOfOffset } from './parse-error.js';
+export type { Report, CreateReportSpec, ReportValidationResult } from './report.js';
+export { REPORT_SCHEMA_VERSION, createReport, maxSeverity, validateReport, } from './report.js';
+export type { MergeOptions, MergeSource, InvalidReport, InvalidFinding, MergedReport, } from './merge.js';
+export { mergeFindings } from './merge.js';
+export type { SecretMatch, MatchSecretOptions } from './secrets.js';
+export { matchSecret, SECRET_PATTERNS } from './secrets.js';
+export type { Exception, ApplyExceptionsResult } from './exceptions.js';
+export { applyExceptions, validateException } from './exceptions.js';
 export type { ByteRange } from './locators.js';
 export { lineOfJsonKey, lineOfJsonStringValue, lineOfTomlKey, } from './locators.js';
 export type { McpCommandSpec } from './mcp.js';

package/dist/index.js

@@ -2,6 +2,10 @@ export { SEVERITIES, TOOL_KINDS, isSeverity, isToolKind, isNamespacedKind, kind,
 export { readJsonObjectWithSource, stripJsonComments } from './jsonc.js';
 export { readTomlObject, parseToml } from './toml.js';
 export { ConfigParseError, lineColumnOfOffset } from './parse-error.js';
+export { REPORT_SCHEMA_VERSION, createReport, maxSeverity, validateReport, } from './report.js';
+export { mergeFindings } from './merge.js';
+export { matchSecret, SECRET_PATTERNS } from './secrets.js';
+export { applyExceptions, validateException } from './exceptions.js';
 export { lineOfJsonKey, lineOfJsonStringValue, lineOfTomlKey, } from './locators.js';
 export { normalizeMcpCommand } from './mcp.js';
 export { tokenizeShell, tokenizeShellDeep, getCommandHead } from './shell.js';

package/dist/merge.d.ts

@@ -0,0 +1,91 @@
+import { type Finding, type Severity, type ToolKind } from './finding.js';
+export interface MergeOptions {
+    /**
+     * Lower bound for findings included in the merged output. Anything below
+     * this severity is dropped from `findings` (but still counted in
+     * `droppedBelowThreshold`). Defaults to `'low'` (include everything).
+     */
+    threshold?: Severity;
+    /**
+     * When two reports contribute findings with the same fingerprint, the
+     * default keeps the one with the higher severity. Set this to `'first'`
+     * to keep the first report's finding instead. Default: `'highest_severity'`.
+     */
+    duplicatePolicy?: 'highest_severity' | 'first';
+}
+export interface MergeSource {
+    tool: ToolKind;
+    toolVersion?: string;
+    /** Conversation ID declared by this source, if any. */
+    conversationId?: string;
+    /** Number of findings in this source report (BEFORE dedup or threshold filtering). */
+    findingCount: number;
+    /** Aggregate rating reported by the source. */
+    rating: 'none' | Severity;
+}
+export interface InvalidReport {
+    /** Index into the input `reports` array. */
+    index: number;
+    /** Tool name from the malformed report, if recoverable. */
+    tool?: ToolKind;
+    errors: string[];
+}
+export interface InvalidFinding {
+    /** Originating tool's report index. */
+    reportIndex: number;
+    /** Index of the finding within that report's `findings` array. */
+    findingIndex: number;
+    /** Tool name from the report. */
+    tool: ToolKind;
+    errors: string[];
+}
+export interface MergedReport {
+    schemaVersion: '1.0';
+    /** Per-tool provenance for the reports that fed into this merge. */
+    sources: MergeSource[];
+    /** Aggregate rating across all surviving findings. */
+    rating: 'none' | Severity;
+    /**
+     * Conversation ID shared by all valid source reports — set iff every source
+     * declared the same `conversationId`. When sources disagree (or some lack the
+     * field), this is omitted so a meta-reviewer can detect cross-conversation
+     * mixing.
+     */
+    conversationId?: string;
+    /** Deduped findings, sorted by severity (highest first). */
+    findings: Finding[];
+    /** Count of findings dropped because their severity was below `threshold`. */
+    droppedBelowThreshold: number;
+    /** Count of finding pairs collapsed via fingerprint dedup. */
+    duplicateCollapsed: number;
+    /** Reports rejected by envelope validation. */
+    invalidReports: InvalidReport[];
+    /** Individual findings rejected by finding validation. */
+    invalidFindings: InvalidFinding[];
+    /** Severity counts across the surviving findings. */
+    severityCounts: Record<Severity, number>;
+}
+/**
+ * Merge N reports from different tools into one normalized report. Validates
+ * each input report and each finding, deduplicates by fingerprint, applies an
+ * optional severity threshold, and rolls up the aggregate rating.
+ *
+ * Invalid reports / findings are NOT silently dropped — they're collected in
+ * `invalidReports` and `invalidFindings` so a meta-reviewer can surface them
+ * to the user instead of letting bad data disappear.
+ *
+ * @example
+ * import { readFileSync } from 'node:fs';
+ * import { mergeFindings } from 'agent-gov-core';
+ *
+ * const reports = [
+ *   JSON.parse(readFileSync('scopetrail-report.json', 'utf8')),
+ *   JSON.parse(readFileSync('policymesh-report.json', 'utf8')),
+ *   JSON.parse(readFileSync('capabilityecho-report.json', 'utf8')),
+ * ];
+ * const merged = mergeFindings(reports, { threshold: 'medium' });
+ * console.log(`Merged rating: ${merged.rating}`);
+ * console.log(`${merged.findings.length} unique findings across ${merged.sources.length} tools`);
+ */
+export declare function mergeFindings(reports: readonly unknown[], opts?: MergeOptions): MergedReport;
+//# sourceMappingURL=merge.d.ts.map

package/dist/merge.js

@@ -0,0 +1,154 @@
+import { SEVERITIES, TOOL_KINDS, isToolKind, validateFinding } from './finding.js';
+import { REPORT_SCHEMA_VERSION, maxSeverity } from './report.js';
+import { rankSeverity } from './action.js';
+/**
+ * Merge N reports from different tools into one normalized report. Validates
+ * each input report and each finding, deduplicates by fingerprint, applies an
+ * optional severity threshold, and rolls up the aggregate rating.
+ *
+ * Invalid reports / findings are NOT silently dropped — they're collected in
+ * `invalidReports` and `invalidFindings` so a meta-reviewer can surface them
+ * to the user instead of letting bad data disappear.
+ *
+ * @example
+ * import { readFileSync } from 'node:fs';
+ * import { mergeFindings } from 'agent-gov-core';
+ *
+ * const reports = [
+ *   JSON.parse(readFileSync('scopetrail-report.json', 'utf8')),
+ *   JSON.parse(readFileSync('policymesh-report.json', 'utf8')),
+ *   JSON.parse(readFileSync('capabilityecho-report.json', 'utf8')),
+ * ];
+ * const merged = mergeFindings(reports, { threshold: 'medium' });
+ * console.log(`Merged rating: ${merged.rating}`);
+ * console.log(`${merged.findings.length} unique findings across ${merged.sources.length} tools`);
+ */
+export function mergeFindings(reports, opts = {}) {
+    const threshold = opts.threshold ?? 'low';
+    const duplicatePolicy = opts.duplicatePolicy ?? 'highest_severity';
+    const thresholdRank = rankSeverity(threshold);
+    const sources = [];
+    const invalidReports = [];
+    const invalidFindings = [];
+    // fingerprint → Finding chosen so far
+    const dedupe = new Map();
+    let droppedBelowThreshold = 0;
+    let duplicateCollapsed = 0;
+    for (let i = 0; i < reports.length; i++) {
+        const candidate = reports[i];
+        // Structural envelope check — does NOT recurse into individual findings.
+        // A report with some malformed findings is still partially mergeable; we
+        // collect the bad ones into `invalidFindings` and pass through the good
+        // ones. Only a structurally broken envelope (wrong tool, missing array,
+        // etc.) gets rejected wholesale.
+        const envelope = validateReportEnvelope(candidate);
+        if (!envelope.ok) {
+            const tool = candidateTool(candidate);
+            invalidReports.push({ index: i, tool, errors: envelope.errors });
+            continue;
+        }
+        const report = candidate;
+        const source = {
+            tool: report.tool,
+            findingCount: report.findings.length,
+            rating: report.rating,
+        };
+        if (report.toolVersion !== undefined)
+            source.toolVersion = report.toolVersion;
+        if (report.conversationId !== undefined)
+            source.conversationId = report.conversationId;
+        sources.push(source);
+        for (let j = 0; j < report.findings.length; j++) {
+            const finding = report.findings[j];
+            const findingCheck = validateFinding(finding);
+            if (!findingCheck.ok) {
+                invalidFindings.push({
+                    reportIndex: i,
+                    findingIndex: j,
+                    tool: report.tool,
+                    errors: findingCheck.errors,
+                });
+                continue;
+            }
+            if (rankSeverity(finding.severity) < thresholdRank) {
+                droppedBelowThreshold++;
+                continue;
+            }
+            // Dedupe by fingerprint. Fall back to the finding's structural identity
+            // when fingerprint is missing — though by v0.5.0 it should always be
+            // populated by `createFinding`.
+            const key = finding.fingerprint ?? `${finding.kind}|${finding.location?.file ?? ''}|${finding.location?.line ?? ''}|${finding.salientKey ?? ''}`;
+            const existing = dedupe.get(key);
+            if (existing === undefined) {
+                dedupe.set(key, finding);
+                continue;
+            }
+            duplicateCollapsed++;
+            if (duplicatePolicy === 'highest_severity') {
+                if (rankSeverity(finding.severity) > rankSeverity(existing.severity)) {
+                    dedupe.set(key, finding);
+                }
+            }
+            // 'first' policy: keep existing — do nothing
+        }
+    }
+    const findings = Array.from(dedupe.values()).sort((a, b) => rankSeverity(b.severity) - rankSeverity(a.severity));
+    const severityCounts = { low: 0, medium: 0, high: 0, critical: 0 };
+    for (const f of findings)
+        severityCounts[f.severity]++;
+    // Propagate conversationId iff every source agrees. When sources disagree
+    // or some lack the field, leave it undefined — silent unification of cross-
+    // conversation reports would hide a meta-reviewer misuse.
+    const conversationIds = sources.map((s) => s.conversationId);
+    const allSame = conversationIds.length > 0
+        && conversationIds.every((id) => id !== undefined && id === conversationIds[0]);
+    const merged = {
+        schemaVersion: '1.0',
+        sources,
+        rating: maxSeverity(findings),
+        findings,
+        droppedBelowThreshold,
+        duplicateCollapsed,
+        invalidReports,
+        invalidFindings,
+        severityCounts,
+    };
+    if (allSame)
+        merged.conversationId = conversationIds[0];
+    return merged;
+}
+function candidateTool(value) {
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    const t = value.tool;
+    return typeof t === 'string' && /^(scope_trail|policy_mesh|capability_echo|task_bound|session_trail)$/.test(t)
+        ? t
+        : undefined;
+}
+/**
+ * Envelope-only structural check. Unlike `validateReport`, this does NOT
+ * recurse into individual findings — that's done separately by mergeFindings
+ * so a single bad finding doesn't poison the rest of the report.
+ */
+function validateReportEnvelope(value) {
+    const errors = [];
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return { ok: false, errors: ['report must be a plain object'] };
+    }
+    const v = value;
+    if (v.schemaVersion !== REPORT_SCHEMA_VERSION) {
+        errors.push(`schemaVersion must be '${REPORT_SCHEMA_VERSION}'`);
+    }
+    if (!isToolKind(v.tool)) {
+        errors.push(`tool must be one of: ${TOOL_KINDS.join(', ')}`);
+    }
+    const ratingValues = new Set(['none', ...SEVERITIES]);
+    if (typeof v.rating !== 'string' || !ratingValues.has(v.rating)) {
+        errors.push(`rating must be one of: none, ${SEVERITIES.join(', ')}`);
+    }
+    if (!Array.isArray(v.findings)) {
+        errors.push('findings must be an array');
+    }
+    return { ok: errors.length === 0, errors };
+}
+//# sourceMappingURL=merge.js.map

package/dist/report.d.ts

@@ -0,0 +1,85 @@
+import { type Finding, type Severity, type ToolKind } from './finding.js';
+/** Canonical envelope version. */
+export declare const REPORT_SCHEMA_VERSION: "1.0";
+/**
+ * Canonical multi-tool report envelope. Wraps `Finding[]` with provenance,
+ * rating, and optional tool-specific extension data so a cross-tool
+ * meta-reviewer can ingest reports from N tools through one shape.
+ */
+export interface Report {
+    schemaVersion: typeof REPORT_SCHEMA_VERSION;
+    tool: ToolKind;
+    toolVersion?: string;
+    runId?: string;
+    /**
+     * Identifier for the agent session, PR review, or thread this run belongs to.
+     * Distinct from `runId` (which identifies *this* tool run): one conversation
+     * can produce many runs. Matches OpenTelemetry's `gen_ai.conversation.id`
+     * semantic convention — if a consumer also emits OTel traces about the same
+     * agent session, pass the same string here and downstream tooling can cross-
+     * reference governance findings with the traces.
+     *
+     * @see https://opentelemetry.io/docs/specs/semconv/gen-ai/
+     */
+    conversationId?: string;
+    baseRef?: string;
+    headRef?: string;
+    /** Aggregate severity. `'none'` iff findings is empty or all below threshold. */
+    rating: 'none' | Severity;
+    findings: Finding[];
+    /** Tool-specific extension data (PolicyMesh `effectiveUnion`, CapabilityEcho `surfaceSummary`, etc). */
+    data?: Record<string, unknown>;
+}
+export interface CreateReportSpec {
+    tool: ToolKind;
+    toolVersion?: string;
+    runId?: string;
+    /** See {@link Report.conversationId}. */
+    conversationId?: string;
+    baseRef?: string;
+    headRef?: string;
+    findings: Finding[];
+    data?: Record<string, unknown>;
+    /**
+     * Explicit rating override. When omitted, `rating` is computed as the
+     * maximum severity across `findings` (or `'none'` if empty).
+     */
+    rating?: 'none' | Severity;
+}
+/**
+ * Build a {@link Report} with `schemaVersion` set and `rating` derived from
+ * the maximum finding severity (unless overridden). This is the recommended
+ * way to produce a report — sets the envelope version correctly and computes
+ * the rating consistently with other tools.
+ *
+ * @example
+ * const report = createReport({
+ *   tool: 'scope_trail',
+ *   toolVersion: '0.1.18',
+ *   baseRef: 'abc123',
+ *   headRef: 'def456',
+ *   findings: [finding1, finding2],
+ *   data: { mcpServers: [...] },
+ * });
+ */
+export declare function createReport(spec: CreateReportSpec): Report;
+/**
+ * Maximum severity across a finding list. Returns `'none'` for empty input.
+ * Used by {@link createReport} when no explicit rating is supplied.
+ */
+export declare function maxSeverity(findings: readonly Finding[]): 'none' | Severity;
+export interface ReportValidationResult {
+    ok: boolean;
+    errors: string[];
+}
+/**
+ * Runtime check that a value conforms to the canonical Report envelope.
+ * Aggregates errors across all findings — a single malformed finding does
+ * not short-circuit the rest of the envelope check.
+ *
+ * @example
+ * const result = validateReport(JSON.parse(reportJson));
+ * if (!result.ok) console.error(result.errors.join('\n'));
+ */
+export declare function validateReport(value: unknown): ReportValidationResult;
+//# sourceMappingURL=report.d.ts.map

package/dist/report.js

@@ -0,0 +1,156 @@
+import { SEVERITIES, TOOL_KINDS, isSeverity, isToolKind, validateFinding, } from './finding.js';
+/** Canonical envelope version. */
+export const REPORT_SCHEMA_VERSION = '1.0';
+/**
+ * Build a {@link Report} with `schemaVersion` set and `rating` derived from
+ * the maximum finding severity (unless overridden). This is the recommended
+ * way to produce a report — sets the envelope version correctly and computes
+ * the rating consistently with other tools.
+ *
+ * @example
+ * const report = createReport({
+ *   tool: 'scope_trail',
+ *   toolVersion: '0.1.18',
+ *   baseRef: 'abc123',
+ *   headRef: 'def456',
+ *   findings: [finding1, finding2],
+ *   data: { mcpServers: [...] },
+ * });
+ */
+export function createReport(spec) {
+    const report = {
+        schemaVersion: REPORT_SCHEMA_VERSION,
+        tool: spec.tool,
+        rating: spec.rating ?? maxSeverity(spec.findings),
+        findings: spec.findings,
+    };
+    if (spec.toolVersion !== undefined)
+        report.toolVersion = spec.toolVersion;
+    if (spec.runId !== undefined)
+        report.runId = spec.runId;
+    if (spec.conversationId !== undefined)
+        report.conversationId = spec.conversationId;
+    if (spec.baseRef !== undefined)
+        report.baseRef = spec.baseRef;
+    if (spec.headRef !== undefined)
+        report.headRef = spec.headRef;
+    if (spec.data !== undefined)
+        report.data = spec.data;
+    return report;
+}
+/**
+ * Maximum severity across a finding list. Returns `'none'` for empty input.
+ * Used by {@link createReport} when no explicit rating is supplied.
+ */
+export function maxSeverity(findings) {
+    let best = 'none';
+    for (const f of findings) {
+        if (severityRank(f.severity) > severityRank(best))
+            best = f.severity;
+    }
+    return best;
+}
+function severityRank(s) {
+    if (s === 'none')
+        return 0;
+    if (s === 'low')
+        return 1;
+    if (s === 'medium')
+        return 2;
+    if (s === 'high')
+        return 3;
+    return 4;
+}
+const REPORT_ALLOWED_KEYS = new Set([
+    'schemaVersion',
+    'tool',
+    'toolVersion',
+    'runId',
+    'conversationId',
+    'baseRef',
+    'headRef',
+    'rating',
+    'findings',
+    'data',
+]);
+const RATING_VALUES = new Set(['none', ...SEVERITIES]);
+/**
+ * Runtime check that a value conforms to the canonical Report envelope.
+ * Aggregates errors across all findings — a single malformed finding does
+ * not short-circuit the rest of the envelope check.
+ *
+ * @example
+ * const result = validateReport(JSON.parse(reportJson));
+ * if (!result.ok) console.error(result.errors.join('\n'));
+ */
+export function validateReport(value) {
+    const errors = [];
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return { ok: false, errors: ['report must be a plain object'] };
+    }
+    const v = value;
+    if (v.schemaVersion !== REPORT_SCHEMA_VERSION) {
+        errors.push(`schemaVersion must be '${REPORT_SCHEMA_VERSION}'`);
+    }
+    if (!isToolKind(v.tool)) {
+        errors.push(`tool must be one of: ${TOOL_KINDS.join(', ')}`);
+    }
+    if (typeof v.rating !== 'string' || !RATING_VALUES.has(v.rating)) {
+        errors.push(`rating must be one of: none, ${SEVERITIES.join(', ')}`);
+    }
+    if (!Array.isArray(v.findings)) {
+        errors.push('findings must be an array');
+    }
+    else {
+        for (let i = 0; i < v.findings.length; i++) {
+            const f = validateFinding(v.findings[i]);
+            if (!f.ok) {
+                errors.push(`findings[${i}]: ${f.errors.join('; ')}`);
+            }
+            else if (isToolKind(v.tool) && v.findings[i].tool !== v.tool) {
+                errors.push(`findings[${i}].tool ('${v.findings[i].tool}') does not match report.tool ('${v.tool}')`);
+            }
+        }
+    }
+    if (v.toolVersion !== undefined && typeof v.toolVersion !== 'string') {
+        errors.push('toolVersion must be a string when present');
+    }
+    if (v.runId !== undefined && typeof v.runId !== 'string') {
+        errors.push('runId must be a string when present');
+    }
+    if (v.conversationId !== undefined && typeof v.conversationId !== 'string') {
+        errors.push('conversationId must be a string when present');
+    }
+    if (v.baseRef !== undefined && typeof v.baseRef !== 'string') {
+        errors.push('baseRef must be a string when present');
+    }
+    if (v.headRef !== undefined && typeof v.headRef !== 'string') {
+        errors.push('headRef must be a string when present');
+    }
+    if (v.data !== undefined && (v.data === null || typeof v.data !== 'object' || Array.isArray(v.data))) {
+        errors.push('data must be an object when present');
+    }
+    for (const key of Object.keys(v)) {
+        if (!REPORT_ALLOWED_KEYS.has(key))
+            errors.push(`unknown property: ${key}`);
+    }
+    // Cross-field consistency: rating should be at or above the max finding severity.
+    // We don't *enforce* this strictly (a tool may downgrade by policy) but flag a
+    // genuine inconsistency where the rating is BELOW what the findings imply.
+    if (Array.isArray(v.findings) &&
+        typeof v.rating === 'string' &&
+        RATING_VALUES.has(v.rating)) {
+        const findingsOk = v.findings.every((f) => validateFinding(f).ok);
+        if (findingsOk) {
+            const implied = maxSeverity(v.findings);
+            if (severityRank(v.rating) < severityRank(implied)) {
+                errors.push(`rating '${v.rating}' is below the maximum finding severity '${implied}'`);
+            }
+        }
+    }
+    // Ensure isSeverity-style check on rating when not 'none' for callers that
+    // need a tighter type than the wider RATING_VALUES set.
+    void isSeverity;
+    return { ok: errors.length === 0, errors };
+}
+//# sourceMappingURL=report.js.map

package/dist/secrets.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Hardcoded credential detection.
+ *
+ * Scans strings for provider-prefix tokens (Anthropic, OpenAI, GitHub, AWS,
+ * Slack, Google, GitLab, npm, Docker, Stripe) plus a length-restricted hex
+ * pattern that only fires in env/header context (a bare hex blob in a
+ * positional command argument is indistinguishable from a commit SHA).
+ *
+ * Contract: the literal credential is NEVER returned in any field. Callers
+ * receive only the provider name plus the pattern that matched (provider
+ * label only — not the regex). This is the same contract PolicyMesh shipped
+ * the detector under, lifted into the substrate so every governance tool
+ * uses one source of truth for "what does a hardcoded credential look like."
+ *
+ * @example
+ * import { matchSecret } from 'agent-gov-core';
+ *
+ * matchSecret('sk-ant-abcdefghijklmnopqrstuv');
+ * // → { provider: 'Anthropic' }
+ *
+ * matchSecret('env:OPENAI_API_KEY');
+ * // → undefined (env var reference, not a literal)
+ *
+ * matchSecret('a'.repeat(40), { envOrHeaderContext: true });
+ * // → undefined (only A-F0-9 are hex; not a hex token)
+ */
+export interface SecretMatch {
+    /** Human-readable provider name. The literal credential is NEVER included. */
+    provider: string;
+}
+export interface MatchSecretOptions {
+    /**
+     * When `true`, patterns flagged `envOrHeaderOnly` are eligible. Set this
+     * only when scanning env values or HTTP header values — never when scanning
+     * a joined launch command (positional args often contain commit SHAs that
+     * would false-positive against a bare hex token pattern).
+     */
+    envOrHeaderContext?: boolean;
+}
+interface SecretPattern {
+    provider: string;
+    regex: RegExp;
+    /** See {@link MatchSecretOptions.envOrHeaderContext}. */
+    envOrHeaderOnly?: boolean;
+}
+/**
+ * Built-in provider patterns. Conservative — only shapes whose prefix
+ * unambiguously identifies a credential class. The bare hex pattern is gated
+ * to env/header context to avoid commit-SHA false positives.
+ *
+ * Stable as of v0.7.0 — additions are non-breaking, removals or shape changes
+ * require a major bump (the golden compatibility tests in `test/golden.test.mjs`
+ * pin the current provider set).
+ */
+export declare const SECRET_PATTERNS: readonly Readonly<SecretPattern>[];
+/**
+ * Scan `value` for a hardcoded provider credential. Returns the matched
+ * provider name (never the literal credential) or `undefined` when nothing
+ * matches.
+ *
+ * Set `options.envOrHeaderContext` to `true` only when scanning env values
+ * or HTTP header values — that enables the more permissive hex-token pattern
+ * which would false-positive on positional command arguments.
+ */
+export declare function matchSecret(value: string, options?: MatchSecretOptions): SecretMatch | undefined;
+export {};
+//# sourceMappingURL=secrets.d.ts.map

package/dist/secrets.js

@@ -0,0 +1,81 @@
+/**
+ * Hardcoded credential detection.
+ *
+ * Scans strings for provider-prefix tokens (Anthropic, OpenAI, GitHub, AWS,
+ * Slack, Google, GitLab, npm, Docker, Stripe) plus a length-restricted hex
+ * pattern that only fires in env/header context (a bare hex blob in a
+ * positional command argument is indistinguishable from a commit SHA).
+ *
+ * Contract: the literal credential is NEVER returned in any field. Callers
+ * receive only the provider name plus the pattern that matched (provider
+ * label only — not the regex). This is the same contract PolicyMesh shipped
+ * the detector under, lifted into the substrate so every governance tool
+ * uses one source of truth for "what does a hardcoded credential look like."
+ *
+ * @example
+ * import { matchSecret } from 'agent-gov-core';
+ *
+ * matchSecret('sk-ant-abcdefghijklmnopqrstuv');
+ * // → { provider: 'Anthropic' }
+ *
+ * matchSecret('env:OPENAI_API_KEY');
+ * // → undefined (env var reference, not a literal)
+ *
+ * matchSecret('a'.repeat(40), { envOrHeaderContext: true });
+ * // → undefined (only A-F0-9 are hex; not a hex token)
+ */
+/**
+ * Built-in provider patterns. Conservative — only shapes whose prefix
+ * unambiguously identifies a credential class. The bare hex pattern is gated
+ * to env/header context to avoid commit-SHA false positives.
+ *
+ * Stable as of v0.7.0 — additions are non-breaking, removals or shape changes
+ * require a major bump (the golden compatibility tests in `test/golden.test.mjs`
+ * pin the current provider set).
+ */
+export const SECRET_PATTERNS = [
+    { provider: 'Anthropic', regex: /sk-ant-[A-Za-z0-9_-]{20,}/ },
+    { provider: 'OpenAI', regex: /sk-proj-[A-Za-z0-9_-]{20,}/ },
+    { provider: 'OpenAI', regex: /sk-(?!ant-|proj-)[A-Za-z0-9]{32,}/ },
+    { provider: 'GitHub', regex: /gh[pousr]_[A-Za-z0-9]{36,}/ },
+    { provider: 'GitHub', regex: /github_pat_[A-Za-z0-9_]{20,}/ },
+    { provider: 'Slack', regex: /xox[abprs]-[A-Za-z0-9-]{20,}/ },
+    { provider: 'AWS', regex: /AKIA[0-9A-Z]{16}/ },
+    { provider: 'Google', regex: /AIza[0-9A-Za-z_-]{35}/ },
+    { provider: 'GitLab', regex: /glpat-[A-Za-z0-9_-]{20,}/ },
+    { provider: 'npm', regex: /npm_[A-Za-z0-9]{36}/ },
+    { provider: 'Docker', regex: /dckr_pat_[A-Za-z0-9_-]{20,}/ },
+    { provider: 'Stripe', regex: /(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{20,}/ },
+    // env/header context only — see comment block at top of file.
+    { provider: 'Hex token', regex: /(?:^|[^A-Fa-f0-9])([A-Fa-f0-9]{40,})(?:$|[^A-Fa-f0-9])/, envOrHeaderOnly: true },
+];
+/**
+ * Prefix marking an environment-variable reference. Values starting with
+ * `env:` are not literal credentials — they're a reference resolved at
+ * runtime by the consuming tool (Codex notation). Skipped during scanning.
+ */
+const ENV_REFERENCE_PREFIX = 'env:';
+/**
+ * Scan `value` for a hardcoded provider credential. Returns the matched
+ * provider name (never the literal credential) or `undefined` when nothing
+ * matches.
+ *
+ * Set `options.envOrHeaderContext` to `true` only when scanning env values
+ * or HTTP header values — that enables the more permissive hex-token pattern
+ * which would false-positive on positional command arguments.
+ */
+export function matchSecret(value, options = {}) {
+    if (!value)
+        return undefined;
+    if (value.startsWith(ENV_REFERENCE_PREFIX))
+        return undefined;
+    for (const pattern of SECRET_PATTERNS) {
+        if (pattern.envOrHeaderOnly && !options.envOrHeaderContext)
+            continue;
+        if (pattern.regex.test(value)) {
+            return { provider: pattern.provider };
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=secrets.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-gov-core",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Shared primitives for the AI-agent governance suite: Finding schema, JSONC/TOML readers, line locators, MCP command normalization, shell tokenization, and GitHub Action helpers.",
   "type": "module",
   "main": "./dist/index.js",
@@ -14,7 +14,8 @@
       "types": "./dist/test-utils.d.ts",
       "import": "./dist/test-utils.js"
     },
-    "./schemas/finding.schema.json": "./schemas/finding.schema.json"
+    "./schemas/finding.schema.json": "./schemas/finding.schema.json",
+    "./schemas/report.schema.json": "./schemas/report.schema.json"
   },
   "files": [
     "dist/**/*.js",

package/schemas/report.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/Conalh/agent-gov-core/schemas/report.schema.json",
+  "title": "Report",
+  "description": "Canonical multi-tool report envelope emitted by tools in the AI-agent governance suite. Wraps a `Finding[]` with provenance, rating, and optional tool-specific extension data so a cross-tool meta-reviewer can ingest reports from N tools through one shape.",
+  "type": "object",
+  "required": ["schemaVersion", "tool", "rating", "findings"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "const": "1.0",
+      "description": "Envelope schema version. Currently '1.0'. Future incompatible envelope changes require a major bump on this field; readers must reject unknown major versions."
+    },
+    "tool": {
+      "type": "string",
+      "enum": ["scope_trail", "policy_mesh", "capability_echo", "task_bound", "session_trail"],
+      "description": "Originating tool. Matches the `Finding.tool` enum."
+    },
+    "toolVersion": {
+      "type": "string",
+      "description": "Semver of the emitting tool (e.g. '0.1.18'). Optional; helps a meta-reviewer attribute findings to a specific release."
+    },
+    "runId": {
+      "type": "string",
+      "description": "Unique identifier for this run. Optional; useful when merging reports from concurrent runs or comparing runs over time."
+    },
+    "conversationId": {
+      "type": "string",
+      "description": "Identifier for the agent session, PR review, or thread this run belongs to. Distinct from runId (one conversation can produce many runs). Matches OpenTelemetry's gen_ai.conversation.id semantic convention — if a consumer also emits OTel traces about the same agent session, pass the same string here."
+    },
+    "baseRef": {
+      "type": "string",
+      "description": "Git base ref for diff-mode tools (ScopeTrail, CapabilityEcho, TaskBound). Omit for non-diff tools (PolicyMesh, SessionTrail)."
+    },
+    "headRef": {
+      "type": "string",
+      "description": "Git head ref for diff-mode tools. Omit for non-diff tools."
+    },
+    "rating": {
+      "type": "string",
+      "enum": ["none", "low", "medium", "high", "critical"],
+      "description": "Aggregate severity for this report. 'none' iff `findings` is empty or all findings fell below the tool's fail-on threshold."
+    },
+    "findings": {
+      "type": "array",
+      "items": { "$ref": "./finding.schema.json" },
+      "description": "Findings emitted by this tool run."
+    },
+    "data": {
+      "type": "object",
+      "description": "Tool-specific extension data (e.g. PolicyMesh's `effectiveUnion`, CapabilityEcho's `surfaceSummary`, ScopeTrail's `scopeMatchCount`). Opaque to a cross-tool meta-reviewer but preserved so each tool's UX can read its own extensions back from a merged report."
+    }
+  }
+}