@afokapu/atdd-bun 0.1.0

package/conventions/coder.htmx/coder.htmx.swap-oob-carries-id.convention.yaml

@@ -0,0 +1,56 @@
+schema_version: 1.1.0
+rule_id: coder.htmx.swap-oob-carries-id
+kind: rule
+status: active
+name: Out-of-band swap elements declare the id they swap into
+statement: >-
+  Every element carrying `hx-swap-oob` MUST also carry an `id`. htmx matches an out-of-band element to
+  its destination BY ID; an oob element with no id has no destination, so htmx discards it silently —
+  no error, no console warning, no swap. This is the Bun/htmx-stack realization of the agnostic
+  "a declarative binding must name its target" obligation, enforced by the `htmx_hypermedia_detector`
+  family implementation on `atdd.workspace.bun`.
+terms:
+- term_id: out_of_band_swap
+  text: >-
+    `hx-swap-oob` marks an element in a response for swapping somewhere OTHER than the requesting
+    element's target — the mechanism for updating a cart badge, a flash region or a sidebar count from
+    a response whose main target is elsewhere.
+- term_id: silent_discard
+  text: >-
+    htmx's behaviour when no element in the document matches the oob element's id: it drops the
+    fragment and continues. The failure is invisible at every layer — the server logs a 200, the
+    network tab shows the markup arriving, and the page does not change.
+content:
+  summary: >-
+    An "oob swaps name their destination" obligation. The realization is a zero-dependency Bun detector
+    that locates each `hx-swap-oob` occurrence, extracts the enclosing opening tag with a quote-aware
+    scan (so a `>` inside an attribute value does not end the tag early), and flags the element when
+    that tag carries no `id="…"` or JSX `id={…}`.
+  normative_text: |
+    This is the highest-frequency silent bug in an htmx codebase, and it presents to the developer as
+    "the server is definitely returning it but the page doesn't update" — which sends people to debug
+    the server, the route, and the response headers, none of which are wrong.
+    The obligation is that an out-of-band fragment names its destination. WHERE the id must appear is
+    part of the rule: on the oob element itself, not on a wrapper, because htmx reads the id from the
+    element carrying the attribute.
+  fix_hint: |
+    Give the oob element the id of the element it replaces:
+
+      <div class="cart-count" hx-swap-oob="true">3</div>   <!-- ✗ no destination; dropped -->
+      <div id="cart-count" hx-swap-oob="true">3</div>      <!-- ✓ swaps into #cart-count -->
+
+    The id must match an element that EXISTS in the current document; an id that matches nothing is
+    dropped just as silently, which this rule cannot see and a smoke test must. `strict`.
+  exceptions:
+  - An element whose id is supplied dynamically as a JSX expression (`id={rowId}`) satisfies the rule —
+    the binding is present; whether it resolves is a runtime concern.
+  - "`hx-swap` (in-band) is out of scope: it swaps into `hx-target`, a selector, not an id."
+metadata:
+  aliases:
+  - HTMX-OOB-ID-001
+  severity: 2
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: htmx_hypermedia_detector

package/conventions/coder.htmx/coder.htmx.verb-destructive-confirms.convention.yaml

@@ -0,0 +1,56 @@
+schema_version: 1.1.0
+rule_id: coder.htmx.verb-destructive-confirms
+kind: rule
+status: active
+name: Destructive htmx requests declare a confirmation
+statement: >-
+  Every element carrying `hx-delete` MUST also carry `hx-confirm` (or `hx-prompt`). In a hypermedia
+  application a delete is one attribute on a clickable element: there is no form submit, no route
+  transition and no framework guard between the user's click and the destructive request.
+  `hx-confirm` IS that guard, and it is declarative precisely so it cannot be forgotten. This is the
+  Bun/htmx-stack realization of the agnostic "a destructive action requires explicit intent"
+  obligation, enforced by the `htmx_hypermedia_detector` family implementation on
+  `atdd.workspace.bun`.
+terms:
+- term_id: destructive_verb
+  text: >-
+    `hx-delete`. `hx-post`/`hx-put`/`hx-patch` are mutating but not inherently destructive — they are
+    governed by `coder.htmx.verb-mutation-signals-progress` instead.
+- term_id: declared_confirmation
+  text: >-
+    `hx-confirm="…"` (a yes/no gate) or `hx-prompt="…"` (a gate requiring typed input). Either
+    satisfies the obligation; which one is a product decision about how much friction the action
+    deserves.
+content:
+  summary: >-
+    A "deletes are confirmed" obligation. The realization is a zero-dependency Bun detector that finds
+    each `hx-delete`, extracts the enclosing opening tag with a quote-aware scan, and flags the element
+    when that tag carries neither `hx-confirm` nor `hx-prompt`.
+  normative_text: |
+    In a component framework a destructive action typically passes through a handler, and the
+    confirmation lives in that handler where a reviewer sees it. htmx removes the handler — which is
+    the point — and with it removes the place the confirmation used to live. The obligation therefore
+    has to be relocated onto the element and enforced there, or it is simply lost in the migration.
+    The rule checks CO-LOCATION on the same element, not mere presence in the file: a confirmation on
+    a neighbouring control protects nothing.
+  fix_hint: |
+    Put the confirmation on the element that issues the delete:
+
+      <button hx-delete="/orders/7">Delete</button>                            <!-- ✗ unguarded -->
+      <button hx-delete="/orders/7" hx-confirm="Delete order 7?">Delete</button>   <!-- ✓ -->
+
+    For high-value deletions prefer `hx-prompt` so the user must type something meaningful rather than
+    reflexively clicking OK. `strict` — an unguarded delete is not suppressible.
+  exceptions:
+  - An element carrying `hx-prompt` instead of `hx-confirm` satisfies the rule.
+  - A delete implemented as a `hx-post` to an explicit `/…/delete` route is not detected by this rule;
+    that is a naming choice the rule cannot see, and it is why the verb should be `hx-delete`.
+metadata:
+  aliases:
+  - HTMX-DELETE-CONFIRM-001
+  severity: 2
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: htmx_hypermedia_detector

package/conventions/coder.htmx/coder.htmx.verb-endpoint-is-routed.convention.yaml

@@ -0,0 +1,73 @@
+schema_version: 1.1.0
+rule_id: coder.htmx.verb-endpoint-is-routed
+kind: rule
+status: active
+name: A mutating htmx endpoint is served by the Station Master surface (Bun/htmx)
+statement: >-
+  An endpoint declared by a STATE-CHANGING htmx verb (`hx-post`, `hx-put`, `hx-patch`, `hx-delete`)
+  MUST be served by the Station Master surface — the module declaring the `JOURNEY_MAP`. htmx
+  declares its route space in the MARKUP, which is what makes it hypermedia; without this, that
+  markup can mint a state-advancing route the journey space never admitted, and the affordance posts
+  into nothing.
+implementation:
+  type: validator
+  ref: coder.htmx.verb-endpoint-is-routed
+content:
+  summary: >-
+    Binds htmx's markup route space to the declared journey space. The JS realization finds the
+    module declaring a `JOURNEY_MAP`, collects every statically written mutating verb endpoint, and
+    flags one the Station Master names nowhere. Member of the `htmx_hypermedia_detector` FAMILY
+    detector (checks/htmx_verb_endpoint_is_routed.mjs).
+  normative_text: |
+    `tester.htmx.verb-endpoint-coverage` states this stack's premise plainly — "an htmx endpoint is
+    declared in the MARKUP, so the markup is this stack's route space". That is right, and it is
+    also the hole. Measured on a consumer: an `hx-post="/orders/void-all"` carrying a confirm, an
+    indicator and a passing test, bound to no wagon, train or interlocking, passed EVERY gated
+    bun+htmx rule.
+
+    This is the parallel-route-space shape the hub already rejects elsewhere. The interlocking
+    families fail a consumer that declares reachability in a second, private field instead of the
+    declared one; htmx had the same hole with none of the teeth.
+
+    MUTATIONS ONLY, DELIBERATELY. `hx-get` fetches a fragment — presentation — and requiring every
+    read to be routed by the Station Master would fail ordinary htmx. The mutating verbs advance
+    state, which is what a journey does, so those are the ones that owe a route.
+
+    STATIC PATHS ONLY. An endpoint built by interpolation (`/orders/${id}/void`) cannot be compared
+    to a server route by text, and guessing would report on correct code. Those are skipped, exactly
+    as the Vite family treats an unresolvable trainId as advisory rather than inventing a verdict.
+
+    The Station Master is found by the JOURNEY_MAP it DECLARES, never by filename. Matching is on
+    the whole path or its distinctive terminal segment: matching any segment was the first attempt
+    and made the rule vacuous, because a Station Master importing from `./src/orders/` made every
+    `/orders/*` endpoint look routed.
+
+    NOT_APPLICABLE when no Station Master surface resolves — a consumer with no JOURNEY_MAP has no
+    journey space to be outside of.
+  fix_hint: |
+    Route the endpoint from the Station Master, or drop the affordance:
+
+      if (req.method === "POST" && path === "/orders/confirm") {
+        if (!authorize(req)) return Response.json({ code: "unauthorized" }, { status: 401 });
+        return orderRowFragment("1");
+      }
+
+    A button added to markup ahead of its handler is the common cause. This rule is `strict`: a
+    state-changing affordance the server never routes is not suppressible and fails CI.
+  exceptions:
+    - "`hx-get` endpoints are NOT reported; fetching a fragment is presentation, not a journey."
+    - An endpoint written with interpolation is skipped rather than guessed at, preserving the
+      advisory treatment this hub gives statically unresolvable bindings.
+metadata:
+  aliases:
+    - HTMX-VERB-ENDPOINT-ROUTED-001
+  severity: 4
+  disposition: strict
+  introduced_in: 0.2.0
+  core_design_refs:
+    - afokapu/atdd#1246
+terms:
+  - term_id: journey_space
+    text: >-
+      the routes the Station Master admits, declared by the module carrying `JOURNEY_MAP`, which a
+      state-changing htmx endpoint must be served by.

package/conventions/coder.htmx/coder.htmx.verb-endpoint-same-origin.convention.yaml

@@ -0,0 +1,58 @@
+schema_version: 1.1.0
+rule_id: coder.htmx.verb-endpoint-same-origin
+kind: rule
+status: active
+name: htmx verb attributes address same-origin paths, never absolute URLs
+statement: >-
+  Every htmx verb attribute (`hx-get`, `hx-post`, `hx-put`, `hx-patch`, `hx-delete`) MUST address a
+  same-origin path (`/api/orders`) and MUST NOT carry a hardcoded absolute or protocol-relative URL
+  (`https://host/…`, `//host/…`). htmx swaps the response body directly into the live DOM, so the
+  endpoint's origin is a trust boundary, not a configuration detail. This is the Bun/htmx-stack
+  realization of the agnostic "a client must not hardcode a foreign origin" obligation; the detector
+  that enforces it is the `htmx_hypermedia_detector` family implementation on
+  `atdd.workspace.bun`.
+terms:
+- term_id: verb_attribute
+  text: >-
+    one of `hx-get` / `hx-post` / `hx-put` / `hx-patch` / `hx-delete` — the attributes that make an
+    element issue an HTTP request.
+- term_id: same_origin_path
+  text: >-
+    a root-relative path beginning `/`, resolved by the browser against the origin that served the
+    document. The correct form for every hypermedia control in the app.
+content:
+  summary: >-
+    An "htmx endpoints are same-origin paths" obligation. The realization is a zero-dependency Bun
+    detector that scans `.html`/`.htm` templates and `.ts`/`.tsx`/`.js`/`.jsx`/`.mjs` source for a verb
+    attribute whose value begins `http://`, `https://` or `//`.
+  normative_text: |
+    A hardcoded foreign origin in a verb attribute fails three ways at once. It is a CORS failure the
+    moment the other origin stops sending permissive headers. It is an untrusted-HTML injection point,
+    because htmx inserts whatever comes back straight into the DOM — the response is markup, not data,
+    and there is no parse step that would reject it. And it is the standard mechanism by which a staging
+    host reaches production, since a baked-in `https://staging.example.com` is invisible to every
+    environment variable and every config review.
+    Cross-origin calls that are genuinely required belong behind a same-origin proxy route on the Bun
+    server, where the origin decision is made in one auditable place rather than scattered across
+    templates.
+  fix_hint: |
+    Replace the absolute URL with the path, and proxy if the upstream really is remote:
+
+      <div hx-get="https://api.example.com/orders">      <!-- ✗ foreign origin in markup -->
+      <div hx-get="/api/orders">                          <!-- ✓ same-origin path -->
+
+    On the Bun side, route `/api/orders` through `Bun.serve` and let THAT handler call upstream. The
+    rule is `strict`: an absolute-URL endpoint is not suppressible.
+  exceptions:
+  - A path-only value (`/orders`, `./orders`, `orders`) is same-origin and never flagged.
+  - Non-verb htmx attributes (`hx-target`, `hx-swap`, `hx-trigger`) are out of scope — they carry
+    selectors and modifiers, not endpoints.
+metadata:
+  aliases:
+  - HTMX-ENDPOINT-ORIGIN-001
+  severity: 2
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: htmx_hypermedia_detector

package/conventions/coder.htmx/coder.htmx.verb-mutation-signals-progress.convention.yaml

@@ -0,0 +1,59 @@
+schema_version: 1.1.0
+rule_id: coder.htmx.verb-mutation-signals-progress
+kind: rule
+status: active
+name: Mutating htmx requests signal that they are in flight
+statement: >-
+  Every element issuing a mutating htmx request (`hx-post`, `hx-put`, `hx-patch`, `hx-delete`) MUST
+  declare either `hx-indicator` or `hx-disabled-elt`. htmx swaps in place with no navigation, so
+  without one of these the page is visually identical while the request is in flight: the user
+  receives no feedback, clicks again, and a non-idempotent request runs twice. This is the
+  Bun/htmx-stack realization of the agnostic "an in-flight mutation is observable" obligation, enforced
+  by the `htmx_hypermedia_detector` family implementation on `atdd.workspace.bun`.
+terms:
+- term_id: mutating_request
+  text: >-
+    `hx-post` / `hx-put` / `hx-patch` / `hx-delete` — a request that changes server state, so a
+    duplicate is not harmless.
+- term_id: progress_signal
+  text: >-
+    `hx-indicator="…"` (show a spinner region for the duration) or `hx-disabled-elt="…"` (disable the
+    control for the duration). The first tells the user something is happening; the second makes the
+    double-submit physically impossible. Either satisfies the obligation.
+content:
+  summary: >-
+    An "in-flight mutations are visible" obligation. The realization is a zero-dependency Bun detector
+    that finds each mutating verb attribute, extracts the enclosing opening tag, and flags the element
+    when it declares neither `hx-indicator` nor `hx-disabled-elt`. Findings are deduplicated per
+    element, so an element carrying two mutating verbs reports once.
+  normative_text: |
+    A full page navigation gave the user a free progress signal: the browser's own spinner and the page
+    going blank. Swapping a fragment in place gives none. This is the single most common complaint
+    about htmx applications from users, and it is not a taste issue — it produces duplicate orders,
+    duplicate charges and duplicate rows, because the user's model ("nothing happened, click again") is
+    a correct reading of what the page showed them.
+    GET is deliberately out of scope: a read is idempotent, so a duplicate is harmless and an indicator
+    there is a UX preference rather than an obligation.
+  fix_hint: |
+    Declare a progress signal on the element issuing the mutation:
+
+      <form hx-post="/orders">…</form>                                <!-- ✗ invisible in flight -->
+      <form hx-post="/orders" hx-indicator="#spinner">…</form>        <!-- ✓ shows progress -->
+      <form hx-post="/orders" hx-disabled-elt="find button">…</form>  <!-- ✓ prevents re-submit -->
+
+    Prefer `hx-disabled-elt` where a duplicate would be expensive; the indicator alone tells the user
+    to wait but does not stop them. `suppress-and-clean`: a ratchet holds existing cases flat.
+  exceptions:
+  - "`hx-get` is not scoped by this rule (idempotent)."
+  - An element declaring both signals is fine; only declaring neither is a violation.
+  - Server-driven idempotency (an idempotency key on the endpoint) is a real mitigation but not one
+    this rule can see; it does not exempt the element from signalling progress to the user.
+metadata:
+  aliases:
+  - HTMX-MUTATION-PROGRESS-001
+  severity: 3
+  disposition: suppress-and-clean
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: htmx_hypermedia_detector

package/conventions/planner.docs/planner.docs.adr-registry-derived.convention.yaml

@@ -0,0 +1,83 @@
+schema_version: 1.1.0
+rule_id: planner.docs.adr-registry-derived
+kind: rule
+status: active
+name: 'The ADR registry is derived from :decides: edges, never hand-maintained'
+statement: >-
+  `docs/architecture/decisions/index.adoc` MUST list exactly the ADRs the corpus declares, derived
+  from their `:decides:` edges. An ADR present in the tree and absent from the registry — or listed
+  in the registry and absent from the tree — is a violation. The registry is a projection, never a
+  typed list (spec 2 §5.2, §6).
+
+  WHAT COUNTS AS A LISTING. Where the registry declares a machine-maintained region —
+  `// BEGIN GENERATED: adr-register` … `// END GENERATED: adr-register`, the markers a generator
+  writes around its own output — only that region is read. A corpus whose generator marks its
+  output has already said where its list begins and ends, and taking it at its word beats any
+  heuristic. Where no region is declared, the file is read minus its `----` listing blocks: an ADR
+  skeleton shown in fences illustrates the shape and lists nothing. A prose mention outside a
+  declared region is NOT excused — a sentence naming an id and a list entry naming one cannot be
+  told apart without guessing at a corpus's formatting, and a corpus that wants prose ignored says
+  so with the markers.
+terms:
+- term_id: adr
+  text: >-
+    a document at `docs/architecture/decisions/adr-YYYYMMDD-NNN-<slug>.adoc` declaring `:adr-id:`,
+    `:status:`, `:date:` and `:decides:`.
+- term_id: generated_region
+  text: >-
+    a machine-maintained span delimited by `// BEGIN GENERATED: <name>` and
+    `// END GENERATED: <name>`, which a generator rewrites in place; where the registry declares
+    one named `adr-register`, that span is the listing the projection is compared against.
+- term_id: derived_registry
+  text: >-
+    `index.adoc` in the decisions directory, whose entries are computed from the set of ADR files and
+    their `:decides:` targets. It contains references to the decisions, never the decisions themselves.
+- term_id: disposition_rationale
+  text: >-
+    advisory while the consuming corpus is brought into compatibility. The measurement below was
+    TAKEN on 2026-09-06, not recalled — #1782 found this convention's own recorded measurement
+    already stale, so the date lives in the key and the command is recorded beside the result.
+    Re-take it at the escalation checkpoint; never escalate on the number here.
+  values:
+    measured_2026_09_06: 'The decisions directory does not exist and there are 0 ADR files. Spec 2 §6 names the first two: ADR-20260906-001 (shared control root) and ADR-20260906-002 (the documentation system itself, authored as current documentation — the proof the system works).'
+    measurement_target: 'afokapu/atdd @ main (/Users/alecfokapu/Github/atdd/main)'
+    measurement_command: 'ls -d docs/architecture/decisions 2>&1 ; find . -name ''adr-*.adoc'' | wc -l'
+    escalate_when: '`docs/architecture/decisions/` exists and its index.adoc matches the derived projection exactly on a full scan.'
+content:
+  summary: >-
+    A hand-maintained list of decisions drifts from the decisions — precisely the failure class ATDD
+    exists to kill, reproduced inside the documentation system itself. Deriving the registry makes
+    drift impossible rather than detectable.
+  normative_text: |
+    One architectural decision lives in ONE ADR file (spec 2 §6). The registry's job is to make the
+    set of them navigable, and the moment a human types an entry into it the set has two sources of
+    truth.
+
+    The check is bidirectional on purpose. A missing entry is the obvious drift; a STALE entry — an
+    ADR listed after its file was renamed or removed — is the one that survives review, because a
+    list that names something is read as authoritative about it.
+
+    An ADR's `:decides:` target is resolved by `planner.docs.graph-target-resolves` like any other
+    edge. An ADR deciding an architecture node that no document declares is reported there, not here.
+  fix_hint: |
+    Regenerate the registry rather than editing it:
+
+      atdd docs build        # once #1623 lands the operator verbs (spec 2 §7)
+
+    Until then the capability reports the delta and the registry is regenerated by the same code
+    path the check uses, so the two can never disagree. If you find yourself typing an entry into
+    `decisions/index.adoc`, the entry belongs in an ADR file with a `:decides:` attribute instead.
+  exceptions:
+  - Prose surrounding the derived entries in `index.adoc` (a title, an introductory paragraph) is not
+    compared. Only the set of ADR references is.
+  - A decisions directory holding no ADRs requires no entries; an empty registry is a correct
+    projection of an empty set.
+metadata:
+  aliases:
+  - DOCS-ADR-001
+  severity: 2
+  disposition: advisory
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: docs_capability

package/conventions/planner.docs/planner.docs.area-index-required.convention.yaml

@@ -0,0 +1,67 @@
+schema_version: 1.1.0
+rule_id: planner.docs.area-index-required
+kind: rule
+status: active
+name: Each authored area carries an index.adoc
+statement: >-
+  Each authored area of the canonical tree — `docs/`, `docs/purpose/`, `docs/architecture/`,
+  `docs/architecture/decisions/`, `docs/delivery/`, `docs/archive/` — MUST contain an `index.adoc`.
+  Other canonical filenames are defined when useful and are NOT instantiated merely to satisfy an
+  empty taxonomy (spec 2 §4).
+terms:
+- term_id: authored_area
+  text: >-
+    a directory of the canonical tree that holds authored documents. `docs/dist/` is not one; it is
+    generated output.
+- term_id: index
+  text: >-
+    `index.adoc` — the area's entry point and the node the rendered site navigates to. For
+    `docs/architecture/decisions/` it is additionally a DERIVED registry, governed by
+    `planner.docs.adr-registry-derived`.
+- term_id: disposition_rationale
+  text: >-
+    advisory while the consuming corpus is brought into compatibility. The measurement below was
+    TAKEN on 2026-09-06, not recalled — #1782 found this convention's own recorded measurement
+    already stale, so the date lives in the key and the command is recorded beside the result.
+    Re-take it at the escalation checkpoint; never escalate on the number here.
+  values:
+    measured_2026_09_06: '`docs/` exists and holds 71 markdown files; none of purpose/, architecture/, delivery/ or archive/ exists, and there is no index.adoc anywhere. 0 of 6 canonical areas are present, so the rule currently reports nothing and will begin reporting as the tree is created.'
+    measurement_target: 'afokapu/atdd @ main (/Users/alecfokapu/Github/atdd/main)'
+    measurement_command: 'ls -d docs docs/purpose docs/architecture docs/delivery docs/archive 2>&1'
+    escalate_when: 'The canonical tree exists in the consuming repository and every existing authored area carries an index.adoc.'
+content:
+  summary: >-
+    An area without an index is an area the rendered site cannot navigate into and a reader cannot
+    enter. The rule checks the six canonical areas only; it does not require an index in every
+    subdirectory an author happens to create.
+  normative_text: |
+    The rule is scoped to the canonical areas DELIBERATELY, and the restraint is the point. Spec 2 §4
+    warns against instantiating filenames to fill an empty taxonomy, and a rule demanding an index in
+    every directory would do exactly that — it would push authors to create ceremonial files for
+    directories that hold two related documents and need no landing page.
+
+    An area that does not exist is not a violation. The tree grows when a real requirement justifies
+    an area (spec 2 §2, *Out of scope*, on images / reference / operations domains). This rule fires
+    only when an area EXISTS and has no index.
+  fix_hint: |
+    Add the index and give it identity like any other document:
+
+      docs/architecture/index.adoc
+        = Architecture
+        :doc-id: architecture.index
+        :status: current
+
+    If the area has no content to introduce, the question is whether the area should exist yet, not
+    what to write in its index.
+  exceptions:
+  - '`docs/dist/` is generated output and is never required to carry an index.'
+  - An area that does not exist in the tree is not reported. Only an existing area missing its index is.
+metadata:
+  aliases:
+  - DOCS-TREE-001
+  severity: 3
+  disposition: advisory
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: docs_capability

package/conventions/planner.docs/planner.docs.artifact-path-shape.convention.yaml

@@ -0,0 +1,82 @@
+schema_version: 1.1.0
+rule_id: planner.docs.artifact-path-shape
+kind: rule
+status: active
+name: Declared documentation artifacts name AsciiDoc paths inside the canonical tree
+statement: >-
+  A documentation artifact declared at RATIFY MUST name a `path` that begins `docs/` and ends
+  `.adoc`; an artifact with `action: archive` MUST name a `path` beneath `docs/archive/`. Core stores
+  these paths as opaque strings and never interprets them (companion §3); interpreting them is this
+  extension's job, because only the extension knows the tree.
+terms:
+- term_id: declaration
+  text: >-
+    the `documentation:` block recorded in the store at RATIFY (companion §3), in one of its two
+    total forms — `impact: change` with artifacts, or `impact: none` with a reason.
+- term_id: artifact
+  text: >-
+    one entry of `artifacts:` — an `action` (`create`, `modify`, `archive`), a `path`, and for
+    `archive` a `from` naming the document being retired.
+- term_id: disposition_rationale
+  text: >-
+    advisory while the consuming corpus is brought into compatibility. The measurement below was
+    TAKEN on 2026-09-06, not recalled — #1782 found this convention's own recorded measurement
+    already stale, so the date lives in the key and the command is recorded beside the result.
+    Re-take it at the escalation checkpoint; never escalate on the number here.
+  values:
+    measured_2026_09_06: '0 declarations exist to check. The `documentation:` block lands with the core unit (companion spec, work item B) and this rule has an empty input until it does. Advisory is the only honest disposition for a rule whose subject does not exist yet.'
+    measurement_target: 'afokapu/atdd @ main (/Users/alecfokapu/Github/atdd/main)'
+    measurement_command: '(the declaration is core''s, companion §3, and is not yet implemented)'
+    escalate_when: 'Documentation declarations are being recorded at RATIFY in the consuming repository and a full pass over recent plans reports zero malformed artifact paths.'
+content:
+  summary: >-
+    The declaration is a promise about paths. This rule checks the promise is well formed BEFORE the
+    work is done, so a malformed declaration is caught at RATIFY rather than discovered at COMPLETE
+    when the paths do not match the change set.
+  normative_text: |
+    The division of labour with core is exact and worth stating, because getting it wrong is what
+    #1782 originally proposed. Core checks that every declared path APPEARS IN THE CHANGE SET
+    (companion §4, check 4) — path-agnostic, format-agnostic, and non-vacuous with no extension
+    installed. This rule checks that the path is SHAPED like documentation. Core cannot: it does not
+    know what `docs/` is, or what a `.adoc` is, and companion §8's anti-theatre test greps core for
+    exactly those tokens and requires zero hits.
+
+    The archive constraint is the load-bearing half. `action: archive` with a destination outside
+    `docs/archive/` is how history quietly gets promoted into current truth — the single outcome
+    spec 2 §2 names as most likely to happen under time pressure, and the one that recreates the
+    problem #1782 exists to solve.
+  fix_hint: |
+    Shape the declaration to the tree:
+
+      documentation:
+        impact: change
+        artifacts:
+          - action: create
+            path: docs/architecture/shared-control-root.adoc     # ✓ under docs/, ends .adoc
+          - action: archive
+            from: docs/old-spec.md
+            path: docs/archive/old-spec.adoc                     # ✓ archive lands in archive/
+
+    An archived document keeps its content and gains `:status:`. It does not gain a place in
+    `purpose/`, `architecture/` or `delivery/` — those are for documents that are accepted truth today.
+  exceptions:
+  - >-
+    `impact: none` declares no artifacts and is not checked by this rule. Core enforces that a
+    reason is present; core does not judge the reason's quality, and neither does this extension.
+  - >-
+    An ABSENT declaration is not `impact: none`. `impact: none` is core considering the question
+    and declaring no documentation change — a positive statement, which permits. A missing
+    declaration is core having said nothing, so no declaration-dependent rule can be evaluated and
+    the capability returns COULD_NOT_CHECK, which BLOCKS. The corpus rules are still evaluated and
+    still reported: "genuinely nothing to check" is false whenever there is a corpus to read.
+  - The `from` path of an archive artifact is NOT required to end `.adoc` — it names the legacy
+    document being retired, which is exactly the markdown the migration is converting.
+metadata:
+  aliases:
+  - DOCS-DECLARATION-001
+  severity: 2
+  disposition: advisory
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: docs_capability

package/conventions/planner.docs/planner.docs.asciidoc-only.convention.yaml

@@ -0,0 +1,71 @@
+schema_version: 1.1.0
+rule_id: planner.docs.asciidoc-only
+kind: rule
+status: active
+name: AsciiDoc is the only authored format beneath docs/
+statement: >-
+  A file authored beneath `docs/` MUST be AsciiDoc (`.adoc`). An authored `.md` beneath `docs/`,
+  outside the generated `docs/dist/` tree, is a violation. This is the format half of the
+  documentation model handoff spec 2 §4 names; it is an EXTENSION obligation because core is
+  forbidden to know what a `.adoc` is (companion §4, *Deliberately excluded*).
+terms:
+- term_id: authored_file
+  text: >-
+    a file a human wrote and committed beneath `docs/`. The test is location, not content: anything
+    under `docs/` that is not under `docs/dist/` is authored.
+- term_id: generated_output
+  text: >-
+    everything beneath `docs/dist/`. It is rendered by the build (spec 2 §7), normally excluded from
+    git, and never subject to the authored-format rule.
+- term_id: disposition_rationale
+  text: >-
+    advisory while the consuming corpus is brought into compatibility. The measurement below was
+    TAKEN on 2026-09-06, not recalled — #1782 found this convention's own recorded measurement
+    already stale, so the date lives in the key and the command is recorded beside the result.
+    Re-take it at the escalation checkpoint; never escalate on the number here.
+  values:
+    measured_2026_09_06: '71 markdown beneath docs/, 18 non-dotfile markdown at the repository root (89 total; 90 counting .atdd-launch-prompt.md), 0 .adoc anywhere. The corpus is 0% compatible, which is why this rule ships advisory.'
+    measurement_target: 'afokapu/atdd @ main (/Users/alecfokapu/Github/atdd/main)'
+    measurement_command: 'find docs -name ''*.md'' -type f | wc -l ; find . -maxdepth 1 -name ''*.md'' -type f | wc -l ; find . -name ''*.adoc'' -not -path ''./.git/*'' | wc -l'
+    escalate_when: 'No authored `.md` remains beneath `docs/` outside `docs/dist/` in the consuming repository — i.e. the migration of spec 2 §1 has landed and the corpus is compatible with `strict`.'
+    measurement_note: 'Spec 2 §1 records 71 + 18 = 89 as of the same date and this run reproduces it exactly for the non-dotfile corpus. Re-take this measurement at the escalation checkpoint; do not escalate on the number recorded here (spec 2 §8, and companion §7 on stale measurements).'
+content:
+  summary: >-
+    One authored format, mechanically checked. The rule exists because a mixed corpus cannot carry a
+    relationship graph: `doc-id` and the `:implements:` / `:supersedes:` edges of
+    `planner.docs.graph-target-resolves` are AsciiDoc attributes, and a markdown file has nowhere to
+    put them. Format uniformity is the precondition for every other rule in this extension.
+  normative_text: |
+    The rule is deliberately a LOCATION test rather than a content test. Asking "is this really
+    prose documentation?" is semantic and undecidable; asking "is this path under docs/ and not
+    under docs/dist/, and does it end .md?" is deterministic and cheap. Spec 2 §4 chose the
+    decidable form on purpose, and the same reasoning is why the undeclared-change rule
+    (planner.docs.undeclared-change) is stated as the enforceable inverse of "should this have been
+    declared?".
+
+    `docs/dist/**` is excluded because it is build output, not authorship. Excluding it by path —
+    rather than by gitignore status — keeps the check identical whether or not the tree has been
+    built, which is what makes it deterministic in CI.
+  fix_hint: |
+    Convert the file and keep its content:
+
+      docs/architecture/shared-control-root.md      # ✗ authored markdown under docs/
+      docs/architecture/shared-control-root.adoc     # ✓ authored AsciiDoc
+
+    A historical document does not become current by being converted. Convert it INTO
+    `docs/archive/` and give it `:status:` accordingly — spec 2 §2 *Out of scope* is explicit that
+    migration preserves history and never promotes it.
+  exceptions:
+  - Everything beneath `docs/dist/` is generated output and is never scanned.
+  - Markdown OUTSIDE `docs/` is untouched by this rule. `README.md`, `CONTRIBUTING.md` and the
+    repository-root corpus are out of its scope; they are migrated by the adoption step, not
+    rejected by this detector.
+metadata:
+  aliases:
+  - DOCS-FORMAT-001
+  severity: 2
+  disposition: advisory
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: docs_capability