# AWP Specification Presentation Standard **Status:** **Binding documentation/design standard** **Date:** 2026-08-20 **Full-spec policy:** [`../plans/AWP-FULL-SPECIFICATION-RATIFICATION.md`](../plans/AWP-FULL-SPECIFICATION-RATIFICATION.md) **Purpose:** Make AWP specifications simultaneously rigorous enough for implementation/agents and clear enough for humans to audit full product intent before it drifts across increments. ## 1. Non-negotiable principle A specification is not successful merely because an AI agent can parse it. > **If a human cannot read, navigate, audit and challenge the specification, the specification has failed.** AWP specs preserve full technical detail while presenting it through a polished human documentation system. ## 2. Dual representation without dual truth Every canonical specification has: ```text .md canonical technical source .html committed human presentation generated from the same source ``` The Markdown source supports diffs, agent work and structured review. The HTML companion is mandatory for human review/navigation and must contain the complete material contract. There are never two independently maintained technical truths. CI must eventually fail when HTML is stale relative to source. ## 3. Full target-state requirement Every canonical spec describes the complete intended target behavior/seam for the product area it governs, even when parts are realized in later increments. Every spec must therefore contain visible sections for: ```text Target State Invariants From Day 1 Increment Realization Current Implementation State Deferred Realization Temporary Dogfood Behavior Decisions / ADRs ``` A future capability may be operationally deferred, but its intended target seam must not be hidden behind `TBD later` when that seam constrains earlier implementation. ## 4. Root human navigation `docs/specs/INDEX.html` is the human entry point for the entire specification system. It must link to every active specification and the governing implementation/specification plans. Each indexed spec exposes: ```text title category status: Draft | In review | Approved | Superseded last meaningful update purpose dependencies / consumed specs first operational increment / deepening increments human HTML link canonical source link related Decisions / ADRs / mockups ``` Navigation supports at least: ```text Architecture ADRs Domains Workflows UI / Pages Schemas / Contracts Research / evidence Browse by increment realization ``` Broken internal spec links are CI failures. ## 5. Human page structure Every rendered HTML spec uses a common shell: ```text AWP Specifications / breadcrumb Title Status + updated date + authority Purpose / orientation At a glance target state key invariants major dependencies first realization increment current implementation status Target State Invariants From Day 1 Increment Realization Current Implementation State Deferred Realization Temporary Dogfood Behavior Table of contents Main technical contract diagrams/tables adjacent to concepts Journeys / operational flows Failure/recovery behavior Acceptance criteria Decisions / ADRs Related specs / mockups Canonical source / history ``` Do not push the actual specification below decorative content. ## 6. Technical completeness rule HTML contains the entire material contract of the canonical source. It may visually reorganize information using: ```text callouts tables diagrams collapsible evidence/rationale status/increment chips cross-links side navigation ``` but may not replace precise technical content with a short summary. A human reviewer must be able to discover every invariant, lifecycle, failure mode, realization boundary and acceptance requirement from HTML. ## 7. Diagrams Use diagrams when relationships or sequence are easier to verify visually than through prose. Expected forms: ```text system/context entity/domain relationship state machine sequence workflow/decision flow data/control flow trust boundary CI/CD lifecycle page/user journey increment realization/timeline ``` Canonical diagram source should be text-reviewable where practical, such as Mermaid or another source-controlled representation. HTML should render diagrams locally/static, preferably inline SVG/assets rather than relying on a third-party service at view time. Diagrams complement exact prose; they never replace invariants. ## 8. Increment Realization presentation Every HTML spec must make delivery timing obvious without implying that later behavior is undefined. Recommended presentation: ```text Target capability Specified now I0 foundation only I1 narrow activation I2 deepening ... I9 later productization ``` The current increment, first operational increment and later deepening points should be visually easy to scan and link to [`../plans/AWP-INCREMENT-REALIZATION-MATRIX.html`](../plans/AWP-INCREMENT-REALIZATION-MATRIX.html). ## 9. UI/page specifications Every user-facing page specification includes: ```text page purpose primary users/jobs entry/exit points complete target information architecture user journeys data shown + source of truth actions + hierarchy permissions/authorization Empty / Loading / Error / Populated / Stale waiting/blocked/failure behavior responsive behavior keyboard/focus/accessibility URL-restorable state async feedback / duplicate-mutation safety linked domain/workflow contracts Increment Realization current vs future visible capability acceptance criteria visual mockups ``` A page spec without journeys, complete material states and target-to-increment mapping is incomplete. ## 10. Mockup authority and replacement Low-fidelity diagrams/wireframes are discovery/reference material. Before implementation of a user-facing state, approved high-fidelity mockups are mandatory. When high-fi is approved: 1. store it in the canonical mockup area; 2. link/embed it from the page's HTML spec; 3. make it the canonical visual reference for that state; 4. replace/remove competing low-fi visual authority from the current presentation; 5. keep historical visuals only as clearly labeled history/reference. Behavioral text remains authoritative where a static image cannot express dynamic/error/permission behavior. ### 10.1 Full-target page composition — no visual vision drift **The first high-fidelity design of a page freezes the page's complete intended target composition, not merely the controls implemented in the current increment.** Incremental implementation may defer functionality. It may not defer where that functionality belongs in the product. Therefore an early high-fi page must show the final intended placement/hierarchy for future material capabilities when their presence affects layout, navigation, spatial balance or user mental model. Use an explicit planned/non-operational treatment such as: ```text Ask Project Manager Planned I3 Decision Log Planned I3 CI control plane Planned I5 Release / Deployment Planned I6 Cluster management Planned I7 ``` Allowed treatments include disabled controls with `Planned I#`, read-only previews, muted destination rows, or a compact planned-capability state. The treatment must make it impossible to mistake the capability for operational behavior. Do **not**: ```text design a deliberately sparse early page implement it let users habituate to it then ask a later implementation agent to discover where future features should fit ``` That is visual/product vision drift. Do: ```text full target page high-fi now -> approved final spatial/interaction hierarchy -> annotate increment availability -> implement only current increment behavior -> activate later capability in its already-designed location ``` A later high-fi pass may refine copy, states, or detail as evidence improves, but moving a material capability to a new structural location requires an explicit design Decision/spec amendment rather than incidental implementation convenience. This rule does not require filling the screen with fake empty dashboards. A future subsystem that has no effect on current page composition can remain absent. The test is whether hiding it now would leave its future placement/hierarchy undecided. ## 11. Mockup coverage High-fi approval is not one happy-path screenshot when materially different states exist. Typical distinct frames: ```text normal populated empty loading error/failure waiting/blocked important modal/drawer/inspector narrow/responsive high-risk confirmation ``` Only materially distinct states require separate frames. ## 12. Whole-product visual coherence Before the first user-facing implementation, full specs and the first relevant page high-fi must already define: ```text product shell navigation model major page relationships shared design system / visual language whole-product information architecture final placement of material future page capabilities ``` Later high-fi can deepen a page, but may not create a new navigation/product model or casually rearrange established capability placement. ## 13. Cross-reference rules References are hyperlinks, not prose scavenger hunts. Bad: ```text See the planning domain spec. ``` Required: ```text See Planning Domain > Decision Participation. ``` with a direct source/HTML anchor. Every primitive referenced by UI/workflow specs links to its defining domain spec. Workflows link to their consumed domains and operated pages. ADR references link directly to the ADR. Increment references link to the realization matrix/plan. ## 14. Stable anchors Generated headings use deterministic anchors. Broadly referenced concepts prefer explicit stable IDs, for example: ```text #planning-participation-mode #decision-participation-class #verification-authority #project-connection-binding #plan-launch #increment-realization ``` Display-copy changes should not unnecessarily break links. ## 15. Spec graph The documentation system exposes relationships such as: ```text defined by consumes depends on constrained by Decision supersedes first realized in expanded in implemented by validated by visualized by ``` This lets a human follow architecture -> domain -> workflow -> UI -> mockup -> increment -> implementation/evidence. ## 16. Status and authority Each spec declares: ```text Draft In review Approved Superseded ``` Approved specs are implementation source of truth for their surface. A superseded spec links to replacement and does not appear as current authority. `Deferred Realization` is **not** a weaker spec status; an Approved target spec may contain behavior whose implementation is scheduled for I6 or I9. ## 17. Human review gate A technically complete specification is not ready until a human can reasonably audit it. The full baseline must pass: ```text technical completeness cross-spec consistency link integrity human readability diagram completeness increment-realization completeness Decision/ADR traceability whole-product IA coherence ``` Before each user-facing implementation increment, add exact high-fi approval for the states being shipped. The high-fi must use the full-target composition rule above. ## 18. Presentation design The spec site should look like a professional product/engineering design system, not raw generated API docs. Required qualities: ```text strong typography hierarchy comfortable prose width wide diagram/table/mockup breakouts persistent desktop section navigation responsive narrow navigation breadcrumbs clear code/invariant blocks subtle status/increment/rationale/evidence callouts print-friendly layout no decorative visual noise ``` Use shared design tokens across all spec pages. ## 19. Search and navigation As the spec set grows, `INDEX.html` supports search/filtering by: ```text title primitive/domain workflow page status keyword increment realization ``` Search should lead to exact specs/sections, not merely filenames. ## 20. Spec-generation pipeline The repository must contain a deterministic renderer that eventually: ```text reads canonical Markdown/spec metadata renders HTML with shared design system renders text-defined diagrams to static assets/SVG embeds/links approved mockups builds INDEX.html navigation/search/realization metadata checks internal links/anchors checks source -> HTML freshness checks required visual assets for implementation-ready UI states ``` The renderer is build tooling, not a second authoring system. ## 21. CI enforcement At minimum verify: ```text all canonical specs render committed HTML matches source no broken internal links no duplicate stable anchors INDEX.html includes every active spec Increment Realization exists and links to the canonical matrix Approved UI states being implemented link required high-fi superseded specs do not appear as current authority ``` A spec-lint rule should validate required section coverage by spec type. ## 22. No hidden early mistakes Important early decisions must be easy to inspect: ```text what was decided why confidence/evidence what depends on it which increments realize it how to change it what becomes stale if changed ``` A decision made in step 1 must not remain buried until step 7 exposes it. ## 23. Implementation gate Before Increment 0 implementation materially begins: ```text full target spec inventory complete all active HTML companions complete cross-links + realization matrix complete Decision/ADR traceability reviewed whole-product IA defined ``` Before any later user-facing state is implemented: ```text target spec already approved increment boundary confirmed required high-fi approved + linked high-fi shows the full target page composition where later capabilities affect placement future non-operational capability is unmistakably labeled with planned increment spec/high-fi consistent remaining unknowns implementation-local ``` This is intentionally stronger than the Overdeck-era process.