Skip to content

README.md

Latest commit

 

History

History
109 lines (86 loc) · 12 KB

README.md

File metadata and controls

109 lines (86 loc) · 12 KB

Sergeant Documentation

Last touched: 2026-06-14 by @github-actions[bot]. Next review: 2026-09-12. Status: Active

Main documentation index for Sergeant.

🟢 Docs trust: HEALTHY — оновлено 2026-06-14 via pnpm docs:gen-trust-badge

0 stale docs · 0 WIP violations · 0 cron failures — система здорова, працюй спокійно. Деталі → today.md.

Daily entry — «що зараз у роботі?»

Три дашборди, що тримають тебе в курсі без чтення всього docs/ дерева:

Питання Документ
Загальна панель — почни звідси STATUS.md — одна сторінка: 🎯 фокус · 🟢 зроблено (pr-ledger) · 🔵 в роботі · ⏭️ далі · 🧱 стек · 🗺️ карта доків. Ручний лише блок FOCUS; решта — pnpm docs:gen-status.
Що мені робити сьогодні? today.md — auto-brief: top-7 actionable items (Phase X next / blocked), прострочений review, WIP load. Regen pnpm docs:gen-today. Daily ритуал — відкрий вранці.
Що НЕ доробленого по всіх trackers? open-work.md — auto-rollup усіх Status: Active / Draft / In progress / Phase * документів з 7 trackers. Regen pnpm docs:gen-open-work; drift gate в CI.
Чи документи свіжі? governance/freshness-dashboard.html — Last validated / Next review по всьому tracked-set.
Що шипнули у whats-new? whats-new/ — markdown side; canonical source = apps/web/src/core/whatsNew/releases.ts (drift caught by releases.test.ts).

Чому довіряти: open-work.md парсить > **Status:** headers (Rule #10) програмно — будь-який drift падає в CI через pnpm docs:check-open-work. Якщо документ показується тут зі статусом Active, значить його джерело справді у такому стані.

Quick start

Sections

Sections are grouped by genre so it is obvious at a glance whether a directory is reference material you read on demand, an active tracker you update when you ship work, or a frozen archive.

Кожна верхньорівнева секція має власний index-README з картою своїх піддиректорій: 00-start/ · 01-product/ · 02-engineering/ · 03-operations/ · 04-governance/ · 05-design/ · 90-work/.

Informational — reference / architecture / policy. Evergreen; consult when you need context. Trackers — multi-PR series, registries, lifecycle-managed work (Active → Closed → Archived). Read when you plan a PR; update when you ship. Archive — Closed documents past their stabilization window or historical artefacts kept for context. Read-only.

Informational (reference / architecture / policy)

Section Purpose
adr/ Architectural decisions and tradeoffs
agents/ Agent operating system, routing catalog, workflows
api/ OpenAPI, API contracts, generated artifacts
architecture/ Repo map, runtime surfaces, platform architecture
copy/ UA-copy tone-of-voice rules; reference for every Cyrillic JSX literal
deploy/ Deploy walkthroughs (Railway, Vercel, console, etc.)
design/ Design system, brand, accents, dark mode, UI patterns
development/ Local dev-loop how-tos (ESLint config, local Postgres, pre-commit timing)
governance/ Hard rules registry, policy docs, feature-flag registry, link-check allowlist
i18n/ i18n readiness foundation (UA-only today; lightweight scaffolding for future locales)
integrations/ Third-party integrations (Monobank, Voyage, Renovate, …)
marketing/ Pre-launch GTM execution plans (reference; reconciled against shipped landing)
mobile/ Expo/mobile strategy and migration docs
notes/ Design spikes and exploratory engineering notes
observability/ Alerts, SLOs, logs, engineering metrics
ops/ Recurring ops runbooks (Renovate maintainer workflow, dependency hygiene)
playbooks/ Canonical execution recipes for repeatable tasks
postmortems/ Incident reviews and follow-up memory
runbooks/ DR-grade operational runbooks (DB backup/restore, encryption key rotation, …)
security/ Security policy, access governance, recovery, and audit docs
testing/ Testing strategy meta-docs (mutation testing, layer matrix, threshold-is)
ui/ Cross-cutting UI behaviour policy (keyboard shortcuts registry, toast policy)
web/ apps/web platform deep-dives (Service Worker update strategy)

Trackers (multi-PR series, registries, lifecycle-managed work)

Section Purpose
open-work.md Автогенерований єдиний дашборд активних документів з усіх 7 tracker-ів (Rule #10 sweep)
audits/ Code, architecture, UX audits with Active → Closed → Archived lifecycle and freshness gate
initiatives/ Numbered multi-PR initiatives with acceptance criteria, progress tables, and 90-day stabilization window
launch/ Go-to-market, monetization, ops, and product-OS roadmaps (FTUX master tracker + sprint plans)
planning/ Active roadmaps, infra plans, staged improvements
security/hardening/ Living security hardening backlog (per-finding cards + sprint plans)
superpowers/ High-leverage one-page guides for cross-cutting capabilities (active implementation plans under plans/)
tech-debt/ Active debt registries and cleanup plans (per-platform, with freshness gate)

Archive (read-only / superseded)

Path What
audits/archive/ Audits past their stabilization window; superseded historical scans
initiatives/archive/ Initiatives 90+ days past Closed without regressions
launch/product-os/sprint-retros/ Per-sprint launch retrospectives (frozen after sprint closes)
planning/archive/ Historical roadmap journals (e.g. dev-stack-roadmap session log from 2026-04)

Adding new docs

  1. Decide the genre first: reference (informational), active tracker, or archive candidate. Put the doc in the matching section above.
  2. If it is an execution recipe, use docs/00-start/playbooks/.
  3. If it is policy or machine-readable governance, use docs/04-governance/governance/.
  4. If it changes routing for agents, sync docs/00-start/agents/* and AGENTS.md.
  5. For docs with review cadence, include Last validated and Status headers.
  6. When a tracker doc reaches its stabilization milestone, move it to the section's archive/ subdirectory (where one exists) and leave a one-line redirect from the old path.