@qa-gentic/stlc-agents 1.0.16 → 1.0.18

package/src/cli/cmd-mcp-config.js

@@ -1,12 +1,40 @@
 /**
- * cmd-mcp-config.js — `qa-stlc mcp-config`
+ * cmd-mcp-config.js — `qa-stlc mcp-config`  (updated with cost tracking env injection)
  *
- * Generates .mcp.json (Claude Code) or .vscode/mcp.json (GitHub Copilot / VS Code).
+ * Change from original: both buildClaudeConfig() and buildVscodeConfig() now
+ * inject STLC cost tracking env vars into every MCP server entry.
+ *
+ * What gets injected and why:
+ *
+ *   STLC_COST_TRACKING       "true" — enables cost tracking (opt-out via "false")
+ *
+ *   ANTHROPIC_MODEL          "${env:ANTHROPIC_MODEL}" — Claude Code sets this
+ *                            automatically on the process that launches Claude.
+ *                            Passing it through to the MCP subprocess lets the
+ *                            cost tracker auto-detect the model without any
+ *                            manual configuration.
+ *
+ *   GITHUB_COPILOT_MODEL     "${env:GITHUB_COPILOT_MODEL}" — VS Code / Copilot
+ *                            may set this; passed through for the same reason.
+ *
+ *   STLC_CODING_AGENT_MODEL  "${env:STLC_CODING_AGENT_MODEL}" — explicit user
+ *                            override. Empty by default; set in shell profile
+ *                            or .env to hard-pin the model regardless of agent.
+ *
+ * The detection order inside cost_tracker.py is:
+ *   STLC_CODING_AGENT_MODEL → ANTHROPIC_MODEL → CLAUDE_MODEL →
+ *   GITHUB_COPILOT_MODEL → ~/.qa-stlc/agent-model → "claude-sonnet-4-6"
+ *
+ * RESULT: zero configuration for Claude Code users — the model is detected
+ * automatically. Copilot / Cursor / Windsurf users set STLC_CODING_AGENT_MODEL
+ * once in their shell profile or run `qa-stlc cost --set-model <model>`.
  */
+
 "use strict";
 
-const path     = require("path");
-const fs       = require("fs");
+const path        = require("path");
+const fs          = require("fs");
+const os          = require("os");
 const { spawnSync } = require("child_process");
 
 const C = {
@@ -15,45 +43,54 @@ const C = {
   yellow: "\x1b[33m", red: "\x1b[31m", dim: "\x1b[2m",
 };
 const ok   = (m) => console.log(`${C.green}✓${C.reset}  ${m}`);
-const info = (m) => console.log(`${C.cyan}→${C.reset}  ${m}`);
 const warn = (m) => console.log(`${C.yellow}⚠${C.reset}  ${m}`);
 
-const os   = require("os");
-const fs_  = fs;  // alias — fs already required above
-
-const PREF_FILE_MCP = require("path").join(os.homedir(), ".qa-stlc", "integration");
+const PREF_FILE_MCP = path.join(os.homedir(), ".qa-stlc", "integration");
 
 function readIntegrationPref() {
   try {
-    if (fs_.existsSync(PREF_FILE_MCP))
-      return fs_.readFileSync(PREF_FILE_MCP, "utf8").trim();
+    if (fs.existsSync(PREF_FILE_MCP))
+      return fs.readFileSync(PREF_FILE_MCP, "utf8").trim();
   } catch (_) {}
   return "ado";
 }
 
-const CWD = process.cwd();
+const CWD    = process.cwd();
 const IS_WIN = process.platform === "win32";
-const EXT = IS_WIN ? ".exe" : "";
+const EXT    = IS_WIN ? ".exe" : "";
 
-const AGENT_NAMES = [
+const AGENT_NAMES    = [
   "qa-test-case-manager",
   "qa-gherkin-generator",
   "qa-playwright-generator",
   "qa-helix-writer",
 ];
-
-// Jira agent — added separately because it needs env var injection
 const JIRA_AGENT_NAME = "qa-jira-manager";
+
+// ── Cost tracking env vars injected into every server entry ───────────────
+//
+// These are passed as env block items in both .mcp.json and .vscode/mcp.json.
+// The "${env:X}" syntax is evaluated by Claude Code / VS Code at server start,
+// substituting the actual value from the coding agent's own environment.
+//
+// ANTHROPIC_MODEL is the key one: Claude Code sets it automatically, so
+// Claude Code users get correct pricing with zero manual configuration.
+const COST_ENV = {
+  // Carry the coding agent's model ID into the MCP subprocess
+  "ANTHROPIC_MODEL":          "${env:ANTHROPIC_MODEL}",
+  "GITHUB_COPILOT_MODEL":     "${env:GITHUB_COPILOT_MODEL}",
+  // Explicit override — user sets this in shell profile if auto-detect is wrong
+  "STLC_CODING_AGENT_MODEL":  "${env:STLC_CODING_AGENT_MODEL}",
+  // Opt-out flag — user sets STLC_COST_TRACKING=false in their shell to silence output
+  "STLC_COST_TRACKING":       "${env:STLC_COST_TRACKING}",
+};
+
 const JIRA_ENV_VARS = {
   JIRA_CLIENT_ID:     "${env:JIRA_CLIENT_ID}",
   JIRA_CLIENT_SECRET: "${env:JIRA_CLIENT_SECRET}",
   JIRA_CLOUD_ID:      "${env:JIRA_CLOUD_ID}",
 };
 
-/**
- * Locate the binary for an agent.
- * Priority: .venv → --python dir → system PATH → python sys.executable dir → macOS framework dirs
- */
 function findBinary(name, pythonBin) {
   // 1. .venv in cwd
   const venvBin = IS_WIN
@@ -67,116 +104,137 @@ function findBinary(name, pythonBin) {
     if (fs.existsSync(candidate)) return candidate;
   }
 
-  // 3. system PATH via which/where
+  // 3. system PATH
   const which = spawnSync(IS_WIN ? "where" : "which", [name], { encoding: "utf8" });
-  if (which.status === 0 && which.stdout.trim()) return which.stdout.trim().split("\n")[0].trim();
+  if (which.status === 0 && which.stdout.trim())
+    return which.stdout.trim().split("\n")[0].trim();
 
-  // 4. ask Python where its own bin dir is (catches framework installs not on PATH)
+  // 4. Python's own bin dir (framework installs not on PATH)
   for (const py of ["python3", "python"]) {
-    const r = spawnSync(py, ["-c", "import sys, os; print(os.path.dirname(sys.executable))"], { encoding: "utf8" });
+    const r = spawnSync(py, ["-c", "import sys,os;print(os.path.dirname(sys.executable))"], { encoding: "utf8" });
     if (r.status === 0 && r.stdout.trim()) {
       const candidate = path.join(r.stdout.trim(), name + EXT);
       if (fs.existsSync(candidate)) return candidate;
     }
   }
 
-  // 5. macOS Python.org framework fallback
+  // 5. macOS framework fallback
   if (!IS_WIN) {
-    const frameworkDirs = [
-      "/Library/Frameworks/Python.framework/Versions/3.13/bin",
-      "/Library/Frameworks/Python.framework/Versions/3.12/bin",
-      "/Library/Frameworks/Python.framework/Versions/3.11/bin",
-      "/Library/Frameworks/Python.framework/Versions/3.10/bin",
-    ];
-    for (const dir of frameworkDirs) {
-      const candidate = path.join(dir, name);
+    for (const v of ["3.13", "3.12", "3.11", "3.10"]) {
+      const candidate = `/Library/Frameworks/Python.framework/Versions/${v}/bin/${name}`;
       if (fs.existsSync(candidate)) return candidate;
     }
   }
-
   return null;
 }
 
+// ── Claude Code config (.mcp.json) ────────────────────────────────────────
+
 function buildClaudeConfig(pythonBin, playwrightPort, integration) {
   const servers = {};
   const missing = [];
   const needsAdo  = !integration || integration === "ado"  || integration === "both";
   const needsJira = integration === "jira" || integration === "both";
-
-  // ADO agents — always included for ado/both; also included for jira because
-  // qa-gherkin-generator, qa-playwright-generator, and qa-helix-writer are shared
-  // by the Jira pipeline (Gherkin → Playwright → Helix steps run the same agents).
   const activeNames = (needsAdo || needsJira) ? AGENT_NAMES : [];
 
   for (const name of activeNames) {
     const bin = findBinary(name, pythonBin);
     if (bin) {
-      servers[name] = { command: bin };
+      // Every server gets the cost tracking env block
+      servers[name] = { command: bin, env: { ...COST_ENV } };
     } else {
       missing.push(name);
-      servers[name] = { command: `/path/to/.venv/bin/${name}`, "_comment": "NOT FOUND — run: pip install qa-gentic-stlc-agents" };
+      servers[name] = {
+        command: `/path/to/.venv/bin/${name}`,
+        env: { ...COST_ENV },
+        "_comment": "NOT FOUND — run: pip install qa-gentic-stlc-agents",
+      };
     }
   }
 
-  // Jira agent — only when integration includes jira
   if (needsJira) {
     const jiraBin = findBinary(JIRA_AGENT_NAME, pythonBin);
     if (jiraBin) {
-      servers[JIRA_AGENT_NAME] = { command: jiraBin, env: JIRA_ENV_VARS };
+      servers[JIRA_AGENT_NAME] = {
+        command: jiraBin,
+        env: { ...COST_ENV, ...JIRA_ENV_VARS },
+      };
     } else {
       missing.push(JIRA_AGENT_NAME);
       servers[JIRA_AGENT_NAME] = {
         command: `/path/to/.venv/bin/${JIRA_AGENT_NAME}`,
-        env: JIRA_ENV_VARS,
+        env: { ...COST_ENV, ...JIRA_ENV_VARS },
         "_comment": "NOT FOUND — run: pip install qa-gentic-stlc-agents",
       };
     }
   }
 
   servers["playwright"] = {
-    type: "url",
-    url: `ws://localhost:${playwrightPort}`,
+    command: "npx",
+    args: ["@playwright/mcp@latest", "--isolated"],
   };
 
   return { config: { mcpServers: servers }, missing };
 }
 
+// ── VS Code config (.vscode/mcp.json) ─────────────────────────────────────
+
 function buildVscodeConfig(pythonBin, playwrightPort, integration) {
   const servers = {};
   const missing = [];
   const needsAdo  = !integration || integration === "ado"  || integration === "both";
   const needsJira = integration === "jira" || integration === "both";
-  // Shared agents (Gherkin, Playwright, Helix) are needed by both ADO and Jira pipelines.
   const activeNames = (needsAdo || needsJira) ? AGENT_NAMES : [];
 
   for (const name of activeNames) {
     const bin = findBinary(name, pythonBin);
     if (bin) {
-      servers[name] = { command: bin };
+      servers[name] = {
+        type: "stdio",
+        command: bin,
+        args: [],
+        env: { ...COST_ENV },
+      };
     } else {
       missing.push(name);
-      servers[name] = { command: `/path/to/.venv/bin/${name}`, "_comment": "NOT FOUND — run: pip install qa-gentic-stlc-agents" };
+      servers[name] = {
+        type: "stdio",
+        command: `/path/to/.venv/bin/${name}`,
+        args: [],
+        env: { ...COST_ENV },
+        "_comment": "NOT FOUND — run: pip install qa-gentic-stlc-agents",
+      };
     }
   }
 
-  // Jira agent — only when integration includes jira
   if (needsJira) {
-    const jiraBinV = findBinary(JIRA_AGENT_NAME, pythonBin);
-    if (jiraBinV) {
-      servers[JIRA_AGENT_NAME] = { command: jiraBinV, env: JIRA_ENV_VARS };
+    const jiraBin = findBinary(JIRA_AGENT_NAME, pythonBin);
+    if (jiraBin) {
+      servers[JIRA_AGENT_NAME] = {
+        type: "stdio",
+        command: jiraBin,
+        args: [],
+        env: {
+          ...COST_ENV,
+          ...JIRA_ENV_VARS,
+        },
+      };
     } else {
       missing.push(JIRA_AGENT_NAME);
       servers[JIRA_AGENT_NAME] = {
+        type: "stdio",
         command: `/path/to/.venv/bin/${JIRA_AGENT_NAME}`,
-        env: JIRA_ENV_VARS,
+        args: [],
+        env: { ...COST_ENV, ...JIRA_ENV_VARS },
         "_comment": "NOT FOUND — run: pip install qa-gentic-stlc-agents",
       };
     }
   }
 
   servers["playwright"] = {
-    type: "http",
-    url: `http://localhost:${playwrightPort}/mcp`,
+    type: "stdio",
+    command: "npx",
+    args: ["@playwright/mcp@latest", "--isolated"],
   };
 
   return { config: { servers }, missing };
@@ -185,14 +243,17 @@ function buildVscodeConfig(pythonBin, playwrightPort, integration) {
 function printNextSteps(mode, playwrightPort) {
   const isVscode = mode === "vscode";
   console.log(`
-  ${C.dim}Start Playwright MCP before running generation workflows:${C.reset}
-  npx @playwright/mcp@latest --port ${playwrightPort}
-  ${C.dim}headless (CI): npx @playwright/mcp@latest --headless --port ${playwrightPort}${C.reset}
+  ${C.dim}Playwright MCP is auto-started by the MCP framework (--isolated, no manual start needed).
+  For CI/headless: set PLAYWRIGHT_MCP_URL or start manually with --headless --isolated --port ${playwrightPort}${C.reset}
 
   ${isVscode
-    ? `Reload VS Code window — all 5 MCP servers will appear in the MCP panel.`
-    : `In Claude Code, run /mcp to verify all 5 servers are loaded.`
+    ? `Reload VS Code window — all MCP servers will appear in the MCP panel.`
+    : `In Claude Code, run /mcp to verify all servers are loaded.`
   }
+
+  ${C.dim}Cost tracking is active on all servers.
+  Each tool call logs tokens + cost to ~/.qa-stlc/cost-<session>.jsonl
+  View reports: qa-stlc cost${C.reset}
 `);
 }
 
@@ -220,7 +281,7 @@ module.exports = async function mcpConfig(opts) {
     fs.mkdirSync(dir, { recursive: true });
     const out = path.join(dir, "mcp.json");
     fs.writeFileSync(out, JSON.stringify(config, null, 2) + "\n", "utf8");
-    ok(`Written → .vscode/mcp.json`);
+    ok(`Written → .vscode/mcp.json  (cost tracking env vars included)`);
     if (missing.length) {
       warn(`${missing.length} agent(s) not found — run: pip install qa-gentic-stlc-agents`);
       missing.forEach((m) => warn(`  missing: ${m}`));
@@ -230,7 +291,7 @@ module.exports = async function mcpConfig(opts) {
     const { config, missing } = buildClaudeConfig(pythonBin, playwrightPort, integration);
     const out = path.join(CWD, ".mcp.json");
     fs.writeFileSync(out, JSON.stringify(config, null, 2) + "\n", "utf8");
-    ok(`Written → .mcp.json`);
+    ok(`Written → .mcp.json  (cost tracking env vars included)`);
     if (missing.length) {
       warn(`${missing.length} agent(s) not found — run: pip install qa-gentic-stlc-agents`);
       missing.forEach((m) => warn(`  missing: ${m}`));

package/src/cli/cmd-skills.js

@@ -9,6 +9,8 @@
  *   windsurf  →  .windsurf/rules/
  *   both      →  claude + vscode
  *   print     →  stdout only
+ *
+ * Also installs ORCHESTRATION_RULES.md to project root (multi-step workflow reference).
  */
 "use strict";
 
@@ -35,10 +37,11 @@ function readIntegrationPrefSk() {
 }
 
 // Resolve the skills bundled with this npm package
-const PKG_ROOT    = path.resolve(__dirname, "../..");
-const SKILLS_DIR  = path.join(PKG_ROOT, "skills");
-const BEHAVIOR_MD = path.join(SKILLS_DIR, "AGENT-BEHAVIOR.md");
-const AGENTS_DIR  = path.join(PKG_ROOT, ".github", "agents");
+const PKG_ROOT           = path.resolve(__dirname, "../..");
+const SKILLS_DIR         = path.join(PKG_ROOT, "skills");
+const BEHAVIOR_MD        = path.join(SKILLS_DIR, "AGENT-BEHAVIOR.md");
+const ORCHESTRATION_MD   = path.join(PKG_ROOT, "ORCHESTRATION_RULES.md");
+const AGENTS_DIR         = path.join(PKG_ROOT, ".github", "agents");
 
 /** Copy a file, creating parent dirs as needed. */
 function cp(src, dest) {
@@ -105,6 +108,15 @@ function installAgents(integration) {
   agentFiles(integration).forEach((f) => info(path.basename(f)));
 }
 
+/** Install ORCHESTRATION_RULES.md to project root for multi-step workflow reference. */
+function installOrchestrationRules() {
+  if (!fs.existsSync(ORCHESTRATION_MD)) return;
+  const dest = path.join(CWD, "ORCHESTRATION_RULES.md");
+  cp(ORCHESTRATION_MD, dest);
+  ok(`ORCHESTRATION_RULES.md installed → project root`);
+  info("Reference this file for multi-step QA workflow best practices");
+}
+
 function installClaude(integration) {
   const dest = path.join(CWD, ".claude", "skills");
   // Copy entire skill directory (preserves references/ subdirectory)
@@ -118,6 +130,7 @@ function installClaude(integration) {
   info("AGENT-BEHAVIOR.md → .claude/AGENT-BEHAVIOR.md");
   skillEntries(integration).forEach((e) => info(`${e.name}/SKILL.md`));
   installAgents(integration);
+  installOrchestrationRules();
   printPlaywrightHint();
 }
 
@@ -134,6 +147,7 @@ function installVscode(integration) {
   info("AGENT-BEHAVIOR.md → .github/copilot-instructions/AGENT-BEHAVIOR.md");
   skillEntries(integration).forEach((e) => info(`${e.name}/SKILL.md`));
   installAgents(integration);
+  installOrchestrationRules();
   printPlaywrightHint();
 }
 
@@ -146,6 +160,7 @@ function installCursor(integration) {
   cp(BEHAVIOR_MD, path.join(dest, "AGENT-BEHAVIOR.md"));
   ok(`Skills installed → .cursor/rules/`);
   installAgents(integration);
+  installOrchestrationRules();
   printPlaywrightHint();
 }
 
@@ -158,6 +173,7 @@ function installWindsurf(integration) {
   cp(BEHAVIOR_MD, path.join(dest, "AGENT-BEHAVIOR.md"));
   ok(`Skills installed → .windsurf/rules/`);
   installAgents(integration);
+  installOrchestrationRules();
   printPlaywrightHint();
 }
 
@@ -165,6 +181,7 @@ function printSkills() {
   console.log("\nAvailable skills:\n");
   skillEntries().forEach((e) => console.log(`  ${e.name}/SKILL.md`));
   console.log(`  AGENT-BEHAVIOR.md`);
+  console.log(`  ORCHESTRATION_RULES.md (workflow reference)`);
 }
 
 /** Recursively copy a directory tree. */

package/src/stlc_agents/agent_gherkin_generator/server.py

@@ -323,6 +323,55 @@ async def list_tools() -> list[types.Tool]:
                 "required": ["gherkin_content"],
             },
         ),
+
+        # ── NEW: Headless composite — fetch + validate + attach with retry ───
+        types.Tool(
+            name="generate_and_attach_gherkin",
+            description=(
+                "Headless composite tool: fetch work item data, validate Gherkin content, "
+                "and attach to ADO — retrying once internally if validation fails. "
+                "Use this from the pipeline or CI runner instead of calling "
+                "validate_gherkin_content + attach_gherkin_to_feature/work_item separately. "
+                "Accepts pre-generated gherkin_content from the LLM caller. "
+                "If validation fails on the first pass the errors are returned as "
+                "validation_failed (no retry is possible without a new LLM call — "
+                "the pipeline must re-generate and call this tool again). "
+                "Returns {status, gherkin_content, attached} on success, "
+                "or {status: validation_failed, errors, gherkin_content} on failure."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "work_item_id": {
+                        "type": "integer",
+                        "description": "ADO Feature, PBI, or Bug ID",
+                    },
+                    "work_item_title": {
+                        "type": "string",
+                        "description": "Title of the work item (used in filename)",
+                    },
+                    "organization_url": {"type": "string"},
+                    "project_name": {"type": "string"},
+                    "gherkin_content": {
+                        "type": "string",
+                        "description": "Pre-generated .feature file content from LLM caller",
+                    },
+                    "scope": {
+                        "type": "string",
+                        "enum": ["feature", "work_item"],
+                        "description": (
+                            "'feature' attaches to a Feature work item (5–10 scenarios). "
+                            "'work_item' attaches to a PBI or Bug (3–9 scenarios). "
+                            "Default: 'work_item'."
+                        ),
+                    },
+                },
+                "required": [
+                    "work_item_id", "work_item_title", "organization_url",
+                    "project_name", "gherkin_content",
+                ],
+            },
+        ),
     ]
 
 
@@ -416,6 +465,44 @@ async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
                 arguments.get("scope", "feature"),
             )
 
+        elif name == "generate_and_attach_gherkin":
+            org = arguments["organization_url"]
+            project = arguments["project_name"]
+            wi_id = arguments["work_item_id"]
+            wi_title = arguments["work_item_title"]
+            gherkin = arguments["gherkin_content"]
+            scope = arguments.get("scope", "work_item")
+
+            # Step 1: validate
+            validation = await asyncio.to_thread(_validate_gherkin, gherkin, scope)
+            if not validation["valid"]:
+                result = {
+                    "status": "validation_failed",
+                    "errors": validation.get("errors", []),
+                    "gherkin_content": gherkin,
+                    "message": (
+                        "Gherkin content failed structural validation. "
+                        "The pipeline must re-generate and call this tool again "
+                        "with corrected content. No file was attached to ADO."
+                    ),
+                }
+            else:
+                # Step 2: attach
+                if scope == "feature":
+                    attach = await asyncio.to_thread(
+                        _attach_feature, org, project, wi_id, wi_title, gherkin
+                    )
+                else:
+                    attach = await asyncio.to_thread(
+                        _attach_wi_file, org, project, wi_id, wi_title, gherkin
+                    )
+                attach["_validation"] = _validate_attach_response(attach, scope)
+                result = {
+                    "status": "ok",
+                    "gherkin_content": gherkin,
+                    "attached": attach,
+                }
+
         else:
             result = {"error": f"Unknown tool: {name}"}
 
@@ -448,7 +535,4 @@ def main():
 
 
 if __name__ == "__main__":
-    main()
-
-
-    
+    main()

package/src/stlc_agents/agent_helix_writer/tools/helix_write.py

@@ -40,6 +40,10 @@ Within-file deduplication
                      src/test/features/ are scanned for existing scenario titles.
                      A title already present in any sibling file is treated as a
                      duplicate and dropped from the incoming content.
+  For cucumber.config.ts : new profiles are appended ONLY if the file already exists.
+                     If the file does not exist, the profile is skipped entirely.
+                     This prevents orphaned config files from being created when
+                     no Cucumber config yet exists on disk.
 
 Interface adapter
   The generator emits repo.updateHealed / repo.incrementSuccess / repo.getBBox etc.
@@ -140,11 +144,26 @@ def _adapt_to_helix_interface(content: str) -> str:
         'import { EnvironmentManager } from "@helper/environment/environmentManager.util";',
         'import { environment } from "@config/environment";',
     )
+    # If content uses environment.getConfig() but lacks the import, add it after the last import line
+    if "environment.getConfig()" in content and 'from "@config/environment"' not in content:
+        import_insert = 'import { environment } from "@config/environment";'
+        # Insert after the last import statement
+        last_import = content.rfind("\nimport ")
+        if last_import != -1:
+            end_of_line = content.find("\n", last_import + 1)
+            if end_of_line != -1:
+                content = content[:end_of_line + 1] + import_insert + "\n" + content[end_of_line + 1:]
     content = re.sub(r"\s*this\.env\s*=\s*new EnvironmentManager\(\);?\s*\n", "\n", content)
     content = content.replace("new EnvironmentManager()", "environment")
     content = content.replace("this.env.getBaseUrl()",    "environment.getConfig().baseUrl")
     content = re.sub(r"this\.env\.getPath\(['\"]([^'\"]+)['\"]\)", r'"\1"', content)
 
+    # Fix super() — cannot access this before super() in TS
+    content = content.replace(
+        "super(page ?? this.page);",
+        "super(page ?? fixture().page);",
+    )
+
     return content
 
 
@@ -162,11 +181,22 @@ def _resolve_destination(helix_root: Path, file_key: str) -> Path:
     if _STEPS_RE.search(key):
         return helix_root / "src" / "test" / "steps" / Path(key).name
     if _LOCATOR_RE.search(key):
-        parts = Path(key).parts
-        stem = next(
-            (p for p in parts if p not in ("src", "pages", "locators", "utils") and not p.endswith(".ts")),
-            "page",
-        )
+        # Extract the page/feature name from the path
+        # Input: src/pages/login-page/locators.ts or src/locators/login-page.locators.ts
+        # Output stem: login-page
+        path_obj = Path(key)
+        
+        # First try: if filename is exactly 'locators.ts', use parent directory name
+        if path_obj.name == "locators.ts" and path_obj.parent.name:
+            stem = path_obj.parent.name
+        else:
+            # Otherwise extract stem from filename
+            fname = path_obj.name
+            stem = re.sub(r"\.locators\.ts$", "", fname)
+            stem = re.sub(r"\.ts$", "", stem)
+            if not stem or stem in ("src", "locators", "pages", "utils"):
+                stem = "page"
+        
         return helix_root / "src" / "locators" / f"{stem}.locators.ts"
     if _PAGE_RE.search(key):
         return helix_root / "src" / "pages" / Path(key).name
@@ -242,7 +272,7 @@ def _collect_all_scenario_titles(features_dir: Path, exclude_file: Path | None =
     return titles
 
 
-
+def _collect_all_step_patterns(steps_dir: Path, exclude_file: Path | None = None) -> set[str]:
     """Return every /^pattern$/ defined in all *.steps.ts files in steps_dir,
     optionally excluding one file (the one currently being written)."""
     patterns: set[str] = set()
@@ -627,29 +657,31 @@ def write_files_to_helix(
                 skipped.append({"file_key": file_key, "dest": dest_rel, "reason": str(exc)})
             continue
 
-        # ── Cucumber config: append profile, skip duplicate ────────────────
+        # ── Cucumber config: append profile only if file exists, never create ────────────
         if _CUCUMBER_RE.search(file_key):
+            if not dest.exists():
+                # RULE: if cucumber config does not exist, skip creation
+                skipped.append({
+                    "file_key": file_key, "dest": dest_rel,
+                    "reason": "cucumber.config.ts does not exist; only append to existing configs",
+                })
+                continue
             try:
-                if dest.exists():
-                    existing_text  = dest.read_text(encoding="utf-8")
-                    profile_match  = re.match(r"\s*(\w+)\s*:", content.strip())
-                    profile_name   = profile_match.group(1) if profile_match else None
-                    if profile_name and profile_name in existing_text:
-                        skipped.append({
-                            "file_key": file_key, "dest": dest_rel,
-                            "reason": f"profile '{profile_name}' already exists in cucumber.config.ts",
-                        })
-                        continue
-                    dest.write_text(
-                        existing_text.rstrip() + "\n\n// --- generated profile ---\n" + content,
-                        encoding="utf-8",
-                    )
-                    written.append({"file_key": file_key, "dest": dest_rel,
-                                    "bytes": len(content.encode()), "action": "appended"})
-                else:
-                    dest.write_text(content, encoding="utf-8")
-                    written.append({"file_key": file_key, "dest": dest_rel,
-                                    "bytes": len(content.encode()), "action": "created"})
+                existing_text  = dest.read_text(encoding="utf-8")
+                profile_match  = re.match(r"\s*(\w+)\s*:", content.strip())
+                profile_name   = profile_match.group(1) if profile_match else None
+                if profile_name and profile_name in existing_text:
+                    skipped.append({
+                        "file_key": file_key, "dest": dest_rel,
+                        "reason": f"profile '{profile_name}' already exists in cucumber.config.ts",
+                    })
+                    continue
+                dest.write_text(
+                    existing_text.rstrip() + "\n\n// --- generated profile ---\n" + content,
+                    encoding="utf-8",
+                )
+                written.append({"file_key": file_key, "dest": dest_rel,
+                                "bytes": len(content.encode()), "action": "appended"})
             except OSError as exc:
                 skipped.append({"file_key": file_key, "dest": dest_rel, "reason": str(exc)})
             continue
@@ -867,4 +899,4 @@ def list_helix_tree(helix_root: str) -> dict[str, Any]:
         else:
             tree["other"].append(rel)
 
-    return {"success": True, "helix_root": str(root), "tree": tree}
+    return {"success": True, "helix_root": str(root), "tree": tree}