Issue #35: Add scope markers to all instruction files (Phase 2)

instructions/a11y.instructions.md

@@ -1,4 +1,8 @@
 ---
+file_type: "instructions"
+title: "Accessibility Instructions"
 description: "Guidance for creating more accessible code"
+scope: "organization-wide"
+status: "active"
 applyTo: "**"
 ---

instructions/agent-spec.instructions.md

@@ -2,6 +2,7 @@
 file_type: "instructions"
 title: "Agent Specification Instructions"
 description: "How to design, write, and review LightSpeed Copilot agent specification files."
+scope: "repo-local"
 version: "v1.0"
 last_updated: "2025-12-11"
 owners: ["GitHub Community Health Team"]

instructions/automation.instructions.md

@@ -2,6 +2,7 @@
 file_type: "instructions"
 title: "Automation Standards"
 description: "Comprehensive standards for GitHub automation agents, workflows, and repository health management"
+scope: "repo-local"
 version: "v1.0"
 last_updated: "2025-12-07"
 owners: ["GitHub Community Health Team"]

instructions/coding-standards.instructions.md

@@ -1,11 +1,14 @@
 ---
 file_type: "instructions"
+title: "Coding Standards"
 description: "Unified coding standards for all LightSpeedWP projects: applies to all code, documentation, automation, and AI contributions."
+scope: "organization-wide"
 applyTo: "**"
 version: "v2.1"
 last_updated: "2025-12-04"
 owners: ["LightSpeedWP Team"]
 tags: ["coding-standards", "governance", "automation", "docs", "lint", "ai"]
+status: "active"
 ---
 
 # LightSpeedWP Coding Standards — Canonical Reference
@@ -104,3 +107,11 @@ All documentation links to files within the same repository should use `/blob/HE
 - See [LightSpeed Copilot Prompts Index](../.github/prompts/prompts.md) for reusable prompts.
 
 ---
+
+## Related Files
+
+- **[linting.instructions.md](./linting.instructions.md)** — Tool-specific linting rules and configurations
+- **[languages.instructions.md](./languages.instructions.md)** — Language-specific coding standards and formatting
+- **[quality-assurance.instructions.md](./quality-assurance.instructions.md)** — Testing and QA standards
+
+---

instructions/community-standards.instructions.md

@@ -2,6 +2,7 @@
 file_type: "instructions"
 title: "Community Standards"
 description: "Community health standards: naming conventions, README expectations, saved replies, and shared assets. File placement lives in file-organisation.instructions.md."
+scope: "organization-wide"
 version: "v1.0"
 last_updated: "2025-12-07"
 owners: ["GitHub Community Health Team"]

instructions/copilot-operations.instructions.md

@@ -1,5 +1,8 @@
 ---
-applyTo: "**"
+file_type: "instructions"
+title: "Copilot Operations"
 description: "Unified Copilot operating guide: behaviour guardrails and process logging with correct file placement."
+scope: "repo-local"
+applyTo: "**"
 status: "active"
 ---

instructions/docs.instructions.md

@@ -2,6 +2,7 @@
 file_type: "instructions"
 title: "Documentation Instructions"
 description: "Universal documentation standards for Markdown files in this repository unless overridden by more specific guidance."
+scope: "repo-local"
 applyTo: "**/*.md"
 ---
 

instructions/documentation-formats.instructions.md

@@ -2,6 +2,7 @@
 file_type: "instructions"
 title: "Documentation Formats Standards"
 description: "Unified standards for Markdown, YAML frontmatter, and Mermaid diagrams across all GitHub community health documentation"
+scope: "organization-wide"
 version: "v1.1.1"
 last_updated: "2026-05-28"
 owners: ["GitHub Community Health Team"]
@@ -601,3 +602,12 @@ jobs:
 - All checks required before merge
 
 ---
+
+## Related Files
+
+- **[coding-standards.instructions.md](./coding-standards.instructions.md)** — Code quality standards referenced in documentation
+- **[issues.instructions.md](./issues.instructions.md)** — Issue documentation and templates
+- **[pull-requests.instructions.md](./pull-requests.instructions.md)** — PR documentation and templates
+- **[community-standards.instructions.md](./community-standards.instructions.md)** — Community health documentation standards
+
+---

instructions/file-organisation.instructions.md

@@ -1,5 +1,8 @@
 ---
-applyTo: "**"
+file_type: "instructions"
+title: "File Organisation"
 description: "Portable file organisation rules for GitHub-native governance files, portable AI assets, project artefacts, reports, and temporary outputs."
+scope: "repo-local"
+applyTo: "**"
 status: "active"
 ---

instructions/hooks.instructions.md

@@ -1,4 +1,72 @@
 ---
-description: "Guidelines for authoring portable guardrail hooks with explicit inputs, outputs, and safety outcomes."
-applyTo: "hooks/**"
+file_type: "instructions"
+title: "Hook File Instructions"
+description: "Guidelines for authoring portable guardrail hooks with explicit inputs, outputs, and safety outcomes"
+scope: "repo-local"
+version: "v1.0"
+last_updated: "2026-05-29"
+owners: ["LightSpeed Team"]
+tags: ["hooks", "guardrails", "safety", "automation", "validation"]
+applyTo: ["hooks/**/*.md"]
+status: "active"
+---
+
+# LightSpeed Hook File Instructions
+
+Create reusable, safety-focused hooks for pre-commit, CI/CD, and automation workflows. Hooks must have explicit guardrails and clear documentation.
+
+## General Rules
+
+- Hook files are stored in `hooks/` at repository root
+- Each hook must have a clear purpose and trigger condition
+- Document all inputs, outputs, and side effects explicitly
+- Include safety constraints and guardrails upfront
+- Test hooks locally before committing
+- Use descriptive file names (e.g., `validate-commit-message.md`)
+
+## Hook Frontmatter
+
+- `title` — Descriptive name of the hook
+- `description` — What it validates or enforces
+- `version` — Semantic version
+- `scope` — "organization-wide" (for reusable hooks) or "repo-local"
+- `trigger` — When hook runs (pre-commit, pre-push, CI, etc.)
+- `exit_code` — Success (0) and failure codes
+- `tags` — Searchable keywords
+
+## Hook Structure
+
+1. **Purpose** — What safety risk or validation this hook addresses
+2. **Trigger** — When and how the hook executes
+3. **Input** — What data/files the hook receives
+4. **Validation Rules** — Specific checks performed
+5. **Output** — Success/failure messages
+6. **Guardrails** — Constraints and limitations
+7. **Examples** — Sample passing and failing cases
+
+## Safety Requirements
+
+All hooks must:
+
+- Fail safely (err on the side of caution)
+- Have clear error messages
+- Not require user secrets or credentials
+- Be reversible or non-destructive
+- Document any system changes
+- Include rollback instructions if applicable
+
+## Testing Hooks
+
+- Test locally with various file types and edge cases
+- Verify exit codes match documentation
+- Ensure error messages are helpful
+- Test on both success and failure paths
+
+---
+
+## Related Files
+
+- [automation.instructions.md](./automation.instructions.md) — Automation standards and workflow integration
+- [coding-standards.instructions.md](./coding-standards.instructions.md) — Code quality standards hooks enforce
+
 ---

instructions/instructions.instructions.md

@@ -1,8 +1,11 @@
 ---
+file_type: "instructions"
+title: "Instructions"
 description: "Guidelines for writing Copilot instruction files in the LightSpeed .github community health repository"
+scope: "repo-local"
+version: "v1.0"
+last_updated: "2025-12-11"
 applyTo: "**/.github/instructions/*.instructions.md"
-version: 1.0
-lastUpdated: 2025-12-11
 ---
 
 # LightSpeed Organisation GitHub Instruction Authoring

instructions/issues.instructions.md

@@ -2,6 +2,7 @@
 file_type: "instructions"
 title: "Issue Creation Instructions"
 description: "Canonical instructions for creating, labeling, and managing Issues in LightSpeedWP projects. Reference for templates, types, automation, and labeling strategy."
+scope: "organization-wide"
 version: "1.2"
 last_updated: "2026-05-28"
 owners: ["lightspeedwp/maintainers"]
@@ -235,3 +236,11 @@ See [Issue Creation Guide](../docs/ISSUE_CREATION_GUIDE.md) for details.
 - Use the correct template and title prefix (`bug:`, `feature:`, etc.) to ensure type detection and correct automation.
 
 ---
+
+## Related Files
+
+- **[pull-requests.instructions.md](./pull-requests.instructions.md)** — Companion guide for PR creation and labeling; mirrors issue workflow patterns
+- **[labeling.instructions.md](./labeling.instructions.md)** — Detailed label naming conventions and one-hot rules
+- **[coding-standards.instructions.md](./coding-standards.instructions.md)** — Code quality standards referenced in issue templates
+
+---

instructions/labeling.instructions.md

@@ -1,4 +1,86 @@
 ---
-applyTo: "**"
-description: "Canonical instructions for the unified labeling automation system. Describes mission, strategy, configuration, and best practices for label management across issues, PRs, and discussions."
+file_type: "instructions"
+title: "Labeling Instructions"
+description: "Canonical instructions for the unified labeling automation system. Describes mission, strategy, configuration, and best practices for label management across issues, PRs, and discussions"
+scope: "repo-local"
+version: "v1.0"
+last_updated: "2026-05-29"
+owners: ["LightSpeed Team"]
+tags: ["labels", "automation", "triage", "metadata", "governance"]
+applyTo: ["**/*.md", ".github/workflows/labeling.yml", "scripts/agents/labeling.agent.js"]
+status: "active"
+---
+
+# LightSpeed Labeling Instructions
+
+Unified labeling strategy for organizing and automating GitHub issues, PRs, and discussions. Labels support triage, routing, and workflow automation.
+
+## Labeling Philosophy
+
+- **One-hot principle**: Only one value per label group (e.g., one `priority:*`, one `status:*`)
+- **Automation-first**: Labels trigger workflows and project updates
+- **Discoverability**: Labels enable search and filtering
+- **Governance**: Labels enforce quality gates and routing rules
+
+## Label Categories
+
+### Status Labels (`status:*`)
+
+- `status:needs-triage` — New, not yet reviewed
+- `status:ready` — Clear requirements, ready to work
+- `status:in-progress` — Someone is actively working
+- `status:needs-review` — Waiting for review/approval
+- `status:blocked` — Blocked by another issue/PR
+- `status:done` — Completed and closed
+
+**Rule:** Each issue/PR has exactly one `status:*` label
+
+### Priority Labels (`priority:*`)
+
+- `priority:urgent` — Security, critical bug, or blocker
+- `priority:high` — High-impact, affecting multiple users
+- `priority:normal` — Standard feature or improvement
+- `priority:low` — Nice-to-have, deferred work
+
+**Rule:** Each issue has exactly one `priority:*` label (PRs inherit from linked issue)
+
+### Type Labels (`type:*`)
+
+- `type:bug` — Unexpected behavior or error
+- `type:feature` — New functionality
+- `type:chore` — Maintenance, cleanup, tooling
+- `type:docs` — Documentation improvements
+- `type:refactor` — Code quality, no behavior change
+
+### Area Labels (`area:*`)
+
+Examples: `area:ci`, `area:documentation`, `area:a11y`, `area:performance`
+
+Indicates which system or domain the issue affects.
+
+## Automation Rules
+
+- Labels trigger workflows via `labeling.agent.js`
+- Status changes update project board automatically
+- Priority labels route issues to appropriate teams
+- Type labels filter by issue category
+
+## Creating New Labels
+
+Before creating a label:
+
+1. Check if an existing label covers the need
+2. Propose in an issue with rationale
+3. Get approval from governance team
+4. Update this documentation
+5. Add to `.github/labels.json`
+
+---
+
+## Related Files
+
+- [issues.instructions.md](./issues.instructions.md) — Issue creation and labeling standards
+- [pull-requests.instructions.md](./pull-requests.instructions.md) — PR creation and labeling standards
+- [automation.instructions.md](./automation.instructions.md) — Automation and workflow integration
+
 ---

instructions/languages.instructions.md

@@ -2,6 +2,7 @@
 file_type: "instructions"
 title: "Programming Languages Standards"
 description: "Unified linting, formatting, and documentation standards for JavaScript, TypeScript, JSON, and YAML across all GitHub repositories"
+scope: "organization-wide"
 version: "v1.0"
 last_updated: "2025-12-07"
 owners: ["GitHub Community Health Team"]
@@ -424,3 +425,11 @@ jobs:
 ```
 
 ---
+
+## Related Files
+
+- **[coding-standards.instructions.md](./coding-standards.instructions.md)** — General coding standards applicable across all languages
+- **[linting.instructions.md](./linting.instructions.md)** — Tool-specific linting configurations and rules
+- **[quality-assurance.instructions.md](./quality-assurance.instructions.md)** — Testing and code quality standards
+
+---

instructions/linting.instructions.md

@@ -1,6 +1,8 @@
 ---
 file_type: "instructions"
+title: "Linting Instructions"
 description: "Master index for all linting instructions in the LightSpeed organisation. Lists and cross-references all linting instructions, config, and coding standards."
+scope: "organization-wide"
 applyTo: "**/*.{js,ts,php,css,scss,sass,html,json,md,yml,yaml,py,sh}"
 version: "v2.0"
 last_updated: "2025-11-27"
@@ -185,3 +187,11 @@ Linting instructions should evolve with our standards and requirements. When upd
 4. Document significant changes in the commit message.
 
 ---
+
+## Related Files
+
+- **[coding-standards.instructions.md](./coding-standards.instructions.md)** — General coding standards that linting tools enforce
+- **[languages.instructions.md](./languages.instructions.md)** — Language-specific linting configurations and rules
+- **[quality-assurance.instructions.md](./quality-assurance.instructions.md)** — Testing standards that complement linting
+
+---