refactor(kdl-specs)!: rename `specgen` -> kdl-specs / kdl_specs / kdlspecs (package, command, docs) #174

New issue

Closed

opened 2026-06-26 16:32:23 +00:00 by coilysiren · 2 comments

coilysiren commented

2026-06-26 16:32:23 +00:00

Owner

Goal

Rename the build-time generator specgen to the kdl-specs family, applying the right casing per context (the maintainer's "depending on text" rule):

kdlspecs - Go package name + import-path segment (Go package names are flat lowercase, no hyphen/underscore). package specgen -> package kdlspecs; dir http/specgen/ -> http/kdlspecs/; import paths updated everywhere.
kdl-specs - the CLI command / binary name and ALL prose, docs, and user-facing messages. cmd/specgen/ -> cmd/kdl-specs/; help text and the ErrNoLock / ErrSkew strings ("run 'specgen lock'" -> "run 'kdl-specs lock'"); docs/specgen.md -> docs/kdl-specs.md; mkdocs nav refs.
kdl_specs - snake_case ONLY where the surrounding text is already snake (a generated identifier, a lock-file field key, a make var, a test-fixture name). Apply by context; if nothing snake exists, this form may not appear, which is fine.

Why

specgen was just unified under that prefix (#164, commit 4afbbe5) but the name does not say what it generates - the artifact is the KDL spec surface, so kdl-specs is the speaking name.

Scope (verified - the literal `specgen` appears in ~18 files)

Go: http/specgen/specgen.go (package + dir), cmd/specgen/main.go (package main + command doc-comment + dir), http/specgen/codegen/*.go, http/specgen/cache.go, http/specgen/deplock.go, http/specgen/exec_unix.go, http/specgen/exec_other.go, http/specverb/prune.go, plus the _test.go peers. Update package name, every import of the path segment, and the literal specgen in comments/messages.
Docs: rename docs/specgen.md -> docs/kdl-specs.md; update refs in docs/specverb.md, docs/specverb-describe.md, docs/specverb-mixed-transports.md, docs/execverb.md, docs/FEATURES.md, and the mkdocs.yml nav.
Any Make target or ward verb that invokes specgen.

Keep CI green (the freshness gate)

Regenerate godoc-current.txt via ./scripts/check-godoc-current.sh --update - the package rename changes every ## <pkg> heading, and the godoc-current.txt up to date CI step (.forgejo/workflows/ci.yml) fails on drift.
go mod tidy (CI does git diff --exit-code on go.mod/go.sum), then go build ./... && go vet ./... && go test -race ./... and golangci-lint run all green.
Land as a breaking refactor(kdl-specs)!: commit (the import path changes), matching house style (see ba21df3, 4afbbe5).

Acceptance

No remaining specgen literal in code or docs (grep -rl specgen clean except historical commit/changelog references).
Go package is kdlspecs, the command is kdl-specs, docs/prose read kdl-specs, any snake contexts read kdl_specs.
Full CI green, including godoc-current freshness and go mod tidy.

Files

The grep inventory above. Do this first - the keyword-index feature (#175) should land on the renamed surface, or rebase onto it.

When done

Run the gate, commit, push to canonical main, update docs/FEATURES.md, and comment on #175 that the renamed surface is available.

## Goal Rename the build-time generator `specgen` to the **kdl-specs** family, applying the right casing per context (the maintainer's "depending on text" rule): - **`kdlspecs`** - Go package name + import-path segment (Go package names are flat lowercase, no hyphen/underscore). `package specgen` -> `package kdlspecs`; dir `http/specgen/` -> `http/kdlspecs/`; import paths updated everywhere. - **`kdl-specs`** - the CLI command / binary name and ALL prose, docs, and user-facing messages. `cmd/specgen/` -> `cmd/kdl-specs/`; help text and the `ErrNoLock` / `ErrSkew` strings ("run 'specgen lock'" -> "run 'kdl-specs lock'"); `docs/specgen.md` -> `docs/kdl-specs.md`; mkdocs nav refs. - **`kdl_specs`** - snake_case ONLY where the surrounding text is already snake (a generated identifier, a lock-file field key, a make var, a test-fixture name). Apply by context; if nothing snake exists, this form may not appear, which is fine. ## Why `specgen` was just unified under that prefix (#164, commit 4afbbe5) but the name does not say what it generates - the artifact is the **KDL spec surface**, so kdl-specs is the speaking name. ## Scope (verified - the literal `specgen` appears in ~18 files) - **Go:** `http/specgen/specgen.go` (package + dir), `cmd/specgen/main.go` (package main + command doc-comment + dir), `http/specgen/codegen/*.go`, `http/specgen/cache.go`, `http/specgen/deplock.go`, `http/specgen/exec_unix.go`, `http/specgen/exec_other.go`, `http/specverb/prune.go`, plus the `_test.go` peers. Update package name, every import of the path segment, and the literal `specgen` in comments/messages. - **Docs:** rename `docs/specgen.md` -> `docs/kdl-specs.md`; update refs in `docs/specverb.md`, `docs/specverb-describe.md`, `docs/specverb-mixed-transports.md`, `docs/execverb.md`, `docs/FEATURES.md`, and the `mkdocs.yml` nav. - **Any** Make target or ward verb that invokes `specgen`. ## Keep CI green (the freshness gate) - Regenerate `godoc-current.txt` via `./scripts/check-godoc-current.sh --update` - the package rename changes every `## <pkg>` heading, and the `godoc-current.txt up to date` CI step (.forgejo/workflows/ci.yml) fails on drift. - `go mod tidy` (CI does `git diff --exit-code` on go.mod/go.sum), then `go build ./... && go vet ./... && go test -race ./...` and `golangci-lint run` all green. - Land as a breaking `refactor(kdl-specs)!:` commit (the import path changes), matching house style (see ba21df3, 4afbbe5). ## Acceptance - No remaining `specgen` literal in code or docs (`grep -rl specgen` clean except historical commit/changelog references). - Go package is `kdlspecs`, the command is `kdl-specs`, docs/prose read `kdl-specs`, any snake contexts read `kdl_specs`. - Full CI green, including godoc-current freshness and go mod tidy. ## Files The grep inventory above. **Do this first** - the keyword-index feature (#175) should land on the renamed surface, or rebase onto it. ## When done Run the gate, commit, push to canonical `main`, update `docs/FEATURES.md`, and comment on #175 that the renamed surface is available.

coilysiren referenced this issue

2026-06-26 16:32:23 +00:00

feat(docs): auto-generate a flat KDL-keyword index (names-only UL) linking each keyword to its doc page + command entrypoint, freshness-validated #175

coilysiren added the

headless

labels

2026-07-01 04:29:31 +00:00

coilyco-ops commented

2026-07-01 04:45:54 +00:00

Member

🔒 Reserved by ward agent --driver claude — container engineer-claude-cli-guard-174 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-01T04:45:52Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); --force overrides.

— Claude (she/her), via ward agent

🔒 Reserved by `ward agent --driver claude` — container `engineer-claude-cli-guard-174` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-01T04:45:52Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides.  — Claude (she/her), via `ward agent`

coilysiren referenced this issue from a commit

2026-07-01 04:50:33 +00:00

refactor(kdl-specs)!: rename `specgen` -> kdl-specs family

coilysiren closed this issue

2026-07-01 04:50:33 +00:00

coilysiren referenced this issue

2026-07-01 04:50:51 +00:00

feat(docs): auto-generate a flat KDL-keyword index (names-only UL) linking each keyword to its doc page + command entrypoint, freshness-validated #175

coilysiren commented

2026-07-01 04:51:06 +00:00

Author

Owner

WARD-OUTCOME: done - renamed specgen -> kdlspecs (package) / kdl-specs (command, docs, messages); landed on main as 0359c55, closes #174.

The interesting part of this one was resisting the urge to run a single blanket sed. The "depending on text" rule means the same token splits three ways, so I ran it as ordered passes: import paths / package clause / Go selectors (specgen.Foo) all went to kdlspecs first, then everything left over (message prefixes, help text, command name, doc paths) fell through to kdl-specs. The one trap was specgen.md vs specgen.Gen - both look like a dot-selector, so the selector pass had to anchor on an uppercase-letter/loadGroup follow, not a bare dot. As predicted, no snake context existed, so kdl_specs never appears.

Confidence is high: the grep for specgen is clean across code and docs (only historical commits mention it), godoc-current regenerated cleanly, and vet/lint/tidy/pre-commit are all green. Race tests pass except the pre-existing cli/sandbox seccomp/ptrace/jail cases, which fail identically on the untouched base - this container can't grant those kernel caps, so they're environmental, not mine.

No follow-ups worth filing. I did notify #175 that the renamed surface is live so the keyword-index work can build on it rather than the old name.

WARD-OUTCOME: done - renamed `specgen` -> kdlspecs (package) / kdl-specs (command, docs, messages); landed on main as 0359c55, closes #174. The interesting part of this one was resisting the urge to run a single blanket `sed`. The "depending on text" rule means the same token splits three ways, so I ran it as ordered passes: import paths / `package` clause / Go selectors (`specgen.Foo`) all went to `kdlspecs` first, then everything left over (message prefixes, help text, command name, doc paths) fell through to `kdl-specs`. The one trap was `specgen.md` vs `specgen.Gen` - both look like a dot-selector, so the selector pass had to anchor on an uppercase-letter/`loadGroup` follow, not a bare dot. As predicted, no snake context existed, so `kdl_specs` never appears. Confidence is high: the grep for `specgen` is clean across code and docs (only historical commits mention it), godoc-current regenerated cleanly, and vet/lint/tidy/pre-commit are all green. Race tests pass except the pre-existing `cli/sandbox` seccomp/ptrace/jail cases, which fail identically on the untouched base - this container can't grant those kernel caps, so they're environmental, not mine. No follow-ups worth filing. I did notify #175 that the renamed surface is live so the keyword-index work can build on it rather than the old name.