MVP з нуля

# YourProjectName — правила роботи з проєктом

## 1. Статус baseline

Цей файл є стабільним operational contract для людей та AI-асистентів.

- **Product / MVP:** `Waiting for MVP input`
- **Stack / architecture:** `Waiting for MVP input`
- **Sprint dates and owners:** `Waiting for MVP input`
- **Current phase:** governance setup only

Не вигадувати поведінку YourProjectName, користувачів, метрики, стек, архітектуру, тести, deployment, production readiness або user validation до появи підтвердженої MVP-специфікації.

## 2. Канонічні артефакти

| Артефакт | Канонічний шлях | Роль | Правило оновлення |
|---|---|---|---|
| Project contract | `SPEC.md` | Довгоживуча специфікація проблеми, користувача, outcome, scope і acceptance | Редагувати після узгодженого рішення про зміну контракту |
| Task contract | `TASK_SPEC.md` | Контракт однієї малої перевірюваної роботи | Оновлювати до початку роботи та при зміні scope |
| Evidence | `EVIDENCE.md` | Фактичний журнал перевірених результатів | Тільки append-only; не замінювати планом або narration |
| Delivery history | `RUNBOOK.md` | Операційна історія, рішення, blockers і handoff | Тільки append-only після фактичної перевірки |
| Sprint convention | `docs/sprints/README.md` | Формат майбутніх S1–S3 планів | Змінювати лише разом із governance-рішенням |
| Decision convention | `docs/decisions/README.md` | Формат stack/architecture/scope decision records | Додавати окремий record на кожне рішення |

Не створювати паралельні canonical names (`EVIDENCE_LOG.md`, `docs/SPEC.md`, дублікати templates) без окремого decision record. У цьому проєкті `EVIDENCE.md` є canonical evidence path.

## 3. Статуси та metadata

Кожен довгоживучий артефакт повинен мати: `ID`, `Version`, `Status`, `Owner`, `Date`, `Related artifacts`.

Використовувати такі статуси:

- `Draft` — створено, але не погоджено;
- `Ready` — контракт погоджено та можна виконувати;
- `Active` — робота триває;
- `Verified` — результат підтверджений свіжим evidence;
- `Superseded` — замінено новою версією.

Для значень усередині документів використовувати окремі маркери: `Confirmed`, `Assumption`, `Unknown`, `Needs verification`, `Blocked`, `Waiting for MVP input`.

Template, documented example, catalog entry або текст у плані не є доказом фізичного файлу, виконання команди чи якості результату.

## 4. Контрольований AI workflow

Перед кожною зміною:

1. Прочитати актуальний tree, пов'язані артефакти та affected paths.
2. Зафіксувати task ID, goal, allowed paths, expected diff і targeted check у `TASK_SPEC.md`.
3. Перевірити, що зміна підтримує scope `SPEC.md`.

Під час роботи:

- робити один bounded slice за ітерацію;
- не додавати unrelated cleanup, redesign або dependency без рішення;
- не змінювати файли поза allowed paths;
- явно маркувати assumptions та Unknowns;
- не читати й не записувати secrets/credentials без окремого дозволу;
- зупинятися, якщо scope розширився, contract неясний або немає oracle для перевірки.

Після зміни людина має перевірити diff і обрати `continue`, `revise` або `HOLD`. Не вважати відсутність помилки моделі evidence.

## 5. Acceptance, verification і rollback

Кожен task має містити:

- observable acceptance criteria;
- targeted commands або manual checks;
- expected та observed result;
- checkpoint після slice;
- stop conditions;
- rollback/recovery path.

Рішення sprint: `DONE`, `CONTINUE WITH APPROVAL` або `HOLD`. Для demo окремо розділяти blocking checks, advisory checks, evidence anchors і межу claims. Demo readiness не є deployment authorization.

Rollback має описувати, як повернутися до останнього підтвердженого стану, хто приймає рішення і яке evidence потрібне. Не виконувати production, publish, migration або destructive commands без окремої авторизації.

## 6. Правила артефактів

- `SPEC.md` — contract про проблему, primary user/JTBD, value proposition, success metric, core flow, scope, non-goals, release slice та acceptance. Не є task plan або evidence.
- `TASK_SPEC.md` — contract конкретної роботи: owner, input, output, constraints, verification, checkpoint, exit і rollback. До MVP це inactive template.
- `EVIDENCE.md` — лише спостережені факти: source, expected, observed, timestamp, status і limitations. Не називати documented example фактичним виконанням.
- `RUNBOOK.md` — історія delivery та handoff; не повний chat transcript, не специфікація і не заміна evidence.
- `docs/sprints/` — лише майбутні S1, S2, S3 після затвердження SPEC і stack. Кожен sprint має один observable outcome.
- `docs/decisions/` — окремі записи рішень із context, options, decision, rationale, consequences, owner і verification trigger.

## 7. Change control та звіт

Зміну scope, canonical path, статусу або decision оформити перед реалізацією та пов'язати через IDs. Не тихо переписувати історію. Evidence і RUNBOOK дописувати лише після перевірки.

Фінальний звіт кожної роботи має містити:

1. змінені файли;
2. фактичні команди та їх статус;
3. evidence links/IDs;
4. unresolved Unknowns та blockers;
5. rollback або recovery note;
6. handoff і наступний bounded action.

## 8. Порядок перевірки

Поки runtime і stack не обрані, використовувати structural/content checks для Markdown та Git. Після вибору stack порядок за замовчуванням:

```text
check → validate → build → targeted tests → demo gate
```

Не звітувати про команду, яку не запускали, і не підміняти `Unknown` правдоподібним результатом.

# SPEC.md — YourProjectName project contract

- **ID:** `SPEC-SEA-001`
- **Version:** `0.1.0`
- **Status:** `Draft`
- **Owner:** `Waiting for MVP input`
- **Date:** 2026-09-21
- **Related artifacts:** [`CLAUDE.md`](CLAUDE.md), [`TASK_SPEC.md`](TASK_SPEC.md), [`EVIDENCE.md`](EVIDENCE.md), [`RUNBOOK.md`](RUNBOOK.md)

> Цей документ є reviewer-oriented contract shell. MVP input ще не надано. Незаповнені поля мають статус `Unknown`, а не є припущеннями про продукт.

## Problem

`Unknown — Waiting for MVP input.`

## Primary user

`Unknown — Waiting for MVP input.`

## User / JTBD

- **When:** `Unknown`
- **I want to:** `Unknown`
- **So I can:** `Unknown`
- **Constraints:** `Unknown`
- **Evidence status:** `Waiting for MVP input`

## Value proposition

- **Problem:** `Unknown`
- **Alternative today:** `Unknown`
- **Promised outcome:** `Unknown`
- **Proof signal:** `Unknown`
- **Claims excluded until verified:** adoption, production impact, scalability, revenue and user validation.

## Desired outcome

`Unknown — не визначати feature-first; спочатку потрібен один bounded outcome.`

## Success metric

| Поле | Значення |
|---|---|
| Name | `Unknown` |
| Unit | `Unknown` |
| Baseline | `Unknown` |
| Target | `Unknown` |
| Observation window | `Unknown` |
| Collection method | `Unknown` |
| Guardrail metric | `Unknown` |
| Status | `Waiting for MVP input` |

## Core flow

`Unknown — trigger → AI-assisted/product step → human checkpoint → observable result`.

## Scope

### In scope

- Один bounded MVP release slice після отримання та узгодження MVP input.
- Тільки поведінка, потрібна для перевірки визначеного outcome.

### Non-goals

- Вибір stack або architecture до decision record.
- Три sprint plans до затвердження MVP scope.
- Autonomous approval/merge/deployment.
- Production readiness, масштабування, billing, додаткові інтеграції та широкі ролі, якщо вони не потрібні core flow.

## Release slice

`Unknown — буде визначено після фіксації user, JTBD, core flow і success signal.`

## Acceptance criteria

1. Primary user, JTBD, outcome і межі scope зафіксовані в цій SPEC.
2. Release slice має observable acceptance та reproducible verification path.
3. Кожен task має bounded contract у `TASK_SPEC.md` або пов'язаному task record.
4. Кожен заявлений результат має evidence у `EVIDENCE.md`.
5. Непідтверджені claims позначені `Unknown` або `Needs verification`.

**Current acceptance status:** `Blocked — Waiting for MVP input`.

## Verification plan

До надходження MVP input: structural/content review документів та Git status.

Після надходження MVP input: targeted checks, tests, demo quality gate і handoff, визначені в sprint/task contracts. Команди поки `Unknown`, бо stack не обраний.

## Assumptions

- Проєкт має бути організований як AI-assisted delivery з human checkpoints. `Assumption — підтвердити з owner.`
- MVP складатиметься з трьох sprint-ів, згідно з intake note. `Waiting for MVP input.`

## Open decisions

- Який продукт і його bounded core flow?
- Хто primary user та owner рішення?
- Який stack та architecture відповідають MVP constraints?
- Які baseline, target і observation window метрики?
- Які рівні verification потрібні для кожного slice?

## MVP input gate

Роботу над product implementation не починати, доки owner не надасть MVP specification і не буде узгоджено: user/JTBD, outcome, scope/non-goals, acceptance, success metric, constraints та спосіб delivery у трьох sprint-ах.

# TASK_SPEC.md — bounded task contract

- **ID:** `TASK-SEA-TEMPLATE-001`
- **Version:** `0.1.0`
- **Status:** `Draft`
- **Owner:** `Waiting for MVP input`
- **Date:** 2026-09-21
- **Related artifacts:** [`CLAUDE.md`](CLAUDE.md), [`SPEC.md`](SPEC.md), [`EVIDENCE.md`](EVIDENCE.md), [`RUNBOOK.md`](RUNBOOK.md)

> `Template — no active task.` Цей файл описує executor contract, але не створює вигадану роботу. Перед реалізацією його потрібно заповнити для конкретного bounded slice або створити пов'язаний task record за цим самим contract.

## Goal and linked outcome

- **Goal:** `Waiting for MVP input`
- **SPEC outcome:** `SPEC-SEA-001 / desired outcome — Unknown`
- **Current/desired behavior:** `Unknown`

## Owner and allowed paths

- **Owner:** `Waiting for MVP input`
- **Allowed paths:** `Unknown — визначити до початку ітерації`
- **Affected paths:** `Unknown`

## Inputs and constraints

- **Inputs:** `MVP specification — pending`
- **Constraints:** не вибирати stack без decision record; не розширювати scope; не читати/записувати secrets; не додавати unrelated cleanup.
- **Dependencies:** `Unknown`

## Expected output

`Unknown — конкретний reviewable increment визначається після MVP input.`

## In scope

`Unknown — Waiting for MVP input.`

## Non-goals

- Будь-які зміни поза allowed paths.
- Редизайн або масовий cleanup, не потрібні acceptance.
- Claims про deployment, production readiness, adoption або user validation.

## Acceptance criteria

- [ ] Observable result сформульований у термінах поведінки.
- [ ] Scope і non-goals погоджені з `SPEC-SEA-001`.
- [ ] Verification command/manual check має expected signal.
- [ ] Evidence entry має посилання на task ID.
- [ ] Human checkpoint виконаний до переходу далі.

**Current acceptance status:** `Blocked — no active task until MVP input.`

## Verification

- **Targeted command:** `Unknown — stack не обраний`
- **Manual check:** перевірити diff, acceptance, evidence anchor і відсутність scope drift.
- **Expected result:** `Unknown`
- **Observed result:** `Not run`

## Checkpoint and stop conditions

- **Checkpoint:** після кожного slice переглянути diff і targeted signal.
- **Stop when:** scope expands; contract unclear; affected paths unexpected; verification oracle unavailable; rollback невизначений; з'являється потреба в непогодженому dependency.
- **Exit decision:** `HOLD — waiting for MVP input`

## Risks and open questions

- Product outcome, stack, architecture, owners і acceptance не визначені.
- Неясно, які checks будуть blocking, advisory або demo-only.

## Rollback / recovery

До появи active task: не виконувати зміни продукту. Для майбутньої роботи описати повернення до останнього `Verified` стану, owner рішення про rollback і evidence, яке підтверджує recovery.

## Handoff

Наступна дія: отримати MVP specification, після чого створити конкретний task contract і decision records до реалізації.

# EVIDENCE.md — фактичний evidence ledger

- **ID:** `EVIDENCE-SEA-001`
- **Version:** `0.1.0`
- **Status:** `Active`
- **Owner:** `Waiting for MVP input`
- **Date:** 2026-09-21
- **Related artifacts:** [`CLAUDE.md`](CLAUDE.md), [`SPEC.md`](SPEC.md), [`TASK_SPEC.md`](TASK_SPEC.md), [`RUNBOOK.md`](RUNBOOK.md)

## Purpose and boundary

Це canonical, append-only журнал фактичних перевірок. План, template, documented example або текст у чаті не є evidence. Кожен запис має відділяти expected від observed і маркувати Unknown.

Не змішувати цей файл із `RUNBOOK.md`, не перейменовувати в `EVIDENCE_LOG.md` без окремого decision record.

## Entry schema

Для кожного запису використовувати:

- **Evidence ID**
- **Related SPEC/TASK ID**
- **Claim under verification**
- **Source** — command, file, diff, log або screenshot
- **Expected**
- **Observed**
- **Timestamp / environment**
- **Status** — `PASS`, `FAIL`, `BLOCKED`, `UNKNOWN`, `SUPERSEDED`
- **Reviewer / owner**
- **Limitations and follow-up**

## Evidence entries

### E-SEA-001 — initial repository baseline

- **Related SPEC/TASK ID:** `SPEC-SEA-001`; `TASK-SEA-TEMPLATE-001`
- **Claim under verification:** repository begins without product implementation and requires governance setup.
- **Source:** initial tree inspection and `the temporary intake note` read during setup.
- **Expected:** current tree contains only the pre-existing intake note and IntelliJ metadata; no runtime or product implementation is claimed.
- **Observed:** before setup, `the temporary intake note` and `.idea/` were present; no source, tests, build manifest, Git metadata, or project rules were present.
- **Timestamp / environment:** 2026-09-21; macOS; local YourProjectName workspace.
- **Status:** `PASS`
- **Reviewer / owner:** `Pending owner review`
- **Limitations and follow-up:** this verifies only the initial structural baseline; it proves no product behavior, stack, deployment, user validation, or production readiness.

### E-SEA-002 — governance baseline verification

- **Related SPEC/TASK ID:** `SPEC-SEA-001`; `TASK-SEA-TEMPLATE-001`
- **Claim under verification:** canonical governance artifacts and future-work conventions are present without speculative MVP content.
- **Source:** `find`, `git status --short`, and a Python structural/content checklist run after creating the baseline.
- **Expected:** required canonical files exist; MVP, stack, architecture, sprint tasks and product claims remain pending/Unknown.
- **Observed:** all required canonical files and directories were present; `S1.md`, `S2.md`, `S3.md`, `EVIDENCE_LOG.md` and `docs/SPEC.md` were absent; required headings were found; `the temporary intake note` remained present because deletion requires explicit owner authorization.
- **Timestamp / environment:** 2026-09-21; macOS; local YourProjectName workspace.
- **Status:** `PASS`
- **Reviewer / owner:** `Pending owner review`
- **Limitations and follow-up:** temporary `the temporary intake note` still needs an explicit owner decision; Git status was inspected but files are not committed; no runtime checks exist yet.

# RUNBOOK.md — delivery history and handoff

- **ID:** `RUNBOOK-SEA-001`
- **Version:** `0.1.0`
- **Status:** `Active`
- **Owner:** `Waiting for MVP input`
- **Date:** 2026-09-21
- **Related artifacts:** [`CLAUDE.md`](CLAUDE.md), [`SPEC.md`](SPEC.md), [`TASK_SPEC.md`](TASK_SPEC.md), [`EVIDENCE.md`](EVIDENCE.md)

## Purpose and boundary

`RUNBOOK.md` is an append-only operational history. It records goals, commands, decisions, blockers, recovery and handoff for a new operator. It is not the project specification, not the evidence ledger and not a full chat transcript.

## Entry format

Each entry must include: date/session, goal and scope, changed artifacts, commands and actual status, decisions and rationale, blockers/Unknowns, rollback or recovery, evidence links, handoff and next action.

## Entries

### 2026-09-21 — governance baseline setup

- **Session:** initial YourProjectName project setup.
- **Goal and scope:** create project-management infrastructure before MVP implementation; preserve a bounded AI workflow and explicit evidence boundary.
- **Changed artifacts:** created `CLAUDE.md`, `SPEC.md`, `TASK_SPEC.md`, `EVIDENCE.md`, this `RUNBOOK.md`, `docs/README.md`, `docs/sprints/README.md`, `docs/decisions/README.md`, `.gitignore`; initialized Git. `the temporary intake note` remains pending explicit owner authorization for deletion.
- **Commands and status:** `git init` — `PASS`; `find`/`git status --short`/Python structural-content checklist — `PASS`; temporary intake note deletion — `BLOCKED by explicit-permission requirement`.
- **Decisions:** `EVIDENCE.md` is this project's canonical evidence path; no stack, architecture, sprint task, product behavior or metric was invented; future work is exactly three sprint plans after MVP input and approval.
- **Blockers / Unknowns:** MVP specification, primary user/JTBD, outcome, success metric, constraints, owner, stack and architecture are pending.
- **Rollback / recovery:** restore `the temporary intake note` from the pre-setup workspace only if the owner explicitly requests it; otherwise revert the setup changes through Git after inspecting the diff. No product code or destructive operation was performed.
- **Evidence:** `E-SEA-001` records the initial structural baseline; `E-SEA-002` remains `UNKNOWN` until checks run.
- **Handoff:** owner to provide the MVP specification. Next bounded action: update `SPEC.md`, create stack/architecture decision records, then decompose approved scope into S1–S3.

# Project documentation

## Canonical records

- [`../CLAUDE.md`](../CLAUDE.md) — stable rules for AI-assisted work and artifact governance.
- [`../SPEC.md`](../SPEC.md) — durable project contract.
- [`../TASK_SPEC.md`](../TASK_SPEC.md) — current bounded task contract/template.
- [`../EVIDENCE.md`](../EVIDENCE.md) — append-only factual verification ledger.
- [`../RUNBOOK.md`](../RUNBOOK.md) — append-only delivery history and handoff.
- [`sprints/README.md`](sprints/README.md) — format for the future three sprint plans.
- [`decisions/README.md`](decisions/README.md) — format for stack, architecture and scope decisions.

## Working order

1. Read the current tree and `CLAUDE.md`.
2. Update `SPEC.md` only when product input or an approved decision changes the project contract.
3. Fill `TASK_SPEC.md` for one bounded slice before implementation.
4. Verify with targeted checks and record observed results in `EVIDENCE.md`.
5. Append the operational result and handoff to `RUNBOOK.md`.

There is one canonical path per artifact. Templates and examples must not diverge from the canonical records.

## Current gate

MVP input is pending. No implementation, stack selection or sprint-specific plan is authorized by the current project documents.

# Sprint planning convention

- **ID:** `SPRINT-GOV-001`
- **Version:** `0.1.0`
- **Status:** `Draft`
- **Owner:** `Waiting for MVP input`
- **Date:** 2026-09-21

## Boundary

YourProjectName will be decomposed into exactly three MVP sprints only after `SPEC.md` is populated and the stack/architecture decisions are approved. Until then, `S1`, `S2` and `S3` plan files intentionally do not exist.

## Required sprint contract

Each future `S1`, `S2` or `S3` record must contain:

- one observable outcome and explicit non-goals;
- linked SPEC and task IDs;
- ordered small slices with owner, input and expected output;
- allowed/affected paths and dependencies;
- verification command or manual check for every slice;
- checkpoint after each slice and human diff review;
- blocking vs advisory demo checks;
- readiness assumptions, safe fixtures, fallback and blocking Unknowns;
- rollback/recovery path;
- exit decision: `DONE`, `CONTINUE WITH APPROVAL` or `HOLD`;
- evidence links and a RUNBOOK handoff, including on `HOLD`.

## Creation gate

Create sprint files only when the owner approves the MVP contract, success metric, stack decision, architecture decision and three-sprint boundaries. Do not fill dates, tasks or technical choices from assumptions.

# Decision records

- **ID:** `DECISIONS-GOV-001`
- **Version:** `0.1.0`
- **Status:** `Draft`
- **Owner:** `Waiting for MVP input`
- **Date:** 2026-09-21

## Decision record format

Create one record per material stack, architecture, integration or scope decision. Each record must include:

- decision ID, version, date, status and owner;
- context and constraints;
- options considered, including why an option was not selected;
- chosen option and rationale;
- consequences, risks and deferred work;
- verification or revisit trigger;
- linked SPEC, TASK, EVIDENCE and RUNBOOK records.

A catalog entry or chat statement is not a decision. Do not select a technology until the MVP constraints are known and the record is reviewed.

## Pending decisions

| Decision | Status | Required input |
|---|---|---|
| Stack selection | `Waiting for MVP input` | MVP outcome, constraints, delivery environment and verification needs |
| Architecture boundary | `Waiting for MVP input` | Core flow, data boundaries, integrations and non-goals |
| Sprint allocation | `Waiting for MVP input` | Approved release slice and exactly three sprint outcomes |

Future records should use `docs/decisions/DEC-<number>-<short-name>.md` and update this index after verification.

# PRODUCT_BRIEF.md — documented example

- ID: PRODUCT-INPUT-001
- Version: 0.1.0
- Status: Waiting for MVP input
- Owner: Unknown
- Related artifacts: SPEC.md, VALUE_PROPOSITION.md, USER_JTBD.md, SUCCESS_METRIC.md

## Problem

Unknown — the owner has not described the problem in user terms.

## Primary user

Unknown — do not infer a target audience from the chosen technology.

## Desired outcome

Unknown — define one observable outcome before listing features.

## Constraints

Unknown — collect time, access, data, privacy, delivery and review constraints.

## Claims boundary

This is a non-technical product description template. It does not select a stack, prove user demand, or authorize implementation.

Status: documented example; waiting for product input.

# VALUE_PROPOSITION.md — documented example

- Status: Waiting for MVP input
- User: Unknown
- Problem: Unknown
- Current alternative: Unknown
- Promised outcome: Unknown
- Proof signal: Unknown

## Questions to answer

1. Who experiences the problem?
2. What are they trying to accomplish now?
3. What makes the current alternative costly, slow or unreliable?
4. What observable change would count as progress?
5. Which claims remain Unknown until user validation?

This file describes product value, not technical implementation. It must not claim adoption, revenue, production impact or product-market fit without evidence.

# USER_JTBD.md — documented example

- Status: Waiting for MVP input
- Primary user: Unknown

## Job statement

When [situation], I want to [motivation], so I can [desired progress].

## Context

- Trigger: Unknown
- Current workaround: Unknown
- Constraint: Unknown
- Human decision point: Unknown

## Evidence boundary

This job statement is a hypothesis until the owner provides source material or user evidence. Do not convert a persona guess into a product requirement.

# SUCCESS_METRIC.md — documented example

- Status: Waiting for MVP input
- Metric name: Unknown
- Unit: Unknown
- Baseline: Unknown
- Target: Unknown
- Observation window: Unknown
- Collection method: Unknown
- Guardrail metric: Unknown

## Interpretation rule

A metric is not ready until its baseline, target, observation window and collection method are explicit. Number of AI calls, generated screens or completed setup steps is not automatically an outcome metric.

No result is claimed by this template.

# RELEASE_SLICE.md — documented example

- Status: Waiting for MVP input
- User and JTBD: Unknown
- Core flow: Unknown
- In scope: Unknown
- Non-goals: Unknown
- Acceptance signal: Unknown
- Verification path: Unknown

## Boundary

Define the smallest end-to-end slice that can be shown and checked without implying deployment or production readiness. Defer integrations, roles and features that do not support the first observable outcome.

This is a planning example, not a release authorization.