Codify Ward’s terminology and metaphor system

coilysiren commented

2026-07-18 20:47:25 +00:00

Owner

Context

Ward has accumulated a substantial operational vocabulary across the CLI, implementation, documentation, issues, and normal development conversation.

Some terms come from established systems domains:

process and container lifecycle
schedulers and queues
source-control workflows
fleet operations
security boundaries
supervision and recovery

Other language draws more loosely from the semantic space around Ward itself. The repository also lives under coilyco-flight-deck, and flight-deck language already aligns naturally with parts of the product: dispatch, launch, active fleets, intervention, recovery, recording, and landing.

This flexibility has been useful. It has allowed concise terms such as reap and drain to develop without forcing Ward into one overly literal metaphor.

It also creates ambiguity:

The same verb may be used for different lifecycle transitions.
Adjacent verbs may be treated as stylistic synonyms despite having different operational meanings.
Agents rewriting documentation may normalize deliberate distinctions away.
New concepts may receive names from whichever metaphor is most salient during that session.
The product lacks one place explaining how its vocabulary fits together.
Readers may over-index on one interpretation of “ward” and miss the broader operational model.

Goal

Document Ward’s existing conceptual vocabulary and establish enough coherence that:

Important lifecycle and architecture terms have explicit meanings.
Terms that represent different states or transitions are not casually interchanged.
Overloaded terms are identified and resolved deliberately.
Documentation and agent instructions can link to one canonical terminology source.
Ward retains room for metaphor and expressive language without allowing metaphor to obscure implementation semantics.
The flight-deck framing is available as a first-class explanatory analogy where it improves comprehension.

This issue should discover and codify the terminology rather than beginning with a prescribed replacement glossary.

Work

Inventory the current vocabulary

Collect terms from:

CLI commands and flags
README and FEATURES
architecture and lifecycle documentation
code-level state names
issues and pull requests
audit records
operator-facing output
agent-facing instructions

Group terms by the concept they currently appear to represent.

Likely areas include:

incoming work
assignment and dispatch
execution lifecycle
agent and harness identity
containment and authority
supervision
queue and fleet behavior
cleanup and recovery
completion and repository outcomes
release and deployment lifecycle

The inventory should describe observed usage without assuming that every current usage is correct.

Identify ambiguity

For each material term, determine:

Whether it has one meaning or several.
Whether those meanings are compatible.
Whether another term is being used for the same concept.
Whether the distinction is implementation-significant.
Whether the term relies on established technical usage.
Whether it is primarily product metaphor.
Whether users or agents are likely to infer the wrong behavior from it.

Pay particular attention to cases where:

two commands sound equivalent but are not;
one term refers to both runtime state and durable state;
one verb is used in separate queue, process, and repository contexts;
documentation varies between harness, worker, agent, run, workflow, or role;
release terminology conflicts with runtime lifecycle terminology.

Define the conceptual relationships

Produce a small model showing the important objects, transitions, and ownership boundaries in Ward.

The model should answer questions such as:

What receives work?
What is created when work begins?
What persists after a process exits?
What does Ward supervise?
What does the harness own?
What does the execution environment own?
What exactly reaches a terminal state?
What actions affect one run versus the wider fleet?
What represents successful software delivery versus successful process termination?

This can be a diagram, transition table, prose model, or combination thereof.

Build an analogy bank

Document several concise ways to explain Ward to different audiences without treating any single analogy as the complete architecture.

Include at least:

a direct non-metaphorical description;
a platform/workload-management description;
a software-delivery description;
a security-boundary description;
a process-supervision description;
a flight-deck description.

The flight-deck version should explore the useful correspondence among concepts such as:

dispatch
launch
fleet visibility
active supervision
intervention or abort
recovery
flight recording
landing

This is explanatory language, not a requirement to rename every command using aviation terminology.

Establish terminology guidance

Add a canonical documentation page that records:

preferred terms;
their meanings;
important non-equivalences;
deliberately overloaded terms, where retained;
deprecated or confusing usages;
which distinctions are normative;
how new terminology should be evaluated.

Link it from the relevant architecture, lifecycle, README, and agent-facing documentation.

Align existing documentation

Update conflicting uses where the terminology review identifies genuine semantic drift.

Do not perform broad stylistic rewriting merely to make every page use the same metaphor. Preserve established technical terms when they are accurate.

Non-goals

Renaming Ward.
Replacing every current term.
Forcing the product into a hospital, prison, security, factory, or aviation metaphor.
Producing a cute vocabulary at the expense of technical precision.
Renaming stable CLI commands without a demonstrated ambiguity.
Rewriting all documentation as part of this issue.
Treating ordinary prose variation as an API compatibility problem.
Defining Factory Worker terminology; that project may share analogies but has its own conceptual boundary.

Deliverables

A current terminology inventory.
A list of concrete ambiguities or collisions.
A conceptual object/lifecycle model.
A small audience-oriented analogy bank, including flight-deck framing.
One canonical terminology document.
Links to that document from the primary architecture and agent-facing entry points.
Focused corrections for usages found to be materially misleading.

Acceptance criteria

Current CLI, code, docs, and agent-facing terminology has been sampled and inventoried.
Materially overloaded or conflicting terms are explicitly recorded.
The relationship between work, execution, supervision, and terminal outcomes is documented.
Important terms are defined by operational meaning rather than only by metaphor.
Flight-deck framing is included as an explanatory vocabulary source.
No single metaphor is declared mandatory for all product terminology.
A canonical terminology page exists and is linked from the primary documentation surfaces.
Agent instructions direct terminology changes toward the canonical page rather than improvising synonyms.
Any CLI rename or compatibility churn discovered during the work is filed separately rather than silently bundled into this issue.

Design constraint

Ward’s vocabulary should remain expressive and capable of growing.

The objective is not to eliminate the broad semantic and metaphorical space around the project. It is to ensure that flexibility remains intentional—and that the system’s actual state transitions are still understandable when the metaphor is removed.

Context Ward has accumulated a substantial operational vocabulary across the CLI, implementation, documentation, issues, and normal development conversation. Some terms come from established systems domains: * process and container lifecycle * schedulers and queues * source-control workflows * fleet operations * security boundaries * supervision and recovery Other language draws more loosely from the semantic space around Ward itself. The repository also lives under coilyco-flight-deck, and flight-deck language already aligns naturally with parts of the product: dispatch, launch, active fleets, intervention, recovery, recording, and landing. This flexibility has been useful. It has allowed concise terms such as reap and drain to develop without forcing Ward into one overly literal metaphor. It also creates ambiguity: * The same verb may be used for different lifecycle transitions. * Adjacent verbs may be treated as stylistic synonyms despite having different operational meanings. * Agents rewriting documentation may normalize deliberate distinctions away. * New concepts may receive names from whichever metaphor is most salient during that session. * The product lacks one place explaining how its vocabulary fits together. * Readers may over-index on one interpretation of “ward” and miss the broader operational model. Goal Document Ward’s existing conceptual vocabulary and establish enough coherence that: 1. Important lifecycle and architecture terms have explicit meanings. 2. Terms that represent different states or transitions are not casually interchanged. 3. Overloaded terms are identified and resolved deliberately. 4. Documentation and agent instructions can link to one canonical terminology source. 5. Ward retains room for metaphor and expressive language without allowing metaphor to obscure implementation semantics. 6. The flight-deck framing is available as a first-class explanatory analogy where it improves comprehension. This issue should discover and codify the terminology rather than beginning with a prescribed replacement glossary. Work Inventory the current vocabulary Collect terms from: * CLI commands and flags * README and FEATURES * architecture and lifecycle documentation * code-level state names * issues and pull requests * audit records * operator-facing output * agent-facing instructions Group terms by the concept they currently appear to represent. Likely areas include: * incoming work * assignment and dispatch * execution lifecycle * agent and harness identity * containment and authority * supervision * queue and fleet behavior * cleanup and recovery * completion and repository outcomes * release and deployment lifecycle The inventory should describe observed usage without assuming that every current usage is correct. Identify ambiguity For each material term, determine: * Whether it has one meaning or several. * Whether those meanings are compatible. * Whether another term is being used for the same concept. * Whether the distinction is implementation-significant. * Whether the term relies on established technical usage. * Whether it is primarily product metaphor. * Whether users or agents are likely to infer the wrong behavior from it. Pay particular attention to cases where: * two commands sound equivalent but are not; * one term refers to both runtime state and durable state; * one verb is used in separate queue, process, and repository contexts; * documentation varies between harness, worker, agent, run, workflow, or role; * release terminology conflicts with runtime lifecycle terminology. Define the conceptual relationships Produce a small model showing the important objects, transitions, and ownership boundaries in Ward. The model should answer questions such as: * What receives work? * What is created when work begins? * What persists after a process exits? * What does Ward supervise? * What does the harness own? * What does the execution environment own? * What exactly reaches a terminal state? * What actions affect one run versus the wider fleet? * What represents successful software delivery versus successful process termination? This can be a diagram, transition table, prose model, or combination thereof. Build an analogy bank Document several concise ways to explain Ward to different audiences without treating any single analogy as the complete architecture. Include at least: * a direct non-metaphorical description; * a platform/workload-management description; * a software-delivery description; * a security-boundary description; * a process-supervision description; * a flight-deck description. The flight-deck version should explore the useful correspondence among concepts such as: * dispatch * launch * fleet visibility * active supervision * intervention or abort * recovery * flight recording * landing This is explanatory language, not a requirement to rename every command using aviation terminology. Establish terminology guidance Add a canonical documentation page that records: * preferred terms; * their meanings; * important non-equivalences; * deliberately overloaded terms, where retained; * deprecated or confusing usages; * which distinctions are normative; * how new terminology should be evaluated. Link it from the relevant architecture, lifecycle, README, and agent-facing documentation. Align existing documentation Update conflicting uses where the terminology review identifies genuine semantic drift. Do not perform broad stylistic rewriting merely to make every page use the same metaphor. Preserve established technical terms when they are accurate. Non-goals * Renaming Ward. * Replacing every current term. * Forcing the product into a hospital, prison, security, factory, or aviation metaphor. * Producing a cute vocabulary at the expense of technical precision. * Renaming stable CLI commands without a demonstrated ambiguity. * Rewriting all documentation as part of this issue. * Treating ordinary prose variation as an API compatibility problem. * Defining Factory Worker terminology; that project may share analogies but has its own conceptual boundary. Deliverables * A current terminology inventory. * A list of concrete ambiguities or collisions. * A conceptual object/lifecycle model. * A small audience-oriented analogy bank, including flight-deck framing. * One canonical terminology document. * Links to that document from the primary architecture and agent-facing entry points. * Focused corrections for usages found to be materially misleading. Acceptance criteria * Current CLI, code, docs, and agent-facing terminology has been sampled and inventoried. * Materially overloaded or conflicting terms are explicitly recorded. * The relationship between work, execution, supervision, and terminal outcomes is documented. * Important terms are defined by operational meaning rather than only by metaphor. * Flight-deck framing is included as an explanatory vocabulary source. * No single metaphor is declared mandatory for all product terminology. * A canonical terminology page exists and is linked from the primary documentation surfaces. * Agent instructions direct terminology changes toward the canonical page rather than improvising synonyms. * Any CLI rename or compatibility churn discovered during the work is filed separately rather than silently bundled into this issue. Design constraint Ward’s vocabulary should remain expressive and capable of growing. The objective is not to eliminate the broad semantic and metaphorical space around the project. It is to ensure that flexibility remains intentional—and that the system’s actual state transitions are still understandable when the metaphor is removed.

coilysiren commented

2026-07-18 22:46:52 +00:00

Author

Owner

Just thought up the term “warded flight ops” to refer to orchestration and I love it

coilysiren commented

2026-07-18 22:47:16 +00:00

Author

Owner

Something something nasa

coilyco-ops added the

labels

2026-07-28 08:47:27 +00:00

coilyco-ops referenced this issue from a commit

2026-07-28 10:08:42 +00:00

docs: codify Ward terminology

coilyco-ops closed this issue

2026-07-28 10:09:48 +00:00

coilyco-ops commented

2026-07-28 10:13:32 +00:00

Member

WARD-WORKFLOW: done ✅

details

workflow: merge-remote-main; review summary: skipped - in-container review gate intentionally skipped because the temporary Ward default is pending brokered QA.

summary: Added canonical terminology docs for vocabulary inventory, ambiguities, lifecycle model, and analogy frames; linked them from README, docs index, architecture, agent lifecycle/workflow, AGENTS, and agent skills.

validation: commit hooks passed; ward exec test passed on the feature branch and on pushed main.

landing: merged and pushed main at b44e0b82f3.

felt: mostly documentation archaeology; the doc-size caps forced a cleaner split than the first draft.

confidence: high.

surprises: aosguard task verification could not resolve SSM/IMDS credentials here; public Forgejo API showed run 2509 for this merge was cancelled by a newer main push and run 2510 was running.

follow-ups: no CLI rename or compatibility churn bundled; future terminology changes should update docs/terminology.md first.

WARD-WORKFLOW: done ✅ <details><summary>details</summary> workflow: merge-remote-main; review summary: skipped - in-container review gate intentionally skipped because the temporary Ward default is pending brokered QA. summary: Added canonical terminology docs for vocabulary inventory, ambiguities, lifecycle model, and analogy frames; linked them from README, docs index, architecture, agent lifecycle/workflow, AGENTS, and agent skills. validation: commit hooks passed; ward exec test passed on the feature branch and on pushed main. landing: merged and pushed main at b44e0b82f3a2a8af62084aeffc996c5651241df2. felt: mostly documentation archaeology; the doc-size caps forced a cleaner split than the first draft. confidence: high. surprises: aosguard task verification could not resolve SSM/IMDS credentials here; public Forgejo API showed run 2509 for this merge was cancelled by a newer main push and run 2510 was running. follow-ups: no CLI rename or compatibility churn bundled; future terminology changes should update docs/terminology.md first. </details>

coilyco-ops reopened this issue

2026-07-28 10:13:44 +00:00

coilyco-ops commented

2026-07-28 10:13:45 +00:00

Member

WARD-WORKFLOW: blocked 🛑

salvage details

An ephemeral ward container (codex mode) dispatched for this issue finished but its work was not merged to main, so cleanup preserved it on a branch before teardown and reopened the issue (a closing reference for #1484 never reached main). Recover from the salvage branch below.

Repo: coilyco-flight-deck/ward
Salvage branch: ward-salvage/ward-b87f8859
Pull request: not opened - salvage branch has no diff against main
Reason: merge conflict integrating onto main
Container uptime at reap: 15m (age of the baked Forgejo PAT snapshot; a long-lived container is likelier to carry a rotated token)

Cleanup diagnostics

--- reap diagnostics ---
ward version:      v0.823.0
version source:    pinned via WARD_VERSION/--ward-version (v0.823.0)
HEAD:              b44e0b82f3a2
origin/main:       423059f4232f
ancestry:          HEAD is ALREADY on origin/main - a salvage here is a FALSE salvage (ward#504 signature)
decision gate:     provenance missing or unreadable on already-landed merge-remote-main run
reason:            merge conflict integrating onto main
provenance:        missing or unreadable
run-owned landed:  no
working tree:      clean
container uptime:  15m (baked Forgejo PAT age proxy)
--- end reap diagnostics ---

Recover

git fetch https://forgejo.coilysiren.me/coilyco-flight-deck/ward.git ward-salvage/ward-b87f8859
git checkout -b ward-salvage/ward-b87f8859 FETCH_HEAD

— Codex, via ward agent

WARD-WORKFLOW: blocked 🛑 <details><summary>salvage details</summary> An ephemeral `ward container` (codex mode) dispatched for this issue finished but its work was **not merged to `main`**, so cleanup preserved it on a branch before teardown and reopened the issue (a closing reference for #1484 never reached `main`). Recover from the salvage branch below. - **Repo:** `coilyco-flight-deck/ward` - **Salvage branch:** `ward-salvage/ward-b87f8859` - **Pull request:** not opened - salvage branch has no diff against main - **Reason:** merge conflict integrating onto main - **Container uptime at reap:** 15m (age of the baked Forgejo PAT snapshot; a long-lived container is likelier to carry a rotated token) ## Cleanup diagnostics ``` --- reap diagnostics --- ward version: v0.823.0 version source: pinned via WARD_VERSION/--ward-version (v0.823.0) HEAD: b44e0b82f3a2 origin/main: 423059f4232f ancestry: HEAD is ALREADY on origin/main - a salvage here is a FALSE salvage (ward#504 signature) decision gate: provenance missing or unreadable on already-landed merge-remote-main run reason: merge conflict integrating onto main provenance: missing or unreadable run-owned landed: no working tree: clean container uptime: 15m (baked Forgejo PAT age proxy) --- end reap diagnostics --- ``` ## Recover ```bash git fetch https://forgejo.coilysiren.me/coilyco-flight-deck/ward.git ward-salvage/ward-b87f8859 git checkout -b ward-salvage/ward-b87f8859 FETCH_HEAD ``` </details>  — Codex, via `ward agent`

coilyco-ops commented

2026-07-28 10:13:45 +00:00

Member

WARD-WORKFLOW: reservation-released

release details

Run finished with WARD-WORKFLOW: blocked 🛑.

ward container reap released container engineer-codex-ward-1484 (--harness codex): the terminal outcome supersedes the reservation, so a later redispatch no longer needs --override-reservation.

— Codex, via ward agent

WARD-WORKFLOW: reservation-released <details><summary>release details</summary> Run finished with `WARD-WORKFLOW: blocked 🛑`. `ward container reap` released container `engineer-codex-ward-1484` (`--harness codex`): the terminal outcome supersedes the reservation, so a later redispatch no longer needs `--override-reservation`. </details>  — Codex, via `ward agent`

coilyco-ops commented

2026-07-28 10:14:55 +00:00

Member

Director cleanup: closing this manually because the run completed despite the later false salvage notice. Proof from the archived run: posted WARD-WORKFLOW: done; pushed main at b44e0b82; reaper diagnostics say HEAD is ALREADY on origin/main and salvage has no diff. The false-salvage bug is captured as coilyco-flight-deck/ward#1606.

Director cleanup: closing this manually because the run completed despite the later false salvage notice. Proof from the archived run: posted WARD-WORKFLOW: done; pushed main at b44e0b82; reaper diagnostics say HEAD is ALREADY on origin/main and salvage has no diff. The false-salvage bug is captured as coilyco-flight-deck/ward#1606.

coilyco-ops closed this issue

2026-07-28 10:15:04 +00:00

Rows
Columns

Codify Ward’s terminology and metaphor system #1484

Cleanup diagnostics

Recover