grinta 1.0.0__tar.gz

grinta-1.0.0/.gitignore

@@ -0,0 +1,81 @@
+# Python
+.venv/
+.venv-smoke/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+pip/
+
+# Node (residual)
+node_modules/
+dist/
+build/
+
+# OS
+.DS_Store
+*.log
+
+# Backup files
+*.bak
+
+# Secrets
+.env
+.env.local
+.jwt_secret
+~/
+backend/~/  # Never commit JWT secrets or sensitive backend configs
+
+# Runtime config (user-specific — only template is tracked)
+settings.json
+
+# Test coverage reports
+coverage/
+.coverage
+.coverage.*
+coverage.json
+coverage.xml
+coverage-full.xml
+coverage_report.json
+*.cover
+htmlcov/
+
+# Generated dependency audit exports
+audit-requirements.txt
+
+# Test framework caches
+.hypothesis/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.tox/
+
+# Analysis / lint tool output
+mypy_*.txt
+pylint_*.txt
+*_results.txt
+*_check.txt
+
+# Local pip download cache (must not be tracked)
+pip/cache/
+
+# Grinta runtime logs (always under install tree ``logs/``, not workspace cwd)
+logs/*
+!logs/README.md
+!logs/.gitkeep
+
+# Debug/error logs
+*.out
+tsc_errors*.txt
+
+backend/MagicMock/
+.pytest-reliability/
+bandit-out.json
+
+# Release assets and generated agent state
+backend/.grinta/
+rustup-init.exe
+grinta_raft.mp4
+docs/assets/grinta-demo.mp4
+docs/assets/grinta-demo-preview.webp
+traces/**/session.zip

grinta-1.0.0/CHANGELOG.md

@@ -0,0 +1,304 @@
+# Changelog
+
+All notable changes to Grinta will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- **Repository launch surface:** a compact README hero, animated recovery
+  preview, capability table, contributor call, and direct links to the
+  strongest autonomous-run evidence.
+- **Public showcase:** standardized case studies for the 4h 33m autonomous
+  session, failure recovery, issue-tracker build, and Raft key-value store.
+- **Shareable media:** a 1280 × 640 social-preview asset and a compressed,
+  looping WebP excerpt that links to the full demo.
+
+### Changed
+
+- **Package discovery metadata:** expanded the package description, keywords,
+  classifiers, and project URLs for package-index searchability.
+- **Citation metadata:** credits maintainer Youssef Mejdi and records the
+  public repository URL.
+
+### Removed
+
+- **`read_symbol` tool removed after a brief trial.** Targeted discovery remains
+  in `find_symbols`; file content is read through `read_file`. Removing the
+  dedicated tool keeps the final public file surface at six tools.
+
+- **`edit_symbol` tool removed.** The model was not using it; the schema
+  was complex (six optional disambiguation fields plus `new_content`),
+  and `replace_string` covers the same ground with a simpler schema the
+  model already uses confidently. Symbol discovery stays in `find_symbols`;
+  content reads stay in `read_file`.
+- **`create(type="symbol")` mode removed.** `create` is now file-only.
+  Insert new symbols via `replace_string` with an anchor line.
+- **`multiedit` `edit_symbol` command removed.** `multiedit` now
+  supports `replace_string` operations only. The `allOf`/`if-then`
+  conditional schema is gone; the operation shape is just
+  `path`, `old_string`, `new_string`, `replace_all`.
+
+### Changed
+
+- **Packaging:** PDF/DOCX/PPTX/LaTeX parsers (`pypdf`, `python-docx`,
+  `python-pptx`, `pylatexenc`) are included in the base install; the
+  `[documents]` extra is removed. Optional extras are now `[rag]`, `[browser]`,
+  and `[all]`.
+- **Packaging:** `debugpy` is no longer bundled in the base wheel. Python
+  debugging is auto-detected when `debugpy` is installed in the active
+  environment (`pip install debugpy`), consistent with other DAP adapters and
+  LSP servers. Contributor dev deps still include `debugpy`.
+- **Model-facing file API:** `read` renamed to `read_file`, `create` renamed
+  to `create_file`, and the old `read(type="symbols")` mode was retired. A
+  dedicated `read_symbol` tool was tried and later removed. Final public tools:
+  `read_file`, `find_symbols`, `create_file`, `replace_string`, `multiedit`,
+  `undo_last_edit`.
+- **CI:** `py-tests` required jobs on Linux and Windows run the full
+  `backend/tests/unit` corpus (fast PR gates), not a fixed nine-file slice.
+  [docs/CI.md](docs/CI.md) documents the tiers.
+- **Testing:** [`pytest.ini`](pytest.ini) `testpaths` defaults to
+  `backend/tests` (full tree for a bare `pytest`); use `pytest backend/tests/unit`
+  to match the required gates locally.
+- **Docs:** [CONTRIBUTING.md](CONTRIBUTING.md) testing instructions match CI;
+  added [docs/RELEASE_CHECKLIST.md](docs/RELEASE_CHECKLIST.md),
+  [docs/REGRESSION_TESTS.md](docs/REGRESSION_TESTS.md); user-facing autonomy
+  naming is **conservative** / **balanced** / **full** only
+  ([docs/SECURITY_CHECKLIST.md](docs/SECURITY_CHECKLIST.md),
+  [docs/USER_GUIDE.md](docs/USER_GUIDE.md)).
+- **OSS readiness:** added governance and ownership policy docs
+  ([GOVERNANCE.md](GOVERNANCE.md), [MAINTAINERS.md](MAINTAINERS.md)),
+  published [docs/SUPPORT_MATRIX.md](docs/SUPPORT_MATRIX.md), expanded
+  [SUPPORT.md](SUPPORT.md) with response targets, and added
+  [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+
+### Removed
+
+- **`supervised` autonomy spelling:** Config, `/autonomy`, and
+  `PermissionsConfig.get_preset()` no longer accept `supervised`; use
+  `conservative` (same behaviour). A clear validation error points to
+  `conservative` if old configs still say `supervised`.
+
+## [1.0.0-rc1] - 2026-04-29
+
+First release candidate. Includes everything in `0.56.0` plus the
+pre-launch polish below. Tagged as `rc1` to invite community feedback
+before the final `1.0.0` cut.
+
+### Added
+
+- **Symbol-aware reading restored** (tree-sitter-backed). Lets the
+  agent fetch named symbols or a whole file through the public file API,
+  replacing the previous multi-call dance of code search plus file reads.
+  Backed by the already-core
+  `backend.utils.treesitter_editor.TreeSitterEditor.find_symbol()`. Wired
+  through `planner.py`, `function_calling.py`, and the CLI display layer.
+- **README** rewritten with a multi-line pitch and an 11-row competitor
+  comparison table (Grinta vs Aider, Claude Code, Codex CLI) covering
+  install size, provider-agnosticism, local-first posture, LSP, DAP, HUD,
+  stuck-detection, hardened_local profile, checkpoint/resume, Windows
+  parity, and MCP support.
+- **Demo material**: `docs/DEMO_SCRIPT.md` — a 60-second asciinema scenario
+  (`demo_app/calc.py::average` `ZeroDivisionError`) plus an `agg` command
+  for converting the cast into a GIF for the README.
+- **Smoke-test scripts** for clean-box install verification:
+  - `scripts/smoke/smoke_install.sh` (Linux/macOS, accepts extras as positional
+    args; prefers a local wheel from `$WHEEL_DIR=./dist`, falls back to PyPI).
+  - `scripts/smoke/smoke_install.ps1` (Windows mirror; reports site-packages MB).
+  - `scripts/Dockerfile.smoke` (Python 3.12-slim base, ripgrep pre-installed,
+    `EXTRAS` env var picks the optional extras to test).
+  Each script runs `python -c "import backend"`, `--help`, and
+  `verify_optional_imports.py` so a broken extras gate is caught before
+  publishing to PyPI.
+- **GitHub label catalog** at `.github/labels.yml` covering triage,
+  type, severity, OS (`os: windows|linux|macos`), provider
+  (`provider: openai|anthropic|google|openrouter|ollama|lmstudio`), area
+  (`area: cli|engine|execution|lsp|dap|rag|mcp|safety|telemetry|packaging`),
+  contributor onboarding, and release governance. Apply with
+  `gh label sync -f .github/labels.yml`.
+
+### Changed
+
+- **Wheel size**: stable at ~1.4 MB on the base install (see `0.56.0`).
+- **Issue template** version hint bumped to `1.0.0rc1`.
+- **Autonomy is now a single-axis knob**. The three modes
+  (`conservative` / `balanced` / `full`) share identical execution,
+  prompting, and retry behaviour. The _only_ difference between them is
+  _when_ the runtime stops to ask the user before running an action:
+  conservative asks for every action, balanced asks only for high-risk
+  actions, full never asks. The system prompt no longer branches on the
+  mode (the previous "FULL AUTONOMOUS MODE" block has been replaced by a
+  single mode-agnostic sentence so the prompt stays correct when the
+  user toggles modes mid-session via `/autonomy`).
+- **Cost caps and iteration limits decoupled from autonomy**.
+  `max_cost_per_task`, `warn_at_cost`, `max_autonomous_iterations`, and
+  `stuck_threshold_iterations` are now standalone config keys with
+  global defaults; they apply universally regardless of autonomy mode.
+  `PermissionsConfig.get_preset()` no longer pre-fills cost caps per
+  mode, and the "this knob only applies in full autonomy" warning has
+  been removed.
+
+### Added
+
+- **Per-session "always allow" memory** for the confirmation gate. The
+  approval prompt now offers `[y/n/a=always]`; choosing `a` whitelists
+  that exact action signature (e.g. the literal command string) for the
+  remainder of the session so the agent does not re-ask for the same
+  `pytest -q`, `git status`, or `ls` over and over. The whitelist is
+  in-memory only and is cleared on process exit.
+
+### Migration
+
+- **`autonomy_level: supervised` is renamed to `conservative`** to
+  better describe the behaviour ("confirm every action in the confirmation
+  flow") and to avoid implying extra oversight features that don't exist.
+  The string `supervised` is **rejected** in config files and on the
+  `/autonomy` slash command; use `conservative` instead.
+- Set `max_budget_per_task` explicitly in `settings.json` for per-task
+  spend caps (see [docs/SETTINGS.md](docs/SETTINGS.md)).
+
+## [0.56.0] - 2026-04-29
+
+### Added
+
+- **Auto-discovery of LSP servers**: `LspClient` now probes `PATH` for
+  installed language servers (pylsp, typescript-language-server, rust-analyzer,
+  gopls, clangd, jdtls, omnisharp, lua-language-server, bash-language-server,
+  vscode-html-language-server, vscode-css-language-server, vscode-json-language-server,
+  yaml-language-server, ruby-lsp, solargraph, intelephense, terraform-ls).
+  No more pylsp-only gating.
+- **Auto-discovery of DAP debug adapters**: `DAPDebugManager` now probes
+  `PATH` for `dlv`, `codelldb`, `lldb-dap`, `netcoredbg`, `node`, etc. and
+  falls back to a sensible adapter command when the model omits `adapter_command`.
+  Python remains batteries-included via bundled `debugpy`.
+- `detect_lsp_servers()` and `detect_debug_adapters()` discovery helpers
+  exported for diagnostics / UI.
+- Optional dependency extras: `[rag]` (chromadb + ONNX MiniLM-L6-v2),
+  `[documents]` (PyPDF2 / python-docx / python-pptx / pylatexenc),
+  `[browser]` (browser-use), and `[all]` (everything).
+
+### Changed
+
+- `enable_lsp_query` now defaults to **`True`** — the planner enables the
+  `lsp` tool whenever any supported LSP server is on `PATH`.
+- DAP `start` no longer requires the model to supply `adapter_command` for
+  languages whose adapter is auto-discoverable.
+- **Massive install slim-down**: base wheel dropped from ~1.6GB to ~1.4MB.
+  Achieved by gating `chromadb` behind the `[rag]` extra, dropping the
+  redundant `sentence-transformers` + `torch` + `transformers` stack in
+  favour of chromadb's bundled ONNX `DefaultEmbeddingFunction` (384-dim,
+  ~80MB) when `[rag]` is installed, and moving document parsers
+  (`PyPDF2`, `python-docx`, `python-pptx`, `pylatexenc`) behind
+  `[documents]`. `enable_vector_memory` and `enable_hybrid_retrieval`
+  agent-config flags now default to `False`.
+- `MemoryMonitor` migrated from `memory-profiler` to a `psutil`-based RSS
+  sampler thread (no behaviour change for callers).
+
+### Removed
+
+- **GraphRAG** subsystem (`backend/context/graph_rag.py`,
+  `graph_store.py`) and its dependent tools (`explore_tree_structure`,
+  `read_symbol_definition`). The four remaining retrieval primitives
+  (`grep` / `glob` via ripgrep, `find_symbols` / `read` via tree-sitter,
+  `lsp` via LSP) cover the same surface
+  without the index-maintenance cost.
+- **`ReRanker`** class and the cross-encoder rerank step from
+  `EnhancedVectorStore` — over-engineered for a CLI agent's recall
+  workload. Hybrid retrieval now returns top-k candidates directly.
+- Unused dependencies dropped from base install: `sentence-transformers`,
+  `optimum`, `puremagic`, `memory-profiler`, plus the eager top-level
+  imports of `python-docx` / `python-pptx` / `pylatexenc` / `PyPDF2` /
+  `chromadb`.
+
+## [0.55.0] - 2026-04-29
+
+First public open-source release. Grinta is now a **CLI-only**, local-first
+coding agent with no managed web UI, no hosted control plane, and no built-in
+HTTP server.
+
+### Added
+
+- Open-source release on PyPI as `grinta`, with Homebrew and Scoop manifests
+  in `packaging/` for native installs on macOS and Windows.
+- `CHANGELOG.md` following [keepachangelog.com](https://keepachangelog.com)
+  format and `SECURITY.md` describing reporting, threat model, and supported
+  versions.
+- `docs/SECURITY_CHECKLIST.md` documenting the trust boundary, built-in
+  protections, and operator pre-flight checklist for untrusted repositories.
+- `hardened_local` execution profile with workspace-scoped allowlists for git,
+  package, and network-capable commands; CRITICAL refusal gate enforced in
+  `safety_validator.py` regardless of profile or autonomy level.
+- Session checkpoint and resume support via `SessionCheckpointManager`.
+- `LLMRateGovernor` per-session token-rate throttling and cost-acceleration
+  loop detection in `StuckDetector` to bound runaway agent loops.
+- Real auto-recovery in `ErrorRecoveryStrategy` covering network retry,
+  context truncation, and runtime restart.
+- Canonical local-server startup planner shared by `start_server.py` and the
+  embedded mode, with the resolved plan surfaced in health and settings
+  output.
+- Audit logging middleware for sensitive operations (settings, secrets,
+  conversations) writing to `~/.grinta/workspaces/<id>/storage/<session>/audit/`.
+- Plugin authoring guide (`docs/PLUGIN_GUIDE.md`) and MCP integration examples
+  (`docs/MCP_EXAMPLES.md`).
+- Cross-platform CI matrix on GitHub Actions: Ubuntu and Windows are required
+  gates; macOS runs as advisory in both `py-tests.yml` and `e2e-tests.yml`.
+
+### Changed
+
+- Repositioned Grinta as a **CLI-only** coding agent. Removed the React web
+  UI, Socket.IO surface, Textual TUI prototype, and the public
+  `/api/v1/monitoring/*` HTTP endpoints. The CLI is the sole interactive
+  surface.
+- Removed all cloud runtime dependencies (`e2b`, `modal`,
+  `runloop-api-client`, `daytona`) for a strictly local-first runtime.
+- Renamed `get_remote_runtime_config` -> `get_runtime_config`.
+- Hardened the local execution policy: interactive terminals, command cwd,
+  uploads, and direct file access stay workspace-scoped under
+  `security.execution_profile = "hardened_local"`.
+- Crash recovery now fails closed more often, tracks restore provenance, and
+  uses persisted control-event evidence to distinguish stale WAL from
+  ambiguous recovery.
+- Trimmed base dependencies: `asyncpg` and `libtmux` moved to optional
+  groups; `python-socketio` removed from base runtime.
+- Consolidated editor tools around a smaller public file API;
+  older experimental editor modules are deprecated.
+- Broke up `action_execution_server.py` (1944 → 4 focused modules),
+  `conversation_memory.py` (1709 → 4 focused modules), and `config/utils.py`
+  (43 KB → 4 focused modules).
+- Rewrote `README.md` and the public docs set (`docs/INSTALL.md`,
+  `docs/QUICK_START.md`, `docs/USER_GUIDE.md`, `docs/TROUBLESHOOTING.md`,
+  `docs/ARCHITECTURE.md`, `docs/DEVELOPER.md`) for the CLI-only positioning.
+- Repository home moved to `josephsenior/Grinta-Coding-Agent`; all release
+  metadata, support links, and issue templates updated to match.
+
+### Deprecated
+
+- `ultimate_editor.py` — use the public file API instead.
+- `universal_editor.py` — use the public file API or `atomic_refactor`
+  internally instead.
+
+### Removed
+
+- React frontend, Socket.IO real-time streaming, Textual TUI replacement, and
+  the `/api/v1/monitoring/agent-metrics` HTTP endpoint.
+- `start_backend.ps1`, `openapi.json`, archival `client/` package, the dead
+  `service_circuit_breaker.py`, and stale socket-era tests.
+
+### Security
+
+- New `SECURITY.md` documents reporting, supported versions, the threat
+  model, and the trust boundary (Grinta runs as the operator’s OS user — it
+  is **not** a sandbox).
+- Secret masker strips known credential patterns from event-stream output,
+  audit logs, and panel renders before display.
+- Telemetry remains **off by default**; the only on-disk telemetry is the
+  local `AuditLogger`. No outbound calls are made beyond configured LLM
+  providers and explicitly enabled MCP servers.
+
+[Unreleased]: https://github.com/josephsenior/Grinta-Coding-Agent/compare/v1.0.0-rc1...HEAD
+[1.0.0-rc1]: https://github.com/josephsenior/Grinta-Coding-Agent/releases/tag/v1.0.0-rc1
+[0.56.0]: https://github.com/josephsenior/Grinta-Coding-Agent/releases/tag/v0.56.0
+[0.55.0]: https://github.com/josephsenior/Grinta-Coding-Agent/releases/tag/v0.55.0

grinta-1.0.0/CITATION.cff

@@ -0,0 +1,12 @@
+cff-version: 1.2.0
+title: Grinta
+message: "If you use Grinta in research, please cite this software."
+type: software
+authors:
+  - family-names: Mejdi
+    given-names: Youssef
+    alias: josephsenior
+repository-code: "https://github.com/josephsenior/Grinta-Coding-Agent"
+url: "https://github.com/josephsenior/Grinta-Coding-Agent"
+license: MIT
+version: "1.0.0"

grinta-1.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,47 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery and unwelcome sexual attention
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without explicit permission
+* Other conduct which could reasonably be considered inappropriate
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainers at:
+
+- conduct@app.ai
+
+Security issues should be reported through the private channels in `SECURITY.md`,
+not through Code of Conduct channels.
+
+All complaints will be reviewed and investigated promptly and fairly. Maintainers
+will respect reporter confidentiality to the extent possible and communicate follow-up
+status when an investigation is closed.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1.

grinta-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,223 @@
+# Contributing to Grinta
+
+Thank you for your interest in contributing to Grinta! This guide will help you get started.
+
+## Development Setup
+
+### Prerequisites
+
+- **Git** (to clone and contribute)
+- **No manual Python or `uv`** — `START_HERE.ps1` / `start_here.sh` install the toolchain when missing
+
+### Getting Started
+
+```bash
+git clone https://github.com/josephsenior/Grinta-Coding-Agent.git Grinta
+cd Grinta
+bash start_here.sh
+```
+
+Windows PowerShell:
+
+```powershell
+.\START_HERE.ps1
+```
+
+That installs `uv` and Python 3.12 if needed, natively downloads `ripgrep`, syncs `dev-test` dependencies, runs setup when `settings.json` is missing, and installs the `grinta` CLI globally via `uv tool install`.
+
+Manual equivalent:
+
+```bash
+uv python install 3.12
+uv run python scripts/bootstrap_env.py dev-test
+uv tool install -e .
+```
+
+**Windows note:** `make` targets in the Makefile are aimed at macOS, Linux, and WSL.
+On native Windows, use `START_HERE.ps1` for the same happy path, and run pytest directly:
+
+```powershell
+uv run python scripts/bootstrap_env.py dev-test
+$env:PYTHONPATH = '.'
+uv run pytest backend/tests/unit/ --tb=short -q
+```
+
+### Repo hygiene
+
+- Treat `dist/`, `logs/`, local cache directories, and one-off diagnostics as disposable output, not source.
+- Historical narrative docs under `docs/journey/` are intentionally not the current spec; use `README.md`, `docs/USER_GUIDE.md`, `docs/ARCHITECTURE.md`, and `docs/DEVELOPER.md` for current behavior.
+- Prefer the current helper surfaces for local work:
+  - `make help`
+  - `make run-cli`
+  - `make test-unit`
+  - `make reliability-gate`
+
+### Local configuration (source checkout)
+
+- **`settings.json`** at the repository root holds non-secret defaults (`llm_model`,
+  `llm_provider`, `${LLM_API_KEY}` placeholder).
+- **`.env`** beside `settings.json` stores the real `LLM_API_KEY` (copy from
+  [`.env.template`](.env.template); never commit secrets).
+- **`APP_ROOT`** overrides where `settings.json` is resolved when you need an
+  isolated config directory (for example smoke tests or multiple profiles).
+- Installed runs (`pipx`, Homebrew, Scoop) use `~/.grinta/settings.json` instead
+  of the repo root unless `APP_ROOT` is set.
+
+Launching `grinta` or `uv run python -m backend.cli.entry` without a configured
+key runs the same setup wizard as `grinta init` on first interactive launch.
+Use `grinta init` when you want to configure without the TUI, or for `--non-interactive` / CI.
+
+See also [docs/QUICK_START.md](docs/QUICK_START.md) and [docs/USER_GUIDE.md](docs/USER_GUIDE.md).
+
+## How to Contribute
+
+### Reporting Bugs
+
+- Use the [Bug Report template](.github/ISSUE_TEMPLATE/bug_template.yml)
+- Include: steps to reproduce, expected vs actual behavior, environment details
+- Attach logs from `backend/` console output if applicable
+
+### Suggesting Features
+
+- Use the [Feature Request template](.github/ISSUE_TEMPLATE/feature_request.md)
+- Describe the use case, not just the solution
+
+### Submitting Code
+
+1. **Fork** the repository
+2. **Branch** from `main`: `git checkout -b feature/your-feature`
+3. **Implement** your change following existing patterns
+4. **Test**: see [Testing before a pull request](#testing-before-a-pull-request)
+5. **Commit** with a clear message: `feat: add trajectory pagination`
+6. **Push** and open a Pull Request
+
+### Testing before a pull request
+
+**Required** GitHub Actions jobs differ by platform ([docs/CI.md](docs/CI.md)):
+
+- **Linux (`gates-on-linux`):** unit corpus with coverage — match locally with:
+
+```bash
+uv run python scripts/bootstrap_env.py dev-test
+PYTHONPATH=. uv run pytest --cov=backend --cov-fail-under=75 backend/tests/unit
+```
+
+- **Windows (`gates-on-windows` + `gates-on-windows-extended`):** unit corpus, then integration/e2e/stress — match locally with:
+
+```bash
+uv run python scripts/bootstrap_env.py dev-test
+PYTHONPATH=. uv run pytest backend/tests/unit
+PYTHONPATH=. uv run pytest backend/tests/integration backend/tests/e2e backend/tests/stress
+```
+
+- **macOS (`gates-on-macos` + `gates-on-macos-extended`):** same extended tier as Windows.
+
+For day-to-day edits, `pytest backend/tests/unit` is usually enough before you push. Run the full Linux corpus when your change touches integration, e2e, stress, or cross-cutting orchestration paths.
+
+Optional: `uv run pytest backend/tests/unit -q` for quieter output.
+
+A bare `pytest` or `PYTHONPATH=. uv run pytest` from the repository root discovers all of **`backend/tests`** (unit, integration, e2e, stress, and so on) per [`pytest.ini`](pytest.ini). That run is much slower and may need extra services; use it when your change spans those tiers or before a large release.
+
+The scheduled **Heavy / Integration Tests** job runs a marker-filtered slice (`pytest backend/tests -m "heavy or integration or benchmark"`). See [docs/CI.md](docs/CI.md#heavy--integration--benchmark-tier).
+
+If your change touches the CLI, REPL, or orchestration hot paths, also run the [CLI regression workflow](.github/workflows/e2e-tests.yml) locally when possible (it may also run on PRs when files under `backend/`, `launch/`, etc. change).
+
+For bugfix PRs, prefer adding a **regression test** next to the code you fixed (see [docs/REGRESSION_TESTS.md](docs/REGRESSION_TESTS.md)).
+
+Dependency profiles are centralized in `scripts/bootstrap_env.py` (for example: `base`, `browser`, `dev`, `dev-test`, `dev-test-browser`).
+
+For a one-command onboarding sanity check on Unix-like systems:
+
+```bash
+bash scripts/check_contributor_bootstrap.sh
+```
+
+For packaging / onboarding smoke (wheel + source non-interactive checks):
+
+```bash
+uv build --wheel
+WHEEL_DIR=./dist ./scripts/smoke/smoke_install.sh
+./scripts/smoke/smoke_source_onboarding.sh
+```
+
+Maintainers: see [docs/onboarding_reports/](docs/onboarding_reports/) for GA fresh-machine evidence.
+
+### Code Standards
+
+**Backend (Python):**
+
+- Type hints on all function signatures
+- Docstrings on public functions (Google style)
+- `async def` for I/O-bound operations
+- Use `app_logger` for logging (not `print()`)
+- Follow existing service decomposition patterns
+
+### Commit Convention
+
+```text
+type: short description
+
+types: feat, fix, refactor, docs, test, chore, perf
+```
+
+## Where to start in the codebase
+
+New contributors: read **[docs/CONTRIBUTOR_MAP.md](docs/CONTRIBUTOR_MAP.md)** first.
+It lists task-oriented entry points (CLI, orchestration, inference, MCP, tests)
+without reading the whole tree. Day-to-day reference: [docs/DEVELOPER.md](docs/DEVELOPER.md).
+
+## Architecture Quick Reference
+
+| Directory | Purpose |
+| --- | --- |
+| `backend/orchestration/` | Session orchestration (decomposed services) |
+| `backend/orchestration/services/` | Service classes composing the orchestrator |
+| `backend/cli/` | CLI entrypoint, REPL, init wizard, and session commands |
+| `backend/ledger/` | Event sourcing, backpressure-aware stream, durable writer |
+| `backend/persistence/` | File & DB storage implementations |
+| `backend/inference/` | Provider registry, LLM clients, model catalogs |
+| `backend/integrations/` | MCP adapters (external tools) |
+| `backend/engine/` | Production agent engine package |
+| `backend/context/` | Context memory, compactors, RAG, vector store |
+| `backend/core/` | Config (Pydantic), exceptions, schemas, logging |
+| `backend/security/` | Security analyzer, input validation |
+
+### Orchestration Service Map
+
+The `SessionOrchestrator` delegates work to these services (implementation split
+across mixins under `backend/orchestration/mixins/`):
+
+| Service | Responsibility |
+| --- | --- |
+| `LifecycleService` | Init, reset, config binding |
+| `ActionExecutionService` | Get & execute next agent action |
+| `ActionService` | Action intake, pending coordination |
+| `RecoveryService` | Exception classification, retry orchestration |
+| `TaskValidationService` | Optional completion-quality warning pipeline |
+| `CircuitBreakerService` | Circuit breaker pattern |
+| `StuckDetectionService` | 6-strategy stuck/loop detection |
+| `IterationGuardService` | Iteration limit control flags |
+| `StateTransitionService` | Agent state machine transitions |
+| `StepGuardService` | Pre-step guard checks |
+| `StepPrerequisiteService` | Can-step prerequisite checks |
+| `PendingActionService` | Pending action get/set/timeout |
+| `ConfirmationService` | User confirmation flow |
+| `SafetyService` | Safety validation |
+| `RetryService` | Retry count & backoff |
+| `ObservationService` | Observation event handling |
+| `AutonomyService` | Autonomy controller init |
+| `IterationService` | Iteration counting |
+| `OrchestrationContext` | Shared facade for services |
+
+### Key Patterns
+
+- **Event sourcing**: All agent actions/observations go through `EventStream`
+- **Backpressure**: `EventStream` caps in-flight events and applies backpressure
+- **Compactor**: Memory management via `Compactor` with configurable strategies
+- **State checkpoints**: Timestamped state snapshots (last 3 kept for crash recovery)
+- **Circuit breaker**: Trips after consecutive errors/stuck detections
+- **Safe defaults**: Budget capped at $5, circuit breaker ON, graceful shutdown ON
+
+## Questions?
+
+Open an issue with the relevant template if you need help or want to discuss a change.