peaks-cli 1.0.3 → 1.0.5

package/dist/src/cli/commands/codegraph-commands.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerCodegraphCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,99 @@
+import { InvalidArgumentError } from 'commander';
+import { createCodegraphInvocation, executeCodegraphInvocation } from '../../services/codegraph/codegraph-service.js';
+import { fail } from '../../shared/result.js';
+import { getErrorMessage, printResult, redactSensitiveErrorMessage } from '../cli-helpers.js';
+function addPeaksJsonOption(command) {
+    return command.option('--peaks-json', 'print Peaks error envelope as machine-readable JSON');
+}
+function addProjectOption(command) {
+    return addPeaksJsonOption(command.requiredOption('--project <path>', 'target project root'));
+}
+function parsePositiveInteger(value) {
+    if (!/^\d+$/.test(value)) {
+        throw new InvalidArgumentError('must be a positive integer');
+    }
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < 1) {
+        throw new InvalidArgumentError('must be a positive integer');
+    }
+    return parsed;
+}
+function printCodegraphFailure(io, command, error, asJson, exitCode = 1) {
+    printResult(io, fail(command, 'CODEGRAPH_COMMAND_FAILED', redactSensitiveErrorMessage(getErrorMessage(error)), {}, ['Check the codegraph command options and project path before retrying']), asJson);
+    process.exitCode = exitCode;
+}
+async function runCodegraphCommand(io, command, options, asJson) {
+    try {
+        const invocation = createCodegraphInvocation(options);
+        const result = await executeCodegraphInvocation(invocation);
+        if (result.exitCode !== null && result.exitCode !== 0 && asJson === true) {
+            printCodegraphFailure(io, command, new Error(result.stderr || result.stdout || `codegraph exited with code ${result.exitCode}`), true, result.exitCode);
+            return;
+        }
+        const didFail = result.exitCode !== null && result.exitCode !== 0;
+        if (result.stdout.length > 0) {
+            io.stdout((didFail ? redactSensitiveErrorMessage(result.stdout) : result.stdout).trimEnd());
+        }
+        if (result.stderr.length > 0) {
+            io.stderr((didFail ? redactSensitiveErrorMessage(result.stderr) : result.stderr).trimEnd());
+        }
+        if (didFail) {
+            process.exitCode = result.exitCode;
+        }
+    }
+    catch (error) {
+        printCodegraphFailure(io, command, error, asJson);
+    }
+}
+export function registerCodegraphCommands(program, io) {
+    const codegraph = program.command('codegraph').description('Run upstream codegraph commands through the Peaks launcher');
+    addProjectOption(codegraph.command('status').description('Show codegraph status')).action((options) => runCodegraphCommand(io, 'codegraph.status', { subcommand: 'status', project: options.project }, options.peaksJson));
+    addProjectOption(codegraph.command('init').description('Initialize codegraph for a project').option('--yes', 'answer yes to upstream prompts')).action((options) => runCodegraphCommand(io, 'codegraph.init', {
+        subcommand: 'init',
+        project: options.project,
+        ...(options.yes === true ? { yes: true } : {})
+    }, options.peaksJson));
+    addProjectOption(codegraph
+        .command('index')
+        .description('Index a project with codegraph')
+        .option('--force', 'force reindexing')
+        .option('--quiet', 'reduce upstream output')).action((options) => runCodegraphCommand(io, 'codegraph.index', {
+        subcommand: 'index',
+        project: options.project,
+        ...(options.force === true ? { force: true } : {}),
+        ...(options.quiet === true ? { quiet: true } : {})
+    }, options.peaksJson));
+    addProjectOption(codegraph
+        .command('query')
+        .description('Query codegraph')
+        .argument('<search>', 'search text')
+        .option('--json', 'forward JSON output flag to upstream codegraph')
+        .option('--limit <n>', 'maximum result count', parsePositiveInteger)).action((search, options) => runCodegraphCommand(io, 'codegraph.query', {
+        subcommand: 'query',
+        project: options.project,
+        search,
+        ...(options.json === true ? { json: true } : {}),
+        ...(options.limit !== undefined ? { limit: options.limit } : {})
+    }, options.peaksJson));
+    addProjectOption(codegraph
+        .command('files')
+        .description('List codegraph files')
+        .option('--json', 'forward JSON output flag to upstream codegraph')
+        .option('--max-depth <n>', 'maximum traversal depth', parsePositiveInteger)).action((options) => runCodegraphCommand(io, 'codegraph.files', {
+        subcommand: 'files',
+        project: options.project,
+        ...(options.json === true ? { json: true } : {}),
+        ...(options.maxDepth !== undefined ? { maxDepth: options.maxDepth } : {})
+    }, options.peaksJson));
+    addProjectOption(codegraph.command('context').description('Build task context with codegraph').argument('<task>', 'task text')).action((task, options) => runCodegraphCommand(io, 'codegraph.context', { subcommand: 'context', project: options.project, task }, options.peaksJson));
+    addProjectOption(codegraph
+        .command('affected')
+        .description('Find code affected by files')
+        .argument('<files...>', 'project-relative file paths')
+        .option('--json', 'forward JSON output flag to upstream codegraph')).action((files, options) => runCodegraphCommand(io, 'codegraph.affected', {
+        subcommand: 'affected',
+        project: options.project,
+        files,
+        ...(options.json === true ? { json: true } : {})
+    }, options.peaksJson));
+}

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

@@ -31,7 +31,7 @@ function registerSCArtifactCommands(sc, io) {
     addJsonOption(sc.command('validate').description('Validate artifact retention for a slice').requiredOption('--slice-id <id>', 'slice identifier')).action((options) => {
         printResult(io, ok('sc.validate', validateArtifactRetention(options.sliceId)), options.json);
     });
-    addJsonOption(sc.command('boundary').description('Record commit boundary for a slice').requiredOption('--slice-id <id>', 'slice identifier').option('--artifact <path>', 'artifact path', multipleOption).option('--code <file>', 'code file path', multipleOption)).action((options) => {
+    addJsonOption(sc.command('boundary').description('Record retention boundary for a slice').requiredOption('--slice-id <id>', 'slice identifier').option('--artifact <path>', 'artifact path', multipleOption).option('--code <file>', 'code file path', multipleOption)).action((options) => {
         printResult(io, ok('sc.boundary', recordCommitBoundary({ sliceId: options.sliceId, ...(options.artifact ? { artifacts: options.artifact } : {}), ...(options.code ? { codeFiles: options.code } : {}) })), options.json);
     });
 }

package/dist/src/cli/program.js

@@ -3,6 +3,7 @@ import { CLI_VERSION } from '../shared/version.js';
 import { registerCoreAndArtifactCommands } from './commands/core-artifact-commands.js';
 import { registerWorkflowCommands } from './commands/workflow-commands.js';
 import { registerCapabilityWorkerConfigAndSCCommands } from './commands/capability-worker-config-sc-commands.js';
+import { registerCodegraphCommands } from './commands/codegraph-commands.js';
 export { printResult } from './cli-helpers.js';
 export function createProgram(io = { stdout: (text) => console.log(text), stderr: (text) => console.error(text) }) {
     const program = new Command();
@@ -24,5 +25,6 @@ export function createProgram(io = { stdout: (text) => console.log(text), stderr
     registerCoreAndArtifactCommands(program, io);
     registerWorkflowCommands(program, io);
     registerCapabilityWorkerConfigAndSCCommands(program, io);
+    registerCodegraphCommands(program, io);
     return program;
 }

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

@@ -0,0 +1,41 @@
+declare const CODEGRAPH_PACKAGE_NAME = "@colbymchenry/codegraph@0.7.10";
+declare const CODEGRAPH_EXECUTABLE: string;
+declare const ALLOWED_SUBCOMMANDS: readonly ["status", "init", "index", "query", "files", "context", "affected"];
+type CodegraphSubcommand = (typeof ALLOWED_SUBCOMMANDS)[number];
+type BaseCodegraphInvocationOptions = {
+    subcommand: CodegraphSubcommand;
+    project: string;
+    search?: string;
+    files?: string[];
+    json?: boolean;
+    quiet?: boolean;
+    yes?: boolean;
+    force?: boolean;
+    limit?: number;
+    maxDepth?: number;
+};
+type ContextCodegraphInvocationOptions = Omit<BaseCodegraphInvocationOptions, 'subcommand'> & {
+    subcommand: 'context';
+    task: string;
+};
+type NonContextCodegraphInvocationOptions = BaseCodegraphInvocationOptions & {
+    subcommand: Exclude<CodegraphSubcommand, 'context'>;
+    task?: never;
+};
+export type CodegraphInvocationOptions = ContextCodegraphInvocationOptions | NonContextCodegraphInvocationOptions;
+export type CodegraphInvocation = {
+    executable: typeof CODEGRAPH_EXECUTABLE;
+    args: string[];
+    cwd: string;
+    packageName: typeof CODEGRAPH_PACKAGE_NAME;
+    subcommand: CodegraphSubcommand;
+};
+export type CodegraphExecutionResult = {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+};
+export type CodegraphProcessRunner = (invocation: CodegraphInvocation) => Promise<CodegraphExecutionResult>;
+export declare function createCodegraphInvocation(options: CodegraphInvocationOptions): CodegraphInvocation;
+export declare function executeCodegraphInvocation(invocation: CodegraphInvocation, runner?: CodegraphProcessRunner): Promise<CodegraphExecutionResult>;
+export {};

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

@@ -0,0 +1,264 @@
+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';
+const CODEGRAPH_PACKAGE_NAME = '@colbymchenry/codegraph@0.7.10';
+const CODEGRAPH_EXECUTABLE = process.execPath;
+const CODEGRAPH_NPX_CLI_PATH = resolveNpxCliPath();
+const CODEGRAPH_BINARY_NAME = 'codegraph';
+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: [],
+    init: ['yes'],
+    index: ['force', 'quiet'],
+    query: ['search', 'json', 'limit'],
+    files: ['json', 'maxDepth'],
+    context: ['task'],
+    affected: ['files', 'json']
+};
+function resolveNpxCliPath() {
+    const require = createRequire(import.meta.url);
+    try {
+        return require.resolve('npm/bin/npx-cli.js');
+    }
+    catch {
+        const nodeBinDirectory = dirname(process.execPath);
+        const candidatePaths = [
+            join(nodeBinDirectory, 'node_modules', 'npm', 'bin', 'npx-cli.js'),
+            resolve(nodeBinDirectory, '..', 'lib', 'node_modules', 'npm', 'bin', 'npx-cli.js')
+        ];
+        const npxCliPath = candidatePaths.find((candidatePath) => existsSync(candidatePath));
+        if (npxCliPath === undefined) {
+            throw new Error('Unable to resolve npm npx-cli.js from the current Node installation');
+        }
+        return npxCliPath;
+    }
+}
+function assertSupportedSubcommand(subcommand) {
+    if (!ALLOWED_SUBCOMMANDS.includes(subcommand)) {
+        throw new Error(`Unsupported codegraph subcommand: ${subcommand}`);
+    }
+}
+function resolveProjectRoot(project) {
+    const projectRoot = resolve(project);
+    try {
+        if (!statSync(projectRoot).isDirectory()) {
+            throw new Error('Project path must exist and be a directory');
+        }
+        return realpathSync.native(projectRoot);
+    }
+    catch {
+        throw new Error('Project path must exist and be a directory');
+    }
+}
+function assertPositiveInteger(value, flagName) {
+    if (value === undefined) {
+        return;
+    }
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error(`${flagName} must be a positive integer`);
+    }
+}
+function assertPositionalArgument(value, argumentName) {
+    if (value.startsWith(POSITIONAL_ARGUMENT_PREFIX)) {
+        throw new Error(`${argumentName} must not start with -`);
+    }
+}
+function assertSupportedOptions(options) {
+    const allowedOptions = new Set(ALLOWED_OPTIONS_BY_SUBCOMMAND[options.subcommand]);
+    const presentOptionKeys = Object.keys(options).filter((key) => !COMMON_OPTION_KEYS.includes(key));
+    const unsupportedOption = presentOptionKeys.find((key) => !allowedOptions.has(key));
+    if (unsupportedOption) {
+        throw new Error(`Unsupported option ${unsupportedOption} for codegraph ${options.subcommand}`);
+    }
+}
+function assertRequiredOptions(options) {
+    if (options.subcommand === 'query' && (!options.search || options.search.trim() === '')) {
+        throw new Error('search must be non-empty');
+    }
+    if (options.subcommand === 'query' && options.search) {
+        assertPositionalArgument(options.search, 'search');
+    }
+    if (options.subcommand === 'context') {
+        assertPositionalArgument(options.task, 'task');
+    }
+}
+function assertInsideProject(projectRoot, absolutePath) {
+    const relativePath = relative(projectRoot, absolutePath);
+    if (relativePath === '' || relativePath.startsWith('..') || isAbsolute(relativePath)) {
+        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)) {
+        const parentPath = dirname(currentPath);
+        if (parentPath === currentPath) {
+            return currentPath;
+        }
+        currentPath = parentPath;
+    }
+    return currentPath;
+}
+function normalizeProjectRelativeFile(projectRoot, file) {
+    assertPositionalArgument(file, 'Affected files');
+    const absoluteFilePath = resolve(projectRoot, file);
+    assertInsideProject(projectRoot, absoluteFilePath);
+    const realBoundary = realpathSync.native(resolveExistingBoundary(absoluteFilePath));
+    assertInsideProject(projectRoot, realBoundary);
+    return relative(projectRoot, absoluteFilePath).split(sep).join('/');
+}
+function buildAffectedFileArgs(projectRoot, files) {
+    if (!files || files.length < 1) {
+        throw new Error('affected requires at least one file');
+    }
+    return files.map((file) => normalizeProjectRelativeFile(projectRoot, file));
+}
+function buildCommandArgs(options, projectRoot) {
+    const args = [CODEGRAPH_NPX_CLI_PATH, '--no', '--package', CODEGRAPH_PACKAGE_NAME, CODEGRAPH_BINARY_NAME, options.subcommand];
+    if (options.subcommand === 'query' && options.search) {
+        args.push(options.search);
+    }
+    if (options.subcommand === 'context') {
+        if (options.task.trim() === '') {
+            throw new Error('task must be non-empty');
+        }
+        args.push(options.task);
+    }
+    if (options.subcommand === 'affected') {
+        args.push(...buildAffectedFileArgs(projectRoot, options.files));
+    }
+    if (options.yes === true) {
+        args.push('--yes');
+    }
+    if (options.force === true) {
+        args.push('--force');
+    }
+    if (options.json === true) {
+        args.push('--json');
+    }
+    if (options.quiet === true) {
+        args.push('--quiet');
+    }
+    if (options.limit !== undefined) {
+        args.push('--limit', String(options.limit));
+    }
+    if (options.maxDepth !== undefined) {
+        args.push('--max-depth', String(options.maxDepth));
+    }
+    return args;
+}
+function createCodegraphEnvironment(sourceEnv = process.env) {
+    const preservedKeys = ['PATH', 'Path', 'HOME', 'USERPROFILE', 'APPDATA', 'LOCALAPPDATA', 'TEMP', 'TMP', 'SystemRoot', 'WINDIR'];
+    const environment = {};
+    for (const key of preservedKeys) {
+        const value = sourceEnv[key];
+        if (value !== undefined) {
+            environment[key] = value;
+        }
+    }
+    return environment;
+}
+function assertOutputLimit(currentSize, chunkSize) {
+    const nextSize = currentSize + chunkSize;
+    if (nextSize > CODEGRAPH_OUTPUT_LIMIT_BYTES) {
+        throw new Error(`codegraph output exceeded ${CODEGRAPH_OUTPUT_LIMIT_BYTES} bytes`);
+    }
+    return nextSize;
+}
+function terminateCodegraphProcess(childProcess) {
+    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' });
+        return;
+    }
+    try {
+        process.kill(-childProcess.pid, 'SIGTERM');
+    }
+    catch {
+        childProcess.kill('SIGTERM');
+    }
+}
+function defaultCodegraphProcessRunner(invocation) {
+    return new Promise((resolveResult, reject) => {
+        const childProcess = spawn(invocation.executable, invocation.args, {
+            cwd: invocation.cwd,
+            detached: process.platform !== 'win32',
+            env: createCodegraphEnvironment(),
+            shell: false
+        });
+        const timeout = setTimeout(() => {
+            terminateCodegraphProcess(childProcess);
+            reject(new Error(`codegraph process timed out after ${CODEGRAPH_PROCESS_TIMEOUT_MS}ms`));
+        }, CODEGRAPH_PROCESS_TIMEOUT_MS);
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let stdoutSize = 0;
+        let stderrSize = 0;
+        childProcess.stdout.on('data', (chunk) => {
+            try {
+                stdoutSize = assertOutputLimit(stdoutSize, chunk.length);
+                stdoutChunks.push(chunk);
+            }
+            catch (error) {
+                terminateCodegraphProcess(childProcess);
+                reject(error);
+            }
+        });
+        childProcess.stderr.on('data', (chunk) => {
+            try {
+                stderrSize = assertOutputLimit(stderrSize, chunk.length);
+                stderrChunks.push(chunk);
+            }
+            catch (error) {
+                terminateCodegraphProcess(childProcess);
+                reject(error);
+            }
+        });
+        childProcess.on('error', (error) => {
+            clearTimeout(timeout);
+            reject(error);
+        });
+        childProcess.on('close', (exitCode) => {
+            clearTimeout(timeout);
+            resolveResult({
+                exitCode,
+                stdout: Buffer.concat(stdoutChunks).toString('utf8'),
+                stderr: Buffer.concat(stderrChunks).toString('utf8')
+            });
+        });
+    });
+}
+export function createCodegraphInvocation(options) {
+    assertSupportedSubcommand(options.subcommand);
+    const projectRoot = resolveProjectRoot(options.project);
+    assertSupportedOptions(options);
+    assertRequiredOptions(options);
+    assertPositiveInteger(options.limit, 'limit');
+    assertPositiveInteger(options.maxDepth, 'maxDepth');
+    return {
+        executable: CODEGRAPH_EXECUTABLE,
+        args: buildCommandArgs(options, projectRoot),
+        cwd: projectRoot,
+        packageName: CODEGRAPH_PACKAGE_NAME,
+        subcommand: options.subcommand
+    };
+}
+export async function executeCodegraphInvocation(invocation, runner = defaultCodegraphProcessRunner) {
+    return runner(invocation);
+}

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

@@ -98,7 +98,9 @@ function readArtifactFile(rootPath, artifactWorkspacePath, artifact) {
     try {
         const artifactWorkspaceRealPath = stableRealPath(artifactWorkspacePath);
         const rootRealPath = stableRealPath(rootPath);
-        if (!isInsidePath(rootRealPath, artifactWorkspaceRealPath)) {
+        const rdRootPath = resolve(rootPath, '..');
+        const sessionRootPath = resolve(rdRootPath, '..');
+        if (lstatSync(sessionRootPath).isSymbolicLink() || lstatSync(rdRootPath).isSymbolicLink() || lstatSync(rootPath).isSymbolicLink() || !isInsidePath(rootRealPath, artifactWorkspaceRealPath)) {
             return null;
         }
         const artifactStat = lstatSync(artifactPath);
@@ -138,7 +140,7 @@ function getConcreteTargetAreas(request, artifactWorkspacePath, hasApprovedTechA
     if (!artifactWorkspacePath || !hasApprovedTechArtifacts || !hasPlannerArtifactWorkspace(request, artifactWorkspacePath)) {
         return [];
     }
-    const architectureRoot = join(artifactWorkspacePath, '.peaks', 'changes', request.changeId, 'architecture');
+    const architectureRoot = join(artifactWorkspacePath, '.peaks', request.changeId, 'rd', 'architecture');
     const candidates = TECH_REQUIRED_ARTIFACTS.flatMap((artifact) => {
         if (artifact === 'tech-approval-record.md') {
             return [];
@@ -155,7 +157,7 @@ function buildPlan(request) {
     const executionModelId = request.executionModelId?.trim() || getConfiguredExecutionModelId(undefined);
     const { workerTarget, blockedReasons } = resolveWorkerTarget(request.maxWorkers);
     const artifactWorkspacePath = resolveArtifactWorkspacePath(request);
-    const artifactRoot = buildArtifactRelativePath(request.changeId, 'swarm');
+    const artifactRoot = buildArtifactRelativePath(request.changeId, 'rd', 'swarm');
     const techStatus = getTechStatus({
         changeId: request.changeId,
         ...(artifactWorkspacePath ? { artifactWorkspacePath } : {}),
@@ -174,10 +176,10 @@ function buildPlan(request) {
             conflictGroups: [],
             artifactRoot,
             outputs: {
-                taskGraph: buildArtifactRelativePath(request.changeId, 'swarm', 'task-graph.json'),
+                taskGraph: buildArtifactRelativePath(request.changeId, 'rd', 'swarm', 'task-graph.json'),
                 waveManifests: [],
                 workerBriefs: [],
-                reducerReport: buildArtifactRelativePath(request.changeId, 'swarm', 'reducer-report.md'),
+                reducerReport: buildArtifactRelativePath(request.changeId, 'rd', 'swarm', 'reducer-report.md'),
             },
             gateStatus: {
                 techApprovalRequired: requiresTechApproval,
@@ -199,10 +201,10 @@ function buildPlan(request) {
             conflictGroups: [],
             artifactRoot,
             outputs: {
-                taskGraph: buildArtifactRelativePath(request.changeId, 'swarm', 'task-graph.json'),
+                taskGraph: buildArtifactRelativePath(request.changeId, 'rd', 'swarm', 'task-graph.json'),
                 waveManifests: [],
                 workerBriefs: [],
-                reducerReport: buildArtifactRelativePath(request.changeId, 'swarm', 'reducer-report.md'),
+                reducerReport: buildArtifactRelativePath(request.changeId, 'rd', 'swarm', 'reducer-report.md'),
             },
             gateStatus: {
                 techApprovalRequired: true,
@@ -223,10 +225,10 @@ function buildPlan(request) {
             conflictGroups: [],
             artifactRoot,
             outputs: {
-                taskGraph: buildArtifactRelativePath(request.changeId, 'swarm', 'task-graph.json'),
+                taskGraph: buildArtifactRelativePath(request.changeId, 'rd', 'swarm', 'task-graph.json'),
                 waveManifests: [],
                 workerBriefs: [],
-                reducerReport: buildArtifactRelativePath(request.changeId, 'swarm', 'reducer-report.md'),
+                reducerReport: buildArtifactRelativePath(request.changeId, 'rd', 'swarm', 'reducer-report.md'),
             },
             gateStatus: {
                 techApprovalRequired: requiresTechApproval,
@@ -263,7 +265,7 @@ function buildPlan(request) {
     };
     const tasks = taskIds.map((taskId, index) => {
         const wave = index < 8 ? 'discovery' : index < 16 ? 'planning' : index < taskIds.length - 8 ? 'implementation candidates' : index < taskIds.length - 5 ? 'unit-test execution' : index < taskIds.length - 1 ? 'quality gates' : 'reducer';
-        const briefPath = buildArtifactRelativePath(request.changeId, 'swarm', 'workers', taskId, 'brief.md');
+        const briefPath = buildArtifactRelativePath(request.changeId, 'rd', 'swarm', 'workers', taskId, 'brief.md');
         const implementationIndex = index - 16;
         const targetArea = wave === 'implementation candidates' && hasConcreteTargetAreas(concreteTargetAreas)
             ? selectConcreteTargetArea(concreteTargetAreas, implementationIndex)
@@ -294,7 +296,7 @@ function buildPlan(request) {
     });
     const conflictGroups = waves.map((wave) => ({
         groupId: `group-${wave.name.replace(/\s+/g, '-')}`,
-        ownedPaths: wave.taskIds.map((taskId) => buildArtifactRelativePath(request.changeId, 'swarm', 'workers', taskId, 'brief.md')),
+        ownedPaths: wave.taskIds.map((taskId) => buildArtifactRelativePath(request.changeId, 'rd', 'swarm', 'workers', taskId, 'brief.md')),
         parallelismPolicy: wave.taskIds.length > 1 ? 'parallel' : 'sequential',
         reason: `${wave.name} work is isolated by worker output path`,
     }));
@@ -308,10 +310,10 @@ function buildPlan(request) {
         conflictGroups,
         artifactRoot,
         outputs: {
-            taskGraph: buildArtifactRelativePath(request.changeId, 'swarm', 'task-graph.json'),
-            waveManifests: waves.map((wave, index) => buildArtifactRelativePath(request.changeId, 'swarm', 'waves', `wave-${index + 1}-${wave.name}.json`)),
+            taskGraph: buildArtifactRelativePath(request.changeId, 'rd', 'swarm', 'task-graph.json'),
+            waveManifests: waves.map((wave, index) => buildArtifactRelativePath(request.changeId, 'rd', 'swarm', 'waves', `wave-${index + 1}-${wave.name}.json`)),
             workerBriefs: tasks.map((task) => task.outputs[0]),
-            reducerReport: buildArtifactRelativePath(request.changeId, 'swarm', 'reducer-report.md'),
+            reducerReport: buildArtifactRelativePath(request.changeId, 'rd', 'swarm', 'reducer-report.md'),
         },
         gateStatus: {
             techApprovalRequired: requiresTechApproval,

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

@@ -83,6 +83,10 @@ export const seedCapabilityItems = [
         fallback: { mode: 'manual-docs-input', qualityImpact: 'lower', nextAction: 'Ask the user to provide the relevant documentation link or pasted excerpt.' },
         presentation: { displayName: { en: 'Documentation Lookup', 'zh-CN': '文档查询能力' }, description: { en: 'Fetches current library and API documentation for implementation planning.', 'zh-CN': '用于获取当前库和 API 文档，辅助实现规划。' } }
     },
+    capability('codegraph.project-indexing', 'codegraph', 'Codegraph Project Indexing', 'cli', 'project-analysis', ['engineer'], 'medium', 'peaks-rd-local-scan', 'Use Peaks RD local project scanning when codegraph is unavailable.', 'Codegraph Project Indexing', 'Codegraph 项目索引', 'Indexes a local project through the peaks codegraph execution boundary for role-skill analysis.', '通过 peaks codegraph 执行边界索引本地项目，辅助角色 skill 分析。'),
+    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('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 实现规划。'),
@@ -104,7 +108,12 @@ export const seedCapabilityItems = [
     capability('ruflo-access-repo.workflow-reference', 'ruflo-access-repo', 'Ruflo Workflow Reference', 'doc', 'workflow-reference', ['engineer'], 'medium', 'peaks-autonomous-planning', 'Use Peaks autonomous planning references without executing external code.', 'Workflow Reference', '工作流参考', 'Catalog-only workflow orchestration reference.', '仅作为目录化的工作流编排参考。'),
     capability('modelcontextprotocol-servers.collection', 'modelcontextprotocol-servers', 'MCP Server Collection', 'doc', 'mcp-collection', ['engineer'], 'medium', 'future-peaks-mcp-catalog', 'Use future Peaks MCP catalog review before selecting individual servers.', 'MCP Collection', 'MCP 集合', 'Catalog-only MCP server collection reference.', '仅作为目录化的 MCP server 集合参考。'),
     capability('andrej-karpathy-skills.guidance', 'andrej-karpathy-skills', 'Engineering Guidance', 'doc', 'engineering-guidance', ['engineer'], 'low', 'project-local-standards', 'Use project-local standards before external guidance.', 'Engineering Guidance', '工程指导', 'External engineering guidance reference.', '外部工程指导参考。'),
-    capability('mattpocock-skills.typescript-guidance', 'mattpocock-skills', 'TypeScript Guidance', 'doc', 'typescript-guidance', ['engineer'], 'low', 'project-local-typescript-standards', 'Use project-local TypeScript standards first.', 'TypeScript Guidance', 'TypeScript 指导', 'External TypeScript guidance reference.', '外部 TypeScript 指导参考。'),
+    capability('mattpocock-skills.product-prd-methods', 'mattpocock-skills', 'Product PRD Methods', 'skill', 'product-prd-methods', ['product', 'engineer'], 'low', 'peaks-prd', 'Use Peaks PRD artifacts first; inspect upstream to-prd, zoom-out, and grill-with-docs before applying method ideas.', 'Product PRD Methods', '产品 PRD 方法', 'References to-prd, zoom-out, and grill-with-docs for product shaping while Peaks PRD remains authoritative.', '参考 to-prd、zoom-out 和 grill-with-docs 进行产品塑形，Peaks PRD 仍保持权威。'),
+    capability('mattpocock-skills.engineering-diagnosis', 'mattpocock-skills', 'Engineering Diagnosis Methods', 'skill', 'engineering-diagnosis', ['engineer'], 'low', 'peaks-rd', 'Use Peaks RD gates first; inspect upstream diagnose, triage, improve-codebase-architecture, and prototype before applying method ideas.', 'Engineering Diagnosis Methods', '工程诊断方法', 'References diagnosis, triage, architecture review, and prototype methods for RD analysis.', '为 RD 分析参考诊断、分流、架构评审和原型方法。'),
+    capability('mattpocock-skills.tdd-method', 'mattpocock-skills', 'TDD Method', 'skill', 'tdd-method', ['engineer', 'qa'], 'low', 'peaks-rd-qa-gates', 'Use Peaks RD and QA test gates first; inspect upstream tdd before applying method ideas.', 'TDD Method', 'TDD 方法', 'References tests-first discipline for RD implementation and QA coverage review.', '为 RD 实现和 QA 覆盖评审参考测试先行纪律。'),
+    capability('mattpocock-skills.qa-triage', 'mattpocock-skills', 'QA Triage Methods', 'skill', 'qa-triage', ['qa', 'engineer'], 'low', 'peaks-qa', 'Use Peaks QA validation gates first; inspect upstream triage and grill-with-docs before applying method ideas.', 'QA Triage Methods', 'QA 分流方法', 'References failure triage and document-backed acceptance checks for QA review.', '为 QA 评审参考失败分流和文档支撑的验收检查。'),
+    capability('mattpocock-skills.handoff-context', 'mattpocock-skills', 'Handoff Context Methods', 'skill', 'handoff-context', ['product', 'engineer', 'qa'], 'low', 'peaks-txt-context-capsule', 'Use Peaks TXT local capsules first; inspect upstream handoff, to-issues, and write-a-skill before applying method ideas.', 'Handoff Context Methods', '交接上下文方法', 'References compact handoff, follow-up issue shaping, and reusable skill lesson capture for TXT.', '为 TXT 参考紧凑交接、后续 issue 塑形和可复用技能经验沉淀。'),
+    capability('mattpocock-skills.git-guardrails', 'mattpocock-skills', 'Git Guardrails References', 'doc', 'git-guardrails', ['engineer'], 'medium', 'peaks-built-in-git-safety', 'Use Peaks and project-local git safety rules; do not install hooks or mutate git configuration automatically.', 'Git Guardrails References', 'Git 护栏参考', 'Catalog-only references for git guardrails and pre-commit setup; not an executable hook action.', 'Git 护栏和 pre-commit 设置的仅目录化参考；不是可执行 hook 动作。'),
     capability('impeccable.quality-guidance', 'impeccable', 'Quality Guidance', 'doc', 'quality-guidance', ['engineer'], 'low', 'peaks-review-gates', 'Use Peaks review gates as authoritative.', 'Quality Guidance', '质量指导', 'Quality reference catalog entry.', '质量参考目录项。'),
     capability('vercel-agent-skills.skill-pack', 'vercel-agent-skills', 'Vercel Agent Skills Pack', 'skill', 'skill-pack', ['engineer'], 'medium', 'external-skill-catalog', 'Inspect individual skills before use.', 'Agent Skills Pack', '代理技能包', 'Catalog-only external skill pack.', '仅作为目录化的外部技能包。'),
     capability('darwin-skill.external-skill', 'darwin-skill', 'Darwin Skill', 'skill', 'external-skill', ['engineer'], 'medium', 'external-skill-catalog', 'Inspect for project fit and safety before use.', 'Darwin Skill', 'Darwin 技能', 'Catalog-only external skill reference.', '仅作为目录化的外部技能参考。'),

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

@@ -1,6 +1,13 @@
 export const seedCapabilityLandingMappings = [
     mapping({ capabilityId: 'ruflo-access-repo.workflow-reference', sourceId: 'ruflo-access-repo', sourceGroup: 'access-repo', landingKind: 'catalog', target: 'peaks autonomous planning reference', guidance: 'Use as workflow orchestration inspiration only; Peaks owns execution boundaries.' }),
     mapping({ capabilityId: 'context7.docs-lookup', sourceId: 'context7', sourceGroup: 'access-repo', landingKind: 'cli', target: 'peaks recommend', commandPreview: 'peaks recommend --workflow code-refactor --json', guidance: 'Use for current library/API documentation lookup through approved MCP access.' }),
+    mapping({ capabilityId: 'codegraph.project-indexing', sourceId: 'codegraph', sourceGroup: 'access-repo', landingKind: 'skill', target: 'peaks-rd', skillName: 'peaks-rd', guidance: 'Dry-run reference only: if local indexing is explicitly approved, peaks-rd may use peaks codegraph index --project <path> before semantic analysis; generated .codegraph artifacts stay local unless explicitly approved.' }),
+    mapping({ capabilityId: 'codegraph.semantic-query', sourceId: 'codegraph', sourceGroup: 'access-repo', landingKind: 'skill', target: 'peaks-rd', skillName: 'peaks-rd', guidance: 'Dry-run reference only: peaks-rd may use peaks codegraph query --project <path> <search> for project relationship evidence during RD planning when execution is approved; Peaks RD gates remain authoritative.' }),
+    mapping({ capabilityId: 'codegraph.impact-analysis', sourceId: 'codegraph', sourceGroup: 'access-repo', landingKind: 'skill', target: 'peaks-rd', skillName: 'peaks-rd', guidance: 'Dry-run reference only: peaks-rd may use peaks codegraph affected --project <path> <files...> --json to inspect likely impact before slice planning and red-line checks when execution is approved.' }),
+    mapping({ capabilityId: 'codegraph.impact-analysis', sourceId: 'codegraph', sourceGroup: 'access-repo', landingKind: 'skill', target: 'peaks-qa', skillName: 'peaks-qa', guidance: 'Use affected output as regression-surface evidence only; QA validation and test evidence remain authoritative.' }),
+    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: '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.' }),
@@ -14,7 +21,13 @@ export const seedCapabilityLandingMappings = [
     mapping({ capabilityId: 'everything-claude-code.security-review-agent', sourceId: 'everything-claude-code', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-rd', skillName: 'peaks-rd', guidance: 'Use as security review capability after local diff and test evidence exist.' }),
     mapping({ capabilityId: 'everything-claude-code.security-review-guidance', sourceId: 'everything-claude-code', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-qa', skillName: 'peaks-qa', guidance: 'Use as project-local security review standards guidance during QA preflight.' }),
     mapping({ capabilityId: 'andrej-karpathy-skills.guidance', sourceId: 'andrej-karpathy-skills', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-rd', skillName: 'peaks-rd', guidance: 'Use as engineering guidance inspiration after project-local standards are scanned.' }),
-    mapping({ capabilityId: 'mattpocock-skills.typescript-guidance', sourceId: 'mattpocock-skills', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-rd', skillName: 'peaks-rd', guidance: 'Use as TypeScript guidance only when it fits project-local conventions.' }),
+    mapping({ capabilityId: 'mattpocock-skills.product-prd-methods', sourceId: 'mattpocock-skills', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-prd', skillName: 'peaks-prd', guidance: 'Use to-prd, zoom-out, and grill-with-docs as inspected product-method references; Peaks PRD artifacts remain authoritative.' }),
+    mapping({ capabilityId: 'mattpocock-skills.engineering-diagnosis', sourceId: 'mattpocock-skills', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-rd', skillName: 'peaks-rd', guidance: 'Use diagnose, triage, improve-codebase-architecture, and prototype as inspected engineering references; Peaks RD gates remain authoritative.' }),
+    mapping({ capabilityId: 'mattpocock-skills.tdd-method', sourceId: 'mattpocock-skills', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-rd', skillName: 'peaks-rd', guidance: 'Use tdd as an inspected tests-first reference during RD implementation; Peaks unit-test and review gates remain authoritative.' }),
+    mapping({ capabilityId: 'mattpocock-skills.tdd-method', sourceId: 'mattpocock-skills', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-qa', skillName: 'peaks-qa', guidance: 'Use tdd as an inspected reference for checking whether tests protect changed behavior; Peaks QA evidence gates remain authoritative.' }),
+    mapping({ capabilityId: 'mattpocock-skills.qa-triage', sourceId: 'mattpocock-skills', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-qa', skillName: 'peaks-qa', guidance: 'Use triage and grill-with-docs as inspected QA references for blockers, release risk, and acceptance evidence; Peaks QA remains the acceptance authority.' }),
+    mapping({ capabilityId: 'mattpocock-skills.handoff-context', sourceId: 'mattpocock-skills', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-txt', skillName: 'peaks-txt', guidance: 'Use handoff, to-issues, and write-a-skill as inspected context references; Peaks TXT local capsule and memory-authorization rules remain authoritative.' }),
+    mapping({ capabilityId: 'mattpocock-skills.git-guardrails', sourceId: 'mattpocock-skills', sourceGroup: 'mcp-server', landingKind: 'catalog', target: 'git guardrails reference catalog', guidance: 'Catalog only; do not install hooks, mutate git configuration, or write Claude settings from this capability map.' }),
     mapping({ capabilityId: 'impeccable.quality-guidance', sourceId: 'impeccable', sourceGroup: 'mcp-server', landingKind: 'catalog', target: 'quality reference catalog', guidance: 'Use as quality inspiration; Peaks review gates remain authoritative.' }),
     mapping({ capabilityId: 'vercel-agent-skills.skill-pack', sourceId: 'vercel-agent-skills', sourceGroup: 'mcp-server', landingKind: 'catalog', target: 'external skill catalog', guidance: 'Catalog only until individual skills are inspected and approved.' }),
     mapping({ capabilityId: 'agent-browser.browser-agent', sourceId: 'agent-browser', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-qa', skillName: 'peaks-qa', guidance: 'Use for browser validation; never submit forms or mutate authenticated state without explicit permission.' }),