Repository Structure: Schema Consolidation Migration

[ashleyshaw]

---

name: "Repository Structure: Schema Consolidation Migration"
labels:

• type:task
• status:needs-more-info
• priority:medium
• component:repo-structure
• area:documentation
  assignees: []

---

Overview

Consolidate schema files from current location (.github/schema/) to unified hidden folder (.github/.schemas/) following awesome-copilot pattern. This requires updating 200+ references across scripts, workflows, and documentation.

Status: Ready for implementation (Extended audit complete)

Problem Statement

The repository has schema files in .github/schema/ (26 files) with:

• Inconsistent references across 200+ locations (scripts, workflows, docs)
• Hard-coded paths in 4 validation scripts that need updating
• Boundary marker duplication between .github/.github/schemas/ and .github/.schemas/
• Unclear separation between portable schemas (12) and repo-local schemas (5)

The target consolidation location .github/.schemas/ is prepared but empty.

Definition of Ready (DoR)

• Extended audit completed (all 26 files and 200+ references mapped)
• Consolidation plan documented in project folder
• Target location identified: .github/.schemas/ (nested hidden folder)
• Risk assessment completed (Low risk - no circular dependencies)
• Implementation sequence defined (Phase 1-4)
• Branch created with proper naming: refactor/repo-structure-schema-consolidation

Definition of Done (DoD)

Phase 1: Validation & Preparation

• Review extended audit findings and consolidation map
• Confirm target location: .github/.schemas/
• Verify all 26 source files are accounted for
• Document any script dependencies not yet identified

Phase 2: Documentation Updates

• Update CLAUDE.md - Repository boundaries table, schema location reference
• Update .github/custom-instructions.md - Path references
• Update instructions/file-organisation.instructions.md - Schema folder location
• Update all documentation references (150+) - Bulk find/replace .github/schema/ → .github/.schemas/

Phase 3: File Migration

• Move all 26 files from .github/schema/ to .github/.schemas/
  • 25 schema JSON files
  • 2 example files (in examples/ subdirectory)
  • 5 memory system schemas (in memory/ subdirectory)
  • 1 README.md (merge with existing)
• Update .github/schema/schema-registry.json references in .github/.schemas/schema-registry.json

Phase 4: Script & Configuration Updates

• Update .github/scripts/agents/branding-unified.agent.js - Path references (2 locations)
• Update .github/scripts/verify-wceu-readiness.js - Directory check logic
• Update 4 workflow files - Path triggers and references
• Update package.json - Schema glob patterns from schema/** → .schemas/**

Phase 5: Validation & Cleanup

• Run npm run validate:json:schemas - Verify schemas validate
• Run all CI workflows - Confirm passing
• Verify no broken references in documentation
• Delete old .github/schema/ directory (after verification)
• Confirm .github/.github/schemas/ remains as repo-local boundary marker
• Update CHANGELOG.md with migration entry

Quality Gates

• All hardcoded script paths updated and tested
• CI/CD pipeline passes
• Zero broken documentation links
• Zero references to old .github/schema/ location (except history)

Audit Findings Summary

Locations Involved:

• Source: .github/schema/ (26 files - active, contains all production schemas)
• Target: .github/.schemas/ (nested hidden folder - prepared, currently empty)
• Boundary: .github/.github/schemas/ (repo-local marker - will remain)

File Inventory (26 total):

• 25 JSON schema files (12 portable, 5 repo-local, 8 supporting)
• 2 example files
• 5 memory system schemas
• 1 README.md

Reference Map (200+ total):

• 4 hardcoded script references (P1)
• 4 workflow file references (P1)
• 150+ documentation references (P2)
• 5 configuration file references (P2)

Risk Assessment: 🟢 Low Risk

• No circular dependencies
• Well-isolated schema system
• Can proceed independently
• Estimated effort: 6-8 hours

Implementation Plan

See detailed plan in:
projects/active/repository-maintenance-infrastructure/SCHEMA-CONSOLIDATION-MIGRATION-PLAN.md

Phases:

1. Validation & Preparation (~1 hour)
2. Documentation Updates (~2-3 hours)
3. File Migration (~30 minutes)
4. Script & Configuration Updates (~1-2 hours)
5. Validation & Cleanup (~1 hour)

Related Issues & PRs

• Related: Wave 5 Documentation Audit (file organization alignment)
• Related: Repository Maintenance Infrastructure project
• Blocks: Any documentation or tooling relying on schema location clarity
• Blocked By: None

Child Issues (to be created)

• Phase 1: Validate schema consolidation scope and dependencies
• Phase 2: Update documentation and governance files
• Phase 3: Migrate schema files to .github/.schemas/
• Phase 4: Update scripts and workflows with new paths
• Phase 5: Validation, cleanup, and post-migration verification

Notes

• Use .github/.schemas/ as canonical location (hidden folder, nested in .github/)
• Archive migration of .github/instructions/ to root instructions/ is separate initiative
• Consolidate with agents restructuring (PR to follow for that initiative)
• Maintain boundary markers for clarity on portable vs. repo-local assets

Checklist for Reviewer

• Audit findings are accurate and complete
• Consolidation plan is realistic and achievable
• Implementation sequence makes sense
• Risk assessment is reasonable
• Ready to proceed with Phase 1

[linear-code]

LS-1829

[github-actions]

⏱️ Aging and SLA annotation

• Age: 5 day(s)
• SLA state: Within SLA
• Thresholds: warn at 7 days, breach at 14 days
• Last updated: 2026-07-29T17:26:24.824Z

Maintained by project-meta-sync workflow.

[ashleyshaw]

Phase 1: Validation & Preparation — COMPLETE ✅

Findings Summary

File Inventory Verified

• ✅ Source location: .github/schema/ (26 files confirmed)
  • 19 root schema files (.schema.json, .v2.json, registry)
  • 2 example files (examples/ subdirectory)
  • 5 memory schema files (memory/ subdirectory)
• ✅ Target location: .github/.schemas/ (prepared, contains README.md only)
• ✅ All 26 source files accounted for

Script Dependencies Documented

Found 35 total references across 11 script files:

Scripts Using schema/ paths (27 references):

1. scripts/verify-wceu-readiness.js — 7 references
   • Checks for frontmatter.schema.json, plugin-manifest.schema.json
   • Validates memory/ directory has 5 schemas
   • ⚠️ ISSUE: Also checks that .schemas should NOT exist — needs update
2. scripts/validation/validate-agent-frontmatter.js — 2 references
   • Uses ../../schema/frontmatter.schema.json hardcoded path
3. scripts/validation/validate-frontmatter.js — 1 reference
   • Uses ../../schema/frontmatter.schema.json hardcoded path
4. scripts/validation/validate-links.js — 1 reference
   • References schema/README.md in content
5. scripts/validation/validate-json.js — 2 references
   • Example documentation only
6. scripts/validation/__tests__/validate-branch-name.test.js — 1 reference
   • Test data reference
7. package.json — 2 npm scripts
   • validate:json:schemas — glob schema/**/*.json
   • format:json:schemas — glob schema/**/*.json

Scripts Using .schemas paths (8 references):

1. scripts/verify-wceu-readiness.js — 4 references
   • Checks for .schemas directory that should NOT exist (conflicting)
   • Scans for orphaned .schemas/ references
2. scripts/agents/branding-unified.agent.js — 2 references
   • ✅ ALREADY EXPECTS NEW LOCATION: .schemas/branding-schema.json and .schemas/frontmatter.schema.json
3. scripts/validation/update-coderabbit-schema.cjs — 1 reference
   • ✅ ALREADY EXPECTS NEW LOCATION: ../../.schemas/coderabbit-overrides.v2.json
4. scripts/validation/validate-coderabbit-yml.cjs — 1 reference
   • ✅ ALREADY EXPECTS NEW LOCATION: ../../.schemas/coderabbit-overrides.v2.json

Conflicting Logic Found ⚠️

scripts/verify-wceu-readiness.js has conflicting checks:

• Line: checkDirExists(".schemas", true); — Checks .schemas should NOT exist
• But this will fail AFTER migration when .schemas/ does exist
• This script needs logic update to accommodate post-migration state

Action Items for Phase 2

Priority 1 — Critical Path (blocking migration):

1. Update scripts/verify-wceu-readiness.js

   • Change .schemas check from "should NOT exist" to "should exist"
   • Update orphaned reference scanning logic
   • Update memory schema count check path

2. Update hardcoded paths in:

   • scripts/validation/validate-agent-frontmatter.js (line ~22)
   • scripts/validation/validate-frontmatter.js (hardcoded path)

3. Update npm scripts in package.json:

   • Change glob schema/**/*.json → .schemas/**/*.json (2 scripts)

Priority 2 — Documentation & Configuration:

1. Update .coderabbit.yml references to .schemas/
2. Update validation examples in script documentation
3. Update validate-links.js reference list

Priority 3 — Already Prepared:

• ✅ scripts/agents/branding-unified.agent.js already expects .schemas/
• ✅ update-coderabbit-schema.cjs already expects .schemas/
• ✅ validate-coderabbit-yml.cjs already expects .schemas/

DoD Checklist Update

• Review extended audit findings and consolidation map
• Confirm target location: .github/.schemas/
• Verify all 26 source files are accounted for
• Document any script dependencies not yet identified

Next Step: Proceed to Phase 2 (Documentation Updates)

---

Phase 1 Status: ✅ READY FOR PHASE 2