ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests 1 Actions 1 Packages Projects 1 Releases Wiki Activity
platform-dev
TenantAtlas/specs/370-global-surface-information-architecture-contract/tasks.md
ahmido c36cb43741 spec: add global surface IA contract (#441) 
This PR introduces the Global Surface Information Architecture Contract, detailing rules for decision-first display, metadata separation, and zero-state suppression across UI surfaces.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #441
2026-06-10 20:25:15 +00:00

6.3 KiB
Raw Permalink Blame History

Tasks: Spec 370 - Global Surface Information Architecture Contract v1

Input: Design documents from specs/370-global-surface-information-architecture-contract/ Prerequisites: spec.md, plan.md, Spec 368 audit artifacts, checklists/requirements.md

Tests: Docs-only package. No Pest/browser lane is required unless a later implementation step changes runtime UI.

Phase 1: Preparation Guardrails

  • T001 Re-read specs/370-global-surface-information-architecture-contract/spec.md, plan.md, tasks.md, and .specify/memory/constitution.md.
  • T002 [P] Confirm the package remains docs-only by checking no runtime paths outside specs/370-global-surface-information-architecture-contract/ are modified.
  • T003 [P] Inspect Spec 368 source inputs in specs/368-platform-ui-signal-to-noise-browser-audit/audit.md, findings.md, recommendations.md, page-scorecard.csv, spec-candidates.md, and artifacts/raw/browser-notes.md.
  • T004 [P] Inspect the Spec 368 screenshot inventory under specs/368-platform-ui-signal-to-noise-browser-audit/artifacts/screenshots/ and keep examples evidence-labeled.
  • T005 Confirm Spec 369 is completed/validated context only and do not edit specs/369-baseline-profile-decision-view/.

Phase 2: Source Evidence Artifacts

  • T006 [P] Review and finalize specs/370-global-surface-information-architecture-contract/artifacts/source-audit-summary.md so each referenced Spec 368 input uses exact verification class labels such as repo-verified, browser-verified, derived from existing implementation, not available, or deferred.
  • T007 [P] Review and finalize specs/370-global-surface-information-architecture-contract/artifacts/validation-report.md with branch, HEAD, dirty/untracked files, source artifact availability, and preparation analysis result.
  • T008 Ensure missing or blocked source evidence is recorded as not available or deferred, never invented.

Phase 3: Global Surface Contract

  • T009 [US1] Review and finalize specs/370-global-surface-information-architecture-contract/artifacts/surface-contract.md with the first-viewport hierarchy: status, reason, impact, primary next action, affected objects, evidence availability, diagnostics second, technical metadata on demand.
  • T010 [US1] Ensure the contract separates Header, Main Content, Sidebar/Aside, Technical Details, and Evidence Area responsibilities.
  • T011 [US1] Ensure the contract defines zero-metric suppression and duplicate-truth controls without requiring a runtime component or static guard.
  • T012 [US1] Ensure the contract defines verification classes and requires future facts to use them.

Phase 4: Surface, Audience, And Scope Matrix

  • T013 [US1] Review and finalize specs/370-global-surface-information-architecture-contract/artifacts/surface-type-matrix.md with all required Spec 370 IA review classes from the spec, explicitly stating they are not runtime ActionSurfaceType values or replacements for canonical UI standards.
  • T014 [US2] Confirm each audience type in the matrix states decision need, forbidden default burden, allowed technical depth, evidence expectation, diagnostics expectation, and action model.
  • T015 [US1] Confirm each scope type states default scope treatment and raw ID placement rules.
  • T016 [US3] Confirm diagnostic and system surfaces are allowed more technical depth while still requiring impact and next action.

Phase 5: Bloat, Copy, And Checklist Artifacts

  • T017 [US1] Review and finalize specs/370-global-surface-information-architecture-contract/artifacts/ui-bloat-patterns.md with Spec 368-derived patterns and prevention rules.
  • T018 [US2] Review and finalize specs/370-global-surface-information-architecture-contract/artifacts/copy-and-terminology-rules.md with provider-neutral, customer-safe, and operator-action-oriented language rules.
  • T019 [US1] Review and finalize specs/370-global-surface-information-architecture-contract/artifacts/page-assessment-checklist.md so future specs can assess pages before implementation.
  • T020 [US1] Ensure the page assessment checklist ends with one review outcome and one workflow outcome.

Phase 6: Follow-up Boundary

  • T021 Review and finalize specs/370-global-surface-information-architecture-contract/artifacts/follow-up-spec-map.md.
  • T022 Confirm page-level runtime refactors, browser fixture repair, screenshot refreshes, target mock/examples per archetype, static guards, and docs/product publication remain follow-up candidates and are not hidden inside Spec 370.
  • T023 Confirm future automation guard work requires a separate spec after at least one additional consuming UI productization spec validates the contract.

Phase 7: Review, Analysis, And Validation

  • T024 Run ./.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks.
  • T025 Run a read-only preparation analysis across spec.md, plan.md, and tasks.md using the repo's speckit-analyze guidance.
  • T026 Fix only Spec Kit preparation artifacts if the preparation analysis finds bounded inconsistencies.
  • T027 Run git diff --check.
  • T028 Record final readiness, no-runtime-impact, branch name, and any remaining non-blocking question in artifacts/validation-report.md only after T024-T027 complete.
  • T029 Confirm no application/runtime implementation was performed.

Test Governance Checklist

  • Lane assignment is named and is the narrowest sufficient proof for the changed behavior. Docs-only/manual review is sufficient because no runtime behavior changes.
  • New or changed tests stay in the smallest honest family, and any heavy-governance or browser addition is explicit. No tests are added.
  • Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default; any widening is isolated or documented. No helpers or fixtures are added.
  • Planned validation commands cover the change without pulling in unrelated lane cost. check-prerequisites, read-only analysis, and git diff --check cover the prep package.
  • The declared surface test profile or standard-native-filament relief is explicit. N/A - no reachable UI surface changes.
  • Any material budget, baseline, trend, or escalation note is recorded in the active spec or PR. None.