Merge pull request 'Session workflow: pickup and wrap around the task flow' (#85) from task/445-session-workflow into master

2026-08-02 11:39:11 +02:00
parent f4deccacc9 c0d61a71a4
commit bdcfccce77
8 changed files with 480 additions and 2 deletions
@@ -213,3 +213,60 @@ data pans on a phone. Local preview + headless screenshot recipe is in `AGENTS.m

 This repo is project **Maven** (ID 2) in Vikunja. MCP: `http://localhost:9100/mcp` (or
 `http://192.168.1.104:9100/mcp` from workpc). Feature/bug/deploy tasks go there.
+
+Vikunja is the durable task store. A task holds the goal, the constraints and the
+assumption ledger. Work without a task id is work nobody can resume, so a session that
+has no id asks for one before it starts.
+
+## Session workflow
+
+`~/.local/bin/task` owns the branch, the commit identity and the PR. One task, one
+session, one PR.
+
+```sh
+task start <vikunja-id>   # branch off origin/master, write TASK.md, fetch review comments
+task pr                   # push, open or refresh the PR, label Vikunja, notify
+task comments             # re-pull this branch's review comments into .task/
+```
+
+Around that, `/pickup` opens a session and `/wrap` closes it. Wrap at roughly half
+context rather than letting the session compact.
+
+Five stores, and each one owns something the others must not hold:
+
+| Store | Holds | Lifetime |
+|---|---|---|
+| Vikunja task | goal, constraints, assumption ledger, status | durable |
+| `CLAUDE.md`, `AGENTS.md` | what an agent must know before touching code | durable |
+| `docs/` | design, measurements, decisions | durable |
+| `TASK.md` | the brief for this branch, written by `task start`, immutable | one branch |
+| `HANDOFF.md` | only what the next agent needs to resume | one session |
+
+`TASK.md` and `.task/` are excluded through `.git/info/exclude`. `HANDOFF.md` is
+gitignored and injected at session start. If a line in the handoff would still matter
+next week, it is in the wrong file.
+
+Docs are tiered by path, so staleness is visible from the filename. Files directly under
+`docs/` are living and carry a `Last verified: <date> @ <sha>` line. Files under
+`docs/evals/` are dated measurements and are never edited after the day, so a newer
+number is a new file. Files under `docs/archive/` are dead and read by nobody by default.
+
+## Git guards
+
+Two hooks in `.githooks/`, tracked, wired with `core.hooksPath`. Fresh clone:
+
+```sh
+git config core.hooksPath .githooks
+```
+
+- `pre-commit` refuses master, and refuses more than 300 changed lines in non-markdown
+  files. Markdown is exempt and may land as one batch.
+- `commit-msg` requires the subject to end with `(V-<id>)`. `V-` and not `#`, because
+  Gitea autolinks `#123` to a Gitea issue, which is the wrong tracker.
+
+Two more guards live outside the repo, in `~/.claude/hooks/`. `diff-budget.sh` blocks
+further edits past 600 changed lines on a `task/` branch. `prose_lint_hook.py` checks
+prose on every write. Both measure against `origin/master`, so a local master that is
+ahead of the remote makes the diff budget read high.
+
+`--no-verify` exists. Using it means saying why in the commit body.