@@ -23,11 +23,7 @@ const changedTsFiles = pr.files
   as="rawDiagnostics"
  />
 
-```ts eval
-import { buildDiagnostics } from "@executablemd/code-review-agent";
-
-const diagnostics = buildDiagnostics(rawDiagnostics, pr, doctor);
-```
+<ReviewDiagnostics raw={rawDiagnostics} pr={pr} doctor={doctor} as="diagnostics" />
 
 <ReleaseSpecWarning files={changedFilePaths} />
 
 
@@ -25,11 +25,7 @@ const changedTsFiles = pr.files
   as="rawDiagnostics"
  />
 
-```ts eval
-import { buildDiagnostics } from "@executablemd/code-review-agent";
-
-const diagnostics = buildDiagnostics(rawDiagnostics, pr, doctor);
-```
+<ReviewDiagnostics raw={rawDiagnostics} pr={pr} doctor={doctor} as="diagnostics" />
 
 <ThinkFilter>
 <DeepInfraProvider model="Qwen/Qwen3-30B-A3B">
 
@@ -405,7 +405,9 @@ the corpus or enabling in-shard concurrency is not an answer to a miss.
 ## MUST READ
 
 - https://github.com/thefrontside/effection/blob/v4/AGENTS.md
-- `architecture.md` — read fully
+- [`architecture.md`](architecture.md) — read fully. Its [reading map](architecture.md#reading-this-architecture)
+  locates current invariants and their feature-interface owners; it does not
+  replace the full reading.
 - `specs/executable-mdx-spec.md` — read the sections your change touches
 
 ## Code Rules
 
@@ -22,6 +22,21 @@ Three documents own the rest:
 - [`specs/executable-mdx-spec.md`](specs/executable-mdx-spec.md) — what the
   product does, with the conformance matrix that pins it.
 
+Follow a question into the [architecture reading map](architecture.md#reading-this-architecture):
+
+- [Execution and diagnostic journals](architecture.md#a-document-running): what
+  runs, what a Plan produces, and which journal can continue a workflow.
+- [Partial and completed replay](architecture.md#replay-and-effect-transactions):
+  why a historical file read survives a later deletion.
+- [Native Agent ownership](architecture.md#native-agent-sessions): handoff,
+  release and executable compatibility.
+- [Installed structural regions](architecture.md#the-installed-structural-syntax-boundary):
+  demand, output and cancellation.
+- [Plan recovery](architecture.md#typed-candidate-recovery-around-evaluate): why
+  cleanup failure stops a candidate retry.
+- [Current rules and historical decisions](specs/decisions.md#finding-the-current-rule):
+  where the architecture, feature contracts and vision differ in authority.
+
 Locate the package that owns the behavior you are about to change:
 
 - `packages/core/` — the engine: the boundary scanner, component expansion,
@@ -33,7 +48,7 @@ Locate the package that owns the behavior you are about to change:
 - `packages/durable-streams/` — the journal protocol, replay and divergence.
 - `packages/workflow/` — workflow runs, run storage, and the Workspace.
 - `packages/git/` — repository collaboration: `<Repository>`, `<Worktree>`,
-  `<Dir>`, the `Git.*` operations, pull requests and issues, and the GitHub
+  the `Git.*` operations, pull requests and issues, and the GitHub
   adapter behind them. It is the one Plugin `xmd` bundles, active by default for
   the run-profile commands — `run`, `plan`, `syntax`, and `workflow start`,
   `resume` and `fork`. The `xmd test` root is deliberately not one of them, so a
 
@@ -22,8 +22,8 @@
  * with nothing in it. `--approve-all`, `--approve-reads` and `--deny-all`
  * configure the approved document, later, and reach none of this.
  *
- * The document itself is given no Files, command, service or XMD-mediated
- * network capability either. It decides what to write; it writes nothing.
+ * The trusted document reads through the ordinary Files provider and effective
+ * Permissions. This frame refuses Files mutations, Process, Service and Fetch.
  */
 
 import { ensure, Err, Ok, scoped, until, useScope } from "effection";
 
@@ -767,17 +767,11 @@ describe("Tier PC — <Plan> in an ordinary document", () => {
     /**
      * Cancelling an information read, with its cleanup held open.
      *
-     * The grant is live exactly across `tryContent()` and the teardown the
-     * projection joins, so the interesting interruption is one that lands
-     * *inside* the provider: the read is in flight, a cleanup registered with it
-     * holds, and the halt may not be allowed to complete until that cleanup
-     * finishes. `joined` read while the cleanup is still held is what proves it
-     * waited — a flag checked afterwards would be true either way.
-     *
-     * What it shows about access is what a cancelled run can show: nothing
-     * further is performed under the grant. The retained-guard case — a guard
-     * answering no once its frame has ended — is Tier PLA's, where a scope can
-     * outlive what it was asking about.
+     * The interruption lands inside the provider: the read is in flight and
+     * its registered cleanup is held open. The projection joins that teardown,
+     * so halting the run must wait until the cleanup finishes. Reading `joined`
+     * before releasing the cleanup proves the halt waited — a flag checked
+     * afterwards would be true either way.
      */
     it("PI27: cancelling an entered information read waits for its cleanup", function* () {
       yield* useWorkingDirectory(function* () {
 
@@ -1,19 +1,19 @@
 Long-form documentation for the code-review agent's TypeScript components.
 
-Six components that gather the evidence a review reasons about: the pull request
-and its diff, the checkout's readiness, the Oxlint sensor's diagnostics, the
+Seven components gather or group the evidence a review reasons about: the pull
+request and its diff, the checkout's readiness, the Oxlint sensor's diagnostics, the
 repository's source inventory, and the review comments already on the pull
-request. Each one *reads* — none of them writes a comment, pushes a branch or
-changes a file.
+request. They read or transform evidence without writing a comment, pushing a
+branch or changing a file.
 
-They are reserved: this package claims these six names, so a repository under
+They are reserved: this package claims these seven names, so a repository under
 review cannot supply its own `ReviewContext.ts` and have a review run it. The
 Markdown components that compose them are declared by this package for the same
 reason, and are documented by their own bodies rather than here.
 
-Every one of them runs against the working directory. A review of another
-checkout establishes that checkout first — with `<Worktree>` or `<Dir>` — and
-these report on whatever is current.
+The evidence-gathering components run against the working directory. A review
+of another checkout establishes that checkout first — with `<Worktree>` or
+`<Dir>` — and these report on whatever is current.
 
 ## ReviewContext
 
@@ -67,6 +67,18 @@ cannot use. A silent empty result would be indistinguishable from a clean run,
 and a review that reported "no findings" because its sensor died is worse than
 one that stopped.
 
+## ReviewDiagnostics
+
+Group normalized Oxlint diagnostics for review policies.
+
+```mdx
+<ReviewDiagnostics raw={rawDiagnostics} pr={pr} doctor={doctor} as="diagnostics" />
+```
+
+Groups the sensor results by rule, applies the Doctor's import-noise filtering,
+and computes categories, density and summary through the package's existing
+`buildDiagnostics` helper. This transformation uses only its supplied values.
+
 ## RepositoryInventory
 
 Counts what is in the repository, for a review that reasons about the whole tree
 
@@ -0,0 +1,68 @@
+import type { Operation } from "effection";
+import type { Diagnostics, DoctorResult, OxlintDiagnostic, PR } from "../types.ts";
+import { buildDiagnostics } from "../parse-diagnostics.ts";
+import { returns as rawDiagnosticsSchema } from "./OxlintDiagnostics.ts";
+import { returns as doctorSchema } from "./Doctor.ts";
+
+export const props = {
+  type: "object",
+  properties: {
+    raw: rawDiagnosticsSchema,
+    pr: { type: "object" },
+    doctor: doctorSchema,
+  },
+  required: ["raw", "pr", "doctor"],
+  additionalProperties: false,
+};
+
+const groupSchema = {
+  type: "object",
+  properties: {
+    ruleId: { type: "string" },
+    count: { type: "number" },
+    files: { type: "array", items: { type: "string" } },
+    instances: rawDiagnosticsSchema,
+  },
+  required: ["ruleId", "count", "files", "instances"],
+  additionalProperties: false,
+};
+const groupsSchema = { type: "array", items: groupSchema };
+
+export const returns = {
+  type: "object",
+  properties: {
+    groups: groupsSchema,
+    total: { type: "number" },
+    fileCount: { type: "number" },
+    ruleCount: { type: "number" },
+    byCategory: {
+      type: "object",
+      properties: {
+        structural: groupsSchema,
+        verbosity: groupsSchema,
+        typeAware: groupsSchema,
+        other: groupsSchema,
+      },
+      required: ["structural", "verbosity", "typeAware", "other"],
+      additionalProperties: false,
+    },
+    summary: { type: "string" },
+    density: { type: "number" },
+  },
+  required: ["groups", "total", "fileCount", "ruleCount", "byCategory", "summary", "density"],
+  additionalProperties: false,
+};
+
+interface ReviewDiagnosticsProps {
+  raw: OxlintDiagnostic[];
+  pr: PR;
+  doctor: DoctorResult;
+}
+
+export default function* ReviewDiagnostics({
+  raw,
+  pr,
+  doctor,
+}: ReviewDiagnosticsProps): Operation<Diagnostics> {
+  return buildDiagnostics(raw, pr, doctor);
+}
@@ -2,7 +2,7 @@
  * Install the packaged review graph when an operator selects this Plugin.
  *
  * Run, syntax, plan and executing workflow actions reserve its thirty-five
- * Markdown declarations and six reserved registrations, so the repository being
+ * Markdown declarations and seven reserved registrations, so the repository being
  * reviewed cannot replace the review program. Root `xmd test` reserves none;
  * its isolated `<Execution host="run">` child reinstalls this Plugin with
  * command `run`.
@@ -100,7 +100,7 @@ const reviewPlugin: Plugin = Plugin({
     if (!claimsGraph(request)) {
       return undefined;
     }
-    // The six reserved registrations and the documentation describing them, in
+    // The seven reserved registrations and the documentation describing them, in
     // the scope the command runs in. Declarative only: nothing here installs a
     // provider, spawns a process, reads a credential or reaches the network.
     yield* useReviewComponents();