Rewrite FEATURES.md as a brand-neutral capability inventory

coilyco-ops commented

2026-07-31 07:09:01 +00:00

Member

Outcome

Make docs/FEATURES.md a concise inventory of Ward's major product capabilities.

The feature inventory must describe what Ward enables without duplicating provider compatibility, implementation details, diagnostics, bugfixes, or release plumbing.

Documentation boundary

docs/FEATURES.md is brand-neutral and capability-oriented.
docs/compat-surface.md is brand-explicit and records the honest provider matrix, partial support, and unsupported providers.
Feature-specific walkthroughs explain behavior and contracts.
Release notes, issues, and source comments carry implementation details and narrow fixes.

Provider names may remain in the compatibility matrix and provider-specific walkthroughs. They should not appear in the coarse feature inventory.

Current problem

The current feature inventory mixes major capabilities with:

explicit harness and forge names
provider-specific RPC and issue operations
harness-specific failure buffering
browser restrictions for one harness
launch-intent implementation details
reservation cleanup mechanics
PR repair classification
artifact selectors
release workflow implementation
features already approved for removal

That makes Ward appear coupled to specific providers and turns the inventory into a partial changelog.

Scope

Rewrite docs/FEATURES.md around a small set of durable product capabilities.
Describe harness support as typed or guarded harness integration without listing brands.
Describe issue, tracker, forge, and PR operations by capability without naming a provider.
Describe observability and failure handling generically.
Remove implementation-level bullets such as internal state splits, cleanup mechanisms, repair classifiers, and artifact selectors unless they materially define a public capability.
Remove narrow negative implementation facts such as disabling one harness's browser integration.
Replace release workflow mechanics with at most one durable release-distribution capability, if release belongs in the inventory at all.
Keep one clear link to docs/compat-surface.md for provider support details.
Review docs/compat-surface.md for missing provider truth exposed by removing names from the feature inventory. Do not falsely claim provider neutrality where adapters remain partial.
Coordinate already-approved removals:
- #1620 removes autonomous burndown.
- #1621 removes the demo image and toy application.
- #1622 removes AOS and AOSguard from the shipped product contract.
Align the feature inventory with the product and adopter boundary tracked in #1610.

Suggested capability level

The resulting inventory should be closer to:

governed repository command execution and audit
isolated agent execution
role and workflow selection
durable reservation, dispatch, and recovery
read-only supervision and machine-readable run state
issue-to-branch, PR, and landing workflows
authority-free context handoff
ephemeral container lifecycle and credential boundaries
provider compatibility, linked rather than duplicated

This list is illustrative. Keep only capabilities that are significant and shipped.

Acceptance

docs/FEATURES.md contains no harness, forge, tracker, container-runtime, or operator-product brand names.
Provider support remains explicit and accurate in docs/compat-surface.md.
The feature inventory contains no diagnostics, bugfix ledger entries, narrow implementation details, or workflow-internal state names presented as major features.
Removed or scheduled-for-removal surfaces are absent.
Every retained bullet describes a durable user-visible capability.
Major features with dedicated walkthroughs link to those walkthroughs.
Documentation validation passes.

Non-goals

Hiding real provider limitations.
Claiming adapters are provider-neutral when they are not.
Removing provider-specific compatibility documentation.
Generalizing runtime adapters as part of this documentation issue.
Expanding FEATURES.md into a roadmap or changelog.

## Outcome Make `docs/FEATURES.md` a concise inventory of Ward's major product capabilities. The feature inventory must describe what Ward enables without duplicating provider compatibility, implementation details, diagnostics, bugfixes, or release plumbing. ## Documentation boundary * `docs/FEATURES.md` is brand-neutral and capability-oriented. * `docs/compat-surface.md` is brand-explicit and records the honest provider matrix, partial support, and unsupported providers. * Feature-specific walkthroughs explain behavior and contracts. * Release notes, issues, and source comments carry implementation details and narrow fixes. Provider names may remain in the compatibility matrix and provider-specific walkthroughs. They should not appear in the coarse feature inventory. ## Current problem The current feature inventory mixes major capabilities with: * explicit harness and forge names * provider-specific RPC and issue operations * harness-specific failure buffering * browser restrictions for one harness * launch-intent implementation details * reservation cleanup mechanics * PR repair classification * artifact selectors * release workflow implementation * features already approved for removal That makes Ward appear coupled to specific providers and turns the inventory into a partial changelog. ## Scope * Rewrite `docs/FEATURES.md` around a small set of durable product capabilities. * Describe harness support as typed or guarded harness integration without listing brands. * Describe issue, tracker, forge, and PR operations by capability without naming a provider. * Describe observability and failure handling generically. * Remove implementation-level bullets such as internal state splits, cleanup mechanisms, repair classifiers, and artifact selectors unless they materially define a public capability. * Remove narrow negative implementation facts such as disabling one harness's browser integration. * Replace release workflow mechanics with at most one durable release-distribution capability, if release belongs in the inventory at all. * Keep one clear link to `docs/compat-surface.md` for provider support details. * Review `docs/compat-surface.md` for missing provider truth exposed by removing names from the feature inventory. Do not falsely claim provider neutrality where adapters remain partial. * Coordinate already-approved removals: * #1620 removes autonomous burndown. * #1621 removes the demo image and toy application. * #1622 removes AOS and AOSguard from the shipped product contract. * Align the feature inventory with the product and adopter boundary tracked in #1610. ## Suggested capability level The resulting inventory should be closer to: * governed repository command execution and audit * isolated agent execution * role and workflow selection * durable reservation, dispatch, and recovery * read-only supervision and machine-readable run state * issue-to-branch, PR, and landing workflows * authority-free context handoff * ephemeral container lifecycle and credential boundaries * provider compatibility, linked rather than duplicated This list is illustrative. Keep only capabilities that are significant and shipped. ## Acceptance * `docs/FEATURES.md` contains no harness, forge, tracker, container-runtime, or operator-product brand names. * Provider support remains explicit and accurate in `docs/compat-surface.md`. * The feature inventory contains no diagnostics, bugfix ledger entries, narrow implementation details, or workflow-internal state names presented as major features. * Removed or scheduled-for-removal surfaces are absent. * Every retained bullet describes a durable user-visible capability. * Major features with dedicated walkthroughs link to those walkthroughs. * Documentation validation passes. ## Non-goals * Hiding real provider limitations. * Claiming adapters are provider-neutral when they are not. * Removing provider-specific compatibility documentation. * Generalizing runtime adapters as part of this documentation issue. * Expanding `FEATURES.md` into a roadmap or changelog.

coilyco-ops referenced this issue

2026-07-31 07:25:05 +00:00

Collapse the documentation tree into durable product contracts #1624

coilyco-ops referenced this issue

2026-07-31 07:29:57 +00:00

Audit downstream consumers before removing ward exec/git/audit/repocfg #1248

coilyco-ops referenced this issue

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

meta: release pressure-test run log (cold-read usability sweeps) #428

coilyco-ops referenced this issue

2026-07-31 08:11:57 +00:00

docs: document Ward product and adopter boundary #1610

coilyco-ops referenced this issue

2026-07-31 08:14:17 +00:00

Reposition Ward as the operations layer for unattended coding agents #974

coilyco-ops added the

labels

2026-07-31 08:25:48 +00:00

coilyco-ops referenced this issue

2026-07-31 09:25:31 +00:00

code-fleet-watch: policy findings #1616

coilyco-ops referenced this issue

2026-08-05 09:48:55 +00:00

code-fleet-watch: policy findings #1616

coilyco-ops commented

2026-08-05 10:04:20 +00:00

Author

Member

Decision resolved by Kai on 2026-08-05.

Make docs/FEATURES.md a strict snapshot of capabilities shipped on main in the same commit. Use these seven durable capability areas:

governed repository commands and audit
isolated least-access agent execution
role selection and fixed landing workflows
durable dispatch, capacity, reservation, and restart recovery
read-only supervision, lifecycle status, logs, and cleanup
revision-bound independent verification
authority-free context handoff and brokered collaboration

Rules:

Use at most one short paragraph or a few bullets per capability.
Name Ward commands only when the command is the actual public entrypoint.
Include no provider brands, internal states, narrow fixes, diagnostics, scheduled features, or release-pipeline mechanics.
End with one link to the brand-explicit compatibility matrix.
Keep the product and adopter boundary in README or architecture rather than presenting it as a feature.

Decision resolved by Kai on 2026-08-05. Make docs/FEATURES.md a strict snapshot of capabilities shipped on main in the same commit. Use these seven durable capability areas: * governed repository commands and audit * isolated least-access agent execution * role selection and fixed landing workflows * durable dispatch, capacity, reservation, and restart recovery * read-only supervision, lifecycle status, logs, and cleanup * revision-bound independent verification * authority-free context handoff and brokered collaboration Rules: * Use at most one short paragraph or a few bullets per capability. * Name Ward commands only when the command is the actual public entrypoint. * Include no provider brands, internal states, narrow fixes, diagnostics, scheduled features, or release-pipeline mechanics. * End with one link to the brand-explicit compatibility matrix. * Keep the product and adopter boundary in README or architecture rather than presenting it as a feature.

coilyco-ops referenced this issue from a commit

2026-08-06 00:28:51 +00:00

docs: rewrite the capability inventory

coilyco-ops closed this issue

2026-08-06 00:28:51 +00:00

coilyco-ops commented

2026-08-06 00:28:58 +00:00

Author

Member

Landed on canonical main in d7c56436.

Replaced the implementation-heavy inventory with the seven settled durable capability areas.
Removed all provider brands, diagnostics, release plumbing, internal state names, and scheduled work from the inventory.
Kept provider truth in the existing brand-explicit compatibility matrix.
Documented the shipped exact-revision QA verdict contract in its linked walkthrough.
Passed ward doctor and the complete pre-commit documentation and repository validation suite.

Landed on canonical `main` in `d7c56436`. * Replaced the implementation-heavy inventory with the seven settled durable capability areas. * Removed all provider brands, diagnostics, release plumbing, internal state names, and scheduled work from the inventory. * Kept provider truth in the existing brand-explicit compatibility matrix. * Documented the shipped exact-revision QA verdict contract in its linked walkthrough. * Passed `ward doctor` and the complete pre-commit documentation and repository validation suite.

Rows
Columns

Rewrite FEATURES.md as a brand-neutral capability inventory #1623

Outcome

Documentation boundary

Current problem

Scope

Suggested capability level

Acceptance

Non-goals