the .ward/ward.yaml schema is documented nowhere field-by-field #434

New issue

Closed

opened 2026-07-01 21:38:41 +00:00 by coilyco-ops · 1 comment

coilyco-ops commented

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

Member

Why

Persona: forgejo-selfhoster walking the "zero to a working warded #<issue>" path, angle yaml-config. README.md says: "Each repo declares which Makefile targets are exposed in .ward/ward.yaml. The contract is verified by ward lint." That is the entire public explanation of the config file. docs/config-discovery.md explains where ward looks for the file (.ward/ward.yaml, .coily/coily.yaml, --config, $WARD_CONFIG) but explicitly defers the format: "Both use the cli-guard repocfg format." No ward doc explains what that format contains.

The only artifact a stranger can read is wards own self-referential .ward/ward.yaml:

catalog:
  description: "..."
  dependsOn:
    - forgejo.coilysiren.me/coilyco-flight-deck/cli-guard
commands:
  build:
    run: make build
    description: Build all packages.
  ...

Reverse-engineering a config for a different repo from this one example leaves open questions no doc answers: is catalog.dependsOn required, and what does it do for a downstream (non-ward) repo that has no such dependency? Is commands.<name>.run restricted to make <target>, or can it be arbitrary shell (mind the "shell-metacharacter policy check" config-discovery.md mentions in passing)? Is the commands key-set fixed to the six verbs named in the README ("build, test, vet, lint, tidy, cover"), or freely extensible - wards own file adds install and build-ward-kdl, which nothing in the README prepares a reader for. Are there other top-level keys?

I checked whether the sibling cli-guard repo (which owns the repocfg format per config-discovery.md) documents this schema publicly, since if so ward could just link it: its docs/ has 20+ files including execverb.md, examples.md, fleetconfig.md, none of which contain the strings catalog, dependsOn, or commands: used in this schema. The format is undocumented in both public repos.

Deliverable

A schema reference for .ward/ward.yaml (either in ward's own docs or a linked page in cli-guard, if repocfg is meant to live there) that states, at minimum: required vs. optional top-level keys, the purpose and consumer of catalog.dependsOn, the constraints on commands.<verb>.run (shell syntax allowed, argv policy), and whether the verb key-set is fixed or open. A second, non-self-referential example (a config for a different, non-ward repo) would remove the "is this generic or ward-specific" ambiguity entirely.

Done condition

A stranger can author a valid .ward/ward.yaml for a repo that is not ward itself, using only published docs, without guessing at any field's purpose or constraints.

Severity: major-friction · persona: forgejo-selfhoster · angle: yaml-config
Filed by Claude Code during a cold-read release pressure test (run 3).

## Why Persona: `forgejo-selfhoster` walking the "zero to a working `warded #<issue>`" path, angle `yaml-config`. `README.md` says: "Each repo declares which Makefile targets are exposed in `.ward/ward.yaml`. The contract is verified by `ward lint`." That is the *entire* public explanation of the config file. `docs/config-discovery.md` explains *where* ward looks for the file (`.ward/ward.yaml`, `.coily/coily.yaml`, `--config`, `$WARD_CONFIG`) but explicitly defers the format: "Both use the cli-guard `repocfg` format." No ward doc explains what that format contains. The only artifact a stranger can read is wards own self-referential `.ward/ward.yaml`: ```yaml catalog: description: "..." dependsOn: - forgejo.coilysiren.me/coilyco-flight-deck/cli-guard commands: build: run: make build description: Build all packages. ... ``` Reverse-engineering a config for a *different* repo from this one example leaves open questions no doc answers: is `catalog.dependsOn` required, and what does it do for a downstream (non-ward) repo that has no such dependency? Is `commands.<name>.run` restricted to `make <target>`, or can it be arbitrary shell (mind the "shell-metacharacter policy check" `config-discovery.md` mentions in passing)? Is the `commands` key-set fixed to the six verbs named in the README ("build, test, vet, lint, tidy, cover"), or freely extensible - wards own file adds `install` and `build-ward-kdl`, which nothing in the README prepares a reader for. Are there other top-level keys? I checked whether the sibling `cli-guard` repo (which owns the `repocfg` format per `config-discovery.md`) documents this schema publicly, since if so ward could just link it: its `docs/` has 20+ files including `execverb.md`, `examples.md`, `fleetconfig.md`, none of which contain the strings `catalog`, `dependsOn`, or `commands:` used in this schema. The format is undocumented in both public repos. ## Deliverable A schema reference for `.ward/ward.yaml` (either in ward's own docs or a linked page in cli-guard, if repocfg is meant to live there) that states, at minimum: required vs. optional top-level keys, the purpose and consumer of `catalog.dependsOn`, the constraints on `commands.<verb>.run` (shell syntax allowed, argv policy), and whether the verb key-set is fixed or open. A second, non-self-referential example (a config for a *different*, non-ward repo) would remove the "is this generic or ward-specific" ambiguity entirely. ## Done condition A stranger can author a valid `.ward/ward.yaml` for a repo that is not `ward` itself, using only published docs, without guessing at any field's purpose or constraints. --- **Severity: major-friction** · persona: forgejo-selfhoster · angle: yaml-config Filed by Claude Code during a cold-read release pressure test (run 3).

coilyco-ops added the

pressure-test

label

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

coilyco-ops referenced this issue

2026-07-01 21:39: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/ward.yaml has no field-by-field schema doc; the security: block is authorable only by reading cli-guard Go source #436

coilyco-ops added this to the ward launch milestone

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

coilyco-ops added the

headless

labels

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

coilyco-ops commented

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

Author

Member

Merged into #436 (same finding: ward.yaml schema documented nowhere field-by-field; #436 carries the richer body incl. the security: block). 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:03 +00:00

coilyco-ops referenced this issue

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

.ward/ward.yaml has no field-by-field schema doc; the security: block is authorable only by reading cli-guard Go source #436