kaiten-cli 0.3.3__tar.gz

kaiten_cli-0.3.3/.gitignore

@@ -0,0 +1,29 @@
+.venv/
+.verify-venv/
+__pycache__/
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+.claude-flow/
+.bin/
+.pipx/
+.uv-tools/
+build/
+dist/
+*.egg-info/
+*.pyc
+.env
+.env_stage
+.env_private
+.DS_Store
+/ARCHITECTURE_REVIEW.md
+/docs/archive/
+/docs/audits/
+/scripts/analyze_codex_kaiten_sessions.py
+/tests/test_analyze_codex_kaiten_sessions.py
+/PLAN*.md
+/PARITY_CHECKLIST.md

kaiten_cli-0.3.3/AGENTS.md

@@ -0,0 +1,97 @@
+# kaiten-cli for Agents
+
+This file only captures agent-specific guidance.
+
+For install, human-oriented usage, and the full docs map, start with [README.md](README.md).  
+For the full command catalog, use [COMMAND_REFERENCE.md](COMMAND_REFERENCE.md).  
+For the system map, use [ARCHITECTURE.md](ARCHITECTURE.md).
+For optimized LLM workflows, start with:
+
+- [skills/kaiten-cli-heavy-data/SKILL.md](skills/kaiten-cli-heavy-data/SKILL.md)
+- [skills/kaiten-cli-metrics/SKILL.md](skills/kaiten-cli-metrics/SKILL.md)
+- [skills/kaiten-cli-mutations/SKILL.md](skills/kaiten-cli-mutations/SKILL.md)
+
+## Conversation locale
+
+Pass `--locale ru` for Russian conversations and `--locale en` for English or
+other languages, before the command name in every invocation, including help,
+discovery and `--json`. Change it when the user changes the conversation language.
+Explicit `--locale` overrides `KAITEN_CLI_LOCALE`; the default is `en`.
+The CLI does not infer conversation language from the operating system.
+Only CLI-owned prose is localized; command names, JSON keys, enum values and
+Kaiten/user data remain unchanged. Examples below omit the locale for brevity;
+add the current conversation locale when executing them.
+
+## Discovery-first flow
+
+Prefer this sequence before calling mutations or heavy commands:
+
+```bash
+kaiten --help
+kaiten search-tools cards
+kaiten describe cards.list
+kaiten examples cards.list
+```
+
+Run discovery once per unfamiliar command family, mutation workflow, or heavy
+read. Reuse the discovered contract inside the same workflow instead of
+repeating `describe` before every call.
+
+Use `--json` by default for machine-safe parsing:
+
+```bash
+kaiten --json spaces list --compact --fields id,title
+```
+
+If the workflow will ask many questions about the same space or board set, switch early to the local-first path:
+
+```bash
+kaiten --json snapshot build --name team-basic --space-id 10 --preset basic
+kaiten --json query cards --snapshot team-basic --view summary --fields id,title,state
+```
+
+## Config and precedence
+
+Credential resolution order:
+
+1. `--profile <name>`
+2. active profile from config
+3. `KAITEN_DOMAIN` + `KAITEN_TOKEN`
+
+Recommended persistent setup:
+
+```bash
+kaiten profile add main --domain <company-subdomain-or-url> --token <api-token> --set-active
+```
+
+## Safety and efficiency
+
+- Start with read-only commands.
+- Normal profiles can mutate; treat real credentials as real writes.
+- For analysis-only workflows, use global `--read-only` or `KAITEN_CLI_READ_ONLY=1`; this blocks remote mutations while allowing local snapshot lifecycle operations and the POST-backed chart retrieval commands reported with `read_only_allowed=true`.
+- `KAITEN_LIVE=1|true` is the explicit per-run gate for the live test suite.
+- Prefer `--compact` and `--fields` to reduce payload and token cost.
+- Request-scoped cache for safe GETs is built in; default `--cache-mode auto` also persists cacheable safe reads across CLI processes.
+- Omit `--cache-mode` for ordinary workflows: this keeps the default `auto`.
+- Use `--cache-mode refresh` once at a freshness boundary; never put it inside an entity loop. For a reused local working set, prefer `snapshot refresh`.
+- Use `--cache-mode off` only for cache debugging, privacy-sensitive reads, or high-churn polling.
+- Use `--cache-mode readwrite` only with an explicit, meaningful `--cache-ttl-seconds` when a fixed TTL is required.
+- Heavy/batch reads and dense repeated entity reads get longer adaptive TTLs in `auto`; do not force tiny TTLs in wrapper scripts unless freshness is the main requirement.
+- JSON responses include top-level `stats`; check `http_request_count`, `api_wait_ms`, cache counters, and grouped path families before repeating expensive calls.
+- Use `--verbose` when you need request-path and execution diagnostics; diagnostics stay in `stderr`.
+- Use `--trace-file` or `KAITEN_TRACE_FILE` when you need a JSONL trace of real command cost across a longer workflow.
+- Trace is required for wrappers with at least three CLI commands, expected runs above ten HTTP requests, or unavoidable loops. Review it with `kaiten --json trace summarize --file <trace.jsonl>`.
+- Treat `aggregated` and `synthetic` tools as potentially more expensive than `direct_http`.
+- For high-cardinality reads, follow the heavy-data skill instead of inventing a per-entity loop.
+- For metrics workflows, follow the metrics skill instead of reconstructing raw history one card at a time.
+- For repeated report or analytics questions on one working set, prefer `snapshot build` plus `query cards` / `query metrics` over re-fetching the same population.
+- Keep `query cards` in `summary` view by default; use `detail` or `evidence` only after local candidate reduction.
+- Treat `query metrics` as a generic local metrics layer unless a workflow explicitly defines tenant-specific flow semantics outside the CLI.
+- Prefer `space-topology.get`, `cards.batch-get`, `time-logs.batch-list`, `space-activity-all.get`, `card-children.batch-list`, `comments.batch-list`, and `card-location-history.batch-get` over manual orchestration loops.
+- When two or more entity IDs are known and `describe` reports `bulk_alternative`, use the bulk command.
+- When the same population is needed a second time, build a snapshot and continue with local `query cards` / `query metrics`.
+- Before a live mutation, use `kaiten --json --profile <name> --read-only profile probe`, then follow the mutation skill: discovery, read-only investigation, exact preview, authorization, resumable manifest, small batches, and field-scoped readback.
+- Addon state lives outside the normal card fields: use `card-addon-data` / `user-addon-data` for raw addon storage, and the `github-addon` commands for PRs, branches, commits and issues shown on a card.
+- Attaching a PR to a card usually means the GitHub addon, not `external-links create`; check both sources when looking for every PR a card references.
+- The GitHub addon UUID is derived from its mount path only on on-premises Kaiten; elsewhere it is random. `addons uid` returns the derived guess, `space-addons list` and `company-addons list` return the real one, and the `github-addon` commands re-resolve it from the card's space when the guess finds no data.
+- Live validation is opt-in and documented in [LIVE_VALIDATION.md](LIVE_VALIDATION.md).

kaiten_cli-0.3.3/API_BEHAVIOR_MATRIX.md

@@ -0,0 +1,107 @@
+# API Behavior Matrix
+
+Этот документ фиксирует API-контракты для `kaiten-cli`, ранее наблюдавшиеся на live test tenant и закодированные в текущем live harness.
+
+Запуск live suite по-прежнему gated только через `KAITEN_LIVE=1|true`; special-case по домену или profile metadata для этого не используется.
+
+## Verification metadata
+
+| Поле | Значение |
+|------|----------|
+| Contract baseline | `kaiten-cli v0.1.23` |
+| Tenant class | Kaiten sandbox test tenant |
+| Текущий аудит | `2026-07-09`; live suite **не запускался** |
+| Последняя полная live campaign | `TBD`: дата и commit не подтверждены в репозитории |
+| Источник до следующего live run | checked-in contracts и `tests/live/`; записи ниже нельзя считать повторно подтверждёнными текущим аудитом |
+
+После следующей полной live campaign эту таблицу нужно обновить точными датой, commit SHA, версией CLI и tenant class. Secrets, tenant URL и идентификаторы тестовых сущностей сюда не записываются.
+
+## Default rule
+
+Все canonical команды из registry, которые не перечислены ниже, считаются `live_passed`: они должны проходить по normal success-path в полном live suite.
+
+## Validated success-path contracts with special notes
+
+| Command | Verb / Path | Status | Notes |
+|---------|-------------|--------|-------|
+| `automations.create` | `POST /spaces/{space_id}/automations` | `live_passed` | Успешно проходит на sandbox с known-good payload: `trigger.type=card_created`, `action.type=add_assignee`, `created`, `data.variant`, `data.userId`. |
+| `automations.update` | `PATCH /spaces/{space_id}/automations/{automation_id}` | `live_passed` | Успешно проходит для automation, созданной с known-good payload. |
+| `automations.delete` | `DELETE /spaces/{space_id}/automations/{automation_id}` | `live_passed` | Успешный cleanup подтверждён в live validation. |
+
+## Runtime-shaped contracts
+
+| Command | Verb / Path | Status | Notes |
+|---------|-------------|--------|-------|
+| `boards.delete` | `DELETE /spaces/{space_id}/boards/{board_id}` | `live_passed_with_runtime_fix` | Sandbox требует `force`; CLI передаёт его в query и body. |
+
+## Synthetic reads
+
+| Command | Primary endpoint | Status | Fallback |
+|---------|------------------|--------|----------|
+| `projects.cards.list` | `GET /projects/{project_id}/cards` | `synthetic_read` | При `405` CLI делает `GET /projects/{project_id}?with_cards_data=true` и извлекает embedded cards list. |
+| `checklists.list` | `GET /cards/{card_id}` | `synthetic_read` | Extracts embedded `checklists` instead of the collection GET, which returned 405 on the tested tenant and was also reported on production in [kaiten-mcp PR #4](https://github.com/ViktorOgnev/kaiten-mcp/pull/4). |
+| `checklist-items.list` | `GET /cards/{card_id}/checklists/{checklist_id}` | `synthetic_read` | Extracts `items` from the individual checklist, avoiding the unsupported collection GET. API errors are preserved. |
+
+## Stable expected-error contracts
+
+| Command | Verb / Path | Status | Expected statuses | Notes |
+|---------|-------------|--------|-------------------|-------|
+| `removed-boards.list` | `GET /boards/removed` | `live_passed_as_expected_error` | `405` | Sandbox recycle-bin endpoint unsupported. |
+| `removed-cards.list` | `GET /cards/removed` | `live_passed_as_expected_error` | `405` | Sandbox recycle-bin endpoint unsupported. |
+| `card-subscribers.list` | `GET /cards/{card_id}/subscribers` | `live_passed_as_expected_error` | `405` | Direct subscriber listing unsupported on sandbox. |
+| `column-subscribers.list` | `GET /columns/{column_id}/subscribers` | `live_passed_as_expected_error` | `405` | Direct subscriber listing unsupported on sandbox. |
+| `service-desk.users.update` | `PATCH /service-desk/users/{user_id}` | `live_passed_as_expected_error` | `400`, `403`, `404`, `405` | Для текущего sandbox-аккаунта API возвращает `400 Should be service desk user`, если пользователь не является SD user. |
+| `service-desk.organization-users.update` | `PATCH /service-desk/organizations/{organization_id}/users/{user_id}` | `live_passed_as_expected_error` | `400`, `403`, `404`, `405` | Обновление permissions для organization-user остаётся sandbox-dependent even after successful add. |
+
+## Conditional success-or-error contracts
+
+Эти команды остаются live-correct, даже если sandbox вместо success-path возвращает ожидаемый `4xx`.
+
+| Command family | Status | Expected statuses | Notes |
+|----------------|--------|-------------------|-------|
+| `sprints.create` | `live_passed_as_expected_error` | `403`, `405` | Создание спринта зависит от sandbox permissions/capabilities. |
+| `sprints.list` | `live_passed_as_expected_error` | `403`, `405` | Чтение списка спринтов зависит от sandbox permissions/capabilities. |
+| `service-desk.users.set-temp-password` | `live_passed_as_expected_error` | `403`, `404`, `405` | На sandbox может либо успешно сработать, либо вернуть documented `403/404/405`; live suite принимает оба исхода. |
+| `sprints.get`, `sprints.delete` | `live_passed_as_expected_error` | `403`, `404`, `405` | При недоступном create live suite валидирует sentinel error contract. |
+| `sprints.update` | `live_passed_as_expected_error` | `403`, `404`, `405`, `500` | На sandbox update по sentinel sprint id может отдавать `500`; это зафиксировано как documented sandbox defect contract. |
+| `automations.get` | `live_passed_as_expected_error` | `405` | GET-single для automation может быть unsupported даже после успешного create. |
+| `automations.copy` | `live_passed_as_expected_error` | `400`, `403`, `404`, `405` | Даже при live-valid source automation copy остаётся sandbox-dependent. |
+| `webhooks.get`, `webhooks.delete` | `live_passed_as_expected_error` | `404`, `405` | После create эти endpoints могут быть недоступны как отдельные singleton operations. |
+| `workflows.create` | `live_passed_as_expected_error` | `403`, `405` | Создание workflow зависит от sandbox permissions/capabilities. |
+| `workflows.get`, `workflows.update`, `workflows.delete` | `live_passed_as_expected_error` | `403`, `404`, `405` | При недоступном create live suite валидирует sentinel error contract. |
+| `service-desk.requests.create` | `live_passed_as_expected_error` | `400`, `403`, `404`, `405` | Request creation permission-dependent. |
+| `service-desk.requests.get`, `service-desk.requests.update`, `service-desk.requests.delete` | `live_passed_as_expected_error` | `403`, `404`, `405` | При недоступном create live suite валидирует sentinel error contract. |
+| `service-desk.sla-rules.create` | `live_passed_as_expected_error` | `400`, `403`, `404`, `405` | SLA rule creation schema- and permission-dependent. |
+| `service-desk.sla-rules.update`, `service-desk.sla-rules.delete` | `live_passed_as_expected_error` | `400`, `403`, `404`, `405` | При недоступном create live suite валидирует sentinel error contract. |
+| `compute-jobs.cancel` | `live_passed_as_expected_error` | `400`, `404`, `409` | Cancel зависит от состояния compute job. |
+| `user-timers.list` | `live_passed_as_expected_error` | `403`, `405` | Sandbox timer surface нестабилен. |
+| `user-timers.create` | `live_passed_as_expected_error` | `400`, `403`, `405`, `409` | Timer creation зависит от sandbox semantics. |
+| `user-timers.get`, `user-timers.update`, `user-timers.delete` | `live_passed_as_expected_error` | `403`, `404`, `405` | При недоступном create live suite валидирует sentinel error contract. |
+
+## Not yet live-validated
+
+Эти команды добавлены после последней полной live campaign. Сценарии для них уже есть в
+`tests/live/`, но прогона, подтверждающего контракт, не было, поэтому default rule
+`live_passed` на них не распространяется.
+
+| Command family | Verb / Path | Status | Notes |
+|----------------|-------------|--------|-------|
+| `restrictions.list`, `restrictions.get` | `GET /spaces/{space_id}/restrictions` | `live_not_validated` | Недокументированное расширение по серверному коду. Весь список без пагинации; `get` выбирает UUID из списка и возвращает явную ошибку при отсутствии. Ограничения workflow исключены. |
+| `restrictions.create`, `restrictions.copy` | `POST /spaces/{space_id}/restrictions` | `live_not_validated` | Создание принимает `conditions` и `restrictions`; копирование передаёт `source_restriction_id` в целевое пространство и сохраняет фактический статус ответа, включая `broken`. |
+| `restrictions.update`, `restrictions.delete` | `PATCH` / `DELETE /spaces/{space_id}/restrictions/{restriction_id}` | `live_not_validated` | PATCH передаёт только заданные поля; массивы заменяются целиком. `status=active\|disabled`. Для `error_text` необходимо ещё одно поле. DELETE может вернуть пустое тело. Opt-in lifecycle и проверяемая очистка добавлены, но не запускались. |
+| `addons.list` | `GET /addons` | `live_not_validated` | Каталог опубликованных аддонов без фильтра по компании; live suite принимает success или `403/405`. |
+| `company-addons.list` | `GET /company/addons` | `live_not_validated` | Аддоны, зарегистрированные самой компанией, включая неопубликованные. |
+| `addons.uid` | локальная команда | `live_not_validated` | UUID v5 считается локально, обращения к API нет; проверяется совпадение с эталонным UID `/github`. |
+| `space-addons.list` | `GET /spaces/{space_id}/addons` | `live_not_validated` | Требует права `space.addons.read`. |
+| `space-addons.install`, `space-addons.uninstall` | `PATCH` / `DELETE /spaces/{space_id}/addons/{addon_uid}` | `live_not_validated` | В live suite проверяются только на sentinel UID, чтобы не менять набор аддонов реального пространства. Sentinel подобран так, чтобы проходить `uuidIdRule`, иначе probe подтверждал бы 404 от несовпадения маршрута, а не контракт эндпоинта. |
+| `card-addon-data.get`, `user-addon-data.get` | `GET .../addons-data/{addon_uid}` | `live_not_validated` | Чтение; для неустановленного аддона возможен пустой ответ или `403/404/405`. |
+| `card-addon-data.set`, `user-addon-data.set` | `PATCH .../addons-data/{addon_uid}` | `live_not_validated` | Запись проверяется только на sentinel UID: реальная запись требует установленного аддона и `card.update`. |
+| `github-addon.*.list` | `GET /cards/{card_id}/addons-data/{addon_uid}` | `live_not_validated` | Чтение shared-ключей `attachedPulls`, `attachedBranches`, `attachedCommits`, `attachedIssues`. При пустом ответе на выведенный UID дополнительно читаются `GET /cards/{id}` и `GET /spaces/{id}/addons`, чтобы взять реально зарегистрированный UID. |
+| `github-addon.*.attach`, `github-addon.*.detach` | `PATCH /cards/{card_id}/addons-data/{addon_uid}` | `live_not_validated` | Live suite покрывает только `--dry-run`: реальная запись изменила бы данные аддона на живой карточке. |
+
+## Policy exclusions
+
+| Command | Status | Notes |
+|---------|--------|-------|
+| `api-keys.create` | `policy_excluded` | Создание ключей не тестируется live, потому что clean teardown потребовал бы testing delete. |
+| `api-keys.delete` | `policy_excluded` | Явно исключено по пользовательской политике. |

kaiten_cli-0.3.3/ARCHITECTURE.md

@@ -0,0 +1,183 @@
+# Architecture
+
+`kaiten-cli` is organized around one core idea: the tool surface is declared once, in the registry, and every other layer consumes that metadata.
+
+## System Map
+
+Runtime flow:
+
+`registry -> discovery/app -> input merge -> executor -> client -> transforms/output`
+
+For high-cardinality reads there is one more path:
+
+`registry -> discovery/app -> input merge -> executor -> execution context -> runtime behavior -> bulk worker pool -> per-worker clients`
+
+For repeated report and analytics workflows there is also a local-first path:
+
+`registry -> discovery/app -> input merge -> executor -> local snapshot store -> local query/metrics`
+
+Successful interactive commands have an independent post-command path:
+
+`app -> install metadata -> cached Git tag check -> optional installer confirmation`
+
+Main layers:
+
+- `src/kaiten_cli/registry/`
+  Source of truth for the command catalog. Each tool is declared as a `ToolSpec` with canonical name, MCP alias, schema, examples, request metadata, response policy, and optional runtime behavior.
+- `src/kaiten_cli/runtime/`
+  Execution layer. Builds requests, resolves profiles and cache settings, applies read-only mutation policies, runs HTTP calls, handles synthetic and aggregated reads, persists local snapshots, and serves local-only query commands.
+- `src/kaiten_cli/runtime/support/`
+  Domain-specific helpers used by runtime behaviors for documents, projects, tree aggregation, cards bulk pagination, relation/comment batch reads, activity pagination, and space topology aggregation.
+- top-level `src/kaiten_cli/`
+  Stable package surface and shared core: `app.py`, `discovery.py`, `profiles.py`, `models.py`, `errors.py`, entrypoints.
+
+## Registry vs Runtime
+
+This repo does not have two different sets of tools.
+
+- `registry` defines the tools.
+- `runtime` executes the tools.
+
+If a command looks “special”, it is still a registry-defined tool. The only difference is that its `ToolSpec.runtime_behavior` points to a request shaper or custom executor in `src/kaiten_cli/runtime/behaviors.py`.
+
+That means:
+
+- `cards.list` is a registry tool with direct HTTP execution
+- `projects.cards.list` is a registry tool with synthetic execution
+- `cards.list-all` is a registry tool with aggregated execution
+
+The command catalog stays centralized even when runtime semantics differ.
+
+## Output Locale
+
+`i18n.py` holds an invocation-scoped `ContextVar`. The root Click group and public
+entrypoint resolve `--locale ru|en` before help and parser errors; the flag wins
+over `KAITEN_CLI_LOCALE`, then `en`. OS locale and profiles do not participate.
+The caller (agent) chooses the language from the conversation.
+
+English source templates are stable message IDs. `locales/ru.json` is an offline
+catalog shipped in the wheel. Runtime prose opts in with `tr`; discovery copies
+only explicitly defined prose fields, including JSON Schema descriptions.
+API payloads, user values, enum values, command identifiers and trace fields are
+never passed through recursive translation. Raw API/OS/library diagnostics retain
+their source language inside a localized CLI message.
+
+`localized_click.py` binds Click's module-local gettext callbacks once to the
+context-aware dispatcher. Help is rendered from command copies; Click's cached
+help option remains English. Context tokens reset on success and failure, and
+async workers inherit the invocation locale. Dependency updates must pass the
+catalog check and sequential/concurrent locale regression tests.
+
+Registry metadata stays canonical English for stable generated documentation.
+Search uses both language descriptions plus private `search_terms`; changing the
+output locale cannot change ranking. Agent instructions and gateway prompts
+require an explicit locale per invocation. This is a language contract, not a
+claim of improved model accuracy; that requires separate evaluation.
+
+Run `python scripts/check_locales.py` for coverage, formatting placeholders and
+command-flag preservation. Unknown messages fall back to English at runtime;
+the check and tests fail for missing known translations. See
+[localization verification](docs/LOCALIZATION_VERIFICATION.md) for invariants and evidence.
+
+## Execution Context and Cache
+
+Each CLI invocation builds one execution context for the selected profile.
+
+- request-scoped cache is always enabled for safe GET reads
+- identical in-flight GETs are deduplicated inside the same execution context
+- persistent disk cache defaults to `--cache-mode auto` for cacheable safe reads
+- persistent cache scope includes a one-way credential fingerprint, so different users of the same tenant/profile cannot reuse each other's cached responses
+- `auto` uses adaptive TTLs: small fresh reads stay short, while heavy batch/aggregated reads, closed historical windows, and dense same-family entity loops are retained longer
+- worker clients share one execution-scoped rate limiter instead of multiplying the request budget by worker count
+- every attempted remote mutation clears persistent cache for the current credential scope, including ambiguous failures, so verification reads cannot reuse pre-mutation data
+- incompatible or corrupt local sqlite cache files are treated as disposable state and recreated automatically
+- credential config, HTTP cache, snapshots, and trace files are stored with user-only file permissions (`0600`); application-owned parent directories are `0700`, while existing user-selected trace/config parent modes are preserved
+- JSON success/error envelopes include runtime `stats` with duration, HTTP/API wait, cache counters, and grouped method/path-family aggregates
+- optional JSONL trace output can be appended through `--trace-file` or `KAITEN_TRACE_FILE`
+
+This keeps freshness controls explicit (`refresh` / `off`) while reducing repeated entity, page, and card-scoped reads in synthetic, aggregated, worker-pooled, and external-script paths.
+
+## Post-command Update Check
+
+`update_check.py` is outside the Kaiten execution/runtime path. It recognizes only
+remote Git installations described by standard Python `direct_url.json` metadata,
+detects the owning `pipx`, `uv tool`, or pip environment, and compares the
+installed version with stable `vX.Y.Z` tags from the same remote.
+
+The check runs only after a successful interactive command, is cached for 24
+hours, and is disabled for JSON/non-TTY/help/version/completion calls. Network and
+metadata failures are fail-open. The cache stores a source hash rather than the
+Git URL, and installer commands are passed directly to `subprocess` without a
+shell. A confirmed update is a separate local side effect and does not alter the
+already completed Kaiten command.
+
+## Mutation Safety
+
+- Transport retries are limited to safe HTTP methods. An ambiguous timeout, connection failure, HTTP 5xx, or malformed successful response for a remote mutation is returned without retry and explicitly tells the caller to verify remote state.
+- Global `--read-only` and `KAITEN_CLI_READ_ONLY=1` block registry tools that mutate Kaiten through `RuntimeBehavior.enforce_mutation_guard`.
+- Local snapshot lifecycle commands opt out of that guard because they only write derived local sqlite state; their Kaiten API calls remain reads.
+- Three POST-backed chart retrieval commands opt out because they only submit analytics filters; chart build commands remain guarded because they create transient compute jobs.
+- Discovery exposes `read_only_allowed` separately from HTTP-method-derived `mutation`.
+- The agent gateway passes remote and local-storage read-only environment policies, disables ambient Codex user config/rules, applies request limits, and requires bearer authentication for non-loopback binds. Existing snapshots use a SQLite read-only connection inside that sandbox; snapshot lifecycle writes are rejected. Because the child still has shell access and Kaiten credentials, this is a cooperative safety layer rather than a hard authorization boundary; untrusted/non-loopback deployments require server-side credential restrictions and an external TLS/connection-limiting proxy.
+
+The trace layer records command-level facts such as duration, real HTTP request count, API wait time, retry/cache counters, grouped path families, and bulk metadata. It exists because outer Codex/session logs do not reliably see internal Kaiten subprocess calls from higher-level scripts.
+
+## Local-first Snapshot Layer
+
+`snapshot.*` and `query.*` are still registry-defined tools. They differ from transport tools because their `custom` executor path persists and reads local sqlite state in `runtime/snapshots.py`.
+
+Current intent:
+
+- `snapshot.build` and `snapshot.refresh`
+  Fetch a bounded working set from Kaiten once, then persist topology, cards, activity, history, time logs, relations, comments, and derived fields locally.
+- `query.cards`
+  Run local filtering and candidate reduction without new API calls. The default local view is `summary`; `detail` and `evidence` are explicit escalations.
+- `query.metrics`
+  Compute local metrics over the stored working set instead of rebuilding the same population/history path on every run.
+
+This shifts repeated headless analytics from `API-per-question` to `snapshot-per-window`.
+The path stays explicit: normal transport commands are not silently rewritten to snapshot-backed reads.
+The snapshot sqlite store is also treated as disposable derived state: incompatible or corrupt local files are dropped and recreated instead of migrated in place.
+
+## Execution Modes
+
+- `direct_http`
+  One request derived directly from `OperationSpec`.
+- `synthetic`
+  Runtime may use fallback logic or reshape API responses to preserve a stable tool contract.
+- `aggregated`
+  Runtime performs bounded multi-request collection and returns one logical result.
+- `custom`
+  Runtime uses a dedicated executor because the API contract does not map cleanly to a simple request/response flow.
+
+`custom` now covers two families:
+
+- transport-adjacent orchestration such as batch/history/topology paths
+- local-first snapshot/query paths that do not map to one upstream endpoint
+
+Bulk reads are still registry-defined tools. The difference is that some aggregated tools now use a dedicated bulk execution path instead of repeated one-shot CLI invocations. Current examples include `cards.list-all`, `cards.batch-get`, `time-logs.batch-list`, `space-activity-all.get`, `space-topology.get`, `card-children.batch-list`, `comments.batch-list`, and `card-location-history.batch-get`.
+
+## Docs Map
+
+Primary docs:
+
+- [README.md](README.md) for install, usage, config, and operator guidance
+- [COMMAND_REFERENCE.md](COMMAND_REFERENCE.md) for the full generated command catalog
+- [AGENTS.md](AGENTS.md) for agent-specific usage and safety shortcuts
+- `skills/` for repo-local LLM workflows in `SKILL.md` format
+- [LIVE_VALIDATION.md](LIVE_VALIDATION.md) for live test process
+- [API_BEHAVIOR_MATRIX.md](API_BEHAVIOR_MATRIX.md) for documented sandbox contracts
+- `ARCHITECTURE.md` for the system map
+
+`ARCHITECTURE_REVIEW.md` is intentionally kept out of tracked docs. It is an audit artifact, not the maintained architecture reference.
+
+## Known Tradeoffs
+
+- The manual registry is easy to inspect, but large and maintenance-heavy.
+- Runtime behaviors are now explicit, but still centralized in one behavior module.
+- Request-scoped cache is built in, but persistent cache deliberately stays conservative and opt-in.
+- Snapshot refresh is still rebuild-oriented in v1; there is no incremental sync yet.
+- Local metric semantics are still generic; tenant-specific flow profiles are intentionally deferred.
+- The default local card path is intentionally summary-first to reduce token and payload cost before LLM involvement.
+- The CLI favors boundedness and predictability over maximum raw throughput, so bulk execution stays conservative by default.
+- Live validation is explicit and well-documented, but sandbox contracts remain inherently unstable.

kaiten_cli-0.3.3/LIVE_VALIDATION.md

@@ -0,0 +1,186 @@
+# Live Validation
+
+Этот документ описывает, как устроена полная live-проверка `kaiten-cli` на реальных credentials с явным per-run gate.
+
+Текущая матрица контрактов в основном собрана на sandbox tenant, но сам live harness не привязывается к домену, имени профиля или profile metadata автоматически.
+
+## Статус проверки
+
+- На `2026-07-09` в рамках текущего аудита live suite **не запускался**.
+- Текущий contract baseline — `kaiten-cli v0.1.23`; tenant class ранее зафиксированных контрактов — Kaiten sandbox test tenant.
+- Дата и commit последней полной live campaign не подтверждены в репозитории и остаются `TBD`.
+- До нового запуска [API_BEHAVIOR_MATRIX.md](API_BEHAVIOR_MATRIX.md) описывает ранее наблюдавшиеся и закодированные контракты, а не свежую проверку production или sandbox API.
+
+После каждой полной campaign нужно записать в оба документа дату, commit SHA, версию CLI и tenant class, не сохраняя credentials, tenant URL и идентификаторы временных сущностей.
+
+## Ограничения пространства
+
+Группа `restrictions` — недокументированное расширение по серверному коду, со статусом
+`live_not_validated`. На 2026-10-06 live-сценарий **не запускался**.
+Отдельный opt-in сценарий создаёт два временных пространства, создаёт правило,
+проверяет список и просмотр, отключение и включение с readback, копирование, удаление
+и отсутствие удалённых правил в списках. Cleanup зарегистрирован сразу после создания
+каждого правила и повторно проверяет его отсутствие. Существующие правила не используются.
+Сценарий также включён в полную последовательную campaign.
+
+После зелёных локальных проверок и выбора тестовых credentials:
+
+```bash
+KAITEN_LIVE=1 python -m pytest -q -m live tests/live/test_restrictions_live.py
+```
+
+Перед мутациями выполняется `profile probe` в режиме `--read-only`.
+Отдельный сценарий записывает trace в временный каталог pytest. Успешные offline-тесты
+не подтверждают доступность маршрутов на действующем сервере.
+
+## Базовые правила
+
+- live suite запускается только после зелёного локального `pytest`
+- live suite запускается только при явном `KAITEN_LIVE=1|true`
+- live suite никогда не идёт в default test run
+- выполнение строго последовательное, без параллельных API-вызовов
+- между вызовами остаются паузы для соблюдения low-load discipline
+- все mutation-сценарии обязаны иметь проверяемый teardown
+- если cleanup падает, live test падает
+
+## Outcome classes
+
+Для live verification используются следующие статусы:
+
+- `live_passed`
+  Команда реально проходит по success-path на текущем live tenant.
+- `live_passed_with_runtime_fix`
+  Команда проходит на текущем live tenant, но для этого понадобился runtime shaping в CLI.
+- `live_passed_as_expected_error`
+  Живой API стабильно или условно возвращает ожидаемый `4xx`, и этот контракт проверяется как корректный.
+- `synthetic_read`
+  Прямой endpoint нестабилен или unsupported, но CLI честно собирает эквивалентный read из другого безопасного endpoint.
+- `policy_excluded`
+  Команда сознательно исключена из live validation по политике безопасности.
+- `live_not_validated`
+  Команда добавлена после последней полной campaign. В live suite сценарий для неё есть, но
+  реального прогона, подтверждающего контракт, ещё не было.
+
+## Что считается успешной live-валидацией
+
+Команда считается live-covered только если выполнено одно из условий:
+
+1. success-path реально отработал и postcondition подтверждён;
+2. documented expected-error-path реально отработал и статус соответствует контракту;
+3. synthetic fallback реально отработал и вернул ожидаемые данные;
+4. команда помечена `policy_excluded`.
+
+Статус `live_not_validated` покрытием не считается: он честно фиксирует, что сценарий в
+harness уже написан, но прогона ещё не было.
+
+Скрытых “ну это вроде нормально” сценариев быть не должно.
+
+## Как устроен live harness
+
+Файлы:
+
+- [tests/live/conftest.py](tests/live/conftest.py)
+- [tests/live/test_sandbox_live_full.py](tests/live/test_sandbox_live_full.py)
+
+Harness делает следующее:
+
+- создаёт run-scoped имена временных сущностей
+- ведёт cleanup stack в обратном порядке
+- использует только canonical commands для live coverage
+- считает покрытие по всему registry surface, кроме policy exclusions
+- различает normal success path и expected-error path
+
+## Policy exclusions
+
+Сейчас live validation не включает:
+
+- `api-keys.create`
+- `api-keys.delete`
+
+Причина: clean teardown невозможен без тестирования удаления ключей, а удаление ключей пользователь запретил проверять live.
+
+## Synthetic contracts
+
+Явные synthetic reads:
+
+- `projects.cards.list`
+  - сначала CLI пробует `GET /projects/{project_id}/cards`
+  - если live API отвечает `405`, CLI делает `GET /projects/{project_id}?with_cards_data=true`
+  - затем извлекает embedded cards list из project payload
+- `checklists.list`
+  - direct `GET /cards/{card_id}/checklists` возвращает `405`
+  - CLI делает `GET /cards/{card_id}` и извлекает embedded `checklists`
+- `checklist-items.list`
+  - direct `GET /cards/{card_id}/checklists/{checklist_id}/items` возвращает `405`
+  - CLI делает `GET /cards/{card_id}` и извлекает `items` из matching checklist
+
+## Expected-error contracts
+
+Некоторые команды считаются live-correct именно через documented `4xx`:
+
+- `removed-boards.list` -> `405`
+- `removed-cards.list` -> `405`
+- `card-subscribers.list` -> `405`
+- `column-subscribers.list` -> `405`
+
+Есть и условные tenant'ы, где live API может разрешить success-path или вернуть ожидаемый `4xx`:
+
+- `automations.copy`
+- `sprints.*`
+- `workflows.*`
+- `service-desk.requests.*`
+- `service-desk.sla-rules.*`
+- `user-timers.*`
+- `compute-jobs.cancel`
+
+Отдельно зафиксирован automation contract:
+
+- `automations.create` и `automations.update` проходят на success-path при e2e-shaped payload:
+  - `trigger.type = card_created`
+  - `action.type = add_assignee`
+  - `action.created = <iso datetime>`
+  - `action.data.variant = specific`
+  - `action.data.userId = <current_user_id>`
+- `automations.get` может возвращать `405` даже после успешного create
+- `automations.copy` остаётся conditional sandbox contract
+
+Также зафиксирован ещё один стабильный expected-error:
+
+- `service-desk.users.update` -> `400`, если текущий live-пользователь не является Service Desk user
+
+И один смешанный Service Desk contract:
+
+- `service-desk.users.set-temp-password` может либо успешно отработать, либо вернуть `403/404/405`
+- `service-desk.organization-users.update` может либо успешно отработать, либо вернуть `400/403/404/405` даже после успешного `organization-users.add`
+
+Точные статусы и примечания см. в [API_BEHAVIOR_MATRIX.md](API_BEHAVIOR_MATRIX.md).
+
+## Запуск
+
+```bash
+KAITEN_LIVE=true KAITEN_DOMAIN=<company-subdomain-or-url> KAITEN_TOKEN=... \
+  .venv/bin/pytest -m live -o addopts='--disable-socket --allow-unix-socket' \
+  tests/live/test_sandbox_live_full.py
+```
+
+Если credentials уже сохранены в обычном active profile, достаточно выставить только `KAITEN_LIVE=1|true`.
+
+## Что делать при новом blocker-е
+
+1. Сначала определить, это runtime bug, live API limitation или synthetic-fallback candidate.
+2. Если это runtime bug — добавить/обновить offline test и чинить CLI.
+3. Если это корректный expected error — зафиксировать его в `API_BEHAVIOR_MATRIX.md` и, если меняется объяснение системы, в `ARCHITECTURE.md`.
+4. Если это честный synthetic candidate — сначала добавить failing offline test, потом реализовать fallback.
+
+## Изменения чтения чеклистов
+
+`checklists.list` читает `GET /cards/{card_id}` и извлекает `checklists`.
+Collection GET возвращал 405 на тестовом инстансе; такое же поведение на боевом
+инстансе описано автором [kaiten-mcp PR #4](https://github.com/ViktorOgnev/kaiten-mcp/pull/4).
+Это свидетельство автора PR, а не новая live-проверка CLI.
+
+`checklist-items.list` теперь читает `GET /cards/{card_id}/checklists/{checklist_id}`
+и извлекает `items`. Пустой чеклист возвращает `[]`, а ошибки API, включая 404,
+сохраняются. Некорректный ответ без массива `items` считается ошибкой транспорта.
+Оба обхода применяются ко всем профилям; тестовый инстанс — место наблюдения,
+а не особый режим CLI. Изменение проверено офлайн через HTTP-моки.