taskledger 0.4.1__tar.gz → 0.5.0__tar.gz

taskledger-0.5.0/.archledger/archive/records/building_blocks/al_block_0083.md

@@ -0,0 +1,41 @@
+---
+schema_version: 2
+id: al_block_0083
+type: black_box
+title: Human Presentation Layer
+status: archived
+section: building_block_view
+level: 1
+parent: al_block_0029
+order: 60
+date: "2026-06-07"
+interfaces:
+  - Service read models -> terminal TUI
+  - Dashboard/report payloads -> HTML or Markdown
+location:
+  - taskledger/tui/
+  - taskledger/services/tui_read_model.py
+  - taskledger/services/dashboard.py
+  - taskledger/services/task_reports.py
+fulfilled_requirements: []
+risks: []
+tags: []
+body_format: markdown
+created_at: "2026-06-07T11:49:59Z"
+updated_at: "2026-06-11T20:53:29Z"
+source_refs:
+  - path: taskledger/tui/
+    role: implements
+  - path: taskledger/services/tui_read_model.py
+    role: implements
+test_refs:
+  - tests/test_tui_cli.py
+  - tests/test_tui_read_model.py
+archived_at: "2026-06-11T20:53:29Z"
+archived_reason: TUI and HTML dashboard removed from taskledger; task-0126 ledger-isolation
+archived_from: records/building_blocks/al_block_0083.md
+---
+
+Optional human-facing views over the same durable task records used by CLI and API operations. The Textual TUI presents task lists, plan review, todos, implementation, code reviews, validation, files, events, and raw reports. HTML dashboard and Markdown report services provide related inspection and sharing views.
+
+This layer is read-only with respect to lifecycle state. Users invoke explicit CLI commands for mutations, preserving approval, lock, todo, and validation gates.

taskledger-0.5.0/.archledger/archive/records/concepts/al_concept_0081.md

@@ -0,0 +1,32 @@
+---
+schema_version: 2
+id: al_concept_0081
+type: concept
+title: BDD traceability and report evidence
+status: archived
+section: cross_cutting_concepts
+order: 70
+date: "2026-06-07"
+applies_to: []
+body_format: markdown
+created_at: "2026-06-07T11:49:58Z"
+updated_at: "2026-06-11T20:53:29Z"
+source_refs:
+  - path: taskledger/domain/bdd.py
+    role: implements
+  - path: taskledger/services/bdd_gherkin.py
+    role: implements
+  - path: taskledger/services/bdd_reports.py
+    role: implements
+test_refs:
+  - tests/test_bdd_gherkin.py
+  - tests/test_bdd_report_import.py
+  - tests/test_bdd_validation_integration.py
+archived_at: "2026-06-11T20:53:29Z"
+archived_reason: BDD traceability removed from taskledger; task-0126 ledger-isolation
+archived_from: records/concepts/al_concept_0081.md
+---
+
+BDD is an optional traceability overlay on a managed task. Features contain rules and Given/When/Then examples. Examples can reference canonical acceptance-criterion IDs and Archledger record IDs.
+
+Gherkin export is an exchange artifact, not canonical state. Stable tags preserve task, example, criterion, and architecture identities. Imported Cucumber JSON or JUnit XML is matched back to examples and persisted as report evidence that can contribute validation checks. Normal lifecycle and validation gates remain authoritative.

taskledger-0.5.0/.archledger/archive/records/runtime/al_runtime_0076.md

@@ -0,0 +1,33 @@
+---
+schema_version: 2
+id: al_runtime_0076
+type: runtime_scenario
+title: HTML report and serve dashboard
+status: archived
+section: runtime_view
+order: 70
+date: "2026-05-23"
+participants: []
+trigger: Developer runs taskledger report html or taskledger serve
+result: ""
+body_format: markdown
+created_at: "2026-05-23T19:30:00Z"
+updated_at: "2026-06-11T20:54:44Z"
+archived_at: "2026-06-11T20:54:44Z"
+archived_reason: HTML report and serve dashboard removed; task-0126 ledger-isolation
+archived_from: records/runtime/al_runtime_0076.md
+---
+
+**Trigger**: Developer runs `taskledger report html` or `taskledger serve`.
+
+**Flow**:
+
+1. `report html` → Generates a standalone HTML report file from task data using Jinja2 templates
+2. `task report` → Generates a per-task report with configurable sections (summary, plan, changes, command-log)
+3. `serve` → Starts a localhost HTTP server with a read-only web dashboard for browsing tasks, plans, and status
+4. Dashboard renders task trees, status summaries, and plan details in a browser
+5. All report/serve output is read-only — no mutations through the dashboard
+
+**Result**: Human-readable HTML reports and a local dashboard for inspecting task state without the CLI. Agents should continue using JSON output and CLI commands.
+
+**Key source**: `taskledger/services/html_reports.py`, `taskledger/services/web_dashboard.py`, `taskledger/services/task_reports.py`, `taskledger/cli_report.py`.

taskledger-0.5.0/.archledger/archive/records/runtime/al_runtime_0084.md

@@ -0,0 +1,42 @@
+---
+schema_version: 2
+id: al_runtime_0084
+type: runtime_scenario
+title: BDD example to validation evidence
+status: archived
+section: runtime_view
+order: 100
+date: "2026-06-07"
+participants:
+  - coding agent
+  - taskledger CLI
+  - BDD services
+  - task storage
+trigger: An actor wants executable examples linked to task acceptance criteria.
+result: External automation results are persisted as traceable validation evidence.
+body_format: markdown
+created_at: "2026-06-07T11:50:18Z"
+updated_at: "2026-06-11T20:53:29Z"
+source_refs:
+  - path: taskledger/cli_bdd.py
+    role: implements
+  - path: taskledger/services/bdd_gherkin.py
+    role: implements
+  - path: taskledger/services/bdd_reports.py
+    role: implements
+test_refs:
+  - tests/test_bdd_cli.py
+  - tests/test_bdd_validation_integration.py
+archived_at: "2026-06-11T20:53:29Z"
+archived_reason: BDD example scenario removed from taskledger; task-0126 ledger-isolation
+archived_from: records/runtime/al_runtime_0084.md
+---
+
+1. An actor initializes task-local BDD/example records for a managed task.
+2. Each example links to acceptance-criterion IDs and may link to Archledger records.
+3. Canonical behavior specs live outside Taskledger under `specs/behavior/features/<area>/<feature>.feature`, owned by SpecWeave.
+4. Plain pytest files under `tests/test_<area>_<feature>.py` enforce the behavior and may emit JUnit XML under `reports/behavior/`.
+5. `bdd example link-automation` records metadata that links a task-local example to the external feature file, scenario tag/title, and pytest node id.
+6. `validate import-bdd-report` imports JUnit XML or Cucumber-compatible JSON evidence and matches it back to task-local examples.
+7. Matched results become validation evidence through normal validation checks; normal latest-check-wins and mandatory-criterion gates still decide completion.
+8. `bdd gherkin-export` remains a derived exchange/export command. It must not be presented as the canonical source of executable behavior.

taskledger-0.5.0/.archledger/profiles/arc42/sections/al_content_0001.md

@@ -0,0 +1,30 @@
+---
+schema_version: 2
+id: al_content_0001
+type: section
+section: introduction_and_goals
+title: Introduction and Goals
+order: 10
+status: accepted
+date: "2026-05-23"
+body_format: markdown
+created_at: "2026-05-23T12:24:46Z"
+updated_at: "2026-05-23T12:24:46Z"
+---
+
+taskledger is a task-first durable state layer for staged coding work. It provides a Python CLI and library that manages the full lifecycle of coding tasks: creation, planning, user approval, implementation, validation, and completion.
+
+The system is designed for use by both human developers and automated coding agents. Its primary goals are:
+
+- **Durable task state**: Every task, plan, todo, and validation check is persisted as Markdown/YAML front matter in the project's `.taskledger/` directory. State survives process restarts, context switches, and handoffs between actors.
+- **Explicit lifecycle gates**: Transitions between stages (draft → planning → plan_review → approved → implementing → implemented → validating → done) are enforced by policy decisions. User approval is required before implementation begins. Validation checks gate completion.
+- **Fresh-context handoffs**: Agents and humans can create, claim, and close handoff records that capture enough context (task state, plan, todos, questions, lock status) for a fresh process to continue work without reading the entire history.
+- **Machine-readable output**: Every CLI command supports `--json` for structured output with a stable envelope shape (`ok`, `command`, `result_type`, `result`, `events`, `warnings`) and deterministic exit codes.
+
+The canonical workflow is:
+
+```text
+task → plan → approval → implement → validate → done
+```
+
+This workflow is the product contract, not decoration. Deviations from this flow require explicit user decisions or repair commands.

taskledger-0.5.0/.archledger/profiles/arc42/sections/al_content_0002.md

@@ -0,0 +1,21 @@
+---
+schema_version: 2
+id: al_content_0002
+type: section
+section: architecture_constraints
+title: Architecture Constraints
+order: 20
+status: accepted
+date: "2026-05-23"
+body_format: markdown
+created_at: "2026-05-23T12:24:46Z"
+updated_at: "2026-05-23T12:24:46Z"
+---
+
+taskledger operates under several fixed constraints that shape its architecture:
+
+- **Python 3.10+ with minimal dependencies**: The runtime depends only on `typer`, `PyYAML`, and `tomli` (for Python <3.11). No database, no network server, no external service is required.
+- **File-system canonical storage**: All durable state lives in the project's `.taskledger/` directory as Markdown files with YAML front matter. This makes state inspectable, diffable, and version-controllable alongside source code.
+- **CLI-first with machine-readable JSON output**: The primary interface is the `taskledger` CLI command. Every command supports `--json` for structured output. The JSON envelope shape and exit codes are part of the public contract.
+- **Skills outside the package**: Agent skill files (e.g., `skills/taskledger/SKILL.md`) live outside the Python package and are never packaged as Python package data. The package provides the CLI/library; skill distribution is separate.
+- **Project-local configuration**: Each project has its own `taskledger.toml` and `.taskledger/` directory. There is no global state or central server.

taskledger-0.5.0/.archledger/profiles/arc42/sections/al_content_0003.md

@@ -0,0 +1,24 @@
+---
+schema_version: 2
+id: al_content_0003
+type: section
+section: context_and_scope
+title: Context and Scope
+order: 30
+status: accepted
+date: "2026-05-23"
+body_format: markdown
+created_at: "2026-05-23T12:24:46Z"
+updated_at: "2026-05-23T12:24:46Z"
+---
+
+taskledger operates as a self-contained tool within a software development project. It interacts with four categories of external actors:
+
+1. **Agent harnesses** (opencode, codex, chatgpt, etc.) invoke taskledger CLI commands to create tasks, propose plans, log implementation changes, run validation checks, and manage handoffs. They consume `--json` output.
+2. **Human developers** use the CLI directly in terminals for task creation, plan review, approval, lock management, and inspection (`status`, `context`, `next-action`, `doctor`).
+3. **CI systems** may invoke taskledger for status checks, validation, or snapshot/export operations.
+4. **Python library consumers** import from `taskledger.api.*` to programmatically manage tasks without the CLI subprocess.
+
+The system boundary is the `.taskledger/` directory and the `taskledger.toml` config file at the project root. Everything inside `.taskledger/` is taskledger-owned state. Everything outside is the host project's source code.
+
+taskledger does not depend on any external services, databases, or network endpoints. It reads the host project's file system for search/symbol operations but does not modify files outside `.taskledger/`.

taskledger-0.5.0/.archledger/profiles/arc42/sections/al_content_0004.md

@@ -0,0 +1,38 @@
+---
+schema_version: 2
+id: al_content_0004
+type: section
+section: solution_strategy
+title: Solution Strategy
+order: 40
+status: accepted
+date: "2026-05-23"
+body_format: markdown
+created_at: "2026-05-23T12:24:46Z"
+updated_at: "2026-05-23T12:24:46Z"
+---
+
+taskledger uses a layered architecture with clear dependency direction: upper layers depend on lower layers, never the reverse.
+
+1. **CLI Layer** (`taskledger/cli*.py`) — Typer commands that parse arguments, resolve task references, call service functions, and render output (human text or JSON).
+2. **API Layer** (`taskledger/api/*.py`) — Stable public wrappers that mirror the CLI surface for programmatic use.
+3. **Services Layer** (`taskledger/services/*.py`) — Orchestration logic: lifecycle flows (planning, implementation, validation), handoff rendering, doctor checks, dashboard assembly.
+4. **Domain Layer** (`taskledger/domain/*.py`) — Pure data models, state enums, normalization, and policy decisions. No I/O, no file system access.
+5. **Storage Layer** (`taskledger/storage/*.py`) — File system operations: front matter read/write, atomic writes, lock files, index rebuilds, migrations.
+
+Key architectural choices:
+
+- **Markdown/YAML front matter as canonical format** — Each record (task, plan, run, lock, handoff, etc.) is stored as a `.md` file with YAML front matter metadata and a Markdown body. This makes state human-readable and Git-friendly.
+- **JSON indexes as derived caches** — Index files under `.taskledger/indexes/` are rebuilt from canonical records by `taskledger reindex`. They are never the source of truth.
+- **Policy-based gate decisions** — All lifecycle transitions go through functions in `taskledger/domain/policies.py` that return `Decision` objects with `allowed`, `code`, `message`, and `exit_code`. This keeps gate logic testable and separate from I/O.
+- **Atomic file writes** — All writes use `atomic_write_text` (write to temp, `os.replace`) to prevent partial writes on crash.
+- **Evidence as sidecars** — Code-review records extend traceability without introducing new lifecycle stages or weakening validation gates.
+
+## Maintenance
+
+`ARCHITECTURE.md` in the repository root is generated from archledger source records. Do not edit it directly.
+
+- **Edit**: `.archledger/sections/*.md` for section content, `.archledger/records/**/*.md` for individual records.
+- **Regenerate**: Run `archledger build` (or the configured build command) to regenerate `ARCHITECTURE.md`.
+- **Verify**: Run `pytest tests/test_docs_and_skill.py tests/test_service_boundaries.py` after changes.
+- **Authoritative source**: The archledger records under `.archledger/` are the single source of truth for architecture documentation. `docs/architecture_taskledger_split.rst` is a concise human-maintained summary.

taskledger-0.5.0/.archledger/profiles/arc42/sections/al_content_0005.md

@@ -0,0 +1,25 @@
+---
+schema_version: 2
+id: al_content_0005
+type: section
+section: building_block_view
+title: Building Block View
+order: 50
+status: accepted
+date: "2026-05-23"
+body_format: markdown
+created_at: "2026-05-23T12:24:46Z"
+updated_at: "2026-05-23T12:24:46Z"
+---
+
+The top-level building block is the **taskledger system**, decomposed into five black-box components:
+
+1. **CLI Layer** — Handles command parsing, task reference resolution, and output rendering.
+2. **API Layer** — Provides stable Python function wrappers around service operations.
+3. **Services Layer** — Orchestrates lifecycle flows, handoffs, and inspection.
+4. **Domain Layer** — Defines models, state machines, and policy decisions.
+5. **Storage Layer** — Manages file system persistence and layout.
+
+Data flows strictly downward: CLI → Services → Domain + Storage. The API layer calls Services directly. The Domain layer has no dependencies on Storage or Services.
+
+Each task is stored as a **task bundle directory** under `.taskledger/ledgers/<ledger_ref>/` containing the task record (Markdown) and sidecar collections for plans, runs, locks, todos, questions, changes, checks, handoffs, and links. Mutations append immutable `TaskEvent` records to the ledger-level `events/` directory. Action/event logging is enabled by default; set `[event_logging] enabled = false` in `taskledger.toml` to disable new event records. Existing records remain readable regardless.

taskledger-0.5.0/.archledger/profiles/arc42/sections/al_content_0006.md

@@ -0,0 +1,22 @@
+---
+schema_version: 2
+id: al_content_0006
+type: section
+section: runtime_view
+title: Runtime View
+order: 60
+status: accepted
+date: "2026-05-23"
+body_format: markdown
+created_at: "2026-05-23T12:24:46Z"
+updated_at: "2026-05-23T12:24:46Z"
+---
+
+The runtime view traces the main operational scenarios through the system:
+
+1. **Task lifecycle** — A task is created in `draft`, moves to `planning` (lock acquired, run started), then `plan_review` after a plan is proposed. The user approves → `approved`. Implementation starts → `implementing`, finishes → `implemented`. Validation starts → `validating`, passes → `done`.
+2. **Lock lifecycle** — Starting a stage (planning/implementation/validation) acquires a lock and creates a run. Locks have lease timers and heartbeats. Stale locks require explicit break flow with audit trail.
+3. **Handoff flow** — A worker creates a handoff with generated context (task state, plan, todos, questions, lock info). Another worker claims it, optionally transferring the lock. The handoff is closed when the receiving worker completes.
+4. **Doctor checks** — Inspects lock/run consistency, front matter integrity, index staleness, and storage layout version. Reports diagnostics with severity, code, and repair hints.
+5. **Validation evidence flow** — Acceptance criteria from the accepted plan are checked during the validation stage. Evidence is recorded per criterion with pass/fail/warn status. Latest-check-wins semantics apply; mandatory criteria gate completion.
+6. **Code-review evidence** — A reviewer records append-only review evidence against an implementation run, handoff, worker step, working tree, or commit. This is evidence attached to the task, not a new lifecycle stage.

taskledger-0.5.0/.archledger/profiles/arc42/sections/al_content_0007.md

@@ -0,0 +1,21 @@
+---
+schema_version: 2
+id: al_content_0007
+type: section
+section: deployment_view
+title: Deployment View
+order: 70
+status: accepted
+date: "2026-05-23"
+body_format: markdown
+created_at: "2026-05-23T12:24:46Z"
+updated_at: "2026-05-23T12:24:46Z"
+---
+
+taskledger is a single-node, file-system-based tool. Deployment consists of:
+
+- **Installation**: `pip install taskledger` (PyPI) or local `pip install -e .`
+- **Project initialization**: `taskledger init` creates `taskledger.toml` and `.taskledger/` in the project root
+- **Runtime**: The CLI runs as a Python process, reading and writing the project's `.taskledger/` directory. No daemon, no server.
+- **CI integration**: taskledger commands can be run in CI pipelines for status checks and validation
+- **Agent integration**: Agent harnesses invoke taskledger CLI commands as subprocess calls

taskledger-0.5.0/.archledger/profiles/arc42/sections/al_content_0008.md

@@ -0,0 +1,24 @@
+---
+schema_version: 2
+id: al_content_0008
+type: section
+section: cross_cutting_concepts
+title: Cross-cutting Concepts
+order: 80
+status: accepted
+date: "2026-05-23"
+body_format: markdown
+created_at: "2026-05-23T12:24:46Z"
+updated_at: "2026-05-23T12:24:46Z"
+---
+
+Cross-cutting concerns that span multiple layers:
+
+- **Actor metadata**: Every mutation carries an `ActorRef` (type: agent/user/system, name, role, session, harness). Decisions distinguish user-only actions (approval, waiver) from agent actions.
+- **JSON output envelope**: All CLI commands emit a consistent JSON envelope with `ok`, `command`, `result_type`, `result`, `events`, and `warnings` fields when `--json` is passed.
+- **YAML front matter serialization**: All canonical records use YAML front matter (`---` delimited) for metadata and Markdown for body. Serialization/deserialization is in `taskledger/storage/frontmatter.py`.
+- **Atomic file writes**: All file writes go through `atomic_write_text` (temp file → `os.replace` → directory fsync) to prevent corruption.
+- **Action/event logging (default-on)**: Mutations append immutable `TaskEvent` records to the ledger-level `events/` directory under `.taskledger/ledgers/<ledger_ref>/`. Action/event logging is enabled by default; set `[event_logging] enabled = false` to disable new records. Existing records remain readable. Events track who did what, when, and why. Source: `taskledger/storage/events.py`, `taskledger/services/task_events.py`.
+- **Exit code taxonomy**: Errors map to stable exit codes (0=success, 1=generic, 2=bad input, 3=workflow rejection, 4=lock conflict, 5=missing, 6=storage, 7=validation failed).
+- **Opaque cross-ledger references**: Links and file references remain opaque strings. Taskledger does not interpret archledger IDs, SpecWeave feature paths, or other external system references.
+- **Read-model reuse**: `view` and `status` commands consume service-level read models. These presentations are read-only and do not bypass lifecycle services.

taskledger-0.5.0/.archledger/profiles/arc42/sections/al_content_0009.md

@@ -0,0 +1,22 @@
+---
+schema_version: 2
+id: al_content_0009
+type: section
+section: architecture_decisions
+title: Architecture Decisions
+order: 90
+status: accepted
+date: "2026-05-23"
+body_format: markdown
+created_at: "2026-05-23T12:24:46Z"
+updated_at: "2026-05-23T12:24:46Z"
+---
+
+Key architecture decisions documented as ADR records:
+
+- **ADR-1**: Markdown/YAML front matter as canonical format (not JSON, not SQLite)
+- **ADR-2**: JSON indexes as derived rebuildable caches (not authoritative)
+- **ADR-3**: Explicit lifecycle gates with policy decisions (not free-form state)
+- **ADR-4**: Typer CLI framework (not argparse, not click directly)
+- **ADR-5**: Task bundle directory layout (not single-file index)
+- **ADR-6**: External skill packaging (skills outside the Python package)

taskledger-0.5.0/.archledger/profiles/arc42/sections/al_content_0010.md

@@ -0,0 +1,21 @@
+---
+schema_version: 2
+id: al_content_0010
+type: section
+section: quality_requirements
+title: Quality Requirements
+order: 100
+status: accepted
+date: "2026-05-23"
+body_format: markdown
+created_at: "2026-05-23T12:24:46Z"
+updated_at: "2026-05-23T12:24:46Z"
+---
+
+Quality requirements that gate architectural decisions:
+
+- **Data integrity**: Atomic writes and strict front matter validation prevent corrupt state. Partial writes are impossible due to `os.replace` semantics.
+- **CLI exit code contract**: Exit codes are stable and tested. Agents and CI pipelines rely on specific codes for automation.
+- **JSON envelope stability**: The JSON output shape (`ok`, `command`, `result_type`, `result`) is a public API contract. Breaking changes require explicit versioning.
+- **Lifecycle gate correctness**: Every stage transition is validated by policy functions with full test coverage of error paths.
+- **Export/import round-trip**: Archives preserve all state. Import into a fresh workspace reproduces the original taskledger state exactly.

taskledger-0.5.0/.archledger/profiles/arc42/sections/al_content_0011.md

@@ -0,0 +1,20 @@
+---
+schema_version: 2
+id: al_content_0011
+type: section
+section: risks_and_technical_debt
+title: Risks and Technical Debt
+order: 110
+status: accepted
+date: "2026-05-23"
+body_format: markdown
+created_at: "2026-05-23T12:24:46Z"
+updated_at: "2026-05-23T12:24:46Z"
+---
+
+Known risks and areas of technical debt:
+
+- **Storage scaling with many tasks**: Each task is a directory with multiple sidecar files. Very large projects (hundreds of tasks) may see slowdowns in list/query operations since indexes are rebuilt from file scans.
+- **Migration surface between storage versions**: The storage layout has evolved (currently v3). Migration code in `taskledger/storage/migrations.py` adds complexity. Future format changes must maintain backward compatibility.
+- **Service boundary erosion**: Some service modules (notably `tasks.py`) have grown large. The service layer has no formal interface contracts — boundaries are enforced by convention and tests (`test_service_boundaries.py`).
+- **Growing dependency count**: The dependency set is small (typer, PyYAML, tomli) but new dependencies must be justified by core features, not optional presentations.

taskledger-0.5.0/.archledger/profiles/arc42/sections/al_content_0012.md

@@ -0,0 +1,15 @@
+---
+schema_version: 2
+id: al_content_0012
+type: section
+section: glossary
+title: Glossary
+order: 120
+status: accepted
+date: "2026-05-23"
+body_format: markdown
+created_at: "2026-05-23T12:24:46Z"
+updated_at: "2026-05-23T12:24:46Z"
+---
+
+Domain terms used throughout taskledger:

taskledger-0.5.0/.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-06-11T21:00:00Z"
+---
+
+## Motivation
+
+taskledger decomposes into core layers with downward dependency flow. This isolates persistence, business rules, orchestration, and public interfaces.
+
+## 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.5.0/.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-06-11T21:00:00Z"
+---
+
+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`). Command families include the canonical lifecycle plus `review`, `config`, task archive operations, transfer/sync, diagnostics, and the `monitor` observer.
+
+Source refs: `taskledger/cli.py`, `taskledger/cli_common.py`, `taskledger/command_inventory.py`, and the focused `taskledger/cli_*.py` registration modules.

taskledger-0.5.0/.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.5.0/.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-06-11T21:00:00Z"
+---
+
+Orchestrates lifecycle flows by coordinating Domain policies and records with Storage. Focused services own planning, implementation, validation, handoffs, doctor checks, navigation, worker pipelines, archival, code-review evidence, event logging, exports, dashboard assembly, and ready-work inspection. `tasks.py` remains the compatibility-oriented lifecycle facade while ownership is progressively extracted into focused modules.

taskledger-0.5.0/.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-06-11T21:00:00Z"
+---
+
+Data models, state enums, normalization, and policy decisions without storage I/O. Besides lifecycle and sidecar records, the domain defines append-only code-review records. State transitions remain in `states.py`; policy decisions in `policies.py` return structured `Decision` objects.

taskledger-0.5.0/.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-06-11T21:00:00Z"
+---
+
+File system persistence for canonical records. Storage layout keeps each task in `.taskledger/ledgers/<ledger_ref>/tasks/<task-id>/`, with independently addressable sidecars including plans, runs, locks, todos, questions, changes, checks, handoffs, links, and code reviews. Ledger-level collections hold events, introductions, releases, and rebuildable indexes. Action/event logging is enabled by default and can be disabled in project config. Project config edits use structured TOML handling rather than ad hoc text replacement.

taskledger-0.5.0/.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.5.0/.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.