bdeshiandClaude Opus 5
ec6e9838f0
docs/content-model.md opens with "Engine specification". It is also where the rule lives that a leading underscore makes a file unaddressable — and the human who owns this site did not know that rule, because nothing in this repository is addressed to an author. Twelve documents named docs/ while being exclusively about building the parser is a signpost pointing at the wrong room. Naming the directory for its audience makes the gap visible instead of hiding it. docs/ is now reserved and deliberately absent: an empty docs/ is an honest statement that end-user documentation does not exist, where docs/ full of parser specs was a claim that it did. HARNESS.md stays at the root. Root holds the three entry points — README.md for a human, CLAUDE.md for an agent, HARNESS.md for whoever maintains the machine — and harness/README.md is the map of the directory, so moving the guide inside would have collided with it for nothing. Mechanical and wide: 100 path references across 24 files. Every verify.sh gate that names a doc by path, the directory lists the dangling-path and ADR-number gates scan, surface.sh's output target, the Makefile, CLAUDE.md's read order, the skill, four commands, and two Go package comments. A first pass with a shell loop silently edited only four files and the rest still said docs/; the fix was to write the file list out and check the remaining count was zero rather than trust the loop's exit status. No rule, threshold, gate or obligation moved — this is a rename, and the gates demonstrated it twice: they stayed green on the new paths, and the ADR-number gate caught ADR-0082 before the entry existed. Deferred, both on the human's call: the end-user documentation site itself, which wants its own decision about where it lives and whether its claims are gated; and moving examples/ under docs/, since demo-site is a live site root that verify.sh, the coverage test and make demo all point at, and moving it would couple a rename to a design nobody has made. 31 files, +146/-106. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
52 lines
1.7 KiB
Makefile
52 lines
1.7 KiB
Makefile
# Convenience only. `go build`, `go test` and ./scripts/verify.sh are the ground truth — nothing here
|
|
# is required to work on khosra, and the gate never invokes make.
|
|
|
|
SITE ?= $(KHOSRA_SITE)
|
|
ADDR ?= localhost:8080
|
|
BIN := ./khosra
|
|
|
|
.PHONY: help build run check new demo test verify quiet surface fmt tidy clean
|
|
|
|
help: ## list targets
|
|
@grep -hE '^[a-z]+:.*##' $(MAKEFILE_LIST) | sed 's/:[^#]*## /|/' | column -t -s '|'
|
|
|
|
build: ## compile the binary
|
|
go build -o $(BIN) ./cmd/khosra
|
|
|
|
run: build ## serve a site root: make run SITE=/path/to/site
|
|
@test -n "$(SITE)" || { echo "set SITE=/path/to/site, or export KHOSRA_SITE"; exit 1; }
|
|
$(BIN) -site "$(SITE)" -addr "$(ADDR)"
|
|
|
|
check: build ## validate a site root's content: make check SITE=/path/to/site
|
|
@test -n "$(SITE)" || { echo "set SITE=/path/to/site, or export KHOSRA_SITE"; exit 1; }
|
|
$(BIN) check -site "$(SITE)"
|
|
|
|
new: build ## scaffold a bundle: make new KEY=posts/hello-world SITE=/path/to/site
|
|
@test -n "$(SITE)" || { echo "set SITE=/path/to/site, or export KHOSRA_SITE"; exit 1; }
|
|
@test -n "$(KEY)" || { echo "set KEY=posts/hello-world"; exit 1; }
|
|
$(BIN) new -site "$(SITE)" "$(KEY)"
|
|
|
|
demo: build ## serve the demo site in examples/, which exercises every feature
|
|
$(BIN) -site examples/demo-site -addr "$(ADDR)"
|
|
|
|
test: ## run tests with the race detector
|
|
go test -race ./...
|
|
|
|
verify: ## everything the harness enforces; must be green before a commit
|
|
./scripts/verify.sh
|
|
|
|
quiet: ## the same gates, printing only what needs acting on
|
|
./scripts/verify.sh --quiet
|
|
|
|
surface: ## regenerate harness/surface.md, the compressed map of the code
|
|
./scripts/surface.sh --write
|
|
|
|
fmt: ## format all Go source
|
|
gofmt -w .
|
|
|
|
tidy: ## tidy go.mod
|
|
go mod tidy
|
|
|
|
clean: ## remove build output
|
|
rm -f $(BIN)
|