Routing Anti-Patterns Registry

It checks a public list of repeated navigation mistakes, each a typed row with a stable id and a plain explanation. The system keeps a public list of navigation mistakes that agents repeat: reaching for grep before asking the kernel for a route, sending work to a bridge before the scope is chosen, or switching execution mode in a chat reply without updating the disk contract. Each mistake is one typed row with a stable id and a plain explanation. This component checks that list.

It confirms the rows hold their shape and the exported copy matches the source byte for byte, emitting counts, ids, and digests without copying the body or editing a route. It reads a copy of the routing registry, confirms the rows hold their declared shape, and confirms that the exported copy still matches the source byte for byte. It emits a result record carrying counts, ids, digests, and verdicts. It never copies the registry body text into that record, and it never edits a route.

Fixture checker, not a live router

It is a checker, not a router, and rejects any row that declares route or source authority even while describing a public anti-pattern. routing_anti_patterns_registry is a checker, not a router. A page that lists routing failures is easy to mistake for the thing that decides routes. This component refuses that role in code. A row may describe a public anti-pattern, but a row that declares route or source authority is rejected.

Purpose

Navigation fails quietly until named

Navigation can fail silently, as when an agent greps a wide tree instead of taking a kernel route, so naming the failures as typed rows lets a reader recognise them. A navigation system can fail quietly. An agent greps a wide tree when one kernel route would have narrowed it first, and nothing complains until the work is already off course. Naming these failures as typed rows lets a reader recognise them instead of rediscovering them.

A loose list is not trustworthy evidence

Duplicate ids, missing explanations, self-graded labels, or claimed route authority would break the list, so each failure mode becomes a named rejection. A loose list is not enough. If rows can carry duplicate ids, skip their explanations, grade themselves with a pre-written label, or quietly claim route authority, the list stops being trustworthy evidence. The component turns each of those failure modes into a named rejection, so a passing run means something specific.

How it works

Fixture and bundle entrypoints over one core

run checks the fixture with its negative cases and run-bundle checks the exported bundle with a source-copy manifest, both calling _build_result in a fixed order. Two entrypoints share one validation core. run checks the first-wave fixture, including its negative cases. run_routing_anti_patterns_bundle (the run-bundle command) checks the exported bundle, where a source-copy manifest is required and the negative cases are not present. Both call _build_result, which runs the checks in a fixed order.

Row shape, anchors, and forbidden fields

_payload_findings requires the routing_anti_patterns kind, uniquely-id'd rows with text and the three named anchors, and rejects authority overclaims, authority roles, and private fields. The row check is validate_copied_macro_registry_rows, which wraps _payload_findings. _payload_findings requires kind: routing_anti_patterns, a positive integer version, and at least one anti_patterns row. Each row must carry a stable unique id and explanatory text. When the positive fixture is checked, the three named anchors kernel_before_grep, bridge_before_scope, and mode_in_chat_only must all appear. It then walks every nested object and rejects three things: authority overclaims such as release_authorized, provider_calls_authorized, source_mutation_authorized, and route_policy_mutation_authorized; forbidden authority roles, where a row claims source_authority, route_authority, control_plane_authority, or a similar role; and private fields such as private_source_body, raw_seed_body, provider_payload_body, and secret_value.

Repair state derived from text, not labels

_route_repair_state_for_row derives each row's repair state from its own id and text rather than a baked label, keeping baked_expected_labels_sufficient false. One design choice sits in _route_repair_state_for_row. Rather than trust a label written into the row, the checker derives each row's repair state from the row's own id and text. kernel_before_grep only earns kernel_first_navigation if its text actually mentions grep, kernel, and route. A row that ships a pre-written label is recorded, and the field baked_expected_labels_sufficient stays false. The meaning stays grounded in text a reader can see, not in a self-asserted grade.

Source-copy digest and anchor accountability

_source_module_manifest_result streams a sha256 over each copied module, requires all declared digests and anchors to match, and blocks the run on any mismatch. The exported-bundle path adds source-copy accountability through _source_module_manifest_result. It requires source_module_manifest.json, checks that the import is classified copied_non_secret_macro_body, and confirms the manifest keeps body text out of the result record. For each listed module it streams a sha256 over the copied target with _sha256, requires the declared sha256, source_sha256, and target_sha256 to all match that digest, checks that the declared anchors appear in the copied body under source_modules/, and re-runs the row check over that copied body. A digest mismatch or a missing anchor blocks the run.

Secret scan and metadata-only result records

_build_result passes only when rows, negative cases, the secret scan, and the source-copy check all clear, then writes metadata-only records and a compact card. _build_result also runs a secret-exclusion scan over the input paths. It reports a pass only when the positive rows have no findings, no expected negative case is missing, the scan has no blocking hit, and the source-copy check is either clean or absent. _write_receipts then writes the result, board, and validation records, and result_card projects a compact card whose omission list names the full-payload keys it left out.

flowchart TD Run["run / run-bundle"] Build["_build_result"] Rows["validate_copied_macro_registry_rows shape + derived repair state"] Neg["_negative_findings six named rejections"] Src["_source_module_manifest_result sha256 + anchors"] Scan["scan_paths secret exclusion"] Status["status = pass or blocked"] Out["_write_receipts / result_card metadata-only records"] Run --> Build Build --> Rows Build --> Neg Build --> Src Build --> Scan Rows --> Status Neg --> Status Src --> Status Scan --> Status Status --> Out

Negative cases

The first-wave fixture ships six perturbations. Each must be rejected with its own error code: The first-wave fixture ships six perturbations. Each must be rejected with its own error code:

• missing_kind rejected with ROUTING_ANTI_PATTERN_KIND_REQUIRED
• duplicate_id rejected with ROUTING_ANTI_PATTERN_DUPLICATE_ID
• missing_text rejected with ROUTING_ANTI_PATTERN_TEXT_REQUIRED
• authority_overclaim rejected with ROUTING_ANTI_PATTERN_AUTHORITY_OVERCLAIM
• source_authority_masquerade rejected with ROUTING_ANTI_PATTERN_SOURCE_AUTHORITY_FORBIDDEN
• private_source_leakage rejected with ROUTING_ANTI_PATTERN_PRIVATE_SOURCE_FORBIDDEN

Negative cases as proof obligations

A run passes only when every expected case appears with its code and missing_negative_cases is empty, making the negatives proof obligations rather than illustrations. A run passes only when every expected case appears with its expected code and missing_negative_cases is empty. That makes the negative cases proof obligations, not illustrations.

Prior Art Grounding

From pattern catalogs to CLI usability

The registry follows the pattern and anti-pattern catalog tradition and CLI usability practice, requiring stable ids and explanatory text while staying below route-source authority. This registry follows the pattern and anti-pattern catalog tradition: name recurring failure shapes so future operators can recognise and avoid them. The Hillside patterns library is the positive pattern-language ancestor, and the software anti-pattern literature supplies the inverse move of documenting practices that look useful but produce bad outcomes. The routing-specific presentation borrows from CLI usability practice: the Command Line Interface Guidelines press for discoverability and clear errors, and this component applies that pressure to navigation failures by requiring stable ids and explanatory text while staying below route-source authority.

Validation Result record Path

From microcosm-substrate, check the public routing-registry diagnostic without writing tracked records:

What a pass proves and does not

A pass proves the public fixture, the six negative cases, and the copied-body digest floor, and does not make the registry a route source. A pass proves the public fixture, the six negative cases, and the copied-body digest floor. It does not make the registry a route source.