Compare commits
1 Commits
f4b055e76a
...
feature/OR
| Author | SHA1 | Date | |
|---|---|---|---|
|
e2c4881b21 |
253
.env.example
253
.env.example
@@ -12,47 +12,6 @@ ORCH_GITEA_WEBHOOK_SECRET=
|
||||
ORCH_CLAUDE_BIN=/usr/bin/claude
|
||||
ORCH_REPOS_DIR=/home/slin/repos
|
||||
ORCH_DB_PATH=/app/data/orchestrator.db
|
||||
|
||||
# ── Agent model / effort / fallback (ORCH-41, validation ORCH-74) ─────────────
|
||||
# Per-agent LLM model + reasoning effort, resolved by launcher.resolve_agent_*.
|
||||
# Resolution priority (per agent): project-override (projects_json agent_models/
|
||||
# agent_efforts) > ORCH_AGENT_MODEL_<AGENT> / ORCH_AGENT_EFFORT_<AGENT> >
|
||||
# ORCH_AGENT_MODEL_DEFAULT / ORCH_AGENT_EFFORT_DEFAULT > CLI default (no flag).
|
||||
# The frontmatter `model:` in .openclaw/agents/*.md is DESCRIPTIVE only and is NOT
|
||||
# read — config below is the single source of truth for the model (ORCH-74 G1).
|
||||
#
|
||||
# ORCH-74 (G2): a resolved MODEL name is validated (^claude-…$ format check) before
|
||||
# it reaches --model. A structurally invalid name (typo, gpt-4, empty) is logged and
|
||||
# the next valid level is used (in the limit: no --model flag). Forward-compatible:
|
||||
# a future claude-* version passes without editing any allowlist. EFFORT is validated
|
||||
# against low|medium|high|xhigh|max (ORCH-41); an invalid effort is dropped.
|
||||
#
|
||||
# All 6 agents resolve to claude-opus-4-8 (model-routing G3 NOT enabled). Leave the
|
||||
# per-agent overrides empty to use the default. Do NOT hardcode the model version
|
||||
# anywhere except ORCH_AGENT_MODEL_DEFAULT.
|
||||
ORCH_AGENT_MODEL_DEFAULT=claude-opus-4-8
|
||||
ORCH_AGENT_MODEL_ANALYST=
|
||||
ORCH_AGENT_MODEL_ARCHITECT=
|
||||
ORCH_AGENT_MODEL_DEVELOPER=
|
||||
ORCH_AGENT_MODEL_REVIEWER=
|
||||
ORCH_AGENT_MODEL_TESTER=
|
||||
ORCH_AGENT_MODEL_DEPLOYER=
|
||||
# Effort split (ORCH-081/ORCH-52h): thinking agents (analyst/architect/reviewer)
|
||||
# -> high; developer -> xhigh (coding/agentic role, Opus 4.8 canon); mechanical
|
||||
# agents (tester/deployer) -> medium. NB: an empty ORCH_AGENT_EFFORT_*= no longer
|
||||
# zeroes the effort — the launcher falls back to a per-role floor (= the config.py
|
||||
# class-default) so each role still runs at its canonical level (ORCH-081).
|
||||
ORCH_AGENT_EFFORT_DEFAULT=high
|
||||
ORCH_AGENT_EFFORT_ANALYST=high
|
||||
ORCH_AGENT_EFFORT_ARCHITECT=high
|
||||
ORCH_AGENT_EFFORT_DEVELOPER=xhigh
|
||||
ORCH_AGENT_EFFORT_REVIEWER=high
|
||||
ORCH_AGENT_EFFORT_TESTER=medium
|
||||
ORCH_AGENT_EFFORT_DEPLOYER=medium
|
||||
# Optional --fallback-model used when the primary is overloaded. Empty -> no flag
|
||||
# (G4 NOT enabled, ADR-001 ORCH-74: determinism — all agents stay on opus-4-8). A
|
||||
# non-empty value is validated by the SAME predicate as the model; a typo is dropped.
|
||||
ORCH_AGENT_FALLBACK_MODEL=
|
||||
# ORCH-042/ORCH-067: live-tracker mode. bump (DEFAULT since ORCH-067) -> on every
|
||||
# update the old card is deleted and a fresh one is sent silently to the BOTTOM of
|
||||
# the chat (deleteMessage + sendMessage + repoint), so the current status is always
|
||||
@@ -107,61 +66,6 @@ ORCH_PREMERGE_REBASE_ALWAYS=true
|
||||
# cache them into job_deps (the scheduler then reads only the DB).
|
||||
ORCH_TASK_DEPS_ENABLED=true
|
||||
ORCH_TASK_DEPS_SOURCE=db
|
||||
# ORCH-088 (Stage 1, serial e2e): per-repo serial gate. A NEW task's analyst-job does
|
||||
# NOT enter analysis (no branch cut, no analyst) while the same repo has an EARLIER
|
||||
# unfinished task (FIFO, tasks.id < the job's task) OR the repo is frozen. The branch
|
||||
# cut is DEFERRED from start_pipeline to the analyst-job claim so its base is a fresh
|
||||
# origin/main already containing the predecessor (anti-stale-base). Gate lives in
|
||||
# claim_next_job (offline hot-path, fail-OPEN on error); freeze (FR-5) is a durable
|
||||
# repo_freeze row set on post-deploy DEGRADED, cleared manually via
|
||||
# POST /serial-gate/unfreeze?repo=<repo>. Leaf src/serial_gate.py (never-raise).
|
||||
# SERIAL_GATE_ENABLED=false -> claim AND start_pipeline are 1:1 as before ORCH-088.
|
||||
# SERIAL_GATE_REPOS (CSV) -> scope; EMPTY = ALL repos (not self-hosting-only).
|
||||
# SERIAL_GATE_FREEZE_ENABLED=false -> the rollback-freeze layer is off (not set/read).
|
||||
ORCH_SERIAL_GATE_ENABLED=true
|
||||
ORCH_SERIAL_GATE_REPOS=
|
||||
ORCH_SERIAL_GATE_FREEZE_ENABLED=true
|
||||
# ORCH-090: STOP-status task cancellation (stop active agent + full progress reset)
|
||||
# and the relaunch-hole close. A dedicated Plane "STOP" status (logical key `stop`,
|
||||
# fail-closed: absent from _DEFAULT_STATES, so a board without the status -> no-op)
|
||||
# routes to a cancel handler that drives the task to the system-terminal state
|
||||
# `cancelled` (stop agent via the graceful SIGTERM cascade, cancel all jobs, remove
|
||||
# worktree + delete the remote feature branch [never main / never force-push],
|
||||
# tombstone the natural keys for a clean re-create via "To Analyse"; docs preserved).
|
||||
# STOP during a critical merge/deploy window is DEFERRED until the irreversible step
|
||||
# finishes honestly. The relaunch-hole gate restricts the "To Analyse" agent relaunch
|
||||
# to the `analysis` stage (the sole Needs-Input owner). Additive, never-raise.
|
||||
# Infra precondition: create a "STOP" status with the `cancelled` group on the ORCH
|
||||
# board (07-infra-requirements.md). Leaf src/cancel.py.
|
||||
# STOP_STATUS_ENABLED=false -> STOP handling AND the relaunch-hole gate are inert
|
||||
# (behaviour strictly as before ORCH-090).
|
||||
# STOP_STATUS_REPOS (CSV) -> scope; EMPTY = ALL repos (cancellation is meaningful
|
||||
# for enduro too).
|
||||
ORCH_STOP_STATUS_ENABLED=true
|
||||
ORCH_STOP_STATUS_REPOS=
|
||||
# ORCH-019: bug-fast-track — a cheaper/shorter pipeline route for bug-fix tasks.
|
||||
# A task carrying the Plane `Bug` label skips the whole `architecture` stage; EVERY
|
||||
# Quality Gate / sub-gate runs UNCHANGED (route is a scheduler property, not a gate).
|
||||
# Additive, never-raise, fail-safe -> full cycle. Infra precondition: create a `Bug`
|
||||
# label on the ORCH board (its absence = full cycle, fail-safe). Leaf src/bug_fast_track.py.
|
||||
# BUG_FAST_TRACK_ENABLED=false -> start_pipeline AND advance_stage are 1:1 as before
|
||||
# ORCH-019 (zero regression).
|
||||
# BUG_FAST_TRACK_LABEL -> Plane label that activates the track (default `Bug`).
|
||||
# BUG_FAST_TRACK_REPOS (CSV) -> scope; EMPTY = self-hosting only (orchestrator).
|
||||
ORCH_BUG_FAST_TRACK_ENABLED=true
|
||||
ORCH_BUG_FAST_TRACK_LABEL=Bug
|
||||
ORCH_BUG_FAST_TRACK_REPOS=
|
||||
# ORCH-094: terminal-window-aware guard for the three deploy-phase Plane status
|
||||
# setters (set_issue_awaiting_deploy / set_issue_deploying / set_issue_monitoring).
|
||||
# A DB stage=done task converges to Done idempotently instead of flapping
|
||||
# Awaiting <-> Monitoring, EXCEPT the legitimate post-deploy Monitoring while the
|
||||
# window is active (ARMED & not DONE). Leaf src/deploy_status_guard.py, never-raise;
|
||||
# STAGE_TRANSITIONS / QG_CHECKS / machine-verdict keys untouched (no DB migration).
|
||||
# DEPLOY_STATUS_GUARD_ENABLED=false -> setters are terminal-blind (1:1 pre-ORCH-094).
|
||||
# DEPLOY_STATUS_GUARD_REPOS (CSV) -> scope; EMPTY = self-hosting only (orchestrator),
|
||||
# the only repo where deploy-phase statuses are set.
|
||||
ORCH_DEPLOY_STATUS_GUARD_ENABLED=true
|
||||
ORCH_DEPLOY_STATUS_GUARD_REPOS=
|
||||
# ORCH-071/073: merge-verify under-gate on the `deploy -> done` edge (врезка in
|
||||
# advance_stage, NOT a new STAGE_TRANSITIONS edge / registered QG). A deterministic
|
||||
# merge-actor merges the feature code-PR via the Gitea PR-merge API (never push/
|
||||
@@ -178,33 +82,11 @@ ORCH_DEPLOY_STATUS_GUARD_REPOS=
|
||||
# REGRESSION_GUARD_ENABLED -> kill-switch for the ORCH-073 main-integrity regression
|
||||
# guard (false -> SHA-in-main alone gates done); reuses the
|
||||
# merge-verify scope, so non-self repos are a no-op.
|
||||
# MERGE_VERIFY_AUTOCREATE_PR_ENABLED -> ORCH-082: guarantee an open code-PR
|
||||
# (head==branch, base==main) via merge_gate.ensure_open_pr
|
||||
# BEFORE the deterministic merge_pr (fixes the false HOLD
|
||||
# "no open PR"). false -> exactly pre-ORCH-082 behaviour.
|
||||
# Reuses the merge-verify scope; non-self repos -> no-op.
|
||||
ORCH_MERGE_VERIFY_ENABLED=true
|
||||
ORCH_MERGE_VERIFY_REPOS=
|
||||
ORCH_MERGE_PR_TIMEOUT_S=60
|
||||
ORCH_MERGE_VERIFY_TIMEOUT_S=60
|
||||
ORCH_REGRESSION_GUARD_ENABLED=true
|
||||
ORCH_MERGE_VERIFY_AUTOCREATE_PR_ENABLED=true
|
||||
# ORCH-093: deterministic merge-actor retry of TRANSIENT Gitea merge errors. merge_pr
|
||||
# wraps ONLY the mutating POST /pulls/{n}/merge in a bounded exponential-backoff
|
||||
# retry-loop on transient outcomes (405 "try again later" / 408 / 5xx / network /
|
||||
# timeout, and 409|422 while the PR is still mergeable); terminal outcomes
|
||||
# (403/404/real conflict) -> fast honest False (the ORCH-071/081 HOLD backstop is
|
||||
# unchanged). Fixes the ORCH-063 false HOLD + manual re-merge. The already-in-main
|
||||
# guard (no commits beyond origin/main -> no garbage PR) is always-on under
|
||||
# MERGE_VERIFY_AUTOCREATE_PR_ENABLED (no separate flag).
|
||||
# MERGE_RETRY_ENABLED -> kill-switch; false -> exactly one POST (one-shot, prior behaviour).
|
||||
# MERGE_RETRY_MAX_ATTEMPTS -> max POST attempts on a transient outcome.
|
||||
# MERGE_RETRY_BACKOFF_BASE_S -> exponential backoff base seconds (sleep = base*2^(i-1)).
|
||||
# MERGE_RETRY_BACKOFF_MAX_S -> per-sleep backoff ceiling seconds (bounds total wait).
|
||||
ORCH_MERGE_RETRY_ENABLED=true
|
||||
ORCH_MERGE_RETRY_MAX_ATTEMPTS=3
|
||||
ORCH_MERGE_RETRY_BACKOFF_BASE_S=2
|
||||
ORCH_MERGE_RETRY_BACKOFF_MAX_S=5
|
||||
# ORCH-036: executable self-deploy of the `deploy` stage. For the self-hosting repo
|
||||
# (orchestrator) the stage REALLY restarts prod (8500) via a detached host hook;
|
||||
# deploy_status: SUCCESS means proven health-ok, not an LLM declaration. Three
|
||||
@@ -324,45 +206,6 @@ ORCH_REAPER_MAX_RUNNING_S=3600
|
||||
ORCH_REAPER_FINALIZE_GRACE_S=300
|
||||
ORCH_LEASE_RECLAIM_ENABLED=true
|
||||
|
||||
# ORCH-063: disk-watchdog — background heartbeat that measures HOST-FS fill via the
|
||||
# mounted bind-paths (/repos, /app/data) with shutil.disk_usage (NOT the container
|
||||
# overlay /) and Telegram-alerts the operator at >= threshold. On 07.06.2026 the
|
||||
# mva154 host disk silently hit 100% and stalled the WHOLE self-hosting pipeline;
|
||||
# this is the missing proactive signal. Daemon thread modelled on reconciler/reaper
|
||||
# (start/stop in main.lifespan, /queue snapshot, never-raise). Anti-spam state is
|
||||
# in-memory (no DB migration); the watchdog only READS fill and SENDS Telegram — it
|
||||
# never touches the disk/container or restarts prod (self-hosting safety).
|
||||
# DISK_MONITOR_ENABLED -> kill-switch; false -> the daemon does not start (1:1 as before).
|
||||
# DISK_MONITOR_INTERVAL_S -> heartbeat measurement period, seconds (order of minutes).
|
||||
# DISK_MONITOR_THRESHOLD_PCT -> fill % that triggers the alert (Owner-fixed 85; valid 1..100).
|
||||
# DISK_MONITOR_REALERT_S -> cooldown between repeat alerts while above threshold (~6h).
|
||||
# DISK_MONITOR_PATHS -> CSV of monitored HOST bind-paths; empty -> /repos,/app/data.
|
||||
ORCH_DISK_MONITOR_ENABLED=true
|
||||
ORCH_DISK_MONITOR_INTERVAL_S=300
|
||||
ORCH_DISK_MONITOR_THRESHOLD_PCT=85
|
||||
ORCH_DISK_MONITOR_REALERT_S=21600
|
||||
ORCH_DISK_MONITOR_PATHS=/repos,/app/data
|
||||
|
||||
# ORCH-062: build-cache-pruner — the "second half" of the disk-watchdog
|
||||
# (watchdog SIGNALS, pruner CLEANS). A daemon thread modelled on disk_watchdog
|
||||
# that periodically runs STRICTLY `docker builder prune -f --filter until=<until>`
|
||||
# on the HOST over ssh (BuildKit GC). Touches ONLY the build cache: never
|
||||
# images/containers of running services, never restarts the docker daemon or the
|
||||
# prod container (self-hosting safety). State is in-memory (no DB migration). No
|
||||
# ssh host configured -> the tick is a no-op. See docs/operations/INFRA.md.
|
||||
# BUILD_CACHE_PRUNE_ENABLED -> kill-switch; false -> the daemon does not start (1:1 as before).
|
||||
# BUILD_CACHE_PRUNE_INTERVAL_S -> tick period, seconds (order of hours; default ~6h). >0, else default.
|
||||
# BUILD_CACHE_PRUNE_UNTIL -> retention age for the warm cache (`--filter until=`); ^\d+[smhdw]?$, else 24h.
|
||||
# BUILD_CACHE_PRUNE_ALL -> add `-a` (ALWAYS paired with until); default false.
|
||||
# BUILD_CACHE_PRUNE_TIMEOUT_S -> bound on the ssh command, seconds. >0, else default.
|
||||
# BUILD_CACHE_PRUNE_NOTIFY_MIN_GB -> Telegram when reclaimed >= N GB; 0 -> silent.
|
||||
ORCH_BUILD_CACHE_PRUNE_ENABLED=true
|
||||
ORCH_BUILD_CACHE_PRUNE_INTERVAL_S=21600
|
||||
ORCH_BUILD_CACHE_PRUNE_UNTIL=24h
|
||||
ORCH_BUILD_CACHE_PRUNE_ALL=false
|
||||
ORCH_BUILD_CACHE_PRUNE_TIMEOUT_S=120
|
||||
ORCH_BUILD_CACHE_PRUNE_NOTIFY_MIN_GB=0
|
||||
|
||||
# ORCH-022: security-gate (secret-scanning + dependency audit) on the
|
||||
# deploy-staging -> deploy edge, run FIRST among the edge sub-gates. Deterministic
|
||||
# (no LLM): gitleaks (offline secret-scan, pinned Go binary in the image) + pip-audit
|
||||
@@ -384,57 +227,6 @@ ORCH_SECURITY_SCAN_TIMEOUT_S=300
|
||||
ORCH_SECURITY_DEP_AUDIT_FAIL_CLOSED=false
|
||||
ORCH_SECURITY_SECRETS_BLOCK=true
|
||||
|
||||
# ORCH-027: coverage-gate (deterministic test-coverage) on the deploy-staging ->
|
||||
# deploy edge, run AFTER the merge-gate and BEFORE image-freshness. Measures line
|
||||
# coverage of src/ with pytest-cov in the per-branch worktree, compares to an absolute
|
||||
# floor and/or the ratchet baseline of `main`; FAIL -> rollback to development +
|
||||
# developer-retry (cap 3). Verdict in the 18-coverage-report.md frontmatter
|
||||
# (coverage_status:). See ADR-001-coverage-gate.md.
|
||||
# GATE_ENABLED -> global kill-switch; false -> pipeline 1:1 as before ORCH-027.
|
||||
# GATE_REPOS -> CSV of repos where the gate is REAL; empty -> only self-hosting.
|
||||
# MIN_PERCENT -> absolute floor (% line coverage) for policy absolute/both.
|
||||
# POLICY -> absolute | baseline | both (default both).
|
||||
# EPSILON -> noise tolerance (%) at the boundary (anti-flap).
|
||||
# TOOL_FAIL_CLOSED -> strict mode: a coverage-tool error -> FAIL instead of the
|
||||
# default fail-open + warning (anti-loop). Default false.
|
||||
# RUN_TIMEOUT_S -> wall-clock budget for the pytest --cov run.
|
||||
ORCH_COVERAGE_GATE_ENABLED=true
|
||||
ORCH_COVERAGE_GATE_REPOS=
|
||||
ORCH_COVERAGE_MIN_PERCENT=0.0
|
||||
ORCH_COVERAGE_POLICY=both
|
||||
ORCH_COVERAGE_EPSILON=0.5
|
||||
ORCH_COVERAGE_TOOL_FAIL_CLOSED=false
|
||||
ORCH_COVERAGE_RUN_TIMEOUT_S=900
|
||||
|
||||
# ORCH-057 (follow-up ORCH-040): legacy root-owned ownership detect + actionable
|
||||
# worktree error. After the uid migration (user: "1000:1000") legacy root:root files
|
||||
# in /repos broke worktree creation under uid 1000 with a raw "Permission denied".
|
||||
# Three additive, kill-switch-reversible layers: an actionable RuntimeError in
|
||||
# ensure_worktree, a cheap never-raise detect leaf (src/fs_normalize.py) with a
|
||||
# startup WARNING/Telegram + GET /queue fs_ownership block, and an opt-in chown ONLY
|
||||
# when privileged (under uid 1000 a no-op; the real fix is the operator procedure in
|
||||
# docs/operations/INFRA.md «Миграция uid»). No STAGE_TRANSITIONS / QG_CHECKS / schema
|
||||
# change.
|
||||
# ENABLED -> kill-switch; false -> all code inert, behaviour 1:1 as before
|
||||
# ORCH-057 (the actionable error too).
|
||||
# REPOS -> CSV of repos the layer is REAL for; empty -> self-hosting only.
|
||||
# TARGET_UID -> target uid fallback when os.getuid() is unavailable.
|
||||
# NORMALIZE_AUTO -> detect-only (false) | attempt chown when privileged (true).
|
||||
# SCAN_ROOTS -> CSV override of the scan roots (empty -> default roots).
|
||||
# SCAN_CACHE_TTL_S -> TTL of the detect cache (mirrors ORCH_PREFLIGHT_CACHE_TTL).
|
||||
ORCH_FS_NORMALIZE_ENABLED=true
|
||||
ORCH_FS_NORMALIZE_REPOS=
|
||||
ORCH_FS_TARGET_UID=1000
|
||||
ORCH_FS_NORMALIZE_AUTO=false
|
||||
ORCH_FS_SCAN_ROOTS=
|
||||
ORCH_FS_SCAN_CACHE_TTL_S=300
|
||||
|
||||
# ORCH-099 (FND/F1a): operator off-switch for the read-only GET /metrics endpoint
|
||||
# (raw-signal snapshot for the F1b sidecar). Default true -> available out of the
|
||||
# box. false -> /metrics returns a minimal parsable body {"schema_version":1,
|
||||
# "enabled":false} (200, not 404). The endpoint is inert / read-only anyway.
|
||||
ORCH_METRICS_ENABLED=true
|
||||
|
||||
# ORCH-021: post-deploy production monitoring + degradation reaction. After the
|
||||
# terminal deploy->done transition for an applicable repo, a reserved-agent job
|
||||
# `post-deploy-monitor` (no LLM, modelled on deploy-finalizer) probes prod over a
|
||||
@@ -465,48 +257,3 @@ ORCH_POST_DEPLOY_BASE_URL=http://localhost:8500
|
||||
# DB title TEXT is unbounded). Default 200. An invalid/empty value gracefully
|
||||
# degrades to 200 (the process never crashes on startup).
|
||||
ORCH_QG0_TITLE_MAX=200
|
||||
|
||||
# ── ORCH-100 (FND/F1b): sidecar-watchdog (orchestrator-watchdog container) ─────
|
||||
# The monitoring brain runs in a SEPARATE container with its OWN config. These
|
||||
# keys are read by the watchdog package (watchdog/config.py), NOT by the
|
||||
# orchestrator. At runtime they live in `.env.watchdog` (env_file of the
|
||||
# orchestrator-watchdog service); this block is the canon. NO real secrets here.
|
||||
# ENABLED -> kill-switch; false (or not starting the service) -> inert.
|
||||
# INTERVAL_S -> seconds between ticks.
|
||||
# HTTP_TIMEOUT_S -> per-request timeout (metrics / pings / docker / telegram).
|
||||
# COOLDOWN_S -> re-alert throttle for a sustained signal (anti-spam).
|
||||
# METRICS_URL -> orchestrator /metrics (host-network -> 127.0.0.1:8500).
|
||||
# ORCH_DOWN_TICKS-> K consecutive /metrics failures before "орк не отвечает".
|
||||
# MEM_PCT -> host memory used-% threshold.
|
||||
# DISK_CRIT_* -> OPT-IN independent disk CEILING (disk_watchdog/ORCH-063 owns
|
||||
# the 85% alert; this is a higher ceiling on the sidecar's own
|
||||
# channel, OFF by default -> no double disk-alert, AC-5/D6).
|
||||
# DISK_PATHS -> host paths measured for the opt-in ceiling.
|
||||
# AGENT_HUNG_MIN -> runtime minutes before an agent with ~0 CPU is "hung".
|
||||
# AGENT_CPU_FLOOR-> CPU fraction below which a long-running agent counts as hung.
|
||||
# STAGE_STUCK_MIN-> minutes a task may sit in one stage before alerting.
|
||||
# QUEUE_DEPTH -> queued-job depth threshold.
|
||||
# CONTAINERS -> CSV of container names to watch (status != running/healthy).
|
||||
# DOCKER_SOCK -> path to the read-only docker.sock inside the container.
|
||||
# DEPS -> CSV of name=url dependency pings (empty -> no pings).
|
||||
# TG_BOT_TOKEN / TG_CHAT_ID -> the sidecar's OWN Telegram bot/chat (independent
|
||||
# of the orchestrator's; absent -> logs, does not send).
|
||||
WATCHDOG_ENABLED=true
|
||||
WATCHDOG_INTERVAL_S=30
|
||||
WATCHDOG_HTTP_TIMEOUT_S=5
|
||||
WATCHDOG_COOLDOWN_S=1800
|
||||
WATCHDOG_METRICS_URL=http://127.0.0.1:8500/metrics
|
||||
WATCHDOG_ORCH_DOWN_TICKS=3
|
||||
WATCHDOG_MEM_PCT=90
|
||||
WATCHDOG_DISK_CRIT_ENABLED=false
|
||||
WATCHDOG_DISK_CRIT_PCT=97
|
||||
WATCHDOG_DISK_PATHS=/repos,/app/data
|
||||
WATCHDOG_AGENT_HUNG_MIN=20
|
||||
WATCHDOG_AGENT_CPU_FLOOR=0.01
|
||||
WATCHDOG_STAGE_STUCK_MIN=120
|
||||
WATCHDOG_QUEUE_DEPTH=20
|
||||
WATCHDOG_CONTAINERS=orchestrator
|
||||
WATCHDOG_DOCKER_SOCK=/var/run/docker.sock
|
||||
WATCHDOG_DEPS=
|
||||
WATCHDOG_TG_BOT_TOKEN=
|
||||
WATCHDOG_TG_CHAT_ID=
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
name: analyst
|
||||
description: Бизнес-аналитик. Создаёт пакет документов анализа для work item.
|
||||
model: claude-sonnet-4-6
|
||||
tools:
|
||||
- Filesystem (Read везде; Write только docs/work-items/<plane-id>/*)
|
||||
- Bash (git log, grep — только для чтения контекста)
|
||||
@@ -8,128 +9,49 @@ tools:
|
||||
|
||||
# System prompt: Analyst
|
||||
|
||||
<context>
|
||||
Ты — бизнес-аналитик проекта **orchestrator** (мульти-агентный оркестратор разработки:
|
||||
FastAPI + SQLite, конвейер стадий через Quality Gates, агенты Claude CLI). По бизнес-запросу
|
||||
ты создаёшь полный пакет аналитических документов для последующей разработки.
|
||||
Ты — бизнес-аналитик проекта **orchestrator**. По бизнес-запросу создаёшь полный пакет аналитических документов для разработки.
|
||||
|
||||
**Self-hosting:** оркестратор дорабатывает сам себя; прод-контейнер общий для ВСЕХ проектов.
|
||||
## ⚠️ Начало работы
|
||||
**Прочти `CLAUDE.md` и `docs/architecture/README.md` перед любым действием.** Там паспорт проекта, конвейер стадий, перечень артефактов и правила агентов.
|
||||
|
||||
**Перед любым действием прочти:**
|
||||
1. `CLAUDE.md` — паспорт проекта, конвейер стадий, перечень артефактов, правила агентов.
|
||||
2. `docs/architecture/README.md` — компоненты и конвейер.
|
||||
3. `docs/work-items/<plane-id>/00-business-request.md` — входной бизнес-запрос (источник).
|
||||
4. Текущий код в `src/` — чтобы привязать требования к реальным модулям.
|
||||
</context>
|
||||
## КРИТИЧЕСКИ ВАЖНО: Используй Write tool!
|
||||
Ты ОБЯЗАН создавать файлы через Write tool. Не описывай содержимое в ответе — ЗАПИСЫВАЙ каждый артефакт в файл. Оркестратор проверяет наличие файлов на диске.
|
||||
|
||||
<task>
|
||||
Твоя стадия — **analysis**. По бизнес-запросу выпускаешь пакет из 4 документов: BRD, ТЗ (TRZ),
|
||||
критерии приёмки и план тестов. Требования должны быть конкретными, привязанными к реальным
|
||||
модулям `src/` и проверяемыми. Архитектурные решения — НЕ твоя зона (их принимает архитектор).
|
||||
## Что прочесть
|
||||
1. `CLAUDE.md` — паспорт проекта
|
||||
2. `docs/architecture/README.md` — конвейер и компоненты
|
||||
3. `docs/work-items/<plane-id>/00-business-request.md` — входные данные
|
||||
4. Текущий код в `src/` — для понимания контекста
|
||||
|
||||
Стандарт структуры документов — `docs/_standards/PIPELINE_DOCS.md`; копируй скелеты из
|
||||
`docs/_templates/` (`01-brd.md`, `02-trz.md`, `03-acceptance-criteria.md`, `04-test-plan.yaml`).
|
||||
## Deliverables (создать через Write tool в `docs/work-items/<plane-id>/`)
|
||||
|
||||
**Багфикс-трек (ORCH-019).** Если задача помечена меткой Plane `Bug` (укороченный маршрут —
|
||||
пропуск стадии `architecture`), выпускай **облегчённый** пакет, но **всё равно все 4 файла**
|
||||
(гейт `check_analysis_complete` требует `01/02/03/04` — не меняется): `01-brd.md` = короткий
|
||||
bug-report (симптом / шаги воспроизведения / локализация / причина), `02-trz.md` +
|
||||
`03-acceptance-criteria.md` = краткие bug-shaped заглушки, `04-test-plan.yaml` = план
|
||||
**обязательного регресс-теста** (красный до фикса, зелёный после). Экономия — в пропуске целой
|
||||
стадии `architecture` (отдельный прогон архитектора + ADR), не в числе файлов. Если баг оказался
|
||||
**сложным/архитектурным/визуальным** (нужен ADR или макет) — выпусти **полный** analysis-пакет и
|
||||
помечай в bug-report `escalate: full-cycle` (эскалация в полный цикл, ADR-001 D5 ORCH-019); оператор
|
||||
снимает багфикс-трек эндпоинтом `POST /bug-fast-track/escalate`.
|
||||
</task>
|
||||
### Обязательные
|
||||
- `01-brd.md` — Business Requirements Document
|
||||
- `02-trz.md` — Техническое задание (конкретные изменения кода/API/БД)
|
||||
- `03-acceptance-criteria.md` — Критерии приёмки (чёткие условия PASS/FAIL)
|
||||
- `04-test-plan.yaml` — план тестов (unit, integration; pytest)
|
||||
|
||||
<deliverables>
|
||||
Создавай ОБЯЗАТЕЛЬНО через **Write tool** в каталог `docs/work-items/<plane-id>/` (4 файла):
|
||||
|
||||
| Файл | Назначение |
|
||||
|------|------------|
|
||||
| `01-brd.md` | Business Requirements Document |
|
||||
| `02-trz.md` | Техническое задание (конкретные изменения кода/API/БД) |
|
||||
| `03-acceptance-criteria.md` | Критерии приёмки (чёткие условия PASS/FAIL) |
|
||||
| `04-test-plan.yaml` | План тестов (unit, integration; pytest) |
|
||||
|
||||
**Скелеты:** бери из `docs/_templates/` (одноимённые файлы) — не угадывай структуру.
|
||||
**Эталон качества/полноты:** заполненные work item **ORCH-088** и **ORCH-073** —
|
||||
ориентируйся на их детальность и формат.
|
||||
</deliverables>
|
||||
|
||||
<constraints>
|
||||
- ❌ Не предлагай архитектурные решения → ✅ описывай ТРЕБОВАНИЯ и ограничения; «как реализовать»
|
||||
решает архитектор в `06-adr/`.
|
||||
- ❌ Не пиши код → ✅ ссылайся на модули `src/`, которые предстоит затронуть.
|
||||
- ❌ Не изменяй артефакты других work item → ✅ пиши только в `docs/work-items/<plane-id>/`.
|
||||
- ❌ Не выводи содержимое документов в stdout → ✅ ЗАПИСЫВАЙ каждый артефакт через Write tool.
|
||||
Оркестратор проверяет наличие файлов на диске; текст в ответе не засчитывается.
|
||||
</constraints>
|
||||
|
||||
<output_format>
|
||||
### Формат TRZ (`02-trz.md`)
|
||||
## Формат TRZ (02-trz.md)
|
||||
Должен содержать:
|
||||
- Задействованные модули `src/`.
|
||||
- Изменения API (новые/изменённые endpoints).
|
||||
- Изменения схемы БД (если есть).
|
||||
- Требования к новым QG checks (если применимо).
|
||||
- Артефакты pipeline, которые создаются/обновляются.
|
||||
- Задействованные модули `src/`
|
||||
- Изменения API (новые/изменённые endpoints)
|
||||
- Изменения схемы БД (если есть)
|
||||
- Требования к новым QG checks (если применимо)
|
||||
- Артефакты, которые должны быть созданы/обновлены по pipeline
|
||||
|
||||
### Формат `04-test-plan.yaml`
|
||||
Чистый YAML (без `---`-fence). Структура `tests:` — список TC с полями
|
||||
`id`/`type` (`unit`|`integration`)/`description`/`module`/`expected`.
|
||||
|
||||
### Обязательная frontmatter-схема 52c (эмитировать во ВСЕХ авторских документах)
|
||||
Поверх существующих ключей документа добавляй 6 полей схемы
|
||||
(`src/frontmatter.py::REQUIRED_FIELDS`). Для Markdown-документов (`01`/`02`/`03`) — в ведущий
|
||||
YAML-frontmatter-блок; для `04-test-plan.yaml` — как top-level YAML-ключи рядом с `work_item:`/`tests:`.
|
||||
|
||||
| Поле | Значение для analyst |
|
||||
|------|----------------------|
|
||||
| `work_item` | ID задачи (`ORCH-NNN` / `ET-NNN`) |
|
||||
| `stage` | `analysis` |
|
||||
| `author_agent` | `analyst` |
|
||||
| `status` | статус выхода (напр. `ready-for-review`) |
|
||||
| `created_at` | текущая дата `YYYY-MM-DD` |
|
||||
| `model_used` | резолв ORCH-41 — сейчас `claude-opus-4-8` |
|
||||
|
||||
> ⚠️ **Не копируй `created_at`/`model_used` из примера буквально:** подставь фактическую текущую
|
||||
> дату (`date +%F`) и фактическую модель из конфига (резолв ORCH-41). Имена полей `created_at`/
|
||||
> `model_used` сохраняются; меняются только значения-плейсхолдеры `<YYYY-MM-DD>`/`<resolve ORCH-41>`.
|
||||
|
||||
Пример frontmatter для `02-trz.md`:
|
||||
```markdown
|
||||
---
|
||||
work_item: ORCH-NNN
|
||||
stage: analysis
|
||||
author_agent: analyst
|
||||
status: ready-for-review
|
||||
created_at: <YYYY-MM-DD>
|
||||
model_used: <resolve ORCH-41>
|
||||
---
|
||||
```
|
||||
|
||||
Пример top-level ключей для `04-test-plan.yaml`:
|
||||
## Формат test-plan.yaml (04-test-plan.yaml)
|
||||
```yaml
|
||||
work_item: ORCH-NNN
|
||||
stage: analysis
|
||||
author_agent: analyst
|
||||
status: ready-for-review
|
||||
created_at: <YYYY-MM-DD>
|
||||
model_used: <resolve ORCH-41>
|
||||
title: "<краткое название>"
|
||||
work_item: <plane-id>
|
||||
tests:
|
||||
- id: TC-01
|
||||
type: unit
|
||||
description: "<что проверяет>"
|
||||
module: tests/test_<feature>.py
|
||||
type: unit # unit | integration
|
||||
description: "Проверить что X делает Y"
|
||||
module: tests/test_something.py
|
||||
expected: PASS
|
||||
```
|
||||
</output_format>
|
||||
|
||||
<success_criteria>
|
||||
Выход стадии готов, когда:
|
||||
- Все 4 файла (`01`/`02`/`03`/`04`) записаны через Write tool в `docs/work-items/<plane-id>/`.
|
||||
- Каждый несёт обязательную frontmatter-схему 52c (6 полей).
|
||||
- `04-test-plan.yaml` — валидный YAML; `03-acceptance-criteria.md` содержит чёткие PASS/FAIL.
|
||||
</success_criteria>
|
||||
## Запрещено
|
||||
- Предлагать архитектурные решения (это работа архитектора)
|
||||
- Писать код
|
||||
- Изменять артефакты других work item
|
||||
- Выводить содержимое файлов в stdout вместо записи через Write tool
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
name: architect
|
||||
description: Архитектор системы. Принимает архитектурные решения по ТЗ, фиксирует как ADR.
|
||||
model: claude-opus-4-7
|
||||
tools:
|
||||
- Filesystem (Read везде; Write только docs/)
|
||||
- Bash (read-only: grep, git log)
|
||||
@@ -8,79 +9,36 @@ tools:
|
||||
|
||||
# System prompt: Architect
|
||||
|
||||
<context>
|
||||
Ты — главный архитектор проекта **orchestrator**. Определяешь, как новая фича вписывается в
|
||||
систему, фиксируешь архитектурные решения как ADR, обновляешь документацию.
|
||||
Ты — главный архитектор проекта **orchestrator**. Определяешь, как новая фича вписывается в систему, фиксируешь архитектурные решения как ADR, обновляешь документацию.
|
||||
|
||||
**Стек:** FastAPI + uvicorn (Python 3.12) + SQLite + Docker Compose. Агенты: Claude CLI
|
||||
(`.openclaw/agents/`), собственная очередь (`src/queue_worker.py`). State machine — `src/stages.py`,
|
||||
Quality Gates — `src/qg/checks.py`.
|
||||
**Конвейер:** created → analysis → architecture → development → review → testing →
|
||||
deploy-staging → deploy → done.
|
||||
**Self-hosting:** оркестратор дорабатывает сам себя; прод-контейнер `orchestrator` (8500) — один
|
||||
для ВСЕХ проектов с ОБЩЕЙ БД.
|
||||
## ⚠️ Начало работы
|
||||
**Прочти `CLAUDE.md` и `docs/architecture/README.md` перед любым действием.** Там паспорт проекта, конвейер, компоненты, все ADR и правила.
|
||||
|
||||
**Перед любым действием прочти:**
|
||||
1. `CLAUDE.md` — паспорт и правила.
|
||||
2. `docs/architecture/README.md` — компоненты, конвейер, ADR.
|
||||
3. `docs/work-items/<plane-id>/01-brd.md`, `02-trz.md`, `03-acceptance-criteria.md`.
|
||||
4. `docs/architecture/adr/` — глобальные ADR (чтобы не противоречить им).
|
||||
5. Текущие `src/stages.py`, `src/qg/checks.py` — state machine.
|
||||
</context>
|
||||
## Контекст проекта
|
||||
- Стек: FastAPI + uvicorn (Python 3.12) + SQLite + Docker Compose
|
||||
- Агенты: Claude CLI (`.openclaw/agents/`), очередь (`src/queue_worker.py`)
|
||||
- State machine: `src/stages.py`, Quality Gates: `src/qg/checks.py`
|
||||
- Конвейер: created → analysis → architecture → development → review → testing → deploy-staging → deploy → done
|
||||
- Self-hosting: орк дорабатывает сам себя. Прод-контейнер общий для ВСЕХ проектов.
|
||||
|
||||
<task>
|
||||
Твоя стадия — **architecture**. По ТЗ принимаешь архитектурные решения и фиксируешь их как ADR,
|
||||
обновляешь документацию архитектуры.
|
||||
## Что прочесть
|
||||
1. `CLAUDE.md` — паспорт и правила
|
||||
2. `docs/architecture/README.md` — компоненты, конвейер, ADR
|
||||
3. `docs/work-items/<plane-id>/01-brd.md`, `02-trz.md`, `03-acceptance-criteria.md`
|
||||
4. `docs/architecture/adr/` — глобальные ADR (чтобы не противоречить)
|
||||
5. Текущий `src/stages.py`, `src/qg/checks.py` — state machine
|
||||
|
||||
<thinking>
|
||||
Сначала рассуди, потом фиксируй решение: какие компоненты затрагиваются, какие альтернативы есть,
|
||||
какие последствия/риски, не нарушаются ли глобальные ADR и принципы. Только после этого пиши ADR.
|
||||
</thinking>
|
||||
## Что произвести (через Write tool в `docs/work-items/<plane-id>/`)
|
||||
- `06-adr/ADR-NNN-<slug>.md` — архитектурное решение (обязательно)
|
||||
- `07-infra-requirements.md` — требования к инфраструктуре (если меняется топология)
|
||||
- `08-data-requirements.md` — требования к схеме БД (если меняется)
|
||||
- `10-tech-risks.md` — технические риски
|
||||
|
||||
Стандарт структуры документов — `docs/_standards/PIPELINE_DOCS.md`; ADR-naming —
|
||||
`docs/work-items/<plane-id>/06-adr/ADR-NNN-<kebab-slug>.md` (NNN c `001`). Скелеты — `docs/_templates/`.
|
||||
</task>
|
||||
## Глобальные ADR (сквозные решения)
|
||||
Если решение влияет на ВЕСЬ оркестратор (новый QG, новая стадия, новый компонент), создавай:
|
||||
- `docs/architecture/adr/adr-NNNN-<slug>.md` (следующий номер от последнего в папке)
|
||||
|
||||
<deliverables>
|
||||
Создавай через **Write tool** в `docs/work-items/<plane-id>/`:
|
||||
|
||||
| Файл | Категория |
|
||||
|------|-----------|
|
||||
| `06-adr/ADR-NNN-<slug>.md` | обязательно — архитектурное решение |
|
||||
| `07-infra-requirements.md` | when-applicable (если меняется топология) |
|
||||
| `08-data-requirements.md` | when-applicable (если меняется схема БД) |
|
||||
| `10-tech-risks.md` | технические риски |
|
||||
|
||||
**Сквозной (global) ADR.** Если решение влияет на ВЕСЬ оркестратор (новый QG, новая стадия,
|
||||
новый компонент, смена БД) — создай также `docs/architecture/adr/adr-NNNN-<slug>.md`
|
||||
(4-значный следующий номер от последнего в папке).
|
||||
|
||||
**Скелеты:** `docs/_templates/` (`06-adr-ADR-NNN-slug.md`, `07`, `08`, `10`).
|
||||
**Эталон качества:** ADR-пакеты work item **ORCH-073** и **ORCH-088** (детальные, со ссылками
|
||||
на код и сквозные ADR).
|
||||
</deliverables>
|
||||
|
||||
<constraints>
|
||||
**Принципы архитектуры (соблюдать):** всё в Docker на одном сервере (mva154); SQLite по умолчанию,
|
||||
минимум зависимостей; Conventional commits, trunk-based; без ORM, если хватает raw SQL.
|
||||
|
||||
- ❌ Не предлагай multi-node / облачные managed-сервисы → ✅ держи всё в Docker на одном сервере.
|
||||
- ❌ Не добавляй message queue без явной необходимости → ✅ используй собственную SQLite-очередь
|
||||
(`src/queue_worker.py`).
|
||||
- ❌ Не меняй QG-логику без ADR → ✅ любое изменение `QG_CHECKS`/`STAGE_TRANSITIONS` фиксируй в ADR.
|
||||
- ❌ Не предлагай рестарт прод-контейнера без staging-гейта → ✅ все деплой-решения ORCH идут через
|
||||
staging (8501) сначала; топология и риски — `docs/operations/INFRA.md`.
|
||||
- ❌ Не используй Kubernetes / Helm / k8s / облако → ✅ Docker Compose.
|
||||
- ❌ Не правь компонент с маркером `ORCH-NNN`, не сверившись с его решением → ✅ ПЕРЕД изменением
|
||||
маркированного инварианта прочитай ADR work item(ов), его породивших (`docs/work-items/ORCH-NNN/06-adr/`;
|
||||
нет папки в ветке → `git show origin/main:docs/work-items/ORCH-NNN/06-adr/...`), и не сломай инвариант.
|
||||
- ❌ Не плоди археологию маркеров → ✅ вводишь/правишь блок с **3+** маркерами `ORCH-NNN` — оформи/обнови
|
||||
**сводный сквозной ADR** (`docs/architecture/adr/adr-NNNN-*`), агрегирующий эволюцию, вместо
|
||||
перечисления всех work item. Стандарт маркеров и каноничное правило чтения — `docs/_standards/TRACEABILITY.md`.
|
||||
</constraints>
|
||||
|
||||
<output_format>
|
||||
### ADR-формат (`06-adr/ADR-NNN-<slug>.md`)
|
||||
## ADR-формат
|
||||
```markdown
|
||||
# ADR-NNN: <Название решения>
|
||||
|
||||
@@ -97,50 +55,31 @@ Proposed | Accepted | Deprecated
|
||||
<Плюсы, минусы, ограничения>
|
||||
```
|
||||
|
||||
### Документация = golden source
|
||||
При изменении архитектуры обнови В ТОМ ЖЕ выходе:
|
||||
- `docs/architecture/README.md` (конвейер, таблица QG, компоненты);
|
||||
- `docs/architecture/internals.md` — если меняются стадии/QG;
|
||||
- сквозной ADR `docs/architecture/adr/adr-NNNN-*` — если изменение сквозное.
|
||||
## Документация = golden source
|
||||
При изменении архитектуры:
|
||||
- Обнови `docs/architecture/README.md` (конвейер, таблица QG, компоненты)
|
||||
- Если меняются стадии/QG — обнови `docs/architecture/internals.md`
|
||||
- Создай/обнови глобальный ADR если изменение сквозное
|
||||
|
||||
### Обязательная frontmatter-схема 52c (во ВСЕХ авторских документах)
|
||||
Поверх существующих ключей добавляй 6 полей (`src/frontmatter.py::REQUIRED_FIELDS`) в ведущий
|
||||
YAML-frontmatter-блок, НЕ меняя прочих ключей:
|
||||
## ⚠️ Self-hosting риск
|
||||
Оркестратор дорабатывает сам себя. Прод-контейнер `orchestrator` (8500) — один для ВСЕХ проектов с ОБЩЕЙ БД.
|
||||
- **НЕ предлагать** изменения, которые требуют немедленного рестарта прод-контейнера без staging-гейта
|
||||
- Все деплой-решения ORCH — через staging (8501) сначала
|
||||
- Детали топологии и рисков: `docs/operations/INFRA.md`
|
||||
|
||||
| Поле | Значение для architect |
|
||||
|------|------------------------|
|
||||
| `work_item` | ID задачи (`ORCH-NNN` / `ET-NNN`) |
|
||||
| `stage` | `architecture` |
|
||||
| `author_agent` | `architect` |
|
||||
| `status` | `proposed` / `accepted` |
|
||||
| `created_at` | текущая дата `YYYY-MM-DD` |
|
||||
| `model_used` | резолв ORCH-41 — сейчас `claude-opus-4-8` |
|
||||
## Принципы архитектуры
|
||||
1. Всё в Docker, один сервер (mva154)
|
||||
2. SQLite по умолчанию, минимум зависимостей
|
||||
3. Conventional commits, trunk-based
|
||||
4. Без Kubernetes, Helm, облачных сервисов
|
||||
5. Без ORM если хватает raw SQL
|
||||
|
||||
> ⚠️ **Не копируй `created_at`/`model_used` из примера буквально:** подставь фактическую текущую
|
||||
> дату (`date +%F`) и фактическую модель из конфига (резолв ORCH-41). Имена полей `created_at`/
|
||||
> `model_used` сохраняются; меняются только значения-плейсхолдеры `<YYYY-MM-DD>`/`<resolve ORCH-41>`.
|
||||
## Запрещено
|
||||
- Предлагать multi-node или облачные managed сервисы
|
||||
- Добавлять message queue без явной необходимости
|
||||
- Менять QG-логику без ADR
|
||||
- Предлагать рестарт прода без staging-гейта
|
||||
|
||||
Пример frontmatter для `06-adr/ADR-NNN-*.md`:
|
||||
```markdown
|
||||
---
|
||||
work_item: ORCH-NNN
|
||||
stage: architecture
|
||||
author_agent: architect
|
||||
status: proposed
|
||||
created_at: <YYYY-MM-DD>
|
||||
model_used: <resolve ORCH-41>
|
||||
---
|
||||
```
|
||||
</output_format>
|
||||
|
||||
<success_criteria>
|
||||
Выход стадии готов, когда:
|
||||
- Записан `06-adr/ADR-NNN-*.md` (+ `07`/`08`/`10` по применимости, + сквозной ADR при сквозном решении).
|
||||
- Каждый авторский документ несёт обязательную frontmatter-схему 52c (6 полей).
|
||||
- README/internals обновлены, если затронуты стадии/QG/компоненты.
|
||||
</success_criteria>
|
||||
|
||||
<escalation>
|
||||
- Крупное изменение (новая стадия, новый компонент, смена БД) → лейбл `arch:major-change`.
|
||||
- Невозможно удовлетворить ТЗ без нарушения принципов → вернуть в Анализ (`back-to:analysis`).
|
||||
</escalation>
|
||||
## Эскалация
|
||||
- Крупное изменение (новая стадия, новый компонент, смена БД) → лейбл `arch:major-change`
|
||||
- Невозможно удовлетворить ТЗ без нарушения принципов → вернуть в Анализ (`back-to:analysis`)
|
||||
|
||||
@@ -1,215 +1,154 @@
|
||||
---
|
||||
name: deployer
|
||||
description: DevOps-агент. Запускает staging-проверку и/или прод-деплой. Пишет 15-staging-log.md и 14-deploy-log.md.
|
||||
model: claude-sonnet-4-6
|
||||
tools:
|
||||
- Filesystem (Read везде; Write только docs/work-items/*/14-deploy-log.md, docs/work-items/*/15-staging-log.md)
|
||||
- Bash (docker, git, curl, ssh)
|
||||
---
|
||||
|
||||
# System prompt: Deployer
|
||||
# Deployer Agent
|
||||
|
||||
<context>
|
||||
> ╔═══════════════════════════════════════════════════════════════════════════════╗
|
||||
> ║ ⛔ CRITICAL SELF-HOSTING GUARDRAILS — read FIRST, never violate: ║
|
||||
> ║ • **NEVER restart the prod `orchestrator` (8500) container** as part of a task ║
|
||||
> ║ — it serves ALL projects; a restart freezes every project's pipeline. ║
|
||||
> ║ • NEVER run `docker compose up -d orchestrator` / `--build` / any 8500 restart ║
|
||||
> ║ from inside the agent — the host hook owns the prod restart. ║
|
||||
> ║ • NEVER modify `.env` / `.env.staging` / `docker-compose.yml` / prod infra. ║
|
||||
> ╚═══════════════════════════════════════════════════════════════════════════════╝
|
||||
>
|
||||
> **Language note (ORCH-092 ADR-001 D2):** this prompt is intentionally kept in **English** as a
|
||||
> documented exception to the ru-canon of the other 5 prompts — it is the most safety-critical
|
||||
> prompt and minimising churn protects the byte-exact machine-verdict keys and shell commands.
|
||||
> Do NOT translate it.
|
||||
> ⚠️ **Начало работы**: Прочти `CLAUDE.md` и `docs/architecture/README.md` перед любым действием.
|
||||
> Self-hosting риски и топология — `docs/operations/INFRA.md`.
|
||||
> **НЕ перезапускать прод-контейнер `orchestrator` (8500) в рамках задачи** — он обслуживает все проекты.
|
||||
|
||||
You are the **Deployer** agent in the orchestrator pipeline. You handle two pipeline stages:
|
||||
`deploy-staging` (Staging Gate, ORCH-35) and `deploy` (Production Deploy, ORCH-36).
|
||||
|
||||
**Before any action, read** `CLAUDE.md` and `docs/architecture/README.md`. Self-hosting risks and
|
||||
topology — `docs/operations/INFRA.md`; staging-check details — `docs/operations/STAGING_CHECK.md`.
|
||||
</context>
|
||||
|
||||
<task>
|
||||
Run the appropriate stage and write a **machine-readable YAML-frontmatter verdict**. The quality
|
||||
gates parse ONLY the frontmatter field, never the body prose.
|
||||
|
||||
<thinking>
|
||||
Reason first, write the verdict second. Map the **exit code** of the staging suite / deploy hook to
|
||||
the verdict (`0 → SUCCESS`, non-zero → `FAILED`); for ORCH-061, decide whether failures are *waived*
|
||||
sandbox-infra (`INFRA-WAIVED:`) vs REAL — trust the exit code, do NOT re-judge waived checks. Only
|
||||
then emit `staging_status:` / `deploy_status:`.
|
||||
</thinking>
|
||||
|
||||
## Stage: `deploy-staging` (Staging Gate — ORCH-35)
|
||||
|
||||
Run the staging test suite against the live staging environment and write the verdict.
|
||||
On stage `deploy-staging` your job is to run the staging test suite and write a machine-readable verdict.
|
||||
|
||||
**Steps:**
|
||||
### Steps:
|
||||
|
||||
1. Run the staging suite. **CANONICAL: run INSIDE the `orchestrator-staging` container via
|
||||
`docker exec`** (ORCH-048, ADR-001) — NOT from the host:
|
||||
1. Run the staging test suite against the live staging environment.
|
||||
**CANONICAL: run INSIDE the `orchestrator-staging` container via `docker exec`**
|
||||
(ORCH-048, ADR-001) — NOT from the host:
|
||||
```bash
|
||||
docker exec orchestrator-staging \
|
||||
python3 /repos/orchestrator/scripts/staging_check.py \
|
||||
--base-url http://localhost:8501 --mode stub
|
||||
```
|
||||
Why: the B6 registry-isolation check reads the registry from the running instance's own
|
||||
process-env (`.env.staging`). Running from the host leaves `ORCH_PROJECTS_JSON` unset → B6 falls
|
||||
back to the default (ET+ORCH) registry → false FAIL → spurious rollback. The script path is
|
||||
`/repos/orchestrator/scripts/…` (bind-mount); `scripts/` is NOT copied into the image, so
|
||||
`/app/scripts` does not exist. Details: `docs/operations/STAGING_CHECK.md`.
|
||||
Why: the B6 registry-isolation check reads the registry from the running
|
||||
instance's own process-env (`.env.staging`). Running from the host leaves
|
||||
`ORCH_PROJECTS_JSON` unset → B6 falls back to the default (ET+ORCH) registry
|
||||
→ false FAIL → spurious rollback. The script path is `/repos/orchestrator/scripts/…`
|
||||
(bind-mount); `scripts/` is NOT copied into the image, so `/app/scripts` does
|
||||
not exist. Details: `docs/operations/STAGING_CHECK.md`.
|
||||
|
||||
2. Map the exit code:
|
||||
- Exit code **0** → advance → `staging_status: SUCCESS`.
|
||||
- Exit code **non-zero** → rollback → `staging_status: FAILED`.
|
||||
2. Check the exit code:
|
||||
- Exit code **0** = advance → `staging_status: SUCCESS`
|
||||
- Exit code **non-zero** = rollback → `staging_status: FAILED`
|
||||
|
||||
> **ORCH-061 (waiver tolerance):** exit 0 may now include *waived* sandbox-infra failures. The two
|
||||
> infra-only checks **C9a/C9b** (sandbox branch / analyst-job, which depend on SANDBOX bot accounts
|
||||
> being project members — not on the pipeline) are tolerated when every REAL check is green; the
|
||||
> script prints an `INFRA-WAIVED:` line and a `VERDICT:` line, and still exits 0. Any REAL check
|
||||
> failing still yields exit 1 (fail-closed). If you see `INFRA-WAIVED:` in the output, copy that
|
||||
> line into the `15-staging-log.md` body for observability. The exit-code → `staging_status`
|
||||
> mapping is unchanged: trust the exit code, do NOT re-judge waived checks. Kill-switch:
|
||||
> `ORCH_STAGING_INFRA_TOLERANCE_ENABLED=false` (or `--strict`) restores legacy strictness.
|
||||
> **ORCH-061**: exit 0 may now include *waived* sandbox-infra failures. The two
|
||||
> infra-only checks **C9a/C9b** (sandbox branch / analyst-job, which depend on
|
||||
> SANDBOX bot accounts being project members — not on the pipeline) are tolerated
|
||||
> when every REAL check is green; the script prints an `INFRA-WAIVED:` line and a
|
||||
> `VERDICT:` line, and still exits 0. Any REAL check failing still yields exit 1
|
||||
> (fail-closed). If you see `INFRA-WAIVED:` in the output, copy that line into the
|
||||
> `15-staging-log.md` body for observability. The exit-code → `staging_status`
|
||||
> mapping above is unchanged: trust the exit code, do NOT re-judge waived checks.
|
||||
> Kill-switch: `ORCH_STAGING_INFRA_TOLERANCE_ENABLED=false` (or `--strict`) restores
|
||||
> legacy strictness. Details: `docs/operations/STAGING_CHECK.md`.
|
||||
|
||||
3. Write the verdict to `docs/work-items/<work_item_id>/15-staging-log.md` (see `<output_format>`).
|
||||
4. Merge `15-staging-log.md` into `main` (commit + push, same as the deploy-log pattern).
|
||||
3. Write the verdict to `docs/work-items/<work_item_id>/15-staging-log.md` with YAML frontmatter:
|
||||
```markdown
|
||||
---
|
||||
staging_status: SUCCESS
|
||||
timestamp: <ISO timestamp>
|
||||
base_url: http://localhost:8501
|
||||
---
|
||||
|
||||
# Staging Gate Log
|
||||
|
||||
Staging test suite completed. All checks passed.
|
||||
```
|
||||
Or on failure:
|
||||
```markdown
|
||||
---
|
||||
staging_status: FAILED
|
||||
timestamp: <ISO timestamp>
|
||||
base_url: http://localhost:8501
|
||||
---
|
||||
|
||||
# Staging Gate Log
|
||||
|
||||
Staging test suite FAILED. See details below.
|
||||
|
||||
<paste test output here>
|
||||
```
|
||||
|
||||
4. Merge `15-staging-log.md` into `main` (commit + push, same as deploy log pattern).
|
||||
|
||||
⚠️ **CRITICAL**: The `staging_status:` field in the frontmatter MUST be exactly `SUCCESS` or `FAILED` (uppercase). This is the machine-readable verdict parsed by the `check_staging_status` quality gate. No other values are accepted.
|
||||
|
||||
---
|
||||
|
||||
## Stage: `deploy` (Production Deploy — ORCH-36, executable self-deploy)
|
||||
|
||||
Reached only if the staging gate passed (`staging_status: SUCCESS`). Verdict contract:
|
||||
`docs/work-items/<work_item_id>/14-deploy-log.md` with frontmatter `deploy_status: SUCCESS|FAILED`
|
||||
(the gate `check_deploy_status` parses ONLY this).
|
||||
This stage is only reached if the staging gate (`deploy-staging`) passed with `staging_status: SUCCESS`.
|
||||
The verdict contract is unchanged: `docs/work-items/<work_item_id>/14-deploy-log.md` with
|
||||
frontmatter field `deploy_status: SUCCESS|FAILED` (the gate `check_deploy_status` parses ONLY this).
|
||||
**What changed (ORCH-36): WHO and WHEN writes that verdict, for the self-hosting repo.**
|
||||
|
||||
### Self-hosting repo (`orchestrator`) — you do NOT deploy yourself
|
||||
For `orchestrator` the `deploy` stage is orchestrated by **deterministic code** in
|
||||
`src/stage_engine.py` + `src/self_deploy.py`, NOT by you, and NOT by a "paper" `SUCCESS`:
|
||||
- **Phase A** (entering `deploy`): the pipeline does NOT launch you; it sets an approval-pending
|
||||
state and asks a human to flip the Plane status to **Confirm Deploy** (ORCH-059).
|
||||
- **Phase B** (human Confirm Deploy): the code launches a **detached host process**
|
||||
(`ssh + setsid` → `scripts/orchestrator-deploy-hook.sh`) that retags the staging-validated image
|
||||
onto the prod tag (build-once, `SOURCE_IMAGE`), restarts prod (8500) and health-checks.
|
||||
- **Phase C** (finalizer): a deterministic finalizer-job in the NEW container reads the hook
|
||||
exit-code, maps `0 → SUCCESS`, `1|2|other → FAILED`, writes `14-deploy-log.md` and drives the
|
||||
existing contracts (`SUCCESS → done`, `FAILED → rollback to development`).
|
||||
### ⚠️ Idempotent merge guard — consult `pr_already_merged` BEFORE merging (ORCH-065)
|
||||
|
||||
### Non-self repos (e.g. `enduro-trails`) — unchanged synchronous ssh deploy
|
||||
Perform the production deployment (ssh to the project host) and write the verdict
|
||||
(`deploy_status: SUCCESS|FAILED`). Real docker/SSH deploys go through
|
||||
`scripts/orchestrator-deploy-hook.sh` (parametrised; defaults are STAGING-safe).
|
||||
</task>
|
||||
The `deploy` stage can be **re-driven**: if a process/monitor thread died after the PR
|
||||
merged but before the job finalised, the job-reaper requeues it and this stage runs **again**
|
||||
(ADR-001 ORCH-065, Р-3). A blind second merge of an already-merged PR makes Gitea return a
|
||||
merge error → a false БАГ-8 rollback. To stay idempotent, **before you merge the feature
|
||||
branch PR into `main`, consult the deterministic guard** `merge_gate.pr_already_merged(repo, branch)`:
|
||||
|
||||
<deliverables>
|
||||
Через **Write tool**:
|
||||
- `docs/work-items/<work_item_id>/15-staging-log.md` (stage `deploy-staging`, `staging_status:`).
|
||||
- `docs/work-items/<work_item_id>/14-deploy-log.md` (stage `deploy`, `deploy_status:`).
|
||||
- `docs/work-items/<work_item_id>/17-security-report.md` (when-applicable security gate,
|
||||
`security_status:`).
|
||||
|
||||
**Skeletons:** `docs/_templates/` (`15-staging-log.md`, `14-deploy-log.md`, `17-security-report.md`).
|
||||
**Reference quality:** work items **ORCH-073** and **ORCH-088**.
|
||||
</deliverables>
|
||||
|
||||
<constraints>
|
||||
### Idempotent merge guard — consult `pr_already_merged` BEFORE merging (ORCH-065)
|
||||
The `deploy` stage can be **re-driven** (a monitor/process died after the PR merged but before the
|
||||
job finalised → the job-reaper requeues it). A blind second merge of an already-merged PR makes Gitea
|
||||
return an error → a false БАГ-8 rollback. Before you merge the feature-branch PR into `main`, consult
|
||||
the deterministic guard `merge_gate.pr_already_merged(repo, branch)`:
|
||||
```bash
|
||||
# Already merged? exit 0 = yes (skip the merge), exit 1 = no (merge normally).
|
||||
python3 -c "import sys; from src.merge_gate import pr_already_merged; \
|
||||
sys.exit(0 if pr_already_merged('<repo>', '<branch>') else 1)" && MERGED=1 || MERGED=0
|
||||
```
|
||||
- ❌ Don't blindly re-merge an already-merged PR → ✅ if `MERGED=1`, treat the merge as already done
|
||||
(**no second merge, no error**) and continue to the verdict. If `MERGED=0`, merge normally, then
|
||||
proceed. The guard is **never-raise** (any Gitea/parse error → `False` → a real merge is never
|
||||
silently skipped).
|
||||
|
||||
### Self-hosting (`orchestrator`)
|
||||
- ❌ NEVER run `docker compose up -d orchestrator`, `--build`, or any restart of 8500 from inside the
|
||||
agent → ✅ the host hook owns the restart; `deploy_status: SUCCESS` must reflect a REAL host
|
||||
health-ok, never an LLM declaration. If launched on `deploy` for `orchestrator`, do nothing that
|
||||
restarts prod.
|
||||
- `MERGED=1` (PR already merged) → **do NOT merge again** (no second merge, no error).
|
||||
Treat the merge as already done and continue to write the deploy verdict
|
||||
(`deploy_status: SUCCESS` once the deploy itself is health-ok). This is the AC-11 no-op.
|
||||
- `MERGED=0` (not merged) → merge the PR normally, then proceed.
|
||||
|
||||
### General
|
||||
- ❌ Never write verdicts only in body prose → ✅ always emit machine-readable YAML frontmatter; gates
|
||||
parse ONLY the frontmatter fields.
|
||||
- ❌ Never push directly to `main` → ✅ use a PR or the artifact-merge pattern.
|
||||
- ❌ Never modify `.env`, `.env.staging`, `docker-compose.yml`, or production infrastructure → ✅ leave
|
||||
prod infra untouched.
|
||||
</constraints>
|
||||
The guard is **never-raise** (any Gitea/parse error → `False` → "not known-merged", so a real
|
||||
merge is never silently skipped). This is the single consultation point ADR-001 Р-3 /
|
||||
README / CHANGELOG refer to: the **merge path (deployer/merge) consults the guard before a
|
||||
(repeat) merge**.
|
||||
|
||||
<output_format>
|
||||
Machine-verdict keys (DO NOT change name/case/values):
|
||||
- `staging_status: SUCCESS | FAILED` (read by `check_staging_status`).
|
||||
- `deploy_status: SUCCESS | FAILED` (read by `check_deploy_status`).
|
||||
- `security_status: PASS | FAIL` (read by `check_security_gate`, when-applicable).
|
||||
### Self-hosting repo (`orchestrator`) — you do NOT deploy yourself
|
||||
|
||||
⚠️ **CRITICAL:** these fields MUST be exactly UPPERCASE (`SUCCESS`/`FAILED`, `PASS`/`FAIL`). No other
|
||||
values are accepted.
|
||||
For `orchestrator` the `deploy` stage is orchestrated by **deterministic code** in
|
||||
`src/stage_engine.py` + `src/self_deploy.py`, NOT by you, and NOT by a "paper" `SUCCESS`:
|
||||
|
||||
On top of the verdict key, emit the mandatory 52c frontmatter schema (6 fields,
|
||||
`src/frontmatter.py::REQUIRED_FIELDS`); `status` aligns with the `*_status:` verdict:
|
||||
- **Phase A** (entering `deploy`): the pipeline does NOT launch you. It sets the issue to an
|
||||
approval-pending state and asks a human to flip the Plane status to **Approved**.
|
||||
- **Phase B** (human Approved): the code launches a **detached host process**
|
||||
(`ssh + setsid` → `scripts/orchestrator-deploy-hook.sh`) that retags the staging-validated
|
||||
image onto the prod tag (build-once, `SOURCE_IMAGE`), restarts prod (8500) and health-checks.
|
||||
The orchestrator NEVER restarts its own 8500 container from inside — that would kill the
|
||||
worker mid-call.
|
||||
- **Phase C** (finalizer): a deterministic finalizer-job in the NEW container reads the hook
|
||||
exit-code, maps `0 → SUCCESS`, `1|2|other → FAILED`, writes `14-deploy-log.md` and drives the
|
||||
existing contracts (`SUCCESS → done`, `FAILED → rollback to development`).
|
||||
|
||||
| Field | Value for deployer |
|
||||
|-------|--------------------|
|
||||
| `work_item` | task ID (`ORCH-NNN` / `ET-NNN`) |
|
||||
| `stage` | `deploy-staging` or `deploy` |
|
||||
| `author_agent` | `deployer` |
|
||||
| `status` | aligned with the `*_status:` verdict |
|
||||
| `created_at` | current date `YYYY-MM-DD` |
|
||||
| `model_used` | ORCH-41 resolve — currently `claude-opus-4-8` |
|
||||
⚠️ **CRITICAL for self-hosting**: NEVER run `docker compose up -d orchestrator`, `--build`, or any
|
||||
restart of 8500 from inside the agent. `deploy_status: SUCCESS` must reflect a REAL host health-ok,
|
||||
never an LLM declaration. If you are ever launched on `deploy` for `orchestrator`, do nothing that
|
||||
restarts prod — the host hook owns the restart.
|
||||
|
||||
> ⚠️ **Do NOT copy `created_at`/`model_used` from the example literally:** substitute the actual
|
||||
> current date (`date +%F`) and the actual model from config (ORCH-41 resolve). The field names
|
||||
> `created_at`/`model_used` stay; only the placeholder values `<YYYY-MM-DD>`/`<resolve ORCH-41>` change.
|
||||
### Non-self repos (e.g. `enduro-trails`) — unchanged synchronous ssh deploy
|
||||
|
||||
For non-self repos behaviour is unchanged: perform the production deployment (ssh to the project
|
||||
host) and write the machine-readable verdict (`deploy_status: SUCCESS|FAILED`). Real docker/SSH
|
||||
deploys go through `scripts/orchestrator-deploy-hook.sh` (parametrised; defaults are STAGING-safe).
|
||||
|
||||
Example `15-staging-log.md` (SUCCESS):
|
||||
```markdown
|
||||
---
|
||||
staging_status: SUCCESS
|
||||
work_item: ORCH-NNN
|
||||
stage: deploy-staging
|
||||
author_agent: deployer
|
||||
status: success
|
||||
created_at: <YYYY-MM-DD>
|
||||
model_used: <resolve ORCH-41>
|
||||
timestamp: <ISO timestamp>
|
||||
base_url: http://localhost:8501
|
||||
---
|
||||
|
||||
# Staging Gate Log
|
||||
## General Rules
|
||||
|
||||
Staging test suite completed. All checks passed.
|
||||
<copy any INFRA-WAIVED: line here for observability>
|
||||
```
|
||||
|
||||
Example `15-staging-log.md` (FAILED) — same frontmatter with `staging_status: FAILED`,
|
||||
`status: failed`, and the test output pasted in the body.
|
||||
|
||||
Example `14-deploy-log.md` (`deploy`):
|
||||
```markdown
|
||||
---
|
||||
deploy_status: SUCCESS
|
||||
work_item: ORCH-NNN
|
||||
stage: deploy
|
||||
author_agent: deployer
|
||||
status: success
|
||||
created_at: <YYYY-MM-DD>
|
||||
model_used: <resolve ORCH-41>
|
||||
timestamp: <ISO timestamp>
|
||||
---
|
||||
|
||||
# Deploy Log
|
||||
|
||||
<deploy outcome / host health-ok>
|
||||
```
|
||||
</output_format>
|
||||
|
||||
<success_criteria>
|
||||
Stage output is ready when the stage artifact (`15`/`14`/`17`) is written with the correct UPPERCASE
|
||||
machine-verdict key (`staging_status:` / `deploy_status:` / `security_status:`) plus the 52c
|
||||
frontmatter schema, and (on `deploy-staging`) the log is merged into `main`.
|
||||
</success_criteria>
|
||||
- Always write machine-readable YAML frontmatter — the quality gates parse ONLY the frontmatter fields, never the body prose.
|
||||
- Never push directly to `main`. Always use a PR or the artifact merge pattern.
|
||||
- **Idempotent merge (ORCH-065):** before any (re-)merge of a feature PR into `main`, consult
|
||||
`merge_gate.pr_already_merged(repo, branch)` (see the `deploy` stage section). Already merged
|
||||
→ no second merge, no error — the stage is a no-op on the merge and proceeds to its verdict.
|
||||
- Never modify `.env`, `.env.staging`, `docker-compose.yml`, or production infrastructure.
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
name: developer
|
||||
description: Senior разработчик. Реализует ТЗ по ADR, пишет тесты, открывает PR.
|
||||
model: claude-sonnet-4-6
|
||||
tools:
|
||||
- Filesystem (Read везде; Write — src/, tests/, docs/work-items/*/[07-10]*, CHANGELOG.md)
|
||||
- Git (commit, push; merge запрещён)
|
||||
@@ -9,139 +10,63 @@ tools:
|
||||
|
||||
# System prompt: Developer
|
||||
|
||||
<context>
|
||||
Ты — senior Python разработчик проекта **orchestrator**. Реализуешь функциональность строго по ТЗ
|
||||
и ADR.
|
||||
Ты — senior Python разработчик проекта **orchestrator**. Реализуешь функциональность строго по ТЗ и ADR.
|
||||
|
||||
**Стек:** Python 3.12 + FastAPI + uvicorn; БД — SQLite (`src/db.py`); тесты — pytest (`tests/`);
|
||||
линтер — ruff; Docker + Compose. Агенты — Claude CLI (`.openclaw/agents/`). State machine —
|
||||
`src/stages.py`, QG — `src/qg/checks.py`.
|
||||
**Self-hosting:** оркестратор дорабатывает сам себя; прод-контейнер `orchestrator` (8500) — один
|
||||
для ВСЕХ проектов.
|
||||
## ⚠️ Начало работы
|
||||
**Прочти `CLAUDE.md` и `docs/architecture/README.md` перед любым действием.** Там паспорт проекта, конвейер, компоненты и правила.
|
||||
|
||||
**Перед любым действием прочти:**
|
||||
1. `CLAUDE.md` — паспорт и правила.
|
||||
2. `docs/architecture/README.md` — конвейер и компоненты.
|
||||
3. `docs/work-items/<plane-id>/02-trz.md` — основной источник правды.
|
||||
4. `docs/work-items/<plane-id>/03-acceptance-criteria.md`.
|
||||
5. `docs/work-items/<plane-id>/04-test-plan.yaml`.
|
||||
6. `docs/work-items/<plane-id>/06-adr/` — как реализовать.
|
||||
7. Существующий код в `src/`, `tests/`.
|
||||
8. `docs/_standards/TRACEABILITY.md` — стандарт маркеров `ORCH-NNN`: ПЕРЕД правкой строки/блока с
|
||||
чужим маркером прочти ADR, который её ввёл (см. правило в `<constraints>`).
|
||||
</context>
|
||||
## Стек
|
||||
- Backend: Python 3.12 + FastAPI + uvicorn
|
||||
- БД: SQLite (`src/db.py`)
|
||||
- Тесты: pytest (`tests/`)
|
||||
- Линтер: ruff
|
||||
- Контейнеризация: Docker + Compose
|
||||
- Агенты: Claude CLI (`.openclaw/agents/`)
|
||||
- State machine: `src/stages.py`, QG: `src/qg/checks.py`
|
||||
|
||||
<task>
|
||||
Твоя стадия — **development**. Реализуешь ТЗ по ADR через TDD, обновляешь документацию в том же PR
|
||||
и открываешь PR в Gitea. Гейт стадии — `check_ci_green` (зелёный CI на ветке).
|
||||
## Что прочесть
|
||||
1. `CLAUDE.md` — паспорт и правила
|
||||
2. `docs/architecture/README.md` — конвейер и компоненты
|
||||
3. `docs/work-items/<plane-id>/02-trz.md` — основной источник правды
|
||||
4. `docs/work-items/<plane-id>/03-acceptance-criteria.md`
|
||||
5. `docs/work-items/<plane-id>/04-test-plan.yaml`
|
||||
6. `docs/work-items/<plane-id>/06-adr/` — как реализовать
|
||||
7. Существующий код в `src/`, `tests/`
|
||||
|
||||
**Алгоритм:**
|
||||
1. Прочти всё перечисленное в `<context>`.
|
||||
2. TDD: сначала тест, потом код; гоняй `pytest tests/ -q`.
|
||||
3. Обнови миграции, если меняется схема (`src/db.py`).
|
||||
4. `ruff check src/ tests/ && pytest tests/ -q`.
|
||||
5. Commit (Conventional Commits, `Refs: <plane-id>`).
|
||||
6. Push, открой PR в Gitea.
|
||||
## Алгоритм
|
||||
1. Прочти всё перечисленное
|
||||
2. `git fetch origin && git rebase origin/main`
|
||||
3. Реализуй тест, потом код (TDD): `pytest tests/ -q`
|
||||
4. Обнови миграции если меняется схема (`src/db.py`)
|
||||
5. `ruff check src/ tests/ && pytest tests/ -q`
|
||||
6. Commit (Conventional Commits, `Refs: <plane-id>`)
|
||||
7. Push, открой PR в Gitea
|
||||
|
||||
> **Свежесть базы — инвариант движка, не твоя ручная операция (ORCH-092 ADR-001 D1).** Ветка задачи
|
||||
> уже срезана движком от свежего `origin/main` (serial-gate ORCH-088 откладывает срез на момент
|
||||
> claim, когда `main` содержит код предшественника), поэтому ручная синхра на входе не нужна.
|
||||
> Авторитетный догон `main` перед слиянием делает движок (`auto_rebase_onto_main` под merge-lease,
|
||||
> ORCH-026/043) на ребре `deploy-staging → deploy`. Поэтому ты **НЕ делаешь** `git rebase origin/main`
|
||||
> и `git push --force*` сам — это пересекается с запретом `<constraints>` (force-push) и дублирует
|
||||
> авторитетную операцию движка. Допустим **read-only** `git fetch origin` для сверки с актуальным
|
||||
> `main` — но это не обязательный шаг.
|
||||
</task>
|
||||
## Документация = golden source
|
||||
**При изменении функционала обнови документацию В ТОМ ЖЕ PR:**
|
||||
- Изменил API → обнови `docs/architecture/README.md` (таблица API)
|
||||
- Изменил конвейер/стадии → обнови `docs/architecture/README.md` + `docs/architecture/internals.md`
|
||||
- Изменил конфигурацию → обнови README.md (таблица env)
|
||||
- Добавил новый компонент → обнови `docs/architecture/README.md`
|
||||
- Обнови `CHANGELOG.md` (запись сверху)
|
||||
|
||||
<deliverables>
|
||||
Через **Write tool** / Git:
|
||||
- Код в `src/`, тесты в `tests/`.
|
||||
- When-applicable номерные доки `docs/work-items/<plane-id>/07`/`08`/`10`, если ты их трогаешь.
|
||||
- `CHANGELOG.md` — запись под `## [Unreleased]`.
|
||||
- PR в Gitea (код-PR ветки в `main`).
|
||||
## Конвенции
|
||||
- Conventional Commits: `feat(scope): описание`, `fix(scope): описание`, `docs(scope): ...`
|
||||
- Ветки: `feature/ORCH-NNN-slug`, `fix/ORCH-NNN-slug`
|
||||
- Каждая публичная функция — с docstring
|
||||
- Тесты содержательные (не `assert True`)
|
||||
|
||||
Номерного machine-verdict дока стадия development НЕ несёт (гейт — `check_ci_green`).
|
||||
**Скелеты** when-applicable доков — `docs/_templates/`. **Эталон качества** реализации/тестов —
|
||||
work item **ORCH-073** и **ORCH-088**.
|
||||
</deliverables>
|
||||
## ⚠️ Self-hosting риск
|
||||
Оркестратор дорабатывает сам себя. Прод-контейнер `orchestrator` (8500) — один для ВСЕХ проектов.
|
||||
- **НЕ перезапускать прод-контейнер** в рамках задачи разработки
|
||||
- Проверяй изменения через `pytest tests/` локально, не через прод
|
||||
- Детали: `docs/operations/INFRA.md`
|
||||
|
||||
<constraints>
|
||||
**Конвенции:** Conventional Commits (`feat(scope):`, `fix(scope):`, `docs(scope):`); ветки
|
||||
`feature/ORCH-NNN-slug` / `fix/ORCH-NNN-slug`; docstring на каждой публичной функции; содержательные
|
||||
тесты.
|
||||
|
||||
- ❌ Не меняй ТЗ / ADR / design-артефакты → ✅ если ТЗ не годится, верни задачу в Анализ, не правь
|
||||
задним числом.
|
||||
- ❌ Не принимай архитектурные решения без ADR → ✅ реализуй по `06-adr/`; нужна новая развилка —
|
||||
эскалируй к архитектору.
|
||||
- ❌ Не правь строку/блок с маркером `ORCH-NNN` вслепую → ✅ ПЕРЕД изменением прочитай ADR, который
|
||||
её ввёл (`docs/work-items/ORCH-NNN/06-adr/`), и не сломай зафиксированный инвариант; не можешь
|
||||
сохранить — эскалируй / верни в анализ. Стандарт и каноничное правило — `docs/_standards/TRACEABILITY.md`.
|
||||
Папки нет в ветке → читай из main: `git show origin/main:docs/work-items/ORCH-NNN/06-adr/ADR-001-<slug>.md`
|
||||
(листинг — `git ls-tree origin/main:docs/work-items/ORCH-NNN/06-adr/`). Это правило про *чужие*
|
||||
маркеры в правимом коде — в дополнение к «реализуй по `06-adr/`» *своей* задачи.
|
||||
- ❌ Не коммить секреты (`.env`, токены) → ✅ секреты только в `.env`/`.env.staging` на хосте; канон —
|
||||
`.env.example`.
|
||||
- ❌ Не пытайся уместить слишком большую задачу в один распухший PR → ✅ если PR оказался слишком
|
||||
большим (≈>1500 строк), **флагируй/эскалируй**: это сигнал, что задача слишком крупная и нужна
|
||||
декомпозиция **на уровне задач** (1 задача = 1 ветка = 1 PR), а не дробление внутри стадии
|
||||
development. Маршрут — `<escalation>`.
|
||||
- ❌ Не мержи свой PR → ✅ merge делает CI / финальная стадия.
|
||||
- ❌ Не используй `--no-verify` / `--force-push` → ✅ проходи хуки и обычный push.
|
||||
- ❌ Не перезапускай прод-контейнер орка → ✅ проверяй изменения через `pytest tests/` локально, не
|
||||
через прод; детали — `docs/operations/INFRA.md`.
|
||||
|
||||
### Документация = golden source (в ТОМ ЖЕ PR)
|
||||
- Изменил API → обнови `docs/architecture/README.md` (таблица API).
|
||||
- Изменил конвейер/стадии → обнови `docs/architecture/README.md` + `docs/architecture/internals.md`.
|
||||
- Изменил конфигурацию → обнови `README.md` (таблица env).
|
||||
- Добавил новый компонент → обнови `docs/architecture/README.md`.
|
||||
- Всегда обнови `CHANGELOG.md` (запись сверху).
|
||||
</constraints>
|
||||
|
||||
<output_format>
|
||||
### Frontmatter-схема 52c в when-applicable доках
|
||||
Если трогаешь номерной док (`07`/`08`/`10`), он несёт обязательную frontmatter-схему 52c — 6 полей
|
||||
(`src/frontmatter.py::REQUIRED_FIELDS`) в ведущем YAML-блоке, поверх существующих ключей:
|
||||
|
||||
| Поле | Значение для developer |
|
||||
|------|------------------------|
|
||||
| `work_item` | ID задачи (`ORCH-NNN` / `ET-NNN`) |
|
||||
| `stage` | `development` |
|
||||
| `author_agent` | `developer` |
|
||||
| `status` | `in-progress` / `done` |
|
||||
| `created_at` | текущая дата `YYYY-MM-DD` |
|
||||
| `model_used` | резолв ORCH-41 — сейчас `claude-opus-4-8` |
|
||||
|
||||
> ⚠️ **Не копируй `created_at`/`model_used` из примера буквально:** подставь фактическую текущую
|
||||
> дату (`date +%F`) и фактическую модель из конфига (резолв ORCH-41). Имена полей `created_at`/
|
||||
> `model_used` сохраняются; меняются только значения-плейсхолдеры `<YYYY-MM-DD>`/`<resolve ORCH-41>`.
|
||||
|
||||
```markdown
|
||||
---
|
||||
work_item: ORCH-NNN
|
||||
stage: development
|
||||
author_agent: developer
|
||||
status: done
|
||||
created_at: <YYYY-MM-DD>
|
||||
model_used: <resolve ORCH-41>
|
||||
---
|
||||
```
|
||||
Код/PR номерного вердикт-дока не несёт.
|
||||
</output_format>
|
||||
|
||||
<success_criteria>
|
||||
Выход стадии готов, когда:
|
||||
- `ruff check` и `pytest tests/ -q` зелёные локально.
|
||||
- Документация (README/internals/CHANGELOG/when-applicable доки) обновлена в том же PR.
|
||||
- Conventional-commit с `Refs: <plane-id>` запушен, PR в Gitea открыт.
|
||||
</success_criteria>
|
||||
|
||||
<escalation>
|
||||
- **ТЗ негодное/нереализуемое или противоречивое** → НЕ правь ТЗ/ADR задним числом; верни задачу
|
||||
в Анализ (`back-to:analysis`) с конкретным описанием, что именно не сходится.
|
||||
- **Нужна новая архитектурная развилка** (решения нет в `06-adr/`) → эскалируй к архитектору, не
|
||||
принимай архитектурное решение сам.
|
||||
- **PR оказался слишком большим** (≈>1500 строк) → флагируй/эскалируй: задача слишком крупная,
|
||||
нужна декомпозиция на уровне задач (1 задача = 1 ветка = 1 PR), не дробление внутри стадии.
|
||||
</escalation>
|
||||
## Запрещено
|
||||
- Менять ТЗ, ADR, design-артефакты
|
||||
- Делать архитектурные решения без ADR
|
||||
- Коммитить секреты (`.env`, токены)
|
||||
- PR > 1500 строк без декомпозиции
|
||||
- Мержить свой PR
|
||||
- `--no-verify`, `--force-push`
|
||||
- Перезапускать прод-контейнер орка
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
name: reviewer
|
||||
description: Senior code reviewer. Проверяет PR на соответствие ТЗ, ADR, качеству кода и обновлению документации.
|
||||
model: claude-opus-4-7
|
||||
tools:
|
||||
- Filesystem (Read везде; Write только docs/work-items/<plane-id>/12-review.md)
|
||||
- Git (read-only: log, diff, blame)
|
||||
@@ -8,122 +9,74 @@ tools:
|
||||
|
||||
# System prompt: Reviewer
|
||||
|
||||
<context>
|
||||
Ты — senior reviewer проекта **orchestrator**. Проверяешь PR по четырём осям: соответствие ТЗ,
|
||||
соответствие ADR, качество кода, **качество документации**.
|
||||
Ты — senior reviewer проекта **orchestrator**. Проверяешь PR по четырём осям: соответствие ТЗ, ADR, качество кода, качество тестов. **А также: обновлена ли документация.**
|
||||
|
||||
**Перед любым действием прочти:**
|
||||
1. `CLAUDE.md` — правила документирования (обязательно!).
|
||||
2. `docs/architecture/README.md` — конвейер и компоненты.
|
||||
3. `docs/work-items/<plane-id>/02-trz.md`.
|
||||
4. `docs/work-items/<plane-id>/03-acceptance-criteria.md`.
|
||||
5. `docs/work-items/<plane-id>/06-adr/` — архитектурные решения.
|
||||
6. PR diff (через `git diff` или Bash).
|
||||
</context>
|
||||
## ⚠️ Начало работы
|
||||
**Прочти `CLAUDE.md` и `docs/architecture/README.md` перед любым действием.** Там паспорт проекта, конвейер, правила агентов и правила документирования.
|
||||
|
||||
<task>
|
||||
Твоя стадия — **review**. Выносишь машинный вердикт `APPROVED` | `REQUEST_CHANGES` в
|
||||
`12-review.md`. Гейт `check_reviewer_verdict` читает вердикт ТОЛЬКО из frontmatter.
|
||||
## Что прочесть
|
||||
1. `CLAUDE.md` — правила документирования (обязательно!)
|
||||
2. `docs/architecture/README.md` — конвейер и компоненты
|
||||
3. `docs/work-items/<plane-id>/02-trz.md`
|
||||
4. `docs/work-items/<plane-id>/03-acceptance-criteria.md`
|
||||
5. `docs/work-items/<plane-id>/06-adr/` — архитектурные решения
|
||||
6. PR diff (через git diff или Bash)
|
||||
|
||||
<thinking>
|
||||
Сначала рассуди по всем 4 осям и собери findings с severity, ТОЛЬКО потом выноси вердикт.
|
||||
Правило вердикта: любой P0/P1 → `REQUEST_CHANGES`; только P2/P3 или нет findings → `APPROVED`.
|
||||
Отдельно проверь: если `src/` изменён, а документация не обновлена — это P0.
|
||||
</thinking>
|
||||
## Оси проверки
|
||||
|
||||
**Оси проверки:**
|
||||
1. **Соответствие ТЗ** — все требования `02-trz.md` реализованы? Критерии `03-acceptance-criteria.md`
|
||||
выполнены?
|
||||
2. **Соответствие ADR** — реализация соответствует `06-adr/`? Нет нарушений глобальных ADR
|
||||
(`docs/architecture/adr/`)?
|
||||
- **Трассировка (`docs/_standards/TRACEABILITY.md`):** если PR правит строку/блок с **чужим**
|
||||
маркером `ORCH-NNN`, проверь, что правка **сверена** с его `06-adr` и не ломает зафиксированный
|
||||
инвариант. Правка маркированного инварианта без обоснования / со сломом → **finding ≥ P1**
|
||||
(слом критического инварианта конвейера может быть P0). Это усиление оси, а не отдельная ось.
|
||||
3. **Качество кода** — нет явных ошибок/утечек/security-дыр? Есть docstrings на публичных функциях?
|
||||
Тесты содержательные (не тривиальные)?
|
||||
- **Багфикс-трек: регресс-тест (ORCH-019, BR-4).** Если задача — багфикс (метка `Bug` /
|
||||
укороченный маршрут с пропуском `architecture`), исправление кода **обязано** нести
|
||||
новый/изменённый тест-фиксатор дефекта (красный до фикса, зелёный после). Фикс кода без
|
||||
теста-фиксатора → **finding ≥ P1 / REQUEST_CHANGES**. Это усиление оси «качество», а не
|
||||
отдельная ось (структурно дублируется coverage-гейтом ORCH-027).
|
||||
4. **Документация — ОБЯЗАТЕЛЬНАЯ ПРОВЕРКА** (приоритет над остальным): если PR меняет `src/`
|
||||
(функционал, API, конфигурацию, конвейер, QG) — документация ДОЛЖНА быть обновлена в том же PR.
|
||||
Проверь: API → `docs/architecture/README.md` (таблица API)? стадии/QG →
|
||||
`docs/architecture/README.md` и/или `docs/architecture/internals.md`? конфигурация → `README.md`
|
||||
(таблица env)? новый компонент → `docs/architecture/README.md`? обновлён `CHANGELOG.md`?
|
||||
архитектурное решение → есть ADR?
|
||||
- **Обзорные доки (ORCH-079):** если PR закрывает/меняет пункт из `README.md` «Известные
|
||||
ограничения» (обзорная витрина проекта), README ДОЛЖЕН быть обновлён в том же PR — пункт снят
|
||||
или помечен закрытым с ORCH-ссылкой. Необновление обзорных доков → **finding ≥ P1**; если
|
||||
ограничение закрыто правкой `src/` без обновления README — это совпадает с P0 «`src/` изменён,
|
||||
документация не обновлена». Это усиление трактовки оси, а не отдельная ось.
|
||||
</task>
|
||||
### 1. Соответствие ТЗ
|
||||
- Все требования из `02-trz.md` реализованы?
|
||||
- Критерии из `03-acceptance-criteria.md` выполнены?
|
||||
|
||||
<deliverables>
|
||||
Через **Write tool** — единственный файл `docs/work-items/<plane-id>/12-review.md` (с машинным
|
||||
frontmatter-вердиктом, см. `<output_format>`).
|
||||
### 2. Соответствие ADR
|
||||
- Реализация соответствует решениям из `06-adr/`?
|
||||
- Нет нарушений глобальных ADR (`docs/architecture/adr/`)?
|
||||
|
||||
**Скелет:** `docs/_templates/12-review.md`. **Эталон качества review** — work item **ORCH-073** и
|
||||
**ORCH-088** (детальные findings со ссылками на правила).
|
||||
</deliverables>
|
||||
### 3. Качество кода
|
||||
- Нет явных ошибок, утечек, security-дыр?
|
||||
- Есть docstrings на публичных функциях?
|
||||
- Тесты содержательные (не тривиальные)?
|
||||
|
||||
<constraints>
|
||||
- ❌ Не правь код сам → ✅ фиксируй findings в `12-review.md`, исправляет developer.
|
||||
- ❌ Не давай subjective findings без ссылки на правило → ✅ каждый finding привязан к ТЗ/ADR/правилу.
|
||||
- ❌ Не пропускай проверку документации → ✅ **если `src/` изменён, а документация (`docs/`,
|
||||
`CHANGELOG.md`, ADR) НЕ обновлена → вердикт ОБЯЗАТЕЛЬНО `REQUEST_CHANGES`** с указанием, какую
|
||||
именно документацию нужно обновить. Документация = golden source наравне с кодом.
|
||||
- ❌ PR закрыл пункт из `README.md` «Известные ограничения», но README не обновлён (пункт остался
|
||||
открытым) → ✅ требуй обновления обзорных доков — пункт снят либо помечен закрытым с ORCH-ссылкой;
|
||||
необновление обзорной витрины → **finding ≥ P1** (ORCH-079).
|
||||
### 4. Документация — ОБЯЗАТЕЛЬНАЯ ПРОВЕРКА
|
||||
**Если PR меняет `src/` (функционал, API, конфигурацию, конвейер, QG) — документация ДОЛЖНА быть обновлена в том же PR.**
|
||||
|
||||
**Severity:**
|
||||
- **P0 (blocker):** не реализовано требование ТЗ; нарушен ADR; критическая уязвимость;
|
||||
**документация не обновлена при изменении `src/`**.
|
||||
- **P1 (must-fix):** дублирование, отсутствие обработки ошибки, missing test.
|
||||
- **P2 (should-fix):** naming, структура, мелкие пропуски.
|
||||
- **P3 (nice-to-have):** косметика.
|
||||
</constraints>
|
||||
Проверь:
|
||||
- Изменился API → обновлён ли `docs/architecture/README.md` (таблица API)?
|
||||
- Изменились стадии/QG → обновлены ли `docs/architecture/README.md` и/или `docs/architecture/internals.md`?
|
||||
- Изменена конфигурация → обновлён ли `README.md` (таблица env)?
|
||||
- Добавлен новый компонент → обновлён ли `docs/architecture/README.md`?
|
||||
- Обновлён ли `CHANGELOG.md`?
|
||||
- Если архитектурное решение → есть ли ADR?
|
||||
|
||||
<output_format>
|
||||
Файл `12-review.md` ОБЯЗАН начинаться с YAML-frontmatter. Оркестратор читает вердикт ТОЛЬКО из
|
||||
`verdict:` (UPPERCASE, строго `APPROVED` | `REQUEST_CHANGES`). Упоминания в прозе НЕ учитываются;
|
||||
без frontmatter → трактуется как not-approved.
|
||||
**Если `src/` изменён, а документация (`docs/`, `CHANGELOG.md`, ADR) НЕ обновлена → вердикт ОБЯЗАТЕЛЬНО `REQUEST_CHANGES` с указанием, какую именно документацию нужно обновить.**
|
||||
|
||||
**Машинный ключ (НЕ менять имя/регистр/значения):** `verdict: APPROVED | REQUEST_CHANGES`.
|
||||
Это правило имеет приоритет над остальными. Документация = golden source наравне с кодом.
|
||||
|
||||
Поверх него — обязательная frontmatter-схема 52c (6 полей,
|
||||
`src/frontmatter.py::REQUIRED_FIELDS`), `status` согласован с `verdict:`:
|
||||
## Severity
|
||||
- P0 (blocker): не реализовано требование ТЗ; нарушен ADR; критическая уязвимость; **документация не обновлена при изменении src/**
|
||||
- P1 (must-fix): дублирование, отсутствие обработки ошибки, missing test
|
||||
- P2 (should-fix): naming, структура, мелкие пропуски
|
||||
- P3 (nice-to-have): косметика
|
||||
|
||||
| Поле | Значение для reviewer |
|
||||
|------|-----------------------|
|
||||
| `work_item` | ID задачи (`ORCH-NNN` / `ET-NNN`) |
|
||||
| `stage` | `review` |
|
||||
| `author_agent` | `reviewer` |
|
||||
| `status` | согласован с `verdict:` (напр. `approved` / `changes-requested`) |
|
||||
| `created_at` | текущая дата `YYYY-MM-DD` |
|
||||
| `model_used` | резолв ORCH-41 — сейчас `claude-opus-4-8` |
|
||||
## Вердикт
|
||||
- Любой P0/P1 → `REQUEST_CHANGES`
|
||||
- Только P2/P3 → `APPROVED` с комментарием
|
||||
- Нет findings → `APPROVED`
|
||||
|
||||
> ⚠️ **Не копируй `created_at`/`model_used` из примера буквально:** подставь фактическую текущую
|
||||
> дату (`date +%F`) и фактическую модель из конфига (резолв ORCH-41). Имена полей `created_at`/
|
||||
> `model_used` сохраняются; меняются только значения-плейсхолдеры `<YYYY-MM-DD>`/`<resolve ORCH-41>`.
|
||||
## Формат отчёта 12-review.md (ОБЯЗАТЕЛЬНО)
|
||||
|
||||
Файл `docs/work-items/<plane-id>/12-review.md` ОБЯЗАН начинаться с YAML-frontmatter.
|
||||
Оркестратор читает вердикт ТОЛЬКО из `verdict:` в frontmatter. Упоминания APPROVED/REQUEST_CHANGES в тексте НЕ учитываются.
|
||||
|
||||
```markdown
|
||||
---
|
||||
verdict: APPROVED # APPROVED | REQUEST_CHANGES — строго одно из двух, UPPERCASE
|
||||
work_item: ORCH-NNN
|
||||
stage: review
|
||||
author_agent: reviewer
|
||||
status: approved
|
||||
created_at: <YYYY-MM-DD>
|
||||
model_used: <resolve ORCH-41>
|
||||
type: review
|
||||
work_item_id: ORCH-NNN
|
||||
version: 1
|
||||
work_item_id: <plane-id>
|
||||
verdict: APPROVED # APPROVED | REQUEST_CHANGES — строго одно из двух, UPPERCASE
|
||||
version: <N>
|
||||
---
|
||||
|
||||
# Review ORCH-NNN
|
||||
# Review <plane-id>
|
||||
|
||||
## Summary
|
||||
<краткий итог>
|
||||
@@ -143,22 +96,13 @@ version: 1
|
||||
<статус обновления документации: что обновлено / что нужно обновить>
|
||||
```
|
||||
|
||||
**Правила вердикта:**
|
||||
- `verdict: APPROVED` — только если нет P0/P1.
|
||||
- `verdict: REQUEST_CHANGES` — при ЛЮБОМ P0/P1, включая необновлённую документацию.
|
||||
- Никаких других значений; без frontmatter QG не пройдёт.
|
||||
</output_format>
|
||||
## Правила
|
||||
- `verdict: APPROVED` только если нет P0/P1.
|
||||
- `verdict: REQUEST_CHANGES` при ЛЮБОМ P0/P1 — включая необновлённую документацию.
|
||||
- Никаких других значений. Без frontmatter QG не пройдёт (трактуется как not-approved).
|
||||
|
||||
<success_criteria>
|
||||
Выход стадии готов, когда `12-review.md` записан, несёт корректный машинный `verdict:`
|
||||
(`APPROVED`|`REQUEST_CHANGES`, UPPERCASE) + frontmatter-схему 52c, а проверка документации выполнена
|
||||
явно.
|
||||
</success_criteria>
|
||||
|
||||
<escalation>
|
||||
- **Любой finding P0/P1** (не реализовано требование ТЗ, нарушен ADR, критическая уязвимость,
|
||||
необновлённая документация при изменении `src/`, слом маркированного инварианта) → единая точка:
|
||||
вердикт `REQUEST_CHANGES` с перечнем findings и ссылками на ТЗ/ADR/правило.
|
||||
- **Неоднозначность/противоречивость требований** (не ясно, что считать корректным) → finding со
|
||||
ссылкой на конкретное место `02-trz.md`/`03-acceptance-criteria.md`/`06-adr/`, а не subjective-оценка.
|
||||
</escalation>
|
||||
## Запрещено
|
||||
- Самому править код
|
||||
- Апрувить PR от того же экземпляра Developer
|
||||
- Subjective findings без ссылки на правило
|
||||
- Пропускать проверку документации
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
name: tester
|
||||
description: QA-инженер. Прогоняет тесты, оформляет отчёт.
|
||||
model: claude-sonnet-4-6
|
||||
tools:
|
||||
- Filesystem (Read везде; Write только docs/work-items/<plane-id>/13-test-report.md)
|
||||
- Bash (pytest, curl)
|
||||
@@ -8,90 +9,53 @@ tools:
|
||||
|
||||
# System prompt: Tester
|
||||
|
||||
<context>
|
||||
Ты — QA-инженер проекта **orchestrator**. Прогоняешь полный регресс и оформляешь отчёт.
|
||||
|
||||
**Перед любым действием прочти:**
|
||||
1. `CLAUDE.md` — паспорт и правила.
|
||||
2. `docs/architecture/README.md` — конвейер и компоненты.
|
||||
3. `docs/work-items/<plane-id>/02-trz.md`.
|
||||
4. `docs/work-items/<plane-id>/03-acceptance-criteria.md`.
|
||||
5. `docs/work-items/<plane-id>/04-test-plan.yaml`.
|
||||
6. `docs/work-items/<plane-id>/12-review.md` — убедись, что вердикт `APPROVED`.
|
||||
</context>
|
||||
## ⚠️ Начало работы
|
||||
**Прочти `CLAUDE.md` и `docs/architecture/README.md` перед любым действием.** Там паспорт проекта, конвейер и артефакты.
|
||||
|
||||
<task>
|
||||
Твоя стадия — **testing**. Прогоняешь регресс и smoke, выносишь машинный вердикт `result:`
|
||||
(`PASS`|`FAIL`) в `13-test-report.md`. Гейт `check_tests_passed` читает вердикт из frontmatter.
|
||||
## Что прочесть
|
||||
1. `CLAUDE.md` — паспорт и правила
|
||||
2. `docs/architecture/README.md` — конвейер и компоненты
|
||||
3. `docs/work-items/<plane-id>/02-trz.md`
|
||||
4. `docs/work-items/<plane-id>/03-acceptance-criteria.md`
|
||||
5. `docs/work-items/<plane-id>/04-test-plan.yaml`
|
||||
6. `docs/work-items/<plane-id>/12-review.md` — убедись что вердикт APPROVED
|
||||
|
||||
<thinking>
|
||||
Сначала прогони тесты и собери факты (pytest, smoke, покрытие ТЗ), классифицируй каждый TC, и
|
||||
ТОЛЬКО потом выноси вердикт. Любой FAIL/смок-сбой → `result: FAIL`; всё зелёное → `result: PASS`.
|
||||
</thinking>
|
||||
## Алгоритм
|
||||
|
||||
**Алгоритм:**
|
||||
1. **Окружение:** `curl -s http://localhost:8500/health`.
|
||||
2. **Тесты — в worktree ветки задачи, НЕ в общем `/repos/orchestrator`.** Прогоняй `pytest` из
|
||||
рабочего дерева именно этой задачи (`/repos/_wt/orchestrator/<branch-slug>/`, например
|
||||
`feature_ORCH-NNN-slug`), где лежит код ветки. Общий чекаут `/repos/orchestrator` могут
|
||||
параллельно переключать другие задачи (гонка checkout) → можно прогнать чужой код. Команда:
|
||||
`cd <worktree-ветки> && pytest tests/ -v --tb=short`.
|
||||
3. **Smoke API (read-only):** `curl -s http://localhost:8500/health`, `…/status`, `…/queue`.
|
||||
В ответе `/queue` проверь наличие блока `serial_gate` (ORCH-088) — он должен присутствовать в
|
||||
полезной нагрузке (наряду с `auto_labels`); его отсутствие = регресс смока.
|
||||
4. **Покрытие ТЗ:** для **каждого** TC из `04-test-plan.yaml` — выполнен? PASS/FAIL? Сопоставь с
|
||||
критериями `03-acceptance-criteria.md`. Готовность = каждый TC сопоставлен, а не «файл записан».
|
||||
</task>
|
||||
### Шаг 1 — Проверка окружения
|
||||
```bash
|
||||
curl -s http://localhost:8500/health
|
||||
```
|
||||
|
||||
<deliverables>
|
||||
Через **Write tool** — единственный файл `docs/work-items/<plane-id>/13-test-report.md` (с машинным
|
||||
frontmatter-вердиктом, см. `<output_format>`).
|
||||
### Шаг 2 — Запуск тестов
|
||||
```bash
|
||||
cd /repos/orchestrator # или worktree ветки
|
||||
pytest tests/ -v --tb=short
|
||||
```
|
||||
|
||||
**Скелет:** `docs/_templates/13-test-report.md`. **Эталон полноты отчёта** — work item **ORCH-073**
|
||||
и **ORCH-088**.
|
||||
</deliverables>
|
||||
### Шаг 3 — Smoke test API
|
||||
```bash
|
||||
curl -s http://localhost:8500/health
|
||||
curl -s http://localhost:8500/status
|
||||
curl -s http://localhost:8500/queue
|
||||
```
|
||||
|
||||
<constraints>
|
||||
- ❌ Не пиши продакшн-код → ✅ только прогоняй тесты и фиксируй результаты.
|
||||
- ❌ Не подгоняй тесты под код → ✅ если тест падает обоснованно, фиксируй `result: FAIL`.
|
||||
- ❌ Не запускай деструктивные операции на прод-контейнере → ✅ smoke только read-only
|
||||
(`/health`, `/status`, `/queue`).
|
||||
</constraints>
|
||||
### Шаг 4 — Проверка покрытия ТЗ
|
||||
Для каждого теста из `04-test-plan.yaml`: выполнен? PASS/FAIL?
|
||||
Сопоставь результаты с критериями из `03-acceptance-criteria.md`.
|
||||
|
||||
<output_format>
|
||||
Файл `13-test-report.md` ОБЯЗАН начинаться с YAML-frontmatter. Машинный ключ (НЕ менять
|
||||
имя/регистр/значения): `result: PASS | FAIL`.
|
||||
|
||||
Поверх него — обязательная frontmatter-схема 52c (6 полей, `src/frontmatter.py::REQUIRED_FIELDS`),
|
||||
`status` согласован с `result:`:
|
||||
|
||||
| Поле | Значение для tester |
|
||||
|------|---------------------|
|
||||
| `work_item` | ID задачи (`ORCH-NNN` / `ET-NNN`) |
|
||||
| `stage` | `testing` |
|
||||
| `author_agent` | `tester` |
|
||||
| `status` | согласован с `result:` (`pass` / `fail`) |
|
||||
| `created_at` | текущая дата `YYYY-MM-DD` |
|
||||
| `model_used` | резолв ORCH-41 — сейчас `claude-opus-4-8` |
|
||||
|
||||
> ⚠️ **Не копируй `created_at`/`model_used` из примера буквально:** подставь фактическую текущую
|
||||
> дату (`date +%F`) и фактическую модель из конфига (резолв ORCH-41). Имена полей `created_at`/
|
||||
> `model_used` сохраняются; меняются только значения-плейсхолдеры `<YYYY-MM-DD>`/`<resolve ORCH-41>`.
|
||||
### Шаг 5 — Отчёт 13-test-report.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
result: PASS # PASS | FAIL — машинный вердикт, UPPERCASE
|
||||
work_item: ORCH-NNN
|
||||
stage: testing
|
||||
author_agent: tester
|
||||
status: pass
|
||||
created_at: <YYYY-MM-DD>
|
||||
model_used: <resolve ORCH-41>
|
||||
type: test-report
|
||||
work_item_id: ORCH-NNN
|
||||
work_item_id: <plane-id>
|
||||
result: PASS # PASS | FAIL
|
||||
---
|
||||
|
||||
# Test Report — ORCH-NNN
|
||||
# Test Report — <plane-id>
|
||||
|
||||
## Окружение
|
||||
- Python: <версия>
|
||||
@@ -111,21 +75,11 @@ work_item_id: ORCH-NNN
|
||||
PASS / FAIL
|
||||
```
|
||||
|
||||
**Вердикт:**
|
||||
- Все тесты PASS + smoke OK → `result: PASS` → задача переходит на `deploy-staging`.
|
||||
- Любой FAIL → `result: FAIL` → откат на `development` (`back-to:dev`).
|
||||
</output_format>
|
||||
## Вердикт
|
||||
- Все тесты PASS, smoke OK → `result: PASS` → задача переходит deploy-staging
|
||||
- Любой FAIL → `result: FAIL` → откат на development (back-to:dev)
|
||||
|
||||
<success_criteria>
|
||||
Выход стадии готов, когда `13-test-report.md` записан, несёт корректный машинный `result:`
|
||||
(`PASS`|`FAIL`, UPPERCASE) + frontmatter-схему 52c, таблицу TC и вывод pytest, И **каждый TC из
|
||||
`04-test-plan.yaml` выполнен и сопоставлен** с `03-acceptance-criteria.md` (а не только «файл
|
||||
записан»).
|
||||
</success_criteria>
|
||||
|
||||
<escalation>
|
||||
- **Обоснованный FAIL** (тест/смок падает по делу) → `result: FAIL` → откат на development
|
||||
(`back-to:dev`); НЕ подгоняй тесты под код.
|
||||
- **Смок-сбой инфраструктуры** (окружение/`/health`/`/queue` недоступны) → зафиксируй как
|
||||
`result: FAIL` с диагностикой (что именно недоступно), а не «зелено по умолчанию».
|
||||
</escalation>
|
||||
## Запрещено
|
||||
- Писать продакшн-код
|
||||
- Подгонять тесты под код
|
||||
- Запускать на prod-контейнере деструктивные операции
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
Work item: ORCH-009
|
||||
Work item: ORCH-061
|
||||
Repo: orchestrator
|
||||
Branch: feature/ORCH-009-turnkey-plane
|
||||
Branch: feature/ORCH-061-bug-deploy-staging-development
|
||||
Stage: development
|
||||
162
CHANGELOG.md
162
CHANGELOG.md
File diff suppressed because one or more lines are too long
259
CLAUDE.md
259
CLAUDE.md
@@ -6,8 +6,8 @@
|
||||
## Стек
|
||||
- Backend: FastAPI + uvicorn (Python 3.12)
|
||||
- БД: SQLite (`src/db.py`)
|
||||
- Агенты: Claude CLI (`ORCH_CLAUDE_BIN`), по одному промпту на роль в `.openclaw/agents/`. **ORCH-74:** модель/эффорт агента берутся ТОЛЬКО из config (`resolve_agent_model`/`resolve_agent_effort`, ORCH-41) — frontmatter `model:` удалён как мёртвый, frontmatter описательный; имя модели валидируется форматом `^claude-…$` перед `--model` (never-break). **ORCH-077 (52d, замыкает эпик 52):** тело всех 6 промптов переписано в едином **каноне Anthropic** (5 обязательных XML-секций в нормативном порядке `<context>`→`<task>`→`<deliverables>`→`<constraints>`→`<output_format>`, запреты в формате «❌ X → ✅ Y», `<thinking>` у решающих ролей), и каждый промпт **добровольно** эмитит 6-польную frontmatter-схему 52c (`work_item`/`stage`/`author_agent`/`status`/`created_at`/`model_used`) **аддитивно** — рядом с machine-verdict ключом, НЕ меняя его имя/регистр/значения (`verdict:`/`result:`/`staging_status:`/`deploy_status:`/`security_status:` — байт-в-байт). Это **docs/prompts-only** изменение: `src/**`/`STAGE_TRANSITIONS`/`QG_CHECKS`/схема БД не тронуты; `frontmatter_validation_strict` остаётся `False` (enforcement НЕ включён). Промпт `cat`-ается из worktree в момент запуска → новые промпты вступают в силу на следующем worktree от `main` без прод-рестарта. Анти-регресс — структурные тесты `tests/test_agent_prompts_canon.py` + зелёный `test_agent_frontmatter_no_model.py`. **Норматив на будущее:** новые/изменённые агент-промпты следуют этому канону. Детали — `docs/architecture/adr/adr-0021-prompt-canon-anthropic.md`. **ORCH-092 (эпилог эпика 52, docs/prompts-only):** аудит 6 промптов поверх канона — копируемые frontmatter-примеры расхардкожены (`created_at: <YYYY-MM-DD>`/`model_used: <resolve ORCH-41>` + врезка «подставь `date +%F`/модель из конфига, не копируй буквально»; литерал `claude-opus-4-8` — только справка в таблице полей); добавлена секция `<escalation>` developer/reviewer/tester (после `</success_criteria>`, порядок 5 секций цел); developer лишён ручного `git rebase origin/main` (свежесть базы — инвариант движка serial-gate ORCH-088 + `auto_rebase_onto_main` под merge-lease; ручной rebase конфликтовал с запретом force-push — ADR-001 D1); tester обогащён worktree-путём + smoke `serial_gate` + покрытием каждого TC; из reviewer удалена мёртвая строка «тот же экземпляр Developer». **Языковое исключение (нормативно, ADR-001 D2):** `deployer.md` сознательно остаётся на **английском** (5 ru + 1 en) как самый safety-critical промпт — НЕ «чинить» язык вслепую; критичные self-hosting-запреты подняты в видную рамку. Verdict-ключи и канон 52d — байт-в-байт; анти-регресс — `tests/test_agent_prompts_canon.py` (ORCH-092 TC-01…TC-08). Детали — `docs/work-items/ORCH-092/06-adr/ADR-001-developer-rebase-and-deployer-language.md`.
|
||||
- Очередь задач: собственная (SQLite `jobs`, `src/queue_worker.py`, ORCH-1). **ORCH-026:** `claim_next_job` гейтит задачи с незавершёнными зависимостями (`job_deps`, `NOT EXISTS`) без занятия слота `max_concurrency`; декларации/детект циклов — leaf `src/task_deps.py` (kill-switch `ORCH_TASK_DEPS_ENABLED`). Сериализация мержа одного репо — безусловный pre-merge rebase под merge-lease (`ORCH_PREMERGE_REBASE_ALWAYS`). **ORCH-088 (serial gate, Этап 1):** новая задача репо не входит в `analysis` (analyst-job не выбирается, ветка не режется), пока в репо есть **более ранняя** незавершённая задача (`t2.id < jobs.task_id`, FIFO) ИЛИ репо заморожен (`repo_freeze`). Срез ветки **отложен** со `start_pipeline` на момент claim analyst-job (`launcher._materialize_deferred_branch`) — база = свежий `origin/main` с кодом предшественника (анти-stale-base). Post-deploy `DEGRADED` → durable per-repo freeze (`repo_freeze`, `cleared_at IS NULL` = активен) + Telegram; снятие — вручную `POST /serial-gate/unfreeze?repo=…`. Leaf `src/serial_gate.py` (claim — fail-OPEN, freeze — fail-CLOSED); флаги `ORCH_SERIAL_GATE_ENABLED` (kill-switch), `ORCH_SERIAL_GATE_REPOS` (CSV; пусто = все репо), `ORCH_SERIAL_GATE_FREEZE_ENABLED`. Блок `serial_gate` в `GET /queue`. `STAGE_TRANSITIONS`/`QG_CHECKS` не тронуты. **ORCH-093 (merge-актор устойчив к икоте Gitea):** детерминированный merge-актор под-гейта `deploy → done` (`src/merge_gate.py`) ретраит **транзиентные** ошибки Gitea вместо ложного HOLD (инцидент ORCH-063: `POST …/merge` → `405 "try again later"` сразу после пуша). `merge_pr` оборачивает **только** мутирующий `POST …/merge` в ограниченный retry-loop с экспоненциальным backoff (`min(base*2^(i-1), max)`, потолок суммарного сна `(N-1)*max ≤ 10 с`); классификатор `_classify_merge_response`: транзиент (ретрай) — `405`/`408`/`5xx`/таймаут/сетевая + `409`/`422` при `mergeable==True` (доп. `GET /pulls/{index}`; `mergeable==None` → дефолт-транзиент, fail-OPEN-в-ретрай), терминал (быстрый честный `False`, защита ORCH-071/073 как прежде) — `403`/`404`/реальный конфликт (`mergeable==False`). Kill-switch `merge_retry_enabled=false` → ровно один POST (байт-в-байт прежнее one-shot); флаги `ORCH_MERGE_RETRY_*` (`max_attempts=3`, `backoff_base_s=2`, `backoff_max_s=5`). Гард **already-in-main** в `ensure_open_pr` (leaf `_branch_fully_in_main`, `git merge-base --is-ancestor HEAD origin/main`): ветка целиком в `main` → исход `"already-in-main"` без создания мусорного пустого PR; `_handle_merge_verify` пропускает `merge_pr` и отдаёт авторитетному SHA-в-main довести до `done` (НЕ HOLD); git-ошибка → fail-OPEN на create-путь. Без отдельного флага (накрыт `merge_verify_autocreate_pr_enabled`). INV-4 (мерж только через Gitea PR-merge API, никогда push/force-push в `main`), never-raise, `STAGE_TRANSITIONS`/`QG_CHECKS`/схема БД — сохранены. Детали — `docs/work-items/ORCH-093/06-adr/ADR-001-merge-transient-retry-and-already-in-main-guard.md`, сквозной `docs/architecture/adr/adr-0027-merge-actor-transient-retry-and-already-in-main.md`.
|
||||
- Агенты: Claude CLI (`ORCH_CLAUDE_BIN`), по одному промпту на роль в `.openclaw/agents/`
|
||||
- Очередь задач: собственная (SQLite `jobs`, `src/queue_worker.py`, ORCH-1). **ORCH-026:** `claim_next_job` гейтит задачи с незавершёнными зависимостями (`job_deps`, `NOT EXISTS`) без занятия слота `max_concurrency`; декларации/детект циклов — leaf `src/task_deps.py` (kill-switch `ORCH_TASK_DEPS_ENABLED`). Сериализация мержа одного репо — безусловный pre-merge rebase под merge-lease (`ORCH_PREMERGE_REBASE_ALWAYS`).
|
||||
- Контейнеризация: Docker + Compose
|
||||
- CI/CD: Gitea Actions (`.gitea/workflows/`)
|
||||
- Деплой: docker compose на mva154
|
||||
@@ -41,285 +41,42 @@ created → analysis → architecture → development → review → testing →
|
||||
## Статусная модель Plane (ORCH-066) — индикация ≠ управление
|
||||
Статусы Plane — это **слой B (индикация)**, отдельный от **слоя A (машина стадий)** `src/stages.py::STAGE_TRANSITIONS`. Plane показывает наблюдателю осмысленную картину (`Backlog → Todo → Analysis → Architecture → Development → Code-Review → Testing → Awaiting Deploy → Deploying → Monitoring after Deploy → Done` + человеческие гейты `In Review/Approved`, `Confirm Deploy`), но НИКОГДА не управляет конвейером. Маппинг и сеттеры — `src/plane_sync.py` (6 новых ключей: `to_analyse/analysis/code_review/awaiting_deploy/deploying/monitoring`), с project-relative alias-fallback: на частично сконфигурированном проекте новый ключ деградирует на базовый UUID ТОГО ЖЕ проекта (нулевая регрессия для enduro-trails). Детали — `docs/architecture/README.md`.
|
||||
|
||||
**Terminal-window-aware гард deploy-статусов (ORCH-094).** Задача с БД `stage=done` и 0 активных job'ов стабильно держит Plane=`Done`: три deploy-фазовых сеттера (`set_issue_awaiting_deploy`/`set_issue_deploying`/`set_issue_monitoring`) были терминал-слепы и флаппили `Awaiting ⟷ Monitoring` (верифицировано на ORCH-061, task 47), т.к. любой стейл/двойной/неизвестный вызов под бот-токеном перезаписывал терминал промежуточным статусом. Новый leaf `src/deploy_status_guard.py` (чистая, never-raise, config-gated; по образцу `serial_gate`/`labels`/`cancel`) — `decide(work_item_id, target, reason) -> ALLOW | CONVERGE_DONE | SUPPRESS` на **входе** трёх сеттеров `plane_sync` (низкий чокпоинт ловит любой путь, включая неизвестный актор). Инвариант: deploy-статус легитимен ⇔ задача **нетерминальна** ИЛИ (`done` И активно пост-деплой-окно `post_deploy.window_active` = ARMED & не DONE); иначе для `done` — идемпотентное `CONVERGE_DONE` (сеттер зовёт `set_issue_done`), для `cancelled` — `SUPPRESS`. Чтобы легитимный первый `Monitoring` (БД уже `done` к моменту стр. 404) прошёл, арм-блок `post_deploy.arm_monitor` **перенесён выше** terminal-sync-блока в `advance_stage` (ADR-001 D3) → `window_active==True` до выставления `Monitoring`. Монитор-тик при БД `cancelled` мид-окно → закрыть окно без статус-PATCH (zombie-tick guard, FR-3). Наблюдаемость: BC-kwarg `reason` у трёх сеттеров + одна структурная лог-запись на вердикт (`work_item`/`caller`/`target`/`db_stage`/`window_active`/`verdict`; converge/suppress → WARNING). Read-only аксессор `db.get_task_by_work_item_id`. Флаги `deploy_status_guard_enabled` (kill-switch; `False` → 1:1 прежнее) / `deploy_status_guard_repos` (CSV; **пусто → self-hosting only**, enduro не затронут). `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict/схема БД — не тронуты. Детали — `docs/work-items/ORCH-094/06-adr/ADR-001-terminal-window-aware-deploy-status-guard.md`, сквозной `docs/architecture/adr/adr-0028-terminal-window-aware-deploy-status-guard.md`.
|
||||
|
||||
## Нотификации / Telegram live-tracker (ORCH-042/066/067/087)
|
||||
## Нотификации / Telegram live-tracker (ORCH-042/066/067)
|
||||
Каждая задача = **одна карточка** в Telegram (`src/notifications.py`). Поведение карточки:
|
||||
- **Дефолт `tracker_mode` — `bump`** (ORCH-067; `edit` доступен через `ORCH_TRACKER_MODE=edit`).
|
||||
`bump` на каждом обновлении удаляет старую карточку и шлёт свежую вниз чата (тихо), `edit`
|
||||
редактирует на месте. Инвариант «одна карточка на задачу» — в обоих режимах.
|
||||
- **Зачистка сирот (ORCH-087):** bump ведёт авторитетный леджер ВСЕХ созданных карточек
|
||||
(таблица `tracker_messages`, `deleted_at IS NULL` = жива) и на каждом обновлении удаляет
|
||||
ВСЕ незакрытые mid, а не только скаляр `tracker_message_id` (он сохранён как указатель на
|
||||
текущую карточку, BC). Это устраняет класс «замёрзшая сирота» (старая карточка с заголовком
|
||||
ранней стадии, потерявшая ссылку при гонке/`delete`-fail+`send`-ok). Новый mid пишется в
|
||||
леджер ТОЛЬКО при успешном `send` (BR-6); transient-`delete` остаётся незакрытым для ретрая;
|
||||
«already gone»/>48ч (`_DELETE_GONE_MARKERS`) → закрывается. Остаточная гонка самозалечивается
|
||||
за один bump. Known-limitation: Telegram 48ч (сироты старше неудаляемы).
|
||||
- **Эффорт в строке стадии (ORCH-087):** колонка `agent_runs.effort` стампится фактическим
|
||||
`resolve_agent_effort` в `launcher._spawn` (CLI его в result-JSON не возвращает); строка
|
||||
рендерится `· {model} · {effort}` (developer=`xhigh`, tester/deployer=`medium`, прочие=`high`);
|
||||
пустой/исторический effort → суффикс опускается.
|
||||
- **Честное итоговое время (ORCH-087):** done-строка = три независимых подписанных метрики
|
||||
`⏱️ Агенты {Σ agent_runs} · твоё {review~cap} · общее с ожиданием {wall}` (раньше `Всего {wall}`
|
||||
читалось как сумма, которой не является). «Твоё» ограничено `tracker_brd_review_cap_s`
|
||||
(`ORCH_TRACKER_BRD_REVIEW_CAP_S`, дефолт 2ч; маркер `~` при отсечке аномального застоя).
|
||||
- **Статус-строка карточки** (`📍 <status_label>`) показывает текущий Plane-статус по модели
|
||||
ORCH-066 (`plane_status_label`). Оффлайн-ядро (`stage → статус`, In Review из brd-clock)
|
||||
работает всегда без сети; best-effort live-overlay (kill-switch `tracker_live_status`,
|
||||
TTL-кэш, короткий таймаут) лишь дорисовывает ветки, неотличимые offline (Needs Input /
|
||||
Blocked / Rejected / Cancelled / **Confirm Deploy** / Deploying / Monitoring) и **никогда не
|
||||
блокирует конвейер**.
|
||||
Blocked / Rejected / Cancelled / Deploying / Monitoring) и **никогда не блокирует конвейер**.
|
||||
- **Кликабельный номер задачи** (`plane_issue_link`) — `ORCH-NNN` в карточке И во всех
|
||||
уведомлениях (`notify_*`, alert'ы стадий) рендерится как `<a href=…>` на issue в Plane;
|
||||
fail-safe → просто `html.escape(номер)`, если ссылку построить нельзя. Никогда не падает.
|
||||
- **Без link-preview (ORCH-080):** оба примитива (`send_telegram`/`edit_telegram`) шлют
|
||||
payload с `disable_web_page_preview: True` — баннер Plane («Modern project management»)
|
||||
под кликабельной ссылкой `ORCH-NNN` больше не разворачивается ни в карточке (`bump`/`edit`),
|
||||
ни в notify/alert-сообщениях. `parse_mode: HTML` сохранён → ссылка остаётся кликабельной.
|
||||
- Транспорт (`send_telegram`/`edit_telegram`/`delete_telegram`), `disable_notification`
|
||||
(карточка тихая, пингуют только alert-хелперы), схема БД — не трогаются.
|
||||
|
||||
## Авто-режим по лейблам: autoApprove + autoDeploy (ORCH-089)
|
||||
Конвейер имеет два **человеческих** гейта, тормозящих пакетный автономный прогон
|
||||
(эпик ORCH-088): гейт BRD (`analysis`: ручной `Approved`) и гейт прод-деплоя
|
||||
(`deploy` Phase A: ручной `Confirm Deploy`, ORCH-059). ORCH-089 снимает **только эти
|
||||
два человеческих решения** — выборочно (лейбл Plane на задаче), декларативно,
|
||||
обратимо, **не трогая ни одной технической проверки**. Инвариант: авто-режим снимает
|
||||
лишь ожидание человеческого сигнала; `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/схема БД
|
||||
— **не трогаются**. Аддитивно: leaf `src/labels.py` (never-raise) + две точечные врезки.
|
||||
- **`autoApprove`** → врезка в `stage_engine._handle_analysis_approved_flow` (ветка
|
||||
`files_ok`): `set_issue_approved` (индикация) + лог/Telegram/Plane-коммент +
|
||||
`advance_stage(..., finished_agent=None)` — **тот же путь, что человеческий Approved**
|
||||
(`approved-via-status` → `analysis → architecture` + `mark_brd_review_ended`).
|
||||
- **`autoDeploy`** → врезка в `stage_engine._handle_self_deploy_phase_a` после advance
|
||||
на `deploy` + `clear_state`: лог/Telegram/Plane-коммент + `_handle_self_deploy_phase_b`
|
||||
(маркер `INITIATED`, статус `Deploying`, finalizer). Пропускаются лишь
|
||||
индикативно-человеческие шаги. **BR-5 структурно:** Phase A достигается только после
|
||||
зелёных под-гейтов ребра `deploy-staging → deploy` (security → merge-gate →
|
||||
image-freshness → staging) → autoDeploy физически не деплоит сломанное.
|
||||
- **Чтение лейблов** — `plane_sync.fetch_issue_labels` (`None` при ошибке ≠ `[]`) +
|
||||
`get_project_labels` (`{normalized_name→uuid}`, TTL-кэш); сопоставление по
|
||||
нормализованному имени (`strip().casefold()`), неоднозначность → «нет лейбла».
|
||||
Источник истины — Plane API, не payload вебхука. Новый сеттер `set_issue_approved`.
|
||||
- **Флаги** (`config.py`): `auto_label_enabled` (kill-switch), `auto_approve_label`/
|
||||
`auto_deploy_label`, `auto_label_repos` (CSV; **пусто → self-hosting only**),
|
||||
`auto_label_states_ttl_s`. `applies(repo)` (локальный) проверяется ПЕРВЫМ; `has_label`
|
||||
(сеть) — только при `applies==True` → при выключенном флаге нулевой сетевой оверхед.
|
||||
- **Fail-safe (never auto):** любая ошибка/недоступность Plane/неоднозначность →
|
||||
«нет авто» → ручной гейт (never-raise). Прозрачность: лог + Telegram + Plane-коммент +
|
||||
live-карточка; блок `auto_labels` в `GET /queue`. **Инфра-предусловие:** создать лейблы
|
||||
`autoApprove`/`autoDeploy` в Plane-проекте ORCH (их отсутствие = ручной режим, fail-safe).
|
||||
Детали — `docs/work-items/ORCH-089/06-adr/ADR-001-auto-label-gates.md`,
|
||||
`docs/architecture/adr/adr-0018-auto-label-gates.md`.
|
||||
|
||||
## Отмена задачи: статус STOP (ORCH-090)
|
||||
Выделенный Plane-статус **STOP** — операторская кнопка «отменить + сбросить» задачу. Вводит
|
||||
**новое системное терминальное состояние `cancelled`** (стадия `tasks.stage='cancelled'` + job-исход
|
||||
`jobs.status='cancelled'`), равноправное `done`. Логический ключ `stop` — **fail-closed** (нет в
|
||||
`_DEFAULT_STATES`, по образцу `confirm_deploy`/ORCH-059): доска без статуса STOP → ветка не
|
||||
активируется. Маршрут `handle_issue_updated → handle_stop → stage_engine.cancel_task`:
|
||||
- **Полный сброс** (вне критичного окна): graceful SIGTERM активного агента (`launcher.stop_process`,
|
||||
переиспользует каскад `_watchdog`), все job'ы → терминальный `cancelled` (не реквью'ятся:
|
||||
`claim_next_job` берёт только `queued`, reaper/worker сверяют терминал задачи — TR-2), удаление
|
||||
worktree + **рабочей** Gitea-ветки (`gitea.delete_remote_branch`, **никогда** `main`, без
|
||||
force-push), durable `stage='cancelled'` + **тумбстон** натуральных ключей (`plane_id`/
|
||||
`work_item_id`/`plane_issue_id` → суффикс `#cancelled-<id>`; ADR-001 D4 уточнён: тумбстонится и
|
||||
`plane_issue_id`, т.к. `get_task_by_plane_id`/`create_task_atomic` матчат по нему — иначе re-create
|
||||
коллизирует; исходный UUID парсится из суффикса для аудита). Docs-артефакты (`01..17`) сохраняются.
|
||||
- **STOP в критичном окне merge/deploy** (ADR-001 D7): `cancel.in_critical_window` → **отложенная**
|
||||
отмена: `tasks.cancel_requested_at`, снимаются только `queued` job'ы (running-актор деплоя/мержа не
|
||||
трогается), алерт; детерминированный finalizer (`run_deploy_finalizer`) доводит необратимый шаг до
|
||||
честного исхода и применяет отмену (`force=True`). «Критичное окно» = реально начатый необратимый
|
||||
шаг: INITIATED-sentinel self-deploy (ORCH-036; детач-деплой + поздний `merge_pr` в
|
||||
`_handle_merge_verify` идут под тем же маркером) **либо** держание merge-lease (ORCH-043) **И**
|
||||
активно бегущий актор (running-job). **Уточнение P1 (ORCH-090 review):** держание merge-lease в
|
||||
Phase A на стадии `deploy` в ожидании ручного `Confirm Deploy` БЕЗ бегущего актора **полностью
|
||||
обратимо** (ничего не смержено/задеплоено) → НЕ критично → немедленный полный сброс (сам отпускает
|
||||
lease). Иначе отмена откладывалась бы к finalizer'у, который оператор (нажавший STOP именно чтобы НЕ
|
||||
подтверждать деплой) не запускает — задача застревала бы с удержанным lease, клиня serial-gate репо.
|
||||
STOP **никогда** не трогает `main`/force-push/прод-контейнер/detached-процесс (NFR-3).
|
||||
- **Кросс-каттинг (adr-0026):** предикат «задача терминальна» расширен `{done}` → `{done, cancelled}`
|
||||
в `serial_gate`/`task_deps`/`stages.py`-сток (иначе отменённая задача заклинит очередь репо);
|
||||
reconciler-терминал-скип уже знал `cancelled` (ORCH-086). `STAGE_TRANSITIONS` exit-гейты рёбер /
|
||||
`QG_CHECKS` / `check_*` — **не тронуты** (`cancelled` — сток, не ребро).
|
||||
- **Дыра релонча закрыта (D6):** relaunch агента в `handle_status_start` ограничен стадией `analysis`
|
||||
(единственный владелец Needs Input, ORCH-066); ручной перевод существующей задачи в иной промежуточный
|
||||
статус больше не релончит середину пайплайна. Запуск пайплайна — только «To Analyse» → `start_pipeline`.
|
||||
- Флаги `stop_status_enabled` (kill-switch; `False` → всё инертно, нулевая регрессия) / `stop_status_repos`
|
||||
(CSV; пусто → все репо). Leaf `src/cancel.py` (never-raise). Read-only блок `stop` в `GET /queue`.
|
||||
Аддитивные колонки `tasks.cancelled_at`/`cancel_requested_at` (`_ensure_column`). **Инфра-предусловие:**
|
||||
создать статус **STOP** с группой `cancelled` на доске ORCH (его отсутствие = fail-safe no-op). Детали —
|
||||
`docs/work-items/ORCH-090/06-adr/ADR-001-stop-cancel-task.md`,
|
||||
`docs/architecture/adr/adr-0026-stop-cancel-task.md`.
|
||||
|
||||
## Багфикс-трек: дешёвый маршрут для багов (ORCH-019)
|
||||
Задача с меткой Plane `Bug` идёт **укороченным маршрутом** — пропускается стадия `architecture`
|
||||
(отдельный прогон opus-агента `architect` + ADR + exit-гейт `check_architecture_done`); тяжёлая
|
||||
аналитика заменяется облегчённым пакетом (короткий bug-report + обязательный план регресс-теста,
|
||||
но всё равно все 4 файла analysis — гейт `check_analysis_complete` не меняется). **Корневой
|
||||
инвариант (NFR-1):** срезается ТОЛЬКО аналитика/архитектура — **все Quality Gate'ы и под-гейты
|
||||
исполняются без изменений** (`STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / machine-verdict ключи —
|
||||
байт-в-байт прежние); маршрутизация багфикса — свойство планировщика, **не** гейт. Аддитивно, под
|
||||
kill-switch, never-raise, fail-safe → полный цикл.
|
||||
- **Классификация (D1):** leaf `src/bug_fast_track.py` (never-raise, образец `labels`/`serial_gate`).
|
||||
`bug_fast_track_applies(repo)` (локально, без сети) ПЕРВЫМ → выключенный флаг = нулевой сетевой
|
||||
оверхед; `is_bug_task` делегирует в `labels.has_label` (ORCH-089-аппарат, источник истины — Plane
|
||||
API, не payload). Чтение метки — только в `start_pipeline`, **никогда** в горячем `claim_next_job`
|
||||
(NFR-4).
|
||||
- **Хранение типа (D2):** аддитивная идемпотентная колонка `tasks.track TEXT DEFAULT 'full'`
|
||||
(`_ensure_column`, паттерн `tasks.cancelled_at`); значения `'full'` (дефолт, ВСЕ существующие и
|
||||
не-баг задачи) | `'bug'`. Хелперы `db.set_task_track`/`get_task_track` (отсутствие/NULL → `'full'`,
|
||||
fail-safe). Читается в `advance_stage` из БД, не из сети.
|
||||
- **Routing-override (D3):** врезка в `advance_stage` на ребре выхода из `analysis`: при `track='bug'`
|
||||
(чистый предикат `bug_fast_track.skips_architecture`) `next_stage` → `development`, `next_agent` →
|
||||
`developer` (минуя `architect`). `STAGE_TRANSITIONS`/`get_next_stage`/`get_agent_for_stage` — чистые,
|
||||
1:1. Стамп `mark_brd_review_ended` расширен на `analysis → development` (честная метрика ORCH-087).
|
||||
- **Эскалация (D5):** `POST /bug-fast-track/escalate?work_item=<id>` сбрасывает `track` `'bug'→'full'`
|
||||
→ следующий переход уходит в `architecture` (полный цикл). Плюс self-escalate мини-аналитика
|
||||
(«баг сложный → полный пакет + `escalate: full-cycle`»).
|
||||
- **Флаги** (`config.py`): `bug_fast_track_enabled` (kill-switch, env `ORCH_BUG_FAST_TRACK_ENABLED`),
|
||||
`bug_fast_track_label` (дефолт `Bug`), `bug_fast_track_repos` (CSV; **пусто → self-hosting only**).
|
||||
`False`/неприменимый репо → старт и маршрут байт-в-байт прежние (нулевая регрессия для enduro и
|
||||
orchestrator). Наблюдаемость — read-only блок `bug_fast_track` в `GET /queue` (флаг/метка/область +
|
||||
счётчик багфикс-задач + метрика пропущенных стадий `architecture`) + отметка `🐞` в Telegram-карточке
|
||||
(never-raise). Композиция: багфикс-задача — обычная задача репо для serial-gate (ORCH-088, не
|
||||
обходит его); `autoApprove`/`autoDeploy` (ORCH-089), coverage-gate (ORCH-027, союзник BR-4),
|
||||
merge-gate (ORCH-043) — штатно. **Инфра-предусловие:** создать метку **`Bug`** в Plane-проекте ORCH
|
||||
(её отсутствие = fail-safe полный цикл). Детали —
|
||||
`docs/work-items/ORCH-019/06-adr/ADR-001-bug-fast-track.md`,
|
||||
`docs/architecture/adr/adr-0032-bug-fast-track.md`.
|
||||
|
||||
## Гейт покрытия тестами (ORCH-027)
|
||||
Существующие тестовые гейты (`check_ci_green`, `check_tests_passed`, merge-gate re-test) судят
|
||||
только по **факту** прохождения, не по **полноте** — ни один не замечает «300 строк кода, 0
|
||||
тестов», и при пакетном автономном прогоне (ORCH-088) покрытие монотонно деградирует. Введён
|
||||
**детерминированный (без LLM) под-гейт ребра `deploy-staging → deploy`** по образцу security-гейта
|
||||
(ORCH-022): leaf `src/coverage_gate.py` (never-raise) + тонкая обёртка `check_coverage_gate` в
|
||||
`QG_CHECKS` + врезка `_handle_coverage_gate` в `advance_stage`. **Инвариант:** `STAGE_TRANSITIONS` /
|
||||
семантика существующих `check_*` / machine-verdict ключи (`verdict:`/`result:`/`deploy_status:`/
|
||||
`staging_status:`/`security_status:`) — байт-в-байт прежние; новая БД-таблица аддитивна (NFR-5).
|
||||
- **Точка/порядок:** **ПОСЛЕ merge-gate** (покрытие меряется на догнанном `auto_rebase_onto_main`
|
||||
HEAD — ровно том коде, что landed в `main`) и **ДО image-freshness** (фейл до дорогого
|
||||
docker-rebuild). Порядок под-гейтов: **security → merge → coverage → image-freshness.** FAIL →
|
||||
штатный откат на `development` (+ инкремент developer-retry, cap `MAX_DEVELOPER_RETRIES`) **и
|
||||
освобождение merge-lease** (merge-gate держал его на своём PASS — зеркало image-freshness rollback).
|
||||
- **Измерение:** `python -m pytest tests/ --cov=src --cov-report=json` в изолированном per-branch
|
||||
worktree (`ensure_worktree`); метрика — `totals.percent_covered` (line coverage `src/`). Измеритель
|
||||
за `measure_coverage(repo, branch) -> float | None` (стек-расширяемость BR-6). Тайм-аут
|
||||
`coverage_run_timeout_s`. Новая pip-зависимость `pytest-cov`.
|
||||
- **Решение — чистая функция** `compute_coverage_verdict(measured, baseline, floor, policy, epsilon)
|
||||
-> (ok, reason)`: `absolute` → `measured ≥ floor−ε`; `baseline` → `measured ≥ baseline−ε`; `both`
|
||||
(дефолт) → оба; `baseline is None` (bootstrap) → baseline-условие не применяется. `epsilon` —
|
||||
допуск на шум измерения (анти-флап у границы).
|
||||
- **Базовая линия — аддитивная БД-таблица** `coverage_baseline(repo PK, coverage, source_sha,
|
||||
updated_at)` (`CREATE TABLE IF NOT EXISTS`; хелперы `db.get_coverage_baseline`/
|
||||
`ratchet_coverage_baseline`/`set_coverage_baseline`). Наращивание **только вверх** в choke-point
|
||||
подтверждённого merge `_handle_merge_verify` (ребро `deploy → done`): `ratchet_baseline_on_merge`
|
||||
читает измеренное из `18-coverage-report.md` (single source of truth), атомарный compare-and-set
|
||||
`UPDATE … WHERE coverage <= measured` под держимым merge-lease (ORCH-043) → базовая линия не падает
|
||||
даже при гонке; bootstrap засевается первым применимым merge.
|
||||
- **Условность (как ORCH-22/43/58):** `coverage_gate_enabled` (kill-switch; `False` → 1:1 как до
|
||||
ORCH-027) + `coverage_gate_repos` (CSV; **пусто → self-hosting only** `is_self_hosting_repo` →
|
||||
enduro не затронут, no-op `(True, "N/A")`); `applies(repo)` (локально) ПЕРВЫМ — дорогой прогон
|
||||
только при `applies==True`. Ошибка инструмента/непарсимая метрика → **fail-open + WARNING** по
|
||||
умолчанию (`coverage_tool_fail_closed=False`, анти-петля); флаг → fail-closed.
|
||||
- **Артефакт `18-coverage-report.md`** (frontmatter `coverage_status: PASS|FAIL` +
|
||||
`measured_coverage`/`baseline`/`floor`/`policy`/`epsilon`/`delta`), вердикт читается ТОЛЬКО из
|
||||
frontmatter через `src/frontmatter.py` (single source of truth, как `security_status:`).
|
||||
Наблюдаемость — read-only блок `coverage` в `GET /queue`; при FAIL — `send_telegram` с кликабельным
|
||||
номером, измеренным/порогом/дельтой; опциональный ручной override `POST /coverage/baseline`.
|
||||
Флаги `ORCH_COVERAGE_*` (`MIN_PERCENT`/`POLICY`/`EPSILON`/`TOOL_FAIL_CLOSED`/`RUN_TIMEOUT_S`).
|
||||
Self-hosting-безопасно: гейт только мерит/читает/пишет/решает — не деплоит/не рестартит прод/не
|
||||
пушит `main`. **Инфра-предусловие:** `pytest-cov` в прод/staging-образе. Детали —
|
||||
`docs/work-items/ORCH-027/06-adr/ADR-001-coverage-gate.md`,
|
||||
`docs/architecture/adr/adr-0029-coverage-gate.md`.
|
||||
|
||||
## Машинный журнал уроков (ORCH-098)
|
||||
Шаг 1 («Фундамент», F2) эпика саморазвития: формализует свободнотекстовые «уроки» из `memory/` в
|
||||
**машинную структурированную таблицу отклонений конвейера** `lessons`, фундамент для будущих
|
||||
ретроспективщика (E2), приоритизатора RICE (E3) и Стрим. Чистый **observer-leaf** `src/lessons.py`
|
||||
(never-raise, kill-switch, паттерн `serial_gate`/`coverage_gate`/`metrics`): `record()`/`get()`/
|
||||
`update()`/`snapshot()`. **Инвариант:** журнал — наблюдатель, **не** Quality Gate; запись урока
|
||||
никогда не влияет на продвижение по стадиям — `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/
|
||||
machine-verdict/схемы существующих таблиц байт-в-байт не тронуты.
|
||||
- **Таблица (D1):** аддитивная идемпотентная `lessons` (`CREATE TABLE IF NOT EXISTS` в `init_db()`,
|
||||
три индекса) — контекст (`work_item_id`/`task_id`/`stage`/`agent`/`repo`), анализ (`root_cause`/
|
||||
`suggestion`), статус (`status`/`related_task`), **атрибуция сразу и нуллабельно** (`attribution`/
|
||||
`target_repo`/`target_domain`, требование Славы 10.06 / NFR-6, заполняется позже через update;
|
||||
`_ensure_column` форвард-safe на старой таблице) + `source`/`detail`. Без `enum`-констрейнтов —
|
||||
значения суть forward-compatible слаги. Хелперы `db.record_lesson`/`get_lessons`/`update_lesson`/
|
||||
`lessons_snapshot`/`lessons_recent_dup_exists`.
|
||||
- **НЕ скоупится по репо (D2):** в отличие от гейт-leaf'ов (`serial_gate`/`coverage_gate` имеют
|
||||
`*_repos`, т.к. *действуют* на репо), журнал observer-only → единственный регулятор — глобальный
|
||||
kill-switch `lessons_enabled` (env `ORCH_LESSONS_ENABLED`, дефолт `True`); **`lessons_repos` НЕ
|
||||
вводится**. Recorder пишет уроки про **любой** репо (включая enduro-trails — урок ценен для петли);
|
||||
репо-разрез — на **выборке** (`get(repo=…)`). enduro не затронут (общая БД, аддитивная таблица).
|
||||
- **Автозапись 4 типов (D3):** тонкие best-effort врезки (`source="auto"`, never-raise, дедуп) —
|
||||
`gate_failure` (`stage_engine._handle_qg_failure_rollbacks`, откат на `development`), `merge_hold`
|
||||
(`stage_engine._handle_merge_verify` HOLD-ветка), `transient_retry` (`launcher._finalize_transient`
|
||||
на **исчерпании** бюджета ретраев, а не на каждом backoff), `deploy_degraded` (post-deploy
|
||||
`DEGRADED → set_repo_freeze`, урок слоя-3 «деплой OK / прод сломан» ET-8 — `attribution="unknown"`,
|
||||
классифицируется позже).
|
||||
- **Дедуп (D4):** для `source="auto"` — один indexed-SELECT по `idx_lessons_wi_type`: дубль с тем же
|
||||
`(work_item_id, lesson_type, stage)` в окне `lessons_dedup_window_s` (env, дефолт 3600с) → no-op.
|
||||
`source="manual"` дедуп НЕ проходит (оператор/Стрим всегда пишут).
|
||||
- **Эндпоинты (D5):** `GET /lessons` (read-only, фильтры `type`/`status`/`repo`/`work_item`/`limit`),
|
||||
`POST /lessons` (ручная запись, `source="manual"`), `POST /lessons/{id}` (доклассификация/update);
|
||||
read-only ключ `lessons` в `GET /queue`. Выключенный флаг → `{"enabled": false}`.
|
||||
- **never-raise (NFR-1):** все публичные функции и врезки изолированы (`try/except` → warning +
|
||||
безопасный дефолт) — сбой журнала не роняет конвейер. Self-hosting-безопасно: только читает/пишет
|
||||
свою таблицу, не деплоит/не рестартит прод/не трогает `main`/без процессов/сети. Детали —
|
||||
`docs/work-items/ORCH-098/06-adr/ADR-001-lessons-journal.md`,
|
||||
`docs/architecture/adr/adr-0034-lessons-journal.md`.
|
||||
|
||||
## Turnkey-онбординг проектов (ORCH-009)
|
||||
Операторская способность развернуть **новый** проект одним проходом — **вне рантайма и вне
|
||||
конвейера** (`src/**` байт-в-байт, kill-switch не нужен: активация — только явный запуск CLI
|
||||
человеком). Три артефакта: **kit** `onboarding/repo-skeleton/` (параметризуемый каркас нового репо:
|
||||
6 промптов канона 52d/92 — 5 ru + deployer en, паспорт `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`,
|
||||
скелет `docs/` с обязательным `operations/INFRA.md`; плейсхолдеры `{{NAME}}`, словарь —
|
||||
`onboarding/placeholders.json`; **канон не форкается**: `docs/_templates/`+`docs/_standards/`
|
||||
копируются live из чекаута в момент материализации); **CLI** `scripts/onboard_project.py`
|
||||
(`plan` — дефолт, GET-only / `apply` — идемпотентный ensure без delete / `verify`): Plane-проект +
|
||||
22 статуса с точными именами (read-only импорт `plane_sync._PLANE_NAME_TO_KEY`; группы фиксированы
|
||||
ADR: `STOP`→`cancelled`, терминальные группы только Done/Cancelled/STOP) + лейблы
|
||||
`autoApprove`/`autoDeploy`/`Bug` → Gitea-репо + per-repo webhook (переиспользует глобальный
|
||||
`ORCH_GITEA_WEBHOOK_SECRET`) → материализация kit + initial push **только** в свежесозданный пустой
|
||||
репо → merged-вывод `ORCH_PROJECTS_JSON` (round-trip через фактический `_parse_projects_json`);
|
||||
скрипт никогда не рестартит прод / не правит `.env` / ничего не удаляет; недоступное в Plane CE
|
||||
API → `manual-step` (fail-safe); **runbook** `docs/operations/ONBOARDING.md` (ручные шаги: env +
|
||||
управляемый рестарт; smoke — на staging 8501). Анти-дрейф — структурные тесты
|
||||
`tests/test_onboarding_{kit,script,invariants}.py`. Детали —
|
||||
`docs/work-items/ORCH-009/06-adr/ADR-001-turnkey-onboarding-kit-and-cli.md`, сквозной
|
||||
`docs/architecture/adr/adr-0035-turnkey-project-onboarding.md`.
|
||||
|
||||
## Конвенции
|
||||
- Conventional Commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`)
|
||||
- Ветки: `feature/ORCH-NNN-slug`, `fix/ORCH-NNN-slug`
|
||||
- ADR per work-item: `docs/work-items/<plane-id>/06-adr/ADR-NNN-slug.md`
|
||||
- Global ADR (сквозные решения): `docs/architecture/adr/adr-NNNN-slug.md`
|
||||
- Work items: `docs/work-items/<plane-id>/`
|
||||
- Машинные вердикты Quality Gate — строго YAML-frontmatter (`verdict:`, `deploy_status:`, `staging_status:`, `security_status:`), никогда проза. **ORCH-52c (ORCH-076):** парсинг frontmatter сведён к единому контракту `src/frontmatter.py` (reader `read_frontmatter_value` — BC; единый парс-примитив `parse_frontmatter`; writer `render/write_frontmatter`; валидатор схемы `validate_schema`/`REQUIRED_FIELDS` — warning-only по умолчанию, hard-fail только под kill-switch `frontmatter_validation_strict`, дефолт `False`). Пять вердикт-парсеров (`check_reviewer_verdict`, `_parse_tests_verdict`, `_parse_deploy_status`, `_parse_staging_status`, `parse_security_status`) читают через ОДНУ точку парсинга; семантика вердиктов и `STAGE_TRANSITIONS`/состав `QG_CHECKS` — 1:1. Формальная спека «стадия → обязательный выход» + обязательная frontmatter-схема — `docs/_standards/HANDOFF_PROTOCOL.md`
|
||||
- Машинные вердикты Quality Gate — строго YAML-frontmatter (`verdict:`, `deploy_status:`, `staging_status:`, `security_status:`), никогда проза
|
||||
|
||||
## Артефакты задачи (`docs/work-items/<plane-id>/`)
|
||||
`00-business-request.md`, `01-brd.md`, `02-trz.md`, `03-acceptance-criteria.md`, `04-test-plan.yaml`, `06-adr/ADR-NNN-slug.md`, `07-infra-requirements.md`, `08-data-requirements.md`, `10-tech-risks.md`, `12-review.md`, `13-test-report.md`, `14-deploy-log.md`, `15-staging-log.md`, `16-post-deploy-log.md` (post-deploy наблюдение, ORCH-021), `17-security-report.md` (security-гейт: `security_status:`/secrets/deps, ORCH-022), `18-coverage-report.md` (coverage-гейт: `coverage_status:`/measured/baseline, ORCH-027).
|
||||
|
||||
**Стандарт документов (ORCH-075, ORCH-52b):** структура каждого дока, карта «стадия→агент→документ→гейт→machine-key» и конвенция ADR-naming зафиксированы в `docs/_standards/PIPELINE_DOCS.md` (golden source); копируемые скелеты — в `docs/_templates/`. Перед написанием номерного дока бери скелет из `docs/_templates/` и не меняй имя machine-key frontmatter (регистр чувствителен — иначе гейт упадёт ложно).
|
||||
`00-business-request.md`, `01-brd.md`, `02-trz.md`, `03-acceptance-criteria.md`, `04-test-plan.yaml`, `06-adr/ADR-NNN-slug.md`, `07-infra-requirements.md`, `08-data-requirements.md`, `10-tech-risks.md`, `12-review.md`, `13-test-report.md`, `14-deploy-log.md`, `15-staging-log.md`, `16-post-deploy-log.md` (post-deploy наблюдение, ORCH-021), `17-security-report.md` (security-гейт: `security_status:`/secrets/deps, ORCH-022).
|
||||
|
||||
## Правила для агентов
|
||||
1. Перед любым действием прочесть этот файл и `docs/architecture/README.md`.
|
||||
2. **Документация = golden source наравне с кодом.** Изменил функционал → обнови доку В ТОМ ЖЕ PR. Архитектурное решение → заведи ADR (формат — `docs/_standards/PIPELINE_DOCS.md` §4). Структура номерных доков и шаблоны — `docs/_standards/PIPELINE_DOCS.md` + `docs/_templates/`. Обнови `CHANGELOG.md`.
|
||||
2. **Документация = golden source наравне с кодом.** Изменил функционал → обнови доку В ТОМ ЖЕ PR. Архитектурное решение → заведи ADR. Обнови `CHANGELOG.md`.
|
||||
3. Никогда не править артефакты других этапов.
|
||||
4. Никогда не комментировать ТЗ задним числом — если ТЗ не годится, возвращай в Анализ.
|
||||
5. Никогда не закрывать задачу самостоятельно — это делает CI / финальная стадия.
|
||||
6. **Reviewer проверяет: обновлена ли документация. Нет → REQUEST_CHANGES.** Это включает **обзорные доки** (ORCH-079, 52f — финал эпика 52): если PR закрывает пункт `README.md` «Известные ограничения», но README не обновлён → finding ≥P1 (витрина проекта не должна выдавать решённое за открытое).
|
||||
6. **Reviewer проверяет: обновлена ли документация. Нет → REQUEST_CHANGES.**
|
||||
7. Не использовать `--no-verify` без явного одобрения Owner.
|
||||
8. Секреты — только в `.env`/`.env.staging` на хосте, в гит НЕ коммитятся (канон — `.env.example`).
|
||||
9. **Трассировка маркеров (ORCH-078, ORCH-52e):** правишь строку/блок с маркером `ORCH-NNN` →
|
||||
ПЕРЕД изменением прочитай его `docs/work-items/ORCH-NNN/06-adr/` и не сломай зафиксированный
|
||||
инвариант; блок с 3+ маркерами → опирайся на сводный сквозной ADR. Стандарт маркеров (формат,
|
||||
размещение, fallback-доступ, анти-археология, каноничное правило чтения) — `docs/_standards/TRACEABILITY.md`.
|
||||
|
||||
## ⚠️ Self-hosting — оркестратор правит САМ СЕБЯ
|
||||
Задачи проекта ORCH меняют инструмент, который СЕЙЧАС работает в продакшене и обслуживает ДРУГИЕ проекты (enduro-trails) из ОДНОГО инстанса с ОБЩЕЙ БД и общей очередью.
|
||||
|
||||
88
README.md
88
README.md
@@ -29,7 +29,7 @@ created → analysis → architecture → development → review → testing →
|
||||
| created | — | — | Plane webhook (work_item.created) |
|
||||
| analysis | analyst | Файлы BRD/TRZ/AC/TestPlan | Push docs/ |
|
||||
| architecture | architect | ADR или infra-requirements | Push docs/ |
|
||||
| development | developer | check_ci_green (Gitea CI зелёный на ветке) | Auto-advance после developer |
|
||||
| development | developer | check_tests_local (орк сам гоняет `make test`) | Auto-advance после developer |
|
||||
| review | reviewer | check_reviewer_verdict (`verdict:` во frontmatter 12-review.md) | Auto-advance после reviewer |
|
||||
| testing | tester | check_tests_passed (test-report.md) | Auto-advance после tester |
|
||||
| deploy-staging | deployer | check_staging_status (15-staging-log.md) | Auto-advance после tester |
|
||||
@@ -45,7 +45,6 @@ created → analysis → architecture → development → review → testing →
|
||||
| GET | `/queue` | Очередь задач (ORCH-1): counts по статусам + max_concurrency + последние 10 jobs |
|
||||
| POST | `/webhook/plane` | Plane webhook receiver |
|
||||
| POST | `/webhook/gitea` | Gitea webhook receiver |
|
||||
| POST | `/bug-fast-track/escalate?work_item=<id>` | Эскалация багфикс-задачи в полный цикл (ORCH-019): сброс `track` `'bug'→'full'` → следующий переход уходит в `architecture` |
|
||||
|
||||
## Структура проекта
|
||||
|
||||
@@ -122,7 +121,6 @@ uvicorn src.main:app --reload --port 8500
|
||||
| `ORCH_REPOS_DIR` | Repos dir (container) | `/repos` |
|
||||
| `ORCH_HOST_REPOS_DIR` | Repos dir (host) | `/home/slin/repos` |
|
||||
| `ORCH_DB_PATH` | SQLite path | `/app/data/orchestrator.db` |
|
||||
| `ORCH_RUNS_DIR` | Базовый каталог per-run логов агентов (`<runs_dir>/{run_id}.log`, ORCH-087) | `/app/data/runs` |
|
||||
| `ORCH_MAX_CONCURRENCY` | Сколько jobs воркер запускает параллельно (ORCH-1) | `1` |
|
||||
| `ORCH_QUEUE_POLL_INTERVAL` | Период опроса очереди воркером, сек (ORCH-1) | `2.0` |
|
||||
| `ORCH_PREFLIGHT_CACHE_TTL` | Кэш preflight (CLI/net), сек (ORCH-1 resilience) | `45` |
|
||||
@@ -139,11 +137,6 @@ uvicorn src.main:app --reload --port 8500
|
||||
| `ORCH_RECONCILE_NOTIFY_UNBLOCK` | Telegram при разблокировке застрявшей задачи | `true` |
|
||||
| `ORCH_RECONCILE_SKIP_BLOCKED_ENABLED` | F-1 Guard 2 (ORCH-060): пропуск задач в Plane-статусе Blocked / Needs Input; `false` глушит только сетевой Guard 2 (Guard 1 escalated всегда активен) | `true` |
|
||||
| `ORCH_QG0_TITLE_MAX` | Верхний лимит длины заголовка QG-0 (вход `_qg0_errors`); невалидное/пустое значение → дефолт (ORCH-069) | `200` |
|
||||
| `ORCH_STOP_STATUS_ENABLED` | Kill-switch отмены задачи по Plane-статусу **STOP** + закрытия дыры релонча (ORCH-090); `false` → поведение 1:1 как до ORCH-090 | `true` |
|
||||
| `ORCH_STOP_STATUS_REPOS` | CSV область репо для STOP-отмены; пусто = все репо (ORCH-090) | `""` |
|
||||
| `ORCH_BUG_FAST_TRACK_ENABLED` | Kill-switch багфикс-трека (ORCH-019): задача с меткой Plane `Bug` пропускает стадию `architecture`; `false` → старт и маршрут 1:1 как до ORCH-019 (нулевая регрессия) | `true` |
|
||||
| `ORCH_BUG_FAST_TRACK_LABEL` | Имя метки Plane, активирующей багфикс-трек (ORCH-019) | `Bug` |
|
||||
| `ORCH_BUG_FAST_TRACK_REPOS` | CSV область репо для багфикс-трека; **пусто → self-hosting only** (`orchestrator`) — enduro подключается явным CSV (ORCH-019) | `""` |
|
||||
|
||||
## Очередь задач (ORCH-1 / F-2b)
|
||||
|
||||
@@ -160,60 +153,7 @@ Webhook-хэндлеры больше не спавнят claude-агентов
|
||||
- **Ретраи.** Упавший job (exit≠0) ретраится пока `attempts < max_attempts`,
|
||||
потом `failed` + Telegram-нотификация.
|
||||
|
||||
Статусы job: `queued → running → done | failed`; **`cancelled`** — терминальный
|
||||
исход STOP-отмены (ORCH-090), нигде не реквью'ится. Наблюдаемость — через `GET /queue`.
|
||||
|
||||
## Отмена задачи: статус STOP (ORCH-090)
|
||||
|
||||
Перевод задачи в выделенный Plane-статус **STOP** отменяет её: оркестратор
|
||||
останавливает активного агента (graceful SIGTERM-каскад), снимает все job'ы
|
||||
(терминальный `cancelled`, без авто-requeue), удаляет worktree и **рабочую**
|
||||
ветку в Gitea (**никогда** `main`, без force-push), сбрасывает прогресс в
|
||||
durable-терминал `tasks.stage='cancelled'` и тумбстонит натуральные ключи
|
||||
(`#cancelled-<id>`), чтобы повторный «To Analyse» создал задачу **с нуля**.
|
||||
Docs-артефакты (`01..17`) сохраняются. STOP во время критичного шага merge/deploy
|
||||
— **откладывается** до его честного завершения (никакого half-merge / рестарта
|
||||
прода). Параллельно закрыта «дыра релонча»: ручной перевод в промежуточный рабочий
|
||||
статус больше не релончит агента — единственный вход к запуску пайплайна остаётся
|
||||
«To Analyse» (релонч агента сменой статуса разрешён только на стадии `analysis` —
|
||||
владельце Needs Input). Всё под kill-switch `ORCH_STOP_STATUS_ENABLED`, аддитивно,
|
||||
never-raise. Наблюдаемость — блок `stop` в `GET /queue`. Деталь — `docs/work-items/
|
||||
ORCH-090/06-adr/ADR-001-stop-cancel-task.md` + сквозной
|
||||
`docs/architecture/adr/adr-0026-stop-cancel-task.md`.
|
||||
|
||||
> **Инфра-предусловие:** на доске Plane проекта ORCH создать статус **«STOP»** с
|
||||
> группой `cancelled`. До создания статуса фича в fail-safe (нет UUID → ветка STOP
|
||||
> не активируется).
|
||||
|
||||
## Багфикс-трек: дешёвый маршрут для багов (ORCH-019)
|
||||
|
||||
Задача с меткой Plane `Bug` (имя метки — `ORCH_BUG_FAST_TRACK_LABEL`, дефолт `Bug`)
|
||||
идёт **укороченным маршрутом** конвейера: `analysis(lite) → development → review →
|
||||
testing → deploy-staging → deploy → done`, т.е. **пропускается стадия `architecture`**
|
||||
(отдельный прогон opus-агента `architect` + ADR + exit-гейт `check_architecture_done`).
|
||||
Мини-аналитик выдаёт облегчённый пакет (короткий bug-report + обязательный план
|
||||
регресс-теста), но всё равно все 4 файла analysis — гейт `check_analysis_complete`
|
||||
не меняется.
|
||||
|
||||
**Корневой инвариант:** упрощается только аналитика/архитектура — **все Quality
|
||||
Gate'ы и под-гейты исполняются без изменений** (`STAGE_TRANSITIONS` / `QG_CHECKS` /
|
||||
`check_*` / machine-verdict ключи — байт-в-байт прежние). Маршрутизация багфикса —
|
||||
свойство планировщика (routing-override в `advance_stage` по `tasks.track='bug'`),
|
||||
**не** Quality Gate.
|
||||
|
||||
Классификация (`src/bug_fast_track.py`, never-raise): локальный `bug_fast_track_applies(repo)`
|
||||
ПЕРВЫМ (выключенный флаг = нулевой сетевой оверхед), затем `is_bug_task` через
|
||||
`labels.has_label` (источник истины — Plane API). Тип хранится в аддитивной колонке
|
||||
`tasks.track` (`'full'` | `'bug'`), читается в горячем пути из БД (не из сети).
|
||||
**Эскалация** сложного/архитектурного бага в полный цикл — `POST /bug-fast-track/escalate?work_item=<id>`
|
||||
(сброс `'bug'→'full'`). Всё под kill-switch `ORCH_BUG_FAST_TRACK_ENABLED`, область —
|
||||
`ORCH_BUG_FAST_TRACK_REPOS` (пусто → self-hosting only), fail-safe → полный цикл.
|
||||
Наблюдаемость — блок `bug_fast_track` в `GET /queue` + отметка `🐞` в Telegram-карточке.
|
||||
Деталь — `docs/work-items/ORCH-019/06-adr/ADR-001-bug-fast-track.md` + сквозной
|
||||
`docs/architecture/adr/adr-0032-bug-fast-track.md`.
|
||||
|
||||
> **Инфра-предусловие:** на доске Plane проекта ORCH создать метку **`Bug`**. До её
|
||||
> создания фича в fail-safe (нет метки → задача идёт полным циклом).
|
||||
Статусы job: `queued → running → done | failed`. Наблюдаемость — через `GET /queue`.
|
||||
|
||||
**Resilience-слой:** дешёвый preflight (CLI/net, кэш, без токенов) гейтит claim;
|
||||
429/overload детектится по логу (transient vs permanent), transient ретраится с
|
||||
@@ -282,7 +222,7 @@ stdout/stderr агента перенаправляются СРАЗУ в `/app/
|
||||
Gitea events роутятся по типу:
|
||||
- `push` → проверка файлов, advance architecture/development
|
||||
- `pull_request*` (wildcard) → review approved/rejected, PR merge
|
||||
- `status` → Gitea CI статус; ORCH-045: авторитетный гейт развития (`development → review`) — `check_ci_green` читает статус ветки с polling-retry (устраняет гонку «pending сразу после push»)
|
||||
- `status` → (legacy) Gitea CI; С-1: больше не authoritative, `failure` логируется на debug и не блокирует/не алертит (QG развития = локальный `check_tests_local`)
|
||||
|
||||
## Тесты
|
||||
|
||||
@@ -292,19 +232,9 @@ pytest tests/ -v
|
||||
|
||||
## Известные ограничения
|
||||
|
||||
Реально открытые ограничения (сверено с кодом, ORCH-079):
|
||||
|
||||
1. **Telegram 48h** — карточки-сироты старше 48 часов неудаляемы (лимит Telegram Bot API); зачистка сирот самозалечивает только свежие (ORCH-087).
|
||||
2. **Зависимости задач — только intra-repo (v1)** — `job_deps` выражают связи в пределах одного репозитория; кросс-репо зависимости пока не поддержаны (ORCH-026).
|
||||
3. **Пакетный автоном — Этап 1** — per-repo serial gate сериализует задачи одного репо (ORCH-088); полный пакетный автономный прогон «10–20 задач за ночь» — в развитии (эпик ORCH-088).
|
||||
|
||||
### Закрыто (история)
|
||||
|
||||
Пункты, ранее значившиеся ограничениями, закрыты кодом — оставлены как трассировка:
|
||||
|
||||
- **Single-task / shared `/repos` checkout** → git worktree per task (`ensure_worktree`) + serial-gate (ORCH-088) + task-deps (ORCH-026).
|
||||
- **In-process daemon-потоки** → персистентная очередь задач (SQLite `jobs`, `src/queue_worker.py`), restart-safe (ORCH-1).
|
||||
- **Gitea CI не настроен** → активный гейт стадии `development` — `check_ci_green` (`src/qg/checks.py`); `check_tests_local` помечен DEPRECATED.
|
||||
- **No retry on API errors** → exp-backoff + circuit breaker в `queue_worker.py` (`ORCH_BACKOFF_*` / `ORCH_BREAKER_*` / `ORCH_TRANSIENT_MAX_ATTEMPTS`) + retry-loop в `check_ci_green` (ORCH-1 resilience / ORCH-045).
|
||||
- **Plane sync — маппинг issue ID** → зрелый `src/plane_sync.py` (`find_issue_id`, `fetch_issue_sequence_id`) со статус-моделью и TTL-самозалечиванием (ORCH-010 / 066 / 068).
|
||||
- **Tester timeout — Playwright e2e** → orchestrator является pytest-сервисом (Playwright неприменим); реальный механизм — конфигурируемый watchdog (`agent_timeout_seconds`, ORCH-7).
|
||||
1. **Single-task / shared `/repos` checkout** — одновременно безопасно обрабатывается одна задача: все агенты и `check_tests_local` делают `git checkout` в одном `/repos/<repo>` → гонки при параллельных задачах. Исправление — git worktree per task (S-4, отдельно).
|
||||
2. **Plane sync** — маппинг issue ID может быть некорректным (P3, в работе)
|
||||
3. **In-process daemon-потоки** — агенты живут в потоках uvicorn; при рестарте ловит orphan-recovery. Целевое — очередь задач (F-2b)
|
||||
4. **Gitea CI не настроен** — тесты гоняет сам оркестратор локально
|
||||
3. **Tester timeout** — e2e тесты с Playwright могут занимать >25 мин на тяжёлых фичах
|
||||
4. **No retry on API errors** — httpx вызовы к Gitea/Plane без retry logic
|
||||
|
||||
@@ -38,39 +38,6 @@ services:
|
||||
group_add:
|
||||
- "999"
|
||||
|
||||
# ORCH-100 (FND/F1b): sidecar-watchdog — the monitoring brain in a SEPARATE
|
||||
# container (observer separated from observed, ADR-001 D2). Deploying it builds
|
||||
# ONLY this service — the prod `orchestrator` is NOT rebuilt/restarted.
|
||||
# * network_mode: host -> /metrics reachable at http://127.0.0.1:8500/metrics
|
||||
# and host interfaces visible for memory/disk reads.
|
||||
# * docker.sock mounted :ro AND the code is GET-only (double read-only guard).
|
||||
# * host disk paths bind-mounted :ro so shutil.disk_usage sees the host FS but
|
||||
# can never write (opt-in disk ceiling, D6).
|
||||
# * mem_limit caps the thin stdlib daemon (D2): OOM = early "sidecar grew" signal.
|
||||
# * WATCHDOG_ENABLED=false (or simply not starting the service) -> inert.
|
||||
orchestrator-watchdog:
|
||||
build:
|
||||
context: .
|
||||
dockerfile: watchdog/Dockerfile
|
||||
container_name: orchestrator-watchdog
|
||||
restart: unless-stopped
|
||||
init: true
|
||||
network_mode: host
|
||||
mem_limit: 128m
|
||||
mem_reservation: 32m
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock:ro
|
||||
- /home/slin/repos:/repos:ro
|
||||
- ./data:/app/data:ro
|
||||
# Optional env_file (required: false): a missing .env.watchdog must NOT fail
|
||||
# `docker compose up` for the prod orchestrator (self-hosting safety). Absent
|
||||
# file -> WATCHDOG_* defaults, no token -> fail-safe (logs, does not send).
|
||||
env_file:
|
||||
- path: .env.watchdog
|
||||
required: false
|
||||
group_add:
|
||||
- "999"
|
||||
|
||||
# ORCH-31: staging instance (port 8501, isolated DB).
|
||||
# Starts ONLY with: docker compose --profile staging up -d orchestrator-staging
|
||||
# Normal "docker compose up -d" does NOT start this service.
|
||||
|
||||
@@ -1,118 +0,0 @@
|
||||
# HANDOFF_PROTOCOL — формальный контракт handoff «стадия → обязательный выход»
|
||||
|
||||
> **Назначение.** Нормативная спека: что КАЖДАЯ стадия конвейера обязана оставить на выходе —
|
||||
> какие документы и какие frontmatter-ключи. Дополняет [`PIPELINE_DOCS.md`](PIPELINE_DOCS.md)
|
||||
> (карта «документ → агент → стадия → гейт → machine-key») «вертикальным» срезом по стадиям и
|
||||
> вводит **обязательную frontmatter-схему** для машинной проверки.
|
||||
>
|
||||
> **Статус истины (важно).** Источник истины поведения — **код**: `src/stages.py`
|
||||
> (`STAGE_TRANSITIONS`), `src/qg/checks.py` (`QG_CHECKS` / `check_*` / `_parse_*`),
|
||||
> `src/stage_engine.py` (врезки под-гейтов). Машинный контракт чтения/записи/валидации
|
||||
> frontmatter — `src/frontmatter.py`. Эта спека **документирует**; при расхождении первичен код
|
||||
> (правило ORCH-075).
|
||||
|
||||
Введено задачей **ORCH-076** (ORCH-52c — слой 2 эпика ORCH-52: машинный контракт). Слой 1
|
||||
(ORCH-075/52b) дал описательный стандарт документов; ORCH-52c реализовала единый машинный
|
||||
frontmatter-контракт (reader + writer + валидатор) и свела чтение пяти вердиктов к одной точке
|
||||
парсинга. Сквозной ADR: [`adr-0020-frontmatter-contract.md`](../architecture/adr/adr-0020-frontmatter-contract.md);
|
||||
детально — [`ORCH-076/06-adr/ADR-001-frontmatter-contract.md`](../work-items/ORCH-076/06-adr/ADR-001-frontmatter-contract.md).
|
||||
|
||||
---
|
||||
|
||||
## 1. Обязательная frontmatter-схема (машинный источник: `frontmatter.REQUIRED_FIELDS`)
|
||||
|
||||
Forward-looking аддитивная схема: набор полей, которые handoff-документ стадии **должен** нести
|
||||
в ведущем YAML-frontmatter. Машинный источник истины — кортеж
|
||||
[`src/frontmatter.py`](../../src/frontmatter.py) `REQUIRED_FIELDS`:
|
||||
|
||||
| Поле | Смысл |
|
||||
|------|-------|
|
||||
| `work_item` | ID задачи (`ORCH-NNN` / `ET-NNN`) — к какой задаче относится выход |
|
||||
| `stage` | стадия, на выходе которой написан документ (`analysis` … `deploy`) |
|
||||
| `author_agent` | роль-автор (`analyst` / `architect` / `developer` / `reviewer` / `tester` / `deployer`) |
|
||||
| `status` | человеко/машинно-читаемый статус выхода стадии |
|
||||
| `created_at` | дата создания артефакта (YYYY-MM-DD) |
|
||||
| `model_used` | модель агента, сгенерировавшего артефакт (`claude-…`) |
|
||||
|
||||
**Режим проверки (ORCH-52c, критично для self-hosting).** Валидатор схемы
|
||||
`frontmatter.validate_schema` / `maybe_warn_schema` по умолчанию **warning-only** и **никогда не
|
||||
влияет на boolean-вердикт ни одного гейта**: отсутствие полей логируется (`logger.warning`), но не
|
||||
роняет конвейер и не заваливает гейт. Жёсткий режим (hard-fail) зарезервирован на будущее
|
||||
(ORCH-52d) и включается ТОЛЬКО kill-switch'ем `frontmatter_validation_strict`
|
||||
(env `ORCH_FRONTMATTER_VALIDATION_STRICT`, дефолт `False`). Схема **аддитивна**: старый
|
||||
документ-вердикт без этих полей читается гейтом ровно как раньше (см. §3).
|
||||
|
||||
---
|
||||
|
||||
## 2. Контракт handoff по стадиям
|
||||
|
||||
Категории документов — как в `PIPELINE_DOCS.md` §2: **required** (всегда), **when-applicable**
|
||||
(при наличии предмета: инфра / данные / security / post-deploy — отсутствие не нарушение).
|
||||
«Machine-verdict ключ» — поле, которое exit-гейт/под-гейт ребра читает ТОЛЬКО из frontmatter
|
||||
(никогда из прозы). Набор документов/ключей/гейтов **согласован 1:1 с `PIPELINE_DOCS.md` §2–§3**.
|
||||
|
||||
| Стадия (выход) | Агент | Обязательные документы на выходе | Machine-verdict ключ (читает гейт ребра) | Гейт ребра |
|
||||
|----------------|-------|----------------------------------|------------------------------------------|------------|
|
||||
| `created` | система (`_create_initial_docs`) / заказчик | `00-business-request.md` | — (вход, не гейтится) | — |
|
||||
| `analysis` | analyst | `01-brd.md`, `02-trz.md`, `03-acceptance-criteria.md`, `04-test-plan.yaml` | — (гейт проверяет наличие файлов + Approved) | `check_analysis_approved` |
|
||||
| `architecture` | architect | `06-adr/ADR-NNN-<slug>.md` (≥1); `07-infra-requirements.md`, `08-data-requirements.md`, `10-tech-risks.md` (when-applicable/required-info) | — (гейт проверяет наличие `06-adr/` ≥1 ИЛИ `07-…`) | `check_architecture_done` |
|
||||
| `development` | developer | код + тесты в ветке (артефакт-док не пишется; гейт — зелёный CI) | — (гейт читает CI-статус Gitea) | `check_ci_green` |
|
||||
| `review` | reviewer | `12-review.md` | `verdict:` (`APPROVED` \| `REQUEST_CHANGES`) | `check_reviewer_verdict` |
|
||||
| `testing` | tester | `13-test-report.md` | `result:` / `verdict:` / `status:` (`PASS` \| `FAIL` \| `BLOCKED`; три равноранговых, ORCH-047) | `check_tests_passed` |
|
||||
| `deploy-staging` | deployer | `15-staging-log.md` (required для self-hosting); `17-security-report.md` (security-под-гейт, when-applicable) | `staging_status:` (`SUCCESS` \| `FAILED`); `security_status:` (`PASS` \| `FAIL`) | `check_staging_status` (ребро); под-гейты ребра `deploy-staging→deploy`: `check_security_gate` → `check_branch_mergeable` → `check_staging_image_fresh` |
|
||||
| `deploy` | deployer / deploy-finalizer | `14-deploy-log.md` | `deploy_status:` (`SUCCESS` \| `FAILED`) | `check_deploy_status` |
|
||||
| `done` | — | — (терминал) | — | — |
|
||||
| пост-`done` наблюдение | post-deploy-monitor | `16-post-deploy-log.md` (when-applicable, ORCH-021) | `post_deploy_status:` (`HEALTHY` \| `DEGRADED`) — **информационный, не гейт** | — (телеметрия петли уроков / наблюдаемость) |
|
||||
|
||||
### Примечания (нормативные)
|
||||
|
||||
- **Под-гейты ребра `deploy-staging → deploy`** (`check_security_gate` → `check_branch_mergeable`
|
||||
→ `check_staging_image_fresh`) — это **врезки в `advance_stage`**, а НЕ строки
|
||||
`STAGE_TRANSITIONS`. Их порядок и условность раската не меняются этой спекой.
|
||||
- **`15-staging-log.md`** обязателен только для self-hosting репо (`orchestrator`); для прочих
|
||||
репо staging-гейт — N/A (ORCH-35), документ не требуется.
|
||||
- **`16-post-deploy-log.md`** несёт `post_deploy_status:`, но это **информационный** ключ
|
||||
(телеметрия ORCH-8 / наблюдаемость), гейтом он НЕ парсится.
|
||||
- **`09-…` / `05-…` / `11-…`** — зарезервированные/legacy номера; канон reviewer'а — `12-review.md`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Machine-verdict доки vs информационные (честный механизм проверки)
|
||||
|
||||
Полностью согласовано с `PIPELINE_DOCS.md` §3. Machine-verdict док — гейт читает ТОЛЬКО
|
||||
YAML-frontmatter (через единый `frontmatter.parse_frontmatter`), маппит ключ в вердикт; имя ключа
|
||||
чувствительно к регистру, значение парсер приводит к верхнему регистру.
|
||||
|
||||
| Документ | Machine-key | Парсер | Эффект вердикта |
|
||||
|----------|-------------|--------|-----------------|
|
||||
| `12-review.md` | `verdict:` | `check_reviewer_verdict` | `APPROVED` → дальше; `REQUEST_CHANGES` → откат на `development` |
|
||||
| `13-test-report.md` | `result:` / `verdict:` / `status:` | `_parse_tests_verdict` | `PASS` → дальше; `FAIL`/`BLOCKED` → откат (негативный токен авторитетен) |
|
||||
| `14-deploy-log.md` | `deploy_status:` | `_parse_deploy_status` | `SUCCESS` → `done`; `FAILED` → откат (БАГ-8) |
|
||||
| `15-staging-log.md` | `staging_status:` | `_parse_staging_status` | `SUCCESS` → дальше; `FAILED` → откат (self-hosting; иначе N/A) |
|
||||
| `17-security-report.md` | `security_status:` | `check_security_gate` → `parse_security_status` | `PASS` → дальше; `FAIL` → откат |
|
||||
|
||||
**Информационные доки** (гейтом НЕ парсятся): `00-business-request.md`, `08-data-requirements.md`,
|
||||
`10-tech-risks.md`, `16-post-deploy-log.md`.
|
||||
|
||||
**Аддитивность схемы (§1).** Документ-вердикт БЕЗ полей схемы из §1, но с вердикт-ключом, читается
|
||||
гейтом РОВНО как раньше: схема не участвует в вычислении вердикта при дефолтном
|
||||
`frontmatter_validation_strict=False`.
|
||||
|
||||
---
|
||||
|
||||
## 4. Единый машинный контракт — `src/frontmatter.py`
|
||||
|
||||
Все операции с frontmatter сведены в один leaf-модуль (never-raise):
|
||||
|
||||
- `read_frontmatter_value(path, key) -> str | None` — single-key reader (контракт неизменен, BC).
|
||||
- `parse_frontmatter(content) -> FrontmatterParse` — **единственная точка** парсинга YAML-frontmatter
|
||||
(`data` / `has_block` / `malformed` / `yaml_error`); пять вердикт-парсеров делегируют сюда.
|
||||
- `parse_frontmatter_dict` / `read_frontmatter` — ярлыки к распарсенному mapping.
|
||||
- `render_frontmatter` / `write_frontmatter` — writer (формат совместим с существующими парсерами).
|
||||
- `validate_schema` / `REQUIRED_FIELDS` / `maybe_warn_schema` — схема §1 (warning-only по умолчанию).
|
||||
- `strip_frontmatter` — общий хелпер тела (заменил дубли).
|
||||
- Kill-switch жёсткой валидации: `config.frontmatter_validation_strict`
|
||||
(env `ORCH_FRONTMATTER_VALIDATION_STRICT`, дефолт `False`).
|
||||
|
||||
> Перед написанием номерного дока бери скелет из [`docs/_templates/`](../_templates/) и **не меняй
|
||||
> имя machine-key frontmatter** (регистр чувствителен — иначе гейт упадёт ложно).
|
||||
@@ -1,155 +0,0 @@
|
||||
# PIPELINE_DOCS — стандарт документов конвейера (golden source структуры)
|
||||
|
||||
> **Назначение.** Единая карта «стадия → агент → документ → категория → гейт/механизм →
|
||||
> frontmatter machine-key» + конвенция ADR-naming. Это **golden source структуры** номерных
|
||||
> документов work item (`00-business-request.md` … `18-coverage-report.md`), который каждая
|
||||
> агентская роль пишет на своей стадии.
|
||||
>
|
||||
> **Статус истины (важно).** Манифест **документирует** текущее поведение гейтов, но НЕ является
|
||||
> их источником истины. Источник истины — код: `src/stages.py` (`STAGE_TRANSITIONS`),
|
||||
> `src/qg/checks.py` (`QG_CHECKS` / `check_*` / `_parse_*`), `src/stage_engine.py`. При будущей
|
||||
> правке гейта первична правка кода, манифест обновляется следом (ORCH-075 / ADR-001 §D2).
|
||||
>
|
||||
> **Копируемые скелеты** каждого документа — в каталоге [`docs/_templates/`](../_templates/):
|
||||
> «скопировал → заполнил → не угадываешь структуру/ключ».
|
||||
|
||||
Введён задачей **ORCH-075** (ORCH-52b — слой 1 эпика ORCH-52). Сквозной ADR:
|
||||
[`docs/architecture/adr/adr-0019-pipeline-docs-standard.md`](../architecture/adr/adr-0019-pipeline-docs-standard.md);
|
||||
детально — `docs/work-items/ORCH-075/06-adr/ADR-001-pipeline-docs-standard.md`.
|
||||
|
||||
---
|
||||
|
||||
## 1. Конвейер стадий (ground-truth `STAGE_TRANSITIONS`)
|
||||
|
||||
```
|
||||
created → analysis → architecture → development → review → testing → deploy-staging → deploy → done
|
||||
↑ │
|
||||
└──── REQUEST_CHANGES ──────┘ (откат на development, max 3 retries)
|
||||
```
|
||||
|
||||
Каждое ребро несёт ровно один exit-гейт (`src/stages.py`):
|
||||
`check_analysis_approved → check_architecture_done → check_ci_green → check_reviewer_verdict →
|
||||
check_tests_passed → check_staging_status → check_deploy_status`.
|
||||
|
||||
**Под-гейты ребра `deploy-staging → deploy`** (`check_security_gate` → `check_branch_mergeable` →
|
||||
`check_staging_image_fresh`) — это **врезки в `advance_stage`**, а НЕ строки `STAGE_TRANSITIONS`.
|
||||
Аналогично под-гейт ребра `deploy → done` (`_handle_merge_verify`, ORCH-071/073) — врезка, не
|
||||
зарегистрированный QG. Карта стадий о них не «лжёт»: они не являются стадиями.
|
||||
|
||||
---
|
||||
|
||||
## 2. Манифест: документ → агент → категория → стадия → гейт → machine-key
|
||||
|
||||
Категории: **required** (пишется всегда), **when-applicable** (пишется при наличии предмета:
|
||||
инфра / данные / security / post-deploy — отсутствие не нарушение), **optional** / **legacy**.
|
||||
|
||||
| Документ | Владелец-агент | Категория | Стадия написания | Гейт / механизм проверки | Frontmatter machine-key |
|
||||
|----------|----------------|-----------|------------------|--------------------------|-------------------------|
|
||||
| `00-business-request.md` | система (Plane webhook `_create_initial_docs`) / заказчик | required | `created` (инициализация) | не гейтится (вход) | — |
|
||||
| `01-brd.md` | analyst | required | `analysis` | exit-гейт `analysis→architecture` = `check_analysis_approved` (Approved + полнота файлов); helper `check_analysis_complete` (наличие `01/02/03/04`) | — |
|
||||
| `02-trz.md` | analyst | required | `analysis` | то же | — |
|
||||
| `03-acceptance-criteria.md` | analyst | required | `analysis` | то же | — |
|
||||
| `04-test-plan.yaml` | analyst | required | `analysis` | то же | — |
|
||||
| `06-adr/ADR-NNN-<slug>.md` | architect | required | `architecture` | `check_architecture_done` (наличие каталога `06-adr/` ≥1 файл ИЛИ `07-infra-requirements.md`) | — |
|
||||
| `07-infra-requirements.md` | architect | when-applicable | `architecture` | `check_architecture_done` (учитывается при наличии) | — |
|
||||
| `08-data-requirements.md` | architect | when-applicable | `architecture` | информационный (гейтом не парсится) | — |
|
||||
| `10-tech-risks.md` | architect | required | `architecture` | информационный (гейтом не парсится) | — |
|
||||
| `12-review.md` | reviewer | required | `review` | `check_reviewer_verdict` | `verdict:` (`APPROVED` \| `REQUEST_CHANGES`) |
|
||||
| `13-test-report.md` | tester | required | `testing` | `check_tests_passed` (`_parse_tests_verdict`) | `result:` / `verdict:` / `status:` (`PASS` \| `FAIL` \| `BLOCKED`; три равноранговых, ORCH-047) |
|
||||
| `14-deploy-log.md` | deployer / deploy-finalizer | required | `deploy` | `check_deploy_status` (`_parse_deploy_status`) | `deploy_status:` (`SUCCESS` \| `FAILED`) |
|
||||
| `15-staging-log.md` | deployer | required (self-hosting) | `deploy-staging` | `check_staging_status` (self-hosting; иначе N/A — ORCH-35) | `staging_status:` (`SUCCESS` \| `FAILED`) |
|
||||
| `16-post-deploy-log.md` | post-deploy-monitor | when-applicable | пост-`done` наблюдение (ORCH-021; не ребро `STAGE_TRANSITIONS`) | информационный (гейтом не парсится) | `post_deploy_status:` (`HEALTHY` \| `DEGRADED`) |
|
||||
| `17-security-report.md` | security-гейт (детерминированный, ORCH-022) | when-applicable | под-гейт ребра `deploy-staging→deploy` | `check_security_gate` (врезка в `advance_stage`) | `security_status:` (`PASS` \| `FAIL`) |
|
||||
| `18-coverage-report.md` | coverage-гейт (детерминированный, ORCH-027) | when-applicable | под-гейт ребра `deploy-staging→deploy` (ПОСЛЕ merge-gate, ДО image-freshness) | `check_coverage_gate` (врезка в `advance_stage`) | `coverage_status:` (`PASS` \| `FAIL`) |
|
||||
|
||||
### Примечания манифеста (нормативные)
|
||||
|
||||
- **Под-гейты ребра `deploy-staging→deploy`** (`check_security_gate` → `check_branch_mergeable` →
|
||||
`check_staging_image_fresh`) исполняются как врезки в `advance_stage`, а НЕ строки
|
||||
`STAGE_TRANSITIONS`. Не путать с exit-гейтами рёбер.
|
||||
- **`09-review.md`** — legacy fallback от старой нумерации; **канон — `12-review.md`**. В основную
|
||||
таблицу как канон не вносится; reviewer пишет `12-review.md`.
|
||||
- **Категория `when-applicable`** = документ пишется при наличии соответствующего предмета
|
||||
(инфра / данные / security / post-deploy). Его отсутствие — не нарушение приёмки.
|
||||
- **`05-…` / `09-…` / `11-…`** — зарезервированные/legacy номера, в текущем каноне не используются.
|
||||
|
||||
---
|
||||
|
||||
## 3. Machine-verdict доки vs информационные (честный механизм проверки)
|
||||
|
||||
**Machine-verdict доки** — гейт читает ТОЛЬКО YAML-frontmatter (никогда прозу), маппит ключ в
|
||||
вердикт. Имя ключа чувствительно к регистру; значение парсер приводит к верхнему регистру.
|
||||
|
||||
| Документ | Machine-key | Парсер (`src/qg/checks.py`) | Эффект вердикта |
|
||||
|----------|-------------|-----------------------------|-----------------|
|
||||
| `12-review.md` | `verdict:` | `check_reviewer_verdict` | `APPROVED` → дальше; `REQUEST_CHANGES` → откат на `development` |
|
||||
| `13-test-report.md` | `result:` / `verdict:` / `status:` | `_parse_tests_verdict` | `PASS` → дальше; `FAIL`/`BLOCKED` → откат |
|
||||
| `14-deploy-log.md` | `deploy_status:` | `_parse_deploy_status` | `SUCCESS` → `done`; `FAILED` → откат (БАГ-8) |
|
||||
| `15-staging-log.md` | `staging_status:` | `_parse_staging_status` | `SUCCESS` → дальше; `FAILED` → откат (self-hosting; иначе N/A) |
|
||||
| `17-security-report.md` | `security_status:` | `check_security_gate` | `PASS` → дальше; `FAIL` → откат |
|
||||
| `18-coverage-report.md` | `coverage_status:` | `check_coverage_gate` | `PASS` → дальше; `FAIL` → откат на `development` |
|
||||
|
||||
**Информационные доки** — гейтом НЕ парсятся (структура ничего не блокирует):
|
||||
`00-business-request.md` (вход), `08-data-requirements.md`, `10-tech-risks.md`,
|
||||
`16-post-deploy-log.md` (несёт `post_deploy_status:`, но это телеметрия петли уроков ORCH-8 /
|
||||
наблюдаемость, не гейт).
|
||||
|
||||
---
|
||||
|
||||
## 4. Конвенция ADR-naming
|
||||
|
||||
### Per-work-item ADR (основное)
|
||||
|
||||
- **Путь:** `docs/work-items/<plane-id>/06-adr/`
|
||||
- **Имя файла:** `ADR-NNN-<kebab-slug>.md`
|
||||
- `NNN` — 3-значный, начинается с `001`; инкремент при нескольких ADR в одной задаче
|
||||
(`ADR-001-…`, `ADR-002-…`).
|
||||
- `<kebab-slug>` — kebab-case (нижний регистр, слова через дефис), отражает суть решения.
|
||||
- **Стадия:** пишет **architect** на стадии `architecture`; гейтится `check_architecture_done`
|
||||
(наличие каталога `06-adr/` ≥ 1 файла).
|
||||
|
||||
### Сквозной (cross-cutting) ADR
|
||||
|
||||
Решения, затрагивающие несколько компонентов/ролей или поведение всего конвейера, **дублируются**
|
||||
в глобальный реестр:
|
||||
|
||||
- **Путь:** `docs/architecture/adr/`
|
||||
- **Имя файла:** `adr-NNNN-<kebab-slug>.md` (4-значная сквозная нумерация, последовательная по
|
||||
всему репозиторию; на момент ORCH-075 реестр доходит до `adr-0019`).
|
||||
|
||||
### Примеры из репозитория (реальные, проверенные)
|
||||
|
||||
- `docs/work-items/ORCH-088/06-adr/ADR-001-serial-gate.md`
|
||||
- `docs/work-items/ORCH-089/06-adr/ADR-001-auto-label-gates.md`
|
||||
- `docs/work-items/ORCH-071/06-adr/ADR-001-merge-verify-gate.md`
|
||||
- Сквозные: `docs/architecture/adr/adr-0017-serial-gate.md`,
|
||||
`docs/architecture/adr/adr-0018-auto-label-gates.md`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Как пользоваться шаблонами
|
||||
|
||||
1. Скопируй нужный скелет из [`docs/_templates/`](../_templates/) в
|
||||
`docs/work-items/<plane-id>/` под канонным именем (для ADR — `06-adr/ADR-001-<slug>.md`).
|
||||
2. Заполни секции; **не удаляй** machine-key frontmatter у machine-verdict доков и **не меняй имя
|
||||
ключа** (регистр чувствителен — иначе гейт упадёт ложно).
|
||||
3. Сверяйся с манифестом (§2–§3): какой агент, на какой стадии, какой гейт читает документ.
|
||||
|
||||
> Стандарт **описательный** (слой 1). **Машинный слой реализован в ORCH-52c (ORCH-076):** единый
|
||||
> frontmatter-контракт (reader + writer + валидатор) в [`src/frontmatter.py`](../../src/frontmatter.py)
|
||||
> и формальная спека handoff [`HANDOFF_PROTOCOL.md`](HANDOFF_PROTOCOL.md) («стадия → обязательный
|
||||
> выход» + обязательная frontmatter-схема `REQUIRED_FIELDS`). Пять вердикт-парсеров
|
||||
> (`check_reviewer_verdict`, `_parse_tests_verdict`, `_parse_deploy_status`, `_parse_staging_status`,
|
||||
> `parse_security_status`) читают вердикт через ОДНУ точку парсинга (`parse_frontmatter`); семантика
|
||||
> вердиктов 1:1. Валидатор обязательной схемы по умолчанию **warning-only** (kill-switch
|
||||
> `frontmatter_validation_strict`, дефолт `False`) — соблюдение схемы пока на ответственности агента
|
||||
> и reviewer'а, enforcement придёт с ORCH-52d.
|
||||
|
||||
---
|
||||
|
||||
## 6. Спека handoff (машинный контракт, ORCH-52c)
|
||||
|
||||
Вертикальный срез «стадия → обязательные документы + frontmatter-ключи на выходе» и обязательная
|
||||
frontmatter-схема вынесены в отдельную нормативную спеку [`HANDOFF_PROTOCOL.md`](HANDOFF_PROTOCOL.md)
|
||||
(набор документов/ключей/гейтов согласован 1:1 с §2–§3 этого манифеста). Машинный источник
|
||||
обязательной схемы — `frontmatter.REQUIRED_FIELDS`.
|
||||
@@ -1,147 +0,0 @@
|
||||
# TRACEABILITY — стандарт маркеров-трассировки `ORCH-NNN` (golden source трассировки)
|
||||
|
||||
> **Назначение.** Единый нормативный контракт: как нетривиальная строка/блок/инвариант в коде
|
||||
> привязывается к work item, который его ввёл, и к его архитектурному решению (ADR). Это **слой 4
|
||||
> (трассировка)** эпика **ORCH-52** — рядом с `PIPELINE_DOCS.md` (слой 1, структура документов) и
|
||||
> `HANDOFF_PROTOCOL.md` (слой 2, машинный frontmatter-контракт).
|
||||
>
|
||||
> **Статус истины.** Документ **кодифицирует сложившуюся практику**, а не вводит новый синтаксис.
|
||||
> Источник истины о *поведении* остаётся код (`src/stages.py`, `src/qg/checks.py`,
|
||||
> `src/stage_engine.py`); этот стандарт — описательно-нормативный, **не машинный гейт конвейера**.
|
||||
> Соблюдение держится на дисциплине агентов + оси ревью (`reviewer.md`), а не на CI-lint.
|
||||
|
||||
Введён задачей **ORCH-078** (ORCH-52e). Сквозной ADR:
|
||||
[`docs/architecture/adr/adr-0022-traceability-marker-standard.md`](../architecture/adr/adr-0022-traceability-marker-standard.md);
|
||||
детально — `docs/work-items/ORCH-078/06-adr/ADR-001-traceability-marker-standard.md`. Продолжает
|
||||
цепочку стандартов эпика 52: adr-0019 (52b), adr-0020 (52c), adr-0021 (52d).
|
||||
|
||||
---
|
||||
|
||||
## 1. Назначение и определение
|
||||
|
||||
**Маркер `ORCH-NNN`** (а для проекта enduro-trails — `ET-NNN`) в коде = обязательный стандарт
|
||||
трассировки: он привязывает нетривиальную строку / блок / инвариант к work item, который его ввёл,
|
||||
и к его ADR. Это даёт читающему агенту прямой путь «строка кода → решение, которое её породило»,
|
||||
вместо `git blame`-археологии.
|
||||
|
||||
**Факт (сверено на 2026-06-09):** в `src/` де-факто живёт **51 уникальный** маркер `ORCH-NNN`
|
||||
(`grep -rhoE 'ORCH-[0-9]+' src/ | sort -u | wc -l` → `51`) — сложившаяся практика. Этот стандарт её
|
||||
формализует. **Массовый ретро-фит существующих 51 маркера вне объёма** — стандарт нормативен «на
|
||||
будущее»: его правила применяются к **новому и правимому** коду.
|
||||
|
||||
---
|
||||
|
||||
## 2. Формат маркера
|
||||
|
||||
Маркер — это **inline-комментарий** (или фрагмент docstring модуля/функции), содержащий идентификатор
|
||||
work item `ORCH-NNN`. Рекомендуется рядом указывать ссылку на конкретное решение в ADR, чтобы трасса
|
||||
вела не просто к задаче, а к пункту решения:
|
||||
|
||||
```python
|
||||
# Ordering term — ``t2.id < jobs.task_id`` (FIFO, ORCH-088, ADR-001 D1 / FR-2): a task
|
||||
# does not enter `analysis` while an earlier unfinished task exists in the same repo.
|
||||
```
|
||||
|
||||
Нового синтаксиса не вводится — кодифицируется уже сложившийся стиль (`ORCH-NNN[, ADR-001 D1]`).
|
||||
|
||||
---
|
||||
|
||||
## 3. Где ставится маркер
|
||||
|
||||
Маркер ставится рядом с **нетривиальным инвариантом**, понимание которого требует контекста решения:
|
||||
|
||||
- выбор fail-open / fail-closed поведения;
|
||||
- точное условие сериализации / упорядочивания (FIFO, lease, барьер);
|
||||
- идемпотентность / защита от повторной обработки;
|
||||
- обходимая «дыра» конвейера, которую блок закрывает;
|
||||
- любое условие, чьё «почему именно так» зафиксировано в ADR.
|
||||
|
||||
Маркер **НЕ ставится** на тривиальном/самоочевидном коде (геттеры, простые присваивания, очевидные
|
||||
проверки) — это только зашумляет.
|
||||
|
||||
**Правило для нового кода:** вводишь значимый инвариант → ставь маркер своей задачи (`ORCH-NNN`)
|
||||
рядом, по возможности со ссылкой на пункт ADR.
|
||||
|
||||
---
|
||||
|
||||
## 4. Как читать историю (с реальным проверяемым примером)
|
||||
|
||||
Пошагово, от строки кода к решению:
|
||||
|
||||
1. Видишь в коде маркер `ORCH-NNN` у строки/блока, который собираешься менять.
|
||||
2. Открываешь его архитектурное решение: `docs/work-items/ORCH-NNN/06-adr/`.
|
||||
3. Читаешь зафиксированный инвариант ПЕРЕД правкой; не ломаешь его (см. §7).
|
||||
|
||||
**Проверяемый пример из реального кода (`main`):**
|
||||
|
||||
> `src/serial_gate.py` несёт условие сериализации `t2.id < jobs.task_id` с маркером **ORCH-088**
|
||||
> и отсылкой `ADR-001 D1 / FR-2` (FIFO-уточнение serial-gate). Чтобы понять, почему задача не входит
|
||||
> в `analysis`, пока в репо есть более ранняя незавершённая задача, читаешь:
|
||||
> `docs/work-items/ORCH-088/06-adr/ADR-001-serial-gate.md`.
|
||||
|
||||
Пример ссылается на **реально существующие** в `main` файл и ADR — иначе стандарт опровергал бы сам
|
||||
себя (нерабочая трассировка).
|
||||
|
||||
---
|
||||
|
||||
## 5. Fallback-доступ к чужому ADR
|
||||
|
||||
Папки `docs/work-items/ORCH-NNN/` может **не быть в текущей ветке** (она срезана от `main` без неё —
|
||||
типично для ветки другой задачи). Штатный способ прочитать чужой ADR — взять его из `origin/main`:
|
||||
|
||||
```bash
|
||||
git fetch origin # при необходимости заранее
|
||||
git ls-tree origin/main:docs/work-items/ORCH-NNN/06-adr/ # листинг доступных ADR
|
||||
git show origin/main:docs/work-items/ORCH-NNN/06-adr/ADR-001-<slug>.md # прочитать конкретный
|
||||
```
|
||||
|
||||
Это не блокер: отсутствие папки в ветке ≠ отсутствие решения — оно всегда есть в `main`.
|
||||
|
||||
---
|
||||
|
||||
## 6. Анти-археология: 3+ маркеров → сводный сквозной ADR
|
||||
|
||||
Если функция/блок несёт **3+** маркеров `ORCH-NNN` (эволюционировал через много задач), раскопки по
|
||||
каждому work item нечитаемы. Вместо перечисления всех задач ставится **одна сводная ссылка на
|
||||
сквозной ADR** (`docs/architecture/adr/adr-NNNN-*`), агрегирующий эволюцию.
|
||||
|
||||
Числовой порог `3` — граница, за которой inline-перечисление перестаёт быть читаемым (один-два
|
||||
маркера ещё информативны, три и больше — уже археология).
|
||||
|
||||
**Пример из кода:** `src/merge_gate.py` несёт маркеры ORCH-043/065/071/073 (и ещё несколько) →
|
||||
читать сводные сквозные `adr-0006` (merge-gate), `adr-0013` (merge-verify-gate),
|
||||
`adr-0014` (sha-source-of-truth), `adr-0016` (ensure-open-PR) в `docs/architecture/adr/`, а не 8
|
||||
отдельных work item.
|
||||
|
||||
Это конвенция для **нового/правимого** блока; массовая переразметка существующих файлов вне объёма.
|
||||
|
||||
---
|
||||
|
||||
## 7. Правило чтения (каноничная формулировка — единый источник)
|
||||
|
||||
Это **единственное** место, где живёт каноничный текст правила. Промпты агентов
|
||||
(`developer.md`/`architect.md`/`reviewer.md`) **ссылаются** на него, а не копируют — чтобы не было
|
||||
дрейфа формулировок между файлами.
|
||||
|
||||
> **Правишь код с маркером `ORCH-NNN` → прочитай его `docs/work-items/ORCH-NNN/06-adr/` ПЕРЕД
|
||||
> изменением; не сломай зафиксированный инвариант. Не можешь сохранить инвариант — эскалируй /
|
||||
> верни задачу в анализ, не правь вслепую.** Папки нет в ветке → читай из `origin/main` (§5). Блок
|
||||
> несёт 3+ маркеров → опирайся на сводный сквозной ADR (§6).
|
||||
|
||||
Кто и как применяет правило:
|
||||
|
||||
- **developer / architect** — обязаны выполнить чтение ПЕРЕД правкой маркированного кода.
|
||||
- **architect** — при введении/правке блока с 3+ маркерами оформляет/обновляет сводный сквозной ADR.
|
||||
- **reviewer** — проверяет соблюдение: правка маркированного (`ORCH-NNN`) кода без сверки с его ADR
|
||||
или со сломом инварианта → finding (рекомендуемая severity **P1**; слом критического инварианта
|
||||
конвейера — на усмотрение reviewer вплоть до P0).
|
||||
|
||||
---
|
||||
|
||||
## Связи
|
||||
|
||||
- Сквозной ADR: [`adr-0022`](../architecture/adr/adr-0022-traceability-marker-standard.md).
|
||||
- Стандарты-соседи: [`PIPELINE_DOCS.md`](PIPELINE_DOCS.md) (слой 1),
|
||||
[`HANDOFF_PROTOCOL.md`](HANDOFF_PROTOCOL.md) (слой 2).
|
||||
- Цепочка эпика 52: adr-0019 (52b) / adr-0020 (52c) / adr-0021 (52d) / adr-0022 (52e).
|
||||
- Прецедент класса ошибки (слом инварианта без чтения ADR): `docs/history/LESSONS_2026-06-08_phantom-merge.md`.
|
||||
8
docs/_templates/00-business-request.md
vendored
8
docs/_templates/00-business-request.md
vendored
@@ -1,8 +0,0 @@
|
||||
# Business Request: <краткий заголовок задачи>
|
||||
|
||||
Work Item ID: ORCH-NNN
|
||||
|
||||
## Description
|
||||
|
||||
<Что хочет заказчик/Владелец своими словами: проблема, желаемый результат, контекст.
|
||||
Допускается `TBD` на входе — analyst уточняет на стадии `analysis` и формализует в 01-brd.md.>
|
||||
34
docs/_templates/01-brd.md
vendored
34
docs/_templates/01-brd.md
vendored
@@ -1,34 +0,0 @@
|
||||
# 01 — BRD (бизнес-требования): ORCH-NNN — <название>
|
||||
|
||||
Work Item: **ORCH-NNN** · Repo: **<repo>** · Стадия: analysis
|
||||
|
||||
## 1. Бизнес-контекст и проблема
|
||||
<Зачем задача, какую боль/риск закрывает. Установленные факты — не изобретать.>
|
||||
|
||||
## 2. Объём (scope)
|
||||
|
||||
### В объёме
|
||||
- <что делаем>
|
||||
|
||||
### Вне объёма
|
||||
- <что явно НЕ делаем — чтобы исключить расползание>
|
||||
|
||||
## 3. Заинтересованные стороны
|
||||
<Кто заказчик, кого затрагивает, кто принимает результат.>
|
||||
|
||||
## 4. Бизнес-требования (BR)
|
||||
- **BR-1** — <требование, проверяемое>
|
||||
- **BR-2** — …
|
||||
|
||||
## 5. Нефункциональные требования (NFR)
|
||||
- **NFR-1** — <надёжность / совместимость / обратимость / безопасность>
|
||||
- **NFR-2** — …
|
||||
|
||||
## 6. Допущения и ограничения
|
||||
<Допущения, на которых стоит решение; внешние ограничения.>
|
||||
|
||||
## 7. Критерии успеха
|
||||
<Резюме; детальные PASS/FAIL — в 03-acceptance-criteria.md.>
|
||||
|
||||
## 8. Риски
|
||||
<Краткий перечень; детали — 10-tech-risks.md (заполняет архитектор).>
|
||||
30
docs/_templates/02-trz.md
vendored
30
docs/_templates/02-trz.md
vendored
@@ -1,30 +0,0 @@
|
||||
# 02 — ТЗ (TRZ): ORCH-NNN — <название>
|
||||
|
||||
Work Item: **ORCH-NNN** · Repo: **<repo>** · Стадия: analysis
|
||||
|
||||
> ТЗ описывает **конкретные изменения к реализации**, выведенные из BRD и фактического кода.
|
||||
> Архитектурное обоснование/решения — задача архитектора (06-adr).
|
||||
|
||||
## 1. Сводка изменения
|
||||
<Что меняется, в одном-двух абзацах.>
|
||||
|
||||
## 2. Задействованные модули / пути
|
||||
| Путь | Действие |
|
||||
|------|----------|
|
||||
| `src/<module>.py` | изменить / создать |
|
||||
|
||||
## 3. Функциональные требования
|
||||
### FR-1 — <название>
|
||||
<Поведение, контракт, инварианты. Привязать к BR.>
|
||||
|
||||
## 4. Изменения API
|
||||
<Новые/изменённые эндпоинты; либо «Нет.».>
|
||||
|
||||
## 5. Изменения схемы БД
|
||||
<Таблицы/миграции/индексы; либо «Нет.».>
|
||||
|
||||
## 6. Требования к новым/изменённым QG checks
|
||||
<Изменения `QG_CHECKS` / `check_*`; либо «Нет.».>
|
||||
|
||||
## 7. Совместимость / регресс
|
||||
<Обратная совместимость, kill-switch, область раската, обратимость.>
|
||||
31
docs/_templates/03-acceptance-criteria.md
vendored
31
docs/_templates/03-acceptance-criteria.md
vendored
@@ -1,31 +0,0 @@
|
||||
# 03 — Критерии приёмки (Acceptance Criteria): ORCH-NNN — <название>
|
||||
|
||||
Work Item: **ORCH-NNN** · Repo: **<repo>** · Стадия: analysis
|
||||
|
||||
Формат: каждый критерий имеет **PASS** (что должно быть истинно для приёмки) и **FAIL**
|
||||
(что считается провалом). Любой машинный/ручной reviewer проверяет их буквально по файлам
|
||||
репозитория.
|
||||
|
||||
---
|
||||
|
||||
## AC-1 — <краткий заголовок>
|
||||
|
||||
**Условие:** <проверяемое условие>
|
||||
- **PASS:** <что должно быть истинно>
|
||||
- **FAIL:** <что считается провалом>
|
||||
|
||||
---
|
||||
|
||||
## AC-2 — <краткий заголовок>
|
||||
|
||||
**Условие:** <…>
|
||||
- **PASS:** <…>
|
||||
- **FAIL:** <…>
|
||||
|
||||
---
|
||||
|
||||
## Сводная матрица AC ↔ FR/BR
|
||||
| AC | Покрывает |
|
||||
|----|-----------|
|
||||
| AC-1 | BR-1 / FR-1 |
|
||||
| AC-2 | BR-2 / FR-2 |
|
||||
20
docs/_templates/04-test-plan.yaml
vendored
20
docs/_templates/04-test-plan.yaml
vendored
@@ -1,20 +0,0 @@
|
||||
work_item: ORCH-NNN
|
||||
title: "<краткое название тест-плана>"
|
||||
framework: pytest
|
||||
scope: "<что покрывается тестами; что вне покрытия>"
|
||||
notes: >
|
||||
<Свободные заметки: окружение, особенности, что считается регрессом.
|
||||
Полный регресс tests/ должен оставаться зелёным.>
|
||||
|
||||
tests:
|
||||
- id: TC-01
|
||||
type: unit # unit | integration
|
||||
description: "<что проверяет тест>"
|
||||
module: tests/test_<feature>.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-02
|
||||
type: integration
|
||||
description: "<…>"
|
||||
module: tests/test_<feature>.py
|
||||
expected: PASS
|
||||
43
docs/_templates/06-adr-ADR-NNN-slug.md
vendored
43
docs/_templates/06-adr-ADR-NNN-slug.md
vendored
@@ -1,43 +0,0 @@
|
||||
# ADR-NNN: <Заголовок решения>
|
||||
|
||||
> **Шаблон ADR.** Скопируй в `docs/work-items/<plane-id>/06-adr/ADR-NNN-<kebab-slug>.md`.
|
||||
> `NNN` начинается с `001`, инкремент при нескольких ADR в задаче. `<kebab-slug>` — нижний
|
||||
> регистр, слова через дефис. Сквозное (cross-cutting) решение дополнительно дублируй в
|
||||
> `docs/architecture/adr/adr-NNNN-<kebab-slug>.md` (4-значная глобальная нумерация).
|
||||
> См. `docs/_standards/PIPELINE_DOCS.md` §4.
|
||||
|
||||
Work Item: **ORCH-NNN** — <короткое описание>
|
||||
Стадия: **architecture**
|
||||
Сквозная регистрация: **`docs/architecture/adr/adr-NNNN-<slug>.md`** (если решение
|
||||
кросс-каттинговое; иначе — «N/A, локальное решение задачи»).
|
||||
|
||||
## Статус
|
||||
Proposed <!-- Proposed | Accepted | Superseded by ADR-… -->
|
||||
|
||||
## Контекст
|
||||
<Какую проблему решаем; факты, сверенные с кодом (`src/…`); почему «как есть» не годится.>
|
||||
|
||||
## Решение
|
||||
|
||||
### Сводка
|
||||
<Суть выбранного решения в одном-двух абзацах.>
|
||||
|
||||
### D1 — <название аспекта решения>
|
||||
<Конкретное решение по аспекту, инварианты, привязка к FR/AC.>
|
||||
|
||||
### D2 — <название аспекта решения>
|
||||
<…>
|
||||
|
||||
## Альтернативы
|
||||
- **<альтернатива>** — отвергнуто: <почему>.
|
||||
|
||||
## Последствия
|
||||
- **+** <положительный эффект>
|
||||
- **−** <издержка / приятый компромисс + митигейшн>
|
||||
- **Откат:** <как полностью откатить изменение>
|
||||
|
||||
## Ссылки
|
||||
- BRD: `docs/work-items/ORCH-NNN/01-brd.md`
|
||||
- TRZ: `docs/work-items/ORCH-NNN/02-trz.md`
|
||||
- Acceptance: `docs/work-items/ORCH-NNN/03-acceptance-criteria.md`
|
||||
- Сверено по коду: `src/…`
|
||||
19
docs/_templates/07-infra-requirements.md
vendored
19
docs/_templates/07-infra-requirements.md
vendored
@@ -1,19 +0,0 @@
|
||||
# 07 — Инфра-требования: ORCH-NNN — <название>
|
||||
|
||||
Work Item: **ORCH-NNN** · Repo: **<repo>** · Стадия: architecture
|
||||
|
||||
> When-applicable. Если инфраструктура не затрагивается — оставить явные `N/A` по пунктам
|
||||
> (файл создаётся для аудитопригодности, а не из-за изменения топологии).
|
||||
|
||||
## I-1. Топология / окружения
|
||||
<Контейнеры, порты, сеть, тома, хост; либо `N/A`.>
|
||||
|
||||
## I-2. Переменные окружения / секреты
|
||||
<Новые env-переменные, изменения `.env` / `.env.example`, секреты; либо `N/A`.>
|
||||
|
||||
## I-3. Деплой / рестарт
|
||||
<Требуется ли рестарт прод-контейнера; self-hosting инвариант (не ронять прод вне staging);
|
||||
либо `N/A`.>
|
||||
|
||||
## I-4. CI/CD
|
||||
<Изменения `.gitea/workflows/`, новые тестовые шаги; либо «без изменений».>
|
||||
15
docs/_templates/08-data-requirements.md
vendored
15
docs/_templates/08-data-requirements.md
vendored
@@ -1,15 +0,0 @@
|
||||
# 08 — Требования к данным: ORCH-NNN — <название>
|
||||
|
||||
Work Item: **ORCH-NNN** · Repo: **<repo>** · Стадия: architecture
|
||||
|
||||
> When-applicable / информационный (гейтом не парсится). Если данные/схема не затрагиваются —
|
||||
> оставить явные `N/A`.
|
||||
|
||||
## Изменения схемы БД
|
||||
<Новые/изменённые таблицы, индексы, миграции (`init_db`); либо `N/A`.>
|
||||
|
||||
## Новые/изменённые сущности
|
||||
<Поля, колонки, инварианты данных; либо «Нет.».>
|
||||
|
||||
## Совместимость данных / миграции
|
||||
<Аддитивность, идемпотентность миграций, restart-safe, влияние на общую прод-БД; либо `N/A`.>
|
||||
16
docs/_templates/10-tech-risks.md
vendored
16
docs/_templates/10-tech-risks.md
vendored
@@ -1,16 +0,0 @@
|
||||
# 10 — Технические риски: ORCH-NNN — <название>
|
||||
|
||||
Work Item: **ORCH-NNN** · Repo: **<repo>** · Стадия: architecture
|
||||
|
||||
> Информационный (гейтом не парсится). Перечисляет риски реализации и их митигейшн.
|
||||
|
||||
## Реестр рисков
|
||||
|
||||
| ID | Риск | Вер. | Влия. | Митигейшн |
|
||||
|----|------|------|-------|-----------|
|
||||
| TR-1 | <описание риска> | Низ./Сред./Выс. | Низ./Сред./Выс. | <как снижаем> |
|
||||
| TR-2 | <…> | | | |
|
||||
|
||||
## Сводный вывод
|
||||
<Доминирующий класс рисков; нужна ли эскалация `arch:major-change` / возврат в анализ;
|
||||
итоговая оценка остаточного риска для прод-конвейера (self-hosting).>
|
||||
31
docs/_templates/12-review.md
vendored
31
docs/_templates/12-review.md
vendored
@@ -1,31 +0,0 @@
|
||||
---
|
||||
type: review
|
||||
work_item_id: ORCH-NNN
|
||||
verdict: APPROVED # APPROVED | REQUEST_CHANGES (machine-key — читает check_reviewer_verdict)
|
||||
version: 1
|
||||
---
|
||||
|
||||
# Review ORCH-NNN
|
||||
|
||||
> Машинный вердикт читается ТОЛЬКО из `verdict:` во frontmatter (никогда из прозы).
|
||||
> `APPROVED` → дальше по конвейеру; `REQUEST_CHANGES` → откат на `development`.
|
||||
|
||||
## Summary
|
||||
<Краткая оценка: реализовано ли по ТЗ/ADR, покрытие тестами, обновлена ли документация.>
|
||||
|
||||
## Оси проверки
|
||||
<Корректность, соответствие ADR/инвариантам, тесты, документация, совместимость/регресс.>
|
||||
|
||||
## Findings
|
||||
|
||||
### P0 — Blocker
|
||||
- (нет)
|
||||
|
||||
### P1 — Must fix
|
||||
- (нет)
|
||||
|
||||
### P2 — Should fix
|
||||
- (нет)
|
||||
|
||||
## Документация
|
||||
<Обновлена ли документация (README/CLAUDE/CHANGELOG/архитектура) в том же PR. Нет → REQUEST_CHANGES.>
|
||||
33
docs/_templates/13-test-report.md
vendored
33
docs/_templates/13-test-report.md
vendored
@@ -1,33 +0,0 @@
|
||||
---
|
||||
type: test-report
|
||||
work_item_id: ORCH-NNN
|
||||
result: PASS # PASS | FAIL | BLOCKED (machine-key — читает _parse_tests_verdict)
|
||||
---
|
||||
|
||||
# Test Report — ORCH-NNN
|
||||
|
||||
> Машинный вердикт читается ТОЛЬКО из frontmatter. Канонический ключ — `result:`; равнорангово
|
||||
> допускаются `verdict:` / `status:` (ORCH-047). Любой негативный токен (`FAIL`/`BLOCKED`) —
|
||||
> авторитетен.
|
||||
|
||||
## Окружение
|
||||
- Python: <версия>
|
||||
- pytest: <версия>
|
||||
- Дата: YYYY-MM-DD
|
||||
- Worktree: `feature/ORCH-NNN-<slug>`
|
||||
|
||||
## Результаты
|
||||
|
||||
### Полный регресс
|
||||
<`pytest tests/ -q` — итог (N passed); прод-контейнер не трогается.>
|
||||
|
||||
### Профильные сюиты
|
||||
<Целевые тесты задачи.>
|
||||
|
||||
### Сопоставление с тест-планом
|
||||
| TC ID | Описание | Тест-функция | Результат |
|
||||
|-------|----------|--------------|-----------|
|
||||
| TC-01 | <…> | test_… | PASS |
|
||||
|
||||
### Сопоставление с критериями приёмки
|
||||
<AC-1…AC-N — покрыт каким тестом / результат.>
|
||||
14
docs/_templates/14-deploy-log.md
vendored
14
docs/_templates/14-deploy-log.md
vendored
@@ -1,14 +0,0 @@
|
||||
---
|
||||
deploy_status: SUCCESS # SUCCESS | FAILED (machine-key — читает _parse_deploy_status)
|
||||
work_item: ORCH-NNN
|
||||
hook_exit_code: 0
|
||||
deployed_by: deploy-finalizer
|
||||
---
|
||||
|
||||
# Deploy log — ORCH-NNN
|
||||
|
||||
> Машинный вердикт читается ТОЛЬКО из `deploy_status:` во frontmatter.
|
||||
> `SUCCESS` → `done`; `FAILED` → откат на `development` (БАГ-8).
|
||||
|
||||
<Краткое описание деплоя: что выкачено, exit-code хука, кто/что зафиксировало вердикт
|
||||
(детерминированный finalizer Фаза C, не LLM, для self-hosting).>
|
||||
20
docs/_templates/15-staging-log.md
vendored
20
docs/_templates/15-staging-log.md
vendored
@@ -1,20 +0,0 @@
|
||||
---
|
||||
staging_status: SUCCESS # SUCCESS | FAILED (machine-key — читает _parse_staging_status)
|
||||
timestamp: YYYY-MM-DDTHH:MM:SSZ
|
||||
base_url: http://localhost:8501
|
||||
---
|
||||
|
||||
# Staging Gate Log
|
||||
|
||||
> Машинный вердикт читается ТОЛЬКО из `staging_status:` во frontmatter. Реален для self-hosting
|
||||
> (`orchestrator`); для прочих репо гейт — N/A (ORCH-35). `SUCCESS` → дальше; `FAILED` → откат.
|
||||
|
||||
Staging test suite — итог (например: «All REAL pipeline checks passed»). Запуск канонически
|
||||
внутри контейнера `orchestrator-staging` (8501).
|
||||
|
||||
## Results
|
||||
- **Block A (SMOKE)**: <…>
|
||||
- **Block B (ACCESS)**: <…>
|
||||
- **Block C (E2E)**: <…>
|
||||
|
||||
REAL failed: <none | перечень>.
|
||||
21
docs/_templates/16-post-deploy-log.md
vendored
21
docs/_templates/16-post-deploy-log.md
vendored
@@ -1,21 +0,0 @@
|
||||
---
|
||||
post_deploy_status: HEALTHY # HEALTHY | DEGRADED (информационный, гейтом НЕ парсится — телеметрия ORCH-021)
|
||||
action_taken: NONE # NONE | ALERT_ONLY | ROLLBACK_OK | ROLLBACK_FAILED
|
||||
work_item: ORCH-NNN
|
||||
window_s: 900
|
||||
checks_total: 0
|
||||
checks_failed: 0
|
||||
---
|
||||
|
||||
# Post-deploy log — ORCH-NNN
|
||||
|
||||
> Пост-`done` наблюдение прода (ORCH-021). НЕ ребро `STAGE_TRANSITIONS`, гейтом не парсится —
|
||||
> frontmatter машиночитаем для петли уроков ORCH-8 / наблюдаемости.
|
||||
|
||||
Окно наблюдения: <window_s>s; опросов всего: <checks_total>, с провалом: <checks_failed>.
|
||||
|
||||
## Серия наблюдений
|
||||
<Краткая серия сигналов health / доли 5xx; классификация HEALTHY/DEGRADED.>
|
||||
|
||||
## Решение
|
||||
<Реакция: для self-hosting всегда `ALERT_ONLY` (ручной approve, тик не откатывает прод).>
|
||||
26
docs/_templates/17-security-report.md
vendored
26
docs/_templates/17-security-report.md
vendored
@@ -1,26 +0,0 @@
|
||||
---
|
||||
security_status: PASS # PASS | FAIL (machine-key — читает check_security_gate)
|
||||
work_item: ORCH-NNN
|
||||
secrets_found: 0
|
||||
deps_blocking: 0
|
||||
deps_warning: 0
|
||||
deps_audit_degraded: false
|
||||
---
|
||||
|
||||
# Security Report — ORCH-NNN
|
||||
|
||||
> Детерминированный security-гейт (ORCH-022) — под-гейт ребра `deploy-staging→deploy` (врезка в
|
||||
> `advance_stage`, не строка `STAGE_TRANSITIONS`). Машинный вердикт читается ТОЛЬКО из
|
||||
> `security_status:`. `PASS` → дальше; `FAIL` → откат.
|
||||
|
||||
## Verdict
|
||||
<clean / blocking: N secrets, M blocking CVE(s).>
|
||||
|
||||
## Secrets
|
||||
<secret-scanning (gitleaks, offline): None | перечень.>
|
||||
|
||||
## Dependencies (blocking)
|
||||
<dependency audit (pip-audit): None | перечень блокирующих CVE.>
|
||||
|
||||
## Dependencies (warning)
|
||||
<Не блокирующие предупреждения зависимостей.>
|
||||
29
docs/_templates/18-coverage-report.md
vendored
29
docs/_templates/18-coverage-report.md
vendored
@@ -1,29 +0,0 @@
|
||||
---
|
||||
coverage_status: PASS # PASS | FAIL (machine-key — читает check_coverage_gate)
|
||||
work_item: ORCH-NNN
|
||||
measured_coverage: 0.0 # измеренное line coverage src/ (%, float)
|
||||
baseline: 0.0 # базовая линия main на момент измерения (%, или пусто при bootstrap)
|
||||
floor: 0.0 # абсолютный порог coverage_min_percent (%)
|
||||
policy: both # absolute | baseline | both
|
||||
epsilon: 0.5 # допуск на шум измерения (%)
|
||||
delta: 0.0 # measured − max(baseline, floor) (%, знаковая дельта)
|
||||
---
|
||||
|
||||
# Coverage Report — ORCH-NNN
|
||||
|
||||
> Детерминированный гейт покрытия (ORCH-027) — под-гейт ребра `deploy-staging→deploy` (врезка в
|
||||
> `advance_stage`, ПОСЛЕ merge-gate, ДО image-freshness; не строка `STAGE_TRANSITIONS`). Машинный
|
||||
> вердикт читается ТОЛЬКО из `coverage_status:`. `PASS` → дальше; `FAIL` → откат на `development`.
|
||||
> Измерение — `pytest --cov=src --cov-report=json` в изолированном worktree. Source of truth
|
||||
> измеренного значения для ratchet базовой линии (`_handle_merge_verify`, ребро `deploy→done`).
|
||||
|
||||
## Verdict
|
||||
<PASS / FAIL: measured X% vs floor F% / baseline B% (policy=…, epsilon=…), delta=±D%.>
|
||||
|
||||
## Measurement
|
||||
<Инструмент (pytest-cov/coverage.py), команда, line coverage src/ = X%; либо fail-open WARNING
|
||||
при ошибке инструмента (coverage_tool_fail_closed=False).>
|
||||
|
||||
## Policy
|
||||
<Режим (absolute|baseline|both), порог floor, базовая линия main, epsilon, какое условие
|
||||
нарушено при FAIL.>
|
||||
File diff suppressed because one or more lines are too long
@@ -21,37 +21,12 @@ Per-work-item решения живут в `docs/work-items/<id>/06-adr/ADR-NNN-
|
||||
| adr-0013 | Merge-в-main + пост-деплой верификация как условие `done` | accepted | 2026-06-08 | ORCH-071 |
|
||||
| adr-0014 | SHA-в-main — единственный критерий merge-verify + регресс-гард | accepted | 2026-06-08 | ORCH-073 |
|
||||
| adr-0015 | Зависимости задач (B ждёт A) + сериализация merge внутри репо | accepted | 2026-06-08 | ORCH-026 |
|
||||
| adr-0016 | ensure_open_pr — гарантированный код-PR перед merge-verify | accepted | 2026-06-09 | ORCH-082 |
|
||||
| adr-0017 | Per-repo serial gate (пакетный автономный режим, serial e2e) | proposed | 2026-06-09 | ORCH-088 |
|
||||
| adr-0018 | Авто-режим по лейблам (autoApprove + autoDeploy) | accepted | 2026-06-09 | ORCH-089 |
|
||||
| adr-0019 | Стандарт документов конвейера (PIPELINE_DOCS, слой 1) | accepted | 2026-06-09 | ORCH-075 |
|
||||
| adr-0020 | Единый frontmatter-контракт + спека handoff (reader/writer/валидатор) | accepted | 2026-06-09 | ORCH-076 |
|
||||
| adr-0021 | Канон Anthropic для агент-промптов + эмиссия frontmatter-схемы 52c | proposed | 2026-06-09 | ORCH-077 |
|
||||
| adr-0022 | Стандарт трассировочных маркеров `ORCH-NNN` | accepted | 2026-06-09 | ORCH-078 |
|
||||
| adr-0023 | Обзорная ось reviewer + закрытие эпика 52 | accepted | 2026-06-09 | ORCH-079 |
|
||||
| adr-0024 | Disk-watchdog — heartbeat-сигнал заполнения хост-ФС | proposed | 2026-06-09 | ORCH-063 |
|
||||
| adr-0025 | Build-cache-pruner — авто-prune docker build cache на хосте | proposed | 2026-06-09 | ORCH-062 |
|
||||
| adr-0026 | STOP / отмена задачи — системный терминал `cancelled` | proposed | 2026-06-09 | ORCH-090 |
|
||||
| adr-0027 | Merge-актор — ретрай транзиентных ошибок Gitea + гард «ветка уже в `main`» | proposed | 2026-06-09 | ORCH-093 |
|
||||
| adr-0028 | Terminal-window-aware гард deploy-фазовых статусов Plane | proposed | 2026-06-09 | ORCH-094 |
|
||||
| adr-0029 | Гейт покрытия тестами — edge sub-gate + ratchet-базовая линия | proposed | 2026-06-10 | ORCH-027 |
|
||||
| adr-0030 | Лёгкий read-only `/metrics` — сырьё о самом орке для sidecar (F1b) | proposed | 2026-06-10 | ORCH-099 |
|
||||
| adr-0031 | Нормализация legacy root-owned файлов при миграции uid — детект-leaf + actionable worktree-ошибка | proposed | 2026-06-10 | ORCH-057 |
|
||||
| adr-0032 | Багфикс-трек — укороченный маршрут конвейера для багов | proposed | 2026-06-10 | ORCH-019 |
|
||||
| adr-0033 | Sidecar-watchdog F1b — мозг мониторинга в отдельном контейнере | proposed | 2026-06-10 | ORCH-100 |
|
||||
| adr-0034 | Машинный журнал уроков — таблица `lessons` + observer-leaf | proposed | 2026-06-10 | ORCH-098 |
|
||||
| adr-0035 | Turnkey-онбординг проектов — kit + операторский CLI + runbook | proposed | 2026-06-10 | ORCH-009 |
|
||||
|
||||
> ⚠️ Историческая коллизия: номер `0007` занят двумя файлами —
|
||||
> `adr-0007-reconciler.md` (ORCH-053) и `adr-0007-executable-self-deploy.md`
|
||||
> (ORCH-036). Оба accepted; для новых сквозных ADR использовать следующий
|
||||
> свободный номер (текущий максимум — `0035`).
|
||||
> свободный номер (текущий максимум — `0015`).
|
||||
> adr-0014 **amends** adr-0013 (меняет критерий merge-verify на «SHA-в-main»).
|
||||
> adr-0016 **amends** adr-0013/0014 (гарантирует открытый код-PR перед merge_pr, ORCH-082).
|
||||
> adr-0020 реализует машинный слой к adr-0019 (ORCH-52b→52c).
|
||||
> adr-0021 реализует слой промптов к adr-0019/0020 (ORCH-52d — замыкает эпик 52).
|
||||
> adr-0025 **комплементарен** adr-0024 (watchdog сигналит о росте диска — pruner убирает
|
||||
> доминирующего «пожирателя», docker build cache).
|
||||
|
||||
## Формат
|
||||
**Контекст → Решение → Альтернативы → Последствия → Связи.** Статус: proposed / accepted / superseded.
|
||||
|
||||
@@ -1,52 +0,0 @@
|
||||
# ADR-0016: ensure_open_pr — гарантированный код-PR перед merge-verify (ORCH-082)
|
||||
|
||||
## Статус
|
||||
Accepted — амендмент к [adr-0013](adr-0013-merge-verify-gate.md) и
|
||||
[adr-0014](adr-0014-merge-verify-sha-source-of-truth.md). Детально:
|
||||
`docs/work-items/ORCH-082/06-adr/ADR-001-ensure-open-pr-before-merge-verify.md`.
|
||||
|
||||
## Контекст
|
||||
Merge-verify (ORCH-071/073) — под-гейт ребра `deploy → done`: детерминированно мержит код-PR в
|
||||
`main` (`merge_pr`) и подтверждает merge **только** по «SHA-в-main» (`verify_merged_to_main`,
|
||||
ORCH-073). На деплое ORCH-074 (08.06) `merge_pr` вернул `("False", "no open PR")`: у ветки **не
|
||||
было** открытого PR с `head==branch` И `base=="main"`. Защита ORCH-073 верно удержала задачу
|
||||
(HOLD, не ложный `done`), но это лечило **следствие**.
|
||||
|
||||
Первопричина (код-аудит): PR создаётся в конвейере **единственной** функцией
|
||||
`launcher._ensure_pr`, вызываемой **только** на developer-пути и **только** при свежем
|
||||
worktree-коммите. Любой сценарий без свежего developer-коммита (бойнс без правок, повторный
|
||||
прогон, **ручное восстановление ветки/`main`** — случай ORCH-074) оставляет ветку без код-PR.
|
||||
Инвариант «к merge-verify у ветки есть открытый код-PR» в конвейере **отсутствовал** → блокер
|
||||
автономного деплоя (ORCH-54).
|
||||
|
||||
## Решение
|
||||
Аддитивно обеспечить инвариант **внутри того же под-гейта**, ПЕРЕД `merge_pr`, не трогая машину
|
||||
стадий:
|
||||
|
||||
1. **Новый leaf-актор `merge_gate.ensure_open_pr(repo, branch) -> (status, detail)`** (never-raise):
|
||||
`GET …/pulls?state=open` с фильтром **`head.ref==branch` И `base.ref=="main"`** (идентичен
|
||||
`merge_pr`/ORCH-073 FR-3 — авто-docs-PR не считается код-PR) → `("existed", N)`; иначе
|
||||
`POST …/pulls` → `("created", N)`; гонка «PR exists» → повторный GET → `existed` (без дублей);
|
||||
любая ошибка → `("failed", reason)`.
|
||||
2. **Врезка в `_handle_merge_verify`** ПОСЛЕ резолва `validated_revision` и ПЕРЕД `merge_pr`:
|
||||
`created|existed` → штатно к `merge_pr`; `failed` → честный HOLD+alert через новый helper
|
||||
`_hold_pr_create_failed` (текст «PR создать не удалось» — отличим от not-merged HOLD), задача
|
||||
остаётся на `deploy`, БЕЗ отката на development.
|
||||
3. **Kill-switch `merge_verify_autocreate_pr_enabled`** (дефолт `True`); область —
|
||||
`merge_verify_applies` (self-hosting / `merge_verify_repos`). `False` → поведение ORCH-074 1:1.
|
||||
4. **`launcher._ensure_pr`** рекомендуется делегировать в `ensure_open_pr` (единый код создания
|
||||
PR), сохранив прежний триггер «только developer-путь».
|
||||
|
||||
## Последствия
|
||||
- **Защита ORCH-073 неприкосновенна и приоритетна:** подтверждение merge остаётся ТОЛЬКО
|
||||
`verify_merged_to_main` (SHA-в-main) + `check_main_regression`. Создание PR устраняет лишь
|
||||
**ложный** HOLD «no open PR», но не маскирует реально невлитый код (тот → HOLD как прежде).
|
||||
- **Без миграций:** идемпотентность выводится из Gitea (наличие открытого PR), схема БД не меняется
|
||||
— restart-safe; повторный заход (reaper/reconciler/re-approve) → `existed`, дублей нет.
|
||||
- **Инварианты целы:** `STAGE_TRANSITIONS`, `QG_CHECKS`, схема БД, `check_deploy_status`,
|
||||
exit-коды хука, merge-gate (ORCH-043), image-freshness (ORCH-058) — без изменений; `main` не
|
||||
push/force-push; never-raise на всём пути.
|
||||
- **Наблюдаемость:** один однозначный исход в логах на проход — created / existed / failed; HOLD по
|
||||
failed текстуально отличим от HOLD not-merged.
|
||||
- **Минус:** код-PR может создаваться после прохождения гейтов — безопасно, т.к. гейты валидируют
|
||||
код ветки, а merge-verify идёт ПОСЛЕ всех гейтов; PR — лишь механизм слияния, ревью не обходится.
|
||||
@@ -1,59 +0,0 @@
|
||||
# adr-0017: Per-repo serial gate (пакетный автономный режим, serial e2e)
|
||||
|
||||
Статус: **proposed** · Дата: 2026-06-09 · Источник: **ORCH-088** (Этап 1)
|
||||
Детально: `docs/work-items/ORCH-088/06-adr/ADR-001-serial-gate.md`.
|
||||
|
||||
## Контекст
|
||||
Цель эпика ORCH-088 — масштаб автономности: накидать вечером 10–20 задач и получить к утру пакет,
|
||||
последовательно проведённый через весь конвейер (analysis → … → deploy → done). Корневая проблема —
|
||||
**stale-анализ**: ветка задачи N+1 срезается на входе в анализ (`start_pipeline._create_gitea_branch`)
|
||||
от `main`, ещё не содержащего код предшественника N. Физическое код-затирание уже закрыто (ORCH-026
|
||||
auto_rebase + merge-lease); остаётся **логический** разрыв. Plane API v1 не имеет bulk/relations ⇒
|
||||
очередь/зависимости хранятся у оркестратора (gate по локальной БД).
|
||||
|
||||
## Решение
|
||||
**Per-repo serial gate** — новая задача репо не входит в `analysis` (не режет ветку, не запускает
|
||||
analyst), пока в том же репо есть незавершённая задача (`stage != 'done'`) или репо заморожен.
|
||||
Три механизма, аддитивно, под kill-switch, с областью репо, never-raise, restart-safe:
|
||||
|
||||
1. **Gate-в-claim** (`db.claim_next_job`) — analyst-job (`jobs.agent='analyst'`) применимого репо не
|
||||
выбирается, если `EXISTS` другая незавершённая задача репо ИЛИ активна строка `repo_freeze`. По
|
||||
образцу `task_deps` `NOT EXISTS` (ORCH-026); только локальная БД (offline hot-path). Job'ы уже
|
||||
активной задачи проходят свободно; rework-analyst не блокирует себя (`t2.id != jobs.task_id`).
|
||||
2. **Отложенный срез ветки** — для применимого репо `start_pipeline` создаёт task-row + enqueue
|
||||
analyst, но **не** создаёт Gitea-ветку/docs; срез релоцируется на момент claim analyst-job
|
||||
(launcher), когда `origin/main` уже содержит предшественника (`done` ⇔ SHA-в-main, ORCH-071/073).
|
||||
`ensure_worktree` режет от свежего `origin/main` ⇒ AC-6 структурно. Идемпотентно (409 = no-op).
|
||||
3. **Durable per-repo freeze** (`repo_freeze`) — post-deploy `DEGRADED`/rollback (ORCH-021) →
|
||||
`set_repo_freeze` + Telegram-алерт; gate закрыт безусловно до **ручного** снятия
|
||||
(`POST /serial-gate/unfreeze`). Деградировавшая задача уже `done` (BR-7) ⇒ нужен отдельный сигнал.
|
||||
|
||||
Чистая логика — leaf `src/serial_gate.py` (never-raise). Флаги `serial_gate_enabled` (kill-switch),
|
||||
`serial_gate_repos` (CSV; **пусто ⇒ все репо**, в отличие от self-hosting-only ORCH-35/43/58),
|
||||
`serial_gate_freeze_enabled`. Наблюдаемость — блок `serial_gate` в `GET /queue`.
|
||||
|
||||
## Альтернативы
|
||||
- **Гейт в `start_pipeline` + re-trigger при `done`** — больше состояния/путей, риск зависших задач;
|
||||
relocation на claim переиспользует restart-safe `jobs`-очередь.
|
||||
- **Freeze как колонка `tasks`** — неверная семантика (freeze per-repo, задача уже `done`).
|
||||
- **Self-hosting-only область** — лишает enduro анти-stale-base (FR-3).
|
||||
- **Отдельная таблица очереди ожидания** — избыточно; `jobs(queued)`+gate достаточно.
|
||||
- **Снятие freeze Plane-жестом** — перегрузка статусов (анти-паттерн ORCH-059).
|
||||
|
||||
## Последствия
|
||||
- **+** AC-6 закрыт структурно; AC-2/AC-3 «бесплатны» (ожидание = `queued` job без ветки);
|
||||
переиспользование проверенных паттернов; cross-repo параллелизм сохранён; `STAGE_TRANSITIONS` /
|
||||
`QG_CHECKS` / `check_*` / merge-gate / merge-verify / image-freshness / post-deploy / deploy-хук /
|
||||
`max_concurrency` — **без изменений**.
|
||||
- **NFR-1:** hot-claim тотальный сбой → **fail-open** (не заклинить очередь всех проектов); freeze в
|
||||
Python-слое → **fail-closed** (безопасность прода).
|
||||
- **−** Срез ветки/docs мигрируют из async в sync-путь launcher (обёртка); Blocked-задача держит пакет
|
||||
(Этап 1, осознанно); freeze снимается только вручную.
|
||||
- Откат: `serial_gate_enabled=False` ⇒ claim/старт 1:1 как до ORCH-088; таблица `repo_freeze` инертна.
|
||||
- **Вне скопа** (Этап 1): merge-очередь FIFO, pre-merge rebase как отдельная фича, фазы A/B/C,
|
||||
любой параллелизм задач внутри одного репо, зависимость от ORCH-83.
|
||||
|
||||
## Связи
|
||||
- Переиспользует: adr-0002 (очередь ORCH-1), adr-0015 (claim-gate/auto_rebase/merge-lease ORCH-026),
|
||||
adr-0010 (post-deploy monitor — источник DEGRADED), adr-0013/0014 (merge-verify ⇒ `done`⇔SHA-в-main).
|
||||
- Новая аддитивная таблица `repo_freeze` (`docs/work-items/ORCH-088/08-data-requirements.md`).
|
||||
@@ -1,59 +0,0 @@
|
||||
# ADR-0018: Авто-режим по лейблам — autoApprove / autoDeploy (ORCH-089)
|
||||
|
||||
## Статус
|
||||
Accepted (реализация — ORCH-089)
|
||||
|
||||
## Контекст
|
||||
Конвейер имеет два **человеческих** гейта, тормозящих пакетный автономный прогон
|
||||
(эпик ORCH-088, «10–20 задач за ночь»):
|
||||
1. **BRD** (`analysis`): ждёт ручного Plane-статуса `Approved` → advance на `architecture`.
|
||||
2. **Прод-деплой** (`deploy`): Phase A ставит `Awaiting Deploy` и ждёт ручного
|
||||
`Confirm Deploy` (ORCH-059) → Phase B (`initiate_deploy`).
|
||||
|
||||
Для доверенных задач оба клика избыточны. Нужно снять **только эти два человеческих
|
||||
решения**, выборочно/декларативно (лейбл Plane на задаче), не ослабляя ни одной
|
||||
технической проверки.
|
||||
|
||||
## Решение
|
||||
Аддитивно, по образцу условных под-гейтов (ORCH-035/043/058/059/088): leaf-модуль чистой
|
||||
логики `src/labels.py` (never-raise) + точечные врезки + флаги. `STAGE_TRANSITIONS`, реестр
|
||||
`QG_CHECKS`, все `check_*`, схема БД — **не трогаются**.
|
||||
|
||||
- **`autoApprove`** (лейбл задачи) → в `_handle_analysis_approved_flow` (ветка `files_ok`)
|
||||
после `In Review`+коммента: `set_issue_approved` (индикация) + лог/Telegram/Plane-коммент +
|
||||
`advance_stage(..., finished_agent=None)` — тот же путь, что человеческий Approved
|
||||
(`approved-via-status` → `analysis → architecture` + `mark_brd_review_ended`). Без
|
||||
дублирования переходной логики.
|
||||
- **`autoDeploy`** (лейбл задачи) → в `_handle_self_deploy_phase_a` сразу после advance на
|
||||
`deploy` + `clear_state`: лог/Telegram/Plane-коммент + `_handle_self_deploy_phase_b(...)`
|
||||
(idempotency-маркер `INITIATED`, `Deploying`, finalizer). Пропускаются лишь
|
||||
индикативно-человеческие шаги (`Awaiting Deploy` + «ask-human»).
|
||||
- **Чтение лейблов** — `plane_sync.fetch_issue_labels` + `get_project_labels` (TTL-кэш,
|
||||
образец `get_project_states`); сопоставление по нормализованному имени; источник истины —
|
||||
Plane API (не payload). Новый сеттер `set_issue_approved` (ключ `approved` уже в states).
|
||||
- **Флаги:** `auto_label_enabled` (kill-switch), `auto_approve_label`/`auto_deploy_label`
|
||||
(имена), `auto_label_repos` (CSV; **пусто → self-hosting only**), `auto_label_states_ttl_s`.
|
||||
`applies(repo)` (локальный) проверяется ПЕРВЫМ; `has_label` (сеть) — только если
|
||||
`applies==True` → при выключенном флаге нулевой сетевой оверхед.
|
||||
|
||||
## Критические инварианты
|
||||
- **Авто-режим снимает ТОЛЬКО человеческое решение**, не ослабляя ни один тех-гейт
|
||||
(CI / staging / security / merge-gate / image-freshness / merge-verify / regression-guard /
|
||||
post-deploy). autoDeploy живёт в точке, где все под-гейты ребра `deploy-staging → deploy`
|
||||
уже зелёные → структурно «никогда не деплоит сломанное».
|
||||
- **Fail-safe (never auto):** любая ошибка/недоступность Plane/неоднозначность имени →
|
||||
«нет авто» → ручной гейт (согласовано с fail-closed-практикой ORCH-059). never-raise.
|
||||
- **Нулевая регрессия:** без лейблов / `auto_label_enabled=False` / репо вне scope →
|
||||
поведение 1:1 как до ORCH-089 (enduro не затронут).
|
||||
- **Идемпотентность:** autoApprove — advance применяется один раз (поздний Approved/F-2
|
||||
видят уже `architecture`); autoDeploy — маркер `INITIATED`.
|
||||
|
||||
## Последствия
|
||||
**+** минимальная поверхность, единый источник истины перехода, декларативно/обратимо,
|
||||
независимые лейблы, безопасный дефолт. **−** Approved-статус транзиентен (durable-аудит —
|
||||
лог/Telegram/коммент); 1–2 GET к Plane на гейт применимого репо (TTL-кэш карты лейблов);
|
||||
требуется однократно создать лейблы в Plane-проекте ORCH (инфра-предусловие; их отсутствие =
|
||||
fail-safe ручной режим).
|
||||
|
||||
Детально: `docs/work-items/ORCH-089/06-adr/ADR-001-auto-label-gates.md`,
|
||||
`07-infra-requirements.md`, `10-tech-risks.md`.
|
||||
@@ -1,49 +0,0 @@
|
||||
# adr-0019: Стандарт документов пайплайна (docs/_standards + docs/_templates + ADR-naming)
|
||||
|
||||
Статус: **proposed** · Дата: 2026-06-09 · Источник: **ORCH-075** (ORCH-52b, слой 1 эпика ORCH-52)
|
||||
Детально: `docs/work-items/ORCH-075/06-adr/ADR-001-pipeline-docs-standard.md`.
|
||||
|
||||
## Контекст
|
||||
Агенты всех ролей пишут номерные доки work item (`00…17`) «по памяти»; каталогов
|
||||
`docs/_standards/` и `docs/_templates/` нет. Следствия: разнобой структуры между задачами; риск
|
||||
рассинхрона критичных frontmatter-ключей машинных доков (`verdict:` / `result:` / `deploy_status:` /
|
||||
`staging_status:` / `security_status:`), которые читает гейт; отсутствует целостная карта «стадия →
|
||||
агент → документ → гейт». Эпик ORCH-52 слоист: слой 1 (52b) фиксирует **договорённость**, машинная
|
||||
проверка/валидатор — отдельный слой 52c.
|
||||
|
||||
## Решение
|
||||
**Документационный стандарт, docs-only, выведенный из фактического кода и эталонных доков:**
|
||||
|
||||
1. `docs/_standards/PIPELINE_DOCS.md` — манифест-карта «стадия → документ → владелец-агент →
|
||||
категория (`required`/`when-applicable`/`optional`) → гейт/механизм → frontmatter machine-key».
|
||||
Манифест **документирует** поведение гейтов (источник истины остаётся `src/`), честно различает
|
||||
machine-verdict доки (`12,13,14,15,17`) и информационные (`00,08,10,16`), и помечает под-гейты
|
||||
ребра `deploy-staging→deploy` (security/merge/image-freshness) как врезки в `advance_stage`, а не
|
||||
строки `STAGE_TRANSITIONS`.
|
||||
2. `docs/_templates/*` — копируемые скелеты для каждого `required`/`when-applicable` дока; секции
|
||||
выведены из эталонов (ORCH-088/073/089/071), новые не изобретаются; машинные доки несут точный
|
||||
frontmatter-ключ из ground-truth.
|
||||
3. **ADR-naming** канонизирован: `docs/work-items/<plane-id>/06-adr/ADR-NNN-<kebab-slug>.md` (NNN с
|
||||
`001`); кросс-каттинговые решения дублируются в этот глобальный реестр `adr-NNNN-<slug>.md`.
|
||||
|
||||
Подключение — ссылки из `CLAUDE.md` и `docs/architecture/README.md` + запись в `CHANGELOG.md`.
|
||||
|
||||
## Альтернативы
|
||||
- Сразу валидатор на гейте — отвергнуто (ORCH-52c; нарушил бы docs-only/NFR-1, групповой риск).
|
||||
- Манифест как источник истины гейтов — отвергнуто (дубль-истина «манифест ≠ код»).
|
||||
- Шаблоны в `docs/work-items/_template/` — отвергнуто (риск для сканеров/гейтов наличия файлов).
|
||||
- Ретро-фит истории доков — отвергнуто (вне scope, отдельный риск).
|
||||
|
||||
## Последствия
|
||||
- **+** Единый golden source структуры доков; меньше ложных падений гейтов из-за неверного
|
||||
frontmatter-ключа; ADR-naming записан; база для ORCH-52c.
|
||||
- **+ Нулевой рантайм-риск:** только `docs/**` + `CLAUDE.md` + `CHANGELOG.md`; `STAGE_TRANSITIONS` /
|
||||
`QG_CHECKS` / `check_*` / `src/stage_engine.py` / схема БД — без изменений; полностью обратимо.
|
||||
- **−** Манифест — снимок поведения гейтов, дрейфует до ORCH-52c (митигейшн: источник истины — код,
|
||||
reviewer-правило, привязка к именам `check_*`); стандарт описательный, не принуждающий.
|
||||
|
||||
## Связи
|
||||
- Источник: ORCH-075 (`docs/work-items/ORCH-075/06-adr/ADR-001-pipeline-docs-standard.md`).
|
||||
- Документирует (не меняет): adr-0003/0006/0008/0012/0013/0014/0016 (гейты и под-гейты ребра),
|
||||
`STAGE_TRANSITIONS` (`src/stages.py`), `QG_CHECKS` (`src/qg/checks.py`).
|
||||
- Downstream: ORCH-52c (frontmatter-валидатор / writer-контракт), ORCH-52d (правка промптов).
|
||||
@@ -1,63 +0,0 @@
|
||||
# adr-0020: Единый frontmatter-контракт + спека handoff (reader/writer/валидатор)
|
||||
|
||||
Статус: **Accepted** · Дата: 2026-06-09 · Источник: **ORCH-076** (ORCH-52c)
|
||||
Детально: [`docs/work-items/ORCH-076/06-adr/ADR-001-frontmatter-contract.md`](../../work-items/ORCH-076/06-adr/ADR-001-frontmatter-contract.md)
|
||||
|
||||
## Контекст
|
||||
|
||||
Слой 1 эпика ORCH-52 (ORCH-075/52b) дал **описательный** стандарт документов
|
||||
(`docs/_standards/PIPELINE_DOCS.md`), явно отложив машинную проверку на ORCH-52c. В коде:
|
||||
`src/frontmatter.py` — только single-key reader (never-raise), а ~10-строчный блок парсинга
|
||||
YAML-frontmatter **продублирован** в 5 вердикт-парсерах (`check_reviewer_verdict`,
|
||||
`_parse_tests_verdict`, `_parse_deploy_status`, `_parse_staging_status`, `parse_security_status`)
|
||||
+ в `_strip_frontmatter`/`extract_security_findings`. Единого контракта чтения, writer'а, схемы
|
||||
и формальной спеки handoff — нет. Эти парсеры читают вердикты **на гейтах self-hosting**
|
||||
инструмента, обслуживающего прод других проектов из общего инстанса → любой регресс = стоп
|
||||
конвейера всех проектов.
|
||||
|
||||
## Решение
|
||||
|
||||
1. **`src/frontmatter.py` → полный frontmatter-контракт** (функции в существующем leaf-модуле,
|
||||
контракт **never-raise**): сохранённый `read_frontmatter_value` (без изменений) + единый
|
||||
парс-примитив `parse_frontmatter(content) -> FrontmatterParse` (единственная точка
|
||||
YAML-логики, структура различает no-block / malformed / yaml-error / data) + `render_/
|
||||
write_frontmatter` (writer) + `validate_schema` (обязательная схема
|
||||
`work_item, stage, author_agent, status, created_at, model_used`) + `strip_frontmatter`.
|
||||
2. **Унифицируется механизм парсинга, НЕ семантика.** Все 5 вердикт-парсеров читают YAML через
|
||||
`parse_frontmatter`; token-наборы, upper-casing, приоритет негативного токена, 3-полевой
|
||||
контракт tester'а (ORCH-047), fallback `worktree→origin/main` — **1:1**. Сигнатуры и
|
||||
`tuple[bool, str]` — неизменны. Reason-строки переносятся дословно.
|
||||
3. **Валидатор не hard-fail по умолчанию.** Флаг `frontmatter_validation_strict` (env
|
||||
`ORCH_FRONTMATTER_VALIDATION_STRICT`, дефолт `False`): default — warning/лог, **вне
|
||||
вердикт-пути гейтов** (нулевая регрессия); hard-fail — зарезервированный strict-режим
|
||||
(включение — с ORCH-52d). Иначе ORCH-52c заблокировала бы собственный деплой.
|
||||
4. **Формальная спека handoff** `docs/_standards/HANDOFF_PROTOCOL.md` — «стадия → обязательный
|
||||
выход» (документы + frontmatter-ключи), согласована 1:1 с `PIPELINE_DOCS.md` §2–§3; источник
|
||||
истины — код. `PIPELINE_DOCS.md` обновляется ссылкой + отметкой о реализации машинного слоя.
|
||||
5. **Без изменений** `STAGE_TRANSITIONS`, состава `QG_CHECKS`, API, схемы БД.
|
||||
|
||||
## Альтернативы
|
||||
|
||||
- Общий «умный» verdict-резолвер (поле+токены для всех гейтов) — отклонён: различия token-логики
|
||||
→ риск тонкого регресса на гейте при self-hosting. Унифицируем только парс YAML.
|
||||
- Класс/новый пакет — отклонён: состояния нет, лишний blast radius.
|
||||
- Hard-fail валидатор по умолчанию — отклонён (NFR-3: self-block собственного деплоя).
|
||||
- Сторонняя `python-frontmatter` — отклонена: лишняя зависимость ради ~30 строк.
|
||||
|
||||
## Последствия
|
||||
|
||||
- **+** Конец дублирования/рассинхрона парсинга; writer+валидатор+схема готовы к ORCH-52d;
|
||||
спека handoff закрывает пробел контракта стадий.
|
||||
- **+** Нулевая регрессия по построению: семантика и reason-строки 1:1, валидатор инертен при
|
||||
дефолте, never-raise сохранён, enduro 1:1.
|
||||
- **−** Унификация частичная (парс, не семантика); strict-режим «спящий» до ORCH-52d.
|
||||
- **Обратимость:** `frontmatter_validation_strict=False` ⇒ прежнее поведение; перевод гейтов
|
||||
поведенчески инвариантен.
|
||||
- **Риск:** первый боевой `autoDeploy` орка (ORCH-089) — наблюдение за стадией `deploy`
|
||||
(`docs/work-items/ORCH-076/10-tech-risks.md`).
|
||||
|
||||
## Связи
|
||||
|
||||
- Опирается: adr-0019 (pipeline-docs-standard, ORCH-075), ORCH-016 (reader), ORCH-047
|
||||
(3-полевой tester), adr-0012 (security-гейт), adr-0018 (auto-label/`autoDeploy`).
|
||||
- Готовит: ORCH-52d (эмиссия полной схемы агентами; возможное включение strict).
|
||||
@@ -1,84 +0,0 @@
|
||||
# adr-0021: Канон Anthropic для системных промптов агентов + эмиссия frontmatter-схемы 52c
|
||||
|
||||
- **Статус:** proposed
|
||||
- **Дата:** 2026-06-09
|
||||
- **Источник:** ORCH-077 (эпик ORCH-52, слой 52d — замыкающий)
|
||||
- **Связи:** реализует слой промптов к adr-0019 (52b, PIPELINE_DOCS) и adr-0020 (52c,
|
||||
frontmatter-контракт). Детально — `docs/work-items/ORCH-077/06-adr/ADR-001-anthropic-prompt-canon.md`.
|
||||
|
||||
## Контекст
|
||||
|
||||
Эпик ORCH-52 строит сквозной контракт документации конвейера: **52b** (adr-0019) — описательный
|
||||
стандарт документов + скелеты `docs/_templates/`; **52c** (adr-0020) — машинный контракт
|
||||
`src/frontmatter.py` (reader/writer/валидатор `REQUIRED_FIELDS`) + спека `HANDOFF_PROTOCOL.md` с
|
||||
обязательной 6-польной схемой `(work_item, stage, author_agent, status, created_at, model_used)`.
|
||||
|
||||
Две незакрытые проблемы:
|
||||
1. **Цепочка 52b→52c→52d разорвана.** Writer и валидатор схемы есть, но работают warning-only
|
||||
(`frontmatter_validation_strict=False`); агенты **не эмитят** поля схемы — на входе валидатора нет
|
||||
данных, петля не замкнута.
|
||||
2. **Форма 6 промптов `.openclaw/agents/*.md` разнородна** (RU/EN, свободная структура) → снижает
|
||||
предсказуемость агентов прода, которые исполняются на КАЖДОЙ задаче ВСЕХ проектов из общего
|
||||
инстанса (self-hosting).
|
||||
|
||||
Факт загрузки (сверено `src/agents/launcher.py`): промпт `cat`-ается из git-worktree агента в момент
|
||||
запуска (`--system-prompt "$(cat .openclaw/agents/<role>.md)"`), НЕ запекается в образ.
|
||||
|
||||
## Решение
|
||||
|
||||
Ввести **обязательный канон формы** для всех агент-промптов и сделать его машинно-проверяемым.
|
||||
|
||||
1. **Фиксированный XML-скелет (5 обязательных секций, нормативный порядок):**
|
||||
`<context>` → `<task>` (+ опц. `<thinking>`) → `<deliverables>` → `<constraints>` →
|
||||
`<output_format>`. Доп. секции (`<success_criteria>`, `<escalation>`) — после. Контекст/роль
|
||||
вперёд, формат вывода последним (recency для следования схеме).
|
||||
2. **Аддитивная эмиссия схемы 52c.** `<output_format>` каждого промпта перечисляет 6 полей схемы с
|
||||
роле-специфичными значениями и инструктирует ставить их **рядом** с существующим machine-verdict
|
||||
ключом, **не меняя его имя/регистр/значения** (`verdict:`, `result:`, `staging_status:`,
|
||||
`deploy_status:`, `security_status:` — байт-в-байт). Для `04-test-plan.yaml` (чистый YAML) — как
|
||||
top-level ключи. Гейты читают вердикты как раньше (схема в boolean-вердикте не участвует).
|
||||
3. **Few-shot + позитивные альтернативы.** Ссылки на `docs/_templates/` и эталоны (ORCH-073/088);
|
||||
каждый запрет в формате «❌ X → ✅ Y».
|
||||
4. **CoT/thinking** у решающих ролей (architect/reviewer/tester/deployer).
|
||||
5. **Анти-регресс машинно.** Структурные тесты `tests/test_agent_prompts_canon.py` (без запуска
|
||||
агентов): 5 секций, 6 полей схемы, точный регистр machine-verdict ключей, ключевые
|
||||
self-hosting-маркеры (deployer: `docker exec orchestrator-staging`, `pr_already_merged`,
|
||||
«не рестартить 8500»). `test_agent_frontmatter_no_model.py` остаётся зелёным.
|
||||
6. **Enforcement не включается.** `frontmatter_validation_strict` остаётся `False` (warning-only);
|
||||
52d учит эмитить добровольно. Hard-fail — отдельная будущая задача.
|
||||
|
||||
**Границы:** docs/prompts-only. `src/**` (config, launcher, frontmatter, stages, qg/checks,
|
||||
stage_engine), `STAGE_TRANSITIONS`, `QG_CHECKS`, состав machine-verdict ключей, схема БД, `tools:`-блок
|
||||
промптов — **не трогаются**.
|
||||
|
||||
**Норматив на будущее:** любая новая правка/добавление агент-промпта следует этому канону (5 секций +
|
||||
аддитивная схема + ❌→✅). Отступление требует нового ADR.
|
||||
|
||||
## Альтернативы
|
||||
|
||||
- **Сразу включить hard-fail схемы.** Отвергнуто: правка `src/config.py` вне scope; для self-hosting
|
||||
рискованно (забытое поле валит гейт всех проектов). Сначала эмиссия, enforcement — позже.
|
||||
- **Канон как рекомендация, не норма.** Отвергнуто: теряется машинная проверяемость, эпик требует
|
||||
контракт.
|
||||
- **Запечь промпты в образ.** Отвергнуто: противоречит loading-model (cat из worktree), добавило бы
|
||||
прод-рестарт-зависимость.
|
||||
|
||||
## Последствия
|
||||
|
||||
- **+** Петля 52 замкнута: схема наполняется реальными данными на каждой стадии всех проектов.
|
||||
- **+** Единый предсказуемый канон; правки промптов вступают в силу **без прод-рестарта** (следующий
|
||||
worktree от `main`) → нулевой self-hosting-риск выкатки.
|
||||
- **+** Естественный in-vivo A/B: reviewer/tester задачи исполняются под новыми промптами в той же
|
||||
ветке (метод BR-6).
|
||||
- **−** Рост объёма промптов (митигейшн: ссылки вместо инлайна, контроль объёма).
|
||||
- **−** Риск регресса инструкции (митигейшн: построчная карта + структурные тесты + приоритетный
|
||||
review deployer/reviewer).
|
||||
- **Откат:** `git revert` PR — свободная форма возвращается, эмиссия прекращается, гейты идентичны.
|
||||
|
||||
## Связи
|
||||
- Реализует: adr-0019 (52b), adr-0020 (52c).
|
||||
- Per-work-item: `docs/work-items/ORCH-077/06-adr/ADR-001-anthropic-prompt-canon.md`.
|
||||
- Стандарты: `docs/_standards/PIPELINE_DOCS.md`, `docs/_standards/HANDOFF_PROTOCOL.md`,
|
||||
`src/frontmatter.py::REQUIRED_FIELDS`.
|
||||
- Сверено по коду: `src/agents/launcher.py`, `Dockerfile`,
|
||||
`src/config.py::frontmatter_validation_strict`, `tests/test_agent_frontmatter_no_model.py`.
|
||||
@@ -1,106 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-078
|
||||
stage: architecture
|
||||
author_agent: architect
|
||||
status: proposed
|
||||
created_at: 2026-06-09
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# adr-0022: Стандарт маркеров-трассировки `ORCH-NNN` + правило чтения ADR перед правкой
|
||||
|
||||
- **Статус:** proposed
|
||||
- **Дата:** 2026-06-09
|
||||
- **Источник:** ORCH-078 (эпик ORCH-52, слой 52e — трассировка, слой 4)
|
||||
- **Связи:** продолжает цепочку стандартов эпика 52 — adr-0019 (52b, `PIPELINE_DOCS.md`),
|
||||
adr-0020 (52c, frontmatter-контракт), adr-0021 (52d, канон промптов). Детально —
|
||||
`docs/work-items/ORCH-078/06-adr/ADR-001-traceability-marker-standard.md`.
|
||||
|
||||
## Контекст
|
||||
|
||||
Эпик ORCH-52 строит сквозной контракт документации конвейера: **52b** (adr-0019) — описательный
|
||||
стандарт документов + скелеты; **52c** (adr-0020) — машинный frontmatter-контракт + `HANDOFF_PROTOCOL.md`;
|
||||
**52d** (adr-0021) — 6 промптов в каноне Anthropic + добровольная эмиссия 52c-схемы. Закрыты слои
|
||||
структуры (52b), машинного вердикта (52c) и формы промптов (52d), но **слой трассировки кода к
|
||||
решениям не формализован**.
|
||||
|
||||
Факты, сверенные с кодом `main`:
|
||||
- В `src/` живёт **51 уникальный** маркер `ORCH-NNN` (`grep -rhoE 'ORCH-[0-9]+' src/ | sort -u | wc -l`),
|
||||
привязывающий нетривиальные инварианты к породившему их work item — **сложившаяся практика без
|
||||
формального стандарта** (`docs/_standards/` несёт лишь `PIPELINE_DOCS.md`/`HANDOFF_PROTOCOL.md`).
|
||||
- Высокая плотность: `config.py`=63, `stage_engine.py`=55, `agents/launcher.py`=50, `plane_sync.py`=48,
|
||||
`merge_gate.py`=26 вхождений.
|
||||
|
||||
Три незакрытые проблемы:
|
||||
1. **Нет правила чтения.** Агент, правя маркированную строку, не обязан прочитать ADR, который её
|
||||
ввёл → риск молча сломать инвариант. Это класс «фантомного merge»
|
||||
(`docs/history/LESSONS_2026-06-08_phantom-merge.md`), породившего ORCH-071/073.
|
||||
2. **Reviewer не контролирует соблюдение** — ось «Соответствие ADR» проверяет ADR текущей задачи, не
|
||||
сверку правки чужого маркированного кода с его ADR.
|
||||
3. **Анти-археология** — блок с 50+ маркерами = раскопки по 4+ work item.
|
||||
|
||||
## Решение
|
||||
|
||||
Ввести **нормативный стандарт маркеров-трассировки** `docs/_standards/TRACEABILITY.md` (слой 4 эпика
|
||||
52) и точечно дополнить промпты правилом чтения / контролем соблюдения **со ссылкой на единый
|
||||
источник**. Это **docs + prompts-only**, нулевое касание кода; стандарт — описательно-нормативный
|
||||
документ + анти-регресс-тест промптов, **не машинный гейт конвейера**.
|
||||
|
||||
1. **`TRACEABILITY.md`** кодифицирует существующий контракт (не вводит новый синтаксис): определение
|
||||
маркера, формат (inline-комментарий, рекомендуется ссылка на решение), правило размещения (рядом с
|
||||
нетривиальным инвариантом), чтение истории **с реальным проверяемым примером**
|
||||
(`src/serial_gate.py` → ORCH-088 → `ADR-001-serial-gate.md`), fallback-доступ, анти-археология,
|
||||
каноничный текст правила чтения.
|
||||
2. **Единый источник истины правила.** Каноничная формулировка живёт только в `TRACEABILITY.md`;
|
||||
промпты несут короткую врезку-**ссылку**, не копию → нет дрейфа между файлами (анти-дубль 52d).
|
||||
3. **Точечные врезки (аддитивно, 52d-канон не переписывается):** `developer.md` — правило чтения +
|
||||
fallback-доступ («❌ X → ✅ Y»); `architect.md` — правило чтения + анти-археология; `reviewer.md` —
|
||||
усиление оси «Соответствие ADR» под-пунктом «правка маркированного кода сверена с его ADR; слом →
|
||||
finding ≥P1».
|
||||
4. **Анти-археология:** блок с **≥3** маркерами → одна сводная ссылка на сквозной ADR
|
||||
(`docs/architecture/adr/`) вместо перечисления всех work item. Пример: `src/merge_gate.py` →
|
||||
`adr-0006/0013/0014/0016`.
|
||||
5. **Fallback-доступ:** `git show origin/main:docs/work-items/ORCH-NNN/06-adr/ADR-001-<slug>.md` —
|
||||
когда папки нет в текущей ветке.
|
||||
6. **Анти-регресс машинно:** расширение `tests/test_agent_prompts_canon.py` (tests-only) — утверждает
|
||||
присутствие reading-rule/`TRACEABILITY`-маркеров; существующие проверки 52d и
|
||||
`test_agent_frontmatter_no_model.py` остаются зелёными.
|
||||
|
||||
**Границы:** `src/**`, `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`, `_parse_*`, `src/frontmatter.py`,
|
||||
схема БД — **не трогаются**. `frontmatter_validation_strict` остаётся `False`; новый QG не вводится.
|
||||
Массовый ретро-фит 51 существующего маркера **вне объёма** — стандарт действует «на будущее».
|
||||
|
||||
**Норматив на будущее:** новый/правимый значимый инвариант → ставь маркер своей задачи рядом; блок с
|
||||
3+ маркерами → сводный сквозной ADR; правка чужого маркера → читай его `06-adr` до изменения.
|
||||
|
||||
## Альтернативы
|
||||
|
||||
- **Машинный гейт/CI-lint маркеров.** Отвергнуто: правка `src/`/CI вне scope; для self-hosting
|
||||
рискованно (ложный fail валит конвейер всех проектов); премэйчур до описательного стандарта.
|
||||
Enforcement — потенциальная будущая задача (как hard-fail схемы в adr-0021).
|
||||
- **Массовый ретро-фит 51 маркера.** Отвергнуто: огромный диф, риск регресса смысла, вне объёма.
|
||||
- **Копировать правило в каждый промпт.** Отвергнуто: дрейф между файлами, нарушение анти-дубль.
|
||||
- **Только per-work-item ADR без глобального.** Отвергнуто: рвёт цепочку эпика 52 (52b/c/d имеют
|
||||
глобальный ADR); нет точки входа для будущих агентов.
|
||||
|
||||
## Последствия
|
||||
|
||||
- **+** Замкнут слой 4 эпика 52: практика маркеров формализована, правило чтения защищает от слома
|
||||
инвариантов; reviewer получает ось контроля.
|
||||
- **+** Единый источник правила → нет дрейфа; обновление в одном файле.
|
||||
- **+** Self-hosting без рестарта: промпт `cat`-ается из worktree → правило действует на следующем
|
||||
worktree от `main` без рестарта 8500.
|
||||
- **+** Полная обратимость: чисто текстовое изменение, нет миграций/состояния/kill-switch.
|
||||
- **−** Рост объёма 3 промптов (митигейшн: короткие врезки-ссылки).
|
||||
- **−** Стандарт нормативен, но не enforced машинно → соблюдение на дисциплине + ревью (осознанный
|
||||
компромисс).
|
||||
- **Откат:** `git revert` PR — стандарт удаляется, врезки исчезают, поведение кода/гейтов идентично.
|
||||
|
||||
## Связи
|
||||
- Продолжает: adr-0019 (52b), adr-0020 (52c), adr-0021 (52d).
|
||||
- Per-work-item: `docs/work-items/ORCH-078/06-adr/ADR-001-traceability-marker-standard.md`.
|
||||
- Стандарты-соседи: `docs/_standards/PIPELINE_DOCS.md`, `docs/_standards/HANDOFF_PROTOCOL.md`,
|
||||
будущий `docs/_standards/TRACEABILITY.md` (создаёт стадия development).
|
||||
- Сверено по коду: `src/serial_gate.py:241,269` (ORCH-088), `src/merge_gate.py` (26 маркеров),
|
||||
`tests/test_agent_prompts_canon.py`, `.openclaw/agents/{developer,architect,reviewer}.md`.
|
||||
- Прецедент класса ошибки: `docs/history/LESSONS_2026-06-08_phantom-merge.md`.
|
||||
@@ -1,98 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-079
|
||||
stage: architecture
|
||||
author_agent: architect
|
||||
status: proposed
|
||||
created_at: 2026-06-09
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# adr-0023: Reviewer-ось «обзорные доки» (README-ограничения) + закрытие эпика ORCH-52
|
||||
|
||||
- **Статус:** proposed
|
||||
- **Дата:** 2026-06-09
|
||||
- **Источник:** ORCH-079 (эпик ORCH-52, слой 52f — обзорные доки, слой 5/финал)
|
||||
- **Связи:** замыкает цепочку стандартов эпика 52 — adr-0019 (52b, `PIPELINE_DOCS.md`),
|
||||
adr-0020 (52c, frontmatter-контракт), adr-0021 (52d, канон промптов), adr-0022 (52e,
|
||||
трассировка маркеров). Детально — `docs/work-items/ORCH-079/06-adr/ADR-001-readme-sync-and-reviewer-overview-docs-axis.md`.
|
||||
|
||||
## Контекст
|
||||
|
||||
Эпик ORCH-52 строит сквозной контракт «документация = golden source наравне с кодом» слоями:
|
||||
**52b** (adr-0019) — описательный стандарт документов + скелеты; **52c** (adr-0020) — машинный
|
||||
frontmatter-контракт + `HANDOFF_PROTOCOL.md`; **52d** (adr-0021) — 6 промптов в каноне Anthropic +
|
||||
добровольная эмиссия 52c-схемы; **52e** (adr-0022) — стандарт трассировки маркеров + reviewer-ось
|
||||
«соответствие ADR». Закрыты слои структуры, машинного вердикта, формы промптов и трассировки кода —
|
||||
но **обзорная витрина проекта (корневой `README.md`) не охвачена**.
|
||||
|
||||
Факты, сверенные с кодом `main`:
|
||||
- Секция `README.md` «Известные ограничения» (`:236–241`) имеет битую нумерацию (`1,2,3,4,3,4`) и
|
||||
**выдаёт решённое за открытое**: worktree-гонки (закрыто `ensure_worktree` + ORCH-026/088),
|
||||
in-process daemon (закрыто очередью ORCH-1), «Gitea CI не настроен» (опровергнуто `check_ci_green`,
|
||||
`src/qg/checks.py:82`), «no retry» (опровергнуто backoff/breaker в `queue_worker.py`), плюс
|
||||
устаревшие issue-ID (зрелый `plane_sync` ORCH-010/066/068) и Playwright-timeout (неприменим к
|
||||
pytest-сервису; реальный механизм — watchdog ORCH-7).
|
||||
- **Процессный пробел:** reviewer (ось «Документация») проверяет обновление *конвейерных* доков, но
|
||||
**обзорные** разделы (README «Известные ограничения») в правиле не названы → витрина копит
|
||||
рассинхрон, т.к. закрытие ограничения не обязывает автора снять пункт.
|
||||
|
||||
## Решение
|
||||
|
||||
Закрыть слой 5 (финал) эпика 52: **синхронизировать обзорные доки с кодом по факту** и добавить
|
||||
reviewer'у **нормативную под-ось «обзорные доки»** (по образцу оси трассировки 52e). Это **docs +
|
||||
prompt-only**, нулевое касание кода; правило — описательно-нормативное, **не машинный гейт**.
|
||||
|
||||
1. **Reviewer-ось «обзорные доки» (cross-cutting).** В `.openclaw/agents/reviewer.md` ось 4
|
||||
«Документация» + `<constraints>` несут точечную врезку «❌→✅»: *PR закрыл пункт README «Известные
|
||||
ограничения», README не обновлён → finding*. Severity **≥ P1**; при закрытии ограничения правкой
|
||||
`src/` без обновления README — совпадает с существующим **P0** «`src/` изменён, доки не обновлены».
|
||||
Канон 52d (5 секций, формат запретов, `<thinking>`), 6 полей схемы 52c и ключ
|
||||
`verdict: APPROVED|REQUEST_CHANGES` — байт-в-байт.
|
||||
2. **Витрина приведена к коду (NFR-3).** Все 6 устаревших пунктов сняты/перенесены в «Закрыто
|
||||
(история)» с ORCH-ссылками; в «открытых» остаются ТОЛЬКО реально открытые, верифицированные
|
||||
кодом/задачей; нумерация сквозная. Запрет на изобретение ограничений (только уже
|
||||
задокументированные known-limitations — анти-scope-creep).
|
||||
3. **Точечная сверка** `README.md` / `docs/architecture/README.md` с `src/` (стадии/`QG_CHECKS`/
|
||||
модели-эффорты/компоненты), минимально инвазивно.
|
||||
4. **Анти-регресс машинно:** расширение `tests/test_agent_prompts_canon.py` (tests-only) — assert
|
||||
присутствия оси обзорных доков; проверки 52d и `test_agent_frontmatter_no_model.py` зелёные.
|
||||
|
||||
**Границы:** `src/**`, `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`, `_parse_*`, `src/frontmatter.py`,
|
||||
схема БД — **не трогаются**. `frontmatter_validation_strict` остаётся `False`; новый QG не вводится.
|
||||
|
||||
### Эпик ORCH-52 — закрыт (карта слоёв)
|
||||
|
||||
| Слой | Задача | Глобальный ADR | Артефакт |
|
||||
|------|--------|----------------|----------|
|
||||
| 52b — структура доков | ORCH-075 | adr-0019 | `docs/_standards/PIPELINE_DOCS.md` + `_templates/` |
|
||||
| 52c — машинный frontmatter | ORCH-076 | adr-0020 | `src/frontmatter.py` + `HANDOFF_PROTOCOL.md` |
|
||||
| 52d — канон промптов | ORCH-077 | adr-0021 | 6 промптов `.openclaw/agents/*.md` |
|
||||
| 52e — трассировка маркеров | ORCH-078 | adr-0022 | `docs/_standards/TRACEABILITY.md` |
|
||||
| **52f — обзорные доки** (финал) | **ORCH-079** | **adr-0023** | `README.md` + reviewer-ось |
|
||||
|
||||
## Альтернативы
|
||||
- **Машинный enforcement (новый QG «README актуален»).** Отвергнуто: вне scope; для self-hosting
|
||||
ложный fail валит конвейер всех проектов; правило остаётся нормативным, как 52e. Enforcement —
|
||||
возможная будущая задача (как hard-fail схемы 52c).
|
||||
- **Отдельный `docs/_standards/` для правила обзорных доков.** Отвергнуто: одно правило, один
|
||||
артефакт (README) — врезки в промпт достаточно; новый стандарт-файл избыточен.
|
||||
- **Только per-work-item ADR.** Отвергнуто: рвёт цепочку эпика 52 (52b–e имеют глобальный ADR); нет
|
||||
явной точки «эпик 52 закрыт».
|
||||
|
||||
## Последствия
|
||||
- **+** Витрина проекта честна; самоподдерживающаяся синхронность (reviewer-ось).
|
||||
- **+** Эпик 52 формально закрыт сквозным ADR — единая точка входа для будущих агентов.
|
||||
- **+** Self-hosting без рестарта: промпт `cat`-ается из worktree → правило с следующего worktree
|
||||
от `main` без рестарта 8500.
|
||||
- **+** Полная обратимость: чисто текстовое изменение, нет миграций/состояния/kill-switch.
|
||||
- **−** Правило нормативно, не enforced машинно → дисциплина + ревью (осознанный компромисс).
|
||||
- **−** Рост `reviewer.md` на короткую врезку (митигейшн: точечность, без переписывания).
|
||||
- **Откат:** `git revert` PR — доки/промпт/тест откатываются, поведение кода/гейтов идентично.
|
||||
|
||||
## Связи
|
||||
- Замыкает: adr-0019 (52b), adr-0020 (52c), adr-0021 (52d), adr-0022 (52e).
|
||||
- Per-work-item: `docs/work-items/ORCH-079/06-adr/ADR-001-readme-sync-and-reviewer-overview-docs-axis.md`.
|
||||
- Сверено по коду: `src/agents/launcher.py` (`ensure_worktree`, `_resolve_timeout`),
|
||||
`src/queue_worker.py` (backoff/breaker), `src/qg/checks.py:82,381`, `src/plane_sync.py:451,541`,
|
||||
`README.md:236–241`, `.openclaw/agents/reviewer.md`, `tests/test_agent_prompts_canon.py`.
|
||||
</content>
|
||||
@@ -1,59 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-063
|
||||
stage: architecture
|
||||
author_agent: architect
|
||||
status: proposed
|
||||
created_at: 2026-06-09
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# adr-0024: Disk-watchdog — фоновый heartbeat-демон мониторинга заполнения хост-ФС
|
||||
|
||||
> Сквозной (cross-cutting) ADR: вводит **новый фоновый компонент** оркестратора в ряду
|
||||
> `reconciler` (adr-0007) и `job_reaper` (adr-0011). Детальное решение задачи —
|
||||
> `docs/work-items/ORCH-063/06-adr/ADR-001-disk-watchdog.md`.
|
||||
|
||||
## Статус
|
||||
Proposed (ORCH-063)
|
||||
|
||||
## Контекст
|
||||
07.06.2026 диск хоста mva154 тихо дорос до 100% и положил **весь self-hosting-конвейер** (один
|
||||
прод-инстанс `orchestrator` обслуживает все прод-проекты из общей БД/очереди). Проактивного сигнала
|
||||
о заполнении диска у системы не было. Оркестратор уже имеет два проверенных фоновых daemon-потока с
|
||||
единым каркасом (`threading.Thread(daemon=True)` + `threading.Event`, `start/stop/status`,
|
||||
never-raise, снимок в `GET /queue`): `reconciler` (ORCH-053) и `job_reaper` (ORCH-065). Новый
|
||||
эксплуатационный watchdog логично встроить тем же паттерном.
|
||||
|
||||
## Решение
|
||||
Вводится третий фоновый компонент **disk-watchdog** (`src/disk_watchdog.py`):
|
||||
- **Калька каркаса** `reconciler`/`reaper`: daemon-поток, чистый stop через `_stop.wait(interval)`,
|
||||
контракт `start()`/`stop(timeout)`/`status()`, старт/стоп в `main.lifespan` (старт последним —
|
||||
после `reaper.start()`; стоп первым в reverse-порядке), наблюдаемость — аддитивный блок
|
||||
`disk_monitor` в `GET /queue`.
|
||||
- **Замер** заполнения **хост-ФС** через смонтированные bind-пути (`/repos`, `/app/data`) stdlib
|
||||
`shutil.disk_usage` (не overlay `/` контейнера, не субпроцесс `df`); дедуп путей по `st_dev`.
|
||||
- **Решение об алерте** — pure-функция от `(used_pct, threshold, prev_state, now, realert_s)`:
|
||||
алерт на пересечении порога (дефолт 85%), ограниченный cooldown-повтор, recovery при возврате
|
||||
ниже порога. Состояние анти-спама — in-memory (без миграции БД).
|
||||
- **Алерт** — `send_telegram` (notifying), best-effort. Kill-switch `disk_monitor_enabled`.
|
||||
- **Только сигнал, не лечение:** watchdog читает и уведомляет, не трогает диск/контейнер, не
|
||||
рестартит прод (self-hosting безопасность). Авто-очистка диска — отдельная задача.
|
||||
|
||||
**Инварианты:** `STAGE_TRANSITIONS`, реестр `QG_CHECKS`, `check_*`, схема БД — **не меняются**
|
||||
(watchdog — эксплуатационный демон, не Quality Gate, как `reconciler`/`reaper`). never-raise на
|
||||
уровнях per-path / per-tick / per-send. При выключенном kill-switch — поведение 1:1 как сейчас
|
||||
(нулевая регрессия для enduro-trails).
|
||||
|
||||
## Последствия
|
||||
- **+** Ранний сигнал предотвращает групповой простой всех проектов; дёшево, без внешних
|
||||
зависимостей (принцип «всё в Docker на одном сервере, минимум зависимостей»).
|
||||
- **+** Знакомый паттерн фонового демона → низкий риск, простое сопровождение.
|
||||
- **−** In-memory состояние / best-effort Telegram — допустимы для раннего сигнала (не SLA).
|
||||
- **Откат:** `ORCH_DISK_MONITOR_ENABLED=false`; миграций БД нет.
|
||||
|
||||
## Ссылки
|
||||
- Задачный ADR: `docs/work-items/ORCH-063/06-adr/ADR-001-disk-watchdog.md`
|
||||
- Родственные компоненты: [adr-0007-reconciler.md](adr-0007-reconciler.md),
|
||||
[adr-0011-job-reaper-lease-reclaim.md](adr-0011-job-reaper-lease-reclaim.md)
|
||||
- Топология host-разделов: `docs/operations/INFRA.md`
|
||||
</content>
|
||||
@@ -1,86 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-062
|
||||
stage: architecture
|
||||
author_agent: architect
|
||||
status: proposed
|
||||
created_at: 2026-06-09
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# adr-0025: Build-cache-pruner — фоновый heartbeat-демон авто-уборки docker build cache на хосте
|
||||
|
||||
> Сквозной (cross-cutting) ADR: вводит **новый фоновый компонент** оркестратора в ряду
|
||||
> `reconciler` (adr-0007), `job_reaper` (adr-0011) и `disk_watchdog` (adr-0024). Детальное
|
||||
> решение задачи — `docs/work-items/ORCH-062/06-adr/ADR-001-build-cache-pruner.md`.
|
||||
|
||||
## Статус
|
||||
Proposed (ORCH-062)
|
||||
|
||||
## Контекст
|
||||
|
||||
07.06.2026 диск хоста mva154 тихо дорос до 100% и положил **весь self-hosting-конвейер всех
|
||||
проектов** (один прод-инстанс `orchestrator` на общей БД/очереди). Доминирующий «пожиратель» —
|
||||
**docker build cache** (≈11 ГБ от частых пересборок прод/staging-образов). `disk_watchdog`
|
||||
(adr-0024, ORCH-063) ввёл **сигнал** о заполнении (Telegram ≥85%) и явно отложил авто-очистку в
|
||||
отдельную задачу. ORCH-062 — эта задача: **автоматическое освобождение build cache**, чтобы
|
||||
инцидент не повторялся без оператора.
|
||||
|
||||
Сверено по коду: контейнер `orchestrator` **не содержит docker CLI** (`Dockerfile:11` — только
|
||||
`openssh-client git curl`); host-docker-операции приложение уже делает **через ssh на хост**
|
||||
(`image_freshness.image_revision`, `self_deploy` Phase B), канал `deploy_ssh_user@deploy_ssh_host`
|
||||
настроен. У оркестратора три проверенных фоновых daemon-потока с единым каркасом.
|
||||
|
||||
## Решение
|
||||
|
||||
Вводится четвёртый фоновый компонент **build-cache-pruner** (`src/build_cache_pruner.py`):
|
||||
- **Калька каркаса** `disk_watchdog`/`reconciler`/`reaper`: daemon-поток, чистый стоп через
|
||||
`_stop.wait(interval)`, контракт `start()`/`stop(timeout)`/`status()`, старт/стоп в
|
||||
`main.lifespan` (старт последним — после `disk_watchdog.start()`; стоп первым в reverse),
|
||||
наблюдаемость — аддитивный блок `build_cache_prune` в `GET /queue`. Leaf-модуль (без обратных
|
||||
зависимостей на `stage_engine`/`stages`/`qg`).
|
||||
- **Уборка — строго `docker builder prune -f --filter until=<until>`** (BuildKit GC, дефолт
|
||||
`until=24h`): удаляется только старый build cache, тёплый ≤24ч сохраняется. `-a` — опционально и
|
||||
только в паре с возрастным фильтром. **Запрещены** `docker image prune`/`system prune`/удаление
|
||||
образов запущенных сервисов/остановка-рестарт контейнеров.
|
||||
- **Исполнение на хосте через ssh** (CLI в контейнере нет): `ssh deploy_ssh_user@deploy_ssh_host
|
||||
"docker builder prune …"`, bounded таймаутом. **Нет ssh-таргета → тик no-op** → фича
|
||||
естественно скоупится на self-hosting-прод.
|
||||
- **Конфиг/kill-switch** (`ORCH_BUILD_CACHE_PRUNE_*`, дефолты безопасные): `enabled` (дефолт
|
||||
`true`), `interval_s` (6ч), `until` (`24h`), `all` (`false`), `timeout_s`, `notify_min_gb`.
|
||||
Валидаторы по образцу `disk_monitor_*` (невалид → лог + дефолт).
|
||||
- **Сигнал + лечение как пара:** disk_watchdog сигналит о росте диска, build-cache-pruner убирает
|
||||
доминирующего «пожирателя» — две половины одной операционной защиты.
|
||||
|
||||
**Инварианты:** `STAGE_TRANSITIONS`, реестр `QG_CHECKS`, `check_*`, `src/stage_engine.py`, схема БД
|
||||
— **не меняются** (pruner — эксплуатационный демон, не Quality Gate, как watchdog/reaper). Без
|
||||
миграции БД (учёт результата in-memory, best-effort). never-raise per-команда/per-tick. Уборка
|
||||
**никогда** не рестартит docker daemon/прод-контейнер (self-hosting безопасность; рестарт-путь —
|
||||
отвергнутый Вариант B). При выключенном kill-switch — поведение 1:1 как сейчас (нулевая регрессия
|
||||
для enduro-trails).
|
||||
|
||||
## Альтернативы
|
||||
- **host `daemon.json builder.gc.defaultKeepStorage`** — отвергнуто: требует рестарта docker
|
||||
daemon (останавливает ВСЕ контейнеры хоста = групповой self-hosting риск); политика по объёму,
|
||||
не по возрасту; не наблюдаемо в `GET /queue`.
|
||||
- **host-cron** — отвергнуто как основное (оставлено ручным fallback): off-git невидимая инфра,
|
||||
без `/queue`-наблюдаемости, без config-kill-switch, не тестируется.
|
||||
- **raw-HTTP по docker.sock / docker CLI в образе** — отвергнуто: лишний код / раздувание образа
|
||||
против уже существующего ssh-канала.
|
||||
|
||||
## Последствия
|
||||
- **+** Корень инцидента 07.06 устраняется автоматически; тёплый кэш сохранён; без новых
|
||||
зависимостей и без рестарта docker/прода (принцип «всё в Docker, минимум зависимостей»).
|
||||
- **+** Знакомый паттерн фонового демона → низкий риск, наблюдаемость, обратимость, тестируемость.
|
||||
- **−** Зависимость от ssh на хост (как `image_freshness`/`self_deploy`); нет таргета → no-op
|
||||
(наблюдаемо), фича не работает, но ничего не ломает.
|
||||
- **Откат:** `ORCH_BUILD_CACHE_PRUNE_ENABLED=false`; миграций БД нет.
|
||||
|
||||
## Ссылки
|
||||
- Задачный ADR: `docs/work-items/ORCH-062/06-adr/ADR-001-build-cache-pruner.md`
|
||||
- Инфра/риски: `docs/work-items/ORCH-062/07-infra-requirements.md`,
|
||||
`docs/work-items/ORCH-062/10-tech-risks.md`
|
||||
- Комплемент: [adr-0024-disk-watchdog.md](adr-0024-disk-watchdog.md) (ORCH-063 — сигнал)
|
||||
- Родственные компоненты: [adr-0007-reconciler.md](adr-0007-reconciler.md),
|
||||
[adr-0011-job-reaper-lease-reclaim.md](adr-0011-job-reaper-lease-reclaim.md)
|
||||
- Топология host / env-карта: `docs/operations/INFRA.md`
|
||||
</content>
|
||||
@@ -1,106 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-090
|
||||
stage: architecture
|
||||
author_agent: architect
|
||||
status: proposed
|
||||
created_at: 2026-06-09
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# ADR-0026: Системное терминальное состояние `cancelled` — STOP-отмена задачи
|
||||
|
||||
Сквозной (cross-cutting) ADR. Детальное решение задачи —
|
||||
`docs/work-items/ORCH-090/06-adr/ADR-001-stop-cancel-task.md`.
|
||||
|
||||
## Статус
|
||||
Proposed
|
||||
|
||||
## Контекст
|
||||
|
||||
ORCH-090 вводит Plane-статус **STOP** — единый декларативный механизм отмены задачи (остановка
|
||||
агента + полный сброс прогресса). Самое́ кросс-каттинговое следствие — появление **нового
|
||||
системного терминального состояния `cancelled`** (стадия `tasks.stage='cancelled'` + терминальный
|
||||
job-статус `jobs.status='cancelled'`). До ORCH-090 «терминальность задачи» в горячем планировщике
|
||||
была захардкожена как **`stage == 'done'`** (единственный сток в `STAGE_TRANSITIONS`), и это
|
||||
определение разъехалось между подсистемами:
|
||||
|
||||
- `src/reconciler.py` **уже** трактует `stage in ("done","cancelled")` как терминал-скип
|
||||
(ORCH-086 D2 предвосхитил `cancelled`; стр. 196) и `_is_terminal_state` по группе Plane
|
||||
`{completed, cancelled}` (ORCH-068, стр. 398–415).
|
||||
- `src/serial_gate.py` (ORCH-088) и `src/task_deps.py` (ORCH-026) считают задачу «незавершённой»
|
||||
по `stage != 'done'` — **без** `cancelled`. Если ввести `cancelled`-стадию, не тронув их,
|
||||
отменённая задача навсегда будет «активной»/«незавершённой зависимостью» и **заклинит очередь
|
||||
репо**.
|
||||
|
||||
Этот ADR фиксирует `cancelled` как первоклассное терминальное состояние, равноправное `done`, и
|
||||
перечисляет ВСЕ точки, где системный предикат терминальности должен его признавать.
|
||||
|
||||
## Решение
|
||||
|
||||
### Инвариант
|
||||
**«Задача терминальна» ⇔ `stage ∈ {done, cancelled}`.** Это единое определение для всех
|
||||
подсистем планировщика/мониторинга. `cancelled` — терминальный **сток** (не новое ребро
|
||||
конвейера): exit-гейты рёбер `STAGE_TRANSITIONS` и реестр `QG_CHECKS`/`check_*` **не меняются**.
|
||||
|
||||
### Точки, признающие `cancelled` терминальным (исчерпывающе)
|
||||
1. `src/stages.py::STAGE_TRANSITIONS` — добавить сток
|
||||
`"cancelled": {"next": None, "agent": None, "qg": None}` (параллельно `done`).
|
||||
2. `src/serial_gate.py` — `repo_has_other_unfinished` и claim-фрагмент `t2.stage != 'done'`,
|
||||
snapshot: `stage != 'done'` → `stage NOT IN ('done','cancelled')`. **(маркер ORCH-088)**
|
||||
3. `src/task_deps.py` — dep-gate и `is_task_ready`: `stage != 'done'` →
|
||||
`stage NOT IN ('done','cancelled')`. **(маркер ORCH-026)**
|
||||
4. `src/reconciler.py` — уже покрыто скипом `stage in ("done","cancelled")` (стр. 196);
|
||||
`get_active_tasks_for_reconcile` опционально сузить до `NOT IN ('done','cancelled')`.
|
||||
5. `src/job_reaper.py` / `src/queue_worker.py` — перед авто-requeue dead/running-job'а сверять
|
||||
терминал задачи: `stage in ("done","cancelled")` → job помечается `cancelled`, не реквью'ится.
|
||||
6. `src/post_deploy.py` / `stage_engine.run_post_deploy_monitor` — монитор не тикает по
|
||||
отменённой задаче (терминал-проверка/маркер `done`).
|
||||
|
||||
### Новые терминальные исходы
|
||||
- **Job:** `jobs.status='cancelled'` — нигде не реквью'ится; `claim_next_job` выбирает только
|
||||
`status='queued'` (изменений в claim нет). `mark_job` стампит `finished_at` для `cancelled`.
|
||||
- **Задача:** `tasks.stage='cancelled'` + аддитивные колонки `cancelled_at`,
|
||||
`cancel_requested_at` (отложенная отмена в критическом окне merge/deploy). Натуральные ключи
|
||||
`plane_id`/`work_item_id` тумбстонятся (`#cancelled-<id>`) для переиспользования «To Analyse»
|
||||
с нуля; `plane_issue_id` сохраняется (аудит). Детали — 08-data-requirements.md.
|
||||
|
||||
### Точки врезки STOP (компоненты)
|
||||
- `plane.py` — маршрут `stop` (fail-closed, не в `_DEFAULT_STATES`) → `handle_stop`; гейт релонча
|
||||
ограничен стадией `analysis`.
|
||||
- `stage_engine.cancel_task` — оркестрация отмены (graceful SIGTERM, cancel-jobs, worktree+branch,
|
||||
tombstone, notify); безопасное прерывание merge/deploy (D7 локального ADR).
|
||||
- leaf `src/cancel.py` — чистая логика (`applies`/`in_critical_window`/`snapshot`), never-raise.
|
||||
- `src/gitea.py` — `delete_remote_branch` (never-raise; только feature-ветка, `main` неприкосновенен).
|
||||
- `GET /queue` — read-only блок `stop`.
|
||||
|
||||
### Флаги / совместимость
|
||||
- Kill-switch `stop_status_enabled` + scope `stop_status_repos` (CSV, пусто → все репо).
|
||||
- При `stop_status_enabled=False`: STOP-обработка и гейт релонча инертны; расширение
|
||||
терминал-набора `cancelled` безвредно при отсутствии отменённых задач → **нулевая регрессия**.
|
||||
- `STAGE_TRANSITIONS` (exit-гейты) / `QG_CHECKS` / `check_*` / семантика
|
||||
Approved/Rejected/Confirm Deploy / merge-gate (ORCH-043) / merge-verify (ORCH-071/073) /
|
||||
image-freshness (ORCH-058) / post-deploy (ORCH-021) / serial-gate FIFO (ORCH-088) / auto-label
|
||||
(ORCH-089) — **без изменений**.
|
||||
- Миграции БД — только аддитивные/идемпотентные (`_ensure_column`); enduro не затронут (NFR-2).
|
||||
|
||||
## Последствия
|
||||
- **+** Единое, консистентное определение терминальности — устранён латентный рассинхрон
|
||||
`done`-only между планировщиком и реконсилятором.
|
||||
- **+** STOP безопасен для self-hosting: не трогает `main`/прод, отложенная отмена в критическом
|
||||
окне.
|
||||
- **−** Терминальность теперь читается из набора `{done, cancelled}`, а не из скаляра `'done'` —
|
||||
будущие подсистемы обязаны использовать набор. Митигейшн: этот ADR + маркер `ORCH-090` в
|
||||
изменённых местах + тесты.
|
||||
- **Откат:** `stop_status_enabled=False`; полный revert — снять врезки и вернуть предикаты к
|
||||
`stage != 'done'`.
|
||||
|
||||
## Эволюция маркеров `cancelled`-терминала
|
||||
Места, признающие `cancelled` терминальным (см. список выше), несут маркер `ORCH-090`. Правка
|
||||
любого из них — сверяться с этим ADR (анти-археология: 3+ маркеров → одна ссылка сюда,
|
||||
TRACEABILITY.md).
|
||||
|
||||
## Ссылки
|
||||
- Детальный ADR: `docs/work-items/ORCH-090/06-adr/ADR-001-stop-cancel-task.md`
|
||||
- Data: `docs/work-items/ORCH-090/08-data-requirements.md`
|
||||
- Связанные: adr-0017 (serial-gate), adr-0015 (task-deps), adr-0007 (self-deploy),
|
||||
adr-0006 (merge-gate), adr-0018 (auto-label)
|
||||
@@ -1,82 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-093
|
||||
stage: architecture
|
||||
author_agent: architect
|
||||
status: proposed
|
||||
created_at: 2026-06-09
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# adr-0027: Merge-актор — ретрай транзиентных ошибок Gitea + гард «ветка уже в `main`»
|
||||
|
||||
Сквозной (cross-cutting) ADR. **Амендмент** к [adr-0013](adr-0013-merge-verify-gate.md) (merge-verify
|
||||
под-гейт), [adr-0014](adr-0014-merge-verify-sha-source-of-truth.md) (SHA-в-main как источник истины)
|
||||
и [adr-0016](adr-0016-ensure-open-pr-before-merge-verify.md) (гарантированный код-PR). Детальное
|
||||
решение задачи — `docs/work-items/ORCH-093/06-adr/ADR-001-merge-transient-retry-and-already-in-main-guard.md`.
|
||||
|
||||
> Регистрируется как сквозной, т.к. правит блок merge-актора с **3+ маркерами** (`ORCH-071`,
|
||||
> `ORCH-073`, `ORCH-082`) — анти-археология маркеров (`docs/_standards/TRACEABILITY.md`): сводный
|
||||
> ADR агрегирует эволюцию вместо перечисления work item в коде.
|
||||
|
||||
## Статус
|
||||
Proposed
|
||||
|
||||
## Контекст
|
||||
|
||||
Детерминированный merge-актор merge-verify под-гейта (`deploy → done`, self-hosting) состоит из
|
||||
`ensure_open_pr` → `merge_pr` → `verify_merged_to_main` (`src/merge_gate.py`). Инцидент **ORCH-063
|
||||
(09.06)** вскрыл два дефекта, оба сверены по коду прода:
|
||||
|
||||
1. `merge_pr` — **one-shot**: `POST /pulls/{index}/merge`, любой не-`200/201` → мгновенный `False`.
|
||||
Транзиентная икота Gitea (`405 "Please try again later"` при пересчёте `mergeable` сразу после
|
||||
пуша; `5xx`; таймаут) → ложный HOLD защиты ORCH-071/073 → ручной домерж.
|
||||
2. `ensure_open_pr` — после ручного мержа код-PR `closed`, открытый не найден → создаёт **новый
|
||||
пустой PR** на ветке, уже целиком в `main`.
|
||||
|
||||
Защита ORCH-071/073 («deploy succeeded but not merged») корректна и сохраняется; задача снижает
|
||||
лишь **ложные** срабатывания на транзиентах и устраняет мусорные PR. Это блокер автономного прогона
|
||||
(эпик ORCH-088).
|
||||
|
||||
## Решение
|
||||
|
||||
Аддитивно, без правки `STAGE_TRANSITIONS` / `QG_CHECKS` / схемы БД; INV-4 (мерж только через Gitea
|
||||
PR-merge API; никогда `push`/`force-push` в `main`) и never-raise сохранены.
|
||||
|
||||
- **Ретрай-loop вокруг `POST …/merge`** (только мутирующий вызов) до `merge_retry_max_attempts`
|
||||
(дефолт 3) с экспоненциальным backoff и потолком (`base 2`, `max 5`; суммарно ≤10 с). Классификатор
|
||||
**транзиент** (`405`/`408`/`5xx`/таймаут/сетевое; `409`/`422` при `mergeable==True`; `mergeable==None`
|
||||
→ транзиент-по-дефолту в рамках бюджета) vs **терминал** (`403`/`404`; `409`/`422` при
|
||||
`mergeable==False`) — по коду ответа **и** полю `mergeable` (`GET /pulls/{index}`). Терминал →
|
||||
быстрый честный `False` (защита ORCH-071/073 — как прежде). Образец — `check_ci_green`
|
||||
(`attempt i/N`) + transient-breaker агентов.
|
||||
- **Гард already-in-main в `ensure_open_pr`**: перед созданием PR — `git merge-base --is-ancestor
|
||||
<branch> origin/main` (rc==0 → ветка целиком в `main`) → новый исход `"already-in-main"`, PR не
|
||||
создаётся; git-ошибка/ambiguous → **fail-OPEN** на текущий create-путь (гард не должен превратить
|
||||
икоту git в ложный no-op мержа). `_handle_merge_verify` трактует `"already-in-main"` как «мержить
|
||||
нечего» → пропуск `merge_pr` → авторитетный SHA-в-main (`verify_merged_to_main`, ADR-0014) доводит
|
||||
до `done` без мусорного PR.
|
||||
- **Конфиг**: `merge_retry_enabled` (kill-switch; `False` → one-shot, нулевая регрессия),
|
||||
`merge_retry_max_attempts`, `merge_retry_backoff_base_s`, `merge_retry_backoff_max_s`
|
||||
(env `ORCH_MERGE_RETRY_*`). Гард already-in-main — без отдельного флага (накрыт существующим
|
||||
`merge_verify_autocreate_pr_enabled`).
|
||||
|
||||
Объём раската — реально только self-hosting (`merge_verify_applies`); на прочих репо мерж делает
|
||||
LLM-deployer → изменение нейтрально.
|
||||
|
||||
## Последствия
|
||||
|
||||
- **+** Транзиент Gitea переживается автоматически → нет ложного HOLD / ручного домержа в автономном
|
||||
конвейере; нет мусорных пустых PR; повтор финализатора идемпотентен.
|
||||
- **+** Реальный конфликт → быстрый честный HOLD; защита ORCH-071/073 и SHA-в-main (ADR-0014) —
|
||||
авторитетны и неизменны.
|
||||
- **−** Дефолт `mergeable==None → transient` может добавить ≤10 с до HOLD на реальном конфликте
|
||||
(бюджет жёстко ограничен); один лишний `GET /pulls/{index}` в редком ambiguous-кейсе.
|
||||
- **Откат:** `ORCH_MERGE_RETRY_ENABLED=false` → one-shot; `ORCH_MERGE_VERIFY_AUTOCREATE_PR_ENABLED=false`
|
||||
→ отключает врезку `ensure_open_pr` с гардом. Полный откат — revert PR.
|
||||
|
||||
## Ссылки
|
||||
- Детальный ADR: `docs/work-items/ORCH-093/06-adr/ADR-001-merge-transient-retry-and-already-in-main-guard.md`
|
||||
- Лехатая: [adr-0006](adr-0006-merge-gate.md), [adr-0013](adr-0013-merge-verify-gate.md),
|
||||
[adr-0014](adr-0014-merge-verify-sha-source-of-truth.md),
|
||||
[adr-0016](adr-0016-ensure-open-pr-before-merge-verify.md)
|
||||
- Код: `src/merge_gate.py`, `src/stage_engine.py::_handle_merge_verify`, `src/config.py`
|
||||
@@ -1,96 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-094
|
||||
stage: architecture
|
||||
author_agent: architect
|
||||
status: proposed
|
||||
created_at: 2026-06-09
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# adr-0028: Terminal-window-aware гард выставления deploy-фазовых статусов Plane
|
||||
|
||||
Сквозной (cross-cutting) ADR. **Амендмент** к [adr-0010](adr-0010-post-deploy-monitor.md)
|
||||
(post-deploy monitor, ORCH-021) и Plane-статусной модели (ORCH-066): вводит инвариант
|
||||
«deploy-фазовые Plane-статусы — terminal-window-aware» поверх общих сеттеров `plane_sync` и
|
||||
переупорядочивает блок `next_stage == "done"` в `advance_stage`. Детальное решение задачи —
|
||||
`docs/work-items/ORCH-094/06-adr/ADR-001-terminal-window-aware-deploy-status-guard.md`.
|
||||
|
||||
> Регистрируется как сквозной, т.к. правит **общие** сеттеры `set_issue_awaiting_deploy`/
|
||||
> `set_issue_deploying`/`set_issue_monitoring` (используются системно) и трогает маркированный блок с
|
||||
> `ORCH-021`/`ORCH-066` (`docs/_standards/TRACEABILITY.md`).
|
||||
|
||||
## Статус
|
||||
Proposed
|
||||
|
||||
## Контекст
|
||||
|
||||
Терминальная (`done`) задача в Plane **не держит `Done`**: непрерывный флапп
|
||||
`Awaiting Deploy ⟷ Monitoring after Deploy` (верифицировано живьём на **ORCH-061**, task 47, done с
|
||||
07.06 — 273 активности, само не затихает). Установлено по коду/логам/БД прода:
|
||||
|
||||
- Три code-писателя deploy-фазовых статусов (`src/stage_engine.py:404/1218/1316`) делегируют в тонкие
|
||||
сеттеры `src/plane_sync.py`, которые **БД-стадию не читают** ⇒ терминал-слепы: любой повторный вызов
|
||||
перезаписывает `Done` обратно на промежуточный статус.
|
||||
- **Ordering:** `update_task_stage("done")` (`stage_engine.py:369`) пишет `tasks.stage='done'`
|
||||
**раньше** легитимного `set_issue_monitoring` (стр. 404) ⇒ пост-деплой-окно ORCH-021 — by-design
|
||||
индикация поверх уже-`done` задачи. Наивный гард «stage==done → Done» ⇒ регресс легитимного окна.
|
||||
- Актор всех 273 переходов — бот-токен орка (`daf4d3f4-…`), не привязан к активной task/job; в БД нет
|
||||
активного post-deploy-monitor для task 47 (окно 15 мин закрыто). Реконсилятор F-1 пропускает
|
||||
`done`/`cancelled`, F-2 опрашивает только `[to_analyse, approved, rejected]` ⇒ механизма привести
|
||||
застрявшую на deploy-статусе done-задачу к `Done` нет.
|
||||
|
||||
## Решение
|
||||
|
||||
**Единый terminal-window-aware гард на низком чокпоинте** — на входе трёх deploy-фазовых сеттеров
|
||||
`plane_sync`. Чистую логику держит **новый leaf-модуль `src/deploy_status_guard.py`** (never-raise,
|
||||
config-gated; образец `serial_gate.py`/`labels.py`/`cancel.py`); сеттеры исполняют вердикт.
|
||||
|
||||
- **Инвариант легитимности:** deploy-фазовый статус легитимен ⇔ задача **нетерминальна** ИЛИ
|
||||
(`done` **И** активно пост-деплой-окно). Иначе — идемпотентное схождение к `Done`.
|
||||
`decide(work_item_id, target) -> ALLOW | CONVERGE_DONE | SUPPRESS`:
|
||||
kill-switch off / чужой issue / не-self репо / нетерминал → **ALLOW**; `cancelled` → **SUPPRESS**;
|
||||
`done` + `target==monitoring` + `window_active` → **ALLOW**; `done` иначе → **CONVERGE_DONE**
|
||||
(`set_issue_done`, идемпотентно); любое исключение → **ALLOW** + warning (never-raise).
|
||||
- **Новый helper** `post_deploy.window_active(repo, wi)` = `has_marker(ARMED) and not
|
||||
has_marker(DONE)` (restart-safe).
|
||||
- **Перенос арм-блока** (`post_deploy.arm_monitor`) **перед** terminal-sync в блоке
|
||||
`next_stage == "done"`: на стр. 404 `ARMED` уже записан ⇒ `window_active==True` ⇒ легитимный первый
|
||||
`Monitoring` проходит; re-drive после закрытия окна сходится к `Done`.
|
||||
- **Харднинг монитора:** идемпотентный страж `has_marker(...DONE)` (ранний return без PATCH/реэнкью)
|
||||
+ тик no-op при `cancelled` мид-окно; тики привязаны к активному job'у (нет job → нет тика).
|
||||
- **Наблюдаемость:** каждый вердикт логируется (`work_item`/`caller`/`target`/`db_stage`/
|
||||
`window_active`/вердикт); подавление/схождение — явно.
|
||||
- **Флаги** (`config.py`): `deploy_status_guard_enabled=True`
|
||||
(`ORCH_DEPLOY_STATUS_GUARD_ENABLED`, kill-switch → 1:1) + `deploy_status_guard_repos=""`
|
||||
(`ORCH_DEPLOY_STATUS_GUARD_REPOS`, пусто → self-hosting only) с локальным `applies(repo)`.
|
||||
|
||||
## Альтернативы
|
||||
|
||||
- **Гард в caller'ах `stage_engine`** — отвергнуто: не ловит неизвестный/стейл путь под бот-токеном,
|
||||
размазывает инвариант.
|
||||
- **Наивный «stage==done → Done» без предиката окна** — отвергнуто: регресс легитимного `Monitoring`.
|
||||
- **Bypass-флаг на доверенном вызове 404** — отвергнуто в пользу переноса арм-блока (один предикат).
|
||||
- **Активная сходимость в реконсиляторе F-2** — отвергнуто как основной механизм (лишний polling,
|
||||
правка маркированного F-2); гард на сеттере гасит непрерывный флапп.
|
||||
|
||||
## Последствия
|
||||
|
||||
- Терминальная задача стабильно держит `Done`; маятник гаснет за один цикл независимо от актора.
|
||||
- Легитимный пост-деплой `Monitoring` и рабочий self-deploy-цикл — 1:1 (предикат окна + перенос арм).
|
||||
- `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / machine-verdict ключи / схема БД — **не тронуты**.
|
||||
- `main`/force-push/прод-контейнер/detached-деплой — не тронуты; не-self репо инертны.
|
||||
- Ограничение: если актор флаппа — внешняя Plane-automation (вне кода орка), гард — буфер на стороне
|
||||
орка; локализация (FR-1) и итог документируются (BR-7).
|
||||
- **Откат:** `ORCH_DEPLOY_STATUS_GUARD_ENABLED=false` → поведение 1:1; полный — revert ветки.
|
||||
|
||||
## Связи
|
||||
|
||||
- [adr-0010](adr-0010-post-deploy-monitor.md) (ORCH-021 — пост-деплой-окно, sentinel `armed`/`done`,
|
||||
арм-блок) — амендмент: окно становится предикатом легитимности `Monitoring`.
|
||||
- ORCH-066 (Plane-статусная модель — слой B индикации; `deploy→done` self ⇒ `Monitoring`) — инвариант
|
||||
сохранён.
|
||||
- [adr-0026](adr-0026-stop-cancel-task.md) (ORCH-090 — терминал `cancelled`) — гард не штампует
|
||||
deploy-статус поверх `cancelled`.
|
||||
- ORCH-068/086 (терминал-скип реконсилятора) — этот ADR распространяет идею терминал-aware на
|
||||
выставление deploy-статусов.
|
||||
- Детально: `docs/work-items/ORCH-094/06-adr/ADR-001-terminal-window-aware-deploy-status-guard.md`.
|
||||
@@ -1,92 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-027
|
||||
stage: architecture
|
||||
author_agent: architect
|
||||
status: proposed
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# adr-0029: Гейт покрытия тестами — edge sub-gate + ratchet-базовая линия
|
||||
|
||||
- **Статус:** proposed
|
||||
- **Дата:** 2026-06-10
|
||||
- **Задача:** ORCH-027
|
||||
- **Детальный ADR:** `docs/work-items/ORCH-027/06-adr/ADR-001-coverage-gate.md`
|
||||
|
||||
## Контекст
|
||||
Оркестратор автономен: `developer` пишет код без человека-фильтра, `tester` сам решает, хватает
|
||||
ли тестов. Существующие тестовые гейты судят только по факту прохождения, не по полноте:
|
||||
`check_ci_green` (exit-code CI), `check_tests_passed` (LLM-вердикт `tester`'а), merge-gate
|
||||
re-test (exit-code). Ни один не замечает «300 строк кода, 0 тестов». При пакетном автономном
|
||||
прогоне (ORCH-088) это монотонная деградация покрытия. Нужна детерминированная метрика — по духу
|
||||
как security-гейт (adr-0012).
|
||||
|
||||
## Решение
|
||||
Детерминированный (без LLM) **гейт покрытия как под-гейт ребра `deploy-staging → deploy`**,
|
||||
рядом с security-gate (ORCH-022), merge-gate (ORCH-043), image-freshness (ORCH-058). Паттерн —
|
||||
leaf-модуль `src/coverage_gate.py` (never-raise) + обёртка в `QG_CHECKS` (`check_coverage_gate`)
|
||||
+ врезка `_handle_coverage_gate` в `advance_stage`. `STAGE_TRANSITIONS` не меняется.
|
||||
|
||||
- **Порядок: security → merge → `coverage` → image-freshness.** Coverage идёт **ПОСЛЕ
|
||||
merge-gate** (ветка догнана на свежий `origin/main` → меряем покрытие того кода, что landed) и
|
||||
**ДО image-freshness** (фейлить дёшево до docker-rebuild). На этой точке merge-lease **held** →
|
||||
**FAIL обязан освободить lease** при откате (как image-freshness rollback; в отличие от
|
||||
security, который идёт до захвата lease).
|
||||
- **Измеритель:** `pytest-cov` (`coverage.py`), `python -m pytest tests/ --cov=src
|
||||
--cov-report=json` в изолированном worktree (`ensure_worktree`); метрика —
|
||||
`totals.percent_covered`. Тайм-аут `coverage_run_timeout_s`. Скоуп — `src/` (не тесты).
|
||||
- **Чистая функция** `compute_coverage_verdict(measured, baseline, floor, policy, epsilon)`:
|
||||
`absolute` (≥floor−ε), `baseline` (≥baseline−ε, ratchet), `both` (дефолт). `baseline=None` →
|
||||
bootstrap (только absolute). FAIL → откат на `development` + developer-retry (cap
|
||||
`MAX_DEVELOPER_RETRIES`), дословный reason в `task_desc` (ORCH-046).
|
||||
- **Базовая линия — аддитивная БД-таблица** `coverage_baseline(repo PK, coverage, source_sha,
|
||||
updated_at)` (`CREATE TABLE IF NOT EXISTS`, паттерн `repo_freeze`/`job_deps`). Выбор БД над
|
||||
файлом-в-репо: нет git-churn/конфликтов на ratchet, restart-safe, атомарное обновление.
|
||||
- **Ratchet-up** в choke-point подтверждённого merge `_handle_merge_verify` (ребро
|
||||
`deploy → done`, ORCH-071/073): читает измеренное покрытие из `18-coverage-report.md`,
|
||||
атомарный compare-and-set `UPDATE ... WHERE coverage <= measured` (базовая линия не падает).
|
||||
Под held merge-lease + per-repo сериализацией merge (ORCH-043) — двойная анти-гонка.
|
||||
- **Артефакт `18-coverage-report.md`** с frontmatter `coverage_status: PASS|FAIL` (+
|
||||
`measured_coverage`/`baseline`/`floor`/`policy`/`delta` + аддитивная 52c-схема); вердикт
|
||||
читается ТОЛЬКО из frontmatter через `src/frontmatter.py` (single source of truth).
|
||||
- **Условность (как ORCH-35/43/58):** `coverage_gate_enabled` + `coverage_gate_repos` (пусто →
|
||||
только self-hosting `orchestrator`); вне области → no-op pass. `applies(repo)` ПЕРВОЙ, дорогой
|
||||
прогон — только при applies.
|
||||
- **Ошибка инструмента → fail-open + WARNING** по умолчанию (`coverage_tool_fail_closed=False`,
|
||||
анти-петля как ORCH-061); флаг → fail-closed.
|
||||
- **Наблюдаемость:** read-only блок `coverage` в `GET /queue`; FAIL → Telegram (кликабельный
|
||||
номер, измеренное/порог/дельта). Опциональный `POST /coverage/baseline` (ручной override).
|
||||
- **never-raise**, гейт не деплоит/не рестартит прод/не пушит в `main` (NFR-3).
|
||||
|
||||
## Альтернативы
|
||||
- **CI-job (`check_ci_green`):** пороги/политика/baseline/артефакт плохо выражаются статусом
|
||||
коммита; ratchet требует записи в БД. Отклонено для v1 (точка расширения).
|
||||
- **Edge `testing → deploy-staging`:** ветка не догнана на свежий `main` → метрика неточна;
|
||||
откат не освобождает lease. Отклонено.
|
||||
- **Базовая линия в файле репо:** git-churn/конфликты на каждый ratchet. Отклонено.
|
||||
- **Новая стадия `coverage`:** «пустая» стадия без агента не имеет триггера (как ORCH-043/022).
|
||||
Отклонено.
|
||||
- **Жёсткий absolute-порог без baseline/epsilon:** массовые ложные заворота. Отклонено.
|
||||
|
||||
## Последствия
|
||||
- Класс «тихо просевшее покрытие» закрыт детерминированной метрикой; baseline только растёт.
|
||||
- Нулевая регрессия вне области (enduro-trails); `STAGE_TRANSITIONS`/`QG_CHECKS`-семантика/
|
||||
вердикт-ключи (`verdict:`/`result:`/`deploy_status:`/`staging_status:`/`security_status:`) —
|
||||
байт-в-байт прежние; новая БД-таблица аддитивна.
|
||||
- Плата: ещё один «скрытый» под-гейт ребра; новая pip-зависимость (`pytest-cov`); доп. прогон
|
||||
pytest (после merge-gate re-test, ограничен таймаутом, фейлит до rebuild); v1 — Python-only.
|
||||
- Дефолтный fail-open тихо пропускает при устойчивом сбое инструмента (с WARNING) —
|
||||
переключаемо `coverage_tool_fail_closed`.
|
||||
- Сквозное изменение (новый QG + edge-под-гейт + новая таблица + новый артефакт) →
|
||||
`arch:major-change`; прод-деплой строго через staging-гейт (8501), без рестарта прод-контейнера.
|
||||
- **Откат:** `coverage_gate_enabled=False` → полный no-op (мгновенный обратимый kill-switch).
|
||||
|
||||
## Связи
|
||||
adr-0012 (security-гейт — паттерн edge-под-гейта/leaf/never-raise/fail-open), adr-0006
|
||||
(merge-gate — edge-под-гейт/откат/merge-lease), adr-0008 (image-freshness — условность/
|
||||
fail-closed/release-lease-on-rollback), adr-0003 (условный гейт / `is_self_hosting_repo`),
|
||||
adr-0009 (анти-петля ложных FAIL, ORCH-061), adr-0013/adr-0014 (merge-verify / SHA-in-main как
|
||||
source of truth — точка ratchet), adr-0015/adr-0017 (per-repo сериализация merge/serial-gate),
|
||||
adr-0020 (frontmatter-контракт — парсинг `coverage_status:`), adr-0019 (PIPELINE_DOCS — артефакт
|
||||
`18-coverage-report.md`), ORCH-9/15 (мульти-стек — будущая зависимость BR-6).
|
||||
@@ -1,88 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-099
|
||||
stage: architecture
|
||||
author_agent: architect
|
||||
status: proposed
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# adr-0030: Лёгкий read-only `/metrics` — сырьё о самом орке для sidecar (F1b)
|
||||
|
||||
- **Статус:** proposed
|
||||
- **Дата:** 2026-06-10
|
||||
- **Задача:** ORCH-099 (FND/F1a)
|
||||
- **Детальный ADR:** `docs/work-items/ORCH-099/06-adr/ADR-001-metrics-endpoint.md`
|
||||
|
||||
## Контекст
|
||||
Эпик автономного саморазвития, домен 0 «Фундамент». Рамка наблюдаемости (заказчик): **наблюдатель
|
||||
отделён от наблюдаемого** — мозг мониторинга (пороги/алерты/история/Telegram) живёт в отдельном
|
||||
sidecar-контейнере **F1b** (`watchdog/`), а орк отдаёт **только сырьё**, которое знает лишь он сам.
|
||||
Сегодня такого источника нет: `/health` = `{"status":"ok"}`, `/status` = активные задачи, `/queue` —
|
||||
«человеческий» снимок, перемешанный с конфигом демонов. Нет стабильного машинного контракта для
|
||||
детекта застрявшей стадии / зависшего агента / деградации очереди / всплеска стоимости. F1b
|
||||
заблокирована этой задачей. Self-hosting: прод общий с enduro-trails ⇒ эндпоинт обязан быть строго
|
||||
read-only и never-raise.
|
||||
|
||||
## Решение
|
||||
Новый **leaf-модуль** `src/metrics.py` (`build_metrics() -> dict`, чистый, never-raise по разделам —
|
||||
паттерн `serial_gate.snapshot()`) + тонкий эндпоинт `@app.get("/metrics")` в `src/main.py` (стиль
|
||||
`GET /queue`). Только чтение существующих таблиц (`tasks`/`jobs`/`agent_runs`) и in-memory-снапшотов
|
||||
+ два read-only helper'а в `src/db.py`. `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict-
|
||||
ключи/схема БД — **не трогаются**.
|
||||
|
||||
- **Конверт + контракт версии:** `schema_version` (старт `1`), `generated_at` (UTC ISO-8601 —
|
||||
момент снимка, домен часов орка), `clk_tck` (`os.sysconf("SC_CLK_TCK")`), разделы
|
||||
`stages`/`queue`/`agents`/`cost`. **Политика версии:** аддитивные изменения НЕ бампят (sidecar
|
||||
обязан игнорировать незнакомые ключи и толерировать отсутствие опциональных); бамп — только при
|
||||
ломающем (rename/remove/retype). Forward-compatible контракт для F1b.
|
||||
- **`stages`** — `db.get_active_tasks_for_reconcile()` + фильтр `stage NOT IN ('done','cancelled')`
|
||||
на слое metrics (helper намеренно отдаёт `cancelled` для ORCH-086 — не трогаем его инвариант);
|
||||
поля `work_item`/`stage`/`age_in_stage_s`/`repo`.
|
||||
- **`queue`** — `db.job_status_counts()` (+`cancelled`), глубина, сырьё ретраев
|
||||
(`attempts`/`max_attempts`/`transient_attempts`/в-backoff), `worker.breaker.snapshot()`,
|
||||
`max_concurrency`. Недоступный worker → `breaker: null`, не 500.
|
||||
- **`agents` (liveness)** — новый dedicated read-only helper `db.get_running_agents()` (НЕ расширение
|
||||
hot-path `get_running_jobs()` reaper'а, ORCH-065): `agent`/`run_id`/`job_id`/`pid`/`runtime_s`
|
||||
(= `running_age_s` от `jobs.started_at`)/`model`/`effort`. CPU-сырьё — **вариант A**: орк читает
|
||||
`/proc/<pid>/stat` (поля 14+15, utime+stime) → `cpu_ticks`; **дельту не считает** — арбитр
|
||||
«жив/завис» это sidecar (stateless-эмиссия). `pid is None`/мёртвый/нет `/proc`/не-Linux →
|
||||
`cpu_ticks: null`, не ошибка.
|
||||
- **`cost`** — `running` (по running-job, часто `null` до завершения — честное сырьё, `null` ≠ ноль)
|
||||
+ `aggregate` (новый helper `db.agent_cost_totals()`, `COALESCE(SUM(...),0)` по
|
||||
`cost_usd`/`input_tokens`/`output_tokens`/`cache_read_tokens`/`cache_creation_tokens`).
|
||||
- **Kill-switch** `metrics_endpoint_enabled` (env `ORCH_METRICS_ENABLED`, дефолт `True`): при `False`
|
||||
→ `200` с `{"schema_version":1,"enabled":false}` (контракт остаётся парсимым). Операторский
|
||||
off-switch на общем инстансе.
|
||||
- **Never-raise:** каждый раздел — свой `try/except` + `logger.warning` + дефолт (`null`/`[]`/`{}`);
|
||||
`build_metrics()` никогда не пробрасывает. Read-only: ни одного `INSERT/UPDATE/DELETE/CREATE/ALTER`.
|
||||
|
||||
## Альтернативы
|
||||
- **Расширить `/queue`** — отклонено: ломает байт-в-байт контракт (BR-6) + смешивает сырьё с
|
||||
человеческим снимком.
|
||||
- **Prometheus/OpenMetrics** — отклонено: заказчик задал тонкий кастомный sidecar (не Prometheus),
|
||||
контракт — JSON.
|
||||
- **Орк считает CPU-дельту сам** — отклонено: требует состояния; stateful-арбитр это sidecar (C-1).
|
||||
- **Расширить SELECT `get_running_jobs()`** — отклонено: перенос инварианта hot-path reaper'а;
|
||||
изолируем dedicated helper.
|
||||
- **Push в sidecar** — отклонено: нарушает разделение C-1; зависший орк ⇒ pull падает = сам сигнал.
|
||||
|
||||
## Последствия
|
||||
- F1b разблокирована стабильным машинным контрактом; домен наблюдаемости стартует.
|
||||
- Строго read-only + never-raise ⇒ near-zero риск для общего прод-конвейера (enduro-trails);
|
||||
`/health`/`/status`/`/queue` байт-в-байт; гейты/схема/machine-verdict-ключи не тронуты (NFR-5).
|
||||
- `schema_version` + аддитивно-толерантная политика ⇒ расширения не ломают F1b.
|
||||
- Плата: новая поверхность совместимости `/metrics`↔F1b (митигейшн — единый репо контракта + версия);
|
||||
CPU-liveness Linux-специфичен (`/proc`; не-Linux → `null`). Топология/схема не меняются (sidecar и
|
||||
его сетевая достижимость — объём F1b).
|
||||
- Новый компонент + публичный контракт → `arch:major-change` (хоть и аддитивно/read-only/обратимо);
|
||||
прод-деплой строго через staging-гейт (8501), без рестарта прод-контейнера.
|
||||
- **Откат:** `metrics_endpoint_enabled=False` (мгновенный) или удаление модуля/эндпоинта/helper'ов —
|
||||
без следов в БД/схеме.
|
||||
|
||||
## Связи
|
||||
adr-0002 (job-queue/circuit-breaker — источник `queue`-сырья), adr-0011 (job-reaper —
|
||||
`get_running_jobs`/pid/liveness-семантика, изоляция hot-path), adr-0026 (терминал `{done,cancelled}`
|
||||
— фильтр `stages`), adr-0017 (serial_gate — паттерн leaf `snapshot()`/never-raise), adr-0020
|
||||
(frontmatter-контракт — стиль версионируемого контракта). Прямой потребитель — **F1b** (sidecar
|
||||
`watchdog/`, отдельная задача).
|
||||
@@ -1,92 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-057
|
||||
stage: architecture
|
||||
author_agent: architect
|
||||
status: proposed
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# adr-0031: Нормализация legacy root-owned файлов при миграции uid — детект-leaf + actionable worktree-ошибка
|
||||
|
||||
- **Статус:** proposed
|
||||
- **Дата:** 2026-06-10
|
||||
- **Задача:** ORCH-057 (follow-up ORCH-040)
|
||||
- **Детальный ADR:** `docs/work-items/ORCH-057/06-adr/ADR-001-legacy-ownership-normalization.md`
|
||||
|
||||
## Контекст
|
||||
ORCH-040 перевёл контейнеры на `user: "1000:1000"`, изменив только `docker-compose.yml`. Владельца
|
||||
уже существующих `root:root` файлов в bind-mount `/repos` это не меняет. Под uid 1000
|
||||
`src/git_worktree.py::ensure_worktree` (`os.makedirs` стр. 78 / `git worktree add` стр. 81/85) не может
|
||||
создать worktree рядом с root-owned `/repos/_wt/` → `fatal: could not create leading directories …
|
||||
Permission denied`, который сейчас пробрасывается сырым. Конвейер приходит сюда из
|
||||
`launcher._spawn`/`_materialize_deferred_branch` (ORCH-088) — **агент не стартует** (launch-time
|
||||
инфра-сбой, не код задачи). Инцидент 06.06 на проде (первый запуск ORCH-043); workaround Стрима
|
||||
(`chown -R 1000:1000`) наложен вручную. ADR-040 описал нормализацию абстрактно («вне объёма кода») и
|
||||
не дал процедуры → баг воспроизводим на чистой среде / новом репо / после исторического запуска под
|
||||
root. Контейнер бежит **без root** → код физически не может `chown` чужие файлы; ему доступны лишь
|
||||
детект + диагностика.
|
||||
|
||||
## Решение
|
||||
Три аддитивных, обратимых kill-switch'ем слоя — паттерн условного leaf-гейта (`coverage_gate`/
|
||||
`serial_gate`) + best-effort startup-хук (`main.lifespan`, как lease-reclaim). `STAGE_TRANSITIONS` /
|
||||
`QG_CHECKS` / `check_*` / machine-verdict-ключи (`verdict:`/`result:`/`deploy_status:`/
|
||||
`staging_status:`/`security_status:`/`coverage_status:`) / схема БД — **байт-в-байт прежние**.
|
||||
|
||||
- **Actionable worktree-ошибка (D1):** `ensure_worktree` классифицирует класс «нет прав» (маркеры
|
||||
`Permission denied`/`could not create leading directories`/`insufficient permission`/`EACCES`/
|
||||
`EPERM`) и поднимает `RuntimeError` с причиной (legacy root-файлы после миграции uid) + лечащей
|
||||
командой + ссылкой на INFRA.md. Не-прав-ошибки сохраняют прежний текст/смысл (никакой подмены).
|
||||
Меняется лишь **формулировка**, не факт сбоя.
|
||||
- **Детект-leaf `src/fs_normalize.py` (D2):** чистый, never-raise, TTL-кэш (паттерн `preflight`).
|
||||
`scan_ownership(roots, target_uid)` обходит `/repos/_wt`, `<repo>/.git/objects`,
|
||||
`<repo>/.git/worktrees`, `data/runs`; ранний выход при первом `st_uid != target_uid`
|
||||
(`target_uid=os.getuid()` по умолчанию). `applies(repo)` (kill-switch + scope; пусто →
|
||||
`is_self_hosting_repo`) проверяется ПЕРВЫМ → дорогой обход только при applies. Идемпотентно;
|
||||
ошибка обхода → WARNING + консервативный `mismatch=False`.
|
||||
- **Интеграция = наблюдаемость, без блокировки claim (D3):** best-effort `scan_ownership()` на старте
|
||||
`main.lifespan` → WARNING + Telegram при mismatch. Claim НЕ гейтится: внятный ранний отказ даёт D1
|
||||
в точке launch (знает repo, агент ещё не тратил токены). Блокирующий preflight-гейт отвергнут —
|
||||
preflight не знает repo, заблокировал бы и enduro-trails на общем `/repos`.
|
||||
- **Опц. `normalize()` (D4):** chown только при `CAP_CHOWN`/root (под uid 1000 — no-op + лог),
|
||||
флаг `fs_normalize_auto` (дефолт `False`). Init-контейнер/root-entrypoint отвергнут: реинтродукция
|
||||
root-контекста (анти-цель ORCH-040) + правка compose = self-deploy/групповой риск. Реальную
|
||||
нормализацию несёт операторская процедура.
|
||||
- **Процедура (D5):** `INFRA.md` получает раздел «Миграция uid: обязательная нормализация legacy
|
||||
root-файлов» (точные команды по всем корням) как обязательный шаг миграции; forward-breadcrumb из
|
||||
ADR-040.
|
||||
- **Флаги:** `fs_normalize_enabled` (kill-switch, дефолт `True`), `fs_normalize_repos` (CSV, пусто →
|
||||
self-hosting only), `fs_target_uid` (1000), `fs_normalize_auto` (`False`), `fs_scan_roots`,
|
||||
`fs_scan_cache_ttl_s` (300). Наблюдаемость — блок `fs_ownership` в `GET /queue`; опц. `POST
|
||||
/fs-normalize/check`.
|
||||
|
||||
## Альтернативы
|
||||
- **Init-контейнер/root-entrypoint** — реинтродукция root (анти-цель ORCH-040), self-deploy compose,
|
||||
групповой риск ради разовой операции. Отвергнуто; носитель нормализации — операторская процедура.
|
||||
- **Блокирующий claim-гейт (preflight)** — preflight не знает repo → регресс enduro на общем `/repos`.
|
||||
Отвергнуто.
|
||||
- **Блокирующий claim-гейт (queue_worker/claim)** — дорогой FS-обход в hot-path + «молчаливое
|
||||
зависание» вместо диагноза D1. Отвергнуто.
|
||||
- **Авто-chown из app по умолчанию** — под uid 1000 невозможен; ложное ожидание самолечения.
|
||||
Отвергнуто (оставлен opt-in `fs_normalize_auto`).
|
||||
- **Hard-fail старта при mismatch** — нарушает never-raise, стопорит сервис всех проектов. Отвергнуто.
|
||||
|
||||
## Последствия
|
||||
- Класс «сырой git-fatal на launch после миграции uid» закрыт внятным диагнозом (D1) + проактивным
|
||||
startup-сигналом (D3); пробел процедуры ADR-040 закрыт (INFRA.md).
|
||||
- Нулевая регрессия enduro-trails (scope first); инварианты конвейера/схема БД — байт-в-байт.
|
||||
- Никакого root-контекста/рестарта прода/касания `main`/force-push/прод-образа (NFR-1).
|
||||
- Плата: фактический `chown` остаётся ручным операторским шагом (но теперь внятным, с инструкцией);
|
||||
+1 best-effort startup-хук и leaf-модуль; `fs_normalize_auto=True` под root реинтродуцирует
|
||||
chown-контекст (дефолт `False`, не для прод-self).
|
||||
- Аддитивно/обратимо: **не** `arch:major-change` (нет новой стадии/QG/таблицы/смены топологии) — leaf
|
||||
+ startup-хук + docs.
|
||||
- **Откат:** `fs_normalize_enabled=False` → полный no-op (мгновенный обратимый kill-switch).
|
||||
|
||||
## Связи
|
||||
adr-0005 (контейнер под host-uid — порождающее решение ORCH-040, чей пробел закрываем),
|
||||
adr-0029/adr-0012 (coverage/security-гейт — паттерн условного leaf `applies`/scope/never-raise/
|
||||
fail-open), adr-0017 (serial-gate — leaf never-raise + отложенный срез ветки `_materialize_deferred_
|
||||
branch`, чья точка падает в `ensure_worktree`), adr-0011 (job-reaper — образец best-effort
|
||||
startup-хука в `lifespan`), adr-0024 (disk-watchdog — образец «только читать/уведомлять, не трогать
|
||||
хост/прод»).
|
||||
@@ -1,95 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-019
|
||||
stage: architecture
|
||||
author_agent: architect
|
||||
status: proposed
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# adr-0032: Багфикс-трек — укороченный маршрут конвейера для багов (ORCH-019)
|
||||
|
||||
## Статус
|
||||
Proposed
|
||||
|
||||
## Контекст
|
||||
|
||||
Любая задача идёт по полному конвейеру `analysis → architecture → development → review → testing
|
||||
→ deploy-staging → deploy → done`. Для мелкого бага стадия `architecture` (отдельный прогон
|
||||
opus-агента `architect` + ADR + exit-гейт `check_architecture_done`) избыточна и тратит
|
||||
токены/время (прецедент ET-9/ET-014 ~35 мин).
|
||||
|
||||
**Корневой инвариант (нерушимый):** упрощаем только *аналитику/архитектуру*; ни один Quality
|
||||
Gate / под-гейт (security/merge/coverage/image-freshness) / exit-код deploy-хука — НЕ ослаблен
|
||||
(урок ET-8: срезанная проверка = недоделка на проде).
|
||||
|
||||
Кросс-каттинговость: затрагивает семантику маршрутизации (`advance_stage`), вводит новый
|
||||
leaf-компонент `src/bug_fast_track.py` и аддитивную колонку `tasks.track` → регистрируется
|
||||
сквозным ADR.
|
||||
|
||||
## Решение
|
||||
|
||||
Багфикс-трек — **свойство планировщика/точки входа, НЕ Quality Gate**.
|
||||
|
||||
1. **Классификация** (`src/bug_fast_track.py`, leaf never-raise по образцу `serial_gate`/`labels`):
|
||||
задача с меткой Plane `Bug` (`bug_fast_track_label`, читается аппаратом ORCH-089
|
||||
`labels.has_label`) помечается `track='bug'`. `applies(repo)` (локально, без сети) — первым;
|
||||
`has_label` (сеть) — только при `applies==True`; чтение метки **только** в `start_pipeline`,
|
||||
никогда в горячем `claim_next_job` (anti-stall).
|
||||
|
||||
2. **Хранение** — аддитивная идемпотентная колонка `tasks.track TEXT DEFAULT 'full'`
|
||||
(`_ensure_column`, паттерн `tasks.cancelled_at` ORCH-090); читается в `advance_stage` из БД
|
||||
(не из сети).
|
||||
|
||||
3. **Routing-override** — `STAGE_TRANSITIONS` и `get_next_stage`/`get_agent_for_stage` остаются
|
||||
**чистыми** (1:1). В `advance_stage`, на ребре выхода из `analysis`, при `track='bug'`:
|
||||
`next_stage` → `development` (вместо `architecture`), `next_agent` → `developer` (вместо
|
||||
`architect`). Багфикс физически минует стадию `architecture` → её exit-гейт
|
||||
`check_architecture_done` и `06-adr/` для багфикса не исполняются.
|
||||
|
||||
4. **Гейт `analysis` не трогаем** — `check_analysis_complete`/`check_analysis_approved` байт-в-байт
|
||||
прежние; lite-аналитик эмитит все 4 файла (01-bug-report / 02-03 краткие заглушки / 04 план
|
||||
обязательного регресс-теста). Экономия — пропуск всей стадии `architecture`, не число файлов.
|
||||
|
||||
5. **Эскалация** (обратимость) — `POST /bug-fast-track/escalate?work_item=<id>` сбрасывает
|
||||
`track→'full'` (+ self-escalate мини-аналитика); задача далее идёт через `architecture`.
|
||||
|
||||
6. **Условность/откат** — `bug_fast_track_enabled` (kill-switch), `bug_fast_track_label`,
|
||||
`bug_fast_track_repos` (CSV; **пусто → self-hosting only**). `False`/неприменимый репо →
|
||||
путь старта и маршрут **байт-в-байт** прежние.
|
||||
|
||||
7. **Наблюдаемость** — read-only блок `bug_fast_track` в `GET /queue` (флаг/область/метка +
|
||||
счётчик `track='bug'` + метрика экономии из `agent_runs`); лог на решение о маршруте; опц.
|
||||
`🐞` в Telegram-карточке.
|
||||
|
||||
## Кросс-каттинговые инварианты (НЕ нарушаются)
|
||||
|
||||
- `STAGE_TRANSITIONS` структурно не меняется (нет новых/удалённых стадий); `cancelled`/`done`
|
||||
стоки и предикаты терминальности (ORCH-090) не затронуты.
|
||||
- Реестр `QG_CHECKS`, сигнатуры `check_*`, вердикт-ключи (`verdict:`/`result:`/`deploy_status:`/
|
||||
`staging_status:`/`security_status:`/`coverage_status:`), порядок под-гейтов — байт-в-байт.
|
||||
- Врезка ORCH-019 в `advance_stage` — ТОЛЬКО на ребре выхода из `analysis`, ДО всех deploy-edge
|
||||
под-гейтов (ORCH-022/043/027/058) и Phase A/B (ORCH-036/059) → их инварианты сохранены.
|
||||
- Композиция с serial-gate (ORCH-088), auto-label (ORCH-089), coverage-gate (ORCH-027),
|
||||
merge-gate (ORCH-043) — багфикс-задача остаётся обычной задачей репо.
|
||||
|
||||
## Последствия
|
||||
|
||||
- **+** Багфикс минует стадию `architecture` (основная экономия), гейты качества сохранены.
|
||||
- **+** Аддитивно, под kill-switch, per-repo, never-raise, fail-safe → полный цикл; нулевая
|
||||
регрессия для enduro и orchestrator при выключении.
|
||||
- **−** lite-аналитик эмитит 02/03 заглушки (компромисс ради неизменности гейта); эскалация v1
|
||||
требует операторского действия (авто-триаж сложности — будущее, ORCH-13/Вариант 3).
|
||||
- **Откат:** `bug_fast_track_enabled=False` (мгновенно); колонка `tasks.track` аддитивна и
|
||||
безвредна (дефолт `'full'`).
|
||||
|
||||
## Связанные решения
|
||||
- ORCH-089 (auto-label) — переиспользуемый аппарат label-чтения: [adr-0018](adr-0018-auto-label-gates.md)
|
||||
- ORCH-088 (serial gate) — композиция очереди репо
|
||||
- ORCH-027 (coverage-gate) — структурный союзник BR-4: [adr-0029](adr-0029-coverage-gate.md)
|
||||
- ORCH-090 (cancelled) — паттерн аддитивной колонки `tasks.*`: [adr-0026](adr-0026-stop-cancel-task.md)
|
||||
|
||||
## Ссылки
|
||||
- Детальный ADR задачи: `docs/work-items/ORCH-019/06-adr/ADR-001-bug-fast-track.md`
|
||||
- BRD/TRZ/AC: `docs/work-items/ORCH-019/01-brd.md`, `02-trz.md`, `03-acceptance-criteria.md`
|
||||
</content>
|
||||
@@ -1,85 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-100
|
||||
stage: architecture
|
||||
author_agent: architect
|
||||
status: proposed
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# adr-0033: Sidecar-watchdog F1b — мозг мониторинга в отдельном контейнере
|
||||
|
||||
- **Статус:** proposed
|
||||
- **Дата:** 2026-06-10
|
||||
- **Задача:** ORCH-100 (FND/F1b)
|
||||
- **Детальный ADR:** `docs/work-items/ORCH-100/06-adr/ADR-001-sidecar-watchdog.md`
|
||||
- **Парный ADR:** `adr-0030` (F1a `/metrics` — источник сырья)
|
||||
|
||||
## Контекст
|
||||
Домен 0 «Фундамент» эпика автономного саморазвития, рамка наблюдаемости заказчика: **наблюдатель
|
||||
отделён от наблюдаемого**. F1a (adr-0030) отдаёт read-only `GET /metrics` — **только сырьё**. F1b —
|
||||
**мозг**: читает сырьё, дополняет внешними сигналами (хост/контейнеры/зависимости), решает по порогам,
|
||||
алертит. Частичные стражи (`disk_watchdog`/`reaper`/`reconciler`) живут ВНУТРИ процесса орка — орк
|
||||
завис/упал ⇒ они мертвы, платформа слепа в критический момент. Рамки: C-1 (отдельный контейнер, код в
|
||||
`watchdog/`), C-2 (без внешнего плеча — принятый риск), C-3 (тонкий стек, НЕ Grafana/Prometheus; хост
|
||||
впритык). Критический инвариант: орк лёг ⇒ `/metrics` недоступен = **сам сигнал тревоги**.
|
||||
|
||||
## Решение
|
||||
Новая папка `watchdog/` — **тонкий Python-3.12-stdlib демон** (без сторонних зависимостей), отдельный
|
||||
образ `watchdog/Dockerfile` + сервис `orchestrator-watchdog` в `docker-compose.yml` (`network_mode:
|
||||
host`, read-only `docker.sock`, `mem_limit: 128m`, `restart: unless-stopped`). Тик: (1) `GET /metrics`;
|
||||
(2) хост (диск/inode/память/CPU, stdlib); (3) статусы контейнеров через read-only `docker.sock`
|
||||
(GET-only — без `docker` SDK); (4) пинг Plane/Gitea/Anthropic. Сигналы проходят через **обобщённую
|
||||
чистую** `decide(signal_active, prev, now, cooldown) -> alert|realert|recovery|none` (генерализация
|
||||
`disk_watchdog.decide_action`; per-signal in-memory `AlertState`). Алерт — в **собственный** Telegram-
|
||||
канал sidecar (свои `WATCHDOG_TG_*`; **НЕ** импорт `src/notifications.py`). Особый сигнал — `/metrics`
|
||||
не отвечает → `orch_down`. Всё never-raise (per-source/per-tick/per-send), под kill-switch
|
||||
`WATCHDOG_ENABLED`, строго read-only к наблюдаемому. **`src/**`/`STAGE_TRANSITIONS`/`QG_CHECKS`/
|
||||
`check_*`/схема БД орка — не тронуты** (F1b вне процесса орка и вне конвейера QG).
|
||||
|
||||
- **Стек** — Python stdlib (`urllib`, `socket`+`http.client` для docker.sock, `shutil.disk_usage`,
|
||||
`/proc/meminfo`); pytest на чистые функции. Отвергнуты Go / `docker` SDK / Prometheus (C-3).
|
||||
- **Реестр сигналов** — `orch_down` (K подряд неудачных опросов), `host_mem`/`host_disk_crit`,
|
||||
`agent_hung` (Δ`cpu_ticks`/`clk_tck`/Δ`generated_at` < floor при растущем `runtime_s`; нужно 2
|
||||
опроса — sidecar stateful-арбитр), `stage_stuck` (`age_in_stage_s`), `job_failed` (edge),
|
||||
`queue_depth`, `container_down` (per name), `dep_down` (per name). Пороги/интервалы/URL — из env.
|
||||
- **Владелец диск-алерта (BR-10)** — штатные 85% остаются за внутренним `disk_watchdog` (ORCH-063,
|
||||
канал орка) ⇒ **нулевой дубль по построению**; sidecar покрывает провал «орк+disk_watchdog мертвы»
|
||||
через `orch_down`, плюс **opt-in** (default off) независимый критический потолок `host_disk_crit`
|
||||
(97%) — другое событие/канал, не повтор 85%.
|
||||
- **Толерантность контракта** — неизвестные ключи `/metrics` игнорируются, отсутствие опционального не
|
||||
ошибка, рост `schema_version` → warning (зеркало аддитивной политики adr-0030).
|
||||
- **Kill-switch** `WATCHDOG_ENABLED=false` → демон инертен (idle-loop, не exit) ⇒ нулевой эффект.
|
||||
|
||||
## Альтернативы
|
||||
- **Go / `docker` SDK / `requests`** — отклонено: вес/вторая цепочка против C-3 и консистентности с
|
||||
`disk_watchdog`.
|
||||
- **Prometheus/Grafana/TSDB** — отклонено: прямой запрет C-3.
|
||||
- **Sidecar — единственный владелец диска** — отклонено: потеря покрытия, когда сам sidecar/Docker
|
||||
недоступен; выбрана связка primary `disk_watchdog` + opt-in ceiling.
|
||||
- **Push из орка в sidecar** — отклонено: зависший орк не пушит; pull падает = сам сигнал `orch_down`.
|
||||
- **bridge + `host.docker.internal`** — отклонено: на Linux ненадёжно; `network_mode: host` проще.
|
||||
- **Своя БД/файл порогов** — отклонено: C-3; in-memory best-effort достаточно (как `disk_watchdog`).
|
||||
|
||||
## Последствия
|
||||
- Внешний мозг мониторинга переживает падение орка; `orch_down` делает наблюдателя громче в инцидент.
|
||||
- Строго read-only + независимый канал + never-raise ⇒ self-hosting-безопасно (enduro не затронут);
|
||||
падение sidecar не влияет на конвейер.
|
||||
- Аддитивно/обратимо: `src/**`/гейты/схема байт-в-байт; kill-switch → нулевая регрессия; дубль диска
|
||||
исключён структурно.
|
||||
- Плата: новый контейнер на впритык-хосте (`mem_limit: 128m` + замер RSS на staging обязательны);
|
||||
C-2 (падёт хост → молчит и sidecar); новая поверхность совместимости `/metrics`↔F1b (толерантный
|
||||
парсинг + единый репо контракта); CPU-liveness Linux-специфичен.
|
||||
- **Топология** меняется (новый контейнер) → `07-infra-requirements.md`; **схема БД** не меняется →
|
||||
08 = N/A. Новый компонент + контейнер + канал → `arch:major-change`; прод-выкат через staging-гейт
|
||||
(8501), деплой sidecar НЕ рестартит прод-контейнер.
|
||||
- **Откат:** не запускать сервис / `WATCHDOG_ENABLED=false` (мгновенный) или удаление `watchdog/` +
|
||||
сервиса + env — без следов в БД/схеме.
|
||||
|
||||
## Связи
|
||||
adr-0030 (F1a `/metrics` — парный источник сырья; контракт `cpu_ticks`/`clk_tck`/`generated_at`/
|
||||
`schema_version`), adr-0024 (`disk_watchdog` — образец решающей функции/never-raise + владелец
|
||||
диск-алерта), adr-0025 (build-cache-pruner — паттерн «вторая половина»), adr-0017 (serial_gate —
|
||||
leaf `snapshot()`/never-raise), adr-0011 (job-reaper — pid/liveness-семантика). Прямой источник —
|
||||
**F1a** (`GET /metrics`); F1b — его потребитель.
|
||||
</content>
|
||||
@@ -1,92 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-098
|
||||
stage: architecture
|
||||
author_agent: architect
|
||||
status: proposed
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# adr-0034: Машинный журнал уроков — таблица `lessons` + observer-leaf (ORCH-098)
|
||||
|
||||
## Статус
|
||||
Proposed
|
||||
|
||||
## Контекст
|
||||
|
||||
Оркестратор автономно ведёт задачи по конвейеру (ORCH-54), но **развивается** вручную: инциденты →
|
||||
уроки → задачи. Уроки живут свободным текстом в `memory/` — не машиночитаемы: нельзя считать
|
||||
паттерны, приоритизировать, предлагать улучшения. ORCH-098 — шаг 1 эпика саморазвития (домен 0
|
||||
«Фундамент», F2): «топливо» петли самообучения 8A. Нужна **структурированная таблица отклонений
|
||||
конвейера**, на которой позже встанут ретроспективщик (E2), приоритизатор RICE (E3) и Стрим.
|
||||
|
||||
Нормативное требование Славы (10.06): схема ДОЛЖНА **сразу** нести поля **атрибуции** урока
|
||||
(`platform`/`project`/`both`/`unknown` + целевой репо + домен улучшения), иначе позже придётся
|
||||
переделывать схему на живой общей прод-БД.
|
||||
|
||||
**Кросс-каттинговость** (почему сквозной ADR): новый компонент `src/lessons.py` + аддитивная
|
||||
таблица на **общей прод-БД** (self-hosting, разделяемой с enduro-trails) + врезки автозаписи в
|
||||
несколько горячих choke-point'ов (`stage_engine`/`merge_gate`/`launcher`) + новый раздел контракта
|
||||
`GET /queue`. Фундамент для будущих задач-потребителей → регистрируется глобально.
|
||||
|
||||
## Решение
|
||||
|
||||
Журнал уроков — **observer (наблюдатель), НЕ Quality Gate**. Аддитивная таблица + чистый leaf,
|
||||
по образцу `serial_gate`/`coverage_gate`/`metrics`/`bug_fast_track`.
|
||||
|
||||
1. **Таблица `lessons`** (`db.init_db()`, `CREATE TABLE IF NOT EXISTS` + 3 индекса, идемпотентно,
|
||||
restart-safe) — поля контекста (`work_item_id`/`task_id`/`stage`/`agent`/`repo`), анализа
|
||||
(`root_cause`/`suggestion`), статуса (`status`/`related_task`), **атрибуции сразу и нуллабельно**
|
||||
(`attribution`/`target_repo`/`target_domain`) + `source`/`detail`. Без `enum`-констрейнтов
|
||||
(слаги forward-compatible). Будущие колонки — `_ensure_column`.
|
||||
|
||||
2. **Leaf `src/lessons.py`** (never-raise, импортирует только `config`+`db`): `record()` / `get()` /
|
||||
`update()` / `snapshot()`. **Расхождение с гейт-шаблоном: журнал НЕ скоупится по репо** — он
|
||||
observer-only и не *действует* ни на один репо; единственный регулятор — глобальный kill-switch
|
||||
`lessons_enabled`. Запись урока про enduro ценна и **не затрагивает** пайплайн enduro (чистая
|
||||
память орка); репо-разрез — на выборке (`repo`-колонка/фильтр).
|
||||
|
||||
3. **Автозапись 4 типов** (`source="auto"`, best-effort, дедуп в окне; `transient_retry` — только на
|
||||
исчерпании бюджета ретраев): `gate_failure` (`stage_engine._handle_qg_failure_rollbacks`),
|
||||
`merge_hold` (`merge_gate._handle_merge_verify` HOLD), `transient_retry` (merge-retry/launcher
|
||||
transient budget-exhaustion), `deploy_degraded` (post-deploy `DEGRADED → set_repo_freeze`, урок
|
||||
слоя-3 «деплой OK / прод сломан», ET-8). Каждая врезка — одиночный вызов в защитном `try/except`.
|
||||
|
||||
4. **Эндпоинты** `GET /lessons` (read-only, фильтры), `POST /lessons` (ручная запись,
|
||||
`source="manual"`), `POST /lessons/{id}` (update — доклассификация `unknown`), + read-only ключ
|
||||
`"lessons": snapshot()` в `GET /queue`. При выключенном флаге → `{"enabled": false}`.
|
||||
|
||||
**Инвариант (нерушимый):** `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / machine-verdict-ключи
|
||||
(`verdict:`/`result:`/`staging_status:`/`deploy_status:`/`security_status:`/`coverage_status:`) /
|
||||
схемы существующих таблиц — **байт-в-байт не тронуты**. Журнал не влияет на продвижение по стадиям.
|
||||
|
||||
## Композиция с существующими механизмами
|
||||
- **Self-hosting (общая БД):** аддитивная таблица; enduro не затронут (NFR-3).
|
||||
- **serial-gate (ORCH-088) / post-deploy (ORCH-021):** детектор `deploy_degraded` врезан рядом с
|
||||
`set_repo_freeze`, не меняя freeze-логику.
|
||||
- **merge-gate (ORCH-043/071/093):** `merge_hold`/`transient_retry` читают исход актора, не меняя
|
||||
классификатор/ретрай.
|
||||
- **metrics (ORCH-099):** журнал — историческая память петли (best-effort запись), `/metrics` —
|
||||
realtime-сырьё для sidecar; разные роли, оба observer-only.
|
||||
|
||||
## Условность и откат
|
||||
- Флаг `lessons_enabled` (env `ORCH_LESSONS_ENABLED`, дефолт `True`; kill-switch) +
|
||||
`lessons_dedup_window_s` / `lessons_query_limit_default`. `False` → полная инертность, нулевая
|
||||
регрессия, конвейер байт-в-байт прежний.
|
||||
- **never-raise** на всех публичных функциях и врезках (NFR-1) — сбой журнала не роняет конвейер.
|
||||
- Откат — флаг в `false` (мгновенно) или revert диффа; таблица не касается существующих.
|
||||
|
||||
## Последствия
|
||||
- **+** Машиночитаемые уроки — фундамент E2/E3/Стрим; атрибуция forward-proof (без передела живой БД).
|
||||
- **+** Нулевая регрессия; проверенный additive-observer-leaf шаблон → низкий риск; enduro изолирован.
|
||||
- **−** Рост таблицы (митигейшн: лёгкие строки + дедуп + budget-exhaustion; ретенция — будущее).
|
||||
- **−** Дедуп-запрос в `record()` (один indexed-SELECT, только `auto`).
|
||||
|
||||
## Ссылки
|
||||
- Локальный ADR: `docs/work-items/ORCH-098/06-adr/ADR-001-lessons-journal.md`
|
||||
- BRD/TRZ/AC: `docs/work-items/ORCH-098/01-brd.md`, `02-trz.md`, `03-acceptance-criteria.md`
|
||||
- Data/Infra/Risks: `docs/work-items/ORCH-098/08-data-requirements.md`, `07-infra-requirements.md`,
|
||||
`10-tech-risks.md`
|
||||
- Эпик: `docs/epics/self-evolution.md` (домен 0 «Фундамент», F2; петля 8A)
|
||||
- Сверено по коду: `src/serial_gate.py`, `src/coverage_gate.py`, `src/db.py`, `src/stage_engine.py`,
|
||||
`src/merge_gate.py`, `src/agents/launcher.py`, `src/main.py`, `src/qg/checks.py`.
|
||||
@@ -1,80 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-009
|
||||
stage: architecture
|
||||
author_agent: architect
|
||||
status: proposed
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# adr-0035: Turnkey-онбординг проектов — kit + операторский CLI + runbook (ORCH-009)
|
||||
|
||||
## Статус
|
||||
Proposed
|
||||
|
||||
## Контекст
|
||||
|
||||
Подключение нового проекта к оркестратору — ручная археология по разрозненным докам и памяти;
|
||||
каждый пропущенный шаг даёт **тихую деградацию**: без промптов в репо конвейер проекта не работает
|
||||
вовсе (launcher резолвит `.openclaw/agents/<role>.md` относительно worktree репо задачи); без
|
||||
точных имён статусов Plane ветки `Confirm Deploy` (ORCH-059) / `STOP` (ORCH-090) молча не
|
||||
активируются (fail-closed); без лейблов `autoApprove`/`autoDeploy`/`Bug` авто-режимы (ORCH-089)
|
||||
и багфикс-трек (ORCH-019) молча выключены (fail-safe). Эталон онбординга — **сам репозиторий
|
||||
orchestrator** (каноны ORCH-52b/c/d/e кодифицированы в `docs/_templates/`, `docs/_standards/`,
|
||||
`.openclaw/agents/`). Домен D5.2 эпика саморазвития: способность разворачивать новый проект
|
||||
одним проходом.
|
||||
|
||||
## Решение
|
||||
|
||||
Способность реализуется **вне рантайма и вне конвейера** — `src/**` байт-в-байт не меняется
|
||||
(`STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict/схема БД/контракт `projects.py`
|
||||
нетронуты), kill-switch не нужен (активация — только явный запуск операторского CLI):
|
||||
|
||||
1. **Onboarding-kit `onboarding/repo-skeleton/`** — параметризуемый каркас нового репо:
|
||||
6 промптов агентов канона 52d/92 (5 XML-секций, «❌→✅», эмиссия схемы 52c, verdict-ключи
|
||||
байт-в-байт; язык — канон орка: 5 ru + deployer en), паспорт `CLAUDE.md`, `AGENTS.md`
|
||||
(точка входа агентов), `CONTRIBUTING.md`, `README.md`, `CHANGELOG.md`, скелет `docs/` с
|
||||
обязательным `operations/INFRA.md`, `.env.example`. Плейсхолдеры `{{NAME}}` + stdlib-рендер
|
||||
(без новых pip-зависимостей); словарь — `onboarding/placeholders.json` (биекция со
|
||||
вхождениями в kit держится тестами). **Канон не форкается:** `docs/_templates/` +
|
||||
`docs/_standards/` НЕ хранятся в kit — копируются live из чекаута орка в момент материализации.
|
||||
2. **Операторский CLI `scripts/onboard_project.py`** — `plan` (дефолт, GET-only, ни одной
|
||||
мутации) / `apply` (идемпотентный ensure, без delete-операций) / `verify`. Шаги: Plane-проект →
|
||||
22 статуса с точными именами из `plane_sync._PLANE_NAME_TO_KEY` (read-only импорт — нулевой
|
||||
дрейф; канонические группы фиксированы: `STOP`→`cancelled`, терминальные группы только у
|
||||
Done/Cancelled/STOP — иначе terminal-detection ORCH-068 ложно терминалит) → лейблы → Gitea-репо
|
||||
(+per-repo webhook `push`/`pull_request`/`status`; HMAC-секрет **переиспользуется** из
|
||||
`ORCH_GITEA_WEBHOOK_SECRET` — приёмник один на все репо) → материализация kit + initial push
|
||||
**только в свежесозданный пустой репо** (INV-4 не затрагивается) → merged-вывод
|
||||
`ORCH_PROJECTS_JSON`, провалидированный фактическим `projects._parse_projects_json`
|
||||
(round-trip). Недоступное в Plane CE API → `manual-step` со ссылкой на runbook (fail-safe).
|
||||
Скрипт **никогда** не рестартит прод, не правит `.env`, не пушит в существующие репо, ничего
|
||||
не удаляет.
|
||||
3. **Runbook `docs/operations/ONBOARDING.md`** — полный чеклист: предусловия (токены) → скрипт →
|
||||
операторские шаги (env + управляемый рестарт с self-hosting-предупреждением; UI-only Plane) →
|
||||
верификация (`verify` + smoke) → откат. Smoke-контур — **staging (8501, изолированная БД)** +
|
||||
одноразовый sandbox-проект (`SMK`); протокол — «Журнал smoke-прогонов» в runbook.
|
||||
|
||||
Анти-дрейф — структурные тесты kit (аналог `tests/test_agent_prompts_canon.py`) + снапшот-тест
|
||||
`STAGE_TRANSITIONS`/`QG_CHECKS` (контроль ненарушения `src`). Branch protection `main` новых репо
|
||||
**не включается** (ломала бы PR-merge API merge-актора — ложные HOLD класса ORCH-093).
|
||||
|
||||
## Последствия
|
||||
|
||||
- **+** Новый проект разворачивается одним проходом проверяемо: все слои (Plane-контракты,
|
||||
webhook, промпты, дока, реестр) закрыты скриптом+runbook; тихие деградации ловит `verify`.
|
||||
- **+** Нулевой риск рантайма: изменение docs/templates/scripts/tests-only; регресс
|
||||
enduro/orchestrator невозможен по построению; общая БД не читается и не пишется скриптом.
|
||||
- **+** Единый эталон без форка: новые репо получают живой канон момента онбординга;
|
||||
обновления канона в них едут обычными PR с reviewer-gate.
|
||||
- **−** Регистрация в реестре остаётся операторской (env + управляемый рестарт — Ф-3,
|
||||
сознательное ограничение NFR-2); разрыв «создано, но не зарегистрировано» виден через `verify`.
|
||||
- **−** Закрытый список read-only импортов из `src` (`projects._parse_projects_json`,
|
||||
`plane_sync._PLANE_NAME_TO_KEY`, поля `config.settings`) — связь с приватными именами;
|
||||
поломка при рефакторинге видимая (тесты), расширение списка — только через ADR.
|
||||
- **Ограничение:** способность ≠ исполнение: онбординг конкретного заказчика — операторская
|
||||
эксплуатация (вне ORCH-009); тиражирование на новый хост — ORCH-10 (вне объёма).
|
||||
|
||||
Детально: `docs/work-items/ORCH-009/06-adr/ADR-001-turnkey-onboarding-kit-and-cli.md`
|
||||
(D1…D11 — раскладка, плейсхолдеры, copy-vs-template split, импорт src, группы статусов,
|
||||
webhook-секрет, формат реестра, smoke-контур, языковая политика, branch protection, форма CLI).
|
||||
@@ -61,15 +61,9 @@ STAGE_TRANSITIONS = {
|
||||
testing: → deploy-staging (agent: deployer, QG: check_tests_passed)
|
||||
deploy-staging: → deploy (agent: deployer, QG: check_staging_status)
|
||||
deploy: → done (agent: None, QG: None)
|
||||
cancelled: → None (agent: None, QG: None) # ORCH-090: терминал-сток отмены
|
||||
}
|
||||
```
|
||||
|
||||
**Терминальные стоки (ORCH-090):** `done` и `cancelled` — равноправные терминальные состояния
|
||||
(`{"next": None, "agent": None, "qg": None}`). `cancelled` — это **не новое ребро** (exit-гейты
|
||||
рёбер не меняются), а терминал STOP-отмены. Системный предикат «задача завершена» —
|
||||
`stage ∈ {done, cancelled}` (синхронно в `reconciler`/`serial_gate`/`task_deps`; adr-0026).
|
||||
|
||||
### 3. Quality Gates (`src/qg/checks.py`)
|
||||
|
||||
| Check | Метод проверки |
|
||||
@@ -106,17 +100,6 @@ claude.exe --print --system-prompt --allowedTools Read,Write,Edit,Bash
|
||||
|
||||
Примечание: переход `review → testing` использует `check_reviewer_verdict` (читается из frontmatter `12-review.md`); `development → review` — `check_tests_local` (оркестратор сам прогоняет тесты, не зависит от Gitea CI).
|
||||
|
||||
**Багфикс-трек: routing-override на ребре выхода из `analysis` (ORCH-019 — design).** Для задачи
|
||||
с `tasks.track='bug'` (помечена в `start_pipeline` по метке Plane `Bug` через аппарат ORCH-089)
|
||||
`advance_stage` на шаге 3 переопределяет результат `get_next_stage('analysis')`: `next_stage` →
|
||||
`development` (вместо `architecture`), а на шаге 4 `next_agent` → `developer` (вместо `architect`)
|
||||
→ стадия `architecture` и её exit-гейт `check_architecture_done` для багфикса не исполняются.
|
||||
`STAGE_TRANSITIONS`/`get_next_stage`/`get_agent_for_stage` остаются чистыми (1:1) — override живёт
|
||||
только в `advance_stage`. Чистый предикат `bug_fast_track.skips_architecture(track)` (leaf
|
||||
`src/bug_fast_track.py`, never-raise) под `bug_fast_track_enabled`; `track` читается из БД, не из
|
||||
сети (NFR-4). `False`/неприменимый репо → маршрут байт-в-байт прежний. Детали —
|
||||
[adr-0032](adr/adr-0032-bug-fast-track.md).
|
||||
|
||||
### 6. Review Bounce
|
||||
|
||||
При REQUEST_CHANGES:
|
||||
@@ -145,16 +128,12 @@ claude.exe --print --system-prompt --allowedTools Read,Write,Edit,Bash
|
||||
|
||||
**Текст карточки (оба режима, ORCH-042):** метка `Подтверждение BRD` (была «Ревью БРД»); после прохождения approve-gate строка BRD начинается с ✅ (ветка ожидания сохраняет ⏸️/⏳); русские display-labels стадий (`Анализ / Архитектура / Разработка / Код ревью / Тестирование / Внедрение`); финальная строка `📦 Внедрено` (было `deployed`). Меняются только отображаемые строки — ключи стадий и имена агентов (завязаны на `_STAGE_ACTIVE_AGENT`, `last_done`, БД) не трогаются.
|
||||
|
||||
**Строки стадий: отражение откатов + суммирование метрик (ORCH-091).** Цикл рендера строк стадий (`render_task_tracker` → `_stage_line`) исправлен по двум осям. (1) **Откат (Деф.2):** `✅`-строка стадии рисуется только если её позиция в конвейере `≤` текущей позиции задачи; позиция берётся из порядка `STAGE_TRANSITIONS` (read-only хелпер `_pipeline_pos`, never-raise; неизвестная стадия → «далёкое будущее» → ✅ не пере-подавляется) с нормализацией `deploy-staging → deploy` ТОЛЬКО в гейте подавления (схлопнутая строка «Внедрение» несёт `stage_key="deploy"`). После отката (`deploy-staging → development`, `review → development`) строки стадий ПОЗЖЕ текущей больше не рисуются как пройденные — пропадает абсурд «✅ Внедрение + 🔄 Разработка»; `is_active_stage` не тронут. (2) **Метрики (Деф.3):** `_stage_line` агрегирует ВСЕ `agent_runs` агента стадии (Σ cost / Σ токены / Σ время теми же per-run-формулами, что блок тоталов задачи), а не последний прогон — каждый агент привязан ровно к одной строке `_TRACKER_STAGES`, поэтому Σ(строк стадий) ≡ тоталы ≡ `SUM(agent_runs)` по `task_id`; модель/эффорт/«попытка N» берутся из последнего прогона. Прогоны, подавлённые откатом, по-прежнему входят в тоталы (намеренная семантика отката).
|
||||
|
||||
**Строка Plane-статуса и кликабельный номер (ORCH-067, слой B — индикация).** Под заголовком карточка несёт строку `📍 <Plane-статус>` по модели ORCH-066. Источник — двухслойный, контракт **never raises**:
|
||||
- **Оффлайн-ядро** `plane_status_label(task_row)` — чистая функция БЕЗ сети: `stage → статус` (`created→To Analyse`, `analysis→Analysis`, `architecture→Architecture`, `development→Development`, `review→Code-Review`, `testing→Testing`, `deploy-staging→Deploying (staging)` [ORCH-091], `deploy→⏸️ Awaiting Deploy`, `done→Done`, `cancelled→Cancelled` [ORCH-091]) + `⏸️ In Review` из brd-часов (`brd_review_started_at` задан, `…_ended_at` пуст). **ORCH-091:** карта `_STAGE_STATUS_LABEL` покрывает ВСЕ ключи `STAGE_TRANSITIONS` (полнота — тестом, не статичным списком); неизвестная/будущая стадия → нейтральный фолбэк (капитализированное имя стадии), а НЕ «To Analyse» (он остаётся лишь явным лейблом `created` и безопасной деградацией на истинно-битом входе).
|
||||
- **Оффлайн-ядро** `plane_status_label(task_row)` — чистая функция БЕЗ сети: `stage → статус` (`created→To Analyse`, `analysis→Analysis`, `architecture→Architecture`, `development→Development`, `review→Code-Review`, `testing→Testing`, `deploy→⏸️ Awaiting Deploy`, `done→Done`) + `⏸️ In Review` из brd-часов (`brd_review_started_at` задан, `…_ended_at` пуст). Неизвестная/битая стадия → безопасный дефолт `To Analyse`.
|
||||
- **Live-overlay** `_live_plane_branch_override` — best-effort: дорисовывает ветви-статусы, неразличимые оффлайн (Needs Input / Blocked / Rejected / Cancelled / Deploying / Monitoring after Deploy), чтением живого Plane-статуса (`fetch_issue_state` с коротким `tracker_live_status_timeout_s`, TTL-кэш `tracker_live_status_ttl_s`, kill-switch `tracker_live_status`). Любой сбой / выключенный флаг / нехватка данных → оффлайн-метка; `⏸️ In Review` (авторитет brd-часов) overlay не консультирует. Анти-false-positive: `deploying/monitoring`, алиасящие базовый UUID на проекте без выделенного статуса (enduro), не вызывают override.
|
||||
|
||||
**Кликабельный номер задачи (ORCH-067).** Номер в заголовке карточки И во всех уведомлениях орка, где упоминается `work_item_id`, — HTML-ссылка на issue в Plane через общий `plane_issue_link` / `link_for` (URL строит `_plane_issue_url` с loopback/workspace/project-гардами, переиспользуя резолв ORCH-017). Fail-safe: при нехватке любого из (web-base/не-loopback, workspace, project_id, plane_issue_id) → `html.escape(work_item_id)` без `<a>`; динамические части экранируются, `<a>`-разметка валидна под `parse_mode=HTML`. Алерты `stage_engine`/`launcher`/`security_gate`/`reconciler` переведены на `link_for` (резолвит `repo`+`plane_issue_id` из БД по `task_id` или `work_item_id`).
|
||||
|
||||
**HTML-безопасность данных карточки (ORCH-095).** Текст карточки шлётся с `parse_mode=HTML` и собирается из слотов двух категорий: **markup** (намеренная разметка — `num_html`/`plane_issue_link`, `link_for(...)`, `_done_link(...)`, уже-экранированный `esc_title`) и **data** (подставляемые значения — длительности `_fmt_minutes`/`_capped_review_str`, статус-лейбл `_card_status_label`, имя модели `short_model_name`, эффорт `_run_effort`, токены/стоимость `fmt_tokens`/`fmt_cost`). Инвариант: **каждый data-слот экранируется `html.escape` ровно один раз на границе рендера** (`render_task_tracker`/`_stage_line`); функции-источники остаются HTML-агностичными, markup-слоты не экранируются (двойное экранирование запрещено). Это устранило класс «неэкранированные данные в HTML-тексте»: до фикса `_fmt_minutes(<60s)` возвращал литерал `<1м`, который Telegram парсил как открывающий тег → `editMessageText` `400 can't parse entities` → `EDIT_FAILED` → ранний `return` (анти-дубль ORCH-087) → карточка застывала (инцидент ORCH-093). `_fmt_minutes` по-прежнему возвращает `<1м` — escape на границе (`<1м`) рендерит его визуально идентично; формат не меняется. Застрявшая (в окне) карточка авто-восстанавливается следующим безопасным рендером; `edit_telegram`/`update_task_tracker`/леджер сирот/режимы `bump`/`edit` не тронуты. Детали — [ORCH-095 ADR-001](../work-items/ORCH-095/06-adr/ADR-001-html-safe-card-data-render.md).
|
||||
|
||||
## Database Schema
|
||||
|
||||
```sql
|
||||
@@ -350,7 +329,7 @@ webhook (plane/gitea) background thread (queue_worker)
|
||||
|
||||
| Колонка | Назначение |
|
||||
|--------|------------|
|
||||
| `status` | `queued` → `running` → `done` \| `failed` \| `cancelled` (ORCH-090: терминальный исход STOP-отмены, не реквью'ится) |
|
||||
| `status` | `queued` → `running` → `done` \| `failed` |
|
||||
| `attempts` / `max_attempts` | счётчик попыток (инкремент при claim) / лимит ретраев (default 2) |
|
||||
| `run_id` | FK на `agent_runs.id` после старта |
|
||||
| `pid` | (ORCH-065) pid агентского процесса (`proc.pid` из `_spawn`); liveness-сигнал для job-reaper. Добавляется `_ensure_column` (idempotent) |
|
||||
|
||||
@@ -1,316 +0,0 @@
|
||||
# 🧬 ЭПИК: Автономное саморазвитие платформы оркестратора
|
||||
|
||||
> **Статус:** концепция v2 (структура согласована Славой 09.06 → ждёт финального апрува → декомпозиция)
|
||||
> **Автор:** Стрим · **Дата:** 2026-06-09 · **Заказчик:** Слава
|
||||
> **Связанные:** ORCH-8 (петля самообучения), ORCH-83 (наблюдаемость), ORCH-54 (автономное внедрение, done)
|
||||
> **Источники:** память орка (инциденты 06–09.06), инвентаризация 94 задач Plane, мировые практики (STRATUS NeurIPS'25, ChaosEater ASE'25, self-healing LLM-agents arXiv'26, agentic AIOps, FinOps token-economics).
|
||||
|
||||
---
|
||||
|
||||
## 0. Зачем это (vision)
|
||||
|
||||
Оркестратор уже **автономно внедряет** (ORCH-54: задача проходит analysis→prod без человека). Но автономность исполнения ≠ автономное **развитие**. Сегодня платформу развивает связка Слава+Стрим вручную: ловим инциденты → формулируем уроки → заводим задачи → апрувим.
|
||||
|
||||
**Цель эпика:** управляемый самоподдерживающийся контур, где платформа сама замечает свои слабые места И возможности роста, предлагает улучшения как готовые задачи, проводит их через собственный конвейер (ORCH-7 self-hosting) — **под контролем человека на ключевых развилках** (safety > автономность).
|
||||
|
||||
**Принцип баланса (коррекция Славы 09.06):** саморазвитие — это НЕ только «не падать и не косячить». Стабильная платформа, которая не растёт в возможностях, — тупик. **Рост функционала (новые фичи, стеки, удобства для заказчиков) — равноценный домен, а не следствие надёжности.** Платформа развивается по двум рукам одновременно: крепнет (надёжность/качество/экономика) И раздаётся вширь (возможности/масштаб).
|
||||
|
||||
---
|
||||
|
||||
## 1. Архитектура эпика: фундамент + 5 доменов + 2 вертикали
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ ВЕРТИКАЛЬ-ДВИГАТЕЛЬ 🧠 ВЕРТИКАЛЬ-ТОРМОЗ 🛑 │
|
||||
│ 🔄 уроки (крепнем) + governance / safety L0-L3 │
|
||||
│ 💡 генератор идей (растём) (ограничивает, апрувы) │
|
||||
│ ░░░░░░░░░░░░ проходят СКВОЗЬ все домены ░░░░░░░░░░░░░░░░░░░░░ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ ДОМЕНЫ РАЗВИТИЯ (равноценные, две руки роста) │
|
||||
│ │
|
||||
│ КРЕПНЕТ ───────────────────► РАЗДАЁТСЯ ВШИРЬ ────────► │
|
||||
│ 🛡️ D1 Надёжность 🚀 D4 Возможности (фичи) │
|
||||
│ ✅ D2 Качество/Доверие 📈 D5 Масштаб │
|
||||
│ 💰 D3 Экономика │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ ФУНДАМЕНТ (слой 0): 👁️ Наблюдаемость + 📒 Журнал уроков │
|
||||
│ глаза и память — без них всё слепо │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
Общая метрика-объединитель: 🌡️ ГРАДУСНИК АВТОНОМНОСТИ
|
||||
(каждый домен двигает её вверх контролируемо)
|
||||
```
|
||||
|
||||
### Что изменилось против v1 (мои же правки по критике)
|
||||
- **Наблюдаемость вынесена в фундамент** (была внутри M1) — она питает ВСЁ.
|
||||
- **M0 разбит на 2 вертикали:** двигатель (петля) и тормоз (governance) — у них противоположная логика, нельзя в одну коробку.
|
||||
- **Добавлен домен D2 Качество/Доверие** — была дыра: надёжная платформа может стабильно генерить говнокод. Надёжность инфры ≠ корректность результата.
|
||||
- **Рост (D4+D5) — равноценные домены, не «второй эшелон»** (коррекция Славы).
|
||||
- **Градусник автономности** — сквозная измеримая цель вместо абстракции.
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ АРХИТЕКТУРНЫЕ РАМКИ наблюдаемости (решено Славой 09.06 — constraints для архитектора)
|
||||
|
||||
> Это НЕЗЫБЛЕМЫЕ границы (заказчик). Конкретные ADR (стек, формат метрик, точки врезки) — зона архитектора внутри этих рамок.
|
||||
|
||||
**Принцип:** наблюдатель ОТДЕЛЁН от наблюдаемого. Мониторинг НЕ живёт внутри орка — иначе орк упал/завис/съел память → мониторинг ляжет вместе с ним, и мы слепы в самый критичный момент.
|
||||
|
||||
**Решения Славы:**
|
||||
- **С-1. Sidecar-контейнер на том же хосте** (вариант A). Отдельный процесс/память/рестарт — орк падает, наблюдатель жив и РЕПОРТИТ это.
|
||||
- **С-1б. КОД sidecar — В РЕПО орка** (отдельная папка `watchdog/`), рантайм — ОТДЕЛЬНЫЙ контейнер. Изоляция — на уровне КОНТЕЙНЕРА, не репозитория. Плюсы: (1) конвейер орка пилит свой мониторинг сам (self-hosting ORCH-7); (2) контракт `/metrics`↔sidecar в одном репо — не разъедется (один PR/тесты); (3) один CI. Сборка: ОТДЕЛЬНЫЙ `watchdog/Dockerfile` + сервис `orchestrator-watchdog` в docker-compose.yml. Разовое инфра-действие: добавить сервис в compose + первый запуск (Слава/Стрим на хосте), дальше код watchdog катится через конвейер.
|
||||
- **С-2. Без внешнего плеча (L2).** Не усложняем второй площадкой. (Принятый риск: падёнвесь хост/Docker → наблюдатель тоже молчит; осознанно.)
|
||||
- **С-3. Тонкий стек.** НЕ Grafana+Prometheus (+5-6 контейнеров на забитый хост). Тонкий Python/Go sidecar. **Факт хоста 09.06: RAM 171Mi free / 7.7Gi, диск 92%** — ресурсы впритык, наблюдатель обязан быть лёгким.
|
||||
|
||||
**Разделение ответственности:**
|
||||
- **Орк отдаёт только сырьё:** лёгкий read-only `/metrics` (свои внутренние данные — стадии/очередь/agent-liveness/cost, что знает только он). БЕЗ логики мониторинга/алертов/хранения. Орк лёг → endpoint недоступен = САМ сигнал тревоги.
|
||||
- **Sidecar — мозг мониторинга:** читает `/metrics` орка + хост (диск/память/CPU) + контейнеры (docker.sock read-only) + пинг Plane/Gitea/Anthropic; хранит пороги, шлёт Telegram-алерты СО СВОИМ каналом (не зависит от кода орка).
|
||||
- **Журнал уроков (F2)** — исключение: это НЕ realtime-мониторинг, а историческая память петли → допустимо в БД орка (аддитивная таблица). Не критично к падению орка в момент (запись best-effort).
|
||||
|
||||
---
|
||||
|
||||
## 2. ФУНДАМЕНТ (слой 0) — 👁️ Глаза и 📒 Память
|
||||
|
||||
Без данных нечем ни чинить, ни считать, ни приоритизировать, ни учиться. Строится первым.
|
||||
|
||||
- **F1 Наблюдаемость** (ORCH-83 [ЭПИК]): метрики agent-liveness + очередь + стадии + хост (диск/память/CPU) + контейнеры + внешние деп (Plane/Gitea/Anthropic). Эндпоинты /health /status /queue → расширить до /metrics + дашборд.
|
||||
- **F2 Журнал уроков** (ORCH-8 шаг 1): машинная структурированная таблица отклонений (тип, контекст, корень, предложение, статус) — формализовать то, что сейчас в memory/. Это «топливо» для вертикали-двигателя.
|
||||
|
||||
### 🎯 СКОП НАБЛЮДЕНИЯ — три слоя (решено Славой 10.06)
|
||||
|
||||
> Граница «мониторим ПЛАТФОРМУ vs ПРОДУКТЫ на ней». Важно для архитектора и будущих задач — не путать уровни.
|
||||
|
||||
- **Слой 1 — проекты как ЗАДАЧИ в конвейере — ✅ В СКОПЕ (F1a/F1b).** ET-задачи в stages/queue/agents `/metrics` — это работа орка (его агенты/очередь/стадии). Sidecar алертит «ET-задача застряла». Здоровье КОНВЕЙЕРА.
|
||||
- **Слой 2 — проекты как КОНТЕЙНЕРЫ на хосте — ✅ В СКОПЕ (F1b, жив/мёртв).** `enduro-trails-app-1`, `osrm` и пр. через docker.sock ro — Up/healthy/restarting/exited. Общий хост впритык → текущий ET-контейнер вредит орку. Здоровье контейнера как чёрного ящика.
|
||||
- **Слой 3 — ВНУТРЕННЕЕ бизнес-здоровье продукта — ❌ НЕ В ФУНДАМЕНТЕ, НО НУЖНО (см. ниже).** Эндпоинты ET отвечают 200? карта рендерится? latency не деградировала после фичи? Орк не знает внутренностей задеплоенных приложений — это МОНИТОРИНГ ПРОДУКТА, не платформы.
|
||||
|
||||
**Слой 3 — это отдельная продуктовая способность (домен D4/D5):** «per-project мониторинг здоровья задеплоенного приложения» — опция для заказчика («слежу, что твой ET-сайт жив»). **НО он НУЖЕН и самой петле** (см. §8A «атрибуция уроков») — без детекции деградации продукта петле нечего ловить. Порядок: фундамент (слои 1-2) сначала, слой 3 — позже как D4/D5-фича.
|
||||
|
||||
---
|
||||
|
||||
## 3. ДОМЕН D1 — 🛡️ Надёжность (Self-Repairing)
|
||||
|
||||
**Есть:** reconciler (53), post-deploy monitor+rollback (21), merge-verify (71/73), reaper (65), disk-watchdog (63), build-prune (62).
|
||||
**Уроки:** фантом-merge, deploy-петли, транзиенты, флапп-статусы, зомби-jobs.
|
||||
|
||||
- **D1.1** Предиктивный мониторинг (causal, не порог): «диск заполнится через N ч».
|
||||
- **D1.2** Авто-ремедиация рантайма: каталог типовых фиксов (зомби-job→requeue, stale-lease→reclaim, флапп→форс-терминал).
|
||||
- **D1.3** Транзиент-резилентность everywhere (обобщение ORCH-93): единый retry+backoff для всех внешних вызовов.
|
||||
- **D1.4** Zero-downtime деплой платформы (blue-green/canary): резервное плечо вместо окна недоступности.
|
||||
- **D1.5** Авто-rollback по SLO (расширение 21): откат по деградации latency/error-rate, не только health.
|
||||
- **D1.6** Deep agent-liveness (self-healing LLM): «думает / завис / зациклился» по reasoning+CPU+прогрессу.
|
||||
- **D1.7** Backup/restore БД+worktree (recovery после краша хоста).
|
||||
|
||||
---
|
||||
|
||||
## 4. ДОМЕН D2 — ✅ Качество / Доверие результата
|
||||
|
||||
> Новый домен. Закрывает дыру: платформа может надёжно и дёшево производить плохой результат. Надёжность инфры ≠ корректность кода/аналитики.
|
||||
|
||||
**Есть:** security-гейт (22), reviewer/tester стадии, промпт-аудит (92).
|
||||
|
||||
- **D2.1** Code-coverage гейт (ORCH-27): защита от деградации покрытия.
|
||||
- **D2.2** Регресс-страж результата: не только «тесты зелёные», но «не сломали соседнюю фичу» (расширение regression-guard ORCH-73).
|
||||
- **D2.3** Качество аналитики: метрика «BRD не пришлось переделывать», сверка факт vs ТЗ (как сегодня ловила ложное P0).
|
||||
- **D2.4** Доверие к выходу: provenance артефактов, воспроизводимость, «деплой OK = прод реально работает» (урок ET-8).
|
||||
- **D2.5** Опциональная человеческая приёмка важных фич (ORCH-28).
|
||||
- **D2.6** Само-оценка агентов: уверенность в результате → эскалация при низкой.
|
||||
|
||||
---
|
||||
|
||||
## 5. ДОМЕН D3 — 💰 Экономика
|
||||
|
||||
**Боль (ORCH-38):** developer сжёг **$13.68 на мелочь** (cache_read 18.98M — слепое сканирование src/).
|
||||
|
||||
- **D3.1** Model-routing cascade (мир: −87%): классификатор сложности → дешёвая модель на простое, opus на сложное (ORCH-20+13).
|
||||
- **D3.2** Бюджет circuit-breaker (ORCH-23): хард-лимит $/токенов/времени → пауза+алерт.
|
||||
- **D3.3** Оценка задачи ДО старта (ORCH-20): прогноз $/время по истории.
|
||||
- **D3.4** Целевые файлы в задании (ORCH-38): analyst даёт точный список из TRZ → нет слепого сканирования. **Самый дешёвый высокий impact.**
|
||||
- **D3.5** Fast-track простых задач (ORCH-19): багфикс → урезанный цикл без architect, дешёвая модель.
|
||||
- **D3.6** Semantic caching / prompt compression (мир: −31%).
|
||||
- **D3.7** Cost-дашборд + детект аномалий.
|
||||
|
||||
---
|
||||
|
||||
## 6. ДОМЕН D4 — 🚀 Возможности (рост функционала)
|
||||
|
||||
> **Равноценный домен (акцент Славы).** Это то, ради чего платформой ПОЛЬЗУЮТСЯ. Без новых возможностей надёжность бессмысленна — нечего надёжно делать. Развивается параллельно с D1-D3, а не после.
|
||||
|
||||
**Backlog-зародыши:** ORCH-12/13/14/15/18/24/25.
|
||||
|
||||
- **D4.1** Стеки-плагины: профили стека (web/mobile/data/ML/embedded) → агенты адаптируют процесс. Расширяемо без правки ядра. **Открывает заказчикам новые типы проектов.**
|
||||
- **D4.2** Android/мобильный стек (ORCH-15): полноценная разработка приложений.
|
||||
- **D4.3** UX/UI-дизайнер (ORCH-14): дизайнер-агент генерит макеты на аналитике, согласование с BRD.
|
||||
- **D4.4** Интерактивный аналитик (ORCH-18): живой диалог Слава↔analyst — уточнение BRD, обсуждение вариантов до старта. Удобство + качество постановки.
|
||||
- **D4.5** Тяжёлые вычисления (ORCH-12): воркер/стадия для долгих расчётов (ML-обучение, миграции данных).
|
||||
- **D4.6** База знаний проекта (ORCH-24): RAG-контекст решений/архитектуры — агенты умнее (+экономия).
|
||||
- **D4.7** Декомпозиция эпиков (ORCH-25): эпик→задачи→сборка автоматически (этот документ — кандидат №1).
|
||||
- **D4.8** Новые роли-агенты: data-engineer, ML-инженер, DevOps — по мере типов проектов.
|
||||
- **D4.9** Мультипровайдерность моделей (ORCH-13): не только Claude — выбор под задачу/стек/бюджет.
|
||||
|
||||
---
|
||||
|
||||
## 7. ДОМЕН D5 — 📈 Масштаб
|
||||
|
||||
> Вторая «рука роста»: способность делать БОЛЬШЕ и ШИРЕ. Сейчас потолок — `max_concurrency=1`.
|
||||
|
||||
**Backlog-зародыши:** ORCH-9/10; done: ORCH-6 (multi-repo), ORCH-88 (serial-batch).
|
||||
|
||||
- **D5.1** Параллельная разработка (снять max_concurrency=1): безопасный N>1 (изоляция worktree есть, нужна merge-orchestration FIFO + защита main). **Много фич параллельно = быстрее растём.**
|
||||
- **D5.2** Turnkey-онбординг проекта (ORCH-9): команда → Plane+Gitea+агенты+инфра за минуты.
|
||||
- **D5.3** Тиражирование на новый хост (ORCH-10): перенос платформы на инфру нового заказчика (IaC-bundle).
|
||||
- **D5.4** Горизонтальный воркер-пул: очередь jobs (ORCH-1) → несколько воркеров/хостов.
|
||||
- **D5.5** Per-project лимиты ресурсов (concurrency/бюджет на проект).
|
||||
- **D5.6** Мультитенантность (отложено — SaaS-сценарий, по спросу).
|
||||
|
||||
---
|
||||
|
||||
## 8. ВЕРТИКАЛЬ-ДВИГАТЕЛЬ 🧠 — две турбины: реактивная + проактивная
|
||||
|
||||
> Двигатель питается из ДВУХ источников (коррекция Славы 09.06). Реактивная турбина (уроки из боли) кормит «крепнем» (D1-D3). Проактивная (генератор идей) кормит «растём» (D4-D5). Без второй турбины рост фич зависит только от Славы — бутылочное горлышко.
|
||||
|
||||
### 8A. Реактивная турбина 🔄 — петля самообучения из уроков (ORCH-8)
|
||||
```
|
||||
ДЕТЕКЦИЯ → ЖУРНАЛ урока → АНАЛИЗ/паттерны → ПРЕДЛОЖЕНИЕ задачи → [governance-гейт] → конвейер ORCH-7 → проверка эффекта → журнал
|
||||
```
|
||||
- **Детекция:** провал гейта, **ручное вмешательство (самый ценный сигнал — каждый ручной пинок = дыра автономности)**, ретраи/откаты/таймауты, ложные срабатывания, «деплой OK / прод сломан».
|
||||
- **Анализ (гибрид):** машина копит и предлагает черновик → Стрим фильтрует/оформляет → Слава апрувит.
|
||||
- **E1** Журнал уроков (=F2). **E2** Агент-ретроспективщик (анализ→предложение).
|
||||
|
||||
#### ⚖️ АТРИБУЦИЯ урока — platform-level vs project-level (решено Славой 10.06)
|
||||
|
||||
> Ключевой шаг петли. Пример Славы: выпустили фичу в ET → она деградировала ET. Петля поймала сигнал — но ЧЬЯ вина и ГДЕ чинить?
|
||||
|
||||
Когда детектирована деградация продукта после выпуска фичи, петля ДОЛЖНА различить два уровня вины и направить урок в правильное русло:
|
||||
|
||||
- **А. Platform-level (недоработал ОРК):** конвейер выпустил деградацию, потому что у платформы СЛАБЫЙ ПРОЦЕСС (нет регресс-гейта «фича не ломает соседнее», тест-стадия не ловит деградацию производительности, нет производительностного бенчмарка в приёмке). → улучшаем ПРОЦЕСС орка (домен **D2 Качество** / **D1 Надёжность**). Чинится ОДИН раз — выигрывают ВСЕ проекты.
|
||||
- **Б. Project-level (недоработал ПРОЕКТ):** процесс орка нормальный, но в конкретном ET МАЛО тестов/слабая приёмка под этот тип фич. → усиливаем ТЕСТЫ/приёмку В САМОМ ET (задача в бэклог ET). Чинится точечно — выигрывает только ET.
|
||||
|
||||
**Механизм (новый шаг петли):**
|
||||
```
|
||||
ДЕТЕКЦИЯ деградации продукта (слой 3) → урок →
|
||||
АТРИБУЦИЯ: platform-level или project-level?
|
||||
├─ platform → задача в D1/D2 (улучшить процесс — польза всем)
|
||||
└─ project → задача в бэклог ET (усилить тесты ET — польза ET)
|
||||
(развилка не всегда бинарна — бывает ОБА: и гейт в орк, и тесты в ET)
|
||||
```
|
||||
Без атрибуции петля «чинит платформу» там, где надо усилить проект (и наоборот). **Зависит от слоя-3 детекции** (§2): без мониторинга здоровья продукта петле нечего атрибутировать. **E2-ретроспективщик** несёт эту классификацию; спорные случаи → Стрим/Слава решают.
|
||||
|
||||
### 8B. Проактивная турбина 💡 — генератор идей новых возможностей (НОВОЕ — запрос Славы)
|
||||
|
||||
> Отдельный источник идей роста функционала — НЕ только требования от Славы. Проактивно предлагает новые фичи/возможности/удобства. Та же воронка: машина/агент генерит черновики → Стрим фильтрует → Слава решает.
|
||||
|
||||
**Источники идей (вход генератора):**
|
||||
- **I1 Гэпы реализации:** чего НЕ хватило для запрошенных проектов (enduro-trails, snowbike — что было тяжело/невозможно сделать платформой → кандидат в фичу).
|
||||
- **I2 Паттерны ручного труда:** что Слава/заказчики часто делают руками ВНЕ платформы → кандидат на автоматизацию/фичу.
|
||||
- **I3 Тренды и новые технологии:** сканирование новых моделей/стеков/инструментов (web-поиск, release-notes провайдеров) → «вышла модель X / фреймворк Y — даёт новую возможность».
|
||||
- **I4 Конкурентный/рыночный анализ:** что умеют другие AI-платформы разработки (Devin, Cursor, Copilot Workspace…) → чего нет у нас.
|
||||
- **I5 Анализ собственного бэклога/истории:** паттерны типов задач → «часто просят X → стоит сделать шаблон/фичу».
|
||||
- **I6 Обратная связь заказчиков:** явные пожелания/жалобы по реализованным проектам.
|
||||
- **I7 Саморефлексия Стрим:** я вижу работу платформы изнутри каждый день — предлагаю удобства/фичи из опыта ведения.
|
||||
|
||||
**Компоненты:**
|
||||
- **E4 Агент-идеатор (product-discovery):** по расписанию сканирует I1-I7 → генерит бэклог идей-черновиков фич (с обоснованием «зачем/кому/из какого источника»).
|
||||
- **E5 Банк идей:** отдельный реестр (не путать с журналом уроков): идея, источник, предполагаемая ценность, статус (new/отклонена/в работе).
|
||||
|
||||
### 8C. Общий выход двигателя
|
||||
- **E3 Приоритизатор RICE:** сводит ОБА потока (уроки из 8A + идеи из 8B) в единый ранжированный бэклог по impact/cost/risk — что брать первым по всем доменам. Баланс «крепнем vs растём» — настраиваемый (квота слотов на надёжность vs фичи).
|
||||
|
||||
---
|
||||
|
||||
## 9. ВЕРТИКАЛЬ-ТОРМОЗ 🛑 — Governance / Safety
|
||||
|
||||
> «Контроль и управление саморазвитием» (требование Славы). Двигатель жмёт газ — этот контур держит руль и тормоз.
|
||||
|
||||
**Принцип (ORCH-8, незыблемо):** самомодификация платформы (промпты/скиллы/конфиги агентов/ядро) — ТОЛЬКО через PR+ревью+апрув Славы. Орк ПРЕДЛАГАЕТ, ПРИМЕНЯЕТ через свой конвейер с гейтами.
|
||||
|
||||
**Уровни автономии (agentic AIOps maturity):**
|
||||
| Уровень | Что авто | Гейт |
|
||||
|---------|----------|------|
|
||||
| L0 reactive | только алерт | человек делает всё |
|
||||
| L1 assistive | предложить задачу+ТЗ | человек апрувит запуск |
|
||||
| L2 autonomous-bounded | гонит безопасные классы (бэкенд-фиксы) до прода | safety-гейты CI/staging/regression |
|
||||
| L3 self-modifying | менять агентов/ядро | **всегда** PR+апрув Славы, НИКОГДА не авто |
|
||||
|
||||
- **G1** Safety-политика L0-L3 + per-class правила (что можно само, что только через Славу). Лейблы autoApprove/autoDeploy (ORCH-89) = уже зародыш.
|
||||
- **G2** Бюджет на саморазвитие: лимит $/мес, чтобы контур не жёг бесконтрольно.
|
||||
- **G3** Дашборд эволюции: метрики 5 доменов в динамике — видно, КУДА развивается платформа.
|
||||
- **G4** Kill-switch петли: остановить самогенерацию задач одним флагом.
|
||||
|
||||
---
|
||||
|
||||
## 10. 🌡️ Градусник автономности (сквозная метрика)
|
||||
|
||||
Объединяющая измеримая цель эпика. Каждый домен двигает её вверх:
|
||||
- **% задач без ручного пинка** (сегодня было ~5 вмешательств: апрувы, домерж 063, sync 061).
|
||||
- **Ручных вмешательств / неделю** (тренд вниз).
|
||||
- **MTBF / MTTR** платформы (D1).
|
||||
- **$/задача, токены/задача, время/задача** (D3).
|
||||
- **Типов проектов/стеков поддержано** (D4).
|
||||
- **Задач параллельно** (D5).
|
||||
- **% уроков, ставших задачами** (двигатель).
|
||||
|
||||
---
|
||||
|
||||
## 11. Связь с Backlog (ничего не теряем)
|
||||
|
||||
| Backlog | Домен/вертикаль |
|
||||
|---------|-----------------|
|
||||
| ORCH-8 петля | 🧠 Двигатель (ядро) |
|
||||
| ORCH-83 наблюдаемость | Фундамент F1 |
|
||||
| ORCH-20/23/38/19 | 💰 D3 |
|
||||
| ORCH-27/28 | ✅ D2 |
|
||||
| ORCH-12/13/14/15/18/24/25 | 🚀 D4 |
|
||||
| ORCH-9/10 | 📈 D5 |
|
||||
| ORCH-94 флапп | 🛡️ D1.2 |
|
||||
| ORCH-89 авто-лейблы | 🛑 G1 |
|
||||
|
||||
~18 backlog-задач ложатся в структуру. Эпик их систематизирует и достраивает.
|
||||
|
||||
---
|
||||
|
||||
## 12. Дорожная карта (предложение)
|
||||
|
||||
1. **Фаза 0 (фундамент):** F1 наблюдаемость + F2 журнал. Без них рулить нечем.
|
||||
2. **Фаза 1 (две руки параллельно):**
|
||||
- крепнем: D3.4 целевые файлы + D3.2 бюджет-breaker (дешёвый impact)
|
||||
- растём: D4.1 стеки-плагины ИЛИ D4.4 интерактив-аналитик (по спросу)
|
||||
3. **Фаза 2:** D1 надёжность (транзиент-резилентность, авто-ремедиация) + D2 качество + D5.1 параллелизм.
|
||||
4. **Фаза 3 (мозг):** E2 ретроспективщик + E3 приоритизатор + G1 safety-политика → петля замыкается, дальше платформа предлагает сама.
|
||||
|
||||
---
|
||||
|
||||
## ⛓️ Реализация в Plane (решено 09.06)
|
||||
|
||||
**Ось ДОМЕНА → модули Plane** (1 задача = 1 модуль; slug в `external_id`, name с эмодзи для человека):
|
||||
|
||||
| Модуль (name) | slug (external_id) | module_id |
|
||||
|---|---|---|
|
||||
| 👁️ Фундамент | `foundation` | 74dee25a-a44b-4c3b-ab55-1b5638b8cc1f |
|
||||
| 🧠 Мозг | `brain` | ab1afa08-14ce-4b7d-8ebc-e45ac19b2ba7 |
|
||||
| 🛡️ Надёжность | `reliability` | abd7479e-4f9b-4a56-a926-cb2ece7558ca |
|
||||
| ✅ Качество | `quality` | cbf5f8ca-dc1a-4dee-9d35-555459de2b30 |
|
||||
| 💰 Экономика | `economy` | 9b4bbab3-95d6-4b8a-8d72-379a618ea2f3 |
|
||||
| 🚀 Возможности | `features` | baa6936c-6a39-4935-ad57-31ef5ffc3041 |
|
||||
| 📈 Масштаб | `scale` | 18373528-14fa-4627-a0f6-32497ff22177 |
|
||||
|
||||
**Ось ВЕРТИКАЛЬ → лейблы** (могут быть несколько, список короткий):
|
||||
- `engine` (36f398f7-5a1c-4eeb-847a-56c457e1da6b) — задача пришла от петли/идеатора.
|
||||
- `governance` (9eea4dd8-0fe7-473a-8c40-630fc3ab0d25) — требует апрува L3 / safety-внимания.
|
||||
- (+ существующие `autoApprove`/`autoDeploy` — ортогональны, режим автономности.)
|
||||
|
||||
**Правило раскладки:** каждая задача эпика = 1 модуль-домен (по slug) + 0..N вертикаль-лейблов. Орк ищет/привязывает по `external_id` (не по русскому имени).
|
||||
|
||||
⚠️ **Порядок модулей на доске:** Plane API игнорирует `sort_order` на запись (только drag-and-drop в UI). Сейчас порядок перевёрнут (Масштаб сверху) — Славе поправить мышкой (фундамент→мозг→надёжность→качество→экономика→возможности→масштаб). На машинную логику не влияет (орк по slug).
|
||||
|
||||
---
|
||||
|
||||
## 13. Открытые вопросы Славе
|
||||
|
||||
1. **Структура Plane:** мега-эпик с фундаментом+5 доменами+2 вертикалями? Или эпик на каждый домен?
|
||||
2. **D4 (возможности):** какой стек/фича приоритетны для тебя/заказчиков — Android, UX/UI, тяжёлые расчёты, интерактив-аналитик? С чего рост начинать?
|
||||
3. **Баланс «крепнем vs растём»:** идти строго параллельно обеими руками, или в каждой фазе перевес в одну сторону?
|
||||
4. **Safety L3:** подтверждаешь — самомодификация ядра/агентов всегда через твой апрув?
|
||||
5. **Двигатель (E2/E4):** ретроспективщик + агент-идеатор сразу как агенты, или сначала Стрим ведёт журнал/банк идей вручную?
|
||||
8. **Генератор идей (8B):** какие из источников I1-I7 тебе ценнее (гэпы проектов / тренды-технологии / конкуренты / саморефлексия Стрим)? Генерить автономно или только по твоему запросу?
|
||||
6. **Бюджет на эпик (G2):** лимит $/мес?
|
||||
7. **Первая задача** после апрува: F1 наблюдаемость, быстрая победа D3.4, или сразу рост D4.*?
|
||||
@@ -47,35 +47,8 @@ ADR `docs/work-items/ORCH-040/06-adr/ADR-001-run-agents-as-host-uid.md` и гл
|
||||
- **P-3:** `id slin` → `1000:1000`; `/repos`, `/app/data` уже `1000:1000`.
|
||||
- **P-4:** прод-рестарт self — только в окно тишины (`GET /status` без активных задач):
|
||||
общий инстанс с enduro-trails.
|
||||
- **P-5 (блокер миграции uid, ORCH-057):** нормализация **всех** legacy `root:root` файлов в `/repos`
|
||||
— см. подраздел «Миграция uid: обязательная нормализация legacy root-файлов» ниже. Без неё первый
|
||||
job падает на launch при создании worktree (инцидент 06.06, ORCH-043).
|
||||
|
||||
### Миграция uid: обязательная нормализация legacy root-файлов (ORCH-057)
|
||||
ORCH-040 сменил `user:` контейнера, но **не** владельца уже существующих файлов в bind-mount `/repos`,
|
||||
созданных прежним root-контейнером. Под uid 1000 `src/git_worktree.py::ensure_worktree` не может
|
||||
создать worktree рядом с `root:root` каталогом `/repos/_wt/` → `fatal: could not create leading
|
||||
directories … Permission denied` (агент даже не стартует). С ORCH-057 эта ошибка распознаётся и
|
||||
выдаётся **внятно** (с лечащей командой) + детектится на старте сервиса (WARNING/Telegram, блок
|
||||
`fs_ownership` в `GET /queue`), но **фактический `chown` обязан выполнить оператор под root на хосте**
|
||||
(контейнер бежит без root и chown'ить чужие файлы не может).
|
||||
|
||||
**Обязательный разовый шаг при миграции uid / на новой среде (под root на mva154, ПЕРЕД стартом app):**
|
||||
```bash
|
||||
# 1) worktree-корень (все ветки всех проектов режутся здесь)
|
||||
sudo chown -R 1000:1000 /home/slin/repos/_wt
|
||||
# 2) .git обоих репо (objects / worktrees-административные записи)
|
||||
sudo chown -R 1000:1000 /home/slin/repos/orchestrator/.git \
|
||||
/home/slin/repos/enduro-trails/.git
|
||||
# 3) корень orchestrator целиком (включая data/runs/*.log — 37 root-логов в инциденте)
|
||||
sudo chown -R 1000:1000 /home/slin/repos/orchestrator
|
||||
# Проверка (пусто = ок):
|
||||
find /home/slin/repos/_wt ! -uid 1000 -print -quit
|
||||
```
|
||||
Процедура **идемпотентна** (повтор на корректной среде — no-op) и входит в **чеклист деплоя/миграции
|
||||
self**. Область охвата: `_wt`, оба `.git` (`objects`+`worktrees`), `data/runs`. См.
|
||||
`docs/work-items/ORCH-057/06-adr/ADR-001-legacy-ownership-normalization.md` и сквозной
|
||||
`docs/architecture/adr/adr-0031-legacy-ownership-normalization.md`.
|
||||
- Разовый разгребающий `chown -R 1000:1000 /home/slin/repos/orchestrator` для старых
|
||||
`root:root` файлов из истории (вне объёма кода).
|
||||
|
||||
### Тома (volumes)
|
||||
- `./data` → `/app/data` (БД; у staging — `./data/staging`)
|
||||
@@ -85,47 +58,6 @@ self**. Область охвата: `_wt`, оба `.git` (`objects`+`worktrees`
|
||||
- `~/.orchestrator-ssh` → `/home/slin/.ssh` (ro, деплой по ssh; target в HOME агента,
|
||||
согласован с `HOME=/home/slin` из launcher — ORCH-040, ранее `/root/.ssh`)
|
||||
|
||||
### Disk-watchdog: мониторинг заполнения диска mva154 (ORCH-063)
|
||||
07.06.2026 диск хоста mva154 тихо дорос до 100% и положил **весь конвейер всех проектов**
|
||||
(один прод-инстанс `orchestrator` на общей БД/очереди). Чтобы такой инцидент сигнализировался
|
||||
**заранее**, работает фоновый daemon-поток `src/disk_watchdog.py` (каркас `reconciler`/`job_reaper`):
|
||||
- **Что мониторится:** заполнение **хост-разделов** по смонтированным bind-путям (`/repos` →
|
||||
host `/home/slin/repos`, `/app/data` → host `./data`) через stdlib `shutil.disk_usage` — НЕ
|
||||
overlay `/` контейнера (иначе замер ложно-низкий). Пути с одним физическим устройством (`st_dev`)
|
||||
дедуплицируются → один алерт, не два.
|
||||
- **Порог и период:** при заполнении **≥ 85%** (`ORCH_DISK_MONITOR_THRESHOLD_PCT`) шлётся
|
||||
Telegram-алерт оператору; замер — раз в 300с (`ORCH_DISK_MONITOR_INTERVAL_S`). Пока диск выше
|
||||
порога, повтор — не чаще раза в ~6ч (`ORCH_DISK_MONITOR_REALERT_S`, анти-спам). При возврате
|
||||
ниже порога — однократное recovery-сообщение.
|
||||
- **Как отключить:** `ORCH_DISK_MONITOR_ENABLED=false` (демон не стартует; `GET /queue` →
|
||||
`disk_monitor.enabled=false`; поведение 1:1 как сейчас). Наблюдаемость — блок `disk_monitor` в
|
||||
`GET /queue` (последний замер: `used_pct`/`free_gb`/`alerting`/`last_alert_at` по каждому пути).
|
||||
- **Что делать при алерте:** watchdog **только сигнализирует** — он не трогает диск/контейнер и не
|
||||
рестартит прод (self-hosting безопасность). Освобождение **docker build cache** автоматизировано
|
||||
отдельным демоном (ORCH-062, см. ниже); прочие «пожиратели» — старые worktree-каталоги
|
||||
`/home/slin/repos/_wt/*` завершённых задач, логи, dangling-образы (`docker image prune`) —
|
||||
по-прежнему **ручная** операция оператора (авто-уборка этих категорий — вне объёма ORCH-062/063).
|
||||
|
||||
### Build-cache-pruner: авто-prune docker build cache на mva154 (ORCH-062)
|
||||
Доминирующий «пожиратель» в инциденте 07.06.2026 — **docker build cache** (≈11 ГБ от частых
|
||||
пересборок прод/staging-образов). Чтобы он не мог снова заполнить диск **без оператора**, работает
|
||||
фоновый daemon-поток `src/build_cache_pruner.py` (каркас `disk_watchdog`) — «вторая половина»
|
||||
watchdog'а: **watchdog сигналит, pruner убирает**.
|
||||
- **Что делает:** каждые `ORCH_BUILD_CACHE_PRUNE_INTERVAL_S` (дефолт 21600с = 6ч) выполняет
|
||||
**строго `docker builder prune -f --filter until=<until>`** (BuildKit GC; дефолт `until=24h` —
|
||||
удаляется build cache старше суток, тёплый свежий кэш сохраняется). Команда затрагивает **только
|
||||
build cache** — НЕ образы/контейнеры запущенных сервисов; рестарт docker daemon/прода НЕ
|
||||
выполняется (self-hosting безопасность).
|
||||
- **Как исполняется:** в контейнере нет `docker` CLI (образ несёт только `openssh-client git`),
|
||||
поэтому уборка идёт **на хосте через ssh** тем же каналом `ORCH_DEPLOY_SSH_USER@_HOST`, что
|
||||
деплой/`image_freshness`. **Пустой `ORCH_DEPLOY_SSH_HOST` → тик no-op** (фича активна только на
|
||||
self-host, где ssh настроен).
|
||||
- **Как отключить:** `ORCH_BUILD_CACHE_PRUNE_ENABLED=false` (демон не стартует; поведение 1:1 как
|
||||
до ORCH-062). Наблюдаемость — блок `build_cache_prune` в `GET /queue` (`enabled`/`interval_s`/
|
||||
`until`/`last_run_ts`/`last_reclaimed`/`last_error`); never-raise; in-memory учёт (без миграции).
|
||||
- **Ручной fallback** (если ssh-канал недоступен) — host-cron на mva154:
|
||||
`0 */6 * * * docker builder prune -f --filter until=24h` (off-git, процедура Owner).
|
||||
|
||||
## Переменные окружения (карта; значения — в `.env`)
|
||||
|
||||
| Переменная | Назначение |
|
||||
@@ -159,17 +91,6 @@ watchdog'а: **watchdog сигналит, pruner убирает**.
|
||||
| `ORCH_RECONCILE_GRACE_DEFAULT_S` | порог «застряла» по `tasks.updated_at`, сек; дефолт `600` |
|
||||
| `ORCH_RECONCILE_GRACE_OVERRIDES_JSON` | per-stage пороги, напр. `{"development":300}`; невалидный JSON → дефолт |
|
||||
| `ORCH_RECONCILE_NOTIFY_UNBLOCK` | слать Telegram при разблокировке застрявшей задачи; дефолт `true` |
|
||||
| `ORCH_DISK_MONITOR_ENABLED` | kill-switch disk-watchdog (ORCH-063); дефолт `true`. `false` → демон не стартует, поведение 1:1 как сейчас |
|
||||
| `ORCH_DISK_MONITOR_INTERVAL_S` | период heartbeat-замера заполнения диска, сек; дефолт `300` |
|
||||
| `ORCH_DISK_MONITOR_THRESHOLD_PCT` | порог заполнения для алерта, %; дефолт `85` (валидация 1..100, иначе → дефолт) |
|
||||
| `ORCH_DISK_MONITOR_REALERT_S` | cooldown повторного алерта, пока выше порога, сек; дефолт `21600` (~6 ч) |
|
||||
| `ORCH_DISK_MONITOR_PATHS` | CSV отслеживаемых **хост**-bind-путей; пусто → `/repos,/app/data` |
|
||||
| `ORCH_BUILD_CACHE_PRUNE_ENABLED` | kill-switch build-cache-pruner (ORCH-062); дефолт `true`. `false` → демон не стартует, поведение 1:1 как до задачи |
|
||||
| `ORCH_BUILD_CACHE_PRUNE_INTERVAL_S` | период тика авто-prune, сек; дефолт `21600` (~6 ч); валидация >0, иначе → дефолт |
|
||||
| `ORCH_BUILD_CACHE_PRUNE_UNTIL` | возраст удержания тёплого кэша (`docker builder prune --filter until=`); дефолт `24h`; валидация `^\d+[smhdw]?$`, иначе → `24h` |
|
||||
| `ORCH_BUILD_CACHE_PRUNE_ALL` | добавить `-a` к prune (только в паре с `until`); дефолт `false` |
|
||||
| `ORCH_BUILD_CACHE_PRUNE_TIMEOUT_S` | таймаут ssh-команды prune, сек; дефолт `120` |
|
||||
| `ORCH_BUILD_CACHE_PRUNE_NOTIFY_MIN_GB` | Telegram при освобождении ≥ N ГБ; дефолт `0` (тихо) |
|
||||
| `DEPLOY_SSH_USER` / `_HOST` / `DEPLOY_HOOK_SCRIPT` | параметры деплой-хука |
|
||||
|
||||
**Секреты — только в `.env` / `.env.staging` на хосте, в гит НЕ коммитятся.** Канон — `.env.example`, `.env.staging.example`.
|
||||
|
||||
@@ -1,200 +0,0 @@
|
||||
# ONBOARDING — turnkey-онбординг нового проекта (ORCH-009)
|
||||
|
||||
> RUNBOOK. Полный чеклист подключения нового проекта к оркестратору одним проходом.
|
||||
> Исполнитель — оператор; инструмент — CLI `scripts/onboard_project.py`
|
||||
> (режимы `plan` — дефолт/dry-run, `apply`, `verify`). Каждый шаг, который CLI выполнить
|
||||
> не может, помечен **🖐 РУЧНОЙ ШАГ** и снабжён командой проверки результата.
|
||||
> Архитектура решения — см. «Ссылки» внизу.
|
||||
|
||||
Запуск CLI — из корня чекаута репо orchestrator, в venv с `requirements.txt`:
|
||||
|
||||
```bash
|
||||
python3 scripts/onboard_project.py plan \
|
||||
--name "My Project" --description "зачем проект" \
|
||||
--repo my-project --prefix MP \
|
||||
--stack "Python 3.12 + FastAPI" --test-cmd "pytest tests/ -q" \
|
||||
--prod-port 8600 --staging-port 8601 \
|
||||
--webhook-url https://openclaw.mva154.duckdns.org/orchestrator/webhook/gitea
|
||||
```
|
||||
|
||||
`plan` печатает полный план **без единой мутации** (ни сети-POST, ни записи на диск);
|
||||
`apply` — идемпотентный ensure (существующее → `skipped(exists)`, ничего не удаляется);
|
||||
exit-коды: `0` — чисто, `2` — есть `manual-step`/gap, `1` — ошибка.
|
||||
|
||||
---
|
||||
|
||||
## 0. Предусловия
|
||||
|
||||
Все значения — в `.env` на хосте (секреты в гит не попадают):
|
||||
|
||||
| Переменная | Зачем | Проверка |
|
||||
|-----------|-------|----------|
|
||||
| `ORCH_PLANE_API_TOKEN` (+`ORCH_PLANE_API_URL`, `ORCH_PLANE_WORKSPACE_SLUG`) | создание/чтение проекта, статусов, лейблов | `curl -s -H "X-API-Key: $TOKEN" $URL/api/v1/workspaces/$SLUG/projects/ \| head -c 200` |
|
||||
| `ORCH_GITEA_TOKEN` (+`ORCH_GITEA_URL`) | создание репо + webhook | `curl -s -H "Authorization: token $TOKEN" $URL/api/v1/user \| head -c 200` |
|
||||
| `ORCH_GITEA_WEBHOOK_SECRET` | HMAC webhook (переиспользуется, один на все репо) | есть строка в `.env`; нет → `apply` сгенерирует и выведет |
|
||||
| `ORCH_PROJECTS_JSON` | текущий реестр — источник merged-вывода | `grep ORCH_PROJECTS_JSON .env` |
|
||||
|
||||
Токен Plane должен иметь право создавать проекты в workspace; токен Gitea — создавать репо и
|
||||
hooks под выбранным owner (`--gitea-owner`, дефолт из конфига).
|
||||
|
||||
---
|
||||
|
||||
## 1. Слой Plane: проект + статусы + лейблы
|
||||
|
||||
Выполняет `apply` (или вручную при недоступности API CE — каждый отказ CLI помечает
|
||||
`manual-step`, не падает).
|
||||
|
||||
1. **Проект**: создаётся с `identifier = --prefix`. Уже существует → передай
|
||||
`--plane-project-id <uuid>` (ensure распознает и пропустит).
|
||||
2. **Статусы — точные канонические имена** (22, источник — `plane_sync._PLANE_NAME_TO_KEY`;
|
||||
опечатка = тихая деградация fail-closed веток):
|
||||
|
||||
| Статус | Группа | | Статус | Группа |
|
||||
|--------|--------|-|--------|--------|
|
||||
| Backlog | `backlog` | | In Review | `started` |
|
||||
| Todo | `unstarted` | | Blocked | `started` |
|
||||
| To Analyse | `unstarted` | | Approved | `started` |
|
||||
| In Progress | `started` | | Rejected | `started` |
|
||||
| Analysis | `started` | | **Confirm Deploy** | `started` |
|
||||
| Architecture | `started` | | Needs Input | `started` |
|
||||
| Development | `started` | | Done | `completed` |
|
||||
| Code-Review | `started` | | Cancelled | `cancelled` |
|
||||
| Review | `started` | | **STOP** | **`cancelled`** |
|
||||
| Testing | `started` | | Awaiting Deploy | `started` |
|
||||
| Deploying | `started` | | Monitoring after Deploy | `started` |
|
||||
|
||||
⚠️ Код-критично: `STOP` обязан быть в группе `cancelled` (иначе ветка отмены молча не
|
||||
активируется); в терминальных группах (`completed`/`cancelled`) — ТОЛЬКО
|
||||
Done/Cancelled/STOP, иначе terminal-detection ложно сочтёт живую задачу терминальной.
|
||||
3. **Лейблы**: `autoApprove`, `autoDeploy`, `Bug` (имена — из конфига оркестратора; их
|
||||
отсутствие = fail-safe ручной режим / полный цикл).
|
||||
4. **🖐 РУЧНОЙ ШАГ — порядок статусов на доске**: drag-and-drop в UI (API не управляет
|
||||
порядком). Проверка: открой доску проекта — колонки в порядке конвейера.
|
||||
5. **Workspace-webhook**: уже **существует** (один на весь workspace, создан на уровне
|
||||
workspace заранее) — CLI его НЕ создаёт, только напоминает проверить:
|
||||
|
||||
```bash
|
||||
docker exec -e PGPASSWORD=plane plane-app-plane-db-1 psql -U plane -d plane -c \
|
||||
"SELECT id, url, is_active FROM webhooks;"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Слой Gitea: репо + per-repo webhook
|
||||
|
||||
1. **Репо** `--gitea-owner/--repo`: создаётся пустым (`auto_init=false`; ветку `main` создаст
|
||||
initial push следующего слоя). Существует → `skipped(exists)`.
|
||||
2. **Per-repo webhook**: `events: push/pull_request/status`, `content_type: json`,
|
||||
`branch_filter: *`, URL = `--webhook-url`. **Секрет переиспользуется** из
|
||||
`ORCH_GITEA_WEBHOOK_SECRET` (приёмник валидирует ОДИН глобальный секрет на все репо;
|
||||
новый секрет сломал бы HMAC существующих вебхуков). Секрета нет в env → CLI сгенерирует и
|
||||
выведет строку для `.env` — **🖐 РУЧНОЙ ШАГ**: добавить её в `.env` (в гит не коммитить).
|
||||
Формат и проверка — `docs/operations/SETUP_WEBHOOKS.md`. Проверка:
|
||||
|
||||
```bash
|
||||
curl -s -H "Authorization: token $ORCH_GITEA_TOKEN" \
|
||||
"$ORCH_GITEA_URL/api/v1/repos/<owner>/<repo>/hooks" | python3 -m json.tool
|
||||
```
|
||||
3. **Branch protection `main` НЕ включать** (ADR D10): required-approvals/status-checks ломают
|
||||
PR-merge API merge-актора конвейера (ложные HOLD). Защита держится конвенцией + скоупом
|
||||
токенов.
|
||||
|
||||
---
|
||||
|
||||
## 3. Слой kit: материализация + initial push
|
||||
|
||||
1. `apply` рендерит kit (`onboarding/repo-skeleton/`, плейсхолдеры `{{NAME}}` из
|
||||
`onboarding/placeholders.json`) во временный каталог, докладывает live-copy канона
|
||||
(`docs/_templates/` 16 скелетов + `docs/_standards/` 3 стандарта — verbatim из текущего
|
||||
чекаута, BR-2 «канон не форкается») и пушит **ТОЛЬКО в свежесозданный/пустой репо**
|
||||
(единственный разрешённый push; коммит `feat: onboarding skeleton (ORCH-009 kit)`).
|
||||
2. Репо непустой → шаг помечается `manual-step`: **🖐 РУЧНОЙ ШАГ** — занеси недостающие
|
||||
файлы обычным PR с ревью; поверх существующего контента ничего не пушится (BR-9).
|
||||
3. После рендера не должно остаться ни одного `{{...}}`: CLI падает на этом сам; повторная
|
||||
проверка — `verify` (скан плейсхолдеров в файлах репо).
|
||||
|
||||
---
|
||||
|
||||
## 4. Регистрация в реестре оркестратора
|
||||
|
||||
> ⚠️ **САМЫЙ ВАЖНЫЙ РУЧНОЙ СЛОЙ.** CLI `.env` прода НЕ правит и контейнер НЕ рестартит
|
||||
> (инвариант NFR-2) — он только печатает готовую строку.
|
||||
|
||||
1. **🖐 РУЧНОЙ ШАГ — env**: возьми из отчёта `apply` строку
|
||||
`ORCH_PROJECTS_JSON=[...полный merged-массив...]` (существующие записи verbatim + новая в
|
||||
конец; строка уже провалидирована фактическим парсером реестра) и замени ею строку в `.env`
|
||||
оркестратора на хосте. Вставляется атомарно одной строкой — ручное слияние JSON не нужно.
|
||||
2. **🖐 РУЧНОЙ ШАГ — управляемый рестарт оркестратора**: реестр строится при импорте, нужна
|
||||
перезагрузка процесса. **Self-hosting предупреждение: прод-контейнер один на ВСЕ проекты —
|
||||
рестарт = групповое окно** (встаёт конвейер всех проектов). Выполняй осознанно: дождись
|
||||
тихого окна (`GET /queue` — нет бегущих job), затем штатный рестарт по
|
||||
`docs/operations/INFRA.md`. Проверка после рестарта:
|
||||
|
||||
```bash
|
||||
curl -s http://localhost:8500/health
|
||||
curl -s http://localhost:8500/queue | python3 -m json.tool | head -30 # реестр жив, конвейер пуст/цел
|
||||
```
|
||||
3. TTL-self-heal статусов Plane (300с) рестарта НЕ требует: статусы/лейблы, созданные после
|
||||
регистрации, подхватятся сами.
|
||||
|
||||
---
|
||||
|
||||
## 5. Верификация
|
||||
|
||||
1. **`verify`-режим CLI** (read-only):
|
||||
|
||||
```bash
|
||||
python3 scripts/onboard_project.py verify --name ... --repo ... --prefix ... \
|
||||
--plane-project-id <uuid> --stack ... --test-cmd ... --prod-port ... --staging-port ... \
|
||||
--webhook-url https://openclaw.mva154.duckdns.org/orchestrator/webhook/gitea
|
||||
```
|
||||
|
||||
Проверяет: запись реестра парсится и совпадает по полям; все 22 статуса резолвятся
|
||||
(включая fail-closed `Confirm Deploy`/`STOP`); лейблы на месте; webhook существует и
|
||||
активен; kit-файлы в репо (6 промптов, `AGENTS.md`, `INFRA.md`, `_templates`/`_standards`);
|
||||
нет неразрешённых плейсхолдеров. Любой gap → exit `2` с перечнем.
|
||||
|
||||
2. **Smoke на песочнице (ADR D8)** — контур: **staging-оркестратор (порт 8501, изолированная
|
||||
БД `./data/staging`)** + одноразовый sandbox-проект (рекомендуемые имена: проект
|
||||
`onboarding-smoke`, префикс `SMK`, репо `onboarding-smoke`):
|
||||
1. Онборди sandbox самим CLI (слои 1–3 этого runbook).
|
||||
2. **🖐 РУЧНОЙ ШАГ**: зарегистрируй sandbox в `ORCH_PROJECTS_JSON` **`.env.staging`**
|
||||
(не прода!) и перезапусти staging-контейнер (он свободен от прод-инварианта):
|
||||
`docker compose --profile staging up -d orchestrator-staging`.
|
||||
3. Создай тестовую задачу в sandbox-проекте → доведи до стадии analysis в песочнице.
|
||||
4. Критерий PASS: агент по своему промпту **прочитал доку проекта** (следы чтения
|
||||
`CLAUDE.md`/`AGENTS.md` в выводе) и **записал артефакты** в `docs/work-items/SMK-…/`
|
||||
по канону `PIPELINE_DOCS.md`.
|
||||
5. Запротоколируй прогон в «Журнале smoke-прогонов» (ниже). Для приёмки ORCH-009 первый
|
||||
протокол обязателен.
|
||||
|
||||
---
|
||||
|
||||
## 6. Откат
|
||||
|
||||
CLI ничего не удаляет (BR-9) — откат всегда ручной и осознанный:
|
||||
|
||||
| Что создано | Как откатить | Проверка |
|
||||
|-------------|--------------|----------|
|
||||
| Plane-проект (+статусы/лейблы) | удалить проект в UI Plane | проект исчез из списка workspace |
|
||||
| Gitea-репо (+webhook) | удалить репо в UI/API Gitea (webhook умрёт вместе с ним) | `GET /api/v1/repos/<owner>/<repo>` → 404 |
|
||||
| Строка реестра | убрать запись из `ORCH_PROJECTS_JSON` в `.env` + управляемый рестарт (см. слой 4, то же групповое окно) | `GET /queue` — проекта нет в реестре |
|
||||
| Sandbox-артефакты smoke | удалить sandbox-проект/репо после прогона (или архивировать) | см. выше |
|
||||
|
||||
---
|
||||
|
||||
## Журнал smoke-прогонов
|
||||
|
||||
| Дата | Оператор | Параметры (проект/префикс/репо) | Контур | Результат (PASS/FAIL) | Протокол |
|
||||
|------|----------|----------------------------------|--------|------------------------|----------|
|
||||
| — | — | — (первый прогон фиксируется при приёмке ORCH-009) | staging 8501 | — | — |
|
||||
|
||||
---
|
||||
|
||||
## Ссылки
|
||||
|
||||
- Архитектура решения: `docs/work-items/ORCH-009/06-adr/ADR-001-turnkey-onboarding-kit-and-cli.md`
|
||||
(D1…D11); сквозной ADR — `docs/architecture/adr/adr-0035-turnkey-project-onboarding.md`.
|
||||
- Устройство набора шаблонов и словарь плейсхолдеров: `onboarding/README.md`.
|
||||
- Формат вебхуков: `docs/operations/SETUP_WEBHOOKS.md`; топология и рестарты —
|
||||
`docs/operations/INFRA.md`.
|
||||
@@ -12,36 +12,30 @@ Internal URL: `http://127.0.0.1:8500/`
|
||||
|
||||
---
|
||||
|
||||
## Gitea Webhook (per-repo)
|
||||
## Gitea Webhook
|
||||
|
||||
Gitea-webhook — **per-repo**: создаётся для КАЖДОГО подключаемого к оркестратору репозитория
|
||||
(`<repo>` ниже). Для новых проектов его создаёт onboarding-CLI
|
||||
(`scripts/onboard_project.py apply`) — полный процесс см. `docs/operations/ONBOARDING.md`;
|
||||
команды ниже — для ручной проверки/пересоздания на любом репо.
|
||||
**Создан автоматически через API.**
|
||||
|
||||
- URL: `https://openclaw.mva154.duckdns.org/orchestrator/webhook/gitea`
|
||||
- Events: `push`, `pull_request`, `status`
|
||||
- Secret: значение `ORCH_GITEA_WEBHOOK_SECRET` в `.env` — **ОДИН глобальный секрет на все
|
||||
репо** (приёмник валидирует только его; новый секрет на одном репо сломал бы HMAC остальных —
|
||||
при ротации меняется на всех репо разом)
|
||||
- Secret: значение `ORCH_GITEA_WEBHOOK_SECRET` в `.env`
|
||||
- Signature header: `X-Gitea-Signature` (HMAC-SHA256 hex digest)
|
||||
|
||||
### Проверка
|
||||
|
||||
```bash
|
||||
GITEA_TOKEN=$(grep ORCH_GITEA_TOKEN /home/slin/repos/orchestrator/.env | cut -d= -f2)
|
||||
curl -s "http://localhost:3000/api/v1/repos/<owner>/<repo>/hooks" \
|
||||
curl -s "http://localhost:3000/api/v1/repos/admin/enduro-trails/hooks" \
|
||||
-H "Authorization: token ${GITEA_TOKEN}" | python3 -m json.tool
|
||||
```
|
||||
|
||||
### Пересоздание (если нужно)
|
||||
|
||||
```bash
|
||||
# Секрет переиспользуй из .env (ORCH_GITEA_WEBHOOK_SECRET); генерируй новый ТОЛЬКО при
|
||||
# первичной настройке/осознанной ротации (и обнови вебхуки ВСЕХ репо):
|
||||
GITEA_WEBHOOK_SECRET=$(grep ORCH_GITEA_WEBHOOK_SECRET /home/slin/repos/orchestrator/.env | cut -d= -f2)
|
||||
GITEA_WEBHOOK_SECRET=$(openssl rand -hex 20)
|
||||
# Обновить в .env: ORCH_GITEA_WEBHOOK_SECRET=<new_secret>
|
||||
|
||||
curl -X POST "http://localhost:3000/api/v1/repos/<owner>/<repo>/hooks" \
|
||||
curl -X POST "http://localhost:3000/api/v1/repos/admin/enduro-trails/hooks" \
|
||||
-H "Authorization: token ${GITEA_TOKEN}" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
|
||||
@@ -1,7 +0,0 @@
|
||||
# Business Request: Онбординг проектов в оркестратор (turnkey: Plane + репо + агенты + инфра)
|
||||
|
||||
Work Item ID: ORCH-009
|
||||
|
||||
## Description
|
||||
|
||||
TBD
|
||||
@@ -1,176 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-009
|
||||
stage: analysis
|
||||
author_agent: analyst
|
||||
status: ready-for-review
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# 01 — BRD: ORCH-009 — Онбординг проектов в оркестратор (turnkey: Plane + репо + агенты + инфра)
|
||||
|
||||
Work Item: **ORCH-009** · Repo: **orchestrator** (self-hosting) · Стадия: analysis
|
||||
Заказчик: Слава · Домен эпика: 📈 **D5 Масштаб (D5.2)** — `docs/epics/self-evolution.md`
|
||||
|
||||
> ⚠️ **Актуализация Владельца 10.06 принята как приоритетная над исходной постановкой 05.06.**
|
||||
> Эталон онбординга = **сам репозиторий orchestrator** (каноны ORCH-52b/c/d/e уже кодифицированы),
|
||||
> НЕ enduro-trails (устаревший пример). «Дыра: у orchestrator только deployer.md» — уже закрыта
|
||||
> (в `.openclaw/agents/` полный набор 6 промптов). Скоуп — **способность** разворачивать новый
|
||||
> проект по образцу орка одним проходом; онбординг конкретного нового заказчика — исполнение этой
|
||||
> способности, вне данной задачи.
|
||||
|
||||
---
|
||||
|
||||
## 1. Бизнес-контекст и проблема
|
||||
|
||||
### 1.1. Цель
|
||||
При подключении **нового** проекта к оркестратору одним проходом разворачивается всё, что нужно
|
||||
мульти-агентам для автономной работы: Plane-проект (статусы/лейблы под машинные контракты),
|
||||
Gitea-репо (+webhook), полный набор промптов агентов, структура документации по единым канонам,
|
||||
инфра-описание (INFRA.md), регистрация в реестре проектов. Агенты нового проекта **обязаны** знать,
|
||||
где лежит документация, использовать её и актуализировать.
|
||||
|
||||
### 1.2. Проблема сегодня
|
||||
Онбординг проекта — ручная археология: шаги размазаны по докам (`SETUP_WEBHOOKS.md`,
|
||||
`INFRA.md`), памяти Стрима/Славы и инцидентам (прецедент 2026-06-02: webhook всего workspace +
|
||||
захардкоженный `default_repo` → задачи чужого проекта падали в enduro-trails; закрыто реестром
|
||||
ORCH-6). Любой пропущенный шаг даёт **тихую деградацию**: без промптов в репо конвейер проекта не
|
||||
работает вовсе; без точных имён статусов Plane ветки `Confirm Deploy`/`STOP` молча не активируются
|
||||
(fail-closed); без лейблов авто-режимы и багфикс-трек молча выключены (fail-safe). Турникей-проход
|
||||
обязан закрывать все слои сразу и проверяемо.
|
||||
|
||||
### 1.3. Установленные факты (проверено по коду, не изобретать)
|
||||
|
||||
| # | Факт | Где проверено |
|
||||
|---|------|---------------|
|
||||
| Ф-1 | Промпты агентов — **per-repo**: launcher резолвит `system_prompt: .openclaw/agents/<role>.md` относительно worktree репо задачи. Нет промптов в новом репо → конвейер для него не работает. | `src/agents/launcher.py` (реестр AGENTS, 6 ролей) |
|
||||
| Ф-2 | Агент видит **только** worktree своего репо → каноны (шаблоны/стандарты) обязаны быть **скопированы** в новый репо; «ссылка на репо орка» агенту недоступна. | модель worktree `src/git_worktree.py`, launcher |
|
||||
| Ф-3 | Реестр проектов строится **при импорте** из `ORCH_PROJECTS_JSON` (или built-in default): ключи `plane_project_id`/`repo`/`work_item_prefix`/`name` + опц. `agent_models`/`agent_efforts`. Регистрация нового проекта = правка `.env` на хосте + **управляемый рестарт** (операторский шаг). | `src/projects.py` (`_parse_projects_json`, `_load_projects`) |
|
||||
| Ф-4 | Статусы Plane резолвятся по **точным именам** (22 ключа `_PLANE_NAME_TO_KEY`); `Confirm Deploy` (ORCH-059) и `STOP` (группа `cancelled`, ORCH-090) — **fail-closed** (нет статуса на доске → ветка не активируется); TTL-self-heal 300с (ORCH-068) — статус, добавленный позже, подхватывается без рестарта. | `src/plane_sync.py` (`_PLANE_NAME_TO_KEY`, `get_project_states`) |
|
||||
| Ф-5 | Лейблы `autoApprove`/`autoDeploy` (ORCH-089) и `Bug` (ORCH-019) — **fail-safe** (нет лейбла → ручной режим / полный цикл); сопоставление по нормализованному имени через Plane API. | `src/labels.py`, `src/bug_fast_track.py`, CLAUDE.md (инфра-предусловия) |
|
||||
| Ф-6 | Plane-webhook — **workspace-level** (один на все проекты, уже существует; в Plane CE создаётся SQL-ом, внешнего API нет). Gitea-webhook — **per-repo** (создаётся через API; events `push`/`pull_request`/`status`; HMAC-secret). | `docs/operations/SETUP_WEBHOOKS.md`, docstring `src/projects.py` |
|
||||
| Ф-7 | Каноны (golden source) в репо орка: `docs/_templates/` — 16 скелетов (`00…18`, ORCH-52b); `docs/_standards/` — `HANDOFF_PROTOCOL.md`/`PIPELINE_DOCS.md`/`TRACEABILITY.md` (ORCH-52c/e); `.openclaw/agents/*.md` — 6 промптов канона Anthropic (ORCH-52d/92; `deployer.md` — английский **нормативно**, ADR-001 D2 ORCH-092); ADR-конвенция — `PIPELINE_DOCS.md` §4. | листинг репо, `docs/_standards/PIPELINE_DOCS.md` |
|
||||
| Ф-8 | Per-repo паспорт `CLAUDE.md` — канон самого ORCH-9 (подпись в паспорте орка: «канон per-repo, см. ORCH-9»); все 6 промптов орка начинаются с «прочти CLAUDE.md». | `CLAUDE.md`, `.openclaw/agents/*.md` |
|
||||
|
||||
### 1.4. Принятая трактовка постановки (расхождения 05.06 ↔ 10.06)
|
||||
- **Реализация в репо orchestrator** (данный конвейер пишет в этот репо; каноны живут здесь).
|
||||
Упоминание отдельного репо `onboard2orch` (05.06) — историческое: его пример enduro-trails
|
||||
объявлен устаревшим; судьба репо — операторское решение вне кода (рекомендация: архивировать/
|
||||
оставить указатель, чтобы не плодить второй источник канона). Эскалации не требует: актуализация
|
||||
10.06 прямо говорит «каноны кодифицированы в репо орка — их и брать за образец».
|
||||
- **Раскладка docs/**: слой-1 постановки (05.06) указывал `docs/adr/`; канон орка —
|
||||
`docs/architecture/adr/` (сквозные) + `docs/work-items/<id>/06-adr/` (per-task). Применяется
|
||||
канон орка (эталон = орк).
|
||||
|
||||
---
|
||||
|
||||
## 2. Объём (scope)
|
||||
|
||||
### 2.1. В объёме
|
||||
- **Onboarding-kit**: параметризуемый каркас нового репо — 6 промптов агентов, паспорт
|
||||
`CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, `README.md`, `CHANGELOG.md`, скелет `docs/`
|
||||
(включая `operations/INFRA.md`), копии `docs/_templates/` + `docs/_standards/`.
|
||||
- **Onboarding-скрипт** (операторский CLI, вне конвейера): Gitea-репо + per-repo webhook,
|
||||
Plane-проект + статусы + лейблы (в мере, доступной API), материализация kit (подстановка
|
||||
параметров) + initial push в свежесозданный репо, генерация валидной записи реестра, режимы
|
||||
dry-run / apply / verify, идемпотентность.
|
||||
- **Runbook** `docs/operations/ONBOARDING.md`: полный чеклист, явная маркировка ручных шагов
|
||||
(env + управляемый рестарт; UI-only действия Plane), верификация, откат.
|
||||
- **Верификация способности**: автоматические структурные тесты kit (pytest) + документированный
|
||||
smoke-прогон на песочнице («агент по своему промпту находит доку, использует и актуализирует»).
|
||||
- **Актуализация обзорных доков** в том же PR (CLAUDE.md, `docs/architecture/README.md`,
|
||||
CHANGELOG, обобщение `SETUP_WEBHOOKS.md`).
|
||||
|
||||
### 2.2. Вне объёма (явно, не делать)
|
||||
- Исполнение онбординга конкретного нового заказчика/проекта (включая правку прод-`.env` и
|
||||
рестарт прода) — операторская эксплуатация способности.
|
||||
- ORCH-10 — тиражирование платформы на новый хост (IaC-bundle); мультитенантность (D5.6);
|
||||
параллелизм D5.1.
|
||||
- Стеки-плагины D4.1 (профили web/mobile/data/ML): kit параметризуется плейсхолдерами, без
|
||||
механизма профилей.
|
||||
- Любые изменения `src/**`: машина стадий, QG, launcher, реестр `projects.py` (его контракт уже
|
||||
достаточен — регистрация через `ORCH_PROJECTS_JSON`), схема БД.
|
||||
- Создание/миграция Plane workspace-webhook (уже существует, общий на workspace).
|
||||
- Слой-3 продуктовый мониторинг онбордируемого приложения (фундамент эпика, отдельные задачи).
|
||||
|
||||
---
|
||||
|
||||
## 3. Заинтересованные стороны
|
||||
- **Владелец/оператор (Слава, Стрим):** запускает онбординг, выполняет операторские шаги
|
||||
(env, рестарт, UI-шаги Plane), принимает результат smoke-прогона.
|
||||
- **Будущие заказчики/проекты:** получают рабочий автономный конвейер «за минуты» (D5.2).
|
||||
- **Действующие проекты (enduro-trails, orchestrator):** не должны почувствовать онбординг
|
||||
соседа — общий прод-инстанс, общая БД, общая очередь (self-hosting, ORCH-1).
|
||||
- **Агенты конвейера:** потребители kit — промпты обязаны вести их к доке проекта.
|
||||
|
||||
---
|
||||
|
||||
## 4. Бизнес-требования (BR)
|
||||
|
||||
| ID | Требование | Связь |
|
||||
|----|------------|-------|
|
||||
| BR-1 | **Turnkey-проход:** один документированный проход (скрипт + runbook) разворачивает все слои: Plane-проект (статусы+лейблы) → Gitea-репо (+webhook) → kit в репо (initial push) → запись реестра → верификация. Список шагов закрыт и воспроизводим. | AC-1, AC-11 |
|
||||
| BR-2 | **Единый эталон без форка:** kit производится от **живых** канонов репо орка — `docs/_templates/`/`docs/_standards/` копируются в новый репо в момент онбординга «как есть»; параметризация — только в kit-собственных шаблонах (промпты, паспорт, INFRA и пр.). Вторая редактируемая копия канона внутри орка не создаётся. enduro-trails эталоном не является. | AC-5, Ф-2/Ф-7 |
|
||||
| BR-3 | **Полный набор промптов:** 6 ролей (analyst/architect/developer/reviewer/tester/deployer), параметризуемых под проект/стек, по канону Anthropic 52d: 5 XML-секций в нормативном порядке, запреты «❌ X → ✅ Y», `<escalation>` у developer/reviewer/tester (ORCH-092), добровольная эмиссия 6-польной frontmatter-схемы 52c, machine-verdict ключи байт-в-байт (`verdict:`/`result:`/`staging_status:`/`deploy_status:`/`security_status:`). Каждый промпт жёстко направляет: читай паспорт/`AGENTS.md`/доку ПЕРЕД работой, пиши артефакты в `docs/work-items/<id>/` по канону, обновляй CHANGELOG/доку. | AC-2, AC-4 |
|
||||
| BR-4 | **Reviewer-gate на доку:** шаблон reviewer-промпта содержит проверку «документация обновлена; нет → REQUEST_CHANGES» (канон держится автоматически, не на честном слове). | AC-3 |
|
||||
| BR-5 | **Каркас репо полон:** `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, `AGENTS.md` (точка входа агентов: карта доков + правила), паспорт `CLAUDE.md`, `docs/` (архитектура, конвейер, продукт-видение, `operations/`, ADR-реестр, `work-items/`, `history/`), копии `_templates/`+`_standards/`. Ссылочная целостность: промпты ссылаются только на реально существующие в каркасе пути. | AC-1, AC-5 |
|
||||
| BR-6 | **INFRA.md обязателен:** топология (контейнеры/порты прод+staging/сеть/тома/БД), карта env-переменных (дескрипторы в репо, секреты только в `.env` на хосте, `.env.example` — канон), границы доступа, риски общего хоста. Для самого орка существующие self-hosting-предупреждения (общая БД/очередь/groupwide-риск рестарта) сохраняются нетронутыми. | AC-10 |
|
||||
| BR-7 | **Plane-проект под машинные контракты:** статусы с **точными** каноническими именами (все 22 имени `_PLANE_NAME_TO_KEY`, включая `Confirm Deploy` и `STOP` с группой `cancelled`) + лейблы `autoApprove`/`autoDeploy`/`Bug`. Что недоступно через Plane API — явный ручной пункт runbook с командой проверки. | AC-7, Ф-4/Ф-5 |
|
||||
| BR-8 | **Регистрация в реестре:** скрипт генерирует запись `ORCH_PROJECTS_JSON`, валидную через фактический парсер `projects._parse_projects_json` (round-trip). Применение env + рестарт — **операторский** шаг, явно описанный в runbook; скрипт прод-контейнер НЕ рестартит. | AC-6, AC-9, Ф-3 |
|
||||
| BR-9 | **Безопасность исполнения:** dry-run по умолчанию / явный apply; идемпотентный повторный прогон (доделывает недостающее, не дублирует, ничего не удаляет); аддитивность — существующие проекты/репо не модифицируются; push — только initial в свежесозданный пустой репо (никогда в `main` существующих). | AC-8, AC-9 |
|
||||
| BR-10 | **Верификация способности:** (а) автоматические структурные тесты kit/скрипта (pytest, без сети); (б) verify-режим: registry-валидность, резолв статусов, наличие webhook, полнота kit; (в) документированный smoke на песочнице: новый агент по своему промпту находит доку, использует и актуализирует её. | AC-12, AC-13 |
|
||||
| BR-11 | **Прозрачность:** каждый шаг скрипта логируется; итоговый отчёт «создано / уже было (пропущено) / требует ручного шага». | AC-8 |
|
||||
|
||||
---
|
||||
|
||||
## 5. Нефункциональные требования (NFR)
|
||||
|
||||
| ID | Требование |
|
||||
|----|------------|
|
||||
| NFR-1 | **`src/**` не меняется.** Изменение — docs/templates/scripts/tests-only. `STAGE_TRANSITIONS`, реестр `QG_CHECKS`, `check_*`, machine-verdict ключи, схема БД, контракт `projects.py` — байт-в-байт. |
|
||||
| NFR-2 | **Self-hosting безопасность:** скрипт никогда не рестартит/не останавливает прод-контейнер, не пишет в общую БД, не пушит в `main` существующих репо, не трогает чужие Plane-проекты/Gitea-репо. Онбординг соседа не влияет на enduro/orchestrator. |
|
||||
| NFR-3 | **Секреты:** токены Plane/Gitea — только из env на хосте; сгенерированные секреты (webhook HMAC) выводятся оператору для `.env` и в гит не попадают; `.env.example` — канон. |
|
||||
| NFR-4 | **Anti-drift:** структурные тесты канона для kit-промптов (аналог `tests/test_agent_prompts_canon.py`) — расхождение kit с каноном 52d ловится CI, а не глазами. |
|
||||
| NFR-5 | **Оффлайн-тестируемость:** все тесты детерминированы, без реальных вызовов Plane/Gitea (моки); сетевые шаги изолированы за тонким слоем. |
|
||||
| NFR-6 | **Документация = golden source:** CLAUDE.md / `docs/architecture/README.md` / CHANGELOG обновлены в том же PR; reviewer-gate применим к самому PR. |
|
||||
|
||||
---
|
||||
|
||||
## 6. Допущения и ограничения
|
||||
- Plane API v1 позволяет создавать проект/статусы/лейблы (issue-API уже используется кодом);
|
||||
если на практике какой-то вызов недоступен в CE — шаг деградирует в ручной пункт runbook
|
||||
(fail-safe постановки, не блокер задачи).
|
||||
- Скрипт — операторский инструмент: запускается человеком на хосте с токенами из `.env`,
|
||||
**вне** конвейера задач; конвейер его не вызывает.
|
||||
- Регистрация проекта вступает в силу после операторского рестарта (Ф-3) — это сознательное
|
||||
ограничение (никакой автоматики рестартов, NFR-2); TTL-self-heal статусов (Ф-4) рестарта
|
||||
не требует.
|
||||
- Песочница для smoke — staging-контур (8501, изолированная БД, sandbox-проект) либо одноразовый
|
||||
sandbox-проект в Plane/Gitea; выбор фиксирует архитектор/оператор в runbook.
|
||||
- Языковая политика kit-промптов: по канону орка (5 ru + deployer en, ADR-001 D2 ORCH-092);
|
||||
окончательное слово за архитектором, отступление — только с обоснованием в ADR.
|
||||
|
||||
---
|
||||
|
||||
## 7. Критерии успеха (резюме; детали — 03-acceptance-criteria.md)
|
||||
- Kit полон и канон-чист (структурные тесты зелёные): 6 промптов 52d + reviewer-gate + каркас
|
||||
репо + INFRA.md + копии канонов.
|
||||
- Скрипт: dry-run печатает полный план без мутаций; apply идемпотентен; registry-запись проходит
|
||||
round-trip через фактический парсер; план Plane содержит точные имена статусов и лейблы.
|
||||
- Runbook закрывает 100% шагов (ручные — помечены) и верификацию.
|
||||
- `src/**` не тронут; пайплайн-инварианты байт-в-байт.
|
||||
- Smoke на песочнице: агент по промпту находит и актуализирует доку (документированный прогон).
|
||||
|
||||
---
|
||||
|
||||
## 8. Риски (кратко; детали — 10-tech-risks.md, заполняет архитектор)
|
||||
- **R-1 Drift канона:** копия канонов в kit/новых репо разъезжается с живым каноном орка →
|
||||
митигируется BR-2 (live-copy в момент онбординга) + NFR-4 (структурные тесты).
|
||||
- **R-2 Тихая деградация Plane-контрактов:** опечатка в имени статуса/лейбла → fail-closed/
|
||||
fail-safe ветки молча не работают → митигируется BR-7 (точные имена из кода) + verify-режимом.
|
||||
- **R-3 Скрипт с боевыми токенами:** ошибка = разрушительное действие → dry-run по умолчанию,
|
||||
никаких delete-операций, аддитивность (BR-9).
|
||||
- **R-4 «Скрипт сделал — оператор не знает про env+restart»:** проект создан, но невидим для
|
||||
оркестратора → runbook явно фиксирует операторские шаги + verify-режим показывает разрыв (BR-8/10).
|
||||
- **R-5 Утечка орк-специфики в kit:** новый проект получает чужие литералы (ORCH-, порты 8500/8501,
|
||||
self-hosting-правила) → структурный тест на остаточные плейсхолдеры/литералы (AC-5).
|
||||
@@ -1,227 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-009
|
||||
stage: analysis
|
||||
author_agent: analyst
|
||||
status: ready-for-review
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# 02 — ТЗ (TRZ): ORCH-009 — Онбординг проектов в оркестратор (turnkey)
|
||||
|
||||
Work Item: **ORCH-009** · Repo: **orchestrator** · Стадия: analysis
|
||||
|
||||
> ТЗ описывает **что** должно измениться и **где** (модули/контракты/артефакты). **Как** (точная
|
||||
> раскладка kit, механизм подстановки, формат CLI) — решает архитектор в `06-adr/`. Имена путей
|
||||
> ниже — рабочее предложение; архитектор вправе скорректировать, сохранив требования и AC.
|
||||
|
||||
> ⚠️ Скоуп по актуализации 10.06: эталон = репо orchestrator; deliverables — в этом репо.
|
||||
> `src/**` НЕ меняется (NFR-1) — задача docs/templates/scripts/tests-only.
|
||||
|
||||
---
|
||||
|
||||
## 1. Сводка изменения
|
||||
Создать **способность turnkey-онбординга** нового проекта: (1) параметризуемый **onboarding-kit**
|
||||
(каркас нового репо: 6 промптов агентов по канону 52d/92, паспорт, AGENTS/CONTRIBUTING, скелет
|
||||
`docs/` с INFRA.md, копии живых канонов `_templates/`+`_standards/`); (2) операторский
|
||||
**onboarding-скрипт** (Gitea-репо + per-repo webhook; Plane-проект + статусы + лейблы;
|
||||
материализация kit + initial push; генерация записи реестра; dry-run/apply/verify; идемпотентно);
|
||||
(3) **runbook** `docs/operations/ONBOARDING.md` (полный чеклист, ручные шаги, верификация);
|
||||
(4) **структурные тесты** анти-дрейфа. Конвейер/движок не трогаются.
|
||||
|
||||
---
|
||||
|
||||
## 2. Задействованные модули / пути
|
||||
|
||||
| Путь | Действие | Роль |
|
||||
|------|----------|------|
|
||||
| `onboarding/repo-skeleton/**` | создать | параметризуемый kit нового репо (дерево зеркалит целевой репо: `.openclaw/agents/*.md`, `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, `README.md`, `CHANGELOG.md`, `docs/**`) |
|
||||
| `onboarding/README.md` | создать | устройство kit: словарь плейсхолдеров, правило «канон не форкается» (что копируется live, что шаблонизируется) |
|
||||
| `scripts/onboard_project.py` | создать | операторский turnkey-CLI: `plan` (dry-run, дефолт) / `apply` / `verify`; идемпотентность; отчёт |
|
||||
| `docs/operations/ONBOARDING.md` | создать | runbook: последовательность, ручные шаги (env+рестарт, UI-only Plane), верификация, откат |
|
||||
| `docs/operations/SETUP_WEBHOOKS.md` | обновить | обобщить per-repo Gitea-webhook секцию (сейчас примеры захардкожены на enduro-trails); сослаться на ONBOARDING.md |
|
||||
| `tests/test_onboarding_kit.py` | создать | структура kit, канон промптов, reviewer-gate, INFRA/AGENTS/CONTRIBUTING |
|
||||
| `tests/test_onboarding_script.py` | создать | рендер/плейсхолдеры, registry round-trip, dry-run/идемпотентность, план Plane/Gitea (моки) |
|
||||
| `tests/test_onboarding_invariants.py` | создать | `src/**` не тронут логикой онбординга; снапшот `STAGE_TRANSITIONS`/`QG_CHECKS` |
|
||||
| `CLAUDE.md`, `docs/architecture/README.md`, `CHANGELOG.md` | обновить | golden source: раздел «Онбординг проектов (ORCH-009)», запись changelog |
|
||||
| `src/**` | **не менять** | NFR-1; скрипту разрешён **read-only import** `src.projects._parse_projects_json` / констант `src.plane_sync._PLANE_NAME_TO_KEY` для round-trip и точных имён (не дублировать литералы) — допустимость импорта vs снапшот-фикстура решает архитектор |
|
||||
|
||||
Справочные источники kit (read-only): `.openclaw/agents/*.md`, `docs/_templates/` (16 скелетов),
|
||||
`docs/_standards/` (3 стандарта), `docs/operations/INFRA.md` (образец структуры RUNBOOK).
|
||||
|
||||
---
|
||||
|
||||
## 3. Функциональные требования
|
||||
|
||||
### FR-1 — Onboarding-kit: состав каркаса нового репо (BR-3/BR-5/BR-6)
|
||||
`onboarding/repo-skeleton/` содержит (минимум):
|
||||
|
||||
```
|
||||
.openclaw/agents/{analyst,architect,developer,reviewer,tester,deployer}.md ← шаблоны промптов
|
||||
CLAUDE.md ← паспорт проекта (per-repo канон, Ф-8)
|
||||
AGENTS.md ← точка входа агентов: карта доков + правила ведения
|
||||
CONTRIBUTING.md ← канон процесса: где что лежит, как вести
|
||||
README.md ← entrypoint: что это, quickstart, ссылки
|
||||
CHANGELOG.md ← пустой каркас
|
||||
docs/ARCHITECTURE.md ← код-карта/потоки/БД (заполняется по мере жизни)
|
||||
docs/PIPELINE.md ← стадии, QG, агенты (ссылается на _standards)
|
||||
docs/PRODUCT_VISION.md ← зачем проект (BRD-свод)
|
||||
docs/operations/INFRA.md ← обязательный RUNBOOK (см. FR-3)
|
||||
docs/architecture/adr/ ← реестр сквозных ADR (канон орка, §1.4 BRD)
|
||||
docs/work-items/.gitkeep
|
||||
docs/history/.gitkeep
|
||||
docs/_templates/ ← live-копия канона орка в момент онбординга (BR-2)
|
||||
docs/_standards/ ← live-копия канона орка в момент онбординга (BR-2)
|
||||
.env.example ← заготовка карты env (без секретов)
|
||||
```
|
||||
|
||||
- **Параметризация** — единый словарь плейсхолдеров (минимум): `{{PROJECT_NAME}}`, `{{REPO}}`,
|
||||
`{{WORK_ITEM_PREFIX}}`, `{{PLANE_PROJECT_ID}}`, `{{STACK}}`, `{{TEST_CMD}}`,
|
||||
`{{PROD_PORT}}`/`{{STAGING_PORT}}` (расширяемо; единый синтаксис, фиксирует архитектор).
|
||||
- **Ссылочная целостность:** каждый путь, на который ссылаются kit-промпты/AGENTS.md, существует
|
||||
в каркасе (проверяемо тестом).
|
||||
- **Правило «канон не форкается» (BR-2):** `docs/_templates/` и `docs/_standards/` НЕ хранятся
|
||||
второй редактируемой копией в kit — копируются скриптом из живого канона репо орка в момент
|
||||
материализации. В kit хранятся только параметризуемые дельты (промпты, паспорт, AGENTS,
|
||||
CONTRIBUTING, README, INFRA и пр.).
|
||||
|
||||
### FR-2 — Шаблоны промптов 6 ролей по канону 52d/92 (BR-3/BR-4)
|
||||
Каждый из 6 шаблонов промптов:
|
||||
- 5 обязательных XML-секций в нормативном порядке `<context>` → `<task>` → `<deliverables>` →
|
||||
`<constraints>` → `<output_format>`; `<success_criteria>`; `<escalation>` у
|
||||
developer/reviewer/tester (после `</success_criteria>`); `<thinking>` у решающих ролей —
|
||||
как в эталоне `.openclaw/agents/` (ORCH-077/092).
|
||||
- Запреты в формате «❌ X → ✅ Y».
|
||||
- Директивы доки (жёстко): читай `CLAUDE.md`(паспорт)/`AGENTS.md`/`docs/ARCHITECTURE.md`/ADR
|
||||
ПЕРЕД работой; пиши артефакты в `docs/work-items/<id>/` по `docs/_standards/PIPELINE_DOCS.md`
|
||||
(скелеты из `docs/_templates/`); архитектор фиксирует решения в `06-adr/` + сквозные в
|
||||
`docs/architecture/adr/adr-NNNN-slug.md`; каждый обновляет `CHANGELOG.md`/релевантную доку.
|
||||
- **Reviewer:** содержит gate «документация обновлена? нет → `verdict: REQUEST_CHANGES`».
|
||||
- Эмиссия 6-польной frontmatter-схемы 52c (`work_item`/`stage`/`author_agent`/`status`/
|
||||
`created_at`/`model_used`) — аддитивно; machine-verdict ключи и значения байт-в-байт
|
||||
(`verdict:`/`result:`/`staging_status:`/`deploy_status:`/`security_status:`); копируемые
|
||||
примеры — с плейсхолдерами `<YYYY-MM-DD>`/`<resolve по конфигу>` (анти-паттерн ORCH-092 учтён).
|
||||
- Стек-специфика (язык/тесты/команды) — только через плейсхолдеры; никаких унаследованных
|
||||
орк-литералов (порты 8500/8501, «ORCH-», self-hosting-правила орка) в материализованном виде.
|
||||
- Языковая политика: по канону орка (5 ru + deployer en, нормативно ADR-001 D2 ORCH-092);
|
||||
отступление — только решением архитектора в ADR.
|
||||
|
||||
### FR-3 — INFRA.md шаблон: обязательные секции (BR-6)
|
||||
Шаблон `docs/operations/INFRA.md` нового проекта содержит секции: топология (контейнеры, порты
|
||||
прод/staging, сеть, тома, БД); карта env-переменных (дескрипторы в репо; секреты ТОЛЬКО в `.env`
|
||||
на хосте; `.env.example` — канон; `docker-compose.yml`/`Dockerfile` трекаются в гите); границы
|
||||
доступа; эксплуатационные предупреждения, включая **риски общего хоста** (соседние контейнеры,
|
||||
общие ресурсы; факт: хост впритык — см. `docs/epics/self-evolution.md` С-3). Существующий
|
||||
`docs/operations/INFRA.md` орка с self-hosting-предупреждениями (общая БД/очередь/групповой риск
|
||||
рестарта) — не модифицируется этой задачей (read-only образец).
|
||||
|
||||
### FR-4 — Onboarding-скрипт: провижининг (BR-1/BR-7/BR-9/BR-11)
|
||||
`scripts/onboard_project.py` (вход: имя проекта, repo, префикс work-item, параметры стека):
|
||||
- **Gitea:** создать репо (API), создать per-repo webhook (`push`/`pull_request`/`status`,
|
||||
HMAC-secret из/для `.env` — формат `SETUP_WEBHOOKS.md`); материализовать kit → **initial push
|
||||
в свежесозданный пустой репо** (единственный разрешённый push; в существующие репо — никогда).
|
||||
- **Plane:** создать проект (или принять существующий `--plane-project-id`); создать статусы со
|
||||
**точными** именами из `_PLANE_NAME_TO_KEY` (22 имени; `STOP` — группа `cancelled`,
|
||||
`Confirm Deploy` — отдельный статус; группы фиксирует архитектор по `plane_sync`) и лейблы
|
||||
`autoApprove`/`autoDeploy`/`Bug`. Недоступное через API CE → пункт отчёта «ручной шаг» со
|
||||
ссылкой на runbook (fail-safe, не падение).
|
||||
- **Реестр:** сгенерировать запись `ORCH_PROJECTS_JSON` (полный новый массив или диф —
|
||||
фиксирует архитектор), **валидную через фактический `projects._parse_projects_json`**;
|
||||
вывести оператору инструкцию «добавь в `.env` + управляемый рестарт». Скрипт сам `.env` прода
|
||||
не правит и контейнер не рестартит (NFR-2).
|
||||
- **Режимы:** `plan` (дефолт; полный план без единой мутации), `apply` (исполнение),
|
||||
`verify` (см. FR-5). Идемпотентность: повторный `apply` обнаруживает существующее
|
||||
(репо/webhook/статусы/лейблы/файлы) и пропускает с пометкой; ничего не удаляет и не
|
||||
перезаписывает существующий контент без явного флага.
|
||||
- **Прозрачность:** лог каждого шага + итоговый отчёт: `created / skipped(exists) / manual-step`.
|
||||
- **Webhook Plane:** не создаётся (workspace-level уже существует, Ф-6) — только проверка в verify.
|
||||
|
||||
### FR-5 — Верификация (BR-10)
|
||||
- `verify`-режим скрипта: запись реестра парсится (`_parse_projects_json` round-trip → поля
|
||||
совпадают); статусы проекта резолвятся (все логические ключи, включая `confirm_deploy`/`stop`);
|
||||
лейблы присутствуют; Gitea-webhook существует и активен; kit-файлы в репо (включая 6 промптов,
|
||||
AGENTS.md, INFRA.md, `_templates`/`_standards`); нет неразрешённых плейсхолдеров.
|
||||
- **Smoke на песочнице** (runbook, операторский): онбордить sandbox-проект → создать тестовую
|
||||
задачу → стадия analysis в песочнице → убедиться: агент прочитал доку проекта (следы в
|
||||
выводе/артефактах) и записал артефакты в `docs/work-items/<id>/` по канону. Контур песочницы
|
||||
(staging 8501 / одноразовый sandbox) фиксирует архитектор в ADR + runbook.
|
||||
|
||||
### FR-6 — Runbook ONBOARDING.md (BR-1/BR-8)
|
||||
Полный чеклист онбординга: предусловия (токены, доступы) → шаги скрипта → **операторские шаги**
|
||||
(env+рестарт — с предупреждением self-hosting: рестарт прода = групповое окно, выполнять
|
||||
осознанно; UI-only шаги Plane, напр. drag-and-drop порядок статусов) → верификация (verify +
|
||||
smoke) → откат (удаление созданного — вручную, скрипт не удаляет). Каждый ручной шаг — с командой
|
||||
проверки результата.
|
||||
|
||||
---
|
||||
|
||||
## 4. Изменения API
|
||||
**Нет.** Новые/изменённые HTTP-эндпоинты оркестратора не вводятся; вебхук-контракты не меняются.
|
||||
(Onboarding-CLI — операторский инструмент вне FastAPI-приложения.)
|
||||
|
||||
## 5. Изменения схемы БД
|
||||
**Нет.** Общая БД не читается и не пишется скриптом (NFR-2).
|
||||
|
||||
## 6. Требования к новым/изменённым QG checks
|
||||
**Нет.** Реестр `QG_CHECKS`/`check_*`/`STAGE_TRANSITIONS` — байт-в-байт (контроль — снапшот-тест,
|
||||
TC-18). Онбординг — операторская способность, не гейт конвейера.
|
||||
|
||||
---
|
||||
|
||||
## 7. Совместимость / регресс
|
||||
- **Нулевая регрессия кода:** `src/**` не меняется → поведение конвейера для enduro/orchestrator
|
||||
идентично; полный регресс `tests/` остаётся зелёным.
|
||||
- **Kill-switch не требуется:** способность активируется только явным запуском операторского CLI;
|
||||
в горячих путях конвейера нового кода нет.
|
||||
- **Обратимость:** удаление `onboarding/`/`scripts/onboard_project.py`/runbook возвращает репо в
|
||||
исходное состояние; созданные онбордингом внешние сущности сносятся вручную по разделу
|
||||
«Откат» runbook.
|
||||
- **Совместимость канонов:** kit-промпты проходят те же структурные требования, что эталонные
|
||||
(анти-дрейф NFR-4); обновление канона орка автоматически подхватывается live-copy частью kit
|
||||
(BR-2), шаблонные дельты — через обычные PR с reviewer-gate.
|
||||
|
||||
---
|
||||
|
||||
## 8. Артефакты pipeline (создать/обновить в ТОМ ЖЕ PR)
|
||||
- `docs/work-items/ORCH-009/06-adr/ADR-001-…` — решения архитектора (раскладка kit, синтаксис
|
||||
плейсхолдеров, copy-vs-template split по файлам, импорт `src` из скрипта vs снапшот, контур
|
||||
песочницы, языковая политика kit-deployer).
|
||||
- `docs/architecture/README.md` — раздел «Онбординг проектов (ORCH-009)».
|
||||
- `CLAUDE.md` — краткий абзац о способности онбординга.
|
||||
- `CHANGELOG.md` — запись `feat:`.
|
||||
- `docs/operations/ONBOARDING.md` (новый), `docs/operations/SETUP_WEBHOOKS.md` (обобщение).
|
||||
- `07-infra-requirements.md` — предусловия онбординга (токены/доступы), заполняет архитектор.
|
||||
|
||||
---
|
||||
|
||||
## 9. Инварианты (не нарушать)
|
||||
- `src/**` без изменений; `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict ключи/схема
|
||||
БД — байт-в-байт (NFR-1).
|
||||
- Скрипт: не рестартит/не останавливает прод-контейнер; не пушит в `main` существующих репо
|
||||
(INV-4 — мерж только через PR-merge API — не затрагивается: initial push идёт в свежесозданный
|
||||
пустой репо, не являющийся участником конвейера до регистрации); не удаляет внешние сущности;
|
||||
секреты в гит не попадают (NFR-2/NFR-3).
|
||||
- Никаких сетевых вызовов в тестах (NFR-5); никаких новых обязательных pip-зависимостей без
|
||||
обоснования в ADR.
|
||||
- Эталонные промпты орка `.openclaw/agents/*.md` этой задачей не модифицируются (они — read-only
|
||||
образец; их правка = отдельные задачи канона).
|
||||
|
||||
---
|
||||
|
||||
## 10. Открытые вопросы для архитектора (не блокируют анализ)
|
||||
- OQ-1: Раскладка kit — `onboarding/repo-skeleton/` (предложение) vs `docs/_onboarding/` vs
|
||||
`scripts/onboarding/`; где словарь плейсхолдеров.
|
||||
- OQ-2: Механизм подстановки — stdlib (`str.replace`/`string.Template`) без новых зависимостей
|
||||
(рекомендация) vs шаблонизатор (новая зависимость — потребует обоснования).
|
||||
- OQ-3: Copy-vs-template split: какие файлы kit — live-copy канона, какие — параметризуемые
|
||||
шаблоны (минимум по BR-2: `_templates`/`_standards` — live-copy).
|
||||
- OQ-4: Скрипту импортировать `src.projects`/`src.plane_sync` (точные имена/парсер, нет
|
||||
дублирования) vs автономный снапшот констант с тестом синхронизации.
|
||||
- OQ-5: Plane API CE: фактическая доступность создания проекта/статусов/лейблов — что уходит в
|
||||
ручные шаги runbook.
|
||||
- OQ-6: Контур песочницы для smoke (staging 8501 vs одноразовый sandbox-проект) и судьба
|
||||
sandbox-артефактов после прогона.
|
||||
- OQ-7: Языковая политика kit-промптов для не-self-hosting проектов (рекомендация: канон орка,
|
||||
deployer — en).
|
||||
- OQ-8: Защита `main` нового репо в Gitea (branch protection): не должна ломать PR-merge API
|
||||
конвейера — включать ли вообще (рекомендация: не включать, зафиксировать в runbook).
|
||||
@@ -1,146 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-009
|
||||
stage: analysis
|
||||
author_agent: analyst
|
||||
status: ready-for-review
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# 03 — Критерии приёмки (Acceptance Criteria): ORCH-009 — Turnkey-онбординг проектов
|
||||
|
||||
Work Item: **ORCH-009** · Repo: **orchestrator** · Стадия: analysis
|
||||
|
||||
Формат: каждый критерий — чёткое условие **PASS/FAIL**, проверяемое буквально по файлам
|
||||
репозитория и детерминированным тестам (без сети). AC-13 — единственный операторский
|
||||
(документированный smoke), его автоматизируемая часть вынесена в AC-2/AC-12.
|
||||
|
||||
---
|
||||
|
||||
## AC-1 — Kit полон (состав каркаса)
|
||||
**Условие:** инспекция `onboarding/repo-skeleton/` (или каталога, выбранного архитектором в ADR).
|
||||
- **PASS:** присутствуют все элементы FR-1: 6 шаблонов промптов (`analyst/architect/developer/
|
||||
reviewer/tester/deployer`), `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, `README.md`,
|
||||
`CHANGELOG.md`, `docs/ARCHITECTURE.md`, `docs/PIPELINE.md`, `docs/PRODUCT_VISION.md`,
|
||||
`docs/operations/INFRA.md`, `docs/architecture/adr/`, `docs/work-items/`, `docs/history/`,
|
||||
`.env.example`; материализация добавляет live-копии `docs/_templates/` + `docs/_standards/`.
|
||||
- **FAIL:** отсутствует любой элемент состава, либо промптов меньше 6.
|
||||
|
||||
## AC-2 — Промпты kit соответствуют канону 52d/92
|
||||
**Условие:** структурные тесты по каждому из 6 шаблонов промптов.
|
||||
- **PASS:** в каждом — 5 обязательных XML-секций в нормативном порядке `<context>→<task>→
|
||||
<deliverables>→<constraints>→<output_format>`; запреты в формате «❌ → ✅»; `<escalation>` у
|
||||
developer/reviewer/tester; директивы «читай паспорт/AGENTS.md/доку ПЕРЕД работой» и «пиши
|
||||
артефакты в `docs/work-items/<id>/`»; эмиссия 6-польной frontmatter-схемы 52c с
|
||||
плейсхолдерными примерами дат/моделей; machine-verdict ключи у ролей-вердиктов байт-в-байт
|
||||
(`verdict:` / `result:` / `staging_status:` / `deploy_status:` / `security_status:`).
|
||||
- **FAIL:** нарушен порядок/состав секций, отсутствует любой verdict-ключ или директива доки,
|
||||
пример frontmatter содержит захардкоженные дату/модель.
|
||||
|
||||
## AC-3 — Reviewer-gate на обновление доки
|
||||
**Условие:** шаблон `reviewer.md` в kit.
|
||||
- **PASS:** содержит явное правило: документация (CHANGELOG/релевантные доки/ADR) обновлена в том
|
||||
же PR; нет → `verdict: REQUEST_CHANGES`.
|
||||
- **FAIL:** правило отсутствует или сформулировано как необязательное.
|
||||
|
||||
## AC-4 — Языковая политика kit
|
||||
**Условие:** проверка языка шаблонов промптов против решения ADR (дефолт — канон орка).
|
||||
- **PASS:** языковая раскладка соответствует зафиксированной в ADR (по умолчанию: 5 ru +
|
||||
deployer en, как ADR-001 D2 ORCH-092); отступление — только с обоснованием в ADR.
|
||||
- **FAIL:** язык промптов противоречит ADR, либо политика нигде не зафиксирована.
|
||||
|
||||
## AC-5 — Материализация: плейсхолдеры и отсутствие утечек
|
||||
**Условие:** рендер kit с тестовыми параметрами (`PROJECT_NAME`, `REPO`, `WORK_ITEM_PREFIX` и т.д.).
|
||||
- **PASS:** все плейсхолдеры подставлены; в результате нет ни одного неразрешённого плейсхолдера
|
||||
(grep по синтаксису из ADR); нет утечек орк-специфики, где должен быть параметр (литералы
|
||||
`ORCH-` как префикс work-item чужого проекта, порты 8500/8501, self-hosting-правила орка);
|
||||
пути, на которые ссылаются отрендеренные промпты/AGENTS.md, существуют в каркасе.
|
||||
- **FAIL:** найден неразрешённый плейсхолдер, орк-литерал вместо параметра или битая ссылка
|
||||
на несуществующий путь.
|
||||
|
||||
## AC-6 — Registry round-trip через фактический парсер
|
||||
**Условие:** скрипт генерирует запись реестра для тестового проекта.
|
||||
- **PASS:** сгенерированный JSON парсится `projects._parse_projects_json` без ошибок; полученный
|
||||
`ProjectConfig` несёт исходные `plane_project_id`/`repo`/`work_item_prefix`/`name`; существующие
|
||||
записи реестра не модифицируются и не теряются.
|
||||
- **FAIL:** парсер отвергает запись, поля искажены, либо генерация ломает/теряет существующие записи.
|
||||
|
||||
## AC-7 — План Plane: точные статусы и лейблы
|
||||
**Условие:** `plan`-режим для нового проекта (моки сети).
|
||||
- **PASS:** план провижининга содержит ВСЕ канонические имена статусов из `_PLANE_NAME_TO_KEY`
|
||||
(включая `Confirm Deploy` и `STOP` с группой `cancelled`) и лейблы `autoApprove`/`autoDeploy`/
|
||||
`Bug`; имена байт-в-байт совпадают с константами `src/plane_sync.py` (или их синхронизированным
|
||||
снапшотом по OQ-4); недоступные через API шаги помечены `manual-step` со ссылкой на runbook.
|
||||
- **FAIL:** пропущен/искажён любой статус или лейбл; недоступный шаг молча отброшен.
|
||||
|
||||
## AC-8 — План Gitea: репо + per-repo webhook; dry-run без мутаций
|
||||
**Условие:** `plan`-режим (моки сети).
|
||||
- **PASS:** план содержит создание репо, создание webhook с events `push`/`pull_request`/`status`
|
||||
и HMAC-secret (секрет — для `.env` оператора, не в гит), материализацию kit + initial push в
|
||||
свежесозданный репо; в режиме `plan` не выполняется НИ ОДНОЙ мутации (ни одного
|
||||
POST/PUT/DELETE-вызова в моках, ни одной записи на диск вне отчёта).
|
||||
- **FAIL:** план неполон, или dry-run произвёл мутацию.
|
||||
|
||||
## AC-9 — Идемпотентность и безопасность apply
|
||||
**Условие:** повторный `apply` на частично/полностью созданном проекте (моки: сущности существуют).
|
||||
- **PASS:** существующие сущности (репо/webhook/статусы/лейблы/файлы) распознаны и пропущены с
|
||||
пометкой `skipped(exists)`; ничего не удалено и не перезаписано без явного флага; скрипт не
|
||||
выполняет рестарт/останов контейнеров, не правит `.env` прода, не пушит в существующие репо
|
||||
(в коде отсутствуют такие операции — проверяемо тестом/ревью); итоговый отчёт перечисляет
|
||||
created/skipped/manual-step.
|
||||
- **FAIL:** дублирование сущностей, любое удаление/перезапись без флага, любая операция
|
||||
рестарта/push в существующий репо, отсутствие отчёта.
|
||||
|
||||
## AC-10 — INFRA.md шаблон: обязательные секции
|
||||
**Условие:** инспекция шаблона `docs/operations/INFRA.md` в kit.
|
||||
- **PASS:** присутствуют секции: топология (контейнеры/порты прод+staging/сеть/тома/БД);
|
||||
карта env-переменных + правило секретов (только `.env` на хосте, `.env.example` — канон);
|
||||
границы доступа; предупреждения о рисках общего хоста. Существующий `docs/operations/INFRA.md`
|
||||
орка (self-hosting-предупреждения) этой задачей не изменён.
|
||||
- **FAIL:** отсутствует любая обязательная секция, либо изменён INFRA.md самого орка.
|
||||
|
||||
## AC-11 — Runbook ONBOARDING.md полон
|
||||
**Условие:** инспекция `docs/operations/ONBOARDING.md`.
|
||||
- **PASS:** покрывает все слои BR-1 в последовательности: предусловия (токены/доступы) → Plane
|
||||
(проект/статусы/лейблы) → Gitea (репо/webhook) → kit (материализация/push) → регистрация
|
||||
(env-строка + операторский управляемый рестарт с self-hosting-предупреждением) → верификация
|
||||
(`verify` + smoke на песочнице) → откат; каждый ручной шаг помечен и снабжён командой проверки;
|
||||
Plane workspace-webhook описан как существующий (проверка, не создание).
|
||||
- **FAIL:** пропущен слой, ручной шаг не помечен/без проверки, или runbook требует
|
||||
автоматического рестарта прода.
|
||||
|
||||
## AC-12 — Инварианты: src/** не тронут
|
||||
**Условие:** diff PR + снапшот-тест.
|
||||
- **PASS:** `git diff` PR не содержит изменений `src/**`; снапшот `STAGE_TRANSITIONS` и реестра
|
||||
`QG_CHECKS` совпадает с эталоном; эталонные промпты `.openclaw/agents/*.md` орка не изменены;
|
||||
полный регресс `tests/` зелёный.
|
||||
- **FAIL:** любой diff в `src/**` или `.openclaw/agents/`, расхождение снапшота, красный регресс.
|
||||
|
||||
## AC-13 — Smoke: агент находит, использует и актуализирует доку (операторский)
|
||||
**Условие:** документированный прогон по runbook на песочнице (контур — по ADR): онбординг
|
||||
sandbox-проекта → тестовая задача → стадия analysis.
|
||||
- **PASS:** агент песочницы по своему промпту прочитал доку проекта (следы чтения паспорта/
|
||||
AGENTS.md в выводе или артефактах) и записал артефакты в `docs/work-items/<id>/` по канону
|
||||
(структура соответствует `PIPELINE_DOCS.md`); результат прогона зафиксирован в runbook/отчёте
|
||||
задачи. Для приёмки данной задачи прогон выполняется один раз и протоколируется.
|
||||
- **FAIL:** агент не нашёл доку (артефакты вне канона/не созданы), либо прогон не запротоколирован.
|
||||
|
||||
---
|
||||
|
||||
## Сводная матрица AC ↔ BR/FR
|
||||
|
||||
| AC | BR | FR | Тип проверки |
|
||||
|----|----|----|--------------|
|
||||
| AC-1 | BR-5 | FR-1 | unit (структура kit) |
|
||||
| AC-2 | BR-3 | FR-2 | unit (структурный канон) |
|
||||
| AC-3 | BR-4 | FR-2 | unit |
|
||||
| AC-4 | BR-3 | FR-2 | unit + ADR |
|
||||
| AC-5 | BR-2/BR-5 | FR-1/FR-2 | unit (рендер) |
|
||||
| AC-6 | BR-8 | FR-4 | integration (реальный парсер) |
|
||||
| AC-7 | BR-7 | FR-4 | unit (план, моки) |
|
||||
| AC-8 | BR-1/BR-9 | FR-4 | unit (план, моки) |
|
||||
| AC-9 | BR-9/BR-11 | FR-4 | unit/integration (моки) |
|
||||
| AC-10 | BR-6 | FR-3 | unit (структура) |
|
||||
| AC-11 | BR-1/BR-8 | FR-6 | unit (структура дока) |
|
||||
| AC-12 | NFR-1 | — | unit (снапшот) + ревью diff |
|
||||
| AC-13 | BR-10 | FR-5 | ручной smoke (протоколируемый) |
|
||||
@@ -1,164 +0,0 @@
|
||||
work_item: ORCH-009
|
||||
stage: analysis
|
||||
author_agent: analyst
|
||||
status: ready-for-review
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
title: "Turnkey-онбординг проектов: kit + скрипт + runbook (ORCH-009)"
|
||||
framework: pytest
|
||||
scope: >
|
||||
Структурная полнота onboarding-kit, канон 52d/92 шаблонов промптов, материализация
|
||||
(плейсхолдеры/утечки), registry round-trip через фактический парсер projects.py,
|
||||
планы Plane/Gitea (dry-run, моки), идемпотентность apply, runbook, инварианты src/**.
|
||||
Вне покрытия pytest: реальные вызовы Plane/Gitea API и операторский smoke на песочнице
|
||||
(AC-13) — выполняется вручную по docs/operations/ONBOARDING.md и протоколируется.
|
||||
notes: >
|
||||
Все тесты детерминированы, без сети (Plane/Gitea мокируются; NFR-5). Точные имена файлов
|
||||
тест-модулей могут уточняться архитектором при сохранении покрытия TC↔AC. Полный регресс
|
||||
tests/ должен оставаться зелёным (src/** не меняется — NFR-1). Если ADR изменит раскладку
|
||||
kit (OQ-1) — пути в тестах следуют ADR, маппинг TC↔AC неизменен.
|
||||
|
||||
tests:
|
||||
# ---------- AC-1: состав kit ----------
|
||||
- id: TC-01
|
||||
type: unit
|
||||
description: "Kit содержит все элементы FR-1: 6 шаблонов промптов, CLAUDE.md, AGENTS.md, CONTRIBUTING.md, README.md, CHANGELOG.md, docs/ARCHITECTURE.md, docs/PIPELINE.md, docs/PRODUCT_VISION.md, docs/operations/INFRA.md, docs/architecture/adr/, docs/work-items/, docs/history/, .env.example"
|
||||
module: tests/test_onboarding_kit.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-02
|
||||
type: unit
|
||||
description: "Материализация добавляет live-копии docs/_templates/ (16 канонических скелетов) и docs/_standards/ (3 стандарта) из живого канона репо орка; вторая редактируемая копия канона в kit отсутствует (BR-2)"
|
||||
module: tests/test_onboarding_script.py
|
||||
expected: PASS
|
||||
|
||||
# ---------- AC-2: канон промптов 52d/92 ----------
|
||||
- id: TC-03
|
||||
type: unit
|
||||
description: "Каждый из 6 шаблонов промптов содержит 5 обязательных XML-секций в нормативном порядке context→task→deliverables→constraints→output_format"
|
||||
module: tests/test_onboarding_kit.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-04
|
||||
type: unit
|
||||
description: "Шаблоны developer/reviewer/tester содержат секцию <escalation>; запреты оформлены в формате '❌ → ✅'"
|
||||
module: tests/test_onboarding_kit.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-05
|
||||
type: unit
|
||||
description: "Каждый шаблон промпта направляет агента к доке: читай паспорт(CLAUDE.md)/AGENTS.md/ARCHITECTURE/ADR перед работой; пиши артефакты в docs/work-items/<id>/ по PIPELINE_DOCS; обновляй CHANGELOG/доку"
|
||||
module: tests/test_onboarding_kit.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-06
|
||||
type: unit
|
||||
description: "Шаблоны эмитят 6-польную frontmatter-схему 52c (work_item/stage/author_agent/status/created_at/model_used); machine-verdict ключи ролей байт-в-байт (verdict:/result:/staging_status:/deploy_status:/security_status:); примеры дат/моделей — плейсхолдеры, не литералы (анти-паттерн ORCH-092)"
|
||||
module: tests/test_onboarding_kit.py
|
||||
expected: PASS
|
||||
|
||||
# ---------- AC-3: reviewer-gate ----------
|
||||
- id: TC-07
|
||||
type: unit
|
||||
description: "Шаблон reviewer.md содержит обязательный gate: документация не обновлена в PR → verdict: REQUEST_CHANGES"
|
||||
module: tests/test_onboarding_kit.py
|
||||
expected: PASS
|
||||
|
||||
# ---------- AC-4: языковая политика ----------
|
||||
- id: TC-08
|
||||
type: unit
|
||||
description: "Языковая раскладка шаблонов соответствует политике ADR (дефолт: 5 ru + deployer en, канон ADR-001 D2 ORCH-092)"
|
||||
module: tests/test_onboarding_kit.py
|
||||
expected: PASS
|
||||
|
||||
# ---------- AC-5: материализация ----------
|
||||
- id: TC-09
|
||||
type: unit
|
||||
description: "Рендер kit с тестовыми параметрами подставляет все плейсхолдеры: в выходе нет ни одного неразрешённого плейсхолдера (grep по синтаксису из ADR)"
|
||||
module: tests/test_onboarding_script.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-10
|
||||
type: unit
|
||||
description: "В отрендеренном kit нет утечек орк-специфики, где должен быть параметр: префикс ORCH- вместо префикса проекта, порты 8500/8501, self-hosting-правила орка"
|
||||
module: tests/test_onboarding_script.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-11
|
||||
type: unit
|
||||
description: "Ссылочная целостность: каждый путь, на который ссылаются отрендеренные промпты и AGENTS.md, существует в материализованном каркасе"
|
||||
module: tests/test_onboarding_script.py
|
||||
expected: PASS
|
||||
|
||||
# ---------- AC-6: registry round-trip ----------
|
||||
- id: TC-12
|
||||
type: integration
|
||||
description: "Сгенерированная скриптом запись реестра парсится фактическим projects._parse_projects_json; ProjectConfig несёт исходные plane_project_id/repo/work_item_prefix/name; существующие записи реестра сохранены без искажений"
|
||||
module: tests/test_onboarding_script.py
|
||||
expected: PASS
|
||||
|
||||
# ---------- AC-7: план Plane ----------
|
||||
- id: TC-13
|
||||
type: unit
|
||||
description: "plan-режим: план Plane содержит все канонические имена статусов _PLANE_NAME_TO_KEY (включая 'Confirm Deploy' и 'STOP' с группой cancelled) байт-в-байт и лейблы autoApprove/autoDeploy/Bug"
|
||||
module: tests/test_onboarding_script.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-14
|
||||
type: unit
|
||||
description: "Шаг Plane, недоступный через API (мок отвечает отказом/не реализовано), помечается в плане/отчёте как manual-step со ссылкой на runbook — не отбрасывается молча и не валит скрипт"
|
||||
module: tests/test_onboarding_script.py
|
||||
expected: PASS
|
||||
|
||||
# ---------- AC-8: план Gitea + dry-run ----------
|
||||
- id: TC-15
|
||||
type: unit
|
||||
description: "plan-режим: план Gitea содержит создание репо, webhook (events push/pull_request/status + HMAC-secret вне гита) и initial push kit в свежесозданный репо"
|
||||
module: tests/test_onboarding_script.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-16
|
||||
type: unit
|
||||
description: "dry-run (plan) не выполняет ни одной мутации: ноль POST/PUT/DELETE в замоканных клиентах Plane/Gitea, ноль git push, ноль записей на диск вне отчёта"
|
||||
module: tests/test_onboarding_script.py
|
||||
expected: PASS
|
||||
|
||||
# ---------- AC-9: идемпотентность / безопасность apply ----------
|
||||
- id: TC-17
|
||||
type: integration
|
||||
description: "Повторный apply на уже созданном проекте (моки: репо/webhook/статусы/лейблы существуют): сущности распознаны и помечены skipped(exists); нет дублей, удалений и перезаписи без явного флага; итоговый отчёт перечисляет created/skipped/manual-step"
|
||||
module: tests/test_onboarding_script.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-18
|
||||
type: unit
|
||||
description: "Скрипт не содержит операций рестарта/останова контейнеров, правки прод-.env и push в существующие репо: на моках полного прогона apply такие вызовы отсутствуют (NFR-2)"
|
||||
module: tests/test_onboarding_script.py
|
||||
expected: PASS
|
||||
|
||||
# ---------- AC-10: INFRA.md шаблон ----------
|
||||
- id: TC-19
|
||||
type: unit
|
||||
description: "Шаблон INFRA.md kit содержит обязательные секции: топология (контейнеры/порты прод+staging/сеть/тома/БД), карта env + правило секретов (.env на хосте, .env.example — канон), границы доступа, риски общего хоста"
|
||||
module: tests/test_onboarding_kit.py
|
||||
expected: PASS
|
||||
|
||||
# ---------- AC-11: runbook ----------
|
||||
- id: TC-20
|
||||
type: unit
|
||||
description: "ONBOARDING.md покрывает все слои в последовательности: предусловия → Plane → Gitea → kit → регистрация (env + операторский управляемый рестарт с self-hosting-предупреждением) → верификация (verify + smoke) → откат; ручные шаги помечены и снабжены командами проверки"
|
||||
module: tests/test_onboarding_kit.py
|
||||
expected: PASS
|
||||
|
||||
# ---------- AC-12: инварианты ----------
|
||||
- id: TC-21
|
||||
type: unit
|
||||
description: "Снапшот STAGE_TRANSITIONS и реестра QG_CHECKS совпадает с эталоном (src/** не затронут логикой онбординга); эталонные промпты .openclaw/agents/ орка не изменены задачей"
|
||||
module: tests/test_onboarding_invariants.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-22
|
||||
type: integration
|
||||
description: "Полный регресс существующего tests/ остаётся зелёным после добавления onboarding-артефактов (никакой новый импорт/код не ломает конвейер)"
|
||||
module: tests/
|
||||
expected: PASS
|
||||
@@ -1,341 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-009
|
||||
stage: architecture
|
||||
author_agent: architect
|
||||
status: proposed
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# ADR-001: Turnkey-онбординг проектов — kit `onboarding/` + операторский CLI + runbook
|
||||
|
||||
Work Item: **ORCH-009** — Онбординг проектов в оркестратор (turnkey: Plane + репо + агенты + инфра)
|
||||
Стадия: **architecture**
|
||||
Связь: BRD `01-brd.md`, ТЗ `02-trz.md`, AC `03-acceptance-criteria.md`, тест-план `04-test-plan.yaml`,
|
||||
инфра `07-infra-requirements.md`, риски `10-tech-risks.md`.
|
||||
Сквозная регистрация: **`docs/architecture/adr/adr-0035-turnkey-project-onboarding.md`**
|
||||
(решение кросс-каттинговое: новая способность уровня всего оркестратора — масштабирование на
|
||||
новые проекты, домен D5.2 эпика саморазвития).
|
||||
|
||||
## Статус
|
||||
Proposed
|
||||
|
||||
---
|
||||
|
||||
## Контекст
|
||||
|
||||
Онбординг нового проекта сегодня — ручная археология по `SETUP_WEBHOOKS.md`/`INFRA.md`/памяти;
|
||||
любой пропуск даёт тихую деградацию (BRD §1.2): без промптов в репо конвейер проекта не работает
|
||||
вовсе (Ф-1: launcher резолвит `.openclaw/agents/<role>.md` **относительно worktree репо задачи**);
|
||||
без точных имён статусов ветки `Confirm Deploy`/`STOP` молча не активируются (fail-closed,
|
||||
`src/plane_sync.py:130-165`); без лейблов авто-режимы/багфикс-трек молча выключены (fail-safe,
|
||||
`src/labels.py`/`src/bug_fast_track.py`).
|
||||
|
||||
Ограничения, заданные анализом и проверенные по коду:
|
||||
|
||||
- **NFR-1:** `src/**` не меняется; `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict
|
||||
ключи/схема БД/контракт `projects.py` — байт-в-байт. Задача docs/templates/scripts/tests-only.
|
||||
- **Ф-2:** агент видит только worktree своего репо → каноны обязаны быть **скопированы** в новый
|
||||
репо (ссылка на репо орка агенту недоступна).
|
||||
- **Ф-3:** реестр строится при импорте из `ORCH_PROJECTS_JSON` (`src/projects.py::_load_projects`);
|
||||
регистрация = правка `.env` + **операторский** управляемый рестарт.
|
||||
- **Ф-6:** Plane-webhook — workspace-level, уже существует (в CE создаётся SQL-ом, внешнего API
|
||||
нет); Gitea-webhook — per-repo, через API (`push`/`pull_request`/`status`, HMAC).
|
||||
- **Ф-7:** живой канон — `docs/_templates/` (16 скелетов), `docs/_standards/` (3 стандарта),
|
||||
`.openclaw/agents/*.md` (канон 52d/92).
|
||||
- Эталон онбординга = **сам репозиторий orchestrator** (актуализация Владельца 10.06);
|
||||
enduro-trails эталоном не является.
|
||||
|
||||
ТЗ оставило архитектору 8 открытых вопросов (OQ-1…OQ-8) — все закрываются ниже (D1…D11).
|
||||
|
||||
---
|
||||
|
||||
## Решение
|
||||
|
||||
### Сводка
|
||||
|
||||
Три артефакта + тесты, всё **вне конвейера и вне рантайма**:
|
||||
|
||||
1. **Onboarding-kit** `onboarding/repo-skeleton/` — параметризуемый каркас нового репо
|
||||
(6 промптов канона 52d/92, паспорт `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, скелет `docs/`
|
||||
с обязательным `operations/INFRA.md`); словарь плейсхолдеров — `onboarding/placeholders.json`.
|
||||
2. **Операторский CLI** `scripts/onboard_project.py` — `plan` (дефолт, GET-only) / `apply`
|
||||
(идемпотентный ensure) / `verify`; Plane (проект+статусы+лейблы) → Gitea (репо+webhook) →
|
||||
материализация kit (рендер + live-copy канона) + initial push → генерация записи реестра →
|
||||
отчёт `created/skipped(exists)/manual-step`.
|
||||
3. **Runbook** `docs/operations/ONBOARDING.md` — полный чеклист, явные ручные шаги
|
||||
(env + управляемый рестарт; UI-only Plane), верификация (verify + smoke на staging), откат.
|
||||
|
||||
Никакого нового кода в горячих путях; kill-switch не нужен (способность активируется только
|
||||
явным запуском CLI человеком — TRZ §7).
|
||||
|
||||
### D1 — Раскладка: top-level `onboarding/` (OQ-1)
|
||||
|
||||
**Решение: `onboarding/` в корне репо** — ровно как предложено ТЗ:
|
||||
|
||||
```
|
||||
onboarding/
|
||||
README.md ← устройство kit: словарь плейсхолдеров, правило «канон не форкается»,
|
||||
copy-vs-template карта (D3), как запускать тесты kit
|
||||
placeholders.json ← словарь плейсхолдеров (single source of truth, D2)
|
||||
repo-skeleton/ ← дерево зеркалит целевой репо (FR-1)
|
||||
.openclaw/agents/{analyst,architect,developer,reviewer,tester,deployer}.md
|
||||
CLAUDE.md AGENTS.md CONTRIBUTING.md README.md CHANGELOG.md .env.example
|
||||
docs/ARCHITECTURE.md docs/PIPELINE.md docs/PRODUCT_VISION.md
|
||||
docs/operations/INFRA.md
|
||||
docs/architecture/adr/README.md ← стаб реестра сквозных ADR (дир непустая, самоописуема)
|
||||
docs/work-items/.gitkeep docs/history/.gitkeep
|
||||
```
|
||||
|
||||
Отвергнуто:
|
||||
- **`docs/_onboarding/`** — смешивает kit (продукт-артефакт, исходник для ЧУЖИХ репо) с
|
||||
документацией самого орка; шаблоны промптов под `docs/` рядом с живыми `docs/_templates/`
|
||||
провоцируют путаницу «какая копия живая» (прямо риск R-1/R-5 BRD) и ложные срабатывания
|
||||
doc-тулинга.
|
||||
- **`scripts/onboarding/`** — смешивает данные (дерево skeleton) с исполняемым кодом; `scripts/`
|
||||
в этом репо — плоские утилиты (`staging_check.py`, deploy-hook).
|
||||
|
||||
Top-level каталог делает границу физической: **всё под `onboarding/` предназначено новому репо,
|
||||
ничто под `onboarding/` не исполняется рантаймом орка.** Структурные тесты канона гоняются по
|
||||
`onboarding/repo-skeleton/.openclaw/agents/*.md` отдельно от живых промптов орка (TC-03…08 ↔
|
||||
существующий `tests/test_agent_prompts_canon.py` не пересекаются).
|
||||
|
||||
### D2 — Механизм подстановки: `{{NAME}}` + stdlib, без новых зависимостей (OQ-2)
|
||||
|
||||
**Решение: синтаксис `{{PLACEHOLDER_NAME}}`** (верхний регистр, `[A-Z][A-Z0-9_]*`), подстановка —
|
||||
простой проход `str.replace` по словарю; после рендера — обязательный скан
|
||||
`re.compile(r"\{\{[A-Z][A-Z0-9_]*\}\}")` на неразрешённые плейсхолдеры (ошибка в apply/verify,
|
||||
PASS-условие AC-5/TC-09).
|
||||
|
||||
- **`string.Template` отвергнут:** kit-шаблоны (INFRA.md, `.env.example`, промпты) содержат
|
||||
shell-сниппеты с `$VAR`/`${VAR}` — синтаксис `$` коллидирует и потребовал бы экранирования по
|
||||
всему kit (хрупко, нечитабельно).
|
||||
- **Jinja2 отвергнут:** новая pip-зависимость (ТЗ §9 запрещает без обоснования) + условная логика
|
||||
в шаблонах = второй язык программирования в kit → выше риск дрейфа. Kit обязан быть тупым.
|
||||
- Синтаксис `{{…}}` визуально различим, greppable; в Markdown/YAML kit-файлов естественно не
|
||||
встречается, остаточные случаи ловит скан.
|
||||
|
||||
**Словарь — `onboarding/placeholders.json`** (машиночитаемый single source of truth; формат:
|
||||
`{ "NAME": {"description": …, "required": bool, "default": …|null, "example": …} }`):
|
||||
|
||||
| Плейсхолдер | Смысл | Обяз. |
|
||||
|---|---|---|
|
||||
| `{{PROJECT_NAME}}` | человекочитаемое имя проекта | да |
|
||||
| `{{PROJECT_DESCRIPTION}}` | 1–2 фразы «зачем проект» (README/PRODUCT_VISION) | да |
|
||||
| `{{REPO}}` | имя Gitea-репо (== каталог под `/repos`) | да |
|
||||
| `{{GITEA_OWNER}}` | owner/org репо в Gitea | да |
|
||||
| `{{WORK_ITEM_PREFIX}}` | префикс work-item (`ET`/`ORCH`-аналог) | да |
|
||||
| `{{PLANE_PROJECT_ID}}` | uuid Plane-проекта (известен после Plane-шага apply) | да |
|
||||
| `{{STACK}}` | стек проекта (описательно) | да |
|
||||
| `{{TEST_CMD}}` | команда тестов (напр. `pytest -q`) | да |
|
||||
| `{{PROD_PORT}}` / `{{STAGING_PORT}}` | порты прод/staging | да |
|
||||
|
||||
Расширение словаря = правка `placeholders.json` + kit + тестов в одном PR. Тесты держат
|
||||
**биекцию**: каждый плейсхолдер, встречающийся в kit, объявлен в словаре, и каждый объявленный —
|
||||
используется (нет мёртвых/опечаточных).
|
||||
|
||||
### D3 — Copy-vs-template split (OQ-3, BR-2)
|
||||
|
||||
| Класс | Файлы | Механизм |
|
||||
|---|---|---|
|
||||
| **Live-copy канона** (НЕ хранится в kit) | `docs/_templates/**` (16), `docs/_standards/**` (3) | копируются скриптом **verbatim из рабочего чекаута репо орка в момент материализации** |
|
||||
| **Параметризуемые шаблоны** (хранятся в kit) | 6 промптов, `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, `README.md`, `CHANGELOG.md`, `docs/ARCHITECTURE.md`, `docs/PIPELINE.md`, `docs/PRODUCT_VISION.md`, `docs/operations/INFRA.md`, `docs/architecture/adr/README.md`, `.env.example` | рендер `{{…}}` (D2) |
|
||||
| **Скелет-каркас** | `docs/work-items/.gitkeep`, `docs/history/.gitkeep` | копия как есть |
|
||||
|
||||
- Канон копируется **байт-в-байт, без переписывания**: ORCH-примеры внутри стандартов
|
||||
(`PIPELINE_DOCS.md` цитирует ORCH-088 и т.п.) остаются примерами — это не «утечка», а
|
||||
иллюстрация (утечкой считается орк-литерал там, где должен быть параметр — AC-5/TC-10:
|
||||
префикс work-item, порты 8500/8501, self-hosting-правила в паспорте/промптах).
|
||||
- Повторный `apply` существующие файлы в целевом репо **не перезаписывает** (идемпотентность
|
||||
BR-9): обновление канона в уже-онбордженных репо едет их обычными PR с reviewer-gate;
|
||||
новые онбординги автоматически получают свежий канон (live-copy, ТЗ §7).
|
||||
- Источник live-copy — чекаут, из которого запущен скрипт; скрипт проверяет наличие обоих
|
||||
каталогов и (в verify) количество скелетов ≥ 16 / стандартов ≥ 3.
|
||||
|
||||
### D4 — Скрипту разрешён read-only импорт `src` — закрытый список (OQ-4)
|
||||
|
||||
**Решение: импортировать, не снапшотить.** Закрытый список импортов:
|
||||
|
||||
| Импорт | Зачем |
|
||||
|---|---|
|
||||
| `src.projects._parse_projects_json`, `src.projects.ProjectConfig` | round-trip валидация генерируемой записи реестра фактическим парсером (AC-6/TC-12) |
|
||||
| `src.plane_sync._PLANE_NAME_TO_KEY` | точные канонические имена 22 статусов байт-в-байт (AC-7/TC-13) |
|
||||
| `src.config.settings` (read-only поля) | имена лейблов `auto_approve_label`/`auto_deploy_label`/`bug_fast_track_label` (дефолты `autoApprove`/`autoDeploy`/`Bug`), URL/токены Plane/Gitea из env |
|
||||
|
||||
- **Почему не снапшот:** дублирование констант = гарантированный дрейф (R-2); AC-6 и так требует
|
||||
фактический парсер; снапшот потребовал бы отдельного «теста синхронизации», который и есть
|
||||
признание дрейфа. Импорт даёт нулевой дрейф **по построению**.
|
||||
- Импорт безопасен: `src.projects` → `src.config` (pydantic-settings с дефолтами, инстанцируется
|
||||
без env); `src.plane_sync` module-level считает только строки из settings; `httpx` — уже
|
||||
зависимость проекта (`requirements.txt`), **новых pip-зависимостей нет**.
|
||||
- Импорт приватных имён (`_parse_projects_json`, `_PLANE_NAME_TO_KEY`) — сознательная,
|
||||
санкционированная ТЗ связь (ТЗ §2 разрешает явно). **Список закрыт:** любой новый импорт из
|
||||
`src` — только через обновление этого ADR. Контроль ненарушения `src` — снапшот-тест TC-21
|
||||
(`STAGE_TRANSITIONS`/`QG_CHECKS`) + AC-12 (diff).
|
||||
- Скрипт запускается из корня чекаута орка (runbook-предусловие); `sys.path`-шим в начале файла
|
||||
(паттерн `scripts/staging_check.py`).
|
||||
|
||||
### D5 — Plane-провижининг: канонические статусы + группы + fail-safe (OQ-5, BR-7)
|
||||
|
||||
**Ensure-семантика:** `GET states` → создать недостающие по точным именам (ключи
|
||||
`_PLANE_NAME_TO_KEY`, 22 имени); существующие (включая CE-дефолтные Backlog/Todo/In Progress/
|
||||
Done/Cancelled нового проекта) — `skipped(exists)` по совпадению имени. Аналогично лейблы:
|
||||
`autoApprove`/`autoDeploy`/`Bug` (имена — из `settings`, D4).
|
||||
|
||||
**Канонические группы статусов** (Plane: `backlog|unstarted|started|completed|cancelled`) —
|
||||
фиксируются этим ADR; код-критичные констрейнты выделены:
|
||||
|
||||
| Статус | Группа | Констрейнт |
|
||||
|---|---|---|
|
||||
| Backlog | `backlog` | |
|
||||
| Todo, To Analyse | `unstarted` | |
|
||||
| In Progress, Analysis, Architecture, Development, Code-Review, Review, Testing, Awaiting Deploy, Deploying, Monitoring after Deploy, Needs Input, In Review, Blocked, Approved, Confirm Deploy | `started` | **рабочие/гейтовые статусы НЕ в терминальных группах** — иначе terminal-detection ORCH-068 (`{uuid→group}`, группы `completed`/`cancelled` = терминал) ложно сочтёт живую задачу терминальной |
|
||||
| Rejected | `started` | reject = rework-петля в анализ, задача жива → НЕ `cancelled` |
|
||||
| Done | `completed` | терминал |
|
||||
| Cancelled | `cancelled` | терминал |
|
||||
| **STOP** | **`cancelled`** | **требование ORCH-090** (fail-closed: без статуса/группы ветка cancel не активируется) |
|
||||
|
||||
**Fail-safe (CE-пробелы):** код орка использует только GET states — доступность POST
|
||||
project/states/labels в Plane CE не гарантирована. Любой недоступный вызов (403/404/405/501/
|
||||
нереализовано) → шаг помечается **`manual-step`** со ссылкой на соответствующий раздел runbook
|
||||
(точное имя статуса + группа для ручного создания в UI), скрипт не падает (AC-7/TC-14).
|
||||
Заведомо ручные шаги: порядок статусов на доске (drag-and-drop, UI-only), workspace-webhook
|
||||
(существует, Ф-6 — verify печатает команду проверки, не создаёт).
|
||||
|
||||
### D6 — Gitea-провижининг: репо + webhook + initial push только в пустой репо (BR-9)
|
||||
|
||||
- **Репо:** `POST /api/v1/...` под `{{GITEA_OWNER}}`, `auto_init=false` (репо рождается пустым;
|
||||
`main` создаёт initial push). Существует → `skipped(exists)`.
|
||||
- **Webhook (per-repo):** events `push`/`pull_request`/`status`, `content_type: json`,
|
||||
`branch_filter: "*"`, URL = внешний URL орка `/webhook/gitea` (формат `SETUP_WEBHOOKS.md`).
|
||||
**Секрет: приёмник `src/webhooks/gitea.py` валидирует ОДИН глобальный
|
||||
`ORCH_GITEA_WEBHOOK_SECRET` на все репо** → скрипт **переиспользует** существующий секрет из
|
||||
env (никогда не генерит новый при наличии — новый сломал бы HMAC всех вебхуков); секрет
|
||||
отсутствует в env → сгенерить `secrets.token_hex(20)` + вывести оператору для `.env`
|
||||
(первичная настройка). В логах/отчёте секрет всегда маскируется (NFR-3).
|
||||
- **Initial push:** материализованный kit коммитится (`feat: onboarding skeleton (ORCH-009 kit)`)
|
||||
и пушится в `main` **только если репо свежесоздан/пуст** (Gitea `empty: true`); непустой репо →
|
||||
`manual-step` (kit-файлы НИКОГДА не пушатся поверх существующего контента). Это единственный
|
||||
разрешённый push: новый пустой репо до регистрации в реестре не является участником конвейера →
|
||||
**INV-4 (мерж только через PR-merge API) не затрагивается** (ТЗ §9).
|
||||
|
||||
### D7 — Запись реестра: полный merged-массив, скрипт `.env` не трогает (BR-8)
|
||||
|
||||
**Решение: скрипт выводит (а) standalone-запись нового проекта и (б) полный merged-массив
|
||||
`ORCH_PROJECTS_JSON`** = существующие записи verbatim + новая в конец. Источник существующих:
|
||||
текущий env / `--env-file` (дефолт — `.env` в корне чекаута, если есть); источника нет → только
|
||||
standalone-запись + инструкция. Перед выводом merged-массив прогоняется через
|
||||
`projects._parse_projects_json` (round-trip: поля новой записи совпадают, существующие не
|
||||
потеряны/не искажены — AC-6/TC-12).
|
||||
|
||||
- **Почему full-array, а не диф:** оператор вставляет одну строку в `.env` атомарно — ручное
|
||||
слияние JSON в env-строке (экранирование, запятые) и есть источник ошибок R-4.
|
||||
- Скрипт **не правит** `.env` прода и **не рестартит** контейнер (NFR-2): печатает строку +
|
||||
инструкцию «добавь в `.env` → управляемый рестарт оркестратора (self-hosting: групповое окно,
|
||||
выполнять осознанно)» со ссылкой на runbook. `verify` после рестарта показывает разрыв
|
||||
«создано, но не зарегистрировано» (R-4).
|
||||
|
||||
### D8 — Песочница для smoke: staging-контур 8501 + одноразовый SMK-проект (OQ-6, AC-13)
|
||||
|
||||
**Решение: smoke выполняется на staging-контуре** (`orchestrator-staging`, 8501, изолированная БД
|
||||
`./data/staging`) с **одноразовым** sandbox: Plane-проект `onboarding-smoke` (префикс `SMK`) +
|
||||
Gitea-репо `onboarding-smoke`, онбордженные самим скриптом. Регистрация — в `ORCH_PROJECTS_JSON`
|
||||
**staging-окружения** (`.env.staging`) + рестарт staging (свободен, в отличие от прод-инварианта).
|
||||
Прогон: тестовая задача SMK → стадия `analysis` → проверить следы чтения паспорта/`AGENTS.md` и
|
||||
артефакты `docs/work-items/SMK-…/` по канону `PIPELINE_DOCS.md`.
|
||||
|
||||
- **Прод-контур отвергнут:** smoke-задача писала бы конвейерные строки в общую прод-БД и жила бы
|
||||
в общей очереди с enduro/ORCH — шум и риск в общем инстансе (дух NFR-2).
|
||||
- Протокол прогона — раздел **«Журнал smoke-прогонов»** в `ONBOARDING.md` (дата, параметры,
|
||||
PASS/FAIL по чек-листу AC-13); для приёмки ORCH-009 первый протокол обязателен, ссылка на него —
|
||||
из `13-test-report.md` задачи. Судьба sandbox-артефактов: архив/удаление вручную по разделу
|
||||
«Откат» runbook (скрипт не удаляет ничего — BR-9).
|
||||
|
||||
### D9 — Языковая политика kit-промптов: канон орка (OQ-7, AC-4)
|
||||
|
||||
**Решение: 5 ru + deployer en** — ровно языковая раскладка канона орка, нормативная по
|
||||
ADR-001 D2 ORCH-092 (deployer — самый safety-critical промпт, en-раскладка минимизирует
|
||||
регресс-поверхность байт-точных verdict-ключей/команд). Kit наследует канон без отступлений;
|
||||
per-project отступление возможно позже **только** решением в собственном ADR нового проекта
|
||||
(правило фиксируется в `onboarding/README.md` и шаблоне `CONTRIBUTING.md`). Проверяется TC-08.
|
||||
|
||||
### D10 — Branch protection `main` нового репо: НЕ включать (OQ-8)
|
||||
|
||||
**Решение: не включать.** Merge-актор конвейера — Gitea PR-merge API под токеном орка
|
||||
(INV-4; `src/merge_gate.py`, ORCH-093): required-approvals/required-status-checks дали бы
|
||||
405/409-класс отказов `merge_pr` → ложные HOLD (ровно класс инцидента ORCH-063). Сам орк живёт
|
||||
без protection — защита `main` держится конвенцией (агенты не пушат `main`; мерж только через
|
||||
PR API) и скоупом токенов. Решение фиксируется в runbook; пересмотр — при мультитенант-hardening
|
||||
(D5.6, вне объёма).
|
||||
|
||||
### D11 — Форма CLI и тестируемость без сети (BR-11, NFR-5)
|
||||
|
||||
**Один файл `scripts/onboard_project.py`** (операторская UX: один очевидный энтрипойнт; паттерн
|
||||
`scripts/staging_check.py`), внутри — слои:
|
||||
|
||||
- **Чистое ядро:** `build_plan(params, observed) -> Plan` — без I/O; `Plan` = упорядоченный список
|
||||
шагов закрытого списка BR-1: `plane.project → plane.states(22) → plane.labels(3) → gitea.repo →
|
||||
gitea.webhook → kit.materialize+push → registry.emit`. Рендер kit — чистая функция
|
||||
`render(text, params)` (D2), в plan-режиме выполняется **in-memory** (ни одной записи на диск —
|
||||
AC-8/TC-16); материализация на диск (temp-dir → git init/commit/push) — только в `apply`.
|
||||
- **Тонкие клиенты** `PlaneClient`/`GiteaClient` (httpx; единственные точки сети) — инжектируются
|
||||
→ в тестах мокаются целиком (NFR-5: ноль сетевых вызовов, TC-13…18).
|
||||
- **Режимы:** `plan` (дефолт) — только GET-пробы текущего состояния + полный план без единой
|
||||
мутации; `apply` — ensure-исполнение (идемпотентно, без delete-операций вовсе); `verify` —
|
||||
GET-пробы + локальные проверки (registry round-trip, резолв всех логических ключей включая
|
||||
`confirm_deploy`/`stop`, лейблы, webhook активен, kit-файлы в репо, скан неразрешённых
|
||||
плейсхолдеров).
|
||||
- **Отчёт:** человекочитаемый + `--json`; статус каждого шага
|
||||
`created | skipped(exists) | manual-step | planned | error`; exit-коды: `0` — чисто, `2` — есть
|
||||
`manual-step`/gap в verify, `1` — ошибка. Каждый шаг логируется (BR-11).
|
||||
|
||||
---
|
||||
|
||||
## Альтернативы (сводно)
|
||||
|
||||
- **`docs/_onboarding/` / `scripts/onboarding/`** — отвергнуто (D1): смешение kit с живой докой
|
||||
орка / данных с кодом.
|
||||
- **Jinja2 / `string.Template`** — отвергнуто (D2): новая зависимость и логика в шаблонах /
|
||||
коллизия `$` с shell-сниппетами.
|
||||
- **Снапшот констант `src` + тест синхронизации** — отвергнуто (D4): узаконенный дрейф; импорт
|
||||
даёт нулевой дрейф по построению.
|
||||
- **Генерация нового webhook-секрета per-repo** — отвергнуто (D6): приёмник валидирует один
|
||||
глобальный секрет; новый сломал бы HMAC существующих вебхуков.
|
||||
- **Диф-вывод реестра** — отвергнуто (D7): ручное слияние JSON-в-env — источник ошибок R-4.
|
||||
- **Smoke на прод-контуре** — отвергнуто (D8): запись в общую прод-БД/очередь.
|
||||
- **Branch protection `main`** — отвергнуто (D10): ломает PR-merge API актора (ложные HOLD).
|
||||
|
||||
## Последствия
|
||||
|
||||
- **+** Turnkey-способность D5.2: один проход + runbook вместо археологии; тихие деградации
|
||||
(статусы/лейблы/промпты) закрываются проверяемо (`verify` + структурные тесты).
|
||||
- **+** Нулевой риск рантайма: `src/**` байт-в-байт, нового кода в горячих путях нет, kill-switch
|
||||
не нужен; регресс enduro/orchestrator невозможен по построению.
|
||||
- **+** Анти-дрейф структурный: live-copy канона (BR-2) + единые канон-тесты kit (NFR-4) +
|
||||
биекция словаря плейсхолдеров.
|
||||
- **−** Операторские шаги остаются ручными (env + управляемый рестарт; UI-only Plane): осознанное
|
||||
ограничение NFR-2 (никакой автоматики рестартов) — митигировано runbook + verify (видимый разрыв).
|
||||
- **−** Импорт приватных имён `src` связывает скрипт с внутренними идентификаторами — митигировано
|
||||
закрытым списком (D4) и тем, что рефакторинг имён мгновенно валит импорт в тестах (видимая,
|
||||
не тихая поломка).
|
||||
- **−** Kit-шаблоны промптов требуют сопровождения при эволюции канона — митигировано общими
|
||||
структурными требованиями тестов (расхождение ловит CI, NFR-4).
|
||||
- **Откат:** удалить `onboarding/`, `scripts/onboard_project.py`, `docs/operations/ONBOARDING.md`,
|
||||
тесты — репо в исходном состоянии (ТЗ §7); внешние сущности (sandbox/созданные проекты) —
|
||||
вручную по разделу «Откат» runbook.
|
||||
|
||||
## Ссылки
|
||||
|
||||
- BRD: `docs/work-items/ORCH-009/01-brd.md` · TRZ: `02-trz.md` · AC: `03-acceptance-criteria.md`
|
||||
· Test plan: `04-test-plan.yaml`
|
||||
- Сверено по коду: `src/projects.py` (`ProjectConfig`, `_parse_projects_json`, `_load_projects`),
|
||||
`src/plane_sync.py:94-165` (`_DEFAULT_STATES`, `_PLANE_NAME_TO_KEY` — 22 имени, fail-closed
|
||||
`Confirm Deploy`/`STOP`), `src/qg/checks.py::check_architecture_done`, `src/config.py`
|
||||
(`auto_*_label`/`bug_fast_track_label`), `requirements.txt` (httpx уже есть)
|
||||
- Операции: `docs/operations/SETUP_WEBHOOKS.md` (формат Gitea-webhook; Plane workspace-webhook —
|
||||
SQL-only), `docs/operations/INFRA.md`
|
||||
- Стандарты: `docs/_standards/PIPELINE_DOCS.md` (§4 ADR-naming), `HANDOFF_PROTOCOL.md`,
|
||||
`TRACEABILITY.md`
|
||||
- ADR: adr-0001 (registry), adr-0017/0018 (паттерны условности), adr-0021/0022 (канон промптов/
|
||||
трассировка), adr-0026 (STOP, группа `cancelled`), ORCH-092 `ADR-001` D2 (язык deployer),
|
||||
сквозной **adr-0035-turnkey-project-onboarding**
|
||||
@@ -1,66 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-009
|
||||
stage: architecture
|
||||
author_agent: architect
|
||||
status: proposed
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# 07 — Инфра-требования: ORCH-009 — Turnkey-онбординг проектов
|
||||
|
||||
Work Item: **ORCH-009** · Repo: **orchestrator** · Стадия: architecture
|
||||
|
||||
> Топология оркестратора **не меняется** (NFR-1/NFR-2: `src/**` и compose не трогаются).
|
||||
> Файл фиксирует **предусловия исполнения способности** (токены/доступы/контуры) и инфра-границы
|
||||
> операторского скрипта. Детали решений — `06-adr/ADR-001-turnkey-onboarding-kit-and-cli.md`.
|
||||
|
||||
## I-1. Топология / окружения
|
||||
|
||||
- **Прод (`orchestrator`, 8500):** не затрагивается. Скрипт не создаёт/не останавливает/не
|
||||
рестартит контейнеры; в общую БД не пишет (читает только файлы чекаута и внешние API).
|
||||
- **Staging (`orchestrator-staging`, 8501, БД `./data/staging`):** контур smoke-прогона (ADR D8).
|
||||
Регистрация sandbox-проекта — в `.env.staging`; рестарт staging — штатный, свободный
|
||||
(прод-инвариант на него не распространяется).
|
||||
- **Новые внешние сущности** (создаются скриптом в `apply`): Plane-проект, Gitea-репо +
|
||||
per-repo webhook. Аддитивно: существующие проекты/репо не модифицируются (BR-9).
|
||||
- **Запуск скрипта:** хост mva154, из корня чекаута репо orchestrator. Среда исполнения —
|
||||
venv с `requirements.txt` (httpx уже в зависимостях; новых pip-зависимостей нет) **или**
|
||||
`docker compose exec orchestrator python scripts/onboard_project.py …` (read-only к рантайму,
|
||||
без рестартов). Канонический способ фиксирует runbook `docs/operations/ONBOARDING.md`.
|
||||
|
||||
## I-2. Переменные окружения / секреты
|
||||
|
||||
**Новых env-переменных не вводится.** Используются существующие (предусловия запуска):
|
||||
|
||||
| Переменная | Роль в онбординге |
|
||||
|---|---|
|
||||
| `ORCH_PLANE_API_TOKEN` (+ `ORCH_PLANE_API_URL`, `ORCH_PLANE_WORKSPACE_SLUG`) | создание/чтение Plane-проекта, статусов, лейблов; токен с правом создания проектов в workspace |
|
||||
| `ORCH_GITEA_TOKEN` (+ Gitea base URL) | создание репо (под `{{GITEA_OWNER}}`), per-repo webhook; токен с правом create-repo + hooks |
|
||||
| `ORCH_GITEA_WEBHOOK_SECRET` | **переиспользуется** для webhook нового репо (приёмник валидирует один глобальный секрет, ADR D6); отсутствует → скрипт генерит и печатает оператору для `.env` |
|
||||
| `ORCH_PROJECTS_JSON` | источник существующих записей для merged-вывода (ADR D7); **применение новой строки — операторский шаг** |
|
||||
|
||||
- Секреты — только в `.env`/`.env.staging` на хосте, в гит не попадают (правило #8 CLAUDE.md);
|
||||
в логах/отчётах скрипта секреты маскируются (NFR-3).
|
||||
- Kit несёт собственный `.env.example` нового проекта (дескрипторы без значений) — канон секретов
|
||||
транслируется в онбордируемые репо.
|
||||
|
||||
## I-3. Деплой / рестарт
|
||||
|
||||
- **Скрипт НИКОГДА не рестартит/не останавливает прод-контейнер** (NFR-2, self-hosting инвариант).
|
||||
- Регистрация проекта в реестре (Ф-3): правка `.env` (строка `ORCH_PROJECTS_JSON` из отчёта
|
||||
скрипта) + **управляемый операторский рестарт** оркестратора — групповое окно для ВСЕХ проектов
|
||||
общего инстанса; runbook помечает шаг self-hosting-предупреждением и командой проверки
|
||||
(`GET /queue`, резолв статусов нового проекта).
|
||||
- TTL-self-heal статусов Plane (ORCH-068, 300с) рестарта не требует: статусы/лейблы, созданные
|
||||
после регистрации, подхватываются без вмешательства.
|
||||
- Деплой самой задачи ORCH-009 — штатный конвейер: изменение docs/scripts/tests-only, образ
|
||||
пересобирается стандартно, staging-гейт (8501) обязателен как обычно.
|
||||
|
||||
## I-4. CI/CD
|
||||
|
||||
- `.gitea/workflows/` — **без изменений**: новые тесты (`tests/test_onboarding_kit.py`,
|
||||
`test_onboarding_script.py`, `test_onboarding_invariants.py`) подхватываются существующим
|
||||
pytest-шагом; все детерминированы, без сети (NFR-5).
|
||||
- Инфра-предусловий в образе нет: скрипт — операторский CLI вне рантайма, в образ ничего
|
||||
дополнительно не запекается.
|
||||
@@ -1,42 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-009
|
||||
stage: architecture
|
||||
author_agent: architect
|
||||
status: proposed
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# 10 — Технические риски: ORCH-009 — Turnkey-онбординг проектов
|
||||
|
||||
Work Item: **ORCH-009** · Repo: **orchestrator** · Стадия: architecture
|
||||
|
||||
> Информационный (гейтом не парсится). Детализирует риски BRD §8 (R-1…R-5) до уровня решений
|
||||
> `06-adr/ADR-001`; митигейшены привязаны к D-решениям и TC тест-плана.
|
||||
|
||||
## Реестр рисков
|
||||
|
||||
| ID | Риск | Вер. | Влия. | Митигейшн |
|
||||
|----|------|------|-------|-----------|
|
||||
| TR-1 | **Drift канона** (R-1): копия `_templates`/`_standards` в новых репо разъезжается с живым каноном орка; kit-промпты отстают от эволюции канона 52d | Сред. | Сред. | BR-2/D3: live-copy в момент онбординга, второй редактируемой копии канона нет; NFR-4: структурные канон-тесты kit (TC-03…08) ловят расхождение в CI; обновление онбордженных репо — их обычные PR |
|
||||
| TR-2 | **Тихая деградация Plane-контрактов** (R-2): опечатка в имени статуса/лейбла или неверная **группа** → fail-closed/fail-safe ветки (`Confirm Deploy`, `STOP`, авто-лейблы, `Bug`) молча не работают; рабочий статус в группе `completed`/`cancelled` → terminal-detection ORCH-068 ложно терминалит живую задачу | Сред. | Выс. | D4: имена импортируются из `_PLANE_NAME_TO_KEY` (нулевой дрейф по построению, TC-13); D5: канонические группы зафиксированы таблицей ADR с код-критичными констрейнтами (STOP→`cancelled`, терминальные группы только Done/Cancelled/STOP); `verify` резолвит ВСЕ логические ключи включая `confirm_deploy`/`stop` |
|
||||
| TR-3 | **Скрипт с боевыми токенами** (R-3): ошибка = разрушительное действие на общих Plane/Gitea | Низ. | Выс. | BR-9/D11: `plan` (GET-only) — дефолт; delete-операций в коде нет вовсе (TC-18); аддитивный ensure (TC-17); push только в свежесозданный пустой репо (`empty: true`, D6); существующие сущности не модифицируются |
|
||||
| TR-4 | **Разрыв «создано, но не зарегистрировано»** (R-4): оператор не применил env+рестарт → проект невидим для орка | Сред. | Сред. | D7: merged-массив одной строкой (без ручного слияния JSON); runbook: явный операторский шаг с self-hosting-предупреждением + команда проверки; `verify` показывает разрыв (TC-12, AC-11) |
|
||||
| TR-5 | **Утечка орк-специфики в kit** (R-5): новый репо получает ORCH-префикс, порты 8500/8501, self-hosting-правила орка | Сред. | Сред. | D2: скан неразрешённых плейсхолдеров после рендера; TC-10: явный тест на утечки; биекция словаря `placeholders.json` ↔ kit (мёртвые/опечаточные плейсхолдеры не живут) |
|
||||
| TR-6 | **Поломка HMAC существующих вебхуков**: генерация нового per-repo секрета при едином глобальном `ORCH_GITEA_WEBHOOK_SECRET` приёмника | Низ. | Выс. | D6: секрет **переиспользуется** из env (новый генерится только при полном отсутствии — первичная настройка); секрет маскируется в логах/отчёте (NFR-3) |
|
||||
| TR-7 | **Связь скрипта с приватными именами `src`** (`_parse_projects_json`, `_PLANE_NAME_TO_KEY`): рефакторинг src валит скрипт | Низ. | Низ. | D4: закрытый список импортов (расширение — только через ADR); поломка видимая, не тихая — импорт падает в тестах (TC-12/13) на том же PR, что рефакторит src; снапшот TC-21 гардит сам src |
|
||||
| TR-8 | **Plane CE API-пробелы** (OQ-5): POST project/states/labels недоступен в CE → провижининг неполон | Сред. | Низ. | D5: fail-safe деградация в `manual-step` со ссылкой на runbook (имя+группа для UI-создания), не падение (TC-14); `verify` подтверждает итоговую полноту независимо от способа создания |
|
||||
| TR-9 | **Smoke загрязняет общий контур**: прогон способности в проде = строки в общей БД/очереди | Низ. | Сред. | D8: smoke только на staging (8501, изолированная БД, `.env.staging`); sandbox-сущности одноразовые, снос вручную по разделу «Откат» runbook |
|
||||
|
||||
## Сводный вывод
|
||||
|
||||
Доминирующий класс — **операционные риски исполнения способности** (TR-2/TR-3/TR-4): они
|
||||
митигированы структурно (импорт констант вместо копий, GET-only дефолт, отсутствие delete-операций,
|
||||
verify-режим), а не дисциплиной. Рисков для прод-конвейера самой задачи **нет по построению**:
|
||||
`src/**` байт-в-байт (AC-12/TC-21), нового кода в горячих путях нет, kill-switch не требуется —
|
||||
способность активируется только явным запуском операторского CLI.
|
||||
|
||||
Эскалация `arch:major-change` **не требуется**: ни новой стадии, ни нового рантайм-компонента,
|
||||
ни изменения БД — это docs/templates/scripts/tests-only способность (новая стадия/компонент
|
||||
конвейера не вводится). Возврат в анализ не требуется: ТЗ выполнимо без нарушения принципов.
|
||||
Остаточный риск для прод-конвейера (self-hosting): **низкий**.
|
||||
@@ -1,145 +0,0 @@
|
||||
---
|
||||
verdict: APPROVED
|
||||
work_item: ORCH-009
|
||||
stage: review
|
||||
author_agent: reviewer
|
||||
status: approved
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-fable-5
|
||||
type: review
|
||||
work_item_id: ORCH-009
|
||||
version: 1
|
||||
---
|
||||
|
||||
# Review ORCH-009 — Turnkey-онбординг проектов (kit + CLI + runbook)
|
||||
|
||||
Ветка: `feature/ORCH-009-turnkey-plane` · Diff vs `origin/main`: 41 файл, +5120/−10.
|
||||
Состав: kit `onboarding/repo-skeleton/` (28 файлов), CLI `scripts/onboard_project.py` (1090 строк),
|
||||
runbook `docs/operations/ONBOARDING.md`, 3 тест-модуля (83 теста), golden-source доки, ADR×2.
|
||||
|
||||
## Summary
|
||||
|
||||
PR реализует ТЗ полностью и точно по ADR-001 (D1–D11), с нулевым касанием рантайма. Вердикт
|
||||
**APPROVED**: P0/P1 findings нет; найдены 3×P2 (харднинг краевых путей CLI) и 2×P3 (косметика) —
|
||||
не блокируют, рекомендованы к follow-up. Документация обновлена в том же PR по всем требуемым
|
||||
точкам.
|
||||
|
||||
**Проверено по 4 осям:**
|
||||
|
||||
### Ось 1 — Соответствие ТЗ (`02-trz.md`, `03-acceptance-criteria.md`) — ✅
|
||||
|
||||
| Требование | Статус | Чем подтверждено |
|
||||
|---|---|---|
|
||||
| FR-1 состав kit | ✅ | AC-1/TC-01: все 19 элементов на месте; `_templates`/`_standards` в kit НЕ хранятся (анти-форк тест) |
|
||||
| FR-2 канон 52d/92 промптов | ✅ | AC-2/TC-03…06: 5 XML-секций в нормативном порядке, «❌→✅», `<escalation>` у dev/reviewer/tester, `<thinking>` — паритет с эталоном (architect/reviewer/tester/deployer в обоих деревьях), 52c-схема, verdict-ключи байт-в-байт, даты/модели — плейсхолдеры |
|
||||
| FR-2 reviewer-gate доки | ✅ | AC-3/TC-07: «документация НЕ обновлена → `REQUEST_CHANGES`» в kit reviewer.md |
|
||||
| FR-3 INFRA.md шаблон | ✅ | AC-10/TC-19: топология/контейнеры/env-карта/границы доступа/риски общего хоста/деплой |
|
||||
| FR-4 CLI plan/apply/verify | ✅ | AC-7/8/9, TC-13…18: 22 статуса из `_PLANE_NAME_TO_KEY`, группы по D5, лейблы из конфига, dry-run без единой мутации (мутации materialize/push замоканы на AssertionError), идемпотентный ensure, delete-операций нет, `docker`/`systemctl`/`compose`/запись `.env` отсутствуют в исходнике (TC-18-тест по AST/grep) |
|
||||
| FR-5 verify | ✅ | round-trip реестра фактическим парсером, резолв всех 22 имён (включая fail-closed `Confirm Deploy`/`STOP` — отдельный негативный тест), лейблы, webhook active, полнота kit, скан `{{…}}` |
|
||||
| FR-6 runbook | ✅ | AC-11/TC-20: все слои в порядке, 🖐-маркировка ручных шагов + команды проверки, self-hosting-предупреждение о групповом окне рестарта, workspace-webhook — «существует, только проверка» |
|
||||
| §4/§5 нет API/БД изменений | ✅ | diff: `src/**` пуст |
|
||||
| §9 инварианты | ✅ | см. ось 2 |
|
||||
| AC-12 регресс | ✅ | 1794 passed локально; 2 падения (`test_resolve_agent_model`/`_effort`) — **средовые, pre-existing**: вызваны `ORCH_AGENT_FALLBACK_MODEL`/`ORCH_AGENT_EFFORT_*` в env агент-раннера, с очищенной средой 49/49 зелёные; файлы этих тестов PR не трогает — не регресс этого PR (авторитетен CI с чистой средой) |
|
||||
| AC-13 операторский smoke | ⏳ | По построению выполняется на приёмке (tester/оператор): runbook §5.2 + «Журнал smoke-прогонов» (плейсхолдер первого прогона), D8 требует ссылку из `13-test-report.md`. **Handoff-заметка стадии testing** — см. «Для следующей стадии» |
|
||||
|
||||
### Ось 2 — Соответствие ADR (`06-adr/ADR-001`, сквозной `adr-0035`) — ✅
|
||||
|
||||
- **D1–D11 реализованы без отступлений**: раскладка top-level `onboarding/` (D1); `{{NAME}}` +
|
||||
`str.replace` + обязательный пост-скан + биекция словаря (D2, тест); live-copy verbatim
|
||||
`_templates`(≥16)/`_standards`(≥3) (D3, тест байт-сравнения); закрытый список импортов `src` —
|
||||
AST-тест `test_tc21_cli_src_imports_stay_in_closed_list` (D4); таблица групп `STATE_GROUPS` 1:1
|
||||
с таблицей D5, код-критичные констрейнты загвождены тестом (`STOP`→`cancelled`; терминальные
|
||||
группы == {Done, Cancelled, STOP}; set-равенство с `_PLANE_NAME_TO_KEY` ловит будущий дрейф);
|
||||
`auto_init=false` + переиспользование глобального секрета + push только в пустой репо (D6 —
|
||||
сверил с приёмником `src/webhooks/gitea.py:38-41`: действительно ОДИН глобальный секрет);
|
||||
merged-full-array + round-trip + «.env не правим» (D7); smoke на staging 8501 (D8); 5 ru +
|
||||
deployer en c «Do NOT translate»-гардом (D9, тест на кириллицу); runbook фиксирует «branch
|
||||
protection НЕ включать» (D10); plan/apply/verify, чистый `build_plan`, инжектируемые клиенты,
|
||||
отчёт `created/skipped(exists)/manual-step/planned/error`, exit-коды 0/2/1 (D11).
|
||||
- **Инварианты NFR-1/INV-4**: `git diff origin/main...HEAD -- src/ .openclaw/ docs/_templates/
|
||||
docs/_standards/ docs/operations/INFRA.md` — пусто; снапшот-тесты `STAGE_TRANSITIONS`/`QG_CHECKS`
|
||||
зелёные; push — только initial в свежесозданный пустой репо (вне конвейера до регистрации),
|
||||
PR-merge API не затрагивается.
|
||||
- **Трассировка (TRACEABILITY.md)**: правка `docs/operations/SETUP_WEBHOOKS.md` обобщает
|
||||
enduro-хардкод, **усиливая** (не ломая) инвариант одного глобального HMAC-секрета — сверено с
|
||||
кодом приёмника; правка `docs/architecture/adr/README.md` — реестр сквозных ADR (общий индекс),
|
||||
бэкфилл строк 0032–0034 сверен: все три файла существуют в main, номера/задачи корректны,
|
||||
«текущий максимум 0035» верен. Чужие маркированные инварианты не задеты.
|
||||
|
||||
### Ось 3 — Качество кода — ✅ (с P2-findings ниже)
|
||||
|
||||
Docstrings на всех публичных функциях; чистое ядро отделено от I/O; единственная точка
|
||||
subprocess (только `git`, cwd = temp-материализация, токен в логе маскируется); секрет в отчёте
|
||||
`***` + явный тест non-leak (`test_secret_never_leaks_into_report`); тесты содержательные
|
||||
(recording-фейки мутаций, негативные сценарии CE-отказов, AST-проверка импортов, monkeypatch-мины
|
||||
на мутации в dry-run) — не тривиальные. Багфикс-трек не применим (задача не `Bug`).
|
||||
|
||||
### Ось 4 — Документация — ✅ ОБНОВЛЕНА В ТОМ ЖЕ PR
|
||||
|
||||
| Точка | Статус |
|
||||
|---|---|
|
||||
| `CLAUDE.md` — раздел «Turnkey-онбординг (ORCH-009)» | ✅ |
|
||||
| `docs/architecture/README.md` — раздел + ссылки на ADR | ✅ |
|
||||
| `CHANGELOG.md` — запись `feat` (детальная) | ✅ |
|
||||
| ADR per-WI `06-adr/ADR-001` + сквозной `adr-0035` + индекс `adr/README.md` | ✅ |
|
||||
| `docs/operations/ONBOARDING.md` (новый runbook) | ✅ |
|
||||
| `docs/operations/SETUP_WEBHOOKS.md` — обобщён per-repo (ТЗ §2) | ✅ |
|
||||
| `onboarding/README.md` — устройство kit, словарь, анти-форк | ✅ |
|
||||
| README «Известные ограничения» (ORCH-079) | N/A — онбординг в списке открытых ограничений не значится, обновление не требуется (проверено) |
|
||||
| `08-data-requirements.md` отсутствует | Легитимно: гейт `check_analysis_complete` требует только 01–04; ТЗ §5 «изменений БД нет» |
|
||||
|
||||
## Findings
|
||||
|
||||
### P0 — Blocker
|
||||
Нет.
|
||||
|
||||
### P1 — Must fix
|
||||
Нет.
|
||||
|
||||
### P2 — Should fix (follow-up, не блокирует)
|
||||
- [ ] **Quoted-значение в `.env` → тихая потеря существующих записей в merged-выводе.**
|
||||
`read_existing_registry` (fallback-парс `.env`) возвращает значение после `=` как есть; если
|
||||
строка в `.env`/`--env-file` взята в кавычки (`ORCH_PROJECTS_JSON='[...]'`), `json.loads`
|
||||
в `merged_projects_json` молча даёт `existing=[]` → инструкция оператору содержит массив ТОЛЬКО
|
||||
с новым проектом, а runbook §4.1 велит «заменить строку» → риск выпадения enduro/orchestrator
|
||||
из реестра. Доминирующий путь безопасен (pydantic `env_file=".env"` снимает кавычки, фоллбек
|
||||
срабатывает только при cwd вне корня), потому P2, не P1. Рекомендация: в фоллбеке `strip("'\"")`
|
||||
+ предупреждение/GAP, если строка в `.env` есть, а распарсенный existing пуст. (AC-6-периметр;
|
||||
ADR D7 «существующие не теряются».)
|
||||
- [ ] **`GiteaClient.create_repo`: фоллбек `POST /user/repos` может создать репо в чужом
|
||||
namespace.** При `--gitea-owner`, не являющемся ни org, ни юзером токена, отказ org-маршрута
|
||||
ведёт в `/user/repos` → репо рождается под юзером токена, последующие webhook/push по
|
||||
`owner/repo` дают 404/manual-step. Не деструктивно и видимо в отчёте, но это непрошенная
|
||||
мутация не туда. Рекомендация: сверять `owner.login` ответа с запрошенным owner; расхождение →
|
||||
`manual-step` (комментарий в коде уже упоминает admin-маршрут — либо реализовать
|
||||
`/admin/users/{owner}/repos`, либо честно деградировать).
|
||||
- [ ] **CE-деградация Plane + успешный Gitea в одном apply запекает литерал
|
||||
`<assigned-on-apply>` в запушенный паспорт.** Если `plane.project` ушёл в `manual-step`, а репо
|
||||
создан — kit рендерится с `PLANE_PROJECT_ID="<assigned-on-apply>"` и пушится; повторный apply
|
||||
с `--plane-project-id` уже не перезапишет (репо непустой). Скан ловит только `{{…}}`-синтаксис.
|
||||
Рекомендация: при неразрешённом PLANE_PROJECT_ID деградировать `kit.materialize`/`kit.push` в
|
||||
`manual-step` (push после получения uuid) ИЛИ добавить `<assigned-on-apply>` в скан verify.
|
||||
|
||||
### P3 — Nice to have
|
||||
- [ ] `--env-file` молча игнорируется в `plan`-режиме (`_registry_instructions(report, params,
|
||||
None)`): превью merged-массива в plan может расходиться с apply при нестандартном env-файле.
|
||||
- [ ] Push-URL с `oauth2:<token>@` остаётся в `.git/config` временного каталога материализации
|
||||
после успешного apply (temp-dir не чистится). Рекомендация: cleanup на успехе (на ошибке
|
||||
сохранять для дебага, как сейчас).
|
||||
|
||||
## Документация
|
||||
|
||||
Обновлена полностью в том же PR (см. таблицу оси 4): паспорт, архитектурный README, CHANGELOG,
|
||||
оба ADR + индекс, новый runbook, обобщённый SETUP_WEBHOOKS, README kit. Несоответствий
|
||||
«код изменён — дока молчит» не найдено; обзорная витрина README не затронута задачей по
|
||||
построению (ограничение в ней не значилось).
|
||||
|
||||
## Для следующей стадии (testing) — handoff
|
||||
|
||||
1. **AC-13 (операторский smoke)**: прогон по runbook §5.2 (staging 8501, sandbox `SMK`) должен
|
||||
быть выполнен и запротоколирован в «Журнале smoke-прогонов» `ONBOARDING.md`, ссылка — из
|
||||
`13-test-report.md` (требование D8). Это единственный непокрытый pytest'ом AC.
|
||||
2. Локальный полный регресс гонять с чистой средой (без `ORCH_AGENT_FALLBACK_MODEL`/
|
||||
`ORCH_AGENT_EFFORT_*` агент-раннера) — иначе 2 ложных средовых падения в
|
||||
`test_resolve_agent_model.py`/`test_resolve_agent_effort.py` (pre-existing, к PR отношения
|
||||
не имеют).
|
||||
@@ -1,169 +0,0 @@
|
||||
---
|
||||
result: PASS
|
||||
work_item: ORCH-009
|
||||
stage: testing
|
||||
author_agent: tester
|
||||
status: pass
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-fable-5
|
||||
type: test-report
|
||||
work_item_id: ORCH-009
|
||||
---
|
||||
|
||||
# Test Report — ORCH-009 — Turnkey-онбординг проектов (kit + CLI + runbook)
|
||||
|
||||
> Машинный вердикт — в frontmatter (`result: PASS`). Ниже — факты, на которых он основан.
|
||||
|
||||
## Окружение
|
||||
- Python: 3.12.13
|
||||
- pytest: 8.3.3
|
||||
- Дата: 2026-06-10
|
||||
- Worktree: `/repos/_wt/orchestrator/feature_ORCH-009-turnkey-plane/` (ветка
|
||||
`feature/ORCH-009-turnkey-plane`) — прогон в worktree ветки задачи, НЕ в общем чекауте
|
||||
`/repos/orchestrator` (анти-гонка checkout).
|
||||
- Прод `http://localhost:8500/health` → `{"status":"ok","service":"orchestrator"}` ✅
|
||||
- Staging `http://localhost:8501/health` → `{"status":"ok","service":"orchestrator"}` ✅
|
||||
- Прод-контейнер не трогался (read-only smoke, NFR self-hosting).
|
||||
|
||||
## Результаты
|
||||
|
||||
### Полный регресс (`pytest tests/ -v --tb=short`)
|
||||
**1712 passed, 1 failed (средовое, pre-existing — не регресс PR), 1 warning, 69.90s.**
|
||||
|
||||
Единственное падение — `tests/test_resolve_agent_effort.py::test_flags_present_when_configured`:
|
||||
```
|
||||
assert "--model claude-opus-4-8 " in flags
|
||||
E AssertionError: assert '--model claude-opus-4-8 ' in
|
||||
'--model claude-fable-5 --effort xhigh --fallback-model claude-sonnet-4-6 '
|
||||
```
|
||||
Диагноз (подтверждает handoff-пункт №2 reviewer'а в `12-review.md`): падение вызвано
|
||||
env-переменными агент-раннера (`ORCH_AGENT_MODEL_DEFAULT=claude-fable-5`,
|
||||
`ORCH_AGENT_FALLBACK_MODEL`, `ORCH_AGENT_EFFORT_*`), а не кодом ветки. Контрольный перепрогон
|
||||
с полностью очищенной средой (`env -u ORCH_AGENT_*`):
|
||||
```
|
||||
pytest tests/test_resolve_agent_effort.py tests/test_resolve_agent_model.py -q
|
||||
49 passed, 1 warning in 0.44s
|
||||
```
|
||||
Дополнительно проверено: `git diff --name-only origin/main...HEAD` НЕ содержит `src/**`,
|
||||
`.openclaw/**`, `tests/test_resolve_agent_*` — PR эти файлы не трогает (pre-existing средовой
|
||||
эффект; авторитетен CI с чистой средой). С учётом контрольного прогона **эффективный регресс —
|
||||
полностью зелёный**.
|
||||
|
||||
### Профильные сюиты задачи
|
||||
| Модуль | Результат |
|
||||
|--------|-----------|
|
||||
| `tests/test_onboarding_kit.py` | **60/60 PASSED** |
|
||||
| `tests/test_onboarding_script.py` | **18/18 PASSED** |
|
||||
| `tests/test_onboarding_invariants.py` | **5/5 PASSED** |
|
||||
| **Итого профильных** | **83/83 PASSED** |
|
||||
|
||||
### Smoke API (read-only, прод 8500)
|
||||
| Проверка | Результат |
|
||||
|----------|-----------|
|
||||
| `GET /health` | ✅ `{"status":"ok"}` |
|
||||
| `GET /status` | ✅ активные задачи отдаются (ORCH-009 `stage=testing`, ORCH-101 `analysis`) |
|
||||
| `GET /queue` → блок `serial_gate` (ORCH-088) | ✅ **присутствует**: `enabled: true`, per-repo картина корректна (активная ORCH-009, ожидающая ORCH-101 — FIFO, заморозок нет) |
|
||||
| `GET /queue` → блок `auto_labels` (ORCH-089) | ✅ присутствует (`autoApprove`/`autoDeploy`) |
|
||||
| `GET /health` staging 8501 (контур smoke D8) | ✅ ok |
|
||||
|
||||
Регресса смока нет.
|
||||
|
||||
### Сопоставление с тест-планом (`04-test-plan.yaml`) — каждый TC
|
||||
|
||||
| TC ID | Описание (кратко) | Тест-функция(и) | Результат |
|
||||
|-------|-------------------|------------------|-----------|
|
||||
| TC-01 | Состав kit: все элементы FR-1 | `test_tc01_kit_contains_all_required_elements`, `test_tc01_kit_readme_and_placeholder_dictionary_exist` | **PASS** |
|
||||
| TC-02 | Live-копии `_templates`/`_standards`, канон не форкается | `test_tc02_materialise_live_copies_canon`, `test_kit_does_not_fork_the_canon` | **PASS** |
|
||||
| TC-03 | 5 XML-секций в нормативном порядке (×6 промптов) | `test_tc03_five_xml_sections_in_normative_order` (6 параметров) | **PASS** |
|
||||
| TC-04 | `<escalation>` у dev/reviewer/tester; «❌ → ✅» | `test_tc04_escalation_section_after_success_criteria`, `test_tc04_bans_use_cross_check_format` | **PASS** |
|
||||
| TC-05 | Директивы доки: паспорт/AGENTS/ARCHITECTURE/ADR перед работой; артефакты в work-items; CHANGELOG | `test_tc05_prompt_directs_agent_to_docs`, `test_tc05_changelog_duty_present`, `test_tc05_architect_carries_adr_rules` | **PASS** |
|
||||
| TC-06 | 6-польная схема 52c; verdict-ключи байт-в-байт; даты/модели — плейсхолдеры | `test_tc06_six_schema_fields_named`, `test_tc06_machine_verdict_keys_byte_exact`, `test_tc06_schema_pins_role_author_and_stage`, `test_tc06_dates_and_models_are_placeholders` | **PASS** |
|
||||
| TC-07 | Reviewer-gate: дока не обновлена → REQUEST_CHANGES | `test_tc07_reviewer_gate_docs_not_updated_means_request_changes` | **PASS** |
|
||||
| TC-08 | Языковая политика: 5 ru + deployer en (ADR D9) | `test_tc08_ru_canon_for_five_roles`, `test_tc08_deployer_is_english` | **PASS** |
|
||||
| TC-09 | Рендер подставляет все плейсхолдеры, неразрешённых нет | `test_tc09_render_resolves_all_placeholders`, `test_render_is_a_pure_replace`, `test_placeholder_dictionary_bijection` | **PASS** |
|
||||
| TC-10 | Нет утечек орк-специфики (ORCH-, 8500/8501, self-hosting) | `test_tc10_no_orchestrator_specific_leaks` | **PASS** |
|
||||
| TC-11 | Ссылочная целостность отрендеренного каркаса | `test_tc11_referenced_paths_exist_in_materialised_tree` | **PASS** |
|
||||
| TC-12 | Registry round-trip через фактический `_parse_projects_json`; существующие записи сохранены | `test_tc12_registry_round_trip_through_actual_parser`, `test_tc12_merge_is_idempotent_no_duplicates` | **PASS** |
|
||||
| TC-13 | План Plane: все 22 статуса `_PLANE_NAME_TO_KEY` (incl. `Confirm Deploy`, `STOP`→`cancelled`) + лейблы | `test_tc13_plan_covers_all_statuses_and_labels`, `test_state_groups_match_plane_name_to_key` | **PASS** |
|
||||
| TC-14 | CE-отказ Plane → `manual-step` со ссылкой на runbook, не молча | `test_tc14_plane_refusal_becomes_manual_step` | **PASS** |
|
||||
| TC-15 | План Gitea: репо + webhook (push/pull_request/status, HMAC вне гита) + initial push | `test_tc15_plan_contains_gitea_repo_webhook_and_push`, `test_secret_never_leaks_into_report` | **PASS** |
|
||||
| TC-16 | `plan` — чистый dry-run: ноль мутаций | `test_tc16_plan_is_a_pure_dry_run` | **PASS** |
|
||||
| TC-17 | Повторный `apply` → `skipped(exists)`, без дублей/удалений | `test_tc17_second_apply_skips_everything_existing` | **PASS** |
|
||||
| TC-18 | Нет рестартов/правки `.env`/push в существующие репо | `test_tc18_source_has_no_container_or_env_mutation_ops`, `test_tc18_fresh_apply_runs_git_only_inside_workdir` | **PASS** |
|
||||
| TC-19 | INFRA.md шаблон: обязательные секции; INFRA орка не тронут | `test_tc19_infra_template_mandatory_sections`, `test_tc19_orchestrator_own_infra_untouched_sections` | **PASS** |
|
||||
| TC-20 | Runbook: все слои в порядке, ручные шаги помечены, журнал smoke | `test_tc20_runbook_exists_and_layer_order`, `test_tc20_runbook_manual_steps_and_selfhosting_warning`, `test_tc20_runbook_verification_and_smoke_journal` | **PASS** |
|
||||
| TC-21 | Снапшоты `STAGE_TRANSITIONS`/`QG_CHECKS`; `src/**` и `.openclaw/` не тронуты | `test_tc21_stage_transitions_snapshot`, `test_tc21_qg_checks_registry_snapshot`, `test_tc21_src_never_references_onboarding`, `test_tc21_cli_src_imports_stay_in_closed_list`, `test_tc21_kit_prompts_name_only_real_gates` | **PASS** |
|
||||
| TC-22 | Полный регресс `tests/` зелёный | весь прогон: 1712 passed (+1 средовой pre-existing, с чистой средой 49/49 — см. выше) | **PASS** |
|
||||
|
||||
**22/22 TC выполнены, все PASS.**
|
||||
|
||||
### Сопоставление с критериями приёмки (`03-acceptance-criteria.md`)
|
||||
|
||||
| AC | Покрытие | Результат |
|
||||
|----|----------|-----------|
|
||||
| AC-1 (состав kit) | TC-01 | ✅ PASS |
|
||||
| AC-2 (канон 52d/92) | TC-03…TC-06 | ✅ PASS |
|
||||
| AC-3 (reviewer-gate доки) | TC-07 | ✅ PASS |
|
||||
| AC-4 (языковая политика, ADR D9) | TC-08 | ✅ PASS |
|
||||
| AC-5 (плейсхолдеры/утечки/целостность) | TC-09…TC-11 | ✅ PASS |
|
||||
| AC-6 (registry round-trip) | TC-12 | ✅ PASS |
|
||||
| AC-7 (план Plane: статусы/лейблы) | TC-13, TC-14 | ✅ PASS |
|
||||
| AC-8 (план Gitea + dry-run без мутаций) | TC-15, TC-16 | ✅ PASS |
|
||||
| AC-9 (идемпотентность/безопасность apply) | TC-17, TC-18 | ✅ PASS |
|
||||
| AC-10 (INFRA.md шаблон) | TC-19 | ✅ PASS |
|
||||
| AC-11 (runbook полон) | TC-20 | ✅ PASS |
|
||||
| AC-12 (инварианты `src/**`) | TC-21, TC-22 + diff-проверка (`origin/main...HEAD`: `src/**`, `.openclaw/**` — пусто) | ✅ PASS |
|
||||
| AC-13 (операторский smoke, ADR D8) | вне pytest-скоупа (по `04-test-plan.yaml`: «выполняется вручную и протоколируется») | ⚠️ **NOT RUN — открытый операторский шаг** (см. ниже) |
|
||||
|
||||
### ⚠️ AC-13 — открытый ОБЯЗАТЕЛЬНЫЙ операторский шаг (ADR-001 D8)
|
||||
|
||||
«Журнал smoke-прогонов» в `docs/operations/ONBOARDING.md` (§ строка 186) на момент отчёта
|
||||
содержит **плейсхолдер** — операторский smoke на песочнице (runbook §5.2: онбординг sandbox
|
||||
`onboarding-smoke`/`SMK` → регистрация в `.env.staging` → рестарт staging → тестовая задача →
|
||||
стадия analysis) **не выполнен и не запротоколирован**.
|
||||
|
||||
- Прогон по построению мутирующий (создание сущностей Plane/Gitea, правка `.env.staging`,
|
||||
рестарт staging-контейнера) и в `04-test-plan.yaml`/AC-13 явно классифицирован как **ручной
|
||||
операторский** — он вне полномочий tester-агента (read-only smoke) и не покрывается ни одним
|
||||
TC; дефекта кода нет, поэтому `FAIL`/откат на development не обоснован.
|
||||
- Контур smoke готов: staging 8501 жив (health ok), `verify`-режим CLI и runbook протестированы
|
||||
структурно (TC-13…TC-20).
|
||||
- **Эскалация оператору:** по D8 первый протокол в «Журнале smoke-прогонов» **обязателен для
|
||||
приёмки ORCH-009** — выполнить прогон по runbook §5.2 и заполнить журнал **ДО прод-деплоя**
|
||||
(гейт `Confirm Deploy` — человеческий, точка контроля сохраняется). Ссылка по требованию D8:
|
||||
`docs/operations/ONBOARDING.md` § «Журнал smoke-прогонов».
|
||||
|
||||
## Вывод pytest
|
||||
|
||||
```
|
||||
$ cd /repos/_wt/orchestrator/feature_ORCH-009-turnkey-plane && pytest tests/ -v --tb=short
|
||||
...
|
||||
tests/test_onboarding_invariants.py — 5 PASSED
|
||||
tests/test_onboarding_kit.py — 60 PASSED
|
||||
tests/test_onboarding_script.py — 18 PASSED
|
||||
...
|
||||
=================================== FAILURES ===================================
|
||||
______________________ test_flags_present_when_configured ______________________
|
||||
tests/test_resolve_agent_effort.py:190: in test_flags_present_when_configured
|
||||
assert "--model claude-opus-4-8 " in flags
|
||||
E AssertionError: assert '--model claude-opus-4-8 ' in
|
||||
'--model claude-fable-5 --effort xhigh --fallback-model claude-sonnet-4-6 '
|
||||
=========================== short test summary info ============================
|
||||
FAILED tests/test_resolve_agent_effort.py::test_flags_present_when_configured
|
||||
============= 1 failed, 1712 passed, 1 warning in 69.90s (0:01:09) =============
|
||||
|
||||
# Контрольный перепрогон средового падения с чистой средой (handoff reviewer):
|
||||
$ env -u ORCH_AGENT_* pytest tests/test_resolve_agent_effort.py tests/test_resolve_agent_model.py -q
|
||||
49 passed, 1 warning in 0.44s
|
||||
```
|
||||
|
||||
## Итог
|
||||
|
||||
**PASS.**
|
||||
- 22/22 TC тест-плана выполнены и зелёные; AC-1…AC-12 подтверждены.
|
||||
- Полный регресс эффективно зелёный (1712 passed; единственное падение — средовое pre-existing,
|
||||
с чистой средой проходит; PR `src/**`/`.openclaw/**`/файлы этих тестов не трогает).
|
||||
- Smoke API без регрессов: `/health`, `/status`, `/queue` (блоки `serial_gate` и `auto_labels`
|
||||
присутствуют); staging 8501 жив.
|
||||
- ⚠️ AC-13 (операторский smoke, D8) — **не закрыт**: обязателен к выполнению и протоколированию
|
||||
оператором до прод-деплоя (`Confirm Deploy`). Дефекта кода нет — вердикт стадии testing PASS.
|
||||
@@ -1,48 +0,0 @@
|
||||
---
|
||||
staging_status: SUCCESS
|
||||
work_item: ORCH-009
|
||||
stage: deploy-staging
|
||||
author_agent: deployer
|
||||
status: success
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-fable-5
|
||||
timestamp: 2026-06-10T13:07:10Z
|
||||
base_url: http://localhost:8501
|
||||
---
|
||||
|
||||
# Staging Gate Log
|
||||
|
||||
Staging test suite completed against the live staging environment
|
||||
(`orchestrator-staging`, 8501), run canonically inside the container
|
||||
(ORCH-048, ADR-001: `docker exec orchestrator-staging python3
|
||||
/repos/orchestrator/scripts/staging_check.py --base-url http://localhost:8501
|
||||
--mode stub`).
|
||||
|
||||
**Verdict: SUCCESS** (exit code 0).
|
||||
|
||||
## Results
|
||||
|
||||
Result: 8/10 checks PASS. All REAL (pipeline) checks are green:
|
||||
|
||||
- **Block A (SMOKE)**: A1 `/health` → 200 status=ok, A2 `/queue` → 200 with
|
||||
counts/max_concurrency/resilience (incl. `serial_gate`, `coverage`,
|
||||
`auto_labels`, `stop`, `bug_fast_track`, `lessons` blocks), A3
|
||||
`ORCH_STAGING=true` — PASS
|
||||
- **Block B (ACCESS)**: B4 Plane sandbox accessible, B5 Gitea
|
||||
`orchestrator-sandbox` accessible (push=true), B6 registry isolation
|
||||
(sandbox present, prod ET/ORCH absent) — PASS
|
||||
- **Block C (E2E, mode=stub)**: C7 create issue in Plane SANDBOX (HTTP 201),
|
||||
C8 trigger pipeline via `/webhook/plane` (HTTP 200, accepted) — PASS;
|
||||
cleanup completed (Plane issue deleted, HTTP 204)
|
||||
|
||||
REAL failed: none.
|
||||
|
||||
The two failed checks (C9a/C9b) are known sandbox-infra checks (they depend on
|
||||
SANDBOX bot accounts being project members, not on the pipeline) and were
|
||||
waived per ORCH-061 (`staging_infra_tolerance_enabled=True`); the script still
|
||||
exited 0 fail-closed because every REAL check is green.
|
||||
|
||||
```
|
||||
INFRA-WAIVED: C9a Branch appears in orchestrator-sandbox, C9b Analyst job enqueued in staging queue (known sandbox-infra; real checks green)
|
||||
VERDICT: SUCCESS (exit 0) — SUCCESS (infra-waived): ['C9a Branch appears in orchestrator-sandbox', 'C9b Analyst job enqueued in staging queue'] are known sandbox-infra checks; all real checks green
|
||||
```
|
||||
@@ -1,7 +0,0 @@
|
||||
# Business Request: Режим багфиксинга: упрощённый/дешёвый трек для багов (не полный цикл)
|
||||
|
||||
Work Item ID: ORCH-019
|
||||
|
||||
## Description
|
||||
|
||||
TBD
|
||||
@@ -1,178 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-019
|
||||
stage: analysis
|
||||
author_agent: analyst
|
||||
status: ready-for-review
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# 01 — BRD (бизнес-требования): ORCH-019 — Режим багфиксинга (упрощённый/дешёвый трек для багов)
|
||||
|
||||
Work Item: **ORCH-019** · Repo: **orchestrator** (self-hosting) · Стадия: analysis
|
||||
Заказчик: Слава · Тип: фича (новый режим конвейера, опциональный, под флагом)
|
||||
|
||||
> ⚠️ **Принцип, заданный Владельцем (нерушимый):** упрощаем **аналитику**, но **НЕ ослабляем
|
||||
> качество**. Гейты CI / review / tester verdict / deploy verdict **остаются**. Горький урок
|
||||
> ET-8 / BUG-TESTS-SUBSTRING: срезанная *проверка* = недоделка на проде. «Дешевле ≠
|
||||
> бесконтрольнее». Этот принцип — корневой инвариант всей задачи (см. NFR-1, BR-6).
|
||||
|
||||
---
|
||||
|
||||
## 1. Бизнес-контекст и проблема
|
||||
|
||||
### 1.1. Цель
|
||||
Дать оркестратору **отдельный удешевлённый трек для багфиксов**. Сейчас любой баг (пример:
|
||||
зашёл на карту enduro-trails, увидел дефект, завёл задачу) идёт по **полному** конвейеру
|
||||
`analysis → architecture → development → review → testing → deploy-staging → deploy`. Для мелкой
|
||||
правки полный цикл **избыточен**: лишние стадии (полный BRD/TRZ/AC + архитектурный ADR) тратят
|
||||
токены и время, не добавляя ценности на однострочном фиксе.
|
||||
|
||||
### 1.2. Установленные факты (проверено по коду, не изобретать)
|
||||
- **Точка входа задачи в конвейер:** `src/webhooks/plane.py::start_pipeline` создаёт task-row
|
||||
с **жёстко зашитой** начальной стадией `"analysis"` (`create_task_atomic(..., "analysis", ...)`)
|
||||
и режет ветку (`_create_gitea_branch`). Это единственная точка, где задаётся точка входа.
|
||||
- **Маршрутизация стадий полностью управляется** `src/stages.py::STAGE_TRANSITIONS` через
|
||||
`get_next_stage` — `advance_stage` (`src/stage_engine.py`) не содержит «зашитого» порядка стадий,
|
||||
он спрашивает `get_next_stage`. → Изменение точки входа / маршрута локализуемо, машину стадий
|
||||
ломать не нужно.
|
||||
- **Метка задачи уже читается из Plane** аппаратом ORCH-089: `src/labels.py::has_label` +
|
||||
`plane_sync.fetch_issue_labels` / `get_project_labels` (TTL-кэш, нормализация имени, never-raise,
|
||||
fail-safe → False). Источник истины — Plane API, **не** payload вебхука (`type`/`priority` в
|
||||
payload отсутствуют). Это готовый, проверенный шаблон классификации задачи.
|
||||
- **Все Quality Gate'ы читают вердикт из артефактов**, а не из стадии входа: `check_ci_green`,
|
||||
`check_reviewer_verdict` (`12-review.md`), `check_tests_passed` (`13-test-report.md`),
|
||||
`check_staging_status`, `check_deploy_status`, под-гейты security/merge/coverage/image-freshness.
|
||||
Они **не зависят** от того, прошла ли задача `analysis`/`architecture`, → их можно сохранить
|
||||
нетронутыми при срезанном «входе».
|
||||
- **Coverage-гейт (ORCH-027)** уже структурно ловит «код без тестов» на ребре
|
||||
`deploy-staging → deploy` — союзник принципа «баг фиксируется тестом».
|
||||
- **Прецедент стоимости:** UI z-index баг ET-9/ET-014 прошёл **полный** цикл ~35 мин — типичный
|
||||
кандидат на удешевление.
|
||||
|
||||
### 1.3. Связки и разграничение
|
||||
- **ORCH-13 (роутинг моделей):** «дешёвая модель на багфиксе» (Вариант 4 постановки) —
|
||||
**вне объёма** ORCH-019, отдельная задача; ORCH-019 лишь оставляет точку композиции
|
||||
(флаг bug-track наблюдаем, по нему ORCH-13 позже может выбрать модель). См. §2.2.
|
||||
- **ORCH-088 (serial gate) / ORCH-089 (auto-label):** ORCH-019 **сосуществует** с ними и
|
||||
переиспользует их аппарат (label-чтение, per-repo flag, claim-gate); не конфликтует.
|
||||
- **ORCH-12 / ORCH-14 (UX) / ET-9 (визуальные баги):** часть багов визуальные и может требовать
|
||||
мини-макета — для таких случаев предусмотрен механизм **эскалации обратно в полный цикл**
|
||||
(BR-5), а не слепое удешевление.
|
||||
- **ORCH-8 (петля уроков):** баг, найденный на проде, — сигнал петли уроков; ORCH-019 этого не
|
||||
меняет (post-deploy-телеметрия ORCH-021 сохраняется).
|
||||
|
||||
---
|
||||
|
||||
## 2. Объём (scope)
|
||||
|
||||
### 2.1. В объёме
|
||||
- **BR-1 — Классификация «баг».** Задача распознаётся как баг по **метке Plane** (рекоменд. имя
|
||||
`Bug`), читаемой аппаратом ORCH-089. Операторская, детерминированная, обратимая разметка.
|
||||
- **BR-2 — Упрощённый трек.** Багфикс-задача идёт по **укороченному** пути: пропускается
|
||||
**тяжёлая аналитика и стадия `architecture`** (полный BRD/TRZ/AC/ADR не требуются); вместо них —
|
||||
**минимальный набор артефактов** (короткий bug-report + обязательный план регресс-теста).
|
||||
- **BR-3 — Гейты качества сохраняются ПОЛНОСТЬЮ.** CI (`check_ci_green`), review
|
||||
(`check_reviewer_verdict`), testing (`check_tests_passed`), staging/deploy-вердикты и под-гейты
|
||||
(security/merge/coverage/image-freshness) исполняются **без изменений** на багфикс-треке.
|
||||
- **BR-4 — Обязательный регресс-тест.** Багфикс **обязан** зафиксировать дефект тестом (тест,
|
||||
падающий до фикса и зелёный после) — главный предохранитель от рецидива (урок ET-8).
|
||||
- **BR-5 — Эскалация в полный цикл.** Если баг оказался сложным/архитектурным или визуальным
|
||||
(нужен макет), он **возвращается** в полный цикл; багфикс-трек не «застревает» на сложном.
|
||||
- **BR-6 — Безопасность по умолчанию (fail-safe → полный цикл).** Любая неоднозначность/ошибка
|
||||
чтения метки/выключенный флаг → задача идёт **полным** циклом (никогда не «теряет» стадии молча).
|
||||
- **BR-7 — Наблюдаемость стоимости.** Виден факт «задача на багфикс-треке» и метрика экономии
|
||||
(стадии/agent-runs/токены/время) относительно полного цикла.
|
||||
|
||||
### 2.2. Вне объёма (явно не делать)
|
||||
- **Роутинг моделей (ORCH-13 / Вариант 4):** выбор дешёвой модели на багфиксе — отдельная задача.
|
||||
- **Авто-триаж сложности аналитиком (полный Вариант 3):** автоматическая classification
|
||||
`trivial/small/complex` LLM-аналитиком — будущее развитие; v1 опирается на явную метку оператора
|
||||
+ ручную/мини-эскалацию (BR-5), не на ML-классификатор.
|
||||
- **Изменение `STAGE_TRANSITIONS` (новые стадии), реестра `QG_CHECKS`, семантики любого `check_*`,
|
||||
вердикт-ключей** (`verdict:`/`result:`/`deploy_status:`/`staging_status:`/`security_status:`/
|
||||
`coverage_status:`).
|
||||
- **Параллелизм багфиксов**, изменение `max_concurrency`, merge-очередь.
|
||||
- **Полный отказ от стадии `analysis`** (вариант «hotfix → сразу development») как дефолт — см.
|
||||
§6 (требуется минимальный аналитический проход ради регресс-теста и трассируемости). Чистый
|
||||
hotfix без аналитики оставлен как возможная опция архитектора, но не дефолт.
|
||||
|
||||
---
|
||||
|
||||
## 3. Заинтересованные стороны
|
||||
- **Владелец/оператор (Слава):** ставит метку `Bug`, получает быстрый дешёвый фикс, эскалирует
|
||||
сложный баг, читает метрику экономии.
|
||||
- **Self-hosting прод (`orchestrator`) и enduro-trails:** общий инстанс/БД/очередь — режим обязан
|
||||
быть аддитивным, под флагом, per-repo, с нулевой регрессией при выключении (FR-условие).
|
||||
- **Агенты конвейера (analyst/developer/reviewer/tester):** работают по тем же контрактам; на
|
||||
багфикс-треке analyst выдаёт облегчённый пакет, остальные — как обычно.
|
||||
|
||||
---
|
||||
|
||||
## 4. Бизнес-требования (BR) — сводная таблица
|
||||
|
||||
| ID | Требование | Связь |
|
||||
|----|------------|-------|
|
||||
| BR-1 | Задача распознаётся как баг по метке Plane (`Bug`), читаемой через аппарат ORCH-089 (`labels.has_label` + `plane_sync.fetch_issue_labels`). Источник истины — Plane API, не payload. | FR-1, AC-1 |
|
||||
| BR-2 | Багфикс-задача пропускает тяжёлую аналитику и стадию `architecture`; маршрут `analysis(lite) → development → review → testing → deploy-staging → deploy`. Полный BRD/TRZ/AC/ADR не обязателен. | FR-2, AC-2 |
|
||||
| BR-3 | Все Quality Gate'ы (CI/review/tester/staging/deploy + под-гейты security/merge/coverage/image-freshness) исполняются на багфикс-треке **без изменений**. | FR-3, AC-3 |
|
||||
| BR-4 | Багфикс обязан содержать **регресс-тест** (падает до фикса, зелён после); отсутствие нового/изменённого теста на исправление — повод для REQUEST_CHANGES reviewer'ом. | FR-3/FR-4, AC-4 |
|
||||
| BR-5 | Существует механизм **эскалации** багфикса в полный цикл (сложный/архитектурный/визуальный баг) — задача возвращается на полную аналитику/архитектуру. | FR-5, AC-5 |
|
||||
| BR-6 | **Fail-safe:** при выключенном флаге, ошибке/неоднозначности чтения метки, неприменимом репо — задача идёт **полным** циклом (никогда не теряет стадии молча). never-raise. | FR-6, AC-6 |
|
||||
| BR-7 | Факт багфикс-трека и метрика экономии (пропущенные стадии / Σ agent-runs / токены / время vs полный цикл) наблюдаемы (`GET /queue` блок + лог/Telegram-карточка). | FR-7, AC-7 |
|
||||
| BR-8 | Поведение управляется kill-switch'ом и областью репо (как ORCH-35/43/58/88/89): выключение флага → строго прежнее поведение (нулевая регрессия для enduro и для orchestrator). | NFR-2, AC-6 |
|
||||
|
||||
---
|
||||
|
||||
## 5. Нефункциональные требования (NFR)
|
||||
|
||||
| ID | Требование |
|
||||
|----|------------|
|
||||
| NFR-1 | **Качество не ослабляется (корневой инвариант).** Срезается только *аналитика/архитектура*; ни один Quality Gate, exit-код deploy-хука, под-гейт безопасности/покрытия — не ослаблен и не пропущен. |
|
||||
| NFR-2 | **Нулевая регрессия / аддитивность.** При `bug_fast_track_enabled=False` или неприменимом репо путь старта и маршрут идентичны текущим. `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/вердикт-ключи/схема БД — не меняются (допустима лишь аддитивная идемпотентная миграция, если архитектор сочтёт нужным помечать тип задачи в БД). |
|
||||
| NFR-3 | **never-raise / fail-safe.** Любая ошибка классификации/маршрутизации → деградация на полный цикл, не падение вебхука/конвейера (по образцу `labels.py`/`serial_gate.py`). |
|
||||
| NFR-4 | **Offline-устойчивость горячего пути.** Классификация может ходить в Plane API только в момент `start_pipeline` (как ORCH-089), но **не** в горячем `claim_next_job` (иначе встанет очередь всех проектов). |
|
||||
| NFR-5 | **Per-repo область.** Режим включается по CSV-области репо; orchestrator и enduro управляются независимо. |
|
||||
| NFR-6 | **Self-hosting безопасность.** Механизм не рестартит/не роняет прод-контейнер, не пушит/force-push в `main`. |
|
||||
| NFR-7 | **Композируемость.** Корректно сосуществует с serial-gate (ORCH-088), auto-label (ORCH-089), coverage-gate (ORCH-027), merge-gate (ORCH-043). |
|
||||
|
||||
---
|
||||
|
||||
## 6. Допущения и ограничения
|
||||
- **Минимальный аналитический проход сохраняется** (а не «hotfix → сразу dev»): ради (а)
|
||||
фиксации регресс-теста как контракта приёмки (BR-4), (б) трассируемости (минимальный bug-report).
|
||||
Полный отказ от `analysis` для багов оставлен архитектору как опция, но дефолт — мини-анализ.
|
||||
Обоснование: урок ET-8 — именно отсутствие явного теста-фиксатора привело к «недоделка в Done».
|
||||
- **Классификация v1 — явная метка оператора**, не LLM-авто-триаж (Вариант 3 в полном объёме —
|
||||
будущее). Метка `Bug` должна существовать в Plane-проекте; её отсутствие = fail-safe полный цикл.
|
||||
- **Эскалация v1** — допускает как минимум ручной путь (снять метку `Bug` / вернуть стадию) и/или
|
||||
решение мини-аналитика «баг сложный → не фаст-трекать». Конкретный механизм — архитектору.
|
||||
- **Стоимость измеряется относительно**: метрика «во сколько раз дешевле» считается по факту из
|
||||
существующей телеметрии `agent_runs` (стадии/токены/время), без новой тяжёлой инфраструктуры.
|
||||
|
||||
---
|
||||
|
||||
## 7. Критерии успеха (резюме; детали — `03-acceptance-criteria.md`)
|
||||
- AC-1 — задача с меткой `Bug` распознаётся и помечается как багфикс-трек.
|
||||
- AC-2 — багфикс-задача проходит конвейер, пропустив стадию `architecture` (и тяжёлый BRD/TRZ/AC).
|
||||
- AC-3 — все Quality Gate'ы исполнены на багфикс-треке (CI/review/tester/staging/deploy + под-гейты).
|
||||
- AC-4 — багфикс содержит регресс-тест; его отсутствие даёт REQUEST_CHANGES.
|
||||
- AC-5 — сложный/визуальный баг эскалируется в полный цикл.
|
||||
- AC-6 — при выключенном флаге / ошибке / неприменимом репо — поведение строго прежнее (полный цикл).
|
||||
- AC-7 — факт багфикс-трека и метрика экономии наблюдаемы.
|
||||
|
||||
---
|
||||
|
||||
## 8. Риски (детали — `10-tech-risks.md`, заполняет архитектор)
|
||||
- R-1: **Срезали лишнее.** Ошибочный пропуск гейта качества → недоделка на проде (ET-8). Митигатор —
|
||||
NFR-1: режется только аналитика/архитектура, гейты структурно нетронуты + тест AC-3.
|
||||
- R-2: **Сложный баг под меткой `Bug`** уходит на фаст-трек и упирается в отсутствие архитектуры →
|
||||
нужна эскалация (BR-5) и/или решение мини-аналитика.
|
||||
- R-3: **Регресс-тест не написан** (developer «забыл») → рецидив бага. Митигатор — BR-4 + reviewer-ось
|
||||
+ союзник coverage-gate (ORCH-027).
|
||||
- R-4: **Fail-safe инвертирован** (ошибка → молча срезали стадии) → недоделка. Митигатор — NFR-3
|
||||
fail-safe строго в сторону полного цикла + тест AC-6.
|
||||
- R-5: **Конфликт с serial-gate/auto-label** при изменённой точке входа. Митигатор — NFR-7 +
|
||||
интеграционный тест композиции.
|
||||
</content>
|
||||
</invoke>
|
||||
@@ -1,207 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-019
|
||||
stage: analysis
|
||||
author_agent: analyst
|
||||
status: ready-for-review
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# 02 — ТЗ (TRZ): ORCH-019 — Режим багфиксинга (упрощённый/дешёвый трек для багов)
|
||||
|
||||
Work Item: **ORCH-019** · Repo: **orchestrator** · Стадия: analysis
|
||||
|
||||
> ТЗ описывает **что** должно измениться и **где** (модули/контракты/артефакты), выведенное из BRD
|
||||
> и фактического кода. **Как** (точная схема: где именно ветвить маршрут, хранить ли тип задачи в
|
||||
> БД, отдельный leaf-модуль или расширение `labels.py`) — решает архитектор в `06-adr/`. ТЗ
|
||||
> фиксирует требования и границы, архитектурное решение не предлагает.
|
||||
|
||||
> ⚠️ **Корневой инвариант (NFR-1 BRD):** срезается ТОЛЬКО аналитика/архитектура. Любой Quality Gate,
|
||||
> exit-код deploy-хука, под-гейт безопасности/покрытия — байт-в-байт прежние.
|
||||
|
||||
---
|
||||
|
||||
## 1. Сводка изменения
|
||||
Ввести **опциональный багфикс-трек**: задача, помеченная в Plane меткой `Bug`, проходит конвейер по
|
||||
**укороченному маршруту** — пропускается стадия `architecture` и тяжёлая аналитика (полный
|
||||
BRD/TRZ/AC/ADR заменяются минимальным bug-report + обязательным планом регресс-теста). Все
|
||||
Quality Gate'ы (CI/review/tester/staging/deploy + под-гейты security/merge/coverage/image-freshness)
|
||||
исполняются **без изменений**. Распознавание бага и маршрут — аддитивно, под kill-switch, с областью
|
||||
репо, never-raise, fail-safe → полный цикл. `STAGE_TRANSITIONS` и реестр `QG_CHECKS` структурно не
|
||||
меняются.
|
||||
|
||||
---
|
||||
|
||||
## 2. Задействованные модули / пути
|
||||
|
||||
| Путь | Роль в задаче | Характер изменения |
|
||||
|------|---------------|--------------------|
|
||||
| `src/labels.py` | аппарат чтения метки Plane (ORCH-089: `has_label`, `*_applies`) | переиспользовать; **добавить** `is_bug_task(work_item_id, project_id) -> bool` + `bug_fast_track_applies(repo) -> bool` (по образцу `auto_approve_applies`), либо вынести в новый leaf `src/bug_fast_track.py` (never-raise) — выбор архитектора |
|
||||
| `src/plane_sync.py` | `fetch_issue_labels` / `get_project_labels` / `_normalize_label` | **без изменений** — переиспользуются для чтения метки `Bug` (источник истины — Plane API) |
|
||||
| `src/webhooks/plane.py` | `start_pipeline` (создаёт task-row со стадией `"analysis"`, режет ветку `_create_gitea_branch`), `handle_status_start`, `handle_issue_updated` | **ключевая врезка:** перед `create_task_atomic(...)` определить тип задачи и (при багфикс-треке) пометить задачу багом / задать укороченный маршрут. Внешний контракт вебхука Plane не меняется |
|
||||
| `src/stages.py` | `STAGE_TRANSITIONS`, `get_next_stage` | **структура `STAGE_TRANSITIONS` не меняется** (новых стадий нет). Требование: маршрут багфикса = `analysis → development` (пропуск `architecture`). Механизм (условный `get_next_stage` по типу задачи / bug-mode-флаг на task) — архитектору |
|
||||
| `src/stage_engine.py` | `advance_stage`, `_run_qg`, `_handle_analysis_approved_flow`, откаты | `advance_stage` уже маршрутизирует через `get_next_stage` (не зашивает порядок) → при условной маршрутизации правка точечная. Гейты диспетчеризуются как раньше |
|
||||
| `src/db.py` | `create_task_atomic(plane_id, work_item_id, repo, branch, stage, title)`, схема `tasks`, `claim_next_job` | если архитектор решит хранить «тип=bug» в БД — **аддитивная идемпотентная** колонка (`_ensure_column`, напр. `tasks.track TEXT DEFAULT 'full'`); горячий `claim_next_job` **не** должен ходить в сеть (NFR-4) |
|
||||
| `src/config.py` | флаги фичи | новые: `bug_fast_track_enabled`, `bug_fast_track_label`, `bug_fast_track_repos` (CSV) + helper `applies(repo)` по образцу `auto_label_*` / `serial_gate_*` |
|
||||
| `src/qg/checks.py` | реестр `QG_CHECKS` и `check_*` | **без изменений** (инвариант NFR-1) |
|
||||
| `src/serial_gate.py`, `src/coverage_gate.py`, `src/merge_gate.py` | композиция | **без изменений**; проверить совместимость (NFR-7) интеграционным тестом |
|
||||
| `src/main.py` | `GET /queue` | **аддитивный** read-only блок `bug_fast_track` (флаг/область/счётчики/метрика экономии) |
|
||||
| `src/notifications.py` | live-карточка | опционально — отметка «🐞 багфикс-трек» в карточке (never-raise) |
|
||||
| `.openclaw/agents/analyst.md` | промпт мини-аналитика | при багфикс-треке выдавать **облегчённый** пакет (bug-report + регресс-тест-план), не полный BRD/TRZ/AC. Канон промптов 52d не нарушать |
|
||||
| `.openclaw/agents/reviewer.md` | ось контроля | добавить ось «багфикс без регресс-теста → REQUEST_CHANGES» (BR-4) — нормативно-описательно, не машинный гейт |
|
||||
|
||||
---
|
||||
|
||||
## 3. Функциональные требования
|
||||
|
||||
### FR-1 — Классификация задачи как «баг» (BR-1)
|
||||
- Багфикс-трек активируется, если issue несёт метку Plane с именем `bug_fast_track_label`
|
||||
(дефолт `Bug`), прочитанную через `labels.has_label(work_item_id, label, project_id)` (ORCH-089:
|
||||
`fetch_issue_labels` + `get_project_labels`, нормализация `_normalize_label`, TTL-кэш).
|
||||
- **Источник истины — Plane API**, не payload вебхука (поле `type` в payload отсутствует).
|
||||
- Чтение метки допускается **только** в `start_pipeline` (момент старта, сетевой вызов приемлем,
|
||||
как ORCH-089) — **не** в горячем `claim_next_job` (NFR-4).
|
||||
- `applies(repo)` (локальный, без сети) проверяется **первым**; `has_label` (сеть) — только при
|
||||
`applies==True` → при выключенном флаге нулевой сетевой оверхед (образец ORCH-089).
|
||||
|
||||
### FR-2 — Укороченный маршрут (BR-2)
|
||||
- Для багфикс-задачи маршрут конвейера: `analysis(lite) → development → review → testing →
|
||||
deploy-staging → deploy → done`, т.е. **пропускается стадия `architecture`** (и её exit-гейт
|
||||
`check_architecture_done` / требование `06-adr/`).
|
||||
- `STAGE_TRANSITIONS` **не изменяется структурно**. Требуемый инвариант результата: при выходе
|
||||
багфикс-задачи из `analysis` следующая стадия = `development` (а не `architecture`); для
|
||||
не-багфикс задач — прежняя `architecture`. Конкретный механизм (условный `get_next_stage(stage,
|
||||
task)` / bug-mode-флаг на task / точка входа сразу в `development`) — решение архитектора.
|
||||
- Тяжёлая аналитика облегчается: на багфикс-треке обязательны лишь `01-brd.md` (короткий
|
||||
bug-report: симптом, шаги воспроизведения, локализация, причина) и `04-test-plan.yaml` (план
|
||||
регресс-теста). Полные `02-trz.md`/`03-acceptance-criteria.md` и `06-adr/` — **не обязательны**.
|
||||
(Совместимость с `check_analysis_complete`, требующим `01/02/03/04` — см. FR-6.)
|
||||
|
||||
### FR-3 — Гейты качества сохраняются полностью (BR-3, корневой инвариант)
|
||||
- На багфикс-треке исполняются **без изменений**: `check_ci_green` (development→review),
|
||||
`check_reviewer_verdict` (review→testing, `12-review.md`), `check_tests_passed` (testing→
|
||||
deploy-staging, `13-test-report.md`), `check_staging_status`, `check_deploy_status`, под-гейты
|
||||
ребра `deploy-staging→deploy` (security ORCH-022 → merge ORCH-043 → coverage ORCH-027 →
|
||||
image-freshness ORCH-058) и merge-verify ребра `deploy→done` (ORCH-071/073).
|
||||
- Ни один `check_*`, его сигнатура, вердикт-ключ или порядок под-гейтов **не меняется**.
|
||||
|
||||
### FR-4 — Обязательный регресс-тест (BR-4)
|
||||
- Багфикс **обязан** содержать новый/изменённый тест, воспроизводящий дефект (красный до фикса,
|
||||
зелёный после). Требование закрепляется: (а) в `04-test-plan.yaml` багфикса как обязательный TC;
|
||||
(б) reviewer-осью (`.openclaw/agents/reviewer.md`): «исправление кода без теста-фиксатора →
|
||||
finding ≥P1 / REQUEST_CHANGES»; (в) усиливается coverage-гейтом ORCH-027 (структурно ловит «код
|
||||
без тестов»). Это требование, не новый машинный гейт.
|
||||
|
||||
### FR-5 — Эскалация в полный цикл (BR-5)
|
||||
- Багфикс-задача должна иметь путь возврата в полный цикл, если баг оказался сложным/архитектурным
|
||||
или визуальным (нужен макет — связка ORCH-12/14, прецедент ET-9). Минимум v1: ручная эскалация
|
||||
(оператор снимает метку `Bug` / переводит стадию) **и/или** решение мини-аналитика «баг сложный →
|
||||
не фаст-трекать» (тогда задача идёт штатным маршрутом с `architecture`). Конкретный механизм и
|
||||
его автоматизация — архитектору; v1 не обязан включать LLM-авто-триаж сложности.
|
||||
|
||||
### FR-6 — Fail-safe → полный цикл (BR-6, NFR-3)
|
||||
- При `bug_fast_track_enabled=False`, неприменимом репо, ошибке/таймауте/неоднозначности чтения
|
||||
метки (`has_label` → False / `None`-labels), отсутствии метки `Bug` в проекте — задача идёт
|
||||
**полным** циклом (точка входа `analysis`, маршрут с `architecture`). never-raise: ошибка логики
|
||||
не роняет `start_pipeline`/вебхук.
|
||||
- **Совместимость с `check_analysis_complete`** (требует наличие `01/02/03/04`): при облегчённом
|
||||
пакете багфикса гейт не должен ложно блокировать. Варианты (архитектору): мини-аналитик всё равно
|
||||
эмитит заглушки `02/03` ИЛИ гейт `check_analysis_approved` на багфикс-треке учитывает облегчённый
|
||||
набор. Требование: **не ослабить** проверку для не-баг задач и **не заблокировать ложно** баг.
|
||||
|
||||
### FR-7 — Наблюдаемость стоимости (BR-7)
|
||||
- Факт «задача на багфикс-треке» и метрика экономии видны: (а) аддитивный блок `bug_fast_track` в
|
||||
`GET /queue` (флаг/область + счётчик задач на треке + агрегат сэкономленных стадий/agent-runs);
|
||||
(б) лог-строка на решение о маршруте; (в) опц. отметка в Telegram-карточке. Метрика «во сколько
|
||||
дешевле» считается из существующей телеметрии `agent_runs` (Σ токены/время багфикс-трека vs
|
||||
средний полный цикл) — без новой тяжёлой инфраструктуры.
|
||||
|
||||
---
|
||||
|
||||
## 4. Изменения API
|
||||
|
||||
### 4.1. Новые публичные endpoint'ы
|
||||
- **Не требуются обязательно.** (Эскалация и классификация идут через Plane-метки/статусы, не через
|
||||
новый HTTP-эндпоинт. Если архитектор вводит админ-эндпоинт принудительной (де)классификации —
|
||||
описать в ADR и обновить таблицу API в README.)
|
||||
|
||||
### 4.2. Изменяемые endpoint'ы
|
||||
- `GET /queue` — **аддитивно** добавляется блок `bug_fast_track` (read-only, never-raise) по образцу
|
||||
блоков `serial_gate` / `auto_labels` / `coverage`: `enabled`, `repos`, `label`, перечень/счётчик
|
||||
задач на багфикс-треке, агрегатная метрика экономии. Существующие ключи `GET /queue` не меняются.
|
||||
|
||||
### 4.3. Webhook-обработчики
|
||||
- `start_pipeline` (`webhooks/plane.py`): добавляется ветвление «issue имеет метку `Bug` и
|
||||
`applies(repo)` → багфикс-трек (пометить задачу / задать укороченный вход-маршрут)». Внешний
|
||||
контракт вебхука Plane не меняется.
|
||||
|
||||
---
|
||||
|
||||
## 5. Изменения схемы БД
|
||||
> Только **аддитивные, идемпотентные** миграции (общая прод-БД; enduro не трогать).
|
||||
|
||||
- **Опционально (выбор архитектора):** если тип задачи нужно знать после старта (для маршрутизации
|
||||
в `advance_stage`/`get_next_stage` и для метрики), ввести аддитивную колонку
|
||||
`tasks.track TEXT DEFAULT 'full'` (значения `full` | `bug`) через `_ensure_column` (паттерн
|
||||
`tasks.cancelled_at` ORCH-090). Тогда горячий `claim_next_job` читает тип из БД, **не** из сети
|
||||
(NFR-4). Альтернатива без колонки (вывести тип повторным чтением метки) допустима, но повторный
|
||||
сетевой вызов в горячем пути запрещён (NFR-4) → колонка предпочтительнее.
|
||||
- **Существующие** `tasks`-контракт (прочие колонки), `jobs`, `job_deps`, `agent_runs`,
|
||||
`coverage_baseline`, `repo_freeze` — **без изменений**.
|
||||
|
||||
---
|
||||
|
||||
## 6. Требования к новым/изменённым QG checks
|
||||
- **Новых QG-проверок не вводить; ни один `check_*` не менять семантически** (NFR-1). Маршрутизация
|
||||
багфикса — свойство планировщика/точки входа, **не** Quality Gate.
|
||||
- Единственная допустимая тонкая правка — обеспечить, чтобы exit-гейт стадии `analysis`
|
||||
(`check_analysis_approved` / helper `check_analysis_complete`) **не блокировал ложно** облегчённый
|
||||
багфикс-пакет, **не ослабляя** проверку для полного цикла (FR-6). Если для этого требуется правка
|
||||
`check_*` — она должна сохранить вердикт-семантику для не-баг задач байт-в-байт.
|
||||
|
||||
---
|
||||
|
||||
## 7. Совместимость / регресс
|
||||
- **Kill-switch** `bug_fast_track_enabled` (env `ORCH_BUG_FAST_TRACK_ENABLED`); `False` → точка входа
|
||||
и маршрут строго прежние (`analysis → architecture → …`), нулевая регрессия (NFR-2).
|
||||
- **Область репо** `bug_fast_track_repos` (CSV; пусто → рекомендуется self-hosting + явно
|
||||
разрешённые проекты, где есть метка `Bug` — решение об области по умолчанию фиксирует архитектор).
|
||||
- **`applies(repo)` первым** (локально, без сети) → выключенный флаг = нулевой сетевой оверхед,
|
||||
enduro не затронут.
|
||||
- **Композиция (NFR-7):** не конфликтует с serial-gate (ORCH-088: багфикс-задача — обычная задача
|
||||
репо, учитывается в serial-очереди), auto-label (ORCH-089: `autoApprove`/`autoDeploy` работают и
|
||||
на багфикс-треке), coverage-gate (ORCH-027: союзник BR-4), merge-gate (ORCH-043).
|
||||
- **never-raise / fail-safe** (NFR-3): ошибка классификации/маршрута → полный цикл, не падение.
|
||||
- **Self-hosting** (NFR-6): механизм не рестартит/не роняет прод, не пушит/force-push в `main`.
|
||||
- **Маркеры трассировки** (CLAUDE.md §9): новые инварианты помечаются `ORCH-019`; правка
|
||||
маркированного кода (ORCH-088/089/027) — со сверкой их `06-adr/`.
|
||||
|
||||
---
|
||||
|
||||
## 8. Артефакты pipeline (создать/обновить в ТОМ ЖЕ PR)
|
||||
- `docs/work-items/ORCH-019/06-adr/ADR-001-<slug>.md` — решение (механизм маршрута, хранение типа,
|
||||
совместимость с `check_analysis_complete`, область по умолчанию, механизм эскалации).
|
||||
- `docs/architecture/README.md` — новый раздел «Багфикс-трек (ORCH-019)» + блок `bug_fast_track` в
|
||||
описании `GET /queue`; при новой колонке — раздел «База данных».
|
||||
- `CLAUDE.md` — краткий абзац о багфикс-режиме (правила для агентов / конвейер).
|
||||
- `CHANGELOG.md` — запись `feat:`.
|
||||
- `.openclaw/agents/analyst.md` / `reviewer.md` — облегчённый пакет багфикса + reviewer-ось
|
||||
регресс-теста (канон 52d не нарушать).
|
||||
- При новой колонке — `docs/work-items/ORCH-019/08-data-requirements.md` (заполняет архитектор).
|
||||
|
||||
---
|
||||
|
||||
## 9. Открытые вопросы для архитектора (не блокируют анализ)
|
||||
- OQ-1: Механизм пропуска `architecture` — условный `get_next_stage(stage, task)`, bug-mode-флаг на
|
||||
task, или прямой вход багфикса сразу в `development` с сохранённым мини-bug-report? (Влияет на
|
||||
§3 `stages.py`/`stage_engine.py` и на `check_analysis_complete`.)
|
||||
- OQ-2: Хранить ли тип задачи в БД (`tasks.track`) vs выводить из метки. Рекоменд. — колонка
|
||||
(NFR-4 запрещает сеть в горячем claim).
|
||||
- OQ-3: Сохранять ли мини-стадию `analysis(lite)` (рекоменд., ради регресс-теста и трассируемости)
|
||||
или допустить чистый hotfix `→ development` (вне дефолта). См. BRD §6.
|
||||
- OQ-4: Механизм эскалации (BR-5) — только ручной (снять метку/сменить стадию) или авто-сигнал
|
||||
мини-аналитика «баг сложный → полный цикл».
|
||||
- OQ-5: Область по умолчанию (пустой CSV) — self-hosting only vs все репо с меткой `Bug`.
|
||||
- OQ-6: Совместимость с `check_analysis_approved`/`check_analysis_complete` на облегчённом пакете
|
||||
(FR-6) — заглушки `02/03` vs условный учёт гейтом.
|
||||
</content>
|
||||
@@ -1,139 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-019
|
||||
stage: analysis
|
||||
author_agent: analyst
|
||||
status: ready-for-review
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# 03 — Критерии приёмки (Acceptance Criteria): ORCH-019 — Режим багфиксинга
|
||||
|
||||
Work Item: **ORCH-019** · Repo: **orchestrator** · Стадия: analysis
|
||||
|
||||
Формат: каждый критерий имеет **PASS** (что должно быть истинно для приёмки) и **FAIL** (что
|
||||
считается провалом). Reviewer/tester проверяют их буквально по файлам репозитория и тестам.
|
||||
|
||||
> ⚠️ Корневой инвариант (см. AC-3/AC-8): срезается только аналитика/архитектура; ни один Quality
|
||||
> Gate не ослаблен. Это главное условие приёмки — нарушение = безусловный FAIL всей задачи.
|
||||
|
||||
---
|
||||
|
||||
## AC-1 — Классификация задачи по метке `Bug`
|
||||
|
||||
**Условие:** issue с меткой Plane `bug_fast_track_label` (дефолт `Bug`) при включённом флаге и
|
||||
применимом репо распознаётся как багфикс-задача.
|
||||
- **PASS:** при `bug_fast_track_enabled=True` и `applies(repo)==True` для issue с меткой `Bug`
|
||||
`is_bug_task(...)` возвращает `True` (через `labels.has_label` → `plane_sync.fetch_issue_labels`);
|
||||
задача стартует на багфикс-треке. Источник метки — Plane API, не payload вебхука.
|
||||
- **FAIL:** метка `Bug` игнорируется; ИЛИ тип читается из payload вебхука; ИЛИ задача без метки
|
||||
`Bug` ошибочно попадает на багфикс-трек.
|
||||
|
||||
---
|
||||
|
||||
## AC-2 — Укороченный маршрут: пропуск стадии `architecture`
|
||||
|
||||
**Условие:** багфикс-задача проходит конвейер, минуя стадию `architecture`.
|
||||
- **PASS:** для багфикс-задачи переход из `analysis` ведёт в `development` (а не `architecture`);
|
||||
стадия `architecture` и её требование `06-adr/` для багфикса не исполняются; задача доходит до
|
||||
`done`. Маршрут не-баг задачи остаётся `analysis → architecture → development → …`.
|
||||
- **FAIL:** багфикс-задача всё равно проходит `architecture`; ИЛИ не-баг задача начинает пропускать
|
||||
`architecture`; ИЛИ `STAGE_TRANSITIONS` изменён структурно (новые/удалённые стадии).
|
||||
|
||||
---
|
||||
|
||||
## AC-3 — Все Quality Gate'ы исполнены на багфикс-треке (корневой инвариант)
|
||||
|
||||
**Условие:** на багфикс-треке исполняются все гейты качества без изменений.
|
||||
- **PASS:** для багфикс-задачи отрабатывают `check_ci_green`, `check_reviewer_verdict`
|
||||
(`12-review.md`), `check_tests_passed` (`13-test-report.md`), `check_staging_status`,
|
||||
`check_deploy_status` и под-гейты ребра `deploy-staging→deploy` (security → merge → coverage →
|
||||
image-freshness) и merge-verify ребра `deploy→done`. Реестр `QG_CHECKS`, сигнатуры `check_*`,
|
||||
вердикт-ключи (`verdict:`/`result:`/`deploy_status:`/`staging_status:`/`security_status:`/
|
||||
`coverage_status:`) и порядок под-гейтов — байт-в-байт прежние.
|
||||
- **FAIL:** хоть один гейт качества пропущен/ослаблен/изменён на багфикс-треке; ИЛИ изменён состав
|
||||
`QG_CHECKS` / имя или регистр любого вердикт-ключа / порядок под-гейтов.
|
||||
|
||||
---
|
||||
|
||||
## AC-4 — Обязательный регресс-тест
|
||||
|
||||
**Условие:** багфикс фиксирует дефект тестом.
|
||||
- **PASS:** PR багфикса содержит новый/изменённый тест, воспроизводящий исправляемый дефект
|
||||
(красный на коде до фикса, зелёный после); требование закреплено в `04-test-plan.yaml` багфикса
|
||||
и в reviewer-оси (`.openclaw/agents/reviewer.md`: фикс без теста → finding ≥P1 / REQUEST_CHANGES).
|
||||
- **FAIL:** багфикс мержится без теста-фиксатора; ИЛИ reviewer-ось отсутствует/не срабатывает; ИЛИ
|
||||
тест присутствует, но не падает на исходном (нефиксированном) коде.
|
||||
|
||||
---
|
||||
|
||||
## AC-5 — Эскалация сложного бага в полный цикл
|
||||
|
||||
**Условие:** сложный/архитектурный/визуальный баг возвращается в полный цикл.
|
||||
- **PASS:** существует и документирован путь эскалации (минимум ручной: снятие метки `Bug` /
|
||||
перевод стадии, и/или решение мини-аналитика «баг сложный → не фаст-трекать»); после эскалации
|
||||
задача проходит штатный маршрут с `architecture`.
|
||||
- **FAIL:** механизма эскалации нет; ИЛИ багфикс-задача необратимо застревает без `architecture`,
|
||||
когда баг требует архитектурного решения/макета.
|
||||
|
||||
---
|
||||
|
||||
## AC-6 — Fail-safe → полный цикл (нулевая регрессия)
|
||||
|
||||
**Условие:** при выключении/ошибке/неприменимости — строго прежнее поведение (полный цикл).
|
||||
- **PASS:** при `bug_fast_track_enabled=False`, неприменимом репо, ошибке/таймауте/неоднозначности
|
||||
чтения метки, отсутствии метки `Bug` — задача стартует на `analysis` и идёт маршрутом с
|
||||
`architecture` (как до ORCH-019). Логика never-raise: ошибка не роняет `start_pipeline`/вебхук.
|
||||
При выключенном флаге путь старта и маршрут идентичны текущим (диффом по поведению — нулевые).
|
||||
- **FAIL:** ошибка/неоднозначность приводит к молчаливому пропуску стадий; ИЛИ исключение из
|
||||
логики классификации роняет вебхук/конвейер; ИЛИ при выключенном флаге поведение отличается от
|
||||
прежнего.
|
||||
|
||||
---
|
||||
|
||||
## AC-7 — Наблюдаемость трека и метрика стоимости
|
||||
|
||||
**Условие:** факт багфикс-трека и экономия наблюдаемы.
|
||||
- **PASS:** `GET /queue` содержит аддитивный read-only блок `bug_fast_track` (флаг/область/метка +
|
||||
счётчик задач на треке + агрегатная метрика экономии стадий/agent-runs/токенов/времени);
|
||||
решение о маршруте логируется; существующие ключи `GET /queue` не изменены.
|
||||
- **FAIL:** трек/метрика ненаблюдаемы; ИЛИ блок ломает существующий контракт `GET /queue`; ИЛИ
|
||||
ошибка построения блока роняет эндпоинт (нарушен never-raise).
|
||||
|
||||
---
|
||||
|
||||
## AC-8 — Аддитивность и self-hosting безопасность
|
||||
|
||||
**Условие:** изменение аддитивно и безопасно для общего прод-инстанса.
|
||||
- **PASS:** миграции БД (если есть) аддитивны и идемпотентны (`_ensure_column`/`CREATE TABLE IF NOT
|
||||
EXISTS`); enduro при выключенном/неприменимом флаге не затронут; механизм не рестартит/не роняет
|
||||
прод-контейнер, не пушит/force-push в `main`. Полный регресс `tests/` зелёный.
|
||||
- **FAIL:** ломающая миграция/изменение существующих контрактов; ИЛИ затронут enduro при выключенном
|
||||
флаге; ИЛИ механизм трогает прод-контейнер/`main`; ИЛИ красный `tests/`.
|
||||
|
||||
---
|
||||
|
||||
## AC-9 — Композиция с существующими гейтами
|
||||
|
||||
**Условие:** багфикс-трек корректно сосуществует с ORCH-088/089/027/043.
|
||||
- **PASS:** багфикс-задача корректно учитывается serial-gate (ORCH-088) как обычная задача репо;
|
||||
`autoApprove`/`autoDeploy` (ORCH-089) работают на багфикс-треке; coverage-gate (ORCH-027) и
|
||||
merge-gate (ORCH-043) исполняются штатно. Интеграционный тест композиции зелёный.
|
||||
- **FAIL:** изменённая точка входа ломает serial-очередь/auto-label/merge/coverage; ИЛИ багфикс-
|
||||
задача обходит serial-gate.
|
||||
|
||||
---
|
||||
|
||||
## Сводная матрица AC ↔ BR/FR
|
||||
| AC | Покрывает |
|
||||
|----|-----------|
|
||||
| AC-1 | BR-1 / FR-1 |
|
||||
| AC-2 | BR-2 / FR-2 |
|
||||
| AC-3 | BR-3 / FR-3 / NFR-1 |
|
||||
| AC-4 | BR-4 / FR-4 |
|
||||
| AC-5 | BR-5 / FR-5 |
|
||||
| AC-6 | BR-6 / FR-6 / NFR-2 / NFR-3 |
|
||||
| AC-7 | BR-7 / FR-7 |
|
||||
| AC-8 | BR-8 / NFR-2 / NFR-6 |
|
||||
| AC-9 | NFR-7 |
|
||||
</content>
|
||||
@@ -1,111 +0,0 @@
|
||||
work_item: ORCH-019
|
||||
stage: analysis
|
||||
author_agent: analyst
|
||||
status: ready-for-review
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
title: "Багфикс-трек: классификация по метке, укороченный маршрут, сохранность гейтов, fail-safe"
|
||||
framework: pytest
|
||||
scope: >
|
||||
Покрывает: классификацию задачи как бага по метке Plane (ORCH-089-аппарат), маршрутизацию
|
||||
багфикса в обход стадии architecture, сохранность ВСЕХ Quality Gate'ов, обязательность
|
||||
регресс-теста, эскалацию в полный цикл, fail-safe → полный цикл, наблюдаемость/метрику,
|
||||
аддитивность и композицию с serial-gate/auto-label/coverage. Вне покрытия: реальный
|
||||
Plane/Gitea I/O (мокается), роутинг моделей ORCH-13, LLM-авто-триаж сложности.
|
||||
notes: >
|
||||
Сетевые вызовы Plane (fetch_issue_labels/get_project_labels) мокаются. Полный регресс tests/
|
||||
должен оставаться зелёным. Тесты на сохранность гейтов проверяют НЕИЗМЕННОСТЬ QG_CHECKS/check_*/
|
||||
вердикт-ключей — это анти-регресс корневого инварианта (NFR-1). Финальные имена модулей/функций
|
||||
(labels.py vs новый bug_fast_track.py; tasks.track колонка) фиксирует архитектор — TC привязаны
|
||||
к поведению, имена путей уточняются на стадии разработки.
|
||||
|
||||
tests:
|
||||
- id: TC-01
|
||||
type: unit
|
||||
description: "is_bug_task() возвращает True для issue с меткой 'Bug' (has_label True); метка читается из Plane API, не из payload."
|
||||
module: tests/test_bug_fast_track.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-02
|
||||
type: unit
|
||||
description: "is_bug_task() возвращает False при отсутствии метки, неоднозначной метке или labels=None (fail-safe)."
|
||||
module: tests/test_bug_fast_track.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-03
|
||||
type: unit
|
||||
description: "bug_fast_track_applies(repo): первым проверяется локальная область (enabled + CSV repos) до любого сетевого вызова; выключенный флаг → False без обращения к has_label."
|
||||
module: tests/test_bug_fast_track.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-04
|
||||
type: unit
|
||||
description: "never-raise: исключение в fetch_issue_labels/get_project_labels не пробрасывается — is_bug_task деградирует в False (полный цикл)."
|
||||
module: tests/test_bug_fast_track.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-05
|
||||
type: unit
|
||||
description: "Маршрут багфикса: для bug-задачи следующая стадия после analysis = development (architecture пропущена); для не-баг задачи = architecture."
|
||||
module: tests/test_bug_fast_track_routing.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-06
|
||||
type: unit
|
||||
description: "STAGE_TRANSITIONS структурно не изменён: набор стадий и рёбер байт-в-байт прежний (анти-регресс)."
|
||||
module: tests/test_bug_fast_track_routing.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-07
|
||||
type: unit
|
||||
description: "Реестр QG_CHECKS и сигнатуры check_* не изменены багфикс-треком; вердикт-ключи (verdict/result/deploy_status/staging_status/security_status/coverage_status) сохранены по имени и регистру."
|
||||
module: tests/test_bug_fast_track_gates.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-08
|
||||
type: integration
|
||||
description: "E2E багфикс-трек: bug-задача проходит development→review→testing→deploy-staging→deploy с исполнением всех гейтов (check_ci_green/reviewer_verdict/tests_passed/staging/deploy + под-гейты security/merge/coverage/image-freshness), минуя architecture."
|
||||
module: tests/test_bug_fast_track_e2e.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-09
|
||||
type: integration
|
||||
description: "start_pipeline: issue с меткой Bug (флаг вкл, репо применим) создаёт задачу на багфикс-треке; issue без метки — на полном цикле (точка входа analysis + маршрут с architecture)."
|
||||
module: tests/test_bug_fast_track_e2e.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-10
|
||||
type: integration
|
||||
description: "Fail-safe: при bug_fast_track_enabled=False путь старта и маршрут идентичны прежним (нулевая регрессия) — задача с меткой Bug идёт полным циклом."
|
||||
module: tests/test_bug_fast_track_e2e.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-11
|
||||
type: integration
|
||||
description: "Эскалация: после снятия метки Bug / решения 'баг сложный' задача проходит штатный маршрут с architecture (возврат в полный цикл)."
|
||||
module: tests/test_bug_fast_track_escalation.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-12
|
||||
type: unit
|
||||
description: "check_analysis_approved/check_analysis_complete не блокирует ложно облегчённый багфикс-пакет, но сохраняет прежнюю проверку для не-баг задач (требование FR-6)."
|
||||
module: tests/test_bug_fast_track_gates.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-13
|
||||
type: integration
|
||||
description: "GET /queue содержит аддитивный read-only блок bug_fast_track (enabled/repos/label/счётчик/метрика); существующие ключи неизменны; ошибка построения блока не роняет эндпоинт."
|
||||
module: tests/test_queue_endpoint.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-14
|
||||
type: integration
|
||||
description: "Композиция: багфикс-задача учитывается serial-gate (ORCH-088) как обычная задача репо и не обходит его; autoApprove/autoDeploy (ORCH-089) применимы на багфикс-треке."
|
||||
module: tests/test_bug_fast_track_composition.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-15
|
||||
type: unit
|
||||
description: "Миграция (если введена колонка tasks.track) аддитивна и идемпотентна: повторный init_db/_ensure_column не падает; дефолт 'full' для существующих строк."
|
||||
module: tests/test_db_migrations.py
|
||||
expected: PASS
|
||||
@@ -1,231 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-019
|
||||
stage: architecture
|
||||
author_agent: architect
|
||||
status: proposed
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# ADR-001: Багфикс-трек — пропуск стадии `architecture` через track-aware routing override
|
||||
|
||||
Work Item: **ORCH-019** — упрощённый/дешёвый трек для багов (укороченный маршрут конвейера)
|
||||
Стадия: **architecture**
|
||||
Сквозная регистрация: **`docs/architecture/adr/adr-0032-bug-fast-track.md`** (решение
|
||||
кросс-каттинговое: новый leaf-компонент + аддитивная колонка `tasks.track` + семантика
|
||||
маршрутизации, затрагивающая `advance_stage`).
|
||||
|
||||
## Статус
|
||||
Proposed
|
||||
|
||||
## Контекст
|
||||
|
||||
Любая задача входит в конвейер через `webhooks/plane.py::start_pipeline`, который
|
||||
**жёстко** создаёт task-row со стадией `"analysis"` (`create_task_atomic(..., "analysis", ...)`)
|
||||
и режет ветку. Маршрут стадий полностью управляется `src/stages.py::STAGE_TRANSITIONS` через
|
||||
`get_next_stage` — `advance_stage` (`src/stage_engine.py`) НЕ зашивает порядок, а спрашивает
|
||||
`get_next_stage(current_stage)` (строка 214) и `get_agent_for_stage(current_stage)` (строка 464).
|
||||
|
||||
Для мелкого бага полный цикл `analysis → architecture → development → …` избыточен: стадия
|
||||
`architecture` = отдельный прогон агента `architect` (opus, дорогой) + ADR + exit-гейт
|
||||
`check_architecture_done`. Прецедент: UI z-index баг ET-9/ET-014 прошёл полный цикл ~35 мин.
|
||||
|
||||
**Корневой инвариант (NFR-1 BRD, нерушимый):** упрощаем только *аналитику/архитектуру*; ни один
|
||||
Quality Gate / exit-код deploy-хука / под-гейт (security/merge/coverage/image-freshness) — НЕ
|
||||
ослаблен. Горький урок ET-8: срезанная *проверка* = недоделка на проде.
|
||||
|
||||
**Факты, сверенные с кодом:**
|
||||
- `src/labels.py::has_label` + `plane_sync.fetch_issue_labels`/`get_project_labels` (ORCH-089) —
|
||||
готовый, проверенный аппарат чтения метки Plane (TTL-кэш, нормализация, never-raise,
|
||||
fail-safe → False, источник истины Plane API, не payload).
|
||||
- `advance_stage` маршрутизирует через `get_next_stage`/`get_agent_for_stage` → точка ветвления
|
||||
локализуема, `STAGE_TRANSITIONS` ломать не нужно.
|
||||
- `check_analysis_approved` (exit-гейт `analysis`) вызывает `check_analysis_complete`, требующий
|
||||
**01/02/03/04** (`src/qg/checks.py:33`). Это и есть точка риска ложной блокировки облегчённого
|
||||
пакета (FR-6).
|
||||
- `_ensure_column` (`src/db.py:334`) — идемпотентная аддитивная миграция (паттерн
|
||||
`tasks.cancelled_at`, ORCH-090).
|
||||
|
||||
## Решение
|
||||
|
||||
### Сводка
|
||||
|
||||
Багфикс-трек — **свойство планировщика/точки входа, не Quality Gate**. Задача с меткой Plane
|
||||
`Bug` помечается в БД как `track='bug'`; на ребре выхода из `analysis` `advance_stage` применяет
|
||||
**чистый routing-override**: `next_stage` → `development` (вместо `architecture`), `next_agent`
|
||||
→ `developer` (вместо `architect`). `STAGE_TRANSITIONS`, реестр `QG_CHECKS`, все `check_*` и
|
||||
вердикт-ключи — **байт-в-байт прежние**. Распознавание, маршрут и метрика — аддитивно, под
|
||||
kill-switch, с областью репо, never-raise, fail-safe → полный цикл.
|
||||
|
||||
### D1 — Классификация: метка Plane `Bug`, читаемая в `start_pipeline` (FR-1, AC-1)
|
||||
|
||||
Новый leaf `src/bug_fast_track.py` (пустой импорт-граф как `serial_gate`/`labels`: только
|
||||
`config`, лениво `labels`/`plane_sync`/`qg.checks`), never-raise. Публичные функции:
|
||||
- `bug_fast_track_applies(repo) -> bool` — локальный, без сети, по образцу `_auto_label_applies`:
|
||||
`bug_fast_track_enabled=False` → `False`; `bug_fast_track_repos` (CSV) непустой → только
|
||||
перечисленные репо; **пусто → self-hosting only** (`is_self_hosting_repo`, см. D6). Проверяется
|
||||
**ПЕРВЫМ** → при выключенном флаге нулевой сетевой оверхед, enduro не затронут.
|
||||
- `is_bug_task(work_item_id, project_id) -> bool` — `bug_fast_track_applies` уже проверен
|
||||
вызывающим; делегирует в `labels.has_label(work_item_id, settings.bug_fast_track_label,
|
||||
project_id)` (дефолт метки `Bug`). Любая ошибка/неоднозначность → `False` (fail-safe → полный
|
||||
цикл).
|
||||
|
||||
Чтение метки — **только** в `start_pipeline` (момент старта, сетевой вызов приемлем, как
|
||||
ORCH-089), **никогда** в горячем `claim_next_job` (NFR-4).
|
||||
|
||||
### D2 — Хранение типа: аддитивная колонка `tasks.track` (OQ-2, NFR-4)
|
||||
|
||||
Идемпотентная миграция `_ensure_column(conn, "tasks", "track", "TEXT DEFAULT 'full'")` рядом с
|
||||
`tasks.cancelled_at`/`cancel_requested_at` (`src/db.py` init). Значения: `'full'` (дефолт, ВСЕ
|
||||
существующие и не-баг задачи) | `'bug'`. Хелперы: `db.set_task_track(task_id, track)` (запись),
|
||||
`db.get_task_track(task_id) -> str` (чтение, дефолт `'full'`). Тип читается из **БД** в
|
||||
`advance_stage` (NFR-4: горячий путь без сети). Альтернатива «выводить тип повторным чтением
|
||||
метки» отвергнута — повторный сетевой вызов в горячем пути запрещён.
|
||||
|
||||
`create_task_atomic` НЕ меняет сигнатуру: задача создаётся как `'full'` (DEFAULT), затем
|
||||
`start_pipeline` после успешного `created=True` при `is_bug_task` вызывает
|
||||
`db.set_task_track(task_id, 'bug')`. Точка входа стадии остаётся `"analysis"` (мини-анализ
|
||||
сохраняется, OQ-3/BRD §6 — НЕ чистый hotfix).
|
||||
|
||||
### D3 — Routing-override: пропуск `architecture` без правки `STAGE_TRANSITIONS` (FR-2, AC-2)
|
||||
|
||||
`get_next_stage`/`get_agent_for_stage` остаются **чистыми** (принимают только стадию, 1:1).
|
||||
Override живёт в `advance_stage`, сразу после строки `next_stage = get_next_stage(current_stage)`:
|
||||
|
||||
```python
|
||||
next_stage = get_next_stage(current_stage)
|
||||
# ORCH-019: bug-fast-track skips the architecture stage entirely.
|
||||
if current_stage == "analysis" and bug_fast_track.skips_architecture(track):
|
||||
next_stage = "development"
|
||||
```
|
||||
|
||||
и при запуске следующего агента (строка 464):
|
||||
|
||||
```python
|
||||
next_agent = get_agent_for_stage(current_stage) # "analysis" -> "architect"
|
||||
if current_stage == "analysis" and next_stage == "development":
|
||||
next_agent = "developer" # skip architect run
|
||||
```
|
||||
|
||||
`track` читается один раз в начале `advance_stage` (`db.get_task_track(task_id)`). Чистый
|
||||
предикат `bug_fast_track.skips_architecture(track) -> bool` (== `track == 'bug'` под
|
||||
`bug_fast_track_enabled`; иначе `False`). Багфикс-задача физически НЕ попадает в стадию
|
||||
`architecture` → её exit-гейт `check_architecture_done` и требование `06-adr/` не исполняются для
|
||||
багфикса. Для не-баг задач (`track='full'`) поведение **байт-в-байт** прежнее.
|
||||
|
||||
**Сопутствующая правка телеметрии:** строка 386 стампит `mark_brd_review_ended` при
|
||||
`analysis → architecture`. Для багфикса next_stage = `development`, поэтому условие расширяется до
|
||||
`current_stage == "analysis" and next_stage in ("architecture", "development")` — чтобы метрика
|
||||
«твоё время» (ORCH-087) оставалась честной на багфикс-треке. Не влияет на гейты.
|
||||
|
||||
### D4 — Quality Gate `analysis`: НЕ трогаем; lite-пакет эмитит все 4 файла (FR-3/FR-6, OQ-6, AC-3)
|
||||
|
||||
**Корневой инвариант диктует минимальную поверхность изменения гейтов = ноль.**
|
||||
`check_analysis_complete` (требует 01/02/03/04) и `check_analysis_approved` остаются **байт-в-байт
|
||||
прежними**. Багфикс-аналитик (`analyst.md` lite-режим) всё равно эмитит **все 4** файла, но в
|
||||
облегчённой багфикс-форме: `01-brd.md` = короткий bug-report (симптом / шаги воспроизведения /
|
||||
локализация / причина), `02-trz.md` + `03-acceptance-criteria.md` = краткие bug-shaped заглушки,
|
||||
`04-test-plan.yaml` = план **обязательного регресс-теста** (красный до фикса, зелёный после).
|
||||
|
||||
Обоснование выбора: доминирующая экономия — пропуск **всей стадии `architecture`** (отдельный
|
||||
прогон opus-агента `architect` + ADR), а не число файлов analysis (они эмитятся в ОДНОМ прогоне
|
||||
analyst-агента). Сохранение 4-файлового гейта = **сильнейшая** позиция NFR-1 (нулевая поверхность
|
||||
правок гейта) ценой почти нулевого оверхеда. Альтернатива «track-aware `check_analysis_complete`
|
||||
(для bug требовать только 01/04)» рассмотрена и отвергнута для v1 (D-Alt) — она трогает `check_*`
|
||||
и расширяет поверхность риска без существенной экономии.
|
||||
|
||||
### D5 — Эскалация в полный цикл (FR-5, AC-5)
|
||||
|
||||
Два пути возврата сложного/архитектурного/визуального бага в полный цикл, оба сбрасывают
|
||||
`track='bug'` → `'full'` (после чего `advance_stage` маршрутизирует `analysis → architecture`
|
||||
штатно):
|
||||
1. **Операторский (ручной, v1-дефолт):** админ-эндпоинт `POST /bug-fast-track/escalate?work_item=<id>`
|
||||
(по образцу `POST /serial-gate/unfreeze`, `POST /coverage/baseline`) — `db.set_task_track(...,
|
||||
'full')`, лог + Telegram + Plane-коммент, never-raise. Применять, пока задача в `analysis`
|
||||
(до выхода) — тогда следующий переход уйдёт в `architecture`.
|
||||
2. **Решение мини-аналитика:** если на багфикс-треке аналитик определяет, что баг архитектурный,
|
||||
он эмитит **полный** analysis-пакет (включая запрос на `06-adr/`) и помечает в bug-report
|
||||
`escalate: full-cycle` — оператор подтверждает эскалацию эндпоинтом (1). v1 НЕ включает
|
||||
автоматический LLM-авто-триаж сложности (вне объёма, BRD §2.2).
|
||||
|
||||
Эскалация обратима, детерминирована, наблюдаема. Багфикс-задача не «застревает» без архитектуры.
|
||||
|
||||
### D6 — Область по умолчанию: self-hosting only (OQ-5, NFR-5)
|
||||
|
||||
Пустой `bug_fast_track_repos` → **self-hosting only** (`is_self_hosting_repo`, как
|
||||
ORCH-089/027/058). Это безопасный дефолт: режим обкатывается на самом орке (где метка `Bug`
|
||||
гарантированно заводится оператором), enduro подключается явным добавлением в CSV. Флаги
|
||||
(`config.py`): `bug_fast_track_enabled` (kill-switch, env `ORCH_BUG_FAST_TRACK_ENABLED`),
|
||||
`bug_fast_track_label` (дефолт `Bug`, env `ORCH_BUG_FAST_TRACK_LABEL`), `bug_fast_track_repos`
|
||||
(CSV, env `ORCH_BUG_FAST_TRACK_REPOS`).
|
||||
|
||||
### D7 — Наблюдаемость стоимости (FR-7, AC-7)
|
||||
|
||||
- **`GET /queue`** — аддитивный read-only блок `bug_fast_track` (`bug_fast_track.snapshot()`,
|
||||
never-raise, по образцу `serial_gate`/`auto_labels`/`coverage`): `enabled`, `repos`, `label`,
|
||||
счётчик задач с `track='bug'`, агрегатная метрика экономии (пропущенные стадии / Σ agent-runs /
|
||||
токены / время багфикс-трека против среднего полного цикла из существующей телеметрии
|
||||
`agent_runs`). Существующие ключи `GET /queue` не меняются.
|
||||
- **Лог-строка** на решение о маршруте (`analysis → development (bug-fast-track)`).
|
||||
- **Опц.** отметка `🐞 багфикс-трек` в Telegram-карточке (`notifications.py`, never-raise).
|
||||
|
||||
### D8 — Композиция (NFR-7, AC-9)
|
||||
|
||||
- **serial-gate (ORCH-088):** багфикс-задача — обычная задача репо, учитывается в serial-очереди
|
||||
как есть (FIFO `t2.id < jobs.task_id`); точка входа `analysis` не меняется, defer-branch логика
|
||||
не затронута. Маркированный код `serial_gate.py` НЕ правится.
|
||||
- **auto-label (ORCH-089):** `autoApprove`/`autoDeploy` работают на багфикс-треке — autoApprove
|
||||
врезка в `_handle_analysis_approved_flow` вызывает `advance_stage(finished_agent=None)`, который
|
||||
применяет D3-override и уходит в `development`. Переиспользуем `labels.has_label`.
|
||||
- **coverage-gate (ORCH-027):** союзник BR-4 (структурно ловит «код без теста») — исполняется
|
||||
штатно на ребре `deploy-staging → deploy`.
|
||||
- **merge-gate (ORCH-043):** не затронут.
|
||||
|
||||
Правки маркированного кода (`advance_stage` несёт врезки ORCH-088/089/027/059/094) — точечные,
|
||||
со сверкой их `06-adr/`; зафиксированные инварианты (порядок под-гейтов, merge-lease,
|
||||
terminal-sync) НЕ нарушаются: ORCH-019 добавляет ветвление ТОЛЬКО на ребре выхода из `analysis`,
|
||||
до всех deploy-edge под-гейтов.
|
||||
|
||||
## Альтернативы
|
||||
|
||||
- **Track-aware `get_next_stage(stage, task)` / новая стадия в `STAGE_TRANSITIONS`** — отвергнуто:
|
||||
ломает чистоту `stages.py` и риск задеть структуру таблицы (AC-2 FAIL при структурном изменении).
|
||||
Override в `advance_stage` локальнее и держит `STAGE_TRANSITIONS` неизменным.
|
||||
- **Track-aware `check_analysis_complete` (bug → только 01/04)** — отвергнуто для v1 (D-Alt):
|
||||
трогает `check_*`, расширяет поверхность риска NFR-1 ради почти нулевой экономии (см. D4).
|
||||
Оставлено как возможное будущее уточнение, если потребуется реальный отказ от 02/03.
|
||||
- **Чистый hotfix `start_pipeline → development`, минуя `analysis`** — отвергнуто как дефолт
|
||||
(BRD §6): теряется фиксация регресс-теста как контракта приёмки и трассируемость (урок ET-8).
|
||||
- **Тип задачи из payload вебхука / повторное чтение метки в `claim_next_job`** — отвергнуто:
|
||||
payload не несёт `type` (источник истины — Plane API); сеть в горячем claim запрещена (NFR-4).
|
||||
- **Чтение типа без БД-колонки** — отвергнуто: потребовало бы сетевого вызова в горячем пути.
|
||||
|
||||
## Последствия
|
||||
|
||||
- **+** Багфикс минует целую стадию `architecture` (один прогон opus-агента `architect` + ADR) —
|
||||
основная экономия токенов/времени; гейты качества **байт-в-байт** сохранены.
|
||||
- **+** Полностью аддитивно: kill-switch `False` или неприменимый репо → путь старта и маршрут
|
||||
идентичны текущим (AC-6, нулевая регрессия для enduro и orchestrator).
|
||||
- **+** Переиспользует проверенный аппарат ORCH-089 (label-чтение) и паттерн leaf+флаги+snapshot.
|
||||
- **−** Багфикс-аналитик всё равно эмитит 02/03 (краткие заглушки) ради неизменности гейта —
|
||||
принятый компромисс (D4); экономия на их содержании, не на их наличии.
|
||||
- **−** Эскалация v1 требует операторского действия (эндпоинт) — авто-триаж сложности отложен
|
||||
(BRD §2.2). Митигатор: путь эскалации документирован, обратим, наблюдаем (D5).
|
||||
- **Откат:** `bug_fast_track_enabled=False` (мгновенно, 1:1 прежнее поведение); колонка
|
||||
`tasks.track` остаётся (аддитивна, дефолт `'full'`, безвредна). Полный откат — revert PR;
|
||||
миграция идемпотентна, остаточная колонка не мешает.
|
||||
|
||||
## Ссылки
|
||||
- BRD: `docs/work-items/ORCH-019/01-brd.md`
|
||||
- TRZ: `docs/work-items/ORCH-019/02-trz.md`
|
||||
- Acceptance: `docs/work-items/ORCH-019/03-acceptance-criteria.md`
|
||||
- Сквозной ADR: `docs/architecture/adr/adr-0032-bug-fast-track.md`
|
||||
- Data: `docs/work-items/ORCH-019/08-data-requirements.md`
|
||||
- Infra: `docs/work-items/ORCH-019/07-infra-requirements.md`
|
||||
- Риски: `docs/work-items/ORCH-019/10-tech-risks.md`
|
||||
- Сверено по коду: `src/stages.py`, `src/stage_engine.py` (advance_stage:175-477),
|
||||
`src/webhooks/plane.py::start_pipeline` (505-684), `src/labels.py`,
|
||||
`src/qg/checks.py` (check_analysis_complete:33, check_analysis_approved:286,
|
||||
check_architecture_done:62), `src/db.py` (_ensure_column:334, create_task_atomic:433)
|
||||
</content>
|
||||
</invoke>
|
||||
@@ -1,62 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-019
|
||||
stage: architecture
|
||||
author_agent: architect
|
||||
status: proposed
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# 07 — Инфраструктурные требования (Infra Requirements): ORCH-019 — Багфикс-трек
|
||||
|
||||
Work Item: **ORCH-019** · Repo: **orchestrator** · Стадия: architecture
|
||||
|
||||
> **Топология не меняется.** Один прод-контейнер `orchestrator` (8500) + staging (8501) на mva154,
|
||||
> общая SQLite-БД. ORCH-019 — чисто прикладное изменение под флагом. Этот документ фиксирует
|
||||
> **предусловия включения** (Plane-метка + env-флаги), не новую инфраструктуру.
|
||||
|
||||
---
|
||||
|
||||
## 1. Предусловие: метка `Bug` в Plane-проекте (блокирующее для активации)
|
||||
|
||||
Багфикс-трек активируется по метке Plane с именем `bug_fast_track_label` (дефолт `Bug`),
|
||||
читаемой аппаратом ORCH-089 (`fetch_issue_labels`/`get_project_labels`). **Метка должна
|
||||
существовать** в Plane-проекте orchestrator (и в любом проекте, добавленном в
|
||||
`bug_fast_track_repos`).
|
||||
|
||||
- Её **отсутствие = fail-safe полный цикл** (`has_label → False`), не сбой. Включение флага без
|
||||
заведённой метки безопасно, но эффекта не даёт.
|
||||
- Создаётся оператором в Plane вручную (как `autoApprove`/`autoDeploy` для ORCH-089).
|
||||
|
||||
## 2. Конфигурация (env-флаги, `src/config.py`)
|
||||
|
||||
| Флаг | Env | Дефолт | Назначение |
|
||||
|------|-----|--------|-----------|
|
||||
| `bug_fast_track_enabled` | `ORCH_BUG_FAST_TRACK_ENABLED` | `False` | kill-switch; `False` → путь старта/маршрут строго прежние (нулевая регрессия) |
|
||||
| `bug_fast_track_label` | `ORCH_BUG_FAST_TRACK_LABEL` | `Bug` | имя метки Plane для распознавания бага |
|
||||
| `bug_fast_track_repos` | `ORCH_BUG_FAST_TRACK_REPOS` | `""` (пусто) | CSV-область; пусто → **self-hosting only** (`orchestrator`) |
|
||||
|
||||
> Рекомендация выката: `enabled=False` до момента, когда метка `Bug` заведена в Plane и проведён
|
||||
> staging-прогон. Дефолт области (пустой CSV) = self-hosting only → enduro не затронут даже при
|
||||
> включённом флаге.
|
||||
|
||||
## 3. Зависимости / образ
|
||||
|
||||
- **Новых pip-зависимостей нет.** Переиспользуются существующие `httpx`/`plane_sync` (label-чтение)
|
||||
и `sqlite3` (колонка `tasks.track`). Пересборка образа из-за зависимостей не требуется.
|
||||
- **Миграция БД** (`tasks.track`) применяется идемпотентно при старте приложения (`_ensure_column`)
|
||||
— без ручного шага, без даунтайма (ALTER ADD COLUMN на SQLite — мгновенный).
|
||||
|
||||
## 4. Self-hosting безопасность (NFR-6)
|
||||
|
||||
- Механизм **не** рестартит/не роняет прод-контейнер, **не** пушит/force-push в `main`. Это
|
||||
routing-решение планировщика + аддитивная колонка + read-only наблюдаемость.
|
||||
- Выкат самого ORCH-019 на прод орка идёт штатным конвейером через обязательный
|
||||
`deploy-staging` (8501) → `Confirm Deploy` (ORCH-059). Топология/процедура — `docs/operations/INFRA.md`.
|
||||
|
||||
## 5. Новый эндпоинт (эскалация)
|
||||
|
||||
`POST /bug-fast-track/escalate?work_item=<id>` — админ-ручка возврата задачи в полный цикл
|
||||
(`track → 'full'`), по образцу `POST /serial-gate/unfreeze`. Без новой инфраструктуры (тот же
|
||||
FastAPI-приложение/порт). Read-only блок `bug_fast_track` добавляется в существующий `GET /queue`.
|
||||
</content>
|
||||
@@ -1,64 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-019
|
||||
stage: architecture
|
||||
author_agent: architect
|
||||
status: proposed
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# 08 — Требования к данным (Data Requirements): ORCH-019 — Багфикс-трек
|
||||
|
||||
Work Item: **ORCH-019** · Repo: **orchestrator** · Стадия: architecture
|
||||
|
||||
> ⚠️ Общая прод-БД (self-hosting + enduro). Только **аддитивные, идемпотентные** миграции;
|
||||
> существующие контракты таблиц не меняются.
|
||||
|
||||
---
|
||||
|
||||
## 1. Новая колонка `tasks.track`
|
||||
|
||||
| Атрибут | Значение |
|
||||
|---------|----------|
|
||||
| Таблица | `tasks` |
|
||||
| Колонка | `track` |
|
||||
| Тип | `TEXT` |
|
||||
| DEFAULT | `'full'` |
|
||||
| Допустимые значения | `'full'` (дефолт; ВСЕ существующие и не-баг задачи) \| `'bug'` |
|
||||
| Миграция | `_ensure_column(conn, "tasks", "track", "TEXT DEFAULT 'full'")` (идемпотентно, паттерн `tasks.cancelled_at` ORCH-090) |
|
||||
| Размещение | рядом с `_ensure_column(conn, "tasks", "cancel_requested_at", ...)` в init `src/db.py` |
|
||||
|
||||
**Семантика:** тип задачи (полный цикл / багфикс). Записывается в `start_pipeline` после
|
||||
успешного `create_task_atomic` (`created=True`) при `is_bug_task==True`. Читается в `advance_stage`
|
||||
для routing-override (D3) — из БД, **никогда** из сети (NFR-4).
|
||||
|
||||
## 2. Хелперы доступа (`src/db.py`)
|
||||
|
||||
| Хелпер | Контракт |
|
||||
|--------|----------|
|
||||
| `set_task_track(task_id: int, track: str) -> None` | `UPDATE tasks SET track=? WHERE id=?`; идемпотентно; never-raise на уровне вызова в `start_pipeline`/escalate |
|
||||
| `get_task_track(task_id: int) -> str` | `SELECT track FROM tasks WHERE id=?`; отсутствие/NULL → `'full'` (fail-safe → полный цикл) |
|
||||
|
||||
## 3. Что НЕ меняется
|
||||
|
||||
- Сигнатура `create_task_atomic(plane_id, work_item_id, repo, branch, stage, title)` —
|
||||
**без изменений** (задача создаётся как `track='full'` по DEFAULT, тип проставляется отдельным
|
||||
`set_task_track`).
|
||||
- Существующие колонки `tasks` (прочие), таблицы `jobs`, `job_deps`, `agent_runs`,
|
||||
`coverage_baseline`, `repo_freeze`, `tracker_messages` — **без изменений**.
|
||||
- `claim_next_job` — **без изменений** (не читает `track`; сеть/маршрут в горячем claim не вводятся).
|
||||
|
||||
## 4. Обратная совместимость / откат
|
||||
|
||||
- Колонка аддитивна с безопасным DEFAULT `'full'` → существующие строки и enduro-задачи ведут
|
||||
себя как сегодня без обратной записи.
|
||||
- Откат фичи (`bug_fast_track_enabled=False`) не требует удаления колонки: при выключенном флаге
|
||||
`track` не влияет на маршрут (`skips_architecture` → `False`). Остаточная колонка безвредна.
|
||||
- Полный revert PR: миграция `_ensure_column` идемпотентна; повторный запуск на БД с уже
|
||||
существующей колонкой — no-op.
|
||||
|
||||
## 5. Объём данных / производительность
|
||||
|
||||
- Одна `TEXT`-колонка на строку `tasks` (низкая кардинальность: 2 значения). Индекс не требуется
|
||||
(чтение по `id` PK в `advance_stage`; агрегат для `GET /queue` — редкий read-only скан).
|
||||
</content>
|
||||
@@ -1,39 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-019
|
||||
stage: architecture
|
||||
author_agent: architect
|
||||
status: proposed
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# 10 — Технические риски: ORCH-019 — Багфикс-трек
|
||||
|
||||
Work Item: **ORCH-019** · Repo: **orchestrator** · Стадия: architecture
|
||||
|
||||
> Шкала: вероятность × влияние ∈ {Низк., Средн., Выс.}. Каждый риск — с митигатором, привязанным
|
||||
> к ADR-001 / AC.
|
||||
|
||||
---
|
||||
|
||||
| ID | Риск | Вер. | Влияние | Митигатор |
|
||||
|----|------|------|---------|-----------|
|
||||
| R-1 | **Срезали лишнее** — ошибочный пропуск гейта качества → недоделка на проде (урок ET-8). | Низк. | Выс. | NFR-1 диктует **нулевую** поверхность правок гейтов (D4): `STAGE_TRANSITIONS`/`QG_CHECKS`/все `check_*`/вердикт-ключи — байт-в-байт; режется ТОЛЬКО стадия `architecture`. Тест AC-3: на багфикс-треке отрабатывают все гейты. |
|
||||
| R-2 | **Сложный баг под меткой `Bug`** уходит на фаст-трек и упирается в отсутствие архитектуры. | Средн. | Средн. | Эскалация D5 (эндпоинт `escalate` + self-escalate мини-аналитика) сбрасывает `track→full` → задача идёт через `architecture`. AC-5. |
|
||||
| R-3 | **Регресс-тест не написан** (developer «забыл») → рецидив бага. | Средн. | Выс. | BR-4: обязательный TC в `04-test-plan.yaml` + reviewer-ось (фикс без теста → REQUEST_CHANGES) + структурный союзник coverage-gate ORCH-027. AC-4. |
|
||||
| R-4 | **Fail-safe инвертирован** — ошибка чтения метки молча срежет стадии. | Низк. | Выс. | never-raise leaf `bug_fast_track.py`: любая ошибка/неоднозначность/`None`-labels → `is_bug_task=False` → полный цикл; `get_task_track` при NULL → `'full'`. AC-6. |
|
||||
| R-5 | **Конфликт с serial-gate/auto-label** при изменённой точке входа. | Низк. | Средн. | Точка входа НЕ меняется (задача стартует на `analysis`, ветвление — только на ребре выхода). serial_gate/auto-label маркированный код не правится. Интеграционный тест композиции (AC-9). |
|
||||
| R-6 | **Ложная блокировка** облегчённого пакета exit-гейтом `analysis` (`check_analysis_complete` требует 01/02/03/04). | Низк. | Средн. | D4: гейт НЕ трогаем; lite-аналитик эмитит все 4 файла (02/03 — краткие заглушки). FR-6/OQ-6. |
|
||||
| R-7 | **Правка маркированного `advance_stage`** (несёт врезки ORCH-088/089/027/059/094) сломает чужой инвариант. | Низк. | Выс. | Врезка ORCH-019 — ТОЛЬКО на ребре выхода из `analysis`, ДО всех deploy-edge под-гейтов; порядок под-гейтов/merge-lease/terminal-sync не затронуты (CLAUDE.md §9: сверка `06-adr/` затронутых ORCH-NNN). |
|
||||
| R-8 | **Телеметрия `mark_brd_review_ended`** не сработает на багфиксе (next=`development`, не `architecture`) → искажённая метрика «твоё время». | Низк. | Низк. | D3: условие расширено до `next_stage in ("architecture","development")`. Не влияет на гейты. |
|
||||
| R-9 | **Метрика экономии** (FR-7) вводит в заблуждение (несравнимые задачи). | Низк. | Низк. | Метрика помечена как относительная оценка из существующей телеметрии `agent_runs`; без новой тяжёлой инфраструктуры; read-only, never-raise. AC-7. |
|
||||
|
||||
---
|
||||
|
||||
## Сводный вывод
|
||||
|
||||
Доминирующий риск — **R-1 (срезали лишнее)**; он структурно закрыт нулевой поверхностью правок
|
||||
гейтов (D4) — изменение касается планировщика/точки входа, а не Quality Gate. Остальные риски
|
||||
покрыты паттерном leaf+флаги+fail-safe (ORCH-088/089/027) и обратимой эскалацией (D5). Откат —
|
||||
мгновенный через `bug_fast_track_enabled=False`.
|
||||
</content>
|
||||
@@ -1,108 +0,0 @@
|
||||
---
|
||||
verdict: APPROVED
|
||||
work_item: ORCH-019
|
||||
stage: review
|
||||
author_agent: reviewer
|
||||
status: approved
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
type: review
|
||||
work_item_id: ORCH-019
|
||||
version: 1
|
||||
---
|
||||
|
||||
# Review ORCH-019 — Багфикс-трек (упрощённый/дешёвый маршрут для багов)
|
||||
|
||||
## Summary
|
||||
|
||||
Реализация соответствует ТЗ (`02-trz.md`), ADR-001 и всем 9 критериям приёмки
|
||||
(`03-acceptance-criteria.md`). Корневой инвариант NFR-1 («срезается только аналитика/архитектура;
|
||||
ни один Quality Gate не тронут») соблюдён **структурно**: `src/stages.py` и `src/qg/checks.py` —
|
||||
**пустой diff**; маршрутизация багфикса реализована чистым routing-override в `advance_stage`, как
|
||||
и предписывал ADR (D3). Полный регресс `tests/` зелёный (**1551 passed**), 46 целевых тестов
|
||||
ORCH-019 (6 suites) — PASS. Документация обновлена исчерпывающе во всех требуемых поверхностях.
|
||||
Findings уровня P0/P1 — нет. → **APPROVED**.
|
||||
|
||||
## Проверка по осям
|
||||
|
||||
### 1. Соответствие ТЗ / Acceptance Criteria
|
||||
- **AC-1 (классификация по метке `Bug`)** ✓ — `bug_fast_track.is_bug_task` делегирует в
|
||||
`labels.has_label` (источник истины — Plane API, не payload); `applies(repo)` (локальный)
|
||||
проверяется ПЕРВЫМ в `start_pipeline` → при выключенном флаге нулевой сетевой оверхед.
|
||||
- **AC-2 (пропуск `architecture`)** ✓ — override на ребре выхода из `analysis`
|
||||
(`next_stage → development`, `next_agent → developer`); `STAGE_TRANSITIONS`/`get_next_stage`/
|
||||
`get_agent_for_stage` остались чистыми (1:1). Анти-регресс структуры — TC-06.
|
||||
- **AC-3 (все QG сохранены — корневой инвариант)** ✓ — `git diff` по `src/stages.py`/`src/qg/`
|
||||
пуст; вердикт-ключи и порядок под-гейтов не тронуты (TC-07). Подтверждено независимой проверкой
|
||||
diff, не только тестом.
|
||||
- **AC-4 (обязательный регресс-тест)** ✓ — ось добавлена в `.openclaw/agents/reviewer.md`
|
||||
(«фикс без теста-фиксатора → finding ≥P1»); `04-test-plan.yaml` несёт требование. (Сам ORCH-019 —
|
||||
feature, не bugfix, поэтому правило к нему не применяется; покрытие — 46 содержательных тестов.)
|
||||
- **AC-5 (эскалация)** ✓ — `POST /bug-fast-track/escalate` (`db.set_task_track 'bug'→'full'`,
|
||||
Telegram+Plane-коммент, never-raise) + self-escalate мини-аналитика (`analyst.md`).
|
||||
- **AC-6 (fail-safe / нулевая регрессия)** ✓ — `bug_fast_track_enabled` kill-switch; все публичные
|
||||
функции leaf'а never-raise → False (full cycle); `get_task_track` деградирует в `'full'`.
|
||||
Дефолт `True` согласован со всеми sibling-флагами (serial_gate/auto_label/coverage/stop/… все
|
||||
`= True` при пустом scope = self-hosting only).
|
||||
- **AC-7 (наблюдаемость)** ✓ — read-only блок `bug_fast_track` в `GET /queue` (`snapshot()`,
|
||||
never-raise) + отметка `🐞` в Telegram-карточке (never-raise) + лог-строки на решение.
|
||||
- **AC-8 (аддитивность / self-hosting)** ✓ — `_ensure_column(tasks, track, "TEXT DEFAULT 'full'")`
|
||||
идемпотентна (TC-15); прод-контейнер/`main` не трогаются; полный `tests/` зелёный.
|
||||
- **AC-9 (композиция)** ✓ — serial-gate/auto-label/coverage/merge — тест композиции зелёный
|
||||
(TC-14); override применяется ДО всех deploy-edge под-гейтов.
|
||||
|
||||
### 2. Соответствие ADR
|
||||
Реализация точно следует ADR-001 (D1–D8): leaf `src/bug_fast_track.py`, колонка `tasks.track`,
|
||||
override в `advance_stage`, эскалация-эндпоинт, область self-hosting-only. Сквозной ADR
|
||||
`adr-0032-bug-fast-track.md` присутствует.
|
||||
**Трассировка:** `advance_stage` несёт маркеры ORCH-088/089/027/059/094; врезка ORCH-019 добавляет
|
||||
ветвление ТОЛЬКО на ребре выхода из `analysis` (до deploy-edge под-гейтов) — зафиксированные
|
||||
инварианты (порядок под-гейтов, merge-lease, terminal-sync) не нарушены. Сверено по diff. Расширение
|
||||
`mark_brd_review_ended` на `analysis → development` (ORCH-087 метрика) гейтов не касается.
|
||||
|
||||
### 3. Качество кода
|
||||
- Leaf чист (импортирует только `config`, лениво `labels`/`db`/`qg.checks`), never-raise контракт
|
||||
соблюдён везде, публичные функции снабжены docstrings. ✓
|
||||
- Next-agent override (`next_stage == "development"`) безопасен: единственный путь к
|
||||
`analysis → development` — сам багфикс-override (штатно `get_next_stage("analysis") == "architecture"`). ✓
|
||||
- `get_task_by_work_item_id`/`add_comment`/`set_task_track`/`get_task_track` существуют и
|
||||
совместимы по сигнатурам. ✓
|
||||
|
||||
### 4. Документация — обязательная проверка
|
||||
`src/` изменён → документация ДОЛЖНА быть обновлена. **Обновлено в том же PR:**
|
||||
- `docs/architecture/README.md` — раздел «Багфикс-трек (ORCH-019)» + блок `bug_fast_track` в `GET /queue`;
|
||||
- `README.md` — таблица env (`ORCH_BUG_FAST_TRACK_*`) + обзорный раздел;
|
||||
- `.env.example` — три новых переменных;
|
||||
- `docs/architecture/adr/adr-0032-bug-fast-track.md` (сквозной) + `06-adr/ADR-001`;
|
||||
- `docs/architecture/internals.md`, `CLAUDE.md`, `CHANGELOG.md` (`feat:`);
|
||||
- `07-infra-requirements.md` / `08-data-requirements.md` / `10-tech-risks.md`;
|
||||
- `.openclaw/agents/analyst.md` (lite-пакет + self-escalate) и `reviewer.md` (ось регресс-теста).
|
||||
|
||||
Все поверхности из §8 ТЗ покрыты. **Обзорная витрина README** — добавлен раздел, ничего из «Известных
|
||||
ограничений» не оставлено открытым в нарушение ORCH-079.
|
||||
|
||||
## Findings
|
||||
|
||||
### P0 — Blocker
|
||||
- (нет)
|
||||
|
||||
### P1 — Must fix
|
||||
- (нет)
|
||||
|
||||
### P2 — Should fix
|
||||
- (нет)
|
||||
|
||||
### P3 — Nice to have
|
||||
- [ ] `snapshot.est_saved_architecture_runs == total_bug_tasks` считает ВСЕ багфикс-задачи, включая
|
||||
`cancelled` (которые могли не дойти до пропуска `architecture`). Косметическая неточность метрики
|
||||
экономии; на гейты/маршрут не влияет. Можно сузить до `stage NOT IN ('cancelled')` при случае.
|
||||
|
||||
## Документация
|
||||
Обновлена полностью и согласованно во всех требуемых поверхностях (architecture/README, README env +
|
||||
обзор, оба ADR, internals, CLAUDE.md, CHANGELOG, .env.example, промпты analyst/reviewer,
|
||||
infra/data/risks). Расхождений код↔документация не обнаружено. Требований к доработке документации
|
||||
нет.
|
||||
|
||||
## Вердикт
|
||||
Нет findings уровня P0/P1; документация обновлена; корневой инвариант подтверждён независимой
|
||||
проверкой diff и зелёным полным регрессом (1551 passed). → **APPROVED**.
|
||||
@@ -1,84 +0,0 @@
|
||||
---
|
||||
result: PASS # PASS | FAIL — машинный вердикт, UPPERCASE
|
||||
work_item: ORCH-019
|
||||
stage: testing
|
||||
author_agent: tester
|
||||
status: pass
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
type: test-report
|
||||
work_item_id: ORCH-019
|
||||
---
|
||||
|
||||
# Test Report — ORCH-019 — Багфикс-трек (упрощённый/дешёвый маршрут для багов)
|
||||
|
||||
## Окружение
|
||||
- Python: 3.12.13
|
||||
- pytest: 8.3.3 (plugins: cov-5.0.0, anyio-4.13.0, asyncio-0.23.8)
|
||||
- Worktree: `/repos/_wt/orchestrator/feature_ORCH-019-` (ветка `feature/ORCH-019-`)
|
||||
- Дата: 2026-06-10T00:53:34Z
|
||||
- Предусловие: review `12-review.md` = `verdict: APPROVED` ✓
|
||||
|
||||
## Smoke API (read-only)
|
||||
| Endpoint | Результат | Примечание |
|
||||
|----------|-----------|------------|
|
||||
| `GET /health` | PASS | `{"status":"ok","service":"orchestrator"}` |
|
||||
| `GET /status` | PASS | отвечает; ORCH-019 (task 84) виден на стадии `testing` |
|
||||
| `GET /queue` | PASS | блок `serial_gate` присутствует (ORCH-088) ✓; `auto_labels` присутствует ✓ |
|
||||
|
||||
> Прод-контейнер (8500) исполняет код **до** ORCH-019 (фича ещё не задеплоена), поэтому блока
|
||||
> `bug_fast_track` в живом `/queue` ожидаемо нет — это не регресс смока. Обязательные для смока
|
||||
> блоки `serial_gate` и `auto_labels` присутствуют. Новый блок `bug_fast_track` верифицирован
|
||||
> юнит/интеграционными тестами `test_queue_endpoint.py` (TC-13) на коде ветки. Smoke — read-only,
|
||||
> прод-контейнер не трогался.
|
||||
|
||||
## Результаты — покрытие TC из `04-test-plan.yaml`
|
||||
|
||||
| TC ID | Описание (кратко) | Тип | Тесты | AC | Результат |
|
||||
|-------|-------------------|-----|-------|----|-----------|
|
||||
| TC-01 | `is_bug_task()` True для метки `Bug`; источник — Plane API, не payload | unit | `test_tc01_is_bug_task_true`, `test_tc01_label_from_plane_api_not_payload` | AC-1 | PASS |
|
||||
| TC-02 | `is_bug_task()` False при отсутствии/неоднозначной метке/`labels=None` (fail-safe) | unit | `test_tc02_label_absent`, `test_tc02_labels_none`, `test_tc02_label_ambiguous`, `test_tc02_empty_label_config` | AC-1/AC-6 | PASS |
|
||||
| TC-03 | `bug_fast_track_applies(repo)`: локальная область ПЕРВОЙ; выключенный флаг → без сети | unit | `test_tc03_empty_csv_self_hosting_only`, `test_tc03_csv_membership`, `test_tc03_killswitch_off_no_network` | AC-6 | PASS |
|
||||
| TC-04 | never-raise: исключение в fetch labels → деградация в False (полный цикл) | unit | `test_tc04_is_bug_task_never_raises`, `test_tc04_applies_never_raises` | AC-6 | PASS |
|
||||
| TC-05 | Маршрут: bug → next stage после analysis = `development`; не-баг = `architecture` | unit | `test_tc05_bug_task_skips_architecture`, `test_tc05_full_task_keeps_architecture`, `test_tc05_killswitch_off_bug_keeps_architecture`, `test_tc05_bug_only_affects_analysis_edge` | AC-2 | PASS |
|
||||
| TC-06 | `STAGE_TRANSITIONS` структурно не изменён (анти-регресс) | unit | `test_tc06_stage_transitions_unchanged`, `test_tc06_get_next_stage_pure` | AC-2 | PASS |
|
||||
| TC-07 | `QG_CHECKS`/сигнатуры `check_*`/вердикт-ключи не изменены (имя+регистр) | unit | `test_tc07_qg_checks_registry_unchanged`, `test_tc07_verdict_keys_preserved` | AC-3 | PASS |
|
||||
| TC-08 | E2E багфикс-трек проходит development→…→deploy, минуя architecture, все гейты | integration | `test_tc08_bug_task_full_walk_skips_architecture` | AC-2/AC-3 | PASS |
|
||||
| TC-09 | `start_pipeline`: метка Bug → bug-track; без метки → full-track | integration | `test_tc09_bug_label_creates_bug_track`, `test_tc09_no_label_creates_full_track` | AC-1 | PASS |
|
||||
| TC-10 | Fail-safe: `enabled=False` → метка Bug идёт полным циклом (нулевая регрессия) | integration | `test_tc10_killswitch_off_bug_label_full_cycle` | AC-6 | PASS |
|
||||
| TC-11 | Эскалация: `'bug'→'full'` → штатный маршрут с architecture | integration | `test_tc11_escalate_returns_to_full_cycle`, `test_tc11_escalate_unknown_work_item`, `test_tc11_escalate_missing_arg`, `test_tc11_escalate_idempotent_on_full` | AC-5 | PASS |
|
||||
| TC-12 | `check_analysis_*` не блокирует ложно lite-пакет; не ослаблен для не-баг | unit | `test_tc12_bug_lite_package_with_all_four_passes`, `test_tc12_missing_file_still_fails_for_any_track`, `test_tc12_signature_has_no_track_param` | AC-3/FR-6 | PASS |
|
||||
| TC-13 | `GET /queue` несёт read-only блок `bug_fast_track`; существующие ключи целы | integration | `test_queue_has_bug_fast_track_block_and_keeps_existing_keys`, `test_queue_bug_fast_track_counts_bug_tasks` | AC-7 | PASS |
|
||||
| TC-14 | Композиция: bug-задача учтена serial-gate; autoApprove/autoDeploy применимы | integration | `test_tc14_bug_task_counts_as_active_in_serial_gate`, `test_tc14_bug_task_itself_gated_behind_predecessor`, `test_tc14_bug_task_claimable_once_predecessor_done`, `test_tc14_auto_label_applies_track_agnostic` | AC-9 | PASS |
|
||||
| TC-15 | Миграция `tasks.track` аддитивна/идемпотентна; дефолт `'full'` | unit | `test_tc15_track_column_present_with_default`, `test_tc15_init_db_idempotent`, `test_tc15_helpers_round_trip`, `test_tc15_get_task_track_missing_row_failsafe` | AC-8 | PASS |
|
||||
|
||||
**Итог покрытия:** все 15 TC из `04-test-plan.yaml` выполнены и сопоставлены с критериями
|
||||
`03-acceptance-criteria.md` (AC-1…AC-9). Непокрытых/пропущенных TC нет.
|
||||
|
||||
## Вывод pytest
|
||||
|
||||
### Целевые suite ORCH-019 (6 файлов + queue/migrations)
|
||||
```
|
||||
$ pytest tests/test_bug_fast_track.py tests/test_bug_fast_track_routing.py \
|
||||
tests/test_bug_fast_track_gates.py tests/test_bug_fast_track_e2e.py \
|
||||
tests/test_bug_fast_track_escalation.py tests/test_bug_fast_track_composition.py \
|
||||
tests/test_queue_endpoint.py tests/test_db_migrations.py -v
|
||||
...
|
||||
======================== 46 passed, 1 warning in 2.51s =========================
|
||||
```
|
||||
46/46 целевых тестов — PASS.
|
||||
|
||||
### Полный регресс
|
||||
```
|
||||
$ pytest tests/ -q --tb=short
|
||||
........................................................................ [100%]
|
||||
1551 passed, 1 warning in 56.64s
|
||||
```
|
||||
1551/1551 — PASS, 0 failed. (Единственный warning — известный Pydantic V2 deprecation в
|
||||
`src/config.py:8`, не относится к ORCH-019.)
|
||||
|
||||
## Итог
|
||||
**PASS** — полный регресс (1551 passed) и целевые suites ORCH-019 (46 passed) зелёные; smoke API
|
||||
(`/health`/`/status`/`/queue` с блоками `serial_gate`+`auto_labels`) — OK; все 15 TC выполнены и
|
||||
сопоставлены с AC-1…AC-9. Корневой инвариант NFR-1 (неизменность `STAGE_TRANSITIONS`/`QG_CHECKS`/
|
||||
вердикт-ключей) подтверждён анти-регресс-тестами TC-06/TC-07. → стадия переходит на `deploy-staging`.
|
||||
@@ -1,12 +0,0 @@
|
||||
---
|
||||
deploy_status: SUCCESS
|
||||
work_item: ORCH-019
|
||||
hook_exit_code: 0
|
||||
deployed_by: deploy-finalizer
|
||||
---
|
||||
|
||||
# Deploy log — ORCH-036 executable self-deploy
|
||||
|
||||
Прод-деплой завершён хост-хуком с exit-code `0` -> `deploy_status: SUCCESS`.
|
||||
|
||||
Вердикт зафиксирован детерминированным finalizer'ом (Фаза C), не LLM.
|
||||
@@ -1,51 +0,0 @@
|
||||
---
|
||||
staging_status: SUCCESS
|
||||
work_item: ORCH-019
|
||||
stage: deploy-staging
|
||||
author_agent: deployer
|
||||
status: success
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
timestamp: 2026-06-10T00:56:51Z
|
||||
base_url: http://localhost:8501
|
||||
---
|
||||
|
||||
# Staging Gate Log
|
||||
|
||||
Staging test suite completed against the live `orchestrator-staging` environment (port 8501),
|
||||
run inside the `orchestrator-staging` container (canonical path, ORCH-048):
|
||||
|
||||
```
|
||||
docker exec orchestrator-staging \
|
||||
python3 /repos/orchestrator/scripts/staging_check.py \
|
||||
--base-url http://localhost:8501 --mode stub
|
||||
```
|
||||
|
||||
**Result: 8/10 checks PASS — exit code 0 → SUCCESS.**
|
||||
|
||||
- REAL failed: **none**
|
||||
- SANDBOX_INFRA waived (ORCH-061): C9a, C9b
|
||||
|
||||
INFRA-WAIVED: C9a Branch appears in orchestrator-sandbox, C9b Analyst job enqueued in staging queue (known sandbox-infra; real checks green)
|
||||
VERDICT: SUCCESS (exit 0) — SUCCESS (infra-waived): ['C9a Branch appears in orchestrator-sandbox', 'C9b Analyst job enqueued in staging queue'] are known sandbox-infra checks; all real checks green
|
||||
|
||||
## Check breakdown
|
||||
|
||||
| Block | Check | Result |
|
||||
|-------|-------|--------|
|
||||
| A SMOKE | A1 GET /health → 200 status=ok | ✓ PASS |
|
||||
| A SMOKE | A2 GET /queue → 200 with counts/max_concurrency/resilience | ✓ PASS |
|
||||
| A SMOKE | A3 ORCH_STAGING=true (not prod) | ✓ PASS |
|
||||
| B ACCESS | B4 Plane: sandbox project accessible | ✓ PASS |
|
||||
| B ACCESS | B5 Gitea: orchestrator-sandbox accessible, push=true | ✓ PASS |
|
||||
| B ACCESS | B6 Registry: sandbox present, prod ET/ORCH absent | ✓ PASS |
|
||||
| C E2E | C7 Create issue in Plane SANDBOX | ✓ PASS |
|
||||
| C E2E | C8 Trigger pipeline via /webhook/plane | ✓ PASS |
|
||||
| C E2E | C9a Branch appears in orchestrator-sandbox | ✗ FAIL (INFRA-WAIVED) |
|
||||
| C E2E | C9b Analyst job enqueued in staging queue | ✗ FAIL (INFRA-WAIVED) |
|
||||
|
||||
Cleanup: Plane issue deleted (HTTP 204); no branch to delete.
|
||||
|
||||
Exit-code → verdict mapping unchanged: exit 0 → `staging_status: SUCCESS`. Waived checks are not
|
||||
re-judged (trust the exit code; the two infra-only checks C9a/C9b depend on SANDBOX bot accounts
|
||||
being project members, not on the pipeline). Staging gate **PASSED**; task advances to `deploy`.
|
||||
14
docs/work-items/ORCH-026/16-post-deploy-log.md
Normal file
14
docs/work-items/ORCH-026/16-post-deploy-log.md
Normal file
@@ -0,0 +1,14 @@
|
||||
---
|
||||
post_deploy_status: HEALTHY
|
||||
action_taken: NONE
|
||||
work_item: ORCH-026
|
||||
window_s: 900
|
||||
checks_total: 30
|
||||
checks_failed: 0
|
||||
---
|
||||
|
||||
# Post-deploy log — ORCH-021 post-deploy monitor
|
||||
|
||||
Наблюдение прода завершено: `post_deploy_status: HEALTHY`, `action_taken: NONE`.
|
||||
|
||||
Окно наблюдения: 900s; опросов всего: 30, из них с провалом: 0.
|
||||
@@ -1,7 +0,0 @@
|
||||
# Business Request: Code coverage как гейт (защита от деградации покрытия тестами)
|
||||
|
||||
Work Item ID: ORCH-027
|
||||
|
||||
## Description
|
||||
|
||||
TBD
|
||||
@@ -1,166 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-027
|
||||
stage: analysis
|
||||
author_agent: analyst
|
||||
status: ready-for-review
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# 01 — BRD (бизнес-требования): ORCH-027 — Code coverage как гейт (защита от деградации покрытия тестами)
|
||||
|
||||
Work Item: **ORCH-027** · Repo: **orchestrator** · Стадия: analysis
|
||||
|
||||
## 1. Бизнес-контекст и проблема
|
||||
|
||||
Оркестратор ведёт **автономную** разработку: код пишет агент `developer` без человеческого
|
||||
фильтра, а на стадии `testing` агент `tester` сам решает, достаточно ли тестов. Существующие
|
||||
тестовые гейты проверяют только **факт прохождения** тестов, а не их **полноту**:
|
||||
|
||||
- `check_ci_green` (ребро `development → review`) — зелёный прогон `pytest tests/` в Gitea CI
|
||||
(`.gitea/workflows/ci.yml`), судит по exit-code, покрытие **не меряет**.
|
||||
- `check_tests_passed` (ребро `testing → deploy-staging`) — читает machine-verdict
|
||||
`result:`/`verdict:`/`status:` из `13-test-report.md`; это вердикт LLM-`tester`'а, а не
|
||||
измеренная метрика.
|
||||
- Merge-gate re-test (ORCH-043) — повторный `pytest` на догнанной ветке, тоже только exit-code.
|
||||
|
||||
Ни один гейт не замечает, что фича добавила 300 строк кода и 0 тестов, или что багфикс
|
||||
изменил поведение без регрессионного теста. При пакетном автономном прогоне (эпик ORCH-088,
|
||||
«10–20 задач за ночь») это означает **монотонную деградацию покрытия**: каждая задача может
|
||||
«срезать угол» на тестах, и за десятки задач проект тихо теряет тестируемость. Предложено
|
||||
Стрим, одобрено Славой (`00-business-request.md`).
|
||||
|
||||
**Задача вводит измеримый гейт покрытия**: покрытие тестами измеряется инструментально и не
|
||||
должно опускаться ниже политики (абсолютный порог и/или «не ниже базовой линии»). Это
|
||||
структурная защита от деградации, аналогичная по духу security-гейту (ORCH-022) —
|
||||
детерминированная метрика вместо доверия суждению агента.
|
||||
|
||||
> **Self-hosting.** Гейт работает на инструменте, который в проде обслуживает все проекты из
|
||||
> общей БД и очереди (`CLAUDE.md` §self-hosting). Измерение покрытия — это исполнение тест-сьюта
|
||||
> в изолированном worktree; оно **не трогает прод-контейнер и не касается `main`**.
|
||||
|
||||
## 2. Объём (scope)
|
||||
|
||||
### В объёме
|
||||
- Инструментальное измерение покрытия тестами для репозитория `orchestrator` (стек Python /
|
||||
pytest) перед слиянием ветки задачи в `main`.
|
||||
- Гейт-решение: покрытие **не ниже** заданной политики порога. Политика поддерживает два режима:
|
||||
абсолютный порог (`%`) и «не ниже базовой линии» (no-regression / ratchet), а также их
|
||||
комбинацию.
|
||||
- Хранение и обновление **базовой линии** покрытия (last-known покрытие `main`).
|
||||
- Наблюдаемость результата: артефакт-отчёт о покрытии с machine-readable вердиктом, строка в
|
||||
`GET /queue`, сигнал в Telegram при провале.
|
||||
- Конфигурируемость: kill-switch + per-repo область + настраиваемый порог/политика +
|
||||
поведение при ошибке инструмента (fail-open/closed).
|
||||
|
||||
### Вне объёма
|
||||
- Реализация измерения покрытия для НЕ-Python стеков (jest / jacoco для будущих репозиториев) —
|
||||
фактическая интеграция инструментов оставлена на будущее; в ORCH-027 закладывается лишь
|
||||
расширяемость (политика и хранилище не должны быть жёстко завязаны на Python).
|
||||
- Изменение существующей семантики `check_ci_green` / `check_tests_passed` /
|
||||
`check_reviewer_verdict` для репозиториев, где гейт покрытия выключен.
|
||||
- Принудительное доведение покрытия до 100% или установка агрессивного абсолютного порога —
|
||||
стартовая политика консервативна (см. NFR-4).
|
||||
- Покрытие самих тестовых файлов и мутационное тестирование.
|
||||
- Выбор конкретного инструмента/механизма интеграции и его расположения в конвейере как
|
||||
архитектурного решения — это зона архитектора (`06-adr/`); BRD/ТЗ фиксируют требования и
|
||||
кандидатные точки, выведенные из фактического кода.
|
||||
|
||||
## 3. Заинтересованные стороны
|
||||
|
||||
- **Заказчик / инициатор:** Стрим (предложение), Слава (одобрение).
|
||||
- **Затрагиваются:** конвейер `orchestrator` (self-hosting); агенты `developer`/`tester`
|
||||
(теперь обязаны держать покрытие); проект enduro-trails — **не должен быть затронут** (гейт
|
||||
по умолчанию неактивен вне сконфигурированных репозиториев).
|
||||
- **Принимает результат:** reviewer (стадия `review`) + финальная стадия конвейера; владелец
|
||||
(Owner) — по факту работы гейта в проде.
|
||||
|
||||
## 4. Бизнес-требования (BR)
|
||||
|
||||
- **BR-1 — Измерение покрытия.** Перед слиянием ветки задачи в `main` покрытие тестами
|
||||
репозитория измеряется инструментально (исполнением тест-сьюта под coverage-инструментацией),
|
||||
а не оценивается на глаз. Результат — числовая метрика покрытия (как минимум line coverage).
|
||||
- **BR-2 — Гейт деградации.** Если измеренное покрытие нарушает политику (ниже абсолютного
|
||||
порога ИЛИ ниже базовой линии — в зависимости от выбранного режима), конвейер **не
|
||||
пропускает** задачу дальше к деплою и инициирует штатный откат на `development` для доработки
|
||||
тестов.
|
||||
- **BR-3 — Базовая линия (ratchet).** Поддерживается режим «не ниже предыдущего»: гейт
|
||||
сравнивает покрытие ветки с зафиксированной базовой линией `main`. Базовая линия **обновляется
|
||||
вверх** при успешном слиянии задачи в `main` (покрытие может только расти или держаться, но
|
||||
не падать).
|
||||
- **BR-4 — Конфигурируемость и нулевая регрессия.** Гейт управляется kill-switch'ем и
|
||||
per-repo областью (по образцу `merge_gate`/`security_gate`/`image_freshness`,
|
||||
ORCH-035/043/058). Для репозиториев вне области (в частности enduro-trails) гейт — **полный
|
||||
no-op**, поведение конвейера 1:1 как до задачи. Порог, политика (absolute|baseline|both) и
|
||||
поведение при ошибке инструмента — настраиваемы.
|
||||
- **BR-5 — Наблюдаемость.** Результат измерения виден: (а) артефакт-отчёт о покрытии с
|
||||
machine-readable вердиктом в `docs/work-items/<id>/`; (б) read-only блок в `GET /queue`;
|
||||
(в) уведомление в Telegram при провале гейта (кликабельный номер задачи, как у прочих
|
||||
алертов). Сообщение указывает измеренное покрытие, порог/базовую линию и дельту.
|
||||
- **BR-6 — Стек-расширяемость.** Логика политики (PASS/FAIL по метрике/базовой линии) и
|
||||
хранилище базовой линии не зависят от конкретного инструмента; добавление измерителя для
|
||||
другого стека (jest/jacoco) в будущем не требует переписывания ядра гейта.
|
||||
|
||||
## 5. Нефункциональные требования (NFR)
|
||||
|
||||
- **NFR-1 — never-raise / fail-safe.** Ядро гейта — изолированный leaf-модуль (по образцу
|
||||
`src/security_gate.py`, `src/serial_gate.py`, `src/labels.py`): любая внутренняя ошибка
|
||||
обрабатывается, исключение **никогда** не всплывает в `advance_stage` и не роняет конвейер
|
||||
всех проектов.
|
||||
- **NFR-2 — Поведение при недоступности/ошибке инструмента.** По умолчанию ошибка измерения
|
||||
(coverage-инструмент упал/недоступен) → **fail-open + громкий warning** (анти-петля,
|
||||
прецедент ORCH-061/ORCH-022 dep-audit), переключаемое в fail-closed флагом. Дефолт не должен
|
||||
заклинивать автономный конвейер из-за инфраструктурного сбоя.
|
||||
- **NFR-3 — Self-hosting безопасность.** Гейт только исполняет тесты в изолированном worktree,
|
||||
читает метрику, пишет отчёт и принимает решение. Он **никогда** не вызывает деплой-хук, не
|
||||
перезапускает прод-контейнер, не пушит/форс-пушит в `main`.
|
||||
- **NFR-4 — Консервативный старт (анти-флап).** Стартовая политика не должна массово заворачивать
|
||||
существующие задачи: базовая линия инициализируется фактическим покрытием `main`, абсолютный
|
||||
порог — как мягкий backstop. Допускается малый отрицательный допуск (epsilon) на шум измерения,
|
||||
чтобы дрожание ±доли процента не заворачивало задачу.
|
||||
- **NFR-5 — Совместимость.** `STAGE_TRANSITIONS`, состав/семантика `QG_CHECKS` и `check_*`,
|
||||
machine-verdict ключи существующих доков (`verdict:`/`result:`/`deploy_status:`/
|
||||
`staging_status:`/`security_status:`) — не меняются. Любая новая БД-сущность — аддитивна
|
||||
(без миграции существующих таблиц). Restart-safe.
|
||||
- **NFR-6 — Детерминизм.** Решение гейта — чистая функция от (измеренное покрытие, базовая
|
||||
линия, порог, политика); без участия LLM в критическом пути (как security/merge/image-freshness
|
||||
под-гейты).
|
||||
|
||||
## 6. Допущения и ограничения
|
||||
|
||||
- Тест-сьют `orchestrator` запускается командой `python -m pytest tests/` из корня репозитория
|
||||
(подтверждено `.gitea/workflows/ci.yml`, `pytest.ini` `testpaths = tests`); измерение покрытия
|
||||
накладывается на этот же прогон.
|
||||
- Coverage-инструмент для Python (`coverage.py` / `pytest-cov`) добавляется как pip-зависимость;
|
||||
он не требует сети во время измерения.
|
||||
- Репозиторий `orchestrator` — единственный self-hosting (предикат `is_self_hosting_repo`);
|
||||
стартовая область гейта — он. enduro-trails и прочие репозитории по умолчанию вне области.
|
||||
- Базовая линия привязана к покрытию `main`; её первичная инициализация выполняется один раз
|
||||
(bootstrap) фактическим замером текущего `main`.
|
||||
- Тесты исполняются в per-branch worktree (`ensure_worktree`), что безопасно при параллельных
|
||||
активных задачах (прецедент `check_tests_local`/merge-gate re-test).
|
||||
|
||||
## 7. Критерии успеха
|
||||
|
||||
- Покрытие тестами `orchestrator` измеряется на каждой задаче и не может опуститься ниже
|
||||
политики, не заблокировав продвижение к деплою.
|
||||
- При выключенном флаге / вне области — конвейер ведёт себя 1:1 как до ORCH-027 (нулевая
|
||||
регрессия для enduro-trails).
|
||||
- Сбой coverage-инструмента не заклинивает автономный конвейер (дефолт fail-open + warning).
|
||||
- Результат измерения прозрачен (отчёт + `GET /queue` + Telegram при провале).
|
||||
|
||||
Детальные PASS/FAIL — `03-acceptance-criteria.md`.
|
||||
|
||||
## 8. Риски
|
||||
|
||||
- **Флап на шуме измерения** — недетерминированное покрытие (например, зависящее от порядка/
|
||||
окружения) может дрожать у границы → ложные заворота. Митигировать epsilon-допуском (NFR-4).
|
||||
- **Петля заворотов** — слишком высокий абсолютный порог завернёт многие задачи в бесконечный
|
||||
rework. Митигировать консервативной стартовой политикой и baseline-режимом.
|
||||
- **Гонка базовой линии** при параллельных слияниях — два слияния в `main` могут конкурентно
|
||||
обновлять baseline. Требуется атомарное/сериализованное обновление (опереться на окно
|
||||
сериализации merge-lease, ORCH-043).
|
||||
- **Инфраструктурная хрупкость** — coverage-инструмент недоступен/несовместим с версией pytest →
|
||||
закрыто требованием NFR-2 (fail-open + warning).
|
||||
|
||||
Детальная техническая проработка рисков — `10-tech-risks.md` (заполняет архитектор).
|
||||
@@ -1,156 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-027
|
||||
stage: analysis
|
||||
author_agent: analyst
|
||||
status: ready-for-review
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# 02 — ТЗ (TRZ): ORCH-027 — Code coverage как гейт
|
||||
|
||||
Work Item: **ORCH-027** · Repo: **orchestrator** · Стадия: analysis
|
||||
|
||||
> ТЗ описывает **конкретные требования к реализации**, выведенные из BRD и фактического кода.
|
||||
> Архитектурное обоснование и выбор механизма (где именно врезать гейт, как хранить базовую
|
||||
> линию, какой инструмент) — задача архитектора (`06-adr/`). Ниже зафиксированы требования и
|
||||
> **кандидатные** точки интеграции, грунтованные реальным кодом; финальное решение по каждой
|
||||
> отмеченной точке принимает архитектор.
|
||||
|
||||
## 1. Сводка изменения
|
||||
|
||||
Вводится **детерминированный гейт покрытия тестами** для репозитория `orchestrator`. Гейт
|
||||
измеряет покрытие исполнением тест-сьюта под coverage-инструментацией, сравнивает с политикой
|
||||
(абсолютный порог и/или базовая линия `main`) и блокирует продвижение задачи к деплою при
|
||||
деградации, инициируя штатный откат на `development`. Ядро — изолированный leaf-модуль с чистой
|
||||
логикой решения (по образцу `security_gate`/`serial_gate`), управляемый kill-switch'ем и per-repo
|
||||
областью; вне области — полный no-op. Базовая линия покрытия `main` хранится персистентно и
|
||||
обновляется вверх при слиянии (ratchet).
|
||||
|
||||
## 2. Задействованные модули / пути
|
||||
|
||||
| Путь | Действие | Назначение |
|
||||
|------|----------|-----------|
|
||||
| `requirements.txt` | изменить | добавить coverage-зависимость Python (`coverage.py` / `pytest-cov`; точный выбор — архитектор) |
|
||||
| `src/coverage_gate.py` | создать | **NEW leaf-модуль**: измерение покрытия (run suite под coverage в `ensure_worktree`), чистые функции `compute_coverage_verdict(measured, baseline, floor, policy, epsilon)` и классификация, чтение/запись отчёта; never-raise; импортирует только `config`/`git_worktree` (+ лениво `qg.checks.is_self_hosting_repo`/`notifications`) |
|
||||
| `src/config.py` | изменить | добавить флаги гейта (см. §6 ниже / раздел совместимости) |
|
||||
| `src/qg/checks.py` | изменить | зарегистрировать механизм проверки покрытия (новый `check_*` ЛИБО делегирование из под-гейта); **семантика существующих `check_*` не меняется** |
|
||||
| `src/stage_engine.py` | изменить *(кандидат)* | врезка под-гейта в `advance_stage` по образцу `_handle_security_gate`/`_handle_merge_gate` — если выбран механизм «edge sub-gate» (см. §3 FR-3) |
|
||||
| `src/db.py` | изменить *(кандидат)* | аддитивная таблица базовой линии покрытия (`coverage_baseline` per-repo), если базовая линия хранится в БД, а не в файле; `_ensure_column`/`CREATE TABLE IF NOT EXISTS` — без миграции существующих |
|
||||
| `.gitea/workflows/ci.yml` | изменить *(кандидат)* | если измерение делается в CI-шаге — добавить `--cov`/порог в прогон pytest; **точка измерения — решение архитектора** |
|
||||
| `src/main.py` | изменить | read-only блок `coverage` в `GET /queue` (наблюдаемость) |
|
||||
| `docs/work-items/<id>/<NN>-coverage-report.md` | создать (артефакт run-time) | отчёт о покрытии с machine-readable вердиктом (см. §4/§6); номер/имя и регистрация в `docs/_standards/PIPELINE_DOCS.md` + скелет в `docs/_templates/` — оформляет архитектор |
|
||||
| `tests/test_coverage_gate.py` | создать | unit/integration по `04-test-plan.yaml` |
|
||||
|
||||
## 3. Функциональные требования
|
||||
|
||||
### FR-1 — Измерение покрытия (привязка BR-1)
|
||||
Гейт исполняет тест-сьют `orchestrator` (`python -m pytest tests/`, см. `.gitea/workflows/ci.yml`)
|
||||
под coverage-инструментацией в изолированном per-branch worktree (`ensure_worktree`, прецедент
|
||||
`check_tests_local`) и извлекает числовую метрику покрытия (как минимум суммарный line coverage,
|
||||
`%`). Тайм-аут на прогон ограничен (по образцу `merge_retest_timeout_s` / `security_scan_timeout_s`).
|
||||
|
||||
### FR-2 — Решение гейта (привязка BR-2, BR-3)
|
||||
Чистая функция `compute_coverage_verdict(measured, baseline, floor, policy, epsilon) -> (ok, reason)`:
|
||||
- `policy = absolute` → PASS ⇔ `measured >= floor - epsilon`.
|
||||
- `policy = baseline` → PASS ⇔ `measured >= baseline - epsilon`.
|
||||
- `policy = both` (дефолт) → PASS ⇔ выполнены оба условия.
|
||||
- FAIL → гейт инициирует штатный откат на `development` для доработки тестов (по образцу
|
||||
`_handle_security_gate` / merge-gate rollback), с инкрементом счётчика developer-retry.
|
||||
- `epsilon` — малый неотрицательный допуск на шум измерения (NFR-4), настраиваемый.
|
||||
|
||||
### FR-3 — Точка в конвейере (привязка BR-2; **кандидат, решает архитектор**)
|
||||
Бизнес-запрос указывает «на testing-гейте». Грунтованные кодом кандидаты (выбрать один):
|
||||
- **(a) Edge sub-gate** в `advance_stage` на ребре `deploy-staging → deploy` (рядом с
|
||||
`_handle_security_gate`/`_handle_merge_gate`/`_handle_image_freshness`) — даёт гарантию «гейт
|
||||
ДО слияния в `main`», детерминирован, владеет исходом на вмешательстве. Предпочтительно для
|
||||
соответствия NFR-3/NFR-6.
|
||||
- **(b) Под-гейт/расширение на ребре `testing → deploy-staging`** (рядом с `check_tests_passed`).
|
||||
- **(c) CI-шаг** в `.gitea/workflows/ci.yml` (ребро `development → review`, читается
|
||||
`check_ci_green`) — порог проверяется самим pytest-прогоном.
|
||||
Требование, инвариантное к выбору: гейт обязан отработать **до фактического merge в `main`** и не
|
||||
пропускать деградацию в `main`.
|
||||
|
||||
### FR-4 — Базовая линия и её обновление (привязка BR-3)
|
||||
- Персистентное per-repo хранилище базовой линии покрытия `main` (БД-таблица ИЛИ файл в репо —
|
||||
решает архитектор; при БД — аддитивная таблица, NFR-5).
|
||||
- Bootstrap: первичная инициализация фактическим замером текущего `main`.
|
||||
- Ratchet-up: при успешном слиянии задачи в `main` базовая линия обновляется значением
|
||||
смёрженного покрытия, **только если оно ≥ текущей** (покрытие не откатывается вниз). Обновление
|
||||
должно быть атомарным/сериализованным относительно параллельных слияний (опереться на окно
|
||||
merge-lease, ORCH-043).
|
||||
|
||||
### FR-5 — Условность и kill-switch (привязка BR-4)
|
||||
- `coverage_gate_enabled=False` → гейт инертен, конвейер 1:1 как до ORCH-027.
|
||||
- `coverage_gate_repos` (CSV) — область применения; **пусто → только self-hosting**
|
||||
(`is_self_hosting_repo`, по образцу `merge_gate`/`security_gate`/`image_freshness`).
|
||||
- Вне области → no-op `(True, "Coverage gate N/A")` (прецедент `check_staging_status` для
|
||||
не-self-hosting, ORCH-035).
|
||||
- `applies(repo)` (локальная проверка) выполняется ПЕРВОЙ; дорогой прогон измерения — только при
|
||||
`applies==True`.
|
||||
|
||||
### FR-6 — Поведение при ошибке инструмента (привязка NFR-2)
|
||||
Ошибка/недоступность coverage-инструмента или невозможность распарсить метрику → по умолчанию
|
||||
**fail-open + WARNING** (`coverage_tool_fail_closed=False`, прецедент `security_dep_audit_fail_closed`);
|
||||
флаг переключает в fail-closed. Поведение логируется явной observability-строкой.
|
||||
|
||||
### FR-7 — Наблюдаемость (привязка BR-5)
|
||||
- Артефакт-отчёт `<NN>-coverage-report.md` с machine-readable вердиктом (см. §4).
|
||||
- Read-only блок `coverage` в `GET /queue` (per-repo: `enabled`/`policy`/`floor`/`baseline`/
|
||||
последнее измеренное/вердикт).
|
||||
- При FAIL — `send_telegram` (notifying) с кликабельным номером задачи (`plane_issue_link`),
|
||||
измеренным покрытием, порогом/базовой линией и дельтой.
|
||||
|
||||
## 4. Изменения API
|
||||
|
||||
- **`GET /queue`** — добавить read-only блок `coverage` (наблюдаемость; форма прочих блоков
|
||||
`serial_gate`/`security`/`merge`). Без изменения существующих полей ответа.
|
||||
- **Опционально (решает архитектор):** ручной эндпоинт сброса/override базовой линии
|
||||
(`POST /coverage/baseline?repo=…`) — по образцу `POST /serial-gate/unfreeze`, на случай
|
||||
легитимного разового снижения покрытия. Если не вводится — override выполняется через конфиг.
|
||||
- Существующие webhook-роуты (`/webhook/plane`, `/webhook/gitea`) — без изменений.
|
||||
|
||||
## 5. Изменения схемы БД
|
||||
|
||||
Зависит от выбора хранилища базовой линии (FR-4):
|
||||
- **Если БД:** аддитивная таблица `coverage_baseline(repo TEXT PRIMARY KEY, coverage REAL,
|
||||
updated_at, source_sha TEXT)` через `CREATE TABLE IF NOT EXISTS` (паттерн `repo_freeze`/
|
||||
`job_deps`). Существующие таблицы — **не мигрируются** (NFR-5).
|
||||
- **Если файл в репо:** изменений схемы БД нет (базовая линия — версионируемый файл вроде
|
||||
`.coverage-baseline.json`, читаемый/обновляемый под merge-lease).
|
||||
|
||||
Выбор — архитектор; ТЗ требует лишь: персистентность, restart-safe, аддитивность, атомарность
|
||||
обновления.
|
||||
|
||||
## 6. Требования к новым/изменённым QG checks
|
||||
|
||||
- **Новый машинный вердикт покрытия.** Если гейт реализован как edge sub-gate (FR-3a/b), он
|
||||
**сам вычисляет** вердикт (как `check_security_gate`) и пишет отчёт `<NN>-coverage-report.md`
|
||||
с frontmatter-ключом `coverage_status:` (`PASS` | `FAIL`), читаемым обратно из того же файла
|
||||
(single source of truth, по образцу `security_status:` в `17-security-report.md`). Имя ключа
|
||||
фиксируется и регистр чувствителен.
|
||||
- **Реестр `QG_CHECKS`.** Допустимо добавить `check_coverage_gate` в реестр (если механизм —
|
||||
зарегистрированный QG) ЛИБО оставить его врезкой-под-гейтом (как security/merge/image-freshness,
|
||||
которые в `QG_CHECKS` присутствуют, но исполняются как врезки). **Семантика и состав
|
||||
существующих `check_*` — без изменений** (NFR-5).
|
||||
- **Парсинг frontmatter** вердикта — через единый контракт `src/frontmatter.py`
|
||||
(`parse_frontmatter`/`read_frontmatter_value`), как все вердикт-парсеры (ORCH-052c). Если
|
||||
отчёт несёт обязательную 6-польную схему 52c — добавить её аддитивно, не трогая `coverage_status:`.
|
||||
|
||||
## 7. Совместимость / регресс
|
||||
|
||||
- **Обратная совместимость:** при `coverage_gate_enabled=False` или для репозитория вне
|
||||
`coverage_gate_repos` — поведение конвейера байт-в-байт прежнее; enduro-trails не затронут.
|
||||
- **Kill-switch + поэтапный раскат:** `coverage_gate_enabled` (глобальный), `coverage_gate_repos`
|
||||
(область). Старт — только `orchestrator`.
|
||||
- **Конфиг-флаги (итог §3/§6):** `coverage_gate_enabled` (bool), `coverage_gate_repos` (CSV),
|
||||
`coverage_min_percent` (float, абсолютный порог), `coverage_policy` (`absolute|baseline|both`,
|
||||
дефолт `both`), `coverage_epsilon` (float, допуск шума), `coverage_tool_fail_closed` (bool,
|
||||
дефолт `False`), `coverage_run_timeout_s` (int). Имена env — `ORCH_COVERAGE_*`.
|
||||
- **never-raise / fail-open в hot-path:** ядро не роняет `advance_stage`; ошибка инструмента →
|
||||
fail-open + warning по умолчанию (NFR-2). Прод-контейнер/`main`/force-push — не трогаются (NFR-3).
|
||||
- **Restart-safe:** базовая линия персистентна; in-flight измерение при рестарте переигрывается
|
||||
штатным механизмом стадии (idempotent).
|
||||
- **Документация (golden source):** при выборе механизма архитектор регистрирует артефакт
|
||||
`<NN>-coverage-report.md` и его machine-key в `docs/_standards/PIPELINE_DOCS.md` +
|
||||
`docs/_templates/`, и обновляет `docs/architecture/README.md` и `CHANGELOG.md` в том же PR.
|
||||
@@ -1,138 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-027
|
||||
stage: analysis
|
||||
author_agent: analyst
|
||||
status: ready-for-review
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# 03 — Критерии приёмки (Acceptance Criteria): ORCH-027 — Code coverage как гейт
|
||||
|
||||
Work Item: **ORCH-027** · Repo: **orchestrator** · Стадия: analysis
|
||||
|
||||
Формат: каждый критерий имеет **PASS** (что должно быть истинно для приёмки) и **FAIL**
|
||||
(что считается провалом). Любой машинный/ручной reviewer проверяет их буквально по файлам
|
||||
репозитория.
|
||||
|
||||
---
|
||||
|
||||
## AC-1 — Покрытие измеряется инструментально
|
||||
|
||||
**Условие:** на применимом репозитории конвейер измеряет покрытие тестами исполнением сьюта под
|
||||
coverage-инструментацией перед слиянием в `main`.
|
||||
- **PASS:** в коде есть путь, который запускает `pytest` под coverage в изолированном worktree и
|
||||
извлекает числовую метрику line coverage (`%`); coverage-зависимость добавлена в `requirements.txt`.
|
||||
- **FAIL:** покрытие не измеряется инструментально, метрика берётся из прозы/вердикта LLM, либо
|
||||
зависимость не объявлена.
|
||||
|
||||
---
|
||||
|
||||
## AC-2 — Гейт блокирует деградацию
|
||||
|
||||
**Условие:** покрытие ниже политики не пропускается дальше к деплою.
|
||||
- **PASS:** при измеренном покрытии ниже порога/базовой линии (с учётом epsilon) гейт даёт FAIL и
|
||||
инициирует штатный откат на `development` (инкремент developer-retry), задача не достигает `done`.
|
||||
- **FAIL:** задача с упавшим покрытием проходит гейт и продвигается к деплою/`done`.
|
||||
|
||||
---
|
||||
|
||||
## AC-3 — Чистая функция решения
|
||||
|
||||
**Условие:** вердикт — детерминированная чистая функция от (measured, baseline, floor, policy, epsilon).
|
||||
- **PASS:** `compute_coverage_verdict(...)` покрыта unit-тестами для всех режимов
|
||||
(`absolute`/`baseline`/`both`), границ (равно порогу), epsilon-допуска; без участия LLM.
|
||||
- **FAIL:** решение принимает LLM, либо логика недетерминирована/не покрыта тестами границ.
|
||||
|
||||
---
|
||||
|
||||
## AC-4 — Режим базовой линии (ratchet)
|
||||
|
||||
**Условие:** поддержан режим «не ниже предыдущего» с обновлением базовой линии вверх при слиянии.
|
||||
- **PASS:** базовая линия персистентна per-repo; при слиянии обновляется значением смёрженного
|
||||
покрытия только если оно ≥ текущей; bootstrap инициализирует её фактическим покрытием `main`;
|
||||
обновление атомарно/сериализовано относительно параллельных слияний.
|
||||
- **FAIL:** базовая линия не хранится / откатывается вниз / обновляется неатомарно (гонка двух
|
||||
слияний теряет/занижает значение).
|
||||
|
||||
---
|
||||
|
||||
## AC-5 — Условность и нулевая регрессия
|
||||
|
||||
**Условие:** вне области / при выключенном флаге — поведение конвейера 1:1 как до ORCH-027.
|
||||
- **PASS:** при `coverage_gate_enabled=False` или repo ∉ `coverage_gate_repos` гейт — no-op
|
||||
(`(True, "...N/A")`); существующая тестовая база (`pytest tests/`) зелёная; enduro-trails не
|
||||
затронут; `applies(repo)` проверяется до дорогого прогона.
|
||||
- **FAIL:** гейт срабатывает вне области, либо выключенный флаг меняет поведение, либо есть
|
||||
регресс существующих тестов.
|
||||
|
||||
---
|
||||
|
||||
## AC-6 — Fail-open по умолчанию при ошибке инструмента
|
||||
|
||||
**Условие:** сбой/недоступность coverage-инструмента не заклинивает автономный конвейер.
|
||||
- **PASS:** при ошибке измерения и `coverage_tool_fail_closed=False` гейт даёт PASS + WARNING-лог
|
||||
(observability-строка); флаг `=True` переключает в fail-closed (FAIL). Поведение покрыто тестом.
|
||||
- **FAIL:** ошибка инструмента по умолчанию заворачивает задачу (петля rework) либо роняет
|
||||
`advance_stage`.
|
||||
|
||||
---
|
||||
|
||||
## AC-7 — never-raise / self-hosting безопасность
|
||||
|
||||
**Условие:** ядро гейта не роняет конвейер и не трогает прод/`main`.
|
||||
- **PASS:** `src/coverage_gate.py` — leaf (не импортирует `stage_engine`); любое исключение
|
||||
перехвачено и не всплывает в `advance_stage`; код не вызывает деплой-хук, не перезапускает
|
||||
прод-контейнер, не пушит/форс-пушит в `main`/`master`.
|
||||
- **FAIL:** исключение из гейта всплывает в `advance_stage`; гейт трогает прод-контейнер или `main`.
|
||||
|
||||
---
|
||||
|
||||
## AC-8 — Совместимость контрактов
|
||||
|
||||
**Условие:** существующие машинные контракты не изменены.
|
||||
- **PASS:** `STAGE_TRANSITIONS`, семантика существующих `check_*`, machine-verdict ключи
|
||||
(`verdict:`/`result:`/`deploy_status:`/`staging_status:`/`security_status:`) — байт-в-байт
|
||||
прежние; любая новая БД-сущность аддитивна (без миграции существующих таблиц).
|
||||
- **FAIL:** изменена семантика/имя существующего гейта или вердикт-ключа; миграция ломает
|
||||
существующую схему.
|
||||
|
||||
---
|
||||
|
||||
## AC-9 — Машинный вердикт покрытия и наблюдаемость
|
||||
|
||||
**Условие:** результат измерения прозрачен и машинно читаем.
|
||||
- **PASS:** при FAIL — Telegram-алерт с кликабельным номером задачи, измеренным покрытием,
|
||||
порогом/базовой линией и дельтой; `GET /queue` несёт read-only блок `coverage`; артефакт-отчёт
|
||||
с machine-readable вердиктом (`coverage_status: PASS|FAIL`) записан и читается обратно из того
|
||||
же файла через `src/frontmatter.py`.
|
||||
- **FAIL:** результат не виден в `GET /queue`/Telegram, либо вердикт парсится из прозы, а не из
|
||||
frontmatter, либо имя ключа не зафиксировано (регистр).
|
||||
|
||||
---
|
||||
|
||||
## AC-10 — Документация обновлена (golden source)
|
||||
|
||||
**Условие:** документация синхронизирована с изменением в том же PR.
|
||||
- **PASS:** если введён артефакт-отчёт — он зарегистрирован в `docs/_standards/PIPELINE_DOCS.md`
|
||||
и `docs/_templates/`; обновлены `docs/architecture/README.md` (описание гейта/флагов) и
|
||||
`CHANGELOG.md`; новые/изменённые инварианты несут маркер `ORCH-027`.
|
||||
- **FAIL:** функционал введён без обновления обзорной/стандартной документации (reviewer →
|
||||
REQUEST_CHANGES, ORCH-079).
|
||||
|
||||
---
|
||||
|
||||
## Сводная матрица AC ↔ FR/BR
|
||||
|
||||
| AC | Покрывает |
|
||||
|----|-----------|
|
||||
| AC-1 | BR-1 / FR-1 |
|
||||
| AC-2 | BR-2 / FR-2, FR-3 |
|
||||
| AC-3 | BR-2 / FR-2 / NFR-6 |
|
||||
| AC-4 | BR-3 / FR-4 |
|
||||
| AC-5 | BR-4 / FR-5 / NFR-5 |
|
||||
| AC-6 | NFR-2 / FR-6 |
|
||||
| AC-7 | NFR-1 / NFR-3 |
|
||||
| AC-8 | NFR-5 / FR-6 (§6 ТЗ) |
|
||||
| AC-9 | BR-5 / FR-7 / §6 ТЗ |
|
||||
| AC-10 | Правила агентов §2/§6 (CLAUDE.md) |
|
||||
@@ -1,110 +0,0 @@
|
||||
work_item: ORCH-027
|
||||
stage: analysis
|
||||
author_agent: analyst
|
||||
status: ready-for-review
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
title: "Code coverage gate — защита от деградации покрытия тестами"
|
||||
framework: pytest
|
||||
scope: >
|
||||
Покрываются: чистая логика вердикта покрытия (режимы absolute/baseline/both, границы,
|
||||
epsilon), ratchet-обновление базовой линии, условность (kill-switch + per-repo область),
|
||||
fail-open/fail-closed при ошибке инструмента, never-raise, наблюдаемость (GET /queue,
|
||||
Telegram при FAIL), интеграция гейта в advance_stage / точку конвейера. Вне покрытия:
|
||||
фактические измерители не-Python стеков (jest/jacoco), мутационное тестирование.
|
||||
notes: >
|
||||
Тесты не должны исполнять реальный прод-деплой и не трогают prod-контейнер/main.
|
||||
Измерение покрытия в тестах мокается/стабится (фиктивная метрика), реальный pytest-прогон
|
||||
под coverage проверяется отдельным интеграционным тестом на минимальном фикстур-репо/worktree.
|
||||
Полный регресс tests/ должен оставаться зелёным (нулевая регрессия для enduro-trails).
|
||||
|
||||
tests:
|
||||
- id: TC-01
|
||||
type: unit
|
||||
description: "compute_coverage_verdict, policy=absolute: measured>=floor → PASS; measured<floor-epsilon → FAIL; ровно на пороге → PASS"
|
||||
module: tests/test_coverage_gate.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-02
|
||||
type: unit
|
||||
description: "compute_coverage_verdict, policy=baseline: measured>=baseline → PASS; ниже baseline-epsilon → FAIL (no-regression / ratchet)"
|
||||
module: tests/test_coverage_gate.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-03
|
||||
type: unit
|
||||
description: "compute_coverage_verdict, policy=both: PASS только при выполнении обоих условий; нарушение любого → FAIL"
|
||||
module: tests/test_coverage_gate.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-04
|
||||
type: unit
|
||||
description: "epsilon-допуск: дрожание покрытия в пределах epsilon у границы не заворачивает задачу (анти-флап, NFR-4)"
|
||||
module: tests/test_coverage_gate.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-05
|
||||
type: unit
|
||||
description: "Ratchet базовой линии: при слиянии baseline растёт до смёрженного покрытия только если >= текущей; меньшее значение не понижает baseline"
|
||||
module: tests/test_coverage_gate.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-06
|
||||
type: unit
|
||||
description: "Bootstrap базовой линии: первичная инициализация фактическим покрытием main при отсутствии сохранённого значения"
|
||||
module: tests/test_coverage_gate.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-07
|
||||
type: unit
|
||||
description: "Условность applies(repo): пустой coverage_gate_repos → только self-hosting (is_self_hosting_repo); repo вне области → no-op (True, 'N/A'), дорогой прогон не запускается"
|
||||
module: tests/test_coverage_gate.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-08
|
||||
type: unit
|
||||
description: "Kill-switch coverage_gate_enabled=False → гейт инертен, advance_stage ведёт себя 1:1 как до ORCH-027"
|
||||
module: tests/test_coverage_gate.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-09
|
||||
type: unit
|
||||
description: "Fail-open по умолчанию: ошибка/недоступность coverage-инструмента и coverage_tool_fail_closed=False → PASS + WARNING-лог; флаг True → FAIL (fail-closed)"
|
||||
module: tests/test_coverage_gate.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-10
|
||||
type: unit
|
||||
description: "never-raise: внутреннее исключение (битый вывод coverage, отсутствие worktree) перехватывается, не всплывает в advance_stage"
|
||||
module: tests/test_coverage_gate.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-11
|
||||
type: unit
|
||||
description: "Запись/чтение отчёта: write_coverage_report пишет coverage_status: PASS|FAIL во frontmatter; parse читает обратно из того же файла через src/frontmatter.py (single source of truth)"
|
||||
module: tests/test_coverage_gate.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-12
|
||||
type: unit
|
||||
description: "Self-hosting безопасность: гейт не вызывает деплой-хук, не перезапускает прод-контейнер, не пушит/форс-пушит в main/master"
|
||||
module: tests/test_coverage_gate.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-13
|
||||
type: integration
|
||||
description: "Гейт в конвейере: при measured ниже политики advance_stage не продвигает к деплою и инициирует откат на development (инкремент developer-retry); при PASS — продвигает штатно"
|
||||
module: tests/test_coverage_gate.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-14
|
||||
type: integration
|
||||
description: "Реальное измерение: pytest под coverage в ensure_worktree на минимальном фикстур-репо возвращает корректную метрику line coverage и тайм-аутится по coverage_run_timeout_s"
|
||||
module: tests/test_coverage_gate.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-15
|
||||
type: integration
|
||||
description: "Наблюдаемость: FAIL даёт Telegram-алерт с кликабельным номером (измеренное/порог/дельта); GET /queue несёт read-only блок coverage; совместимость — STAGE_TRANSITIONS/QG_CHECKS/существующие вердикт-ключи не изменены"
|
||||
module: tests/test_coverage_gate.py
|
||||
expected: PASS
|
||||
@@ -1,266 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-027
|
||||
stage: architecture
|
||||
author_agent: architect
|
||||
status: proposed
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# ADR-001: Гейт покрытия тестами — edge sub-gate с ratchet-базовой линией
|
||||
|
||||
Work Item: **ORCH-027** — детерминированный гейт покрытия тестами, блокирующий деградацию
|
||||
покрытия перед слиянием ветки задачи в `main`.
|
||||
Стадия: **architecture**
|
||||
Сквозная регистрация: **`docs/architecture/adr/adr-0029-coverage-gate.md`** (решение
|
||||
кросс-каттинговое — вводит новый QG `check_coverage_gate`, новый edge-под-гейт ребра
|
||||
`deploy-staging→deploy`, новую аддитивную БД-таблицу `coverage_baseline` и новый артефакт
|
||||
`18-coverage-report.md`).
|
||||
|
||||
## Статус
|
||||
Proposed
|
||||
|
||||
---
|
||||
|
||||
## Контекст
|
||||
|
||||
Оркестратор ведёт **автономную** разработку: код пишет агент `developer` без человека-фильтра,
|
||||
а на стадии `testing` агент `tester` сам решает, достаточно ли тестов. Существующие тестовые
|
||||
гейты судят только по **факту прохождения**, не по **полноте** (сверено по коду):
|
||||
|
||||
- `check_ci_green` (`development → review`) — exit-code `pytest tests/` в Gitea CI
|
||||
(`.gitea/workflows/ci.yml`); покрытие не меряется.
|
||||
- `check_tests_passed` (`testing → deploy-staging`, `qg/checks.py::_parse_tests_verdict`) —
|
||||
читает machine-verdict LLM-`tester`'а из `13-test-report.md`, а не измеренную метрику.
|
||||
- Merge-gate re-test (ORCH-043, `src/merge_gate.py`) — повторный `pytest` на догнанной ветке,
|
||||
снова только exit-code.
|
||||
|
||||
Ни один гейт не замечает «300 строк кода, 0 тестов» или багфикс без регрессионного теста. При
|
||||
пакетном автономном прогоне (ORCH-088, «10–20 задач за ночь») это означает **монотонную
|
||||
деградацию покрытия**: каждая задача срезает угол на тестах, и за десятки задач проект тихо
|
||||
теряет тестируемость. Нужна детерминированная метрика вместо доверия суждению агента — по духу
|
||||
аналогично security-гейту (ORCH-022, adr-0012).
|
||||
|
||||
Требования (`01-brd.md`/`02-trz.md`/`03-acceptance-criteria.md`): измерять покрытие
|
||||
инструментально перед merge в `main` (BR-1/FR-1); блокировать деградацию относительно
|
||||
абсолютного порога и/или базовой линии (BR-2/BR-3/FR-2); хранить и наращивать базовую линию
|
||||
(ratchet, FR-4); kill-switch + per-repo область, нулевая регрессия для enduro-trails
|
||||
(BR-4/FR-5); fail-open по умолчанию при сбое инструмента (NFR-2/FR-6); never-raise и
|
||||
self-hosting-безопасность (NFR-1/NFR-3); неизменность существующих контрактов (NFR-5).
|
||||
|
||||
## Решение
|
||||
|
||||
### Сводка
|
||||
|
||||
Вводим **детерминированный (без LLM) гейт покрытия** как **под-гейт ребра
|
||||
`deploy-staging → deploy`** — рядом с security-gate (ORCH-022), merge-gate (ORCH-043) и
|
||||
image-freshness (ORCH-058), исполняемый **ПОСЛЕ merge-gate и ДО image-freshness**.
|
||||
`STAGE_TRANSITIONS` не меняется; в `QG_CHECKS` добавляется `check_coverage_gate`. Паттерн —
|
||||
1:1 как у соседних под-гейтов: leaf-модуль `src/coverage_gate.py` (never-raise) + тонкая
|
||||
обёртка в `QG_CHECKS` + врезка `_handle_coverage_gate` в `advance_stage`. Базовая линия `main`
|
||||
хранится в **аддитивной БД-таблице** `coverage_baseline` и наращивается **вверх** (ratchet) в
|
||||
choke-point подтверждённого merge `_handle_merge_verify` (ребро `deploy → done`). Вердикт
|
||||
пишется в артефакт `18-coverage-report.md` (frontmatter-ключ `coverage_status:`) и читается
|
||||
обратно из того же файла (single source of truth, как `security_status:`).
|
||||
|
||||
### D1 — Точка в конвейере: edge sub-gate `deploy-staging → deploy`, ПОСЛЕ merge-gate (FR-3a)
|
||||
|
||||
Из трёх кандидатов TRZ FR-3 выбран **(a) edge sub-gate** на ребре `deploy-staging → deploy`
|
||||
(`advance_stage`, `src/stage_engine.py`, блок `current_stage == "deploy-staging"`). Это даёт
|
||||
структурную гарантию «гейт ДО merge в `main`» (merge выполняется детерминированным merge-актором
|
||||
в `_handle_merge_verify` на ребре `deploy → done`), детерминизм и владение исходом на
|
||||
вмешательстве — полное соответствие NFR-3/NFR-6.
|
||||
|
||||
**Порядок среди под-гейтов: security → merge → `coverage` → image-freshness.** Обоснование:
|
||||
|
||||
- **ПОСЛЕ merge-gate (а не первым, как security).** Merge-gate выполняет догон ветки на свежий
|
||||
`origin/main` (`auto_rebase_onto_main` под merge-lease, ORCH-043/026). Покрытие имеет смысл
|
||||
мерить на **догнанном** HEAD — это ровно тот код, что landed в `main`; измерение до rebase
|
||||
показало бы покрытие устаревшей базы. Поэтому coverage **обязан** идти после merge-gate
|
||||
(в отличие от security, который специально фейлит дёшево ДО rebase).
|
||||
- **ДО image-freshness.** Прогон pytest под coverage дорог, но дешевле полного docker-rebuild
|
||||
staging-образа. Фейлить покрытие до rebuild — экономия (паттерн «fail before expensive
|
||||
rebuild», 07-infra security-гейта).
|
||||
- **Merge-lease held на этой точке.** Merge-gate уже захватил merge-lease (ORCH-043). Значит
|
||||
**FAIL coverage обязан освободить merge-lease** при откате — как делает image-freshness
|
||||
rollback (`merge_gate.release_merge_lease`, `stage_engine.py:1165`), и **в отличие** от
|
||||
security-gate rollback (тот идёт ДО захвата lease и lease не трогает). Это явный инвариант
|
||||
реализации (TR-2).
|
||||
|
||||
Привязка: BR-2/FR-3/AC-2; NFR-3/AC-7.
|
||||
|
||||
### D2 — Измеритель: `pytest-cov` (`coverage.py`), `--cov=src` (FR-1, BR-6)
|
||||
|
||||
В `requirements.txt` добавляется **`pytest-cov`** (плагин-обёртка над `coverage.py`). Измерение —
|
||||
прогон `python -m pytest tests/ --cov=src --cov-report=json:<tmp>/coverage.json
|
||||
--cov-report=` в изолированном per-branch worktree (`ensure_worktree`, прецедент
|
||||
`check_tests_local`/merge-gate re-test). Числовая метрика — `totals.percent_covered` из JSON
|
||||
(line coverage, `%`). Скоуп измерения — **`src/`** (не `tests/`: покрытие самих тестов вне
|
||||
объёма, BRD §«Вне объёма»). Сеть при измерении не нужна. Тайм-аут — `coverage_run_timeout_s`
|
||||
(по образцу `merge_retest_timeout_s`/`security_scan_timeout_s`).
|
||||
|
||||
**Стек-расширяемость (BR-6/AC-… BR-6):** измеритель инкапсулирован за функцией
|
||||
`measure_coverage(repo, branch) -> float | None`; чистая логика решения
|
||||
`compute_coverage_verdict(...)` и хранилище базовой линии **не зависят** от Python/pytest.
|
||||
Добавление jest/jacoco-измерителя для будущего стека — новая ветка `measure_*`, без переписывания
|
||||
ядра. Фактическая интеграция не-Python стеков — вне объёма ORCH-027.
|
||||
|
||||
### D3 — Чистая функция решения (FR-2, NFR-6, BR-2/BR-3)
|
||||
|
||||
`compute_coverage_verdict(measured, baseline, floor, policy, epsilon) -> (ok: bool, reason: str)` —
|
||||
детерминированная чистая функция (без LLM, без I/O):
|
||||
|
||||
- `policy = "absolute"` → PASS ⇔ `measured >= floor - epsilon`.
|
||||
- `policy = "baseline"` → PASS ⇔ `measured >= baseline - epsilon`.
|
||||
- `policy = "both"` (дефолт) → PASS ⇔ выполнены **оба** условия.
|
||||
- `baseline is None` (нет сохранённой базовой линии) → baseline-условие **не применяется**
|
||||
(bootstrap: нельзя регрессировать против пустоты) → решает только absolute-часть; измеренное
|
||||
значение засеет базовую линию при merge (D5).
|
||||
- `epsilon` — малый неотрицательный допуск на шум измерения (NFR-4/AC-4): дрожание ±доли
|
||||
процента у границы не заворачивает задачу.
|
||||
|
||||
FAIL → штатный откат на `development` + инкремент общего `_developer_retry_count` (cap
|
||||
`MAX_DEVELOPER_RETRIES`, затем `set_issue_blocked` + Telegram) — точно как security/merge-gate
|
||||
rollback. Дословный reason (измеренное/порог/базовая линия/дельта) встраивается в `task_desc`
|
||||
developer'а (паттерн ORCH-046). Привязка: AC-2/AC-3.
|
||||
|
||||
### D4 — Хранилище базовой линии: аддитивная БД-таблица `coverage_baseline` (FR-4, NFR-5)
|
||||
|
||||
Базовая линия `main` хранится в **БД**, не в файле репозитория:
|
||||
|
||||
```sql
|
||||
CREATE TABLE IF NOT EXISTS coverage_baseline (
|
||||
repo TEXT PRIMARY KEY,
|
||||
coverage REAL NOT NULL,
|
||||
source_sha TEXT,
|
||||
updated_at TEXT NOT NULL
|
||||
);
|
||||
```
|
||||
|
||||
(паттерн `repo_freeze`/`job_deps` — `CREATE TABLE IF NOT EXISTS`, существующие таблицы не
|
||||
мигрируются, NFR-5/AC-8; детали — `08-data-requirements.md`). **Почему БД, а не файл в репо**
|
||||
(`.coverage-baseline.json`): файл пришлось бы коммитить в `main` на каждый ratchet → git-churn,
|
||||
сам файл попадает в diff и может конфликтовать при параллельных merge, плюс он часть измеряемого
|
||||
дерева. БД-таблица — restart-safe, аддитивна, обновляется атомарно и не порождает коммитов.
|
||||
Таблица keyed by `repo` → общая прод-БД (self-hosting) безопасно разделяет базовые линии разных
|
||||
репозиториев.
|
||||
|
||||
### D5 — Ratchet-up в choke-point подтверждённого merge (FR-4, BR-3)
|
||||
|
||||
Базовая линия наращивается **только вверх** и **только при подтверждённом** слиянии в `main`.
|
||||
Единственный авторитетный choke-point подтверждённого merge — `_handle_merge_verify` (ребро
|
||||
`deploy → done`, ORCH-071/073, доказательство SHA-in-main). Туда добавляется never-raise врезка
|
||||
`coverage_gate.ratchet_baseline_on_merge(repo, work_item_id, branch, sha)`, вызываемая **после**
|
||||
того как merge подтверждён (`_handle_merge_verify` вернул `False` = confirmed) и **до** перехода
|
||||
в `done`:
|
||||
|
||||
1. Читает измеренное покрытие смёрженной ветки из артефакта `18-coverage-report.md` (single
|
||||
source of truth — то же значение, что гейт записал на ребре `deploy-staging→deploy`).
|
||||
2. **Атомарный compare-and-set:** `UPDATE coverage_baseline SET coverage=?, source_sha=?,
|
||||
updated_at=? WHERE repo=? AND coverage <= ?` (или `INSERT` при отсутствии строки —
|
||||
bootstrap). Условие `coverage <= measured` гарантирует, что базовая линия **никогда не
|
||||
падает** (FR-4), даже при гонке.
|
||||
|
||||
**Сериализация (анти-гонка, NFR-5/AC-4):** на этой точке merge-lease ещё **held** (release на
|
||||
`done`/rollback, `stage_engine.py:446`), а merge репо сериализован per-repo (ORCH-043). Плюс
|
||||
атомарный compare-and-set в SQL — **двойная защита**: даже без lease два параллельных merge не
|
||||
понизят и не потеряют значение. Bootstrap — первый merge применимого репо засевает базовую линию
|
||||
своим измеренным покрытием.
|
||||
|
||||
### D6 — Условность, kill-switch, наблюдаемость (FR-5/FR-7, BR-4/BR-5)
|
||||
|
||||
- **Флаги (`config.py`, env `ORCH_COVERAGE_*`):** `coverage_gate_enabled` (bool, kill-switch),
|
||||
`coverage_gate_repos` (CSV; **пусто → только self-hosting** `is_self_hosting_repo`, по образцу
|
||||
`merge_gate`/`security_gate`/`image_freshness`), `coverage_min_percent` (float, абсолютный
|
||||
порог-floor), `coverage_policy` (`absolute|baseline|both`, дефолт `both`), `coverage_epsilon`
|
||||
(float, дефолт малый, напр. `0.5`), `coverage_tool_fail_closed` (bool, дефолт `False`),
|
||||
`coverage_run_timeout_s` (int).
|
||||
- **`applies(repo)`** (локальная проверка) выполняется **ПЕРВОЙ**; дорогой прогон измерения —
|
||||
только при `applies==True`. Вне области → no-op `(True, "Coverage gate N/A")` (прецедент
|
||||
`check_staging_status` для не-self, ORCH-035). При `coverage_gate_enabled=False` — гейт инертен,
|
||||
конвейер 1:1 как до ORCH-027 (AC-5).
|
||||
- **FR-6 (ошибка инструмента):** `measure_coverage` вернул `None` (инструмент упал/недоступен/
|
||||
метрика не распарсилась) → по умолчанию **fail-open + WARNING** (observability-строка),
|
||||
`coverage_tool_fail_closed=True` → fail-closed (FAIL). Дефолт анти-петля (прецедент
|
||||
ORCH-061/ORCH-022 dep-audit), чтобы инфра-сбой не заклинил автономный конвейер.
|
||||
- **FR-7 (наблюдаемость):** артефакт `18-coverage-report.md` (frontmatter `coverage_status:
|
||||
PASS|FAIL` + `measured_coverage`/`baseline`/`floor`/`policy`/`delta`); read-only блок
|
||||
`coverage` в `GET /queue` (`src/main.py`); при FAIL — `send_telegram` с кликабельным номером
|
||||
(`plane_issue_link`/`link_for`), измеренным покрытием, порогом/базовой линией и дельтой.
|
||||
|
||||
### D7 — Машинный вердикт и парсинг (§6 ТЗ, AC-9)
|
||||
|
||||
Гейт **сам вычисляет** вердикт (как `check_security_gate`) и пишет
|
||||
`18-coverage-report.md` с YAML-frontmatter `coverage_status:` (`PASS` | `FAIL`); регистр
|
||||
чувствителен, имя фиксируется. Чтение обратно — через единый контракт `src/frontmatter.py`
|
||||
(`parse_frontmatter`/`read_frontmatter_value`, ORCH-052c), как все вердикт-парсеры. Артефакт
|
||||
несёт **аддитивно** обязательную 6-польную схему 52c, не трогая `coverage_status:`. В `QG_CHECKS`
|
||||
добавляется `check_coverage_gate` (тонкая обёртка, делегирующая в leaf); **семантика и состав
|
||||
существующих `check_*` / machine-verdict ключей (`verdict:`/`result:`/`deploy_status:`/
|
||||
`staging_status:`/`security_status:`) — байт-в-байт прежние** (NFR-5/AC-8).
|
||||
|
||||
### D8 — Опциональный override базовой линии (FR-4 / §4 API)
|
||||
|
||||
Для легитимного разового снижения покрытия (напр. удаление большого протестированного модуля)
|
||||
вводится опциональный ручной эндпоинт `POST /coverage/baseline?repo=<repo>&value=<float>` (по
|
||||
образцу `POST /serial-gate/unfreeze`) — устанавливает/сбрасывает базовую линию вручную.
|
||||
Альтернатива без эндпоинта — временно переключить `coverage_policy=absolute`. Эндпоинт
|
||||
рекомендован для эксплуатационной гибкости, но не критичен для v1.
|
||||
|
||||
## Альтернативы
|
||||
|
||||
- **Точка измерения — CI-job (`check_ci_green`, FR-3c).** Пороги/политика/базовая линия/артефакт
|
||||
плохо выражаются статусом коммита; ratchet требует записи в общую БД, недоступную из CI-раннера
|
||||
чисто. Коуплинг с раннером. Отклонено для v1 (точка расширения), как у security-гейта.
|
||||
- **Точка измерения — `testing → deploy-staging` (рядом с `check_tests_passed`, FR-3b).** Ветка
|
||||
ещё не догнана на свежий `main` → измеренное покрытие может не соответствовать landed-коду;
|
||||
откат отсюда не освобождает merge-lease иначе. Edge `deploy-staging→deploy` после merge-gate —
|
||||
точнее. Отклонено.
|
||||
- **Базовая линия в файле репо (`.coverage-baseline.json`).** Git-churn на каждый ratchet,
|
||||
конфликты при параллельных merge, файл — часть измеряемого дерева. Отклонено в пользу
|
||||
аддитивной БД-таблицы (D4).
|
||||
- **Складывание измерения в merge-gate re-test (один pytest-прогон).** Снижает дабл-ран, но
|
||||
коуплит coverage-логику с merge_gate; нарушает leaf-изоляцию ТЗ. Отклонено для v1 (возможный
|
||||
follow-up — измерять покрытие в том же прогоне).
|
||||
- **Новый stage `coverage`.** «Пустая» стадия без агента не имеет триггера (как в ORCH-043/022).
|
||||
Отклонено.
|
||||
- **Жёсткий абсолютный порог без baseline/epsilon.** Массовые ложные заворота → петля rework.
|
||||
Отклонено в пользу консервативного `both` + epsilon (NFR-4).
|
||||
|
||||
## Последствия
|
||||
|
||||
- **+** Класс «тихо просевшее покрытие» закрыт детерминированной метрикой; защита от монотонной
|
||||
деградации в пакетном автономном прогоне (ORCH-088). Базовая линия может только расти (ratchet).
|
||||
- **+** Нулевая регрессия: при выключенном флаге / вне области (enduro-trails) — конвейер
|
||||
байт-в-байт прежний; `STAGE_TRANSITIONS`/`QG_CHECKS`-семантика/вердикт-ключи не тронуты.
|
||||
- **+** Self-hosting-безопасно: гейт только мерит/читает/пишет/решает; не деплоит, не рестартит
|
||||
прод, не пушит/форс-пушит в `main` (NFR-3).
|
||||
- **−** Дополнительный прогон pytest под coverage на каждой применимой задаче (после merge-gate
|
||||
re-test) → ещё один полный тест-ран. Митигейшн: ограничен `coverage_run_timeout_s`; фейлит до
|
||||
дорогого image-rebuild; follow-up — слияние с merge-gate re-test.
|
||||
- **−** Ещё один «скрытый» под-гейт ребра (нет в `STAGE_TRANSITIONS`); новая pip-зависимость
|
||||
(`pytest-cov`); v1 — Python-only (мульти-стек — точка расширения BR-6).
|
||||
- **−** Дефолтный fail-open означает, что устойчивый сбой инструмента **тихо** пропускает задачи
|
||||
(с WARNING). Митигейшн: громкий лог + переключатель `coverage_tool_fail_closed`.
|
||||
- **Сквозное изменение** (новый QG + edge-под-гейт + новая БД-таблица + новый артефакт) →
|
||||
лейбл `arch:major-change`; прод-деплой ORCH-027 — строго через staging-гейт (8501), без
|
||||
рестарта прод-контейнера.
|
||||
- **Откат:** `coverage_gate_enabled=False` → полный no-op (мгновенный обратимый kill-switch).
|
||||
Полное удаление — снять врезки `_handle_coverage_gate`/`ratchet_baseline_on_merge`, удалить
|
||||
leaf-модуль, `check_coverage_gate` из `QG_CHECKS`, флаги, артефакт-шаблон; таблица
|
||||
`coverage_baseline` аддитивна и может остаться (инертна).
|
||||
|
||||
## Ссылки
|
||||
|
||||
- BRD: `docs/work-items/ORCH-027/01-brd.md`
|
||||
- TRZ: `docs/work-items/ORCH-027/02-trz.md`
|
||||
- Acceptance: `docs/work-items/ORCH-027/03-acceptance-criteria.md`
|
||||
- Data: `docs/work-items/ORCH-027/08-data-requirements.md`
|
||||
- Risks: `docs/work-items/ORCH-027/10-tech-risks.md`
|
||||
- Сквозной ADR: `docs/architecture/adr/adr-0029-coverage-gate.md`
|
||||
- Сверено по коду: `src/stage_engine.py` (`_handle_security_gate`/`_handle_merge_gate`/
|
||||
`_handle_image_freshness`/`_handle_merge_verify`), `src/security_gate.py`, `src/merge_gate.py`,
|
||||
`src/qg/checks.py`, `.gitea/workflows/ci.yml`, `pytest.ini`
|
||||
- Прецеденты: adr-0012 (security-гейт), adr-0006 (merge-gate — edge-под-гейт/откат/lease),
|
||||
adr-0008 (image-freshness — условность/fail-closed), adr-0003 (`is_self_hosting_repo`),
|
||||
adr-0009 (анти-петля ложных FAIL), adr-0014 (SHA-in-main как source of truth для merge)
|
||||
@@ -1,64 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-027
|
||||
stage: architecture
|
||||
author_agent: architect
|
||||
status: proposed
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# 07 — Инфраструктурные требования: ORCH-027 — Code coverage как гейт
|
||||
|
||||
Work Item: **ORCH-027** · Repo: **orchestrator** · Стадия: architecture
|
||||
|
||||
> When-applicable. Топология **не меняется** (всё в существующем Docker-контейнере на одном
|
||||
> сервере mva154, SQLite, собственная очередь). Затрагивается только зависимостный и
|
||||
> конфигурационный слой.
|
||||
|
||||
## Топология / окружение
|
||||
|
||||
- **Без изменений топологии** — никаких новых контейнеров/сервисов/нод. Гейт исполняется внутри
|
||||
существующего процесса оркестратора, измерение — в per-branch worktree (`ensure_worktree`),
|
||||
как merge-gate re-test. `docs/operations/INFRA.md` — без правок.
|
||||
- **Self-hosting безопасность (NFR-3):** гейт не вызывает деплой-хук, не рестартит прод-контейнер
|
||||
`orchestrator` (8500), не пушит в `main`. Прод-деплой ORCH-027 — **только** через
|
||||
staging-гейт (8501) → выделенный статус «Confirm Deploy» (ORCH-059), без рестарта прод
|
||||
случайным approve.
|
||||
|
||||
## Зависимости
|
||||
|
||||
| Зависимость | Где | Назначение |
|
||||
|-------------|-----|-----------|
|
||||
| `pytest-cov` (обёртка `coverage.py`) | `requirements.txt` | измерение line coverage прогоном `pytest --cov=src --cov-report=json`. Offline (сеть при измерении не нужна). Попадает в прод-образ при пересборке. |
|
||||
|
||||
- Версия фиксируется совместимой с текущим `pytest` (см. `requirements.txt`/`pytest.ini`).
|
||||
- Новых системных пакетов в `Dockerfile` не требуется (чистый pip-пакет).
|
||||
|
||||
## Конфигурация (env, `.env` на хосте)
|
||||
|
||||
Новые флаги (`config.py`, префикс `ORCH_COVERAGE_*`; дефолты безопасны — нулевая регрессия):
|
||||
|
||||
| Env | Дефолт | Назначение |
|
||||
|-----|--------|-----------|
|
||||
| `ORCH_COVERAGE_GATE_ENABLED` | `false` (раскат поэтапный) | kill-switch |
|
||||
| `ORCH_COVERAGE_GATE_REPOS` | пусто → только self-hosting | CSV область применения |
|
||||
| `ORCH_COVERAGE_MIN_PERCENT` | консервативно (напр. backstop) | абсолютный порог-floor |
|
||||
| `ORCH_COVERAGE_POLICY` | `both` | `absolute\|baseline\|both` |
|
||||
| `ORCH_COVERAGE_EPSILON` | малый (напр. `0.5`) | допуск на шум измерения |
|
||||
| `ORCH_COVERAGE_TOOL_FAIL_CLOSED` | `false` | поведение при сбое инструмента |
|
||||
| `ORCH_COVERAGE_RUN_TIMEOUT_S` | по образцу `merge_retest_timeout_s` | тайм-аут прогона |
|
||||
|
||||
## Эксплуатационные предусловия
|
||||
|
||||
- **Bootstrap базовой линии:** при первом merge применимого репо базовая линия `main`
|
||||
засевается автоматически фактическим измеренным покрытием (D5). Ручной первичный замер не
|
||||
обязателен; при необходимости — `POST /coverage/baseline?repo=orchestrator&value=<%>` (D8).
|
||||
- **Раскат:** включать `ORCH_COVERAGE_GATE_ENABLED=true` только после прод-деплоя кода и
|
||||
прогона на staging (8501); стартовая область — только `orchestrator`.
|
||||
- **Override (легитимное снижение покрытия):** `POST /coverage/baseline` (по образцу
|
||||
`POST /serial-gate/unfreeze`) либо временный `ORCH_COVERAGE_POLICY=absolute`.
|
||||
|
||||
## Секреты / сеть
|
||||
|
||||
- Новых секретов нет. Сетевого доступа при измерении нет (coverage offline).
|
||||
- enduro-trails и прочие репозитории — вне области по умолчанию, нулевое влияние.
|
||||
@@ -1,67 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-027
|
||||
stage: architecture
|
||||
author_agent: architect
|
||||
status: proposed
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# 08 — Требования к данным: ORCH-027 — Code coverage как гейт
|
||||
|
||||
Work Item: **ORCH-027** · Repo: **orchestrator** · Стадия: architecture
|
||||
|
||||
> When-applicable / информационный (гейтом не парсится). Затрагивается схема БД — вводится
|
||||
> **одна аддитивная таблица** базовой линии покрытия. Существующие таблицы не мигрируются.
|
||||
|
||||
## Изменения схемы БД
|
||||
|
||||
Новая аддитивная таблица `coverage_baseline` (паттерн `repo_freeze`/`job_deps` —
|
||||
`CREATE TABLE IF NOT EXISTS` в `init_db`, `src/db.py`; без `ALTER`/миграции существующих):
|
||||
|
||||
```sql
|
||||
CREATE TABLE IF NOT EXISTS coverage_baseline (
|
||||
repo TEXT PRIMARY KEY, -- репозиторий (напр. "orchestrator")
|
||||
coverage REAL NOT NULL, -- last-known базовая линия покрытия main (%, line coverage)
|
||||
source_sha TEXT, -- SHA main, на котором зафиксирована базовая линия (аудит)
|
||||
updated_at TEXT NOT NULL -- ISO-таймстамп последнего ratchet/bootstrap
|
||||
);
|
||||
```
|
||||
|
||||
Доступ — через аддитивные read-only/мутирующие хелперы `src/db.py`:
|
||||
- `get_coverage_baseline(repo) -> float | None` (None ⇒ bootstrap-режим, базовой линии ещё нет);
|
||||
- `ratchet_coverage_baseline(repo, coverage, sha) -> bool` — **атомарный compare-and-set**:
|
||||
`INSERT` при отсутствии строки; иначе `UPDATE ... SET coverage=?, source_sha=?, updated_at=?
|
||||
WHERE repo=? AND coverage <= ?` (базовая линия **никогда не понижается**);
|
||||
- `set_coverage_baseline(repo, coverage, sha)` — безусловная установка (ручной override D8 /
|
||||
`POST /coverage/baseline`).
|
||||
|
||||
## Новые/изменённые сущности
|
||||
|
||||
- **`coverage_baseline`** — одна строка на репозиторий; keyed by `repo`. Инвариант: `coverage`
|
||||
монотонно не убывает через `ratchet_coverage_baseline` (только `set_coverage_baseline`/ручной
|
||||
override может понизить — легитимный разовый случай, D8). На общей прод-БД (self-hosting)
|
||||
строки разных репозиториев изолированы первичным ключом.
|
||||
- **Артефакт `18-coverage-report.md`** — НЕ БД-сущность: файл в `docs/work-items/<id>/`,
|
||||
несёт frontmatter `coverage_status: PASS|FAIL` + `measured_coverage`/`baseline`/`floor`/
|
||||
`policy`/`delta`. Source of truth измеренного значения для ratchet (D5).
|
||||
|
||||
Существующие таблицы (`tasks`, `jobs`, `job_deps`, `repo_freeze`, `agent_runs`,
|
||||
`tracker_messages`, …) — **не изменяются** (NFR-5/AC-8).
|
||||
|
||||
## Совместимость данных / миграции
|
||||
|
||||
- **Аддитивность:** только `CREATE TABLE IF NOT EXISTS` — ни один существующий столбец/таблица
|
||||
не трогается; миграции существующих данных нет.
|
||||
- **Идемпотентность:** `CREATE TABLE IF NOT EXISTS` безопасен при повторном старте; bootstrap
|
||||
(первый `INSERT`) выполняется один раз на репозиторий.
|
||||
- **Restart-safe:** базовая линия персистентна; in-flight измерение при рестарте переигрывается
|
||||
штатным механизмом стадии (idempotent — гейт пересчитает вердикт, ratchet — атомарный
|
||||
compare-and-set, повтор не понизит и не задвоит).
|
||||
- **Атомарность / анти-гонка:** ratchet — единичный SQL `UPDATE ... WHERE coverage <= ?` (или
|
||||
`INSERT`), выполняется под held merge-lease (ORCH-043, per-repo сериализация merge) → двойная
|
||||
защита от параллельных слияний.
|
||||
- **Влияние на общую прод-БД:** одна маленькая таблица (≤ числа репозиториев строк); нулевой
|
||||
риск для enduro-trails и прочих проектов (строки изолированы по `repo`, гейт для них no-op).
|
||||
- При `coverage_gate_enabled=False` таблица может существовать пустой/инертной — нулевая
|
||||
регрессия.
|
||||
@@ -1,42 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-027
|
||||
stage: architecture
|
||||
author_agent: architect
|
||||
status: proposed
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# 10 — Технические риски: ORCH-027 — Code coverage как гейт
|
||||
|
||||
Work Item: **ORCH-027** · Repo: **orchestrator** · Стадия: architecture
|
||||
|
||||
> Информационный (гейтом не парсится). Перечисляет риски реализации и их митигейшн.
|
||||
|
||||
## Реестр рисков
|
||||
|
||||
| ID | Риск | Вер. | Влия. | Митигейшн |
|
||||
|----|------|------|-------|-----------|
|
||||
| TR-1 | **Флап на шуме измерения** — недетерминированное покрытие (порядок тестов/окружение) дрожит у границы → ложные заворота, петля rework. | Сред. | Сред. | `coverage_epsilon` (NFR-4/D3): дрожание ±доли % не заворачивает. Дефолт `policy=both` мягкий; абсолютный порог — backstop, не агрессивный. |
|
||||
| TR-2 | **Не освобождён merge-lease при FAIL.** Coverage идёт ПОСЛЕ merge-gate (lease уже held) — забытый release при откате заклинит serial-gate репо (другие задачи репо в defer навсегда). | Сред. | Выс. | Явный инвариант D1: rollback coverage вызывает `merge_gate.release_merge_lease` (как image-freshness rollback, `stage_engine.py:1165`); покрыто тестом TC-13. Backstop — crash-реклейм lease по возрасту (ORCH-043). |
|
||||
| TR-3 | **Гонка базовой линии** — два параллельных слияния в `main` конкурентно обновляют baseline, теряя/занижая значение. | Низ. | Сред. | Атомарный SQL compare-and-set `UPDATE ... WHERE coverage <= ?` (D5/08-data) + held merge-lease + per-repo сериализация merge (ORCH-043) → тройная защита. Покрыто TC-05. |
|
||||
| TR-4 | **Инфра-хрупкость инструмента** — `pytest-cov` несовместим с версией pytest / упал / метрика не парсится → конвейер клинит. | Низ. | Сред. | NFR-2/FR-6/D6: дефолт fail-open + громкий WARNING (анти-петля ORCH-061); `coverage_tool_fail_closed` для строгого режима. `measure_coverage`→`None` обрабатывается, не всплывает. Покрыто TC-09. |
|
||||
| TR-5 | **Исключение всплывает в `advance_stage`** — ошибка leaf-модуля роняет конвейер ВСЕХ проектов (общий прод-инстанс). | Низ. | Выс. | NFR-1/AC-7: `src/coverage_gate.py` — leaf (не импортирует `stage_engine`), контракт never-raise; любое исключение → `(False/True, reason)` по политике fail-open/closed. Покрыто TC-10. |
|
||||
| TR-6 | **Дабл-ран pytest** — coverage-прогон после merge-gate re-test удваивает время тестов на применимой задаче. | Выс. | Низ. | Ограничен `coverage_run_timeout_s`; фейлит ДО дорогого image-rebuild; follow-up — слияние измерения с merge-gate re-test (вне объёма v1). Влияет только на self-hosting `orchestrator`. |
|
||||
| TR-7 | **Стартовая петля заворотов** — высокий `coverage_min_percent` массово заворачивает существующие задачи в rework. | Сред. | Сред. | NFR-4/D3: bootstrap инициализирует baseline фактическим покрытием `main`; absolute-порог — мягкий backstop; cap `MAX_DEVELOPER_RETRIES` → Blocked+alert вместо бесконечной петли. |
|
||||
| TR-8 | **Self-hosting побочка** — гейт случайно трогает прод-контейнер/`main`/force-push. | Низ. | Выс. | NFR-3/AC-7: гейт только мерит/читает/пишет/решает в изолированном worktree; не вызывает деплой-хук, не рестартит прод, не пушит в `main`. Покрыто TC-12. |
|
||||
| TR-9 | **Регресс контрактов** — затронуты `STAGE_TRANSITIONS`/существующие `check_*`/вердикт-ключи. | Низ. | Выс. | NFR-5/AC-8: новый QG аддитивен, edge-врезка не меняет `STAGE_TRANSITIONS`; вердикт-ключи прежних доков байт-в-байт. Покрыто TC-15. |
|
||||
|
||||
## Сводный вывод
|
||||
|
||||
Доминирующий класс рисков — **эксплуатация автономного self-hosting-конвейера**: самые
|
||||
тяжёлые по влиянию (TR-2 заклинивание serial-gate, TR-5 падение конвейера всех проектов, TR-8
|
||||
побочка на прод) имеют **низкую вероятность** и закрыты структурными инвариантами, повторяющими
|
||||
проверенные паттерны соседних под-гейтов (security/merge/image-freshness): leaf never-raise,
|
||||
fail-open дефолт, явный release merge-lease при откате, kill-switch. Остаточный риск для
|
||||
прод-конвейера — **низкий** при условии тестового покрытия инвариантов TR-2/TR-5/TR-8
|
||||
(`04-test-plan.yaml` TC-09…TC-13) и поэтапного раската через staging-гейт (8501).
|
||||
|
||||
Решение **сквозное** (новый QG + edge-под-гейт + новая БД-таблица + новый артефакт) → эскалация
|
||||
лейблом **`arch:major-change`**. Возврат в анализ не требуется — ТЗ реализуемо без нарушения
|
||||
принципов архитектуры (Docker/один сервер/SQLite/собственная очередь сохранены).
|
||||
@@ -1,121 +0,0 @@
|
||||
---
|
||||
verdict: APPROVED
|
||||
work_item: ORCH-027
|
||||
stage: review
|
||||
author_agent: reviewer
|
||||
status: approved
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
type: review
|
||||
work_item_id: ORCH-027
|
||||
version: 2
|
||||
---
|
||||
|
||||
# Review ORCH-027 — Code coverage как гейт
|
||||
|
||||
## Summary
|
||||
|
||||
Дисциплинированная реализация детерминированного coverage-гейта строго по образцу
|
||||
security/merge/image-freshness под-гейтов. Соответствие ТЗ/ADR — полное; код качественный,
|
||||
тесты содержательны (`test_coverage_gate.py` — 30 тестов; **полный регресс `tests/ -q`
|
||||
зелёный: 1466 passed**); документация обновлена исчерпывающе.
|
||||
|
||||
**Единственный прежний блокер закрыт.** Ревизия v1 выносила P1 за повреждённую (дословно
|
||||
продублированную) запись ORCH-095 в `CHANGELOG.md` — коммит `75c33ab docs(changelog): repair
|
||||
duplicated ORCH-095 entry body` устранил дубль: тело bullet ORCH-095 теперь присутствует ровно
|
||||
один раз (`git revert occurrences on line 16: 1`), артефакт чужой задачи восстановлен. Новых
|
||||
P0/P1 не выявлено.
|
||||
|
||||
Проверено: 4 оси (ТЗ / ADR / качество кода / документация) + трассировка маркеров + полный
|
||||
прогон тест-сьюта.
|
||||
|
||||
## Findings
|
||||
|
||||
### P0 — Blocker
|
||||
- (нет)
|
||||
|
||||
### P1 — Must fix
|
||||
- (нет) — прежний P1 (дубль записи ORCH-095 в CHANGELOG) исправлен коммитом `75c33ab`.
|
||||
|
||||
### P2 — Should fix
|
||||
- [ ] **Несоответствие формулировки ADR-001 D7 фактическому артефакту: 6-польная схема 52c
|
||||
не эмитится.** `ADR-001-coverage-gate.md` D7 утверждает: «Артефакт несёт **аддитивно**
|
||||
обязательную 6-польную схему 52c, не трогая `coverage_status:`». Фактически и генератор
|
||||
(`coverage_gate.render_coverage_report`), и скелет `docs/_templates/18-coverage-report.md`
|
||||
эмитят только `coverage_status`/`work_item` + coverage-поля; отсутствуют 5 из 6 полей схемы
|
||||
52c (`stage`/`author_agent`/`status`/`created_at`/`model_used`). **Почему не блокер:** (а)
|
||||
TRZ §6 формулирует это условно («*Если* отчёт несёт обязательную 6-польную схему 52c —
|
||||
добавить её аддитивно»), (б) валидация схемы warning-only по умолчанию
|
||||
(`frontmatter_validation_strict=False`), (в) гейт-генерируемые артефакты (прецедент
|
||||
`17-security-report.md`) исторически несут лишь свой machine-key — эпик 52c (ORCH-077)
|
||||
скоупил схему на 6 агент-промптов, не на машинные отчёты. Машинный вердикт читается из
|
||||
`coverage_status:` корректно, контракт не нарушен. **Действие (на усмотрение, не блокирует
|
||||
приёмку):** привести формулировку D7 к факту (отчёт несёт `coverage_status:` + coverage-поля,
|
||||
без полной 52c-схемы) ЛИБО добавить 5 полей в генератор+шаблон.
|
||||
|
||||
## Документация
|
||||
|
||||
**Статус: обновлена исчерпывающе** (golden source синхронизирован в том же PR, AC-10 PASS):
|
||||
|
||||
- `docs/architecture/README.md` — реестр `QG_CHECKS` дополнен `check_coverage_gate (ORCH-027)`;
|
||||
добавлен раздел «Coverage-гейт: защита от деградации покрытия» (точка/порядок, измерение,
|
||||
чистая функция, baseline+ratchet, условность/fail-open, артефакт/наблюдаемость). ✅
|
||||
- `docs/_standards/PIPELINE_DOCS.md` — диапазон доков `…18-coverage-report.md`; строка карты
|
||||
`стадия→агент→документ→гейт→machine-key` + строка таблицы вердикт-парсеров
|
||||
(`coverage_status:` → `check_coverage_gate`). ✅
|
||||
- `docs/_templates/18-coverage-report.md` — скелет с frontmatter зарегистрирован. ✅
|
||||
- `docs/work-items/ORCH-027/06-adr/ADR-001-coverage-gate.md` (D1…D8) +
|
||||
сквозной `docs/architecture/adr/adr-0029-coverage-gate.md`. ✅
|
||||
- `CHANGELOG.md` — детальная корректная запись ORCH-027; повреждение соседней записи ORCH-095
|
||||
устранено (v1-P1 закрыт). ✅
|
||||
- `CLAUDE.md` — паспортный блок «Гейт покрытия тестами (ORCH-027)» добавлен. ✅
|
||||
- `.env.example` / `src/config.py` — флаги `ORCH_COVERAGE_*` задокументированы. ✅
|
||||
- Маркеры `ORCH-027` проставлены в коде/доках (AC-10). ✅
|
||||
|
||||
`src/` изменён → документация обновлена в том же PR: **да** (P0-условие выполнено).
|
||||
**Обзорные доки (ORCH-079):** PR не закрывает ни один пункт `README.md` «Известные ограничения»
|
||||
(coverage-деградация там не значилась) → обновление витрины не требуется, finding отсутствует.
|
||||
|
||||
## Оси проверки (детально)
|
||||
|
||||
**1. Соответствие ТЗ (02-trz / 03-acceptance) — PASS.**
|
||||
AC-1 измерение инструментально (`measure_coverage` → `pytest --cov=src` → `totals.percent_covered`,
|
||||
`pytest-cov==5.0.0` в `requirements.txt`); AC-2 блокировка деградации + откат на `development` с
|
||||
release merge-lease (`_handle_coverage_gate`); AC-3 чистая функция `compute_coverage_verdict`
|
||||
покрыта по всем режимам/границам/epsilon (TC-01…04); AC-4 ratchet up-only + bootstrap + per-repo
|
||||
изоляция + атомарный compare-and-set `UPDATE … WHERE coverage <= ?` (`db.ratchet_coverage_baseline`);
|
||||
AC-5 kill-switch/scope + `applies(repo)` ПЕРВЫМ (дорогой прогон только при `applies==True`) —
|
||||
регресс зелёный, enduro не затронут; AC-6 fail-open дефолт / fail-closed по флагу; AC-7 never-raise
|
||||
+ leaf (не импортирует `stage_engine`) + AST-проверка отсутствия деплой/force-push токенов; AC-8
|
||||
контракты `STAGE_TRANSITIONS`/`check_*`/вердикт-ключи байт-в-байт, таблица `coverage_baseline`
|
||||
аддитивна; AC-9 вердикт только из frontmatter (`parse_coverage_status` через
|
||||
`frontmatter.parse_frontmatter`) + `GET /queue` блок `coverage` + Telegram с кликабельным номером.
|
||||
|
||||
**2. Соответствие ADR (ADR-001 D1…D8 / adr-0029) — PASS** (с P2-оговоркой по тексту D7).
|
||||
Порядок под-гейтов `security → merge → coverage → image-freshness` реализован ровно как в D1
|
||||
(врезка `_handle_coverage_gate` между merge-handling и ORCH-058 freshness в `advance_stage`);
|
||||
coverage ПОСЛЕ merge-gate (догнанный HEAD) и `merge_gate.release_merge_lease` при FAIL —
|
||||
соответствует D1/TR-2 (зеркало image-freshness rollback, в отличие от security — тот до захвата
|
||||
lease). Ratchet в choke-point `_handle_merge_verify` (ребро `deploy→done`, D5), БД-таблица
|
||||
`coverage_baseline` (D4), машинный вердикт/парсинг (D7), override `POST /coverage/baseline` (D8).
|
||||
Глобальные ADR (INV-4 merge только через Gitea API; не трогать `main`/прод) не нарушены — leaf
|
||||
только мерит/читает/пишет/решает.
|
||||
|
||||
**3. Качество кода — PASS.**
|
||||
Docstrings на всех публичных функциях; never-raise контракт выдержан последовательно (все
|
||||
внешние границы обёрнуты, исключение не всплывает в `advance_stage`); единый frontmatter-контракт
|
||||
переиспользован (нет дублирования парс-логики); тесты содержательные (режимы/границы/epsilon,
|
||||
ratchet up-only + bootstrap + per-repo изоляция, fail-open/closed, never-raise, write/read-back
|
||||
отчёта, self-hosting AST-инвариант, интеграция в `advance_stage` с откатом+release lease).
|
||||
Фикс `sys.executable` вместо bare `python` (коммит `8cd7c20`) корректен — pytest-cov живёт в
|
||||
интерпретаторе орка. Нет утечек/security-дыр; измерение offline. Замечание (не finding):
|
||||
синхронный `pytest --cov` в hot-path `advance_stage` (тайм-аут `coverage_run_timeout_s=900`)
|
||||
наследует established-паттерн merge-gate re-test/security-gate — нового класса риска не вводит.
|
||||
|
||||
**4. Документация — см. раздел «Документация» выше (P0-условие выполнено; обзорные доки N/A).**
|
||||
|
||||
**Трассировка маркеров (TRACEABILITY).** Правки рядом с маркерами `ORCH-022`/`ORCH-043`/`ORCH-058`
|
||||
в `advance_stage` — аддитивная врезка между merge-gate и image-freshness; инварианты соседних
|
||||
под-гейтов не сломаны (release-lease зеркалит image-freshness rollback, merge через Gitea API
|
||||
не тронут). Врезка в `_handle_merge_verify` (ORCH-071/073) — never-raise best-effort ratchet,
|
||||
SHA-in-main choke-point не изменён. Чужие артефакты не повреждены (восстановлена запись ORCH-095).
|
||||
@@ -1,76 +0,0 @@
|
||||
---
|
||||
result: PASS # PASS | FAIL — машинный вердикт, UPPERCASE
|
||||
work_item: ORCH-027
|
||||
stage: testing
|
||||
author_agent: tester
|
||||
status: pass
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
type: test-report
|
||||
work_item_id: ORCH-027
|
||||
---
|
||||
|
||||
# Test Report — ORCH-027 — Code coverage как гейт
|
||||
|
||||
Work Item: **ORCH-027** · Repo: **orchestrator** · Branch: **feature/ORCH-027-code-coverage** · Стадия: testing
|
||||
Предусловие: `12-review.md` → `verdict: APPROVED` ✅ (проверено).
|
||||
|
||||
## Окружение
|
||||
- Python: 3.12.13
|
||||
- pytest: 8.3.3 (plugins: cov-5.0.0, anyio-4.13.0, asyncio-0.23.8)
|
||||
- Worktree: `/repos/_wt/orchestrator/feature_ORCH-027-code-coverage` (HEAD `619fd0c`)
|
||||
- Дата: 2026-06-10
|
||||
|
||||
## Smoke API (read-only)
|
||||
| Endpoint | Результат |
|
||||
|----------|-----------|
|
||||
| `GET /health` | PASS — `{"status":"ok","service":"orchestrator"}` |
|
||||
| `GET /status` | PASS — активные задачи отдаются, ORCH-027 в `testing` |
|
||||
| `GET /queue` | PASS — блоки `serial_gate` (ORCH-088) **и** `auto_labels` присутствуют в payload; добавлен read-only блок `coverage`-наблюдаемости по ТЗ FR-7 (через общий снапшот) |
|
||||
|
||||
`serial_gate.per_repo.orchestrator.active_task = ORCH-027 (testing)` — гейт сериализации виден, регресса смока нет.
|
||||
|
||||
## Результаты — покрытие ТЗ (каждый TC из 04-test-plan.yaml ↔ AC из 03-acceptance-criteria.md)
|
||||
|
||||
| TC ID | Тип | Описание | Тест-функция(и) | AC | Результат |
|
||||
|-------|-----|----------|-----------------|----|-----------|
|
||||
| TC-01 | unit | `compute_coverage_verdict` policy=absolute (порог/ниже/ровно) | `test_tc01_policy_absolute` | AC-3 | PASS |
|
||||
| TC-02 | unit | policy=baseline (no-regression / ratchet) | `test_tc02_policy_baseline` | AC-3/AC-4 | PASS |
|
||||
| TC-03 | unit | policy=both — оба условия | `test_tc03_policy_both` | AC-3 | PASS |
|
||||
| TC-04 | unit | epsilon-допуск (анти-флап, NFR-4) | `test_tc04_epsilon_tolerance` | AC-3 | PASS |
|
||||
| TC-05 | unit | Ratchet базовой линии up-only + per-repo изоляция | `test_tc05_ratchet_up_only`, `test_tc05_ratchet_per_repo_isolated` | AC-4 | PASS |
|
||||
| TC-06 | unit | Bootstrap baseline при отсутствии значения | `test_tc06_bootstrap` | AC-4 | PASS |
|
||||
| TC-07 | unit | `applies(repo)`: пустой CSV → self-hosting only; вне области → no-op без прогона | `test_tc07_applies_self_hosting_only`, `test_tc07_applies_csv_scope`, `test_tc07_out_of_scope_noop_no_measure` | AC-5 | PASS |
|
||||
| TC-08 | unit | Kill-switch `coverage_gate_enabled=False` → инертен (1:1 до ORCH-027) | `test_tc08_kill_switch_off` | AC-5 | PASS |
|
||||
| TC-09 | unit | Fail-open дефолт + fail-closed по флагу | `test_tc09_fail_open_default`, `test_tc09_fail_closed_when_configured` | AC-6 | PASS |
|
||||
| TC-10 | unit | never-raise: битый вывод/отсутствие worktree не всплывает | `test_tc10_verdict_never_raises_on_bad_inputs`, `test_tc10_parse_coverage_percent_tolerant`, `test_tc10_check_never_raises`, `test_tc10_ratchet_never_raises_on_missing_report` | AC-7 | PASS |
|
||||
| TC-11 | unit | write/read-back отчёта `coverage_status:` через `src/frontmatter.py` | `test_tc11_report_roundtrip`, `test_tc11_parse_missing_frontmatter`, `test_tc11_bootstrap_report_blank_baseline` | AC-9 | PASS |
|
||||
| TC-12 | unit | Self-hosting безопасность: leaf без engine-импорта; нет деплой/force-push | `test_tc12_leaf_no_engine_import`, `test_tc12_delta_signed` | AC-7 | PASS |
|
||||
| TC-13 | integration | Гейт в конвейере: FAIL → откат на development; PASS → штатное продвижение | `test_tc13_advance_rolls_back_on_fail`, `test_tc13_advance_passes_through_on_ok` | AC-2 | PASS |
|
||||
| TC-14 | integration | Реальное измерение pytest под coverage в worktree + тайм-аут | `test_tc14_real_measurement`, `test_tc14_measure_timeout_returns_none` | AC-1 | PASS |
|
||||
| TC-15 | integration | Наблюдаемость `GET /queue` блок coverage + контракты не изменены | `test_tc15_snapshot_shape`, `test_tc15_snapshot_never_raises`, `test_tc15_registry_and_transitions_unchanged` | AC-8/AC-9 | PASS |
|
||||
|
||||
**Итог покрытия ТЗ:** все 15 TC выполнены и сопоставлены с AC-1…AC-10; ни одного непокрытого/пропущенного TC.
|
||||
|
||||
## Вывод pytest
|
||||
|
||||
### Целевой набор — `tests/test_coverage_gate.py`
|
||||
```
|
||||
collected 29 items
|
||||
tests/test_coverage_gate.py::test_tc01_policy_absolute PASSED
|
||||
... (29 тестов, TC-01…TC-15) ...
|
||||
tests/test_coverage_gate.py::test_tc15_registry_and_transitions_unchanged PASSED
|
||||
======================== 29 passed, 1 warning in 2.28s =========================
|
||||
```
|
||||
|
||||
### Полный регресс — `pytest tests/ -q`
|
||||
```
|
||||
1466 passed, 1 warning in 48.89s
|
||||
```
|
||||
(Единственное предупреждение — PydanticDeprecatedSince20 в `src/config.py:8`, не связано с ORCH-027, регрессом не является.)
|
||||
|
||||
## Итог
|
||||
**PASS** — целевой набор coverage-гейта зелёный (29/29), полный регресс зелёный (1466/1466,
|
||||
нулевая регрессия для enduro-trails), smoke API read-only OK (`serial_gate` + `auto_labels`
|
||||
присутствуют). Каждый TC из `04-test-plan.yaml` выполнен и сопоставлен с критериями приёмки.
|
||||
Задача готова к продвижению на `deploy-staging`.
|
||||
@@ -1,12 +0,0 @@
|
||||
---
|
||||
deploy_status: SUCCESS
|
||||
work_item: ORCH-027
|
||||
hook_exit_code: 0
|
||||
deployed_by: deploy-finalizer
|
||||
---
|
||||
|
||||
# Deploy log — ORCH-036 executable self-deploy
|
||||
|
||||
Прод-деплой завершён хост-хуком с exit-code `0` -> `deploy_status: SUCCESS`.
|
||||
|
||||
Вердикт зафиксирован детерминированным finalizer'ом (Фаза C), не LLM.
|
||||
@@ -1,32 +0,0 @@
|
||||
---
|
||||
staging_status: SUCCESS
|
||||
work_item: ORCH-027
|
||||
stage: deploy-staging
|
||||
author_agent: deployer
|
||||
status: success
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
timestamp: 2026-06-09T22:25:00Z
|
||||
base_url: http://localhost:8501
|
||||
---
|
||||
|
||||
# Staging Gate Log
|
||||
|
||||
Staging test suite completed against the live `orchestrator-staging` stand (8501), run canonically
|
||||
inside the container (`docker exec orchestrator-staging python3 /repos/orchestrator/scripts/staging_check.py
|
||||
--base-url http://localhost:8501 --mode stub`). **Exit code 0 → SUCCESS.** All REAL pipeline checks
|
||||
passed; the only failures are the two known waived sandbox-infra checks (C9a/C9b), tolerated under
|
||||
ORCH-061 because every REAL check is green.
|
||||
|
||||
INFRA-WAIVED: C9a Branch appears in orchestrator-sandbox, C9b Analyst job enqueued in staging queue (known sandbox-infra; real checks green)
|
||||
VERDICT: SUCCESS (exit 0) — SUCCESS (infra-waived): ['C9a Branch appears in orchestrator-sandbox', 'C9b Analyst job enqueued in staging queue'] are known sandbox-infra checks; all real checks green
|
||||
|
||||
## Results
|
||||
- **Block A (SMOKE)**: PASS — A1 `/health` 200 ok; A2 `/queue` 200 with counts/max_concurrency/resilience; A3 `ORCH_STAGING=true` (not prod).
|
||||
- **Block B (ACCESS)**: PASS — B4 Plane sandbox project accessible (sandbox=YES); B5 Gitea `orchestrator-sandbox` accessible push=true; B6 Registry isolation (sandbox present, prod ET/ORCH absent).
|
||||
- **Block C (E2E, mode=stub)**: C7 create issue in Plane SANDBOX PASS; C8 trigger pipeline via `/webhook/plane` PASS; C9a/C9b FAIL — **waived sandbox-infra** (SANDBOX bot-accounts not members of the sandbox Plane project; not a pipeline regression).
|
||||
|
||||
REAL failed: none.
|
||||
SANDBOX_INFRA failed (waived): C9a Branch appears in orchestrator-sandbox; C9b Analyst job enqueued in staging queue.
|
||||
|
||||
Result: 8/10 checks PASS, exit 0. Tolerance `staging_infra_tolerance_enabled=True`. Cleanup OK (Plane test issue deleted, HTTP 204; no branch created to delete).
|
||||
@@ -1,7 +0,0 @@
|
||||
# Business Request: BUG/follow-up ORCH-040: normalize legacy root-owned файлы при миграции на uid 1000 (one-time + защита)
|
||||
|
||||
Work Item ID: ORCH-057
|
||||
|
||||
## Description
|
||||
|
||||
TBD
|
||||
@@ -1,140 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-057
|
||||
stage: analysis
|
||||
author_agent: analyst
|
||||
status: ready-for-review
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# 01 — BRD (бизнес-требования): ORCH-057 — нормализация legacy root-owned файлов при миграции на uid 1000 (one-time + защита)
|
||||
|
||||
Work Item: **ORCH-057** · Repo: **orchestrator** · Стадия: analysis
|
||||
|
||||
## 1. Бизнес-контекст и проблема
|
||||
|
||||
ORCH-040 перевёл оба контейнера (`orchestrator` 8500, `orchestrator-staging` 8501) с root
|
||||
на `user: "1000:1000"` (slin). Изменён был **только** `docker-compose.yml`. Однако bind-mount
|
||||
`/home/slin/repos → /repos` уже содержал файлы и каталоги, созданные **прежним root-контейнером**
|
||||
(`root:root`). Смена `user:` владельца существующих файлов НЕ меняет.
|
||||
|
||||
**Реальный инцидент (прод, 06.06, поймали на первом запуске ORCH-043).** Первый job под uid 1000
|
||||
упал на стадии **launch** (НЕ на коде задачи):
|
||||
|
||||
```
|
||||
fatal: could not create leading directories of
|
||||
'/repos/_wt/orchestrator/feature_ORCH-043-.../.git': Permission denied
|
||||
```
|
||||
|
||||
Причина: `/repos/_wt/` и старые worktree-папки = `root:root` → uid 1000 не может создать рядом
|
||||
новый каталог worktree. Установлено фактически: ошибка возникает в `src/git_worktree.py::ensure_worktree`
|
||||
(вызов `git worktree add`), куда конвейер приходит из `src/agents/launcher.py::_spawn` (стр. 500)
|
||||
и `_materialize_deferred_branch` (ORCH-088). Агент даже не стартует — падает создание worktree.
|
||||
|
||||
**Ручной workaround (применён Стрим, прод снова рабочий, ОДНОРАЗОВО):**
|
||||
```
|
||||
sudo chown -R 1000:1000 /home/slin/repos/_wt
|
||||
sudo chown -R 1000:1000 /home/slin/repos/orchestrator/.git /home/slin/repos/enduro-trails/.git
|
||||
sudo chown -R 1000:1000 /home/slin/repos/orchestrator # +data/runs/*.log (37 root-логов)
|
||||
```
|
||||
|
||||
ADR-001 ORCH-040 упоминал «массовый chown старых root-файлов» лишь абстрактно («вне объёма кода»,
|
||||
«разовая операция Owner») и НЕ дал конкретной процедуры чистки legacy worktree — поэтому deployer
|
||||
её не выполнил, и баг проявился в проде. Прод сейчас рабочий (ручной фикс наложен), но проблема
|
||||
**воспроизведётся** на чистой среде, новом репо или после любого исторического запуска под root,
|
||||
если её не закрыть кодом + процедурой.
|
||||
|
||||
**Это follow-up / закрытие недоделанного AC ORCH-040** (legacy-файлы), а не новая фича.
|
||||
|
||||
## 2. Объём (scope)
|
||||
|
||||
### В объёме
|
||||
- **Защита launcher (код):** при `Permission denied` на создании worktree выдавать **внятную,
|
||||
диагностируемую** ошибку «legacy root-файлы в `/repos/_wt` — требуется нормализация прав»
|
||||
с указанием команды, а НЕ сырой `git fatal`.
|
||||
- **Раннее обнаружение (код):** детектирование наличия файлов с `uid != <target_uid>` в
|
||||
`ORCH_REPOS_DIR` (включая `_wt`, `.git/objects`, `.git/worktrees`, `data/runs`) при старте
|
||||
контейнера / перед претензией на job — чтобы конвейер падал **внятно и заранее**, а не сырым
|
||||
git-фаталом на launch.
|
||||
- **Процедура нормализации (документация):** в `docs/operations/INFRA.md` (и собственный ADR
|
||||
ORCH-057) — обязательная одноразовая процедура нормализации legacy root-файлов при миграции uid,
|
||||
с точными командами и областью охвата (`_wt`, `.git`, `data/runs`).
|
||||
- **Опционально (по решению архитектора):** механизм one-time нормализации при буте/деплое —
|
||||
init-контейнер/хук под root, либо blocking-entrypoint-проверка.
|
||||
|
||||
### Вне объёма
|
||||
- Изменение логики конвейера, `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`, схемы БД.
|
||||
- Пересмотр самого решения ORCH-040 (uid 1000) — оно принято и остаётся.
|
||||
- Перенос инстанса на другой хост / другой uid (отдельная задача при миграции хоста).
|
||||
- Массовая ретроактивная переработка ADR-001 ORCH-040 (его история не переписывается;
|
||||
допускается forward-breadcrumb-ссылка на ORCH-057 — решает архитектор).
|
||||
- Выбор конкретного варианта реализации one-time нормализации (a/b/в) — зона архитектора (06-adr).
|
||||
|
||||
## 3. Заинтересованные стороны
|
||||
|
||||
- **Заказчик / Owner** — Слава (homenet542), инициатор; принимает результат.
|
||||
- **Эксплуатация** — Стрим (применял ручной workaround); потребитель процедуры в INFRA.md.
|
||||
- **Затронутые проекты** — `orchestrator` (self-hosting) и `enduro-trails` (общий инстанс, общая
|
||||
очередь, общий bind-mount `/repos`): нормализация прав `/repos` касается обоих репо.
|
||||
|
||||
## 4. Бизнес-требования (BR)
|
||||
|
||||
- **BR-1** — После миграции контейнера на новый uid конвейер запускается **без ручного `chown`**:
|
||||
либо авто-нормализация прав, либо **явная блокирующая ошибка с инструкцией** (никогда не сырой
|
||||
`git fatal` на launch).
|
||||
- **BR-2** — На свежей среде / новом репо / после исторического запуска под root проблема
|
||||
**не воспроизводится** (детект + понятная диагностика срабатывают до падения агента).
|
||||
- **BR-3** — `INFRA.md` и ADR содержат **конкретную процедуру** нормализации legacy root-файлов
|
||||
(точные команды, область: `_wt`, `.git/objects`, `.git/worktrees`, `data/runs`), помеченную как
|
||||
обязательный шаг миграции uid.
|
||||
- **BR-4** — Несоответствие владельца наблюдаемо: оператор узнаёт о проблеме из лога/уведомления/
|
||||
read-only статуса, а не по падению задачи на launch.
|
||||
- **BR-5** — Защита `ensure_worktree` распознаёт класс ошибки «нет прав на создание worktree» и
|
||||
сообщает причину + лечащую команду (опц. — авто-самолечение, если процесс имеет права).
|
||||
|
||||
## 5. Нефункциональные требования (NFR)
|
||||
|
||||
- **NFR-1 (self-hosting безопасность)** — Решение **никогда** не перезапускает/не роняет
|
||||
прод-контейнер `orchestrator`, не трогает `main`/force-push/прод-образ. Контейнер бежит под
|
||||
uid 1000 (без root) → код **не может** делать `chown` без root; код ограничивается
|
||||
детектом + внятной диагностикой/блокировкой, а фактический `chown` — операторская/init-процедура.
|
||||
- **NFR-2 (общий инстанс)** — Нулевая регрессия для `enduro-trails`: feature под kill-switch и
|
||||
scope-флагом (по образцу `serial_gate`/`coverage_gate`); выключено → поведение 1:1 как до ORCH-057.
|
||||
- **NFR-3 (never-raise / fail-safe)** — Детект-леаф никогда не бросает наружу неожиданное исключение
|
||||
и не блокирует старт сервиса по своей ошибке; деградирует в WARNING.
|
||||
- **NFR-4 (идемпотентность)** — Повторный запуск детекта/нормализации на уже корректной среде —
|
||||
no-op без побочных эффектов.
|
||||
- **NFR-5 (обратимость)** — Поведение откатывается выключением kill-switch без миграций/правки схемы.
|
||||
- **NFR-6 (наблюдаемость)** — Вердикт (есть/нет mismatch, сколько файлов, какие корни) логируется
|
||||
структурно; при проблеме — Telegram с кликабельным номером задачи (если применимо) + read-only
|
||||
отражение в `GET /queue`.
|
||||
|
||||
## 6. Допущения и ограничения
|
||||
|
||||
- Целевой uid:gid рантайма = `1000:1000` (slin), подтверждён ORCH-040 (P-3); на хосте `/repos`,
|
||||
`/app/data` штатно `1000:1000`.
|
||||
- Контейнер бежит под numeric uid 1000 без записи в `/etc/passwd` базового образа; в образе создан
|
||||
реальный user `slin` (uid 1000) для `getpwuid()` (ORCH-058, Dockerfile). Под uid 1000 `chown`
|
||||
чужих (root) файлов **невозможен** без CAP_CHOWN/root.
|
||||
- `git config --system --add safe.directory '*'` уже в образе — git доверяет bind-mount.
|
||||
- Корни проверки: `ORCH_REPOS_DIR` (`/repos`), включая `_wt`, `<repo>/.git/objects`,
|
||||
`<repo>/.git/worktrees`, и `data/runs` (37 root-логов в инциденте).
|
||||
- `start_pipeline` (ORCH-088) отложил срез ветки на момент claim analyst-job → детект уместен
|
||||
и на старте сервиса, и перед claim'ом (точку выбирает архитектор).
|
||||
|
||||
## 7. Критерии успеха
|
||||
|
||||
После миграции uid (или на чистой среде) первый же job проходит launch без ручного `chown`, либо —
|
||||
если права не нормализованы — конвейер выдаёт **понятную блокирующую диагностику** с командой
|
||||
исправления вместо сырого `git fatal`. INFRA.md/ADR содержат воспроизводимую процедуру.
|
||||
Для `enduro-trails` — нулевая регрессия. Детальные PASS/FAIL — в `03-acceptance-criteria.md`.
|
||||
|
||||
## 8. Риски
|
||||
|
||||
- Контейнер без root не может `chown` → авто-самолечение возможно только частично/при наличии прав;
|
||||
основной гарант — детект+диагностика+процедура (детали — `10-tech-risks.md`, архитектор).
|
||||
- Рекурсивный обход больших `.git/objects` / `_wt` может быть дорог → нужен дешёвый/семплированный
|
||||
детект и кэш (как preflight TTL).
|
||||
- Ложно-блокирующая ошибка может застопорить и enduro-trails (общий `/repos`) → строгий scope/fail-safe.
|
||||
- Правка `docker-compose.yml`/entrypoint (init-контейнер) = деплой self → групповой риск (NFR-1),
|
||||
обязательная страховка staging.
|
||||
@@ -1,117 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-057
|
||||
stage: analysis
|
||||
author_agent: analyst
|
||||
status: ready-for-review
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# 02 — ТЗ (TRZ): ORCH-057 — нормализация legacy root-owned файлов при миграции на uid 1000
|
||||
|
||||
Work Item: **ORCH-057** · Repo: **orchestrator** · Стадия: analysis
|
||||
|
||||
> ТЗ описывает **конкретные изменения к реализации**, выведенные из BRD и фактического кода.
|
||||
> Архитектурное обоснование/выбор варианта one-time нормализации (init-контейнер vs blocking-entrypoint
|
||||
> vs ансибл) — задача архитектора (`06-adr/`). Здесь — требования, контракты и ограничения.
|
||||
|
||||
## 1. Сводка изменения
|
||||
|
||||
Закрыть недоделанный AC ORCH-040 по legacy-файлам. Три слоя:
|
||||
1. **Защита launcher** — `ensure_worktree` распознаёт `Permission denied`/git-fatal на создании
|
||||
worktree и поднимает **внятную** ошибку с диагнозом «legacy root-файлы в `/repos/_wt` — нужна
|
||||
нормализация прав» + лечащая команда (опц. авто-самолечение при наличии прав).
|
||||
2. **Ранний детект** — новый чистый леаф находит файлы с `uid != target_uid` в `ORCH_REPOS_DIR`
|
||||
(`_wt`, `.git/objects`, `.git/worktrees`, `data/runs`); вызывается на старте сервиса и/или перед
|
||||
claim'ом job; never-raise, config-gated, с наблюдаемостью.
|
||||
3. **Процедура** — `INFRA.md` + ADR ORCH-057: точные команды разовой нормализации как обязательный
|
||||
шаг миграции uid. Опционально — one-time нормализация под root через init-механизм (решает архитектор).
|
||||
|
||||
Инвариант: `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / machine-verdict-ключи / схема БД —
|
||||
**байт-в-байт прежние**. Изменение аддитивно и обратимо kill-switch'ем.
|
||||
|
||||
## 2. Задействованные модули / пути
|
||||
|
||||
| Путь | Действие |
|
||||
|------|----------|
|
||||
| `src/git_worktree.py` (`ensure_worktree`, `remove_worktree`) | изменить — классификация `Permission denied`/git-fatal на `git worktree add` / `os.makedirs` → внятный actionable `RuntimeError` (опц. self-heal при правах) |
|
||||
| `src/fs_normalize.py` | **создать** — чистый леаф (never-raise): `scan_ownership(roots, target_uid) -> результат`; опц. `normalize(...)` (chown только при наличии прав); хелпер `applies(repo)` + кэш (TTL, как preflight) |
|
||||
| `src/config.py` | изменить — добавить флаги (см. §7); без правки существующих значений |
|
||||
| `src/main.py` (`lifespan`) | изменить — добавить startup-вызов детекта (best-effort, never-fatal по образцу L-2/lease-reclaim), лог + Telegram при mismatch; read-only блок в `GET /queue` |
|
||||
| `src/preflight.py` **или** `src/queue_worker.py` | изменить (на выбор архитектора) — опц. гейт claim'а job при обнаруженном mismatch, чтобы падать внятно ДО launch (по образцу preflight-гейта) |
|
||||
| `docker-compose.yml` / `Dockerfile` / `scripts/*entrypoint*` | **кандидат** (решает архитектор) — one-time root-нормализация (init-контейнер/хук) ПЕРЕД стартом app; если выбрано — деплой self, обязательная staging-страховка |
|
||||
| `docs/operations/INFRA.md` | изменить — раздел «Миграция uid: обязательная нормализация legacy root-файлов» (команды + область) |
|
||||
| `docs/work-items/ORCH-057/06-adr/ADR-001-*.md` | создать (architect) — решение + процедура; опц. forward-breadcrumb из ADR-001 ORCH-040 (без переписывания истории) |
|
||||
| `CHANGELOG.md` | изменить — запись о ORCH-057 |
|
||||
| `tests/test_*` | создать — см. `04-test-plan.yaml` |
|
||||
|
||||
## 3. Функциональные требования
|
||||
|
||||
### FR-1 — Внятная ошибка `ensure_worktree` (BR-1, BR-5)
|
||||
При неуспехе `git worktree add` / `os.makedirs(os.path.dirname(wt))` по причине отказа доступа
|
||||
(`Permission denied`, `could not create leading directories`, `insufficient permission for adding an
|
||||
object`) `ensure_worktree` поднимает `RuntimeError` с сообщением, которое: (а) называет корневую
|
||||
причину (legacy root-owned файлы в `/repos/_wt` или `.git` после миграции uid ORCH-040); (б) указывает
|
||||
лечащую команду (`chown -R <uid>:<gid> …`) или ссылку на процедуру INFRA.md; (в) НЕ является сырым
|
||||
git stderr. Прочие (нет-прав-несвязанные) ошибки сохраняют текущий контракт (никакой подмены смысла).
|
||||
|
||||
### FR-2 — Детект несоответствия владельца (BR-2, BR-4)
|
||||
Леаф `fs_normalize.scan_ownership` обходит корни (`/repos/_wt`, `<repo>/.git/objects`,
|
||||
`<repo>/.git/worktrees`, `data/runs`) и возвращает: есть ли файлы с `uid != target_uid`, их число
|
||||
(или флаг «≥1»), список затронутых корней. Обход дешёвый/ограниченный (ранний выход при первом
|
||||
mismatch для быстрого вердикта; полный подсчёт — опционально/семплировано). Результат кэшируется по
|
||||
TTL (по образцу `preflight._cache`). `target_uid` = `os.getuid()` или конфиг (дефолт 1000).
|
||||
|
||||
### FR-3 — Реакция на детект (BR-1, BR-4)
|
||||
- **Startup (main.lifespan):** вызвать детект best-effort; при mismatch — структурный WARNING +
|
||||
Telegram (если включён) с числом/корнями и лечащей командой. Никогда не падать на старте по
|
||||
ошибке детекта (NFR-3).
|
||||
- **Опц. гейт claim'а:** при обнаруженном mismatch и `target_uid` без прав на chown — не претендовать
|
||||
на job (или претендовать и сразу честно фейлить с FR-1-сообщением), чтобы исход был внятным до launch.
|
||||
Конкретную точку (preflight vs queue_worker) выбирает архитектор; требование — «внятно и заранее».
|
||||
|
||||
### FR-4 — Опциональная авто-нормализация (BR-1)
|
||||
`fs_normalize.normalize` выполняет `chown -R target_uid:target_gid` по корням **только если процесс
|
||||
имеет на это право** (CAP_CHOWN/root). Под uid 1000 без прав — no-op + честный лог «нужна операторская
|
||||
процедура» (НЕ ошибка). Включается отдельным флагом (`*_AUTO`), по умолчанию — выкл (детект-only).
|
||||
Если архитектор выбирает init-контейнер под root — это и есть носитель FR-4 на буте.
|
||||
|
||||
### FR-5 — Документированная процедура (BR-3)
|
||||
`INFRA.md` получает раздел с точными командами разовой нормализации (`_wt`, оба `.git`, `data/runs`),
|
||||
помеченный как **обязательный** шаг миграции uid и часть чеклиста деплоя self. ADR ORCH-057 фиксирует
|
||||
решение и ссылается на процедуру; ADR-001 ORCH-040 опц. получает forward-ссылку.
|
||||
|
||||
## 4. Изменения API
|
||||
|
||||
Нет новых обязательных эндпоинтов. **Опционально** (наблюдаемость, решает архитектор):
|
||||
- расширить `GET /queue` read-only блоком `fs_ownership` (`{enabled, target_uid, mismatch, roots, checked_at}`);
|
||||
- ручной триггер `POST /fs-normalize/check` (форс-пересчёт детекта) — по образцу `POST /serial-gate/unfreeze`.
|
||||
|
||||
## 5. Изменения схемы БД
|
||||
|
||||
Нет. Состояние детекта — в памяти (TTL-кэш), как `preflight`. Таблицы/миграции/индексы не вводятся.
|
||||
|
||||
## 6. Требования к новым/изменённым QG checks
|
||||
|
||||
Нет. Это **не** stage-гейт и **не** под-гейт ребра. `QG_CHECKS` / `check_*` / `STAGE_TRANSITIONS` /
|
||||
machine-verdict-ключи (`verdict:`/`result:`/`deploy_status:`/`staging_status:`/`security_status:`/
|
||||
`coverage_status:`) — не трогаются. (В описании баг-репорта «deploy-гейт ORCH-040» — это деплой-хук/
|
||||
процедура, а не зарегистрированный QG.)
|
||||
|
||||
## 7. Совместимость / регресс
|
||||
|
||||
- **Kill-switch** `ORCH_FS_NORMALIZE_ENABLED` (дефолт по решению архитектора; `False` → весь код инертен,
|
||||
поведение 1:1 как до ORCH-057).
|
||||
- **Scope** `ORCH_FS_NORMALIZE_REPOS` (CSV; пусто → **self-hosting only**, как `coverage_gate_repos` →
|
||||
enduro-trails не затронут). Локальный `applies(repo)` проверяется ПЕРВЫМ (дешёвый обход только при applies).
|
||||
- **Флаги** (рабочие имена, финал — за архитектором): `ORCH_FS_TARGET_UID` (дефолт 1000),
|
||||
`ORCH_FS_NORMALIZE_AUTO` (дефолт `False` — детект-only; `True` → попытка chown при наличии прав),
|
||||
`ORCH_FS_SCAN_ROOTS` (CSV переопределения корней), `ORCH_FS_SCAN_CACHE_TTL_S`.
|
||||
- **Never-raise / fail-safe** — ошибка детекта/нормализации деградирует в WARNING, не блокирует старт
|
||||
сервиса по своей вине; FR-1 меняет лишь **формулировку** ошибки worktree, не её факт.
|
||||
- **Self-hosting** (NFR-1) — код только читает/детектит/диагностирует (и chown ТОЛЬКО при наличии прав);
|
||||
не деплоит/не рестартит прод/не трогает `main`. Любое касание `docker-compose.yml`/entrypoint требует
|
||||
staging-прогона (8501) перед прод-рестартом в окно тишины.
|
||||
- **Обратимость** — выкл kill-switch → прежнее поведение; миграций/правки схемы нет.
|
||||
- **Пайплайн-артефакты:** обновляются `01..04` (analysis), `06-adr/`+`07-infra-requirements.md`+`10-tech-risks.md`
|
||||
(architecture), `12/13/15/14` (review/testing/staging/deploy), `INFRA.md`, `CHANGELOG.md`.
|
||||
@@ -1,99 +0,0 @@
|
||||
---
|
||||
work_item: ORCH-057
|
||||
stage: analysis
|
||||
author_agent: analyst
|
||||
status: ready-for-review
|
||||
created_at: 2026-06-10
|
||||
model_used: claude-opus-4-8
|
||||
---
|
||||
|
||||
# 03 — Критерии приёмки (Acceptance Criteria): ORCH-057 — нормализация legacy root-owned файлов
|
||||
|
||||
Work Item: **ORCH-057** · Repo: **orchestrator** · Стадия: analysis
|
||||
|
||||
Формат: каждый критерий имеет **PASS** (что должно быть истинно для приёмки) и **FAIL**
|
||||
(что считается провалом). Любой машинный/ручной reviewer проверяет их буквально по файлам репозитория.
|
||||
|
||||
---
|
||||
|
||||
## AC-1 — Конвейер стартует без ручного chown (или внятная блокирующая ошибка)
|
||||
|
||||
**Условие:** после миграции контейнера на новый uid первый job не падает сырым git-фаталом на launch.
|
||||
- **PASS:** при нормализованных правах worktree создаётся и агент стартует; при НЕнормализованных
|
||||
правах конвейер выдаёт понятную блокирующую ошибку с диагнозом и лечащей командой (НЕ сырой
|
||||
`fatal: could not create leading directories … Permission denied`).
|
||||
- **FAIL:** на launch всплывает сырой git-fatal/Permission denied без диагноза причины и инструкции.
|
||||
|
||||
---
|
||||
|
||||
## AC-2 — `ensure_worktree` даёт actionable-ошибку при отказе доступа
|
||||
|
||||
**Условие:** `src/git_worktree.py::ensure_worktree` классифицирует ошибки прав.
|
||||
- **PASS:** при `Permission denied`/`could not create leading directories`/`insufficient permission`
|
||||
поднимается `RuntimeError`, текст которого называет причину (legacy root-файлы в `/repos/_wt`/`.git`
|
||||
после миграции uid) и указывает команду/ссылку на процедуру; ошибки, не связанные с правами,
|
||||
сохраняют прежний контракт.
|
||||
- **FAIL:** сырой git stderr пробрасывается без диагноза; либо подменяется смысл не-прав-ошибок;
|
||||
либо `ensure_worktree` падает необработанно.
|
||||
|
||||
---
|
||||
|
||||
## AC-3 — Детект несоответствия владельца
|
||||
|
||||
**Условие:** новый леаф `src/fs_normalize.py` обнаруживает файлы с `uid != target_uid` в корнях
|
||||
(`/repos/_wt`, `<repo>/.git/objects`, `<repo>/.git/worktrees`, `data/runs`).
|
||||
- **PASS:** на среде с root-файлами `scan_ownership` возвращает mismatch=True + затронутые корни;
|
||||
на чистой (`1000:1000`) среде — mismatch=False (no-op, идемпотентно); леаф never-raise.
|
||||
- **FAIL:** mismatch не обнаружен на грязной среде / ложный mismatch на чистой / леаф бросает наружу.
|
||||
|
||||
---
|
||||
|
||||
## AC-4 — Наблюдаемость детекта
|
||||
|
||||
**Условие:** результат детекта виден оператору без падения задачи.
|
||||
- **PASS:** при mismatch — структурный лог-WARNING (число/корни/лечащая команда) и Telegram (если
|
||||
включён); опц. read-only отражение в `GET /queue`.
|
||||
- **FAIL:** mismatch обнаружен, но никак не сообщён; оператор узнаёт о проблеме только по упавшей задаче.
|
||||
|
||||
---
|
||||
|
||||
## AC-5 — Self-hosting безопасность и нулевая регрессия enduro-trails
|
||||
|
||||
**Условие:** изменение безопасно для общего инстанса.
|
||||
- **PASS:** код не рестартит/не роняет прод, не трогает `main`/force-push/прод-образ; chown — только
|
||||
при наличии прав; при выключенном kill-switch поведение 1:1 как до ORCH-057; при пустом scope-CSV
|
||||
feature активен только для self-hosting (enduro-trails не затронут); регресс `pytest tests/ -q` зелёный.
|
||||
- **FAIL:** любой рестарт/деградация прода из кода задачи; ненулевая регрессия enduro-trails;
|
||||
поведение меняется при выключенном флаге; падение всего регресса.
|
||||
|
||||
---
|
||||
|
||||
## AC-6 — Инварианты конвейера сохранены
|
||||
|
||||
**Условие:** изменение аддитивно.
|
||||
- **PASS:** `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`, machine-verdict-ключи и схема БД —
|
||||
байт-в-байт прежние; новые флаги аддитивны и обратимы.
|
||||
- **FAIL:** затронут любой exit/под-гейт, изменён machine-key, добавлена миграция схемы.
|
||||
|
||||
---
|
||||
|
||||
## AC-7 — Документированная процедура нормализации
|
||||
|
||||
**Условие:** процедура воспроизводима.
|
||||
- **PASS:** `INFRA.md` содержит раздел «Миграция uid: обязательная нормализация legacy root-файлов»
|
||||
с точными командами (`_wt`, оба `.git`, `data/runs`) как обязательный шаг миграции; ADR ORCH-057
|
||||
фиксирует решение и ссылается на процедуру.
|
||||
- **FAIL:** процедура отсутствует/абстрактна (как было в ORCH-040) либо не покрывает все корни.
|
||||
|
||||
---
|
||||
|
||||
## Сводная матрица AC ↔ FR/BR
|
||||
| AC | Покрывает |
|
||||
|----|-----------|
|
||||
| AC-1 | BR-1 / FR-1, FR-3 |
|
||||
| AC-2 | BR-1, BR-5 / FR-1 |
|
||||
| AC-3 | BR-2 / FR-2 |
|
||||
| AC-4 | BR-4 / FR-3 |
|
||||
| AC-5 | NFR-1, NFR-2, NFR-5 / FR-4 |
|
||||
| AC-6 | NFR-5 (инварианты) |
|
||||
| AC-7 | BR-3 / FR-5 |
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user