ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
1746eb5570
TenantAtlas/specs/201-enforcement-review-guardrails/tasks.md

14 KiB
Raw Blame History

Tasks: Enforcement & Review Guardrails

Input: Design documents from /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/201-enforcement-review-guardrails/
Prerequisites: plan.md (required), spec.md (required), research.md, data-model.md, contracts/, quickstart.md

Tests: Not required. This feature is docs and workflow only, so validation is by representative low-impact and guarded-case walkthroughs, cross-artifact consistency review, and recording the outcomes in the active spec artifacts.

Organization: Tasks are grouped by user story so each story can be implemented and validated independently where possible.

Phase 1: Setup (Shared Context)

Purpose: Freeze the real workflow surfaces and the exact implementation scope before editing templates or guidance.

  • T001 Audit specs/201-enforcement-review-guardrails/spec.md, specs/201-enforcement-review-guardrails/plan.md, specs/201-enforcement-review-guardrails/research.md, specs/201-enforcement-review-guardrails/data-model.md, specs/201-enforcement-review-guardrails/quickstart.md, .specify/templates/spec-template.md, .specify/templates/plan-template.md, .specify/templates/tasks-template.md, .specify/templates/checklist-template.md, .specify/README.md, and docs/ui/operator-ux-surface-standards.md against Specs 196 through 200 to confirm the exact guardrail gaps and optional wording-alignment scope

Phase 2: Foundational (Blocking Stabilization Prerequisites)

Purpose: Reconcile and stabilize the shared guardrail vocabulary and structured contracts that every later template and checklist update depends on.

Critical: No user story work should begin until this phase is complete.

  • T002 Reconcile and confirm specs/201-enforcement-review-guardrails/data-model.md as the stable source for rule mappings, reviewer question set, repository signals, test-guardrail profiles, exception workflow, workflow touchpoints, validation scenarios, and the active feature PR close-out entry that all later workflow surfaces must reuse
  • T003 [P] Reconcile specs/201-enforcement-review-guardrails/contracts/guardrail-governance.schema.json with the confirmed rule mappings, review outcome classes, repository-signal handling modes, test-guardrail profiles, validation scenarios, and the active feature PR close-out entry from specs/201-enforcement-review-guardrails/data-model.md
  • T004 [P] Reconcile specs/201-enforcement-review-guardrails/contracts/guardrail-governance.logical.openapi.yaml with the confirmed logical flows for spec-impact validation, review classification, repository-signal assessment, test-guardrail resolution, exception assessment, and the active feature PR close-out entry
  • T005 [P] Refine specs/201-enforcement-review-guardrails/quickstart.md with the canonical low-impact path, the representative fake-native/shared-family/state-layer/exception walkthroughs, the timing and duplicate-prompt validation expectations, and the explicit first-pass deferral list for grep/lint/CI hardening

Checkpoint: The shared vocabulary, contracts, and validation scenarios are stable enough for story-specific workflow changes.

Phase 3: User Story 1 - Reviewers Classify Drift Early (Priority: P1) 🎯 MVP

Goal: Give reviewers one fixed checklist and outcome model that catches fake-native drift, host drift, hidden exceptions, and shell/page/detail confusion before merge.

Independent Test: Apply the finished reviewer workflow to the representative cases from Specs 196 through 200 and confirm the review can reach the intended guardrail outcome without inventing new categories.

Implementation for User Story 1

  • T006 [P] [US1] Update .specify/templates/checklist-template.md with the fixed UI/surface guardrail questions, the review outcome classes (blocker, strong-warning, documentation-required-exception, acceptable-special-case), and the explicit workflow outcomes (keep, split, document-in-feature, follow-up-spec, reject-or-split)
  • T007 [P] [US1] Update .specify/README.md as the reviewer entry point for applying the canonical UI/surface guardrail checklist, handling low-impact N/A cases, and interpreting the workflow outcomes consistently
  • T008 [US1] Validate the reviewer workflow against specs/196-hard-filament-nativity-cleanup/spec.md, specs/197-shared-detail-contract/spec.md, specs/198-monitoring-page-state/spec.md, specs/199-global-context-shell-contract/spec.md, and specs/200-filament-surface-rules/spec.md, then record the reached review outcome classes, handling modes, elapsed guarded-review time, duplicate-question notes, and any wording refinements in specs/201-enforcement-review-guardrails/spec.md and specs/201-enforcement-review-guardrails/quickstart.md

Checkpoint: Reviewers can classify the target drift cases early and consistently.

Phase 4: User Story 2 - Authors Declare Native Vs Custom Up Front (Priority: P1)

Goal: Make authors capture native/custom classification, state-layer ownership, shared-family relevance, and exception need during spec and plan authoring.

Independent Test: Draft a low-impact docs-only path and a UI/surface-changing path through the updated spec and plan prompts and confirm the required classifications are explicit without adding a second workflow.

Implementation for User Story 2

  • T009 [P] [US2] Update .specify/templates/spec-template.md so UI/surface-changing specs explicitly capture native/custom classification, state-layer ownership, shared-family relevance, exception need, and low-impact N/A handling when no operator-facing surface changes exist
  • T010 [P] [US2] Update .specify/templates/plan-template.md so planning artifacts explicitly capture guardrail handling modes, repository-signal treatment, required test depth for special surface classes, and the active feature PR close-out entry for exceptions and smoke coverage
  • T011 [US2] Validate the authoring flow using a low-impact docs-only scenario limited to .specify/templates/checklist-template.md and .specify/README.md plus a surface-changing scenario grounded in specs/200-filament-surface-rules/spec.md, then record the authoring outcome, low-impact completion time, duplicate-prompt notes, and any prompt refinements in specs/201-enforcement-review-guardrails/spec.md and specs/201-enforcement-review-guardrails/quickstart.md

Checkpoint: Authors can classify surface risk and exception need before implementation begins.

Phase 5: User Story 3 - Maintainers Get Proportionate Signals And Test Triggers (Priority: P2)

Goal: Make likely drift visible through repository signals and define which surface classes require special tests or smoke checks without overhardening standard native surfaces.

Independent Test: Map the representative drift classes and surface classes to the final signal catalog and test-guardrail matrix, then confirm each one has a clear handling mode or required test profile.

Implementation for User Story 3

  • T012 [P] [US3] Update .specify/templates/tasks-template.md so generated task lists carry forward native/custom, state-layer, shared-family, and exception classification into implementation tasks and require repository-signal handling, review classification work, definition-of-done checks, exception documentation, required tests or manual smoke checks, and the active feature PR close-out entry whenever a special surface class is involved
  • T013 [P] [US3] Finalize the repository-signal catalog, test-guardrail matrix, standard-native surface relief rule, and first-pass automation deferrals in specs/201-enforcement-review-guardrails/research.md, specs/201-enforcement-review-guardrails/data-model.md, and specs/201-enforcement-review-guardrails/quickstart.md
  • T014 [US3] Validate signal and test-trigger handling against specs/196-hard-filament-nativity-cleanup/spec.md, specs/197-shared-detail-contract/spec.md, specs/198-monitoring-page-state/spec.md, specs/199-global-context-shell-contract/spec.md, and specs/200-filament-surface-rules/spec.md, then record the final handling-mode matrix, required test profiles, standard-native surface relief rule, active feature PR close-out entry, and any wording refinements in specs/201-enforcement-review-guardrails/spec.md and specs/201-enforcement-review-guardrails/quickstart.md

Checkpoint: Maintainers have one proportionate reference for signals, required tests, and deferred hardening.

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Reconcile the finished workflow surfaces and remove drift between the templates, guidance, and active feature artifacts.

  • T015 [P] Align .specify/templates/spec-template.md, .specify/templates/plan-template.md, .specify/templates/tasks-template.md, .specify/templates/checklist-template.md, .specify/README.md, specs/201-enforcement-review-guardrails/spec.md, and specs/201-enforcement-review-guardrails/quickstart.md so the same guardrail vocabulary and workflow outcomes appear once and without contradictory wording
  • T016 [P] Add a minimal guardrail workflow cross-reference in docs/ui/operator-ux-surface-standards.md only if the finished templates and .specify/README.md still need an explicit pointer from operator-UX standards back to the .specify/ review workflow
  • T017 Run the completion checklist in specs/201-enforcement-review-guardrails/quickstart.md against .specify/templates/spec-template.md, .specify/templates/plan-template.md, .specify/templates/tasks-template.md, .specify/templates/checklist-template.md, .specify/README.md, specs/201-enforcement-review-guardrails/spec.md, and specs/201-enforcement-review-guardrails/plan.md, then record any remaining first-pass automation deferrals, low-impact completion time, representative guarded-review completion time, active feature PR close-out entry targeting, and redundant-prompt findings in specs/201-enforcement-review-guardrails/quickstart.md

Dependencies & Execution Order

Phase Dependencies

  • Setup (Phase 1): No dependencies and can start immediately.
  • Foundational (Phase 2): Depends on Setup and blocks all user story work.
  • User Story 1 (Phase 3): Depends on Foundational and delivers the MVP review workflow.
  • User Story 2 (Phase 4): Depends on Foundational and can proceed independently of User Story 1 once the shared guardrail vocabulary is stable.
  • User Story 3 (Phase 5): Depends on Foundational and benefits from the live authoring/review surfaces from User Stories 1 and 2 before final validation closes.
  • Polish (Phase 6): Depends on all desired user stories being complete.

User Story Dependencies

  • User Story 1 (P1): Can begin immediately after Foundational and is the recommended MVP slice.
  • User Story 2 (P1): Can begin immediately after Foundational and delivers an independent authoring workflow improvement.
  • User Story 3 (P2): Can begin after Foundational, but its final validation should run after User Stories 1 and 2 have stabilized the workflow surfaces it references.

Within Each User Story

  • Feature-local guardrail vocabulary and contracts must be stable before template wording is finalized.
  • Template changes should land before story-specific validation notes are recorded in spec.md and quickstart.md.
  • Validation walkthroughs should complete before closing the corresponding story.
  • Cross-artifact cleanup should happen only after all targeted workflow surfaces are updated.

Parallel Opportunities

  • T003, T004, and T005 can run in parallel after T002 reconciles the guardrail vocabulary and the active feature PR close-out entry.
  • T006 and T007 can run in parallel because they update different reviewer-facing workflow surfaces.
  • T009 and T010 can run in parallel because they update different authoring surfaces.
  • T012 and T013 can run in parallel once Foundational work is stable because they touch different implementation surfaces.
  • T015 and T016 can run in parallel during Polish because they target different files.

Parallel Example: Foundational Work

# After T002 reconciles the guardrail vocabulary and the active feature PR close-out entry:
Task: "Align specs/201-enforcement-review-guardrails/contracts/guardrail-governance.schema.json"
Task: "Align specs/201-enforcement-review-guardrails/contracts/guardrail-governance.logical.openapi.yaml"
Task: "Update specs/201-enforcement-review-guardrails/quickstart.md"

Parallel Example: User Story 1

# After Foundational is complete:
Task: "Update .specify/templates/checklist-template.md"
Task: "Update .specify/README.md"

Parallel Example: User Story 2

# After Foundational is complete:
Task: "Update .specify/templates/spec-template.md"
Task: "Update .specify/templates/plan-template.md"

Implementation Strategy

MVP First (User Story 1 Only)

  1. Complete Phase 1: Setup.
  2. Complete Phase 2: Foundational.
  3. Complete Phase 3: User Story 1.
  4. Validate the representative reviewer cases before continuing.

Incremental Delivery

  1. Lock the shared guardrail vocabulary and contracts first.
  2. Deliver the reviewer-facing workflow surfaces.
  3. Deliver the authoring prompts for specs and plans.
  4. Deliver the maintainer-facing task and signal/test-trigger surfaces.
  5. Finish with cross-artifact cleanup and quickstart completion review.

Parallel Team Strategy

  1. One contributor can stabilize the feature-local guardrail vocabulary while another prepares the contract and quickstart updates after the foundational mapping is fixed.
  2. Reviewer-facing surfaces in User Story 1 can be updated in parallel once Foundational is done.
  3. Spec and plan template work in User Story 2 can be updated in parallel once the same vocabulary is stable.
  4. Maintainer-facing task-template updates and final signal/test-trigger refinements can run in parallel late in the workflow.

Notes

  • [P] tasks operate on different files or independent workflow surfaces and can run in parallel once dependencies are satisfied.
  • [US1], [US2], and [US3] map tasks directly to the user stories in spec.md.
  • This feature is docs and workflow only, so validation is recorded in the active spec artifacts rather than by running Pest lanes.
  • First-pass repository signals remain report-first and exception-aware; grep/lint/CI hardening stays explicitly deferred unless the implementation proves a smaller workflow surface is insufficient.