docs(ward): write the surviving .ward/ward.yaml schema into a writable repo #1328

Merged

coilyco-ops merged 1 commit from aos/claude/fp87-ward-schema into main

2026-08-27 10:27:34 +00:00

coilyco-ops commented

2026-08-27 10:26:04 +00:00

Owner

Refs #1299.

Ward is archived this week and its docs/ward-yaml.md goes read-only with it, while .ward/ward.yaml stays in 15 of the 16 repositories on this host. The schema outliving its own documentation is the seam this closes, and it is the open question I left on #1299.

The sweep changed what the doc needed to say

I swept every repo on this host for real readers before writing anything. The schema is not dead, and it is not what Ward documented either.

Live consumers, none of them Ward. agentic-os-kai/scripts/pull-capabilities.py reads a capabilities: list that was never in Ward's schema at all, and eco-mods/scripts/ci-root-hygiene.sh asserts the file exists.
catalog.description and catalog.dependsOn have no code reader on this host. They are declared nearly everywhere. The doc records that as an honest gap rather than describing them as live inputs.
Two different files share the name. A root ward.yaml carrying tailnet.shortcut is fetched over the Forgejo API by infrastructure/scripts/generate-caddy-shortcuts.py, with coily.yaml and config.yml as migration fallbacks. Separate path, schema, and consumer from .ward/ward.yaml, and only pull-capabilities.py accepts both. Worth writing down before someone conflates them.
commands and security are retired, to the justfile (inbox#366) and to AOSguard plus umbra respectively.

So a verbatim copy of Ward's page would have been wrong in both directions: documenting two retired blocks, and missing the one key anything actually reads.

Placement

Folded into docs/ward-specs.md rather than given its own page. That doc is already the AOS-side Ward boundary page, AGENTS.md already points at it, and docs/ sits at exactly the large-band cap of 40 files, so a new page would have failed documentation-layout for a reason unrelated to its content.

This also corrects that file's opening, which said ward doctor validates the YAML. It will not, once #1299 cuts the runtime.

One stale comment fixed

.ward/ward.yaml claimed it survived "because check_catalog_block pins this exact path and catalog-trifecta wants README, AGENTS, and FEATURES to link it". No check_catalog_block exists, and catalog-trifecta dropped the requirement fleet-wide under inbox#385. Comment only, no behavior change.

Not in scope

No consumer code is touched, and no .ward/ward.yaml is added or removed anywhere. Whether the fleet should keep declaring a file nothing validates is a separate call.

Validation

pre-commit run --all-files passes, exit 0. docs/ward-specs.md lands at 100 lines and 6640 bytes against the large-band caps of 120 and 8000.

Refs #1299. Ward is archived this week and its `docs/ward-yaml.md` goes read-only with it, while `.ward/ward.yaml` stays in 15 of the 16 repositories on this host. The schema outliving its own documentation is the seam this closes, and it is the open question I left on #1299. ## The sweep changed what the doc needed to say I swept every repo on this host for real readers before writing anything. The schema is not dead, and it is not what Ward documented either. * **Live consumers, none of them Ward.** `agentic-os-kai/scripts/pull-capabilities.py` reads a `capabilities:` list that **was never in Ward's schema at all**, and `eco-mods/scripts/ci-root-hygiene.sh` asserts the file exists. * **`catalog.description` and `catalog.dependsOn` have no code reader on this host.** They are declared nearly everywhere. The doc records that as an honest gap rather than describing them as live inputs. * **Two different files share the name.** A root `ward.yaml` carrying `tailnet.shortcut` is fetched over the Forgejo API by `infrastructure/scripts/generate-caddy-shortcuts.py`, with `coily.yaml` and `config.yml` as migration fallbacks. Separate path, schema, and consumer from `.ward/ward.yaml`, and only `pull-capabilities.py` accepts both. Worth writing down before someone conflates them. * **`commands` and `security` are retired**, to the justfile (inbox#366) and to AOSguard plus umbra respectively. So a verbatim copy of Ward's page would have been wrong in both directions: documenting two retired blocks, and missing the one key anything actually reads. ## Placement Folded into `docs/ward-specs.md` rather than given its own page. That doc is already the AOS-side Ward boundary page, AGENTS.md already points at it, and `docs/` sits at exactly the large-band cap of 40 files, so a new page would have failed `documentation-layout` for a reason unrelated to its content. This also corrects that file's opening, which said `ward doctor` validates the YAML. It will not, once #1299 cuts the runtime. ## One stale comment fixed `.ward/ward.yaml` claimed it survived "because check_catalog_block pins this exact path and catalog-trifecta wants README, AGENTS, and FEATURES to link it". No `check_catalog_block` exists, and catalog-trifecta dropped the requirement fleet-wide under inbox#385. Comment only, no behavior change. ## Not in scope No consumer code is touched, and no `.ward/ward.yaml` is added or removed anywhere. Whether the fleet should keep declaring a file nothing validates is a separate call. ## Validation `pre-commit run --all-files` passes, exit 0. `docs/ward-specs.md` lands at 100 lines and 6640 bytes against the large-band caps of 120 and 8000.

coilyco-ops added 1 commit

2026-08-27 10:26:04 +00:00

docs(ward): write the surviving .ward/ward.yaml schema into a writable repo

ci / aos-eval-tests (pull_request) Successful in 7s

Details

ci / ward-doctor (pull_request) Successful in 6s

Details

ci / aos-cli-tests (pull_request) Successful in 24s

Details

ci / gate (pull_request) Successful in 47s

Details

0094c74c52

Refs #1299.

Ward is archived this week and its `docs/ward-yaml.md` goes read-only with it,
while `.ward/ward.yaml` stays in 15 of the 16 repositories on this host. The
schema outliving its own documentation is the seam this closes.

## What the sweep actually found

The schema is not dead, and it is not what Ward documented either.

* **Live consumers, none of them Ward.** `agentic-os-kai/scripts/pull-capabilities.py`
  reads a `capabilities:` list that was never in Ward's schema at all, and
  `eco-mods/scripts/ci-root-hygiene.sh` asserts the file exists.
* **`catalog.description` and `catalog.dependsOn` have no code reader on this
  host.** They are declared nearly everywhere. Recorded as an honest gap rather
  than described as live inputs.
* **Two different files share the name.** A root `ward.yaml` carrying
  `tailnet.shortcut` is fetched over the Forgejo API by
  `infrastructure/scripts/generate-caddy-shortcuts.py`. It is a separate path,
  schema, and consumer from `.ward/ward.yaml`, and only `pull-capabilities.py`
  accepts both. Worth writing down before someone conflates them.
* **`commands` and `security` are retired**, to the justfile (inbox#366) and to
  AOSguard plus umbra respectively.

## Placement

Folded into `docs/ward-specs.md` rather than given its own page. That doc is
already the AOS-side Ward boundary page and AGENTS.md already points at it, and
`docs/` sits at exactly the large-band cap of 40 files, so a new page would have
failed documentation-layout for a reason unrelated to its content.

Also corrects that file's opening, which said `ward doctor` validates the YAML.
It will not once #1299 cuts the runtime.

## One stale comment fixed

`.ward/ward.yaml` claimed it survived "because check_catalog_block pins this
exact path and catalog-trifecta wants README, AGENTS, and FEATURES to link it".
No `check_catalog_block` exists, and catalog-trifecta dropped the requirement
fleet-wide under inbox#385. Comment only, no behavior.

`pre-commit run --all-files` passes, exit 0.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Agent-Role: tpm

coilyco-ops merged commit aec61571cc into main

2026-08-27 10:27:34 +00:00

coilyco-ops referenced this pull request from a commit

2026-08-27 10:27:34 +00:00

docs(ward): write the surviving .ward/ward.yaml schema into a writable repo (#1328)

coilyco-ops referenced this pull request

2026-08-27 10:28:04 +00:00

Freeze Ward as a contract: cut its runtime from AOS CI and the dev-base image #1299

coilyco-ops referenced this pull request

2026-08-27 10:28:25 +00:00

Decide whether 15 repos keep declaring .ward/ward.yaml, now that no validator reads it #1329

coilyco-ops referenced this pull request from a commit