taskledger 0.1.0__py3-none-any.whl

taskledger/timeutils.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+
+def utc_now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()

taskledger-0.1.0.dist-info/METADATA

@@ -0,0 +1,411 @@
+Metadata-Version: 2.4
+Name: taskledger
+Version: 0.1.0
+Summary: Durable project-state storage and CLI for coding workflows
+Author: Taskledger Contributors
+Maintainer: Holger Nahrstaedt
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/holgern/taskledger
+Project-URL: Repository, https://github.com/holgern/taskledger
+Project-URL: Issues, https://github.com/holgern/taskledger/issues
+Project-URL: Changelog, https://github.com/holgern/taskledger/releases
+Keywords: cli,durable-state,project-state,developer-tools,workflows
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer
+Requires-Dist: PyYAML
+Requires-Dist: tomli; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Provides-Extra: rich
+Requires-Dist: rich; extra == "rich"
+Dynamic: license-file
+
+# taskledger
+
+`taskledger` is a task-first durable state layer for staged coding work. It keeps
+project-local configuration in `taskledger.toml` at the workspace root and stores
+plans, approval state, implementation logs, validation results, locks, and
+fresh-context handoffs under a configurable `taskledger_dir` (default:
+`.taskledger/` beside that config file).
+
+## Canonical workflow
+
+```text
+task -> plan -> approval -> implement -> validate -> done
+```
+
+The supported command surface is organized as:
+
+**Core workflow:**
+
+- `task`, `plan`, `question`, `implement`, `validate`, `todo`
+
+**Context and decision-making:**
+
+- `intro`, `file`, `link`, `require`, `handoff`
+
+**Operations:**
+
+- `context`, `next-action`, `can`, `search`, `grep`, `symbols`, `deps`, `actor`, `view`, `serve`
+
+**Repair and inspection:**
+
+- `lock`, `doctor`, `repair`, `reindex`
+
+**Project lifecycle:**
+
+- `init`, `status`, `export`, `import`, `snapshot`
+
+## Install
+
+```bash
+python -m pip install -e .
+python -m pip install -e ".[dev]"
+```
+
+## Quick start
+
+Initialize durable state in the current workspace:
+
+```bash
+taskledger init
+# or keep storage outside the source repo
+taskledger init --taskledger-dir /mnt/cloud/taskledger/my-repo
+# or point at another workspace explicitly
+taskledger --root /path/to/repo init
+```
+
+`init` writes `taskledger.toml` in the workspace root. By default that config
+points at `.taskledger/`, but `--taskledger-dir` can move durable state to an
+external directory without nesting another `.taskledger` inside it.
+
+Create and activate a task, ask required planning questions, regenerate the
+plan from answers, approve it, implement todos with evidence, and validate it:
+
+```bash
+taskledger task create "Rewrite V2" --slug rewrite-v2 --description "Migrate to the task-first design."
+taskledger task activate rewrite-v2 --reason "Start planning"
+taskledger plan start
+taskledger question add --text "Should exports include the new state?" --required-for-plan
+taskledger question answer-many --text "q-0001: Yes."
+taskledger question status
+taskledger plan upsert --from-answers --file ./plan.md
+taskledger plan lint --version 1
+taskledger plan accept --version 1 --note "Ready."
+
+taskledger next-action
+taskledger --json next-action
+
+taskledger context --for implementation --format markdown
+taskledger implement start
+taskledger implement checklist
+taskledger implement change --path taskledger/storage/task_store.py --kind edit --summary "Normalized v2 markdown storage."
+taskledger todo done todo-0001 --evidence "Updated taskledger/storage/task_store.py"
+taskledger implement finish --summary "Implemented the approved plan."
+
+taskledger context --for validation --format markdown
+taskledger validate start
+taskledger validate status
+taskledger validate check --criterion ac-0001 --status pass --evidence "pytest -q tests/test_taskledger_v2_cli.py"
+taskledger validate finish --result passed --summary "Validated the rewrite."
+```
+
+If validation finds an implementation bug, keep the accepted plan and restart
+implementation explicitly:
+
+```bash
+taskledger validate finish --result failed --summary "Parser edge case still fails."
+taskledger next-action
+taskledger context --for implementation --format markdown
+taskledger implement restart --summary "Fix failed validation findings."
+```
+
+If validation finds an implementation bug, keep the accepted plan and restart
+implementation explicitly:
+
+```bash
+taskledger validate finish --result failed --summary "Parser edge case still fails."
+taskledger next-action
+taskledger context --for implementation --format markdown
+taskledger implement restart --summary "Fix failed validation findings."
+```
+
+`taskledger next-action` is the preferred fresh-context entrypoint. It stays
+read-only and points at the next concrete question, todo, criterion, or repair
+step.
+
+Human output example:
+
+```text
+todo-work: Implementation is in progress; 1 todos remain.
+Next todo: todo-0001 -- Update next-action JSON payload.
+Command: taskledger todo show todo-0001
+Mark todo done after evidence exists: taskledger todo done todo-0001 --evidence "..."
+Progress: 0/1 todos done
+```
+
+JSON result example:
+
+```json
+{
+  "kind": "task_next_action",
+  "action": "todo-work",
+  "next_command": "taskledger todo show todo-0001",
+  "next_item": {
+    "kind": "todo",
+    "id": "todo-0001",
+    "text": "Update next-action JSON payload.",
+    "validation_hint": "Run: pytest tests/test_todo_implementation_gate.py -q; Expected: pass",
+    "done_command_hint": "taskledger todo done todo-0001 --evidence \"...\""
+  },
+  "commands": [
+    {
+      "kind": "inspect",
+      "label": "Show next todo",
+      "command": "taskledger todo show todo-0001",
+      "primary": true
+    },
+    {
+      "kind": "complete",
+      "label": "Mark todo done after evidence exists",
+      "command": "taskledger todo done todo-0001 --evidence \"...\"",
+      "primary": false
+    }
+  ],
+  "progress": {
+    "todos": {
+      "total": 1,
+      "done": 0,
+      "open": 1,
+      "open_ids": ["todo-0001"]
+    }
+  },
+  "blocking": []
+}
+```
+
+## Compact implementation loop
+
+For routine same-session implementation, prefer `next-action` and the single next
+todo over broad generated context:
+
+```bash
+taskledger --json next-action
+taskledger --json todo next
+taskledger todo show todo-0003
+# implement only that todo
+pytest tests/...
+taskledger todo done todo-0003 --evidence "pytest tests/... passed"
+taskledger --json next-action
+```
+
+Rules for agents:
+
+- Prefer `next-action` and `todo next` over generated context during normal work.
+- Use the todo `validation_hint` before marking a todo done.
+- Record concise evidence with `todo done`.
+- Do not create handoffs or context bundles unless the user asked to switch harness or session.
+
+## Human monitoring UI
+
+`taskledger serve` starts a read-only local dashboard for humans monitoring task
+state. It now emphasizes the active task, next action, progress, blockers, and
+compact task browsing while staying local-only, read-only, and dependency-free.
+The MVP still binds to localhost only, refreshes with read-only JSON polling,
+and exposes no browser mutation endpoints.
+
+```bash
+taskledger serve
+taskledger serve --open
+taskledger serve --task rewrite-v2 --refresh-ms 2000
+```
+
+Agents should keep using `taskledger next-action`, `taskledger todo next`, and
+`--json` commands as the canonical automation interface for routine same-session
+work. Reach for `context` or handoffs when the task actually needs a broader
+fresh-context transfer.
+
+## Storage layout
+
+`taskledger` keeps project-local configuration in the workspace root and durable
+records under the configured storage root:
+
+```text
+taskledger.toml
+.taskledger/
+  intros/
+  tasks/
+  events/
+  indexes/   # optional derived caches and registries
+```
+
+Markdown files are canonical. Task, plan, and run listings scan those records
+directly. JSON files under `.taskledger/indexes/` are optional derived caches or
+registries and are not required for task correctness.
+
+You can also point `taskledger.toml` at an external storage root:
+
+```bash
+taskledger init --taskledger-dir /mnt/cloud/taskledger/project-a
+```
+
+```text
+/home/me/src/project-a/taskledger.toml
+/mnt/cloud/taskledger/project-a/storage.yaml
+/mnt/cloud/taskledger/project-a/tasks/
+/mnt/cloud/taskledger/project-a/events/
+/mnt/cloud/taskledger/project-a/indexes/
+```
+
+Use one `taskledger_dir` per source project. Do not share one storage directory
+across unrelated repositories.
+
+## JSON output
+
+Use `--json` for machine-readable payloads:
+
+```bash
+taskledger --json status --full
+taskledger --json task active
+taskledger --json task show
+taskledger --json context --for validation --format json
+```
+
+Example status payload:
+
+```json
+{
+  "ok": true,
+  "command": "status",
+  "result": {
+    "kind": "taskledger_status",
+    "workspace_root": "/home/me/src/project-a",
+    "config_path": "/home/me/src/project-a/taskledger.toml",
+    "taskledger_dir": "/home/me/src/project-a/.taskledger",
+    "project_dir": "/home/me/src/project-a/.taskledger",
+    "counts": {
+      "tasks": 1,
+      "introductions": 0,
+      "plans": 1,
+      "questions": 1,
+      "runs": 2,
+      "changes": 1,
+      "locks": 0
+    },
+    "active_task": null,
+    "healthy": true
+  },
+  "events": []
+}
+```
+
+## Handoff-driven work
+
+Fresh-context handoff is a primary feature:
+
+```bash
+taskledger context --for planning --format markdown
+taskledger context --for implementation --format markdown
+taskledger context --for validation --format json
+taskledger task dossier --format markdown
+taskledger handoff create --mode implementation --intended-actor agent --intended-harness codex
+taskledger handoff claim handoff-0001
+taskledger handoff close handoff-0001 --reason "Implementation started."
+```
+
+## Fresh-worker contexts
+
+Use focused contexts when handing one todo or one review run to a fresh worker:
+
+```bash
+taskledger context --for implementer --todo todo-0003
+taskledger context --for spec-reviewer --run run-0008
+taskledger context --for code-reviewer --run run-0008
+taskledger handoff create --mode implementation --todo todo-0003
+taskledger handoff show handoff-0001 --format markdown
+```
+
+`handoff create` now stores the generated Markdown context snapshot in the handoff
+record so another harness can continue from the exact same input.
+
+## Multi-Actor Handoff Protocol
+
+The handoff protocol enables safe work transitions between human and agent actors across different harnesses:
+
+### Features
+
+- **Actor Identity**: Track WHO performs each stage (human, agent, system)
+- **Harness Tracking**: Record FROM WHERE each stage ran (manual, Codex, OpenCode, etc.)
+- **Handoff Records**: Explicitly hand off work with context and intent
+- **Claim Protocol**: New actors claim handoffs before starting work
+- **Lock Management**: Transfer or release locks during handoffs
+- **Event Trail**: Full audit trail recording all state changes
+- **Durable Records**: Markdown-first storage with YAML metadata
+
+### Quick Start
+
+```bash
+# See your current identity
+$ taskledger actor whoami
+
+# Create a handoff
+$ taskledger handoff create --task task-0001 --mode implementation --todo todo-0003
+
+# Claim it
+$ taskledger handoff claim handoff-0001 --task task-0001
+
+# Show details
+$ taskledger handoff show handoff-0001 --task task-0001 --format text
+
+# Close when done
+$ taskledger handoff close handoff-0001 --task task-0001 --reason "Continued."
+```
+
+See [docs/usage.rst](docs/usage.rst) and
+[skills/taskledger/SKILL.md](skills/taskledger/SKILL.md)
+for task-first handoff guidance.
+
+## Export, import, and snapshots
+
+```bash
+taskledger --json export
+taskledger import ./taskledger-export.json --replace
+taskledger snapshot ./artifacts
+```
+
+## Skill packaging
+
+The canonical skill file lives at:
+
+```text
+skills/taskledger/SKILL.md
+```
+
+No additional `skills/taskledger/examples/` directory is required.
+
+## Development
+
+```bash
+pytest -q
+ruff check .
+```

taskledger-0.1.0.dist-info/RECORD

@@ -0,0 +1,67 @@
+taskledger/__init__.py,sha256=mz00ypklNGoOef9Sh6Iak2wpVytIbeU2xoYAjGSONpI,107
+taskledger/__main__.py,sha256=uc72I0AlS0BgV48SQJCJMNTbqFjeDGKt7hISsQy7VIg,124
+taskledger/_version.py,sha256=n_5vdJsPNu7wZ57LGuRL585uvll-hiuvZUBWzdG0RQU,520
+taskledger/cli.py,sha256=6C2ZpEfO4-U7MVbRiocHZ9Y3uVLh0uStGlU1NnrtWsg,18115
+taskledger/cli_actor.py,sha256=I_0nDrNrb6f78H10FKduMb0YZTLCdqjTQsznAPyTw4w,5532
+taskledger/cli_common.py,sha256=RtuLsgBa1fQoJrFEd7LSQmi28xnlXtmCCLddzeB1jBM,20077
+taskledger/cli_implement.py,sha256=GrVHzeEOzevyGSCytWG8VNuAyMagRugphInTEMXwgqo,14433
+taskledger/cli_migrate.py,sha256=uv-1Upwy35oov9zG2eq1QeK0nF8vUztmy1UShvAYkHE,10571
+taskledger/cli_misc.py,sha256=ueEejA19O_59q3kfIe7K3H8TaL5-3BY2LxCz5bubZnY,33704
+taskledger/cli_plan.py,sha256=75Sm8CdBwFbNl52Gn3oklp5FUPNUyLUeQ-dYVS5X_SY,17388
+taskledger/cli_question.py,sha256=2C1fkcoAD7ckf2tAmWLUH_wWpwQ037uzz_aNPhwHM-E,11324
+taskledger/cli_task.py,sha256=sxU7dR4o6vKFnzRejjwYB3SzCpEJplunijAnu3Gixfg,9584
+taskledger/cli_validate.py,sha256=0f-yG2d3yEbTAAcXokuKNjiM8mipchxpPRenreqHkCY,10104
+taskledger/command_inventory.py,sha256=oYMrZzcsAtT16JSqOFBM_glCcAmncZYY9X9ZMxBL1oI,6940
+taskledger/errors.py,sha256=mGAF42EneOERNzW9kxoNl46pr6BqZH2GIWAYZEoZZsI,4763
+taskledger/exchange.py,sha256=1XMGU9D1lMm5gMb-Tk4JwxHgVketib2kKDX4Ew0USiY,12179
+taskledger/ids.py,sha256=etcKDswR_4gJ15aRLJ81Oe37f6eh0Dd8gYYayYW6AdI,573
+taskledger/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+taskledger/search.py,sha256=wvOpdRLtaYQ90t198LVQvP5wgWLeD56Nt5Echau4ICU,10741
+taskledger/timeutils.py,sha256=Y6ilKrtygIPJApUe-q2sNu0Fckcp9Q-Y0QWi_TH-IhM,154
+taskledger/api/__init__.py,sha256=6P28iq9eTAfMc5iZMOaDpvooOZ50A8dPKk1ok9q2cfo,188
+taskledger/api/handoff.py,sha256=nQtQ8g3kONbOpnK12UphBaO0ymtoS5xtJFGRCOK8QkA,7405
+taskledger/api/introductions.py,sha256=q6mI-UmyxxemGeqTNfAfTdLIJDShCQYvFl5h9LJqemU,281
+taskledger/api/locks.py,sha256=onGwS2F179tL84aqDVmy4uOehrOFIbvn0ip6dApGcBs,206
+taskledger/api/plans.py,sha256=tkCXqRdoLONenyEc53UWGfwEC22SakI-HXilfnGhJjY,648
+taskledger/api/project.py,sha256=F5D6H29WaRs17xybGD036hHjFr76ytzbeu1Br4J1UPk,5868
+taskledger/api/questions.py,sha256=pA2zDwKxwo_Attcb5x8Q-4NGcI2sNiN1DSr3T5maWE4,406
+taskledger/api/search.py,sha256=KeuKiAv8aQ47DZUeLc2s4EzSYbwuU_t0xeym2NfD9fQ,1834
+taskledger/api/task_runs.py,sha256=wR5JLT_QiWG5H4gmokU7RSQmZZZkBhg8J93IJpHYFDI,934
+taskledger/api/tasks.py,sha256=cyG0Q0vVcraEKOJC1G6bLze8QZyM6RHPaREQrBQIXIs,1175
+taskledger/domain/__init__.py,sha256=fjiP5OfsfbA52cNphQPkXORszOTJa7g86h51DoF3U-w,116
+taskledger/domain/models.py,sha256=dIDII19b-KZnckqIs8EvGIWFSwp0q6ZpofUqVx2RjCg,68067
+taskledger/domain/policies.py,sha256=QSjR4UcvwZskl5ixn4IH94KEPFHTqvX-244LJZqYuY0,16034
+taskledger/domain/states.py,sha256=9oBazNbV7gmnfk08Pj_tfgOhoL0S6Jd-jvVBVIfv2dY,10221
+taskledger/services/__init__.py,sha256=ZdqtjyWlxYxZ90QKbvPwtdwIveDeulhCZIT1yyBP1Mw,42
+taskledger/services/actors.py,sha256=-vsaBvR9v3O5T5N0qe6gHZpUa8xMp9vCCLvQCPgD9sQ,7349
+taskledger/services/dashboard.py,sha256=VXaOqYMqq8qut7N7O1Hmwn6mlNIyca339iu_RsXPxZE,9762
+taskledger/services/doctor.py,sha256=iknb7wiVW04ucYprkzwJX3wkrQ_FtxiH2_xAOCUZPro,16720
+taskledger/services/handoff.py,sha256=IM6jGqFmdcsuAWgAtewOMTTCtqNIzR0Byh7R0AJRx-A,35626
+taskledger/services/handoff_lifecycle.py,sha256=PH9sTIdfw-yuKPO0tlc0zGxzDrh6S3vlGLmeRUJtt6A,5010
+taskledger/services/navigation.py,sha256=2EOBPtd0HH6KRCrW6MPet6ujdMr3gQOCYxj4-UdyIaE,32565
+taskledger/services/phase5_lock_transfer.py,sha256=boHl4BTgL77TOKKdWvvXicdx3HPOzcIII5hMvyPkQA8,2895
+taskledger/services/plan_lint.py,sha256=wrpSh4aqz337btWu3J_d44tn2NXxpGT6E9VRYDAH5uI,12188
+taskledger/services/serve_read_model.py,sha256=045_FOu0_--UthERyGeNuXio75sPJrWC67F5Xevov-E,30222
+taskledger/services/tasks.py,sha256=FUsAbvrG74x-kkuHJPISv6NlxKXnKFfqjXu0yJLEAro,133761
+taskledger/services/validation.py,sha256=rTORiah-cWjgu53c0vujYzHIGR9AYLQxCSfl9XeL0EU,7879
+taskledger/services/web_dashboard.py,sha256=VrpAujIrEbiP791vBtQSUc79Kxm7twqJs4Y8crMLCOw,74055
+taskledger/storage/__init__.py,sha256=K9PgqJ9RfkbPms28y8A0VzSMGwRpoChnRckTETxAvg8,995
+taskledger/storage/atomic.py,sha256=wbjz9x_XUMbrZfqHMV02ROVpy8yZDYEHxJeZrtqmhYM,1791
+taskledger/storage/common.py,sha256=XnKnF67O5ZxF8BHodxNJEaZC8XtOe9lNAJFBYdzPbhg,2666
+taskledger/storage/events.py,sha256=PMwHop3_Dq3noxNe7jAdq7j6r9B3fw1X0mOU5KWyvSQ,3283
+taskledger/storage/frontmatter.py,sha256=MmaoFsUxYiobWV74-aF0BUt4qBPKc1T4X7eRpon_cjw,1910
+taskledger/storage/indexes.py,sha256=PF1L_LySVqjMmQk21pv51yA2dGKv3Na5wtTN_addpxI,1226
+taskledger/storage/init.py,sha256=EY1M6CI6qHvcbyhUkf2oD1H383XxkrUBuGsPae-yGAM,6253
+taskledger/storage/locks.py,sha256=bxUpWG_RFqgH9HERv0YRKkQH7V4HTnQTypCs6CdFY-4,2417
+taskledger/storage/meta.py,sha256=r9UNeb8m-nRx6pEnhgrtQUHGEao5d_Uz6w616ZV1fBw,3819
+taskledger/storage/migrations.py,sha256=W8kpFtMM5fmiazNHrTCW2AuVSdWRt7rTVDQpf8fo5Fs,6252
+taskledger/storage/paths.py,sha256=Sqc4Q1n1OZaIaN2LwSo3_k12dry0TQ-v4qQDyUvzKKg,5521
+taskledger/storage/project_config.py,sha256=XKD0jxxZbaaHOSPYOQ4qLZGxvZV63I4Q8jrc1JO9_iI,15288
+taskledger/storage/repos.py,sha256=Nj5yZN-mqPplcLRKnyq0-35V2hEqc5SeitvcNxewkiU,8672
+taskledger/storage/task_store.py,sha256=AVNd8aeASE4I2OQXDTmOe_nt71eCAc8ySRxsj6xNXFs,28588
+taskledger-0.1.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+taskledger-0.1.0.dist-info/METADATA,sha256=iOZ4wJIRAKsGtGGUld6EQbJ4Z1EyK42J6fvDq3hEOg8,12542
+taskledger-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+taskledger-0.1.0.dist-info/entry_points.txt,sha256=j_uWEaPMblrudLEeVvxFEU5eBuPkJR2JeMfOOsCwOBU,55
+taskledger-0.1.0.dist-info/top_level.txt,sha256=PEC4fvOzGkYVL55VpQUETk_wPjyZsR8av89sd65NnIg,11
+taskledger-0.1.0.dist-info/RECORD,,

taskledger-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

taskledger-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+taskledger = taskledger.cli:cli_main