chore: cover the behavioural edits with tests and add the new required checks

.github/rulesets/README.md

@@ -35,7 +35,13 @@ This directory contains version-controlled JSON definitions of the GitHub reposi
     - `Route PR template and apply labels`
     - `Validate changelog on PR`
     - `actionlint`
-- **Not enforced:** no merge-queue rule — the repo merges directly and via Mergify, not the GitHub merge queue. No bypass actors.
+- **Not enforced:** no merge-queue rule — the repo merges directly and via Mergify, not the GitHub merge queue.
+- **Bypass:** one actor, the repository owner `eleshar` (User `1577675`), in `pull_request` mode: the owner can merge a pull request past the review requirement, and cannot push to `develop` directly. Any other bypass actor, or a different mode for this one, is reported as drift by `validate-ruleset-drift`, but only when the script can see the actors. GitHub returns `bypass_actors` only to a caller with write access to the ruleset, so CI (which deliberately holds no such credential) notes that they were not compared. An owner verifies them by running the check with their own token, for example after any ruleset change:
+
+  ```bash
+  GITHUB_TOKEN=$(gh auth token) GITHUB_REPOSITORY=lightspeedwp/.github \
+    node scripts/validation/validate-ruleset-drift.cjs
+  ```
 
 ### 2. `main` Branch Ruleset ([main.ruleset.json](./main.ruleset.json))
 

.github/rulesets/develop.ruleset.json

@@ -4,9 +4,7 @@
   "enforcement": "active",
   "conditions": {
     "ref_name": {
-      "include": [
-        "refs/heads/develop"
-      ],
+      "include": ["refs/heads/develop"],
       "exclude": []
     }
   },
@@ -40,10 +38,22 @@
           },
           {
             "context": "actionlint"
+          },
+          {
+            "context": "Lint (JS/YAML/package.json)"
+          },
+          {
+            "context": "Typecheck"
           }
         ]
       }
     }
   ],
-  "bypass_actors": []
+  "bypass_actors": [
+    {
+      "actor_id": 1577675,
+      "actor_type": "User",
+      "bypass_mode": "pull_request"
+    }
+  ]
 }

.github/workflows/ruleset-drift.yml

@@ -0,0 +1,70 @@
+name: Ruleset Drift
+
+# Fails when a deployed branch ruleset no longer matches its version-controlled
+# declaration in .github/rulesets/.
+#
+# The declarations are applied by hand (see .github/rulesets/README.md), so
+# nothing else noticed when a required status check quietly stopped being
+# enforced. A check that is no longer required is invisible in the JSON and only
+# shows up as a PR merging that it should not have.
+#
+# This detects drift; it never applies, creates or mutates a ruleset. Pushing
+# ruleset changes needs a token with ruleset-write, and letting a pull request
+# rewrite branch protection is a privilege escalation. Detection and application
+# stay separate, deliberate steps.
+
+on:
+  pull_request:
+    paths:
+      - '.github/rulesets/**'
+      - 'scripts/validation/validate-ruleset-drift.cjs'
+      - '.github/workflows/ruleset-drift.yml'
+  push:
+    branches:
+      - develop
+    paths:
+      - '.github/rulesets/**'
+      - 'scripts/validation/validate-ruleset-drift.cjs'
+      - '.github/workflows/ruleset-drift.yml'
+  # Catch drift that does not come from a ruleset change, e.g. someone editing
+  # a ruleset in the GitHub UI without updating the declaration.
+  schedule:
+    - cron: '17 6 * * 1'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ruleset-drift-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  drift:
+    name: Ruleset declaration matches live
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version-file: .nvmrc
+
+      - name: Check for ruleset drift
+        # Read-only: a repository GITHUB_TOKEN can read rulesets but cannot
+        # create or update them, which is the point of this job.
+        #
+        # Bypass actors are not compared here. GitHub returns `bypass_actors` only
+        # to a caller with WRITE access to the ruleset (Administration read is not
+        # enough), so reading them in CI would need a credential that can also
+        # change branch protection. This job deliberately has none. The script
+        # prints a note that actors were not compared; an owner checks them by
+        # running the script with their own token (see .github/rulesets/README.md).
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+        run: node scripts/validation/validate-ruleset-drift.cjs

agents/changelog-agent/changelog-validator.js

@@ -213,4 +213,6 @@ if (require.main === module) {
   main();
 }
 
-module.exports = { validateEntry, auditRelease, exportReleaseNotes };
+// parseYamlEntry is exported for unit testing: validateEntry catches every
+// error and exits, so the `cause` chaining cannot be asserted through it.
+module.exports = { validateEntry, auditRelease, exportReleaseNotes, parseYamlEntry };

agents/changelog-agent/tests/unit/parse-yaml-entry.test.js

@@ -0,0 +1,56 @@
+/**
+ * Unit tests for parseYamlEntry.
+ *
+ * The YAML parse error is rethrown with the original error attached as
+ * `cause`. That is easy to lose: validateEntry catches everything and exits,
+ * so a plain `new Error(...)` would look identical from the CLI while dropping
+ * the underlying parser position. These assertions pin the chaining.
+ */
+
+const { parseYamlEntry } = require('../../changelog-validator.js');
+
+describe('parseYamlEntry', () => {
+  it('parses valid YAML into an object', () => {
+    expect(parseYamlEntry('id: 123\ntitle: "A change"\n')).toEqual({
+      id: 123,
+      title: 'A change',
+    });
+  });
+
+  it('throws with the parser error preserved as cause', () => {
+    const input = 'id: 123\n  bad indent: [unclosed\n';
+
+    // The exception js-yaml itself raises for this input: the cause has to be that
+    // error, with its reason and position, not any other Error.
+    let original;
+    try {
+      require('js-yaml').load(input);
+    } catch (error) {
+      original = error;
+    }
+    expect(original).toBeDefined();
+    expect(original.mark).toBeDefined();
+
+    let thrown;
+    try {
+      parseYamlEntry(input);
+    } catch (error) {
+      thrown = error;
+    }
+
+    expect(thrown).toBeInstanceOf(Error);
+    expect(thrown.message).toBe(`Invalid YAML: ${original.message}`);
+    expect(thrown.cause).not.toBe(thrown);
+    expect(thrown.cause.name).toBe(original.name);
+    expect(thrown.cause.reason).toBe(original.reason);
+    expect(thrown.cause.message).toBe(original.message);
+    expect(thrown.cause.mark).toEqual(
+      expect.objectContaining({ line: original.mark.line, column: original.mark.column })
+    );
+  });
+
+  it('does not set cause when parsing succeeds', () => {
+    const parsed = parseYamlEntry('id: 1');
+    expect(parsed).toEqual({ id: 1 });
+  });
+});

docs/LINEAR_INTEGRATION.md

@@ -55,13 +55,13 @@ use:
 The following need the **Enterprise** plan and are deliberately not part of this
 integration. Do not plan work that depends on them:
 
-| Feature                             | Why it is out of scope                                                                           | Source                                                            |
-| ----------------------------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
-| The **workspace owner** role        | Business tops out at Admin, so every instruction below says **workspace Admin**, never **owner** | [members and roles](https://linear.app/docs/members-roles)        |
-| SCIM provisioning                   | Enterprise                                                                                       | [SCIM](https://linear.app/docs/scim)                               |
-| Audit logs                          | Enterprise; only owners can read them                                                            | [audit log](https://linear.app/docs/audit-log)                     |
-| Private-team issue sharing          | Enterprise only. Private teams themselves are available on Business                                | [private teams](https://linear.app/docs/private-teams)            |
-| Owner-only "Workspace restrictions" | Owners configure role restrictions; Enterprise workspaces can limit Admin permissions          | [members and roles](https://linear.app/docs/members-roles)        |
+| Feature                             | Why it is out of scope                                                                           | Source                                                     |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- |
+| The **workspace owner** role        | Business tops out at Admin, so every instruction below says **workspace Admin**, never **owner** | [members and roles](https://linear.app/docs/members-roles) |
+| SCIM provisioning                   | Enterprise                                                                                       | [SCIM](https://linear.app/docs/scim)                       |
+| Audit logs                          | Enterprise; only owners can read them                                                            | [audit log](https://linear.app/docs/audit-log)             |
+| Private-team issue sharing          | Enterprise only. Private teams themselves are available on Business                              | [private teams](https://linear.app/docs/private-teams)     |
+| Owner-only "Workspace restrictions" | Owners configure role restrictions; Enterprise workspaces can limit Admin permissions            | [members and roles](https://linear.app/docs/members-roles) |
 
 Each row is a claim about the plan, so each cites the page that establishes it.
 Two features that were previously listed here are **not** Enterprise-only:
@@ -220,6 +220,16 @@ default. Set `"visible": true` to also surface the comment in Linear's activity
 feed. On-behalf-of blocks are visible by default unless `"visible": false` is
 set. Put `visible` on each plugin object, not on the block.
 
+**Visible summary on GitHub.** GitHub shows a comment that holds only HTML
+comments as "No description provided.", so the block is followed by a short
+plain-text summary: the risk level and each explanation, plus the agent and model
+when attributed. File names in the summary are shown in code spans with `<` and `>`
+replaced by single angle quotes, so a hostile file name cannot mention a user,
+link, inject HTML or forge a second `linear:extension` block. Linear's handling of
+a comment that carries visible text next to a block is not verified; it may appear
+in the activity feed. To go back to a hidden-only comment, drop the
+`renderVisibleSummary` line at the end of `buildExtensionBlock`.
+
 ### Emitting an attributed comment
 
 Any local AI agent produces the block with one command:

package.json

@@ -112,6 +112,7 @@
     "validate:issue-fields": "node scripts/validation/validate-issue-fields.cjs",
     "validate:linear-guidance": "node scripts/validation/validate-linear-guidance.cjs",
     "validate:retired-doc-links": "node scripts/validation/validate-retired-doc-links.cjs",
+    "validate:ruleset-drift": "node scripts/validation/validate-ruleset-drift.cjs",
     "validate:workflow-npm-scripts": "node scripts/validation/validate-workflow-npm-scripts.cjs",
     "validate:frontmatter": "node scripts/validation/validate-frontmatter.js",
     "validate:frontmatter:changed": "node scripts/validation/validate-frontmatter.js",

scripts/automation/__tests__/linear-review-extension.test.js

@@ -228,6 +228,40 @@ describe('buildExtensionBlock', () => {
     expect(blocks[0].map((plugin) => plugin.plugin)).toEqual(['riskScore', 'onBehalfOf']);
   });
 
+  test('follows the hidden block with a visible summary so GitHub shows content', () => {
+    const body = buildExtensionBlock({
+      risk: { level: 3, explanations: ['Touches authentication'] },
+      agent: 'claude',
+      model: 'Opus 4.5',
+    });
+    const visible = body.slice(body.lastIndexOf('-->') + 3).trim();
+
+    expect(visible).toBe(
+      [
+        '**Linear review**: risk level 3 of 4',
+        '- `Touches authentication`',
+        'Published on behalf of `claude` (`Opus 4.5`)',
+      ].join('\n')
+    );
+  });
+
+  test('renders untrusted text in inert code spans', () => {
+    const body = buildExtensionBlock({
+      risk: {
+        level: 2,
+        explanations: [
+          '@octocat [x](http://e.test) <img src=x> `a``b` <!-- linear:extension {} -->',
+        ],
+      },
+    });
+    const visible = body.slice(body.lastIndexOf('-->') + 3);
+
+    expect(visible).not.toMatch(/[<>]/);
+    expect(visible).toContain('- ```@octocat');
+    expect(body.match(/<!--\s*linear:extension/g)).toHaveLength(1);
+    expect(parseExtensionBlocks(body)).toHaveLength(1);
+  });
+
   test('emits a single valid JSON payload that starts with the marker', () => {
     const body = buildExtensionBlock({ risk: { level: 1 } });
 

scripts/automation/linear-review-extension.cjs

@@ -417,7 +417,62 @@ function buildExtensionBlock(input = {}) {
   }
 
   const payload = { version: EXTENSION_VERSION, plugins };
-  return `${EXTENSION_MARKER}\n<!-- linear:extension ${serialisePayload(payload)} -->`;
+  return (
+    `${EXTENSION_MARKER}\n<!-- linear:extension ${serialisePayload(payload)} -->` +
+    `\n\n${renderVisibleSummary(plugins)}`
+  );
+}
+
+/**
+ * Render untrusted text as an inline code span.
+ *
+ * Explanations quote pull request filenames, which a contributor chooses, and this
+ * text is now shown on GitHub. A code span keeps it literal: no mentions, links,
+ * images, HTML or Markdown. The fence is one backtick longer than the longest run
+ * inside, so a name containing backticks cannot close the span early.
+ *
+ * Angle brackets are replaced with the look-alike single angle quotation marks.
+ * Markdown rendering is not the only reader: Linear scans the comment's source for
+ * `<!-- linear:extension ... -->`, so a file named like a forged block would
+ * otherwise be parsed as a second one, and a literal `-->` would break the
+ * invariant that the body holds exactly the closers this module wrote. With no
+ * `<` or `>` in the visible text, neither can occur.
+ * @param {string} text - Text to show verbatim.
+ * @returns {string} The code span.
+ */
+function codeSpan(text) {
+  const flat = String(text).replace(/</g, '‹').replace(/>/g, '›').replace(/\s+/g, ' ').trim();
+  const longestRun = Math.max(0, ...(flat.match(/`+/g) || []).map((run) => run.length));
+  const fence = '`'.repeat(longestRun + 1);
+  const pad = flat.startsWith('`') || flat.endsWith('`') ? ' ' : '';
+  return `${fence}${pad}${flat}${pad}${fence}`;
+}
+
+/**
+ * The human-readable part of the comment.
+ *
+ * The `linear:extension` blocks are HTML comments, so on their own GitHub renders
+ * the comment as "No description provided." This gives people reading the pull
+ * request the same facts Linear receives: the risk level, why, and who published
+ * it. It is derived only from the validated payload, so it is deterministic and
+ * the upsert's byte-identical check still avoids needless edits.
+ * @param {Array<object>} plugins - The plugins just serialised into the block.
+ * @returns {string} Markdown to append below the hidden blocks.
+ */
+function renderVisibleSummary(plugins) {
+  const lines = [];
+  for (const plugin of plugins) {
+    if (plugin.plugin === 'riskScore') {
+      lines.push(`**Linear review**: risk level ${plugin.level} of ${MAX_RISK_LEVEL}`);
+      for (const explanation of plugin.explanations || []) {
+        lines.push(`- ${codeSpan(explanation)}`);
+      }
+    } else if (plugin.plugin === 'onBehalfOf') {
+      const model = plugin.model ? ` (${codeSpan(plugin.model)})` : '';
+      lines.push(`Published on behalf of ${codeSpan(plugin.agent)}${model}`);
+    }
+  }
+  return lines.join('\n');
 }
 
 /**

scripts/validation/__tests__/agent-permissions-frontmatter.test.js

@@ -0,0 +1,47 @@
+/**
+ * Pins the agent frontmatter shape the skill and agent validator actually
+ * accepts.
+ *
+ * mode-thinking.agent.md moved its permissions between a top-level
+ * `permissions:` list and a `metadata.permissions` string more than once while
+ * #3774 was in review, and the two forms are not interchangeable: the
+ * validator reads the top-level list. Commit 2c1efe2d56 settled it on the
+ * top-level form and 823c4544fe taught the schema to allow it. This asserts
+ * the agreed shape so a later "tidy-up" cannot silently break validation
+ * again.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const yaml = require('js-yaml');
+
+const repositoryRoot = path.resolve(__dirname, '../../..');
+const AGENT = 'agents/mode-thinking.agent.md';
+
+function frontmatter(relative) {
+  const raw = fs.readFileSync(path.join(repositoryRoot, relative), 'utf8');
+  const match = /^---\n([\s\S]*?)\n---\n/.exec(raw);
+
+  expect(match).not.toBeNull();
+
+  return yaml.load(match[1]);
+}
+
+describe('mode-thinking agent frontmatter', () => {
+  it('parses', () => {
+    expect(() => frontmatter(AGENT)).not.toThrow();
+  });
+
+  it('declares permissions as a top-level list', () => {
+    const data = frontmatter(AGENT);
+
+    expect(Array.isArray(data.permissions)).toBe(true);
+    expect(data.permissions).toEqual(expect.arrayContaining(['read', 'write', 'github:repo']));
+  });
+
+  it('does not move permissions into metadata', () => {
+    const data = frontmatter(AGENT);
+
+    expect(data.metadata?.permissions).toBeUndefined();
+  });
+});