🚀 Project Sync

Project Sync is a high-performance GitHub Projects v2 automation engine designed to synchronize issues and pull requests across complex, multi-repository organizations with 100% predictability.

✨ Overview

This tool transforms your GitHub Project into a self-driving productivity engine. It eliminates manual board maintenance by implementing a rule-based state machine for:

• Intelligent Intake: Automatically adds PRs and issues to the project board based on authorship, assignment, or repository source.
• Dynamic Workflows: Moves items between columns (e.g., New → Active) based on real-time state changes.
• Sprint Orchestration: Seamlessly manages sprint assignments and rollovers.
• Smart Inheritance: Propagates PR metadata (assignees, sprints, columns) to linked issues.
• Multi-Org Mastery: Monitors activity across bcgov, bcgov-c, and bcgov-nr simultaneously.

🛡️ Stability & Predictability

We treat stability as a first-class feature. Our "Ludicrous Testing" philosophy ensures that every rule processed is verified against a comprehensive matrix of conditions.

• Hardcoded Validation: We use a strict whitelist-based validator to ensure rule evaluation is 100% predictable and secure against code injection.
• Native Efficiency: Built on Node.js 24 and native ES Modules for lightning-fast, future-proof execution.
• Zero-Network Tests: Our 240+ count test suite runs in pure isolation, guaranteeing that the core logic is bulletproof without ever making a real API call.
• Strict Environments: We enforce Node versions via .npmrc to ensure that every developer and CI runner is perfectly aligned.

📋 Visibility & Auditing

Designed for transparency. Every run provides:

• GitHub Actions Job Summary: A premium Markdown report generated in the Action's summary tab.
• Audit Logs: Detailed console output with a [AUDIT] prefix for all state transitions.
• Precision Metrics: Real-time counters for processed, added, and skipped items.

⚙️ Configuration

Configure your entire workflow in a single, version-controlled rules.yml file.

Project Connection

The tool resolves your project identity with minimal friction:

project:
  url: https://github.com/orgs/bcgov/projects/16
  # Organization and ID are automatically resolved from the URL

Resource Monitoring

Define which realms the engine should govern:

project:
  allowedOrgs:
    - bcgov
    - bcgov-c
    - bcgov-nr

🛠️ Development & Specs

This project follows a Spec-Driven Development model using the SpecKit framework.

• SpecKit Architecture: Documentation for our feature specifications lives in the specs/ directory. See the SpecKit README for usage guidelines.
• Rule Engine Spec: See Spec 004 for a deep dive into our validation architecture.
• Project Constitution: Review memory/constitution.md for our core development principles and "Ludicrous Testing" standards.
• AI Pair Programming: See .github/copilot-instructions.md for guidance when working with AI coding assistants.

🧪 Testing

We value exhaustive verification. Run the full suite, including the ludicrous coverage matrix:

npm test

For targeted testing of the core engines:

# Test the unified rule processor
npm test -- test/processors/unified-rule-processor.test.js

# Test the ludicrous validation matrix
npm test -- test/processors/ludicrous-coverage.test.js

---

Built with ❤️ by the Advanced Project Automation Team.