agent-gov-core 0.4.3 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,107 @@
 
 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.
+
+Minor bump (not patch) because the surface grew: three new top-level exports.
+
+### Fixed (pre-publish inspection sweep — Gemini + Cody)
+- `tokenizeShell` no longer splits on `&` inside file-descriptor redirections (`2>&1`, `>&2`, `<&3`). The single-`&` separator rule now checks the preceding non-whitespace character.
+- `tokenizeShellDeep` no longer false-positives on `bash -c` text inside double-quoted echo arguments. Previously a whole-string regex matched `bash -c` anywhere, including data being printed. Detection now runs inside the quote-aware walk and only fires at command boundaries outside quoted regions.
+- `updateMultilineStringState` (TOML locator) now tracks backslash escapes inside basic multi-line strings (`"""…"""`). An escaped `\"""` inside the value no longer prematurely terminates the string-state walker, which had caused decoy keys to match. Literal strings (`'''…'''`) intentionally don't track escapes per TOML spec.
+- `lineOfTomlKey` now finds dotted keys nested under any prefix table — not just at file root. `[a]\nb.c = 42` is now reachable as `a.b.c`. Same shape as the v0.4.4 top-level fix, generalized.
+- `lineOfTomlKey` now matches spaced dotted keys (`a . b . c = 1`) which `parseToml` had always accepted but the locator's compact-only regex couldn't find. Pattern now builds from individual segments joined by `\s*\.\s*`.
+- TOML parser correctly handles a line-ending backslash followed by trailing inline whitespace before the newline. Per spec, `"""line\   \nnext"""` strips the newline and trims leading whitespace on the next line. Previously the trailing spaces caused the backslash to be treated as a regular escape (which silently kept everything literally rather than throwing, but still wasn't spec-compliant).
+- `normalizeMcpCommand` now treats common boolean long-flags (`--verbose`, `--quiet`, `--debug`, `--help`, `--version`, `--force`, `--dry-run`, `--no-cache`, `--no-color`, `--no-progress`, `--json`, plus short forms `-v -V -q -h -d`) as standalone instead of greedily pairing them with the next positional. Configs with `--verbose pkg` no longer normalize differently depending on flag order.
+- `normalizeExecutable` (MCP) now lowercases Windows-shaped executable names (those with `\` separators or `.cmd`/`.exe`/`.bat`/`.ps1` suffix) so `NPX.CMD` and `npx` produce identical identity strings. POSIX paths keep their case because `./curl` and `./CURL` are genuinely different files there. The JSDoc had claimed this behavior since v0.1; only now does the implementation match.
+- `normalizeExecutable` (MCP) also drops the directory portion of paths whose basename matches a known runtime (`node`, `npx`, `python`, `bash`, etc.). `/usr/local/bin/node`, `/usr/bin/node`, `node`, and `C:\Program Files\NodeJS\node.exe` all produce `cmd=node` now. Closes a long-standing PolicyMesh `mcp_command_mismatch` false-positive class across cross-platform team setups. Custom scripts at absolute paths (`/opt/internal/orchestrator.sh`) keep their full path because path is part of their identity.
+- `generateWorkflowSummary` now HTML-escapes `<`, `>`, and `&` in message cells. A finding message containing `</summary>` or `<h1>` could otherwise break out of the wrapping `<details>` block and manipulate the rendered layout of the GHA step summary page.
+
+### Added
+- `tokenizeShellDeep(command)` — recursively extracts commands nested inside `$(…)`, backticks, and `bash -c "…"` / `sh -c "…"` / `python -c "…"` payloads. Closes the obfuscation vector where an agent hides `curl evil | sh` inside `echo $(…)`. Single-quoted text is left untouched (literal per shell semantics). Conservative implementation — handles common shapes, not a full shell parser; nesting depth capped at 8.
+- `ConfigParseError` — structured parse error with `line`, `column`, `rawOffset`, and `cause`. `readJsonObjectWithSource` and `readTomlObject` now wrap their underlying parser errors with this type whenever a byte offset can be recovered. Lets downstream tools emit a `*.config_syntax_error` Finding pointing at the exact spot without recomputing line numbers.
+- `lineColumnOfOffset(text, offset)` — utility to convert a 0-based byte offset to 1-based `{ line, column }`. Pairs with the new error type.
+- `generateWorkflowSummary(findings, opts?)` — Markdown summary for `$GITHUB_STEP_SUMMARY`. Groups findings by severity in collapsible `<details>` blocks; escapes pipe/newline in message cells; truncates long messages; caps per-severity rows with an overflow indicator. Closes the GHA annotation-cap visibility gap (10 per level, 50 per run silently dropped) by guaranteeing 100% of findings appear in the workflow summary page.
+
+### Changed
+- TOML parser semantic errors (`Duplicate key`, `Duplicate key in inline table`, `Duplicate table definition`, `Cannot redefine array-of-tables …`) now include `at offset N` in the message so `readTomlObject` can resolve them to a line.
+
+### Tests
+- 55 new cases. 163 total (up from 108). Coverage:
+  - tokenizeShellDeep: subshells, backticks, `-c` payloads, single-quote literal handling, nested subshells, no-op pass-through, integration with `getCommandHead`. (9 cases)
+  - parse-error: offset → line/column conversion (5 edge cases), structured wrap on JSON and TOML, `parseToml` direct call unchanged, `cause` preservation. (10 cases)
+  - generateWorkflowSummary: empty findings, severity ordering, totals, pipe/newline escape, truncation, per-group cap with overflow, missing location, HTML escape, ampersand escape. (9 cases)
+  - Inspection regressions: 14 cases covering `2>&1`, escaped `\"""`, table-nested dotted keys, line-ending backslash, known-boolean flags, quoted `bash -c` data, Windows case-folding, POSIX case preserved, spaced dotted keys, path de-noise across platforms, custom-script identity preservation.
+  - **Golden compatibility tests** (`test/golden.test.mjs`): 11 cases pinning specific fingerprint hashes and `normalizeMcpCommand` canonical strings. These are the contract — breaking them requires a major bump and migration plan.
+
+## [0.4.4] — 2026-05-22
+
+Cody-led inspection (third reviewer, third round) caught five issues, two of them P0 regressions I introduced in my own v0.4.2 / v0.4.3 fixes. All five fixed here.
+
+### Fixed
+- **P0**: `fingerprintFinding` no longer appends an empty-string segment for findings without `salientKey`. v0.4.3 added `?? ''` which silently changed the hash for every existing finding and broke the v0.4.2 → v0.4.3 backwards-compat claim in my own changelog. Pinned by a new test that asserts the specific v0.4.2-form hash for a salient-less finding.
+- **P0**: TOML parser no longer rejects valid subtable headers repeated under separate array-of-tables entries. `[[fruits]] [fruits.physical] [[fruits]] [fruits.physical]` now parses correctly — each `[[fruits]]` entry resets the "already defined" status of subtable paths under that AOT. My v0.4.2 `definedTables` guard was global per-file when it should have been scoped to the current AOT entry.
+- `lineOfJsonStringValue` no longer matches occurrences in key position. Searching for value `"command"` in `{"command":"npx", "args":["command"]}` now returns the array-element line, not the key. Negative lookahead `(?!\s*:)` after the closing quote.
+- `lineOfTomlKey` now finds top-level dotted keys. `lineOfTomlKey('a.b.c = 1', 'a.b.c')` returns 1 instead of 0 — the dotted-key check was gated behind `inTargetTable` which is false at file root.
+
+### Changed
+- `package-lock.json` resynced to 0.4.4. Was drifting at 0.4.2 because previous releases bumped `package.json` without running `npm install` to refresh the lockfile.
+
+### Tests
+- 6 new cases: pinned v0.4.2-form fingerprint hash, JSON value-vs-key disambiguation (+ colon-in-value sanity check), top-level dotted TOML keys, AOT subtable repeat across entries (+ within-entry duplicate still rejected). 108 total (up from 102).
+
 ## [0.4.3] — 2026-05-22
 
 Third Gemini-inspection round caught one confirmed bug, one disguised-as-suggestion bug, and three feature opportunities. Both bugs fixed here; the feature work is queued for v0.5.0.

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,11 +91,30 @@ 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? }`; `value` and `json` reference the same parsed object — `json` is kept as a deprecated alias.
+- `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
-- `readTomlObject(path)` — TOML reader (sections, arrays of tables, inline tables, multi-line strings, dotted/quoted keys). Returns `{ value, toml, text, parseError? }`; `value` and `toml` reference the same parsed object — `toml` is kept as a deprecated alias.
-- `parseToml(text)` — same exposed for text
+- `readTomlObject(path)` — TOML reader (sections, arrays of tables, inline tables, multi-line strings, dotted/quoted keys). Returns `{ value, toml, text, parseError? }`. Errors are also `ConfigParseError` with `line`/`column`/`rawOffset` when resolvable.
+- `parseToml(text)` — same exposed for text; throws raw `Error` (file-level wrapping happens in `readTomlObject`)
+- `ConfigParseError` — structured parse error with `line`, `column`, `rawOffset`, and `cause`. Lets downstream tools emit a `*.config_syntax_error` finding pointing at the exact spot.
+- `lineColumnOfOffset(text, offset)` — convert a 0-based byte offset to 1-based `{ line, column }`. Useful when a hand-rolled scanner exposes byte positions and a `Finding.location` needs line/column.
 
 ### Line locators
 - `lineOfJsonKey(text, key, scope?)` — 1-based line of `"key":`, optionally scoped to a byte range
@@ -81,16 +122,23 @@ 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`)
+- `tokenizeShellDeep(command)` — recursively extracts commands nested inside `$(…)`, backticks, and `bash -c "…"` / `sh -c "…"` / `python -c "…"` payloads. Closes the obfuscation vector where an agent hides `curl evil | sh` inside `echo $(…)`. Single-quoted text is left untouched (literal, per shell semantics).
 - `getCommandHead(subcommand)` — extract the leading verb after tokenization
 
 ### GitHub Action helpers
 - `rankSeverity(s)` — numeric rank `low=1, medium=2, high=3, critical=4` (matches the schema's closed severity enum; there is no `none`)
 - `passesSeverityThreshold(s, threshold)`, `anyAtOrAbove(findings, threshold)` — fail-on plumbing
 - `emitFindingAnnotation(f)` — render a Finding as a `::warning file=…,line=…,title=…::…` GitHub workflow annotation
+- `generateWorkflowSummary(findings, opts?)` — Markdown summary suitable for `$GITHUB_STEP_SUMMARY`. Groups findings by severity in collapsible `<details>` blocks so 100% of findings remain visible even when GHA's inline-annotation cap (~10 per level, 50 per run) silently drops the rest
 
 ### Test fixtures (`agent-gov-core/test-utils`)
 Secondary entry point used by consumer test suites. Zero overhead in production — only loaded when test files import it.

package/dist/action.d.ts

@@ -28,4 +28,34 @@ export declare function anyAtOrAbove(findings: readonly Finding[], threshold: Se
  * // → '::error file=.github/workflows/ci.yml,line=12,title=[capability_echo.workflow_permission_write] high::Workflow grants contents: write to PR-triggered jobs.'
  */
 export declare function emitFindingAnnotation(finding: Finding): string;
+export interface WorkflowSummaryOptions {
+    /** Top-level heading. Default: `Findings`. */
+    title?: string;
+    /** Cap per severity group; remaining count rendered as `(+N more)`. Default: 100. */
+    perSeverityLimit?: number;
+    /** Truncate message to this many characters (with `…` suffix). Default: 200. */
+    messageMaxLength?: number;
+}
+/**
+ * Render a Markdown summary of findings suitable for writing to
+ * `$GITHUB_STEP_SUMMARY`. GitHub Actions caps inline annotations (~10 per
+ * level, 50 per run) and silently drops the rest; the step summary has no
+ * such cap, so a Markdown table guarantees that 100% of findings are visible
+ * in the workflow's run summary page even when annotations are truncated.
+ *
+ * Findings are grouped by severity (critical → high → medium → low) inside
+ * collapsible `<details>` blocks. Each row carries file, line, kind, and a
+ * length-capped message. Pipe characters in message text are escaped so they
+ * don't break Markdown table rendering.
+ *
+ * @example
+ * import { generateWorkflowSummary } from 'agent-gov-core';
+ * import { appendFileSync } from 'node:fs';
+ *
+ * const md = generateWorkflowSummary(findings, { title: 'CapabilityEcho findings' });
+ * if (process.env.GITHUB_STEP_SUMMARY) {
+ *   appendFileSync(process.env.GITHUB_STEP_SUMMARY, md);
+ * }
+ */
+export declare function generateWorkflowSummary(findings: readonly Finding[], options?: WorkflowSummaryOptions): string;
 //# sourceMappingURL=action.d.ts.map

package/dist/action.js

@@ -76,4 +76,102 @@ function escapeProperty(s) {
         .replace(/:/g, '%3A')
         .replace(/,/g, '%2C');
 }
+/**
+ * Render a Markdown summary of findings suitable for writing to
+ * `$GITHUB_STEP_SUMMARY`. GitHub Actions caps inline annotations (~10 per
+ * level, 50 per run) and silently drops the rest; the step summary has no
+ * such cap, so a Markdown table guarantees that 100% of findings are visible
+ * in the workflow's run summary page even when annotations are truncated.
+ *
+ * Findings are grouped by severity (critical → high → medium → low) inside
+ * collapsible `<details>` blocks. Each row carries file, line, kind, and a
+ * length-capped message. Pipe characters in message text are escaped so they
+ * don't break Markdown table rendering.
+ *
+ * @example
+ * import { generateWorkflowSummary } from 'agent-gov-core';
+ * import { appendFileSync } from 'node:fs';
+ *
+ * const md = generateWorkflowSummary(findings, { title: 'CapabilityEcho findings' });
+ * if (process.env.GITHUB_STEP_SUMMARY) {
+ *   appendFileSync(process.env.GITHUB_STEP_SUMMARY, md);
+ * }
+ */
+export function generateWorkflowSummary(findings, options = {}) {
+    const title = options.title ?? 'Findings';
+    const perGroupLimit = options.perSeverityLimit ?? 100;
+    const messageMax = options.messageMaxLength ?? 200;
+    if (findings.length === 0) {
+        return `# ${title}\n\nNo findings.\n`;
+    }
+    const groups = {
+        critical: [],
+        high: [],
+        medium: [],
+        low: [],
+    };
+    for (const f of findings)
+        groups[f.severity].push(f);
+    const counts = {
+        critical: groups.critical.length,
+        high: groups.high.length,
+        medium: groups.medium.length,
+        low: groups.low.length,
+    };
+    const lines = [];
+    lines.push(`# ${title}`, '');
+    lines.push(`**Total**: ${findings.length} finding${findings.length === 1 ? '' : 's'} — ` +
+        `${counts.critical} critical, ${counts.high} high, ` +
+        `${counts.medium} medium, ${counts.low} low`);
+    lines.push('');
+    const severityOrder = ['critical', 'high', 'medium', 'low'];
+    for (const severity of severityOrder) {
+        const group = groups[severity];
+        if (group.length === 0)
+            continue;
+        const shown = group.slice(0, perGroupLimit);
+        const overflow = group.length - shown.length;
+        lines.push(`<details${severity === 'critical' || severity === 'high' ? ' open' : ''}>`);
+        lines.push(`<summary><strong>${group.length} ${severity}</strong></summary>`);
+        lines.push('');
+        lines.push('| File | Line | Kind | Message |');
+        lines.push('|------|------|------|---------|');
+        for (const f of shown) {
+            lines.push('| ' +
+                [
+                    escapeMarkdownTableCell(f.location?.file ?? '—'),
+                    f.location?.line ?? '—',
+                    escapeMarkdownTableCell(f.kind),
+                    escapeMarkdownTableCell(truncate(f.message, messageMax)),
+                ].join(' | ') +
+                ' |');
+        }
+        if (overflow > 0) {
+            lines.push(`| _(+${overflow} more ${severity} finding${overflow === 1 ? '' : 's'})_ | | | |`);
+        }
+        lines.push('');
+        lines.push('</details>');
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+function truncate(s, max) {
+    if (s.length <= max)
+        return s;
+    return s.slice(0, Math.max(1, max - 1)) + '…';
+}
+function escapeMarkdownTableCell(s) {
+    // Escape HTML control characters so a finding message containing
+    // `</summary>` or `<h1>` can't break out of the `<details>` block we
+    // emit around each severity group. GitHub sanitizes script execution,
+    // but unescaped tags still let an attacker manipulate the visual layout
+    // of the workflow summary (collapse other groups, inject misleading
+    // headings, etc.).
+    return String(s)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/\|/g, '\\|')
+        .replace(/\r?\n/g, ' ');
+}
 //# sourceMappingURL=action.js.map

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/finding.js

@@ -100,11 +100,14 @@ export function fingerprintFinding(finding) {
         fileNormalized,
         finding.location?.line ?? '',
         finding.location?.column ?? '',
-        // salientKey lets multiple distinct findings at the same (kind, file, line)
-        // site keep separate fingerprints. Empty string when absent so the hash
-        // shape is stable across findings that don't need a discriminator.
-        finding.salientKey ?? '',
     ];
+    // salientKey is appended ONLY when present. Appending `?? ''` would add a
+    // trailing pipe even for findings without salientKey, breaking the v0.4.2
+    // hash. This way pre-0.4.3 fingerprints stay stable for findings that
+    // never set salientKey, while new findings with one stay distinct.
+    if (finding.salientKey !== undefined) {
+        parts.push(finding.salientKey);
+    }
     return createHash('sha256').update(parts.join('|')).digest('hex').slice(0, 16);
 }
 const FINDING_ALLOWED_KEYS = new Set([

package/dist/index.d.ts

@@ -4,10 +4,20 @@ export type { JsonObjectWithSource } from './jsonc.js';
 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';
 export { normalizeMcpCommand } from './mcp.js';
-export { tokenizeShell, getCommandHead } from './shell.js';
-export { rankSeverity, passesSeverityThreshold, anyAtOrAbove, emitFindingAnnotation, } from './action.js';
+export { tokenizeShell, tokenizeShellDeep, getCommandHead } from './shell.js';
+export type { WorkflowSummaryOptions } from './action.js';
+export { rankSeverity, passesSeverityThreshold, anyAtOrAbove, emitFindingAnnotation, generateWorkflowSummary, } from './action.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,8 +1,13 @@
 export { SEVERITIES, TOOL_KINDS, isSeverity, isToolKind, isNamespacedKind, kind, createFinding, fingerprintFinding, validateFinding, } from './finding.js';
 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, getCommandHead } from './shell.js';
-export { rankSeverity, passesSeverityThreshold, anyAtOrAbove, emitFindingAnnotation, } from './action.js';
+export { tokenizeShell, tokenizeShellDeep, getCommandHead } from './shell.js';
+export { rankSeverity, passesSeverityThreshold, anyAtOrAbove, emitFindingAnnotation, generateWorkflowSummary, } from './action.js';
 //# sourceMappingURL=index.js.map