TenantAtlas/specs/212-test-authoring-guardrails/plan.md

Implementation Plan: Test Suite Authoring Constitution & Review Guardrails

Branch: 212-test-authoring-guardrails | Date: 2026-04-18 | Spec: /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/212-test-authoring-guardrails/spec.md Input: Feature specification from /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/212-test-authoring-guardrails/spec.md

Summary

Implement Spec 212 by tightening the existing TEST-GOV-001 workflow surfaces in the constitution, SpecKit templates, and contributor-facing repository guidance so new tests must declare lane impact, justify heavy setup, trigger explicit escalation when new cost centers appear, and give reviewers a fast decision-grade checklist without introducing runtime tooling, bots, or a second governance subsystem.

Technical Context

Language/Version: Markdown for repository governance artifacts, JSON Schema plus logical OpenAPI for planning contracts, and Bash-backed SpecKit scripts already present in the repo
Primary Dependencies: .specify/memory/constitution.md, .specify/templates/spec-template.md, .specify/templates/plan-template.md, .specify/templates/tasks-template.md, .specify/templates/checklist-template.md, .specify/README.md, README.md, and the existing Specs 206 through 211 governance vocabulary
Storage: Repository-owned markdown and contract artifacts under .specify/, specs/212-test-authoring-guardrails/, and root documentation files; no product database persistence
Testing: Document and template validation against representative low-impact and higher-cost feature flows, checklist completeness review, and no runtime Pest lane execution because the feature is docs and workflow only
Validation Lanes: N/A
Target Platform: TenantAtlas monorepo with SpecKit-driven specification workflow, repository contributor guidance, and Gitea-backed code review
Project Type: Monorepo with a Laravel platform app and Astro website, but this feature is scoped strictly to repository governance and authoring workflow artifacts
Performance Goals: Keep low-impact feature answers to the new prompts completable in under 1 minute, keep representative review-guardrail application under 3 minutes, and avoid adding any new daily workflow surface beyond the existing constitution, templates, and contributor guidance entry points
Constraints: No new runtime dependencies, no CI bot requirement, no new product routes or persistence, no contradiction with Specs 206 through 211, no speculative governance framework, and no new documentation sprawl when an existing entry point can carry the guidance
Scale/Scope: One constitution section, four SpecKit templates, two contributor-facing guidance surfaces, one review-guardrail surface, one escalation policy set, one contributor guidance pack, and validation against at least two representative spec flows

Filament v5 Implementation Notes

• Livewire v4.0+ compliance: Preserved. This feature only changes repository authoring and review artifacts and does not alter the Filament or Livewire runtime stack.
• Provider registration location: Unchanged. Existing panel providers remain registered in bootstrap/providers.php.
• Global search rule: No globally searchable resources are added or modified.
• Destructive actions: No runtime destructive actions are introduced. Existing confirmation and authorization behavior remain unchanged.
• Asset strategy: No panel or shared assets are added. Existing filament:assets deployment behavior remains unchanged.
• Testing plan: Validate the constitution, template prompts, checklist wording, escalation semantics, and contributor guidance against one docs-only N/A path and one higher-cost governed spec path; no runtime UI, action, or Livewire tests are added by this feature.

Test Governance Check

• Affected validation lanes: N/A
• Narrowest proving command(s): N/A. Validation is document and workflow based rather than runtime-lane based.
• Fixture / helper cost risks: None directly. The feature exists to prevent future hidden helper and fixture cost growth rather than to introduce new shared setup.
• Heavy-family additions or promotions: None. The intended change is earlier disclosure and escalation of heavy-family growth in future work.
• Budget / baseline / trend follow-up: None directly. The feature must stay consistent with current lane, budget, and trend vocabulary without mutating those contracts.
• Why no dedicated follow-up spec is needed: Spec 212 is itself the structural authoring and review guardrail feature. After rollout, routine upkeep should live inside ordinary feature specs unless recurring pain or another structural lane-model change appears.

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

• Inventory-first: PASS. No inventory, backup, or snapshot product truth changes.
• Read/write separation: PASS. This is repository-only governance work with no end-user mutations.
• Graph contract path: PASS. No Microsoft Graph calls or contract-registry changes.
• Deterministic capabilities: PASS. No capability resolver or authorization registry changes.
• RBAC-UX, workspace isolation, tenant isolation: PASS. No runtime routes, policies, or scope behavior change.
• Run observability and Ops-UX: PASS. No OperationRun or monitoring lifecycle changes.
• Data minimization: PASS. The new artifacts are repository-owned prompts and guidance only.
• Test governance (TEST-GOV-001): PASS WITH WORK. The feature intentionally strengthens authoring-time and review-time enforcement of lane choice, fixture-cost disclosure, heavy-family escalation, and runtime-drift documentation.
• Proportionality and bloat control: PASS WITH LIMITS. The implementation may touch several workflow entry points, but it must do so by sharpening existing sections rather than creating a new governance framework, parallel handbook, or automation layer.
• TEST-TRUTH-001: PASS WITH WORK. The added prompts and checklists must stay tied to real lane, cost, and escalation decisions instead of inventing abstract process overhead.
• Filament/UI constitutions: PASS / NOT APPLICABLE. No operator-facing runtime UI, action surfaces, or panels are changed.

Phase 0 Gate Result: PASS

• The feature stays bounded to repository constitution, templates, review prompts, and contributor guidance.
• No new product persistence, Graph seams, runtime routes, or authorization planes are introduced.
• The plan reuses existing TEST-GOV-001 workflow surfaces instead of inventing a second governance mechanism.

Project Structure

Documentation (this feature)

specs/212-test-authoring-guardrails/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   ├── test-authoring-governance.schema.json
│   └── test-authoring-governance.logical.openapi.yaml
└── tasks.md

Source Code (repository root)

.specify/
├── memory/
│   └── constitution.md
├── templates/
│   ├── checklist-template.md
│   ├── plan-template.md
│   ├── spec-template.md
│   └── tasks-template.md
└── README.md
README.md
specs/
└── 212-test-authoring-guardrails/
    ├── spec.md
    └── checklists/requirements.md

Structure Decision: Keep all changes inside the existing constitution, SpecKit templates, and established contributor documentation entry points so the governance model becomes more explicit without creating a separate handbook, reviewer-only subsystem, or new runtime-owned code surface.

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
None	Not applicable	Not applicable

Proportionality Review

• Current operator problem: Contributors can still introduce broad, expensive, or misclassified tests before review, and reviewers still lack one compact, repeatable checklist for catching accidental heavy cost and escalation triggers before merge.
• Existing structure is insufficient because: TEST-GOV-001 and the current templates already mention lane/runtime impact, but they do not yet fully encode authoring-time classification discipline, a stable review checklist, escalation triggers, or lightweight contributor decision guidance.
• Narrowest correct implementation: Tighten the existing constitution, templates, and contributor docs with a small number of mandatory prompts and review questions instead of adding bots, runtime policy engines, or a standalone governance manual.
• Ownership cost created: The repo must maintain a concise shared vocabulary for escalation, authoring prompts, and review guardrails across constitution, template, and contributor docs.
• Alternative intentionally rejected: A new automation bot, PR scoring system, or separate governance handbook, because each would add process surface or drift risk beyond what the current delivery workflow needs.
• Release truth: Current-release repository truth needed to make the test-governance chain from Specs 206 through 211 durable in day-to-day authoring and review.

Phase 0 — Research (complete)

• Output: research.md
• Resolved key decisions:
  • Reuse and sharpen the existing TEST-GOV-001 workflow surfaces instead of creating a new governance subsystem.
  • Keep contributor guidance in existing high-traffic documentation surfaces unless a new file proves necessary for clarity.
  • Model review guardrails as a short question set and explicit escalation outcomes rather than a lengthy rubric or approval board.
  • Treat escalation as a documented authoring and review decision, not a new automatic CI blocker.
  • Validate the workflow with one docs-only N/A path and one higher-cost governed-spec path so both minimal overhead and escalation behavior are proven.
  • Use logical contract artifacts to describe the expected prompt, checklist, and escalation semantics even though the feature adds no transport API, while treating those files as plan-time scaffolding rather than new maintained workflow surfaces.

Phase 1 — Design & Contracts (complete)

• Output: data-model.md formalizes the repository-owned governance objects: constitution rule set, spec and plan prompt blocks, task checklist, review checklist, escalation assessment, contributor guidance pack, and validation scenarios.
• Output: contracts/test-authoring-governance.schema.json defines schema-first planning scaffolding for the governance pack the workflow must express; it is not an additional maintained reviewer-facing surface.
• Output: contracts/test-authoring-governance.logical.openapi.yaml captures logical planning semantics for validating spec and plan impact blocks, evaluating a task checklist, assessing escalation, and serving contributor guidance; it is not an additional maintained reviewer-facing surface.
• Output: quickstart.md provides the implementation order, representative validation flows, and rollout checklist.

Post-design Constitution Re-check

• PASS: No runtime routes, panels, Graph seams, or authorization planes are introduced.
• PASS: The design keeps all new truth repository-owned and documentation-first.
• PASS: The workflow surfaces stay inside existing constitution, template, and contributor entry points rather than creating a new process framework.
• PASS WITH WORK: Review guardrails and escalation wording must remain concise enough that low-impact features can still answer with N/A or none without friction.
• PASS WITH WORK: Any contributor guidance added to README.md or .specify/README.md must avoid duplicating the same rules in multiple long prose blocks that will drift.

Phase 2 — Implementation Planning

tasks.md should cover:

• Auditing the current TEST-GOV-001 constitution text, SpecKit templates, and contributor docs to isolate exactly which authoring-time and review-time gaps remain after Specs 206 through 211.
• Updating .specify/memory/constitution.md with a short, binding test authoring and review guardrail section that makes classification, minimal fixtures, explicit heavy justification, escalation triggers, and expensive-default bans unmistakable.
• Updating .specify/templates/spec-template.md so the existing Testing / Lane / Runtime Impact block explicitly asks for lane fit, heavy-surface justification, fixture-cost disclosure, and minimal reviewer validation in authoring-time language.
• Updating .specify/templates/plan-template.md so the Test Governance Check and technical planning surfaces make test type changes, helper widening, lane reshaping, escalation triggers, and closing validation explicit before implementation begins.
• Updating .specify/templates/tasks-template.md to standardize a short task-level governance checklist covering lane assignment, minimal setup, relevant validation, hidden-cost prevention, and documentation of material budget or trend impact.
• Updating .specify/templates/checklist-template.md as the canonical generated review-checklist surface, with .specify/README.md as the reviewer entry point, so reviewers get a stable, quick guardrail checklist with direct keep, split, or escalate questions.
• Updating .specify/README.md and README.md with concise contributor guidance showing how to answer N/A for low-impact work, when database or UI-heavy coverage is justified, and when a new heavy family or browser path requires escalation.
• Validating the updated workflow against one low-impact docs or template scenario and one higher-cost governed-spec scenario, confirming that the low-impact path stays fast and the higher-cost path surfaces the intended escalation questions.
• Recording the validation note inside the active spec or implementation PR so the workflow proof is durable and does not live only in casual commentary.

Contract Implementation Note

• The JSON schema is repository-tooling oriented and describes the complete governance pack the repo must express during planning even if the first implementation lives mostly in markdown templates and checklists.
• The OpenAPI file is logical rather than transport-prescriptive. It documents workflow semantics for authoring and review interactions, not a public HTTP API.
• The design intentionally avoids new runtime services or CI bots. The contracts are plan-time alignment aids inside this spec set, not new long-term reviewer-facing workflow surfaces that must evolve independently from the markdown sources.

Deployment Sequencing Note

• No database migration is planned.
• No asset publish step changes.
• Recommended rollout order: tighten constitution text first, then update spec and plan templates, then update task and review checklist surfaces, then update contributor guidance, then validate low-impact and higher-cost scenarios, and finally note any wording refinements needed to keep the process lightweight.