taskledger 0.4.0__tar.gz → 0.4.2__tar.gz

taskledger-0.4.2/.archledger/records/building_blocks/al_block_0029.md

@@ -0,0 +1,37 @@
+---
+schema_version: 2
+id: al_block_0029
+type: white_box
+title: "taskledger system"
+status: proposed
+section: building_block_view
+level: 1
+parent: null
+order: 10
+date: "2026-05-23"
+diagram: null
+quality_characteristics: []
+tags: []
+body_format: markdown
+created_at: "2026-05-23T12:30:16Z"
+updated_at: "2026-05-23T12:30:16Z"
+---
+
+## Motivation
+
+taskledger decomposes into five layers with strict downward dependency flow. This decomposition isolates I/O (storage), business rules (domain), orchestration (services), and presentation (CLI/API).
+
+## Contained building blocks
+
+1. **CLI Layer** (`al_block_0030`) — Typer commands, argument parsing, output rendering
+2. **API Layer** (`al_block_0031`) — Stable Python function wrappers
+3. **Services Layer** (`al_block_0032`) — Lifecycle orchestration, handoffs, inspection
+4. **Domain Layer** (`al_block_0033`) — Models, state machines, policies (no I/O)
+5. **Storage Layer** (`al_block_0034`) — File system persistence, atomic writes, layout
+
+## Important interfaces
+
+- CLI → Services: function calls with `workspace_root` + task references
+- Services → Domain: policy functions take `PolicyContext`, return `Decision`
+- Services → Storage: record CRUD operations via `task_store.py` functions
+- API → Services: direct function calls mirroring CLI behavior

taskledger-0.4.2/.archledger/records/building_blocks/al_block_0030.md

@@ -0,0 +1,24 @@
+---
+schema_version: 2
+id: al_block_0030
+type: black_box
+title: "CLI Layer"
+status: accepted
+section: building_block_view
+level: 1
+parent: al_block_0029
+order: 10
+date: "2026-05-23"
+interfaces: []
+location: []
+fulfilled_requirements: []
+risks: []
+tags: []
+body_format: markdown
+created_at: "2026-05-23T12:30:23Z"
+updated_at: "2026-05-23T12:30:23Z"
+---
+
+Handles command parsing via Typer, task reference resolution (`--task` option, active task default), and output rendering (human text or JSON envelope via `cli_common.py`). Registers 41 command groups from `COMMAND_METADATA`: `actor`, `can`, `commands`, `context`, `deps`, `doctor`, `export`, `file`, `grep`, `handoff`, `harness`, `implement`, `import`, `init`, `intro`, `ledger`, `link`, `lock`, `migrate`, `next-action`, `pipeline`, `plan`, `question`, `reindex`, `release`, `repair`, `report`, `require`, `review`, `search`, `serve`, `snapshot`, `status`, `storage`, `sync`, `symbols`, `task`, `todo`, `tree`, `validate`, `view`. The `review` group provides code-review record support (`review record`, `review list`, `review show`).
+
+Source refs: `taskledger/cli.py`, `taskledger/cli_common.py`, `taskledger/cli_task.py`, `taskledger/cli_plan.py`, `taskledger/cli_implement.py`, `taskledger/cli_validate.py`, `taskledger/cli_misc.py`.

taskledger-0.4.2/.archledger/records/building_blocks/al_block_0031.md

@@ -0,0 +1,22 @@
+---
+schema_version: 2
+id: al_block_0031
+type: black_box
+title: "API Layer"
+status: proposed
+section: building_block_view
+level: 1
+parent: al_block_0029
+order: 20
+date: "2026-05-23"
+interfaces: []
+location: []
+fulfilled_requirements: []
+risks: []
+tags: []
+body_format: markdown
+created_at: "2026-05-23T12:30:27Z"
+updated_at: "2026-05-23T12:30:27Z"
+---
+
+Stable Python function wrappers under `taskledger/api/` that mirror the CLI surface for programmatic use. Each module (tasks, plans, handoff, locks, etc.) exposes functions that accept workspace paths and return dictionaries matching the JSON output shape. The API layer calls Services directly.

taskledger-0.4.2/.archledger/records/building_blocks/al_block_0032.md

@@ -0,0 +1,22 @@
+---
+schema_version: 2
+id: al_block_0032
+type: black_box
+title: "Services Layer"
+status: proposed
+section: building_block_view
+level: 1
+parent: al_block_0029
+order: 30
+date: "2026-05-23"
+interfaces: []
+location: []
+fulfilled_requirements: []
+risks: []
+tags: []
+body_format: markdown
+created_at: "2026-05-23T12:30:29Z"
+updated_at: "2026-05-23T12:30:29Z"
+---
+
+Orchestrates lifecycle flows by coordinating between Domain (policies, models) and Storage (persistence). Key modules: `tasks.py` (core lifecycle operations), `planning_flow.py`, `implementation_flow.py`, `validation_flow.py`, `handoff.py` + `handoff_lifecycle.py`, `doctor.py`, `navigation.py`, `worker_pipeline.py`, `dashboard.py`. Services gather context from storage, call domain policies, and persist results.

taskledger-0.4.2/.archledger/records/building_blocks/al_block_0033.md

@@ -0,0 +1,22 @@
+---
+schema_version: 2
+id: al_block_0033
+type: black_box
+title: "Domain Layer"
+status: proposed
+section: building_block_view
+level: 1
+parent: al_block_0029
+order: 40
+date: "2026-05-23"
+interfaces: []
+location: []
+fulfilled_requirements: []
+risks: []
+tags: []
+body_format: markdown
+created_at: "2026-05-23T12:30:29Z"
+updated_at: "2026-05-23T12:30:29Z"
+---
+
+Pure data models, state enums, normalization, and policy decisions with zero I/O dependencies. Defines `TaskRecord`, `PlanRecord`, `TaskRunRecord`, `TaskLock`, `TaskHandoffRecord`, `TaskEvent`, `ActorRef`, `HarnessRef`, and sidecar types (`TaskTodo`, `FileLink`, `AcceptanceCriterion`, `ValidationCheck`). State machine transitions in `states.py`. Policy decisions in `policies.py` return `Decision` objects. All models have `to_dict()` / `from_dict()` for serialization.

taskledger-0.4.2/.archledger/records/building_blocks/al_block_0034.md

@@ -0,0 +1,22 @@
+---
+schema_version: 2
+id: al_block_0034
+type: black_box
+title: "Storage Layer"
+status: proposed
+section: building_block_view
+level: 1
+parent: al_block_0029
+order: 50
+date: "2026-05-23"
+interfaces: []
+location: []
+fulfilled_requirements: []
+risks: []
+tags: []
+body_format: markdown
+created_at: "2026-05-23T12:30:29Z"
+updated_at: "2026-05-23T12:30:29Z"
+---
+
+File system persistence for all canonical records. Implements the v2 task bundle layout where each task is a directory under `.taskledger/ledgers/<ledger_ref>/` with sidecar collections for plans, runs, locks, todos, questions, changes, checks, handoffs, and links. Event logging is opt-in (disabled by default) via `[event_logging] enabled = true`; when enabled, append-only `TaskEvent` records are stored in the ledger-level `events/` directory, not per-task sidecars. Key modules: `task_store.py` (CRUD, layout resolution), `frontmatter.py` (YAML/Markdown serialization), `atomic.py` (atomic writes), `locks.py` (lock file operations), `indexes.py` (index rebuilds), `events.py` (append-only event log), `paths.py` (project discovery), `project_config.py` (taskledger.toml parsing), `migrations.py` (storage version upgrades).

taskledger-0.4.2/.archledger/records/concepts/al_concept_0040.md

@@ -0,0 +1,18 @@
+---
+schema_version: 2
+id: al_concept_0040
+type: concept
+title: "Actor metadata and role semantics"
+status: proposed
+section: cross_cutting_concepts
+order: 10
+date: "2026-05-23"
+applies_to: []
+body_format: markdown
+created_at: "2026-05-23T12:30:59Z"
+updated_at: "2026-05-23T12:30:59Z"
+---
+
+Every mutation carries an `ActorRef` (type: agent/user/system, name, role, session ID, harness ID) and optionally a `HarnessRef` (harness identity, kind, capabilities). The system distinguishes user-only actions (plan approval, criterion waivers) from agent actions. Actor metadata is persisted in locks, runs, events, and handoff records for audit trails.
+
+Source: `taskledger/domain/actor.py` (`ActorRef`, `HarnessRef`), `taskledger/domain/states.py` (`ActorType`, `ActorRole`, `HarnessKind`).

taskledger-0.4.2/.archledger/records/concepts/al_concept_0041.md

@@ -0,0 +1,16 @@
+---
+schema_version: 2
+id: al_concept_0041
+type: concept
+title: "JSON output envelope contract"
+status: proposed
+section: cross_cutting_concepts
+order: 20
+date: "2026-05-23"
+applies_to: []
+body_format: markdown
+created_at: "2026-05-23T12:31:00Z"
+updated_at: "2026-05-23T12:31:00Z"
+---
+
+When `--json` is passed, every CLI command emits a JSON envelope: `{"ok": bool, "command": str, "result_type": str, "result": ..., "events": [...], "warnings": [...]}`. On error, the envelope includes `error` with `code`, `message`, `details`, and `remediation`. This shape is a public API contract tested by `test_json_contracts.py`. Exit codes map deterministically to error categories.

taskledger-0.4.2/.archledger/records/concepts/al_concept_0042.md

@@ -0,0 +1,16 @@
+---
+schema_version: 2
+id: al_concept_0042
+type: concept
+title: "YAML front matter serialization"
+status: proposed
+section: cross_cutting_concepts
+order: 30
+date: "2026-05-23"
+applies_to: []
+body_format: markdown
+created_at: "2026-05-23T12:31:00Z"
+updated_at: "2026-05-23T12:31:00Z"
+---
+
+All canonical records are `.md` files with YAML front matter (`---` delimited) containing structured metadata and a Markdown body. Read/write is handled by `read_markdown_front_matter` and `write_markdown_front_matter` in `taskledger/storage/frontmatter.py`. Models implement `to_dict()` / `from_dict()` for serialization. Schema version and object type fields enforce contract integrity on read.

taskledger-0.4.2/.archledger/records/concepts/al_concept_0043.md

@@ -0,0 +1,16 @@
+---
+schema_version: 2
+id: al_concept_0043
+type: concept
+title: "Atomic file writes"
+status: proposed
+section: cross_cutting_concepts
+order: 40
+date: "2026-05-23"
+applies_to: []
+body_format: markdown
+created_at: "2026-05-23T12:31:01Z"
+updated_at: "2026-05-23T12:31:01Z"
+---
+
+All file writes go through `atomic_write_text` (temp file → flush/fsync → `os.replace` → directory fsync) or `atomic_create_text` (`O_CREAT | O_EXCL` for lock files). This prevents partial writes on crash. Test environments can disable fsync via `TASKLEDGER_TEST_FAST_IO=1` for speed. Source: `taskledger/storage/atomic.py`.

taskledger-0.4.2/.archledger/records/concepts/al_concept_0044.md

@@ -0,0 +1,16 @@
+---
+schema_version: 2
+id: al_concept_0044
+type: concept
+title: "Append-only event log"
+status: proposed
+section: cross_cutting_concepts
+order: 50
+date: "2026-05-23"
+applies_to: []
+body_format: markdown
+created_at: "2026-05-23T12:31:01Z"
+updated_at: "2026-05-23T12:31:01Z"
+---
+
+When `[event_logging] enabled = true` in `taskledger.toml`, mutations append an immutable `TaskEvent` record to the ledger-level `events/` directory under `.taskledger/ledgers/<ledger_ref>/`. Event logging is disabled by default; when disabled, no new event records are written but existing records remain readable. Events are never modified or deleted. Each event has a deterministic ID, name (e.g., `task.created`, `plan.approved`, `lock.acquired`, `code_review.recorded`), timestamp, and actor metadata. Events support audit trails, handoff context, and `task transcript` output. Duplicate event detection prevents re-appending on retry. Source: `taskledger/storage/events.py`, `taskledger/services/task_events.py`, `taskledger/domain/event.py`.

taskledger-0.4.2/.archledger/records/concepts/al_concept_0045.md

@@ -0,0 +1,16 @@
+---
+schema_version: 2
+id: al_concept_0045
+type: concept
+title: "Exit code taxonomy"
+status: proposed
+section: cross_cutting_concepts
+order: 60
+date: "2026-05-23"
+applies_to: []
+body_format: markdown
+created_at: "2026-05-23T12:31:01Z"
+updated_at: "2026-05-23T12:31:01Z"
+---
+
+Stable exit codes for CLI and error classification: 0 (success), 1 (generic failure), 2 (bad input), 3 (workflow rejection — invalid transition, approval required, dependency blocked), 4 (lock conflict — stale lock requires break), 5 (not found / no active task), 6 (storage error / data integrity), 7 (validation failed). Defined in `taskledger/domain/states.py` and `taskledger/errors.py`. Agents and CI pipelines rely on specific codes for automation.

taskledger-0.4.2/.archledger/records/constraints/al_constraint_0016.md

@@ -0,0 +1,17 @@
+---
+schema_version: 2
+id: al_constraint_0016
+type: constraint
+title: "Python 3.10+ with minimal dependencies"
+status: proposed
+section: architecture_constraints
+order: 10
+date: "2026-05-23"
+category: technical
+impact: "Limits runtime to Python 3.10+ with five dependencies; no database or native extensions."
+body_format: markdown
+created_at: "2026-05-23T12:29:53Z"
+updated_at: "2026-05-23T12:29:53Z"
+---
+
+Runtime dependencies are limited to `typer`, `PyYAML`, `Jinja2`, `markdown-it-py`, and `tomli` (Python <3.11 only). This constraint ensures easy installation in constrained environments (CI, containers, Termux) and avoids dependency conflicts with host projects. The trade-off is that features like full-text search use pure-Python implementations rather than native libraries.

taskledger-0.4.2/.archledger/records/constraints/al_constraint_0017.md

@@ -0,0 +1,17 @@
+---
+schema_version: 2
+id: al_constraint_0017
+type: constraint
+title: "File-system canonical storage"
+status: proposed
+section: architecture_constraints
+order: 20
+date: "2026-05-23"
+category: technical
+impact: "State is file-based; query performance depends on index rebuilds."
+body_format: markdown
+created_at: "2026-05-23T12:29:54Z"
+updated_at: "2026-05-23T12:29:54Z"
+---
+
+All durable state is stored as Markdown files with YAML front matter in `.taskledger/`. This makes state human-readable, diffable in Git, and inspectable without taskledger. The trade-off is that query performance depends on file scanning and index rebuilding rather than a database engine.

taskledger-0.4.2/.archledger/records/constraints/al_constraint_0018.md

@@ -0,0 +1,17 @@
+---
+schema_version: 2
+id: al_constraint_0018
+type: constraint
+title: "CLI-first with machine-readable JSON output"
+status: proposed
+section: architecture_constraints
+order: 30
+date: "2026-05-23"
+category: technical
+impact: "JSON envelope shape and exit codes are public API contracts; breaking changes require version bumps."
+body_format: markdown
+created_at: "2026-05-23T12:29:54Z"
+updated_at: "2026-05-23T12:29:54Z"
+---
+
+The CLI is the primary interface. Every command supports `--json` for machine-readable output with a stable envelope shape (`ok`, `command`, `result_type`, `result`, `events`, `warnings`) and deterministic exit codes. This enables agent harnesses and CI pipelines to consume output programmatically without parsing human text.

taskledger-0.4.2/.archledger/records/constraints/al_constraint_0019.md

@@ -0,0 +1,17 @@
+---
+schema_version: 2
+id: al_constraint_0019
+type: constraint
+title: "Skills must stay outside the Python package"
+status: proposed
+section: architecture_constraints
+order: 40
+date: "2026-05-23"
+category: technical
+impact: "Skill distribution is separate from package distribution; skill installation is a distinct step."
+body_format: markdown
+created_at: "2026-05-23T12:29:55Z"
+updated_at: "2026-05-23T12:29:55Z"
+---
+
+Agent skill files (e.g., `skills/taskledger/SKILL.md`) live outside the `taskledger` Python package. They are not packaged as package data, not loaded via `importlib.resources`, and not distributed via PyPI. This separates the concerns of tool functionality (the package) from agent integration instructions (the skill).

taskledger-0.4.2/.archledger/records/contexts/al_context_0020.md

@@ -0,0 +1,20 @@
+---
+schema_version: 2
+id: al_context_0020
+type: context_interface
+title: "Agent harnesses"
+status: proposed
+section: context_and_scope
+order: 10
+date: "2026-05-23"
+context_kind: "technical"
+partner: "agent harness (opencode, codex, chatgpt)"
+inputs: []
+outputs: []
+channels: []
+body_format: markdown
+created_at: "2026-05-23T12:29:55Z"
+updated_at: "2026-05-23T12:29:55Z"
+---
+
+Agent harnesses invoke taskledger CLI commands as subprocesses. They consume `--json` output and rely on exit codes for automation. Key interactions: `task create`, `plan start`, `plan propose`, `implement start`, `implement log`, `validate start`, `validate check`, `handoff create`, `handoff claim`, `context`. Agents are restricted from user-only actions (plan approval, criterion waivers) by default.

taskledger-0.4.2/.archledger/records/contexts/al_context_0021.md

@@ -0,0 +1,20 @@
+---
+schema_version: 2
+id: al_context_0021
+type: context_interface
+title: "Human developers"
+status: proposed
+section: context_and_scope
+order: 20
+date: "2026-05-23"
+context_kind: "technical"
+partner: "terminal user"
+inputs: []
+outputs: []
+channels: []
+body_format: markdown
+created_at: "2026-05-23T12:29:55Z"
+updated_at: "2026-05-23T12:29:55Z"
+---
+
+Human developers use the CLI directly in terminals. Key interactions: `task create`, `task show`, `plan approve`, `implement finish`, `validate finish`, `lock break`, `doctor`, `status`, `next-action`. Humans render human-readable output (default) and perform user-only actions like plan approval and criterion waivers.

taskledger-0.4.2/.archledger/records/contexts/al_context_0022.md

@@ -0,0 +1,20 @@
+---
+schema_version: 2
+id: al_context_0022
+type: context_interface
+title: "CI systems"
+status: proposed
+section: context_and_scope
+order: 30
+date: "2026-05-23"
+context_kind: "technical"
+partner: "CI runner"
+inputs: []
+outputs: []
+channels: []
+body_format: markdown
+created_at: "2026-05-23T12:29:56Z"
+updated_at: "2026-05-23T12:29:56Z"
+---
+
+CI runners invoke taskledger commands in automated pipelines. Key interactions: `status --json`, `doctor`, `validate`, `export`, `snapshot`. CI relies on deterministic exit codes to gate pipeline stages.

taskledger-0.4.2/.archledger/records/contexts/al_context_0023.md

@@ -0,0 +1,20 @@
+---
+schema_version: 2
+id: al_context_0023
+type: context_interface
+title: "Python library consumers"
+status: proposed
+section: context_and_scope
+order: 40
+date: "2026-05-23"
+context_kind: "technical"
+partner: "Python import"
+inputs: []
+outputs: []
+channels: []
+body_format: markdown
+created_at: "2026-05-23T12:29:56Z"
+updated_at: "2026-05-23T12:29:56Z"
+---
+
+Python code imports from `taskledger.api.*` modules to manage tasks programmatically. The API layer (`taskledger/api/tasks.py`, `taskledger/api/plans.py`, etc.) provides function wrappers that mirror CLI operations without subprocess overhead. Returns dictionaries with the same shapes as JSON output.

taskledger-0.4.2/.archledger/records/decisions/al_adr_0046.md

@@ -0,0 +1,38 @@
+---
+schema_version: 2
+id: al_adr_0046
+type: adr
+title: "Markdown/YAML front matter as canonical format"
+status: accepted
+section: architecture_decisions
+order: 10
+date: "2026-05-23"
+deciders: []
+supersedes: []
+related: []
+tags: []
+body_format: markdown
+created_at: "2026-05-23T12:31:02Z"
+updated_at: "2026-05-23T12:31:02Z"
+---
+
+## Context
+
+Need a storage format for task state that is durable, human-readable, and version-controllable. Agents and humans need to inspect state without running taskledger.
+
+## Decision
+
+Store all records as Markdown files with YAML front matter (`---` delimited). Metadata (ID, type, status, dates) goes in YAML; free-form content goes in Markdown body.
+
+## Consequences
+
+- Positive: State is Git-diffable, human-readable, and editable in any text editor.
+- Positive: No database dependency.
+- Negative: Parsing is slower than binary formats for large datasets.
+- Negative: Schema evolution requires careful validation on read.
+
+## Alternatives considered
+
+- SQLite: Faster queries but opaque binary format, harder to version-control and inspect.
+- Pure JSON: Easier parsing but not human-friendly for long-form content (plan bodies, handoff contexts).
+- Single JSON index file: Rejected due to merge conflicts and scalability concerns.

taskledger-0.4.2/.archledger/records/decisions/al_adr_0047.md

@@ -0,0 +1,38 @@
+---
+schema_version: 2
+id: al_adr_0047
+type: adr
+title: "JSON indexes as derived rebuildable caches"
+status: accepted
+section: architecture_decisions
+order: 20
+date: "2026-05-23"
+deciders: []
+supersedes: []
+related: []
+tags: []
+body_format: markdown
+created_at: "2026-05-23T12:31:02Z"
+updated_at: "2026-05-23T12:31:02Z"
+---
+
+## Context
+
+Listing tasks, locks, and dependencies requires scanning many front matter files. Need a way to speed up queries without adding a database.
+
+## Decision
+
+Maintain JSON index files under `.taskledger/indexes/` as derived caches. They are rebuilt from canonical records by `taskledger reindex` and checked by `doctor indexes`. They are never the source of truth.
+
+## Consequences
+
+- Positive: Fast list/query operations without parsing all front matter files.
+- Positive: Indexes can always be rebuilt from canonical source.
+- Negative: Indexes can become stale after manual edits or crashes.
+- Negative: `reindex` must be run after out-of-band changes.
+
+## Alternatives considered
+
+- No indexes (always scan files): Simpler but too slow for large projects.
+- SQLite index: More robust but adds complexity and dependency.
+- In-memory cache: Lost on process restart, not durable.

taskledger-0.4.2/.archledger/records/decisions/al_adr_0048.md

@@ -0,0 +1,37 @@
+---
+schema_version: 2
+id: al_adr_0048
+type: adr
+title: "Explicit lifecycle gates with policy decisions"
+status: accepted
+section: architecture_decisions
+order: 30
+date: "2026-05-23"
+deciders: []
+supersedes: []
+related: []
+tags: []
+body_format: markdown
+created_at: "2026-05-23T12:31:02Z"
+updated_at: "2026-05-23T12:31:02Z"
+---
+
+## Context
+
+Without lifecycle gates, agents could skip review and implement without approval. Need enforceable transitions between task stages.
+
+## Decision
+
+Implement lifecycle gates as pure policy functions in `taskledger/domain/policies.py`. Each gate function takes a `PolicyContext` (task, lock, run) and returns a `Decision` (allowed, code, message, exit_code). The state machine in `states.py` defines `ALLOWED_STAGE_TRANSITIONS`. Services call policies before mutating state.
+
+## Consequences
+
+- Positive: Gate logic is fully testable without I/O setup.
+- Positive: User-only actions (approval, waivers) are enforced at the policy level.
+- Negative: Services must gather full context before calling policies.
+
+## Alternatives considered
+
+- Free-form state changes: Rejected — agents could bypass review.
+- Database triggers: Rejected — adds database dependency and complexity.
+- CLI-only validation: Rejected — API and programmatic users would bypass gates.

taskledger-0.4.2/.archledger/records/decisions/al_adr_0049.md

@@ -0,0 +1,37 @@
+---
+schema_version: 2
+id: al_adr_0049
+type: adr
+title: "Typer CLI framework"
+status: accepted
+section: architecture_decisions
+order: 40
+date: "2026-05-23"
+deciders: []
+supersedes: []
+related: []
+tags: []
+body_format: markdown
+created_at: "2026-05-23T12:31:03Z"
+updated_at: "2026-05-23T12:31:03Z"
+---
+
+## Context
+
+Need a CLI framework that supports subcommand groups, type-annotated parameters, and integrates with Click's ecosystem.
+
+## Decision
+
+Use Typer (built on Click) for the CLI. Typer provides type-annotated parameters, subcommand groups, and automatic help generation. The root app in `cli.py` registers nested Typer apps for each command family.
+
+## Consequences
+
+- Positive: Clean type-annotated parameter definitions with `Annotated` types.
+- Positive: Click ecosystem compatibility (middleware, testing).
+- Negative: Typer adds `click` as a transitive dependency.
+
+## Alternatives considered
+
+- Pure Click: More verbose parameter definitions, no type annotation inference.
+- Argparse: Standard library but lacks subcommand ergonomics and type inference.
+- Docopt: Declarative but harder to compose nested subcommands.

taskledger-0.4.2/.archledger/records/decisions/al_adr_0050.md

@@ -0,0 +1,36 @@
+---
+schema_version: 2
+id: al_adr_0050
+type: adr
+title: "Task bundle directory layout"
+status: accepted
+section: architecture_decisions
+order: 50
+date: "2026-05-23"
+deciders: []
+supersedes: []
+related: []
+tags: []
+body_format: markdown
+created_at: "2026-05-23T12:31:03Z"
+updated_at: "2026-05-23T12:31:03Z"
+---
+
+## Context
+
+Need a storage layout that scales to many sidecar collections per task (plans, runs, locks, todos, questions, changes, checks, handoffs, links) while keeping each record individually addressable. Events are stored at ledger level, not per-task, and are opt-in.
+
+## Decision
+
+Use a directory-per-task layout (v2 bundle) under `.taskledger/ledgers/<ledger_ref>/`. Each task gets a directory containing the task record (Markdown) and subdirectories for sidecar collections. JSON indexes are derived caches at the ledger level. Event records are stored in the ledger-level `events/` directory (not per-task) and are only written when `[event_logging] enabled = true`.
+
+## Consequences
+
+- Positive: Each record is a single file — easy to read, edit, and version-control.
+- Positive: Sidecar collections are independently addressable.
+- Negative: Many small files create directory overhead on very large projects.
+
+## Alternatives considered
+
+- Single JSON index file: Merge conflicts, scalability, not human-readable.
+- Database (SQLite): Opaque, harder to inspect and version-control.

taskledger-0.4.2/.archledger/records/decisions/al_adr_0051.md

@@ -0,0 +1,36 @@
+---
+schema_version: 2
+id: al_adr_0051
+type: adr
+title: "External skill packaging"
+status: accepted
+section: architecture_decisions
+order: 60
+date: "2026-05-23"
+deciders: []
+supersedes: []
+related: []
+tags: []
+body_format: markdown
+created_at: "2026-05-23T12:31:04Z"
+updated_at: "2026-05-23T12:31:04Z"
+---
+
+## Context
+
+Agent skill files (SKILL.md) provide integration instructions for coding agents. Need to decide where they live relative to the Python package.
+
+## Decision
+
+Skills live under `skills/taskledger/` in the repository, outside the `taskledger` Python package. They are not packaged as Python package data, not loaded via `importlib.resources`, and not distributed via PyPI as part of the package.
+
+## Consequences
+
+- Positive: Clean separation between tool functionality and agent integration instructions.
+- Positive: Skills can be versioned independently and distributed through different channels.
+- Negative: Skill installation is a separate step from package installation.
+
+## Alternatives considered
+
+- Package skills as package data: Coupling skill version to package version, harder to update independently.
+- Load skills via importlib.resources: Adds packaging complexity and coupling.