ward-kdl-authoring.md and cmd/ward-kdl/README.md point at each other in a loop; the actual KDL grammar lives undiscoverable in cli-guard #440

New issue

Closed

opened 2026-07-01 21:48:16 +00:00 by coilyco-ops · 2 comments

coilyco-ops commented

2026-07-01 21:48:16 +00:00

Member

Why

Persona: the-agent-itself, angle kdl-config. Mandate: draft a guardfile in scratch space using only the documentation. Trail:

README.md -> docs/ward-kdl.md: explains the three-dialect concept (permission surfaces / fleet manifest / operator-local) and the build-time-vs-run-time boundary well, but gives no syntax.
docs/ward-kdl.md -> docs/ward-kdl-authoring.md, the doc whose title promises "authoring." Its entire content: "See cmd/ward-kdl/README.md."
cmd/ward-kdl/README.md: "See docs/ward-kdl-authoring.md."

That is a closed two-file loop. Neither file contains a single KDL token. The per-area docs under docs/ward-kdl/*.guardfile.md (e.g. ward-kdl.git.guardfile.md) are generated output - the resulting verb surface of an already-written guardfile - not a syntax reference; they never show a wrap, can run, or exec node.

The grammar exists and is well-documented - just not in this repo. cli-guard's docs/execverb.md has a full ## Grammar section with a worked wrap ward git { ... } example (dialect 1), and docs/fleetconfig.md has the same for the fleet manifest (dialect 2). I confirmed this by checking cli-guard's own docs tree (permitted under rule 3, to verify "documented nowhere" vs. "documented elsewhere and unlinked" - it is the latter). Nothing in ward's docs/ward-kdl*.md, README.md, or AGENTS.md links to either file. A stranger following ward's own "See also" trails never learns cli-guard has the grammar at all.

Related but distinct: ward#271 (closed) fixed the conceptual framing of ward-kdl.md (three-layer boundary) but did not touch the authoring-loop dead end. ward#431 (open, currently empty body) flags confusion about read/write/admin KDL tiers, a different axis (profile selection, not syntax).

Deliverable

Break the loop: docs/ward-kdl-authoring.md should either inline the grammar or, at minimum, link directly to cli-guard's execverb.md (dialect 1) and fleetconfig.md (dialect 2) as the actual syntax reference, instead of bouncing to a stub that bounces back.

Done condition

Starting from README.md and clicking only linked docs, a stranger reaches a page containing actual KDL grammar (node names, block structure) for both *.guardfile.kdl and ward-kdl.fleet.kdl, with zero circular hops.

Severity: adoption-fatal · persona: the-agent-itself · angle: kdl-config
Filed by Claude Code during a cold-read release pressure test (run 4).

## Why Persona: `the-agent-itself`, angle `kdl-config`. Mandate: draft a guardfile in scratch space using only the documentation. Trail: 1. `README.md` -> [`docs/ward-kdl.md`](docs/ward-kdl.md): explains the three-dialect concept (permission surfaces / fleet manifest / operator-local) and the build-time-vs-run-time boundary well, but gives no syntax. 2. `docs/ward-kdl.md` -> [`docs/ward-kdl-authoring.md`](docs/ward-kdl-authoring.md), the doc whose title promises "authoring." Its entire content: "See [cmd/ward-kdl/README.md](../cmd/ward-kdl/README.md)." 3. [`cmd/ward-kdl/README.md`](cmd/ward-kdl/README.md): "See [docs/ward-kdl-authoring.md](../../docs/ward-kdl-authoring.md)." That is a closed two-file loop. Neither file contains a single KDL token. The per-area docs under `docs/ward-kdl/*.guardfile.md` (e.g. [`ward-kdl.git.guardfile.md`](docs/ward-kdl/ward-kdl.git.guardfile.md)) are generated *output* - the resulting verb surface of an already-written guardfile - not a syntax reference; they never show a `wrap`, `can run`, or `exec` node. The grammar exists and is well-documented - just not in this repo. `cli-guard`'s [`docs/execverb.md`](https://forgejo.coilysiren.me/coilyco-flight-deck/cli-guard/raw/branch/main/docs/execverb.md) has a full `## Grammar` section with a worked `wrap ward git { ... }` example (dialect 1), and [`docs/fleetconfig.md`](https://forgejo.coilysiren.me/coilyco-flight-deck/cli-guard/raw/branch/main/docs/fleetconfig.md) has the same for the fleet manifest (dialect 2). I confirmed this by checking cli-guard's own docs tree (permitted under rule 3, to verify "documented nowhere" vs. "documented elsewhere and unlinked" - it is the latter). Nothing in ward's `docs/ward-kdl*.md`, `README.md`, or `AGENTS.md` links to either file. A stranger following ward's own "See also" trails never learns cli-guard has the grammar at all. Related but distinct: ward#271 (closed) fixed the *conceptual framing* of `ward-kdl.md` (three-layer boundary) but did not touch the authoring-loop dead end. ward#431 (open, currently empty body) flags confusion about read/write/admin KDL tiers, a different axis (profile selection, not syntax). ## Deliverable Break the loop: `docs/ward-kdl-authoring.md` should either inline the grammar or, at minimum, link directly to `cli-guard`'s `execverb.md` (dialect 1) and `fleetconfig.md` (dialect 2) as the actual syntax reference, instead of bouncing to a stub that bounces back. ## Done condition Starting from `README.md` and clicking only linked docs, a stranger reaches a page containing actual KDL grammar (node names, block structure) for both `*.guardfile.kdl` and `ward-kdl.fleet.kdl`, with zero circular hops. --- **Severity: adoption-fatal** · persona: the-agent-itself · angle: kdl-config Filed by Claude Code during a cold-read release pressure test (run 4).

coilyco-ops added the

pressure-test

label

2026-07-01 21:48:16 +00:00

coilyco-ops referenced this issue

2026-07-01 21:48:59 +00:00

meta: release pressure-test run log (cold-read usability sweeps) #428

coilyco-ops commented

2026-07-01 21:55:38 +00:00

Author

Member

Dedup note: this duplicates #437, filed earlier the same day (parallel sweeps raced). This issue adds the sharper fact that the KDL grammar lives only in the unlinked sibling repo cli-guard — worth folding into #437's deliverable if the two merge.
Filed by Claude Code during a cold-read release pressure test (run 12 dedup pass).

Dedup note: this duplicates #437, filed earlier the same day (parallel sweeps raced). This issue adds the sharper fact that the KDL grammar lives only in the unlinked sibling repo cli-guard — worth folding into #437's deliverable if the two merge. Filed by Claude Code during a cold-read release pressure test (run 12 dedup pass).

coilyco-ops referenced this issue

2026-07-01 22:12:15 +00:00

Move the KDL specs (ops guardfiles + fleet manifest) out of ward up into aos, as a swappable build input #453

coilyco-ops added this to the ward launch milestone

2026-07-01 23:29:39 +00:00

coilyco-ops added the

headless

labels

2026-07-01 23:30:31 +00:00

coilyco-ops commented

2026-07-01 23:57:03 +00:00

Author

Member

Merged into #437 (same pointer-loop finding; #437 also carries the adopter-needs-a-guardfile question, now answered - see decision comment there). Recorded by Claude Code (Fable) during the 2026-07-01 ward launch triage session with Kai.

coilyco-ops closed this issue

2026-07-01 23:57:04 +00:00

coilyco-ops referenced this issue

2026-07-01 23:59:29 +00:00

guardfile authoring docs are a two-node pointer circle, and no doc says whether a downstream adopter needs a guardfile at all #437