plan-cross-wp-validation

name	plan-cross-wp-validation
description	Cross-WP consistency check, config schemas
argument-hint	Invoked by Planner Coordinator - do not call directly

plan-cross-wp-validation

Phase: 2 (Contract Generation -- runs last) Common contract: .github/skills/PLAN-SKILL-CONTRACT.md Spec refs: FR-051, FR-052, FR-053, FR-054

This skill is dispatched by the Planner Coordinator as the final Phase 2 skill. It reads ALL plan files and ALL contract files generated by earlier skills, performs a 7-point consistency audit, generates a shared configuration schema, fixes any inconsistencies, and verifies 100% spec artifact coverage.

---

Input Contract (FR-023)

#	Input	Description
1	skill_path	Path to this SKILL.md file
2	plan_dir	Path to .sdd/plans/ directory
3	contracts_dir	Path to .sdd/plans/contracts/ directory
4	spec_path	Path to the source spec file
5	spec_artifacts_dir	Path to spec companion artifacts
6	research_summary	Key findings from the research phase
7	target_language	Programming language for contract generation
8	patterns	Active plan-domain patterns to avoid
9	phase	Phase indicator (always 2 for this skill)

---

Execution Sequence (FR-024)

1. Read SKILL.md - Load this file for validation instructions
2. Read plan state - Read README, ALL WP files, and ALL contract files from contracts_dir
3. Read spec + artifacts - Read the full spec and ALL companion artifacts from spec_artifacts_dir. Read multiple independent files in parallel via concurrent tool calls.
4. Write fixes + outputs - Fix inconsistencies in WP/contract files, generate config schema, update README

---

Step 1 - Load All Inputs

This skill requires the broadest read scope of any plan skill:

1. Plan files: plan_dir/README.md and all plan_dir/WP*.md files
2. Contract files: All files under contracts_dir/ (per-WP and shared directories)
3. Spec: Full spec at spec_path
4. Spec artifacts: All files under spec_artifacts_dir/ (interfaces, data-schemas, api-contracts, state-machines, error-catalog)

---

Step 2 - Run 7-Point Consistency Audit (FR-051)

Perform each check and collect findings. For each finding, record:

• Check category (1-7)
• Severity (error / warning)
• Affected files
• Description of the inconsistency
• Proposed fix

Check 1: Data Contract Consistency (FR-051.1)

For each entity that appears in data-schemas across multiple WPs:

1. Compare field names -- must be identical
2. Compare field types -- must be identical
3. Compare validation rules -- must be compatible (stricter is OK, weaker is not)
4. Compare relationship definitions -- must be consistent

Example inconsistency: WP01 defines userId: string but WP03 uses userId: number. Fix: use the spec's canonical type.

Check 2: API/Interface Contract Consistency (FR-051.2)

For each endpoint or interface referenced across multiple WPs:

1. Compare HTTP method + path -- must match
2. Compare request type fields -- must match
3. Compare response type fields -- must match
4. Compare error response schemas -- must be consistent
5. Compare interface method signatures -- parameter types and return types must match

Example inconsistency: WP02 defines POST /api/orders expecting { userId: string } but WP04 sends { user_id: string }. Fix: use the spec's canonical field name.

Check 3: Dependency Integrity (FR-051.3)

1. Build the WP dependency graph from metadata table Depends on fields
2. Run topological sort -- if it fails, there is a circular dependency
3. Verify every Depends on reference is a valid WP ID (not a typo, not a non-existent WP)
4. For WPs marked Parallelisable: Yes, verify they do not share mutable state:
   • Do not write to the same data entities
   • Do not modify the same config keys
   • Do not have implicit ordering requirements
5. Cross-reference README dependency graph with individual WP declarations

Check 4: Configuration Consistency (FR-051.4)

Scan all WP files and contract files for environment variables and config keys:

1. Extract all env var references (e.g., process.env.DATABASE_URL, os.environ['DATABASE_URL'])
2. Compare names -- must be identical across WPs
3. Compare expected types -- must be identical
4. Compare default values -- must be consistent (WP-A must not assume a different default than WP-B)
5. Identify undocumented env vars -- referenced in code but not in any WP implementation guidance

Check 5: Test Consistency (FR-051.5)

1. Verify coverage thresholds (80% code, 90% branch) are stated identically in all WPs that reference testing
2. Verify test requirement types are consistent with spec BDD scenarios
3. Verify BDD scenario references in tasks match actual scenarios in the spec

Check 6: Spec Traceability (FR-051.6)

1. Extract all FR IDs from the spec's traceability matrix (Section 16)
2. Extract all Spec refs from all tasks across all WPs
3. Build FR -> Task mapping
4. Verify:
   • Every FR has at least one task (no orphan FRs)
   • No FR is assigned to multiple tasks unless explicitly justified (shared FRs like FR-023, FR-024)
   • Every task has at least one FR (no untraced tasks)

Check 7: Contract-to-Task Alignment (FR-051.7)

1. List all contract files under contracts_dir/
2. Search all task descriptions and implementation guidance across all WPs for references to those files
3. Verify:
   • Every contract file is referenced by at least one task
   • Every task that mentions a contract file has the file actually generated
   • No orphan contracts (generated but unreferenced)
   • No missing contracts (referenced but not generated)

---

Step 3 - Generate Configuration Schema (FR-052)

After completing the consistency audit, aggregate all environment variables and config keys into a shared config schema:

Write <contracts_dir>/shared/config-schema.<ext>:

Manifest Header

// Generated by: plan-cross-wp-validation skill
// Source spec: <spec_path>
// Work package: shared
// Target language: <target_language>
// DO NOT EDIT MANUALLY -- regenerated on plan revision

Schema Content

// TypeScript example
export interface AppConfig {
  DATABASE_URL: string;          // PostgreSQL connection string
  JWT_SECRET: string;            // JWT signing secret (min 32 chars)
  PORT: number;                  // HTTP server port (default: 3000)
  LOG_LEVEL: 'debug' | 'info' | 'warn' | 'error';  // (default: 'info')
  REDIS_URL?: string;            // Redis connection string (optional)
}

export const CONFIG_DEFAULTS: Partial<AppConfig> = {
  PORT: 3000,
  LOG_LEVEL: 'info',
};

export const CONFIG_VALIDATION = {
  DATABASE_URL: { type: 'string', required: true, format: 'uri' },
  JWT_SECRET: { type: 'string', required: true, minLength: 32 },
  PORT: { type: 'number', required: false, default: 3000, min: 1, max: 65535 },
  LOG_LEVEL: { type: 'string', required: false, default: 'info', enum: ['debug', 'info', 'warn', 'error'] },
  REDIS_URL: { type: 'string', required: false, format: 'uri' },
} as const;

# Python example
from pydantic import BaseModel, Field
from typing import Literal, Optional

class AppConfig(BaseModel):
    DATABASE_URL: str = Field(..., description='PostgreSQL connection string')
    JWT_SECRET: str = Field(..., min_length=32, description='JWT signing secret')
    PORT: int = Field(3000, ge=1, le=65535, description='HTTP server port')
    LOG_LEVEL: Literal['debug', 'info', 'warn', 'error'] = Field('info', description='Log level')
    REDIS_URL: Optional[str] = Field(None, description='Redis connection string')

Each config entry MUST include:

• Name (the env var or config key)
• Type
• Default value (if any)
• Validation rule (min/max, format, enum, etc.)
• Description (one-line purpose)
• Which WP(s) reference it

---

Step 4 - Fix Inconsistencies (FR-053)

For each finding from Step 2:

1. Determine the canonical value: Use the spec as the source of truth. If the spec does not specify, use the first-definer WP's value.
2. Apply the fix: Modify the affected WP file or contract file directly
3. Use the [CONSISTENCY FIX] marker per FR-027 when modifying existing files
4. Record the fix: Add an entry to the corrections log

Do NOT fix by removing content -- always fix by correcting to the canonical value.

---

Step 5 - Document Corrections in README (FR-053)

Update <plan_dir>/README.md with a "Consistency Notes" section:

## Consistency Notes

Cross-WP consistency audit performed by plan-cross-wp-validation. Findings:

- **Data contracts**: [summary of findings and corrections]
- **API/Interface contracts**: [summary]
- **Dependency integrity**: [summary]
- **Configuration**: [summary]
- **Test consistency**: [summary]
- **Spec traceability**: [summary - X orphan FRs found and assigned, Y duplicate assignments resolved]
- **Contract-to-task alignment**: [summary - X orphan contracts, Y missing contracts]

### Corrections Applied

| # | Category | Files Affected | What Changed |
|---|----------|---------------|--------------|
| 1 | Data contract | WP03/data-schemas.ts | Changed userId type from number to string per spec |
| 2 | Config | WP01.md, WP03.md | Unified PORT default to 3000 |

If no inconsistencies are found, state it explicitly:

## Consistency Notes

Cross-WP consistency audit performed. No inconsistencies found across all 7 checks.

---

Step 6 - Verify 100% Spec Artifact Coverage (FR-054)

Compare spec companion artifacts against generated contract files:

1. Entities: Every entity in spec_artifacts_dir/data-schemas.<ext> must appear in at least one WP's data-schemas.<ext>
2. Endpoints: Every endpoint in spec_artifacts_dir/api-contracts.<ext> must appear in at least one WP's api-contracts.<ext>
3. Error codes: Every error code in spec_artifacts_dir/error-catalog.<ext> must appear in at least one WP's error-catalog.<ext>
4. State machines: Every state machine in spec_artifacts_dir/state-machines.<ext> must appear in at least one WP's state-machines.<ext>
5. Interfaces: Every interface in spec_artifacts_dir/interfaces.<ext> must appear in at least one WP's interfaces.<ext>

Output a coverage matrix:

### Spec Artifact Coverage

| Artifact Type | Spec Count | Plan Count | Coverage |
|--------------|-----------|-----------|----------|
| Entities | 5 | 5 | 100% |
| Endpoints | 10 | 10 | 100% |
| Error codes | 15 | 15 | 100% |
| State machines | 2 | 2 | 100% |
| Interfaces | 8 | 8 | 100% |

**Overall**: 100% coverage

If coverage is below 100%, list the missing items and flag them for resolution.

If spec companion artifacts do not exist (spec was prose-only), note it and skip coverage verification:

### Spec Artifact Coverage

No companion artifacts found at `<spec_artifacts_dir>`. Coverage verification skipped.
Plan contracts were generated from spec prose (see individual skill outputs).

---

Constraints

• This skill MUST run after all other Phase 2 skills have completed
• Fixes MUST use the [CONSISTENCY FIX] marker when modifying existing files (FR-027)
• The spec is always the tiebreaker for inconsistencies -- not any individual WP
• Do NOT add new WPs or tasks -- only fix content inconsistencies
• Do NOT remove WPs, tasks, or contract files
• config-schema goes to contracts/shared/, not to individual WP directories
• Use plain ASCII hyphens and straight quotes only -- no em dashes, smart quotes, or curly apostrophes