# Bulk + async + performance

Apply only to the changed flow. Derive limits from its actual service/behavior contract; unknown limits remain unverified.

| Flow | Implementation + meaningful assertion |
| --- | --- |
| Batches | Reuse native batching/pagination/streams. Exercise empty, boundary + final partial inputs; assert exact records/order, no loss/duplication + expected calls. Account for payload limits and retries, not only item count. |
| Fan-out / queue | Bound active + pending work; define overload behavior. Hold workers at a controlled boundary, prove both bounds, then release and verify completion, errors + relevant cancellation/timeout cleanup. A semaphore around eagerly created tasks does not bound pending memory. |
| Repeated I/O | Assert required query/request counts across representative input sizes, cache states + partial failures. Retries must not duplicate effects or amplify overload. |
| Scaling | Name input dimensions + expected time/space growth; inspect repeated scans, copies, sorts + I/O. Assert independently justified operation bounds where feasible; include skewed inputs when relevant. |

Use controlled inputs, fake clocks or synchronization instead of sleep-based comparisons. Native pattern lints and timing samples do not prove general Big-O.

Async does not make CPU work parallel; unbounded gathers can worsen resource use.

## Optimisation

Only when the requested outcome is a measured improvement (time, memory, size, cost):

1. Reproduce the real workload. The plan names the metric, target, measurement command and correctness constraints.
2. Show the measurement detects a known change, then freeze the workload, command and configuration for the comparison.
3. Record revision, configuration and repeated samples on both sides, enough that the difference exceeds run-to-run spread. Never run competing measurements on the same constrained CPU, disk or network.
4. One hypothesis per change: measure before and after, run the existing gates, and keep only demonstrated improvements or equally fast simplifications. Revert rejected task-owned changes only.
5. Record baseline, samples and decisions in the plan's Baseline/Verification. Stop at the authorised target or budget, or when further work is unjustified; never weaken a check or shrink the workload to meet a target.

Diagnose surprises with [troubleshooting](../../research/references/troubleshooting.md); prove affected journeys per [testing](testing.md).

# Adapt + repair checks

Apply when adapting or repairing project checks; use native diagnostics for enforced requirements.

Plan migration: Ready/Complete plans now need an explicit `E2E:` disposition. When reopening or validating an older plan, derive it from that plan's recorded runtime evidence or a concrete inapplicability reason; missing evidence remains pending. Do not relabel historical tests as fresh execution or turn local proof into remote delivery.

| Agent decision | Required proof |
| --- | --- |
| Package/source coverage | Match actual production owners, nested packages + native workspaces. Review scan roots, generated/vendor attributes, ignored files and dynamic entry points; a clean report cannot prove omitted code was examined. |
| Affected selection | `depends_on` = reviewed direct package-impact edges from native manifests, workspace/service setup and root lockfile/tool providers; traversal includes transitive dependents. Every package in a multi-package repository requires that review; missing mappings fail verification, and `[]` means reviewed independence. Initial setup leaves mappings for review. `impact_inputs` adds repository-relative file/directory inputs read by a package's checks, including cross-language contracts and documentation used as data; match exact paths or descendants, including deletions. Plans/top-level Markdown run only the secret scan when no declared input consumes them. Hard Eng config, workflow and scaffold changes stay full. Review imported schemas, generated sources and shared configuration before narrowing scope; selected packages still run their full suites and coverage. |
| CI ownership | Inspect existing jobs before assigning Hard Eng work. Each required assertion has one job/owner; compare arguments, reports and thresholds before removing duplicates. Keep local native checks; integrate missing CI assertions into existing jobs and name their required results in `shipping.checks`. Setup preserves existing workflows and leaves adaptation pending; it generates a new workflow only with a project shipping policy. |
| Import boundaries | Derive public/private interfaces + allowed dependencies from actual architecture. Prove allowed → pass, forbidden → fail, restored → pass, including relevant aliases, exports + test imports. Do not invent boundaries to satisfy a gate. |
| Performance | Choose representative workloads/environment + justified latency, memory, frame or operation budgets. Intentionally exceed each budget to prove failure. Flutter rendering needs profile-mode device measurements; debug unit tests are insufficient. See [Efficiency](efficiency.md) for bulk/async cases. |
| Security + dependencies | Review actual trust boundaries, native exclusions, extractor coverage + selected lockfiles/images. Confirm the scanned image is the intended build; scanner success does not establish exploitability or complete coverage. With a resolvable `--base`, the `secrets-history` gate's `--log-opts=--all` scans only `base..HEAD`, because earlier commits were scanned when they entered; without a base, or with one Git cannot resolve, it scans the full history. |
| Missing inputs | Repair missing/stale coverage, reports, generated sources or comparison refs at their producer/selection owner. Preserve the required metric, threshold and scope; disabling the metric or asserting the disabled configuration in a test does not repair the input. Unavailable proof remains a failed/blocked check. |
| Exceptions | Only proven false positives or intentional supported patterns; narrow native exception + adjacent reason/evidence. Keep the rule active elsewhere. No baseline, tolerance, ignore list, inline disable, raised threshold or hidden warning for an actual finding: repair it in code, even when it is unrelated to the task, and commit that repair before the task continues. |
| Parallelism | Opt in only independent commands with distinct outputs; account for child workers, memory + connections. Builds, generators and report cleaners may need ordering. Setup runs a generated pytest gate with `pytest-xdist` and `-n auto`, and upgrades an older serial one on update. A suite that shares a database, port or fixed file across tests fails under it: isolate that state per worker, or keep the suite serial by setting `-n 0` in the gate command, which setup preserves. |

When no meaningful performance workload and justified budget exist, review the package's responsibilities and actual consumers before recording a nonblank `performance_exception` string in that package's gate group. Include the reason, inspected evidence and changes that require revisiting it. Package size or language alone is insufficient; missing tests or an inconvenient failing budget is not an exception. Remove only the unused template performance placeholder after review. Setup preserves the declaration and omitted check; every configured performance suite still runs with serial execution and native report validation. Unit tests, coverage and all other strict checks remain mandatory. The parser validates the declaration's shape, not the review's correctness.

CI adaptation is one-time repository work, not a second check runner or receipt store. Reuse native job dependencies and failure propagation; required checks must report for affected and unaffected changes. A deploy job can `needs:` a job that `uses: ./.github/workflows/hard-eng.yml` with the `base_sha` input; the called check reports as `<caller job> / hard-eng`, which `shipping.checks` must name. Push/PR execution requires a nonblank `--base`; use `github.event.pull_request.base.sha || github.event.before`, or the reusable workflow's `base_sha` input. Local and manual full runs may omit it. Review package impact before verification; an unavailable comparison ref or uncertain changed-file impact still selects full scope. Provision only the selected owners' tools, reuse native caches without stale-version fallback, and measure both critical-path time and runner minutes. Do not widen timeouts to conceal duplication. A build/performance/browser prerequisite remains required when its consumer moves jobs.

Measure setup, checks, waiting and deployment separately. Replace a runner polling another workflow with native `needs`/reusable-workflow ordering, then remove duplicate triggers. Keep cache restore keys within the selected tool set and use the same package-manager store before dependency installation. Resolve each native workspace's locked dependencies once per job, before its consumers; remove duplicate workflow/wrapper installs only when the retained owner supplies the same dependencies and lifecycle scripts. Keep code generation once before its checks, retaining output-drift assertions; use Flutter's `--no-pub` only after the locked dependency gate succeeds. Remove repeated tests/scans only after comparing scope, tool versions, arguments and report thresholds. Dart Decimate's unfiltered strict `check` already includes boundary findings; its `--boundary-violations` option filters output and must not be added to the combined dead-code/duplicate gate.

`shipping.ci_seconds` bounds each named check's reported execution time. A three-second aggregate does not measure its upstream jobs: retain meaningful worker checks in the policy and measured native workflow/job timeouts. Report end-to-end CI elapsed time separately; do not claim a whole-pipeline budget from the aggregate's duration. Existing monoliths require a deliberate assertion-by-assertion migration before removing their product triggers; setup never deletes them automatically.

Use existing [Python](../templates/hard-eng.python.json), [JavaScript](../templates/hard-eng.javascript.json) or [Dart/Flutter](../templates/hard-eng.dart.json) templates when adapting a new package. Do not copy a template over project-specific contracts.

## Plan checks

Load for planning-stage checks or plan validation failures. Use [HE Plan](../../he-plan/SKILL.md) for readiness + authorization; [PLAN.md](../../he-plan/templates/PLAN.md) owns required fields.

| Command | Required declaration |
| --- | --- |
| `python3 .hooks/hard-eng.py check --plan-stage Draft` | Filled plan; permits pending baseline/intermediate verification. |
| `python3 .hooks/hard-eng.py check --plan-stage Ready` | Ready or Complete; baseline Passed with evidence; UX Passed with a rendered Mock/Existing/New proposal image or reasoned N/A; explicit E2E disposition; no declared blockers. |
| `python3 .hooks/hard-eng.py check --plan-stage Complete` | Complete; above requirements + implementation evidence, no unchecked requirements, and no pending local E2E. Deployment-only E2E requires Deploy and configured delivery checks. |

Every command also runs native project checks and the AGENTS.md comment rule: each changed source file, generated output aside, may hold only one-line comments. Ordinary `check` (including pre-push/CI) requires Complete for non-Markdown changes; Markdown-only planning can stop at Draft/Ready. Stop checks at Ready while every unfinished applicable plan is Ready with Verification Pending (a build in progress), unless a line of the turn opens with the HE Build handoff `Ready for ship —`. Changed root/feature plans take precedence; otherwise active plans apply. An unchanged historical Complete plan cannot cover new work relative to a known base. Missing bases fail plan validation; a new branch's zero base compares with its merge base on the `shipping.base` remote branch, and an unborn repository or missing remote branch uses Git's empty tree (the whole initial snapshot). Unchanged Complete plans keep their recorded rules: a missing `E2E:` field fails only once the plan is edited. Unchanged repositories can still be audited without inventing a task plan.

Draft Stop requires an explicit `Handoff: Clarification` with a real prerequisite question, or `Handoff: Approval` with baseline, UX and E2E planning evidence. Missing/invalid declarations and incomplete approval evidence block; a clarification does not waive another plan's requirements. This is a declared handoff check, not a trusted approval record or proof of the conversation's meaning. See [HE Plan](../../he-plan/SKILL.md#readiness--authorization).

Plan-only edits after a matching passed baseline → use the same stage command with `--base HEAD` to validate the plan and affected checks. The baseline must cover the current code/configuration/environment; the base flag cannot substitute for that proof. Uncommitted code/config changes remain in the comparison, unknown impact retains full scope, and required pre-push/CI checks still run. Do not repeat the whole application suite solely for plan wording or a Draft-to-Ready declaration change.

The check validates structure + declarations, not evidence truth, approval, relevance or delivery chronology. A passing Draft/Ready run is not implementation completion. Baseline Exception is rejected. If the Ready or Complete command fails, return the same plan to Draft with the actual blocker; do not replace failure with N/A or leave a false Ready/Complete claim. Starting failures follow [baseline repair](#baseline-repair); build regressions stay in their current effort. Neither route may weaken checks to bypass actual findings.

## Baseline repair

```mermaid
flowchart TD
  F[Failed baseline: feature stays Draft + blocked] --> A{Repair + main delivery authorized?}
  A -->|No| Q[Resolve only missing scope or prerequisite]
  A -->|Yes| R[Separate repair plan + task branch]
  R --> B[HE Build: baseline repairs only from truthful Draft]
  B --> C[All native checks pass + repair plan Complete]
  C --> S[HE Ship: merge repairs + verify main CI and delivery]
  S --> N[Fresh feature branch from verified main + new baseline]
  click B "../../he-build/SKILL.md"
  click S "../../he-ship/SKILL.md"
```

- Repair scope = all actual enforced baseline failures, including pre-existing debt and findings unrelated to the task or surfaced by a newer tool release; age, effort or relevance is not an exemption. Correct proven false positives only under the existing [native exception rule](#adapt--repair-checks). Reuse valid user authorization; otherwise ask for the missing repair/delivery scope.
- Repair is the sole failed-baseline implementation route: record failures, bounded repair steps + intended proof before edits. Preserve the original failed evidence; after repair, record the passing rerun as current baseline and complete normal build checks. Never declare Ready while checks fail.
- Feature resumes only after the repair revision is on the intended main branch and required CI/delivery checks pass. An open PR or local pass is insufficient. Keep repair and feature plans/diffs separate; apply the feature's original authorization and readiness rules after updating its baseline.

# Set up relevant integrations

Apply during first setup, brownfield adoption, scaffold updates or a relevant MCP failure. Reuse repository configuration, existing secret-loading launchers and settled product decisions. Ask only for missing choices; never ask for a secret in chat or repeat an answered hosting/project question.

```mermaid
flowchart TD
  R[Inspect existing integrations + product requirements] --> K{Target already known?}
  K -->|No| Q[Ask only unresolved service / hosting / project choice]
  K -->|Yes| C[Preserve valid config; adapt conflicting legacy entry]
  Q --> C
  C --> H[Load in intended trusted host + authenticate]
  H --> P[Read-only call against intended target]
  P --> V[Report configured / authenticated / verified separately]
```

- Greenfield = imports cannot reveal an unimplemented product choice. Resolve intended backend/observability from the product plan before configuring those services; no blanket installation of unrelated integrations.
- Brownfield/update = an install/update request covers routine migration within task scope; preserve explicit user restrictions and unrelated customizations. Inspect existing harness entries, actual endpoint, project identity and env owner first; use the pinned source as authority. Migrate incompatible project commands at their owner, preserving security/behavior; preserve custom valid hooks and remove only proven-obsolete Hard Eng-owned hooks, instructions and bootstrap. A legacy Hard Eng entry is not proof of suitability. Unknown consequential choices remain explicit blockers.
- Retirement before repair = identify user-retired tooling before adapting gates. Remove its obsolete workflows and registrations within authorization; do not repair, recreate or add infrastructure for a workflow the user wants retired.
- Older installations retiring Context Mode or Codebase Memory need the current published installer in a fresh process. An already-running older updater can replace tracked files while retaining its old cleanup code; verify local plugin settings and generated state are gone before declaring retirement complete.
- Verification ownership = trace active agent hooks through the native Git hook and CI jobs. A pre-tool `git push --dry-run` invokes pre-push too; remove repeated full verification while retaining any distinct bypass guard. Compare legacy commands against current gate scope/arguments before retiring them. Apply supported installer migrations first; custom workflow or impact-mapping diagnostics remain unfinished adoption work until repaired and verified. Record actual push/CI time and runner minutes, not assumed savings.
- The piped installer has no interactive questionnaire. Unresolved optional services are reported as `MCP setup pending`; the core scaffold is installed so HE Plan can resolve only the missing choices. Supply the known endpoint/host from the existing environment, then rerun setup. Conflicting existing configuration fails before writes. Do not mark setup ready from exit status or a revision marker alone.
- Completion = finish routine repairs and configured CI integration; ensure CI provisions pnpm before pnpm-dependent caching. Local gates prove local setup. When shipping is authorized, use the existing isolated pre-push check on the final rebased commit, including required skill targets even when ignored, then verify hosted required checks. Installation/update does not authorize publication.

| Integration | Selection + proof |
| --- | --- |
| Appwrite | Follow the [canonical MCP owner](../../appwrite-backend/references/mcp-servers.md). `APPWRITE_ENDPOINT` selects Cloud OAuth (`https://mcp.appwrite.io/`) or the self-hosted repo launcher. Reuse an existing valid URL/launcher on updates. Prove the intended endpoint/project with a read-only call. |
| Sentry | Reuse the existing target. New SaaS setup: supply `SENTRY_MCP_URL`, preferably `https://mcp.sentry.dev/mcp/{org}/{project}`; preserve an existing chosen scope. Self-hosted: one executable `scripts/sentry-mcp` resolves its own repo root, loads the existing gitignored env file, validates `SENTRY_HOST` + `SENTRY_ACCESS_TOKEN`, and execs `pnpm dlx @sentry/mcp-server@latest`. Preserve existing compatible launchers/configs. Read-only organization/project access proves readiness; token scopes and unsupported tools follow [Sentry's official server](https://github.com/getsentry/sentry-mcp/tree/main/packages/mcp-core). |
| Dart/Flutter | Official SDK command `dart mcp-server`; verify native initialization and the tools needed for the operation. Existing package-command registrations require migration to the official command before claiming current setup. |
| Marionette | Optional debug-only integration. Registration trigger = any Flutter app, pinned to the `pubspec.lock` version of `marionette_flutter` when locked and unpinned otherwise; detection runs only on install or an applied update, so a package added or upgraded between updates needs a manual pin edit. Registration alone does not configure or connect a running app; [Flutter recorded proof](../../e2e/references/flutter.md) owns the binding, connection and recording steps. |

For Claude Code, setup approves the `.mcp.json` servers it writes through `enabledMcpjsonServers` in `.claude/settings.json`; Claude honors that only once the main repository's folder is trusted, so a worktree of an untrusted repository still shows `Pending approval`.

For Codex, project trust controls loading; hook trust is separate. Inspect `codex mcp list` inside the target root. Use `codex mcp login <name>` for an unauthenticated OAuth server. A newly written entry may require reconnecting or starting a fresh task before tools appear. State that limitation; never claim installation failed solely because the current task cannot see newly configured tools. Do not change global trust/config or create a duplicate global server.

Project instructions live in `AGENTS.md`, read natively by Codex and Claude Code v2.1.277+. Remove redundant Claude import files; review unique rules, relative imports and scope before migrating custom files. Never copy private local instructions into tracked shared files. Ancestor project Claude files can suppress AGENTS loading and need separate cleanup at their owner.

Generated configurations target Codex and Claude Code. Retire other harness registrations during an authorized migration; retain shared instructions and distinct assertions in the supported owners before removing custom integrations.

Probe relevant integrations once when setting them up or relying on them, not every tool call. Unrelated service outages must not trigger a mandatory startup sweep. Keep keys and personal/project details out of public scaffold files and PRs.

# Test design + quality

Apply when designing, changing or reviewing tests. Reuse the existing framework, fixtures + suite; each case needs a distinct required outcome or meaningful failure. Identify expected outcomes + relevant failure modes before implementation; meaningful tests may be added afterwards unless TDD is requested.

| Decision | Required proof |
| --- | --- |
| Expected result | Derive from accepted behavior/public contract, independently of the implementation under test. Name precondition + action + observable result; copying the implementation's calculation into the assertion proves neither correct. |
| Boundary | Use the narrowest public seam crossing the behavior's real owner. Assert return/state, emitted contract, visible result or durable effect. Internal calls/structure alone do not prove behavior; behavior-preserving refactors should retain valid tests. |
| Collaborators | Keep the collaborators needed to expose the actual failure. Isolate slow, nondeterministic, destructive or unavailable external boundaries with contract-faithful doubles; add integration proof where the double could hide the defect. Mock calls are sufficient only when those calls are themselves the required contract. |
| Cases | Cover relevant boundaries, invalid/empty inputs, denied access, failure/recovery, concurrency + state/time transitions. Use realistic minimal data; isolate mutable state and avoid timing/order-dependent assertions. No mandatory matrix of unrelated cases. |
| Regression | Show the test fails on the original defective behavior for the expected reason, then passes with the fix. Use an available defective revision or existing controlled reproduction; unavailable red evidence remains a stated gap. Setup/compiler/fixture failures are not valid regression proof. |
| Runtime contract | Compiler/interpreter/runner behavior needs compatible tool execution. Source-text checks establish wiring only. Affected UI/device/API/CLI journeys need real [E2E](../../e2e/SKILL.md) proof where applicable. Retain focused tests that add meaningful coverage, faster feedback or clearer diagnosis; E2E does not replace them. |
| Strength | Coverage, execution, snapshots, existence checks + aggregate counts alone cannot establish the intended behavior. Judge whether a realistic wrong result would fail the assertion; remove duplicate or implementation-coupled proof only within task scope. |
| Deletion | Before deleting a test, state the behavior it protects and either the retained replacement proof or why that proof is unnecessary. Overlap with E2E alone does not justify deletion. |

## Explicit TDD

Apply only when TDD/red-green-refactor is requested. One observable behavior per increment; reuse the scenario's contract + meaningful seam above.

```mermaid
flowchart LR
  B[Next required behavior] --> R[RED: fails for missing / wrong behavior]
  R --> G[GREEN: minimum complete implementation + affected tests pass]
  G --> F[REFACTOR: same behavior + tests pass]
  F -->|Uncovered requirement| B
```

Harness failure → repair harness before accepting RED. Changed requirements → update expected behavior before continuing; do not generalize production code merely to satisfy an artificial test.

## Completion

- Report behavior + test path + repeatable setup + commands + assertions + actual results + material gaps using existing task evidence; no separate ledger or behavior-ID scheme. State unavailable regression or E2E proof explicitly.
- Preserve useful success + failure artifacts (logs, traces, media) per [E2E](../../e2e/SKILL.md#visual-proof-and-completion). Screenshots alone do not prove correctness.
- Mutation execution uses [Work + verification](workflow.md)'s scope/runtime acceptance rule. If run, inspect meaningful survivors: fix a test gap or explain equivalent/invalid/deferred cases and their consequence. A score alone is insufficient.
- Run applicable project gates. This guidance supports judgment; passing checks cannot certify test quality.

# Work + verification

- Task mode = for a new feature request, reuse the user's stated Human-loop/Autonomous choice; if absent, ask once. Apply only to that task, preserve it on continuation and allow the user to change it. Existing task authorization remains valid; do not restart mode selection for each step. Mode governs participation, not tool permissions or authority for external actions.
- Planning = before new implementation or material scope changes, use [he-plan](../../he-plan/SKILL.md). Existing ready + authorized plan → continue; reviews/explanations alone need no new plan. Readiness and authorization belong to he-plan; completion checks are not a start-of-work barrier.
- Context = read root `PRODUCT.md` + `DESIGN.md` before implementation. Missing/empty → study existing docs, code + relevant interface; fill [PRODUCT](../templates/PRODUCT.md) / [DESIGN](../templates/DESIGN.md) from evidence. Preserve existing content; unknown product/design choices stay explicit.
- Product = actual users, problem, purpose + boundaries per [product.md](https://product.md/). Design = observed tokens/components per [design.md](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md); use [Atomic Design](https://atomicdesign.bradfrost.com/chapter-2/) to describe existing UI, not force a restructure. No visual UI → document the actual interface.
- Isolation = start new implementation in a task branch/worktree before code changes; reuse that task's existing isolation on continuation. Preserve other tasks and shared state. PR delivery is the default; [HE Ship](../../he-ship/SKILL.md) owns verification and safe cleanup after the requested delivery.
- Build = [HE Build](../../he-build/SKILL.md) owns local implementation, verification and Ready for ship in the same plan. [HE Ship](../../he-ship/SKILL.md) owns authorized PR/merge/delivery actions and remote proof. Review-only work stays with its review owner; local Complete does not mean the overall delivery is finished.
- Learning + steering = use [HE Learn](../../he-learn/SKILL.md) for repeated failures or lasting decisions; session/failure checkpoints remind once at those boundaries. Ordinary prompts/tools need no callback. Prefer deterministic prevention; skills are the last resort. Capture accepted durable choices in `docs/adr/` and read applicable ADRs on the next affected task; routine steering stays in the plan. A hook prompt proves neither learning nor prevention.
- Mutation = optional; present changed-function scope, covering tests + estimated runtime; obtain acceptance before running.

## Participation

| Mode | Planning behavior |
| --- | --- |
| Human-loop | Resolve grouped material questions, show the grounded UX and completed plan, then request one combined approval covering plan + UX + execution recommendation. Reuse approval of that proposal; the initial feature request alone is not proposal approval. |
| Autonomous | Study and prepare without routine approval stops; provide concise progress. Still ask unresolved material questions and show/inspect applicable UX references. Choose reversible details within the user's constraints; initial authorization covers proceeding once ready. |

- Neither mode permits inventing user answers, skipping UX/baseline proof or crossing an unauthorized boundary. A mode name alone does not authorize publication, production changes or other external actions beyond the task's agreed delivery scope.

rules:
  - id: dart-accept-invalid-certificate
    languages: [dart]
    severity: ERROR
    message: Reject invalid TLS certificates instead of accepting every certificate.
    metadata:
      references:
        - https://api.dart.dev/dart-io/HttpClient/badCertificateCallback.html
    pattern-either:
      - pattern: $CLIENT.badCertificateCallback = (...) => true
      - pattern: $CLIENT.badCertificateCallback = (...) { return true; }
  - id: dart-shell-process
    languages: [dart]
    severity: ERROR
    message: Use direct process execution; shell parsing requires a reviewed narrow exception.
    metadata:
      references:
        - https://api.dart.dev/dart-io/Process/run.html
    pattern-either:
      - pattern: 'Process.run(..., runInShell: true, ...)'
      - pattern: 'Process.runSync(..., runInShell: true, ...)'
      - pattern: 'Process.start(..., runInShell: true, ...)'

rules:
  - id: insecure-hash-algorithm-sha1
    languages: [python]
    severity: WARNING
    message: >-
      SHA-1 is not collision resistant. Use SHA-256 or SHA-3; when a file
      format mandates SHA-1 for integrity only, declare it with
      usedforsecurity=False.
    metadata:
      cwe:
        - "CWE-327: Use of a Broken or Risky Cryptographic Algorithm"
      references:
        - https://docs.python.org/3/library/hashlib.html#hashlib.new
    patterns:
      - pattern: hashlib.sha1(...)
      - pattern-not: hashlib.sha1(..., usedforsecurity=False, ...)

<!-- Use only when DESIGN.md is missing. Study the running interface and its code.
Fill the relevant prompts; omit visual sections for a CLI/backend-only repository.
Add YAML tokens only when actual token values are established in the project. -->

# [TODO: Product name] Design

## Overview

[TODO: The actual interface, its audience and its established design principles.]

## Colors

[TODO: Existing semantic colors, exact values and source locations.]

## Typography

[TODO: Existing type roles, fonts, sizes and source locations.]

## Layout

[TODO: Existing layout, spacing and responsive behavior.]

## Components

[TODO: Describe existing UI composition using the levels below. For a nonvisual
product, replace this list with its actual interface and state that visual
Atomic Design does not apply. Do not create components just to fill a level.]

- Atoms: [TODO: Basic elements and their existing implementations.]
- Molecules: [TODO: Small combinations of elements.]
- Organisms: [TODO: Larger interface sections.]
- Templates: [TODO: Reusable page or screen layouts.]
- Pages: [TODO: Actual screens, content and relevant states.]

## Do's and Don'ts

[TODO: Established interaction, accessibility and consistency rules.]

{
  "version": 1,
  "packages": [
    {
      "name": "app",
      "path": ".",
      "language": "dart",
      "sources": ["lib"],
      "checks": [
        {
          "name": "performance",
          "role": "performance",
          "command": ["dart", "test", "test/performance", "--reporter=json"],
          "report": { "type": "performance-dart", "path": "coverage/performance.jsonl", "stdout": true }
        },
        {
          "name": "format",
          "role": "format",
          "parallel": true,
          "command": [
            "sh",
            "-c",
            "set -e; candidates=$(mktemp); files=$(mktemp); trap 'rm -f \"$candidates\" \"$files\"' EXIT HUP INT TERM; git ls-files -z --cached --others --exclude-standard -- '*.dart' ':(glob,exclude)**/build/**' ':(glob,exclude)**/.dart_tool/**' ':(exclude).agents/**' ':(exclude).hooks/**' ':(exclude)vendor/**' > \"$candidates\"; xargs -0 sh -c 'for path in \"$@\"; do if [ -f \"$path\" ]; then printf \"%s\\0\" \"$path\"; fi; done' sh < \"$candidates\" > \"$files\"; [ -s \"$files\" ] || exit 0; xargs -0 dart format --output=none --set-exit-if-changed < \"$files\""
          ]
        },
        { "name": "types-lint", "role": "types", "parallel": true, "command": ["dart", "analyze", "--fatal-infos", "."] },
        {
          "name": "tests",
          "role": "tests",
          "command": ["flutter", "test", "--no-pub", "--machine", "--coverage", "--coverage-path=coverage/lcov.info"],
          "report": { "type": "dart-tests", "tests": "coverage/tests.jsonl", "coverage": "coverage/lcov.info" }
        },
        {
          "name": "dead-code-duplicates",
          "role": "dead-code-duplicates",
          "command": ["dart-decimate", "check", ".", "--threshold", "0", "--strict", "--format", "json"],
          "report": { "type": "dart-decimate", "path": "coverage/dart-decimate.json", "stdout": true }
        }
      ]
    }
  ],
  "shared": [
    { "name": "lockfile", "role": "lockfiles", "command": ["flutter", "pub", "get", "--enforce-lockfile"] },
    {
      "name": "secrets-files",
      "role": "secrets-files",
      "parallel": true,
      "command": [
        "gitleaks",
        "dir",
        ".",
        "--redact=100",
        "--no-banner",
        "--report-format",
        "sarif",
        "--report-path",
        "coverage/gitleaks-files.sarif"
      ],
      "report": { "type": "gitleaks", "path": "coverage/gitleaks-files.sarif" }
    },
    {
      "name": "secrets-history",
      "role": "secrets-history",
      "parallel": true,
      "command": [
        "gitleaks",
        "git",
        ".",
        "--redact=100",
        "--no-banner",
        "--log-opts=--all",
        "--report-format",
        "sarif",
        "--report-path",
        "coverage/gitleaks-history.sarif"
      ],
      "report": { "type": "gitleaks", "path": "coverage/gitleaks-history.sarif" }
    },
    {
      "name": "vulnerabilities",
      "role": "vulnerabilities",
      "parallel": true,
      "command": [
        "osv-scanner",
        "scan",
        "source",
        "--lockfile=pubspec.lock",
        "--all-packages",
        "--format=json",
        "--output-file=coverage/osv.json"
      ],
      "report": { "type": "osv", "path": "coverage/osv.json" }
    },
    {
      "name": "security",
      "role": "security",
      "parallel": true,
      "command": [
        "semgrep",
        "scan",
        "--config",
        ".agents/skills/he/security",
        "--jobs",
        "2",
        "--error",
        "--strict",
        "--time",
        "--json",
        "--output",
        "coverage/semgrep.json",
        "."
      ],
      "report": { "type": "semgrep", "path": "coverage/semgrep.json" }
    }
  ]
}

{
  "version": 1,
  "packages": [
    {
      "name": "app",
      "path": ".",
      "language": "javascript",
      "sources": ["src"],
      "checks": [
        {
          "name": "performance",
          "role": "performance",
          "command": ["pnpm", "run", "test:performance"],
          "report": { "type": "performance-junit", "path": "coverage/performance.xml" }
        },
        { "name": "format-lint", "role": "format-lint", "parallel": true, "command": ["biome", "ci", ".", "--error-on-warnings"] },
        {
          "name": "focused-tests",
          "role": "focused-tests",
          "parallel": true,
          "command": ["biome", "lint", "--only=suspicious/noFocusedTests", "--error-on-warnings", "."]
        },
        {
          "name": "typing-style",
          "role": "typing-style",
          "parallel": true,
          "command": [
            "biome",
            "lint",
            "--only=suspicious/noVar",
            "--only=suspicious/noExplicitAny",
            "--only=suspicious/noImplicitAnyLet",
            "--only=performance/noAccumulatingSpread",
            "--error-on-warnings",
            "."
          ]
        },
        {
          "name": "types",
          "role": "types",
          "parallel": true,
          "command": [
            "tsc",
            "--noEmit",
            "--strict",
            "--noImplicitAny",
            "--noImplicitThis",
            "--strictNullChecks",
            "--strictFunctionTypes",
            "--strictBindCallApply",
            "--strictPropertyInitialization",
            "--strictBuiltinIteratorReturn",
            "--useUnknownInCatchVariables",
            "--alwaysStrict",
            "--allowJs",
            "--checkJs",
            "--noCheck",
            "false"
          ]
        },
        {
          "name": "tests",
          "role": "tests",
          "command": ["pnpm", "run", "test:coverage"],
          "report": { "type": "lcov-tests", "tests": "coverage/junit.xml", "coverage": "coverage/lcov.info" }
        },
        {
          "name": "dead-code-duplicates",
          "role": "dead-code-duplicates",
          "command": [
            "fallow",
            "--only",
            "dead-code,dupes",
            "--max-file-size",
            "0",
            "--fail-on-issues",
            "--format",
            "json",
            "--output-file",
            "coverage/fallow.json"
          ],
          "report": { "type": "fallow", "path": "coverage/fallow.json" }
        }
      ]
    }
  ],
  "shared": [
    { "name": "lockfile", "role": "lockfiles", "command": ["pnpm", "install", "--frozen-lockfile"] },
    {
      "name": "secrets-files",
      "role": "secrets-files",
      "parallel": true,
      "command": [
        "gitleaks",
        "dir",
        ".",
        "--redact=100",
        "--no-banner",
        "--report-format",
        "sarif",
        "--report-path",
        "coverage/gitleaks-files.sarif"
      ],
      "report": { "type": "gitleaks", "path": "coverage/gitleaks-files.sarif" }
    },
    {
      "name": "secrets-history",
      "role": "secrets-history",
      "parallel": true,
      "command": [
        "gitleaks",
        "git",
        ".",
        "--redact=100",
        "--no-banner",
        "--log-opts=--all",
        "--report-format",
        "sarif",
        "--report-path",
        "coverage/gitleaks-history.sarif"
      ],
      "report": { "type": "gitleaks", "path": "coverage/gitleaks-history.sarif" }
    },
    {
      "name": "vulnerabilities",
      "role": "vulnerabilities",
      "parallel": true,
      "command": [
        "osv-scanner",
        "scan",
        "source",
        "--lockfile=pnpm-lock.yaml",
        "--allow-no-lockfiles",
        "--all-packages",
        "--format=json",
        "--output-file=coverage/osv.json"
      ],
      "report": { "type": "osv", "path": "coverage/osv.json" }
    },
    {
      "name": "security",
      "role": "security",
      "parallel": true,
      "command": [
        "semgrep",
        "scan",
        "--config",
        "p/javascript",
        "--config",
        "p/typescript",
        "--jobs",
        "2",
        "--error",
        "--strict",
        "--time",
        "--json",
        "--output",
        "coverage/semgrep.json",
        "."
      ],
      "report": { "type": "semgrep", "path": "coverage/semgrep.json" }
    }
  ]
}

{
  "version": 1,
  "packages": [
    {
      "name": "app",
      "path": ".",
      "language": "python",
      "sources": ["src"],
      "checks": [
        {
          "name": "performance",
          "role": "performance",
          "command": ["pytest", "tests/performance", "--junitxml=coverage/performance.xml"],
          "report": { "type": "performance-junit", "path": "coverage/performance.xml" }
        },
        {
          "name": "format",
          "role": "format",
          "parallel": true,
          "command": ["ruff", "format", "--check", ".", "--extend-exclude", ".agents/skills,.claude/skills"]
        },
        { "name": "lint", "role": "lint", "parallel": true, "command": ["ruff", "check", ".", "--extend-select", "C901,PLR0912,PLR0915"] },
        {
          "name": "complexity",
          "role": "complexity",
          "parallel": true,
          "command": [
            "ruff",
            "check",
            ".",
            "--select",
            "C901,PLR0912,PLR0915",
            "--config",
            "lint.mccabe.max-complexity = 10",
            "--config",
            "lint.pylint.max-branches = 12",
            "--config",
            "lint.pylint.max-statements = 50"
          ]
        },
        {
          "name": "types",
          "role": "types",
          "parallel": true,
          "command": ["pyrefly", "check", "--check-unannotated-defs=true", "--min-severity", "info"]
        },
        {
          "name": "annotations",
          "role": "annotations",
          "parallel": true,
          "command": [
            "ruff",
            "check",
            "src",
            "tests",
            "--select",
            "ANN,TID251,RUF017,ASYNC210",
            "--config",
            "lint.flake8-annotations.ignore-fully-untyped = false",
            "--config",
            "lint.flake8-tidy-imports.banned-api.\"typing.Any\".msg = \"Use a precise type instead of Any\"",
            "--config",
            "lint.flake8-tidy-imports.banned-api.\"typing_extensions.Any\".msg = \"Use a precise type instead of Any\""
          ]
        },
        {
          "name": "tests",
          "role": "tests",
          "command": ["pytest", "--cov=src", "--cov-branch", "--cov-report=json:coverage/coverage.json", "--junitxml=coverage/junit.xml"],
          "report": { "type": "python-tests", "tests": "coverage/junit.xml", "coverage": "coverage/coverage.json" }
        },
        { "name": "dead-code", "role": "dead-code", "parallel": true, "command": ["vulture", "src", "tests", "--min-confidence", "60"] },
        {
          "name": "duplicates",
          "role": "duplicates",
          "command": [
            "jscpd",
            "src",
            "tests",
            "--format",
            "python",
            "--threshold",
            "0",
            "--max-size",
            "100mb",
            "--max-lines",
            "1000000",
            "--reporters",
            "json",
            "--output",
            "coverage/jscpd"
          ],
          "report": { "type": "jscpd", "path": "coverage/jscpd/jscpd-report.json" }
        },
        {
          "name": "dependencies",
          "role": "dependencies",
          "parallel": true,
          "command": [
            "deptry",
            ".",
            "--extend-exclude",
            "(^|/)\\.(hooks|agents)(/|$)",
            "--no-ansi",
            "--json-output",
            "coverage/deptry.json"
          ],
          "report": { "type": "deptry", "path": "coverage/deptry.json" }
        },
        {
          "name": "imports",
          "role": "imports",
          "parallel": true,
          "command": ["lint-imports", "--no-logo"],
          "report": { "type": "import-linter", "path": "coverage/import-linter.txt", "stdout": true }
        }
      ]
    }
  ],
  "shared": [
    { "name": "lockfile", "role": "lockfiles", "command": ["uv", "sync", "--locked"] },
    {
      "name": "secrets-files",
      "role": "secrets-files",
      "parallel": true,
      "command": [
        "gitleaks",
        "dir",
        ".",
        "--redact=100",
        "--no-banner",
        "--report-format",
        "sarif",
        "--report-path",
        "coverage/gitleaks-files.sarif"
      ],
      "report": { "type": "gitleaks", "path": "coverage/gitleaks-files.sarif" }
    },
    {
      "name": "secrets-history",
      "role": "secrets-history",
      "parallel": true,
      "command": [
        "gitleaks",
        "git",
        ".",
        "--redact=100",
        "--no-banner",
        "--log-opts=--all",
        "--report-format",
        "sarif",
        "--report-path",
        "coverage/gitleaks-history.sarif"
      ],
      "report": { "type": "gitleaks", "path": "coverage/gitleaks-history.sarif" }
    },
    {
      "name": "vulnerabilities",
      "role": "vulnerabilities",
      "parallel": true,
      "command": [
        "osv-scanner",
        "scan",
        "source",
        "--lockfile=uv.lock",
        "--all-packages",
        "--format=json",
        "--output-file=coverage/osv.json"
      ],
      "report": { "type": "osv", "path": "coverage/osv.json" }
    },
    {
      "name": "security",
      "role": "security",
      "parallel": true,
      "command": [
        "semgrep",
        "scan",
        "--config",
        "p/python",
        "--jobs",
        "2",
        "--error",
        "--strict",
        "--time",
        "--json",
        "--output",
        "coverage/semgrep.json",
        "."
      ],
      "report": { "type": "semgrep", "path": "coverage/semgrep.json" }
    }
  ]
}

<!-- Use only when PRODUCT.md is missing. Study the repository, fill the prompts,
and remove irrelevant sections. Do not invent facts to fill a heading. -->

# [TODO: Product name]

[TODO: One sentence describing the actual product.]

## Register

[TODO: product or brand, based on the product's purpose.]

## Users

[TODO: Who uses it and what they are trying to accomplish.]

## Problem

[TODO: The concrete problem it solves.]

## Product Purpose

[TODO: What it does today and the intended outcome. Distinguish planned work.]

## Brand Personality / Tone

[TODO: The established voice and communication style.]

## Boundaries

[TODO: Explicit scope limits and important non-goals.]

## Stack

[TODO: Link relevant existing documentation and source locations without duplicating them.]