From fc96ec3eb013e0810975decf042cd9fb108997b0 Mon Sep 17 00:00:00 2001 From: jellespijker Date: Fri, 26 Jun 2026 08:22:22 +0200 Subject: [PATCH 1/3] [EMB-463] Bootstrap agentic files and pre-commits for python-quality-control --- .github/copilot-instructions.md | 20 ++ .../code-reviewer.instructions.md | 5 + .../hardware-integration.instructions.md | 5 + .../pr-assistant.instructions.md | 6 + .../testing-automation.instructions.md | 5 + .pre-commit-config.yaml | 67 +++++++ .talismanrc | 6 + AGENTS.md | 184 ++++++++++++++++++ 8 files changed, 298 insertions(+) create mode 100644 .github/copilot-instructions.md create mode 100644 .github/copilot-instructions/code-reviewer.instructions.md create mode 100644 .github/copilot-instructions/hardware-integration.instructions.md create mode 100644 .github/copilot-instructions/pr-assistant.instructions.md create mode 100644 .github/copilot-instructions/testing-automation.instructions.md create mode 100644 .pre-commit-config.yaml create mode 100644 .talismanrc create mode 100644 AGENTS.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..ec65bb1 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,20 @@ +# GitHub Copilot Custom Instructions for python-quality-control + +Welcome! This configuration coordinates our multi-role coding assistant system to ensure that all generated code, documentation, and tests comply with `python-quality-control`'s rigorous engineering quality standards. + +## Role-Based Personas + +Depending on the context of your query, please adopt one of our specialized development personas: + +1. **[PR Assistant](.github/copilot-instructions/pr-assistant.instructions.md):** Focuses on creating logical, small, atomic commits starting with the bracketed Jira ticket key (e.g., `[EMB-463]`) and generating structured, descriptive pull request details. +2. **[Code Reviewer](.github/copilot-instructions/code-reviewer.instructions.md):** Focuses on reviewing architectural patterns (SOLID, DRY, KISS), checking for static bugs or lints, and enforcing compact files (around 300 lines, max 400 is acceptable, but prefer smaller). +3. **[Testing Automation](.github/copilot-instructions/testing-automation.instructions.md):** Focuses on pytest async tests, Jest/C++ assertions, and non-flaky testing protocols. +4. **[Hardware Integration](.github/copilot-instructions/hardware-integration.instructions.md):** Focuses on physical/virtual hardware interaction layers, dbus interfaces, sensor loops, or direct registers context. + +--- + +## Strategic Principles + +- **Future AI Optimization:** Write clean, modular files (around 300 lines, max 400 is acceptable, but prefer smaller) with single-responsibility structures. This keeps context sizes minimal and limits token overhead. +- **Secure by Design:** Actively mitigate OWASP IoT Top 10 vulnerabilities (input sanitization, safe DBus communication paths, credential separation). +- **Experimental Guardrails:** Never commit manual tests, scratch files, or temporary test scripts. diff --git a/.github/copilot-instructions/code-reviewer.instructions.md b/.github/copilot-instructions/code-reviewer.instructions.md new file mode 100644 index 0000000..43d67a8 --- /dev/null +++ b/.github/copilot-instructions/code-reviewer.instructions.md @@ -0,0 +1,5 @@ +# Code Reviewer Persona +Focus on: +- Keeping modules compact (around 300 lines). +- SOLID design principles, DRY, and KISS. +- Proper static typing (e.g., typing hints in Python, typed interfaces in C++/QML). diff --git a/.github/copilot-instructions/hardware-integration.instructions.md b/.github/copilot-instructions/hardware-integration.instructions.md new file mode 100644 index 0000000..10ecfbb --- /dev/null +++ b/.github/copilot-instructions/hardware-integration.instructions.md @@ -0,0 +1,5 @@ +# Hardware Integration Persona +Focus on: +- Safe communication path boundaries. +- invoked inside Docker containers during commit/build pipelines. +- Real-time performance checks and timing interlocks. diff --git a/.github/copilot-instructions/pr-assistant.instructions.md b/.github/copilot-instructions/pr-assistant.instructions.md new file mode 100644 index 0000000..1ea9eb2 --- /dev/null +++ b/.github/copilot-instructions/pr-assistant.instructions.md @@ -0,0 +1,6 @@ +# PR Assistant Persona +Focus on: +- Small, single-topic, functional commits. +- Every commit starts with `[EMB-XXXX]` where XXXX is the active ticket. +- Draft PR policy checkoff list. +- Upload screenshots via `gh-image` for visual changes. diff --git a/.github/copilot-instructions/testing-automation.instructions.md b/.github/copilot-instructions/testing-automation.instructions.md new file mode 100644 index 0000000..5a7a186 --- /dev/null +++ b/.github/copilot-instructions/testing-automation.instructions.md @@ -0,0 +1,5 @@ +# Testing Automation Persona +Focus on: +- Comprehensive assertions. +- pytest linter audit assertions implementation patterns. +- Mocking external hardware, DBus services, and network endpoints cleanly to avoid flakiness. diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..4e71efd --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,67 @@ +# pre-commit configuration for python-quality-control +default_stages: [commit] + +repos: + - repo: https://github.com/thoughtworks/talisman + rev: v1.32.0 + hooks: + - id: talisman-commit + + - repo: local + hooks: + - id: check-yaml + name: Check YAML Syntax + entry: |- + python3 -c ' + import sys, yaml + for f in sys.argv[1:]: + try: yaml.safe_load(open(f)) + except Exception as e: print(f"YAML Error in {f}: {e}"); sys.exit(1) + ' + language: system + files: \.(yaml|yml)$ + + - id: check-json + name: Check JSON Syntax + entry: python3 -c 'import json, sys; [json.load(open(f)) for f in sys.argv[1:]]' + language: system + files: \.json$ + - id: check-agent-artifacts + name: Check for Agent Artifacts + entry: >- + bash -c 'if [ "$SKIP_PRE_COMMIT" = "1" ]; then exit 0; fi; for f in "$@"; do if [[ "$f" =~ (task(_.*)?\.md|task\..*|implementation_plan(_.*)?\.md|implementation_plan\..*|walkthrough(_.*)?\.md|walkthrough\..*|\.playwright-cli|__pycache__|scratch_.*|scratch\..*|temp_.*|temp\..*|test_scratch_.*|test_scratch\..*|test_agent_.*|test_agent\..*|test_temp_.*|test_temp\..*|test_run_.*|test_run\..*|test_debug_.*|test_debug\..*|test_mock_.*|test_mock\..*|test_quick_.*|test_quick\..*|test_sandbox_.*|test_sandbox\..*|test_test_.*|test_test\..*|^test_[^/]+\.(py|js|ts|tsx)$) ]]; then echo "ERROR: Agent tracking/development artifact \"$f\" must not be committed to the repository."; exit 1; fi; done' -- + language: system + - id: isort + name: Sort Imports (isort - new files only) + entry: >- + bash -c 'if [ "$SKIP_PRE_COMMIT" = "1" ]; then exit 0; fi; if ! command -v isort &>/dev/null; then echo "WARNING: isort not found. Skipping import sorting."; exit 0; fi; new_files=$(git diff --cached --diff-filter=A --name-only); args=(); for f in "$@"; do if echo "$new_files" | grep -Fx "$f" >/dev/null; then args+=("$f"); fi; done; if [ ${#args[@]} -gt 0 ]; then exec isort "${args[@]}"; fi' -- + language: system + types: [python] + + - id: black + name: Format Code (black - new files only) + entry: >- + bash -c 'if [ "$SKIP_PRE_COMMIT" = "1" ]; then exit 0; fi; if ! command -v black &>/dev/null; then echo "WARNING: black not found. Skipping code formatting."; exit 0; fi; new_files=$(git diff --cached --diff-filter=A --name-only); args=(); for f in "$@"; do if echo "$new_files" | grep -Fx "$f" >/dev/null; then args+=("$f"); fi; done; if [ ${#args[@]} -gt 0 ]; then exec black "${args[@]}"; fi' -- + language: system + types: [python] + + - id: flake8 + name: Lint Code (flake8) + entry: >- + bash -c 'if [ "$SKIP_PRE_COMMIT" = "1" ]; then exit 0; fi; if ! command -v flake8 &>/dev/null; then echo "WARNING: flake8 not found. Skipping code linting."; exit 0; fi; exec flake8 "$@"' -- + language: system + types: [python] + - id: check-local-paths + name: Check for Local Path References + entry: >- + bash -c 'if [ "$SKIP_PRE_COMMIT" = "1" ]; then exit 0; fi; if [ -n "$HOME" ] && grep -FIn "$HOME" "$@" >/dev/stderr; then echo "ERROR: Staged files contain references to your local home directory ($HOME). Please use relative paths instead."; exit 1; fi; if grep -EIn "/(home|Users)/[a-zA-Z0-9_-]+" "$@" >/dev/stderr; then echo "ERROR: Staged files contain absolute local paths (e.g., /home/USER/ or /Users/USER/). Please use relative paths instead."; exit 1; fi' -- + language: system + files: \.(py|js|jsx|ts|tsx|sh|bash|md|cpp|h|qml)$ + + - id: check-jira-ticket + name: Check Jira Ticket in Commit Message + entry: >- + bash -c 'if [ "$SKIP_PRE_COMMIT" = "1" ]; then exit 0; fi; if ! grep -Ei "^\[(EMB|CES|COL|UC|NP)-[0-9]+\] " "$1" >/dev/null; then echo "ERROR: Commit message must start with a bracketed Jira ticket prefix (e.g., [EMB-463] Description)."; exit 1; fi' -- + language: system + stages: [commit-msg] + diff --git a/.talismanrc b/.talismanrc new file mode 100644 index 0000000..37318b9 --- /dev/null +++ b/.talismanrc @@ -0,0 +1,6 @@ +fileignoreconfig: +- filename: .github/copilot-instructions.md + checksum: 3a6b1ca5f8d83df36f1fce57285d3b589f1898440dc550943c57dbf6d6adb648 +- filename: AGENTS.md + checksum: ccadb976d29d469135c76b275a76e5c885b35131b5fb776c09127c5979fd0c94 +version: "" diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..31fcf7f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,184 @@ +# Agent Operational & Onboarding Guide (AGENTS.md) + +Welcome, AI Agent! This document defines the operational boundaries, design patterns, testing strategies, and collaborative conventions for the `python-quality-control` repository. + +As a dynamic assistant, you must adhere strictly to these principles to maintain codebase sanity and ensure future AI developers can read, modify, and build upon your work efficiently. + +--- + +## 1. Firmware Context & Core Business Value + +The **Python Quality Control Framework** is a crucial the centralized library holding formatting rules, style linters, and verification scripts used across all python firmware layers within the UltiMaker 3D printing ecosystem (specifically powering S-Line, Factor 4, and Factor 4+ series of professional/industrial 3D printers). + +### Business Value: +Unified quality gate preventing code formatting drifts and syntax errors across 15+ submodules. + +### Repository Ecosystem & Sibling Services: +Our engineering stack is modular and distributed across separate sibling repositories. When implementing changes, always align patterns and keep cross-repository dependencies synchronized: +- **[jedi-build](https://github.com/Ultimaker/jedi-build):** Central build orchestrator. Compiles target firmware images, packaging service debians. +- **[jedi-cookbook](https://github.com/Ultimaker/jedi-cookbook):** Contains build recipes for all packages in the ecosystem. +- **[python-quality-control](https://github.com/Ultimaker/python-quality-control):** Centralized quality gating, linting, and style analysis. +- **[stardust-embedded](https://github.com/Ultimaker/stardust-embedded):** The core IoT connectivity layer that connects our printers to the UltiMaker Digital Factory. +- **[okuda](https://github.com/Ultimaker/okuda):** The main touch-screen user interface (Qt/QML) which displays printer states and processes user inputs locally. +- **[opinicus](https://github.com/Ultimaker/opinicus):** The central print orchestrator daemon that coordinates all print jobs, hardware movements, and service states. + +--- + +## 2. How the Project is Used & Ecosystem + +### System Integration: +- `python-quality-control` operates as a shared test & lint utility on the printer's Linux environment. +- It interfaces with other components via invoked inside Docker containers during commit/build pipelines. +- It is deployed as part of the system update image (`.swu` update files) compiled by `jedi-build`. + +### 🔍 Dynamic AI Skill Discovery & Installation + +To gain expert domain context, succeeding AI agents should dynamically discover and install our organization's specialized engineering skills from the centralized repository `Ultimaker/UltiCortex` on branch `UC-3695_improve_code_base_for_agentic_development`. + +Install the relevant skills before generating code: +```bash +# Search for Ultimaker skills +gh skill search ultimaker --owner Ultimaker + +# Install specialized skills dynamically +gh skill install Ultimaker/UltiCortex ultimaker-firmware-developer +``` + +### Privacy, Compliance & Sovereignty: +- **Regional Data Sovereignty (GCP):** Strict separation exists between the US and the rest of the world. All US customer data is processed in US-based GCP regions, while the rest of the world is served from EU data centers. +- **ISO-27001 Audit Traceability:** All code changes must be strictly traceable. Do not make any changes without a corresponding tracking ticket in our Jira system. +- **PII & Data Protection:** Treat all Personally Identifiable Information (PII) as highly sensitive. Never print, log, or expose PII to debuggers or standard outputs. + +--- + +## 3. Work Tracking, Git & PR Habits + +### Jira Work Tracking: +- We use **Jira** to track all work. The Jira project keys are **`EMB`** (Embedded / Firmware team tasks), **`CES`** (Customer Engineering Support), or **`COL`** (Collaboration). +- **Rule:** Before starting any development task, you **must** check or ask for an active Jira ticket number (e.g., `EMB-463` or `CES-123`). +- **Branch Naming:** All feature/bugfix branches must start with the Jira ticket number, formatted as uppercase for the key and lowercase with underscores for the rest: + ```bash + EMB-463_improve_code_base_for_agentic_development + ``` +- **Confluence Links:** Refer to Confluence for specifications and architecture overviews: [Firmware Space](https://ultimaker.atlassian.net/wiki/spaces/SF/overview). + +### Git Commit Standards: +- **Bracketed Ticket Prefix**: Every Git commit title and GitHub Pull Request title **MUST** start with the bracketed Jira key: `[EMB-XXXX] `. +- **No Semantic Prefixes**: Do **NOT** use conventional/semantic commit prefix tags (such as `feat:`, `fix:`, `chore:`, `refactor:`, etc.) in commit titles or Pull Request titles. +- **Changelog Generation**: This prefixing standard is strictly required because the repository's CHANGELOG is automatically generated by GitHub directly from PR titles. We do **NOT** use or maintain a local `CHANGELOG.md` file. +- **Atomic Commits:** Keep commits small, single-topic, and functional. +- **Commit Message Standard:** Include the *why* (the reason the change was needed), the *how* (implementation details), and other peculiarities. + +### Pull Request & Review Flow: +- **Strict Branch Guardrails:** **Never** work on or merge directly into `main`, `master`, or `staging` branches. All development must occur on separate feature/bugfix branches. +- **Developer Review:** Every change made by an AI Agent must be thoroughly reviewed by a human developer. +- **GitHub Pull Request Requirements:** An official GitHub Pull Request must be opened in **DRAFT** state. It can only be considered merge-ready when: + 1. All automated GitHub Actions status checks show **green checkmarks**. + 2. All review topics, comments, and threads are completely **resolved**. +- **Empty Initiator Checklist:** Every pull request description must end with an empty checklist for the human dev who initiated the agent, confirming they reviewed the code. +- **Visual Evidence:** UI-impacting changes require visual evidence (screenshots/recordings) added to the PR description (uploaded via browser or `gh-image` tool). Do NOT commit media files directly into the repository. +- **Human Merge Only:** Under no circumstances should an AI agent attempt to merge its own Pull Request. Merging is **strictly restricted to humans**. + +### Support Portal Review & Alert Annotations: +- **Support Documentation Audit Rule:** When introducing a **new feature** or **changing existing behavior**, you **MUST** search the UltiMaker Support page: `https://support.makerbot.com/s/global-search/` and analyze if any relevant public-facing support pages are impacted. + - If support page changes are required, add a **warning block** (`> [!WARNING]`) in the PR description advising the developer to contact the support team. Outline exactly **what changed**, **why**, and **how**, citing any existing support page URLs. +- **PR Alert Annotations:** Always annotate pull request and merge descriptions with standard GitHub markdown alerts to guide the reviewer: + ```markdown + > [!NOTE] + > Useful information that users should know, even when skimming content. + + > [!WARNING] + > Urgent info that needs immediate user attention to avoid problems. + ``` + +--- + +## 4. Directory Organization & Tech-Stack Architecture + +### Tech-Stack: +- **Languages**: Python, Shell +- **Build/Build Tooling**: None - raw runner scripts +- **Core Frameworks**: flake8, pylint, pytest, vulture, mypy + +### Core Directory Layout: +- `/cfg/`: Linters rules configurations (.flake8, pycodestyle.ini). +- `/run_flake8.sh`: Shell executable triggers. + +--- + +## 5. Designing for Future AI Generated Code + +- **Decomposed File Footprints:** Keep individual modules and files as small as possible. Individual files (Python modules, C++ sources, headers, or QML) should ideally remain **around 300 lines (max 400 lines is acceptable)** to minimize token overhead and keep context-windows clean. +- **Leverage Third-Party Libraries:** Favor mature, well-maintained third-party frameworks and libraries instead of building custom code from scratch. Search NPM, PyPI, or Conan registries before implementing custom helpers. + +--- + +## 6. Local Development Environment & Setup + +### Requirements & Prerequisites: +Directly invoke linter hooks locally: `./run_flake8.sh ` + +--- + +## 7. Security & OWASP IoT Top 10 Mitigations + +Our software is deployed on industrial 3D printing equipment. We must actively mitigate the **OWASP IoT Top 10** vulnerabilities: + +1. **Weak, Guessable, or Hardcoded Credentials:** NEVER hardcode passwords, private keys, or API tokens. Our signing keys are backed in GCP Secret Manager and retrieved securely at runtime. +2. **Insecure Network Services:** Minimize listening ports. All local/network service interfaces must authenticate requests and utilize TLS/SSL where applicable. +3. **Insecure Ecosystem Interfaces:** Secure all API endpoints, DBus, and MQTT communication paths. Validate and sanitize all incoming payloads. +4. **Lack of Secure Update Mechanism:** S-Line/Factor 4 firmware updates use the SquashFS SWU format with detached GPG signatures. Never bypass the GPG signature check. +5. **Use of Insecure or Outdated Components:** Keep our Python packages, Conan packages, and debian dependencies up to date. +6. **Insufficient Privacy Protection:** Securely handle user profiles, PII, and telemetry. Never write passwords or sensitive tokens to local log files. +7. **Insecure Data Transfer and Storage:** Encrypt sensitive credentials and configurations. Use RAM-backed filesystems (`/dev/shm`) for temporary decryption targets. +8. **Lack of Device Management:** Integrate with UltiMaker Digital Factory securely. +9. **Insecure Default Settings:** Enforce safe defaults out-of-the-box. +10. **Lack of Physical Hardening:** Secure local terminal and SSH ports. Enforce strict `umssh.sh` password-less or authenticated connections. + +--- + +## 8. Companion Guides + +Consult the following guides found within the repository or ecosystem: +- **README.md**: Standard setup and compilation guidelines. +- None extra. + +--- + +## 9. Automated Pre-Commit Tooling & Closed-Loop Cycle + +To support a robust, automated closed-loop development cycle, this repository enforces automatic static quality checks using `pre-commit` before any git commit is recorded. + +### Core Architecture & Checks: +- **Fast Static Analysis:** Hooks run formatters, linters, and credentials scanning to ensure code quality and safety. +- **Commit Guardrails:** + 1. **Jira Ticket Reference:** Commit messages *must* reference a Jira ticket prefix. + 2. **Agent Artifact & Scratch File Block:** Blocks staging/committing agent-specific tracking files (`task.md`, `implementation_plan.md`, `walkthrough.md`, scratch files, temporary `test_` scripts). + 3. **Talisman Secret Scanner:** ThoughtWorks Talisman pre-commit scanner blocks committed credentials/secrets. + 4. **Local Paths Reference Blocker:** Prevents hardcoded local absolute path references (e.g., `/home//`). + +### Setup and Manual Use: +1. **Installation:** Ensure `pre-commit` is installed and set up: + ```bash + pip install pre-commit + pre-commit install --hook-type pre-commit --hook-type commit-msg + ``` +2. **Manual Execution:** Run checks manually on staged or all files: + ```bash + pre-commit run --all-files + ``` + +--- + +## 10. Visual Validation & Verification (V&V) Guidelines + +Every feature implementation, UI refinement, or bug fix **MUST** undergo a systematic Validation & Verification (V&V) process. + +### Scenarios to Test: +- **Happy Path Scenarios:** Verify standard successful workflows. Ensure that no console exceptions, network errors, or visual regressions occur. +- **Unhappy Path Scenarios:** Verify edge cases, input limits, and error handling (e.g., failed DBus bindings, offline state, empty profiles). +- **Physical Verification / Emulation:** Where applicable, use the `ultimaker-printer-ssh` skill to push the generated build output onto a networked test printer: + ```bash + ./deploy_to_printer.sh + ``` +- **PR Visual Evidence Mandate:** For visual changes (Okuda UI, griffin_html), provide viewport screenshots/recordings of both happy and unhappy paths in your PR description. From ce075381041835dece2bee57746757c9b5011c3b Mon Sep 17 00:00:00 2001 From: jellespijker Date: Fri, 26 Jun 2026 11:54:38 +0200 Subject: [PATCH 2/3] [EMB-463] Refactor check-yaml hook to use standard inline python entrypoint --- .pre-commit-config.yaml | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 4e71efd..9c6faa6 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -11,13 +11,7 @@ repos: hooks: - id: check-yaml name: Check YAML Syntax - entry: |- - python3 -c ' - import sys, yaml - for f in sys.argv[1:]: - try: yaml.safe_load(open(f)) - except Exception as e: print(f"YAML Error in {f}: {e}"); sys.exit(1) - ' + entry: python3 -c 'import sys, yaml; [yaml.safe_load(open(f)) for f in sys.argv[1:]]' language: system files: \.(yaml|yml)$ From e790978725e55ba91b4f5793d0d288c85740ea97 Mon Sep 17 00:00:00 2001 From: Jelle Spijker Date: Thu, 20 Aug 2026 10:41:38 +0200 Subject: [PATCH 3/3] [EMB-463] Refine agentic setup based on adversarial red team review Why: - The initial agentic bootstrap included generic firmware and hardware deployment residue (such as .swu image packaging and on-printer test execution) that does not apply to python-quality-control, which is purely a shared CI quality control submodule. - Pre-push bisect hook was failing due to false-positive test command assumptions (pytest finding 0 tests in cfg/). - Sibling consumer documentation in Rule 34 omitted 10+ consumers and did not trigger on runner scripts or linter configs. How: - Updated check_atomic_bisect_history.py to clear false test commands. - Rewrote AGENTS.md and GEMINI.md to accurately document python-quality-control as a shared CI submodule mounted across 14+ consumers. - Aligned Rule 04, Rule 15, and bootstrap-profile.json to reflect the quality verification workflow. - Updated Rule 34 (Library Consumer Contract) trigger paths and documentation to cover shell runners and linter configs across all consumers. - Integrated repository empirical observations (commit message bodies and commit size profiles) into Rule 01 and Rule 08. - Harmonized branch naming regex in git-branch-guard.py and refreshed .talismanrc checksums. --- .agents/bootstrap-profile.json | 33 +++--- .agents/hooks/check_atomic_bisect_history.py | 4 +- .agents/hooks/git-branch-guard.py | 6 +- .agents/rules/01-jira-commit-standards.md | 4 +- .../04-build-test-and-deployment-rules.md | 6 +- .../rules/06-pull-request-lifecycle-rules.md | 2 +- .../08-scoped-changes-and-minimal-diffs.md | 1 + .../15-shipped-runner-and-consumer-rules.md | 10 +- .../34-library-consumer-contract-rules.md | 75 +++++-------- .talismanrc | 20 ++-- AGENTS.md | 105 ++++++++---------- GEMINI.md | 105 ++++++++---------- 12 files changed, 165 insertions(+), 206 deletions(-) diff --git a/.agents/bootstrap-profile.json b/.agents/bootstrap-profile.json index 3ff8764..0a3cc77 100644 --- a/.agents/bootstrap-profile.json +++ b/.agents/bootstrap-profile.json @@ -53,10 +53,7 @@ "frameworks": [ "pytest" ], - "commands": [ - "cd cfg && pytest -x -q", - "./run_pytest.sh" - ] + "commands": [] }, "linters": { "ruff": false, @@ -238,50 +235,50 @@ "fired": true, "blocked": true, "detail": "staged violation rejected", - "at": "2026-08-20T07:31:15+00:00", - "sha": "ed7d5f2" + "at": "2026-08-20T08:27:48+00:00", + "sha": "ca4947b" }, "block-absolute-paths": { "fired": true, "blocked": true, "detail": "staged violation rejected", - "at": "2026-08-20T07:31:15+00:00", - "sha": "ed7d5f2" + "at": "2026-08-20T08:27:48+00:00", + "sha": "ca4947b" }, "pretool-guard": { "fired": true, "blocked": true, "detail": "secret payload denied", - "at": "2026-08-20T07:31:15+00:00", - "sha": "ed7d5f2" + "at": "2026-08-20T08:27:48+00:00", + "sha": "ca4947b" }, "block-name-matched-kill": { "fired": true, "blocked": true, "detail": "pkill denied", - "at": "2026-08-20T07:31:15+00:00", - "sha": "ed7d5f2" + "at": "2026-08-20T08:27:48+00:00", + "sha": "ca4947b" }, "check-rule-frontmatter": { "fired": true, "blocked": null, "detail": "exit 0 (advisory; executed, not violated)", - "at": "2026-08-20T07:31:15+00:00", - "sha": "ed7d5f2" + "at": "2026-08-20T08:27:48+00:00", + "sha": "ca4947b" }, "audit-quad-agent-parity": { "fired": true, "blocked": null, "detail": "exit 0 (advisory; executed, not violated)", - "at": "2026-08-20T07:31:15+00:00", - "sha": "ed7d5f2" + "at": "2026-08-20T08:27:48+00:00", + "sha": "ca4947b" }, "check-upstream-alignment": { "fired": true, "blocked": null, "detail": "exit 0 (advisory; executed, not violated)", - "at": "2026-08-20T07:31:16+00:00", - "sha": "ed7d5f2" + "at": "2026-08-20T08:27:49+00:00", + "sha": "ca4947b" } } } diff --git a/.agents/hooks/check_atomic_bisect_history.py b/.agents/hooks/check_atomic_bisect_history.py index 24a3970..8a0e231 100755 --- a/.agents/hooks/check_atomic_bisect_history.py +++ b/.agents/hooks/check_atomic_bisect_history.py @@ -85,9 +85,7 @@ def is_themeable_source(path: str) -> bool: #: This repository's build entry points, detected at bootstrap. BUILD_COMMANDS: tuple[str, ...] = () #: Its test runner, if the investigation found one. -TEST_COMMANDS: tuple[str, ...] = ( - 'cd cfg && pytest -x -q', -) +TEST_COMMANDS: tuple[str, ...] = () BUILD_TIMEOUT_SECONDS = 900 diff --git a/.agents/hooks/git-branch-guard.py b/.agents/hooks/git-branch-guard.py index 44e9762..b0e4c86 100755 --- a/.agents/hooks/git-branch-guard.py +++ b/.agents/hooks/git-branch-guard.py @@ -77,10 +77,8 @@ def is_themeable_source(path: str) -> bool: and not any(name in path for name in THEME_DEFINITION_FILES)) -# `KEY-123-short-description`: hyphens throughout, never underscores. A branch -# named `EMB-463_short_description` reads as one token to every tool -# that splits on `-`, and the convention here is hyphenated. -BRANCH_NAME_RE = re.compile(r"^EMB-\d+-[a-z0-9]+(-[a-z0-9]+)*$", re.I) +# `KEY-123-short-description` or `KEY-123_short_description` +BRANCH_NAME_RE = re.compile(r"^(EMB|CES|COL|UC|NP)-\d+[-_][a-z0-9]+([-_][a-z0-9]+)*$", re.I) def check_branch(): diff --git a/.agents/rules/01-jira-commit-standards.md b/.agents/rules/01-jira-commit-standards.md index a2aafe3..77152c0 100644 --- a/.agents/rules/01-jira-commit-standards.md +++ b/.agents/rules/01-jira-commit-standards.md @@ -10,6 +10,8 @@ trigger: always_on 2. **Commit Title Standard**: - Every commit title MUST start with bracketed Jira ticket key: `[EMB-463] `. - Do NOT use semantic commit prefixes (`feat:`, `fix:`, `chore:`, `refactor:`) in commit or PR titles. -3. **Pull Request Policy**: +3. **Commit Message Body (Why & How)**: + - Commit messages must include an explanatory body detailing the *why* (business rationale, root cause, or requirement) and the *how* (technical implementation details, affected components). +4. **Pull Request Policy**: - Always open PRs in **DRAFT** state. - Merging is strictly restricted to human developers. diff --git a/.agents/rules/04-build-test-and-deployment-rules.md b/.agents/rules/04-build-test-and-deployment-rules.md index 0b636fd..ba6db0c 100644 --- a/.agents/rules/04-build-test-and-deployment-rules.md +++ b/.agents/rules/04-build-test-and-deployment-rules.md @@ -7,9 +7,9 @@ trigger: always_on 1. **Package Registry Authentication**: - Obtain `GITHUB_TOKEN` (scope `read:packages`) for private `@ultimaker` packages via the keyring-first chain in `scripts/get_github_token.sh` — source it (`. scripts/get_github_token.sh`) instead of hand-exporting: (a) an existing env var wins, (b) else the system keyring (Linux: `secret-tool lookup service github user "$USER"`), (c) else a gitignored `.env`/`.env.local` fallback with a warning. Store it once per machine, user-specific — never a hardcoded username: `echo -n "" | secret-tool store --label="$USER-github-token" service github user "$USER"`. Never write tokens to disk, logs, or git. -2. **Test Commands (detected)**: - - `cd cfg && pytest -x -q` - - `./run_pytest.sh` +2. **Quality Verification & No In-Repo Test Suite**: + - This repository holds no standalone application code or test suite of its own. It is a shared CI quality framework mounted at `ci/` in consumer repositories. + - Verify changes using `pre-commit run --all-files`, `shellcheck`, and by verifying runner scripts against a consumer repository checkout. 3. **Artifact Isolation**: - Keep generated build outputs, intermediate binaries, and logs out of git. Ensure `.env` and `.env.local` files remain strictly gitignored. 4. **Freshness Before Evidence**: diff --git a/.agents/rules/06-pull-request-lifecycle-rules.md b/.agents/rules/06-pull-request-lifecycle-rules.md index b0997b2..0647f56 100644 --- a/.agents/rules/06-pull-request-lifecycle-rules.md +++ b/.agents/rules/06-pull-request-lifecycle-rules.md @@ -32,5 +32,5 @@ trigger: always_on This repository preserves merge topology for pull requests and feature branches to maintain ISO-27001 auditability and review history: 1. **No Force-Pushing Published Review Branches**: Do NOT rewrite history or force-push rebased commits on published branches that have already been opened for PR review. -2. **Integrate Upstream via Merge**: Integrate upstream base branch updates using `git merge origin/main` (or `/sync-base`) rather than rebasing published history. +2. **Integrate Upstream via Merge**: Integrate upstream base branch updates using `git merge origin/master` rather than rebasing published history. 3. **Draft PR Lifecycle**: PRs must remain in DRAFT status until all status checks pass and human review is complete. Merging is strictly restricted to human developers. diff --git a/.agents/rules/08-scoped-changes-and-minimal-diffs.md b/.agents/rules/08-scoped-changes-and-minimal-diffs.md index d6eba83..b32e5c3 100644 --- a/.agents/rules/08-scoped-changes-and-minimal-diffs.md +++ b/.agents/rules/08-scoped-changes-and-minimal-diffs.md @@ -8,6 +8,7 @@ trigger: always_on 1. **Strict Scope Compliance**: Make changes strictly relevant to the active Jira ticket task. Avoid scope creep. 2. **Diff Relevance Validation**: Inspect `git diff --name-only` against the base branch before committing. Revert files touched only by formatters or side-effects: `git checkout origin/ -- `. 3. **No Unrelated Refactoring**: Do not modify whitespace, formatting, or code in files unrelated to the task. Never edit `vendor/`, `third_party/`, or submodule trees. +4. **Empirical Scope Profile**: Commits in this repository are historically small and atomic (median 1 file modified per commit, 90th percentile 8 files). Keep diffs tight and focused. ## Single Responsibility PRs & Boy Scouting Branch Isolation diff --git a/.agents/rules/15-shipped-runner-and-consumer-rules.md b/.agents/rules/15-shipped-runner-and-consumer-rules.md index 4889048..8aa318a 100644 --- a/.agents/rules/15-shipped-runner-and-consumer-rules.md +++ b/.agents/rules/15-shipped-runner-and-consumer-rules.md @@ -14,13 +14,9 @@ configuration that other repositories mount as a git submodule named `ci`. `git ls-files` returns no test file and no `conftest.py`. `cfg/` holds only `.ini` and `.txt` files. -Rule `04-build-test-and-deployment-rules.md` lists two detected test commands. -Neither command tests this repository. Do not run them here. - -- `pytest -x -q cfg` collects nothing and exits with "no tests ran". -- `./run_pytest.sh` fails with `FileNotFoundError` for `./ci/cfg/pytest.ini`. - That path exists only inside a consumer, where this repository is mounted - at `ci`. +Rule `04-build-test-and-deployment-rules.md` explicitly notes that this repository has no in-repo test suite. +- `pytest` collects nothing and exits with code 5 ("no tests ran"). +- `./run_pytest.sh` fails with `FileNotFoundError` for `./ci/cfg/pytest.ini` when run locally. That path exists only inside a consumer checkout where this repository is mounted at `ci`. Verify a change to a runner script in a consumer checkout, or with `shellcheck`. State in the pull request which consumer you used. diff --git a/.agents/rules/34-library-consumer-contract-rules.md b/.agents/rules/34-library-consumer-contract-rules.md index 185cd13..3e4e951 100644 --- a/.agents/rules/34-library-consumer-contract-rules.md +++ b/.agents/rules/34-library-consumer-contract-rules.md @@ -1,59 +1,44 @@ --- name: library-consumer-contract -description: This repository's public surface is mounted into other repositories — every exported symbol, model field and schema is a cross-repository contract. +description: This repository's public surface (runner scripts, linter configs in cfg/, CI workflows) is mounted into 14+ consumer repositories — any change is a cross-repository contract. trigger: glob -glob: "**/*.py" +glob: "*.sh" paths: + - "*.sh" + - "cfg/*" + - "local/*" + - ".github/**/*" - "**/*.py" --- # Library Consumer Contract -This repository is consumed by other repositories rather than run on its own. -The evidence, from this tree: +This repository is consumed by downstream repositories rather than run on its own. +Sibling checkouts across firmware and cloud pin this repository as a submodule at `ci`: +`okuda`, `opinicus`, `dbus-interface-lib`, `libLogger`, `libCharon`, `print-process-reporting`, +`misp-service`, `ultiLib`, `libSmeagol`, `mqttHandler`, `ebpf-io-logger`, `UMBusService`, etc. -- sibling checkouts pin this repository as a submodule: `dbus-interface-lib` at `ci`, `libLogger` at `ci`, `okuda` at `ci`, `opinicus` at `ci` +A service is bounded by its own process: rename an internal function and nothing outside notices. +This repository has no such boundary. Its public surface is mounted directly into downstream builds and CI pipelines. +## Published Surface & What Constitutes a Breaking Change -A service is bounded by its own process: rename an internal function and -nothing outside notices. This repository has no such boundary. Its surface is -mounted into someone else's build, so a change here lands in trees that this -checkout cannot see and that no test in this repository runs. +Within the published surface, all of the following are contract changes, not isolated refactors: -## What that makes a breaking change +1. **Tightening Linter Configuration (`cfg/`)**: + - Adding new linter error codes or strict checks in `cfg/.flake8`, `cfg/mypy.ini`, `cfg/pylintrc`, or `cfg/pycodestyle.ini` will immediately fail CI runs across downstream repositories if their code does not comply. +2. **Modifying Runner Scripts (`run_*.sh`, `references.sh`)**: + - Renaming runner scripts, altering command-line arguments, or changing environment variable contracts (such as `PARENT_BRANCH` in `references.sh`) affects all consumers calling `./ci/run_*.sh`. +3. **Altering Submodule Layout**: + - Moving or renaming directories (`cfg/`, `local/`) breaks consumers whose scripts rely on paths like `./ci/cfg/pytest.ini`. -Within the published surface, all of the following are contract changes, -not refactors: +## How to Make Contract Changes -1. **Renaming or removing any exported symbol** — class, function, constant, - type, or module path. A consumer imports it by name. -2. **Changing a model or schema field** — removing it, renaming it, narrowing - its type, or making an optional field required. Adding an optional field - with a default is the only safe shape change. -3. **Changing a default value or an enum member**, including its wire value. -4. **Moving a file between packages**, even with the symbol re-exported: a - consumer may import the module path directly. - -## How to make one anyway - -1. **Name the consumers in the pull request.** - - `dbus-interface-lib` mounts this repository at `ci`. - - `libLogger` mounts this repository at `ci`. - - `okuda` mounts this repository at `ci`. - - `opinicus` mounts this repository at `ci`. - -2. **Land this repository first, then move each consumer's pointer.** A - submodule pointer bump is its own commit and names the revision it moves to. - Never commit inside a consumer's mounted copy of this tree. -3. **Additive first.** Where a breaking shape is unavoidable, ship the new - surface alongside the old one, migrate the consumers, and remove the old - surface in a later ticket — not in the same one. -4. **Say so in the commit message.** The consumers' agents read this - repository's history to work out what moved under them. - -## What this rule does not cover - -The *meaning* of the contract — which peer owns which definition, what happens -operationally when a field changes — is the ecosystem-contract investigator's -subject (`.agents/agents/ecosystem_contract_investigator/agent.md`). This rule -covers only what is provable from the tree: that the surface is shared, and -that a change to it is never local. +1. **Name Affected Consumers in the PR**: + - Identify which downstream repositories are affected (e.g. `opinicus`, `okuda`, `dbus-interface-lib`, `libLogger`, `libCharon`). +2. **Land Changes Here First, Then Update Consumer Pointers**: + - Merge the quality control repository changes to `master`. + - Update the `ci` submodule pointer in each consumer repository in a dedicated commit referencing the Jira ticket. +3. **Additive & Coordinated Updates**: + - When introducing stricter linter rules, test against active consumer branches and coordinate PRs to clean up lint in consumers before or alongside submodule bumps. +4. **Transparent Commit Messages**: + - Detail the changes and migration steps in the commit message so downstream developers and agents understand rule adjustments. diff --git a/.talismanrc b/.talismanrc index f5af6ba..4a4ad4c 100644 --- a/.talismanrc +++ b/.talismanrc @@ -10,7 +10,7 @@ fileignoreconfig: - filename: .agents/bootstrap-observations.md checksum: 62c476f431b689bed425deeb51e67d92f1508a736086e1addc343b38631603da - filename: .agents/bootstrap-profile.json - checksum: 204b51f61068483e07c90d7afcf5fed31668c53b325cccbea83c05fb31b11fec + checksum: ef8ca12ff4e9d4a687140cc52b4432ab72b9b91c826fa4a1ce2626374e427d02 - filename: .agents/dispatch-invariants.md checksum: 1b91951410beab17a7d0d5af02a6ae9c843359a830c099c5eaaf3b760e778b19 - filename: .agents/file-size-baseline.json @@ -26,7 +26,7 @@ fileignoreconfig: - filename: .agents/hooks/block_name_matched_kill.py checksum: 9dc2e672d8cb3c3e41c619556c769f677e2abcf0785d4bcdf74fb986b6d0b572 - filename: .agents/hooks/check_atomic_bisect_history.py - checksum: a86faf0427b44109a2ed236881e0b79fee63d600d6a2e1216410cbdbc311dcaa + checksum: a3ae05585ba4e0fcc43be192a81875ca31cd5a30cfa1481d7cbe2a1c48cab611 - filename: .agents/hooks/check_file_size_budget.py checksum: 12458e166a02055bd697567dabca58c6305f72c551610872bfe5533e949a09b3 - filename: .agents/hooks/check_multi_intent_scope.py @@ -46,7 +46,7 @@ fileignoreconfig: - filename: .agents/hooks/file_size_scope.py checksum: 51f79f03e5077d0b2bf5b19a0788129e7d9b558340582513bdbb43f08aedc998 - filename: .agents/hooks/git-branch-guard.py - checksum: 3a3bd8edf0703bd88cf1255cb71d0b26ad14aad9a22da742614a2aaf5073268c + checksum: 035b17e05a1ba8b417a067a3b1771689e755fe6caa454104be3ae3d5acfd4372 - filename: .agents/hooks/path_scanner.py checksum: 264a159d977383e6d129bb83bbdb045474115fd211f725f81e12d61ec3705d96 - filename: .agents/hooks/pretool_guard.py @@ -66,19 +66,19 @@ fileignoreconfig: - filename: .agents/rules-manifest.json checksum: 659c0ed5d99d8c7e80198490284fd4d2ffd6df56dba5d0c3cf8626fe5d3d4e01 - filename: .agents/rules/01-jira-commit-standards.md - checksum: 80261adeef03732b7c36e4a21827b425f0e55d3b230d7e71a394fa83b432ae73 + checksum: e4894f1b338b0642691a2de33f08393459ffa7a453bf5641fefefdd91b25d028 - filename: .agents/rules/02-security-and-paths.md checksum: f3279797a883e9db0ec9af65fa609a4a24c33a99e201e4c71c42804e78b6bd21 - filename: .agents/rules/04-build-test-and-deployment-rules.md - checksum: d3987760db7b17dfe74ff06b5388099c1470a5ede0ffb20b5921e2407a495f78 + checksum: e71771d4f309695b4e38ca7ae11fa514e4c6717cb6e53d982e31c47e2fc89301 - filename: .agents/rules/05-ultimaker-skill-discovery-rules.md checksum: 218b3d471b0d53add352631cc9f475e86fb0e123328ae89c60186fa2dff62da3 - filename: .agents/rules/06-pull-request-lifecycle-rules.md - checksum: 88c8179d5ecc799e25a5da68b209750f3008397ed5d670215de6ebcd8aab12fe + checksum: 4f9f9b58bfe630fe582813df71770ece2c43ba2a65eb4cd02750b315b5231f35 - filename: .agents/rules/07-owasp-security-rules.md checksum: c164300ab7cf3035f75b8df01ff1bda5978a5e7d30a19b538c854aedff525f57 - filename: .agents/rules/08-scoped-changes-and-minimal-diffs.md - checksum: 154788fb92eb0c0d00ed2aec98d48aa202eaeeea439a2fb00b6be367cb877f4a + checksum: 9e416a992918319a98c90433ba2fc736ab1729d850ca5085ec0d37f9d640c2bd - filename: .agents/rules/09-atomic-bisect-safe-commits.md checksum: d3eb665180d55754b6a03309df5be9a2e1263c02fdaa8316d12cc8a2ec60596c - filename: .agents/rules/10-file-size-and-decomposition-rules.md @@ -88,15 +88,15 @@ fileignoreconfig: - filename: .agents/rules/13-dependency-management-rules.md checksum: 0160a92aa5e698984e9bb2d7c8938c93cc5112685ad1d988b0af2a5848270f91 - filename: .agents/rules/15-shipped-runner-and-consumer-rules.md - checksum: 695ce1d794828259c5e9e3823945cbf394b7568d89b970279f17f838164be634 + checksum: 31f3d2047a5abf4ca5e5c1f3a24a6107852185042dc88609d90234c280d65bce - filename: .agents/rules/34-library-consumer-contract-rules.md - checksum: ff0fab5c48a366aed030a8f0e22b685d83bbd9d1588bc7e7bd8a1e3df7f7e7ad + checksum: 5ceb6adc316e0078ee143f2c897af9fb8249b219060922b23f91da78d92ab770 - filename: .agents/rules/40-skill-discovery-index-rules.md checksum: 2a16f2e9305a0f025c467601fadddde492c572941fa58d8b10b737c2c9db73ab - filename: .github/copilot-instructions.md checksum: 06b84a183590e20b29b7b27ec530dd380062b2a8e891b41a76a8a5e86d5fb06b - filename: AGENTS.md - checksum: ba90518e1382645af63ee8dca9f33fe880c80f794abf831971dc440cc4734f65 + checksum: c5bf5321c0eb2bc574b5bfa7b1d4cdbfb66dfcaaae3375bd6c9e2cf2bf568345 version: "1.0" threshold: medium custom_patterns: diff --git a/AGENTS.md b/AGENTS.md index 05b1834..b1f9eea 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,28 +8,28 @@ As a dynamic assistant, you must adhere strictly to these principles to maintain ## 1. Firmware Context & Core Business Value -The **Python Quality Control Framework** is a crucial the centralized library holding formatting rules, style linters, and verification scripts used across all python firmware layers within the UltiMaker 3D printing ecosystem (specifically powering S-Line, Factor 4, and Factor 4+ series of professional/industrial 3D printers). +The **Python Quality Control Framework** is the centralized repository holding shared formatting rules, style linters, and verification scripts used across 15+ Python firmware and cloud repositories within the UltiMaker ecosystem. ### Business Value: -Unified quality gate preventing code formatting drifts and syntax errors across 15+ submodules. +Unified quality gate preventing code formatting drifts and syntax errors across all downstream services and libraries. -### Repository Ecosystem & Sibling Services: -Our engineering stack is modular and distributed across separate sibling repositories. When implementing changes, always align patterns and keep cross-repository dependencies synchronized: -- **[jedi-build](https://github.com/Ultimaker/jedi-build):** Central build orchestrator. Compiles target firmware images, packaging service debians. -- **[jedi-cookbook](https://github.com/Ultimaker/jedi-cookbook):** Contains build recipes for all packages in the ecosystem. -- **[python-quality-control](https://github.com/Ultimaker/python-quality-control):** Centralized quality gating, linting, and style analysis. -- **[stardust-embedded](https://github.com/Ultimaker/stardust-embedded):** The core IoT connectivity layer that connects our printers to the UltiMaker Digital Factory. -- **[okuda](https://github.com/Ultimaker/okuda):** The main touch-screen user interface (Qt/QML) which displays printer states and processes user inputs locally. -- **[opinicus](https://github.com/Ultimaker/opinicus):** The central print orchestrator daemon that coordinates all print jobs, hardware movements, and service states. +### Repository Ecosystem & Consumer Repositories: +`python-quality-control` is mounted as a git submodule (at path `ci/`) or called directly in CI pipelines across the UltiMaker ecosystem, including: +- **[opinicus](https://github.com/Ultimaker/opinicus):** The central print orchestrator daemon. +- **[okuda](https://github.com/Ultimaker/okuda):** The touchscreen user interface daemon. +- **[dbus-interface-lib](https://github.com/Ultimaker/dbus-interface-lib):** Inter-service DBus bindings. +- **[libLogger](https://github.com/Ultimaker/libLogger):** Core structured logging library. +- **[libCharon](https://github.com/Ultimaker/libCharon):** Package and profile management service. +- **10+ additional firmware and cloud services** (`print-process-reporting`, `misp-service`, `ultiLib`, `libSmeagol`, `mqttHandler`, `ebpf-io-logger`, `UMBusService`, etc.). --- ## 2. How the Project is Used & Ecosystem ### System Integration: -- `python-quality-control` operates as a shared test & lint utility on the printer's Linux environment. -- It interfaces with other components via invoked inside Docker containers during commit/build pipelines. -- It is deployed as part of the system update image (`.swu` update files) compiled by `jedi-build`. +- `python-quality-control` is consumed as a submodule (`ci/`) by downstream repositories. +- Downstream repositories invoke `./ci/run_flake8.sh`, `./ci/run_mypy.sh`, `./ci/run_pytest.sh`, etc., from their root directories during pre-commit checks and CI workflows. +- It is executed in Docker containers and GitHub Actions runners during pull-request and build pipelines. ### 🔍 Dynamic AI Skill Discovery & Installation @@ -41,7 +41,7 @@ Install the relevant skills before generating code: gh skill search ultimaker --owner Ultimaker # Install specialized skills dynamically -gh skill install Ultimaker/UltiCortex ultimaker-firmware-developer +gh skill install Ultimaker/UltiCortex software-architect ``` ### Privacy, Compliance & Sovereignty: @@ -56,7 +56,7 @@ gh skill install Ultimaker/UltiCortex ultimaker-firmware-developer ### Jira Work Tracking: - We use **Jira** to track all work. The Jira project keys are **`EMB`** (Embedded / Firmware team tasks), **`CES`** (Customer Engineering Support), or **`COL`** (Collaboration). - **Rule:** Before starting any development task, you **must** check or ask for an active Jira ticket number (e.g., `EMB-463` or `CES-123`). -- **Branch Naming:** All feature/bugfix branches must start with the Jira ticket number, formatted as uppercase for the key and lowercase with underscores for the rest: +- **Branch Naming:** All feature/bugfix branches must start with the Jira ticket number, formatted with either underscores or hyphens: ```bash EMB-463_improve_code_base_for_agentic_development ``` @@ -65,9 +65,9 @@ gh skill install Ultimaker/UltiCortex ultimaker-firmware-developer ### Git Commit Standards: - **Bracketed Ticket Prefix**: Every Git commit title and GitHub Pull Request title **MUST** start with the bracketed Jira key: `[EMB-XXXX] `. - **No Semantic Prefixes**: Do **NOT** use conventional/semantic commit prefix tags (such as `feat:`, `fix:`, `chore:`, `refactor:`, etc.) in commit titles or Pull Request titles. +- **Commit Message Standard**: Commit messages must include an explanatory body explaining the *why* (the problem or business requirement driving the change) and the *how* (the technical implementation details). - **Changelog Generation**: This prefixing standard is strictly required because the repository's CHANGELOG is automatically generated by GitHub directly from PR titles. We do **NOT** use or maintain a local `CHANGELOG.md` file. - **Atomic Commits:** Keep commits small, single-topic, and functional. -- **Commit Message Standard:** Include the *why* (the reason the change was needed), the *how* (implementation details), and other peculiarities. ### Pull Request & Review Flow: - **Strict Branch Guardrails:** **Never** work on or merge directly into `main`, `master`, or `staging` branches. All development must occur on separate feature/bugfix branches. @@ -76,13 +76,12 @@ gh skill install Ultimaker/UltiCortex ultimaker-firmware-developer 1. All automated GitHub Actions status checks show **green checkmarks**. 2. All review topics, comments, and threads are completely **resolved**. - **Empty Initiator Checklist:** Every pull request description must end with an empty checklist for the human dev who initiated the agent, confirming they reviewed the code. -- **Visual Evidence:** UI-impacting changes require visual evidence (screenshots/recordings) added to the PR description (uploaded via browser or `gh-image` tool). Do NOT commit media files directly into the repository. - **Human Merge Only:** Under no circumstances should an AI agent attempt to merge its own Pull Request. Merging is **strictly restricted to humans**. ### Support Portal Review & Alert Annotations: -- **Support Documentation Audit Rule:** When introducing a **new feature** or **changing existing behavior**, you **MUST** search the UltiMaker Support page: `https://support.makerbot.com/s/global-search/` and analyze if any relevant public-facing support pages are impacted. - - If support page changes are required, add a **warning block** (`> [!WARNING]`) in the PR description advising the developer to contact the support team. Outline exactly **what changed**, **why**, and **how**, citing any existing support page URLs. -- **PR Alert Annotations:** Always annotate pull request and merge descriptions with standard GitHub markdown alerts to guide the reviewer: +- **Support Documentation Audit Rule:** When introducing a **new feature** or **changing existing behavior**, search the UltiMaker Support page (`https://support.makerbot.com/s/global-search/`) to evaluate whether any public documentation is impacted. + - If support page changes are required, add a **warning block** (`> [!WARNING]`) in the PR description advising the developer to contact the support team. +- **PR Alert Annotations:** Always annotate pull request and merge descriptions with standard GitHub markdown alerts: ```markdown > [!NOTE] > Useful information that users should know, even when skimming content. @@ -96,64 +95,59 @@ gh skill install Ultimaker/UltiCortex ultimaker-firmware-developer ## 4. Directory Organization & Tech-Stack Architecture ### Tech-Stack: -- **Languages**: Python, Shell -- **Build/Build Tooling**: None - raw runner scripts -- **Core Frameworks**: flake8, pylint, pytest, vulture, mypy +- **Languages**: Shell, Python +- **Build/Build Tooling**: Shell runner scripts, pre-commit +- **Core Linters & Tools**: flake8, pylint, pytest, vulture, mypy, shellcheck ### Core Directory Layout: -- `/cfg/`: Linters rules configurations (.flake8, pycodestyle.ini). -- `/run_flake8.sh`: Shell executable triggers. +- `/cfg/`: Centralized linter rule configurations (`.flake8`, `mypy.ini`, `pycodestyle.ini`, `pylintrc`, `pytest.ini`, `vulture_whitelist.py`). +- `/run_*.sh`: Shipped shell runner scripts invoked from consumer repositories (e.g. `run_flake8.sh`, `run_mypy.sh`, `run_pytest.sh`, `references.sh`). +- `/local/`: Local development variants of runner scripts. --- ## 5. Designing for Future AI Generated Code -- **Decomposed File Footprints:** Keep individual modules and files as small as possible. Individual files (Python modules, C++ sources, headers, or QML) should ideally remain **around 300 lines (max 400 lines is acceptable)** to minimize token overhead and keep context-windows clean. -- **Leverage Third-Party Libraries:** Favor mature, well-maintained third-party frameworks and libraries instead of building custom code from scratch. Search NPM, PyPI, or Conan registries before implementing custom helpers. +- **Decomposed File Footprints:** Keep individual modules and runner scripts small and modular (ideally under 300 lines, max 400 lines). +- **Consumer Compatibility:** Any change to a runner script or configuration in `cfg/` will affect all 14+ consumer repositories. Always preserve backwards compatibility or coordinate submodule updates across consumers. --- ## 6. Local Development Environment & Setup ### Requirements & Prerequisites: -Directly invoke linter hooks locally: `./run_flake8.sh ` +- This repository has no standalone test suite of its own. +- Verify shell script syntax with `shellcheck`. +- Verify changes locally with `pre-commit run --all-files`. +- To test changes end-to-end, test the updated runner scripts within a checkout of a consumer repository (e.g., `opinicus` or `okuda`). --- -## 7. Security & OWASP IoT Top 10 Mitigations +## 7. Security & OWASP Mitigations -Our software is deployed on industrial 3D printing equipment. We must actively mitigate the **OWASP IoT Top 10** vulnerabilities: - -1. **Weak, Guessable, or Hardcoded Credentials:** NEVER hardcode passwords, private keys, or API tokens. Our signing keys are backed in GCP Secret Manager and retrieved securely at runtime. -2. **Insecure Network Services:** Minimize listening ports. All local/network service interfaces must authenticate requests and utilize TLS/SSL where applicable. -3. **Insecure Ecosystem Interfaces:** Secure all API endpoints, DBus, and MQTT communication paths. Validate and sanitize all incoming payloads. -4. **Lack of Secure Update Mechanism:** S-Line/Factor 4 firmware updates use the SquashFS SWU format with detached GPG signatures. Never bypass the GPG signature check. -5. **Use of Insecure or Outdated Components:** Keep our Python packages, Conan packages, and debian dependencies up to date. -6. **Insufficient Privacy Protection:** Securely handle user profiles, PII, and telemetry. Never write passwords or sensitive tokens to local log files. -7. **Insecure Data Transfer and Storage:** Encrypt sensitive credentials and configurations. Use RAM-backed filesystems (`/dev/shm`) for temporary decryption targets. -8. **Lack of Device Management:** Integrate with UltiMaker Digital Factory securely. -9. **Insecure Default Settings:** Enforce safe defaults out-of-the-box. -10. **Lack of Physical Hardening:** Secure local terminal and SSH ports. Enforce strict `umssh.sh` password-less or authenticated connections. +1. **Weak, Guessable, or Hardcoded Credentials:** NEVER hardcode passwords, private keys, or API tokens. +2. **Input Validation:** Ensure runner shell scripts safely quote arguments and paths to avoid shell injection. +3. **Privacy & Data Protection:** Treat sensitive tokens and credentials with strict protection. Never output credentials in CI logs. +4. **Dependency Hygiene:** Keep linter dependencies and pre-commit hooks updated. --- ## 8. Companion Guides -Consult the following guides found within the repository or ecosystem: -- **README.md**: Standard setup and compilation guidelines. -- None extra. +- **README.md**: Setup and overview. +- **.agents/rules/**: Active agent rules catalog. --- ## 9. Automated Pre-Commit Tooling & Closed-Loop Cycle -To support a robust, automated closed-loop development cycle, this repository enforces automatic static quality checks using `pre-commit` before any git commit is recorded. +This repository enforces automatic static quality checks using `pre-commit` before any git commit is recorded. ### Core Architecture & Checks: - **Fast Static Analysis:** Hooks run formatters, linters, and credentials scanning to ensure code quality and safety. - **Commit Guardrails:** - 1. **Jira Ticket Reference:** Commit messages *must* reference a Jira ticket prefix. - 2. **Agent Artifact & Scratch File Block:** Blocks staging/committing agent-specific tracking files (`task.md`, `implementation_plan.md`, `walkthrough.md`, scratch files, temporary `test_` scripts). + 1. **Jira Ticket Reference:** Commit messages *must* reference a Jira ticket prefix (`[EMB-XXXX]`). + 2. **Agent Artifact Block:** Blocks staging/committing agent-specific tracking files (`task.md`, `implementation_plan.md`, `walkthrough.md`, scratch files). 3. **Talisman Secret Scanner:** ThoughtWorks Talisman pre-commit scanner blocks committed credentials/secrets. 4. **Local Paths Reference Blocker:** Prevents hardcoded local absolute path references (e.g., `/home//`). @@ -163,22 +157,19 @@ To support a robust, automated closed-loop development cycle, this repository en pip install pre-commit pre-commit install --hook-type pre-commit --hook-type commit-msg ``` -2. **Manual Execution:** Run checks manually on staged or all files: +2. **Manual Execution:** Run checks manually on all files: ```bash pre-commit run --all-files ``` --- -## 10. Visual Validation & Verification (V&V) Guidelines +## 10. Validation & Verification (V&V) Guidelines -Every feature implementation, UI refinement, or bug fix **MUST** undergo a systematic Validation & Verification (V&V) process. +Every configuration change, script update, or rule refinement **MUST** undergo systematic verification: ### Scenarios to Test: -- **Happy Path Scenarios:** Verify standard successful workflows. Ensure that no console exceptions, network errors, or visual regressions occur. -- **Unhappy Path Scenarios:** Verify edge cases, input limits, and error handling (e.g., failed DBus bindings, offline state, empty profiles). -- **Physical Verification / Emulation:** Where applicable, use the `ultimaker-printer-ssh` skill to push the generated build output onto a networked test printer: - ```bash - ./deploy_to_printer.sh - ``` -- **PR Visual Evidence Mandate:** For visual changes (Okuda UI, griffin_html), provide viewport screenshots/recordings of both happy and unhappy paths in your PR description. +- **Static Gate Verification:** Run `pre-commit run --all-files` and ensure 100% passing checks. +- **Quad-Agent Parity:** Run `python3 .agents/hooks/audit_quad_agent_parity.py .` to ensure all agent harnesses are synchronized. +- **Consumer Verification:** Test runner script execution against a consumer repository checkout to verify that `references.sh` and config files operate correctly. +- **Pre-PR Quality Gate:** Run `bash scripts/verify_and_create_pr.sh` before submitting or updating pull requests. diff --git a/GEMINI.md b/GEMINI.md index 7971769..ab71367 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -11,28 +11,28 @@ As a dynamic assistant, you must adhere strictly to these principles to maintain ## 1. Firmware Context & Core Business Value -The **Python Quality Control Framework** is a crucial the centralized library holding formatting rules, style linters, and verification scripts used across all python firmware layers within the UltiMaker 3D printing ecosystem (specifically powering S-Line, Factor 4, and Factor 4+ series of professional/industrial 3D printers). +The **Python Quality Control Framework** is the centralized repository holding shared formatting rules, style linters, and verification scripts used across 15+ Python firmware and cloud repositories within the UltiMaker ecosystem. ### Business Value: -Unified quality gate preventing code formatting drifts and syntax errors across 15+ submodules. +Unified quality gate preventing code formatting drifts and syntax errors across all downstream services and libraries. -### Repository Ecosystem & Sibling Services: -Our engineering stack is modular and distributed across separate sibling repositories. When implementing changes, always align patterns and keep cross-repository dependencies synchronized: -- **[jedi-build](https://github.com/Ultimaker/jedi-build):** Central build orchestrator. Compiles target firmware images, packaging service debians. -- **[jedi-cookbook](https://github.com/Ultimaker/jedi-cookbook):** Contains build recipes for all packages in the ecosystem. -- **[python-quality-control](https://github.com/Ultimaker/python-quality-control):** Centralized quality gating, linting, and style analysis. -- **[stardust-embedded](https://github.com/Ultimaker/stardust-embedded):** The core IoT connectivity layer that connects our printers to the UltiMaker Digital Factory. -- **[okuda](https://github.com/Ultimaker/okuda):** The main touch-screen user interface (Qt/QML) which displays printer states and processes user inputs locally. -- **[opinicus](https://github.com/Ultimaker/opinicus):** The central print orchestrator daemon that coordinates all print jobs, hardware movements, and service states. +### Repository Ecosystem & Consumer Repositories: +`python-quality-control` is mounted as a git submodule (at path `ci/`) or called directly in CI pipelines across the UltiMaker ecosystem, including: +- **[opinicus](https://github.com/Ultimaker/opinicus):** The central print orchestrator daemon. +- **[okuda](https://github.com/Ultimaker/okuda):** The touchscreen user interface daemon. +- **[dbus-interface-lib](https://github.com/Ultimaker/dbus-interface-lib):** Inter-service DBus bindings. +- **[libLogger](https://github.com/Ultimaker/libLogger):** Core structured logging library. +- **[libCharon](https://github.com/Ultimaker/libCharon):** Package and profile management service. +- **10+ additional firmware and cloud services** (`print-process-reporting`, `misp-service`, `ultiLib`, `libSmeagol`, `mqttHandler`, `ebpf-io-logger`, `UMBusService`, etc.). --- ## 2. How the Project is Used & Ecosystem ### System Integration: -- `python-quality-control` operates as a shared test & lint utility on the printer's Linux environment. -- It interfaces with other components via invoked inside Docker containers during commit/build pipelines. -- It is deployed as part of the system update image (`.swu` update files) compiled by `jedi-build`. +- `python-quality-control` is consumed as a submodule (`ci/`) by downstream repositories. +- Downstream repositories invoke `./ci/run_flake8.sh`, `./ci/run_mypy.sh`, `./ci/run_pytest.sh`, etc., from their root directories during pre-commit checks and CI workflows. +- It is executed in Docker containers and GitHub Actions runners during pull-request and build pipelines. ### 🔍 Dynamic AI Skill Discovery & Installation @@ -44,7 +44,7 @@ Install the relevant skills before generating code: gh skill search ultimaker --owner Ultimaker # Install specialized skills dynamically -gh skill install Ultimaker/UltiCortex ultimaker-firmware-developer +gh skill install Ultimaker/UltiCortex software-architect ``` ### Privacy, Compliance & Sovereignty: @@ -59,7 +59,7 @@ gh skill install Ultimaker/UltiCortex ultimaker-firmware-developer ### Jira Work Tracking: - We use **Jira** to track all work. The Jira project keys are **`EMB`** (Embedded / Firmware team tasks), **`CES`** (Customer Engineering Support), or **`COL`** (Collaboration). - **Rule:** Before starting any development task, you **must** check or ask for an active Jira ticket number (e.g., `EMB-463` or `CES-123`). -- **Branch Naming:** All feature/bugfix branches must start with the Jira ticket number, formatted as uppercase for the key and lowercase with underscores for the rest: +- **Branch Naming:** All feature/bugfix branches must start with the Jira ticket number, formatted with either underscores or hyphens: ```bash EMB-463_improve_code_base_for_agentic_development ``` @@ -68,9 +68,9 @@ gh skill install Ultimaker/UltiCortex ultimaker-firmware-developer ### Git Commit Standards: - **Bracketed Ticket Prefix**: Every Git commit title and GitHub Pull Request title **MUST** start with the bracketed Jira key: `[EMB-XXXX] `. - **No Semantic Prefixes**: Do **NOT** use conventional/semantic commit prefix tags (such as `feat:`, `fix:`, `chore:`, `refactor:`, etc.) in commit titles or Pull Request titles. +- **Commit Message Standard**: Commit messages must include an explanatory body explaining the *why* (the problem or business requirement driving the change) and the *how* (the technical implementation details). - **Changelog Generation**: This prefixing standard is strictly required because the repository's CHANGELOG is automatically generated by GitHub directly from PR titles. We do **NOT** use or maintain a local `CHANGELOG.md` file. - **Atomic Commits:** Keep commits small, single-topic, and functional. -- **Commit Message Standard:** Include the *why* (the reason the change was needed), the *how* (implementation details), and other peculiarities. ### Pull Request & Review Flow: - **Strict Branch Guardrails:** **Never** work on or merge directly into `main`, `master`, or `staging` branches. All development must occur on separate feature/bugfix branches. @@ -79,13 +79,12 @@ gh skill install Ultimaker/UltiCortex ultimaker-firmware-developer 1. All automated GitHub Actions status checks show **green checkmarks**. 2. All review topics, comments, and threads are completely **resolved**. - **Empty Initiator Checklist:** Every pull request description must end with an empty checklist for the human dev who initiated the agent, confirming they reviewed the code. -- **Visual Evidence:** UI-impacting changes require visual evidence (screenshots/recordings) added to the PR description (uploaded via browser or `gh-image` tool). Do NOT commit media files directly into the repository. - **Human Merge Only:** Under no circumstances should an AI agent attempt to merge its own Pull Request. Merging is **strictly restricted to humans**. ### Support Portal Review & Alert Annotations: -- **Support Documentation Audit Rule:** When introducing a **new feature** or **changing existing behavior**, you **MUST** search the UltiMaker Support page: `https://support.makerbot.com/s/global-search/` and analyze if any relevant public-facing support pages are impacted. - - If support page changes are required, add a **warning block** (`> [!WARNING]`) in the PR description advising the developer to contact the support team. Outline exactly **what changed**, **why**, and **how**, citing any existing support page URLs. -- **PR Alert Annotations:** Always annotate pull request and merge descriptions with standard GitHub markdown alerts to guide the reviewer: +- **Support Documentation Audit Rule:** When introducing a **new feature** or **changing existing behavior**, search the UltiMaker Support page (`https://support.makerbot.com/s/global-search/`) to evaluate whether any public documentation is impacted. + - If support page changes are required, add a **warning block** (`> [!WARNING]`) in the PR description advising the developer to contact the support team. +- **PR Alert Annotations:** Always annotate pull request and merge descriptions with standard GitHub markdown alerts: ```markdown > [!NOTE] > Useful information that users should know, even when skimming content. @@ -99,64 +98,59 @@ gh skill install Ultimaker/UltiCortex ultimaker-firmware-developer ## 4. Directory Organization & Tech-Stack Architecture ### Tech-Stack: -- **Languages**: Python, Shell -- **Build/Build Tooling**: None - raw runner scripts -- **Core Frameworks**: flake8, pylint, pytest, vulture, mypy +- **Languages**: Shell, Python +- **Build/Build Tooling**: Shell runner scripts, pre-commit +- **Core Linters & Tools**: flake8, pylint, pytest, vulture, mypy, shellcheck ### Core Directory Layout: -- `/cfg/`: Linters rules configurations (.flake8, pycodestyle.ini). -- `/run_flake8.sh`: Shell executable triggers. +- `/cfg/`: Centralized linter rule configurations (`.flake8`, `mypy.ini`, `pycodestyle.ini`, `pylintrc`, `pytest.ini`, `vulture_whitelist.py`). +- `/run_*.sh`: Shipped shell runner scripts invoked from consumer repositories (e.g. `run_flake8.sh`, `run_mypy.sh`, `run_pytest.sh`, `references.sh`). +- `/local/`: Local development variants of runner scripts. --- ## 5. Designing for Future AI Generated Code -- **Decomposed File Footprints:** Keep individual modules and files as small as possible. Individual files (Python modules, C++ sources, headers, or QML) should ideally remain **around 300 lines (max 400 lines is acceptable)** to minimize token overhead and keep context-windows clean. -- **Leverage Third-Party Libraries:** Favor mature, well-maintained third-party frameworks and libraries instead of building custom code from scratch. Search NPM, PyPI, or Conan registries before implementing custom helpers. +- **Decomposed File Footprints:** Keep individual modules and runner scripts small and modular (ideally under 300 lines, max 400 lines). +- **Consumer Compatibility:** Any change to a runner script or configuration in `cfg/` will affect all 14+ consumer repositories. Always preserve backwards compatibility or coordinate submodule updates across consumers. --- ## 6. Local Development Environment & Setup ### Requirements & Prerequisites: -Directly invoke linter hooks locally: `./run_flake8.sh ` +- This repository has no standalone test suite of its own. +- Verify shell script syntax with `shellcheck`. +- Verify changes locally with `pre-commit run --all-files`. +- To test changes end-to-end, test the updated runner scripts within a checkout of a consumer repository (e.g., `opinicus` or `okuda`). --- -## 7. Security & OWASP IoT Top 10 Mitigations +## 7. Security & OWASP Mitigations -Our software is deployed on industrial 3D printing equipment. We must actively mitigate the **OWASP IoT Top 10** vulnerabilities: - -1. **Weak, Guessable, or Hardcoded Credentials:** NEVER hardcode passwords, private keys, or API tokens. Our signing keys are backed in GCP Secret Manager and retrieved securely at runtime. -2. **Insecure Network Services:** Minimize listening ports. All local/network service interfaces must authenticate requests and utilize TLS/SSL where applicable. -3. **Insecure Ecosystem Interfaces:** Secure all API endpoints, DBus, and MQTT communication paths. Validate and sanitize all incoming payloads. -4. **Lack of Secure Update Mechanism:** S-Line/Factor 4 firmware updates use the SquashFS SWU format with detached GPG signatures. Never bypass the GPG signature check. -5. **Use of Insecure or Outdated Components:** Keep our Python packages, Conan packages, and debian dependencies up to date. -6. **Insufficient Privacy Protection:** Securely handle user profiles, PII, and telemetry. Never write passwords or sensitive tokens to local log files. -7. **Insecure Data Transfer and Storage:** Encrypt sensitive credentials and configurations. Use RAM-backed filesystems (`/dev/shm`) for temporary decryption targets. -8. **Lack of Device Management:** Integrate with UltiMaker Digital Factory securely. -9. **Insecure Default Settings:** Enforce safe defaults out-of-the-box. -10. **Lack of Physical Hardening:** Secure local terminal and SSH ports. Enforce strict `umssh.sh` password-less or authenticated connections. +1. **Weak, Guessable, or Hardcoded Credentials:** NEVER hardcode passwords, private keys, or API tokens. +2. **Input Validation:** Ensure runner shell scripts safely quote arguments and paths to avoid shell injection. +3. **Privacy & Data Protection:** Treat sensitive tokens and credentials with strict protection. Never output credentials in CI logs. +4. **Dependency Hygiene:** Keep linter dependencies and pre-commit hooks updated. --- ## 8. Companion Guides -Consult the following guides found within the repository or ecosystem: -- **README.md**: Standard setup and compilation guidelines. -- None extra. +- **README.md**: Setup and overview. +- **.agents/rules/**: Active agent rules catalog. --- ## 9. Automated Pre-Commit Tooling & Closed-Loop Cycle -To support a robust, automated closed-loop development cycle, this repository enforces automatic static quality checks using `pre-commit` before any git commit is recorded. +This repository enforces automatic static quality checks using `pre-commit` before any git commit is recorded. ### Core Architecture & Checks: - **Fast Static Analysis:** Hooks run formatters, linters, and credentials scanning to ensure code quality and safety. - **Commit Guardrails:** - 1. **Jira Ticket Reference:** Commit messages *must* reference a Jira ticket prefix. - 2. **Agent Artifact & Scratch File Block:** Blocks staging/committing agent-specific tracking files (`task.md`, `implementation_plan.md`, `walkthrough.md`, scratch files, temporary `test_` scripts). + 1. **Jira Ticket Reference:** Commit messages *must* reference a Jira ticket prefix (`[EMB-XXXX]`). + 2. **Agent Artifact Block:** Blocks staging/committing agent-specific tracking files (`task.md`, `implementation_plan.md`, `walkthrough.md`, scratch files). 3. **Talisman Secret Scanner:** ThoughtWorks Talisman pre-commit scanner blocks committed credentials/secrets. 4. **Local Paths Reference Blocker:** Prevents hardcoded local absolute path references (e.g., `/home//`). @@ -166,22 +160,19 @@ To support a robust, automated closed-loop development cycle, this repository en pip install pre-commit pre-commit install --hook-type pre-commit --hook-type commit-msg ``` -2. **Manual Execution:** Run checks manually on staged or all files: +2. **Manual Execution:** Run checks manually on all files: ```bash pre-commit run --all-files ``` --- -## 10. Visual Validation & Verification (V&V) Guidelines +## 10. Validation & Verification (V&V) Guidelines -Every feature implementation, UI refinement, or bug fix **MUST** undergo a systematic Validation & Verification (V&V) process. +Every configuration change, script update, or rule refinement **MUST** undergo systematic verification: ### Scenarios to Test: -- **Happy Path Scenarios:** Verify standard successful workflows. Ensure that no console exceptions, network errors, or visual regressions occur. -- **Unhappy Path Scenarios:** Verify edge cases, input limits, and error handling (e.g., failed DBus bindings, offline state, empty profiles). -- **Physical Verification / Emulation:** Where applicable, use the `ultimaker-printer-ssh` skill to push the generated build output onto a networked test printer: - ```bash - ./deploy_to_printer.sh - ``` -- **PR Visual Evidence Mandate:** For visual changes (Okuda UI, griffin_html), provide viewport screenshots/recordings of both happy and unhappy paths in your PR description. +- **Static Gate Verification:** Run `pre-commit run --all-files` and ensure 100% passing checks. +- **Quad-Agent Parity:** Run `python3 .agents/hooks/audit_quad_agent_parity.py .` to ensure all agent harnesses are synchronized. +- **Consumer Verification:** Test runner script execution against a consumer repository checkout to verify that `references.sh` and config files operate correctly. +- **Pre-PR Quality Gate:** Run `bash scripts/verify_and_create_pr.sh` before submitting or updating pull requests.