Collapse the documentation tree into durable product contracts #1624

New issue

Closed

opened 2026-07-31 07:25:05 +00:00 by coilyco-ops · 3 comments

coilyco-ops commented

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

Member

Outcome

Reduce Ward's documentation tree from an accumulated release-era archive into a coherent set of durable product contracts.

Every retained page should have a distinct reader purpose, describe a current supported surface, be discoverable from the documentation structure, and agree with the shipped code. Historical incidents, link-preservation anchors, provider-specific residue, and fragments that belong inside a larger contract should not remain standalone pages.

Current evidence

The current tree contains 120 Markdown pages.

The docs index exposes only about 50 pages.
32 pages have no inbound documentation reference.
26 pages lack doc_goal front matter.
Several 10-to-20-line pages exist primarily to preserve an old heading or link.
Four release-run pages preserve point-in-time CI incidents as product documentation.
Multiple subsystems are split across overlapping pages with no canonical contract.
Several pages describe features already approved for removal.
Some pages make claims that source does not support. For example, dispatch health implements native desktop notification, while its page presents SigNoz, Telegram, and ntfy channels as though Ward ships them.
The generated agent flag page claims to cover every command while its generator explicitly suppresses pr status, pr merge, and pr rerun.

Ordering and dependencies

Perform the approved product removals before polishing their documentation:

#1620 removes autonomous burndown and its director-loop documentation.
#1621 removes the demo image, toy application, and their walkthroughs.
#1622 removes AOS and AOSguard from Ward's shipped contract.
#1623 rewrites docs/FEATURES.md as a brand-neutral capability inventory.
#1495 removes tailnet and Tailscale knowledge.
#1255 removes the in-container review panel while retaining independent QA dispatch through the broker.

Do not remove ward exec, ward git, or ward audit through this cleanup. The v1 product boundary retains governed repository command execution and audit as core capabilities. #1248 is closed because that removal direction was declined.

Delete historical and trivial pages

Delete point-in-time incident records from product documentation:

docs/promote-run-2491.md
docs/release-run-2495.md
docs/release-run-2497.md
docs/release-run-2501.md

Delete or absorb anchors that do not carry a distinct durable contract, including:

docs/features-release-tooling.md
docs/release-notes.md
docs/workflow-mirror.md
docs/director-startup-triage.md
docs/drain-timing.md
docs/fleet-local.md
docs/github-token.md
docs/hook.md
docs/agent-stale-reservation-cleanup.md
docs/terminology-inventory.md
docs/terminology-analogies.md

Preserve any still-useful content by moving it into the owning durable page. Do not keep forwarding stubs solely for old internal links. Fix inbound links at their sources.

Consolidate overlapping document families

Create one canonical contract for each family, then delete the fragments:

Harnesses - fold the Claude, Codex, Goose, and OpenCode pages into agent-harnesses.md. Provider-specific details belong in compat-surface.md when they are compatibility facts.
Roles - consolidate engineer, QA, roles, and subcommand prose. Retain the generated roster only if it remains an independently useful generated reference.
Lifecycle and preflight - combine preflight, trust, wrong-repository, frontload, gate, and check-placement material into a coherent lifecycle contract.
Agent operations - combine list, logs, stop, and reap fragments into agent-ops.md.
Broker and authority - combine broker, dispatch-broker, surface, and security material into one least-authority broker contract plus one recovery page where needed.
Reservations - combine reservation behavior, cache behavior, and supported cleanup into one page.
Container lifecycle - absorb environment, lifecycle-log, multi-repository, reaping, skill-surface, and catalog fragments into the container contract, lifecycle, staging, and substrate pages.
Observability - absorb log-schema.md into agent-observability.md.
Core verbs - absorb git-clone.md into git-verbs.md and verb-fallback.md into exec-verb.md.
Terminology - keep one concise terminology page containing the actual object model and necessary non-equivalences.
Configuration - replace config-discovery.md, config-source.md, config-migration.md, agent-config-overrides.md, and fleet-local.md with one exact source, discovery, precedence, and migration contract.
Release - consolidate release.md and release-binaries.md into one maintainer release contract. Keep end-user installation material in README.

Complete or correct retained pages

ward-yaml.md must provide the actual supported schema, value types, defaults, validation behavior, and realistic examples sufficient to author a configuration without reading source.
first-run.md must provide one tested end-to-end path with exact repository resolution, expected output, and an explicit no-mutation contract for dry run.
doctor.md must document prerequisites, configuration inputs, checks, failure meanings, and remedies.
architecture.md must describe Ward itself, with a consistent component count and clear data, authority, and execution boundaries.
compat-surface.md must remain brand-explicit and agree with the adapters actually shipped.
troubleshooting.md must become a symptom-to-evidence-to-remedy guide using supported Ward surfaces. Remove incident links and external product recovery instructions.
agent-dispatch-health.md must distinguish Ward-owned desktop notification from externally configured alert consumers.
agent-flags.md must either include every command promised by its doc_goal or narrow that goal to the deliberately rendered subset.
PR workflow pages must remain source-aligned and should be consolidated where the status-object split no longer helps readers.

Product decisions exposed by the audit

This documentation issue does not silently remove product code. File or link focused implementation issues for each accepted removal, then delete its documentation with the implementation:

Remove verification-fixture mode. It is a bespoke public configuration and flag surface coupled to the burndown path removed by #1620. Normal disposable repositories and retained direct dispatch primitives should provide verification.
Remove the Claude-specific tool-failure buffer and its ~/.cache/agentic-os output.
Remove Ward-owned Forgejo-derived substrate catalog generation while retaining the provider-neutral substrate and multi-repository contract.
Decide whether the optional Sentry/GlitchTip panic reporter belongs in the core binary. If it remains, fold its behavior into an observability or operator contract rather than preserving a tiny standalone page.
Close or supersede #1533 because consuming an AOS substrate primitive conflicts with the newer AOS-opacity decision in #1622.

FEATURES alignment

Coordinate with #1623 so the resulting feature inventory contains durable, brand-neutral callouts for significant retained behavior:

least-authority brokered dispatch with durable IDs and restart recovery
human-feedback acknowledgement before close, reopen, or merge
guarded PR and CI status, wait, logs, landing, and recovery
rescue artifacts and explicit recovery after failed landing or forge outages
secret-free redacted run artifacts and structured observability
reservation idempotency, launch-intent tracking, capacity, and backpressure

Do not promote generated references, provider hooks, incident tooling, diagnostics, internal state names, review panels, verification fixtures, or release workflow mechanics into product features.

Acceptance

Every retained page is reachable from docs/README.md, another canonical page, or a clearly documented generated-reference entrypoint.
No retained standalone page exists only to preserve an old link, heading, issue note, or release incident.
Each subsystem has one obvious canonical contract rather than a cluster of overlapping fragments.
Every hand-authored retained page has a truthful doc_goal at the correct altitude.
Claims about commands, flags, integrations, defaults, providers, and authority boundaries are verified against current source.
Removed product surfaces have no remaining walkthrough, index entry, feature bullet, or terminology residue.
docs/FEATURES.md, README, AGENTS, docs/README.md, compatibility documentation, and feature walkthroughs agree.
Documentation validation and repository tests pass.
The final tree is materially smaller because concepts were consolidated or removed, not because useful detail was discarded.

Non-goals

Preserving obsolete internal links through empty compatibility pages.
Turning docs/FEATURES.md into a changelog.
Hiding provider limitations from compat-surface.md.
Removing retained product behavior solely to reduce the page count.
Rewriting documentation for a feature whose approved removal has not landed.

## Outcome Reduce Ward's documentation tree from an accumulated release-era archive into a coherent set of durable product contracts. Every retained page should have a distinct reader purpose, describe a current supported surface, be discoverable from the documentation structure, and agree with the shipped code. Historical incidents, link-preservation anchors, provider-specific residue, and fragments that belong inside a larger contract should not remain standalone pages. ## Current evidence The current tree contains 120 Markdown pages. * The docs index exposes only about 50 pages. * 32 pages have no inbound documentation reference. * 26 pages lack `doc_goal` front matter. * Several 10-to-20-line pages exist primarily to preserve an old heading or link. * Four release-run pages preserve point-in-time CI incidents as product documentation. * Multiple subsystems are split across overlapping pages with no canonical contract. * Several pages describe features already approved for removal. * Some pages make claims that source does not support. For example, dispatch health implements native desktop notification, while its page presents SigNoz, Telegram, and ntfy channels as though Ward ships them. * The generated agent flag page claims to cover every command while its generator explicitly suppresses `pr status`, `pr merge`, and `pr rerun`. ## Ordering and dependencies Perform the approved product removals before polishing their documentation: * #1620 removes autonomous burndown and its director-loop documentation. * #1621 removes the demo image, toy application, and their walkthroughs. * #1622 removes AOS and AOSguard from Ward's shipped contract. * #1623 rewrites `docs/FEATURES.md` as a brand-neutral capability inventory. * #1495 removes tailnet and Tailscale knowledge. * #1255 removes the in-container review panel while retaining independent QA dispatch through the broker. Do not remove `ward exec`, `ward git`, or `ward audit` through this cleanup. The v1 product boundary retains governed repository command execution and audit as core capabilities. #1248 is closed because that removal direction was declined. ## Delete historical and trivial pages Delete point-in-time incident records from product documentation: * `docs/promote-run-2491.md` * `docs/release-run-2495.md` * `docs/release-run-2497.md` * `docs/release-run-2501.md` Delete or absorb anchors that do not carry a distinct durable contract, including: * `docs/features-release-tooling.md` * `docs/release-notes.md` * `docs/workflow-mirror.md` * `docs/director-startup-triage.md` * `docs/drain-timing.md` * `docs/fleet-local.md` * `docs/github-token.md` * `docs/hook.md` * `docs/agent-stale-reservation-cleanup.md` * `docs/terminology-inventory.md` * `docs/terminology-analogies.md` Preserve any still-useful content by moving it into the owning durable page. Do not keep forwarding stubs solely for old internal links. Fix inbound links at their sources. ## Consolidate overlapping document families Create one canonical contract for each family, then delete the fragments: * Harnesses - fold the Claude, Codex, Goose, and OpenCode pages into `agent-harnesses.md`. Provider-specific details belong in `compat-surface.md` when they are compatibility facts. * Roles - consolidate engineer, QA, roles, and subcommand prose. Retain the generated roster only if it remains an independently useful generated reference. * Lifecycle and preflight - combine preflight, trust, wrong-repository, frontload, gate, and check-placement material into a coherent lifecycle contract. * Agent operations - combine list, logs, stop, and reap fragments into `agent-ops.md`. * Broker and authority - combine broker, dispatch-broker, surface, and security material into one least-authority broker contract plus one recovery page where needed. * Reservations - combine reservation behavior, cache behavior, and supported cleanup into one page. * Container lifecycle - absorb environment, lifecycle-log, multi-repository, reaping, skill-surface, and catalog fragments into the container contract, lifecycle, staging, and substrate pages. * Observability - absorb `log-schema.md` into `agent-observability.md`. * Core verbs - absorb `git-clone.md` into `git-verbs.md` and `verb-fallback.md` into `exec-verb.md`. * Terminology - keep one concise terminology page containing the actual object model and necessary non-equivalences. * Configuration - replace `config-discovery.md`, `config-source.md`, `config-migration.md`, `agent-config-overrides.md`, and `fleet-local.md` with one exact source, discovery, precedence, and migration contract. * Release - consolidate `release.md` and `release-binaries.md` into one maintainer release contract. Keep end-user installation material in README. ## Complete or correct retained pages * `ward-yaml.md` must provide the actual supported schema, value types, defaults, validation behavior, and realistic examples sufficient to author a configuration without reading source. * `first-run.md` must provide one tested end-to-end path with exact repository resolution, expected output, and an explicit no-mutation contract for dry run. * `doctor.md` must document prerequisites, configuration inputs, checks, failure meanings, and remedies. * `architecture.md` must describe Ward itself, with a consistent component count and clear data, authority, and execution boundaries. * `compat-surface.md` must remain brand-explicit and agree with the adapters actually shipped. * `troubleshooting.md` must become a symptom-to-evidence-to-remedy guide using supported Ward surfaces. Remove incident links and external product recovery instructions. * `agent-dispatch-health.md` must distinguish Ward-owned desktop notification from externally configured alert consumers. * `agent-flags.md` must either include every command promised by its `doc_goal` or narrow that goal to the deliberately rendered subset. * PR workflow pages must remain source-aligned and should be consolidated where the status-object split no longer helps readers. ## Product decisions exposed by the audit This documentation issue does not silently remove product code. File or link focused implementation issues for each accepted removal, then delete its documentation with the implementation: * Remove verification-fixture mode. It is a bespoke public configuration and flag surface coupled to the burndown path removed by #1620. Normal disposable repositories and retained direct dispatch primitives should provide verification. * Remove the Claude-specific tool-failure buffer and its `~/.cache/agentic-os` output. * Remove Ward-owned Forgejo-derived substrate catalog generation while retaining the provider-neutral substrate and multi-repository contract. * Decide whether the optional Sentry/GlitchTip panic reporter belongs in the core binary. If it remains, fold its behavior into an observability or operator contract rather than preserving a tiny standalone page. * Close or supersede #1533 because consuming an AOS substrate primitive conflicts with the newer AOS-opacity decision in #1622. ## FEATURES alignment Coordinate with #1623 so the resulting feature inventory contains durable, brand-neutral callouts for significant retained behavior: * least-authority brokered dispatch with durable IDs and restart recovery * human-feedback acknowledgement before close, reopen, or merge * guarded PR and CI status, wait, logs, landing, and recovery * rescue artifacts and explicit recovery after failed landing or forge outages * secret-free redacted run artifacts and structured observability * reservation idempotency, launch-intent tracking, capacity, and backpressure Do not promote generated references, provider hooks, incident tooling, diagnostics, internal state names, review panels, verification fixtures, or release workflow mechanics into product features. ## Acceptance * Every retained page is reachable from `docs/README.md`, another canonical page, or a clearly documented generated-reference entrypoint. * No retained standalone page exists only to preserve an old link, heading, issue note, or release incident. * Each subsystem has one obvious canonical contract rather than a cluster of overlapping fragments. * Every hand-authored retained page has a truthful `doc_goal` at the correct altitude. * Claims about commands, flags, integrations, defaults, providers, and authority boundaries are verified against current source. * Removed product surfaces have no remaining walkthrough, index entry, feature bullet, or terminology residue. * `docs/FEATURES.md`, README, AGENTS, `docs/README.md`, compatibility documentation, and feature walkthroughs agree. * Documentation validation and repository tests pass. * The final tree is materially smaller because concepts were consolidated or removed, not because useful detail was discarded. ## Non-goals * Preserving obsolete internal links through empty compatibility pages. * Turning `docs/FEATURES.md` into a changelog. * Hiding provider limitations from `compat-surface.md`. * Removing retained product behavior solely to reduce the page count. * Rewriting documentation for a feature whose approved removal has not landed.

Rows
Columns