Skip to content

[AI Ops] Close issue #32 child labeling gaps #412

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ashleyshaw merged 1 commit into from
May 26, 2026
+106 −7
Merged

[AI Ops] Close issue #32 child labeling gaps #412

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 88 additions & 0 deletions .github/instructions/markdown.instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
```

```
Comment on lines +65 to +71

@gemini-code-assist gemini-code-assist Bot May 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The example code block is not nested correctly. In Markdown, to nest a fenced code block inside another, the outer block should use more backticks (e.g., four backticks ````) than the inner block (three backticks ```). Otherwise, the first inner closing/opening backticks will prematurely close the outer block.

Update the outer block to use four backticks:

````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.*
1 change: 0 additions & 1 deletion .github/workflows/labeling.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,6 @@ jobs:
uses: actions/checkout@v4
with:
fetch-depth: 0
ref: develop

- name: Setup Node
uses: actions/setup-node@v4
Expand Down
24 changes: 18 additions & 6 deletions scripts/agents/labeling.agent.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Comment on lines +86 to +88

@gemini-code-assist gemini-code-assist Bot May 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The mapping of type:accessibility to type:a11y represents a label migration. Please ensure this migration is documented in the central /docs/MIGRATION.md file so that contributors can follow the migration rules across the repository.

References
  1. Document migration maps and notes in a central /docs/MIGRATION.md file to ensure contributors can follow migration rules mentioned in README files across the repository.

};

// Branch prefix to type mapping for PRs
Expand All @@ -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) {
Expand Down Expand Up @@ -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,
Expand All @@ -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(
Expand Down Expand Up @@ -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)) {

@gemini-code-assist gemini-code-assist Bot May 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

If the issue or pull request has an empty description, body will be null. Since detectIssueTypeFromContent does not handle null values defensively (it calls body.toLowerCase()), this will throw a TypeError: Cannot read properties of null (reading 'toLowerCase') and fail the content-based type detection step.

To prevent this, ensure body and title are guarded or defaulted to empty strings before being passed, or update detectIssueTypeFromContent to handle null/undefined values.

if (!dryRun) {
await octokit.rest.issues.addLabels({
owner,
Expand All @@ -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(
Expand Down
Loading