context-rail 0.1.0__tar.gz

context_rail-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

context_rail-0.1.0/PKG-INFO

@@ -0,0 +1,437 @@
+Metadata-Version: 2.4
+Name: context-rail
+Version: 0.1.0
+Summary: Context Rail — agentic task-management that keeps your project on rails.
+License: MIT
+Project-URL: Repository, https://github.com/nguyenhoanhson797/Context-Rail
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0.0
+Provides-Extra: web
+Requires-Dist: fastapi>=0.115; extra == "web"
+Requires-Dist: uvicorn>=0.30; extra == "web"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-asyncio>=0.24; extra == "test"
+Requires-Dist: fastapi>=0.115; extra == "test"
+Dynamic: license-file
+
+# Context-Rail
+
+**A local project rail for long-running agentic work.**
+
+AI agents are good at individual tasks. Long projects drift — they forget the plan, lose context between sessions, repeat bad actions, mark work done without review, and start every session like the project is new.
+
+Context-Rail keeps the project on rail by giving both the **human** and the **agent** the same structured project state. It is not a chatbot memory file. It is not a code indexer. It is a **local operating loop for agent work**.
+
+```text
+PLAN → EXECUTE → REVIEW → ACT
+```
+
+Built with **Python + SQLite + MCP**.
+
+---
+
+## Install
+
+**Core (MCP server + CLI — lightweight, no web deps):**
+
+```bash
+pip install git+https://github.com/nguyenhoanhson797/Context-Rail.git
+```
+
+**With web UI (adds FastAPI + Uvicorn):**
+
+```bash
+pip install "git+https://github.com/nguyenhoanhson797/Context-Rail.git#egg=context-rail[web]"
+```
+
+Initialize:
+
+```bash
+ctx-rail init
+```
+
+This creates the local SQLite database, generates an `AGENTS.md` in the current directory (so your agent knows the CR workflow), and installs CR skills to `.agents/skills/context-rail/`.
+
+Connect to your MCP client:
+
+```bash
+ctx-rail config
+```
+
+This prints the correct config with the absolute Python path — important on Windows where bare `python` may resolve to the wrong interpreter. Paste it into your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "context-rail": {
+      "command": "C:/Python313/python.exe",
+      "args": ["-m", "context_rail", "serve"]
+    }
+  }
+}
+```
+
+For Codex (TOML format):
+
+```bash
+ctx-rail config --client codex
+```
+
+Update later (upgrades the package + refreshes AGENTS.md + skills):
+
+```bash
+ctx-rail update
+```
+
+Start the MCP server:
+
+```bash
+ctx-rail serve
+```
+
+Start the web platform (requires `[web]` install):
+
+```bash
+ctx-rail web                # API + React UI (default)
+ctx-rail web --no-frontend  # API only
+```
+
+---
+
+## A session with Context-Rail
+
+This is what it feels like to work with CR — not a tool catalog, but the flow an agent actually follows.
+
+### 1. Start — the agent already knows
+
+The agent opens a session and calls one tool:
+
+```text
+session_start(agent_id="codex-1", workdir="/path/to/repo")
+```
+
+It gets back everything it needs in one response:
+
+* which project is active (via workspace binding — survives across sessions);
+* the roadmap story — intent, success criteria, non-goals;
+* the current phase and its progress;
+* the next task with dependencies and context items;
+* open warnings (blocked tasks, tasks needing evidence);
+* governance status — is there an intent tree? an approved plan contract?
+
+If the workspace isn't bound yet, the agent binds it once:
+
+```text
+project_login("project-id", agent_id="codex-1", workdir="/path/to/repo")
+```
+
+From then on, every session in that workspace opens with the correct project automatically.
+
+The agent does not guess what to do next. It does not start from zero.
+
+### 2. Plan — natural brainstorm, not a blank form
+
+Before jumping into tasks, CR runs a **brainstorm** — a natural conversation proportional to the idea. It can shape:
+
+* a whole project (vision, phases, roadmap, risks);
+* one phase or one goal;
+* one feature or task;
+* a refinement or an option comparison;
+* an execution plan.
+
+The conversation stays friendly. The agent drafts the plan. The human reviews it. Only approved plans become committed project work.
+
+Approval creates a **plan contract** — not just old context. That contract carries the goal, quality bar, autonomy boundaries, evidence rules, stop rules, plan snapshot, drift rules, and rail-check policy that later execution must follow.
+
+### 3. Focus — context sticks to the task
+
+The agent calls:
+
+```text
+focus(agent_id="codex-1", agent_name="Codex", harness="codex", role="builder")
+```
+
+It gets the execution packet for the next task:
+
+* task description, dependencies, notes, handoffs;
+* risks, lessons, artifacts, related goals;
+* active agents working on the task;
+* review state;
+* PDCA stage, contract constraints, required evidence, stop conditions, rail-check status.
+
+Context is not floating in a chat log. It is **attached to the task**. The agent loads what it needs, not the whole project.
+
+When `agent_id` is provided, CR clocks that agent into the task. If the agent was active on another task, the older session is released. When the task is done or blocked, active work sessions close. This keeps ownership flexible while answering: "which agent is doing this right now?"
+
+### 4. Work — guardrails that adapt to risk
+
+The agent works freely — editing, testing, browsing, debugging. CR does not micromanage every tool call.
+
+For risky or repeated actions, the agent can call:
+
+```text
+check_action(kind="retry", context_json='{"path": "/abs/path", "error": "..."}')
+```
+
+CR returns Allow, Warn, or Block based on project rules.
+
+The key design point: **guardrails adapt to risk**. Not every task needs the same ceremony:
+
+| Lane | Tier | Behavior |
+|------|------|----------|
+| `tiny` | T0 | Skip PDCA entirely — just flip status to done |
+| `normal` | T1 | Lightweight cycle check, evidence validation relaxed |
+| `high_risk` | T2 | Full governance — evidence, review, drift, rail-check |
+
+This means a typo fix doesn't go through the same pipeline as an architecture change. The agent picks the lane when adding the task; CR handles the rest.
+
+### 5. Done — evidence is harvested, not asked for
+
+When the agent calls `done()`, CR does not ask "please attach evidence." It **harvests evidence automatically** — git diffs, test results, file changes — and records it to the PDCA cycle.
+
+If evidence is insufficient, the task is flagged `needs_evidence` — visible in the next `session_start()` or `focus()` call. The agent can supplement it or the human can override.
+
+Evidence is validated before it satisfies a required rule. A failing test result or empty manual check does not count as proof.
+
+`done()` also returns the **next task with its context** — so the agent can continue without a separate `focus()` call.
+
+### 6. Review — lessons become future work
+
+After a phase, the agent or human runs a retro:
+
+```text
+retro(phase_id="...")
+```
+
+Then turns improvements into next-phase tasks:
+
+```text
+retro(action="act")
+```
+
+Lessons don't stay as passive notes. They affect future tasks, risks, rules, and reviews. Decisions are recorded with `decision_create()` so direction changes are visible and queryable.
+
+### 7. Resume — next session picks up where this one left
+
+CR stores project state locally in SQLite. The next session recovers:
+
+* current project (via workspace binding);
+* active plan contract and autonomy run;
+* PDCA cycle state, rail-check result;
+* active phase, task queue, blocked work;
+* notes, lessons, risks, artifacts, rules, review state, retros.
+
+This makes CR useful for multi-day, multi-session, and multi-agent work.
+
+---
+
+## How Context-Rail adapts
+
+### Governance on/off
+
+Not every project needs heavy governance. `project_create(governance=False)` switches to **lightweight mode**:
+
+* `check_action` returns Allow or Warn — never Block;
+* PDCA runs **non-blocking** — warnings instead of gates;
+* direction guard is off;
+* auto-evidence harvesting still works (always on).
+
+This is the "OS background" metaphor: CR runs quietly, records what happened, warns when something looks off — but doesn't get in the way.
+
+### Intent tree — the living plan
+
+Plans are not frozen at approval. CR maintains an **intent tree** — a living structure of what the project is trying to achieve:
+
+```text
+intent_plant(title="User auth", intent="Secure login without friction",
+             success_criteria="2FA optional, <3s login", non_goals="No SSO")
+intent_list()
+intent_check(task_title="Add OAuth provider")  →  matches or warns off-plan
+```
+
+When a new task doesn't match any intent node, CR warns. The tree grows with the project — plant new intents as scope evolves.
+
+### Context items — knowledge that sticks
+
+CR has a scoped knowledge store (`context_items`) that attaches to tasks, phases, goals, and roadmaps:
+
+```text
+context_add(scope_type="task", scope_id="...", content="API uses Bearer token", kind="reference")
+context_pack(task_id="...")     →  relevant items for that task
+context_wiki()                  →  browse all knowledge grouped by kind
+context_verify(id="...")        →  refresh stale items
+context_health()                →  coverage and freshness report
+```
+
+Context items have lifecycle: seed → grow → maintain → serve. Stale items are flagged. The agent uses `context_apply()` to mark items as used, keeping the knowledge loop alive.
+
+### Roadmaps — project genesis
+
+Roadmaps are the entry point for every project — high-level initiatives, milestones, or bets that define the vision. Each roadmap carries:
+
+* **intent** — why it matters strategically;
+* **success_criteria** — what done looks like;
+* **background** — context for the initiative;
+* **non_goals** — what's explicitly out of scope;
+* **stakeholders_note** — who cares and why;
+* **progress** — auto-rolled up from phases → tasks.
+
+The brainstorm conductor Stage 0 asks for initiatives before phases. Roadmaps link to phases; phases link to tasks; done tasks roll progress up to the roadmap automatically.
+
+### Multi-agent lanes
+
+Different agents can have narrower rails:
+
+```text
+rail_policy_set(agent_id="ui-bot", task_tags="ui")
+rail_policy_set(agent_id="api-bot", task_tags="backend")
+```
+
+An agent-specific rail can restrict what that agent touches. It cannot loosen stop rules, remove evidence requirements, or bypass phase gates.
+
+`runtime_status()` is the single source of truth — it reports whether the agent can proceed and, if not, an ordered list of blockers across all enforcement layers (rail-check, PDCA, lease, drift).
+
+### Unified configuration
+
+One tool replaces six:
+
+```text
+configure(action="update_project", name="...", budget="high")
+configure(action="add_rule", rule_kind="retry", rule_threshold='{"max": 3}')
+configure(action="list_rules")
+configure(action="remove_rule", rule_id="...")
+configure(action="reset_session")
+```
+
+---
+
+## For humans
+
+CR answers the questions a human actually has:
+
+```text
+What are we building?         → roadmap story
+Where are we now?             → phase + progress
+What should happen next?      → next task
+What is blocked?              → warnings in session_start
+What needs review?            → review state on tasks
+What did we learn?            → lessons, retros, decisions
+What should change next phase? → retro → act
+```
+
+The human does not micromanage every tool call. They review direction, approve plans, resolve blockers, and keep authority over important decisions.
+
+---
+
+## For agents
+
+```text
+1. session_start(agent_id="...", workdir="/path/to/repo")
+   If unbound, call project_login() to bind the workspace.
+
+2. Read the response — project, phase, next task, context, warnings, governance.
+
+3. autonomy_start() to activate PDCA evidence loop and lease tracking.
+   (Without this, done()/block() skip the evidence gate.)
+
+4. focus() on the next task. Pass agent_id if the harness has identity.
+
+5. Work freely. Save findings with note(). Save lessons with learn().
+   Record direction changes with decision_create().
+
+6. done() when complete — evidence is auto-harvested. Next task is returned.
+   block() when stuck or a stop rule fires.
+
+7. retro() when a phase ends. Convert improvements into future tasks.
+
+If unsure whether a stop is in effect, call runtime_status().
+```
+
+---
+
+## Core objects
+
+```text
+Project
+  ├─ Roadmap (vision, intent, success criteria, progress rollup)
+  │   └─ Phase
+  │       └─ Task (lane: tiny | normal | high_risk)
+  │           ├─ Context items (scoped knowledge)
+  │           ├─ Dependencies
+  │           ├─ Handoffs
+  │           ├─ Active agent sessions
+  │           └─ Review state
+  ├─ Goals ←→ Tasks (N:N links)
+  ├─ Intent nodes (living plan tree)
+  ├─ Plan contracts (approved plan → execution binding)
+  ├─ Autonomy runs / PDCA cycles (lease, evidence, drift)
+  ├─ Categories
+  │   ├─ Risks
+  │   ├─ Lessons
+  │   └─ Artifacts
+  ├─ Rules
+  ├─ Gates
+  └─ Retros
+```
+
+<details>
+<summary>Diagram: data model</summary>
+
+```mermaid
+erDiagram
+    PROJECT ||--o{ ROADMAP : defines
+    ROADMAP ||--o{ PHASE : scopes
+    PROJECT ||--o{ PHASE : contains
+    PHASE ||--o{ TASK : tracks
+    PROJECT ||--o{ GOAL : defines
+    GOAL }o--o{ TASK : links
+    PROJECT ||--o{ INTENT_NODE : intends
+    PROJECT ||--o{ PLAN_CONTRACT : binds
+    PROJECT ||--o{ AUTONOMY_RUN : executes
+    AUTONOMY_RUN ||--o{ PDCA_CYCLE : cycles
+    TASK ||--o{ CONTEXT_ITEM : carries
+    TASK ||--o{ AGENT_WORK_SESSION : has
+    PROJECT ||--o{ RULE : guards
+    PROJECT ||--o{ GATE : reviews
+    PHASE ||--o{ RETRO : reviews
+    CATEGORY ||--o{ RISK : owns
+    CATEGORY ||--o{ LESSON : owns
+    CATEGORY ||--o{ ARTIFACT : owns
+```
+
+</details>
+
+---
+
+## Useful commands
+
+```bash
+ctx-rail init       # Initialize database + AGENTS.md + skills
+ctx-rail serve      # Start MCP server (stdio)
+ctx-rail config     # Print MCP client config (correct Python path)
+ctx-rail config --client codex  # TOML format for Codex
+ctx-rail status     # Show active project, DB location, counts
+ctx-rail doctor     # Health check: DB, schema, skills, AGENTS.md, MCP config
+ctx-rail web        # Start web platform (requires [web] install)
+ctx-rail update     # Upgrade package + refresh AGENTS.md + skills
+```
+
+---
+
+## What Context-Rail is not
+
+* a code indexer;
+* a semantic search engine;
+* a replacement for Git, Jira, or Linear;
+* a replacement for Cursor, Claude Code, Codex, or GitNexus.
+
+Context-Rail sits beside those tools as the **agent work rail**. Use code intelligence tools to understand the codebase. Use Context-Rail to keep the project plan, task flow, reviews, risks, lessons, and execution memory on track.
+
+---
+
+## License
+
+MIT