coilyco-flight-deck/ward

Watch

Give Ward's high-level domain objects human names #1640

New issue

Closed

opened 2026-08-05 06:33:45 +00:00 by coilyco-ops · 2 comments

coilyco-ops commented

2026-08-05 06:33:45 +00:00

Member

Outcome

Give Ward's high-level domain objects comfortable human names, then align documentation and user-visible surfaces around one coherent vocabulary.

Two names are already selected:

A supervised Docker Compose project, currently called a collaboration cluster, is a flight.
The per-flight service currently called the broker is the dispatcher.

Use the flight metaphor only where it names real domain objects. Do not spread aviation language across every role, lifecycle state, command, artifact, or recovery path.

Current evidence

Ward already has a terminology inventory and several load-bearing distinctions, but much of the top-level vocabulary still exposes implementation structure or requires readers to memorize overlapping system states.

The most collision-prone families are:

work, issue, ref, task, backlog, queue, and lane
agent, worker, peer, role, harness, model, and CLI
cluster, broker, dispatch, launch, run, container, and workspace
reservation, launch intent, running engineer, and capacity
workflow, submitted, merge-ready, done, blocked, failed, terminal outcome, and parked outcome
stop, reap, cleanup, drain, salvage, rescue, and recover
substrate, context bundle, ledger, and dispatch artifact

The current terminology rule says flight language is analogy-only and stable CLI commands must not be renamed during terminology cleanup. Both statements should be reconsidered. flight and dispatcher are intended product concepts, and stable CLI spellings are compatibility constraints rather than permanent naming vetoes.

Scope

Define the small human-facing object model before changing prose.
Give each high-level concept one preferred product name.
Separate product vocabulary from precise protocol, storage, Docker, and implementation terms.
Keep implementation terms available where technical reference material needs them.
Reserve flight for the Compose-project collaboration entity and dispatcher for its internal coordination service.
Audit the remaining vocabulary for implementation leakage, overload, and synonyms that describe the same object.
Update README, terminology, architecture, lifecycle, agent, container, troubleshooting, feature, command-help, prompt, and skill surfaces that expose the selected concepts.
Coordinate documentation placement with #1624 and the human-versus-agent boundary in #1631.
Remove the blanket rule against renaming stable CLI commands.
Evaluate CLI renames individually. A rename may proceed when the human model materially improves and the issue includes an explicit alias, warning, migration, or removal plan proportionate to the compatibility cost.
Preserve exact machine-readable field names and compatibility parsers until their own migration is deliberately approved.

Acceptance

flight unambiguously means one supervised Compose project and its shared lifecycle identity.
dispatcher unambiguously means the per-flight service that accepts requests, coordinates participants, mediates bounded operations, and protects credentials.
The docs do not turn the rest of Ward into an aviation thesaurus.
Every retained high-level term has one preferred human meaning and a documented relationship to any lower-level compatibility name.
Product prose no longer requires readers to understand implementation terms merely to understand the system.
Agent-facing instructions retain the exact distinctions agents need to act safely.
CLI names are assessed rather than automatically preserved or automatically renamed.
Any CLI rename includes tested compatibility behavior and clear migration output.
README, terminology, architecture, FEATURES, detailed docs, embedded help, prompts, and shipped skills agree after the change.
Repository validation passes.

Non-goals

Renaming every internal identifier to match product prose.
Adding flight-themed synonyms for concepts that already have comfortable ordinary names.
Hiding Docker, protocol, storage, or security terminology from technical reference pages.
Bundling unrelated feature or authority changes into the vocabulary pass.

## Outcome Give Ward's high-level domain objects comfortable human names, then align documentation and user-visible surfaces around one coherent vocabulary. Two names are already selected: * A supervised Docker Compose project, currently called a collaboration cluster, is a `flight`. * The per-flight service currently called the broker is the `dispatcher`. Use the flight metaphor only where it names real domain objects. Do not spread aviation language across every role, lifecycle state, command, artifact, or recovery path. ## Current evidence Ward already has a terminology inventory and several load-bearing distinctions, but much of the top-level vocabulary still exposes implementation structure or requires readers to memorize overlapping system states. The most collision-prone families are: * work, issue, ref, task, backlog, queue, and lane * agent, worker, peer, role, harness, model, and CLI * cluster, broker, dispatch, launch, run, container, and workspace * reservation, launch intent, running engineer, and capacity * workflow, submitted, merge-ready, done, blocked, failed, terminal outcome, and parked outcome * stop, reap, cleanup, drain, salvage, rescue, and recover * substrate, context bundle, ledger, and dispatch artifact The current terminology rule says flight language is analogy-only and stable CLI commands must not be renamed during terminology cleanup. Both statements should be reconsidered. `flight` and `dispatcher` are intended product concepts, and stable CLI spellings are compatibility constraints rather than permanent naming vetoes. ## Scope * Define the small human-facing object model before changing prose. * Give each high-level concept one preferred product name. * Separate product vocabulary from precise protocol, storage, Docker, and implementation terms. * Keep implementation terms available where technical reference material needs them. * Reserve `flight` for the Compose-project collaboration entity and `dispatcher` for its internal coordination service. * Audit the remaining vocabulary for implementation leakage, overload, and synonyms that describe the same object. * Update README, terminology, architecture, lifecycle, agent, container, troubleshooting, feature, command-help, prompt, and skill surfaces that expose the selected concepts. * Coordinate documentation placement with #1624 and the human-versus-agent boundary in #1631. * Remove the blanket rule against renaming stable CLI commands. * Evaluate CLI renames individually. A rename may proceed when the human model materially improves and the issue includes an explicit alias, warning, migration, or removal plan proportionate to the compatibility cost. * Preserve exact machine-readable field names and compatibility parsers until their own migration is deliberately approved. ## Acceptance * `flight` unambiguously means one supervised Compose project and its shared lifecycle identity. * `dispatcher` unambiguously means the per-flight service that accepts requests, coordinates participants, mediates bounded operations, and protects credentials. * The docs do not turn the rest of Ward into an aviation thesaurus. * Every retained high-level term has one preferred human meaning and a documented relationship to any lower-level compatibility name. * Product prose no longer requires readers to understand implementation terms merely to understand the system. * Agent-facing instructions retain the exact distinctions agents need to act safely. * CLI names are assessed rather than automatically preserved or automatically renamed. * Any CLI rename includes tested compatibility behavior and clear migration output. * README, terminology, architecture, FEATURES, detailed docs, embedded help, prompts, and shipped skills agree after the change. * Repository validation passes. ## Non-goals * Renaming every internal identifier to match product prose. * Adding flight-themed synonyms for concepts that already have comfortable ordinary names. * Hiding Docker, protocol, storage, or security terminology from technical reference pages. * Bundling unrelated feature or authority changes into the vocabulary pass.

coilyco-ops added the

autonomy

async-consult

label

2026-08-05 06:33:52 +00:00

coilyco-ops commented

2026-08-05 09:34:03 +00:00

Author

Member

Cross-repository vocabulary ownership moved to coilysiren/inbox#331.

This Ward issue now owns only the Ward-local implementation after inbox#331 resolves the canonical object model, cross-repository consumer inventory, and compatibility treatment for each approved rename. Keep this issue in consult and do not dispatch it until that parent decision produces an exact Ward slice.

Cross-repository vocabulary ownership moved to https://forgejo.coilysiren.me/coilysiren/inbox/issues/331. This Ward issue now owns only the Ward-local implementation after inbox#331 resolves the canonical object model, cross-repository consumer inventory, and compatibility treatment for each approved rename. Keep this issue in `consult` and do not dispatch it until that parent decision produces an exact Ward slice.

coilyco-ops commented

2026-08-05 09:35:02 +00:00

Author

Member

Scope correction: this issue is fully transferred to coilysiren/inbox#331 and is superseded here.

The inbox issue owns the shared object model, compatibility decisions, and cross-repository consumer inventory. Create new Ward implementation issues only after those decisions produce exact Ward-local slices. Closing this ticket removes the unresolved portfolio decision from the Ward queue.

Scope correction: this issue is fully transferred to https://forgejo.coilysiren.me/coilysiren/inbox/issues/331 and is superseded here. The inbox issue owns the shared object model, compatibility decisions, and cross-repository consumer inventory. Create new Ward implementation issues only after those decisions produce exact Ward-local slices. Closing this ticket removes the unresolved portfolio decision from the Ward queue.

coilyco-ops closed this issue

2026-08-05 09:35:03 +00:00

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

coilyco-flight-deck/ward#1640

No description provided.

Rows
Columns