feat(audit): okf audit — corpus-level trust, freshness and lifecycle query

CHANGELOG.md

@@ -10,6 +10,11 @@ and this project adheres to
 
 ### Added
 
+- **`okf audit`** — a corpus-level query over a bundle's trust (§5.3), lifecycle
+  (§5.4) and staleness (§5.5) signals: counts plus a filterable worklist, with
+  `--stale`, `--trust`, `--status`, `--type`, `--as-of` and `--json`. Backed by
+  the new `ConceptAudit` in the core library and exposed to agents as the
+  read-only `okf_audit` tool.
 - **`okf render <bundle> --out <dir>`** generates a self-contained, browsable
   HTML site from a bundle: one page per concept (frontmatter table + rendered
   body), a generated index, navigable cross-links with broken links flagged,

CLAUDE.md

@@ -33,10 +33,11 @@ Requires .NET SDK 10.0+. CI (ci.yml) runs build+test on Linux/Windows/macOS, `do
 
 - **`src/OKF4net/`** — the library. One file per spec concern, following the OKF reference implementation's structure: `ConceptId` (§2), `Bundle` (§3, permissive loading — parse failures go into `Bundle.ParseErrors`, never abort), `OkfDocument`/`Frontmatter` (§4), `Links.cs`/`LinkScanner` (§6, legacy citations §13.1), `IndexGenerator` (§8), `ChangeLog` (§9), `Validate.cs`/`BundleValidator` (§11). The README has the full spec-section → type mapping table.
   - `ConceptSearch` — the single shared full-text scorer (title x3, tags/description x2, body x1) used by both `OKF4net.Agents` (`okf_search`/context provider) and `OKF4net.Catalog` (`OkfBundleKnowledgeSource`, `FileMemoryStore`); do not fork a second scorer in either consumer.
+  - `Audit.cs` — `ConceptAudit`, the single shared corpus-level query behind both `okf audit` and the `okf_audit` tool; the two renderers are deliberately separate (the CLI's bytes are golden-locked), but the computation and the `AuditVocabulary` labels must not be forked.
   - `Yaml/` — the documented YAML *subset* (scalars, lists, shallow maps, block/flow, `|`/`>`); it deliberately rejects anchors/tags/multi-docs with clear errors. `Frontmatter` wraps an order-preserving `YamlMapping` with typed getters rather than a fixed DTO, so unknown producer keys survive round-trips.
   - `Internal/LfLines.cs` — the single shared line splitter (splits on `\n` only, stripping a preceding `\r`). Use it anywhere `\n`-based line splitting matters; do not reintroduce private copies.
   - `Internal/ReparsePoints.cs` — internal symlink/junction detection; `OKF4net.Catalog` is granted `InternalsVisibleTo` so it can reuse this seam rather than duplicating a platform-specific implementation.
-- **`src/OKF4net.Cli/`** — the `okf` binary (`validate`/`info`/`index`/`graph`/`parse`/`fmt`/`render`), published Native AOT (`PublishAot`, `InvariantGlobalization`). All logic lives in `OkfCli.Run(args, out, err)` so tests invoke it in-process without spawning a process.
+- **`src/OKF4net.Cli/`** — the `okf` binary (`validate`/`audit`/`info`/`index`/`graph`/`parse`/`fmt`/`render`), published Native AOT (`PublishAot`, `InvariantGlobalization`). All logic lives in `OkfCli.Run(args, out, err)` so tests invoke it in-process without spawning a process.
 - **`src/OKF4net.Attestation/`** — zero-dep §10 attested-computation orchestration, referencing only `OKF4net`. Defines the host-plugged contracts (`IParameterBinder`, `IComputationExecutor`, `IAttester`, resolved per concept's `runtime` field through `IAttestationRuntimeRegistry`) and the value types that flow between them (`BoundComputation`, `Receipt`, `AttestationVerdict`, `AttestationContext`, `AttestationOutcome`); `AttestationOrchestrator.RunAsync` drives one run end to end (resolve → bind → execute → receipt-shape check → attest → gate on verdict + `stale_after`), errors-as-data, never writing a verdict back to the bundle (§10.6). Referenced by `OKF4net.Agents` to back `okf_run_computation`.
 - **`src/OKF4net.Agents/`** — Microsoft Agent Framework layer exposing OKF bundle operations as function tools (e.g. `OkfBundleTools`) plus `OkfContextProvider`, an `AIContextProvider` that auto-injects budget-bounded bundle context and captures deterministic per-day memory concepts; the only project depending on `Microsoft.Agents.AI`.
 - **`src/OKF4net.Catalog/`** — knowledge-catalog model and logic, referencing only `OKF4net` (BCL otherwise; zero `PackageReference`). Depended on by `OKF4net.Catalog.Hosting`. Each manifest source carries a `role` (`SourceRole`): `Knowledge` (read-only, searched by `IKnowledgeResolver`) or `Memory` (writable, scoped by a required `tier` — `session`/`user`/`tenant`, all three backed by `FileMemoryStore`, fed by `IMemoryStore`, never searched by the resolver); any other `role` string in `catalog.json` is rejected (`CatalogDiagnosticCode.IllegalRole`).

README.md

@@ -176,6 +176,7 @@ On any OS, build from source — see [Building & testing](#building--testing).
 
 ```
 okf validate <bundle>    Check a bundle against OKF v0.2 conformance (§11)
+okf audit    <bundle>    Report trust, freshness and lifecycle across the bundle
 okf info     <bundle>    Summarize a bundle (concepts, types, links, version)
 okf index    <bundle>    (Re)generate every index.md in the bundle
 okf graph    <bundle>    Print the cross-link graph (--dot for Graphviz DOT)
@@ -192,6 +193,21 @@ okf validate ./bundles/ga4
 okf graph ./bundles/ga4 --dot | dot -Tsvg > graph.svg
 ```
 
+`okf audit <bundle>` reports trust, freshness and lifecycle across a whole
+bundle: counts per trust tier (§5.3) and status (§5.4), plus the worklist of
+stale concepts (§5.5). Filter it to ask corpus-level questions —
+
+```sh
+# Which concepts are past stale_after and were never verified by a human?
+okf audit bundles/acme_retail --stale --trust unverified,machine-confirmed
+```
+
+Without filter flags it selects exactly what `--stale` selects and prints the
+summary form; with any filter flag it prints one line per matching concept, so
+the output pipes. `--json` always emits the full document. Note the counts
+always cover the whole bundle while `findings` covers the selection: `audit` is
+a worklist, not an inventory (use `okf info --json` for that).
+
 Generate a browsable HTML site from a bundle:
 
 ```sh
@@ -213,8 +229,8 @@ machine. Full command reference with real output samples:
 `src/OKF4net.Agents/` exposes bundle operations as function tools for the
 [Microsoft Agent Framework](https://github.com/microsoft/agent-framework):
 `OkfBundleTools` wraps one bundle root and its `GetTools()` method returns
-ten ready-to-use `AITool`s unconditionally, which `AsAIAgent` turns into an
-agent's tool list, plus an eleventh — `okf_run_computation` — only when the
+eleven ready-to-use `AITool`s unconditionally, which `AsAIAgent` turns into an
+agent's tool list, plus a twelfth — `okf_run_computation` — only when the
 tool set is constructed with an `OKF4net.Attestation` orchestrator wired in
 (see [Attested computation](#attested-computation-okf4netattestation)).
 
@@ -231,16 +247,17 @@ var response = await agent.RunAsync("Search the bundle for concepts about refund
 Console.WriteLine(response.Text);
 ```
 
-The ten unconditional tools, plus the eleventh conditional on an attestation
-orchestrator being wired (read → browse → graph → search → write → append →
-regenerate → validate → changes-since → get-computation → run-computation):
+The eleven unconditional tools, plus the twelfth conditional on an attestation
+orchestrator being wired (read → browse → graph → search → audit → write →
+append → regenerate → validate → changes-since → get-computation → run-computation):
 
 | Tool                     | Description                                                                                                                                                                                                    |
 |--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `okf_read_concept`       | Read one concept from the OKF bundle: its frontmatter, body, outgoing links and backlinks.                                                                                                                    |
 | `okf_browse`             | Browse the bundle via its index files (progressive disclosure). Without a path, lists the bundle root.                                                                                                        |
 | `okf_graph`              | Inspect the cross-link graph. With a concept id: its outgoing links, backlinks and broken links. Without: bundle-wide stats.                                                                                  |
 | `okf_search`             | Full-text search across concept titles, descriptions, tags and bodies. Returns matching concept ids ranked by relevance.                                                                                      |
+| `okf_audit`              | Audit the bundle's trust, freshness and lifecycle signals (§5.3–§5.5): counts by trust tier and status, plus the concepts needing attention. Read-only.                                                       |
 | `okf_write_concept`      | Create or update a concept document. The frontmatter must contain non-empty type, title and description (producer-grade validation is enforced before writing).                                               |
 | `okf_append_log`         | Append an entry to the bundle root log.md under today's date (ISO). Note: log.md is re-rendered through the strict §9 model, so non-conforming prose or comments in a hand-authored log.md are not preserved. |
 | `okf_regenerate_indexes` | Regenerate every index.md in the bundle (progressive-disclosure listings). Run after adding or changing concepts.                                                                                             |
@@ -507,6 +524,7 @@ This table is also published as the
 | §4 Concept documents                  | `OKF4net.OkfDocument`, `OKF4net.Frontmatter`                   |
 | §4.2 Body headings                    | `OkfDocument.Computation()` (fenced `# Computation` heading)   |
 | §5 Provenance, trust, and lifecycle   | `Frontmatter.Sources`/`Generated`/`Verified`/`TrustTier`/`Status`/`StaleAfter`, `Actor`/`Trust`/`Provenance`/`Lifecycle` |
+| §5.3–§5.5 | `ConceptAudit`, `AuditQuery`, `AuditReport` — corpus-level trust/freshness query behind `okf audit` and `okf_audit` |
 | §6 Cross-linking and paths            | `OKF4net.LinkScanner`, `Bundle.LinksFrom` / `Bundle.Backlinks` |
 | §6.2 Path-valued fields               | `OkfDocument.FrontmatterResources()`, `Bundle.TryResolveResource` / `Bundle.ReadResourceText` |
 | §7 Actor convention                   | `OKF4net.Actor.Parse` — `human:`/`process:`/`<producer>/<version>` |

ROADMAP.md

@@ -14,6 +14,12 @@ are the concrete entry points.
 
 ## Next
 
+- **`okf audit` shipped** — a corpus-level query over a bundle's trust (§5.3),
+  lifecycle (§5.4) and staleness (§5.5) signals: counts plus a filterable
+  worklist, across the CLI verb and the read-only `okf_audit` agent tool,
+  backed by the shared `ConceptAudit`/`AuditVocabulary` model in `OKF4net`.
+  Motivated by ["OKF v0.2 Quietly Admits the Folder Has a Ceiling"](https://medium.com/@davidroliver/okf-v0-2-quietly-admits-the-folder-has-a-ceiling-the-way-up-is-a-library-25fa54e872f9)
+  — see [its design spec](docs/superpowers/specs/2026-08-21-okf-audit-design.md).
 - More `OKF4net.Agents` samples with Microsoft Agent Framework — the first,
   `samples/acme-retail-agent`, shipped in 0.4.0; more welcome.
 - `OKF4net.Catalog` samples: `samples/catalog-explorer` (multi-source