taskledger 0.1.2__tar.gz → 0.3.0__tar.gz

{taskledger-0.1.2 → taskledger-0.3.0}/.codecrate.toml

@@ -6,7 +6,7 @@ respect_gitignore = true
 # exclude = ["*/.venv/*", "integration_tests", "examples", "docs"]
 gitignore_allow = ["taskledger/_version.py"]
 exclude = ["*/.venv/*", "integration_tests", "todo.md"]
-include = ["**/*.py", "**/*.toml", "**/*.rst", "**/*.md", "**/*.typed"]
+include = ["**/*.py", "**/*.toml", "**/*.rst", "**/*.md", "**/*.typed", "**/*.js", "**/*.css"]
 split_max_chars = 0
 manifest = false
 layout = "full"

taskledger-0.3.0/.github/workflows/pre-commit.yml

@@ -0,0 +1,31 @@
+name: pre-commit
+
+on:
+  pull_request:
+  push:
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install Python tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install "ruff==0.15.12"
+
+      - name: Install Node tools
+        run: |
+          npm install -g prettier@2.7.1 @prettier/plugin-xml@2.2.0 eslint
+
+      - uses: pre-commit/action@v3.0.1

{taskledger-0.1.2 → taskledger-0.3.0}/.pre-commit-config.yaml

@@ -17,14 +17,19 @@ exclude: |
   (LICENSE.*|COPYING.*)|
 default_language_version:
   python: python3
-  node: "16.17.0"
 repos:
-  - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.12
+  - repo: local
     hooks:
-      - id: ruff
-        args: [--fix, --exit-non-zero-on-fix, --config=.ruff.toml]
+      - id: ruff-check
+        name: ruff check
+        entry: ruff check --fix --exit-non-zero-on-fix --config=.ruff.toml --force-exclude
+        language: system
+        types_or: [python, pyi]
       - id: ruff-format
+        name: ruff format
+        entry: ruff format --force-exclude
+        language: system
+        types_or: [python, pyi]
   - repo: https://github.com/asottile/pyupgrade
     rev: v3.21.2
     hooks:
@@ -59,11 +64,3 @@ repos:
         args:
           - --plugin=@prettier/plugin-xml
         files: \.(css|htm|html|js|json|jsx|less|md|scss|toml|ts|xml|yaml|yml)$
-  - repo: https://github.com/pre-commit/mirrors-eslint
-    rev: v10.2.1
-    hooks:
-      - id: eslint
-        verbose: true
-        args:
-          - --color
-          - --fix

taskledger-0.3.0/.taskledger.toml

@@ -0,0 +1,30 @@
+# Project-local taskledger configuration.
+# This file lives in the source project root.
+config_version = 2
+taskledger_dir = '.taskledger'
+
+# Stable project identity. Commit this with your source tree.
+project_uuid = "081c7c05-2d10-42b7-9b37-3d814c2f400a"
+
+# Taskledger branch-scoped state. This block is intentionally safe to commit.
+ledger_ref = "main"
+ledger_parent_ref = ""
+ledger_next_task_number = 81
+ledger_branch_guard = "off"
+
+[prompt_profiles.planning]
+profile = "balanced"
+question_policy = "ask_when_missing"
+max_required_questions = 5
+min_acceptance_criteria = 1
+todo_granularity = "implementation_steps"
+require_files = true
+require_test_commands = true
+require_expected_outputs = true
+require_validation_hints = true
+plan_body_detail = "normal"
+required_question_topics = []
+extra_guidance = ""
+
+[agent_logging]
+enabled = true

{taskledger-0.1.2 → taskledger-0.3.0}/API.md

@@ -53,11 +53,15 @@ from taskledger.errors import (
 - `project_doctor`
 - `project_export`
 - `project_import`
+- `project_export_archive`
+- `project_import_archive`
 - `project_snapshot`
+- `project_tree`
 
 ### `taskledger.api.tasks`
 
 - `create_task`
+- `record_completed_task`
 - `show_active_task`
 - `activate_task`
 - `deactivate_task`
@@ -69,7 +73,10 @@ from taskledger.errors import (
 - `cancel_task`
 - `uncancel_task`
 - `close_task`
+- `archive_task`
+- `unarchive_task`
 - `create_follow_up_task`
+- `list_archived_task_summaries`
 - `add_requirement`
 - `remove_requirement`
 - `waive_requirement`
@@ -82,11 +89,14 @@ from taskledger.errors import (
 - `todo_status`
 - `next_todo`
 - `task_dossier`
+- `render_task_report`
+- `TaskReportOptions`
 - `next_action`
 - `can_perform`
 - `reindex`
 - `repair_task_record`
 - `repair_orphaned_planning_run`
+- `repair_planning_command_changes`
 
 ### `taskledger.api.plans`
 
@@ -94,17 +104,31 @@ from taskledger.errors import (
 - `propose_plan`
 - `plan_template`
 - `upsert_plan`
+- `export_plan`
+- `amend_plan`
 - `regenerate_plan_from_answers`
 - `materialize_plan_todos`
 - `list_plan_versions`
 - `show_plan`
 - `diff_plan`
 - `lint_plan`
+- `plan_guidance`
 - `approve_plan`
 - `reject_plan`
 - `revise_plan`
 - `run_planning_command`
 
+Planning guidance API example:
+
+```python
+from pathlib import Path
+
+from taskledger.api.plans import plan_guidance
+
+payload = plan_guidance(Path.cwd(), "task-0001")
+# payload includes: kind, task_id, has_project_guidance, guidance, profile, question_policy
+```
+
 ### `taskledger.api.questions`
 
 - `add_question`

{taskledger-0.1.2 → taskledger-0.3.0}/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Changelog
 
+## v0.2.0 - 2026-05-03
+
+### Added
+
+- Added `taskledger task record` for creating done tasks that represent manually completed work, with change records, evidence, and implementation summaries. Does not acquire locks or activate the task. Recorded tasks are included in release changelogs.
+- Added branch-scoped ledger state with `taskledger ledger` command group (`status`, `list`, `fork`, `switch`, `adopt`, `doctor`). Each git branch can maintain its own isolated task ledger, with `adopt` for copying branch-local task history into the current ledger.
+- Added `taskledger tree` command to render ledger and task structure with follow-up nesting, subtree filtering, release boundaries, and per-ledger release counts in both human and JSON output.
+- Added compressed export/import with a project UUID guard to prevent importing archives into the wrong project, plus archive member-count and manifest/payload size limits for safety.
+- Added `taskledger status --check` to run doctor diagnostics alongside status, keeping the default `status` fast by avoiding full record parsing.
+- Added structured diagnostics to `taskledger doctor` JSON output with task IDs, change IDs, run IDs, types, relative paths, and actionable repair hints.
+- Added explicit `repair` command for existing planning-command change records that were incorrectly persisted as code changes.
+- Added a top-level `Makefile` with a `release-check` automation target (compile, test, lint, type-check, build, twine check).
+- Added AST-based service boundary guardrail tests with explicit whitelists and documented rationale.
+
+### Changed
+
+- Split core plan/implement/validate service entrypoints from `tasks.py` into dedicated `planning_flow.py`, `implementation_flow.py`, and `validation_flow.py` modules. `tasks.py` remains a compatibility facade.
+- Decoupled validation service from private task helpers by extracting shared query logic into a new `task_queries` module.
+- Planning commands are now persisted as planning-run evidence (worklog/artifacts/event) instead of creating `CodeChangeRecord` entries.
+- Replaced chmod-dependent storage write failure test with a deterministic synthetic `OSError` monkeypatch.
+- Sped up test suite with test-only fast fsync bypass, command-runner seam, and reduced subprocess-heavy setup.
+
+### Fixed
+
+- Fixed import replace so it no longer restores stale locks across machines.
+
+### Documentation
+
+- Documented branch-scoped ledger workflow, `task record` usage and warnings, `tree` command, and `make release-check` across README, RST docs, API docs, and the taskledger skill.
+- Added `docs/service_boundary_whitelist.md` documenting temporary module/function boundary whitelist entries and split targets.
+
+### Quality
+
+- Expanded regression coverage for branch-scoped ledgers, task record, tree command, compressed export/import, doctor diagnostics, status performance, service boundaries, and planning command persistence. Repo-wide pytest, ruff, and mypy passed.
+
+## v0.1.2 - 2026-04-30
+
+### Fixed
+
+- Fixed orphaned planning run lifecycle recovery so plan regeneration safely finishes the latest orphaned planning run with audit evidence, plan approval rejects tasks with any running run, and `implement start` reports structured conflict details including run id, run type, lock match status, and suggested diagnostic command.
+- Aligned `next-action` and `can implement` so they never recommend `implement start` when a running run or run/lock mismatch blocks implementation.
+- Expanded `taskledger doctor` and `taskledger doctor locks` to report run/lock mismatches with specific repair guidance.
+
+### Added
+
+- Added `taskledger repair run` for guarded, reasoned, audited repair of orphaned running planning runs.
+
+### Documentation
+
+- Updated taskledger skill, command contract, and API docs with running-run conflict protocol and `repair run` usage.
+
+### Quality
+
+- Expanded regression coverage for plan regeneration recovery, approval guards, next-action alignment, doctor diagnostics, and repair lifecycle. Targeted pytest, ruff, format, and mypy passed.
+
 ## v0.1.1 - 2026-04-29
 
 ### Added

taskledger-0.3.0/Makefile

@@ -0,0 +1,9 @@
+.PHONY: release-check
+
+release-check:
+	python3 -m compileall -q taskledger tests
+	PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python3 -m pytest -q
+	python3 -m ruff check --config=.ruff.toml .
+	python3 -m mypy taskledger
+	python3 -m build
+	python3 -m twine check dist/*

{taskledger-0.1.2/taskledger.egg-info → taskledger-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taskledger
-Version: 0.1.2
+Version: 0.3.0
 Summary: Durable project-state storage and CLI for coding workflows
 Author: Taskledger Contributors
 Maintainer: Holger Nahrstaedt
@@ -33,6 +33,7 @@ Provides-Extra: dev
 Requires-Dist: build; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-xdist; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 Requires-Dist: types-PyYAML; extra == "dev"
@@ -81,6 +82,53 @@ The supported command surface is organized as:
 
 - `init`, `status`, `export`, `import`, `snapshot`, `release`
 
+### Which read command to use
+
+| Need                       | Command                                             |
+| -------------------------- | --------------------------------------------------- |
+| Next step                  | `next-action`                                       |
+| Next implementation item   | `todo next`                                         |
+| Active task summary        | `task show`                                         |
+| Specific task summary      | `task show TASK_REF` or `task show --task TASK_REF` |
+| Project/ledger overview    | `status`, `tree`                                    |
+| Human dashboard            | `serve`                                             |
+| Reviewable markdown report | `task report`                                       |
+| Fresh worker context       | `context` or durable `handoff show`                 |
+| Command audit              | `task transcript`                                   |
+
+## Planning guidance profiles
+
+Taskledger supports project-local advisory planning guidance under
+`[prompt_profiles.planning]` in the active project config file (`taskledger.toml`
+or `.taskledger.toml` when legacy config is still present).
+
+```toml
+[prompt_profiles.planning]
+profile = "strict"
+question_policy = "always_before_plan"
+max_required_questions = 3
+min_acceptance_criteria = 2
+todo_granularity = "atomic"
+require_files = true
+require_test_commands = true
+require_expected_outputs = true
+require_validation_hints = true
+plan_body_detail = "detailed"
+required_question_topics = ["scope", "compatibility", "test strategy"]
+extra_guidance = "Every plan must mention docs, tests, and rollback or repair behavior."
+```
+
+Inspect guidance for the active task:
+
+```bash
+taskledger plan guidance
+taskledger --json plan guidance
+```
+
+This guidance is advisory and cannot override lifecycle gates, user approval,
+validation requirements, lock rules, or higher-priority harness instructions.
+See `docs/usage.rst` for the full key reference and workflow details.
+
 ## Install
 
 ```bash
@@ -136,14 +184,36 @@ taskledger validate check --criterion ac-0001 --status pass --evidence "pytest -
 taskledger validate finish --result passed --summary "Validated the rewrite."
 ```
 
-If validation finds an implementation bug, keep the accepted plan and restart
-implementation explicitly:
+To revise a proposed plan, re-enter planning and edit an exported workspace
+copy. Never edit `.taskledger/` files directly:
 
 ```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 plan revise
+taskledger plan export --version latest --file ./plan.md
+# edit ./plan.md
+taskledger plan upsert --file ./plan.md
+```
+
+For manually completed work (e.g., manual testing, operations tasks, or work
+completed outside the task-first lifecycle), use `task record` to create a
+done task directly without acquiring lifecycle locks. **Note**: `task record`
+does not replace the normal task lifecycle; it is for recording work already
+completed, not as a shortcut for active task management.
+
+```bash
+taskledger task record "Deploy to production" --summary "Deployed v0.4.1 to prod" --change "infra/deploy.sh:run:Updated prod config" --evidence "Monitoring shows no errors"
+taskledger task record "Manual API testing" --summary "Tested new endpoints" --allow-empty-record --reason "Exploratory testing, no formal changes tracked"
+```
+
+Archive is a visibility operation: it hides tasks from default list/tree/dashboard
+views without deleting history. Task ids stay monotonic and are never reused.
+Slugs can be reused after archive.
+
+```bash
+taskledger task archive task-0030 --reason "Hide historical task"
+taskledger task list --archived
+taskledger task unarchive task-0030 --reason "Need to continue work" --slug task-0030-reopened
+taskledger tree --include-archived
 ```
 
 If validation finds an implementation bug, keep the accepted plan and restart
@@ -270,21 +340,47 @@ fresh-context transfer.
 ## Storage layout
 
 `taskledger` keeps project-local configuration in the workspace root and durable
-records under the configured storage root:
+records under the configured storage root. The checked-in `.taskledger.toml`
+stores only a branch-scoped ledger pointer and next task number. Operational task
+state remains ignored under `.taskledger/ledgers/<ledger_ref>/`:
 
 ```text
-taskledger.toml
+.taskledger.toml
 .taskledger/
-  intros/
-  releases/
-  tasks/
-  events/
-  indexes/   # optional derived caches and registries
+  storage.yaml
+  ledgers/
+    main/
+      intros/
+      releases/
+      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.
+Markdown files are canonical. Task, plan, and run listings scan only the current
+ledger by default. JSON files under the current ledger's `indexes/` directory are
+optional derived caches or registries and are not required for task correctness.
+
+### Branch-scoped ledgers
+
+`.taskledger/` stays ignored and local. `.taskledger.toml` is safe to commit and
+contains the current `ledger_ref`, optional parent ref, and the next logical task
+number for the checked-out source branch.
+
+When starting long-lived branch-local work, fork the ledger pointer after creating
+the Git branch:
+
+```bash
+git checkout -b feature-a
+taskledger ledger fork feature-a
+git add .taskledger.toml
+```
+
+Returning to a branch whose `.taskledger.toml` points back to `main` hides the
+feature branch's active task and task list. Two ledgers may both contain a logical
+`task-0030`; this is expected because task IDs are scoped by `ledger_ref`. Use
+`taskledger ledger adopt --from REF TASK_REF` when branch-local task history
+should be copied into the current ledger.
 
 You can also point `taskledger.toml` at an external storage root:
 
@@ -312,6 +408,7 @@ Use `--json` for machine-readable payloads:
 taskledger --json status --full
 taskledger --json task active
 taskledger --json task show
+taskledger --json task show task-0001
 taskledger --json context --for validation --format json
 ```
 
@@ -352,6 +449,7 @@ taskledger context --for planning --format markdown
 taskledger context --for implementation --format markdown
 taskledger context --for validation --format json
 taskledger task dossier --format markdown
+taskledger task report --task task-0030 -o task30.md
 taskledger handoff create --mode implementation --intended-actor agent --intended-harness codex
 taskledger handoff claim handoff-0001
 taskledger handoff close handoff-0001 --reason "Implementation started."
@@ -412,11 +510,39 @@ for task-first handoff guidance.
 ## Export, import, and snapshots
 
 ```bash
-taskledger --json export
-taskledger import ./taskledger-export.json --replace
+taskledger init --project-name "Taskledger"
+taskledger export
+taskledger import ./taskledger-transfer.tar.gz --dry-run
+taskledger import ./taskledger-transfer.tar.gz --replace
 taskledger snapshot ./artifacts
 ```
 
+Default export filenames use this policy:
+
+```text
+taskledger-export-{project_slug}-{ledger_ref}-{timestamp}.tar.gz
+```
+
+`project_slug` is derived from `project_name` in `taskledger.toml`. If
+`project_name` is missing, taskledger falls back to the workspace directory name.
+Import safety still relies on `project_uuid`, not the name/slug.
+
+`--include-bodies` and `--include-run-artifacts` now change archive content:
+
+- `--no-include-bodies` strips record body text (`body` / `context_body`) from exported payloads.
+- `--include-run-artifacts` embeds task and agent-log artifact files under `artifacts/` in the archive.
+
+Cross-machine imports preserve durable task/run data, but imported runtime locks
+are quarantined by default. After importing an in-progress implementation,
+run:
+
+```bash
+taskledger next-action
+taskledger implement resume --reason "Continue imported implementation."
+```
+
+Use `--lock-policy keep` only for diagnostic full-fidelity lock restoration.
+
 ## Skill packaging
 
 Agent workflows work best when the `taskledger` skill is installed in the
@@ -436,6 +562,15 @@ Keep this skill outside the Python package. No additional
 ## Development
 
 ```bash
-pytest -q
+python -m pytest -m "not slow"
+python -m pytest -m "not slow" -n auto
+python -m pytest -n auto
+python -m pytest
 ruff check .
 ```
+
+Full release-readiness sweep:
+
+```bash
+make release-check
+```