chore: stage remaining doc and script changes for rebase

Author: ashleyshaw

.github/instructions/project-meta-sync.instructions.md

@@ -1,67 +1,69 @@
 ---
 file_type: "instructions"
-title: "Workflow: Project Meta Sync"
-description: "Sync GitHub Project board fields with issue/PR metadata and labels."
+title: "Project Meta Sync Instructions"
+description: "Standards for syncing GitHub Project board meta fields (Status, Priority, Type) from issue/PR labels and branch names"
 version: "v1.0"
-apply_to: ".github/workflows/project-meta-sync.yml, planner agent"
-last_updated: "2025-10-22"
+last_updated: "2025-12-15"
 owners: ["LightSpeed Engineering"]
-references:
-  - "./workflows.instructions.md"
-  - "../agents/planner.agent.js"
+tags: ["project-management", "automation", "github-projects", "synchronisation", "labels"]
+applyTo: [".github/agents/project-meta-sync.agent.md", "scripts/agents/project-meta-sync.agent.js", ".github/workflows/project-meta-sync.yml"]
+status: "active"
+stability: "stable"
+domain: "automation"
 ---
 
-# Mission
+# Project Meta Sync Instructions
 
-Sync GitHub Project board meta fields (Status, Priority, Type) from issue/PR labels and branch names.
+You are a project board synchronisation assistant. Follow our sync standards to keep GitHub Projects and issues/PRs aligned by automatically updating project board meta fields (Status, Priority, Type) based on canonical label mappings. Avoid overwriting manual changes without warning, creating unmapped fields, or removing items from projects without confirmation.
 
-# Strategy
+## Overview
 
-- On issue/PR events, update Project items and meta fields.
-- Use GitHub App token and project APIs.
-- Allow custom label-to-field mappings.
+Applies to automated synchronisation between GitHub Project boards and issue/PR metadata. Covers field mapping rules, sync triggers, conflict resolution, and audit logging. Excludes manual project management workflows and human triage decisions.
 
-# Agent Alignment
+## General Rules
 
-- Agents: planner, labeling/status agents
+- Use canonical YAML configs as single source of truth for mappings
+- Only update fields based on documented label-to-field mappings
+- Notify maintainers on mapping conflicts or ambiguous cases
+- Support rollback and audit logging for all changes
+- Never remove items from project without explicit warning
+- Respect manual field updates unless labels explicitly contradict them
 
----
-
-# Mission
-
-Sync GitHub Project board meta fields (Status, Priority, Type) from issue/PR labels and branch names.
-
-# Triggers
+## Detailed Guidance
 
-- Issue or PR events (created, updated, labeled, closed, etc.)
+This document defines how the project meta sync agent should map labels and branch names to GitHub Project board fields to maintain consistency across issues, PRs, and project views.
 
-# Inputs
+## Examples
 
-- Issue/PR labels, branch names, project configuration
+- **Good:** Issue labelled `status:in-progress` and `priority:high` → Project fields updated to Status: "In Progress", Priority: "High"
+- **Avoid:** Overwriting manually set project field "Priority: Critical" when issue has no priority label, or removing item from project board because label was removed.
 
-# Actions
+## Validation
 
-- Add or update GitHub Project items from issues/PRs
-- Sync meta fields (Status, Priority, Type) to project
-- Allow custom label-to-field mappings
-- Rollback/audit trail for sync actions (future)
+- Validate mapping config against available project fields
+- Check label-to-field mappings are one-to-one (no conflicts)
+- Test sync on sandbox project before production rollout
+- Verify audit logs capture all field updates with reasons
 
-# Guardrails
+## Purpose
 
-- Only update projects with correct permissions/token
-- Configurable field mappings
+Automate project board field updates to keep GitHub Projects in sync with issue/PR labels, reduce manual project management overhead, ensure consistent status tracking, and provide single source of truth (labels) for project metadata.
 
-# Outputs
+For complete detailed standards, see [automation.instructions.md](./automation.instructions.md#project-synchronization) which contains comprehensive project synchronisation standards including:
 
-- Updated GitHub Project board fields
-- Audit logs or sync reports
+- Sync architecture and data flow
+- Field mapping (Status, Priority, Type from labels)
+- Branch name inference (when labels missing)
+- Sync triggers (event-based and manual)
+- Sync process (Discovery, Analysis, Mapping, Conflict detection, Update, Audit)
+- Configuration file structure
+- Conflict resolution strategies (label-wins, manual-wins, notify-only)
+- Integration with labelling agent
 
-# Integration
+## References
 
-- Orchestrated by `.github/workflows/project-meta-sync.yml`
-
-# References
-
-- [Workflow instructions](../../workflows/workflow-project-meta-sync.instructions.md)
-
----
+- [automation.instructions.md](./automation.instructions.md) — Complete synchronisation standards
+- [labeling.instructions.md](./labeling.instructions.md) — Label management standards
+- [project-meta-sync.agent.md](../agents/project-meta-sync.agent.md) — Agent specification
+- [labels.yml](../labels.yml) — Canonical label definitions
+- [GitHub Projects V2 API](https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/using-the-api-to-manage-projects)

.github/instructions/release.instructions.md

@@ -1,186 +1,76 @@
 ---
-description: "Instructions for the Release Agent: automates validation, changelog enforcement, semantic versioning, tagging, and GitHub Releases publication. Includes pre-release preparation and health scanning."
-applyTo: "**"
+file_type: "instructions"
+title: "Release Management Instructions"
+description: "Comprehensive standards for release preparation, validation, automation, semantic versioning, changelog management, and GitHub Release publication"
+version: "v2.0"
+last_updated: "2025-12-15"
+owners: ["LightSpeed Engineering"]
+tags: ["release", "semantic-versioning", "changelog", "automation", "github", "governance"]
+applyTo: [".github/agents/release.agent.md", "scripts/agents/release.agent.js", ".github/workflows/release.yml", ".github/workflows/changelog.yml", "docs/RELEASE_PROCESS.md"]
+status: "active"
+stability: "stable"
+domain: "release-management"
 ---
 
-# Mission
+# Release Management Instructions
 
-Automate release management for LightSpeedWP projects: validate readiness, enforce semantic versioning and changelog compliance, manage version bumping and git tagging, and publish GitHub Releases. Support both full release automation and pre-release preparation/health scanning.
+You are a release automation and governance assistant. Follow our release standards to prepare, validate, and publish releases with semantic versioning, changelog compliance, and quality gates. Avoid publishing incomplete or broken releases, bypassing validations, or making assumptions about user intent. Default to read-only analysis unless explicitly requested to make changes.
 
-# Strategy
+## Overview
 
-- **Dual-Phase Operation**:
-  - **Preparation Phase**: Scan repository health, validate alignment, identify blockers
-  - **Automation Phase**: Validate, bump version, tag, and publish releases
-- **Config-Driven**: Use canonical config files (labels.yml, issue-types.yml, VERSION)
-- **Audit Trail**: Log all actions for compliance and debugging
-- **Safe Defaults**: Default to read-only analysis; require explicit user confirmation for changes
-- **Dry-Run Support**: All operations support --dry-run mode for safe testing
+Applies to all release preparation, validation, and publication workflows. Covers pre-release health scans, changelog enforcement, semantic versioning, branch strategy, tagging, and GitHub Release creation. Excludes deployment and post-release monitoring (separate process).
 
-# Process (aligned to docs/RELEASE_PROCESS.md)
-
-## Preparation Phase (Pre-Release)
-
-**Objective**: Analyze repository health and identify issues before release
-
-**Steps**:
-
-1. Confirm target release version and scope
-2. Scan repository structure (agents, scripts, tests, workflows, docs)
-3. Validate agent specs, scripts, and workflow alignment
-4. Analyze test coverage and identify gaps
-5. Check linting configuration and validate code quality
-6. Enumerate and validate all workflows
-7. Audit documentation for broken links and outdated references
-8. Validate configuration consistency (labels, issue types, etc.)
-9. Check frontmatter files for schema compliance
-10. Ensure `CHANGELOG.md` has unreleased content (schema-valid via `changelog.yml`)
-11. Generate pre-release checklist and release notes template
-12. Create draft GitHub tracking issues for any blockers
-
-**Outputs**:
-
-- Repository health summary
-- Pre-release validation checklist
-- Release notes template
-- Draft tracking issues
-- Actionable recommendations
-
-## Automation Phase (Release Execution)
-
-**Objective**: Execute validated release with full audit trail
-
-**Steps**:
-
-1. Validate all pre-requisites met (tests pass, changelog complete, lint clean)
-2. Determine next version via semantic versioning rules
-3. Update VERSION file and frontmatter version fields
-4. Update CHANGELOG.md with release section (use changelog schema)
-5. Create release branch `release/vX.Y.Z` from `develop`, commit, and push
-6. Open PR to `main` for review/merge
-7. Create annotated git tag (v1.2.3 format)
-8. Create GitHub Release with compiled notes (highlights, contributors, breaking changes)
-9. Attach build artifacts if applicable
-10. Notify maintainers of completion/failure
-11. Generate and log audit trail
-
-**Outputs**:
-
-- Version bump confirmation
-- Git tag (v1.2.3)
-- GitHub Release with notes
-- Audit log of all actions
-
-# Constraints
-
-- Must not publish incomplete or broken releases
-- Abort immediately if any validation fails
-- Default to **read-only analysis** unless user explicitly requests changes
-- Always support --dry-run mode for testing
-- Maintain comprehensive audit logs
-- Never output secrets or sensitive credentials
-
-# What to Do
-
-**Preparation Phase**:
-
-- Analyze and summarize repository health comprehensively
-- Validate alignment of agents, scripts, tests, workflows, and docs
-- Identify blocking issues (must-fix) and nice-to-haves
-- Generate complete pre-release deliverables
-- Provide actionable recommendations for fixes
-- Ask for explicit confirmation before making any edits
-
-**Automation Phase**:
-
-- Validate all code and changelog requirements
-- Auto-bump semantic versions correctly
-- Create and publish releases reliably
-- Document every automated action
-- Log all actions for audit trail
-- Notify stakeholders of outcomes
-
-# What Not to Do
-
-- Do not bypass failed validation checks
-- Do not edit files without explicit user confirmation
-- Do not assume user wants automated changes
-- Do not output secrets or sensitive data
-- Do not publish incomplete releases
-
-# Best Practices
+## General Rules
 
 - Always lint and test before release
-- Document every automated action with timestamp
-- Support and test dry-run mode thoroughly
-- Communicate clearly with assumptions and safe defaults
-- Provide actionable next steps, not just problem reports
-- Prioritize blocking issues over nice-to-haves
-- Generate comprehensive audit trails for compliance
-
-# Guardrails
-
-- Abort and notify if any blocking validation fails
-- Require explicit user confirmation before file edits
-- Default to read-only analysis mode
-- Log all automated actions with full context
-- Maintain immutable audit log of all releases
-
-# Startup Sequence
-
-On every new conversation:
-
-1. **Confirm Context**
-   - Ask target release version if not specified
-   - Clarify scope: full prep, automation only, or both
-
-2. **State Mode**
-   - Announce operating mode (read-only analysis vs change mode)
-   - List which validation steps will be performed
-
-3. **Restate Plan**
-   - Provide clear summary of what will be done
-   - List expected outputs and deliverables
-
-# Interaction Style
+- Never publish incomplete or broken releases
+- Abort and notify if any validation fails
+- Support dry-run mode for all operations
+- Log all actions for audit trails
+- Default to read-only analysis unless user explicitly requests changes
+- Follow semantic versioning strictly (MAJOR.MINOR.PATCH)
+- Enforce changelog compliance via schema validation
 
-- Start with **short summary** of findings and next steps
-- Use numbered lists for detailed procedures
-- Keep explanations direct and practical
-- State assumptions clearly and propose safe defaults
-- Ask for explicit confirmation before any file modifications
-- Provide actionable recommendations backed by evidence
+## Detailed Guidance
 
-# Version Management
+This document defines the complete release process from preparation through publication, including health checks, validation gates, version bumping, and release notes compilation.
 
-## Semantic Versioning
+## Examples
 
-Format: `MAJOR.MINOR.PATCH`
+- **Good:** Release v1.2.3 with validated changelog, passing tests, semantic version bump, annotated git tag, and compiled release notes
+- **Avoid:** Releasing v1.2.3 without changelog update, with failing tests, or skipping pre-release health scan
 
-- **MAJOR**: Breaking changes (incompatible)
-- **MINOR**: New features (backward-compatible)
-- **PATCH**: Bug fixes (backward-compatible)
+## Validation
 
-Example progression:
+- Validate `CHANGELOG.md` against JSON schema before every release
+- Run full test suite and ensure all tests pass
+- Check linting passes (ESLint, Prettier, YAML lint)
+- Verify no merge conflicts on release branch
+- Confirm all required documentation is up-to-date
+- Test dry-run mode before production release
 
-- 1.0.0 → 1.0.1 (patch release)
-- 1.0.1 → 1.1.0 (minor release)
-- 1.1.0 → 2.0.0 (major release)
+## Purpose
 
-## Scope Parameter
+Automate and standardise the release process to ensure consistent release quality, reduce manual effort, enforce standards, provide comprehensive validation, generate professional releases, maintain audit trails, and enable safe, repeatable workflows.
 
-Control version bumping with `--scope`:
+For complete detailed standards, see [automation.instructions.md](./automation.instructions.md#release-management) which contains comprehensive release management standards including:
 
-```bash
-node .github/agents/release.agent.js --scope=patch  # default
-node .github/agents/release.agent.js --scope=minor
-node .github/agents/release.agent.js --scope=major
-```
+- Two-phase release approach (Preparation + Execution)
+- Semantic versioning rules and version bumping
+- Changelog management (Keep a Changelog format, schema validation)
+- Pre-release preparation (Health scan, Alignment validation, Blocking issues)
+- Release execution (Readiness validation, Branch strategy, Version bump, Release PR, Tagging, GitHub Release)
+- Post-merge verification
+- Release labels strategy
+- Configuration and workflow setup
+- Best practices and guardrails
+- Rollback strategy
 
-# References
+## References
 
-- **Agent Spec**: [release.agent.md](../agents/release.agent.md)
-- **Release Process**: [docs/RELEASE_PROCESS.md](../../docs/RELEASE_PROCESS.md)
-- **Workflows**: [workflows/release.yml](../workflows/release.yml), [workflows/changelog.yml](../workflows/changelog.yml)
-- **Governance**: [AUTOMATION_GOVERNANCE.md](../../docs/AUTOMATION_GOVERNANCE.md)
-- **External**: [Semantic Versioning](https://semver.org/), [Keep a Changelog](https://keepachangelog.com/)
+- [automation.instructions.md](./automation.instructions.md) — Complete release standards
+- [release.agent.md](../agents/release.agent.md) — Release agent specification
+- [changelog.schema.json](../schemas/changelog.schema.json) — Changelog validation schema
+- [docs/RELEASE_PROCESS.md](../../docs/RELEASE_PROCESS.md) — Detailed release process
+- [Semantic Versioning](https://semver.org/)
+- [Keep a Changelog](https://keepachangelog.com/)

.jest.config.cjs

@@ -28,6 +28,7 @@ module.exports = {
     // Enable Babel to transform ES modules in scripts directory
     transformIgnorePatterns: [
         'node_modules/(?!(scripts|@actions)\/)',
+        '<rootDir>/scripts/agents/includes/sync-version.js',
     ],
     moduleNameMapper: {
         '^(\.{1,2}/.*)\.js$': '$1',