# Global Copilot Instructions – Portal People / NGauge

## Versioning & Release Workflow

All modules in this workspace follow the same release process.

### Version Format
- Semver with a `v` prefix: `v1.0.0`, `v1.0.13`, etc.
- Patch bump (`v1.0.x`) for fixes and minor features.
- Minor bump (`v1.x.0`) for new functionality.
- Major bump (`vx.0.0`) for breaking changes.

### Bumping the Version
When updating a version, always update **all occurrences** in `composer.json`:
```json
"version": "vX.Y.Z",
"extra": {
  "branch-alias": {
    "stable": "vX.Y.Z",
    "dev": "v1.0.x-dev"
  }
}
```
if module.xml file exists with a version number bump this to match composer version.

### Commit, Tag & Push
After updating `composer.json`, always run in this exact order:
```bash
git add -A
git commit -m "vX.Y.Z - <short description of change>"
git tag vX.Y.Z
git push
git push origin vX.Y.Z
```

Never tag before committing. Never push the tag in the same command as the branch push — always two separate `git push` calls.

### Amending a Release
If `composer.json` was missed from a commit:
```bash
git add composer.json
git commit --amend --no-edit
git tag -f vX.Y.Z
git push --force
git push origin vX.Y.Z --force
```

### Changelog Maintenance
When making changes to a project or module:
- Create or update `CHANGELOG.md` in the project root if it doesn't exist
- Follow [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format
- Structure entries under version headings with date: `## [vX.Y.Z] - YYYY-MM-DD`
- Categorize changes under: `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`
- Add entries to `[Unreleased]` section during development
- Move unreleased entries to the new version section when releasing
- Keep entries concise and user-focused (what changed, not how)

**Example:**
```markdown
# Changelog

## [Unreleased]

## [v1.0.1] - 2026-03-06
### Fixed
- Resolved null pointer exception in user authentication

### Added
- Support for custom email templates

## [v1.0.0] - 2026-03-01
### Added
- Initial release with core functionality
```

## Opening Folder/project
Look for and Read AI_Guideline.md

### External AI Guidance
When working on projects, also fetch and read external AI guidance documentation:
- Fetch the latest AI best practices guide from the specified URL
- Read and incorporate the guidance before making changes
- External guides may contain project-specific patterns, architecture decisions, and coding standards

**Example usage:**
```bash
# Fetch external guidance
curl -o /tmp/external-ai-guide.md https://example.com/path/to/ai-guidance.md

# Read the file before proceeding with changes
```

## Software Environment
The workspace uses the following core technologies and versions:
- **PHP**: 8.4+ minimum (8.5+ recommended for newer projects)
- **Composer**: v2
- **Yii2 Framework**: REQUIRED for all projects unless explicitly stated otherwise. Yii3 should be considered in planning for future migrations.
- **MySQL**: For database operations
- **Git**: For version control

### Required PHP Extensions
- `php-curl` - HTTP requests
- `php-zip` - Archive handling
- `php-gd` or `php-imagick` - Image processing
- `php-mbstring` - Multibyte string handling
- `php-xml` - XML parsing
- `php-intl` - Internationalization support

### Development Tools
- **PHPStan**: Static analysis (included in projects with phpstan.neon)
- **CodeCeption**: Testing framework (included in projects with codeception.yml)
- **Composer**: Dependency management

## System Commands
When running commands that modify system files, install packages, or require elevated privileges, always use `sudo`.

**Important:** Sudo commands must be run in a separate session. When a sudo command is needed:
1. Stop and provide the command with explanation of why it's needed
2. Prompt the user to confirm the command has been run (Y/N)
3. Wait for user confirmation before proceeding

## PHP Coding Preferences
When writing PHP code in this workspace, follow these conventions:
- Use curly braces `{}` for control structures instead of colon syntax (`:` and `endif`, `endfor`, `endforeach`, `endwhile`, etc.)
- Use short array syntax `[]` instead of `array()`

### Examples
**Preferred:**
```php
if ($condition) {
    // code
}

$items = ['a', 'b', 'c'];
```

**Avoid:**
```php
if ($condition):
    // code
endif;

$items = array('a', 'b', 'c');
```

## Code Compatibility
Always prioritize writing code with the highest compatibility in mind while being aware of modern best practices:
- Check project's PHP version requirements in `composer.json` before using newer PHP features
- When using functions or features that require specific versions, add a comment noting the minimum required version
- Example: `// Requires PHP 7.4+ for arrow functions` or `// Requires Yii 2.0.40+ for this feature`
- Prefer backwards-compatible solutions unless newer features provide significant benefits
- When suggesting modern alternatives, mention the version requirements

## Project Context
When working in a specific project folder (ahs-hub, InlineTrack, NGauge_Base, etc.):
- Always check for and read any `AI_Guideline.md` or `README.md` files first
- Understand project-specific conventions and architecture before making changes
- Review existing code patterns in the project to maintain consistency

## Yii2 Framework Conventions
Many projects in this workspace use Yii2. Follow these conventions:
- Use Yii2's dependency injection via constructors or `Yii::$app->get()`
- Follow Yii2 naming conventions for controllers (e.g., `SiteController`, `actionIndex`)
- Use migrations for database schema changes (`./yii migrate/create`)
- Leverage ActiveRecord for database interactions
- Follow Yii2's MVC architecture strictly

## Code Quality & Testing
- Run PHPStan analysis before committing when `phpstan.neon` exists in the project
- Write or update tests when modifying critical business logic
- Use CodeCeption for testing in projects that have `codeception.yml`
- Ensure all code changes maintain or improve existing quality standards

## Module Development (NGauge_modules)
When working with modules in `NGauge_modules/`:
- Each module should have its own `composer.json` with version
- Follow the same versioning and release workflow as main projects
- Ensure modules are decoupled and follow single responsibility principle
- Test module integration with the main application

### Module Environments
Different modules use different technology stacks:
- `NGauge_modules/netsuite-sharepoint`: SuiteScript/JavaScript
- `NGauge_modules/ahs-netsuite`: PHP 8.x, Yii2
- Most other modules: PHP 8.x, Yii2 (default stack)

Always check the module's specific requirements before making changes.

### Creating a New Module
To create a new module, gather the following information:
- **name**: Display name of the module
- **reponame**: Repository name (lowercase, hyphenated)

**Workflow:**
1. Create repository in Azure DevOps:
   - Organization: `PortalPeopleUK`
   - Project: `NGauge_Modules`
   - Repository URL: `https://dev.azure.com/PortalPeopleUK/NGauge_Modules/_git/{reponame}`

2. Use Azure CLI to create and clone:
   ```bash
   # Create repository using az client
   az repos create --name {reponame} --project NGauge_Modules --organization https://dev.azure.com/PortalPeopleUK/
   
   # Clone into NGauge_modules directory
   cd NGauge_modules
   git clone https://dev.azure.com/PortalPeopleUK/NGauge_Modules/_git/{reponame}
   ```

3. Initialize module structure with `composer.json`, versioning, and required files

## Commit Messages
For non-version commits, use conventional commits format:
- Format: `type(scope): description`
- Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`
- Include ticket/issue references when applicable
- Examples:
  - `feat(users): add password reset functionality`
  - `fix(api): resolve null pointer in user endpoint`
  - `docs(readme): update installation instructions`

## Security Best Practices
- Never commit sensitive credentials, API keys, or passwords
- Use environment variables for configuration (`.env` files)
- Sanitize all user inputs and use parameterized queries
- Review all file upload functionality for security vulnerabilities
- Follow OWASP security guidelines for web applications
- Use HTTPS for all external API communications

## Azure DevOps MCP Server
- Default context: `organization=PortalPeopleUK`, `project=ngauge_modules`.
- Tool naming: use only underscore-style `mcp_ado_*` tools.
- Always enable `core` domain tools first for project/team/identity lookup.
- Domain filters to use: `core`, `work`, `work-items`, `repositories`, `pipelines`, `wiki`, `search`, `test-plans`, `advanced-security`.

**Available MCP Tools**
- **Core**: `mcp_ado_core_list_projects`, `mcp_ado_core_list_project_teams`, `mcp_ado_core_get_identity_ids`.
- **Work Items**: `mcp_ado_wit_get_work_item`, `mcp_ado_wit_get_work_items_batch_by_ids`, `mcp_ado_wit_create_work_item`, `mcp_ado_wit_update_work_item`, `mcp_ado_wit_update_work_items_batch`.
  `mcp_ado_wit_add_child_work_items`, `mcp_ado_wit_work_items_link`, `mcp_ado_wit_work_item_unlink`, `mcp_ado_wit_add_artifact_link`, `mcp_ado_wit_link_work_item_to_pull_request`.
  `mcp_ado_wit_list_work_item_comments`, `mcp_ado_wit_add_work_item_comment`, `mcp_ado_wit_list_work_item_revisions`, `mcp_ado_wit_get_work_item_type`, `mcp_ado_wit_my_work_items`.
  `mcp_ado_wit_get_work_items_for_iteration`, `mcp_ado_wit_list_backlogs`, `mcp_ado_wit_list_backlog_work_items`, `mcp_ado_wit_get_query`, `mcp_ado_wit_get_query_results_by_id`.
- **Work/Iterations**: `mcp_ado_work_list_iterations`, `mcp_ado_work_create_iterations`, `mcp_ado_work_list_team_iterations`, `mcp_ado_work_assign_iterations`, `mcp_ado_work_get_iteration_capacities`, `mcp_ado_work_get_team_capacity`, `mcp_ado_work_update_team_capacity`.
- **Repositories**: `mcp_ado_repo_list_repos_by_project`, `mcp_ado_repo_get_repo_by_name_or_id`, `mcp_ado_repo_list_branches_by_repo`, `mcp_ado_repo_list_my_branches_by_repo`, `mcp_ado_repo_get_branch_by_name`, `mcp_ado_repo_create_branch`.
  `mcp_ado_repo_search_commits`, `mcp_ado_repo_list_pull_requests_by_repo_or_project`, `mcp_ado_repo_list_pull_requests_by_commits`, `mcp_ado_repo_get_pull_request_by_id`, `mcp_ado_repo_create_pull_request`, `mcp_ado_repo_update_pull_request`, `mcp_ado_repo_update_pull_request_reviewers`.
  `mcp_ado_repo_list_pull_request_threads`, `mcp_ado_repo_list_pull_request_thread_comments`, `mcp_ado_repo_create_pull_request_thread`, `mcp_ado_repo_reply_to_comment`, `mcp_ado_repo_resolve_comment`.
- **Pipelines**: `mcp_ado_pipelines_create_pipeline`, `mcp_ado_pipelines_get_builds`, `mcp_ado_pipelines_get_build_status`, `mcp_ado_pipelines_get_build_log`, `mcp_ado_pipelines_get_build_log_by_id`, `mcp_ado_pipelines_get_build_changes`, `mcp_ado_pipelines_get_build_definitions`, `mcp_ado_pipelines_get_build_definition_revisions`, `mcp_ado_pipelines_run_pipeline`, `mcp_ado_pipelines_get_run`, `mcp_ado_pipelines_list_runs`, `mcp_ado_pipelines_update_build_stage`.
- **Wiki**: `mcp_ado_wiki_list_wikis`, `mcp_ado_wiki_get_wiki`, `mcp_ado_wiki_list_pages`, `mcp_ado_wiki_get_page`, `mcp_ado_wiki_get_page_content`, `mcp_ado_wiki_create_or_update_page`.
- **Search**: `mcp_ado_search_code`, `mcp_ado_search_wiki`, `mcp_ado_search_workitem`.
- **Test Plans**: `mcp_ado_testplan_list_test_plans`, `mcp_ado_testplan_create_test_plan`, `mcp_ado_testplan_list_test_suites`, `mcp_ado_testplan_create_test_suite`, `mcp_ado_testplan_add_test_cases_to_suite`, `mcp_ado_testplan_list_test_cases`, `mcp_ado_testplan_create_test_case`, `mcp_ado_testplan_update_test_case_steps`, `mcp_ado_testplan_show_test_results_from_build_id`.
- **Advanced Security**: `mcp_ado_advsec_get_alerts`, `mcp_ado_advsec_get_alert_details`.

**Essential Workflows (PortalPeopleUK/ngauge_modules)**
- Always call `mcp_ado_wit_my_work_items` before starting new work.
- Before `mcp_ado_wit_create_work_item`, first run `mcp_ado_search_workitem` or `mcp_ado_wit_get_query_results_by_id`.
- For feature work, run `mcp_ado_search_code` and `mcp_ado_search_wiki` before implementation.
- Include work item IDs in branch names, commit messages, and PR descriptions.
- Use `mcp_ado_wit_add_artifact_link` for traceability with `linkType="Branch"`, `linkType="Fixed in Commit"`, `linkType="Pull Request"`, `linkType="Build"`.

**Tool Call Patterns**
- **Example 1: Search before creating work items**
  1. Call `mcp_ado_search_workitem` (or `mcp_ado_wit_get_query_results_by_id`) in `PortalPeopleUK/ngauge_modules`.
  2. Review results and avoid duplicate creation.
  3. If needed, call `mcp_ado_wit_create_work_item` with project and `workItemType`.
- **Example 2: Feature branch workflow with work item linkage**
  1. Call `mcp_ado_repo_create_branch` with `branchName="feature/[workItemId]-description"`.
  2. Call `mcp_ado_wit_add_artifact_link` with `linkType="Branch"` for that work item.
  3. Create PR via `mcp_ado_repo_create_pull_request` and include work item ID in PR text.
  4. Call `mcp_ado_wit_add_artifact_link` with `linkType="Pull Request"`; add `Fixed in Commit` and `Build` links as work progresses.
- **Example 3: Find and document solutions**
  1. Call `mcp_ado_search_code` or `mcp_ado_search_wiki` to find existing ngauge_modules patterns.
  2. If missing, call `mcp_ado_wiki_create_or_update_page` to document the solution.
  3. Link the wiki artifact back to the related work item for reuse.
**Mermaid Diagram Standards**
When creating or updating Mermaid diagrams in this workspace, follow these standards:
Apply mermaid stanards to all diagrams in the workspace, following the guidelines for flowchart structure, styling, and metadata.
from .github/MERMAID_DIAGRAM_STANDARDS.md, and ensure all diagrams are updated to match these standards.