pyworklog 0.7.0__tar.gz → 0.8.0__tar.gz

{pyworklog-0.7.0 → pyworklog-0.8.0}/.github/workflows/release.yml

@@ -20,7 +20,7 @@ jobs:
       id-token: write   # for PyPI Trusted Publisher (OIDC)
       actions: read     # to read the Test workflow's run status for this commit (release gate)
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0  # need full history for auto-generated release notes
 
@@ -62,7 +62,7 @@ jobs:
           exit 1
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@v8.2.0
         with:
           python-version: '3.12'
           enable-cache: true

{pyworklog-0.7.0 → pyworklog-0.8.0}/.github/workflows/test.yml

@@ -16,10 +16,10 @@ jobs:
         python-version: ['3.9', '3.10', '3.11', '3.12', '3.13', '3.14']
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@v8.2.0
         with:
           python-version: ${{ matrix.python-version }}
           enable-cache: true
@@ -32,7 +32,7 @@ jobs:
 
       - name: Upload coverage to Codecov
         if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v7
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: ./coverage.xml
@@ -40,12 +40,19 @@ jobs:
 
       - name: Smoke test CLI
         run: |
+          set -euo pipefail
           export WORKLOG_DB=$(mktemp -d)/worklog.db
           uv run wl init
           uv run wl --version
-          uv run wl add "ci smoke task" -k task -p A
+          uv run wl add "ci smoke task" -k task -p A --sched today
           uv run wl log 1 "hello from CI"
-          uv run wl done 1
+          uv run wl recap "ci smoke recap"   # creates today's day skeleton so the overview renders
           uv run wl show 1
-          uv run wl tree
+          uv run wl day
+          # wl tree must render real structure (the timeline + the scheduled task),
+          # not just exit 0 on an empty overview — assert the task title shows up.
+          tree=$(uv run wl tree)
+          printf '%s\n' "$tree"
+          printf '%s\n' "$tree" | grep -q "ci smoke task" || { echo "::error::wl tree rendered no structure"; exit 1; }
+          uv run wl done 1
           uv run wl migrate

{pyworklog-0.7.0 → pyworklog-0.8.0}/.gitignore

@@ -223,3 +223,4 @@ __marimo__/
 wl.py.bak
 TODO.local.md
 local/
+experiments/

{pyworklog-0.7.0 → pyworklog-0.8.0}/AGENTS.md

@@ -7,7 +7,7 @@ Primary operating guide for AI coding agents (Claude Code, Cursor, Aider, etc.)
 - **`DESIGN.md`** is canonical for every shared convention (command style, state machine, marker symbols, time-window flags, rendering, schema, import/apply formats, color theming, scheduled time, planned/unplanned derivation, etc.). Read the relevant section before adding a command or changing a format — keeping `src/worklog/cli.py`, the tests, the completion strings, and DESIGN in sync is the project's hardest rule.
 - **`CONTRIBUTING.md`** holds the full dev setup, TDD + DRY conventions, local Makefile overrides, and release process. Do not duplicate that content here.
 - **`skills/worklog-cli/SKILL.md`** is the Claude Code skill (AI-facing usage guide: when to use `wl`, scenario→command table, bulk `import` / `apply` patterns, `-q` brief mode for token savings). Update this when usage patterns change.
-- `README.md` is the project overview + install pointer only; `tests/test_wl.py` is the de-facto contract for every command.
+- `README.md` is the project overview + install pointer only; the `tests/test_*.py` suite (split by area) is the de-facto contract for every command.
 
 ## Common commands
 
@@ -17,7 +17,7 @@ make test           # pytest in parallel (-n auto) with the 95% cov gate from py
 make test-v         # sequential, no cov — debug noisy output
 make test-fast      # parallel, no cov gate — quick dev loop
 make cov            # detailed term-missing coverage report
-make demo           # reset DB + populate sample tree (irreversible)
+make demo           # populate a FRESH demo DB (refuses if the DB exists; use WORKLOG_DB=/tmp/wl-demo.db)
 make reset          # interactive: drop current DB + re-init
 make ship           # test then push (only pushes if green)
 ```
@@ -25,7 +25,7 @@ make ship           # test then push (only pushes if green)
 Single-test invocation:
 
 ```fish
-uv run pytest tests/test_wl.py::TestApply::test_apply_delete_cascades_subtree -v --no-cov
+uv run pytest tests/test_add.py::TestAdd::test_add_task -v --no-cov
 ```
 
 Ad-hoc DB for scratch work without touching `~/.local/share/worklog/worklog.db`:
@@ -41,30 +41,34 @@ wl --db /tmp/scratch.db add "..."
 
 **Single-package CLI.** `src/worklog/` holds everything: `cli.py` (~5000 lines) is the implementation, `migrations/NNNN_*.sql` is the schema (one initial file at v0.3.0, more added per schema change), `__init__.py` re-exports `__version__`. No further submodule split inside `cli.py` — kept this way intentionally; reconsider only when a feature truly cannot be co-located.
 
-**One polymorphic `node` table.** The `kind` column distinguishes `lifetime / decade / year / quarter / month / week / day / area / project / task / meetlog / habit / signal`; `parent_id` self-reference builds the tree. Two parallel sub-trees hang under `lifetime`: a **responsibility line** (`area → project → task`, PARA-style) and a **time line** (`year → quarter → month → week → day`, time skeleton + metadata props). Day/week/month views are **log-driven** (`logged_at` + ancestor chain + tags), not via fixed parent-of-task — moving projects between areas does not break per-day views. Tables: `node / tag / log / prop / link / sched / date_meta` + recursive CTE view `v_node_path`.
+**One polymorphic `node` table.** The `kind` column distinguishes `lifetime / decade / year / quarter / month / week / day / area / project / task / meetlog / habit / signal`; `parent_id` self-reference builds the tree. Two parallel sub-trees hang under `lifetime`: a **responsibility line** (`area → project → task`, PARA-style) and a **time line** (`year → quarter → month → week → day`, time skeleton + each level's `goal` / the day's `summary` reserved-tag logs). Day/week/month views are **log-driven** (`logged_at` + ancestor chain + tags), not via fixed parent-of-task — moving projects between areas does not break per-day views. Tables: `node / tag / log / prop / link / sched / date_meta` + recursive CTE view `v_node_path`.
 
 **Path resolution.** Priority: `wl --db PATH` flag → `$WORKLOG_DB` env → `$XDG_DATA_HOME/worklog/worklog.db` (default `~/.local/share/worklog/worklog.db`). Config is `$XDG_CONFIG_HOME/worklog/aliases.ini`. `_resolve_db_path(args)` is the only resolver; `cmd_config` displays which branch fired.
 
-**Subcommand dispatch.** `build_parser()` constructs the argparse tree (one `sub.add_parser(...)` block per command, with `help` + `description` + `epilog`). `HANDLERS = {"cmd": cmd_handler}` maps the parsed name to `cmd_<name>(args, con) -> None`. `main()` resolves user aliases (`~/.config/worklog/aliases.ini`), routes meta-commands (`print-completion`, `config`) that bypass `ensure_db()`, applies `--db` override, then calls the handler. Tests invoke `HANDLERS[cmd](args, con)` directly through the `cli` fixture to bypass `main()`.
+**Subcommand dispatch.** `build_parser()` constructs the argparse tree (one `sub.add_parser(...)` block per command, with `help` + `description` + `epilog`). `HANDLERS = {"cmd": cmd_handler}` maps the parsed name to `cmd_<name>(args, con) -> None`. `main()` resolves user aliases (`~/.config/worklog/aliases.ini`), routes bootstrap commands (`print-completion`, `config`) that bypass `ensure_db()`, applies `--db` override, then calls the handler. Tests invoke `HANDLERS[cmd](args, con)` directly through the `cli` fixture to bypass `main()`.
 
 **Rendering pipeline.** All output goes through `out()` (rich-aware) — never bare `print()` for user-visible rows. `_c(text, style)` is the single coloring entry: when `_CONSOLE` is set, it escapes content via `rich.markup.escape` (so `[x]`, `[[doc]]`, `[#A]` aren't eaten as rich markup) and wraps with `[style]…[/style]`; when console is plain, it returns the string. **Any fragment that may contain `[ ]` must go through `_c`** — direct insertion triggers `rich.MarkupError` or silent eating. `_node_line(con, n, ...)` is the **only node renderer**; reuse it everywhere listing nodes, including new commands, to inherit highlighting + search-hit emphasis for free. `_init_console` runs once in `main()`; tests run in plain mode (no TTY).
 
+**"meta" is internal-only — never a user-facing concept.** The string `meta` survives in the code ONLY in implementation roles, none of which denote a wl feature: the `"meta"` theme/style key (the grey auxiliary-text rendering role, used as `_c(text, "meta")`), the `date_meta` table name, argparse parser-metadata helpers (`_collect_sub_meta`), and incidental module names. There is **no "meta field" / "meta" concept in wl's design** — that was removed; a node's forward `goal` and backward `summary` are *reserved-tag logs* (`log.tag`), managed by `wl goal` (see `wl help goal`). Do **not** reintroduce "meta" in any user-facing surface — command names, `--help` text, `-o json` keys, or DESIGN's user-model sections. These internal usages are kept only because renaming them is churn with zero behavior change; they must stay invisible to the user.
+
 **Shell completion is generated, not hand-written.** `wl print-completion {fish,bash,zsh}` walks the argparse tree at runtime and emits a script tailored to that shell. Each shell template contains a `__wl_db_path[_bash|_zsh]` helper that queries SQLite directly for dynamic node-id / tag completions — **no Python startup**, so Tab is <50ms. When you add a subcommand or flag, completion is automatic; **but** if it takes a node id or tag, register it in `_FISH_POSITIONAL_NODE` / `_FISH_HELPERS` / `_BASH_DYN_HELPERS` so dynamic completion fires.
 
 **Coverage gate is hard (95%).** `pytest.ini` enforces `--cov-fail-under=95`; the CI runs the same. The two pragma-no-cover regions are TTY/escape-sequence probes in `_detect_bg_is_dark` and the bare `main()` entrypoint (tests bypass it).
 
 ## Core principles
 
-- **TDD (Red → Green → Refactor).** Behavioral changes start with a failing test in `tests/test_wl.py` that reproduces the bug or pins the new behavior. Confirm it fails for the right reason, then write the minimum code to make it pass, then refactor. Tests stay green at every step. A PR that adds behavior without adding the test that drives it is rejected. See CONTRIBUTING.md "TDD" for the full loop.
+- **TDD (Red → Green → Refactor).** Behavioral changes start with a failing test in the matching `tests/test_<area>.py` that reproduces the bug or pins the new behavior. Confirm it fails for the right reason, then write the minimum code to make it pass, then refactor. Tests stay green at every step. A PR that adds behavior without adding the test that drives it is rejected. See CONTRIBUTING.md "TDD" for the full loop.
 - **DRY (Don't Repeat Yourself).** The codebase has a small set of single-source helpers — `_status_marker`, `_node_line`, `out`/`_c`, `_resolve_window`, `_resolve_db_path`, `_project_members`, `_node_clock_min`, `_collect_descendants` (see DESIGN §12 for the full list). New code reuses them; re-implementing one of them in a fresh form is a review block. Same rule for docs: install / dev / release info is in CONTRIBUTING.md and only there — link to it, don't restate it.
 
 ## Hard rules
 
-- **DESIGN.md is the source of truth.** If a convention changes (statuses, markers, time-window flag set, project↔task linkage rule, `--by` aggregation dim, theme key set, schema), update DESIGN + `src/worklog/cli.py` + tests + completion strings in the same commit. Drift between them is the failure mode this project guards against.
+- **Keep every surface in sync, same commit.** A command/flag/behavior change isn't done until all its descriptions agree — update `src/worklog/cli.py` (incl. its `help=`/`epilog`/`description`) + shell completion + the `wl help <topic>` doc + `tests/` + a `CHANGELOG.md` `[Unreleased]` line, plus `DESIGN.md` (+`.zh`) if a convention changed and `SKILL.md` if everyday usage changed. Drift between them is the failure mode this project guards against. (Full checklist: CONTRIBUTING.md "Keep every surface in sync".)
 - **Status / priority / theme key names** are enumerated in DESIGN §3/§5/§19; add to `_THEME_KEYS` when introducing a new palette entry — `test_themes_have_same_keys` catches misses.
 - **No bare `print()` for renderable content**; all rows go through `out()` + `_c()`.
 - **Bulk writes default to `--dry-run`.** `wl apply` and `wl import` validate first, then execute as a single transaction (`_collect_descendants` recurses for the `-` delete prefix because the FK is `ON DELETE SET NULL`, not cascade). Update flags strictly: only fields that appear in the diff are touched — see DESIGN §18.2 "anti-wipe" rule.
 - **No internal task-tracker ids in the repo.** This is a public repo; the maintainer tracks work in a private system whose ids are meaningless to outside readers. Never write a `WL#NNN` or a bareword `#NNN` design backref in source comments, docstrings, tests, the changelog, or commit / PR text — a bare `#NNN` also renders as a GitHub issue/PR link and misleads. Describe the change in prose instead ("the dedup-warning feature", "the focus-on-day-node fix"); if you must label it, write `task NNN` without the `#`. **Preserved** (these are not backrefs): illustrative example ids in usage snippets (`wl show 42`), the `#L<id>` / `node #123` format documentation, and the deliberately-nonexistent ids in apply/import test fixtures (`#999` / `#888`).
+- **Write docs terse.** SKILL.md, CHANGELOG, help topics, DESIGN: short, plain sentences — say it clearly and stop. No multi-clause run-ons, no over-explaining. A CHANGELOG entry is one tight highlight line (command + what changed), not a paragraph; SKILL rows stay scannable.
+- **No links to the maintainer's private files.** Never reference a private memory (`feedback_…`) or a maintainer-specific path (their `~/projects/…`, personal notes) from anything in this repo — those mean nothing to other readers; keep guidance self-contained. (Standard user-config targets in install instructions, e.g. `~/.claude/hooks/` / `~/.claude/settings.json`, are fine — every user has those.)
 - **i18n layout.** README + DESIGN are bilingual (`*.zh.md`), `src/worklog/cli.py` strings + tests + SKILL.md are English. CJK fixtures in tests are intentional (they exercise unicode width / sort / title handling).
 - **`tmp_path_home` test fixture pattern.** When a test changes `$HOME` to assert path resolution, it must also `monkeypatch.delenv("XDG_CONFIG_HOME")` + `delenv("XDG_DATA_HOME")` — CI runners preset XDG vars and otherwise leak through. See `TestUserAliasesIni._setup_aliases` for the working pattern.
 

pyworklog-0.8.0/CHANGELOG.md

@@ -0,0 +1,215 @@
+# Changelog
+
+All notable changes to **worklog** are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+The autogenerated `Commits since vX.Y.Z` block on each GitHub Release captures every commit; this file is the human-curated highlight reel — keep entries to one tight line. **Breaking changes go in a `### Breaking` section, listed first in the release** (env/path/schema migrations, renamed or removed commands/flags, changed contracts).
+
+## [Unreleased]
+
+## [0.8.0] - 2026-06-14
+
+### Breaking
+- **`wl meta` removed — merged into `wl goal`.** `meta set/ls/rm` → `goal set/ls/rm <node>`; `overview`/`top5` collapse into one `goal` tag (level = node kind); migration 0010 retags old logs.
+
+### Changed
+- **`wl agent ls` reworked** — recency-sorted, capped at 12 (`--all`), width-adaptive session id, per-day grouping by default (`--flat` off), `--by active|bound`.
+- **Unset priority renders `[# ]`** (4 cols, one `_pri_marker`) — fixes column misalignment + the `[ ]`/TODO collision.
+- **`wl agent` records which runtime** (claude/cursor/codex, from `--agent`/`$WL_AGENT`), writing `agent_session` + `agent` metrics.
+- **`wl agent <id>` records history by default** (was `--record`; `--no-record` skips).
+- **`wl tree`'s empty overview is honest** — tells a truly-empty DB from out-of-scope nodes (points at `--depth 9` / `ls --all`).
+- **Migrations snapshot the DB first** to `<db>.pre-v<N>.bak`, so a bad migration is recoverable.
+
+### Added
+- **`wl query` / `wl reindex` — hybrid (semantic + keyword) search.** `wl reindex` embeds each node's chunks (head + per-log) via an OpenAI-compatible server (default local Ollama) into a sidecar LanceDB; `wl query` RRF-fuses best-chunk cosine with a jieba-segmented, `[synonyms]`-expanded keyword match — paraphrases *and* exact names both surface — showing the matched passage, term-highlighted (`--limit`/`--threshold`/`-o json`). Configurable backend + `query_prompt` template (`wl config`). Pluggable, graceful degradation: the `semantic` extra (LanceDB + jieba) is the fast path, but absent it `wl query`/`reindex` auto-fall-back to a pure-Python SQLite vector store + `\w+` segmentation — so semantic search works on every Python 3.9–3.14 / platform with no required extras (slower where there's no LanceDB wheel: Intel macOS, musl, …).
+- **`wl help` is a short overview; `wl help --all` lists every topic.**
+- **Structured goal targets — `wl goal "..." <ids>`** records the task nodes a goal targets (order = priority) as queryable `goal` metrics; shown as `[done/total]` in `wl day`/`wl goal`.
+- **`wl show` timeline marks a log's tag** — `✎ goal`/`✎ summary`/`✎ <custom>` vs plain `✎ log`.
+- **`wl day` header shows the day node id** (`#<id>`).
+- **Relations show under `props:` + derived `=backrels`** in `wl show` / `-o json`.
+- **Node ids are highlighted** (green) across all output.
+- **`wl relation`** — task↔task relations (`split-from`/`split-into`/`related`), bidirectional, stored as `relation.*` props; `wl add --relation` links at creation.
+- **`wl kinds` / `wl tags` / `wl props` / `wl metrics`** — cross-node "vocabulary in use" lists (+ `-o json`).
+- **`wl agent context`** — prints the session binding (`--hook` for `UserPromptSubmit` JSON); ships jq-free integrations.
+- **`--width {full,help,N}` / `$WORKLOG_WIDTH`** — cap output width.
+- **`--title {wrap,clip}` / `$WORKLOG_TITLE`** — wrap long titles hang-indented (default) or clip to one line.
+- **`wl day` / `wl tree` titles wrap hang-indented too** (shared with `_node_line`).
+- **Aliases can carry arguments** — `wl alias add w "day -t work"` → `wl w` == `wl day -t work`.
+- **`--prop` filter** on list/view — `--prop release=v0.7.0` / `linear.id` / `github.*`; repeatable = AND.
+- **`--priority` / `-p` filter** on `ls`/`tree`/`day`/`agenda`/`logs`; `--status` takes comma any-of.
+- **`-o json` output** on `show`/`ls`/`logs`/`projects`/`day`/`tree`/`summary` — stable field names, empty → `[]`.
+- **`wl day` header is clearer** — distinct markers for goal/recap/week/month (🎯/📝/📅/⭐); goals naming `#ids` show `[done/total]`.
+
+### Fixed
+- **`wl find` highlights hits in tag/prop/link matches too.**
+- **Fish completion of an alias offers the target's positional args** (`wl w <TAB>` suggests dates).
+- **Fish completion no longer breaks on a `"` in help text** (descriptions single-quoted).
+- **`wl agent ls` columns align** (`#id` + `<agent>:<sid>` padded uniform).
+- **`wl summary --by day` shows a `worked` group per day** — tasks logged that day.
+- **`make demo` refuses to overwrite an existing DB.**
+- **`wl add` / `wl log` stamp the current time** in the success line.
+
+## [0.7.0] - 2026-06-09
+
+### Added
+- **Signed relative-delta dates** — `+1` / `-2d` / `+3w` / `+1m` / `-1y` on every date-accepting command (`wl day -2`, `wl sched 42 +3w`, `wl log … --date -1d`); month/year deltas clamp the day.
+- **Relative date words resolve everywhere, connector- and case-insensitive** — `next-week`/`-month`/`-quarter` → that period's first day; `NEXT_WEEK` / `next week` / plurals parse. `someday` stays `defer`-only.
+- **`wl agent`** — bind the current AI session to a task (`wl agent <id>` / show / `ls` / `rm`); stored as the `agent_session.claude` prop, rebinding moves it.
+- **`wl agent <id> --record`** — also writes a log + an `agent_session` metric with the full session id, so `wl metric ls <id> --tag agent_session --all` recovers every session a node was worked under. (Became the default in [Unreleased].)
+
+### Changed
+- **`wl set` / `wl prop set` / import `props` refuse reserved node-field names** (`status`/`priority`/`title`/…) so a prop can't shadow a real column (it had produced two `status` values in `wl show`).
+- **Wider Python support: 3.9–3.14** (was 3.11+) — no 3.10/3.11-only feature used; CI tests the full matrix on Ubuntu + macOS.
+
+### Docs
+- **README reframed around AI-first / local-first** — scannable Why/Features, a Quickstart, Python req in prose (EN + 中文).
+- **Internal task-tracker ids dropped from the public repo** + a hard rule in `AGENTS.md`.
+
+## [0.6.0] - 2026-06-07
+
+### Added
+- **`wl show` annotates a recurring schedule with its next occurrence** (`recur weekly:Mon,Fri (next 2026-06-08 Mon)`).
+- **`wl help` — a topic browser** (`wl help` index / `wl help <topic>`): repo-managed Markdown under `src/worklog/help/<lang>/`, i18n-ready, tab-completable; `--help` points into it. 18 topics.
+- **`wl node` group** — `node add / ls / show / edit / rm / reparent`; starts the `<entity> <verb>` reshape (`wl add` == `wl node add`). `reparent` has cycle guards; `rm` is soft-delete.
+- **`wl prop` + `wl clock` groups** — `prop set/ls/rm` (with a `wl unset` shortcut to finally remove a prop); `clock ls/edit/rm` (intervals still created by `start`/`stop`/`spent`).
+- **`wl link` group + default-verb mechanism** — `link add/ls/rm`; for a collision-name entity, a non-verb token after it is taken as an id, so `wl link 42 doc` still works.
+- **`wl tag` / `wl log` / `wl sched` reshaped into default-verb groups** — everyday `wl tag 42 +x` / `wl log 42 "…"` / `wl sched 42 <when>` unchanged; each gains `ls`/`rm` (+ `log edit`/`rm` = relog/unlog).
+- **`wl date` group** (`date set/ls/rm/import`) completes the reshape; `wl dateinfo` stays the shortcut.
+- **`wl meta` group** — `meta set/ls/rm <node> <field>` for goal/summary/overview/top5 (append typed log); `wl set`/`unset` key-route to meta vs prop.
+- **`wl alias add/ls/rm`** — manage `~/.config/worklog/aliases.ini` (`wl d` == `wl day`).
+- **Newcomer-friendlier `--help`** — quickstart line, commands-by-purpose map, Concepts glossary, per-arg help, and explainers on `wl add`/`day`/`goal`/`recap`.
+- **Single-letter flags** `-d` (`--date`) / `-n` (`--note`) on the daily-workflow commands.
+- **Help cross-references shortcut ↔ canonical both ways** (DESIGN §1.2).
+
+### Changed
+- **`wl -h` colorizes to match `wl help`** (3-tier scheme; no-op when color is off; epilogs may use the restricted Markdown).
+- **`--help` epilogs slimmed** — full detail moved to `wl help` topics, leaving summary + examples + a pointer (~23 commands).
+- **`--help` wraps with a hanging indent + caps width** (`_WlHelpFormatter`, 100 cols), measured on visible width.
+- **Removals are reversible (soft-delete tombstones), FKs off** — `deleted_at` on every table; reads filter tombstones; app-level cascade (prep for CRDT sync). Migrations 0008/0009.
+
+### Fixed
+- **Width handling hardened** (GPT-5.5 / Kimi / Codex cross-model review) — display-column measurement everywhere (`east_asian_width`, CJK=2, separators=1), char-break for over-long tokens, mono no longer leaks italics, narrow-terminal floors.
+- **`wl show` timeline lines no longer overflow** — truncation budgets the real prefix width.
+- **`wl help <topic>` renders a Markdown subset + escapes literal brackets** (no crash on `[ ]`/`[x]`).
+- **`wl tree --root <month>` / `focus <month>` show `@month`-pinned tasks** (the parent_id walk missed them → false "nothing scheduled").
+- **Shell completion for default-verb group leaf args** (`wl sched <id> --recur`, `wl log <id> --date`).
+- **`parent_id` cycle safety** — bulk apply/import refuse a self/descendant parent; ancestor/descendant walks are visited-set guarded.
+- **`wl link` strips an outer `[[ ]]`** — `[[X]]` and `X` store identically.
+- **`wl day` drops the redundant `«planned·not-done»` hint under `--by plan`.**
+
+### Internal
+- **Command taxonomy documented (DESIGN §1.1)** — primitive CRUD / composite helper / view.
+- **More raw SQL moved onto `db_table`** — `_insert_log` returns the id; only genuinely complex JOIN/window/aggregate SQL stays raw.
+
+## [0.5.0] — 2026-06-05
+
+### Breaking
+- **`at`/`date` timestamp convention — `*_at` instants stored UTC, `*date` calendar days kept local.** `node.scheduled_at`→`scheduled_date`, `deadline_at`→`deadline_date` (column rename); existing rows migrated local→UTC (migration 0007). Transparent to CLI users; **direct-DB consumers must use the new column names and expect UTC instants.** `$WORKLOG_TZ` pins a fixed offset.
+
+### Added
+- **Shared `--tag`/`--kind`/`--status` filter across `ls`/`tree`/`day`/`logs`/`agenda`** — one meaning everywhere; `-t` is comma-separated AND.
+- **`wl day` header states the day's nature** — `workday`/`weekend`, refined to `holiday`/`leave` via `wl dateinfo`.
+
+### Changed
+- **Day-grouping converts UTC→local before bucketing** (so a log near local midnight lands on the right day).
+- **Habit month-to-date label → English** (`(this month N/M)`).
+
+### Internal
+- **Zero-dependency single-table CRUD layer (`db_table`)** — all single-table SQL routes through it; codified as design goal G3 (complex queries stay raw).
+
+## [0.4.0] — 2026-06-05
+
+### Fixed
+- **`wl sched` is idempotent** — re-scheduling the same date/recurrence reports `= already scheduled`, no duplicate row.
+- **`wl day` no longer tags DONE/CANCELED tasks `«planned·not-done»`.**
+- **`wl focus <day>` expands that day's activity** (was missing tasks hung under projects/habit groups).
+- **Auto-created day builds its full time-ancestor chain** (fixes broken per-month aggregation).
+- **`wl apply` gives an actionable error for an un-indented field op** (instead of "cannot parse").
+- **Shell completion stops offering `someday` for concrete-date commands.**
+- **Flat `wl logs` row stays one line with CJK titles** (display-width budget, not a 30-char slice).
+- **`wl day` plan grouping collapsed to planned/unplanned** (dropped the confusing third bucket).
+
+### Added
+- **`wl agenda <start> <end>`** — cross-range scheduling overview reading both schedule sources (concrete days + fuzzy `@month`/`someday` pins).
+- **`wl add` warns when a similar open task/project exists** (non-blocking title-similarity check).
+- **`wl tag <id> +work -planned`** — edit real tags; rejects the old shadow-`tags`-prop footgun.
+- **`wl unlink <id> "doc"`** — remove a single vault link.
+- **`wl recap --date`** — read/back-fill a past day's recap; stamps the staleness marker; builds the day on demand.
+- **Habit lines show month-to-date completion** (`(this month N/M)`).
+- **Metrics fold under their node/log** in `show`/`day`/`tree` (`↳ [glucose] 5.4 mmol/L`).
+- **`node → log → metric` data model** — `metric` table for structured datapoints; `log` gains a `tag`. Migrations 0002/0006.
+- **`wl metric add/ls/edit/rm`** — datapoint CRUD; ids are `#M<id>`.
+- **`--metric` shortcut on `wl log` / `wl add`.**
+- **Habit check-in is a structured signal** — `checkin` metric (idempotent per day); migration 0003 backfills.
+- **`wl import` supports metrics.**
+- **Structured time tracking (`clock` table)** — `start`/`stop`/`spent`/`wait` use a typed interval table; migration 0005.
+- **Day/week/month meta fields keep history** (typed logs, not props); migration 0004.
+- **`wl show` displays the schedule.**
+- **`-q`/`--brief` accepted after the subcommand too** (`wl day -q`).
+- **`wl done` warns on recurring tasks** (use `wl tick` for one occurrence).
+
+## [0.3.0] — 2026-06-01
+
+### Added
+- **`pip install pyworklog`** — ships as a proper package with a `wl` entry point; dist name is `pyworklog` (short names were taken).
+- **SQL migrations runner** — `migrations/NNNN_*.sql` tracked by `PRAGMA user_version`; `wl migrate` is the explicit form.
+- **Downgrade guard** — aborts if the DB is newer than the running build.
+
+### Changed
+- `wl.py` → `src/worklog/cli.py`, `schema.sql` → `migrations/0001_initial_schema.sql`.
+- `__version__` reads from package metadata — `pyproject.toml` is the single version source.
+- `--cov` target `wl` → `worklog`.
+
+### Removed
+- Hand-edited `__version__` in `wl.py`.
+
+### Migration notes
+- DB path unchanged; existing DBs upgrade transparently (verified on a 311 KB backup, integrity ok). Re-run `make install` so `~/bin/wl` points at the new venv.
+
+## [0.2.0] — 2026-05-31
+
+### Breaking
+- **Namespace `wl` → `worklog`** — DB + config paths and env vars renamed: `~/.local/share/wl/wl.db` → `…/worklog/worklog.db`, `~/.config/wl/aliases.ini` → `…/worklog/`, `$WL_DB`/`$WL_COLOR`/`$WL_THEME` → `$WORKLOG_*`. The `wl` command itself is unchanged — but **move your DB/config and update env vars** (or re-run `make setup`). The pre-XDG fallback `~/.worklog/wl.db` is gone.
+
+### Added
+- **`wl config`** — prints resolved paths / env / runtime info (read-only).
+- **`wl --db PATH`** — per-invocation DB override (beats `$WORKLOG_DB` + XDG default).
+- **XDG Base Directory spec** — DB at `$XDG_DATA_HOME/worklog/`, aliases at `$XDG_CONFIG_HOME/worklog/`.
+- **CI matrix** (Ubuntu + macOS × Python 3.11–3.13) + Codecov + README badges.
+- **Release workflow** — a `v*` tag verifies version anchors, runs tests, publishes a GitHub Release.
+- **`AGENTS.md`** (TDD/DRY rules) + **`CONTRIBUTING.md`** (dev setup, release).
+
+### Changed
+- **uv replaces venv/pip/requirements** (`pyproject.toml` + `uv.lock`).
+- Test fixture clears `XDG_CONFIG_HOME` / `XDG_DATA_HOME`.
+
+### Removed
+- `requirements*.txt`.
+
+## [0.1.0] — 2026-05-31
+
+Initial open-source release of `worklog-cli` (`wl`).
+
+### Added
+- **Single-table execution-system model** — one `node` table (13 kinds, one id space, `parent_id` tree) + 6 sibling tables (`log`/`tag`/`sched`/`prop`/`link`/`date_meta`).
+- **Seven-state lifecycle** — TODO/DOING/LATER/WAIT/DONE/DEFERRED/CANCELED (superset of markdown's four) + A/B/C priority + auto `closed_at`.
+- **37 subcommands** — create/edit, logging, state transitions, views, meta fields, scheduling, bulk I/O, search, display (most with short aliases).
+- **Scheduling with recurrence** — `sched` table holds one-off dates + rrules; "planned" is derived from it, not a manual tag.
+- **Time tracking** — `start`/`stop`/`spent`/`active`/`wait`.
+- **Project association via shared tags** — `wl projects` rolls members up by children + shared tags (generic tags excluded).
+- **Bulk loaders** — `wl import` (JSON) / `wl apply` (wl-diff).
+- **Compound flags** on `add`/`done`/`cancel` (create + log + close + timestamp + link + schedule in one).
+- **Date aliases** — `today`/`yesterday`/… + Chinese equivalents.
+- **Brief mode `-q`** on every command (~50–90% fewer chars for AI consumers).
+- **`rich` highlighting** with dark/light/mono themes (background auto-detect).
+- **Shell completion** (fish/bash/zsh) via `wl print-completion`.
+- **Vault integration** — `wl link` ↔ Obsidian docs (`[[doc]]`).
+- Bilingual docs (EN + 中文); MIT License.
+
+[Unreleased]: https://github.com/xyb/worklog/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/xyb/worklog/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/xyb/worklog/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/xyb/worklog/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/xyb/worklog/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/xyb/worklog/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/xyb/worklog/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/xyb/worklog/releases/tag/v0.1.0

{pyworklog-0.7.0 → pyworklog-0.8.0}/CONTRIBUTING.md

@@ -5,7 +5,7 @@ Thanks for considering a contribution! This guide covers the local setup, the de
 ## Prerequisites
 
 - [uv](https://docs.astral.sh/uv/) — install via `brew install uv` or `pipx install uv`.
-- Python ≥ 3.11. `uv` handles the interpreter — no system Python juggling.
+- Python ≥ 3.9 (tested on 3.9–3.14). `uv` handles the interpreter — no system Python juggling.
 
 ## Quick start
 
@@ -25,8 +25,8 @@ make test          # parallel, cov, 95% gate  — pre-commit baseline
 make test-fast     # parallel, no cov, no gate — quick iteration
 make test-v        # sequential, verbose, no cov — debug a single failure
 
-# single test by node id
-uv run pytest tests/test_wl.py::TestApply::test_apply_delete_cascades_subtree -v --no-cov
+# single test by node id (tests are split by area: test_add.py / test_agent.py / …)
+uv run pytest tests/test_add.py::TestAdd::test_add_task -v --no-cov
 
 # coverage gate already lives in pytest.ini (--cov-fail-under=95); `make cov`
 # just re-runs `make test` with term-missing output for inspection.
@@ -44,10 +44,21 @@ wl --db /tmp/scratch.db add "experiment"
 
 ## Architecture
 
-`DESIGN.md` is canonical for every shared convention — command style, state machine, marker symbols, time-window flags, render pipeline, schema, `import` / `apply` formats, theme keys, scheduled-time resolution, planned/unplanned derivation. Read the relevant section before adding a command or changing a format. If your change touches a convention, the same commit must update **DESIGN.md + `src/worklog/cli.py` + `tests/test_wl.py` + completion strings together** — drift between them is the failure mode this project guards against.
+`DESIGN.md` is canonical for every shared convention — command style, state machine, marker symbols, time-window flags, render pipeline, schema, `import` / `apply` formats, theme keys, scheduled-time resolution, planned/unplanned derivation. Read the relevant section before adding a command or changing a format.
 
 `AGENTS.md` is the operating guide for AI coding agents (Claude Code, Cursor, Aider). Skim it once even if you code by hand; it concentrates the hard-rules into one page.
 
+### Keep every surface in sync (same commit)
+
+A command/flag/behavior is described in many places; a change isn't done until they all agree. Drift between them is the failure mode this project guards against. When you touch one, update in the **same commit**:
+
+- **`src/worklog/cli.py`** — the implementation + its argparse `help=` / `epilog` / `description`.
+- **Shell completion** — a new command/flag must appear; if it takes a node id or tag, also wire `_FISH_POSITIONAL_NODE` / the dynamic helpers (it regenerates from the parser, but id/tag completion is hand-registered).
+- **`wl help <topic>`** — the matching topic doc under `src/worklog/help/<lang>/`.
+- **`CHANGELOG.md`** — a one-line `[Unreleased]` entry; a **breaking** change (env/path/schema migration, renamed or removed command/flag, changed contract) goes in a `### Breaking` section, listed first in the release.
+- **`tests/test_<area>.py`** — the test that pins it.
+- **`DESIGN.md`** (+ `DESIGN.zh.md`) if a convention changed; **`skills/worklog-cli/SKILL.md`** if everyday usage changed.
+
 ## Writing `wl help` topics
 
 `wl help <topic>` is an info-style browser over Markdown docs in `src/worklog/help/<lang>/<topic>.md` (architecture: DESIGN §25). `en` is the source language and the per-topic fallback; other languages mirror the same topic ids. To add or edit a topic, just add/edit a `.md` file — the loader, the index, shell completion, and each command's `--help` pointer pick it up automatically.
@@ -93,13 +104,13 @@ Everything else is printed verbatim, so **lay the body out as readable plain tex
 
 Every change touching behavior follows the [Red-Green-Refactor cycle](https://brennanbrown.github.io/notes/programming/python-tdd/):
 
-1. **Red** — add a failing test in `tests/test_wl.py` first. Run it; confirm it fails for the reason you expect (not an import error). A test that never fails is not a test.
+1. **Red** — add a failing test in the matching `tests/test_<area>.py` first. Run it; confirm it fails for the reason you expect (not an import error). A test that never fails is not a test.
 2. **Green** — write the minimum production code to make that test pass. Resist the urge to also fix neighboring code; one cycle, one concern.
 3. **Refactor** — clean up. Extract helpers, remove duplication, rename. Tests still green at every step.
 
 Bug fixes follow the same path: write a regression test that reproduces the bug first, then fix.
 
-Tests don't ship without docstrings explaining what behavior they pin down (see existing `TestXDGPaths`, `TestConfig` for the style). One `Test<Command>` class per command. Cover happy path + boundaries (missing id, empty DB, illegal flag values) — the boundaries are where DESIGN drift surfaces first.
+Tests need a docstring saying what behavior they pin down. One `Test<Command>` class per command. Cover happy path + boundaries (missing id, empty DB, illegal flag values) — boundaries are where DESIGN drift surfaces first.
 
 ## DRY: there is exactly one of each
 
@@ -130,7 +141,7 @@ After saving, `make help` lists `push-gitea` alongside the built-in targets.
 
 ## Release process
 
-Version has a **single** in-repo source: `version = "X.Y.Z"` in `pyproject.toml`. `__version__` in `src/worklog/cli.py` reads it via `importlib.metadata.version("worklog")` — never edit it by hand. The git tag `vX.Y.Z` must match the pyproject version; the release workflow enforces that.
+Version has a **single** in-repo source: `version = "X.Y.Z"` in `pyproject.toml`. `__version__` in `src/worklog/cli.py` reads it via `importlib.metadata.version("pyworklog")` — never edit it by hand. The git tag `vX.Y.Z` must match the pyproject version; the release workflow enforces that.
 
 The `Release` workflow (`.github/workflows/release.yml`) is triggered by pushing a `v*` tag. It verifies tag == pyproject version, re-runs the test suite, then calls `softprops/action-gh-release@v2` to publish a GitHub Release with auto-generated notes (commits since the previous tag).
 
@@ -139,7 +150,7 @@ To cut a release:
 ```fish
 # 1. bump version in pyproject.toml only
 # 2. refresh the lock entry so uv.lock pins the new version
-uv lock --upgrade-package worklog
+uv lock --upgrade-package pyworklog
 # 3. commit + tag + push
 git commit -am "chore: bump version to X.Y.Z"
 git tag vX.Y.Z
@@ -153,5 +164,5 @@ The workflow fails the release if any of the three version anchors disagree, so
 
 - Branch from `main`. PRs target `main`.
 - Each PR moves the test count up: a refactor adds no tests but keeps coverage ≥95%; a feature/fix adds the test that exercises it.
-- Run `make test` locally before pushing. CI runs the same parallel pytest + 95% gate across ubuntu + macos × Python 3.11/3.12/3.13.
-- DESIGN.md / AGENTS.md drift is the most common review block — when in doubt, update them in the same PR.
+- Run `make test` locally before pushing. CI runs the same parallel pytest + 95% gate across ubuntu + macos × Python 3.9–3.14.
+- Doc/completion/help/changelog drift is the most common review block — run the "Keep every surface in sync" checklist above before pushing.