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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: context-rail
-Version: 0.2.1
+Version: 0.2.2
 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.1 → context_rail-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "context-rail"
-version = "0.2.1"
+version = "0.2.2"
 description = "Context Rail — agentic task-management that keeps your project on rails."
 readme = "README.md"
 license = {text = "MIT"}
@@ -33,4 +33,4 @@ Repository = "https://github.com/nguyenhoanhson797/Context-Rail"
 where = ["src"]
 
 [tool.setuptools.package-data]
-context_rail = []
+context_rail = ["skills/**/*"]

context_rail-0.2.2/src/context_rail/skills/daily/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: context-rail-daily
+description: "Context Rail day-to-day workflow — capture reflex, project facts, session startup, find() search, memory vs CR boundary."
+version: 1.0.0
+author: Context Rail
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [Context-Rail, Capture, Project-Facts, Daily-Workflow, Session-Startup]
+    related_skills: [context-rail-governance, context-rail-orchestration]
+---
+
+# Context Rail — Daily Workflow
+
+The minimal daily loop for using Context Rail on every task. Load this skill at session start to get the capture reflex and avoid the memory() trap.
+
+## Session Startup (MANDATORY)
+
+Every session starts with these 3 calls — in order. Never skip a step.
+
+```
+1. orient(workdir="/path/to/repo") — project status + recently captured items
+2. find("task keywords")          — search ALL context before working
+3. focus()                        — get task execution packet
+```
+
+`orient()` shows "Recently Captured" items — if you see the fact you need there, skip `find()`.
+`find()` searches context_items, tasks, lessons, project_notes, decisions, risks — everything.
+`focus()` returns context_pack with inherited project facts from the scope hierarchy.
+
+## The Capture Boundary (CRITICAL — VIOLATE THIS AND YOU WASTE SESSIONS)
+
+```
+┌─────────────────────────────────────────────────────┐
+│ Project codebase facts → note(content, kind="...")  │
+│ Agent environment facts → memory()                  │
+│                                                     │
+│ NEVER use memory() for project facts.               │
+│ NEVER re-discover the same fact across sessions.    │
+│ If you found it once, it belongs in Context Rail.   │
+└─────────────────────────────────────────────────────┘
+```
+
+### What is a "project fact"?
+
+- Run commands: `yarn test tests/agent-chat/`, `npm run build`
+- Test patterns: "mock DB in conftest.py, use pytest fixtures"
+- Architecture notes: "API at localhost:4175, 3 microservices"
+- API endpoints: `POST /api/v2/tasks`, `GET /api/v2/projects`
+- File locations: "tests live in tests/agent-chat/, 3 test files"
+- Configuration: "use .env.local for dev, .env for CI"
+
+### What is an "environment fact" (→ memory)?
+
+- Host details: "Python 3.13 at /c/Python313/python.exe"
+- Tool quirks: "patch tool replace_all is dangerous on this host"
+- Shell syntax: "use bash not PowerShell on this Windows host"
+- Path conventions: "venv at ~/AppData/Local/hermes/"
+
+## Quick Capture (2 params, always works)
+
+```
+note(content, kind="reference")
+```
+
+With `task_id`: writes to task_context (task-scoped, surfaces in focus()).
+Without `task_id`: writes to context_items as project-scoped (surfaces in find(), orient(), context_pack).
+
+Valid kinds: `reference`, `command`, `finding`, `note`, `decision`, `link`, `warning`, `file_path`, `file_touched`, `attempt`
+
+### Capture reflex checklist
+
+After any of these actions, immediately note() the finding:
+- Discovered a run command → `note("yarn test tests/agent-chat/", kind="command")`
+- Found a test pattern → `note("mock DB in conftest.py", kind="reference")`
+- Located an API endpoint → `note("POST /api/v2/tasks", kind="reference")`
+- Hit a pitfall → `note("watch out for X when doing Y", kind="warning")`
+
+## Search First, Discover Later
+
+Before using `search_files`, `read_file`, or `grep` to find project information:
+1. Call `find("keywords")` first
+2. If it returns results — use them, don't re-discover
+3. If it returns empty — discover from source, then `note()` it for next time
+
+## Task Completion
+
+```
+done(task_id) — marks task complete
+block(task_id, reason) — marks task blocked
+```
+
+`done()` has a soft gate: if context items were presented but none were touched, it warns.
+Second `done()` call always succeeds. This is a speed bump, not a wall.
+
+## Common Anti-Patterns
+
+| Anti-pattern | Why it's wrong |
+|---|---|
+| `memory.add("yarn test")` | Project fact in memory — invisible to find(), not scoped, not shared |
+| Calling `search_files("yarn")` before `find("yarn")` | Context Rail already has it — re-discovering wastes 10+ tool calls |
+| Skipping `orient()` at session start | Missing gap alerts, recently captured items, project status |
+| Using `context_add(19 params)` for a simple run command | Overkill — `note(content, kind="command")` is 2 params |
+
+## Verification
+
+After implementing a task, verify the capture loop works:
+1. `note("test fact", kind="reference")` → "Project note saved"
+2. `orient()` → see the fact in "Recently Captured"
+3. `find("test fact")` → see the fact in context_items
+4. `focus()` → see the fact in context_pack under "project"
+
+If any step fails, Context Rail needs attention — report it.

context_rail-0.2.2/src/context_rail/skills/governance/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: context-rail-governance
+description: "Context Rail governance patterns — brainstorm, plan_review, autonomy PDCA, retros, evidence validation, context learning loop."
+version: 1.0.0
+author: Context Rail
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [Context-Rail, Governance, PDCA, Planning, Retros, Evidence, Autonomy]
+    related_skills: [context-rail-daily, context-rail-orchestration]
+---
+
+# Context Rail — Governance
+
+Planned work patterns: brainstorm, approve, execute with PDCA checks, retro, act. Load this when working on structured phases, not quick tasks.
+
+## Plan Flow
+
+```
+brainstorm(goal="...")
+    ↓
+brainstorm_continue(answer) × 7 stages:
+  roadmap → frame → explore → challenge → converge → plan → approve
+    ↓
+plan_review(action="gates")  — evaluate gates, provide evidence
+    ↓
+plan_review(action="approve")  — commit to database, create active contract
+    ↓
+autonomy_start()  — begin PDCA execution
+```
+
+### Brainstorm gates
+
+Each gate in `plan_review(action="gates")` needs a YES/NO + evidence:
+- `proj_gap_coverage` — does the plan cover all requirements?
+- `proj_scope_boundary` — are non-goals explicitly excluded?
+- `proj_dependency_order` — are phases ordered correctly?
+- 5 more gates available
+
+Evidence must include a `falsifier` (test kind: runnable command that FAILS if wrong) or `file_path` (manual_check kind: path the validator can check exists).
+
+## Execute Flow (PDCA)
+
+```
+orient()  →  see contract, lease, rail-check, stop state
+    ↓
+focus()   →  get execution packet with context_pack
+    ↓
+harness work  →  note/learn/decision as you go
+    ↓
+autonomy_record(do_json, evidence_json)  →  record what was done
+    ↓
+autonomy_gate("rail_check")  →  check gates before next cycle
+    ↓
+done(task_id)  →  complete task (triggers PDCA cycle check)
+    ↓
+block(task_id, reason)  →  if blocked, stop the cycle
+```
+
+### Evidence format
+
+```json
+// For test evidence:
+{"kind": "test", "falsifier": "pytest tests/test_x.py -k 'test_feature'", "summary": "All 5 scenarios pass"}
+
+// For manual check evidence:
+{"kind": "manual_check", "file_path": "docs/architecture.md", "summary": "Architecture documented"}
+```
+
+## Review Flow
+
+After a phase completes:
+```
+retro(phase_id)  →  view retros for this phase
+
+retro(phase_id,
+    went_well="What worked",
+    went_wrong="What didn't",
+    improve="What to change"
+)  →  write retro
+
+retro(action="act")  →  convert improve items into tasks for next phase
+```
+
+## Context Learning Loop
+
+For governance-level context (scoped, ranked, validated):
+
+```
+focus() → context_pack + recommended_reads
+
+For items used:      context_apply(id)           — bumps applied_count
+For correct items:   context_verify(id)          — updates freshness
+For wrong/stale:     context_update(id, content=...) — fixes stale info
+For missing info:    context_add(title, content, scope_type="phase", scope_id="...", priority=80)
+
+Health check:        context_health()            — after several tasks
+Improvement ideas:   context_propose()           — mechanical proposals from friction patterns
+Friction log:        autonomy_record(do_json='{"harness_friction":"...","context_items_read":[...]}"')
+```
+
+## Decisions (provenance)
+
+```
+decision_create(question="...", choice="X", rationale="because Y",
+                alternatives=["A", "B"], category="architecture")
+decision_list()  —  browse before re-litigating
+```
+
+## Autonomy Run Management
+
+```
+autonomy_status()              — view active run state
+autonomy_next(max_cycles=3)    — get next execution packet
+autonomy_gate(action="resume") — resume after stop
+rail_policy_set(phase_ids="...", category_ids="...") — narrow agent lane
+```
+
+## Rail-check Resolution
+
+When a rail-check stop occurs:
+1. Read the `stop_reason` from `autonomy_status()` or `runtime_status()`
+2. Fix the underlying issue (add evidence, resolve dependency, etc.)
+3. Call `autonomy_gate(action="resume", notes="Fixed X")` to continue
+
+## Common Governance Pitfalls
+
+| Pitfall | Fix |
+|---|---|
+| Evidence without `falsifier` or `file_path` | Evidence marked invalid_or_insufficient_evidence |
+| `plan_phase` ignores `project_id` param | Call `project_set_active` first, all MCP calls in one subprocess |
+| `task_add` missing phase_id | Must pass both `phase_id` AND `project_id` |
+| `tags` as comma-separated string | Must be JSON array: `'["tag1","tag2"]'` |
+| State.json split-brain | Use `workdir` + `agent_id` on every call |

context_rail-0.2.2/src/context_rail/skills/orchestration/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: context-rail-orchestration
+description: "Context Rail multi-agent orchestration — delegation, lanes, N:N goal-task DAGs, rail policies, subagent-driven development."
+version: 1.0.0
+author: Context Rail
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [Context-Rail, Multi-Agent, Orchestration, Delegation, DAG, Subagent]
+    related_skills: [context-rail-daily, context-rail-governance]
+---
+
+# Context Rail — Orchestration
+
+Multi-agent patterns: delegate tasks, design N:N goal-task DAGs, enforce rail policies, run two-stage reviews. Load for large features and parallel workstreams.
+
+## Agent Roles
+
+| Role | Depth | Can spawn | Use case |
+|---|---|---|---|
+| **leaf** (default) | 0 | Cannot delegate further | Single atomic task |
+| **orchestrator** | 1 | Can spawn 2-3 leaves | Coordinates sub-tasks toward a goal |
+
+Max spawn depth: 2. Max concurrent children: 5. Orchestrators track their children and synthesize results.
+
+## Task Lanes
+
+```
+task_add(title="...", lane="tiny|normal|high_risk")
+```
+
+| Lane | Token budget | Review required | Use case |
+|---|---|---|---|
+| `tiny` | ~2K tokens | No | Copy changes, labels, one-line fixes |
+| `normal` | ~5K tokens | No | Standard features and bug fixes |
+| `high_risk` | ~10K tokens | **Yes** | Auth, schema migrations, API changes |
+
+High-risk tasks automatically set `review_required=true` and get expanded context packs.
+
+## Delegation Patterns
+
+### Pattern 1: Simple split (2-3 leaves)
+
+```python
+delegate_task(tasks=[
+    {"goal": "Implement parser fix in src/parser.ts", "context": "The bug is on line 42..."},
+    {"goal": "Update tests for parser fix", "context": "Test file: tests/parser.test.ts"},
+    {"goal": "Update docs with new parser behavior", "context": "Doc file: docs/parser.md"},
+])
+```
+
+All run in parallel. Results arrive as independent messages.
+
+### Pattern 2: Orchestrator + leaves (2-stage)
+
+```python
+# Stage 1: Orchestrator designs the approach
+delegate_task(
+    goal="Design audit approach for Nexterface imagination loop",
+    role="orchestrator",
+    context="Focus on state machine paths, not test coverage. Write findings to .md in project root."
+)
+# Orchestrator spawns 2-3 leaf workers for deep-dive on specific areas
+
+# Stage 2: Synthesize (you, the parent) — combine orchestrator's results
+```
+
+### Pattern 3: Two-stage review (subagent-driven)
+
+For complex tasks:
+```
+1. delegate_task(goal="Write spec for feature X", role="orchestrator")
+   → Orchestrator produces spec with acceptance criteria
+2. delegate_task(goal="Implement feature X from spec", context="Spec: ...")
+   → Leaf worker implements against the spec
+3. You review leaf output against the spec
+   → review(task_id, status="approved|changes_requested", notes="...")
+```
+
+## N:N Goal-Task DAGs
+
+Goals and tasks are not 1:1. One task can serve multiple goals:
+
+```
+task_link_goal(task_id="t1", goal_id="g1")   — add link
+task_link_goal(task_id="t1", goal_id="g2")   — same task, second goal
+task_unlink_goal(task_id="t1", goal_id="g2") — remove link
+
+task_bulk_link_goal(task_ids="t1,t2,t3", goal_ids="g1,g2")  — cross-product link
+```
+
+### DAG design rules
+
+1. **Foundation tasks** (shared across goals) → link to all goals via `task_link_goal`
+2. **Integration tasks** (wire goal outputs together) → link to both goals
+3. **Goal-specific tasks** → link to single goal only
+4. **Tasks with no goal** → flagged as "Orphans" in `orient()`
+
+### Dependency types
+
+```
+task_add(deps="taskid:FS,taskid2:SS")
+```
+
+| Type | Meaning |
+|---|---|
+| `FS` | Finish-to-Start (default) — dep must complete before task starts |
+| `FF` | Finish-to-Finish — task finishes when dep finishes |
+| `SS` | Start-to-Start — task starts when dep starts |
+| `SF` | Start-to-Finish — task finishes when dep starts (rare) |
+
+## Rail Policies (Agent Lanes)
+
+Narrow what an agent can work on:
+
+```
+rail_policy_set(phase_ids="phase1,phase2", category_ids="cat1", task_tags='["parser","security"]')
+```
+
+The agent can only:
+- Focus on tasks in phase1 or phase2
+- Work on tasks tagged "parser" or "security"
+- Access context items in category cat1
+
+## Enforcement Rules
+
+```
+rule_add(kind="read_limit", threshold_json='{"max_per_file": 1}')
+rule_add(kind="tool_limit", threshold_json='{"max": 30}')
+rule_add(kind="retry_limit", threshold_json='{"failures": 1}')
+rule_add(kind="block_list", threshold_json='{"paths": ["*.gen.*", "*.min.js"]}')
+rule_add(kind="test_required", threshold_json='{"paths": ["src/db.py"]}')
+
+rule_list()           — view active rules
+rule_update(id, ...)  — modify a rule
+rule_remove(id)       — delete a rule
+
+# Rules auto-derive from lessons:
+learn(content="Never read *.gen.ts files", kind="pitfall")
+# → auto-creates block_list rule for *.gen.ts
+```
+
+## Handoffs
+
+```
+handoff(task_id="t1", to="agent-name", note="Handing over parser work")
+```
+
+Transfers task ownership. Pass `agent_id` to also clock the recipient into the task and record them in the agents table.
+
+## Conflict Detection
+
+When two agents edit the same task, `focus()` returns a `conflict_warning`:
+```json
+{"edited_by": "agent-2", "edited_at": "2026-06-24T...",
+ "message": "This task was last modified by a different agent. Review before continuing."}
+```
+
+## Common Orchestration Pitfalls
+
+| Pitfall | Fix |
+|---|---|
+| Orchestrator depth exceeds 2 | Split into separate delegation calls |
+| More than 5 concurrent tasks | Batch in groups of ≤5 |
+| High-risk task without review | `task_add(lane="high_risk")` auto-sets `review_required=true` |
+| Orphan tasks (no goal) | Link to goal with `task_link_goal` |
+| Dead subagent output not verified | `review()` the output before marking task done |

context_rail-0.2.2/src/context_rail/skills/setup/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: context-rail-setup
+description: "Set up and manage Context Rail in a project — project creation, workspace binding, skill loading, installation, upgrades."
+version: 1.0.0
+author: Context Rail
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [Context-Rail, Setup, Project-Management, Skills, Installation]
+    related_skills: [context-rail-daily, context-rail-governance, context-rail-orchestration]
+---
+
+# Context Rail — Project Setup & Management
+
+Everything needed to set up, configure, upgrade, and understand the Context Rail project context system. Load this when creating a new project, troubleshooting setup, or explaining how Context Rail works.
+
+## Architecture
+
+Context Rail has two layers that work together:
+
+```
+┌────────────────────────────────────────────┐
+│ AGENTS.md  (~22 lines, always loaded)      │
+│   The MAP — compact reference, points to   │
+│   skills for detailed instructions         │
+├────────────────────────────────────────────┤
+│ Skills (loaded on demand, injected into    │
+│   system prompt context)                   │
+│   The GUIDEBOOK — detailed workflows,      │
+│   pitfalls, examples                       │
+├────────────────────────────────────────────┤
+│   context-rail-setup       ← YOU ARE HERE  │
+│   context-rail-daily       ← daily workflow│
+│   context-rail-governance  ← planning/PDCA  │
+│   context-rail-orchestration ← multi-agent  │
+└────────────────────────────────────────────┘
+```
+
+AGENTS.md is auto-generated by `context-rail init` or `context-rail update`.
+Skills are auto-copied to `.agents/skills/context-rail/` in the current project.
+
+## Creating a New 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
+
+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)
+
+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
+```
+
+### 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
+```
+
+## Workspace Binding (how agents resolve projects)
+
+Context Rail resolves the active project from the agent's current working directory:
+
+| 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 |
+
+All 113 MCP tools use `resolve_pid_for_tool(workdir, agent_id)` first, then fall back to `load_state()`. Workspace bindings take priority.
+
+## Loading Skills
+
+```
+skill_view("context-rail-daily")         — load daily capture workflow
+skill_view("context-rail-governance")    — load governance patterns
+skill_view("context-rail-orchestration") — load multi-agent patterns
+skill_view("context-rail-setup")         — load this setup guide
+```
+
+### When to load each skill
+
+| Situation | Load |
+|---|---|
+| Starting any session | context-rail-daily |
+| Starting a planned phase / brainstorm | context-rail-governance |
+| Splitting work across agents | context-rail-orchestration |
+| Setting up a new project | context-rail-setup |
+| Troubleshooting Context Rail itself | context-rail-setup |
+| Explaining the system to someone | context-rail-setup |
+
+AGENTS.md tells you which skills exist and when to load them. Skills contain the detailed instructions.
+
+## Understanding a Project's State
+
+```
+orient()
+→ Project name, status, phase progress, roadmaps
+→ Recently Captured context items
+→ Alerts: blocked goals, stale tasks, unverified items, pending retros
+→ Active enforcement rules and session counters
+→ Active plan contract and autonomy run status
+
+focus(task_id)
+→ Full task detail + context_pack with inherited context items
+→ Related lessons, decisions, enforcement rules
+→ Recommended reads (lane-aware: tiny/normal/high_risk)
+
+find("keyword")
+→ Searches ALL tables: tasks, goals, lessons, context_items,
+  project_notes, risks, artifacts, decisions
+→ Use before search_files() or read_file() to avoid re-discovery
+```
+
+## Installation & Updates
+
+### Fresh install
+
+```
+pip install git+https://github.com/nguyenhoanhson797/Context-Rail.git
+context-rail init
+```
+
+### Update
+
+```
+context-rail update
+```
+
+Both `init` and `update`:
+1. Initialize/verify the database
+2. Generate/refresh AGENTS.md in the current directory
+3. Copy skills to `.agents/skills/context-rail/`
+
+### Verify installation
+
+```
+python -m context_rail status
+→ Shows project count, active project, active task
+```
+
+### MCP client config
+
+```
+context-rail config
+→ Prints JSON config for MCP client
+→ Use `command: C:/Python313/python.exe, args: [-m, context_rail, serve]`
+```
+
+## Multiple Projects
+
+```
+project_list()
+→ Lists all projects with task counts and completion percentages
+
+project_set_active(project_id="...", workdir="/another/repo")
+→ Switch active project for a different workspace
+
+project_list(include_deleted=True)
+→ Shows soft-deleted projects (can be restored)
+```
+
+Each workspace can be bound to a different project. Agents in `/repo-a` get project A, agents in `/repo-b` get project B.
+
+## Project Lifecycle Management
+
+```
+project_update(name="New Name", description="Updated desc")  — rename/re-describe
+project_budget(budget="high")                                 — set expansion budget (small/medium/high/max)
+project_delete()                                              — soft-delete (recoverable)
+project_restore()                                             — restore soft-deleted project
+project_hard_delete()                                         — permanent delete (cannot undo)
+```
+
+## Troubleshooting
+
+### orient() shows ⚠ unbound
+
+```
+project_login(project_id="...", agent_id="...", workdir="/path/to/repo")
+```
+
+### Find() returns empty for known facts
+
+1. Was the fact saved via `note()` or `context_add()`?
+2. `orient()` → check "Recently Captured" section
+3. `context_list(scope_type="project")` → verify the item exists
+4. If saved before the usability fix, it may be in `project_notes` or `task_context` (older tables)
+
+### MCP server not responding
+
+1. Check config: `context-rail config` — verify command and args
+2. Restart MCP server (quit and restart Hermes, or restart the MCP process)
+3. Check database: `python -m context_rail status`
+
+### Skills not appearing in your project
+
+1. Run `context-rail init` to regenerate skills
+2. Verify files exist: `ls .agents/skills/context-rail/`
+3. Restart your agent to pick up new skills
+
+### "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
+2. Call `project_set_active(workdir="/path/to/repo")` first
+3. Report the tool name — it may still need the workspace binding fix
+
+## Capturing Project Context (the full flow)
+
+```
+Session start:
+  orient(workdir="/path/to/repo")
+  → "Recently Captured: Run Commands, Test Patterns"
+  → Gap alert if 0 context items
+
+  find("task keywords")
+  → Search ALL tables before working
+
+  focus()
+  → Get task with context_pack
+
+Work:
+  Discover a fact → note(content, kind="reference")
+  Learn a lesson → learn(content, kind="pattern")
+  Make a decision → decision_create(question, choice, rationale)
+
+Complete:
+  done(task_id)  →  soft gate if context items untouched
+
+Next session:
+  orient() → sees the saved facts → trusts the system → saves more
+```
+
+## The Memory Boundary
+
+```
+Project facts    → note()        → context_items (searchable, scoped, shared)
+Environment facts → memory()      → agent memory (auto-injected, per-agent)
+```
+
+If you save a run command to memory(), it's invisible to find(), not scoped to the project, not shared across agents. When in doubt: project fact = note().