@besales/ops-framework 0.1.0

package/templates/execution-feedback.md

@@ -0,0 +1,25 @@
+# Execution Feedback
+
+## Feedback Event 1
+
+- Received at: `YYYY-MM-DDTHH:mm:ss.sssZ`
+- Source: `user`
+- Raw feedback:
+- Current stage when received: `Execute`
+- Classification: `within_approved_scope | plan_patch_required | research_required | brief_reset_required | human_triage_required | human_arbitration_required`
+- Rationale:
+- Affected artifacts: `plan.md, research.md, brief.md, execution.md, verify.md`
+- Supervisor decision: `stay_execute | return_plan | return_research | return_brief | human_triage | human_arbitration`
+- Requires fresh Check: `yes | no`
+- Requires new Human Gate: `yes | no`
+
+## Classification rules
+
+- `within_approved_scope`: feedback does not invalidate approved `plan.md` or `check.md`.
+- `plan_patch_required`: implementation path changes but task outcome does not.
+- `research_required`: feedback reveals missing facts.
+- `brief_reset_required`: feedback changes task frame, outcome, UI/data/analytics contour or lifecycle.
+- `human_triage_required`: automation cannot classify feedback unambiguously.
+- `human_arbitration_required`: feedback is a risk appetite, product tradeoff or architecture decision.
+
+Feedback cannot modify execution until classified.

package/templates/execution.md

@@ -0,0 +1,101 @@
+# Execution
+
+## Краткое summary
+
+## Risk tier / execution budget used
+
+- Approved risk tier:
+- Actual execution target:
+- Fast-loop fixes made inside approved scope:
+- Stop rules encountered:
+
+## Planned Item Coverage
+
+| Plan item / section | Status (`done | partial | not_done | blocked | superseded`) | Evidence | Notes |
+| --- | --- | --- | --- |
+
+## Preflight Evidence
+
+| Check | Result | Evidence / notes |
+| --- | --- | --- |
+| Dev server / API availability |  |  |
+| Browser / UI automation availability |  |  |
+| Auth/session availability |  |  |
+| DB target / representative data |  |  |
+| Dirty worktree / unrelated files |  |  |
+
+## Execution Ledger
+
+- `execution-ledger.json`: `present | not_generated`
+- Command: `corepack yarn agent:build-execution-ledger <TASK-id>`
+- Notes:
+
+## Измененные файлы
+
+| File | Change summary | Planned item / reason |
+| --- | --- | --- |
+
+## Запущенные команды
+
+| Command | Result | Evidence / notes |
+| --- | --- | --- |
+
+## Micro-verify evidence
+
+| Assertion / check | Result | Evidence / notes |
+| --- | --- | --- |
+
+## Slice-verify evidence
+
+| Assertion / check | Result | Evidence / notes |
+| --- | --- | --- |
+
+## UI Acceptance Evidence
+
+Required when `plan.md` has `UI Acceptance Scenarios`.
+
+| Scenario ID | Result (`pass | fail | blocked | human-owned`) | Observed evidence / screenshot / payload | Notes |
+| --- | --- | --- | --- |
+| UI-001 |  |  |  |
+
+## Complexity / Performance Evidence
+
+Required when `plan.md` has `Complexity / Performance Budget`.
+
+| Hot path / budget | Result | Timing / rows / EXPLAIN / N+1 evidence | Notes |
+| --- | --- | --- | --- |
+
+## Optimization Review Evidence
+
+Required when `plan.md` has O2/O3 `Optimization Strategy`.
+
+| Hot path | Tier | Review result | Evidence / deferred findings |
+| --- | --- | --- | --- |
+
+## Production Rollout Evidence
+
+Required when `plan.md` has `Production Rollout Gate`.
+
+| Rollout check | Result | Env/deploy/rollback/post-deploy evidence | Notes |
+| --- | --- | --- | --- |
+
+## Source Sync / Provider Evidence
+
+Required when `plan.md` has `Source Sync / Provider Gate`.
+
+| Provider/sync check | Result | Idempotency/retry/pagination/raw-record/coverage evidence | Notes |
+| --- | --- | --- | --- |
+
+## Отклонения от плана
+
+| Deviation | Reason | Impact | Follow-up / resolution |
+| --- | --- | --- | --- |
+
+## Explicit Non-Actions
+
+| Action not taken | Reason | Requires future Human Gate? |
+| --- | --- | --- |
+
+## Блокеры
+
+## Follow-up notes

package/templates/human-gate-summary.md

@@ -0,0 +1,49 @@
+# Human Gate Summary
+
+## Task
+
+`TASK-xxx`
+
+## Decision Needed
+
+Approve moving from `Human Gate` to `Execute`, or ask a clarifying question before approval.
+
+## Problem We Are Solving
+
+[Describe the problem.]
+
+## Approved Plan Summary
+
+[Summarize the approved plan.]
+
+## Execution Approach
+
+[Describe the execution approach.]
+
+## Human Gate Requirements
+
+Before approval, human should confirm:
+
+- [Approval item.]
+
+## What Approval Allows
+
+After approval, Executor may:
+
+- [Allowed action.]
+
+## What Remains Forbidden
+
+Even after approval, Executor must not:
+
+- [Forbidden action.]
+
+## Check Result
+
+- Verdict: `ready_for_human_gate`
+- Blocking findings: `0`
+- Check result: `check.result.json`
+
+## Next Step
+
+Human approves Execute or asks a clarifying question.

package/templates/orchestration-log.md

@@ -0,0 +1,8 @@
+# Orchestration Log
+
+## Entries
+
+- `YYYY-MM-DD HH:MM` — supervisor перевел задачу в этап `Brief`.
+- `YYYY-MM-DD HH:MM` — вызван `Researcher`, ожидается `research.md`.
+- `YYYY-MM-DD HH:MM` — вызван `Planner`, ожидается `plan.md`.
+- `YYYY-MM-DD HH:MM` — plan gate: `approved | revision requested | scope changed`.

package/templates/plan.md

@@ -0,0 +1,86 @@
+# Plan
+
+## Цель
+
+## Опора на research
+
+## Допущения
+
+## Затронутые модули и файлы
+
+## Risk tier and execution budget
+
+- Risk tier: `R0 | R1 | R2 | R3 | R4 | R5`
+- Speed mode: `Fast | Standard | Strict`
+- Approved execution target:
+- Fast-loop allowed inside this slice:
+- Requires return to Plan/Check if:
+
+## UI Acceptance Scenarios
+
+Required when the task is `panel-ui` or `ui-visible-api`. Do not use page-load-only smoke as acceptance.
+
+| ID | User intent | Setup/data | Steps | Expected visible result | Must catch |
+| --- | --- | --- | --- | --- | --- |
+| UI-001 |  |  |  |  |  |
+
+## Complexity / Performance Budget
+
+Required for read-model, materializer, worker, production-runtime, dashboard/table UI, replay/backfill or other hot-path work.
+
+- Hot paths:
+- Expected data size / row counts:
+- Complexity risks:
+- Planned mitigation:
+- Budget / stop rule:
+
+## Optimization Strategy
+
+Required for O2/O3 hot-path work. Keep it bounded: prevent obvious inefficient design without turning delivery into an endless optimization loop.
+
+- Optimization tier: `O0 none | O1 checklist | O2 focused review | O3 measured review`
+- Hot paths:
+- Expected data size / row counts:
+- Chosen efficient approach:
+- Anti-patterns explicitly avoided: `N+1 | repeated scan | nested O(n^2) | unbounded full scan | heavy render recompute`
+- Optimizer budget / stop rule:
+- Deferred optimization ideas:
+
+## Production Rollout Gate
+
+Required for migrations, env vars, cron/workers, billing/auth, external APIs, deployment/runtime behavior, or production-readiness claims.
+
+- Impact / blast radius:
+- Environment / deploy variables:
+- Rollback / disable path:
+- Post-deploy evidence:
+
+## Source Sync / Provider Gate
+
+Required for sync/import/provider pipelines, raw records, retries, pagination, rate limits, idempotency, replay/backfill, or partial failure recovery.
+
+- Scope / provider window:
+- Idempotency / duplicate handling:
+- Failure handling / retry boundaries:
+- Coverage / parity evidence:
+
+## Checker Context Hints
+
+- Required repo files for Checker to inspect:
+- Prior relevant failures:
+- Exact questions Checker must answer:
+- Relevant playbooks:
+
+## Шаги реализации
+
+## Риски и открытые вопросы
+
+## План проверки
+
+### Verification ladder
+
+- Micro-verify during Execute:
+- Slice-verify before completion:
+- External Verify required before closeout: `yes | no`, reason:
+
+## Что требует human approval

package/templates/research.md

@@ -0,0 +1,13 @@
+# Research
+
+## Цель исследования
+
+## Подтвержденные repo findings
+
+## Затронутые модули и файлы
+
+## Риски и ограничения
+
+## Открытые вопросы
+
+## Рекомендации для planning

package/templates/retrospective.md

@@ -0,0 +1,48 @@
+# Retrospective
+
+## Статус
+
+`not_started`
+
+## Что сработало хорошо
+
+## Что вызвало лишние циклы
+
+## Переиспользуемые выводы
+
+## Какие обновления памяти нужны
+
+## Какие checklist или prompts стоит обновить
+
+## Learning Loop Audit
+
+- `ops-agent memory-candidates` выполнен после заполнения retrospective/check/verify feedback: `[fill in]`
+- `ops-agent learning-index` создал human-reviewable decisions: `[fill in]`
+- `ops-agent learning-review` создал human approval pack и был показан human: `[fill in]`
+- `learning-index.json` reviewed human/supervisor: `[fill in]`
+- Promoted to project memory: `[fill in]`
+- Promoted to project playbooks: `[fill in]`
+- Shared playbook candidates requiring reviewed framework task: `[fill in]`
+- `ops-agent update-memory --apply-approved` выполнен, если были approved entries: `[fill in]`
+- `ops-agent learning-report` показан human перед closeout: `[fill in]`
+
+## Time Trace Audit
+
+- Краткая трассировка времени по блокам: `[fill in]`
+- Где время ушло на productive engineering: `[fill in]`
+- Где время ушло на non-productive loops/tooling/waiting: `[fill in]`
+- Нужна ли human escalation по framework optimization: `[fill in]`
+
+Если значимая доля времени ушла на non-productive loops, external tooling, stale gates, browser/tool instability или unrelated dirty-worktree blockers, Supervisor обязан:
+- показать human эту трассировку;
+- предложить конкретную optimization policy;
+- не менять framework/prompt/checklist самостоятельно без human approval.
+
+## Closeout audit
+
+- `verify.md` содержит итоговый verdict: `[fill in]`
+- `verify.result.json` существует, current и не блокирует Retrospective: `[fill in]`
+- `status.md` обновлен до final/paused stage: `[fill in]`
+- `orchestration-log.md` содержит closure/boundary decision: `[fill in]`
+- deferred/follow-up work зафиксирован: `[fill in]`
+- `git diff --check` после документационных правок: `[fill in]`

package/templates/status.md

@@ -0,0 +1,53 @@
+# Status
+
+## Task ID
+
+## Текущий этап
+
+## Текущий owner
+
+## Latest routing decision
+
+## Plan SHA
+
+`sha256:required-in-phase-3`
+
+## Memory SHA
+
+`sha256:required-in-phase-3`
+
+## Latest check verdict
+
+`not_started | return_to_plan | ready_for_human_gate | human_arbitration_required | checker_failed`
+
+## Latest check result
+
+- `check.result.json`: missing | present | stale | current
+
+## Latest check resolution
+
+- `check-resolution.md`: not_required | missing | present | accepted_by_supervisor
+
+## Human Gate summary
+
+- `human-gate-summary.md`: not_required | missing | present
+
+## Feedback intake
+
+- `feedback.md`: no_events | unclassified_event | classified
+
+## Latest verify verdict
+
+`not_started | pass | pass_with_notes | return_to_execute | return_to_plan | human_arbitration_required | verifier_failed`
+
+## Latest verify result
+
+- `verify.result.json`: missing | present | stale | current
+
+## Последнее действие supervisor
+
+## Что ожидается на выходе текущего этапа
+
+## Нужен ли сейчас human approval
+
+## Следующий шаг

package/templates/verify-result.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": 1,
+  "taskId": "TASK-000-example",
+  "planSha": "sha256:required",
+  "executionSha": "sha256:required",
+  "verificationMode": "internal_supervisor",
+  "verifierProvider": "supervisor",
+  "verifierModel": "none",
+  "verifierRunId": "internal-supervisor-run-id-required",
+  "verdict": "pass",
+  "failureReason": null,
+  "readyForRetrospective": true,
+  "counts": {
+    "blockingFindings": 0,
+    "nonBlockingFindings": 0,
+    "questions": 0
+  },
+  "findings": []
+}

package/templates/verify.md

@@ -0,0 +1,41 @@
+# Verify
+
+## Verdict
+
+`PASS | PASS_WITH_NOTES | FAIL`
+
+## Plan vs Execution Coverage
+
+| Plan item / execution claim | Verification status (`verified | partial | contradicted | not_verified`) | Evidence | Finding ID |
+| --- | --- | --- | --- |
+
+## Выполненные проверки
+
+| Check | Command / method | Result | Notes |
+| --- | --- | --- | --- |
+
+## Verification mode
+
+`internal_supervisor | external_cli`
+
+Use `internal_supervisor` for ordinary local R0-R3 slices when focused tests/build/lint/smoke evidence is sufficient. Use `external_cli` for R4/R5, production-readiness, destructive/security/financial/broad operational work, material migrations/backfills, broad ambiguous refactors or explicit human request.
+
+## Verification ladder coverage
+
+| Level (`micro | slice | internal | external`) | Coverage | Evidence | Gaps |
+| --- | --- | --- | --- |
+
+## UI/browser verification
+
+## Findings
+
+| ID | Severity | Category | Claim | Expected correction |
+| --- | --- | --- | --- |
+
+## Residual risks
+
+## Recommended next step
+
+## Structured Result
+
+`verify.result.json` is required next to this file before Retrospective or Human Closeout Gate.