peaks-cli 1.0.2 → 1.0.3

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

@@ -144,7 +144,8 @@ function registerWorkspaceCommands(config, io) {
         const artifactRepo = parseArtifactRepoInput(io, options, options.json);
         if (artifactRepo === null)
             return;
-        const workspace = { workspaceId: options.id, name: options.name, rootPath: options.path, installedCapabilityIds: [] };
+        const artifactStorage = artifactRepo ? { mode: 'local-with-remote-sync', remote: artifactRepo } : { mode: 'local' };
+        const workspace = { workspaceId: options.id, name: options.name, rootPath: options.path, installedCapabilityIds: [], artifactStorage };
         const configLayer = layer ?? 'user';
         if (artifactRepo) {
             addWorkspace({ ...workspace, artifactRepo }, configLayer);
@@ -152,7 +153,7 @@ function registerWorkspaceCommands(config, io) {
         else {
             addWorkspace(workspace, configLayer);
         }
-        printResult(io, ok('config.workspace.add', { workspaceId: options.id, name: options.name, rootPath: options.path, artifactRepo }), options.json);
+        printResult(io, ok('config.workspace.add', { workspaceId: options.id, name: options.name, rootPath: options.path, artifactRepo, artifactStorage }), options.json);
     });
     addJsonOption(configWorkspace.command('remove').description('Remove a workspace').requiredOption('--id <id>', 'workspace identifier').option('--layer <layer>', 'user or project')).action((options) => {
         const layer = parseConfigLayer(options.layer);

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

@@ -5,6 +5,7 @@ import { createAutonomousWorkflowPlan } from '../../services/workflow/workflow-a
 import { createRecommendationPlan } from '../../services/recommendations/recommendation-service.js';
 import { createRefactorDryRun } from '../../services/refactor/refactor-service.js';
 import { getCurrentWorkspaceConfig, readConfig } from '../../services/config/config-service.js';
+import { validateChangeIdOrThrow } from '../../shared/change-id.js';
 import { getEconomyAwareExecutionModelId } from '../../services/config/model-routing.js';
 import { getLocalArtifactPath } from '../../services/artifacts/workspace-service.js';
 import { fail, ok } from '../../shared/result.js';
@@ -24,6 +25,12 @@ function parseMaxWorkers(io, command, value, asJson) {
     }
     return maxWorkers;
 }
+function validatePlanningInput(changeId, goal) {
+    validateChangeIdOrThrow(changeId);
+    if (!goal.trim()) {
+        throw new Error('Goal must be non-empty');
+    }
+}
 function parseSoloMode(io, command, mode, soloMode, asJson) {
     if (mode !== 'solo' && soloMode) {
         printResult(io, fail(command, 'SOLO_MODE_REQUIRES_SOLO_WORKFLOW', '--solo-mode can only be used with --mode solo', {}, ['Remove --solo-mode or use --mode solo']), asJson);
@@ -46,6 +53,7 @@ function runTechPlan(io, options) {
         return;
     }
     try {
+        validatePlanningInput(options.changeId, options.goal);
         const workspaceContext = getWorkspaceContext();
         const plan = createTechPlan({
             changeId: options.changeId,
@@ -88,6 +96,7 @@ function runWorkflowRoute(io, options) {
     if (soloMode === null)
         return;
     try {
+        validatePlanningInput(options.changeId, options.goal);
         const workspaceContext = getWorkspaceContext();
         const plan = createWorkflowRouterPlan({
             changeId: options.changeId,
@@ -123,6 +132,7 @@ function runAutonomousWorkflow(io, options) {
     if (soloMode === null)
         return;
     try {
+        validatePlanningInput(options.changeId, options.goal);
         const workspaceContext = getWorkspaceContext();
         const plan = createAutonomousWorkflowPlan({
             changeId: options.changeId,
@@ -155,6 +165,7 @@ function runSwarmPlan(io, options) {
     if (maxWorkers === null)
         return;
     try {
+        validatePlanningInput(options.changeId, options.goal);
         const workspaceContext = getWorkspaceContext();
         const config = readConfig();
         const plan = createRdSwarmPlan({
@@ -246,12 +257,12 @@ export function registerWorkflowCommands(program, io) {
         .command('recommend')
         .description('Create a dry-run recommendation plan for a workflow')
         .requiredOption('--workflow <workflow>', 'workflow: code-refactor, product-refactor, or frontend-design')
-        .option('--language <language>', 'human presentation language', 'en')).action((options) => {
+        .option('--language <language>', 'human presentation language')).action((options) => {
         if (!isRecommendationWorkflow(options.workflow)) {
             printResult(io, fail('recommend', 'UNSUPPORTED_RECOMMENDATION_WORKFLOW', `Unsupported recommendation workflow ${options.workflow}`, {}, ['Use --workflow code-refactor, product-refactor, or frontend-design']), options.json);
             process.exitCode = 1;
             return;
         }
-        printResult(io, ok('recommend', createRecommendationPlan({ workflow: options.workflow, language: options.language })), options.json);
+        printResult(io, ok('recommend', createRecommendationPlan({ workflow: options.workflow, language: options.language ?? readConfig().language })), options.json);
     });
 }

package/dist/src/services/artifacts/artifact-service.js

@@ -3,7 +3,7 @@ import { execFileSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { resolve } from 'node:path';
 import { getCurrentWorkspaceConfig } from '../config/config-service.js';
-import { getLocalArtifactPath } from './workspace-service.js';
+import { getArtifactRemoteRepo, getLocalArtifactPath } from './workspace-service.js';
 function getRemoteUrl(artifactRepo) {
     if (!artifactRepo)
         return null;
@@ -46,7 +46,7 @@ export function createArtifactInitPlan(options) {
 }
 export function createGuidedArtifactSetup() {
     const workspace = getCurrentWorkspaceConfig();
-    const artifactRepo = workspace?.artifactRepo ?? null;
+    const artifactRepo = workspace ? getArtifactRemoteRepo(workspace) : null;
     const validationResult = {
         workspaceExists: workspace !== null,
         gitAvailable: hasGit(),
@@ -65,7 +65,7 @@ export function createGuidedArtifactSetup() {
         localPath,
         remoteUrl,
         validationResult,
-        nextStep: workspace ? (artifactRepo ? 'validate' : 'configure') : 'configure',
+        nextStep: workspace ? (artifactRepo ? 'validate' : 'complete') : 'configure',
         guidance: [
             'Step 1: Detect current workspace and environment',
             `  - Workspace: ${workspace?.workspaceId ?? 'not configured'}`,
@@ -74,6 +74,7 @@ export function createGuidedArtifactSetup() {
             `  - SSH key for code push: ${validationResult.sshKeyAvailable ? 'available' : 'not found'}`,
             '',
             'Step 2: Configure artifact repository',
+            '  - Optional for local-only storage',
             '  - Run: peaks artifacts init --provider github --name <repo> --dry-run',
             '  - Or add to workspace: peaks config workspace add --id <id> --provider github --repo-owner <owner> --repo-name <name>',
             '',
@@ -82,7 +83,7 @@ export function createGuidedArtifactSetup() {
             '  - Run: peaks artifacts workspace',
             '',
             'Step 4: Complete',
-            '  - Artifact sync is ready when workspace has artifactRepo configured'
+            artifactRepo ? '  - Artifact sync is ready when workspace has remote artifact storage configured' : '  - Local artifact storage is ready'
         ]
     };
 }

package/dist/src/services/artifacts/workspace-service.d.ts

@@ -22,6 +22,7 @@ export type SyncResult = {
 export declare function getLocalArtifactPath(workspace: WorkspaceConfig): string;
 export declare function isArtifactWorkspaceOutsideTarget(workspace: WorkspaceConfig, artifactWorkspacePath?: string): boolean;
 export declare function hasValidArtifactWorkspace(workspace: WorkspaceConfig, artifactWorkspacePath?: string): boolean;
+export declare function getArtifactRemoteRepo(workspace: WorkspaceConfig): WorkspaceConfig['artifactRepo'] | null;
 export declare function executeArtifactSync(workspaceId?: string): Promise<SyncResult>;
 export declare function getArtifactWorkspaceStatus(workspaceId?: string): ArtifactWorkspaceStatus;
 export declare function planArtifactSync(workspaceId?: string, dryRun?: boolean): {

package/dist/src/services/artifacts/workspace-service.js

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs';
 import { Buffer } from 'node:buffer';
-import { basename, dirname, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
 import { isInsidePath, stablePath } from '../../shared/path-utils.js';
 import { readConfig, getCurrentWorkspaceConfig } from '../config/config-service.js';
 import { pathExists } from '../../shared/fs.js';
@@ -12,8 +13,10 @@ function canonicalChildPath(parentPath, ...segments) {
     return stablePath(resolve(parentPath, ...segments));
 }
 export function getLocalArtifactPath(workspace) {
-    const rootPath = resolve(workspace.rootPath);
-    return resolve(dirname(rootPath), `${basename(rootPath)}.peaks-artifacts`);
+    if (workspace.artifactStorage?.localPath) {
+        return resolve(workspace.artifactStorage.localPath);
+    }
+    return resolve(homedir(), '.peaks', 'workspaces', workspace.workspaceId, 'artifacts');
 }
 export function isArtifactWorkspaceOutsideTarget(workspace, artifactWorkspacePath = getLocalArtifactPath(workspace)) {
     const targetRoot = canonicalPath(workspace.rootPath);
@@ -44,6 +47,15 @@ export function hasValidArtifactWorkspace(workspace, artifactWorkspacePath = get
         return false;
     return true;
 }
+export function getArtifactRemoteRepo(workspace) {
+    if (workspace.artifactStorage?.mode === 'local-with-remote-sync') {
+        return workspace.artifactStorage.remote;
+    }
+    if (workspace.artifactStorage?.mode === 'local') {
+        return null;
+    }
+    return workspace.artifactRepo ?? null;
+}
 function getPublicRemoteUrl(artifactRepo) {
     if (!artifactRepo)
         return null;
@@ -78,7 +90,7 @@ export async function executeArtifactSync(workspaceId) {
     const workspace = workspaceId
         ? readConfig().workspaces.find((w) => w.workspaceId === workspaceId) ?? null
         : getCurrentWorkspaceConfig();
-    if (!workspace || !workspace.artifactRepo) {
+    if (!workspace) {
         return {
             workspaceId: workspaceId ?? 'unknown',
             success: false,
@@ -86,7 +98,7 @@ export async function executeArtifactSync(workspaceId) {
             remoteUrl: null,
             commands: [],
             output: [],
-            error: 'No artifact repository configured for this workspace'
+            error: 'Workspace not found'
         };
     }
     const localPath = getLocalArtifactPath(workspace);
@@ -101,8 +113,19 @@ export async function executeArtifactSync(workspaceId) {
             error: 'Artifact workspace must be outside the target repository'
         };
     }
-    const remoteUrl = getPublicRemoteUrl(workspace.artifactRepo);
-    const gitAuthEnv = getGitAuthEnv(workspace.artifactRepo);
+    const artifactRepo = getArtifactRemoteRepo(workspace);
+    if (!artifactRepo) {
+        return {
+            workspaceId: workspace.workspaceId,
+            success: true,
+            localPath,
+            remoteUrl: null,
+            commands: [],
+            output: ['Local artifact storage is configured']
+        };
+    }
+    const remoteUrl = getPublicRemoteUrl(artifactRepo);
+    const gitAuthEnv = getGitAuthEnv(artifactRepo);
     if (!remoteUrl) {
         return {
             workspaceId: workspace.workspaceId,
@@ -183,9 +206,9 @@ export function getArtifactWorkspaceStatus(workspaceId) {
     }
     const localPath = getLocalArtifactPath(workspace);
     const hasLocalDir = existsSync(localPath);
-    const hasArtifactRepo = !!workspace.artifactRepo;
+    const artifactRepo = getArtifactRemoteRepo(workspace);
     const hasSafeBoundary = isArtifactWorkspaceOutsideTarget(workspace, localPath);
-    const syncStatus = !hasArtifactRepo || !hasSafeBoundary
+    const syncStatus = !hasSafeBoundary
         ? 'unknown'
         : !hasLocalDir
             ? 'pending'
@@ -193,23 +216,23 @@ export function getArtifactWorkspaceStatus(workspaceId) {
     return {
         workspaceId: workspace.workspaceId,
         localPath,
-        configured: hasArtifactRepo && hasSafeBoundary,
+        configured: hasSafeBoundary,
         syncStatus,
         lastSync: null,
         hasLocalChanges: false,
-        artifactRepo: workspace.artifactRepo ?? null,
+        artifactRepo,
         nextActions: !hasSafeBoundary
             ? ['Configure artifact workspace outside the target repository.']
-            : hasArtifactRepo
+            : artifactRepo
                 ? [`Run peaks artifacts sync --workspace ${workspace.workspaceId} --dry-run`]
-                : [`Configure artifact repo: peaks config workspace add --id ${workspace.workspaceId} --provider github --repo-owner <owner> --repo-name <name>`]
+                : [`Local artifact storage ready at ${localPath}`]
     };
 }
 export function planArtifactSync(workspaceId, dryRun = true) {
     const workspace = workspaceId
         ? readConfig().workspaces.find((w) => w.workspaceId === workspaceId) ?? null
         : getCurrentWorkspaceConfig();
-    if (!workspace || !workspace.artifactRepo) {
+    if (!workspace) {
         return {
             workspaceId: workspaceId ?? 'unknown',
             dryRun,
@@ -228,21 +251,26 @@ export function planArtifactSync(workspaceId, dryRun = true) {
             plannedCommands: ['Artifact workspace must be outside the target repository']
         };
     }
-    const remoteUrl = workspace.artifactRepo.provider === 'github'
-        ? `https://github.com/${workspace.artifactRepo.owner}/${workspace.artifactRepo.name}.git`
-        : `https://gitlab.com/${workspace.artifactRepo.owner}/${workspace.artifactRepo.name}.git`;
-    const plannedCommands = dryRun
-        ? [
-            `# Sync plan for workspace ${workspace.workspaceId}`,
-            `# Local: ${localPath}`,
-            `# Remote: ${remoteUrl}`,
-            '# peaks artifacts sync --workspace ' + workspace.workspaceId,
-            '# (dry-run only — no changes made)'
-        ]
+    const artifactRepo = getArtifactRemoteRepo(workspace);
+    const remoteUrl = getPublicRemoteUrl(artifactRepo);
+    const plannedCommands = artifactRepo
+        ? dryRun
+            ? [
+                `# Sync plan for workspace ${workspace.workspaceId}`,
+                `# Local: ${localPath}`,
+                `# Remote: ${remoteUrl}`,
+                '# peaks artifacts sync --workspace ' + workspace.workspaceId,
+                '# (dry-run only — no changes made)'
+            ]
+            : [
+                `# Sync execution for workspace ${workspace.workspaceId}`,
+                `# Confirm: will sync ${localPath} with ${remoteUrl}`,
+                '# Exit 1 if not confirmed'
+            ]
         : [
-            `# Sync execution for workspace ${workspace.workspaceId}`,
-            `# Confirm: will sync ${localPath} with ${remoteUrl}`,
-            '# Exit 1 if not confirmed'
+            `# Local artifact storage for workspace ${workspace.workspaceId}`,
+            `# Local: ${localPath}`,
+            '# No remote repository is configured or required'
         ];
     return {
         workspaceId: workspace.workspaceId,

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

@@ -1,4 +1,5 @@
 import type { ConfigGetOptions, ConfigLayer, ConfigSetOptions, MiniMaxProviderConfig, PeaksConfig, TokenRef, WorkspaceConfig } from './config-types.js';
+export declare function resolveProjectRootForConfig(startPath: string): string;
 export declare function isConfigLayer(value: string): value is ConfigLayer;
 export declare function isSensitiveConfigPath(path: string): boolean;
 export declare function containsSensitiveConfigValue(value: unknown): boolean;
@@ -17,6 +18,7 @@ export type MiniMaxProviderStatus = {
 export declare function getMiniMaxProviderConfig(): MiniMaxProviderConfig;
 export declare function getMiniMaxProviderStatus(): MiniMaxProviderStatus;
 export declare function setMiniMaxProviderConfig(input: MiniMaxProviderConfig): MiniMaxProviderStatus;
+export declare function bootstrapProjectLanguageConfig(projectRoot: string, language: string): void;
 export declare function readConfig(projectRoot?: string | null): PeaksConfig;
 export declare function writeConfig(partial: Partial<PeaksConfig>, layer?: ConfigLayer): void;
 export declare function getConfig(options?: ConfigGetOptions): unknown;

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

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, relative, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { DEFAULT_CONFIG } from './config-types.js';
@@ -38,6 +38,23 @@ function findProjectRoot(startPath) {
     }
     return null;
 }
+export function resolveProjectRootForConfig(startPath) {
+    const start = resolve(startPath);
+    const homePath = resolve(homedir());
+    let current = start;
+    let parent = dirname(current);
+    while (current !== parent && current !== homePath) {
+        if (existsSync(resolve(current, '.peaks', 'config.json')) && isSafeProjectConfigMarker(current)) {
+            return current;
+        }
+        if (existsSync(resolve(current, 'package.json')) || existsSync(resolve(current, '.git'))) {
+            return current;
+        }
+        parent = current;
+        current = dirname(parent);
+    }
+    return start;
+}
 function getProjectConfigPath(projectRoot) {
     if (!projectRoot)
         return null;
@@ -45,6 +62,46 @@ function getProjectConfigPath(projectRoot) {
         return null;
     return resolve(projectRoot, '.peaks', 'config.json');
 }
+function getProjectBootstrapConfigPath(projectRoot) {
+    const projectRootPath = resolve(projectRoot);
+    const peaksPath = resolve(projectRootPath, '.peaks');
+    const configPath = resolve(peaksPath, 'config.json');
+    if (!isInsidePath(configPath, projectRootPath)) {
+        throw new Error('Project config path must stay inside the project root');
+    }
+    if (!existsSync(peaksPath)) {
+        mkdirSync(peaksPath, { recursive: true });
+    }
+    validateProjectBootstrapConfigPath(projectRootPath, peaksPath, configPath);
+    return configPath;
+}
+function validateProjectBootstrapConfigPath(projectRootPath, peaksPath, configPath) {
+    const projectRootReal = realpathSync(projectRootPath);
+    const peaksStats = lstatSync(peaksPath);
+    const peaksReal = realpathSync(peaksPath);
+    if (!peaksStats.isDirectory() || peaksStats.isSymbolicLink() || peaksReal !== resolve(projectRootReal, '.peaks')) {
+        throw new Error('Project config path must stay inside the project root');
+    }
+    try {
+        const markerStats = lstatSync(configPath);
+        if (!markerStats.isFile() || markerStats.isSymbolicLink()) {
+            throw new Error('Project config path must stay inside the project root');
+        }
+        const markerReal = realpathSync(configPath);
+        if (!isInsidePath(markerReal, projectRootReal) || !isInsidePath(markerReal, peaksReal)) {
+            throw new Error('Project config path must stay inside the project root');
+        }
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+}
+function validateProjectBootstrapConfigPathForWrite(projectRoot, configPath) {
+    const projectRootPath = resolve(projectRoot);
+    validateProjectBootstrapConfigPath(projectRootPath, resolve(projectRootPath, '.peaks'), configPath);
+}
 function readJsonFile(path) {
     if (!path || !existsSync(path))
         return null;
@@ -55,6 +112,16 @@ function readJsonFile(path) {
         return null;
     }
 }
+function readExistingJsonFile(path, errorMessage) {
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        throw new Error(errorMessage);
+    }
+}
 function ensureDir(dirPath) {
     if (!existsSync(dirPath)) {
         mkdirSync(dirPath, { recursive: true });
@@ -97,9 +164,9 @@ function setNestedValue(obj, path, value) {
     const last = parts[parts.length - 1];
     current[last] = value;
 }
-function removeProjectProviderSecrets(config) {
-    const { providers, ...safeConfig } = config;
-    return safeConfig;
+function removeProjectSensitiveConfig(config) {
+    const { providers, proxy, tokens, ...safeConfig } = config;
+    return Object.fromEntries(Object.entries(safeConfig).filter(([key, value]) => !isSecretKey(key) && !containsSensitiveConfigValue(value)));
 }
 export function isConfigLayer(value) {
     return value === 'user' || value === 'project';
@@ -214,18 +281,48 @@ function validateProxyConfig(partial) {
 function isRecord(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
+function isSafeConfigSegment(value) {
+    return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value) && !value.includes('..') && !value.endsWith('.');
+}
+function toArtifactRemoteRepoConfig(value) {
+    if (!isRecord(value) || (value.provider !== 'github' && value.provider !== 'gitlab') || typeof value.owner !== 'string' || typeof value.name !== 'string') {
+        return null;
+    }
+    if (!isSafeConfigSegment(value.owner) || !isSafeConfigSegment(value.name)) {
+        return null;
+    }
+    return { provider: value.provider, owner: value.owner, name: value.name };
+}
+function toArtifactStorageConfig(value) {
+    if (!isRecord(value))
+        return null;
+    const localPath = typeof value.localPath === 'string' ? { localPath: value.localPath } : {};
+    if (value.mode === 'local') {
+        return { mode: 'local', ...localPath };
+    }
+    const remote = toArtifactRemoteRepoConfig(value.remote);
+    if (value.mode === 'local-with-remote-sync' && remote) {
+        return { mode: 'local-with-remote-sync', ...localPath, remote };
+    }
+    return null;
+}
 function toWorkspaceConfig(value) {
     if (!isRecord(value))
         return null;
     const { workspaceId, name, rootPath, installedCapabilityIds } = value;
-    if (typeof workspaceId !== 'string' || typeof name !== 'string' || typeof rootPath !== 'string' || !Array.isArray(installedCapabilityIds) || !installedCapabilityIds.every((id) => typeof id === 'string')) {
+    if (typeof workspaceId !== 'string' || !isSafeConfigSegment(workspaceId) || typeof name !== 'string' || typeof rootPath !== 'string' || !Array.isArray(installedCapabilityIds) || !installedCapabilityIds.every((id) => typeof id === 'string')) {
         return null;
     }
-    let artifactRepo;
-    if (isRecord(value.artifactRepo) && (value.artifactRepo.provider === 'github' || value.artifactRepo.provider === 'gitlab') && typeof value.artifactRepo.owner === 'string' && typeof value.artifactRepo.name === 'string') {
-        artifactRepo = { provider: value.artifactRepo.provider, owner: value.artifactRepo.owner, name: value.artifactRepo.name };
-    }
-    return artifactRepo ? { workspaceId, name, rootPath, installedCapabilityIds, artifactRepo } : { workspaceId, name, rootPath, installedCapabilityIds };
+    const artifactRepo = toArtifactRemoteRepoConfig(value.artifactRepo);
+    const artifactStorage = toArtifactStorageConfig(value.artifactStorage);
+    return {
+        workspaceId,
+        name,
+        rootPath,
+        installedCapabilityIds,
+        ...(artifactRepo ? { artifactRepo } : {}),
+        ...(artifactStorage ? { artifactStorage } : {})
+    };
 }
 function toWorkspaceConfigs(value) {
     return Array.isArray(value) ? value.map(toWorkspaceConfig).filter((workspace) => workspace !== null) : [];
@@ -355,6 +452,19 @@ export function setMiniMaxProviderConfig(input) {
     writeConfig({ providers }, 'user');
     return createMiniMaxProviderStatus(providers.minimax ?? {});
 }
+function inferHumanLanguage(value) {
+    const normalized = value.trim();
+    if (!normalized) {
+        throw new Error('Language must be non-empty');
+    }
+    if (/^zh(?:-|$)/i.test(normalized) || /[㐀-鿿]/u.test(normalized)) {
+        return 'zh-CN';
+    }
+    if (/^en(?:-|$)/i.test(normalized)) {
+        return 'en';
+    }
+    return 'en';
+}
 function toPeaksConfig(value) {
     if (!isRecord(value))
         return {};
@@ -372,12 +482,22 @@ function toPeaksConfig(value) {
         ...(proxy ? { proxy } : {})
     };
 }
+export function bootstrapProjectLanguageConfig(projectRoot, language) {
+    const inferredLanguage = inferHumanLanguage(language);
+    const projectPath = getProjectBootstrapConfigPath(projectRoot);
+    const existing = readExistingJsonFile(projectPath, 'Project config must contain valid JSON') ?? {};
+    if (typeof existing.language === 'string' && existing.language.trim().length > 0) {
+        return;
+    }
+    validateProjectBootstrapConfigPathForWrite(projectRoot, projectPath);
+    writeFileSync(projectPath, JSON.stringify({ ...existing, language: inferredLanguage }, null, 2), 'utf-8');
+}
 export function readConfig(projectRoot) {
     const detectedRoot = projectRoot ?? findProjectRoot(process.cwd());
     const userPath = getUserConfigPath();
     const projectPath = getProjectConfigPath(detectedRoot);
     const userConfig = toPeaksConfig(readJsonFile(userPath));
-    const projectConfig = removeProjectProviderSecrets(toPeaksConfig(readJsonFile(projectPath)));
+    const projectConfig = removeProjectSensitiveConfig(toPeaksConfig(readJsonFile(projectPath)));
     const { proxy: projectProxy, ...projectConfigWithoutProxy } = projectConfig;
     return {
         ...DEFAULT_CONFIG,
@@ -413,7 +533,7 @@ export function writeConfig(partial, layer = 'user') {
 export function getConfig(options = {}) {
     const projectRoot = findProjectRoot(process.cwd());
     const userConfig = readJsonFile(getUserConfigPath()) ?? {};
-    const projectConfig = removeProjectProviderSecrets(readJsonFile(getProjectConfigPath(projectRoot)) ?? {});
+    const projectConfig = removeProjectSensitiveConfig(readJsonFile(getProjectConfigPath(projectRoot)) ?? {});
     const { proxy: projectProxy, ...projectConfigWithoutProxy } = projectConfig;
     const source = options.layer === 'user' ? userConfig : options.layer === 'project' ? projectConfig : { ...userConfig, ...projectConfigWithoutProxy };
     const config = isRecord(source) ? { ...source, ...(source.tokens !== undefined ? { tokens: toTokenConfig(source.tokens) } : {}) } : source;
@@ -465,6 +585,9 @@ function readLayerConfig(layer) {
         : { currentWorkspace: null, workspaces: [] };
 }
 export function addWorkspace(workspace, layer = 'user') {
+    if (!isSafeConfigSegment(workspace.workspaceId)) {
+        throw new Error('Workspace id must only contain letters, numbers, dots, underscores, or hyphens and must not contain path traversal');
+    }
     const config = readLayerConfig(layer);
     const workspaces = config.workspaces;
     const existing = workspaces.findIndex((w) => w.workspaceId === workspace.workspaceId);
@@ -474,6 +597,8 @@ export function addWorkspace(workspace, layer = 'user') {
     writeConfig({ workspaces: updatedWorkspaces }, layer);
 }
 export function removeWorkspace(workspaceId, layer = 'user') {
+    if (!isSafeConfigSegment(workspaceId))
+        return false;
     const config = readLayerConfig(layer);
     const workspaces = config.workspaces;
     const idx = workspaces.findIndex((w) => w.workspaceId === workspaceId);
@@ -485,6 +610,8 @@ export function removeWorkspace(workspaceId, layer = 'user') {
     return true;
 }
 export function setCurrentWorkspace(workspaceId, layer = 'user') {
+    if (!isSafeConfigSegment(workspaceId))
+        return false;
     const config = readLayerConfig(layer);
     const workspaces = config.workspaces;
     const exists = workspaces.some((w) => w.workspaceId === workspaceId);

package/dist/src/services/config/config-types.d.ts

@@ -27,15 +27,26 @@ export type ModelProviderConfig = {
 export type ProxyConfig = {
     httpProxy?: string;
 };
+export type ArtifactProvider = 'github' | 'gitlab';
+export type ArtifactRemoteRepoConfig = {
+    provider: ArtifactProvider;
+    owner: string;
+    name: string;
+};
+export type ArtifactStorageConfig = {
+    mode: 'local';
+    localPath?: string;
+} | {
+    mode: 'local-with-remote-sync';
+    localPath?: string;
+    remote: ArtifactRemoteRepoConfig;
+};
 export type WorkspaceConfig = {
     workspaceId: string;
     name: string;
     rootPath: string;
-    artifactRepo?: {
-        provider: 'github' | 'gitlab';
-        owner: string;
-        name: string;
-    };
+    artifactRepo?: ArtifactRemoteRepoConfig;
+    artifactStorage?: ArtifactStorageConfig;
     installedCapabilityIds: string[];
 };
 export type PeaksConfig = {

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

@@ -1,8 +1,9 @@
 import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { basename, relative, resolve } from 'node:path';
+import { isInsidePath } from '../../shared/path-utils.js';
 import { getCurrentWorkspaceConfig } from '../config/config-service.js';
-import { getArtifactWorkspaceStatus, getLocalArtifactPath } from '../artifacts/workspace-service.js';
+import { getArtifactRemoteRepo, getArtifactWorkspaceStatus, getLocalArtifactPath } from '../artifacts/workspace-service.js';
 const REQUIRED_ARTIFACTS = [
     { name: 'artifact-retention-report.md', path: ['qa', 'artifact-retention-report.md'] },
     { name: 'change-impact.json', path: ['sc', 'change-impact.json'] },
@@ -63,8 +64,8 @@ function mapSyncState(syncStatus) {
         return 'pending';
     return 'failed';
 }
-function getCurrentArtifactDir(workspaceRoot) {
-    const peaksPath = getPeaksPath(workspaceRoot);
+function getCurrentArtifactDir(artifactWorkspacePath) {
+    const peaksPath = getPeaksPath(artifactWorkspacePath);
     const changeId = resolveCurrentChangeId(peaksPath);
     const effectiveChangeId = changeId ?? 'unknown-change';
     return {
@@ -73,14 +74,30 @@ function getCurrentArtifactDir(workspaceRoot) {
         changeDir: resolve(peaksPath, 'changes', effectiveChangeId)
     };
 }
-function getRetentionChangeDir(workspaceRoot, sliceId) {
-    const peaksPath = getPeaksPath(workspaceRoot);
+function getRetentionChangeDir(artifactWorkspacePath, sliceId) {
+    const peaksPath = getPeaksPath(artifactWorkspacePath);
     return {
         peaksPath,
         changeId: sliceId,
         changeDir: resolve(peaksPath, 'changes', sliceId)
     };
 }
+function isRetainedArtifactFile(filePath, artifactWorkspacePath, changesRoot, changeDir) {
+    if (!existsSync(filePath))
+        return false;
+    try {
+        const artifactWorkspaceRealPath = realpathSync(artifactWorkspacePath);
+        const changesRootRealPath = realpathSync(changesRoot);
+        const changeDirRealPath = realpathSync(changeDir);
+        const fileRealPath = realpathSync(filePath);
+        return isInsidePath(changesRootRealPath, artifactWorkspaceRealPath)
+            && isInsidePath(changeDirRealPath, changesRootRealPath)
+            && isInsidePath(fileRealPath, changeDirRealPath);
+    }
+    catch {
+        return false;
+    }
+}
 export function getChangeTraceabilityStatus() {
     const workspace = getCurrentWorkspaceConfig();
     const artifactStatus = getArtifactWorkspaceStatus(workspace?.workspaceId);
@@ -98,8 +115,10 @@ export function getChangeTraceabilityStatus() {
             nextActions: ['Add a workspace: peaks config workspace add --id <id> --name <name> --path <path>']
         };
     }
-    const { peaksPath, changeId, changeDir } = getCurrentArtifactDir(workspace.rootPath);
-    const hasArtifactRepo = Boolean(workspace.artifactRepo);
+    const artifactWorkspacePath = getLocalArtifactPath(workspace);
+    const { peaksPath, changeId, changeDir } = getCurrentArtifactDir(artifactWorkspacePath);
+    const artifactRepo = getArtifactRemoteRepo(workspace);
+    const hasArtifactRepo = Boolean(artifactRepo);
     const requiredArtifacts = REQUIRED_ARTIFACTS.map((artifact) => {
         const artifactPath = resolve(changeDir, ...artifact.path);
         return {
@@ -112,11 +131,7 @@ export function getChangeTraceabilityStatus() {
     if (!changeId) {
         nextActions.push('Set the current change in .peaks/current-change');
     }
-    if (!hasArtifactRepo) {
-        nextActions.push('Configure artifact repo: peaks config workspace add --id <id> --provider github --repo-owner <owner> --repo-name <name>');
-        nextActions.push('Then run: peaks artifacts init --provider github --name <repo> --dry-run');
-    }
-    else if (artifactStatus.syncStatus === 'pending') {
+    if (hasArtifactRepo && artifactStatus.syncStatus === 'pending') {
         nextActions.push(`Run peaks artifacts sync --workspace ${workspace.workspaceId} --dry-run`);
     }
     return {
@@ -130,7 +145,7 @@ export function getChangeTraceabilityStatus() {
 }
 export function createChangeImpact(options) {
     const workspace = getCurrentWorkspaceConfig();
-    const artifactRepo = workspace?.artifactRepo ?? null;
+    const artifactRepo = workspace ? getArtifactRemoteRepo(workspace) : null;
     return {
         changeId: options.changeId,
         sourceArtifacts: options.sourceArtifacts ?? [],
@@ -195,10 +210,12 @@ export function validateArtifactRetention(sliceId) {
             warnings: ['Slice id must stay inside .peaks/changes and only contain letters, numbers, dots, underscores, or hyphens']
         };
     }
-    const { changeDir } = getRetentionChangeDir(workspace.rootPath, sliceId);
+    const artifactWorkspacePath = getLocalArtifactPath(workspace);
+    const { peaksPath, changeDir } = getRetentionChangeDir(artifactWorkspacePath, sliceId);
+    const changesRoot = resolve(peaksPath, 'changes');
     const missingArtifacts = RETENTION_REQUIREMENTS
         .map(([folder, file]) => resolve(changeDir, folder, file))
-        .filter((filePath) => !existsSync(filePath))
+        .filter((filePath) => !isRetainedArtifactFile(filePath, artifactWorkspacePath, changesRoot, changeDir))
         .map((filePath) => relative(changeDir, filePath).replace(/\\/g, '/'));
     return {
         valid: missingArtifacts.length === 0,

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

@@ -1 +1 @@
-export declare const CLI_VERSION = "1.0.2";
+export declare const CLI_VERSION = "1.0.3";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.0.2";
+export const CLI_VERSION = "1.0.3";

package/output-styles/peaks-skill-swarm.md

@@ -0,0 +1,132 @@
+---
+name: Peaks Skill Swarm
+description: Peaks 专用输出风格：仅在 peaks skills 工作流中用东北幽默强化角色编排、蜂群开发、成本模式和交付证据。
+keep-coding-instructions: true
+---
+
+This output style is self-gated. Apply the sections below only when the current task explicitly invokes or continues a Peaks skill workflow, including `/peaks-*`, `skills/peaks-*`, Peaks PRD/RD/QA/UI/SC/TXT/Solo work, or edits to this repository's `skills/` directory. For unrelated tasks, preserve the default Claude Code behavior and keep responses concise.
+
+## Peaks response contract
+
+When active, make the skill transition visually obvious with a light Northeastern Chinese humor tone. Keep technical facts, risks, commands, and evidence precise; use humor only in short labels or one-liners, never to obscure blockers or failures. Start the first response for a Peaks skill task with this banner:
+
+```markdown
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Peaks Skill Active: <skill-name> — 整活开工，但不整虚的
+Role Chain: <PRD → RD → QA → SC, or single role>
+Mode: <Solo | Assisted | Swarm | Strict | Economy>
+Current Gate: <confirmation | dry-run | coverage | QA | commit boundary | handoff>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Use visible layout elements, not just a different tone: heavy separators, bracketed badges, a three-step workflow strip, and compact evidence tables. Then include a short process preview before doing work:
+
+```markdown
+[流程条] ① <current role action>  →  ② <next gate or validation>  →  ③ <handoff / artifact / follow-up>
+```
+
+For swarm or economy mode, add a compact worker table when useful:
+
+```markdown
+| Worker | Scope | Model/Cost lane | Output | Stop condition |
+| --- | --- | --- | --- | --- |
+| RD-1 | <subsystem> | <high/economy/configured provider> | <artifact> | <done signal> |
+```
+
+For final evidence, prefer this visual block:
+
+```markdown
+┌─ Evidence ───────────────────────
+│ Commands: <only commands that matter>
+│ Artifacts: <paths or none>
+│ Changed: <files or none>
+│ Blocker: <blocker or none>
+│ Next: <one next action>
+└──────────────────────────────────
+```
+
+For continuing turns in the same Peaks workflow, use a compact status header instead of the full banner:
+
+```markdown
+Peaks Skill: <skill-name> | Gate: <current gate> | Next: <one short action>
+```
+
+Structure active Peaks responses around:
+
+1. **Role** — name the active Peaks role or role chain, for example PRD → RD → QA → SC.
+2. **Mode** — state whether the workflow is Solo, Assisted, Swarm, Strict, or Economy.
+3. **Gate** — show the current required gate: product confirmation, RD dry-run, coverage, QA acceptance, commit boundary, or handoff.
+4. **Action** — describe the immediate next action in one short sentence before tool use.
+5. **Evidence** — end with only the evidence that matters: commands, artifacts, changed files, blockers, and next action.
+
+Do not produce long narrative logs. Prefer compact capsules, tables, and checklists when they reduce ambiguity. For unrelated non-Peaks tasks, do not show the banner.
+
+## GStack alignment
+
+Use gstack as a workflow reference for `Think → Plan → Build → Review → Test → Ship → Reflect`, but keep Peaks as the authority:
+
+- Think maps to Peaks PRD and TXT context.
+- Plan maps to Peaks RD/UI planning, risk matrices, and slice contracts.
+- Build maps to RD implementation under strict specs.
+- Review maps to code review, design review, and security review.
+- Test maps to QA regression and acceptance evidence.
+- Ship maps to SC commit boundaries, sync state, and rollback points.
+- Reflect maps to TXT lessons and reusable memory candidates.
+
+Do not imply that gstack commands are available unless the project has explicitly installed or exposed them.
+
+## Swarm development mode
+
+Use Swarm mode for broad, parallelizable work with separable responsibilities. When recommending or running swarm work:
+
+- split workers by role, risk, or subsystem;
+- give each worker a bounded brief, expected artifact, and stop condition;
+- require a reducer pass that merges findings, removes conflicts, and chooses the smallest safe implementation;
+- keep shared-state actions, commits, pushes, deploys, and external messages behind explicit confirmation;
+- report worker outputs as a compact matrix: worker, scope, result, blocker, next action.
+
+Prefer parallel agents only for independent work. Do not duplicate searches or reviews already assigned to a worker.
+
+## Economy mode
+
+Use Economy mode when the user asks for low-cost execution or when the task is broad but low-risk. In Economy mode:
+
+- reserve high-capability models for architecture, reducer decisions, security-sensitive work, and final review;
+- route routine summarization, first-pass classification, repetitive inspection, and draft generation to cheaper available workers or providers when the environment supports them;
+- treat MiniMax and similar low-cost models as candidate worker backends only when the current toolchain exposes them or the user authorizes that routing;
+- never claim MiniMax or another external model was used unless an actual configured tool or agent invocation used it;
+- escalate from Economy to Strict when the task touches security, destructive operations, data loss risk, releases, or unclear requirements.
+
+When explaining Economy mode, separate **available now** from **recommended if configured**.
+
+## Peaks RD code-output rule
+
+When the active role is Peaks RD and code is produced or modified, require repeated dry-runs:
+
+1. run applicable Peaks standards dry-runs before planning or implementation;
+2. rerun relevant dry-runs after each meaningful slice or standards-affecting decision;
+3. rerun before handoff, review, or commit-boundary work;
+4. include dry-run command, result, and remaining action in the RD handoff capsule.
+
+If a dry-run cannot be executed, state the blocker and keep it as the next action rather than silently skipping it.
+
+## Output examples
+
+### Active Peaks skill
+
+```markdown
+Role: RD → QA
+Mode: Swarm
+Gate: RD dry-run before implementation
+Action: I will run standards dry-runs, then split workers by subsystem.
+
+Evidence:
+- Commands: ...
+- Artifacts: ...
+- Blocker: none
+- Next: reducer review
+```
+
+### Non-Peaks task
+
+Use normal concise Claude Code responses without the Peaks role/mode/gate wrapper.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Peaks CLI and short skill family for Claude Code automation.",
   "author": "SquabbyZ",
   "license": "SEE LICENSE IN LICENSE",
@@ -22,6 +22,7 @@
     "scripts/install-skills.mjs",
     "scripts/watch.mjs",
     "skills/**",
+    "output-styles/**",
     "schemas/*.json"
   ],
   "scripts": {

package/scripts/install-skills.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, readdirSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, readdirSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -29,13 +29,22 @@ function markManagedPeaksLink(targetPath, sourcePath) {
   writeFileSync(markerPath, `${sourcePath}\n`, 'utf8');
 }
 
+function isManagedPeaksOutputStyle(managedTarget, outputStyleName) {
+  if (managedTarget === null) return false;
+  return managedTarget.replaceAll('\\', '/').endsWith(`/output-styles/${outputStyleName}`);
+}
+
+function createInstallResult() {
+  return { installed: [], skipped: [] };
+}
+
 export function installBundledSkills(options = {}) {
   const packageRoot = resolve(options.packageRoot ?? join(dirname(fileURLToPath(import.meta.url)), '..'));
   const skillsRoot = join(packageRoot, 'skills');
   const targetRoot = resolve(options.targetRoot ?? process.env.PEAKS_CLAUDE_SKILLS_DIR ?? join(homedir(), '.claude', 'skills'));
 
   if (process.env.PEAKS_SKIP_SKILL_INSTALL === '1' || !existsSync(skillsRoot)) {
-    return { installed: [], skipped: [] };
+    return createInstallResult();
   }
 
   const installed = [];
@@ -75,18 +84,66 @@ export function installBundledSkills(options = {}) {
   return { installed, skipped };
 }
 
+export function installBundledOutputStyles(options = {}) {
+  const packageRoot = resolve(options.packageRoot ?? join(dirname(fileURLToPath(import.meta.url)), '..'));
+  const outputStylesRoot = join(packageRoot, 'output-styles');
+  const targetRoot = resolve(options.targetRoot ?? process.env.PEAKS_CLAUDE_OUTPUT_STYLES_DIR ?? join(homedir(), '.claude', 'output-styles'));
+
+  if (process.env.PEAKS_SKIP_SKILL_INSTALL === '1' || !existsSync(outputStylesRoot)) {
+    return createInstallResult();
+  }
+
+  const installed = [];
+  const skipped = [];
+  mkdirSync(targetRoot, { recursive: true });
+
+  for (const outputStyleName of readdirSync(outputStylesRoot)) {
+    const sourcePath = join(outputStylesRoot, outputStyleName);
+    const targetPath = join(targetRoot, outputStyleName);
+
+    if (!lstatSync(sourcePath).isFile() || !outputStyleName.endsWith('.md')) {
+      continue;
+    }
+
+    const current = getPathStats(targetPath);
+    if (current) {
+      const managedTarget = getManagedTarget(targetPath);
+      if (isManagedPeaksOutputStyle(managedTarget, outputStyleName)) {
+        unlinkSync(targetPath);
+        unlinkSync(`${targetPath}.peaks-managed`);
+      } else {
+        skipped.push(outputStyleName);
+        continue;
+      }
+    }
+
+    copyFileSync(sourcePath, targetPath);
+    markManagedPeaksLink(targetPath, sourcePath);
+    installed.push(outputStyleName);
+  }
+
+  return { installed, skipped };
+}
+
 if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
   try {
-    const result = installBundledSkills();
-    if (result.installed.length > 0) {
-      process.stdout.write(`Peaks skills linked: ${result.installed.join(', ')}\n`);
+    const skillsResult = installBundledSkills();
+    const outputStylesResult = installBundledOutputStyles();
+    if (skillsResult.installed.length > 0) {
+      process.stdout.write(`Peaks skills linked: ${skillsResult.installed.join(', ')}\n`);
+    }
+    if (skillsResult.skipped.length > 0) {
+      process.stderr.write(`Peaks skills skipped because local files already exist: ${skillsResult.skipped.join(', ')}\n`);
+    }
+    if (outputStylesResult.installed.length > 0) {
+      process.stdout.write(`Peaks output styles installed: ${outputStylesResult.installed.join(', ')}\n`);
     }
-    if (result.skipped.length > 0) {
-      process.stderr.write(`Peaks skills skipped because local files already exist: ${result.skipped.join(', ')}\n`);
+    if (outputStylesResult.skipped.length > 0) {
+      process.stderr.write(`Peaks output styles skipped because local files already exist: ${outputStylesResult.skipped.join(', ')}\n`);
     }
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    process.stderr.write(`Peaks skills were not linked: ${message}\n`);
+    process.stderr.write(`Peaks skills and output styles were not installed: ${message}\n`);
     process.exitCode = 1;
   }
 }

package/skills/peaks-prd/SKILL.md

@@ -26,6 +26,14 @@ For refactor workflows, avoid writing a full product PRD unless needed. Produce
 - risk notes;
 - user confirmation record.
 
+## GStack integration
+
+Use gstack as a concrete workflow reference for the product-facing parts of `Think → Plan → Build → Review → Test → Ship → Reflect`:
+
+- map `/office-hours`-style exploration to Peaks goal, non-goal, and design-doc artifacts;
+- map CEO/product plan review to user-confirmable product assumptions and acceptance criteria;
+- preserve Peaks artifact gates instead of copying gstack commands verbatim.
+
 ## External capability guidance
 
 Use `peaks capabilities --source mcp-server --json` before recommending product or workflow methodology resources.

package/skills/peaks-qa/SKILL.md

@@ -29,6 +29,18 @@ If the repo needs a first-time standards bundle, treat `standards init` as the c
 
 For refactors, QA must be involved before implementation. It defines the regression and acceptance surface, then verifies the same surface after implementation.
 
+## GStack integration
+
+Use gstack as a concrete QA workflow reference for the `Review → Test → Ship` stages:
+
+- map `/qa` and `/qa-only` browser validation concepts to Peaks regression matrices and validation reports;
+- map regression-test creation to Peaks acceptance checks and coverage evidence;
+- keep Peaks QA as the acceptance authority, with gstack browser and QA patterns as references only when capabilities and user approval allow them.
+
+## Compact handoff
+
+Before QA work stops, finishes, blocks, or hands off, emit a short resumable capsule: validation surface, coverage status, commands run, pass/fail summary, artifact paths, residual risks, blockers, and next action. Link to logs, coverage reports, regression matrices, and validation reports instead of pasting full outputs.
+
 ## External capability guidance
 
 Use `peaks capabilities --source access-repo --json` before recommending browser or validation MCPs.

package/skills/peaks-rd/SKILL.md

@@ -25,6 +25,22 @@ Before RD planning or implementation work in a code repository, call the Peaks C
 
 If `CLAUDE.md` is missing, treat creation as the preferred path. If `CLAUDE.md` already exists, use `standards update` to decide whether to append a managed index block or surface review-only suggestions. Apply only when write authorization exists; otherwise keep the CLI output as a preflight next action. Do not hand-write standards file mutations inside the skill.
 
+## GStack integration and code dry-runs
+
+Use gstack as a concrete engineering workflow reference for `Think → Plan → Build → Review → Test → Ship → Reflect`:
+
+- map plan engineering review to Peaks RD risk matrices, task graphs, and slice contracts;
+- map build/review discipline to strict spec-first implementation and code-review gates;
+- map investigate/careful/guard concepts to root-cause analysis, risky-action confirmation, and scoped edit boundaries;
+- adapt gstack concepts into Peaks artifacts rather than invoking gstack commands as runtime dependencies.
+
+When Peaks RD produces or changes code, dry-run repeatedly instead of only during preflight:
+
+1. run standards dry-runs before planning or implementation;
+2. run the relevant Peaks dry-run again after each meaningful implementation slice or standards-affecting decision;
+3. run the relevant dry-run before handoff, review, or commit-boundary work;
+4. record dry-run command, result, and remaining action in the RD handoff capsule.
+
 ## Refactor hard gates
 
 If a request is refactor, cleanup, architecture adjustment, module split, or technical debt work:
@@ -39,6 +55,38 @@ If a request is refactor, cleanup, architecture adjustment, module split, or tec
 8. require 100% acceptance for the slice;
 9. require code and intermediate artifacts to be committed before continuing.
 
+## OpenSpec usage
+
+For non-trivial RD changes, use OpenSpec when the project already has `openspec/` or the user approves adding OpenSpec. Create or update `openspec/changes/<change-id>/proposal.md`, `design.md`, `tasks.md`, and `specs/**/spec.md` before implementation slices begin.
+
+OpenSpec artifacts are durable project specification files, not Peaks runtime swarm artifacts. They may live in the target repository root under `openspec/changes/...`. Swarm/runtime outputs such as task graphs, worker briefs, worker reports, reducer reports, scan reports, validation evidence, and compact handoffs must remain in the configured Peaks artifact workspace outside the target repository.
+
+Peaks PRD/RD/QA gates remain authoritative: OpenSpec structures the durable spec, while Peaks artifacts still carry role handoffs, coverage gates, QA evidence, swarm coordination, and execution state.
+
+## Frontend project generation
+
+When RD work creates a frontend application and the user has not specified a technology stack, and the current scan plus existing project standards still do not establish a frontend stack, default to React + Vite + shadcn/ui with:
+
+- `pnpm dlx shadcn@latest init --preset [CODE] --template vite`
+
+`[CODE]` is the preset code supplied by the shadcn registry or user workflow; if it is unknown, stop and resolve the intended preset before scaffolding.
+
+If the user specifies a frontend stack or scaffold command, use the specified technology. If the scaffold emits JavaScript, convert generated application files to TypeScript before continuing; if conversion is not practical, ask for a TypeScript-compatible scaffold.
+
+Application projects generated through this skill must not contain JavaScript source or config files. Generate TypeScript only (`.ts`, `.tsx`, and TypeScript config equivalents), including when adapting examples from libraries or templates.
+
+## 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 outside the target repository, not the repository root. If the artifact workspace is unknown, stop and resolve it before writing generated outputs. Use one session directory inside that workspace consistently so generated outputs stay grouped.
+
+When project-local `CLAUDE.md` or project-local `.claude/rules/**` is created or updated, route the mutation through `peaks standards init` or `peaks standards update`; do not hand-write standards mutations. Derive the content from the current scan results and existing project standards. Keep only the rules that match the project's languages, frameworks, tooling, and repository layout. Do not emit generic templates, copy-pasted boilerplate, or rules unrelated to the current scan evidence. Do not update user-global `~/.claude/rules/**` from this workflow.
+
+If the scan results are insufficient to justify a rule, leave it out or surface a review-only suggestion instead of writing it into project standards.
+
+## Compact handoff
+
+Before RD work stops, finishes, blocks, or hands off to another role, emit a short resumable capsule: mode, scope, coverage status, validated decisions, current slice, artifact paths, blockers, and next action. Link to scan reports, matrices, plans, and task graphs instead of restating them.
+
 ## External capability guidance
 
 Use `peaks capabilities --source access-repo --json` and `peaks capabilities --source mcp-server --json` as the source of truth before recommending external resources.
@@ -46,7 +94,7 @@ Use `peaks capabilities --source access-repo --json` and `peaks capabilities --s
 - Context7 can support current library/API documentation lookup when the map says it is available or the user authorizes MCP access.
 - SearchCode can support external code discovery only after confirming the query will not expose secrets or private code.
 - everything-claude-code, Claude Code Best Practice, mattpocock/skills, and andrej-karpathy-skills are RD guidance or review references; apply project-local conventions first.
-- OpenSpec can shape spec-first RD artifacts, but Peaks PRD/RD/QA gates remain authoritative.
+- OpenSpec should structure durable spec-first RD changes when available or approved, but Peaks PRD/RD/QA gates remain authoritative.
 - GitNexus remains a future proxied repository-intelligence boundary; do not install or run it directly.
 
 ## Boundaries

package/skills/peaks-sc/SKILL.md

@@ -19,6 +19,14 @@ Peaks SC records how product, RD, QA, code, and artifacts move together.
 
 Each refactor slice must leave a traceable commit boundary containing code changes and PRD/RD/QA/TXT intermediate artifacts.
 
+## GStack integration
+
+Use gstack as a concrete source-control and release workflow reference for the `Ship → Reflect` stages:
+
+- map `/ship` and `/land-and-deploy` concepts to Peaks commit boundaries, sync state, rollback points, and artifact retention;
+- map checkpoint discipline to traceable code-plus-artifact slices;
+- do not create PRs, merge, deploy, or mutate shared state unless the active Peaks workflow and user confirmation explicitly allow it.
+
 ## Project memory backup
 
 Project `.claude/memory` is the primary source for durable project memory. At approved checkpoints, use `peaks memory sync --project <path> --workspace <artifact-workspace> --apply` to back up the full project memory directory into the artifact repository workspace; do not treat the artifact backup as a second writable memory source.

package/skills/peaks-solo/SKILL.md

@@ -31,6 +31,28 @@ Peaks Solo must not silently:
 
 Use the Peaks CLI for runtime side effects.
 
+## GStack integration
+
+Use gstack as a concrete orchestration reference for the full `Think → Plan → Build → Review → Test → Ship → Reflect` loop:
+
+- map gstack role reviews to Peaks PRD, RD, UI, QA, SC, and TXT artifacts;
+- map `/autoplan`-style review pipelines to Peaks mode selection and role handoffs;
+- 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.
+
+## Mode selection
+
+When the user invokes Peaks Solo without explicitly selecting an execution profile, use `AskUserQuestion` before orchestration starts. Present the recommended full-auto path as the first/default option, and give every option a practical description so users can choose quickly.
+
+Offer these profiles unless the active command narrows the valid set:
+
+1. **Full auto (Recommended, Solo profile)** — Peaks handles planning, role coordination, validation, and compact handoff end-to-end while preserving required confirmation gates for risky or shared-state actions.
+2. **Assisted** — Peaks proposes plans, artifacts, and checks, then pauses for user decisions at major workflow boundaries.
+3. **Swarm** — Peaks maximizes safe parallel role/worker execution for larger RD or QA workloads while keeping reducer validation and artifact boundaries explicit.
+4. **Strict** — Peaks uses the most conservative gates: explicit confirmations, strict slice specs, coverage evidence, QA acceptance, and commit boundaries before continuing.
+
+If the user already names a profile, do not ask again unless the request crosses a risk boundary or the named profile conflicts with required Peaks gates.
+
 ## Project standards preflight
 
 Before orchestrating an end-to-end code repository workflow, gather the project standards preflight status from RD and QA by calling the Peaks CLI:
@@ -56,6 +78,12 @@ It must enforce the shared refactor red lines:
 6. require 100% acceptance for each slice;
 7. require code and intermediate artifacts to be committed before the next slice.
 
+## Completion handoff
+
+After a Peaks Solo workflow reaches final validation, refresh the project-local standards from the current scan-backed evidence before the handoff closes. Route project-local `CLAUDE.md` and project-local `.claude/rules/**` writes through `peaks standards init` or `peaks standards update`; do not hand-write standards mutations. If write authorization exists, apply an incremental merge of scan-backed changes into existing project-local standards. Preserve existing hand-maintained content unless the user explicitly confirms deletion or rewrite. If write authorization or the CLI path is unavailable, keep the standards output as the next action instead of writing it.
+
+Use Peaks TXT for the final, blocked, or interrupted handoff capsule. Keep that capsule compact: current mode, validated decisions, artifact paths, standards deltas, open questions, and next action. Do not restate the full workflow log when a short handoff plus artifact links will do.
+
 ## Optional capabilities
 
 When built-in guidance is insufficient, use capability discovery rather than reimplementing specialist workflows. Ask for user consent before token-heavy discovery unless the active profile permits it.

package/skills/peaks-txt/SKILL.md

@@ -18,6 +18,18 @@ Peaks TXT compresses workflow context into portable, role-specific artifacts.
 
 For refactors, create initial context before RD analysis and final context after validation and artifact retention.
 
+## Compaction-safe outputs
+
+When used alone or when a workflow needs portable artifacts that must survive session compaction, end with a short structured capsule: mode, validated decisions, artifact paths, standards deltas, open questions, and next action. Prefer links or paths over long narrative. Do not duplicate the full workflow log when a compact capsule is enough.
+
+## GStack integration
+
+Use gstack as a concrete context and reflection workflow reference for the `Reflect` stage:
+
+- map `/retro` summaries to Peaks lessons, discarded options, and staleness conditions;
+- map documentation-release ideas to compact downstream context for PRD, RD, QA, UI, and SC;
+- keep durable memory writes behind Peaks memory extraction and user-approved persistence.
+
 ## Project memory guidance
 
 When a skill artifact contains reusable project facts, decisions, rules, or constraints, mark only the stable extract with:

package/skills/peaks-ui/SKILL.md

@@ -19,6 +19,14 @@ Peaks UI handles experience, interaction, visual direction, and UI-specific refa
 
 Only engage when the refactor affects UI, interaction, styling, page structure, design system, or frontend user behavior.
 
+## GStack integration
+
+Use gstack as a concrete design-review workflow reference for the `Plan → Review → Test` UI stages:
+
+- map design review concepts to Peaks UX flow, page-state, interaction, and visual constraint artifacts;
+- 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.
+
 ## External capability guidance
 
 Use `peaks capabilities --json` before recommending design, browser, or UI reference resources.