context-rail 0.2.2__tar.gz → 0.2.4__tar.gz

{context_rail-0.2.2/src/context_rail.egg-info → context_rail-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: context-rail
-Version: 0.2.2
+Version: 0.2.4
 Summary: Context Rail — agentic task-management that keeps your project on rails.
 License: MIT
 Project-URL: Repository, https://github.com/nguyenhoanhson797/Context-Rail

{context_rail-0.2.2 → context_rail-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "context-rail"
-version = "0.2.2"
+version = "0.2.4"
 description = "Context Rail — agentic task-management that keeps your project on rails."
 readme = "README.md"
 license = {text = "MIT"}

{context_rail-0.2.2 → context_rail-0.2.4}/src/context_rail/cli.py

@@ -5,7 +5,7 @@ import json
 import sys
 from pathlib import Path
 
-from .db import DB_DIR, DB_PATH, STATE_PATH, get_db, init_db, load_state
+from .db import DB_DIR, DB_PATH, STATE_PATH, get_db, init_db, load_state, resolve_workspace_project, write_local_project, find_local_project
 
 
 
@@ -85,9 +85,22 @@ def ensure_agents_md(project_id: str = "", project_name: str = "") -> None:
         agents_path.write_text(existing.rstrip() + "\n\n" + wrapped, encoding="utf-8")
 
 
+def _ensure_gitignore_has_context_rail(cwd: str) -> None:
+    """Add .context-rail to .gitignore if a .gitignore exists but doesn't mention it."""
+    gi_path = Path(cwd) / ".gitignore"
+    if not gi_path.is_file():
+        return
+    content = gi_path.read_text(encoding="utf-8")
+    if ".context-rail" in content:
+        return
+    gi_path.write_text(content.rstrip() + "\n\n.context-rail\n", encoding="utf-8")
+
+
 def _active_project_for_agents_md() -> tuple[str, str]:
-    state = load_state()
-    project_id = state.get("active_project_id")
+    from pathlib import Path
+    project_id, _ = resolve_workspace_project(str(Path.cwd()))
+    if not project_id:
+        project_id = load_state().get("active_project_id", "")
     if not project_id:
         return "", ""
 
@@ -234,8 +247,10 @@ def cmd_doctor() -> int:
 
     # --- 3. State ---
     print("\nState:")
-    state = load_state()
-    pid = state.get("active_project_id")
+    from pathlib import Path
+    pid, _ = resolve_workspace_project(str(Path.cwd()))
+    if not pid:
+        pid = load_state().get("active_project_id", "")
     if pid:
         ok(f"Active project: {pid}")
     else:
@@ -337,18 +352,45 @@ def cmd_init() -> None:
         print("  AGENTS.md: generated in current directory")
         print("  Skills: context-rail skills installed to .agents/skills/")
     else:
-        state = load_state()
-        pid = state.get("active_project_id")
+        from pathlib import Path
+        cwd = str(Path.cwd())
+        pid = ""
+        resolution = ""
+
+        # 1. Local .context-rail file
+        pid = find_local_project(cwd)
+        if pid:
+            resolution = ".context-rail file"
+        # 2. Workspace binding
+        if not pid:
+            pid, tier = resolve_workspace_project(cwd)
+            if pid:
+                resolution = f"workspace binding ({tier})"
+        # 3. Global state fallback
+        if not pid:
+            pid = load_state().get("active_project_id", "")
+            if pid:
+                resolution = "global state fallback"
+
         if pid:
-            proj = get_db().execute("SELECT name FROM projects WHERE id = ?", (pid,)).fetchone()
-            if proj:
-                print(f"Active project: {proj['name']}")
+            proj = get_db().execute(
+                "SELECT name, deleted_at FROM projects WHERE id = ?", (pid,)
+            ).fetchone()
+            if proj and not proj["deleted_at"]:
+                source = "" if resolution == ".context-rail file" else f"  (source: {resolution})"
+                print(f"Active project: {proj['name']}{source}")
                 ensure_agents_md(pid, proj["name"])
+                write_local_project(cwd, pid)
+                _ensure_gitignore_has_context_rail(cwd)
+            elif proj and proj["deleted_at"]:
+                print(f"Active project: {proj['name']} (DELETED — run project_set_active() for a new project)")
+                ensure_agents_md()
             else:
-                print(f"Active project not found (stale ID). Run project_set_active().")
+                print(f"Stale project ID '{pid}' found in {resolution}. Run project_set_active().")
                 ensure_agents_md()
         else:
-            print(f"{projects} project(s) exist but none is active. Run project_set_active().")
+            print(f"{projects} project(s) exist but none is active.")
+            print("Run project_set_active(project_id=\"...\", workdir=\".\") to bind this directory.")
             ensure_agents_md()
         ensure_skills()
         print("  AGENTS.md: updated in current directory")
@@ -441,14 +483,12 @@ def cmd_status(deleted: bool = False) -> None:
         "SELECT COUNT(*) as cnt FROM projects WHERE deleted_at IS NOT NULL"
     ).fetchone()["cnt"]
     conn.close()
-    state = load_state()
 
-    print(f"DB: {DB_PATH}")
-    print(f"Projects: {active_count} active")
-    if deleted_count > 0:
-        print(f"          {deleted_count} soft-deleted (use --deleted to list)")
-    pid = state.get("active_project_id")
-    tid = state.get("active_task_id")
+    from pathlib import Path
+    pid, _ = resolve_workspace_project(str(Path.cwd()))
+    if not pid:
+        pid = load_state().get("active_project_id", "")
+    tid = load_state().get("active_task_id")
     if pid:
         proj = get_db().execute(
             "SELECT name, deleted_at FROM projects WHERE id = ?", (pid,)

{context_rail-0.2.2 → context_rail-0.2.4}/src/context_rail/db.py

@@ -3,8 +3,11 @@
 
 import sqlite3
 import json
+import os
 from pathlib import Path
 
+CONTEXT_RAIL_FILE = ".context-rail"
+
 
 from contextlib import contextmanager
 
@@ -130,18 +133,46 @@ def set_workspace_binding(workdir: str, project_id: str, agent_id: str = "") ->
     save_workspace_bindings(bindings)
 
 
+def find_local_project(cwd: str) -> str:
+    """Walk up from cwd looking for a .context-rail file containing a project_id.
+
+    Returns project_id string, or "" if none found.
+    """
+    directory = Path(cwd).resolve()
+    while True:
+        cr_file = directory / CONTEXT_RAIL_FILE
+        if cr_file.is_file():
+            try:
+                return cr_file.read_text().strip()
+            except (OSError, UnicodeDecodeError):
+                pass
+        parent = directory.parent
+        if parent == directory:
+            break
+        directory = parent
+    return ""
+
+
+def write_local_project(workdir: str, project_id: str) -> None:
+    """Write a .context-rail file in the given directory pointing to the project."""
+    cr_file = Path(workdir) / CONTEXT_RAIL_FILE
+    try:
+        cr_file.write_text(project_id + "\n")
+    except OSError:
+        pass  # non-blocking — directory may not be writable
+
+
 def resolve_pid_for_tool(workdir: str = "", agent_id: str = "") -> str:
     """Resolve the active project_id for a tool call.
 
     Order of resolution:
 
+      0. Local .context-rail file in cwd (or ancestor) — auto-created by
+         project_create / project_set_active / ctx-rail init
       1. Explicit workdir parameter on the call → workspace binding lookup
       2. Default workdir = Path.cwd() (MCP subprocess inherits chat's cwd)
       3. Workspace binding lookup with the effective workdir
-      4. Fall back to state.json ``active_project_id`` — needed because
-         many tools (plan_phase, plan_goal, tools_risks, etc.) still read
-         state.json directly, so a project created via project_create()
-         (which writes state.json) must be visible here too.
+      4. Fall back to state.json ``active_project_id``
       5. Empty string (caller decides what to do — usually fail with
          "No active project")
 
@@ -152,6 +183,9 @@ def resolve_pid_for_tool(workdir: str = "", agent_id: str = "") -> str:
         from pathlib import Path
         workdir = str(Path.cwd())
     if workdir:
+        local_pid = find_local_project(workdir)
+        if local_pid:
+            return local_pid
         bound_pid, _tier = resolve_workspace_project(workdir, agent_id)
         if bound_pid:
             return bound_pid

{context_rail-0.2.2 → context_rail-0.2.4}/src/context_rail/server/_imports.py

@@ -41,6 +41,8 @@ _DELEGATES: dict[str, tuple] = {
     "resolve_workspace_project": (_db, "resolve_workspace_project"),
     "set_workspace_binding": (_db, "set_workspace_binding"),
     "resolve_pid_for_tool": (_db, "resolve_pid_for_tool"),
+    "find_local_project": (_db, "find_local_project"),
+    "write_local_project": (_db, "write_local_project"),
     "rows_to_list": (_db, "rows_to_list"),
     "log_activity": (_db, "log_activity"),
     "clock_in_agent_for_task": (_db, "clock_in_agent_for_task"),

{context_rail-0.2.2 → context_rail-0.2.4}/src/context_rail/server/tools_lifecycle.py

@@ -33,9 +33,11 @@ async def session_start(agent_id: str = "", workdir: str = "") -> str:
         workdir = str(Path.cwd())
 
     if workdir:
-        bound_pid, tier = resolve_workspace_project(workdir, agent_id)
-        if bound_pid:
-            pid = bound_pid
+        pid = find_local_project(workdir)
+        if not pid:
+            bound_pid, tier = resolve_workspace_project(workdir, agent_id)
+            if bound_pid:
+                pid = bound_pid
 
     if not pid:
         state_pid = load_state().get("active_project_id")

{context_rail-0.2.2 → context_rail-0.2.4}/src/context_rail/server/tools_orient.py

@@ -44,7 +44,7 @@ async def orient(agent_id: str = "", workdir: str = "") -> str:
     conn = get_db()
     init_db(conn)
 
-    # --- Resolve project: workspace binding > workdir > cwd > state fallback ---
+    # --- Resolve project: .context-rail > workspace binding > workdir > cwd > state fallback ---
     pid = ""
     binding_tier = ""
 
@@ -56,10 +56,14 @@ async def orient(agent_id: str = "", workdir: str = "") -> str:
         workdir = str(Path.cwd())
 
     if workdir:
-        bound_pid, tier = resolve_workspace_project(workdir, agent_id)
-        binding_tier = tier
-        if bound_pid:
-            pid = bound_pid
+        pid = find_local_project(workdir)
+        if pid:
+            binding_tier = "local_file"
+        else:
+            bound_pid, tier = resolve_workspace_project(workdir, agent_id)
+            binding_tier = tier
+            if bound_pid:
+                pid = bound_pid
 
     if not pid:
         # Fallback: state.json active_project_id — keeps orient()

{context_rail-0.2.2 → context_rail-0.2.4}/src/context_rail/server/tools_plan_review.py

@@ -436,8 +436,7 @@ async def plan_contract_view(contract_id: str = "", workdir: str = "") -> str:
     kind) or a verifiable artifact path/URL (manual_check). See
     `default_evidence_rules()` in autonomy/_contracts.py.
     """
-    state = load_state()
-    pid = state.get("active_project_id") if state else resolve_pid_for_tool(workdir)
+    pid = resolve_pid_for_tool(workdir) or load_state().get("active_project_id", "")
     # Fall back to helper if state is empty (NCR from state.json removal)
     if not pid:
         pid = resolve_pid_for_tool(workdir)
@@ -530,8 +529,7 @@ async def contract_refresh(contract_id: str = "", workdir: str = "") -> str:
 
     Returns the refreshed contract with before/after drift summary.
     """
-    state = load_state()
-    pid = state.get("active_project_id") if state else resolve_pid_for_tool(workdir)
+    pid = resolve_pid_for_tool(workdir) or load_state().get("active_project_id", "")
     if not pid:
         pid = resolve_pid_for_tool(workdir)
     if not pid:

{context_rail-0.2.2 → context_rail-0.2.4}/src/context_rail/server/tools_planning.py

@@ -11,12 +11,13 @@ async def plan_goal(
     priority: int = 0,
     goal_type: str = "objective",
     planned: bool = True,
+    workdir: str = "",
+    agent_id: str = "",
 ) -> str:
     """Add a goal to the current active phase."""
     conn = get_db()
     init_db(conn)
-    state = load_state()
-    pid = state.get("active_project_id")
+    pid = resolve_pid_for_tool(workdir, agent_id) or load_state().get("active_project_id", "")
 
     if not pid:
         return "No active project."
@@ -39,12 +40,11 @@ async def plan_goal(
 
 
 @mcp.tool()
-async def plan_phase(name: str, target_date: str = "", sort_order: int = 0) -> str:
+async def plan_phase(name: str, target_date: str = "", sort_order: int = 0, workdir: str = "", agent_id: str = "") -> str:
     """Add a new phase to the active project."""
     conn = get_db()
     init_db(conn)
-    state = load_state()
-    pid = state.get("active_project_id")
+    pid = resolve_pid_for_tool(workdir, agent_id) or load_state().get("active_project_id", "")
 
     if not pid:
         return "No active project."
@@ -74,12 +74,11 @@ async def plan_phase(name: str, target_date: str = "", sort_order: int = 0) -> s
 
 
 @mcp.tool()
-async def phase_reorder(phase_id: str, new_sort_order: int) -> str:
+async def phase_reorder(phase_id: str, new_sort_order: int, workdir: str = "", agent_id: str = "") -> str:
     """Move a phase to a new position. Other phases are rebalanced automatically."""
     conn = get_db()
     init_db(conn)
-    state = load_state()
-    pid = state.get("active_project_id")
+    pid = resolve_pid_for_tool(workdir, agent_id) or load_state().get("active_project_id", "")
 
     if not pid:
         return "No active project."

{context_rail-0.2.2 → context_rail-0.2.4}/src/context_rail/server/tools_projects.py

@@ -68,6 +68,7 @@ async def project_login(project_id: str, agent_id: str = "", workdir: str = "")
             binding_msg = f" Workspace {workdir} bound (agent {agent_id})."
         else:
             binding_msg = " (existing wildcard binding preserved; pass agent_id to bind specifically)"
+        write_local_project(workdir, project_id)
     else:
         binding_msg = " (pass workdir to bind workspace)"
 
@@ -109,6 +110,7 @@ async def project_create(name: str, description: str = "", budget: str = "medium
 
     if workdir:
         set_workspace_binding(workdir, pid)
+        write_local_project(workdir, pid)
 
     # Update AGENTS.md
     try:
@@ -221,16 +223,15 @@ async def project_list(project_id: str = "", include_deleted: bool = False) -> s
 # ---------------------------------------------------------------------------
 
 @mcp.tool()
-async def project_budget(budget: str = "medium", project_id: str = "") -> str:
+async def project_budget(budget: str = "medium", project_id: str = "", workdir: str = "", agent_id: str = "") -> str:
     """Set the project budget. Controls how deep auto-expand goes: small(3), medium(10), high(25), max.
 
     Lower budgets save tokens during orient/focus. Use expand_all=True on focus() to bypass.
     """
     conn = get_db()
     init_db(conn)
-    state = load_state()
 
-    pid = project_id or state.get("active_project_id")
+    pid = project_id or resolve_pid_for_tool(workdir, agent_id) or load_state().get("active_project_id", "")
     if not pid:
         conn.close()
         return json.dumps({"error": "No project"})
@@ -249,13 +250,12 @@ async def project_budget(budget: str = "medium", project_id: str = "") -> str:
 
 
 @mcp.tool()
-async def project_update(project_id: str = "", name: str = "", description: str = "", budget: str = "", status: str = "", userConfirm: bool = False) -> str:
+async def project_update(project_id: str = "", name: str = "", description: str = "", budget: str = "", status: str = "", userConfirm: bool = False, workdir: str = "", agent_id: str = "") -> str:
     """Update a project. Uses active project if project_id is empty. To change status, set userConfirm=True."""
     conn = get_db()
     init_db(conn)
-    state = load_state()
 
-    pid = project_id or state.get("active_project_id")
+    pid = project_id or resolve_pid_for_tool(workdir, agent_id) or load_state().get("active_project_id", "")
     if not pid:
         conn.close()
         return json.dumps({"error": "No project"})

{context_rail-0.2.2 → context_rail-0.2.4}/src/context_rail/server/tools_risks.py

@@ -10,6 +10,8 @@ async def risk(
     severity: str = "medium",
     description: str = "",
     entity_type: str = "task",
+    workdir: str = "",
+    agent_id: str = "",
 ) -> str:
     """Flag a risk on a task or goal (severity: low|medium|high|critical)."""
     conn = get_db()
@@ -38,8 +40,7 @@ async def risk(
     # Auto-create enforcement rules for high/critical risks
     derived_msg = ""
     if severity in ("high", "critical"):
-        state = load_state()
-        pid = state.get("active_project_id")
+        pid = resolve_pid_for_tool(workdir, agent_id) or load_state().get("active_project_id", "")
         if pid:
             # For critical: block retries; for high: warn on retries
             action = "block" if severity == "critical" else "warn"

{context_rail-0.2.2 → context_rail-0.2.4}/src/context_rail/server/tools_roadmap.py

@@ -38,6 +38,8 @@ async def roadmap_add(
     tags: str = "",
     visibility: str = "team",
     order_idx: int = 0,
+    workdir: str = "",
+    agent_id: str = "",
 ) -> str:
     """Create a new roadmap item.
 
@@ -49,8 +51,7 @@ async def roadmap_add(
 
     conn = get_db()
     init_db(conn)
-    state = load_state()
-    pid = state.get("active_project_id")
+    pid = resolve_pid_for_tool(workdir, agent_id) or load_state().get("active_project_id", "")
     if not pid:
         conn.close()
         return json.dumps({"error": "No active project"})
@@ -172,6 +173,8 @@ async def roadmap_list(
     status: str = "",
     parent_id: str = "",
     visibility: str = "",
+    workdir: str = "",
+    agent_id: str = "",
 ) -> str:
     """List roadmap items with optional filters.
 
@@ -179,8 +182,7 @@ async def roadmap_list(
     """
     conn = get_db()
     init_db(conn)
-    state = load_state()
-    pid = state.get("active_project_id")
+    pid = resolve_pid_for_tool(workdir, agent_id) or load_state().get("active_project_id", "")
     if not pid:
         conn.close()
         return json.dumps({"error": "No active project"})

{context_rail-0.2.2 → context_rail-0.2.4}/src/context_rail/skills/setup/SKILL.md

@@ -45,36 +45,45 @@ Skills are auto-copied to `.agents/skills/context-rail/` in the current project.
 ```
 1. project_create(name="My Project", description="What it does", workdir="/path/to/repo")
    → Creates project in database, auto-generates AGENTS.md
-   → Optionally binds the workspace
+   → Creates .context-rail file + workspace binding in workdir
 
 2. project_set_active(project_id="...", workdir="/path/to/repo")
-   → Sets as active project in state.json
-   → Creates workspace binding (agent resolves project from cwd)
+   → Sets as active project in state.json (global fallback)
+   → Creates .context-rail file + workspace binding
+   → After this, any command/tool in that directory auto-resolves
 
 3. project_login(project_id, agent_id="...", workdir="/path/to/repo")
    → Alternative: log an agent into the project with workspace binding
    → Call this when orient() shows ⚠ unbound
+
+4. ctx-rail init  (run in project root)
+   → Auto-detects project from .context-rail file, workspace binding, or state.json
+   → Creates .context-rail file if a project resolves
+   → Adds .context-rail to .gitignore (if .gitignore exists)
 ```
 
 ### Verifying setup
 
 ```
 orient(workdir="/path/to/repo")
-→ Should show: "Login: ✓ bound as '<agent>' in this workspace"
-→ If shows "⚠ no workspace binding" → run project_login or project_set_active
+→ Should show: "Login: ✓ bound via .context-rail"
+→ If shows "⚠ unbound" → run ctx-rail init or project_set_active with workdir
 ```
 
-## Workspace Binding (how agents resolve projects)
+## Project Resolution (how agents find the right project)
 
-Context Rail resolves the active project from the agent's current working directory:
+Context Rail resolves the active project from the agent's current working directory
+using a 3-tier approach:
 
-| Method | How it works | When to use |
-|---|---|---|
-| `project_set_active(workdir="/repo")` | Binds workspace → project (wildcard `*`) | Any agent in that directory gets this project |
-| `project_login(agent_id="a1", workdir="/repo")` | Binds workspace → project for specific agent | Multiple agents in same directory, different projects |
-| `orient(workdir="/repo")` | Queries bindings → falls back to state.json | Called automatically on session startup |
+| Tier | Method | How it works | Automatic? |
+|---|---|---|---|
+| 1 | `.context-rail` file | File in cwd (or parent) containing project_id | Created on `ctx-rail init`, `project_create`, `project_set_active` |
+| 2 | Workspace binding | Global mapping in `workspace_bindings.json` | Created when workdir is passed to `project_set_active` |
+| 3 | State fallback | `state.json`'s `active_project_id` | Legacy — only used when tiers 1 & 2 miss |
 
-All 113 MCP tools use `resolve_pid_for_tool(workdir, agent_id)` first, then fall back to `load_state()`. Workspace bindings take priority.
+All tools use `resolve_pid_for_tool(workdir, agent_id)` which checks all three tiers
+in order. After one `ctx-rail init`, you never need `project_set_active` again —
+the `.context-rail` file handles it automatically.
 
 ## Loading Skills
 
@@ -208,8 +217,9 @@ project_login(project_id="...", agent_id="...", workdir="/path/to/repo")
 
 ### "No active project" on tools that should work
 
-The tool may be using `load_state()` only (legacy). All tools should now use workspace binding. If a specific tool still fails:
-1. Pass `workdir="/path/to/repo"` explicitly
+1. Run `ctx-rail init` in the project root to create `.context-rail`
+2. Pass `workdir="/path/to/repo"` explicitly
+3. Call `project_set_active(project_id="...", workdir="/path/to/repo")` to bind the directory
 2. Call `project_set_active(workdir="/path/to/repo")` first
 3. Report the tool name — it may still need the workspace binding fix
 

{context_rail-0.2.2 → context_rail-0.2.4/src/context_rail.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: context-rail
-Version: 0.2.2
+Version: 0.2.4
 Summary: Context Rail — agentic task-management that keeps your project on rails.
 License: MIT
 Project-URL: Repository, https://github.com/nguyenhoanhson797/Context-Rail