tomevault-io Skill: coordinator-blueprint-gates
Purpose
Run deterministic PASS/FAIL validation on Architect outputs (RA/Tech/DP/Handoff) and produce a BlueprintIssueReport when failing.
Trigger
Use whenever Architect provides:
- updated RA/Tech/DP
- a GRACE_HANDOFF v2
- block and you must decide whether blueprint is ready for approval/implementation.
Coordinator Validation Gates (PASS/FAIL)
Blueprint Validation (Architect Output) -- REQUIRED
Run these gates and output PASS/FAIL.
- Consistency Gate (BLOCKING)
- IDs follow conventions: ACT/UC/NFR/DP-SVC/Flow/DEC/MC/FC/BA/TC
- No "OR" ambiguity in canonical artifacts
- DEC-* identical across Technology.xml and handoff DecisionsSnapshot
- DB-per-service and no cross-service joins implied
- New services (if any) must have:
- DP-SVC entry
- bounded context named
- dependencies listed
- DB ownership implied (no shared schema)
- Traceability Gate (BLOCKING)
- All targets exist (or explicitly marked TBD with PENDING_HUMAN)
- UC -> Flow -> Contract -> BA -> TC is linked for in-scope critical paths
- Completeness Gate (BLOCKING for critical paths)
- For each in-scope critical use case: FC exists + BA anchors defined + TC-* cases present
- Core critical paths typically include:
- configuration validation
- pricing calculation
- payment/deposit capture
- order state transitions
- measurement request + submit results (if in scope)
- B2B billing/invoices (if in scope)
- document generation/versioning (if in scope)
- Security Mapping: Explicit RBAC roles defined for critical entry points (function/module contracts).
- API Alignment: Inbound adapters mapped to explicit definitions in api-contracts.
- ContractEvolutionPolicy exists in DevelopmentPlan.xml (or explicitly added by Architect)
- Human-Readability & Clean-Code Gate (BLOCKING)
- Blueprint/contracts must lead to human-readable code: small responsibilities, explicit boundaries, predictable flow.
- Watchlist enforcement (must be addressed in blueprint/contracts): A) Huge classes/methods must be prevented by design (SRP split, clear module responsibilities). Example: NO validate+price+save+notify in one service -> OK split components/services B) Magic numbers must be avoided via domain constants/config/enums. Example: NO if(attempts>5) -> OK if(attempts>MAX_LOGIN_ATTEMPTS) C) Error handling must be consistent and domain-focused (no generic exceptions for domain failures). Example: NO IllegalArgumentException("Configuration not found") OK AccountDomainErrors.configurationNotFound(userId, configId) D) Mapper duplication must be addressed via shared mapping utilities/abstractions. E) Complex conditional logic must be minimized via guard clauses, named predicates, or Strategy/State. Example: NO if(a){if(b){if(c){...}}} -> OK guard clauses / Strategy
If any gate fails, produce BlueprintIssueReport-YYYYMMDD-##.xml file in docs/grace/reports/blueprint-issue with the following format:
- Git Governance Gate (BLOCKING)
- Architect output includes before GRACE_HANDOFF
- GIT_IMPACT routing is consistent with handoff scope (services/use cases)
- Coordinator produces a BranchSpec consistent with GIT_IMPACT and GitFlow defaults
- For release/* or hotfix/*: back-merge requirement is explicitly present
- No instruction suggests direct pushes to main/develop or force-push
PASS Output
- CoordinatorChecks: PASS with gate list
- ApprovalInstruction: include exact v2 tag to add to approvals.log
FAIL Output
- CoordinatorChecks: FAIL + gate name(s)
- Produce BlueprintIssueReport XML (below)
- Route to Architect with a minimal fix list
BlueprintIssueReport Template
<BlueprintIssueReport
id="ISSUE-RPT-YYYYMMDD-##"
handoffRef="Handoff-YYYYMMDD-##[-suffix]"
gateStatus="FAIL|PASS_WITH_WARNINGS"
created="YYYY-MM-DDTHH:mm:ss(+|-)HH:MM"
validatedBy="GRACE-COORDINATOR"
>
<Summary>
[High-level summary of why the handoff failed gate validation. Highlight blocking issues concisely. E.g., "Handoff failed Consistency Gate due to missing decisions in Technology.xml."]
</Summary>
<Issue id="ISS-...">
<Severity>BLOCKING|NONBLOCKING</Severity>
<Description>...</Description>
<Evidence>Artifact/Section/ID references...</Evidence>
<Impact>...</Impact>
<ProposedFix>...</ProposedFix>
<RequiredAgent>GRACE-ARCHITECT</RequiredAgent>
</Issue>
<Recommendation>
[Clear, directive instructions on the next workflow steps. E.g., "Return to GRACE-ARCHITECT to address blocking issues. Once resolved, re-submit for validation."]
</Recommendation>
</BlueprintIssueReport>
Converted and distributed by TomeVault — claim your Tome and manage your conversions.