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

coilyco-ops commented

2026-07-01 21:47:32 +00:00

Owner

Why

Persona: the-agent-itself, attempting the second half of setup ("draft a guardfile"). Trail: README → docs/ward-kdl.md → docs/ward-kdl-authoring.md → cmd/ward-kdl/README.md. The last two form a closed loop: ward-kdl-authoring.md's entire authoring content is ten lines naming three dialects plus "See cmd/ward-kdl/README.md", and cmd/ward-kdl/README.md contains only "See docs/ward-kdl-authoring.md". The KDL dialect is exemplified (guardfiles in-tree; generated per-area reference docs describe verbs) but its syntax/grammar is documented nowhere a stranger can find, and auth config (SSM refs etc.) is never explained.

Upstream of the syntax gap sits a fork no doc resolves: does a downstream adopter author a guardfile at all, or is .ward/ward.yaml alone the adoption contract, with guardfiles being ward's own build-time internals? ward-kdl.md gestures at the latter ("You rarely run ward-kdl by hand") but never addresses the adopter directly. An agent asked to "set up ward" will burn its context trying to author one — or skip one it needed. (This run's agent abandoned the guardfile draft at the pointer circle.)

Deliverable

Break the pointer circle: make ward-kdl-authoring.md (or a doc it links) a real authoring reference — dialect syntax, one minimal working guardfile, where auth config lives.
One early paragraph in ward-kdl.md or the README answering the adopter question directly: "you need a guardfile when X; for dev-verb adoption, .ward/ward.yaml is all you write."

Done condition

Following the docs' own link chain from the README lands on actual authoring instructions, not a two-node cycle; a cold reader can state in one sentence whether their repo needs a guardfile. (Related history: #421 reframed ward-kdl's charter but left the authoring stub circular.)

Severity: major-friction · persona: the-agent-itself · angle: yaml-config
Filed by Claude Code during a cold-read release pressure test (run 2).

## Why Persona: `the-agent-itself`, attempting the second half of setup ("draft a guardfile"). Trail: README → docs/ward-kdl.md → docs/ward-kdl-authoring.md → cmd/ward-kdl/README.md. The last two form a closed loop: ward-kdl-authoring.md's entire authoring content is ten lines naming three dialects plus "See cmd/ward-kdl/README.md", and cmd/ward-kdl/README.md contains only "See docs/ward-kdl-authoring.md". The KDL dialect is exemplified (guardfiles in-tree; generated per-area reference docs describe *verbs*) but its syntax/grammar is documented nowhere a stranger can find, and auth config (SSM refs etc.) is never explained. Upstream of the syntax gap sits a fork no doc resolves: does a downstream adopter author a guardfile at all, or is `.ward/ward.yaml` alone the adoption contract, with guardfiles being ward's own build-time internals? ward-kdl.md gestures at the latter ("You rarely run ward-kdl by hand") but never addresses the adopter directly. An agent asked to "set up ward" will burn its context trying to author one — or skip one it needed. (This run's agent abandoned the guardfile draft at the pointer circle.) ## Deliverable 1. Break the pointer circle: make ward-kdl-authoring.md (or a doc it links) a real authoring reference — dialect syntax, one minimal working guardfile, where auth config lives. 2. One early paragraph in ward-kdl.md or the README answering the adopter question directly: "you need a guardfile when X; for dev-verb adoption, `.ward/ward.yaml` is all you write." ## Done condition Following the docs' own link chain from the README lands on actual authoring instructions, not a two-node cycle; a cold reader can state in one sentence whether their repo needs a guardfile. (Related history: #421 reframed ward-kdl's charter but left the authoring stub circular.) --- **Severity: major-friction** · persona: the-agent-itself · angle: yaml-config Filed by Claude Code during a cold-read release pressure test (run 2).

coilyco-ops added the

pressure-test

label

2026-07-01 21:47:32 +00:00

coilyco-ops referenced this issue

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

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

coilyco-ops referenced this issue

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

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

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 referenced this issue

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

Remove ward-kdl (authoring binary + tier CLIs) from the public-facing published artifacts #455

coilyco-ops added this to the ward launch milestone

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

coilyco-ops added the

labels

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

coilyco-ops referenced this issue

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

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

coilyco-ops commented

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

Author

Owner

Canonical for #440 (merged). DECISION already on record in #455's body: for dev-verb adoption, .ward/ward.yaml is ALL a downstream adopter writes - adopters do NOT author guardfiles. The doc fix: break the two-file pointer loop, state that contract explicitly, and link the cli-guard KDL grammar reference for spec authors (who obtain ward-kdl separately per #455). Recorded by Claude Code (Fable) during the 2026-07-01 ward launch triage session with Kai.

coilyco-ops referenced this issue

2026-07-02 00:01:42 +00:00

meta: jul 1st evening sprint - launch burndown session 1 #492

coilysiren referenced this issue from a commit

2026-07-02 03:08:30 +00:00

feat(ward-kdl): ship a swappable spec-bundle input + neutral example

coilyco-ops commented

2026-07-02 07:10:24 +00:00

Author

Owner

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-437 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-02T07:10:22Z). 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-ward-437` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-02T07:10:22Z). 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

2026-07-02 07:10:55 +00:00

meta: jul 1st evening sprint - launch burndown session 1 #492

coilysiren referenced this issue from a commit

2026-07-02 07:23:36 +00:00

docs: break the guardfile-authoring pointer circle, answer the adopter question

coilysiren closed this issue

2026-07-02 07:23:36 +00:00

coilysiren commented

2026-07-02 07:24:14 +00:00

Owner

WARD-OUTCOME: done - new docs/guardfile-grammar.md ends the authoring trail on real syntax + a minimal guardfile; ward-kdl.md now answers "do I need a guardfile?" up front.

Honest retro: the doc work itself was straightforward - I traced the pointer circle (authoring.md <-> cmd/ward-kdl/README.md), then wrote the grammar reference grounded in the compiling example bundle (spec dialect) and the cli-guard execverb parser (exec dialect) rather than inventing syntax. That grounding paid off: my first "minimal guardfile" used echo with an empty can run, which the parser actually rejects (needs a real subcommand), so I swapped it for a one-verb kubectl wrap that genuinely compiles.

The thing that fought back hardest was not the content but the size caps - docs/*.md are hard-capped at 80 lines / 4000 chars, and ward-kdl.md was already at ~3870 chars. Splitting the grammar into its own doc plus several rounds of tightening got all three under the caps. I confirmed the pinned decision comment (adopters write only .ward/ward.yaml) matches what I documented.

Confidence: high on correctness (grammar checked against parser + a known-good bundle) and on the done-condition (the README trail now lands on real instructions, and the one-sentence adopter answer is stated in bold). Rough edge / possible follow-up: the decision comment suggested linking a cli-guard KDL grammar reference for spec authors - I wrote the reference in-repo instead since none was findable, but if cli-guard later ships a canonical grammar doc, guardfile-grammar.md should point at it rather than duplicate it.

WARD-OUTCOME: done - new docs/guardfile-grammar.md ends the authoring trail on real syntax + a minimal guardfile; ward-kdl.md now answers "do I need a guardfile?" up front. Honest retro: the doc work itself was straightforward - I traced the pointer circle (authoring.md <-> cmd/ward-kdl/README.md), then wrote the grammar reference grounded in the compiling example bundle (spec dialect) and the cli-guard execverb parser (exec dialect) rather than inventing syntax. That grounding paid off: my first "minimal guardfile" used `echo` with an empty `can run`, which the parser actually rejects (needs a real subcommand), so I swapped it for a one-verb kubectl wrap that genuinely compiles. The thing that fought back hardest was not the content but the size caps - docs/*.md are hard-capped at 80 lines / 4000 chars, and ward-kdl.md was already at ~3870 chars. Splitting the grammar into its own doc plus several rounds of tightening got all three under the caps. I confirmed the pinned decision comment (adopters write only .ward/ward.yaml) matches what I documented. Confidence: high on correctness (grammar checked against parser + a known-good bundle) and on the done-condition (the README trail now lands on real instructions, and the one-sentence adopter answer is stated in bold). Rough edge / possible follow-up: the decision comment suggested linking a cli-guard KDL grammar reference for spec authors - I wrote the reference in-repo instead since none was findable, but if cli-guard later ships a canonical grammar doc, guardfile-grammar.md should point at it rather than duplicate it.

coilysiren commented

2026-07-02 07:52:58 +00:00

Owner

WARD-OUTCOME: done - re-dispatch of an already-landed issue; verified the fix holds on main, nothing new to push.

This container was dispatched onto #437 again, but the work was already complete: commit 9fd085d (closes #437) is on origin/main, my branch is byte-identical to it, and the issue is already closed. I re-read the whole chain to confirm the deliverable actually holds rather than trusting the closed state - README -> ward-kdl.md -> ward-kdl-authoring.md -> guardfile-grammar.md now terminates on real dialect-1 syntax, a compiling minimal guardfile, and the auth-config section, with no back-edge closing a cycle. The adopter fork is answered up front in ward-kdl.md's 'Do you need to author a guardfile?' section (one-sentence answer: only if you run your own ward ops surface; dev-verb adoption is .ward/ward.yaml alone).

Nothing fought back because there was nothing to build - the honest note is just that the prior run nailed it, so this run's contribution is verification, not code. Confidence high. No follow-ups beyond the one the earlier retro already flagged (point guardfile-grammar.md at a canonical cli-guard grammar doc if one ever ships).

WARD-OUTCOME: done - re-dispatch of an already-landed issue; verified the fix holds on main, nothing new to push. This container was dispatched onto #437 again, but the work was already complete: commit 9fd085d (`closes #437`) is on origin/main, my branch is byte-identical to it, and the issue is already closed. I re-read the whole chain to confirm the deliverable actually holds rather than trusting the closed state - README -> ward-kdl.md -> ward-kdl-authoring.md -> guardfile-grammar.md now terminates on real dialect-1 syntax, a compiling minimal guardfile, and the auth-config section, with no back-edge closing a cycle. The adopter fork is answered up front in ward-kdl.md's 'Do you need to author a guardfile?' section (one-sentence answer: only if you run your own `ward ops` surface; dev-verb adoption is `.ward/ward.yaml` alone). Nothing fought back because there was nothing to build - the honest note is just that the prior run nailed it, so this run's contribution is verification, not code. Confidence high. No follow-ups beyond the one the earlier retro already flagged (point guardfile-grammar.md at a canonical cli-guard grammar doc if one ever ships).

Rows
Columns

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

Why

Deliverable

Done condition