354 lines
29 KiB
Markdown
354 lines
29 KiB
Markdown
# Windmill: the system as flows
|
||
|
||
Local Windmill instance for Personal OS pipelines. After the owner-requested
|
||
cleanup on 2026-11-18, the active catalog contains six flows with real code:
|
||
`f/attend/attention_loop_e5`, `f/attend/roles_importance_e4`,
|
||
`f/fetch/asana_expansion_e1`, `f/fetch/github_prs`,
|
||
`f/analyse/work_claims_extract`, and `f/analyse/work_situation`.
|
||
|
||
Sixteen obsolete entries are archived: fourteen flows containing placeholder
|
||
modules (including the old system overview), plus the unused `asana_sync`
|
||
compatibility entrypoint and `work_triage`. No flow was permanently deleted.
|
||
The retained flow definitions, their versions, existing schedules, and active
|
||
jobs were preserved. The archived paths and local source folders are excluded
|
||
from normal CLI sync in `workspace/wmill.yaml`, so a later sync does not silently
|
||
restore them. Their local source files remain historical material, not active
|
||
implementations. See [the exact cleanup evidence](personal-os-evidence/2026-11-18/windmill-catalog-cleanup.json).
|
||
|
||
The existing local owner account is now a member of `personal_os`. Open
|
||
[Personal OS workflows](http://localhost:8000/?workspace=personal_os); refresh
|
||
an already open page if it still shows only the Admins fallback. Visibility,
|
||
real code, and successful runs do not certify correctness of every feature:
|
||
the outstanding [remediation plan](../planning/personal-os-remediation-plan-2026-11-18.md)
|
||
remains open and unrelated development remains paused.
|
||
|
||
GitHub collection and work situations use the primary `personal_os` database.
|
||
The work flow persists local work items and design sources in inventory mode;
|
||
its separate `resolve` mode uses the existing model and keeps the result as a
|
||
candidate. Asana task creation remains a separate reviewed dashboard action.
|
||
See [the implementation](../planning/github-work-situations-2026-10-14.md).
|
||
|
||
The approved rollout copied 17 evidence tables with full content hashes matched,
|
||
then changed both flows' default target to `primary`. SQL source reads remain
|
||
read-only; only the fixed host-runner operations write evidence and decisions.
|
||
|
||
## Layout
|
||
|
||
| Path | What |
|
||
|---|---|
|
||
| `system-map.yaml` | The plan. One entry per flow with status, trigger, code it maps to, and its stages. Edit this. |
|
||
| `bootstrap/gen_map.py` | Turns the map into `workspace/f/<stage>/<flow>__flow/` skeletons. |
|
||
| `bootstrap/bootstrap.py` | One-time: workspace, folders, CLI token. |
|
||
| `bootstrap/steps/` | Historical extraction draft; the published incremental flow uses its real steps under `workspace/`. |
|
||
| `workspace/` | What the `wmill` CLI syncs with the server. Flows live under `f/`. |
|
||
| `docker-compose.yml` | Server, worker, native worker, LSP, caddy. Uses the host PostgreSQL. |
|
||
| `.env` | Database URL and CLI token. Not in git. |
|
||
|
||
Stage folders: `fetch` (sources in), `observe` (snapshots of now), `analyse`
|
||
(claims and links), `publish` (acceptance), `attend` (roles, attention, retro).
|
||
|
||
Historical status tags such as settled, draft, PROPOSED and PLANNED are not evidence of a working implementation. Archived definitions are visible only when archived entries are explicitly requested.
|
||
|
||
## Run
|
||
|
||
```bash
|
||
cd windmill && docker-compose up -d
|
||
```
|
||
|
||
UI: http://localhost:8000. Workspace: `personal_os`. The administrator password
|
||
was changed during setup; use the existing local credentials. CLI credentials
|
||
are kept in `.env`, outside Git.
|
||
|
||
The generator is historical scaffolding. It still describes archived drafts;
|
||
do not regenerate that catalog or remove the archive exclusions. The active
|
||
workspace contains the six retained flows. Do not push the whole workspace for
|
||
a feature change: a dry-run on 2026-11-18 exposed unrelated resource and source
|
||
drift, and no workspace-wide push was performed. First export the live target:
|
||
|
||
```bash
|
||
cd windmill/workspace
|
||
wmill flow get f/attend/attention_loop_e5 --json --workspace personal_os > /tmp/personal-os-e5-before.json
|
||
```
|
||
|
||
Build a scoped candidate from that export, preserving unrelated live modules,
|
||
schema and permissions. Test it and run the inline-source audit below. Publish
|
||
only the approved candidate directory to the existing target:
|
||
|
||
```bash
|
||
wmill flow push /absolute/path/candidate__flow f/attend/attention_loop_e5 --workspace personal_os
|
||
```
|
||
|
||
Export the published target again, repeat the audit and compare the unchanged
|
||
parts with the saved live version. Avoid workspace-wide pulls over local edits.
|
||
|
||
## Database
|
||
|
||
Windmill uses the database `windmill` on the host PostgreSQL 17 (roles
|
||
`windmill`, `windmill_user`, `windmill_admin`). Personal OS data stays in
|
||
`personal_os`. Containers reach the host as `host.docker.internal`.
|
||
|
||
## Host-only work
|
||
|
||
Mattermost and Zoom collectors need the signed-in Chrome on the Mac and cannot
|
||
run inside a worker container. Their browser collection stays on launchd.
|
||
Planning and discussion processing use the authenticated host transport while
|
||
Windmill owns their step order, run identity and schedules.
|
||
|
||
## Personal planning and review (2026-11-13)
|
||
|
||
E5 has separate `production`, `clarify`, `discussion_observe` and
|
||
`discussion_refresh` modes. Production reads current mirrors through the host,
|
||
freezes an evidence snapshot, runs E4 before E5 capacity allocation, validates
|
||
the returned results against that snapshot and current source revisions, and
|
||
publishes the plan. Preparation that creates a new review triggers exactly one
|
||
second planning pass. GTD review, observation and notification follow publication.
|
||
No mode sends a source-system message or treats a human review as already done.
|
||
|
||
Short steps use `personalos_planning` on the reserved planning worker. Model
|
||
inference uses the ordinary `python3` pool. The host only exposes fixed operations;
|
||
it accepts no arbitrary command from a flow argument. A disconnected caller
|
||
cancels its owned subprocess group. Lock contention is reported as `busy`, not
|
||
completed analysis.
|
||
|
||
The four schedule definitions are stored next to E5. They replace only the
|
||
legacy focus-shadow, clarification-worker, discussion-actions and
|
||
discussion-source-observer LaunchAgents. Asana, claims and browser collection
|
||
retain their existing owners. A cutover requires saved flow/LaunchAgent versions,
|
||
no active legacy job, persistent disabling of those four agents, and verification
|
||
of the enabled Windmill schedules. Do not start both sets of owners.
|
||
|
||
UI replanning submits a durable Windmill job ID through `windmill-dispatch.py`.
|
||
An overlapping request is coalesced and drained after the current cycle. It does
|
||
not run a second local planner. Production schedules enforce weekday hours;
|
||
clarification also rechecks hours before inference. Current deployment versions,
|
||
actual jobs and remaining acceptance conditions are recorded in the
|
||
[acceptance journal](../planning/personal-os-production-acceptance.md).
|
||
|
||
## Continuous Asana worker (2026-10-14)
|
||
|
||
`f/fetch/asana_expansion_e1` is scheduled every five minutes, with overlap disabled.
|
||
Its real Python steps call `/asana/status` and `/asana/sync` on the authenticated
|
||
Mac runner. Asana credentials remain on the host. Live project rosters and personal
|
||
sources are scanned every 15 minutes; project events provide intermediate changes.
|
||
The project catalogue adds newly followed projects hourly. Task details, complete
|
||
stories, children, dependencies/dependents, memberships and the old read projection
|
||
are updated through durable PostgreSQL cursors. A denied object enters a six-hour
|
||
retry; transient errors use bounded backoff. No error or completed batch disables
|
||
the schedule. The retired launchd backfill job stays disabled; Windmill owns the
|
||
schedule. Its historical stop file is retained and is not consulted by the worker.
|
||
|
||
The first automatic Windmill job was `01a13b4d-8006-7275-0af2-4cc619eb3fdf`:
|
||
3,000 read requests, 648 tasks refreshed, no source/task errors. This is a bounded
|
||
batch result, not a claim that the initial refresh queue is empty. The dashboard
|
||
header and `/api/asana-worker` show live project freshness, outstanding changes,
|
||
background work and retry errors. See [the worker runbook](../planning/asana-coverage-pilot/expansion-2026-10-06.md#постоянный-worker--14102026).
|
||
|
||
## Incremental claim updates (2026-10-15)
|
||
|
||
`f/analyse/work_claims_extract` is published (version 176) and scheduled every
|
||
five minutes in `Asia/Bishkek`, with `target=primary`, `max_jobs=1` and
|
||
`no_flow_overlap=true`. Both migrations 011 and 012 are applied to `personal_os`.
|
||
The authenticated Mac runner and database browser were restarted after the
|
||
Asana writer checkpoint. The existing pilot runs and claims remain unchanged.
|
||
|
||
The flow has three real steps: `read_tasks` snapshots semantic source changes
|
||
and queues work; `run_model` processes at most one durable job through the host
|
||
runner's `/claims/process`; `write_claims` reports the scan and queue outcomes.
|
||
The host calls the existing local model gateway at `127.0.0.1:8767`. Containers
|
||
use the saved `f/system/work_evidence_runner` resource to reach the host runner.
|
||
Credentials stay in that resource and the host configuration.
|
||
|
||
Existing claims receive sparse `add/update/withdraw` operations with stable IDs
|
||
and history. Unchanged work makes no model call. Human decisions are protected;
|
||
contradictions become proposals for review in the task page's **Анализ работы**
|
||
panel. A completed job does not establish semantic acceptance. The separate
|
||
`f/publish/claims_review` publication flow remains planned.
|
||
|
||
Initial queue processing is ongoing. Packets over 160,000 characters are visibly
|
||
blocked without truncation; retryable errors retain their attempts and backoff.
|
||
`partial` reports pending work even when the Windmill job itself succeeds.
|
||
The interval is a scheduling interval, not a freshness guarantee. Current status,
|
||
CLI commands, verification artifacts and rollback procedure are in the
|
||
[claim-update runbook](../planning/work-claim-updates-2026-10-15.md).
|
||
|
||
## Проверка копий inline-кода перед публикацией
|
||
|
||
Один Python-файл может использоваться в нескольких узлах с разными именами.
|
||
Отбор только по имени узла пропускает обычные и диагностические ветки.
|
||
Перед точечной публикацией проверьте кандидат, после неё — заново полученный
|
||
JSON рабочего flow. Аудитор использует ссылки на файлы из локального `flow.yaml`,
|
||
проверяет каждую копию и отклоняет старую, отсутствующую или лишнюю копию.
|
||
Он ничего не публикует и не запускает задания. Для инструмента нужен PyYAML;
|
||
в среде разработки проверена версия 6.0.3.
|
||
|
||
Из корня репозитория:
|
||
|
||
```sh
|
||
python3 scripts/windmill-inline-audit.py \
|
||
--local-flow windmill/workspace/f/attend/attention_loop_e5__flow/flow.yaml \
|
||
--published /path/to/fetched-flow.json \
|
||
--source read_context.py --source propose_actions.py --source day_constraints.py
|
||
```
|
||
|
||
Ошибку этой проверки требуется устранить до публикации. Остальные узлы,
|
||
входная схема и права сравниваются с полученной рабочей версией отдельно.
|
||
Проверка не разрешает широкую загрузку локальных незавершённых flow.
|
||
|
||
## Рабочие пути шести workflows · 18 ноября 2026
|
||
|
||
По отдельной команде заказчика исправляются именно шесть сохранённых workflows.
|
||
Архив из шестнадцати entries не восстанавливается. Результаты, версии, реальные
|
||
run ID и остаточные ограничения фиксируются в
|
||
[квитанции проверки](personal-os-evidence/2026-11-18/windmill-six-workflows.json).
|
||
Проверка не засчитывает интеграционные прогоны как дни пользовательского пилота.
|
||
|
||
- **E5 — план дня.** Production запускается каждые 15 минут; наблюдение активности,
|
||
обсуждений и уточнения имеют отдельные режимы. Публикация проверяет фактически
|
||
вычисленные E4/E5 результаты против сохранённых входов и текущих источников.
|
||
Сверяются все inline-копии, включая повторные ветки. Тайм-аут наблюдения активности
|
||
согласован с работой сервиса: 90 секунд для HTTP, 105 для шага. Недельный выбор
|
||
включает подтверждённые запросы на ответ и ревью с известной личной ролью,
|
||
даже когда у них нет срочности или связи с текущим Top Priority. Срочность,
|
||
дедлайн и принадлежность к цели при этом не добавляются. Удержанные действия,
|
||
неизвестная роль, сроки, зависимости и резерв продолжают ограничивать отбор.
|
||
- **E4 — ранжирование.** Самостоятельный read-only preview получает готовый пакет;
|
||
сетевого сбора и собственного расписания у него нет. В production применяется
|
||
проверяемая inline-копия rank. Отсутствие отдельного расписания здесь нормально:
|
||
качество сбора источников остаётся обязанностью предыдущих шагов. Проверка E4
|
||
сравнивает реальный Windmill-результат с точным повтором рабочего входа.
|
||
- **Asana E1 — непрерывный сбор.** Расписание — каждые 10 минут с запретом пересечения.
|
||
Текущие назначения и My Tasks получают приоритет перед отслеживаемыми работами
|
||
и историей; отдельная ограниченная доля обработки остаётся для старых ссылок.
|
||
Завершённая история не блокирует свежесть текущих действий. Повторное открытие,
|
||
новые события и отсутствие текущей записи сохраняют требование обновления.
|
||
Признак completed из живого roster сохраняется вместе с checkpoint; история
|
||
и доказательства не удаляются. Завершение ограниченной пачки возвращает partial
|
||
или degraded, пока общий охват неполон. `coverage_complete` отделяет полный
|
||
охват от успешного выполнения кода.
|
||
- **GitHub PR mirror — сбор и сверка.** Запуск — на 3-й, 18-й, 33-й и 48-й минутах
|
||
часа, без пересечения. Охват `personal-current-v1` строится из личных назначений, подтверждённых
|
||
адресных запросов, зависимостей и завершений за семь дней. Канонические родители
|
||
группируют работу, но не добавляют PR соседних задач. Прямые ссылки Asana принимаются из любых доступных
|
||
репозиториев; дополнительный поиск открытых PR по авторству, запросу ревью и упоминанию
|
||
также не ограничен прежним списком репозиториев. Историческое участие в ревью
|
||
не является основанием для автоматического личного охвата. Пустая дата формы означает последние
|
||
30 дней. Исправление старой пустой даты сохраняет обработанную часть очереди.
|
||
Незавершённый автоматический сбор возобновляется при совпадении охвата,
|
||
параметров поиска, личных task ID, политики отбора, кэша и режима артефактов. Исчерпанные ошибки не сбрасываются.
|
||
Блокирующие GitHub/keychain операции выполняются в отдельном последовательном потоке;
|
||
HTTP-сервис остаётся доступным другим рабочим путям. При rate limit сохраняется
|
||
пауза от 15 до 60 минут, очередь не продвигается и попытка PR не расходуется.
|
||
Пауза сохраняется между перезапусками; удержанный результат не запускает verify.
|
||
Повтор поиска после временного пробела выполняется в той же очереди. Повторный сбор merged PR
|
||
использует ограниченный суточный кэш; новая активность в поиске и явный запрос
|
||
code artifacts требуют обновления. Открытые и закрытые без merge PR проверяются
|
||
заново. Сверка проверяет состояние, HEAD, текст и версии комментариев и ревью;
|
||
для открытых PR — также CI и решение ревью. Изменившиеся источники ставятся
|
||
на ограниченный повтор в той же очереди. `verified=false` всегда даёт partial.
|
||
- **Work Claims — кандидаты обязательств.** Расписание — каждые 10 минут,
|
||
до трёх заданий за проход с сохранением общего model lock. Результат содержит
|
||
число ожидающих работ, категории блокировок, число квитанций и ограниченную
|
||
выборку их ID. Полный scan остаётся в шаге read_tasks и в durable receipts;
|
||
большой приватный пакет больше не дублируется в итоговом ответе. Partial,
|
||
ожидание модели и блокировки не объявляются извлечёнными фактами. Сохранённые
|
||
ответы, попытки и решения пользователя не обнуляются ради снятия блокировки.
|
||
- **Work Situations — состояние работ.** Автоматический inventory запускается
|
||
подзадачей GitHub после чтения той же выборки; отдельное конкурирующее расписание
|
||
ему не требуется. Инвентаризация, связи и результаты сохраняются в primary.
|
||
Работы без основания ожидать PR не получают ложный пробел «нет PR»;
|
||
запрос изменений по старому HEAD не становится текущим блокером.
|
||
Подтверждённый merge используется как необратимый факт в пределах ограниченного
|
||
кэша; активные ревью требуют свежего чтения. Результат с пробелами — partial.
|
||
Режим resolve не занимает GitHub writer, использует общий с Claims model lock,
|
||
проверяет revision и stale; повтор request ID не создаёт новую модельную работу.
|
||
Режим запускается отдельным действием агента из интерфейса и возвращает
|
||
кандидата, требующего ревью; создание задачи Asana остаётся отдельным действием.
|
||
|
||
### Проверка эксплуатации
|
||
|
||
Зелёный статус Windmill удостоверяет выполнение кода. Для приёмки дополнительно
|
||
проверяются business result, сохранённый план и недельная привязка, содержимое
|
||
рабочей БД, квитанции модели и фактическая видимость действий в Today.
|
||
`busy`, `skipped`, `deferred`, `partial` и `queued` сохраняют собственный смысл.
|
||
Покрытие всех источников нельзя выводить из количества успешных запусков.
|
||
|
||
`GET /health` аутентифицированного host runner содержит `loaded_code`: PID,
|
||
время запуска и SHA-256 шести загруженных JS-модулей. Перед сдачей требуется
|
||
сравнить их с файлами релиза, затем сверить опубликованные inline-копии.
|
||
Один хеш файла на диске не доказывает, что долгоживущий сервис загрузил правку.
|
||
Перед применением проверяются оба вида модельных заданий: Work Claims и
|
||
work resolution, а также активные HTTP-запросы. Исправленное ожидание обновления
|
||
сохраняет health со статусом draining, новым операциям возвращает 409 и Retry-After;
|
||
текущие запросы завершаются перед закрытием сервера; чужие model jobs и source requests не отменяются. Автоматический
|
||
транспорт ограниченно повторяет только 409 и точно не принятые соединения.
|
||
Неоднозначные тайм-ауты не повторяются как новые операции.
|
||
|
||
Итог технической проверки шести workflows — `verified_with_documented_limitations`.
|
||
Штатный GitHub → Work Situations, конечный ответ resolve и отрицательный
|
||
параллельный запуск проверены по содержимому; это не сдача всей Personal OS.
|
||
Исторический backlog Asana, недоступные источники, удержанные Claims и
|
||
неподтверждённые связи локальной работы отражаются отдельно от исправлений кода.
|
||
|
||
|
||
### Отрицательный рабочий результат: избыточные 385 PR
|
||
|
||
Первый общий обход не принят по релевантности: 355 PR были закрыты, у 78 не
|
||
подтверждена прямая роль в GitHub. Личный отбор дал 51 прямую ссылку
|
||
из 194 личных задач; после восстановления поиска итог составил 78 PR.
|
||
Штатная цепочка `01a1ee01-6cc6-c1c2-0607-3626a283df3a` сверила 48 PR,
|
||
ещё 30 merged использовала из ограниченного кэша; GitHub gaps/errors пусты.
|
||
Это источники проверки, а не 78 задач владельцу. Соседние задачи общего
|
||
родителя не наследуются. Первое удержание secondary rate limit сохранено
|
||
как отрицательный результат. Поведение при лимитах
|
||
соответствует [рекомендациям GitHub](https://docs.github.com/en/rest/using-the-rest-api/best-practices-for-using-the-rest-api):
|
||
последовательные запросы, остановка при ограничении, увеличивающаяся пауза.
|
||
Заголовки retry-after/reset через текущий gh-адаптер не доступны; используется
|
||
консервативная пауза. Общие внешние GitHub-клиенты этим сборщиком не управляются.
|
||
|
||
|
||
Сетевой отказ отдельного PR при verify не должен обрывать остальные проверки:
|
||
источник сохраняется в verification_errors, результат partial, повтор ограничен
|
||
сохранёнными attempts. В рабочем проходе это требование воспроизведено на TLS
|
||
handshake timeout. После освобождения model lock resolve
|
||
`181f13d2-d21e-4217-90b2-074315242405` получил конечный ответ модели;
|
||
две цитаты и task ID проверены, кандидат не принят автоматически.
|
||
Пропуск no_flow_overlap не засчитывается как обработка данных.
|
||
Обслуживание сохранило активный HTTP-запрос Claims; фоновых resolver-заданий
|
||
при drain не было.
|
||
|
||
|
||
CI берётся из raw_json.ci_state: отдельной колонки в github_pr_current нет.
|
||
Сверка проверена на реальной форме БД и контролируемом повторе захваченных
|
||
живых ответов; совпадающее CI не должно повторно ставить неизменный PR.
|
||
Реально изменившееся CI на том же HEAD продолжает давать partial и repair.
|
||
Checkpoint хранит ограниченные примеры различий для воспроизводимой диагностики.
|
||
|
||
|
||
### Ручной и плановый контроллер
|
||
|
||
Schedule no_flow_overlap не защищает от ручного root одновременно с плановым.
|
||
Перед prepare host читает реестр Windmill и допускает старейший активный/уже
|
||
наступивший опубликованный GitHub flow; running=false у ожидающего дочерний шаг
|
||
контроллера не означает завершение. Непосредственный WM_FLOW_JOB_ID передаётся
|
||
отдельно от внешнего root. Дубль получает already_running и owner_job_id до
|
||
подключения к source DB; при недоступном реестре возвращается deferred.
|
||
Эти статусы пропускают сбор, verify и inventory и не считаются обработкой.
|
||
Нативный [concurrency limit Windmill](https://www.windmill.dev/docs/flows/concurrency_limit)
|
||
требует Cloud/Enterprise; его наличие здесь не предполагается. Проверка относится
|
||
к опубликованным manual/scheduled flows; вызовы preview/direct RPC дополнительно
|
||
сериализуются только существующим writer-lock на время операции.
|
||
|
||
Опубликованный v227 проверен отрицательным запуском
|
||
`01a1ee45-c628-71e8-84e0-289c9f9cd4c3`: результат already_running,
|
||
verified=false, work_ids=[] и ссылка на действующий плановый контроллер.
|
||
Сбор и inventory не запускались. Пустая ветка Windmill наследует предыдущее
|
||
значение; итоговый report использует отдельный inventory_requested и проверяет
|
||
форму результата. Пропуск не получает выдуманный inventory; отсутствующий
|
||
действительно запрошенный результат даёт partial/unavailable.
|
||
|
||
Финальные проверки: 56 inline-копий и шесть загруженных JS-хешей совпали;
|
||
48 Node-регрессий с изолированной БД и 11 Python-регрессий прошли.
|
||
В реальном inventory осталось пять явных пробелов данных; Claims и исторический
|
||
backlog Asana также сохраняют ограничения. Подробности и run ID — в
|
||
[протоколе](personal-os-evidence/2026-11-18/windmill-six-workflows.json).
|