agentic-mermaid 0.1.1 → 0.2.0

package/docs/mermaid-layout-complaints.md

@@ -1,10 +1,15 @@
 # Mermaid layout complaints: catalog, root causes, and coverage
 
+Status: evidence and capability-coverage scorecard, not a roadmap or backlog.
+`TODO.md` is the sole authority for scheduled work. Historical issues and specs
+below retain candidate contract evidence only; they do not schedule
+implementation unless a stable root TODO item promotes them.
+
 This document maps what users actually complain about in Mermaid's layout →
 why those failures happen → which Agentic Mermaid work addresses each one
-(landed, specced, or deliberately out of scope). It is the durable version of
-a June 2026 research pass and should be updated when complaint-relevant work
-lands.
+(landed, retained as candidate evidence, or deliberately out of scope). It is
+the durable version of a June 2026 research pass and should be updated when
+complaint-relevant work lands.
 
 Companions:
 
@@ -35,7 +40,7 @@ Status legend used below:
 |---|---|
 | **landed** | shipped in this repo with tests |
 | **partial** | some of the complaint class is covered, the rest is not |
-| **specced** | designed in #25/#26/PR #24 with acceptance criteria, not implemented |
+| **candidate evidence** | described in a historical issue/spec, but unscheduled unless promoted to root `TODO.md` |
 | **out of scope** | deliberately not addressed; the reason is stated |
 
 ---
@@ -62,15 +67,14 @@ tricks. This is the loudest and oldest theme.
   diagram is visually laid out there's not really an easy way to change it"
   ([41262756](https://news.ycombinator.com/item?id=41262756)).
 - Root cause: R3 (missing control surface).
-- Status here: **out of scope, by policy.** Issue #25 (open question 2)
-  recommends against route/position hints: "Keep route intent inferred from
-  semantics and author order unless Mermaid core standardizes hints," and
-  syntax invention is a stated non-goal. The substitute is actuation through
-  the agent loop: deterministic layout (`measureQuality`, `checkQuality`,
-  `eval/layout-compare/`) makes bad layout *detectable*, typed mutation makes
-  source restructuring cheap, and #25's route certificates would make
-  detours *explained* — so a program can iterate where a human would drag a
-  node. This substitutes for manual positioning; it does not provide it.
+- Status here: **manual coordinates and post-hoc nudging remain out of scope.**
+  `BUILD-24` now owns a narrower response: typed, deterministic structural
+  constraints for rank/layer, adjacency, and edge-length preference. They are
+  render/mutation metadata, not Agentic-only Mermaid syntax, and therefore do
+  not contradict #25's rule against inventing route syntax. Deterministic
+  quality measurement and route certificates remain the feedback loop; the
+  hints let an agent state topology-preserving intent without deleting a real
+  edge. This still does not provide arbitrary node coordinates or dragging.
 
 ### C2. Layout collapses at scale
 
@@ -128,11 +132,14 @@ sibling clusters overlap.
   a Tier 1 `GROUP_BREACH` warning.
 - Status here: **landed** (PRs #17, #21, #22). Residual: cross-hierarchy and
   container-edge *route classes* — making the SVG router treat boundary
-  edges semantically rather than via representative children — are specced
-  (#25 §8.3, #26 workstream 2).
+  edges semantically rather than via representative children — remain candidate
+  contract evidence in #25 §8.3 and #26 workstream 2, not scheduled work.
 
 ### C4. Erratic edge routing: avoidable crossings, overlaps, doglegs
 
+Here and in the scorecard, **C4 means complaint category 4**, not Mermaid's C4
+diagram family.
+
 Edges cross when they obviously need not, overlap each other or pass through
 nodes, and acquire small unexplained doglegs ("hitches"). Users untangle by
 trial-and-error reordering of source lines.
@@ -168,15 +175,16 @@ trial-and-error reordering of source lines.
   tie-breaking in the ASCII pathfinder
   (`src/__tests__/ascii-pathfinder-determinism.test.ts`).
 - Status here: **partial today, with the route-contract core landed and the
-  broader program still specced.** #25 defines route classes
+  broader program retained as candidate evidence.** #25 defines route classes
   (`primary-forward`/`feedback`/fan trunks/…), the straight-primary and
   hitch invariants (§11.1–11.2), the certifying simplifier (§12), and the
   hard rule "no node-coordinate mutation after route extraction unless all
   incident routes are rerouted or recertified" (§9). The current tests now
   include route-certificate geometry and property coverage across dotted,
-  thick, bidirectional, marker, and labeled edge forms. Remaining work lives
-  in the still-open route/port issues (#32, #35, #38 and the #26 umbrella),
-  plus cross-renderer adoption.
+  thick, bidirectional, marker, and labeled edge forms. The still-open
+  route/port issues (#32, #35, #38 and the #26 umbrella) retain unscheduled
+  evidence; any implementation or cross-renderer adoption requires promotion
+  to root `TODO.md`.
 
 ### C5. Edge labels overlap edges, nodes, and each other
 
@@ -190,7 +198,6 @@ edge they describe.
   integrated-labeling concept yFiles ships, see R3),
   [mermaid#2131 mis-aligned state labels](https://github.com/mermaid-js/mermaid/issues/2131),
   [mermaid#2525 "messages appear with line through them"](https://github.com/mermaid-js/mermaid/issues/2525),
-  [mermaid#7492 C4 label/text/arrow chaos](https://github.com/mermaid-js/mermaid/issues/7492),
   [mermaid#1233](https://github.com/mermaid-js/mermaid/issues/1233).
 - Root cause: R1 (label placement is NP-hard and classically solved *after*
   layout; dagre models labels as mid-edge dummy nodes), R4/R5 (renderers do
@@ -297,7 +304,8 @@ at layout time, and no width budget for CJK/long words.
 - Status here: **landed**, with an honest gap: the 7px/char SVG heuristic is
   approximate (`docs/quality.md`), and the shared text-measurement contract
   that would unify SVG/ASCII/quality measurement (CJK, emoji, ambiguous
-  width) is specced as #26 workstream 8. Regression coverage now includes
+  width) remains candidate evidence in #26 workstream 8. Regression coverage
+  now includes
   emoji-presentation selectors and East Asian ambiguous-width symbols, so
   common Unicode labels cannot silently drift between SVG metrics and
   terminal-width assumptions.
@@ -343,8 +351,9 @@ take long unexplained detours.
   (Tier 2) and self-loop clearance heuristics
   (`layout-quality-heuristics.test.ts`) guard regressions. SVG self-loop
   port policy (N/S side by clearance) is #25 §8.1; mermaid#6049 is listed as
-  a future fixture in [`issue-derived-test-cases.md`](./issue-derived-test-cases.md).
-- Status here: **partial** (ASCII decent + guarded; SVG semantics specced).
+  candidate fixture evidence in [`issue-derived-test-cases.md`](./issue-derived-test-cases.md).
+- Status here: **partial** (ASCII decent + guarded; SVG semantics retained as
+  candidate evidence, not scheduled).
 
 ### C11. Unstable output across versions and renderers
 
@@ -395,15 +404,14 @@ titles, notes colliding with lifelines.
 
 ### C13. Chart families: hard-coded geometry breaks on real data
 
-Gantt axis dates overlap on long ranges, pie titles/labels clip, radar axis
-labels compress, C4 is widely considered the worst-layouted type. These are
+Gantt axis dates overlap on long ranges, pie titles/labels clip, and radar axis
+labels compress. These are
 not dagre problems — each chart type has bespoke geometry with no collision
 handling.
 
 - Evidence: [mermaid#1301 gantt axis overlap](https://github.com/mermaid-js/mermaid/issues/1301)
   (23R), [mermaid#6232 pie title cut off](https://github.com/mermaid-js/mermaid/issues/6232),
-  [mermaid#7683 radar labels clipped](https://github.com/mermaid-js/mermaid/issues/7683),
-  [mermaid#7492 C4](https://github.com/mermaid-js/mermaid/issues/7492).
+  and [mermaid#7683 radar labels clipped](https://github.com/mermaid-js/mermaid/issues/7683).
 - Root cause: R5 (per-family renderer-first geometry; semantics inferred at
   draw time — the exact anti-pattern #26's guiding principle names).
 - Fixture/test: pie and quadrant landed source-level with geometry tests
@@ -412,10 +420,10 @@ handling.
   pure, clock-free schedule resolver *before* layout, family validators
   (deterministic task intervals, milestone zero-width markers,
   non-overlapping compact rows) designed against precisely the mermaid#1301
-  class. C4, radar, and mindmap are not supported at all.
-- Status here: **partial** (pie/quadrant/gantt landed; C4/radar/mindmap
-  absent — see [`comparison.md`](./comparison.md) for the current
-  family-coverage trade).
+  class. Mindmap now has deterministic tree geometry; Radar has deterministic
+  radial layout, bounded labels, ring ticks, and cross-format render contracts.
+- Status here: **covered for every registered chart family**; remaining work is
+  tracked as family-specific quality improvement, not missing Radar support.
 
 ---
 
@@ -448,7 +456,8 @@ directly:
    Harvard TR-05-91), and edge-label placement specifically is NP-hard
    ([Kakoulis & Tollis 2001](https://www.sciencedirect.com/science/article/pii/S0925772100000250),
    Comput. Geom. 18(1)). No engine "chooses" the avoidable crossing in
-   C4 — it fails to find the better optimum it cannot afford to search for.
+   complaint C4 — it fails to find the better optimum it cannot afford to
+   search for.
 2. **Phases cannot revisit earlier decisions.** Layering fixes ranks before
    crossing minimization sees them; coordinates are assigned before routing.
    A route that needs a node nudged one lane over cannot get it. This is
@@ -590,7 +599,8 @@ assignment is
 in `lib/position/bk.js`) and then stops: there is no routing phase at all —
 edges are interpolated through dummy-node points.
 [dagre-d3#291](https://github.com/dagrejs/dagre-d3/issues/291) is the
-user-visible result, and C4/C5 are the Mermaid-visible results. Cluster
+user-visible result, and complaint categories C4/C5 are the Mermaid-visible
+results. Cluster
 support follows Sander/Forster on paper (per
 [dagre's wiki](https://github.com/dagrejs/dagre/wiki)) but fails on nesting
 and compound edges in practice
@@ -625,8 +635,8 @@ docs) — selected via frontmatter `config.layout`, and per the
 edge-overlap ask
 [mermaid#1006](https://github.com/mermaid-js/mermaid/issues/1006) was
 closed *Wont Fix*. GitHub's native rendering still runs the dagre default —
-so most readers see the unfixed engine (C2, C3, C4, C9), and even opted-in
-users get the better engine for two of ~25 families. PlantUML made the
+so most readers see the unfixed engine (complaint categories C2, C3, C4, C9),
+and even opted-in users get the better engine for two of ~25 families. PlantUML made the
 opposite bet decades earlier: it
 [delegates class/state/component/usecase layout to Graphviz dot](https://plantuml.com/graphviz-dot),
 inheriting dot's router and rank constraints along with its weaknesses.
@@ -688,7 +698,10 @@ model, derive layout intent, compute geometry, certify, then render —
 with renderers as projections of shared intent rather than the place where
 intent is invented.
 
-### Root causes → issue #26 workstreams
+### Root causes → historical issue #26 workstream evidence
+
+This crosswalk preserves the research decomposition only. It does not make the
+issue workstreams an active schedule; root `TODO.md` must own any promoted work.
 
 | Root cause | #26 workstream(s) |
 |---|---|
@@ -700,7 +713,7 @@ intent is invented.
 | R4 rectangular/port-less model | WS3 semantic ports and shape-aware anchors |
 | R5 renderer-first semantics | WS5 Gantt resolver model (landed); WS7 class/ER contracts; WS10 region tree; WS13 preservation ladder |
 | Unreviewable visual change (meta) | WS12 reproducible before/after evidence |
-| Generic metrics miss failures (meta, C4 worked example) | WS11 family-specific validators |
+| Generic metrics miss failures (meta, complaint C4 worked example) | WS11 family-specific validators |
 
 ---
 
@@ -711,13 +724,13 @@ intent is invented.
 | C1 | Manual positioning | mermaid#5420 (47R), #270 (2016–) | **out of scope** by policy | #25 OQ2; agent loop as substitute |
 | C2 | Scale collapse | mermaid#1984 (39R) | **partial** (detection only) | `quality.ts` bands; `eval/layout-compare/` |
 | C3 | Subgraphs | mermaid#2509 (189R) | **landed** | `subgraph-direction.test.ts`; PRs #17/#21/#22 |
-| C4 | Erratic routing | mermaid#6476, #5601 | **partial**; fix **specced** | #25 §11–12; MFA worked example above |
-| C5 | Edge-label overlap | mermaid#2131, #7492 | **partial** | inline ELK labels; `labelEdgeProximity`; #25 §11.4 |
+| C4 | Erratic routing | mermaid#6476, #5601 | **partial**; candidate fix evidence only | #25 §11–12; MFA worked example above |
+| C5 | Edge-label overlap | mermaid#2131 | **partial** | inline ELK labels; `labelEdgeProximity`; #25 §11.4 |
 | C6 | Order control / edit stability | mermaid#3723 (86R), #815 (45R) | **partial** | model-order ELK opts; `agent-auth-flow.test.ts`; edit-stability tests |
 | C7 | Default aesthetics | HN 30339032 | **landed** (upstream + fork) | theming; Style + Palette; contrast tests |
-| C8 | Text clipping | mermaid#2688 (24R) | **landed** | zero-DOM text; `LABEL_OVERFLOW`; CJK tests; WS8 specced |
+| C8 | Text clipping | mermaid#2688 (24R) | **landed** | zero-DOM text; `LABEL_OVERFLOW`; CJK tests; WS8 candidate evidence |
 | C9 | dagre stagnation | Mermaid docs' own ELK advice | **landed** structurally | `layout-engine.ts`; `elk-instance.ts`; #25 §10 |
-| C10 | Self-loops | mermaid#6336 (31R) | **partial** | clearance heuristics; #25 §8.1 specced |
+| C10 | Self-loops | mermaid#6336 (31R) | **partial** | clearance heuristics; #25 §8.1 candidate evidence |
 | C11 | Version/renderer instability | mermaid#5813 (28R) | **landed** | determinism suite; `eval/layout-compare/`; goldens |
 | C12 | Sequence alignment | mermaid#1765 (28R) | **partial**; first properties landed | #25 §14.2; #26 WS11; `sequence-layout.test.ts` |
 | C13 | Chart-family geometry | mermaid#1301 (23R) | **partial** | PR #24 (gantt); pie/quadrant/gantt geometry tests |
@@ -728,10 +741,11 @@ intent is invented.
 
 Stated plainly so the scorecard cannot oversell:
 
-1. **Manual positioning (C1).** The loudest single ask is answered with a
-   substitute (deterministic + measurable + explainable auto-layout for
-   editing programs), not a solution. If Mermaid core standardizes layout
-   hints, this fork follows; it will not invent them (#25 non-goals).
+1. **Manual positioning (C1).** Arbitrary coordinates and post-layout nudging
+   remain deliberately unsupported. `BUILD-24` schedules only typed structural
+   auto-layout constraints (rank, adjacency, short-edge preference), without
+   inventing Mermaid source syntax. If Mermaid core standardizes compatible
+   source hints, this fork can map them into the same typed contract.
 2. **Large-diagram compaction (C2).** Detection exists; no compaction work
    is scheduled. Source-order priority can make wide diagrams wider — the
    Auth Flow aspect band in `agent-auth-flow.test.ts` is widened to 7
@@ -743,14 +757,14 @@ Stated plainly so the scorecard cannot oversell:
    applies to diagrams rendered through this stack (agent pipelines, CI,
    terminals, the editor) plus whatever is upstreamed per the
    [upstreaming strategy](./fork-differences.md#upstreaming-strategy).
-4. **Family coverage.** 12 families vs Mermaid's ~25. Gantt is now rendered
-   and characterized in this fork; C4/radar/mindmap and many other Mermaid
-   families remain outside the current engine.
+4. **Family coverage.** The checked runtime registry is the source of truth for
+   supported families. Every registered family, including Radar, is rendered and
+   characterized; Mermaid families outside that registry remain unsupported.
 5. **Metric honesty.** Today's perceptual metrics pass diagrams whose
-   routing is visibly wrong (C4 worked example). Until #25 certificates and
-   #26 family validators land, `verify.ok` + `checkQuality` must not be
-   read as "looks right" — `docs/quality.md` already says this; the MFA
-   fixture proves it.
+   routing is visibly wrong (complaint C4 worked example). Unless and until the
+   #25 certificate and #26 family-validator candidates are promoted in root
+   `TODO.md` and land, `verify.ok` + `checkQuality` must not be read as "looks
+   right" — `docs/quality.md` already says this; the MFA fixture proves it.
 
 ---
 

package/docs/mutation-testing.md

@@ -1,49 +1,120 @@
-# Mutation testing (ASCII layout core)
+# Mutation testing
 
-Stryker mutation testing is scoped to the five ASCII layout modules where a
+The original ASCII Stryker lane is scoped to the five layout modules where a
 silent logic regression is most expensive: `src/ascii/pathfinder.ts`,
 `src/ascii/edge-routing.ts`, `src/ascii/converter.ts`, `src/ascii/grid.ts`,
 `src/ascii/draw.ts`.
-The config is `stryker.ascii.config.json`; its command runner executes the
+The `ascii` profile in the single `stryker.config.mjs` authority executes the
 ASCII test files (goldens, invariants, properties, unit tests) per mutant.
 
 ## Running
 
 ```bash
 # One module (preferred — a full module takes 5–15 minutes):
-npx stryker run stryker.ascii.config.json --mutate 'src/ascii/pathfinder.ts'
+bun run mutation-test -- ascii --mutate 'src/ascii/pathfinder.ts'
 
-# All five (also available as `bun run mutation-test:ascii`):
-npx stryker run stryker.ascii.config.json
+# All five:
+bun run mutation-test -- ascii
+
+# Discover every available profile:
+bun run mutation-test -- --list
 ```
 
-(`stryker.families.config.json` / `bun run mutation-test:families` covers the
-agent family parsers, and `stryker.routes.config.json` / `bun run
-mutation-test:routes` covers the route-contracts module
+(`bun run mutation-test -- families` covers the
+shared Architecture, XYChart, Mindmap, GitGraph, and Radar parser/layout/renderer
+cores plus Radar's structured editing body, and `bun run mutation-test -- routes` covers
+the route-contracts module
 (`docs/design/system/route-contracts.md`), all with the same policy.)
 
 Narrow lanes for PR-scale survivor harvests:
 
 ```bash
-bun run mutation-test:links            # text-embedded link-length parsing
-bun run mutation-test:routes:certs     # route-certificate finality + stale-route audit
-bun run mutation-test:routes:subgraph  # subgraph endpoint/LCA routing
+bun run mutation-test -- links            # text-embedded link-length parsing
+bun run mutation-test -- routes:certs     # route-certificate finality + stale-route audit
+bun run mutation-test -- routes:subgraph  # subgraph endpoint/LCA routing
 bun run sabotage:routes                # one-line revert checks against committed HEAD; expects focused tests to fail
 ```
 
-The JSON report lands in `reports/mutation/` (gitignored). Beyond the lanes
-documented here, `stryker.*.config.json` also covers the per-family parsers
-(state/sequence/timeline/class/er/journey/pie/quadrant/gantt via
-`mutation-test:families`), characterization, and the link-grammar lane — see
-`package.json` scripts for the full index. Broad route lanes
-are intentionally not part of the PR gate, but `.github/workflows/nightly-route-mutation.yml`
-runs `mutation-test:routes`, `mutation-test:routes:certs`,
-`mutation-test:routes:subgraph`, and `sabotage:routes` nightly and on manual
-`workflow_dispatch`, uploading reports as artifacts — though every scheduled
-run to date has been cancelled at the 90-minute cap before uploading anything
-(the unsharded routes lane exceeds it; PR #63 carries the sharding fix), so
-current scores come from local runs. Run the narrow lane locally
-when you touch ASCII/route core logic and want immediate proof the tests bite.
+JSON reports land in `reports/mutation/` (gitignored). The single executable
+config resolves route-certificate, subgraph-routing, and link-grammar ranges
+from source-adjacent markers; inserting code above the behavior cannot silently
+move those lanes onto unrelated lines.
+
+Beyond the lanes documented here, configs exist for every built-in renderable
+family through named profiles: flowchart uses `mutation-test -- routes`;
+XYChart, Architecture, and Radar share `mutation-test -- families`; State, Sequence,
+Timeline, Class, ER, Journey, Pie, Quadrant, Gantt, Mindmap, and GitGraph each
+have a focused command. These are **opt-in diagnostic survivor harvests**. They
+emit scores and JSON reports, but have no `thresholds.break` and are neither
+scheduled nor acceptance gates.
+
+Two bounded checks run automatically on each PR:
+
+- `mutation-test -- incremental` mutates one small, pure module in about one minute
+  and enforces its measured score.
+- `sabotage:routes` injects five named one-line regressions and requires the
+  focused behavioral tests to fail.
+
+This distinction is deliberate. Mutation testing is useful when it challenges
+a specific test or design assumption; family membership alone is not a reason
+to enroll code in an expensive recurring sweep. A local mutation score without
+a retained report is diagnostic evidence, not a repository acceptance claim.
+
+## Why broad scheduled mutation was retired (2026-07-14)
+
+The nightly workflow, its sharder, mutant-set oracle, aggregate verifier, and
+orchestration tests were retired and deleted. The operational evidence did
+not support maintaining them:
+
+- all 26 scheduled runs from 19 June through 14 July failed or were cancelled;
+- the workflow expanded from four route checks to every family while it was
+  still unable to produce a successful retained run;
+- the final repair grew to 39 coverage workers (41 jobs total), yet long lanes
+  still timed out and hosted runners disappeared before producing reports; and
+- rerunning unchanged mutation-relevant code consumed runner-hours without
+  adding information.
+
+The [last scheduled baseline](https://github.com/adewale/agentic-mermaid/actions/runs/29309167850),
+[calibration diagnostic](https://github.com/adewale/agentic-mermaid/actions/runs/29327418603),
+and [cancelled 41-job repair](https://github.com/adewale/agentic-mermaid/actions/runs/29340333016)
+are retained as historical evidence, not as acceptance authority. The focused
+configs, marker-based scopes, survivor classifications, incremental gate, and
+sabotage probes remain because they are independently useful.
+
+The causal record is in
+[`project/archive/mutation-infrastructure-postmortem-2026-07.md`](./project/archive/mutation-infrastructure-postmortem-2026-07.md).
+The durable stop rule is: after three consecutive scheduled failures, an owner
+must fix, narrow, disable, or delete the diagnostic before adding scope. Any new
+recurring lane also needs a demonstrated fault class, one complete retained
+baseline, a runner-minute budget, an owner, and a removal criterion. No single
+proxy—coverage, mutation score, assertion count, or matrix enrollment—is “the”
+adequacy signal.
+
+## Focused Mindmap/GitGraph historical local measurement (2026-07-10)
+
+These figures came from local runs. Their JSON reports are gitignored and no
+immutable CI artifact URL is committed, so they are diagnostic history—not a
+PR acceptance gate or a current break floor.
+
+| Lane | Mutants | Killed | Survived | Score |
+|---|---:|---:|---:|---:|
+| `bun run mutation-test -- mindmap` (`src/agent/mindmap-body.ts`) | 405 | 400 | 5 | **98.77%** |
+| `bun run mutation-test -- gitgraph` (`src/agent/gitgraph-body.ts`) | 303 | 294 | 9 | **97.03%** |
+
+The operation suites exercise every happy path, validation branch, source-order
+rewrite, recursive/cycle guard, null-clearing path, and verification warning.
+Mindmap's five survivors are two correlated node-syntax tuple guards plus
+three exception-path mutations around the node/body stability probes (two
+empty `catch` forms remain falsy; one `false`→`true` mutation is retained as a
+non-gating test gap). GitGraph's nine
+survivors are canonical serialization equivalents (trimming an already
+canonical header, explicit `NORMAL`, and optional attribute whitespace),
+merge-field guards implied by the discriminated model, or widened
+statement-kind guards that serialize identically on valid replay state. Reports
+are generated at `reports/mutation/{mindmap,gitgraph}-mutation.json`
+(gitignored); the committed configs make the runs reproducible. The measured
+scores above are not acceptance evidence: any separately owned acceptance claim
+must cite retained CI artifacts or a content-addressed report.
 
 ## Policy
 
@@ -61,19 +132,22 @@ documented, not killed with synthetic inputs.
 | converter.ts | 38.4% | 94 | 151 |
 | grid.ts | 70.1% | 421 | 180 |
 | layout/passes/index.ts:931-1165 (linkrank packing repair) | 49.86% → 65.07% after the geometry-characterization harvest (355 mutants; killed 176 → 230+1 timeout). The +54 kills were the repair's candidate ORDERING / ahead-node selection / push-delta arithmetic — invisible to HARD-metric assertions (a mutant picking a different clear lane still yields zero violations), pinned instead by per-repro geometry snapshots in `linkrank-packing.test.ts` (layout determinism makes them stable). | 355 | 124 — see classification below |
-| route-contracts.ts | 58.1% → 72.3% → 75.6% → 73.1% across the first three batches; 54.31% at 0b43c90, then 50.69% at 526d9cf after the slanted-family batch (shapePorts generalization, convex-polygon geometry: 2659 → 2740 mutants — absolute kills 1444 → 1381). The percentage fell purely on denominator growth (~3× since batch 3); a survivor-harvest batch is the documented next quality step. | 882 → 2740 | 50.69% (1381 killed) — survivor harvest pending |
+| route-contracts.ts | 58.1% → 72.3% → 75.6% → 73.1% across the first three batches; 54.31% at 0b43c90, then 50.69% at 526d9cf after the slanted-family batch (shapePorts generalization, convex-polygon geometry: 2659 → 2740 mutants — absolute kills 1444 → 1381). The percentage fell on denominator growth (~3× since batch 3); residuals from that run are classified below. | 882 → 2740 | 50.69% (1381 killed) — historical snapshot |
 
 (Numbers from the June 2026 runs; regenerate rather than trusting this
 table — the report lands in `reports/mutation/`.)
 
-## Survivor classification
+## Historical survivor classification
+
+This section explains the recorded run; it is not a secondary test backlog.
+Only root `TODO.md` can schedule a new fixture or survivor-harvest package.
 
 **linkrank lane residual (124 at the 65.07% run)**, classified:
 
-- **Real gap, next harvest**: the subgraph-scoped `separationUnit` branch (walk the
-  overlapped node's scope chain, push its outermost subgraph unit) never fires — the
-  degenerate repro set has no subgraphs. Killing these needs a subgraph + long-link
-  shove-overlap fixture.
+- **Unexercised branch in the recorded corpus**: the subgraph-scoped
+  `separationUnit` branch (walk the overlapped node's scope chain, push its
+  outermost subgraph unit) did not fire because the degenerate repro set had no
+  subgraphs. A subgraph + long-link shove-overlap fixture was not part of that run.
 - **Unexercised defensive fallbacks**: the `rungSource` feedback family and some
   min-lane branches fire only on inputs the deterministic enumeration no longer
   produces (0 residual signatures); every adopted route is still runtime-validated by
@@ -93,8 +167,8 @@ be preserved).
 **Accepted — performance guards, not behavior** (pathfinder): the #66
 bounded-search mutants (`next.x > boundX || next.y > boundY` weakenings,
 `maxIterations` arithmetic). They change how much work an unreachable-target
-search does before returning null, not what any reachable search returns. A
-test would need to time the search, which is flakier than the risk warrants.
+search does before returning null, not what any reachable search returns.
+Timing the search was judged less reliable than the risk warranted.
 
 **Accepted — unreachable via convention** (pathfinder): the `dy`-dominant
 fallback in `buildMoveDirs` (lines ~157–159). All nine 3×3 `Direction`
@@ -136,59 +210,62 @@ reachability verdicts, on the small graphs flowcharts produce.
 
 **Accepted — bounded-iteration guard** (route-contracts): the fixed-point
 loop's `round < 4` weakenings only change how many re-prove rounds run;
-the duplicate-edge regression pins one unblocking round, and constructing
-a graph that needs three chained rounds would be a synthetic-input test.
+the duplicate-edge regression pins one unblocking round, while three chained
+rounds were outside the recorded real-input corpus.
 
-**Open test gaps** (highest-value first):
+**Residual observations from that run** (not scheduled):
 - `directLaneBlockers` label-rect axis ternaries retain a few survivors on
-  rect width/height swaps for near-square pills; a multi-line (taller than
-  wide) label obstacle fixture would discriminate them.
+  rect width/height swaps for near-square pills; the corpus lacked a multi-line
+  (taller than wide) label obstacle.
 - `findLabelSlot`'s rect-overlap conjunction retains sign-variant survivors
-  for rects that only graze on one axis; corner-touching fixtures would
-  pin them.
+  for rects that only graze on one axis; corner-touching fixtures were absent.
 - The audit's pill-hit prefilter (`hitsPill`) retains inclusive-vs-strict
   comparison survivors for segments that exactly graze the pill border;
   they only widen the prefilter the collinearity check still gates.
-- The container repair's reversed-order gaps (target above / left of
-  source) lack fixtures; the gap arithmetic is symmetric with the two
+- The container repair's reversed-order gaps (target above / left of source)
+  were absent; the recorded classification relied on symmetry with the two
   covered directions.
 - `grid.ts` `ensureSubgraphSpacing` (~48 survivors): the overlap/min-spacing
   resolution between root subgraphs is never triggered by the corpus —
-  placement upstream appears to avoid overlaps already. Needs either a
-  corpus sample that genuinely overlaps or a dead-code verdict.
+  placement upstream appeared to avoid overlaps, so the run could not
+  distinguish reachable behavior from defensive dead code.
 - `converter.ts` entry/exit attachment roles and phantom still-used checks
   (`resolveSubgraphEdges` area): rendered-output invariants tolerate several
-  mutants because other mechanisms compensate. Needs assertions on the
-  resolved edge structure, not just the rendered text.
+  mutants because other mechanisms compensate; the run asserted rendered text,
+  not the intermediate resolved edge structure.
 - `edge-routing.ts` label segment filter (`width >= lenLabel && index > 1 &&
   orientationMatches`): the labeled-fanout invariants pin the TD vertical-drop
   case; LR orientation and the index>1 exclusion lack direct coverage.
 
-## Incremental per-PR lane (`stryker.incremental.config.json`)
+## Incremental per-PR profile
 
 A fast lane gates the small, pure faithfulness counter on every PR (the
-`mutation-incremental` CI job), separate from the broad nightly lanes. It
+`mutation-incremental` CI job), separate from the opt-in diagnostic configs. It
 mutates `src/agent/structural-count.ts` (the counter + `faithfulnessWarning` +
 `isDrop`), run by the sub-second `structural-count.test.ts` unit runner. A full
 run is ~1 min, so it runs in full each PR.
 
-Score is ~96% (regenerate to confirm; the report lands in `reports/mutation/`),
-gated by `thresholds.break: 90`. The few survivors are all equivalent mutants,
-accepted not chased:
+The 2026-07-14 post-Radar run scored **97.01%** (130 killed / 134 valid; regenerate to
+confirm, with the report in `reports/mutation/`), gated by
+`thresholds.break: 90`. The retained floor deliberately remains below the
+measured score; this result for one small pure module is not a repository policy
+or a reason to expand mutation scope.
+
+The survivor review found real valid-domain gaps rather than accepting a score:
+the State counter needed both a doubly nested composite and concurrent-region
+fixtures; ER needed a semantic-subgraph fixture and the public empty body with
+its optional `groups` field absent; and `nodes = services + junctions` needed an
+Architecture fixture containing a junction. These cases remain because they
+pin real behavior, not because they improve a metric.
 
-- `structural-count.ts:96` (`case 'opaque': return null`) — two mutants
-  (the case label + its string). Equivalent: an opaque body returns `null`, and
-  the `default` branch *also* returns `null`, so mutating the `opaque` case
-  cannot change the result for any input.
-- `structural-count.ts:98` (`default:` exhaustiveness branch) — two mutants
-  (the branch condition + its block). Unreachable by construction: all twelve
-  families are handled explicitly and the `const _never: never = body` assigns
-  compile-time exhaustiveness, so the branch never executes at runtime.
+Four survivors are classified rather than killed with invalid inputs or by
+weakening the code's forward-compatibility tripwire:
 
-What earlier survivors taught us (now killed, kept as regression fixtures): the
-recursive `edges += inner.edges` state accumulation needed a *doubly-nested*
-composite-state fixture, and `nodes = services + junctions` needed an
-architecture fixture that actually contains a junction.
+- two mutations to `case 'opaque': return null` are equivalent because the
+  exhaustive default also returns `null`; and
+- two mutations to the `default` branch are unreachable for the valid
+  discriminated union. Its `const _never: never = body` assignment is retained
+  so adding a family without a count remains a compile-time error.
 
 ### Why `verify.ts`'s faithfulness wrapper is NOT in the gated mutate set
 
@@ -199,8 +276,10 @@ the `catch` — which no *real* diagram exercises: a structured diagram's
 serialization always re-parses, and re-parses structured (not opaque), and never
 throws. Those branches are therefore unkillable through real `verifyMermaid`
 inputs without a synthetic drop, and the *decision logic* they guard already
-lives in `faithfulnessWarning`, which the incremental lane gates at 96%+. Adding
-the wrapper to the gated `mutate` would crater the score to ~27% and force either
+lives in `faithfulnessWarning`, which the incremental lane currently measures
+at 97.01%. Adding the wrapper to the gated `mutate` would crater the score to
+~27% and force either
 a meaningless break threshold or a pile of accepted survivors. So the wrapper
 stays out of the gated set and is recorded here as I/O-glue equivalents; its
-logic is covered where it actually lives.
+logic is covered where it actually lives, where the current measured score is
+97.01%.