coilyco-flight-deck/ward

Archived

Watch

V1 deletion pass: remove dead compatibility, private workflow, and non-AgentOps surface #1015

Closed

opened 2026-07-10 10:21:32 +00:00 by coilysiren · 0 comments

coilysiren commented

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

Owner

The problem

Proposed change

Body

Summary

Perform a surgical deletion pass before Ward v1, using the new product positioning as the boundary:

Ward is the operations layer for unattended coding agents.

This supersedes the earlier “apex cut” framing. Ward should retain complexity that materially makes unattended agents dependable: isolation, observability, reservation, recovery, review, supervision, and workflow closure.

The deletion target is code that:

Produces no meaningful user outcome
Exists only for expired pre-v1 compatibility
Encodes a private fleet workflow as public product behavior
Belongs to generic infrastructure operations rather than coding-agent operations
Advertises an integration Ward cannot support at v1 reliability
Reimplements nothing useful and survives only through tests

The goal is to remove code, not reorganize it into a new abstraction layer.

Product boundary

Ward v1 should be able to explain every retained feature through this lifecycle:

Accept agent work.
Reserve and isolate it.
Launch the selected harness.
Observe and supervise the run.
Preserve work through failure.
Review and govern the result.
Produce a durable outcome.
Clean up.

A feature does not need to appear in onboarding to belong. Hidden operational complexity is valuable when it makes this lifecycle dependable.

Delete now

1. Remove `ward setup`

Delete:

cmd/ward/setup.go
cmd/ward/setup_test.go
Root command registration
Feature-list and example references
Setup-specific compile-root scaffolding

The current command describes credential and host-integration phases as stubs. Its implemented behavior is primarily config warming and compiling surfaces that normal commands already load.

It is neither meaningful onboarding nor a complete doctor command. Reintroduce setup only if Ward later has an actual guided installation and validation workflow.

2. Remove the generic `ward ops` runtime surface

Delete the public generic operator CLI generated from ward-kdl:

Root ward ops command
Runtime spec compilation and command grafting
Embedded opsassets
Generated-asset drift tests
Generic Forgejo admin/REST command wrappers that are not required by agent execution
ops-forgejo public documentation
Release instructions that rely on self-shelling through ward ops

Do not remove the focused tracker and forge clients used directly by agent reservation, comments, PR handling, reaping, or director reconciliation.

The code already documents that the agent control plane does not depend on generated ward ops leaves. Generic REST and infrastructure command generation is not part of the “operations layer for unattended coding agents” category.

ward-kdl may remain as a build-time authoring tool for relevant guarded execution surfaces. This deletion targets its generic operator API being mounted into the Ward runtime.

3. Remove the automatic latest-release dispatch nag

Delete:

cmd/ward/agent_upgrade.go
cmd/ward/agent_upgrade_test.go
Calls to maybeWarnWardOutdated
The self-invocation of ward ops forgejo release list

A best-effort network request before agent launches is not part of dispatch correctness. It silently adds latency and currently depends on the unrelated generic ops surface.

Version compatibility must fail loudly when it is required for correctness. General upgrade discovery belongs in release tooling, package managers, or an explicit version-check command.

4. Remove freeform automatic repository routing

Delete:

cmd/ward/agent_route.go
cmd/ward/agent_route_test.go
The hardcoded coilysiren/inbox intake workflow
Live cross-owner repository surveys
Unsandboxed host-model repository selection
Automatic intake creation, child creation, cross-linking, and closing
Route-specific prompt, verdict, and bounce behavior

Retain explicit work dispatch:

Issue references
Explicit owner/repo
Repository inference from the current checkout where unambiguous
Instructions supplied against an explicit target

Freeform text should not create external issue state or let a host-side model choose a repository during v1. The existing behavior is a private workflow encoded as generic product behavior and creates several failure opportunities before the real run begins.

A future generic intake router should be justified independently and driven entirely by user configuration.

5. Remove expired compatibility aliases

Remove all compatibility paths described as deprecated, legacy, or retained for one release, including:

qwen as an alias for opencode
--driver
--engineer-driver
Deprecated workflow spellings
Deprecated --aws
Deprecated --tailnet
Hidden compatibility-only --tailnet-mode behavior where it exists solely to support the deprecated flag
Old environment-variable aliases
Broker acceptance of removed flag spellings
Tests whose only purpose is preserving pre-v1 skew

Retain canonical concepts and spellings:

--harness
--agent, if both spellings remain an intentional public decision
opencode
Canonical workflow values
Config-driven AWS and tailnet capabilities where still supported

V1 is the compatibility boundary. Do not publish already-expired transition paths as permanent API.

6. Remove the dead agent sink selector

Delete:

WARD_AGENT_SINK
sinkMode
resolveSinkMode
Legacy sink tests and logging

The drain always writes a local disk archive regardless of the selected value. A configuration knob that does not alter behavior is misleading.

Retain the actual local archive, redacted view, metadata, and run observability.

7. Collapse the generated semantic-role machinery

Delete the semantic-capability abstraction that exists only to render role descriptions:

cmd/ward/agent_semantic_capabilities.go
Its dedicated tests
Generic set composition and parsing that do not enforce runtime policy
ward agent roster --markdown
Generated Markdown regeneration and drift machinery, if it provides no other contract

Retain discoverability through ordinary CLI command descriptions and a short maintained role guide.

If capability names remain useful in roster output, store the four current descriptions directly with their role metadata. Do not maintain a composable semantic authorization model that is not consulted for authorization.

Remove from v1 unless a live deployment is identified

GitLab agent integration

Delete the GitLab tracker, merge-request, workflow, parsing, credential, prompt, and test branches unless a current Ward operator depends on them.

Supporting a forge means owning its authentication, issue semantics, review object, CI integration, error handling, and recovery behavior. Parser acceptance without demonstrated end-to-end operation weakens Ward’s reliability claim.

Shortcut tracker integration

Delete the Shortcut client and its story/workflow-state behavior unless a current Ward operator depends on it.

Shortcut introduces a second tracker model detached from repository authority and is not necessary for the initial Forgejo/GitHub agent-operations spearpoint.

Decision deadline

Before implementation, search current configuration and deployment documentation for a live GitLab or Shortcut consumer.

If none exists, remove the integration.
If one exists, name the owner and supported workflow explicitly and remove this item from the deletion issue.
Do not preserve speculative support.

Explicitly retain

This issue must not become the earlier apex cut. Retain:

ward exec
ward git
ward audit
ward agent engineer
Director and native-goal integration
Reservation and concurrency control
Reaping, cleanup, and salvage
Run logs, redacted artifacts, and outcome metadata
Review and QA pending a separate duplication analysis
Brokered control required for safe read-only supervision
Container isolation
Forgejo agent integration
GitHub agent integration
Harness support for Claude Code, Codex, Goose, and OpenCode
AWS and tailnet capabilities that are still intentionally granted through current role configuration
Substrate and multi-repository context pending usage evidence
Supported landing workflows pending a separate policy review
Runtime configuration required by retained AgentOps behavior

These features may be hidden from the first-run experience while remaining part of Ward’s operational depth.

Documentation cleanup

As each feature is removed:

Delete its documentation rather than leaving a historical explanation.
Remove source comments pointing to deleted or nonexistent pages.
Remove examples and help text advertising removed behavior.
Update README.md, AGENTS.md, docs/FEATURES.md, and the docs index.
Ensure the new AgentOps positioning remains accurate after the reduced surface.
Do not replace removed pages with migration essays unless an actual external user needs one.

The current source refers to numerous documentation files that no longer exist. This pass should eliminate stale references in every touched subsystem.

Implementation constraints

Prefer complete vertical deletion: implementation, tests, docs, assets, flags, and configuration.
Do not add a plugin framework to preserve removed features.
Do not retain hidden aliases “just in case.”
Do not replace removed generated behavior with equivalent handwritten behavior.
Do not refactor unrelated retained systems during the deletion.
Keep each commit buildable and focused on one deletion slice.
Preserve unrelated user changes in the worktree.

Suggested order

Expired aliases and dead environment knobs
ward setup
Latest-release nag
Freeform route mode
Generic ward ops
Semantic roster machinery
GitLab and Shortcut after the live-consumer check
Documentation and generated-asset cleanup

Removing ward ops after the release nag avoids preserving the nag through a temporary replacement implementation.

Acceptance criteria

ward setup is no longer registered.
ward ops is no longer registered or embedded.
Agent launch performs no best-effort release lookup.
Freeform work cannot file an intake or select a repository automatically.
No public or hidden parser accepts the removed compatibility aliases.
WARD_AGENT_SINK has no runtime meaning and is undocumented.
Semantic capabilities do not exist as a non-enforcing parallel policy model.
GitLab and Shortcut are either removed or have a named live consumer documented in the issue.
Forgejo and GitHub agent workflows continue to operate.
Reservations, isolation, logs, reaping, review, director supervision, and workflow closure remain intact.
Tests and docs contain no references to removed behavior.
The implementation is materially net-negative in source, tests, generated assets, and documentation.
No replacement abstraction offsets the deletion.
The full validation suite passes.

Expected result

This should remove several thousand lines while preserving Ward’s differentiated value.

The resulting boundary should be clearer:

Ward contains sophisticated machinery when that machinery helps operate unattended coding agents. It does not carry generic infrastructure APIs, private intake workflows, dead configuration, or expired pre-v1 compatibility.

Alternatives considered

Before filing

I searched existing issues and this is not a duplicate.
This stays within ward's scope (the dev-verb gate / agent driver), not a personal-infra or downstream-repo verb.

### The problem // ### Proposed change **Body** ## Summary Perform a surgical deletion pass before Ward v1, using the new product positioning as the boundary: > **Ward is the operations layer for unattended coding agents.** This supersedes the earlier “apex cut” framing. Ward should retain complexity that materially makes unattended agents dependable: isolation, observability, reservation, recovery, review, supervision, and workflow closure. The deletion target is code that: * Produces no meaningful user outcome * Exists only for expired pre-v1 compatibility * Encodes a private fleet workflow as public product behavior * Belongs to generic infrastructure operations rather than coding-agent operations * Advertises an integration Ward cannot support at v1 reliability * Reimplements nothing useful and survives only through tests The goal is to remove code, not reorganize it into a new abstraction layer. ## Product boundary Ward v1 should be able to explain every retained feature through this lifecycle: 1. Accept agent work. 2. Reserve and isolate it. 3. Launch the selected harness. 4. Observe and supervise the run. 5. Preserve work through failure. 6. Review and govern the result. 7. Produce a durable outcome. 8. Clean up. A feature does not need to appear in onboarding to belong. Hidden operational complexity is valuable when it makes this lifecycle dependable. ## Delete now ### 1. Remove `ward setup` Delete: * `cmd/ward/setup.go` * `cmd/ward/setup_test.go` * Root command registration * Feature-list and example references * Setup-specific compile-root scaffolding The current command describes credential and host-integration phases as stubs. Its implemented behavior is primarily config warming and compiling surfaces that normal commands already load. It is neither meaningful onboarding nor a complete doctor command. Reintroduce setup only if Ward later has an actual guided installation and validation workflow. ### 2. Remove the generic `ward ops` runtime surface Delete the public generic operator CLI generated from ward-kdl: * Root `ward ops` command * Runtime spec compilation and command grafting * Embedded `opsassets` * Generated-asset drift tests * Generic Forgejo admin/REST command wrappers that are not required by agent execution * `ops-forgejo` public documentation * Release instructions that rely on self-shelling through `ward ops` Do not remove the focused tracker and forge clients used directly by agent reservation, comments, PR handling, reaping, or director reconciliation. The code already documents that the agent control plane does not depend on generated `ward ops` leaves. Generic REST and infrastructure command generation is not part of the “operations layer for unattended coding agents” category. ward-kdl may remain as a build-time authoring tool for relevant guarded execution surfaces. This deletion targets its generic operator API being mounted into the Ward runtime. ### 3. Remove the automatic latest-release dispatch nag Delete: * `cmd/ward/agent_upgrade.go` * `cmd/ward/agent_upgrade_test.go` * Calls to `maybeWarnWardOutdated` * The self-invocation of `ward ops forgejo release list` A best-effort network request before agent launches is not part of dispatch correctness. It silently adds latency and currently depends on the unrelated generic ops surface. Version compatibility must fail loudly when it is required for correctness. General upgrade discovery belongs in release tooling, package managers, or an explicit version-check command. ### 4. Remove freeform automatic repository routing Delete: * `cmd/ward/agent_route.go` * `cmd/ward/agent_route_test.go` * The hardcoded `coilysiren/inbox` intake workflow * Live cross-owner repository surveys * Unsandboxed host-model repository selection * Automatic intake creation, child creation, cross-linking, and closing * Route-specific prompt, verdict, and bounce behavior Retain explicit work dispatch: * Issue references * Explicit `owner/repo` * Repository inference from the current checkout where unambiguous * Instructions supplied against an explicit target Freeform text should not create external issue state or let a host-side model choose a repository during v1. The existing behavior is a private workflow encoded as generic product behavior and creates several failure opportunities before the real run begins. A future generic intake router should be justified independently and driven entirely by user configuration. ### 5. Remove expired compatibility aliases Remove all compatibility paths described as deprecated, legacy, or retained for one release, including: * `qwen` as an alias for `opencode` * `--driver` * `--engineer-driver` * Deprecated workflow spellings * Deprecated `--aws` * Deprecated `--tailnet` * Hidden compatibility-only `--tailnet-mode` behavior where it exists solely to support the deprecated flag * Old environment-variable aliases * Broker acceptance of removed flag spellings * Tests whose only purpose is preserving pre-v1 skew Retain canonical concepts and spellings: * `--harness` * `--agent`, if both spellings remain an intentional public decision * `opencode` * Canonical workflow values * Config-driven AWS and tailnet capabilities where still supported V1 is the compatibility boundary. Do not publish already-expired transition paths as permanent API. ### 6. Remove the dead agent sink selector Delete: * `WARD_AGENT_SINK` * `sinkMode` * `resolveSinkMode` * Legacy sink tests and logging The drain always writes a local disk archive regardless of the selected value. A configuration knob that does not alter behavior is misleading. Retain the actual local archive, redacted view, metadata, and run observability. ### 7. Collapse the generated semantic-role machinery Delete the semantic-capability abstraction that exists only to render role descriptions: * `cmd/ward/agent_semantic_capabilities.go` * Its dedicated tests * Generic set composition and parsing that do not enforce runtime policy * `ward agent roster --markdown` * Generated Markdown regeneration and drift machinery, if it provides no other contract Retain discoverability through ordinary CLI command descriptions and a short maintained role guide. If capability names remain useful in roster output, store the four current descriptions directly with their role metadata. Do not maintain a composable semantic authorization model that is not consulted for authorization. ## Remove from v1 unless a live deployment is identified ### GitLab agent integration Delete the GitLab tracker, merge-request, workflow, parsing, credential, prompt, and test branches unless a current Ward operator depends on them. Supporting a forge means owning its authentication, issue semantics, review object, CI integration, error handling, and recovery behavior. Parser acceptance without demonstrated end-to-end operation weakens Ward’s reliability claim. ### Shortcut tracker integration Delete the Shortcut client and its story/workflow-state behavior unless a current Ward operator depends on it. Shortcut introduces a second tracker model detached from repository authority and is not necessary for the initial Forgejo/GitHub agent-operations spearpoint. ### Decision deadline Before implementation, search current configuration and deployment documentation for a live GitLab or Shortcut consumer. * If none exists, remove the integration. * If one exists, name the owner and supported workflow explicitly and remove this item from the deletion issue. * Do not preserve speculative support. ## Explicitly retain This issue must not become the earlier apex cut. Retain: * `ward exec` * `ward git` * `ward audit` * `ward agent engineer` * Director and native-goal integration * Reservation and concurrency control * Reaping, cleanup, and salvage * Run logs, redacted artifacts, and outcome metadata * Review and QA pending a separate duplication analysis * Brokered control required for safe read-only supervision * Container isolation * Forgejo agent integration * GitHub agent integration * Harness support for Claude Code, Codex, Goose, and OpenCode * AWS and tailnet capabilities that are still intentionally granted through current role configuration * Substrate and multi-repository context pending usage evidence * Supported landing workflows pending a separate policy review * Runtime configuration required by retained AgentOps behavior These features may be hidden from the first-run experience while remaining part of Ward’s operational depth. ## Documentation cleanup As each feature is removed: * Delete its documentation rather than leaving a historical explanation. * Remove source comments pointing to deleted or nonexistent pages. * Remove examples and help text advertising removed behavior. * Update `README.md`, `AGENTS.md`, `docs/FEATURES.md`, and the docs index. * Ensure the new AgentOps positioning remains accurate after the reduced surface. * Do not replace removed pages with migration essays unless an actual external user needs one. The current source refers to numerous documentation files that no longer exist. This pass should eliminate stale references in every touched subsystem. ## Implementation constraints * Prefer complete vertical deletion: implementation, tests, docs, assets, flags, and configuration. * Do not add a plugin framework to preserve removed features. * Do not retain hidden aliases “just in case.” * Do not replace removed generated behavior with equivalent handwritten behavior. * Do not refactor unrelated retained systems during the deletion. * Keep each commit buildable and focused on one deletion slice. * Preserve unrelated user changes in the worktree. ## Suggested order 1. Expired aliases and dead environment knobs 2. `ward setup` 3. Latest-release nag 4. Freeform route mode 5. Generic `ward ops` 6. Semantic roster machinery 7. GitLab and Shortcut after the live-consumer check 8. Documentation and generated-asset cleanup Removing `ward ops` after the release nag avoids preserving the nag through a temporary replacement implementation. ## Acceptance criteria * `ward setup` is no longer registered. * `ward ops` is no longer registered or embedded. * Agent launch performs no best-effort release lookup. * Freeform work cannot file an intake or select a repository automatically. * No public or hidden parser accepts the removed compatibility aliases. * `WARD_AGENT_SINK` has no runtime meaning and is undocumented. * Semantic capabilities do not exist as a non-enforcing parallel policy model. * GitLab and Shortcut are either removed or have a named live consumer documented in the issue. * Forgejo and GitHub agent workflows continue to operate. * Reservations, isolation, logs, reaping, review, director supervision, and workflow closure remain intact. * Tests and docs contain no references to removed behavior. * The implementation is materially net-negative in source, tests, generated assets, and documentation. * No replacement abstraction offsets the deletion. * The full validation suite passes. ## Expected result This should remove several thousand lines while preserving Ward’s differentiated value. The resulting boundary should be clearer: > Ward contains sophisticated machinery when that machinery helps operate unattended coding agents. It does not carry generic infrastructure APIs, private intake workflows, dead configuration, or expired pre-v1 compatibility. ### Alternatives considered // ### Before filing - [x] I searched existing issues and this is not a duplicate. - [x] This stays within ward's scope (the dev-verb gate / agent driver), not a personal-infra or downstream-repo verb.