@afokapu/atdd-bun 0.1.0

package/HOOK_AUDIT.md

@@ -0,0 +1,22 @@
+# ATDD hook behavior inventory
+
+Audited: `.atdd/hooks/`, `src/atdd/coach/templates/hooks/`,
+`src/atdd/coach/commands/hooks.py`, and their hook/worktree tests.
+
+| Hook / behavior | Bun package decision |
+| --- | --- |
+| `pre-commit`: direct protected-branch commits | Port unchanged as Git policy. |
+| `pre-commit`: staged-file advisory warning | Reimplement as blocking, configurable micro-commit policy. |
+| `pre-commit`: ATDD branch registration | Exclude: state store/work-item orchestration. |
+| `pre-commit`: registry auto-heal | Exclude: ATDD registry mutation. |
+| `commit-msg`: mass-delete token/backstop | Reimplement with package policy and `[mass-delete-approved]`. |
+| `pre-push`: protected branches | Port unchanged as Git policy. |
+| `pre-push`: commits-per-push limit | Reimplement as package policy. |
+| `pre-push`: ATDD interpreter/version gate | Exclude: Python/ATDD runtime. |
+| `pre-push`: store mirror, tags, state/runtime bypasses | Exclude: ATDD state/runtime orchestration. |
+| `pre-push`: blast-radius validation | Reimplement using Bun enforcer profiles. |
+| `pre-merge-commit`: protected main/master | Port unchanged as Git policy. |
+| `post-commit`: blast-radius validation | Reimplement as advisory Bun validation. |
+| `post-commit`: agent-session capture | Exclude: ATDD state store. |
+| `post-merge`: reconciliation/self-upgrade | Exclude: ATDD state and package upgrade orchestration. |
+| post-checkout, post-rewrite, pre-rebase, Claude/GitHub hooks | Exclude: lifecycle, GitHub, or external runtime orchestration. |

package/PLANNER_PORT.md

@@ -0,0 +1,55 @@
+# Planner port boundary
+
+This package is Python-free for Bun enforcement. It deliberately does not claim
+to port ATDD's full planner yet.
+
+## Portable planner kernel
+
+The package ships 195 canonical convention nodes in `planner-nodes/` and
+21 schemas in `planner-schemas/`. It does not ship Python validator files:
+they are executable Python/pytest code, not portable package assets. Port each
+selected validator into Bun/TypeScript before enabling it in a `planner` profile.
+
+1. Plan artifact schemas and canonical paths: wagon, feature, WMBT, acceptance,
+   train, contract, interlocking, and journey-topology documents.
+2. URN and naming grammar, including wagon/feature/WMBT chains.
+3. Plan graph references: wagon-to-feature, WMBT-to-acceptance, train registry
+   and participant/sequence references, contract registry references.
+4. Static interlocking route declarations and their digest/registry invariants.
+5. Journey topology closure across interlockings, bound through artifacts produced by the selected train.
+
+## Port status
+
+Enabled in the Bun `planner` profile (clean against ATDD's current plan and with a
+dirty fixture per emitted rule):
+
+- wagon identity and duplicate wagon slugs;
+- wagon URN naming;
+- duplicate produced artifact and feature declarations;
+- produce/consume destination and source validity, including direct self-cycles;
+- duplicate contract and telemetry ownership.
+- train registry/document coherence in both directions.
+- journey continuation closure across reachable interlocking routes.
+
+The current source surface has 63 Python validator modules and 372 test cases.
+The remaining modules are deliberately not represented as inert Python or as a
+claim of parity. Each is admitted only after its applicability rules, clean real
+plan baseline, and fault cases are reproduced under Bun.
+
+These rules validate committed files and have no need for ATDD runtime state.
+
+## Not a package concern
+
+Do not port these into this package without a separate product decision:
+
+- interactive `atdd plan` sessions, ratify/author state, and generated issue bodies;
+- GitHub, local-store, coach, and runtime integrations;
+- ATDD substrate admission, rule binding, dispositions, or suppressions.
+
+They are orchestration capabilities, not Bun repository enforcement.
+
+## Parity requirement
+
+The current Python planner contains 197 convention nodes, 18 schemas, and 78 files
+under its validators surface. A TypeScript port is accepted only when each selected
+validator has a clean fixture, a fault fixture, and a Bun test proving both outcomes.

package/README.md

@@ -0,0 +1,256 @@
+# `@afokapu/atdd-bun`
+
+`@afokapu/atdd-bun` is a Bun-native ATDD enforcement package for repositories
+that keep their plan, acceptance evidence, tests, and implementation in the
+same Git history. It gives developers and coding agents fast local feedback,
+then runs the same checks in GitHub Actions.
+
+It does not require Python, the `atdd` executable, an ATdd state store, a
+global installation, or network access while enforcing a repository.
+
+## What it protects
+
+The package is an enforcer, not a planner or deployment platform. It checks the
+relationships that a plan makes explicit:
+
+```text
+plan / WMBT → acceptance → Bun test → implementation
+```
+
+Depending on the selected profile, it also checks the Bun code/test convention
+corpus, documentation policy, plan integrity, scoped planner validation, and
+interlocking rules.
+
+It deliberately does **not** claim that static links prove a test is
+semantically adequate. Where the package can establish only a structural link,
+its report says so. Deployment execution, cloud credentials, and release
+publishing remain repository-owned.
+
+## How a repository uses it
+
+A repository normally uses the package in three places:
+
+1. A local Bun test or command gives immediate feedback while work is underway.
+2. Git hooks prevent clearly invalid commits and pushes; they are convenience,
+   not merge authority.
+3. GitHub Actions runs the full policy. Protect the resulting required check in
+   the repository’s GitHub branch ruleset.
+
+The practical result is that an agent cannot quietly add production code without
+the plan/test links the repository has chosen to require, and a local hook is
+not the only thing standing between an invalid branch and `main`.
+
+## Install and first use
+
+When the package is published to the configured package registry, add it as a
+development dependency:
+
+```sh
+bun add -d @afokapu/atdd-bun
+```
+
+Run the complete installed policy from the repository root:
+
+```sh
+bun run atdd-bun all
+```
+
+`all` runs every enabled packaged detector. It is the command that CI uses for
+the local enforcement portion of its check. Run a focused profile directly—for
+example, `bun run atdd-bun planner` or `bun run atdd-bun traceability`—without
+an extra `profile` verb. `--profile <name>` remains available for compatibility.
+
+For a focused local test, register only the policy that matters to that test:
+
+```ts
+import { registerEnforcementTest } from "@afokapu/atdd-bun/register";
+
+registerEnforcementTest({
+  root: import.meta.dir + "/..",
+  profiles: ["traceability"],
+});
+```
+
+This makes a Bun test fail when plan → acceptance → test → implementation
+closure is broken, without enabling unrelated code-quality profiles.
+
+## Choose the enforcement scope
+
+Run `bun run atdd-bun help` to see the complete command list, or
+`bun run atdd-bun help --json` for an agent-readable command/profile inventory.
+
+Profiles describe *what is being checked*, rather than a technical detector
+name.
+
+| Profile | Use it when you need to check |
+|---|---|
+| `traceability` | plan acceptance, Bun test, and implementation closure |
+| `planner` | plan parsing/graph integrity plus the explicitly scoped planner rules |
+| `docs` | the optional documentation capability and its declared artifacts |
+| `coder`, `tester`, `security`, `architecture`, `metrics`, `runtime` | Bun source and test conventions for that concern |
+| `interlocking` | declared train/interlocking binding, infrastructure, and coverage |
+| `htmx` | htmx-specific source and test conventions |
+| `all` | the complete package policy, normally used by CI |
+
+The package ships the canonical planner-node corpus as planning reference, but
+does not pretend that every node is executable. The
+[planner enforcement scope](planner-nodes/ENFORCEMENT_SCOPE.yaml) identifies
+which rules have a Bun realization, which predicates are only partial, and which
+nodes are reference-only.
+
+The planner profile first validates recognized plan artifacts against the
+package-shipped JSON Schemas—wagon, feature, WMBT (including embedded
+acceptances), train, train interlocking, and journey topology. It then runs
+cross-artifact validators such as registry coherence, traceability, and
+cross-interlocking continuation closure. A journey starts at one interlocking;
+each reachable route must either terminate explicitly or continue, through an
+artifact produced by that route's selected train, to another interlocking. Exposed journeys also
+carry Station Master actions; the Bun interlocking family checks those actions resolve through
+`JOURNEY_MAP` to `JourneyRunner`, while internal journeys carry no public reachability obligation.
+Hooks, direct CLI use, and CI invoke this same profile and therefore share the
+same schema source.
+
+### Theme and contract registry
+
+Theme vocabulary belongs to the repository, not the package. When a plan uses
+themes, declare them in `plan/_themes.yaml`; only index `0: commons` is
+reserved. Every other index and kebab-case name is repository-defined.
+
+```yaml
+themes:
+  "0": commons
+  "1": orders
+  "2": inventory
+```
+
+Every contract is recorded in `contracts/_contracts.yaml` with its identity,
+path, theme, producers, and consumers. The planner profile checks that contract
+references resolve, registry paths exist, a contract identity begins with its
+declared theme, and cross-wagon artifacts have contract evidence.
+
+## Hooks: fast feedback, not merge authority
+
+Run the explicit repository bootstrap once in each worktree where you work:
+
+```sh
+bun run atdd-bun init
+```
+
+It creates `.githooks/` dispatchers, sets a worktree-local `core.hooksPath`,
+and generates `.github/workflows/atdd-bun.yml` when it is absent. It never
+overwrites another hook path or an existing generated workflow unless you
+explicitly pass `--replace`. Installing the dependency alone deliberately does
+neither: package installation must not mutate a repository through postinstall.
+
+Use `hooks install` or `ci init` when only one surface is wanted:
+
+```sh
+bun run atdd-bun hooks install
+bun run atdd-bun ci init
+```
+
+The hooks enforce protected-branch blocking, micro-commit limits, mass-delete
+approval, affected-area validation, and configured traceability. To inspect or
+remove that installation, use:
+
+```sh
+bun run atdd-bun hooks status
+bun run atdd-bun hooks uninstall
+```
+
+Hooks can be bypassed by Git and therefore are never the merge gate. The CI
+workflow and GitHub branch ruleset are the authority for merging.
+
+## CI: the merge gate
+
+Generate the repository-owned workflow with:
+
+```sh
+bun run atdd-bun ci init
+```
+
+This writes `.github/workflows/atdd-bun.yml`. It refuses to overwrite an
+existing workflow unless `--replace` is supplied. The generated workflow runs
+on pull requests, merge-queue merge groups, and pushes to `main`/`master`; it
+installs with `bun install --frozen-lockfile`, runs the locally installed package
+without `bunx`, runs `bun test`, and uploads reports when present.
+
+After generating it, configure the GitHub branch ruleset to require the workflow
+job before merging. `merge_group` is included so the same protection works with
+GitHub Merge Queue.
+
+## Linked worktrees for agent work
+
+An optional policy reserves one primary checkout for `main` and requires feature
+commits to happen in sibling linked worktrees:
+
+```text
+my-repo/
+  main/                    # primary checkout, on branch main
+  worktrees/feature-x/     # linked checkout, on branch feature/x
+```
+
+Enable the policy in `main/atdd-bun.yaml`:
+
+```yaml
+worktrees:
+  enabled: true
+  root: ../worktrees
+  primary_directory: main
+  primary_branch: main
+  require_linked_worktree: true
+```
+
+An agent starts one worktree per work item—not per commit:
+
+```sh
+# Run from my-repo/main/ while it is on main.
+bun run atdd-bun worktree start feature/x
+```
+
+That command creates `worktrees/feature-x`, creates the `feature/x` branch, and
+installs the package hooks there. Subsequent commits happen normally from that
+linked checkout. The hook rejects commits from the primary checkout, protected
+branches, detached heads, and linked checkouts outside the configured root.
+
+When the branch is merged into local `main`, inspect or safely retire it with:
+
+```sh
+bun run atdd-bun worktree status
+bun run atdd-bun worktree finish --delete-branch
+```
+
+`finish` refuses a dirty or unmerged worktree. It never removes a worktree just
+because a hook ran.
+
+Git stores linked-worktree metadata in `main/.git/worktrees/`; the linked
+checkouts themselves belong beside `main`, not inside `.git` or inside the
+primary repository working tree.
+
+## Release policy
+
+If a repository enables `release` in `atdd-bun.yaml`, this read-only command
+checks SemVer, a single release decision, release intent, and that the proposed
+version is greater than the latest reachable matching local Git tag:
+
+```sh
+bun run atdd-bun release check
+```
+
+It creates no tag, makes no network request, and does not publish anything.
+The separate optional release workflow is where a repository may create a tag or
+publish using its own credentials and registry configuration.
+
+## Verification of this package
+
+`bun test` runs the package’s real-Git fixtures and detector clean/dirty corpora.
+The suite proves that every declared convention output has a matching convention
+and a deliberate failing case; it also covers hook isolation, CI generation,
+planner scope, release validation, and linked-worktree policy.
+
+## Boundaries
+
+This package intentionally excludes ATdd’s Python runtime orchestration,
+registry/state reconciliation, GitHub API integration, cluster access, and
+deployment execution. Those capabilities may be configured around the package,
+but repository enforcement remains deterministic and locally runnable.

package/bunfig.toml

@@ -0,0 +1,2 @@
+[test]
+root = "tests"

package/conventions/coder.bun/coder.bun.boundaries-http-client.convention.yaml

@@ -0,0 +1,43 @@
+schema_version: 1.1.0
+rule_id: coder.bun.boundaries-http-client
+kind: rule
+status: active
+name: Outbound HTTP goes through the centralized client
+statement: >-
+  A module in the `domain/`, `application/` or `presentation/` layer MUST NOT call the platform `fetch()`
+  primitive or a bare `axios` call; outbound HTTP goes through the project's centralized, contract-driven
+  client. Bun realization mirroring `coder.vite.boundaries-http-client`; core obligation
+  `coder.boundaries.http-client`.
+terms:
+- term_id: centralized_client
+  text: >-
+    the project's contract-driven HTTP client, where retries, timeouts, auth headers, tracing
+    and error translation live.
+- term_id: bare_primitive
+  text: >-
+    a direct `fetch(` or `axios(` in a consumer layer — a call site with none of those, which
+    will not acquire them because nobody remembers it exists.
+content:
+  summary: >-
+    Flags a bare `fetch(`/`axios(` in a consumer layer, over masked source. Integration is excluded — that
+    is the client's own home.
+  normative_text: |
+    A centralized client is where retries, timeouts, auth headers, tracing and error translation live. Every bare `fetch` is a call site that has none of them and will not acquire them, because nobody remembers it exists.
+    In an htmx app this matters on the SERVER side particularly: the fragments a handler renders often depend on an upstream call, and a bare fetch there fails in a way the user sees as a blank swap.
+  fix_hint: |
+    Call the client in `integration/` and let it own the cross-cutting concerns.
+  exceptions:
+  - Test files and vendored/build directories are never scanned.
+  - Bare npm specifiers resolve outside the project graph and are not layer-checked.
+  - A file carrying no layer segment is outside these rules rather than in violation of them.
+metadata:
+  aliases:
+  # Mirrored rule-for-rule from coder.vite.boundaries-http-client
+  # Core obligation: coder.boundaries.http-client
+  - BUN-BOUNDARIES-HTTP-CLIENT-001
+  severity: 3
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_clean_architecture_detector

package/conventions/coder.bun/coder.bun.commons-application-no-integration.convention.yaml

@@ -0,0 +1,40 @@
+schema_version: 1.1.0
+rule_id: coder.bun.commons-application-no-integration
+kind: rule
+status: active
+name: Commons application modules do not import integration
+statement: >-
+  A module under a `commons/application/` or `shared/application/` tree MUST NOT import from the commons
+  `integration/` layer. Bun realization mirroring `coder.convex.commons-application-no-integration`; core
+  obligation `coder.commons.domain-layer-purity`.
+terms:
+- term_id: commons_application
+  text: >-
+    a module under `commons/application/` or `shared/application/` — orchestration over ports it
+    defines.
+- term_id: inverted_dependency
+  text: >-
+    reaching into integration from application, which welds orchestration to a specific
+    transport.
+content:
+  summary: >-
+    Flags an import from a commons application module that resolves into the integration layer.
+  normative_text: |
+    The application layer orchestrates through ports it defines. Reaching into integration inverts the dependency and welds orchestration to a specific transport, so changing the transport changes the orchestration.
+  fix_hint: |
+    Define the port in `application/` and let `integration/` implement it; the composition root supplies the implementation.
+  exceptions:
+  - Test files and vendored/build directories are never scanned.
+  - Bare npm specifiers resolve outside the project graph and are not layer-checked.
+  - A file carrying no layer segment is outside these rules rather than in violation of them.
+metadata:
+  aliases:
+  # Mirrored rule-for-rule from coder.convex.commons-application-no-integration
+  # Core obligation: coder.commons.domain-layer-purity
+  - BUN-COMMONS-APPLICATION-NO-INTEGRATION-001
+  severity: 3
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_clean_architecture_detector

package/conventions/coder.bun/coder.bun.commons-cross-feature-imports-in.convention.yaml

@@ -0,0 +1,39 @@
+schema_version: 1.1.0
+rule_id: coder.bun.commons-cross-feature-imports-in
+kind: rule
+status: active
+name: Commons features are not reached into from siblings
+statement: >-
+  A module at `commons/<layer>/<feature>/…` MUST NOT import directly into a SIBLING feature's internals;
+  cross-feature use goes through the layer root. Bun realization mirroring `coder.convex.commons-cross-
+  feature-imports-in`; core obligation `coder.boundaries.no-cross-wagon-imports`.
+terms:
+- term_id: commons_feature
+  text: >-
+    a directory under `commons/<layer>/`, whose internals belong to it alone.
+- term_id: layer_root
+  text: >-
+    the surface a feature deliberately exposes. Cross-feature use goes through it, or two
+    features are coupled through a path neither published.
+content:
+  summary: >-
+    Resolves each import and flags one whose target sits inside a different commons feature directory.
+  normative_text: |
+    A feature's internals are its own. The layer root is the surface it deliberately exposes, and reaching past it couples two features through a path that neither of them chose to publish — which is how a shared module quietly becomes unsplittable.
+  fix_hint: |
+    Import from the layer root, and if the thing you need is not exported there, that is the decision to make explicit — export it, or move it.
+  exceptions:
+  - Test files and vendored/build directories are never scanned.
+  - Bare npm specifiers resolve outside the project graph and are not layer-checked.
+  - A file carrying no layer segment is outside these rules rather than in violation of them.
+metadata:
+  aliases:
+  # Mirrored rule-for-rule from coder.convex.commons-cross-feature-imports-in
+  # Core obligation: coder.boundaries.no-cross-wagon-imports
+  - BUN-COMMONS-CROSS-FEATURE-IMPORTS-IN-001
+  severity: 3
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_clean_architecture_detector

package/conventions/coder.bun/coder.bun.commons-domain-no-framework-import.convention.yaml

@@ -0,0 +1,40 @@
+schema_version: 1.1.0
+rule_id: coder.bun.commons-domain-no-framework-import
+kind: rule
+status: active
+name: Domain modules import no runtime machinery
+statement: >-
+  A module in the `domain/` layer MUST NOT import runtime machinery (`bun:*`, `node:*`, `htmx`, `express`,
+  `fastify`, `koa`) nor reach the `Bun.` global. Bun realization mirroring `coder.vite.commons-domain-no-
+  framework-import`; core obligation `coder.commons.domain-layer-purity`.
+terms:
+- term_id: runtime_machinery
+  text: >-
+    `bun:*`, `node:*`, an HTTP framework, or the `Bun.` global — this stack's equivalent of the
+    UI frameworks the Vite sibling forbids.
+- term_id: server_free_domain
+  text: >-
+    the practical test: the domain must be runnable with no server started.
+content:
+  summary: >-
+    Flags framework/runtime import specifiers in a domain module, and any use of the `Bun.` global.
+  normative_text: |
+    The Vite sibling forbids react/preact/@tanstack/gsap because those are ITS frameworks. The obligation is identical — the domain expresses rules, not machinery — and only the list of machinery changes with the stack. For a full-stack Bun app the machinery is the server and transport primitives.
+    The practical test: the domain must be runnable with no server started. `Bun.` in a domain module means it is not.
+  fix_hint: |
+    Move the machinery to `integration/` and pass the result in. A domain function should take data and return data.
+  exceptions:
+  - Test files and vendored/build directories are never scanned.
+  - Bare npm specifiers resolve outside the project graph and are not layer-checked.
+  - A file carrying no layer segment is outside these rules rather than in violation of them.
+metadata:
+  aliases:
+  # Mirrored rule-for-rule from coder.vite.commons-domain-no-framework-import
+  # Core obligation: coder.commons.domain-layer-purity
+  - BUN-COMMONS-DOMAIN-NO-FRAMEWORK-IMPORT-001
+  severity: 3
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_clean_architecture_detector

package/conventions/coder.bun/coder.bun.commons-domain-no-outbound.convention.yaml

@@ -0,0 +1,41 @@
+schema_version: 1.1.0
+rule_id: coder.bun.commons-domain-no-outbound
+kind: rule
+status: active
+name: Commons domain modules import nothing outward
+statement: >-
+  A module under a `commons/domain/` or `shared/domain/` tree MUST NOT import from the commons
+  `application/` or `integration/` layers. Bun realization mirroring `coder.convex.commons-domain-no-
+  outbound`; core obligation `coder.commons.domain-layer-purity`.
+terms:
+- term_id: commons_domain
+  text: >-
+    a module under a `commons/domain/` or `shared/domain/` tree — the shared centre holding
+    rules.
+- term_id: outbound_import
+  text: >-
+    an import resolving into the application or integration layer. Dependencies point inward
+    only.
+content:
+  summary: >-
+    Flags an import from a commons domain module that resolves into the application or integration layer.
+  normative_text: |
+    Dependencies point INWARD only. The domain is the centre: it holds the rules, and it must not know what orchestrates them or what transports them.
+    An outward import inverts that and makes the rules unusable without the machinery — which shows up first as a domain test that needs a database.
+  fix_hint: |
+    Move the shared thing into the domain, or invert the dependency by defining a port in the domain that the outer layer implements.
+  exceptions:
+  - Test files and vendored/build directories are never scanned.
+  - Bare npm specifiers resolve outside the project graph and are not layer-checked.
+  - A file carrying no layer segment is outside these rules rather than in violation of them.
+metadata:
+  aliases:
+  # Mirrored rule-for-rule from coder.convex.commons-domain-no-outbound
+  # Core obligation: coder.commons.domain-layer-purity
+  - BUN-COMMONS-DOMAIN-NO-OUTBOUND-001
+  severity: 3
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_clean_architecture_detector

package/conventions/coder.bun/coder.bun.complexity-cyclomatic.convention.yaml

@@ -0,0 +1,51 @@
+schema_version: 1.1.0
+rule_id: coder.bun.complexity-cyclomatic
+kind: rule
+status: active
+name: TypeScript function cyclomatic complexity stays at or below 10
+statement: >-
+  Every TypeScript/TSX function MUST keep its cyclomatic complexity at or below 10, so the number of
+  independent paths through any one function stays testable. Stack-neutral obligation, NATIVE BUN
+  detector: the thresholds and the counting rule are transcribed from the python-pytest sibling
+  `coder.refactor.complexity-cyclomatic-typescript` and verified to produce identical numbers, so this
+  repo enforces its own metrics without a Python interpreter. Realized by `bun_ts_metrics_detector` (core
+  alias COMPLEXITY-CYCLOMATIC-TS-001).
+terms:
+- term_id: decision_point
+  text: >-
+    a construct adding an independent path: if / else if / for / while / do / catch / case, a
+    `&&` / `||` / `??`, or a ternary.
+- term_id: trivial_function
+  text: >-
+    a function under three code lines. Not scored, because a two-line arrow is not a complexity
+    problem.
+content:
+  summary: >-
+    Complexity is 1 plus each decision keyword (if / else if / for / while / do / catch / case), each
+    boolean or nullish operator (&& / || / ??) and each ternary. Functions under 3 code lines are skipped.
+  normative_text: |
+    The obligation and its arithmetic are unchanged from the Python realization — deliberately, because a repo that switches providers must not see its numbers move. What changes is only WHO runs the count.
+    Cyclomatic complexity is a proxy for how many test cases a function needs before its behaviour is pinned. Above roughly ten paths, complete coverage stops being written, and the untested paths are where defects settle.
+  fix_hint: |
+    Reduce the branching of the flagged function:
+
+      * extract nested decision blocks into named helpers,
+      * replace long if / else-if ladders or switch arms with a dispatch map,
+      * collapse compound &&/||/?? conditions into well-named predicates.
+  exceptions:
+  - Functions with fewer than 3 code lines are not scored.
+  - Test files and vendored/build directories are outside the scan.
+  - Pre-existing counts are held flat by a ratchet baseline, not by lowering the threshold.
+metadata:
+  aliases:
+  # COMPLEXITY-CYCLOMATIC-TS-001 is the SHARED core alias, also carried by the agnostic node and by
+  # its python-pytest realization. One obligation, two detectors, two runtimes.
+  - COMPLEXITY-CYCLOMATIC-TS-001
+  severity: 3
+  # `strict`, matching the python-pytest sibling exactly. A repo adopting this on an
+  # existing codebase records a ratchet baseline rather than lowering the threshold.
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_ts_metrics_detector

package/conventions/coder.bun/coder.bun.complexity-length.convention.yaml

@@ -0,0 +1,43 @@
+schema_version: 1.1.0
+rule_id: coder.bun.complexity-length
+kind: rule
+status: active
+name: TypeScript functions stay at or below 50 code lines
+statement: >-
+  Every TypeScript/TSX function MUST be at most 50 lines of code, excluding blank and comment lines.
+  Stack-neutral obligation, NATIVE BUN detector transcribed from the python-pytest sibling
+  `coder.refactor.complexity-length-typescript` and verified numerically identical. Realized by
+  `bun_ts_metrics_detector` (core alias COMPLEXITY-LENGTH-TS-001).
+terms:
+- term_id: code_line
+  text: >-
+    a line inside the function body that is neither blank nor a comment.
+- term_id: internal_seam
+  text: >-
+    a boundary inside a long function, usually marked by the comment introducing each block.
+    Each is a candidate helper whose comment is its name.
+content:
+  summary: >-
+    Counts non-blank, non-comment lines between the function's signature and its matching closing brace,
+    found by a string- and comment-aware brace matcher so a `}` inside a string never closes a body early.
+  normative_text: |
+    Length is the crudest of the three per-function metrics and the hardest to argue with: a function longer than a screen cannot be read as one unit, so it is read in fragments and its invariants are reconstructed from memory each time.
+    It catches a different fault from complexity. A long function may be perfectly linear — fifty sequential assignments score 1 on cyclomatic complexity — and still be doing five things that wanted names.
+  fix_hint: |
+    Split the function along its internal seams. The comment lines inside a long function usually mark them exactly: each block a comment introduces is a candidate helper, and its comment is the helper's name.
+  exceptions:
+  - Blank lines and comment lines are not counted.
+  - Test files and vendored/build directories are outside the scan.
+metadata:
+  aliases:
+  # COMPLEXITY-LENGTH-TS-001 is the SHARED core alias, also carried by the agnostic node and by
+  # its python-pytest realization. One obligation, two detectors, two runtimes.
+  - COMPLEXITY-LENGTH-TS-001
+  severity: 2
+  # `strict`, matching the python-pytest sibling exactly. A repo adopting this on an
+  # existing codebase records a ratchet baseline rather than lowering the threshold.
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_ts_metrics_detector