context-rail 0.1.0__py3-none-any.whl

context_rail/__init__.py

@@ -0,0 +1,3 @@
+"""Context Rail — agentic task-management that keeps your project on rails."""
+
+__version__ = "0.1.0"

context_rail/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running as python -m context_rail."""
+from .cli import main
+
+main()

context_rail/autonomy/__init__.py

@@ -0,0 +1,85 @@
+"""Context Rail autonomy subpackage — contracts, rail checks, PDCA cycles, and run orchestration."""
+
+from ._runtime import (
+    Blocker,
+    BlockerLayer,
+    BlockerSeverity,
+    RuntimeCheckReport,
+    runtime_check,
+)
+
+from ._contracts import (
+    CONTRACT_FIELDS,
+    _contract_digest,
+    _json_dumps,
+    _json_load,
+    _project_exists,
+    _row_contract,
+    _row_cycle,
+    _snapshot_from_draft,
+    _task_row,
+    active_plan_contract,
+    apply_contract_defaults,
+    apply_contract_edits,
+    contract_review_lines,
+    create_plan_contract,
+    default_autonomy_policy,
+    default_drift_rules,
+    default_evidence_rules,
+    default_quality_contract,
+    default_rail_check_policy,
+    default_stop_rules,
+)
+from ._rails import (
+    _completed_task_count,
+    _create_default_rail_policies,
+    _pending_due_checks,
+    _policy_row,
+    _rail_cursor_snapshot,
+    _record_due_rail_checks,
+    build_rail_check_packet,
+    collect_rail_context,
+    create_agent_rail_policy,
+    create_default_rail_policies,
+    detect_due_rail_checks,
+    evaluate_rail_check,
+    list_rail_policies,
+    record_rail_check,
+    resolve_rail_policies,
+)
+from ._drift import (
+    compute_plan_drift,
+    detect_decision_conflicts,
+)
+from ._pdca import (
+    _active_run_for_task,
+    _cycle_evidence,
+    _cycle_for_task,
+    attach_activity_to_active_cycle,
+    check_cycle,
+    handle_task_blocked,
+    handle_task_done,
+    precheck_task_done,
+    record_do,
+    record_evidence,
+)
+from ._runs import (
+    _active_cycle_for_task,
+    _parse_sqlite_datetime,
+    _row_run,
+    _select_next_task,
+    active_autonomy_run,
+    autonomy_gate,
+    autonomy_next,
+    autonomy_record,
+    autonomy_status,
+    build_execution_packet,
+    ensure_pdca_cycle_for_task,
+    execution_packet_for_task,
+    latest_autonomy_run,
+    lease_limit_report,
+    phase_gate_report,
+    resume_autonomy_run,
+    start_autonomy_run,
+    stop_run_for_user,
+)

context_rail/autonomy/_contracts.py

@@ -0,0 +1,487 @@
+"""Plan contract defaults, editing, persistence, and snapshots."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import sqlite3
+import uuid
+from pathlib import Path
+from typing import Any
+
+from ..db import get_db, init_db, load_state, log_activity, save_state, transaction
+
+
+def _create_default_rail_policies(conn: sqlite3.Connection, project_id: str, contract: dict[str, Any]) -> list[dict[str, Any]]:
+    from ._rails import _create_default_rail_policies as _impl
+    return _impl(conn, project_id, contract)
+
+
+CONTRACT_FIELDS = {
+    "quality_contract",
+    "autonomy_policy",
+    "rail_check_policy",
+    "stop_rules",
+    "drift_rules",
+    "evidence_rules",
+}
+
+
+def default_quality_contract() -> dict[str, Any]:
+    return {
+        "good_feels_like": [
+            "Goal-first, not task-first",
+            "Dense but readable",
+            "Clear next action, blockers, and review state",
+        ],
+        "reference_examples": [],
+        "non_negotiables": [
+            "No hidden approval state",
+            "No task-by-task user babysitting",
+            "User-visible gates for meaningful direction changes",
+        ],
+        "acceptance_evidence": [
+            "tests_pass_or_gap_recorded",
+            "plan_alignment_checked",
+        ],
+        "quality_floor": [
+            "No broken primary flow",
+            "No invisible next action",
+            "No unchecked plan drift",
+        ],
+    }
+
+
+def default_autonomy_policy() -> dict[str, Any]:
+    return {
+        "codex_can_decide": [
+            "Implementation details inside approved scope",
+            "Small bug fixes",
+            "Documentation and cleanup",
+            "Tests and verification steps",
+        ],
+        "codex_must_stop_for": [
+            "Product direction change",
+            "Major UX direction change",
+            "Architecture change",
+            "Scope expansion",
+            "Missing required quality evidence",
+            "Conflicting decisions",
+        ],
+        "max_cycles_without_user": 10,
+        "phase_gate_required": True,
+        "lease": {
+            "scope": "phase",
+            "max_cycles": 10,
+            "max_minutes": 120,
+            "visible_gate": "phase",
+        },
+    }
+
+
+def default_rail_check_policy() -> dict[str, Any]:
+    return {
+        "default_every_completed_tasks": 5,
+        "also_check_on": [
+            "path_complete",
+            "goal_progress",
+            "goal_complete",
+            "before_phase_change",
+            "agent_lane_violation",
+            "decision_changed",
+            "evidence_missing",
+            "dependency_risk",
+            "scope_drift",
+            "quality_drift",
+        ],
+        "user_defined_paths": [],
+    }
+
+
+def default_stop_rules() -> list[dict[str, Any]]:
+    return [
+        {
+            "id": "scope_expansion",
+            "severity": "hard",
+            "condition": "new_task_outside_plan",
+            "message": "New work is outside the approved plan contract.",
+            "required_action": "user_gate",
+        },
+        {
+            "id": "missing_required_evidence",
+            "severity": "hard",
+            "condition": "required_evidence_missing",
+            "message": "Required quality evidence is missing.",
+            "required_action": "collect_evidence_or_user_gate",
+        },
+    ]
+
+
+def default_drift_rules() -> list[dict[str, Any]]:
+    return [
+        {"id": "unplanned_inside_phase", "score": 1, "condition": "unplanned_task_inside_current_phase"},
+        {"id": "unplanned_outside_phase", "score": 3, "condition": "unplanned_task_outside_current_phase"},
+        {"id": "direction_changed", "score": 5, "condition": "product_or_architecture_direction_changed"},
+        {"id": "non_negotiable_violated", "score": 6, "condition": "quality_contract_non_negotiable_violated"},
+    ]
+
+
+def default_evidence_rules() -> list[dict[str, Any]]:
+    return [
+        {"id": "plan_alignment", "scope": "cycle", "required": True, "kind": "manual_check",
+         "hint": "summary must reference a verifiable artifact (path or URL)"},
+        {"id": "tests_or_reason", "scope": "phase", "required": True, "kind": "test",
+         "hint": "evidence must include metadata.falsifier (>=15 chars)"},
+        {"id": "phase_report", "scope": "phase", "required": True, "kind": "manual_check",
+         "hint": "summary must reference a verifiable artifact"},
+    ]
+
+
+def apply_contract_defaults(draft: dict[str, Any]) -> dict[str, Any]:
+    """Ensure a draft contains the user-reviewable autonomy contract fields."""
+    draft.setdefault("quality_contract", default_quality_contract())
+    draft.setdefault("autonomy_policy", default_autonomy_policy())
+    draft.setdefault("rail_check_policy", default_rail_check_policy())
+    draft.setdefault("stop_rules", default_stop_rules())
+    draft.setdefault("drift_rules", default_drift_rules())
+    draft.setdefault("evidence_rules", default_evidence_rules())
+    return draft
+
+
+def apply_contract_edits(draft: dict[str, Any], edits: dict[str, Any]) -> dict[str, Any]:
+    """Apply review-time edits to contract fields."""
+    for field in CONTRACT_FIELDS:
+        if field in edits:
+            draft[field] = edits[field]
+    return apply_contract_defaults(draft)
+
+
+def contract_review_lines(draft: dict[str, Any]) -> list[str]:
+    """Return compact human-readable lines for contract fields in plan review."""
+    draft = apply_contract_defaults(draft)
+    quality = draft.get("quality_contract") or {}
+    autonomy = draft.get("autonomy_policy") or {}
+    rail = draft.get("rail_check_policy") or {}
+    lease = autonomy.get("lease") or {}
+    return [
+        "",
+        "Autonomy Contract:",
+        f"  Quality floor: {len(quality.get('quality_floor') or [])} item(s)",
+        f"  Non-negotiables: {len(quality.get('non_negotiables') or [])} item(s)",
+        f"  Can decide: {len(autonomy.get('codex_can_decide') or [])} item(s)",
+        f"  Must stop for: {len(autonomy.get('codex_must_stop_for') or [])} item(s)",
+        f"  Lease: {lease.get('scope', 'phase')} / {lease.get('max_cycles', autonomy.get('max_cycles_without_user', 0))} cycle(s)",
+        f"  Rail-check: every {rail.get('default_every_completed_tasks', 5)} completed task(s), "
+        f"{len(rail.get('also_check_on') or [])} trigger(s)",
+        f"  Evidence rules: {len(draft.get('evidence_rules') or [])} item(s)",
+    ]
+
+
+def _json_dumps(value: Any) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"))
+
+
+def _json_load(value: Any, fallback: Any) -> Any:
+    if value in (None, ""):
+        return fallback
+    if isinstance(value, (dict, list)):
+        return value
+    try:
+        return json.loads(value)
+    except (TypeError, json.JSONDecodeError):
+        return fallback
+
+
+def _row_cycle(row: sqlite3.Row | None) -> dict[str, Any] | None:
+    if not row:
+        return None
+    data = dict(row)
+    for field, fallback in (
+        ("plan_step", {}),
+        ("do_log", {}),
+        ("check_report", {}),
+        ("act_log", {}),
+        ("evidence_summary", {}),
+    ):
+        data[field] = _json_load(data.get(field), fallback)
+    return data
+
+
+def _task_row(conn: sqlite3.Connection, task_id: str) -> dict[str, Any] | None:
+    row = conn.execute(
+        "SELECT * FROM tasks WHERE id = ? AND deleted_at IS NULL",
+        (task_id,),
+    ).fetchone()
+    return dict(row) if row else None
+
+
+def _contract_digest(contract: dict[str, Any]) -> str:
+    blob = _json_dumps({
+        "goal": contract.get("goal", ""),
+        "quality_contract": contract.get("quality_contract", {}),
+        "autonomy_policy": contract.get("autonomy_policy", {}),
+        "rail_check_policy": contract.get("rail_check_policy", {}),
+        "stop_rules": contract.get("stop_rules", []),
+        "drift_rules": contract.get("drift_rules", []),
+        "evidence_rules": contract.get("evidence_rules", []),
+        "plan_snapshot": contract.get("plan_snapshot", {}),
+    })
+    return hashlib.sha256(blob.encode("utf-8")).hexdigest()
+
+
+def _snapshot_from_draft(draft: dict[str, Any]) -> dict[str, Any]:
+    phases = []
+    goals = []
+    tasks = []
+    for phase in draft.get("phases", []) or []:
+        phases.append({
+            "id": phase.get("id", ""),
+            "name": phase.get("name", ""),
+            "sort_order": phase.get("sort_order", 0),
+        })
+        for goal in phase.get("goals", []) or []:
+            goals.append({
+                "id": goal.get("id", ""),
+                "phase_id": phase.get("id", ""),
+                "title": goal.get("title", ""),
+                "priority": goal.get("priority", 0),
+            })
+            for task in goal.get("tasks", []) or []:
+                tasks.append({
+                    "id": task.get("id", ""),
+                    "phase_id": phase.get("id", ""),
+                    "goal_id": goal.get("id", ""),
+                    "title": task.get("title", ""),
+                    "priority": task.get("priority", 0),
+                })
+        for task in phase.get("unlinked_tasks", []) or []:
+            tasks.append({
+                "id": task.get("id", ""),
+                "phase_id": phase.get("id", ""),
+                "goal_id": task.get("goal_id") or "",
+                "title": task.get("title", ""),
+                "priority": task.get("priority", 0),
+            })
+    snapshot: dict[str, Any] = {
+        "scope": draft.get("_scope", "project"),
+        "level": draft.get("_level") or draft.get("level", ""),
+        "phases": phases,
+        "goals": goals,
+        "tasks": tasks,
+        "risks": draft.get("risks", []) or [],
+        "decisions": draft.get("decisions", []) or [],
+    }
+    if draft.get("markdown"):
+        snapshot["markdown"] = draft.get("markdown", "")
+    return snapshot
+
+
+def _project_exists(conn: sqlite3.Connection, project_id: str) -> bool:
+    row = conn.execute(
+        "SELECT id FROM projects WHERE id = ? AND COALESCE(deleted_at, '') = ''",
+        (project_id,),
+    ).fetchone()
+    return row is not None
+
+
+def _row_contract(row: sqlite3.Row | None) -> dict[str, Any] | None:
+    if not row:
+        return None
+    data = dict(row)
+    data["quality_contract"] = _json_load(data.get("quality_contract"), {})
+    data["autonomy_policy"] = _json_load(data.get("autonomy_policy"), {})
+    data["rail_check_policy"] = _json_load(data.get("rail_check_policy"), {})
+    data["stop_rules"] = _json_load(data.get("stop_rules"), [])
+    data["drift_rules"] = _json_load(data.get("drift_rules"), [])
+    data["evidence_rules"] = _json_load(data.get("evidence_rules"), [])
+    data["plan_snapshot"] = _json_load(data.get("plan_snapshot"), {})
+    return data
+
+
+def create_plan_contract(
+    project_id: str,
+    draft: dict[str, Any],
+    approved_by: str = "",
+    source_type: str = "plan_review",
+    source_id: str = "",
+) -> dict[str, Any] | None:
+    """Convert an approved draft into a durable plan contract.
+
+    Returns None when the project row is absent. That keeps legacy unit tests
+    with monkeypatched state from failing, while real approvals still persist.
+    """
+    conn = get_db()
+    init_db(conn)
+    draft = apply_contract_defaults(dict(draft))
+    try:
+        if not _project_exists(conn, project_id):
+            return None
+        latest = conn.execute(
+            "SELECT COALESCE(MAX(version), 0) as version FROM plan_contracts WHERE project_id = ?",
+            (project_id,),
+        ).fetchone()
+        version = int(latest["version"] or 0) + 1
+        contract = {
+            "id": str(uuid.uuid4()),
+            "project_id": project_id,
+            "source_type": source_type,
+            "source_id": source_id,
+            "title": draft.get("title") or draft.get("phase_name") or draft.get("goal") or "Approved plan",
+            "goal": draft.get("goal", ""),
+            "version": version,
+            "approved_by": approved_by,
+            "quality_contract": draft.get("quality_contract", {}),
+            "autonomy_policy": draft.get("autonomy_policy", {}),
+            "rail_check_policy": draft.get("rail_check_policy", {}),
+            "stop_rules": draft.get("stop_rules", []),
+            "drift_rules": draft.get("drift_rules", []),
+            "evidence_rules": draft.get("evidence_rules", []),
+            "plan_snapshot": draft.get("plan_snapshot") or _snapshot_from_draft(draft),
+        }
+        contract["digest"] = _contract_digest(contract)
+        with transaction(conn):
+            conn.execute(
+                """UPDATE plan_contracts
+                   SET status = 'superseded', updated_at = datetime('now')
+                   WHERE project_id = ? AND status = 'active' AND deleted_at IS NULL""",
+                (project_id,),
+            )
+            conn.execute(
+                """INSERT INTO plan_contracts (
+                     id, project_id, source_type, source_id, title, goal, status,
+                     version, approved_by, approved_at, quality_contract,
+                     autonomy_policy, rail_check_policy, stop_rules, drift_rules,
+                     evidence_rules, plan_snapshot, digest
+                   ) VALUES (?, ?, ?, ?, ?, ?, 'active', ?, ?, datetime('now'), ?, ?, ?, ?, ?, ?, ?, ?)""",
+                (
+                    contract["id"],
+                    project_id,
+                    source_type,
+                    source_id,
+                    contract["title"],
+                    contract["goal"],
+                    version,
+                    approved_by,
+                    _json_dumps(contract["quality_contract"]),
+                    _json_dumps(contract["autonomy_policy"]),
+                    _json_dumps(contract["rail_check_policy"]),
+                    _json_dumps(contract["stop_rules"]),
+                    _json_dumps(contract["drift_rules"]),
+                    _json_dumps(contract["evidence_rules"]),
+                    _json_dumps(contract["plan_snapshot"]),
+                    contract["digest"],
+                ),
+            )
+            policies = _create_default_rail_policies(conn, project_id, contract)
+            log_activity(
+                conn,
+                "project",
+                project_id,
+                "plan_contract_approved",
+                {"contract_id": contract["id"], "version": version, "rail_policies": [p["id"] for p in policies]},
+            )
+        state = load_state()
+        state["active_project_id"] = project_id
+        state["active_plan_contract_id"] = contract["id"]
+        if policies:
+            state["active_rail_policy_id"] = policies[0]["id"]
+        save_state(state)
+        return active_plan_contract(project_id)
+    finally:
+        conn.close()
+
+
+def active_plan_contract(project_id: str) -> dict[str, Any] | None:
+    conn = get_db()
+    init_db(conn)
+    try:
+        row = conn.execute(
+            """SELECT * FROM plan_contracts
+               WHERE project_id = ? AND status = 'active' AND deleted_at IS NULL
+               ORDER BY version DESC, created_at DESC LIMIT 1""",
+            (project_id,),
+        ).fetchone()
+        return _row_contract(row)
+    finally:
+        conn.close()
+
+
+# ---------------------------------------------------------------------
+# Task title validation (NCR-1)
+# ---------------------------------------------------------------------
+
+# Common English stopwords + frequent imperative verbs that happen to look
+# like code identifiers (PascalCase or lowercase) but aren't. Without this
+# filter, "Wire the new module to the editor" would extract "Wire", "new",
+# "the", "module" — three of which are noise.
+_TITLE_STOPWORDS: frozenset[str] = frozenset({
+    # articles, prepositions, conjunctions, pronouns
+    "the", "a", "an", "to", "and", "or", "of", "in", "on", "at", "for",
+    "with", "from", "by", "is", "are", "was", "were", "be", "been", "being",
+    "have", "has", "had", "do", "does", "did", "will", "would", "could",
+    "should", "may", "might", "must", "shall", "can",
+    "this", "that", "these", "those", "i", "you", "we", "they",
+    "he", "she", "it", "its", "their", "our", "your", "my",
+    # adverbs / quantifiers
+    "new", "old", "first", "last", "next", "prev", "previous",
+    "all", "any", "some", "no", "not", "only",
+    # common imperative verbs (lowercase form)
+    "wire", "add", "fix", "make", "update", "implement", "create", "build",
+    "test", "tests", "verify", "check", "run", "remove", "delete", "drop",
+    "migrate", "rename", "refactor", "clean", "cleanup",
+    "ship", "merge", "split", "merge", "land", "deploy",
+})
+
+
+def _extract_code_nouns(title: str) -> list[str]:
+    """Extract likely code-entity nouns from a task title.
+
+    Returns PascalCase (``[A-Z][a-zA-Z0-9]+``) and snake_case
+    (``[a-z][a-z0-9]*(_[a-z0-9]+)+``) tokens that aren't English stopwords.
+    Order is preserved, duplicates are removed (first occurrence wins).
+    """
+    pascal = re.findall(r"\b[A-Z][a-zA-Z0-9]+\b", title)
+    # Non-capturing group so re.findall returns the full match, not the last
+    # captured underscore-prefixed segment.
+    snake = re.findall(r"\b[a-z][a-z0-9]*(?:_[a-z0-9]+)+\b", title)
+    seen: set[str] = set()
+    result: list[str] = []
+    for n in pascal + snake:
+        if n.lower() in _TITLE_STOPWORDS:
+            continue
+        if n in seen:
+            continue
+        seen.add(n)
+        result.append(n)
+    return result
+
+
+def _find_unresolved_refs(title: str, src_root: str) -> dict[str, list[str]]:
+    """Check which code-noun tokens in ``title`` don't match anything in ``src_root``.
+
+    Returns ``{"resolved": [...], "unresolved": [...]}``. When ``src_root``
+    does not exist, both lists are empty (caller decides policy).
+    """
+    nouns = _extract_code_nouns(title)
+    src_path = Path(src_root)
+    if not src_path.exists():
+        return {"resolved": [], "unresolved": []}
+    # Build set of identifier-like tokens harvested from filenames under src/.
+    found: set[str] = set()
+    for p in src_path.rglob("*"):
+        if not p.is_file():
+            continue
+        stem = p.stem
+        if stem:
+            found.add(stem)
+        for token in re.findall(r"[A-Z][a-zA-Z0-9]+|[a-z][a-z0-9]*(?:_[a-z0-9]+)+", stem):
+            found.add(token)
+    resolved: list[str] = []
+    unresolved: list[str] = []
+    for n in nouns:
+        if n in found:
+            resolved.append(n)
+        else:
+            unresolved.append(n)
+    return {"resolved": resolved, "unresolved": unresolved}