peaks-cli 1.0.11 → 1.0.12

package/dist/src/cli/commands/config-commands.js

@@ -1,4 +1,5 @@
-import { addWorkspace, getConfig, getMiniMaxProviderConfig, getMiniMaxProviderStatus, isSensitiveConfigPath, readConfig, redactConfigSecrets, removeWorkspace, setConfig, setCurrentWorkspace, setMiniMaxProviderConfig } from '../../services/config/config-service.js';
+import { getLocalArtifactPath } from '../../services/artifacts/workspace-service.js';
+import { addWorkspace, ensureWorkspaceConfigForPath, getConfig, getMiniMaxProviderConfig, getMiniMaxProviderStatus, isSensitiveConfigPath, readConfig, redactConfigSecrets, removeWorkspace, setConfig, setCurrentWorkspace, setMiniMaxProviderConfig } from '../../services/config/config-service.js';
 import { testMiniMaxProvider } from '../../services/providers/minimax-provider-service.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, getErrorMessage, isArtifactProvider, isArtifactRepoSegment, isMiniMaxHttpsUrl, parseConfigLayer, printInvalidConfigLayer, printResult, redactSensitiveErrorMessage, summarizeMiniMaxSmokeResult } from '../cli-helpers.js';
@@ -135,6 +136,21 @@ function registerWorkspaceCommands(config, io) {
         const cfg = readConfig();
         printResult(io, ok('config.workspace.list', { currentWorkspace: cfg.currentWorkspace, workspaces: cfg.workspaces }), options.json);
     });
+    addJsonOption(configWorkspace.command('ensure').description('Ensure a user workspace exists for a project path and make it current').option('--path <path>', 'project path to ensure, defaults to cwd')).action((options) => {
+        try {
+            const workspace = ensureWorkspaceConfigForPath(options.path ?? process.cwd());
+            if (!workspace) {
+                printResult(io, fail('config.workspace.ensure', 'WORKSPACE_ENSURE_FAILED', 'Could not resolve a workspace for the provided path', {}, ['Run from inside a project or pass --path <project>']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('config.workspace.ensure', { workspace, currentWorkspace: workspace.workspaceId, artifactWorkspacePath: getLocalArtifactPath(workspace) }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('config.workspace.ensure', 'WORKSPACE_ENSURE_FAILED', getErrorMessage(error), {}, ['Check that the project path exists and artifact workspace markers are safe']), options.json);
+            process.exitCode = 1;
+        }
+    });
     addJsonOption(configWorkspace.command('add').description('Add a workspace').requiredOption('--id <id>', 'workspace identifier').requiredOption('--name <name>', 'workspace display name').requiredOption('--path <path>', 'workspace root path').option('--provider <provider>', 'artifact repo provider: github or gitlab').option('--repo-owner <owner>', 'artifact repo owner').option('--repo-name <name>', 'artifact repo name').option('--layer <layer>', 'user or project')).action((options) => {
         const layer = parseConfigLayer(options.layer);
         if (layer === null) {

package/dist/src/cli/commands/workflow-commands.js

@@ -11,21 +11,20 @@ import { getLocalArtifactPath } from '../../services/artifacts/workspace-service
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, failUnsupportedNonDryRun, getErrorMessage, isRecommendationWorkflow, printResult } from '../cli-helpers.js';
 function getCurrentWorkspaceContext() {
-    const workspace = getCurrentWorkspaceConfig();
+    const workspace = ensureWorkspaceConfigForCurrentPath() ?? getCurrentWorkspaceConfig();
     if (!workspace)
         return {};
     return { workspace, artifactWorkspacePath: getLocalArtifactPath(workspace) };
 }
 function getWorkflowWorkspaceContext() {
-    try {
-        const workspace = ensureWorkspaceConfigForCurrentPath() ?? getCurrentWorkspaceConfig();
-        if (!workspace)
-            return {};
-        return { workspace, artifactWorkspacePath: getLocalArtifactPath(workspace) };
-    }
-    catch {
+    const workspace = ensureWorkspaceConfigForCurrentPath() ?? getCurrentWorkspaceConfig();
+    if (!workspace)
         return {};
-    }
+    return { workspace, artifactWorkspacePath: getLocalArtifactPath(workspace) };
+}
+function failWorkflowWorkspaceContext(io, command, error, asJson) {
+    printResult(io, fail(command, 'WORKSPACE_CONTEXT_FAILED', getErrorMessage(error), {}, ['Run peaks config workspace ensure --path <project> --json and resolve the reported workspace issue']), asJson);
+    process.exitCode = 1;
 }
 function parseMaxWorkers(io, command, value, asJson) {
     const maxWorkers = Number(value);
@@ -65,24 +64,39 @@ function runTechPlan(io, options) {
     }
     try {
         validatePlanningInput(options.changeId, options.goal);
-        const workspaceContext = getCurrentWorkspaceContext();
-        const plan = createTechPlan({
-            changeId: options.changeId,
-            goal: options.goal,
-            swarm: options.swarm ?? false,
-            dryRun: true,
-            ...workspaceContext
-        });
-        printResult(io, ok('tech.plan', plan), options.json);
     }
     catch (error) {
         printResult(io, fail('tech.plan', 'INVALID_CHANGE_ID_OR_GOAL', getErrorMessage(error), {}, ['Use a safe change id and a non-empty goal']), options.json);
         process.exitCode = 1;
+        return;
+    }
+    let workspaceContext;
+    try {
+        workspaceContext = getCurrentWorkspaceContext();
+    }
+    catch (error) {
+        failWorkflowWorkspaceContext(io, 'tech.plan', error, options.json);
+        return;
     }
+    const plan = createTechPlan({
+        changeId: options.changeId,
+        goal: options.goal,
+        swarm: options.swarm ?? false,
+        dryRun: true,
+        ...workspaceContext
+    });
+    printResult(io, ok('tech.plan', plan), options.json);
 }
 function runTechStatus(io, options) {
+    let workspaceContext;
+    try {
+        workspaceContext = getCurrentWorkspaceContext();
+    }
+    catch (error) {
+        failWorkflowWorkspaceContext(io, 'tech.status', error, options.json);
+        return;
+    }
     try {
-        const workspaceContext = getCurrentWorkspaceContext();
         printResult(io, ok('tech.status', getTechStatus({ changeId: options.changeId, ...workspaceContext })), options.json);
     }
     catch (error) {
@@ -108,23 +122,31 @@ function runWorkflowRoute(io, options) {
         return;
     try {
         validatePlanningInput(options.changeId, options.goal);
-        const workspaceContext = getWorkflowWorkspaceContext();
-        const plan = createWorkflowRouterPlan({
-            changeId: options.changeId,
-            goal: options.goal,
-            mode: options.mode,
-            ...(soloMode ? { soloMode } : {}),
-            maxWorkers,
-            dryRun: true,
-            config: readConfig(),
-            ...workspaceContext
-        });
-        printResult(io, ok('workflow.route', plan), options.json);
     }
     catch (error) {
         printResult(io, fail('workflow.route', 'INVALID_CHANGE_ID_OR_GOAL', getErrorMessage(error), {}, ['Use a safe change id and a non-empty goal']), options.json);
         process.exitCode = 1;
+        return;
     }
+    let workspaceContext;
+    try {
+        workspaceContext = getWorkflowWorkspaceContext();
+    }
+    catch (error) {
+        failWorkflowWorkspaceContext(io, 'workflow.route', error, options.json);
+        return;
+    }
+    const plan = createWorkflowRouterPlan({
+        changeId: options.changeId,
+        goal: options.goal,
+        mode: options.mode,
+        ...(soloMode ? { soloMode } : {}),
+        maxWorkers,
+        dryRun: true,
+        config: readConfig(),
+        ...workspaceContext
+    });
+    printResult(io, ok('workflow.route', plan), options.json);
 }
 function runAutonomousWorkflow(io, options) {
     if (options.dryRun === false) {
@@ -144,23 +166,31 @@ function runAutonomousWorkflow(io, options) {
         return;
     try {
         validatePlanningInput(options.changeId, options.goal);
-        const workspaceContext = getWorkflowWorkspaceContext();
-        const plan = createAutonomousWorkflowPlan({
-            changeId: options.changeId,
-            goal: options.goal,
-            mode: options.mode,
-            ...(soloMode ? { soloMode } : {}),
-            maxWorkers,
-            dryRun: true,
-            config: readConfig(),
-            ...workspaceContext
-        });
-        printResult(io, ok('workflow.autonomous', plan), options.json);
     }
     catch (error) {
         printResult(io, fail('workflow.autonomous', 'INVALID_CHANGE_ID_OR_GOAL', getErrorMessage(error), {}, ['Use a safe change id and a non-empty goal']), options.json);
         process.exitCode = 1;
+        return;
+    }
+    let workspaceContext;
+    try {
+        workspaceContext = getWorkflowWorkspaceContext();
     }
+    catch (error) {
+        failWorkflowWorkspaceContext(io, 'workflow.autonomous', error, options.json);
+        return;
+    }
+    const plan = createAutonomousWorkflowPlan({
+        changeId: options.changeId,
+        goal: options.goal,
+        mode: options.mode,
+        ...(soloMode ? { soloMode } : {}),
+        maxWorkers,
+        dryRun: true,
+        config: readConfig(),
+        ...workspaceContext
+    });
+    printResult(io, ok('workflow.autonomous', plan), options.json);
 }
 function runSwarmPlan(io, options) {
     if ((options.skill ?? 'rd') !== 'rd') {
@@ -177,24 +207,32 @@ function runSwarmPlan(io, options) {
         return;
     try {
         validatePlanningInput(options.changeId, options.goal);
-        const workspaceContext = getWorkflowWorkspaceContext();
-        const config = readConfig();
-        const plan = createRdSwarmPlan({
-            skill: 'rd',
-            changeId: options.changeId,
-            goal: options.goal,
-            maxWorkers,
-            dryRun: true,
-            swarmMode: config.swarmMode,
-            executionModelId: getEconomyAwareExecutionModelId(config),
-            ...workspaceContext
-        });
-        printResult(io, ok('swarm.plan', plan), options.json);
     }
     catch (error) {
         printResult(io, fail('swarm.plan', 'INVALID_CHANGE_ID_OR_GOAL', getErrorMessage(error), {}, ['Use a safe change id and a non-empty goal']), options.json);
         process.exitCode = 1;
+        return;
+    }
+    let workspaceContext;
+    try {
+        workspaceContext = getWorkflowWorkspaceContext();
     }
+    catch (error) {
+        failWorkflowWorkspaceContext(io, 'swarm.plan', error, options.json);
+        return;
+    }
+    const config = readConfig();
+    const plan = createRdSwarmPlan({
+        skill: 'rd',
+        changeId: options.changeId,
+        goal: options.goal,
+        maxWorkers,
+        dryRun: true,
+        swarmMode: config.swarmMode,
+        executionModelId: getEconomyAwareExecutionModelId(config),
+        ...workspaceContext
+    });
+    printResult(io, ok('swarm.plan', plan), options.json);
 }
 function addTechPlanOptions(command) {
     return addJsonOption(command

package/dist/src/services/codegraph/codegraph-service.js

@@ -1,19 +1,15 @@
 import { existsSync, realpathSync, statSync } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
-import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { dirname, isAbsolute, relative, resolve, sep, win32 } from 'node:path';
 const CODEGRAPH_PACKAGE_NAME = '@colbymchenry/codegraph';
 const CODEGRAPH_PACKAGE_VERSION = '0.7.10';
 const CODEGRAPH_EXECUTABLE = process.execPath;
 const CODEGRAPH_BINARY_PATH = resolveCodegraphBinaryPath();
 const CODEGRAPH_PROCESS_TIMEOUT_MS = 600_000;
 const CODEGRAPH_OUTPUT_LIMIT_BYTES = 10 * 1024 * 1024;
-const NODE_OPTIONS_ENV_KEY = 'NODE_OPTIONS';
-const NPM_CONFIG_PREFIX = 'npm_config_';
-const NPM_CONFIG_UPPER_PREFIX = 'NPM_CONFIG_';
 const POSITIONAL_ARGUMENT_PREFIX = '-';
 const ALLOWED_SUBCOMMANDS = ['status', 'init', 'index', 'query', 'files', 'context', 'affected'];
-const NUMERIC_FLAG_NAMES = ['limit', 'maxDepth'];
 const COMMON_OPTION_KEYS = ['subcommand', 'project'];
 const ALLOWED_OPTIONS_BY_SUBCOMMAND = {
     status: [],
@@ -24,13 +20,16 @@ const ALLOWED_OPTIONS_BY_SUBCOMMAND = {
     context: ['task'],
     affected: ['files', 'json']
 };
+function assertCodegraphBinaryExists(binaryPath) {
+    if (!existsSync(binaryPath)) {
+        throw new Error('Unable to resolve local codegraph binary from @colbymchenry/codegraph');
+    }
+}
 function resolveCodegraphBinaryPath() {
     const require = createRequire(import.meta.url);
     const packageJsonPath = require.resolve('@colbymchenry/codegraph/package.json');
     const binaryPath = resolve(dirname(packageJsonPath), 'dist', 'bin', 'codegraph.js');
-    if (!existsSync(binaryPath)) {
-        throw new Error('Unable to resolve local codegraph binary from @colbymchenry/codegraph');
-    }
+    assertCodegraphBinaryExists(binaryPath);
     return binaryPath;
 }
 function assertSupportedSubcommand(subcommand) {
@@ -38,12 +37,15 @@ function assertSupportedSubcommand(subcommand) {
         throw new Error(`Unsupported codegraph subcommand: ${subcommand}`);
     }
 }
+function assertProjectRootDirectory(projectRoot) {
+    if (!statSync(projectRoot).isDirectory()) {
+        throw new Error('Project path must exist and be a directory');
+    }
+}
 function resolveProjectRoot(project) {
     const projectRoot = resolve(project);
     try {
-        if (!statSync(projectRoot).isDirectory()) {
-            throw new Error('Project path must exist and be a directory');
-        }
+        assertProjectRootDirectory(projectRoot);
         return realpathSync.native(projectRoot);
     }
     catch {
@@ -88,12 +90,8 @@ function assertInsideProject(projectRoot, absolutePath) {
         throw new Error('Affected files must stay inside the project');
     }
 }
-function resolveExistingBoundary(absoluteFilePath) {
-    if (existsSync(absoluteFilePath)) {
-        return absoluteFilePath;
-    }
-    let currentPath = dirname(absoluteFilePath);
-    while (!existsSync(currentPath)) {
+function climbToExistingBoundary(currentPath, pathExists = existsSync) {
+    while (!pathExists(currentPath)) {
         const parentPath = dirname(currentPath);
         if (parentPath === currentPath) {
             return currentPath;
@@ -102,6 +100,9 @@ function resolveExistingBoundary(absoluteFilePath) {
     }
     return currentPath;
 }
+function resolveExistingBoundary(absoluteFilePath) {
+    return existsSync(absoluteFilePath) ? absoluteFilePath : climbToExistingBoundary(dirname(absoluteFilePath));
+}
 function normalizeProjectRelativeFile(projectRoot, file) {
     assertPositionalArgument(file, 'Affected files');
     const absoluteFilePath = resolve(projectRoot, file);
@@ -110,10 +111,13 @@ function normalizeProjectRelativeFile(projectRoot, file) {
     assertInsideProject(projectRoot, realBoundary);
     return relative(projectRoot, absoluteFilePath).split(sep).join('/');
 }
-function buildAffectedFileArgs(projectRoot, files) {
+function assertAffectedFiles(files) {
     if (!files || files.length < 1) {
         throw new Error('affected requires at least one file');
     }
+}
+function buildAffectedFileArgs(projectRoot, files) {
+    assertAffectedFiles(files);
     return files.map((file) => normalizeProjectRelativeFile(projectRoot, file));
 }
 function buildCommandArgs(options, projectRoot) {
@@ -168,24 +172,36 @@ function assertOutputLimit(currentSize, chunkSize) {
     }
     return nextSize;
 }
-function terminateCodegraphProcess(childProcess) {
+function getWindowsTaskkillPath(fileExists = existsSync) {
+    const candidates = [
+        win32.join('C:\\Windows', 'System32', 'taskkill.exe'),
+        win32.join('C:\\WINNT', 'System32', 'taskkill.exe')
+    ];
+    return candidates.find((candidate) => fileExists(candidate)) ?? null;
+}
+function terminateCodegraphProcess(childProcess, platform = process.platform, killProcess = process.kill, spawnProcess = spawn, taskkillPath = getWindowsTaskkillPath()) {
     if (childProcess.pid === undefined) {
         childProcess.kill();
         return;
     }
-    if (process.platform === 'win32') {
-        const taskkillPath = process.env.SystemRoot ? join(process.env.SystemRoot, 'System32', 'taskkill.exe') : 'taskkill.exe';
-        spawn(taskkillPath, ['/pid', String(childProcess.pid), '/T', '/F'], { shell: false, stdio: 'ignore' });
+    if (platform === 'win32') {
+        if (!taskkillPath) {
+            childProcess.kill();
+            return;
+        }
+        const killerProcess = spawnProcess(taskkillPath, ['/pid', String(childProcess.pid), '/T', '/F'], { shell: false, stdio: 'ignore' });
+        killerProcess.on('error', () => childProcess.kill());
+        killerProcess.unref();
         return;
     }
     try {
-        process.kill(-childProcess.pid, 'SIGTERM');
+        killProcess(-childProcess.pid, 'SIGTERM');
     }
     catch {
         childProcess.kill('SIGTERM');
     }
 }
-function defaultCodegraphProcessRunner(invocation) {
+function runCodegraphProcess(invocation, timeoutMs = CODEGRAPH_PROCESS_TIMEOUT_MS) {
     return new Promise((resolveResult, reject) => {
         const childProcess = spawn(invocation.executable, invocation.args, {
             cwd: invocation.cwd,
@@ -195,8 +211,8 @@ function defaultCodegraphProcessRunner(invocation) {
         });
         const timeout = setTimeout(() => {
             terminateCodegraphProcess(childProcess);
-            reject(new Error(`codegraph process timed out after ${CODEGRAPH_PROCESS_TIMEOUT_MS}ms`));
-        }, CODEGRAPH_PROCESS_TIMEOUT_MS);
+            reject(new Error(`codegraph process timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
         const stdoutChunks = [];
         const stderrChunks = [];
         let stdoutSize = 0;
@@ -235,6 +251,9 @@ function defaultCodegraphProcessRunner(invocation) {
         });
     });
 }
+function defaultCodegraphProcessRunner(invocation) {
+    return runCodegraphProcess(invocation);
+}
 export function createCodegraphInvocation(options) {
     assertSupportedSubcommand(options.subcommand);
     const projectRoot = resolveProjectRoot(options.project);

package/dist/src/services/config/config-service.js

@@ -156,6 +156,25 @@ function validateUserConfigPathForWrite(configPath) {
         }
     }
 }
+function getExistingBoundary(path) {
+    let currentPath = resolve(path);
+    while (!existsSync(currentPath)) {
+        const parentPath = dirname(currentPath);
+        if (parentPath === currentPath) {
+            return currentPath;
+        }
+        currentPath = parentPath;
+    }
+    return currentPath;
+}
+function validateArtifactWorkspaceRootBeforeCreate(artifactRoot, workspaceRoot) {
+    const workspaceRootReal = realpathSync(workspaceRoot);
+    const existingBoundary = getExistingBoundary(artifactRoot);
+    const existingBoundaryReal = realpathSync(existingBoundary);
+    if (isInsidePath(resolve(artifactRoot), workspaceRoot) || isInsidePath(existingBoundaryReal, workspaceRootReal)) {
+        throw new Error('Artifact workspace must stay outside the project root');
+    }
+}
 function validateArtifactWorkspaceRoot(artifactRoot, workspaceRoot) {
     const artifactStats = lstatSync(artifactRoot);
     if (!artifactStats.isDirectory() || artifactStats.isSymbolicLink()) {
@@ -871,6 +890,7 @@ function ensureArtifactWorkspaceMarker(workspace) {
     const artifactRoot = getWorkspaceArtifactRoot(workspace);
     const peaksPath = resolve(artifactRoot, '.peaks');
     const markerPath = resolve(peaksPath, 'config.json');
+    validateArtifactWorkspaceRootBeforeCreate(artifactRoot, workspace.rootPath);
     ensureDir(artifactRoot);
     validateArtifactWorkspaceRoot(artifactRoot, workspace.rootPath);
     ensureDir(peaksPath);
@@ -887,7 +907,7 @@ export function ensureWorkspaceConfigForPath(path = process.cwd()) {
     const existingWorkspace = findWorkspaceForPath(config.workspaces, path);
     if (existingWorkspace) {
         ensureArtifactWorkspaceMarker(existingWorkspace);
-        if (!config.currentWorkspace) {
+        if (config.currentWorkspace !== existingWorkspace.workspaceId) {
             writeConfig({ currentWorkspace: existingWorkspace.workspaceId }, 'user');
         }
         return existingWorkspace;
@@ -903,7 +923,7 @@ export function ensureWorkspaceConfigForPath(path = process.cwd()) {
     };
     ensureArtifactWorkspaceMarker(workspace);
     const updatedWorkspaces = [...config.workspaces, workspace];
-    writeConfig({ workspaces: updatedWorkspaces, ...(!config.currentWorkspace ? { currentWorkspace: workspace.workspaceId } : {}) }, 'user');
+    writeConfig({ workspaces: updatedWorkspaces, currentWorkspace: workspace.workspaceId }, 'user');
     return workspace;
 }
 export function getWorkspaceConfigForCurrentPath() {

package/dist/src/services/recommendations/capability-seed-items.js

@@ -87,7 +87,7 @@ export const seedCapabilityItems = [
     capability('codegraph.semantic-query', 'codegraph', 'Codegraph Semantic Query', 'cli', 'project-analysis', ['engineer'], 'medium', 'peaks-rd-local-scan', 'Use local Grep/Glob and RD scanning when codegraph semantic query is unavailable.', 'Codegraph Semantic Query', 'Codegraph 语义查询', 'Queries local symbols and project relationships for RD planning evidence.', '查询本地符号和项目关系，为 RD 规划提供证据。'),
     capability('codegraph.impact-analysis', 'codegraph', 'Codegraph Impact Analysis', 'cli', 'impact-analysis', ['engineer', 'qa'], 'medium', 'peaks-rd-qa-impact-review', 'Use RD changed-file analysis and QA regression planning when codegraph affected output is unavailable.', 'Codegraph Impact Analysis', 'Codegraph 影响面分析', 'Analyzes likely impact for changed files so RD and QA can focus planning and regression scope.', '分析变更文件的可能影响面，帮助 RD 与 QA 聚焦规划和回归范围。'),
     capability('codegraph.context-pack', 'codegraph', 'Codegraph Context Pack', 'cli', 'context-pack', ['engineer', 'qa', 'product'], 'medium', 'peaks-txt-context-capsule', 'Use Peaks TXT context capsules and role-skill handoffs when codegraph context output is unavailable.', 'Codegraph Context Pack', 'Codegraph 上下文包', 'Builds task-specific local context that Solo, RD, and TXT can use as supporting evidence.', '生成任务相关的本地上下文，作为 Solo、RD 与 TXT 的辅助证据。'),
-    capability('playwright-mcp.browser-validation', 'playwright-mcp', 'Playwright MCP Browser Validation', 'mcp', 'browser-validation', ['engineer', 'qa'], 'medium', 'manual-browser-test', 'Use local Playwright or manual browser verification.', 'Playwright Browser Validation', 'Playwright 浏览器验证', 'Validates UI flows through controlled browser automation.', '通过受控浏览器自动化验证 UI 流程。'),
+    capability('gstack-browse.headed-browser-validation', 'gstack-browse', 'gstack Browse Headed Browser Validation', 'cli', 'browser-validation', ['engineer', 'qa'], 'medium', 'blocked-browser-validation', 'Block browser validation until headed gstack/browse/dist/browse can open the actual launched app URL.', 'gstack Browse Validation', 'gstack 有头浏览器验证', 'Validates UI flows in a visible gstack browse session against the app URL advertised by the launched dev server.', '使用有头 gstack browse 会话验证由开发服务器实际输出 URL 对应的 UI 流程。'),
     capability('chrome-devtools-mcp.browser-debug', 'chrome-devtools-mcp', 'Chrome DevTools Browser Debug', 'mcp', 'browser-debug', ['engineer', 'qa'], 'medium', 'manual-devtools-inspection', 'Use browser screenshots, console logs, and network traces supplied by the user.', 'Chrome DevTools Debug', 'Chrome DevTools 调试', 'Inspects runtime UI, console, network, and performance behavior.', '检查运行时 UI、控制台、网络和性能行为。'),
     capability('figma-context-mcp.design-context', 'figma-context-mcp', 'Figma Design Context', 'mcp', 'design-context', ['designer', 'engineer'], 'medium', 'manual-design-input', 'Ask the user for screenshots, tokens, or exported design notes.', 'Figma Design Context', 'Figma 设计上下文', 'Reads design context for UI implementation planning.', '读取设计上下文以辅助 UI 实现规划。'),
     capability('searchcode-mcp.code-search', 'searchcode-mcp', 'SearchCode MCP', 'mcp', 'code-search', ['engineer'], 'medium', 'local-code-search', 'Use local Grep/Glob and ask before sending private code externally.', 'External Code Search', '外部代码搜索', 'Searches code examples or repositories outside the current workspace.', '搜索当前工作区外部的代码示例或仓库。'),

package/dist/src/services/recommendations/capability-seed-mappings.js

@@ -8,7 +8,7 @@ export const seedCapabilityLandingMappings = [
     mapping({ capabilityId: 'codegraph.context-pack', sourceId: 'codegraph', sourceGroup: 'access-repo', landingKind: 'skill', target: 'peaks-rd', skillName: 'peaks-rd', guidance: 'Dry-run reference only: peaks-rd may use peaks codegraph context --project <path> <task> to gather local evidence for RD analysis when execution is approved, without replacing standards dry-runs.' }),
     mapping({ capabilityId: 'codegraph.context-pack', sourceId: 'codegraph', sourceGroup: 'access-repo', landingKind: 'skill', target: 'peaks-solo', skillName: 'peaks-solo', guidance: 'Solo may attach local context packs or affected summaries before role handoff so RD, QA, and TXT share the same project evidence.' }),
     mapping({ capabilityId: 'codegraph.context-pack', sourceId: 'codegraph', sourceGroup: 'access-repo', landingKind: 'skill', target: 'peaks-txt', skillName: 'peaks-txt', guidance: 'TXT may summarize recorded codegraph context packs into handoffs while treating them as supporting evidence only.' }),
-    mapping({ capabilityId: 'playwright-mcp.browser-validation', sourceId: 'playwright-mcp', sourceGroup: 'access-repo', landingKind: 'skill', target: 'peaks-qa', skillName: 'peaks-qa', guidance: 'Use for browser and E2E validation after user-approved app targets are available.' }),
+    mapping({ capabilityId: 'gstack-browse.headed-browser-validation', sourceId: 'gstack-browse', sourceGroup: 'access-repo', landingKind: 'skill', target: 'peaks-qa', skillName: 'peaks-qa', guidance: 'Launch the app, capture its actual advertised URL, and validate only with headed gstack/browse/dist/browse; block instead of falling back to Playwright MCP or default ports.' }),
     mapping({ capabilityId: 'chrome-devtools-mcp.browser-debug', sourceId: 'chrome-devtools-mcp', sourceGroup: 'access-repo', landingKind: 'skill', target: 'peaks-ui', skillName: 'peaks-ui', guidance: 'Use for runtime UI, console, network, and performance inspection.' }),
     mapping({ capabilityId: 'context-mode.context-management', sourceId: 'context-mode', sourceGroup: 'access-repo', landingKind: 'skill', target: 'peaks-txt', skillName: 'peaks-txt', guidance: 'Use only for explicit context management; durable memory requires user opt-in.' }),
     mapping({ capabilityId: 'modelcontextprotocol-servers.collection', sourceId: 'modelcontextprotocol-servers', sourceGroup: 'access-repo', landingKind: 'catalog', target: 'future peaks mcp catalog', guidance: 'Treat as an unscanned MCP collection; do not auto-install unknown servers.' }),

package/dist/src/services/recommendations/capability-seed-sources.js

@@ -2,7 +2,7 @@ export const seedCapabilitySources = [
     { sourceId: 'ruflo-access-repo', sourceType: 'repo', sourceGroup: 'access-repo', title: 'Ruflo', url: 'https://github.com/ruvnet/ruflo', trustSignals: { notes: ['Workflow orchestration reference; do not execute or install from the capability map.'] }, discoveryStatus: 'unscanned', items: ['ruflo-access-repo.workflow-reference'] },
     { sourceId: 'context7', sourceType: 'repo', sourceGroup: 'access-repo', title: 'Context7', url: 'https://github.com/upstash/context7', trustSignals: { sourceReputation: 'commonly used docs lookup MCP capability' }, discoveryStatus: 'indexed', items: ['context7.docs-lookup'] },
     { sourceId: 'codegraph', sourceType: 'repo', sourceGroup: 'access-repo', title: 'codegraph', url: 'https://github.com/colbymchenry/codegraph', trustSignals: { notes: ['Use through peaks codegraph only; do not run upstream install flows from the capability map.', 'Local project indexing can create .codegraph artifacts; do not commit generated databases unless explicitly requested.'] }, discoveryStatus: 'indexed', items: ['codegraph.project-indexing', 'codegraph.semantic-query', 'codegraph.impact-analysis', 'codegraph.context-pack'] },
-    { sourceId: 'playwright-mcp', sourceType: 'repo', sourceGroup: 'access-repo', title: 'Playwright MCP', url: 'https://github.com/microsoft/playwright-mcp', trustSignals: { sourceReputation: 'Microsoft browser automation MCP server' }, discoveryStatus: 'indexed', items: ['playwright-mcp.browser-validation'] },
+    { sourceId: 'gstack-browse', sourceType: 'repo', sourceGroup: 'access-repo', title: 'gstack browse', url: 'https://github.com/garrytan/gstack', trustSignals: { notes: ['Use headed gstack/browse/dist/browse only after launching the app and discovering its actual advertised URL. Do not substitute Playwright MCP.'] }, discoveryStatus: 'indexed', items: ['gstack-browse.headed-browser-validation'] },
     { sourceId: 'chrome-devtools-mcp', sourceType: 'website', sourceGroup: 'access-repo', title: 'Chrome DevTools MCP', url: 'https://www.pulsemcp.com/servers/chrome-devtools', trustSignals: { notes: ['Browser inspection and performance debugging capability.'] }, discoveryStatus: 'indexed', items: ['chrome-devtools-mcp.browser-debug'] },
     { sourceId: 'context-mode', sourceType: 'repo', sourceGroup: 'access-repo', title: 'Context Mode', url: 'https://github.com/mksglu/context-mode', trustSignals: { notes: ['Context and memory management reference.'] }, discoveryStatus: 'indexed', items: ['context-mode.context-management'] },
     { sourceId: 'modelcontextprotocol-servers', sourceType: 'mcp-collection', sourceGroup: 'access-repo', title: 'Model Context Protocol Servers', url: 'https://github.com/modelcontextprotocol/servers', trustSignals: { sourceReputation: 'official MCP server collection' }, discoveryStatus: 'unscanned', items: ['modelcontextprotocol-servers.collection'] },

package/dist/src/services/shadcn/shadcn-service.d.ts

@@ -18,10 +18,6 @@ export type ShadcnExecutionResult = {
     stderr: string;
 };
 export type ShadcnProcessRunner = (invocation: ShadcnInvocation) => Promise<ShadcnExecutionResult>;
-declare function createShadcnEnvironment(sourceEnv?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 export declare function createShadcnInvocation(options: ShadcnInvocationOptions): ShadcnInvocation;
 export declare function executeShadcnInvocation(invocation: ShadcnInvocation, runner?: ShadcnProcessRunner): Promise<ShadcnExecutionResult>;
-export declare const testInternals: {
-    createShadcnEnvironment: typeof createShadcnEnvironment;
-};
 export {};

package/dist/src/services/shadcn/shadcn-service.js

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
-import { resolve } from 'node:path';
+import { win32 } from 'node:path';
 const SHADCN_PACKAGE_NAME = 'shadcn';
 const SHADCN_PACKAGE_VERSION = '4.7.0';
 const SHADCN_EXECUTABLE = process.execPath;
@@ -10,12 +10,15 @@ const SHADCN_PROCESS_TIMEOUT_MS = 600_000;
 const SHADCN_OUTPUT_LIMIT_BYTES = 10 * 1024 * 1024;
 const POSITIONAL_ARGUMENT_PREFIX = '-';
 const PRESERVED_ENV_KEYS = ['PATH', 'Path', 'HOME', 'USERPROFILE', 'APPDATA', 'LOCALAPPDATA', 'TEMP', 'TMP', 'SystemRoot', 'WINDIR'];
-function resolveShadcnBinaryPath() {
-    const require = createRequire(import.meta.url);
-    const binaryPath = require.resolve('shadcn');
+function assertShadcnBinaryExists(binaryPath) {
     if (!existsSync(binaryPath)) {
         throw new Error('Unable to resolve local shadcn binary from shadcn');
     }
+}
+function resolveShadcnBinaryPath() {
+    const require = createRequire(import.meta.url);
+    const binaryPath = require.resolve('shadcn');
+    assertShadcnBinaryExists(binaryPath);
     return binaryPath;
 }
 function assertShadcnArgs(args) {
@@ -43,24 +46,36 @@ function assertOutputLimit(currentSize, chunkSize) {
     }
     return nextSize;
 }
-function terminateShadcnProcess(childProcess) {
+function getWindowsTaskkillPath(fileExists = existsSync) {
+    const candidates = [
+        win32.join('C:\\Windows', 'System32', 'taskkill.exe'),
+        win32.join('C:\\WINNT', 'System32', 'taskkill.exe')
+    ];
+    return candidates.find((candidate) => fileExists(candidate)) ?? null;
+}
+function terminateShadcnProcess(childProcess, platform = process.platform, killProcess = process.kill, spawnProcess = spawn, taskkillPath = getWindowsTaskkillPath()) {
     if (childProcess.pid === undefined) {
         childProcess.kill();
         return;
     }
-    if (process.platform === 'win32') {
-        const taskkillPath = process.env.SystemRoot ? resolve(process.env.SystemRoot, 'System32', 'taskkill.exe') : 'taskkill.exe';
-        spawn(taskkillPath, ['/pid', String(childProcess.pid), '/T', '/F'], { shell: false, stdio: 'ignore' });
+    if (platform === 'win32') {
+        if (!taskkillPath) {
+            childProcess.kill();
+            return;
+        }
+        const killerProcess = spawnProcess(taskkillPath, ['/pid', String(childProcess.pid), '/T', '/F'], { shell: false, stdio: 'ignore' });
+        killerProcess.on('error', () => childProcess.kill());
+        killerProcess.unref();
         return;
     }
     try {
-        process.kill(-childProcess.pid, 'SIGTERM');
+        killProcess(-childProcess.pid, 'SIGTERM');
     }
     catch {
         childProcess.kill('SIGTERM');
     }
 }
-function defaultShadcnProcessRunner(invocation) {
+function runShadcnProcess(invocation, timeoutMs = SHADCN_PROCESS_TIMEOUT_MS) {
     return new Promise((resolveResult, reject) => {
         const childProcess = spawn(invocation.executable, invocation.args, {
             cwd: invocation.cwd,
@@ -70,8 +85,8 @@ function defaultShadcnProcessRunner(invocation) {
         });
         const timeout = setTimeout(() => {
             terminateShadcnProcess(childProcess);
-            reject(new Error(`shadcn process timed out after ${SHADCN_PROCESS_TIMEOUT_MS}ms`));
-        }, SHADCN_PROCESS_TIMEOUT_MS);
+            reject(new Error(`shadcn process timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
         const stdoutChunks = [];
         const stderrChunks = [];
         let stdoutSize = 0;
@@ -110,6 +125,9 @@ function defaultShadcnProcessRunner(invocation) {
         });
     });
 }
+function defaultShadcnProcessRunner(invocation) {
+    return runShadcnProcess(invocation);
+}
 export function createShadcnInvocation(options) {
     assertShadcnArgs(options.args);
     return {
@@ -123,6 +141,3 @@ export function createShadcnInvocation(options) {
 export async function executeShadcnInvocation(invocation, runner = defaultShadcnProcessRunner) {
     return runner(invocation);
 }
-export const testInternals = {
-    createShadcnEnvironment
-};

package/dist/src/shared/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "1.0.11";
+export declare const CLI_VERSION = "1.0.12";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.0.11";
+export const CLI_VERSION = "1.0.12";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.0.11",
+  "version": "1.0.12",
   "description": "Peaks CLI and short skill family for Claude Code automation.",
   "author": "SquabbyZ",
   "license": "MIT",
@@ -21,6 +21,7 @@
     "scripts/sync-version.mjs",
     "scripts/install-skills.mjs",
     "scripts/watch.mjs",
+    "scripts/strip-internal-exports.mjs",
     "skills/**",
     "!skills/**/test-prompts.json",
     "!skills/**/.DS_Store",
@@ -28,7 +29,7 @@
     "schemas/*.json"
   ],
   "scripts": {
-    "build": "node ./scripts/sync-version.mjs && node ./scripts/clean-dist.mjs && tsc -p tsconfig.json",
+    "build": "node ./scripts/sync-version.mjs && node ./scripts/clean-dist.mjs && tsc -p tsconfig.json && node ./scripts/strip-internal-exports.mjs",
     "prepack": "npm run build",
     "postinstall": "node ./scripts/install-skills.mjs",
     "dev": "tsx src/cli/index.ts",

package/scripts/strip-internal-exports.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const distSrcRoot = join(packageRoot, 'dist', 'src');
+const internalExportPattern = /\/\*\* @internal \*\/\r?\nexport const testInternals = \{[\s\S]*?\r?\n\};\r?\n?/g;
+
+function getJavaScriptFiles(directory) {
+  return readdirSync(directory).flatMap((entry) => {
+    const path = join(directory, entry);
+    const stats = statSync(path);
+    if (stats.isDirectory()) {
+      return getJavaScriptFiles(path);
+    }
+    return stats.isFile() && path.endsWith('.js') ? [path] : [];
+  });
+}
+
+for (const filePath of getJavaScriptFiles(distSrcRoot)) {
+  const source = readFileSync(filePath, 'utf8');
+  if (!source.includes('testInternals')) {
+    continue;
+  }
+
+  const strippedSource = source.replace(internalExportPattern, '');
+  if (strippedSource === source || strippedSource.includes('testInternals')) {
+    throw new Error(`Failed to strip internal test export from ${filePath}`);
+  }
+  writeFileSync(filePath, strippedSource, 'utf8');
+}

package/skills/peaks-qa/SKILL.md

@@ -55,17 +55,17 @@ QA cannot pass a change until the report contains evidence for every applicable
 
 1. **Unit tests** — run the project test command or a focused test command that covers new/changed code. For legacy projects below the target coverage, require coverage for the new or changed code rather than failing on pre-existing uncovered code.
 2. **API validation** — when the change touches API contracts, data loading, request handling, auth, or integrations, exercise the relevant API path and record request/response evidence or a justified local substitute.
-3. **Frontend browser validation** — when the repository has a frontend or the change affects UI, launch the app and use headed `gstack/browse/dist/browse` for real browser end-to-end validation. Verify the visible browser with `browse status`, screenshot evidence, or user confirmation. If login, CAPTCHA, SSO, or MFA appears, wait for the user to complete login and explicitly confirm completion before continuing. Capture sanitized route/actions, sanitized screenshots or observations, sanitized console/network failures, and acceptance result.
+3. **Frontend browser validation** — when the repository has a frontend or the change affects UI, launch the app with the project's actual dev/preview command, capture the actual advertised reachable URL from server output/config/user input, and use headed `gstack/browse/dist/browse` against that exact URL for real browser end-to-end validation. Never assume framework default ports such as 3000, 5173, 4200, 4321, or 8080. Verify the visible browser with `browse status`, screenshot evidence, or user confirmation. If login, CAPTCHA, SSO, or MFA appears, wait for the user to complete login and explicitly confirm completion before continuing. Capture sanitized actual URL origin/path, route/actions, sanitized screenshots or observations, sanitized console/network failures, and acceptance result.
 4. **Browser-error feedback loop** — if `gstack/browse/dist/browse` shows a page error, console exception, broken network request, hydration/render failure, or visible regression, return the work to RD/development with the exact evidence. Do not pass QA until the fixed build is retested in the browser.
 5. **Security check** — run security review for the changed surface and dependency/config changes. Record findings, fixes, and unresolved risks.
 6. **Performance check** — run the project’s available performance check, build-size check, Lighthouse-equivalent check, or browser performance inspection appropriate to the change. Record baseline/after numbers when available.
 7. **Validation report** — write or link a report containing scope, environment, commands, sanitized browser evidence, security/performance results, pass/fail summary, residual risks, and next action.
 
-If headed `gstack/browse/dist/browse` is unavailable, mark the gate blocked with the missing capability. Screenshots, logs, manual steps, or other tools must not substitute for the mandatory frontend browser gate. Do not silently downgrade frontend validation to API-only testing.
+If headed `gstack/browse/dist/browse` is unavailable, unstable, closes unexpectedly, or cannot verify a visible browser, mark the gate blocked with the missing/unstable capability. Screenshots, logs, manual steps, Playwright MCP, or other tools must not substitute for the mandatory frontend browser gate. Do not silently downgrade frontend validation to API-only testing.
 
 ## Local intermediate artifacts
 
-QA reports, sanitized browser evidence, logs, matrices, and validation summaries should be written to `.peaks/<session-id>/qa/` by default, or to the Peaks CLI-provided local artifact workspace. Do not store login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs containing PII or SSO/MFA material. Do not default to git-backed storage or external artifact sync unless the user or active profile explicitly authorizes it.
+QA reports, sanitized browser evidence, logs, matrices, and validation summaries should be written under the Peaks CLI-provided `artifactWorkspacePath` at `.peaks/<session-id>/qa/` by default. Do not store login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs containing PII or SSO/MFA material. Do not default to target-repo `.peaks` storage, git-backed storage, or external artifact sync unless the CLI returned that location or the user/active profile explicitly authorizes it.
 
 ## Compact handoff
 

package/skills/peaks-qa/references/artifact-contracts.md

@@ -2,6 +2,6 @@
 
 This reference documents artifact-contracts.md for peaks-qa.
 
-Default local artifact path: `.peaks/<session-id>/qa/`.
+Default runtime artifact path: `<artifactWorkspacePath>/.peaks/<session-id>/qa/`, where `artifactWorkspacePath` comes from `peaks config workspace ensure --path <project> --json`.
 
-QA artifacts should include regression matrices, API evidence, headed `gstack/browse/dist/browse` E2E evidence, sanitized console/network observations, sanitized screenshots or observations, security/performance checks, validation report, residual risks, and blocked/final handoff capsules. Do not retain login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs containing PII or SSO/MFA material. Keep artifacts local by default. Do not commit or sync them unless explicitly authorized.
+QA artifacts should include regression matrices, API evidence, headed `gstack/browse/dist/browse` E2E evidence against the actual launched app URL, sanitized console/network observations, sanitized screenshots or observations, security/performance checks, validation report, residual risks, and blocked/final handoff capsules. Do not retain login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs containing PII or SSO/MFA material. Keep runtime artifacts in the configured Peaks artifact workspace by default. Do not commit or sync them unless explicitly authorized.

package/skills/peaks-qa/references/regression-gates.md

@@ -9,7 +9,7 @@ QA must be involved before refactor implementation.
 - baseline report;
 - acceptance checks;
 - API validation evidence when API behavior is in scope;
-- headed `gstack/browse/dist/browse` browser E2E evidence when a frontend exists or UI is in scope, with mandatory visible-browser confirmation;
+- headed `gstack/browse/dist/browse` browser E2E evidence when a frontend exists or UI is in scope, using the actual URL advertised by the launched app rather than default framework ports, with mandatory visible-browser confirmation;
 - security check evidence;
 - performance check evidence;
 - validation report;
@@ -21,4 +21,4 @@ UT coverage below 95%, missing coverage, or unverifiable coverage blocks refacto
 
 ## Frontend failure rule
 
-If browser validation shows page errors, console exceptions, failed critical network requests, or visible regressions, QA returns the change to RD with evidence and reruns the browser path after the fix.
+If browser validation shows page errors, console exceptions, failed critical network requests, or visible regressions, QA returns the change to RD with evidence and reruns the browser path after the fix. If headed gstack browse is unavailable, unstable, closes unexpectedly, or cannot confirm a visible browser, QA blocks instead of falling back to Playwright MCP, screenshots-only evidence, or default-port probing.

package/skills/peaks-rd/SKILL.md

@@ -65,7 +65,7 @@ RD cannot mark a development slice complete until all of these are true:
 1. OpenSpec change artifacts exist and are linked for non-trivial work when the target repo already has `openspec/`, or the user has approved adding it;
 2. unit tests covering the new or changed behavior have been added or updated and run successfully;
 3. if the repository is legacy and total UT coverage is below the project target, do not block on historical coverage, but require coverage evidence for newly added or changed code;
-4. for frontend or UI-affecting slices, RD self-test has launched the app and used headed `gstack/browse/dist/browse` for real browser end-to-end validation with visible-browser confirmation, sanitized route/actions, sanitized console/network observations, and acceptance result recorded; if login, CAPTCHA, SSO, or MFA appears, wait for the user to complete login and explicitly confirm completion before continuing;
+4. for frontend or UI-affecting slices, RD self-test has launched the app with the project's actual dev/preview command, captured the actual advertised reachable URL from server output/config/user input, and used headed `gstack/browse/dist/browse` against that exact URL for real browser end-to-end validation with visible-browser confirmation, sanitized route/actions, sanitized console/network observations, and acceptance result recorded; never assume framework default ports such as 3000, 5173, 4200, 4321, or 8080; if `gstack/browse/dist/browse` is unavailable, unstable, closes unexpectedly, or cannot verify a visible browser, mark RD self-test blocked instead of falling back to Playwright MCP, screenshots-only evidence, or default-port probing; if login, CAPTCHA, SSO, or MFA appears, wait for the user to complete login and explicitly confirm completion before continuing;
 5. code review has been performed with findings recorded and CRITICAL/HIGH issues fixed before progression; unresolved CRITICAL/HIGH findings only allow a blocked handoff;
 6. security review has been performed for the changed surface, with CRITICAL/HIGH issues fixed before progression and particular attention to user input, file system access, external calls, auth, secrets, and dependency changes;
 7. the post-check dry-run has passed and is linked in the handoff.
@@ -84,7 +84,7 @@ If a request is refactor, cleanup, architecture adjustment, module split, or tec
 6. call or consume peaks-prd and peaks-qa artifacts even in direct RD mode;
 7. require strict slice spec before each slice;
 8. require 100% acceptance for the slice;
-9. require code changes and intermediate artifacts to be traceable in local `.peaks/<session-id>/` storage before continuing; commit or sync artifacts only when explicitly authorized.
+9. require code changes and intermediate artifacts to be traceable under the Peaks CLI-provided `artifactWorkspacePath` at `.peaks/<session-id>/` before continuing; commit or sync artifacts only when explicitly authorized.
 
 ## OpenSpec usage
 
@@ -110,7 +110,7 @@ Application projects generated through this skill must not contain JavaScript so
 
 ## Artifact and standards output
 
-When project identification or scanning produces reports, matrices, maps, plans, or validation files, write them under the configured Peaks artifact workspace. By default, use local non-git storage at `.peaks/<session-id>/rd/` in the target project or the Peaks CLI-provided local workspace. If the artifact workspace is unknown, create or request `.peaks/<session-id>/` before writing generated outputs. Use one session directory consistently so generated outputs stay grouped.
+When project identification or scanning produces reports, matrices, maps, plans, or validation files, write them under the configured Peaks artifact workspace returned by `peaks config workspace ensure --path <project> --json`. By default, use local non-git storage at `<artifactWorkspacePath>/.peaks/<session-id>/rd/`. If the artifact workspace is unknown, run/request `peaks config workspace ensure` before writing generated outputs. Use one session directory consistently so generated outputs stay grouped.
 
 Do not default to a git-backed artifact repository, external artifact sync, or automatic commits for intermediate artifacts. Git inclusion or sync requires explicit user confirmation or an active profile that clearly authorizes it. Browser evidence must be sanitized before retention: do not store login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs containing PII or SSO/MFA material.
 

package/skills/peaks-rd/references/artifact-contracts.md

@@ -2,6 +2,6 @@
 
 This reference documents artifact-contracts.md for peaks-rd.
 
-Default local artifact path: `.peaks/<session-id>/rd/`.
+Default runtime artifact path: `<artifactWorkspacePath>/.peaks/<session-id>/rd/`, where `artifactWorkspacePath` comes from `peaks config workspace ensure --path <project> --json`.
 
-RD artifacts should include scan reports, OpenSpec path notes, slice specs, task graphs, coverage evidence, code-review and security-review reports, post-check dry-run output, and handoff capsules. Keep artifacts local by default. Do not commit or sync them unless explicitly authorized.
+RD artifacts should include scan reports, OpenSpec path notes, slice specs, task graphs, coverage evidence, code-review and security-review reports, post-check dry-run output, and handoff capsules. Keep runtime artifacts in the configured Peaks artifact workspace by default. Do not mix target-repo `.peaks` with the CLI-returned artifact workspace, and do not commit or sync artifacts unless explicitly authorized.

package/skills/peaks-rd/references/refactor-workflow.md

@@ -19,7 +19,7 @@
 - Each implemented slice must pass unit tests, code review, and security review before RD dry-run.
 - The post-check dry-run runs after tests, CR, and security review, not before them.
 - Each slice must pass 100% acceptance.
-- Code changes and sanitized intermediate artifacts must be traceable in local `.peaks/<session-id>/` storage before the next slice; commit or sync sanitized artifacts only when explicitly authorized. Browser evidence must not retain login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs containing PII or SSO/MFA material.
+- Code changes and sanitized intermediate artifacts must be traceable under the Peaks CLI-provided `artifactWorkspacePath` at `.peaks/<session-id>/` before the next slice; commit or sync sanitized artifacts only when explicitly authorized. Browser evidence must not retain login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs containing PII or SSO/MFA material.
 
 ## Required artifacts
 
@@ -36,4 +36,4 @@
 - `security-review-report.md`
 - `post-check-dry-run.md`
 - `validation-report.md`
-- `retention-boundary.md` documenting local `.peaks/<session-id>/` traceability, browser-evidence sanitization, and any explicitly authorized commit/sync requirement
+- `retention-boundary.md` documenting `artifactWorkspacePath/.peaks/<session-id>/` traceability, browser-evidence sanitization, and any explicitly authorized commit/sync requirement

package/skills/peaks-solo/SKILL.md

@@ -40,13 +40,15 @@ Use gstack as a concrete orchestration reference for the full `Think → Plan
 - map `/retro` to Peaks TXT final context and reusable lessons;
 - preserve Peaks confirmation gates, artifact workspace boundaries, and role separation instead of delegating orchestration to gstack commands.
 
-For frontend workflows, Peaks Solo must ensure RD self-test and QA validation use headed `gstack/browse/dist/browse` for real browser end-to-end validation. A visible browser opening is mandatory. If login, CAPTCHA, SSO, or MFA appears, wait for the user to complete login and explicitly confirm completion before continuing. If browser validation reports page, console, network, render, or visible UI errors, route the workflow back to RD for fixes before QA can pass.
+For frontend workflows, Peaks Solo must ensure RD self-test and QA validation launch the app with the project's actual dev/preview command, capture the actual advertised reachable URL from server output/config/user input, and use headed `gstack/browse/dist/browse` against that exact URL for real browser end-to-end validation. Never assume framework default ports such as 3000, 5173, 4200, 4321, or 8080. A visible browser opening is mandatory. If `gstack/browse/dist/browse` is unavailable, unstable, closes unexpectedly, or cannot verify a visible browser, mark the browser gate blocked instead of falling back to Playwright MCP, screenshots-only evidence, or default-port probing. If login, CAPTCHA, SSO, or MFA appears, wait for the user to complete login and explicitly confirm completion before continuing. If browser validation reports page, console, network, render, or visible UI errors, route the workflow back to RD for fixes before QA can pass.
 
 Browser validation artifacts must be sanitized before retention: do not store login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs containing PII or SSO/MFA material in `.peaks` artifacts, and do not commit or sync sensitive browser evidence.
 
 ## Local intermediate artifact workspace
 
-Peaks Solo should establish or discover a local `.peaks/<session-id>/` workspace before role handoffs. Store PRD/RD/UI/QA/SC/TXT intermediate artifacts there by default, with role subdirectories such as `prd/`, `rd/`, `ui/`, `qa/`, `sc/`, and `txt/`.
+Before role handoffs, Peaks Solo must run or require `peaks config workspace ensure --path <project> --json` for the target project. This command must ensure the user `~/.peaks/config.json` contains a workspace for the current project and switch `currentWorkspace` to that workspace. Treat the returned `artifactWorkspacePath` as the single runtime artifact root for the workflow.
+
+Store PRD/RD/UI/QA/SC/TXT intermediate artifacts under `<artifactWorkspacePath>/.peaks/<session-id>/` by default, with role subdirectories such as `prd/`, `rd/`, `ui/`, `qa/`, `sc/`, and `txt/`. Do not mix target-repo `.peaks/<session-id>/` with the configured artifact workspace unless the CLI explicitly returns a project-local artifact root. Record workspace id, project root, artifactWorkspacePath, session id, and any OpenSpec paths in every role handoff so later stages read and write the same directories.
 
 Do not default to a git-backed local artifact repository, external artifact sync, or automatic commits for intermediate artifacts. Only include sanitized `.peaks` artifacts in git, sync them elsewhere, or create external artifact repositories after explicit user confirmation or an active profile that clearly authorizes it.
 
@@ -128,7 +130,7 @@ It must enforce the shared refactor red lines:
 4. split broad refactors into minimal functional slices;
 5. require strict verifiable specs before each slice;
 6. require 100% acceptance for each slice;
-7. require code changes and sanitized intermediate artifacts to be traceable in local `.peaks/<session-id>/` storage before the next slice; commit or sync sanitized artifacts only when explicitly authorized.
+7. require code changes and sanitized intermediate artifacts to be traceable under the Peaks CLI-provided `artifactWorkspacePath` at `.peaks/<session-id>/` before the next slice; commit or sync sanitized artifacts only when explicitly authorized.
 
 ## Completion handoff
 
@@ -140,7 +142,7 @@ Use Peaks TXT for the final, blocked, or interrupted handoff capsule. Keep that
 
 Codegraph is an optional project-analysis enhancement for role handoff. Solo may coordinate `peaks codegraph context --project <path> "<task>"` or `peaks codegraph affected --project <path> <changed-files...> --json` before assigning work to RD, QA, or TXT when shared project evidence would make the handoff narrower.
 
-Record useful output in the local Peaks artifact workspace, such as `.peaks/<session-id>/rd/codegraph-context.md` or `.peaks/<session-id>/rd/codegraph-affected.json`. Treat codegraph output as untrusted supporting evidence. Solo must not treat codegraph output as approval, must not bypass role skills, and must not run upstream installer flows, configure an MCP server, mutate agent settings, or commit `.codegraph/` artifacts.
+Record useful output in the local Peaks artifact workspace, such as `<artifactWorkspacePath>/.peaks/<session-id>/rd/codegraph-context.md` or `<artifactWorkspacePath>/.peaks/<session-id>/rd/codegraph-affected.json`. Treat codegraph output as untrusted supporting evidence. Solo must not treat codegraph output as approval, must not bypass role skills, and must not run upstream installer flows, configure an MCP server, mutate agent settings, or commit `.codegraph/` artifacts.
 
 ## Optional capabilities
 

package/skills/peaks-solo/references/artifact-contracts.md

@@ -2,6 +2,6 @@
 
 This reference documents artifact-contracts.md for peaks-solo.
 
-Default local artifact root: `.peaks/<session-id>/` with role subdirectories `prd/`, `rd/`, `ui/`, `qa/`, `sc/`, and `txt/`.
+Default runtime artifact root: `<artifactWorkspacePath>/.peaks/<session-id>/`, where `artifactWorkspacePath` comes from `peaks config workspace ensure --path <project> --json`, with role subdirectories `prd/`, `rd/`, `ui/`, `qa/`, `sc/`, and `txt/`.
 
-Solo coordinates artifact paths and handoff completeness. Keep artifacts local by default. Do not commit, sync, or move them to a git-backed artifact repository unless explicitly authorized.
+Solo coordinates artifact paths and handoff completeness. Keep runtime artifacts in the configured Peaks artifact workspace by default. Do not commit, sync, or move them to a git-backed artifact repository unless explicitly authorized.

package/skills/peaks-solo/references/refactor-mode.md

@@ -15,9 +15,9 @@
 9. Execute one minimal functional slice at a time.
 10. After every RD slice, coordinate `peaks-qa`; if QA reports any failed, blocked, missing, or unverified item, return the report to RD for repair and repeat QA.
 11. Require 100% acceptance for the slice before completion or the next slice.
-12. Coordinate `peaks-sc` for local artifact retention and the `.peaks/<session-id>/sc/retention-boundary.md` boundary.
+12. Coordinate `peaks-sc` for local artifact retention and the `<artifactWorkspacePath>/.peaks/<session-id>/sc/retention-boundary.md` boundary.
 13. Exclude login URLs, cookies, headers, tokens, storage state, browser traces, and PII/SSO/MFA screenshots or logs from retained artifacts.
-14. Refuse the next slice until code changes and sanitized intermediate artifacts are traceable in local `.peaks/<session-id>/` storage; commit or sync only after explicit user or profile authorization.
+14. Refuse the next slice until code changes and sanitized intermediate artifacts are traceable under the Peaks CLI-provided `artifactWorkspacePath` at `.peaks/<session-id>/`; commit or sync only after explicit user or profile authorization.
 
 ## Runtime resources
 

package/skills/peaks-solo/references/workflow.md

@@ -21,7 +21,7 @@ A code workflow is not complete until Solo has linked or summarized:
 6. security-review evidence;
 7. RD post-check dry-run evidence;
 8. QA API validation when applicable;
-9. sanitized QA headed `gstack/browse/dist/browse` browser E2E evidence for frontend projects, with mandatory visible-browser confirmation and without login URLs, cookies, headers, tokens, storage state, browser traces, or PII/SSO/MFA screenshots/logs;
+9. sanitized QA headed `gstack/browse/dist/browse` browser E2E evidence for frontend projects, using the actual URL advertised by the launched app rather than guessed default ports, with mandatory visible-browser confirmation and without login URLs, cookies, headers, tokens, storage state, browser traces, or PII/SSO/MFA screenshots/logs;
 10. QA security, performance, and validation report evidence;
 11. RD repair evidence for every failed, blocked, missing, or unverified QA item;
 12. final QA report showing all acceptance items passed, or a blocked TXT handoff;

package/skills/peaks-ui/SKILL.md

@@ -27,7 +27,7 @@ Use gstack as a concrete design-review workflow reference for the `Plan → Revi
 - map browser walkthrough concepts to UI regression seeds when runtime validation is approved;
 - keep accessibility, performance, and product-specific visual direction as Peaks UI acceptance inputs.
 
-For frontend work, especially full-auto mode, use headed `gstack/browse/dist/browse` to inspect the running page or prototype before accepting the UI direction. Verify that a visible browser actually opened. If login, CAPTCHA, SSO, or MFA appears, wait for the user to complete login and explicitly confirm completion before continuing. Capture only sanitized visible regressions, weak hierarchy, generic template patterns, console errors, and interaction problems as UI feedback that should return to design/RD before handing off to QA; do not retain login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs containing PII or SSO/MFA material.
+For frontend work, especially full-auto mode, launch the app with the project's actual dev/preview command, capture the actual advertised reachable URL from server output/config/user input, and use headed `gstack/browse/dist/browse` against that exact URL to inspect the running page or prototype before accepting the UI direction. Never assume framework default ports such as 3000, 5173, 4200, 4321, or 8080. Verify that a visible browser actually opened. If `gstack/browse/dist/browse` is unavailable, unstable, closes unexpectedly, or cannot verify a visible browser, mark UI browser review blocked instead of falling back to Playwright MCP, screenshots-only evidence, or default-port probing. If login, CAPTCHA, SSO, or MFA appears, wait for the user to complete login and explicitly confirm completion before continuing. Capture only sanitized visible regressions, weak hierarchy, generic template patterns, console errors, and interaction problems as UI feedback that should return to design/RD before handing off to QA; do not retain login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs containing PII or SSO/MFA material.
 
 ## Performance-safe motion references
 
@@ -58,7 +58,7 @@ When Peaks UI is used in full-auto frontend design, default to the curated taste
 5. define design dials before generating UI: design variance, motion intensity, visual density, typography pair, palette, interaction feel, motion budget, and reduced-motion behavior;
 6. reject centered stock heroes, default card grids, unmodified shadcn/library defaults, AI purple-blue gradients, generic three-card feature rows, and safe gray-on-white pages without a point of view;
 7. require loading, empty, error, hover, focus, active, responsive, and reduced-motion states for meaningful surfaces;
-8. browser-check the result with headed `gstack/browse/dist/browse`, wait for explicit user confirmation after any login challenge, and iterate until the UI looks intentional, memorable, performant, and product-specific.
+8. browser-check the result by launching the app, using the actual advertised URL with headed `gstack/browse/dist/browse`, waiting for explicit user confirmation after any login challenge, and iterating until the UI looks intentional, memorable, performant, and product-specific.
 
 Full-auto Peaks UI output must include a short taste report: visual direction, references used, rejected generic patterns, motion budget, reduced-motion behavior, browser observations, performance evidence, remaining design risks, and the next visual iteration if the page is not yet good enough.
 

package/skills/peaks-ui/references/workflow.md

@@ -13,7 +13,7 @@ Use this path before generating or accepting frontend UI:
 5. Define a motion budget: allowed animated properties, max intensity, reduced-motion behavior, lazy-loading expectations, and performance evidence required.
 6. Reject generic AI UI tells: centered stock hero, uniform card grids, default shadcn/library styling, purple-blue gradients, three equal feature cards, generic placeholder copy, and static-only happy states.
 7. Require meaningful loading, empty, error, hover, focus, active, responsive, and reduced-motion states.
-8. Use headed `gstack/browse/dist/browse` on the running page or prototype to inspect real browser output; visible browser confirmation is mandatory, and login/CAPTCHA/SSO/MFA requires waiting for explicit user confirmation before continuing.
+8. Launch the app with the project command, capture the actual advertised URL from server output/config/user input, and use headed `gstack/browse/dist/browse` on that URL to inspect real browser output; visible browser confirmation is mandatory, default framework ports must not be guessed, gstack instability blocks the browser gate instead of falling back to Playwright MCP, and login/CAPTCHA/SSO/MFA requires waiting for explicit user confirmation before continuing.
 9. If the browser view looks generic, visually weak, broken, inaccessible, slow, janky, or has console/runtime errors, return to design/RD and iterate before handing off to QA.
 
 ## Outputs