Wave 5 Phase 3: Complete extended README audit

.github/projects/README.md

@@ -1,158 +1,97 @@
 ---
 file_type: "documentation"
-title: "Reports Directory"
-description: "An overview of the reports directory, detailing the purpose of each subfolder for storing generated artifacts."
+title: "Projects Directory"
+description: "Task tracking files, project planning documents, implementation roadmaps, and progress tracking for active and completed projects."
 version: "1.1"
-last_updated: "2026-05-29"
+last_updated: "2026-05-31"
 owners: ["LightSpeed Engineering"]
-tags: ["reports", "documentation", "governance"]
+tags: ["projects", "documentation", "governance"]
 ---
+
 # Projects Directory
 
 This directory contains all task tracking files, project planning documents, implementation roadmaps, and progress tracking.
 
-# 📂 Reports Directory
-
 ## Purpose
 
-This directory stores all automated and manually generated reports. Each subfolder is dedicated to a specific category of report to ensure clear organization and easy retrieval of information.
-
-- Store all project planning and tracking files
-- Centralize task lists and implementation plans
-- Maintain organized project documentation
-For detailed guidelines on report generation, naming conventions, and storage, please refer to the [**Reporting Instructions**](../instructions/reporting.instructions.md).
+Centralize and organise all project-related files, from early planning through completion. Each subdirectory serves a specific lifecycle phase.
 
 ## Directory Structure
 
-## Report Categories
-
 ```
-projects/
-├── active/          # Current active projects and sprints
-├── completed/       # Finished project archives
-├── planning/        # Planning and scoping documents
-└── ADR/             # Architecture Decision Records (optional)
+.github/projects/
+├── active/       # Current active projects and ongoing work
+├── archived/     # Archived projects and historical records
+├── completed/    # Finished projects ready for reference
+└── PLANNING_TEMPLATE.md  # Template for starting new projects
 ```
 
-The following diagram and table provide an overview of the available report categories and their intended purpose.
-
-### Subdirectory Purposes
-
-```mermaid
-graph TD
-    A[📂 .github/reports] --> B[🤖 Agents]
-    A --> C[🔬 Analysis]
-    A --> D[🛡️ Audits]
-    A --> E[📊 Coverage]
-    A --> F[📄 Frontmatter]
-    A --> G[🚀 Implementation]
-    A --> H[📈 Issue Metrics]
-    A --> I[🏷️ Labeling]
-    A --> J[🧹 Linting]
-    A --> K[✨ Meta]
-    A --> L[📈 Metrics]
-    A --> M[🚚 Migration]
-    A --> N[⚡ Optimisation]
-    A --> O[🛠️ Tech Debt]
-    A --> P[✅ Validation]
-
-**`active/`** - Current Active Projects
-    subgraph "Report Categories"
-        B
-        C
-        D
-        E
-        F
-        G
-        H
-        I
-        J
-        K
-        L
-        M
-        N
-        O
-        P
-    end
+## Subdirectory Purposes
+
+### `active/` – Current Active Projects
 
 - Work-in-progress project files
 - Active sprint plans and task tracking
 - Current implementation roadmaps
 - Files actively being updated and referenced
-- Move files here when work begins
+- **Move files here** when a project transitions from planning to active development
 
-**`completed/`** - Finished Project Archives
+### `completed/` – Finished Project Archives
 
 - Completed project documentation for reference
 - Archived task lists from finished initiatives
 - Historical planning documents
 - Successfully implemented project records
-- Move files here when projects are fully complete
+- **Move files here** when all tasks are done, PRs merged, and objectives achieved
 
-**When to Move Files:**
+### `archived/` – Long-term Archives
 
-- **To `active/`**: When a project moves from planning to active development
-- **To `completed/`**: When all tasks are done, PRs merged, and objectives achieved
-- **Root level**: Use for cross-project files or files that span multiple phases
+- Projects superseded by newer initiatives
+- Deprecated planning documents
+- Historical reference materials
+- Files preserved for audit trails
 
 ## File Naming Convention
 
-Use descriptive project names:
+Use descriptive project names with type indicators:
 
-    style A fill:#e1f5fe,stroke:#333,stroke-width:2px
 ```
-
 {project-name}-{type}.md
+```
 
 Examples:
-context-reduction-tasks.md
-instruction-consolidation-guide.md
-labeling-system-roadmap.md
-phase6-planning-suite-consolidation.md
 
-```
-| Category | Purpose |
-| :--- | :--- |
-| **/agents** | Logs and outputs from AI agent executions. |
-| **/analysis** | In-depth analysis of code, architecture, or processes. |
-| **/audits** | One-time audit reports for security, accessibility, or compliance. |
-| **/coverage** | Code coverage reports generated from test runs. |
-| **/frontmatter** | Reports from frontmatter validation and audit scripts. |
-| **/implementation** | Tracking reports for the implementation of features or epics. |
-| **/issue-metrics** | Metrics related to GitHub issues (e.g., time to close, label distribution). |
-| **/labeling** | Reports from the automated labeling agent. |
-| **/linting** | Reports from code linters (ESLint, Stylelint, etc.). |
-| **/meta** | Reports from the meta agent, which manages badges, footers, and other metadata. |
-| **/metrics** | General repository and developer workflow metrics. |
-| **/migration** | Reports related to data, schema, or platform migrations. |
-| **/optimisation** | Reports on performance and resource optimisation efforts. |
-| **/tech-debt** | Reports tracking identified technical debt. |
-| **/validation** | Reports from validation scripts (e.g., schema validation, link checking). |
+- `context-reduction-tasks.md`
+- `instruction-consolidation-guide.md`
+- `labeling-system-roadmap.md`
+- `phase-6-planning.md`
 
 ## Guidelines
 
 ✅ **DO:**
 
-- Create all task tracking files in this directory
+- Create all project tracking files in this directory
 - Use descriptive project names
-- Include frontmatter for metadata (created_date, status, etc.)
+- Include frontmatter for metadata (created_date, status, owners, etc.)
 - Update files as work progresses
-- Start new projects at root level or in `planning/`
+- Start new projects at the root level of `.github/projects/`
 - Move to `active/` when work begins
-- Move completed projects to `completed/` subdirectory
+- Move completed projects to `completed/` when finished
 - Add completion date to frontmatter when archiving
 
 ❌ **DON'T:**
 
-- Create task files in repository root
-- Create task files in `docs/` folder
-- Create task files in `.github/agents/` or `.github/instructions/`
+- Create project files in repository root
+- Create project files in `docs/` folder
+- Create project files in `.github/agents/` or `.github/instructions/`
 - Use generic names like `tasks.md` or `todo.md`
+- Leave projects in `active/` after completion
 
 ## Current Projects
 
-- [context-reduction-tasks.md](./context-reduction-tasks.md) - Token optimization task tracking
-- [instruction-consolidation-guide.md](./instruction-consolidation-guide.md) - File consolidation migration guide
+- [context-reduction-tasks.md](./context-reduction-tasks.md) – Token optimisation task tracking
+- [instruction-consolidation-guide.md](./instruction-consolidation-guide.md) – File consolidation migration guide
+- [PLANNING_TEMPLATE.md](./PLANNING_TEMPLATE.md) – Template for new project planning
 
 ## Related Documentation
 
@@ -163,8 +102,5 @@ phase6-planning-suite-consolidation.md
 ---
 
 *For questions about project file organisation, see [file-organisation.instructions.md](../instructions/file-organisation.instructions.md)*
-*This directory is managed by automated workflows. Please do not add files manually unless specified by the reporting instructions.*
-
-_Docs signed by 🤖 Copilot for LightSpeedWP – always fresh!_
 
-_Docs signed by 🤖 Copilot for LightSpeedWP – always fresh!_
+*Docs signed by 🤖 Copilot for LightSpeedWP – always fresh!*

.github/reports/README.md

@@ -1,3 +1,15 @@
+---
+file_type: "documentation"
+title: "Reports Directory"
+description: "Central repository for generated reports, analysis outputs, audit files, and agent execution summaries"
+version: "v1.0.0"
+created_date: "2026-01-01"
+last_updated: "2026-05-31"
+maintainer: "LightSpeed Team"
+tags: ["reports", "audits", "metrics", "analysis"]
+status: "active"
+---
+
 # Reports Directory
 
 <!-- BADGES-START -->
@@ -255,6 +267,3 @@ progress/weekly-summary-2025-w50.md
 
 *Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP*
 [Contact](https://lightspeedwp.agency/contact)
-
-*Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP*
-[Contact](https://lightspeedwp.agency/contact)

hooks/secrets-scanner/README.md

@@ -1,14 +1,11 @@
 ---
 file_type: "documentation"
-title: "secrets-scanner hook"
+title: "secrets-scanner Hook"
 description: "Scans changed files for likely secrets before commit or release workflows."
 version: "v0.1.0"
-last_updated: "2026-05-28"
+last_updated: "2026-05-31"
 owners: ["LightSpeedWP Team"]
 ---
 
 *Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP*
 [Contact](https://lightspeedwp.agency/contact)
-
-*Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP*
-[Contact](https://lightspeedwp.agency/contact)

hooks/session-logger/README.md

@@ -1,15 +1,11 @@
 ---
-file_type: documentation
-title: session-logger hook
-description: Captures structured session activity events for audit and troubleshooting.
-version: v0.1.0
-last_updated: '2026-05-28'
-owners:
-- LightSpeedWP Team
+file_type: "documentation"
+title: "session-logger Hook"
+description: "Captures structured session activity events for audit and troubleshooting."
+version: "v0.1.0"
+last_updated: "2026-05-31"
+owners: ["LightSpeedWP Team"]
 ---
 
 *Built by 🧱 LightSpeedWP with ☕, 🚀, and open-source spirit!*
 [Contributors](https://github.com/lightspeedwp/lsx-demo-theme/graphs/contributors)
-
-*Built by 🧱 LightSpeedWP with ☕, 🚀, and open-source spirit!*
-[Contributors](https://github.com/lightspeedwp/lsx-demo-theme/graphs/contributors)

hooks/tool-guardian/README.md

@@ -1,15 +1,11 @@
 ---
-file_type: documentation
-title: tool-guardian hook
-description: Prevents unsafe or disallowed tool operations based on configured guardrails.
-version: v0.1.0
-last_updated: '2026-05-28'
-owners:
-- LightSpeedWP Team
+file_type: "documentation"
+title: "tool-guardian Hook"
+description: "Prevents unsafe or disallowed tool operations based on configured guardrails."
+version: "v0.1.0"
+last_updated: "2026-05-31"
+owners: ["LightSpeedWP Team"]
 ---
 
 *Maintained with ❤️ by the 🚀 LightSpeedWP Automation Team*
 [Org Profile](https://github.com/lightspeedwp/.github/tree/main/profile)
-
-*Maintained with ❤️ by the 🚀 LightSpeedWP Automation Team*
-[Org Profile](https://github.com/lightspeedwp/.github/tree/main/profile)

instructions/README.md

@@ -1,20 +1,15 @@
 ---
-authors:
-- LightSpeed Team
-description: Ownership index for portable instruction files covering standards, best practices, and governance across LightSpeed projects.
-domain: governance
-file_type: documentation
-last_updated: '2026-05-31'
-license: GPL-3.0
-maintainer: LightSpeed Team
-stability: stable
-tags:
-- instructions
-- standards
-- documentation
-- governance
-title: Portable Instructions & Standards
-version: v0.3.2
+file_type: "documentation"
+title: "Portable Instructions & Standards"
+description: "Ownership index for portable instruction files covering standards, best practices, and governance across LightSpeed projects."
+version: "v0.3.2"
+last_updated: "2026-05-31"
+maintainer: "LightSpeed Team"
+authors: ["LightSpeed Team"]
+tags: ["instructions", "standards", "documentation", "governance"]
+domain: "governance"
+stability: "stable"
+license: "GPL-3.0"
 ---
 
 # Portable Instructions & Standards

schema/README.md

@@ -1,10 +1,9 @@
 ---
-file_type: index
-title: Portable Schemas
-description: Ownership index for portable schemas used by LightSpeed AI assets and
-  plugin metadata.
-version: v0.1.1
-last_updated: '2026-05-26'
+file_type: "documentation"
+title: "Portable Schemas"
+description: "Ownership index for portable schemas used by LightSpeed AI assets and plugin metadata."
+version: "v0.1.1"
+last_updated: "2026-05-31"
 maintainer: LightSpeed Team
 authors:
 - Codex

wceu-2026/README.md

@@ -1,9 +1,12 @@
 ---
+file_type: "documentation"
 title: "WCEU 2026 Presentation Materials"
 description: "Complete Phase 1, 2, and 3 materials for WCEU 2026 talk: 'One .github repo to rule them all'"
+version: "v1.0.0"
 created_date: "2026-05-28"
-file_type: documentation
-last_updated: "2026-05-30"
+last_updated: "2026-05-31"
+maintainer: "LightSpeed Team"
+tags: ["wceu-2026", "presentation", "documentation"]
 ---
 
 # WCEU 2026 Presentation Materials