@afokapu/atdd-bun 0.1.0

package/conventions/coder.bun/coder.bun.runtime-single-lockfile.convention.yaml

@@ -0,0 +1,56 @@
+schema_version: 1.1.0
+rule_id: coder.bun.runtime-single-lockfile
+kind: rule
+status: active
+name: Bun's lockfile is the only lockfile
+statement: >-
+  A repository whose package manager is Bun MUST NOT carry `package-lock.json`, `yarn.lock` or
+  `pnpm-lock.yaml` alongside `bun.lock`/`bun.lockb`. Two lockfiles mean two resolvers disagree about
+  the dependency graph, and which one wins is decided by whichever command a developer or CI step
+  happens to run. This is the Bun-stack realization of the agnostic "dependency resolution has one
+  source of truth" obligation, enforced by the `bun_fullstack_detector` family implementation on
+  `atdd.workspace.bun`.
+terms:
+- term_id: foreign_lockfile
+  text: >-
+    `package-lock.json` (npm), `yarn.lock` (Yarn), `pnpm-lock.yaml`/`.yml` (pnpm) — a resolution record
+    written by a package manager that is not this stack's.
+- term_id: resolution_drift
+  text: >-
+    the state where two lockfiles pin different versions of the same transitive dependency, so the
+    installed tree depends on which tool ran last. It is invisible in review because nobody reads a
+    lockfile diff.
+content:
+  summary: >-
+    A "one lockfile" repo-hygiene obligation. The realization is a zero-dependency Bun detector that
+    walks the declared scan roots for foreign lockfile BASENAMES and reports each at line 1 — the file
+    itself is the fact, so there is no line to point at.
+  normative_text: |
+    This is the cheapest rule in the extension to satisfy and one of the most expensive to violate,
+    because its failure mode is the "works on my machine, breaks in CI" class that costs hours per
+    occurrence and is never attributed to its actual cause.
+    It also matters more during a migration than after one. A repo moving to Bun will pass through a
+    window where the old lockfile is still committed, and that window is exactly when the two graphs
+    diverge — someone runs `npm install` out of habit, the trees fork, and the divergence is discovered
+    much later in a failing deploy.
+  fix_hint: |
+    Delete the foreign lockfile and let Bun own resolution:
+
+      rm package-lock.json     # or yarn.lock / pnpm-lock.yaml
+      bun install              # regenerates bun.lock from package.json
+
+    Add the foreign names to `.gitignore` so a stray `npm install` cannot reintroduce one. `strict`.
+  exceptions:
+  - A vendored or fixture lockfile inside an excluded tree (`node_modules`, `dist`, `build`,
+    `_generated`) is never scanned.
+  - A monorepo package that is deliberately NOT on Bun should be scoped out via the consumer scope map,
+    not suppressed here.
+metadata:
+  aliases:
+  - BUN-SINGLE-LOCKFILE-001
+  severity: 3
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_fullstack_detector

package/conventions/coder.bun/coder.bun.runtime-typecheck-enforced.convention.yaml

@@ -0,0 +1,91 @@
+schema_version: 1.1.0
+rule_id: coder.bun.runtime-typecheck-enforced
+kind: rule
+status: active
+name: A TypeScript Bun project actually typechecks its types
+statement: >-
+  A Bun project containing TypeScript sources MUST have a typechecker it can run and MUST wire a
+  no-emit typecheck into its check path — TypeScript (or an equivalent native preview) as a
+  dependency, a `tsconfig.json`, and some script that runs a no-emit typecheck. Bun executes `.ts`
+  by STRIPPING types; it transpiles and never checks, and it bundles no `tsc`. Absent this, a Bun
+  stack is by default less type-safe than a tsc-based one.
+terms:
+- term_id: typechecker
+  text: >-
+    a tool that verifies types without emitting output — `tsc --noEmit`, `tsgo --noEmit`,
+    `vue-tsc`, `svelte-check`, `astro check`, or `tsc --build`. The obligation is that types ARE
+    checked; WHICH checker is the project's business.
+- term_id: check_path
+  text: >-
+    the scripts a developer or CI runs to validate the project. A typecheck that exists but is
+    never invoked is not wired in — it is a tool sitting beside the build, not part of it.
+- term_id: demonstrably_not_strict
+  text: >-
+    a `tsconfig.json` that either sets `"strict": false` outright, or enables no flag of the strict
+    family AND extends no base config. A tsconfig that `extends` something is NOT judged: this
+    rule's detector cannot resolve the base, and reporting what it cannot see would be a false
+    positive.
+- term_id: disposition_rationale
+  text: >-
+    advisory because this states a stack norm rather than a defect, and because the consuming
+    projects have not been surveyed. The measurement below was TAKEN on 2026-09-06, not recalled.
+  values:
+    measured_2026_09_06: >-
+      0 consumer Bun projects surveyed. This hub is a package repository and contains no Bun
+      application to measure — its own .ts files are deliberately-wrong detector fixtures, which
+      is exactly why this rule is authored for consumers and never run against the hub.
+    measurement_target: afokapu/atdd-extensions @ main (the hub itself — deliberately not a consumer)
+    measurement_command: "find official -name '*.ts' -not -path '*/fixtures/*' | wc -l"
+    escalate_when: >-
+      A consumer Bun project has been surveyed, typescript + a wired no-emit typecheck are present,
+      and the team accepts blocking on it. Escalating to strict is a MAJOR change class.
+content:
+  summary: >-
+    Bun's own gap, stated as a convention. `bun test`, `bun install`, `bun build`, `Bun.serve` and a
+    TS/JSX transpiler all ship; a typechecker does not. So `resolveTrain()` can return something
+    structurally wrong and Bun will run it happily.
+  normative_text: |
+    THIS IS COMPLEMENTARY TO THE OTHER BUN DETECTORS, NOT OVERLAPPING, and the distinction is the
+    reason the rule exists. Every detector in this stack is regex-over-source: they verify SHAPE.
+    `coder.bun.interlocking-resolution-model-exists` confirms an `InterlockingResolution` declaring
+    its eight fields is present — it cannot confirm that what `resolveTrain` actually returns
+    conforms to it. Only a typechecker can, and only if one is actually run.
+
+    DELIBERATELY UNFORCED, in four ways. This rule states a norm, not a blessed incantation:
+
+      SCOPE       only a tree that is genuinely a TypeScript project — a package.json AND at
+                  least one .ts/.tsx source. A JS-only Bun app carries no obligation at all.
+      HOW         any recognised no-emit typechecker in any script satisfies it, as does a
+                  script simply named `typecheck` / `check-types` / `types`.
+      WHERE       TypeScript counts from `dependencies` or `devDependencies`.
+      STRICTNESS  reported only when demonstrably off. A tsconfig that `extends` a base is left
+                  alone, because the detector cannot resolve the base and a rule that reports
+                  what it cannot see is worse than one that stays quiet.
+
+    WHERE IT APPLIES. The consumer repository, never this hub. The hub is a package repository: it
+    has no Bun application, its detectors are `.mjs`, and its `.ts` files are deliberately-wrong
+    fixtures that must NOT typecheck — `fixtures/dirty/interlocking_resolution_model/...` exists
+    precisely to be malformed.
+  fix_hint: |
+    Three small additions to a consumer project:
+
+      package.json   "devDependencies": { "typescript": "^5.6.0" }
+                     "scripts": { "typecheck": "tsc --noEmit",
+                                  "check": "bun run typecheck && bun test" }
+      tsconfig.json  { "compilerOptions": { "strict": true, "noEmit": true } }
+
+    Any equivalent satisfies it — `svelte-check`, `astro check`, `vue-tsc`, or extending a strict
+    base config. What must not happen is types being stripped and never checked anywhere.
+  exceptions:
+  - A Bun project with no TypeScript sources is out of scope entirely.
+  - A tsconfig that `extends` a base config is never reported for strictness (see terms).
+  - This hub is not a consumer and is never scanned by this rule; its .ts files are fixtures.
+metadata:
+  aliases:
+  - BUN-TYPECHECK-ENFORCED-001
+  severity: 2
+  disposition: advisory
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: coder.bun.runtime-typecheck-enforced

package/conventions/coder.bun/coder.bun.security-hardcoded-secret.convention.yaml

@@ -0,0 +1,50 @@
+schema_version: 1.1.0
+rule_id: coder.bun.security-hardcoded-secret
+kind: rule
+status: active
+name: No secret literals in source
+statement: >-
+  Source MUST NOT contain a secret literal — an AWS access key id, a PEM private-key header, or a password
+  / api-key / token assigned a literal string. Stack-neutral obligation, and one of only two rules in this
+  family that PORTS verbatim: the five patterns in the python-pytest sibling `coder.security.hardcoded-
+  secret` are language-neutral, because `password = "..."` and a PEM header look identical in Python and
+  TypeScript. Realized by `bun_security_hygiene_detector` (core alias SECURITY-HARDCODED-SECRET-001).
+terms:
+- term_id: secret_literal
+  text: >-
+    a credential written into source: an AWS key id, a PEM private-key header, or a password /
+    api-key / token assigned a literal string.
+- term_id: rotation_not_deletion
+  text: >-
+    the actual remedy. Git keeps a committed secret, so removing the line does not fix it.
+content:
+  summary: >-
+    Scans source and templates for the five transcribed secret patterns. `.example` / `.sample` /
+    `.template` files are documentation and are skipped.
+  normative_text: |
+    A committed secret is not fixed by deleting it, because git keeps it. It is fixed by ROTATING it, which is why detection has to happen before the commit rather than in review.
+    The rule reads assignment shape rather than entropy, so it catches the realistic case — someone pasting a working key to get unblocked — and deliberately does not attempt to judge whether a random-looking string is secret.
+  fix_hint: |
+    Move the value to the environment and read it at the edge:
+
+      const apiKey = "sk_live_0123456789abcdef";   // wrong
+      const apiKey = process.env.API_KEY;            // right
+
+    If the literal was ever committed, rotate it — removing the line is not enough.
+  exceptions:
+  - "`.example`, `.sample` and `.template` files are placeholders, not secrets."
+  - Vendored and build directories are never scanned.
+  - Values read from `process.env` are never literals and are not matched.
+metadata:
+  aliases:
+  # SECURITY-HARDCODED-SECRET-001 is the SHARED core alias, also carried by the agnostic node and its
+  # python-pytest realization.
+  - SECURITY-HARDCODED-SECRET-001
+  severity: 4
+  # PORTED verbatim from the python-pytest sibling — the pattern is
+  # language-neutral, so both providers produce the same findings.
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_security_hygiene_detector

package/conventions/coder.bun/coder.bun.security-missing-auth.convention.yaml

@@ -0,0 +1,53 @@
+schema_version: 1.1.0
+rule_id: coder.bun.security-missing-auth
+kind: rule
+status: active
+name: State-changing routes perform an authorisation check
+statement: >-
+  A route handler for POST, PUT, PATCH or DELETE MUST perform an authorisation check in its body. Stack-
+  neutral obligation, RE-REALIZED for Bun: the python-pytest sibling matches a FastAPI decorator whose
+  signature carries `Depends(get_current_user)`. Bun has neither decorators nor a DI container — routes
+  are entries in the `routes` object of `Bun.serve` or branches of a `fetch` handler, and authorisation is
+  an ordinary call. Realized by `bun_security_hygiene_detector` (core alias SECURITY-MISSING-AUTH-001).
+terms:
+- term_id: mutating_route
+  text: >-
+    a POST, PUT, PATCH or DELETE handler. GET is out of scope: a public read is normal in a
+    hypermedia app.
+- term_id: authorisation_step
+  text: >-
+    a recognisable guard call inside the handler body. The rule asks whether the author
+    considered auth here at all, not which helper they used.
+content:
+  summary: >-
+    Finds each mutating route entry or `req.method === "POST"` guard, brace-matches ITS handler body, and
+    reports the handler when no recognisable authorisation call appears inside it.
+  normative_text: |
+    Mutating methods only, deliberately. A public GET is normal in an htmx application — it is how fragments load — so requiring auth on reads would produce noise on the most common route in the codebase. A mutating handler with no auth call is the shape that leaks writes.
+    The set of recognised auth calls is broad on purpose. The rule asks whether the author thought about authorisation at this handler at all; it is not trying to enforce one blessed helper, and a project with its own guard should add that name rather than suppress the rule.
+  fix_hint: |
+    Call the guard first, and let it throw or return early:
+
+      POST: async (req) => {
+        const user = await requireUser(req);   // authorise before any write
+        ...
+      }
+
+    The check must be inside THIS handler — auth performed in a sibling route protects nothing.
+  exceptions:
+  - GET and HEAD handlers are out of scope (reads).
+  - A handler delegating to a wrapper that authorises internally should call it by a recognised name, or the wrapper name should be added to the rule.
+  - Test files are excluded.
+metadata:
+  aliases:
+  # SECURITY-MISSING-AUTH-001 is the SHARED core alias, also carried by the agnostic node and its
+  # python-pytest realization.
+  - SECURITY-MISSING-AUTH-001
+  severity: 4
+  # RE-REALIZED, not ported: the python-pytest sibling inspects a Python
+  # AST for constructs this stack does not have. Same obligation, new detector.
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_security_hygiene_detector

package/conventions/coder.bun/coder.bun.security-sql-injection.convention.yaml

@@ -0,0 +1,54 @@
+schema_version: 1.1.0
+rule_id: coder.bun.security-sql-injection
+kind: rule
+status: active
+name: SQL is parameterised, never interpolated or concatenated
+statement: >-
+  SQL passed to a query sink MUST NOT be built by interpolating a template literal or concatenating
+  strings. Stack-neutral obligation, RE-REALIZED for Bun: the python-pytest sibling walks a Python AST for
+  `execute` / `executemany` / `raw` / `execute_sql` and its own manifest scopes it "python stack only".
+  Bun's sinks are `bun:sqlite` (`query` / `run` / `exec` / `prepare`), `Bun.sql` and the postgres/mysql
+  clients. Realized by `bun_security_hygiene_detector` (core alias SECURITY-SQL-INJECTION-001).
+terms:
+- term_id: query_sink
+  text: >-
+    a call that executes SQL: bun:sqlite's query / run / exec / prepare, or a postgres/mysql
+    client method.
+- term_id: tagged_template
+  text: >-
+    `sql`…`` — a template invoking a function that PARAMETERISES each substitution. Safe by
+    construction, and visually almost identical to the untagged form that is not.
+content:
+  summary: >-
+    Flags a query-sink call whose first argument is a template literal containing both a SQL keyword and a
+    `${}` interpolation, or a quoted SQL string followed by `+`.
+  normative_text: |
+    The load-bearing subtlety is that a TAGGED template is safe and an untagged one is not, and they look almost identical:
+
+        sql`SELECT * FROM orders WHERE id = ${id}`      // safe — Bun.sql BINDS the value
+        db.query(`SELECT * FROM orders WHERE id = ${id}`)  // injectable — the value is spliced
+
+    A tagged template invokes a function that parameterises each substitution; an untagged one produces a string before the sink ever sees it. The detector therefore flags only the second shape. This distinction has no Python analogue at all, which is why the rule had to be re-realized rather than translated.
+  fix_hint: |
+    Use the tagged template or explicit parameters:
+
+      db.query(`SELECT * FROM orders WHERE id = ${id}`)      // wrong
+      db.query("SELECT * FROM orders WHERE id = ?").get(id)  // right — bound parameter
+      await sql`SELECT * FROM orders WHERE id = ${id}`        // right — Bun.sql binds
+  exceptions:
+  - Tagged templates (`sql`...``) are parameterised by construction and are never flagged.
+  - Template literals with no SQL keyword are not SQL and are skipped.
+  - Static SQL with no interpolation is not injectable.
+metadata:
+  aliases:
+  # SECURITY-SQL-INJECTION-001 is the SHARED core alias, also carried by the agnostic node and its
+  # python-pytest realization.
+  - SECURITY-SQL-INJECTION-001
+  severity: 4
+  # RE-REALIZED, not ported: the python-pytest sibling inspects a Python
+  # AST for constructs this stack does not have. Same obligation, new detector.
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_security_hygiene_detector

package/conventions/coder.bun/coder.bun.station-master-interlocking-routing.convention.yaml

@@ -0,0 +1,62 @@
+schema_version: 1.1.0
+rule_id: coder.bun.station-master-interlocking-routing
+kind: rule
+status: active
+name: Station Master routes both direct and interlocking journeys, delegating to TrainRunner (Bun)
+statement: >-
+  The Station Master composition root (`server.ts`) MUST support both direct train routing and
+  interlocking-enabled routing: its `JOURNEY_MAP` MUST admit a direct `trainId` string AND an
+  `{interlockingId, path}` route object, and when an interlocking route is present the Station Master MUST
+  reference `InterlockingRunner` and ultimately reference `TrainRunner` for the selected train. This is
+  the Bun-stack realization of the agnostic core obligation
+  `coder.train.station-master-interlocking-routing` (core afokapu/atdd#1251); the JS detector that
+  enforces it is the atdd.workspace.bun implementation referenced below.
+implementation:
+  type: validator
+  ref: coder.bun.station-master-interlocking-routing
+content:
+  summary: >-
+    An agnostic "Station Master is wired for interlocking" obligation, rendered for the Bun application.
+    The JS realization scans `server.ts`: when JOURNEY_MAP declares an interlocking route object, the
+    module MUST reference `InterlockingRunner` (else unlinked) and `TrainRunner` (else no delegation).
+    Member of the `bun_interlocking_infrastructure` FAMILY detector (checks/interlocking_station_routing.mjs).
+  normative_text: |
+    Core runtime spec afokapu/atdd#1251 — the additive call model:
+
+        Station Master -> InterlockingRunner.resolveTrain(action, inputs, state)
+                       -> TrainRunner.execute(selectedTrainId, ...)
+
+    The existing direct mapping (`JOURNEY_MAP[action] = "<trainId>"`) remains valid; the interlocking
+    mapping (`{interlockingId, path}`) is additive. In BOTH cases the final train execution is performed
+    by TrainRunner. A Station Master that declares an interlocking route but never routes through
+    InterlockingRunner, or never reaches TrainRunner, breaks the contract. WHICH entrypoint is inspected
+    and HOW the routing is recognized is the per-stack detector's concern.
+  fix_hint: |
+    Route through the runner and delegate:
+
+      import { InterlockingRunner } from "./trains/interlocking";
+      import { TrainRunner } from "./trains/runner";
+      export const JOURNEY_MAP = {
+        start_match: "train:match:solo-match-complete",                       // direct
+        resolve_match: { interlockingId: "...", path: "...yaml" },            // interlocking
+      };
+      // interlocking branch: new InterlockingRunner(path).execute(...) -> TrainRunner.execute(...)
+
+    This rule is `strict`: an unlinked or non-delegating Station Master is not suppressible and fails CI.
+  exceptions:
+    - Applies only when JOURNEY_MAP declares at least one interlocking route object; a pure direct-train
+      Station Master carries no interlocking obligation.
+metadata:
+  aliases:
+    - BUN-STATION-MASTER-INTERLOCKING-ROUTING-001
+  severity: 4
+  disposition: strict
+  introduced_in: 0.1.0
+  core_design_refs:
+    - afokapu/atdd#1246
+    - afokapu/atdd#1251
+terms:
+  - term_id: station_master
+    text: >-
+      the composition root (`server.ts`) whose JOURNEY_MAP routes both direct trainId strings and
+      interlocking route objects, referencing InterlockingRunner and ultimately calling TrainRunner.

package/conventions/coder.bun/coder.bun.station-master-journey-routing.convention.yaml

@@ -0,0 +1,49 @@
+schema_version: 1.1.0
+rule_id: coder.bun.station-master-journey-routing
+kind: rule
+status: active
+name: Station Master reaches exposed journey topology through JourneyRunner (Bun)
+statement: >-
+  Every journey document with entrypoint.exposed=true MUST be reachable from the Bun Station Master
+  composition root. Each declared entrypoint action MUST appear in server.ts JOURNEY_MAP as a
+  {journeyId, path} mapping to that journey document, and the Station Master MUST reference
+  JourneyRunner. Internal journeys (entrypoint.exposed=false) carry no Station Master reachability
+  obligation. This closes the public entry direction for the higher-order journey topology without
+  weakening the existing direct-train or direct-interlocking mappings.
+implementation:
+  type: validator
+  ref: coder.bun.station-master-journey-routing
+content:
+  summary: >-
+    Binds journey declaration -> Station Master reachability -> JourneyRunner. It reads
+    plan/_journeys/**/*.yaml, selects exposed journeys, and verifies that each declared action maps
+    to the same journey_id/path in JOURNEY_MAP and that server.ts references JourneyRunner.
+  normative_text: |
+    The Station Master admits three additive route forms:
+
+        action -> "train:<subject>:<slug>"
+        action -> { interlockingId, path }
+        action -> { journeyId, path: "plan/_journeys/<id>.yaml" }
+
+    For a journey route the call boundary is:
+
+        Station Master -> JourneyRunner(journeyPath) -> InterlockingRunner -> TrainRunner
+
+    The journey document is authoritative for continuation topology. JOURNEY_MAP only establishes
+    external reachability; it must not restate continuation edges.
+  fix_hint: |
+    For every exposed journey action, add a JOURNEY_MAP entry whose journeyId and path point to the
+    declared journey document and dispatch it through JourneyRunner.
+  exceptions:
+    - Journeys with entrypoint.exposed:false are intentionally not Station-Master-reachable.
+metadata:
+  aliases:
+    - BUN-STATION-MASTER-JOURNEY-ROUTING-001
+  severity: 4
+  disposition: strict
+  introduced_in: 0.1.0
+terms:
+  - term_id: journey_reachability
+    text: the declaration-to-composition-root binding that makes an exposed journey executable.
+  - term_id: journey_mapping
+    text: a Station Master JOURNEY_MAP value carrying journeyId and the canonical journey YAML path.

package/conventions/coder.bun/coder.bun.wagon-honours-its-contract.convention.yaml

@@ -0,0 +1,64 @@
+schema_version: 1.1.0
+rule_id: coder.bun.wagon-honours-its-contract
+kind: rule
+status: active
+name: A wagon's implementation moves the artifacts its plan document declares (Bun)
+statement: >-
+  A wagon document declares a DATA CONTRACT: `produce[]` are the artifacts the wagon owns and
+  `consume[]` the ones it takes from other wagons (core `wagon.schema.json` requires both). The Bun
+  implementation MUST name each declared artifact where it moves Cargo, so the declaration and the
+  data actually carried cannot drift apart. Core validates that the contract is well formed; only a
+  per-stack detector can see whether this stack's code honours it.
+implementation:
+  type: validator
+  ref: coder.bun.wagon-honours-its-contract
+content:
+  summary: >-
+    Binds a wagon's declared artifact contract to the Bun code that moves Cargo. The JS realization
+    reads every wagon document under `plan/**`, collects the `produce[].name` and `consume[].name`
+    artifact names, and flags any that no Cargo-moving module names. Member of the
+    `bun_interlocking_infrastructure` FAMILY detector (checks/wagon_contract_honoured.mjs).
+  normative_text: |
+    Core `wagon.schema.json` requires `produce` and `consume`, each entry carrying an artifact `name`
+    (and, for produce, a `contract` and `telemetry` URN). Core validates that shape wherever the plan
+    lives; it cannot know whether a Bun module puts those artifacts into Cargo, because that means
+    reading Bun source and this stack's Cargo idiom.
+
+    The wagon implementation is recognised STRUCTURALLY — a module that moves artifacts through Cargo
+    — not by filename. A `wagon.ts` naming heuristic is the kind of fitted check this hub has had to
+    unpick more than once, and a consumer is free to name its modules as it likes.
+
+    NOT_APPLICABLE, deliberately, in two cases. A consumer that declares no wagon contract has nothing
+    to honour. A contract declared with no wagon implementation at all is an unimplemented feature,
+    not a broken contract, and belongs to whatever rule governs unimplemented plan; reporting it here
+    would fire on every freshly planned repository.
+  fix_hint: |
+    Name each declared artifact where the wagon moves it, so the two cannot drift:
+
+      export const CONSUMES = "orders:priced-basket";   // plan: consume[].name
+      export const PRODUCES = "orders:confirmed-order"; // plan: produce[].name
+
+      export function runWagon(step: string, cargo: Cargo): void {
+        const basket = cargo.get(CONSUMES);
+        cargo.put(PRODUCES, { confirmed: true, basket });
+      }
+
+    Or correct the plan if the wagon no longer owns that artifact. This rule is `strict`: a wagon
+    whose declared contract nothing implements is not suppressible and fails CI.
+  exceptions:
+    - A wagon declared in the plan with no implementation anywhere is NOT reported here; the rule
+      judges code that exists against the contract it claims, not the absence of code.
+metadata:
+  aliases:
+    - BUN-WAGON-CONTRACT-001
+  severity: 4
+  disposition: strict
+  introduced_in: 0.2.0
+  core_design_refs:
+    - afokapu/atdd#1246
+    - afokapu/atdd#1251
+terms:
+  - term_id: wagon_data_contract
+    text: >-
+      the artifacts a wagon document declares under `produce[]` and `consume[]`, each identified by an
+      artifact `name`, which the wagon's Cargo-moving code must name.

package/conventions/coder.htmx/coder.htmx.fragment-escapes-interpolation.convention.yaml

@@ -0,0 +1,72 @@
+schema_version: 1.1.0
+rule_id: coder.htmx.fragment-escapes-interpolation
+kind: rule
+status: active
+name: HTML fragments escape interpolated values before htmx swaps them into the DOM
+statement: >-
+  A template literal that emits HTML MUST NOT interpolate a bare variable or property chain
+  (`${user.name}`) directly into the markup; the value MUST pass through an escaping helper first. In a
+  full-stack Bun + htmx application the server renders fragments as template literals and htmx inserts
+  them into the live DOM via `innerHTML`, so there is no framework auto-escaping anywhere in the path.
+  This is the Bun/htmx-stack realization of the agnostic "untrusted data is escaped at the rendering
+  boundary" obligation, enforced by the `htmx_hypermedia_detector` family implementation on
+  `atdd.workspace.bun`.
+terms:
+- term_id: html_bearing_template
+  text: >-
+    a backtick template literal whose text contains an opening tag (`<div`, `<li …`). That is the
+    signal the literal is markup rather than a log line or a SQL string.
+- term_id: bare_interpolation
+  text: >-
+    an interpolation whose expression is only an identifier or a property chain — `${title}`,
+    `${order.customer.name}`. No call, no operator, no literal. This is raw data reaching markup.
+- term_id: composition
+  text: >-
+    an interpolation that is a CALL — `${escapeHtml(x)}`, `${rows.map(row).join("")}`. Either an escape
+    helper or fragment nesting; deliberately out of scope, because flagging it would bury the rule in
+    false positives on legitimate composition.
+content:
+  summary: >-
+    A "fragments escape their data" obligation, and the security-critical rule of this extension. The
+    realization is a zero-dependency Bun detector that extracts every template literal (brace-depth
+    aware, so a nested object inside an interpolation does not end it early), keeps the ones containing
+    an opening tag, and flags interpolations whose expression is a bare identifier or property chain.
+  normative_text: |
+    This obligation is IMPLICIT in a JSX stack and EXPLICIT here, and that shift is the whole reason the
+    rule exists. React escapes `{value}` in JSX automatically; a team moving to htmx carries over the
+    habit of interpolating values into markup without carrying over the escaping that used to happen
+    invisibly underneath. The result is stored XSS in exactly the code that looks most like what they
+    wrote before.
+    The rule is deliberately narrow so that it is precise rather than noisy: it catches the shape that
+    is ALWAYS wrong — raw data dropped straight into markup — and says nothing about calls, which may
+    be escaping helpers or nested fragments. A call that neither escapes nor nests (`${format(bio)}`)
+    passes this rule and must be caught by review; narrowing was the price of a signal a team will not
+    switch off.
+  fix_hint: |
+    Route the value through an escaping helper at the interpolation site:
+
+      `<li class="order">${order.title}</li>`                 // ✗ raw data into markup
+      `<li class="order">${escapeHtml(order.title)}</li>`     // ✓ escaped at the boundary
+
+    Escape at the RENDER site, never at the storage or fetch site: a value escaped early is
+    double-escaped when it reaches a non-HTML sink, and a value escaped late is escaped exactly once,
+    in the one place its destination is known. `strict` — this is the extension's security rule.
+  exceptions:
+  - Template literals containing no opening tag are not markup and are never scanned.
+  - Interpolations that are calls are treated as escaping or composition (see `composition`).
+  - Test files (`*.test.*`, `*.spec.*`) are excluded.
+metadata:
+  aliases:
+  # SECURITY-XSS-001 is the SHARED core alias — the same one carried by
+  # coder.security.xss (core) and coder.vite.security-xss (the Vite realization).
+  # Carrying it is how a stack realization declares lineage in this hub: the three
+  # rules are one obligation with three per-stack detectors, and tooling that
+  # reasons about the obligation finds them through the shared alias.
+  - HTMX-FRAGMENT-ESCAPE-001
+  - SECURITY-XSS-001
+  severity: 1
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: htmx_hypermedia_detector

package/conventions/coder.htmx/coder.htmx.swap-no-inline-handler.convention.yaml

@@ -0,0 +1,59 @@
+schema_version: 1.1.0
+rule_id: coder.htmx.swap-no-inline-handler
+kind: rule
+status: active
+name: htmx-driven markup declares behaviour with hx-attributes, not inline handlers
+statement: >-
+  Markup that uses htmx MUST NOT carry inline HTML event handlers (`onclick="…"`, `onsubmit="…"`,
+  `onchange="…"`, …). Behaviour in a hypermedia application is declared with `hx-trigger` and `hx-on`,
+  which participate in htmx's event and swap lifecycle; an inline handler does not. This is the
+  Bun/htmx-stack realization of the agnostic "behaviour is declared where the framework can see it"
+  obligation, enforced by the `htmx_hypermedia_detector` family implementation on
+  `atdd.workspace.bun`.
+terms:
+- term_id: htmx_driven_markup
+  text: >-
+    a file that contains at least one `hx-` attribute. The rule is SELF-SCOPING to these files: a plain
+    non-htmx page elsewhere in the repo is not this rule's business.
+- term_id: inline_event_handler
+  text: >-
+    a lowercase HTML attribute of the form `on<event>="…"` carrying JavaScript in markup. Deliberately
+    lowercase-only, so React's camelCase JSX prop `onClick={…}` — a different mechanism with different
+    lifecycle semantics — is never flagged.
+content:
+  summary: >-
+    A "no inline JS handlers in hypermedia markup" obligation. The realization is a zero-dependency Bun
+    detector that first confirms the file contains an `hx-` attribute, then flags any lowercase
+    `on<event>="` attribute in it.
+  normative_text: |
+    An inline handler is destroyed the moment htmx swaps the element that carries it, and any state it
+    closed over goes with it. Worse, the reverse also happens: a handler attached to an element that is
+    swapped OUT can remain live on a detached node, so a stale click keeps firing against markup the
+    user can no longer see. htmx has an explicit answer for both — `hx-on` for element-scoped
+    behaviour, `hx-trigger` for the request itself — and those survive swaps because htmx re-processes
+    the new content.
+    Mixing the two models is also why htmx codebases drift back toward a JS layer: each inline handler
+    is a small piece of behaviour that is invisible to the hypermedia lifecycle, and they accumulate.
+  fix_hint: |
+    Move the behaviour onto an htmx attribute:
+
+      <button hx-get="/rows/1" onclick="track('open')">Open</button>          <!-- ✗ dies on swap -->
+      <button hx-get="/rows/1" hx-on::after-request="track('open')">Open</button>   <!-- ✓ -->
+
+    For behaviour that is genuinely presentational and not request-related, attach it in a delegated
+    listener on a stable ancestor that is never swapped. Disposition is `suppress-and-clean`: existing
+    handlers are held flat by a ratchet baseline while they are migrated.
+  exceptions:
+  - Files containing no `hx-` attribute are never scanned (self-scoping).
+  - React/JSX camelCase props (`onClick={…}`, `onSubmit={…}`) are a different mechanism and are out of
+    scope.
+  - Test files (`*.test.*`, `*.spec.*`) are excluded.
+metadata:
+  aliases:
+  - HTMX-NO-INLINE-HANDLER-001
+  severity: 3
+  disposition: suppress-and-clean
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: htmx_hypermedia_detector