Task Matrix
This is a local-first task matrix application. The UI is generated by Hono JSX
on a Cloudflare Worker, HTMX handles partial updates, the Matrix uses
pointer-event drag-and-drop, and task state is persisted in D1.
Configuration layout
Tool configuration lives under .config/. The Taskfile is at
.config/Taskfile.yml, so every task runs as
task -t .config/Taskfile.yml <name>. aqua discovers its configuration through
the committed .aqua/ symlinks (aqua.yaml, aqua-code-mode-host-registry.yaml)
that point at .config/, so aqua-managed commands such as opencode work
without exporting AQUA_CONFIG. Recreate the links if they are missing:
task -t .config/Taskfile.yml setup:aqua-links
env.sh also redirects generated output into tmp/: the Python virtual
environment (.venv), Ruff/pytest caches, and Playwright results. The Taskfile
applies the same values for task-run commands. In
non-interactive shells and CI, source the same file explicitly to get
AQUA_CONFIG and AQUA_POLICY_CONFIG:
. ./.config/env.sh
Setup
Use the Yoriwake-base release as the standard WSL development environment:
On Windows, download siftq-base.tar from the release page, then import it
as a WSL2 distribution:
wsl --import App C:\WSL\App C:\Users\<user>\Downloads\siftq-base.tar --version 2
wsl -d App
Inside the WSL distribution, clone the repository and install project tools and
dependencies:
git clone [email protected]:ANKM0/SIFTQ.git
cd SIFTQ
. ./.config/env.sh
task -t .config/Taskfile.yml setup
If you are using an existing Linux or WSL environment instead of the base
template, install aqua first, then run the same task -t .config/Taskfile.yml setup command. It will install Bun and Vite+ if they are missing.
Development
Start the Worker development server with cf:
. ./.config/env.sh
task -t .config/Taskfile.yml dev
Start the UI preview with fixed mock data:
bun run preview:mock
Open http://127.0.0.1:8787 and sign in with password preview.
Apply the local D1 migrations:
bun x wrangler d1 migrations apply siftq --local -c .config/wrangler.jsonc --persist-to .wrangler/state
Local D1 migration stays on Wrangler: cf d1 migrations apply --local does not
exit in the current cf beta. cf dev reads local state from .wrangler/state
and does not accept --persist-to, so apply migrations there. cf itself uses
Wrangler as its bundler.
Run the unit tests:
vp test run --passWithNoTests
Common checks:
task -t .config/Taskfile.yml ci:typecheck
task -t .config/Taskfile.yml ci:lint
task -t .config/Taskfile.yml ci:test
task -t .config/Taskfile.yml ci:build
Deployment
正規の本番URLは https://app.siftq-app.workers.dev/（Worker名 app）。
Cloudflare Workers とリモート D1 へのデプロイ手順は
docs/contributing/deployment.md を参照する。
Session Backup
Codex と opencode のセッションは age で暗号化して sessions/ へ保存する。
鍵管理・注入・復元・サイズ・履歴の扱いは
docs/contributing/session-backup.md を参照する。
Loop Engineering
The loop engineering direction is recorded in
docs/adr/0012-adopt-taqt-centered-loop-engineering-policy.md. taqt is the
main task/workflow owner, while GitHub monitoring and other external
integrations are script adapters.
CI Checks
Run the same local checks before opening or updating a pull request:
. ./.config/env.sh
task -t .config/Taskfile.yml setup:python
task -t .config/Taskfile.yml setup:frontend:ci
task -t .config/Taskfile.yml ci
Repository Structure
src/: Worker application source..config/: tool and task configuration.migrations/: D1 schema migrations.tests/: unit tests.docs/requirements/: product and system requirements..taqt/runs/: run state, events, and design decision artifacts.docs/adr/: architecture and repository-wide decisions.
