From 83ad855acbf7e545ff11e86330c0f0fb289d7efc Mon Sep 17 00:00:00 2001 From: Jeffrey Phillips Freeman Date: Wed, 15 Apr 2026 18:25:13 +0000 Subject: [PATCH] docs(skill): generalise SKILL.md for any programming language Remove project-specific src/cleveragents/ path (now src// with examples). Replace all bare nox/Pyright/ruff/Behave references with the language-agnostic 'task runner / type checker / linter / BDD framework' abstractions, keeping the project-specific tool as a parenthetical example. Add ecosystem-equivalents reference table (Python, JS/TS, Java/Kotlin, Go) in the Quick Command Reference. Generalise type-suppression rules across languages (# type: ignore, @ts-ignore, @SuppressWarnings). Generalise TDD assertion failure type requirement with Python, Java, and JS examples. Generalise import rules, project manifest references, and directory layout descriptions. Remove Python-only step-file naming; add multi-language examples throughout. LangChain/LangGraph and v3/legacy plan workflow sections are left as-is and clearly labelled as project-specific. ISSUES CLOSED: #0 --- .../skills/cleverthis-guidelines/SKILL.md | 542 ++++++++++-------- 1 file changed, 306 insertions(+), 236 deletions(-) diff --git a/.opencode/skills/cleverthis-guidelines/SKILL.md b/.opencode/skills/cleverthis-guidelines/SKILL.md index fd95b678c..532b1f55d 100644 --- a/.opencode/skills/cleverthis-guidelines/SKILL.md +++ b/.opencode/skills/cleverthis-guidelines/SKILL.md @@ -16,22 +16,28 @@ description: | contributing to CleverThis. Covers: commit format and quality rules, pull request requirements and merge - criteria, BDD testing with Behave (unit) and Robot Framework (integration), - coverage threshold (97% project-specific), Pyright type checking, nox task - runner commands (all sessions), CI/CD pipeline (all jobs + required gates), - issue hierarchy (Issue→Epic→Legendary), label system (State/Priority/MoSCoW/ - Type/), ticket lifecycle, sprint structure (2-week, 1st and 15th), DSDM - triaging, MoSCoW prioritization, point estimation (poker points), branch - naming conventions (feature/mN-, bugfix/mN-, tdd/mN-), TDD bug fix workflow - with exact tag validation rules (AssertionError requirement), file organization - (src/ features/ robot/ docs/ config/ scripts/ examples/ k8s/), documentation - traceability rules (no line numbers, module.class.method + commit hash), - code style principles, SOLID patterns, error handling rules, security policies - (gopass, Yubikey, encryption), confidentiality levels (Restricted/Secret/Trade - Secret/Confidential/Public), organizational structure, boards (ELB/OCRB), - committees (12 committees), FOSS policies, open standards mandate, backwards - compatibility policy (none pre-v3.0.0), v3 vs legacy plan workflow, - LangChain/LangGraph guidelines, and definition of done. + criteria, BDD testing (project uses Behave for unit and Robot Framework for + integration), coverage threshold (97% project-specific), static type checking + (project uses Pyright), task runner commands (project uses nox), CI/CD pipeline + (all jobs + required gates), issue hierarchy (Issue→Epic→Legendary), label + system (State/Priority/MoSCoW/Type/), ticket lifecycle, sprint structure + (2-week, 1st and 15th), DSDM triaging, MoSCoW prioritization, point estimation + (poker points), branch naming conventions (feature/mN-, bugfix/mN-, tdd/mN-), + TDD bug fix workflow with exact tag validation rules (assertion failure type + requirement), file organization (src/ test/ docs/ config/ scripts/ examples/), + documentation traceability rules (no line numbers, logical module path + + commit hash), code style principles, SOLID patterns, error handling rules, + security policies (gopass, Yubikey, encryption), confidentiality levels + (Restricted/Secret/Trade Secret/Confidential/Public), organizational structure, + boards (ELB/OCRB), committees (12 committees), FOSS policies, open standards + mandate, backwards compatibility policy, project-specific CLI workflow + (v3 vs legacy), AI framework guidelines (LangChain/LangGraph), and + definition of done. + + All tooling references are framed as project-specific examples. The rules + themselves apply universally; specific tools (nox, Pyright, ruff, Behave, + Robot Framework) are the current project's choices for a Python codebase, with + equivalents for other language ecosystems noted throughout. references: - commits - pull-requests @@ -59,39 +65,58 @@ and the project-specific **CONTRIBUTING.md**. ## ⚡ Quick Command Reference +> **Language / tooling note:** The commands below are the **project-specific** examples +> using Python and nox. The underlying principle applies to any language: **always use +> the project's designated task runner** — never invoke linters, type checkers, or test +> frameworks directly. Common equivalents by ecosystem: +> +> | Concern | Python *(this project)* | JavaScript / TypeScript | Java / Kotlin | Go | +> |---------|------------------------|------------------------|---------------|----| +> | Task runner | `nox` | `npm run` / `pnpm run` | Gradle / Maven | `make` / `mage` | +> | Linter | ruff | ESLint / Biome | Checkstyle / Detekt | golangci-lint | +> | Formatter | ruff format | Prettier | google-java-format | gofmt | +> | Type checker | Pyright | tsc (strict) | javac / kotlinc | built-in | +> | Unit tests (BDD) | Behave | jest-cucumber / vitest | Cucumber-JVM | godog | +> | Integration tests | Robot Framework | Playwright / Cypress | Selenium | `go test` (tagged) | +> | Coverage | Slipcover | Istanbul / c8 | JaCoCo | `go test -cover` | +> | Security scan | bandit + semgrep | npm audit + semgrep | SpotBugs | gosec | +> | Benchmarks | ASV | Benchmark.js | JMH | `go test -bench` | +> | Build / package | hatch build | npm pack / vite build | `./gradlew build` | `go build` | +> | Docs | MkDocs | VitePress / Docusaurus | Javadoc | pkg.go.dev | + ```bash -# Run ALL quality gates (must pass before any PR) +# Run ALL quality gates (must pass before any PR) — Python/nox: nox # Core quality sessions: -nox -s lint # ruff linting + format check -nox -s format # auto-format code with ruff -nox -s format -- --check # check formatting only (no changes) — used in CI -nox -s typecheck # Pyright type checking (strict, no suppressions) -nox -s security_scan # bandit + semgrep + vulture -nox -s dead_code # vulture dead code detection +nox -s lint # linting + format check (ruff) +nox -s format # auto-format code (ruff) +nox -s format -- --check # check formatting only, no changes — CI mode +nox -s typecheck # static type checking (Pyright, strict, no suppressions) +nox -s security_scan # security scan (bandit + semgrep + vulture) +nox -s dead_code # dead code detection (vulture) # Test sessions: -nox -s unit_tests # Behave BDD unit tests (features/) -nox -s integration_tests # Robot Framework via pabot (robot/) -nox -s e2e_tests # End-to-end Robot tests with real LLM keys -nox -s coverage_report # Slipcover coverage report (must be ≥ 97%) -nox -s benchmark # Airspeed Velocity (ASV) performance benchmarks -nox -s benchmark_regression # ASV benchmark regression check (PRs only) +nox -s unit_tests # BDD unit tests (Behave — features/) +nox -s integration_tests # integration tests (Robot Framework via pabot — robot/) +nox -s e2e_tests # end-to-end tests with real external credentials +nox -s coverage_report # coverage report (Slipcover — must be ≥ 97%) +nox -s benchmark # performance benchmarks (Airspeed Velocity) +nox -s benchmark_regression # benchmark regression check (PRs only) # Analysis sessions: -nox -s complexity # Radon complexity analysis (nightly quality sweep) +nox -s complexity # code complexity (Radon — nightly quality sweep) -# Build/docs sessions: -nox -s docs # build documentation with MkDocs -nox -s build # build wheel distribution +# Build / docs sessions: +nox -s docs # build documentation (MkDocs) +nox -s build # build distributable (wheel) -# Setup dev environment (installs pre-commit hooks): -scripts/setup-dev.sh +# Dev environment setup: +scripts/setup-dev.sh # installs pre-commit hooks -# Install Commitizen (interactive commit messages): +# Conventional commit message helper (works for any language project): npm install -g commitizen@2.8.6 cz-customizable@4.0.0 -git cz # use instead of git commit +git cz # interactive commit — replaces git commit # Release (triggers CI release.yml workflow): git tag v3.6.0 && git push origin v3.6.0 @@ -109,7 +134,7 @@ What are you about to do? ├─ Write or commit code │ ├─ Before writing → "Am I about to write code?" tree below │ ├─ Before committing → "Am I about to commit?" tree below -│ └─ About to push → run nox first, verify all gates pass +│ └─ About to push → run the task runner first (e.g. nox), verify all gates pass │ ├─ Create or update an issue/ticket │ ├─ New issue → "Am I creating an issue?" tree below @@ -213,23 +238,33 @@ Before writing any code: │ ├─ Code style checklist (before writing): │ ├─ Write tests BEFORE implementation (test-first, no exceptions) -│ ├─ Is this Python? → use full type annotations everywhere -│ ├─ Will code be in src/ only? (no mocks/test-data in production src/) +│ ├─ Use the language's type system fully — no inline suppression of type errors: +│ │ ├─ Python → full type annotations on all functions, variables, and returns +│ │ ├─ TypeScript → strict mode enabled; avoid `any` +│ │ ├─ Java / C# / Kotlin → rely on compiler types; use generics appropriately +│ │ └─ No type-suppression comments regardless of language +│ │ (Python: # type: ignore | TS: // @ts-ignore | Java: @SuppressWarnings) +│ ├─ Production source only in src/ — no mocks or test data there │ ├─ Are you using SOLID principles? (see references/code-style/) │ └─ File under 500 lines? (break into modules if approaching limit) │ -├─ Is this LangChain/LangGraph code? +├─ Is this LangChain/LangGraph code? (project-specific — this project uses Python LangGraph) │ ├─ Use TypedDict for state, verb-based node names │ ├─ Use BaseLanguageModel / BaseLLM unified interfaces │ ├─ Always use MemorySaver for checkpointing │ ├─ Use ChatPromptTemplate or PromptTemplate for prompts │ └─ See references/code-style/README.md (LangChain/LangGraph section) │ -└─ Import rules: - ├─ All imports at top of file, never inside functions/methods - ├─ Never inside if/try/for blocks - ├─ Exception: TYPE_CHECKING only for circular-dependency avoidance - └─ Prefer specific symbols: from module import ClassName +└─ Dependency / import declaration rules: + ├─ Declare all imports/dependencies at the top of the file (language-idiomatic) + ├─ Never scatter them throughout code or bury them inside functions or blocks + ├─ Prefer specific imports over wildcard or whole-module imports: + │ ├─ Python: from module import ClassName (not import *) + │ ├─ Java: explicit class imports (not import java.util.*) + │ └─ TypeScript: import { Foo } from './foo' (named imports) + └─ Exception: type-only imports for circular-dependency avoidance + ├─ Python: if TYPE_CHECKING: block + └─ TypeScript: import type { Foo } from './foo' ``` ### "Am I about to commit?" @@ -240,11 +275,11 @@ Before every commit: ├─ Have all tests been written for this change? │ └─ NO → Write tests first (test-first development) │ -├─ Run quality gates: -│ ├─ nox -s lint → must be green -│ ├─ nox -s typecheck → must be green (Pyright, no suppressions) -│ ├─ nox -s unit_tests → must be green -│ └─ nox -s coverage_report → must be ≥ 97% +├─ Run quality gates (use the task runner — see "What task runner session should I run?"): +│ ├─ Lint session → must be green (e.g. nox -s lint) +│ ├─ Type check session → must be green, no inline suppressions (e.g. nox -s typecheck) +│ ├─ Unit test session → must be green (e.g. nox -s unit_tests) +│ └─ Coverage session → must be ≥ 97% (e.g. nox -s coverage_report) │ ├─ Self-review the diff: │ ├─ Only intended changes staged? (use git add -p) @@ -282,9 +317,10 @@ Before every commit: PR submission checklist (ALL must be true): │ ├─ CODE QUALITY -│ ├─ nox (full suite) passes with zero failures -│ ├─ Coverage ≥ 97% (nox -s coverage_report) -│ ├─ No type: ignore suppressions anywhere +│ ├─ Task runner full suite passes with zero failures (e.g. nox) +│ ├─ Coverage ≥ 97% (e.g. nox -s coverage_report) +│ ├─ No inline type-checking suppressions anywhere +│ │ (Python: # type: ignore | TypeScript: // @ts-ignore | Java: @SuppressWarnings) │ └─ All pre-commit hooks pass │ ├─ COMMIT STRUCTURE @@ -351,7 +387,7 @@ Code review responsibilities: │ ├─ Readability: clear names, easy to follow, no magic numbers? │ ├─ Performance: no unnecessary inefficiencies or N+1 problems? │ ├─ Security: no vulnerabilities, secrets, or unsafe patterns? -│ ├─ Style: follows project coding standards (ruff, Pyright)? +│ ├─ Style: follows project coding standards (linter, type checker)? │ ├─ Tests: adequate coverage? edge cases covered? error paths tested? │ ├─ Coverage: does coverage remain ≥ 97%? │ └─ Documentation: updated alongside code changes? @@ -541,19 +577,20 @@ Work is DONE only when ALL of the following are true: │ └─ All subtasks in the issue checklist are checked off │ ├─ TESTS (MANDATORY) -│ ├─ BDD Behave scenarios written BEFORE implementation (test-first) +│ ├─ BDD scenarios written BEFORE implementation (project uses Behave; +│ │ other frameworks: Cucumber, SpecFlow, pytest-bdd, rspec, godog) │ ├─ Unit tests cover all non-trivial logic paths │ ├─ Integration tests updated/added if component interfaces changed -│ ├─ nox -s unit_tests → green -│ ├─ nox -s integration_tests → green -│ └─ nox -s coverage_report → ≥ 97% (project-specific threshold) +│ ├─ Task runner unit test session → green (e.g. nox -s unit_tests) +│ ├─ Task runner integration test session → green (e.g. nox -s integration_tests) +│ └─ Task runner coverage session → ≥ 97% (e.g. nox -s coverage_report) │ ├─ CODE QUALITY -│ ├─ nox -s lint → green (ruff, no suppressions) -│ ├─ nox -s typecheck → green (Pyright, no type: ignore) -│ ├─ nox -s security_scan → green -│ ├─ nox -s dead_code → no new dead code introduced -│ └─ nox (full default suite) → all green +│ ├─ Task runner lint session → green, no suppressions (e.g. nox -s lint) +│ ├─ Task runner type check session → green, no inline suppressions (e.g. nox -s typecheck) +│ ├─ Task runner security scan session → green (e.g. nox -s security_scan) +│ ├─ Task runner dead code session → no new dead code (e.g. nox -s dead_code) +│ └─ Task runner full default suite → all green (e.g. nox) │ ├─ COMMIT AND PR │ ├─ Atomic commit with correct Conventional Changelog format @@ -568,7 +605,8 @@ Work is DONE only when ALL of the following are true: │ ├─ DOCUMENTATION │ ├─ Documentation updated alongside code in same commit -│ ├─ References use module.class.method (never line numbers) +│ ├─ References use logical module path — never line numbers +│ │ └─ Python example: mypackage.services.plan_service.PlanService.execute │ ├─ Changelog has one new entry for this commit │ └─ CONTRIBUTORS.md updated if first contribution │ @@ -723,37 +761,40 @@ Testing requirements (MANDATORY at all levels): │ ├─ Tests go in same commit as the implementation they test │ └─ Never commit implementation without its tests │ -├─ UNIT TESTS (Behave / BDD / Gherkin) -│ ├─ Framework: Behave (Cucumber/Gherkin standard) -│ ├─ Location: features/ directory ONLY -│ ├─ Mocks/fakes location: features/mocks/ subdirectory -│ ├─ DO NOT write xUnit-style tests (pytest assertions alone, JUnit, etc.) -│ ├─ All unit-level tests = Gherkin feature files + step definitions +├─ UNIT TESTS — BDD / Gherkin (project uses Behave) +│ ├─ All unit-level tests must follow Behavior-Driven Development (BDD) +│ ├─ Framework: project uses Behave; other options: Cucumber, SpecFlow, pytest-bdd, rspec, godog +│ ├─ Test format: human-readable Gherkin feature files + step definitions +│ ├─ Location: designated unit test directory (project: features/) +│ ├─ Mock/fake location: mock subdirectory within test dir (project: features/mocks/) +│ ├─ DO NOT write xUnit-style tests (raw assertions without BDD structure) │ ├─ Step files: group by feature, add to existing files before creating new -│ ├─ Steps for foo.feature → foo_steps.py; shared steps → reusable named file -│ ├─ Never commit placeholder steps (all steps must be implemented) -│ ├─ Mocks/fakes/stubs: allowed in unit tests, location: features/mocks/ ONLY -│ ├─ Run via: nox -s unit_tests -│ └─ Coverage threshold: ≥ 97% (measured by nox -s coverage_report) +│ ├─ Name step files after their feature (Python example: foo_steps.py for foo.feature) +│ ├─ Never commit placeholder steps (all steps must be fully implemented) +│ ├─ Mocks/fakes/stubs: allowed ONLY in unit tests, in the designated mock location +│ ├─ Run via: task runner unit test session (e.g. nox -s unit_tests) +│ └─ Coverage threshold: ≥ 97% (e.g. nox -s coverage_report) │ -├─ INTEGRATION TESTS (Robot Framework) -│ ├─ Framework: Robot Framework via pabot (parallel) -│ ├─ Location: robot/ directory -│ ├─ Run via: nox -s integration_tests +├─ INTEGRATION TESTS (project uses Robot Framework) +│ ├─ Framework: keyword-driven integration tests (project: Robot Framework via pabot) +│ ├─ Other frameworks: Playwright, Cypress, Selenium, `go test` (integration tag) +│ ├─ Location: integration test directory (project: robot/) +│ ├─ Run via: task runner integration test session (e.g. nox -s integration_tests) │ ├─ Exercise real services, endpoints, dependencies │ ├─ NO mocking in integration tests (strictly prohibited) -│ ├─ Mocks OK for truly impractical external dependencies only +│ ├─ Mocks acceptable ONLY for truly impractical external dependencies │ └─ Must be updated when component interfaces change │ -├─ END-TO-END TESTS (Robot Framework with real LLM keys) -│ ├─ Run via: nox -s e2e_tests -│ ├─ Requires real LLM API keys (separate from integration tests) -│ └─ Tests the full system with real providers +├─ END-TO-END TESTS (project uses Robot Framework with real credentials) +│ ├─ Run via: task runner e2e session (e.g. nox -s e2e_tests) +│ ├─ Requires real external service credentials (separate from integration tests) +│ └─ Tests the complete system with real providers end-to-end │ ├─ PERFORMANCE BENCHMARKS -│ ├─ Use ASV (Airspeed Velocity) for performance-sensitive code -│ ├─ Run via: nox -s benchmark -│ └─ PRs: regression check via nox -s benchmark_regression +│ ├─ Write benchmarks for performance-sensitive code +│ │ (project: ASV — Airspeed Velocity; others: JMH, Benchmark.js, `go test -bench`) +│ ├─ Run via: task runner benchmark session (e.g. nox -s benchmark) +│ └─ PRs: regression check via task runner (e.g. nox -s benchmark_regression) │ ├─ COVERAGE REQUIREMENTS │ ├─ Minimum: ≥ 97% (project-specific; C.O.C. baseline is 85%) @@ -769,25 +810,29 @@ Testing requirements (MANDATORY at all levels): │ └─ Regression tests for every bug fix (via TDD workflow) │ ├─ MOCK PLACEMENT (strict) -│ ├─ Mocks/fakes/stubs/fixtures: features/mocks/ directory ONLY -│ ├─ NEVER in src/, NEVER in scripts/ -│ ├─ Production code must not contain if testing: guards or test-only paths +│ ├─ Mocks/fakes/stubs/fixtures: designated mock directory ONLY (project: features/mocks/) +│ ├─ NEVER in production source directory (src/) or scripts/ +│ ├─ Production code must not contain if-testing guards or test-only code paths │ └─ Use dependency injection to substitute test doubles │ ├─ TDD BUG FIX TAGS (see also "Am I writing a TDD issue-capture test?") │ ├─ Required tags: @tdd_issue + @tdd_issue_N + @tdd_expected_fail │ ├─ @tdd_expected_fail inverts result: failing assertion = CI passes -│ └─ AssertionError ONLY: use assert or raise AssertionError (not ValueError etc.) +│ └─ Must use the language's assertion failure type — NOT runtime exceptions +│ (Python: AssertionError | Java: AssertionError | JS: assert.AssertionError) │ -├─ LangChain/LangGraph testing specifics +├─ LangChain/LangGraph testing (project-specific — Python LangGraph) │ ├─ Use FakeListLLM or custom mock providers (deterministic) │ ├─ Test each node's state transformation independently │ ├─ Verify complete workflow with expected state transitions │ └─ Test both event emission and final results for streaming │ └─ RUNNING TESTS - ├─ Always use nox (never invoke frameworks directly from command line) - ├─ If nox session is missing → add it to nox configuration first + ├─ Always use the task runner — never invoke frameworks directly + │ Python/nox: never call `behave`, `robot`, or `pytest` directly — use `nox` + │ Node.js: never call `jest` directly — use `npm run test` + │ Java: never call `junit` directly — use `./gradlew test` + ├─ If a task runner session is missing → add it to the task runner config FIRST └─ Test failure during development → immediately becomes blocking task ``` @@ -837,7 +882,7 @@ Conventional Changelog commit message format: │ └─ Use EXACTLY the text from ## Metadata section (copy-paste, verbatim) │ └─ TOOLS - ├─ Commitizen: git cz (interactive, recommended) + ├─ Commitizen: git cz (interactive, recommended — works for any language project) ├─ npm install -g commitizen@2.8.6 cz-customizable@4.0.0 └─ Pre-commit hook validates format automatically ``` @@ -856,14 +901,16 @@ Mandatory Bug Fix TDD Workflow: ├─ STEP 2: Write the failing test │ ├─ Branch naming: tdd/mN- (N = milestone number) │ │ e.g.: tdd/m3-shacl-crash -│ ├─ Write Behave scenario that captures the buggy behavior +│ ├─ Write a BDD scenario that captures the buggy behavior (project uses Behave) │ ├─ Tag the test with ALL THREE tags (see Tag Validation Rules below): │ │ ├─ @tdd_issue │ │ ├─ @tdd_issue_N (N = bug issue number, e.g. @tdd_issue_123) │ │ └─ @tdd_expected_fail ← CRITICAL: inverts pass/fail in CI │ ├─ The test MUST fail when run normally (it proves the bug exists) -│ └─ ⚠️ AssertionError ONLY: use assert or raise AssertionError -│ Do NOT use ValueError, RuntimeError, OSError — those are NOT inverted +│ └─ ⚠️ Use the language's assertion failure type ONLY — NOT runtime exceptions: +│ Python: use `assert` or `raise AssertionError(...)` — not ValueError/RuntimeError +│ Java: throw new AssertionError(...) — not RuntimeException +│ JavaScript: throw new assert.AssertionError(...) — not Error or TypeError │ ├─ STEP 3: Merge the TDD test PR │ ├─ CI passes because @tdd_expected_fail inverts the result @@ -894,7 +941,7 @@ Mandatory Bug Fix TDD Workflow: ├─ TAG VALIDATION RULES (enforced by CI) │ ├─ @tdd_issue_N present → @tdd_issue MUST also be present │ ├─ @tdd_expected_fail present → @tdd_issue AND @tdd_issue_N MUST be present -│ ├─ Expected-fail steps MUST fail via AssertionError (not other exceptions) +│ ├─ Expected-fail steps MUST fail via the language's assertion type (not runtime exceptions) │ ├─ Bug fix PR closing #N → @tdd_expected_fail MUST be removed from @tdd_issue_N │ └─ Bug fix PR closing #N → @tdd_issue_N test MUST exist in codebase │ @@ -1192,12 +1239,13 @@ Documentation standards (all code-related docs): │ └─ Updated doc: find the single canonical location and update there │ ├─ TRACEABILITY RULES (enforced) -│ ├─ Reference code by LOGICAL LOCATION only: -│ │ └─ Format: module.class.method -│ │ e.g. cleveragents.services.plan_service.PlanService.execute +│ ├─ Reference code by LOGICAL LOCATION only (language-appropriate format): +│ │ ├─ Python example: mypackage.services.plan_service.PlanService.execute +│ │ ├─ Java example: com.example.services.PlanService.execute +│ │ └─ TypeScript: services/planService.PlanService.execute │ ├─ Include commit hash at time of writing │ │ └─ e.g. (see commit a3f92b1) -│ ├─ ⚠️ NEVER reference by line number (file.py:142) +│ ├─ ⚠️ NEVER reference by line number (e.g. file.py:142 or file.go:87) │ │ Line numbers shift with every edit and become misleading immediately │ └─ When names are refactored later, commit hash traces original location │ @@ -1219,15 +1267,15 @@ Documentation standards (all code-related docs): │ ├─ When code ≠ spec → code is wrong, align code to spec │ └─ Spec changes: go through ADR process, not ad-hoc edits │ -├─ CODE DOCUMENTATION (doc strings, comments) -│ ├─ All public functions, classes, methods → docstrings required +├─ CODE DOCUMENTATION (docstrings / doc comments) +│ ├─ All public functions, classes, methods → docstrings/doc comments required │ ├─ Non-obvious logic → inline comments explaining WHY (not what) │ ├─ Avoid comments that merely restate the code │ └─ Keep comments current when code changes │ ├─ DOCS DIRECTORY (docs/) -│ ├─ All markdown files must be written for MkDocs format -│ ├─ Build with: nox -s docs +│ ├─ All markdown files must be written for the project's doc tool (project: MkDocs) +│ ├─ Build with: task runner docs session (e.g. nox -s docs) │ └─ API docs, architecture overviews, user guides → all in docs/ │ └─ CHANGELOG @@ -1235,47 +1283,47 @@ Documentation standards (all code-related docs): └─ Describes the change from the user's perspective ``` -### "What nox session should I run?" +### "What task runner session should I run?" ``` -Complete nox session guide: +Complete task runner guide (this project uses nox — Python): │ ├─ BEFORE COMMITTING (run all of these): -│ ├─ nox -s lint → ruff linting (find code style violations) -│ ├─ nox -s format -- --check → check if formatting passes (CI mode) -│ ├─ nox -s typecheck → Pyright static type checking -│ ├─ nox -s unit_tests → Behave BDD tests -│ └─ nox -s coverage_report → verify ≥ 97% coverage +│ ├─ Lint session → linting (nox -s lint) +│ ├─ Format check session → formatting only, no changes (nox -s format -- --check) +│ ├─ Type check session → static type checking (nox -s typecheck) +│ ├─ Unit test session → BDD tests (nox -s unit_tests) +│ └─ Coverage session → verify ≥ 97% (nox -s coverage_report) │ ├─ BEFORE SUBMITTING A PR (additionally run): -│ ├─ nox → ALL default sessions (the full gate) -│ ├─ nox -s security_scan → bandit + semgrep + vulture -│ ├─ nox -s dead_code → vulture dead code detection -│ └─ nox -s integration_tests → Robot Framework integration tests +│ ├─ Full default suite → ALL sessions (nox) +│ ├─ Security scan session → bandit + semgrep + vulture (nox -s security_scan) +│ ├─ Dead code session → vulture (nox -s dead_code) +│ └─ Integration test session → Robot Framework (nox -s integration_tests) │ ├─ SPECIFIC SITUATIONS: -│ ├─ Auto-fix formatting: nox -s format -│ ├─ Run e2e tests: nox -s e2e_tests (needs real LLM keys) -│ ├─ Performance benchmarks: nox -s benchmark -│ ├─ Benchmark regression: nox -s benchmark_regression -│ ├─ Code complexity: nox -s complexity (radon; nightly sweep) -│ ├─ Build docs: nox -s docs -│ ├─ Build wheel: nox -s build -│ └─ Build everything: nox +│ ├─ Auto-fix formatting: Format session (nox -s format) +│ ├─ End-to-end tests: E2E session — needs real credentials (nox -s e2e_tests) +│ ├─ Performance benchmarks: Benchmark session (nox -s benchmark) +│ ├─ Benchmark regression: Benchmark regression session (nox -s benchmark_regression) +│ ├─ Code complexity analysis: Complexity session — Radon (nox -s complexity) +│ ├─ Build documentation: Docs session — MkDocs (nox -s docs) +│ ├─ Build distributable: Build session (nox -s build) +│ └─ Run everything: Full default suite (nox) │ -├─ CI JOBS AND THEIR SESSIONS: -│ ├─ lint job → nox -s lint + nox -s format -- --check -│ ├─ typecheck job → nox -s typecheck -│ ├─ security job → nox -s security_scan + nox -s dead_code -│ ├─ quality job → nox -s complexity -│ ├─ unit_tests job → nox -s unit_tests +├─ CI JOBS AND THEIR SESSIONS (project-specific mapping): +│ ├─ lint job → nox -s lint + nox -s format -- --check +│ ├─ typecheck job → nox -s typecheck +│ ├─ security job → nox -s security_scan + nox -s dead_code +│ ├─ quality job → nox -s complexity +│ ├─ unit_tests job → nox -s unit_tests │ ├─ integration_tests job → nox -s integration_tests -│ ├─ e2e_tests job → nox -s e2e_tests -│ ├─ coverage job → nox -s coverage_report (fail-under 97%) -│ ├─ benchmark-regression → nox -s benchmark_regression -│ ├─ benchmark-publish → nox -s benchmark (publish variant) -│ ├─ build job → nox -s build -│ └─ docker job → (Docker build, uses wheel from build job) +│ ├─ e2e_tests job → nox -s e2e_tests +│ ├─ coverage job → nox -s coverage_report (fail-under 97%) +│ ├─ benchmark-regression → nox -s benchmark_regression +│ ├─ benchmark-publish → nox -s benchmark (publish variant, push to master/develop only) +│ ├─ build job → nox -s build +│ └─ docker job → Docker build + smoke test │ ├─ REQUIRED FOR MERGE (status-check gate): │ ├─ lint ✓ @@ -1283,15 +1331,19 @@ Complete nox session guide: │ ├─ security ✓ │ ├─ unit_tests ✓ │ └─ coverage ✓ -│ (integration_tests, e2e_tests, benchmark-regression are informational) +│ (integration_tests, e2e_tests, benchmark-regression are informational only) │ -├─ RULES: -│ ├─ ALWAYS use nox — never invoke behave/robot/pytest directly -│ ├─ If a session is missing → add it to noxfile.py BEFORE using +├─ UNIVERSAL RULES (apply to any language, not just Python/nox): +│ ├─ ALWAYS use the task runner — never invoke test/lint/type-check tools directly +│ │ Python/nox: never call `behave`, `robot`, `pyright`, or `ruff` directly +│ │ Node.js: never call `jest`, `eslint`, or `tsc` directly — use `npm run