chore(lint/docs): add granular npm-package-json-lint env toggles, enable CI step, and standardize doc link guidance

- add NPMPKGJSONLINT_REQUIRE_* and NPMPKGJSONLINT_DISABLE_ORDER vars to .env.example
- support granular require toggles in npmpackagejsonlint.config.cjs; relax scope/license enforcement
- update package.json script to use config file and remove forced disable-order flag
- run npm-package-json-lint in CI (add step and env defaults in .github/workflows/lint.yml)
- document npm-package-json-lint env vars, examples, and usage in docs/LINTING.md
- consolidate universal repo-local link guidance (/blob/HEAD/) across docs instructions (docs, readme, markdown-style-guide, coding-standards)

Author: ashleyshaw

.env.example

@@ -172,6 +172,16 @@ NPMPKGJSONLINT_NAME_FORMAT=error
 # Enable required fields validation (default: true)
 NPMPKGJSONLINT_REQUIRE_FIELDS=true
 
+# Granular required metadata toggles (override master NPMPKGJSONLINT_REQUIRE_FIELDS)
+# Set any of these to "false" to disable a single required rule while leaving others on.
+NPMPKGJSONLINT_REQUIRE_DESCRIPTION=true
+NPMPKGJSONLINT_REQUIRE_REPOSITORY=true
+NPMPKGJSONLINT_REQUIRE_LICENSE=true
+NPMPKGJSONLINT_REQUIRE_AUTHOR=true
+
+# Disable property ordering enforcement (prefer-property-order rule)
+NPMPKGJSONLINT_DISABLE_ORDER=false
+
 # =============================================================================
 # Stylelint Configuration
 # =============================================================================

.github/instructions/coding-standards.instructions.md

@@ -91,11 +91,7 @@ This document is the single source of truth for all coding standards in LightSpe
 
 ## Documentation Standards
 
-- All docs must use Markdown, be linted, and follow [markdownlint](https://github.com/DavidAnson/markdownlint) rules.
-- All public functions/classes must have docblocks or docstrings.
-- Inline documentation must be clear and reference related files or standards.
-
----
+ All documentation links to files within the same repository should use `/blob/HEAD/` in URLs to ensure universality across branches and avoid broken links after merges. Always validate links after editing documentation.
 
 ## AI & Copilot Instructions
 
@@ -116,4 +112,4 @@ This document is the single source of truth for all coding standards in LightSpe
 ---
 
 _This file is the canonical reference for all code, documentation, and automation standards in LightSpeedWP projects.  
-All contributors, agents, and AI assistants must comply with these standards._
+All contributors, agents, and AI assistants must comply with these standards._

.github/instructions/docs.instructions.md

@@ -1,9 +1,111 @@
 # Documentation Instructions
 
 ## Expectations
-- Update README when behaviour changes.
-- For patterns: add screenshot, purpose, usage notes, a11y notes.
-- Maintain CHANGELOG entries for user-visible changes.
+
+- All documentation must comply with the standards below and respect the references and cross-linking conventions for every document created or updated.
+- Every `.md` file in `docs/` and its subfolders must include YAML frontmatter, clear structure, accessibility, and cross-references as described.
 
 ## Structure
-- Keep docs close to code; link from `README.md` to pattern/block docs.
+
+All cross-references and file links must be universal. Avoid branch-specific links unless necessary for historical context. Use `/blob/HEAD/` for repo-local files.
+
+---
+
+# Universal Documentation Standards for `.md` Files
+
+## 1. Frontmatter
+
+Every documentation file should start with YAML frontmatter including:
+
+- `title`: Document title (required)
+- `description`: Brief summary of the file’s purpose (required)
+- `last_updated`: Date of last meaningful update (required)
+- `owners`: Responsible maintainers or teams (required)
+- `references`: Related files, specs, or external resources (required; must be real, repo-relative links)
+
+## 2. Structure & Headings
+
+- Use clear, hierarchical headings (`#`, `##`, `###`) for logical organization.
+- Include a Table of Contents for files longer than ~100 lines.
+- Start with an **Overview** or **Purpose** section.
+
+## 3. Clarity & Language
+
+- Use plain, concise language.
+- Avoid jargon unless defined.
+- Prefer UK English (per org standards).
+
+## 4. Navigation & Cross-References
+
+- Reference parent indexes and related docs (see `CHECKLIST_CROSSLINKING.md`).
+- Ensure bidirectional and lateral links—no dead ends.
+- All references must be respected and validated for every document.
+- Use `/blob/HEAD/` for repo-local files and relative links for files within the same repo.
+
+## 5. Formatting & Accessibility
+
+- Follow [WCAG 2.2 AA](https://www.w3.org/TR/WCAG22/) and a11y.instructions.md.
+- Use lists, tables, and code blocks for clarity.
+- Add alt text to images and diagrams.
+- Ensure headings and lists are properly spaced for readability.
+- Use badges for status, coverage, or compliance where relevant.
+- Run markdownlint and Prettier for formatting compliance.
+
+## 6. Diagrams & Visuals
+
+- Use Mermaid diagrams for workflows, architecture, or processes.
+- Include screenshots or illustrations where helpful.
+
+## 7. Examples & Usage
+
+- Provide code examples, sample commands, or usage scenarios.
+- For configuration or scripts, show input/output and expected results.
+
+## 8. Validation & Testing
+
+- Document how to validate, test, or review the content (e.g., linting, schema checks).
+- Validate all links and references after every edit.
+
+## 9. Change Log & Versioning
+
+- For critical or frequently updated docs, include a change log or version history.
+- Update `last_updated` and `version` fields on changes.
+- Document significant changes in commit messages and changelogs.
+
+## 10. Contribution & Review
+
+- State how to propose changes or report issues.
+- Reference contributing guidelines.
+- Schedule regular audits and integrate checks into CI/CD.
+
+## 11. Compliance & Security
+
+- For compliance/security docs, include audit status, responsible owner, and incident history.
+
+## 12. Accessibility & Inclusion
+
+- Ensure documentation is accessible to all users (screen reader compatibility, keyboard navigation, etc.).
+- Use people-first, bias-aware language.
+
+## 13. Footer
+
+- Add a consistent footer with references, contact info, and license.
+
+---
+
+## Documentation Checklist
+
+- [ ] YAML frontmatter is present and complete
+- [ ] Overview or Purpose section is clear
+- [ ] Table of Contents included for long files
+- [ ] Headings are hierarchical and logical
+- [ ] All links use `/blob/HEAD/` for repo-local files
+- [ ] All references are respected and validated
+- [ ] Formatting is clear and accessible
+- [ ] Diagrams and images have alt text
+- [ ] Examples and usage are provided where relevant
+- [ ] Validation/testing instructions included
+- [ ] Change log/version history present if needed
+- [ ] Contribution and review process described
+- [ ] Compliance/security info present if needed
+- [ ] Footer is present and complete

.github/instructions/markdown-style-guide.instructions.md

@@ -47,6 +47,10 @@ Wrap the title in square brackets `[title]` immediately followed by the URL in `
 [WordPress](https://wordpress.org/)
 ```
 
+#### Universal Link Guidance
+
+When linking to files in the same repository, always use `/blob/HEAD/` in the URL instead of a branch name. This ensures links remain valid after merges or branch changes.
+
 ## Blockquotes
 
 Use `>` for blockquotes, double `>>` to further indent:
@@ -63,6 +67,9 @@ Use `>` for blockquotes, double `>>` to further indent:
 Use `-` for unordered lists, and intent two spaces for list subitems:
 
 ```md
+
+### Universal Link Guidance
+
 - List
   - List
 - List

.github/instructions/readme.instructions.md

@@ -6,6 +6,7 @@ applyTo: "README.md, *.md"
 # README Documentation Standards & Update Tasks
 
 ## Universal Required Sections (for all README.md)
+
 - **Frontmatter:**
   - `description`: What is this file/folder for?
   - `references`: Related docs, schemas, instructions (AI cross-linking).
@@ -16,6 +17,7 @@ applyTo: "README.md, *.md"
 - **Footer:** Consistent references for human readers.
 
 ## Strongly Recommended Sections
+
 - **Owners/Maintainers:** Who is responsible for updates?
 - **Version:** For scripts, schemas, configs, or agents.
 - **Status/Badges:** Coverage, build, lint, security, etc.
@@ -29,6 +31,7 @@ applyTo: "README.md, *.md"
 - **Validation/Testing:** How to validate or test the file/folder.
 
 ## Optional Sections (add if relevant)
+
 - **FAQ/Troubleshooting:** Common issues and solutions.
 - **Limitations/Notes:** Known issues, future improvements.
 - **Related Projects/Links:** Other relevant projects or resources.
@@ -43,6 +46,7 @@ applyTo: "README.md, *.md"
 - **Deprecation Notice:** If the file/folder is deprecated or superseded.
 
 ## Expanded Guidance by Type
+
 - **Test Folders:** Coverage badge, test matrix, how to run, test dependencies, test data location, test environment.
 - **Scripts/Utilities:** Supported platforms, dependencies, input/output, error handling, logging, performance notes.
 - **Schemas/Configs:** Schema version, validation instructions, example config, compatibility notes, migration instructions.
@@ -76,16 +80,7 @@ How to use or run this folder/file.
 ```
 
 ## Additional Guidance
-- Use Mermaid diagrams for any process, workflow, or architecture that benefits from visualization.
-- Add badges for status, coverage, lint, or other relevant metrics.
-- Use emoji in headers only when it enhances clarity, accessibility, or engagement (see header-footer instructions).
-- Ensure all references in frontmatter are valid relative paths.
-- Keep README files concise but comprehensive; use optional sections only when they add value.
-- For folders with many files, include a structure diagram and navigation index.
-- For scripts/utilities, document all parameters, dependencies, and error handling.
-- For agents/AI files, document model, tools, limitations, and integration points.
-- For documentation folders, provide update policy, translation status, and accessibility notes.
-- For compliance/security folders, include audit status, responsible owner, and incident history.
 
----
 For further guidance, see referenced instructions files above.
+
+When linking to files in the same repository, always use `/blob/HEAD/` in the URL instead of a branch name. This ensures links remain valid after merges or branch changes.

.github/workflows/lint.yml

@@ -12,6 +12,12 @@ on:
 jobs:
   lint:
     runs-on: ubuntu-latest
+    env:
+      NPMPKGJSONLINT_STRICT_MODE: true
+      NPMPKGJSONLINT_REQUIRE_DESCRIPTION: true
+      NPMPKGJSONLINT_REQUIRE_REPOSITORY: true
+      NPMPKGJSONLINT_REQUIRE_LICENSE: true
+      NPMPKGJSONLINT_REQUIRE_AUTHOR: true
     steps:
       - uses: actions/checkout@v4
       - name: Set up Node.js
@@ -32,4 +38,6 @@ jobs:
         run: |
           find . -type f -name "*.sh" ! -path "*/node_modules/*" -exec shellcheck {} +
       - name: Run yamllint
-        run: yamllint .
+        run: yamllint .
+      - name: Run npm-package-json-lint
+        run: npm run lint:pkg-json

docs/LINTING.md

@@ -64,7 +64,7 @@ Our linting strategy follows these core principles:
 | **Prettier**       | Code formatting               | `prettier.config.js`         | ✅       |
 | **markdownlint**   | Markdown linting              | `.markdownlint.json`         | ✅       |
 | **Spectral**       | YAML/JSON linting             | `.spectral.yaml`             | ❌       |
-| **npmPkgJsonLint** | package.json validation       | `.npmpackagejsonlintrc.json` | ❌       |
+| **npmPkgJsonLint** | package.json validation       | `npmpackagejsonlint.config.cjs` | ❌       |
 
 ### Tool Selection Rationale
 
@@ -128,6 +128,47 @@ export default [
 
 ### Environment Configuration
 
+### npm-package-json-lint Configuration & Env Vars
+
+The package JSON lint configuration now lives in `npmpackagejsonlint.config.cjs` (CJS for environment variable access and comments). You can influence rule enforcement via the following environment variables in `.env` (see `.env.example`):
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `NPMPKGJSONLINT_STRICT_MODE` | Treat `version-format` failures as errors (otherwise warning) | `false` |
+| `NPMPKGJSONLINT_NAME_FORMAT` | Severity for `name-format` rule (`error`/`warning`/`off`) | `error` |
+| `NPMPKGJSONLINT_REQUIRE_FIELDS` | Master toggle for all required metadata rules | `true` |
+| `NPMPKGJSONLINT_REQUIRE_DESCRIPTION` | Require `description` field | `true` |
+| `NPMPKGJSONLINT_REQUIRE_REPOSITORY` | Require `repository` field | `true` |
+| `NPMPKGJSONLINT_REQUIRE_LICENSE` | Require `license` field | `true` |
+| `NPMPKGJSONLINT_REQUIRE_AUTHOR` | Require `author` field | `true` |
+| `NPMPKGJSONLINT_DISABLE_ORDER` | Disable `prefer-property-order` enforcement | `false` |
+| `NPMPKGJSONLINT_IGNORE_PATHS` | Additional comma‑separated paths to ignore | (empty) |
+
+Example script (already defined):
+
+```jsonc
+"lint:pkg-json": "npmPkgJsonLint --configFile npmpackagejsonlint.config.cjs ."
+```
+
+To temporarily relax ordering while keeping other rules:
+
+```bash
+NPMPKGJSONLINT_DISABLE_ORDER=true npm run lint:pkg-json
+```
+
+To enforce strict version formatting in CI:
+
+```bash
+NPMPKGJSONLINT_STRICT_MODE=true npm run lint:pkg-json
+```
+
+Incremental adoption strategy:
+
+1. Enable required metadata (default) and address any missing fields.
+2. Turn on strict version formatting (`STRICT_MODE=true`).
+3. Keep scope validation off until an allowed scope list is defined.
+4. Optionally tighten `valid-values-license` to `error` once all packages normalize licensing.
+
 ```bash
 # .env - Customize linting behaviour
 ESLINT_IGNORE=node_modules/**,build/**,custom-folder/**
@@ -160,7 +201,7 @@ PRETTIER_PRINT_WIDTH=80
         "lint:md": "markdownlint '**/*.md' --fix",
         "lint:yaml": "spectral lint '**/*.{yml,yaml}' --ruleset .spectral.yaml",
         "lint:workflows": "spectral lint '.github/workflows/*.{yml,yaml}' --ruleset .spectral-workflows.yaml",
-        "lint:pkg-json": "npmPkgJsonLint ."
+        "lint:pkg-json": "npmPkgJsonLint --configFile npmpackagejsonlint.config.cjs ."
     }
 }
 ```

npmpackagejsonlint.config.cjs

@@ -6,12 +6,15 @@
  *   scripts/utility/npm-package-json-lint-helpers.js
  *
  * Environment variables (optional overrides):
- *   NPMPKGJSONLINT_IGNORE_PATHS       Comma-separated extra ignore paths
- *   NPMPKGJSONLINT_STRICT_MODE        Treat version-format as error (default false)
- *   NPMPKGJSONLINT_NAME_FORMAT        Severity for name-format (default error)
- *   NPMPKGJSONLINT_REQUIRE_FIELDS     Toggle description/repository/license (default true)
- *   NPMPKGJSONLINT_REQUIRE_AUTHOR     Toggle require-author rule (default true)
- *   NPMPKGJSONLINT_DISABLE_ORDER      Disable prefer-property-order rule (default false)
+ *   NPMPKGJSONLINT_IGNORE_PATHS          Comma-separated extra ignore paths
+ *   NPMPKGJSONLINT_STRICT_MODE            Treat version-format as error (default false)
+ *   NPMPKGJSONLINT_NAME_FORMAT            Severity for name-format (default error)
+ *   NPMPKGJSONLINT_REQUIRE_FIELDS         Backwards-compatible master toggle (if false, disables all require-* rules)
+ *   NPMPKGJSONLINT_REQUIRE_DESCRIPTION    Toggle require-description (default true)
+ *   NPMPKGJSONLINT_REQUIRE_REPOSITORY     Toggle require-repository (default true)
+ *   NPMPKGJSONLINT_REQUIRE_LICENSE        Toggle require-license (default true)
+ *   NPMPKGJSONLINT_REQUIRE_AUTHOR         Toggle require-author (default true)
+ *   NPMPKGJSONLINT_DISABLE_ORDER          Disable prefer-property-order rule (default false)
  *
  * NOTE: Only documented rules supported by npm-package-json-lint v7 are enabled.
  */
@@ -36,6 +39,13 @@ const strictMode = process.env.NPMPKGJSONLINT_STRICT_MODE === 'true';
 const nameFormat = process.env.NPMPKGJSONLINT_NAME_FORMAT || 'error';
 const requireFields = process.env.NPMPKGJSONLINT_REQUIRE_FIELDS !== 'false';
 const requireAuthor = process.env.NPMPKGJSONLINT_REQUIRE_AUTHOR !== 'false';
+// Granular required field toggles (fall back to master flag)
+const requireDescription =
+    requireFields && process.env.NPMPKGJSONLINT_REQUIRE_DESCRIPTION !== 'false';
+const requireRepository =
+    requireFields && process.env.NPMPKGJSONLINT_REQUIRE_REPOSITORY !== 'false';
+const requireLicense =
+    requireFields && process.env.NPMPKGJSONLINT_REQUIRE_LICENSE !== 'false';
 const disableOrder = process.env.NPMPKGJSONLINT_DISABLE_ORDER === 'true';
 const ignorePathsEnv = parseList(process.env.NPMPKGJSONLINT_IGNORE_PATHS);
 
@@ -100,15 +110,16 @@ module.exports = {
     rules: {
         // --- Naming & scope rules ---
             'name-format': nameFormat,
-            'valid-values-name-scope': 'error',
+            // Scope validation remains disabled until an allowed scope list is defined.
+            'valid-values-name-scope': 'off',
 
         // --- Version rules ---
             'version-format': strictMode ? 'error' : 'warning',
 
         // --- Required metadata (env toggles) ---
-            'require-description': requireFields ? 'error' : 'off',
-            'require-license': requireFields ? 'error' : 'off',
-            'require-repository': requireFields ? 'error' : 'off',
+            'require-description': requireDescription ? 'error' : 'off',
+            'require-license': requireLicense ? 'error' : 'off',
+            'require-repository': requireRepository ? 'error' : 'off',
             'require-author': requireAuthor ? 'error' : 'off',
 
         // --- Type checks (low risk, ensure JSON shape consistency) ---
@@ -122,8 +133,8 @@ module.exports = {
             ? 'off'
             : ['warning', preferredOrder],
 
-        // --- License values (relaxed set; enable later if stricter policy adopted) ---
-            'valid-values-license': 'error',
+        // --- License values ---
+            'valid-values-license': ['warning', ['GPL-3.0-or-later']],
     },
 };
 

package.json

@@ -108,7 +108,7 @@
         "typescript": "^5.0.0"
     },
     "scripts": {
-        "lint:pkg-json": "NPMPKGJSONLINT_DISABLE_ORDER=true npmPkgJsonLint --configFile npmpackagejsonlint.config.cjs .",
+        "lint:pkg-json": "npmPkgJsonLint --configFile npmpackagejsonlint.config.cjs .",
         "lint:yaml": "spectral lint '**/*.{yml,yaml}' --ruleset spectral.config.js",
         "lint:workflows": "spectral lint '.github/workflows/*.{yml,yaml}' --ruleset spectral.config.js",
         "lint": "npm run lint:js && npm run lint:css && npm run lint:yaml && npm run lint:pkg-json",