boxbox-plugin 0.0.0-stage → 0.2.8

package/payload/claude/plugin/skills/boxbox/references/charter.md

@@ -0,0 +1,72 @@
+# BoxBox Charter
+
+Status: confirmed (M1.8 S1) · Date: 2026-09-30
+
+This document is **layer 0** of the five normative layers. Grammar (layer 1), surface forms (layer 2), conventions (layer 3) and the example book (layer 4) all sit below it, and when they conflict with this document, this document wins. Only maintainers may change it.
+
+## Core (generating source)
+
+The three lines below are copied verbatim to the top of `SKILL.md` and into the marked section of a user repository's `AGENTS.md`. When the wording changes, the copies must change with it (pinned by a test in M1.8 S7).
+
+<!-- boxbox:core:begin -->
+1. Write same-role code in the same pattern. Code is language.
+2. Simplify first, align second. Never cover a reducible difference with whitespace.
+3. Fix automatically only whitespace, and only when certain. Suggest everything else.
+<!-- boxbox:core:end -->
+
+## 1. Principle — readability
+
+Let the reader follow the flow from top to bottom and compare same-role code vertically. Every rule in this product exists for this one sentence.
+
+## 2. Values — code is language
+
+- Code is made of **words** (names), **sentences** (one line's declaration, call or condition), **paragraphs** (groups of sentences with one purpose) and **texts** (files).
+- Write same-role sentences in **the same pattern**. Uniformity does not mean fitting every line to the longest one; it means giving the same role **the same minimal composition**.
+- Symbols such as `=`, `:`, `from` and `(` are **particles** that mark roles inside a sentence. Alignment lines up the particles of the same pattern vertically so the reader can scan roles column by column.
+- The same grammar serves both **guiding what gets written** (GUIDE) and **checking it** (REVIEW). The two must never look at different standards.
+- We also know the limits of this metaphor. Understanding code relies mainly on reasoning, not on language ability. So patterns are defined by **role**, not by English word order, and the goal is to reduce the reader's reasoning load.
+
+## 3. Identity — a deterministic program
+
+- boxbox is a **deterministic program**, and the agent plugin is a channel that calls it. Rules are set by the program and by human approval, not by an agent's judgment.
+- So it has what a program needs: a version, a config schema, exit codes, and a CLI that runs without an agent (CI, hooks, editors).
+- Users can change **conventions** (layer 3) and **examples** (layer 4) to their taste. **Invariants** (section 5) can be changed by no one. Users write only one file themselves, the config; everything else is written by tools and approved by people.
+
+## 4. Order — simplify first, align second, verify always
+
+*Simplify first. Align second. Verify always. — Follow the structure. Don't force it.*
+
+- Alignment is not the goal. A structure lengthened by an exceptional element is first removed, wrapped inward or normalized.
+- Only real, irreducible information is accepted as cell data and aligned at minimum width.
+- Covering a reducible difference with whitespace alignment, or letting whitespace pull semantic units apart, is a failure.
+
+## 5. Invariants — unchangeable and not configurable
+
+An attempt to turn off any item in this list through configuration is not silently ignored; it is a schema error. An item with an empty "enforced at" exists only as a documented promise, and moving it into code is roadmap work.
+
+| # | Invariant | Enforced at |
+|---|---|---|
+| 1 | **Only whitespace changes.** Automatic fixes touch only spaces, tabs and line breaks. Non-whitespace tokens, strings and comments must be byte-identical | `common/09_preservation.ts`, `typescript/16_token-preservation.ts`, `test/mutation.test.ts` |
+| 2 | **Output is re-parsed.** A fix is written only when the language's official parser rereads it with the same diagnostics | `common/08_parse-check.ts`, `typescript/07_align-tables.ts` |
+| 3 | **When uncertain, do not touch.** `REFUSE` when it cannot be split losslessly, `UNCERTAIN` when classification is ambiguous. A missed fix is better than a wrong fix | `REFUSE`: across the engine · `UNCERTAIN`: not implemented |
+| 4 | **Automatic fixes only for 3+ rows.** Two-row pairs are only suggested. The only exceptions are user-approved `=` declaration tables and imports | `common/06_table-engine.ts`, `typescript/13_grid-kinds.ts` `minRows` |
+| 5 | **Idempotent.** Running twice gives the same result | per-language alignment tests (`test/lang-harness.ts`) |
+| 6 | **Only relative placement is stored.** Width is always the minimum that table needs, and tables never share widths | `common/06_table-engine.ts` |
+| 7 | **Deterministic.** The same input and config give the same result. There is no LLM and no similarity search on the check/fix path. An LLM is used only to read guidance or to pre-sort the review queue | design rule (no reproduction test) |
+| 8 | **Only humans approve.** Evidence never becomes a rule by itself. Agents only investigate and propose | read-only agents: `test/plugin-contract.test.ts` · approval flow: not implemented |
+| 9 | **Layer priority:** safety > project > user > preset > base. Nothing overrides safety | not implemented (M1.8 S3–S5) |
+| 10 | **Single source, thin adapters.** The engine, grammar and conventions live in one place; hosts differ only in install location and manifest. The result JSON and pattern keys are versioned public contracts | `common/24_result-json.ts`, `common/02_signature.ts` |
+| 11 | **Runs last, after the formatter.** The canonical form of a file is `boxbox(formatter(file))`, and rerunning must not change it | not implemented (M2) |
+
+## 6. What this document does not do
+
+- It does not define concrete patterns, roles or rules → grammar (`grammar.md`), conventions (`presets/`, `.boxbox/rules/`).
+- It does not list the order in which tools are called → `SKILL.md`.
+- It does not describe the product structure or roadmap → `docs/development/design.md`.
+
+## 7. How to change it
+
+1. First write the reason and evidence for the change in `docs/development/plan.md`.
+2. A maintainer approves it.
+3. When an invariant changes, change the code and tests that enforce it in the same change.
+4. When the three core lines change, change the copies (`SKILL.md`, the marked section of the user's `AGENTS.md`) in the same change.

package/payload/claude/plugin/skills/boxbox/references/grammar.md

@@ -0,0 +1,147 @@
+# BoxBox Grammar
+
+Status: confirmed (M1.8 S2) · Date: 2026-09-30 · First scope: TypeScript, Python (Java is on hold; the Java column in the tables is for reference)
+Review: Codex cross-review applied (`docs/development/reviews/2026-09-30-codex-grammar-review.md`)
+
+This document is **layer 1** of the five normative layers. It sits below the charter (`charter.md`) and **defines every ID** used by surface forms (layer 2), conventions (layer 3) and the example book (layer 4). Lower layers cannot create IDs that are not in this document. This document defines **roles**, not the grammar of a particular language. Layer 2 decides which symbols and word order express each role in each language.
+
+IDs are written in English capitals and are never translated.
+
+## 0. Scope and premises
+
+- This grammar is for **sentences that become alignment targets** and for **the sentence shapes GUIDE recommends**. It does not claim to classify every sentence in code. Sentences that fit no pattern are left unclassified and untouched.
+- **The parser classifies first.** A pattern is a name attached to a structure the parser (AST, masked tokens) has confirmed. The "code is language" metaphor must never decide classification ahead of the parser and semantic analysis. Even with the same symbol shape, scope, control flow and side effects can differ.
+- If it cannot be confirmed, it is `UNCERTAIN` (charter invariant 3).
+
+## 1. Four units
+
+| ID | Unit | In code | What is checked | Automation |
+|---|---|---|---|---|
+| `WORD` | word | a name (identifier) | whether the role shows, whether the name matches the behavior | GUIDE |
+| `SENTENCE` | sentence | one line's declaration, call, condition or exit | whether it fits a pattern (section 3) | SUGGEST |
+| `PARAGRAPH` | paragraph | a group of sentences separated by blank lines | whether it has one purpose (section 4) | SUGGEST |
+| `TEXT` | text | a file, a function body | whether the paragraph order fits the genre (section 5) | GUIDE |
+
+**When the property differs, split the paragraph.** A sentence's property is its pattern (section 3) and, for a definition, its **declaration kind**. Put a blank line where the property changes. Examples: a group of value definitions (`const`) → a check (`WHEN`+`EXIT`) → a result (`EXIT`); in tests, a group of setup (`const`) → a group of assertions (`expect`).
+
+- **Declaration kind** uses only what can be determined reliably per language. The first criterion separates **declarations erased after compilation** (TypeScript `type`, `interface`, `import type`, `declare`) from **declarations that remain at run time** (`const`/`let`/`var`, `function`, `class`, `enum`). `class` and `enum` are also types but remain at run time, so they belong to the latter. Erased declarations are grouped separately instead of being slotted one by one between executed declarations.
+- **Observational information:** visibility (`export`) and reassignability (`const`/`let`) are not mandatory criteria for splitting paragraphs. Making them mandatory over-fragments paragraphs; `const` only forbids reassignment rather than making a value immutable; and Python has no matching marker. They are shown as information in reports, and conventions (layer 3) decide whether to split.
+- **Keep the original order.** The engine never reorders sentences. The basic principle is **preserving the original execution and evaluation order**, and dependencies (no use before declaration, TDZ) are one reason for it. Whether moving is safe differs by language: JavaScript function declarations are hoisted and erased types have no execution order, but Python's `def` evaluates defaults and decorators at definition time and module-level `import` can have side effects. So grouping by property goes only as far as inserting blank lines **within sentences that are already consecutive**, and proposals to move sentences are left to humans.
+- **Inserting a blank line is also a suggestion.** It changes only whitespace, but changing a paragraph boundary changes what the next alignment targets. Inserting automatically first requires verifying syntactic boundaries, behavior preservation, a fixed split criterion, invariance on rerun, and that splitting and aligning do not keep flipping each other. Line breaks inside strings or continued expressions are not targets.
+
+**Exception — a check right after a definition:** a guard that checks a name defined just above (`if (!found) throw …;` after `const found = …;`) stays in the same paragraph as the definition, because "find it, and refuse if missing" is one purpose (the extract → refuse ladder of the `ALGORITHM` genre has this shape too). If the guard checks a different name, it is not an exception.
+
+**Paragraphs and tables differ.** A paragraph is a group separated by blank lines, and one paragraph may hold sentences with several roles. Normally a **table** is **three or more consecutive sentences of the same pattern** within one paragraph, with documented declaration/import pair exceptions. Tables have independent widths and normally stop at blank lines or comments.
+
+**Scoped return-guard exception (2026-10-21 user clarification):** supported `WHEN` sentences of the form
+`if (condition) return value;` can share a return-start column across ordinary statements and blank lines in one
+immediate block. All statements retain their original order. Inner blocks calculate their own widths; their guards
+do not enter the outer table. Comments between statements, unsupported guards, unconditional exits and function/class
+declarations separate regions. See [column-sharing regions](readability-contract.md#column-sharing-regions).
+
+## 2. Roles and markers
+
+Sentences are made of **roles**, and roles show through **markers** (symbols). Markers work like grammatical particles: even when word order differs, the marker tells the role. Alignment lines up the markers of the same pattern vertically.
+
+**Roles are defined only within a pattern.** The same `:` is the marker after `KEY` in `MAP` and the marker after `NAME` in `DESCRIBE`. Pairs whose role boundaries look blurry (`NAME`/`TARGET`/`KEY`, `VALUE`/`RESULT`, `ITEM`/`ARGS`) are told apart only by the role lists in section 3, after the pattern is decided.
+
+| ID | Role | Used in patterns |
+|---|---|---|
+| `NAME` | a newly created name | `DEFINE`, `DESCRIBE` |
+| `TYPE` | a type | `DEFINE`, `DESCRIBE` |
+| `VALUE` | the value given to a name, target or key | `DEFINE`, `DESCRIBE`, `MAP`, `CHANGE` |
+| `KEY` | the left side of a mapping | `MAP` |
+| `ITEM` | one cell of a list | `LIST`, `IMPORT` |
+| `SOURCE` | where something is imported from | `IMPORT` |
+| `TARGET` | something that already exists (the receiver of a call, the thing that changes) | `DO`, `CHANGE` |
+| `ACTION` | the function or method called | `DO` |
+| `ARGS` | the values passed to a call | `DO` |
+| `CONDITION` | a condition, the match pattern of a `case` | `WHEN` |
+| `RESULT` | what is handed over when ending the flow (return value, thrown exception) | `EXIT` |
+
+The match pattern of a `case` differs from a general condition (value comparison, destructuring), but this grammar groups both under `CONDITION`. If they ever need to be told apart, this document changes to create a new role.
+
+## 3. Patterns (closed set, 9)
+
+| ID | Meaning | Roles (in logical order) | TypeScript | Python | Java |
+|---|---|---|---|---|---|
+| `IMPORT` | imports | ITEM · SOURCE | `import { a } from "m";` | `from m import a` | `import m.a;` |
+| `DEFINE` | defines | NAME · [TYPE] · VALUE | `const a = 1;` | (ambiguous, rule 2) | `int a = 1;` |
+| `DESCRIBE` | describes | NAME · TYPE · [VALUE] | `a: string;` | `a: str` | `private int a;` |
+| `MAP` | maps | KEY · VALUE | `a: handler,` | `"a": 1,` | — |
+| `LIST` | lists | ITEM… | `[1, 2],` | `(1, 2),` | `{1, 2},` · `RED,` |
+| `DO` | acts | TARGET · ACTION · ARGS | `log.info(a);` | — | — |
+| `CHANGE` | changes | TARGET · VALUE | `a = 1;` | `self.a = 1` | — |
+| `WHEN` | if the condition holds | CONDITION · (inner sentence) | `case A: …` | — | — |
+| `EXIT` | ends | [RESULT] | `return a;` · `throw e;` | `return a` | `return a;` |
+
+- `—` means that language's engine does not build tables of this pattern yet (layer 2's job). It does not mean the pattern is absent from the language.
+- `EXIT` covers `return`, `throw`, `break` and `continue`. An unconditional `return value` is `EXIT`, not `WHEN`. A guard (`if (x) return;`) is **a sentence with `EXIT` inside `WHEN`**.
+- The inner sentence of `WHEN` is another pattern (`EXIT`, `DO`, `CHANGE` …). `WHEN` only names the pairing of a condition and its inner sentence.
+
+### Decision rules (ambiguous cases)
+
+1. **An enumeration with values is `MAP`; names only is `LIST`.** `enum { A = 1 }` and `RED(1, 2)` are MAP, and `RED,` is LIST.
+2. **With a declaration marker it is `DEFINE`; if the target certainly exists already it is `CHANGE`; otherwise it is ambiguous.**
+   - Declaration markers: TypeScript `const`/`let`/`var`, Java type declarations.
+   - Certain `CHANGE`: assignment to a property or element (`a.b =`, `a[i] =`), assignment without declaration in TypeScript and Java.
+   - Python's `a = v` shares syntax between declaration and assignment. Until the parser confirms whether it is module level (indentation cannot tell: the inside of a module-level `if` is indented too), whether it is `global`/`nonlocal`, and whether the name is bound for the first time, it is **ambiguous**.
+3. **Ambiguous rows are never grouped into one table with certain rows.** When a certain `DEFINE` row and an ambiguous row are adjacent, the table is split. Whether a table of ambiguous rows may be fixed is decided by verdict (layer 4). Until a verdict exists, the current behavior is kept and the result is marked ambiguous.
+4. **The container decides the pattern.** `a: T = v` in a class body is `DESCRIBE` (a field with a default), and `a: T = v` inside a function is `DEFINE`. In an engine that does not know the container (the current Python line engine), it is ambiguous.
+5. **A new pattern exists only by changing this document.** It needs evidence (corpus table counts) and human approval. Conventions and examples cannot create patterns.
+
+## 4. Paragraph purposes
+
+States what a `PARAGRAPH` groups sentences for. Used when checking the order of a function body (text). **The levels are only SUGGEST and GUIDE; there is no automatic fix.**
+
+| ID | What it does | Patterns mainly used |
+|---|---|---|
+| `CHECK` | sends back the failing cases first | `WHEN` + `EXIT` |
+| `PREPARE` | gathers what is needed | `DEFINE` |
+| `DECIDE` | decides without side effects | `DEFINE`, `WHEN` |
+| `ACT` | changes the outside world | `DO`, `CHANGE` |
+| `RESULT` | returns | `EXIT` |
+
+**Verbs are only hints.** Lookup verbs (`find`, `get`) likely mean preparation and action verbs (`save`, `send`) likely mean acting, but often, as with `load` or `create`, the name alone cannot reveal side effects. If control flow and outputs cannot confirm it, the purpose is `UNCERTAIN`. Verb dictionaries differ by project, so they live in conventions (layer 3) and the example book (layer 4).
+
+Loop shapes (filter, find, collect, emit) are convention (layer 3) vocabulary, not grammar IDs, because their purpose spans several sentences rather than one line's pattern.
+
+## 5. Genres
+
+Order rules for a text (`TEXT`) differ by genre. Genres are set by config scopes (`scopes`).
+
+| ID | Text order | Examples |
+|---|---|---|
+| `BUSINESS` | CHECK → PREPARE → DECIDE → ACT → RESULT | services, handlers |
+| `ALGORITHM` | no order rule; an "extract → refuse" ladder is considered normal | parsers, alignment engines |
+| `TEST` | Arrange → Act → Assert | tests |
+| `CONFIG` | mostly `MAP` and `LIST`, no order rule | config, registration tables |
+
+Scopes without a genre get no order rule.
+
+## 6. Evidence (measured 2026-09-30)
+
+Every **table of three or more rows** in the pinned corpus and the stress corpus was counted and mapped to a pattern. These numbers concern sentences that became tables; they are not evidence that every sentence is explained by the nine patterns (section 0).
+
+| Pattern | TypeScript (7,214) | Python (879) | Java (162) |
+|---|---|---|---|
+| `DEFINE` | 3,367 | — | 154 |
+| `DEFINE` or `CHANGE` (ambiguous) | — | 301 | — |
+| `DESCRIBE` | 871 | 128 (including 26 container-ambiguous) | 2 |
+| `MAP` | 2,259 | 339 | — |
+| `LIST` | — | 111 | 6 |
+| `DO` | 602 | — | — |
+| `CHANGE` | 83 | — | — |
+| `WHEN` | 32 | — | — |
+
+- No table was left unmapped.
+- TypeScript and Python: the pinned corpus in `development/corpus/manifest.json` (vscode, prisma, trpc, zod, requests, fastapi, pydantic, django), at most 400 files per source.
+- Java: dropped from the first scope (2026-09-30). The table's numbers come only from five OpenJDK files in the stress corpus, chosen as the longest files and therefore biased, and are GPL so used for checking only. **Java distributions are not used as evidence until a permissively licensed Java corpus is pinned (M1.8 S2.5).**
+- `IMPORT` is handled by a separate step (`00_normalize-imports.ts`), so it is not counted. `EXIT` rarely forms tables of three or more rows, so it is not counted; it is used in GUIDE and paragraph checks.
+- 51.5% of TypeScript tables are inside function bodies. Patterns are used not only in declarations but also inside business logic.
+
+## 7. Open questions
+
+- Whether to introduce scope analysis (the official `ast` module) to separate Python `DEFINE`/`CHANGE`.
+- Classification priority of value shapes (value/computation, call/construction, `await`, object/array, `as`) when they overlap, as in `await f() as T`.
+- Whether to separate the match pattern of a `case` from `CONDITION`.

package/payload/claude/plugin/skills/boxbox/references/readability-contract.md

@@ -0,0 +1,311 @@
+# Readability Contract
+
+## Goal
+
+Compare code as rows, columns and cells, where uniformity means **giving the same role the same minimal composition**. First remove, bind or normalize structures that became long because of exceptions. Apply tabular alignment when three or more comparable same-role rows are contiguous. Make a table from two rows only when the user confirmed the comparison is useful. Column 120 is a signal to consider splitting a new structure, not a ceiling for dismantling an already accepted canonical grid. Alignment is not the goal in itself: covering a reducible structure with whitespace, or letting whitespace push semantic units apart, is a failure.
+
+Uniformity priorities:
+
+1. Give the same role the same structure and reading order.
+2. Check whether a foreign element mixed into the base form is a required contract or a structural leak.
+3. Simplify the structure by removal, internal binding, normalization or table splitting while preserving meaning and type safety.
+4. Accept only irreducible, real information as cell data and align it at minimum width.
+
+`The same minimal composition` does not mean abbreviating until meaning is lost. Remove only foreign elements that can go while preserving behavior, type safety and domain responsibility; keep necessary differences as explicit contracts.
+
+Therefore the longest code is not always the alignment basis. First decide whether that length is domain information, boundary information, an implementation detail or a duplicate expression, then use only the preserved longest data as the basis.
+
+## Top-to-bottom role structure
+
+- A feature implementation file puts the public features consumers look for first, then individual processing, then response conversion and validation. The reference order for a lookup adapter is `public feature → individual lookup → response conversion`. Do not add functions or sections just to fill a missing role.
+- Functions with the same role use the same reading order and naming scheme. Before reordering declarations, check initialization and registration order dependencies, and preserve execution order.
+- Rename abbreviations whose role must be decoded — `opts`, `res`, `d` — to role-revealing names such as `options`, `response`, `document`. Collections reveal their content and lookup key, as in `placesById`; do not mechanically lengthen idiomatic indices.
+- Apply reuse only to implementations with confirmed identical responsibility, input/output and failure contract. Do not merge lookups or conversions that merely look alike and thereby hide the call flow, and do not add wrappers that only forward names.
+- When applying these structural principles to other languages such as Kotlin, first check that project's declaration and lifecycle rules. Do not port the TypeScript column alignment and check commands verbatim.
+
+## Grid model
+
+- **Table**: a contiguous code block with the same syntax structure and comparison purpose.
+- **Row**: one declaration, property, import or execution flow.
+- **Column**: a repeated syntax boundary such as `:`, `( )`, `{ }`, `< >`, `=>`, `from`, `= await`, `//`.
+- **Cell**: the actual identifier, type, value, statement or note between columns.
+- **Sub-table**: an inner grid re-decomposed into name, separator and type when a repeated structure such as `:` appears again inside a cell.
+- **Alignment policy**: align contiguous repeated blocks of three or more comparable rows at minimum width. User-confirmed exceptions: `=` declaration tables and imports align from two rows. Other two-row groups are reported as pairs and never fixed automatically. Methods of a public Port split by JSDoc or different lifecycle responsibilities are not merged into one table. Per-field JSDoc does not by itself split same-role data fields: a required data record keeps its fields in one table. This authoring principle also applies beyond the implemented detector; record unsupported regions separately. Preserve the `import`, `:`, `=>` and `case` axes of a reference file accepted by the user. The inner width of `( )` in a repeated function table is set by the actual longest argument, not by existing spaces; only short values are centered within that minimum width.
+
+The public B-layout Align path changes horizontal layout only. It preserves non-whitespace tokens, comments, identifiers, their
+order, leading indentation, physical line count and the structural TypeScript AST. It may align an existing function
+call, but it never introduces a function or performs a C-level structural refactor. Authoring may choose line breaks or
+move a leading logical operator before this path; those changes require their own token/comment and structural-AST checks.
+
+## Column-sharing regions
+
+The matrix is defined by comparable syntax boundaries, not by whole-line length. A condition and a callee can have
+different widths while their corresponding `return` or call parentheses share a column. Scope the comparison first,
+then compute minimum widths from the cells in that region. A different expression is not automatically a different role.
+
+- **Early-return guards:** treat the start of `return` in `if (condition) return value;` as the `guard-return` gap axis.
+  In one immediate block, three or more supported guards can share that column across ordinary statements, including
+  declarations and loops, and blank lines. Preserve every statement in place. Only immediate sibling guards contribute
+  to the column width; a nested block owns its own widths. Comments between statements, unsupported guards (including
+  `else`), unconditional return/throw/break/continue and function/class declarations separate regions. A trailing
+  comment also separates that statement from the next guard region. The final
+  unconditional return is a different role.
+- **Different callees:** consecutive supported call-valued declarations can share their outer `(` and `)` columns even
+  when callee names or arities differ. The argument list is one cell in this outer table; compatible same-call rows can
+  additionally share inner argument columns. A trailing non-null assertion stays attached after `)`. Empty `()` stays
+  attached and unsupported wrappers keep their own shape. `declaration-call-envelope` has the declaration two-row floor.
+- **Member-call boundary:** split a supported property callee into `receiver | . | method`, then its call parentheses.
+  `call-member-dot` aligns the final receiver/method separator when at least two rows have that role. For example,
+  `Array.from` and `rows.filter` share the dot column as well as the parentheses. In `registry.rows.filter`, the receiver
+  is `registry.rows`; its inner dot remains inside that cell. A bare function has no member-dot cell. Decimal points,
+  string contents, optional chains and dots inside arguments are different syntax and are not matched to this axis.
+- **Property rows:** a property header keeps its `name | :` comparison when its value continues on later lines.
+  Shorthand properties participate in the same property run without inventing a `:` boundary.
+  A multiline value's terminal punctuation belongs to that value; it does not widen a comma column on unrelated
+  one-line properties. Within the retained region, each consecutive run of at least three ordinary one-line explicit
+  properties computes its own minimum-width colon, value-start and comma columns. Remaining explicit and multiline
+  headers share a fallback family; shorthand contributes only its existing comma gap and never gains a colon or a
+  missing comma. Families are ordered by source: the first uses unsuffixed axes and later families use suffixes `2`,
+  `3`, and so on. Only a three-or-more ordinary one-line explicit family exposes `property-value`. Blank lines and
+  interstitial comments split the comparison region.
+- **Function parameters:** an already vertical `FunctionDeclaration` list with at least three contiguous one-line
+  identifier parameters is a `vertical-function-parameters` table. Typed rows share `parameter-colon`, defaulted rows
+  share `parameter-equals`, and existing separators share `parameter-comma`. Each axis needs two occurrences within
+  the three-or-more-row table; two defaulted rows do not create a two-row table exception. The last parameter keeps
+  its original comma presence. Optional names and generic declarations keep their syntax. Destructuring, rest,
+  parameter modifiers, comments, multiline types/defaults, blank lines and shared opening/closing lines exclude the
+  whole list rather than exposing a supported subset. A declaration spanning at least three distinct parameter rows
+  reports that exclusion as `REFUSE` with its original parameter range; shorter and single-line lists are not candidates.
+  Arrow functions and methods are outside this kind. Parameter
+  descriptions map to `DESCRIBE`; detection and guidance do not grant public write approval.
+- **Logical chains:** an existing multiline homogeneous `||` or `&&` chain uses `operator | one space | optional ! |
+  operand`. The operator cell is two characters and the negation cell is either one `!` or empty. `!=` and `!==` are
+  indivisible comparison operators, and `!!value` stays opaque. A virtual first-row operator/negation prefix is an
+  authoring aid only; public Align never inserts it or moves an operator across lines.
+- **Conditional call arguments:** declarations with the same callee and arity may align a compatible comparison or
+  conditional expression at the same argument position. This nested layer has the declaration two-row floor; ordinary
+  kinds still need three rows. Callee, arity, argument position and expression shape must match. An incompatible nested
+  expression drops the layer rather than broadening the parent table. Inside a larger heterogeneous declaration group,
+  recursively detected disjoint runs of two or more adjacent compatible declarations form local
+  `declaration-call-expressions` subgroups. The outer `declaration-equals` group keeps its `equals`/`semicolon` axes and
+  legacy approval identity; each local subgroup owns only its call and comparison/conditional axes. A wholly compatible
+  declaration group keeps the existing whole-group path. Local subgroup detection is not approval, so an unknown subgroup
+  remains blocked from public writes.
+- **Adjacent `if` headers:** three or more adjacent same-family headers may align even when a one-line condition has a
+  multiline body. Blank lines and interstitial comments split the run. Braced rows align `)` and `{`; unbraced-return
+  rows align `)` and `return`. The two forms are separate families, and alignment never inserts braces.
+- **Exceptional type shapes:** in an authorized Refactor, keep ordinary interface properties in a compact table and
+  put nested object type members in their own paragraphs, below the ordinary fields when the type contract permits it.
+  Expand their nested properties into independent tables. Preserve names, readonly/optional modifiers and member types.
+  Runtime declarations and object initializers retain their evaluation order; separate a dependent exceptional expression
+  in place instead of moving it below its consumers. A new type alias needs a domain reason beyond shortening a column.
+
+The return-guard region is an explicit exception to contiguous-row grouping. Other kinds keep their existing grouping
+rules. These authoring choices and engine detection do not create public write approval: new group/axis lookup keys
+still require their own proof. Report checked columns and unsupported regions separately.
+
+## Confirmed rules
+
+1. Modify only one product file at a time.
+   Files the user designated as close to canonical are excluded from modification and read only as a comparison basis.
+2. Imports separate runtime and type roles, and paths inside `src` use the `@/` alias. Splitting a named import that mixes values and `type` specifiers into `import` and `import type` declarations changes tokens and belongs to a separate Write/Refactor normalization path; the layout-only import authoring path refuses and reports it. A single named specifier always stays on one line; two or more fold onto one line when the completed line's display width is 120 or less. Only above 120 do they break into one item per line, with the closing `}` and `from` on the same line. All brace imports of an import section (groups separated only by blank lines) form one table: the head cell always reserves the `import type` width, so `{` sits in one column; the fixed-width `{ }` cell (names left-aligned one space after `{`), `from`, the module specifier and the terminating `;` share columns across every group. An import goes vertical — one name per line on the names column, aligned commas, and the closing `}` on the table's `}` column — when (A) its one-line form exceeds 120 columns, (B) its names are 20+ columns wider than the second-widest names, or (C) the aligned table still exceeds 120 columns, taking the widest names first. Preserve whether the original final named specifier has a trailing comma in both compact and vertical form. Imports without braces (default only, namespace, `defer`, side-effect, `import x = require`) and imports with attributes stay as written without breaking the table; a lone brace import stays compact. Files without semicolons get no `;` column. When applying the alias to a new boundary, also verify the architecture import graph.
+3. Split a table block into cells by syntax units: identifier, `:`, `( )`, `=>`, `{ }`, `< >`, `= await`, `from`, trailing `//`.
+4. Unify each cell at the minimum width required by the longest actual content in the same block. Left-align feature/function identifiers and execution cells. Never create an arbitrary column farther than the actual longest row.
+5. Parentheses, braces and angle brackets are each independent outer boundaries. In the same comparison block, align both opening and closing symbols. The inner width is set by the longest actual single-line content; short and empty values sit inside that fixed width.
+6. When type parameters push a line past column 120, break one parameter per line.
+7. Repeated syntax inside an outer cell is also aligned as a sub-table when there are two or more comparable rows. Recompute the width of a function-argument cell from the actual longest value. Center short values within that width; write empty arguments attached as `()` and put the leftover width outside the parentheses. Do not reuse existing unnecessary inner spaces as a width basis.
+8. Keep the `{ }` of production destructuring as a fixed-width cell. The imported callable identifiers are function names, so left-align them one space after `{` with leftover width on the right. Align the closing `}` and the following `= await` column on every row.
+9. The body `{ }` of a one-line arrow function is an execution block, not a value cell. Align the opening `{` and the start column of the last statement, but end the last call at its actual length. Put exactly one space after the terminating `;` and close with `}`; add no trailing spaces to align the closing brace column.
+10. Group production dependencies by role — run, list, select, write. Do not arbitrarily break the accepted `const { } = await import(...)` and execution-cell axes of the reference file into multiple lines.
+11. A trailing note is the last open cell. Align the `//` start column across role sections in the same declaration table. Keep the minimum width of preceding cells such as `Promise< >` and move `//` only with the outer space after the statement terminator. Left-align the note one space after `//`; add no right padding to equalize note lengths.
+12. Repeated implementations are one line by default. Break into two lines at a semantic boundary only when a line becomes excessively long; do not expand short rows wholesale.
+13. Keep a dependency interface as one interface and split roles with `// Run`, `// List`, `// Select`, `// Write` section comments. Do not split the type into per-role interfaces.
+    Each role section is an independent table. The widths of `( )`, `Promise< >`, `;` and `//` are computed only from the actual longest value inside the section; do not borrow a long type from another section as a width basis.
+14. Do not extract function signatures into named local types just to reduce table width. In the same comparison block, use the longest actual signature as the width basis as is. Split out a type only when it has an independent domain meaning or reuse contract.
+15. Before repeating an inline object type, find and reuse an existing Domain or Port type that owns the same meaning. The purpose of naming a type is to reveal an existing contract's meaning, not to shorten rows.
+16. Column header comments above a table use only ASCII labels such as `NAME`, `PARAMETERS`, `RETURN TYPE`. CJK display width varies across terminals and editors, so it is not used as reference data for column positions. The header's syntax boundaries and sub-cell start columns must match the actual code rows.
+17. When a long exceptional element is found, check its definition, callers and tests before aligning. Information consumers do not choose — such as a parameter passed as the same constant at every call — should be considered for removal from the interface and binding inside the implementation adapter.
+18. Structural simplification must preserve meaning and type safety. Removing required inputs, merging different contracts, or adding a type alias just to look shorter is not simplification.
+19. Uniformity does not force the longest exception's width onto every row. When an element that differs from the base rows widens the whole table, first consider moving it to a separate row, a separate table or the internal implementation; include it in the common width only when it cannot be separated semantically.
+20. `?` does not mark something for removal; it means omission of the value is part of the contract. Keep it only where omission is really possible at the input boundary, and narrow to a concrete type as early as possible inside, via condition checks, defaults and normalization. On a public or boundary interface where the meaning of omission is not obvious from the name, a short `/** JSDoc */` right before the property owns that meaning, and its exposure is verified with an actual property hover.
+21. Do not mix `null` and `undefined` for the same absent state. Express explicit results such as a user cancel with `null`, and a missing object property with `?`. When code appears to convert between the two across layers, revisit the boundary contract.
+22. For `!` on array indices and `as` on wide values, first check whether a local variable and a conditional branch can remove them. An assertion that silences the checker without runtime evidence is not simplification.
+23. Do not alias primitives that are already short and clear, such as `void`, `string`, `boolean`. Give a short, specific name to a long, repeated composite type only when it has an independent domain meaning.
+24. Supplementary documentation of named types and public optional properties is owned by a `/** JSDoc */` right before the declaration. String literals and trailing `//` are not hover documentation; find the actual declaration with the TypeScript LSP `textDocument/documentSymbol`, then confirm the documentation appears in the `textDocument/hover` response. Specify same-name declarations as `name#occurrence`, and fail ambiguous requests or requests without JSDoc.
+    However, consecutive local type aliases that are not exported are grouped into a `type / name / = / actual type / ; / // note` table. That note is for in-file navigation and does not replace the public hover contract.
+25. Record the minimal common form of the repeated rows first. When a type modifier, extra parameter, wrapper, absence expression or conversion code absent from the base form appears, do not adopt it as the width basis immediately; classify it as a foreign element.
+26. Judge each foreign element as one of `required domain information`, `boundary-only information`, `implementation detail`, `duplicate expression`. Keep boundary information near the boundary, implementation details inside, and remove duplicate expressions.
+27. Do not accept a structural change just because it looks shorter. Accept it as simplification only when the base form actually became more uniform and behavior, type safety and layer responsibility were preserved.
+28. With `exactOptionalPropertyTypes` off, `property?: T` also accepts an explicit `property: undefined`. Inspect property omission and explicit `undefined` at call sites separately, and unify on omission when they mean the same absence. Keep `| undefined` as an explicit contract only when a different meaning is confirmed.
+29. For optional tightening, first run `04_audit-optional-types.ts` as a read-only migration gate. The default run requires zero errors, and `--max-errors <current baseline>` fails on any increase. `--file <target file>` keeps the global verdict while separately reporting line, column, error code and diagnostic message for that file. Enable it in `tsconfig.json` only after confirming zero total errors and passing related behavior tests; never pass the gate by appending `| undefined` wholesale.
+30. The population for the uncertainty audit is extracted from the TypeScript AST by `03_audit-type-uncertainty.ts --file <target file>`. It reports optional properties, parameters, methods, tuples and types, `null`, `undefined`, non-null assertions, definite assignments, `as` and angle-bracket assertions as distinct kinds. Logical negation and the conditional operator are not listed; the output is not an automatic removal list, and each item is judged from definitions, callers and tests.
+31. A feature implementation file may carry a function map at the top (`GROUP | FUNCTION | INPUT | RETURN | CALLS | ROLE`). FUNCTION maps 1:1 to declarations in the file, the INPUT count must match the parameters, and names listed in CALLS must exist in the file. Drift between map and code is locked by the `09_function-map.ts` check. GROUP and ROLE follow the sections and roles of the reading flow. The repository-wide flow summary is still owned by audit documents under `docs/`.
+32. Public Port and Domain contracts default to compact TypeScript notation. Do not add role comments to a method list that mixes JSDoc, optional capabilities and lifecycle responsibilities to create a fake table, and do not pad type internals to align the closing `>` of `Promise< >`. This exception does not apply merely because an ordinary data field has JSDoc; same-role data fields retain their common name, colon and type columns.
+33. In a same-role object array, each object is one row. When omitting an optional property is merely a presentational default, normalize every row to the same property cells and align `{`, each `:`, each `,` and `}` to the actual longest value. When the omission itself carries domain meaning, do not overwrite it with an explicit value; split it into a separate table.
+34. An object-based column specification and the generation of data rows for those columns are independent tables. Do not nest the two tables inside complex call arguments; split each into a named local value and keep the call site minimal, as in `{ columns, rows }`.
+35. The terminating `;` is no longer attached as an exception. Within a table, align its column to the actual longest value like any other column. One-line execution blocks where `}` immediately follows `;` (rule 9) remain a separate case and are not overridden by this rule.
+36. A standalone statement with no rows to compare against (fewer than three same-role repetitions, so no table forms) is not split vertically for alignment. Short flows originally read as one line, such as `if (condition) run() return`, prefer the compressed one-line form.
+37. In interface and class member declarations, one member owns one physical row. Do not chain several property or method declarations on the same row with `;`, hiding the table's row boundaries. Short public contracts are no exception.
+38. In authoring, a homogeneous guard or validation chain with at least four operands may be split into a multiline condition with `||` or `&&` at line start. Column 120 is an authoring consideration, not a generic wrapping trigger, and an accepted canonical grid stays intact. Mixed operators, `!!`, comments and other unsupported shapes are reported for manual judgment. This layout rule does not create predicates, functions or wrappers; any such refactor is a separately authorized structural change.
+39. In a separately authorized Refactor, do not inline feature slots (approvalPreview, reconciliation, execute, ...) inside anonymous ternaries or conditional spreads. Extract each slot into one named local function so it reads top to bottom, and leave the assembly point in the minimal form `...(write ? { approvalPreview, reconciliation } : {})`. B-layout only reports this structural opportunity.
+
+## Column anchors
+
+Before writing a repeated block, decide the cells and syntax axes to compare. Besides object arrays, registration objects and local computation declarations are in scope.
+
+- **Registration objects**: one entry is one row. Split into `property name | : | expression` and align `:` and the expression start column. Inside repeated `new` or `scroll(new …)`, compare constructor names and argument parentheses as sub-cells. Do not force a lone exceptional wrapper onto other rows as a width basis.
+- **Consecutive declarations**: in `const | name | = | expression` of the same computation step, align `=` and the expression start column. A multi-line array initialization is a separate table and does not share axes with local declarations inside callbacks or with other computation steps.
+- **Check scope**: identify every such block in the change diff and pass each block's line range, tokens and expected columns to the measurer. Passing some blocks is not passing the file. Leave unchecked blocks marked as unchecked.
+
+## Column alignment check steps
+
+Proceed to the next step only after the current one passes. Do not adjust a later step's whitespace first and blur an earlier step's boundaries.
+
+1. **Confirm comparison blocks**: group only contiguous rows with the same role and syntax structure into one table.
+2. **Record the base form**: record the minimal structure and reading order shared by the most common normal rows as the table's base form.
+3. **Judge exceptional elements**: check definitions and callers to decide whether the longest row's type, parameters and return value are a required contract or an implementation detail reducible by binding into the adapter or removing duplication.
+4. **Simplify structure**: classify foreign elements as required domain information, boundary information, implementation detail or duplicate expression, and consider removal, internal binding, default normalization and table splitting in that order.
+5. **Judge type uncertainty**: find `?`, `null`, `undefined`, `!` and `as`, and classify them as real absence contracts, duplicate expressions or removable assertions. Give names and JSDoc only to meaningful composite types.
+   With `exactOptionalPropertyTypes` off, count optional-property omission and explicit `undefined` arguments separately, and normalize same-meaning arguments in the current file to omission.
+6. **Align outermost boundaries**: fix the columns of `:` after identifiers, outer `( )`, `=>`, the outer `{ }` of function bodies, statement-ending `;` and trailing `//`, left to right.
+7. **Compute widths**: compute each cell's width only from the minimum required by the actual content preserved after simplification. Split multiple parameters per line first, and use the longest line as the basis. Close an empty parameter list as `()` and align the column up to the next syntax boundary with outer padding.
+8. **Align inner constructs**: once outer boundaries are fixed, align the start columns of repeated inner constructs such as `import`, `from`, `const`, `= await`, and the final `await`/`return`.
+9. **Place content**: left-align feature/function names and execution cells. Write empty `()` and array markers `[]` without inner spaces. Measure an object array as one outer row from the opening `{` to the closing `}`, and confirm that every preserved property's `:` and separating `,` share a column.
+10. **Handle overlong rows**: consider splitting a new row over column 120 at a semantic boundary. Do not change an accepted grid in a reference file without user confirmation.
+11. **Verify by measurement**: confirm the selected short repeated blocks and JSDoc exposure with the display-width and hover measurers. Confirm with execution, type checking and target tests that behavior did not change.
+
+## Authoring axis contract — the single basis for prompts and checks
+
+Code is written **from the moment of authoring** with the axis columns below already aligned. Before completion, the checker applies a second lock. This table maps 1:1 to the `KIND_AXES` registry in `13_grid-kinds.ts`. The registry owns implemented axis identifiers; the accepted readability contract and the user's confirmed reference own the intended layout. When they differ, investigate detector coverage and rule scope. Zero registered groups and reviewer agreement do not override an accepted reference.
+
+Each newly supported shape or axis set has a new kind and suppresses any overlapping legacy region. Detection never
+widens an older approval key: approval remains exact to kind and ordered axes. Public whole-file writes are denied when
+an applicable changed group lacks approval, even when a legacy kind covering nearby syntax was approved.
+
+- **Gap axis** — leave at least one space before the token. Within a table, pad with spaces up to the actual longest value to align the column.
+- **Insert axis** — preserve existing TypeScript conventions. Do not pry apart attached tokens (`)`, `):`, `":`); padding goes outside.
+- A table normally needs three or more contiguous same-role rows, with the documented declaration/import pair exceptions.
+  The scoped return-guard exception is defined in [column-sharing regions](#column-sharing-regions). The bounded
+  `documented-data-members` kind also permits attached per-field JSDoc in an interface made entirely of required,
+  identifier-named data properties on their own physical lines, with JSDoc on preceding comment lines. Blank paragraphs, ordinary comments and different readonly modifiers split its runs.
+  Methods, optional capabilities, explicitly callable types, nested object/mapped types, classes and type literals retain their existing
+  boundaries. Other kinds stop at blank lines, comments and JSDoc. Conditional-type `:`, `for` header `;`, empty statements and unsupported one-line
+  execution blocks are not alignment targets.
+- Axis names use the checker registry identifiers verbatim. Core names include `colon` (`:` after a name), `equals` (`=`), `semicolon` (`;`), `comma` (`,`), `comment` (trailing `//`), `open-paren` (`(`), `close-paren` (`)`), `case-colon` (case label `:`), `call-paren` (first call `(` in a case row), `subject-close-paren` (call-statement subject `)`), `matcher-dot` (right-hand matcher `.`), `matcher-open-paren` / `matcher-close-paren` (matcher argument cell), `return-tail` (start of a bare `return;`), `value` (expression start), and `open-brace` / `close-brace` (object row `{ }`). New-kind identifiers appear verbatim in the table below.
+
+| Kind | Gap axes | Insert axes |
+|---|---|---|
+| declaration | `:` , `;` | `//` |
+| declaration-equals (declaration table with `=`) | `:` , `=` , `;` | `//` |
+| declaration-values (every initializer a string, number, boolean or null) | `:` , `=` , `;` | `//` |
+| declaration-call-envelope | `colon`, `equals`, `semicolon` | `call-member-dot`, `call-envelope-open`, `call-envelope-close`, `comment` |
+| declaration-call-expressions | `colon`, `equals`, `call-arg{i}`, `list-value-comma{i}`, `list-value-el{i}`, `list-arg{i}-comma{i}`, `list-arg{i}-el{i}`, `comparison-operator{i}`, `comparison-right{i}`, `conditional-question{i}`, `conditional-true{i}`, `conditional-colon{i}`, `conditional-false{i}`, `semicolon` | `call-open-paren`, `call-comma{i}`, `call-close-paren`, `list-value-open`, `list-value-close`, `list-arg{i}-open`, `list-arg{i}-close`, `subscript-close`, `comment` |
+| return-guards | `guard-return` | — |
+| if-headers-braced | `if-open-brace` | `if-close-paren` |
+| if-headers-return | `if-return` | `if-close-paren` |
+| logical-chains | `comparison-operator{i}`, `comparison-right{i}` | `logical-operator`, `logical-not`, `logical-operand` |
+| vertical-call-arguments | — | `vertical-call-comma` |
+| type-alias | `=` , `;` | `//` |
+| method-signature · class-method | — | `(` , `)` , return `:` , `//` |
+| interface-members · class-members · type-members (`type X = { ... }`) | `:` , `=` , `;` | `//` |
+| documented-data-members (bounded required interface data fields with attached JSDoc) | `colon`, `member-type` | `semicolon`, `comment` |
+| enum-member | `=` , `,` | `//` |
+| case-clause | — | case `:` |
+| object-rows (`{i}` per property position) | property start `{i}` , `:{i}` , `value{i}` start , `,{i}` , `}` | `{` , tail `tail` (`,` `;` `)` `as const`) |
+| object-properties | `property-colon`, `property-value`, `property-comma`, `property-colon{i}`, `property-value{i}`, `property-comma{i}` | — |
+| registration | `:` , expression start , trailing `,` | — |
+| assignments (`this.x = y;` assignment table) | `=` , `;` | `//` |
+| call-statements (`expect(…).toBe(…);` call-statement table) | `;` | subject `)` , matcher `.` , matcher `(` , matcher `)` , `//` |
+| literal-array-rows (one scalar literal per line in a `const` array asserted `as const`) | existing `,` | — |
+
+Authoring examples — all identical to the checker's `--write` output:
+
+```ts
+const alpha : string  = "a"  ;
+const beta  : number  = 22   ;
+const gamma : boolean = true ;
+
+type AppOptions      = RunOptions             ;
+type SessionList     = RecentSessionSummary[] ;
+type ThreadSelection = string | null          ;
+```
+
+```ts
+	runFirst (first: string                ): Promise<void>;
+	runSecond(second: number, extra: string): void;
+	listAll  ()                             : Promise<string[]>;
+
+	dashboard : new DashboardRail(get, synthetic),
+	workflow  : new WorkflowRail(get, synthetic),
+	context   : new ContextRail(get, synthetic),
+
+	Low    = 1   ,
+	Middle = 22  ,
+	High   = 333 ,
+
+	case "a"  : return "first";
+	case "bb" : return "second";
+	case "ccc": return "third";
+```
+
+Insert-axis conventions — things the checker never reverts, however the code is written:
+
+- Empty parameter lists stay attached as `()`, are excluded from `)` alignment, and keep their padding outside the parentheses.
+- Return types attach to `)` as in `): Promise<void>`. The `:` of `case "a":` also attaches to the label.
+- Between rows with long and short parameter lists, the `)` column is aligned only by widening the inner space right after `(` and right before `)`.
+
+Two-point lock:
+
+1. **Authoring time (prompt)** — when an LLM or a person writes code, they write it in the form of the table and examples above. Agent definitions use SKILL.md as their manual, so this section is the prompt.
+2. **Completion time (check)** — every changed TypeScript file passes the selected import check
+   (`00_normalize-imports.ts --layout-only` for B-layout; the default full normalizer for an authorized
+   Write/Refactor). Every changed TypeScript or Python file passes its language aligner
+   (`typescript/07_align-tables.ts --file` or `python/02_align-tables.ts --file`, `misaligned=0`). If you want a form that cannot pass both checks, change this contract first.
+
+## Grid-first authoring
+
+Alignment normalizes rows that already share a structure. When you write new code, design the structure first: before
+writing a group of three or more same-role values, name the column set they share, then write each value as one row of
+that set. Do not write them in whatever shape is convenient and hope the aligner can pair them afterwards. This is
+advisory structural guidance, not approval data: it never authorizes an automatic write, and Align stays whitespace-only.
+
+| Situation | Row form that keeps the columns shared |
+|---|---|
+| Several values read from one source (options, config, request fields) | One reader family with one argument shape, defaults passed explicitly: `name = readX(source, "key", default)`. A value with a different role (`write = flag && !other`) is derived on its own line after a blank line. |
+| An object literal with several fields | One field per row: `key : value ,`. Do not leave the whole object on one long line. |
+| The same operation over several lists | One row per list: `name = list .map(item => transform(item))`. Move the part that differs into a named transform so the rows keep one shape. |
+| A branch that picks between two implementations | Pick the function in one row (`const run = flag ? a : b;`) and let both return the same record, so the code after it is the same rows for either path. |
+| A report assembled from parts | `[name, value]` pairs or one row per section, joined once. |
+| Per-item results folded into totals | One row per fold over the same list: `runs.map(…)`, `runs.flatMap(…)`, `runs.some(…)`. |
+
+Limits — these keep grid-first from becoming padding by other means:
+
+1. A row must carry data the code needs. Do not add wrappers, parameters or helpers whose only job is to fill a column, and
+   do not merge roles that merely look alike (see the reuse rule above).
+2. A different role is a different region: derived values, guards, early returns and control flow stay outside the table.
+   Keep a side-effecting callback outside a value-row table unless an independently justified function already exposes
+   the needed result; grid shape alone never justifies a wrapper.
+3. Preserve behavior: execution order, when errors surface, and output bytes. Verify a rewrite of existing code by comparing
+   the old and new versions on the same inputs, not only by running the existing tests.
+4. Hot paths: `.map` chains and tuple arrays allocate. Use them freely for configuration, reporting, CLI glue, test data and
+   pipelines that run once per item of work; measure before using them in code that runs millions of times.
+5. Report what the grid cannot hold. A row or a region that cannot share the columns is a visible exception, not a failure.
+
+## Discarded rules
+
+- Do not place `=>` or comments in an arbitrary column farther than the longest row.
+- Do not force statements with different meanings into one column across the file just because they share a token.
+- Unrelated blocks do not share one maximum width. Cell widths are computed only within the current block being compared.
+- Do not change the whole repository at once like an automatic formatter.
+- Do not create center alignment with no comparison value, or arbitrary widths wider than the actual longest data.
+
+## Interface split criteria
+
+Dependencies that one consumer receives all at once, such as `CliDependencies`, stay as a single interface.
+
+- `Run`: starts execution or delegates a command.
+- `List`: looks up multiple items.
+- `Select`: receives a user selection.
+- `Write`: outputs to the user.
+
+Expose each role with a section comment such as `// Run`. Inside a section use execution-flow order; do not reorder alphabetically. Do not create empty sections such as `Read` to fill a role that does not exist.