archive task

openspec/specs/repo-quality/spec.md

@@ -0,0 +1,49 @@
+## ADDED Requirements
+
+### Requirement: Repository exposes a clean integration test architecture
+The repository SHALL provide a top-level integration test architecture that allows runtime flows to be tested outside in-module unit tests.
+
+#### Scenario: Integration tests import the crate cleanly
+- **WHEN** an integration test under `/tests` needs to exercise repository code
+- **THEN** it imports the project through a library target rather than depending on binary-only wiring
+
+#### Scenario: Integration helpers are centralized
+- **WHEN** multiple integration tests need shared X11 or daemon helpers
+- **THEN** those helpers live in a shared test-support location under `/tests`
+- **AND** production code does not need to host integration-only support files
+
+### Requirement: CI validates real X11 integration behavior
+The repository SHALL run Xvfb-backed integration coverage in CI for the supported X11 runtime.
+
+#### Scenario: Pull requests run X11 integration tests
+- **WHEN** a pull request modifies runtime or test-relevant code
+- **THEN** CI runs the repository's Xvfb-backed integration test lane
+- **AND** fails the change if the integration lane does not pass
+
+#### Scenario: Integration lane covers core runtime flows
+- **WHEN** the Xvfb integration lane runs
+- **THEN** it exercises at least runtime diagnostics, window enumeration, and daemon startup/recovery behavior
+
+### Requirement: Repository defines one local validation workflow
+The repository SHALL define one coherent local validation workflow that contributors can run before pushing and that CI can mirror.
+
+#### Scenario: Local formatting and linting entrypoints are documented
+- **WHEN** a contributor wants to validate a change locally
+- **THEN** the repository provides documented commands for formatting, linting, unit tests, and integration tests
+
+#### Scenario: CI and local validation stay aligned
+- **WHEN** CI validates the repository
+- **THEN** it uses the same validation categories that contributors are expected to run locally
+- **AND** avoids introducing a separate undocumented CI-only workflow
+
+### Requirement: Repository uses a single hook system
+The repository SHALL standardize on one pre-commit hook workflow for contributor checks.
+
+#### Scenario: Hook workflow does not require root Node ownership
+- **WHEN** a contributor installs the hook workflow
+- **THEN** the repository can run Rust and site checks without requiring a root-level Node package workflow
+
+#### Scenario: Hook scope stays fast and focused
+- **WHEN** the pre-commit hook runs
+- **THEN** it executes only fast checks appropriate for commit-time feedback
+- **AND** slower validation remains in pre-push or CI lanes