mcp-phase-gate 2.0.1 → 2.2.0

package/README.md

@@ -34,7 +34,7 @@ flowchart TD
 
 And between one phase and the next there is a **gate**, which is what gives the server its name: ask for a phase while skipping the previous one and the server notices and warns you ([see below](#-the-gate-skipping-a-phase-stops-being-invisible)).
 
-In phase 5 the AI only reads. **You always make the commits and open the PR.**
+In phase 4 the AI commits each batch only with your OK; it never pushes or opens the PR. In phase 5 it only reads.
 
 ## Who it's for
 
@@ -59,7 +59,10 @@ DOCUMENTATION/
 │           ├── 01 - Análisis Técnico.md   ← Phase 1
 │           ├── 02 - Decisiones.md         ← Phase 2
 │           ├── 03 - Plan Técnico.md       ← Phase 3
-│           ├── 04 - Ejecución.md          ← Phase 4
+│           ├── 04 - Ejecución/            ← Phase 4, with more than one batch: one receipt each
+│           │   ├── L01 - <slug>.md
+│           │   └── L02 - <slug>.md
+│           ├── 04 - Ejecución.md          ← Phase 4: the receipt, or the index of receipts
 │           └── 05 - Auditoría.md          ← Phase 5
 ├── PROJECT-B/
 │   └── Proyectos/
@@ -69,7 +72,9 @@ DOCUMENTATION/
         └── <task_name>/
 ```
 
-The `Proyectos` level is the tasks subfolder, and its name is configurable — see `ORQUESTADOR_TASKS_SUBDIR` below. The document names come from the phase prompts, which is why they are in Spanish by default.
+The `Proyectos` level is the tasks subfolder, and its name is configurable — see `PHASE_GATE_TASKS_SUBDIR` below. The document names come from the phase prompts, which is why they are in Spanish by default.
+
+**Batches and receipts.** The phase 3 plan splits the work into batches (`L01`, `L02`…): each one is a change that can be reverted on its own and leaves the application working. Phase 4 runs them one at a time and closes each batch with a short **receipt** (what was done, what was verified, what is waiting for you) and a commit. With a single batch, the receipt is `04 - Ejecución.md` itself and there is no subfolder, unless that batch fails or is discarded: then its receipt goes in `04 - Ejecución/` and the phase isn't marked as closed. With several, the receipts go in `04 - Ejecución/` and `04 - Ejecución.md` is the index written when the last one closes: until then the phase doesn't show as finished. When you ask for phase 4 or 5, the server appends the list of existing receipts to the prompt, so a new chat can pick up without guessing their names.
 
 > The server builds this path **automatically**. You (or the LLM) only supply `project`, `task_name` and `file_name`; nobody has to type a full path.
 
@@ -96,7 +101,7 @@ The code is identical everywhere; the only thing that changes between machines i
 
 Nothing to install: `npx` fetches the package the first time and caches it. Everything is configured in your MCP client's file.
 
-**The key you give it is what identifies the server and prefixes its tools**, so you can name it whatever you like. The examples use `mcp-phase-gate`, the same as the npm package and the name the server reports for itself — one name in all three places, so there's nothing to remember.
+**The key you give it is what identifies the server and prefixes its tools and commands**, so you can name it whatever you like. The examples use `mcp-phase-gate`, the same as the npm package and the name the server reports for itself. If you're registering it for the first time, a short key such as `pg` keeps the commands short (`/pg:f1` in Claude Code). **If it's already registered, keep your key**: changing it renames every tool and command, and you'd have to grant their permissions again.
 
 Remember that in JSON every `\` must be doubled as `\\`.
 
@@ -110,8 +115,8 @@ Remember that in JSON every `\` must be doubled as `\\`.
       "command": "npx",
       "args": ["-y", "mcp-phase-gate"],
       "env": {
-        "ORQUESTADOR_DOCS_PATH": "C:\\Users\\YOUR_USER\\OneDrive - YOUR ORGANISATION\\Documents\\DOCUMENTATION",
-        "ORQUESTADOR_REPOS_PATH": "C:\\projects"
+        "PHASE_GATE_DOCS_PATH": "C:\\Users\\YOUR_USER\\OneDrive - YOUR ORGANISATION\\Documents\\DOCUMENTATION",
+        "PHASE_GATE_REPOS_PATH": "C:\\projects"
       }
     }
   }
@@ -132,8 +137,8 @@ Two differences to watch: the top-level key is `servers`, not `mcpServers`, and
       "command": "npx",
       "args": ["-y", "mcp-phase-gate"],
       "env": {
-        "ORQUESTADOR_DOCS_PATH": "C:\\Users\\YOUR_USER\\OneDrive - YOUR ORGANISATION\\Documents\\DOCUMENTATION",
-        "ORQUESTADOR_REPOS_PATH": "C:\\projects"
+        "PHASE_GATE_DOCS_PATH": "C:\\Users\\YOUR_USER\\OneDrive - YOUR ORGANISATION\\Documents\\DOCUMENTATION",
+        "PHASE_GATE_REPOS_PATH": "C:\\projects"
       }
     }
   }
@@ -145,19 +150,21 @@ Two differences to watch: the top-level key is `servers`, not `mcpServers`, and
 <summary><b>Claude Code</b> — one line</summary>
 
 ```bash
-claude mcp add mcp-phase-gate --env ORQUESTADOR_DOCS_PATH="C:\Users\YOUR_USER\Documents\DOCUMENTATION" --env ORQUESTADOR_REPOS_PATH="C:\projects" -- npx -y mcp-phase-gate
+claude mcp add mcp-phase-gate --env PHASE_GATE_DOCS_PATH="C:\Users\YOUR_USER\Documents\DOCUMENTATION" --env PHASE_GATE_REPOS_PATH="C:\projects" -- npx -y mcp-phase-gate
 ```
 
 Or by hand, in a `.mcp.json` at the project root, shaped like the Cursor one.
 </details>
 
-That `ORQUESTADOR_DOCS_PATH` is only an **example** using a OneDrive folder. `G:\My Drive\Documentation`, `D:\Dropbox\Docs` or plain `C:\Docs` with no cloud at all work just as well.
+That `PHASE_GATE_DOCS_PATH` is only an **example** using a OneDrive folder. `G:\My Drive\Documentation`, `D:\Dropbox\Docs` or plain `C:\Docs` with no cloud at all work just as well.
 
 > **There is no `.env` on this route.** The package lives inside `node_modules`, which is no place to keep your configuration, so the paths go in the `"env"` block — that's the only option here. The `.env` file only exists on the route below.
 
 **Both variables are required and have no default value.** If one is missing, or points at a folder that doesn't exist, the tools that need it say so by name instead of failing later for some unrelated-looking reason.
 
-> Typing `npx mcp-phase-gate` straight into a terminal **looks like it hangs**, and nothing is broken: it's an MCP server waiting for messages on stdin. If you just want to check it's there, run `npx mcp-phase-gate --help`.
+> **Already using it with `ORQUESTADOR_*`?** Those names keep working as aliases of `PHASE_GATE_*`; there's nothing to change. If you define both with different values, `PHASE_GATE_*` wins, and `doctor` and the server log tell you.
+
+> Typing `npx mcp-phase-gate` straight into a terminal **looks like it hangs**, and nothing is broken: it's an MCP server waiting for messages on stdin. If you want to check your setup, run `npx mcp-phase-gate doctor` ([see below](#-check-your-setup-doctor)).
 
 ---
 
@@ -183,11 +190,11 @@ cp .env.example .env
 Single backslashes on Windows, no quotes:
 
 ```ini
-ORQUESTADOR_DOCS_PATH=C:\Users\YOUR_USER\OneDrive - YOUR ORGANISATION\Documents\DOCUMENTATION
-ORQUESTADOR_REPOS_PATH=C:\projects
+PHASE_GATE_DOCS_PATH=C:\Users\YOUR_USER\OneDrive - YOUR ORGANISATION\Documents\DOCUMENTATION
+PHASE_GATE_REPOS_PATH=C:\projects
 ```
 
-> On Windows, save `.env` as **UTF-8 without BOM**. Creating it from PowerShell with `>` produces UTF-16, accented characters arrive mangled, and the path "doesn't exist" even though it looks right.
+> Save `.env` as **UTF-8** (with or without BOM, either works). Creating it from PowerShell with `>` produces UTF-16: the server detects it, doesn't load it, and tells you so — both in the missing-variable error and in `doctor`.
 
 **3. Register the server** as in route A, but swapping `command` and `args` for your clone's `build/index.js`, and dropping the `"env"` block (the paths come from `.env` now):
 
@@ -204,8 +211,20 @@ In **Claude Code**, a `.mcp.json` at this repo's root can use a **relative** pat
 
 ### ✅ Verify it works
 1. Restart the client, or toggle the server off and on in its MCP panel.
-2. It should show up active with its 8 tools. In **Cursor** that's Settings → MCP; in **VS Code**, the extensions/MCP view; in **Claude Code**, `/mcp`.
-3. Try it from the chat: *"Use the `get_active_task` tool from mcp-phase-gate"* — it should answer, even if only to say there's no active task yet.
+2. It should show up active with its 9 tools. In **Cursor** that's Settings → MCP; in **VS Code**, the extensions/MCP view; in **Claude Code**, `/mcp`.
+3. Try it from the chat: *"Use the `get_orchestrator_status` tool from mcp-phase-gate"* — it returns an X-ray of the installation: which variables it sees, which prompts it uses and which projects it finds.
+
+### 🔍 Check your setup: `doctor`
+
+From a terminal, with the same variables you give the client:
+
+```bash
+npx mcp-phase-gate doctor
+```
+
+It tells you which version is running and from where (`npx`, global, a dependency or a clone), the value of each variable and where it came from (the environment or `.env`, and whether you used the new name or the alias), which prompt file wins for each phase, which projects exist with their active task, and a list of findings: a missing required variable, a UTF-16 `.env`, a custom `global-rules.md` missing sections the phases cite, a phase with no document… It exits with code `1` if there's any error, so it also works in a script. `doctor --json` gives the same thing as JSON.
+
+It's the same information returned by the `get_orchestrator_status` tool and the `phase-gate://estado` resource; from the chat, it also includes which client is connected and which capabilities it announced.
 
 ---
 
@@ -233,23 +252,23 @@ You may want separate documentation sets that never mix — one for work and one
 ```jsonc
 {
   "mcpServers": {
-    "orquestador-work": {
+    "pg-work": {
       "command": "npx",
       "args": ["-y", "mcp-phase-gate"],
       "env": {
-        "ORQUESTADOR_DOCS_PATH": "C:\\Users\\YOUR_USER\\OneDrive - YOUR ORGANISATION\\Documents\\DOCUMENTATION",
-        "ORQUESTADOR_REPOS_PATH": "C:\\projects",
-        "ORQUESTADOR_STATE_PATH": "C:\\Users\\YOUR_USER\\.orquestador\\work"
+        "PHASE_GATE_DOCS_PATH": "C:\\Users\\YOUR_USER\\OneDrive - YOUR ORGANISATION\\Documents\\DOCUMENTATION",
+        "PHASE_GATE_REPOS_PATH": "C:\\projects",
+        "PHASE_GATE_STATE_PATH": "C:\\Users\\YOUR_USER\\.orquestador\\work"
       }
     },
-    "orquestador-personal": {
+    "pg-personal": {
       "command": "npx",
       "args": ["-y", "mcp-phase-gate"],
       "env": {
-        "ORQUESTADOR_DOCS_PATH": "G:\\My Drive\\Documentation",
-        "ORQUESTADOR_REPOS_PATH": "D:\\dev",
-        "ORQUESTADOR_TASKS_SUBDIR": "",
-        "ORQUESTADOR_STATE_PATH": "C:\\Users\\YOUR_USER\\.orquestador\\personal"
+        "PHASE_GATE_DOCS_PATH": "G:\\My Drive\\Documentation",
+        "PHASE_GATE_REPOS_PATH": "D:\\dev",
+        "PHASE_GATE_TASKS_SUBDIR": "",
+        "PHASE_GATE_STATE_PATH": "C:\\Users\\YOUR_USER\\.orquestador\\personal"
       }
     }
   }
@@ -258,12 +277,12 @@ You may want separate documentation sets that never mix — one for work and one
 
 It's the same package in both — only the paths differ. Each registration can even have its own tasks subfolder; above, the personal one leaves it empty so tasks hang directly off the project.
 
-> ⚠️ **`ORQUESTADOR_STATE_PATH` must differ between registrations.** Share it and the active-task pointers clobber each other **silently**: the state is keyed by project name, so two documentation roots holding a project with the same name end up sharing one entry, and one answers for the other. No error is raised — you just get the wrong task back.
+> ⚠️ **`PHASE_GATE_STATE_PATH` must differ between registrations.** Share it and the active-task pointers clobber each other **silently**: the state is keyed by project name, so two documentation roots holding a project with the same name end up sharing one entry, and one answers for the other. No error is raised — you just get the wrong task back.
 
 Two more things that bite and aren't obvious:
 
 - **Mirror mode, not streaming.** Google Drive in *streaming* mode and OneDrive with *Files On-Demand* leave files as placeholders until something opens them. This server lives on listing folders and checking whether files exist, so placeholders make it slow, or make it fail with no network. Keep the documentation folder **downloaded locally** if you can.
-- **Keep code repos out of the synced folder.** Documentation in the cloud is fine. Code isn't: sync competing with git over `.git/` corrupts repositories. Point `ORQUESTADOR_REPOS_PATH` at a local disk.
+- **Keep code repos out of the synced folder.** Documentation in the cloud is fine. Code isn't: sync competing with git over `.git/` corrupts repositories. Point `PHASE_GATE_REPOS_PATH` at a local disk.
 
 ---
 
@@ -276,7 +295,7 @@ Two more things that bite and aren't obvious:
 | The compiled server | `build/` in your clone | It's gitignored. **After every `git pull` that touches `src/`, run `npm run build`** or the client keeps executing the previous version. |
 | This machine's paths | `.env` at the root ([route B](#-route-b--from-source), step 2) | The system user and the documentation folder differ per machine. |
 | The MCP registration | Your client's config ([route A](#-route-a--with-npx-recommended), or step 3 of [route B](#-route-b--from-source)) | In Cursor and VS Code it holds the absolute path to `build/index.js`, which depends on where you cloned and points into a gitignored folder. No single path can be right on every machine. See [`docs/decisiones.md`](docs/decisiones.md). The exception is Claude Code's `.mcp.json`, which uses a relative path. |
-| The `/f1`–`/f5` commands in **Cursor** | `~/.cursor/commands/f<N>.md` | Cursor only reads them from the user folder, so they're copied by hand on each machine. Not an issue in **Claude Code**: they're versioned in `.claude/commands/` and arrive with the pull. |
+| The `/f1`–`/f5` commands as files, **only if your client doesn't show MCP Prompts well** | `~/.cursor/commands/f<N>.md` in Cursor | Since 2.2.0 the server offers them as MCP Prompts and they arrive with every version ([see below](#the-phase-commands)). The file copy is only a fallback; in **Claude Code** inside this repo it's already versioned in `.claude/commands/`. |
 
 ### The phase commands
 
@@ -287,20 +306,24 @@ You invoke them by typing `/f1`, `/f2`, etc. in the chat. **They are orchestrati
 | `/f1` | `start_task` + `get_phase_prompt(1)` | Phase 1's |
 | `/f2` | `get_phase_prompt(2)`, reads phase 1's | Phase 2's, after you answer the questions |
 | `/f3` | `get_phase_prompt(3)`, reads the previous ones | Phase 3's |
-| `/f4` | `get_phase_prompt(4)`, reads the plan | Phase 4's, short and at the end |
+| `/f4` | `get_phase_prompt(4)`, reads the plan | One receipt per batch; the phase document when it closes |
 | `/f5` | `get_phase_prompt(5)` | Phase 5's: the audit and the PR description, which also go in the chat |
 
 No command names a file: the name is declared in each phase prompt's header and `get_phase_prompt` hands it to the model.
 
-`/f1` and `/f5` expect data after the command: `/f1` needs project, task_name and the full requirement; `/f5`, which commits to audit. The other four start from `get_active_task`.
+`/f1` needs project, task_name and the full requirement. `/f5` accepts a commit range; without one it audits the commits recorded in the phase 4 receipts, and only asks if there are no receipts. The rest start from `get_active_task`.
 
-**Where to put them, per client:**
+**They arrive on their own, as MCP Prompts.** Since 2.2.0 the server offers each command as an MCP prompt (`f1`…`f5`), with its text in [`prompts/comandos/`](prompts/comandos). Nothing to copy into any folder, and they update with every package version. All their arguments are optional — `project`; in `/f1` also `task_name` and `contexto`; in `/f5`, `commits` —: whatever you don't pass, the command asks for, and a long context can be pasted after the command as plain chat text. A phase you add yourself (a `fase-6`) gets its own `/f6` with a generic text, and a `comandos/fN.md` in your own prompts folder wins over the packaged one.
 
-- **Claude Code:** already in [`.claude/commands/`](.claude/commands), versioned. They work when you open this repo, no setup. To use them from your other projects, copy them to `~/.claude/commands/`.
-- **Cursor:** copy them to `~/.cursor/commands/`. From there they work across all your projects.
-- **VS Code:** no slash commands of its own; paste the file contents into the chat.
+How they look in each client:
 
-The exact contents of all five are also in [`docs/comandos-de-fase.md`](docs/comandos-de-fase.md) (Spanish).
+| Client | `/f1`…`/f5` visible | Arguments with spaces | `@` resources | Direct confirmations | Notes |
+|--------|---------------------|-----------------------|---------------|----------------------|-------|
+| Claude Code | To be verified (per its docs: `/<key>:f1 (MCP)`, with `/mcp__<key>__f1` as an alias) | To be verified | To be verified | To be verified | |
+| Cursor | To be verified (per its docs: in the MCP prompts menu) | To be verified | To be verified | To be verified | On Windows, `PHASE_GATE_ELICITATION=off` while the form bug stays open ([see below](#-protected-documents)) |
+| VS Code | To be verified (its docs contradict themselves between `/<key>.f1` and `mcp.<key>.f1`) | To be verified | To be verified | To be verified | |
+
+**If your client doesn't show them comfortably**, use the files: in this repo, Claude Code already reads them from [`.claude/commands/`](.claude/commands) (identical to `prompts/comandos/`); to use them in your other projects, copy them to `~/.claude/commands/`, or to `~/.cursor/commands/` in Cursor. More detail in [`docs/comandos-de-fase.md`](docs/comandos-de-fase.md) (Spanish).
 
 ---
 
@@ -327,24 +350,64 @@ Three things it deliberately does **not** do:
 - **It doesn't make you type anything extra.** You still type `/f4` and nothing else. Working out which task you mean is the server's job, using the pointer it already keeps — not the model asking you.
 - **It doesn't go quiet when it can't check.** If several projects have an active task and none was named, it says so instead of pretending everything is in order.
 
+**It also flags what the previous phase left open.** If the previous phase's document has a `## Validaciones pendientes` section with something in it, or if, when asking for phase 5, some batch receipt ended up `con pendientes`, `fallido` or `descartado`, the prompt also arrives with a `## PENDIENTES HEREDADOS (detectados por el servidor)` block naming them, so the AI tells you before starting. A section that only says "Ninguna." doesn't count. It doesn't block anything either: it only points at what the prompt already required writing.
+
+---
+
+## 🔒 Protected documents
+
+Each phase works on top of the previous phases' documents, so rewriting one that's already been passed silently changes the basis of everything that came after. That's why `write_central_doc` refuses, **without `force: true`**, to write:
+
+- **The initial context** (`00 - Contexto Inicial.md`), always, even to create it. Only `start_task` writes it without `force`.
+- **The document of a frozen phase.** A phase freezes as soon as a later phase's document exists, or as soon as phase 4 has any receipt in `04 - Ejecución/`. Receipts count as phase 4: they and `04 - Ejecución.md` are frozen only by phase 5.
+
+Creating a phase document that doesn't exist yet is never refused; a new receipt is, once phase 5 is present. Names are compared ignoring case and in the same Unicode form, so spelling them differently doesn't get around the protection.
+
+**If a legitimate fix is needed** — a typo in the analysis when the decisions are already written — it depends on your client:
+
+- **If your client supports direct confirmations** (MCP elicitation), the server **asks you**, in a form in your client with one checkbox: "Reescribir `01 - Análisis Técnico.md`". Tick it and accept, and it's written, with the response saying it was with your confirmation; say no or close the form, and nothing is written. Here `force` isn't enough: the AI sets it, and that's exactly what the question avoids.
+- **If it doesn't**, it works as before: the refusal tells the AI it needs your explicit confirmation in the chat and `force: true`, and the response warns that the document was overwritten (or created, if it didn't exist).
+
+The same goes for **starting a new project** with `crear_proyecto: true`: with direct confirmations, the server asks you before creating the folder.
+
+If your client announces direct confirmations but the form never shows up, the server waits three minutes and writes nothing; the second time in a row it doesn't write either (even if the AI set `force`) and stops asking for the rest of the session: from then on `force` decides again, with your confirmation in the chat. If your client cancels the call before you answer, nothing is written. To avoid this from the start, register the server with `PHASE_GATE_ELICITATION=off`. **On Cursor for Windows, `off` is recommended** while the bug where the form doesn't appear stays open.
+
+On top of that, `write_central_doc` only writes **inside the folder of a task that already exists**: it doesn't create stray folders in the documentation.
+
 ---
 
 ## 🛠 Available tools
 
 | Tool | What it does |
 |------|--------------|
-| `start_task` | Creates the folder for a **new** task (`<PROJECT>/<tasks subfolder>/<task>`), saves the initial context and makes it the **active task of its project**. If the task already exists it refuses and points you at `switch_task`, so the initial context is never overwritten. |
+| `start_task` | Creates the folder for a **new** task (`<PROJECT>/<tasks subfolder>/<task>`), saves the initial context and makes it the **active task of its project**. If the task already exists it refuses and points you at `switch_task`, so the initial context is never overwritten. Starting a new project takes `crear_proyecto: true` and, if your client can, your direct confirmation. |
 | `get_active_task` | Returns the active task and **which phase it's on**, derived from the documents it already has. Without `project` it answers for every project. Use it when opening a new chat or after losing track. |
 | `list_tasks` | Lists the tasks that exist and each one's phase, most recently touched first. For picking up something old or seeing what was left half-done. |
 | `switch_task` | Changes which task is active for a project. **Touches no files**: it's the correct way to resume an existing task. |
-| `get_phase_prompt` | Returns the behaviour rules for a phase (1–5), with the global rules prepended and the exact document filenames appended. The text lives in `prompts/`. It also checks the **gate**: pass `project` and, if you skipped a phase, the prompt arrives with the warning on top. |
+| `get_phase_prompt` | Returns the behaviour rules for a phase (1–5), with the global rules prepended and the exact document filenames appended. The text lives in `prompts/`. It also checks the **gate**: pass `project` and, if you skipped a phase, the prompt arrives with the warning on top, followed by the inherited pending items if there are any. |
 | `read_central_doc` | Reads a file from the central documentation. **Recommended:** pass `project` + `task_name` + `file_name` and let the server build the path. It also accepts a relative `file_path`. |
-| `write_central_doc` | Writes/overwrites a file. Same parameters as `read_central_doc` plus `content`. |
+| `write_central_doc` | Writes/overwrites a file inside a task folder. Same parameters as `read_central_doc` plus `content`, and `force` for [protected documents](#-protected-documents) when your client doesn't support direct confirmations. |
 | `read_cross_repo` | Reads files from your other local repos, so you can check how another codebase solved something without switching windows. |
+| `get_orchestrator_status` | The installation X-ray, same as [`doctor`](#-check-your-setup-doctor): package version and path, variables and where each came from, which prompt wins per phase, projects with their active task, and findings. Plus the connected client and its capabilities. Use it when something doesn't behave as you expect. |
+
+They all declare their MCP annotations (read-only, destructive, idempotent), so a cautious client can let the read-only ones through without asking. Only `write_central_doc` is destructive.
+
+### `phase-gate://` resources
+
+The server also exposes the documents as **read-only resources**, which compatible clients show when you type `@` in the chat, to attach them without asking the AI:
+
+| Resource | What it is |
+|----------|------------|
+| `phase-gate://estado` | The `doctor` X-ray, in Markdown |
+| `phase-gate://fases` | The available phases, with their document, receipts, and which prompt file wins |
+| `phase-gate://tareas/{proyecto}/{tarea}/{documento}` | A task document |
+| `phase-gate://tareas/{proyecto}/{tarea}/recibos/{recibo}` | A phase 4 batch receipt |
+
+The list only includes the existing documents of **each project's active task**, so the picker doesn't drown; the rest is reachable through the template, which autocompletes project, task and document. They have the same defences as `read_central_doc`: they can't leave the task folder, don't expose dot-files, and don't read more than 1 MB.
 
 ### How the server builds paths
-- **Documentation:** `ORQUESTADOR_DOCS_PATH` / `<PROJECT>` / `ORQUESTADOR_TASKS_SUBDIR` / `<task>` / `<file>`
-- **Code repos:** `ORQUESTADOR_REPOS_PATH` / `<repo>` / `<file>`
+- **Documentation:** `PHASE_GATE_DOCS_PATH` / `<PROJECT>` / `PHASE_GATE_TASKS_SUBDIR` / `<task>` / `<file>`
+- **Code repos:** `PHASE_GATE_REPOS_PATH` / `<repo>` / `<file>`
 
 ### What counts as a project
 
@@ -352,7 +415,7 @@ There is no list of projects to maintain. **A project is any folder that contain
 
 A project that doesn't exist is rejected, showing the list of the ones that do, instead of silently creating a stray folder. To **start** a brand new project you have to ask on purpose: `start_task` accepts `crear_proyecto: true`, and without that flag a typo can't pollute your documentation.
 
-> If you leave `ORQUESTADOR_TASKS_SUBDIR` empty, the rule can't be applied and **any** folder counts as a project.
+> If you leave `PHASE_GATE_TASKS_SUBDIR` empty, the rule can't be applied and **any** folder counts as a project.
 
 ---
 
@@ -367,7 +430,10 @@ prompts/
 ├── fase-2-decisiones.md
 ├── fase-3-plan-tecnico.md
 ├── fase-4-ejecucion.md
-└── fase-5-auditoria-pr.md       ← includes the PR description contract
+├── fase-5-auditoria-pr.md       ← includes the PR description contract
+└── comandos/                    ← the /f1…/f5 text, served by the server as MCP Prompts
+    ├── f1.md
+    └── …
 ```
 
 **They are read on every call.** Edit a `.md` and the next `get_phase_prompt` already returns the new version — no `npm run build`, no client restart. That's what makes it practical to tune a phase and test it immediately.
@@ -395,7 +461,7 @@ Format rules:
 
 ### Using your own prompts without losing the packaged ones
 
-`ORQUESTADOR_PROMPTS_PATH` points at a folder of yours that is **layered on top of** the packaged one. It does not replace it.
+`PHASE_GATE_PROMPTS_PATH` points at a folder of yours that is **layered on top of** the packaged one. It does not replace it.
 
 To change only phase 2, your folder holds **one file**:
 
@@ -411,6 +477,7 @@ Three details that matter:
 - **Layering is by phase number, not by filename.** Your `fase-2-my-way.md` overrides the package's `fase-2-decisiones.md`. You don't have to guess the original's name.
 - **It also adds.** A `fase-6-deployment.md` in your folder creates phase 6, nothing else needed.
 - **Your `global-rules.md` replaces the packaged one, it doesn't stack.** Concatenating two rule sets makes it impossible to tell which file an unwanted instruction came from, exactly when you need to know. If you want the packaged rules plus extras, copy them and add.
+  **Watch out:** the packaged rules include the `EVIDENCIA`, `BASE DE CADA DECISIÓN` and `PENDIENTES HEREDADOS` sections, which the phases refer to. A `global-rules.md` of your own without them leaves the phases pointing at rules that don't exist; copy them into your file.
 
 On the `npx` route this is the **only** way to customise: the packaged prompts live inside `node_modules`, where editing them achieves nothing because the next install wipes them.
 
@@ -437,13 +504,16 @@ Loaded from the `.env` at the repo root, or from the `"env"` block in your clien
 
 The first two are **required and have no default**: they point at folders that only exist on your machine, so any default would be somebody else's path. If one is missing, or points at something that doesn't exist or isn't a folder, the tools that use it return the variable name and where to configure it. Tools that don't depend on it — like `get_phase_prompt` — keep working.
 
+Each variable also has an **alias** with the old name, `ORQUESTADOR_*` (e.g. `ORQUESTADOR_DOCS_PATH`), which keeps working so no existing setup breaks. If you define both with different values, `PHASE_GATE_*` wins, and `doctor` and the server log tell you.
+
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `ORQUESTADOR_DOCS_PATH` | **none, required** | Path to the root of your central documentation. **Different on each machine.** |
-| `ORQUESTADOR_REPOS_PATH` | **none, required** | Path to the folder holding your code repositories. |
-| `ORQUESTADOR_TASKS_SUBDIR` | `Proyectos` | Subfolder where tasks live inside each project. Empty means tasks hang directly off the project. It's also the rule that decides what counts as a project (see above). |
-| `ORQUESTADOR_PROMPTS_PATH` | none | Folder holding your own prompts. They are **layered on top of** the packaged ones rather than replacing them, so you only drop in the phases you want to change ([see above](#using-your-own-prompts-without-losing-the-packaged-ones)). |
-| `ORQUESTADOR_STATE_PATH` | Your user data folder (see above) | Where the active-task pointers are stored. Rarely needs touching; useful to isolate state in tests, and **required if you register the server more than once** (see [More than one documentation folder?](#-more-than-one-documentation-folder-optional)). |
+| `PHASE_GATE_DOCS_PATH` | **none, required** | Path to the root of your central documentation. **Different on each machine.** |
+| `PHASE_GATE_REPOS_PATH` | **none, required** | Path to the folder holding your code repositories. |
+| `PHASE_GATE_TASKS_SUBDIR` | `Proyectos` | Subfolder where tasks live inside each project. Empty means tasks hang directly off the project. It's also the rule that decides what counts as a project (see above). |
+| `PHASE_GATE_PROMPTS_PATH` | none | Folder holding your own prompts. They are **layered on top of** the packaged ones rather than replacing them, so you only drop in the phases you want to change ([see above](#using-your-own-prompts-without-losing-the-packaged-ones)). |
+| `PHASE_GATE_STATE_PATH` | Your user data folder (see above) | Where the active-task pointers are stored. Rarely needs touching; useful to isolate state in tests, and **required if you register the server more than once** (see [More than one documentation folder?](#-more-than-one-documentation-folder-optional)). |
+| `PHASE_GATE_ELICITATION` | none (enabled) | `off` (or `false`, `0`, `no`) so the server doesn't ask the client for [direct confirmations](#-protected-documents) and lets `force` decide, as before. Recommended on Cursor for Windows. No alias. |
 
 ---
 
@@ -455,11 +525,19 @@ The source lives in `src/`, split by responsibility:
 
 | File | What it handles |
 |------|-----------------|
-| `config.ts` | Environment paths, where state lives, server identity |
+| `config.ts` | Environment variables and their aliases, reading `.env`, where state lives, server identity |
 | `paths.ts` | How every path is built, and the check that it stays inside its base |
 | `phases.ts` | Discovering the phases and assembling each one's prompt |
-| `tasks.ts` | Which tasks exist, which phase each is on, and which one is active |
-| `index.ts` | The server's tools. It computes nothing: it translates between the protocol and the above |
+| `tasks.ts` | Which tasks exist, which phase each is on, which one is active, the gate and inherited pending items |
+| `schemas.ts` | Each tool's arguments, with their description and error message |
+| `servidor.ts` | The server's tools. It computes nothing: it translates between the protocol and the above |
+| `recursos.ts` | The `phase-gate://` resources |
+| `prompts-mcp.ts` | The `/f1`…`/fN` commands as MCP Prompts |
+| `confirmacion.ts` | Direct confirmations to the user (elicitation) |
+| `diagnostico.ts` | The X-ray shared by `doctor`, `get_orchestrator_status` and `phase-gate://estado` |
+| `cli.ts` | The command line: `doctor`, `--help`, `--version` |
+| `log.ts` | Logging: stderr and, with a client connected, MCP notifications |
+| `index.ts` | The entry point: the command line, or the server over stdio |
 
 The client runs the compiled `build/index.js`, so after any change:
 
@@ -485,7 +563,7 @@ yours. CI runs them on every PR.
 |-------------------------|-------|
 | What the project does today | This README (and its Spanish twin, [`README.es.md`](README.es.md) — **change one, change the other**) |
 | Why it's designed this way | [`docs/decisiones.md`](docs/decisiones.md) (Spanish) |
-| The `/f1`–`/f5` commands, to recreate them elsewhere | [`docs/comandos-de-fase.md`](docs/comandos-de-fase.md) (Spanish) |
+| The `/f1`–`/f5` commands | Their text in [`prompts/comandos/`](prompts/comandos); how they reach each client in [`docs/comandos-de-fase.md`](docs/comandos-de-fase.md) (Spanish) |
 | That a change broke nothing | [`test/`](test), via `npm test`. CI runs them on every PR |
 | What's still missing | [Issues](https://github.com/Montse2308/mcp-phase-gate/issues) — grouped under the `v1-uso-propio` and `v2-publico` labels |
 | What's already been done | The commit history and merged PRs |

package/build/cli.d.ts

@@ -0,0 +1,14 @@
+export declare const AYUDA: string;
+export declare const AVISO_TERMINAL = "Esperando un cliente MCP por stdin. Si quer\u00EDas revisar la instalaci\u00F3n: `npx mcp-phase-gate doctor`.";
+export type Salida = {
+    out: (texto: string) => void;
+    err: (texto: string) => void;
+};
+export type ResultadoCli = {
+    accion: "servidor";
+} | {
+    accion: "salir";
+    codigo: number;
+};
+export declare function ejecutarCli(argv: string[], salida?: Salida, esTerminal?: boolean): ResultadoCli;
+//# sourceMappingURL=cli.d.ts.map

package/build/cli.js

@@ -0,0 +1,98 @@
+// La línea de comandos del paquete. Sin argumentos, el binario es el servidor MCP que lanza el
+// cliente; con argumentos, es una herramienta para la persona que lo instaló.
+//
+// Un servidor MCP habla JSON-RPC por stdin y no imprime nada por stdout. Ejecutado a mano en
+// una terminal —que es exactamente lo que hace quien acaba de leer `npx mcp-phase-gate` en el
+// README— se queda esperando entrada, sin señal de vida, y parece roto. Por eso existen la ayuda
+// y `doctor`: el primero explica qué es esto, el segundo dice si está bien instalado.
+import { parseArgs } from "util";
+import { SERVER_NAME, SERVER_VERSION } from "./config.js";
+import { diagnosticar, formatearDiagnostico } from "./diagnostico.js";
+export const AYUDA = `${SERVER_NAME} v${SERVER_VERSION}
+
+Servidor MCP que parte cada requerimiento en cinco fases con compuerta y obliga a que cada
+una deje su documento en una documentación central.
+
+El servidor NO se ejecuta a mano: lo lanza tu cliente MCP. Ejecutado directamente se queda
+esperando mensajes JSON-RPC por stdin, que es lo que parece que se colgó.
+
+Uso:
+  ${SERVER_NAME}                 Arranca el servidor MCP por stdio (lo hace tu cliente).
+  ${SERVER_NAME} doctor          Revisa la instalación: variables, prompts, proyectos y avisos.
+  ${SERVER_NAME} doctor --json   Lo mismo, como JSON.
+  ${SERVER_NAME} --version       La versión.
+  ${SERVER_NAME} --help          Esta ayuda.
+
+Regístralo en tu cliente (Cursor, VS Code, Claude Code) así:
+
+  {
+    "mcpServers": {
+      "${SERVER_NAME}": {
+        "command": "npx",
+        "args": ["-y", "mcp-phase-gate"],
+        "env": {
+          "PHASE_GATE_DOCS_PATH": "<tu carpeta de documentación>",
+          "PHASE_GATE_REPOS_PATH": "<tu carpeta de repositorios>"
+        }
+      }
+    }
+  }
+
+Variables de entorno (los nombres ORQUESTADOR_* de antes siguen valiendo como alias):
+  PHASE_GATE_DOCS_PATH      Obligatoria. Raíz de la Documentación Central.
+  PHASE_GATE_REPOS_PATH     Obligatoria. Carpeta con tus repositorios de código.
+  PHASE_GATE_TASKS_SUBDIR   Subcarpeta de tareas dentro de cada proyecto. Por defecto "Proyectos".
+  PHASE_GATE_PROMPTS_PATH   Carpeta de prompts propios, que se superponen a los del paquete.
+  PHASE_GATE_STATE_PATH     Dónde guardar los punteros de tarea activa.
+  PHASE_GATE_ELICITATION    "off" para que el servidor no pida confirmaciones al cliente.
+
+Documentación: https://github.com/Montse2308/mcp-phase-gate`;
+export const AVISO_TERMINAL = "Esperando un cliente MCP por stdin. Si querías revisar la instalación: `npx mcp-phase-gate doctor`.";
+const SALIDA_DE_PROCESO = {
+    out: (texto) => process.stdout.write(`${texto}\n`),
+    err: (texto) => process.stderr.write(`${texto}\n`),
+};
+function invalido(salida) {
+    salida.err(AYUDA);
+    return { accion: "salir", codigo: 2 };
+}
+export function ejecutarCli(argv, salida = SALIDA_DE_PROCESO, esTerminal = Boolean(process.stdin.isTTY)) {
+    if (argv.length === 0) {
+        // stderr, no stdout: stdout es el canal del JSON-RPC aunque nadie esté escuchando.
+        if (esTerminal)
+            salida.err(AVISO_TERMINAL);
+        return { accion: "servidor" };
+    }
+    let valores;
+    let posicionales;
+    try {
+        ({ values: valores, positionals: posicionales } = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            strict: true,
+            options: {
+                help: { type: "boolean", short: "h" },
+                version: { type: "boolean", short: "v" },
+                json: { type: "boolean" },
+            },
+        }));
+    }
+    catch {
+        return invalido(salida);
+    }
+    if (valores.help) {
+        salida.out(AYUDA);
+        return { accion: "salir", codigo: 0 };
+    }
+    if (valores.version) {
+        salida.out(SERVER_VERSION);
+        return { accion: "salir", codigo: 0 };
+    }
+    if (posicionales.length === 1 && posicionales[0] === "doctor") {
+        const diagnostico = diagnosticar();
+        salida.out(valores.json ? JSON.stringify(diagnostico, null, 2) : formatearDiagnostico(diagnostico, "texto"));
+        return { accion: "salir", codigo: diagnostico.hallazgos.some((h) => h.severidad === "error") ? 1 : 0 };
+    }
+    return invalido(salida);
+}
+//# sourceMappingURL=cli.js.map

package/build/config.d.ts

@@ -1,11 +1,35 @@
 export declare const MODULE_DIR: string;
+export declare function envPorDefecto(): string;
+export declare function clavesDeEnv(): ReadonlySet<string>;
+export declare function errorDeEnv(): string | null;
+export declare function reiniciarEnv(): void;
+export declare function cargarEnv(archivo?: string): void;
+export type NombreLogico = "DOCS_PATH" | "REPOS_PATH" | "TASKS_SUBDIR" | "PROMPTS_PATH" | "STATE_PATH" | "ELICITATION";
+type Nombres = {
+    principal: string;
+    alias: string | null;
+    esRuta: boolean;
+};
+export declare const VARIABLES: Record<NombreLogico, Nombres>;
+export declare const NOMBRES_LOGICOS: NombreLogico[];
+export type FuenteVariable = "entorno" | ".env" | "sin definir";
+export type LecturaVariable = {
+    logica: NombreLogico;
+    valor: string | undefined;
+    usada: string | null;
+    fuente: FuenteVariable;
+    discrepancia: string | null;
+};
+export declare function leerVariable(logica: NombreLogico): LecturaVariable;
+export declare function nombrarVariable(logica: NombreLogico): string;
 export type RutaRequerida = {
-    variable: string;
+    logica: NombreLogico;
     apuntaA: string;
 };
 export declare const DOCS: RutaRequerida;
 export declare const REPOS: RutaRequerida;
-export declare function requireBasePath({ variable, apuntaA }: RutaRequerida): string;
+export declare function requireBasePath({ logica, apuntaA }: RutaRequerida): string;
+export declare const TASKS_SUBDIR_POR_DEFECTO = "Proyectos";
 export declare function tasksSubdir(): string;
 export declare function defaultPromptsPath(): string;
 export declare function promptsLayers(): string[];
@@ -14,4 +38,5 @@ export declare function stateDir(): string;
 export declare function stateFile(): string;
 export declare const SERVER_NAME = "mcp-phase-gate";
 export declare const SERVER_VERSION: string;
+export {};
 //# sourceMappingURL=config.d.ts.map