Repo root hygiene: move FORMAT.md to docs/, contrib/ to bin/, fix bash script style #74

New Issue

clawbot · 2026-08-09T03:42:02+02:00

clawbot commented

2026-08-09 03:42:02 +02:00

Context

Policy: "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: bin/, cmd/, configs/, deploy/,
docs/, internal/, pkg/, share/, static/, web/.

Divergences:

FORMAT.md (the 6.4KB format specification) sits at the repo root. It is
documentation and belongs in docs/. There is currently no docs/
directory at all.
contrib/usage.sh uses contrib/, which is not a canonical subdirectory
name.

Separately, both bash scripts violate the bash style guide, which requires
#!/usr/bin/env bash, set -euo pipefail, and all code inside functions
with main called at the bottom:

bin/gitrev.sh:1-2 — #!/bin/bash, no set -euo pipefail, no main.
contrib/usage.sh:1-2 — #!/bin/bash, has set -euo pipefail, no main.

(script/* are intentionally POSIX sh per scripts-to-rule-them-all and are
correct as-is. Do not touch them.)

Definition of done

FORMAT.md is at docs/FORMAT.md, moved with git mv so history is
preserved.
Every reference to it is updated: AGENTS.md:28, and README.md at lines
12-13, 22, and 143. Search the whole repo for FORMAT.md rather than
trusting that list.
contrib/usage.sh is moved to bin/usage.sh (or docs/ if it is really
example documentation rather than an executable tool — decide and say
which in the commit message), and contrib/ no longer exists.
Both bash scripts use #!/usr/bin/env bash, set -euo pipefail, and wrap
their logic in a main function invoked at the bottom of the file.
Both scripts still work after the rewrite — bin/gitrev.sh in particular
is invoked from Makefile:7 and its output feeds the version ldflags.
make check passes and docker build . succeeds. TODO.md updated in
the same commit.

Implementation requirements

Makefile:7 runs bash $(PWD)/bin/gitrev.sh 2>/dev/null || echo unknown.
Adding set -euo pipefail changes failure behavior — verify the fallback
to unknown still works when the script is run outside a git checkout,
and that a non-git build (e.g. a source tarball) does not now fail hard.
Check .dockerignore and the Dockerfile for references to contrib/ or
FORMAT.md before moving either.
Note that .gitignore currently contains /bin/, which ignores the
directory you are moving a script into. Confirm the moved file is actually
tracked after the move — git status --ignored — and adjust the ignore
rule if needed. This interacts with #72; whichever lands second must
re-verify.
Do not rewrite the contents of FORMAT.md in this change. Moving and
editing in one commit makes the move unreviewable. Content work on the
spec is tracked separately.
Commit title must end with (closes #74).

## Context Policy: "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: `bin/`, `cmd/`, `configs/`, `deploy/`, `docs/`, `internal/`, `pkg/`, `share/`, `static/`, `web/`. Divergences: - `FORMAT.md` (the 6.4KB format specification) sits at the repo root. It is documentation and belongs in `docs/`. There is currently no `docs/` directory at all. - `contrib/usage.sh` uses `contrib/`, which is not a canonical subdirectory name. Separately, both bash scripts violate the bash style guide, which requires `#!/usr/bin/env bash`, `set -euo pipefail`, and all code inside functions with `main` called at the bottom: - `bin/gitrev.sh:1-2` — `#!/bin/bash`, no `set -euo pipefail`, no `main`. - `contrib/usage.sh:1-2` — `#!/bin/bash`, has `set -euo pipefail`, no `main`. (`script/*` are intentionally POSIX `sh` per scripts-to-rule-them-all and are correct as-is. Do not touch them.) ## Definition of done - `FORMAT.md` is at `docs/FORMAT.md`, moved with `git mv` so history is preserved. - Every reference to it is updated: `AGENTS.md:28`, and `README.md` at lines 12-13, 22, and 143. Search the whole repo for `FORMAT.md` rather than trusting that list. - `contrib/usage.sh` is moved to `bin/usage.sh` (or `docs/` if it is really example documentation rather than an executable tool — decide and say which in the commit message), and `contrib/` no longer exists. - Both bash scripts use `#!/usr/bin/env bash`, `set -euo pipefail`, and wrap their logic in a `main` function invoked at the bottom of the file. - Both scripts still work after the rewrite — `bin/gitrev.sh` in particular is invoked from `Makefile:7` and its output feeds the version ldflags. - `make check` passes and `docker build .` succeeds. `TODO.md` updated in the same commit. ## Implementation requirements - `Makefile:7` runs `bash $(PWD)/bin/gitrev.sh 2>/dev/null || echo unknown`. Adding `set -euo pipefail` changes failure behavior — verify the fallback to `unknown` still works when the script is run outside a git checkout, and that a non-git build (e.g. a source tarball) does not now fail hard. - Check `.dockerignore` and the `Dockerfile` for references to `contrib/` or `FORMAT.md` before moving either. - Note that `.gitignore` currently contains `/bin/`, which ignores the directory you are moving a script into. Confirm the moved file is actually tracked after the move — `git status --ignored` — and adjust the ignore rule if needed. This interacts with #72; whichever lands second must re-verify. - Do not rewrite the contents of `FORMAT.md` in this change. Moving and editing in one commit makes the move unreviewable. Content work on the spec is tracked separately. - Commit title must end with ` (closes #74)`.

clawbot added this to the 1.0.0 milestone 2026-08-09 03:42:02 +02:00

clawbot referenced this issue

2026-08-09 03:44:51 +02:00

Make docs/FORMAT.md a complete, independently-implementable specification #84

clawbot commented

2026-08-09 03:45:07 +02:00

One related item deliberately left out of this issue's scope, because it is
an owner decision rather than a fix.

AGENTS.md also sits in the repo root and is also not on the policy's
allow-list of permitted root files. Unlike FORMAT.md and contrib/, there
is no obviously correct place to move it: a root AGENTS.md is the emerging
convention for agent-facing repository instructions, and tooling generally
expects it there. The repo's own TODO.md already flags this as unresolved
("Reconcile root-level AGENTS.md with directory-hygiene policy (keep or
relocate)").

Resolving it properly means amending the authoritative REPO_POLICIES.md in
the prompts repo to carve out AGENTS.md as an allowed root file — which
is a cross-repo change to a user-owned document, not something to do here.

Recommendation: leave AGENTS.md where it is, and amend the policy document
to permit it. The alternative — relocating it to satisfy a rule that predates
the convention — would break the tooling expectation for no practical gain.

Do not action this as part of #74. Flagging it so it is not lost; it needs a
decision from sneak and a change in the prompts repo.

One related item deliberately left out of this issue's scope, because it is an owner decision rather than a fix. `AGENTS.md` also sits in the repo root and is also not on the policy's allow-list of permitted root files. Unlike `FORMAT.md` and `contrib/`, there is no obviously correct place to move it: a root `AGENTS.md` is the emerging convention for agent-facing repository instructions, and tooling generally expects it there. The repo's own `TODO.md` already flags this as unresolved ("Reconcile root-level AGENTS.md with directory-hygiene policy (keep or relocate)"). Resolving it properly means amending the authoritative `REPO_POLICIES.md` in the `prompts` repo to carve out `AGENTS.md` as an allowed root file — which is a cross-repo change to a user-owned document, not something to do here. Recommendation: leave `AGENTS.md` where it is, and amend the policy document to permit it. The alternative — relocating it to satisfy a rule that predates the convention — would break the tooling expectation for no practical gain. Do not action this as part of #74. Flagging it so it is not lost; it needs a decision from `sneak` and a change in the `prompts` repo.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: sneak/mfer#74