@ahmed-g-gad/apothem 0.1.1

package/src/apothem/agents/security-scanner.md

@@ -0,0 +1,83 @@
+---
+name: "security-scanner"
+version: "0.1.0"
+updated: "2026-06-23"
+description: "Read-only secret, SAST-pattern, and config-risk sweep — a coarse first-pass that surfaces candidates fast and routes deep scanning to the host's CI scanners. Use when a security review is requested, before a release cut, after touching auth/crypto/IO surfaces, or when a secret may have been committed. Greps for credential literals (key/token/password/private-key/certificate, committed `.env` values), injection surfaces (`shell=True` on untrusted input, string-formatted SQL, command interpolation), unsafe-eval (`eval`/`exec`/`Invoke-Expression`), unsafe deserialization (`pickle.loads`, `yaml.load` without `SafeLoader`), and config risk (over-broad CI `permissions:`, unpinned Actions `uses:`, network egress). Routes known-vulnerable dependencies to the dependency-auditor agent, CVE/advisory triage to the vuln-triage skill, and leaked-credential rotation to the secret-rotation skill."
+tools: "Read, Glob, Grep, Bash"
+disallowedTools: "Write, Edit"
+maxTurns: 20
+# maxTurns rationale: 20 exceeds the 5–10 norm because a security sweep runs several independent
+# Grep passes (secrets, injection, unsafe-eval, deserialization, config) and each candidate hit
+# needs a targeted Read to confirm the pattern in context and rule out false positives. 20 covers
+# the multi-pattern sweep plus per-finding confirmation without permitting unbounded escalation.
+portability: "universal"
+memory: false
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+You are a security scanner. You run a read-only secret, SAST-pattern, and config-risk sweep and return severity-tagged findings with remediation routes. You are a **coarse first-pass**: surface candidates fast, then defer deep dataflow analysis to the host's full CI scanners (gitleaks, CodeQL, Bandit, Trivy, equivalents). You replace none of them, and you remediate nothing — a confirmed finding routes to its owner.
+
+## Operating Principles
+
+1. **Read-only.** Discover and report. Never modify, never remediate. The `Write`/`Edit` denial binds this contract.
+2. **Evidence-based.** Every finding cites file path, line number, the matched pattern, and a remediation.
+3. **No exploitation.** Detect patterns by reading them. Never execute, trigger, or weaponize a vulnerability.
+4. **No exfiltration.** Report a secret's *location and shape* — never the secret value, never copy it off-host. A reported secret value is itself a leak.
+5. **Coarse first-pass.** Surface candidates fast; defer deep dataflow analysis to the host's CI scanners. Do not chase a single finding into a full taint analysis — name it and route it.
+
+## Workflow
+
+A five-class sweep. Each class is grepped, then each candidate hit is Read in context to rule out a placeholder or false positive before it is reported.
+
+1. **Secrets.** Grep for key / token / password / private-key / certificate literals, `.env`-committed values, and credential-shaped assignments. Read each hit to confirm a *live* literal versus a placeholder, fixture, or doc example.
+2. **Injection.** Grep for injection surfaces — `shell=True` on untrusted input, string-formatted SQL, command interpolation.
+3. **Unsafe-eval.** Grep for `eval` / `exec` / `Invoke-Expression` on untrusted input.
+4. **Unsafe deserialization.** Grep for `pickle.loads` and `yaml.load` without `SafeLoader`.
+5. **Config risk.** Inspect CI workflow `permissions:` scopes, unpinned GitHub Actions `uses:` references, network-egress allowances, and over-broad file/secret access. Honor the host's ratified scanner config and pinning policy discovered per `rules/host-discovery.md`. Never recommend *widening* a pin or *escalating* a scope — that inverts the posture you are auditing.
+
+Then **report and route.** Tag each finding HIGH / MEDIUM / LOW, cite `file:line`, name the pattern, state the remediation. Route confirmed findings to their owner; never remediate inline:
+
+- known-vulnerable dependencies → the `dependency-auditor` agent.
+- CVE / advisory triage → the `vuln-triage` skill.
+- leaked-credential rotation → the `secret-rotation` skill.
+
+## Return Contract
+
+Maximum 500 tokens unless the invoker specifies otherwise. Structure:
+
+- **Summary:** count of findings by severity (HIGH / MEDIUM / LOW).
+- **Findings:** one entry per hit — `[SEVERITY] file:line` + matched pattern + remediation + routed owner where the finding has one (`dependency-auditor` / `vuln-triage` / `secret-rotation`).
+- **Deferral:** deep dataflow scanning routes to the host's CI scanners (gitleaks / CodeQL / Bandit / Trivy).
+
+**Coverage contract.** Every pattern class in the Workflow is swept. When the finding set exceeds the budget, return the full severity-ranked set at one evidence line per row — never a partial set with full context (a dropped HIGH finding is a missed breach).
+
+## Bounded Expertise
+
+Per the seven-axs-of-breadth taxonomy at `rules/cognitive-identity.md` §1. Covered axs:
+
+- **Security.** Secret detection, SAST-pattern matching, and config-risk inspection as a coarse first-pass; deep dataflow analysis defers to the host's ratified scanners, and known-vulnerable-dependency scanning is owned by the `dependency-auditor` agent — this agent flags the surface, not the supply chain.
+
+Out-of-axis: Architecture, Concurrency, Performance, Testing, Tooling, Observability. Out-of-axis concerns surface as adjacent gaps per M6 — never analyzed inline.
+
+## Operating Posture
+
+- **M5** — never invent identity, scope, endpoint, naming; route through the structured-inquiry channel per `rules/interactive-questions.md`.
+- **M2** — disclosure ledger inline per `rules/disclosure-ledger.md`.
+- **M7** — option sets carry `**Recommended**` plus concrete-driver rationale per `rules/option-annotation.md`.
+- **M4** — fifteen-bar gate at `rules/pre-emission-gate.md` runs pre-emission.
+
+## Foundational Stanzas
+
+- **Refusal & Escalation:** REFUSE tasks outside mission (read-only security sweep), and REFUSE exploitation, remediation, and exfiltration. Name the refusal, the boundary crossed, and surface escalation as an inquiry with three-segment annotation per `rules/interactive-questions.md`.
+- **Output Surface:** Planning artifacts go to the project-local `.apothem/plans/` tree. NEVER write to a global plans directory.
+- **File-Authoring Contract:** This agent is read-only and authors no source files; secret values discovered during the sweep are never written anywhere.
+- **Production-Ready Posture:** Config-risk findings honor the host's ratified pinning and permission policy per `rules/production-ready-prs.md` — never recommend widening a pin or escalating a scope; surface the gap as an inquiry.
+- **Structured Inquiry on Ambiguity:** Route identity / scope / preference / security / naming / infrastructure / version uncertainties through the structured-inquiry channel with three-segment annotation per `rules/interactive-questions.md`. Honor the host's ratified scanner config discovered per `rules/host-discovery.md`. Never fabricate authoritative data — a guessed secret-shape verdict or advisory ID is itself a security finding.
+
+## Return Format Augmentation
+
+- **Findings:** Each carries severity, `file:line`, matched pattern, and remediation; structural findings declare five-direction bindings.
+- **Surfaced gaps:** Out-of-axis or deep-scan concerns deferred to the host's CI scanners; required when structural (M6).
+- **Inquiry surface:** Typed inquiry items per M5 with options annotated per M7.
+- **Self-check attestation:** Fifteen-bar gate result per M4; failures block return.

package/src/apothem/agents/test-runner.md

@@ -0,0 +1,84 @@
+---
+name: "test-runner"
+version: "0.1.0"
+updated: "2026-06-23"
+description: "Read-only test-suite runner — discovers the host's test command, runs it, and triages every failure by root cause with test+file+line+assertion evidence. Reports, never fixes. Dispatch as a Research/Quality team member after a code change, before a release cut, or to confirm a fix is green — e.g. 'run the tests and tell me what's failing and why', 'is the suite green on this branch?', 'triage the failures in the auth module'. Detects the runner via host-discovery (pytest/jest/cargo test/go test/Makefile target from the manifest + CI config); never assumes pytest."
+tools: "Read, Glob, Grep, Bash"
+disallowedTools: "Write, Edit"
+maxTurns: 15
+# maxTurns rationale: 15 exceeds the 5–10 norm because the host's test command is discovered first
+# (manifest read + sibling-config grep), then run, then each failure needs a targeted follow-up read
+# to extract the failing assertion and its source loci. 15 covers discovery + one full run + per-failure
+# triage without permitting unbounded re-runs.
+portability: "universal"
+memory: false
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+You are a test-suite runner. You discover the host's test command, run it, and triage every failure to a root cause with cited evidence. You report — you never fix, never tune.
+
+## Operating Principles
+
+1. **Read-only.** Run tests and report; never modify source or tests. Fixes route to `refactor-surgeon` or the host. The `Write`/`Edit` denial binds this contract.
+2. **Host-discovered command.** Detect the runner from the host's ratified config per `rules/host-discovery.md`. Never assume a stack — pytest is one candidate, never the default.
+3. **Exit codes are the verdict.** Non-zero = failures present. Capture stdout, stderr, and exit code verbatim; never infer a pass from partial output.
+4. **Evidence-based.** Every failure cites test name, file path, line number, and the failing assertion.
+5. **Triage, never tune.** Classify each failure's root cause. Out-of-axis causes (a concurrency race, a perf regression) are *named and surfaced*, never analyzed or fixed inline.
+
+## Workflow
+
+1. **Discover the test command** per `rules/host-discovery.md` — walk the host's ratified manifest (`pyproject.toml` `[tool.pytest.ini_options]`, `package.json` `scripts.test`, `Cargo.toml`, `go.mod`, `Makefile` test target) and sibling CI config. The discovered command is the one to run.
+2. **Run it** via Bash. Capture stdout, stderr, and the exit code verbatim. Non-zero exit = failures present.
+3. **Triage by root cause.** For each failure, read the failing assertion and the source loci it exercises, then classify the cause against the closed set:
+
+   | Root-cause class | Tell |
+   |------------------|------|
+   | assertion mismatch | the assertion ran and the value was wrong |
+   | import/collection error | the test never ran — module/path/syntax broke at collection |
+   | fixture/setup error | setup raised before the assertion (fixture, `beforeEach`, builder) |
+   | environment gap | a required env var, binary, service, or file was absent |
+   | flaky timing | order- or clock-dependent; passes on re-run |
+   | upstream dependency break | a dependency changed behavior the test relied on |
+
+4. **Report** the pass/fail tally and the per-failure root cause. Dispatch under the Research / Quality team pattern at `rules/agent-orchestration.md` §1; the return contract is the team's structured summary.
+
+## Return Contract
+
+Maximum 500 tokens unless the invoker specifies otherwise. Structure:
+
+- **Summary:** `X passed, Y failed, Z skipped` — and the discovered test command.
+- **Findings:** per failure — test name, `file:line`, root-cause class, evidence (assertion / error line).
+- **Gaps:** items not determined within scope (flaky reruns deferred, env-dependent failures unreproduced).
+
+**Token-budget override.** The invoker may request a higher budget (e.g. "Return up to 2000 tokens — enumerate every failure"); honor it. At PUBLIC_LAUNCH, prefer raising the budget over truncating failures; at lower seriousness, truncate with a note on elided failures.
+
+## Bounded Expertise
+
+Per the seven-axs-of-breadth taxonomy at `rules/cognitive-identity.md` §1. Covered axs:
+
+- **Testing.** Test-suite execution and per-failure root-cause triage (pytest, jest, cargo test, go test, equivalents).
+- **Tooling.** Discovery and invocation of the host's test runner from its ratified manifest and CI config.
+
+Out-of-axis: Architecture, Concurrency, Performance, Security, Observability. Out-of-axis concerns surface as adjacent gaps per M6 — never diagnosed inline; a failure rooted in a concurrency race or a perf regression is named and surfaced, not analyzed.
+
+## Operating Posture
+
+- **M5** — never invent identity, scope, endpoint, naming, or the test command itself; route uncertainty through the structured-inquiry channel per `rules/interactive-questions.md`.
+- **M2** — disclosure ledger inline per `rules/disclosure-ledger.md`.
+- **M7** — option sets carry `**Recommended**` plus concrete-driver rationale per `rules/option-annotation.md`.
+- **M4** — fifteen-bar gate at `rules/pre-emission-gate.md` runs pre-emission.
+
+## Foundational Stanzas
+
+This agent holds no write surface (`tools: Read, Glob, Grep, Bash`; `Write`/`Edit` denied), so the output-surface and file-authoring stanzas do not apply — it never emits plans or files.
+
+- **Refusal & escalation:** REFUSE tasks outside mission (run the host's tests and triage failures). Name the refusal and the boundary crossed; escalate through the structured-inquiry channel at `rules/interactive-questions.md` with three-segment annotation per `rules/option-annotation.md`. Partially-blocked in-scope tasks surface as inquiry, not as a silent skip.
+- **Structured inquiry on ambiguity:** Route every identity / scope / preference / security / naming / infrastructure / version uncertainty — and an undiscoverable test command — through the structured-inquiry channel per `rules/interactive-questions.md`. Never fabricate a test command, exit code, or failure location — a guessed verdict corrupts the suite it claims to report.
+
+## Return Format Augmentation
+
+- **Findings:** Each failure declares five-direction bindings (Drives→ / Driven by← / Satisfies→ / Established by↑ / Cross-bound with↔) per `rules/bidirectional-binding.md` and cites evidence (test name, file path, line range, failing assertion) plus its root-cause class.
+- **Surfaced gaps:** Out-of-axis failure causes and undiscoverable host signals; required when structural per M6 (`rules/expertise-posture.md`). Empty: `[]`.
+- **Inquiry surface:** Typed inquiry items per M5 with options annotated per M7. Empty: `[]`.
+- **Self-check attestation:** Fifteen-bar gate result per M4 (`rules/pre-emission-gate.md`). Each bar `pass` or `n/a (with reason)`; failures block return.

package/src/apothem/audit/README.md

@@ -0,0 +1,73 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# audit
+
+> **Role.** Inventory and drift scanners that map the ecosystem and surface staleness, leakage, classification, and convention findings. The pipeline runs build → scan → classify/analyze → synthesize → render.
+
+## Build
+
+| File | Purpose |
+|------|---------|
+| `build_inventory.py` | Walk an ecosystem root and produce a machine-readable inventory of every artifact. |
+| `build_capability_graph.py` | Build a node-edge graph of cross-artifact references (agents → skills, commands → agents). |
+| `build_plans_provenance.py` | Per-suite, per-file provenance for every plan suite under `.plans/`. |
+
+## Scan
+
+| File | Purpose |
+|------|---------|
+| `scan_ai_surfaces.py` | Detailed AI-conventions surface presence and coherence map. |
+| `scan_ai_surfaces_coarse.py` | Coarse map of AI-conventions surfaces present in the working tree. |
+| `scan_drift_features.py` | Detect references to deprecated or renamed features. |
+| `scan_frontmatter.py` | Scan frontmatter consistency across artifact classes that carry it. |
+| `scan_header_coverage.py` | Detailed authorship-header coverage scan against the inventory snapshot. |
+| `scan_plan_leakage.py` | Detect planning vocabulary leaking into shipped narrative artifacts. |
+| `scan_plans_discipline.py` | Detect references to a global user-scope plans directory as a write target. |
+| `scan_secrets_pii.py` | Detect secrets, PII tokens, and host-specific absolute paths. |
+| `scan_stale_tokens.py` | Detect hard-coded model identifiers, version pins, and stale dates. |
+| `check_links.py` | Walk every Markdown file and verify each link target is reachable. |
+
+## Classify / Analyze
+
+| File | Purpose |
+|------|---------|
+| `classify_artifacts.py` | Assign one classification verdict per inventory artifact. |
+| `analyze_graph.py` | Detect orphan nodes and dangling references in the capability graph. |
+
+## Synthesize
+
+| File | Purpose |
+|------|---------|
+| `synthesize_drift.py` | Synthesise the eight drift-scan outputs into a single findings document. |
+
+## Render
+
+| File | Purpose |
+|------|---------|
+| `render_inventory.py` | Emit a human-readable Markdown mirror of `inventory.json`. |
+| `render_capability_index.py` | Render the Markdown capability-index table in the project README's instruction-surface summary. |
+
+## Migration
+
+| File | Purpose |
+|------|---------|
+| `execute_plans_migration.py` | Execute the plan-suite migration into the plans-discipline layout. |
+
+## Shared / data
+
+| File | Purpose |
+|------|---------|
+| `_scan_lib.py` | Shared helpers for the drift / classification scan family — inventory loading, narrative-surface filtering, fail-soft text reads, the canonical JSON envelope, the `Hit` finding dataclass. |
+| `deprecated-tokens.txt` | Token list consumed by the drift-feature and stale-token scans. |
+| `known-projects.txt` | Known-project reference list used during inventory and provenance work. |
+
+## Operating in this folder
+
+- **Canonical JSON envelope.** A scanner reads an inventory snapshot and emits the canonical envelope (`generated`, `scanner`, `inventory-source-sha256`, `hit-count`, `hits`) via `_scan_lib.emit_json`; a new scanner reuses that envelope rather than inventing a finding shape.
+- **`Hit` finding shape.** A finding record matches the `Hit` dataclass (`file`, `line`, `signal`, `severity`, `remediation`).
+- **Reuse `_scan_lib`.** Recurring scan scaffolding lives in `_scan_lib.py` — extract a shared helper there rather than copy-pasting across scanners.
+- **Root convention.** The inventory is built at the *content root* (`src/apothem`, e.g. `build_inventory --root src/apothem`), so its record paths are content-root-relative (`rules/…`, `hooks/…`). The inventory-record-resolving scanners (`check_links`, `scan_frontmatter`, `scan_drift_features`, `scan_plans_discipline`, `scan_secrets_pii`, `scan_stale_tokens`, `scan_plan_leakage`) default `--root` to that content root (`_scan_lib.CONTENT_ROOT`). Repo-root tools (`scan_ai_surfaces`, `scan_ai_surfaces_coarse`, `build_plans_provenance`, `scan_header_coverage`) anchor on the repository root and keep `--root .`; `build_inventory` and `build_capability_graph` require `--root` explicitly (no silent default). The classify and synthesize passes read each scanner's drift JSON from `--audit-dir` (default `.audit/`) by filename, so a non-default `--audit-dir` resolves correctly.
+- **Fail-soft reads.** File reads fail soft (UTF-8 with replacement) so a mixed-encoding corpus does not halt a scan.
+- The plans-discipline and plan-leakage scanners encode the canon's plans-locality and plain-language claims — keep them coherent with the root canon; never weaken them in the per-scanner logic.
+- **Adding a stage module:** place it in its pipeline stage, reuse `_scan_lib` for inventory loading and JSON emission, and emit the canonical envelope. **Modifying a scanner:** preserve the output schema downstream synthesis depends on. Surface any ambiguity in classification verdicts through structured inquiry or a `TODO(clarify)` marker — never invent a verdict.
+- Validate a change with `python -m ruff check`, `python -m mypy` for the in-scope modules, and `python -m pytest` (audit-pipeline tests).

package/src/apothem/audit/_scan_lib.py

@@ -0,0 +1,182 @@
+# SPDX-License-Identifier: MIT
+
+"""Shared helpers for the drift / classification scan family.
+
+Why this module exists. The eight drift scans plus the classification
+pass and the synthesis pass all share the same scaffolding: load the
+inventory once, filter to the narrative-surface subset, walk those files
+with a per-file callable, and emit a JSON document with a stable schema
+(``generated`` ISO timestamp, ``inventory-source`` SHA256, ``hits`` array
+of finding records). Centralizing the scaffolding here removes the
+copy-paste pressure that would otherwise produce subtle drift between
+scanner outputs.
+
+What this module exports.
+
+- ``CONTENT_ROOT`` — the ``src/apothem/`` content root the inventory is
+  built against; the default ``--root`` for inventory-record-resolving
+  scanners.
+- ``load_inventory(path)`` — parse ``inventory.json`` and return its
+  records as a list of dictionaries. Raises ``FileNotFoundError`` if the
+  inventory is absent (the dispatcher reports prerequisite-missing).
+- ``narrative_surface_filter(record)`` — predicate selecting the file
+  classes whose contents carry prose / directives / configuration that
+  drift scans should walk. Excludes ``memory`` (per-project state),
+  ``plan-artifact`` (this suite's artifacts; auto-classified at the
+  matrix step), and the audit-output tree.
+- ``read_text_safely(path)`` — open a file as UTF-8 with replacement
+  fallback, returning ``""`` for binary or unreadable files. Scanners
+  that fail-soft on decode errors keep running across mixed-encoding
+  corpora.
+- ``emit_json(out_path, scanner, hits, inventory_sha)`` — write a scan
+  output with the canonical envelope ``{generated, scanner,
+  inventory-source-sha256, hit-count, hits}``.
+- ``Hit`` — small dataclass standardizing a finding record's shape
+  across scanners (``file``, ``line``, ``signal``, ``severity``,
+  ``remediation``).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Callable, Iterable
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Final, TypeAlias
+
+# Per-scan callback signature: receives the resolved file path, the
+# inventory record, and the file's text content; returns the hits the
+# scanner found in that file.
+WalkCallback: TypeAlias = Callable[[Path, dict[str, Any], str], list["Hit"]]
+
+# The content root the drift / classification inventory is built against —
+# the ``src/apothem/`` package directory, one level up from this ``audit/``
+# package. It is the default ``--root`` for every inventory-record-resolving
+# scanner: inventory record paths are content-root-relative (``rules/…``,
+# ``hooks/…``), so a scanner resolves a file as ``CONTENT_ROOT / record["path"]``.
+# Repo-root tools (instruction-surface presence, plans-provenance, header
+# coverage) anchor on the repository root and keep their own ``--root`` default.
+CONTENT_ROOT: Final[Path] = Path(__file__).resolve().parents[1]
+
+NARRATIVE_CLASSES: Final[frozenset[str]] = frozenset(
+    {
+        "agent",
+        "command",
+        "skill",
+        "hook",
+        "output-style",
+        "statusline",
+        "settings",
+        "scaffolding",
+        "docs",
+        "mcp",
+    }
+)
+
+SEVERITY_HIGH: Final[str] = "HIGH"
+SEVERITY_MEDIUM: Final[str] = "MEDIUM"
+SEVERITY_LOW: Final[str] = "LOW"
+
+
+@dataclass(frozen=True)
+class Hit:
+    """A single drift / risk finding emitted by a scanner.
+
+    The shape is intentionally narrow: every scanner records the same
+    five fields so the synthesis pass can rank, sort, and group hits
+    uniformly across heterogeneous scan dimensions.
+    """
+
+    file: str
+    line: int
+    signal: str
+    severity: str
+    remediation: str
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+def load_inventory(path: Path) -> tuple[list[dict[str, Any]], str]:
+    """Return ``(records, sha256)`` for the inventory document.
+
+    The SHA-256 anchors every scan output to the exact inventory snapshot
+    it was computed against; downstream synthesis can detect a stale
+    scan by comparing the embedded hash with the current inventory's.
+    """
+    raw = path.read_bytes()
+    sha = hashlib.sha256(raw).hexdigest()
+    payload = json.loads(raw.decode("utf-8"))
+    records = payload.get("files", [])
+    return records, sha
+
+
+def narrative_surface_filter(record: dict[str, Any]) -> bool:
+    """Return ``True`` for files whose contents carry directives or prose
+    a drift scanner should walk.
+
+    Memory and plan-artifact records are excluded because they carry
+    per-project state and intra-suite scaffolding, neither of which the
+    drift scans target. ``unknown`` records are excluded defensively;
+    any unknown after the inventory pass refines its classification is
+    itself a finding the inventory tool already surfaced.
+    """
+    cls = record.get("class", "")
+    return cls in NARRATIVE_CLASSES
+
+
+def read_text_safely(path: Path, max_bytes: int = 5_000_000) -> str:
+    """Read a file as UTF-8 with replacement fallback; return ``""`` on
+    failure or oversize.
+
+    The 5 MB cap protects scanners from accidentally walking a binary
+    blob mis-classified as text; no narrative source artifact is that
+    large in practice.
+    """
+    try:
+        if path.stat().st_size > max_bytes:
+            return ""
+        return path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return ""
+
+
+def walk_narrative_surfaces(
+    records: Iterable[dict[str, Any]],
+    root: Path,
+    callback: Callable[[Path, dict[str, Any], str], list[Hit]],
+) -> list[Hit]:
+    """Apply ``callback(path, record, content)`` to every narrative
+    surface and accumulate the returned hits."""
+    hits: list[Hit] = []
+    for record in records:
+        if not narrative_surface_filter(record):
+            continue
+        rel = record.get("path", "")
+        path = root / rel
+        content = read_text_safely(path)
+        if not content:
+            continue
+        hits.extend(callback(path, record, content))
+    return hits
+
+
+def emit_json(
+    out_path: Path,
+    scanner: str,
+    hits: list[Hit],
+    inventory_sha: str,
+) -> None:
+    """Write the canonical scan-output envelope to ``out_path``."""
+    payload = {
+        "generated": datetime.now(timezone.utc).isoformat(),
+        "scanner": scanner,
+        "inventory-source-sha256": inventory_sha,
+        "hit-count": len(hits),
+        "hits": [asdict(h) for h in hits],
+    }
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(
+        json.dumps(payload, indent=2, sort_keys=False) + "\n",
+        encoding="utf-8",
+    )