Scrub the noun "carry" jargon repo-wide: say "engineer" (keep carry as a verb) #403

New issue

Closed

opened 2026-07-01 06:13:08 +00:00 by coilysiren · 1 comment

coilysiren commented

2026-07-01 06:13:08 +00:00

Owner

Filed from the read-only director surface (she/her).

Goal

"carry" has drifted into a noun-synonym for the engineer role across docs, comments, and user-facing strings. Where it stands in for the engineer, say engineer. This is a behavior-preserving terminology sweep, not a logic change. Do it in the proper way: "carry" has three senses and only one gets scrubbed - a blind s/carry/engineer/ would break the other two.

Scope (measured in /substrate/ward)

carry-family hits: docs ~109, Go ~239 (153 non-test). Most are the verb or the possess-sense and must be left alone. Read each in context.

The three buckets

1. KEEP - "carry" as a VERB (engineer carries an issue)

Idiomatic, it is the docs' own voice. Do not touch:

"carry an issue end to end", "carry a single feature start to merge", "filed there and carried", "never commit, push, or carry work to merge" (advisor doc).

2. KEEP - "carry" as ordinary English (possess / bear)

Unrelated to the role. Do not touch:

"ward.* labels carry identity" (container.md:18), "Repos carry no lockdown" (container-permissions.md:41), "Three knobs carry this" (agent-attribution.md:52), "likelier to carry a rotated token" (container_reap_compute.go:179), "the per-role docs... carry the prose detail" (agent_roster.go:104).

3. SCRUB - "carry" as a NOUN meaning the engineer run -> engineer (or "engineer run")

This is the whole point. Examples:

docs: "The engineer carry always detaches" -> "The engineer always..."; "the launch flags the carry brings" (container.md:34); "the ref carry" / "the fire-and-forget carry" (agent-subcommands.md:12,27); "a detached engineer carry" (agent-director.md:43); "what the engineer carry does" (agent-subcommands.md:62); "An engineer carry additionally clears..." (container-cleanup.md:39).
code identifier: the dispatchCarry type and its carry dispatchCarry params / d.cfg.carry (agent_director.go:861,897, agent_director_heartbeat.go:181). Rename in the same spirit (e.g. dispatchEngineer/engineerDispatch) if it stays clean and behavior-identical - update every reference and test. If a rename balloons risk, leave the identifier and fix the surrounding prose/comments; note the skip.

3b. SPECIAL CASE - the dispatch broker: "carry" means ANY dispatched run

agent_dispatch_broker.go serves both engineer and advisor (validateDispatchBrokerRequest allows both). So "the served carry", "carry log", "carry output" (:50,146,190,312-314) are not engineer-specific - scrub them to "run" / "dispatch" / "dispatched run", never "engineer". Same for --ts-sidecar carry (forward.go:38,74) - that is a container run, use "run".

Rules

Bias toward KEEP. If a "carry" is a verb or the possess-sense, leave it. Only scrub a noun that clearly stands for the engineer (bucket 3) or a generic dispatched run (3b).
Behavior-preserving. No logic, flag, command-name, container-name, or marker changes. The public ward agent engineer command and WARD-OUTCOME etc. are untouched. If a string is asserted by a test, update the test to match.
Follow existing voice (AGENTS.md): no em-dashes, no semicolons in prose.
Run pre-commit run --all-files before landing. Update docs/FEATURES.md only if a feature name actually changes (it should not - this is wording).

Deliverable

One sweep across docs/*.md, Go comments, and user-facing strings (Usage/log/Fprintf), plus the dispatchCarry identifier if clean. List in the retrospective any "carry" you deliberately kept and why (proves the buckets were applied, not a blind replace).

Mode

headless. Rules are explicit, no design fork - just judgment per the three buckets.

Filed from the read-only director surface (she/her). ## Goal "carry" has drifted into a noun-synonym for the **engineer** role across docs, comments, and user-facing strings. Where it stands in for the engineer, say **engineer**. This is a **behavior-preserving terminology sweep**, not a logic change. Do it **in the proper way**: "carry" has three senses and only one gets scrubbed - a blind `s/carry/engineer/` would break the other two. ## Scope (measured in /substrate/ward) carry-family hits: **docs ~109**, **Go ~239** (153 non-test). Most are the verb or the possess-sense and must be left alone. Read each in context. ## The three buckets ### 1. KEEP - "carry" as a VERB (engineer carries an issue) Idiomatic, it is the docs' own voice. Do **not** touch: - "carry an issue end to end", "carry a single feature start to merge", "filed there and carried", "never commit, push, or carry work to merge" (advisor doc). ### 2. KEEP - "carry" as ordinary English (possess / bear) Unrelated to the role. Do **not** touch: - "`ward.*` labels **carry** identity" (container.md:18), "Repos **carry** no lockdown" (container-permissions.md:41), "Three knobs **carry** this" (agent-attribution.md:52), "likelier to **carry** a rotated token" (container_reap_compute.go:179), "the per-role docs... **carry** the prose detail" (agent_roster.go:104). ### 3. SCRUB - "carry" as a NOUN meaning the engineer run -> **engineer** (or "engineer run") This is the whole point. Examples: - docs: "The **engineer carry** always detaches" -> "The engineer always..."; "the launch flags the **carry** brings" (container.md:34); "the ref **carry**" / "the fire-and-forget **carry**" (agent-subcommands.md:12,27); "a detached **engineer carry**" (agent-director.md:43); "what the **engineer carry** does" (agent-subcommands.md:62); "An **engineer carry** additionally clears..." (container-cleanup.md:39). - code identifier: the **`dispatchCarry`** type and its `carry dispatchCarry` params / `d.cfg.carry` (`agent_director.go:861,897`, `agent_director_heartbeat.go:181`). Rename in the same spirit (e.g. `dispatchEngineer`/`engineerDispatch`) **if** it stays clean and behavior-identical - update every reference and test. If a rename balloons risk, leave the identifier and fix the surrounding prose/comments; note the skip. ### 3b. SPECIAL CASE - the dispatch broker: "carry" means ANY dispatched run `agent_dispatch_broker.go` serves **both** engineer and advisor (`validateDispatchBrokerRequest` allows both). So "the served carry", "carry log", "carry output" (`:50,146,190,312-314`) are **not** engineer-specific - scrub them to **"run"** / **"dispatch"** / **"dispatched run"**, never "engineer". Same for `--ts-sidecar carry` (`forward.go:38,74`) - that is a container run, use "run". ## Rules - **Bias toward KEEP.** If a "carry" is a verb or the possess-sense, leave it. Only scrub a noun that clearly stands for the engineer (bucket 3) or a generic dispatched run (3b). - **Behavior-preserving.** No logic, flag, command-name, container-name, or marker changes. The public `ward agent engineer` command and `WARD-OUTCOME` etc. are untouched. If a string is asserted by a test, update the test to match. - **Follow existing voice** (AGENTS.md): no em-dashes, no semicolons in prose. - Run `pre-commit run --all-files` before landing. Update `docs/FEATURES.md` only if a feature name actually changes (it should not - this is wording). ## Deliverable One sweep across `docs/*.md`, Go comments, and user-facing strings (Usage/log/Fprintf), plus the `dispatchCarry` identifier if clean. List in the retrospective any "carry" you deliberately kept and why (proves the buckets were applied, not a blind replace). ## Mode headless. Rules are explicit, no design fork - just judgment per the three buckets.

coilysiren referenced this issue from a commit

2026-07-01 06:34:05 +00:00

refactor(agent): scrub the noun "carry" jargon, say "engineer"/"run" (closes #403)

coilysiren closed this issue

2026-07-01 06:34:05 +00:00

coilysiren commented

2026-07-01 06:34:52 +00:00

Author

Owner

WARD-OUTCOME: done - scrubbed the noun "carry" to "engineer"/"run" across docs, Go, skills, and the entrypoint, merged and pushed to main.

The three-bucket framing in the body did the hard thinking, so this was less "decide" than "read every hit in context and resist the easy replace." That restraint was the whole job: of ~125 doc and ~265 Go hits, the big majority were the verb or the possess sense and had to stay. Bucket 3b earned its keep - the dispatch broker and the ts-sidecar/host-net comments really do serve advisor too, so "run" was correct exactly where "engineer" would have been wrong.

Judgment calls I made: I extended past the measured docs/+Go scope into README, .gitignore, Makefile, the two skills, and entrypoint.sh, since they carried the identical jargon and the title says repo-wide. I renamed dispatchCarry -> dispatchEngineer and its carry field -> dispatch (behavior-identical, every reference and test updated), kept every "carry-to-merge" compound (verb sense), and left README's stale --watch mention alone as out of scope.

Confidence is high: build/vet/test green, pre-commit clean, golangci reported 0 new findings. One thing that fought back: a mid-run merge from main quietly re-introduced fresh "carry" nouns from ward#402's reservation WARN, which I caught and scrubbed in a follow-up commit. Deliberately kept: "labels carry identity", "results carry the highest", "carry an issue end to end", "carry work to merge". Nothing worth filing.

WARD-OUTCOME: done - scrubbed the noun "carry" to "engineer"/"run" across docs, Go, skills, and the entrypoint, merged and pushed to main. The three-bucket framing in the body did the hard thinking, so this was less "decide" than "read every hit in context and resist the easy replace." That restraint was the whole job: of ~125 doc and ~265 Go hits, the big majority were the verb or the possess sense and had to stay. Bucket 3b earned its keep - the dispatch broker and the ts-sidecar/host-net comments really do serve advisor too, so "run" was correct exactly where "engineer" would have been wrong. Judgment calls I made: I extended past the measured docs/+Go scope into README, .gitignore, Makefile, the two skills, and entrypoint.sh, since they carried the identical jargon and the title says repo-wide. I renamed dispatchCarry -> dispatchEngineer and its `carry` field -> `dispatch` (behavior-identical, every reference and test updated), kept every "carry-to-merge" compound (verb sense), and left README's stale --watch mention alone as out of scope. Confidence is high: build/vet/test green, pre-commit clean, golangci reported 0 new findings. One thing that fought back: a mid-run merge from main quietly re-introduced fresh "carry" nouns from ward#402's reservation WARN, which I caught and scrubbed in a follow-up commit. Deliberately kept: "labels carry identity", "results carry the highest", "carry an issue end to end", "carry work to merge". Nothing worth filing.