Skip to content

Open-source skills for designing and reviewing software with AI agents

ci(contributions): clarify intake and required validation (#143)

n3wth559f7fbecbb7
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index b53b2cb..27414a9 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -8,11 +8,15 @@ Maintainers control design-ready and pr-ready. Automation manages design-needed.
## Contribution Type
-Please select the track that matches this pull request:
+Replace the value below with exactly one of the track names listed here:
-- [ ] **Bug Fix / Minor Patch** (Targeted fix, non-test diff <= 100 lines and < 3 core files in `skills/` or `agents/`; no design doc required)
-- [ ] **Feature / Architectural Change -- Stage 1: Design Doc PR** (`Refs #___` with `design-ready` | Adds `docs/designs/<name>.md` and updates `docs/designs/README.md`; use `Refs` instead of `Closes` so the issue stays open for Stage 2)
-- [ ] **Feature / Architectural Change -- Stage 2: Implementation PR** (`Closes #___` with `pr-ready` | Implements merged `docs/designs/<name>.md`)
+Track: <choose one track>
+
+- **Bug Fix / Minor Patch**: targeted fix, non-test diff <= 100 lines and < 3 core files in `skills/` or `agents/`; no design doc required.
+- **Feature / Architectural Change -- Stage 1: Design Doc PR**: use `Refs #___` with `design-ready`; add `docs/designs/<name>.md` and update the design index. Keep the issue open for Stage 2.
+- **Feature / Architectural Change -- Stage 2: Implementation PR**: use `Closes #___` with `pr-ready`; implement a merged design.
+
+<!-- Delete the track explanations above after selecting your track. -->
## Summary of Key Changes
@@ -26,6 +30,14 @@ List all key changes made in this pull request and why:
## Verification
-- [ ] **For Design Doc PRs (Stage 1)**: Executed `/egm-review docs/designs/<name>.md`, resolved findings via `/egm-resolve`, and verified relative links (`pytest tests/unit/test_link_integrity.py`).
-- [ ] **For Bug Fix / Implementation PRs (Stage 2)**: Unit tests or `test_scenarios.yaml` added/updated and `pytest tests/unit` executed.
-- [ ] **For Harness Support PRs**: Verified plugin installation and end-to-end execution of `/egm-brainstorm`, `/egm-draft`, and `/egm-review` on the target harness; attached execution summary or transcript.
+Record results as **passed**, **not run**, or **not applicable**. Include commands,
+outputs or evidence links, and limits. Delete entries that do not apply.
+
+Unit tests and relative links: <result; commands and evidence>
+
+Design review (Stage 1): <result; `/egm-review`, `/egm-resolve`, and remaining findings>
+
+Native harness workflows (harness support): <result; host/version, installation,
+`/egm-brainstorm`, `/egm-draft`, `/egm-review`, and transcript or summary>
+
+Other checks and limits: <results; checks not run and why>
diff --git a/.github/workflows/pr-scope-advisory.yml b/.github/workflows/pr-scope-advisory.yml
index 652b1c4..4c68203 100644
--- a/.github/workflows/pr-scope-advisory.yml
+++ b/.github/workflows/pr-scope-advisory.yml
@@ -12,7 +12,7 @@
# See the License for the specific language governing permissions and
# limitations under the License.
-name: "PR Scope Advisory"
+name: Check PR scope
on:
# zizmor: ignore[dangerous-triggers] - Only inspects PR metadata/diff stats and posts advisory comment; never checks out or executes untrusted code.
@@ -40,7 +40,18 @@ jobs:
script: |
const pr = context.payload.pull_request;
const body = pr.body || "";
- const isBugFix = /\[[xX]\]\s*\*\*Bug Fix/i.test(body);
+ const contributionType = body.split(/^## Contribution Type[ \t]*\r?$/m)[1]?.split(/^##[ \t]+/m)[0] || "";
+ const selectedTracks = [
+ ...Array.from(contributionType.matchAll(/^[ \t]*Track:[ \t]*(.*)$/gmi), match => match[1].trim()),
+ ...Array.from(contributionType.matchAll(/^[ \t]*(?:[-*][ \t]+)?\[[xX]\][ \t]*\*\*([^*\r\n]+)\*\*/gm), match => match[1].trim())
+ ];
+ const validTracks = [
+ "Bug Fix / Minor Patch",
+ "Feature / Architectural Change -- Stage 1: Design Doc PR",
+ "Feature / Architectural Change -- Stage 2: Implementation PR"
+ ];
+ const hasValidTrack = selectedTracks.length === 1 && validTracks.includes(selectedTracks[0]);
+ const isBugFix = hasValidTrack && selectedTracks[0] === validTracks[0];
// Fetch changed files (paginated, capped at 3 pages / 300 files)
let pageCount = 0;
@@ -89,19 +100,29 @@ jobs:
per_page: 100
}
);
- const existingComment = comments.find(c => (c.body || "").includes(signature));
+ const existingComment = comments.find(c => c.user?.login === "github-actions[bot]" && (c.body || "").includes(signature));
const shouldAdvise = isBugFix && (nonTestChanges > 100 || coreFilesCount >= 3 || files.length >= 300);
if (shouldAdvise) {
+ const scope = files.length >= 300
+ ? "This PR reaches the 300-file scan limit."
+ : `This PR changes ${nonTestChanges} counted lines and ${coreFilesCount} core files in skills/ or agents/.`;
+ const message = `${signature}\n### Scope check\n\nThank you for your contribution! ${scope} The minor-patch limit is 100 counted lines and fewer than 3 core files. Docs, tests, and lockfiles are excluded from these counts.\n\nAsk a maintainer whether this can proceed as a minor patch or needs the [design process](https://github.com/${context.repo.owner}/${context.repo.repo}/blob/main/CONTRIBUTING.md).\n\nThis notice does not block merging or grant approval.`;
if (!existingComment) {
- const message = `${signature}\n### Contribution Scope Advisory\n\nThank you for your contribution! This PR is marked as a **Bug Fix**, but modifies **${nonTestChanges} non-test lines** across **${coreFilesCount} core definition files** (\`skills/\`, \`agents/\`).\n\nFor changes exceeding 100 non-test lines or touching 3+ core files, we recommend reaching out to maintainers first via a [Feature Inquiry Issue](https://github.com/${context.repo.owner}/${context.repo.repo}/issues/new?template=feature_proposal.md) (\`design-ready\`), merging a full EGM design document PR (\`docs/designs/<name>.md\`) authored with \`/egm-brainstorm\`, \`/egm-draft\`, and \`/egm-review\`, and then submitting the implementation PR (\`pr-ready\`).\n\n*Note: This is a non-blocking advisory; your PR remains open in the maintainer queue.*`;
await github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: pr.number,
body: message
});
+ } else if (existingComment.body !== message) {
+ await github.rest.issues.updateComment({
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ comment_id: existingComment.id,
+ body: message
+ });
}
await github.rest.issues.addLabels({
owner: context.repo.owner,
@@ -110,6 +131,13 @@ jobs:
labels: [advisoryLabel]
}).catch(() => {});
} else {
+ if (existingComment) {
+ await github.rest.issues.deleteComment({
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ comment_id: existingComment.id
+ });
+ }
// Bidirectional label cleanup if diff is trimmed or track is switched
await github.rest.issues.removeLabel({
owner: context.repo.owner,
@@ -119,6 +147,18 @@ jobs:
}).catch(() => {});
}
+ const legacyLabel = "advisory: design-doc-suggested";
+ if (pr.labels?.some(label => label.name === legacyLabel)) {
+ await github.rest.issues.removeLabel({
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ issue_number: pr.number,
+ name: legacyLabel
+ }).catch(error => {
+ if (error.status !== 404) throw error;
+ });
+ }
+
// Template conformance: the description must be the filled-in
// .github/PULL_REQUEST_TEMPLATE.md. PRs created with `gh pr create --body`
// or the API skip the template, so this catches them. Bot PRs are exempt.
@@ -131,8 +171,8 @@ jobs:
const problems = requiredHeadings
.filter(heading => !body.includes(heading))
.map(heading => `Missing section: \`${heading}\``);
- if (!/\[[xX]\]\s*\*\*(Bug Fix|Feature \/ Architectural Change)/.test(body)) {
- problems.push("No track selected under **Contribution Type**");
+ if (!hasValidTrack) {
+ problems.push("Select exactly one valid track under **Contribution Type**, using Track: or one legacy checked track");
}
if (!/\[[xX]\]\s*I am a human contributor/i.test(body)) {
problems.push("**Human Accountability Affirmation** is not checked");
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index dcb8f14..9775372 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -33,6 +33,12 @@ jobs:
with:
fetch-depth: 0
persist-credentials: false
+ - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+ with:
+ python-version: '3.12'
+ # Older release tags can predate the workflow's test dependency group.
+ - run: python -m pip install --upgrade "pip>=25.1"
+ - run: python -m pip install --group test
- name: Check out an existing tag contained in main
id: source
env:
@@ -43,10 +49,6 @@ jobs:
git merge-base --is-ancestor "refs/tags/$RELEASE_TAG^{commit}" origin/main
git checkout --detach "refs/tags/$RELEASE_TAG"
echo "commit=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
- - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
- with:
- python-version: '3.12'
- - run: python -m pip install pytest==8.3.5 pyyaml==6.0.2
- run: pytest tests/unit
- name: Prepare archives and notes
env:
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 2b4f531..640fe7c 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -75,7 +75,8 @@ jobs:
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
with:
python-version: '3.12'
- - run: pip install pytest==8.3.5 pyyaml==6.0.2
+ - run: python -m pip install --upgrade "pip>=25.1"
+ - run: python -m pip install --group test
- run: python -m pytest tests/unit
shell: bash
diff --git a/ACCESSIBILITY.md b/ACCESSIBILITY.md
new file mode 100644
index 0000000..b7912fd
--- /dev/null
+++ b/ACCESSIBILITY.md
@@ -0,0 +1,70 @@
+# Accessibility
+
+We want people with disabilities to be able to use and contribute to the
+Elephant-Goldfish Model (EGM). Accessibility reports and contributions are
+welcome.
+
+## Scope and goals
+
+This statement covers the repository's documentation, shared skill content,
+and the [EGM website](https://egm.dev).
+
+Our goal for the website is the Web Content Accessibility Guidelines
+[WCAG 2.2 Level AA](https://www.w3.org/TR/WCAG22/).
+This is a target, not a claim of verified conformance.
+
+Priorities include keyboard access, visible focus, readable text, sufficient
+contrast, clear headings and links, text alternatives, and reduced motion.
+For documentation and generated reports, prefer plain language and text that
+does not depend on color or a diagram alone to convey meaning.
+
+## Environments and current limits
+
+EGM provides Markdown skills and documentation. Its interactive experience
+runs inside a coding agent or host application. See the
+[harness guide](docs/harnesses.md) for installation and verification limits.
+Host support does not establish accessibility support.
+
+The website includes a skip link, keyboard focus styles, and reduced-motion
+styles. These features do not establish that every page is accessible.
+This statement does not certify any browser, screen reader, terminal, or
+host application combination. A comprehensive accessibility audit and
+assistive-technology test matrix have not been established for this statement.
+
+Known limits include:
+
+- Host applications control their own chat, terminal, and plugin interfaces.
+ EGM cannot correct every barrier in those interfaces.
+- Model-generated documents may contain unclear text, complex tables, or
+ diagrams without adequate text explanations. Human review is still needed.
+- Automated unit and build checks do not establish keyboard usability,
+ screen reader support, or WCAG conformance.
+
+The source documentation can be read as Markdown when a rendered view is
+difficult to use. You can also ask your coding agent for a plain-text report
+or a text explanation of a diagram. These options may help, but do not
+replace fixing the underlying barrier.
+
+## Report an accessibility barrier
+
+Use the [bug report template](https://github.com/google/elephant-goldfish-model/issues/new?template=bug_report.md)
+and identify the report as an accessibility issue. Include what you can:
+
+- The page, document, skill, or task affected.
+- What you expected and what prevented you from completing the task.
+- Steps to reproduce, including keyboard actions when relevant.
+- Browser or host, operating system, and assistive technology versions.
+- Whether a workaround exists and whether the barrier blocks a core task.
+
+Screenshots and recordings are optional. Do not include credentials, private
+project content, or medical information. Reports do not need to name a WCAG
+criterion or include a proposed fix.
+
+## Contribute accessibility improvements
+
+Follow the [contributing guide](CONTRIBUTING.md). Describe the barrier and
+record the checks performed. For website changes, check keyboard navigation,
+focus visibility, zoom and reflow, and affected screen reader behavior when
+possible. State any checks that could not be performed. Use automated checks
+alongside manual testing, and provide text alternatives for meaningful images
+and diagrams.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index bb90d21..b6e58bd 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -113,5 +113,8 @@ sign a new one.
## Community Guidelines
+See our [accessibility statement](ACCESSIBILITY.md) for goals, current limits,
+and how to report accessibility barriers.
+
This project follows
[Google's Open Source Community Guidelines](https://opensource.google/conduct/).
diff --git a/README.md b/README.md
index 2368ca7..5acc683 100644
--- a/README.md
+++ b/README.md
@@ -121,6 +121,9 @@ You can use each skill when you need it. You do not have to follow the full sequ
## Contribute
+See the [accessibility statement](https://github.com/google/elephant-goldfish-model/blob/main/ACCESSIBILITY.md)
+for accessibility goals, known limits, and how to report barriers.
+
Read [contributing](https://github.com/google/elephant-goldfish-model/blob/main/CONTRIBUTING.md) for PRs, [issues](https://github.com/google/elephant-goldfish-model/issues) for bugs, and [discussions](https://github.com/google/elephant-goldfish-model/discussions) for questions.
## License
diff --git a/TESTING.md b/TESTING.md
index fffd23a..9c607b1 100644
--- a/TESTING.md
+++ b/TESTING.md
@@ -6,6 +6,9 @@ This document provides a step-by-step developer playbook for running unit tests
## Setup
+Install Node.js 22 or newer for the offline scope-advisory workflow tests.
+These execute the workflow's JavaScript against a fake GitHub API.
+
### A. Python Environment Setup
Create and activate an isolated Python 3.10+ virtual environment:
@@ -22,8 +25,9 @@ python3 -m venv .venv
# Activate environment
source .venv/bin/activate
-# Install testing dependencies
-pip install -r requirements-dev.txt
+# Dependency groups require pip 25.1 or newer
+python -m pip install --upgrade "pip>=25.1"
+python -m pip install --group test
```
If your Python version is older than 3.10, install a newer version from [python.org/downloads](https://www.python.org/downloads/) or your system's package manager. Open a new terminal and verify the updated version before continuing. If `python3` still points to the older version, use the newer interpreter explicitly (for example, `python3.12 -m venv .venv`).
@@ -41,7 +45,8 @@ dependencies. They validate YAML frontmatter schemas and relative link
integrity, the portable plugin manifest, shared metadata consistency, and
marketplace/component paths.
-The read-hook tests also require a POSIX `sh` on `PATH`. On Windows, use
+The read-hook tests require a POSIX `sh`, and the workflow-gate tests require
+`bash` on `PATH` to execute the workflow's actual shell step. On Windows, use
Git for Windows and run the tests from Git Bash, or add its `bin` directory
(containing `sh.exe`) to `PATH` in the current PowerShell session. Create
the environment with `python -m venv .venv`, then activate it with
@@ -51,6 +56,11 @@ Shell scripts use LF line endings through `.gitattributes`, including when
Git's `core.autocrlf` is enabled. CI runs this offline suite on Ubuntu and
Windows; this does not establish native host workflow support.
+The `CI` check waits for both unit jobs and fails if validation fails, is
+cancelled, or is skipped. Workflows that include site validation must list it
+as a `CI` dependency too. A new push cancels older runs for the same pull
+request. Pushes to `main` keep independent runs.
+
```bash
# Run all unit tests
pytest tests/unit
diff --git a/distributions/claude/README.md b/distributions/claude/README.md
index 2368ca7..5acc683 100644
--- a/distributions/claude/README.md
+++ b/distributions/claude/README.md
@@ -121,6 +121,9 @@ You can use each skill when you need it. You do not have to follow the full sequ
## Contribute
+See the [accessibility statement](https://github.com/google/elephant-goldfish-model/blob/main/ACCESSIBILITY.md)
+for accessibility goals, known limits, and how to report barriers.
+
Read [contributing](https://github.com/google/elephant-goldfish-model/blob/main/CONTRIBUTING.md) for PRs, [issues](https://github.com/google/elephant-goldfish-model/issues) for bugs, and [discussions](https://github.com/google/elephant-goldfish-model/discussions) for questions.
## License
diff --git a/pyproject.toml b/pyproject.toml
index 1d4b0b3..359356b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -12,6 +12,12 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+[dependency-groups]
+test = [
+ "pytest==8.3.5",
+ "pyyaml==6.0.2",
+]
+
[tool.pytest.ini_options]
minversion = "7.0"
testpaths = ["tests/unit"]
diff --git a/requirements-dev.txt b/requirements-dev.txt
deleted file mode 100644
index 7003a3e..0000000
--- a/requirements-dev.txt
+++ /dev/null
@@ -1,17 +0,0 @@
-# Copyright 2026 Google LLC
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-# https://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-# Development and testing dependencies for EGM Open Source
-pytest>=7.4.0
-pyyaml>=6.0.1
diff --git a/tests/conftest.py b/tests/conftest.py
index 5ebc08b..50ebbf7 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -15,49 +15,21 @@
"""Shared pytest configuration and root discovery fixtures."""
import pathlib
-from typing import Any, Callable, List
+from typing import List
-try:
- import pytest
- fixture = pytest.fixture
-except ImportError:
- def fixture(*args: Any, **unused_kwargs: Any) -> Any:
- def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
- return fn
- if len(args) == 1 and callable(args[0]):
- return args[0]
- return decorator
+import pytest
-@fixture(scope="session")
[email protected](scope="session")
def repo_root() -> pathlib.Path:
- """Resolves the repository root directory across repository layouts."""
- current = pathlib.Path(__file__).resolve().parent
- for candidate in [current] + list(current.parents):
- if (candidate / "plugins" / "egm").exists():
- return candidate / "plugins" / "egm"
- if (candidate / "skills").exists() and (candidate / "agents").exists():
- return candidate
- return current.parent
+ """Return the root of this repository."""
+ return pathlib.Path(__file__).resolve().parents[1]
-@fixture(scope="session")
-def skills_dir(repo_root: pathlib.Path) -> pathlib.Path:
- """Locates the skills directory dynamically."""
- direct_path = repo_root / "skills"
- if direct_path.exists():
- return direct_path
-
- oss_path = repo_root / "plugins" / "egm" / "skills"
- if oss_path.exists():
- return oss_path
-
- raise FileNotFoundError(f"Skills directory not found relative to {repo_root}")
-
-
-@fixture(scope="session")
-def discovered_skills(skills_dir: pathlib.Path) -> List[pathlib.Path]:
[email protected](scope="session")
+def discovered_skills(repo_root: pathlib.Path) -> List[pathlib.Path]:
"""Returns all skill directory paths under the skills root."""
+ skills_dir = repo_root / "skills"
skills = [
p for p in skills_dir.iterdir()
if p.is_dir() and not p.name.startswith((".", "_"))
diff --git a/tests/scope_advisory.cjs b/tests/scope_advisory.cjs
new file mode 100644
index 0000000..15eaf23
--- /dev/null
+++ b/tests/scope_advisory.cjs
@@ -0,0 +1,221 @@
+// Copyright 2026 Google LLC.
+// SPDX-License-Identifier: Apache-2.0
+
+const assert = require('node:assert/strict')
+const { readFileSync } = require('node:fs')
+const { test } = require('node:test')
+
+const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor
+const evaluate = new AsyncFunction('github', 'context', 'core', readFileSync(0, 'utf8'))
+const signature = '<!-- egm-scope-advisory -->'
+const legacy = 'advisory: design-doc-suggested'
+
+function fixture() {
+ const state = { comments: [], labels: new Set(['ci']), changes: 101, minor: true }
+ let nextId = 1
+ const issues = {
+ listComments: async () => state.comments,
+ createComment: async ({ body }) => {
+ state.comments.push({ id: nextId++, body, user: { login: 'github-actions[bot]' } })
+ },
+ updateComment: async ({ comment_id, body }) => {
+ const comment = state.comments.find(c => c.id === comment_id)
+ assert.ok(comment, 'updated comment must exist')
+ comment.body = body
+ },
+ deleteComment: async ({ comment_id }) => {
+ assert.ok(state.comments.some(c => c.id === comment_id), 'deleted comment must exist')
+ state.comments = state.comments.filter(c => c.id !== comment_id)
+ },
+ addLabels: async ({ labels }) => labels.forEach(label => state.labels.add(label)),
+ removeLabel: async ({ name }) => {
+ if (!state.labels.delete(name)) {
+ throw Object.assign(new Error('Label not found'), { status: 404 })
+ }
+ },
+ }
+ const pulls = { listFiles: async () => [{ filename: 'src/example.js', changes: state.changes }] }
+ const github = {
+ rest: { issues, pulls },
+ paginate: async (method, args, map) => {
+ const data = await method(args)
+ return map ? map({ data }, () => {}) : data
+ },
+ }
+ state.run = async (labels = [...state.labels], cleanupError) => {
+ if (cleanupError) {
+ const removeLabel = issues.removeLabel
+ issues.removeLabel = async args => {
+ if (args.name === legacy) throw cleanupError
+ return removeLabel(args)
+ }
+ }
+ const body = [
+ '## Contribution Type',
+ state.track ?? (state.minor ? '[x] **Bug Fix / Minor Patch**' : '[x] **Feature / Architectural Change -- Stage 1: Design Doc PR**'),
+ '## Summary of Key Changes',
+ '## Human Accountability Affirmation',
+ state.affirmation ?? '[x] I am a human contributor',
+ '## Verification',
+ ].join('\n')
+ await evaluate(github, {
+ repo: { owner: 'fixture', repo: 'example' },
+ payload: { action: state.action ?? 'opened', changes: state.editedFields, pull_request: {
+ number: 1, body: state.body ?? body, user: { type: state.bot ? 'Bot' : 'User' },
+ labels: labels.map(name => ({ name })),
+ } },
+ }, { setFailed: message => assert.fail(message) })
+ }
+ return state
+}
+
+test('create, refresh and retain one notice with current scope counts', async () => {
+ const state = fixture()
+ await state.run()
+ assert.equal(state.comments.length, 1)
+ const id = state.comments[0].id
+ assert.ok(state.comments[0].body.includes(signature))
+ assert.match(state.comments[0].body, /101 counted lines/)
+ assert.ok(state.labels.has('design-needed'))
+ state.changes = 150
+ await state.run()
+ assert.equal(state.comments.length, 1)
+ assert.equal(state.comments[0].id, id)
+ assert.match(state.comments[0].body, /150 counted lines/)
+ const body = state.comments[0].body
+ await state.run()
+ assert.equal(state.comments.length, 1)
+ assert.equal(state.comments[0].id, id)
+ assert.equal(state.comments[0].body, body)
+})
+
+for (const resolution of ['trim diff', 'switch track']) {
+ test(`remove resolved notice and label: ${resolution}`, async () => {
+ const state = fixture()
+ await state.run()
+ if (resolution === 'trim diff') state.changes = 100
+ else state.minor = false
+ await state.run()
+ assert.deepEqual(state.comments, [])
+ assert.deepEqual([...state.labels], ['ci'])
+ })
+}
+
+test('user marker cannot suppress a bot notice or be updated/deleted', async () => {
+ const state = fixture()
+ const human = { id: 99, body: `${signature} User discussion`, user: { login: 'contributor' } }
+ state.comments.push(structuredClone(human))
+ for (const changes of [101, 150, 100]) {
+ state.changes = changes
+ await state.run()
+ assert.deepEqual(state.comments.find(c => c.id === human.id), human)
+ assert.equal(state.comments.length, changes > 100 ? 2 : 1)
+ const bot = state.comments.find(c => c.id !== human.id)
+ if (bot) assert.ok(bot.body.includes(`${changes} counted lines`))
+ }
+})
+
+for (const changes of [100, 101]) {
+ test(`remove legacy label while preserving unrelated labels: ${changes} lines`, async () => {
+ const state = fixture()
+ state.changes = changes
+ state.labels.add(legacy)
+ await state.run()
+ assert.ok(!state.labels.has(legacy))
+ assert.ok(state.labels.has('ci'))
+ assert.equal(state.labels.has('design-needed'), changes > 100)
+ await state.run()
+ assert.ok(!state.labels.has(legacy))
+ assert.equal(state.comments.length, changes > 100 ? 1 : 0)
+ })
+}
+
+test('stale event label does not fail cleanup', async () => {
+ const state = fixture()
+ await state.run(['ci', legacy])
+ assert.ok(!state.labels.has(legacy))
+ assert.ok(state.labels.has('design-needed'))
+})
+
+test('unexpected legacy cleanup errors remain visible', async () => {
+ const state = fixture()
+ const error = Object.assign(new Error('Forbidden'), { status: 403 })
+ await assert.rejects(state.run(['ci', legacy], error), error)
+})
+
+for (const track of [
+ 'Bug Fix / Minor Patch',
+ 'Feature / Architectural Change -- Stage 1: Design Doc PR',
+ 'Feature / Architectural Change -- Stage 2: Implementation PR',
+]) {
+ for (const selection of [`Track: ${track}`, `- [x] **${track}** (track requirements)`]) {
+ test(`accept exactly one track: ${selection}`, async () => {
+ const state = fixture()
+ state.track = selection
+ await state.run()
+ assert.equal(state.labels.has('design-needed'), track === 'Bug Fix / Minor Patch')
+ })
+ }
+}
+
+for (const track of [
+ '',
+ 'Track: ',
+ 'Track: Other',
+ '- [x] **Other**',
+ 'Track: Bug Fix / Minor Patch\nTrack: Feature / Architectural Change -- Stage 1: Design Doc PR',
+ '- [x] **Bug Fix / Minor Patch**\n- [x] **Feature / Architectural Change -- Stage 1: Design Doc PR**',
+ 'Track: Bug Fix / Minor Patch\n- [x] **Bug Fix / Minor Patch**',
+ 'Track: Other\n- [x] **Bug Fix / Minor Patch**',
+]) {
+ test(`reject missing, unknown, or conflicting tracks: ${JSON.stringify(track)}`, async () => {
+ const state = fixture()
+ state.track = track
+ await assert.rejects(state.run(), /track/i)
+ })
+}
+
+test('a track outside Contribution Type cannot satisfy the selection', async () => {
+ const state = fixture()
+ state.track = ''
+ state.affirmation = '[x] I am a human contributor\nTrack: Bug Fix / Minor Patch'
+ await assert.rejects(state.run(), /track/i)
+})
+
+test('new track descriptions still require human affirmation', async () => {
+ const state = fixture()
+ state.track = 'Track: Bug Fix / Minor Patch'
+ state.affirmation = '[ ] I am a human contributor'
+ await assert.rejects(state.run(), /Affirmation/)
+})
+
+test('bots remain exempt from description and affirmation requirements', async () => {
+ const state = fixture()
+ state.bot = true
+ state.body = ''
+ await state.run()
+})
+
+test('filled current PR template passes without deleting track explanations', async () => {
+ const state = fixture()
+ state.body = readFileSync(`${__dirname}/../.github/PULL_REQUEST_TEMPLATE.md`, 'utf8')
+ .replace('Track: <choose one track>', 'Track: Bug Fix / Minor Patch')
+ .replace('[ ] I am a human contributor', '[x] I am a human contributor')
+ await state.run()
+ assert.ok(state.labels.has('design-needed'))
+})
+
+test('body edits and title-only edits validate the current description', async () => {
+ const state = fixture()
+ state.action = 'edited'
+ state.editedFields = { body: { from: 'older description' } }
+ state.track = 'Track: Bug Fix / Minor Patch'
+ state.affirmation = '[ ] I am a human contributor'
+ await assert.rejects(state.run(), /Affirmation/)
+ state.editedFields = { title: { from: 'older title' } }
+ await assert.rejects(state.run(), /Affirmation/)
+ state.affirmation = '[x] I am a human contributor'
+ await state.run()
+ state.track = 'Track: Other'
+ await assert.rejects(state.run(), /track/i)
+})
diff --git a/tests/unit/test_ci_workflow.py b/tests/unit/test_ci_workflow.py
new file mode 100644
index 0000000..b255d3c
--- /dev/null
+++ b/tests/unit/test_ci_workflow.py
@@ -0,0 +1,72 @@
+# Copyright 2026 Google LLC.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Exercise the workflow's required-result gate without running hosted jobs."""
+
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+
+import pytest
+import yaml
+
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def workflow() -> dict:
+ return yaml.safe_load((ROOT / ".github/workflows/tests.yml").read_text())
+
+
+def test_ci_waits_for_all_validation_jobs() -> None:
+ jobs = workflow()["jobs"]
+ assert set(jobs["ci"]["needs"]) == set(jobs) - {"ci"}
+ assert jobs["ci"]["name"] == "CI"
+ assert jobs["ci"]["if"] == "${{ always() }}"
+ assert jobs["unit"]["strategy"]["fail-fast"] is False
+ assert set(jobs["unit"]["strategy"]["matrix"]["os"]) == {
+ "ubuntu-24.04", "windows-2025",
+ }
+
+
+def test_release_installs_shared_test_group_before_tag_checkout() -> None:
+ release = yaml.safe_load(
+ (ROOT / ".github/workflows/release.yml").read_text())
+ release_steps = release["jobs"]["build"]["steps"]
+ install = "python -m pip install --group test"
+ unit_steps = workflow()["jobs"]["unit"]["steps"]
+ assert install in [step.get("run") for step in unit_steps]
+ install_index = next(i for i, step in enumerate(release_steps)
+ if step.get("run") == install)
+ tag_index = next(i for i, step in enumerate(release_steps)
+ if step.get("id") == "source")
+ assert install_index < tag_index, "Older tags may not define the test group"
+
+
[email protected]("results,success", [
+ ({"unit": "success"}, True),
+ ({"unit": "failure"}, False),
+ ({"unit": "cancelled"}, False),
+ ({"unit": "skipped"}, False),
+ ({"unit": "success", "site-validation": "success"}, True),
+ ({"unit": "success", "site-validation": "failure"}, False),
+ ({"unit": "success", "site-validation": "cancelled"}, False),
+ ({"unit": "success", "site-validation": "skipped"}, False),
+])
+def test_ci_requires_successful_results(results: dict, success: bool) -> None:
+ step = workflow()["jobs"]["ci"]["steps"][0]
+ assert step["env"]["NEEDS_JSON"] == "${{ toJSON(needs) }}"
+ shell = shutil.which("bash")
+ assert shell, "POSIX bash is required for workflow shell checks"
+ completed = subprocess.run(
+ [shell, "-e", "-c", step["run"]],
+ env={**os.environ, "NEEDS_JSON": json.dumps({
+ name: {"result": result} for name, result in results.items()
+ })},
+ text=True, capture_output=True, timeout=10,
+ )
+ assert (completed.returncode == 0) is success, (
+ completed.stdout + completed.stderr
+ )
diff --git a/tests/unit/test_scope_advisory.py b/tests/unit/test_scope_advisory.py
new file mode 100644
index 0000000..eba311a
--- /dev/null
+++ b/tests/unit/test_scope_advisory.py
@@ -0,0 +1,24 @@
+# Copyright 2026 Google LLC.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Run the actual scope workflow against an offline GitHub API harness."""
+
+from pathlib import Path
+import subprocess
+
+import yaml
+
+
+def test_scope_advisory() -> None:
+ root = Path(__file__).resolve().parents[2]
+ workflow = yaml.safe_load(
+ (root / ".github/workflows/pr-scope-advisory.yml").read_text()
+ )
+ steps = workflow["jobs"]["scope-advisory"]["steps"]
+ script = next(step["with"]["script"] for step in steps
+ if step.get("uses", "").startswith("actions/github-script@"))
+ result = subprocess.run(
+ ["node", str(root / "tests/scope_advisory.cjs")],
+ input=script, capture_output=True, text=True, timeout=30,
+ )
+ assert result.returncode == 0, result.stdout + result.stderr