Phase 2B — Move Portable Scripts to Root & Update Paths (#1461)

[ashleyshaw]

Phase 2B — Move Portable Scripts to Root & Update Paths

Status: ⚠️ INCOMPLETE — Requires Phase 2C.X Remediation
Parent: #1461 (Script Organization Architecture)
Related: #1465 (Phase 2C Testing), PR #1493 (Audit Findings)

---

Issue Summary

Move 117 portable scripts from .github/scripts/ to root-level scripts/ folder while maintaining backward compatibility and updating all references throughout the codebase.

Phase 2B Completion Status

✅ DONE:

• Scripts copied to portable location (scripts/)
• Validation infrastructure implemented
• Schema paths updated
• All 1,114 unit tests passing

❌ NOT DONE (Blocking Merge):

• ❌ Dual paths not resolved (scripts still in .github/scripts/)
• ❌ 21 workflow references not updated
• ❌ 28 documentation references not updated
• ❌ Script consolidation incomplete

---

Critical Issues Found (Phase 2C Audit)

Finding 1: Dual Path Problem 🔴

Status: BLOCKING

Scripts exist in BOTH locations:

• .github/scripts/ → 107 files (old location)
• scripts/ → 217 files (new location)
• OVERLAP → ~54 files duplicated

Root Cause: Phase 2B copied scripts but didn't remove from source

Impact:

• Maintenance burden (changes in two places)
• Workflow confusion (which path is authoritative?)
• Potential inconsistency if files diverge

Finding 2: Inconsistent Workflow References 🔴

Status: BLOCKING

21 workflows still reference old .github/scripts/ paths:

1. documentation.yml
2. docs-maintenance.yml
3. docs-validation.yml
4. labeling.yml
5. labeling-governance.yml
6. issue-remediation-bulk.yml
7. metrics-pipeline.yml
8. metrics-reporting.yml
9. project-archival.yml
10. issues.yml
11. reviewer.yml
12. release.yml
13. meta.yml
14. planner.yml
    15-21. (and 7 more workflows)

Impact:

• Workflows may fail if files moved
• No clear migration status
• Inconsistent code paths

Finding 3: Documentation References 🟠

Status: HIGH PRIORITY

28 documentation files reference old paths:

• docs/AUTOMATION.md
• docs/LABELING.md
• docs/RELEASE_PROCESS.md
• docs/METRICS.md
• docs/CHANGELOG_AUTOMATION.md
• (and 23 more documentation files)

---

Phase 2B Execution Status

Stage 1: Inventory & Classification ✅

• Identified all scripts
• Classified portable vs GitHub-only
• Documented folder structure

Stage 2: File Migration ⚠️

• Copy portable scripts to root scripts/
• ❌ ISSUE: Did not remove from .github/scripts/ (dual state)

Stage 3: Reference Updates 🔴 BLOCKED

• Update all workflow references (21 files)
• Update all documentation references (28 files)
• Verify schema path references

Stage 4: Testing & Validation 🟡 PARTIAL

• Unit tests pass (1,114 tests)
• Validation scripts operational
• Workflow references need verification
• Full regression testing

Stage 5: Archive & Closure ⏳ PENDING

• Close issue Architecture: Script Organization — Resolve .github/scripts/ vs. Portable scripts/ Conflict #1461, Phase 2B — Move Portable Scripts to Root & Update Paths (#1461) #1464, Phase 2C — Testing, Documentation & Merge to Develop (#1461) #1465
• Merge to develop
• Update epic Issue Triage Automation System Implementation #1376

---

Phase 2C Extended Scope: Remediation Required

Phase 2C.X (NEW) addresses Phase 2B incomplete execution

2C.X.1: Resolve Dual Path Problem (2-3 hours)

• Identify all duplicate files
• Determine authoritative location
• Move portable scripts to scripts/
• Remove from .github/scripts/
• Keep GitHub-only scripts in .github/scripts/

2C.X.2: Update Workflow References (3-4 hours)

• Update 21 workflows with old references
• Test each with dry-run
• Verify execution
• Commit with clear messages

2C.X.3: Update Documentation References (1-2 hours)

• Update 28 documentation files
• Verify examples still work
• Ensure consistency

2C.X.4: Path Validation & Testing (1 hour)

• Audit schema path references
• Run npm test (1,114+ tests)
• Run npm validate:all (all validators)
• Verify no regressions

2C.X.5: Archive & Closure (1-2 hours)

• Create follow-up PR
• Review and address feedback
• Merge to develop
• Update issues/epic

Total Effort: 10-13 hours

---

Documentation & References

All audit findings available in PR #1493:

Key Documents:

• PHASE_2B_EXECUTION_PLAN.md (830 lines)
• SCRIPTS_INVENTORY.md (630 lines)
• 2026-08-04-CRITICAL-AUDIT-SUMMARY.md
• 2026-08-04-phase-2c-script-testing.md
• STATUS.md (updated with findings)

Issue Comments:

• Architecture: Script Organization — Resolve .github/scripts/ vs. Portable scripts/ Conflict #1461 - Complete audit findings + Phase 2C.X scope
• Phase 2C — Testing, Documentation & Merge to Develop (#1461) #1465 - Testing results + extended scope
• Phase 2B — Move Portable Scripts to Root & Update Paths (#1461) #1464 (this issue) - Phase 2B status update

---

Success Criteria (Phase 2B Completion)

• Portable scripts migrated to scripts/
• All dual paths resolved (duplicate files removed)
• All 21 workflow references updated and tested
• All 28 documentation references updated
• Full regression testing passed
• Zero path resolution errors
• All issues closed with findings documented
• Epic marked complete

---

Recommendation

Phase 2B cannot be marked complete until Phase 2C.X remediation resolves dual paths and updates all references. The portable script architecture is sound (all tests passing), but execution is incomplete.

Recommended Action:

1. Execute Phase 2C.X remediation (10-13 hours)
2. Create follow-up PR with all fixes
3. Merge to develop and close Phase 2B/2C

---

Timeline

Phase	Status	Est. Duration
2B	⚠️ INCOMPLETE	Original
2C.1-4	✅ COMPLETE	5 hours
2C.X	🔴 PENDING	10-13 hours
2C.5	⏳ PENDING	1-2 hours

Total for completion: ~10-13 hours from start of Phase 2C.X

---

Last Updated: 2026-08-04 (Phase 2C Audit)
Next Action: Review PR #1493 and plan Phase 2C.X remediation

[linear-code]

LS-2253

[github-actions]

⏱️ Aging and SLA annotation

• Age: 0 day(s)
• SLA state: Within SLA
• Thresholds: warn at 7 days, breach at 14 days
• Last updated: 2026-08-04T14:17:09.204Z

Maintained by project-meta-sync workflow.

[github-actions]

⚠️ This issue does not follow a required issue template.

Missing required section(s): Definition of Ready (DoR), Definition of Done (DoD)

The issue will remain open and flagged until the body is corrected.
Please update the issue with one of the official templates:

• https://github.com/lightspeedwp/.github/issues/new/choose

If this was opened by automation, update the automation to preserve the template sections before creating the issue.