devtime-ei 0.1.0__py3-none-any.whl

devtime/intelligence/scoring.py

@@ -0,0 +1,99 @@
+"""Understanding Score and Understanding Debt (Builder Edition, Chapter 12).
+
+Scores must explain themselves or they are theater.
+
+Trust Repair (v0.0.6):
+  - Higher Understanding Score = better understanding. Understanding Debt is a
+    *label* (low/medium/high), never the same number as the score.
+  - Freshness is NOT measured in V0 (no git-history). It contributes zero points
+    and is reported as "not measured" rather than silently adding score.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from devtime.intelligence.claims import ConceptIntelligence
+from devtime.intelligence.evidence import EvidenceItem
+
+
+@dataclass
+class UnderstandingScore:
+    score: int
+    debt_label: str
+    causes: list[str] = field(default_factory=list)
+    how_to_reduce: list[str] = field(default_factory=list)
+    dimensions: dict[str, object] = field(default_factory=dict)
+
+
+def _clamp(value: float, low: float, high: float) -> float:
+    return max(low, min(high, value))
+
+
+def _evidence_quality(evidence: list[EvidenceItem]) -> float:
+    if not evidence:
+        return 0.0
+    weights = {"strong": 1.0, "medium": 0.6, "weak": 0.3, "contradictory": 0.0}
+    return sum(weights.get(e.strength, 0.0) for e in evidence) / len(evidence)
+
+
+def compute_understanding(ci: ConceptIntelligence) -> UnderstandingScore:
+    evidence = ci.evidence
+    kinds = {e.signal.kind for e in evidence}
+
+    concept_confidence = ci.concept.confidence
+    evidence_quality = _evidence_quality(evidence)
+    # Only corroborated decisions count toward understanding (see repository load).
+    decision_coverage = 1.0 if any(e.kind == "decision" for e in evidence) else 0.0
+    test_coverage_signal = (
+        1.0 if any(e.signal.kind == "test" and e.strength == "strong" for e in evidence)
+        else (0.4 if "test" in kinds else 0.0)
+    )
+    ownership_clarity = 0.0  # V0 has no confirmed owners yet.
+    contradiction_penalty = (
+        1.0 if any(e.strength == "contradictory" for e in evidence) else 0.0
+    )
+
+    # Weights sum to 100. Freshness is intentionally absent (not measured in V0).
+    score = 0.0
+    score += concept_confidence * 30
+    score += evidence_quality * 25
+    score += decision_coverage * 20
+    score += test_coverage_signal * 15
+    score += ownership_clarity * 10
+    score -= contradiction_penalty * 15
+    score = int(round(_clamp(score, 0, 100)))
+
+    causes: list[str] = []
+    how: list[str] = []
+    if decision_coverage == 0.0:
+        causes.append("missing or uncorroborated decision evidence")
+        how.append("Record a decision that matches the scanned implementation.")
+    if test_coverage_signal < 1.0:
+        causes.append("weak or missing behavior-specific tests")
+        how.append("Add or link a behavior-specific test.")
+    if ownership_clarity == 0.0:
+        causes.append("no confirmed owner")
+        how.append("Confirm a suggested reviewer or owner.")
+    if contradiction_penalty > 0.0:
+        causes.append("contradictory docs and code")
+        how.append("Resolve the conflict between documentation and implementation.")
+
+    # Debt is the inverse *label* of the score, never the numeric score itself.
+    debt_label = "low" if score >= 75 else "medium" if score >= 50 else "high"
+
+    return UnderstandingScore(
+        score=score,
+        debt_label=debt_label,
+        causes=causes,
+        how_to_reduce=how,
+        dimensions={
+            "concept_confidence": round(concept_confidence, 2),
+            "evidence_quality": round(evidence_quality, 2),
+            "decision_coverage": decision_coverage,
+            "test_coverage_signal": test_coverage_signal,
+            "ownership_clarity": ownership_clarity,
+            "freshness": "not measured in V0",
+            "contradiction_penalty": contradiction_penalty,
+        },
+    )

devtime/mcp/schemas.py

@@ -0,0 +1,39 @@
+"""MCP tool schemas (Full Book Appendix C; Builder Edition Chapter 16)."""
+
+from __future__ import annotations
+
+TOOLS = {
+    "read": [
+        "list_concepts",
+        "explain_concept",
+        "show_evidence",
+        "get_claims",
+        "get_decisions",
+        "get_understanding_debt",
+    ],
+    "context": [
+        "get_context_pack",
+        "get_onboarding_pack",
+        "get_risk_context",
+    ],
+    "review": [
+        "review_diff",
+        "check_sensitive_concepts",
+    ],
+    "write_later": [
+        "add_decision",
+        "challenge_claim",
+        "confirm_claim",
+    ],
+}
+
+DEFAULT_PERMISSIONS = {
+    "read_memory": True,
+    "read_evidence_metadata": True,
+    "read_source": False,
+    "generate_context_pack": True,
+    "review_diff": True,
+    "write_decisions": False,
+    "challenge_claims": False,
+    "export_memory": False,
+}

devtime/mcp/server.py

@@ -0,0 +1,35 @@
+"""MCP server description (Builder Edition, Chapter 16).
+
+V0 ships the tool surface, schemas, and permission model. The actual transport
+(stdio/socket via an MCP SDK) is wired in a later milestone; this module makes
+the read-only contract inspectable today.
+"""
+
+from __future__ import annotations
+
+import json
+
+from devtime.intelligence.context_pack import generate_context_pack  # noqa: F401
+from devtime.mcp import schemas
+
+
+def describe_server() -> str:
+    """Honest preview output (Trust Repair v0.0.6): no server is started, and no
+    bind address is shown, because the MCP transport is not implemented in V0."""
+    lines = [
+        "MCP transport is not implemented in V0.",
+        "No server was started.",
+        "This command is a preview of planned read-only MCP tools.",
+        "",
+        "Planned read tools:",
+    ]
+    lines += [f"  - {t}" for t in schemas.TOOLS["read"]]
+    lines += ["Planned context tools:"]
+    lines += [f"  - {t}" for t in schemas.TOOLS["context"]]
+    lines += ["Planned review tools:"]
+    lines += [f"  - {t}" for t in schemas.TOOLS["review"]]
+    return "\n".join(lines)
+
+
+def describe_permissions() -> str:
+    return json.dumps(schemas.DEFAULT_PERMISSIONS, indent=2)

devtime/mcp/tools.py

@@ -0,0 +1,90 @@
+"""MCP tool implementations (Builder Edition, Chapter 16).
+
+Read-only by default. Evidence ids and uncertainty are always included; full
+source is never returned.
+"""
+
+from __future__ import annotations
+
+from devtime.db import connection, repository
+from devtime.intelligence import concepts as concepts_mod
+from devtime.intelligence.context_pack import generate_context_pack
+from devtime.intelligence.scoring import compute_understanding
+
+
+def list_concepts(limit: int = 50) -> list[dict]:
+    conn = connection.connect()
+    try:
+        out = []
+        for ci in repository.load_all_concepts(conn)[:limit]:
+            out.append(
+                {
+                    "concept": ci.concept.name,
+                    "slug": ci.concept.slug,
+                    "confidence": concepts_mod.confidence_label(ci.concept.confidence),
+                }
+            )
+        return out
+    finally:
+        conn.close()
+
+
+def explain_concept(concept: str) -> dict:
+    conn = connection.connect()
+    try:
+        ci = repository.load_concept(conn, concept)
+        if ci is None:
+            return {"error": "concept_not_found", "suggested_tool": "list_concepts"}
+        us = compute_understanding(ci)
+        return {
+            "concept": ci.concept.name,
+            "confidence": {
+                "concept": concepts_mod.confidence_label(ci.concept.confidence),
+                "decision": "low" if not any(e.kind == "decision" for e in ci.evidence) else "high",
+            },
+            "claims": [
+                {
+                    "type": c.type,
+                    "text": c.text,
+                    "state": c.state,
+                    "confidence": round(c.confidence, 2),
+                    "evidence": [e.path for e in c.evidence if e.path],
+                }
+                for c in ci.claims
+                if c.type != "uncertainty"
+            ],
+            "uncertainty": [u.text for u in ci.uncertainties],
+            "understanding_score": us.score,
+            "human_review_required": bool(ci.uncertainties),
+        }
+    finally:
+        conn.close()
+
+
+def get_context_pack(concept: str, mode: str = "risk") -> dict:
+    conn = connection.connect()
+    try:
+        ci = repository.load_concept(conn, concept)
+        if ci is None:
+            return {"error": "concept_not_found", "suggested_tool": "list_concepts"}
+        pack = generate_context_pack(ci, mode=mode)
+        return {
+            "concept": pack.concept,
+            "mode": pack.mode,
+            "supported_claims": pack.supported_claims,
+            "decisions": pack.decisions,
+            "uncertainty": pack.uncertainty,
+            "do_not_change_without_review": pack.do_not_change,
+            "limited": pack.limited,
+            "tests_to_run": [
+                {"path": t.path, "reason": t.reason} for t in pack.tests_to_run
+            ],
+            "agent_guidance": pack.agent_guidance,
+            "privacy": {
+                "contains_source_excerpts": False,
+                "contains_file_paths": True,
+                "review_before_sharing": True,
+            },
+        }
+    finally:
+        conn.close()

devtime/output/json_export.py

@@ -0,0 +1,50 @@
+"""JSON / Markdown export of repository memory (Builder Edition, Chapter 4)."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from devtime.db import connection, repository
+from devtime.intelligence.scoring import compute_understanding
+
+
+def export_memory(fmt: str = "json", root: Path | None = None) -> str:
+    conn = connection.connect(root)
+    try:
+        items = repository.load_all_concepts(conn)
+        data = []
+        for ci in items:
+            us = compute_understanding(ci)
+            data.append(
+                {
+                    "concept": ci.concept.name,
+                    "slug": ci.concept.slug,
+                    "confidence": round(ci.concept.confidence, 2),
+                    "understanding_score": us.score,
+                    "debt": us.debt_label,
+                    "claims": [
+                        {"type": c.type, "text": c.text, "confidence": round(c.confidence, 2)}
+                        for c in ci.claims
+                    ],
+                    "uncertainty": [u.text for u in ci.uncertainties],
+                    "evidence": [
+                        {"kind": e.kind, "strength": e.strength, "path": e.path}
+                        for e in ci.evidence
+                    ],
+                }
+            )
+    finally:
+        conn.close()
+
+    if fmt == "markdown":
+        lines = ["# DevTime Repository Memory Export", ""]
+        for d in data:
+            lines.append(f"## {d['concept']} ({d['understanding_score']}/100, debt: {d['debt']})")
+            lines.append("Claims:")
+            lines += [f"- [{c['type']}] {c['text']}" for c in d["claims"]]
+            lines.append("Uncertainty:")
+            lines += [f"- {u}" for u in d["uncertainty"]] or ["- None"]
+            lines.append("")
+        return "\n".join(lines)
+    return json.dumps(data, indent=2)

devtime/output/markdown.py

@@ -0,0 +1,50 @@
+"""Rendering for risk review results (Trust Repair v0.0.6)."""
+
+from __future__ import annotations
+
+from devtime.intelligence.risk import (
+    STATE_FINDING,
+    STATE_NO_FINDINGS,
+    STATE_REVIEW_FAILED,
+    STATE_UNSUPPORTED,
+    RiskReview,
+)
+
+
+def render_risk_review(review: RiskReview) -> str:
+    if review.state == STATE_REVIEW_FAILED:
+        return (
+            "Risk review failed: Git could not read the diff.\n"
+            f"Reason: {review.reason or 'unknown'}"
+        )
+
+    if review.state == STATE_NO_FINDINGS:
+        return (
+            "DevTime Risk Review\n\n"
+            "No memory-aware risk findings for this diff.\n"
+            "Supported checks completed."
+        )
+
+    if review.state == STATE_UNSUPPORTED:
+        concepts = ", ".join(review.affected_concepts) or "a known concept"
+        return (
+            "DevTime Risk Review\n\n"
+            "Manual review required:\n"
+            f"Changed files are linked to {concepts}, but V0 has no specific rule "
+            "for this change class.\n"
+            "No supported risk rule evaluated this diff."
+        )
+
+    # STATE_FINDING
+    blocks = ["DevTime Risk Review", ""]
+    for f in review.findings:
+        blocks.append(f"Affected concept:\n  {f.concept}")
+        blocks.append(f"Finding ({f.severity}):\n  {f.text}")
+        if f.why_it_matters:
+            blocks.append(f"Why this matters:\n  {f.why_it_matters}")
+        if f.missing:
+            blocks.append("Missing:")
+            blocks += [f"  - {m}" for m in f.missing]
+        blocks.append(f"Suggested action:\n  {f.suggested_action}")
+        blocks.append("")
+    return "\n".join(blocks)

devtime/output/terminal.py

@@ -0,0 +1,208 @@
+"""Terminal output (Builder Edition, Chapter 4).
+
+The CLI is the first proof surface. Output shows what was learned, what evidence
+supports it, what is uncertain, and what to do next.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from rich.console import Console
+from rich.markup import escape
+
+from devtime import config, paths
+from devtime.db import connection, repository
+from devtime.intelligence import concepts as concepts_mod
+from devtime.intelligence.context_pack import generate_context_pack, render_markdown
+from devtime.intelligence.scoring import compute_understanding
+
+console = Console()
+
+
+def _require_init(root: Path | None = None) -> bool:
+    if not paths.is_initialized(root):
+        console.print("[red]DevTime is not initialized.[/red] Run [bold]dtc init[/bold] first.")
+        return False
+    return True
+
+
+def print_concepts(root: Path | None = None) -> None:
+    if not _require_init(root):
+        return
+    conn = connection.connect(root)
+    try:
+        items = repository.load_all_concepts(conn)
+        if not items:
+            console.print("No concepts detected yet. Run [bold]dtc scan[/bold].")
+            return
+        console.print("[bold]Detected concepts[/bold]\n")
+        for i, ci in enumerate(items, 1):
+            us = compute_understanding(ci)
+            ev_kinds = sorted({e.kind for e in ci.evidence})
+            console.print(f"{i}. [bold]{ci.concept.name}[/bold]")
+            console.print(
+                f"   confidence: {concepts_mod.confidence_label(ci.concept.confidence)}"
+            )
+            console.print(f"   evidence: {', '.join(ev_kinds) or 'none'}")
+            console.print(f"   debt: {us.debt_label}\n")
+    finally:
+        conn.close()
+
+
+def print_explanation(concept: str, root: Path | None = None) -> None:
+    if not _require_init(root):
+        return
+    conn = connection.connect(root)
+    try:
+        ci = repository.load_concept(conn, concept)
+        if ci is None:
+            console.print(f"[yellow]No concept found matching[/yellow] '{concept}'.")
+            console.print("Run [bold]dtc concepts[/bold] to see detected concepts.")
+            return
+        us = compute_understanding(ci)
+        console.print(f"[bold]Concept:[/bold] {ci.concept.name}\n")
+
+        console.print("[bold]Supported claims:[/bold]")
+        supported = [c for c in ci.claims if c.type != "uncertainty"]
+        if not supported:
+            console.print("  (none)")
+        for c in supported:
+            paths_str = ", ".join(dict.fromkeys(e.path for e in c.evidence if e.path)) or "n/a"
+            console.print(f"  - {escape(c.text)}")
+            console.print(
+                f"    [dim]type: {c.type}  confidence: {c.confidence:.2f}  "
+                f"evidence: {escape(paths_str)}[/dim]"
+            )
+
+        console.print("\n[bold]Uncertainty:[/bold]")
+        if not ci.uncertainties:
+            console.print("  (none)")
+        for u in ci.uncertainties:
+            console.print(f"  - {escape(u.text)}")
+
+        # Trust Repair: Understanding Score (higher = better); Debt is a label.
+        console.print(
+            f"\n[bold]Understanding Score:[/bold] {us.score} / 100"
+        )
+        console.print(f"[bold]Understanding Debt:[/bold] {us.debt_label}")
+        if us.causes:
+            console.print("causes:")
+            for cause in us.causes:
+                console.print(f"  - {cause}")
+        if us.how_to_reduce:
+            console.print("suggested next steps:")
+            for step in us.how_to_reduce:
+                console.print(f"  - {step}")
+    finally:
+        conn.close()
+
+
+def print_evidence(concept: str, root: Path | None = None) -> None:
+    if not _require_init(root):
+        return
+    conn = connection.connect(root)
+    try:
+        ci = repository.load_concept(conn, concept)
+        if ci is None:
+            console.print(f"[yellow]No concept found matching[/yellow] '{concept}'.")
+            return
+        console.print(f"[bold]Evidence for {ci.concept.name}[/bold]\n")
+        for e in ci.evidence:
+            loc = f" ({e.path})" if e.path else ""
+            console.print(f"- [{e.strength}] {escape(e.summary + loc)}")
+    finally:
+        conn.close()
+
+
+def print_debt(root: Path | None = None) -> None:
+    if not _require_init(root):
+        return
+    conn = connection.connect(root)
+    try:
+        items = repository.load_all_concepts(conn)
+        scored = sorted(
+            ((ci, compute_understanding(ci)) for ci in items),
+            key=lambda pair: pair[1].score,
+        )
+        console.print("[bold]Understanding Score and Debt[/bold]\n")
+        for ci, us in scored:
+            console.print(
+                f"[bold]{ci.concept.name}[/bold] - score {us.score}/100, debt {us.debt_label}"
+            )
+            for cause in us.causes:
+                console.print(f"  - {cause}")
+            console.print("")
+    finally:
+        conn.close()
+
+
+def print_context(concept: str, mode: str, root: Path | None = None) -> str | None:
+    if not _require_init(root):
+        return None
+    conn = connection.connect(root)
+    try:
+        ci = repository.load_concept(conn, concept)
+        if ci is None:
+            console.print(f"[yellow]No concept found matching[/yellow] '{concept}'.")
+            return None
+        pack = generate_context_pack(ci, mode=mode)
+        md = render_markdown(pack)
+        # markup=False so filesystem paths like calendar/[provider]/route.ts render literally.
+        console.print(md, markup=False)
+        # Persist the generated pack to memory.
+        repository_save_context_pack(conn, ci.concept.slug, mode, md)
+        return md
+    finally:
+        conn.close()
+
+
+def repository_save_context_pack(conn, concept_slug: str, mode: str, body: str) -> None:
+    import uuid
+    from datetime import datetime, timezone
+
+    conn.execute(
+        "INSERT INTO context_packs(id, concept_id, mode, body_markdown, metadata_json, created_at) "
+        "VALUES (?,?,?,?,?,?)",
+        (
+            f"CP-{uuid.uuid4().hex[:10]}",
+            concept_slug,
+            mode,
+            body,
+            "{}",
+            datetime.now(timezone.utc).isoformat(),
+        ),
+    )
+    conn.commit()
+
+
+def print_status(root: Path | None = None) -> None:
+    root = root or paths.repo_root()
+    initialized = paths.is_initialized(root)
+    cfg = config.load_config(root)
+    priv = cfg["privacy"]
+    mcp = cfg["mcp"]
+
+    last_scan = None
+    if initialized:
+        conn = connection.connect(root)
+        try:
+            last_scan = repository.last_scan_time(conn)
+        finally:
+            conn.close()
+
+    console.print("[bold]Repository:[/bold]")
+    console.print(f"  Initialized: {'yes' if initialized else 'no'}")
+    console.print(f"  Root: {root.resolve()}")
+    console.print("[bold]Storage:[/bold]")
+    console.print(f"  Local SQLite: {paths.db_path(root)}")
+    console.print("[bold]AI:[/bold]")
+    console.print(f"  {'Enabled' if priv['ai_enabled'] else 'Disabled'}")
+    console.print("[bold]Cloud:[/bold]")
+    console.print(f"  {'Enabled' if priv['cloud_enabled'] else 'Disabled'}")
+    console.print("[bold]Telemetry:[/bold]")
+    console.print(f"  {'On' if priv['telemetry_enabled'] else 'Off'}")
+    console.print("[bold]MCP:[/bold]")
+    console.print(f"  {'Enabled' if mcp['enabled'] else 'Stopped'}")
+    console.print("[bold]Last scan:[/bold]")
+    console.print(f"  {last_scan or 'never'}")

devtime/paths.py

@@ -0,0 +1,40 @@
+"""Local path helpers (Builder Edition, Chapter 5)."""
+
+from pathlib import Path
+
+DEV_DIR = ".devtime"
+DB_NAME = "devtime.sqlite"
+CONFIG_NAME = "config.yaml"
+IGNORE_NAME = ".devtimeignore"
+
+
+def repo_root() -> Path:
+    return Path.cwd()
+
+
+def devtime_dir(root: Path | None = None) -> Path:
+    return (root or repo_root()) / DEV_DIR
+
+
+def db_path(root: Path | None = None) -> Path:
+    return devtime_dir(root) / DB_NAME
+
+
+def config_path(root: Path | None = None) -> Path:
+    return devtime_dir(root) / CONFIG_NAME
+
+
+def ignore_path(root: Path | None = None) -> Path:
+    return (root or repo_root()) / IGNORE_NAME
+
+
+def backups_dir(root: Path | None = None) -> Path:
+    return devtime_dir(root) / "backups"
+
+
+def logs_dir(root: Path | None = None) -> Path:
+    return devtime_dir(root) / "logs"
+
+
+def is_initialized(root: Path | None = None) -> bool:
+    return db_path(root).exists()