Compare commits
4 Commits
33fb5dde98
...
llm-prose-
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
73099520ca | ||
|
|
1c70757fb9 | ||
|
|
6438ed22d3 | ||
|
|
d38c1295e9 |
@@ -1,97 +1,3 @@
|
|||||||
# Docker matches this file with moby/patternmatcher: Go filepath.Match
|
|
||||||
# semantics plus a `**` extension, compiled to a regexp. Plain
|
|
||||||
# filepath.Match has no `**` at all. What follows from that: `*` does not
|
|
||||||
# cross `/`, and a pattern without a leading `**/` is anchored at the
|
|
||||||
# build-context root. Every depth-independent pattern therefore needs the
|
|
||||||
# `**/` prefix — without it `config/.env` and `certs/server.key` still
|
|
||||||
# ship while the file reads as solved.
|
|
||||||
#
|
|
||||||
# Root-anchored entries are for paths that occur exactly once, at the
|
|
||||||
# context root. A host-built binary is the usual case, and it must be
|
|
||||||
# written anchored: `/myapp`, never `**/myapp`. The prefixed form also
|
|
||||||
# matches `cmd/myapp/`, which deletes the package directory from the
|
|
||||||
# context. In-repo agent scratch is the other case, for the same reason
|
|
||||||
# — with the caveat recorded at that entry: anchoring is exact only
|
|
||||||
# where agents run at the repo root, and a repo where they do not must
|
|
||||||
# add its own entries.
|
|
||||||
#
|
|
||||||
# Matching is case-sensitive, so `**/*.key` does not match
|
|
||||||
# `certs/SERVER.KEY`, which is reachable on the case-insensitive
|
|
||||||
# filesystems most laptops use. Adding an ALL-CAPS twin per pattern is
|
|
||||||
# not the fix: it still misses `Server.Key` while reading as though case
|
|
||||||
# were handled. Character ranges cover every spelling in one line, so
|
|
||||||
# every secret name below is written that way — including the
|
|
||||||
# extensionless SSH keys and `.envrc`, because on those same
|
|
||||||
# case-insensitive filesystems direnv reads `.ENVRC` and ssh reads
|
|
||||||
# `ID_RSA`.
|
|
||||||
#
|
|
||||||
# `**/*.[eE][nN][vV]` also excludes a committed env template such as
|
|
||||||
# `example.env`. If the build genuinely needs one, re-include it with a
|
|
||||||
# negation after the pattern: `!docs/example.env`.
|
|
||||||
#
|
|
||||||
# Extend this file with the repo's own host-built artifacts (compiled
|
|
||||||
# binaries, test binaries, coverage output); those are per-repo and
|
|
||||||
# belong here because a host build otherwise drops them into the
|
|
||||||
# context.
|
|
||||||
|
|
||||||
# Repository metadata: exactly one, at the context root. Excluding it
|
|
||||||
# means `git describe` cannot run in any build stage, and it fails
|
|
||||||
# quietly there rather than erroring, so a version embedded that way
|
|
||||||
# comes out empty. Compute the version on the host and pass it in with
|
|
||||||
# `--build-arg VERSION=...`; see the version rule in REPO_POLICIES.md.
|
|
||||||
.git
|
.git
|
||||||
|
node_modules
|
||||||
# In-repo agent scratch: a directory holding a full additional checkout
|
.DS_Store
|
||||||
# of the repo for each in-flight agent. Anchored because it occurs
|
|
||||||
# exactly once *where agents run at the repo root*, which is the
|
|
||||||
# convention this file assumes; the `**/` form would also match any
|
|
||||||
# nested directory of that name and delete it from the build.
|
|
||||||
#
|
|
||||||
# KNOWN GAP, and it is not hypothetical: the directory is created in the
|
|
||||||
# agent's working directory. If agents in this repo run in
|
|
||||||
# subdirectories — a monorepo with a per-service agent, say — then
|
|
||||||
# `services/api/.claude/` is NOT excluded by the line below and still
|
|
||||||
# reaches the build context and the image, which is the exposure this
|
|
||||||
# entry exists to close. A repo in that shape adds its own anchored
|
|
||||||
# entries (`/services/api/.claude`), or `**/.claude` after confirming no
|
|
||||||
# legitimately named nested directory would be caught.
|
|
||||||
#
|
|
||||||
# Not case-folded, unlike the secret patterns below: tooling creates
|
|
||||||
# this directory in exactly one spelling, so a folded pattern would add
|
|
||||||
# no coverage.
|
|
||||||
.claude
|
|
||||||
|
|
||||||
# Environment files. `*.env` covers both the bare `.env` name (`*` matches
|
|
||||||
# the empty string) and the `prod.env` convention.
|
|
||||||
**/*.[eE][nN][vV]
|
|
||||||
**/.[eE][nN][vV].*
|
|
||||||
**/.[eE][nN][vV][rR][cC]
|
|
||||||
|
|
||||||
# Private keys and the bundles that carry them. Public certificates
|
|
||||||
# (*.crt, *.cer) are deliberately absent: they are not secrets and are
|
|
||||||
# sometimes a legitimate build input.
|
|
||||||
**/*.[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 under a developer's
|
|
||||||
# hands, so it invalidates COPY for reasons unrelated to the source.
|
|
||||||
**/*.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
|
||||||
|
|
||||||
# script/bootstrap installs all prerequisites (make via apk here; node
|
|
||||||
# and yarn are already in the base image, so those steps are skipped).
|
|
||||||
# Dependency manifests are copied first so the bootstrap layer is
|
|
||||||
# cached until they 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 supplied by 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 it must be redeclared in every stage that runs checks. The guard
|
|
||||||
# makes a bare `docker build .` fail loudly instead of silently reusing
|
|
||||||
# the empty (and therefore stable) cache key. Expand the value into the
|
|
||||||
# command so the cache miss does not depend on BuildKit's handling of an
|
|
||||||
# unreferenced ARG. Both the guard and the check RUN reference the value,
|
|
||||||
# so both are value-keyed: there are two independent invalidation points
|
|
||||||
# here, not one. Keep both.
|
|
||||||
ARG CHECK_EPOCH
|
|
||||||
RUN [ -n "$CHECK_EPOCH" ] || exit 1
|
|
||||||
RUN echo "check epoch: ${CHECK_EPOCH}" && make check
|
|
||||||
|
|||||||
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
|
||||||
|
|||||||
35
README.md
35
README.md
@@ -102,41 +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
|
|
||||||
- `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
|
||||||
|
|||||||
137
TODO.md
137
TODO.md
@@ -1,137 +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-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-09
|
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-09
|
|||||||
```
|
```
|
||||||
|
|
||||||
```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)
|
||||||
@@ -114,16 +101,9 @@ last_modified: 2026-08-09
|
|||||||
`golangci-lint`.
|
`golangci-lint`.
|
||||||
|
|
||||||
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)
|
||||||
@@ -156,15 +136,8 @@ last_modified: 2026-08-09
|
|||||||
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.
|
||||||
|
|
||||||
@@ -176,15 +149,9 @@ last_modified: 2026-08-09
|
|||||||
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-09
|
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,57 +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.
|
|
||||||
- [ ] `.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:
|
||||||
@@ -87,26 +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
|
|
||||||
- [ ] Go: `script/lint` isolates golangci-lint per checkout —
|
|
||||||
`GOLANGCI_LINT_CACHE` and `TMPDIR` both exported into `.lint-cache/`
|
|
||||||
(which is in `.gitignore` and `.dockerignore`), `--allow-serial-runners`
|
|
||||||
passed, and the lock error retried rather than reported as findings. Copy
|
|
||||||
the canonical block from `REPO_POLICIES.md`. Setting only the cache is the
|
|
||||||
common half-fix and leaves `parallel golangci-lint is running` failing
|
|
||||||
runs red.
|
|
||||||
- [ ] `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
|
||||||
@@ -134,25 +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
|
||||||
- [ ] `script/cibuild` succeeds (a bare `docker build .` fails closed by design,
|
- [ ] `docker build` succeeds
|
||||||
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,7 @@
|
|||||||
# LLM Prose Tells
|
# LLM Prose Tells
|
||||||
|
|
||||||
A catalog of patterns found in LLM-generated prose.
|
Human writers occasionally use every pattern in this document. The reason they
|
||||||
|
work as tells is that LLM output packs fifteen of them into a paragraph.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -13,11 +14,17 @@ 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 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. A human writer might use one or two in a
|
||||||
|
piece. Models scatter them everywhere because the em-dash can stand in for any
|
||||||
|
other punctuation mark. More than two or three per page is a signal.
|
||||||
|
|
||||||
### The Colon Elaboration
|
### The Colon Elaboration
|
||||||
|
|
||||||
@@ -25,25 +32,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.
|
||||||
|
|
||||||
### The Two-Clause Compound Sentence
|
### The Two-Clause Compound Sentence
|
||||||
|
|
||||||
An independent clause, a comma, a conjunction ("and," "but," "which,"
|
Possibly the most pervasive tell, and easy to miss because each individual
|
||||||
"because"), and a second independent clause of similar length. Every sentence
|
instance looks like normal English. The model produces sentence after sentence
|
||||||
becomes two balanced halves.
|
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.
|
||||||
|
|
||||||
> "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,44 +68,49 @@ 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.
|
||||||
|
|
||||||
### 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 a piece. If the first paragraph has four sentences, every
|
||||||
every subsequent paragraph will too.
|
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.
|
||||||
|
|
||||||
### 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 essay is a reasonable
|
||||||
> "Full stop." "Let that sink in."
|
stylistic choice, but models drop them in once per section or more.
|
||||||
|
|
||||||
### 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.
|
||||||
|
|
||||||
### 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."
|
||||||
|
|
||||||
> "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
|
||||||
|
|
||||||
@@ -100,15 +120,19 @@ Models keep going after the sentence has already made its point.
|
|||||||
> 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. 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 +140,43 @@ 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 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 high
|
||||||
|
density in model-generated analytical prose. It's a micro-hedge, diagnostic in
|
||||||
|
volume.
|
||||||
|
|
||||||
### "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.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -158,20 +187,23 @@ 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.
|
||||||
|
|
||||||
### 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.
|
||||||
|
|
||||||
### 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 +224,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.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -206,28 +240,33 @@ 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.
|
||||||
|
|
||||||
### 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.
|
||||||
|
|
||||||
### 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 doesn't do this.
|
||||||
|
|
||||||
### 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.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -237,27 +276,42 @@ 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.
|
||||||
|
|
||||||
### "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.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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. 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 +325,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 +334,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 +343,105 @@ 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. Read every clause, phrase, and adjective
|
||||||
in each sentence and ask whether the sentence loses meaning without it. If
|
in each sentence and ask whether the sentence loses meaning without it. This
|
||||||
you can cut it and the sentence still says the same thing, cut it.
|
includes trailing clauses that restate what the sentence already said,
|
||||||
|
redundant modifiers ("a single paragraph" when "a paragraph" works),
|
||||||
|
secondary clauses that add nothing ("which is why this matters"), and any
|
||||||
|
words whose removal doesn't change the meaning. If you can cut it and the
|
||||||
|
sentence still says the same thing, 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 +488,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-09
|
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,34 +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.
|
|
||||||
- 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
|
||||||
- [ ] 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
|
||||||
@@ -91,72 +65,15 @@ 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 linter
|
|
||||||
- [ ] Go: exports `GOLANGCI_LINT_CACHE` **and** `TMPDIR` into a
|
|
||||||
`.lint-cache/` directory inside the checkout, above any
|
|
||||||
container-versus-host branch so every path that reaches the linter
|
|
||||||
gets them; passes `--allow-serial-runners` (never
|
|
||||||
`--allow-parallel-runners`); retries on
|
|
||||||
`parallel golangci-lint is running` detected on **stderr** and exits
|
|
||||||
75 with a VOID message on exhaustion. Copy the canonical block from
|
|
||||||
`REPO_POLICIES.md` rather than writing your own: a version that sets
|
|
||||||
only the cache leaves the false-red half live, and one that detects
|
|
||||||
the collision by exit status can retry a real finding away.
|
|
||||||
- [ ] Go: `.lint-cache/` is in both `.gitignore` and `.dockerignore`
|
|
||||||
- [ ] `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.
|
|
||||||
|
|
||||||
- [ ] `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
|
||||||
|
|
||||||
|
|||||||
File diff suppressed because it is too large
Load Diff
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,33 +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 on an
|
|
||||||
# unchanged tree and the build exits 0 without running the suite.
|
|
||||||
set -eu
|
|
||||||
|
|
||||||
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
|
|
||||||
|
|
||||||
main() {
|
|
||||||
cd "$ROOT"
|
|
||||||
# Assign on its own line: a failing command substitution inside an
|
|
||||||
# argument does not trip `set -e`, which would silently degrade the
|
|
||||||
# nonce to an empty constant. `$$` is required because busybox `date`
|
|
||||||
# drops %N without erroring.
|
|
||||||
epoch="$(date +%s%N)$$"
|
|
||||||
# VERSION must be computed here, on the host: .dockerignore excludes
|
|
||||||
# .git, so `git describe` cannot run in any build stage and fails
|
|
||||||
# quietly there rather than erroring. Same own-line discipline as the
|
|
||||||
# epoch. `|| true` keeps a failing describe from tripping `set -e`
|
|
||||||
# and leaves the value empty; the guard below is then the single
|
|
||||||
# place the fallback is applied, and it does fire — on an export with
|
|
||||||
# no .git, or a repo with no commits yet. `unknown` is visibly wrong
|
|
||||||
# in a binary in a way that an empty version is not.
|
|
||||||
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,35 +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"
|
|
||||||
# Assign on its own line: a failing command substitution inside an
|
|
||||||
# argument does not trip `set -e`, which would silently degrade the
|
|
||||||
# nonce to an empty constant. `$$` is required because busybox `date`
|
|
||||||
# drops %N without erroring.
|
|
||||||
epoch="$(date +%s%N)$$"
|
|
||||||
# VERSION must be computed here, on the host: .dockerignore excludes
|
|
||||||
# .git, so `git describe` cannot run in any build stage and fails
|
|
||||||
# quietly there rather than erroring. Same own-line discipline as the
|
|
||||||
# epoch. `|| true` keeps a failing describe from tripping `set -e`
|
|
||||||
# and leaves the value empty; the guard below is then the single
|
|
||||||
# place the fallback is applied, and it does fire — on an export with
|
|
||||||
# no .git, or a repo with no commits yet. `unknown` is visibly wrong
|
|
||||||
# in a binary in a way that an empty version is not.
|
|
||||||
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 "$@"
|
|
||||||
13
script/lint
13
script/lint
@@ -1,13 +0,0 @@
|
|||||||
#!/bin/sh
|
|
||||||
# script/lint: run the linter.
|
|
||||||
set -eu
|
|
||||||
|
|
||||||
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
|
|
||||||
|
|
||||||
main() {
|
|
||||||
cd "$ROOT"
|
|
||||||
echo "Linting markdown files..."
|
|
||||||
yarn run prettier --check '**/*.md' --tab-width 4 --prose-wrap always
|
|
||||||
}
|
|
||||||
|
|
||||||
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