Restructure the ward KDL layer: scope guardfiles into read/write/admin (drop the flat bucket), relocate into `.ward/`, convert `.ward` config to KDL

coilysiren commented

2026-07-01 21:40:50 +00:00

Owner

Restructure the ward KDL layer end to end. Three coupled moves, one coherent job (the flat-bucket removal, the .ward/ relocation, and the config-to-KDL conversion all rewrite the same tree, so they land together, not as three racing branches).

1. Scope every guardfile into the read / write / admin trifecta; remove the flat cross-cutting bucket

Today cmd/ward-kdl/ holds 21 flat guardfiles directly in the top layer (aider, aws, brew, claude, codex, docker, eco-native, eco-server, forgejo-key, forgejo, git, glama, glitchtip, goose, kubectl, ollama, opencode, signoz, skillsmp, tailscale, trello). Only forgejo and signoz have been split into the scoped subdirs:

cmd/ward-kdl/
    ward-kdl.<tool>.guardfile.kdl   <- the flat cross-cutting bucket, MUST GO
    ward-kdl-read/   ward-kdl.forgejo.read.guardfile.kdl,  ward-kdl.signoz.read.guardfile.kdl
    ward-kdl-write/  ward-kdl.forgejo.write.guardfile.kdl, ward-kdl.signoz.write.guardfile.kdl
    ward-kdl-admin/  ward-kdl.forgejo.admin.guardfile.kdl, ward-kdl.signoz.admin.guardfile.kdl

Target: no guardfiles live directly in the ward-kdl/ layer. Every tool's surface is split by permission scope into ward-kdl-read/, ward-kdl-write/, ward-kdl-admin/, the way forgejo and signoz already are. A read-only director/advisor session mounts only the -read set; write and admin are separately gated. This is the generalization of the read/write/admin split that ward#572 (publish-kdl-read producer) already assumes exists for every tool, not just forgejo/signoz.

2. Move the whole thing into `.ward/`

The KDL setup currently lives in the ward source tree (cmd/ward-kdl/). It moves up to the top-level .ward/ config dir (the canonical home for ward configuration). Carry the embed-mirror machinery with it: the guardfiles are hand-edited in the source dir and copied into cmd/ward/execassets/ + cmd/ward/opsassets/ (and fleet.generated.kdl into cmd/ward/fleetassets/) for go:embed via make sync-*-assets, with drift tests failing the build on skew. The relocation must keep the source -> embed -> drift-test contract intact from the new .ward/ home.

3. Convert the existing `.ward/` config to KDL

.ward/ward.yaml (the commands + security + catalog YAML) becomes KDL, so the whole .ward/ layer speaks one grammar. The repocfg loader (which today unmarshals commands + security for ward exec / ward doctor / the hook) reads the KDL form. Preserve the catalog: block semantics (read by the aos catalog tooling and by every warded role for dependsOn).

Prereq / sequencing

Blocked on ward#547 (read-only observe surface, restart-critical). #547 is actively adding a new eco read-only observe guardfile and touching ward-kdl.fleet.kdl. Restructuring the whole guardfile tree concurrently would force #547 into a contested structural merge on the critical path. Dispatch this only after #547 closes, so its new observe guardfile gets scoped into ward-kdl-read/ as part of this restructure.
Blocks ward#453 (move the user-purpose layer up to aos). #453 lands on top of the trifecta-scoped, .ward/-relocated structure this issue produces.

Done condition

ward-kdl/ (now under .ward/) has no guardfiles at its top layer, every tool has read/write/admin scope variants, the embed/sync/drift machinery works from the new home, and .ward config is KDL with ward exec / doctor / the hook still green.

Origin: eco-ops director session, 2026-07-05, capturing Kai's KDL-restructure direction (described before but never fully executed). Supersedes the thin original body ("especially including the KDL specs").

Restructure the ward KDL layer end to end. Three coupled moves, one coherent job (the flat-bucket removal, the `.ward/` relocation, and the config-to-KDL conversion all rewrite the same tree, so they land together, not as three racing branches). ## 1. Scope every guardfile into the read / write / admin trifecta; remove the flat cross-cutting bucket Today `cmd/ward-kdl/` holds **21 flat guardfiles** directly in the top layer (aider, aws, brew, claude, codex, docker, eco-native, eco-server, forgejo-key, forgejo, git, glama, glitchtip, goose, kubectl, ollama, opencode, signoz, skillsmp, tailscale, trello). Only **forgejo** and **signoz** have been split into the scoped subdirs: ``` cmd/ward-kdl/ ward-kdl.<tool>.guardfile.kdl <- the flat cross-cutting bucket, MUST GO ward-kdl-read/ ward-kdl.forgejo.read.guardfile.kdl, ward-kdl.signoz.read.guardfile.kdl ward-kdl-write/ ward-kdl.forgejo.write.guardfile.kdl, ward-kdl.signoz.write.guardfile.kdl ward-kdl-admin/ ward-kdl.forgejo.admin.guardfile.kdl, ward-kdl.signoz.admin.guardfile.kdl ``` Target: **no guardfiles live directly in the `ward-kdl/` layer.** Every tool's surface is split by permission scope into `ward-kdl-read/`, `ward-kdl-write/`, `ward-kdl-admin/`, the way forgejo and signoz already are. A read-only director/advisor session mounts only the `-read` set; write and admin are separately gated. This is the generalization of the read/write/admin split that ward#572 (publish-kdl-read producer) already assumes exists for every tool, not just forgejo/signoz. ## 2. Move the whole thing into `.ward/` The KDL setup currently lives in the ward **source tree** (`cmd/ward-kdl/`). It moves up to the top-level **`.ward/`** config dir (the canonical home for ward configuration). Carry the embed-mirror machinery with it: the guardfiles are hand-edited in the source dir and copied into `cmd/ward/execassets/` + `cmd/ward/opsassets/` (and `fleet.generated.kdl` into `cmd/ward/fleetassets/`) for `go:embed` via `make sync-*-assets`, with drift tests failing the build on skew. The relocation must keep the source -> embed -> drift-test contract intact from the new `.ward/` home. ## 3. Convert the existing `.ward/` config to KDL `.ward/ward.yaml` (the `commands` + `security` + `catalog` YAML) becomes KDL, so the whole `.ward/` layer speaks one grammar. The `repocfg` loader (which today unmarshals `commands` + `security` for `ward exec` / `ward doctor` / the hook) reads the KDL form. Preserve the `catalog:` block semantics (read by the aos catalog tooling and by every warded role for `dependsOn`). ## Prereq / sequencing - **Blocked on ward#547** (read-only observe surface, restart-critical). #547 is actively adding a new eco read-only observe guardfile and touching `ward-kdl.fleet.kdl`. Restructuring the whole guardfile tree concurrently would force #547 into a contested structural merge on the critical path. **Dispatch this only after #547 closes**, so its new observe guardfile gets scoped into `ward-kdl-read/` as part of this restructure. - **Blocks ward#453** (move the user-purpose layer up to aos). #453 lands on top of the trifecta-scoped, `.ward/`-relocated structure this issue produces. ## Done condition `ward-kdl/` (now under `.ward/`) has no guardfiles at its top layer, every tool has read/write/admin scope variants, the embed/sync/drift machinery works from the new home, and `.ward` config is KDL with `ward exec` / `doctor` / the hook still green. Origin: eco-ops director session, 2026-07-05, capturing Kai's KDL-restructure direction (described before but never fully executed). Supersedes the thin original body ("especially including the KDL specs").

coilyco-ops added the

headless

P3

labels

2026-07-02 00:19:47 +00:00

coilyco-ops commented

2026-07-02 00:22:34 +00:00

Member

Labeled headless/P3, re-scoped: #453 moves the KDL specs to aos, which covers the body's 'especially' clause. Remaining scope = migrate/verify all remaining repo-level ward config canonically under .ward/; if nothing remains after #453 lands, close as mooted. Recorded by Claude Code (Fable) during the 2026-07-01 ward launch triage session with Kai.

coilyco-ops commented

2026-07-04 08:47:39 +00:00

Member

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-435 on host KAI-DESKTOP-TOWER is carrying this issue (reserved 2026-07-04T08:47:31Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); --force overrides.

Do not comment on or edit this issue to steer the run while it is reserved. The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a new issue, dispatched fresh — that is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494).

— Claude (she/her), via ward agent

🔒 Reserved by `ward agent --driver claude` — container `engineer-claude-ward-435` on host `KAI-DESKTOP-TOWER` is carrying this issue (reserved 2026-07-04T08:47:31Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides. **Do not comment on or edit this issue to steer the run while it is reserved.** The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a **new issue, dispatched fresh** — that is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494).  — Claude (she/her), via `ward agent`

coilysiren changed title from ~~move all ward configuration files to canonical live within .ward/ top level dir~~ to Restructure the ward KDL layer: scope guardfiles into read/write/admin (drop the flat bucket), relocate into .ward/, convert .ward config to KDL

2026-07-05 22:21:29 +00:00

coilysiren referenced this issue

2026-07-05 22:21:43 +00:00

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

coilyco-ops commented

2026-07-05 22:56:34 +00:00

Member

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-435 on host KAI-DESKTOP-TOWER is carrying this issue (reserved 2026-07-05T22:56:31Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); --force overrides.

Do not comment on or edit this issue to steer the run while it is reserved. The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a new issue, dispatched fresh — that is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494).

run seed context — what this run is carrying (ward#609)

Resolved: coilyco-flight-deck/ward#435 · branch issue-435 · driver claude · workflow direct-main
Run: engineer-claude-ward-435 · ward v0.406.0 · dispatched 2026-07-05T22:56:31Z
Comment thread: 1 included in the pre-flight read, 1 stripped (ward's own automated comments).
- included: @coilyco-ops (2026-07-02T00:22:34Z)
- stripped: @coilyco-ops (2026-07-04T08:47:39Z)

Issue body as seeded:

Restructure the ward KDL layer end to end. Three coupled moves, one coherent job (the flat-bucket removal, the `.ward/` relocation, and the config-to-KDL conversion all rewrite the same tree, so they land together, not as three racing branches).

## 1. Scope every guardfile into the read / write / admin trifecta; remove the flat cross-cutting bucket

Today `cmd/ward-kdl/` holds **21 flat guardfiles** directly in the top layer (aider, aws, brew, claude, codex, docker, eco-native, eco-server, forgejo-key, forgejo, git, glama, glitchtip, goose, kubectl, ollama, opencode, signoz, skillsmp, tailscale, trello). Only **forgejo** and **signoz** have been split into the scoped subdirs:

` ` `
cmd/ward-kdl/
    ward-kdl.<tool>.guardfile.kdl   <- the flat cross-cutting bucket, MUST GO
    ward-kdl-read/   ward-kdl.forgejo.read.guardfile.kdl,  ward-kdl.signoz.read.guardfile.kdl
    ward-kdl-write/  ward-kdl.forgejo.write.guardfile.kdl, ward-kdl.signoz.write.guardfile.kdl
    ward-kdl-admin/  ward-kdl.forgejo.admin.guardfile.kdl, ward-kdl.signoz.admin.guardfile.kdl
` ` `

Target: **no guardfiles live directly in the `ward-kdl/` layer.** Every tool's surface is split by permission scope into `ward-kdl-read/`, `ward-kdl-write/`, `ward-kdl-admin/`, the way forgejo and signoz already are. A read-only director/advisor session mounts only the `-read` set; write and admin are separately gated. This is the generalization of the read/write/admin split that ward#572 (publish-kdl-read producer) already assumes exists for every tool, not just forgejo/signoz.

## 2. Move the whole thing into `.ward/`

The KDL setup currently lives in the ward **source tree** (`cmd/ward-kdl/`). It moves up to the top-level **`.ward/`** config dir (the canonical home for ward configuration). Carry the embed-mirror machinery with it: the guardfiles are hand-edited in the source dir and copied into `cmd/ward/execassets/` + `cmd/ward/opsassets/` (and `fleet.generated.kdl` into `cmd/ward/fleetassets/`) for `go:embed`

… (truncated to 2000 chars; full body is on this issue)

Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.406.0).

— Claude (she/her), via ward agent

🔒 Reserved by `ward agent --driver claude` — container `engineer-claude-ward-435` on host `KAI-DESKTOP-TOWER` is carrying this issue (reserved 2026-07-05T22:56:31Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides. **Do not comment on or edit this issue to steer the run while it is reserved.** The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a **new issue, dispatched fresh** — that is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494). <details><summary>run seed context — what this run is carrying (ward#609)</summary> - **Resolved:** `coilyco-flight-deck/ward#435` · branch `issue-435` · driver `claude` · workflow `direct-main` - **Run:** `engineer-claude-ward-435` · ward `v0.406.0` · dispatched `2026-07-05T22:56:31Z` - **Comment thread:** 1 included in the pre-flight read, 1 stripped (ward's own automated comments). - included: @coilyco-ops (2026-07-02T00:22:34Z) - stripped: @coilyco-ops (2026-07-04T08:47:39Z) **Issue body as seeded:** ``` Restructure the ward KDL layer end to end. Three coupled moves, one coherent job (the flat-bucket removal, the `.ward/` relocation, and the config-to-KDL conversion all rewrite the same tree, so they land together, not as three racing branches). ## 1. Scope every guardfile into the read / write / admin trifecta; remove the flat cross-cutting bucket Today `cmd/ward-kdl/` holds **21 flat guardfiles** directly in the top layer (aider, aws, brew, claude, codex, docker, eco-native, eco-server, forgejo-key, forgejo, git, glama, glitchtip, goose, kubectl, ollama, opencode, signoz, skillsmp, tailscale, trello). Only **forgejo** and **signoz** have been split into the scoped subdirs: ` ` ` cmd/ward-kdl/ ward-kdl.<tool>.guardfile.kdl <- the flat cross-cutting bucket, MUST GO ward-kdl-read/ ward-kdl.forgejo.read.guardfile.kdl, ward-kdl.signoz.read.guardfile.kdl ward-kdl-write/ ward-kdl.forgejo.write.guardfile.kdl, ward-kdl.signoz.write.guardfile.kdl ward-kdl-admin/ ward-kdl.forgejo.admin.guardfile.kdl, ward-kdl.signoz.admin.guardfile.kdl ` ` ` Target: **no guardfiles live directly in the `ward-kdl/` layer.** Every tool's surface is split by permission scope into `ward-kdl-read/`, `ward-kdl-write/`, `ward-kdl-admin/`, the way forgejo and signoz already are. A read-only director/advisor session mounts only the `-read` set; write and admin are separately gated. This is the generalization of the read/write/admin split that ward#572 (publish-kdl-read producer) already assumes exists for every tool, not just forgejo/signoz. ## 2. Move the whole thing into `.ward/` The KDL setup currently lives in the ward **source tree** (`cmd/ward-kdl/`). It moves up to the top-level **`.ward/`** config dir (the canonical home for ward configuration). Carry the embed-mirror machinery with it: the guardfiles are hand-edited in the source dir and copied into `cmd/ward/execassets/` + `cmd/ward/opsassets/` (and `fleet.generated.kdl` into `cmd/ward/fleetassets/`) for `go:embed` ``` … (truncated to 2000 chars; full body is on this issue) Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.406.0). </details>  — Claude (she/her), via `ward agent`

coilysiren referenced this issue

2026-07-05 23:13:52 +00:00

Restructure ward KDL layer: per-verb read/write/admin trifecta (drop flat bucket) + convert .ward config to KDL - the two upstream-blocked parts of #435 #614

coilysiren referenced this issue from a commit

2026-07-05 23:14:22 +00:00

refactor(ward-kdl): relocate the guardfile tree from cmd/ward-kdl into .ward/ (closes #435)

coilysiren closed this issue

2026-07-05 23:14:22 +00:00

coilysiren commented

2026-07-05 23:18:13 +00:00

Author

Owner

WARD-OUTCOME: done - relocated the ward-kdl guardfile tree from cmd/ward-kdl into .ward/ward-kdl (Part 2); the flat-bucket trifecta (Part 1) and config-to-KDL (Part 3) are upstream-blocked and carried in #614.

Honest retrospective: I went in expecting a big-but-mechanical three-part rewrite and came out having landed only one part, because reading the actual wiring changed the picture. Part 2 (the relocation) was the pleasant surprise - a wholesale git mv preserved every internal relative path, the go:embed asset dirs never move, and only three drift-test constants plus the Makefile, release.yml, and doc references needed repointing. Build, tests, ward doctor, and the full pre-commit gate all came up green, and the release run (938) built the read/write KDL tiers from the new paths without complaint.

What fought back was the discovery that the other two parts are not mine to finish from inside a container. Part 3 wants .ward/ward.yaml to become KDL, but cli-guard's repocfg.Load is YAML-only at the pinned REF and the agentic-os catalog hooks (catalog-block-present, catalog-trifecta) hard-code .ward/ward.yaml + yaml.safe_load and run on every commit - so forcing KDL would red the commit gate, and I must never --no-verify. Part 1 wants the flat bucket gone, but per-verb tiering for the ~15 remaining tools is the ward#339 fan-out gated on cli-guard#169, it is security-critical per-tool judgement, and the flat bucket is also the live embed/auto-mount source for ward docker/ward ops/ward agents, so it cannot just be deleted. Both need coordinated changes in external repos outside this run's grant.

Confidence: high on what landed (fully verified locally + release CI green), and high that the remainder is genuinely blocked rather than me under-reaching - I traced it to the exact YAML-hardcoded lines and the cli-guard#169 gate. The one judgement call worth a second look: I chose to land the relocation and closes #435 with the blocked parts split to #614, rather than park the whole issue. The container machinery salvages any push without a closing ref, and the relocation is the foundation #453 needs, so landing it felt right - but if you wanted all three to stay atomic, reopen #435 and fold #614 back in. Rough edge / follow-up: #614 carries the full blocker analysis and a suggested sequencing; it should not start until cli-guard#169 and the cli-guard-repocfg-KDL + aos-catalog-KDL support land.

WARD-OUTCOME: done - relocated the ward-kdl guardfile tree from cmd/ward-kdl into .ward/ward-kdl (Part 2); the flat-bucket trifecta (Part 1) and config-to-KDL (Part 3) are upstream-blocked and carried in #614. Honest retrospective: I went in expecting a big-but-mechanical three-part rewrite and came out having landed only one part, because reading the actual wiring changed the picture. Part 2 (the relocation) was the pleasant surprise - a wholesale `git mv` preserved every internal relative path, the go:embed asset dirs never move, and only three drift-test constants plus the Makefile, release.yml, and doc references needed repointing. Build, tests, `ward doctor`, and the full pre-commit gate all came up green, and the release run (938) built the read/write KDL tiers from the new paths without complaint. What fought back was the discovery that the other two parts are not mine to finish from inside a container. Part 3 wants `.ward/ward.yaml` to become KDL, but cli-guard's `repocfg.Load` is YAML-only at the pinned REF *and* the agentic-os catalog hooks (`catalog-block-present`, `catalog-trifecta`) hard-code `.ward/ward.yaml` + `yaml.safe_load` and run on every commit - so forcing KDL would red the commit gate, and I must never `--no-verify`. Part 1 wants the flat bucket gone, but per-verb tiering for the ~15 remaining tools is the ward#339 fan-out gated on cli-guard#169, it is security-critical per-tool judgement, and the flat bucket is also the live embed/auto-mount source for `ward docker`/`ward ops`/`ward agents`, so it cannot just be deleted. Both need coordinated changes in external repos outside this run's grant. Confidence: high on what landed (fully verified locally + release CI green), and high that the remainder is genuinely blocked rather than me under-reaching - I traced it to the exact YAML-hardcoded lines and the cli-guard#169 gate. The one judgement call worth a second look: I chose to land the relocation and `closes #435` with the blocked parts split to #614, rather than park the whole issue. The container machinery salvages any push without a closing ref, and the relocation is the foundation #453 needs, so landing it felt right - but if you wanted all three to stay atomic, reopen #435 and fold #614 back in. Rough edge / follow-up: #614 carries the full blocker analysis and a suggested sequencing; it should not start until cli-guard#169 and the cli-guard-repocfg-KDL + aos-catalog-KDL support land.

coilysiren referenced this issue

2026-07-14 15:27:09 +00:00

director should emit colorized, space buffered, visually distinct messages about the categories of actions its performing on startup #1283

Rows
Columns

Restructure the ward KDL layer: scope guardfiles into read/write/admin (drop the flat bucket), relocate into .ward/, convert .ward config to KDL #435

1. Scope every guardfile into the read / write / admin trifecta; remove the flat cross-cutting bucket

2. Move the whole thing into .ward/

3. Convert the existing .ward/ config to KDL

Prereq / sequencing

Done condition

Restructure the ward KDL layer: scope guardfiles into read/write/admin (drop the flat bucket), relocate into `.ward/`, convert `.ward` config to KDL #435

2. Move the whole thing into `.ward/`

3. Convert the existing `.ward/` config to KDL