---
phase: 07-workflow-smoke-convention-locks
plan: 01
subsystem: docs
tags: [adr, ldtk, gridsize, convention-lock]

# Dependency graph
requires:
  - phase: 06-client-rebuild-mvp-gate
    provides: 44x40 floor pitch source-of-truth (CLAUDE.md §Extracted Constants); legacy-origin.ts runtime helper
provides:
  - ADR 0009 — LDtk gridSize=4 unified convention (IntGrid + Tile + Entity)
  - Locked editor-grid invariant for all Phase 8+ .ldtk authoring
  - 44x40 → 11x10 cell mapping documented; entity 4 px snap tradeoff accepted
affects: [08-map-loader-phaser-ldtkloader-testbed, 09-room-converter-ldtk-import, 11-minimap-hud]

# Tech tracking
tech-stack:
  added: []
  patterns:
    - "ADR Pattern B: Michael Nygard format mirroring docs/adr/0008 header ordering (H1 → Date/Phase → blank → [<doc>->REQ-*] → blank → ## Status); --no-matrix lint mode for non-engine ADRs"

key-files:
  created:
    - docs/adr/0009-ldtk-gridsize-convention.md
  modified: []

key-decisions:
  - "gridSize = 4 unified across IntGrid + Tile + Entity layers (diverges from research-default 4/1 split per operator preference for single mental grid)"
  - "44x40 floor pitch maps to 11x10 LDtk cells per BNO floor tile; mental gear-shift acknowledged in ADR"
  - "Entity placement snaps to 4 px, not pixel-accurate — accepted because legacy BNO entities are tile-aligned in GML"
  - "Re-evaluation gate tied to Phase 8 operator-machine evidence of entity drift vs legacy GML"

patterns-established:
  - "Pattern B (ADR template) extended to Phase 7 convention-lock ADRs: ADR 0008 header ordering + --no-matrix lint mode + [doc->REQ-MAP-02] tag on its own line"

requirements-completed: [MAP-02]

# Metrics
duration: ~12min
completed: 2026-05-20
---

# Phase 07 Plan 01: LDtk gridSize Convention ADR Summary

**ADR 0009 locks `gridSize = 4` unified across IntGrid, Tile, and Entity layers, documenting the 44x40 floor pitch → 11x10 LDtk cell mapping and the deliberate 4 px entity-snap tradeoff before any Phase 8 `.ldtk` content is authored.**

## Performance

- **Duration:** ~12 min
- **Started:** 2026-05-20 (this execution wave)
- **Completed:** 2026-05-20
- **Tasks:** 1 / 1
- **Files created:** 1
- **Files modified:** 0

## Accomplishments

- Authored ADR 0009 at `docs/adr/0009-ldtk-gridsize-convention.md` (127 lines).
- Documented the three sub-decisions from `07-CONTEXT.md` §"gridSize ADR" (D-01, D-02, D-03) verbatim in the Decision section, with inline arithmetic `44 / 4 = 11` and `40 / 4 = 10`.
- Mirrored ADR 0008's header ordering (H1 → Date → Phase → blank → `[doc->REQ-MAP-02]` → blank → `## Status`) for consistency with the most-recent ADR style.
- Listed three rejected alternatives (4/1 split research default, 1/1 pixel-accurate, 44/40 non-square cells) with explicit `Rejected: <reason>` form per Pattern B.
- Cross-referenced ADR 0008 (canvas base-resolution sibling), CLAUDE.md §"Extracted Constants" + §"Coordinate Conventions (D-63)", and `extracted/client-5-8/sprites/0023-Tile1/meta.json` (44x40 source-of-truth) in the References section.
- Verified `lint-adr.mjs --no-matrix` exits 0; `[doc->REQ-MAP-02]` tag present on its own line; file >50 lines (127).

## Task Commits

1. **Task 1: Author ADR 0009 gridSize=4 unified convention** — `5f229c7` (docs)

## Files Created/Modified

- `docs/adr/0009-ldtk-gridsize-convention.md` — New ADR locking the LDtk `gridSize` convention. Contains H1 title, Date/Phase header, `[doc->REQ-MAP-02]` tag on its own line, all six required sections (`## Status`, `## Context`, `## Decision`, `## Consequences` with `### Positive` / `### Negative` / `### Neutral`, `## Alternatives considered`, `## References`), the literal phrase `gridSize = 4` (twice), arithmetic `44 / 4 = 11` and `40 / 4 = 10`, and absorbs CONTEXT.md decisions D-01, D-02, D-03, D-04.

## Decisions Made

- None beyond following the plan exactly. The ADR's content decisions (D-01, D-02, D-03, D-04) were pre-locked in `07-CONTEXT.md` §"gridSize ADR"; this plan was a faithful transcription per Pattern B template.

## Deviations from Plan

None — plan executed exactly as written. The ADR mirrors ADR 0008's header ordering as instructed, uses `--no-matrix` lint mode as instructed, omits MATRIX/MX-* citations as instructed, and omits any `## Supersedes` block (ADR 0009 supersedes nothing).

## Issues Encountered

- **One absolute-path slip recovered cleanly:** The initial `Write` call used the main-repo absolute path (`C:\Users\decid\Documents\projects\rebno\docs\adr\...`) instead of the worktree path (`C:\Users\decid\Documents\projects\rebno\.claude\worktrees\agent-a530e386394fc80e8\docs\adr\...`). The misplaced file was detected before commit (worktree `ls` showed it absent), removed from the main repo with `rm`, and re-created at the correct worktree path. The worktree commit (`5f229c7`) is clean; no state leaked into the main repo. This is the exact slip pattern that `<absolute-path safety>` §0b is designed to catch — verify-by-listing inside the worktree caught it pre-commit.

## User Setup Required

None — no external service configuration required. ADR is pure documentation.

## Next Phase Readiness

- ADR 0009 is the first of four Phase 7 convention-lock ADRs (0009 gridSize, 0010 tilesetSourceHash, 0011 BNCentral chunking, 0012 LDtk version pin). The remaining three are parallel siblings in this same wave per `07-PATTERNS.md` §"Cross-Phase Notes for Planner".
- Phase 8 (`08-map-loader-phaser-ldtkloader-testbed`) inherits the locked `gridSize = 4` convention — all Phase 8 `.ldtk` files (including `maps/_smoke/synth-8000x6400.ldtk` and `maps/TestBed_001.ldtk`) MUST be authored with this gridSize across every layer type.
- `pnpm preflight` wiring (Plan 07-06) will gate this ADR via the `lint:adr:0009` script entry it adds to `package.json`.
- Operator's qualitative re-evaluation gate (Phase 8 entity-drift evidence) remains open; nothing in this plan locks future re-litigation.

## Self-Check: PASSED

- `docs/adr/0009-ldtk-gridsize-convention.md` — FOUND (127 lines)
- Commit `5f229c7` — FOUND in `git log` on `worktree-agent-a530e386394fc80e8`
- `lint-adr.mjs --no-matrix` — exit 0 confirmed
- `[doc->REQ-MAP-02]` tag count: 1 (on its own line, between header block and `## Status`)
- `gridSize = 4` literal present: 2 occurrences
- `44 / 4 = 11`: 1 occurrence; `40 / 4 = 10`: 1 occurrence
- All six required ADR sections present (`## Status`, `## Context`, `## Decision`, `## Consequences`, `## Alternatives considered`, `## References`)
- `### Positive` / `### Negative` / `### Neutral` subsections present under `## Consequences`

---
*Phase: 07-workflow-smoke-convention-locks*
*Completed: 2026-05-20*