Four distinct systems are named with two synonyms for one concept #1029

New issue

Open

opened 2026-08-12 17:35:55 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-12 17:35:55 +00:00

Member

The defect

Ward is a synonym for guard. The portfolio has four distinct systems whose names are built from those two words:

Name	What it is	Repository
`ward`	governed execution layer for unattended agents	`coilyco-flight-deck/ward`
`cli-guard`	security framework for guarded command-line tools	`coilyco-flight-deck/cli-guard`
`aosguard`	guarded operator verbs generated by specgen	this repository
`.guardfile.kdl` / `.mcp.kdl`	the grant documents themselves	authored in `coilyco-bridge/deploy`

Plus the sub-namespaces: ward exec, ward-mcp, .ward/ward.yaml, aosguard ops, and cli-guard's *.guardfile.kdl discovery glob.

This is not accidental collision. The same metaphor was independently reached for four times, so the names assert a family relationship that does not exist. cli-guard and aosguard are separate generators with separate descriptor sets; ward-mcp pins cli-guard rather than containing it; ward and aosguard share no machinery at all.

Worse, the systems are genuinely similar in kind — several produce guarded verbs from a spec, in Go, under the same org. Similar things with synonymous names is the hardest case to keep straight, because substring similarity carries almost no information while feeling like it carries a lot.

Evidence, from a real failure

2026-08-12, coilyco-gaming/sirens-echo session. Reconstructed rather than summarised, because the mechanism matters more than the outcome.

Misparsed a possessive. services/forgejo-mcp/forgejo.mcp.kdl reads "parsed by opcore.ParseInline from ward-mcp's pinned cli-guard." That means "the cli-guard that ward-mcp pins" — a dependency. It was read as "ward-mcp's cli-guard" — a component. English possessives do both jobs, so one token of ambiguity put opcore in the wrong repository.
Searched for the belief, not against it. search_repository "ward" returned exactly one clean hit, which felt conclusive because the four names read as one family. Searching cli-guard — one call — would have falsified it instantly.
Quoted the disambiguator without reading it. aosguard --version is aos-v0.195.0. That prefix was pasted into the filed issue as supporting detail. It says agentic-os, and it was invisible because "aos", "ward", and "guard" were all one undifferentiated space.
Filed coilyco-flight-deck/ward#1656 against the wrong repository, and cited aosguard's method resolution as evidence about ward's internals. Both wrong, both withdrawn, refiled as coilyco-flight-deck/cli-guard#281. The related guardfile ask at coilyco-bridge/deploy#395 also had to be corrected, since it framed the gap as a "parity gap between two surfaces" — they share an API, not machinery.

Steps 2 and 3 are the ones this issue is about. Distinct family names would have prevented both: a ward search would have said nothing about where opcore lives, forcing a search for opcore itself, and a foreign aos- prefix on a tool believed to be ward's would have been jarring rather than unremarkable.

Steps 1 and 4 would have survived a rename. The possessive is grammatical, and reaching for weak corroboration is a reasoning failure that would have found some other bad link.

So: a rename addresses half of this specific incident. Claiming more would be overselling it.

Why file it anyway

The case for renaming is not that one agent got confused once. It is that this tax is paid on every read, by every new contributor and every model, forever, and the failure is silent — a plausible wrong conclusion rather than an error. The incident above is simply the cheapest available evidence, because it produced three misfiled or miswritten artifacts in one session and each one was caught.

Constraint: a partial rename is worse than none

ward carries 812 releases, cli-guard 130. The names are load-bearing in guardfile headers, ward exec verbs across every AGENTS.md, pinned image references, workflow scripts, and years of cross-repository issue references (ward#151, ward-mcp#6, ward#380, cli-guard's discovery glob).

Two names for one thing during a transition is precisely the confusion this would be trying to remove. Either commit to finishing a rename or do not start it.

Options, cheapest first

Fix the sentence that caused step 1. "parsed by opcore.ParseInline from cli-guard, which ward-mcp pins." One line, zero churn, removes the possessive ambiguity. Worth doing regardless of everything below.
Rename only the least-entrenched system off the guard/ward metaphor. Breaks the false family without touching the entrenched names. Needs a count of inbound references per system to identify which that is — likely aosguard, since it is the newest surface here, but that should be measured rather than assumed.
Full family rename, with a decided target vocabulary and a completed migration including docs, headers, verbs, and cross-repo references.
Document instead of rename. #1028 already specs a concept skill carrying aosguard is not ward as an explicit negative fact. That is the cheapest approximation of the rename's benefit and it is already decided, so option 4 partially ships whether or not this issue does.

Recommendation

Option 1 now, unconditionally. Then measure inbound references and decide between 2 and 3 with real numbers rather than impressions. Option 4 is already in flight.

Do not treat 4 as a substitute for 2 or 3 if the tax is judged worth removing — documentation tells a reader the family is false, while a name stops asserting it in the first place.

coilyco-flight-deck/agentic-os#1028 — per-entity aosguard skills plus the concept skill.
coilyco-flight-deck/cli-guard#281 — the correctly-filed method-table question.
coilyco-flight-deck/ward#1656 — closed, misfiled, retained as the record of the error.
coilyco-bridge/deploy#395 — the guardfile ask whose framing had to be corrected.

## The defect *Ward* is a synonym for *guard*. The portfolio has four distinct systems whose names are built from those two words: | Name | What it is | Repository | | --- | --- | --- | | `ward` | governed execution layer for unattended agents | `coilyco-flight-deck/ward` | | `cli-guard` | security framework for guarded command-line tools | `coilyco-flight-deck/cli-guard` | | `aosguard` | guarded operator verbs generated by specgen | this repository | | `*.guardfile.kdl` / `*.mcp.kdl` | the grant documents themselves | authored in `coilyco-bridge/deploy` | Plus the sub-namespaces: `ward exec`, `ward-mcp`, `.ward/ward.yaml`, `aosguard ops`, and cli-guard's `*.guardfile.kdl` discovery glob. This is not accidental collision. The same metaphor was independently reached for four times, so **the names assert a family relationship that does not exist**. cli-guard and aosguard are separate generators with separate descriptor sets; ward-mcp pins cli-guard rather than containing it; `ward` and `aosguard` share no machinery at all. Worse, the systems are genuinely similar in *kind* — several produce guarded verbs from a spec, in Go, under the same org. Similar things with synonymous names is the hardest case to keep straight, because substring similarity carries almost no information while feeling like it carries a lot. ## Evidence, from a real failure 2026-08-12, `coilyco-gaming/sirens-echo` session. Reconstructed rather than summarised, because the mechanism matters more than the outcome. 1. **Misparsed a possessive.** `services/forgejo-mcp/forgejo.mcp.kdl` reads *"parsed by `opcore.ParseInline` from ward-mcp's pinned cli-guard."* That means "the cli-guard that ward-mcp pins" — a dependency. It was read as "ward-mcp's cli-guard" — a component. English possessives do both jobs, so one token of ambiguity put `opcore` in the wrong repository. 2. **Searched for the belief, not against it.** `search_repository "ward"` returned exactly one clean hit, which felt conclusive **because the four names read as one family**. Searching `cli-guard` — one call — would have falsified it instantly. 3. **Quoted the disambiguator without reading it.** `aosguard --version` is `aos-v0.195.0`. That prefix was pasted into the filed issue as supporting detail. It says *agentic-os*, and it was invisible because "aos", "ward", and "guard" were all one undifferentiated space. 4. **Filed `coilyco-flight-deck/ward#1656` against the wrong repository**, and cited aosguard's method resolution as evidence about ward's internals. Both wrong, both withdrawn, refiled as `coilyco-flight-deck/cli-guard#281`. The related guardfile ask at `coilyco-bridge/deploy#395` also had to be corrected, since it framed the gap as a "parity gap between two surfaces" — they share an API, not machinery. Steps 2 and 3 are the ones this issue is about. **Distinct family names would have prevented both**: a `ward` search would have said nothing about where `opcore` lives, forcing a search for `opcore` itself, and a foreign `aos-` prefix on a tool believed to be ward's would have been jarring rather than unremarkable. Steps 1 and 4 would have survived a rename. The possessive is grammatical, and reaching for weak corroboration is a reasoning failure that would have found some other bad link. So: **a rename addresses half of this specific incident.** Claiming more would be overselling it. ## Why file it anyway The case for renaming is not that one agent got confused once. It is that this tax is paid on every read, by every new contributor and every model, forever, and the failure is silent — a plausible wrong conclusion rather than an error. The incident above is simply the cheapest available evidence, because it produced three misfiled or miswritten artifacts in one session and each one was caught. ## Constraint: a partial rename is worse than none `ward` carries 812 releases, cli-guard 130. The names are load-bearing in guardfile headers, `ward exec` verbs across every `AGENTS.md`, pinned image references, workflow scripts, and years of cross-repository issue references (`ward#151`, `ward-mcp#6`, `ward#380`, `cli-guard`'s discovery glob). Two names for one thing during a transition is precisely the confusion this would be trying to remove. **Either commit to finishing a rename or do not start it.** ## Options, cheapest first 1. **Fix the sentence that caused step 1.** *"parsed by `opcore.ParseInline` from cli-guard, which ward-mcp pins."* One line, zero churn, removes the possessive ambiguity. Worth doing regardless of everything below. 2. **Rename only the least-entrenched system** off the guard/ward metaphor. Breaks the false family without touching the entrenched names. Needs a count of inbound references per system to identify which that is — likely `aosguard`, since it is the newest surface here, but that should be measured rather than assumed. 3. **Full family rename**, with a decided target vocabulary and a completed migration including docs, headers, verbs, and cross-repo references. 4. **Document instead of rename.** `#1028` already specs a concept skill carrying *aosguard is not ward* as an explicit negative fact. That is the cheapest approximation of the rename's benefit and it is already decided, so option 4 partially ships whether or not this issue does. ## Recommendation Option 1 now, unconditionally. Then measure inbound references and decide between 2 and 3 with real numbers rather than impressions. Option 4 is already in flight. Do not treat 4 as a substitute for 2 or 3 if the tax is judged worth removing — documentation tells a reader the family is false, while a name stops asserting it in the first place. ## Related * `coilyco-flight-deck/agentic-os#1028` — per-entity aosguard skills plus the concept skill. * `coilyco-flight-deck/cli-guard#281` — the correctly-filed method-table question. * `coilyco-flight-deck/ward#1656` — closed, misfiled, retained as the record of the error. * `coilyco-bridge/deploy#395` — the guardfile ask whose framing had to be corrected.

coilyco-ops added the

labels

2026-08-17 02:36:43 +00:00