Repo layout: non-canonical root files, a confusing scripts/ directory, and a stale reformatted CONVENTIONS.md #97

New Issue

clawbot · 2026-08-09T07:04:00+02:00

clawbot commented

2026-08-09 07:04:00 +02:00

From the audit against the canonical REPO_POLICIES.md, verified against main at 61f42e6.

1. Files in the root that policy places in subdirectories. The policy states:

> Avoid putting files in the repo root unless necessary. Root should contain only project-level config files (README.md, Makefile, Dockerfile, LICENSE, .gitignore, .editorconfig, REPO_POLICIES.md, and language-specific config). Everything else goes in a subdirectory.

with a canonical subdirectory list including configs/ for "configuration templates and examples" and docs/ for "documentation and markdown (README.md stays in root)".

In the root today: CONVENTIONS.md (31 KB, belongs in docs/) and config.example.yml (belongs in configs/).

2. A scripts/ directory alongside the canonical script/. scripts/manual-test.sh sits in a directory that is neither the Scripts to Rule Them All entrypoint dir (script/) nor the canonical bin/. Having both script/ and scripts/ is actively confusing — they differ by one character and mean different things.

3. CONVENTIONS.md is a stale, reformatted copy of a canonical document. The policy requires:

> Cross-project documentation (such as this file) must include last_modified: YYYY-MM-DD in the YAML front matter so it can be kept in sync with the authoritative source as policies evolve.

diff against the canonical GO_HTTP_SERVER_CONVENTIONS.md produces 367 lines of difference. pixa's copy has no YAML front matter at all (canonical has title: and last_modified: 2026-02-22), is reflowed to unwrapped long lines, and uses different list markers and demoted heading levels. Because it was reformatted, there is no way to tell which differences are genuinely stale content and which are cosmetic — which is precisely the problem the last_modified requirement exists to prevent.

The contrast is instructive: the repo's REPO_POLICIES.md is byte-identical to canonical (sha256 117dde7f148ed3cd693b333312f6345a0a0ee84fadbbe5cca559ca6fed4a1775). That is the standard to meet.

Not flagged: TODO.md in the root. It is README-referenced and established convention across sneak's repos.

Definition of done

config.example.yml → configs/; update Dockerfile:71 (COPY config.example.yml /etc/pixa/config.yml) and the README.md:119 reference.
scripts/manual-test.sh → bin/; remove the scripts/ directory; update any references.
CONVENTIONS.md replaced with a byte-identical copy of the canonical GO_HTTP_SERVER_CONVENTIONS.md (front matter and last_modified intact) and moved to docs/ — or deleted outright if the reference to it in REPO_POLICIES.md is considered sufficient. Recommend deleting: a vendored copy is a second thing to keep in sync, and the canonical source is already referenced.
docker build . green (the COPY path change is the one thing that can break the image) and make check green.
Pure file moves plus reference updates — no content changes to anything that moves, so the diff should be reviewable at a glance.

Coordination

Touches README.md and Dockerfile, both of which the open PRs modify. Do after both #55 and #54 merge.

From the audit against the canonical `REPO_POLICIES.md`, verified against `main` at `61f42e6`. **1. Files in the root that policy places in subdirectories.** The policy states: > Avoid putting files in the repo root unless necessary. Root should contain only project-level config files (`README.md`, `Makefile`, `Dockerfile`, `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`, and language-specific config). Everything else goes in a subdirectory. with a canonical subdirectory list including `configs/` for "configuration templates and examples" and `docs/` for "documentation and markdown (README.md stays in root)". In the root today: `CONVENTIONS.md` (31 KB, belongs in `docs/`) and `config.example.yml` (belongs in `configs/`). **2. A `scripts/` directory alongside the canonical `script/`.** `scripts/manual-test.sh` sits in a directory that is neither the Scripts to Rule Them All entrypoint dir (`script/`) nor the canonical `bin/`. Having both `script/` and `scripts/` is actively confusing — they differ by one character and mean different things. **3. `CONVENTIONS.md` is a stale, reformatted copy of a canonical document.** The policy requires: > Cross-project documentation (such as this file) must include `last_modified: YYYY-MM-DD` in the YAML front matter so it can be kept in sync with the authoritative source as policies evolve. `diff` against the canonical `GO_HTTP_SERVER_CONVENTIONS.md` produces **367 lines of difference**. pixa's copy has no YAML front matter at all (canonical has `title:` and `last_modified: 2026-02-22`), is reflowed to unwrapped long lines, and uses different list markers and demoted heading levels. Because it was reformatted, there is no way to tell which differences are genuinely stale content and which are cosmetic — which is precisely the problem the `last_modified` requirement exists to prevent. The contrast is instructive: the repo's `REPO_POLICIES.md` is byte-identical to canonical (sha256 `117dde7f148ed3cd693b333312f6345a0a0ee84fadbbe5cca559ca6fed4a1775`). That is the standard to meet. **Not flagged:** `TODO.md` in the root. It is README-referenced and established convention across sneak's repos. ## Definition of done 1. `config.example.yml` → `configs/`; update `Dockerfile:71` (`COPY config.example.yml /etc/pixa/config.yml`) and the `README.md:119` reference. 2. `scripts/manual-test.sh` → `bin/`; remove the `scripts/` directory; update any references. 3. `CONVENTIONS.md` replaced with a byte-identical copy of the canonical `GO_HTTP_SERVER_CONVENTIONS.md` (front matter and `last_modified` intact) and moved to `docs/` — **or** deleted outright if the reference to it in `REPO_POLICIES.md` is considered sufficient. Recommend deleting: a vendored copy is a second thing to keep in sync, and the canonical source is already referenced. 4. `docker build .` green (the `COPY` path change is the one thing that can break the image) and `make check` green. 5. Pure file moves plus reference updates — no content changes to anything that moves, so the diff should be reviewable at a glance. ## Coordination Touches `README.md` and `Dockerfile`, both of which the open PRs modify. Do **after** both #55 and #54 merge.

clawbot added this to the 1.0.0 milestone 2026-08-09 07:04:00 +02:00

clawbot referenced this issue

2026-08-09 07:04:41 +02:00

Markdown is never formatted: script/fmt covers only Go, and no prettier config exists #100

clawbot referenced this issue

2026-08-09 16:10:39 +02:00

Tracking: 1.0.0 sequencing and critical path #103

Sign in to join this conversation.