206 lines
12 KiB
Markdown
206 lines
12 KiB
Markdown
# Tasks: Website Information Architecture / Core Pages
|
||
|
||
**Input**: Design documents from `/specs/215-website-core-pages/`
|
||
**Prerequisites**: `plan.md`, `spec.md`, `research.md`, `data-model.md`, `quickstart.md`, `contracts/public-site-ia.openapi.yaml`
|
||
|
||
**Tests**: Browser smoke coverage and the root website build proof are required for this runtime-changing website feature.
|
||
|
||
## Test Governance Checklist
|
||
|
||
- [X] Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
|
||
- [X] New or changed tests stay in the smallest honest family, and any browser coverage addition remains explicit.
|
||
- [X] Shared helpers and context defaults stay cheap by default; no backend, auth, or fixture-heavy setup is introduced.
|
||
- [X] Planned validation commands cover the website IA change without pulling in unrelated platform lane cost.
|
||
- [X] Any runtime-cost or escalation note stays documented in this feature rather than being deferred implicitly.
|
||
- [X] Explicit governance outcome is recorded as `document-in-feature` for this feature-local fast-feedback validation scope.
|
||
|
||
## Phase 1: Setup (Shared Infrastructure)
|
||
|
||
**Purpose**: Prepare the canonical website IA types, metadata hooks, and smoke-test scaffolding that all user stories depend on.
|
||
|
||
- [X] T001 Update the expanded route and surface taxonomy in `apps/website/src/types/site.ts`
|
||
- [X] T002 [P] Rebuild the core route registry, navigation metadata, footer group seeds, and conversion-route metadata in `apps/website/src/lib/site.ts`
|
||
- [X] T003 [P] Extend route-topology, hidden-surface, and core-navigation smoke helpers in `apps/website/tests/smoke/smoke-helpers.ts`
|
||
|
||
---
|
||
|
||
## Phase 2: Foundational (Blocking Prerequisites)
|
||
|
||
**Purpose**: Create the shared SEO, shell, and publication scaffolding that must exist before any individual story can be completed.
|
||
|
||
**⚠️ CRITICAL**: No user story work should begin until this phase is complete.
|
||
|
||
- [X] T004 Prepare canonical URL and sitemap scaffolding for core and retained secondary routes in `apps/website/src/lib/seo.ts` and `apps/website/src/pages/sitemap.xml.ts`
|
||
- [X] T005 [P] Prepare shared shell support for new core and retained secondary page roles in `apps/website/src/layouts/BaseLayout.astro` and `apps/website/src/components/layout/PageShell.astro`
|
||
- [X] T006 [P] Wire optional `Resources` gating and keep the unpublished `articles` collection out of the public IA in `apps/website/src/content.config.ts` and `apps/website/src/lib/site.ts`
|
||
|
||
**Checkpoint**: The canonical core-route skeleton exists, and user-story work can proceed independently on top of it.
|
||
|
||
---
|
||
|
||
## Phase 3: User Story 1 - Understand the Product and Next Step Quickly (Priority: P1) 🎯 MVP
|
||
|
||
**Goal**: Make the first visitor journey obvious by centering Product, Trust, Changelog, and Contact in the header and core pages.
|
||
|
||
**Independent Test**: A first-time visitor can use `/` and `/product` to discover Product, Trust, Changelog, and Contact within two clicks, without seeing placeholder or deferred top-level routes.
|
||
|
||
### Tests for User Story 1
|
||
|
||
- [X] T007 [P] [US1] Update first-journey smoke coverage for home/product navigation, CTA hierarchy, and core-route reachability in `apps/website/tests/smoke/home-product.spec.ts`
|
||
|
||
### Implementation for User Story 1
|
||
|
||
- [X] T008 [P] [US1] Rebuild primary navigation and header CTA behavior around Product, Trust, Changelog, and Contact in `apps/website/src/lib/site.ts`, `apps/website/src/components/layout/Navbar.astro`, and `apps/website/src/components/layout/PageShell.astro`
|
||
- [X] T009 [P] [US1] Refocus the home and product content modules on product understanding, buyer outcomes, and the next-step path in `apps/website/src/content/pages/home.ts` and `apps/website/src/content/pages/product.ts`
|
||
- [X] T010 [US1] Apply the core first-visit journey to `apps/website/src/content/pages/contact.ts`, `apps/website/src/pages/index.astro`, `apps/website/src/pages/product.astro`, and `apps/website/src/pages/contact.astro`
|
||
|
||
**Checkpoint**: Home and Product now deliver the MVP first-visitor journey with one clear next step.
|
||
|
||
---
|
||
|
||
## Phase 4: User Story 2 - Validate Trust and Technical Seriousness (Priority: P1)
|
||
|
||
**Goal**: Make `/trust` the canonical credibility surface and keep legal/trust discoverability coherent and explicit.
|
||
|
||
**Independent Test**: A technical evaluator can open `/trust`, confirm the presence of trust posture and bounded claims, reach Privacy and Imprint from the footer, and see the legacy `/security-trust` path resolve to the canonical Trust surface.
|
||
|
||
### Tests for User Story 2
|
||
|
||
- [X] T011 [P] [US2] Update trust/legal smoke coverage for the canonical Trust route, `/trust -> /contact` reachability, footer legal visibility, and the legacy Trust redirect in `apps/website/tests/smoke/solutions-trust-integrations.spec.ts` and `apps/website/tests/smoke/contact-legal.spec.ts`
|
||
|
||
### Implementation for User Story 2
|
||
|
||
- [X] T012 [P] [US2] Implement the canonical Trust surface with bounded trust-claim content in `apps/website/src/content/pages/trust.ts` and `apps/website/src/pages/trust.astro`
|
||
- [X] T013 [P] [US2] Rebuild trust/legal footer groups around Trust, Privacy, Imprint, Terms, and Contact in `apps/website/src/lib/site.ts` and `apps/website/src/components/layout/Footer.astro`
|
||
- [X] T014 [US2] Align the retained secondary legal surfaces and Trust compatibility path to the new Trust contract in `apps/website/src/content/pages/legal.ts`, `apps/website/src/content/pages/privacy.ts`, `apps/website/src/content/pages/imprint.ts`, `apps/website/src/pages/legal.astro`, `apps/website/src/pages/privacy.astro`, `apps/website/src/pages/imprint.astro`, `apps/website/src/pages/terms.astro`, and `apps/website/src/pages/security-trust.astro`
|
||
|
||
**Checkpoint**: Trust and legal discoverability are now canonical, explicit, and compatibility-safe.
|
||
|
||
---
|
||
|
||
## Phase 5: User Story 3 - See Visible Product Progress (Priority: P2)
|
||
|
||
**Goal**: Publish a real Changelog surface and keep optional or deferred surfaces from inflating the initial IA.
|
||
|
||
**Independent Test**: A returning visitor can open `/changelog`, see dated updates, and confirm that unpublished `Resources` and editorial `articles` content are not promoted while non-core legacy routes no longer dominate the IA.
|
||
|
||
### Tests for User Story 3
|
||
|
||
- [X] T015 [P] [US3] Add changelog and optional-surface smoke coverage for dated updates, `/changelog -> /contact` reachability, hidden `Resources`, hidden editorial `articles`, and footer content gating in `apps/website/tests/smoke/changelog-core-ia.spec.ts`
|
||
|
||
### Implementation for User Story 3
|
||
|
||
- [X] T016 [P] [US3] Implement the Changelog surface and its initial dated entry in `apps/website/src/content/pages/changelog.ts`, `apps/website/src/pages/changelog.astro`, and `apps/website/src/content/changelog/2026-04-19-initial-core-pages.md`
|
||
- [X] T017 [P] [US3] Gate optional `Resources` discoverability, keep the editorial `articles` collection unpublished, and keep deferred surfaces out of primary navigation in `apps/website/src/lib/site.ts`, `apps/website/src/components/layout/Navbar.astro`, and `apps/website/src/components/layout/Footer.astro`
|
||
- [X] T018 [US3] Reclassify `/legal`, `/terms`, `/solutions`, and `/integrations` as retained secondary surfaces in `apps/website/src/content/pages/legal.ts`, `apps/website/src/pages/legal.astro`, `apps/website/src/content/pages/terms.ts`, `apps/website/src/pages/terms.astro`, `apps/website/src/content/pages/solutions.ts`, `apps/website/src/pages/solutions.astro`, `apps/website/src/content/pages/integrations.ts`, and `apps/website/src/pages/integrations.astro`
|
||
|
||
**Checkpoint**: Returning visitors can see real product progress, and optional/deferred surfaces no longer crowd the initial IA.
|
||
|
||
---
|
||
|
||
## Phase 6: Polish & Cross-Cutting Concerns
|
||
|
||
**Purpose**: Finalize canonical route outputs, record the lane proof, and verify website-working-contract compatibility.
|
||
|
||
- [X] T019 [P] Refresh canonical URL generation and sitemap output for the final core IA in `apps/website/src/lib/seo.ts` and `apps/website/src/pages/sitemap.xml.ts`
|
||
- [X] T020 [P] Record fast-feedback lane validation notes and reviewer proof commands in `specs/215-website-core-pages/plan.md` and `specs/215-website-core-pages/quickstart.md`
|
||
- [X] T021 Run `corepack pnpm build:website` and `corepack pnpm exec playwright test` for the updated website IA contract using `package.json`, `apps/website/package.json`, and `apps/website/playwright.config.ts`
|
||
- [X] T022 Verify website working-contract and static-output invariants in `apps/website/astro.config.mjs`, `package.json`, and `apps/website/package.json`
|
||
|
||
---
|
||
|
||
## Dependencies & Execution Order
|
||
|
||
### Phase Dependencies
|
||
|
||
- Phase 1 starts immediately.
|
||
- Phase 2 depends on Phase 1 and blocks all user stories.
|
||
- Phase 3 depends on Phase 2 only.
|
||
- Phase 4 depends on Phase 2 only.
|
||
- Phase 5 depends on Phase 2 only.
|
||
- Phase 6 depends on the targeted user stories being complete.
|
||
|
||
### User Story Dependencies
|
||
|
||
- US1 is the MVP slice and has no dependency on US2 or US3.
|
||
- US2 has no dependency on US1 or US3, but reuses the shared route and navigation foundation.
|
||
- US3 has no dependency on US1 or US2, but reuses the shared core-route scaffolding and smoke helpers.
|
||
|
||
### Within Each User Story
|
||
|
||
- Write or update the browser smoke coverage first.
|
||
- Update central route or content metadata before finalizing page-route composition.
|
||
- Finish route-level integration before moving to polish or the next story’s cleanup.
|
||
|
||
---
|
||
|
||
## Parallel Opportunities
|
||
|
||
- T002 and T003 can run in parallel after T001.
|
||
- T005 can run in parallel with T006 after T004 starts.
|
||
- In US1, T008 and T009 can run in parallel before T010.
|
||
- In US2, T012 and T013 can run in parallel before T014.
|
||
- In US3, T016 and T017 can run in parallel before T018.
|
||
- In Phase 6, T019 and T020 can run in parallel before T021 and T022.
|
||
|
||
---
|
||
|
||
## Parallel Example: User Story 1
|
||
|
||
```bash
|
||
# Launch first-journey metadata and content work together:
|
||
Task: "T008 [US1] Rebuild primary navigation and header CTA behavior"
|
||
Task: "T009 [US1] Refocus the home and product content modules"
|
||
|
||
# Then finish route-level integration:
|
||
Task: "T010 [US1] Apply the core first-visit journey to the published pages"
|
||
```
|
||
|
||
## Parallel Example: User Story 2
|
||
|
||
```bash
|
||
# Launch Trust and footer/legal work together:
|
||
Task: "T012 [US2] Implement the canonical Trust surface"
|
||
Task: "T013 [US2] Rebuild trust/legal footer groups"
|
||
|
||
# Then align the legal baseline and compatibility path:
|
||
Task: "T014 [US2] Align the legal baseline and compatibility surfaces"
|
||
```
|
||
|
||
## Parallel Example: User Story 3
|
||
|
||
```bash
|
||
# Launch changelog publishing and optional-surface gating together:
|
||
Task: "T016 [US3] Implement the Changelog surface and initial dated entry"
|
||
Task: "T017 [US3] Gate optional Resources discoverability"
|
||
|
||
# Then reclassify the non-core legacy surfaces:
|
||
Task: "T018 [US3] Reclassify the retained secondary surfaces"
|
||
```
|
||
|
||
---
|
||
|
||
## Implementation Strategy
|
||
|
||
### MVP First
|
||
|
||
1. Complete Phase 1: Setup.
|
||
2. Complete Phase 2: Foundational.
|
||
3. Complete Phase 3: User Story 1.
|
||
4. Run `corepack pnpm build:website` and the updated home/product smoke proof.
|
||
5. Demo the MVP on `/`, `/product`, and `/contact` with the new header navigation.
|
||
|
||
### Incremental Delivery
|
||
|
||
1. Setup and Foundational phases establish the canonical core-route contract.
|
||
2. US1 makes the first visitor journey obvious.
|
||
3. US2 makes Trust and legal discoverability canonical.
|
||
4. US3 adds visible progress and optional-surface gating.
|
||
5. Polish refreshes sitemap/canonical output and closes the lane-validation loop.
|
||
|
||
### Suggested MVP Scope
|
||
|
||
- Deliver through **User Story 1** if the smallest initial release is needed.
|
||
- Add **User Story 2** next to make Trust and legal discoverability fully canonical.
|
||
- Finish with **User Story 3** to publish Changelog and tighten optional-surface discipline.
|