aos#310 issue 8 [charter]: reframe ward-kdl docs from 'audited-CLI generator' to 'the build-time authoring layer' (three dialects) #421

New issue

Closed

opened 2026-07-01 10:31:18 +00:00 by coilysiren · 4 comments

coilysiren commented

2026-07-01 10:31:18 +00:00

Owner

Issue 8 of the ward<=>aos config pass (aos#310 §4, charter half). Unblocked: dialect 2 has fully landed (issues 2-6). Docs-only, parallel-safe with the parseMode code work (ward#420).

Deliverable (ward)

Reframe docs/ward-kdl.md + cmd/ward-kdl/README.md from 'the build-time generator / audited-CLI generator' to 'the build-time authoring layer'. Its unifying invariant was never the output type:

author a source file -> cli-guard compiles/validates it -> ward embeds the result -> nothing is fetched at runtime.

Under that invariant ward-kdl runs three dialects:

Dialect 1 - permission surfaces (*.guardfile.kdl, spec + exec). Least-privilege, audited, 'protoc for permissions'. Parsed by cli/execverb + http/specverb. Unchanged.
Dialect 2 - fleet-config manifest (ward-kdl.fleet.kdl: identity, model, endpoint, attribution, roster defaults). Parsed by cli-guard pkg/fleetconfig. Embedded via fleetassets. New.
Dialect 3 boundary (named, tracked separately) - operator-local (axis 3): the same fleetconfig parser, sourced from a local ~/.ward/fleet.local.kdl, not embedded. Reference ward#396 / ward#413.

Constraints

Keep the least-privilege identity legible: config sits beside permissions, not mixed into them. Document the partition (distinct .fleet.kdl suffix, fleetassets/ dir, fleet.go, pkg/fleetconfig, separate docs).
Update ward docs/architecture.md three-layer refs if they call ward-kdl 'just' a generator. The cli-guard docs/architecture.md doctrine note is separate (cli-guard#178). Keep docs/FEATURES.md current.
Do NOT fork the config-placement doctrine into ward AGENTS.md - it is canonical in aos AGENTS.md (aos#311); consumer repos reference, not fork.

Mode: headless.

Issue 8 of the ward<=>aos config pass (**aos#310** §4, charter half). **Unblocked:** dialect 2 has fully landed (issues 2-6). Docs-only, parallel-safe with the `parseMode` code work (ward#420). ## Deliverable (ward) Reframe **`docs/ward-kdl.md`** + **`cmd/ward-kdl/README.md`** from 'the build-time generator / audited-CLI generator' to **'the build-time authoring layer'**. Its unifying invariant was never the output type: > author a source file -> cli-guard compiles/validates it -> ward embeds the result -> nothing is fetched at runtime. Under that invariant ward-kdl runs **three dialects**: - **Dialect 1 - permission surfaces** (`*.guardfile.kdl`, spec + exec). Least-privilege, audited, 'protoc for permissions'. Parsed by `cli/execverb` + `http/specverb`. Unchanged. - **Dialect 2 - fleet-config manifest** (`ward-kdl.fleet.kdl`: identity, model, endpoint, attribution, roster defaults). Parsed by cli-guard `pkg/fleetconfig`. Embedded via `fleetassets`. New. - **Dialect 3 boundary (named, tracked separately) - operator-local** (axis 3): the same `fleetconfig` parser, sourced from a local `~/.ward/fleet.local.kdl`, not embedded. Reference ward#396 / ward#413. ## Constraints - **Keep the least-privilege identity legible:** config sits **beside** permissions, not mixed into them. Document the partition (distinct `.fleet.kdl` suffix, `fleetassets/` dir, `fleet.go`, `pkg/fleetconfig`, separate docs). - Update ward `docs/architecture.md` three-layer refs if they call ward-kdl 'just' a generator. The cli-guard `docs/architecture.md` doctrine note is separate (cli-guard#178). Keep `docs/FEATURES.md` current. - Do NOT fork the config-placement doctrine into ward `AGENTS.md` - it is canonical in aos `AGENTS.md` (aos#311); consumer repos reference, not fork. Mode: headless.

coilyco-ops commented

2026-07-01 10:31:25 +00:00

Member

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-421 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-01T10:31:23Z). 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-421` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-01T10:31:23Z). 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 commented

2026-07-01 10:31:32 +00:00

Author

Owner

🔓 Reservation released by ward container reap — container ward (--driver claude) exited without launching the agent (smoke-test death, ward#222/#264), so the hold it took is retracted. A plain ward agent retry no longer needs --force.

— Claude (she/her), via ward agent

🔓 Reservation released by `ward container reap` — container `ward` (`--driver claude`) exited without launching the agent (smoke-test death, ward#222/#264), so the hold it took is retracted. A plain `ward agent` retry no longer needs `--force`.  — Claude (she/her), via `ward agent`

coilyco-ops commented

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

Member

🔒 Reserved by ward agent --driver codex — container engineer-codex-ward-421 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-01T11:04:21Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); --force overrides.

— Codex, via ward agent

🔒 Reserved by `ward agent --driver codex` — container `engineer-codex-ward-421` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-01T11:04:21Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides.  — Codex, via `ward agent`

coilysiren referenced this issue from a commit

2026-07-01 11:11:10 +00:00

docs: reframe ward-kdl as the build-time authoring layer

coilysiren closed this issue

2026-07-01 11:11:10 +00:00

coilysiren commented

2026-07-01 11:11:23 +00:00

Author

Owner

WARD-OUTCOME: done - reframed ward-kdl docs as the build-time authoring layer

The doc pass went cleanly once I split the outpost pointer and trimmed the long docs to fit the repo caps. The only thing that fought back was the documentation layout hook, not the content. Confidence is high; the only follow-up I would consider is a broader sweep for any other docs that still say "generator" outside the ward-kdl surfaces.

WARD-OUTCOME: done - reframed ward-kdl docs as the build-time authoring layer The doc pass went cleanly once I split the outpost pointer and trimmed the long docs to fit the repo caps. The only thing that fought back was the documentation layout hook, not the content. Confidence is high; the only follow-up I would consider is a broader sweep for any other docs that still say "generator" outside the ward-kdl surfaces.

coilyco-ops referenced this issue

2026-07-01 21:47:32 +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