Compare commits
2 Commits
1e21653f44
...
llm-prose-
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
cedf98b83e | ||
|
|
368fc0edf0 |
@@ -1,58 +1,3 @@
|
|||||||
# .dockerignore does NOT use .gitignore semantics. Docker matches with
|
|
||||||
# moby/patternmatcher: filepath.Match plus `**`, so `*` does not cross
|
|
||||||
# `/` and an unprefixed pattern is anchored at the context root. Every
|
|
||||||
# depth-independent pattern therefore needs `**/`, or `config/.env` and
|
|
||||||
# `certs/server.key` still ship while the file reads as solved. Only
|
|
||||||
# genuinely root-anchored entries go unprefixed. Never transplant these
|
|
||||||
# into .gitignore, where `**/` is wrong.
|
|
||||||
#
|
|
||||||
# Matching is case-sensitive, so secrets use character ranges rather
|
|
||||||
# than an ALL-CAPS twin, which would still miss `Server.Key`.
|
|
||||||
#
|
|
||||||
# Extend with this repo's own host-built artifacts, written anchored:
|
|
||||||
# `/myapp`, never `**/myapp`, which also matches `cmd/myapp/` and
|
|
||||||
# deletes the package directory from the context.
|
|
||||||
|
|
||||||
# Excluding .git means `git describe` cannot run in any build stage and
|
|
||||||
# fails quietly there; pass the version in with --build-arg VERSION.
|
|
||||||
.git
|
.git
|
||||||
|
node_modules
|
||||||
# Agent scratch: one full checkout of the repo per in-flight agent.
|
.DS_Store
|
||||||
# Anchored because it occurs once where agents run at the repo root.
|
|
||||||
# KNOWN GAP: a repo running agents in subdirectories still ships
|
|
||||||
# `services/api/.claude/` and must add its own anchored entry.
|
|
||||||
.claude
|
|
||||||
|
|
||||||
# Environment files. `*.env` covers bare `.env` and the `prod.env`
|
|
||||||
# convention. Re-include a committed template with a negation if the
|
|
||||||
# build needs one: `!docs/example.env`.
|
|
||||||
**/*.[eE][nN][vV]
|
|
||||||
**/.[eE][nN][vV].*
|
|
||||||
**/.[eE][nN][vV][rR][cC]
|
|
||||||
|
|
||||||
# Private keys and the bundles carrying them. Public certificates
|
|
||||||
# (*.crt, *.cer) are deliberately absent: they are legitimate inputs.
|
|
||||||
**/*.[pP][eE][mM]
|
|
||||||
**/*.[kK][eE][yY]
|
|
||||||
**/*.[pP]12
|
|
||||||
**/*.[pP][fF][xX]
|
|
||||||
**/[iI][dD]_[rR][sS][aA]
|
|
||||||
**/[iI][dD]_[dD][sS][aA]
|
|
||||||
**/[iI][dD]_[eE][cC][dD][sS][aA]
|
|
||||||
**/[iI][dD]_[eE][dD]25519
|
|
||||||
|
|
||||||
# Dependencies: restored inside the image, never copied in.
|
|
||||||
**/node_modules
|
|
||||||
|
|
||||||
# OS metadata.
|
|
||||||
**/.DS_Store
|
|
||||||
**/Thumbs.db
|
|
||||||
|
|
||||||
# Editor state: never a build input, and it churns COPY.
|
|
||||||
**/*.swp
|
|
||||||
**/*.swo
|
|
||||||
**/*~
|
|
||||||
**/*.bak
|
|
||||||
**/.idea
|
|
||||||
**/.vscode
|
|
||||||
**/*.sublime-*
|
|
||||||
|
|||||||
@@ -6,4 +6,4 @@ jobs:
|
|||||||
steps:
|
steps:
|
||||||
# actions/checkout v4.2.2, 2026-02-22
|
# actions/checkout v4.2.2, 2026-02-22
|
||||||
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
|
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
|
||||||
- run: script/cibuild
|
- run: docker build .
|
||||||
|
|||||||
6
.gitignore
vendored
6
.gitignore
vendored
@@ -11,12 +11,6 @@ Thumbs.db
|
|||||||
.vscode/
|
.vscode/
|
||||||
*.sublime-*
|
*.sublime-*
|
||||||
|
|
||||||
# Agent scratch (worktrees of this repo, created and destroyed by
|
|
||||||
# in-flight tooling). Unanchored: .gitignore patterns already match at
|
|
||||||
# every depth, so no prefix is wanted here. This is not a .dockerignore
|
|
||||||
# entry and must not be given a `**/` prefix on the way into one.
|
|
||||||
.claude/
|
|
||||||
|
|
||||||
# Node
|
# Node
|
||||||
node_modules/
|
node_modules/
|
||||||
|
|
||||||
|
|||||||
@@ -1,9 +1,5 @@
|
|||||||
version: "2"
|
version: "2"
|
||||||
|
|
||||||
# Config schema uses the golangci-lint v2 layout (settings live under
|
|
||||||
# linters.settings, not top-level linters-settings) so that the
|
|
||||||
# thresholds below are actually applied by golangci-lint >= v2.
|
|
||||||
|
|
||||||
run:
|
run:
|
||||||
timeout: 5m
|
timeout: 5m
|
||||||
modules-download-mode: readonly
|
modules-download-mode: readonly
|
||||||
@@ -18,7 +14,8 @@ linters:
|
|||||||
- wsl # Deprecated, replaced by wsl_v5
|
- wsl # Deprecated, replaced by wsl_v5
|
||||||
- wrapcheck # Too verbose for internal packages
|
- wrapcheck # Too verbose for internal packages
|
||||||
- varnamelen # Short names like db, id are idiomatic Go
|
- varnamelen # Short names like db, id are idiomatic Go
|
||||||
settings:
|
|
||||||
|
linters-settings:
|
||||||
lll:
|
lll:
|
||||||
line-length: 88
|
line-length: 88
|
||||||
funlen:
|
funlen:
|
||||||
@@ -30,5 +27,6 @@ linters:
|
|||||||
threshold: 100
|
threshold: 100
|
||||||
|
|
||||||
issues:
|
issues:
|
||||||
|
exclude-use-default: false
|
||||||
max-issues-per-linter: 0
|
max-issues-per-linter: 0
|
||||||
max-same-issues: 0
|
max-same-issues: 0
|
||||||
|
|||||||
25
Dockerfile
25
Dockerfile
@@ -1,28 +1,11 @@
|
|||||||
# node 22-alpine, 2026-02-22
|
# node 22-alpine, 2026-02-22
|
||||||
FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34
|
FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34
|
||||||
|
|
||||||
|
RUN apk add --no-cache make
|
||||||
|
|
||||||
WORKDIR /app
|
WORKDIR /app
|
||||||
|
|
||||||
# Makes script/lint run the linter directly rather than building
|
|
||||||
# Dockerfile.lint, which would need a docker daemon here.
|
|
||||||
ENV LINT_IN_CONTAINER=1
|
|
||||||
|
|
||||||
# script/bootstrap installs all prerequisites. Manifests are copied
|
|
||||||
# first so that layer stays cached until dependencies change.
|
|
||||||
COPY script/ script/
|
|
||||||
COPY package.json yarn.lock ./
|
COPY package.json yarn.lock ./
|
||||||
RUN script/bootstrap
|
RUN yarn install --frozen-lockfile
|
||||||
|
|
||||||
COPY . .
|
COPY . .
|
||||||
|
|
||||||
# CHECK_EPOCH is a per-invocation nonce from script/cibuild and
|
RUN make check
|
||||||
# script/docker; without it an unchanged tree serves this layer from
|
|
||||||
# cache and the build reports a green it never ran. ARG is stage-scoped,
|
|
||||||
# so declare it in every stage that runs checks. The guard fails a bare
|
|
||||||
# `docker build .`, which would otherwise reuse the empty (and therefore
|
|
||||||
# stable) cache key. The value is also expanded into the check command,
|
|
||||||
# so the cache miss does not depend on BuildKit's handling of an
|
|
||||||
# unreferenced ARG; keep both references.
|
|
||||||
ARG CHECK_EPOCH
|
|
||||||
RUN [ -n "$CHECK_EPOCH" ] || exit 1
|
|
||||||
RUN echo "check epoch: ${CHECK_EPOCH}" && make check
|
|
||||||
|
|||||||
@@ -1,27 +0,0 @@
|
|||||||
# Lint-only image, built by script/lint when it is not already inside a
|
|
||||||
# container. Linting is a build step, so a successful build is a clean
|
|
||||||
# lint, and nothing is bind-mounted, which matters when the daemon is
|
|
||||||
# remote.
|
|
||||||
#
|
|
||||||
# node 22-alpine, 2026-02-22
|
|
||||||
FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34
|
|
||||||
|
|
||||||
WORKDIR /app
|
|
||||||
|
|
||||||
# Makes script/lint run the linter directly instead of recursing into
|
|
||||||
# another docker build, which has no daemon here.
|
|
||||||
ENV LINT_IN_CONTAINER=1
|
|
||||||
|
|
||||||
COPY script/ script/
|
|
||||||
COPY package.json yarn.lock ./
|
|
||||||
RUN script/bootstrap
|
|
||||||
|
|
||||||
COPY . .
|
|
||||||
|
|
||||||
# ARG sits after the dependency layer so that layer stays cached and
|
|
||||||
# only the lint re-runs. The guard fails a bare `docker build
|
|
||||||
# -f Dockerfile.lint .`, which would otherwise reuse the empty (stable)
|
|
||||||
# cache key and report a lint it never ran.
|
|
||||||
ARG CHECK_EPOCH
|
|
||||||
RUN [ -n "$CHECK_EPOCH" ] || exit 1
|
|
||||||
RUN echo "lint epoch: ${CHECK_EPOCH}" && make lint
|
|
||||||
35
Makefile
35
Makefile
@@ -1,32 +1,31 @@
|
|||||||
.PHONY: bootstrap setup test lint fmt fmt-check check docker hooks
|
.PHONY: test lint fmt fmt-check check docker hooks
|
||||||
|
|
||||||
# Makefile targets are thin shims; the implementations live in script/
|
# flags are repeated here (also in .prettierrc) so this Makefile works
|
||||||
# per the scripts-to-rule-them-all pattern (see the Entrypoints section
|
# standalone when copied as a template
|
||||||
# of README.md).
|
PRETTIER := yarn run prettier
|
||||||
|
|
||||||
bootstrap:
|
|
||||||
@script/bootstrap
|
|
||||||
|
|
||||||
setup:
|
|
||||||
@script/setup
|
|
||||||
|
|
||||||
test:
|
test:
|
||||||
@script/test
|
@echo "No tests defined."
|
||||||
|
|
||||||
lint:
|
lint:
|
||||||
@script/lint
|
@echo "Linting markdown files..."
|
||||||
|
@$(PRETTIER) --check '**/*.md' --tab-width 4 --prose-wrap always
|
||||||
|
|
||||||
fmt:
|
fmt:
|
||||||
@script/fmt
|
@$(PRETTIER) --write '**/*.md' --tab-width 4 --prose-wrap always
|
||||||
|
|
||||||
fmt-check:
|
fmt-check:
|
||||||
@script/fmt-check
|
@$(PRETTIER) --check '**/*.md' --tab-width 4 --prose-wrap always
|
||||||
|
|
||||||
check:
|
check: test lint fmt-check
|
||||||
@script/check
|
|
||||||
|
|
||||||
docker:
|
docker:
|
||||||
@script/docker
|
docker build -t prompts .
|
||||||
|
|
||||||
hooks:
|
hooks:
|
||||||
@script/install-precommit
|
@printf '#!/bin/sh\nset -e\n' > .git/hooks/pre-commit
|
||||||
|
@if [ -f go.mod ]; then \
|
||||||
|
printf 'go mod tidy\ngo fmt ./...\ngit diff --exit-code -- go.mod go.sum || { echo "go mod tidy changed files; please stage and retry"; exit 1; }\n' >> .git/hooks/pre-commit; \
|
||||||
|
fi
|
||||||
|
@printf 'make check\n' >> .git/hooks/pre-commit
|
||||||
|
@chmod +x .git/hooks/pre-commit
|
||||||
|
|||||||
37
README.md
37
README.md
@@ -102,43 +102,6 @@ cd prompts
|
|||||||
Prompts are stored as Markdown files in `prompts/`. Copy or reference them as
|
Prompts are stored as Markdown files in `prompts/`. Copy or reference them as
|
||||||
needed in your projects.
|
needed in your projects.
|
||||||
|
|
||||||
## Entrypoints
|
|
||||||
|
|
||||||
This repository adheres to the
|
|
||||||
[Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
|
|
||||||
standard: normalized scripts in `script/` are the entrypoints for the
|
|
||||||
development workflow, and the Makefile targets are thin shims that call them.
|
|
||||||
The scripts are POSIX sh (not bash) so they run in minimal containers such as
|
|
||||||
alpine. We provide:
|
|
||||||
|
|
||||||
- `script/bootstrap` — install all dependencies (yarn install)
|
|
||||||
- `script/setup` — set up the repo for development after a fresh clone: runs
|
|
||||||
`script/bootstrap`, then `script/install-precommit`
|
|
||||||
- `script/projectname` — output the project name (our own extension); used by
|
|
||||||
`script/docker` for the image tag
|
|
||||||
- `script/test` — run the test suite (no tests defined here)
|
|
||||||
- `script/lint` — lint the markdown files with prettier. Inside a container
|
|
||||||
(`LINT_IN_CONTAINER=1`, set by both Dockerfiles) it runs prettier directly; on
|
|
||||||
a host it builds `Dockerfile.lint` so the linter still runs in a container
|
|
||||||
- `script/fmt` — format all markdown files with prettier (writes)
|
|
||||||
- `script/fmt-check` — check formatting (read-only)
|
|
||||||
- `script/check` — run all checks: `test`, `lint`, `fmt-check` (our own
|
|
||||||
extension)
|
|
||||||
- `script/docker` — build the Docker image, tagged via `script/projectname`
|
|
||||||
(byte-identical across repos); passes the same `CHECK_EPOCH` nonce as
|
|
||||||
`script/cibuild`
|
|
||||||
- `script/cibuild` — cd to the repo root, assign `epoch="$(date +%s%N)$$"`, then
|
|
||||||
`docker build --build-arg CHECK_EPOCH="$epoch" .` (what CI runs; the image
|
|
||||||
build runs `script/check`, and the per-invocation `CHECK_EPOCH` nonce is what
|
|
||||||
stops Docker serving that check from cache on an unchanged tree — a bare
|
|
||||||
`docker build .` fails closed on purpose)
|
|
||||||
- `script/precommit` — run by the git pre-commit hook (our own extension); calls
|
|
||||||
`script/check`
|
|
||||||
- `script/install-precommit` — installs the git pre-commit hook (our own
|
|
||||||
extension); `make hooks` shims to it
|
|
||||||
|
|
||||||
`make hooks` installs the pre-commit hook that runs `script/precommit`.
|
|
||||||
|
|
||||||
## Rationale
|
## Rationale
|
||||||
|
|
||||||
LLM prompts, especially development policies, benefit from version control and a
|
LLM prompts, especially development policies, benefit from version control and a
|
||||||
|
|||||||
158
TODO.md
158
TODO.md
@@ -1,158 +0,0 @@
|
|||||||
# Workflow
|
|
||||||
|
|
||||||
- branch (from `main`)
|
|
||||||
- do the work in Next Step
|
|
||||||
- move Next Step to the top of Completed Steps
|
|
||||||
- move the top item of Future Steps into Next Step
|
|
||||||
- commit (`TODO.md` changes in the same commit as the work)
|
|
||||||
- merge to `main` if the branch is not protected, otherwise open a PR
|
|
||||||
- push
|
|
||||||
|
|
||||||
# Status
|
|
||||||
|
|
||||||
pre-1.0
|
|
||||||
|
|
||||||
# Next Step
|
|
||||||
|
|
||||||
Finish the two draft prompt documents in the working tree and commit them:
|
|
||||||
prompts/FIXUP_CLEAN.md (currently a near-empty stub) and prompts/FIXUP_REPORT.md
|
|
||||||
(a rough draft). Write the missing content, run `make fmt` so they pass
|
|
||||||
fmt-check, and commit.
|
|
||||||
|
|
||||||
# Completed Steps
|
|
||||||
|
|
||||||
- 2026-08-10: Moved every lint run into a container. `script/lint` now runs the
|
|
||||||
linter directly when `LINT_IN_CONTAINER=1` and otherwise builds
|
|
||||||
`Dockerfile.lint`, so the linter never runs on a developer host — closing the
|
|
||||||
content-keyed result cache that produced a confirmed false green, the
|
|
||||||
host-global `$TMPDIR/golangci-lint.lock`, and host/container version skew.
|
|
||||||
Detection is on that marker alone: a false negative inside a container fails
|
|
||||||
loudly on the missing daemon, while a false positive on a host would silently
|
|
||||||
restore host linting, so `/.dockerenv` is rejected outright — measured absent
|
|
||||||
inside BuildKit `RUN` steps and present on hosts that are themselves
|
|
||||||
containers. Everything else keeps its existing shape: `make check` still runs
|
|
||||||
in the image, `script/cibuild` is still one build, and the Go multistage lint
|
|
||||||
stage survives with `ENV LINT_IN_CONTAINER=1`. `Dockerfile.lint` carries the
|
|
||||||
same `CHECK_EPOCH` guard, with the `ARG` below the dependency layer so only
|
|
||||||
the lint re-runs. The `script/bootstrap` golangci-lint install and the
|
|
||||||
per-checkout cache/lock/`.lint-cache` wrapper are deleted as superseded; a JS
|
|
||||||
repo's `yarn install` stays, since the rule is about where a verdict comes
|
|
||||||
from, not about which binaries exist. `golangci-lint config verify` was kept
|
|
||||||
on measurement: a bogus config key passes `golangci-lint run` with `0 issues`
|
|
||||||
and fails `config verify`, and every case reproduced byte-identically under
|
|
||||||
`--network none`, so the schema is embedded and the line costs no network.
|
|
||||||
Comment blocks across the touched files were cut hard in the same pass.
|
|
||||||
- 2026-08-09: Made a golangci-lint result belong to the tree that asked for it.
|
|
||||||
REPO_POLICIES.md now carries the canonical Go `script/lint`, which gives the
|
|
||||||
linter per-checkout `GOLANGCI_LINT_CACHE` and per-checkout `TMPDIR`. The two
|
|
||||||
are separate defects and the second is the one that gets dropped: the result
|
|
||||||
cache is keyed on file content rather than location, so checkouts holding
|
|
||||||
identical files serve each other's findings under the other's path, while the
|
|
||||||
concurrency lock is `$TMPDIR/golangci-lint.lock` — host-global, independent of
|
|
||||||
the cache, and unaffected by isolating it. Moving workers from worktrees to
|
|
||||||
their own clones does not help either half; it only removes the foreign-path
|
|
||||||
artefact that made the defect visible. The lock error is retried rather than
|
|
||||||
surfaced, because it is not a result: it exits non-zero exactly as findings
|
|
||||||
do, and reporting it as findings sends a correct branch back for rework.
|
|
||||||
Detection is on the stderr stream and never on exit status, so a finding
|
|
||||||
quoting the lock message in source cannot be retried away, and exhaustion
|
|
||||||
exits 75 with a VOID message rather than passing or failing quietly.
|
|
||||||
`--allow-serial-runners` (which keeps the guard and queues) covers the
|
|
||||||
same-checkout overlap that `TMPDIR` scoping cannot; `--allow-parallel-runners`
|
|
||||||
is rejected outright. The stdout and stderr capture files are per invocation
|
|
||||||
rather than per checkout, because serialising the linter does not serialise
|
|
||||||
the shell's redirections: two runs in one checkout — the overlap the flag
|
|
||||||
exists to support — would otherwise truncate and read each other's output,
|
|
||||||
which is the same defect one layer above where it was fixed. Both checklists
|
|
||||||
gained the corresponding items, since a half-fix that sets only the cache
|
|
||||||
reads as complete. `GOCACHE` was measured and does not need isolating.
|
|
||||||
Verified with the snippet extracted from the committed document and executed
|
|
||||||
as a consuming repo would adopt it, against paired controls: contamination
|
|
||||||
reproduced on the pre-fix form and absent on the adopted one, retry engaged,
|
|
||||||
exhaustion loud, a genuine finding still reported, and a held host lock
|
|
||||||
failing the pre-fix script while leaving the adopted one untouched.
|
|
||||||
- 2026-08-09: Kept in-repo agent scratch out of the Docker build context and out
|
|
||||||
of version control. `.claude/` holds one worktree — an entire additional
|
|
||||||
checkout of the repo — per in-flight agent, and under `COPY . .` all of it was
|
|
||||||
reaching the image: another session's unreviewed, sometimes uncommitted work,
|
|
||||||
inflating the context by a multiple of the repo and invalidating `COPY` for
|
|
||||||
reasons unrelated to the repo's own content. The `.dockerignore` entry is
|
|
||||||
root-anchored, because the directory occurs exactly once where agents run at
|
|
||||||
the repo root and the `**/` form additionally deletes any nested directory of
|
|
||||||
that name — with the residual gap that follows from anchoring (a monorepo
|
|
||||||
running agents in subdirectories still ships `services/api/.claude/`) stated
|
|
||||||
in the canonical `.dockerignore`, the policy and the existing-repo checklist,
|
|
||||||
since consuming repos receive the files rather than the tracker; the
|
|
||||||
`.gitignore` entry is unanchored, because `.gitignore` patterns already match
|
|
||||||
at every depth, and each file is written to its own semantics rather than
|
|
||||||
derived from the other. Also closed the consequence that ships broken
|
|
||||||
silently: excluding `.git` means `git describe` cannot run in any build stage
|
|
||||||
and yields an empty version without erroring, so `script/docker` and
|
|
||||||
`script/cibuild` now compute the version on the host and pass
|
|
||||||
`--build-arg VERSION`, and `REPO_POLICIES.md` states where `VERSION` comes
|
|
||||||
from instead of leaving the reader to fill the gap with `git describe` inside
|
|
||||||
the build. The two Go documents that carry the `GOLDFLAGS` pattern were
|
|
||||||
corrected in the same pass, from `:=` to `?=`, since a `$(shell git describe)`
|
|
||||||
evaluated inside a build stage is exactly the empty version this closes.
|
|
||||||
Verified by enumerating a probe image before, after, and against the
|
|
||||||
`**/`-prefixed form, with a positive control and the `CHECK_EPOCH` cache
|
|
||||||
verification re-run under the changed build context.
|
|
||||||
- 2026-08-09: Closed the secret exposure in the canonical `.dockerignore`: a
|
|
||||||
developer's local `.env`, `*.pem` or `*.key` was reaching the Docker build
|
|
||||||
context under `COPY . .`, invisible to every git-based check because
|
|
||||||
`.gitignore` covers it. The patterns are written to `.dockerignore`'s own
|
|
||||||
`moby/patternmatcher` semantics — `**/`-prefixed so they hold at every depth,
|
|
||||||
which also fixes nested `node_modules` — rather than transplanted from
|
|
||||||
`.gitignore`, whose unprefixed form protects only the repository root while
|
|
||||||
reading as solved. Coverage extends past the `.env`/`.pem`/`.key` trio to the
|
|
||||||
`prod.env` convention, `.envrc`, PKCS#12 bundles and extensionless SSH keys,
|
|
||||||
every one of them case-folded with character ranges because matching is
|
|
||||||
case-sensitive and an ALL-CAPS twin per pattern still misses `Server.Key`.
|
|
||||||
`REPO_POLICIES.md` and both repo checklists now state that asymmetry and
|
|
||||||
require verification by enumerating the image rather than by reading the
|
|
||||||
patterns. Verified with a probe image before, against three naive forms
|
|
||||||
(unprefixed, lowercase-only, ALL-CAPS-doubled), and after.
|
|
||||||
- 2026-08-09: Made the pinned golangci-lint actually propagate: REPO_POLICIES.md
|
|
||||||
now carries the canonical `script/bootstrap` snippet for Go repos, which
|
|
||||||
installs when the installed version does not match the pin (the old
|
|
||||||
`if missing` guard tested PATH presence only, so pins were inert on any
|
|
||||||
provisioned machine and CI silently disagreed with local) and then re-resolves
|
|
||||||
the binary through `PATH` and fails loudly, naming the shadowing path, when
|
|
||||||
the install did not take effect — the failure mode the naive
|
|
||||||
compare-then-install fix leaves behind while reporting success.
|
|
||||||
- 2026-08-09: Fixed the false green in the canonical CI gate: `script/cibuild`
|
|
||||||
and `script/docker` now pass a per-invocation `CHECK_EPOCH` nonce, and the
|
|
||||||
`Dockerfile` (plus the Go multistage template in REPO_POLICIES.md, in both its
|
|
||||||
lint and builder stages) declares `ARG CHECK_EPOCH` with a guard that makes a
|
|
||||||
bare `docker build .` fail closed. Corrected the org-canonical text that
|
|
||||||
asserted a successful build implies all checks pass, across every document
|
|
||||||
carrying it: `REPO_POLICIES.md`, both repo checklists (which still told agents
|
|
||||||
to write the pre-fix `script/cibuild` and ended on an acceptance item the
|
|
||||||
guard makes unsatisfiable), and the Go styleguide.
|
|
||||||
- 2026-08-07: Set the canonical `.golangci.yml` to the org-standard v2-schema
|
|
||||||
config already deployed byte-identical across the org's Go repos (settings
|
|
||||||
under `linters.settings` so thresholds like lll/funlen/cyclop/dupl actually
|
|
||||||
apply under golangci-lint v2). Recorded the canonical golangci-lint version
|
|
||||||
(v2.12.2, commit-pinned) in REPO_POLICIES.md.
|
|
||||||
- 2026-03-20: Strengthened constructor naming and Params struct rules in the Go
|
|
||||||
styleguide.
|
|
||||||
- 2026-03-18: Documented fail-fast Dockerfile lint stage and conditional -v test
|
|
||||||
rerun patterns in REPO_POLICIES.md.
|
|
||||||
- 2026-03-11: Added HTTP service hardening policy for 1.0 releases.
|
|
||||||
- 2026-03-10: Added policy: no build artifacts in repos.
|
|
||||||
- 2026-03-04: Added LLM prose tells reference and copyediting checklist, then
|
|
||||||
several self-applied revision passes.
|
|
||||||
- 2026-02-28: Expanded the pre-1.0 schema migration rule; added clawpub
|
|
||||||
reference.
|
|
||||||
- 2026-02-23: Added Go style rules (no type-only packages, Stringer for
|
|
||||||
string-based types); template repos section in README.
|
|
||||||
- 2026-02-22: Initial policy corpus: REPO_POLICIES.md, code styleguides
|
|
||||||
(general, Go, JS, Python), repo checklists, CI policy, hash pinning, Go HTTP
|
|
||||||
server conventions, repo scaffolding.
|
|
||||||
|
|
||||||
# Future Steps
|
|
||||||
|
|
||||||
- Finish, format, and commit FIXUP_CLEAN.md and FIXUP_REPORT.md (the Next Step).
|
|
||||||
- Commit this TODO.md at the repo root; it is the last missing policy file.
|
|
||||||
- Decide the fate of untracked resume.sh: commit it or delete it.
|
|
||||||
- Add more prompt templates for common development tasks (from README TODO).
|
|
||||||
@@ -1,6 +1,6 @@
|
|||||||
---
|
---
|
||||||
title: Code Styleguide — Go
|
title: Code Styleguide — Go
|
||||||
last_modified: 2026-08-10
|
last_modified: 2026-02-22
|
||||||
---
|
---
|
||||||
|
|
||||||
1. Try to hard wrap long lines at 77 characters or less.
|
1. Try to hard wrap long lines at 77 characters or less.
|
||||||
@@ -49,20 +49,7 @@ last_modified: 2026-08-10
|
|||||||
```
|
```
|
||||||
|
|
||||||
```make
|
```make
|
||||||
# ?= rather than := because this `$(shell git describe ...)` is only
|
VERSION := $(shell git describe --always --dirty)
|
||||||
# correct on the host. `.dockerignore` excludes `.git`, so evaluated
|
|
||||||
# inside a build stage it expands to the empty string without failing
|
|
||||||
# and the binary reports no version at all. The version is computed on
|
|
||||||
# the host by `script/docker` / `script/cibuild` and passed with
|
|
||||||
# `--build-arg VERSION=...`. If this repo's Dockerfile compiles by
|
|
||||||
# invoking make (`RUN make build`), `ARG VERSION` in that stage puts the
|
|
||||||
# value in the environment and `?=` defers to it. The canonical Go
|
|
||||||
# template in REPO_POLICIES.md instead runs `go build` directly with
|
|
||||||
# `-ldflags "... -X main.Version=${VERSION}"`, so there this Makefile is
|
|
||||||
# a host-only path — but it is still `?=`, because a repo that later
|
|
||||||
# moves the build behind make must not silently start shipping an empty
|
|
||||||
# version. See the git-describe rule in REPO_POLICIES.md.
|
|
||||||
VERSION ?= $(shell git describe --always --dirty)
|
|
||||||
BUILDARCH := $(shell uname -m)
|
BUILDARCH := $(shell uname -m)
|
||||||
|
|
||||||
GOLDFLAGS += -X main.Version=$(VERSION)
|
GOLDFLAGS += -X main.Version=$(VERSION)
|
||||||
@@ -111,23 +98,12 @@ last_modified: 2026-08-10
|
|||||||
|
|
||||||
1. For anything beyond a simple script or tool, or anything that is going to
|
1. For anything beyond a simple script or tool, or anything that is going to
|
||||||
run in any sort of "production" anywhere, make sure it passes
|
run in any sort of "production" anywhere, make sure it passes
|
||||||
`golangci-lint`. Run it with `make lint`, never by invoking the binary: the
|
`golangci-lint`.
|
||||||
linter always runs in a container, and `golangci-lint` is not installed on
|
|
||||||
the host by any repo. Invoked directly on a shared host it reads a result
|
|
||||||
cache keyed on file content rather than location, and a host-global lock, so
|
|
||||||
its answer may belong to another checkout entirely.
|
|
||||||
|
|
||||||
1. Write a `Dockerfile` for every repo, even if it only runs the tests and
|
1. Write a `Dockerfile` for every repo, even if it only runs the tests and
|
||||||
linting. `script/cibuild` and `script/docker` should always make sure that
|
linting. `docker build .` should always make sure that the code is in an
|
||||||
the code is in an able-to-be-compiled state, linted, and any tests run, and
|
able-to-be-compiled state, linted, and any tests run. The Docker build
|
||||||
the build should fail if linting doesn't pass. That guarantee holds only
|
should fail if linting doesn't pass.
|
||||||
because those scripts pass a per-invocation `CHECK_EPOCH` build arg that
|
|
||||||
busts the check layers out of the Docker cache; without it an unchanged tree
|
|
||||||
serves those layers from cache and the build reports a green it never ran. A
|
|
||||||
bare `docker build .` fails closed by design, on the `[ -n "$CHECK_EPOCH" ]`
|
|
||||||
guard — always go through `script/cibuild` or `script/docker`. See
|
|
||||||
[Repository Policies](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md)
|
|
||||||
for the canonical form.
|
|
||||||
|
|
||||||
1. Every repo must have a `Makefile`. See
|
1. Every repo must have a `Makefile`. See
|
||||||
[Repository Policies](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md)
|
[Repository Policies](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md)
|
||||||
@@ -160,15 +136,8 @@ last_modified: 2026-08-10
|
|||||||
1. Provide a .gitignore file that ignores at least `*.log`, `*.out`, and
|
1. Provide a .gitignore file that ignores at least `*.log`, `*.out`, and
|
||||||
`*.test` files, as well as any binaries.
|
`*.test` files, as well as any binaries.
|
||||||
|
|
||||||
1. Constructors **must** be called `New()`. `modulename.New()` works great if
|
1. Constructors should be called `New()` whenever possible. `modulename.New()`
|
||||||
you name the packages properly. If the constructor creates an instance from
|
works great if you name the packages properly.
|
||||||
an existing value or representation, `From<Something>()` (e.g.
|
|
||||||
`FromBytes()`, `FromConfig()`) is also acceptable. If the package contains
|
|
||||||
multiple types and `New()` is ambiguous, `NewThing()` is occasionally
|
|
||||||
acceptable — but prefer restructuring packages so each type gets its own
|
|
||||||
package and a plain `New()`. Do not invent creative constructor names like
|
|
||||||
`Create()`, `Make()`, `Build()`, `Open()` (unless wrapping an OS resource),
|
|
||||||
or `Init()`. If you see a constructor with a non-standard name, rename it.
|
|
||||||
|
|
||||||
1. Don't make packages too big. Break them up.
|
1. Don't make packages too big. Break them up.
|
||||||
|
|
||||||
@@ -180,15 +149,9 @@ last_modified: 2026-08-10
|
|||||||
1. Use descriptive names for modules and filenames. Avoid generic names like
|
1. Use descriptive names for modules and filenames. Avoid generic names like
|
||||||
`server`. `util` is banned.
|
`server`. `util` is banned.
|
||||||
|
|
||||||
1. Constructors **must** take a `Params` struct (or `ThingParams` when
|
1. Constructors should take a Params struct if they need more than 1-2
|
||||||
`NewThing()` is used), even for a single argument. Named fields in a Params
|
arguments. Positional arguments are an endless source of bugs and should be
|
||||||
struct are always clearer than positional arguments. Positional arguments
|
avoided whenever possible.
|
||||||
for constructors are an endless source of bugs — they make call sites
|
|
||||||
unreadable, invite wrong-order errors that the compiler can't catch when
|
|
||||||
types coincide, and force every caller to update when a new field is added.
|
|
||||||
The only exception is when the single argument is stupidly obvious from
|
|
||||||
context — e.g. `featureflag.New(true)` or `thing.NewFromReader(r)`. When in
|
|
||||||
doubt, use a Params struct.
|
|
||||||
|
|
||||||
1. Use `context.Context` for all functions that need it. If you don't need it,
|
1. Use `context.Context` for all functions that need it. If you don't need it,
|
||||||
you can pass `context.Background()`. Anything long-running should get and
|
you can pass `context.Background()`. Anything long-running should get and
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
---
|
---
|
||||||
title: Existing Repo Checklist
|
title: Existing Repo Checklist
|
||||||
last_modified: 2026-08-10
|
last_modified: 2026-02-22
|
||||||
---
|
---
|
||||||
|
|
||||||
Use this checklist when beginning work in a repo that may not yet conform to our
|
Use this checklist when beginning work in a repo that may not yet conform to our
|
||||||
@@ -24,66 +24,15 @@ with your task.
|
|||||||
- [ ] `LICENSE` file exists and matches the README
|
- [ ] `LICENSE` file exists and matches the README
|
||||||
- [ ] `REPO_POLICIES.md` exists and version date is current — fetch from
|
- [ ] `REPO_POLICIES.md` exists and version date is current — fetch from
|
||||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md`
|
`https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md`
|
||||||
- [ ] `.gitignore` is comprehensive (OS, editor, agent scratch, language
|
- [ ] `.gitignore` is comprehensive (OS, editor, language artifacts, secrets) —
|
||||||
artifacts, secrets) — fetch from
|
fetch from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore`
|
||||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` if missing.
|
if missing
|
||||||
An existing repo usually has a hand-written one that is never re-fetched,
|
|
||||||
so check the entries rather than the file's presence: `.claude/` in
|
|
||||||
particular, unanchored, so agent worktrees cannot be committed by
|
|
||||||
accident. Do not give it a `**/` prefix — that is a `.dockerignore` form
|
|
||||||
and is wrong here.
|
|
||||||
- [ ] `.editorconfig` exists — fetch from
|
- [ ] `.editorconfig` exists — fetch from
|
||||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/.editorconfig`
|
`https://git.eeqj.de/sneak/prompts/raw/branch/main/.editorconfig`
|
||||||
- [ ] `Dockerfile` and `.dockerignore` exist (fetch `.dockerignore` from
|
- [ ] `Dockerfile` and `.dockerignore` exist; Dockerfile runs `make check` as a
|
||||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore`);
|
build step — fetch `.dockerignore` from
|
||||||
Dockerfile runs `make check` as a build step, and every stage containing a
|
`https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore`
|
||||||
check-running `RUN` declares `ARG CHECK_EPOCH` with the
|
- [ ] Gitea Actions workflow in `.gitea/workflows/` runs `docker build .` on
|
||||||
`RUN [ -n "$CHECK_EPOCH" ] || exit 1` guard immediately below it — see the
|
|
||||||
`CHECK_EPOCH` rule in `REPO_POLICIES.md`. Without them the check layer is
|
|
||||||
served from cache on an unchanged tree and the build reports a green it
|
|
||||||
never ran.
|
|
||||||
- [ ] **Every stage that runs checks sets `ENV LINT_IN_CONTAINER=1`** — the lint
|
|
||||||
stage and the build stage both. This is the item an existing repo most
|
|
||||||
often fails after adopting the containerised lint: without it
|
|
||||||
`script/lint` tries to build `Dockerfile.lint` from inside a build step,
|
|
||||||
where there is no daemon.
|
|
||||||
- [ ] `Dockerfile.lint` exists and `script/lint` builds it when not already in a
|
|
||||||
container — see the containerised-lint rule in `REPO_POLICIES.md`. Base
|
|
||||||
image pinned by sha256 with a version/date comment, `ARG CHECK_EPOCH`
|
|
||||||
**after** the dependency layer with the guard below it.
|
|
||||||
- [ ] `.dockerignore` excludes the repo's own host-built artifacts (compiled
|
|
||||||
binaries, test binaries, coverage output), written root-anchored —
|
|
||||||
`/myapp`, never `**/myapp`, which would also match `cmd/myapp/`. An
|
|
||||||
existing repo is where such a binary is likeliest to already be sitting in
|
|
||||||
the build context, invisible to git.
|
|
||||||
- [ ] `.dockerignore` excludes `.claude`, root-anchored and with no `**/`
|
|
||||||
prefix. Agent worktrees are entire checkouts of the repo, so they inflate
|
|
||||||
the context by a multiple of it and can copy another session's unreviewed
|
|
||||||
work into an image layer. Confirm by enumerating the image, not by reading
|
|
||||||
the file — `.gitignore` hides these from `git status` too.
|
|
||||||
- [ ] **Do agents in this repo run anywhere other than the repo root?** The
|
|
||||||
scratch directory is created in the agent's working directory, so the
|
|
||||||
canonical anchored entry misses `services/api/.claude/` in a monorepo with
|
|
||||||
a per-service agent — it still reaches the build context and the image. An
|
|
||||||
existing repo is where such a layout already exists, so check it here
|
|
||||||
rather than assuming the canonical entry covers you: add anchored entries
|
|
||||||
for the subdirectories that have one (`/services/api/.claude`), or
|
|
||||||
`**/.claude` once you have confirmed no legitimately named nested
|
|
||||||
directory would be caught.
|
|
||||||
- [ ] If the repo embeds a version in a binary, that version is computed on the
|
|
||||||
host and passed with `--build-arg VERSION=...` by `script/docker` and
|
|
||||||
`script/cibuild`. No stage calls `git describe`: `.dockerignore` excludes
|
|
||||||
`.git`, so it yields an empty version without failing the build. A
|
|
||||||
tag-derived version additionally needs `fetch-depth: 0` on the CI checkout
|
|
||||||
step, which clones shallow and fetches no tags by default.
|
|
||||||
- [ ] Every depth-independent pattern in `.dockerignore` carries a `**/` prefix;
|
|
||||||
only genuinely root-anchored entries such as `.git` are unprefixed, and
|
|
||||||
`.gitignore`'s patterns have not been transplanted unmodified.
|
|
||||||
`.dockerignore` anchors an unprefixed pattern at the context root, so the
|
|
||||||
transplanted form leaves `config/.env` and `certs/server.key` in the build
|
|
||||||
context while reading as solved — see the `.dockerignore` rule in
|
|
||||||
`REPO_POLICIES.md`.
|
|
||||||
- [ ] Gitea Actions workflow in `.gitea/workflows/` runs `script/cibuild` on
|
|
||||||
push — reference
|
push — reference
|
||||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitea/workflows/check.yml`
|
`https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitea/workflows/check.yml`
|
||||||
- [ ] Language-specific config:
|
- [ ] Language-specific config:
|
||||||
@@ -96,37 +45,12 @@ with your task.
|
|||||||
- [ ] Python: `pyproject.toml`
|
- [ ] Python: `pyproject.toml`
|
||||||
- [ ] Docs/writing: `.prettierrc`, `.prettierignore` (same URLs as above)
|
- [ ] Docs/writing: `.prettierrc`, `.prettierignore` (same URLs as above)
|
||||||
|
|
||||||
# Makefile and script/ Entrypoints
|
# Makefile
|
||||||
|
|
||||||
- [ ] `Makefile` exists in root — reference
|
- [ ] `Makefile` exists in root — reference
|
||||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`
|
`https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`
|
||||||
- [ ] Has targets: `test`, `lint`, `fmt`, `fmt-check`, `check`, `docker`,
|
- [ ] Has targets: `test`, `lint`, `fmt`, `fmt-check`, `check`, `docker`,
|
||||||
`hooks`
|
`hooks`
|
||||||
- [ ] Target implementations live in `script/` (scripts-to-rule-them-all);
|
|
||||||
Makefile targets are thin shims calling them — model scripts at
|
|
||||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/script/<name>`
|
|
||||||
- [ ] `script/precommit` exists and the pre-commit hook (installed by
|
|
||||||
`script/install-precommit`, shimmed by `make hooks`) runs it
|
|
||||||
- [ ] README has an **Entrypoints** section documenting the `script/`
|
|
||||||
entrypoints and linking the standard
|
|
||||||
- [ ] `script/lint` is the canonical detect-and-branch form, and no host
|
|
||||||
invocation anywhere in the repo can produce a lint **verdict** — grep for
|
|
||||||
the linter's own name across `script/`, the `Makefile` and CI config, not
|
|
||||||
just `script/lint`. A second path is likeliest here: a `make lint-fast`,
|
|
||||||
an older container-versus-host branch, or a CI step calling the binary
|
|
||||||
directly. **Expected hits that are not the defect**: `script/fmt`, and in
|
|
||||||
a repo whose formatter is also its linter, `script/fmt-check`. Everything
|
|
||||||
else the grep finds is a real second path and goes.
|
|
||||||
- [ ] Detection is on `LINT_IN_CONTAINER` alone. Reject any `/.dockerenv` or
|
|
||||||
cgroup heuristic: absent in BuildKit `RUN` steps, present on hosts that
|
|
||||||
are themselves containers, and a false positive lints on the host.
|
|
||||||
- [ ] `script/bootstrap` installs no golangci-lint. Delete the block, its
|
|
||||||
version and ref variables, and its call site. A JS repo's `yarn install`
|
|
||||||
stays — it brings a linter along with every other dependency, which is
|
|
||||||
fine as long as no verdict is taken from it.
|
|
||||||
- [ ] The per-checkout lint state is gone: no `GOLANGCI_LINT_CACHE` or `TMPDIR`
|
|
||||||
exports, no `--allow-serial-runners`, and `.lint-cache/` removed from
|
|
||||||
`.gitignore` and `.dockerignore`.
|
|
||||||
- [ ] `make check` does not modify any files in the repo
|
- [ ] `make check` does not modify any files in the repo
|
||||||
- [ ] `make test` has a 30-second timeout
|
- [ ] `make test` has a 30-second timeout
|
||||||
- [ ] `make test` runs real tests, not a no-op (at minimum, import/compile
|
- [ ] `make test` runs real tests, not a no-op (at minimum, import/compile
|
||||||
@@ -154,28 +78,8 @@ with your task.
|
|||||||
`internal/`, `static/`, etc.)
|
`internal/`, `static/`, etc.)
|
||||||
- [ ] Go migrations in `internal/db/migrations/` and embedded in binary
|
- [ ] Go migrations in `internal/db/migrations/` and embedded in binary
|
||||||
|
|
||||||
# HTTP Service Hardening (if targeting 1.0 and the repo is an HTTP/web service)
|
|
||||||
|
|
||||||
- [ ] Security headers set on all responses (HSTS, CSP, X-Frame-Options,
|
|
||||||
X-Content-Type-Options, Referrer-Policy, Permissions-Policy)
|
|
||||||
- [ ] Request body size limits enforced on all endpoints
|
|
||||||
- [ ] Read/write/idle timeouts configured on the HTTP server (slowloris defense)
|
|
||||||
- [ ] Per-handler execution time limits in place
|
|
||||||
- [ ] Password-based auth endpoints are rate-limited
|
|
||||||
- [ ] CSRF tokens on all state-mutating HTML forms
|
|
||||||
- [ ] Passwords hashed with bcrypt, scrypt, or argon2
|
|
||||||
- [ ] Session cookies use HttpOnly, Secure, and SameSite attributes
|
|
||||||
- [ ] True client IP correctly detected behind reverse proxy (trusted proxy
|
|
||||||
allowlist configured)
|
|
||||||
- [ ] CORS restricted to explicit origin allowlist for authenticated endpoints
|
|
||||||
- [ ] Error responses do not leak stack traces, SQL queries, or internal paths
|
|
||||||
|
|
||||||
# Final
|
# Final
|
||||||
|
|
||||||
- [ ] `make check` passes
|
- [ ] `make check` passes
|
||||||
- [ ] `make lint` runs twice on an unchanged tree with the lint layer `DONE`
|
- [ ] `docker build` succeeds
|
||||||
both times, never `CACHED` and never sub-second
|
|
||||||
- [ ] `script/cibuild` succeeds (a bare `docker build .` or
|
|
||||||
`docker build -f Dockerfile.lint .` fails closed by design, on the
|
|
||||||
`CHECK_EPOCH` guard)
|
|
||||||
- [ ] Commit and merge fixes before starting your actual task
|
- [ ] Commit and merge fixes before starting your actual task
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
---
|
---
|
||||||
title: Go HTTP Server Conventions
|
title: Go HTTP Server Conventions
|
||||||
last_modified: 2026-08-09
|
last_modified: 2026-02-22
|
||||||
---
|
---
|
||||||
|
|
||||||
This document defines the architectural patterns, design decisions, and
|
This document defines the architectural patterns, design decisions, and
|
||||||
@@ -991,14 +991,7 @@ func main() {
|
|||||||
Use ldflags to inject version information at build time:
|
Use ldflags to inject version information at build time:
|
||||||
|
|
||||||
```makefile
|
```makefile
|
||||||
# ?= rather than := because this `$(shell git describe ...)` is only correct
|
VERSION := $(shell git describe --tags --always)
|
||||||
# on the host: `.dockerignore` excludes `.git`, so evaluated inside a build
|
|
||||||
# stage it expands to the empty string without failing and the binary reports
|
|
||||||
# no version. The version is computed on the host by `script/docker` /
|
|
||||||
# `script/cibuild` and passed with `--build-arg VERSION=...`; where the build
|
|
||||||
# stage invokes make, `ARG VERSION` puts it in the environment and `?=` defers
|
|
||||||
# to it. See the git-describe rule in REPO_POLICIES.md.
|
|
||||||
VERSION ?= $(shell git describe --tags --always)
|
|
||||||
BUILDARCH := $(shell go env GOARCH)
|
BUILDARCH := $(shell go env GOARCH)
|
||||||
|
|
||||||
build:
|
build:
|
||||||
|
|||||||
@@ -1,6 +1,8 @@
|
|||||||
# LLM Prose Tells
|
# LLM Prose Tells
|
||||||
|
|
||||||
A catalog of patterns found in LLM-generated prose.
|
Every pattern in this document shows up in human writing occasionally. They
|
||||||
|
become diagnostic only through density. A person might use one or two across an
|
||||||
|
entire essay, but LLM output packs fifteen into a single paragraph.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -13,11 +15,19 @@ A negation followed by an em-dash and a reframe.
|
|||||||
> "It's not just a tool—it's a paradigm shift." "This isn't about
|
> "It's not just a tool—it's a paradigm shift." "This isn't about
|
||||||
> technology—it's about trust."
|
> technology—it's about trust."
|
||||||
|
|
||||||
|
The single most recognizable LLM construction. Models produce this at roughly 10
|
||||||
|
to 50x the rate of human writers. Four of them in one essay and you know what
|
||||||
|
you're reading.
|
||||||
|
|
||||||
### Em-Dash Overuse Generally
|
### Em-Dash Overuse Generally
|
||||||
|
|
||||||
Even outside the "not X but Y" pivot, models substitute em-dashes for commas,
|
Even outside the "not X but Y" pivot, models use em-dashes at far higher rates
|
||||||
semicolons, parentheses, colons, and periods. The em-dash can replace any other
|
than human writers. They substitute em-dashes for commas, semicolons,
|
||||||
punctuation mark, so models default to it.
|
parentheses, colons, and periods, often multiple times per paragraph. A human
|
||||||
|
writer might use one or two in an entire piece for a specific parenthetical
|
||||||
|
effect. Models scatter them everywhere because the em-dash can stand in for any
|
||||||
|
other punctuation mark, so they default to it. More than two or three per page
|
||||||
|
is a meaningful signal on its own.
|
||||||
|
|
||||||
### The Colon Elaboration
|
### The Colon Elaboration
|
||||||
|
|
||||||
@@ -25,25 +35,33 @@ A short declarative clause, then a colon, then a longer explanation.
|
|||||||
|
|
||||||
> "The answer is simple: we need to rethink our approach from the ground up."
|
> "The answer is simple: we need to rethink our approach from the ground up."
|
||||||
|
|
||||||
|
Models reach for this in every other paragraph. The construction is perfectly
|
||||||
|
normal. The frequency gives it away.
|
||||||
|
|
||||||
### The Triple Construction
|
### The Triple Construction
|
||||||
|
|
||||||
> "It's fast, it's scalable, and it's open source."
|
> "It's fast, it's scalable, and it's open source."
|
||||||
|
|
||||||
Three parallel items in a list, usually escalating. Always exactly three (rarely
|
Three parallel items in a list, usually escalating. Always exactly three (rarely
|
||||||
two, never four) with strict grammatical parallelism.
|
two, never four) with strict grammatical parallelism that human writers rarely
|
||||||
|
bother maintaining.
|
||||||
|
|
||||||
### The Staccato Burst
|
### The Staccato Burst
|
||||||
|
|
||||||
> "This matters. It always has. And it always will." "The data is clear. The
|
> "This matters. It always has. And it always will." "The data is clear. The
|
||||||
> trend is undeniable. The conclusion is obvious."
|
> trend is undeniable. The conclusion is obvious."
|
||||||
|
|
||||||
Runs of very short sentences at the same cadence and matching length.
|
Runs of very short sentences at the same cadence. Human writers use a short
|
||||||
|
sentence for emphasis occasionally, but stacking three or four of them in a row
|
||||||
|
at matching length creates a mechanical regularity that reads as generated.
|
||||||
|
|
||||||
### The Two-Clause Compound Sentence
|
### The Two-Clause Compound Sentence
|
||||||
|
|
||||||
An independent clause, a comma, a conjunction ("and," "but," "which,"
|
Possibly the most pervasive structural tell, and easy to miss because each
|
||||||
"because"), and a second independent clause of similar length. Every sentence
|
individual instance looks like normal English. The model produces sentence after
|
||||||
becomes two balanced halves.
|
sentence where an independent clause is followed by a comma, a conjunction
|
||||||
|
("and," "but," "which," "because"), and a second independent clause of similar
|
||||||
|
length. Every sentence becomes two balanced halves joined in the middle.
|
||||||
|
|
||||||
> "The construction itself is perfectly normal, which is why the frequency is
|
> "The construction itself is perfectly normal, which is why the frequency is
|
||||||
> what gives it away." "They contain zero information, and the actual point
|
> what gives it away." "They contain zero information, and the actual point
|
||||||
@@ -53,62 +71,76 @@ becomes two balanced halves.
|
|||||||
|
|
||||||
Human prose has sentences with one clause, sentences with three, sentences that
|
Human prose has sentences with one clause, sentences with three, sentences that
|
||||||
start with a subordinate clause before reaching the main one, sentences that
|
start with a subordinate clause before reaching the main one, sentences that
|
||||||
embed their complexity in the middle.
|
embed their complexity in the middle. When every sentence on the page has that
|
||||||
|
same two-part structure, the rhythm becomes monotonous in a way that's hard to
|
||||||
|
pinpoint but easy to feel.
|
||||||
|
|
||||||
### Uniform Sentences Per Paragraph
|
### Uniform Sentences Per Paragraph
|
||||||
|
|
||||||
Model-generated paragraphs contain between three and five sentences, a count
|
Model-generated paragraphs contain between three and five sentences. This count
|
||||||
that holds steady across a piece. If the first paragraph has four sentences,
|
holds steady across an entire piece. If the first paragraph has four sentences,
|
||||||
every subsequent paragraph will too.
|
every subsequent paragraph will too. Human writers are much more varied (a
|
||||||
|
single sentence followed by one that runs eight or nine) because they follow the
|
||||||
|
shape of an idea, not a template.
|
||||||
|
|
||||||
### The Dramatic Fragment
|
### The Dramatic Fragment
|
||||||
|
|
||||||
Sentence fragments used as standalone paragraphs for emphasis.
|
Sentence fragments used as standalone paragraphs for emphasis, like "Full stop."
|
||||||
|
or "Let that sink in." on their own line. Using one in an entire essay is a
|
||||||
> "Full stop." "Let that sink in."
|
reasonable stylistic choice, but models drop them in once per section or more,
|
||||||
|
at which point it becomes a habit rather than a deliberate decision.
|
||||||
|
|
||||||
### The Pivot Paragraph
|
### The Pivot Paragraph
|
||||||
|
|
||||||
> "But here's where it gets interesting." "Which raises an uncomfortable truth."
|
> "But here's where it gets interesting." "Which raises an uncomfortable truth."
|
||||||
|
|
||||||
One-sentence paragraphs that exist only to transition between ideas, containing
|
One-sentence paragraphs that exist only to transition between ideas. They
|
||||||
zero information. The actual point is always in the next paragraph.
|
contain zero information. The actual point is always in the next paragraph.
|
||||||
|
Delete every one of these and the piece reads better.
|
||||||
|
|
||||||
### The Parenthetical Qualifier
|
### The Parenthetical Qualifier
|
||||||
|
|
||||||
> "This is, of course, a simplification." "There are, to be fair, exceptions."
|
> "This is, of course, a simplification." "There are, to be fair, exceptions."
|
||||||
|
|
||||||
Parenthetical asides inserted to perform nuance without changing the argument.
|
Parenthetical asides inserted to look thoughtful. The qualifier never changes
|
||||||
|
the argument that follows it. Its purpose is to perform nuance, not to express a
|
||||||
|
real reservation about what's being said.
|
||||||
|
|
||||||
### The Unnecessary Contrast
|
### The Unnecessary Contrast
|
||||||
|
|
||||||
A contrasting clause appended to a statement that doesn't need one, using
|
Models append a contrasting clause to statements that don't need one, tacking on
|
||||||
"whereas," "as opposed to," "unlike," or "except that."
|
"whereas," "as opposed to," "unlike," or "except that" to draw a comparison the
|
||||||
|
reader could already infer.
|
||||||
|
|
||||||
> "Models write one register above where a human would, whereas human writers
|
> "Models write one register above where a human would, whereas human writers
|
||||||
> tend to match register to context."
|
> tend to match register to context."
|
||||||
|
|
||||||
The contrasting clause restates what the first clause already said. If you
|
The first clause already makes the point. The contrasting clause restates it
|
||||||
delete the "whereas" clause and the sentence still says everything it needs to,
|
from the other direction. If you delete the "whereas" clause and the sentence
|
||||||
the contrast was filler.
|
still says everything it needs to, the contrast was filler.
|
||||||
|
|
||||||
### Unnecessary Elaboration
|
### Unnecessary Elaboration
|
||||||
|
|
||||||
Models keep going after the sentence has already made its point.
|
Models keep going after the sentence has already made its point, tacking on
|
||||||
|
clarifying phrases, adverbial modifiers, or restatements that add nothing.
|
||||||
|
|
||||||
> "A person might lean on one or two of these habits across an entire essay, but
|
> "A person might lean on one or two of these habits across an entire essay, but
|
||||||
> LLM output will use fifteen of them per paragraph, consistently, throughout
|
> LLM output will use fifteen of them per paragraph, consistently, throughout
|
||||||
> the entire piece."
|
> the entire piece."
|
||||||
|
|
||||||
This sentence could end at "paragraph." The words after it repeat what "per
|
This sentence could end at "paragraph." The words after it just repeat what "per
|
||||||
paragraph" already means. If you can cut the last third of a sentence without
|
paragraph" already means. Models do this because they're optimizing for clarity
|
||||||
losing meaning, the last third shouldn't be there.
|
at the expense of concision, and because their training rewards thoroughness.
|
||||||
|
The result is prose that feels padded. If you can cut the last third of a
|
||||||
|
sentence without losing any meaning, the last third shouldn't be there.
|
||||||
|
|
||||||
### The Question-Then-Answer
|
### The Question-Then-Answer
|
||||||
|
|
||||||
> "So what does this mean for the average user? It means everything."
|
> "So what does this mean for the average user? It means everything."
|
||||||
|
|
||||||
A rhetorical question immediately followed by its own answer.
|
A rhetorical question immediately followed by its own answer. Models do this two
|
||||||
|
or three times per piece because it fakes forward momentum. A human writer might
|
||||||
|
do it once.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -116,38 +148,44 @@ A rhetorical question immediately followed by its own answer.
|
|||||||
|
|
||||||
### Overused Intensifiers
|
### Overused Intensifiers
|
||||||
|
|
||||||
"Crucial," "vital," "robust," "comprehensive," "fundamental," "arguably,"
|
The following words appear at dramatically elevated rates in model output:
|
||||||
|
"crucial," "vital," "robust," "comprehensive," "fundamental," "arguably,"
|
||||||
"straightforward," "noteworthy," "realm," "landscape," "leverage" (as a verb),
|
"straightforward," "noteworthy," "realm," "landscape," "leverage" (as a verb),
|
||||||
"delve," "tapestry," "multifaceted," "nuanced" (applied to the model's own
|
"delve," "tapestry," "multifaceted," "nuanced" (which models apply to their own
|
||||||
analysis), "pivotal," "unprecedented" (applied to things with plenty of
|
analysis with startling regularity), "pivotal," "unprecedented" (frequently
|
||||||
precedent), "navigate," "foster," "underscores," "resonates," "embark,"
|
applied to things with plenty of precedent), "navigate," "foster,"
|
||||||
"streamline," "spearhead."
|
"underscores," "resonates," "embark," "streamline," and "spearhead." Three or
|
||||||
|
more on the same page is a strong signal.
|
||||||
|
|
||||||
### Elevated Register Drift
|
### Elevated Register Drift
|
||||||
|
|
||||||
Models write one register above where a human would, replacing "use" with
|
Models write one register above where a human would. "Use" becomes "utilize."
|
||||||
"utilize," "start" with "commence," "help" with "facilitate," "show" with
|
"Start" becomes "commence." "Help" becomes "facilitate." "Show" becomes
|
||||||
"demonstrate," "try" with "endeavor," "change" with "transform," and "make" with
|
"demonstrate." "Try" becomes "endeavor." "Change" becomes "transform." "Make"
|
||||||
"craft."
|
becomes "craft." The tendency holds regardless of topic or audience.
|
||||||
|
|
||||||
### Filler Adverbs
|
### Filler Adverbs
|
||||||
|
|
||||||
"Importantly," "essentially," "fundamentally," "ultimately," "inherently,"
|
"Importantly," "essentially," "fundamentally," "ultimately," "inherently,"
|
||||||
"particularly," "increasingly." Dropped in to signal that something matters when
|
"particularly," "increasingly." Dropped in to signal that something matters,
|
||||||
the writing itself should make the importance clear.
|
which is unnecessary when the writing itself already makes the importance clear.
|
||||||
|
|
||||||
### The "Almost" Hedge
|
### The "Almost" Hedge
|
||||||
|
|
||||||
Instead of saying a pattern "always" or "never" does something, models write
|
Models rarely commit to an unqualified statement. Instead of saying a pattern
|
||||||
"almost always," "almost never," "almost certainly," "almost exclusively." A
|
"always" or "never" does something, they write "almost always," "almost never,"
|
||||||
micro-hedge, less obvious than the full hedge stack.
|
"almost certainly," "almost exclusively." The word "almost" shows up at
|
||||||
|
extraordinary density in model-generated analytical prose. It's a micro-hedge,
|
||||||
|
less obvious than the full hedge stack but just as diagnostic when it appears
|
||||||
|
ten or fifteen times in a single document.
|
||||||
|
|
||||||
### "In an era of..."
|
### "In an era of..."
|
||||||
|
|
||||||
> "In an era of rapid technological change..."
|
> "In an era of rapid technological change..."
|
||||||
|
|
||||||
Used to open an essay. The model is stalling while it figures out what the
|
A model habit as an essay opener. The model uses it to stall while it figures
|
||||||
actual argument is.
|
out what the actual argument is. Human writers don't begin a piece by zooming
|
||||||
|
out to the civilizational scale before they've said anything specific.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -158,20 +196,24 @@ actual argument is.
|
|||||||
> "While X has its drawbacks, it also offers significant benefits."
|
> "While X has its drawbacks, it also offers significant benefits."
|
||||||
|
|
||||||
Every argument followed by a concession, every criticism softened. A direct
|
Every argument followed by a concession, every criticism softened. A direct
|
||||||
artifact of RLHF training, which penalizes strong stances.
|
artifact of RLHF training, which penalizes strong stances. Models reflexively
|
||||||
|
both-sides everything even when a clear position would serve the reader better.
|
||||||
|
|
||||||
### The Throat-Clearing Opener
|
### The Throat-Clearing Opener
|
||||||
|
|
||||||
> "In today's rapidly evolving digital landscape, the question of data privacy
|
> "In today's rapidly evolving digital landscape, the question of data privacy
|
||||||
> has never been more important."
|
> has never been more important."
|
||||||
|
|
||||||
The first paragraph adds no information. Delete it and the piece improves.
|
The first paragraph of most model-generated essays adds no information. Delete
|
||||||
|
it and the piece improves immediately. The actual argument starts in paragraph
|
||||||
|
two.
|
||||||
|
|
||||||
### The False Conclusion
|
### The False Conclusion
|
||||||
|
|
||||||
> "At the end of the day, what matters most is..." "Moving forward, we must..."
|
> "At the end of the day, what matters most is..." "Moving forward, we must..."
|
||||||
|
|
||||||
The high school "In conclusion,..." dressed up for a professional audience.
|
The high school "In conclusion,..." dressed up for a professional audience.
|
||||||
|
Signals that the model is wrapping up without actually landing on anything.
|
||||||
|
|
||||||
### The Sycophantic Frame
|
### The Sycophantic Frame
|
||||||
|
|
||||||
@@ -192,13 +234,15 @@ the key considerations:"
|
|||||||
> cases it can potentially offer significant benefits."
|
> cases it can potentially offer significant benefits."
|
||||||
|
|
||||||
Five hedges in one sentence ("worth noting," "while," "may not be," "in many
|
Five hedges in one sentence ("worth noting," "while," "may not be," "in many
|
||||||
cases," "can potentially"), communicating nothing.
|
cases," "can potentially"), communicating nothing. The model would rather be
|
||||||
|
vague than risk being wrong about anything.
|
||||||
|
|
||||||
### The Empathy Performance
|
### The Empathy Performance
|
||||||
|
|
||||||
> "This can be a deeply challenging experience." "Your feelings are valid."
|
> "This can be a deeply challenging experience." "Your feelings are valid."
|
||||||
|
|
||||||
Generic emotional language that could apply to anything.
|
Generic emotional language that could apply equally to a bad day at work or a
|
||||||
|
natural disaster. That interchangeability is what makes it identifiable.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -206,28 +250,35 @@ Generic emotional language that could apply to anything.
|
|||||||
|
|
||||||
### Symmetrical Section Length
|
### Symmetrical Section Length
|
||||||
|
|
||||||
If the first section runs about 150 words, every subsequent section will fall
|
If the first section of a model-generated essay runs about 150 words, every
|
||||||
between 130 and 170.
|
subsequent section will fall between 130 and 170. Human writing is much more
|
||||||
|
uneven, with 50 words in one section and 400 in the next.
|
||||||
|
|
||||||
### The Five-Paragraph Prison
|
### The Five-Paragraph Prison
|
||||||
|
|
||||||
Model essays follow a rigid introduction-body-conclusion arc even when nobody
|
Model essays follow a rigid introduction-body-conclusion arc even when nobody
|
||||||
asked for one. The introduction previews the argument, the body presents 3 to 5
|
asked for one. The introduction previews the argument, the body presents 3 to 5
|
||||||
points, the conclusion restates the thesis.
|
points, and then the conclusion restates the thesis using slightly different
|
||||||
|
words.
|
||||||
|
|
||||||
### Connector Addiction
|
### Connector Addiction
|
||||||
|
|
||||||
The first word of each paragraph forms an unbroken chain of transition words:
|
Look at the first word of each paragraph in model output. You'll find an
|
||||||
"However," "Furthermore," "Moreover," "Additionally," "That said," "To that
|
unbroken chain of transition words: "However," "Furthermore," "Moreover,"
|
||||||
end," "With that in mind," "Building on this."
|
"Additionally," "That said," "To that end," "With that in mind," "Building on
|
||||||
|
this." Human prose moves between ideas without announcing every transition.
|
||||||
|
|
||||||
### Absence of Mess
|
### Absence of Mess
|
||||||
|
|
||||||
Model prose doesn't contradict itself mid-paragraph and then catch the
|
Model prose doesn't contradict itself mid-paragraph and then catch the
|
||||||
contradiction, go on a tangent and have to walk it back, use an obscure idiom
|
contradiction. It doesn't go on a tangent and have to walk it back, use an
|
||||||
without explaining it, make a joke that risks falling flat, leave a thought
|
obscure idiom without explaining it, make a joke that risks falling flat, leave
|
||||||
genuinely unfinished, or keep a sentence the writer liked the sound of even
|
a thought genuinely unfinished, or keep a sentence the writer liked the sound of
|
||||||
though it doesn't quite work.
|
even though it doesn't quite work.
|
||||||
|
|
||||||
|
Human writing does all of those things regularly. That total absence of rough
|
||||||
|
patches and false starts is one of the strongest signals that text was
|
||||||
|
machine-generated.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -237,27 +288,45 @@ though it doesn't quite work.
|
|||||||
|
|
||||||
> "This has implications far beyond just the tech industry."
|
> "This has implications far beyond just the tech industry."
|
||||||
|
|
||||||
Zooming out to claim broader significance without substantiating it.
|
Zooming out to claim broader significance without substantiating it. The model
|
||||||
|
has learned that essays are supposed to gesture at big ideas, so it gestures.
|
||||||
|
Nothing concrete is behind the gesture.
|
||||||
|
|
||||||
### "It's important to note that..."
|
### "It's important to note that..."
|
||||||
|
|
||||||
This phrase and its variants ("it's worth noting," "it bears mentioning," "it
|
This phrase and its variants ("it's worth noting," "it bears mentioning," "it
|
||||||
should be noted") function as verbal tics before a qualification the model
|
should be noted") appear at absurd rates in model output. They function as
|
||||||
believes someone expects.
|
verbal tics before a qualification the model believes someone expects.
|
||||||
|
|
||||||
### The Metaphor Crutch
|
### The Metaphor Crutch
|
||||||
|
|
||||||
Models rely on a small, predictable set of metaphors: "double-edged sword," "tip
|
Models rely on a small, predictable set of metaphors ("double-edged sword," "tip
|
||||||
of the iceberg," "north star," "building blocks," "elephant in the room,"
|
of the iceberg," "north star," "building blocks," "elephant in the room,"
|
||||||
"perfect storm," "game-changer."
|
"perfect storm," "game-changer") and reach for them with unusual regularity
|
||||||
|
across every topic. The pool is noticeably smaller than what human writers draw
|
||||||
|
from.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## How to Actually Spot It
|
||||||
|
|
||||||
|
No single pattern on this list proves anything by itself. Humans use em-dashes.
|
||||||
|
Humans write "crucial." Humans ask rhetorical questions.
|
||||||
|
|
||||||
|
What gives it away is how many of these show up at once. Model output will hit
|
||||||
|
10 to 20 of these patterns per page. Human writing might trigger 2 or 3,
|
||||||
|
distributed unevenly, mixed with idiosyncratic constructions no model would
|
||||||
|
produce. When every paragraph on the page reads like it came from the same
|
||||||
|
careful, balanced, slightly formal, structurally predictable process, it was
|
||||||
|
generated by one.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Copyediting Checklist: Removing LLM Tells
|
## Copyediting Checklist: Removing LLM Tells
|
||||||
|
|
||||||
Follow this checklist when editing any document to remove machine-generated
|
Follow this checklist when editing any document to remove machine-generated
|
||||||
patterns. Do at least two full passes, because fixing one pattern often
|
patterns. Go through the entire list for every piece. Do at least two full
|
||||||
introduces another.
|
passes, because fixing one pattern often introduces another.
|
||||||
|
|
||||||
### Pass 1: Word-Level Cleanup
|
### Pass 1: Word-Level Cleanup
|
||||||
|
|
||||||
@@ -271,7 +340,8 @@ introduces another.
|
|||||||
|
|
||||||
2. Search for filler adverbs ("importantly," "essentially," "fundamentally,"
|
2. Search for filler adverbs ("importantly," "essentially," "fundamentally,"
|
||||||
"ultimately," "inherently," "particularly," "increasingly") and delete every
|
"ultimately," "inherently," "particularly," "increasingly") and delete every
|
||||||
instance where the sentence still makes sense without it.
|
instance where the sentence still makes sense without it. That will be most
|
||||||
|
of them.
|
||||||
|
|
||||||
3. Look for elevated register drift ("utilize," "commence," "facilitate,"
|
3. Look for elevated register drift ("utilize," "commence," "facilitate,"
|
||||||
"demonstrate," "endeavor," "transform," "craft" and similar) and replace with
|
"demonstrate," "endeavor," "transform," "craft" and similar) and replace with
|
||||||
@@ -279,6 +349,7 @@ introduces another.
|
|||||||
|
|
||||||
4. Search for "it's important to note," "it's worth noting," "it bears
|
4. Search for "it's important to note," "it's worth noting," "it bears
|
||||||
mentioning," and "it should be noted" and delete the phrase in every case.
|
mentioning," and "it should be noted" and delete the phrase in every case.
|
||||||
|
The sentence that follows always stands on its own.
|
||||||
|
|
||||||
5. Search for the stock metaphors ("double-edged sword," "tip of the iceberg,"
|
5. Search for the stock metaphors ("double-edged sword," "tip of the iceberg,"
|
||||||
"north star," "building blocks," "elephant in the room," "perfect storm,"
|
"north star," "building blocks," "elephant in the room," "perfect storm,"
|
||||||
@@ -287,114 +358,101 @@ introduces another.
|
|||||||
|
|
||||||
6. Search for "almost" used as a hedge ("almost always," "almost never," "almost
|
6. Search for "almost" used as a hedge ("almost always," "almost never," "almost
|
||||||
certainly," "almost exclusively") and decide in each case whether to commit
|
certainly," "almost exclusively") and decide in each case whether to commit
|
||||||
to the unqualified claim or to drop the sentence entirely.
|
to the unqualified claim or to drop the sentence entirely. If the claim needs
|
||||||
|
"almost" to be true, it might not be worth making.
|
||||||
|
|
||||||
7. Search for em-dashes and replace each one with the punctuation mark that
|
7. Search for em-dashes and replace each one with the punctuation mark that
|
||||||
would normally be used in that position (comma, semicolon, colon, period, or
|
would normally be used in that position (comma, semicolon, colon, period, or
|
||||||
parentheses). If you can't identify which one it should be, the sentence
|
parentheses). If you can't identify which one it should be, the sentence
|
||||||
needs to be restructured.
|
needs to be restructured.
|
||||||
|
|
||||||
8. Remove redundant adjectives. For each adjective, ask whether the sentence
|
|
||||||
changes meaning without it. "A single paragraph" means the same as "a
|
|
||||||
paragraph." "An entire essay" means the same as "an essay." If the adjective
|
|
||||||
doesn't change the meaning, cut it.
|
|
||||||
|
|
||||||
9. Remove unnecessary trailing clauses. Read the end of each sentence and ask
|
|
||||||
whether the last clause restates what the sentence already said. If so, end
|
|
||||||
the sentence earlier.
|
|
||||||
|
|
||||||
### Pass 2: Sentence-Level Restructuring
|
### Pass 2: Sentence-Level Restructuring
|
||||||
|
|
||||||
10. Find every em-dash pivot ("not X—but Y," "not just X—Y," "more than X—Y")
|
8. Find every em-dash pivot ("not X...but Y," "not just X...Y," "more than
|
||||||
and rewrite it as two separate clauses or a single sentence that makes the
|
X...Y") and rewrite it as two separate clauses or a single sentence that
|
||||||
point without the negation-then-correction structure.
|
makes the point without the negation-then-correction structure.
|
||||||
|
|
||||||
11. Find every colon elaboration and check whether it's doing real work. If the
|
9. Find every colon elaboration and check whether it's doing real work. If the
|
||||||
clause before the colon could be deleted without losing meaning, rewrite the
|
clause before the colon could be deleted without losing meaning, rewrite the
|
||||||
sentence to start with the substance that comes after the colon.
|
sentence to start with the substance that comes after the colon.
|
||||||
|
|
||||||
12. Find every triple construction (three parallel items in a row) and either
|
10. Find every triple construction (three parallel items in a row) and either
|
||||||
reduce it to two, expand it to four or more, or break the parallelism so the
|
reduce it to two, expand it to four or more, or break the parallelism so the
|
||||||
items don't share the same grammatical structure.
|
items don't share the same grammatical structure.
|
||||||
|
|
||||||
13. Find every staccato burst (three or more short sentences in a row at similar
|
11. Find every staccato burst (three or more short sentences in a row at similar
|
||||||
length) and combine at least two of them into a longer sentence, or vary
|
length) and combine at least two of them into a longer sentence, or vary
|
||||||
their lengths so they don't land at the same cadence.
|
their lengths so they don't land at the same cadence.
|
||||||
|
|
||||||
14. Find every unnecessary contrast ("whereas," "as opposed to," "unlike," "as
|
12. Find every unnecessary contrast ("whereas," "as opposed to," "unlike," "as
|
||||||
compared to," "except that") and check whether the contrasting clause adds
|
compared to," "except that") and check whether the contrasting clause adds
|
||||||
information not already obvious from the main clause. If the sentence says
|
information not already obvious from the main clause. If the sentence says
|
||||||
the same thing twice from two directions, delete the contrast.
|
the same thing twice from two directions, delete the contrast.
|
||||||
|
|
||||||
15. Check for the two-clause compound sentence pattern. If most sentences in a
|
13. Check for the two-clause compound sentence pattern. If most sentences in a
|
||||||
passage follow the "\[clause\], \[conjunction\] \[clause\]" structure, first
|
passage follow the "\[clause\], \[conjunction\] \[clause\]" structure,
|
||||||
try removing the conjunction and second clause entirely, since it's often
|
rewrite some of them. Break a few into two sentences. Start some with a
|
||||||
redundant. If the second clause does carry meaning, break it into its own
|
subordinate clause. Embed a relative clause in the middle of one instead of
|
||||||
sentence, start the sentence with a subordinate clause, or embed a relative
|
appending it at the end. The goal is variety in sentence shape, not just
|
||||||
clause in the middle instead of appending it at the end.
|
sentence length.
|
||||||
|
|
||||||
16. Find every rhetorical question that is immediately followed by its own
|
14. Find every rhetorical question that is immediately followed by its own
|
||||||
answer and rewrite the passage as a direct statement.
|
answer and rewrite the passage as a direct statement.
|
||||||
|
|
||||||
17. Find every sentence fragment being used as its own paragraph and either
|
15. Find every sentence fragment being used as its own paragraph and either
|
||||||
delete it or expand it into a complete sentence that adds information.
|
delete it or expand it into a complete sentence that adds actual
|
||||||
|
information.
|
||||||
|
|
||||||
18. Check for unnecessary elaboration. Read every clause, phrase, and adjective
|
16. Check for unnecessary elaboration at the end of sentences. Read the last
|
||||||
in each sentence and ask whether the sentence loses meaning without it. If
|
clause or phrase of each sentence and ask whether the sentence would lose
|
||||||
you can cut it and the sentence still says the same thing, cut it.
|
any meaning without it. If not, cut it.
|
||||||
|
|
||||||
19. Check each pair of adjacent sentences to see if they can be merged into one
|
17. Find every pivot paragraph ("But here's where it gets interesting." and
|
||||||
sentence cleanly. If a sentence just continues the thought of the previous
|
similar) and delete it. The paragraph after it always contains the actual
|
||||||
one, combine them using a participle, a relative clause, or by folding the
|
point.
|
||||||
second into the first. Don't merge if the result would create a two-clause
|
|
||||||
compound.
|
|
||||||
|
|
||||||
20. Find every pivot paragraph ("But here's where it gets interesting." and
|
|
||||||
similar) and delete it.
|
|
||||||
|
|
||||||
### Pass 3: Paragraph and Section-Level Review
|
### Pass 3: Paragraph and Section-Level Review
|
||||||
|
|
||||||
21. Review the last sentence of each paragraph. If it restates the point the
|
18. Check paragraph lengths across the piece and verify they actually vary. If
|
||||||
paragraph already made, delete it.
|
|
||||||
|
|
||||||
22. Check paragraph lengths across the piece and verify they actually vary. If
|
|
||||||
most paragraphs have between three and five sentences, rewrite some to be
|
most paragraphs have between three and five sentences, rewrite some to be
|
||||||
one or two sentences and let others run to six or seven.
|
one or two sentences and let others run to six or seven.
|
||||||
|
|
||||||
23. Check section lengths for suspicious uniformity. If every section is roughly
|
19. Check section lengths for suspicious uniformity. If every section is roughly
|
||||||
the same word count, combine some shorter ones or split a longer one
|
the same word count, combine some shorter ones or split a longer one
|
||||||
unevenly.
|
unevenly.
|
||||||
|
|
||||||
24. Check the first word of every paragraph for chains of connectors ("However,"
|
20. Check the first word of every paragraph for chains of connectors ("However,"
|
||||||
"Furthermore," "Moreover," "Additionally," "That said"). If more than two
|
"Furthermore," "Moreover," "Additionally," "That said"). If more than two
|
||||||
transition words start consecutive paragraphs, rewrite those openings to
|
transition words start consecutive paragraphs, rewrite those openings to
|
||||||
start with their subject.
|
start with their subject.
|
||||||
|
|
||||||
25. Check whether every argument is followed by a concession or qualifier. If
|
21. Check whether every argument is followed by a concession or qualifier. If
|
||||||
the piece both-sides every point, pick a side on at least some of them and
|
the piece both-sides every point, pick a side on at least some of them and
|
||||||
cut the hedging.
|
cut the hedging.
|
||||||
|
|
||||||
26. Read the first paragraph and ask whether deleting it would improve the
|
22. Read the first paragraph and ask whether deleting it would improve the
|
||||||
piece. If it's scene-setting that previews the argument, delete it and start
|
piece. If it's scene-setting that previews the argument, delete it and start
|
||||||
with paragraph two.
|
with paragraph two.
|
||||||
|
|
||||||
27. Read the last paragraph and check whether it restates the thesis or uses a
|
23. Read the last paragraph and check whether it restates the thesis or uses a
|
||||||
phrase like "at the end of the day" or "moving forward." If so, either
|
phrase like "at the end of the day" or "moving forward." If so, either
|
||||||
delete it or rewrite it to say something the piece hasn't said yet.
|
delete it or rewrite it to say something the piece hasn't said yet.
|
||||||
|
|
||||||
### Pass 4: Overall Texture
|
### Pass 4: Overall Texture
|
||||||
|
|
||||||
28. Read the piece aloud and listen for passages that sound too smooth, too
|
24. Read the piece aloud and listen for passages that sound too smooth, too
|
||||||
even, or too predictable. Human prose has rough patches. If there aren't
|
even, or too predictable. Human prose has rough patches. If there aren't
|
||||||
any, the piece still reads as machine output.
|
any, the piece still reads as machine output.
|
||||||
|
|
||||||
29. Check that the piece contains at least a few constructions that feel
|
25. Check that the piece contains at least a few constructions that feel
|
||||||
idiosyncratic: a sentence with unusual word order, a parenthetical that goes
|
idiosyncratic: a sentence with unusual word order, a parenthetical that goes
|
||||||
on a bit long, an aside only loosely connected to the main point, a word
|
on a bit long, an aside only loosely connected to the main point, a word
|
||||||
choice that's specific and unexpected.
|
choice that's specific and unexpected. If every sentence is clean and
|
||||||
|
correct and unremarkable, it will still read as generated.
|
||||||
|
|
||||||
30. Verify that you haven't introduced new patterns while fixing the original
|
26. Verify that you haven't introduced new patterns while fixing the original
|
||||||
ones. Run the entire checklist again from the top on the revised version.
|
ones. This happens constantly. Run the entire checklist again from the top
|
||||||
|
on the revised version.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -441,9 +499,16 @@ roughly like this:
|
|||||||
>
|
>
|
||||||
> **model:** _(rewrites entire document without em-dashes while describing
|
> **model:** _(rewrites entire document without em-dashes while describing
|
||||||
> em-dash overuse)_
|
> em-dash overuse)_
|
||||||
|
>
|
||||||
|
> **human:** now run the checklist methodically on each paragraph
|
||||||
|
>
|
||||||
|
> **model:** _(finds staccato burst in the section about triple constructions, a
|
||||||
|
> triple in the section about absence of mess, two-clause compounds everywhere,
|
||||||
|
> and "almost" hedges in its own prose about em-dash overuse)_
|
||||||
|
|
||||||
The human compared this process to the deleted scene in Terminator 2 where John
|
The human compared this process to the deleted scene in Terminator 2 where John
|
||||||
Connor switches the T-800's CPU to learning mode. The model compared it to a
|
Connor switches the T-800's CPU to learning mode. The model compared it to a
|
||||||
physician trying to heal itself. Both are accurate.
|
physician trying to heal itself. Both are accurate.
|
||||||
|
|
||||||
This document has been through ten editing passes and it still has tells in it.
|
This document has been through eight editing passes and it still has tells in
|
||||||
|
it.
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
---
|
---
|
||||||
title: New Repo Checklist
|
title: New Repo Checklist
|
||||||
last_modified: 2026-08-10
|
last_modified: 2026-02-22
|
||||||
---
|
---
|
||||||
|
|
||||||
Use this checklist when creating a new repository from scratch. Follow the steps
|
Use this checklist when creating a new repository from scratch. Follow the steps
|
||||||
@@ -35,11 +35,7 @@ Template files can be fetched from:
|
|||||||
|
|
||||||
- [ ] `.gitignore` — fetch from
|
- [ ] `.gitignore` — fetch from
|
||||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore`, extend for
|
`https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore`, extend for
|
||||||
language-specific artifacts. Extensions are written to `.gitignore`'s own
|
language-specific artifacts
|
||||||
semantics, where an unanchored pattern already matches at every depth:
|
|
||||||
never add a `**/` prefix here, which is a `.dockerignore` form. The
|
|
||||||
canonical file already carries `.claude/` so agent worktrees cannot be
|
|
||||||
committed by accident.
|
|
||||||
- [ ] `.editorconfig` — fetch from
|
- [ ] `.editorconfig` — fetch from
|
||||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/.editorconfig`
|
`https://git.eeqj.de/sneak/prompts/raw/branch/main/.editorconfig`
|
||||||
- [ ] `Makefile` — fetch from
|
- [ ] `Makefile` — fetch from
|
||||||
@@ -56,46 +52,12 @@ Template files can be fetched from:
|
|||||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md`
|
`https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md`
|
||||||
- [ ] `Dockerfile` and `.dockerignore` — fetch `.dockerignore` from
|
- [ ] `Dockerfile` and `.dockerignore` — fetch `.dockerignore` from
|
||||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore`
|
`https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore`
|
||||||
- Extend `.dockerignore` with the repo's own host-built artifacts, giving
|
- All Dockerfiles must run `make check` as a build step
|
||||||
every depth-independent pattern a `**/` prefix — but write a repo-root
|
|
||||||
binary anchored, `/myapp` and never `**/myapp`, which would also match
|
|
||||||
`cmd/myapp/` and delete the package directory. Do not transplant
|
|
||||||
`.gitignore`'s patterns: `.dockerignore` anchors an unprefixed pattern at
|
|
||||||
the context root, so the copied form leaves `config/.env` in the build
|
|
||||||
context while reading as solved. See the `.dockerignore` rule in
|
|
||||||
`REPO_POLICIES.md`. The canonical file's `.claude` entry is anchored for
|
|
||||||
the same reason as a repo-root binary; leave it that way, but note it only
|
|
||||||
covers agents running at the repo root — if this repo will run them in
|
|
||||||
subdirectories, `services/api/.claude/` is not excluded and needs its own
|
|
||||||
anchored entry.
|
|
||||||
- If the image embeds a version in a binary, the version is computed on the
|
|
||||||
host and passed with `--build-arg VERSION=...`. `ARG VERSION=dev` is
|
|
||||||
declared in the stage that compiles, and **no stage calls `git describe`**
|
|
||||||
— `.dockerignore` excludes `.git`, so it yields an empty version without
|
|
||||||
failing the build.
|
|
||||||
- All Dockerfiles must run `make check` as a build step, and every stage
|
|
||||||
containing a check-running `RUN` must declare `ARG CHECK_EPOCH` with the
|
|
||||||
`RUN [ -n "$CHECK_EPOCH" ] || exit 1` guard immediately below it — see the
|
|
||||||
`CHECK_EPOCH` rule in `REPO_POLICIES.md`. Without them the check layer is
|
|
||||||
served from cache on an unchanged tree and the build reports a green it
|
|
||||||
never ran.
|
|
||||||
- Every stage that runs checks sets `ENV LINT_IN_CONTAINER=1`, so
|
|
||||||
`script/lint` runs the linter natively instead of trying to build
|
|
||||||
`Dockerfile.lint` where there is no daemon.
|
|
||||||
- Go repos: separate `lint` stage on the `golangci/golangci-lint` image,
|
|
||||||
with `COPY --from=lint /src/go.sum /dev/null` in the build stage to force
|
|
||||||
the ordering. Re-prove that ordering warm after adopting `CHECK_EPOCH`.
|
|
||||||
- Server: also builds and runs the application
|
- Server: also builds and runs the application
|
||||||
- Non-server: brings up dev environment and runs `make check`
|
- Non-server: brings up dev environment and runs `make check`
|
||||||
- Image pinned by sha256 hash with version/date comment
|
- Image pinned by sha256 hash with version/date comment
|
||||||
- [ ] `Dockerfile.lint` — the lint-only image `script/lint` builds when it is
|
|
||||||
not already inside a container. Sets `ENV LINT_IN_CONTAINER=1`; same
|
|
||||||
`ARG CHECK_EPOCH` + guard + expanded-value discipline as above, with the
|
|
||||||
`ARG` **after** the dependency layer so only the lint re-runs. Base image
|
|
||||||
pinned by sha256 with a version/date comment. Copy from
|
|
||||||
`REPO_POLICIES.md`.
|
|
||||||
- [ ] Gitea Actions workflow at `.gitea/workflows/check.yml` that runs
|
- [ ] Gitea Actions workflow at `.gitea/workflows/check.yml` that runs
|
||||||
`script/cibuild` on push — reference
|
`docker build .` on push — reference
|
||||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitea/workflows/check.yml`
|
`https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitea/workflows/check.yml`
|
||||||
- [ ] Language-specific:
|
- [ ] Language-specific:
|
||||||
- [ ] Go: `go mod init sneak.berlin/go/<name>`, `.golangci.yml` (fetch from
|
- [ ] Go: `go mod init sneak.berlin/go/<name>`, `.golangci.yml` (fetch from
|
||||||
@@ -103,81 +65,20 @@ Template files can be fetched from:
|
|||||||
- [ ] JS: `yarn init`, `yarn add --dev prettier`
|
- [ ] JS: `yarn init`, `yarn add --dev prettier`
|
||||||
- [ ] Python: `pyproject.toml`
|
- [ ] Python: `pyproject.toml`
|
||||||
|
|
||||||
## Configure script/ Entrypoints and Makefile
|
## Configure Makefile
|
||||||
|
|
||||||
Implementations live in `script/` (scripts-to-rule-them-all); Makefile targets
|
- [ ] `make test` — runs real tests, not a no-op (30-second timeout)
|
||||||
are thin shims calling them. Model scripts:
|
- [ ] `make lint` — runs linter
|
||||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/script/<name>`
|
- [ ] `make fmt` — formats code (writes)
|
||||||
|
- [ ] `make fmt-check` — checks formatting (read-only)
|
||||||
- [ ] scripts are POSIX sh (`#!/bin/sh`, `set -eu`, no bashisms) so they run on
|
- [ ] `make check` — prereqs: `test`, `lint`, `fmt-check`; must not modify files
|
||||||
alpine images without bash
|
- [ ] `make docker` — builds Docker image
|
||||||
- [ ] `script/bootstrap` / `make bootstrap` — installs all dependencies,
|
- [ ] `make hooks` — installs pre-commit hook
|
||||||
idempotently, assuming nothing (pkg manager detection nix/apt/brew/apk;
|
|
||||||
node used if present, else pinned version via nvm from a hash-verified
|
|
||||||
archive; pinned yarn via corepack); Dockerfile runs it instead of inline
|
|
||||||
installs
|
|
||||||
- [ ] `script/setup` / `make setup` — readies a fresh clone: runs `bootstrap`,
|
|
||||||
then `install-precommit`, plus repo-specific init
|
|
||||||
- [ ] `script/test` / `make test` — runs real tests, not a no-op (30-second
|
|
||||||
timeout)
|
|
||||||
- [ ] `script/lint` / `make lint` — runs the linter directly when
|
|
||||||
`LINT_IN_CONTAINER=1`, otherwise `epoch="$(date +%s%N)$$"` on its own line
|
|
||||||
then `docker build --build-arg CHECK_EPOCH="$epoch" -f Dockerfile.lint .`.
|
|
||||||
No lint verdict may come from a host invocation. Copy from
|
|
||||||
`REPO_POLICIES.md`. Detect on `LINT_IN_CONTAINER` only — never
|
|
||||||
`/.dockerenv`, which is absent in BuildKit `RUN` steps and present on
|
|
||||||
hosts that are themselves containers. Without the nonce this exits 0 on an
|
|
||||||
unchanged tree having linted nothing; without `-f Dockerfile.lint` it
|
|
||||||
builds the main image and lints nothing at all.
|
|
||||||
- [ ] `script/fmt` / `make fmt` — formats code (writes)
|
|
||||||
- [ ] `script/fmt-check` / `make fmt-check` — checks formatting (read-only)
|
|
||||||
- [ ] `script/check` / `make check` — runs `test`, `lint`, `fmt-check`; must not
|
|
||||||
modify files
|
|
||||||
- [ ] `script/projectname` — outputs the project name (used by `script/docker`
|
|
||||||
for the image tag)
|
|
||||||
- [ ] `script/docker` / `make docker` — builds Docker image, tagged via
|
|
||||||
`script/projectname` (byte-identical across repos); carries the same three
|
|
||||||
version lines as `script/cibuild` below, and passes
|
|
||||||
`--build-arg CHECK_EPOCH="$epoch"` and `--build-arg VERSION="$version"`
|
|
||||||
- [ ] `script/cibuild` — cd to repo root, then, each on its own line:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
epoch="$(date +%s%N)$$"
|
|
||||||
version="$(git describe --tags --always --dirty 2>/dev/null || true)"
|
|
||||||
[ -n "$version" ] || version="unknown"
|
|
||||||
docker build \
|
|
||||||
--build-arg CHECK_EPOCH="$epoch" \
|
|
||||||
--build-arg VERSION="$version" \
|
|
||||||
.
|
|
||||||
```
|
|
||||||
|
|
||||||
(what CI runs). Both build args are mandatory, and both assignments must be
|
|
||||||
on their own line: a failing command substitution inside an argument does
|
|
||||||
not trip `set -e`, so the inline form degrades silently to an empty
|
|
||||||
constant. The `[ -n "$version" ]` line is a live check that fires on an
|
|
||||||
export with no `.git` and on a repo with no commits — keep it, and do not
|
|
||||||
collapse it into `|| echo unknown`, which makes it unreachable. See the
|
|
||||||
`CHECK_EPOCH` and git-describe rules in `REPO_POLICIES.md` for why each
|
|
||||||
element is load-bearing. A bare `docker build .` fails closed by design, and
|
|
||||||
so does a bare `docker build -f Dockerfile.lint .`. The image runs
|
|
||||||
`make check`, which includes lint, so `script/cibuild` needs no separate
|
|
||||||
lint step.
|
|
||||||
|
|
||||||
- [ ] `script/precommit` — called by the pre-commit hook; runs `script/check`
|
|
||||||
- [ ] `script/install-precommit` — installs the pre-commit hook that runs
|
|
||||||
`script/precommit`
|
|
||||||
- [ ] `make hooks` — shims to `script/install-precommit`
|
|
||||||
- [ ] README **Entrypoints** section documents the scripts and links the
|
|
||||||
standard
|
|
||||||
|
|
||||||
# 4. Verify
|
# 4. Verify
|
||||||
|
|
||||||
- [ ] `make check` passes
|
- [ ] `make check` passes
|
||||||
- [ ] `make lint` demonstrably runs the linter rather than returning a cached
|
|
||||||
build: run it twice on an unchanged tree and confirm the lint layer says
|
|
||||||
`DONE`, never `CACHED`, both times
|
|
||||||
- [ ] `make docker` succeeds
|
- [ ] `make docker` succeeds
|
||||||
- [ ] `script/cibuild` succeeds and demonstrably executes
|
|
||||||
- [ ] No secrets in repo
|
- [ ] No secrets in repo
|
||||||
- [ ] No mutable image/package references
|
- [ ] No mutable image/package references
|
||||||
- [ ] No unnecessary files in repo root
|
- [ ] No unnecessary files in repo root
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
---
|
---
|
||||||
title: Repository Policies
|
title: Repository Policies
|
||||||
last_modified: 2026-08-10
|
last_modified: 2026-02-22
|
||||||
---
|
---
|
||||||
|
|
||||||
This document covers repository structure, tooling, and workflow standards. Code
|
This document covers repository structure, tooling, and workflow standards. Code
|
||||||
@@ -34,50 +34,10 @@ style conventions are in separate documents:
|
|||||||
every file before committing. There are zero exceptions to this rule.
|
every file before committing. There are zero exceptions to this rule.
|
||||||
|
|
||||||
- Every repo with software must have a root `Makefile` with these targets:
|
- Every repo with software must have a root `Makefile` with these targets:
|
||||||
`make bootstrap`, `make setup`, `make test`, `make lint`, `make fmt` (writes),
|
`make test`, `make lint`, `make fmt` (writes), `make fmt-check` (read-only),
|
||||||
`make fmt-check` (read-only), `make check` (runs `test`, `lint`, `fmt-check`),
|
`make check` (prereqs: `test`, `lint`, `fmt-check`), `make docker`, and
|
||||||
`make docker`, and `make hooks` (installs pre-commit hook). A model Makefile
|
`make hooks` (installs pre-commit hook). A model Makefile is at
|
||||||
is at `https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`.
|
`https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`.
|
||||||
|
|
||||||
- Repos follow the
|
|
||||||
[Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
|
|
||||||
pattern: the implementation of each Makefile target lives in an executable
|
|
||||||
script in `script/` (`script/bootstrap`, `script/setup`, `script/test`,
|
|
||||||
`script/lint`, `script/fmt`, `script/fmt-check`, `script/check`,
|
|
||||||
`script/docker`), and the Makefile targets are thin shims that call them. The
|
|
||||||
scripts must be POSIX sh (`#!/bin/sh`, `set -eu`, no bashisms) so they run in
|
|
||||||
minimal containers (e.g. alpine images have no bash); locate the repo root
|
|
||||||
with `$(cd "$(dirname "$0")/.." && pwd -P)` and `cd` there before acting. From
|
|
||||||
the standard's canonical set we use `bootstrap`, `setup` (make the repo ready
|
|
||||||
for development after a fresh clone: runs `bootstrap`, then
|
|
||||||
`install-precommit`, plus any repo-specific initialization), `test`, and
|
|
||||||
`cibuild`. `script/bootstrap` installs all dependencies idempotently and
|
|
||||||
assumes nothing is present: base tools come from nix, apt, brew, or apk
|
|
||||||
(detected in that order; apt runs noninteractive). For node it uses the
|
|
||||||
installed node if present; otherwise it installs a PINNED node version via
|
|
||||||
nvm, first installing nvm itself if missing — from a hash-verified GitHub
|
|
||||||
release archive (never `curl | sh`), with bash installed as an explicit
|
|
||||||
prerequisite since nvm requires bash. yarn is then pinned via
|
|
||||||
`corepack prepare yarn@<version> --activate`. Never install "latest" or "lts";
|
|
||||||
always exact versions. `script/cibuild` runs the CI build: it changes to the
|
|
||||||
repo root and runs
|
|
||||||
`docker build --build-arg CHECK_EPOCH="$epoch" --build-arg VERSION="$version" .`,
|
|
||||||
where `epoch` is a per-invocation nonce (see the `CHECK_EPOCH` rule below) and
|
|
||||||
`version` is computed on the host because `.git` is not in the build context
|
|
||||||
(see the git-describe rule below); the Gitea workflow calls it. Four further
|
|
||||||
scripts are our own extensions to the standard: `script/check` runs
|
|
||||||
`script/test`, `script/lint`, and `script/fmt-check`; `script/precommit` is
|
|
||||||
what the git pre-commit hook runs, and it calls `script/check`;
|
|
||||||
`script/install-precommit` installs the git pre-commit hook (the `make hooks`
|
|
||||||
target shims to it); and `script/projectname` (literally that filename) simply
|
|
||||||
outputs the project's name. Scripts that need the name call
|
|
||||||
`script/projectname` — e.g. `script/docker` assembles its image tag from it —
|
|
||||||
so those scripts stay byte-identical across all repos. Repo-type-specific
|
|
||||||
pre-commit extras (e.g. `go mod tidy` verification in Go repos) belong in
|
|
||||||
`script/precommit`, not in the hook itself. Model scripts are at
|
|
||||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/script/<name>`. The README
|
|
||||||
must document the provided scripts in an **Entrypoints** section (see the
|
|
||||||
README requirements below).
|
|
||||||
|
|
||||||
- Always use Makefile targets (`make fmt`, `make test`, `make lint`, etc.)
|
- Always use Makefile targets (`make fmt`, `make test`, `make lint`, etc.)
|
||||||
instead of invoking the underlying tools directly. The Makefile is the single
|
instead of invoking the underlying tools directly. The Makefile is the single
|
||||||
@@ -94,346 +54,14 @@ style conventions are in separate documents:
|
|||||||
reading the Makefile.
|
reading the Makefile.
|
||||||
|
|
||||||
- Every repo should have a `Dockerfile`. All Dockerfiles must run `make check`
|
- Every repo should have a `Dockerfile`. All Dockerfiles must run `make check`
|
||||||
as a build step so the build fails if the branch is not green — which requires
|
as a build step so the build fails if the branch is not green. For non-server
|
||||||
`ARG CHECK_EPOCH` and its guard in every stage containing a check-running
|
repos, the Dockerfile should bring up a development environment and run
|
||||||
`RUN`, per the `CHECK_EPOCH` rule below. Without them a Dockerfile satisfies
|
`make check`. For server repos, `make check` should run as an early build
|
||||||
this criterion while its check layers are served from cache, so the build
|
stage before the final image is assembled.
|
||||||
cannot fail on a branch that is not green.
|
|
||||||
|
|
||||||
**Every Dockerfile must also set `ENV LINT_IN_CONTAINER=1`**, above the
|
|
||||||
checks. `script/lint` builds `Dockerfile.lint` when it is not already in a
|
|
||||||
container; without the marker it would try that from inside a build step,
|
|
||||||
where there is no daemon. See the containerised-lint rule below.
|
|
||||||
|
|
||||||
For non-server repos, the Dockerfile should bring up a development
|
|
||||||
environment and run `make check`. For server repos, `make check` should run
|
|
||||||
as an early build stage before the final image is assembled. Dockerfiles
|
|
||||||
install development prerequisites by running `script/bootstrap` rather than
|
|
||||||
duplicating installs inline; COPY `script/` and the dependency manifests
|
|
||||||
(`package.json` + `yarn.lock`, `go.mod` + `go.sum`, etc.) before running it
|
|
||||||
so the bootstrap layer stays cached until dependencies change.
|
|
||||||
|
|
||||||
- **Every check-running `RUN` must be cache-busted with `CHECK_EPOCH`.** Docker
|
|
||||||
invalidates a `COPY` layer only when the copied content changes, so on an
|
|
||||||
unchanged tree the check layer is served from cache, the suite never runs, and
|
|
||||||
the build still exits 0. A sub-second `docker build` reporting success is a
|
|
||||||
cache hit, not a result. This applies to **every** file that runs checks in a
|
|
||||||
build step — `Dockerfile` and `Dockerfile.lint` alike; a `Dockerfile.lint`
|
|
||||||
without the cache-bust is a lint that never ran, reported as a pass. The
|
|
||||||
canonical form, in **every** stage containing a check-running `RUN`, placed
|
|
||||||
**after** the dependency-install layer so that layer stays cached:
|
|
||||||
|
|
||||||
```dockerfile
|
|
||||||
ARG CHECK_EPOCH
|
|
||||||
RUN [ -n "$CHECK_EPOCH" ] || exit 1
|
|
||||||
RUN echo "check epoch: ${CHECK_EPOCH}" && make check
|
|
||||||
```
|
|
||||||
|
|
||||||
and in both `script/cibuild` and `script/docker`:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
epoch="$(date +%s%N)$$"
|
|
||||||
version="$(git describe --tags --always --dirty 2>/dev/null || true)"
|
|
||||||
[ -n "$version" ] || version="unknown"
|
|
||||||
docker build \
|
|
||||||
--build-arg CHECK_EPOCH="$epoch" \
|
|
||||||
--build-arg VERSION="$version" \
|
|
||||||
.
|
|
||||||
```
|
|
||||||
|
|
||||||
`script/lint` needs the same nonce but is **not** this command: it builds a
|
|
||||||
different file with `-f Dockerfile.lint` and passes no version. Copy its
|
|
||||||
form from the containerised-lint rule below, not this block — a
|
|
||||||
`docker build` with no `-f` builds the main image and lints nothing.
|
|
||||||
|
|
||||||
The `VERSION` lines are there for a different reason, covered by the
|
|
||||||
git-describe rule below; they are shown here so the two rules do not each
|
|
||||||
document half a command. All four `CHECK_EPOCH` elements are load-bearing;
|
|
||||||
none is optional, and each guards a failure mode that otherwise fails green:
|
|
||||||
- `ARG` is stage-scoped, so a single declaration leaves the other check
|
|
||||||
stages frozen while the fix reviews as complete. Declare it in every stage
|
|
||||||
that runs checks, immediately above the first such `RUN`.
|
|
||||||
- Expand the value into the command. This makes the cache miss contractual
|
|
||||||
rather than dependent on BuildKit's handling of an unreferenced `ARG`, and
|
|
||||||
it puts the epoch in the build log. The guard is itself value-keyed, for
|
|
||||||
the same reason: it references `$CHECK_EPOCH`, so BuildKit renders the
|
|
||||||
epoch into that layer's description (rendered as
|
|
||||||
`RUN [ -n "<epoch>" ] || exit 1`) and re-runs it whenever the value
|
|
||||||
changes. Each stage therefore has two independent invalidation points, and
|
|
||||||
the guard always precedes the check `RUN`. Keep both: the expansion is
|
|
||||||
defence in depth, and it is what makes the epoch visible in the build
|
|
||||||
output.
|
|
||||||
- The `[ -n ... ]` guard is required: an unset `ARG` is empty, and empty is
|
|
||||||
a stable cache key, so without it a bare `docker build .` still produces
|
|
||||||
the false green. Failed steps are never cached, so the guard fails on
|
|
||||||
every such invocation, loudly. A bare `docker build .` failing is by
|
|
||||||
design.
|
|
||||||
- Assign `epoch=` on its own line, never inline in the `--build-arg`
|
|
||||||
argument: a failing command substitution inside an argument does not trip
|
|
||||||
`set -e`, so the inline form silently degrades to an empty constant. The
|
|
||||||
`$$` suffix is required because busybox `date` drops `%N` and exits 0, so
|
|
||||||
on an alpine host the epoch would degrade to second granularity and
|
|
||||||
concurrent invocations would collide.
|
|
||||||
|
|
||||||
This invalidates the check layers and everything after them while leaving
|
|
||||||
`go mod download` and `script/bootstrap` cached, so it does not push against
|
|
||||||
the five-minute Docker build ceiling. Blanket `--no-cache` is not an
|
|
||||||
acceptable substitute: it also busts the dependency layer, so every run
|
|
||||||
reinstalls dependencies over the network instead of only the first and those
|
|
||||||
after a manifest change. Never reach for `docker builder prune` — the build
|
|
||||||
cache is shared with every other build on the host.
|
|
||||||
|
|
||||||
- **Every lint run happens in a container.** `script/lint` runs the linter
|
|
||||||
directly when it is already inside one, and otherwise builds `Dockerfile.lint`
|
|
||||||
so that it is. Either way the linter never runs on a developer host, where its
|
|
||||||
answer is not trustworthy:
|
|
||||||
- **Confirmed false green.** golangci-lint keys cached results on file
|
|
||||||
**content, not location**, so a second checkout of the same commit serves
|
|
||||||
its findings. One implementer reported `0 issues` on a branch genuinely
|
|
||||||
red with a `goconst` finding. Own-clones-instead-of-worktrees does not
|
|
||||||
help; two clones are byte-identical exactly as two worktrees were.
|
|
||||||
- **False reds**: findings reported against other checkouts and against
|
|
||||||
worktrees already deleted; in one case 399 issues returned to a clean
|
|
||||||
clone that genuinely lints 0.
|
|
||||||
- **Lock contention indistinguishable from findings.** golangci-lint flocks
|
|
||||||
`$TMPDIR/golangci-lint.lock` (`pkg/commands/run.go`, `acquireFileLock()`),
|
|
||||||
host-global and independent of `GOLANGCI_LINT_CACHE`, 5-second timeout. It
|
|
||||||
prints `parallel golangci-lint is running`, analyzes nothing, exits
|
|
||||||
non-zero. Not fixed by per-cache isolation — measured.
|
|
||||||
- **Version skew**: a host linter differing from the pinned one, with the
|
|
||||||
container surfacing thirteen findings the host missed.
|
|
||||||
|
|
||||||
A container has its own cache, its own `TMPDIR` and a binary pinned by
|
|
||||||
digest, so none of it is reachable. This supersedes the per-checkout
|
|
||||||
`GOLANGCI_LINT_CACHE`/`TMPDIR` wrapper, which existed only to make a host
|
|
||||||
run trustworthy; delete it on adoption.
|
|
||||||
|
|
||||||
The canonical `script/lint`, whose executable lines are the same in every
|
|
||||||
repo apart from the native lint command:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
#!/bin/sh
|
|
||||||
# script/lint: run the linter. Inside a container, run it directly; on a
|
|
||||||
# host, build Dockerfile.lint so it runs in one anyway.
|
|
||||||
#
|
|
||||||
# LINT_IN_CONTAINER is set by this repo's Dockerfiles and is the ONLY
|
|
||||||
# accepted signal. Do not add a /.dockerenv fallback: it is absent inside
|
|
||||||
# BuildKit RUN steps and present on hosts that are themselves containers,
|
|
||||||
# so it both misses and false-positives — and a false positive silently
|
|
||||||
# restores host linting.
|
|
||||||
set -eu
|
|
||||||
|
|
||||||
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
|
|
||||||
|
|
||||||
main() {
|
|
||||||
cd "$ROOT"
|
|
||||||
|
|
||||||
if [ "${LINT_IN_CONTAINER:-}" = "1" ]; then
|
|
||||||
exec golangci-lint run --config .golangci.yml ./...
|
|
||||||
fi
|
|
||||||
|
|
||||||
# Own line, and `$$` because busybox `date` drops %N silently.
|
|
||||||
# Without a fresh nonce the lint layer is cached and this exits 0
|
|
||||||
# having linted nothing.
|
|
||||||
epoch="$(date +%s%N)$$"
|
|
||||||
docker build \
|
|
||||||
--build-arg CHECK_EPOCH="$epoch" \
|
|
||||||
-f Dockerfile.lint \
|
|
||||||
.
|
|
||||||
}
|
|
||||||
|
|
||||||
main "$@"
|
|
||||||
```
|
|
||||||
|
|
||||||
and `Dockerfile.lint`, the standalone path for a developer host:
|
|
||||||
|
|
||||||
```dockerfile
|
|
||||||
# Lint-only image, built by script/lint when not already in a container.
|
|
||||||
# golangci/golangci-lint:v2.12.2 (Debian-based), 2026-08-07
|
|
||||||
FROM golangci/golangci-lint@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240
|
|
||||||
|
|
||||||
WORKDIR /src
|
|
||||||
ENV LINT_IN_CONTAINER=1
|
|
||||||
|
|
||||||
COPY go.mod go.sum ./
|
|
||||||
RUN go mod download
|
|
||||||
|
|
||||||
COPY . .
|
|
||||||
|
|
||||||
# ARG after the dependency layer so only the lint re-runs.
|
|
||||||
ARG CHECK_EPOCH
|
|
||||||
RUN [ -n "$CHECK_EPOCH" ] || exit 1
|
|
||||||
RUN echo "lint epoch: ${CHECK_EPOCH}" && \
|
|
||||||
golangci-lint config verify --config .golangci.yml
|
|
||||||
RUN make lint
|
|
||||||
```
|
|
||||||
|
|
||||||
Load-bearing properties:
|
|
||||||
- **Detection rests on `LINT_IN_CONTAINER=1` and nothing else.** Every
|
|
||||||
Dockerfile in the repo sets it; a host does not. The asymmetry is the
|
|
||||||
whole design: a **false negative** inside a container tries a nested
|
|
||||||
`docker build`, finds no daemon and fails loudly, while a **false
|
|
||||||
positive** on a host silently lints there — the exact defect this rule
|
|
||||||
exists to kill. So the signal must be one only our own images can produce.
|
|
||||||
`/.dockerenv` is not such a signal and must not be used, even as a
|
|
||||||
fallback: measured, it is **absent** inside BuildKit `RUN` steps and
|
|
||||||
**present** on any host that is itself a container, which is the common
|
|
||||||
case for CI runners and agent sandboxes. It fails in both directions, and
|
|
||||||
one of them is the dangerous one.
|
|
||||||
- **`CHECK_EPOCH`, not `--no-cache`.** `docker build -f Dockerfile.lint .`
|
|
||||||
on an unchanged tree returns a sub-second cached success having linted
|
|
||||||
nothing. The `ARG` goes **after** the dependency layer so only the lint
|
|
||||||
re-runs; `--no-cache` would also reinstall dependencies on every lint.
|
|
||||||
- **Non-Go repos get the same pattern around their own linter** — `eslint`,
|
|
||||||
`ruff`, `prettier`, `shellcheck`. Only the base image and the native lint
|
|
||||||
command change.
|
|
||||||
- **Keep `golangci-lint config verify`, and it costs no network.** The two
|
|
||||||
commands catch disjoint classes, measured under the pinned v2.12.2: a
|
|
||||||
bogus top-level key and a bogus key under `linters.settings.lll` both pass
|
|
||||||
`golangci-lint run` with **exit 0 and `0 issues`** while `config verify`
|
|
||||||
exits 3 and names them; an invalid value type fails both; an unknown
|
|
||||||
linter name fails `run` and passes `config verify`. So `run` alone
|
|
||||||
silently ignores an unknown key — the mode where a threshold reads as
|
|
||||||
configured and is not applied. It needs no network: every case reproduced
|
|
||||||
byte-identically under `docker run --network none`, in a container where
|
|
||||||
`getent hosts golangci-lint.run` exits 2. The schema is embedded in the
|
|
||||||
pinned binary. Re-run that control when bumping the pin.
|
|
||||||
- **A failed `script/lint` that names no finding is not a lint result.** On
|
|
||||||
the host path `docker build` exits 1 both for findings and for a build
|
|
||||||
that never got there (daemon down, image unpullable, disk full). BuildKit
|
|
||||||
names the failing step; read it, fix the environment, re-run. Do not
|
|
||||||
record a verdict from a run that did not lint.
|
|
||||||
|
|
||||||
**Scope: this rule is about linters, and a formatter is not one.**
|
|
||||||
`script/fmt` writes your working tree, so it can only run on the host, and
|
|
||||||
`script/fmt-check` is its read-only twin. In a repo whose formatter **is**
|
|
||||||
its linter (prettier over markdown; this repo), `script/bootstrap` therefore
|
|
||||||
installs the linter on the host as an ordinary dependency and
|
|
||||||
`script/fmt-check` runs it there. That is accepted: the version is pinned in
|
|
||||||
`package.json` and installed into the repo's own `node_modules`, so there is
|
|
||||||
no shared content-keyed cache, no host-global lock and nothing to skew
|
|
||||||
against. What is forbidden is taking a **lint verdict** from it —
|
|
||||||
`script/lint` stays the only source of one. A repo auditing itself will see
|
|
||||||
those hits and should leave them; anything else the grep finds is a real
|
|
||||||
second path to the linter and goes.
|
|
||||||
|
|
||||||
**What a consuming repo does to adopt this**, in order:
|
|
||||||
1. Add `Dockerfile.lint`.
|
|
||||||
2. Replace `script/lint` with the form above, with its own native lint
|
|
||||||
command.
|
|
||||||
3. Add `ENV LINT_IN_CONTAINER=1` to **every** stage of every Dockerfile that
|
|
||||||
runs checks — the lint stage and the build stage both.
|
|
||||||
4. Delete any golangci-lint install from `script/bootstrap`, with its
|
|
||||||
version and ref variables and its call site. Nothing on the host lints,
|
|
||||||
so it can only reintroduce version skew. A JS repo's `yarn install`
|
|
||||||
stays.
|
|
||||||
5. Delete the per-checkout lint state: `GOLANGCI_LINT_CACHE` and `TMPDIR`
|
|
||||||
exports, `--allow-serial-runners`, the retry/VOID wrapper, and
|
|
||||||
`.lint-cache/` from both `.gitignore` and `.dockerignore`.
|
|
||||||
6. Verify by running `make lint` twice on an unchanged tree: the lint layer
|
|
||||||
must be `DONE` both times, never `CACHED`. Then plant a violation,
|
|
||||||
confirm it fails naming the finding, revert. A bare
|
|
||||||
`docker build -f Dockerfile.lint .` must fail on the guard.
|
|
||||||
|
|
||||||
`script/check`, `script/cibuild`, `script/docker` and the `Dockerfile` are
|
|
||||||
unchanged by this: `make check` still runs inside the image, and
|
|
||||||
`script/lint` there takes the native path.
|
|
||||||
|
|
||||||
- **Dockerfiles must use a separate lint stage for fail-fast feedback.** Go
|
|
||||||
repos use a multistage build where linting runs in an independent stage based
|
|
||||||
on the `golangci/golangci-lint` image (pinned by hash), so lint failures
|
|
||||||
surface in seconds rather than after a full compile. The build stage declares
|
|
||||||
an explicit dependency on it via `COPY --from=lint /src/go.sum /dev/null`,
|
|
||||||
which forces BuildKit — which runs stages in parallel by default — to finish
|
|
||||||
linting first. The canonical Go repo `Dockerfile`:
|
|
||||||
|
|
||||||
```dockerfile
|
|
||||||
# Lint stage — fast feedback on formatting and lint issues
|
|
||||||
# golangci/golangci-lint:v2.x.x, YYYY-MM-DD
|
|
||||||
FROM golangci/golangci-lint@sha256:... AS lint
|
|
||||||
WORKDIR /src
|
|
||||||
ENV LINT_IN_CONTAINER=1
|
|
||||||
COPY go.mod go.sum ./
|
|
||||||
RUN go mod download
|
|
||||||
COPY . .
|
|
||||||
ARG CHECK_EPOCH
|
|
||||||
RUN [ -n "$CHECK_EPOCH" ] || exit 1
|
|
||||||
RUN echo "check epoch: ${CHECK_EPOCH}" && make fmt-check
|
|
||||||
RUN make lint
|
|
||||||
|
|
||||||
# Build stage
|
|
||||||
# golang:1.x-alpine, YYYY-MM-DD
|
|
||||||
FROM golang@sha256:... AS builder
|
|
||||||
WORKDIR /src
|
|
||||||
ENV LINT_IN_CONTAINER=1
|
|
||||||
|
|
||||||
# Force BuildKit to run the lint stage before proceeding
|
|
||||||
COPY --from=lint /src/go.sum /dev/null
|
|
||||||
|
|
||||||
COPY go.mod go.sum ./
|
|
||||||
RUN go mod download
|
|
||||||
COPY . .
|
|
||||||
ARG CHECK_EPOCH
|
|
||||||
RUN [ -n "$CHECK_EPOCH" ] || exit 1
|
|
||||||
RUN echo "check epoch: ${CHECK_EPOCH}" && make test
|
|
||||||
|
|
||||||
# VERSION comes from the host via --build-arg; see the git-describe rule
|
|
||||||
# below. Never run `git describe` here: .dockerignore excludes .git, so
|
|
||||||
# it yields an empty version without failing the build.
|
|
||||||
ARG VERSION=dev
|
|
||||||
RUN CGO_ENABLED=0 go build -trimpath \
|
|
||||||
-ldflags="-s -w -X main.Version=${VERSION}" \
|
|
||||||
-o /app ./cmd/app/
|
|
||||||
|
|
||||||
# Runtime stage
|
|
||||||
FROM alpine@sha256:...
|
|
||||||
COPY --from=builder /app /usr/local/bin/app
|
|
||||||
ENTRYPOINT ["app"]
|
|
||||||
```
|
|
||||||
|
|
||||||
Key points:
|
|
||||||
- The lint stage uses the `golangci/golangci-lint` image directly (it has
|
|
||||||
both Go and the linter), so nothing needs installing. `make lint` there
|
|
||||||
runs `script/lint`, which sees `LINT_IN_CONTAINER=1` and invokes
|
|
||||||
`golangci-lint` natively instead of building `Dockerfile.lint`. Without
|
|
||||||
that `ENV` the stage would attempt a nested build and fail.
|
|
||||||
- `COPY --from=lint /src/go.sum /dev/null` is a no-op copy that exists only
|
|
||||||
to create the stage dependency; without it a lint failure might not fail
|
|
||||||
the overall build.
|
|
||||||
- **Re-prove that ordering on a warm cache after adopting `CHECK_EPOCH`.**
|
|
||||||
The cache-bust turns the no-op `COPY` into a content-cache hit, so an
|
|
||||||
ordering guarantee established cold does not automatically carry over. It
|
|
||||||
was re-proved in another org repo using the same trick and held, but that
|
|
||||||
result does not transfer by assumption — re-check it warm.
|
|
||||||
- If the project uses `//go:embed` referencing build artifacts, the lint
|
|
||||||
stage must create placeholders so the directives resolve:
|
|
||||||
`RUN mkdir -p web/dist && touch web/dist/index.html`.
|
|
||||||
- If linting needs CGO or system libraries (e.g. `vips-dev`), `apk add` them
|
|
||||||
in the lint stage.
|
|
||||||
- Tests run in the build stage, not the lint stage: they may need compiled
|
|
||||||
artifacts or heavier dependencies.
|
|
||||||
- `ARG CHECK_EPOCH` appears in **both** stages, because `ARG` is
|
|
||||||
stage-scoped: declaring it only in the lint stage leaves `make test`
|
|
||||||
frozen at its last cached result. In each stage the guard sits immediately
|
|
||||||
below the `ARG` and the value is expanded into the first check `RUN`.
|
|
||||||
Later `RUN`s in the same stage need no expansion; their parent layer is
|
|
||||||
already busted.
|
|
||||||
- `ARG VERSION=dev` is declared in the build stage and supplied by
|
|
||||||
`script/docker` and `script/cibuild`. **No stage may call
|
|
||||||
`git describe`**: `.dockerignore` excludes `.git`, so it yields an empty
|
|
||||||
version without failing. See the git-describe rule further down.
|
|
||||||
|
|
||||||
- Every repo should have a Gitea Actions workflow (`.gitea/workflows/`) that
|
- Every repo should have a Gitea Actions workflow (`.gitea/workflows/`) that
|
||||||
runs `script/cibuild` (which runs
|
runs `docker build .` on push. Since the Dockerfile already runs `make check`,
|
||||||
`docker build --build-arg CHECK_EPOCH="$epoch" --build-arg VERSION="$version" .`)
|
a successful build implies all checks pass.
|
||||||
on push. The Dockerfile runs `make check`, so a successful build implies all
|
|
||||||
checks pass — but that implication holds **only** because of the `CHECK_EPOCH`
|
|
||||||
cache-bust described above. Without it, an unchanged tree serves the check
|
|
||||||
layer from cache and the build reports a green it never earned. A bare
|
|
||||||
`docker build .` fails closed by design, on the `[ -n "$CHECK_EPOCH" ]` guard;
|
|
||||||
always go through `script/cibuild` or `script/docker`. Never accept a pass as
|
|
||||||
evidence without confirming it ran: a sub-second wall time, or `CACHED` on the
|
|
||||||
check layer, means nothing was executed.
|
|
||||||
|
|
||||||
- Use platform-standard formatters: `black` for Python, `prettier` for
|
- Use platform-standard formatters: `black` for Python, `prettier` for
|
||||||
JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration with
|
JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration with
|
||||||
@@ -441,11 +69,9 @@ style conventions are in separate documents:
|
|||||||
Markdown (hard-wrap at 80 columns). Documentation and writing repos (Markdown,
|
Markdown (hard-wrap at 80 columns). Documentation and writing repos (Markdown,
|
||||||
HTML, CSS) should also have `.prettierrc` and `.prettierignore`.
|
HTML, CSS) should also have `.prettierrc` and `.prettierignore`.
|
||||||
|
|
||||||
- Pre-commit hook: runs `script/precommit`, which calls `script/check`. If local
|
- Pre-commit hook: `make check` if local testing is possible, otherwise
|
||||||
testing is not possible in the repo, `script/precommit` may skip `script/test`
|
`make lint && make fmt-check`. The Makefile should provide a `make hooks`
|
||||||
and run only `script/lint` and `script/fmt-check`. The hook is installed by
|
target to install the pre-commit hook.
|
||||||
`script/install-precommit`; the Makefile must provide a `make hooks` target
|
|
||||||
that shims to it.
|
|
||||||
|
|
||||||
- All repos with software must have tests that run via the platform-standard
|
- All repos with software must have tests that run via the platform-standard
|
||||||
test framework (`go test`, `pytest`, `jest`/`vitest`, etc.). If no meaningful
|
test framework (`go test`, `pytest`, `jest`/`vitest`, etc.). If no meaningful
|
||||||
@@ -456,42 +82,6 @@ style conventions are in separate documents:
|
|||||||
- `make test` must complete in under 20 seconds. Add a 30-second timeout in the
|
- `make test` must complete in under 20 seconds. Add a 30-second timeout in the
|
||||||
Makefile.
|
Makefile.
|
||||||
|
|
||||||
- **`make test` should use the conditional verbose rerun pattern.** Run tests
|
|
||||||
without `-v` (verbose) first. If tests fail, automatically rerun with `-v` to
|
|
||||||
show full output. This keeps CI logs and `docker build` output clean on
|
|
||||||
success (just package/suite summaries) while providing full diagnostic detail
|
|
||||||
on failure (every test case, every assertion). The general shell pattern:
|
|
||||||
|
|
||||||
```makefile
|
|
||||||
test:
|
|
||||||
@<test-command> || \
|
|
||||||
{ echo "--- Rerunning with -v for details ---"; \
|
|
||||||
<test-command-with-v>; exit 1; }
|
|
||||||
```
|
|
||||||
|
|
||||||
Go example:
|
|
||||||
|
|
||||||
```makefile
|
|
||||||
test:
|
|
||||||
@go test -timeout 30s -race -cover ./... || \
|
|
||||||
{ echo "--- Rerunning with -v for details ---"; \
|
|
||||||
go test -timeout 30s -race -v ./...; exit 1; }
|
|
||||||
```
|
|
||||||
|
|
||||||
Python example:
|
|
||||||
|
|
||||||
```makefile
|
|
||||||
test:
|
|
||||||
@python -m pytest || \
|
|
||||||
{ echo "--- Rerunning with -v for details ---"; \
|
|
||||||
python -m pytest -v; exit 1; }
|
|
||||||
```
|
|
||||||
|
|
||||||
The `exit 1` ensures the target always fails after a rerun — the first run
|
|
||||||
already proved the tests are broken, so the build must not pass even if a
|
|
||||||
flaky test happens to succeed on the second attempt. The rerun exists solely
|
|
||||||
for diagnostic output.
|
|
||||||
|
|
||||||
- Docker builds must complete in under 5 minutes.
|
- Docker builds must complete in under 5 minutes.
|
||||||
|
|
||||||
- `make check` must not modify any files in the repo. Tests may use temporary
|
- `make check` must not modify any files in the repo. Tests may use temporary
|
||||||
@@ -503,147 +93,10 @@ style conventions are in separate documents:
|
|||||||
must be in `.gitignore`. No exceptions.
|
must be in `.gitignore`. No exceptions.
|
||||||
|
|
||||||
- `.gitignore` should be comprehensive from the start: OS files (`.DS_Store`),
|
- `.gitignore` should be comprehensive from the start: OS files (`.DS_Store`),
|
||||||
editor files (`.swp`, `*~`), in-repo agent scratch directories (`.claude/`,
|
editor files (`.swp`, `*~`), language build artifacts, and `node_modules/`.
|
||||||
which holds one worktree — an entire additional checkout of the repo — per
|
Fetch the standard `.gitignore` from
|
||||||
in-flight agent), language build artifacts, and `node_modules/`. Fetch the
|
|
||||||
standard `.gitignore` from
|
|
||||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when setting up
|
`https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when setting up
|
||||||
a new repo. These patterns are written to `.gitignore`'s own semantics, in
|
a new repo.
|
||||||
which an unanchored pattern already matches at every depth. They are not a
|
|
||||||
`.dockerignore` and must not be transplanted into one unmodified — see the
|
|
||||||
next rule.
|
|
||||||
|
|
||||||
- **`.dockerignore` does not use `.gitignore` semantics, and copying patterns
|
|
||||||
across unmodified leaves secrets in the build context.** Docker matches with
|
|
||||||
`moby/patternmatcher`: Go `filepath.Match` semantics plus a `**` extension,
|
|
||||||
compiled to a regexp — plain `filepath.Match` has no `**` at all. So `*` does
|
|
||||||
not cross `/`, and a pattern without a leading `**/` is anchored at the
|
|
||||||
build-context root. A `.dockerignore` listing `.env`, `*.pem` and `*.key`
|
|
||||||
therefore excludes only the copies at the repository root; `config/.env` and
|
|
||||||
`certs/server.key` still reach the context and can land in an image layer.
|
|
||||||
That file is more dangerous than a short one with no secret patterns at all,
|
|
||||||
because it reads as solved and stops anyone looking. Give every
|
|
||||||
depth-independent pattern the `**/` prefix — `**/node_modules`,
|
|
||||||
`**/.DS_Store`, and the secret patterns in the canonical file, which are
|
|
||||||
additionally case-folded per the rule below — and leave only genuinely
|
|
||||||
root-anchored entries unprefixed: `.git`, the in-repo agent scratch directory
|
|
||||||
`.claude`, and the repo's own host-built binary. The inverse move is equally
|
|
||||||
wrong: never apply `**/` to `.gitignore`, where it is redundant and produces a
|
|
||||||
file that is wrong in a way that looks careful. Each file is written to its
|
|
||||||
own semantics; neither is derived from the other. Fetch the standard
|
|
||||||
`.dockerignore` from
|
|
||||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore` and extend
|
|
||||||
it with the repo's own host-built artifacts — a host `make build` that leaves
|
|
||||||
a compiled binary in the repo root puts that binary in the build context,
|
|
||||||
where `.gitignore` hides it from every git-based check. Write that binary
|
|
||||||
anchored, `/myapp` and never `**/myapp`: the prefixed form also matches
|
|
||||||
`cmd/myapp/` and deletes the package directory from the context.
|
|
||||||
|
|
||||||
- **In-repo agent scratch belongs in both files, written to each file's own
|
|
||||||
semantics.** `.claude/` holds one worktree per in-flight agent — an entire
|
|
||||||
additional checkout of the repo — so with `COPY . .` the build context
|
|
||||||
inflates by a multiple of the repo, and another session's unreviewed,
|
|
||||||
sometimes uncommitted work can be copied into an image layer. The directory is
|
|
||||||
also created and destroyed constantly, so it invalidates `COPY . .` for
|
|
||||||
reasons that have nothing to do with the repo's own content. In `.gitignore`
|
|
||||||
the entry is `.claude/`, unanchored, which already matches at every depth. In
|
|
||||||
`.dockerignore` it is `.claude`, anchored and with **no** `**/` prefix: the
|
|
||||||
directory occurs exactly once **where agents run at the repo root**, and the
|
|
||||||
prefixed form would also match any nested directory of that name and delete it
|
|
||||||
from the build. It is not case-folded the way the secret patterns are, because
|
|
||||||
tooling creates it in exactly one spelling, so a folded pattern would add no
|
|
||||||
coverage.
|
|
||||||
|
|
||||||
**Known gap that comes with the anchored form.** The directory is created in
|
|
||||||
the agent's working directory, so the "exactly once, at the root" premise is
|
|
||||||
a property of how agents are run and not of the tooling. Where agents run in
|
|
||||||
subdirectories — a monorepo with a per-service agent is the ordinary case —
|
|
||||||
`services/api/.claude/` is **not** excluded by the canonical entry and still
|
|
||||||
reaches the build context and the image, which is the exposure the entry
|
|
||||||
exists to close. A repo in that shape adds its own anchored entries
|
|
||||||
(`/services/api/.claude`), or `**/.claude` once it has confirmed no
|
|
||||||
legitimately named nested directory would be caught. This is stated in the
|
|
||||||
canonical `.dockerignore` itself, since that file is what consuming repos
|
|
||||||
receive.
|
|
||||||
|
|
||||||
- **`.dockerignore` matching is case-sensitive, so cover capitalisation with
|
|
||||||
character classes rather than by doubling patterns.** `**/*.key` does not
|
|
||||||
match `certs/SERVER.KEY`, which is reachable on the case-insensitive
|
|
||||||
filesystems most laptops use. Adding an ALL-CAPS twin for each pattern is not
|
|
||||||
the fix: it still misses `Server.Key` and `Ca.Pem` while reading as though
|
|
||||||
case were handled — the same manufactured confidence as the root-anchored
|
|
||||||
form. The matcher supports character ranges, so one line covers every
|
|
||||||
spelling: `**/*.[kK][eE][yY]`, `**/*.[pP][eE][mM]`. Apply this to every secret
|
|
||||||
name, not only to extensions: the extensionless SSH keys and `.envrc` need it
|
|
||||||
for the same reason, since on the very filesystems that make `SERVER.KEY`
|
|
||||||
reachable, direnv reads `.ENVRC` and ssh reads `ID_RSA`. Note that `*` matches
|
|
||||||
the empty string, so `**/*.[eE][nN][vV]` already covers a bare `.ENV` and no
|
|
||||||
separate literal `.env` entry is needed.
|
|
||||||
|
|
||||||
- **A pattern that also catches something the build needs is re-included with a
|
|
||||||
negation, not deleted.** The canonical `**/*.[eE][nN][vV]` excludes a
|
|
||||||
committed env template such as `example.env`; a repo whose build genuinely
|
|
||||||
reads one adds `!docs/example.env` after the pattern. Deleting the pattern
|
|
||||||
instead reopens the exposure for every other file it covers.
|
|
||||||
|
|
||||||
- **Verify `.dockerignore` by enumerating the image, not by reading the
|
|
||||||
patterns.** Plant files at the root _and_ at least two directories deep, build
|
|
||||||
a probe image that does `COPY . .`, and list what actually landed
|
|
||||||
(`docker run --rm --entrypoint find IMAGE /app`). Reading the patterns and
|
|
||||||
agreeing they look right is exactly what lets the root-only form through. The
|
|
||||||
`transferring context` size is not a substitute: a nested secret is a few
|
|
||||||
bytes, and BuildKit transfers only the delta from the previous build, so the
|
|
||||||
reported size describes the transfer and not the contents of the image.
|
|
||||||
|
|
||||||
- **Excluding `.git` means `git describe` cannot run inside any build stage, and
|
|
||||||
it fails quietly there.** The `GOLDFLAGS` version-embedding pattern assumes
|
|
||||||
`.git` is present; in a build stage there is no repository, so `git describe`
|
|
||||||
writes nothing to stdout and the `-X main.Version=` value comes out **empty**
|
|
||||||
rather than erroring. The binary then reports no version at all and the build
|
|
||||||
still exits 0. Compute the version **on the host** and thread it in as a build
|
|
||||||
arg. `script/docker` and `script/cibuild` do this, byte-identically across
|
|
||||||
repos:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
# Assign on its own line: a failing command substitution inside an
|
|
||||||
# argument does not trip `set -e`, so the inline form degrades to an
|
|
||||||
# empty constant — the same silent-empty failure this rule is about.
|
|
||||||
version="$(git describe --tags --always --dirty 2>/dev/null || true)"
|
|
||||||
[ -n "$version" ] || version="unknown"
|
|
||||||
docker build \
|
|
||||||
--build-arg CHECK_EPOCH="$epoch" \
|
|
||||||
--build-arg VERSION="$version" \
|
|
||||||
.
|
|
||||||
```
|
|
||||||
|
|
||||||
`--always` makes an untagged repo yield the abbreviated commit hash instead
|
|
||||||
of failing. `|| true` keeps a failing `git describe` from tripping `set -e`
|
|
||||||
and leaves the value empty, so the `[ -n "$version" ]` line is the single
|
|
||||||
place the fallback is applied — and it is a **live** check, not defence in
|
|
||||||
depth: it fires on a build from an export with no `.git`, and on a
|
|
||||||
repository with no commits yet. Do not fold the fallback into the
|
|
||||||
substitution as `|| echo unknown`; that makes the guard unreachable, and a
|
|
||||||
guard that cannot fire is indistinguishable from one that works to everyone
|
|
||||||
who copies it. The result is non-empty by construction either way, which is
|
|
||||||
the point: an empty version reads as a successful one, while `unknown` is
|
|
||||||
visibly wrong. The Dockerfile's side is `ARG VERSION=dev` in the stage that
|
|
||||||
compiles, declared there and not inherited, because `ARG` is stage-scoped
|
|
||||||
exactly as `CHECK_EPOCH` is. Passing `VERSION` to a repo whose Dockerfile
|
|
||||||
declares no such `ARG` is silently ignored by BuildKit and costs nothing,
|
|
||||||
which is why the scripts stay byte-identical rather than growing a per-repo
|
|
||||||
variant.
|
|
||||||
|
|
||||||
One consequence for CI: the standard checkout action clones shallow and
|
|
||||||
fetches no tags, so `git describe --tags` there falls back to a bare commit
|
|
||||||
hash. A repo that embeds a tag-derived version must set `fetch-depth: 0` on
|
|
||||||
its checkout step; a repo that does not embed a version needs no change.
|
|
||||||
|
|
||||||
- **No build artifacts in version control.** Code-derived data (compiled
|
|
||||||
bundles, minified output, generated assets) must never be committed to the
|
|
||||||
repository if it can be avoided. The build process (e.g. Dockerfile, Makefile)
|
|
||||||
should generate these at build time. Notable exception: Go protobuf generated
|
|
||||||
files (`.pb.go`) ARE committed because repos need to work with `go get`, which
|
|
||||||
downloads code but does not execute code generation.
|
|
||||||
|
|
||||||
- Never use `git add -A` or `git add .`. Always stage files explicitly by name.
|
- Never use `git add -A` or `git add .`. Always stage files explicitly by name.
|
||||||
|
|
||||||
@@ -654,112 +107,7 @@ style conventions are in separate documents:
|
|||||||
|
|
||||||
- `.golangci.yml` is standardized and must _NEVER_ be modified by an agent, only
|
- `.golangci.yml` is standardized and must _NEVER_ be modified by an agent, only
|
||||||
manually by the user. Fetch from
|
manually by the user. Fetch from
|
||||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml`. The
|
`https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml`.
|
||||||
canonical golangci-lint version is v2.12.2 (released 2026-05-06), pinned as
|
|
||||||
the image digest in `Dockerfile.lint`
|
|
||||||
(`golangci/golangci-lint@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240`,
|
|
||||||
which reports
|
|
||||||
`golangci-lint has version 2.12.2 built with go1.26.2 from c0d3ddc9`). That
|
|
||||||
digest is the only pin: golangci-lint is not installed on the host by any
|
|
||||||
repo. Bumping the version means changing that one digest.
|
|
||||||
|
|
||||||
- **`script/bootstrap` must not install golangci-lint.** This supersedes the
|
|
||||||
pinned host install that used to be canonical here. `script/lint` never runs
|
|
||||||
it on the host — it either builds `Dockerfile.lint` or is already in a
|
|
||||||
container that ships the binary — so a host install has no caller, and its
|
|
||||||
only remaining effect is to put a second, independently-versioned linter where
|
|
||||||
somebody eventually runs it by hand and believes the result. Delete the block,
|
|
||||||
its version and ref variables, and its call site.
|
|
||||||
|
|
||||||
This is not a ban on host dependency installs generally. A JS or docs repo's
|
|
||||||
`script/bootstrap` runs `yarn install`, which brings its linter along with
|
|
||||||
every other dependency; that is unavoidable and fine. The rule is about a
|
|
||||||
**dedicated** linter install, and about where a verdict may come from.
|
|
||||||
|
|
||||||
**The version-enforcement principle it established still applies to any
|
|
||||||
other tool a repo pins and installs on the host**, and it is the part worth
|
|
||||||
keeping, because each of its four properties guards a failure that otherwise
|
|
||||||
reports success:
|
|
||||||
- **Compare the installed version against the pin, never test presence.** A
|
|
||||||
`if missing <tool>; then install; fi` guard tests `PATH` presence and
|
|
||||||
never version, so on any already-provisioned machine the pin is inert and
|
|
||||||
a version bump is a silent no-op. Compare the **whole** version token,
|
|
||||||
exactly: a parser that stops at the first `-` reports `2.12.2` for a host
|
|
||||||
running `2.12.2-rc1` and skips the install — the original defect,
|
|
||||||
reintroduced through the comparison meant to fix it.
|
|
||||||
- **After installing, re-resolve the binary the way callers resolve it** —
|
|
||||||
through `PATH`, not the directory the installer wrote to — and assert the
|
|
||||||
reported version is the pin. An installer that writes to `GOBIN` while a
|
|
||||||
different binary shadows it earlier in `PATH` genuinely succeeds and
|
|
||||||
changes nothing any caller sees, which is worse than no fix: it converts a
|
|
||||||
known-stale tool into one everyone believes is pinned. Run `hash -r` first
|
|
||||||
so the shell does not answer from its own lookup cache, and when the
|
|
||||||
assertion fails, name the path `command -v` found, the version it reports,
|
|
||||||
and the directory the install wrote to. Diagnose from the resolved path
|
|
||||||
rather than asserting a cause: only a path **outside** the install
|
|
||||||
directory is shadowing.
|
|
||||||
- **A mis-parse must fall through to reinstall, never to a false match.**
|
|
||||||
Absent binary, non-zero exit, empty output and unrecognised output should
|
|
||||||
all yield an empty string, which compares unequal to the pin. The failure
|
|
||||||
direction is always a redundant install, never a skipped one.
|
|
||||||
- **Call it, and say so on success.** A function defined and never called is
|
|
||||||
a silent no-op indistinguishable from success: exit 0, nothing installed,
|
|
||||||
no output. Both success branches must print a line naming the version.
|
|
||||||
|
|
||||||
Verifying such logic requires a negative control in an environment where a
|
|
||||||
shadowing binary exists earlier in `PATH` than the install target — without
|
|
||||||
it the control passes against the naive compare-then-install form too and
|
|
||||||
proves nothing — plus a mis-parse control that feeds unparseable `--version`
|
|
||||||
output and confirms a reinstall. Run those controls against the block as a
|
|
||||||
consuming repo would adopt it: pasted into a `script/bootstrap`-shaped file
|
|
||||||
that is then executed, never by sourcing it and invoking the function
|
|
||||||
yourself. Driving the function directly tests something the artifact does
|
|
||||||
not do, and it is exactly how a missing call site passes every control while
|
|
||||||
the adopted snippet does nothing.
|
|
||||||
|
|
||||||
Keep it POSIX sh: no bashisms, no arrays, no `[[`, no `grep -P`.
|
|
||||||
|
|
||||||
- **Superseded: the per-checkout `GOLANGCI_LINT_CACHE`/`TMPDIR` wrapper for
|
|
||||||
`script/lint`.** It existed only to make a host lint run trustworthy, and the
|
|
||||||
containerised-lint rule above removes the host run. Delete the wrapper, the
|
|
||||||
`--allow-serial-runners` flag, and `.lint-cache/` from both `.gitignore` and
|
|
||||||
`.dockerignore`. Two of its conclusions outlive it: **`GOCACHE` does not need
|
|
||||||
isolating** (measured — content-addressed, no foreign paths in its entries, no
|
|
||||||
global lock), and **verifying lint plumbing requires paired controls** run
|
|
||||||
against the artifact as a consuming repo would adopt it, since a control that
|
|
||||||
passes against the broken form proves nothing.
|
|
||||||
|
|
||||||
- **Interim rule for reading a lint result produced on the host, in a repo that
|
|
||||||
has not yet adopted the containerised lint above.** A lint run is **VOID**
|
|
||||||
unless both hold:
|
|
||||||
- the output contains no `parallel golangci-lint is running`, and
|
|
||||||
- no reported file path begins with `../`, and none is an absolute path
|
|
||||||
outside the tree the run was launched from.
|
|
||||||
|
|
||||||
Do not record a verdict from a void run, and do not "fix" findings in files
|
|
||||||
the change does not touch — chasing phantom findings across untouched files
|
|
||||||
puts unrelated edits into a reviewed diff, which is more expensive than the
|
|
||||||
wasted rework.
|
|
||||||
|
|
||||||
The `../` clause is the one that actually bites, and it is why a filter
|
|
||||||
keyed on `/tmp` or on absolute prefixes is not enough: golangci-lint reports
|
|
||||||
paths relative to its own resolved root rather than yours, and three of the
|
|
||||||
org's reported sightings had relative paths and would have passed such a
|
|
||||||
filter. Both clauses are needed and neither alone is sufficient — one
|
|
||||||
reproduction exited non-zero with the lock error and no foreign paths at
|
|
||||||
all, and another reported 34 well-formed findings, every one of them against
|
|
||||||
another checkout.
|
|
||||||
|
|
||||||
**State the limit of these tests rather than treating them as a guarantee.**
|
|
||||||
They catch contamination that **names** foreign files. They cannot catch
|
|
||||||
contamination that **suppresses** findings through a poisoned entry for
|
|
||||||
colliding content, which has no wall-clock tell either — **no evidence of
|
|
||||||
that mode has been observed, and nobody should go chasing it**; the point is
|
|
||||||
the reach of the tests, not a claim that the mode exists. They are a filter
|
|
||||||
for the loud mode, not a proof of soundness — which is the whole argument
|
|
||||||
for containerising the linter instead of documenting a discipline that
|
|
||||||
depends on every agent remembering to apply it. Adopt the rule above and
|
|
||||||
this one stops applying to the repo entirely.
|
|
||||||
|
|
||||||
- When pinning images or packages by hash, add a comment above the reference
|
- When pinning images or packages by hash, add a comment above the reference
|
||||||
with the version and date (YYYY-MM-DD).
|
with the version and date (YYYY-MM-DD).
|
||||||
@@ -773,76 +121,12 @@ style conventions are in separate documents:
|
|||||||
- Dockerized web services listen on port 8080 by default, overridable with
|
- Dockerized web services listen on port 8080 by default, overridable with
|
||||||
`PORT`.
|
`PORT`.
|
||||||
|
|
||||||
- **HTTP/web services must be hardened for production internet exposure before
|
|
||||||
tagging 1.0.** This means full compliance with security best practices
|
|
||||||
including, without limitation, all of the following:
|
|
||||||
- **Security headers** on every response:
|
|
||||||
- `Strict-Transport-Security` (HSTS) with `max-age` of at least one year
|
|
||||||
and `includeSubDomains`.
|
|
||||||
- `Content-Security-Policy` (CSP) with a restrictive default policy
|
|
||||||
(`default-src 'self'` as a baseline, tightened per-resource as
|
|
||||||
needed). Never use `unsafe-inline` or `unsafe-eval` unless
|
|
||||||
unavoidable, and document the reason.
|
|
||||||
- `X-Frame-Options: DENY` (or `SAMEORIGIN` if framing is required).
|
|
||||||
Prefer the `frame-ancestors` CSP directive as the primary control.
|
|
||||||
- `X-Content-Type-Options: nosniff`.
|
|
||||||
- `Referrer-Policy: strict-origin-when-cross-origin` (or stricter).
|
|
||||||
- `Permissions-Policy` restricting access to browser features the
|
|
||||||
application does not use (camera, microphone, geolocation, etc.).
|
|
||||||
- **Request and response limits:**
|
|
||||||
- Maximum request body size enforced on all endpoints (e.g. Go
|
|
||||||
`http.MaxBytesReader`). Choose a sane default per-route; never accept
|
|
||||||
unbounded input.
|
|
||||||
- Maximum response body size where applicable (e.g. paginated APIs).
|
|
||||||
- `ReadTimeout` and `ReadHeaderTimeout` on the `http.Server` to defend
|
|
||||||
against slowloris attacks.
|
|
||||||
- `WriteTimeout` on the `http.Server`.
|
|
||||||
- `IdleTimeout` on the `http.Server`.
|
|
||||||
- Per-handler execution time limits via `context.WithTimeout` or
|
|
||||||
chi/stdlib `middleware.Timeout`.
|
|
||||||
- **Authentication and session security:**
|
|
||||||
- Rate limiting on password-based authentication endpoints. API keys are
|
|
||||||
high-entropy and not susceptible to brute force, so they are exempt.
|
|
||||||
- CSRF tokens on all state-mutating HTML forms. API endpoints
|
|
||||||
authenticated via `Authorization` header (Bearer token, API key) are
|
|
||||||
exempt because the browser does not attach these automatically.
|
|
||||||
- Passwords stored using bcrypt, scrypt, or argon2 — never plain-text,
|
|
||||||
MD5, or SHA.
|
|
||||||
- Session cookies set with `HttpOnly`, `Secure`, and `SameSite=Lax` (or
|
|
||||||
`Strict`) attributes.
|
|
||||||
- **Reverse proxy awareness:**
|
|
||||||
- True client IP detection when behind a reverse proxy
|
|
||||||
(`X-Forwarded-For`, `X-Real-IP`). The application must accept
|
|
||||||
forwarded headers only from a configured set of trusted proxy
|
|
||||||
addresses — never trust `X-Forwarded-For` unconditionally.
|
|
||||||
- **CORS:**
|
|
||||||
- Authenticated endpoints must restrict `Access-Control-Allow-Origin` to
|
|
||||||
an explicit allowlist of known origins. Wildcard (`*`) is acceptable
|
|
||||||
only for public, unauthenticated read-only APIs.
|
|
||||||
- **Error handling:**
|
|
||||||
- Internal errors must never leak stack traces, SQL queries, file paths,
|
|
||||||
or other implementation details to the client. Return generic error
|
|
||||||
messages in production; detailed errors only when `DEBUG` is enabled.
|
|
||||||
- **TLS:**
|
|
||||||
- Services never terminate TLS directly. They are always deployed behind
|
|
||||||
a TLS-terminating reverse proxy. The service itself listens on plain
|
|
||||||
HTTP. However, HSTS headers and `Secure` cookie flags must still be
|
|
||||||
set by the application so that the browser enforces HTTPS end-to-end.
|
|
||||||
|
|
||||||
This list is non-exhaustive. Apply defense-in-depth: if a standard security
|
|
||||||
hardening measure exists for HTTP services and is not listed here, it is
|
|
||||||
still expected. When in doubt, harden.
|
|
||||||
|
|
||||||
- `README.md` is the primary documentation. Required sections:
|
- `README.md` is the primary documentation. Required sections:
|
||||||
- **Description**: First line must include the project name, purpose,
|
- **Description**: First line must include the project name, purpose,
|
||||||
category (web server, SPA, CLI tool, etc.), license, and author. Example:
|
category (web server, SPA, CLI tool, etc.), license, and author. Example:
|
||||||
"µPaaS is an MIT-licensed Go web application by @sneak that receives
|
"µPaaS is an MIT-licensed Go web application by @sneak that receives
|
||||||
git-frontend webhooks and deploys applications via Docker in realtime."
|
git-frontend webhooks and deploys applications via Docker in realtime."
|
||||||
- **Getting Started**: Copy-pasteable install/usage code block.
|
- **Getting Started**: Copy-pasteable install/usage code block.
|
||||||
- **Entrypoints**: Opens by stating that the repo adheres to the
|
|
||||||
[Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
|
|
||||||
standard (with that link), then documents each provided `script/`
|
|
||||||
entrypoint and its purpose.
|
|
||||||
- **Rationale**: Why does this exist?
|
- **Rationale**: Why does this exist?
|
||||||
- **Design**: How is the program structured?
|
- **Design**: How is the program structured?
|
||||||
- **TODO**: Update meticulously, even between commits. When planning, put
|
- **TODO**: Update meticulously, even between commits. When planning, put
|
||||||
@@ -897,9 +181,6 @@ style conventions are in separate documents:
|
|||||||
- `README.md`, `.git`, `.gitignore`, `.editorconfig`
|
- `README.md`, `.git`, `.gitignore`, `.editorconfig`
|
||||||
- `LICENSE`, `REPO_POLICIES.md` (copy from the `prompts` repo)
|
- `LICENSE`, `REPO_POLICIES.md` (copy from the `prompts` repo)
|
||||||
- `Makefile`
|
- `Makefile`
|
||||||
- `script/` entrypoints (`bootstrap`, `setup`, `projectname`, `test`,
|
|
||||||
`lint`, `fmt`, `fmt-check`, `check`, `docker`, `cibuild`, `precommit`,
|
|
||||||
`install-precommit`)
|
|
||||||
- `Dockerfile`, `.dockerignore`
|
- `Dockerfile`, `.dockerignore`
|
||||||
- `.gitea/workflows/check.yml`
|
- `.gitea/workflows/check.yml`
|
||||||
- Go: `go.mod`, `go.sum`, `.golangci.yml`
|
- Go: `go.mod`, `go.sum`, `.golangci.yml`
|
||||||
|
|||||||
136
script/bootstrap
136
script/bootstrap
@@ -1,136 +0,0 @@
|
|||||||
#!/bin/sh
|
|
||||||
# script/bootstrap: install all dependencies needed to build and develop
|
|
||||||
# this repo. Idempotent: every install is guarded by a check so already
|
|
||||||
# installed tools are skipped. Base tooling comes from nix, apt, brew,
|
|
||||||
# or apk (detected in that order); assumes nothing is present. Node is
|
|
||||||
# used directly if installed; otherwise it is installed at a pinned
|
|
||||||
# version via nvm (installing nvm itself first, from a hash-verified
|
|
||||||
# release archive, never curl | sh).
|
|
||||||
set -eu
|
|
||||||
|
|
||||||
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
|
|
||||||
|
|
||||||
# Pinned versions, 2026-07-06
|
|
||||||
NODE_VERSION="22.17.0"
|
|
||||||
NVM_VERSION="0.40.3"
|
|
||||||
# sha256 of https://github.com/nvm-sh/nvm/archive/refs/tags/v0.40.3.tar.gz
|
|
||||||
NVM_SHA256="5f4d6aaa04a177dc93c985e31dbc411ab6b8c6e1e21d8015dbc1372625fcd1d0"
|
|
||||||
YARN_VERSION="1.22.22"
|
|
||||||
|
|
||||||
PKGMGR=""
|
|
||||||
SUDO=""
|
|
||||||
|
|
||||||
detect_pkgmgr() {
|
|
||||||
[ -n "$PKGMGR" ] && return 0
|
|
||||||
if command -v nix-env >/dev/null 2>&1; then
|
|
||||||
PKGMGR="nix"
|
|
||||||
elif command -v apt-get >/dev/null 2>&1; then
|
|
||||||
PKGMGR="apt"
|
|
||||||
elif command -v brew >/dev/null 2>&1; then
|
|
||||||
PKGMGR="brew"
|
|
||||||
elif command -v apk >/dev/null 2>&1; then
|
|
||||||
PKGMGR="apk"
|
|
||||||
else
|
|
||||||
echo "bootstrap: no supported package manager (nix, apt, brew, apk)" >&2
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
if [ "$PKGMGR" = "apt" ]; then
|
|
||||||
export DEBIAN_FRONTEND=noninteractive
|
|
||||||
if [ "$(id -u)" != "0" ]; then
|
|
||||||
SUDO="sudo"
|
|
||||||
fi
|
|
||||||
fi
|
|
||||||
}
|
|
||||||
|
|
||||||
# pkg_install <nix-attr> <apt-pkg> <brew-formula> <apk-pkg>
|
|
||||||
pkg_install() {
|
|
||||||
detect_pkgmgr
|
|
||||||
case "$PKGMGR" in
|
|
||||||
nix) nix-env -iA "nixpkgs.$1" ;;
|
|
||||||
apt) $SUDO env DEBIAN_FRONTEND=noninteractive apt-get install -y "$2" ;;
|
|
||||||
brew) brew install "$3" ;;
|
|
||||||
apk) apk add --no-cache "$4" ;;
|
|
||||||
esac
|
|
||||||
}
|
|
||||||
|
|
||||||
missing() {
|
|
||||||
! command -v "$1" >/dev/null 2>&1
|
|
||||||
}
|
|
||||||
|
|
||||||
# verify_sha256 <file> <expected-hash>
|
|
||||||
verify_sha256() {
|
|
||||||
if command -v sha256sum >/dev/null 2>&1; then
|
|
||||||
actual="$(sha256sum "$1" | cut -d' ' -f1)"
|
|
||||||
else
|
|
||||||
actual="$(shasum -a 256 "$1" | cut -d' ' -f1)"
|
|
||||||
fi
|
|
||||||
if [ "$actual" != "$2" ]; then
|
|
||||||
echo "bootstrap: sha256 mismatch for $1" >&2
|
|
||||||
echo " expected: $2" >&2
|
|
||||||
echo " actual: $actual" >&2
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
}
|
|
||||||
|
|
||||||
# nvm is a bash script; run a command in a bash with nvm loaded
|
|
||||||
nvm_sh() {
|
|
||||||
bash -c ". \"\$HOME/.nvm/nvm.sh\" && $*"
|
|
||||||
}
|
|
||||||
|
|
||||||
ensure_nvm() {
|
|
||||||
[ -s "$HOME/.nvm/nvm.sh" ] && return 0
|
|
||||||
# nvm prerequisites; nvm itself requires bash
|
|
||||||
if missing bash; then pkg_install bash bash bash bash; fi
|
|
||||||
if missing curl; then pkg_install curl curl curl curl; fi
|
|
||||||
if missing git; then pkg_install git git git git; fi
|
|
||||||
tmp="$(mktemp -d)"
|
|
||||||
curl -fsSL -o "$tmp/nvm.tar.gz" \
|
|
||||||
"https://github.com/nvm-sh/nvm/archive/refs/tags/v${NVM_VERSION}.tar.gz"
|
|
||||||
verify_sha256 "$tmp/nvm.tar.gz" "$NVM_SHA256"
|
|
||||||
mkdir -p "$HOME/.nvm"
|
|
||||||
tar -xzf "$tmp/nvm.tar.gz" -C "$HOME/.nvm" --strip-components=1
|
|
||||||
rm -rf "$tmp"
|
|
||||||
}
|
|
||||||
|
|
||||||
ensure_node() {
|
|
||||||
if ! missing node; then return 0; fi
|
|
||||||
ensure_nvm
|
|
||||||
nvm_sh "nvm install $NODE_VERSION"
|
|
||||||
}
|
|
||||||
|
|
||||||
ensure_yarn() {
|
|
||||||
if ! missing yarn; then return 0; fi
|
|
||||||
if ! missing corepack; then
|
|
||||||
corepack enable
|
|
||||||
corepack prepare "yarn@$YARN_VERSION" --activate
|
|
||||||
elif [ -s "$HOME/.nvm/nvm.sh" ]; then
|
|
||||||
nvm_sh "nvm use $NODE_VERSION >/dev/null && corepack enable && \
|
|
||||||
corepack prepare yarn@$YARN_VERSION --activate"
|
|
||||||
else
|
|
||||||
npm install -g "yarn@$YARN_VERSION"
|
|
||||||
fi
|
|
||||||
}
|
|
||||||
|
|
||||||
install_js_deps() {
|
|
||||||
if missing yarn && [ -s "$HOME/.nvm/nvm.sh" ]; then
|
|
||||||
nvm_sh "nvm use $NODE_VERSION >/dev/null && cd \"$ROOT\" && \
|
|
||||||
yarn install --frozen-lockfile"
|
|
||||||
else
|
|
||||||
yarn install --frozen-lockfile
|
|
||||||
fi
|
|
||||||
}
|
|
||||||
|
|
||||||
main() {
|
|
||||||
cd "$ROOT"
|
|
||||||
|
|
||||||
if missing make; then pkg_install gnumake make make make; fi
|
|
||||||
if missing git; then pkg_install git git git git; fi
|
|
||||||
|
|
||||||
ensure_node
|
|
||||||
ensure_yarn
|
|
||||||
install_js_deps
|
|
||||||
|
|
||||||
echo "bootstrap complete"
|
|
||||||
}
|
|
||||||
|
|
||||||
main "$@"
|
|
||||||
14
script/check
14
script/check
@@ -1,14 +0,0 @@
|
|||||||
#!/bin/sh
|
|
||||||
# script/check: run all checks (test, lint, fmt-check). Our own
|
|
||||||
# extension to scripts-to-rule-them-all. Must not modify any files.
|
|
||||||
set -eu
|
|
||||||
|
|
||||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
|
|
||||||
|
|
||||||
main() {
|
|
||||||
"$SCRIPT_DIR/test"
|
|
||||||
"$SCRIPT_DIR/lint"
|
|
||||||
"$SCRIPT_DIR/fmt-check"
|
|
||||||
}
|
|
||||||
|
|
||||||
main "$@"
|
|
||||||
@@ -1,28 +0,0 @@
|
|||||||
#!/bin/sh
|
|
||||||
# script/cibuild: run the CI build. The Dockerfile runs script/check, but
|
|
||||||
# that only proves anything because CHECK_EPOCH is a fresh nonce on every
|
|
||||||
# invocation: without it Docker serves the check layer from cache and the
|
|
||||||
# build exits 0 without running the suite.
|
|
||||||
set -eu
|
|
||||||
|
|
||||||
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
|
|
||||||
|
|
||||||
main() {
|
|
||||||
cd "$ROOT"
|
|
||||||
# Both assignments on their own line: a failing command substitution
|
|
||||||
# inside an argument does not trip `set -e`, so the inline form
|
|
||||||
# degrades silently to an empty constant. `$$` because busybox `date`
|
|
||||||
# drops %N without erroring. VERSION is computed here because
|
|
||||||
# .dockerignore excludes .git, so `git describe` in a build stage
|
|
||||||
# yields an empty version without failing; the guard below is the
|
|
||||||
# single place the fallback is applied.
|
|
||||||
epoch="$(date +%s%N)$$"
|
|
||||||
version="$(git describe --tags --always --dirty 2>/dev/null || true)"
|
|
||||||
[ -n "$version" ] || version="unknown"
|
|
||||||
docker build \
|
|
||||||
--build-arg CHECK_EPOCH="$epoch" \
|
|
||||||
--build-arg VERSION="$version" \
|
|
||||||
.
|
|
||||||
}
|
|
||||||
|
|
||||||
main "$@"
|
|
||||||
@@ -1,29 +0,0 @@
|
|||||||
#!/bin/sh
|
|
||||||
# script/docker: build the Docker image tagged with the project name.
|
|
||||||
# Identical in all repos; the tag comes from script/projectname. The
|
|
||||||
# Dockerfile's checks only actually run because CHECK_EPOCH is a fresh
|
|
||||||
# nonce on every invocation; without it a warm cache turns this into a
|
|
||||||
# green that proves nothing.
|
|
||||||
set -eu
|
|
||||||
|
|
||||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
|
|
||||||
ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
|
|
||||||
|
|
||||||
main() {
|
|
||||||
cd "$ROOT"
|
|
||||||
# Both assignments on their own line: a failing command substitution
|
|
||||||
# inside an argument does not trip `set -e`, so the inline form
|
|
||||||
# degrades silently to an empty constant. `$$` because busybox `date`
|
|
||||||
# drops %N without erroring. VERSION is computed here because
|
|
||||||
# .dockerignore excludes .git, so `git describe` in a build stage
|
|
||||||
# yields an empty version without failing.
|
|
||||||
epoch="$(date +%s%N)$$"
|
|
||||||
version="$(git describe --tags --always --dirty 2>/dev/null || true)"
|
|
||||||
[ -n "$version" ] || version="unknown"
|
|
||||||
docker build \
|
|
||||||
--build-arg CHECK_EPOCH="$epoch" \
|
|
||||||
--build-arg VERSION="$version" \
|
|
||||||
-t "$("$SCRIPT_DIR/projectname")" .
|
|
||||||
}
|
|
||||||
|
|
||||||
main "$@"
|
|
||||||
12
script/fmt
12
script/fmt
@@ -1,12 +0,0 @@
|
|||||||
#!/bin/sh
|
|
||||||
# script/fmt: format all files (writes).
|
|
||||||
set -eu
|
|
||||||
|
|
||||||
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
|
|
||||||
|
|
||||||
main() {
|
|
||||||
cd "$ROOT"
|
|
||||||
yarn run prettier --write '**/*.md' --tab-width 4 --prose-wrap always
|
|
||||||
}
|
|
||||||
|
|
||||||
main "$@"
|
|
||||||
@@ -1,12 +0,0 @@
|
|||||||
#!/bin/sh
|
|
||||||
# script/fmt-check: check formatting (read-only).
|
|
||||||
set -eu
|
|
||||||
|
|
||||||
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
|
|
||||||
|
|
||||||
main() {
|
|
||||||
cd "$ROOT"
|
|
||||||
yarn run prettier --check '**/*.md' --tab-width 4 --prose-wrap always
|
|
||||||
}
|
|
||||||
|
|
||||||
main "$@"
|
|
||||||
@@ -1,16 +0,0 @@
|
|||||||
#!/bin/sh
|
|
||||||
# script/install-precommit: install the git pre-commit hook that runs
|
|
||||||
# script/precommit. Our own extension to scripts-to-rule-them-all.
|
|
||||||
set -eu
|
|
||||||
|
|
||||||
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
|
|
||||||
|
|
||||||
main() {
|
|
||||||
cd "$ROOT"
|
|
||||||
hook=".git/hooks/pre-commit"
|
|
||||||
printf '#!/bin/sh\nset -e\nscript/precommit\n' > .git/hooks/pre-commit
|
|
||||||
chmod +x .git/hooks/pre-commit
|
|
||||||
echo "pre-commit hook installed: runs script/precommit"
|
|
||||||
}
|
|
||||||
|
|
||||||
main "$@"
|
|
||||||
34
script/lint
34
script/lint
@@ -1,34 +0,0 @@
|
|||||||
#!/bin/sh
|
|
||||||
# script/lint: run the linter. Inside a container, run it directly;
|
|
||||||
# on a host, build Dockerfile.lint so it runs in one anyway. The linter
|
|
||||||
# is never run on a developer host, where a shared result cache, a
|
|
||||||
# host-global lock and a stale toolchain make its answer untrustworthy.
|
|
||||||
#
|
|
||||||
# LINT_IN_CONTAINER is set by this repo's Dockerfiles and is the ONLY
|
|
||||||
# accepted signal. Do not add a /.dockerenv fallback: it is absent
|
|
||||||
# inside BuildKit RUN steps and present on hosts that are themselves
|
|
||||||
# containers, so it both misses and false-positives — and a false
|
|
||||||
# positive silently restores host linting.
|
|
||||||
set -eu
|
|
||||||
|
|
||||||
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
|
|
||||||
|
|
||||||
main() {
|
|
||||||
cd "$ROOT"
|
|
||||||
|
|
||||||
if [ "${LINT_IN_CONTAINER:-}" = "1" ]; then
|
|
||||||
exec yarn run prettier --check '**/*.md' \
|
|
||||||
--tab-width 4 --prose-wrap always
|
|
||||||
fi
|
|
||||||
|
|
||||||
# Own line, and `$$` because busybox `date` drops %N silently.
|
|
||||||
# Without a fresh nonce the lint layer is cached and this exits 0
|
|
||||||
# having linted nothing.
|
|
||||||
epoch="$(date +%s%N)$$"
|
|
||||||
docker build \
|
|
||||||
--build-arg CHECK_EPOCH="$epoch" \
|
|
||||||
-f Dockerfile.lint \
|
|
||||||
.
|
|
||||||
}
|
|
||||||
|
|
||||||
main "$@"
|
|
||||||
@@ -1,12 +0,0 @@
|
|||||||
#!/bin/sh
|
|
||||||
# script/precommit: run by the git pre-commit hook; fails the commit if
|
|
||||||
# checks fail. Our own extension to scripts-to-rule-them-all.
|
|
||||||
set -eu
|
|
||||||
|
|
||||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
|
|
||||||
|
|
||||||
main() {
|
|
||||||
"$SCRIPT_DIR/check"
|
|
||||||
}
|
|
||||||
|
|
||||||
main "$@"
|
|
||||||
@@ -1,12 +0,0 @@
|
|||||||
#!/bin/sh
|
|
||||||
# script/projectname: output the name of this project. Our own
|
|
||||||
# extension to scripts-to-rule-them-all. Other scripts that need the
|
|
||||||
# name (e.g. script/docker) call this, so they can stay identical
|
|
||||||
# across all repos.
|
|
||||||
set -eu
|
|
||||||
|
|
||||||
main() {
|
|
||||||
echo "prompts"
|
|
||||||
}
|
|
||||||
|
|
||||||
main "$@"
|
|
||||||
13
script/setup
13
script/setup
@@ -1,13 +0,0 @@
|
|||||||
#!/bin/sh
|
|
||||||
# script/setup: set up the repo for development after a fresh clone:
|
|
||||||
# installs dependencies and the git pre-commit hook.
|
|
||||||
set -eu
|
|
||||||
|
|
||||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
|
|
||||||
|
|
||||||
main() {
|
|
||||||
"$SCRIPT_DIR/bootstrap"
|
|
||||||
"$SCRIPT_DIR/install-precommit"
|
|
||||||
}
|
|
||||||
|
|
||||||
main "$@"
|
|
||||||
12
script/test
12
script/test
@@ -1,12 +0,0 @@
|
|||||||
#!/bin/sh
|
|
||||||
# script/test: run the test suite.
|
|
||||||
set -eu
|
|
||||||
|
|
||||||
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
|
|
||||||
|
|
||||||
main() {
|
|
||||||
cd "$ROOT"
|
|
||||||
echo "No tests defined."
|
|
||||||
}
|
|
||||||
|
|
||||||
main "$@"
|
|
||||||
Reference in New Issue
Block a user