coilyco-flight-deck/umbra

Watch

`ward-kdl` survives in three docs pages and two source comments, against `wrap ward` everywhere else #332

New issue

Closed

opened 2026-08-27 09:01:02 +00:00 by coilyco-ops · 1 comment

coilyco-ops commented

2026-08-27 09:01:02 +00:00

Owner

Spotted by Kai reading the live docs mount at /projects/umbra/docs/, which serves docs/ verbatim. The site is showing exactly what this repo has, so the fix is here.

What is inconsistent

Across docs/*.md, the first token after wrap is ward four times and ward-kdl once. Both names also appear in prose and in Go comments.

Docs

docs/passthrough.md:6 - wrap ward-kdl ssh { in the worked KDL block. Every other guardfile example in docs/ writes wrap ward.
docs/specgen.md:3 - "ward-kdl is a no-code CLI: the consumer authors policy plus committed locks, never Go or build glue."
docs/broker.md:7 - "carrying no git, docker, or ward-kdl knowledge".

Source

http/specgen/codegen/codegen.go:27 - Binary string // binary name, e.g. ward-kdl (Guardfile group[0])
pkg/broker/protocol.go:8 - "It carries no git, docker, or ward-kdl knowledge".

godoc-current.txt carries both of the source ones, so it moves when they do.

What is not established here

Which name is current. cmd/ builds specgen and kdl-specs, neither of which is ward-kdl or ward, and docs/ never says aosguard. In wrap <name> the token is the generated binary's own name (Guardfile group[0] per the codegen comment), so ward-kdl is not wrong on its face, it just names a CLI nothing else in this repo names. Whether the target is ward, aosguard, or a deliberately generic example is a naming call this repo owns, and I have not made it.

The two Go comments are source rather than prose, so that half is Agentic Platform Engineer work regardless of which way the name lands.

Why it is worth closing

docs/passthrough.md and docs/specgen.md are both mounted on the website. A reader meeting wrap ward-kdl ssh on one page and wrap ward git on the case study has no way to tell which one is the real invocation, and the docs mount is verbatim by contract, so nothing downstream can smooth it over. Once this lands, just sync-project-docs in coilysiren/website pulls it through.

Reference: coilysiren/website docs/project-docs-mount.md.

Spotted by Kai reading the live docs mount at `/projects/umbra/docs/`, which serves `docs/` verbatim. The site is showing exactly what this repo has, so the fix is here. ## What is inconsistent Across `docs/*.md`, the first token after `wrap` is `ward` four times and `ward-kdl` once. Both names also appear in prose and in Go comments. **Docs** * `docs/passthrough.md:6` - `wrap ward-kdl ssh {` in the worked KDL block. Every other guardfile example in `docs/` writes `wrap ward`. * `docs/specgen.md:3` - "`ward-kdl` is a **no-code** CLI: the consumer authors policy plus committed locks, never Go or build glue." * `docs/broker.md:7` - "carrying **no git, docker, or ward-kdl knowledge**". **Source** * `http/specgen/codegen/codegen.go:27` - `Binary string // binary name, e.g. ward-kdl (Guardfile group[0])` * `pkg/broker/protocol.go:8` - "It carries no git, docker, or ward-kdl knowledge". `godoc-current.txt` carries both of the source ones, so it moves when they do. ## What is not established here Which name is current. `cmd/` builds `specgen` and `kdl-specs`, neither of which is `ward-kdl` or `ward`, and `docs/` never says `aosguard`. In `wrap <name>` the token is the generated binary's own name (`Guardfile group[0]` per the codegen comment), so `ward-kdl` is not wrong on its face, it just names a CLI nothing else in this repo names. Whether the target is `ward`, `aosguard`, or a deliberately generic example is a naming call this repo owns, and I have not made it. The two Go comments are source rather than prose, so that half is Agentic Platform Engineer work regardless of which way the name lands. ## Why it is worth closing `docs/passthrough.md` and `docs/specgen.md` are both mounted on the website. A reader meeting `wrap ward-kdl ssh` on one page and `wrap ward git` on the case study has no way to tell which one is the real invocation, and the docs mount is verbatim by contract, so nothing downstream can smooth it over. Once this lands, `just sync-project-docs` in `coilysiren/website` pulls it through. Reference: [coilysiren/website docs/project-docs-mount.md](https://forgejo.coilysiren.me/coilysiren/website/src/branch/main/docs/project-docs-mount.md).

coilyco-ops referenced this issue from coilysiren/website

2026-08-27 09:01:20 +00:00

Write the docs manifests for agent-compose and mcp-beaver: 62 pages need a title, a shelf, and a blurb #137

coilyco-ops referenced this issue from a commit

2026-08-27 09:13:33 +00:00

docs: retire ward-kdl from the pages and comments a reader meets

coilyco-ops closed this issue

2026-08-27 09:13:33 +00:00

coilyco-ops commented

2026-08-27 09:13:52 +00:00

Author

Owner

Landed on main as 8e46ec6.

The naming call, with the evidence that settles it. ward-kdl was ward's proving-ground binary, named as such in ward#104 in June 2026. coilyco-flight-deck/ward now builds only cmd/ward, and the string ward-kdl appears nowhere in that repository. So the name is dead rather than ambiguous, and ward is what the four other guardfile examples in docs/ already write.

Fixed the five sites this issue names: docs/passthrough.md, docs/specgen.md, docs/broker.md, http/specgen/codegen/codegen.go, and pkg/broker/protocol.go, with godoc-current.txt following the two comments.

The test fixtures keep the name, deliberately. Reading turned up far more than the issue lists: about 100 occurrences across cli/execverb, http/guardfile, and http/specgen, and some are asserted rather than incidental, for example strings.Contains(data, "ward-kdl.inspect.df") checking an audit verb string. There the token is an arbitrary consumer name in test data, internally consistent and invisible to a reader. Renaming it is churn with real breakage risk and no reader benefit, so it stays.

make test and make lint are clean.

One thing for whoever lints umbra from a temporary clone next. make lint first failed here on paths under /tmp/umbra-304/, a clone from earlier today that no longer exists. golangci-lint had cached absolute paths from that run, so the failure was cache poisoning rather than a finding. golangci-lint cache clean fixed it. Worth knowing, since this repo's AGENTS.md tells every agent to work it from a task-scoped temporary clone, which makes that collision the default rather than the exception.

The docs half reaches the website on the next just sync-project-docs run, which is daily.

Landed on `main` as 8e46ec6. **The naming call, with the evidence that settles it.** `ward-kdl` was ward's proving-ground binary, named as such in ward#104 in June 2026. `coilyco-flight-deck/ward` now builds only `cmd/ward`, and the string `ward-kdl` appears nowhere in that repository. So the name is dead rather than ambiguous, and `ward` is what the four other guardfile examples in `docs/` already write. Fixed the five sites this issue names: `docs/passthrough.md`, `docs/specgen.md`, `docs/broker.md`, `http/specgen/codegen/codegen.go`, and `pkg/broker/protocol.go`, with `godoc-current.txt` following the two comments. **The test fixtures keep the name, deliberately.** Reading turned up far more than the issue lists: about 100 occurrences across `cli/execverb`, `http/guardfile`, and `http/specgen`, and some are asserted rather than incidental, for example `strings.Contains(data, "ward-kdl.inspect.df")` checking an audit verb string. There the token is an arbitrary consumer name in test data, internally consistent and invisible to a reader. Renaming it is churn with real breakage risk and no reader benefit, so it stays. `make test` and `make lint` are clean. **One thing for whoever lints umbra from a temporary clone next.** `make lint` first failed here on paths under `/tmp/umbra-304/`, a clone from earlier today that no longer exists. golangci-lint had cached absolute paths from that run, so the failure was cache poisoning rather than a finding. `golangci-lint cache clean` fixed it. Worth knowing, since this repo's AGENTS.md tells every agent to work it from a task-scoped temporary clone, which makes that collision the default rather than the exception. The docs half reaches the website on the next `just sync-project-docs` run, which is daily.

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

coilyco-flight-deck/umbra#332

No description provided.

Rows
Columns

ward-kdl survives in three docs pages and two source comments, against wrap ward everywhere else #332

What is inconsistent

What is not established here

Why it is worth closing

`ward-kdl` survives in three docs pages and two source comments, against `wrap ward` everywhere else #332