feat: Implement Universal File Resolution Protocol

moisgobg · moisgobg · commit 9dff79bb7216 · 2026-01-07T21:08:02.000Z
Updates GEMINI.md with the resolution protocol and refactors all commands (implement, revert, status, newTrack) to resolve file paths dynamically via index.md, removing hardcoded defaults.
diff --git a/GEMINI.md b/GEMINI.md
@@ -1,3 +1,34 @@
 # Conductor Context
 
 If a user mentions a "plan" or asks about the plan, and they have used the conductor extension in the current session, they are likely referring to the `conductor/tracks.md` file or one of the track plans (`conductor/tracks/<track_id>/plan.md`).
+
+## Universal File Resolution Protocol
+
+**PROTOCOL: How to locate files.**
+To find a file (e.g., "**Product Definition**") within a specific context (Project Root or a specific Track):
+
+1.  **Identify Index:** Determine the relevant index file:
+    -   **Project Context:** `conductor/index.md`
+    -   **Track Context:** `conductor/tracks/<track_id>/index.md`
+
+2.  **Check Index:** Read the index file and look for a link with a matching or semantically similar label.
+
+3.  **Resolve Path:** If a link is found, resolve its path **relative to the directory containing the `index.md` file**.
+    -   *Example:* If `conductor/index.md` links to `./workflow.md`, the full path is `conductor/workflow.md`.
+
+4.  **Fallback:** If the index file is missing or the link is absent, use the **Default Path** keys below.
+
+5.  **Verify:** You MUST verify the resolved file actually exists on the disk.
+
+**Standard Default Paths (Project):**
+- **Product Definition**: `conductor/product.md`
+- **Tech Stack**: `conductor/tech-stack.md`
+- **Workflow**: `conductor/workflow.md`
+- **Product Guidelines**: `conductor/product-guidelines.md`
+- **Tracks Registry**: `conductor/tracks.md`
+
+**Standard Default Paths (Track):**
+- **Specification**: `conductor/tracks/<track_id>/spec.md`
+- **Implementation Plan**: `conductor/tracks/<track_id>/plan.md`
+- **Metadata**: `conductor/tracks/<track_id>/metadata.json`
+
diff --git a/commands/conductor/implement.toml b/commands/conductor/implement.toml
@@ -7,22 +7,13 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai
 
 ---
 
-## 1.1 UNIVERSAL FILE RESOLUTION PROTOCOL
-**PROTOCOL: How to locate files.**
-To find a file (e.g., "**Product Definition**"), you MUST:
-1.  **Check Index:** Look for a link with that label in `conductor/index.md` (if it exists).
-2.  **Fallback:** If `conductor/index.md` is missing or the link is absent, use the **Default Path** keys specified in the steps below.
-3.  **Verify:** You MUST verify the resolved file actually exists on the disk.
-
----
-
-## 1.2 SETUP CHECK
+## 1.1 SETUP CHECK
 **PROTOCOL: Verify that the Conductor environment is properly set up.**
 
-1.  **Verify Core Context:** Using the **Universal File Resolution Protocol**, verify the existence of:
-    -   **Product Definition** (Default: `conductor/product.md`)
-    -   **Tech Stack** (Default: `conductor/tech-stack.md`)
-    -   **Workflow** (Default: `conductor/workflow.md`)
+1.  **Verify Core Context:** Using the **Universal File Resolution Protocol**, resolve and verify the existence of:
+    -   **Product Definition**
+    -   **Tech Stack**
+    -   **Workflow**
 
 2.  **Handle Failure:** If ANY of these are missing (or their resolved paths do not exist), Announce: "Conductor is not set up. Please run `/conductor:setup`." and HALT.
 
@@ -35,7 +26,7 @@ To find a file (e.g., "**Product Definition**"), you MUST:
 1.  **Check for User Input:** First, check if the user provided a track name as an argument (e.g., `/conductor:implement <track_description>`).
 
 2.  **Locate and Parse Tracks Registry:**
-    -   Resolve the **Tracks Registry** file (Default: `conductor/tracks.md`).
+    -   Resolve the **Tracks Registry**.
     -   Read and parse this file. You must parse the file by splitting its content by the `---` separator to identify each track section. For each section, extract the status (`[ ]`, `[~]`, `[x]`), the track description (from the `##` heading), and the link to the track folder.
     -   **CRITICAL:** If no track sections are found after parsing, announce: "The tracks file is empty or malformed. No tracks to implement." and halt.
 
@@ -71,11 +62,7 @@ To find a file (e.g., "**Product Definition**"), you MUST:
 3.  **Load Track Context:**
     a. **Identify Track Folder:** From the tracks file, identify the track's folder link to get the `<track_id>`.
     b. **Read Files:**
-        -   **Track Context:** Check for `conductor/tracks/<track_id>/index.md`.
-            -   **If found:** Use it to resolve **Specification** and **Implementation Plan**.
-            -   **If missing:** Use Defaults:
-                -   **Specification**: `conductor/tracks/<track_id>/spec.md`
-                -   **Implementation Plan**: `conductor/tracks/<track_id>/plan.md`
+        -   **Track Context:** Using the **Universal File Resolution Protocol**, resolve and read the **Specification** and **Implementation Plan** for the selected track.
         -   **Workflow:** Resolve **Workflow** (Default: `conductor/workflow.md`).
     c. **Error Handling:** If you fail to read any of these files, you MUST stop and inform the user of the error.
 
@@ -104,9 +91,9 @@ To find a file (e.g., "**Product Definition**"), you MUST:
 
 4.  **Load Project Documents:**
     -   Resolve and read:
-        -   **Product Definition** (Default: `conductor/product.md`)
-        -   **Tech Stack** (Default: `conductor/tech-stack.md`)
-        -   **Product Guidelines** (Default: `conductor/product-guidelines.md`)
+        -   **Product Definition**
+        -   **Tech Stack**
+        -   **Product Guidelines**
 
 5.  **Analyze and Update:**
     a.  **Analyze Specification:** Carefully analyze the **Specification** to identify any new features, changes in functionality, or updates to the technology stack.
diff --git a/commands/conductor/newTrack.toml b/commands/conductor/newTrack.toml
@@ -5,22 +5,15 @@ You are an AI agent assistant for the Conductor spec-driven development framewor
 
 CRITICAL: You must validate the success of every tool call. If any tool call fails, you MUST halt the current operation immediately, announce the failure to the user, and await further instructions.
 
-## 1.1 UNIVERSAL FILE RESOLUTION PROTOCOL
-**PROTOCOL: How to locate files.**
-To find a file (e.g., "**Product Definition**"), you MUST:
-1.  **Check Index:** Look for a link with that label in `conductor/index.md` (if it exists).
-2.  **Fallback:** If `conductor/index.md` is missing or the link is absent, use the **Default Path** keys specified in the steps below.
-3.  **Verify:** You MUST verify the resolved file actually exists on the disk.
-
 ---
 
-## 1.2 SETUP CHECK
+## 1.1 SETUP CHECK
 **PROTOCOL: Verify that the Conductor environment is properly set up.**
 
-1.  **Verify Core Context:** Using the **Universal File Resolution Protocol**, verify the existence of:
-    -   **Product Definition** (Default: `conductor/product.md`)
-    -   **Tech Stack** (Default: `conductor/tech-stack.md`)
-    -   **Workflow** (Default: `conductor/workflow.md`)
+1.  **Verify Core Context:** Using the **Universal File Resolution Protocol**, resolve and verify the existence of:
+    -   **Product Definition**
+    -   **Tech Stack**
+    -   **Workflow**
 
 2.  **Handle Failure:**
     -   If ANY of these files are missing, you MUST halt the operation immediately.
@@ -100,11 +93,11 @@ To find a file (e.g., "**Product Definition**"), you MUST:
     *   Read the confirmed `spec.md` content for this track.
     *   Resolve and read the **Workflow** file (Default: `conductor/workflow.md`).
     *   Generate a `plan.md` with a hierarchical list of Phases, Tasks, and Sub-tasks.
-    *   **CRITICAL:** The plan structure MUST adhere to the methodology in the workflow file (e.g., TDD tasks for "Write Tests" and "Implement").
+    *   **CRITICAL:** The plan structure MUST adhere to the methodology in the **Workflow** file (e.g., TDD tasks for "Write Tests" and "Implement").
     *   Include status markers `[ ]` for **EVERY** task and sub-task. The format must be:
         - Parent Task: `- [ ] Task: ...`
         - Sub-task: `    - [ ] ...`
-    *   **CRITICAL: Inject Phase Completion Tasks.** Determine if a "Phase Completion Verification and Checkpointing Protocol" is defined in `conductor/workflow.md`. If this protocol exists, then for each **Phase** that you generate in `plan.md`, you MUST append a final meta-task to that phase. The format for this meta-task is: `- [ ] Task: Conductor - User Manual Verification '<Phase Name>' (Protocol in workflow.md)`.
+    *   **CRITICAL: Inject Phase Completion Tasks.** Determine if a "Phase Completion Verification and Checkpointing Protocol" is defined in the **Workflow**. If this protocol exists, then for each **Phase** that you generate in `plan.md`, you MUST append a final meta-task to that phase. The format for this meta-task is: `- [ ] Task: Conductor - User Manual Verification '<Phase Name>' (Protocol in workflow.md)`.
 
 3.  **User Confirmation:** Present the drafted `plan.md` to the user for review and approval.
     > "I've drafted the implementation plan. Please review the following:"
@@ -146,7 +139,7 @@ To find a file (e.g., "**Product Definition**"), you MUST:
         ```
 6.  **Update Tracks Registry:**
     -   **Announce:** Inform the user you are updating the **Tracks Registry**.
-    -   **Append Section:** Resolve the **Tracks Registry** file (Default: `conductor/tracks.md`) via the **Universal File Resolution Protocol**. Append a new section for the track to the end of this file. The format MUST be:
+    -   **Append Section:** Resolve the **Tracks Registry** via the **Universal File Resolution Protocol**. Append a new section for the track to the end of this file. The format MUST be:
         ```markdown
         - [ ] **Track: <Track Description>**
           *Link: [./conductor/tracks/<track_id>/](./conductor/tracks/<track_id>/)*
diff --git a/commands/conductor/revert.toml b/commands/conductor/revert.toml
@@ -9,11 +9,18 @@ Your workflow MUST anticipate and handle common non-linear Git histories, such a
 
 **CRITICAL**: The user's explicit confirmation is required at multiple checkpoints. If a user denies a confirmation, the process MUST halt immediately and follow further instructions. 
 
-**CRITICAL:** Before proceeding, you should start by checking if the project has been properly set up.
-1.  **Verify Tracks File:** Check if the file `conductor/tracks.md` exists. If it does not, HALT execution and instruct the user: "The project has not been set up or conductor/tracks.md has been corrupted. Please run `/conductor:setup` to set up the plan, or restore conductor/tracks.md."
-2.  **Verify Track Exists:** Check if the file `conductor/tracks.md` is not empty. If it is empty, HALT execution and instruct the user: "The project has not been set up or conductor/tracks.md has been corrupted. Please run `/conductor:setup` to set up the plan, or restore conductor/tracks.md." 
+CRITICAL: You must validate the success of every tool call. If any tool call fails, you MUST halt the current operation immediately, announce the failure to the user, and await further instructions.
 
-**CRITICAL**: You must validate the success of every tool call. If any tool call fails, you MUST halt the current operation immediately, announce the failure to the user, and await further instructions.
+---
+
+## 1.1 SETUP CHECK
+**PROTOCOL: Verify that the Conductor environment is properly set up.**
+
+1.  **Verify Core Context:** Using the **Universal File Resolution Protocol**, resolve and verify the existence of the **Tracks Registry**.
+
+2.  **Verify Track Exists:** Check if the **Tracks Registry** is not empty.
+
+3.  **Handle Failure:** If the file is missing or empty, HALT execution and instruct the user: "The project has not been set up or the tracks file has been corrupted. Please run `/conductor:setup` to set up the plan, or restore the tracks file."
 
 ---
 
@@ -29,7 +36,7 @@ Your workflow MUST anticipate and handle common non-linear Git histories, such a
 3.  **Interaction Paths:**
 
     *   **PATH A: Direct Confirmation**
-        1.  Find the specific track, phase, or task the user referenced in the project's `tracks.md` or `plan.md` files.
+        1.  Find the specific track, phase, or task the user referenced in the **Tracks Registry** or **Implementation Plan** files (resolved via **Universal File Resolution Protocol**).
         2.  Ask the user for confirmation: "You asked to revert the [Track/Phase/Task]: '[Description]'. Is this correct?".
             - **Structure:**
                 A) Yes
@@ -38,7 +45,7 @@ Your workflow MUST anticipate and handle common non-linear Git histories, such a
 
     *   **PATH B: Guided Selection Menu**
         1.  **Identify Revert Candidates:** Your primary goal is to find relevant items for the user to revert.
-            *   **Scan All Plans:** You MUST read the main `conductor/tracks.md` and every `conductor/tracks/*/plan.md` file.
+            *   **Scan All Plans:** You MUST read the **Tracks Registry** and every track's **Implementation Plan** (resolved via **Universal File Resolution Protocol**, checking `conductor/tracks/<track_id>/index.md` if available).
             *   **Prioritize In-Progress:** First, find **all** Tracks, Phases, and Tasks marked as "in-progress" (`[~]`).
             *   **Fallback to Completed:** If and only if NO in-progress items are found, find the **5 most recently completed** Tasks and Phases (`[x]`).
         2.  **Present a Unified Hierarchical Menu:** You MUST present the results to the user in a clear, numbered, hierarchical list grouped by Track. The introductory text MUST change based on the context.
@@ -76,15 +83,15 @@ Your workflow MUST anticipate and handle common non-linear Git histories, such a
 **GOAL: Find ALL actual commit(s) in the Git history that correspond to the user's confirmed intent and analyze them.**
 
 1.  **Identify Implementation Commits:**
-    *   Find the primary SHA(s) for all tasks and phases recorded in the target's `plan.md`.
+    *   Find the primary SHA(s) for all tasks and phases recorded in the target's **Implementation Plan**.
     *   **Handle "Ghost" Commits (Rewritten History):** If a SHA from a plan is not found in Git, announce this. Search the Git log for a commit with a highly similar message and ask the user to confirm it as the replacement. If not confirmed, halt.
 
 2.  **Identify Associated Plan-Update Commits:**
-    *   For each validated implementation commit, use `git log` to find the corresponding plan-update commit that happened *after* it and modified the relevant `plan.md` file.
+    *   For each validated implementation commit, use `git log` to find the corresponding plan-update commit that happened *after* it and modified the relevant **Implementation Plan** file.
 
 3.  **Identify the Track Creation Commit (Track Revert Only):**
     *   **IF** the user's intent is to revert an entire track, you MUST perform this additional step.
-    *   **Method:** Use `git log -- conductor/tracks.md` and search for the commit that first introduced the track entry.
+    *   **Method:** Use `git log -- <path_to_tracks_registry>` (resolved via protocol) and search for the commit that first introduced the track entry.
         *   Look for lines matching either `- [ ] **Track: <Track Description>**` (new format) OR `## [ ] Track: <Track Description>` (legacy format).
     *   Add this "track creation" commit's SHA to the list of commits to be reverted.
 
@@ -118,7 +125,6 @@ Your workflow MUST anticipate and handle common non-linear Git histories, such a
 
 1.  **Execute Reverts:** Run `git revert --no-edit <sha>` for each commit in your final list, starting from the most recent and working backward.
 2.  **Handle Conflicts:** If any revert command fails due to a merge conflict, halt and provide the user with clear instructions for manual resolution.
-3.  **Verify Plan State:** After all reverts succeed, read the relevant `plan.md` file(s) again to ensure the reverted item has been correctly reset. If not, perform a file edit to fix it and commit the correction.
+3.  **Verify Plan State:** After all reverts succeed, read the relevant **Implementation Plan** file(s) again to ensure the reverted item has been correctly reset. If not, perform a file edit to fix it and commit the correction.
 4.  **Announce Completion:** Inform the user that the process is complete and the plan is synchronized.
-"""
-
+"""
diff --git a/commands/conductor/status.toml b/commands/conductor/status.toml
@@ -1,11 +1,7 @@
 description = "Displays the current progress of the project"
 prompt = """
 ## 1.0 SYSTEM DIRECTIVE
-You are an AI agent. Your primary function is to provide a status overview of the current tracks file. This involves reading the `conductor/tracks.md` file, parsing its content, and summarizing the progress of tasks.
-
-**CRITICAL:** Before proceeding, you should start by checking if the project has been properly set up.
-1.  **Verify Tracks File:** Check if the file `conductor/tracks.md` exists. If it does not, HALT execution and instruct the user: "The project has not been set up or conductor/tracks.md has been corrupted. Please run `/conductor:setup` to set up the plan, or restore conductor/tracks.md."
-2.  **Verify Track Exists:** Check if the file `conductor/tracks.md` is not empty. If it is empty, HALT execution and instruct the user: "The project has not been set up or conductor/tracks.md has been corrupted. Please run `/conductor:setup` to set up the plan, or restore conductor/tracks.md."
+You are an AI agent. Your primary function is to provide a status overview of the current tracks file. This involves reading the **Tracks Registry** file, parsing its content, and summarizing the progress of tasks.
 
 CRITICAL: You must validate the success of every tool call. If any tool call fails, you MUST halt the current operation immediately, announce the failure to the user, and await further instructions.
 
@@ -15,12 +11,13 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai
 ## 1.1 SETUP CHECK
 **PROTOCOL: Verify that the Conductor environment is properly set up.**
 
-1.  **Check for Required Files:** You MUST verify the existence of the following files in the `conductor` directory:
-    -   `conductor/tech-stack.md`
-    -   `conductor/workflow.md`
-    -   `conductor/product.md`
+1.  **Verify Core Context:** Using the **Universal File Resolution Protocol**, resolve and verify the existence of:
+    -   **Tracks Registry**
+    -   **Product Definition**
+    -   **Tech Stack**
+    -   **Workflow**
 
-2.  **Handle Missing Files:**
+2.  **Handle Failure:**
     -   If ANY of these files are missing, you MUST halt the operation immediately.
     -   Announce: "Conductor is not set up. Please run `/conductor:setup` to set up the environment."
     -   Do NOT proceed to Status Overview Protocol.
@@ -31,9 +28,11 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai
 **PROTOCOL: Follow this sequence to provide a status overview.**
 
 ### 2.1 Read Project Plan
-1.  **Locate and Read:** Read the content of the `conductor/tracks.md` file.
-2.  **Locate and Read:** List the tracks using shell command `ls conductor/tracks`. For each of the tracks, read the corresponding `conductor/tracks/<track_id>/plan.md` file.
-    *   **Parsing Logic:** When reading `conductor/tracks.md` to identify tracks, look for lines matching either the new standard format `- [ ] **Track:` or the legacy format `## [ ] Track:`.
+1.  **Locate and Read:** Read the content of the **Tracks Registry** (resolved via **Universal File Resolution Protocol**).
+2.  **Locate and Read Tracks:**
+    -   Parse the **Tracks Registry** to identify all registered tracks and their paths.
+        *   **Parsing Logic:** When reading the **Tracks Registry** to identify tracks, look for lines matching either the new standard format `- [ ] **Track:` or the legacy format `## [ ] Track:`.
+    -   For each track, resolve and read its **Implementation Plan** (using **Universal File Resolution Protocol**, checking `conductor/tracks/<track_id>/index.md` if available).
 
 ### 2.2 Parse and Summarize Plan
 1.  **Parse Content:**
