diff --git a/.github/instructions/markdown.instructions.md b/.github/instructions/markdown.instructions.md new file mode 100644 index 000000000..e6ff61522 --- /dev/null +++ b/.github/instructions/markdown.instructions.md @@ -0,0 +1,88 @@ +--- +file_type: "instructions" +title: "Markdown Instructions (Repo-local)" +description: "Canonical Markdown authoring rules for the LightSpeed .github control-plane repository." +version: "v1.0" +last_updated: "2026-05-26" +owners: ["LightSpeed Team"] +tags: ["markdown", "documentation", "a11y", "governance"] +applyTo: ["**/*.md"] +status: "active" +stability: "stable" +domain: "governance" +--- + +# Markdown Instructions (Repo-local) + +This file is the canonical Markdown standard for repo-local `.github` documentation. +For portable and organisation-wide rules, use [`../../instructions/documentation-formats.instructions.md`](../../instructions/documentation-formats.instructions.md). + +## Scope + +| Scope | File family | Canonical source | +| --- | --- | --- | +| Repo-local `.github` docs | `.github/**.md`, `docs/**.md` | This file | +| Portable shared standards | `instructions/**` | `instructions/documentation-formats.instructions.md` | + +## Core Rules + +- Use one H1 per file and keep heading levels sequential. +- Use fenced code blocks with language tags. +- Keep links relative for in-repo files and verify they resolve. +- Use `1.` numbering for ordered lists and `-` for unordered lists. +- Keep wording in UK English. + +## Accessibility + +- Provide descriptive alt text for images. +- Ensure table headings are explicit and readable. +- For Mermaid diagrams, use readable labels and avoid low-contrast palettes. +- Write link text that describes destination and purpose. + +## Validation + +Run these checks before merging Markdown changes: + +```bash +npm run lint:md +git diff --check +``` + +## Examples + +Good heading flow: + +```markdown +# Title + +## Section + +### Detail +``` + +Good code block: + +```markdown + +```bash +npm run lint:md +``` + +``` + +## Contribution And Review + +- Keep edits scoped to the issue. +- Add a short rationale in the PR description. +- Cross-link related standards when introducing new conventions. + +## Cross-References + +- [`../../instructions/documentation-formats.instructions.md`](../../instructions/documentation-formats.instructions.md) +- [`../../instructions/community-standards.instructions.md`](../../instructions/community-standards.instructions.md) +- [`../../instructions/quality-assurance.instructions.md`](../../instructions/quality-assurance.instructions.md) +- [`./file-organisation.instructions.md`](./file-organisation.instructions.md) + +--- + +*Maintained by the LightSpeedWP automation and governance maintainers.* diff --git a/.github/workflows/labeling.yml b/.github/workflows/labeling.yml index 2e0983195..81765b4ca 100644 --- a/.github/workflows/labeling.yml +++ b/.github/workflows/labeling.yml @@ -57,7 +57,6 @@ jobs: uses: actions/checkout@v4 with: fetch-depth: 0 - ref: develop - name: Setup Node uses: actions/setup-node@v4 diff --git a/scripts/agents/labeling.agent.js b/scripts/agents/labeling.agent.js index f9b33071f..e06b7d42b 100644 --- a/scripts/agents/labeling.agent.js +++ b/scripts/agents/labeling.agent.js @@ -83,9 +83,9 @@ const KEYWORD_TYPE_MAP = { ci: "type:ci", "continuous integration": "type:ci", workflow: "type:ci", - a11y: "type:accessibility", - accessibility: "type:accessibility", - wcag: "type:accessibility", + a11y: "type:a11y", + accessibility: "type:a11y", + wcag: "type:a11y", }; // Branch prefix to type mapping for PRs @@ -105,7 +105,7 @@ const BRANCH_PREFIX_TYPE_MAP = { "ci/": "type:ci", "deps/": "type:dependencies", "security/": "type:security", - "a11y/": "type:accessibility", + "a11y/": "type:a11y", }; function readYamlArrayFile(path, purpose) { @@ -376,7 +376,11 @@ async function runLabelingAgent(opts = {}) { try { const branchName = context.payload.pull_request.head.ref; const branchType = detectTypeFromBranch(branchName); - if (branchType && !currentLabels.includes(branchType)) { + if ( + branchType && + canonicalSet.has(branchType) && + !currentLabels.includes(branchType) + ) { if (!dryRun) { await octokit.rest.issues.addLabels({ owner, @@ -387,6 +391,10 @@ async function runLabelingAgent(opts = {}) { } report.added.push(branchType); report.rulesApplied.push(`Branch prefix detection: ${branchType}`); + } else if (branchType && !canonicalSet.has(branchType)) { + core.warning( + `[labeling.agent] Branch-derived type is non-canonical and will be skipped: ${branchType}`, + ); } } catch (error) { core.warning( @@ -468,7 +476,7 @@ async function runLabelingAgent(opts = {}) { : context.payload.pull_request.body; const detectedType = detectIssueTypeFromContent(title, body); - if (detectedType) { + if (detectedType && canonicalSet.has(detectedType)) { if (!dryRun) { await octokit.rest.issues.addLabels({ owner, @@ -481,6 +489,10 @@ async function runLabelingAgent(opts = {}) { report.rulesApplied.push( `Content-based type detection: ${detectedType}`, ); + } else if (detectedType && !canonicalSet.has(detectedType)) { + core.warning( + `[labeling.agent] Content-derived type is non-canonical and will be skipped: ${detectedType}`, + ); } } catch (error) { core.warning(