dctracker 1.0.0__py3-none-any.whl

dct/core/checkpoints.py

@@ -0,0 +1,205 @@
+"""Checkpoint CRUD — acceptance criteria tied to items with ledger semantics."""
+
+from datetime import datetime, timezone
+
+import sqlalchemy as sa
+
+from dct.db import item_checkpoints, items, row_to_dict
+
+VALID_STATUSES = {"pending", "done", "rejected"}
+
+# Known checkpoint kinds. 'task' is the default and does NOT block resolve_item.
+# Any non-'task' value is treated as a gate — resolve_item refuses until done
+# or rejected. The set is intentionally open (see `kind` column docstring in
+# db.py) — OSS users may define custom gate kinds; the validator accepts any
+# non-empty string, the whitelist is advisory (warning for typos in future).
+KNOWN_KINDS = {"task", "dogfood", "security", "approval", "review", "cc-task"}
+
+
+def _validate_status(status: str) -> str:
+    if status not in VALID_STATUSES:
+        raise ValueError(f"Invalid status: '{status}'. Valid: {', '.join(sorted(VALID_STATUSES))}")
+    return status
+
+
+def _validate_kind(kind: str) -> str:
+    if not kind or not kind.strip():
+        raise ValueError("Checkpoint kind cannot be empty")
+    return kind
+
+
+def add_checkpoint(
+    engine: sa.Engine,
+    item_id: int,
+    text: str,
+    sort_order: int | None = None,
+    kind: str = "task",
+) -> dict:
+    """Create a checkpoint on an item.
+
+    Args:
+        kind: 'task' (default, non-blocking) or a gate kind:
+              - 'dogfood'  — user-facing feature awaiting fresh-session validation
+              - 'security' — security review required
+              - 'approval' — stakeholder sign-off
+              - 'review'   — code review
+              - 'cc-task'  — mirrored from Claude Code TaskCreate (non-blocking)
+              Any non-'task' kind blocks `resolve_item` until the checkpoint is
+              completed or rejected (reject = 'not applicable').
+    """
+    if not text or not text.strip():
+        raise ValueError("Checkpoint text cannot be empty")
+    _validate_kind(kind)
+
+    with engine.begin() as conn:
+        exists = conn.execute(
+            sa.select(items.c.id).where(items.c.id == item_id, items.c.deleted_at.is_(None))
+        ).first()
+        if not exists:
+            raise ValueError(f"Item #{item_id} not found")
+
+        if sort_order is None:
+            max_row = conn.execute(
+                sa.select(sa.func.max(item_checkpoints.c.sort_order))
+                .where(item_checkpoints.c.item_id == item_id, item_checkpoints.c.deleted_at.is_(None))
+            ).first()
+            max_order = (max_row[0] if max_row else None) or 0
+            sort_order = max_order + 10
+
+        row = conn.execute(
+            item_checkpoints.insert()
+            .values(item_id=item_id, text=text, sort_order=sort_order, kind=kind)
+            .returning(item_checkpoints)
+        ).first()
+        assert row is not None
+        return row_to_dict(row)
+
+
+def list_pending_gates(engine: sa.Engine, item_id: int) -> list[dict]:
+    """Return pending gate checkpoints (kind != 'task', status = 'pending') for item.
+    Used by resolve_item to block resolution until gates close. cc-task is
+    treated as non-gating even though kind != 'task' — it's a mirror class, not
+    a gate. Use the explicit filter in resolve_item rather than hardcoding here
+    so future gate kinds are captured by default.
+    """
+    with engine.begin() as conn:
+        rows = conn.execute(
+            sa.select(item_checkpoints)
+            .where(
+                item_checkpoints.c.item_id == item_id,
+                item_checkpoints.c.kind.notin_(["task", "cc-task"]),
+                item_checkpoints.c.status == "pending",
+                item_checkpoints.c.deleted_at.is_(None),
+            )
+            .order_by(item_checkpoints.c.sort_order)
+        ).fetchall()
+        return [row_to_dict(r) for r in rows]
+
+
+def list_checkpoints(
+    engine: sa.Engine,
+    item_id: int,
+    include_deleted: bool = False,
+    include_rejected: bool = False,
+) -> list[dict]:
+    """List checkpoints for an item.
+
+    Defaults hide rejected and deleted — the typical caller wants the active
+    TODO list (pending + done). Pass include_rejected=True for full audit
+    view (e.g. "what did we plan and abandon?"). Note: get_item() does NOT
+    use this filter — a single-item view always returns all checkpoints,
+    because the caller explicitly asked about that item.
+    """
+    with engine.begin() as conn:
+        q = (
+            sa.select(item_checkpoints)
+            .where(item_checkpoints.c.item_id == item_id)
+            .order_by(item_checkpoints.c.sort_order, item_checkpoints.c.created_at)
+        )
+        if not include_deleted:
+            q = q.where(item_checkpoints.c.deleted_at.is_(None))
+        if not include_rejected:
+            q = q.where(item_checkpoints.c.status != "rejected")
+        return [row_to_dict(r) for r in conn.execute(q)]
+
+
+def get_checkpoint(engine: sa.Engine, checkpoint_id: int) -> dict | None:
+    with engine.begin() as conn:
+        row = conn.execute(
+            sa.select(item_checkpoints).where(
+                item_checkpoints.c.id == checkpoint_id,
+                item_checkpoints.c.deleted_at.is_(None),
+            )
+        ).first()
+        return row_to_dict(row) if row else None
+
+
+def set_status(engine: sa.Engine, checkpoint_id: int, status: str) -> dict | None:
+    _validate_status(status)
+    now = datetime.now(timezone.utc)
+    with engine.begin() as conn:
+        result = conn.execute(
+            item_checkpoints.update()
+            .where(item_checkpoints.c.id == checkpoint_id, item_checkpoints.c.deleted_at.is_(None))
+            .values(status=status, updated_at=now)
+        )
+        if result.rowcount == 0:
+            return None
+    return get_checkpoint(engine, checkpoint_id)
+
+
+def update_text(engine: sa.Engine, checkpoint_id: int, text: str) -> dict | None:
+    if not text or not text.strip():
+        raise ValueError("Checkpoint text cannot be empty")
+    now = datetime.now(timezone.utc)
+    with engine.begin() as conn:
+        result = conn.execute(
+            item_checkpoints.update()
+            .where(item_checkpoints.c.id == checkpoint_id, item_checkpoints.c.deleted_at.is_(None))
+            .values(text=text, updated_at=now)
+        )
+        if result.rowcount == 0:
+            return None
+    return get_checkpoint(engine, checkpoint_id)
+
+
+def delete_checkpoint(engine: sa.Engine, checkpoint_id: int) -> bool:
+    with engine.begin() as conn:
+        result = conn.execute(
+            item_checkpoints.update()
+            .where(item_checkpoints.c.id == checkpoint_id, item_checkpoints.c.deleted_at.is_(None))
+            .values(deleted_at=datetime.now(timezone.utc))
+        )
+        return result.rowcount > 0
+
+
+def get_progress(engine: sa.Engine, item_id: int) -> dict:
+    """Compute checkpoint progress for an item.
+
+    Returns: {total, done, rejected, pending, active, percent}
+    - active = total - rejected (things that actually need to be done)
+    - percent = done / active * 100 (0 if active == 0)
+    """
+    with engine.begin() as conn:
+        rows = conn.execute(
+            sa.select(item_checkpoints.c.status, sa.func.count())
+            .where(item_checkpoints.c.item_id == item_id, item_checkpoints.c.deleted_at.is_(None))
+            .group_by(item_checkpoints.c.status)
+        ).fetchall()
+
+    counts = {"pending": 0, "done": 0, "rejected": 0}
+    for status, count in rows:
+        counts[status] = count
+
+    total = counts["pending"] + counts["done"] + counts["rejected"]
+    active = counts["pending"] + counts["done"]
+    percent = round(counts["done"] / active * 100) if active else 0
+
+    return {
+        "total": total,
+        "done": counts["done"],
+        "rejected": counts["rejected"],
+        "pending": counts["pending"],
+        "active": active,
+        "percent": percent,
+    }

dct/core/decisions.py

@@ -0,0 +1,238 @@
+"""Decision CRUD — ADRs, sprint amendments, inline plan decisions, open questions.
+
+A decision is a first-class record of an architectural / scope choice with
+its own lifecycle (proposed → accepted → superseded/rejected). It can be
+standalone (classic ADR file in docs/adr/) or anchored to a plan, a plan
+section, or a sprint — or several at once (multi-anchor via optional FKs).
+
+Spec §4.1 + §5.1 + §9.5.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+import sqlalchemy as sa
+
+from dct.core.ids import new_ulid
+from dct.core.projects import resolve_project_id
+from dct.db import decisions, row_to_dict
+
+VALID_KINDS = {"adr", "sprint_amendment", "inline_plan", "open_question"}
+VALID_STATUSES = {"proposed", "accepted", "superseded", "rejected"}
+
+
+def _validate(value: str, valid: set[str], field: str) -> str:
+    if value not in valid:
+        raise ValueError(f"Invalid {field}: '{value}'. Valid: {', '.join(sorted(valid))}")
+    return value
+
+
+def create_decision(
+    engine: sa.Engine,
+    project_slug: str,
+    kind: str,
+    title: str,
+    context: str | None = None,
+    decision: str | None = None,
+    consequences: str | None = None,
+    alternatives: str | None = None,
+    status: str = "proposed",
+    ref_code: str | None = None,
+    plan_id: int | None = None,
+    plan_section_id: int | None = None,
+    sprint_id: int | None = None,
+    source_file: str | None = None,
+    source_lines: str | None = None,
+    ulid: str | None = None,
+) -> dict:
+    _validate(kind, VALID_KINDS, "kind")
+    _validate(status, VALID_STATUSES, "status")
+    if not title or not title.strip():
+        raise ValueError("Decision title cannot be empty")
+
+    decision_ulid = ulid or new_ulid()
+    with engine.begin() as conn:
+        project_id = resolve_project_id(conn, project_slug)
+        if ref_code:
+            dup = conn.execute(
+                sa.select(decisions).where(
+                    decisions.c.project_id == project_id,
+                    decisions.c.ref_code == ref_code,
+                    decisions.c.deleted_at.is_(None),
+                )
+            ).first()
+            if dup:
+                raise ValueError(f"Decision with ref_code '{ref_code}' already exists in project")
+
+        row = conn.execute(
+            decisions.insert()
+            .values(
+                ulid=decision_ulid,
+                project_id=project_id,
+                kind=kind,
+                ref_code=ref_code,
+                title=title.strip(),
+                context=context,
+                decision=decision,
+                consequences=consequences,
+                alternatives=alternatives,
+                status=status,
+                source_file=source_file,
+                source_lines=source_lines,
+                plan_id=plan_id,
+                plan_section_id=plan_section_id,
+                sprint_id=sprint_id,
+            )
+            .returning(decisions)
+        ).first()
+        assert row is not None, "INSERT RETURNING must return a row"
+        return row_to_dict(row)
+
+
+def list_decisions(
+    engine: sa.Engine,
+    project_slug: str | None = None,
+    kind: str | None = None,
+    status: str | None = None,
+    plan_id: int | None = None,
+    sprint_id: int | None = None,
+    include_deleted: bool = False,
+) -> list[dict]:
+    with engine.begin() as conn:
+        q = sa.select(decisions).order_by(decisions.c.created_at.desc())
+        if project_slug:
+            q = q.where(decisions.c.project_id == resolve_project_id(conn, project_slug))
+        if kind:
+            q = q.where(decisions.c.kind == kind)
+        if status:
+            q = q.where(decisions.c.status == status)
+        if plan_id is not None:
+            q = q.where(decisions.c.plan_id == plan_id)
+        if sprint_id is not None:
+            q = q.where(decisions.c.sprint_id == sprint_id)
+        if not include_deleted:
+            q = q.where(decisions.c.deleted_at.is_(None))
+        return [row_to_dict(r) for r in conn.execute(q)]
+
+
+def get_decision(engine: sa.Engine, decision_id: int) -> dict | None:
+    with engine.begin() as conn:
+        row = conn.execute(
+            sa.select(decisions).where(
+                decisions.c.id == decision_id, decisions.c.deleted_at.is_(None)
+            )
+        ).first()
+        return row_to_dict(row) if row else None
+
+
+def get_decision_by_ulid(engine: sa.Engine, ulid: str) -> dict | None:
+    with engine.begin() as conn:
+        row = conn.execute(
+            sa.select(decisions).where(
+                decisions.c.ulid == ulid, decisions.c.deleted_at.is_(None)
+            )
+        ).first()
+        return row_to_dict(row) if row else None
+
+
+def get_decision_by_ref_code(
+    engine: sa.Engine, project_slug: str, ref_code: str
+) -> dict | None:
+    with engine.begin() as conn:
+        pid = resolve_project_id(conn, project_slug)
+        row = conn.execute(
+            sa.select(decisions).where(
+                decisions.c.project_id == pid,
+                decisions.c.ref_code == ref_code,
+                decisions.c.deleted_at.is_(None),
+            )
+        ).first()
+        return row_to_dict(row) if row else None
+
+
+def update_decision(engine: sa.Engine, decision_id: int, **kwargs) -> dict | None:
+    allowed = {
+        "title", "context", "decision", "consequences", "alternatives",
+        "status", "kind", "ref_code",
+        "plan_id", "plan_section_id", "sprint_id",
+        "source_file", "source_lines",
+    }
+    values: dict = {}
+    for k, v in kwargs.items():
+        if k not in allowed or v is None:
+            continue
+        if k == "kind":
+            _validate(v, VALID_KINDS, "kind")
+        elif k == "status":
+            _validate(v, VALID_STATUSES, "status")
+        values[k] = v
+    if not values:
+        raise ValueError("No valid fields to update")
+    values["updated_at"] = datetime.now(timezone.utc)
+
+    with engine.begin() as conn:
+        result = conn.execute(
+            decisions.update()
+            .where(
+                decisions.c.id == decision_id, decisions.c.deleted_at.is_(None)
+            )
+            .values(**values)
+        )
+        if result.rowcount == 0:
+            return None
+    return get_decision(engine, decision_id)
+
+
+def supersede_decision(
+    engine: sa.Engine, old_decision_id: int, new_decision_id: int
+) -> dict | None:
+    """Mark an older decision as superseded by a newer one.
+
+    Sets `status='superseded'` and `superseded_by=<new_id>` on the old row.
+    Does NOT touch the new row — caller is responsible for its state
+    (typically `status='accepted'` when the supersession happens).
+    """
+    if old_decision_id == new_decision_id:
+        raise ValueError("A decision cannot supersede itself")
+    now = datetime.now(timezone.utc)
+    with engine.begin() as conn:
+        # Verify both rows exist
+        old = conn.execute(
+            sa.select(decisions.c.id).where(
+                decisions.c.id == old_decision_id,
+                decisions.c.deleted_at.is_(None),
+            )
+        ).first()
+        if not old:
+            raise ValueError(f"Decision #{old_decision_id} not found")
+        new = conn.execute(
+            sa.select(decisions.c.id).where(
+                decisions.c.id == new_decision_id,
+                decisions.c.deleted_at.is_(None),
+            )
+        ).first()
+        if not new:
+            raise ValueError(f"Decision #{new_decision_id} not found")
+
+        result = conn.execute(
+            decisions.update()
+            .where(decisions.c.id == old_decision_id)
+            .values(status="superseded", superseded_by=new_decision_id, updated_at=now)
+        )
+        if result.rowcount == 0:
+            return None
+    return get_decision(engine, old_decision_id)
+
+
+def delete_decision(engine: sa.Engine, decision_id: int) -> bool:
+    now = datetime.now(timezone.utc)
+    with engine.begin() as conn:
+        result = conn.execute(
+            decisions.update()
+            .where(
+                decisions.c.id == decision_id, decisions.c.deleted_at.is_(None)
+            )
+            .values(deleted_at=now)
+        )
+        return result.rowcount > 0

dct/core/engine.py

@@ -0,0 +1,32 @@
+"""Engine bootstrap — the single config→engine→(optional)DDL helper.
+
+DRY extraction of the duplicated `load_config() -> get_engine() -> create_tables()`
+block that previously lived in both dct/server.py and dct/cli.py.
+
+`create=False` returns a usable Engine WITHOUT running any DDL. The v1 web
+viewer is strictly read-only and relies on this to guarantee it never mutates
+the schema (no create_tables, only SELECTs).
+"""
+
+import sqlalchemy as sa
+
+from dct.config import load_config
+from dct.db import get_engine, create_tables
+
+
+def bootstrap_engine(create: bool = True) -> sa.Engine:
+    """Build a SQLAlchemy Engine from dct config.
+
+    Args:
+        create: when True (default) run idempotent DDL via create_tables so the
+            schema exists. When False, skip ALL DDL — caller guarantees the DB
+            already exists (read-only consumers such as the web viewer).
+
+    Returns:
+        A configured sqlalchemy.Engine.
+    """
+    cfg = load_config()
+    engine = get_engine(cfg.database_url)
+    if create:
+        create_tables(engine)  # idempotent
+    return engine

dct/core/handoff.py

@@ -0,0 +1,151 @@
+"""Session handoff ledger — prompts left by one session for the next.
+
+Ledger semantics: never hard-deleted, multiple unconsumed rows per project
+allowed (parallel sessions, different scopes). Consumer marks consumed_at
+(history preserved) or deleted_at (soft discard).
+"""
+
+from datetime import datetime, timezone
+
+import sqlalchemy as sa
+
+from dct.db import session_handoffs, row_to_dict
+from dct.core.projects import resolve_project_id
+
+
+def create_handoff(
+    engine: sa.Engine,
+    project_slug: str,
+    prompt: str,
+    created_by: str,
+    scope: str | None = None,
+    context_summary: str | None = None,
+) -> dict:
+    if not prompt or not prompt.strip():
+        raise ValueError("Handoff prompt cannot be empty")
+    if not created_by or not created_by.strip():
+        raise ValueError("created_by cannot be empty — identify the session (model + timestamp)")
+
+    with engine.begin() as conn:
+        project_id = resolve_project_id(conn, project_slug)
+        row = conn.execute(
+            session_handoffs.insert()
+            .values(
+                project_id=project_id,
+                prompt=prompt,
+                context_summary=context_summary,
+                scope=scope,
+                created_by=created_by,
+            )
+            .returning(session_handoffs)
+        ).first()
+        assert row is not None
+        return row_to_dict(row)
+
+
+def list_handoffs(
+    engine: sa.Engine,
+    project_slug: str | None = None,
+    unconsumed_only: bool = True,
+) -> list[dict]:
+    with engine.begin() as conn:
+        q = sa.select(session_handoffs).where(session_handoffs.c.deleted_at.is_(None))
+        if project_slug:
+            project_id = resolve_project_id(conn, project_slug)
+            q = q.where(session_handoffs.c.project_id == project_id)
+        if unconsumed_only:
+            q = q.where(session_handoffs.c.consumed_at.is_(None))
+        q = q.order_by(session_handoffs.c.created_at.desc())
+        return [row_to_dict(r) for r in conn.execute(q)]
+
+
+def get_handoff(engine: sa.Engine, handoff_id: int) -> dict | None:
+    with engine.begin() as conn:
+        row = conn.execute(
+            sa.select(session_handoffs).where(
+                session_handoffs.c.id == handoff_id,
+                session_handoffs.c.deleted_at.is_(None),
+            )
+        ).first()
+        return row_to_dict(row) if row else None
+
+
+def consume_handoff(
+    engine: sa.Engine,
+    handoff_id: int,
+    consumed_by: str | None = None,
+) -> dict | None:
+    now = datetime.now(timezone.utc)
+    with engine.begin() as conn:
+        result = conn.execute(
+            session_handoffs.update()
+            .where(
+                session_handoffs.c.id == handoff_id,
+                session_handoffs.c.deleted_at.is_(None),
+                session_handoffs.c.consumed_at.is_(None),
+            )
+            .values(consumed_at=now, consumed_by=consumed_by)
+        )
+        if result.rowcount == 0:
+            return None
+    return get_handoff(engine, handoff_id)
+
+
+def delete_handoff(engine: sa.Engine, handoff_id: int) -> bool:
+    """Soft delete — preserves row for audit but hides from list_handoffs."""
+    with engine.begin() as conn:
+        result = conn.execute(
+            session_handoffs.update()
+            .where(
+                session_handoffs.c.id == handoff_id,
+                session_handoffs.c.deleted_at.is_(None),
+            )
+            .values(deleted_at=datetime.now(timezone.utc))
+        )
+        return result.rowcount > 0
+
+
+def update_handoff(
+    engine: sa.Engine,
+    handoff_id: int,
+    prompt: str | None = None,
+    scope: str | None = None,
+    context_summary: str | None = None,
+) -> dict | None:
+    """Amend an UNCONSUMED handoff in place — preserves id + created_at.
+
+    Only fields passed (not None) are changed; None means "leave unchanged".
+    Consumed or soft-deleted handoffs are immutable ledger entries: returns
+    None (no row matches the filter). Also returns None when the id does not
+    exist. This is the in-place alternative to the supersede pattern
+    (delete_handoff + create_handoff), so the next session sees the latest
+    draft without the id churning.
+
+    Raises ValueError if prompt is given but blank, or if no field is given.
+    """
+    if prompt is not None and not prompt.strip():
+        raise ValueError("Handoff prompt cannot be empty")
+
+    values: dict = {}
+    if prompt is not None:
+        values["prompt"] = prompt
+    if scope is not None:
+        values["scope"] = scope
+    if context_summary is not None:
+        values["context_summary"] = context_summary
+    if not values:
+        raise ValueError("Nothing to update — pass prompt, scope, or context_summary")
+
+    with engine.begin() as conn:
+        result = conn.execute(
+            session_handoffs.update()
+            .where(
+                session_handoffs.c.id == handoff_id,
+                session_handoffs.c.deleted_at.is_(None),
+                session_handoffs.c.consumed_at.is_(None),
+            )
+            .values(**values)
+        )
+        if result.rowcount == 0:
+            return None
+    return get_handoff(engine, handoff_id)

dct/core/ids.py

@@ -0,0 +1,25 @@
+"""Identifier helpers — ULID generation for plans/sections/checkpoints/decisions.
+
+Why ULID (not UUID4): time-sortable at millisecond granularity (newer rows
+sort later naturally in DB), shorter stringified form (26 chars vs 36),
+Crockford base32 so no I/L/O/U ambiguity. Strict ordering within one
+millisecond is NOT guaranteed — intra-plan ordering uses explicit sort_order
+columns instead.
+"""
+
+import re
+
+from ulid import ULID
+
+# Crockford base32 alphabet without I, L, O, U; 26 chars total.
+ULID_RE = re.compile(r"^[0-9A-HJKMNP-TV-Z]{26}$")
+
+
+def new_ulid() -> str:
+    """Generate a fresh ULID as a 26-char uppercase Crockford-base32 string."""
+    return str(ULID())
+
+
+def is_valid_ulid(value: str) -> bool:
+    """True iff `value` has the exact shape of a ULID — 26 Crockford-base32 chars."""
+    return bool(ULID_RE.fullmatch(value))