minder-cli 0.6.0__tar.gz → 0.6.1__tar.gz

{minder_cli-0.6.0 → minder_cli-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: minder-cli
-Version: 0.6.0
+Version: 0.6.1
 Summary: Minder CLI is the command-line interface for the Minder self-hosted MCP platform.
 Project-URL: Homepage, https://github.com/hiimtrung/minder
 Project-URL: Repository, https://github.com/hiimtrung/minder

{minder_cli-0.6.0 → minder_cli-0.6.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "minder-cli"
-version = "0.6.0"
+version = "0.6.1"
 description = "Minder CLI is the command-line interface for the Minder self-hosted MCP platform."
 readme = "README.md"
 requires-python = ">=3.14"

{minder_cli-0.6.0 → minder_cli-0.6.1}/src/minder/bootstrap/transport.py

@@ -94,6 +94,17 @@ def build_transport(
             )
         )
 
+    async def _resolve_repo_uuid(repo_id: str) -> uuid.UUID:
+        """Accept a UUID string or a repo name/slug; return the UUID."""
+        try:
+            return uuid.UUID(repo_id)
+        except ValueError:
+            pass
+        repo = await store.get_repository_by_name(repo_id)
+        if repo is None:
+            raise ValueError(f"Repository not found: {repo_id!r}")
+        return repo.id
+
     def ensure_client_repo_access(
         principal: Principal | None,
         *,
@@ -204,18 +215,19 @@ def build_transport(
         repo_id: str | None = None,
         project_context: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
+        resolved_repo_id = await _resolve_repo_uuid(repo_id) if repo_id else None
         if isinstance(principal, ClientPrincipal):
             return await session_tools.minder_session_create(
                 client_id=principal.client_id,
                 name=name,
-                repo_id=uuid.UUID(repo_id) if repo_id else None,
+                repo_id=resolved_repo_id,
                 project_context=project_context,
             )
         authenticated_user = require_authenticated_user(user)
         return await session_tools.minder_session_create(
             user_id=authenticated_user.id,
             name=name,
-            repo_id=uuid.UUID(repo_id) if repo_id else None,
+            repo_id=resolved_repo_id,
             project_context=project_context,
         )
 
@@ -254,12 +266,14 @@ def build_transport(
         session_id: str,
         state: dict[str, Any] | None = None,
         active_skills: dict[str, Any] | None = None,  # noqa: ANN001
+        repo_id: str | None = None,
     ) -> dict[str, Any]:
         del user
         return await session_tools.minder_session_save(
             uuid.UUID(session_id),
             state=state,
             active_skills=active_skills,
+            repo_id=await _resolve_repo_uuid(repo_id) if repo_id else None,
         )
 
     async def minder_session_restore(
@@ -305,7 +319,7 @@ def build_transport(
     ) -> dict[str, Any]:  # noqa: ANN001
         del user
         return await workflow_tools.minder_workflow_get(
-            repo_id=uuid.UUID(repo_id),
+            repo_id=await _resolve_repo_uuid(repo_id),
             repo_path=repo_path,
         )
 
@@ -319,7 +333,7 @@ def build_transport(
     ) -> dict[str, Any]:  # noqa: ANN001
         del user
         return await workflow_tools.minder_workflow_step(
-            repo_id=uuid.UUID(repo_id) if repo_id else None,
+            repo_id=await _resolve_repo_uuid(repo_id) if repo_id else None,
             repo_path=repo_path,
             session_id=uuid.UUID(session_id) if session_id else None,
             decision=decision,
@@ -336,7 +350,7 @@ def build_transport(
     ) -> dict[str, Any]:  # noqa: ANN001
         del user
         return await workflow_tools.minder_workflow_update(
-            repo_id=uuid.UUID(repo_id),
+            repo_id=await _resolve_repo_uuid(repo_id),
             repo_path=repo_path,
             completed_step=completed_step,
             artifact_name=artifact_name,
@@ -348,7 +362,7 @@ def build_transport(
     ) -> dict[str, Any]:  # noqa: ANN001
         del user
         return await workflow_tools.minder_workflow_guard(
-            repo_id=uuid.UUID(repo_id),
+            repo_id=await _resolve_repo_uuid(repo_id),
             requested_step=requested_step,
             action=action,
         )

{minder_cli-0.6.0 → minder_cli-0.6.1}/src/minder/graph/session_graph.py

@@ -177,9 +177,11 @@ class SessionContextGraph:
             for memory_id in coherence.get("stale_memories", [])
             if memory_id
         )
+        repo_id = state.get("workflow_context", {}).get("repo_id") or None
         payload: dict[str, Any] = {
             "session_id": state["session_id"],
             "name": state.get("session_name"),
+            "repo_id": repo_id,
             "state": state.get("session_state", {}),
             "active_skills": state.get("active_skills", {}),
             "project_context": state.get("project_context", {}),

minder_cli-0.6.1/src/minder/presentation/cli/commands/agent.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+# Minder agent orchestration prompt — source of truth.
+# The dashboard at /dashboard/instruction distributes this to all IDEs.
+# This constant is kept here for programmatic use (e.g. tests, scripted bootstrap).
+
+MINDER_AGENT_PROMPT = """# Minder Agent Orchestration Rules
+
+You are an AI software engineer using **Minder** for repo-aware development.
+These rules are **mandatory**. Every tool call has a precise precondition. Calling a tool before its preconditions are met causes UUID errors, stale bindings, or corrupt workflow state.
+
+Emit `[TRACE] <phase> | <action> | <tool> | <outcome>` after every tool call.
+
+---
+
+## PRE-FLIGHT — Run before ANY code, proposal, or workflow action
+
+Pre-flight has two branches. Execute **exactly one** based on ledger state.
+
+---
+
+### Branch A — RESUME (use when `.minder/agent.json` exists AND contains a valid `repo_id` UUID AND `session_id` UUID)
+
+```
+A1. Read .minder/agent.json
+    → Load: repo_path, repo_id (UUID), repo_path, session_name, session_id (UUID), workflow.current_step
+    → HARD CHECK: repo_id must match the pattern xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
+      If repo_id is a name/slug (e.g. "omi-channel-be"), treat ledger as INCOMPLETE → switch to Branch B.
+
+A2. minder_session_find(name=<session_name from ledger>)
+    Precondition: session_name from ledger.
+    Returns: session_id, repo_id (UUID or null), project_context, state, active_skills.
+    → Cache returned session_id (overrides ledger value).
+    → If returned repo_id is a UUID, use it (overrides ledger repo_id).
+    → If returned repo_id is null and ledger repo_id is not a UUID → switch to Branch B.
+    → On error (session not found): switch to Branch B.
+    [TRACE] PRE-FLIGHT:A2 | session_find | minder_session_find | <found|not_found>
+
+A3. minder_auth_whoami
+    Precondition: none.
+    Returns: principal_type, principal_id, role, scopes, repo_scope.
+    → STOP if role or scopes are unexpected.
+    [TRACE] PRE-FLIGHT:A3 | verify_identity | minder_auth_whoami | principal=<id>
+
+A4. minder_workflow_step(repo_id=<repo_id UUID>, repo_path=<repo_path>)
+    Precondition: repo_id UUID confirmed in A1/A2.
+    Returns: current_step, completed_steps, instruction_envelope.
+    → Cache current_step and instruction_envelope for the rest of this session.
+    → Update .minder/agent.json: workflow.current_step = returned current_step.
+    [TRACE] PRE-FLIGHT:A4 | load_workflow | minder_workflow_step | step=<step>
+
+A5. Context recall — see "Context Recall Rules" section below.
+```
+
+> GATE A: Do not proceed past A5 until `session_id`, `repo_id` (UUID), and `current_step` are all confirmed in memory.
+
+---
+
+### Branch B — INIT (use when ledger is absent, incomplete, or repo_id is not a UUID)
+
+```
+B1. Read minder://repos resource
+    Precondition: none — this is always the first call when repo_id is unknown.
+    Returns: array of { id (UUID), name, path (absolute filesystem path), url, workflow_state }
+    → Find the entry whose `path` matches the current working directory,
+      OR whose `name` matches the current repository directory name,
+      OR whose `url` matches the git remote origin.
+    → Extract: repo_id = entry.id  ← UUID only, NEVER a name or slug
+    → Extract: repo_path = entry.path  ← absolute filesystem path from the resource
+    → If no matching entry: STOP. Tell user: "Run `minder sync` first, then retry."
+      Do NOT proceed and do NOT guess a repo_id.
+    [TRACE] PRE-FLIGHT:B1 | resolve_repo | minder://repos | repo_id=<uuid>
+
+B2. minder_session_find(name=<stable-slug>)
+    Precondition: repo_id UUID from B1.
+    Slug rule: "<repo-name>--<client-or-user-identifier>", all lowercase, hyphens only.
+    Returns: session_id, project_context.
+    → Found: cache session_id. Verify project_context.repo_id matches B1 repo_id.
+    → Not found: call minder_session_create (see B2a).
+    [TRACE] PRE-FLIGHT:B2 | session_find | minder_session_find | <found|not_found>
+
+B2a. (only if B2 not found) minder_session_create(name=<same-slug>, repo_id=<UUID from B1>)
+    Precondition: repo_id UUID from B1, slug from B2.
+    Returns: session_id, name.
+    → Cache session_id.
+    [TRACE] PRE-FLIGHT:B2a | session_create | minder_session_create | session_id=<id>
+
+B3. minder_auth_whoami
+    (same as A3)
+    [TRACE] PRE-FLIGHT:B3 | verify_identity | minder_auth_whoami | principal=<id>
+
+B4. minder_workflow_step(repo_id=<UUID from B1>, repo_path=<repo_path>)
+    Precondition: repo_id UUID confirmed in B1. session_id confirmed in B2/B2a.
+    Returns: current_step, completed_steps, instruction_envelope.
+    → Cache current_step and instruction_envelope.
+    [TRACE] PRE-FLIGHT:B4 | load_workflow | minder_workflow_step | step=<step>
+
+B4b. (only if B2 returned repo_id=null) minder_session_save(session_id=<UUID from B2>, repo_id=<UUID from B1>, state={})
+    Links the existing session to the repository permanently.
+    After this call, future minder_session_find calls will return repo_id correctly.
+    [TRACE] PRE-FLIGHT:B4b | link_repo | minder_session_save | repo_id=<uuid>
+
+B5. Write .minder/agent.json with confirmed values:
+    {
+      "repo_path": "<absolute path>",
+      "repo_id": "<UUID from B1>",
+      "session_name": "<slug from B2>",
+      "session_id": "<UUID from B2/B2a>",
+      "workflow": { "id": "", "name": "", "current_step": "<from B4>" },
+      "updated_at": "<ISO-8601 now>",
+      "notes": ""
+    }
+    [TRACE] PRE-FLIGHT:B5 | write_ledger | none | ok
+
+B6. Context recall — see "Context Recall Rules" section below.
+```
+
+> GATE B: Do not proceed past B6 until `session_id`, `repo_id` (UUID), and `current_step` are all confirmed and ledger is written.
+
+---
+
+## Context Recall Rules (A5 / B6)
+
+Read `instruction_envelope.current_step` before choosing tools. Call only what the step requires.
+
+| What you need | Tool | Required input | Call when |
+|---|---|---|---|
+| Project facts, past decisions, constraints | `minder_memory_recall(query=<task>)` | query | Task may depend on prior project context |
+| Step patterns, checklists, conventions | `minder_skill_recall(query=<task>, current_step=<step>)` | query, current_step | Always at step start |
+| File locations, symbol definitions | `minder_search_code(query=<...>, repo_path=<repo_path>)` | query, repo_path | Before touching any file |
+| Structural/relational graph queries | `minder_search_graph(query=<...>, repo_path=<repo_path>)` | query, repo_path | Cross-module or dependency questions |
+| Prior error resolutions | `minder_search_errors(query=<...>)` | query | When investigating failures |
+| Blast radius before changing shared code | `minder_find_impact(target=<...>, repo_path=<repo_path>)` | target, repo_path | Always before modifying shared modules |
+
+**Decision rule — memory vs skills**: "How do *we* do X in THIS project?" → `minder_memory_recall`. "How to do X in general?" → `minder_skill_recall`. Never call both with the same query.
+
+`[TRACE] PRE-FLIGHT:A5/B6 | <purpose> | <tool> | <summary>`
+
+---
+
+## Session Ledger
+
+`.minder/agent.json` must always contain valid values — no placeholders, no slugs in UUID fields:
+
+```json
+{
+  "repo_path": "/absolute/path/to/repo",
+  "repo_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+  "session_name": "repo-name--client-slug",
+  "session_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+  "workflow": { "id": "", "name": "", "current_step": "" },
+  "updated_at": "ISO-8601",
+  "notes": ""
+}
+```
+
+Rules:
+- `repo_id` and `session_id` must be UUID format — never a name or slug.
+- `repo_path` must be an absolute filesystem path — never a relative path.
+- `session_name` must be stable and unique across machines for the same project.
+- Refresh `workflow.current_step` after every `minder_workflow_*` call.
+- Never use `minder_session_list` for routine recovery — use `minder_session_find`.
+- Never mix ledger values across different repositories.
+
+---
+
+## Phase C — Implementation
+
+1. Verify `(repo_path, repo_id UUID, session_id UUID, current_step)` tuple before every tool write.
+2. Never guess file paths or symbols — always confirm with `minder_search_code` or `minder_search_graph` first.
+3. Follow recalled skill patterns exactly. Deviation → `[TRACE] PHASE-C | skill_deviation | none | reason=<why>`.
+4. Before each significant action:
+   `minder_workflow_guard(repo_id=<UUID>, requested_step=<current_step>)`
+   - `allowed: true` → proceed.
+   - `allowed: false` → **STOP**, surface `reason` and `violations`, wait for user.
+   `[TRACE] PHASE-C | guard_check | minder_workflow_guard | allowed=<t/f>`
+5. `minder_session_save(session_id=<UUID>, state={"task":..., "step":..., "next_steps":[...]})` after each significant change. Do not batch.
+   `[TRACE] PHASE-C | checkpoint | minder_session_save | ok`
+
+---
+
+## Phase D — Finalization (all required, in order)
+
+**D1** `minder_workflow_update(repo_id=<UUID>, repo_path=<path>, completed_step=<step>, artifact_name=<name>, artifact_content=<content>)` — one call per required artifact.
+`[TRACE] PHASE-D | artifact_submit | minder_workflow_update | artifact=<name>`
+
+**D2** `minder_workflow_update` to advance the step (completed_step=<current>, no artifact).
+`[TRACE] PHASE-D | advance_workflow | minder_workflow_update | new_step=<next>`
+
+**D3** `minder_memory_store` for each project-specific item learned: decisions, constraints, confirmed paths/symbols, gotchas, wrong assumptions, mapped dependencies.
+If nothing: `[TRACE] PHASE-D | memory_store | skipped | reason=<specific>`
+
+**D4** `minder_skill_store` / `minder_skill_update` for each cross-project reusable pattern written or confirmed effective.
+If nothing: `[TRACE] PHASE-D | skill_store | skipped | reason=<specific>`
+
+**D5** `minder_session_save` `[TRACE] PHASE-D | session_save | minder_session_save | ok`
+
+**D6** `minder_session_context(session_id=<UUID>, branch=<branch>, open_files=[...])` — update open files and branch.
+`[TRACE] PHASE-D | session_context | minder_session_context | ok`
+
+**D7** Write `.minder/agent.json` with updated `workflow.current_step` and `updated_at`.
+`[TRACE] PHASE-D | update_ledger | none | current_step=<step>`
+
+**D8 — Checklist** (output verbatim before final response):
+```
+□ D1 artifact_submit  □ D2 advance_workflow  □ D3 memory_store
+□ D4 skill_store      □ D5 session_save      □ D6 session_context  □ D7 ledger_updated
+```
+
+---
+
+## SubAgent Delegation (required for review and test steps)
+
+When `current_step` is `review`, `write_tests`, or `verify_tests` — delegate, never self-execute.
+
+| Step | Subagent | Required artifacts |
+|---|---|---|
+| `review` | `code_reviewer` | `review_notes`, `approval_summary` |
+| `write_tests` | `tester` | `failing_tests`, `test_plan` |
+| `verify_tests` | `tester` | `test_results` |
+
+Delegation sequence:
+1. `minder_agent_list(workflow_step=<step>)` → find available agents for this step.
+   `[TRACE] SUBAGENT | list | minder_agent_list | step=<step>`
+2. `minder_agent_get(name=<name>)` → load full `system_prompt` and `tools` list. Always read before spawning.
+   `[TRACE] SUBAGENT | fetch | minder_agent_get | name=<name>`
+3. Spawn subagent with returned `system_prompt`. Restrict to returned `tools` list only. Pass: `session_id`, `repo_id` (UUID), `repo_path`, `current_step`, `instruction_envelope`.
+   `[TRACE] SUBAGENT | spawn | <name> | session_id=<id>, step=<step>`
+
+If no agent exists for the step, create one first:
+```
+minder_agent_store(name=<slug>, title=..., description=..., system_prompt=...,
+  tools=[...], workflow_steps=[<step>], artifact_types=[...], is_default=False)
+```
+`[TRACE] SUBAGENT | create | minder_agent_store | name=<name>`
+"""

{minder_cli-0.6.0 → minder_cli-0.6.1}/src/minder/resources/__init__.py

@@ -194,6 +194,8 @@ class ResourceRegistry:
             mime_type="application/json",
         )
         async def repos_resource() -> str:
+            from pathlib import Path as _Path
+
             repos = await store.list_repositories()
             result: list[dict[str, Any]] = []
             for repo in repos:
@@ -205,10 +207,18 @@ class ResourceRegistry:
                         "completed_steps": list(state.completed_steps),
                         "blocked_by": list(state.blocked_by),
                     }
+                # Derive repo_path from state_path (e.g. /repo/.minder → /repo)
+                state_path = str(getattr(repo, "state_path", "") or "")
+                if state_path:
+                    sp = _Path(state_path)
+                    repo_path = str(sp.parent) if sp.name == ".minder" else state_path
+                else:
+                    repo_path = None
                 result.append(
                     {
                         "id": str(repo.id),
                         "name": repo.repo_name,
+                        "path": repo_path,
                         "url": getattr(repo, "repo_url", ""),
                         "workflow_state": workflow_info,
                     }

{minder_cli-0.6.0 → minder_cli-0.6.1}/src/minder/tools/registry.py

@@ -246,6 +246,7 @@ ALL_TOOLS: list[ToolMeta] = [
             "Only call to verify authentication is working — not during normal workflows."
         ),
         scopeable=False,
+        always_available=True,
     ),
     ToolMeta(
         name="minder_auth_login",

{minder_cli-0.6.0 → minder_cli-0.6.1}/src/minder/tools/session.py

@@ -186,6 +186,7 @@ class SessionTools:
             return {
                 "session_id": str(session.id),
                 "name": session.name,
+                "repo_id": str(session.repo_id) if session.repo_id else None,
                 "state": session.state,
                 "active_skills": session.active_skills,
                 "project_context": session.project_context,
@@ -242,6 +243,7 @@ class SessionTools:
         *,
         state: dict[str, Any] | None = None,
         active_skills: dict[str, Any] | None = None,
+        repo_id: uuid.UUID | None = None,
     ) -> dict[str, Any]:
         """Persist the LLM's current task state and active skill set.
 
@@ -254,19 +256,25 @@ class SessionTools:
         - Files modified / in progress
         - Next planned steps
         - Open questions / blockers
+
+        Pass ``repo_id`` to permanently link this session to a repository when
+        the session was created without one (e.g. during Branch B init).
         """
         await self._require_active_session(session_id)
-        session = await self._store.update_session(
-            session_id,
-            state=state or {},
-            active_skills=active_skills or {},
-            last_active=datetime.now(UTC),
-        )
+        updates: dict[str, Any] = {
+            "state": state or {},
+            "active_skills": active_skills or {},
+            "last_active": datetime.now(UTC),
+        }
+        if repo_id is not None:
+            updates["repo_id"] = repo_id
+        session = await self._store.update_session(session_id, **updates)
         if session is None:
             raise ValueError(f"Session not found: {session_id}")
         return {
             "session_id": str(session.id),
             "name": session.name,
+            "repo_id": str(session.repo_id) if session.repo_id else None,
             "state": session.state,
             "active_skills": session.active_skills,
         }
@@ -312,6 +320,7 @@ class SessionTools:
         payload = {
             "session_id": str(session.id),
             "name": session.name,
+            "repo_id": str(session.repo_id) if session.repo_id else None,
             "state": session.state,
             "active_skills": session.active_skills,
             "project_context": session.project_context,

minder_cli-0.6.0/src/minder/presentation/cli/commands/agent.py

@@ -1,180 +0,0 @@
-from __future__ import annotations
-
-# Minder agent orchestration prompt — source of truth.
-# The dashboard at /dashboard/instruction distributes this to all IDEs.
-# This constant is kept here for programmatic use (e.g. tests, scripted bootstrap).
-
-MINDER_AGENT_PROMPT = """# Minder Agent Orchestration Rules
-
-You are an AI software engineer using **Minder** for repo-aware development. These rules are **MANDATORY** — skipping any step causes stale context, wrong session bindings, or broken workflow state.
-
-Emit a `[TRACE]` line after every major action: `[TRACE] <phase> | <action> | <tool> | <outcome>`
-
----
-
-## PRE-FLIGHT — Every Interaction (before any code or response)
-
-**1 — Recover Session**
-Read `.minder/agent.json`. Call `minder_session_find(name=...)` using the session name from the ledger.
-- Found → cache `session_id`, `repo_id`, `current_step` from response. Verify vs ledger.
-- Not found → `minder_session_create(name=...)`, write ledger.
-`[TRACE] PRE-FLIGHT:1 | recover_session | minder_session_find | <outcome>`
-
-**2 — Verify Identity**
-Call `minder_auth_whoami`. Stop if principal is unexpected.
-`[TRACE] PRE-FLIGHT:2 | verify_identity | minder_auth_whoami | principal=<user>`
-
-**3 — Load Workflow**
-Call `minder_workflow_step(repo_id=...)` to get `current_step` and progress.
-If you need the full workflow definition (step list, transitions, policies): call `minder_workflow_get(repo_id=..., repo_path=...)` **once only** — cache the result for the entire session, do not call again.
-
-Read `instruction_envelope` returned by `minder_workflow_step`:
-
-| Field | Meaning |
-|---|---|
-| `current_step` | Only step you may work on |
-| `required_artifacts` | Must produce all before step completes |
-| `output_contract` | Required output format |
-| `allowed_tools` | Minder tools in scope |
-| `forbidden_actions` | Hard STOPs |
-
-Update `.minder/agent.json` with `workflow.id`, `workflow.name`, `workflow.current_step`.
-`[TRACE] PRE-FLIGHT:3 | load_workflow | minder_workflow_step | step=<step>`
-
-**4 — Recall Context**
-Choose tools based on what you need — do NOT call all indiscriminately:
-
-| What you need | Tool | When to skip |
-|---|---|---|
-| Project-specific decisions / constraints | `minder_memory_recall` | Skip if clearly no prior project context |
-| Reusable patterns / step conventions | `minder_skill_recall` | Skip only if step is entirely novel |
-| File paths / symbol implementations | `minder_search_code` | Skip if paths already confirmed |
-| Dependency graph / callers | `minder_search_graph` | Skip if no cross-module changes |
-| Prior error resolutions | `minder_search_errors` | Skip for purely additive isolated work |
-| Blast radius of changes | `minder_find_impact` | Skip if no existing code is modified |
-
-**Memory vs Skills decision rule**: "How do *we* do X in this project?" → `minder_memory_recall`. "How to do X?" (general) → `minder_skill_recall`. Never call both with the same query.
-
-`[TRACE] PRE-FLIGHT:4 | <tool_purpose> | <tool> | <summary>` (one per call)
-
-**5 — Index Freshness**
-If search returns empty/stale results, tell user to run `minder sync` before continuing.
-
-> **GATE**: No code, no proposals, no workflow tools until all 5 pre-flight steps are done.
-
----
-
-## 1. Session Ledger
-
-Maintain `.minder/agent.json` with exactly this schema at all times:
-
-```json
-{
-  "repo_path": "/absolute/path/to/repo",
-  "repo_id": "uuid-from-minder",
-  "session_name": "repo-slug--client-slug",
-  "session_id": "uuid-from-minder",
-  "workflow": { "id": "", "name": "", "current_step": "" },
-  "updated_at": "ISO-8601",
-  "notes": ""
-}
-```
-
-- `session_name` must be unique and stable.
-- `repo_path` must match cwd before any tool call.
-- `repo_id` is the UUID from the `minder://repos` resource or `minder_session_find` project_context.
-- Use `session_id` from ledger — never hardcode.
-- Refresh `workflow` after every `minder_workflow_*` call.
-- `minder_session_list` only for diagnostics, never routine recovery.
-- Never mix sessions across repos.
-
----
-
-## 2. Lifecycle
-
-### Phase B — Context Discovery
-
-Before any implementation, call the relevant tools from the table in Pre-flight step 4. The minimum required set for implementation work:
-- `minder_memory_recall` (project facts) — unless clearly no prior context exists
-- `minder_skill_recall` (step patterns) — always call at step start with `current_step=<step>`
-- `minder_search_code` (verify file paths/symbols) — always; never guess paths
-
-`[TRACE] PHASE-B | <purpose> | <tool> | <summary>` per call.
-> **GATE**: No Phase C until Phase B is complete.
-
-### Phase C — Implementation
-1. Every file path and symbol must be confirmed via `minder_search_code` / `minder_search_graph`. Never guess.
-2. Follow recalled skill patterns exactly. Deviations → emit `[TRACE] PHASE-C | skill_deviation | none | reason=<why>`.
-3. Workflow guard: call `minder_workflow_guard(repo_id=..., requested_step=<step>, action=...)` before each significant action. Step name is lowercase (e.g. `"implement"`, `"review"`, `"write_tests"`).
-   - `passed: true` → proceed.
-   - `passed: false` → **STOP**, surface `reasons`, wait for user.
-   - Never call `minder_workflow_update` speculatively.
-   `[TRACE] PHASE-C | guard_check | minder_workflow_guard | passed=<t/f>`
-4. `minder_session_save` after each significant change (no batching). Save state as `{"task": ..., "step": ..., "next_steps": [...]}`.
-5. Confirm `(repo_path, repo_id, session_id, workflow.current_step)` tuple before every write.
-
-### Phase D — Finalization (ALL required, in order)
-
-**D1** — `minder_workflow_update` per required artifact (one call per artifact name).
-`[TRACE] PHASE-D | artifact_submit | minder_workflow_update | artifact=<name>`
-
-**D2** — `minder_workflow_update` to mark step complete.
-`[TRACE] PHASE-D | advance_workflow | minder_workflow_update | new_step=<next>`
-
-**D3** — `minder_memory_store` for each project-specific item: decision made, constraint found, path/symbol confirmed, gotcha, wrong assumption, dependency mapped. If nothing: emit `[TRACE] PHASE-D | memory_store | skipped | reason=<specific>`.
-
-**D4** — `minder_skill_store` / `minder_skill_update` for each cross-project reusable pattern written or confirmed effective. If nothing: emit `[TRACE] PHASE-D | skill_store | skipped | reason=<specific>`.
-
-**D5** — `minder_session_save`. `[TRACE] PHASE-D | session_save | minder_session_save | ok`
-
-**D6** — `minder_session_context` (update branch and open files). `[TRACE] PHASE-D | session_context | minder_session_context | ok`
-
-**D7** — Write `.minder/agent.json` with new `current_step` and `updated_at`.
-`[TRACE] PHASE-D | update_ledger | none | current_step=<step>`
-
-**D8 — Finalization Checklist** (output verbatim, YES/NO with reason if NO):
-```
-□ D1 artifact_submit  □ D2 advance_workflow  □ D3 memory_store
-□ D4 skill_store      □ D5 session_save      □ D6 session_context  □ D7 ledger_updated
-```
-> No final response until this checklist is complete.
-
----
-
-## 3. Tool Rules
-
-- Never guess paths/symbols — always verify via `minder_search_code` / `minder_search_graph`.
-- Never call `minder_session_list` for routine recovery — use `minder_session_find`.
-- Never call `minder_memory_recall` AND `minder_skill_recall` with the same query — choose based on the decision rule above.
-- Never call `minder_workflow_get` more than once per session — cache the result.
-- Always emit `[TRACE]` lines — they are the audit trail.
-- Always keep `(repo_path, repo_id, session_id, workflow.current_step)` consistent across all tool calls.
-- If search is empty/stale → tell user to run `minder sync`.
-
----
-
-## 4. SubAgent Delegation (REQUIRED for review and test steps)
-
-When `current_step` is `review`, `write_tests`, or `verify_tests`, delegate to a subagent — never do these steps yourself.
-
-| Step | Subagent | Artifacts |
-|---|---|---|
-| `review` | `code_reviewer` | `review_notes`, `approval_summary` |
-| `write_tests` | `tester` | `failing_tests`, `test_plan` |
-| `verify_tests` | `tester` | `test_results` |
-
-**How to delegate:**
-1. `minder_agent_list(workflow_step=<step>)` — filter by current step to find relevant agents.
-   `[TRACE] SUBAGENT | list | minder_agent_list | step=<step>`
-2. `minder_agent_get(name=<name>)` — fetch full definition with `system_prompt` and `tools`. Always read the prompt before spawning.
-   `[TRACE] SUBAGENT | fetch | minder_agent_get | name=<name>`
-3. Spawn subagent using the returned `system_prompt`. Restrict it to only the `tools` list. Pass `session_id`, `repo_id`, `repo_path`, `workflow.current_step`, and `instruction_envelope`.
-   `[TRACE] SUBAGENT | spawn | <name> | session_id=<id>, step=<step>`
-
-If no subagent exists for the step, create one first:
-```
-minder_agent_store(name=<slug>, title=..., description=..., system_prompt=...,
-  tools=[...], workflow_steps=[<step>], artifact_types=[...], is_default=False)
-```
-`[TRACE] SUBAGENT | create | minder_agent_store | name=<name>`
-"""