taskledger 0.5.2__tar.gz → 0.6.0__tar.gz

taskledger-0.6.0/.archledger/archive/records/building_blocks/block-0083.md

@@ -0,0 +1,39 @@
+---
+schema_version: 4
+id: block-0083
+type: black_box
+title: Human Presentation Layer
+status: archived
+section: building_block_view
+level: 1
+parent: block-0029
+order: 60
+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
+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_reason: TUI and HTML dashboard removed from taskledger; task-0126 ledger-isolation
+archived_from: records/building_blocks/block-0083.md
+kind: block
+version: 1
+---
+
+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.6.0/.archledger/archive/records/concepts/concept-0081.md

@@ -0,0 +1,30 @@
+---
+schema_version: 4
+id: concept-0081
+type: concept
+title: BDD traceability and report evidence
+status: archived
+section: cross_cutting_concepts
+order: 70
+applies_to: []
+body_format: markdown
+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_reason: BDD traceability removed from taskledger; task-0126 ledger-isolation
+archived_from: records/concepts/concept-0081.md
+kind: concept
+version: 1
+---
+
+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.6.0/.archledger/archive/records/runtime/runtime-0076.md

@@ -0,0 +1,33 @@
+---
+schema_version: 4
+id: runtime-0076
+type: runtime_scenario
+title: HTML report and serve dashboard
+status: archived
+section: runtime_view
+order: 70
+participants:
+  - taskledger report html (removed)
+  - taskledger serve (removed)
+trigger: Developer runs taskledger report html or taskledger serve
+result: ""
+body_format: markdown
+archived_reason: HTML report and serve dashboard removed; task-0126 ledger-isolation
+archived_from: records/runtime/runtime-0076.md
+kind: runtime
+version: 1
+---
+
+**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.6.0/.archledger/archive/records/runtime/runtime-0084.md

@@ -0,0 +1,40 @@
+---
+schema_version: 4
+id: runtime-0084
+type: runtime_scenario
+title: BDD example to validation evidence
+status: archived
+section: runtime_view
+order: 100
+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
+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_reason: BDD example scenario removed from taskledger; task-0126 ledger-isolation
+archived_from: records/runtime/runtime-0084.md
+kind: runtime
+version: 1
+---
+
+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.6.0/.archledger/document-state.json

@@ -0,0 +1,10 @@
+{
+  "documents": {
+    "arc42:markdown:draft=false:superseded=false": {
+      "fingerprint": "sha256:90460011ff7f175475e9656f06c3472dfaf38d193f6b057612d880e739849df2",
+      "input_count": 84,
+      "version": 1
+    }
+  },
+  "schema": "archledger.document-state.v1"
+}

taskledger-0.6.0/.archledger/profiles/arc42/sections/content-0001.md

@@ -0,0 +1,30 @@
+---
+schema_version: 4
+id: content-0001
+type: section
+section: introduction_and_goals
+title: Introduction and Goals
+order: 10
+status: accepted
+body_format: markdown
+kind: content
+version: 2
+---
+
+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, run, lock, todo, and validation check is persisted as a Markdown record with YAML front matter in the project `.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.
+- **Opaque cross-ledger references**: Task-ledger task, plan, file, and link references remain opaque strings. Taskledger does not interpret ledgercore global refs, archledger IDs, or other external system identifiers.
+
+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.6.0/.archledger/profiles/arc42/sections/content-0002.md

@@ -0,0 +1,21 @@
+---
+schema_version: 4
+id: content-0002
+type: section
+section: architecture_constraints
+title: Architecture Constraints
+order: 20
+status: accepted
+body_format: markdown
+kind: content
+version: 2
+---
+
+taskledger operates under several fixed constraints that shape its architecture:
+
+- **Python 3.10+ with minimal dependencies**: The runtime depends only on `typer`, `click`, `PyYAML`, `tomli` (Python <3.11), and `ledgercore` for atomic I/O, JSON I/O, YAML I/O, front matter parsing, and cross-ledger ref parsing. No database, no network server, no external service is required.
+- **File-system canonical storage**: All durable state lives in the project `.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 (for example `skills/taskledger/SKILL.md`) live outside the Python package and are never packaged as Python package data. The package provides the CLI and 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.
+- **Source-first architecture records**: Arc42 architecture records live under `.archledger/` and are the source of truth for `ARCHITECTURE.md`. `docs/architecture_taskledger_split.md` is a concise human-maintained summary. Skills stay outside both the Python package and the archledger build output.

taskledger-0.6.0/.archledger/profiles/arc42/sections/content-0003.md

@@ -0,0 +1,21 @@
+---
+schema_version: 4
+id: content-0003
+type: section
+section: context_and_scope
+title: Context and Scope
+order: 30
+status: accepted
+body_format: markdown
+kind: content
+version: 2
+---
+
+taskledger operates as a self-contained tool within a software development project. It interacts with four categories of external actors:
+
+1. **Agent harnesses** (pi, codex, chatgpt, and similar) 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`, `monitor`).
+3. **CI systems** may invoke taskledger for status checks, validation, snapshot/export operations, and `taskledger trace` bundles.
+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 source code. Taskledger does not depend on any external services, databases, or network endpoints. It reads the host project file system for search/symbol operations but does not modify files outside `.taskledger/`.

taskledger-0.6.0/.archledger/profiles/arc42/sections/content-0004.md

@@ -0,0 +1,40 @@
+---
+schema_version: 4
+id: content-0004
+type: section
+section: solution_strategy
+title: Solution Strategy
+order: 40
+status: accepted
+body_format: markdown
+kind: content
+version: 2
+---
+
+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, plan input validation, plan review, snapshot capture, dashboard assembly, and navigation.
+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, sidecar index rebuilds, migrations. Storage delegates low-level primitives to `ledgercore`.
+
+Key architectural choices:
+
+- **Markdown and YAML front matter as canonical format** — Each record (task, plan, run, lock, handoff, code review, etc.) is stored as a `.md` file with YAML front matter metadata and a Markdown body. This makes state human-readable and Git-friendly.
+- **Sidecar indexes as derived caches** — A `task_sidecars.json` summary index lives under `.taskledger/ledgers/<ledger_ref>/` and is rebuilt from canonical records. Per-task sidecar writes update the index in place.
+- **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, fsync, `os.replace`) from `ledgercore`.
+- **Editable plan input with preflight** — `taskledger plan check` parses editable plan input through `taskledger/services/plan_input.py`, applies worker-pipeline validation, and returns indexed issues before any plan upsert.
+- **Implementation workspace snapshots** — `taskledger/services/workspace_snapshot.py` captures Git and content snapshots when an implementation run starts, and `validate start` blocks when the workspace diverges. `implement snapshot refresh --reason ...` records new snapshots with an audit trail.
+- **Opaque cross-ledger references** — Task refs, plan versions, file links, and external handoff targets are stored as opaque strings. Taskledger does not interpret ledgercore global refs, archledger IDs, or other external system identifiers.
+- **Read-model reuse** — `view`, `status`, `tree`, and `monitor` consume service-level read models. These presentations are read-only and do not bypass lifecycle services.
+
+## Maintenance
+
+`ARCHITECTURE.md` in the repository root is generated from archledger source records. Do not edit it directly.
+
+- **Edit**: `.archledger/profiles/arc42/sections/*.md` for section content, `.archledger/records/**/*.md` for individual records.
+- **Regenerate**: Run `archledger build` to regenerate `ARCHITECTURE.md`.
+- **Verify**: Run `archledger check` and `pytest -q 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.md` is a concise human-maintained summary.

taskledger-0.6.0/.archledger/profiles/arc42/sections/content-0005.md

@@ -0,0 +1,24 @@
+---
+schema_version: 4
+id: content-0005
+type: section
+section: building_block_view
+title: Building Block View
+order: 50
+status: accepted
+body_format: markdown
+kind: content
+version: 2
+---
+
+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. Command families cover the canonical lifecycle plus `review`, `config`, task archive operations, transfer and sync, diagnostics, the `monitor` observer, and the `pipeline` overlay.
+2. **API Layer** — Provides stable Python function wrappers around service operations.
+3. **Services Layer** — Orchestrates lifecycle flows, plan input validation, plan review, handoffs, snapshot capture, navigation, doctor checks, worker pipelines, archival, code-review evidence, event logging, exports, dashboard assembly, and ready-work inspection.
+4. **Domain Layer** — Defines models, state machines, and policy decisions.
+5. **Storage Layer** — Manages file system persistence and layout. Low-level primitives (atomic writes, JSON, YAML, front matter, refs) are delegated to `ledgercore`.
+
+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, links, and code reviews. Mutations append immutable `TaskEvent` records to the ledger-level `events/` directory. Action and event logging is enabled by default; set `[event_logging] enabled = false` in `taskledger.toml` to disable new event records. Existing records remain readable regardless. A `task_sidecars.json` summary index under the same ledger path is maintained as a derived cache of sidecar counts and lock summaries.

taskledger-0.6.0/.archledger/profiles/arc42/sections/content-0006.md

@@ -0,0 +1,23 @@
+---
+schema_version: 4
+id: content-0006
+type: section
+section: runtime_view
+title: Runtime View
+order: 60
+status: accepted
+body_format: markdown
+kind: content
+version: 2
+---
+
+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. **Plan input flow** — `taskledger plan start` opens planning. `plan guidance` reports the active project planning profile. `plan template` writes a fresh plan skeleton; `plan check --file plan.md` runs the preflight parser in `taskledger/services/plan_input.py` without mutating state. `plan upsert --file plan.md` (or `--from-answers`) persists the plan; `plan lint --version N` surfaces blocking issues; `plan review --version N` produces the approval brief; `plan accept --version N --note ...` records the user-only decision.
+3. **Implementation workspace snapshot** — `implement start` captures a Git and content snapshot in `taskledger/services/workspace_snapshot.py`. `validate start` blocks when the current workspace diverges from the implementation snapshot. `implement snapshot refresh --reason ...` records a new snapshot with an audit trail and is the normal recovery path when validation is blocked by snapshot mismatch.
+4. **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.
+5. **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.
+6. **Doctor checks** — Inspects lock/run consistency, front matter integrity, index staleness, and storage layout version. Reports diagnostics with severity, code, and repair hints.
+7. **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.
+8. **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.6.0/.archledger/profiles/arc42/sections/content-0007.md

@@ -0,0 +1,20 @@
+---
+schema_version: 4
+id: content-0007
+type: section
+section: deployment_view
+title: Deployment View
+order: 70
+status: accepted
+body_format: markdown
+kind: content
+version: 2
+---
+
+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 `.taskledger/` directory. No daemon, no server.
+- **CI integration**: taskledger commands can be run in CI pipelines for status checks, validation, snapshot and export operations, and `taskledger trace` bundles
+- **Agent integration**: Agent harnesses invoke taskledger CLI commands as subprocess calls

taskledger-0.6.0/.archledger/profiles/arc42/sections/content-0008.md

@@ -0,0 +1,24 @@
+---
+schema_version: 4
+id: content-0008
+type: section
+section: cross_cutting_concepts
+title: Cross-cutting Concepts
+order: 80
+status: accepted
+body_format: markdown
+kind: content
+version: 2
+---
+
+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. Error envelopes add `code`, `message`, `details`, and `remediation`.
+- **YAML front matter serialization**: All canonical records use YAML front matter (`---` delimited) for metadata and Markdown for body. Serialization and deserialization live in `taskledger/storage/frontmatter.py`, backed by `ledgercore`.
+- **Atomic file writes**: All file writes go through `ledgercore` atomic primitives (temp file, flush, fsync, `os.replace`, directory fsync) to prevent corruption.
+- **Action and event logging (default-on)**: Mutations append immutable `TaskEvent` records to the ledger-level `events/` directory under `.taskledger/ledgers/<ledger_ref>/`. Action and event logging is enabled by default; set `[event_logging] enabled = false` to disable new records. Existing records remain readable. Source: `taskledger/storage/events.py`, `taskledger/services/task_events.py`, `taskledger/domain/event.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**: Task refs, plan versions, file links, and handoff targets remain opaque strings. Taskledger does not interpret ledgercore global refs, archledger IDs, SpecWeave feature paths, or other external system identifiers.
+- **Read-model reuse**: `view`, `status`, `tree`, and `monitor` commands consume service-level read models. These presentations are read-only and do not bypass lifecycle services.
+- **Editable plan input**: `taskledger plan check` is a pure preflight parser in `taskledger/services/plan_input.py`. It rejects malformed YAML, normalizes the `description` alias to `text`, and surfaces indexed issues before any plan upsert. `plan lint` runs additional structural checks; `plan review` renders the approval brief.

taskledger-0.6.0/.archledger/profiles/arc42/sections/content-0009.md

@@ -0,0 +1,21 @@
+---
+schema_version: 4
+id: content-0009
+type: section
+section: architecture_decisions
+title: Architecture Decisions
+order: 90
+status: accepted
+body_format: markdown
+kind: content
+version: 2
+---
+
+Key architecture decisions documented as ADR records:
+
+- **ADR-1**: Markdown and YAML front matter as canonical format (not JSON, not SQLite)
+- **ADR-2**: Sidecar summary index as derived rebuildable cache (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.6.0/.archledger/profiles/arc42/sections/content-0010.md

@@ -0,0 +1,22 @@
+---
+schema_version: 4
+id: content-0010
+type: section
+section: quality_requirements
+title: Quality Requirements
+order: 100
+status: accepted
+body_format: markdown
+kind: content
+version: 2
+---
+
+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.
+- **Editable plan input preflight**: `taskledger plan check` returns a structured payload with `passed`, `summary`, indexed `issues`, and parsed counts. Lint and review are gate layers; preflight catches them earlier.
+- **Implementation snapshot fidelity**: `validate start` blocks when the current workspace diverges from the implementation snapshot. `implement snapshot refresh --reason ...` is the only sanctioned recovery path and records an audit trail.

taskledger-0.6.0/.archledger/profiles/arc42/sections/content-0011.md

@@ -0,0 +1,21 @@
+---
+schema_version: 4
+id: content-0011
+type: section
+section: risks_and_technical_debt
+title: Risks and Technical Debt
+order: 110
+status: accepted
+body_format: markdown
+kind: content
+version: 2
+---
+
+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 and query operations because the `task_sidecars.json` summary index is rebuilt from file scans on miss and updated on writes. The per-task sidecar index keeps the common read path fast but does not eliminate directory overhead.
+- **Migration surface between storage versions**: The storage layout is currently v3 (`TASKLEDGER_STORAGE_LAYOUT_VERSION` in `taskledger/domain/states.py`). Migration code in `taskledger/storage/migrations.py` adds complexity. Future format changes must maintain backward compatibility or ship migration steps.
+- **Service boundary erosion**: Some service modules (notably `tasks.py` and a few focused modules) have grown large. The service layer has no formal interface contracts; boundaries are enforced by convention and the `tests/test_service_boundaries.py` whitelist in `docs/service_boundary_whitelist.md`.
+- **Implementation snapshot drift**: Workspace snapshots are a strong invariant but require explicit refresh after environment changes. `taskledger next-action` and `validate start` surface mismatch diagnostics; the recovery path is `implement snapshot refresh --reason ...`.
+- **Editable plan input compatibility**: `description` is accepted as an alias for `text` on acceptance criteria; strict mode promotes unknown-field findings to errors to prevent silent structured-data loss.
+- **Growing dependency surface**: The runtime dependency set is small (`typer`, `click`, `PyYAML`, `tomli`, `ledgercore`) but new dependencies must be justified by core features rather than optional presentations.

taskledger-0.6.0/.archledger/profiles/arc42/sections/content-0012.md

@@ -0,0 +1,14 @@
+---
+schema_version: 4
+id: content-0012
+type: section
+section: glossary
+title: Glossary
+order: 120
+status: accepted
+body_format: markdown
+kind: content
+version: 2
+---
+
+Domain terms used throughout taskledger. The full glossary lives in the per-term `glossary-NNNN` records under `.archledger/records/glossary/`. Each term is stored as a record with `term`, `definition`, and reference metadata rather than in this section body.

taskledger-0.6.0/.archledger/records/building_blocks/block-0029.md

@@ -0,0 +1,37 @@
+---
+schema_version: 4
+id: block-0029
+type: white_box
+title: taskledger system
+status: proposed
+section: building_block_view
+level: 1
+parent: null
+order: 10
+diagram: null
+quality_characteristics: []
+tags: []
+body_format: markdown
+kind: block
+version: 2
+---
+
+## Motivation
+
+taskledger decomposes into core layers with downward dependency flow. This isolates persistence, business rules, orchestration, and public interfaces. Low-level persistence primitives are delegated to `ledgercore`, but the layer boundary above it stays in `taskledger/storage/`.
+
+## Contained building blocks
+
+1. **CLI Layer** (`block-0030`) — Typer commands, argument parsing, output rendering
+2. **API Layer** (`block-0031`) — Stable Python function wrappers
+3. **Services Layer** (`block-0032`) — Lifecycle orchestration, handoffs, plan input, plan review, snapshots, inspection
+4. **Domain Layer** (`block-0033`) — Models, state machines, policies (no I/O)
+5. **Storage Layer** (`block-0034`) — File system persistence, atomic writes, sidecar index, layout
+
+## Important interfaces
+
+- CLI -> Services: function calls with `workspace_root` plus task references
+- Services -> Domain: policy functions take `PolicyContext`, return `Decision`
+- Services -> Storage: record CRUD operations through `task_store.py` functions and the sidecar index
+- API -> Services: direct function calls mirroring CLI behavior
+- Storage -> ledgercore: atomic I/O, JSON I/O, YAML I/O, front matter parsing, cross-ledger ref parsing

taskledger-0.6.0/.archledger/records/building_blocks/block-0030.md

@@ -0,0 +1,23 @@
+---
+schema_version: 4
+id: block-0030
+type: black_box
+title: CLI Layer
+status: accepted
+section: building_block_view
+level: 1
+parent: block-0029
+order: 10
+interfaces: []
+location: []
+fulfilled_requirements: []
+risks: []
+tags: []
+body_format: markdown
+kind: block
+version: 2
+---
+
+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 and sync, diagnostics, the `monitor` observer, the `pipeline` overlay, and `ref` cross-ledger helpers.
+
+Source refs: `taskledger/cli.py`, `taskledger/cli_common.py`, `taskledger/command_inventory.py`, and the focused `taskledger/cli_*.py` registration modules.

taskledger-0.6.0/.archledger/records/building_blocks/block-0031.md

@@ -0,0 +1,21 @@
+---
+schema_version: 4
+id: block-0031
+type: black_box
+title: API Layer
+status: proposed
+section: building_block_view
+level: 1
+parent: block-0029
+order: 20
+interfaces: []
+location: []
+fulfilled_requirements: []
+risks: []
+tags: []
+body_format: markdown
+kind: block
+version: 2
+---
+
+Stable Python function wrappers under `taskledger/api/` that mirror the CLI surface for programmatic use. Each module (tasks, plans, handoff, locks, task runs, sync, reviews, search, etc.) exposes functions that accept workspace paths and return dictionaries matching the JSON output shape. The API layer calls Services directly.

taskledger-0.6.0/.archledger/records/building_blocks/block-0032.md

@@ -0,0 +1,21 @@
+---
+schema_version: 4
+id: block-0032
+type: black_box
+title: Services Layer
+status: proposed
+section: building_block_view
+level: 1
+parent: block-0029
+order: 30
+interfaces: []
+location: []
+fulfilled_requirements: []
+risks: []
+tags: []
+body_format: markdown
+kind: block
+version: 2
+---
+
+Orchestrates lifecycle flows by coordinating Domain policies and records with Storage. Focused services own planning (`planning_flow.py`, `plan_input.py`, `plan_review.py`, `plan_lint.py`, `plan_materialization.py`), implementation (`implementation_flow.py`, `workspace_snapshot.py`), validation (`validation_flow.py`), handoffs (`handoff.py`, `handoff_lifecycle.py`, `worker_context.py`), doctor checks (`doctor.py`, `doctor_checks/`), navigation (`navigation.py`, `next_action_model.py`, `next_action_payload.py`, `ready_work.py`), worker pipelines (`worker_pipeline.py`, `workflow_guidance.py`), archival (`task_archive.py`, `task_export.py`, `task_reports.py`), code-review evidence (`code_review.py`), event logging (`task_events.py`, `agent_transcripts.py`, `agent_logging.py`, `change_tracking.py`, `check_tracking.py`, `event_logging.py`), exports and dashboard assembly (`dashboard.py`, `tree.py`, `monitor.py`). `tasks.py` remains the compatibility-oriented lifecycle facade while ownership is progressively extracted into focused modules.

taskledger-0.6.0/.archledger/records/building_blocks/block-0033.md

@@ -0,0 +1,21 @@
+---
+schema_version: 4
+id: block-0033
+type: black_box
+title: Domain Layer
+status: proposed
+section: building_block_view
+level: 1
+parent: block-0029
+order: 40
+interfaces: []
+location: []
+fulfilled_requirements: []
+risks: []
+tags: []
+body_format: markdown
+kind: block
+version: 2
+---
+
+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. The canonical storage layout version is `TASKLEDGER_STORAGE_LAYOUT_VERSION` in `taskledger/domain/states.py`.

taskledger-0.6.0/.archledger/records/building_blocks/block-0034.md

@@ -0,0 +1,21 @@
+---
+schema_version: 4
+id: block-0034
+type: black_box
+title: Storage Layer
+status: proposed
+section: building_block_view
+level: 1
+parent: block-0029
+order: 50
+interfaces: []
+location: []
+fulfilled_requirements: []
+risks: []
+tags: []
+body_format: markdown
+kind: block
+version: 2
+---
+
+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. A `task_sidecars.json` summary index is maintained as a derived cache; per-task sidecar writes call `update_sidecar_summary` from `taskledger/storage/sidecar_index.py` so the read path does not need a full rescan. Atomic write primitives, YAML I/O, front matter parsing, and ref parsing are delegated to `ledgercore`. Action and 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.6.0/.archledger/records/concepts/concept-0040.md

@@ -0,0 +1,15 @@
+---
+schema_version: 4
+id: concept-0040
+type: concept
+title: Actor metadata and role semantics
+status: proposed
+section: cross_cutting_concepts
+order: 10
+applies_to: []
+body_format: markdown
+kind: concept
+version: 2
+---
+
+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, dependency 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`).