Standardize ward structured comments around WARD outcome markers

coilyco-ops commented

2026-07-08 21:08:14 +00:00

Owner

Goal

Standardize ward structured comments around literal WARD-<THING>: marker lines, without reworking comments that already migrated to the newer marker family.

Current direction

Kai confirmed on 2026-07-15 that this issue must be verified against current main before implementation because structured comments have moved a lot. In particular, many workflow comments appear to have already moved to literal WARD-WORKFLOW: ... lines.

The implementation should audit the current marker state first, then patch only real drift. Do not mechanically impose stale examples from this issue.

Product intent

Kai mostly scans run comments for roadblocks and workflow state that should roll forward into future work streams. Examples include missing packages, setup friction, failing scripts, wrong docs, missing image contents, broken harness launch shapes, and auth/network/setup friction.

The marker family should make those states parser-friendly and grep-friendly while leaving longer explanation in normal prose or details blocks.

Marker rules

Marker lines start with literal WARD-.
Emoji, if used, appears after the marker key, never before WARD-.
Current workflow-state comments should use the current literal marker shape, especially WARD-WORKFLOW: ... where that is already the active convention.
Older marker names such as WARD-OUTCOME: may remain only where they are still current after the audit.
Non-ward-prefixed automated markers should either migrate into the WARD-<THING>: family or be explicitly documented as legacy compatibility.

Preferred prefix shape:

WARD-WORKFLOW: failed
WARD-OUTCOME: warning text if this marker is still current after audit

Not:

warning WARD-OUTCOME: text

Do

Inventory current ward-written structured comments and marker strings, including reservation comments, workflow/release/failure comments, broker comments, review comments, PR body notes, advisory-only review notes, and retro comments.
Compare the current implementation to the literal WARD-<THING>: contract.
Preserve already-migrated WARD-WORKFLOW: ... comments instead of reverting them to older wording.
Patch remaining non-ward-prefixed automated markers only where the current implementation still emits them.
Update parsers/tests with backward compatibility where old comments can still exist on issue threads.
Document the current marker vocabulary and intended reader.

Acceptance

The PR starts by naming the current marker inventory and which markers still needed changes.
Workflow comments use the current literal WARD-WORKFLOW: ... shape where applicable.
Any remaining WARD-OUTCOME: usage is deliberate and documented, not copied from stale examples.
Reservation, broker, review, workflow, and retro structured comments consistently use literal WARD-<THING>: markers or documented legacy compatibility.
Tests cover parser compatibility for current markers and at least one legacy marker.
ward exec test passes, or the issue comment names the exact failing check.

Decision for headless carry

Headless, but verification-first. Kai specifically warned that the marker surface has moved and the engineer must not implement from stale issue text.

## Goal Standardize ward structured comments around literal `WARD-<THING>:` marker lines, without reworking comments that already migrated to the newer marker family. ## Current direction Kai confirmed on 2026-07-15 that this issue must be verified against current main before implementation because structured comments have moved a lot. In particular, many workflow comments appear to have already moved to literal `WARD-WORKFLOW: ...` lines. The implementation should audit the current marker state first, then patch only real drift. Do not mechanically impose stale examples from this issue. ## Product intent Kai mostly scans run comments for roadblocks and workflow state that should roll forward into future work streams. Examples include missing packages, setup friction, failing scripts, wrong docs, missing image contents, broken harness launch shapes, and auth/network/setup friction. The marker family should make those states parser-friendly and grep-friendly while leaving longer explanation in normal prose or details blocks. ## Marker rules * Marker lines start with literal `WARD-`. * Emoji, if used, appears after the marker key, never before `WARD-`. * Current workflow-state comments should use the current literal marker shape, especially `WARD-WORKFLOW: ...` where that is already the active convention. * Older marker names such as `WARD-OUTCOME:` may remain only where they are still current after the audit. * Non-ward-prefixed automated markers should either migrate into the `WARD-<THING>:` family or be explicitly documented as legacy compatibility. Preferred prefix shape: ```text WARD-WORKFLOW: failed WARD-OUTCOME: warning text if this marker is still current after audit ``` Not: ```text warning WARD-OUTCOME: text ``` ## Do * Inventory current ward-written structured comments and marker strings, including reservation comments, workflow/release/failure comments, broker comments, review comments, PR body notes, advisory-only review notes, and retro comments. * Compare the current implementation to the literal `WARD-<THING>:` contract. * Preserve already-migrated `WARD-WORKFLOW: ...` comments instead of reverting them to older wording. * Patch remaining non-ward-prefixed automated markers only where the current implementation still emits them. * Update parsers/tests with backward compatibility where old comments can still exist on issue threads. * Document the current marker vocabulary and intended reader. ## Acceptance * The PR starts by naming the current marker inventory and which markers still needed changes. * Workflow comments use the current literal `WARD-WORKFLOW: ...` shape where applicable. * Any remaining `WARD-OUTCOME:` usage is deliberate and documented, not copied from stale examples. * Reservation, broker, review, workflow, and retro structured comments consistently use literal `WARD-<THING>:` markers or documented legacy compatibility. * Tests cover parser compatibility for current markers and at least one legacy marker. * `ward exec test` passes, or the issue comment names the exact failing check. ## Decision for headless carry Headless, but verification-first. Kai specifically warned that the marker surface has moved and the engineer must not implement from stale issue text.

coilyco-ops commented

2026-07-08 21:10:09 +00:00

Author

Owner

Correction from Kai: WARD- should be the literal line prefix. Do not put emoji before it.

Preferred shape:

WARD-OUTCOME: ⚠️ Missing `opencode` binary in dev-base image; filed coilyco-flight-deck/agentic-os#342.

Not:

⚠️ WARD-OUTCOME: Missing `opencode` binary in dev-base image.

The marker needs to be parser/grep friendly from the start of the line. Emoji can appear somewhere after the marker, as part of the human-readable value.

Correction from Kai: `WARD-` should be the literal line prefix. Do not put emoji before it. Preferred shape: ```text WARD-OUTCOME: ⚠️ Missing `opencode` binary in dev-base image; filed coilyco-flight-deck/agentic-os#342. ``` Not: ```text ⚠️ WARD-OUTCOME: Missing `opencode` binary in dev-base image. ``` The marker needs to be parser/grep friendly from the start of the line. Emoji can appear somewhere after the marker, as part of the human-readable value.

coilyco-ops added the

labels

2026-07-09 18:09:23 +00:00

coilyco-ops added

and removed

labels

2026-07-14 06:50:25 +00:00

coilysiren referenced this issue

2026-07-14 15:27:09 +00:00

director should emit colorized, space buffered, visually distinct messages about the categories of actions its performing on startup #1283

coilyco-ops added this to the warded control plane coherence milestone

2026-07-15 05:14:57 +00:00

coilyco-ops commented

2026-07-15 07:16:31 +00:00

Author

Owner

WARD-TRIAGE: warded control plane coherence milestone

This issue is part of the warded control plane coherence sprint. The release thesis is to make warded feel like one dependable control plane for agent work: higher safe parallelism, coherent config defaults, reliable broker/container behavior, human-feedback gates, and enough structured evidence for the next actor after a paused or failed run.

For this sprint, headless means an engineer should be able to carry the issue from current issue context to a merged change without new human decisions. If the issue discovers a missing decision, split or demote the unclear part instead of guessing.

WARD-TRIAGE: warded control plane coherence milestone This issue is part of the `warded control plane coherence` sprint. The release thesis is to make `warded` feel like one dependable control plane for agent work: higher safe parallelism, coherent config defaults, reliable broker/container behavior, human-feedback gates, and enough structured evidence for the next actor after a paused or failed run. For this sprint, `headless` means an engineer should be able to carry the issue from current issue context to a merged change without new human decisions. If the issue discovers a missing decision, split or demote the unclear part instead of guessing.

coilysiren commented

2026-07-18 03:46:38 +00:00

Owner

This might be done??? It's easy and high value though, good to double check

coilyco-ops referenced this issue from a commit

2026-07-23 05:35:59 +00:00

feat(agent): standardize workflow comment markers

coilyco-ops referenced this issue from a pull request that will close it,

2026-07-23 05:36:15 +00:00

Standardize structured workflow comment markers #1522

coilyco-ops commented

2026-07-23 05:38:19 +00:00

Author

Owner

WARDED_WORKFLOW: #1522

details

Review gate intentionally skipped in-container because the temporary ward default is pending brokered QA.
workflow: pull-request-and-merge; review summary: skipped: temporary ward default pending brokered QA

Felt: focused audit and centralized migration. Confidence: high; CI green. Surprise: KDL regeneration cannot reach git.example.com; tracked asset updated in lockstep. Follow-up: brokered QA can re-run the generator when its spec host is reachable.

WARDED_WORKFLOW: https://forgejo.coilysiren.me/coilyco-flight-deck/ward/pulls/1522 <details><summary>details</summary> Review gate intentionally skipped in-container because the temporary ward default is pending brokered QA. workflow: pull-request-and-merge; review summary: skipped: temporary ward default pending brokered QA Felt: focused audit and centralized migration. Confidence: high; CI green. Surprise: KDL regeneration cannot reach `git.example.com`; tracked asset updated in lockstep. Follow-up: brokered QA can re-run the generator when its spec host is reachable. </details>

coilyco-ops commented

2026-07-23 05:38:35 +00:00

Author

Owner

WARDED_WORKFLOW: reservation-released

release details

Run finished with WARDED_WORKFLOW: https://forgejo.coilysiren.me/coilyco-flight-deck/ward/pulls/1522.

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

Outcome summary: #1522

— Codex, via ward agent

WARDED_WORKFLOW: reservation-released <details><summary>release details</summary> Run finished with `WARDED_WORKFLOW: https://forgejo.coilysiren.me/coilyco-flight-deck/ward/pulls/1522`. `ward container reap` released container `engineer-codex-ward-698` (`--harness codex`): the terminal outcome supersedes the reservation, so a later redispatch no longer needs `--override-reservation`. **Outcome summary:** https://forgejo.coilysiren.me/coilyco-flight-deck/ward/pulls/1522 </details>  — Codex, via `ward agent`

coilysiren closed this issue

2026-07-23 06:29:35 +00:00

coilysiren referenced this issue from a commit

2026-07-23 06:29:39 +00:00

Standardize structured workflow comment markers (#1522)

Rows
Columns

Standardize ward structured comments around WARD outcome markers #698

Goal

Current direction

Product intent

Marker rules

Do

Acceptance

Decision for headless carry