coilyco-flight-deck/ward

Fork 0

Standardize ward structured comments around WARD outcome markers #698

New issue

Open

opened 2026-07-08 21:08:14 +00:00 by coilyco-ops · 3 comments

coilyco-ops commented

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

Member

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

Member

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

headless

labels

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

coilyco-ops commented

2026-07-09 22:43:11 +00:00

Author

Member

WARD-RESERVATION: held 🔒

reservation details

Holder: container engineer-codex-ward-698 on host kais-macbook-pro-2.local.

Reserved by ward agent --harness codex (reserved 2026-07-09T22:43:08Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (1h TTL). --force overrides.

Do not comment on or edit this issue to steer the run while it is reserved. The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a new issue, dispatched fresh. That is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494).

run seed context — what this run is carrying (ward#609)

Resolved: coilyco-flight-deck/ward#698 · branch issue-698 · harness codex · workflow pull-requests-and-merge
Run: engineer-codex-ward-698 · ward v0.540.0 · dispatched 2026-07-09T22:43:08Z
Comment thread: 1 included in the pre-flight read, 0 stripped (ward's own automated comments).
- included: @coilyco-ops (2026-07-08T21:10:09Z)

Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.540.0).

— Codex, via ward agent

WARD-RESERVATION: held 🔒 <details><summary>reservation details</summary> Holder: container `engineer-codex-ward-698` on host `kais-macbook-pro-2.local`. Reserved by `ward agent --harness codex` (reserved 2026-07-09T22:43:08Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (1h TTL). `--force` overrides. **Do not comment on or edit this issue to steer the run while it is reserved.** The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a **new issue, dispatched fresh**. That is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494). <details><summary>run seed context — what this run is carrying (ward#609)</summary> - **Resolved:** `coilyco-flight-deck/ward#698` · branch `issue-698` · harness `codex` · workflow `pull-requests-and-merge` - **Run:** `engineer-codex-ward-698` · ward `v0.540.0` · dispatched `2026-07-09T22:43:08Z` - **Comment thread:** 1 included in the pre-flight read, 0 stripped (ward's own automated comments). - included: @coilyco-ops (2026-07-08T21:10:09Z) Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.540.0). </details> </details>  — Codex, via `ward agent`

coilyco-ops added

consult

and removed

headless

labels

2026-07-10 09:00:36 +00:00

coilyco-ops added

headless

and removed

consult

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

Member

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.