How to use the task and QA layer

How-to: use the task & QA layer

What makes cie not-just-a-code-graph: tasks, test results, coverage and PRD hierarchy live in the same store as the code.

Where things live

Embedded mode keeps three files under <root>/.cie/: graph.db (code), tasks.db (tasks + test results + coverage), hierarchy.db (PRD → task hierarchy). Disable per store with --no-task-tracking / --no-hierarchy (the tools then return honest unavailable envelopes).

The loop

1. Plan tasks: push_tasks — write task records against file paths/symbols.
2. Ask what's pending: tasks:pending — the agent's worklist.
3. Record proof: record_test_result (pass/fail per test, per run), record_coverage_snapshot (per-file coverage).
4. Ask the traceability question: traceability_chain — task → code → test → result in one answer; traceability_orphans finds code with no test and no contract (the honest gaps).

Why this is the differentiator

No other surveyed code-graph tool answers "which files implement this task, and are they tested?" as one query — they're pure retrieval. Traceability is also what the HTML snapshot surfaces ("Task & test chains", "Orphans: no test, no contract").

Honest scope

Tasks are per-project (per store). Cross-repo task graphs are roadmap R28, gated on a real multi-repo user.

From the README (migrated, verified at v0.1.4)

Task & PRD-hierarchy layer (tasks.py, task_repository.py, embedded_task_repository.py, hierarchy.py)

• AtomicTask / AtomicTaskBatch (pydantic, schema-versioned at ingest), with status/attempts write-back, artifacts, repair events, dependency cycles validation, coverage validation, API-contract validation.
• Neo4jTaskRepository (real write-behind entity cache, cie.graph_cache) or EmbeddedTaskRepository (SQLite, zero-config — same TaskRepository protocol, same plan_push validation code, no Neo4j) — NullTaskRepository remains available as an explicit opt-out.
• hierarchy.py: stores/traverses a PRD tree (Module → Feature → Workflow → UseCase → UserStory → REALIZED_BY AtomicTask), APOC-free Cypher — Neo4j only, not yet ported to the embedded backend (its three tools — prd_coverage/prd_orphans/prd_traceability_chain — call cie.factory.get_hierarchy_repo directly). CLI: hierarchy:push, hierarchy:children, hierarchy:lineage.