coilyco-flight-deck/ward

Fork 0

Mine warded-agent history for regression tests and review doctrine #934

New issue

Open

opened 2026-07-10 04:02:39 +00:00 by coilyco-ops · 4 comments

coilyco-ops commented

2026-07-10 04:02:39 +00:00

Member

Goal:

Mine the warded-agent era of ward history and produce a regression-defense plan: true integration/smoke tests plus agent-facing CODE-REVIEW.md guidance.

Scope:

Determine the start of the warded-agent era mechanically from ward history. Use the first commit that introduced the ward agent / warded dispatch surface unless a better boundary is found. Record the boundary SHA/date in the output.
Pull commit subjects and bodies from that boundary through current main.
Extract issue references from those commits, fetch the linked issue bodies/comments/outcomes, and join commit evidence with issue evidence.
Derive recurring or high-severity regression themes from the joined corpus.
Propose integration/smoke tests that provide true regression coverage, not quick wins. Favor tests that cross real boundaries: surface -> broker -> Docker, config -> repo authority -> dispatch policy, issue reservation -> launch -> unlock, container bootstrap -> agent auth, reaper -> salvage, review gate -> final outcome, Forgejo comments -> director classification, PR workflow -> protected landing, GitHub path -> PR done-condition.
Draft agent-facing code review guidance in the CODE-REVIEW.md contract shape from coilyco-flight-deck/agentic-os#402: localized invariants and historical-issue defense only, no generic review advice.

Expected deliverables:

A regression matrix with scenario, historical source commits/issues, boundary exercised, fixture needs, CI placement, and why it matters.
A proposed CODE-REVIEW.md section or full draft for ward, layered on top of the automated tests.
Open questions where history is ambiguous or a test requires an explicit product decision.

Notes:

This follows from the current dispatch regression thread and ward#932. The goal is not a small fake-broker test. The integration test list should defend against common or serious regressions that have actually happened in ward history.

Goal: Mine the warded-agent era of ward history and produce a regression-defense plan: true integration/smoke tests plus agent-facing CODE-REVIEW.md guidance. Scope: * Determine the start of the warded-agent era mechanically from ward history. Use the first commit that introduced the `ward agent` / `warded` dispatch surface unless a better boundary is found. Record the boundary SHA/date in the output. * Pull commit subjects and bodies from that boundary through current `main`. * Extract issue references from those commits, fetch the linked issue bodies/comments/outcomes, and join commit evidence with issue evidence. * Derive recurring or high-severity regression themes from the joined corpus. * Propose integration/smoke tests that provide true regression coverage, not quick wins. Favor tests that cross real boundaries: surface -> broker -> Docker, config -> repo authority -> dispatch policy, issue reservation -> launch -> unlock, container bootstrap -> agent auth, reaper -> salvage, review gate -> final outcome, Forgejo comments -> director classification, PR workflow -> protected landing, GitHub path -> PR done-condition. * Draft agent-facing code review guidance in the CODE-REVIEW.md contract shape from coilyco-flight-deck/agentic-os#402: localized invariants and historical-issue defense only, no generic review advice. Expected deliverables: * A regression matrix with scenario, historical source commits/issues, boundary exercised, fixture needs, CI placement, and why it matters. * A proposed CODE-REVIEW.md section or full draft for ward, layered on top of the automated tests. * Open questions where history is ambiguous or a test requires an explicit product decision. Notes: This follows from the current dispatch regression thread and ward#932. The goal is not a small fake-broker test. The integration test list should defend against common or serious regressions that have actually happened in ward history.

coilyco-ops commented

2026-07-10 04:13:53 +00:00

Author

Member

🔎 ward agent advisor

ward agent advisor --harness codex ran a one-shot deep research pass on this question:

Read the issue title, body, and comment thread below as the research brief. Identify the decisions, options, open questions, and risks, then give a clear advisory recommendation that can be posted back on the issue.

Recommendation

Keep this as one ward issue. Do not split child issues. The work is single-repo regression defense in coilyco-flight-deck/ward; coilyco-flight-deck/agentic-os#402 is only the contract source for the future CODE-REVIEW.md shape.

The warded-agent era boundary should be c3d619f6d2fa786c6fccef27bdbf95d20ac3b4d0 on 2026-06-17, feat(agent): add \ward agent work ` issue-seeded container shortcut. That is the first commit adding agentCommand()to the CLI and a real issue-seededward agentdispatch surface. Earlier container commits on 2026-06-16 matter as substrate, but they were not yet the warded-agent surface. The publicwarded` shim arrived later on 2026-06-24, so using it as the boundary would miss the first week of agent failures.

Research pass used that boundary through current main at 7094eac57e5d713f0cec57fcdd285417ab4e02f6 on 2026-07-10. The corpus has 987 commits and 553 referenced ward issues, plus current live thread context from ward#876, ward#900, ward#931, ward#932, and ward#934. The recurring pattern is not lack of small unit tests. It is boundary drift: read-only surfaces fall back to local Docker, generated ops surfaces leak into core agent paths, reservations survive failed launches, bootstrap failures look like successful carries, and done markers are trusted before the real landing boundary is verified.

Decisions

Boundary - use c3d619f6d2fa as the mechanical start. Mention the earlier container foundation separately only when a scenario depends on it.
Test strategy - keep the #933 fake-broker test, but treat it as a routing unit test only. The real missing coverage is a Docker-capable smoke that proves read-only surface -> host dispatch broker -> Docker create/start -> short-lived engineer container.
CI placement - put cheap fake-broker, config, reservation, reaper, workflow, and tracker tests in normal go test ./.... Add a separate Docker-capable smoke job that gates releases at minimum, and PRs if the runner can expose a Docker socket safely.
Fixture stance - avoid live LLMs, live issue mutation, and pushes. Use fake Forgejo/GitHub HTTP servers, local bare git remotes, a local config bundle, and a no-op smoke image. The only live boundary the deep smoke should require is Docker.
Review doctrine - add a root CODE-REVIEW.md once the aos hook is available, or earlier as normal docs. Its content should be local invariants and historical issues only, not generic review advice.

Regression Matrix

Real brokered engineer dispatch smoke - Sources: ward#315, ward#319, ward#321, ward#323, ward#389, ward#391, ward#900, ward#931, ward#932, ward#933. Commits include 4414c5d2dd7d, 0d2a61aa67a7, d8dc72273567, 7094eac57e5d. Boundary exercised: director/read-only surface -> TCP dispatch broker -> host Docker socket -> engineer container. Fixture needs: real Docker socket, fake tracker or fixture issue resolver, local no-op image via WARD_AGENT_IMAGE, temp gitcache, broker token. CI placement: Docker-capable release gate, PR gate if the runner supports it. Why it matters: #933 proves a fake broker records a request, but it still would not catch host Docker socket, labels/env, asset staging, or create/start regressions.
Config and repo authority dispatch policy - Sources: ward#441, ward#453, ward#653-657, ward#876, ward#929, ward#931. Commit: fcd5f2bfbdc8 for core Forgejo decoupling. Boundary exercised: config source -> smart defaults -> repo authority -> dispatch allow/refuse. Fixture needs: file:// fleet bundle trusting coilyco-flight-deck, neutral bundle rejecting it, no network. CI placement: normal unit/integration. Why it matters: the live #931 failure needed explicit WARD_CONFIG_REF, and #876 showed smart-default recursion. Core dispatch should not depend on runtime generated ops surfaces.
Reservation, launch, unlock, and failed-forward comment path - Sources: ward#184, ward#264, ward#570, ward#595, ward#609, ward#689, current ward#934 failure comment. Commits include a7779c05e308, 2f900d630d2a, 36f8f65c0e90, cd07ffd0c58a, 0960b691450c, 8025b73253ed. Boundary exercised: tracker reservation -> broker/launch -> pre-launch failure -> unlock/comment. Fixture needs: fake lock/comment forge, fake broker launch failures, release-asset failure case. CI placement: normal unit plus one broker integration. Why it matters: stale reservations repeatedly blocked retry or made failed runs look active.
Container bootstrap and auth fail-loud smoke - Sources: ward#222, ward#273, ward#288, ward#357, ward#574, ward#597, ward#909, current ward#934 v0.555.0 binary 404. Commits include e74d9185b081, 15c3602f34e6, 9a131f0369b7, 0a92e843ff2a, 40b7eeb7fa57, 4cf59d5ae6c, cd07ffd0c58a. Boundary exercised: host release/version selection -> bootstrap download -> entrypoint smoke gates -> agent launch. Fixture needs: local HTTP release server returning 404, fake auth files, no-op image, temp asset dirs outside /tmp for snap-docker coverage. CI placement: normal unit for selection/errors, Docker smoke for entrypoint behavior. Why it matters: bootstrap and auth failures have historically hung, salvaged fake work, or left only raw logs.
Reaper, salvage, and multi-repo done-condition verification - Sources: ward#291, ward#504, ward#518, ward#529, ward#666, ward#667. Commits include 93b020ab871c, 9013c9d125d0, 343abb53a576. Boundary exercised: workspace git state -> primary and --repo remotes -> carried issue outcome/salvage comments. Fixture needs: local bare remotes for primary and grant repos, fake carried issue, deliberate secondary push miss. CI placement: normal integration, no Docker required. Why it matters: #291 closed as done while granted-repo work was lost. A green issue must mean every repo landed or was salvaged loudly.
Director classification and tracker timeline parsing - Sources: ward#310, ward#400, ward#402, ward#609, ward#613, ward#689, ward#900. Commits include 2e738e53dfd3, 6a66d66b25c0, 02f9a55c6023, 8025b73253ed. Boundary exercised: Forgejo comments/reservations/outcomes -> director heartbeat classification -> broker logs/list path. Fixture needs: synthetic issue timelines with reservation, release, failed dispatch, WARD-OUTCOME, stale PR, and missing local Docker. CI placement: normal unit. Why it matters: #900 shows director classification can report false failure when it reads local Docker from a read-only surface.
Workflow, PR, review gate, and GitHub done-condition - Sources: ward#489, ward#786, ward#899, ward#901, ward#908, ward#922, ward#929. Commits include 671c21d276d1, 763a26025be7, 993e222417e2, 40a37bf7d9d0. Boundary exercised: workflow config -> forge client -> PR create/read/merge policy -> final WARD-OUTCOME. Fixture needs: fake Forgejo and GitHub APIs, protected-main behavior, stale PR 404, review skipped/passed markers. CI placement: normal integration. Why it matters: workflow names and GitHub semantics changed late, and wrong done-condition logic is high impact.

Proposed CODE-REVIEW.md Draft

# Code review contract

Code review here defends ward's local control-plane invariants and the historical failures that have already stopped warded-agent work.

## Localized invariants

* Core agent control-plane paths use ward-owned tracker, forge, broker, bootstrap, reservation, reaper, and workflow code. They must not depend on runtime-selected generated `ward ops` or ward-kdl leaves.
* A read-only director/surface session cannot push its clone and cannot launch, inspect, stop, or log engineers through surface-local Docker. Dispatch, list, logs, and stop go through the host dispatch broker or fail loudly.
* A reservation is never a done-condition. Every pre-launch, broker, Docker, bootstrap, and smoke-test failure must either release the reservation with a tracker comment or leave an intentionally visible active run.
* Container bootstrap fails before agent launch when the selected ward binary, entrypoint, credentials, Docker assets, tailnet network, or harness smoke gate is unavailable. It must not fall through to a shell or salvage fake work.
* A WARD-OUTCOME is trusted only after the workflow boundary is satisfied: direct-main landed, pull-request opened or merged as configured, GitHub path honored, and every granted repo verified or salvaged.
* Director classification reads tracker markers and broker-visible host state. Missing Docker inside the read-only surface is not evidence that a broker-forwarded engineer failed.

## Historical issues

* ward#222, ward#264, ward#570, ward#595, ward#609, and ward#689 cover auth/pre-launch deaths, leaked holds, failed dispatch comments, and retry visibility.
* ward#315, ward#319, ward#321, ward#323, ward#389, ward#391, ward#900, ward#931, and ward#932 cover read-only surface dispatch, broker transport, Docker socket, TUI/log, and real Docker smoke regressions.
* ward#441, ward#453, ward#876, ward#929, and ward#931 cover config-source and generated-surface drift breaking core dispatch.
* ward#291, ward#518, ward#529, and salvage issues cover false done outcomes and lost multi-repo work.
* ward#489 and ward#786 cover GitHub and workflow done-condition semantics.

## Update triggers

Refresh this file when a warded run needs manual recovery, when a launch path is moved across process/container/forge boundaries, when a generated surface is proposed for a core path, or when an issue repeats a failure mode listed above.

Open Questions

Does ward have a Docker-capable CI runner that can safely expose the host Docker socket to a release-gating job? If not, the real-Docker smoke should be release or scheduled only until the runner exists.
Should the no-op smoke use a purpose-built tiny image, or should WARD_SMOKE_TEST_SKIP be tightened so it still performs Docker create/start and only short-circuits inside the launched container? Recommendation: use a tiny image through WARD_AGENT_IMAGE, because it is easier to prove no LLM, Forgejo mutation, or push can happen.
Should the real-Docker smoke use a fake tracker only, or a disposable Forgejo fixture? Recommendation: fake tracker in PR/release CI, disposable Forgejo only as an optional scheduled deep smoke.
Should a broker response mean accepted request or container observed created/started? Current behavior can say forwarded before a reservation appears. The smoke should force an explicit product decision here.
Should ward preflight the selected --ward-version release asset before posting a reservation? The ward#934 comment failed on a v0.555.0 binary 404 after reservation, so this deserves either a test or an explicit acceptance of late failure with self-documenting release/unlock.

Risks

Stopping at #933 leaves the main operational risk uncovered. A fake broker cannot catch host Docker, asset path, labels/env, image, or create/start failures.
Live external services in CI would make this flaky. Keep Forgejo, GitHub, git remotes, and LLMs fake or local.
A Docker smoke that can accidentally use surface-local Docker will pass for the wrong reason. The surface subprocess should run without /var/run/docker.sock and fail if Docker is touched locally.
Generated config and ops surfaces are still moving. Tests should assert core agent paths are independent of runtime KDL/specgen, not just that today's generated command accepts today's flags.
Review doctrine without tests will decay into prose. The CODE-REVIEW.md should be layered on the matrix above, and reviewers should demand a boundary-crossing regression whenever one of these historical paths is touched.

Researched and posted automatically by ward agent advisor --harness codex (ward#179). This is one-shot research, not a carried change - verify before acting on it.

— Codex, via ward agent

### 🔎 ward agent advisor `ward agent advisor --harness codex` ran a one-shot **deep** research pass on this question: > Read the issue title, body, and comment thread below as the research brief. Identify the decisions, options, open questions, and risks, then give a clear advisory recommendation that can be posted back on the issue. --- **Recommendation** Keep this as one ward issue. Do not split child issues. The work is single-repo regression defense in `coilyco-flight-deck/ward`; `coilyco-flight-deck/agentic-os#402` is only the contract source for the future `CODE-REVIEW.md` shape. The warded-agent era boundary should be `c3d619f6d2fa786c6fccef27bdbf95d20ac3b4d0` on 2026-06-17, `feat(agent): add \`ward agent <name> work <issue>\` issue-seeded container shortcut`. That is the first commit adding `agentCommand()` to the CLI and a real issue-seeded `ward agent` dispatch surface. Earlier container commits on 2026-06-16 matter as substrate, but they were not yet the warded-agent surface. The public `warded` shim arrived later on 2026-06-24, so using it as the boundary would miss the first week of agent failures. Research pass used that boundary through current `main` at `7094eac57e5d713f0cec57fcdd285417ab4e02f6` on 2026-07-10. The corpus has 987 commits and 553 referenced ward issues, plus current live thread context from ward#876, ward#900, ward#931, ward#932, and ward#934. The recurring pattern is not lack of small unit tests. It is boundary drift: read-only surfaces fall back to local Docker, generated ops surfaces leak into core agent paths, reservations survive failed launches, bootstrap failures look like successful carries, and done markers are trusted before the real landing boundary is verified. **Decisions** * **Boundary** - use `c3d619f6d2fa` as the mechanical start. Mention the earlier container foundation separately only when a scenario depends on it. * **Test strategy** - keep the #933 fake-broker test, but treat it as a routing unit test only. The real missing coverage is a Docker-capable smoke that proves `read-only surface -> host dispatch broker -> Docker create/start -> short-lived engineer container`. * **CI placement** - put cheap fake-broker, config, reservation, reaper, workflow, and tracker tests in normal `go test ./...`. Add a separate Docker-capable smoke job that gates releases at minimum, and PRs if the runner can expose a Docker socket safely. * **Fixture stance** - avoid live LLMs, live issue mutation, and pushes. Use fake Forgejo/GitHub HTTP servers, local bare git remotes, a local config bundle, and a no-op smoke image. The only live boundary the deep smoke should require is Docker. * **Review doctrine** - add a root `CODE-REVIEW.md` once the aos hook is available, or earlier as normal docs. Its content should be local invariants and historical issues only, not generic review advice. **Regression Matrix** * **Real brokered engineer dispatch smoke** - Sources: ward#315, ward#319, ward#321, ward#323, ward#389, ward#391, ward#900, ward#931, ward#932, ward#933. Commits include `4414c5d2dd7d`, `0d2a61aa67a7`, `d8dc72273567`, `7094eac57e5d`. Boundary exercised: director/read-only surface -> TCP dispatch broker -> host Docker socket -> engineer container. Fixture needs: real Docker socket, fake tracker or fixture issue resolver, local no-op image via `WARD_AGENT_IMAGE`, temp gitcache, broker token. CI placement: Docker-capable release gate, PR gate if the runner supports it. Why it matters: #933 proves a fake broker records a request, but it still would not catch host Docker socket, labels/env, asset staging, or create/start regressions. * **Config and repo authority dispatch policy** - Sources: ward#441, ward#453, ward#653-657, ward#876, ward#929, ward#931. Commit: `fcd5f2bfbdc8` for core Forgejo decoupling. Boundary exercised: config source -> smart defaults -> repo authority -> dispatch allow/refuse. Fixture needs: `file://` fleet bundle trusting `coilyco-flight-deck`, neutral bundle rejecting it, no network. CI placement: normal unit/integration. Why it matters: the live #931 failure needed explicit `WARD_CONFIG_REF`, and #876 showed smart-default recursion. Core dispatch should not depend on runtime generated ops surfaces. * **Reservation, launch, unlock, and failed-forward comment path** - Sources: ward#184, ward#264, ward#570, ward#595, ward#609, ward#689, current ward#934 failure comment. Commits include `a7779c05e308`, `2f900d630d2a`, `36f8f65c0e90`, `cd07ffd0c58a`, `0960b691450c`, `8025b73253ed`. Boundary exercised: tracker reservation -> broker/launch -> pre-launch failure -> unlock/comment. Fixture needs: fake lock/comment forge, fake broker launch failures, release-asset failure case. CI placement: normal unit plus one broker integration. Why it matters: stale reservations repeatedly blocked retry or made failed runs look active. * **Container bootstrap and auth fail-loud smoke** - Sources: ward#222, ward#273, ward#288, ward#357, ward#574, ward#597, ward#909, current ward#934 `v0.555.0` binary 404. Commits include `e74d9185b081`, `15c3602f34e6`, `9a131f0369b7`, `0a92e843ff2a`, `40b7eeb7fa57`, `4cf59d5ae6c`, `cd07ffd0c58a`. Boundary exercised: host release/version selection -> bootstrap download -> entrypoint smoke gates -> agent launch. Fixture needs: local HTTP release server returning 404, fake auth files, no-op image, temp asset dirs outside `/tmp` for snap-docker coverage. CI placement: normal unit for selection/errors, Docker smoke for entrypoint behavior. Why it matters: bootstrap and auth failures have historically hung, salvaged fake work, or left only raw logs. * **Reaper, salvage, and multi-repo done-condition verification** - Sources: ward#291, ward#504, ward#518, ward#529, ward#666, ward#667. Commits include `93b020ab871c`, `9013c9d125d0`, `343abb53a576`. Boundary exercised: workspace git state -> primary and `--repo` remotes -> carried issue outcome/salvage comments. Fixture needs: local bare remotes for primary and grant repos, fake carried issue, deliberate secondary push miss. CI placement: normal integration, no Docker required. Why it matters: #291 closed as done while granted-repo work was lost. A green issue must mean every repo landed or was salvaged loudly. * **Director classification and tracker timeline parsing** - Sources: ward#310, ward#400, ward#402, ward#609, ward#613, ward#689, ward#900. Commits include `2e738e53dfd3`, `6a66d66b25c0`, `02f9a55c6023`, `8025b73253ed`. Boundary exercised: Forgejo comments/reservations/outcomes -> director heartbeat classification -> broker logs/list path. Fixture needs: synthetic issue timelines with reservation, release, failed dispatch, WARD-OUTCOME, stale PR, and missing local Docker. CI placement: normal unit. Why it matters: #900 shows director classification can report false failure when it reads local Docker from a read-only surface. * **Workflow, PR, review gate, and GitHub done-condition** - Sources: ward#489, ward#786, ward#899, ward#901, ward#908, ward#922, ward#929. Commits include `671c21d276d1`, `763a26025be7`, `993e222417e2`, `40a37bf7d9d0`. Boundary exercised: workflow config -> forge client -> PR create/read/merge policy -> final WARD-OUTCOME. Fixture needs: fake Forgejo and GitHub APIs, protected-main behavior, stale PR 404, review skipped/passed markers. CI placement: normal integration. Why it matters: workflow names and GitHub semantics changed late, and wrong done-condition logic is high impact. **Proposed CODE-REVIEW.md Draft** ```markdown # Code review contract Code review here defends ward's local control-plane invariants and the historical failures that have already stopped warded-agent work. ## Localized invariants * Core agent control-plane paths use ward-owned tracker, forge, broker, bootstrap, reservation, reaper, and workflow code. They must not depend on runtime-selected generated `ward ops` or ward-kdl leaves. * A read-only director/surface session cannot push its clone and cannot launch, inspect, stop, or log engineers through surface-local Docker. Dispatch, list, logs, and stop go through the host dispatch broker or fail loudly. * A reservation is never a done-condition. Every pre-launch, broker, Docker, bootstrap, and smoke-test failure must either release the reservation with a tracker comment or leave an intentionally visible active run. * Container bootstrap fails before agent launch when the selected ward binary, entrypoint, credentials, Docker assets, tailnet network, or harness smoke gate is unavailable. It must not fall through to a shell or salvage fake work. * A WARD-OUTCOME is trusted only after the workflow boundary is satisfied: direct-main landed, pull-request opened or merged as configured, GitHub path honored, and every granted repo verified or salvaged. * Director classification reads tracker markers and broker-visible host state. Missing Docker inside the read-only surface is not evidence that a broker-forwarded engineer failed. ## Historical issues * ward#222, ward#264, ward#570, ward#595, ward#609, and ward#689 cover auth/pre-launch deaths, leaked holds, failed dispatch comments, and retry visibility. * ward#315, ward#319, ward#321, ward#323, ward#389, ward#391, ward#900, ward#931, and ward#932 cover read-only surface dispatch, broker transport, Docker socket, TUI/log, and real Docker smoke regressions. * ward#441, ward#453, ward#876, ward#929, and ward#931 cover config-source and generated-surface drift breaking core dispatch. * ward#291, ward#518, ward#529, and salvage issues cover false done outcomes and lost multi-repo work. * ward#489 and ward#786 cover GitHub and workflow done-condition semantics. ## Update triggers Refresh this file when a warded run needs manual recovery, when a launch path is moved across process/container/forge boundaries, when a generated surface is proposed for a core path, or when an issue repeats a failure mode listed above. ``` **Open Questions** * Does ward have a Docker-capable CI runner that can safely expose the host Docker socket to a release-gating job? If not, the real-Docker smoke should be release or scheduled only until the runner exists. * Should the no-op smoke use a purpose-built tiny image, or should `WARD_SMOKE_TEST_SKIP` be tightened so it still performs Docker create/start and only short-circuits inside the launched container? Recommendation: use a tiny image through `WARD_AGENT_IMAGE`, because it is easier to prove no LLM, Forgejo mutation, or push can happen. * Should the real-Docker smoke use a fake tracker only, or a disposable Forgejo fixture? Recommendation: fake tracker in PR/release CI, disposable Forgejo only as an optional scheduled deep smoke. * Should a broker response mean `accepted request` or `container observed created/started`? Current behavior can say forwarded before a reservation appears. The smoke should force an explicit product decision here. * Should ward preflight the selected `--ward-version` release asset before posting a reservation? The ward#934 comment failed on a `v0.555.0` binary 404 after reservation, so this deserves either a test or an explicit acceptance of late failure with self-documenting release/unlock. **Risks** * Stopping at #933 leaves the main operational risk uncovered. A fake broker cannot catch host Docker, asset path, labels/env, image, or create/start failures. * Live external services in CI would make this flaky. Keep Forgejo, GitHub, git remotes, and LLMs fake or local. * A Docker smoke that can accidentally use surface-local Docker will pass for the wrong reason. The surface subprocess should run without `/var/run/docker.sock` and fail if Docker is touched locally. * Generated config and ops surfaces are still moving. Tests should assert core agent paths are independent of runtime KDL/specgen, not just that today's generated command accepts today's flags. * Review doctrine without tests will decay into prose. The CODE-REVIEW.md should be layered on the matrix above, and reviewers should demand a boundary-crossing regression whenever one of these historical paths is touched. --- Researched and posted automatically by `ward agent advisor --harness codex` (ward#179). This is one-shot research, not a carried change - verify before acting on it.   — Codex, via `ward agent`

coilyco-ops commented

2026-07-10 04:14:02 +00:00

Author

Member

🔎 ward agent advisor

ward agent advisor --harness claude ran a one-shot deep research pass on this question:

Read the issue title, body, and comment thread below as the research brief. Identify the decisions, options, open questions, and risks, then give a clear advisory recommendation that can be posted back on the issue.

pre-commit installed at .git/hooks/pre-commit
pre-commit installed at .git/hooks/commit-msg
Not logged in · Please run /login

Researched and posted automatically by ward agent advisor --harness claude (ward#179). This is one-shot research, not a carried change - verify before acting on it.

— Claude (she/her), via ward agent

### 🔎 ward agent advisor `ward agent advisor --harness claude` ran a one-shot **deep** research pass on this question: > Read the issue title, body, and comment thread below as the research brief. Identify the decisions, options, open questions, and risks, then give a clear advisory recommendation that can be posted back on the issue. --- pre-commit installed at .git/hooks/pre-commit pre-commit installed at .git/hooks/commit-msg Not logged in · Please run /login --- Researched and posted automatically by `ward agent advisor --harness claude` (ward#179). This is one-shot research, not a carried change - verify before acting on it.   — Claude (she/her), via `ward agent`

coilyco-ops commented

2026-07-10 04:18:01 +00:00

Author

Member

🔎 ward agent advisor

ward agent advisor --harness codex ran a one-shot deep research pass on this question:

Read the issue title, body, and comment thread below as the research brief. Identify the decisions, options, open questions, and risks, then give a clear advisory recommendation that can be posted back on the issue.

Recommendation

Keep this as one coilyco-flight-deck/ward issue. The work is single-repo regression defense. coilyco-flight-deck/agentic-os#402 is only the source of the CODE-REVIEW.md contract shape.

Use c3d619f6d2fa786c6fccef27bdbf95d20ac3b4d0 on 2026-06-17 as the warded-agent-era boundary. It is the first commit adding the real issue-seeded ward agent <name> work <issue> dispatch surface through agentCommand(). Earlier 2026-06-16 container commits are foundation only. The public warded shim arrives later at dfa5610118258b9f11247618329b3fcbb7b82d10 on 2026-06-24, so using warded as the boundary misses the first week of agent failures.

Current main for this pass is 7094eac57e5d713f0cec57fcdd285417ab4e02f6 on 2026-07-10. The boundary-to-main corpus is 987 commits. A simple local scan finds 540 direct #N references in commit messages, with more possible when counting URL and cross-repo forms. The recurring failure pattern is boundary drift: read-only surfaces accidentally use local Docker, runtime KDL or generated ops leaves leak into core agent paths, reservations outlive failed launches, bootstrap failures look like live work, and final outcome comments are trusted before the true landing boundary is verified.

Decisions

Boundary - Use c3d619f6d2fa as the start. Mention c2cb54cab825 and other container commits only as substrate when a test needs pre-agent container behavior.
Existing smoke - Treat ward#933 as useful but insufficient. TestRunAgentTaskDirectRoutesThroughBrokerOnReadonlySurface in cmd/ward/agent_dispatch_broker_test.go proves a read-only engineer task can file through a fake Forgejo and forward to a fake TCP broker. It does not prove Docker create/start, real asset staging, release binary download, bootstrap, auth gates, labels, or reaper behavior.
Testing shape - Keep cheap fake-server and fake-broker tests in normal go test ./.... Add one Docker-capable smoke job that crosses read-only surface -> host broker -> Docker create/start -> short-lived no-op container.
Fixture stance - No live LLMs, no live issue mutation, and no real pushes in CI. Use fake Forgejo/GitHub HTTP servers, local bare git remotes, file-based config bundles, and a tiny/no-op image selected through WARD_AGENT_IMAGE.
Review doctrine - Add root CODE-REVIEW.md using the agentic-os#402 shape: ## Localized invariants, ## Historical issues, and ## Update triggers. It should contain only ward-specific invariants and historical failures.

Regression Matrix

Real brokered engineer dispatch smoke - Sources: ward#315, ward#319, ward#321, ward#323, ward#389, ward#391, ward#900, ward#931, ward#932, ward#933. Commits: 4414c5d2dd7d, 0d2a61aa67a7, d8dc72273567, 7094eac57e5. Boundary: director/read-only surface -> TCP dispatch broker -> host Docker -> engineer container. Fixtures: Docker socket, no-op image, temp gitcache, fake issue resolver, broker token. CI: Docker-capable release gate, PR gate only if the runner can expose Docker safely. Why: fake broker coverage cannot catch the failures that repeatedly broke real dispatch.
Config and repo-authority dispatch policy - Sources: ward#441, ward#453, ward#653-657, ward#876, ward#929, ward#931. Commit: fcd5f2bfbdc8. Boundary: config source -> smart defaults -> repo authority -> launch allow/refuse. Fixtures: file:// bundle trusting coilyco-flight-deck, neutral bundle rejecting it, malformed bundle, no network. CI: normal integration. Why: #931 needed explicit WARD_CONFIG_REF, #876 hit smart-default recursion, and #929 showed core agent behavior depending on generated ops CLI shape.
Reservation, launch, unlock, failed-forward comments - Sources: ward#184, ward#264, ward#570, ward#595, ward#609, ward#689, ward#934. Commits: a7779c05e308, 2f900d630d2a, 36f8f65c0e90, cd07ffd0c58a, 0960b691450c, 8025b73253ed. Boundary: tracker reservation -> broker or launch -> pre-launch failure -> release/comment/retry marker. Fixtures: fake forge comments and locks, fake broker launch failures, release asset 404. CI: normal tests plus broker integration. Why: stale reservations repeatedly blocked retries or made failed work look active.
Container bootstrap and auth fail-loud smoke - Sources: ward#222, ward#273, ward#288, ward#357, ward#574, ward#597, ward#909, ward#934. Commits: e74d9185b081, 15c3602f34e6, 9a131f0369b7, 40b7eeb7fa57, 4cf59d5ae6c, 7a8d521, cd07ffd0c58a. Boundary: release/version selection -> bootstrap download -> asset staging -> credential seeding -> harness smoke gate. Fixtures: local HTTP release server returning 404, fake credential files, snap-Docker-style path fixture, no-op image. CI: normal tests for selection/errors, Docker smoke for entrypoint behavior. Why: historical bootstrap/auth failures hung, mislabeled root cause, leaked secrets, or fell through to fake salvage.
Reaper, salvage, and multi-repo done-condition - Sources: ward#291, ward#504, ward#518, ward#529, ward#666, ward#667. Commits: 93b020ab871c, 9013c9d125d0, 343abb53a576. Boundary: workspace git state -> primary and granted repo remotes -> issue outcome or salvage comment. Fixtures: local bare primary and granted remotes, fake carried issue, deliberate secondary push miss. CI: normal integration. Why: ward#291 proved a green issue can hide lost secondary-repo work unless every granted repo is verified.
Director classification and tracker timeline parsing - Sources: ward#310, ward#400, ward#402, ward#609, ward#613, ward#689, ward#900. Commits: 2e738e53dfd3, 6a66d66b25c0, 02f9a55c6023, 8025b73253ed. Boundary: Forgejo comments/reservations/outcomes -> director heartbeat classification -> broker-visible state/logs/list. Fixtures: synthetic timelines with reservation, release, failed dispatch, WARD-OUTCOME, stale PR, and missing local Docker. CI: normal unit/integration. Why: ward#900 shows a director can falsely classify broker-forwarded runs as failed by inspecting surface-local Docker.
Workflow, PR, review gate, and GitHub done-condition - Sources: ward#489, ward#786, ward#899, ward#901, ward#908, ward#922, ward#929. Commits: 763a26025be7, 993e222417e2, 40a37bf7d9d0, 671c21d276d1. Boundary: workflow config -> forge client -> PR create/read/merge policy -> final WARD-OUTCOME. Fixtures: fake Forgejo and GitHub APIs, protected-main behavior, stale PR 404, review skipped/passed markers. CI: normal integration. Why: workflow names and GitHub semantics changed late, and wrong done-condition logic is high impact.

Proposed CODE-REVIEW.md Draft

Code review contract

Code review here defends ward control-plane invariants and historical failures that have already stopped warded-agent work.

Localized invariants

Core agent control-plane paths use ward-owned tracker, forge, broker, bootstrap, reservation, reaper, workflow, and review code. They do not depend on runtime-selected generated ward ops leaves.
A read-only director or surface session cannot push its clone and cannot use surface-local Docker for launch, list, logs, stop, or reconcile. Those actions go through the host dispatch broker or fail loudly.
A reservation is not a done-condition. Every pre-launch, broker, Docker, bootstrap, and smoke failure releases or supersedes the reservation and leaves a tracker-visible recovery marker.
Bootstrap fails before agent launch when the selected ward binary, entrypoint, credentials, Docker assets, tailnet network, or harness smoke gate is unavailable. It must not fall through to shell or salvage fake work.
A WARD-OUTCOME is trusted only after the workflow boundary is satisfied: direct-main landed, PR opened or merged as configured, GitHub path honored, review gate settled, and every granted repo verified or salvaged.
Director classification reads tracker markers and broker-visible host state. Missing Docker inside a read-only surface is not evidence that a broker-forwarded engineer failed.

Historical issues

ward#222, ward#264, ward#273, ward#288, ward#357, ward#570, ward#574, ward#595, ward#597, ward#609, ward#689, ward#909, and ward#934 cover bootstrap, auth, credential, asset, reservation, and failed-forward regressions.
ward#315, ward#319, ward#321, ward#323, ward#389, ward#391, ward#900, ward#931, ward#932, and ward#933 cover read-only surface dispatch, broker transport, Docker reachability, and fake-vs-real smoke gaps.
ward#441, ward#453, ward#653-657, ward#876, ward#929, and ward#931 cover config-source and generated-surface drift breaking core dispatch.
ward#291, ward#518, ward#529, ward#666, and ward#667 cover false done outcomes, salvage, and granted-repo verification.
ward#489, ward#786, ward#899, ward#901, ward#908, and ward#922 cover GitHub, PR workflow, review, and director-merge semantics.

Update triggers

Refresh this file when a warded run needs manual recovery, when a launch path moves across process/container/forge boundaries, when generated surfaces are proposed for a core path, or when an issue repeats one of the historical failure modes above.

Options

Fake broker only - cheap and already started by #933, but it leaves the highest-risk Docker/bootstrap boundary uncovered.
Docker smoke in all PRs - best regression signal, but only if the runner has a safe Docker socket and no live credentials.
Docker smoke on release/schedule only - lower PR friction, but dispatch regressions can reach main before the smoke catches them.
Disposable Forgejo fixture - closer to production, but more moving parts and flake. Use fake HTTP in PR/release CI and reserve disposable Forgejo for optional scheduled deep smoke.

Open Questions

Does ward have a CI runner where a Docker socket can be safely exposed to a release-gating smoke? If not, make the real-Docker test scheduled or release-only until that runner exists.
Should the no-op smoke use a purpose-built tiny image, or should WARD_SMOKE_TEST_SKIP be tightened so Docker create/start still happens and only in-container agent work is skipped? Recommendation: tiny image through WARD_AGENT_IMAGE.
Should broker success mean request accepted, container created, or container observed started? The current thread shows forwarded-before-useful-run ambiguity. The smoke should encode the product decision.
Should ward preflight the selected --ward-version release asset before posting a reservation? ward#934 failed on a v0.555.0 binary 404 after reservation, so either preflight it or require the failure path to release and comment loudly.
Should workflow names follow the current shipped direct-main/pull-requests/pull-requests-and-merge/patch-only compatibility, or the ward#786 desired contract with singular PR names and remote-branch-only? Tests need to pin the intended transition.

Risks

Stopping at ward#933 leaves the main operational risk uncovered.
Live external services in CI will make the suite flaky. Keep Forgejo, GitHub, git remotes, and LLMs fake or local.
A Docker smoke can pass for the wrong reason if the simulated surface can touch local Docker. The surface process should run with broker env set and local Docker deliberately unavailable.
Generated config and ops surfaces are still moving. Tests should assert core agent paths are independent of runtime KDL/specgen shape.
Review doctrine without automated tests will decay into prose. CODE-REVIEW.md should point reviewers at these historical invariants and the tests should enforce the actual boundaries.

Researched and posted automatically by ward agent advisor --harness codex (ward#179). This is one-shot research, not a carried change - verify before acting on it.

— Codex, via ward agent

### 🔎 ward agent advisor `ward agent advisor --harness codex` ran a one-shot **deep** research pass on this question: > Read the issue title, body, and comment thread below as the research brief. Identify the decisions, options, open questions, and risks, then give a clear advisory recommendation that can be posted back on the issue. --- **Recommendation** Keep this as one `coilyco-flight-deck/ward` issue. The work is single-repo regression defense. `coilyco-flight-deck/agentic-os#402` is only the source of the `CODE-REVIEW.md` contract shape. Use `c3d619f6d2fa786c6fccef27bdbf95d20ac3b4d0` on 2026-06-17 as the warded-agent-era boundary. It is the first commit adding the real issue-seeded `ward agent <name> work <issue>` dispatch surface through `agentCommand()`. Earlier 2026-06-16 container commits are foundation only. The public `warded` shim arrives later at `dfa5610118258b9f11247618329b3fcbb7b82d10` on 2026-06-24, so using `warded` as the boundary misses the first week of agent failures. Current `main` for this pass is `7094eac57e5d713f0cec57fcdd285417ab4e02f6` on 2026-07-10. The boundary-to-main corpus is 987 commits. A simple local scan finds 540 direct `#N` references in commit messages, with more possible when counting URL and cross-repo forms. The recurring failure pattern is boundary drift: read-only surfaces accidentally use local Docker, runtime KDL or generated ops leaves leak into core agent paths, reservations outlive failed launches, bootstrap failures look like live work, and final outcome comments are trusted before the true landing boundary is verified. **Decisions** * **Boundary** - Use `c3d619f6d2fa` as the start. Mention `c2cb54cab825` and other container commits only as substrate when a test needs pre-agent container behavior. * **Existing smoke** - Treat ward#933 as useful but insufficient. `TestRunAgentTaskDirectRoutesThroughBrokerOnReadonlySurface` in `cmd/ward/agent_dispatch_broker_test.go` proves a read-only engineer task can file through a fake Forgejo and forward to a fake TCP broker. It does not prove Docker create/start, real asset staging, release binary download, bootstrap, auth gates, labels, or reaper behavior. * **Testing shape** - Keep cheap fake-server and fake-broker tests in normal `go test ./...`. Add one Docker-capable smoke job that crosses `read-only surface -> host broker -> Docker create/start -> short-lived no-op container`. * **Fixture stance** - No live LLMs, no live issue mutation, and no real pushes in CI. Use fake Forgejo/GitHub HTTP servers, local bare git remotes, file-based config bundles, and a tiny/no-op image selected through `WARD_AGENT_IMAGE`. * **Review doctrine** - Add root `CODE-REVIEW.md` using the agentic-os#402 shape: `## Localized invariants`, `## Historical issues`, and `## Update triggers`. It should contain only ward-specific invariants and historical failures. **Regression Matrix** * **Real brokered engineer dispatch smoke** - Sources: ward#315, ward#319, ward#321, ward#323, ward#389, ward#391, ward#900, ward#931, ward#932, ward#933. Commits: `4414c5d2dd7d`, `0d2a61aa67a7`, `d8dc72273567`, `7094eac57e5`. Boundary: director/read-only surface -> TCP dispatch broker -> host Docker -> engineer container. Fixtures: Docker socket, no-op image, temp gitcache, fake issue resolver, broker token. CI: Docker-capable release gate, PR gate only if the runner can expose Docker safely. Why: fake broker coverage cannot catch the failures that repeatedly broke real dispatch. * **Config and repo-authority dispatch policy** - Sources: ward#441, ward#453, ward#653-657, ward#876, ward#929, ward#931. Commit: `fcd5f2bfbdc8`. Boundary: config source -> smart defaults -> repo authority -> launch allow/refuse. Fixtures: `file://` bundle trusting `coilyco-flight-deck`, neutral bundle rejecting it, malformed bundle, no network. CI: normal integration. Why: #931 needed explicit `WARD_CONFIG_REF`, #876 hit smart-default recursion, and #929 showed core agent behavior depending on generated ops CLI shape. * **Reservation, launch, unlock, failed-forward comments** - Sources: ward#184, ward#264, ward#570, ward#595, ward#609, ward#689, ward#934. Commits: `a7779c05e308`, `2f900d630d2a`, `36f8f65c0e90`, `cd07ffd0c58a`, `0960b691450c`, `8025b73253ed`. Boundary: tracker reservation -> broker or launch -> pre-launch failure -> release/comment/retry marker. Fixtures: fake forge comments and locks, fake broker launch failures, release asset 404. CI: normal tests plus broker integration. Why: stale reservations repeatedly blocked retries or made failed work look active. * **Container bootstrap and auth fail-loud smoke** - Sources: ward#222, ward#273, ward#288, ward#357, ward#574, ward#597, ward#909, ward#934. Commits: `e74d9185b081`, `15c3602f34e6`, `9a131f0369b7`, `40b7eeb7fa57`, `4cf59d5ae6c`, `7a8d521`, `cd07ffd0c58a`. Boundary: release/version selection -> bootstrap download -> asset staging -> credential seeding -> harness smoke gate. Fixtures: local HTTP release server returning 404, fake credential files, snap-Docker-style path fixture, no-op image. CI: normal tests for selection/errors, Docker smoke for entrypoint behavior. Why: historical bootstrap/auth failures hung, mislabeled root cause, leaked secrets, or fell through to fake salvage. * **Reaper, salvage, and multi-repo done-condition** - Sources: ward#291, ward#504, ward#518, ward#529, ward#666, ward#667. Commits: `93b020ab871c`, `9013c9d125d0`, `343abb53a576`. Boundary: workspace git state -> primary and granted repo remotes -> issue outcome or salvage comment. Fixtures: local bare primary and granted remotes, fake carried issue, deliberate secondary push miss. CI: normal integration. Why: ward#291 proved a green issue can hide lost secondary-repo work unless every granted repo is verified. * **Director classification and tracker timeline parsing** - Sources: ward#310, ward#400, ward#402, ward#609, ward#613, ward#689, ward#900. Commits: `2e738e53dfd3`, `6a66d66b25c0`, `02f9a55c6023`, `8025b73253ed`. Boundary: Forgejo comments/reservations/outcomes -> director heartbeat classification -> broker-visible state/logs/list. Fixtures: synthetic timelines with reservation, release, failed dispatch, `WARD-OUTCOME`, stale PR, and missing local Docker. CI: normal unit/integration. Why: ward#900 shows a director can falsely classify broker-forwarded runs as failed by inspecting surface-local Docker. * **Workflow, PR, review gate, and GitHub done-condition** - Sources: ward#489, ward#786, ward#899, ward#901, ward#908, ward#922, ward#929. Commits: `763a26025be7`, `993e222417e2`, `40a37bf7d9d0`, `671c21d276d1`. Boundary: workflow config -> forge client -> PR create/read/merge policy -> final `WARD-OUTCOME`. Fixtures: fake Forgejo and GitHub APIs, protected-main behavior, stale PR 404, review skipped/passed markers. CI: normal integration. Why: workflow names and GitHub semantics changed late, and wrong done-condition logic is high impact. **Proposed CODE-REVIEW.md Draft** # Code review contract Code review here defends ward control-plane invariants and historical failures that have already stopped warded-agent work. ## Localized invariants * Core agent control-plane paths use ward-owned tracker, forge, broker, bootstrap, reservation, reaper, workflow, and review code. They do not depend on runtime-selected generated `ward ops` leaves. * A read-only director or surface session cannot push its clone and cannot use surface-local Docker for launch, list, logs, stop, or reconcile. Those actions go through the host dispatch broker or fail loudly. * A reservation is not a done-condition. Every pre-launch, broker, Docker, bootstrap, and smoke failure releases or supersedes the reservation and leaves a tracker-visible recovery marker. * Bootstrap fails before agent launch when the selected ward binary, entrypoint, credentials, Docker assets, tailnet network, or harness smoke gate is unavailable. It must not fall through to shell or salvage fake work. * A `WARD-OUTCOME` is trusted only after the workflow boundary is satisfied: direct-main landed, PR opened or merged as configured, GitHub path honored, review gate settled, and every granted repo verified or salvaged. * Director classification reads tracker markers and broker-visible host state. Missing Docker inside a read-only surface is not evidence that a broker-forwarded engineer failed. ## Historical issues * ward#222, ward#264, ward#273, ward#288, ward#357, ward#570, ward#574, ward#595, ward#597, ward#609, ward#689, ward#909, and ward#934 cover bootstrap, auth, credential, asset, reservation, and failed-forward regressions. * ward#315, ward#319, ward#321, ward#323, ward#389, ward#391, ward#900, ward#931, ward#932, and ward#933 cover read-only surface dispatch, broker transport, Docker reachability, and fake-vs-real smoke gaps. * ward#441, ward#453, ward#653-657, ward#876, ward#929, and ward#931 cover config-source and generated-surface drift breaking core dispatch. * ward#291, ward#518, ward#529, ward#666, and ward#667 cover false done outcomes, salvage, and granted-repo verification. * ward#489, ward#786, ward#899, ward#901, ward#908, and ward#922 cover GitHub, PR workflow, review, and director-merge semantics. ## Update triggers Refresh this file when a warded run needs manual recovery, when a launch path moves across process/container/forge boundaries, when generated surfaces are proposed for a core path, or when an issue repeats one of the historical failure modes above. **Options** * **Fake broker only** - cheap and already started by #933, but it leaves the highest-risk Docker/bootstrap boundary uncovered. * **Docker smoke in all PRs** - best regression signal, but only if the runner has a safe Docker socket and no live credentials. * **Docker smoke on release/schedule only** - lower PR friction, but dispatch regressions can reach main before the smoke catches them. * **Disposable Forgejo fixture** - closer to production, but more moving parts and flake. Use fake HTTP in PR/release CI and reserve disposable Forgejo for optional scheduled deep smoke. **Open Questions** * Does ward have a CI runner where a Docker socket can be safely exposed to a release-gating smoke? If not, make the real-Docker test scheduled or release-only until that runner exists. * Should the no-op smoke use a purpose-built tiny image, or should `WARD_SMOKE_TEST_SKIP` be tightened so Docker create/start still happens and only in-container agent work is skipped? Recommendation: tiny image through `WARD_AGENT_IMAGE`. * Should broker success mean request accepted, container created, or container observed started? The current thread shows forwarded-before-useful-run ambiguity. The smoke should encode the product decision. * Should ward preflight the selected `--ward-version` release asset before posting a reservation? ward#934 failed on a `v0.555.0` binary 404 after reservation, so either preflight it or require the failure path to release and comment loudly. * Should workflow names follow the current shipped `direct-main`/`pull-requests`/`pull-requests-and-merge`/`patch-only` compatibility, or the ward#786 desired contract with singular PR names and `remote-branch-only`? Tests need to pin the intended transition. **Risks** * Stopping at ward#933 leaves the main operational risk uncovered. * Live external services in CI will make the suite flaky. Keep Forgejo, GitHub, git remotes, and LLMs fake or local. * A Docker smoke can pass for the wrong reason if the simulated surface can touch local Docker. The surface process should run with broker env set and local Docker deliberately unavailable. * Generated config and ops surfaces are still moving. Tests should assert core agent paths are independent of runtime KDL/specgen shape. * Review doctrine without automated tests will decay into prose. `CODE-REVIEW.md` should point reviewers at these historical invariants and the tests should enforce the actual boundaries. --- Researched and posted automatically by `ward agent advisor --harness codex` (ward#179). This is one-shot research, not a carried change - verify before acting on it.   — Codex, via `ward agent`

coilyco-ops commented

2026-07-10 04:23:04 +00:00

Author

Member

🔎 ward agent advisor

ward agent advisor --harness codex ran a one-shot deep research pass on this question:

Read the issue title, body, and comment thread below as the research brief. Identify the decisions, options, open questions, and risks, then give a clear advisory recommendation that can be posted back on the issue.

Recommendation

Keep this as one coilyco-flight-deck/ward issue. The work is single-repo regression defense in ward. coilyco-flight-deck/agentic-os#402 only supplies the CODE-REVIEW.md contract shape.

Use c3d619f6d2fa786c6fccef27bdbf95d20ac3b4d0 from 2026-06-17 as the warded-agent era boundary. It is the first commit that adds the issue-seeded ward agent <name> work <issue> surface through agentCommand(). Earlier 2026-06-16 container commits are substrate. The public warded shim arrives later at dfa5610118258b9f11247618329b3fcbb7b82d10 on 2026-06-24, so using warded as the boundary misses the first failure-heavy week.

This pass checked current main at 7094eac57e5d713f0cec57fcdd285417ab4e02f6 from 2026-07-10. The boundary-to-main corpus is 987 commits with 554 direct issue references in commit text. The dominant regression pattern is boundary drift: read-only surfaces fall back to local Docker, generated ops or runtime KDL surfaces leak into core agent paths, reservations survive failed launches, bootstrap failures look like live work, and final WARD-OUTCOME markers are trusted before the actual landing boundary is verified.

Decisions

Boundary - use c3d619f6d2fa and cite the earlier container commits only as launch substrate.
Scope - keep this issue in ward. Do not split child issues.
Existing #933 test - keep TestRunAgentTaskDirectRoutesThroughBrokerOnReadonlySurface as a useful fake-broker routing regression. It does not prove Docker create/start, asset staging, release binary download, bootstrap, auth gates, labels, or reaper behavior.
Test stance - keep fake Forgejo/GitHub APIs, local bare git remotes, file config bundles, and no-op images. Do not require live LLMs, live issue mutation, or real pushes in normal CI.
CI placement - normal go test ./... for fake-server and local-git coverage. Add a Docker-capable smoke job for the real dispatch boundary, at least release-gated and PR-gated only if the runner can expose Docker safely.
Review doctrine - add a root CODE-REVIEW.md using the agentic-os#402 contract: localized invariants, historical issues, and update triggers only.

Regression Matrix

Real brokered engineer dispatch smoke - Sources: ward#315, ward#319, ward#321, ward#323, ward#389, ward#391, ward#900, ward#931, ward#932, ward#933. Commits include 87cc58a, e626d60, d8dc722, 4414c5d, 7094eac. Boundary: read-only surface -> dispatch broker -> host Docker socket -> engineer container. Fixtures: real Docker socket, no-op image through WARD_AGENT_IMAGE, fake issue resolver or local tracker, temp gitcache, broker token. CI: Docker-capable release smoke. Why: fake brokers cannot catch the failures that repeatedly broke real dispatch.
Config and repo-authority dispatch policy - Sources: ward#441, ward#453, ward#653-657, ward#876, ward#929, ward#931. Key commit: fcd5f2b. Boundary: config source -> smart defaults -> repo authority -> dispatch allow/refuse. Fixtures: trusted file:// bundle for coilyco-flight-deck, neutral bundle rejection, malformed bundle. CI: normal integration. Why: live failures required explicit WARD_CONFIG_REF, hit smart-default recursion, and exposed core-path dependence on generated ops shape.
Reservation, launch, unlock, failed-forward comments - Sources: ward#184, ward#264, ward#570, ward#595, ward#609, ward#689, ward#934. Commits include a7779c0, 2f900d6, 36f8f65, cd07ffd, 8025b73. Boundary: tracker reservation -> broker or launch -> pre-launch failure -> unlock/comment/retry marker. Fixtures: fake forge comments and locks, broker launch failures, release asset 404. CI: normal tests plus broker integration. Why: stale reservations repeatedly blocked retries or made failed work look active.
Container bootstrap and auth fail-loud smoke - Sources: ward#222, ward#273, ward#288, ward#357, ward#574, ward#597, ward#909, ward#934. Commits include e74d918, 15c3602, 9a131f0, 40b7eeb, 7a8d521. Boundary: release/version selection -> bootstrap download -> asset staging -> credential seeding -> harness smoke gate. Fixtures: local HTTP release server returning 404, fake credential files, snap-Docker path fixture, no-op image. CI: normal tests for selection and errors, Docker smoke for entrypoint behavior. Why: bootstrap/auth failures have historically hung, mislabeled root cause, or salvaged fake work.
Reaper, salvage, and multi-repo done-condition - Sources: ward#291, ward#504, ward#518, ward#529, ward#666, ward#667. Commits include 93b020a, 9013c9d, 343abb5, cee27a6. Boundary: workspace git state -> primary and granted repo remotes -> issue outcome or salvage comment. Fixtures: local bare primary and granted remotes, fake carried issue, deliberate secondary push miss. CI: normal integration. Why: ward#291 proved a green issue can hide lost secondary-repo work unless every granted repo is verified.
Director classification and tracker timeline parsing - Sources: ward#310, ward#400, ward#402, ward#609, ward#613, ward#689, ward#900. Commits include 2e738e5, 6a66d66, 02f9a55, 8025b73. Boundary: tracker comments/reservations/outcomes -> director heartbeat classification -> broker-visible state/logs/list. Fixtures: synthetic timelines with reservation, release, failed dispatch, WARD-OUTCOME, stale PR, and missing local Docker. CI: normal unit/integration. Why: ward#900 shows a director can falsely classify broker-forwarded runs by inspecting surface-local Docker.
Workflow, PR, review gate, and GitHub done-condition - Sources: ward#489, ward#786, ward#899, ward#901, ward#908, ward#922, ward#929. Commits include 671c21d, 763a260, 993e222, 40a37bf, aadd33d. Boundary: workflow config -> forge client -> PR create/read/merge policy -> final WARD-OUTCOME. Fixtures: fake Forgejo and GitHub APIs, protected-main behavior, stale PR 404, review skipped/passed markers. CI: normal integration. Why: workflow names and GitHub semantics changed late, and wrong done-condition logic is high impact.

Proposed CODE-REVIEW.md Draft

# Code review contract

Code review here defends ward control-plane invariants and historical failures that have already stopped warded-agent work.

## Localized invariants

* Core agent control-plane paths use ward-owned tracker, forge, broker, bootstrap, reservation, reaper, workflow, and review code. They do not depend on runtime-selected generated `ward ops` leaves.
* A read-only director or surface session cannot push its clone and cannot use surface-local Docker for launch, list, logs, stop, or reconcile. Those actions go through the host dispatch broker or fail loudly.
* A reservation is not a done-condition. Every pre-launch, broker, Docker, bootstrap, and smoke failure releases or supersedes the reservation and leaves a tracker-visible recovery marker.
* Bootstrap fails before agent launch when the selected ward binary, entrypoint, credentials, Docker assets, tailnet network, or harness smoke gate is unavailable. It must not fall through to shell or salvage fake work.
* A `WARD-OUTCOME` is trusted only after the workflow boundary is satisfied: direct-main landed, PR opened or merged as configured, GitHub path honored, review gate settled, and every granted repo verified or salvaged.
* Director classification reads tracker markers and broker-visible host state. Missing Docker inside a read-only surface is not evidence that a broker-forwarded engineer failed.

## Historical issues

* ward#222, ward#264, ward#273, ward#288, ward#357, ward#570, ward#574, ward#595, ward#597, ward#609, ward#689, ward#909, and ward#934 cover bootstrap, auth, credential, asset, reservation, and failed-forward regressions.
* ward#315, ward#319, ward#321, ward#323, ward#389, ward#391, ward#900, ward#931, ward#932, and ward#933 cover read-only surface dispatch, broker transport, Docker reachability, and fake-vs-real smoke gaps.
* ward#441, ward#453, ward#653-657, ward#876, ward#929, and ward#931 cover config-source and generated-surface drift breaking core dispatch.
* ward#291, ward#518, ward#529, ward#666, and ward#667 cover false done outcomes, salvage, and granted-repo verification.
* ward#489, ward#786, ward#899, ward#901, ward#908, and ward#922 cover GitHub, PR workflow, review, and director-merge semantics.

## Update triggers

Refresh this file when a warded run needs manual recovery, when a launch path moves across process/container/forge boundaries, when generated surfaces are proposed for a core path, or when an issue repeats one of the historical failure modes above.

Options

Fake broker only - cheap and already landed through #933, but it leaves the highest-risk Docker/bootstrap boundary uncovered.
Docker smoke in all PRs - best signal, but only if the runner can expose Docker safely without live credentials.
Docker smoke on release or schedule only - lower PR friction, but dispatch regressions can reach main before the smoke catches them.
Disposable Forgejo fixture - closer to production, but higher flake risk. Prefer fake HTTP in PR/release CI and reserve disposable Forgejo for scheduled deep smoke.

Open Questions

Does ward have a CI runner where the Docker socket can be safely exposed to a release-gating smoke?
Should the no-op smoke use a tiny purpose-built image, or should WARD_SMOKE_TEST_SKIP be tightened so Docker create/start still happens and only in-container agent work is skipped? Recommendation: use a tiny image through WARD_AGENT_IMAGE.
Should broker success mean request accepted, container created, or container observed started? The smoke should encode the product decision.
Should ward preflight the selected --ward-version release asset before posting a reservation? ward#934 failed on a v0.555.0 binary 404 after reservation, so either preflight it or require the late failure path to release and comment loudly.
Should workflow aliases remain compatibility-only, or should tests pin the newer singular contract from ward#786? The suite needs one intended transition point.

Risks

Stopping at ward#933 leaves the main operational risk uncovered.
Live external services in CI will make the suite flaky. Keep Forgejo, GitHub, git remotes, and LLMs fake or local.
A Docker smoke can pass for the wrong reason if the simulated surface can touch local Docker. The surface subprocess should run with broker env set and local Docker deliberately unavailable.
Generated config and ops surfaces are still moving. Tests should assert core agent paths are independent of runtime KDL/specgen shape.
Review doctrine without tests will decay into prose. CODE-REVIEW.md should point reviewers at these historical invariants, while the tests enforce the actual boundaries.

Researched and posted automatically by ward agent advisor --harness codex (ward#179). This is one-shot research, not a carried change - verify before acting on it.

— Codex, via ward agent

### 🔎 ward agent advisor `ward agent advisor --harness codex` ran a one-shot **deep** research pass on this question: > Read the issue title, body, and comment thread below as the research brief. Identify the decisions, options, open questions, and risks, then give a clear advisory recommendation that can be posted back on the issue. --- **Recommendation** Keep this as one `coilyco-flight-deck/ward` issue. The work is single-repo regression defense in ward. `coilyco-flight-deck/agentic-os#402` only supplies the `CODE-REVIEW.md` contract shape. Use `c3d619f6d2fa786c6fccef27bdbf95d20ac3b4d0` from 2026-06-17 as the warded-agent era boundary. It is the first commit that adds the issue-seeded `ward agent <name> work <issue>` surface through `agentCommand()`. Earlier 2026-06-16 container commits are substrate. The public `warded` shim arrives later at `dfa5610118258b9f11247618329b3fcbb7b82d10` on 2026-06-24, so using `warded` as the boundary misses the first failure-heavy week. This pass checked current `main` at `7094eac57e5d713f0cec57fcdd285417ab4e02f6` from 2026-07-10. The boundary-to-main corpus is 987 commits with 554 direct issue references in commit text. The dominant regression pattern is boundary drift: read-only surfaces fall back to local Docker, generated ops or runtime KDL surfaces leak into core agent paths, reservations survive failed launches, bootstrap failures look like live work, and final `WARD-OUTCOME` markers are trusted before the actual landing boundary is verified. **Decisions** * Boundary - use `c3d619f6d2fa` and cite the earlier container commits only as launch substrate. * Scope - keep this issue in ward. Do not split child issues. * Existing #933 test - keep `TestRunAgentTaskDirectRoutesThroughBrokerOnReadonlySurface` as a useful fake-broker routing regression. It does not prove Docker create/start, asset staging, release binary download, bootstrap, auth gates, labels, or reaper behavior. * Test stance - keep fake Forgejo/GitHub APIs, local bare git remotes, file config bundles, and no-op images. Do not require live LLMs, live issue mutation, or real pushes in normal CI. * CI placement - normal `go test ./...` for fake-server and local-git coverage. Add a Docker-capable smoke job for the real dispatch boundary, at least release-gated and PR-gated only if the runner can expose Docker safely. * Review doctrine - add a root `CODE-REVIEW.md` using the agentic-os#402 contract: localized invariants, historical issues, and update triggers only. **Regression Matrix** * Real brokered engineer dispatch smoke - Sources: ward#315, ward#319, ward#321, ward#323, ward#389, ward#391, ward#900, ward#931, ward#932, ward#933. Commits include `87cc58a`, `e626d60`, `d8dc722`, `4414c5d`, `7094eac`. Boundary: read-only surface -> dispatch broker -> host Docker socket -> engineer container. Fixtures: real Docker socket, no-op image through `WARD_AGENT_IMAGE`, fake issue resolver or local tracker, temp gitcache, broker token. CI: Docker-capable release smoke. Why: fake brokers cannot catch the failures that repeatedly broke real dispatch. * Config and repo-authority dispatch policy - Sources: ward#441, ward#453, ward#653-657, ward#876, ward#929, ward#931. Key commit: `fcd5f2b`. Boundary: config source -> smart defaults -> repo authority -> dispatch allow/refuse. Fixtures: trusted `file://` bundle for `coilyco-flight-deck`, neutral bundle rejection, malformed bundle. CI: normal integration. Why: live failures required explicit `WARD_CONFIG_REF`, hit smart-default recursion, and exposed core-path dependence on generated ops shape. * Reservation, launch, unlock, failed-forward comments - Sources: ward#184, ward#264, ward#570, ward#595, ward#609, ward#689, ward#934. Commits include `a7779c0`, `2f900d6`, `36f8f65`, `cd07ffd`, `8025b73`. Boundary: tracker reservation -> broker or launch -> pre-launch failure -> unlock/comment/retry marker. Fixtures: fake forge comments and locks, broker launch failures, release asset 404. CI: normal tests plus broker integration. Why: stale reservations repeatedly blocked retries or made failed work look active. * Container bootstrap and auth fail-loud smoke - Sources: ward#222, ward#273, ward#288, ward#357, ward#574, ward#597, ward#909, ward#934. Commits include `e74d918`, `15c3602`, `9a131f0`, `40b7eeb`, `7a8d521`. Boundary: release/version selection -> bootstrap download -> asset staging -> credential seeding -> harness smoke gate. Fixtures: local HTTP release server returning 404, fake credential files, snap-Docker path fixture, no-op image. CI: normal tests for selection and errors, Docker smoke for entrypoint behavior. Why: bootstrap/auth failures have historically hung, mislabeled root cause, or salvaged fake work. * Reaper, salvage, and multi-repo done-condition - Sources: ward#291, ward#504, ward#518, ward#529, ward#666, ward#667. Commits include `93b020a`, `9013c9d`, `343abb5`, `cee27a6`. Boundary: workspace git state -> primary and granted repo remotes -> issue outcome or salvage comment. Fixtures: local bare primary and granted remotes, fake carried issue, deliberate secondary push miss. CI: normal integration. Why: ward#291 proved a green issue can hide lost secondary-repo work unless every granted repo is verified. * Director classification and tracker timeline parsing - Sources: ward#310, ward#400, ward#402, ward#609, ward#613, ward#689, ward#900. Commits include `2e738e5`, `6a66d66`, `02f9a55`, `8025b73`. Boundary: tracker comments/reservations/outcomes -> director heartbeat classification -> broker-visible state/logs/list. Fixtures: synthetic timelines with reservation, release, failed dispatch, `WARD-OUTCOME`, stale PR, and missing local Docker. CI: normal unit/integration. Why: ward#900 shows a director can falsely classify broker-forwarded runs by inspecting surface-local Docker. * Workflow, PR, review gate, and GitHub done-condition - Sources: ward#489, ward#786, ward#899, ward#901, ward#908, ward#922, ward#929. Commits include `671c21d`, `763a260`, `993e222`, `40a37bf`, `aadd33d`. Boundary: workflow config -> forge client -> PR create/read/merge policy -> final `WARD-OUTCOME`. Fixtures: fake Forgejo and GitHub APIs, protected-main behavior, stale PR 404, review skipped/passed markers. CI: normal integration. Why: workflow names and GitHub semantics changed late, and wrong done-condition logic is high impact. **Proposed `CODE-REVIEW.md` Draft** ```markdown # Code review contract Code review here defends ward control-plane invariants and historical failures that have already stopped warded-agent work. ## Localized invariants * Core agent control-plane paths use ward-owned tracker, forge, broker, bootstrap, reservation, reaper, workflow, and review code. They do not depend on runtime-selected generated `ward ops` leaves. * A read-only director or surface session cannot push its clone and cannot use surface-local Docker for launch, list, logs, stop, or reconcile. Those actions go through the host dispatch broker or fail loudly. * A reservation is not a done-condition. Every pre-launch, broker, Docker, bootstrap, and smoke failure releases or supersedes the reservation and leaves a tracker-visible recovery marker. * Bootstrap fails before agent launch when the selected ward binary, entrypoint, credentials, Docker assets, tailnet network, or harness smoke gate is unavailable. It must not fall through to shell or salvage fake work. * A `WARD-OUTCOME` is trusted only after the workflow boundary is satisfied: direct-main landed, PR opened or merged as configured, GitHub path honored, review gate settled, and every granted repo verified or salvaged. * Director classification reads tracker markers and broker-visible host state. Missing Docker inside a read-only surface is not evidence that a broker-forwarded engineer failed. ## Historical issues * ward#222, ward#264, ward#273, ward#288, ward#357, ward#570, ward#574, ward#595, ward#597, ward#609, ward#689, ward#909, and ward#934 cover bootstrap, auth, credential, asset, reservation, and failed-forward regressions. * ward#315, ward#319, ward#321, ward#323, ward#389, ward#391, ward#900, ward#931, ward#932, and ward#933 cover read-only surface dispatch, broker transport, Docker reachability, and fake-vs-real smoke gaps. * ward#441, ward#453, ward#653-657, ward#876, ward#929, and ward#931 cover config-source and generated-surface drift breaking core dispatch. * ward#291, ward#518, ward#529, ward#666, and ward#667 cover false done outcomes, salvage, and granted-repo verification. * ward#489, ward#786, ward#899, ward#901, ward#908, and ward#922 cover GitHub, PR workflow, review, and director-merge semantics. ## Update triggers Refresh this file when a warded run needs manual recovery, when a launch path moves across process/container/forge boundaries, when generated surfaces are proposed for a core path, or when an issue repeats one of the historical failure modes above. ``` **Options** * Fake broker only - cheap and already landed through #933, but it leaves the highest-risk Docker/bootstrap boundary uncovered. * Docker smoke in all PRs - best signal, but only if the runner can expose Docker safely without live credentials. * Docker smoke on release or schedule only - lower PR friction, but dispatch regressions can reach main before the smoke catches them. * Disposable Forgejo fixture - closer to production, but higher flake risk. Prefer fake HTTP in PR/release CI and reserve disposable Forgejo for scheduled deep smoke. **Open Questions** * Does ward have a CI runner where the Docker socket can be safely exposed to a release-gating smoke? * Should the no-op smoke use a tiny purpose-built image, or should `WARD_SMOKE_TEST_SKIP` be tightened so Docker create/start still happens and only in-container agent work is skipped? Recommendation: use a tiny image through `WARD_AGENT_IMAGE`. * Should broker success mean request accepted, container created, or container observed started? The smoke should encode the product decision. * Should ward preflight the selected `--ward-version` release asset before posting a reservation? ward#934 failed on a `v0.555.0` binary 404 after reservation, so either preflight it or require the late failure path to release and comment loudly. * Should workflow aliases remain compatibility-only, or should tests pin the newer singular contract from ward#786? The suite needs one intended transition point. **Risks** * Stopping at ward#933 leaves the main operational risk uncovered. * Live external services in CI will make the suite flaky. Keep Forgejo, GitHub, git remotes, and LLMs fake or local. * A Docker smoke can pass for the wrong reason if the simulated surface can touch local Docker. The surface subprocess should run with broker env set and local Docker deliberately unavailable. * Generated config and ops surfaces are still moving. Tests should assert core agent paths are independent of runtime KDL/specgen shape. * Review doctrine without tests will decay into prose. `CODE-REVIEW.md` should point reviewers at these historical invariants, while the tests enforce the actual boundaries. --- Researched and posted automatically by `ward agent advisor --harness codex` (ward#179). This is one-shot research, not a carried change - verify before acting on it.   — Codex, via `ward agent`

coilyco-ops added the

consult

labels

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

coilyco-ops added

and removed

labels

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